From 6e7a5da19dd85f83300d4bbc886c344fb9e9db06 Mon Sep 17 00:00:00 2001 From: my_local_kimi_dev2 Date: Mon, 21 Sep 2026 18:40:10 +0800 Subject: [PATCH] docs(agent-service): add AGENTS.md with ai-proj project id 224 and known MCP contract limits --- xiaoqu-agent-service/AGENTS.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 xiaoqu-agent-service/AGENTS.md diff --git a/xiaoqu-agent-service/AGENTS.md b/xiaoqu-agent-service/AGENTS.md new file mode 100644 index 0000000..9312fa2 --- /dev/null +++ b/xiaoqu-agent-service/AGENTS.md @@ -0,0 +1,20 @@ +# xiaoqu-agent-service 项目指引 + +## ai-proj 关联信息 + +- **ai-proj 项目 ID：224**（项目名 xiaoqu_agent_service）。本仓所有需求/任务创建后应挂到该项目，关联任务前确保任务也在项目 224。 +- 近期需求示例：REQ-20260921-0007（id 5778，设备电量消息查询工具，released）→ 任务 22306。 + +## ai-proj MCP 已知限制与真实契约 + +- MCP `update_requirement` 不支持改 project_id/owner；改归属必须走 REST 两步： + 1. `POST /api/v1/requirements/{id}/reassignment/preflight`，body=`{operation_id:"", expected_version:<当前sync_version>, target_project_id:224, target_owner_id?/clear_owner?}` + 2. `POST /api/v1/requirements/{id}/reassignment/confirm`，body=`{operation_id, preflight_token}` +- 任务跨项目用 `move_task`，再 `link_tasks_to_requirement`（role=implementation）。 +- 本机无 ai-proj CLI，远程同步需在有 CLI 的机器执行 `ai-proj sync requirement --id --direction to_remote`。 + +## 生产部署要点 + +- `./deploy/deploy.sh remote-deploy`（SSH 别名 xiaoqu-prd，目录 /data/xiaoqu-agent-service）。 +- 新工具上线后必须幂等绑 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 " 前缀，不要再拼。