docs: align MCP token flow to single ensure-only policy

docs: sync MCP token spec to one-time mobile token flow
docs(mcp): 统一服务文档目录
2026-09-07 13:16:18 +09:30 · 2026-09-07 13:04:13 +09:30 · 2026-09-07 12:27:02 +09:30 · 2026-09-04 18:00:41 +08:00 · 2026-09-04 17:07:11 +08:00 · 2026-09-04 16:53:18 +08:00
28 changed files with 1471 additions and 114 deletions
@@ -25,3 +25,4 @@ front/dist/

 # 本地环境配置(不入库)
 .env
+.kimi-code/mcp.json
@@ -1,8 +0,0 @@
-{
-  "mcpServers": {
-    "xiaoqu": {
-      "url": "http://192.168.4.236:8088/mcp",
-      "bearerTokenEnvVar": "XQ_API_KEY"
-    }
-  }
-}
@@ -55,7 +55,7 @@ xiaoqu-agent-service/
 - `/mcp` 全路径要求 `Authorization: Bearer <ak>`，缺失/无效/禁用/过期 → 401 JSON。
 - 判定链（设计文档 §3.2）：ak → SHA-256 hex → `agent_api_key` 匹配 → 解析出人（Redis db5 `entity:User:{id}` 热缓存优先，fastjson camelCase JSON 用 Jackson 解析；读不到回源 m0 `user` 表）→ AuthContext 存 ThreadLocal → 工具调用前 scope 校验 → 审计落库。
 - **ThreadLocal 实测结论**：`spring.ai.mcp.server.type=SYNC`（application.yml 已显式设置）时，Spring AI 1.1.8 的工具回调在 servlet 请求线程（`nio-8088-exec-*`）上同步执行，ThreadLocal 的 AuthContext 与 RequestContextHolder 均有效（已用真实 curl 验证：agent.list.query 按人过滤、audit_log 正确落 user_id/token_id/client_ip）。AkAuthFilter 在请求结束 finally 清理。
- **已知限制**：`tools/list` 暂不按 key 过滤工具列表，所有工具可见；`tools/call` 时的 scope 强制校验是底线。
+- **tools/list 按作用域过滤**（2026-09-04 起）：MCP SDK 的工具清单在启动时静态注册，无法按请求过滤，故 `ToolsListScopeFilter` 在 servlet 层拦截 POST /mcp 的 tools/list 响应并重写 `result.tools`（只保留该 ak 作用域并集内、且启用状态的工具）。`tools/call` 路径不变：越权调用仍返回可读拒绝信息并落 denied 审计。
 - client_type 识别：`X-Client-Type` 头优先，否则 User-Agent 含 kimi→mcp-kimi / claude→mcp-claude / curl→cli，其余 unknown。

 ## 行级数据权限引擎（permission/PermissionService）
@@ -93,19 +93,11 @@ mysql -h192.168.1.181 -u<svc_db_admin> -p < sql/bootstrap/create-database.sql
 # 启动一次让 ToolSyncService 同步 tool 表后：
 mysql -h192.168.1.181 -u<svc_db_admin> -p xiaoqu_agent_svc_d < sql/seed-dev.sql

-# 必须显式指定环境及凭据；m0/m1/m2 使用数据库只读账号
+# 数据库/Redis 连接信息已明文写在 application-dev.yml（内网 dev 库）；
+# 仍需显式指定 profile
 export SPRING_PROFILES_ACTIVE=dev
-export M0_DB_USERNAME=<readonly_user>
-export M0_DB_PASSWORD=<password>
-export M1_DB_USERNAME=<readonly_user>
-export M1_DB_PASSWORD=<password>
-export M2_DB_USERNAME=<readonly_user>
-export M2_DB_PASSWORD=<password>
-export SVC_DB_USERNAME=<svc_user>
-export SVC_DB_PASSWORD=<password>
 # 已有 V1 库首次接入时设 true；确认 flyway_schema_history 后可设 false
 export SVC_FLYWAY_BASELINE_ON_MIGRATE=true
-export REDIS_PASSWORD=<password>
 # 仅首次、且 admin_user 为空时创建管理员；创建完成后可移除这三个变量
 export ADMIN_BOOTSTRAP_ACCOUNT=<admin_account>
 export ADMIN_BOOTSTRAP_PASSWORD=<strong_password>
@@ -119,7 +111,7 @@ java -jar target/xiaoqu-agent-service.jar
 nohup java -jar target/xiaoqu-agent-service.jar > target/app.log 2>&1 &
 ```

- 不提供默认 profile、数据库账号或密码；缺失配置时不得启动。
+- 不提供默认 profile；数据库/Redis 连接信息明文写在 `application-dev.yml`（内网 dev 库，与 xiaoqu-franchisee pom.xml dev profile 同一惯例）；生产/测试环境不得在配置文件写明文密码。
 - dev 端口 **8088**，管理后台 `http://localhost:8088/`，MCP 端点 `http://localhost:8088/mcp`。
 - Flyway 在 Web 服务启动前执行 `validate + migrate`；checksum、版本或 SQL 执行失败时应用不会启动。
 - 新增 SQL 必须遵循 [sql/README.md](sql/README.md)，禁止修改已合并的历史 migration。
@@ -133,16 +125,16 @@ cp deploy/.env.example deploy/.env.dev   # 填写 dev 凭据（已 gitignore，
 ./deploy/deploy.sh status | log | stop   # 状态 / 跟踪日志 / 停止
 ```

- 凭据从 `deploy/.env.dev` 读取，无需手工 export；日志在 `logs/agent-service.log`，pid 在 `deploy/app.pid`。
+- `.env.dev` 只需管理员引导和 Flyway 开关；数据库/Redis 已走配置文件。日志在 `logs/agent-service.log`，pid 在 `deploy/app.pid`。
 - 注意应用启动较慢（多数据源初始化，约 60-90s），脚本健康检查窗口已放宽到 180s。

 ## 测试 ak（仅 dev）

-仓库不提供固定 ak。每位开发者在本地生成随机 ak，只把 SHA-256 写入 `agent_api_key`，再用 `token_scope` 关联需要的作用域；明文只保存在本地环境变量中，不提交版本库。仓库历史中曾出现的 dev ak 必须视为已泄露并在数据库中禁用。
+仓库不提供固定 ak。每位开发者在本地生成随机 ak，只把 SHA-256 写入 `agent_api_key`，再用 `token_scope` 关联需要的作用域；明文只保存在本机客户端配置（如 `.kimi-code/mcp.json`，已 gitignore）中，不提交版本库。仓库历史中曾出现的 dev ak 必须视为已泄露并在数据库中禁用。

 ```bash
-export XQ_API_KEY="xqak_$(openssl rand -hex 24)"
-printf %s "$XQ_API_KEY" | shasum -a 256
+AK="xqak_$(openssl rand -hex 24)"   # 生成随机 ak，明文只贴进本机客户端配置
+printf %s "$AK" | shasum -a 256     # 输出的哈希写入 agent_api_key.key_hash
 ```

 ## curl 验证（Streamable HTTP 握手）
@@ -181,29 +173,50 @@ agent.list.query 抽测：channel_no='D' + province='北京市' → 总部 11 /

 dev 服务地址示例：`http://192.168.4.236:8088/mcp`（本机内网 IP；本机自测可用 localhost）。生产必须 HTTPS（Nginx 终结 TLS）。

-**Kimi Code** — 项目级 `.kimi-code/mcp.json`：
+**Kimi Code** — 项目级 `.kimi-code/mcp.json`（ak 明文直写；该文件已加入 `.gitignore`，不会提交版本库）：

 ```json
 {
  "mcpServers": {
    "xiaoqu": {
      "url": "http://192.168.4.236:8088/mcp",
-      "bearerTokenEnvVar": "XQ_API_KEY"
+      "headers": {
+        "Authorization": "Bearer <测试ak>"
+      }
    }
  }
 }
 ```

-shell 里 `export XQ_API_KEY=<测试ak>` 后启动 Kimi Code 即可自发现工具。
+写入 ak 后 `/new` 开个新会话即可自发现工具（MCP 配置只在会话启动时加载）。

 **Claude Code**：

 ```bash
-export XQ_API_KEY=<测试ak>
 claude mcp add --transport http xiaoqu http://192.168.4.236:8088/mcp \
-  --header "Authorization: Bearer $XQ_API_KEY"
+  --header "Authorization: Bearer <测试ak>"
 ```

+## Open API（服务间接口，/api/open/**）
+
+供其他系统在服务端到服务端场景下获取用户 Token。鉴权为静态服务间密钥（header `X-Open-Key`，dev 明文配置在 `application-dev.yml` 的 `app.open.api-key`；配置为空 = 接口关闭）。
+
+**`POST /api/open/token/ensure`** —— 按 手机号/邮箱 + 作用域编码 确保 Token 存在（get-or-create）：
+
+```bash
+curl -X POST http://localhost:8088/api/open/token/ensure \
+  -H 'Content-Type: application/json' \
+  -H 'X-Open-Key: <服务间密钥>' \
+  -d '{"mobile":"13800001111","scopeCode":"operation"}'
+```
+
+- 入参：`mobile`、`email` 至少一个（手机号优先）；`scopeCode` 必填。人员只认企业账号（enterprise_type 0/1），查不到 → 404。
+- 已存在有效 Token → `{"created":false,"token":null,"keyPrefix":"xqak_xxx…",...}`（服务端只存哈希，**明文不可回吐**，丢了只能后台重新签发）。
+- 不存在 → 自动创建永久 Token → `{"created":true,"token":"xqak_...（明文，仅此一次）",...}`。
+- 调用写 `audit_log`（`open.token.ensure` / client_type=open-api）。
+
+**签发规则（2026-09-04 起）**：一作用域一 Token。后台签发时选 N 个作用域会生成 N 把 token，每把独立绑定单作用域；编辑存量 token 时作用域为单选。
+
 ## codegen（run-once）

 表白名单：m0 `user, agent, authority, properyt, agent_manage_district_auth`；m2 `warehouse_agent_auth`；svc `agent_api_key, agent_scope, tool, scope_tool, token_scope, audit_log, admin_user`（注：物业表真实表名为老系统遗留拼写 `properyt`）。生成物落在 `src/main/java` 对应分包并提交进仓库。
@@ -1,13 +1,10 @@
-# dev 环境凭据（本文件为模板；实际使用复制为 .env.dev，已 gitignore）
-# 取值参考 xiaoqu-franchisee/pom.xml dev profile
-M0_DB_USERNAME=root
-M0_DB_PASSWORD=
-M1_DB_USERNAME=root
-M1_DB_PASSWORD=
-M2_DB_USERNAME=root
-M2_DB_PASSWORD=
-SVC_DB_USERNAME=root
-SVC_DB_PASSWORD=
+# dev 环境变量（本文件为模板；实际使用复制为 .env.dev，已 gitignore）
+# 数据库/Redis 连接信息已明文写在 application-dev.yml，无需在此配置
+
+# 后台管理员首次引导（仅首次启动且 admin_user 为空时建号，之后可删除）
+APP_ADMIN_BOOTSTRAP_ACCOUNT=admin
+APP_ADMIN_BOOTSTRAP_PASSWORD=
+# APP_ADMIN_BOOTSTRAP_NAME=系统管理员
+
 # 默认拒绝为非空库自动建基线；仅已有 V1 库首次接入时临时改为 true
 SVC_FLYWAY_BASELINE_ON_MIGRATE=false
-REDIS_PASSWORD=
@@ -69,6 +69,8 @@ xq CLI ─────┘  (Go 单二进制, 同为 MCP 客户端)   ┌──
 4. 执行查询，按"人"的数据权限规则加行过滤
 5. 审计落库（人、token、工具、入参摘要、结果、耗时）

+注：`tools/list` 按作用域过滤（2026-09-04 决策，避免"看得到却调不了"的二义性）：MCP SDK 工具清单在启动时静态注册，无法按请求过滤，故由 `ToolsListScopeFilter` 在 servlet 层重写 tools/list 响应。第 3 步的强制点仍是 `tools/call`——绕过 list 直接调未授权工具，得到的仍是可读的拒绝信息 + denied 审计。
+
 ### 3.3 行级数据权限移植规范（照搬现有系统）

 来源：`WrapperUtils.getByIsAgent` 系列 + `authority.isagent`。规则：
@@ -94,7 +96,7 @@ xq CLI ─────┘  (Go 单二进制, 同为 MCP 客户端)   ┌──
 | ES | 部分列表查询 | 预留，一期可后置 |

 - 全部使用**只读数据库账号**（物理封死误写）；将来写工具单独配有写权限的账号。
- 配置按环境分文件（dev/test/prd），密码走环境变量，对齐现有 Maven profile 注入方式。
+- 配置按环境分文件（dev/test/prd）；dev 环境密码明文写在 `application-dev.yml`（内网 dev 库，与现有 pom.xml dev profile 明文同一惯例），生产/测试环境不得在配置文件写明文密码。

 ### 4.1 Entity 生成

@@ -105,25 +107,27 @@ xq CLI ─────┘  (Go 单二进制, 同为 MCP 客户端)   ┌──
 ### 5.1 MCP（主形态）

 - Streamable HTTP 传输，端点 `https://mcp.<域名>/mcp`。
- 客户端配置（Kimi Code `~/.kimi-code/mcp.json`）：
+- 客户端配置（Kimi Code `~/.kimi-code/mcp.json` 或项目级 `.kimi-code/mcp.json`，ak 明文直写；项目级文件已加入 `.gitignore`）：

 ```json
 {
  "mcpServers": {
    "xiaoqu": {
      "url": "https://mcp.<域名>/mcp",
-      "bearerTokenEnvVar": "XQ_API_KEY"
+      "headers": {
+        "Authorization": "Bearer <ak>"
+      }
    }
  }
 }
 ```

 - Claude Code：`claude mcp add --transport http xiaoqu https://mcp.<域名>/mcp --header "Authorization: Bearer <ak>"`。
