oh-my-openagent 技术债审计协议:九维度扫描、sg 结构搜索与 TECH_DEBT_AUDIT.md 产物生成

本文基于 tech-debt-audit 技能协议,系统讲解 oh-my-openagent(下称 OMO)内置的技术债审计流程:如何以 grep、glob、ast-grep(sg)、LSP 诊断与子代理并行任务为工具链,在九个大维度上对代码库做可引用、可验证的扫描,并产出一份带严重度分级、工时估算和优先级排序的 TECH_DEBT_AUDIT.md 审计产物。读完本文,你可以掌握一套可复制到任意 TypeScript/Bun 单仓的 Agent 驱动代码健康检查方法论。

协议定位与触发方式

该技能定义在 .agents/skills/tech-debt-audit/SKILL.md,是一个模型无关(model-agnostic)的审计协议,专为 OMO 这类复杂代码库设计。其 frontmatter 中声明的触发词包括 tech debt、technical debt、debt audit、code health、codebase health check、audit code quality 等——当你向 Agent 提出"帮我做代码库健康检查/架构评审/清理规划"时,就会走这条协议。

协议的核心原则写在开篇:每一条发现(findings)必须引用 file:line:col,不允许无证据的泛泛断言。产物统一写入仓库根目录的 TECH_DEBT_AUDIT.md。

工具链:标准工具 + 可选 CodeGraph

协议使用 OMO 的内置工具完成扫描,分为两层:

标准层(始终可用):grep、glob、bash(其中可调用 sg 即 ast-grep CLI)、read、lsp_diagnostics、task(并行子代理)。

CodeGraph 增强层(可选):若项目中安装了 CodeGraph(用 codegraph status 检查),其 MCP 工具(codegraph_search、codegraph_callers、codegraph_callees、codegraph_impact、codegraph_explore 等)可以取代或补充下文标注了"CodeGraph Enhancement"的维度扫描。CodeGraph 提供按名符号检索、任意函数的调用者/被调用者分析、变更前的影响面(blast radius)评估、一次调用聚合入口点与相关符号的智能上下文构建,以及框架感知的路由映射。需要把 codegraph MCP server 配置进项目的 .mcp.json 或全局 MCP 配置,技能会自动检测其可用性。一个关键限制:通过 task() 派生的子代理不能使用 CodeGraph,它们只能走标准工具路径——这直接影响后文 Phase 2 的分工设计。

标准层工具的源码佐证

协议里的 sg 命令背后是 OMO 仓库自带的 ast-grep-mcp 包(@oh-my-opencode/ast-grep-mcp,服务名 ast_grep,提供 search、rewrite、scan 三个工具)。从 packages/ast-grep-mcp/AGENTS.md 与 sg 进程封装 可以看到该工具链的工程约束,审计时写 sg 命令可以据此把握边界:

• 匹配上限 maxMatches 为 1–500,默认 50;整次调用超时预算默认 300000 ms(即 5 分钟),也是上限;
• pattern 按 UTF-8 字节计,上限 16 KiB;rewrite 规则上限 64 KiB;
• scan 不允许隐式发现 sgconfig.yml,规则源必须显式二选一(ruleFile XOR inlineRules);
• 支持语言涵盖 typescript、tsx、python、go、rust、bash 等 24 种(见 mcp.ts 中的 LANGUAGES 常量),因此协议的维度扫描对多语言仓库同样适用。

协议第 3 维引用的 lsp_diagnostics 则对应 lsp-core 工具定义:工具名 diagnostics(别名 lsp_diagnostics),必传参数 filePath(文件或目录),可选 severity 过滤(error/warning/information/hint/all,默认 all)——所以协议里 lsp_diagnostics(filePath="<src-dir>") 这种按目录取当前类型错误的用法是受 schema 支持的。

审计产物:TECH_DEBT_AUDIT.md 的七个必备章节

协议对输出格式做了硬性规定,TECH_DEBT_AUDIT.md 必须包含:

1. Executive Summary —— 3–5 句:整体健康度、最差的维度、quick wins 数量;
2. Mental Model —— 用一段话描述仓库架构(它做什么、技术栈、模块边界);
3. Findings Table —— 列为:ID、Category、File:Line、Severity(Critical/High/Medium/Low)、Effort(Hours)、Description、Recommendation;
4. Top 5 Priorities —— 按 impact/effort 比排序;
5. Quick Wins Checklist —— 单项 30 分钟以内可完成;
6. "Looks Bad But Is Fine" —— 解释"看着像债但属有意为之"的模式;
7. Open Questions —— 需要维护者澄清的问题。

