oh-my-openagent 技術債審計協議:九維度掃描、sg 結構搜索與 TECH_DEBT_AUDIT.md 產物生成【免費下載鏈接】oh-my-openagentOmO: Drop your tokens. Ultrawork. Done.項目地址: https://gitcode.com/gh_mirrors/oh/oh-my-openagent本文基于 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)評估、一次調用聚合入口點與相關符號的智能上下文構建,以及框架感知的路由映射。需要把codegraphMCP 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,規則源必須顯式二選一(ruleFileXORinlineRules);支持語言涵蓋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(filePathsrc-dir)這種按目錄取當前類型錯誤的用法是受 schema 支持的。審計產物:TECH_DEBT_AUDIT.md 的七個必備章節協議對輸出格式做了硬性規定,TECH_DEBT_AUDIT.md必須包含:Executive Summary—— 3–5 句:整體健康度、最差的維度、quick wins 數量;Mental Model—— 用一段話描述倉庫架構(它做什么、技術棧、模塊邊界);Findings Table—— 列為:ID、Category、File:Line、Severity(Critical/High/Medium/Low)、Effort(Hours)、Description、Recommendation;Top 5 Priorities—— 按 impact/effort 比排序;Quick Wins Checklist—— 單項 30 分鐘以內可完成;Looks Bad But Is Fine—— 解釋看著像債但屬有意為之的模式;Open Questions—— 需要維護者澄清的問題。其中第 6 章尤其體現協議的專業性:代碼庫里大量壞味道其實是刻意設計(比如 OMO 倉庫packages/下大量*-core包是為了解耦而做的共享核心抽取),審計必須區分真債與假債,而不是見到長文件就開火。Phase 0:定向(Orient)——先建立心智模型在開始掃描之前,標準流程(始終執行)共六步:glob(**/*.ts)/glob(**/*.py)等 —— 摸清語言棧;glob(**/package.json)read()—— 依賴與構建工具鏈;bash(git log --oneline -200)—— 統計 churn,找出變更最頻繁的文件;glob(**/*) 基本計算 —— 找出最大文件(300 LOC 即候選);交叉引用高 churn 大文件 技術債熱點區;在自己的工作上下文中寫下心智模型段落。第 5 步是整套協議中最有信息量的一步:高頻變更和大體量同時命中的文件,幾乎必然是架構摩擦點。以 OMO 倉庫為例,packages/omo-opencode/src下有 2700 個源文件、packages/omo-senpi/src下有 700 個源文件,若按此流程跑 Phase 0,git log的 churn 數據加文件行數交叉表就能快速定位真正需要深挖的模塊。若 CodeGraph 可用,可用兩個查詢替代靠目錄名猜模塊邊界:codegraph_explore(queryarchitecture overview and main modules)返回按文件分組的符號關系與源碼,直接作為架構心智模型。codegraph_explore(querymain 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(symbolsuspected-dead-function)查調用者——若結果為零(排除測試文件)即為死代碼;用codegraph_impact(targetmodule-or-file, directionupstream)追蹤關鍵模塊的依賴方,A 依賴 B 且 B 依賴 A 即構成環;用codegraph_explore(querymodule 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(filePathsrc-dir)—— 當前的類型錯誤。該標記什么:公共 API 和導出接口上的any類型;未標注類型的函數參數;API/IO 邊界處缺少 schema 校驗;按文件分組的 LSP 類型錯誤。維度 4:測試債(Test Debt)標準命令:glob(**/*.test.ts)—— 找出全部測試文件;bash(bun test 21 | 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 --omitdev 21 | 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(targetcore-utility-function, directionupstream),看它們被依賴多廣。一個被廣泛依賴但錯誤處理或類型安全性差的模塊是高優先級重構對象,因為改動它會波及所有上游。該標記什么:落后一個大版本的依賴;功能重復的庫;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(本可并行卻順序執行);N1 查詢模式;事件監聽器/定時器/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(symbolkey-error-handler-or-middleware)與codegraph_explore(queryhow errors propagate through key-error-handler)追蹤錯誤在調用鏈中的傳播——若在多層被捕獲后吞掉,即為發現項;用codegraph_impact(targeterror-class-or-interface, directionupstream)檢查自定義錯誤類的影響面——若改動一個錯誤類型會波及 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(categoryunspecified-low, run_in_backgroundtrue, 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(categoryunspecified-low, run_in_backgroundtrue, 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_backgroundtrue保證掃描不阻塞主線程。Phase 3:綜合與交付收集所有發現:直接工具調用、CodeGraph 查詢(如有)、子代理結果;去重 —— 同一問題被多個維度提到時合并;按嚴重度分級:Critical—— 正在導致錯誤行為、數據丟失或安全漏洞;High—— 會在生產中引發問題;阻塞維護;Medium—— 降低可維護性;違反約定;Low—— 表面問題;順手就修;對每個發現保守估算工時(小時);寫入含全部必備章節的TECH_DEBT_AUDIT.md;向用戶匯報摘要。協議還附帶一段嚴重度基準: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 全篇,其方法論可歸納為四個可復用的設計:churn × 體量定位熱點:Phase 0 用git log與文件行數交叉引用,把有限精力投到真正的高摩擦文件;結構搜索優先于文本搜索:所有關鍵模式(導入環、god class、循環內 await、catch 塊)都走sg -p的 AST 級 pattern,配合 ast-grep-mcp 的 16 KiB pattern / 500 匹配 / 5 分鐘超時約束,掃描既精準又不會跑飛;LSP 診斷作為類型債的權威來源:維度 3 直接調用lsp_diagnostics(見 lsp-core 工具定義),讓編譯器而不是正則來判定類型錯誤;可選項漸進增強:CodeGraph 只在如果可用的前提下升級死代碼、循環依賴、影響面分析,且明確子代理不可用 CodeGraph 的邊界——協議對工具能力做了誠實的降級設計。對于 OMO 這樣的多包(monorepo)TypeScript/Bun 倉庫,該協議的全部標準命令開箱即可執行;對引入 CodeGraph 的項目,則在架構維度獲得調用圖級證據。最終產物TECH_DEBT_AUDIT.md的七章節結構本身也值得作為團隊代碼審計報告的標準模板直接使用?！久赓M下載鏈接】oh-my-openagentOmO: Drop your tokens. Ultrawork. Done.項目地址: https://gitcode.com/gh_mirrors/oh/oh-my-openagent創作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考 oh-my-openagent 技術債審計協議:九維度掃描、sg 結構搜索與 TECH_DEBT_AUDIT.md 產物生成
oh-my-openagent 技術債審計協議:九維度掃描、sg 結構搜索與 TECH_DEBT_AUDIT.md 產物生成【免費下載鏈接】oh-my-openagentOmO: Drop your tokens. Ultrawork. Done.項目地址: https://gitcode.com/gh_mirrors/oh/oh-my-openagent本文基于 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)評估、一次調用聚合入口點與相關符號的智能上下文構建,以及框架感知的路由映射。需要把codegraphMCP 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,規則源必須顯式二選一(ruleFileXORinlineRules);支持語言涵蓋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(filePathsrc-dir)這種按目錄取當前類型錯誤的用法是受 schema 支持的。審計產物:TECH_DEBT_AUDIT.md 的七個必備章節協議對輸出格式做了硬性規定,TECH_DEBT_AUDIT.md必須包含:Executive Summary—— 3–5 句:整體健康度、最差的維度、quick wins 數量;Mental Model—— 用一段話描述倉庫架構(它做什么、技術棧、模塊邊界);Findings Table—— 列為:ID、Category、File:Line、Severity(Critical/High/Medium/Low)、Effort(Hours)、Description、Recommendation;Top 5 Priorities—— 按 impact/effort 比排序;Quick Wins Checklist—— 單項 30 分鐘以內可完成;Looks Bad But Is Fine—— 解釋看著像債但屬有意為之的模式;Open Questions—— 需要維護者澄清的問題。其中第 6 章尤其體現協議的專業性:代碼庫里大量壞味道其實是刻意設計(比如 OMO 倉庫packages/下大量*-core包是為了解耦而做的共享核心抽取),審計必須區分真債與假債,而不是見到長文件就開火。Phase 0:定向(Orient)——先建立心智模型在開始掃描之前,標準流程(始終執行)共六步:glob(**/*.ts)/glob(**/*.py)等 —— 摸清語言棧;glob(**/package.json)read()—— 依賴與構建工具鏈;bash(git log --oneline -200)—— 統計 churn,找出變更最頻繁的文件;glob(**/*) 基本計算 —— 找出最大文件(300 LOC 即候選);交叉引用高 churn 大文件 技術債熱點區;在自己的工作上下文中寫下心智模型段落。第 5 步是整套協議中最有信息量的一步:高頻變更和大體量同時命中的文件,幾乎必然是架構摩擦點。以 OMO 倉庫為例,packages/omo-opencode/src下有 2700 個源文件、packages/omo-senpi/src下有 700 個源文件,若按此流程跑 Phase 0,git log的 churn 數據加文件行數交叉表就能快速定位真正需要深挖的模塊。若 CodeGraph 可用,可用兩個查詢替代靠目錄名猜模塊邊界:codegraph_explore(queryarchitecture overview and main modules)返回按文件分組的符號關系與源碼,直接作為架構心智模型。codegraph_explore(querymain 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(symbolsuspected-dead-function)查調用者——若結果為零(排除測試文件)即為死代碼;用codegraph_impact(targetmodule-or-file, directionupstream)追蹤關鍵模塊的依賴方,A 依賴 B 且 B 依賴 A 即構成環;用codegraph_explore(querymodule 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(filePathsrc-dir)—— 當前的類型錯誤。該標記什么:公共 API 和導出接口上的any類型;未標注類型的函數參數;API/IO 邊界處缺少 schema 校驗;按文件分組的 LSP 類型錯誤。維度 4:測試債(Test Debt)標準命令:glob(**/*.test.ts)—— 找出全部測試文件;bash(bun test 21 | 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 --omitdev 21 | 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(targetcore-utility-function, directionupstream),看它們被依賴多廣。一個被廣泛依賴但錯誤處理或類型安全性差的模塊是高優先級重構對象,因為改動它會波及所有上游。該標記什么:落后一個大版本的依賴;功能重復的庫;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(本可并行卻順序執行);N1 查詢模式;事件監聽器/定時器/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(symbolkey-error-handler-or-middleware)與codegraph_explore(queryhow errors propagate through key-error-handler)追蹤錯誤在調用鏈中的傳播——若在多層被捕獲后吞掉,即為發現項;用codegraph_impact(targeterror-class-or-interface, directionupstream)檢查自定義錯誤類的影響面——若改動一個錯誤類型會波及 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(categoryunspecified-low, run_in_backgroundtrue, 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(categoryunspecified-low, run_in_backgroundtrue, 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_backgroundtrue保證掃描不阻塞主線程。Phase 3:綜合與交付收集所有發現:直接工具調用、CodeGraph 查詢(如有)、子代理結果;去重 —— 同一問題被多個維度提到時合并;按嚴重度分級:Critical—— 正在導致錯誤行為、數據丟失或安全漏洞;High—— 會在生產中引發問題;阻塞維護;Medium—— 降低可維護性;違反約定;Low—— 表面問題;順手就修;對每個發現保守估算工時(小時);寫入含全部必備章節的TECH_DEBT_AUDIT.md;向用戶匯報摘要。協議還附帶一段嚴重度基準: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 全篇,其方法論可歸納為四個可復用的設計:churn × 體量定位熱點:Phase 0 用git log與文件行數交叉引用,把有限精力投到真正的高摩擦文件;結構搜索優先于文本搜索:所有關鍵模式(導入環、god class、循環內 await、catch 塊)都走sg -p的 AST 級 pattern,配合 ast-grep-mcp 的 16 KiB pattern / 500 匹配 / 5 分鐘超時約束,掃描既精準又不會跑飛;LSP 診斷作為類型債的權威來源:維度 3 直接調用lsp_diagnostics(見 lsp-core 工具定義),讓編譯器而不是正則來判定類型錯誤;可選項漸進增強:CodeGraph 只在如果可用的前提下升級死代碼、循環依賴、影響面分析,且明確子代理不可用 CodeGraph 的邊界——協議對工具能力做了誠實的降級設計。對于 OMO 這樣的多包(monorepo)TypeScript/Bun 倉庫,該協議的全部標準命令開箱即可執行;對引入 CodeGraph 的項目,則在架構維度獲得調用圖級證據。最終產物TECH_DEBT_AUDIT.md的七章節結構本身也值得作為團隊代碼審計報告的標準模板直接使用?！久赓M下載鏈接】oh-my-openagentOmO: Drop your tokens. Ultrawork. Done.項目地址: https://gitcode.com/gh_mirrors/oh/oh-my-openagent創作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考