howoii/smartbookmark/chrome-extension-dev

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

1. 画清楚本次改动涉及的状态来源、事件入口和消息链路。
2. 再检查是否会影响：

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