ricocc/rico-bookmark-manager

# Rico 书签管理器 将杂乱的浏览器书签导出文件转化为一个整洁、可搜索的本地导航站点——并提供结构化数据、Markdown 概览和审查报告。它既可以作为 Skill 使用，也可以作为一个独立的、无依赖的 Python CLI 运行。 中文文档: [中文说明](README.zh.md)  ## 预览 生成的导航站点附带五个内置主题——`ease`、`kami`、`minimal-mono`、`retro-blue` 和 `ui`： | | | | | :---: | :---: | :---: | | 
`ease`（默认） | 
`kami` | 
`minimal-mono` | | 
`retro-blue` | 
`ui` | | ## 功能特性 - 将浏览器导出的书签解析为结构化的 `bookmarks.json`。 - 分析文件夹结构、类别分布、重复 URL 以及低置信度项目。 - 将书签分类为 `source`、`optimized` 或 `hybrid` 类别路径。 - 在启用网络检查时检测死链。 - 将新的导出文件合并到现有数据中，实现增量更新。 - 导出 Markdown 概览和可导入浏览器的 HTML 文件（可直接导回你的浏览器）。 - 生成一个本地静态导航站点，支持搜索、过滤、报告、导出、主题切换以及本地暂存编辑。 ## 安装 通过以下三种方式之一将其安装为 Claude Code 的 Skill。仓库根目录**本身就是**该 Skill，因此它可以直接映射到你的 skills 目录中。 ``` # Option 1：使用 npx 一行安装（推荐） npx skills add https://github.com/ricocc/rico-bookmark-manager.git # Option 2：git clone 到 Claude Code skills 目录 git clone https://github.com/ricocc/rico-bookmark-manager.git ~/.claude/skills/rico-bookmark-manager # Option 3：下载 ZIP 并解压到 skills 目录 # macOS/Linux: ~/.claude/skills/rico-bookmark-manager/ # Windows: %USERPROFILE%\.claude\skills\rico-bookmark-manager\ ``` 安装后，目录结构如下所示： ``` ~/.claude/skills/rico-bookmark-manager/ ├── SKILL.md ├── scripts/rico_bookmarks_manager.py ├── assets/ └── references/ ``` ### 验证安装 重启 Claude Code 或重新加载 skills，然后在对话中输入： ``` /rico-bookmark-manager ``` 或者直接说“rico, organize my bookmarks”。如果该 Skill 被激活，说明安装成功。 ## 与 AI 配合使用（推荐） 安装完成后，**最自然的使用方式就是在对话中使用日常语言**——无需记忆任何命令。有两种方式： ``` # Option A：显式斜杠调用 /rico-bookmark-manager organize bookmarks.html and build the navigation site # Option B：对话中的自然触发 rico, organize my bookmarks ``` 常见场景（你所说的话 → 发生的操作）： | 你可以说 | 发生的操作 | | --- | --- | | “rico, organize my bookmarks and build a navigation site” | 解析你的书签 HTML，进行分类并生成本地站点。 | | “deduplicate my browser bookmarks and check for dead links” | 查找重复项和失效链接，并生成审查报告。 | | “rebuild the navigation site with the retro-blue theme” | 使用选定的主题重建站点。 | | “merge this new export incrementally, preview first” | 使用 `--dry-run` 预览增量更新，保留现有分类。 | | “export a file I can import back into my browser” | 生成 `bookmarks_import.html`，可直接重新导入（见下文）。 | | “I want to save a bookmark” | 不会触发（没有明确的管理动作）。 | 如需可重复或可脚本化的批量运行，请参阅下方的 [CLI 用法（高级）](#cli-usage-advanced)。 ## 快速开始 **第一步**：从浏览器将你的书签导出为 HTML 文件。 **第二步**：运行完整的工作流： ``` python scripts/rico_bookmarks_manager.py all \ --input bookmarks.html \ --output rico-bookmarks ``` **第三步**：在浏览器中打开 `rico-bookmarks/site/index.html`，进行搜索、过滤、检查、暂存编辑、查看报告以及导出。 这将生成： ``` rico-bookmarks/ ├── site/ # local static navigation site ├── data/bookmarks.json # structured bookmark data ├── reports/*.md # duplicates, dead links, suggestions, distribution ├── categories/*.md # per-category Markdown files ├── 书签总览.md # Markdown overview └── bookmarks_import.html # browser-importable HTML ``` ### 导回你的浏览器 整理好的类别将在你的浏览器中重新构建为**书签文件夹层级**。`all` 命令已经生成了 `bookmarks_import.html`（或者你也可以单独运行 `export-html`）。要将其导回： - **Chrome / Edge**：书签管理器 → 右上角菜单 → 导入书签 → 选择该 HTML 文件。 - **Firefox**：书签管理器（我的足迹） → 导入和备份 → 从 HTML 文件导入书签。 ## CLI 用法（高级） 当你需要可重复、可脚本化或可调试的运行过程时，请直接使用 CLI： ``` # 分析结构和重复项（尚未整理文件） python scripts/rico_bookmarks_manager.py analyze \ --input bookmarks.html \ --output rico-bookmarks # 使用 hybrid 模式和三个分类级别进行整理 python scripts/rico_bookmarks_manager.py organize \ --input bookmarks.html \ --output rico-bookmarks \ --mode hybrid \ --levels 3 # 仅从现有数据重建导航站点 python scripts/rico_bookmarks_manager.py manager \ --data rico-bookmarks/data/bookmarks.json \ --output rico-bookmarks/site # 使用特定主题构建站点 python scripts/rico_bookmarks_manager.py manager \ --data rico-bookmarks/data/bookmarks.json \ --theme retro-blue \ --output rico-bookmarks/site # 从现有数据生成可导入浏览器的 HTML python scripts/rico_bookmarks_manager.py export-html \ --data rico-bookmarks/data/bookmarks.json \ --output rico-bookmarks # 预览增量更新而不写入 python scripts/rico_bookmarks_manager.py update \ --input new_bookmarks.html \ --existing rico-bookmarks/data/bookmarks.json \ --output rico-bookmarks \ --dry-run # 列出内置主题 python scripts/rico_bookmarks_manager.py themes ``` ## 主题 使用 `--theme` 为导航站点选择外观（默认：`ease`）： | 主题 | 描述 | | --- | --- | | `ease` | 默认主题。纸质风格的目录，配以矿物蓝点缀和柔和的表面。 | | `kami` | 温暖的画布、象牙白的纸张、墨蓝色的点缀，以及由衬线字体主导的层级结构。 | | `minimal-mono` | 深色单色界面，配以暖灰色表面。 | | `retro-blue` | 暖色纸张，配以编辑风格的蓝色标题和克制的金色高亮。 | | `ui` | 单色瑞士风格界面，采用边框优先的组件设计。 | 内置主题位于 `assets/themes//` 目录下（包含 `theme.json`、`theme.css` 和 `DESIGN.md`）。如果存在 `theme.css`，管理器会直接复制它；否则会从 `theme.json` 重新生成。使用自定义的 `--design DESIGN.md` 会在构建时生成 `theme.css`。 `kami` 主题借鉴了 Kami 的公开设计语言（[网站](https://kami.tw93.fun/index-zh.html)，[仓库](https://github.com/tw93/kami)）：温暖的画布、象牙白的纸张、墨蓝色的点缀、由衬线字体主导的层级结构，以及极其轻盈的环形边框。 ## 导航站点 生成的静态站点包含： - 支持跨标题、URL、域名、描述、标签、源路径和类别路径的全局搜索。 - 支持按类别、子类别、标签、域名和链接状态进行过滤。 - 提供网格和列表视图。 - 带有访问和详情操作的书签卡片。 - 详情对话框，显示 URL、源文件夹、类别路径、标签、状态、描述以及本地暂存控制。 - 提供说明页面使用方法的指南对话框。 - 提供用于查看统计信息、重复项、死链和建议的报告对话框。 - 支持 JSON、Markdown 以及可导入浏览器的 HTML 格式的导出操作。 详情编辑属于存储在 `localStorage` 中的浏览器本地暂存。它们不会写入 `bookmarks.json` 或浏览器配置数据中。从站点导出的 JSON 包含了暂存的类别、标签和描述更改，因此你可以在之后有意地替换源数据。 ## CLI 参考 ``` python scripts/rico_bookmarks_manager.py [options] ``` | 命令 | 用途 | | --- | --- | | `analyze` | 解析输入的 HTML 文件，并报告结构、重复项、分布情况和建议。 | | `organize` | 解析书签并将其分类为 `source`、`optimized` 或 `hybrid` 类别路径。 | | `export-html` | 从现有的 `bookmarks.json` 生成可导入浏览器的 Netscape HTML。 | | `export-md` | 从现有数据生成概览、类别文件和报告。 | | `manager` | 从现有数据生成本地静态导航站点。 | | `update` | 将新的 HTML 导出文件中的书签合并到现有的 `bookmarks.json` 中。 | | `all` | 运行整理 + Markdown 导出 + 浏览器 HTML 导出 + 导航站点生成。 | | `themes` | 列出内置的导航站点主题。 | | 选项 | 使用者 | 描述 | | --- | --- | --- | | `--input bookmarks.html` | `analyze`、`organize`、`update`、`all` | 书签 HTML 输入文件，通常为浏览器导出文件。 | | `--output rico-bookmarks` | 大多数命令 | 输出目录。 | | `--data path/to/bookmarks.json` | `manager`、`export-md`、`export-html` | 现有的结构化书签数据。 | | `--existing path/to/bookmarks.json` | `update` | 用于增量更新的现有数据文件。 | | `--mode source\|optimized\|hybrid` | `analyze`、`organize`、`all`、`update` | 分类策略。 | | `--levels 1\|2\|3` | `analyze`、`organize`、`all`、`update` | 最大类别深度。 | | `--check-links` | `analyze`、`organize`、`all` | 运行网络链接检查。 | | `--no-network` | `analyze`、`organize`、`all` | 跳过网络检查。 | | `--dry-run` | `update` | 预览更新写入操作，不更改数据文件。 | | `--theme kami\|ease\|minimal-mono\|retro-blue\|ui` | `manager`、`all` | 内置导航主题。默认：`ease`。 | | `--design DESIGN.md` | `manager`、`all` | 根据设计参考生成自定义主题。 | ## 增量更新 增量更新需要一个新的书签 HTML 导出文件加上一个现有的 `bookmarks.json`： ``` python scripts/rico_bookmarks_manager.py update \ --input new_bookmarks.html \ --existing rico-bookmarks/data/bookmarks.json \ --output rico-bookmarks \ --dry-run ``` 该更新过程通过规范化的标准 URL 匹配书签，保留已由人工审查的字段，仅对新增项目进行分类，并写入 `reports/增量更新.md`。请首先使用 `--dry-run` 进行预览。 ## 环境要求 - Python 3.8+ - 无第三方 Python 依赖 - 一个书签输入源，通常是浏览器导出的 Netscape HTML 文件 - Node.js 仅用于开发阶段可选的 JavaScript 语法检查 ## 针对AI Agent 请将此 Skill 用作一种执行契约，而不是特定于产品的集成——任何能够读取文件、运行 Python 并写入输出的运行时都可以运行它。 **触发方式。** 作为 Skill，当满足以下条件时它会被激活：(1) 你在书签相关的请求中提到了 `rico`，或者 (2) 你表达了明确、具体的书签管理任务（整理、去重、检查死链、导出、更新、构建导航站点）。模糊、偶然提及“书签”一词并不会触发它。具体的措辞请参阅上方的[与 AI 配合使用](#use-with-ai-recommended)。 **执行流程。** 理解目标 → 定位或请求输入源 → 选择最小风险的路径 → 运行 CLI → 报告读取了什么、写入了什么，以及是否访问了任何浏览器数据。 **输入源**，从最安全到功能最全： | 级别 | 来源 | 适用场景 | | --- | --- | --- | | 1 | 浏览器导出的 `bookmarks.html` | 默认选项，是进行完整运行、分析和更新最通用的路径。 | | 2 | 现有的 `bookmarks.json` | 重建站点、导出 Markdown/HTML，或合并新导出的文件。 | | 3 | Agent 创建的中间文件 | Agent 已获得用户权限和环境访问权，能够安全地将浏览器数据导出为标准输入文件。 | | 4 | 浏览器自动化或当前标签页 | 属于外部 Agent 的能力，而非固定的 CLI 接口。仅在具有明确用户意图和许可的情况下使用。 | CLI 的公共接口是基于文件的（`--input`、`--data`、`--existing`）。如果你通过直接访问配置文件或自动化操作获取了浏览器数据，请在调用 CLI 之前将其转换为以上文件之一。如有疑问，请向用户索要浏览器导出的 HTML 文件。请勿直接修改浏览器配置文件。 ## 安全提示 - 请勿自动删除书签。 - 请勿直接修改 Chrome、Edge、Firefox 或其他浏览器的配置文件。 - 如果 Agent 有权访问浏览器数据，请先获得用户批准，并创建一个中间输入文件。 - 在执行增量写入之前，请使用 `--dry-run`。 - 在更新过程中保留人工编辑的分类。 - 除非用户有意导出并替换源数据，否则将导航站点的详情编辑视为本地暂存处理。 ## 项目结构 ``` rico-bookmark-manager/ ├── SKILL.md ├── scripts/ │ └── rico_bookmarks_manager.py ├── assets/ │ ├── bookmark-manager-template/ │ └── themes/ ├── references/ │ ├── cli.md │ ├── design-md.md │ ├── link-checking.md │ ├── manager-spec.md │ ├── schema.md │ ├── taxonomy.md │ └── workflow.md ├── agents/ └── screenshot/ ``` ## 我的其它开源项目 - **Rico Skills** — 我的 Skill 系列：[https://github.com/ricocc/rico-skills](https://github.com/ricocc/rico-skills) - **SaaS Template** — 开源项目：[https://github.com/ricocc/ricoui-saas-template](https://github.com/ricocc/ricoui-saas-template) - **Portfolio Template** — 开源项目：[https://github.com/ricocc/ricoui-portfolio](https://github.com/ricocc/ricoui-portfolio) - **Blog Template** — 开源项目：[https://github.com/ricocc/public-portfolio-site](https://github.com/ricocc/public-portfolio-site) ## 关于作者 我是 Rico X (@ricouii)，一名喜欢构建有趣且富有创意的作品的 Web/UI 设计师。我拥有专业的 UI/UX 经验，目前专注于 Web 设计、视觉交付，并积极探索开发项目。 欢迎添加我的微信： 我会定期在我的博客 [Rico's Blog](https://ricoui.com/) 上发布内容。你也可以在小红书上关注我，[@ico的设计漫想](https://www.xiaohongshu.com/user/profile/5f2b6903000000000101f51f)。 ## 💜 支持 如果这个工具对你有所帮助，一点点支持就能给创作者带来极大的动力。非常感谢！ ⭐ 如果这个工具帮你整理了书签，请留下一个 Star。

标签：Claude Code Skill, Python CLI, 多模态安全, 数据可视化, 浏览器书签, 逆向工具, 链接管理, 静态导航站