wigolo 贡献指南本地开发环境搭建、测试与提交规范的完整实践【免费下载链接】wigoloThe go-to web for your AI coding agent — local-first search, fetch, crawl research over MCP. No API keys, no cloud, $0/query. Public beta.项目地址: https://gitcode.com/GitHub_Trending/wi/wigolowigolo 是一个面向 AI 编码代理的本地优先 Web 智能 MCP 服务器local-first web intelligence MCP server提供 search、fetch、crawl、research 等工具无 API Key、无云依赖。本文基于仓库根目录的 CONTRIBUTING.md 展开系统讲解从零开始搭建开发环境、运行构建与测试、遵循提交规范到签署贡献许可协议的完整流程并结合仓库源码说明各项约束背后的工程原因。读完本文你将掌握向 wigolo 提交高质量贡献的全部前置技能包括如何在不破坏 MCP stdio 协议的前提下编写代码、如何用 Vitest 组织测试、以及 AGPL-3.0-only 许可下贡献授权的具体含义。开发环境要求与初始化wigolo 使用 TypeScript 构建运行在 Node.js 之上。开始贡献前请确认环境满足以下条件Node.js ≥ 20这一要求同时写在 CONTRIBUTING.md 与 package.json 的engines字段中tsup的构建目标也为node20见 tsup.config.ts低于 20 的版本无法保证构建与运行行为一致。克隆仓库后在仓库根目录执行依赖安装npm install安装完成后即可开始构建与测试。仓库采用 ESM 模块体系type: module见 package.json所有src目录下的 TypeScript 源码均参与构建。构建、测试与校验命令详解CONTRIBUTING.md 给出了一组核心命令它们的实际行为可在 package.json 的scripts中找到一一对应的实现npm run build # tsc - dist/ npm test # full vitest suite npm run test:unit # unit tests only npm run lint # tsc --noEmit npm run dev # runs the CLI from source via tsx构建npm run buildbuild脚本实际执行tsup tsc -p tsconfig.build.json两步tsup 打包根据 tsup.config.ts 将src/**/*.ts与src/**/*.tsx编译为 ESM 格式输出到dist/目标为node20并生成 sourcemap 方便调试。类型检查与声明通过tsc -p tsconfig.build.json校验类型并输出.d.ts声明文件。需要注意常规开发中的 tsconfig.json 开启了noEmit: true仅用于编辑器与lint的类型检查真正的产物输出由 build 配置完成。测试npm test与npm run test:unit测试统一由 Vitest 驱动devDependencies 中包含vitest见 package.json。默认配置见 vitest.config.tsinclude覆盖tests/**/*.test.ts与tests/**/*.test.tsx即所有测试目录下的测试文件setupFiles加载 tests/setup.ts该文件为测试做了三项关键隔离将WIGOLO_DATA_DIR指向临时目录避免测试误写开发者的真实~/.wigolo数据库默认将WIGOLO_RERANKER置为none避免 reranker 模型被懒下载同时保存并清理 CI 相关环境变量防止 GitHub Actions 等宿主变量干扰 TUI 测试行为testTimeout为 20000ms覆盖较重的集成路径覆盖率使用 v8 provider统计src/**/*.ts排除入口 src/index.ts。npm run test:unit等价于vitest run tests/unit只跑单元测试适合开发阶段的快速反馈。仓库还提供了test:integration、test:e2e、test:perf以及针对 TypeScript / Python SDK 的test:sdk:ts、test:sdk:py等细分脚本可在 package.json 中查看全部选项。性能基准tests/perf/**/*.bench.ts默认被排除在常规测试之外需要空闲 CPU 时单独运行这一设计在 vitest.config.ts 的注释中有明确说明。静态检查npm run lintlint脚本即tsc --noEmit对src下全部源码做严格类型检查strict: true。它与 build 中的tsc -p tsconfig.build.json相互独立但目的一致在任何提交前确保类型系统干净。从源码直接运行npm run devdev脚本通过tsx src/index.ts直接运行 src/index.ts 中的 CLI 入口免去构建步骤适合迭代调试。入口文件main()按子命令分发到 warmup、serve、health、doctor、auth、shell、plugin、init、config、search、fetch、research 等模块并统一通过exitCli()设置退出码——注释特别说明这里刻意避免调用process.exit()而是让 Node 自然退出以免与原生 ONNX 运行时的线程池回收发生竞态见 src/index.ts。提出变更的标准流程CONTRIBUTING.md 规定了一套清晰的贡献流程要求每个步骤都尽量可审查、可回滚先开 Issue 对齐方案任何非平凡non-trivial的改动都建议先创建 Issue与维护者就实现思路达成一致避免 PR 被拒后返工。仓库的 issue 入口配置在 package.json 的bugs字段。从main切分支保持改动聚焦分支应从main拉出一个 PR 只解决一个问题新行为必须伴随测试。遵循 Conventional Commits 提交信息规范提交信息使用feat:、fix:、test:、refactor:、chore:、docs:等前缀让 changelog 自动生成与版本语义化成为可能。仓库自身的 CHANGELOG.md 即按此风格维护。提交前通过全部检查确保npm test与npm run lint均通过再打开 PR。在 PR 中说明改动与动机描述改了什么以及为什么重要帮助评审者快速理解上下文。编码规范与工程约束CONTRIBUTING.md 给出了四条硬性准则前两条是通用软件工程实践后两条则与 wigolo 的架构特性直接相关最小改动原则选择能完整解决问题的最小改动减少评审面与回归风险。匹配现有代码风格注释克制注释只写为什么而非常识性的是什么。仓库中大量源码注释正是这种风格例如 src/index.ts 中对退出策略的说明、tests/setup.ts 中对数据目录隔离动机的解释。所有日志输出到 stderrstdout 保留给 MCP stdio 协议这是本项目最关键的运行时约束。wigolo 以 MCP stdio 传输方式与 AI 代理通信wigolo mcp路径下 stdout 承载 JSON-RPC 协议帧任何非协议内容写入 stdout 都会破坏通信。源码 src/cli/mcp.ts 明确声明该路径绝不挂载 Ink TUI因为渲染 TUI 会污染 stdout。与之对应CLI 的诊断信息统一走process.stderr.write例如 src/cli/auth.ts、src/cli/backfill.ts 等而输出给外部消费者如 MCP 工具结果、JSON 状态的数据才写 stdout如 src/cli/backfill.ts。贡献者在编写任何涉及输出的代码时都必须遵守这条边界。不随意引入依赖新增依赖必须有明确需求并在 PR 中说明。仓库当前的核心依赖见 package.json覆盖 MCP SDK、搜索、抓取、提取如mozilla/readability、defuddle、turndown、嵌入fastembed、sqlite-vec、浏览器自动化playwright等能力依赖面已经较宽评估新增包时需谨慎权衡。贡献者许可协议CLACONTRIBUTING.md 规定提交 PR、补丁或其他工作即表示同意以下条款其核心目标是在保持开源发布的同时为项目保留商业化许可的灵活性贡献的许可贡献者以项目所用许可证GNU AGPL-3.0-only向项目及所有下游用户授权其贡献。这与 package.json 的license字段以及仓库根目录的 LICENSE 一致。对维护者的授权贡献者额外授予项目维护者一项永久、全球范围、非独占、免版税、不可撤销的版权与专利许可允许复制、修改、分发、再许可甚至以不同许可条款转授权例如商业许可。这使得项目可以在开源 AGPL 发布之外提供商业授权。权利的正当性保证贡献者保证所提交内容为原创或有权提交且据其所知不侵犯任何第三方权利。无担保贡献以按现状提供不附带任何形式的担保。若代表雇主贡献需确认已获得雇主授权若无法同意以上条款应先开 Issue 讨论再提交。这套 CLA 是 wigolo 采用AGPL 开源 商业授权并行模式的基础理解它有助于判断自己的贡献是否适合项目。结语wigolo 的贡献门槛并不高Node.js ≥ 20 环境、一套build / test / lint / dev脚本、明确的提交规范与 CLA 条款构成了完整的协作契约。真正需要时刻牢记的工程红线只有一条——MCP stdio 场景下 stdout 是协议通道日志必须走 stderr。无论是修复一个搜索 bug还是为 extract 管线新增提取器先读一读 src/index.ts 的命令分发、src/cli/mcp.ts 的协议入口以及 tests/setup.ts 的测试隔离策略再动手写代码会让你的首个 PR 顺利得多。【免费下载链接】wigoloThe go-to web for your AI coding agent — local-first search, fetch, crawl research over MCP. No API keys, no cloud, $0/query. Public beta.项目地址: https://gitcode.com/GitHub_Trending/wi/wigolo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考