accelint-ts-audit-all

审计全部

全面的 TypeScript 文件审计系统，系统性地应用多种审计技能，并带有进度跟踪和交互式批准。

运行审计时绝对不要做的事

• 绝对不要跳过最初的测试覆盖率步骤 - 在测试覆盖率不足的情况下先进行重构会导致无法检测到的破坏。在任何代码更改之前，务必运行 accelint-ts-testing。
• 绝对不要按顺序运行最佳实践和性能审计 - 分别运行它们会为同一份代码产生相互矛盾的建议。务必并行运行，以查看合并后的建议。
• 绝对不要逐个呈现问题以供批准 - 务必先在带编号的表格中显示所有问题，然后展示每个问题的详细前后代码，最后再要求按编号列表接受。这可以防止出现极度不一致的呈现方式，并让用户发现并行流程之间的冲突。
• 绝对不要跳过显示概览表格 - 阻塞项：在展示任何详细更改之前，你务必显示带有所有问题的 emoji 严重程度表格。没有例外。
• 绝对不要在展示所有详细更改之前请求批准 - 阻塞项：在询问“应用哪些问题？”之前，你务必展示每个问题的完整前后代码。
• 绝对不要自动应用所有建议 - 每项更改都需要用户批准（接受/拒绝/其他），以保持代码所有权并防止不必要的修改。
• 绝对不要运行一次性命令来代替文档化的验证命令 - audit-process 文件记录了确切的验证命令。请逐字使用这些命令。绝对不要临时改用 npm test、bun test 或类似命令，除非它们与文档化的命令完全匹配。
• 绝对不要在完成一个步骤后跳过保存进度 - 在每一个步骤完成后，务必立即将详细进度保存到 audit-process 文件，然后再进入下一步。否则上下文限制会中断流程。
• 绝对不要跳过 100 次通过的 PBT 验证 - 当添加基于属性的测试时，你务必运行测试套件 100 次以验证稳定性。PBT 中随机失败很常见。这是阻塞性要求 - 在连续 100 次通过之前不要继续。关闭覆盖率报告运行测试以提高速度和稳定性。
• 绝对不要在上下文耗尽时丢失进度 - 在每个步骤后将详细进度保存到 audit-process 文件。在大型审计中上下文限制是必然的。
• 绝对不要假设基于属性的测试是稳定的 - PBT 中随机测试失败很常见。在接受之前，将新的属性测试运行 100 次以验证稳定性。关闭覆盖率报告运行测试以提高速度和稳定性。
• 绝对不要到处添加 PERF 注释 - 仅当 // PERF: 注释能提供未来开发者无法自行发现的有意义见解时才添加。
• 绝对不要在未完成全部 9 个步骤的情况下将文件标记为完成 - 部分审计会使文件处于不一致状态。完成所有步骤，或标记为进行中。
• 绝对不要在构建损坏的情况下继续 - 在继续下一步之前，立即修复编译错误、测试失败和 lint 问题。
• 绝对不要在 main 分支中运行审计 - 务必创建隔离的 worktree，以防止与并行审计冲突并允许安全实验。

在开始审计之前，请询问

在启动全面审计之前，应用以下检查：

范围验证

• 此路径是否有效且可访问？ 在创建 TODO 列表之前，验证文件或目录是否存在。
• 是否有可用的测试和构建命令？ 在开始之前，检查 package.json 或向用户询问验证命令。
• 这次审计将涉及多少个文件？ 大型目录（>5 个文件）将需要多个会话。提前设定预期。

会话管理

• 这是新审计还是恢复审计？ 在创建新文件之前，先检查 .agents/audit/ 中是否已有 audit-process 文件。
• 这能在一个会话内完成吗？ 估计每个会话最多约 1-5 个文件。如果规模更大，请规划恢复方案。
• 验证命令是否已知？ 从一开始就在 audit-process 文件中记录确切的 test/build/lint 命令。

变更理念

• 用户的风险容忍度如何？ 有些用户希望采纳每一条建议，另一些则只想要关键修复。在第一次交互式提示词之前先澄清。
• 是否应包含性能微优化？ 对于所有项目而言，1.05x-1.15x 的收益可能不值得为此改动代码。

如何使用

此技能会创建并维护一个审计过程文件，用于跨会话跟踪进度。它会以交互式审批的方式，对每个文件系统地运行四个审计技能。

工作流概览

1. 初始化 - 创建 TODO 列表和审计跟踪文件
2. 对每个文件 - 运行 9 步审计流程并获得用户批准
3. 跟踪进度 - 每一步后都保存，以应对上下文限制
4. 归档已完成项 - 将完成的文件移入历史文件

