From f2eb8afcddaadcc8e7234ade1ef50a72e9622bd8 Mon Sep 17 00:00:00 2001 From: my_local_kimi_dev2 Date: Sat, 7 Nov 2026 23:52:56 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E4=B8=8A=E7=BA=BF=E6=A0=87=E5=87=86?= =?UTF-8?q?=E6=B5=81=E7=A8=8B=E5=9B=BA=E5=8C=96=E6=B5=8B=E8=AF=95=E7=8E=AF?= =?UTF-8?q?=E5=A2=83=E5=86=92=E7=83=9F=E5=85=88=E8=A1=8C=EF=BC=88=E5=86=99?= =?UTF-8?q?=E5=B7=A5=E5=85=B7=E5=85=A8=E9=87=8F=E5=86=92=E7=83=9F=E8=B5=B0?= =?UTF-8?q?=20dev=20=E5=BA=93=EF=BC=8C=E7=94=9F=E4=BA=A7=E5=8F=AA=E8=AF=BB?= =?UTF-8?q?=E6=A0=B8=E9=AA=8C=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- xiaoqu-agent-service/AGENTS.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/xiaoqu-agent-service/AGENTS.md b/xiaoqu-agent-service/AGENTS.md index f469d00..b375488 100644 --- a/xiaoqu-agent-service/AGENTS.md +++ b/xiaoqu-agent-service/AGENTS.md @@ -50,16 +50,20 @@ （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` 再 +4. **测试环境冒烟（2026-11-07 起强制，王恒拍板：不直接动线上数据）**：`./deploy/test-up.sh [--skip-build]` + 起本机测试环境 → 签 Token 用 `scopeCode=test`（「测试专用」scope）→ initialize 取 mcp-session-id → + notifications/initialized → tools/call；**写工具的全部冒烟（真实改派/作废/改回、边界用例）都在这里跑完， + DB 复核恢复原状后才允许上生产**。 +5. **提交部署**：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 → +6. **scope 绑定**：按上面部署要点幂等绑 scope（INSERT IGNORE into scope_tool）。 +7. **生产核验（只读）**：远程 jar md5 与本地一致、健康检查 POST /mcp 返回 401、tools/list 可见； + 可跑纯查询用例验证关键路径与边界（超限报错、不存在返回），**不做改派/作废类写操作**。 + 生产签 Token 用 `/api/open/token/ensure`（X-Open-Key=$OPEN_API_KEY，旧版密钥可签用户 Token，不能签服务 Token）。 +8. **建 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`（追加工具章节，编号顺延）、 +9. **收尾**：更新 `doc/agent-mcp-tools-reference.md`（追加工具章节，编号顺延）、 更新本文件「近期需求示例」；设计文档与代码同提交入库。