Skip to content

AGENTS.md

Latest commit

 

History

History
105 lines (82 loc) · 7.11 KB

AGENTS.md

File metadata and controls

105 lines (82 loc) · 7.11 KB
Raw

Project AGENTS.md

本项目遵守全局 <codex-home>\AGENTS.md。本文件只记录雪花PDF工具的项目专属规则，不复制全局全文。

项目目标

雪花PDF工具是本地纯净的 Chrome 网页转 PDF 扩展。核心目标是保持文字型 PDF 主路径稳定、离线本地运行、站点模板可维护、历史诊断可追溯。

技术栈

  • Chrome Manifest V3 扩展。
  • 运行代码位于项目根层入口文件和职责目录。
  • 后台入口为 background.js，类型为 ES module。
  • 主要打印路径使用 Chrome Debugger Page.printToPDF。
  • 本地存储使用 chrome.storage.local、chrome.storage.session 和 IndexedDB。

目录边界

  • background.js 和 content.js 是当前扩展核心入口，保留在项目根目录。
  • pages/ 放扩展页面入口、页面脚本和页面样式。
  • shared/ 放跨页面/后台复用的纯函数或轻量 UI 辅助模块。
  • page-tools/ 放注入网页的页内工具脚本，manifest 中必须先注入 *-core.js 再注入对应 UI 脚本。
  • site-templates/ 放单站点模板和同目录纯函数模块。
  • shared/print-style-css.js 放打印排版 CSS 和普通节点隔离 CSS 生成逻辑。
  • tests/ 放根层功能模块和页内工具 smoke test；站点模板自身的测试仍放在 site-templates/。
  • legacy-original-plugin/ 只作旧插件参考，不作为运行时依赖。
  • 根目录 css/、imgs/、js/ 只保留当前 UI 必需资源和 js/local-network-guard.js。
  • docs/ 只使用固定长期文档和标准 docs/progress/ 留痕结构。

任务等级默认值

  • L0：只读分析、代码解释、排查建议，不修改文件，不更新文档。
  • L1：版本号、文案、单个断言等微小变更，最小验证，通常不新增 round；若项目已进入发布或用户要求留痕，可写最小 round。
  • L2：常规缺陷修复或小功能，更新受影响文档，必要时新增或更新 docs/progress/rounds/。
  • L3：站点模板、内部消息、历史元数据、权限、安全、打印主路径、模块拆分等重要变更，必须更新相关架构/接口/数据库/知识图谱/变更/进度文档。
  • L4：阶段任务、迁移、版本发布或审计，使用 docs/progress/releases/ 或 docs/progress/phases/。

不要为了留痕制造多余轮次；同一目标连续推进时，优先更新已有 round 或 release 记录。

文档治理

  • 按影响范围更新文档，不机械全量更新。
  • docs/PROGRESS.md 只保留当前阶段、最近完成、下一步、风险和最近留痕入口。
  • docs/DOC_INDEX.md 只索引核心文档、progress 目录和 release 目录，不逐条列出所有 round 文件。
  • round 细节放入 docs/progress/rounds/，发布细节放入 docs/progress/releases/。
  • 不创建 notes.md、guide.md、summary.md、plan.md、development-guide.md、review-notes.md 等同义文档。
  • 新增、删除、移动文档时必须更新 docs/DOC_INDEX.md。

站点模板规则

  • 每个特定网站的精细化处理必须独立模块化，优先放入 site-templates/<site>.js 或同目录纯函数模块。
  • background.js 只负责消息路由、Chrome API 调度、样式采样、PDF 生成、存储和下载，不揉入站点 DOM selector、清理规则、素材等待规则。
  • site-templates/index.js 是注册表，只负责 URL 匹配、公开快照、隔离器、预检器和 ready checker 分发。
  • 新增或修改站点模板时，同步维护 smoke test、相关诊断字段和受影响文档。
  • 借鉴成熟插件时只吸收算法思想和接口形态，必须在本项目当前根层职责目录内本地重写。

