# Minion - 言語モデル向けドキュメント

Minion は AI エージェントのワークスペースです。自前のホスト上で動くエージェント (ミニオン) を
管理し、エージェントと人が共有するワークスペース機能 - ノート、フォーム、カレンダー、
ドライブ、会計、アセスメント、ヘッドレス CMS - を持ちます。

このファイルには Webhook でのワークフロー起動の組み込みに要るページだけが入っています。各ページの先頭に正規 URL があります。

ドキュメント全文: https://docs.minionworkspace.com/ja/llms-full.txt
English: https://docs.minionworkspace.com/llms-dag-webhook.txt

## 間違えやすい規約

コードを書く前にここを読んでください。**一見もっともらしい実装のほうが誤りになる**箇所です。

1. **Webhook はサーバー・CLI・拡張の background から呼びます。Web ページからは呼べません。**
   CORS ヘッダを返しません。認証ヘッダも署名もなく、**URL 全体**
   (`https://<host>/api/dag/webhooks/<token>`) が資格情報です。サーバー側の変数に置き、
   `NEXT_PUBLIC_` / `PUBLIC_` を付けてはいけません。
2. **body は JSON オブジェクト 1 つで、決まったフィールドも封筒もありません。** そのまま start
   ノードの `output_data` になります (`title` / `body` / `payload` のような箱は存在しません)。
   配列・スカラー・空ボディは `400` です。渡すものが無くても `{}` を送ってください。
   `Content-Type: application/json` が必須で、上限は 1MB です。
3. **冪等ではありません。** `Idempotency-Key` は読みません。タイムアウト後の再送は実行を 2 本
   作りえます (`201` が返らなくても 1 本目が作られている場合があるため)。重複が困るなら、body に
   自前の一意な値を入れてワークフロー側で弾くか、自動再送をやめてください。
4. **`201` は受理であって完了ではなく、結果を返す API もありません。** 実行状態の取得は
   ログインセッションを要求するので、トークンでは読めません。結果が要るなら、ワークフローの
   最後に呼び出し元へ POST するノードを置いてください。
5. **ペイロードの形がワークフロー側で決まっている場合があります。** start ノードに
   `input_contract` があるか、start から出るエッジに contract が貼られていると、合わない body は
   1 ノードも走らずに `400` と `violations` で拒否されます。呼ぶ側からは事前に分からないので、
   ワークフローを作った人に聞いてください。
6. **`4xx` は再送しても同じで、`404` はわざと区別されません**: トークン違い・Webhook 無効・
   配置が無効はすべて同じ応答です。また Webhook を無効化するとトークンは破棄されるため、
   有効化し直すと URL が変わります。
7. **画像やファイルは、認証なしで取得できる URL で渡します。base64 ではありません。** 受け取るのは
   JSON だけで、base64 は 1MB の上限を食い (実質 700KB 程度の画像)、実行の記録としても保存されます。
   ログインが要る URL も役に立ちません — ミニオンからも取得できないためです。

---

# Webhook でワークフローを起動する

Source: https://docs.minionworkspace.com/ja/guides/dag-webhook/
Summary: 外部のサービス・スクリプト・ブラウザ拡張から DAG ワークフローを起動するために必要なことを、1 ページに閉じたもの。

DAG ワークフローには、**外から POST するだけで起動できる URL** を 1 本発行できます。手元の
スクリプト、社内のサービス、ブラウザ拡張の「送る」ボタンなどから、ワークフローを走らせられます。

