ワークフロー

RAGSpine のワークフロー層には、3 つの明確に異なる役割があります。

1. コマンドラインまたは HTTP API からワークフローを記述または選択する。
2. 実行することなく設定を正規化・検査・変換・コンパイルする。
3. 明示的でサーバー制御の、デフォルト無効の実行サーフェスを通じてのみ実行する。

これらの役割を分離しておくことで、Web サイトはプロバイダーキーを受け取ったりマーケットプレイスのコードを実行したりすることなく、テンプレートを安全に表示できます。

自然言語からのひな形生成

ragspine "A RAG form-understanding paper workflow using CNN"
ragspine workflow create "invoice extraction and approval" --format json -o invoice.json

scaffold_workflow(description, ...) は、まずカタログとのマッチングを試みます。明示的に template_id を指定すると、そのテンプレートが信頼度 1 で選択されます。それ以外の場合、テンプレートの再利用にはスコアのしきい値と勝者マージンの両方の条件を満たす必要があります。マッチしなかった場合は、固定のエスケープ済み Dify 0.6 start → llm → end グラフが生成されます。モデルに実行可能なコードを創作させることはありません。説明文は 4,096 文字までに制限され、不正な Unicode/NUL 入力は拒否されます。

フォールバックには、インポート後に設定が必要となるモデル要件が含まれます。説明文から API キー、プロバイダーのベース URL、認証情報を受け取ることは決してありません。

マッチャー

• lexical: 決定的な BM25 と、統制されたバイリンガル分類エイリアス。
• onnx: FastEmbed によるセマンティックマッチング。[embed-onnx] が必要で、初回使用時にモデルのダウンロード/キャッシュが行われる場合があります。
• auto: 利用可能であれば ONNX を試み、レキシカルマッチングにフォールバックします。

1,000 テンプレートが意味するもの

同梱カタログには、手作業でキュレーションされた 7 件のテンプレートと、生成された 993 件のテンプレートが含まれます。生成されたディスクリプタは、ちょうど 39 の業種、27 のユースケース、そして 5 つのアーキタイプ（analysis、extraction、routing、synthesis、transformation）をカバーします。

カタログは Spine リポジトリ内で作成・管理されています。Dify Marketplace や n8n のページは、観測された人気度メタデータとともに調査/出典追跡の参照として記録できますが、RAGSpine がそれらの YAML、プロンプト、認証情報、長文説明をコピーすることはありません。実行時に上流のワークフローをダウンロードすることも実行することもありません。生成された 993 件のディスクリプタは、パッケージリソースから制約付きの Dify ワークフローとして具現化されます。

カタログの読み込み時には、識別子と SHA-256 による完全性を検証し、シークレットをスキャンし、ノードおよびプロバイダー/プラグインの形状を制限し、防御的コピーを返します。実行可能と表示されているテンプレートには、環境変数/会話変数や未対応の機能は含まれません。外部モデルの設定は、引き続きデプロイメント側の責任です。

JSON、YAML、TOML

parse_workflow は、テキストまたはバイト列に加えて、明示的な json、yaml、toml の形式指定を受け付けます。load_workflow は .json、.yaml、.yml、.toml の拡張子によって形式を選択します。すべての形式は、JSON 互換の単一の dict[str, object] に正規化されます。

テキストの自動判別では、先頭が { であれば JSON と認識し、それ以外は YAML として解析を試みます。TOML は明示的に指定するか、.toml ファイルから読み込む必要があります。JSON および YAML の重複キーは拒否されます。YAML には安全なローダーを使用します。非有限の数値、未対応の値、過度に大きな構造はフェイルクローズ（安全側で失敗）します。

ファイルの読み込みでは、シンボリックリンク、特殊ファイル、差し替えレース（replacement race）を拒否します。dump_json と dump_dify_yaml は決定的で検証済みの出力を生成し、出力される YAML はエイリアスを含みません。

Dify 互換性

Dify 設定は、ワークフローの主要な交換形式です。コンパイラは、パース → 中間表現 → 最適化/コード生成という流れに従い、Dify のワークフローグラフと advanced-chat グラフをサポートします。

ragspine dify analyze workflow.toml
ragspine dify compile workflow.yml --target ragspine

解析とコンパイルはワークフローを実行しません。コンパイラの Pydantic 境界には、[service] によって既に供給されている場合を除き、[dify] が必要です。

n8n 変換

Python および HTTP の変換サーフェスは、n8n_to_dify と dify_to_n8n をサポートします。変換は純粋（副作用なし）であり、正確に表現できないセマンティクスについては警告を返します。n8n のソースデータは、ラウンドトリップに対応するため、_n8n ノードメタデータとトップレベルの x_n8n データに保持されます。これは、任意の n8n ワークフローがすべて RAGSpine で実行できるという主張ではありません。

プレビュープロトコル v1

ragspine workflow preview ID およびワークフローの HTTP レスポンスは、表示専用のプロジェクションを公開します。

{
  "preview_schema_version": 1,
  "nodes": [
    { "id": "start", "title": "Start", "type": "start", "x": 0, "y": 0, "width": 240, "height": 96 }
  ],
  "edges": []
}

ノードには id、title、type、ジオメトリ、およびオプションの parent_id のみが含まれます。エッジには id、source、target、およびオプションの label のみが含まれます。このプロジェクションは、プロンプト、変数、プロバイダー設定、認証情報を意図的に省略しています。ジオメトリは決定的であり、バリデーションは重複 ID、欠落したエンドポイント、親の循環を拒否します。制限は、ノード 256 個、エッジ 512 本、表示文字列 1 つあたり 512 文字です。

プレビュー v1 は実行可能なワークフロー形式ではありません。利用側は preview_schema_version で分岐し、未知のバージョンは未対応として扱うべきです。

HTTP カタログとひな形生成

• GET /v1/workflow-templates: ページネーション付きのメタデータのみ。1 ページ最大 100 件で、キャッシュと弱い ETag をサポートします。
• GET /v1/workflow-templates/{template_id}: 正規化されたワークフロー、Dify YAML、プレビュー v1。
• POST /v1/workflow-scaffold: 説明文/テンプレートの選択、マッチメタデータ、ワークフロー、YAML、要件、警告、プレビュー。結果を実行することは決してありません。

実行境界

Dify および n8n の実行ルートは、RAGSPINE_DIFY_RUN_ENABLED=true が設定されるまで 403 を返します。プロバイダーおよび登録済みの Dify アプリワークフローパスはサーバー側で設定され、クライアントがプロバイダーオブジェクトや API キーを送信することはできません。コンパイルは静的ゲートを通過した後、設定されたアイソレーションモードのもとで実行されます。デフォルトの inprocess モードは制限付きの Python 境界であって、セキュリティコンテナではありません。Linux ではサブプロセスによるアイソレーションをオプトインで利用できます。

n8n 互換の /webhook/{path} ルートは、Webhook のセマンティクスに合わせて意図的に非認証となっています。このルートはアクティブな保存済みワークフローのみを対象とし、同じデフォルト無効の実行ゲートの対象であり続けます。デプロイメントに適したイングレス認証/レート制限なしに、このルートを直接公開しないでください。