From 80b0035ba64429205595c7a80414dc7f0964c4cf Mon Sep 17 00:00:00 2001 From: xiaoqu Date: Fri, 4 Sep 2026 15:45:55 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=A2=E6=88=B7=E7=AB=AF=E6=8E=A5?= =?UTF-8?q?=E5=85=A5=E6=94=B9=E6=98=8E=E6=96=87ak=E9=85=8D=E7=BD=AE(header?= =?UTF-8?q?s.Authorization),=20=E5=8E=BB=E9=99=A4XQ=5FAPI=5FKEY=E7=8E=AF?= =?UTF-8?q?=E5=A2=83=E5=8F=98=E9=87=8F=E5=86=99=E6=B3=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- xiaoqu-agent-service/README.md | 17 +++++++++-------- .../doc/agent-mcp-service-design.md | 10 ++++++---- 2 files changed, 15 insertions(+), 12 deletions(-) diff --git a/xiaoqu-agent-service/README.md b/xiaoqu-agent-service/README.md index 0a4c585..84e48cc 100644 --- a/xiaoqu-agent-service/README.md +++ b/xiaoqu-agent-service/README.md @@ -130,11 +130,11 @@ cp deploy/.env.example deploy/.env.dev # 填写 dev 凭据（已 gitignore， ## 测试 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 握手） @@ -173,27 +173,28 @@ 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>" ``` ## codegen（run-once） diff --git a/xiaoqu-franchisee/doc/agent-mcp-service-design.md b/xiaoqu-franchisee/doc/agent-mcp-service-design.md index c48e916..543f4a8 100644 --- a/xiaoqu-franchisee/doc/agent-mcp-service-design.md +++ b/xiaoqu-franchisee/doc/agent-mcp-service-design.md @@ -105,21 +105,23 @@ 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 " + } } } } ``` - Claude Code：`claude mcp add --transport http xiaoqu https://mcp.<域名>/mcp --header "Authorization: Bearer "`。 -- ak 明文只出现在客户端环境变量/配置与签发时刻；服务端只存 SHA-256 哈希。 +- ak 明文只出现在本机客户端配置与签发时刻；服务端只存 SHA-256 哈希，含 ak 的客户端配置文件不得提交版本库。 ### 5.2 Web 管理后台（四个页面） @@ -140,7 +142,7 @@ 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 都可读"（如权限拒绝时提示应由管理员在哪个作用域开通）。 ## 6. 技术栈与工程结构