他の言語: English, Español, Português, Deutsch, Français, 한국어, 简体中文, Italiano, हिन्दी · 日本語のガイド一覧
開示: Carbon Forge は 100monkeys.ai で開発しているため、作り手による説明として読んでください。このガイドは公開ドキュメント、主に Perspectives: beam angles through one workspace と Source control settings の Perspectives の節をもとに当社の AI エージェントが下書きし、当社がレビューしました。この日本語版は英語の原文ガイドの翻訳です。パースペクティブと呼び出しはドキュメント自身の例で、引用は英語のまま示し訳を添えています。ドキュメントが答えていない点は最後の節に書いています。
パースペクティブとは
ドキュメントはこう書いています。"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."(パースペクティブは、その記録を通して見る名前付きのレンズです。種類、サーフェス、パス、メディアタイプ、タグ、メタデータでその一部を選び出し、その部分を独自のパスで返します。)また、"Nothing is copied to make one."(作るために何もコピーされません。)書き出しにとって大事な性質が 2 つあります。届く範囲は読み取り専用です。"A perspective never discloses. It narrows what the reader already reads and never widens it."(パースペクティブが何かを開示することはありません。読み手がすでに読めるものを絞るだけで、広げることはありません。)そしてダウンロードは決定的です。"The same ref through the same perspective gives the same bytes."(同じ ref を同じパースペクティブで通せば、同じバイト列になります。)
ステップ 1. ワークスペースが解決するパースペクティブを一覧する
perspectives.list を呼びます。どのワークスペースにも組み込みのものがあります。all、code、docs、adrs、internal、public(匿名の読み手に配信されるものとまったく同じ)、そしてコードツリーごとに、そのツリーを起点とする tree:<path> です。インスタンス管理者はインスタンス全体のものを追加でき、ワークスペース自身のものは最後に来ます。"The nearest layer wins"(いちばん近い層が優先されます)。各応答はその source と、それが overrides するソースを示します。組み込みのもので足りるなら、ステップ 3 に進んでください。
ステップ 2. .perspectives ページに自分のものを書く
ワークスペースのパースペクティブは予約ページ .perspectives に、フェンス付きの JSON ブロックか表として置きます。ドキュメントの例を 1 つのパースペクティブに絞るとこうなります。
{
"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 形式の glob で、! で始めることはできません。root を設定すると各パスからその起点が取り除かれるので、この例は 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."(ページが読めないときは、修正されるまで、ワークスペース内のパースペクティブ経由の読み取りがすべて、ページの最初の不正な行を引用して拒否されます。)ページには Perspectives on this page というパネルが表示され、保存のたびに再検査します。
ステップ 3. ref でプレビューする
perspectives.preview は、ある ref でパースペクティブが含むものを種類ごとに数え、投影された最初のパスを返します。既定は 100 件、最大 500 件です。"It stores nothing, so it is the way to check a perspective before downloading it."(何も保存しないので、ダウンロードの前にパースペクティブを確かめる方法になります。)ブラウザーでは、コードブラウザーの 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 はその時点のトランクです。動かない時点がほしいならカットかスナップショットを指定してください。)再現したいダウンロードにはカットを指定します。競合中のレーンは、競合が解決するまで拒否されます。
ステップ 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 です。中では、ページやアトムはタイトル、種類、メタデータを frontmatter に持つ Markdown ファイルになり、コードファイルはバイト列とモードを保ち、シンボリックリンクはシンボリックリンクのままです。エントリはパスのバイト順に並び、各ファイルには ref の時刻が付き、圧縮はされず、所有者は書き込まれません。zip に入るのは最大 65,535 エントリ、4 GiB までで、それを超えるなら tar を使います。ブラウザーでは、プレビューの横で zip か tar を選んで Download を押します。
ステップ 6. 各ファイルをマニフェストと照合する
どのアーカイブにも、形式 carbon-perspective/1 の .carbon/perspective.json が入っています。インスタンス、ワークスペース、解決されたときのパースペクティブ、そして ref を示します。カットやスナップショットはスナップショット ID で、トランクやレーンは 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. 変更はレーンを通して戻す
"A download is read-only by design. Nothing in the archive is read back."(ダウンロードは設計上読み取り専用です。アーカイブの中身が読み戻されることはありません。)アーカイブの上で行った作業を戻すには、ツール呼び出しで書き込み、レーンに載せてランディングするか、インポートします。そうすれば各変更が自分の実行者と意図を持ちます。レーンについては Working in lanes を、書き出し元のカットの作り方は当社のガイド Carbon Forge でリリースを切り、GitHub にプッシュするをご覧ください。
ドキュメントが答えていないこと
- 書き出しの上限の大きさ。上限を超えたダウンロードは上限を示す一文とともに失敗しますが、ドキュメントは既定値を書いていません。
download_urlがどれだけの間有効か、書き出しがどれだけ保存されるか。- 誰が
.perspectivesを編集できるか。テンプレートの採用は管理者の操作ですが、ページ自体は "is edited like any other page"(他のページと同じように編集されます)とあり、編集者なら誰でもと読めます。 - アーカイブをマニフェストと照合するツール。形式は書かれていますが、照合は読み手自身のスクリプトに任されています。