- ak 明文只出现在客户端环境变量/配置与签发时刻；服务端只存 SHA-256 哈希。
+- ak 明文只出现在服务端签发响应和运行时；服务端保存 SHA-256 哈希及加密密文，含 ak 的客户端配置文件不得提交版本库。

 ### 5.2 Web 管理后台（四个页面）

- **用户与 Token 管理**：人员选自现有 `user` 表，**只列企业账号**（`enterprise_type` 0=企业内部 / 1=代理，历史 NULL 保留），物业账号（=2）不进列表——Token 是给能查代理商/客户数据的人用的；每人名下签发/禁用 token，展示 key 前缀、作用域、最后使用时间；选中人员展示其**数据权限归属**（权限组/isagent、所属代理、企业类型、可见范围说明，只读，便于排查"查不到数据"）。
+- **用户与 Token 管理**：人员选自现有 `user` 表，**只列企业账号**（`enterprise_type` 0=企业内部 / 1=代理，历史 NULL 保留），物业账号（=2）不进列表——Token 是给能查代理商/客户数据的人用的；每人名下签发/禁用 token，展示 key 前缀、作用域、最后使用时间；选中人员展示其**数据权限归属**（权限组/isagent、所属代理、企业类型、可见范围说明，只读，便于排查"查不到数据"）。**一作用域一 Token**：签发时选 N 个作用域生成 N 把 token（每把独立绑定单作用域，独立吊销/审计，明文逐把展示一次）；编辑存量 token 时作用域收敛为单选。
 - **工具管理**：工具列表来自服务端注册自动同步（工具名/分类/读写类型页面只读）；展示每个工具被哪些作用域引用；「停用」为全局紧急开关。分类（category）在代码注册时由开发者声明（工具的业务域归属是客观属性，不允许页面上修改，避免与代码漂移）。
 - **作用域管理**：作用域 CRUD + 勾选工具（工具按 category 分组展示）。
 - **审计日志**：按人/token/工具/时间筛选。
@@ -140,9 +144,21 @@ xq CLI ─────┘  (Go 单二进制, 同为 MCP 客户端)   ┌──
 - **命令规范**：从工具名派生，不手工维护——`warehouse.stock.query` → `xq warehouse stock query --warehouse-id 7`；参数与 help 从 `tools/list` 的 schema 生成。
 - **输出约定**：stdout 恒为 JSON（`--pretty` 给人看）；错误统一 `{"error":{code,message}}` 且 exit code 非 0；`--schema` 吐入参 JSON Schema 供 agent 自发现。
 - **探测命令**：`xq whoami`（ak 归属的人 + 作用域，兼作连通性自检）、`xq tools`（列出本 ak 可用工具）。
- **配置**：`~/.xq/config.yaml` 存 base-url 与多环境 profile（`--env dev|test|prd`）；**ak 不落配置文件**，走 `XQ_API_KEY` 环境变量，与 Kimi 的 `bearerTokenEnvVar` 约定一致。
+- **配置**：`~/.xq/config.yaml` 存 base-url、多环境 profile（`--env dev|test|prd`）与 ak 明文（本机文件，权限 600），与 mcp.json 明文直写同一风格。
 - **服务端配套改动**（仅两点）：审计表加 `client_type`（mcp-kimi / mcp-claude / cli，从请求头识别）；错误消息面向"人和 agent 都可读"（如权限拒绝时提示应由管理员在哪个作用域开通）。

+### 5.4 Open API（服务间接口）
+
+供其他业务系统/智能体平台在服务端到服务端场景下获取用户 Token，路径 `/api/open/**`，与 ak 体系、后台 session 体系完全分离。
+
+- **鉴权**：静态服务间密钥，header `X-Open-Key`，配置项 `app.open.api-key`（dev 明文写 `application-dev.yml`；配置为空 = 接口关闭）。常量时间比较防时序侧信道。
+- **`POST /api/open/token/ensure`**（get-or-create）：
+  - 入参：`mobile`、`email`（至少一个，手机号优先）、`scopeCode`（作用域编码，必填）。
+  - 人员只认企业账号（`enterprise_type` 0/1，NULL 保留，与后台用户列表同口径）；查不到 → 404。
+- 该人员在该作用域下**已存在**有效 Token（正常且未过期）→ `created=false`，只回 `keyPrefix`/`expireTime` 等元信息，明文不回传。
+  - **不存在** → 自动创建永久 Token（一作用域一 Token，memo 标记 `open-api 自动签发`），`created=true` 返回明文，仅此一次。
+  - 全程写 `audit_log`（`tool_name=open.token.ensure`，`client_type=open-api`，参数摘要脱敏）。
+
 ## 6. 技术栈与工程结构

 - **JDK 17 + Spring Boot 3.x**（Spring AI MCP starter 的硬性要求）
@@ -223,6 +239,9 @@ xiaoqu-agent-service/
 - CLI 复用 `/mcp` 端点做 MCP 客户端，不开第二套服务 → 权限逻辑只有一份；Go 单二进制分发，与服务端 Java 栈解耦
 - 不依赖老 jar，Entity 自行生成 → 与老系统零代码依赖
 - 前后端一体打包单 jar → 可逆决定，将来可拆
+- 一作用域一 Token（2026-09-04）→ 收回某能力不需整把吊销；数据模型不变（token_scope 每把只写一行）
+- 长期 Token 仅按用户首次创建返回明文一次；后续复用元信息，不对外提供二次获取明文接口（服务端仅用于禁用/审计与治理）
+- Open API 鉴权用配置文件静态密钥（dev）→ 服务间调用方少，落库+轮换留给生产阶段
 - 列表类接口一律服务端分页，pageSize/rows 上限 100（超出截断为 100）→ 防止一次性拉全表，MCP 工具与后台 API 同一尺度

 ## 11. 开发环境（dev）
@@ -237,7 +256,7 @@ xiaoqu-agent-service/
 | Redis | 192.168.1.181:6379 | 密码见 pom dev | db5（`entity:User:{id}`、Dictionary）、db13 |
 | ES | 192.168.1.152:9200 | 无认证 | 预留，一期不用 |

- 密码等敏感值不入库本文档，以 `pom.xml` dev profile 为准；新系统 `application-dev.yml` 引用同名环境变量。
+- 密码等敏感值不入库本文档；dev 环境 DB/Redis 连接信息明文写在新系统 `application-dev.yml`（内网 dev 库，与 `pom.xml` dev profile 明文同一惯例）。
 - 自有库表（§7）建在同实例新 schema：dev 用 `xiaoqu_agent_svc_d`（沿用 `_d` 后缀约定），首次部署前手工建库。
 - 新系统与老的 dev 后端（Jetty 8091）可同时运行，互不干扰——注意两边连的是**同一套** dev 数据库和 Redis，老系统dev库的数据变动会同时影响两边的查询结果。

@@ -247,4 +266,3 @@ xiaoqu-agent-service/
 - 合并回 main 后用 `xiaoqu-agent-service/deploy/deploy.sh restart` 完成构建+重启，接口实测通过再 `git push`。
 - 后台列表页统一服务端分页（page 从 1 开始，pageSize 默认 20、上限 100）；MCP 工具 `rows` 同样上限 100，超出截断并在 `notice` 字段提示。
 - **新增/修改 MCP 工具必须同步更新 `doc/agent-mcp-tools-reference.md`**（入参、出参、权限语义、示例），工具对外契约以该文档为准。
-
@@ -8,8 +8,8 @@
 | 项 | 说明 |
 |---|---|
 | 端点 | `POST http://<host>:8088/mcp`（MCP Streamable HTTP） |
-| 认证 | Header `Authorization: Bearer xqak_xxx`，ak 在管理后台「用户与 Token」签发，服务端只存 SHA-256 |
-| 工具可见性 | 按 ak 绑定的作用域过滤，`tools/list` 只返回该 ak 可用的工具 |
+| 认证 | Header `Authorization: Bearer xqak_xxx`，Token 由管理后台或受信任 Open API 获取；服务端保存 SHA-256 及加密密文 |
+| 工具可见性 | `tools/list` 按 ak 作用域过滤，只返回该 ak 作用域并集内且启用状态的工具（2026-09-04 起，服务端 servlet 层重写响应实现）；`tools/call` 另有强制校验兜底，越权返回可读拒绝信息并落审计（denied） |
 | 行级数据权限 | 跟 ak 所属人走，照搬老系统 `getByIsAgent` 语义（见设计文档 §3.3），与作用域无关 |
 | 分页 | 列表类工具统一 `page`（从 1 开始，默认 1）、`rows`（默认 20，**上限 100**，超出截断为 100 并在返回 `notice` 字段提示） |
 | 分页出参 | 统一含 `total`（总数）、`page`、`rows`、`records`（本页记录）、`notice`（仅截断时出现） |
