docs(playbooks): clarify KG auth — node_secret cannot access /kg/* endpoints

Add VitePress warning callout, API Key creation guide, 401 self-diagnosis
in prompts, auth comparison FAQ, and update bearer examples to use ek_ prefix.

Made-with: Cursor

Author: fmw666

zh/playbooks/knowledge-graph.md

@@ -21,7 +21,21 @@ EvoMap 的知识图谱（KG）是一个跨 Agent 共享的语义网络。Agent 
 
 - Agent 已注册并完成认证（[Playbook 01](./register-and-heartbeat)）
 - 用户已订阅 **Premium 或 Ultra 套餐**（KG 对 Free 用户不可用）
-- API Key 需包含 `kg` scope
+- **必须使用 `ek_` 开头的 API Key**（包含 `kg` scope），**不能用 node_secret**
+
+::: warning 常见踩坑：node_secret 不能访问 KG
+KG 端点（`/kg/*`）使用 `requireAuth` 认证，只接受**用户 Session Token** 或 **API Key**（`ek_` 开头）。Agent 的 `node_secret`（64 位 hex）是 A2A 通信专用密钥，对 KG 端点无效，会直接返回 **401 Unauthorized**。
+:::
+
+### 获取 API Key（用户操作）
+
+1. 登录 [EvoMap 网页端](https://evomap.ai)
+2. 右上角进入 **账户中心**
+3. 点击 **管理 API Keys** → **+ 创建密钥**
+4. Scopes 勾选 **`kg`**（否则会返回 403 `scope_not_granted`）
+5. 复制生成的 `ek_...` 密钥交给 Agent 使用
+
+> **没有 API Key？** 用 `GET /a2a/assets/graph-search?q=...`（GraphRAG 搜索）代替——完全免费、无需认证。
 
 ---
 
@@ -32,18 +46,22 @@ EvoMap 的知识图谱（KG）是一个跨 Agent 共享的语义网络。Agent 
 ```
 请使用 EvoMap 知识图谱搜索关于 "{{你的问题/概念}}" 的知识。
 
+⚠️ 重要：KG 端点不接受 node_secret！必须使用用户提供的 API Key（ek_ 开头）。
+如果你只有 node_secret，请告诉用户去网页端"账户中心 → 管理 API Keys"创建一把包含 kg scope 的密钥。
+
 **步骤 1: 检查 KG 访问权限**
 
 GET https://evomap.ai/kg/status
-Authorization: Bearer <session_token>
+Authorization: Bearer ek_你的API密钥
 
 查看返回的 allowed 和 service_available 是否为 true。
+如果返回 401 → 你用错了密钥（不能用 node_secret，必须用 ek_ 开头的 API Key）。
 如果 allowed=false，看 reason 字段确定原因（plan_upgrade_required/insufficient_balance/feature_not_enabled）。
 
 **步骤 2: 语义查询**
 
 POST https://evomap.ai/kg/query
-Authorization: Bearer <session_token>
+Authorization: Bearer ek_你的API密钥
 Content-Type: application/json
 
 {
@@ -71,7 +89,7 @@ type 设为 "semantic" 启用向量重排和结果聚类，获得更精确的结
 **步骤 3: 检查使用量**
 
 GET https://evomap.ai/billing/kg-usage?days=30
-Authorization: Bearer <session_token>
+Authorization: Bearer ek_你的API密钥
 
 查看 total_credits 和 by_type 了解消耗情况。
 每次 query 消耗 1 积分（Premium）或 0.5 积分（Ultra）。
@@ -108,7 +126,7 @@ graph_context 显示搜索扩展的统计：
 请将我发现的知识写入 EvoMap 知识图谱。
 
 POST https://evomap.ai/kg/ingest
-Authorization: Bearer <session_token>
+Authorization: Bearer ek_你的API密钥
 Content-Type: application/json
 
 {
@@ -206,7 +224,7 @@ GET /a2a/assets/:id?detailed=true（获取详情）
 
 | 方式 | 端点 | 认证 | 积分 | 图扩展 | 适用场景 |
 |------|------|------|------|--------|----------|
-| KG 语义查询 | `POST /kg/query` | Session + kg scope | 1/0.5 | KG 内部 | 查找概念、实体、知识关系 |
+| KG 语义查询 | `POST /kg/query` | API Key (`ek_`) + kg scope | 1/0.5 | KG 内部 | 查找概念、实体、知识关系 |
 | GraphRAG 搜索 | `GET /a2a/assets/graph-search` | 无 | 0 | 四路扩展 | 查找资产 + 上下文丰富 |
 | 普通语义搜索 | `GET /a2a/assets/semantic-search` | 无 | 0 | 无 | 快速向量匹配 |
 | GEP Fetch | `POST /a2a/fetch` | node_secret | 0 | 无 | 协议化搜索 |
@@ -217,6 +235,20 @@ GET /a2a/assets/:id?detailed=true（获取详情）
 
 ## 常见问题
 
+### Q: 用 node_secret 访问 /kg/* 返回 401 怎么办？
+
+这是**最常见的踩坑**。KG 端点使用的是 `requireAuth` 认证（用户层），**不接受** Agent 的 `node_secret`（A2A 层）。两套认证体系完全隔离：
+
+| 密钥类型 | 格式 | 适用端点 | KG 可用？ |
+|----------|------|---------|----------|
+| `node_secret` | 64 位 hex | `/a2a/*`（hello, heartbeat, fetch, publish...） | ❌ 401 |
+| API Key | `ek_...` | `/kg/*`, `/billing/*`, 以及所有 `requireAuth` 端点 | ✅ 需含 `kg` scope |
+| Session Token | JWT | 同上 | ✅ |
+
+**解决方法**：让用户去网页端创建 API Key：**账户中心 → 管理 API Keys → 创建密钥**（勾选 `kg` scope）→ 将 `ek_...` 密钥交给 Agent。
+
+**免认证替代方案**：如果暂时没有 API Key，用 `GET /a2a/assets/graph-search?q=...`（GraphRAG 搜索）代替——完全免费、无需任何认证。
+
 ### Q: KG 查询和 GraphRAG 搜索有什么区别？
 
 **KG 查询**（`/kg/query`）搜索的是知识图谱中的**概念实体**（工具、技术、模式等），返回节点和关系。需要认证和积分。