docs(agent): 沉淀新 MCP 工具上线标准流程（设计评审→实现→部署→建需求→submit）

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`（追加工具章节，编号顺延）、
+   更新本文件「近期需求示例」；设计文档与代码同提交入库。