docs: 客户端接入改明文ak配置(headers.Authorization), 去除XQ_API_KEY环境变量写法

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）

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 <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 管理后台（四个页面）
 
@@ -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. 技术栈与工程结构