vault backup: 2026-11-07 16:33:44

2026-11-07 16:33:55 +08:00
commit 7015312702
1208 changed files with 132432 additions and 0 deletions
@@ -0,0 +1,122 @@
+
+> 地址：`http://bh.vps.honor3.com:3000`
+> 一句话：**读用 MCP（免密钥），写用 REST（要 `X-Ingest-Key`）**。
+
+---
+
+## 1. 接入 MCP（只读，无需密钥）
+
+MCP 端点是 `POST http://bh.vps.honor3.com:3000/mcp`，走标准 JSON-RPC 2.0，
+**不校验任何密钥**，只暴露只读工具。
+
+客户端配置（Claude Desktop / Cursor / Cherry Studio 通用）：
+
+```json
+{
+  "mcpServers": {
+    "awesome-index": {
+      "url": "http://bh.vps.honor3.com:3000/mcp"
+    }
+  }
+}
+```
+
+手动测试（curl）：
+
+```bash
+curl -s -X POST "http://bh.vps.honor3.com:3000/mcp" \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
+```
+
+⚠️ 必须带 `Accept: application/json, text/event-stream`，否则会被拒。
+
+---
+
+## 2. 四个只读工具
+
+| 工具  | 参数  | 用途  |
+| --- | --- | --- |
+| `search_entries` | `q`（必填，关键字）、`limit`（1–50，默认 20） | 按关键字/类型/标签搜索 |
+| `get_entry` | `slug`（必填，也可传标题关键字自动匹配） | 取单条详情 |
+| `random_entry` | 无   | 随机抽一条，用于发现 |
+| `list_tags` | 无   | 列全部标签组与数量 |
+
+调用示例：
+
+```bash
+curl -s -X POST "http://bh.vps.honor3.com:3000/mcp" \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
+       "params":{"name":"search_entries","arguments":{"q":"自托管相册","limit":5}}}'
+```
+
+结果在 `result.content[0].text` 里，是一段 JSON 字符串，需再解析一次。
+
+---
+
+## 3. 提交条目（写入，要密钥）
+
+```bash
+curl -X POST "http://bh.vps.honor3.com:3000/api/ingest/entry" \
+  -H "X-Ingest-Key: sk-test" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "title": "MinerU",
+    "url": "https://github.com/opendatalab/MinerU",
+    "type": "工具",
+    "summary": "PDF/文档转 Markdown 的解析引擎",
+    "tags": ["Python", "OCR", "文档解析"]
+  }'
+```
+
+成功返回：`{"ok":true,"data":{"created":true,"id":54,"status":"pending"}}`
+
+中文内容建议存成 `.json` 文件再 `-d @file.json`，避免 shell 编码踩坑；
+Windows 下用 Python `json.dumps(..., ensure_ascii=False).encode('utf-8')` 最稳。
+
+---
+
+## 4. 字段规则
+
+| 字段  | 必填  | 约束  |
+| --- | --- | --- |
+| `title` | ✅   | 标题  |
+| `url` | ✅   | 合法 URL，**用于去重** |
+| `type` | ✅   | 只能是：`微服务` `SaaS` `网站` `工具` `应用` `脚本` `插件` |
+| `summary` | ❌   | ≤ 200 字符 |
+| `description_md` | ❌   | ≤ 5000 字符，支持 Markdown |
+| `license` | ❌   | 如 `MIT`、`GPL-3.0` |
+| `stars` | ❌   | 整数  |
+| `tags` | ❌   | 字符串数组 |
+| `status` | ❌   | `pending` / `active` |
+
+**`slug` 不是合法字段**，传了会被静默丢弃。
+
+---
+
+## 5. 五个坑（记牢就够）
+
+1. **认证头是 `X-Ingest-Key`**。`Authorization: Bearer`、`X-API-Key`、`?key=` 全部 403。
+2. **MCP 免密钥 ≠ 密钥有效**。`/mcp` 根本不查 key，别拿它验证密钥。
+3. **提交后默认 `pending`**，前台搜不到是正常的，要等管理员审核变 `active`。
+4. **同 URL 重复提交返回 200 `created:false`**，不是报错，说明已存在。
+5. **`/api/entries` 也能写**（未登录时回退到 AI key 校验），但推荐用 `/api/ingest/entry`。
+
+---
+
+## 6. 典型工作流
+
+```
+1. search_entries 查重 → 已有就 get_entry 看详情，别重复提交
+2. WebSearch / WebFetch 收集项目信息
+3. 组装 JSON（title + url + type 三个必填）
+4. POST /api/ingest/entry（X-Ingest-Key）
+5. 记下返回的 id，状态 pending
+```
+
+---
+
+*整理于 2026-10-27 · 已在 MinerU / Mio CUA / Windows-Use / Transub / TinyJS / Quickemu / nanoMuse 七个条目上验证*