FranklinWH-Toolbox/docs/ai-assistant-agentserver/legacy-kiro-assistant.md

旧 AI 助手（Kiro）参考

状态：2026-10-23 梳理，基于 master a10cbda。新 AI 助手与旧助手相互独立，不修改、不复用旧助手的代码和 MCP；本文只用于核对新助手需要覆盖的能力（第 4 节）和需要避免的问题（第 5 节）。新助手的需求见 requirements.md。

1. 架构概览

浏览器（顶栏 AiChat 抽屉，自写聊天 UI）
  │ POST /ai/chat（SSE）、/ai/sessions/*、/ai/permission、/ai/files/*
  ▼
ToolBox Go 后端（Fiber）
  ACPManager：每个用户一个 kiro-cli 子进程（降权到 KIRO_RUN_AS_USER）
  │ JSON-RPC over stdio（ACP 协议 + _kiro.dev/* 扩展）
  ▼
kiro-cli acp --agent fwh-toolbox-agent
  ├─ 内置工具：read / write / grep / glob / code / shell(白名单) / web_* / knowledge / subagent …
  ├─ knowledgeBase：FranklinWH-Wiki 文档（语义索引）
  ├─ skills / steering：deploy/kiro/
  └─ MCP（stdio）：fwh-tools（./fwh-mcp-server，222 个工具）、drawio、officecli、markitdown
                    │
                    └─ PostgreSQL / MongoDB / Redis / FWH 云平台 API / Plane / SIM 平台 / MinIO

2. 代码入口

层	位置	现状
前端入口	src/layout/header/Actions/AiChat/index.vue	顶栏按钮 + 可拖拽宽度的 NDrawer
前端面板	ChatPanel.vue、MessageItem.vue	自写消息列表、工具标签、权限卡片、文件下载按钮、会话列表
前端逻辑	useAiChat.ts（916 行）	手写 SSE 解析；$$FILE_DOWNLOAD$$ 标记解析为下载片段；剥离 [context] 前缀
前端缓存	chatDB.ts	IndexedDB 缓存会话消息（服务端只有 Kiro 回放，没有完整事件流）
前端 API	src/service/aiChat/index.ts	13 个接口（见第 3 节）
路由/控制器	service/routes/aiChatRoutes.go、service/controllers/aiChatControllers.go	SSE 输出、文件上传下载（MinIO）
会话管理	service/services/aiChatServices.go	内存 map（userId → 会话 + 子进程）、Redis 活跃会话与历史列表（上限 50）、Mongo 会话记录
ACP 客户端	service/utils/acp/acp.go（1569 行）	进程管理、JSON-RPC、session/update 映射、反向请求（readTextFile/writeTextFile 走 MinIO，权限请求转前端，10 分钟超时拒绝）
文件存储	service/utils/filestore/、service/utils/agentfiles/	MinIO upload/、download/ 前缀按 userId/sessionId 隔离；/tmp/fwh-toolbox-agent 定时清理
MCP Server	service/cmd/mcp/（设计见 DESIGN.md）	stdio；PII 脱敏、大结果落盘到 /tmp/fwh-toolbox-agent/results、调用日志
Agent 配置	deploy/kiro/agents/fwh-toolbox-agent.json	工具白名单、shell 正则白名单、读写路径、MCP 定义
技能/引导	deploy/kiro/skills/fwh-toolbox-{rules,workflow}/、deploy/kiro/steering/*.md	操作路由表、数据防护规则、TOU/Plane/直连查询参考、PPT/Python/文件输出规范
部署	deploy/scripts/{install_kiro_cli,deploy_kiro_cli,sync_kiro_config}.sh	安装 kiro-cli、同步配置并替换 __WIKI_DOCS__ 等占位符
配置	service/.env：KIRO_RUN_AS_USER、KIRO_HOME、KIRO_DEBUG_LOG	service/main.go 调用 controllers.InitAIChat

3. 后端接口

接口	用途
POST /ai/chat	发消息，SSE 返回 session_info、welcome、text、tool_call、tool_update、permission、metadata、done、error
GET /ai/sessions/list、GET /ai/sessions/current	会话列表；当前会话的 agent / model / 上下文用量
POST /ai/sessions/new、POST /ai/sessions/:id、GET /ai/sessions/:id/load	新建；切换（重启子进程并 session/load）；SSE 推送回放消息
PATCH、DELETE /ai/sessions/:id	改标题；删除（超过 50 条时调用 kiro-cli chat --delete-session）
POST /ai/cancel、POST /ai/permission	取消本轮；回复权限请求
POST /ai/files/upload、GET /ai/files/download、GET /ai/files/list	上传（≤2MB，文本）、下载、列出 MinIO 中的上传/产出文件

4. 现有能力清单

新助手需要覆盖的能力（编号供 requirements 引用）：

编号	能力	实现方式
C-01	流式对话、思考过程	ACP agent_message_chunk / agent_thought_chunk（思考与正文混在同一文本流）
C-02	工具调用展示	tool_call / tool_call_update，acp.DescribeTool 生成中文简述
C-03	业务数据查询与操作	fwh-tools MCP：站点、告警、停机、功率流、录波、MQTT/EMS 日志、TOU 模版、SIM、Plane、Mongo/PG/Redis 直查、批量下载、站点分析、自动升级配置等
C-04	产品知识问答	Kiro knowledgeBase 索引 FranklinWH-Wiki Markdown
C-05	文件上传分析	上传到 MinIO，Agent 经 readTextFile 反向请求读取；仅文本、≤2MB
C-06	报告/文档生成	Python（fwh-pyrun）、officecli、drawio MCP 生成到 /tmp/fwh-toolbox-agent，再经 MCP 上传 MinIO；回复中输出 $$FILE_DOWNLOAD$$ 标记供前端渲染下载按钮
C-07	写操作审批	Kiro 权限请求 → 前端卡片 → /ai/permission
C-08	会话管理	新建、切换、回放、改标题、删除；按 ToolBox 登录用户隔离
C-09	取消	/ai/cancel → ACP session/cancel；连接断开时也取消
C-10	提交反馈	MCP service_feedback_create → Plane Intake
C-11	数据防护	MCP 侧 PII 脱敏、大结果落盘；steering 禁止把大批量数据读进上下文

5. 问题清单

编号	问题
P-01	维护成本高：ACP 客户端、Kiro 扩展通知、会话恢复、回放、进程降权都由 ToolBox 自己维护，Kiro 协议或版本变化需要跟着改（acp.go 1569 行 + useAiChat.ts 916 行）。
P-02	资源模型：每个在线用户常驻一个 kiro-cli 子进程，切换会话要重启进程；没有全局并发上限和排队。
P-03	身份靠提示词传递：[context] userId=…, sessionId=… 拼在用户消息前，MCP 工具的 userId/sessionId 由模型自己填写，可被省略或伪造；前端还要剥离这段前缀。
P-04	写操作审批不完整：allowedTools 中 @fwh-tools 整体自动信任，service_tou_template_save、service_auto_update_delete_*、service_site_info_update_status 等写工具调用时没有人工确认。
P-05	事件不完整、不可续传：服务端只有 Kiro 的回放文本，工具调用、权限记录不落库；前端用 IndexedDB 补；SSE 断开即丢失本轮输出。
P-06	文件链路绕：产出文件靠模型在回复里输出 $$FILE_DOWNLOAD$$ 标记，漏写或写错就没有下载入口；上传只支持 2MB 文本，不支持截图、Excel、PDF。
P-07	沙箱弱：隔离依赖 Kiro 的工具白名单和 shell 正则，没有 OS 级沙箱；read 允许 ./**（服务目录，含 .env）。
P-08	可观测性弱：没有按会话的用量统计、审计日志和管理后台，调试依赖 KIRO_DEBUG_LOG 打开 kiro-chat.log。