navhub-skills

将你的 NavHub 个人知识库变成 AI Agent 技能。

English | 中文文档

navhub-skills 将你的书签、笔记、RSS 订阅和生图能力，封装为任何 AI Agent 可调用的技能——兼容 Model Context Protocol (MCP)。

它是什么？

NavHub 是一个个人导航与知识管理平台（书签、笔记、RSS、AI 工作台）。navhub-skills 将 NavHub 的开放 API 封装为技能注册表——AI Agent 可以发现并调用的结构化工具集合。

你的 NavHub 数据
  ├── 书签      ──┐
  ├── 笔记      ──┼──▶  navhub-skills  ──▶  任何 AI Agent
  ├── RSS 订阅  ──┤        (MCP)            (Claude、GPT 等)
  └── 图像生成  ──┘

内置技能

| 技能 | 说明 | 所需权限 | |------|------|---------| | memory | 跨会话读写持久化笔记 | notes:read、notes:write | | bookmarks | 搜索和管理书签库 | bookmarks:read、bookmarks:write | | rss | 访问 RSS 订阅和文章 | rss:read | | image-gen | 根据文字描述生成图片 | image:generate |

快速开始

第一次用？ 不带密钥直接把本服务加进 AI 客户端，然后问它任何与 NavHub 相关的问题， 它会把配置步骤讲给你听。服务不会静默失败：没有密钥（或密钥无效）时它照常启动， 只暴露一个 navhub_setup 工具返回引导。

想随时自查连接状态，在终端直接运行：

npx navhub-skills

在终端直跑时它是连接自检命令，被 AI 客户端拉起时它是 MCP 服务 —— 不需要任何参数。

第一步：获取 NavHub API Key

登录 navhub.info → 企业管理 → API Keys → 新建密钥。

密钥形如 nhk_xxxxxxxx，只显示一次，请立即复制保存。

选择需要的权限范围（notes:read、notes:write、bookmarks:read 等）。

第二步：查看可用技能

curl https://navhub.info/open/v1/skills \
  -H "Authorization: Bearer 你的API密钥"

第三步：获取 MCP 清单

curl https://navhub.info/open/v1/mcp.json \
  -H "Authorization: Bearer 你的API密钥"

返回完整的 MCP 工具列表，可直接用于任何 MCP 兼容客户端。

在 Claude Desktop 中使用

在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "navhub": {
      "command": "npx",
      "args": ["-y", "navhub-skills"],
      "env": {
        "NAVHUB_API_KEY": "你的API密钥",
        "NAVHUB_BASE_URL": "https://navhub.info"
      }
    }
  }
}

然后你可以对 Claude 说：

• "记住项目截止日期是 3 月 15 日"
• "在我的书签里搜索 React 性能优化相关的文章"
• "总结今天我的 RSS 订阅中未读的文章"
• "为我的 AI 博客文章生成一张封面图"

API 参考

认证方式

所有端点均需在请求头中携带 API 密钥：

Authorization: Bearer nhk_xxxxxxxxxxxxxxxx

技能发现

| 端点 | 说明 | |------|------| | GET /open/v1/skills | 列出当前 API Key 可访问的所有技能 | | GET /open/v1/skills/:name | 获取单个技能的完整清单 | | GET /open/v1/mcp.json | 完整 MCP 工具清单 |

memory 技能（持久化记忆）

| 动作 | 方法 | 路径 | 说明 | |------|------|------|------| | remember | POST | /open/v1/memory/notes | 写入一条记忆（支持 Markdown） | | recall | GET | /open/v1/memory/notes/search | 关键词检索（?q=） | | list | GET | /open/v1/memory/notes | 列出记忆（支持文件夹过滤） | | get | GET | /open/v1/memory/notes/:id | 获取单条记忆 | | update | PUT | /open/v1/memory/notes/:id | 更新记忆 | | forget | DELETE | /open/v1/memory/notes/:id | 删除记忆 | | graph | GET | /open/v1/memory/notes/graph | 获取双链图谱（节点+边） | | folders | GET | /open/v1/memory/notes/folders | 列出记忆分组 | | links | GET | /open/v1/memory/notes/:id/links | 获取某条记忆的双链关系 |

bookmarks 技能（书签库）

| 动作 | 方法 | 路径 | 说明 | |------|------|------|------| | search | GET | /open/v1/bookmarks/search | 关键词搜索（?q=、limit） | | list | GET | /open/v1/bookmarks | 列出书签（标签/文件夹过滤） | | get | GET | /open/v1/bookmarks/:id | 获取单个书签 | | save | POST | /open/v1/bookmarks | 保存新书签 | | update | PUT | /open/v1/bookmarks/:id | 更新书签 | | delete | DELETE | /open/v1/bookmarks/:id | 删除书签 |

rss 技能（RSS 信息流）

| 动作 | 方法 | 路径 | 说明 | |------|------|------|------| | list_feeds | GET | /open/v1/rss/feeds | 列出所有 RSS 订阅源 | | list_articles | GET | /open/v1/rss/articles | 列出文章（未读、收藏过滤） | | search | GET | /open/v1/rss/articles/search | 关键词搜索文章 | | get_article | GET | /open/v1/rss/articles/:id | 获取文章完整内容 | | mark_read | PUT | /open/v1/rss/articles/:id/read | 标记为已读 | | toggle_star | PUT | /open/v1/rss/articles/:id/star | 收藏/取消收藏 |

image-gen 技能（图像生成）

| 动作 | 方法 | 路径 | 说明 | |------|------|------|------| | generate | POST | /open/v1/image-gen | 根据描述生成图片 | | list_models | GET | /open/v1/image-gen/models | 列出可用模型 |

生成请求示例：

{
  "prompt": "a minimal bookmark icon on white background",
  "aspect_ratio": "1:1",
  "model": "flux-schnell",
  "num_images": 1
}

权限范围说明

| Scope | 说明 | |-------|------| | bookmarks:read | 读取书签 | | bookmarks:write | 创建、更新、删除书签 | | notes:read | 读取笔记 | | notes:write | 创建、更新、删除笔记 | | rss:read | 读取 RSS 订阅和文章 | | rss:write | 标记已读、收藏文章 | | image:generate | 生成图片 |

自托管

navhub-skills 内置于 NavHub 后端。自托管步骤：

git clone https://github.com/shuaninfo/bookmark
cd bookmark
cp config/app.ini.example config/app.ini
# 编辑 config/app.ini 配置数据库等信息
make server

技能 API 将在 http://localhost:8080/open/v1/ 上可用。

使用示例

Claude：记住一个决策

"记住我们决定用 PostgreSQL 替代 MySQL，原因是更好的 JSON 支持。"

Claude 调用 memory__remember → 以标题+内容格式存入你的 NavHub 笔记。

Claude：知识检索

"在我的书签里找所有收藏的 React Server Components 相关内容"

Claude 调用 bookmarks__search?q=react+server+components → 返回匹配书签列表。

Claude：每日简报

"总结一下今天 RSS 订阅里未读的文章"

Claude 调用 rss__list_articles?unread=true → 读取文章 → 生成摘要。

Claude：带图片的笔记

"帮我创建一篇关于个人生产力系统的笔记，并生成一张封面图"

Claude 先调用 image_generate 生成图片，再调用 memory__remember 将图片 URL 嵌入 Markdown 存入笔记。

更多示例请查看 examples/ 目录，包含 Claude Desktop 配置和所有端点的 curl 示例。

参与贡献

欢迎提交 Issue 和 PR。如需请求新技能，请使用 Skill Request 模板。

开源协议

MIT