基于 DeepSeek 的多 Agent 协作 AI 编程助手 — 桌面端 + 服务端 + Web 客户端全栈项目
iotaCode 是一款面向软件工程场景的 Multi-Agent 协作式 AI 编程助手。它围绕一个"主 Agent"调度三个"子 Agent"（技术侦查员、开发工程师、技术研究员）协同工作，内置代码编辑、文件系统、MCP 协议集成等 13+ 工具，支持流式对话、对话上下文图谱、工作区隔离等特性。
iotaCode/
├── client/ # React + Fluent UI 前端（Vite 构建）
│ ├── src/ # 组件、页面、状态管理
│ └── dist/ # 构建产物（被 server 作为 SPA 静态文件服务）
├── desktop/ # Tauri 桌面壳（Rust + Tauri v2）
│ └── src-tauri/ # Tauri Rust 后端
├── server/ # Node.js 后端（核心）
│ ├── src/
│ │ ├── index.ts # 入口
│ │ ├── app.ts # Hono 应用（路由 + CORS + 静态文件）
│ │ ├── types.ts # 类型定义
│ │ ├── agent/ # 🧠 Agent 核心系统
│ │ │ ├── index.ts # 主 Agent 循环（streamText）
│ │ │ ├── compress.ts # 对话压缩执行引擎（/compact）
│ │ │ ├── prompt-builder.ts # 模块化 Prompt 组装器
│ │ │ ├── subagent-runner.ts # 子 Agent 运行器
│ │ │ ├── prompts/ # .prompt.md 系统提示词模块
│ │ │ ├── subagents/ # 子 Agent 身份提示词
│ │ │ └── tools/ # 内置工具实现
│ │ │ └── compress/ # 压缩专用工具（save_topic）
│ │ ├── routes/ # 8 个 API 路由
│ │ ├── db/ # SQLite 数据库层
│ │ ├── lib/ # 工具库（env/token计数/端口）
│ │ └── mcp/ # MCP 协议集成（JSON-RPC over stdio）
│ ├── mcp.json # MCP Server 注册配置
│ └── .env # DeepSeek API Key 配置
├── examples/ # 示例代码
└── README.md # ← 你在这里
| 层级 | 技术 | 版本 |
|---|---|---|
| AI 模型 | DeepSeek (via @ai-sdk/deepseek) |
— |
| AI SDK | Vercel AI SDK (ai) |
^7.0.11 |
| Web 框架 | Hono | ^4.9.0 |
| 运行时 | Node.js | 22+ |
| 语言 | TypeScript | ~6.0 |
| 数据库 | SQLite（node:sqlite 内置） |
— |
| 前端 | React 19 + Fluent UI 9 + Vite 8 | — |
| 桌面 | Tauri v2 + Rust | — |
| MCP 协议 | 纯 Node.js 自实现（JSON-RPC 2.0） | — |
iotaCode 采用 Swarm 架构，一个主 Agent 负责与用户交互、理解需求，并按需派发三个专用子 Agent 并行工作：
┌──────────────┐
│ 用户 │
└──────┬───────┘
│
┌──────▼───────┐
│ 主 Agent │ ← 13 个内置工具
│ (iota) │ + N 个 MCP 工具
└──┬───────┬───┘
│ │
┌─────────▼──┐ ┌──▼──────────┐
│ 技术侦查员 │ │ 开发工程师 │
│ (explore) │ │ (code) │
│ 只读·代码搜索│ │ 读写·编码实现│
└─────────────┘ └─────────────┘
┌──────────────┐
│ 技术研究员 │
│ (research) │
│ 只读·文档调研 │
└──────────────┘
系统提示词拆分为 8 个独立 .prompt.md 模板文件，通过 PromptBuilder 按需组装：
identity— 角色身份system— 系统行为规则tasks— 任务执行指南tools— 工具使用说明caution— 谨慎操作清单code-style— 代码风格约束tone— 语气与风格env— 环境信息
子 Agent 按角色组合不同区块，支持 {placeholder} 变量替换。
点击"压缩对话"按钮即可触发 /compact 命令，由 deepseek-v4-flash 自动识别话题边界并生成摘要。压缩后主 Agent 只看到话题摘要（注入系统提示），需通过 retrieve_topic 工具按需查阅完整历史。支持增量压缩——每次只压缩上次压缩之后的新消息。
纯 Node.js 实现的轻量化 MCP 客户端（零外部 MCP SDK），通过 child_process.spawn 管理多个 MCP Server 的 stdio 连接，遵循 JSON-RPC 2.0 协议，支持自动将 MCP 工具注册为 AI SDK 工具。
| 方法 | 路径 | 描述 |
|---|---|---|
| POST | /api/chat |
流式聊天（SSE） |
| GET | /api/sessions |
获取会话列表 |
| POST | /api/sessions |
创建会话 |
| DELETE | /api/sessions/:id |
删除会话 |
| GET | /api/workspace |
获取/设置工作区 |
| POST | /api/workspace |
切换工作区 |
| GET | /api/fs/* |
文件浏览器 |
| GET | /api/mcp |
MCP 服务器状态 |
| POST | /api/mcp/:name/toggle |
启用/禁用 MCP 服务器 |
| GET | /api/skills |
获取 Agent Skills 元数据 |
| GET | /api/models |
获取可用模型列表 |
| GET | /api/context-usage |
对话上下文使用情况 |
| GET | /api/health |
健康检查 |
- Node.js 22+
- pnpm（推荐）或 npm
- DeepSeek API Key（platform.deepseek.com）
cd server
# 安装依赖
pnpm install
# 配置 API Key
# 编辑 .env，填入 DEEPSEEK_API_KEY
# 启动开发服务器（tsx watch 热重载）
pnpm devcd client
pnpm install
pnpm dev # Vite 开发服务器cd desktop
pnpm install
pnpm tauri dev # Tauri 开发模式| 决策 | 选择 | 理由 |
|---|---|---|
| Multi-Agent 架构 | Swarm（主 Agent + 子 Agent） | 任务分层，专业分工，可并行 |
| Agent 工具 | 自实现 13 个工具 | 精确控制行为，不走第三方 SDK 抽象 |
| 提示词系统 | 模块化 .prompt.md 文件 |
关注点分离，复用组合，易于调试 |
| 对话压缩 | AI 手动触发 + retrieve_topic 工具 | 用户主动控制，Agent 按需查阅，避免上下文膨胀 |
| 数据库 | SQLite（node:sqlite） |
零配置、单文件、工作区级隔离 |
| MCP 集成 | 纯 Node.js JSON-RPC | 避免外部 SDK 依赖，轻量化 |
| 前端 UI | React 19 + Fluent UI 9 | 微软设计语言，适合 IDE 风格工具 |
| 桌面壳 | Tauri v2 (Rust) | 相比 Electron 更轻量、更安全 |
MIT