# アーキテクチャ — ソース実装ガイド

LLM プラグインのサイドバーを支えるクライアント／サーバモジュールの技術リファレンス。

> **設計上の根拠 — 処理フロー・ルール・優先順位と「なぜそうなっているか」は
> [docs/jp/design.md](./design.md) にまとめてある。** 本ドキュメントは「各モジュールが何をするか」の
> カタログ、design.md は「なぜその順序・ルールなのか」を扱う。

## 全体像

```
Editor sidebar (vibe_ui)  ──Send──►  /llm-plugin/generate  ──►  Ollama / OpenAI / Custom
        ▲                                              │
        │                                              ▼
   addMessageToUI                          response { response, model, elapsed }
   importFlowFromMessage  ◄──────────────────────────────┘
        │
        ├── extractFlowNodes  (LLMJsonParser → Vibe Schema → FlowConverterCore.toNodeRed)
        ├── rebuildWorkspaceFromSnapshot (additive wires + property preservation
        │                                 + CanvasLayout positions x / y)
        └── applyWorkspaceDiff → 削除 / その場で更新 / リンクの追加・削除
                               → RED.nodes.import は「追加されたノード」だけ
                               （差分で表現できないときは、消して入れ直す
                                 従来方式 replaceWorkspaceFlow にフォールバック）
```

`src/core/` にある3つの独立したコアモジュールが、変換＋レイアウトの土台を形成する:

| モジュール | 担当 | 参照 |
|--------|------|-----------|
| `flow_converter_core.js` | Vibe Schema ↔ Node-RED JSON + 型判定ヘルパー | [docs/jp/vibe-schema.md](./vibe-schema.md) |
| `canvas_layout.js` | トポロジカルレイアウト、幅を考慮した間隔、コメント配置、グループの枠、衝突の解消 | [docs/jp/layout.md](./layout.md) |
| `llm_json_parser.js` | JSON 修復、fuzzy エイリアス一致、スキーマ抽出 | (インライン JSDoc) |

残りはすべてプラグイン固有のグルーコード。まず下のファイルマップを見て、
各ファイルの詳細はモジュールリファレンスを参照。

## ファイルマップ

```
llm_plugin.js           Node-RED プラグインのエントリポイント — server.js を読み込む
llm_plugin.html         サイドバー + 設定の HTML テンプレート、marked.js と DOMPurify の読み込み
llm-plugin_styles.css   全プラグイン CSS
docs/                   全開発者ドキュメント(このフォルダ) — en/ + jp/
src/
  client.js             スクリプトローダー(ブラウザのエントリ) + 設定ダイアログのコントローラ
  common.js             共有ヘルパー(escapeHtml, notice, el, randomId, …)
  prompt_system.txt     Agent 用システムプロンプト: Vibe Schema の規約
  prompt_ask.txt        Ask 用システムプロンプト: フローを読んで説明する
  core/
    canvas_layout.js    レイアウトエンジン(UMD)
    flow_converter_core.js  Vibe Schema 変換器(UMD)
    llm_json_parser.js  LLM JSON パース(UMD)
  chat_manager.js       チャットセッション CRUD + チェックポイント永続化
  importer.js           LLM 出力の抽出、再構築、エディタへの import
  ui_core.js            メッセージ描画、フローエクスポート
  vibe_ui.js            サイドバー構築 + 生成ワークフロー
  llm_core.js           共有 LLM エンジン(設定/認証/プロバイダ/プロンプト)
  server.js             HTTP エンドポイント + チャット/チェックポイント永続化
node/                   `llm-request` ノード(パレットカテゴリ: llm-plugin)
  llm-request/          msg.payload を送り、モデルの応答を出力する
```

## 読み込み順(クライアント)

`llm_plugin.html` が `<script src="llm-plugin/src/client.js">` を読み込み、
残りを**順番に**取得・実行する:

```
common → canvas_layout → flow_converter_core → llm_json_parser
       → chat_manager → importer → ui_core → vibe_ui
```

レイアウトエンジンは変換器より前でなければならない。変換器がノードの座標決めを
レイアウトエンジンに任せているためである。
全モジュールは即時実行関数で自身を包み、共通のグローバル名前空間を介して互いを参照する。

## HTTP エンドポイント

| Method | Path | 権限 | 用途 |
|--------|------|------|---------|
| POST | `/llm-plugin/generate` | write | プロンプト + フローコンテキストを LLM へ送信。`mode: "ask"` はフローの説明を求め、それ以外はスキーマを求める。モードがシステムプロンプトを選ぶので、判断はブラウザではなくここで行う。1時間でタイムアウトし、サイドバーが接続を閉じたら(停止)打ち切る |
| GET | `/llm-plugin/settings` | read | 設定の読み取り(API キーはマスク) |
| POST | `/llm-plugin/settings` | write | 設定の書き込み(ホワイトリスト項目のみ) |
| GET | `/llm-plugin/chats` | read | 永続化されたチャットの一覧 |
| POST | `/llm-plugin/chats/save` | write | チャットの永続化 |
| POST | `/llm-plugin/chats/delete` | write | チャット ID でチャットとそのチェックポイントを削除 |
| POST | `/llm-plugin/checkpoints/save` | write | フロースナップショットの保存 |
| GET | `/llm-plugin/checkpoints/:id` | read | 保存済みチェックポイントの読み込み |
| POST | `/llm-plugin/client-log` | write | ブラウザ側で起きた失敗を Node-RED のログへ報告 |
| GET | `/llm-plugin/vendor/marked.js` | **なし** | 同梱の marked.js を提供(オフライン Markdown 描画) |
| GET | `/llm-plugin/vendor/purify.js` | **なし** | 同梱の DOMPurify を `LLMPlugin.DOMPurify` として提供(エディタのグローバル `DOMPurify` には触れない) |
| GET | `/llm-plugin/styles.css` | **なし** | プラグインスタイルシートの提供 |
| GET | `/llm-plugin/src/<file>` | **なし** | `client.js` が読み込むクライアントモジュールの提供(1ファイル1ルート) |

権限は `llm-plugin.read` / `llm-plugin.write`。データを読む・書く・課金が発生する
ルートにはすべて権限を付けてある。未認証の3本は、`<script>` / `<link>` タグが
ヘッダを付けずに取得する静的アセットである。