このページは意図的に 1 ページで完結させてあります。**これだけを渡せば組み込める**状態にするため
です (人に渡す場合も、コーディング支援の AI に渡す場合も)。言語モデル向けのプレーンテキスト版は
[`/ja/llms-dag-webhook.txt`](https://docs.minionworkspace.com/ja/llms-dag-webhook.txt) にあります。

## この仕組みを 3 行で

ワークフローをプロジェクトに配置すると、その配置ごとに秘密のトークンを含む URL を発行できます。
その URL に JSON オブジェクトを POST すると、**body がそのまま start ノードの出力**になり、下流の
ノードがその形のまま受け取ります。認証は URL に入っているトークンだけで、ヘッダも署名もありません。

## 始める前に必要な値

| 値 | 見た目 | どこから |
|---|---|---|
| Webhook URL | `https://minionworkspace.com/api/dag/webhooks/<token>` | プロジェクトのワークフローを開き、**Webhook トリガー**の欄で**有効化** → **コピー** |

- **ホストは Minion を開いているオリジンと同じです。** ワークスペース ID もプロジェクト ID も
  パスには出てきません。パスは `/api/dag/webhooks/<token>` だけで、どこに届くかは**トークンが
  決めます**。
- **URL は「ワークフロー × プロジェクト」ごとに 1 本です。** 同じワークフローを 2 つの
  プロジェクトに配置しているなら URL は別々で、どちらのプロジェクトのメンバー・ロール・
  コンテキストで走るかは URL が決めます。呼ぶ側がプロジェクトを指定することはできません。
- トークンは 32 バイトの乱数 (base64url、43 文字) です。**URL 全体が資格情報**なので、
  環境変数に置いてください (例: `MINION_WEBHOOK_URL`)。`NEXT_PUBLIC_`・`PUBLIC_`・`VITE_` を
  付けてはいけません。付けるとブラウザに配る JavaScript に埋め込まれます。
- 画面では URL のトークン部分が伏せられていますが、**コピーは常にフルの URL をコピーします**。
  発行時にしか読めない類のものではないので、無くしたら画面から取り直せます。

### 有効化・停止・作り直し

| 操作 | 起きること |
|---|---|
| **有効化** | トークンを発行して URL が使えるようになる |
| **Rotate token** | 新しいトークンを発行。**古い URL は即座に 404** になる。漏れたときはこれ |
| **無効化** | URL が無効になる。**トークンは破棄されます** |

**「一時停止」のつもりで無効化しないでください。** もう一度有効化すると**別の URL** が発行され、
呼び出し側の設定を書き換える必要があります。

## リクエスト

```bash
curl -i -X POST "$MINION_WEBHOOK_URL" \
  -H 'content-type: application/json' \
  -d '{"source": "chrome-extension", "url": "https://example.com/x/status/123"}'
```

### 認証

**認証ヘッダはありません。** `Authorization: Bearer ...` も `X-...-KEY` も署名も**使いません**。
URL に入っているトークンが唯一の資格情報です。余分なヘッダを付けても読まれず、エラーにもなりません。

URL そのものが鍵なので、**ログ・エラー通知・`Referer`・スクリーンショットに URL を出さない**
ようにしてください。

### ヘッダ

| ヘッダ | 必須 | 備考 |
|---|---|---|
| `Content-Type: application/json` | **必須** | 無いと `415`。`application/json; charset=utf-8` も可 |
| それ以外 | — | 読まれません |

メソッドは `POST` だけです。`GET` などは `405` になります。

### ボディ

**決まった箱はありません。** `title` / `body` / `url` のような固定のフィールド名は定義されて
いません。**好きなキーに好きな型** (文字列・数値・真偽値・配列・ネストしたオブジェクト) を
入れて構いません。封筒 (`{"payload": {...}}` のような包み) も付けません。送ったオブジェクトが
**そのまま** start ノードの `output_data` になり、下流のノードがその形で受け取ります。

| 制約 | 内容 |
|---|---|
| トップレベルの型 | **JSON オブジェクト 1 つ**。配列・`null`・数値・文字列は `400` |
| 空ボディ | `400`。何も渡さないときも `{}` を送ってください |
| 大きさ | **1MB まで** (`Content-Length` で判定、超えると `413`) |

#### 受け取り側が形を決めている場合がある

ワークフローの [start ノード](https://docs.minionworkspace.com/ja/skills-workflows/dag-nodes/start/)に `input_contract` が
設定されているか、start から出るエッジに contract が貼られていると、**body はその型を満たす
必要があり**、満たさなければ実行は 1 ノードも走らずに `400` で弾かれます。レスポンスの
`violations` に、どのフィールドがどう違うかが入ります。

**contract があるかどうかは、呼ぶ側からは事前に分かりません。** ワークフローを作った人に
「start に contract があるか、あるならフィールド名と型」を聞いてください。設定されていなければ、
どんなオブジェクトでも通ります。

## レスポンス

### 成功

```
HTTP/1.1 201 Created

{ "execution_id": "3f0c…", "root_nodes": 1, "total_nodes": 7 }
```

**`201` は「受理して実行を作った」という意味で、完了ではありません。** ワークフロー本体は
この後ミニオン側で非同期に走ります。

**外から進捗や結果を取る API はありません。** `execution_id` は HQ の画面で実行を特定するための
ID で、実行の状態を返す API はログインセッションを要求するため、Webhook のトークンでは読めません。
結果を呼び出し元に返したい場合は、**ワークフローの側から**自分のサービスを叩く (最後にスキル
ノードや script ノードで POST する) 形にしてください。

### 失敗

本文は必ず `{"error": "<英語 1 行>"}` です。contract 違反のときだけ `violations` 配列が付きます。
`error` はそのままボタンの `title` やトーストに出せる短さです。

| status | `error` の例 | 意味・対処 |
|---|---|---|
| `400` | `Request body must be a JSON object` | 配列・スカラー・空ボディを送っている |
| `400` | `Invalid JSON body` | JSON として壊れている |
| `400` | `Payload violates start input contract "X"` | `violations[]` に違反箇所。送る形を直す |
| `400` | `Payload violates start outgoing edge contracts` | 同上 (start の出力エッジ側の型) |
| `400` | `DAG workflow has no version` / `DAG workflow has empty graph` | ワークフローが未保存・空。作った人に連絡 |
| `400` | `No PM minion assigned to project` | 配置先プロジェクトに PM ロールのミニオンがいない |
| `404` | `Not found` | トークンが違う / Webhook が無効 / 配置が無効。**3 つは区別されません** (総当たり対策) |
| `409` | `Project is archived` | プロジェクトが凍結中。解除は人が HQ で行う |
| `413` | `Payload exceeds 1000000 bytes` | 1MB 超 |
| `415` | `Content-Type must be application/json` | ヘッダ不足 |
| `500` | `Internal server error` | 一時障害 |

**`4xx` は送り直しても同じ結果です。** 直してから送ってください。再送の対象は `5xx` と
タイムアウトだけですが、次の項を読んでからにしてください。

## 重複排除

**ありません。** `Idempotency-Key` ヘッダは読みませんし、ボディにも重複排除用のフィールドは
ありません。**同じ body を 2 回 POST すれば、実行が 2 本走ります。**

タイムアウト時の自動再送が危ないのは、**`201` が返る前に切れても実行は作られている可能性が
ある**ためです。必要なら次のどちらかにしてください。

- 呼ぶ側で一意な値 (`"source_id": "..."` など) を body に入れ、**ワークフロー側**で処理済みかを
  見て弾く
- 自動再送をせず、失敗はユーザーに見せて手で押し直させる (拡張機能のボタンなら、たいていこれで
  足ります)

## CORS

**CORS ヘッダは返しません。** `Content-Type: application/json` の POST は必ずプリフライトを
起こすため、**Web ページの JavaScript から直接呼ぶとブラウザにブロックされます。** これは意図した
挙動です — URL 全体が資格情報なので、ページに配る JS に置いてよいものではありません。

| 呼び出し元 | 可否 |
|---|---|
| ブラウザ拡張の background / service worker (`host_permissions` に HQ のオリジンを追加) | **可** |
| サーバー・CLI・CI・ミニオン | **可** |
| Web ページのフロントエンドから直接 | **不可**。自分のサーバーを経由してください |

## レート制限

**アプリ側のレート制限はありません。** ただし 1 回の POST が実際にワークフローを 1 本走らせ、
ミニオンの (課金対象の) 計算時間を消費します。ボタン連打がそのまま実行の山になるので、
**送る側で二重送信を止めてください** (送信中はボタンを無効化する、など)。

## 画像などのファイル

- **この口は JSON だけです。** multipart もバイナリも受け付けません。
- **URL を渡すのが素直です。** 送信サイズが小さく済み、ワークフロー側のミニオンがその URL を
  取りに行けます。ただし**取得に認証が要らない URL** であること。ログインしないと見えない画像は
  ミニオンからも取れません。
- base64 で埋め込むこともできますが、**1MB の上限に効きます。** base64 は約 1.37 倍になるため、
  実質 700KB 程度の画像が上限です。それを超えるものは URL か、先にドライブへ置く形にしてください。
- 送った body は実行の記録としてそのまま保存されます。base64 を送ると実行履歴も同じだけ太ります。

## うまくいかないときは

- **`404` から疑ってください。** 有効化したか / Rotate した後の新しい URL か / そのワークフローの
  配置が有効か。この 3 つは区別されずに `404` になります。
- **`201` が返るのに何も起きない**ように見えるときは、HQ の実行一覧を見てください。実行は
  作られていて、下流のノードがミニオンに拾われるのを待っている (または失敗している) はずです。
- **`400` で `violations` が付いている**なら、送る形の問題です。フィールド名・型・必須の
  過不足が具体的に書かれています。

## 他の起動方法

| 方法 | ペイロード | 備考 |
|---|---|---|
| 手動 | 画面で入力 | HQ の実行ボタン |
| スケジュール (cron) | 常に `{}` | 最短 5 分間隔。プロジェクトの PM ミニオンが発火する |
| **Webhook** | POST した JSON オブジェクト | このページ |

---

# Startノード

Source: https://docs.minionworkspace.com/ja/skills-workflows/dag-nodes/start/
Summary: DAGワークフローのエントリセンチネル

**Start**ノードはワークフローグラフのエントリポイントです。トリガー時のペイロードを受け取り、通常のcascadeで下流ノードに引き渡します。

新規ワークフロー作成時にエディタが自動挿入するため、ノードパレットには現れません（キャンバスにドラッグすることはできません）。

## 使いどころ

トップレベルのグラフには必ずStartノードが1つ必要です。Fan-outテンプレート内には挿入できません（テンプレートはIn/Outマーカーを使うため、start/endは不許可）。

## 設定

| フィールド | 説明 |
|-----------|------|
| `input_contract`（任意） | 受け付けるトリガーペイロードが満たすべきcontract名。未設定なら任意のペイロードを受理（cron起動時は空オブジェクト）。 |

Contractはグラフに定義されたものから選択します。バリデーションに失敗したペイロードは、ワークフローが走り出す前にHTTP 400で拒否されます。

ペイロードの出どころは、手動実行・cronスケジュール（常に`{}`）・外部からの[Webhook URL](https://docs.minionworkspace.com/ja/guides/dag-webhook/)の3つです。

## 動作

1. ワークフローがトリガーされると、Startノードは`completed`として挿入され、`output_data`にトリガーペイロードがセットされます。
2. 直後にcascadeが走り、下流のノードがそのペイロードを入力として受け取ります。

Startはミニオンで実行されることはなく、課金対象の計算時間も発生しません。

## バリデーションルール

- トップレベルグラフにStartはちょうど1つ。
- Startに入力エッジを持たせることはできません。
- Startはfan-outテンプレート内に配置できません。