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），仅供参考