📄 修正 AGENTS.md 与 develop.md 中的过期事实与措辞歧义

[cyfung1031]

Checklist / 检查清单

• Fixes mentioned issues / 已修复或实现
• reviewed by human / 通过人工检查
• Changes tested / 已完成测试

背景

在 #1610 修复 AGENTS.md 中 PR 描述规范提示的可见度问题后，收到提示"检查 AGENTS.md 其余内容是否有类似问题"。逐条核对 AGENTS.md 全文后发现若干过期事实与措辞歧义（第一轮改动），随后收到六轮对改动本身的审阅意见，指出前一轮改动引入或未完全解决的问题（第二至七轮改动）。全部条目均已按 docs/DOC-MAINTENANCE.md 的规则重新对照代码库验证，不直接采信未经验证的外部结论。

本次改动

第一轮：过期事实与触发/所有权歧义

• AGENTS.md："Key Packages" 中 filesystem/ 被描述为 "(WebDAV + local)"，但 packages/filesystem/factory.ts 中实际的 FileSystemType 并无 "local" 选项（实为 zip | webdav | baidu-netdsik | onedrive | googledrive | dropbox | s3）——改为准确描述并链接到 docs/cloud-sync.md。
• AGENTS.md："All four syntax-based harness rules are covered by eslint-rules/harness.test.mjs" 具有误导性：该文件实际只覆盖 no-i18n-default-value、no-raw-color-classname、no-restricted-imports 的 radix-ui 模式、no-restricted-syntax 四项，require-last-error-check（列表中排最前、最易被误认为已覆盖）与 no-restricted-imports 的 sonner 模式均未被覆盖——已用 grep 确认该文件全文无相关字样，改为明确列出实际覆盖与未覆盖的项目，并补上 require-last-error-check 缺失的 chrome-error/ 插件命名空间前缀。
• docs/develop.md："8 locales" 但 src/locales/ 下实际有 9 个语言目录（遗漏 pt-BR）。
• AGENTS.md：docs/design.md 的阅读触发条件写作"建任意 page 前"，但 docs/design.md/docs/develop.md 自身都写"page, dialog, or block"——三处范围不一致，已统一。
• AGENTS.md："single source of truth"/"put all guidance here" 的表述容易与 docs/DOC-MAINTENANCE.md 的所有权模型混淆——已明确该句是相对 CLAUDE.md 而言。
• AGENTS.md："If a test fails, fix the code, not the test" 的绝对化表述与 docs/references/develop-testing.md 允许清理无价值测试的既有规则存在潜在冲突——补充窄化例外。
• AGENTS.md："apply to every change" 改为 "every code change"，并补充 docs/verification.md/Confirm before you fix 的连接、DEVELOP.md/DESIGN.md 大小写不一致修正。

第二轮：对第一轮改动本身的修正

• docs/develop.md：Coding Style 与 i18n 两处仍写 "react/jsx-no-literals: warn"，但 eslint.config.mjs 实际为 "error"——这是第一轮"已核对 eslint.config.mjs"这一说法本身的反例，已修正两处措辞。
• docs/develop.md：不再硬编码 locale 数量/列表，直接指向 docs/translation.md，从根源上避免再次漂移。
• AGENTS.md："apply to every code change" 对 TDD 而言范围过宽、对 Scope discipline 而言范围过窄——改为不再用统一限定词覆盖整节，TDD 条目自带精确范围说明。
• AGENTS.md：docs/design.md 触发提示提升为独立顶部引用块，删除 UI stack 段落中重复的触发语句。
• AGENTS.md："Confirm before you fix" 补充区分：纯逻辑/解析/工具函数类 bug 用单元测试复现，依赖真实扩展/浏览器 API/跨上下文行为时才需要 docs/verification.md 的 scratch-script 工作流。
• AGENTS.md："fix the code, not the test" 例外拆分为两类：契约有误（应修正测试）与从一开始就不该存在（应主动清理，与是否失败无关）。

第三轮：对第二轮新增表述本身的修正

