xiaoqu-agent-service 项目指引

ai-proj 关联信息

ai-proj 项目 ID：224（项目名 xiaoqu_agent_service）。本仓所有需求/任务创建后应挂到该项目，关联任务前确保任务也在项目 224。
近期需求示例：REQ-20260921-0007（id 5778，设备电量消息查询工具，released）→ 任务 22306；REQ-20260919-0003（id 5747，出入库工具复查修复，released）→ 任务 22123。

MCP update_requirement 不支持改 project_id/owner；改归属必须走 REST 两步：
1. POST /api/v1/requirements/{id}/reassignment/preflight，body={operation_id:"<uuid>", 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}（两个字段缺一不可；preflight_token 一次性，confirm 失败即作废，必须在同一条命令里 preflight+confirm 原子执行）
REST base 推导：mcp.json 里 ai-proj 的 url 去掉尾部 /mcp/sse（即 https://ai.pipexerp.com/api/v1），认证头 X-API-Key 同 mcp.json。
⚠️ 本机 shell（Bash 工具）直读 ~/.kimi-code/mcp.json 会被托管层拦截（"local Shell bypass is disabled for a managed MCP route"）；用 Read 工具读取不受限。
任务跨项目用 move_task，再 link_tasks_to_requirement（role=implementation）。
本机无 ai-proj CLI，远程同步需在有 CLI 的机器执行 ai-proj sync requirement --id <id> --direction to_remote。

生产两个 ES 集群（cloud/local，app.es.cloud/local.*）均为 ES 7.7.1：elasticsearch-java 7.17 高阶客户端（ElasticsearchClient）的 vendor Content-Type（application/vnd.elasticsearch+json; compatible-with=7）被 406 拒绝，且其 X-Elastic-Product 响应头校验（7.14 才引入）过不了——业务 ES 查询一律注入低阶 esCloudRestClient/esLocalRestClient（RestClient）bean，不要注入 esCloudClient/esLocalClient（EsClientConfig 里仅为兼容保留）。
低阶 org.elasticsearch.client.Response 构造器包私有且参数是 HttpResponse，测试里用 mock(Response.class) + stub getEntity() 构造；注意 thenReturn(esResponse(...)) 里嵌套 when() 会触发 UnfinishedStubbingException，必须先创建好 Response 再 stub。

./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 " 前缀，不要再拼。