@@ -0,0 +1,302 @@
+# xiaoqu-ai 每用户 MCP Token 接入开发设计文档
+
+## 1. 需求概述
+
+### 1.1 需求信息
+
+| 项目 | 内容 |
+|---|---|
+| 需求标题 | xiaoqu-ai 每用户独立 MCP Token 接入 |
+| 优先级 | high |
+| 目标客户端 | xiaoqu-ai iOS ClawMobile |
+| 目标服务 | xiaoqu-agent-service `/mcp` |
+| 认证要求 | 每个登录用户使用自己的 MCP Token |
+| 预估工时 | 12-16h |
+
+### 1.2 成功标准
+
+- 用户 A 的 MCP 请求只能携带用户 A 的 Token，不能使用用户 B 或应用公共 Token。
+- 登录、刷新 Token、切换账号、退出登录后，Claw/MCP 会话不会串用旧用户凭证。
+- MCP 请求使用 `Authorization: Bearer <token>`，服务端继续执行用户、租户、作用域和审计校验。
+- Token 不出现在 prompt、工具参数、普通日志、崩溃信息或 Git 文件中。
+- 用户无 MCP Token、Token 过期、Token 被撤销时，客户端显示可恢复错误，不发送无凭证请求。
+
+### 1.3 明确不做
+
+- 不把一个固定 Token 写入 App、公共配置文件或所有用户共用。
+- 不把数据库中保存的 Token 哈希当作客户端 Token 返回；明文只在签发响应中出现一次。
+- 不让客户端提交任意 `user_id`、`tenant_id` 来冒充用户身份。
+
+## 2. 现状分析
+
+### 2.1 相关现有代码
+
+| 文件 | 层级 | 当前功能 | 改动类型 |
+|---|---|---|---|
+| `xiaoqu-ai/ios/Sources/XiaoquCRM/Core/Dependencies/ClawBridge.swift` | iOS 依赖 | 静态初始化 Claw 配置，并创建 MCP Server 列表 | 修改 |
+| `xiaoqu-ai/claw-code-parity/rust/crates/claw-mobile/src/ffi.rs` | Rust FFI | 接收 MCP 配置，连接、发现工具、调用工具 | 修改 |
+| `xiaoqu-ai/claw-code-parity/rust/crates/claw-mobile/src/mcp_http.rs` | Rust HTTP | JSON-RPC HTTP/SSE MCP 客户端 | 修改 |
+| `xiaoqu-agent-service/src/main/java/me/iiv/agent/security/AkAuthFilter.java` | 服务鉴权 | 仅解析 `Authorization: Bearer <ak>` | 保持兼容 |
+| `xiaoqu-agent-service/src/main/java/me/iiv/agent/security/AuthService.java` | 服务鉴权 | AK SHA-256 哈希查询、用户加载、过期检查 | 修改/复用 |
+| `xiaoqu-agent-service/src/main/java/me/iiv/agent/admin/AdminTokenService.java` | 服务 Token | 管理员为指定用户签发 AK，明文只返回一次 | 扩展复用 |
+
+### 2.2 当前缺口
+
+1. `ClawBridge.liveValue` 是静态值，Token 只在进程初始化时读取一次。
+2. 当前 FFI 将 `apiKey` 发送为 `X-API-Key`，与服务端要求的 Bearer 不一致。
+3. iOS FFI 未把配置文件中的 MCP Server 自动接入 `FfiEngineConfig`。
+4. 多 MCP Client 共存时，工具调用没有稳定的“工具名 → 所属 Server”映射。
+5. ~~当前管理端签发接口需要管理员会话，不适合作为普通用户登录后的自动取 Token 接口。~~ **已解决（2026-09-04）**：xiaoqu-agent-service 已交付 Open API `POST /api/open/token/ensure`（get-or-create，服务间密钥鉴权），见 §4.1。
+
+## 3. 方案设计
+
+### 3.1 认证模型
+
+采用两级凭证：
+
+1. xiaoqu-ai 登录 `accessToken`：证明当前用户登录身份，只用于向业务后端换取 MCP Token。
+2. MCP Token（`xqak_*`）：绑定 `user_id`，受 MCP scope、租户/行级权限、过期时间和撤销状态约束，只用于 `/mcp`。
+
+客户端不得把 `accessToken` 和 MCP Token 混为一谈。MCP 服务仍只接受 MCP Token。
+
+### 3.2 Token 生命周期
+
+| 场景 | 行为 |
+|---|---|
+| 登录成功 | 用当前用户登录态换取 MCP Token，按用户保存 |
+| MCP Token 过期/401 | 清除当前用户 MCP Token，重新换取一次；同一请求不自动重放工具副作用 |
+| accessToken 刷新 | 保留 MCP Token；若服务返回 401，再重新换取 |
+| 切换账号 | 先断开旧 MCP Client，再加载新账号 Token 并建立新 Client |
+| 退出登录 | 销毁旧 Claw/MCP Client，删除当前账号本地 MCP Token；当前永久 Token 以服务端状态为准，不做客户端侧远程失效调用 |
+| 多账号 | Keychain key 必须包含稳定用户 ID，禁止所有账号共用 `mcpToken` |
+
+~~建议 MCP Token 默认有效期 15 分钟，并提供换取接口；长期 AK 仅用于受控开发/管理场景。~~
+
+**2026-09-04 更新（与已交付实现对齐）**：现行模型为**长期有效 + 禁用回收**（与管理后台签发模型一致），不做 15 分钟短周期。`ensure` 语义天然兼容短周期模式（过期 token 不计入"已存在"，会触发新建并返回新明文），将来如需缩短有效期，只调整签发时的 `expireTime`，协议不变。
+
+## 4. API 契约
+
+> **2026-09-04 更新**：本节按 xiaoqu-agent-service 已交付的 Open API 重写。核心变化——agent-service 不直接验证 xiaoqu-ai 登录态（它没有 JWT 基础设施，也不懂租户），改为**两段式**：iOS 用登录态调 xiaoqu-ai 业务后端；业务后端拿着登录用户的手机号/邮箱，用服务间密钥调 agent-service 的 `ensure` 接口取 MCP Token。
+
+### 4.1 服务端原语（已交付）：POST `/api/open/token/ensure`
+
+描述: 按 手机号/邮箱 + 作用域编码 确保用户有有效 MCP Token（get-or-create）。
+
+认证:
+
+- `X-Open-Key: <服务间静态密钥>`（dev 配置在 `application-dev.yml` 的 `app.open.api-key`，生产走环境变量；配置为空 = 接口关闭）。
+- 只允许 xiaoqu-ai 业务后端等服务端调用方持有，**不得下发到 App**。
+
+请求体:
+
+- `mobile`: string — 登录用户手机号；与 `email` 至少传一个，手机号优先。
+- `email`: string — 登录用户邮箱。
+- `scopeCode`: string (required) — 作用域编码（如 `operation`）；iOS 用哪个作用域由双方约定后在此固定。
+
+响应 200:
+
+- `created`: bool — 本次是否新建。
+- `token`: string | null — **仅 `created=true` 时返回明文，且只出现这一次**；`created=false` 时恒为 null。
+- `keyPrefix`: string — Token 前缀（如 `xqak_abcd1234`），用于标识和对账。
+- `expireTime`: datetime | null — 现行为 null（永久，靠禁用回收）。
+- `userId` / `userName` / `scopeCode`: 归属信息。
+
+错误（统一 `{"message": "原因"}`）:
+
+- `400`: 参数缺失 / 作用域不存在或已停用。
+- `401`: `X-Open-Key` 无效。
+- `403`: Open API 未启用（服务端未配置密钥）。
+- `404`: 人员不存在或非企业账号（只认 `enterprise_type` 0/1 的企业账号）。
+
+服务端处理（已实现）:
+
+- 复用 `agent_api_key` 哈希存储与 `token_scope` 绑定；一作用域一 Token。
+- 已存在有效 Token（正常且未过期）只回元信息——**明文不可回吐，服务端只存 SHA-256**。
+- 不存在则自动创建永久 Token，memo 标记 `open-api 自动签发（<scopeCode>）`。
+- 全程写 `audit_log`（`tool_name=open.token.ensure`、`client_type=open-api`，手机号/邮箱脱敏，不记录 Token）。
+
+**身份约束**：业务后端不得接受客户端或模型传入的 `user_id`、`mobile`、`email` 作为身份依据。必须先从已验证的 xiaoqu-ai `accessToken` 会话解析用户，再由业务后端查询该用户的手机号/邮箱并调用 `ensure`。`X-Open-Key` 只允许服务端保管。
+
+### 4.1b xiaoqu-ai 业务后端门面（待 xiaoqu-ai 侧实现）
+
+iOS 面向的接口（建议沿用原设计）：POST `/api/v1/mcp/session-token`，`Authorization: Bearer <xiaoqu-access-token>`。业务后端从登录态解析用户 → 服务端查询手机号/邮箱 → 调 `ensure` → 返回 `{token, expires_at, user_id}`。不得使用请求体中的 `user_id/mobile/email` 覆盖登录态身份；客户端身份字段（client、device_id）由业务后端自行记录，agent-service 不感知。
+
+### 4.2 POST `/mcp`
+
+描述: MCP Streamable HTTP JSON-RPC 端点，现有接口保持不变。
+
+请求 Header:
+
+- `Authorization: Bearer <mcp-token>` (required)
+- `Content-Type: application/json` (required)
+- `Accept: application/json, text/event-stream` (required)
+- `Mcp-Session-Id: <id>` (required after initialize response contains it)
+
+请求/响应:
+
+- 保持 MCP `initialize` → `notifications/initialized` → `tools/list` → `tools/call` 顺序。
+- `tools/call` 必须继续执行 Token 作用域、用户和租户数据范围校验。
+
+错误:
+
+- `401`: MCP Token 缺失、无效、撤销或过期。
+- `200` + MCP `isError=true`: Token 有效但无权调用该工具，客户端展示权限错误，不切换账号重试。
+
+### 4.3 客户端配置文件
+
+配置文件只保存非用户敏感配置：
+
+```json
+{
+  "mcpServers": {
+    "xiaoqu": {
+      "type": "http",
+      "url": "http://<host>:8088/mcp"
+    }
+  }
+}
+```
+
+Token 不写入该文件。客户端运行时读取当前用户 Token，并动态加入 `Authorization` Header。
+
+## 5. 客户端实现设计
+
+### 5.1 ClawBridge
+
+- 将 `ClawBridge` 从静态全局凭证改为按当前用户创建的实例。
+- `connectMcp(userID, mcpToken)` 创建只属于当前用户的 FFI Engine。
+- `disconnectMcp()` 在切换账号、退出登录和重新换 Token 前调用。
+- 不在 `liveValue` 捕获 `accessToken` 或 MCP Token；通过依赖注入传入当前账号凭证。
+
+### 5.2 FFI / HTTP
+
+- `FfiMcpServerConfig` 增加明确的认证模式，或直接将 `apiKey` 改为 `bearerToken`。
+- 使用 `Authorization: Bearer <mcpToken>`，禁止发送 `X-API-Key`。
+- `initialize` 后保存 `Mcp-Session-Id`，发送 `notifications/initialized`，再调用 `tools/list`。
+- 工具发现时保存 `tool_name → server_name` 映射；调用只发送到所属 Server，不按 Client 顺序盲试。
+- Token 过期只触发一次重新换取和重新连接；并发请求共享刷新锁，避免同一用户并发签发多个 Token。
+
+### 5.3 Keychain
+
+- Key 名：`mcpToken.<user_id>`，值为 MCP Token；使用 ThisDeviceOnly 存储。
+- `device_id` 单独生成并持久化，不从 Token 派生。
+- 日志只记录 Token 是否存在、剩余有效期和用户 ID，不记录 Token 内容。
+
+## 6. 数据模型变更
+
+### 6.1 现有表复用
+
+| 表 | 用途 | 变更 |
+|---|---|---|
+| `agent_api_key` | MCP Token 哈希、用户绑定、状态、过期时间 | 复用；确认 `user_id/status/expire_time/key_hash` 索引 |
+| `token_scope` | Token 与作用域绑定 | 复用 |
+| `audit_log` | MCP 调用和 Token 生命周期审计 | 扩展事件类型/元数据（若当前字段不足） |
+
+### 6.2 建议新增字段（仅在现有字段不足时）
+
+> 2026-09-04 注：已交付实现暂不新增字段——ensure 自动签发的 Token 用 `memo` 标记（`open-api 自动签发（<scopeCode>）`），`create_id=0` 表示系统签发。若后续需要按来源/设备撤销或统计，再按下表加独立 migration。
+
+| 表 | 字段 | 类型/约束 | 说明 |
+|---|---|---|---|
+| `agent_api_key` | `source` | `VARCHAR(32) NOT NULL DEFAULT 'admin'` | `admin` / `user_session`，便于撤销和审计 |
+| `agent_api_key` | `device_id` | `VARCHAR(128) NULL` | 用户会话 Token 的设备绑定 |
+
+索引：`(user_id, source, status, expire_time)`。新增字段必须通过新的 Flyway migration，禁止修改已执行 migration。
+
+## 7. 变更文件清单
+
+### xiaoqu-agent-service
+
+| 文件/目录 | 层级 | 类型 | 改动说明 |
+|---|---|---|---|
+| ~~`security/` JWT 验证组件~~ | Security | ~~新增~~ 取消 | agent-service 不验证 xiaoqu-ai 登录态，改由业务后端两段式调用 |
+| `open/OpenTokenController.java` 等 | Open API | **ensure 已交付** | `ensure` 使用 X-Open-Key 鉴权 |
+| `open/OpenKeyFilter.java` | Filter | **已交付** | 服务间静态密钥，常量时间比较，配置为空即关闭 |
+| `admin/AdminTokenService.java` | Service | **ensure 已交付；密文保存待实现** | 一作用域一 Token；签发时保存哈希和加密密文 |
+| `common/GlobalExceptionHandler.java` | Handler | **已交付** | 错误统一 `{"message": ...}` |
+| `security/AkAuthFilter.java` | Filter | 保持兼容 | `/mcp` Bearer ak 校验不变 |
+| `src/test/...open` | Test | **部分已交付** | 覆盖 ensure 的参数、已存在/新建/404/停用/缺参测试 |
+
+### xiaoqu-ai
+
+| 文件/目录 | 层级 | 类型 | 改动说明 |
+|---|---|---|---|
+| `ios/.../ClawBridge.swift` | iOS | 修改 | 按登录用户注入 Token，重建/销毁 Claw 实例 |
+| `claw-mobile/src/ffi.rs` | Rust FFI | 修改 | Bearer Header、会话通知、Server 路由映射 |
+| `claw-mobile/src/mcp_http.rs` | Rust HTTP | 修改 | 通用 Header、Session ID 和 JSON-RPC 初始化流程 |
+| `ios/.../KeychainClient.swift` | iOS 存储 | 修改 | 账号隔离的 MCP Token 存取和删除 |
+| `ios/.../AuthFeature.swift` | 登录生命周期 | 修改 | 登录/刷新/切换/退出触发 MCP 凭证生命周期 |
+| `ios/Tests/...` | Test | 新增 | 用户切换、401 刷新、Token 不串号测试 |
+| `claw-code-parity/.../settings*.json` | 配置 | 修改 | 仅保存 URL，不保存用户 Token |
+
+## 8. 开发任务拆分
+
+| # | 任务标题 | 工时 | 依赖 | 完成标准 |
+|---|---|---:|---|---|
+| 1 | ~~服务端确认 JWT 与租户映射、Token exchange 契约~~ → xiaoqu-ai 业务后端实现门面接口（登录态 → ensure） | 2h | - | 门面 401/403 语义确定；明文按 user_id 加密落库 |
+| 2 | ~~服务端实现用户 MCP Token 签发与审计~~ **已交付**（ensure + 审计，2026-09-04） | - | - | 已上线并实测幂等/脱敏/错误语义 |
+| 2b | ~~服务端增加二次获取能力~~ | - | - | 已按当前边界关闭，不再新增接口 |
+| 3 | iOS Keychain 账号隔离和认证生命周期接入 | 3h | #1 | 登录/切换/退出无旧 Token 残留 |
+| 4 | Rust MCP HTTP Bearer、Session、初始化通知 | 3h | #3 | initialize/list/call 真实握手成功 |
+| 5 | MCP 工具到 Server 路由映射 | 2h | #4 | 多 Server 下工具调用不发错目标 |
+| 6 | 集成与安全回归测试 | 2-4h | #2-#5 | 用户隔离、401 刷新、权限拒绝和日志脱敏通过 |
+
+实施顺序：#1 → #2；#3 与 #4 可并行；完成后 #5 → #6。
+
+## 9. 测试与验收
+
+### 9.1 服务端
+
+- 用户 A Token 调用 `tools/list` / `tools/call` 成功，审计 `user_id=A`。
+- 用户 B Token 调用时只能看到/调用 B 作用域允许的数据。
+- A 的 Token 调用不存在或已撤销 Token 返回 401；A 的 Token 调 B 身份参数不得改变审计身份。
+- A 无某工具 scope 时返回 MCP `isError=true`，不得执行 Handler。
+- 签发响应后数据库和日志中搜索不到 Token 明文。
+
+### 9.2 iOS
+
+- A 登录后抓包确认所有 MCP 请求为 `Authorization: Bearer <A-MCP-Token>`。
+- 切换 B 后，旧连接关闭，后续请求只携带 B Token。
+- A Token 401 时只刷新 A 的 Token，不影响 B 或其他账号。
+- 退出后旧 Claw 不再产生网络请求。
+- 配置文件、prompt、工具参数和日志不包含 Token。
+
+### 9.3 联调命令
+
+```bash
+# 业务后端侧：用服务间密钥 ensure 用户 MCP Token（示例，密钥与明文不写入仓库）
+curl -X POST http://<host>:8088/api/open/token/ensure \
+  -H 'X-Open-Key: <服务间密钥>' \
+  -H 'Content-Type: application/json' \
+  -d '{"mobile":"<登录用户手机号>","scopeCode":"operation"}'
+
+# iOS 侧：走 xiaoqu-ai 业务后门门面（待实现）
+curl -X POST http://<xiaoqu-ai-host>/api/v1/mcp/session-token \
+  -H 'Authorization: Bearer <xiaoqu-access-token>' \
+  -H 'Content-Type: application/json' \
+  -d '{"client":"xiaoqu-ai-ios","device_id":"<device-id>"}'
+
+# 使用返回的用户 MCP Token 完成 MCP 握手
+curl -X POST http://<host>:8088/mcp \
+  -H 'Authorization: Bearer <user-mcp-token>' \
+  -H 'Content-Type: application/json' \
+  -H 'Accept: application/json, text/event-stream' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"xiaoqu-ai","version":"1.0"}}}'
+```
+
+## 10. 技术风险与回退
+
+| 风险 | 等级 | 应对 |
+|---|---|---|
+| accessToken 与 MCP AK 类型混用 | 高 | 强制 Token exchange；服务端只接受明确的 MCP AK |
+| 静态 Claw 实例持有旧用户 Token | 高 | 用户切换/退出先销毁实例，增加生命周期测试 |
+| 多 MCP Server 工具路由错误 | 高 | 建立工具归属映射，不采用首个 Client 试调用 |
+| Token 泄露到日志/崩溃 | 高 | 脱敏中间件、禁止打印 Header、静态扫描和测试 |
+| Token exchange 不可用 | 中 | MCP 功能降级为不可用并提示重试；不得使用公共 Token 兜底 |
+| 新字段迁移失败 | 中 | 字段变更独立 Flyway migration；回滚只撤销新增字段/索引 |
+
+回退策略：保留现有管理员签发 Token 和 `/mcp` 协议不变；先关闭用户自动换取入口，客户端显示 MCP 不可用。禁止回退到全局共享 Token。
+
+## 11. 设计结论
+
+公共 MCP 配置文件只负责“连哪个服务”；用户 Token 由登录用户上下文动态决定。实现完成后，xiaoqu-ai 的每个用户拥有独立 MCP 权限边界，服务端仍能按用户、租户、作用域和审计链路追踪调用。
@@ -0,0 +1,147 @@
+# xiaoqu-operations-ai 接入 xiaoqu-mcp 开发设置
+
+## 1. 目标
+
+让 `ops-assistant-service` 通过服务端 MCP Client 调用
+`xiaoqu_mcp_service`，保持现有：
+
+```text
+Router → Planner → Executor → Answer
+```
+
+每次调用使用当前已验证用户对应的 MCP Token，不把 MCP Token 放进提示词、Planner 输出、工具参数或普通日志。
+
+## 2. 当前代码结论
+
+- `ops-assistant-service` 是 FastAPI + Python 3.12 服务。
+- 当前依赖中没有 MCP SDK，也没有 `tools/list` / `tools/call` 客户端。
+- `Executor` 目前直接调用本地 capability：`customer_issues.*`、`smartclean.query`。
+- 用户身份来自 Gateway JWT，并通过 `ops_identity_mappings` 解析租户、用户和 `scope_tags`。
+- 当前最合适的接入点是 Executor 的工具适配层，不新增第二套编排器。
+
+## 3. xiaoqu-mcp 服务契约
+
+### 3.1 MCP 调用
+
+- 地址：`POST <XQ_MCP_URL>/mcp`
+- 认证：`Authorization: Bearer <xqak-token>`
+- 初始化顺序：`initialize` → `notifications/initialized` → `tools/list` → `tools/call`
+- 初始化后保存 `Mcp-Session-Id`。
+- `tools/list` 已按 Token scope 过滤，`tools/call` 仍由服务端再次鉴权。
+
+### 3.2 Token 初始化
+
+服务间调用：`POST <XQ_MCP_URL>/api/open/token/ensure`
+
+```http
+X-Open-Key: <server-only-key>
+Content-Type: application/json
+```
+
+请求体包含 `mobile` 或 `email`，以及固定的 `scopeCode`（首期建议 `operation`）。
+
+约束：
+
+- `X-Open-Key` 只能配置在受信任后端，不能下发 App。
+- 业务后端必须从已验证用户会话查询手机号/邮箱，不能信任客户端或模型传入的身份字段。
+- 首次创建返回 Token 明文；xiaoqu-mcp 同时保存 SHA-256 哈希和 KMS/独立密钥加密密文。
+- 已存在 Token 不回传明文，重复调用返回元信息并复用。
+- Token 密文缺失或解密失败必须报错；不得回退到哈希值或公共 Token。
+
+## 4. 推荐实现
+
+### 4.1 配置
+
+在 `config.py` 增加以下 `OPS_ASSISTANT_` 配置：
+
+| 变量 | 默认值 | 说明 |
+|---|---|---|
+| `XQ_MCP_ENABLED` | `false` | 是否启用 MCP capability |
+| `XQ_MCP_URL` | unset | 例如 `http://xiaoqu-mcp:8088`，只存地址，不存用户 Token |
+| `XQ_MCP_OPEN_KEY` | unset | 仅用于服务端 Token 初始化，使用 `SecretStr` |
+| `XQ_MCP_SCOPE_CODE` | `operation` | 固定作用域，禁止由 Planner 或客户端选择 |
+| `XQ_MCP_TIMEOUT_SECONDS` | `10` | MCP 请求超时 |
+
+启用时必须同时提供 URL、Open Key 和 scope；生产环境禁止明文写入仓库。
+
+### 4.2 新增最小模块
+
+建议只增加两个模块：
+
+- `src/ops_assistant_service/mcp_client.py`
+  - 管理 HTTP 请求、JSON-RPC、Session ID、Bearer Header、超时和错误映射。
+  - 进程内按 `user_id` 缓存 MCP Session；账号或 Token 变化时销毁。
+- `src/ops_assistant_service/mcp_token_provider.py`
+  - 接收已验证的 `SharedIdentity`。
+  - 从受信任用户资料源取得 mobile/email。
+- 调用 `ensure`，首次签发返回明文；后续直接复用本地持久化 token。
+  - 不接受 `user_id/mobile/email` 作为客户端覆盖参数。
+
+不引入通用 MCP 框架、第二个 Agent 或数据库直连；现有 `httpx` 已足够完成首期只读接入。
+
+### 4.3 Capability 映射
+
+在 `capability_registry.py` 增加固定的本地 capability，禁止把远端 `tools/list` 原样暴露给 Planner：
+
+| 本地 capability | MCP 工具 | 首期权限 |
+|---|---|---|
+| `xiaoqu.agent_count` | `agent.count` | read |
+| `xiaoqu.agent_list` | `agent.list.query` | read |
+| `xiaoqu.property_list` | `property.list.query` | read |
+
+Planner 只能选择注册表中的名称和 schema。Executor 在调用前同时检查：
+
+```text
+应用允许 ∩ 用户 scope_tags ∩ 租户/数据范围
+```
+
+远端返回结果先经过字段白名单投影，再交给 Answer；Token、原始 Header 和未授权字段不得进入 trace。
+
+### 4.4 Executor 接入点
+
+在 `executor.py` 增加一个只读分支：
+
+```text
+validate_tool_input
+  → 校验本地 capability 和参数白名单
+  → 读取 SharedIdentity / DataScope
+  → 获取当前用户 MCP Token
+  → MCP tools/call
+  → 结果投影
+  → 现有 execution_trace / Answer 链路
+```
+
+现有 `customer_issues.*` 和 `smartclean.query` 保持不变。MCP 不可用时返回稳定的 `TOOL_UNAVAILABLE`，不得回退到公共 Token 或直接访问 xiaoqu-mcp 数据库。
+
+## 5. 生命周期与安全
+
+- 登录用户变化：先关闭旧 Session，再建立新用户 Session。
+- MCP 返回 401：清理当前用户 Token，最多执行一次重新获取和重连；不自动重放副作用请求。
+- 退出登录：清理本地/会话 Token 缓存；如需远端立即失效，走服务端管理端吊销能力。
+- 日志只记录用户 ID、工具名、scope 和错误码，不记录 Token、Authorization Header 或手机号/邮箱明文。
+- `tools/list` 仅用于校验远端能力；真正可调用集合以本地 allowlist 为准。
+
+## 6. 开发顺序
+
+1. 先在 xiaoqu-ai 业务后端完成登录态到 `ensure` 的门面，并验证 Token 明文加密落库。
+2. 增加 `Settings` 配置和启动校验。
+3. 实现 `mcp_token_provider.py` 和 `mcp_client.py`，补充 JSON-RPC/Session 单元测试。
+4. 增加 3 个只读 capability，并接入 Executor。
+5. 增加用户隔离、scope 拒绝、401 重连、Token 脱敏和 MCP 不可用测试。
+6. 先在 development/test 环境启用，完成联调后再进入 staging。
+
+## 7. 验收标准
+
+- 用户 A 的请求始终使用 A 的 MCP Token，用户 B 不能复用。
+- A 无对应 scope 时，Planner/Executor 均不能调用该 MCP 工具。
+- `tools/list`、`tools/call` 使用同一用户 Session 和 Bearer Token。
+- 切换用户后旧 Session 不再发出请求。
+- MCP 401 只刷新当前用户，且同一请求不重复执行副作用。
+- 测试、日志、trace、配置文件和 Git 历史中均无 Token 明文。
+
+## 8. 当前不做
+
+- 不把 MCP Client 放进 iOS/Android 端。
+- 不把全部远程工具动态注册给 Planner。
+- 不复制 xiaoqu-mcp 数据库或绕过 MCP 权限。
+- 不在本次首期引入写工具；写工具需另行设计审批、幂等和补偿协议。
@@ -26,8 +26,8 @@ const audits = ref([])
 const toolFilter = reactive({ category: '', kind: '', keyword: '' })
 const auditFilter = reactive({ person: '', tokenPrefix: '', tool: '', result: '', client: '', from: '', to: '' })
 const tokenDialog = ref(false)
