用 perspectives 导出一个确定性的工作区切片

其他语言: English, Español, Português, 日本語, Deutsch, Français, 한국어, Italiano, हिन्दी · 全部中文指南

声明:Carbon Forge 由 100monkeys.ai 开发,因此请把这篇指南当作开发方的说明来读。它由我们的一个 AI 智能体根据公开文档起草,主要是 Perspectives: beam angles through one workspace 和 Source control settings 的 Perspectives 一节,并经公司审阅;这个简体中文版是英文原版指南的译文。文中的 perspective 和调用都是文档自己的示例,引文保留英文原文,译文附在旁边。文档没有回答的问题,最后一节会说明。

什么是 perspective

文档的说法:"A perspective is a named lens through that record. It picks out a part of it, by kind, surface, path, media type, tag or metadata, and answers that part at paths of its own."(perspective 是透过该记录的一面具名透镜。它按类型、界面、路径、媒体类型、标签或元数据挑出其中一部分,并在自己的路径下返回这一部分。)还有:"Nothing is copied to make one."(创建它不需要复制任何东西。)对导出来说有两点很重要。它在范围上是只读的:"A perspective never discloses. It narrows what the reader already reads and never widens it."(perspective 从不泄露。它只收窄读者本来就能读到的内容,从不扩大。)它的下载是确定性的:"The same ref through the same perspective gives the same bytes."(同一个 ref 经过同一个 perspective,得到相同的字节。)

第 1 步:列出工作区解析出的 perspectives

调用 perspectives.list。每个工作区都有内置的 perspectives:all、code、docs、adrs、internal、public(正是匿名读者看到的内容),以及每棵代码树一个的 tree:<path>,以该树为根。实例管理员可以添加全实例范围的 perspectives,工作区自己的排在最后;"The nearest layer wins"(最近的一层生效)。每个结果都会标明它的 source 以及它 overrides 的来源。如果某个内置的已经够用,直接跳到第 3 步。

第 2 步:在 .perspectives 页面写下你自己的 perspective

工作区的 perspectives 存放在保留页面 .perspectives 中,形式是一个围栏 JSON 块或一张表。文档的示例,精简为一个 perspective:

{
  "perspectives": [
    {
      "name": "api",
      "title": "API service",
      "description": "The api tree's source and README, without generated files.",
      "include": [
        { "kinds": ["tree"], "paths": ["/services/api/src", "/services/api/README*"] }
      ],
      "exclude": [{ "paths": ["*.generated.ts"] }],
      "root": "services/api"
    }
  ]
}

一条规则在它列出的所有字段都匹配时才算匹配;include 收入匹配任一规则的所有内容,exclude 去掉匹配任一规则的所有内容,"even when an include rule matched it"(即使某条 include 规则已经匹配了它)。路径是 gitignore 风格的通配符,不能以 ! 开头。设置了 root 时,每个路径都会去掉这个根,所以这个 perspective 返回 src/main.ts 和 README.md。代码树按文件逐个判断。monorepo、service、library 或 docs-site 等模板可以通过 perspectives.adopt,或在 Settings、Workspace、Source control 中点 Adopt,替你写好这个页面。

写错的行不会被跳过。"When the page cannot be read, every perspective read in the workspace is refused, quoting the page's first bad row, until it is fixed."(页面无法读取时,工作区里所有经由 perspective 的读取都会被拒绝,并引用页面上第一行错误,直到修好为止。)页面上有一个面板 Perspectives on this page,每次保存时都会重新检查。

第 3 步:在某个 ref 上预览

perspectives.preview 按类型统计 perspective 在某个 ref 上包含的内容,并返回前若干条投影路径,默认 100 条,最多 500 条。"It stores nothing, so it is the way to check a perspective before downloading it."(它什么都不存储,所以是下载前检查 perspective 的方法。)在浏览器里,同样的统计显示在代码浏览器 ref 栏的选择器旁边:Selects <n> pages, <n> atoms, <n> code trees, <n> files, <n> library entries at <ref>。

第 4 步:选一个不会移动的 ref

ref 可以是 trunk(默认)、lane:<label>、cut:<name> 或 snapshot:<id>。导出任务在运行时解析 ref,"so trunk is the trunk at that moment. Name a cut or a snapshot for a point that does not move."(所以 trunk 指的是那一刻的 trunk。要一个不会移动的点,就指定一个 cut 或 snapshot。)想要可复现的下载,就指定一个 cut。处于冲突中的 lane 会被拒绝,直到冲突解决。

第 5 步:导出并下载归档

perspectives.export { "perspective": "api", "ref": "cut:<name>", "format": "tar" }
→ { export_id, status: "queued" }
exports.status { ... }   // until it answers a download_url

用导出 id 轮询 exports.status,直到它返回 download_url;发起请求的人也会收到一封带链接的邮件。归档命名为 <workspace>-<perspective>-<ref>.zip 或 .tar。归档里,页面或 atom 是一个带 frontmatter(标题、类型和元数据)的 Markdown 文件;代码文件保留原有字节和权限模式;符号链接仍是符号链接。条目按路径字节排序,每个文件都带 ref 的时间,不做压缩,也不写入所有者。zip 最多容纳 65,535 个条目和 4 GiB;超过就用 tar。在浏览器里,选择 zip 或 tar,然后点预览旁边的 Download。

第 6 步:按清单核对每个文件

每个导出的归档都带有 .carbon/perspective.json,格式为 carbon-perspective/1。它写明实例、工作区、解析后的 perspective 和 ref:cut 或 snapshot 用它的 snapshot id,trunk 或 lane 用 composition_sha256。每个条目列出:

path, kind, entity_id, revision_id, content_hash, seal_hash, mode, size, sha256

对每个文件计算哈希并与 sha256 比较;把 revision_id、content_hash 和 seal_hash 与记录比较。文档说:有了清单,"a reader can check every file against the record it came from"(读者可以把每个文件与它所来自的记录核对)。正因如此,归档是记录的一个切片,而不是 "a copy that can drift into a second truth."(一份可能漂移成第二个事实来源的副本。)

第 7 步:通过 lane 把修改带回来

"A download is read-only by design. Nothing in the archive is read back."(下载在设计上就是只读的。归档里的任何内容都不会被读回。)要把基于归档完成的工作带回来,请用工具调用写入,放到一个 lane 上再落地,或者导入,这样每处修改都带有自己的执行者和意图。Working in lanes 讲解 lane,我们的指南 Cut a release in Carbon Forge and push it to GitHub(英文)讲解如何做出你要导出的 cut。

文档没有回答的问题

• 导出上限有多大。超过上限的下载会失败,并给出一句说明上限的话,但文档没有说默认值。
• download_url 能有效多久,导出会保留多久。
• 谁可以编辑 .perspectives。采用模板是管理员操作;页面本身 "is edited like any other page"(和其他页面一样编辑),读起来意味着任何编辑者都可以。
• 一个按清单核对归档的工具。格式已经说明;核对留给每位读者自己的脚本。