# 新 AI 助手（AgentServer）：文档导航

本目录是 ToolBox **新 AI 助手**的需求与设计。新助手基于 AgentServer（`~/web/AgentServer`，自托管的 Claude Code / Codex Agent 服务）：对话、事件、文件、审批、沙箱由 AgentServer 提供，ToolBox 负责入口、鉴权、会话归属，业务数据由新建的、无用户状态的 MCP 服务 fwh-agent-mcp 提供。

新助手与旧 Kiro 助手**相互独立**：新代码、新数据集合、新 MCP 服务，不修改、不复用旧助手；两者可并存，旧助手的下线另行决定。

当前状态：需求与设计初稿（2026-10-24），尚未编码。AgentServer 已支持第三方 MCP 服务（ADR-0021）；还需要一处通用的结果处理改动（agent-mcp 5.2）。

建议阅读顺序：requirements → technical-design → ui-design → agent-mcp。

## 文档职责

| 文档 | 内容 | 何时读取 |
| --- | --- | --- |
| [requirements.md](requirements.md) | 新助手的目标、功能与非功能需求、待确认事项 | 确定做什么、讨论验收范围时 |
| [technical-design.md](technical-design.md) | 总体架构、ToolBox 前后端新模块（会话归属与代理）、AgentServer 配置、技能、实施步骤与验收用例 | 实现 ToolBox 侧、排期时 |
| [ui-design.md](ui-design.md) | 独立页面的路由与菜单、三栏布局、欢迎页、交互细节、主题与代码结构 | 实现或评审前端页面时 |
| [agent-mcp.md](agent-mcp.md) | fwh-agent-mcp：定位、与旧 MCP 的区别、框架、工具清单、大数据处理、部署与接入、写工具规划 | 实现业务工具时 |
| [legacy-kiro-assistant.md](legacy-kiro-assistant.md) | 旧助手的实现、能力清单与问题 | 核对新助手要覆盖的能力时 |

AgentServer 自身的设计以其仓库 `docs/` 为准，重点参考：`docs/integration.md`、`docs/design/04-api.md`、`docs/design/08-platform-connectors.md`、`docs/adr/0021-third-party-mcp-via-gateway.md`、`docs/design/06-security.md`。

## 维护方式

范围变化更新 `requirements.md` 并关闭对应待确认条目；ToolBox 侧设计变化写入 `technical-design.md`，页面调整写入 `ui-design.md`，MCP 设计变化写入 `agent-mcp.md`；`legacy-kiro-assistant.md` 只描述旧助手，不随新代码更新。编码开始后另建 `implementation-status.md`。