chrome-plugin-wiki

一个本地优先的 Chrome 扩展 + 本机 HTTP bridge。

当前能力：

• 扩展保存网页素材到 IndexedDB（主存储）
• 保存后同步到本机 bridge（便于 OpenClaw/CLI 检索）
• 本机 bridge 提供 POST /sync、GET /search、GET /list、POST /summarize（兼容保留 POST /save）
• OpenClaw 或其他工具可通过本机 HTTP API 检索素材（数据来自同步后的本机库）

---

1. 环境要求

• Node.js >= 18
• Chrome（开发者模式加载扩展）

---

2. 快速开始

2.1 安装依赖（如有）

npm install

2.2 配置 .env

复制示例文件并填写：

cp .env.example .env

关键项：

• WIKI_BRIDGE_PORT：本机服务端口，默认 3456
• WIKI_BRIDGE_API_KEY：bridge 访问口令（随机长串）
• OPENAI_API_KEY：用于 /summarize 的模型密钥（可选）
• OPENAI_BASE_URL、OPENAI_MODEL：可选，兼容 DeepSeek/OpenAI

2.3 启动本机服务

npm run server

启动后请确认两点：

• 终端出现 wiki-bridge 监听 ...，表示服务已启动
• 地址中的端口与你 .env 的 WIKI_BRIDGE_PORT 一致；不一致就停止进程后按当前 .env 重启

示例输出：

wiki-bridge 监听 http://127.0.0.1:<WIKI_BRIDGE_PORT>

---

3. 加载扩展

1. 打开 chrome://extensions
2. 开启「开发者模式」
3. 点击「加载已解压的扩展程序」
4. 选择项目内 extension/ 目录
5. 打开扩展的「选项页」，填写：
   • Bridge 地址（必填，例如 http://127.0.0.1:<WIKI_BRIDGE_PORT>）
   • X-API-Key（必须与 .env 的 WIKI_BRIDGE_API_KEY 一致）

---

4. 使用方式

4.1 保存素材（双写+同步）

在任意网页打开扩展弹窗：

• 点击「AI 生成摘要」可调用本机 POST /summarize 生成摘要与标签
• 点击「保存到 IndexedDB 并同步到本机」会先写入 IndexedDB，再调用本机 POST /sync 同步

成功会显示返回的 id。

4.2 Omnibox 检索（地址栏 s）

• 在 Chrome 地址栏输入 s 后按空格（或 Tab）进入扩展检索模式
• 继续输入关键词即可调用本机 GET /search
• 建议项中带 [来自插件] 前缀的是扩展返回结果，其余可能是 Chrome 默认建议

4.3 AI 摘要与关键词（可选）

点击「AI 摘要与标签」会调用本机 POST /summarize。
需先在 .env 中配置 OPENAI_API_KEY 并重启 npm run server。

---

5. API 示例

以下命令都需要带 X-API-Key。

健康检查

curl -s -H "X-API-Key: <YOUR_KEY>" "http://127.0.0.1:<WIKI_BRIDGE_PORT>/health"

保存素材

curl -s -X POST \
  -H "X-API-Key: <YOUR_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","title":"示例","brief":"摘要","keywords":"标签"}' \
  "http://127.0.0.1:<WIKI_BRIDGE_PORT>/sync"

检索素材

curl -s -H "X-API-Key: <YOUR_KEY>" \
  "http://127.0.0.1:<WIKI_BRIDGE_PORT>/search?q=rag&limit=10"

返回字段已收敛为：id, title, url, brief, keywords, savedAt, score。

最近列表

curl -s -H "X-API-Key: <YOUR_KEY>" \
  "http://127.0.0.1:<WIKI_BRIDGE_PORT>/list?limit=20"

---

6. 常见问题

• 保存时报 401 unauthorized
X-API-Key 与 .env 的 WIKI_BRIDGE_API_KEY 不一致。

• 保存时报 404 not_found
  多半是旧进程占着端口。先确认当前启动的是本项目最新 bridge/server.js。

• 保存时报连接失败
  先确认 npm run server 仍在运行，且端口与扩展设置一致。

---

7. 测试

npm test