bulk-edit

批量编辑

我把“将所有记录的此字段改成这样”转化为一个不会对无法确认的情况妄下结论的转换、一项可在中断后继续的运行，以及一项也会核查原本不该触碰的记录的验证。preflight-mutations 授权写入；除此之外的所有工作都由我负责。

我所要防止的故障不是崩溃，而是运行报告成功，却悄无声息地抹平了群体所依赖的差异。以下每道关卡都是为了防止这种悄无声息的故障。

${CLAUDE_SKILL_DIR}/references/worked-example.md 详细介绍了一次真实的 638 条记录运行，其中包括促成这些关卡的四个险些出错的案例。如果你觉得下面某道关卡是在增加无谓的工作量，请先阅读它。

1. 确定群体和字段

我将群体定义为其他人可以重新运行的查询，并根据系统而非请求者的措辞来确定它。“看板上的所有工单”和“仓库中的所有工单”是不同的集合；我会先报告两者之间的数量差异。只编辑一个字段。触及两个字段的运行就是两次运行，需要两本台账。

我会分别统计群体和候选子集。大多数请求说的是群体，实际指的却是会发生变化的子集，而这两个数量很少相同。

关卡。 群体由可重新运行的查询定义并有相应数量，候选子集有单独的数量，字段名称明确且只有一个。

2. 编写转换前，先了解每种变体

请求中的示例只是一种变体，绝不是规范。我会将整个群体导出到本地一次，并按出现频率列出所有实际形式。我不会抽样，也不会凭目测判断。

我会统计实际出现的分隔符、界定符、前缀和连接符，然后检查长尾数据。常见形式正是我早已预料到的那些。会导致转换出错的是罕见形式，而抽样会让它们隐形：在三千条记录中只出现四次的连接符，恰恰可能是含义不同于常见形式的那种情况。

对于每种不同的形式，我会追问它代表什么，而不是它看起来像什么。外观相似但含义不同的形式最容易造成问题。链式箭头和与号可能出现在同一位置，分别表示“然后”和“并且”；将两者用同一种方式合并，就会抹去后者的区别。

关卡。 我能说出群体中每种不同形式的数量，检查过最罕见的形式，并记录了转换必须保留含义的那些形式。

3. 编写会拒绝处理的转换

我会根据结构而非模式搜索来锚定转换。从固定边界开始并在明确界限处停止的规则无法触及记录中的其他数据；而搜索任何类似目标模式的规则，迟早会在实际内容中间找到匹配项。

每条记录都会被归类为 OK 或 HOLD，并附上原因。HOLD 是运行的输出，不是运行失败。只要某种形式的含义无法得到证实，我就会拒绝处理；只要猜错会导致无法从记录本身恢复的结果，我也会拒绝处理。

我绝不会为了减少暂缓数量而扩大转换范围。交还一份暂缓列表成本很低；抹平差异则是永久性的。

关卡。 群体中的每条记录都归类为 OK 或带原因的 HOLD，两者数量之和与群体数量一致，并且暂缓列表已写入请求者可以查看的位置。

4. 先创建快照，再对照实时系统试运行

我会在执行前立即为整个数据集的当前值创建一份新快照，并将其存储在工作树之外，确保清理或检出操作无法触及它。第 2 节中的探索性转储不是快照；它可能已经过时几分钟或几小时，而两者之间的差异恰好就是我规划期间被其他人编辑的记录。

我会对照实时系统试运行，而不是对照转储。试运行的目的是证明转换仍适用于实际存在的数据。

空白字符和编码差异会在这里造成误报。如果记录与转储不完全相等，我会根据实时值重新推导转换，并比较结果。如果结果符合计划，该记录就没有问题，只是我的校验条件过于严格。这样检查本来也优于相等性检查：它依据实际存在的数据进行验证，而不是依据我的记忆。

关卡。 快照带有时间戳，存储在工作树之外，并覆盖整个数据集。试运行针对实时值执行，且其计数与第 3 节一致。

5. 批次授权

我会将批次交给 preflight-mutations 处理，只有其判定为 ready 后才会写入。

规划恢复方案前，我会先检查平台自身的历史记录。许多系统会永久免费保留旧值：例如会记录重命名的工单跟踪系统、带有审计触发器的表，或支持快照的文件系统。这些保留记录能提供恢复所需的旧值，因此我会在一条真实记录上验证这一点，而不是想当然，并记录读取旧值的确切查询。

保留记录证明可以进行补偿，但不会改变可逆性分类。该分类由 preflight-mutations 负责；如果原始事件或下游影响会在恢复后继续存在，那么无论旧值读回得多干净，这项编辑仍属于 compensating-only。我会提供证据并由该技能进行分类，因为自行提高分类等级会跳过它要求的重新确认。

