📄 修复贡献者/agent 相关文档中的语法、可执行性、重复标题与锚点问题#1603
Draft
cyfung1031 wants to merge 16 commits into
Draft
Conversation
Chrome APIs mocked → Chrome APIs are mocked；MockMessage available → is available； cost ~15% → costs ~15%（主谓一致）。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
该要求原来埋在链接格式说明段落末尾，与 Step 1-4 的编号流程脱节， 容易被按步骤执行的读者/agent 跳过。拆成独立加粗句，内容不变。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
原句 "Scratch copying the inline fixture won't read ..." 省略主语， "Scratch" 读作名词还是动名词短语不明确。补全为 "A scratch script that copies the inline fixture", 保留原有 E2E_RECORD_VIDEO_DIR 与 链接不变。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
步骤 1、2 都点名了具体装饰器和文件，步骤 3（offscreen 路由）和步骤 4 （注册 @grant）却只给出泛化描述，读者/agent 需要额外翻回文档前部或 自行搜索才能定位实际文件。补上已验证存在的 src/app/service/offscreen/gm_api.ts 与 packages/eslint/linter-config.ts， 四个步骤具体程度保持一致。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
cyfung1031
marked this pull request as draft
July 17, 2026 16:55
原文只说明如何做浏览器端验证，未说明哪些改动不需要（纯文档/注释/ type-only）或哪些 bug 应改用普通 Vitest 用例复现（纯 service/unit 逻辑、无跨 context 交互、无真实 Chrome API、无 DOM），导致 agent 可能 为逻辑 bug 过度搭建 E2E scratch，或为文档改动误判需要跑浏览器。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
原文只列出两个选项，选择标准（流式/进度事件/大payload才用 connect） 埋在文档更靠前的 GM_xmlhttpRequest 案例里；只看编号步骤的读者会漏看。 直接把判断依据写进步骤 1，并保留指回原案例的链接。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
design.md 要求"双主题都要验证",verification.md 负责用 scratch 脚本产出截图证据,但两者从未连接——没有任何示例说明怎样在 Playwright scratch 脚本里确定性地切换主题。补充已验证的 localStorage "lightMode" 写法(与 theme-provider.tsx / common.ts 的实现一致),并链接回 design.md 的机制说明,不重复其内容。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
该测试静态校验代码中 t() 调用的 key 是否存在，但只解析 zh-CN 资源； 之前 translation.md 完全没提到它，导致翻译非 zh-CN locale 时得不到 任何自动化信号，也可能被误当作"翻译已验证"的证据。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Five-context 调试表把 Offscreen 行当作平台通用写法，但 src/service_worker.ts:77-85 显示 Firefox 上 chrome.offscreen.createDocument 不存在，offscreen.html 根本不会被加载——architecture.md 已记录这个平台 分歧，本文件之前没有引用它。按此表在 Firefox 上排障会找错上下文。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
develop.md 已规定 PR 标题用 gitmoji + 中文优先，但只从 develop.md 可达；AGENTS.md 的 "Pull Request Description Format" 直接指向 pull-request.md，走这条路径的读者永远看不到标题规则。加一句交叉 链接而非复制内容，避免与 develop.md 重复。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
architecture-build/data/execution/gm-api/services.md 与 design-components.md 都是从旧的单体 architecture.md / design.md 拆分 出来时留下的产物：文件顶部新增了 H1 标题，但原来的段落 H2 标题（同一 个名字，只是大小写/措辞略有不同）没有删除，紧跟其后、中间无任何内容。 对 agent 而言，同一份文件里出现两个几乎相同的标题会造成： - grep/搜索标题时出现两个几乎相同的结果，不确定该看哪一个； - GitHub 渲染时两者 slug 冲突，第二个会被自动加 -1 后缀，导致任何人 凭标题文字手写的锚点链接可能命中错误的标题。 已用 git grep 确认现有文档中没有任何链接指向这些 H2 的锚点 （#the-service-layer 等），删除是安全的；每个文件正文的第一段本身也 已经把 H2 想额外表达的信息（如 design-components.md 的 "usage"）说 清楚了，不存在信息丢失。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
文件里有两个 fenced ```md``` 模板块：第一块只是 Evidence Index 这一节 填好后的排版示例（单独摘出来演示格式），第二块才是完整 report.md 骨架，其中的 Evidence Index 一节写的是"参见上面的样式"，依赖第一块。 两块标题字面完全相同（"## Evidence Index"），会让 agent： - 搜索"Evidence Index"时得到两个含义不同的命中，不确定哪个是真正要 填的位置； - 更危险的是，若把第一块整体当成 report.md 模板复制，会得到一份只有 Evidence Index、缺失 Mode/Goals/Task List/Execution Log/Result/ Blockers 等必需小节的残缺记录。 给第一块标题加上 "(filled-in example)" 后缀消除字面重复，并在两处 之间补一句说明区分两者用途；第二块的回指文字也同步改成精确匹配新 标题，避免"see the shape above"这种模糊指代。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
原有链接检查只验证目标文件是否存在，会把 `#anchor` 直接截掉，从不 校验锚点本身——标题改名/删除时，指向它的 file.md#anchor 链接可以 静默失效而不被任何检查发现。新增第二段脚本，用近似 GitHub slug 算法 （连续空格不合并成单个连字符，如 "Commit & Pull Request Guidelines" → commit--pull-request-guidelines）反推每个锚点应指向的标题并核对。 已用当前分支全部锚点链接跑过一次：仅一处已知限制（CJK 标题不做 ASCII 近似）产生误报，其余全部通过。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
develop-testing.md、architecture.md、verification-debugging.md、 verification.md 里有五处链接：正文已经用"→ Engineering Principles" "→ Testing""deep model in ARCHITECTURE.md"这类措辞点名了目标文件里 的具体章节，但链接本身只写到文件级别，agent 要打开整份 AGENTS.md / develop.md / architecture.md 自己找那一段。 补上 #engineering-principles、#testing、#the-five-contexts-process-model 锚点，用 DOC-MAINTENANCE.md 里新增的锚点校验脚本核对过，全部命中真实 标题；未触碰任何有意指向整份文件的链接（如 AGENTS.md 头部"读 docs/develop.md"这类横幅提示、docs/README.md 索引表）——那些本来就该 是整篇阅读，加锚点反而会误导范围。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
design.md、design-tokens.md、design-components.md 各有一处链接，可见 文字本身写的是 "DEVELOP.md UI section"，但 href 只写到 ./develop.md 文件级别——链接文字已经点名了目标章节，href 却没跟上。develop.md 第 54 行确有 "## UI" 标题，补上 #ui 锚点使三者一致。 用重新跑过的锚点扫描（按目标文件真实标题列表反查每个链接文字，排除 命中目标文件自身标题的"整份文件引用"）确认这是本轮唯一遗漏，其余全部 指向整份文件的链接维持不变。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
cyfung1031
changed the title
这份文件是 GitHub Copilot 自己的入口指令，不在 AGENTS.md 的文档链路 里，本轮"重新扫描全部 agent 可读 markdown"时才发现；它独立复述了一份 架构说明，与 AGENTS.md / architecture.md 各自维护、互不链接，存在两处 与已核实代码不符的地方，且与本 PR 前几轮修复的问题属于同一类： 1. "Sandbox script execution isolated from page context - use unsafeWindow for page access" 把 Sandbox 和 Inject 两个不同 context 混为一谈——Sandbox 跑的是 background/scheduled 脚本，根本没有 page（见 architecture-execution.md:43 "`@background` scripts have no page"）；unsafeWindow 属于 Inject context（见 architecture.md:84 "Page (`MAIN`) world. Has `unsafeWindow`"）。原句会让人误以为可以在 Sandbox 里用 unsafeWindow 访问页面。 2. "Browser Extension Specifics" 完全没提 Firefox 没有 Offscreen API 这件事——与本 PR 第二轮已经在 verification-debugging.md 修复过的 同一个事实缺口（已核对 src/service_worker.ts:77-85）。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
cyfung1031
changed the title
cyfung1031
marked this pull request as ready for review
July 17, 2026 17:30
CodFrm
reviewed
Jul 17, 2026
Collaborator
Author
There was a problem hiding this comment.
我用呀。 github merge 有冲突时都用 免费的copilot 处理
cyfung1031
marked this pull request as draft
July 18, 2026 02:56
Collaborator
Author
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Checklist / 检查清单
背景
按用户要求通读并系统扫描了仓库内全部 46 个 markdown 文件（
git ls-files "*.md"，排除 worktrees），覆盖AGENTS.md/CLAUDE.md、docs/**、.github/*.md、CONTRIBUTING.md、各 package 的README.md、src/locales/README.md、src/pages/.../i18nKeys.md等，检查四类问题：步骤缺少具体文件路径、跨文档规则脱节/矛盾，以及与已核实代码不符的架构性错误。
file.md#anchor风格仅在指向具体章节时才添加，绝不套用到整份文件引用；用新增的锚点校验脚本核对每个链接文字是否已点名具体章节但 href 停在文件级别。
第四轮结束后用户指出"你漏了一些修复"，进而扩大范围重新扫描全部 agent 可读 markdown（而不仅是此前已覆盖的
docs/子集），发现.github/copilot-instructions.md——GitHub Copilot 自己的入口指令文件，完全不在AGENTS.md的文档链路里，独立复述了一份架构说明，存在两处与已核实代码不符的错误，且属于与前几轮同一类问题模式。
涉及"当前分支代码是否真如文档所说"的发现，改文档前都用
grep/test -f/git grep核实过。本次改动
十七个提交，均为纯文档修改，不改变任何既有规则语义：
第一轮 — 语法
1bdff54c—docs/references/develop-testing.md：修复三处语法错误。第一轮 — 可执行性
2.
16a3fa5a—docs/verification.md：拆分"先建验证记录"顺序要求。3.
65423a30—docs/verification.md：修正主语省略歧义。4.
321092e9—docs/references/architecture-gm-api.md：补上步骤 3、4 的具体文件路径。第二轮 — 场景模拟发现的可执行性缺口
5.
77802927—docs/verification.md：补充"何时可跳过本指南"边界。6.
9e5b4243—docs/references/architecture-gm-api.md：补上 sendMessage/connect 选择依据。7.
57e79793—docs/verification.md：补上双主题验证的具体写法。8.
72c93ee6—docs/translation.md：补充 i18n-usage.test.ts 的存在与作用范围。9.
fe089367—docs/references/verification-debugging.md：补充 Firefox 无独立 Offscreen 上下文的提示。10.
7e84e92d—docs/pull-request.md：加交叉链接到 PR 标题规则。第三轮 — 重复标题
11.
3a6b5917— 6 个 references 文档：删除 H1 后紧跟的同义重复 H2。12.
c4c19ae6—verification-report-template.md：消除两处 "Evidence Index" 标题歧义。第四轮 — 锚点精度
13.
fa34afe1—DOC-MAINTENANCE.md：新增锚点完整性校验脚本。14.
6eea05ed— 4 个文档：补上 5 处指名具体章节但 href 停在文件级别的锚点。15.
cf5d6d6c—design.md/design-tokens.md/design-components.md：补上 3 处 "UI section" 链接遗漏的#ui锚点。第五轮 — 扩大范围重新扫描全部 agent 可读 markdown
16. （工具验证，无独立提交）用四类检查脚本对仓库内全部 46 个 markdown 文件跑了一遍：重复标题、文件链接、
锚点完整性、"链接文字点名章节但 href 未跟上"，除下条外全部通过。
17.
8659100c—.github/copilot-instructions.md：修复两处架构性错误——(a) 把 Sandbox（background/scheduled脚本，见 architecture-execution.md:43 "无 page"）与 Inject（见 architecture.md:84 "有 unsafeWindow"）混为
一谈；(b) "Browser Extension Specifics" 完全没提 Firefox 无 Offscreen API（与第 9 条修复的是同一个事实
缺口，已核对 src/service_worker.ts:77-85）。
已知限制
design.md/design-patterns.md中大量原则性、判断性表述——有意保留的设计判断空间。terminology-*.md的翻译内容（除terminology-en-US.md外），需要对应语言母语判断力；但已用相同的机械检查（重复标题、锚点）扫描过全部 7 个其它 locale 的 terminology 文件，均无结构性问题。
AGENTS.md本身，保持其始终加载的 token 成本不变。file.md#anchor风格套用到指向整份文件的链接。README.md、CONTRIBUTING.md、各 package 的README.md——通读后确认无第 1-4 类问题。.github/copilot-instructions.md纳入DOC-MAINTENANCE.md的文档归属表——这是更大的架构性改动（该文件服务于不同工具、有不同约束），超出本 PR 已建立的四类问题范围，仅修复了发现的两处具体错误。
建议审查重点
验证
跑通，仅一处已知 CJK 限制误报（
docs/DOC-MAINTENANCE.md中已注明）。.github/copilot-instructions.md新增的两条事实性修正与architecture-execution.md:43、architecture.md:84、src/service_worker.ts:77-85一致。pnpm test/pnpm run typecheck（无相关代码路径）。