get-shit-done 前端元数据解析器的对抗性测试：duplicate-keys 夹具与 last-wins 语义契约

get-shit-done 前端元数据解析器的对抗性测试：duplicate-keys 夹具与 last-wins 语义契约

【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done

本文聚焦 get-shit-done 仓库中 YAML frontmatter 解析器（get-shit-done/bin/lib/frontmatter.cjs）在面对"同一键重复出现"这一对抗性输入时的确定性行为。以 tests/fixtures/adversarial/frontmatter/duplicate-keys.md 为核心骨架，结合 tests/feat-3594-parser-adversarial-frontmatter.test.cjs 与解析器源码，讲清"last-wins（后者覆盖前者）"这一当前契约如何被固定、被测试、被维护，以及它为什么对状态文件、规划文件等用户频繁手工编辑的文档至关重要。读完你将掌握：如何通过对抗性夹具固定解析器语义、如何读懂并扩展这类契约测试，以及重复键问题在真实文件解析中的危害边界。

一、夹具文档：用最小输入钉死一个解析行为

tests/fixtures/adversarial/frontmatter/duplicate-keys.md 是一个刻意构造的"最小对抗样本"，全文只有十几行：

--- title: First title: Second status: active status: blocked phase: 01 --- Body content for duplicate-keys fixture. When the parser encounters a key twice in the same block, the test pins what is currently observed (last-wins) so a silent semantics change becomes a test failure rather than a quiet data shift.

它的结构极其清晰，却精准命中了 YAML frontmatter 解析中最容易被忽视的语义问题：

用一句话概括这个夹具的角色：它不是一个"bug 样本"，而是一个"契约样本"——它的存在不是为了指出解析器哪里错了，而是为了把"重复键到底谁赢"这一当前实现行为，从"实现细节"升级为"被测试保护的公开契约"。

从目录说明 tests/fixtures/adversarial/frontmatter/README.md 可以看出，整套夹具的设计原则是：每个夹具文件名即编码了"滥用类别"，测试按相对路径加载它们，因此语料库可以持续扩充而无需改动测试代码。新增夹具的约定是：放入文件 → 在测试矩阵中登记 → 明确该文件必须满足的不变量（通常是"不抛异常、不返回半解析垃圾、不静默丢数据"）。

二、解析器源码：last-wins 从何而来

要理解"当前行为"是什么，必须回到解析器实现。get-shit-done/bin/lib/frontmatter.cjs 中的extractFrontmatter()是这套语义的源头，其核心逻辑分四步：

1. 仅匹配文档开头的 frontmatter 块

const match = content.match(/^---\r?\n([\s\S]+?)\r?\n---/);

正则锚定在字节 0（^---），意味着正文中途出现的---（YAML 示例、水平分割线）永远不会被误判为 frontmatter。这一步保证了"重复键"问题只会在真正的元数据块内被讨论。

2. 按行拆分，逐行匹配key: value模式

const keyMatch = line.match(/^(\s*)([a-zA-Z0-9_-]+):\s*(.*)/);

键的正则限定为 ASCII 字符集[a-zA-Z0-9_-]，这是当前解析器的显式契约（在 tests/feat-3594-parser-adversarial-frontmatter.test.cjs 中有对应的回归断言：非 ASCII 键不会被捕获）。

3. 直接对结果对象赋值——这就是 last-wins 的机制根源

