# 旧 AI 助手（Kiro）参考

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