xiaoqu_mcp_service/xiaoqu-agent-service/AGENTS.md

xiaoqu-agent-service 项目指引

ai-proj 关联信息

• ai-proj 项目 ID：224（项目名 xiaoqu_agent_service）。本仓所有需求/任务创建后应挂到该项目，关联任务前确保任务也在项目 224。
• 近期需求示例：REQ-20261012-0002（id 5975，客户换纸记录工具 district.paper.trace.list.query，released）→ 任务 23486；REQ-20260924-0009（id 5806，人流量统计工具+统计类限一个月，implementation 完成）→ 任务 22405；REQ-20260924-0003（id 5800，设备生命周期查询工具，implementation 完成）→ 任务 22391；REQ-20260921-0007（id 5778，设备电量消息查询工具，released）→ 任务 22306；REQ-20260919-0003（id 5747，出入库工具复查修复，released）→ 任务 22123。

ai-proj MCP 已知限制与真实契约

• 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）。
• REST 建需求/任务实测（2026-09-24）：POST /requirements 与 POST /tasks 的 body 带 project_id:224 会创建失败/被忽略，先裸建再走 reassignment；关联用 POST /requirements/{id}/tasks body={task_id, role:"implementation"}；更新用 PUT /requirements/{id}（不支持 PATCH），delivery_stage/reviewer_id 为只读（PUT 静默忽略）；POST /requirements/{id}/submit 可推进 draft→pending 并自动分配评审人，POST /requirements/{id}/review 仅评审人可调用；released 由 CLI sync 或评审/界面流转。
• 本机无 ai-proj CLI，远程同步需在有 CLI 的机器执行 ai-proj sync requirement --id <id> --direction to_remote。

生产 ES 集群关键坑

• 生产两个 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。
• electricitymessage 索引（电量消息类）：createTime 是 date 类型（format strict_date_optional_time||epoch_millis），range 必须发 epoch 毫秒（yyyy-MM-dd HH:mm:ss 字符串 400）；_source 里 value 是文本（"28"/"100"）、createTime 是 ISO 文本（2026-09-21T10:00:00.000+08:00），读取时都要归一。老系统能跑是因为 transport 客户端把 Date 序列化成 epoch 毫秒、Jackson 把字符串 value 反序列化进 Integer 字段。
• paperuselog 索引（换纸日志）：rfid 是 text 类型（mapping 有 ignore_above=256 的 keyword 子字段），terms 聚合必须用 rfid.keyword，直接聚合 text 字段被 7.7.1 以 400 "Text fields are not optimised for aggregations" 拒绝（2026-09-22 生产实测修复）；老系统不做 ES 聚合，而是翻页拉全量文档后在 Java 侧按 P_{positionsId}_{snCode}_{rfid}/T_{toiletId}_{snCode}_{rfid} 复合 key 去重，MCP 用 terms 聚合近似（语义差异见设计文档）。
• curl 直连 MCP 冒烟：JSON body 务必 -d @file（行内 -d 长 JSON 经网关会被截断报 "Invalid message format"）；响应是 SSE，sed -n 's/^data://p' 取 JSON。
• 托管 MCP 工具（mcp__xiaoqu__*）在服务重启后 session 失效会报 AI_PROJ_MCP_SEND_OUTCOME_UNKNOWN，改走上面 curl 直连即可。

生产部署要点

• ./deploy/deploy.sh remote-deploy（SSH 别名 xiaoqu-prd，目录 /data/xiaoqu-agent-service）。
• 部署前必须先把 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（追加工具章节，编号顺延）、 更新本文件「近期需求示例」；设计文档与代码同提交入库。