current.obj[key] = value.replace(/^["']|["']$/g, '');

关键在这里：解析器维护一个结果对象，遇到key: value行时执行的是普通对象赋值current.obj[key] = ...。由于 JavaScript 对象的同名属性赋值天然是"后者覆盖前者"，title: First会被title: Second覆盖，status: active会被status: blocked覆盖，最终对象里只留下最后一次出现的值。解析器既没有收集重复键成数组，也没有报错或去重，这就是"last-wins 是当前行为"的直接代码证据。

4. 缩进栈负责嵌套结构

解析器用一个栈跟踪嵌套层级（对象/数组），重复键的覆盖行为同样适用于嵌套上下文中同层级的键。

因此，duplicate-keys 夹具中预期的解析结果可以完整推导为：

{ "title": "Second", // 第二次赋值覆盖 First "status": "blocked", // 第二次赋值覆盖 active "phase": "01" // 无重复，原样保留 }

三、契约测试：把"当前行为"变成"被保护的语义"

fixtures README 明确声明了 duplicate-keys 的期望："Parser must produce a deterministic result; tests document which value wins (last-wins is the current behavior)"（解析器必须产生确定性结果；测试记录哪个值获胜，last-wins 是当前行为）。

真正把这句话落地的是 tests/feat-3594-parser-adversarial-frontmatter.test.cjs 中的第一个用例duplicate keys collapse to a single deterministic winner。它的断言逻辑值得逐条拆解：

const content = loadFixture('duplicate-keys.md'); const fm = extractFrontmatter(content); assert.equal(typeof fm.title, 'string', 'title must be a string, not an array or object'); assert.equal(typeof fm.status, 'string', 'status must be a string'); // Current parser behavior: the second occurrence wins... assert.equal(fm.title, 'Second', 'duplicate-key collapse must be last-wins (current contract)'); assert.equal(fm.status, 'blocked', 'duplicate-key collapse must be last-wins (current contract)'); assert.equal(fm.phase, '01');

这个用例实际上同时钉住了四层不变量：

1. 类型不变量：title和status必须是字符串——如果未来某天解析器把重复键收集成数组（['First','Second']），这个断言会立刻失败；
2. 值不变量：重复键的胜者是第二次出现的值（Second、blocked），而不是第一次，也不是空值；
3. 对照不变量：未重复的phase键原样往返（'01'），证明重复键处理没有波及无辜键；
4. 确定性不变量：同一次解析、同一份输入，结果是稳定的单值，不是数组、不是半成品对象。

测试注释还点明了这套契约测试的哲学："Pin it so a change to first-wins becomes visible"（把它钉住，让任何改为 first-wins 的变更变得可见）。也就是说，未来如果团队想改成"首次出现者优先"或"重复即报错"，这个测试不应该被悄悄改掉，而应该成为一次显式的语义变更评审——这正是"对抗性夹具"的核心价值：它让语义决策有据可查、有变更记录、有回归保护。

此外，该测试文件末尾还有一个跨语料库的兜底测试：对tests/fixtures/adversarial/frontmatter/目录下所有.md夹具统一断言extractFrontmatter必须返回普通对象、不得抛异常、不得返回 null 或数组。这意味着即使未来新增一个更"恶意"的夹具而忘记写专门用例，这条兜底仍然保证解析器面对整个语料库都不会崩溃。

四、为什么值得较真：重复键在真实工作流中的危害

重复键不是理论玩具，而是多工具协作编辑文件的必然产物。该测试文件头部注释给出了背景："users edit planning files with multiple tools"（用户会用多种工具编辑规划文件）。

在 get-shit-done 中，frontmatter 被广泛用于承载项目状态与规划元数据，例如：

• state.json输出 STATE.md 的 frontmatter；
• plan / summary / verification 三类文件分别有各自的必填字段 schema（定义在同文件 get-shit-done/bin/lib/frontmatter.cjs 的FRONTMATTER_SCHEMAS中）；
• 多个核心模块直接依赖extractFrontmatter()，包括 commands.cjs、phase.cjs、roadmap.cjs、state.cjs、verify.cjs、milestone.cjs、uat.cjs、audit.cjs 等。

试想如下场景：一个规划文件原本写着status: active，用户在编辑器里手工追加了一行status: blocked想"改状态"，但忘了删旧行。如果解析器语义是"首次出现者优先"或"合并成数组"，下游的 verify.cjs 读取到的状态将与用户意图相反；而 last-wins 语义恰好让"后写的行"获胜，与"用户在文件末尾追加修改"的直觉一致。更重要的是，无论采用哪种语义，只要是被测试钉住的确定性语义，下游就不会出现"今天读到一个值、明天读到另一个值"的隐性漂移。

从 CLI 角度看，get-shit-done/bin/gsd-tools.cjs 暴露了完整的 frontmatter CRUD 命令族（frontmatter get/set/merge/validate），它们全部建立在同一个extractFrontmatter()之上。也就是说：无论是 Agent 用frontmatter set <file> --field status --value blocked修改状态，还是用frontmatter validate <file> --schema plan校验必填字段，看到的都是同一套 last-wins 语义。解析器行为的一致性，直接决定了这些读写命令对同一文件的理解是否一致——这正是重复键契约需要被钉死的深层原因。

五、更广的对抗性语料库：一套可复用的解析器压力测试方法论

duplicate-keys 并不是孤例。它所在的 tests/fixtures/adversarial/frontmatter/ 目录是一个完整的"对抗性输入语料库"，每个文件对应一类真实世界中会出现的恶意/边界输入：

这套方法论可以抽象为三个可复用的步骤，任何解析类模块都可以照搬：

1. 把"输入类别"编码进文件名：每个夹具文件的名字即文档，测试按目录扫描加载，新增输入不需要改测试代码；
2. 为每类输入明确"必须满足的不变量"：通常落在"不抛异常 / 不返回半解析垃圾 / 不静默丢数据 / 结果确定"这四类上，而不是纠结于"理想行为"；
3. 钉住当前行为 + 兜底扫描：单个夹具钉住当前契约（哪怕它不是最终理想语义），再配一条"全语料库不崩溃"的兜底测试，防止未来新增夹具时漏写断言。

这也与仓库中另一组属性式测试（roadmap 解析器的 property-style 不变量，见测试文件头部注释对 tests/feat-3594-parser-property-style.test.cjs 的引用）形成互补：用例式夹具负责"某个具体输入长什么样"，属性式测试负责"无论什么输入都必须成立的性质"。

六、本地验证：如何亲手复现这个契约

在仓库根目录下，可以用两种方式验证本文所述行为：

方式一：运行专门的对抗性解析测试

node --test tests/feat-3594-parser-adversarial-frontmatter.test.cjs

该文件由 Node.js 内置测试运行器驱动（node:test+node:assert/strict），不依赖外部框架。运行后可以看到 duplicate-keys、CRLF、未闭合块、Unicode、空字节、大块输入共 6 组断言全部通过（外加一条全语料库兜底）。

方式二：直接用 CLI 复现解析结果

node get-shit-done/bin/gsd-tools.cjs frontmatter get tests/fixtures/adversarial/frontmatter/duplicate-keys.md

frontmatter get命令（入口见 get-shit-done/bin/gsd-tools.cjs 的frontmatter分支，底层委托给 frontmatter.cjs 的cmdFrontmatterGet）会输出该夹具的完整解析结果，你可以亲眼看到title为Second、status为blocked、phase为01，与本文推导完全一致。

也可以尝试"语义变更实验"：把夹具中两行title调换顺序后再执行上面的命令，观察胜者随之变为新的"最后一行"——这正是 last-wins 语义最直观的演示。值得注意的是，修改仓库内文件仅用于本地实验验证，不必保留这些改动。

七、小结：从一份 13 行的夹具看契约工程

一份 duplicate-keys.md 只有 13 行，但它浓缩了 get-shit-done 在处理"用户会用多种工具编辑的元数据文件"时的一整套工程态度：

• 确定性优先：解析器面对重复键，必须给出单值、稳定的结果（last-wins），而不是数组、空值或随机行为；
• 契约显式化：当前行为通过 feat-3594 测试 被钉成公开契约，任何语义漂移都会以测试失败的形式浮出水面；
• 可追溯的语义决策：如果未来想改成 first-wins 或"重复即报错"，需要显式地修改测试契约，而不是让行为悄悄改变；
• 语料库式回归保护：配合 fixtures README 与全目录兜底扫描，整个对抗性语料库构成了解析器长期稳定性的防线。

对于任何需要解析用户可编辑元数据（状态文件、规划文件、配置头）的开发者而言，这份夹具与配套测试提供了一个现成范本：在你为"当前行为"感到侥幸之前，先把它钉进测试里。

【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done