企业官网建设流程全解析

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/wigolo

wigolo 是一个面向 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 build

build脚本实际执行tsup && tsc -p tsconfig.build.json两步：

1. tsup 打包：根据 tsup.config.ts 将src/**/*.ts与src/**/*.tsx编译为 ESM 格式输出到dist/，目标为node20，并生成 sourcemap 方便调试。
2. 类型检查与声明：通过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.ts：

• include覆盖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 lint

lint脚本即tsc --noEmit，对src下全部源码做严格类型检查（strict: true）。它与 build 中的tsc -p tsconfig.build.json相互独立但目的一致：在任何提交前确保类型系统干净。

从源码直接运行：npm run dev

dev脚本通过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 规定了一套清晰的贡献流程，要求每个步骤都尽量可审查、可回滚：

1. 先开 Issue 对齐方案：任何非平凡（non-trivial）的改动都建议先创建 Issue，与维护者就实现思路达成一致，避免 PR 被拒后返工。仓库的 issue 入口配置在 package.json 的bugs字段。
2. 从main切分支，保持改动聚焦：分支应从main拉出，一个 PR 只解决一个问题，新行为必须伴随测试。
3. 遵循 Conventional Commits 提交信息规范：提交信息使用feat:、fix:、test:、refactor:、chore:、docs:等前缀，让 changelog 自动生成与版本语义化成为可能。仓库自身的 CHANGELOG.md 即按此风格维护。
4. 提交前通过全部检查：确保npm test与npm run lint均通过再打开 PR。
5. 在 PR 中说明改动与动机：描述"改了什么"以及"为什么重要"，帮助评审者快速理解上下文。

编码规范与工程约束

CONTRIBUTING.md 给出了四条硬性准则，前两条是通用软件工程实践，后两条则与 wigolo 的架构特性直接相关：

• 最小改动原则：选择能完整解决问题的最小改动，减少评审面与回归风险。
• 匹配现有代码风格，注释克制：注释只写"为什么"而非常识性的"是什么"。仓库中大量源码注释正是这种风格，例如 src/index.ts 中对退出策略的说明、tests/setup.ts 中对数据目录隔离动机的解释。
• 所有日志输出到 stderr，stdout 保留给 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）等能力，依赖面已经较宽，评估新增包时需谨慎权衡。

贡献者许可协议（CLA）

CONTRIBUTING.md 规定：提交 PR、补丁或其他工作即表示同意以下条款，其核心目标是在保持开源发布的同时，为项目保留商业化许可的灵活性：

1. 贡献的许可：贡献者以项目所用许可证（GNU AGPL-3.0-only）向项目及所有下游用户授权其贡献。这与 package.json 的license字段以及仓库根目录的 LICENSE 一致。
2. 对维护者的授权：贡献者额外授予项目维护者一项永久、全球范围、非独占、免版税、不可撤销的版权与专利许可，允许复制、修改、分发、再许可甚至以不同许可条款转授权（例如商业许可）。这使得项目可以在开源 AGPL 发布之外提供商业授权。
3. 权利的正当性保证：贡献者保证所提交内容为原创（或有权提交），且据其所知不侵犯任何第三方权利。
4. 无担保：贡献以"按现状"提供，不附带任何形式的担保。

若代表雇主贡献，需确认已获得雇主授权；若无法同意以上条款，应先开 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