From c21582eb7fe52cefc1f8084c37f75f00cc1dbcc5 Mon Sep 17 00:00:00 2001 From: wangheng Date: Thu, 24 Sep 2026 16:52:07 +0800 Subject: [PATCH] =?UTF-8?q?docs(agent):=20=E6=B2=89=E6=B7=80=E6=96=B0=20MC?= =?UTF-8?q?P=20=E5=B7=A5=E5=85=B7=E4=B8=8A=E7=BA=BF=E6=A0=87=E5=87=86?= =?UTF-8?q?=E6=B5=81=E7=A8=8B=EF=BC=88=E8=AE=BE=E8=AE=A1=E8=AF=84=E5=AE=A1?= =?UTF-8?q?=E2=86=92=E5=AE=9E=E7=8E=B0=E2=86=92=E9=83=A8=E7=BD=B2=E2=86=92?= =?UTF-8?q?=E5=BB=BA=E9=9C=80=E6=B1=82=E2=86=92submit=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- xiaoqu-agent-service/AGENTS.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/xiaoqu-agent-service/AGENTS.md b/xiaoqu-agent-service/AGENTS.md index 33ad835..59982d5 100644 --- a/xiaoqu-agent-service/AGENTS.md +++ b/xiaoqu-agent-service/AGENTS.md @@ -31,3 +31,30 @@ - **部署前必须先把 main 推 origin**：出现过本地 main 领先 origin 1 个修复提交、他人从 origin 构建部署导致生产跑到旧代码的情况（2026-09-22 paperuselog terms 结构 400）。 - 新工具上线后必须幂等绑 prod scope（svc 库 MySQL，tool 表唯一标识列是 `name`；scope 表是 `agent_scope`）：hardware/district 系列惯例绑 scope 1(test)/2(operation)/3(xiaoqu-ai)/5(ops-query)，工单/仓库系列只绑 scope 1。 - prod AK 的 Authorization 头值本身已含 "Bearer " 前缀，不要再拼。 + +## 新 MCP 工具上线标准流程（2026-09-24 沉淀，经 REQ-20260924-0003/0009 两轮验证） + +按顺序执行，每步完成再进下一步： + +1. **设计评审**：先调研老系统接口（xiaoqu-franchisee 控制器行号级依据），写设计文档到 `doc/<工具名>-mcp-tool-design.md`， + 含背景/老接口行为与坑/决策表（给出建议与备选）/参数契约/返回契约/与老系统差异/测试要点。 + **先给用户评审，拍板后再动工**；拍板结论回写文档（含追加决策）。 +2. **实现**：实体/Mapper/（ES Gateway）/Tool 类，遵循现有同类工具模式；枚举配 `*Text` 中文文案； + Redis 字典缺失 fail fast；老系统明显 bug（NPE、错位、吞异常）不复制，在文档差异节注明。 + 注意两个已踩过的坑：**项目未注册 MyBatis-Plus 分页拦截器，分页必须 selectCount+LIMIT 物理分页，禁用 selectPage** + （2026-09-24 生产实测 total=0 不分页）；Jackson `ObjectNode.putArray` 同名字段会覆盖，filter 数组只建一次。 +3. **测试**：每个工具至少覆盖 参数校验/权限/枚举映射/空数据/关键回归（对齐老系统 bug 修复点）； + `./mvnw clean package` 全量必须全过（构建需 JAVA_HOME 指向 .tools 的 JDK 17 + ComSpec 环境变量）。 +4. **提交部署**：Conventional Commits（`feat(mcp): ...`），先 `git push origin main` 再 + `./deploy/deploy.sh remote-deploy`；push 偶发 "Failed to authenticate user" 重试即可。 + 部署后确认远程日志 ToolSyncService「新增 tool」记录。 +5. **scope 绑定**：按上面部署要点幂等绑 scope（INSERT IGNORE into scope_tool）。 +6. **生产冒烟**：用 `/api/open/token/ensure`（X-Open-Key=$OPEN_API_KEY，旧版密钥可签用户 Token，不能签服务 Token） + 给用户（如 id=812 王恒）签 ops-query Token → initialize 取 mcp-session-id → notifications/initialized → tools/call； + 真实数据验证关键路径 + 边界（超限报错、不存在返回）。 +7. **建 ai-proj 需求**：REST 创建（不带 project_id）→ reassignment preflight/confirm 挂 224 → + 建任务（project_id 224、status completed）→ `POST /requirements/{id}/tasks` 关联（role=implementation）→ + PUT 回写实施记录（提交号/测试数/部署 pid/冒烟结果/scope 绑定）→ `POST /requirements/{id}/submit` 推进到待评审。 + released 只能评审或 CLI sync（本机与生产服务器均无 CLI）。 +8. **收尾**：更新 `doc/agent-mcp-tools-reference.md`（追加工具章节，编号顺延）、 + 更新本文件「近期需求示例」；设计文档与代码同提交入库。