全ルートは `RED.httpAdmin` に登録される — [セキュリティ対策](#セキュリティ対策)を参照。

## モジュールリファレンス

### `client.js`

スクリプトを順番に読み込むローダーと、設定ダイアログのコントローラを兼ねる。
コントローラは HTML 側のフォームテンプレートに結びつき、「設定を読み込む」「設定を
書き出す」の2つの操作を外に見せる。プロバイダの切り替え、API キーのマスク表示、
最大プロンプト長(100–100,000)の扱いはここが受け持つ。

### `common.js`

全モジュールが使う小さな共有ヘルパー群。HTML と正規表現のエスケープ、
警告やエラーをチャット欄に出す1行、要素生成のショートハンド、ランダム ID の
生成、ワークスペース ID からタブ名への変換。

### `core/flow_converter_core.js` — Vibe Schema 変換器

Vibe Schema と Node-RED の JSON を相互に変換する。あわせて「そのノードは config
ノードか」「キャンバスに置ける実体か」「入力を持たない種類か」「出力を持たない種類か」
といった型判定と、エディタに登録済みの型情報を実行時に問い合わせる仕組みを提供する。
メタデータの約束もここが持つ: アンダースコア始まりのプロパティはプラグイン内部用であり、
LLM へ出力もせず、LLM からも受け付けない。
プラグイン外からも単体で読み込める形式で書かれている。
[docs/jp/vibe-schema.md](./vibe-schema.md) を参照。

### `core/canvas_layout.js` — レイアウトエンジン

ノードの座標決め専用。プラグインの他の部分に一切依存せず、単体で読み込める。
[docs/jp/layout.md](./layout.md) を参照。

### `core/llm_json_parser.js` — LLM 出力パーサ

LLM の JSON 出力の癖を許容するための層。コメントの除去、壊れたクォートの修復、
表記ゆれを許すエイリアス照合、散文混じりの応答からのスキーマ抽出を行う。

| エクスポート | 用途 |
|----------|-----------|
| ブロックの読み取り | `parseJsonBlock(text)` → `{ value, repaired }`(修復しても読めなければ null)。`repaired` は「書かれたままでは妥当な JSON ではなかった」ことを示す。サイドバーの JSON 折りたたみもこれを使う。パネルの表示とインポートが、同じ読み方の応答を指すようにするためである。 |
| スキーマ抽出 | `extractVibeSchema`, `extractConnectionHints`, `extractFlowDirectives` |
| フロールックアップ | `buildFlowLookup`(エイリアス / 名前 / ID のいずれからでもノード ID を引く。完全一致で見つからなければ表記ゆれを許す照合に落とす) |
| ノード抽出 | `extractFlowNodes` |
| 診断 | `diagnoseJsonExtractionFailure` — ノード抽出が何も返さなかったとき、各コードフェンスを改めてパースし直し、最初に見つかった具体的なパースエラーを行・列・該当箇所付きで返す。これによりインポート側は漠然とした「JSON が見つからない」ではなく「何行目で構文が壊れている」と表示できる。 |

**修復の順序。** `parseJsonRelaxed` はまず素の `JSON.parse` を試し、続けて仮定の少ない順に
修復を当て、最初にパースできた結果を採用する。そのまま → 値の中の未エスケープのクォート →
閉じられていない文字列を行末で閉じる → 閉じられていない文字列を複数行の値とみなす、の順である。
後ろの2つは「文字列の中に生の改行がある」ことの2通りの読み方である。JSON は文字列内の生の改行を
許さないので、これは文字列が閉じられていないことを意味する。どちらが正しいかは事前には決められない
ため、どちらも仮定しない。実際に妥当な JSON になった方だけを採用し、もともと妥当だったブロックは
修復に触れられることすらない。40 ノードのスキーマでクォートが1つ欠けただけで応答全体が失われる、
という事故を防ぐためである。`test/unit/json_repair.test.js` が保証する。

**式の値。** クォートの修復が手を入れた値は、そのあと「文字列リテラルがどこで始まり
どこで終わるか」の2通りの読み方で検査する。修復自身の読み方は、JSONata 式の外側の
クォートを食べてしまい、Node-RED がその式を受け付けなくなるためである。
[docs/jp/design.md §14](./design.md#14-壊れた値の2通りの読み方)を参照。

トークン正規化、JSON 修復(コメント除去・クォート修復・釣り合いの取れたスニペットの走査)、Agent の部分スキーママージは、上記エントリポイントの
内部ステップである。修復に触れられるのは `parseJsonBlock` 経由だけで、これはサイドバーが
インポートとまったく同じ読み方でブロックを読めるようにするために置いている。

### `chat_manager.js`

チャットセッションのライフサイクル。

| API | 説明 |
|-----|-------------|
| `getCurrentChatId()` / `getChatHistory()` / `startNewChat()` | メモリ内のセッション制御。 |
| `addMessage(content, isUser, meta?)` | メッセージを履歴に足し、サーバへ保存し、チャット欄に描画する。 |
| `saveChatToServer(chatId)` | 1チャット分をサーバへ保存。 |
| `loadChatHistoriesFromServer()` | 保存済みチャットを取得。まだ何も開いていなければ最新のものを自動で開く。 |
| `loadChat(chatId)` | 保存されたメッセージをチャット領域に再生する。 |
| `showChatList()` / `deleteChats(chatIds, cb)` | チャット一覧モーダル。チャットは1件ずつ、または All でまとめてチェックし、1回の確認でまとめて削除する。 |
| `saveImportCheckpoint(chatId?, flowIds?)` | インポート直前に対象フローを丸ごとスナップショットとして保存する。保存したスナップショットをメッセージに紐付けておき、メッセージ横の Restore ボタンがそこまで巻き戻す。チャット送信のたびではなく、インポートボタンが押された時点で呼ばれる。スナップショットの範囲には junction と group も含める([docs/jp/design.md](./design.md#7-スナップショットの完全性と-junction--group)参照)。 |
| `updateMessageMeta(messageId, patch)` | 保存済みメッセージのメタデータをパッチ。 |

### `importer.js`

LLM 応答から Node-RED フロー JSON を抽出し、エディタへインポートする。

**`extractFlowNodes(messageContent, options?)`** —
応答中のコードフェンスを走査し、**最後の**有効なブロックを採用する。解釈は
Vibe Schema を最優先とし、それで読めなければ素の Node-RED 配列、さらにコードフェンスの
外に裸で書かれた JSON へと順に落とす。コメント除去は文字列リテラルを避けて行うので、
function ノードのコード中に書かれた `//` は消えない。Agent モードのときは、LLM が返した
部分的なスキーマを現在のフローに重ねてから解釈する。こうしないと、応答が言及していない
既存ノードを接続の相手として指定できないためである。

**`importFlowFromMessage(messageContent, options)`** —
以下を保証する完全なインポートワークフロー:

1. **マージセマンティクス** — すべてのインポートは列挙されたノードを追加/更新し、
   `delete` に挙げられたものを削除し、言及されないものはそのまま残す。
   適用方法はマージのみ — 別の方法を選ぶフィールドはスキーマに存在しない — なので、
   1つのスキーマで追加・更新・削除を自由に組み合わせられる。
2. **ワークスペースのスコープ** — その回の会話で LLM にコンテキストとして渡した
   フローだけを書き換え対象とする。サイドバーがメッセージに記録しておいた対象フロー
   一覧をインポート処理に渡し、「どのタブへ書くか」を決めるすべての判断がその範囲に
   閉じる。タブ名の解決も、後述の返答の振り分けも、
   範囲外のタブは最初から候補に入れない。アクティブタブが範囲外なら、アクティブタブ
   ではなくコンテキストフローを対象にする。そして実際に適用する直前に
   最終確認を行い、対象が範囲外ならインポートそのものを中止する。
   これは体裁ではなく正しさの要件である: 適用はマージ後の最終状態に含まれないものを削除するため、範囲を
   絞らないと、会話が一度も見ていないフローを破壊的に書き換えうる。さらにチェックポイントは
   コンテキストフローの範囲しか保存していないので、Restore でも戻せない。
   コンテキストを1つも選んでいない場合は「範囲指定なし」とみなし、従来どおり
   アクティブタブを対象とする。リグレッションテスト: `test/unit/cross_flow_isolation.test.js`。
3. **1つのエイリアスは1つのノード** — モデルにはコンテキストの全フローを通した1つの
   エイリアス番号を見せているので、各エイリアスはちょうど1つのノードを指す。
   `contextAliasTable` がその番号を `UI.getFlowsByIds` から作り直し、`planByWorkspace` が
   何よりも先に返答をそれで読み、コンテキストフローごとのサブスキーマに分ける。各サブ
   スキーマは、そのフロー単体のインポートが解決するエイリアスで書く。既存ノードは、返答が
   どの `flow` を付けていても実際にあるタブで編集する。新規ノードは `flow` のタブへ、
   なければつながる先や見出しを付ける先のフローへ、それもなければ既定のフローへ置き、
   そのタブで同じエイリアスが別のノードに付いていれば名前を変える。削除、`reposition`、
   接続の削除は、名指ししたノードのフローへ送る。エイリアスと完全には一致しない名前は
   各フローで探し、ちょうど1つのフローだけが持つときに限って適用し、そうでなければ
   チャット欄で知らせる。タブ間のワイヤは作らない。プロパティ中のノード ID
   (`scope: [...]` など)は深さによらずモデルにはエイリアスとして見せ、`restoreNodeRefs` が
   ID に戻す。回帰テスト: `test/unit/cross_flow_isolation.test.js` のシナリオ 9〜11、
   `test/unit/import_safety.test.js` のシナリオ A1〜A3。
4. **厳密な 削除 → 追加/更新 → 接続 の順序** —
   再構築は3つの段階を明示的に分けて実行し、1つのスキーマがマージの途中で
   自己矛盾しないようにする:
   - *第1段階(削除)* は削除指示で名指しされたノードを、スナップショットに保存した元のフローから落とす。
   - *第2段階(追加/更新)* は残りの提案をノード ID ごとにマージする。このとき、第1段階で
     消したばかりのノードは、ID でもエイリアスでも復活させない。
   - *第3段階(接続)* は「既存ノードの自動エイリアス・新規ノードが名乗るエイリアス・
     ノード名・ID」をすべて引ける1つの索引を作り、行き先を失ったワイヤを取り除き、
     切断指示を適用したうえで、同じ索引を使ってスキーマの接続を張る。索引が1つなので、
     Ask / Agent どちらのモードが生成した応答でも新規ノードのエイリアスが解決できる。
5. **加算的なワイヤマージ** — 提案されたノードが既存ノードと一致した場合、接続先は
   出力ポート単位で既存の接続先と足し合わせる。接続が切られるのは、明示的な切断指示が
   あったときだけである。
6. **プロパティ保存** — LLM が言及しなかったプロパティは既存ノードの値のまま残す。
   「言及した」の判定には、スキーマ上で実際に書かれたキーの一覧を使う(Node-RED JSON を
   直接受け取った経路では値が入っているキー)。これにより、変換時に補われる既定値が
   ユーザーの設定を上書きしてしまうことがない。エディタ上のフラグも同じ扱いで、言及されなかった
   `d` / `l` はそのまま残る。`disabled: false` は `d` を削除するが「言及したキー」としては
   数えるので、有効化が復元で打ち消されることもない
   ([docs/jp/vibe-schema.md](./vibe-schema.md) の「エディタ上のフラグ」を参照)。
7. **コメント配置** — すべてのコメントは対象キャンバスノードを `above: <alias>` で
   指定し、そのノードの直上にグリッドギャップ 0 で配置され、**左端が**対象の左端
   (中心ではなく)に揃う。新しいコメントは同じ対象に接している既存コメントの上に
   スタックし、重ならない。`above` を持つコメントは宣言順に関わらず保持される —
   `above` がなく、リスト内に後続のキャンバスノードもないコメントだけが落とされる。
   `above` を省略したスキーマは「宣言順で次のキャンバスノード」にフォールバック
   する。[docs/jp/layout.md](./layout.md#コメント配置)を参照。
8. **Config Node 保護** — LLM は config ノードを作成も削除もできない。既存のものを
   エイリアスで参照するだけである。
9. **junction / group の保存** — スナップショットの範囲には、そのタブの junction と
   group も含める。含めないと、消して作り直す過程で失われ、junction 宛の
   ワイヤも「行き先のない接続」として取り除かれてしまう。差分適用ではスキーマが
   言及しない junction や group はそもそも触らないが、フォールバック時の
   作り直しには依然としてスナップショットが要る。
   [docs/jp/design.md](./design.md#7-スナップショットの完全性と-junction--group)を参照。
10. **差分適用** — マージ後の最終状態は「差分」として当てる。追加・削除・変更のあった
   要素だけを触り、配線の変更はリンクの追加・削除 API を通す（エディタでは接続が独立した
   オブジェクトとして別レジストリにあり、`wires` はそこから導出されるため、配列に代入しても
   何も起きない）。触られなかったノードは Node-RED に渡されもしない。group に属するノードの
   削除は、削除の前に `RED.group.removeFromGroup` を通すので、group が存在しないノードを
   指したまま残ることはない。従来の作り直し方式へフォールバックするのは、group の所属変更と
   type の変更、および group 用の API が使えない状態（ワークスペースのロック中）での
   group 内ノードの削除に限られる。
   [docs/jp/design.md](./design.md#12-作り直しではなく差分適用)を参照。
11. **ID を変えない再配置** — 再配置指示
   ([docs/jp/vibe-schema.md](./vibe-schema.md#reposition-ディレクティブ)参照)は、名指しされた
   ノードだけを、ID・プロパティ・接続を保ったまま並べ直す。並べ直した一群は元の左上位置に
   固定し直すので、キャンバスの他の部分は見た目に動かない。
12. **枠をシーケンスに沿わせる**(`keepBoxesAroundTheirSequences`) — グループの枠は
   ユーザーのものである。応答は枠を作れず、編集も削除もできない。枠は空になっても残す。
   マージ後、枠で囲まれたシーケンスにワイヤでつながれた新しいノードは、隣接ノードの枠が
   すべて同じ1つであればその枠に入る。応答が `above` を指定したコメントは、そのノードの枠に
   入る(ノードに枠がなければ元の枠から出る)。パディングが1行分しかないので、さもなければ
   上辺に載ってしまうからである。そのあと `CanvasLayout.fitGroups` が、すべての枠を
   メンバーの最終座標に合わせる。
   [docs/jp/design.md](./design.md#15-フロー・タブ・グループ)を参照。
13. **メタデータの除去** — 変換時に付けたアンダースコア始まりのプロパティは、キャンバスへ
   渡る前にすべて剥がす。1回目はマージ直後で、このときレイアウトがまだ必要とする
   並び順と配置先の情報だけを残す。2回目はレイアウト完了後で、残りも落とす。
   プラグイン内部の目印がフローに残ることはない。
   [docs/jp/design.md](./design.md) §0 メタデータ境界 を参照。
14. 以上を終えてから、最終状態を対象ワークスペースへ差分として当てる（表現できない
   変更のときだけ作り直しへフォールバックする）。座標はレイアウトエンジンに委ねる。

**`restoreCheckpoint(checkpointId)`** — 保存しておいたスナップショットを読み込み、ワークスペースの
フローを置き換える。このとき描画をひと呼吸遅らせる。そうしないと「ワイヤだけ描かれて
ノードの中身が空白のまま」になる描画競合が起きるためである。メッセージ下の Restore と、巻き戻してから再送するやり直しは、
すべてここを通る。

### `ui_core.js`

| API | 用途 |
|-----|---------|
| `addMessageToUI(content, isUser, messageMeta?)` | メッセージ本体とインポートのボタンを描画する。アシスタントの発言にはモード・モデル・所要秒数のバッジを添え、文中のノード名をクリック可能にする処理も併せて走らせる。最後に `refreshRetryButton()` を呼ぶ。 |
| `refreshRetryButton()` | 再送ボタンを1つだけ、チャット欄の末尾のメッセージに置き直す(他にあれば取り除く)。再送は常に**直前のユーザープロンプト**を送り直すので、古いメッセージに付いたボタンは押したときの動きを偽ることになる。描画時ではなくこの一箇所で配置を決めているのは、履歴から読み直したチャット(以前はボタンが1つも出なかった)、`Error: …` の応答、ユーザーが停止した回にも同じようにボタンを行き渡らせるためである。`Generating...` の仮置きが末尾にある間は、まだ再送するものがないので置かない。`addMessageToUI` の末尾、仮置きに印を付けた直後、そしてリクエストの `finally`(停止すると仮置きだけが消えて応答が増えないため)から呼ぶ。 |
| `formatMessage(text)` | Markdown として描画したうえで、DOMPurify で無害化する(DOMPurify が無ければエスケープしたテキストとして出す)。生の HTML を無効化するのはレンダラ側(`html()` でエスケープ)であり、元のテキストの山カッコを先に潰すやり方はやめた。先に `&lt;` にしてしまうと、コードブロックの中で marked がもう一度エスケープし、読む人の画面に `&lt;` がそのまま出るためである。応答が JSON だけのときは、`language-json` のコードブロック1つとして渡す。字下げされた行は散文ではないからである。 |
| `collapseJsonBlocks(container)` | JSON のコードブロックを `<details class="json-collapsible">` に畳み、`Vibe Schema JSON` / `Flow JSON (n nodes)` / `JSON` のラベルを付ける。スキーマの `description` は畳みの外に散文として引き上げる。ブロックの読み取りは `LLMJsonParser.parseJsonBlock` なので、インポート側が修復した応答も畳める。その場合はラベルに `(repaired)` を付ける。畳んだ中身はモデルが送ってきた文字ではなく、その修復後の読み方だからである。`json` として囲まれていて、まったく読めないブロックも畳む(`JSON (could not be read)`)。モデルが壊した応答こそ、読む人が一番どかしたいものである。 |
| `annotateNodeReferences(rootEl, targetFlowIds?)` | 応答中のノード名をクリック可能にする2段構えの走査。**1段目**は、バッククォートで囲まれた語をノード ID に解決し、当たったものをジャンプ用の要素に差し替える(コードブロック内は対象外)。**2段目**は残りの地の文を走査し、既知のエイリアス(3文字以上)と完全一致する語を拾う。LLM がバッククォートを付け忘れた言及を救うためである。単純な名前も複合的な名前も対象になる。長い候補から順に、かつ単語境界付きで照合するので、長い名前がその一部と同じ短い名前に負けることはない。タブは対象外、config ノードは対象に含め、クリックすると設定ダイアログが開く。対象フローが渡された場合、エイリアスの索引は LLM が見たのとまったく同じエクスポートから作り直す。こうしないと、同種ノードが複数あるときの連番が別のノードを指してしまう。渡されなければキャンバス上の全ノードから作る。システムプロンプト側でも LLM にノード名をバッククォートで囲ませているので、実際には1段目が主経路になる。 |
| `focusCanvasNode(nodeId)` | Debug サイドバーと同じ操作感でノードを指し示す。そのノードのタブへ切り替え、ノードを一時的に光らせ、ビューポートを中央に寄せ、再描画をかけ、約 2.5 秒後に光らせるのをやめる。config ノードはキャンバス上に位置を持たないので、代わりに設定ダイアログを開く。すでに削除済みのノードなら、その旨を通知する。 |
| `reannotateAllAssistantMessages()` | チャット欄にある全アシスタントメッセージのノード名注釈を貼り直す。エディタのフロー読み込み完了・デプロイ・タブ切替・ノードの追加/削除/変更に反応するよう一度だけ登録し、連続発火は 200 ミリ秒まとめる。サイドパネルがフロー読み込みより先にチャット履歴を描いてしまう起動直後の競合を解消し、その後ユーザーが編集やデプロイをしても注釈を追随させる。 |
| `createRestoreCheckpointButton(checkpointId)` | 共通の Restore ボタン。インポートのきっかけとなったアシスタントメッセージの上に差し込まれ、1クリックで編集前の状態まで巻き戻す。 |
| `showPostImportActions(message, checkpointId, content, messageMeta)` | 1つの選択を2つに分け、それぞれが効く場所へ置く。**Restore Checkpoint** は**プロンプトの直上**に置く(`placeRestoreAboveThePrompt` → `promptAbove`。応答の上にある最初のユーザーメッセージ。やり直しでは応答が連続してプロンプトが挟まらないので、直前の応答で探索を止める)。そこから下がまるごと巻き戻る対象だからである。メッセージの外側、兄弟要素として差し込むので、`appendFlowActions` はメッセージをチャットに追加した**後**に走らせる。**Apply Again** はスキーマブロックの見出し行に置く(`placeReapplyOnTheSchema` → `.json-collapsible[data-vibe-schema] > summary`。この印は折りたたみを組み立てるときに付ける)。提案を適用する操作は提案のそばにあるべきだからである。クリックはイベントの伝播を止める。止めないと折りたたみの開閉になってしまう。2つを行き来することが2つの版を見比べる手段であり、Agent モードでは Import ボタンを隠しているので、巻き戻した提案へ戻る手段は Apply Again だけである。どちらも追加前に必ず取り除くので、再適用しても積み上がらない。Apply Again は、まず**その応答を適用する直前のチェックポイントへ巻き戻して**から適用する(Retry と同じく、巻き戻しは可能な範囲で行う)。デプロイ前に複数の応答で押しても、キャンバスに現れるのは最後に押したものであり、すべてが積み重なることはない。各応答はメッセージ情報に、送信時の対象タブ(`targetFlowIds`。適用が書き込めるのはここだけ)、依頼したときに開いていたタブ(`homeWorkspaceId`。後で対象内の別のタブを開いていても、新しいノードはここに置く)、最後に適用したときのチェックポイント(`checkpointId`)を持つ。 |
| `runImport(message, content, messageMeta)` | サイドバーからのインポートが必ず通る唯一の経路(Import も Apply Again も)。チャット ID はクリックした時点で読み、範囲内のフローのチェックポイントを保存してからインポートする。実行のたびに自分のチェックポイントを取るので、Restore はその適用を取り消す。 |
| `getFlowsByIds(flowIds, opts?)` / `getCurrentFlow(flowIds?, opts?)` | 指定したタブと、そこから参照されている config ノードをエクスポートする。エディタ標準のエクスポート機能を通すので認証情報は落ちる。config ノードは**参照されているものだけ**を入れる(フローの選択が「何を外に出してよいか」というユーザーの意思表示だから)。参照は**多段**(mqtt ブローカーが TLS 設定を指しているような場合)でも、**配列プロパティ経由**でもたどる。`llm-request` ノード側の同名の処理と同じ規則である。`opts.includeCanvasExtras` はそのタブの junction **と** group も加える。再構築、チェックポイント、LLM に渡すコンテキストの経路で使う。モデルが見るエイリアスの割り当ては変わらない。変換器が group を落とし、junction や `link out` → `link in` を通るワイヤをその先への接続として読むからである。[docs/jp/design.md](./design.md#7-スナップショットの完全性と-junction--group)を参照。 |
| `getActiveWorkspaceId()` / `extractWorkspaceIds(nodes)` | ワークスペース ID を求める小さなヘルパー。 |
| `retryLastUserMessage(messageMeta?)` | 再送対象のメッセージにスナップショットが紐付いていればそこまで戻してから、直前のユーザープロンプトを送り直す。こうしないと、次のリクエストが「すでに編集が当たった後のフロー」を見てしまう。スナップショットがなければ、単に送り直すだけにする。 |

### `vibe_ui.js`

サイドバー本体。HTML 側のサイドバーと設定ダイアログのテンプレートから画面を組み立て、
続いて各操作を配線する:

- 送信 / 停止のトグル。1つのクリックハンドラが状態を見て振る舞いを変え、リクエスト中に
  二重に発火しないようガードする。
- **プロンプト入力のキー操作**: **Enter** で送信、**Shift+Enter** で改行、**Esc** で
  実行中のリクエストを停止する(サイドバーのどこにフォーカスがあっても効く。ただし設定
  ダイアログが開いているときは、Esc はそのダイアログのものである)。`e.isComposing`
  (または `keyCode === 229`)の間は送信しない。IME では変換を確定する Enter が同じ
  keydown として届くので、このガードがないと日本語を確定するたびに、確定しようとした
  その文が送信されてしまう。Esc と停止ボタンは同じ `stopGeneration()` を通る。
- 送信中のリクエストは中断できる。停止を押すと実際に通信を打ち切る。
- **モードの見え方**: リクエスト中は切り替えを無効化する。
  各応答の所要時間の行に、その回のモードをバッジで残す。
- **フローセレクタ**: フローの追加・変更・削除とタブ切替を購読し、消えたフローの選択を
  取り除く。アクティブなタブだけを選んでいるときは *Current Open Flow* と表示する。
  パネルの先頭は **All flows** 行(全選択/全解除。一部だけ選ばれているときは中間状態で
  表示する)で、その次に**開いているフローを固定で先頭に**並べる。既定のコンテキストであり
  最もよく触る対象なのに、タブが増えるとタブ順のどこかに埋もれてしまうからである。残りは
  タブ順のままなので、開くたびに並びが変わることはない。
- **新しいチャットを始めると、選択は開いているフローだけに戻る**
  (`ChatManager.onNewChat` → `selectActiveFlowOnly`)。フローコンテキストは会話に属する。
  編集が書き込んでよい範囲であり、チェックポイントが覆う範囲でもあるので、前の質問のために
  選んだ状態を引き継ぐと、その両方が黙って広がることになる。
- **チャットを開くと、そのチャットのフローが戻る**(`ChatManager.onChatLoaded` →
  `restoreChatFlows`)。選択はチャットに保存する(`chat.flowIds`。選択が変わるたびに
  `ChatManager.setFlowIds` が書く)。それより前に保存されたチャットは、最後の応答が対象にした
  フローを使う。フローを持たないチャットでは選択に触れない。エディタは起動時に最新のチャットを
  開くので、再起動すると直前に作業していたフローが選ばれた状態に戻る。
- **`flows:loaded` より前には選択を取り除かない。** エディタは読み込み中にタブを1枚ずつ
  追加する(タブごとに `flows:add`)。最初のタブで取り除くと保存済みの他のフローがすべて
  消え、空の状態が保存されて、サイドバーはフロー未選択で始まっていた。読み込みが終わるまでは
  開いているフローも決まらないので、その間に始めた新しいチャット(`wantActiveFlow`)と、
  何も保存されていない起動は、`flows:loaded` が来た時点で開いているフローを選ぶ。選んでいた
  フローがすべて削除された場合は、コンテキストなしではなく開いているフローにする。
- **セッション設定**(ブラウザのローカルストレージ): モデル名、モードの選択、フローの選択を
  サイドバー初期化時に復元し、ユーザーが変更したら保存する。すでに存在しないフローの選択は、
  ワークスペース側のイベントが来たときに遅れて取り除く。読み込みはいずれも例外を握りつぶし、
  ストレージが使えない環境では黙って既定値に戻る。
- **チャット履歴のたどり**: プロンプト入力欄で上下矢印を押すと、そのチャットの過去の
  ユーザーメッセージをシェルのように遡れる。手入力を始めた時点でたどりは解除される。
- 設定ダイアログ: フォーカス管理、Escape キー、背景クリックで閉じる。

エディタのサイドバー API が使えるようになるまでポーリングしてから、タブを登録する。

### `llm_core.js` — 共有 LLM エンジン

サイドバーの HTTP 層と `llm-request` ノードの両方が使う、状態を持たないエンジン。ここに
集約しているからこそ、`llm-request` ノードはサイドバーでユーザーが設定したプロバイダや
API キーをそのまま引き継げる — 設定と認証情報の置き場は1つしかない。

| セクション | 主要関数 |
|---------|---------------|
| ストレージ解決 | `chatsDir` / `checkpointsDir` / `persistenceEnabled`(`<userDir>/llm-plugin`。書けなければメモリのみ)、`writeFileAtomic` |
| 設定 + 認証情報 | `getPluginSettings`, `savePluginSettings`、暗号化した認証情報ファイル、旧形式のキーの移行、`maskApiKey`, `redactSecrets` |
| プロンプト構築 | `buildMessages`(システムプロンプトの読み込みと、現在のフローの Vibe Schema 化)。`llm-request` ノードはこれを使わず、自分のシステムプロンプトとプロンプトだけでメッセージを組む |
| LLM アダプタ | `generateWithProvider(provider, settings, model, messages, {timeoutMs})` — 実際の送信先は3つ。Ollama のチャット API、OpenAI 本体(SDK の Responses API、`/v1/responses`。システムメッセージは `instructions` で送り、`store: false` を付ける。新しいモデルはこの API で提供され、この API でしか使えないものもある)、Custom(Chat Completions。llama.cpp / LM Studio / vLLM / LocalAI などのローカルサーバが話す形式)。いずれも応答を**ストリーミング**で受け取る。ストリーミングしないとエンドポイントは生成が終わるまでヘッダを返さず、Node の `fetch` はタイムアウト設定に関係なく 300 秒でヘッダ待ちを打ち切る(SDK はさらに生成全体を2回送り直していた)。ストリームは終端の印(Ollama の `done`、Chat Completions の `finish_reason`、Responses の `response.completed`。Responses が `incomplete` で終わった場合は理由を添えたエラーにする)が届いて初めて完結とみなす。途中で接続を切るプロキシでもストリームは同じように終わるので、印が無ければ短い応答ではなく `ECONNRESET` とする。タイムアウトは応答全体にかかる。通信エラーのコードは `cause` 側にあり、generate ルートはそこを読んで「接続できない」と伝える。 |

### `server.js`

エンジンの上に載る薄い HTTP 層と、サイドバー専用の永続化。

| セクション | 主要関数 |
|---------|---------------|
| チャット履歴 | `saveChatHistory`, `loadAllChatHistories`(チャット1件につき1ファイル) |
| チェックポイント | `saveCheckpoint`(インポート1回につき1つのフロースナップショット) |
| クライアントログ | `writeClientEvent`(秘匿情報を除去して `RED.log` へ) |
| HTTP admin エンドポイント | 管理用ルートの登録。生成そのものはエンジンに委ねる |

### `node/` — `llm-request` ノード

`llm-request` ノードは設定・認証情報・プロバイダ呼び出しにこのエンジンを再利用する。詳細は
**[docs/jp/llm-request.md](./llm-request.md)** に別途記載。補足: サイドバーのチャット履歴は
対象フローの ID だけでなく**名前**も保持する。後から見返したときに、その回がどのフローに
対する対話だったかが読んで分かるようにするためである。

プロンプト組み立て:

```
messages[0] = {
  role: "system",
  content: <user system prompt (from settings), if set>
           + <contents of prompt_system.txt>
           + optional "CURRENT FLOW (Vibe Schema): ..."
}
messages[1] = { role: "user", content: <user prompt> }
```

チャット履歴は送らない — 各リクエストは LLM に対してステートレス。

#### セキュリティ対策

- **認証。** データを読む・書く・課金が発生する全エンドポイントは
  `RED.auth.needsPermission` で保護する(GET 2本は `llm-plugin.read`、
  残りは `llm-plugin.write`)。クライアント側は `Common.apiFetch` 経由で
  エディタのベアラートークンを付けて呼ぶ。これは明示的に書く必要がある。
  Node-RED は、プラグインが `RED.httpAdmin` に後から登録したルートには
  `adminAuth` を**自動適用しない**。コアの管理 API が自分のルートに個別に
  `needsPermission` を付けているだけで、後から足したものは同じことをしない限り
  素通しになる。`adminAuth` が未設定なら `needsPermission` は何もしないので、
  単独利用の環境の挙動は従来どおり。
  静的アセットのルート(marked.js、DOMPurify、スタイルシート、クライアントモジュール)は未認証の
  まま残す。`<script>` / `<link>` タグはヘッダを送れないためである。各ルートが配るのは
  決まった1ファイルだけで、クライアントモジュールは `client.js` が読み込む一覧と
  一致する。同じ `src/` にあるサーバ側モジュールは配らない(一覧の一致は
  `test/unit/server_api.test.js` が確かめる)。
- **応答の描画。** 応答は Markdown であり、描画先は管理権限を持つエディタの中である。
  だから応答に混じった生の HTML はマークアップではなくテキストとして扱う。これを
  レンダラ側(`html()` でトークンをエスケープ)で担保する。元のテキストの `<` / `>` を
  先に潰す方式はやめた。コードブロックに含まれる実体参照を二重にエスケープしてしまう
  副作用があったためである。Markdown の**画像はリンクに置き換える**。描画すればその URL を
  取得してしまい、フロー内のテキストに誘導された応答なら、その URL にフローの中身を
  載せられるからである。リンクならクリックされるまで何も送らない。この置き換えは、何かが
  読み込まれる前に不活性な文書の上で行う。そのあと marked が出した HTML を **DOMPurify** に
  通す。許すのは Markdown に必要なタグと属性だけで、リンク先は `http(s)` / `mailto:` /
  `tel:` か相対 URL に限り、各リンクに `rel="noopener noreferrer"` を付ける。DOMPurify は
  解析後の属性値を見るので、実体参照で書かれた `javascript:` も素の綴りと同じに扱われる。
  DOMPurify はプラグインが自分の依存(`dompurify`)から配り、`LLMPlugin.DOMPurify` になる
  ように包む。UMD 版をそのまま読み込むと、red.js が使うエディタのグローバル `DOMPurify` を
  別のバージョンで、しかもこのプラグインのフック付きで置き換えてしまうからである。
  DOMPurify が無いときは応答をエスケープしたテキストとして出し、手書きの代替処理は持たない。
  `test/unit/reply_rendering.test.js` が、エディタが読み込むスクリプトを jsdom 上で動かして確かめる。
- API キー(OpenAI と Custom エンドポイント)は AES-256-GCM で暗号化し、
  `<userDir>/llm-plugin/credentials.json` に保存する。フローの認証情報ファイルではなく
  自前のファイルに置くのは、デプロイ時の認証情報クリーンアップの対象になって消されない
  ようにするため。
  暗号鍵は**プラグイン自身が持つ秘密鍵**(`<userDir>/llm-plugin/credential.key`、初回に
  生成)から作る。同じフォルダに置くのは意図的で、プラグインが保存するものはすべてこの
  フォルダ1つにあり、削除すればリセットされる。暗号化が防ぐのは `credentials.json` だけが
  持ち出された場合で、フォルダ全体を読める人はキーも読める。Node-RED 本体の
  `flows_cred.json` と同じ制約である。Node-RED の `_credentialSecret` から導出しないのは意図的である。あれは
  ランタイムが所有する設定で、**ユーザーが settings.js に自分の `credentialSecret`
  を設定した時点でランタイムが削除する**。導出していると、その(推奨されている)変更
  だけで保存済みの API キーが黙って復号不能になってしまう。ランタイム側の鍵は復号時
  にのみ参照するので、旧バージョンが書いたデータもそのまま読め、次回保存時に
  プラグインの鍵で再暗号化される。
  Node-RED 本体が `flows_cred.json` に使う CTR ではなく GCM を使うのは、CTR には
  改ざん検知がなく、書き換えられたファイルがエラーにならないまま攻撃者の意図した
  ビット列に復号されてしまうからである。GCM ならその時点で失敗する。
  旧 CTR 形式のデータも引き続き読める(`g1:` 始まりが GCM の目印)。次回の保存で
  新形式に書き換わる。旧バージョンが平文で保存していたキーは初回起動時に自動移行する。
- API キーはクライアントに返さず、マスクした形だけを返す。保存済みのキーがあるときは、
  マスクが**必ず空でない文字列になる**。設定フォームは空のマスクを「キーは未保存」と解釈して
  入力欄を空で表示するため、そのまま保存すると、残すつもりだったキーが消えてしまうからである。
  前後の一部を見せると大半が露出してしまう短いキーには、長さだけを示す固定の伏せ字を使う。
  設定の書き込みは受け付けるフィールドを列挙方式で限定し、想定外のフィールドの注入を防ぐ。保存済みのキーは
  接続先の変更をまたいで引き継がない。`__EXISTING_KEY__`(保存済みのキーを使う指示)を
  送りながら同じリクエストで `customBaseUrl` を変更した場合は拒否する。そうしないと、
  クライアントからは読めないはずのキーを任意の送信先へ向け直す手段として設定フォームが
  使えてしまう。接続先 URL は `http:` / `https:` に限定する。
- プロンプト長の上限はサーバ側で検査する(既定 10,000 文字、設定可能な範囲は 100–100,000)。
  あわせてフローコンテキストにも独立した 1MB の上限を設ける。両者は同じシステム
  メッセージに連結されるので、後者の上限がないと、中身を `currentFlow` に移すだけで
  前者の上限を回避できてしまう。
- 保存するデータには上限を設ける。チャット・チェックポイントは各 5MB(`meta` を含む)、
  チェックポイントは 200 件を超えたら古いものから削除する。
- パスを受け取るルートはない。チャットはサニタイズした ID で探し、チェックポイント ID は
  `cp_<数字>_<16進>` に一致しなければならず、静的ファイルは決まった一覧だけを配る。
- `provider` は `ollama`・`openai`・`custom` のいずれかに限る。
- エラーメッセージとクライアントからの報告は、出力前に API キー・URL・IP を除去する
  (`meta` も含む)。まず**保存済みのキーの値そのもの**を文字列一致で除去する。Custom
  エンドポイントのキーは形式が決まっていないためパターンでは捉えられず、接続先が
  Authorization ヘッダをエラー本文に含めて返してきた場合、そのまま Node-RED の
  ログに残ってしまうからである。パターンによる除去は、ここに保存されていない
  キーに対する保険として残している。
- `credentials.json` と `credential.key` は原子的に書き込み、ファイルは `0600` で作成する。既存ファイルへの
  通常の書き込みではモード指定が無視されること、また書き込み途中で落ちるとデータが
  途切れて全キーを失うことへの対処である。
- 前後を見せられないほど短いキーには、**長さの分からない固定長**の伏せ字を使う。
- クライアントからの報告は、行単位のログへ渡す前に改行を除去する。呼び出し側が渡した
  文字列でログの行を偽装できないようにするためである。
- LLM へ送る前に、フローコンテキストから認証情報を取り除く。`llm-request` ノードは
  フローコンテキストを一切送らない。送るのはシステムプロンプトと `msg.payload` だけである。

#### Agent モードはモデルが書いたものをそのまま動かす

これは機能の性質であって不具合ではない。そのうえでプラグイン最大のリスクでもある。

- Agent モードはモデルの応答を**確認なしで**キャンバスに適用する。ユーザーがデプロイ
  するまでは動かず、適用の前にチェックポイントを取るので、Restore で取り消せる。
- ノード種別の**許可リストは設けていない**。生成されたフローには `function` ノード
  (ランタイムプロセス内で動く任意の JavaScript)や `exec` ノード(任意のシェル
  コマンド)が含まれうる。モデルが作れるものを制限すると、このモードの意義そのものが
  失われるため、あえて制限していない。

したがって、モデルの出力を支配できる者は、次のデプロイで何が動くかを支配できる。設定した
LLM エンドポイントは信頼できるインフラとして扱い、Agent の編集はデプロイ前にキャンバスで
確認すること。`llm-request` ノードには Agent モードがない。応答は `msg.payload` の
テキストであり、エディタに適用されるものは何もない。

## テスト

テストのドキュメントは別のページ
**[`testing.md`](testing.md)** にある。各スイートが何を
守っているか、共有の `helpers.js` サンドボックス、実 LLM との往復テスト
(`npm run test:llm`)の設定方法。

## 開発メモ

- クライアント側に **jQuery は使わない**。素の DOM 操作と標準の通信 API だけで書く。
- **モジュール間の受け渡し**は、1つのグローバル名前空間にぶら下げた各モジュールを介して行う。
- **チャットとチェックポイントの保存先**はサーバ側で、`llm_core.js` が決める。
  保存先は `<userDir>/llm-plugin` の**1箇所だけ**で、そこに書けない場合はメモリのみに
  なる(警告を1回ログに出す。API キーと設定を含め、再起動で何も残らない)。

  意図的に「代替の保存先を持たない」ようにしている。以前は OS の一時ディレクトリが
  第2候補だった。環境によっては他ユーザーから読め、プラグインの関知しない
  タイミングで消され、アンインストール後も残る。プラグイン自身のインストール先も
  候補にはしない。npm はバージョン更新時にそのツリーごと置き換えるため、
  **履歴を残さなければならないまさにその場面で消えてしまう**からである。

  userDir にすることで意図どおりのライフサイクルになる。**プラグインを更新しても
  チャット履歴・設定・API キーは残り、`<userDir>/llm-plugin` を削除すればリセットされる。**
  プラグインが保存するものはすべてこのフォルダにある: `chats/`、`checkpoints/`、
  `settings.json`、`credentials.json`、`credential.key`。以前のビルドは設定と暗号鍵を
  ランタイムの設定(`<userDir>/.config.runtime.json`)に置いていた。初回起動時に
  このフォルダへ移し、元の場所からは削除する。
- **システムプロンプト**はモジュール読み込み時にプラグインのインストール先から読み込む。
  コードに埋め込んだ代替は持たない。このファイルはパッケージに同梱され、読み込む側の
  モジュールと同じ場所にあるので、読めないとすればパッケージングの不具合である。
  そこで間に合わせのプロンプトに落とすと、エイリアス・所属フロー・コメントの位置・
  再配置といったインポート側が前提にしている規約が黙って失われたまま生成が続いてしまう。
  ファイルの存在は `npm test` で検証する。
- **設定の保存**: 秘匿でない項目は `<userDir>/llm-plugin/settings.json` に置く。エクスポート
  されるフローには含まれない。API キーは暗号化した認証情報の置き場に分離する(上記セキュリティ
  対策を参照)。Custom エンドポイントの API キーは、認証不要のサーバなら空欄でよい。
- **壊れたインストールは黙って動かない。** エントリポイントはエラーを記録したうえで
  **再スロー**するので、Node-RED はプラグインを読み込み失敗として扱う。握りつぶすと、
  全エンドポイントが 404 を返す状態でサイドバーだけが普通に開き、ログには何も残らない。
- **すでにバグの原因になった Node-RED API の作法:**
  ログ出力の関数は引数を**1つ**しか取らない。`console.error(a, b, c)` と違い、2つ目以降は
  捨てられる。`_credentialSecret` はランタイムの
  所有物で、ユーザーが `credentialSecret` を設定すると削除される。ここから鍵を
  導出してはならず、書き込んでもならない。
- **新しいエンドポイントを足すとき**は HTTP 層に追加し、Node-RED を再起動する。
- **新しいクライアントモジュールを足すとき**は `src/` にファイルを置き、ローダーの読み込み
  順の並びに加え、共通の名前空間に公開する。