• AGENTS.md：TDD 例外从"config/dependency changes"整类豁免，改为以"是否改变可观察行为"为判断标准（标题改为 "for changes that alter observable behavior"），避免解析器升级、bundler 配置变更等实际改变行为的改动被错误跳过测试。
• AGENTS.md：ESLint 规则清单引导句移除"lint/tests 强制执行所以不会像文档一样漂移"的说法——第二轮修正的正是这段描述自己的过期内容，这本身反驳了"不会漂移"。

第四轮：TDD 遗漏"自动化覆盖不可行"例外、design.md 触发范围仍限于"新建"

• AGENTS.md：补充 TDD 第二类例外——纯视觉/动画调整、仅特定浏览器版本或生命周期阶段才能复现的问题、文案/翻译改动、无法可靠自动化的平台行为，改用人工验证并记录证据，明确不得为满足本条而提交低价值测试。
• AGENTS.md、docs/develop.md、docs/design.md：design.md 触发范围从"新建"统一改为"新建或修改"，与该文档 Core Constraints 一节"every UI change"的实际范围对齐。

第五轮：token 效率、TDD 三文档冲突、验证工作流适配范围（基于新一轮审阅意见，逐条核实后采纳）

• token 效率（元问题）：审阅指出本 PR 已向 AGENTS.md（每次会话都会加载的文件）持续新增大量文本，多数应下放到其他专属文档而不损失 harness 效果。已将占用最多篇幅的 ESLint 自定义规则清单（规则名、范围、harness.test.mjs 覆盖情况，约 9 行密集内容）整体迁移到 docs/develop.md 新增的 "ESLint custom rules" 小节——该文档本就是 AGENTS.md 自称"concrete how"的权威归属。AGENTS.md 对应位置改为 4 行指针，AGENTS.md 总行数相比上一轮净减少。同时不再需要"这是有意为之的窄范围例外"这类说明性文字，因为详细内容已不在 AGENTS.md 里。
• 阻断级：TDD 失败测试是否强制，三份文档给出不同答案——AGENTS.md 已定义"自动化覆盖不可行时可用验证证据替代失败测试"的例外，但 docs/verification.md 仍无条件断言"scratch reproduction 必须晋升为已提交的失败测试"，docs/references/develop-testing.md 仍无条件写"write failing tests before implementation"，AGENTS.md 自身"确定 bug 存在 → 写测试 → 修复"的中文摘要也未反映新例外——按读到哪份文档，代理会得出不同结论，这正是本 PR 意在减少的跨文档漂移。已让 verification.md/develop-testing.md 不再各自重复并可能过期地断言该策略的具体内容，改为指向 AGENTS.md 作为唯一权威；AGENTS.md 中文摘要补上"或记录验证证据"分支。
• AGENTS.md "keeps only" 与 ESLint 详细清单的矛盾：随上一条 ESLint 清单迁出 AGENTS.md 一并解决——"This file keeps only the non-negotiable engineering principles and the architecture map" 现在是准确陈述，无需额外的例外措辞，也与 docs/DOC-MAINTENANCE.md 所有权表中 AGENTS.md 一行的描述重新保持一致（此前"已知限制"记录的这一条已随之消失）。
• TDD 第二类例外一律指向 docs/verification.md 的扩展级 scratch-script 工作流，对文案/翻译改动等简单场景过重：已改为按是否需要真实扩展/浏览器 API 区分——需要时用该工作流，否则用更轻量的记录说明即可，不再一律套用面向浏览器扩展集成场景设计的完整流程。

第六轮：Engineering Principles 仍偏重，例外细节下放到专属文档（基于新一轮审阅意见，逐条核实后采纳）

