dsa-codebase-audit

DSA 代码库审计

对整个应用执行只读的数据结构与算法审计。找出少量在表示方式和组织模型方面有实质意义的简化方案，而非表面上的重构。

审计范围

被审查的仓库必须保持不变。仅使用只读命令进行检查。不得编辑文件、生成补丁、运行测试、安装依赖、调用格式化工具或生成器、实施建议、提交或推送。将现有测试作为源代码证据进行审查，但不要执行测试。

如果运行环境提供全新的只读子代理，请使用它们。为每个工作者分配一个互不重叠的子系统。并发数量不得超过你能主动协调的工作通道数。如果无法使用全新代理，请在协调者上下文中一次审查一个子系统，并说明这一限制。

在协调者上下文中维护一份规范审计台账。台账负责记录子系统清单、状态、已接受的发现、明确跳过项、跨领域模式、重复或已被取代的发现、优先级、依赖项和审计日志。工作者报告仅作为台账的证据，不能成为相互竞争的事实来源。

只有在每个清单条目都已完成，且最终审计通过独立验证后，审计才算结束。

1. 建立覆盖范围约定

检查仓库根目录、项目指南、目录结构、清单文件、入口点、公共接口、依赖边界和测试布局。在分配审查任务前，列出所有可识别的子系统。

在具有实质相关性的范围内，纳入前端、后端、共享基础设施、平台桥接层、生成式契约的所有权，以及测试或工具基础设施。为每个子系统指定：

• 稳定 ID 和描述性名称；
• 精确且互不重叠的职责边界；
• 关键实现文件；
• 相关公共接口、主要调用点和测试；
• 一个状态：queued、in-review、recommend 或 skip。

宽泛的兜底条目不能证明已覆盖。应继续拆分，直到工作者能够检查所负责的行为及其调用方，而不必负责其他条目。

完成此步骤的条件：每个相关源代码和测试区域都恰好映射到一个可审计子系统，边界互不重叠，且规范台账包含所有条目。

2. 开展有界的子系统审查

将每个 queued 条目分配给一位全新工作者，并在派发前将其标记为 in-review。切勿让一位工作者负责多个子系统。仅当边界彼此独立时，才并行处理独立条目；否则应按顺序处理。每批次只进行一次集中等待，让有进展的工作者完成，并在开启替代工作通道前收集所有可用结果。

向每位工作者提供以下任务说明，并填入其分配的条目：

Review subsystem <stable ID and name> for at most two materially useful simplifications in its data structures, state representation, control flow, algorithms, or organizing model.

Boundary: <exact owned files and behavior>
Key files: <paths>
Interfaces, callers, and tests to inspect: <paths or symbols>

This is read-only. Inspect the implementation, public interfaces, major call sites, and existing tests. Stay inside the assigned ownership boundary. Name cross-subsystem concerns, but do not expand scope to solve them.

Look for:
- scattered booleans or nullable fields that permit invalid combinations and should become a state machine or discriminated union;
- repeated assumptions about object shape that need one shared typed model;
- duplicated branching that a small map, registry, reducer, transition table, or command model would remove;
- unclear state or behavior ownership that a small module boundary would clarify;
- repeated scans, transformations, or lookups where a more appropriate collection or index materially simplifies behavior;
- lifecycle, concurrency, or async representations that permit stale or contradictory state.

Prefer clear local code when it is already sufficient. A recommendation must remove material complexity rather than move existing branching behind a new type. Exclude changes justified only by stylistic consistency, hypothetical extensibility, or minor line-count reduction.

Return at most two opportunities. Return `skip` when none clears that threshold.

For each opportunity provide:
1. Verdict: `recommend` or `skip`.
2. Evidence with exact file and line references.
3. Current complexity or invalid states.
4. Proposed representation and why it is simpler.
5. Smallest credible implementation scope, including affected files and interfaces.
6. Regression risks and migration concerns.
7. Existing and additional validation required.
8. Confidence: `high`, `medium`, or `low`.

工作者失败或未返回结果时，该条目仍未完成，不能视为跳过。应在新的工作通道中重新运行该条目的审查，或按顺序审查。

完成此步骤的条件：每个条目都有一份可用报告，其中包含一到两个符合完整模式的候选项，或明确标注为 skip。

3. 核实并综合

在接受任何候选项之前，独立追踪当前实现、调用方、公开契约和测试中的每一项候选内容。核实每处引用的行以及所声称的无效状态、重复、所有权问题或算法成本。

遇到以下情况时，拒绝、缩小范围或降低候选项的优先级：

• 内容含糊或缺少源代码证据；
• 与另一项发现重复；
• 误解了有意设计的语义；
• 只是转移了复杂性；
• 引入的抽象范围超出已证明的需求；
• 依赖假设性的规模或可扩展性；
• 超出其子系统边界。

按根本原因去重。将每条已接受的建议分配给一个权威子系统，并将相关行记录为已覆盖，而不是重复记录该发现。将已核实的未发现问题结果明确记录为跳过。只有在协调者核实后，才将每一行更新为 recommend 或 skip。

继续分批打开有限数量的条目，直到没有行仍处于 queued 或 in-review 状态。

只有在所有清单行都有经核实的处理结论，且每项已接受的发现都包含全部八个必填字段时，才算完成此步骤。

4. 审查审查过程

进行新一轮独立的只读审查；条件允许时，使用相互独立的 Agent，检查以下方面：

1. 仓库覆盖范围和遗漏的子系统边界；
2. 重复发现和所有权重叠；
3. 重要性和过度抽象；
4. 发现项架构的完整性；
5. 依赖关系感知的优先级排序。

如果覆盖审查发现实际遗漏，则添加新的明确子系统行并进行审查。保留已完成的边界，不要通过扩大先前行的范围来掩盖遗漏。在报告之前，解决台账中的所有其他验证失败。

根据具体影响、置信度、实现工作量、影响范围、前置条件和顺序依赖，为已接受的建议排序。指出最适合作为首批实施内容的切片；不要实施。

只有在五项审查都记录了结果、发现的所有缺陷都已解决或披露，且仓库保持不变时，才算完成此步骤。

5. 报告

按以下顺序返回一份报告，包含这些部分：

## Summary
<Scope, recommendation count, skip count, and strongest themes.>

## Coverage
| ID | Subsystem | Ownership boundary | Key files | Public interfaces and major call sites | Tests | Disposition |
| --- | --- | --- | --- | --- | --- | --- |

## Prioritized recommendations
### 1. <Concrete simplification> — <confidence>
- **Verdict:** `recommend`
- **Subsystem:** <ID and name>
- **Evidence:** `path:lines`, ...
- **Current complexity:** <complexity or invalid states>
- **Proposed representation:** <model and why it is simpler>
- **Smallest scope:** <affected files and interfaces>
- **Risks:** <regression and migration concerns>
- **Validation:** <existing and additional validation required>
- **Priority:** <impact, effort, blast radius, prerequisites, and dependencies>

## Cross-cutting patterns
<Patterns observed across authoritative subsystem findings.>

## Explicit skips
<Subsystems with a concise verified reason no recommendation cleared the bar.>

## Audit validation
<Results of the five independent passes, worker failures or limitations, and confirmation that the repository remained unchanged.>

只有当 Coverage 中包含所有可识别的子系统、每行都以建议或明确的跳过结论结束、每项发现都包含准确的证据、范围、风险和验证、没有重复项和薄弱抽象、优先级与依赖关系一致、五项验证审查均已说明，且经过审查的仓库保持不变时，审计才算完成。