数据流审查

当 Codex 需要通过追踪数据在系统中实际流动路径（而非孤立地评审单个文件）来审查代码时，请使用本方法。

该技能适用于代码审查、合规性审计及补丁检查等场景，其正确性取决于以下要素：

• 数据最初在何处生成
• 数据如何被转换
• 数据在何处被持久化
• 哪些分支条件会改变语义或执行时机
• 哪些下游消费者依赖该值

优先依据真实代码路径、实际调用方、请求构造器、store 写入、事件载荷（event payload）和状态转换进行判断，而非注释、接口名称或主观假设。

适用场景

• 聚焦于状态一致性与语义正确性的代码审查
• 跨文件或跨层级的端到端流程重建
• 补丁审查：微小变更可能影响持久化时机或分支行为
• API 字段溯源检查：覆盖 UI、store、后端、队列及下游消费者各环节
• 审计重试（retries）、取消（cancels）、刷新（refreshes）、恢复（resumes）或失败是否遗留脏状态（dirty state）
• 审查语义上不同的字段是否存在混用、别名（aliasing）、折叠（collapsing）或不安全复用

重构真实数据流

在对任一字段下结论前，务必先追溯其真实流转路径。

1. 定位入口点。 可能包括页面操作（page action）、按钮处理器（button handler）、路由（route）、控制器（controller）、任务消费者（job consumer）、事件处理器（event handler）、定时任务（cron）、队列工作器（queue worker）或 API 端点。

2. 遍历完整调用链。 构建最小化路径图，形式如下：

   entry -> transform -> store/cache/db write -> request/event -> downstream consumer -> next state

3. 显式标注每个分支点。 常见分支类型包括：

   • 成功 vs 失败
   • 确认 vs 取消
   • 重试 vs 首次尝试
   • 恢复（resume）vs 全新初始化（fresh initialization）
   • 同步 vs 异步延续（async continuation）
   • 选用 fallback 值 vs 可用 canonical 值
   • 功能开关（feature-flag）路径 A vs 路径 B

4. 切勿止步于首个看似正确的局部使用。 某字段在一次 API 调用中可能正确，但在下一页渲染、store 读取、队列载荷或后续状态转换中却可能已过期或错误。

追踪规范实体与字段

列出少量必须在整个流程中保持语义稳定的实体或字段。

典型类别包括：

• 标识符（identifiers）：id、key、slug、trace id、correlation id、external id
• 归属或操作者字段（ownership or actor fields）：user id、tenant id、session id、operator id
• 状态/控制字段（state/control fields）：status、phase、mode、source、type、flags、version
• 业务字段（business fields）：amount、currency、plan id、order id、biz id、product id、record id
• 时间字段（time fields）：createdAt、expiresAt、validUntil、scheduledAt
• 派生或转换值（derived or transformed values）：标准化输入（normalized input）、OCR 结果、解析后的载荷（parsed payload）、格式化后的请求字段（formatted request field）

对每个关键字段，需记录：

• 来源（source）：该值首次生成的位置
• 转换（transformation）：是否被标准化、解析、合并、设默认值或重新格式化
• 持久化（persistence）：写入 store/session/cache/db/消息载荷（message payload）的具体位置
• 消费者（consumers）：后续哪些代码路径会读取该值
• 必需语义（required meaning）：下游代码对该字段所代表含义的假设

若某字段临时承载了不同概念，须明确标记；除非已证实所有中间消费者均安全，否则不可接受“后续会修正”的说法。

检查状态边界

审查数据跨越任意边界时可能导致语义漂移的所有位置。

常见边界包括：

• 局部变量（local variable）→ 组件状态（component state）
• 组件状态 → 全局 store
• store → 请求构造器（request builder）
• 请求 → 后端处理器（backend handler）
• 处理器 → 数据库行（database row）
• 数据库行 → DTO / 视图模型（DTO/view model）
• 服务 → 队列/事件载荷（queue/event payload）
• 队列/事件 → 下游消费者
• 内存状态（memory state）→ 持久化缓存/会话/本地存储（persisted cache/session/local storage）

在每个边界处，需追问：

• 这是规范数据源（canonical source），还是缓存副本？
• 该值是否会在下一消费者读取前变得过期？
• 部分成功是否过早写入了持久化状态？
• 仅表示成功的值，是否在真正确认成功前即被写入？
• fallback 值是否掩盖了语义不匹配？