• 审阅指出 Engineering Principles 一节仍偏重，应在不损失 harness 的前提下下放。核对后确认 Fix root causes、Confirm before you fix、TDD/BDD first 三条经五轮修正累积了大量例外场景与反例说明，是该节最重的部分。已将例外细节按各自所有权迁移：
  • Fix root causes 的测试例外（契约本身有误 / 从未有价值）迁移到 docs/references/develop-testing.md 的 "Writing meaningful tests" 小节开头。
  • Confirm before you fix 的复现方式选择（单元测试 vs 扩展级 scratch-script）迁移到 docs/verification.md（该文档本就以复现 bug 为职责范围）。
  • TDD/BDD first 的两类例外整段迁移到 docs/references/develop-testing.md 新增的 "When TDD doesn't apply" 小节。
  • AGENTS.md 三条对应位置收窄为"原则本身 + 一处指针"，文件字节数相比上一轮再减少约 12%（10347 → 9132 字节），例外内容未删减，只是搬到了各自的所有权文档。

第七轮：verification.md 中 scratch 证据与例外的措辞歧义（非阻断，基于新一轮审阅意见，逐条核实后采纳）

• docs/verification.md："a scratch reproduction... is not itself the required test or evidence" 无条件表述，但在 AGENTS.md 的自动化覆盖不可行例外场景下，scratch 复现（report.md、截图、观察记录）本身就是要求的证据——docs/references/develop-testing.md 的 "When TDD doesn't apply" 小节也支持这一解读。已补充"一般情况下"限定，并明确例外场景下 scratch 复现即为所需证据，无需再补一个已提交的测试。
• docs/verification.md："该策略（含其例外）归属 AGENTS.md" 在第六轮例外细节迁出 AGENTS.md 后已不准确——已改为分别说明：AGENTS.md 拥有原则本身，docs/references/develop-testing.md 拥有例外判定标准。

已知限制

• 未处理审阅意见中偏结构性/主观的建议（例如为 docs/architecture.md 新增多个触发回调块）——改动范围更大、收益不确定，留待后续按需评估。

建议审查重点

• 本 PR 经历了多轮"改动本身被审阅发现新问题"的过程，包括三文档 TDD 策略冲突、"Engineering Principles 仍偏重"、以及本轮的 scratch 证据措辞歧义——这提示"我已完成事实核查/token 已经足够精简"类声明本身也需要留有余地。
• docs/verification.md 新增的"一般情况 vs 例外情况证据要求不同"表述，是否与 docs/references/develop-testing.md 的例外判定标准完全对齐，不会出现"符合哪条例外"本身产生新的跨文档分歧。
• AGENTS.md 三条原则收窄为"原则 + 指针"后，是否仍能在不点开链接的情况下让代理理解约束的边界，还是必须打开 docs/references/develop-testing.md/docs/verification.md 才能正确执行。
• docs/references/develop-testing.md 新增的 "When TDD doesn't apply" 小节与 "Writing meaningful tests" 开头新增的契约区分说明，措辞是否与 AGENTS.md 迁移前的原文一致，没有在搬运过程中引入新的表述漂移。
• ESLint 规则清单迁移到 docs/develop.md 后，AGENTS.md 的 4 行指针是否仍能让代理在需要时快速找到细节，而不必先读完整个 develop.md。
• docs/verification.md/docs/references/develop-testing.md 改为指向 AGENTS.md 作为 TDD 策略唯一权威后，是否遗漏了这两份文档原本承担的、AGENTS.md 不适合覆盖的机制性说明（例如 scratch-script 具体怎么写、测试文件放在哪）。
• TDD 例外及其"按是否需要真实扩展区分验证方式"的补充，是否足够具体、不会被泛化滥用为"这个行为变更懒得写测试"的通用借口。

关联

• #1610 — 处理同一类问题（AGENTS.md 中 PR 描述规范提示的可见度与措辞），本 PR 是对 AGENTS.md 其余内容的后续审计。两个 PR 都改动 AGENTS.md，但改动的段落不重叠。

验证

