English | 简体中文
先收藏，后评估，按需安装。让 AI Agent 扩展保持可控。
## 为什么需要 Skills Bookmark？ AI Agent 的 skills、MCP server 和插件越来越多。看到一个有用的扩展时，直接安装会让 Agent 的启动、发现和维护成本不断增加；不安装，又容易忘记或错过。 Skills Bookmark 提供一个轻量的本地收藏层：把扩展保存为候选项，记录来源、用途、兼容 Agent、版本和风险状态，等真正需要时再检查并安装。 > **核心理念：** 收藏不等于启用，发现不等于信任。 ## 功能 - **收藏**：保存 GitHub、Gitee 仓库或 `owner/repo` 短名，自动规范化地址并去重。 - **记录**：提取 README、SKILL.md 和仓库元数据，记录用途、能力标签、支持的 Agent 和 commit。 - **列表**：用本地浏览器表格查看未安装收藏；可筛选已安装和归档记录。 - **图谱**：展示自动推断与人工确认的关系，并保留关系类型、证据、置信度和来源标记。 - **检查**：比较当前 commit 与最新版本，扫描危险 shell、凭据读取、持久化命令和提示词注入模式。 - **审计**：统一检查静态行为、安装脚本、依赖、许可证和网络域名；按需整合 OSV、`npm audit` 与 `pip-audit` 证据。 - **体检**：生成稳定计划，逐项复核，并在确认后应用保留、忽略、归档或首选 skill 决策。 - **导入**：选择性导入已安装 skills、MCP 和插件，先预览候选，再写入本地历史。 - **安装**：安装 skill 到 Codex、Claude Code 或 OpenClaw；使用宿主原生命令或显式 JSON 配置安装 MCP 和插件。 - **升级**：比较远程版本、文件变化和风险，确认后备份并升级。 - **回滚**：将最近一次替换恢复到备份版本，同时保留当前版本，避免升级失败后无法恢复。 - **归档**：移除收藏时保留记录，方便回溯和重新整理。 - **迁移**：通过脱敏 JSON 导出收藏库，并在另一台机器预览、确认后合并。 - **试运行**：只在用户提供明确命令并确认后，使用禁网、只读容器进行隔离试运行。 - **本地优先**：标准库 Python + SQLite，无常驻服务，无前端构建依赖。 ## 快速开始 ### 安装到 Agent 本项目本身是一个 Agent skill。请使用目标 Agent 自己的 skill 安装机制，将下面的开源仓库安装为 `skills-bookmark`： ```text https://gitee.com/synovation/skills-bookmark.git ``` 不同 Agent 的安装入口和配置方式可能不同，Skills Bookmark 不要求用户记住统一的 Python 或 shell 命令。安装完成后，确认该 Agent 能识别 `$skills-bookmark` 即可。 ### 在 Codex 中使用 安装到 Codex 后，可以直接使用自然语言： ```text 收藏 https://gitee.com/example/example-skill.git 列出我的 skills 收藏 检查 skill-navigator 是否有更新或安全风险 打开收藏图谱 扫描我当前安装的 Codex skills 预览导入已安装但未记录的 skills，只导入 browser automation 相关项目 帮我体检当前扩展，找出重复能力和高风险项目 创建一份体检计划，然后逐项帮我复核 浏览器自动化能力优先保留 browser-one 把收藏库导出到 ~/skills-bookmark-library.json 安装 skill-navigator，先展示安装计划，等我确认后再执行 升级 skill-navigator，展示版本差异和风险后等我确认 回滚 skill-navigator 最近一次替换，先展示备份和目标路径 把 skill-a 和 skill-b 标记为可替代关系，证据是两者都提供同一套浏览器测试流程 ``` 显式调用方式： ```text $skills-bookmark 收藏 https://github.com/example/example-skill ``` ### 在其他 Agent 中使用 将本仓库按 Claude Code 或其他 Agent 的 skill 安装规范加入后，使用同样的自然语言请求： ```text 收藏 https://github.com/owner/repo 列出我的扩展收藏 检查 browser-mcp 的版本和安全风险 打开扩展关系图谱 体检 Claude Code 当前 skills 和 MCP 扫描我的 Cursor skills 体检 Gemini CLI skills 列出 Qwen Code 已安装 skills ``` 目前为 Codex、Claude Code、OpenClaw、Cursor、Gemini CLI、Qwen Code、WorkBuddy 和 Kimi 提供 skill 目录适配；其他 Agent 可使用显式自定义目录 adapter。MCP 和插件生命周期支持范围更窄，因为这类操作必须依赖稳定、明确的宿主接口。 ## Agent 使用 Skills Bookmark 支持以下自然语言意图： - **收藏**：收藏一个完整 URL，或解析 `owner/repo` 短名。 - **列表**：打开收藏表格，默认只显示尚未安装的扩展。 - **图谱**：打开扩展之间的相似、替代和 Agent 兼容关系图。 - **检查**：比较最新版本并生成静态安全风险报告。 - **审计**：整合静态、安装脚本、依赖、许可证、域名及可选漏洞数据库证据，并可导出 JSON/HTML 报告。 - **扫描**：读取 Codex、Claude Code、OpenClaw 的已安装 skill；同时读取宿主公开的 MCP/plugin 清单，不执行扩展代码。 - **导入**：预览并选择已安装的 skill、MCP 或插件，确认后加入安装历史。 - **体检**：报告问题、生成计划、复核明确决策，并应用已确认的保留/忽略/归档/首选治理。 - **导出 / 恢复**：通过预览合并，在机器之间迁移脱敏收藏库。 - **隔离试运行**：只运行用户提供的命令，使用现有本地镜像、禁网和只读容器。 - **安装**：先展示来源、revision、目标目录和替换策略；用户确认后才执行安装。 - **升级**：先比较远程版本、文件差异和风险；确认后复用备份安装流程。 - **回滚**：先展示备份路径和目标路径；用户确认后才恢复上一版本。 - **关系**：人工关系必须提供证据和置信度，并且不会被自动图谱重建覆盖。 - **移除**：先预览，再归档并保留历史；永久删除需要额外明确选择。 Codex、Claude Code 和 OpenClaw 已提供 skill adapter。Codex/Claude Code MCP 与插件通过宿主原生命令管理；OpenClaw MCP/Plugin 使用用户显式指定的 JSON 配置文件，不猜测默认路径或私有 schema。 ## 实测示例与结果 下面的请求均通过 Agent 触发，结果来自本机隔离样例库或只读宿主扫描。示例中的编号、版本和数量会随你的环境变化；示例不会修改真实收藏或宿主配置。 ### 收藏 请求： ```text 收藏 https://github.com/GrubbyLee/skill-manager.git ``` 结果： ```text 已收藏 #1 skill-navigator 类型：skill 来源：https://github.com/GrubbyLee/skill-manager#path=integrations/skill-navigator 能力：skill-management, mcp-management 支持：codex, claude-code 状态：bookmarked ``` 短名也可以使用： ```text 收藏 GrubbyLee/skill-manager ``` 如果 GitHub 和 Gitee 都有同名仓库，Agent 会列出候选，不会自动猜平台： ```text 发现多个候选： - github: https://github.com/GrubbyLee/skill-manager - gitee: https://gitee.com/GrubbyLee/skill-manager 请指定要收藏的来源。 ``` ### 列表和图谱 请求： ```text 列出我的 skills 收藏 ``` 结果： ```text 默认展示尚未安装的收藏：2 bookmarked 已安装和归档记录仍保存在历史中。 ```  请求： ```text 打开收藏图谱，只看未安装项目 ``` 结果： ```text 已打开关系图谱。 节点：skills、MCP、plugins、Agent 关系：similar_to、alternative_to、works_with ```  点击节点后会显示关系证据： ```text alternative_to -> browser-mcp 置信度：82% 来源：inferred 证据：Shared capabilities: browser-automation, testing ``` 移动视口也支持同一页面：  ### 检查和审计 请求： ```text 检查 skill-navigator 是否有更新或安全风险 ``` 结果： ```text update=current risk=none 静态模式发现：0 限制：未执行仓库代码；未查询依赖漏洞数据库。 ``` 发现风险时会给出文件和行号： ```text risk=high [high] install.sh:12 - Downloads content directly into a shell ``` 请求： ```text 审计 skill-navigator 的依赖风险 ``` 结果可能是： ```text 依赖文件：package.json, package-lock.json 锁文件：存在 漏洞数据库：已通过 npm audit 查询 ``` 没有工具或锁文件时会明确说明： ```text 未执行漏洞数据库审计。 原因：未找到可用审计工具或依赖锁文件。 已完成：依赖文件清单和静态风险扫描。 ``` 完整安全报告请求： ```text 审计 skill-navigator，查询 OSV，并把 HTML 安全报告导出到 ~/skill-navigator-security.html ``` 结果： ```text risk_level=medium 静态发现=3 安装脚本=1 许可证=27（2 项需要复核） 域名=14（1 个存在复核信号） OSV queried=true，漏洞=0 报告：~/skill-navigator-security.html 限制：干净报告不等于绝对安全。 ``` ### 扫描、导入和体检 请求： ```text 扫描我当前安装的 Codex skills、MCP 和 plugins ``` 本机只读结果示例： ```text codex: 72 skills, 2 MCP servers, 0 plugins 没有修改本地配置。 ``` 请求： ```text 预览导入当前未记录的 Codex skills，只导入 testing 相关项目 ``` 结果： ```text Preview found 9 currently untracked Codex skills with the testing capability. Confirmation required: Yes. No items were imported, installed, or removed. ``` 确认后： ```text 确认导入刚才列出的 9 个项目 ``` 结果： ```text Imported 9 Codex skills into installation history. 状态：installed ``` 其他筛选请求： ```text 只导入名为 webapp-testing 的 skill 只导入 risk=none 的项目 导入 MCP，但不要导入 plugin ``` 请求： ```text 帮我体检当前 Codex 扩展，找出高风险、重复能力和未追踪项目 ``` 结果： ```text Codex doctor: 72 installed, 71 untracked, 0 high-risk, 32 duplicate groups, 1 conflict Recommended actions: - import: webapp-testing - Installed skill is not in the bookmark history. - compare: browser-one / browser-two - Skills share multiple concrete capabilities. - resolve-conflict: design-guide - Multiple installed skills resolve to the same normalized name. ``` 没有可观测会话日志时，不会武断判断“长期未使用”： ```text Usage: unavailable; no stable session logs were found, so no unused claim was made. ``` 生成稳定的治理计划： ```text 按最近 30 天可观测数据，为 Cursor skills 创建体检计划 ``` ```text plan=dp-20260825103000-a1b2c3 A001 import webapp-testing A002 compare browser-one / browser-two A003 review-unused old-helper 尚未应用任何治理决策。 ``` 逐项复核： ```text 对计划 dp-20260825103000-a1b2c3：保留 A001；A002 首选 browser-one；忽略 A003。先预览复核结果。 ``` ```text confirmed=false A001=retain A002=prefer:browser-one A003=ignore 下一步：确认相同的复核决策。 ``` 确认复核后，应用仍有独立确认边界： ```text 应用已复核的体检计划，但先展示精确动作 ``` ```text confirmed=false actions=3 archive 不会删除已安装文件；ignore 只抑制对应的后续建议 下一步：确认 doctor apply。 ``` 存在本地日志时，使用证据标记为 `partial`；没有受支持日志时标记为 `unavailable`，不会把它包装成完整的真实使用统计。 ### 收藏库导出与恢复 请求： ```text 把全部收藏历史导出到 ~/skills-bookmark-library.json ``` ```text 导出项目=18 人工关系=4 已排除=安装路径、备份、检查记录、会话、体检计划、密钥 ``` 恢复请求： ```text 把 ~/skills-bookmark-library.json 合并到当前收藏库，只预览 ``` ```text confirmed=false mode=merge items=18 导出的 installed 记录会变成 bookmark；不会改动宿主中的扩展 ``` 只有明确确认后才执行合并。 ### 隔离试运行 请求： ```text 使用本机已有 python:3.12-alpine 镜像，对 skill-navigator 试运行 python -V，先展示隔离计划 ``` ```text confirmed=false network=none filesystem=read-only capabilities=dropped memory=512m image_pull=disabled command=python -V ``` 确认后才执行命令。隔离输出只是补充证据，不是安全保证。 ### 安装 skill 请求： ```text 把 skill-navigator 安装到 Claude Code，先展示安装计划 ``` 预览结果： ```text agent=claude-code source=https://github.com/GrubbyLee/skill-manager revision=111515dad6ca target=~/.claude/skills/skill-navigator conflict=none confirmed=false ``` 如果目标已存在： ```text target_exists=true conflict=target_exists_requires_replace 需要用户明确允许替换。 ``` ### 安装 MCP MCP 必须提供明确的 URL 或 stdio 命令： ```text 把这个 MCP 安装到 Codex： 名称 browser HTTP URL https://mcp.example.com/mcp Bearer token 环境变量 MCP_TOKEN 先预览，不要执行 ``` 结果： ```text kind=mcp agent=codex name=browser transport=http url=https://mcp.example.com/mcp bearer_token_env_var=MCP_TOKEN environment_values=redacted confirmed=false ``` Claude Code stdio 示例： ```text 把名为 browser 的 MCP 安装到 Claude Code： 命令 npx 参数 @browser/mcp server 环境变量 BROWSER_TOKEN=secret 先展示计划 ``` 结果只展示变量名，不展示值： ```text environment_keys=BROWSER_TOKEN environment_values=redacted ``` OpenClaw 示例： ```text 使用 OPENCLAW_MCP_CONFIG 指定的 JSON 配置，把 browser MCP 写入 OpenClaw，先预览 ``` 未设置配置文件时： ```text warning: OpenClaw MCP config is not configured; set OPENCLAW_MCP_CONFIG explicitly ``` ### 安装 Plugin 插件必须明确指定 marketplace： ```text 把 example-plugin@team-market 安装到 Codex，先预览 ``` 结果： ```text kind=plugin agent=codex selector=example-plugin@team-market confirmed=false 需要确认后才调用 Codex 原生 plugin add。 ``` Claude Code 使用同样的 selector： ```text 把 example-plugin@team-market 安装到 Claude Code，先展示计划 ``` OpenClaw Plugin 需要先配置 `OPENCLAW_PLUGINS_FILE`，否则只报告配置缺失，不创建猜测文件。 ### 升级与回滚 请求： ```text 升级 skill-navigator 到最新版本，先展示 revision、文件差异和风险 ``` 预览结果： ```text current_revision=111515dad6ca latest_revision=222626ebe7db update_available=true changed_files=3 risk=none confirmed=false ``` 确认后会自动备份当前安装目录。回滚请求： ```text 回滚 skill-navigator 最近一次升级，先展示备份路径 ``` 结果： ```text restore_from=~/.codex/skills/.skill-navigator.backup-20260824... target=~/.codex/skills/skill-navigator confirmed=false ``` MCP 和 Plugin 的回滚会恢复宿主配置备份。 ### 人工关系和移除 请求： ```text 把 skill-a 和 skill-b 标记为 alternative_to，置信度 0.95，证据是两者都提供同一套浏览器测试流程，先预览 ``` 结果： ```text source=skill-a target=skill-b relation_type=alternative_to confidence=0.95 evidence=两者都提供同一套浏览器测试流程 confirmed=false ``` 确认后，这条人工关系不会被自动图谱重建覆盖。 请求： ```text 把 skill-navigator 从收藏夹移除，但保留历史 ``` 结果： ```text 已归档 #1 skill-navigator 默认收藏列表不再展示，安装、检查和关系历史仍可查询。 ``` 只有明确要求永久删除时才会清理历史： ```text 永久删除收藏 #1 及其历史记录 ``` ### 请求参数对照 | 参数 | 自然语言写法 | 示例结果 | |---|---|---| | `agent` | “扫描 Claude Code” | `agent=claude-code` | | `kind` | “只看 MCP” | `kind=mcp` | | `name` | “只导入 webapp-testing” | 只返回指定 skill | | `capability` | “只导入 testing 相关” | 只返回含 `testing` 标签的项目 | | `risk` | “只导入 risk=none” | 排除 medium/high 风险项目 | | `all` | “包含已安装和归档” | 展示完整历史 | | `include-self` | “也检查 skills-bookmark 自身” | 不跳过当前 skill | | `usage-days` | “按最近 30 天体检” | 使用窗口为 30 天 | | doctor 模式 | “创建/复核/应用体检计划” | 返回稳定计划编号和动作编号 | | doctor 决策 | “将 A002 设为 prefer:browser-one” | 只有确认后才持久化首选项 | | `yes` | “确认执行刚才的计划” | 才写入配置或收藏库 | | `replace` | “确认替换现有 skill” | 先备份，再替换目标目录 | | MCP URL | “HTTP URL 是 …” | `transport=http` | | MCP command | “命令 npx，参数 …” | `transport=stdio` | | MCP env | “环境变量 TOKEN=…” | 结果只显示 `environment_keys=TOKEN` | | plugin selector | “example@marketplace” | `selector=example@marketplace` | | relation type | “标记为 alternative_to” | 保存指定关系类型 | | confidence | “置信度 0.95” | `confidence=0.95` | | evidence | “证据是两者功能相同” | 保存可解释证据文本 | | `osv` | “本次审计查询 OSV” | 查询固定版本的 npm/PyPI 包；失败会明确报告 | | 报告路径 | “将安全报告导出为 HTML 到……” | 写入新的 JSON/HTML；默认不覆盖已有文件 | | 沙箱镜像 | “使用已有 python:3.12-alpine 镜像” | 禁止自动拉取镜像 | | 沙箱命令 | “试运行 python -V” | 精确命令会出现在预览中 | | 导出历史 | “导出全部历史” | 包含远程 installed/archived 记录，但不含本地安装数据 | | 恢复来源 | “合并这个收藏库 JSON” | 先展示数量和合并策略 | | 永久移除 | “永久删除该记录及历史” | 先展示 purge 计划，并要求确认 | ## 维护者接口 仓库内部使用一个标准库 Python CLI 驱动 SQLite、来源适配器、安全扫描和浏览器页面。它是 skill 的实现细节，主要供项目维护者调试、测试和开发新的 Agent adapter；普通使用者不需要直接调用它。 收藏列表默认只展示尚未安装的项目；已安装和归档记录仍保存在本地数据库中，供 Agent 查询和后续整理。 ## 数据和兼容性 数据默认保存在： - Linux：`~/.local/share/skills-bookmark/skills-bookmark.db` - macOS：`~/Library/Application Support/skills-bookmark/skills-bookmark.db` - Windows：`%LOCALAPPDATA%/skills-bookmark/skills-bookmark.db` 可以通过 `SKILLS_BOOKMARK_HOME` 指定数据目录。旧版本的 `agent-bookmarks` 数据目录和 `bookmarks.db` 会在首次启动时自动迁移。 Claude Code 用户级 skills 默认位于 `~/.claude/skills`；设置 `CLAUDE_CODE_HOME` 可指定 Claude Code 的用户目录。 OpenClaw 默认使用 `~/.openclaw/skills`，如果现有环境采用 workspace 布局则识别 `~/.openclaw/workspace/skills`；也可通过 `OPENCLAW_SKILLS_DIR` 明确指定。MCP 和 Plugin 配置需要分别显式设置 `OPENCLAW_MCP_CONFIG` 和 `OPENCLAW_PLUGINS_FILE`。 其他 Agent skill 路径： - Cursor：`${CURSOR_HOME:-~/.cursor}/skills`；可用 `CURSOR_SKILLS_DIR` 覆盖 - Gemini CLI：`${GEMINI_CLI_HOME:-~/.gemini}/skills`；可用 `GEMINI_CLI_SKILLS_DIR` 覆盖 - Qwen Code：`${QWEN_CODE_HOME:-~/.qwen}/skills`；可用 `QWEN_CODE_SKILLS_DIR` 覆盖 - WorkBuddy：`${WORKBUDDY_HOME:-~/.workbuddy}/skills`；可用 `WORKBUDDY_SKILLS_DIR` 覆盖 - Kimi：`${KIMI_HOME:-~/.kimi}/skills`；可用 `KIMI_SKILLS_DIR` 覆盖 - 其他 Agent：设置 `SKILLS_BOOKMARK_CUSTOM_SKILLS_DIR`，再要求扫描 custom Agent adapter ## 安全边界 Skills Bookmark 不会在收藏或检查阶段执行远程仓库代码。远程 README、SKILL.md、manifest 和脚本都被视为不可信输入。 静态检查不等于完整安全审计。依赖通告依赖用户请求的工具、网络、可解析的固定版本和锁文件；许可证元数据与离线域名信号也可能不完整。来源可信度只描述托管平台身份、revision 固定、fork 状态和热度，不把任何一项当成安全证明。 安装、导入、体检复核/应用、恢复、隔离试运行、升级、回滚、人工关系和移除都会先预览，再要求明确确认。收藏和检查阶段从不执行远程代码；隔离试运行必须提供明确命令，并使用已有本地镜像、禁网、只读文件系统、移除 capabilities 和资源限制。 ## 当前架构 ```text Agent 自然语言请求 | v skills-bookmark skill ---> 本地实现层 ---> SQLite |\ | +--> GitHub / Gitee 元数据 | +--> 安全、来源与使用信号 | +--> 八种 skill 目录 adapters | +--> MCP / plugin 原生命令 \----> 本地列表 / 可解释图谱 HTML ``` 收藏数据和被收藏扩展分离保存，因此大量候选项不会进入 Agent 的 active skills 目录。 ## 开发和贡献 项目运行时不要求用户安装 Python 依赖或前端依赖。贡献者可以通过自己的开发 Agent 执行仓库中的单元测试、规范校验和浏览器 smoke test；测试代码位于 `tests/`，底层实现位于 `scripts/skills_bookmark.py`。 浏览器 smoke test 需要额外提供 Playwright 和 Chromium；它们不属于运行时依赖。 ## 支持范围 | 能力 | Codex | Claude Code | OpenClaw | Cursor / Gemini CLI / Qwen Code / WorkBuddy / Kimi / custom | |---|---|---|---|---| | Skill 扫描、导入、体检 | 支持 | 支持 | 支持 | 支持 | | Skill 安装、升级、回滚 | 支持 | 支持 | 支持 | 支持 | | MCP 扫描、导入、安装、回滚 | 支持 | 支持 | 需显式 `OPENCLAW_MCP_CONFIG` | 未开放 | | Plugin 扫描、导入、安装、回滚 | 支持 | 支持 | 需显式 `OPENCLAW_PLUGINS_FILE` | 未开放 | | 可观测使用信号 | 本地日志，partial | 有日志时 partial | unavailable | unavailable | ## 更新 Skills Bookmark 让 Agent 收藏规范仓库、检查固定 revision，并预览替换当前安装的 `skills-bookmark`。确认后会先创建备份，必要时可使用正常回滚流程恢复： ```text 收藏 https://gitee.com/synovation/skills-bookmark.git，检查后升级我当前安装的 skills-bookmark。修改前先展示来源、revision、目标、风险和备份计划。 ``` 维护者可以通过仓库内的发布辅助程序生成版本化 ZIP 和 SHA-256 清单；生成包不属于运行时，也不会进入 Git。 MCP 安装必须由用户明确提供 HTTP URL 或 stdio 命令；插件安装必须明确提供 marketplace selector。Skills Bookmark 不会从远程 README 猜测可执行命令、环境变量值或插件来源。安全审计会清点依赖锁文件并扫描静态风险模式，但不会安装依赖或声称完成漏洞数据库审计。