債審計(jì)協(xié)議:九維度掃描、sg 結(jié)構(gòu)搜索與 TECH_DEBT_AUDIT.md 產(chǎn)物生成)
oh-my-openagent 技術(shù)債審計(jì)協(xié)議:九維度掃描、sg 結(jié)構(gòu)搜索與 TECH_DEBT_AUDIT.md 產(chǎn)物生成【免費(fèi)下載鏈接】oh-my-openagentOmO: Drop your tokens. Ultrawork. Done.項(xiàng)目地址: https://gitcode.com/gh_mirrors/oh/oh-my-openagent本文基于 tech-debt-audit 技能協(xié)議,系統(tǒng)講解 oh-my-openagent(下稱(chēng) OMO)內(nèi)置的技術(shù)債審計(jì)流程:如何以 grep、glob、ast-grep(sg)、LSP 診斷與子代理并行任務(wù)為工具鏈,在九個(gè)大維度上對(duì)代碼庫(kù)做可引用、可驗(yàn)證的掃描,并產(chǎn)出一份帶嚴(yán)重度分級(jí)、工時(shí)估算和優(yōu)先級(jí)排序的TECH_DEBT_AUDIT.md審計(jì)產(chǎn)物。讀完本文,你可以掌握一套可復(fù)制到任意 TypeScript/Bun 單倉(cāng)的 Agent 驅(qū)動(dòng)代碼健康檢查方法論。協(xié)議定位與觸發(fā)方式該技能定義在 .agents/skills/tech-debt-audit/SKILL.md,是一個(gè)模型無(wú)關(guān)(model-agnostic)的審計(jì)協(xié)議,專(zhuān)為 OMO 這類(lèi)復(fù)雜代碼庫(kù)設(shè)計(jì)。其 frontmatter 中聲明的觸發(fā)詞包括tech debt、technical debt、debt audit、code health、codebase health check、audit code quality等——當(dāng)你向 Agent 提出幫我做代碼庫(kù)健康檢查/架構(gòu)評(píng)審/清理規(guī)劃時(shí),就會(huì)走這條協(xié)議。協(xié)議的核心原則寫(xiě)在開(kāi)篇:每一條發(fā)現(xiàn)(findings)必須引用file:line:col,不允許無(wú)證據(jù)的泛泛斷言。產(chǎn)物統(tǒng)一寫(xiě)入倉(cāng)庫(kù)根目錄的TECH_DEBT_AUDIT.md。工具鏈:標(biāo)準(zhǔn)工具 可選 CodeGraph協(xié)議使用 OMO 的內(nèi)置工具完成掃描,分為兩層:標(biāo)準(zhǔn)層(始終可用):grep、glob、bash(其中可調(diào)用sg即 ast-grep CLI)、read、lsp_diagnostics、task(并行子代理)。CodeGraph 增強(qiáng)層(可選):若項(xiàng)目中安裝了 CodeGraph(用codegraph status檢查),其 MCP 工具(codegraph_search、codegraph_callers、codegraph_callees、codegraph_impact、codegraph_explore等)可以取代或補(bǔ)充下文標(biāo)注了CodeGraph Enhancement的維度掃描。CodeGraph 提供按名符號(hào)檢索、任意函數(shù)的調(diào)用者/被調(diào)用者分析、變更前的影響面(blast radius)評(píng)估、一次調(diào)用聚合入口點(diǎn)與相關(guān)符號(hào)的智能上下文構(gòu)建,以及框架感知的路由映射。需要把codegraphMCP server 配置進(jìn)項(xiàng)目的.mcp.json或全局 MCP 配置,技能會(huì)自動(dòng)檢測(cè)其可用性。一個(gè)關(guān)鍵限制:通過(guò)task()派生的子代理不能使用 CodeGraph,它們只能走標(biāo)準(zhǔn)工具路徑——這直接影響后文 Phase 2 的分工設(shè)計(jì)。標(biāo)準(zhǔn)層工具的源碼佐證協(xié)議里的sg命令背后是 OMO 倉(cāng)庫(kù)自帶的 ast-grep-mcp 包(oh-my-opencode/ast-grep-mcp,服務(wù)名ast_grep,提供search、rewrite、scan三個(gè)工具)。從 packages/ast-grep-mcp/AGENTS.md 與 sg 進(jìn)程封裝 可以看到該工具鏈的工程約束,審計(jì)時(shí)寫(xiě)sg命令可以據(jù)此把握邊界:匹配上限maxMatches為 1–500,默認(rèn) 50;整次調(diào)用超時(shí)預(yù)算默認(rèn) 300000 ms(即 5 分鐘),也是上限;pattern 按 UTF-8 字節(jié)計(jì),上限 16 KiB;rewrite 規(guī)則上限 64 KiB;scan不允許隱式發(fā)現(xiàn)sgconfig.yml,規(guī)則源必須顯式二選一(ruleFileXORinlineRules);支持語(yǔ)言涵蓋typescript、tsx、python、go、rust、bash等 24 種(見(jiàn) mcp.ts 中的 LANGUAGES 常量),因此協(xié)議的維度掃描對(duì)多語(yǔ)言倉(cāng)庫(kù)同樣適用。協(xié)議第 3 維引用的lsp_diagnostics則對(duì)應(yīng) lsp-core 工具定義:工具名diagnostics(別名lsp_diagnostics),必傳參數(shù)filePath(文件或目錄),可選severity過(guò)濾(error/warning/information/hint/all,默認(rèn) all)——所以協(xié)議里lsp_diagnostics(filePathsrc-dir)這種按目錄取當(dāng)前類(lèi)型錯(cuò)誤的用法是受 schema 支持的。審計(jì)產(chǎn)物:TECH_DEBT_AUDIT.md 的七個(gè)必備章節(jié)協(xié)議對(duì)輸出格式做了硬性規(guī)定,TECH_DEBT_AUDIT.md必須包含:Executive Summary—— 3–5 句:整體健康度、最差的維度、quick wins 數(shù)量;Mental Model—— 用一段話描述倉(cāng)庫(kù)架構(gòu)(它做什么、技術(shù)棧、模塊邊界);Findings Table—— 列為:ID、Category、File:Line、Severity(Critical/High/Medium/Low)、Effort(Hours)、Description、Recommendation;Top 5 Priorities—— 按 impact/effort 比排序;Quick Wins Checklist—— 單項(xiàng) 30 分鐘以內(nèi)可完成;Looks Bad But Is Fine—— 解釋看著像債但屬有意為之的模式;Open Questions—— 需要維護(hù)者澄清的問(wèn)題。其中第 6 章尤其體現(xiàn)協(xié)議的專(zhuān)業(yè)性:代碼庫(kù)里大量壞味道其實(shí)是刻意設(shè)計(jì)(比如 OMO 倉(cāng)庫(kù)packages/下大量*-core包是為了解耦而做的共享核心抽取),審計(jì)必須區(qū)分真?zhèn)c假債,而不是見(jiàn)到長(zhǎng)文件就開(kāi)火。Phase 0:定向(Orient)——先建立心智模型在開(kāi)始掃描之前,標(biāo)準(zhǔn)流程(始終執(zhí)行)共六步:glob(**/*.ts)/glob(**/*.py)等 —— 摸清語(yǔ)言棧;glob(**/package.json)read()—— 依賴(lài)與構(gòu)建工具鏈;bash(git log --oneline -200)—— 統(tǒng)計(jì) churn,找出變更最頻繁的文件;glob(**/*) 基本計(jì)算 —— 找出最大文件(300 LOC 即候選);交叉引用高 churn 大文件 技術(shù)債熱點(diǎn)區(qū);在自己的工作上下文中寫(xiě)下心智模型段落。第 5 步是整套協(xié)議中最有信息量的一步:高頻變更和大體量同時(shí)命中的文件,幾乎必然是架構(gòu)摩擦點(diǎn)。以 OMO 倉(cāng)庫(kù)為例,packages/omo-opencode/src下有 2700 個(gè)源文件、packages/omo-senpi/src下有 700 個(gè)源文件,若按此流程跑 Phase 0,git log的 churn 數(shù)據(jù)加文件行數(shù)交叉表就能快速定位真正需要深挖的模塊。若 CodeGraph 可用,可用兩個(gè)查詢替代靠目錄名猜模塊邊界:codegraph_explore(queryarchitecture overview and main modules)返回按文件分組的符號(hào)關(guān)系與源碼,直接作為架構(gòu)心智模型。codegraph_explore(querymain entry points and execution flow)暴露真實(shí)入口點(diǎn)與調(diào)用鏈,讓你理解代碼實(shí)際如何流動(dòng),而不是目錄布局暗示的流動(dòng)方式。Phase 1:九大維度審計(jì)每個(gè)維度都給出標(biāo)準(zhǔn)命令(始終運(yùn)行)和該標(biāo)記什么兩部分;維度內(nèi)應(yīng)并行發(fā)起工具調(diào)用。以下逐維繼承協(xié)議原文。維度 1:架構(gòu)腐化(Architectural Decay)標(biāo)準(zhǔn)命令:bash(sg -p \import { $$$ } from $SRC\ -l ts .)—— 構(gòu)建模塊圖,尋找環(huán)狀模式;bash(sg -p \class $NAME { $$$ }\ -l ts .)—— 檢查 god class;grep(TODO|FIXME|HACK|XXX|WORKAROUND|TEMP)—— 帶標(biāo)簽的債務(wù)標(biāo)記;grep(async|await)掃在看起來(lái)是同步的文件上 —— 錯(cuò)位異步邊界;對(duì) Phase 0 找出的每個(gè)大文件執(zhí)行bash(wc -l file)。CodeGraph 增強(qiáng):對(duì) grep/glob 發(fā)現(xiàn)的疑似死代碼導(dǎo)出,用codegraph_callers(symbolsuspected-dead-function)查調(diào)用者——若結(jié)果為零(排除測(cè)試文件)即為死代碼;用codegraph_impact(targetmodule-or-file, directionupstream)追蹤關(guān)鍵模塊的依賴(lài)方,A 依賴(lài) B 且 B 依賴(lài) A 即構(gòu)成環(huán);用codegraph_explore(querymodule dependencies and architecture boundaries)普查真實(shí)模塊結(jié)構(gòu)。該標(biāo)記什么:500 LOC 的文件(god file);80 LOC 或嵌套 4 層的函數(shù);方法 15 個(gè)或 400 LOC 的類(lèi);導(dǎo)入環(huán)(A → B → A);死導(dǎo)出:定義了但從未被其他地方導(dǎo)入的函數(shù)/類(lèi)(CodeGraph 下用codegraph_callers);被注釋掉的代碼塊(連續(xù) 3 行)。維度 2:一致性腐爛(Consistency Rot)標(biāo)準(zhǔn)命令:bash(sg -p \import $CLIENT from $PKG\ -l ts .)—— 多個(gè) HTTP 客戶端并存;grep(console.log|console.error|console.warn)—— 直接 console vs 統(tǒng)一 logger;bash(sg -p \try { $$$ } catch ($$$) { $$$ }\ -l ts .)—— 錯(cuò)誤處理模式普查;grep(as any|ts-ignore|ts-expect-error|as unknown)—— 類(lèi)型逃逸;grep(eslint-disable|prettier-ignore)—— lint 壓制。該標(biāo)記什么:同一件事有 3 種以上做法(HTTP、日志、校驗(yàn)、配置);混合命名規(guī)范(camelCase snake_case PascalCase);多個(gè)日期時(shí)間庫(kù)并存;跨模塊錯(cuò)誤響應(yīng)形狀不一致。維度 3:類(lèi)型與契約債(Type Contract Debt)標(biāo)準(zhǔn)命令:bash(sg -p \$VALUE as any\ -l ts .)—— 運(yùn)行時(shí)類(lèi)型逃逸;grep(ts-expect-error)—— 被壓制的錯(cuò)誤;grep(ts-ignore)—— 被壓制的錯(cuò)誤(legacy);bash(sg -p \$NAME: any\ -l ts .)—— 聲明為 any 的位置;lsp_diagnostics(filePathsrc-dir)—— 當(dāng)前的類(lèi)型錯(cuò)誤。該標(biāo)記什么:公共 API 和導(dǎo)出接口上的any類(lèi)型;未標(biāo)注類(lèi)型的函數(shù)參數(shù);API/IO 邊界處缺少 schema 校驗(yàn);按文件分組的 LSP 類(lèi)型錯(cuò)誤。維度 4:測(cè)試債(Test Debt)標(biāo)準(zhǔn)命令:glob(**/*.test.ts)—— 找出全部測(cè)試文件;bash(bun test 21 | grep -E (fail|skip|todo))—— 當(dāng)前測(cè)試健康度;將 Phase 0 的高 churn 文件與測(cè)試存在性交叉比對(duì)。該標(biāo)記什么:關(guān)鍵路徑文件零測(cè)試;被跳過(guò)的測(cè)試(test.skip、describe.skip);斷言實(shí)現(xiàn)細(xì)節(jié)而非行為的測(cè)試;慢測(cè)試(單條 1s)。這條命令與 OMO 實(shí)際測(cè)試棧一致——倉(cāng)庫(kù)根 package.json 基于 Bun,大量*.test.ts以bun test運(yùn)行,審計(jì)時(shí)可直接復(fù)用。維度 5:依賴(lài)與配置債(Dependency Config Debt)標(biāo)準(zhǔn)命令:bash(npm audit --omitdev 21 | head -40)—— 已知 CVE(前提是 node_modules 存在);read(package.json)—— 依賴(lài)數(shù)量與陳舊依賴(lài);grep(.env|process.env|Bun.env)—— 環(huán)境變量使用;在非配置文件里grep(API_KEY|SECRET|PASSWORD|TOKEN)—— 硬編碼配置。CodeGraph 增強(qiáng):對(duì)少數(shù)關(guān)鍵內(nèi)部模塊(logger、config loader、HTTP client)執(zhí)行codegraph_impact(targetcore-utility-function, directionupstream),看它們被依賴(lài)多廣。一個(gè)被廣泛依賴(lài)但錯(cuò)誤處理或類(lèi)型安全性差的模塊是高優(yōu)先級(jí)重構(gòu)對(duì)象,因?yàn)楦膭?dòng)它會(huì)波及所有上游。該標(biāo)記什么:落后一個(gè)大版本的依賴(lài);功能重復(fù)的庫(kù);README 未文檔化的環(huán)境變量;硬編碼的環(huán)境特定值。維度 6:性能與資源衛(wèi)生(Performance Resource Hygiene)標(biāo)準(zhǔn)命令:bash(sg -p \for ($$$ of $$$) { $$$ await $$$ }\ -l ts .)—— 循環(huán)內(nèi) await;grep(await.*map|await.*filter|await.*forEach)—— 順序異步迭代;grep(Promise\\.all|Promise\\.allSettled)—— 已有的并行模式(正面信號(hào));grep(addEventListener|on\\(|subscribe)附近沒(méi)有removeEventListener|off\\(|unsubscribe—— 監(jiān)聽(tīng)器衛(wèi)生。該標(biāo)記什么:for/of循環(huán)內(nèi)的await(本可并行卻順序執(zhí)行);N1 查詢模式;事件監(jiān)聽(tīng)器/定時(shí)器/handle 缺少清理;不必要的序列化/反序列化。維度 7:錯(cuò)誤處理與可觀測(cè)性(Error Handling Observability)標(biāo)準(zhǔn)命令:bash(sg -p \catch ($$$) { $$$ }\ -l ts .)—— catch 塊普查;grep(catch.*{}|catch.*{\\s*})—— 空 catch 塊;grep(console.error|logger\\.error|log\\.error)—— 真實(shí)的錯(cuò)誤日志;bash(sg -p \throw new $ERR($$$)\ -l ts .)—— 使用了哪些錯(cuò)誤類(lèi)型。CodeGraph 增強(qiáng):用codegraph_callers(symbolkey-error-handler-or-middleware)與codegraph_explore(queryhow errors propagate through key-error-handler)追蹤錯(cuò)誤在調(diào)用鏈中的傳播——若在多層被捕獲后吞掉,即為發(fā)現(xiàn)項(xiàng);用codegraph_impact(targeterror-class-or-interface, directionupstream)檢查自定義錯(cuò)誤類(lèi)的影響面——若改動(dòng)一個(gè)錯(cuò)誤類(lèi)型會(huì)波及 20 消費(fèi)方,說(shuō)明該錯(cuò)誤契約過(guò)緊。該標(biāo)記什么:空 catch 塊(最?lèi)毫?;無(wú)恢復(fù)邏輯的泛型catch (e) { console.error(e) };跨模塊不一致的錯(cuò)誤形狀;關(guān)鍵路徑缺少結(jié)構(gòu)化日志;promise 鏈中吞錯(cuò)(.catch(() {}))。維度 8:安全衛(wèi)生(Security Hygiene)標(biāo)準(zhǔn)命令(均在源碼文件而非配置/env 文件中執(zhí)行):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)—— 代碼注入。該標(biāo)記什么:源碼中硬編碼的密鑰;字符串拼接 SQL;innerHTML/dangerouslySetInnerHTML;eval()或基于字符串的setTimeout/setInterval;寬松的 CORS 或認(rèn)證中間件。維度 9:文檔漂移(Documentation Drift)標(biāo)準(zhǔn)命令:read(README.md)—— 檢查宣稱(chēng)是否與實(shí)現(xiàn)相符;grep(param|returns|throws)—— docstring 覆蓋度;grep(FIXME|TODO|HACK|XXX|WORKAROUND)—— fixme 密度;將 README 中的 API 示例與真實(shí)函數(shù)簽名比對(duì)。該標(biāo)記什么:README 宣稱(chēng)了不存在的功能;公共函數(shù)沒(méi)有任何文檔注釋;與代碼矛盾的注釋;過(guò)期的架構(gòu)決策記錄(ADR)。Phase 2:并行子代理深挖(50k LOC 倉(cāng)庫(kù))對(duì)大型代碼庫(kù),協(xié)議建議把最重的維度委派給并行子代理。模板如下: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.)要點(diǎn):對(duì)最重的維度派 2–3 個(gè)子代理,并行收集結(jié)果再綜合;主代理自己處理 CodeGraph 查詢,因?yàn)樽哟頍o(wú)法使用 CodeGraph,只能走標(biāo)準(zhǔn)工具路徑。task()的參數(shù)形態(tài)(category、run_in_background、load_skills、prompt)與 OMO 的代理編排能力對(duì)應(yīng),run_in_backgroundtrue保證掃描不阻塞主線程。Phase 3:綜合與交付收集所有發(fā)現(xiàn):直接工具調(diào)用、CodeGraph 查詢(如有)、子代理結(jié)果;去重 —— 同一問(wèn)題被多個(gè)維度提到時(shí)合并;按嚴(yán)重度分級(jí):Critical—— 正在導(dǎo)致錯(cuò)誤行為、數(shù)據(jù)丟失或安全漏洞;High—— 會(huì)在生產(chǎn)中引發(fā)問(wèn)題;阻塞維護(hù);Medium—— 降低可維護(hù)性;違反約定;Low—— 表面問(wèn)題;順手就修;對(duì)每個(gè)發(fā)現(xiàn)保守估算工時(shí)(小時(shí));寫(xiě)入含全部必備章節(jié)的TECH_DEBT_AUDIT.md;向用戶匯報(bào)摘要。協(xié)議還附帶一段嚴(yán)重度基準(zhǔn):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收尾前的快速自檢清單協(xié)議以五條自查項(xiàng)收尾,這是保證產(chǎn)物質(zhì)量可驗(yàn)證的關(guān)鍵:每條具體發(fā)現(xiàn)都有file:line:col引用;沒(méi)有無(wú)證據(jù)的泛泛斷言;Looks Bad But Is Fine 章節(jié)解釋了至少 2–3 個(gè)模式;Top 5 優(yōu)先級(jí)按 impact/effort 排序;Quick wins 均為單項(xiàng) 30 分鐘可完成。小結(jié):這套協(xié)議的可復(fù)用要點(diǎn)回看 SKILL.md 全篇,其方法論可歸納為四個(gè)可復(fù)用的設(shè)計(jì):churn × 體量定位熱點(diǎn):Phase 0 用git log與文件行數(shù)交叉引用,把有限精力投到真正的高摩擦文件;結(jié)構(gòu)搜索優(yōu)先于文本搜索:所有關(guān)鍵模式(導(dǎo)入環(huán)、god class、循環(huán)內(nèi) await、catch 塊)都走sg -p的 AST 級(jí) pattern,配合 ast-grep-mcp 的 16 KiB pattern / 500 匹配 / 5 分鐘超時(shí)約束,掃描既精準(zhǔn)又不會(huì)跑飛;LSP 診斷作為類(lèi)型債的權(quán)威來(lái)源:維度 3 直接調(diào)用lsp_diagnostics(見(jiàn) lsp-core 工具定義),讓編譯器而不是正則來(lái)判定類(lèi)型錯(cuò)誤;可選項(xiàng)漸進(jìn)增強(qiáng):CodeGraph 只在如果可用的前提下升級(jí)死代碼、循環(huán)依賴(lài)、影響面分析,且明確子代理不可用 CodeGraph 的邊界——協(xié)議對(duì)工具能力做了誠(chéng)實(shí)的降級(jí)設(shè)計(jì)。對(duì)于 OMO 這樣的多包(monorepo)TypeScript/Bun 倉(cāng)庫(kù),該協(xié)議的全部標(biāo)準(zhǔn)命令開(kāi)箱即可執(zhí)行;對(duì)引入 CodeGraph 的項(xiàng)目,則在架構(gòu)維度獲得調(diào)用圖級(jí)證據(jù)。最終產(chǎn)物TECH_DEBT_AUDIT.md的七章節(jié)結(jié)構(gòu)本身也值得作為團(tuán)隊(duì)代碼審計(jì)報(bào)告的標(biāo)準(zhǔn)模板直接使用。【免費(fèi)下載鏈接】oh-my-openagentOmO: Drop your tokens. Ultrawork. Done.項(xiàng)目地址: https://gitcode.com/gh_mirrors/oh/oh-my-openagent創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 oh-my-openagent 技術(shù)債審計(jì)協(xié)議:九維度掃描、sg 結(jié)構(gòu)搜索與 TECH_DEBT_AUDIT.md 產(chǎn)物生成
oh-my-openagent 技術(shù)債審計(jì)協(xié)議:九維度掃描、sg 結(jié)構(gòu)搜索與 TECH_DEBT_AUDIT.md 產(chǎn)物生成【免費(fèi)下載鏈接】oh-my-openagentOmO: Drop your tokens. Ultrawork. Done.項(xiàng)目地址: https://gitcode.com/gh_mirrors/oh/oh-my-openagent本文基于 tech-debt-audit 技能協(xié)議,系統(tǒng)講解 oh-my-openagent(下稱(chēng) OMO)內(nèi)置的技術(shù)債審計(jì)流程:如何以 grep、glob、ast-grep(sg)、LSP 診斷與子代理并行任務(wù)為工具鏈,在九個(gè)大維度上對(duì)代碼庫(kù)做可引用、可驗(yàn)證的掃描,并產(chǎn)出一份帶嚴(yán)重度分級(jí)、工時(shí)估算和優(yōu)先級(jí)排序的TECH_DEBT_AUDIT.md審計(jì)產(chǎn)物。讀完本文,你可以掌握一套可復(fù)制到任意 TypeScript/Bun 單倉(cāng)的 Agent 驅(qū)動(dòng)代碼健康檢查方法論。協(xié)議定位與觸發(fā)方式該技能定義在 .agents/skills/tech-debt-audit/SKILL.md,是一個(gè)模型無(wú)關(guān)(model-agnostic)的審計(jì)協(xié)議,專(zhuān)為 OMO 這類(lèi)復(fù)雜代碼庫(kù)設(shè)計(jì)。其 frontmatter 中聲明的觸發(fā)詞包括tech debt、technical debt、debt audit、code health、codebase health check、audit code quality等——當(dāng)你向 Agent 提出幫我做代碼庫(kù)健康檢查/架構(gòu)評(píng)審/清理規(guī)劃時(shí),就會(huì)走這條協(xié)議。協(xié)議的核心原則寫(xiě)在開(kāi)篇:每一條發(fā)現(xiàn)(findings)必須引用file:line:col,不允許無(wú)證據(jù)的泛泛斷言。產(chǎn)物統(tǒng)一寫(xiě)入倉(cāng)庫(kù)根目錄的TECH_DEBT_AUDIT.md。工具鏈:標(biāo)準(zhǔn)工具 可選 CodeGraph協(xié)議使用 OMO 的內(nèi)置工具完成掃描,分為兩層:標(biāo)準(zhǔn)層(始終可用):grep、glob、bash(其中可調(diào)用sg即 ast-grep CLI)、read、lsp_diagnostics、task(并行子代理)。CodeGraph 增強(qiáng)層(可選):若項(xiàng)目中安裝了 CodeGraph(用codegraph status檢查),其 MCP 工具(codegraph_search、codegraph_callers、codegraph_callees、codegraph_impact、codegraph_explore等)可以取代或補(bǔ)充下文標(biāo)注了CodeGraph Enhancement的維度掃描。CodeGraph 提供按名符號(hào)檢索、任意函數(shù)的調(diào)用者/被調(diào)用者分析、變更前的影響面(blast radius)評(píng)估、一次調(diào)用聚合入口點(diǎn)與相關(guān)符號(hào)的智能上下文構(gòu)建,以及框架感知的路由映射。需要把codegraphMCP server 配置進(jìn)項(xiàng)目的.mcp.json或全局 MCP 配置,技能會(huì)自動(dòng)檢測(cè)其可用性。一個(gè)關(guān)鍵限制:通過(guò)task()派生的子代理不能使用 CodeGraph,它們只能走標(biāo)準(zhǔn)工具路徑——這直接影響后文 Phase 2 的分工設(shè)計(jì)。標(biāo)準(zhǔn)層工具的源碼佐證協(xié)議里的sg命令背后是 OMO 倉(cāng)庫(kù)自帶的 ast-grep-mcp 包(oh-my-opencode/ast-grep-mcp,服務(wù)名ast_grep,提供search、rewrite、scan三個(gè)工具)。從 packages/ast-grep-mcp/AGENTS.md 與 sg 進(jìn)程封裝 可以看到該工具鏈的工程約束,審計(jì)時(shí)寫(xiě)sg命令可以據(jù)此把握邊界:匹配上限maxMatches為 1–500,默認(rèn) 50;整次調(diào)用超時(shí)預(yù)算默認(rèn) 300000 ms(即 5 分鐘),也是上限;pattern 按 UTF-8 字節(jié)計(jì),上限 16 KiB;rewrite 規(guī)則上限 64 KiB;scan不允許隱式發(fā)現(xiàn)sgconfig.yml,規(guī)則源必須顯式二選一(ruleFileXORinlineRules);支持語(yǔ)言涵蓋typescript、tsx、python、go、rust、bash等 24 種(見(jiàn) mcp.ts 中的 LANGUAGES 常量),因此協(xié)議的維度掃描對(duì)多語(yǔ)言倉(cāng)庫(kù)同樣適用。協(xié)議第 3 維引用的lsp_diagnostics則對(duì)應(yīng) lsp-core 工具定義:工具名diagnostics(別名lsp_diagnostics),必傳參數(shù)filePath(文件或目錄),可選severity過(guò)濾(error/warning/information/hint/all,默認(rèn) all)——所以協(xié)議里lsp_diagnostics(filePathsrc-dir)這種按目錄取當(dāng)前類(lèi)型錯(cuò)誤的用法是受 schema 支持的。審計(jì)產(chǎn)物:TECH_DEBT_AUDIT.md 的七個(gè)必備章節(jié)協(xié)議對(duì)輸出格式做了硬性規(guī)定,TECH_DEBT_AUDIT.md必須包含:Executive Summary—— 3–5 句:整體健康度、最差的維度、quick wins 數(shù)量;Mental Model—— 用一段話描述倉(cāng)庫(kù)架構(gòu)(它做什么、技術(shù)棧、模塊邊界);Findings Table—— 列為:ID、Category、File:Line、Severity(Critical/High/Medium/Low)、Effort(Hours)、Description、Recommendation;Top 5 Priorities—— 按 impact/effort 比排序;Quick Wins Checklist—— 單項(xiàng) 30 分鐘以內(nèi)可完成;Looks Bad But Is Fine—— 解釋看著像債但屬有意為之的模式;Open Questions—— 需要維護(hù)者澄清的問(wèn)題。其中第 6 章尤其體現(xiàn)協(xié)議的專(zhuān)業(yè)性:代碼庫(kù)里大量壞味道其實(shí)是刻意設(shè)計(jì)(比如 OMO 倉(cāng)庫(kù)packages/下大量*-core包是為了解耦而做的共享核心抽取),審計(jì)必須區(qū)分真?zhèn)c假債,而不是見(jiàn)到長(zhǎng)文件就開(kāi)火。Phase 0:定向(Orient)——先建立心智模型在開(kāi)始掃描之前,標(biāo)準(zhǔn)流程(始終執(zhí)行)共六步:glob(**/*.ts)/glob(**/*.py)等 —— 摸清語(yǔ)言棧;glob(**/package.json)read()—— 依賴(lài)與構(gòu)建工具鏈;bash(git log --oneline -200)—— 統(tǒng)計(jì) churn,找出變更最頻繁的文件;glob(**/*) 基本計(jì)算 —— 找出最大文件(300 LOC 即候選);交叉引用高 churn 大文件 技術(shù)債熱點(diǎn)區(qū);在自己的工作上下文中寫(xiě)下心智模型段落。第 5 步是整套協(xié)議中最有信息量的一步:高頻變更和大體量同時(shí)命中的文件,幾乎必然是架構(gòu)摩擦點(diǎn)。以 OMO 倉(cāng)庫(kù)為例,packages/omo-opencode/src下有 2700 個(gè)源文件、packages/omo-senpi/src下有 700 個(gè)源文件,若按此流程跑 Phase 0,git log的 churn 數(shù)據(jù)加文件行數(shù)交叉表就能快速定位真正需要深挖的模塊。若 CodeGraph 可用,可用兩個(gè)查詢替代靠目錄名猜模塊邊界:codegraph_explore(queryarchitecture overview and main modules)返回按文件分組的符號(hào)關(guān)系與源碼,直接作為架構(gòu)心智模型。codegraph_explore(querymain entry points and execution flow)暴露真實(shí)入口點(diǎn)與調(diào)用鏈,讓你理解代碼實(shí)際如何流動(dòng),而不是目錄布局暗示的流動(dòng)方式。Phase 1:九大維度審計(jì)每個(gè)維度都給出標(biāo)準(zhǔn)命令(始終運(yùn)行)和該標(biāo)記什么兩部分;維度內(nèi)應(yīng)并行發(fā)起工具調(diào)用。以下逐維繼承協(xié)議原文。維度 1:架構(gòu)腐化(Architectural Decay)標(biāo)準(zhǔn)命令:bash(sg -p \import { $$$ } from $SRC\ -l ts .)—— 構(gòu)建模塊圖,尋找環(huán)狀模式;bash(sg -p \class $NAME { $$$ }\ -l ts .)—— 檢查 god class;grep(TODO|FIXME|HACK|XXX|WORKAROUND|TEMP)—— 帶標(biāo)簽的債務(wù)標(biāo)記;grep(async|await)掃在看起來(lái)是同步的文件上 —— 錯(cuò)位異步邊界;對(duì) Phase 0 找出的每個(gè)大文件執(zhí)行bash(wc -l file)。CodeGraph 增強(qiáng):對(duì) grep/glob 發(fā)現(xiàn)的疑似死代碼導(dǎo)出,用codegraph_callers(symbolsuspected-dead-function)查調(diào)用者——若結(jié)果為零(排除測(cè)試文件)即為死代碼;用codegraph_impact(targetmodule-or-file, directionupstream)追蹤關(guān)鍵模塊的依賴(lài)方,A 依賴(lài) B 且 B 依賴(lài) A 即構(gòu)成環(huán);用codegraph_explore(querymodule dependencies and architecture boundaries)普查真實(shí)模塊結(jié)構(gòu)。該標(biāo)記什么:500 LOC 的文件(god file);80 LOC 或嵌套 4 層的函數(shù);方法 15 個(gè)或 400 LOC 的類(lèi);導(dǎo)入環(huán)(A → B → A);死導(dǎo)出:定義了但從未被其他地方導(dǎo)入的函數(shù)/類(lèi)(CodeGraph 下用codegraph_callers);被注釋掉的代碼塊(連續(xù) 3 行)。維度 2:一致性腐爛(Consistency Rot)標(biāo)準(zhǔn)命令:bash(sg -p \import $CLIENT from $PKG\ -l ts .)—— 多個(gè) HTTP 客戶端并存;grep(console.log|console.error|console.warn)—— 直接 console vs 統(tǒng)一 logger;bash(sg -p \try { $$$ } catch ($$$) { $$$ }\ -l ts .)—— 錯(cuò)誤處理模式普查;grep(as any|ts-ignore|ts-expect-error|as unknown)—— 類(lèi)型逃逸;grep(eslint-disable|prettier-ignore)—— lint 壓制。該標(biāo)記什么:同一件事有 3 種以上做法(HTTP、日志、校驗(yàn)、配置);混合命名規(guī)范(camelCase snake_case PascalCase);多個(gè)日期時(shí)間庫(kù)并存;跨模塊錯(cuò)誤響應(yīng)形狀不一致。維度 3:類(lèi)型與契約債(Type Contract Debt)標(biāo)準(zhǔn)命令:bash(sg -p \$VALUE as any\ -l ts .)—— 運(yùn)行時(shí)類(lèi)型逃逸;grep(ts-expect-error)—— 被壓制的錯(cuò)誤;grep(ts-ignore)—— 被壓制的錯(cuò)誤(legacy);bash(sg -p \$NAME: any\ -l ts .)—— 聲明為 any 的位置;lsp_diagnostics(filePathsrc-dir)—— 當(dāng)前的類(lèi)型錯(cuò)誤。該標(biāo)記什么:公共 API 和導(dǎo)出接口上的any類(lèi)型;未標(biāo)注類(lèi)型的函數(shù)參數(shù);API/IO 邊界處缺少 schema 校驗(yàn);按文件分組的 LSP 類(lèi)型錯(cuò)誤。維度 4:測(cè)試債(Test Debt)標(biāo)準(zhǔn)命令:glob(**/*.test.ts)—— 找出全部測(cè)試文件;bash(bun test 21 | grep -E (fail|skip|todo))—— 當(dāng)前測(cè)試健康度;將 Phase 0 的高 churn 文件與測(cè)試存在性交叉比對(duì)。該標(biāo)記什么:關(guān)鍵路徑文件零測(cè)試;被跳過(guò)的測(cè)試(test.skip、describe.skip);斷言實(shí)現(xiàn)細(xì)節(jié)而非行為的測(cè)試;慢測(cè)試(單條 1s)。這條命令與 OMO 實(shí)際測(cè)試棧一致——倉(cāng)庫(kù)根 package.json 基于 Bun,大量*.test.ts以bun test運(yùn)行,審計(jì)時(shí)可直接復(fù)用。維度 5:依賴(lài)與配置債(Dependency Config Debt)標(biāo)準(zhǔn)命令:bash(npm audit --omitdev 21 | head -40)—— 已知 CVE(前提是 node_modules 存在);read(package.json)—— 依賴(lài)數(shù)量與陳舊依賴(lài);grep(.env|process.env|Bun.env)—— 環(huán)境變量使用;在非配置文件里grep(API_KEY|SECRET|PASSWORD|TOKEN)—— 硬編碼配置。CodeGraph 增強(qiáng):對(duì)少數(shù)關(guān)鍵內(nèi)部模塊(logger、config loader、HTTP client)執(zhí)行codegraph_impact(targetcore-utility-function, directionupstream),看它們被依賴(lài)多廣。一個(gè)被廣泛依賴(lài)但錯(cuò)誤處理或類(lèi)型安全性差的模塊是高優(yōu)先級(jí)重構(gòu)對(duì)象,因?yàn)楦膭?dòng)它會(huì)波及所有上游。該標(biāo)記什么:落后一個(gè)大版本的依賴(lài);功能重復(fù)的庫(kù);README 未文檔化的環(huán)境變量;硬編碼的環(huán)境特定值。維度 6:性能與資源衛(wèi)生(Performance Resource Hygiene)標(biāo)準(zhǔn)命令:bash(sg -p \for ($$$ of $$$) { $$$ await $$$ }\ -l ts .)—— 循環(huán)內(nèi) await;grep(await.*map|await.*filter|await.*forEach)—— 順序異步迭代;grep(Promise\\.all|Promise\\.allSettled)—— 已有的并行模式(正面信號(hào));grep(addEventListener|on\\(|subscribe)附近沒(méi)有removeEventListener|off\\(|unsubscribe—— 監(jiān)聽(tīng)器衛(wèi)生。該標(biāo)記什么:for/of循環(huán)內(nèi)的await(本可并行卻順序執(zhí)行);N1 查詢模式;事件監(jiān)聽(tīng)器/定時(shí)器/handle 缺少清理;不必要的序列化/反序列化。維度 7:錯(cuò)誤處理與可觀測(cè)性(Error Handling Observability)標(biāo)準(zhǔn)命令:bash(sg -p \catch ($$$) { $$$ }\ -l ts .)—— catch 塊普查;grep(catch.*{}|catch.*{\\s*})—— 空 catch 塊;grep(console.error|logger\\.error|log\\.error)—— 真實(shí)的錯(cuò)誤日志;bash(sg -p \throw new $ERR($$$)\ -l ts .)—— 使用了哪些錯(cuò)誤類(lèi)型。CodeGraph 增強(qiáng):用codegraph_callers(symbolkey-error-handler-or-middleware)與codegraph_explore(queryhow errors propagate through key-error-handler)追蹤錯(cuò)誤在調(diào)用鏈中的傳播——若在多層被捕獲后吞掉,即為發(fā)現(xiàn)項(xiàng);用codegraph_impact(targeterror-class-or-interface, directionupstream)檢查自定義錯(cuò)誤類(lèi)的影響面——若改動(dòng)一個(gè)錯(cuò)誤類(lèi)型會(huì)波及 20 消費(fèi)方,說(shuō)明該錯(cuò)誤契約過(guò)緊。該標(biāo)記什么:空 catch 塊(最?lèi)毫?;無(wú)恢復(fù)邏輯的泛型catch (e) { console.error(e) };跨模塊不一致的錯(cuò)誤形狀;關(guān)鍵路徑缺少結(jié)構(gòu)化日志;promise 鏈中吞錯(cuò)(.catch(() {}))。維度 8:安全衛(wèi)生(Security Hygiene)標(biāo)準(zhǔn)命令(均在源碼文件而非配置/env 文件中執(zhí)行):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)—— 代碼注入。該標(biāo)記什么:源碼中硬編碼的密鑰;字符串拼接 SQL;innerHTML/dangerouslySetInnerHTML;eval()或基于字符串的setTimeout/setInterval;寬松的 CORS 或認(rèn)證中間件。維度 9:文檔漂移(Documentation Drift)標(biāo)準(zhǔn)命令:read(README.md)—— 檢查宣稱(chēng)是否與實(shí)現(xiàn)相符;grep(param|returns|throws)—— docstring 覆蓋度;grep(FIXME|TODO|HACK|XXX|WORKAROUND)—— fixme 密度;將 README 中的 API 示例與真實(shí)函數(shù)簽名比對(duì)。該標(biāo)記什么:README 宣稱(chēng)了不存在的功能;公共函數(shù)沒(méi)有任何文檔注釋;與代碼矛盾的注釋;過(guò)期的架構(gòu)決策記錄(ADR)。Phase 2:并行子代理深挖(50k LOC 倉(cāng)庫(kù))對(duì)大型代碼庫(kù),協(xié)議建議把最重的維度委派給并行子代理。模板如下: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.)要點(diǎn):對(duì)最重的維度派 2–3 個(gè)子代理,并行收集結(jié)果再綜合;主代理自己處理 CodeGraph 查詢,因?yàn)樽哟頍o(wú)法使用 CodeGraph,只能走標(biāo)準(zhǔn)工具路徑。task()的參數(shù)形態(tài)(category、run_in_background、load_skills、prompt)與 OMO 的代理編排能力對(duì)應(yīng),run_in_backgroundtrue保證掃描不阻塞主線程。Phase 3:綜合與交付收集所有發(fā)現(xiàn):直接工具調(diào)用、CodeGraph 查詢(如有)、子代理結(jié)果;去重 —— 同一問(wèn)題被多個(gè)維度提到時(shí)合并;按嚴(yán)重度分級(jí):Critical—— 正在導(dǎo)致錯(cuò)誤行為、數(shù)據(jù)丟失或安全漏洞;High—— 會(huì)在生產(chǎn)中引發(fā)問(wèn)題;阻塞維護(hù);Medium—— 降低可維護(hù)性;違反約定;Low—— 表面問(wèn)題;順手就修;對(duì)每個(gè)發(fā)現(xiàn)保守估算工時(shí)(小時(shí));寫(xiě)入含全部必備章節(jié)的TECH_DEBT_AUDIT.md;向用戶匯報(bào)摘要。協(xié)議還附帶一段嚴(yán)重度基準(zhǔn):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收尾前的快速自檢清單協(xié)議以五條自查項(xiàng)收尾,這是保證產(chǎn)物質(zhì)量可驗(yàn)證的關(guān)鍵:每條具體發(fā)現(xiàn)都有file:line:col引用;沒(méi)有無(wú)證據(jù)的泛泛斷言;Looks Bad But Is Fine 章節(jié)解釋了至少 2–3 個(gè)模式;Top 5 優(yōu)先級(jí)按 impact/effort 排序;Quick wins 均為單項(xiàng) 30 分鐘可完成。小結(jié):這套協(xié)議的可復(fù)用要點(diǎn)回看 SKILL.md 全篇,其方法論可歸納為四個(gè)可復(fù)用的設(shè)計(jì):churn × 體量定位熱點(diǎn):Phase 0 用git log與文件行數(shù)交叉引用,把有限精力投到真正的高摩擦文件;結(jié)構(gòu)搜索優(yōu)先于文本搜索:所有關(guān)鍵模式(導(dǎo)入環(huán)、god class、循環(huán)內(nèi) await、catch 塊)都走sg -p的 AST 級(jí) pattern,配合 ast-grep-mcp 的 16 KiB pattern / 500 匹配 / 5 分鐘超時(shí)約束,掃描既精準(zhǔn)又不會(huì)跑飛;LSP 診斷作為類(lèi)型債的權(quán)威來(lái)源:維度 3 直接調(diào)用lsp_diagnostics(見(jiàn) lsp-core 工具定義),讓編譯器而不是正則來(lái)判定類(lèi)型錯(cuò)誤;可選項(xiàng)漸進(jìn)增強(qiáng):CodeGraph 只在如果可用的前提下升級(jí)死代碼、循環(huán)依賴(lài)、影響面分析,且明確子代理不可用 CodeGraph 的邊界——協(xié)議對(duì)工具能力做了誠(chéng)實(shí)的降級(jí)設(shè)計(jì)。對(duì)于 OMO 這樣的多包(monorepo)TypeScript/Bun 倉(cāng)庫(kù),該協(xié)議的全部標(biāo)準(zhǔn)命令開(kāi)箱即可執(zhí)行;對(duì)引入 CodeGraph 的項(xiàng)目,則在架構(gòu)維度獲得調(diào)用圖級(jí)證據(jù)。最終產(chǎn)物TECH_DEBT_AUDIT.md的七章節(jié)結(jié)構(gòu)本身也值得作為團(tuán)隊(duì)代碼審計(jì)報(bào)告的標(biāo)準(zhǔn)模板直接使用。【免費(fèi)下載鏈接】oh-my-openagentOmO: Drop your tokens. Ultrawork. Done.項(xiàng)目地址: https://gitcode.com/gh_mirrors/oh/oh-my-openagent創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考