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