--- title: "Referenz zum Manifest" description: "Alle Schlüssel von beeuni.yaml v2 mit Standardwerten, Grenzwerten und Validierungsregeln." --- Das Manifest ist die Datei, die die Plattform als maßgeblich für ein Projekt behandelt. Auf dieser Seite sind alle Schlüssel von `beeuni.yaml` (v2), ihr Typ, ihr Standardwert und die Validierung durch die Plattform aufgeführt. Eine leicht verständliche Version findest du unter [Dein Projekt](/docs/de/project). ## Zwei Konfigurationsbereiche Ein Beeuni-Projekt hat zwei Konfigurationsbereiche mit strikt getrennter Zuständigkeit. - **Beeuni-Konfiguration** — `beeuni.yaml` im Repo-Stammverzeichnis definiert die Projektumgebung, Agenten, Tools, Connectoren und Trigger. Sandbox-Vorlagen können auf eine eigene Dockerfile verweisen. - **Agentenkonfiguration** — die Agentendateien, Skills und Harness-Dateien. Diese liest das Agenten-Harness, in der Sandbox und lokal. | Pfad | Inhalt | | --- | --- | | `beeuni.yaml` | Das Manifest: Agents und worauf jeder zugreifen darf, Trigger, Connectors, env, Sandbox-Vorlagen. | | `agents/.md` | Ein Agent: Frontmatter und System-Prompt. `agents..file` gibt seinen Namen an. | | `skills//SKILL.md` | Ein Skill. Jedes Harness lädt ihn. | | `memory/` | Das Projektspeicher. | | `tools/.ts` | Projekt-Tools, jeweils ein Modul. `tools:` deklariert sie; jedes Harness führt sie aus. Siehe [Tools](/docs/de/project/tools). | | `harnesses/opencode/` | Dateien, die nur Standard-Harness liest: `opencode.jsonc`, `plugins/`, `tools/`, `commands/`. `opencode.config_dir` verweist hierher. | Bei Projekten, die vor 2026-09 erstellt wurden, befinden sich Agents und Skills unter `.beeuni/opencode/` und der Speicher unter `.beeuni/memory/`. Beeuni liest beide Layouts. Die Verbindung zwischen den beiden Bereichen ist die Datei `.md` des Agents. Ein Manifest-Schlüssel `agents.` steuert die Datei, die `agents..file` angibt, oder `agents/.md`, falls `file` fehlt. Alle Verhaltensfelder befinden sich ausschließlich im Frontmatter und Text dieser Datei `.md`, niemals in `beeuni.yaml`: - System-Prompt - `model`, `mode` - `temperature`, `top_p` - `steps`, `permission` Der `agents:`-Block des Manifests legt ausschließlich die Governance fest: welche Agents gestartet werden dürfen und worauf jeder zugreifen darf. Der Validator setzt diese Regeln durch. Er weist einen v2-Agentenblock zurück, der Verhaltensfelder enthält, und gibt eine Fehlermeldung aus, die auf die eigene Datei `.md` des Agents verweist. ## Speicherort und Versionen Jedes Repo mit einem gültigen Manifest im Stammverzeichnis ist ein Beeuni-Projekt. `beeuni.yaml` (v2, nur YAML) ist das aktuelle Format für neue Projekte, die über den Webablauf „Create project“ oder mit `beeuni init` erstellt werden. `beeuni.toml` (v1) funktioniert weiterhin für bestehende Projekte, aber die Plattform akzeptiert dafür keine neuen v2-Funktionen. Unter [Legacy-TOML](/docs/de/project/legacy-toml) findest du das v1-Schema und die Schritte zur Migration von v1 zu v2. `beeuni_version: 2` erfordert YAML — eine `.toml`-Datei, die `beeuni_version: 2` deklariert, besteht die Validierung nicht. Ein Manifest, das eine höhere Version als `2` angibt, wird direkt zurückgewiesen, sodass die Plattform ein zukünftiges Feld niemals stillschweigend falsch interpretiert. Unbekannte Schlüssel auf oberster Ebene werden ignoriert, sodass du eigene Metadaten in der Datei ablegen kannst. `validateManifest()` ist das einzige Nadelöhr für `beeuni ship`, die Merge-Prüfung von Änderungsanfragen und `beeuni validate`. Überall gelten dieselben Regeln, sodass alles, was in `main` gemergt wird, strukturell korrekt ist. Das Schema ist öffentlich und wird aus demselben Paket generiert: - [`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) (verzweigt anhand von `beeuni_version`) Verweise in einem `beeuni.yaml` auf das v2-Schema, um die Validierung im Editor zu aktivieren, oder rufe es über die CLI ab: ```yaml # yaml-language-server: $schema=https://beeuni.ai/schema/beeuni.v2.schema.json beeuni_version: 2 ``` ```bash beeuni schema --version 2 ``` ## Vollständiges Beispiel ```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. ``` ## Schlüssel auf oberster Ebene | Schlüssel | Erforderlich | Hinweise | | --------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------ | | `beeuni_version` | ja | muss `2` sein | | `default_agent` | ja | muss einen deklarierten, aktivierten Agenten benennen | | `imports` | nein | weitere YAML-Dateien oder Verzeichnisse, deren `triggers`, `connectors`, `agents`, `apps` und `tools` in dieses Manifest übernommen werden. Siehe [`imports:`](#imports) | | `tools` | nein | die Tools, die jede Sitzung erhält: Toolname → modulrelativer Pfad im Repo oder `beeuni:` für ein Beeuni-Tool. Mit einem `tools`-Schlüssel erhalten Sitzungen nur die darin aufgeführten Beeuni-Tools. Jedes Harness führt sie aus. Siehe [`tools:`](#tools) | | `runtime` | nein | `"opencode"` (Standard) oder `"pi"` — das Agenten-Harness, das eine Sitzung in ihrer Sandbox startet; `pi` führt Experimental-Harness prozessintern im Sandbox-Daemon aus und liest dieselben Agenten-`.md`-Dateien und Skills. Das Feature-Flag `pi_harness` des Projekts wählt Experimental-Harness auch ohne diese Zeile aus. Experimental-Harness benötigt das Flag `llm_gateway`; andernfalls startet die Sitzung Standard-Harness. | | `harnesses.pi.packages` | nein | Experimental-Harness-Pakete, die die Experimental-Harness-Sitzungen des Projekts laden. Siehe [`harnesses:`](#harnesses) | | `pi.config_dir` | nein | `harnesses/pi`, danach `.beeuni/pi`, falls vorhanden. Experimental-Harness-native `settings.json`, `extensions/`, `skills/` und `prompts/`. | | `project.name` / `project.description` | nein | Anzeigemetadaten; die Plattform liest `project.name` nicht als Anzeigenamen des Projekts | | `env.required` / `env.optional` | nein | Namen von Umgebungsvariablen; `required` dient nur als Hinweis und wird beim Sitzungsstart nie erzwungen | | `sandbox` / `sandbox.templates` / `sandbox.default` | nein | Sandbox-Image(s) und Hardware | | `opencode.config_dir` | nein | Standard-`harnesses/opencode`, danach das veraltete `.beeuni/opencode` | | `triggers` | nein | Liste von Cron-, Webhook- und Monitor-Triggern | | `connectors` | nein | Liste der Connector-Definitionen | | `policy.default_mode` | nein | `allow_all` (Standard) oder `risk`; projektweiter Genehmigungsmodus für Connectors | | `agents` | ja | Governance-Zuordnung von Namen zu Blöcken; darf nicht leer sein. Mit `imports` kann die Zuordnung in einer importierten Datei stehen | ## `imports:` Teile ein Manifest auf mehrere YAML-Dateien auf. Nutze das, wenn `beeuni.yaml` über eine Bildschirmseite hinauswächst: 30 Trigger mit mehrzeiligen Prompts, ein Connector pro Team, eine Datei pro Agentengruppe. ```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. ``` Die Datei im Stammverzeichnis und ihre Importe bilden eine Projektkonfiguration. Ein Trigger in einer Datei kann einen Agenten benennen, der in einer anderen deklariert ist. **Regeln** 1. Ein Pfad ist relativ zum Repository-Stamm. `..`, absolute Pfade und Globs werden abgelehnt. 2. Bei einem Verzeichnisimport werden alle `.yaml`- und `.yml`-Dateien darunter auf jeder Verzeichnisebene nach Pfad sortiert übernommen. Andere Dateien werden übersprungen. 3. Eine importierte Datei deklariert `triggers`, `connectors`, `agents`, `apps`, `tools` und `imports`. Alle anderen Schlüssel (`beeuni_version`, `default_agent`, `runtime`, `project`, `env`, `opencode`, `sandbox`, `policy`, `policies`) verbleiben in der Stammdatei. Eine importierte Datei, die einen solchen Schlüssel setzt, schlägt bei der Validierung fehl. 4. Eine importierte Datei kann weitere Dateien importieren. Es gilt ein Limit von 8 Ebenen und 200 Dateien. Ein Zyklus ist ein Fehler. Eine Datei, die zweimal erreicht wird, wird nur einmal zusammengeführt. 5. Ein Name, eine Datei. Wird ein Trigger-Slug, Connector-Slug, Agentenname, App-Name oder Tool-Name in zwei Dateien deklariert, ist das ein Fehler, der beide Dateien nennt. Nichts wird stillschweigend überschrieben. 6. Einträge werden in dieser Reihenfolge zusammengeführt: zuerst die importierende Datei, dann ihre Importe in der angegebenen Reihenfolge. Ein fehlerhafter Import schlägt für das gesamte Manifest fehl, genauso wie ein YAML-Syntaxfehler. `beeuni validate`, `beeuni ship` und die Zusammenführungsprüfung der Änderungsanfrage melden den Fehler, bevor er `main` erreicht: ```text imports: triggers "weekly-report" is declared in both triggers/a.yaml and triggers/b.yaml — one name, one file ``` **Änderungen werden in der Datei vorgenommen, in der der Eintrag deklariert ist.** Wenn das Dashboard, die API oder `beeuni triggers enable|disable|rm` einen Trigger, Connector, Agenten oder eine App ändert, die in einer importierten Datei deklariert ist, wird nur diese Datei geschrieben. Die Stammdatei wird nicht neu geschrieben. Ein neuer Eintrag wird in die Stammdatei geschrieben. Verschieben Sie ihn manuell in eine importierte Datei, wenn er dort stehen soll. `imports` erfordert `beeuni.yaml`. Ein `beeuni.toml`-Manifest ignoriert den Schlüssel. ## `tools:` Die Tools, die eine Sitzung erhält, nach Namen. Ein Wert hat eine von zwei Formen: | Form | Bedeutung | | --- | --- | | `beeuni:` | Ein Beeuni-Tool (`web_search`, `image_search`, `scrape_webpage`, `memory`, `show`), das von Beeuni gepflegt wird. Der Schlüssel muss `` sein. | | Ein pfadrelativer Modulpfad | Ein eigenes Tool des Projekts in einem beliebigen Ordner. Unter einem Beeuni-Toolnamen ersetzt das Modul das Beeuni-Tool. | ```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 ``` Standard-Harness und Experimental-Harness führen dasselbe Modul aus. Der Modulvertrag, `beeuni tools ls`, `beeuni tools eject` und die Migration von `harnesses/opencode/tools/` sind unter [Tools](/docs/de/project/tools) zu finden. **Auswahlregel.** - Kein `tools`-Schlüssel, weder in der Stammdatei noch in einer importierten Datei: Sitzungen erhalten alle fünf Beeuni-Tools. Jedes Projekt, das vor Einführung der Liste erstellt wurde, behält sie. - Ein `tools`-Schlüssel, auch ein leerer (`tools: {}` oder `tools:` mit allen gelöschten Zeilen): Sitzungen erhalten nur die aufgeführten Beeuni-Tools, entweder als `beeuni:` oder als Modulpfad. Ein `tools`-Schlüssel in einer importierten Datei zählt ebenfalls. Löschen Sie eine `beeuni:`-Zeile, um dieses Tool für alle Agents zu entfernen. Verwenden Sie [`agents..tools`](/docs/de/project/tools#who-may-use-which-tool), um es auf einen Agent zu beschränken. **Fehler.** - Ein Name wird in snake_case geschrieben: `^[a-z][a-z0-9_]{0,63}$`. - Ein Harness-Toolname (`bash`, `read`, `write`, `edit`, `apply_patch`, `glob`, `grep`, `list`, `task`, `question`, `todowrite`, `webfetch`, `websearch`, `skill`, `lsp`, `invalid`, `execute`, `plan_exit`, `pty_*`) ist ein Fehler. - Ein Pfad endet auf `.ts`, `.js`, `.mts`, `.mjs`, `.cts` oder `.cjs`. Er darf nicht mit `/` oder `-` beginnen und kein `.`- oder `..`-Segment enthalten. - `beeuni:` unter einem anderen Schlüssel ist ein Fehler. Unter einem Beeuni-Toolnamen, zum Beispiel `web_search: beeuni:image_search`: ```text tools.web_search: muss `beeuni:web_search` (das Beeuni-Tool) oder ein pfadrelativer Pfad zu einem .ts- oder .js-Modul sein (z. B. `tools/web_search.ts`), das es ersetzt. ``` - `beeuni:` für einen Namen, der kein Beeuni-Tool ist, zum Beispiel `web_serch: beeuni:web_serch`: ```text tools.web_serch: muss ein pfadrelativer Pfad zu einem .ts- oder .js-Modul sein (z. B. `tools/web_serch.ts`). `beeuni:` bezeichnet ein Beeuni-Tool unter seinem eigenen Namen: `web_search: beeuni:web_search`, `image_search: beeuni:image_search`, `scrape_webpage: beeuni:scrape_webpage`, `memory: beeuni:memory`, `show: beeuni:show`. ``` - `beeuni validate` meldet auch ein deklariertes Modul, das nicht existiert. Ein `beeuni:`-Wert benötigt keine Datei. **Warnungen.** Eine Warnung lässt `beeuni validate` nicht fehlschlagen. - Ein `tools`-Schlüssel, der keines der fünf Beeuni-Tools aufführt: ```text tools: Sitzungen dieses Projekts erhalten kein Beeuni-Tool (web_search, image_search, scrape_webpage, memory, show). Fügen Sie `: beeuni:` hinzu, um eines beizubehalten. ``` Damit wird erkannt, wenn ein Projekt sein erstes eigenes Tool hinzufügt und versehentlich die fünf anderen entfernt. - Ein `tools` eines Agents, das ein Beeuni-Tool nennt, das das Projekt nicht lädt: ```text agents.beeuni.tools: „show“ ist ein Beeuni-Tool, das dieses Projekt nicht lädt: Fügen Sie `show: beeuni:show` unter dem übergeordneten `tools` hinzu oder entfernen Sie es hier. ``` ## `project:` Optionale, für Menschen bestimmte Metadaten: `name` und `description`. Die Plattform liest diese Tabelle für keinerlei Zwecke aus — der Anzeigename eines Projekts stammt aus seinem eigenen Datenbankeintrag. Betrachten Sie sie als Dokumentation für Personen, die das Repository lesen. ## `env:` Deklariert die Namen der Umgebungsvariablen, die Ihre Sitzungen benötigen. Die Werte werden auf der Dashboard-Seite „Environment variables“ hinterlegt, niemals direkt im Manifest. Die Plattform entschlüsselt sie und fügt sie beim Start der Sitzung als einfache Umgebungsvariablen ein. ```yaml env: required: [DATABASE_URL] optional: [STRIPE_API_KEY] ``` | Feld | Typ | Hinweise | | ---------- | ---------- | -------------------------------------------------------------------------------------------------------- | | `required` | `string[]` | Unverbindlich. Das Dashboard fordert den Nutzer zur Eingabe dieser Werte auf, aber der Sitzungsstart wird bei einem fehlenden Wert nicht blockiert. | | `optional` | `string[]` | Für Sitzungen verfügbar, sofern gesetzt. Das Fehlen ist unproblematisch. | Namen von Umgebungsvariablen entsprechen `^[A-Z_][A-Z0-9_]*$`. Secrets Manager begrenzt Namen auf 64 Zeichen — längere Namen lassen sich hier zwar parsen, können aber niemals einen Wert erhalten. Auch Namen, die mit `BEEUNI_` beginnen, können keinen Wert erhalten. Verwenden Sie Namen mit höchstens 64 Zeichen und vermeiden Sie das Präfix `BEEUNI_`. Vollständige Spezifikation: [Secrets](/docs/de/project/secrets). ## `sandbox:` und `sandbox.templates` Eine Liste benannter, startfähiger Sandbox-Images. Optional — ohne Einträge startet jede Sitzung mit dem Standard-Image der Plattform. Jede Vorlage benötigt genau eines von `dockerfile` (relativ zum Repository) oder `image` (eine öffentliche Docker-Referenz mit festgelegtem Tag oder Digest). ```yaml sandbox: templates: - slug: ml name: ML Development dockerfile: Dockerfile.ml cpu: 4 memory: 16 disk: 50 ``` | Feld | Typ | Standardwert | Hinweise | | ------------ | ------ | ------------------- | --------------------------------------------------------------------------------- | | `slug` | string | — | Erforderlich. Pro Projekt eindeutig. `default` ist reserviert. | | `name` | string | slug | Anzeigename in der Dashboard-Auswahl. | | `dockerfile` | string | — | Relativer Pfad zum Repository. Nicht kombinierbar mit `image`. | | `image` | string | — | Öffentliches Docker-Image, mit Tag oder Digest fixiert. Nicht kombinierbar mit `dockerfile`. | | `entrypoint` | string | eigene Runtime-Ebene | Überschreibt den Container-Einstiegspunkt. | | `cpu` | int | Provider-Standard | vCPU-Kerne. Bereich: 1–32. | | `memory` | int | Provider-Standard | RAM in GiB. Bereich: 1–128. | | `disk` | int | Provider-Standard | Speicherplatz in GiB. Bereich: 1–500. | | `container_runtime` | bool | `false` | Docker in der Sandbox mit Bridge- und Overlay-Netzwerk ausführen. Siehe [Runtime](/docs/de/work/runtime#docker-in-the-sandbox). | Jeder Wert muss eine positive Ganzzahl sein. Ein Wert unterhalb des Minimums schlägt die Validierung mit einem Fehler fehl. Ein Wert oberhalb des Maximums besteht die Validierung mit einer Warnung und wird dann zur Laufzeit auf den Höchstwert begrenzt. GPUs werden nicht unterstützt — die Angabe von `gpu` löst eine Warnung, keinen Fehler aus. Unter [Runtime](/docs/de/work/runtime) erfährst du, was die Runtime-Ebene zusätzlich zu deinem Image einfügt. ### `sandbox.default` Lege `default` in `sandbox` fest, damit eine Vorlage als projektweiter Standard gilt. Jede Sitzung, jeder Trigger und jeder Kanal startet dann damit, ohne einen Slug anzugeben. ```yaml sandbox: default: dev templates: - slug: dev dockerfile: Dockerfile.dev ``` `default` muss eine in diesem Manifest deklarierte Vorlage oder den reservierten Wert `"default"` für das Plattform-Image angeben. Ein Agent kann seine Umgebung mit `agents..sandbox` auswählen. Der Wert muss eine Manifest- oder Dashboard-Vorlage oder `"default"` angeben. ```yaml agents: researcher: sandbox: ml ``` Die Auflösung der Sitzungsvorlage erfolgt in dieser Reihenfolge: 1. Explizites `sandbox_slug` der Sitzung. 2. `sandbox` des ausgewählten Agenten. 3. `sandbox.default` des Projekts. 4. `"default"` der Plattform. Cron-Trigger, Webhook-Trigger, Zeitpläne und Kanäle verwenden die Vorlage des ausgewählten Agenten. Eine Änderung der Spezifikation (`cpu`, `memory`, `disk`, `container_runtime` oder des Images selbst) erstellt den Snapshot des Projekts neu. Die neue Größe gilt für die nächste Sitzung, nicht für eine laufende. ## `opencode:` Speicherort des Standard-Harness-Konfigurationsverzeichnisses. Optional, mit Standardwert. ```yaml opencode: config_dir: harnesses/opencode ``` | Feld | Typ | Standardwert | Hinweise | | ------------ | ------ | ----------------------------------------------- | ------------------------ | | `config_dir` | string | `harnesses/opencode`, dann `.beeuni/opencode` | Relatives Verzeichnis im Repository. | Wenn `config_dir` nicht festgelegt ist, verwendet Beeuni das erste von `harnesses/opencode` und `.beeuni/opencode`, das eine `opencode.json` oder `opencode.jsonc` enthält. In diesem Verzeichnis liegen nur die Dateien, die Standard-Harness liest: `opencode.jsonc`, `plugins/`, `tools/` und `commands/`. Agenten und Skills befinden sich im Stammverzeichnis des Repositorys, in `agents/` und `skills/`. `opencode.jsonc` bleibt die native Standard-Harness-Registrierung für Plugins, MCP-Server, Provider und Berechtigungen — dupliziere diese Einstellungen nicht im Manifest. Siehe [Agents](/docs/de/project/agents). ## `harnesses:` Harness-spezifische Einstellungen. `pi.config_dir` verweist auf ein relatives Verzeichnis im Repository mit Experimental-Harness-nativer Konfiguration (Standard: `harnesses/pi`, dann `.beeuni/pi`). Das Verzeichnis wird beim Start von Experimental-Harness importiert. `pi.packages` ist davon getrennt: Es installiert Pakete aus dem Manifest-`harnesses.pi.packages` pro Agent. Derzeit gibt es einen Paketschlüssel: `pi.packages`, die Pakete, die jede Experimental-Harness-Sitzung dieses Projekts lädt (`runtime: pi` oder das Flag `pi_harness`). Ein Paket kann alles von packages sein: Erweiterungen (Tools, Hooks, Befehle) sowie die Skills und Prompts, die ein Paket enthält. ```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 ``` | Eintragsform | Bedeutung | | --- | --- | | `npm:@` | Ein npm-Paket mit exakter Version. Ein Versionsbereich oder eine fehlende Version führt zu einem Validierungsfehler. | | `./` | Eine Erweiterungsdatei oder ein Paketverzeichnis in diesem Repository. Mit `..` darf es das Repository nicht verlassen. | | `{ source, extensions, skills, prompts, themes }` | Dieselbe Quelle mit Experimental-Harness-eigenen Einschluss-/Ausschlussfiltern. Ohne Filter wird alles geladen; `[]` lädt nichts. | Höchstens 20 Einträge. Git-Quellen werden abgelehnt. ### Pro Agent Ein Agent kann eigene Pakete hinzufügen und Pakete aus der obersten Ebene entfernen, und zwar unter `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 ``` - Die Pakete eines Agenten entsprechen der Liste der obersten Ebene abzüglich seiner `exclude`, zuzüglich seiner eigenen `packages`. - Ein Agenteneintrag für ein Paket, das auch in der obersten Ebene aufgeführt ist, ersetzt für diesen Agenten den Eintrag der obersten Ebene (andere Version oder andere Filter). - `exclude` führt Paketnamen (`pi-web-access`, `@scope/name`) oder `./`-Pfade so auf, wie sie in der Liste der obersten Ebene stehen. Eine Version wird nie angegeben. - Jede unterschiedliche Paketliste wird einmal erstellt. Agenten mit derselben Liste teilen sich den Build. - Pakete gehören dem Agenten, mit dem eine Sitzung startet. Ein Subagent, den ein anderer Agent mit dem Tool `task` startet, verwendet nur die standardmäßigen Workspace-Tools (`bash`, `read`, `write`, `edit`, `glob`, `grep`), weder seine eigenen Pakete noch die des übergeordneten Agenten; die Erweiterungs-Hooks des übergeordneten Agenten gelten weiterhin für seine Aufrufe. Starte eine Sitzung mit diesem Agenten, um seine Pakete zu verwenden. So gelangen Pakete in eine Sitzung: 1. Beim Zusammenführen der Änderungsanfrage, die diese Liste bearbeitet, werden die Pakete einmal für die Sandbox-Plattform und ohne Installationsskripte erstellt. Jede Erweiterung wird in eine einzelne minimierte Datei vorab erstellt. Beim Build bleiben die übrigen Dateien des Pakets erhalten, ausgenommen der Code, der bereits in dieser Datei enthalten ist, Typdeklarationen, Source Maps sowie das README und CHANGELOG im Stammverzeichnis. Projekte mit derselben Liste teilen sich den Build. 2. Eine neue oder neu gestartete Sitzung lädt den Build herunter, während ihr Repository geklont wird, und lädt jede Erweiterung direkt. Eine Sitzung führt niemals `npm install` aus und kompiliert keine Pakete. 3. Ein Paket, das nicht vorab erstellt werden kann (z. B. weil sein `pi.extensions` Globs verwendet), funktioniert trotzdem: Die Sitzung lädt es stattdessen aus den installierten Paketen, was länger dauert. Wenn der Code eines Pakets eine Datei liest, die beim Build ausgelassen wird, füge dem Eintrag einen Filter `extensions` hinzu: Die Sitzung lädt es dann ebenfalls aus den installierten Paketen. 4. Eine Sitzung, die startet, bevor der Build verfügbar ist, wird ohne die Projektpakete gestartet und beginnt mit dem Build; die nächste Sitzung enthält sie. Beeuni installiert außerdem in jeder Experimental-Harness-Sitzung eine Reihe von Systempaketen. Ein Projekteingtrag für dasselbe Paket ersetzt die Systemversion. Ein Repository kann auch Experimental-Harness-native Erweiterungen in `.pi/extensions/*.ts` enthalten; Experimental-Harness lädt sie ohne Manifesteintrag. Erweiterungen werden ohne Terminal-UI ausgeführt: Tools, Hooks und Befehle funktionieren; Widgets, die nur im Terminal verfügbar sind, haben keine Wirkung. ## `triggers:` Eine Liste von Cron-, Webhook- und Monitor-Definitionen. Jeder Eintrag startet eine Sitzung, in der `prompt` als erste Nachricht ausgeführt wird. ```yaml triggers: - slug: daily-digest type: cron cron: '0 0 9 * * 1-5' prompt: Summarize yesterday's commits. ``` | Feld | Erforderlich | Standardwert | Hinweise | | -------------- | --------------------- | --------------------- | ----------------------------------------------------------------------------------------------------- | | `slug` | ja | — | `[a-z0-9][a-z0-9_-]{0,127}`, unter den Triggern eindeutig. | | `type` | ja | — | `cron`, `webhook` oder `monitor` (experimentell). | | `prompt` | ja | — | Darf nicht leer sein. Unterstützt Templating. | | `name` | nein | slug | Bezeichnung für Menschen. | | `agent` | nein | `default_agent` | Muss einen Schlüssel in `agents:` benennen. Weglassen, um `default_agent` zu verwenden; schreibe nicht den Literalwert `default`. | | `enabled` | nein | `true` | `false` überspringt den Eintrag. | | `model` | nein | wird zum Auslösezeitpunkt aufgelöst | Wire-Form `provider/model`. Legt das ausgelöste Sitzung auf dieses Modell fest. Siehe [Modelle](/docs/de/project/models). | | `session_mode` | nein | `fresh` | `fresh`, `reuse`, `pinned` oder `keyed`. | | `session_id` | erforderlich für `pinned` | — | Genaue Sitzung, für die erneut eine Eingabe gesendet werden soll. | Cron-Trigger benötigen genau eines von `cron` (einen Ausdruck mit 6 Feldern) oder `run_at` (einen einmaligen ISO-8601-Zeitstempel) sowie `timezone` als IANA-Namen. Webhook-Trigger benötigen `secret_env`, den Namen eines Geheimnisses, das die Zustellung mit `broker` und dem Consumer `connector` verwendet. Monitor-Trigger benötigen `run` (einen relativ zum Repo angegebenen Befehl) und `mode` (`poll` oder `stream`) und weisen alle Cron- und Webhook-Felder zurück. Die vollständige Feldreferenz, Einrichtung von Anmeldedaten, Payload-Templating, Endpunkte und Sitzungsstrategie findest du unter [Triggern](/docs/de/connect/triggers). ## `connectors:` Eine Liste externer Tools, die ein Agent aufrufen kann. Die Definition liegt in Git; Anmeldedaten liegen auf der Plattform, niemals im Manifest. Das konzeptionelle Modell findest du unter [Connectors](/docs/de/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 ``` | Feld | Erforderlich | Hinweise | | ------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `slug` | ja | `[a-z0-9][a-z0-9_-]{0,127}`, unter den Connectors eindeutig. | | `provider` | ja | `pipedream`, `mcp`, `openapi`, `postman`, `graphql`, `http` oder `channel`. | | `name` | nein | Anzeigename. Standardmäßig slug. | | `authorization_strategy` | nein | `project` oder `user`. Standardmäßig `project`, wenn nicht angegeben. Eine Projektstrategie verwendet aktive Projektverbindungen. Eine Benutzerstrategie verwendet nur die Verbindung des handelnden Mitglieds. | | `enabled` | nein | Standardmäßig `true`. | | `credential` | nein | Nur `shared` wird unterstützt. Der ausgemusterte Modus `per_user` führt zu einem harten Fehler. | | `sensitive` | nein | Standardmäßig `false`. `true` legt `require_approval` als Standard für nicht zugeordnete Aktionen fest, einschließlich Lesezugriffen. Explizite Projekt- und Connectorregeln werden weiterhin zuerst angewendet. | Anbieterspezifische Felder: | Anbieter | Erforderliches Feld | Hinweise | | ----------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `pipedream` | `app` | `account` optional, Standardwert ist slug. | | `mcp` | `url` | `transport`: `http` (Standardwert) oder `sse`. | | `openapi` | `spec` | Eine URL oder ein relativ zum Repo angegebener Pfad. | | `postman` | `spec` | Eine Collection-JSON-URL oder ein Pfad, ein `.postman/api`-Manifest oder eine Postman-Workspace-URL. | | `graphql` | `endpoint` | `spec` optional (SDL). | | `http` | `base_url` | `spec` optional. | | `channel` | `platform` | `slack`, `teams`, `email` oder `voice`. | | `computer` | — | API-verwaltet. Kann nicht manuell deklariert werden. Jeder verbundene Computer ist eines seiner Konten. Siehe [Computer](/docs/de/connect/computers). | `channel`-Connectors benötigen selten einen manuell geschriebenen Eintrag — wenn du im Dashboard einen Kanal verbindest, wird automatisch einer erstellt. Siehe [Slack & Kanäle](/docs/de/connect/slack). Die Slugs `beeuni_slack`, `beeuni_teams`, `beeuni_email` und `computer` gehören der Plattform; ihre Verwendung mit einem anderen Anbieter führt zu einem Validierungsfehler. Der Connector `computer` wird erstellt, wenn das erste Mitglied einen Computer verbindet, da Computer-IDs Identitäten der Control Plane eines Kontos sind und nicht ins Manifest gehören. `connectors.auth`: optional, für andere Anbieter als `pipedream`. `type` ist `bearer`, `basic`, `custom`, `api_key`, `oauth1`, `hmac`, `aws_sigv4`, `mtls` oder `none` (Standard). `oauth1` ist auf Anbieter von `openapi`, `postman` und `http` beschränkt. `in` ist `header` (Standard), `query` oder `cookie`. `name` ist erforderlich, wenn `type` `custom` oder `api_key` ist. `connectors.policies`: eine Liste mit `{match, action}`-Paaren. `match` ist ein Glob-Muster für Toolnamen. `action` ist `always_run`, `require_approval` oder `block`. Richtlinien gehören zum Connector. Alle Verbindungen unter diesem Connector verwenden dieselben Richtlinien. `policy.default_mode`: ein Top-Level-Schlüssel, getrennt von `connectors:`, der den projektweiten Genehmigungsmodus für Connectoren festlegt. Mögliche Werte sind `allow_all` (Standard; jedes nicht übereinstimmende Tool wird ausgeführt) oder `risk` (Genehmigung für nicht übereinstimmende Schreib- und destruktive Aufrufe erforderlich). Legen Sie den Wert mit `beeuni connectors policy set --default ` fest — siehe [CLI](/docs/de/cli). ## Kanäle v2 entfernt `channels:` aus dem Schema. Das Routing von Kanälen zu Agents (derzeit Slack, Microsoft Teams, E-Mail und Sprache) ist ein aktiver Betriebszustand und keine deklarative Konfiguration. Sie richten es auf der Seite „Channels“ im Dashboard oder über Chat-Befehle ein – dieselbe Trennung, durch die Zugangsdaten nicht in Git landen. Beim Verbinden eines Kanals wird weiterhin ein Eintrag vom Typ `connectors` mit `provider: channel` erstellt, den der Agent aufrufen kann. Siehe [Slack und Kanäle](/docs/de/connect/slack). Die Tabelle `[[channels]]` aus v1 wird unter [Legacy-TOML](/docs/de/project/legacy-toml) behandelt. ## `agents:` Eine Zuordnung von Namen zu Blöcken, wobei der Agentname als Schlüssel dient. Diese Zuordnung dient ausschließlich der Governance – sie legt fest, worauf ein Agent zugreifen darf, nicht, was er sagt oder tut. Dieser Block ist **die zweite der beiden Bindungen**: Ein Prinzipal erhält Rollen von Beeuni, und ein Agent erhält zusätzlich die hier festgelegten Beeuni-Berechtigungen. Eine Sitzung kann nur das tun, was beide erlauben. Siehe [Ein Vokabular, zwei Bindungen](/docs/de/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] ``` | Feld | Standard | Hinweise | | --------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | _(Zuordnungsschlüssel)_ | — | `[a-z0-9][a-z0-9_-]{0,127}`, eindeutig pro Projekt. Ohne `file` ist es auch der Dateiname von `.md`. | | `file` | `agents/.md` | Pfad des `.md` des Agents relativ zum Repository. Siehe [Die Agent-Datei](#the-agent-file). | | `enabled` | `true` | `false` behandelt den Agent als nicht deklariert – die Plattform startet ihn nicht. | | `connectors` | `none` | Welche Connector-Slugs dieser Agent aufrufen darf. `all` bedeutet alle Connectoren. | | `connectors_required` | `none` | Veraltet: wird eingelesen und ignoriert. Der Start der Sandbox wird nicht mehr durch einen verbundenen Connector eingeschränkt; ein Aufruf eines Connectors, mit dem nichts verbunden ist, gibt `connector_not_connected` mit einem Verbindungslink zurück. Muss weiterhin eine Teilmenge von `connectors` sein, sofern angegeben. | | `secrets` | `none` | Welche Projektgeheimnisse dieser Agent als Umgebungsvariablen der Sandbox erhält. Umbenannt von `env` in v1. | | `beeuni_permissions` | `none` | Welche Beeuni-Berechtigungen (Projektaktionen) dieser Agent über CLI, API oder Git ausüben darf. `all` bedeutet alle Projektberechtigungen, weiterhin begrenzt durch die Obergrenze der Rolle des Agents und ohne Berechtigungen, die ausschließlich Menschen vorbehalten sind. `beeuni_cli` ist die veraltete Schreibweise: wird weiterhin akzeptiert, mit einer Validierungswarnung; unterschiedliche Werte für beide Felder sind ein Fehler. | | `skills` | `none` | Welche Skills dieser Agent laden darf. | | `apps` | `none` | Welche Beeuni-App-Slugs dieser Agent öffnen darf, wenn die App `restricted` oder `private` ist. `all` bedeutet alle Apps im Projekt. Siehe [Agents und Apps](/docs/de/feature-flags/apps#agents-and-apps). | | `tools` | `all` | Welche Tools dieser Agent verwenden darf: Harness-, Beeuni- und Projekt-Tools. `all`, `none`, eine Liste (nur diese) oder `{ exclude: [...] }` (alle außer diesen). Die frühere Zuordnungsform `{ bash: false }` funktioniert weiterhin. Anders als bei den obigen Berechtigungen bedeutet ein ausgelassenes `tools`, dass alle Tools erlaubt sind. Siehe [Wer darf welches Tool verwenden](/docs/de/project/tools#who-may-use-which-tool). | | `repository_access` | `true` | Ob neue Sitzungen das Projekt-Repository erhalten. `false` deaktiviert die Bereitstellung des Repositorys und den Zugriff darauf über Sitzungszugangsdaten. Bestehende Sitzungen behalten ihre gespeicherte Richtlinie. | v2 verweigert standardmäßig alle Zugriffe: Ein ausgelassenes `connectors`, `secrets`, `beeuni_permissions`, `skills` oder `apps` wird bei einem deklarierten Agent als `none` aufgelöst. Gewähren Sie ausdrücklich jede Berechtigung, die ein Agent benötigt, wie es der `beeuni`-Agent im Starter oben tut. Bei der Migration eines Projekts von v1 müssen alle Berechtigungen manuell erneut gewährt werden – in v1 wird `env` (Geheimnisse) bei Auslassung standardmäßig auf `all` gesetzt, also genau umgekehrt wie in v2. `connectors_personal` bleibt ein veralteter Eingabealias für `connectors_required`. Neue Manifeste müssen `connectors_required` verwenden. Die Einstellung `authorization_strategy` des Connectors bestimmt, ob die Autorisierung dem Projekt oder dem Mitglied gehört. Berechtigungen für `beeuni_permissions` stammen aus einer festen Liste projektbezogener Berechtigungen (`project.read`, `project.gitops.push`, `project.gitops.merge`, `project.gitops.ref.any`, `project.trigger.*`, `project.secret.*`, `project.connector.*` und weitere). Kontobezogene Berechtigungen — `member.*`, `billing.*`, `project.create` — können Agents niemals gewährt werden. Führen Sie `beeuni validate --scopes` innerhalb einer Sitzung aus, um die aktuelle Liste der gewährbaren Berechtigungen auszugeben. ### Die Agent-Datei `agents..file` benennt `.md` des Agents relativ zum Stammverzeichnis des Repositorys. ```yaml agents: support: file: agents/support.md ``` - Der Pfad muss mit `.md` enden. - Der Pfad darf nicht mit `/` oder `-` beginnen. Er darf weder ein Segment `.` oder `..` noch ein leeres Segment enthalten. - Jedes Segment darf nur Buchstaben, Ziffern, `_`, `-`, `.` und Leerzeichen enthalten. - Wenn `file` ausgelassen wird, liest Beeuni zuerst `agents/.md` und danach `.beeuni/opencode/agents/.md`. Wenn `opencode.config_dir` festgelegt ist, lautet der zweite Pfad `/agents/.md`. - Wenn das Dashboard einen Agent mit `.md` speichert, schreibt es `file` mit diesem Pfad. - Die API lehnt eine Anfrage ab, die `file` ändert (`400`, Code `invalid_config`). Um einen Agent zu verschieben, verschieben Sie dessen `.md` und aktualisieren Sie `file` in `beeuni.yaml` im selben Commit. `beeuni validate` und die Merge-Prüfung für Änderungsanfragen lehnen ein ungültiges `file` mit einem Fehler bei `agents..file` ab. ## Wann Konfigurationsänderungen wirksam werden - Eine Manifest-, `agents/`-, `skills/`- oder Standard-Harness-Konfigurationsverzeichnisänderung wird erst angewendet, wenn eine Änderungsanfrage in `main` zusammengeführt wird. Sitzungen und Trigger lesen den Standard-Branch, nicht die Sitzungs-Branches. - Eine Änderung am Cron-Zeitplan oder Webhook eines Triggers wird innerhalb von Sekunden nach dem Zusammenführen vom Scheduler übernommen. - Eine Änderung am Sandbox-Image oder an der Hardware erstellt den Snapshot neu. Die neue Spezifikation gilt für die nächste Sitzung, nicht für die aktuelle. - Eine Änderung eines Secret-Werts im Dashboard wird beim Erstellen der Sandbox aufgelöst. Sie gilt für die nächste Sitzung, nicht für eine laufende. ## Regeln für Änderungen in beide Richtungen Dashboard-Änderungen lesen die Datei, in der der Eintrag definiert ist, aus, ändern sie und schreiben sie zurück: `beeuni.yaml` oder eine [importierte Datei](#imports). Damit Diffs bei Änderungen über die Benutzeroberfläche und während einer Sitzung sauber bleiben: 1. Belasse `beeuni_version` als ersten Schlüssel. 2. Ordne die Felder innerhalb eines Trigger-Eintrags wie folgt an: `slug`, `name`, `type`, `agent`, `enabled`, danach typspezifische Felder und zuletzt `prompt`. 3. Wenn du einen Webhook-Trigger hinzufügst, bevor sein Secret festgelegt ist, gib den Secret-Namen in `env.optional` an. Belasse den Trigger auf `enabled: false`, bis der Wert eingetragen ist. ### Repository-Zugriff Setze `agents..repository_access` auf `false` für Agents, die keine Projektquelldateien benötigen. Sie können weiterhin Sandbox-Dateien erstellen und ihre gewährten Tools, Secrets und Connectoren verwenden. Setze den Wert auf `true` für Agents, die das Repository benötigen. Git-Berechtigungen bleiben davon getrennt. Ändere diese Einstellung im Agent-Editor unter **Workspace → Project repository access**. Die Einstellung gilt für neue Sitzungen. Bestehende Sitzungen behalten ihre gespeicherte Richtlinie, auch nach einem Austausch der Laufzeit. ```yaml agents: support: repository_access: false engineer: repository_access: true ``` Das veraltete Feld `workspace` ist weiterhin lesbar: `branch` bedeutet `true`, und `runtime` bedeutet `false`. Legacy-Konfigurationen mit `read` verhindern weiterhin das Erstellen von Sitzungen, bis du das Feld durch einen expliziten booleschen Wert ersetzt. Es gibt keinen schreibgeschützten Repository-Modus. Widersprüchliche alte und neue Felder werden abgelehnt. Der Editor und das SDK senden `repository_access`. Bei deaktiviertem Zugriff speichert die API zusätzlich `workspace: runtime` als Kompatibilitätsspiegel. Dadurch bleibt die Einschränkung während eines Rollouts oder Rollbacks auch für ältere API-Replikate erhalten. API-Lesevorgänge lassen den Spiegel aus. Von Hand verfasste Manifeste, die nur `repository_access` verwenden, erfordern die aktualisierte API.