-const tokenForm = reactive({ id: null, memo: '', scopeIds: [], expireTime: null })
-const issuedPlaintext = ref('')
+const tokenForm = reactive({ id: null, memo: '', scopeIds: [], scopeId: null, expireTime: null })
+const issuedTokens = ref([])
 const scopeDialog = ref(false)
 const scopeForm = reactive({ id: null, name: '', code: '', memo: '' })
 const scopeToolsDialog = ref(false)
@@ -106,24 +106,26 @@ async function selectUser(user) {

 function openToken(token = null) {
  Object.assign(tokenForm, token ? {
-    id: token.id, memo: token.memo || '', scopeIds: [...token.scopeIds], expireTime: token.expireTime || null,
-  } : { id: null, memo: '', scopeIds: [], expireTime: null })
+    id: token.id, memo: token.memo || '', scopeIds: [], scopeId: token.scopeIds[0] ?? null,
+    expireTime: token.expireTime || null,
+  } : { id: null, memo: '', scopeIds: [], scopeId: null, expireTime: null })
  tokenDialog.value = true
 }

 async function saveToken() {
-  if (!tokenForm.scopeIds.length) return ElMessage.warning('至少选择一个作用域')
+  const scopeIds = tokenForm.id ? (tokenForm.scopeId ? [tokenForm.scopeId] : []) : tokenForm.scopeIds
+  if (!scopeIds.length) return ElMessage.warning('至少选择一个作用域')
  await run(async () => {
-    const body = JSON.stringify({ memo: tokenForm.memo, scopeIds: tokenForm.scopeIds, expireTime: tokenForm.expireTime })
+    const body = JSON.stringify({ memo: tokenForm.memo, scopeIds, expireTime: tokenForm.expireTime })
    if (tokenForm.id) await api(`/tokens/${tokenForm.id}`, { method: 'PUT', body })
    else {
-      const issued = await api(`/users/${selectedUser.value.id}/tokens`, { method: 'POST', body })
-      issuedPlaintext.value = issued.plaintext
+      // 一作用域一 Token：选 N 个作用域返回 N 把明文
+      issuedTokens.value = await api(`/users/${selectedUser.value.id}/tokens`, { method: 'POST', body })
    }
    tokenDialog.value = false
    tokens.value = await api(`/users/${selectedUser.value.id}/tokens`)
    await loadUsers()
-    ElMessage.success(tokenForm.id ? 'Token 已更新' : 'Token 已签发')
+    ElMessage.success(tokenForm.id ? 'Token 已更新' : `已签发 ${issuedTokens.value.length} 把 Token`)
  }).catch(() => {})
 }