逐一分支核查

对每个分支点，按顺序验证以下问题：

1. 流程是继续执行、阻塞、延迟、重试，还是仅展示/记录结果？
2. 是否在分支安全性得到确认前就发生了任何状态变更？
3. 若用户取消操作或下游步骤失败，是否会残留脏状态？
4. 后续消费者读取的是最新本地值，还是更早的已持久化副本？
5. 仅表示成功的值，是否仅在成功条件真正满足后才被写入？
6. 该分支是否改变了重试、刷新、恢复（resume）、返回导航等行为？
7. 异步后续操作是否使用同一规范值，还是重新构造了不同值？

需特别关注以下情形：

• 在状态迁移 API 成功前即写入 id 或 status
• 取消分支（cancel branches）遗留已持久化的中间状态
• 诸如 a || b 的 fallback 表达式，导致语义被静默折叠
• 某一步使用了正确的本地值，而后续步骤仍读取过期的 store 状态
• 针对特定分支的写入，在失败或取消时未被清理

验证请求与载荷准确性

对每个关键 API 调用、DB 写入或事件载荷：

1. 在代码中定位真实的载荷组装逻辑。
2. 将每个关键字段精确映射至其源变量。
3. 依据实际的格式化/解析逻辑（而非推测）检查类型与格式。
4. 比对语义相近字段，确保它们未被静默合并。
5. 确认该值应置于请求头（header）、查询参数（query）、请求体（body）、路径参数（params）、消息元数据（message metadata）还是数据库记录列（record columns）中。

若存在文档、Schema、电子表格或契约（contracts），需比对：

• 字段名（field name）
• 必填 vs 可选（required vs optional）
• 类型（type）
• 格式（format）
• 常量值（constant values）
• 枚举含义（enum meaning）
• 在请求或载荷中的位置（location in request or payload）

评估补丁安全性

审查补丁时，需提出以下问题：

1. 是否仅修复了预期的语义缺陷？
2. 是否将持久化提前或延后于原逻辑？
3. 是否修改了取消、重试、刷新、恢复（resume）、超时或失败路径？
4. 是否新增了拒绝（rejection）、抛出异常（throw）或提前返回（early-return）路径，但未同步更新调用方？
5. 是否为未受影响的分支保留了原始控制流？
6. 是否改变了后续步骤所读取的“唯一真相源”（source of truth）？

优先选择能恢复语义正确性且行为变更范围最小的修复方案。

审查启发式规则

高风险强信号包括：

• 同一字段名被用于多个不同概念
• 本地修复在一个调用点正确，但在后续消费者处失效
• store/cache 写入发生在下游成功确认之前
• 规范 id（canonical id）与展示 id（display id）混用
• 过期状态在取消/重试/失败后依然残留
• 通过 fallback 表达式或对象展开（object spreading）隐式引入别名（aliasing）
• 后端与前端对同一字段语义理解不一致
• 队列/事件消费者假定了生产者未承诺的载荷结构

问题先行

输出审查意见时，问题（findings）须置于最前，并按严重程度排序。

每个问题应包含：

• 严重等级（severity）
• 精确的文件名与紧凑的行号引用
• 触发该问题的入口路径、分支或具体场景
• 数据为何变得不准确、过期、不一致或语义错误
• 风险类型：错误的请求数据、脏的持久化状态、过期读取、分支回归（branch regression）或下游契约破坏（downstream contract breakage）

问题列表之后，仅当有助于解释整套问题时，方可提供简短的流程摘要。

输出模式

本技能适用于以下类型的输出：

• 聚焦数据正确性的代码审查
• 端到端流程重建
• 逐分支的状态准确性审计
• 最小变更且零回归（no-regression）审查
• 跨多层的 API/载荷溯源检查
• 持久化时机与回滚安全性审计

反模式

• 切勿仅凭接口名判断字段语义。
• 切勿在首次发现局部使用正确后即终止追踪。
• 切勿假设后续覆盖可使前期错误写入变得无害。
• 切勿忽略取消、重试、刷新、恢复（resume）或失败分支。
• 切勿未经语义等价性验证，即认定 fallback 表达式是安全的。
• 切勿仅审查单一层级，而问题本质在于跨层语义漂移。
• 切勿在识别具体正确性风险前，先概括架构设计。