From 4e5ee541e3968a8f040a69a36471faa03285b006 Mon Sep 17 00:00:00 2001 From: my_local_kimi_dev2 Date: Wed, 16 Sep 2026 18:30:07 +0800 Subject: [PATCH] docs(mcp): update ops/ai integration docs with prod scope facts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 4.1 生产环境对接现状（MCP 入口、ensure 换签、握手流程） - operation scope(id=2) 当前绑定 24 个工具；移除未绑定的 agent.count - xiaoqu-ai scope(id=3) 当前绑定 12 个工具；代理域工具改为实际可用映射 - 开发顺序改为按 4.1 清单对照核验 --- .../doc/xiaoqu-ai-mcp-integration-design.md | 47 +++++++++++++++++-- ...qu-operations-ai-mcp-integration-design.md | 38 +++++++++++++-- 2 files changed, 76 insertions(+), 9 deletions(-) diff --git a/xiaoqu-agent-service/doc/xiaoqu-ai-mcp-integration-design.md b/xiaoqu-agent-service/doc/xiaoqu-ai-mcp-integration-design.md index 331e5cd..94ebc5d 100644 --- a/xiaoqu-agent-service/doc/xiaoqu-ai-mcp-integration-design.md +++ b/xiaoqu-agent-service/doc/xiaoqu-ai-mcp-integration-design.md @@ -64,6 +64,33 @@ iOS Sales Agent ──► agent-service │ │ 启用时 URL、Open Key 和 scope 必填。Open Key 只来自部署 Secret，不写入 YAML、客户端配置或仓库。 +### 4.1 生产环境对接现状（2026-09-16 在 prod svc 库核验） + +| 项 | 生产实际值 | +|---|---| +| MCP 入口 | `https://agent.ququclean.com/mcp`（Streamable HTTP，POST） | +| Token 换取 | `POST https://agent.ququclean.com/api/open/token/ensure`，header `X-Open-Key` | +| 本系统 scope | `xiaoqu-ai`（scope id=3，名称「小趣CRM」），服务端固定，禁止模型或客户端选择 | +| 服务密钥 | CRM 专用服务密钥已绑定 `xiaoqu-ai`（同时绑了 sync/operation/test 四域）；密钥未绑 scope 时 ensure 返回 403 | + +**作用域注意**：生产共有 4 个作用域——`test`(id=1，全量)、`operation`(id=2，运营app)、`xiaoqu-ai`(id=3，本系统)、`sync`(id=4，数据同步)。各域绑定独立维护，与 dev 种子数据不一致，核对以 prod svc 库 `agent_scope` / `scope_tool` 为准。 + +**`xiaoqu-ai` scope 当前绑定的工具（12 个）**： + +- 站点/物业/设备：`district.list.query`(4)、`district.detail.get`(5)、`property.list.query`(6)、`property.detail.query`(7)、`hardware.list.query`(14)、`hardware.detail.query`(15) +- 商城订单：`mall.order.list.query`(9)、`mall.order.detail.query`(10)、`mall.order.logistics.query`(11) +- 合同：`contract.list.query`(12)、`contract.detail.query`(13) +- 自检：`integration.context.get`(19) + +**未绑定到 `xiaoqu-ai` 的工具**：`agent.count`(1)、`agent.list.query`(2)、`agent.detail.query`(3)（代理域工具，CRM 首期未开通）、`sys.ping`(8)、`*.changes.list`(16-18)、`contracts.current.batch_get`(25)（后两类为 sync 专用）、全部仓库工具(20-24,26) 与送货/装机工单工具(27-30)。如 CRM 后续需要仓库/工单能力，须先评审再在管理后台补绑。 + +**Token 换取与 MCP 握手流程**： + +1. Gateway 持 `X-Open-Key` 调 ensure：`{"mobile":"<企业账号手机号>","scopeCode":"xiaoqu-ai"}` → 返回 `xqak_...`（长期有效，幂等，created=false 表示复用已有） +2. `POST /mcp` 发 `initialize`，从响应头取 `mcp-session-id` +3. 发 `notifications/initialized`，之后 `tools/list` / `tools/call` 必须带 `Mcp-Session-Id` 头 +4. `Authorization: Bearer xqak_...`（Bearer 前缀只拼一次） + ### 4.2 最小模块 新增 `gateway/internal/connector/xiaoqumcp/`： @@ -82,13 +109,23 @@ iOS Sales Agent ──► agent-service │ │ 在 `gateway/internal/agent/tools.go` 注册稳定的本地工具名，由 Handler 调用 `xiaoqumcp.Client`。不得把远端 `tools/list` 原样注册给模型。 -首期只接只读工具。候选映射以 xiaoqu-mcp 当前工具为基础，但必须先为 xiaoqu-ai 创建并审核独立 scope： +首期只接只读工具。候选映射以 xiaoqu-mcp 当前工具为基础，但必须先为 xiaoqu-ai 创建并审核独立 scope。**生产 `xiaoqu-ai` scope（id=3）已存在并已绑定工具，实际可用映射如下（2026-09-16 核验）**： | Gateway 本地工具 | MCP 工具 | 状态 | |---|---|---| -| `xiaoqu.agent_count` | `agent.count` | scope 绑定后启用 | -| `xiaoqu.agent_list` | `agent.list.query` | scope 绑定后启用 | -| `xiaoqu.property_list` | `property.list.query` | scope 绑定后启用 | +| `xiaoqu.property_list` | `property.list.query` | 已绑定，可启用 | +| `xiaoqu.property_detail` | `property.detail.query` | 已绑定，可启用 | +| `xiaoqu.district_list` | `district.list.query` | 已绑定，可启用 | +| `xiaoqu.district_detail` | `district.detail.get` | 已绑定，可启用 | +| `xiaoqu.hardware_list` | `hardware.list.query` | 已绑定，可启用 | +| `xiaoqu.hardware_detail` | `hardware.detail.query` | 已绑定，可启用 | +| `xiaoqu.mall_order_list` | `mall.order.list.query` | 已绑定，可启用 | +| `xiaoqu.mall_order_detail` | `mall.order.detail.query` | 已绑定，可启用 | +| `xiaoqu.mall_order_logistics` | `mall.order.logistics.query` | 已绑定，可启用 | +| `xiaoqu.contract_list` | `contract.list.query` | 已绑定，可启用 | +| `xiaoqu.contract_detail` | `contract.detail.query` | 已绑定，可启用 | + +> 勘误（2026-09-16）：原候选清单中的 `agent.count` / `agent.list.query` 属代理商域工具，**未绑定到 `xiaoqu-ai` scope**，已移除；如需代理数据须先在管理后台补绑并评审数据范围。仓库与送货/装机工单工具（20-30）也尚未绑定到本 scope，属后续批次。 每个工具继续使用现有 `RequiredDataScope`、Agent Capability 绑定和参数 schema。MCP 返回结果先做字段白名单投影，再进入模型上下文、卡片渲染和 `chat_tool_logs`。 @@ -129,7 +166,7 @@ Agent Service 的 `runtime_gateway_tools.py` 继续转发入站用户 JWT；无 ## 8. 开发顺序 -1. 在目标环境创建或确认 xiaoqu-ai 独立 scope，并绑定首期只读工具。 +1. 在目标环境确认 `xiaoqu-ai` 独立 scope 和工具绑定（prod 已于 2026-09-16 核验，见 4.1 节，首期 10 项只读工具已绑定；新环境上线时按 4.1 清单对照）。 2. 增加 Gateway 配置与启动校验。 3. 实现 `token_provider.go` 和 `client.go`，覆盖 Token、Session、超时和错误映射测试。 4. 在 ToolExecutor 注册固定工具并复用现有 DataScope 校验。 diff --git a/xiaoqu-agent-service/doc/xiaoqu-operations-ai-mcp-integration-design.md b/xiaoqu-agent-service/doc/xiaoqu-operations-ai-mcp-integration-design.md index 534f730..e59aebe 100644 --- a/xiaoqu-agent-service/doc/xiaoqu-operations-ai-mcp-integration-design.md +++ b/xiaoqu-agent-service/doc/xiaoqu-operations-ai-mcp-integration-design.md @@ -75,7 +75,36 @@ Planner 选择本地 Capability | `XQ_MCP_SCOPE_CODE` | `operation` | 服务端固定 scope，禁止由客户端或模型选择 | | `XQ_MCP_TIMEOUT_SECONDS` | `10` | MCP 请求超时 | -启用时 URL、Open Key 和 scope 必填。`operation` 已存在于 xiaoqu-mcp dev 种子；development、test、staging、production 均须分别核对真实 scope 和工具绑定。凭证只由部署 Secret 注入。 +启用时 URL、Open Key 和 scope 必填。凭证只由部署 Secret 注入。 + +### 4.1 生产环境对接现状（2026-09-16 在 prod svc 库核验） + +| 项 | 生产实际值 | +|---|---| +| MCP 入口 | `https://agent.ququclean.com/mcp`（Streamable HTTP，POST） | +| Token 换取 | `POST https://agent.ququclean.com/api/open/token/ensure`，header `X-Open-Key` | +| 本系统 scope | `operation`（scope id=2，名称「运营app」），服务端固定，禁止客户端或模型选择 | +| 服务密钥要求 | 运营专用服务密钥只绑定了 `operation`；密钥未绑 scope 时 ensure 返回 403 | + +**重要勘误**：dev 种子数据与生产不一致——生产承载全量工具的作用域是 `code='test'`（id=1），`operation`（id=2）是独立的运营作用域，两域绑定各自维护。上线核对时必须以 prod svc 库 `agent_scope` / `scope_tool` 为准。 + +**`operation` scope 当前绑定的工具（24 个）**： + +- 代理/物业/站点/设备：`agent.list.query`(2)、`agent.detail.query`(3)、`district.list.query`(4)、`district.detail.get`(5)、`property.list.query`(6)、`property.detail.query`(7)、`hardware.list.query`(14)、`hardware.detail.query`(15) +- 商城订单：`mall.order.list.query`(9)、`mall.order.detail.query`(10)、`mall.order.logistics.query`(11) +- 合同：`contract.list.query`(12)、`contract.detail.query`(13) +- 仓库：`warehouse.out.list.query`(20)、`warehouse.out.detail.query`(21)、`warehouse.in.list.query`(22)、`warehouse.in.detail.query`(23)、`warehouse.stock.list.query`(26)、`warehouse.todo.list.query`(24) +- 工单：`delivery.order.list.query`(27)、`delivery.order.detail.query`(28)、`install.order.list.query`(29)、`install.order.detail.query`(30) +- 自检：`integration.context.get`(19) + +**未绑定到 `operation` 的工具**：`agent.count`(1)、`sys.ping`(8)、`*.changes.list`(16-18，数据同步专用)、`contracts.current.batch_get`(25，sync 专用)。首期 Capability 选择须以上表为准。 + +**Token 换取与 MCP 握手流程**： + +1. 服务端持 `X-Open-Key` 调 ensure：`{"mobile":"<企业账号手机号>","scopeCode":"operation"}` → 返回 `xqak_...`（长期有效，幂等，created=false 表示复用已有） +2. `POST /mcp` 发 `initialize`，从响应头取 `mcp-session-id` +3. 发 `notifications/initialized`，之后 `tools/list` / `tools/call` 必须带 `Mcp-Session-Id` 头 +4. `Authorization: Bearer xqak_...`（Bearer 前缀只拼一次；库中存的令牌值本身不含前缀） ## 5. 最小模块 @@ -117,11 +146,12 @@ Planner 选择本地 Capability | 本地 Capability | `adapter_id` | MCP 工具 | 权限 | |---|---|---|---| -| `xiaoqu.agent_count` | `mcp.xiaoqu.agent_count.v1` | `agent.count` | read | | `xiaoqu.agent_list` | `mcp.xiaoqu.agent_list.v1` | `agent.list.query` | read | | `xiaoqu.property_list` | `mcp.xiaoqu.property_list.v1` | `property.list.query` | read | -每项必须在 `CAPABILITY_REGISTRY` 中声明输入/输出 schema、风险、审批、超时重试、审计事件和结果模板，并将精确 `adapter_id` 加入 `EXECUTION_ADAPTER_IDS`。已有本地 Capability 不改名、不改 Adapter、不改变执行语义。 +> 勘误（2026-09-16）：原首期清单中的 `agent.count` **未绑定到生产 `operation` scope**（该工具只绑在 `test` 全量域，见 4.1 节），已从首期 Capability 移除；如需使用须先在管理后台为 `operation` 补绑该工具。 + +后续批次可按 4.1 节已绑定的清单扩展 Capability（仓库、工单、合同、商城物流等），每项必须在 `CAPABILITY_REGISTRY` 中声明输入/输出 schema、风险、审批、超时重试、审计事件和结果模板，并将精确 `adapter_id` 加入 `EXECUTION_ADAPTER_IDS`。已有本地 Capability 不改名、不改 Adapter、不改变执行语义。 ## 7. 身份与权限 @@ -153,7 +183,7 @@ Web、iOS、Android 提交消息后获得 `202`；Worker 在后台完成 Agent ## 9. 开发顺序 -1. 核对各环境 `operation` scope、三项工具绑定和用户映射数据源。 +1. 核对各环境 `operation` scope 和工具绑定（prod 已于 2026-09-16 核验，见 4.1 节；新环境上线时按 4.1 清单对照）和用户映射数据源。 2. 扩展只读 SharedUser Port，完成运营 UUID 到 mobile/email 的可信解析测试。 3. 增加 Settings 配置、启用校验和 `XiaoquMcpRuntime` 生命周期。 4. 实现 Token Provider、MCP Client 和 Adapter 的协议单元测试。