# nu-deck **Repository Path**: lanhe-green/nu-deck ## Basic Information - **Project Name**: nu-deck - **Description**: Nu-Deck:融合了agent框架和前端页面 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 1 - **Created**: 2026-07-25 - **Last Updated**: 2026-08-01 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Nu-Deck > **Nu-Deck** 是一个 AI 编程助手工作台（浏览器模式），融合三个开源项目的精华： > - **[nu-duo](https://github.com/badlogic/pi-mono)** — 轻量级 AI Agent 引擎（Python），多 Provider LLM 流式、Agent 循环、7 文件工具 > - **[PiDeck](https://github.com/ayuayue/PiDeck)** — 高质量 React AI 桌面工作台，Chat UI、Monaco 编辑器、xterm 终端 > - **my_agent_framework** — RAG 知识库（ChromaDB + BM25 混合检索）、MCP 协议、对话压缩 --- ## 架构 ``` ┌────────────────────────────────────────────────────────────┐ │ Nu-Deck 架构 │ ├────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────────────────────────────────────────┐ │ │ │ Frontend (React SPA · Vite 7 · 75+ 组件) │ │ │ │ ┌──────────┬──────────┬──────────┬───────────┐ │ │ │ │ │ Chat │ Drawer │ Modals │ Config │ │ │ │ │ │ Panel │ ────── │ ────── │ ────── │ │ │ │ │ │ ├Header │ Browser │ MenuHost│ 16 Tabs │ │ │ │ │ │ ├MsgList│ Diff │ Settings│ │ │ │ │ │ │ ├Composer│ Git │ Import │ │ │ │ │ │ │ └Timeline│ Files │ Picker │ │ │ │ │ │ ├──────────┴──────────┴──────────┴───────────┤ │ │ │ │ │ Layout: Sidebar · TerminalDock · 49 CSS │ │ │ │ │ └─────────────────────────────────────────────┘ │ │ │ └──────────────────┬────────────────────────────────┘ │ │ │ HTTP/SSE/WebSocket │ │ ┌──────────────────▼────────────────────────────────┐ │ │ │ Backend (FastAPI + Uvicorn) │ │ │ │ │ │ │ │ ┌────────────┬────────────┬───────────────────┐ │ │ │ │ │ AI Engine │ Agent Core │ 7 Tools │ │ │ │ │ │ (base_prov.│ (Agent Loop)│ (read/write/ │ │ │ │ │ │ + 8 impl.)│ │ edit/bash/ │ │ │ │ │ │ │ │ ls/find/grep) │ │ │ │ │ ├────────────┴────────────┴───────────────────┤ │ │ │ │ │ RAG: ChromaDB + BM25 + 语义分块 + 查询扩展 │ │ │ │ │ │ MCP: 协议客户端 + 工具适配器 │ │ │ │ │ │ Storage: SQLite (会话/设置/密钥/元数据) │ │ │ │ │ └──────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────┘ │ └────────────────────────────────────────────────────────────┘ ``` --- ## 功能 | 功能 | 说明 | 来源 | |------|------|------| | **AI 对话** | SSE 流式 + Agent 循环，thinking/reasoning 实时展示 | nu-duo | | **工具集** | read / write / edit / bash / ls / find / grep + RAG 10 工具 + 日报工具 | nu-duo | | **多 Provider** | OpenAI / Anthropic / Google / Mistral / Bedrock / Azure / 通用 | nu-duo → BaseProvider | | **运行时切换模型/思考级别** | 无需重启，UI 直接接后端 `model`/`thinking` 端点 | Nu-Deck | | **RAG 知识库** | 多分类 / 多集合管理（rag-core：ChromaDB + BM25 混合检索 + CategoryRegistry + DocumentRegistry） | rag-core | | **知识库管理页** | 侧边栏直达入口：集合切换、分类 CRUD、按分类上传/搜索/删除 | Nu-Deck | | **MCP 协议** | 连接外部 MCP 服务器，扩展工具集 | my_agent_framework | | **对话压缩** | 长对话自动摘要压缩，节省 Token | Nu-Deck | | **扩展系统** | 支持运行时加载扩展，注册自定义工具 | Nu-Deck | | **项目管理** | 多项目组织，会话树形管理 | PiDeck | | **代码编辑** | Monaco Editor，差异对比 | PiDeck | | **终端** | xterm.js WebSocket 终端 | PiDeck | | **RichInput** | contentEditable 输入，支持 @文件 /command /&会话 | PiDeck | | **国际化** | 中英文完整支持 | PiDeck | | **亮/暗主题** | 5 种背景色预设 + 三轴字号独立控制 | PiDeck | --- ## 快速开始 ### 源码运行 ```bash # 1. 后端 cd backend python -m venv .venv .venv\Scripts\activate # Windows source .venv/bin/activate # Linux/Mac pip install -r requirements.txt # 安装子模块 pip install -e vendor/nu_ai pip install -e vendor/nu_agent_core pip install -e vendor/nu_coding_agent pip install -e vendor/nu_web_ui cp .env.example .env # 编辑填入 API Key python server.py --port 8080 # 2. 前端（新终端） cd frontend npm install npx vite --host 127.0.0.1 --port 5173 ``` 打开浏览器访问 **http://localhost:5173**。 > 后端默认端口 8080，Vite 自动代理 `/api` 请求到后端。 --- ## 项目结构 ``` agent-myself/ ├── Dockerfile # 容器部署 ├── backend/ # Python 后端 │ ├── server.py # FastAPI 主入口 │ ├── server_pyi.py # PyInstaller 打包入口 │ ├── _server/ │ │ ├── routes/ # API 路由（自动发现） │ │ │ ├── agents.py # Agent + 工具 + SSE（thinking 转发） │ │ │ ├── kb.py # 知识库 API（多分类/多集合，rag-core） │ │ │ ├── terminal.py # WebSocket PTY 终端 │ │ │ ├── projects.py # 项目管理 │ │ │ ├── sessions.py # 会话管理 + 压缩 │ │ │ ├── files.py # 文件浏览/读写 │ │ │ ├── settings.py # 设置 + 模型切换 │ │ │ ├── mcp.py # MCP 服务器管理 │ │ │ └── health.py # 健康检查 │ │ ├── shared.py / store.py # 配置/存储 │ │ ├── ai_config.py # AI 模型配置（环境变量/.env） │ │ ├── compaction.py # 对话压缩 │ │ └── extensions.py # 扩展系统 │ └── vendor/ # 自包含依赖（src 布局子包自动加入 sys.path） │ ├── nu_ai/ # 多 Provider LLM 引擎 │ ├── nu_agent_core/ # Agent 循环 + AgentTool（含 label） │ ├── nu_coding_agent/ # 内置工具 + RAG 工具（rag.py） │ ├── rag-core/ # 知识库：KnowledgeBase/CategoryRegistry/DocumentRegistry │ ├── nu_web_ui/ # SQLite 存储层 │ └── daily_report_core/ # 日报工具 ├── frontend/ # React SPA │ ├── src/ │ │ ├── App.tsx # 应用骨架 │ │ ├── main.tsx # 入口 + setupBrowserApi │ │ ├── browserApi.ts # 浏览器 API 桥（替代 Electron IPC） │ │ ├── _custom/SettingsPage.tsx # 运行时模型设置 + 知识库 tab │ │ ├── components/ │ │ │ ├── layout/ # Sidebar（含知识库直达按钮） │ │ │ ├── chat/ # ChatPanel, Composer, MessageList... │ │ │ ├── knowledge/ # KnowledgeBasePage（分类/集合管理） │ │ │ ├── modals/ # ModalHost, MenuHost, SettingsHost... │ │ │ └── app/ # TurnRow, Pickers, Dialogs... │ │ ├── styles/ # 按域拆分 CSS │ │ └── utils/ # appUtils 等 │ ├── index.html / vite.config.ts / package.json ├── start.bat / start.sh ├── build_exe.bat # PyInstaller 打包 └── README.md ``` --- ## 前端组件树 ``` App.tsx (6,894 行) ├── Sidebar 项目列表 + 会话搜索 + Agent 管理 ├── ChatPanel │ ├── ChatHeader 标题 + 模型选择 + 操作按钮 │ ├── MessageList TurnRow + UserBubble + 骨架屏 │ ├── Composer RichInput + 图片预览 + 工具栏 │ │ ├── ImagePreviewBar 图片附件 │ │ ├── ExtensionWidgets 扩展组件 │ │ ├── SuggestionPopup @命令/@文件 自动补全 │ │ └── ComposerToolbar 模式/附件/发送按钮 │ ├── QueuePrompt 排队提示 │ ├── Timeline 对话大纲 │ └── TerminalArea 终端坞 ├── DrawerSection 右侧抽屉 │ ├── BrowserPanel iframe 浏览器 │ ├── FileDiffViewer Monaco 差异对比 │ ├── GitPanel 分支/提交/历史 │ └── DrawerContent 文件树/会话管理 └── ModalHost 所有弹窗 ├── MenuHost 右键菜单 ├── SettingsHost 设置/更新/环境 ├── ImportHost 会话导入 ├── PickerHost 模型/思考/模式选择 └── OverlayHost 覆盖层/ScratchPad ``` --- ## AI Provider 架构 ``` base_provider.py (抽象基类) ├── stream() / stream_simple() ← 公共入口 + 后台任务管理 ├── _run_stream() ← 错误处理包装 ├── _run_stream_inner() ← 默认流程: client → params → stream ├── _empty_usage() / _new_output() ← 工具函数 │ ├── AnthropicProvider (anthropic.py) ├── OpenAICompletionsProvider (openai_completions.py) ├── OpenAIResponsesProvider (openai_responses.py) ├── GoogleProvider (google.py) ├── GoogleVertexProvider (google_vertex.py) ├── GoogleGeminiCliProvider (google_gemini_cli.py) ├── BedrockProvider (amazon_bedrock.py) └── MistralProvider (mistral.py) ``` --- ## API 概览 | 端点 | 说明 | |------|------| | `GET /api/health` | 健康检查 | | `GET /api/settings` | 获取设置 | | `GET /api/settings/model` | 获取当前模型 | | `POST /api/settings/model` | 切换模型 | | `GET /api/projects` | 项目列表 | | `POST /api/agents` | 创建 Agent | | `GET /api/agents/:id/runtime` | Agent 运行时状态 | | `POST /api/agents/:id/prompt` | SSE 流式对话（thinking_start/delta/end、tool、message、error、assistant_end） | | `POST /api/agents/:id/stop` | 停止当前流式任务（abort，不删 Agent） | | `POST /api/agents/:id/model` / `:id/thinking` | 运行时切换模型 / 思考级别 | | `GET /api/agents/:id/history` | 对话历史 | | `GET /api/sessions` | 会话列表 | | `DELETE /api/sessions/:id` | 删除会话 | | `GET /api/sessions/:id/export-html` | 导出会话 HTML | | `GET /api/files?path=` | 文件浏览 | | `GET /api/v1/kb/collections` | 知识库集合枚举 | | `GET/POST/DELETE /api/v1/kb/categories` | 知识库分类管理 | | `GET /api/v1/kb/docs` | 文档列表（按集合/分类过滤） | | `POST /api/v1/kb/upload` / `ingest-text` | 上传文件 / 录入文本 | | `POST /api/v1/kb/search` | 混合检索（按集合/分类过滤） | | `DELETE /api/v1/kb/docs` · `POST /api/v1/kb/clear` | 删除文档 / 清空集合 | | `WS /api/terminal` | 终端 WebSocket | --- ## 技术栈 | 层 | 技术 | |---|---| | **AI 引擎** | BaseProvider + 8 子类实现 | | **后端框架** | FastAPI + Uvicorn | | **存储** | SQLite + ChromaDB | | **前端框架** | React 19 + TypeScript | | **构建工具** | Vite 7 | | **代码编辑器** | Monaco Editor (lazy load) | | **终端** | xterm.js + ConPTY WebSocket | | **流式通信** | SSE + WebSocket 双通道 | | **测试** | Playwright (E2E) | --- ## 开发 ```bash # 后端热重载 cd backend && python server.py --reload # 前端热更新 cd frontend && npx vite # 打包 exe build_exe.bat # 打包 Docker docker build -t nu-deck . ``` --- ## 已知限制（浏览器模式） 本项目以**浏览器模式**运行（`main.tsx` 用 `setupBrowserApi()` 挂载 `window.piDesktop`，无 Electron 主进程）。以下功能为占位或受限： - **Git 面板**：`browserApi` 中 `git.*` 为占位实现，抽屉打开后为空（后端未提供 Git 端点） - **导入会话**（Codex/Claude/OpenCode）：菜单项已置灰（后端无对应端点） - **项目资源**（技能/扩展/提示词）、**Worktree**：菜单项已置灰 - **Agent 重命名/复制会话**：右键菜单已置灰（后端无端点）；**导出 HTML** 可用（浏览器下载） - **附件选择**：浏览器文件选择器，插入 `@文件名` 引用（无本地路径概念） - **配置弹窗（ConfigModal）**：已整体删除（入口与其 `config/` 占位 tab 于 2026-08-01 清理，见 `docs/frontend-audit-report.md`） - **pi 环境监测**：已移除（EnvironmentDialog 组件与设置页/启动检测均删除；Nu-Deck 一体化部署不依赖 pi CLI） --- ## License MIT