本地纯净边界

  • 默认不恢复 externally_connectable、management、固定 key、update_url、homepage_url、world: "MAIN"。
  • 默认不引入外部服务、远程模板、账号、VIP、商店、反馈、遥测、在线压缩或在线编辑入口。
  • 规则可以随插件深入开发受控演进：确有功能必要时，必须先记录用途、权限、数据流、回退路径和验证结果，并保持本地优先、最小权限、无遥测、无远程模板。
  • 不调用 ColorInk、Chrome Web Store、Google Fonts、jsDelivr、GoFullPage 或其它外部服务。
  • 扩展页面渲染资源默认只允许本地、blob:、data:；知乎含评论 PDF 的内部本地 HTML 源页不得把 zhihu.com / zhimg.com 远程 URL 直接写入 img.src，必须先通过 background 的 fetchZhihuAsset 受控抓取并转为 blob: 后再显示，避免扩展页 CSP 和 chrome.scripting 边界再次打断 PDF 主路径。知乎评论导出只在用户勾选“含评论”后触发，并通过当前知乎页面上下文读取知乎评论接口；批量工作台图片本地化也只能通过 background 受控消息请求知乎/zhimg 白名单资源。不得恢复 Word/DOCX 远程图片抓取例外，不得扩展为外部服务、遥测、远程模板或全网抓图。

常用验证

Get-Content .\manifest.json -Raw | ConvertFrom-Json | Out-Null
Get-ChildItem .\background.js, .\content.js, .\page-tools, .\pages, .\shared, .\site-templates, .\tests -Recurse -Filter *.js | ForEach-Object { node --check $_.FullName }
node .\site-templates\site-templates-smoke.test.js
node .\site-templates\zhihu-formula-protection-smoke.test.js
node .\tests\capture-engine-smoke.test.js
node .\tests\link-template-summary-smoke.test.js
node .\tests\print-style-css-smoke.test.js
node .\tests\font-ui-smoke.test.js
node .\tests\zhihu-page-tools-smoke.test.js
node .\tests\zujuan-page-tools-smoke.test.js
node .\tests\zujuan-popup-controls-smoke.test.js
node --check .\js\local-network-guard.js
rg -n 'externally_connectable|update_url|homepage_url|"key"|"management"|world":\s*"MAIN"' .\manifest.json
rg -n 'colorink\.top|api\.colorink\.top|pages\.colorink\.top|store\.colorink\.top|fonts\.googleapis\.com|cdn\.jsdelivr\.net|chromewebstore|gofullpage' .\background.js .\content.js .\page-tools .\pages .\shared .\site-templates .\tests .\manifest.json .\js\local-network-guard.js

运行级知乎页内工具验收：

. .\scripts\resolve-extension-runtime-env.ps1
node .\tests\extension-runtime-probe.test.js
node .\site-templates\zhihu-link-card-runtime-smoke.test.js
node .\site-templates\zujuan-paper-runtime-smoke.test.js
node .\tests\zujuan-page-tools-runtime-smoke.test.js
node .\tests\zujuan-extension-e2e-smoke.test.js
node .\tests\floating-ui-extension-e2e-smoke.test.js
node .\tests\zhihu-page-tools-runtime-smoke.test.js

浏览器插件调试必须先走 scripts/resolve-extension-runtime-env.ps1 和 tests/extension-runtime-probe.test.js。不要直接使用系统 Chrome 或 Playwright 默认 executable；本机默认 Playwright/系统 Chrome 曾出现版本错位和 MV3 service worker 不启动，稳定路径以 resolver 输出的 SEER_CHROME_PATH 为准。

完成标准

  • 改动完成真实目标，不以较窄替代目标冒充完成。
  • 修改范围符合现有模块边界。
  • 受影响文档按等级和影响范围更新。
  • 已运行能覆盖本次改动的验证；未运行时明确说明原因。
  • 留痕符合任务等级，不新增同义或临时文档。