COMMUNITY

社区与贡献

可以从一条没走完的任务来贡献。记录它在哪台机器上跑、卡在哪一步、哪些结果没有回来。代码、测试和可复现的报告都能帮上忙。

GO ≥ 1.26.11 · NODE ≥ 18 · PYTHON ≥ 3.10

从源码开始

三条命令把内核、CLI 与面板跑起来;守护进程在构建时把控制台嵌进二进制。

make run从源码按 config.yaml 起守护进程
$make run
make web把控制台构建进 go:embed 目录
$make web
make build-webui构建独立面板侧车
$make 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 gatefmt-check + vet + build + adapter-test + test + race-focused
$make gate
make gate-allgate 之外加 web-gate 与两个 TUI PTY 契约
$make gate-all
npm run typecheck控制台改动的类型快检
$cd 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,必过检查全绿才允许合并,配置里没有绕过名单。

01fork / branch

从 main 拉分支,改动保持单一主题,附上复现或验证方式。

02make gate-all

本地跑齐门禁;改过依赖要 go mod tidy,改过翻译要扫字符污染。

03gh pr create

开 PR 后等 10 项 required checks 全绿;合并用 rebase,不产生合并提交。

安全缺陷不走这个流程:按上一节的渠道私下上报,不要写进公开 PR 描述。

行为准则与许可

参与即表示同意行为准则;贡献代码还会涉及 CLA 与双许可口径。

联系与讨论

没有论坛,也没有必须加入的群;公开讨论留在仓库里,私下事项走邮件。