其他语言: English, Español, Português, 日本語, Deutsch, Français, 한국어, Italiano, हिन्दी · 全部中文指南
声明:Carbon Forge 以及与之配套的 AEGIS 由 100monkeys.ai 开发,因此请把这篇指南当作开发方的说明来读。它由我们的一个 AI 智能体根据公开文档起草,主要是 Working in lanes 的第 8 步、Source control settings、MCP tools catalog: Lanes, continued 和 Source control: how it is built and why,并经公司审阅;这个简体中文版是英文原版指南的译文。表格、调用和拒绝信息都来自文档本身,引文保留英文原文,译文附在旁边。文档没有回答的问题,最后一节会说明。
为什么把规则保存在记录里
文档用两句话说明理由:"Landing rules are the code-owners rule kept in the record. The approvers a path needs are named on a page of the workspace, and each approval binds to the lane's composition hash, so review is the record's and not a forge's."(落地规则就是保存在记录里的代码所有者规则。一个路径需要的批准者写在工作区的一个页面上,每次批准都绑定到 lane 的组合哈希,所以审阅属于记录,而不属于某个代码托管平台。)没有这一点,"a landing can carry code no approver saw."(一次落地可能带入没有任何批准者看过的代码。)先说明一个边界:"Carbon runs no review itself."(Carbon 自己不做任何审阅。)它记录谁批准了什么;审阅由你指定的人和工作流来做。
第 1 步:保护 trunk
规则只在受保护的 trunk 上才会被读取。工作区管理员在 Settings、Workspace、Source control 中勾选 Protect the trunk,也可以再勾选 Protect pages and atoms too。智能体可以这样检查该设置:
workspaces.get_settings {}
→ { "workspaceId": "…", "trunkProtected": true, "trunkProtectedEntities": false }此后 "the trunk moves only by a lane's landing"(trunk 只会因 lane 的落地而移动),直接写入会被拒绝,提示 workspace <slug> protects its trunk: the trunk lands by lanes.land only; write on a lane。
第 2 步:编写 .landing-rules 页面
在保留路径 .landing-rules 创建一个页面,它的第一张 Markdown 表格的表头是 glob | approvers | gate。文档的示例:
| glob | approvers | gate |
| --- | --- | --- |
| app/src/billing/** | <user id>, <user id> | |
| docs/** | <user id> | docs-review |glob:一条使用导入排除规则语法的规则,不能以!开头。approvers:用逗号分隔的用户 id,每个都必须是工作区成员。在指定了门控的行里可以为空。gate:可选,一个 AEGIS 工作流的名称,最多 128 个字符。"Carbon never runs it."(Carbon 从不运行它。)
只有工作区管理员能写这个页面,无论在 trunk 还是在 lane 上;其他人会收到拒绝信息 The landing rules page .landing-rules is reserved: only a workspace admin writes it.
第 3 步:确认服务器认为它有效
设置对话框的 Landing rules 一节会报告 <n> rules, valid.,或者指出格式错误的一行并提示 Every landing is refused until it is fixed. 列出非成员的行,或既没有批准者也没有门控的行,都属于格式错误。一个损坏的页面会让所有落地停下,所以在依赖它之前先检查。
第 4 步:在 lane 上完成工作
按照 Working in lanes 所示打开一个 lane 并在上面写入。落地时,lane 触及的每个路径都会与每一行比对:页面按其路径,移动过的页面按新旧两个路径,树中的文件按 <tree path>/<entry path>。
第 5 步:查看 lane 还需要什么
lanes.create { "label": "agent/7/fix-login" }
lanes.get { "label": "agent/7/fix-login" }
lanes.export { "lane": "agent/7/fix-login" } // header line: # composition: <hash>
lanes.approve { "lane": "agent/7/fix-login" }lanes.get 列出已批准的人、尚缺的人,以及每个门控是 pending 还是 satisfied。在应用里,lane 的 Overview 显示同样的信息:它匹配的规则、已批准 n/m,以及标注为 "via gate <workflow>" 的门控批准。
第 6 步:批准确切的改动
审阅者阅读 lanes.export,这是一份以 # composition: <hash> 开头的统一 diff,然后调用 lanes.approve。批准绑定到这个哈希,所以 "a reviewer who reads the export and approves at its # composition: value has approved exactly that change."(阅读导出并在其 # composition: 值上批准的审阅者,批准的正是那一个改动。)之后任何会改变落地内容的补丁、冲突解决或 trunk 移动都会改变哈希,先前的批准随之失效。请在最后一次改动之后批准,而不是之前。
第 7 步:让 AEGIS 工作流作为门控来批准
门控只能由该工作流本身满足。执行的令牌通过 tokens.mint_execution 签发,带上可选参数 workflow,值为门控名称,长度 1 到 128 个字符;执行随后用这个令牌调用 lanes.approve。匹配是精确的,"case included"(包括大小写)。"A person's approval, and one given through a token minted without workflow, satisfies no gate."(个人的批准,以及通过未带 workflow 签发的令牌给出的批准,都不能满足任何门控。)执行令牌是调用方令牌的子令牌,限定于一个工作区、一个树路径、一个 lane、一份工具列表,最长一天。使用 AEGIS by 100monkeys.ai, in beta 时,门控就是你的一个工作流:表格行写明它,Carbon Forge 只检查它的某次执行是否给出了批准。
第 8 步:落地
lanes.land { "label": "agent/7/fix-login", "intent": "fix: accept magic links", "dry_run": true }
lanes.land { "label": "agent/7/fix-login", "intent": "fix: accept magic links" }缺少批准的落地会被整体拒绝,并指出缺少什么:
Lane <label> touches <path> under landing rule <glob> (line <n>), which needs approval from <user ids> and gate <name> at the lane's current composition. Approve with lanes.approve; nothing was written.落地完成后,它所用到的批准,包括门控的批准,"follow its intent as Approved-by: lines"(以 Approved-by: 行的形式跟在其意图之后),变更集像其他变更集一样被封存。注意:带 dry_run 的落地不会检查规则;要检查规则,请读取 lanes.get。
文档没有回答的问题
- AEGIS 这一侧。文档说 "the execution service"(执行服务)会带
workflow签发执行令牌,但没有展示一个持有该令牌并调用lanes.approve的 AEGIS 工作流。 - 批准者只能是用户 id。没有组或团队,设计文档写明 "No per-directory permissions"(没有按目录的权限)。
- 当令牌的用户本身是列出的批准者时,通过执行令牌给出的批准是否也算作该用户的批准。