Agent Substrate 贡献指南：从 CLA 签署到 root 级测试与 schema 演进的完整开发流程

人工智能AI AgentAgent 沙箱云原生容器运行时零信任【免费下载链接】substrateAgent Substrate: the core system项目地址https://gitcode.com/GitHub_Trending/substrate7/substrate点击查看免费下载Agent Substrate 是一个处于早期高速迭代阶段的 agent 执行运行时其贡献流程强调小而聚焦、先讨论后开工、一切变更必须有测试。本文以仓库根目录的 CONTRIBUTING.md 为主体逐节拆解签署 CLA、搭建本地开发环境、PR 规模分级、root-gated 特权测试机制、PostgreSQL schema 演进规则与版权头规范并结合internal/roottest、hack/run-root-tests.sh、hack/verify/postgresql-migrations.sh等源码与脚本说明每一条规则背后的工程动机与可运行的验证命令帮助你在提交第一个补丁前把流程一次走对。贡献前必读CLA、社区准则与开发环境签署 Contributor License AgreementCLA向 Agent Substrate 提交任何补丁前必须先签署 Contributor License AgreementCLA。协议的核心是你或你的雇主保留贡献代码的版权同时授权项目使用与再分发这些贡献。如果你或当前雇主此前已签署过 Google CLA哪怕是为其他项目通常无需重复签署可以通过 https://cla.developers.google.com/ 查看现有协议状态或签署新协议。遵循 Google 开源社区准则项目遵循 Googles Open Source Community Guidelines所有互动包括代码评审、Issue 讨论、社区会议均以此为准。搭建本地开发环境默认gVisor运行时按 README.md 的 QuickstartDevelopment搭建本地集群即可。核心步骤为安装 Go、kubectl、dockerkind等其余依赖由 Go 自动管理随后依次执行# 创建 kind 集群与本地 registryIPv4可用 IP_FAMILYdual|ipv6 覆盖 hack/create-kind-cluster.sh # 安装 ate 系统、PostgreSQL、rustfs hack/install-ate-kind.sh --deploy-ate-system # 安装 counter 演示 hack/install-ate-kind.sh --deploy-demo-counter # 安装 kubectl-ate CLI go install ./cmd/kubectl-ate # 在 demo 的 atespace 中基于 counter 模板创建 actor kubectl ate create actor my-counter-1 -a ate-demo-counter --template counter # 将网络路由器端口转发到本地 8000 端口 kubectl port-forward -n ate-system svc/atenet-router 8000:80在另一个终端用curl -X POST -H ate-target-actor: ate-demo-counter/my-counter-1 -i http://localhost:8000/即可验证 actor 的请求路由链路。microVM 运行时microVM 沙箱ateom-microvm即运行在 Cloud Hypervisor 上的 Kata guest需要/dev/kvm。Linux 主机直接验证 KVM 可用性后运行./hack/create-kind-cluster.shApple SiliconM3 及以上可通过 Lima 的嵌套虚拟化暴露/dev/kvm。完整的分步指引见 docs/dev/microvm-local.md其中包含/dev/kvm: permission deniedrootless Docker、M1/M2 上Starting VZ ... FATA exitingApple Virtualization framework 仅 M3 支持嵌套虚拟化等常见问题的排查表。贡献流程先讨论再动手保持小而聚焦该文档明确说明这是一个非常年轻的项目团队仍在打磨设计与架构迭代极快。这对贡献者有三点直接影响变更可能频繁需要 rebase项目演进快PR 需要随时跟上主干。聚焦于单一 Issue 或功能的小 PR 比横跨多个模块的大 PR 更容易评审与更新。开工前先讨论项目当前只关注让系统可用所需的最小能力集。开始贡献前先在相关 Issue 下留言若没有则新建一个确保你的工作与项目近期目标一致避免与在途工作重复。不对齐目标的 PR 可能被直接关闭这不代表不欢迎新人而是为了保证精力集中在最重要的工作上。如果你的目标是在 Substrate之上构建东西而不是修改 Substrate 本身请先阅读 docs/integration-repos.md 确定代码归属微不足道的 demo如 counter demo、CI 使用的无密钥生命周期 mock留在核心仓库非平凡的端到端集成各自拥有agent-substrate组织下的独立仓库核心缺口一律先在 core 落地再让集成依赖已发布的版本严禁下游 fork 打补丁。PR 规模分级S/M/L/XL 与拆解策略项目为评审体验优化 PR大 PR 会被拆解小 PR 会被合入。具体策略大 PR把巨大的改动拆成一系列逻辑上各自独立的 PR。当中间步骤单独看没有价值时保留为一个 PR但在逻辑断点处分多个 commit并在合并时保留这些 commit。小 PR 与批量 PR发现 typo 时通读整个文件一次性修完而不是只提交单处修改把相关的 typo、文档与单行清理修复合并进一个 PR避免为同一区域开多个碎片化 PR。维护者可能要求你合并碎片化 PR或直接关闭它们。规模参考刻度规模变更行数S 30 行M 100 行L 500 行XL 1000 行大多数 PR 应为 L 或更小XL 及以上是拆分的候选对象。Code Reviews所有提交都要评审且必须有测试所有提交包括项目成员自己的提交都通过 GitHub Pull Request 评审。两条硬性要求所有代码变更必须附带测试。没有测试的代码不会被合并导致测试失败的代码也不会被合并。每次应用 schema 变更都必须遵循 docs/dev/postgresql-schema-evolution.md 中的 PostgreSQL schema 演进规则详见下文。从仓库结构看这一要求贯穿全部核心组件——cmd/下的每个命令如 cmd/ateapi、cmd/atelet、cmd/atecontroller、cmd/atenet以及internal/下几乎所有包都成对提供了*_test.go文件测试与实现同目录同包是项目默认约定。Root-gated 测试需要 root 的特权测试如何编写与运行部分测试需要 root 权限overlay 挂载、mknod、trusted.*xattr 等。这类测试通过 internal/roottest 的roottest.Require(t, ...)作为第一条语句来门控func TestRequire(t *testing.T) { reached : false t.Run(gate, func(t *testing.T) { Require(t, gate probe) reached true }) if want : os.Geteuid() 0; reached ! want { t.Errorf(gated code ran %v, want %v (euid %d), reached, want, os.Geteuid()) } }roottest.Require的实现internal/roottest/roottest.go非常简洁func Require(tb testing.TB, reason string) { tb.Helper() if os.Geteuid() ! 0 { tb.Skipf(needs root: %s (run hack/run-root-tests.sh to execute under sudo), reason) } }工作机制与 CI 配合方式普通go test ./...下这类测试因非 root 而skipCI 会重新以sudo运行所有导入了该包的测试包新增特权测试只需要加一行roottest.Require调用无需任何 CI 改动。本机运行特权测试的命令hack/run-root-tests.shrun-root-tests.shhack/run-root-tests.sh的实现揭示了几个关键细节它用go list -f {{range .TestImports}}...{{end}}{{range .XTestImports}}...{{end}}同时在包内测试TestImports与外部测试包XTestImports中查找 marker 导入路径github.com/agent-substrate/substrate/internal/roottest自动发现所有 root-gated 包——这就是新增特权测试无需 CI 改动的原理使用-count1强制禁用 Go 测试缓存测试缓存不按 euid 做 key否则 root 重跑会回放非特权运行的 skip 结果已是 root 时直接go test -count1否则通过sudo -E env PATH${PATH}保留调用者的 Go 工具链与模块缓存。PostgreSQL schema 演进滚动更新下保证前一个二进制安全ateapi在就绪前应用 PostgreSQL 迁移滚动更新期间前一个二进制继续服务请求新二进制修改 schema。由于 goose 一次提交一个迁移失败的迁移运行可能留下任意已完成的前缀因此规则的核心目标是保证前一个二进制在任意迁移前缀下都安全。兼容性契约与变更规则保持每个迁移前缀与前一个二进制的读写兼容把每个迁移文件边界视为持久化的数据库状态不得依赖后续迁移来修复更早前缀的兼容性新二进制从前一版本迁移 schema并在所有待定迁移完成前不进入就绪状态SELECT与INSERT必须使用显式列清单优先加法变更先加表、列、索引再让新二进制使用新列必须是 nullable 或带兼容的数据库默认值不得删除/重命名前一个二进制仍在使用的表或列不得以不兼容方式改变其类型或语义不得在前一个二进制仍可写入违规值时收紧约束不得移除前一个二进制依赖的默认值两个 schema 结构同时可写时需保持一致性新二进制依赖新结构前先回填存量数据启动期间不得执行大规模数据回填应单独提出迁移流程。保持 actors 表可分区为保留按atespace或actors表按name分区的可能性任何 schema 变更或查询都不得引入省略atespace的唯一索引/约束actors表则不得省略name、按省略atespace的列引用的外键、以及不按atespace过滤的查询actors查询还必须过滤name。跨分区读取如全局列表必须列入TestActorsTablePartitionable否则需要社区同意的豁免。Expand and contract 三步走替换或移除 schema 时使用扩展与收缩序列在 release N 增加新结构、保留旧结构在 release N1 停止使用旧结构在 release N2 移除旧结构。这保证滚动更新乃至临时二进制回滚期间前一个二进制始终兼容注意二进制回滚不会回滚 schema。迁移文件规则与提交前检查清单迁移文件存放于cmd/ateapi/internal/store/atepg/migrations规则包括使用下一个顺序编号NNNNNN_name.sql文件名、恰好一个-- goose Up注解、仅 SQL 迁移、不添加 down 迁移、不使用NO TRANSACTION/ENVSUB、不写事务控制语句、schema 变更不使用IF NOT EXISTS、保持每个启动迁移简短。首个稳定 v1 发布前可以修改或 squash 迁移文件改后重建开发数据库v1 发布后不得修改或删除已发布迁移文件只能新增迁移来修正不得手动编辑schema_migrations账本。提交前清单识别使用被变更对象的前一二进制读写 → 对照每个新迁移前缀检查这些操作 → 某个前缀会破坏操作时使用 expand and contract → 为 schema 行为新增或更新测试 → 运行迁移验证器与 PostgreSQL store 测试hack/verify/postgresql-migrations.sh go test ./cmd/ateapi/internal/store/atepg验证脚本 hack/verify/postgresql-migrations.sh 会逐条强制检查上述文件规则文件名格式^([0-9]{6})_[a-z0-9_]\.sql$、版本号必须严格递增且连续、必须包含-- goose Up、不得包含-- goose Down、NO TRANSACTION、ENVSUB、IF NOT EXISTS及BEGIN/COMMIT/ROLLBACK等事务控制语句在存在形如v1.x.y的已发布 tag 时还会用git diff --diff-filterMD校验已发布迁移文件未被修改或删除。Copyright Headers每个源文件必须携带版权与许可证信息每个包含源代码的文件都必须包含版权与许可证信息包括你可能提供给浏览器的 JS/CSS 文件目的是帮助善意的贡献者避免无意中做出不符合许可证的复制行为。各文件类型的标准头部模板位于 ./hack/boilerplate例如 Go 文件使用// Copyright 2026 Google LLC加 Apache-2.0 许可说明见 hack/boilerplate/go.txtShell 脚本使用#注释版本见 hack/boilerplate/sh.txt。仓库还提供了自动化校验入口 hack/verify/boilerplate.sh它调用 hack/util/verify-boilerplate.py 检查全仓库文件的版权头合规性——本地提交前可运行它做自检。完整验证体系还包括 hack/verify/ 下的 codegen、gofmt、golangci-lint、licenses、metrics、threats 等检查脚本可在hack/verify-all.sh中一次性触发。总结Agent Substrate 的贡献流程可以用三条主线概括先对齐再动手CLA、社区准则、Issue 先讨论、目标对齐、小步快跑PR 规模分级、单 Issue 聚焦、批量小修、变更必须可验证测试伴随代码、root-gated 测试机制、PostgreSQL schema 演进规则、版权头校验。理解roottest.Require与hack/run-root-tests.sh的自动发现机制、掌握 expand and contract 的 schema 演进节奏是绕开评审返工、让补丁顺利合入的关键。赞分享人工智能AI AgentAgent 沙箱云原生容器运行时零信任【免费下载链接】substrateAgent Substrate: the core system项目地址https://gitcode.com/GitHub_Trending/substrate7/substrate点击查看免费下载相关推荐osv-scanner 贡献指南从 CLA 签署、PR 流程到测试、构建与文档贡献的完整实践osv scanner 贡献指南从 CLA 签署、PR 流程到测试、构建与文档贡献的完整实践 本指南以 osv scanner 仓库根目录下的 CONTRIB漏洞扫描供应链安全应用安全CLIMCP 服务Python Fire 贡献指南从 CLA 签署到代码评审、测试与 Lint 的完整参与流程Python Fire 贡献指南从 CLA 签署到代码评审、测试与 Lint 的完整参与流程 Python Fire 是一个能从任意 Python 对象自动生开发工具CLIChocolateychoco开源贡献指南从 CLA 签署到 Pull Request 合并的完整流程Chocolateychoco开源贡献指南从 CLA 签署到 Pull Request 合并的完整流程 Chocolatey 是 Windows 平台的包包管理器CLI开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考