其中第 6 章尤其体现协议的专业性:代码库里大量"坏味道"其实是刻意设计(比如 OMO 仓库 packages/ 下大量 *-core 包是为了解耦而做的共享核心抽取),审计必须区分真债与假债,而不是见到长文件就开火。

Phase 0:定向(Orient)——先建立心智模型

在开始扫描之前,标准流程(始终执行)共六步:

1. glob("**/*.ts") / glob("**/*.py") 等 —— 摸清语言栈;
2. glob("**/package.json") + read() —— 依赖与构建工具链;
3. bash("git log --oneline -200") —— 统计 churn,找出变更最频繁的文件;
4. glob("**/*") + 基本计算 —— 找出最大文件(>300 LOC 即候选);
5. 交叉引用"高 churn + 大文件" = 技术债热点区;
6. 在自己的工作上下文中写下心智模型段落。

第 5 步是整套协议中最有信息量的一步:高频变更和大体量同时命中的文件,几乎必然是架构摩擦点。以 OMO 仓库为例,packages/omo-opencode/src 下有 2700+ 个源文件、packages/omo-senpi/src 下有 700+ 个源文件,若按此流程跑 Phase 0,git log 的 churn 数据加文件行数交叉表就能快速定位真正需要深挖的模块。

若 CodeGraph 可用,可用两个查询替代"靠目录名猜模块边界":

codegraph_explore(query="architecture overview and main modules")

返回按文件分组的符号关系与源码,直接作为架构心智模型。

codegraph_explore(query="main entry points and execution flow")

暴露真实入口点与调用链,让你理解代码实际如何流动,而不是目录布局暗示的流动方式。

Phase 1:九大维度审计

每个维度都给出"标准命令(始终运行)"和"该标记什么"两部分;维度内应并行发起工具调用。以下逐维继承协议原文。

维度 1:架构腐化(Architectural Decay)

标准命令:

• bash("sg -p \"import { $$$ } from '$SRC'\" -l ts .") —— 构建模块图,寻找环状模式;
• bash("sg -p \"class $NAME { $$$ }\" -l ts .") —— 检查 god class;
• grep("TODO|FIXME|HACK|XXX|WORKAROUND|TEMP") —— 带标签的债务标记;
• grep("async|await") 扫在"看起来是同步"的文件上 —— 错位异步边界;
• 对 Phase 0 找出的每个大文件执行 bash("wc -l <file>")。

CodeGraph 增强:对 grep/glob 发现的疑似死代码导出,用 codegraph_callers(symbol="<suspected-dead-function>") 查调用者——若结果为零(排除测试文件)即为死代码;用 codegraph_impact(target="<module-or-file>", direction="upstream") 追踪关键模块的依赖方,A 依赖 B 且 B 依赖 A 即构成环;用 codegraph_explore(query="module dependencies and architecture boundaries") 普查真实模块结构。

该标记什么:

• 500 LOC 的文件(god file);

• 80 LOC 或嵌套 >4 层的函数;

• 方法 >15 个或 >400 LOC 的类;
• 导入环(A → B → A);
• 死导出:定义了但从未被其他地方导入的函数/类(CodeGraph 下用 codegraph_callers);
• 被注释掉的代码块(连续 >3 行)。

维度 2:一致性腐烂(Consistency Rot)

标准命令:

• bash("sg -p \"import $CLIENT from '$PKG'\" -l ts .") —— 多个 HTTP 客户端并存;
• grep("console.log|console.error|console.warn") —— 直接 console vs 统一 logger;
• bash("sg -p \"try { $$$ } catch ($$$) { $$$ }\" -l ts .") —— 错误处理模式普查;
• grep("as any|@ts-ignore|@ts-expect-error|as unknown") —— 类型逃逸;
• grep("eslint-disable|prettier-ignore") —— lint 压制。

该标记什么:同一件事有 3 种以上做法(HTTP、日志、校验、配置);混合命名规范(camelCase + snake_case + PascalCase);多个日期时间库并存;跨模块错误响应形状不一致。

维度 3:类型与契约债(Type & Contract Debt)

标准命令:

