# 新 AI 助手：需求

> 状态：需求初稿，2026-10-24（取代 10-23 的“迁移”版本：新助手与旧 Kiro 助手相互独立，业务工具改用无用户状态的新 MCP）。实现方式见 [technical-design.md](technical-design.md) 与 [agent-mcp.md](agent-mcp.md)；旧助手的能力与问题见 [legacy-kiro-assistant.md](legacy-kiro-assistant.md)。

## 1. 目标与范围

在 ToolBox 中新建一个基于 AgentServer 的 AI 助手：

1. 业务能力覆盖旧助手的主要场景（legacy 第 4 节 C-01～C-11）；
2. Agent 运行、事件、文件、审批、沙箱都交给 AgentServer，ToolBox 只负责入口、鉴权、会话归属和业务数据工具；
3. 业务数据工具是新建的、无用户状态的 MCP 服务；
4. 与旧助手相互独立：不修改、不复用旧助手的代码、数据和 MCP，两者可以同时使用，旧助手的下线另行决定。

**范围内**：ToolBox 新前端模块与后端模块、新 MCP 服务 fwh-agent-mcp、AgentServer 上的 Profile / 技能 / 资料库 / MCP 服务配置，以及 AgentServer 结果处理的一处通用改动（agent-mcp 5.2）。

**范围外**：

- 旧助手的任何改动和数据迁移（Kiro 会话不迁移）；
- 模型凭证（ToolBox 只作为 AgentServer API 的调用方）；
- 一期不做写操作工具（agent-mcp 第 7 节）；
- Codex 引擎（引擎固定 Claude，由 Profile 决定）。

## 2. 功能需求

### FR-01 页面与对话

- 新助手以独立的大页面展示：左侧菜单新增“AI 助手”，不放在顶栏右上角；页面布局为会话栏、对话区、文件栏（[ui-design.md](ui-design.md)）。
- 旧助手的顶栏入口保持不变，两者并存。
- 流式显示正文；思考过程单独折叠。
- 工具调用以卡片显示中文标题、参数摘要和状态（运行中 / 成功 / 失败 / 拒绝），可展开查看结果。
- 可中断当前运行；切换标签页、关闭标签页或刷新页面都不中断运行，回到会话后从断点继续显示。
- 运行中再次发送时提示“上一轮尚未结束”。

### FR-02 会话

- 会话按 ToolBox 登录用户隔离：只能看到、打开、改名、删除自己的会话。
- 新建、切换、改名、删除；按最近活跃排序；首条消息自动生成标题（前 30 字）。
- 打开历史会话显示完整时间线（文本、工具调用、审批、文件卡片），不依赖浏览器缓存。
- ToolBox 或 AgentServer 重启后，历史会话可继续对话。

### FR-03 使用权限

- 可配置哪些角色能使用新助手（默认所有登录用户）。
- 可按角色使用不同的 Profile（不同的工具范围、技能），在会话创建时确定。

### FR-04 业务数据查询

- Agent 通过 fwh-agent-mcp 查询站点、告警、停机、功率流、日志、故障录波、TOU 模版、SIM 卡、EMS 参数、Plane 工作项等数据（工具清单见 agent-mcp 第 4 节）。
- 工具不区分使用者；查询类工具无需审批，直接调用。
- 单次返回结果紧凑，超过上限时明确标注截断并提示缩小范围。
- 需要大量明细时，数据以文件形式进入会话工作区，由 Agent 用 Python 分析，不进入模型上下文。
- 保留个人信息脱敏。

### FR-05 知识库问答

- 检索 FranklinWH-Wiki 产品文档和 `docs/knowledge` 数据知识库；Wiki 更新后同步（频率见 Q-04）。
- 回答引用资料时给出文档路径或标题。

### FR-06 文件上传与产出

- 点击、拖拽、粘贴截图上传；支持截图、CSV、Excel、PDF、Word、PPT、JSON、日志文本；单文件上限按 AgentServer 设置（默认 50MB）。
- Agent 产出的文件自动显示为文件卡片，可下载；文件栏汇总本会话的上传与产出文件，图片、PDF、Markdown、CSV 可预览。
- 报告、PPT 遵循公司规范与模版（技能 `fwh-assistant`）。

### FR-07 审批与提问

- 需要审批的操作弹出卡片：允许一次 / 本会话允许 / 拒绝（可填原因）。
- Agent 主动提问以选择卡片回答。
- 超时（默认 10 分钟）按拒绝处理。

### FR-08 运行状态

- 显示当前模型，可在 Profile 允许的范围内切换。
- 显示本轮用量；排队时显示位置。

## 3. 非功能需求

| 编号 | 要求 |
| --- | --- |
| NF-01 隔离 | 用户不能读取或操作他人的会话、运行、审批和文件。由 ToolBox 后端实现：浏览器只持有 ToolBox 登录令牌，AgentServer API Key 只在后端 |
| NF-02 安全 | Agent 只能写自己的会话工作区，读不到 ToolBox 源码、`.env` 和服务器凭证；业务凭证只在 fwh-agent-mcp 内；MCP 访问令牌只在 AgentServer 服务端与 ToolBox `.env` |
| NF-03 追溯 | 每次工具调用可追溯到 ToolBox 用户：ToolBox 会话归属 → AgentServer 审计（gateway_call 含参数） |
| NF-04 并发 | 多用户同时使用时排队而非失败；fwh-agent-mcp 有自己的并发上限，保护业务系统 |
| NF-05 性能 | 单个查询工具 60 秒内返回（导出 300 秒）；超时给出明确错误 |
| NF-06 独立 | 新模块上线、下线不影响旧助手；新代码不引用旧助手的包 |

## 4. 待确认事项

| 编号 | 问题 | 建议 |
| --- | --- | --- |
| Q-01 | AgentServer 与 ToolBox 是否同机部署 | 同机时 fwh-agent-mcp 监听 127.0.0.1；跨机时监听内网地址并限制来源 |
| Q-02 | 新助手对哪些角色开放、是否需要按角色区分 Profile | 先对所有登录用户开放同一个只读 Profile |
| Q-03 | 每用户会话数量上限与保留期 | 50 条；更早的会话在 AgentServer 侧归档 |
| Q-04 | Wiki 知识库同步频率 | 已定：复制到 `/srv/agent-server/knowledge/`，需要时手动运行同步脚本，不配置定时任务 |
| Q-05 | 旧助手何时下线 | 新助手验收后观察一段时间再定 |
| Q-06 | drawio 图表能力是否需要 | 先不做，按反馈决定 |

MCP 相关的待确认事项见 [agent-mcp.md](agent-mcp.md) 第 8 节。