主审计工作流

第 1 步：初始化审计

检查现有审计： 查看 .agents/audit/ 目录（位于原始仓库根目录）中是否存在审计流程文件。

注意： 请确保 .agents/audit/ 已加入项目的 .gitignore，以免提交审计跟踪文件。

如果正在恢复现有审计，请阅读 audit-process 文件以了解当前状态：

1. 检查完成状态：

   • 查看 "Current Status" 部分，了解已完成和剩余的文件
   • 查看 "Files to Audit" 部分，了解待处理和已完成的明细
   • 如果所有文件都标记为 "Completed"，则审计已完成

2. 检查 worktree 状态（向后兼容）：

   • 如果存在 "Worktree Information" 部分：验证 worktree 是否仍然存在，并切换到该 worktree
   • 如果没有记录 worktree：这是 worktree 支持之前的旧版审计。在当前分支继续，不要创建 worktree。
   • 注意：只有在此功能之后创建的新审计才会使用 worktree

3. 从 "Resume Instructions" 部分继续

如果是恢复审计，请跳至第 2 步。

对于新审计，请创建隔离的 worktree：

阻塞性要求：所有审计工作都必须在隔离的 worktree 中进行，以防止与并行审计发生冲突，并允许安全回滚。

1. 使用带时间戳的分支创建 worktree：

   timestamp=$(date +%Y%m%d-%H%M%S)
   git worktree add .agents/worktrees/audit-${timestamp} -b audit/${timestamp}
   

2. 切换到 worktree 目录：

   cd .agents/worktrees/audit-${timestamp}
   

3. 记录 worktree 路径 - 整个审计过程中你都将在这个目录中工作

重要： worktree 创建在 .agents/worktrees/（而非 .agents/audit/）中，以避免与存放跟踪文件且已被 gitignore 的 .agents/audit/ 目录发生冲突。

创建跟踪文件：

强制要求 - 阅读整个文件：在创建任何跟踪文件之前，你必须从头到尾完整阅读 assets/audit-process-template.md，以了解所需的精确格式和结构。 阅读此文件时，绝不能设置任何范围限制。

同样，你必须阅读 assets/audit-history-template.md 以了解归档格式。

不要再次加载这些模板 - 它们仅在新审计开始时需要一次。

在原始仓库（不在 worktree 中）创建带时间戳的跟踪文件：

• 返回原始仓库根目录：cd $(git rev-parse --show-toplevel)
• 创建 .agents/audit/audit-process-${timestamp}.md（使用与 worktree 相同的时间戳）
• 创建 .agents/audit/audit-history-${timestamp}.md（相同的时间戳）
• 返回 worktree：cd .agents/worktrees/audit-${timestamp}

重要： 跟踪文件位于原始仓库的 .agents/audit/ 目录中（该目录应被 gitignore），因此它们不会随审计变更一起提交。

构建 TODO 列表：

查找目标目录中的所有 TypeScript 文件，排除 .test.ts、.spec.ts 和 .bench.ts 文件。如果给定的是单个文件，请验证它不是测试/基准测试文件。

填充 audit-process 文件：

• 将 worktree 路径和分支添加到 "Worktree Information" 部分
• 将所有文件以 "Pending" 状态添加到 "Files to Audit" 部分
• 记录确切的验证命令（test/build/lint）
• 将 "Current File" 设置为第一个待处理文件
• 保存文件

第 2 步：审计每个文件（8 步流程）

对于待处理列表中的每个文件，请遵循以下确切顺序：

阶段 1：初始测试覆盖率

步骤 1：运行 accelint-ts-testing 技能

Invoke the accelint-ts-testing skill.

[file-path]

步骤 2：交互式变更

阻塞 - 需要交互式批准：

继续之前，你必须完成全部三个检查点：

1. ✅ 显示包含所有问题的 emoji 严重程度表格（参见“交互式变更批准模式”）
2. ✅ 为每一个问题展示详细的变更前后代码
3. ✅ 询问“应用哪些问题？”并提供带编号的列表供接受 无例外。如果你跳过任何检查点，你就是在违反工作流。

• 应用已接受的变更
• 阻塞要求： 如果添加了基于属性的测试，运行验证：

  # Run test suite 100 times to verify PBT stability
  for i in {1..100}; do <test-command> || break; done
  

  • 在不带覆盖率报告的情况下运行测试，以防止覆盖率冲突
  • 如果任何一次运行失败，检查失败的种子
  • 修复测试属性（为任意生成器添加约束：日期范围、过滤 NaN、安全字符串）
  • 重新运行 100 次，直到连续 100 次通过
  • 在此验证通过之前，不要继续执行步骤 3
