COMMUNITY
社区与贡献
可以从一条没走完的任务来贡献。记录它在哪台机器上跑、卡在哪一步、哪些结果没有回来。代码、测试和可复现的报告都能帮上忙。
从源码开始
三条命令把内核、CLI 与面板跑起来;守护进程在构建时把控制台嵌进二进制。
make runmake webmake build-webui没有 make web 时 go build 会嵌入占位页,因此在没有 Node 的机器上也能编译;任何 UI 改动发版前必须先跑 make web。
工具链
三个版本下限来自 CONTRIBUTING.md;低于下限的构建不在支持范围内。
| TOOL | VERSION | 用途 |
|---|---|---|
Go |
≥ 1.26.11 |
内核、CLI、面板与测试 |
Node.js |
≥ 18 |
Web 控制台(webui/app) |
Python |
≥ 3.10 |
语音侧车与 Agent 适配器 |
数据库用纯 Go SQLite,不需要 CGO;Windows 上跑 -race 才需要 MinGW-w64 工具链。
工程门禁
PR 只有在所有门禁全绿时才合并。推之前在本地跑一遍同样的检查。
make gatemake gate-allcd webui/app && npm run typecheck- CI 把同一套检查拆成并行作业:lint、test、race、web、适配器契约、TUI PTY 与跨平台矩阵。
- go test -race ./... 必须全过。内核是并发系统,竞态检测的发现是发布阻断项,不是警告。
- core、scheduler、storage 三个核心包尽量保持约 60% 以上覆盖率;修 bug 要带一条在修复前会失败的回归测试。
- 新增线协议或委派行为要配一条 loopback 测试,范式见 internal/core/dedup_test.go 与 scripts/smoke-delegate。
代码约定
这几条不是风格偏好,是并发系统里能被复现教训换来的约束。
错误
用 %w 包装,用 errors.Is / As 判断;不静默丢弃错误,也不在同一个函数里既记日志又返回它。
注释
解释为什么,不解释是什么。半年后的读者需要的是不变量、取舍或事故引用;非显然的并发决策写在发生的位置。
并发
每把 mutex 注明它保护什么;不持锁做 I/O 或往 channel 发送;关闭由发送方负责,goroutine 的属主从 spawn 处可辨认。
安全
fail closed:分类、授权与脱敏默认走最严格的分支。带机密值的新配置键要做 0600 权限与告警,机密永不进日志。
提交风格
Conventional Commits,scope 取顶层目录名,subject 用祈使句且具体到能在 git log --oneline 里独立成立。
| 示例 | |
|---|---|
feat(cli): interactive REPL — slash commands, /web console, five-language i18n |
新增 CLI 能力 |
fix(core): deterministic mutual-dial dedup — end the 1s connect/disconnect flap |
修复内核缺陷 |
feat(web): full console — queue/detail/ask/projects/nodes + go:embed single binary |
新增控制台能力 |
允许的类型:feat / fix / docs / refactor / chore / test;scope 取 core、cli、web、scheduler、defense 等顶层布局。
控制台开发
控制台是 Vite + Preact + TypeScript,除 Preact 外没有运行时依赖。
- 所有面向用户的字符串走 i18n;新增键要同时补进 webui/app/src/i18n/ 下每一种语言,不能先只交英文键以后再补。
- 英文是 fallback,缺键会静默落到英文;这个行为方便调试,但不构成只写英文的理由。
- 源码还有 internal/i18n 的键集守卫与 web 侧 parity.test.ts,两侧都会因缺键变红。
Pull request 流程
main 受分支保护:必须走 PR,必过检查全绿才允许合并,配置里没有绕过名单。
fork / branch从 main 拉分支,改动保持单一主题,附上复现或验证方式。
make gate-all本地跑齐门禁;改过依赖要 go mod tidy,改过翻译要扫字符污染。
gh pr create开 PR 后等 10 项 required checks 全绿;合并用 rebase,不产生合并提交。
安全缺陷不走这个流程:按上一节的渠道私下上报,不要写进公开 PR 描述。
行为准则与许可
参与即表示同意行为准则;贡献代码还会涉及 CLA 与双许可口径。
联系与讨论
没有论坛,也没有必须加入的群;公开讨论留在仓库里,私下事项走邮件。