nullclaw 开发指南:从 Zig 0.16.0 环境搭建到 PR 提交的完整贡献流程
nullclaw 开发指南:从 Zig 0.16.0 环境搭建到 PR 提交的完整贡献流程
本文是 nullclaw(用 Zig 编写的自主 AI 助手基础设施)的开发者贡献指南,面向准备搭建本地开发环境、对仓库做一次聚焦改动、验证改动并提交 PR 的贡献者与维护者。读完本文,你将掌握 nullclaw 的版本钉扎策略、本地构建与测试命令、按需裁剪的编译选项(channels / engines)、Git Hooks 校验流程,以及开 PR 前必须完成的验证基线。
本文面向谁
- 贡献者:准备在本地搭建 nullclaw 开发环境的开发者;
- 维护者:在打开或审查 PR 之前验证改动的仓库维护人员;
- 文档 / 代码作者:需要核对仓库工作流与验证基线的文档作者。
动手编辑之前必读
- 开发和测试统一钉扎在 Zig 0.16.0。如果你在 Debian 上需要 Zig,请参考 Zig 安装指南。
- 修改代码前先阅读 AGENTS.md。
- 需要更多项目上下文、验证规则或子系统指引时,阅读 CLAUDE.md。
- 使用仓库 flake 的贡献者,
nix build与nix develop同样钉扎在 Zig 0.16.0(见 flake.nix,其中通过zig2nix.outputs.packages.${system}.zig-0_16_0显式锁定版本)。
先检查你本机的 Zig 版本:
zig version
仓库的 build.zig.zon 中 minimum_zig_version = "0.16.0" 是硬约束:从源码结构看,build.zig 的 ensureAndroidBuildEnvironment 中甚至专门针对 "build.zig.zon parse error mentioning '.nullclaw'" 这一现象提示原因就是 Zig 版本不是 0.16.0。
本地构建与测试
zig build
zig build -Doptimize=ReleaseSmall
zig build test --summary all
zig build:开发构建(Debug 优化)。zig build -Doptimize=ReleaseSmall:发布构建,是 nullclaw 面向二进制体积的默认发布目标。从 build.zig 可以看到,非 Debug 优化下会设置strip = true、unwind_tables = .none、omit_frame_pointer = true,并在 macOS 宿主 + 目标机上额外执行strip -x剔除本地符号,这与项目追求极小二进制体积的产品约束(AGENTS.md 中目标 < 1 MB ReleaseSmall)一致。zig build test --summary all:跑全部测试并输出汇总。AGENTS.md 记录当前规模为 245 个源文件、约 204K 行代码、5,640+ 项测试;build.zig 中 test step 会依次执行 compat 测试、库测试与可执行文件测试(zig build test不包含 WASI 目标)。
开代码相关 PR 前,最低限度必须跑:
zig build test --summary all
常用构建选项
zig build -Dchannels=telegram,cli
zig build -Dengines=base,sqlite
zig build -Dtarget=x86_64-linux-musl
zig build -Dversion=2026.3.1
各选项说明:
| 选项 | 作用 |
|---|---|
-Dchannels |
限制编译进二进制的消息通道实现集合,默认 all |
-Dengines |
限制编译进二进制的内存引擎集合,默认 base,sqlite |
-Dtarget |
交叉编译目标三元组,如 x86_64-linux-musl |
-Dversion |
覆盖嵌入二进制的版本字符串,默认 dev,发布流程会注入 git tag |
结合 build.zig 的解析实现,可以给出更完整的实测语义:
-Dchannels的全部合法 token:all、none、cli、telegram、discord、slack、whatsapp、matrix、mattermost、irc、imessage、email、lark、dingtalk、wechat(weixin为别名,二者都打开enable_channel_wechat)、wecom、line、onebot、qq、maixcam、signal、nostr、web、max。不存在的 token 会直接报错退出;all与none混用会被判定为歧义而拒绝。-Dengines的全部合法 token:base(或minimal)、all、none、markdown、memory、api、sqlite、lucid、redis、lancedb、postgres、clickhouse、kg。base代表 none/markdown/memory/api 四个基础后端;all会在此基础上追加全部可选后端。finalize()会做隐式依赖处理:sqlite/lucid/lancedb/kg 任一被选中都会自动打开enable_sqlite运行时依赖;hasAnyBackend()校验至少选中一个后端,否则构建报错。-Dtarget=x86_64-linux-musl:静态交叉编译到 musl libc,是追求最小部署体积的常见用法。注意 Android 目标有额外要求:build.zig的ensureAndroidBuildEnvironment要求通过--libc(或ZIG_LIBC)传入 libc/sysroot 文件,否则即便检测到ANDROID_NDK_HOME等环境变量也会终止构建;原生 Android 构建应直接在 Termux 内构建且不要传-Dtarget。-Dversion:覆盖嵌入二进制中的版本字符串。版本字符串通过build_options注入,实际出口在 src/version.zig(pub const string = build_options.version)与 src/main.zig 的version命令,以及acp、capabilities、main_wasi等处的输出。- 仓库里还可用的其他构建选项(从 build.zig 可见):
-Dstatic(静态链接可执行文件)、-Dembedded_wasm3=false(关闭内嵌 wasm3 运行时,默认开启)。
推荐的开发工作流
- 先读目标模块及其邻近测试,理解现状再动手;
- 每个 PR 只聚焦一个关注点(one PR, one concern);
- 文档与测试的更新随代码改动放在同一个 PR 里;
- 打开 PR 之前先完成全部验证。
文档同步要求
如果你的改动影响用户、运维人员或贡献者,需在同一 PR 内同步更新相关文档:
- 落地页:
README.md - 英文文档:
docs/en/ - 中文文档:
docs/zh/ - 安全策略:
SECURITY.md - 专门部署指南:
SIGNAL.md - 贡献指南:
CONTRIBUTING.md
文档应当保持:
- 面向任务(task-oriented),告诉读者"做什么"而不是罗列结构;
- 便于复制粘贴(copy-paste friendly),命令和配置片段可直接使用;
- 与 src/main.zig 的 CLI 命令路由和当前配置 schema 保持一致;
- 当同时影响中英文读者时,英文与中文文档保持同步。
Git Hooks:一次配置,每次自动校验
每个克隆只需启用一次:
git config core.hooksPath .githooks
仓库自带两个 hook(见 .githooks/pre-commit 与 .githooks/pre-push):
pre-commit:运行zig fmt --check src/,格式不过关会提示先执行zig fmt src/并阻止提交;pre-push:运行zig build test --summary all,测试失败会阻止推送。
这意味着格式检查在本地提交前、全量测试在推送前自动执行,把 CI 级别的两道闸门搬到了本地。
开 PR 前的验证清单
纯文档改动
建议执行:
git diff --check
并人工核对文档中的链接、路径和命令示例是否有效(本文中的仓库相对路径均为已确认存在的真实文件)。
代码改动
必须执行:
zig build test --summary all
影响发布(release-sensitive)的改动
额外执行:
zig build -Doptimize=ReleaseSmall
确保在发布目标(体积与 strip 设置均不同于 Debug)下依然能编译通过。
PR 描述写作指南
PR 描述应说明四点:
- 改了什么(what changed)
- 为什么改(why it changed)
- 跑了哪些验证(what validation you ran)
- 存在哪些风险或后续工作(any risks or follow-up work)
推荐模板:
## Summary
- ...
## Validation
- zig build test --summary all
## Notes
- ...
高频改动路径速查
| 路径 | 用途 |
|---|---|
| src/main.zig | CLI 命令路由(agent、gateway、config、version、models 等命令的入口) |
| src/config.zig | 配置加载与环境变量覆盖 |
| src/gateway.zig | 网关与 webhook |
| src/security/ | 安全与沙箱 |
| src/providers/ | 模型提供方(anthropic、openai、gemini、ollama、openrouter、vertex 等) |
| src/channels/ | 消息通道(telegram、discord、slack、whatsapp、qq、web 等 20+ 实现) |
| src/tools/ | 工具实现(文件操作、shell、web_search、memory_、cron_ 等) |
| src/memory/ | 内存后端与检索(engines/retrieval/vector/lifecycle) |
从源码结构看,nullclaw 采用 vtable + factory 的模块化架构(见 AGENTS.md):src/providers/root.zig 的 Provider、src/channels/root.zig 的 Channel、src/tools/root.zig 的 Tool、src/memory/root.zig 的 Memory 都是扩展点。新增功能优先通过"实现 vtable 结构 + 在 factory 注册"的方式接入,而不是做横切式重写;同时二进制体积与内存占用是硬性产品约束,新增 libc 调用、运行时分配或大数据表前需要先论证其体积成本。
更多阅读
- 架构总览:docs/en/architecture.md
- 命令参考:docs/en/commands.md
- 贡献指南:CONTRIBUTING.md
- 工程协议:AGENTS.md
- 中文读者可对照阅读 docs/zh/development.md 与 docs/zh/README.md
下一步
- 在深入编辑 runtime、security 或 provider 代码前,先读 架构文档;
- 改动涉及 CLI 表面或示例时,参考 命令文档;
- 准备最终 PR 描述与审查流程前,打开 CONTRIBUTING.md。