# マニフェストリファレンス
beeuni.yaml v2 のすべてのキーと、デフォルト値、上限、検証ルール。
Canonical page: https://beeuni.ai/docs/ja/project/manifest
マニフェストは、プラットフォームがプロジェクトの正式な設定として扱うファイルです。このページでは、すべての `beeuni.yaml` (v2) キーについて、型、デフォルト値、プラットフォームによる検証方法を説明します。平易な説明については、[プロジェクト](/docs/ja/project)を参照してください。
## 2つの設定領域
Beeuni プロジェクトには、厳密に分離された2つの設定領域があります。
- **Beeuni の設定** — リポジトリのルートにある `beeuni.yaml` は、プロジェクトの環境、エージェント、ツール、コネクタ、トリガーを定義します。サンドボックステンプレートには独自の Dockerfile を指定できます。
- **エージェントの設定** — エージェントのファイル、スキル、ハーネスのファイル。サンドボックス内とローカル環境で、エージェントのハーネスが読み取ります。
| パス | 内容 |
| --- | --- |
| `beeuni.yaml` | マニフェスト。エージェントと各エージェントがアクセスできる内容、トリガー、コネクタ、環境変数、サンドボックステンプレート。 |
| `agents/.md` | 1つのエージェント。フロントマターとシステムプロンプトを含みます。`agents..file` がこのファイルを指定します。 |
| `skills//SKILL.md` | 1つのスキル。すべてのハーネスが読み込みます。 |
| `memory/` | プロジェクトのメモリ。 |
| `tools/.ts` | プロジェクトのツール。1つのモジュールにつき1つのツールです。`tools:` で宣言し、すべてのハーネスで実行します。[ツール](/docs/ja/project/tools)を参照してください。 |
| `harnesses/opencode/` |標準ハーネスのみが読み取るファイル。`opencode.jsonc`、`plugins/`、`tools/`、`commands/`。`opencode.config_dir` がこの場所を指定します。 |
2026-09 より前に作成されたプロジェクトでは、エージェントとスキルは `.beeuni/opencode/` に、メモリは `.beeuni/memory/` に置かれています。Beeuni はどちらの構成も読み取ります。
2つの領域をつなぐのは、エージェントの `.md` ファイルです。マニフェストのキー `agents.` は、`agents..file` が指定するファイル、または `file` が省略されている場合は `agents/.md` を対象にします。動作に関するフィールドはすべて、その `.md` ファイルのフロントマターと本文にのみ記述します。`beeuni.yaml` には記述しません。
- システムプロンプト
- `model`、`mode`
- `temperature`、`top_p`
- `steps`、`permission`
マニフェストの `agents:` ブロックで設定するのはガバナンスのみです。起動できるエージェントと、各エージェントがアクセスできる対象を指定します。バリデーターがこれを強制します。v2 のエージェントブロックに動作に関するフィールドが含まれていると、エージェント自身の `.md` ファイルを示すエラーで拒否します。
## 場所とバージョン
ルートに有効なマニフェストがあるリポジトリは、Beeuni プロジェクトです。`beeuni.yaml` (v2、YAML のみ) は新規プロジェクト用の現行フォーマットで、ウェブの「Create project」フローと `beeuni init` によって作成されます。`beeuni.toml` (v1) は既存プロジェクトで引き続き使用できますが、プラットフォームは v1 で新しい v2 機能を受け付けません。v1 のスキーマと v1 から v2 への移行手順については、[レガシー TOML](/docs/ja/project/legacy-toml)を参照してください。
`beeuni_version: 2` では YAML が必須です。`beeuni_version: 2` を宣言する `.toml` ファイルは検証に失敗します。`2` より大きなバージョンを宣言するマニフェストは、そのまま拒否されるため、プラットフォームが将来のフィールドを誤って読み取ることはありません。トップレベルの不明なキーは無視されるので、独自のメタデータをファイルに置くことができます。
`validateManifest()` は、`beeuni ship`、変更リクエストのマージチェック、`beeuni validate` を支える唯一のゲートです。どこでも同じルールが適用されるため、`main` にマージされる内容はすべて構造的に正しい状態になります。スキーマは公開されており、同じパッケージから生成されます。
- [`beeuni.v2.schema.json`](/schema/beeuni.v2.schema.json)
- [`beeuni.v1.schema.json`](/schema/beeuni.v1.schema.json)
- [`beeuni.schema.json`](/schema/beeuni.schema.json) (`beeuni_version` に応じて振り分け)
エディターで検証するには、`beeuni.yaml` を v2 スキーマに向けるか、CLI から取得してください。
```yaml
# yaml-language-server: $schema=https://beeuni.ai/schema/beeuni.v2.schema.json
beeuni_version: 2
```
```bash
beeuni schema --version 2
```
## 完全な例
```yaml
beeuni_version: 2
default_agent: beeuni
project:
name: my-project
description: What this project is.
env:
required: [DATABASE_URL]
optional: [STRIPE_API_KEY, WEBHOOK_SLACK_SECRET]
sandbox:
templates:
- slug: ml
name: ML Development
dockerfile: Dockerfile.ml
cpu: 4
memory: 16
opencode:
config_dir: harnesses/opencode
agents:
beeuni:
file: agents/beeuni.md
connectors: all
secrets: all
beeuni_permissions: all
skills: all
release-bot:
file: agents/release-bot.md
sandbox: ml
connectors: [github]
beeuni_permissions: [project.gitops.push]
secrets: [GITHUB_AGENT_TOKEN]
triggers:
- slug: daily-digest
type: cron
agent: beeuni
cron: '0 0 9 * * 1-5'
timezone: America/Los_Angeles
prompt: |
Summarize yesterday's commits. Open a CR against main.
```
## トップレベルのキー
| キー | 必須 | 備考 |
| --------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------ |
| `beeuni_version` | はい | `2` でなければなりません |
| `default_agent` | はい | 宣言済みで有効なエージェントを指定する必要があります |
| `imports` | いいえ | `triggers`、`connectors`、`agents`、`apps`、`tools` がこのマニフェストにマージされる、その他の YAML ファイルまたはディレクトリ。[`imports:`](#imports)を参照してください |
| `tools` | いいえ | すべてのセッションで使えるツール。ツール名 → リポジトリ相対のモジュールパス、または Beeuni ツールの場合は `beeuni:`。`tools` キーがある場合、セッションで使えるのはそこに列挙された Beeuni ツールのみです。すべてのハーネスで実行します。[`tools:`](#tools)を参照してください |
| `runtime` | いいえ | `"opencode"` (デフォルト) または `"pi"` — サンドボックス内でセッションが起動するエージェントハーネス。`pi` はサンドボックスデーモン内で実験的ハーネスをインプロセス実行し、同じエージェントの `.md` ファイルとスキルを読み取ります。この行がなくても、プロジェクトの `pi_harness` 機能フラグで実験的ハーネスを選択できます。実験的ハーネス には `llm_gateway` フラグが必要です。フラグがない場合、セッションは標準ハーネスを起動します。 |
| `harnesses.pi.packages` | いいえ | プロジェクトの実験的ハーネスセッションで読み込む実験的ハーネスパッケージ。[`harnesses:`](#harnesses)を参照してください |
| `pi.config_dir` | いいえ | `harnesses/pi`、存在する場合は続いて `.beeuni/pi`。実験的ハーネス ネイティブの `settings.json`、`extensions/`、`skills/`、`prompts/`。 |
| `project.name` / `project.description` | いいえ | 表示用メタデータ。プラットフォームはプロジェクトの表示名として `project.name` を読み取りません |
| `env.required` / `env.optional` | いいえ | 環境変数名。`required` は参考情報にすぎず、セッション開始時に強制されません |
| `sandbox` / `sandbox.templates` / `sandbox.default` | いいえ | サンドボックスイメージとハードウェア |
| `opencode.config_dir` | いいえ | デフォルトの `harnesses/opencode`、続いてレガシーの `.beeuni/opencode` |
| `triggers` | いいえ | cron、webhook、monitor トリガーのリスト |
| `connectors` | いいえ | コネクタ定義のリスト |
| `policy.default_mode` | いいえ | `allow_all` (デフォルト) または `risk`。プロジェクト全体に適用されるコネクタ承認モード |
| `agents` | はい | 名前からブロックへのガバナンスマップ。空にできません。`imports` がある場合、マップはインポートしたファイルに置くことができます |
## `imports:`
1つのマニフェストを複数の YAML ファイルに分割できます。`beeuni.yaml` が1画面に収まらなくなったときに使用します。複数行のプロンプトを含む30個のトリガー、チームごとのコネクタ、エージェントグループごとのファイルなどが該当します。
```yaml
# beeuni.yaml
beeuni_version: 2
default_agent: beeuni
imports:
- triggers/ # a directory: every .yaml and .yml file below it
- agents.yaml # a single file
agents:
beeuni:
connectors: all
```
```text
beeuni.yaml
agents.yaml
triggers/
reports/
weekly.yaml
monthly.yaml
dockets/
freedom-forever.yaml
```
```yaml
# triggers/reports/weekly.yaml
triggers:
- slug: weekly-report
name: Cross-Sector Weekly Report
type: cron
agent: galileo
cron: "0 15 * * 0"
prompt: |-
Build the weekly report.
```
ルートファイルとそのインポートは、1つのプロジェクト設定を構成します。あるファイルのトリガーから、別のファイルで宣言されたエージェントを指定できます。
**ルール**
1. パスはリポジトリのルートからの相対パスです。`..`、絶対パス、glob は拒否されます。
2. ディレクトリをインポートすると、その配下のすべての階層から`.yaml`ファイルと`.yml`ファイルをすべてパス順に取得します。それ以外のファイルはスキップされます。
3. インポートしたファイルでは、`triggers`、`connectors`、`agents`、`apps`、`tools`、`imports`を宣言します。その他のキー（`beeuni_version`、`default_agent`、`runtime`、`project`、`env`、`opencode`、`sandbox`、`policy`、`policies`）はルートファイルに残します。インポートしたファイルでこれらのキーを設定すると、検証に失敗します。
4. インポートしたファイルから、さらにファイルをインポートできます。上限は深さ8階層、ファイル数200です。循環参照はエラーになります。同じファイルに複数の経路で到達した場合、マージは1回だけ行われます。
5. 1つの名前につき1つのファイルです。トリガーのスラッグ、コネクターのスラッグ、エージェント名、アプリ名、ツール名が2つのファイルで宣言されている場合、両方のファイル名を示すエラーになります。黙って上書きされることはありません。
6. エントリは、インポート元のファイル、その後に記載順でインポート先のファイルという順序でマージされます。
インポートに不備があると、YAML 構文エラーと同様にマニフェスト全体が失敗します。`beeuni validate`、`beeuni ship`、および変更リクエストのマージチェックは、`main`に到達する前にすべて報告します。
```text
imports: triggers "weekly-report" is declared in both triggers/a.yaml and triggers/b.yaml — one name, one file
```
**編集はエントリを宣言しているファイルに反映されます。** ダッシュボード、API、または`beeuni triggers enable|disable|rm`が、インポートしたファイルで宣言されたトリガー、コネクター、エージェント、アプリを変更すると、そのファイルだけが書き込まれます。ルートファイルは書き換えられません。新しいエントリはルートファイルに書き込まれます。そこに置きたい場合は、手動でインポートしたファイルに移動してください。
`imports`には`beeuni.yaml`が必要です。`beeuni.toml`マニフェストでは、このキーは無視されます。
## `tools:`
セッションで使用できるツールを名前で指定します。値は次の2種類のいずれかです。
| 形式 | 意味 |
| --- | --- |
| `beeuni:` | Beeuni が保守する Beeuni ツール（`web_search`、`image_search`、`scrape_webpage`、`memory`、`show`）。キーは``である必要があります。 |
| リポジトリ相対のモジュールパス | プロジェクト独自のツール。任意のフォルダーに置けます。Beeuni ツールの名前で指定すると、そのモジュールが Beeuni ツールに置き換わります。 |
```yaml
tools:
web_search: beeuni:web_search
image_search: beeuni:image_search
scrape_webpage: beeuni:scrape_webpage
memory: tools/memory.ts # replaces the Beeuni memory tool
lookup_order: tools/lookup_order.ts
crm_note: integrations/crm/note.ts
```
標準ハーネス と実験的ハーネスは同じモジュールを実行します。モジュールの仕様、`beeuni tools ls`、
`beeuni tools eject`、および`harnesses/opencode/tools/`からの移行については、
[Tools](/docs/ja/project/tools)を参照してください。
**選択ルール。**
- ルートファイルにもインポートしたファイルにも`tools`キーがない場合、セッションでは5つすべての Beeuni ツールを使用できます。このリストができる前に作成されたすべてのプロジェクトでも、引き続き利用できます。
- `tools`キーがある場合は、空でも（`tools: {}`、またはすべての行を削除した`tools:`の場合でも）、セッションで使用できるのは、`beeuni:`またはモジュールパスとして記載された Beeuni ツールだけです。インポートしたファイル内の`tools`キーも対象になります。
`beeuni:`行を削除すると、そのツールがすべてのエージェントから削除されます。特定のエージェントに限定するには、[`agents..tools`](/docs/ja/project/tools#who-may-use-which-tool)を使用してください。
**エラー。**
- 名前は snake_case です: `^[a-z][a-z0-9_]{0,63}$`。
- ハーネスのツール名（`bash`、`read`、`write`、`edit`、`apply_patch`、`glob`、`grep`、`list`、`task`、`question`、`todowrite`、`webfetch`、`websearch`、`skill`、`lsp`、`invalid`、`execute`、`plan_exit`、`pty_*`）はエラーになります。
- パスの末尾は`.ts`、`.js`、`.mts`、`.mjs`、`.cts`、または`.cjs`である必要があります。`/`または`-`で始めたり、`.`または`..`のセグメントを含めたりすることはできません。
- 別のキーの下にある`beeuni:`はエラーになります。たとえば、Beeuni ツール名の下にある`web_search: beeuni:image_search`の場合:
```text
tools.web_search: `beeuni:web_search`（Beeuni ツール）または置き換え先となる、.ts もしくは .js モジュールへのリポジトリ相対パス（例: `tools/web_search.ts`）である必要があります。
```
- Beeuni ツールではない名前に対する`beeuni:`はエラーになります。例: `web_serch: beeuni:web_serch`:
```text
tools.web_serch: .ts もしくは .js モジュールへのリポジトリ相対パス（例: `tools/web_serch.ts`）である必要があります。`beeuni:`は、次の Beeuni ツールをそれぞれの名前で指定します: `web_search: beeuni:web_search`、`image_search: beeuni:image_search`、`scrape_webpage: beeuni:scrape_webpage`、`memory: beeuni:memory`、`show: beeuni:show`。
```
- `beeuni validate`は、宣言されたモジュールが存在しない場合も報告します。`beeuni:`の値にはファイルは必要ありません。
**警告。** 警告によって`beeuni validate`が失敗することはありません。
- 5つの Beeuni ツールのいずれも指定していない`tools`キー:
```text
tools: このプロジェクトのセッションでは Beeuni ツール（web_search、image_search、scrape_webpage、memory、show）を使用できません。1つを残すには`: beeuni:`を追加してください。
```
独自ツールを初めて追加したときに、誤って5つのツールを削除してしまうケースを検出します。
- エージェントの`tools`で、プロジェクトが読み込んでいない Beeuni ツールを指定している場合:
```text
agents.beeuni.tools: 「show」は、このプロジェクトが読み込んでいない Beeuni ツールです。トップレベルの`tools`の下に`show: beeuni:show`を追加するか、ここから削除してください。
```
## `project:`
任意のユーザー向けメタデータ: `name`と`description`。プラットフォームはこのテーブルを一切参照しません。プロジェクトの表示名は、プロジェクト独自のデータベースレコードから取得されます。リポジトリを読む人向けのドキュメントとして扱ってください。
## `env:`
セッションで必要となる環境変数名を宣言します。値はダッシュボードの「Environment variables」ページに保存し、マニフェスト内に直接記述することはありません。プラットフォームはセッション開始時に値を復号し、通常の環境変数として注入します。
```yaml
env:
required: [DATABASE_URL]
optional: [STRIPE_API_KEY]
```
| フィールド | 型 | 備考 |
| ---------- | ---------- | -------------------------------------------------------------------------------------------------------- |
| `required` | `string[]` | 参考情報です。ダッシュボードではユーザーに入力を求めますが、値がなくてもセッション開始はブロックされません。 |
| `optional` | `string[]` | 設定されていればセッションで使用できます。未設定でも問題ありません。 |
環境変数名は`^[A-Z_][A-Z0-9_]*$`に一致する必要があります。Secrets Manager では名前の長さが64文字までに制限されています。ここではそれより長い名前も解析されますが、値を設定することはできません。`BEEUNI_`で始まる名前にも値を設定できません。名前は64文字以内にし、`BEEUNI_`プレフィックスを避けてください。詳細な仕様については[Secrets](/docs/ja/project/secrets)を参照してください。
## `sandbox:`と`sandbox.templates`
起動可能なサンドボックスイメージに名前を付けて一覧表示します。任意項目で、エントリがなければ、すべてのセッションはプラットフォームのデフォルトイメージで起動します。各テンプレートには、`dockerfile`（リポジトリ相対）または`image`（タグまたはダイジェストを指定した公開 Docker リファレンス）のどちらか一方を指定する必要があります。
```yaml
sandbox:
templates:
- slug: ml
name: ML Development
dockerfile: Dockerfile.ml
cpu: 4
memory: 16
disk: 50
```
| フィールド | 型 | デフォルト | 備考 |
| ------------ | ------ | ------------------- | --------------------------------------------------------------------------------- |
| `slug` | string | — | 必須。プロジェクトごとに一意である必要があります。`default` は予約済みです。 |
| `name` | string | slug | ダッシュボードの選択画面に表示するラベル。 |
| `dockerfile` | string | — | リポジトリ相対パス。`image` とは相互排他的です。 |
| `image` | string | — | 公開 Docker イメージ。タグまたはダイジェストを固定する必要があります。`dockerfile` とは相互排他的です。 |
| `entrypoint` | string | runtime layer's own | コンテナのエントリポイントを上書きします。 |
| `cpu` | int | provider default | vCPU コア数。範囲: 1～32。 |
| `memory` | int | provider default | GiB 単位の RAM。範囲: 1～128。 |
| `disk` | int | provider default | GiB 単位のディスク容量。範囲: 1～500。 |
| `container_runtime` | bool | `false` | ブリッジ + オーバーレイネットワークを使用してサンドボックス内で Docker を実行します。[Runtime](/docs/ja/work/runtime#docker-in-the-sandbox) を参照してください。 |
各値は正の整数である必要があります。最小値未満の値は、エラーとなり検証に失敗します。最大値を超える値は警告付きで受け付けられ、その後、実行時に上限値へ丸められます。GPU はサポートされていません。`gpu` を宣言すると、エラーではなく警告が生成されます。ランタイムレイヤーがイメージに追加する内容については、[Runtime](/docs/ja/work/runtime) を参照してください。
### `sandbox.default`
`sandbox` に `default` を設定すると、1 つのテンプレートをプロジェクト全体のデフォルトにできます。その後、すべてのセッション、トリガー、チャネルは slug を指定せずにそのテンプレートで起動します。
```yaml
sandbox:
default: dev
templates:
- slug: dev
dockerfile: Dockerfile.dev
```
`default` には、このマニフェストで宣言されたテンプレート、またはプラットフォームイメージを表す予約値 `"default"` を指定する必要があります。
エージェントは `agents..sandbox` を使用して環境を選択できます。値には、マニフェストまたはダッシュボードのテンプレート、あるいは `"default"` を指定する必要があります。
```yaml
agents:
researcher:
sandbox: ml
```
セッションテンプレートは次の順序で解決されます。
1. 明示的に指定されたセッション `sandbox_slug`。
2. 選択されたエージェントの `sandbox`。
3. プロジェクトの `sandbox.default`。
4. プラットフォームの `"default"`。
Cron トリガー、Webhook トリガー、スケジュール、チャネルは、選択されたエージェントのテンプレートを使用します。
仕様の変更（`cpu`、`memory`、`disk`、`container_runtime`、またはイメージ自体の変更）により、プロジェクトのスナップショットが再構築されます。新しいサイズは実行中のセッションではなく、次のセッションから適用されます。
## `opencode:`
標準ハーネス 設定ディレクトリの場所。任意ですが、デフォルト値があります。
```yaml
opencode:
config_dir: harnesses/opencode
```
| フィールド | 型 | デフォルト | 備考 |
| ------------ | ------ | ----------------------------------------------- | ------------------------ |
| `config_dir` | string | `harnesses/opencode`、次に `.beeuni/opencode` | リポジトリ相対ディレクトリ。 |
`config_dir` が設定されていない場合、Beeuni は `harnesses/opencode` と `.beeuni/opencode` のうち、`opencode.json` または `opencode.jsonc` を含む最初のディレクトリを使用します。そのディレクトリには、標準ハーネス だけが読み取るファイル（`opencode.jsonc`、`plugins/`、`tools/`、`commands/`）が格納されます。エージェントとスキルはリポジトリルートの `agents/` と `skills/` に配置します。`opencode.jsonc` は、プラグイン、MCP サーバー、プロバイダー、権限に関する標準ハーネスネイティブのレジストリとして使用します。これらの設定をマニフェストに重複して記述しないでください。[Agents](/docs/ja/project/agents) を参照してください。
## `harnesses:`
ハーネスごとの設定。`pi.config_dir` は、実験的ハーネス ネイティブ設定を含むリポジトリ相対ディレクトリを指します（デフォルト: `harnesses/pi`、次に `.beeuni/pi`）。ディレクトリは実験的ハーネスの起動時にインポートされます。`pi.packages` は別の設定で、エージェントごとのマニフェストの `harnesses.pi.packages` からパッケージをインストールします。現在存在するパッケージキーは 1 つです。`pi.packages` は、このプロジェクトのすべての実験的ハーネスセッションが読み込む実験的ハーネスパッケージ（`runtime: pi`、または `pi_harness` フラグ）です。パッケージとは packages にあるものを指し、拡張機能（ツール、フック、コマンド）や、パッケージに含まれるスキルとプロンプトが該当します。
```yaml
runtime: pi
harnesses:
pi:
packages:
- npm:pi-web-access@0.30.0 # pinned extension version
- source: npm:pi-mcp-adapter@2.36.0
extensions: ["extensions/*.ts"] # load only these files of the package
skills: [] # load none of its skills
- ./harnesses/pi/audit.ts # an extension file in this repository
```
| エントリ形式 | 意味 |
| --- | --- |
| `npm:@` | 正確なバージョンを指定した npm パッケージ。範囲指定またはバージョンの欠落は検証に失敗します。 |
| `./` | このリポジトリ内の拡張ファイルまたはパッケージディレクトリ。`..` を使用してリポジトリ外を参照することはできません。 |
| `{ source, extensions, skills, prompts, themes }` | 同じソースに実験的ハーネス独自の include/exclude フィルターを適用したもの。フィルターを省略するとすべてが読み込まれ、`[]` では何も読み込まれません。 |
エントリは最大 20 件です。Git ソースは拒否されます。
### エージェントごとの設定
エージェントは、`agents..harnesses` の下で独自のパッケージを追加し、トップレベルのパッケージを除外できます。
```yaml
harnesses:
pi:
packages: [npm:pi-web-access@0.30.0] # every agent
agents:
researcher:
harnesses:
pi:
packages: [npm:@juicesharp/rpiv-todo@2.11.0] # researcher only
reviewer:
harnesses:
pi:
exclude: [pi-web-access] # reviewer loads no web tools
```
- エージェントのパッケージは、トップレベルのリストからその `exclude` を除き、独自の `packages` を加えたものです。
- トップレベルにも記載されているパッケージについてエージェントがエントリを指定した場合、そのエージェントではトップレベルのエントリが置き換えられます（別のバージョンや別のフィルターを指定できます）。
- `exclude` には、トップレベルのリストに記述されているパッケージ名（`pi-web-access`、`@scope/name`）または `./` パスを指定します。バージョンは指定しません。
- 異なるパッケージリストごとに一度だけビルドされます。同じリストを持つエージェントはビルドを共有します。
- パッケージは、セッションを開始するエージェントに属します。別のエージェントが `task` ツールで起動したサブエージェントは、標準ワークスペースツール（`bash`、`read`、`write`、`edit`、`glob`、`grep`）のみを使用し、独自のパッケージも親のパッケージも使用しません。ただし、親の拡張フックはその呼び出しに適用されます。そのエージェントでセッションを開始すると、そのパッケージを使用できます。
パッケージがセッションに届くまでの流れ:
1. このリストを編集する変更リクエストをマージすると、サンドボックスプラットフォーム向けに、インストールスクリプトを無効にしてパッケージが一度ビルドされます。各拡張機能は、1 つの minify 済みファイルに事前ビルドされます。ビルドでは、そのファイルにすでに含まれているコード、型宣言、ソースマップ、ルートの README と CHANGELOG を除き、パッケージのその他のファイルが保持されます。同じリストを持つプロジェクトはビルドを共有します。
2. 新しいセッションまたは再起動したセッションは、リポジトリのクローン中にビルドをダウンロードし、各拡張機能を直接読み込みます。セッションが `npm install` を実行したり、パッケージをコンパイルしたりすることはありません。
3. 事前ビルドできないパッケージ（たとえば、`pi.extensions` が glob を使用するもの）も動作します。その場合、セッションはインストール済みパッケージから読み込むため、時間がかかります。パッケージのコードがビルドで除外されたファイルのいずれかを読み取る場合は、そのエントリに `extensions` フィルターを指定してください。セッションはそのパッケージもインストール済みパッケージから読み込みます。
4. ビルドの存在前に開始したセッションは、プロジェクトパッケージなしで起動し、ビルドを開始します。次のセッションからパッケージが使用可能になります。
Beeuni は、すべての実験的ハーネスセッションにシステムパッケージ一式もインストールします。同じパッケージについてプロジェクトのエントリがある場合、システムバージョンが置き換えられます。リポジトリには `.pi/extensions/*.ts` に実験的ハーネスネイティブ拡張機能を配置することもでき、実験的ハーネス はマニフェストのエントリなしでそれらを読み込みます。
拡張機能はターミナル UI なしで実行されます。ツール、フック、コマンドは動作しますが、ターミナル専用のウィジェットは何もしません。
## `triggers:`
Cron、Webhook、モニター定義のリスト。各エントリは、`prompt` を最初のメッセージとして実行するセッションを起動します。
```yaml
triggers:
- slug: daily-digest
type: cron
cron: '0 0 9 * * 1-5'
prompt: Summarize yesterday's commits.
```
| フィールド | 必須 | デフォルト | 備考 |
| -------------- | --------------------- | --------------------- | ----------------------------------------------------------------------------------------------------- |
| `slug` | はい | — | `[a-z0-9][a-z0-9_-]{0,127}`。トリガー間で一意である必要があります。 |
| `type` | はい | — | `cron`、`webhook`、または`monitor`（実験的）。 |
| `prompt` | はい | — | 空でないこと。テンプレートに対応しています。 |
| `name` | いいえ | slug | 表示用ラベル。 |
| `agent` | いいえ | `default_agent` | `agents:`内のキーを指定する必要があります。省略すると`default_agent`が使用されます。`default`というリテラルは記述しないでください。 |
| `enabled` | いいえ | `true` | `false`はエントリーをスキップします。 |
| `model` | いいえ | 発火時に解決 | ワイヤ形式は`provider/model`です。発火したセッションのモデルを固定します。[Models](/docs/ja/project/models)を参照してください。 |
| `session_mode` | いいえ | `fresh` | `fresh`、`reuse`、`pinned`、または`keyed`。 |
| `session_id` | `pinned`では必須 | — | 再プロンプトする対象の正確なセッション。 |
Cronトリガーには、`cron`（6フィールド式）または`run_at`（一度限りのISO-8601タイムスタンプ）のいずれか一方と、IANA名の`timezone`が必要です。Webhookトリガーには、`broker`配信と`connector`コンシューマーを使用するシークレットの名前である`secret_env`が必要です。Monitorトリガーには、`run`（リポジトリ相対コマンド）と`mode`（`poll`または`stream`）が必要で、cronフィールドとwebhookフィールドはすべて拒否されます。全フィールドのリファレンス、認証情報の設定、ペイロードのテンプレート、エンドポイント、セッション戦略については、[Triggers](/docs/ja/connect/triggers)を参照してください。
## `connectors:`
エージェントが呼び出せる外部ツールのリストです。定義はgitに保存され、認証情報はプラットフォームに保存されます。マニフェストには保存されません。概念モデルについては、[Connectors](/docs/ja/connect/connectors)を参照してください。
```yaml
connectors:
- slug: gmail-read
name: Gmail read only
provider: pipedream
app: gmail
authorization_strategy: user
policies:
- match: search_email
action: always_run
```
| フィールド | 必須 | 備考 |
| ------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `slug` | はい | `[a-z0-9][a-z0-9_-]{0,127}`。コネクター間で一意である必要があります。 |
| `provider` | はい | `pipedream`、`mcp`、`openapi`、`postman`、`graphql`、`http`、または`channel`。 |
| `name` | いいえ | 表示名。デフォルトはslugです。 |
| `authorization_strategy` | いいえ | `project`または`user`。省略時のデフォルトは`project`です。プロジェクト戦略では、アクティブなプロジェクト接続を使用します。ユーザー戦略では、操作中のメンバーの接続のみを使用します。 |
| `enabled` | いいえ | デフォルトは`true`です。 |
| `credential` | いいえ | `shared`のみサポートされています。廃止された`per_user`モードはハードエラーになります。 |
| `sensitive` | いいえ | デフォルトは`false`です。`true`にすると、読み取りも含め、一致しないアクションのデフォルトは`require_approval`になります。明示的なプロジェクトルールとコネクタールールは引き続き優先して解決されます。 |
プロバイダー固有のフィールド:
| プロバイダー | 必須フィールド | 備考 |
| ----------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `pipedream` | `app` | `account`は任意で、デフォルトはslugです。 |
| `mcp` | `url` | `transport`: `http`（デフォルト）または`sse`。 |
| `openapi` | `spec` | URLまたはリポジトリ相対パス。 |
| `postman` | `spec` | Collection JSONのURLまたはパス、`.postman/api`マニフェスト、またはPostmanワークスペースのURL。 |
| `graphql` | `endpoint` | `spec`は任意（SDL）。 |
| `http` | `base_url` | `spec`は任意です。 |
| `channel` | `platform` | `slack`、`teams`、`email`、または`voice`。 |
| `computer` | — | APIで管理されます。手動では宣言できません。接続されたコンピューターは、それぞれアカウントの1つです。[Computers](/docs/ja/connect/computers)を参照してください。 |
`channel`コネクターは、手動でエントリーを記述する必要がほとんどありません。ダッシュボードからチャンネルを接続すると、自動的に作成されます。[Slack & channels](/docs/ja/connect/slack)を参照してください。`beeuni_slack`、`beeuni_teams`、`beeuni_email`、`computer`のslugはプラットフォーム専用です。別のプロバイダーで使用すると、検証エラーになります。`computer`コネクターは、最初のメンバーがコンピューターを接続したときに作成されます。マシンIDはアカウントのコントロールプレーン上のIDであり、マニフェストに含めてはならないためです。
`connectors.auth`：`pipedream`以外のプロバイダーでは任意です。`type`は`bearer`、`basic`、`custom`、`api_key`、`oauth1`、`hmac`、`aws_sigv4`、`mtls`、または`none`（デフォルト）です。`oauth1`は`openapi`、`postman`、`http`プロバイダーに限定されます。`in`は`header`（デフォルト）、`query`、または`cookie`です。`type`が`custom`または`api_key`の場合、`name`が必要です。
`connectors.policies`：`{match, action}`ペアのリストです。`match`はツール名に対するglobです。`action`は`always_run`、`require_approval`、または`block`です。ポリシーはコネクターに属します。そのコネクター下のすべての接続で同じポリシーが使用されます。
`policy.default_mode`：`connectors:`とは別のトップレベルキーで、プロジェクト全体のコネクター承認モードを設定します。`allow_all`（デフォルト。一致しないすべてのツールを実行）または`risk`（書き込みおよび破壊的な、一致しない呼び出しに承認を要求）を指定します。`beeuni connectors policy set --default `で設定します — [CLI](/docs/ja/cli)を参照してください。
## チャネル
v2ではスキーマから`channels:`が削除されています。チャネルからエージェントへのルーティング（現在はSlack、Microsoft Teams、メール、音声）は、宣言的な設定ではなく、稼働中の運用状態です。ダッシュボードのChannelsページまたはチャットコマンドから設定します。これは認証情報をgitから遠ざける境界と同じです。チャネルを接続すると、エージェントが呼び出すための`provider: channel`を含む`connectors`エントリが引き続き作成されます。[Slack & channels](/docs/ja/connect/slack)を参照してください。v1の`[[channels]]`テーブルについては、[Legacy TOML](/docs/ja/project/legacy-toml)で説明しています。
## `agents:`
エージェント名をキーとする、名前からブロックへのマップです。このマップはガバナンス専用であり、エージェントがアクセスできる対象を許可するものであって、エージェントが発言または実行する内容を許可するものではありません。
このブロックは**2つあるバインディングの2つ目**です。プリンシパルはBeeuniからロールを取得し、エージェントはここで宣言されたBeeuni権限を追加で持ちます。セッションで実行できるのは、両方が許可する操作だけです。[1つの用語体系、2つのバインディング](/docs/ja/accounts#one-vocabulary-two-bindings)を参照してください。
```yaml
default_agent: beeuni
agents:
beeuni:
file: agents/beeuni.md
connectors: all
secrets: all
beeuni_permissions: all
skills: all
release-bot:
file: agents/release-bot.md
connectors: [github]
connectors_required: [github]
beeuni_permissions: [project.gitops.push]
secrets: [GITHUB_AGENT_TOKEN]
```
| フィールド | デフォルト | 注記 |
| --------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| _(マップキー)_ | — | `[a-z0-9][a-z0-9_-]{0,127}`で、プロジェクトごとに一意です。`file`がない場合は、`.md`ファイル名でもあります。 |
| `file` | `agents/.md` | エージェントの`.md`へのリポジトリ相対パス。[エージェントファイル](#the-agent-file)を参照してください。 |
| `enabled` | `true` | `false`はエージェントを未宣言として扱います。プラットフォームは起動しません。 |
| `connectors` | `none` | このエージェントが呼び出せるコネクタのスラッグ。`all`はすべてのコネクタを意味します。 |
| `connectors_required` | `none` | 非推奨：解析されますが無視されます。コネクターに接続があるかどうかでサンドボックスの起動を制御することはなくなりました。何も接続されていないコネクターへの呼び出しは、接続リンク付きの`connector_not_connected`を返します。指定する場合も`connectors`のサブセットである必要があります。 |
| `secrets` | `none` | このエージェントがサンドボックスの環境変数として受け取るプロジェクトシークレット。v1の`env`から名称変更されました。 |
| `beeuni_permissions` | `none` | CLI、API、またはgitを通じて、このエージェントが行使できるBeeuni権限（プロジェクト操作）。`all`はすべてのプロジェクト権限を意味しますが、エージェントの上限ロールによる制限を受け、人間専用の権限は決して含みません。`beeuni_cli`は非推奨の表記です。引き続き受け付けられますが、検証警告が表示されます。両方に異なる値を設定するとエラーになります。 |
| `skills` | `none` | このエージェントが読み込めるスキル。 |
| `apps` | `none` | Appが`restricted`または`private`のときに、このエージェントが開けるBeeuni Appのスラッグ。`all`はプロジェクト内のすべてのAppを意味します。[エージェントとApp](/docs/ja/feature-flags/apps#agents-and-apps)を参照してください。 |
| `tools` | `all` | このエージェントが使用できるツール：ハーネス、Beeuni、プロジェクトツール。`all`、`none`、リスト（記載されたもののみ）、または`{ exclude: [...] }`（記載されたもの以外すべて）を指定できます。以前のマップ形式`{ bash: false }`も引き続き使用できます。上記の権限付与とは異なり、`tools`を省略するとすべてのツールを意味します。[どのユーザーがどのツールを使用できるか](/docs/ja/project/tools#who-may-use-which-tool)を参照してください。 |
| `repository_access` | `true` | 新しいセッションがプロジェクトリポジトリを受け取るかどうか。`false`は、リポジトリの配布とセッション認証情報によるリポジトリへのアクセスを無効にします。既存のセッションでは保存済みのポリシーが維持されます。 |
v2はデフォルトで拒否します。宣言されたエージェントで`connectors`、`secrets`、`beeuni_permissions`、`skills`、または`apps`を省略すると、`none`として解決されます。上記のstarterの`beeuni`エージェントのように、エージェントに必要な権限をすべて明示的に付与してください。v1から移行するプロジェクトでは、すべてを手動で再付与する必要があります。v1では`env`（シークレット）を省略すると`all`がデフォルトになりますが、これはv2とは逆です。
`connectors_personal`は`connectors_required`の非推奨の入力エイリアスとして残っています。新しいマニフェストでは`connectors_required`を使用してください。コネクターの`authorization_strategy`によって、認可がプロジェクト所有かメンバー所有かが決まります。
`beeuni_permissions`の権限付与元は、プロジェクトスコープの固定された権限セット（`project.read`、`project.gitops.push`、`project.gitops.merge`、`project.gitops.ref.any`、`project.trigger.*`、`project.secret.*`、`project.connector.*`など）です。アカウントスコープの権限（`member.*`、`billing.*`、`project.create`）をエージェントに付与することはできません。セッション内から`beeuni validate --scopes`を実行すると、現在付与可能な一覧が出力されます。
### エージェントファイル
`agents..file`は、リポジトリルートからの相対パスでエージェントの`.md`を指定します。
```yaml
agents:
support:
file: agents/support.md
```
- パスは`.md`で終わる必要があります。
- パスは`/`または`-`で始めてはなりません。`.`または`..`セグメントや空のセグメントを含めてはなりません。
- 各セグメントには、文字、数字、`_`、`-`、`.`、スペースのみを使用できます。
- `file`を省略すると、Beeuniはまず`agents/.md`、次に`.beeuni/opencode/agents/.md`を読み取ります。`opencode.config_dir`が設定されている場合、2番目のパスは`/agents/.md`です。
- ダッシュボードが`.md`を持つエージェントを保存すると、そのパスを指定した`file`を書き込みます。
- APIは`file`を変更するリクエスト（`400`、コード`invalid_config`）を拒否します。エージェントを移動するには、その`.md`を移動し、同じコミットで`beeuni.yaml`内の`file`を更新してください。
`beeuni validate`と変更リクエストのマージチェックは、無効な`file`を`agents..file`のエラーで拒否します。
## 設定変更が反映されるタイミング
- マニフェスト、`agents/`、`skills/`、または標準ハーネス設定ディレクトリの編集は、変更リクエストが `main` にマージされた後にのみ適用されます。セッションとトリガーは、セッションブランチではなくデフォルトブランチを読み込みます。
- トリガーの cron または webhook の変更は、マージから数秒以内にスケジューラーに反映されます。
- サンドボックスのイメージまたはハードウェアを変更すると、スナップショットが再構築されます。新しい仕様は次のセッションから適用され、現在のセッションには適用されません。
- ダッシュボードでシークレット値を変更すると、サンドボックスの作成時に解決されます。次のセッションから適用され、実行中のセッションには適用されません。
## ラウンドトリップのルール
ダッシュボードでの編集は、エントリを宣言するファイル（`beeuni.yaml`または[インポートされたファイル](#imports)）に対する読み取り・変更・書き込みです。UI とセッション内での編集の差分をクリーンに保つには、次のようにします。
1. `beeuni_version`を最初のキーにします。
2. トリガーエントリ内のフィールドは、`slug`、`name`、`type`、`agent`、`enabled`の順に並べ、その後に種類固有のフィールドを置き、最後に`prompt`を置きます。
3. シークレットを設定する前に webhook トリガーを追加する場合は、シークレット名を`env.optional`に記載します。値を設定するまでは、トリガーを`enabled: false`のままにします。
### リポジトリへのアクセス
プロジェクトのソースファイルを必要としないエージェントでは、`agents..repository_access`を`false`に設定します。
それでもサンドボックス内のファイルを作成し、付与されたツール、シークレット、コネクターを使用できます。
リポジトリを必要とするエージェントでは、`true`に設定します。Git の権限は別途管理されます。
エージェントエディターの **Workspace → Project repository access** でこの設定を変更します。
この設定は新しいセッションに適用されます。既存のセッションでは、ランタイムの置き換え後も含め、保存済みのポリシーが維持されます。
```yaml
agents:
support:
repository_access: false
engineer:
repository_access: true
```
非推奨の`workspace`フィールドは引き続き読み取り可能です。`branch`は`true`を意味し、`runtime`は`false`を意味します。
従来の`read`設定では、フィールドを明示的なブール値に置き換えるまで、セッションの作成が引き続き拒否されます。
リポジトリへの読み取り専用アクセスモードはありません。旧フィールドと新フィールドの値が競合する場合は拒否されます。
エディターと SDK は`repository_access`を送信します。アクセスを無効にした場合、API は互換性ミラーとして`workspace: runtime`も保存します。これにより、ロールアウトまたはロールバック中も、古い API レプリカで制限が維持されます。API の読み取り結果にはミラーは含まれません。`repository_access`のみを使用する手書きのマニフェストには、更新済みの API が必要です。