API（拡張の説明と決まり事）

このページは、汎用蛇太郎へ機能を足すときの公式の決まり事である。チャットAIには、このページの内容（またはこのページのURL）と、追加したい機能のプロンプトを一緒に渡す。ここだけで窓口と見本が揃う。

ここは APIキーの話ではない。プログラムが蛇太郎へ頼む窓口の呼び方と、短い動く見本である。宛先のAIサービス名は固定しない。利用者が選ぶ。

本体の Python は書き換えない。新しい通信経路も、秘密鍵の直書きもしない。返答は、選んだファイルへ上書き保存するだけで動く完成本文だけにする（説明文や Markdown の囲みは不要）。

ボタンか、パネルか
YOUボタンの決まり
パネルの決まり
見本：button.js
見本：panel
チャットAIへの渡し方

ボタンか、パネルか

一度開いて入力し、結果を見て終わる機能 → 左の YOU ボタン。button.js を全文置換する。
ずっと横（または上）に出しておきたい機能 → パネル。panel.html と panel.js を書く。
迷ったら、用途を見てどちらがよいかを先に提案し、選んだ方の完成ファイルだけを返す。

YOUボタンの決まり

入口は async function run(button, jarvis) { ... } だけである。
中央の一時画面の土台は jarvis.root である。ここに input や button を DOM で足せる。
一覧や結果は jarvis.show(items, reply)。items は必ず {title:"表示文"} の配列。文字列だけの配列は使わない。
案内やエラーの1文だけなら jarvis.show([], "日本語メッセージ") とする。
考えさせるときは jarvis.ask("日本語")。戻りは Promise で、成功時は文字列。例外、または前後空白を除いて空なら失敗とし、同じ失敗文を show([], ...) し、読み上げない。
jarvis.closed() は、ボタンを押した直後（ask の前）と、ask の直後（show の前）の2回見る。押した直後に閉じていれば show([], "中断しました") して戻る。ask のあと閉じていれば show も speak もせず、ボタンを有効にして戻る。
空入力の確認は、ボタンを無効にする前。Enter でも実行ボタンと同じ動きにしてよい。
成功時は show のあと await jarvis.speak(...)。失敗と例外では speak しない。
ほかに使ってよいのは jarvis.speak、jarvis.googleNews(keyword, count)、jarvis.skin(false|true, ticket) である。

パネルの決まり（表示の限界）

右パネルの幅はおよそ 300px。上パネルも横に広い作業机ではない。
枠の外へはみ出さない。長い文は折り返す。入りきらない一覧は、見出しで畳める形（例えば details / summary）にする。
見た目の大きなゲームや広い表は、パネル向きではない。それは YOUボタンの中央画面向きである。
パネルから中央のスキンを隠すときは pageApi.skin(false)。戻すときは pageApi.skin(true, 番号)。
鍵や個人情報はパネルのファイルに書かない。

短い動く見本：YOUボタン（button.js）

追加したボタンのフォルダにある button.js を、次で全文置換する例である。

async function run(button, jarvis) {
  jarvis.root.replaceChildren();
  const input = document.createElement("input");
  input.placeholder = "一文を書く";
  const go = document.createElement("button");
  go.textContent = "言い換える";
  jarvis.root.append(input, go);

  const once = async () => {
    const text = String(input.value || "").trim();
    if (!text) {
      jarvis.show([], "文を書いてから押してください");
      return;
    }
    go.disabled = true;
    try {
      if (jarvis.closed()) {
        jarvis.show([], "中断しました");
        return;
      }
      const reply = String(await jarvis.ask("次を短く言い換えて：" + text) || "").trim();
      if (jarvis.closed()) return;
      if (!reply) {
        jarvis.show([], "言い換えに失敗しました");
        return;
      }
      jarvis.show([{ title: reply }], "言い換え");
      await jarvis.speak("言い換えました");
    } catch (err) {
      jarvis.show([], "言い換えに失敗しました");
    } finally {
      go.disabled = false;
    }
  };

  go.addEventListener("click", () => { once(); });
  input.addEventListener("keydown", (ev) => {
    if (ev.key === "Enter") once();
  });
}

短い動く見本：パネル（panel.html / panel.js）

狭い枠でも崩れにくい、畳める1行の例である。panel.html

<!-- 幅およそ300px。枠の外へ出さない。長い文は折り返す。 -->
<details class="sub" open>
  <summary>いまの一言</summary>
  <p id="one-line">まだありません</p>
</details>

panel.js（読み込まれたとき一度動く）

(() => {
  const line = document.getElementById("one-line");
  if (!line) return;
  line.textContent = "この枠の外へはみ出さず、長い文は折り返してください。";
})();

チャットAIへの渡し方

宛先は利用者が選ぶ。特定のサービス名に固定しない。
このページ（URLでも全文でもよい）と、追加したい機能のプロンプトを一緒に渡す。
AIには、ボタンかパネルかを用途から提案させ、選んだ方の完成ファイル本文だけを返させる。