• docs/DOC-MAINTENANCE.md 自带的链接完整性检查脚本每轮改动后均本地执行，全部链接可解析，无 BROKEN 输出（第五轮改动含 docs/verification.md 中一处链接文本调整，已确认解析正常）。
• 每条"过期事实"类改动均用 git-aware 命令对照当前分支已提交代码逐条核实：git grep/git ls-tree 确认 filesystem/ 实际 provider 列表、harness.test.mjs 实际覆盖的规则、chrome-error//scriptcat/ 插件命名空间前缀、src/locales/ 实际的 9 个语言目录、eslint.config.mjs 中 react/jsx-no-literals 的实际级别。
• 第五轮 "TDD 三文档冲突" 一条用 grep -n "does not replace\|committed failing test\|scratch reproduction" docs/verification.md 与 grep -n "write failing tests\|failing test" docs/references/develop-testing.md 确认两处此前均为无条件表述，与 AGENTS.md 当前例外确实矛盾。
• wc -l AGENTS.md 确认第五轮改动后 AGENTS.md 总行数相比上一轮净减少（ESLint 清单迁出的行数多于本轮新增行数）。
• 第六轮用 wc -c AGENTS.md（改动前后对比 git show <上一轮commit>:AGENTS.md | wc -c）确认字节数从 10347 降至 9132；docs/DOC-MAINTENANCE.md 链接完整性检查脚本改动后本地执行，全部链接可解析，无 BROKEN 输出。
• 第七轮改动前先用 sed -n '1,35p' docs/verification.md 重读改动前原文，确认"is not itself the required test or evidence"确无限定词、且与例外场景矛盾，改动后再次执行链接完整性检查脚本，无 BROKEN 输出。
• git commit 触发的预提交钩子（lint-staged）因每轮改动仅涉及 .md 文件而跳过 JS/TS 相关检查。

[cyfung1031]

@CodFrm

[CodFrm]

@cyfung1031 有冲突了

[CodFrm]

基于当前 head 0bf071b 对完整 diff 和全仓贡献者文档做了复核。大部分事实修正是准确的，但仍有几处会让贡献者得到相互矛盾的可执行规则，因此当前不建议直接合并：

1. docs/architecture.md:233-234 仍保留绝对化 TDD 规则
   该处要求所有实现都先写失败测试，并写着“test fails 时只修代码、不要改测试”。这与本 PR 在 docs/references/develop-testing.md:24-31 明确的三类情况冲突：行为保持型工作不要求新失败测试；自动化确实不可行时可用记录证据且无需提交测试；测试自身契约错误时应修正测试。建议删除这段重复政策，改为指向 AGENTS.md 与 develop-testing.md，architecture 仅保留架构相关测试机制。

2. docs/verification.md 前后互相否定
   docs/verification.md:28-32 已说明符合“自动化覆盖不可行”例外时，scratch 的 report/截图/观察记录就是所需证据，且“不需要 committed test”；但 docs/verification.md:249-251 又要求所有成功复现都进入 failing-test → fix 流程。建议将后者改成条件分支：一般情况进入失败测试；符合例外时保留 scratch 证据并直接进入修复及修复后验证。

3. 迁移后的 ESLint scope 说明仍不完整（docs/develop.md:64-69）
   AGENTS.md:103-106 声称这里提供“exact rule names, scopes”，但文档没有记录 eslint.config.mjs:96-99 对 src/pages/components/ui/toast.ts 完整关闭 no-restricted-imports；这意味着该文件同时豁免 Radix 与 Sonner 两类限制。require-last-error-check、no-i18n-default-value 的全局 lint scope 也没有明确写出。建议补全有效 scope/override，或降低 AGENTS 中“exact scopes”的承诺。

4. 当前 GitHub 显示分支冲突
   当前实时状态为 mergeable: CONFLICTING、mergeStateStatus: DIRTY，需要先 rebase/解决冲突，再对最终合并树重新跑文档链接与事实检查。

其他已核实内容：CLAUDE.md 仅导入 AGENTS.md；filesystem 没有 local provider、Zip 用于本地备份；当前有 9 个运行时 locale；react/jsx-no-literals 为 error；主要链接和新增锚点可解析。FOSSA License Compliance 是外部状态，应与上述文档阻塞分开处理。

[cyfung1031]

@cyfung1031 有冲突了

我有检查过。没实际冲突的。已处理好