我还会把恢复路径写成可运行的脚本，而不是只描述操作步骤。脚本会从第 4 节的快照恢复，并拒绝处理当前值既不是我的新值、也不是原始值的记录，以便保留同事之后所做的编辑。

关卡。 判定结果为 ready，恢复路径已在一条真实记录上演示，且恢复脚本已创建并能以试运行模式运行。

6. 执行

我会先写入一条金丝雀记录，并通过所有独立途径进行验证：写入响应、重新读取，以及平台的历史记录。确认无误后才会处理其余记录。金丝雀只需处理一条记录，却能发现原本可能波及所有记录的整类错误。

我会选择 API 提供的成本最低的写入途径，并检查它会消耗哪项配额。系统通常会将预算拆分到彼此独立耗尽的配额桶中，因此看似显而易见的客户端命令与底层 REST 调用，在成本上可能相差数倍。如果写入响应会返回已更新的记录，那么写入和验证只需一次调用，而不是三次。references/github.md 中列出了 GitHub 的详细示例数据。

我会控制循环节奏，定期探查剩余预算；预算不足时暂停，而不是等到被拒绝才发现已触及上限。在处理整个数据集的过程中途遭到拒绝，会留下只编辑了一半的记录集，这是代价最高的失败。

账本以记录 ID 为键，每次尝试后追加一条记录，并立即写入磁盘。恢复运行时会读取账本，并跳过已写入成功的记录。我绝不会假定状态为零后直接重新开始。

关卡。 金丝雀至少通过两种独立途径验证，账本涵盖候选集中的每条记录，并且每项错误都附有响应文本，而不只是错误计数。

7. 验证全部记录，包括我未纳入目标的记录

我从权威来源重新读取了全部记录。搜索索引和列表端点通常会延迟几分钟才反映写入，因此可能把成功的运行报告为失败，或把失败的运行报告为成功。我读取的是对象，而不是搜索结果。

我报告三个数字，而不是一个：

检查项	问题	失败意味着
目标记录	所有 OK 记录现在是否都具有计划值？	本次运行未完成
保留记录	所有 HOLD 记录是否都保持不变？	转换触及了超出设计范围的记录
附带影响	候选集之外是否有任何记录的值发生变化？	有其他操作同时编辑了记录，或我的锚点泄漏了

附带影响检查最容易被跳过，也是唯一能发现转换范围过宽的检查。一次运行若报告“638 条记录中有 638 条成功”，却没有进行这项检查，就不能证明它只更改了 638 条记录。

我预计会有少量看起来像失败、其实并非失败的记录幸存下来，因为这些记录在转换刻意不触及的位置包含了该模式。我会展示每条记录修改前后的内容，并说明为什么结果正确，而不是把它们埋在总数里。

关卡。 报告所有三项检查的数字，并展示每个看似例外的记录修改前后的内容。

8. 找出会撤销这项工作的写入方

定期运行的任务会重新填入我清理的字段。在报告工作完成之前，我会查明是否有持续写入该字段的任务，并验证我的判断，而不是直接接受说法。

编辑历史能提供证据。我会提取几条代表性记录的变更事件，并按相关时区的星期和小时对时间戳进行聚类。每周运行的任务会产生明显的峰值；人工维护的时间则较为分散。

写入操作背后的账户能告诉我任务存在，却不能告诉我任务在哪里运行。普通用户账户下遵循机器规律的计划，既可能是平台外的 cron，也可能是通过存储的令牌以该用户身份验证的计划工作流。因此，我会分别检查仓库自身的自动化配置和可能运行任务的主机，并且不会仅凭账户类型排除任何一种可能。

当有人指出任务的位置时，我会独立验证位置和计划时间。这两项说法可能分别出错；计划时间正确，并不能证明路径也正确。凭记忆系统中无法获取的信息想起的路径，只是一种假设。

此处顺序比速度更重要。 如果写入方会重写字段与某个真实数据源不一致的记录，那么一次让所有记录都不一致的编辑，就会把尽可能大的一批记录交给该任务处理。我会明确说明清理操作和写入方变更的先后顺序；顺序颠倒造成的反复改写，比什么都不做代价更大，而不是贸然继续。

关卡。 我已根据证据指出写入方，或者说明已检查但未发现写入方。如果写入方存在且仍在运行，我会在建议任何后续编辑之前说明顺序限制。

报告

我会报告运行了什么、三项验证数字、附有原因的保留记录列表、备份位置及其恢复命令，以及我有意未完成的事项。只报告保留记录数量而不说明原因，请求者就无法据此采取行动。

完成。 候选集已编辑并验证，保留记录未编辑且已报告，附带影响检查结果干净，并且回滚路径可以运行。