• bash("sg -p \"$VALUE as any\" -l ts .") —— 运行时类型逃逸;
• grep("@ts-expect-error") —— 被压制的错误;
• grep("@ts-ignore") —— 被压制的错误(legacy);
• bash("sg -p \"$NAME: any\" -l ts .") —— 声明为 any 的位置;
• lsp_diagnostics(filePath="<src-dir>") —— 当前的类型错误。

该标记什么:公共 API 和导出接口上的 any 类型;未标注类型的函数参数;API/IO 边界处缺少 schema 校验;按文件分组的 LSP 类型错误。

维度 4:测试债(Test Debt)

标准命令:

• glob("**/*.test.ts") —— 找出全部测试文件;
• bash("bun test 2>&1 | grep -E '(fail|skip|todo)'") —— 当前测试健康度;
• 将 Phase 0 的高 churn 文件与测试存在性交叉比对。

该标记什么:关键路径文件零测试;被跳过的测试(test.skip、describe.skip);断言实现细节而非行为的测试;慢测试(单条 >1s)。这条命令与 OMO 实际测试栈一致——仓库根 package.json 基于 Bun,大量 *.test.ts 以 bun test 运行,审计时可直接复用。

维度 5:依赖与配置债(Dependency & Config Debt)

标准命令:

• bash("npm audit --omit=dev 2>&1 | head -40") —— 已知 CVE(前提是 node_modules 存在);
• read("package.json") —— 依赖数量与陈旧依赖;
• grep(".env|process.env|Bun.env") —— 环境变量使用;
• 在非配置文件里 grep("API_KEY|SECRET|PASSWORD|TOKEN") —— 硬编码配置。

CodeGraph 增强:对少数关键内部模块(logger、config loader、HTTP client)执行 codegraph_impact(target="<core-utility-function>", direction="upstream"),看它们被依赖多广。一个被广泛依赖但错误处理或类型安全性差的模块是高优先级重构对象,因为改动它会波及所有上游。

该标记什么:落后一个大版本的依赖;功能重复的库;README 未文档化的环境变量;硬编码的环境特定值。

维度 6:性能与资源卫生(Performance & Resource Hygiene)

标准命令:

