stack-audit

Stack Audit

Stack-audit 用于扫描代码库，识别 Outfitter Stack 的适配候选点，并生成审计报告。

用途

在规划将现有 TypeScript 项目迁移到 Outfitter Stack 之前，先用本技能扫描代码库，识别需要改造的位置，评估迁移范围与工作量。

主要能力

识别 throw 语句、try-catch 块等异常处理代码
识别 console 日志调用（console.log/error/warn/debug/info）
识别硬编码路径，包括 homedir()、os.homedir 及 ~/. 形式的波浪线路径
识别自定义错误类（class XxxError extends Error）及其使用次数
生成审计报告和分阶段迁移计划文件
提供错误分类参考表和工作量估算参考

使用方式

方式一：运行扫描器（推荐用于大型项目）

bun run plugins/outfitter-stack/skills/stack-audit/scripts/init-audit.ts [project-root]

生成 .outfitter/adopt/ 目录，包含：

audit-report.md - 扫描结果与范围
plan/ - 分阶段任务文件

方式二：手动扫描（较小项目）

运行以下审计命令了解范围。

关键问题 - 异常：

Count throw statements

rg "throw (new |[a-zA-Z])" --type ts -c

List throw locations

rg "throw (new |[a-zA-Z])" --type ts -n

Count try-catch blocks

rg "(try {|catch ()" --type ts -c

Console 使用：

Count console statements

rg "console.(log|error|warn|debug|info)" --type ts -c

List console locations

rg "console.(log|error|warn|debug|info)" --type ts -n

硬编码路径：

Homedir usage

rg "(homedir()|os.homedir)" --type ts -c

Tilde paths

rg "~/." --type ts -c

Combined path issues

rg "(homedir|~/.)" --type ts -n

自定义错误类：

Find custom error classes

rg "class \w+Error extends Error" --type ts -n

Count usage of custom errors

rg "new MyCustomError(" --type ts -c

生成结构

.outfitter/adopt/ ├── audit-report.md # Scan results, scope, recommendations └── plan/ ├── 00-overview.md # Status dashboard, dependencies ├── 01-foundation.md # Dependencies, context, logger ├── 02-handlers.md # Handler conversions ├── 03-errors.md # Error taxonomy mappings ├── 04-paths.md # XDG path migrations ├── 05-adapters.md # CLI/MCP transport layers ├── 06-documents.md # Documentation updates └── 99-unknowns.md # Items requiring review

迁移阶段

Stage 1. Foundation - 无前置依赖 - 安装包、创建 context/logger Stage 2. Handlers - 依赖 Foundation - 将 throw 转换为 Result Stage 3. Errors - 依赖 Handlers - 映射到错误分类体系 Stage 4. Paths - 无前置依赖 - XDG 路径、securePath Stage 5. Adapters - 依赖 Handlers - CLI/MCP 包装层 Stage 6. Documents - 依赖全部 - 更新文档以反映模式 Stage 99. Unknowns - 无前置依赖 - 随时审查

审计报告字段

Exceptions：需转换为 Result 的 throw 语句
Try/Catch：需重构的错误处理块
Console：需转换为结构化日志的记录
Paths：需转换为 XDG 的硬编码路径
Error Classes：需映射到分类体系的自定义错误
Handlers：包含 throw 的待转换函数
Unknowns：需要人工审查的复杂模式

错误分类参考

映射错误时使用此参考：

NotFoundError -> NotFoundError，分类 not_found InvalidInputError -> ValidationError，分类 validation DuplicateError -> ConflictError，分类 conflict UnauthorizedError -> AuthError，分类 auth ForbiddenError -> PermissionError，分类 permission Generic Error -> InternalError，分类 internal

工作量估算

按数量估算工作量级别：

0 个：None
1-5 个：Low
6-15 个：Medium
16+ 个：High

结果解读

高优先级项：

包含 3 个及以上 throw 语句的函数（错误处理复杂）
包含 3 个及以上 try-catch 块的文件（可能需要重构）
使用次数高的自定义错误类

中优先级项：

零散的 throw 语句（简单转换）
Console 日志（迁移直接）
硬编码路径（机械替换）

低优先级项：

文档更新（可最后进行）
测试文件更新（跟随处理器变更）

审计后的下一步

审查 audit-report.md 的准确性
在 plan/00-overview.md 中调整优先级
从 Stage 1（Foundation）开始
加载 outfitter-stack:stack-patterns 获取转换指导
加载 outfitter-stack:stack-templates 获取脚手架

约束

始终：

在规划适配前先运行审计
审查 unknowns 中的复杂模式
在承诺前估算工作量

绝不：

跳过审计阶段
低估 try-catch 的复杂度
忽略自定义错误类

技能介绍

用途