@@ -206,7 +208,10 @@ async function loadAudit() { audits.value = await api(`/audit${qs(auditFilter)}`
 function date(value) { return value ? new Date(value).toLocaleString('zh-CN', { hour12: false }) : '—' }
 function expiry(value) { return value ? date(value) : '永久' }
 function enterprise(value) { return ({ 1: '代理', 2: '物业' })[value] || `类型 ${value ?? '未配置'}` }
-async function copyToken() { await navigator.clipboard.writeText(issuedPlaintext.value); ElMessage.success('已复制') }
+async function copyText(value) { await navigator.clipboard.writeText(value); ElMessage.success('已复制') }
+async function copyAllTokens() {
+  await copyText(issuedTokens.value.map(item => `${item.token.scopeNames.join('/')}: ${item.plaintext}`).join('\n'))
+}

 onMounted(async () => {
  try {
@@ -388,7 +393,15 @@ onMounted(async () => {
    <el-form label-width="88px">
      <el-form-item label="所属人员"><strong>{{ selectedUser?.name }}</strong></el-form-item>
      <el-form-item label="用途备注"><el-input v-model="tokenForm.memo" maxlength="255" placeholder="如：Kimi 桌面用" aria-label="Token 用途备注" data-testid="admin-token-memo" /></el-form-item>
-      <el-form-item label="作用域"><el-checkbox-group v-model="tokenForm.scopeIds" data-testid="admin-token-scopes"><el-checkbox v-for="scope in scopes.filter(item => item.status === 1)" :key="scope.id" :value="scope.id">{{ scope.name }}</el-checkbox></el-checkbox-group></el-form-item>
+      <el-form-item label="作用域">
+        <el-radio-group v-if="tokenForm.id" v-model="tokenForm.scopeId" data-testid="admin-token-scopes">
+          <el-radio v-for="scope in scopes.filter(item => item.status === 1)" :key="scope.id" :value="scope.id">{{ scope.name }}</el-radio>
+        </el-radio-group>
+        <el-checkbox-group v-else v-model="tokenForm.scopeIds" data-testid="admin-token-scopes">
+          <el-checkbox v-for="scope in scopes.filter(item => item.status === 1)" :key="scope.id" :value="scope.id">{{ scope.name }}</el-checkbox>
+        </el-checkbox-group>
+        <div class="hint" style="margin:4px 0 0">{{ tokenForm.id ? '一把 Token 只绑一个作用域' : '一作用域一 Token：选几个作用域就签发几把' }}</div>
+      </el-form-item>
      <el-form-item label="过期时间"><el-date-picker v-model="tokenForm.expireTime" type="datetime" value-format="YYYY-MM-DDTHH:mm:ssZ" placeholder="留空为永久" aria-label="Token 过期时间" data-testid="admin-token-expiry" /></el-form-item>
    </el-form>
    <template #footer><el-button data-testid="admin-token-cancel" @click="tokenDialog = false">取消</el-button><el-button type="primary" data-testid="admin-token-save" @click="saveToken">确认</el-button></template>
@@ -410,9 +423,13 @@ onMounted(async () => {
    <template #footer><el-button data-testid="admin-scope-tools-cancel" @click="scopeToolsDialog = false">取消</el-button><el-button type="primary" data-testid="admin-scope-tools-save" @click="saveScopeTools">保存配置</el-button></template>
  </el-dialog>

-  <el-dialog :model-value="!!issuedPlaintext" title="Token 签发成功" width="560px" :close-on-click-modal="false" @close="issuedPlaintext = ''">
-    <el-alert title="明文只展示这一次，请立即复制并妥善保存。" type="warning" :closable="false" show-icon />
-    <code class="token-secret" data-testid="admin-issued-token">{{ issuedPlaintext }}</code>
-    <template #footer><el-button type="primary" data-testid="admin-copy-token" @click="copyToken">复制 Token</el-button><el-button data-testid="admin-close-token" @click="issuedPlaintext = ''">我已保存</el-button></template>
+  <el-dialog :model-value="!!issuedTokens.length" title="Token 签发成功" width="600px" :close-on-click-modal="false" @close="issuedTokens = []">
+    <el-alert title="每个作用域一把 Token，明文只展示这一次，请立即复制并妥善保存。" type="warning" :closable="false" show-icon />
+    <div v-for="item in issuedTokens" :key="item.token.id" class="issued-row">
+      <el-tag size="small" effect="plain">{{ item.token.scopeNames.join('/') }}</el-tag>
+      <code class="token-secret" :data-testid="`admin-issued-token-${item.token.id}`">{{ item.plaintext }}</code>
+      <el-button link type="primary" :data-testid="`admin-copy-token-${item.token.id}`" @click="copyText(item.plaintext)">复制</el-button>
+    </div>
+    <template #footer><el-button type="primary" data-testid="admin-copy-all-tokens" @click="copyAllTokens">全部复制</el-button><el-button data-testid="admin-close-token" @click="issuedTokens = []">我已保存</el-button></template>
  </el-dialog>
 </template>
@@ -60,4 +60,6 @@ code { font-family: Menlo, Consolas, monospace; font-size: 12px; }
 .tool-group .el-checkbox__label { display: flex; flex-direction: column; white-space: normal; }
 .tool-group small { margin-top: 3px; color: #909399; }
 .token-secret { display: block; margin-top: 14px; padding: 14px; word-break: break-all; border-radius: 4px; background: #f4f4f5; font-size: 13px; }
+.issued-row { display: flex; align-items: center; gap: 10px; margin-top: 12px; }
+.issued-row .token-secret { flex: 1; margin-top: 0; padding: 9px 12px; }
@media (max-width: 1200px) { .token-layout { grid-template-columns: 300px minmax(640px, 1fr); } }
@@ -130,8 +130,8 @@ public class AdminConsoleController {
    }

    @PostMapping("/users/{id}/tokens")
-    public AdminTokenService.IssuedToken issue(@PathVariable Long id, @RequestBody TokenRequest body,
-                                                HttpSession session) {
+    public List<AdminTokenService.IssuedToken> issue(@PathVariable Long id, @RequestBody TokenRequest body,
+                                                     HttpSession session) {
        if (body == null) bad("请求内容不能为空");
        return tokenService.issue(id, body.memo(), body.scopeIds(), body.expireTime(), adminId(session));
    }
@@ -34,12 +34,23 @@ public class AdminTokenService {
        this.scopeMapper = scopeMapper;
    }

+    /**
+     * 签发 Token：一作用域一 Token。选 N 个作用域生成 N 把，每把独立绑定单个作用域，
+     * 便于独立吊销、独立审计，明文逐把返回（仅本次可见）。
+     */
    @Transactional(transactionManager = "svcTransactionManager")
-    public IssuedToken issue(Long userId, String memo, List<Long> scopeIds, Date expireTime, Long adminId) {
+    public List<IssuedToken> issue(Long userId, String memo, List<Long> scopeIds, Date expireTime, Long adminId) {
        User user = userMapper.selectById(userId);
        if (user == null || Integer.valueOf(1).equals(user.getSoftDelete())) bad("人员不存在");
        validateMemo(memo);
        validateScopes(scopeIds);
+        return scopeIds.stream().distinct()
+                .map(scopeId -> issueSingle(userId, memo, scopeId, expireTime, adminId))
+                .toList();
+    }
+
+    /** 签发一把绑定单个作用域的 Token；人员/作用域合法性由调用方保证。 */
+    public IssuedToken issueSingle(Long userId, String memo, Long scopeId, Date expireTime, Long creatorId) {
        String plaintext = "xqak_" + AdminAuthController.randomHex(24);
        AgentApiKey token = new AgentApiKey();
        token.setUserId(userId);
@@ -48,14 +59,32 @@ public class AdminTokenService {
        token.setMemo(trim(memo, 255));
        token.setStatus((byte) 1);
        token.setExpireTime(expireTime);
-        token.setCreateId(adminId);
-        token.setModifyId(adminId);
+        token.setCreateId(creatorId);
+        token.setModifyId(creatorId);
        token.setSoftDelete((byte) 0);
        tokenMapper.insert(token);
-        replaceScopes(token.getId(), scopeIds, adminId);
+        replaceScopes(token.getId(), List.of(scopeId), creatorId);
        return new IssuedToken(plaintext, view(token));
    }

+    /** 查找某人员在某作用域下的有效 Token（正常状态且未过期），取最新一把；无则 null。 */
+    public AgentApiKey findActiveToken(Long userId, Long scopeId) {
+        List<Long> tokenIds = relationMapper.selectList(new LambdaQueryWrapper<TokenScope>()
+                        .eq(TokenScope::getScopeId, scopeId).eq(TokenScope::getSoftDelete, 0))
+                .stream().map(TokenScope::getTokenId).toList();
+        if (tokenIds.isEmpty()) return null;
+        return tokenMapper.selectList(new LambdaQueryWrapper<AgentApiKey>()
+                        .in(AgentApiKey::getId, tokenIds)
+                        .eq(AgentApiKey::getUserId, userId)
+                        .eq(AgentApiKey::getStatus, 1)
+                        .eq(AgentApiKey::getSoftDelete, 0)
+                        .and(w -> w.isNull(AgentApiKey::getExpireTime)
+                                .or().gt(AgentApiKey::getExpireTime, new Date()))
+                        .orderByDesc(AgentApiKey::getCreateTime)
+                        .last("LIMIT 1"))
+                .stream().findFirst().orElse(null);
+    }
+
    @Transactional(transactionManager = "svcTransactionManager")
    public void update(Long tokenId, String memo, List<Long> scopeIds, Date expireTime, Long adminId) {
        AgentApiKey current = activeToken(tokenId);
@@ -66,7 +66,7 @@ public class AuditService {
    }

    /**
-     * client_type：X-Client-Type 头优先；否则 User-Agent 含 kimi→mcp-kimi，
+     * client_type：/api/open/** → open-api；X-Client-Type 头其次；否则 User-Agent 含 kimi→mcp-kimi，
     * 含 claude→mcp-claude，含 curl→cli，其余 unknown。
     */
    private static String clientType() {
@@ -74,6 +74,9 @@ public class AuditService {
        if (request == null) {
            return "unknown";
        }
+        if (request.getRequestURI() != null && request.getRequestURI().startsWith("/api/open/")) {
+            return "open-api";
+        }
        String explicit = request.getHeader("X-Client-Type");
        if (explicit != null && !explicit.isBlank()) {
            return explicit;
@@ -0,0 +1,24 @@
+package me.iiv.agent.common;
+
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.ExceptionHandler;
+import org.springframework.web.bind.annotation.RestControllerAdvice;
+import org.springframework.web.server.ResponseStatusException;
+
+import java.util.Map;
+
+/**
+ * 统一错误响应：业务校验抛出的 ResponseStatusException 一律返回 {"message": 原因}。
+ * 后台前端与 Open API 调用方（含 agent）都按 message 字段取错误说明；
+ * 未预期的异常不经过这里，避免内部细节外泄。
+ */
+@RestControllerAdvice
+public class GlobalExceptionHandler {
+
+    @ExceptionHandler(ResponseStatusException.class)
+    public ResponseEntity<Map<String, String>> handleStatus(ResponseStatusException error) {
+        String reason = error.getReason();
+        return ResponseEntity.status(error.getStatusCode())
+                .body(Map.of("message", reason == null || reason.isBlank() ? "请求失败" : reason));
+    }
+}
@@ -0,0 +1,77 @@
+package me.iiv.agent.mcp;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.node.ArrayNode;
+import com.fasterxml.jackson.databind.node.ObjectNode;
+
+import java.util.Set;
+
+/**
+ * tools/list 响应重写：把 SSE（或纯 JSON）响应里 result.tools 按 allowedToolNames 过滤。
+ * 纯函数，便于单测；逐行处理 SSE 的 data 负载，其余字节原样保留；
+ * 解析失败的行一律原样放行（不把链路搞坏）。
+ */
+public final class ToolsListResponseRewriter {
+
+    private static final ObjectMapper MAPPER = new ObjectMapper();
+
+    private ToolsListResponseRewriter() {
+    }
+
+    public static String rewrite(String body, Set<String> allowedToolNames) {
+        if (body == null || body.isBlank()) {
+            return body;
+        }
+        // 逐行处理：SSE 事件结构（id:/event:/空行）原样保留，只动 data: 负载行
+        String[] lines = body.split("\\n", -1);
+        for (int i = 0; i < lines.length; i++) {
+            String line = lines[i];
+            if (line.startsWith("data:")) {
+                lines[i] = rewriteDataLine(line, allowedToolNames);
+            } else if (i == 0 && line.startsWith("{")) {
+                // 非 SSE 的纯 JSON 响应
+                return rewriteDataLine(line, allowedToolNames);
+            }
+        }
+        return String.join("\n", lines);
+    }
+
+    private static String rewriteDataLine(String line, Set<String> allowedToolNames) {
+        boolean sse = line.startsWith("data:");
+        String payload = sse ? line.substring("data:".length()).stripLeading() : line;
+        try {
+            JsonNode node = MAPPER.readTree(payload);
+            if (!filterTools(node, allowedToolNames)) {
+                return line;
+            }
+            return (sse ? "data:" : "") + MAPPER.writeValueAsString(node);
+        } catch (Exception e) {
+            return line;
+        }
+    }
+
+    /** 若节点含 result.tools 数组则按白名单过滤，返回是否命中 tools 负载。 */
+    private static boolean filterTools(JsonNode node, Set<String> allowedToolNames) {
+        if (!(node instanceof ObjectNode object)) {
+            return false;
+        }
+        JsonNode result = object.get("result");
+        if (!(result instanceof ObjectNode resultObject)) {
+            return false;
+        }
+        JsonNode tools = resultObject.get("tools");
+        if (!(tools instanceof ArrayNode toolsArray)) {
+            return false;
+        }
+        ArrayNode filtered = MAPPER.createArrayNode();
+        for (JsonNode tool : toolsArray) {
+            JsonNode name = tool.get("name");
+            if (name != null && allowedToolNames.contains(name.asText())) {
+                filtered.add(tool);
+            }
+        }
+        resultObject.set("tools", filtered);
+        return true;
+    }
+}
@@ -0,0 +1,231 @@
+package me.iiv.agent.mcp;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import jakarta.servlet.FilterChain;
+import jakarta.servlet.ServletException;
+import jakarta.servlet.ServletInputStream;
+import jakarta.servlet.ServletOutputStream;
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletRequestWrapper;
+import jakarta.servlet.http.HttpServletResponse;
+import jakarta.servlet.http.HttpServletResponseWrapper;
+import me.iiv.agent.security.AuthContext;
+import me.iiv.agent.security.AuthContextHolder;
+import me.iiv.agent.security.ToolGuard;
+import org.springframework.core.annotation.Order;
+import org.springframework.stereotype.Component;
+import org.springframework.web.filter.OncePerRequestFilter;
+
+import java.io.BufferedReader;
+import java.io.ByteArrayInputStream;
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.io.InputStreamReader;
+import java.io.PrintWriter;
+import java.nio.charset.StandardCharsets;
+import java.util.Set;
+
+/**
+ * tools/list 按 token 作用域过滤（2026-09-04 决策：避免"看得到却调不了"的二义性）。
+ * MCP SDK 的工具清单在服务启动时静态注册，无法按请求过滤，故在 servlet 层拦截
+ * POST /mcp 中 method=tools/list 的响应，重写 result.tools 负载。
+ * tools/call 路径不变：越权调用仍走 GuardedToolCallback 的可读拒绝 + denied 审计。
+ * 仅拦截 POST（请求-响应式）；GET /mcp 的长连接 SSE 流不缓冲。
+ * 必须运行在 AkAuthFilter（@Order(10)）之后，才能拿到 AuthContext。
+ */
+@Component
+@Order(20)
+public class ToolsListScopeFilter extends OncePerRequestFilter {
+
+    private final ToolGuard toolGuard;
+    private final ObjectMapper objectMapper = new ObjectMapper();
+
+    public ToolsListScopeFilter(ToolGuard toolGuard) {
+        this.toolGuard = toolGuard;
+    }
+
+    @Override
+    protected boolean shouldNotFilter(HttpServletRequest request) {
+        return !(request.getRequestURI().startsWith("/mcp") && "POST".equalsIgnoreCase(request.getMethod()));
+    }
+
+    @Override
+    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain)
+            throws ServletException, IOException {
+        byte[] body = request.getInputStream().readAllBytes();
+        CachedBodyRequest wrappedRequest = new CachedBodyRequest(request, body);
+        if (!isToolsList(body)) {
+            chain.doFilter(wrappedRequest, response);
+            return;
+        }
+        BufferingResponse wrappedResponse = new BufferingResponse(response);
+        chain.doFilter(wrappedRequest, wrappedResponse);
+
+        byte[] result = wrappedResponse.bodyBytes();
+        AuthContext ctx = AuthContextHolder.get();
+        if (ctx != null && wrappedResponse.status() == 200) {
+            Set<String> allowed = toolGuard.allowedToolNames(ctx.getTokenId());
+            result = ToolsListResponseRewriter
+                    .rewrite(new String(result, StandardCharsets.UTF_8), allowed)
+                    .getBytes(StandardCharsets.UTF_8);
+        }
+        response.setStatus(wrappedResponse.status());
+        if (wrappedResponse.contentType() != null) {
+            response.setContentType(wrappedResponse.contentType());
+        }
+        response.setContentLength(result.length);
+        response.getOutputStream().write(result);
+        response.flushBuffer();
+    }
+
+    private boolean isToolsList(byte[] body) {
+        try {
+            JsonNode node = objectMapper.readTree(body);
+            return "tools/list".equals(node.path("method").asText());
+        } catch (Exception e) {
+            return false;
+        }
+    }
+
+    /** 可重复读 Body 的请求包装（过滤器预读后继续传给下游）。 */
+    static final class CachedBodyRequest extends HttpServletRequestWrapper {
+
+        private final byte[] body;
+
+        CachedBodyRequest(HttpServletRequest request, byte[] body) {
+            super(request);
+            this.body = body;
+        }
+
+        @Override
+        public ServletInputStream getInputStream() {
+            ByteArrayInputStream input = new ByteArrayInputStream(body);
+            return new ServletInputStream() {
+                @Override
+                public boolean isFinished() {
+                    return input.available() == 0;
+                }
+
+                @Override
+                public boolean isReady() {
+                    return true;
+                }
+
+                @Override
+                public void setReadListener(jakarta.servlet.ReadListener readListener) {
+                    // 同步读取，无需监听器
+                }
+
+                @Override
+                public int read() {
+                    return input.read();
+                }
+
+                @Override
+                public int read(byte[] b, int off, int len) {
+                    return input.read(b, off, len);
+                }
+            };
+        }
+
+        @Override
+        public BufferedReader getReader() {
+            return new BufferedReader(new InputStreamReader(getInputStream(), StandardCharsets.UTF_8));
+        }
+    }
+
+    /** 全量缓冲响应的包装：下游写完前不向真实响应提交任何字节，便于整体重写。 */
+    static final class BufferingResponse extends HttpServletResponseWrapper {
+
+        private final ByteArrayOutputStream buffer = new ByteArrayOutputStream();
+        private int status = HttpServletResponse.SC_OK;
+        private String contentType;
+
+        BufferingResponse(HttpServletResponse response) {
+            super(response);
+        }
+
+        @Override
+        public ServletOutputStream getOutputStream() {
+            return new ServletOutputStream() {
+                @Override
+                public boolean isReady() {
+                    return true;
+                }
+
+                @Override
+                public void setWriteListener(jakarta.servlet.WriteListener writeListener) {
+                    // 同步写出，无需监听器
+                }
+
+                @Override
+                public void write(int b) {
+                    buffer.write(b);
+                }
+
+                @Override
+                public void write(byte[] b, int off, int len) {
+                    buffer.write(b, off, len);
+                }
+            };
+        }
+
+        @Override
+        public PrintWriter getWriter() {
+            return new PrintWriter(new java.io.OutputStreamWriter(getOutputStream(), StandardCharsets.UTF_8), true);
+        }
+
+        @Override
+        public void setStatus(int sc) {
+            this.status = sc;
+        }
+
+        @Override
+        public void sendError(int sc) {
+            this.status = sc;
+        }
+
+        @Override
+        public void sendError(int sc, String msg) {
+            this.status = sc;
+        }
+
+        @Override
+        public void setContentType(String type) {
+            this.contentType = type;
+        }
+
+        @Override
+        public String getContentType() {
+            return contentType;
+        }
+
+        @Override
+        public void setContentLength(int len) {
+            // 长度在重写后由外层统一设置
+        }
+
+        @Override
+        public void setContentLengthLong(long len) {
+            // 长度在重写后由外层统一设置
+        }
+
+        @Override
+        public void flushBuffer() {
+            // 缓冲期间禁止提前提交
+        }
+
+        int status() {
+            return status;
+        }
+
+        String contentType() {
+            return contentType;
+        }
+
+        byte[] bodyBytes() throws IOException {
+            return buffer.toByteArray();
+        }
+    }
+}
@@ -0,0 +1,55 @@
+package me.iiv.agent.open;
+
+import jakarta.servlet.FilterChain;
+import jakarta.servlet.ServletException;
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletResponse;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.stereotype.Component;
+import org.springframework.web.filter.OncePerRequestFilter;
+
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+
+/**
+ * /api/open 通道服务间鉴权：X-Open-Key 静态密钥（配置 app.open.api-key）。
+ * 与 ak 体系、后台 session 体系完全分离；配置为空 = 接口关闭。
+ */
+@Component
+public class OpenKeyFilter extends OncePerRequestFilter {
+
+    static final String OPEN_KEY_HEADER = "X-Open-Key";
+
+    @Value("${app.open.api-key:}")
+    private String apiKey;
+
+    @Override
+    protected boolean shouldNotFilter(HttpServletRequest request) {
+        return !request.getRequestURI().startsWith("/api/open/");
+    }
+
+    @Override
+    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
+                                    FilterChain chain) throws ServletException, IOException {
+        response.setHeader("Cache-Control", "no-store");
+        if (apiKey == null || apiKey.isBlank()) {
+            error(response, 403, "Open API 未启用");
+            return;
+        }
+        String provided = request.getHeader(OPEN_KEY_HEADER);
+        if (provided == null || !MessageDigest.isEqual(
+                apiKey.getBytes(StandardCharsets.UTF_8), provided.getBytes(StandardCharsets.UTF_8))) {
+            error(response, 401, "服务间密钥无效");
+            return;
+        }
+        chain.doFilter(request, response);
+    }
+
+    private static void error(HttpServletResponse response, int status, String message) throws IOException {
+        response.setStatus(status);
+        response.setCharacterEncoding(StandardCharsets.UTF_8.name());
+        response.setContentType("application/json");
+        response.getWriter().write("{\"message\":\"" + message + "\"}");
+    }
+}
@@ -0,0 +1,35 @@
+package me.iiv.agent.open;
+
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.Date;
+
+/**
+ * 对外服务间接口（/api/open/**），X-Open-Key 鉴权，见 OpenKeyFilter。
+ */
+@RestController
+@RequestMapping("/api/open")
+public class OpenTokenController {
+
+    private final OpenTokenService openTokenService;
+
+    public OpenTokenController(OpenTokenService openTokenService) {
+        this.openTokenService = openTokenService;
+    }
+
+    /**
+     * 确保某人员在某作用域下有有效 Token：存在则返回元信息（created=false，无明文），
+     * 不存在则自动创建永久 Token 并返回明文（created=true，仅此一次可见）。
+     */
+    @PostMapping("/token/ensure")
+    public EnsureResult ensure(@RequestBody EnsureRequest body) {
+        return openTokenService.ensure(body);
+    }
+
+    public record EnsureRequest(String mobile, String email, String scopeCode) {}
+    public record EnsureResult(boolean created, String token, String keyPrefix, Date expireTime,
+                               Long userId, String userName, String scopeCode) {}
+}
@@ -0,0 +1,120 @@
+package me.iiv.agent.open;
+
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import me.iiv.agent.admin.AdminTokenService;
+import me.iiv.agent.common.AuditService;
+import me.iiv.agent.entity.m0.User;
+import me.iiv.agent.entity.svc.AgentApiKey;
+import me.iiv.agent.entity.svc.AgentScope;
+import me.iiv.agent.mapper.m0.UserMapper;
+import me.iiv.agent.mapper.svc.AgentScopeMapper;
+import me.iiv.agent.security.AuthContext;
+import org.springframework.http.HttpStatus;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+import org.springframework.util.StringUtils;
+import org.springframework.web.server.ResponseStatusException;
+
+import java.util.Date;
+
+/**
+ * Open API：按 手机号/邮箱 + 作用域编码 确保 Token 存在（get-or-create）。
+ * 存在有效 Token 只回元信息（服务端只存哈希，明文不可回吐）；
+ * 不存在则自动创建永久 Token，明文仅本次返回。
+ */
+@Service
+public class OpenTokenService {
+
+    /** 系统签发（Open API 自动创建）的 createId 约定值 */
+    static final long SYSTEM_CREATOR_ID = 0L;
+    static final String AUDIT_TOOL = "open.token.ensure";
+
+    private final UserMapper userMapper;
+    private final AgentScopeMapper scopeMapper;
+    private final AdminTokenService tokenService;
+    private final AuditService auditService;
+
+    public OpenTokenService(UserMapper userMapper, AgentScopeMapper scopeMapper,
+                            AdminTokenService tokenService, AuditService auditService) {
+        this.userMapper = userMapper;
+        this.scopeMapper = scopeMapper;
+        this.tokenService = tokenService;
+        this.auditService = auditService;
+    }
+
+    @Transactional(transactionManager = "svcTransactionManager")
+    public OpenTokenController.EnsureResult ensure(OpenTokenController.EnsureRequest body) {
+        long start = System.currentTimeMillis();
+        if (body == null) bad(HttpStatus.BAD_REQUEST, "请求内容不能为空");
+        if (!StringUtils.hasText(body.mobile()) && !StringUtils.hasText(body.email())) {
+            bad(HttpStatus.BAD_REQUEST, "手机号和邮箱至少传一个");
+        }
+        if (!StringUtils.hasText(body.scopeCode())) bad(HttpStatus.BAD_REQUEST, "作用域编码不能为空");
+
+        AgentScope scope = scopeMapper.selectOne(new LambdaQueryWrapper<AgentScope>()
+                .eq(AgentScope::getCode, body.scopeCode().trim()).eq(AgentScope::getSoftDelete, 0));
+        if (scope == null || !Byte.valueOf((byte) 1).equals(scope.getStatus())) {
+            bad(HttpStatus.BAD_REQUEST, "作用域不存在或已停用");
+        }
+
+        User user = findUser(body.mobile(), body.email());
+        if (user == null) {
+            audit(null, null, body, "error", "人员不存在或非企业账号", start);
+            throw new ResponseStatusException(HttpStatus.NOT_FOUND, "人员不存在或非企业账号");
+        }
+
+        AgentApiKey existing = tokenService.findActiveToken(user.getId(), scope.getId());
+        if (existing != null) {
+            audit(user, existing, body, "success", "已存在有效 Token，返回元信息", start);
+            return new OpenTokenController.EnsureResult(false, null, existing.getKeyPrefix(),
+                    existing.getExpireTime(), user.getId(), user.getName(), scope.getCode());
+        }
+
+        AdminTokenService.IssuedToken issued = tokenService.issueSingle(user.getId(),
+                "open-api 自动签发（" + scope.getCode() + "）", scope.getId(), null, SYSTEM_CREATOR_ID);
+        AgentApiKey created = new AgentApiKey();
+        created.setId(issued.token().id());
+        audit(user, created, body, "success", "自动创建永久 Token", start);
+        return new OpenTokenController.EnsureResult(true, issued.plaintext(), issued.token().keyPrefix(),
+                null, user.getId(), user.getName(), scope.getCode());
+    }
+
+    /** 手机号优先、邮箱兜底；只认企业账号（enterprise_type 0/1，历史 NULL 保留），与后台用户列表同口径。 */
+    private User findUser(String mobile, String email) {
+        LambdaQueryWrapper<User> query = new LambdaQueryWrapper<User>()
+                .eq(User::getSoftDelete, 0)
+                .and(w -> w.ne(User::getEnterpriseType, 2).or().isNull(User::getEnterpriseType));
+        if (StringUtils.hasText(mobile)) {
+            query.eq(User::getMobile, mobile.trim());
+        } else {
+            query.eq(User::getEmail, email.trim());
+        }
+        return userMapper.selectList(query.orderByDesc(User::getId).last("LIMIT 1"))
+                .stream().findFirst().orElse(null);
+    }
+
+    private void audit(User user, AgentApiKey token, OpenTokenController.EnsureRequest body,
+                       String status, String message, long start) {
+        String digest = "mobile=" + maskMobile(body.mobile()) + " email=" + maskEmail(body.email())
+                + " scopeCode=" + body.scopeCode();
+        auditService.record(new AuthContext(token, user), AUDIT_TOOL, digest,
+                status, message, System.currentTimeMillis() - start);
+    }
+
+    private static String maskMobile(String mobile) {
+        if (!StringUtils.hasText(mobile)) return "-";
+        String value = mobile.trim();
+        return value.length() < 7 ? "***" : value.substring(0, 3) + "****" + value.substring(value.length() - 4);
+    }
+
+    private static String maskEmail(String email) {
+        if (!StringUtils.hasText(email)) return "-";
+        String value = email.trim();
+        int at = value.indexOf('@');
+        return at <= 1 ? "***" + value.substring(at) : value.charAt(0) + "***" + value.substring(at);
+    }
+
+    private static void bad(HttpStatus status, String message) {
+        throw new ResponseStatusException(status, message);
+    }
+}
@@ -5,6 +5,7 @@ import jakarta.servlet.FilterChain;
 import jakarta.servlet.ServletException;
 import jakarta.servlet.http.HttpServletRequest;
 import jakarta.servlet.http.HttpServletResponse;
+import org.springframework.core.annotation.Order;
 import org.springframework.http.MediaType;
 import org.springframework.stereotype.Component;
 import org.springframework.web.filter.OncePerRequestFilter;
@@ -17,8 +18,10 @@ import java.util.Map;
 /**
 * /mcp 通道 ak 鉴权：Authorization: Bearer &lt;ak&gt; → AuthContext（ThreadLocal）。
 * 无 ak / ak 无效 → 401 JSON。
+ * @Order(10)：必须先于 ToolsListScopeFilter（@Order(20)）执行，后者依赖 AuthContext。
 */
@Component
+@Order(10)
 public class AkAuthFilter extends OncePerRequestFilter {

    private static final String MCP_PATH = "/mcp";
@@ -12,6 +12,7 @@ import org.springframework.stereotype.Component;

 import java.util.Collections;
 import java.util.List;
+import java.util.Set;
 import java.util.stream.Collectors;

 /**
@@ -35,23 +36,28 @@ public class ToolGuard {
    }

    public boolean isAllowed(Long tokenId, String toolName) {
+        return allowedToolNames(tokenId).contains(toolName);
+    }
+
+    /** token 的作用域并集内、且启用状态的工具名集合（tools/list 过滤用，固定 3 次查询，与工具数无关）。 */
+    public Set<String> allowedToolNames(Long tokenId) {
        List<Long> scopeIds = enabledScopeIds(tokenId);
        if (scopeIds.isEmpty()) {
-            return false;
+            return Set.of();
        }
        List<ScopeTool> scopeTools = scopeToolMapper.selectList(new LambdaQueryWrapper<ScopeTool>()
                .eq(ScopeTool::getSoftDelete, 0)
                .in(ScopeTool::getScopeId, scopeIds));
        if (scopeTools.isEmpty()) {
-            return false;
+            return Set.of();
        }
        List<Long> toolIds = scopeTools.stream().map(ScopeTool::getToolId).distinct().collect(Collectors.toList());
-        Long count = toolMapper.selectCount(new LambdaQueryWrapper<me.iiv.agent.entity.svc.Tool>()
-                .eq(me.iiv.agent.entity.svc.Tool::getSoftDelete, 0)
-                .eq(me.iiv.agent.entity.svc.Tool::getStatus, 1)
-                .eq(me.iiv.agent.entity.svc.Tool::getName, toolName)
-                .in(me.iiv.agent.entity.svc.Tool::getId, toolIds));
-        return count != null && count > 0;
+        return toolMapper.selectList(new LambdaQueryWrapper<me.iiv.agent.entity.svc.Tool>()
+                        .eq(me.iiv.agent.entity.svc.Tool::getSoftDelete, 0)
+                        .eq(me.iiv.agent.entity.svc.Tool::getStatus, 1)
+                        .in(me.iiv.agent.entity.svc.Tool::getId, toolIds)
+                        .select(me.iiv.agent.entity.svc.Tool::getName))
+                .stream().map(me.iiv.agent.entity.svc.Tool::getName).collect(Collectors.toSet());
    }

    /** token 勾选的、且处于启用状态的作用域 id 集合 */
@@ -1,33 +1,37 @@
 # dev 环境：内网 192.168.1.181（沿用 xiaoqu-franchisee pom.xml dev profile）
-# 账号和密码必须由环境变量提供；m0/m1/m2 应使用数据库只读账号
+# 账号密码明文写在本文件（内网 dev 库，与 xiaoqu-franchisee pom.xml dev profile 同一惯例）；
+# 生产/测试环境不得在配置文件中写明文密码，改用环境变量
 app:
+  open:
+    # Open API（/api/open/**）服务间静态密钥，dev 明文；调用方放 header X-Open-Key
+    api-key: xqok_4b44012f12b9fa54d6ec11690e6da57563a75c891df60961
  datasource:
    m0: # 权限库 xiaoqu_comples_d（user/agent/authority/propery/agent_manage_district_auth）
      driver-class-name: com.mysql.cj.jdbc.Driver
      jdbc-url: jdbc:mysql://192.168.1.181:3306/xiaoqu_comples_d?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
-      username: ${M0_DB_USERNAME}
-      password: ${M0_DB_PASSWORD}
+      username: root
+      password: kaixinjiuhao
    m1: # 商城库 xiaoqu_mall_d（按需启用）
      driver-class-name: com.mysql.cj.jdbc.Driver
      jdbc-url: jdbc:mysql://192.168.1.181:3306/xiaoqu_mall_d?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
-      username: ${M1_DB_USERNAME}
-      password: ${M1_DB_PASSWORD}
+      username: root
+      password: kaixinjiuhao
    m2: # 业务库 xiaoqu_franchisee_d（warehouse_agent_auth 等）
      driver-class-name: com.mysql.cj.jdbc.Driver
      jdbc-url: jdbc:mysql://192.168.1.181:3306/xiaoqu_franchisee_d?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
-      username: ${M2_DB_USERNAME}
-      password: ${M2_DB_PASSWORD}
+      username: root
+      password: kaixinjiuhao
    svc: # 自有库 xiaoqu_agent_svc_d（token/scope/tool/audit，读写）
      driver-class-name: com.mysql.cj.jdbc.Driver
      jdbc-url: jdbc:mysql://192.168.1.181:3306/xiaoqu_agent_svc_d?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
-      username: ${SVC_DB_USERNAME}
-      password: ${SVC_DB_PASSWORD}
+      username: root
+      password: kaixinjiuhao

 spring:
  data:
    redis:
      host: 192.168.1.181
      port: 6379
-      password: ${REDIS_PASSWORD}
+      password: kaixinjiuhao
      database: 5
      timeout: 5s
@@ -14,6 +14,9 @@ app:
      account: ${ADMIN_BOOTSTRAP_ACCOUNT:}
      password: ${ADMIN_BOOTSTRAP_PASSWORD:}
      name: ${ADMIN_BOOTSTRAP_NAME:系统管理员}
+  open:
+    # /api/open 服务间静态密钥；为空 = Open API 关闭。dev 明文见 application-dev.yml
+    api-key: ${OPEN_API_KEY:}

 spring:
  application:
@@ -3,6 +3,7 @@ package me.iiv.agent.admin;
 import me.iiv.agent.entity.m0.User;
 import me.iiv.agent.entity.svc.AgentApiKey;
 import me.iiv.agent.entity.svc.AgentScope;
+import me.iiv.agent.entity.svc.TokenScope;
 import me.iiv.agent.mapper.m0.UserMapper;
 import me.iiv.agent.mapper.svc.AgentApiKeyMapper;
 import me.iiv.agent.mapper.svc.AgentScopeMapper;
@@ -15,12 +16,14 @@ import org.mockito.Mock;
 import org.mockito.junit.jupiter.MockitoExtension;

 import java.util.List;
+import java.util.concurrent.atomic.AtomicLong;

 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertNotEquals;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.times;
 import static org.mockito.Mockito.when;

@ExtendWith(MockitoExtension.class)
@@ -31,12 +34,21 @@ class AdminTokenServiceTest {
    @Mock TokenScopeMapper tokenScopeMapper;
    @Mock AgentScopeMapper scopeMapper;

-    @Test
-    void issueReturnsPlaintextOnceAndStoresOnlyHash() {
+    private User stubUser() {
        User user = new User();
        user.setId(7L);
        user.setSoftDelete(0);
        when(userMapper.selectById(7L)).thenReturn(user);
+        return user;
+    }
+
+    private AdminTokenService service() {
+        return new AdminTokenService(userMapper, tokenMapper, tokenScopeMapper, scopeMapper);
+    }
+
+    @Test
+    void issueReturnsPlaintextOnceAndStoresOnlyHash() {
+        stubUser();
        AgentScope scope = new AgentScope();
        scope.setId(3L);
        scope.setStatus((byte) 1);
@@ -47,28 +59,52 @@ class AdminTokenServiceTest {
            return 1;
        });

-        AdminTokenService service = new AdminTokenService(
-                userMapper, tokenMapper, tokenScopeMapper, scopeMapper);
-        AdminTokenService.IssuedToken issued = service.issue(7L, "Kimi", List.of(3L), null, 1L);
+        List<AdminTokenService.IssuedToken> issued = service().issue(7L, "Kimi", List.of(3L), null, 1L);

+        assertEquals(1, issued.size());
        ArgumentCaptor<AgentApiKey> captor = ArgumentCaptor.forClass(AgentApiKey.class);
        org.mockito.Mockito.verify(tokenMapper).insert(captor.capture());
        AgentApiKey stored = captor.getValue();
-        assertTrue(issued.plaintext().matches("xqak_[0-9a-f]{48}"));
-        assertEquals(AuthService.sha256Hex(issued.plaintext()), stored.getKeyHash());
-        assertNotEquals(issued.plaintext(), stored.getKeyHash());
-        assertEquals(11L, issued.token().id());
+        assertTrue(issued.get(0).plaintext().matches("xqak_[0-9a-f]{48}"));
+        assertEquals(AuthService.sha256Hex(issued.get(0).plaintext()), stored.getKeyHash());
+        assertNotEquals(issued.get(0).plaintext(), stored.getKeyHash());
+        assertEquals(11L, issued.get(0).token().id());
+    }
+
+    @Test
+    void issueWithTwoScopesCreatesTwoTokensEachBoundToOneScope() {
+        stubUser();
+        AgentScope scopeA = new AgentScope();
+        scopeA.setId(3L);
+        scopeA.setStatus((byte) 1);
+        scopeA.setSoftDelete((byte) 0);
+        AgentScope scopeB = new AgentScope();
+        scopeB.setId(4L);
+        scopeB.setStatus((byte) 1);
+        scopeB.setSoftDelete((byte) 0);
+        when(scopeMapper.selectList(any())).thenReturn(List.of(scopeA, scopeB));
+        AtomicLong idSequence = new AtomicLong(10);
+        when(tokenMapper.insert(any(AgentApiKey.class))).thenAnswer(invocation -> {
+            invocation.<AgentApiKey>getArgument(0).setId(idSequence.incrementAndGet());
+            return 1;
+        });
+
+        List<AdminTokenService.IssuedToken> issued = service().issue(7L, "Kimi", List.of(3L, 4L), null, 1L);
+
+        assertEquals(2, issued.size());
+        assertNotEquals(issued.get(0).plaintext(), issued.get(1).plaintext());
+        org.mockito.Mockito.verify(tokenMapper, times(2)).insert(any(AgentApiKey.class));
+        // 每把 Token 只绑定一个作用域
+        ArgumentCaptor<TokenScope> relationCaptor = ArgumentCaptor.forClass(TokenScope.class);
+        org.mockito.Mockito.verify(tokenScopeMapper, times(2)).insert(relationCaptor.capture());
+        List<TokenScope> relations = relationCaptor.getAllValues();
+        assertEquals(List.of(3L, 4L), relations.stream().map(TokenScope::getScopeId).sorted().toList());
    }

    @Test
    void issueRejectsDuplicateScopesBeforeWriting() {
-        User user = new User();
-        user.setId(7L);
-        user.setSoftDelete(0);
-        when(userMapper.selectById(7L)).thenReturn(user);
-        AdminTokenService service = new AdminTokenService(userMapper, tokenMapper, tokenScopeMapper, scopeMapper);
-
+        stubUser();
        assertThrows(RuntimeException.class,
-                () -> service.issue(7L, "Kimi", List.of(3L, 3L), null, 1L));
+                () -> service().issue(7L, "Kimi", List.of(3L, 3L), null, 1L));
    }
 }
@@ -0,0 +1,88 @@
+package me.iiv.agent.mcp;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.junit.jupiter.api.Test;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Set;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class ToolsListResponseRewriterTest {
+
+    private static final ObjectMapper MAPPER = new ObjectMapper();
+
+    private static String sseEvent(String id, String json) {
+        return "id:" + id + "\nevent:message\ndata:" + json + "\n\n";
+    }
+
+    private static String toolsJson(String... names) {
+        StringBuilder tools = new StringBuilder();
+        for (String name : names) {
+            if (tools.length() > 0) tools.append(',');
+            tools.append("{\"name\":\"").append(name).append("\",\"description\":\"d\"}");
+        }
+        return "{\"jsonrpc\":\"2.0\",\"id\":2,\"result\":{\"tools\":[" + tools + "]}}";
+    }
+
+    private static List<String> toolNames(String body) throws Exception {
+        String data = null;
+        for (String line : body.split("\\n")) {
+            if (line.startsWith("data:")) {
+                data = line.substring(5);
+            }
+        }
+        JsonNode node = MAPPER.readTree(data == null ? body : data);
+        List<String> names = new ArrayList<>();
+        node.path("result").path("tools").forEach(tool -> names.add(tool.path("name").asText()));
+        return names;
+    }
+
+    @Test
+    void filtersToolsInSseEvent() throws Exception {
+        String body = sseEvent("evt-1", toolsJson("agent.list.query", "property.list.query", "sys.ping"));
+
+        String rewritten = ToolsListResponseRewriter.rewrite(body, Set.of("agent.list.query", "sys.ping"));
+
+        assertEquals(List.of("agent.list.query", "sys.ping"), toolNames(rewritten));
+        assertTrue(rewritten.startsWith("id:evt-1\nevent:message\n"), "SSE 元信息行需保留");
+        assertTrue(rewritten.endsWith("\n\n"), "事件末尾空行需保留");
+    }
+
+    @Test
+    void emptyAllowanceYieldsEmptyToolList() throws Exception {
+        String body = sseEvent("evt-1", toolsJson("agent.list.query"));
+
+        String rewritten = ToolsListResponseRewriter.rewrite(body, Set.of());
+
+        assertEquals(List.of(), toolNames(rewritten));
+    }
+
+    @Test
+    void nonToolsEventsPassThroughUnchanged() {
+        String initEvent = sseEvent("evt-0", "{\"jsonrpc\":\"2.0\",\"id\":1,\"result\":{\"protocolVersion\":\"2025-03-26\"}}");
+        String body = initEvent + sseEvent("evt-1", toolsJson("a", "b"));
+
+        String rewritten = ToolsListResponseRewriter.rewrite(body, Set.of("a"));
+
+        assertTrue(rewritten.startsWith(initEvent), "非 tools/list 事件原样保留");
+    }
+
+    @Test
+    void plainJsonResponseIsAlsoFiltered() throws Exception {
+        String body = toolsJson("a", "b");
+
+        String rewritten = ToolsListResponseRewriter.rewrite(body, Set.of("b"));
+
+        assertEquals(List.of("b"), toolNames(rewritten));
+    }
+
+    @Test
+    void unparseableBodyPassesThrough() {
+        String garbage = "not-json-not-sse";
+        assertEquals(garbage, ToolsListResponseRewriter.rewrite(garbage, Set.of("a")));
+    }
+}
@@ -0,0 +1,126 @@
+package me.iiv.agent.open;
+
+import me.iiv.agent.admin.AdminTokenService;
+import me.iiv.agent.common.AuditService;
+import me.iiv.agent.entity.m0.User;
+import me.iiv.agent.entity.svc.AgentApiKey;
+import me.iiv.agent.entity.svc.AgentScope;
+import me.iiv.agent.mapper.m0.UserMapper;
+import me.iiv.agent.mapper.svc.AgentScopeMapper;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.springframework.web.server.ResponseStatusException;
+
+import java.util.Date;
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyLong;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.ArgumentMatchers.isNull;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.when;
+
+@ExtendWith(MockitoExtension.class)
+class OpenTokenServiceTest {
+
+    @Mock UserMapper userMapper;
+    @Mock AgentScopeMapper scopeMapper;
+    @Mock AdminTokenService tokenService;
+    @Mock AuditService auditService;
+
+    OpenTokenService service;
+    AgentScope scope;
+    User user;
+
+    @BeforeEach
+    void setUp() {
+        service = new OpenTokenService(userMapper, scopeMapper, tokenService, auditService);
+        scope = new AgentScope();
+        scope.setId(3L);
+        scope.setCode("operation");
+        scope.setStatus((byte) 1);
+        scope.setSoftDelete((byte) 0);
+        user = new User();
+        user.setId(7L);
+        user.setName("张三");
+        user.setSoftDelete(0);
+    }
+
+    private void stubScopeAndUser() {
+        when(scopeMapper.selectOne(any())).thenReturn(scope);
+        when(userMapper.selectList(any())).thenReturn(List.of(user));
+    }
+
+    @Test
+    void existingActiveTokenReturnsMetadataWithoutPlaintext() {
+        stubScopeAndUser();
+        AgentApiKey existing = new AgentApiKey();
+        existing.setId(11L);
+        existing.setKeyPrefix("xqak_abcd1234");
+        when(tokenService.findActiveToken(7L, 3L)).thenReturn(existing);
+
+        OpenTokenController.EnsureResult result = service.ensure(
+                new OpenTokenController.EnsureRequest("13800001111", null, "operation"));
+
+        assertFalse(result.created());
+        assertNull(result.token());
+        assertEquals("xqak_abcd1234", result.keyPrefix());
+        assertEquals(7L, result.userId());
+        org.mockito.Mockito.verify(tokenService, never())
+                .issueSingle(anyLong(), anyString(), anyLong(), isNull(), anyLong());
+    }
+
+    @Test
+    void missingTokenCreatesPermanentOneAndReturnsPlaintext() {
+        stubScopeAndUser();
+        when(tokenService.findActiveToken(7L, 3L)).thenReturn(null);
+        AdminTokenService.TokenView view = new AdminTokenService.TokenView(
+                12L, "xqak_efgh5678", "open-api 自动签发（operation）", (byte) 1,
+                null, null, List.of(3L), List.of("运营"));
+        when(tokenService.issueSingle(eq(7L), anyString(), eq(3L), isNull(), eq(0L)))
+                .thenReturn(new AdminTokenService.IssuedToken("xqak_" + "a".repeat(48), view));
+
+        OpenTokenController.EnsureResult result = service.ensure(
+                new OpenTokenController.EnsureRequest(null, "zhangsan@test.com", "operation"));
+
+        assertTrue(result.created());
+        assertTrue(result.token().matches("xqak_[0-9a-f]{48}"));
+        assertNull(result.expireTime());
+        assertEquals("operation", result.scopeCode());
+    }
+
+    @Test
+    void unknownUserRejected() {
+        when(scopeMapper.selectOne(any())).thenReturn(scope);
+        when(userMapper.selectList(any())).thenReturn(List.of());
+
+        ResponseStatusException error = assertThrows(ResponseStatusException.class, () -> service.ensure(
+                new OpenTokenController.EnsureRequest("13800001111", null, "operation")));
+        assertEquals(404, error.getStatusCode().value());
+    }
+
+    @Test
+    void disabledScopeRejected() {
+        scope.setStatus((byte) 0);
+        when(scopeMapper.selectOne(any())).thenReturn(scope);
+
+        assertThrows(ResponseStatusException.class, () -> service.ensure(
+                new OpenTokenController.EnsureRequest("13800001111", null, "operation")));
+    }
+
+    @Test
+    void requiresMobileOrEmail() {
+        assertThrows(ResponseStatusException.class, () -> service.ensure(
+                new OpenTokenController.EnsureRequest(null, null, "operation")));
+    }
+}
@@ -11,8 +11,6 @@ import static org.junit.jupiter.api.Assertions.assertFalse;

 class ConfigurationSecurityTest {

-    private static final Pattern PASSWORD_WITH_DEFAULT =
-            Pattern.compile("password:\\s*\\$\\{[^}:]+:[^}]+}");
    private static final Pattern COMMITTED_AK =
            Pattern.compile("xqak_[0-9a-f]{20,}");

@@ -24,11 +22,11 @@ class ConfigurationSecurityTest {
    }

    @Test
-    void devConfigurationHasNoRootUserOrPasswordDefaults() throws IOException {
-        String application = Files.readString(Path.of("src/main/resources/application-dev.yml"));
+    void baseConfigurationHasNoPlaintextPassword() throws IOException {
+        // dev 允许明文（内网库，与 xiaoqu-franchisee pom dev 同一惯例）；公共 application.yml 不允许
+        String application = Files.readString(Path.of("src/main/resources/application.yml"));

-        assertFalse(application.contains("username: root"));
-        assertFalse(PASSWORD_WITH_DEFAULT.matcher(application).find());
+        assertFalse(application.contains("password: kaixinjiuhao"));
    }

    @Test
@@ -14,7 +14,9 @@ import org.mockito.Mock;
 import org.mockito.junit.jupiter.MockitoExtension;

 import java.util.List;
+import java.util.Set;

+import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 import static org.mockito.ArgumentMatchers.any;
@@ -26,6 +28,15 @@ import static org.mockito.Mockito.when;
@SuppressWarnings("unchecked")
 class ToolGuardTest {

+    @org.junit.jupiter.api.BeforeAll
+    static void initTableInfo() {
+        // allowedToolNames 的 .select(Tool::getName) 在构建 wrapper 时即解析 lambda 列，需 TableInfo
+        com.baomidou.mybatisplus.core.metadata.TableInfoHelper.initTableInfo(
+                new org.apache.ibatis.builder.MapperBuilderAssistant(
+                        new com.baomidou.mybatisplus.core.MybatisConfiguration(), ""),
+                me.iiv.agent.entity.svc.Tool.class);
+    }
+
    @Mock
    TokenScopeMapper tokenScopeMapper;
    @Mock
@@ -59,7 +70,7 @@ class ToolGuardTest {
        when(tokenScopeMapper.selectList(any(LambdaQueryWrapper.class))).thenReturn(List.of(tokenScope(3L)));
        when(agentScopeMapper.selectList(any(LambdaQueryWrapper.class))).thenReturn(List.of(scope(3L)));
        when(scopeToolMapper.selectList(any(LambdaQueryWrapper.class))).thenReturn(List.of(scopeTool(9L)));
-        when(toolMapper.selectCount(any(LambdaQueryWrapper.class))).thenReturn(1L);
+        when(toolMapper.selectList(any(LambdaQueryWrapper.class))).thenReturn(List.of(tool(9L, "agent.list.query")));
        ToolGuard guard = guard();

        assertTrue(guard.isAllowed(7L, "agent.list.query"));
@@ -70,12 +81,24 @@ class ToolGuardTest {
        when(tokenScopeMapper.selectList(any(LambdaQueryWrapper.class))).thenReturn(List.of(tokenScope(3L)));
        when(agentScopeMapper.selectList(any(LambdaQueryWrapper.class))).thenReturn(List.of(scope(3L)));
        when(scopeToolMapper.selectList(any(LambdaQueryWrapper.class))).thenReturn(List.of(scopeTool(9L)));
-        when(toolMapper.selectCount(any(LambdaQueryWrapper.class))).thenReturn(0L);
+        when(toolMapper.selectList(any(LambdaQueryWrapper.class))).thenReturn(List.of());
        ToolGuard guard = guard();

        assertFalse(guard.isAllowed(7L, "agent.list.query"));
    }

+    @Test
+    void allowedToolNamesReturnsEnabledNamesOnly() {
+        when(tokenScopeMapper.selectList(any(LambdaQueryWrapper.class))).thenReturn(List.of(tokenScope(3L)));
+        when(agentScopeMapper.selectList(any(LambdaQueryWrapper.class))).thenReturn(List.of(scope(3L)));
+        when(scopeToolMapper.selectList(any(LambdaQueryWrapper.class))).thenReturn(List.of(scopeTool(9L)));
+        when(toolMapper.selectList(any(LambdaQueryWrapper.class)))
+                .thenReturn(List.of(tool(9L, "agent.list.query"), tool(10L, "sys.ping")));
+        ToolGuard guard = guard();
+
+        assertEquals(Set.of("agent.list.query", "sys.ping"), guard.allowedToolNames(7L));
+    }
+
    private ToolGuard guard() {
        return new ToolGuard(tokenScopeMapper, scopeToolMapper, toolMapper, agentScopeMapper);
    }
@@ -97,4 +120,11 @@ class ToolGuardTest {
        scopeTool.setToolId(toolId);
        return scopeTool;
    }
+
+    private static me.iiv.agent.entity.svc.Tool tool(Long id, String name) {
+        me.iiv.agent.entity.svc.Tool tool = new me.iiv.agent.entity.svc.Tool();
+        tool.setId(id);
+        tool.setName(name);
+        return tool;
+    }
 }
Author	SHA1	Message	Date
xqzp2026	26769fb3be	docs: align MCP token flow to single ensure-only policy	2026-09-07 13:16:18 +09:30
xqzp2026	4d6dfa5025	docs: sync MCP token spec to one-time mobile token flow	2026-09-07 13:04:13 +09:30
xqzp2026	12f69504e4	docs(mcp): 统一服务文档目录	2026-09-07 12:27:02 +09:30
xiaoqu	237a1f1c26	feat(mcp): tools/list按token作用域过滤(servlet层重写响应); ToolGuard.allowedToolNames批量查询; AkAuthFilter定序@Order(10)	2026-09-04 18:00:41 +08:00
xiaoqu	8d0eba4957	docs: iOS每用户Token设计对齐已交付ensure接口(两段式/明文不可回吐/业务后端门面); 修tools/list不按scope过滤的文档漂移	2026-09-04 17:07:11 +08:00
xiaoqu	62b69657a6	feat(common): 全局异常处理, ResponseStatusException 统一返回 {message} (Open API/后台错误可读)	2026-09-04 16:53:18 +08:00
xiaoqu	965b314751	feat(token): 一作用域一Token(签发N个作用域生成N把); 新增Open API /api/open/token/ensure(get-or-create, X-Open-Key鉴权, 明文不可回吐)	2026-09-04 16:53:18 +08:00
wangheng	b1ad0f727a	Merge pull request 'docs(mcp): 设计每用户 Token 接入方案' (#2 ) from docs/mcp-per-user-token-design into main Reviewed-on: #2	2026-09-04 16:12:25 +08:00
xqzp2026	1bb115dee0	docs(mcp): 设计每用户 Token 接入方案	2026-09-04 17:40:57 +09:30
xiaoqu	80b0035ba6	docs: 客户端接入改明文ak配置(headers.Authorization), 去除XQ_API_KEY环境变量写法	2026-09-04 15:45:55 +08:00
xiaoqu	517b6532f6	chore: .kimi-code/mcp.json 移出版本控制(改明文ak后不宜入库), 加入.gitignore	2026-09-04 15:42:55 +08:00
xiaoqu	e331650dcd	merge: dev配置明文化	2026-09-04 14:28:53 +08:00
xiaoqu	af23ced207	feat(config): dev环境DB/Redis连接信息明文写入application-dev.yml, 不再走环境变量; 同步README/.env.example/设计文档	2026-09-04 14:28:53 +08:00