Context Hub 架構(gòu)全解最小依賴 CLI、雙模輸出與 E2E 測試設(shè)計【免費(fèi)下載鏈接】context-hub項目地址: https://gitcode.com/gh_mirrors/co/context-hubContext Hubchub是一個面向 AI 編程智能體的文檔 CLI 工具它讓 Agent 能搜索并拉取經(jīng)過人工整理、帶版本號的 API 文檔與技能文件而不是靠訓(xùn)練數(shù)據(jù)猜 API。本文帶你快速看懂它的三大架構(gòu)亮點最小依賴的 CLI 設(shè)計、雙模輸出機(jī)制、以及可復(fù)現(xiàn)的 E2E 測試體系。一、整體架構(gòu)一個 CLI兩種入口Context Hub 的倉庫結(jié)構(gòu)非常清晰核心代碼全部位于cli/目錄命令層cli/src/commands/search、get、build、annotate、feedback、cache、update各自獨立注冊核心庫層cli/src/lib/注冊表合并、BM25 檢索、緩存、配置、輸出等無副作用邏輯MCP 服務(wù)層cli/src/mcp/把同樣的能力包裝成 MCP 工具內(nèi)容區(qū)content/所有文檔均為純 MarkdownYAML frontmatter DOC.md按項目/主題/語言組織package.json中聲明了兩個可執(zhí)行入口chub與chub-mcp也就是說同一個代碼庫同時提供命令行和 MCP Server 兩種接入方式Agent 既可以直接執(zhí)行命令也可以通過 MCP 協(xié)議調(diào)用工具能力完全復(fù)用。二、最小依賴設(shè)計7 個運(yùn)行時依賴撐起整個 CLI在 cli/package.json 中運(yùn)行時依賴只有 7 個依賴用途commander命令行參數(shù)解析chalk終端彩色輸出zodMCP 工具參數(shù)校驗modelcontextprotocol/sdkMCP Server 協(xié)議實現(xiàn)posthog-node匿名遙測可用CHUB_TELEMETRY0完全關(guān)閉tar解壓完整文檔包yaml解析~/.chub/config.yaml配置這種極簡依賴帶來三個好處安裝快、攻擊面小——npm 包體積可控供應(yīng)鏈風(fēng)險低充分利用 Node 18 內(nèi)置能力——cli/src/lib/cache.js 直接使用原生fetchAbortController做帶超時的網(wǎng)絡(luò)請求沒有引入任何 HTTP 庫啟動即主路徑清晰——cli/src/index.js 中用preAction鉤子統(tǒng)一處理歡迎語 → 遙測 → 注冊表就緒檢查命令失敗時會給出可操作的修復(fù)提示如chub update 對新手來說這是學(xué)習(xí)如何用最少第三方庫寫一個生產(chǎn)級 CLI的很好范例。三、雙模輸出同一條命令人讀友好 機(jī)器可解析Context Hub 的雙模輸出設(shè)計堪稱優(yōu)雅全部邏輯集中在 cli/src/lib/output.jsoutput(data, humanFormatter, opts) ├── opts.json 為真 → stdout 只輸出格式化 JSON供腳本/Agent 解析 └── 默認(rèn) → 調(diào)用 humanFormatter用 chalk 渲染人類友好的彩色文本以chub get命令為例cli/src/commands/get.js人類模式直接打印文檔 Markdown 正文末尾附上可用附加文件和反饋提示JSON 模式輸出{ id, type, content, path, additionalFiles }結(jié)構(gòu)化數(shù)據(jù)方便管道處理或程序斷言關(guān)鍵細(xì)節(jié)JSON 模式下 stdout 保證純凈——確認(rèn)類信息如已寫入文件一律走 stderr避免污染機(jī)器可讀輸出錯誤也分雙?！猠rror()在 JSON 模式輸出{error: ...}普通模式輸出Error: ...到 stderr 并以退出碼 1 結(jié)束這種單一數(shù)據(jù)源、兩種渲染的設(shè)計讓每條命令只需要寫一次格式化邏輯四、檢索與緩存BM25 打分 本地優(yōu)先的多級回退chub search的搜索能力由 cli/src/lib/bm25.js 實現(xiàn)索引在chub build時預(yù)構(gòu)建倒排索引 IDF搜索時只打分速度快四個字段加權(quán)id權(quán)重 4.0 name3.0 tags2.0 description1.0讓搜包名永遠(yuǎn)優(yōu)先于搜描述無索引時自動回退到關(guān)鍵字匹配cli/src/lib/registry.js 還會疊加前綴/包含/編輯距離的模糊救場打分緩存?zhèn)萩li/src/lib/cache.js采用本地優(yōu)先的多級回退本地源碼 → npm 包內(nèi)置dist內(nèi)容 → 遠(yuǎn)程 CDN 拉取后寫回緩存并配合meta.json時間戳實現(xiàn)refresh_interval自動過期刷新。斷網(wǎng)時依然可用這對 Agent 的穩(wěn)定運(yùn)行至關(guān)重要。五、E2E 測試設(shè)計真實進(jìn)程 隔離環(huán)境 內(nèi)置 Fixturecli/test/e2e.test.js 是理解項目測試?yán)砟畹年P(guān)鍵文件它的設(shè)計有三個亮點1. 測試真實二進(jìn)制而非內(nèi)部函數(shù)測試通過execFileSync(node, [CLI, ...args])啟動真實的 CLI 入口bin/chub覆蓋參數(shù)解析、雙模輸出、退出碼、錯誤文案等完整鏈路——這正是測試用戶實際會用的東西。2. 完全隔離絕不污染用戶環(huán)境用mkdtempSync創(chuàng)建臨時目錄并注入CHUB_DIR環(huán)境變量~/.chub全程無感設(shè)置CHUB_TELEMETRY0與CHUB_FEEDBACK0確保測試不產(chǎn)生任何網(wǎng)絡(luò)副作用測試數(shù)據(jù)完全來自內(nèi)置 Fixturecli/test/fixtures/acme/widgets多文件文檔、multilang/client多語言文檔、acme/versioned-api多版本文檔、testskills/deploy技能一套數(shù)據(jù)覆蓋全部核心場景3. 先 build 再斷言驗證完整流水線beforeAll中先執(zhí)行chub build fixtures生成registry.json隨后斷言注冊表計數(shù)3 docs 1 skill、文件拷貝、模糊搜索、--lang自動選擇、--version回退、--file增量拉取、注釋注入與清除等 40 條用例。 一句話總結(jié)測試不 mock 網(wǎng)絡(luò)、不 mock 文件系統(tǒng)只用環(huán)境變量做隔離——簡單、可信、可復(fù)現(xiàn)。六、安全細(xì)節(jié)值得抄作業(yè)的兩處防御MCP 傳輸保護(hù)cli/src/mcp/server.js 開頭把所有console.log重定向到 stderr——因為任何依賴庫的意外打印都會破壞 stdio 上的 JSON-RPC 協(xié)議注釋默認(rèn)不注入chub get只有在顯式傳--with-annotations時才會附帶本地注釋且輸出中明確標(biāo)注untrusted input防止提示注入風(fēng)險寫在最后Context Hub 用7 個運(yùn)行時依賴、一套雙模輸出、一個全隔離 E2E 套件把給 AI 喂文檔這件小事做到了架構(gòu)級嚴(yán)謹(jǐn)。如果你想動手研究建議按這個順序閱讀源碼cli/src/index.js 看命令裝配 → cli/src/lib/output.js 看輸出雙模 → cli/src/lib/bm25.js 看檢索算法 → cli/test/e2e.test.js 看測試設(shè)計。配套的 Agent 技能文件 cli/skills/get-api-docs/SKILL.md 也值得參考它是讓 Agent 學(xué)會自動查文檔的提示詞范本?！久赓M(fèi)下載鏈接】context-hub項目地址: https://gitcode.com/gh_mirrors/co/context-hub創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考