• 在“当前文件 - 详细进度”部分记录发现
• 更新状态以显示步骤 1 ✅、步骤 2 ✅
• 立即将进度保存到 audit-process 文件，然后再继续

阶段 2：代码质量与性能分析

步骤 3：并行运行两个技能

关键：将这些一起运行，以避免相互矛盾的建议：

Invoke the accelint-ts-best-practices skill.

[file-path]

步骤 8：交互式变更

阻塞 - 需要交互式批准：

继续之前，你必须完成全部三个检查点：

1. ✅ 显示包含所有文档问题的 emoji 严重程度表格（参见“交互式变更批准模式”）
2. ✅ 为每一个问题展示详细的变更前后代码
3. ✅ 询问“应用哪些问题？”并提供带编号的列表供接受 无例外。如果你跳过任何检查点，你就是在违反工作流。

• 应用已接受的变更
• 运行最终验证，确保文档没有破坏任何内容（使用 audit-process 文件中的精确命令）
• 在“当前文件 - 详细进度”中记录
• 更新状态以显示步骤 7 ✅、步骤 8 ✅
• 立即将进度保存到 audit-process 文件，然后再继续执行步骤 3（归档）

步骤 3：归档已完成的文件

当某个文件的所有 9 个步骤都完成时：

1. 将详细进度移动到历史文件

   • 复制整个“当前文件 - 详细进度”部分
   • 追加到 audit-history 文件
   • 在该文件部分的末尾添加汇总统计

2. 更新 audit-process 文件

   • 在“待审计文件”部分将文件标记为“已完成”
   • 清空“当前文件 - 详细进度”部分
   • 将“当前文件”设置为下一个待处理文件
   • 为下一个文件更新“恢复说明”
   • 更新“当前状态”计数

3. 保存两个文件

步骤 4：继续或完成

如果存在更多待处理文件：

• 返回步骤 2 处理下一个文件
• 监控上下文使用情况 - 如果接近限制，停止并保存进度

如果所有文件都已完成：

1. 在工作树中运行最终验证：

   • 运行最终完整测试套件 + lint 验证
   • 确保所有变更在合并前通过

2. 将工作树合并回原始分支：

   # Extract timestamp from current worktree directory name
   # We're in .agents/worktrees/audit-YYYYMMDD-HHMMSS
   timestamp=$(basename $(pwd) | sed 's/audit-//')
   
   # Get the original branch from this audit's process file (in original repo)
   repo_root=$(git rev-parse --show-toplevel)
   audit_process_file="${repo_root}/.agents/audit/audit-process-${timestamp}.md"
   original_branch=$(grep "^**Original Branch:**" ${audit_process_file} | cut -d'`' -f2)
   
   # Commit all changes in worktree
   git add -A
   git commit -m "refactor: complete TypeScript audit
   
   - Improved test coverage across all files
   - Applied type safety and best practice improvements
   - Optimized performance where beneficial
   - Enhanced documentation
   
   Co-Authored-By: {current_model}"
   
   # Switch back to original branch
   cd "${repo_root}"
   git checkout ${original_branch}
   
   # Merge the audit branch
   git merge --no-ff audit/${timestamp}
   

3. 清理工作树：

   # Remove the worktree (use the timestamp extracted earlier)
   git worktree remove .agents/worktrees/audit-${timestamp}
   
   # Optionally delete the audit branch
   git branch -d audit/${timestamp}
   

4. 更新 audit-process 文件以记录完成情况：

   • 添加包含总统计的完成摘要
   • 记录合并提交哈希
   • 将审计标记为“✅ 已完成 - 已合并到 ${original_branch}”

5. 报告结果：

   • 所有文件的总体统计
   • 合并提交信息
   • 确认工作树已清理

进度跟踪格式

文件状态标记：

• [ ] - 待处理（未开始）
• [x] - 已完成（全部 9 个步骤完成，已移动到历史记录）

步骤状态标记：

• ✅ - 已完成
• 🔄 - 进行中
• ⏸️ - 待处理（未开始）

详细进度模板：

### filename.ts - Audit Status 🔄 IN PROGRESS

**Overall Progress:** X% complete (Step Y of 8)

#### ✅ Step 1: Test Coverage - COMPLETE
[Findings, changes applied, test results]

#### 🔄 Step 2: Interactive Changes - IN PROGRESS
[Current change being reviewed, user decision needed]

#### ⏸️ Step 3: Code Quality Analysis - PENDING
[Not started yet]

交互式变更批准模式

