新 AI 助手：需求

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

1. 目标与范围

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

业务能力覆盖旧助手的主要场景（legacy 第 4 节 C-01～C-11）；
Agent 运行、事件、文件、审批、沙箱都交给 AgentServer，ToolBox 只负责入口、鉴权、会话归属和业务数据工具；
业务数据工具是新建的、无用户状态的 MCP 服务；
与旧助手相互独立：不修改、不复用旧助手的代码、数据和 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）。
旧助手的顶栏入口保持不变，两者并存。
流式显示正文；思考过程单独折叠。
工具调用以卡片显示中文标题、参数摘要和状态（运行中 / 成功 / 失败 / 拒绝），可展开查看结果。
可中断当前运行；切换标签页、关闭标签页或刷新页面都不中断运行，回到会话后从断点继续显示。
运行中再次发送时提示“上一轮尚未结束”。

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 服务端与 fwh-agent-mcp 的 `config.agent-mcp.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 第 8 节。

requirements.md 5.9 KB Historia Raaka