Howoii Smartbookmark Smartbookmark

Chrome Extension Development

这个 skill 只放“扩展开发时额外需要的工作流和项目约束”，不重复通用 clean code 或验证规则。

Use This Skill For

• 修改 manifest.json
• 调整 background / popup / quickSearch / settings / content script 行为
• 新增或修改 Chrome 扩展权限、消息通信、存储、国际化、主题或 UI 交互

Task Workflow

1. 先阅读 docs/architecture/PROJECT_ARCHITECTURE.md，确认本项目的运行时、存储层和同步链路。
2. 再识别改动落在哪个运行时：
   • background
   • popup / quickSearch / settings
   • content script
3. 画清楚本次改动涉及的状态来源、事件入口和消息链路。
4. 再检查是否会影响：
   • 权限
   • 生命周期
   • i18n
   • 主题变量
   • 现有交互回归

Runtime-Specific Checklist

Background / Service Worker

• 不依赖常驻内存。
• 跨请求状态要可恢复。
• 设计消息和存储时优先考虑生命周期中断后的恢复路径。

Popup / QuickSearch / Settings

• 关注键盘事件、弹窗层级、编辑模式、搜索模式之间的优先级。
• 任何新增交互都要评估是否会和现有全局快捷键或 Escape 行为冲突。
• UI 文案变化要同步 i18n。

Content Script

• 遵循最小权限原则。
• 避免把重逻辑塞在页面上下文里。
• 与 background 的交互要显式，不要假设共享状态。

Project-Specific Guardrails

Architecture First

• 涉及以下主题时，优先以 docs/architecture/PROJECT_ARCHITECTURE.md 为入口再看代码：
  • 书签聚合
  • background 消息处理
  • Chrome 书签同步
  • WebDAV / cloud 同步
  • 本地存储与设置存储分层

Bookmark Data Sanitization

• 书签对象有两类清洗：
  • sanitizeBookmarkForStorage：仅删除纯运行时字段
  • sanitizeBookmarkForExport：删除所有 _ 前缀字段
• 新增 _ 字段时，要先确认它属于运行时字段还是存储字段，再同步检查这两个清洗入口。

i18n

• 新增用户可见文案时同步更新 _locales/zh_CN/messages.json 和 _locales/en/messages.json。
• 优先复用已有 key 命名风格，不要引入单次使用的随意命名。

Theme / UI

• 不要硬编码颜色，优先复用 css/theme.css 中的变量。
• popup 和 quickSearch 的改动要同时考虑桌面窄宽度下的可用性。

Packaging / Build Hygiene

• 当前打包链路以 build.sh 为入口，流程是：
  • 先用 build.py 和 config/manifest.*.json 生成目标环境配置
  • 再通过 rsync --exclude-from='exclude_list.txt' 复制到临时目录
  • 最后对临时目录执行 zip
• 因此“哪些文件不能进扩展包”的单一事实来源是 exclude_list.txt；调整打包内容时，优先改这里。
• 变更打包排除规则前，先按运行时入口核对真实依赖：
  • manifest.json
  • background.js
  • popup.html
  • quickSave.html
  • quickSearch.html
  • settings.html
  • intro.html
• 当前项目里应排除的开发期内容包括：
  • docs/
  • AGENTS.md
  • skills/
  • .cursor/
  • .codex/
  • .trae/
  • .idea/
  • .vscode/
  • .claude/
  • build/
  • .git/
  • build.sh
  • build.py
  • env.json
  • config/
  • exclude_list.txt
  • .gitignore
  • tmp_build
• 注意不要误排这些运行时仍会用到的资源：
  • intro.html 和 intro.js：安装/升级后会由 background.js 打开
  • videos/：intro.html 会引用，且 manifest.json 已把 videos/* 声明为 web_accessible_resources
  • icons/、css/、_locales/、各页面 HTML/JS 入口：都由 manifest 或页面直接引用
• 如果新增了新的开发工具目录或仓库级文档目录，在同一次提交里同步更新 exclude_list.txt。
• 修改排除规则后，用下面的 dry-run 校验打包结果里是否仍混入开发文件：
  • rsync -avn --exclude-from='exclude_list.txt' . /tmp/smart-bookmark-packcheck
  • 然后检查输出里是否还出现 docs、skills、.cursor、.codex、.trae、AGENTS.md 等开发期路径

When In Doubt

• API 兼容性不确定时，优先查官方文档。
• 权限或生命周期影响较大时，先缩小方案，再决定是否扩展。

Source: howoii/SmartBookmark — distributed by TomeVault.