关键： 始终使用两阶段呈现模式。绝不要逐个呈现问题，也不要在展示所有变更之前请求批准。

阶段 1：概览表（快速扫描）

使用 emoji 严重程度指示符，以编号表格呈现所有问题：

## Found Issues Summary (X total)

| # | Severity | Type | Lines | Description |
|---|----------|------|-------|-------------|
| 1 | 🛑 Critical | Type Safety | 45-47 | Missing null check on user object |
| 2 | ⚠️ High | Performance | 89 | N+1 query in loop - use batch fetch |
| 3 | ⚡ Medium | Performance | 120-125 | Filter+map → single pass with reduce |
| 4 | 🔵 Low | Best Practice | 78 | Use const assertion for readonly array |
| 5 | ✅ Info | Documentation | 12 | Missing JSDoc return type |

严重程度图例：

• 🛑 严重 - 导致运行时错误、安全漏洞或数据丢失
• ⚠️ 高 - 类型错误、显著的性能问题或 API 破坏性变更
• ⚡ 中 - 中等性能收益、可维护性改进
• 🔵 低 - 轻微优化、样式改进
• ✅ 信息 - 文档、注释、非功能性改进

阶段 2：详细变更（完整上下文）

在显示概览表之后，展示每个问题的完整修改前/后代码：

---

### Issue #1: Missing null check (🛑 Critical - Type Safety)
**Lines:** 45-47
**Problem:** Function doesn't handle null user case
**Impact:** Runtime TypeError when user is null

❌ **Before:**
```typescript
function getUsername(user: User | null) {
  return user.name; // TS error + runtime crash
}

✅ 修改后：

function getUsername(user: User | null) {
  return user?.name ?? 'Anonymous';
}

预期收益： 防止运行时 TypeError，修复 TS 编译错误

---

问题 #2：N+1 查询性能（⚠️ 高 - 性能）

[... 每个问题采用相同的详细格式 ...]

---

问题 #3：Filter+map 优化（⚡ 中 - 性能）

[... 每个问题采用相同的详细格式 ...]

---

[继续处理所有问题...]

---

应用哪些问题？ 输入编号（例如 "1, 2, 5" 或 "all" 或 "skip"）：

**Key Benefits:**
- Overview table allows quick scanning for conflicts across parallel processes
- Numbered list makes acceptance explicit and trackable
- All code changes shown upfront before any approval
- Emoji severity indicators enable instant visual prioritization
- Consistent format prevents wildly varying presentations

Wait for user response with numbered list before applying any changes.

## Verification Commands

The audit-process file MUST document exact verification commands. Common patterns:

**Node.js projects:**
```bash
cd <project-root>; npm test
cd <project-root>; npm run build
cd <project-root>; npm run lint

Bun 项目：

cd <project-root>; bun run test
cd <project-root>; bun run build
cd <project-root>; bun run lint
cd <project-root>; bun run bench  # if applicable

Monorepo 包：

cd <workspace-root>/packages/<package-name>; npm test

始终使用 audit-process 文件中的确切命令。切勿猜测。

重要说明

• 请勿加载 README.md - 它包含与本文件重复的用户面向文档。所有 Agent 指令均包含在 SKILL.md 中。
• Worktree 位置： 所有审计工作都在 .agents/worktrees/audit-${timestamp} 中进行，以避免与 gitignore 的 .agents/audit/ 目录产生冲突。
• 跟踪文件位置： 审计流程和历史文件存储在原始仓库的 .agents/audit/ 目录（已 gitignore）中，并且不会随审计变更一起提交。
• 基于属性的测试稳定性： 如果属性测试随机失败，请检查失败的确切种子，并针对该种子验证修复。向 arbitrary 添加约束（日期范围、过滤 NaN、安全字符串）以防止误报。
• 并行技能执行： 当并行运行 ts-best-practices 和 ts-performance 时，请等待两者都完成后再呈现建议。这样你可以识别并合并重叠的建议。
• 上下文窗口管理： audit-process 文件的设计可在上下文限制下存活。每完成一步后，保存进度。如果你必须在文件处理中途停止，请准确记录你所在步骤以及下一步操作。
• 构建失败会阻碍进度： 如果验证命令失败，切勿继续下一步。请先修复问题或回滚变更。
• PERF 注释准则： 仅在优化不明显时添加性能注释。"使用 for...of 代替 map" 不需要注释。"记忆化反序列化器以避免重复 JSON 解析" 则需要。
• 历史文件为只写： 仅在你需要理解之前的决策或考虑回滚变更时才读取 audit-history 文件。否则，它纯粹用于归档。