GlassNote 希望让阅读笔记可靠保存、准确找回，同时保持界面轻盈。欢迎修复缺陷、改进可访问性、完善测试和文档。
- 先搜索已有 Issue 和 PR；较大的功能或数据格式调整，先说明使用场景和方案。
- 普通问题使用 Issue 模板，安全问题按 SECURITY.md 私下报告。
- 从 main 创建分支，一个 PR 尽量解决一个问题。不要混入个人笔记、浏览器配置、安装包或无关格式修改。
- 只提交你有权分享的代码、图片和测试素材。引入第三方材料时，在 PR 中注明来源和许可证。
准备 Node.js 22 或更新版本及 npm。安装开发依赖和测试浏览器：
npm ci
npx playwright install chromium扩展没有构建步骤，也没有运行时 npm 依赖。打开 Chrome 的 chrome://extensions/ 或 Edge 的 edge://extensions/，启用开发者模式，加载包含 manifest.json 的仓库目录。修改后重新加载扩展，并刷新用于测试的网页。
手动测试请使用单独的浏览器配置，不要拿个人笔记做迁移、删除或存储故障实验。升级已有安装前先导出备份；更换扩展目录可能改变扩展 ID，不能假定旧数据会自动跟随。
常用检查：
npm run check
npm test
npm run test:e2e
npm run format:checknpm test 包含需要 Playwright Chromium 的浏览器测试；test:e2e 使用临时浏览器配置和本地示例文章加载真实扩展。两者不需要个人浏览器账号。
仅当改动涉及真实站点兼容性且需要联网验证时运行：
npm run test:live该命令会访问测试脚本中指定的公开站点，不属于默认离线回归。测试报告和截图保存在 test-results，提交前确认没有私人信息。
需要检查分发包时运行：
npm run package
npm run package:verify打包使用 Node.js 内建能力，无需安装系统 zip 命令；产物和校验和在 dist。验包会检查版本、文件清单、内容与校验和。不要把 node_modules、dist、test-results、work 或真实浏览器配置提交到仓库。
按实际影响选择验证，不用为文案修改重复执行整套浏览器测试。
| 改动范围 | 需要保留的行为和验证重点 |
|---|---|
| 原文定位、网页标注 | 不包裹或替换宿主正文；跨节点选区、重复原文、DOM 改写、异步加载与 SPA 切换；无法可靠定位时保留笔记并显示状态，不猜位置。 |
| 保存、删除、迁移和导入 | 旧版数据仍可读取；相同页面相同 ID 的导入不覆盖本地编辑；并发写入、配额失败、格式取消保留想法、已删除记录不被旧编辑器复活。使用合成数据回归。 |
| 弹窗、侧栏和笔记库 | 选文工具、颜色与格式切换、编辑保存失败后的草稿、删除确认、键盘操作，以及窄窗口布局。UI 改动附无隐私的前后截图。 |
| 权限、数据处理和外联 | 说明功能为什么需要变化；同步核对 隐私说明 和商店材料，不能只修改 manifest。 |
锚点测试在 tests/anchor.test.cjs；存储、迁移与格式切换测试在 tests/storage*.test.cjs 和 tests/toggle-storage.test.cjs；界面与真实扩展回归在 tests/content*.test.cjs 和 tests/extension.e2e.cjs。优先为可复现的缺陷增加对应回归用例。
复现材料使用公开网页或最小本地 HTML。导出的 JSON 可能包含完整 URL、摘录、前后文和私人笔记，请用合成数据替代真实备份；截图和日志也应移除账号、令牌及私人路径。详细数据范围见 PRIVACY.md。
PR 写清问题、修改后的行为、实际执行的验证及尚未覆盖的情况。仅打包成功不代表浏览器交互已经通过；如跳过某项验证，请写明原因。新增或更新依赖时同步提交锁文件。
提交贡献即表示你有权提交这些内容，并同意将你拥有版权的原创贡献按根目录 LICENSE 的 MIT 条款提供；第三方材料继续适用其原许可。