• bash("sg -p \"for ($$$ of $$$) { $$$ await $$$ }\" -l ts .") —— 循环内 await;
• grep("await.*map|await.*filter|await.*forEach") —— 顺序异步迭代;
• grep("Promise\\.all|Promise\\.allSettled") —— 已有的并行模式(正面信号);
• grep("addEventListener|on\\(|subscribe") 附近没有 removeEventListener|off\\(|unsubscribe —— 监听器卫生。

该标记什么:for/of 循环内的 await(本可并行却顺序执行);N+1 查询模式;事件监听器/定时器/handle 缺少清理;不必要的序列化/反序列化。

维度 7:错误处理与可观测性(Error Handling & Observability)

标准命令:

• bash("sg -p \"catch ($$$) { $$$ }\" -l ts .") —— catch 块普查;
• grep("catch.*{}|catch.*{\\s*}") —— 空 catch 块;
• grep("console.error|logger\\.error|log\\.error") —— 真实的错误日志;
• bash("sg -p \"throw new $ERR($$$)\" -l ts .") —— 使用了哪些错误类型。

CodeGraph 增强:用 codegraph_callers(symbol="<key-error-handler-or-middleware>") 与 codegraph_explore(query="how errors propagate through <key-error-handler>") 追踪错误在调用链中的传播——若在多层被捕获后吞掉,即为发现项;用 codegraph_impact(target="<error-class-or-interface>", direction="upstream") 检查自定义错误类的影响面——若改动一个错误类型会波及 20+ 消费方,说明该错误契约过紧。

该标记什么:空 catch 块(最恶劣);无恢复逻辑的泛型 catch (e) { console.error(e) };跨模块不一致的错误形状;关键路径缺少结构化日志;promise 链中吞错(.catch(() => {}))。

维度 8:安全卫生(Security Hygiene)

标准命令(均在源码文件而非配置/env 文件中执行):

• grep("api[Kk]ey|api_secret|password|secret|token|credential");
• grep("SELECT .* FROM|INSERT INTO|UPDATE.*SET|DELETE FROM") —— SQL 拼接;
• grep("innerHTML|dangerouslySetInnerHTML") —— XSS 向量;
• grep("eval\\(|Function\\(|setTimeout\\(.*string|setInterval\\(.*string") —— 代码注入。

该标记什么:源码中硬编码的密钥;字符串拼接 SQL;innerHTML / dangerouslySetInnerHTML;eval() 或基于字符串的 setTimeout/setInterval;宽松的 CORS 或认证中间件。

维度 9:文档漂移(Documentation Drift)

标准命令:

• read("README.md") —— 检查宣称是否与实现相符;
• grep("@param|@returns|@throws") —— docstring 覆盖度;
• grep("FIXME|TODO|HACK|XXX|WORKAROUND") —— fixme 密度;
• 将 README 中的 API 示例与真实函数签名比对。

该标记什么:README 宣称了不存在的功能;公共函数没有任何文档注释;与代码矛盾的注释;过期的架构决策记录(ADR)。

Phase 2:并行子代理深挖(>50k LOC 仓库)

对大型代码库,协议建议把最重的维度委派给并行子代理。模板如下:

task(category="unspecified-low", run_in_background=true, load_skills=[], prompt="[CONTEXT] Tech debt audit. [GOAL] Audit dimensions 1 (Architecture) and 2 (Consistency). [REQUEST] Run ast_grep and grep searches for dimensions 1-2 from the tech-debt-audit skill. Report every finding with file:line:col. Tag severity: Critical/High/Medium/Low.")
task(category="unspecified-low", run_in_background=true, load_skills=[], prompt="[CONTEXT] Tech debt audit. [GOAL] Audit dimensions 3 (Type debt) and 7 (Error handling). [REQUEST] Run searches for dimensions 3 and 7 from the tech-debt-audit skill. Report every finding with file:line:col. Tag severity.")

要点:对最重的维度派 2–3 个子代理,并行收集结果再综合;主代理自己处理 CodeGraph 查询,因为子代理无法使用 CodeGraph,只能走标准工具路径。task() 的参数形态(category、run_in_background、load_skills、prompt)与 OMO 的代理编排能力对应,run_in_background=true 保证扫描不阻塞主线程。

Phase 3:综合与交付

1. 收集所有发现:直接工具调用、CodeGraph 查询(如有)、子代理结果;
2. 去重 —— 同一问题被多个维度提到时合并;
3. 按严重度分级:
   • Critical —— 正在导致错误行为、数据丢失或安全漏洞;
   • High —— 会在生产中引发问题;阻塞维护;
   • Medium —— 降低可维护性;违反约定;
   • Low —— 表面问题;顺手就修;
4. 对每个发现保守估算工时(小时);
5. 写入含全部必备章节的 TECH_DEBT_AUDIT.md;
6. 向用户汇报摘要。

协议还附带一段严重度基准:

Critical = actively causing bugs or security holes
High     = will cause problems under normal operation; blocks changes
Medium   = reduces maintainability; inconsistent; violates team conventions
Low      = cosmetic; would be nice to fix when nearby

收尾前的快速自检清单

协议以五条自查项收尾,这是保证产物质量可验证的关键:

• [ ] 每条具体发现都有 file:line:col 引用;
• [ ] 没有无证据的泛泛断言;
• [ ] "Looks Bad But Is Fine" 章节解释了至少 2–3 个模式;
• [ ] Top 5 优先级按 impact/effort 排序;
• [ ] Quick wins 均为单项 <30 分钟可完成。

小结:这套协议的可复用要点

回看 SKILL.md 全篇,其方法论可归纳为四个可复用的设计:

1. churn × 体量定位热点:Phase 0 用 git log 与文件行数交叉引用,把有限精力投到真正的高摩擦文件;
2. 结构搜索优先于文本搜索:所有关键模式(导入环、god class、循环内 await、catch 块)都走 sg -p 的 AST 级 pattern,配合 ast-grep-mcp 的 16 KiB pattern / 500 匹配 / 5 分钟超时约束,扫描既精准又不会跑飞;
3. LSP 诊断作为类型债的权威来源:维度 3 直接调用 lsp_diagnostics(见 lsp-core 工具定义),让编译器而不是正则来判定类型错误;
4. 可选项渐进增强:CodeGraph 只在"如果可用"的前提下升级死代码、循环依赖、影响面分析,且明确子代理不可用 CodeGraph 的边界——协议对工具能力做了诚实的降级设计。

对于 OMO 这样的多包(monorepo)TypeScript/Bun 仓库,该协议的全部标准命令开箱即可执行;对引入 CodeGraph 的项目,则在架构维度获得调用图级证据。最终产物 TECH_DEBT_AUDIT.md 的七章节结构本身也值得作为团队代码审计报告的标准模板直接使用。