---
name: setup
description: "YAML の設定ファイルの項目を、利用者と対話しながら埋める。ファイルの中のコメント（項目の説明・例・選べる値）だけを頼りに、必須で空の項目から1つずつ質問して書き込む。コメントと項目の並びは変えない。「セットアップしたい」「設定したい」「設定ファイルを埋めて」と頼まれたとき、または設定ファイルの場所を渡されたときに使う。/embedded-debug-loop:setup で、このスキルだけでも使える。"
---

# 設定ファイルを対話で埋める

YAML の設定ファイルの項目を、利用者に聞きながら埋めるスキルです。
項目の意味は、ファイルの中のコメントだけを頼りにします。
コメントにないことは、説明も推測もしません。
設定を使って何かを動かしたり、試したりもしません。

## 道具

ファイルの読み書きには、このスキルの道具だけを使います。

```bash
python3 <このスキルのフォルダ>/scripts/config_tool.py <サブコマンド> ...
```

結果は、いつも JSON で返ります。
`"ok": false` のときは、`error` に理由が日本語で入ります。

| サブコマンド | すること |
| --- | --- |
| `list` | 作業フォルダの `.embedded-debug-loop/` にある設定ファイルの一覧を返す |
| `list --dir <フォルダ>` | 指定したフォルダにある設定ファイルの一覧を返す |
| `show <ファイル>` | ファイルの説明と、項目ごとの説明・今の値・例を返す |
| `set <ファイル> <項目> --stdin` | 標準入力で受け取った値を、文字として書き込む |
| `set <ファイル> <項目> --stdin --json` | 標準入力で受け取った値を JSON として読み、数・true か false・リストを書き込む |
| `get <ファイル> <項目>` | 1つの項目の今の値を返す |

- 作業フォルダは、今のフォルダです。違うときは `--workdir <フォルダ>` を付けます。
- `set` は、その項目の行だけを書き換えます。コメントと並びは変えません。
- `set` は、ない項目や、種類の違う値を断ります。
- パスワードなどの値は、空でなければ、結果の中で `＊＊＊` に置き換わります。
  空の値は、空のまま返ります。
- `set` は、`choices` がある項目に、`choices` にない値を書きません。
  空の値も、`choices` に空の値がなければ書きません。

### 値の渡し方（`set`）

値は、いつも標準入力で渡します。コマンドの引数には書きません。

```bash
python3 <このスキルのフォルダ>/scripts/config_tool.py set <ファイル> <項目> --stdin <<'VALUE_END'
<値>
VALUE_END
```

- 値がパス（/opt/… や /dev/… など）のときも、同じです。
  引数に書くと、Copilot CLI が、PC のそのパスを使う許可を求めることがあります。
  値がコマンドの行に出ないようにするためでもあります。
- `<<'VALUE_END'` の ' は外しません。値の中の記号（$ など）が、そのまま渡ります。
- `<値>` の行には、値だけを書きます。値を ' や " で囲みません。
- 数・true か false・リストは、`--json` を付けて、JSON の形で書きます。
  例：`200`、`true`、`["a", "b"]`
- 空の値を書くときは、`<値>` の行を書きません。
  `<<'VALUE_END'` の次の行が、すぐ `VALUE_END` になります。
- 空のリストは、`--json` を付けて `[]` と書きます。

`show` の結果のうち、使うものは次のとおりです。

| 名前 | 中身 |
| --- | --- |
| `header` | ファイルの先頭のコメント（何のファイルか） |
| `missing` | 必須なのに空の項目の名前の一覧 |
| `items` | 項目ごとの情報（次の表） |
| `table` | 項目と値の表。終わりの報告に、そのまま貼る。パスワードなどは伏せてある |

`items` の1つ1つには、次が入っています。

| 名前 | 中身 |
| --- | --- |
| `key` | 項目の名前 |
| `comment` | 項目の説明（項目のすぐ上のコメント） |
| `value` | 今の値 |
| `type` | 値の種類。`string`（文字）、`number`（数）、`boolean`（true か false）、`list`（リスト）、`null`（空） |
| `required` | 必須の項目なら true |
| `fill_recommended` | 必須ではないが、コメントに「必ず書く」などとある項目なら true |
| `empty` | 値が空なら true |
| `can_be_empty` | 空の値にしてよい項目なら true。必須の項目と、空を選べない `choices` の項目は false |
| `secret` | パスワードなど、見せない値なら true |
| `value_digest` | `secret` が true の項目だけにある。値の指紋（値には戻せない短い文字）。空なら空 |
| `examples` | コメントの「例：」の値 |
| `choices` | コメントの「選べる値：」の値。あれば、この中からしか書けない |
| `env_alternative` | 同じ値を環境変数で渡すための項目の名前（あるときだけ） |
| `env_for` | 環境変数の名前を書く項目なら、もとの項目の名前（あるときだけ） |
| `ask_alone` | false なら、この項目だけを聞きません。パスワードなどを環境変数で渡すための項目です |
| `env_defined` | 書いてある名前の環境変数が、今のシェルにあれば true |

`value_digest` は、書き換わったかを見分けるためだけに使います。利用者には見せません。

## 利用者に見せる言葉

- JSON の名前（`secret`、`missing`、`changed` など）は、利用者に見せません。
  ふつうの言葉で言います。
- 設定ファイルの項目の名前（`key`）は、見せてかまいません。
  利用者が、ファイルの中で探す名前だからです。
- コメントには、ファイルの中でしか通じない言い方があります。
  「下の」「上の」「このスキル」「この項目」などです。
  質問・表・説明では、そのまま使わず、名前で言い換えます。
  - 「下の xxx_env を使う」「上の値」は、その項目の名前で言います。
    例：「xxx_env を使う」「xxx の値」
  - 「この項目」は、その項目の名前（`key`）にします。
  - 「このスキル」は、`header` にある持ち主の名前にします。
    名前がなければ、「このファイルを使うもの」とします。

## 質問のしかた

利用者への質問は、必ず質問のツール（ask_user）で行います。
チャットの文で問いかけて終わらないでください。

- ask_user で、質問の文と選択肢を示して聞きます。
- 1回の質問で聞くのは、1つのことだけです。
- 質問の文は、箇条書きにせず、ふつうの文で書きます。
- 利用者は、選択肢のほかに自由に書くこともできます。
  「その他」のような選択肢は足しません。
- おすすめがあるときは、それを1番目に置き、「（おすすめ）」と付けます。
- 選択肢の値は、見える文と同じ日本語の文にします。
  値と見える文を分けて書けるときも、同じ文にします。
  Copilot CLI は、選ばれた値を、そのまま会話の記録に出すからです。
  英語の短い名前や記号を、値に使いません。答えは、その文で見分けます。
- 既定の選択肢（Enter だけで選ばれるもの）は、ふつうは付けません。
  付けるときは、1番目の選択肢だけを既定にします。
  「空のまま」「空にする」は、既定にしません。

### 質問が取り消されたとき・断られたとき

利用者が質問を取り消したとき（Esc を押したとき）や、答えるのを断ったときは、次のとおりにします。

1. それ以上は聞きません。
2. それまでに書き換えた項目を伝えます。
   `set` の結果の `changed` が true だった項目です。
   なければ、「書き換えた項目はありません。」と伝えます。
3. 「7. 終わりの報告」（ファイルの場所と、値の表）をして、終えます。

## 進め方

### 1. 設定するファイルを決める

- 呼び出し元がファイルの場所を渡したら、そのファイルを渡された順に設定します。
- 渡されなかったら、`list` を実行します。
  - 一覧が空なら、「設定ファイルがまだありません。設定ファイルを用意してから、もう一度頼んでください。」と伝えます。
    そのうえで、すでにあるファイルの場所を知っているかを ask_user で聞きます。
  - ファイルが1つなら、そのファイルを設定します。
  - 2つ以上なら、どれを設定するかを ask_user で聞きます。
    - 選択肢は「ファイルの名前：説明」です。
      どちらも `list` の結果の `details`（`name` と `header`）にあります。
    - 最後に「全部」を加えます。
- 呼び出し元か利用者が、直したい項目の名前を示したときは、その項目があるファイルを先にします。
- 渡されたファイルがなければ、作りません。そう伝えて、次のファイルへ進みます。

### 2. ファイルごとに進める

ファイルは、1つずつ順に設定します。
1つのファイルについて、2〜6 を全部終えてから、次のファイルに進みます。
ほかのファイルの項目を、先にまとめて聞くことはしません。

ファイルに入るときは、`show <ファイル>` を実行します。
`header` をもとに、何のファイルかを1〜2行で伝えます。ファイルの場所も伝えます。
`header` が空なら、ファイルの名前と場所だけを伝えます。
`show` が `"ok": false` を返したら、`error` を伝え、そのファイルは飛ばします。

### 3. 聞く順番（1つのファイルの中）

1. 呼び出し元か利用者が、直したい項目の名前を示したときは、その項目から聞きます。
   そのファイルにない名前は、飛ばします。
2. 次に、必須で空の項目（`required` と `empty` がどちらも true）を、ファイルの順に聞きます。
   1 で聞いた項目は、聞きません。
3. ほかの項目をどうするかを、ask_user で1回だけ聞きます。
   まだ聞いていない項目がなければ、聞きません。
   - 聞く前に、まだ聞いていない項目の表をチャットに出します。
     列は「項目」「今の値」「説明」です。
     「説明」には、`comment` の1行目を書きます。
     空の値は「（空）」と書きます。`secret` が true でも同じです。
     `secret` が true で、空でない値は「＊＊＊」にします。
   - 質問の文は、このファイルで、もう聞いた項目があるかで変えます。
     - 聞いた項目があるとき：「ほかの N 個の項目は、今の値のままでよいですか。」
     - まだ1つも聞いていないとき：「この N 個の項目は、今の値のままでよいですか。」
     - N は、表に出した項目の数です。
     - まだ1つも聞いていないときは、表の前の文でも「ほかの」を使いません。
   - 選択肢：「今の値のままにする」「1つずつ確かめる」「直す項目を選ぶ」
4. 「1つずつ確かめる」なら、表の項目をファイルの順に、全部聞きます。
5. 「直す項目を選ぶ」なら、どの項目かを ask_user で聞きます。
   - 選択肢は「項目の名前：説明」と、最後に「これで終わる」です。
   - 選ばれた項目を聞いたら、また同じ質問をします。「これで終わる」まで続けます。
6. `ask_alone` が false の項目は、1〜5 のどれでも扱いません。
   - パスワードなどを、環境変数で渡すための項目です（`env_for` がもとの項目）。
   - 表にも、「直す項目を選ぶ」の選択肢にも入れません。N にも数えません。
   - 単独では聞きません。もとの項目で「環境変数で渡す」を選んだときだけ聞きます。
     （「6. パスワードなど」）

### 4. 1つの項目の聞き方

`secret` が true の項目は、ここではなく「6. パスワードなど」のとおりに聞きます。

- 質問の文は「<key>：<comment>。今の値は <value> です。」の形にします（<comment> が「。」で終わるときは、「。」を重ねません）。
  - `comment` は、「利用者に見せる言葉」のとおりに言い換えてから使います。
  - 今の値が空なら「今の値は空です。」とします。
  - `type` が `list` なら「複数あるときは、「、」で区切って書いてください。」と足します。
- 選択肢は、次の順に並べます。当てはまるものだけを入れます。
  1. 「今の値のまま：<value>」（今の値が空でないとき）
  2. 書ける値。どれも「<値> と書く」の形にします（例：「my_app と書く」）。
     選ぶと、その値がそのままファイルに書かれると分かるようにするためです。
     「例：」は付けません。
     - `choices` の値。今の値と同じものは入れません。
     - `type` が `boolean` で `choices` がなければ、true と false のうち今の値でないもの。
     - `examples` の値。今の値と同じものと、`choices` にもあるものは入れません。
     - リストの値は、中の値を「、」でつないで示します（例：「a、b と書く」）。
  3. 「空のまま」（`can_be_empty` が true で、今の値が空のとき）
  4. 「空にする」（`can_be_empty` が true で、今の値が空でない、文字かリストの項目のとき）
  5. 「あとで決める」（`can_be_empty` が false で、今の値が空のとき）
- `can_be_empty` が false の項目には、「空のまま」「空にする」を出しません。
  `choices` がある項目は、空の値が `choices` にあるときだけ出します。
- 「空のまま」は、書ける値より前に置きません。
- 選択肢に、コメントにない値を足しません。値を作り出しません。
- 選択肢が1つもないときは、選択肢なしで聞きます（自由に書く答えだけになります）。

今の値が空で、`required` が true の項目にも、次と同じく「自分の値を書く（おすすめ）」を1番目に置きます（例の値は「（例）」を付けて後ろに）。例の値をそのまま選ぶと、その人の環境に合わない値が書かれるためです。

今の値が空で、`fill_recommended` が true の項目は、次のように聞きます。
コメントに、ふだん使うには必ず書く項目だとあります。
ただし、例の値が、その人の環境に合うとは限りません。

- 質問の文には、コメントの「必ず書く」の文を、省かずに入れます。
  例：「…なら、必ず書く項目です。」
- 1番目の選択肢は「自分の値を書く（おすすめ）」にします。
- `examples` の値は、「<値> と書く（例）」の形にします。
  例の値に「（おすすめ）」は付けません。
- その後に、ほかの選択肢を、ここまでに書いた順に並べます。
- 「自分の値を書く」を選んだら、書く値を ask_user で聞きます。
  - 質問：「<key> に書く値を書いてください。」
  - 選択肢は付けません（自由に書く答えだけにします）。Enter だけで「やめる」が選ばれてしまわないようにするためです。
  - 書かれた値は、「自由に書かれた答え」のとおりに書き込みます。
  - 何も書かれなかったら、同じ項目をもう一度聞きます。

### 5. 答えを書き込む

- 「今の値のまま」「空のまま」「あとで決める」は、何も書き込みません。
- それ以外は、答えを受けたらすぐに `set` で書き込みます。
  値は、いつも `--stdin` で渡します（「値の渡し方」のとおり）。
  - `type` が `string` か `null` の項目：`--json` を付けずに、答えのまま書きます。
    今の値が null の項目は、そのまま書けば、道具がコメントの「例：」を見て、数や true/false として書きます。
  - `number`・`boolean`・`list` の項目：`--json` を付けて、JSON の形で書きます。
    例：`200`、`true`、`["a", "b"]`
  - 「<値> と書く」を選んだら、`examples` か `choices` にある、その値をそのまま書きます。
    「（例）」や「（おすすめ）」が付いた選択肢でも同じです。
  - `list` の項目で `choices` の値を1つ選んだら、その1つだけのリストにします。
  - 「空にする」は、文字の項目なら空の値を書きます。
    リストの項目なら、`--json` を付けて `[]` を書きます。
- `set` が `"ok": false` を返したら、`error` を読みます。
  - `--json` の付け忘れなど、書き方の誤りなら、直して書き直します。
  - 値そのものの問題なら、`error` を利用者に伝え、同じ項目をもう一度聞きます。

自由に書かれた答えは、次のとおりにします。

- 書かれたとおりに書きます。
- 例や今の値と形が違っても、直した案を出しません。聞き返しもしません。
  例：例が「my_app」で、答えが「bin/my_app --fast」なら、そのまま書きます。
- 確かめるのは、その項目の種類として書けないときだけです。
  - `list`：「、」で分けて、JSON のリストにします。
    「、」がなければ、答え全体を1つの値にします。空白では分けません。
    「、」がなく、「,」などの区切りらしい文字があるときだけ、分け方を確かめます。
    選択肢は、分けた形と分けない形です（例：「a と b の2つ」「a, b で1つ」）。
  - `number`：数でないときだけ確かめます（例：「600秒」）。
    選択肢は、数だけにした値です（例：「600 と書く」）。
  - `boolean`：true か false でないときだけ確かめます（例：「はい」）。
    選択肢は「true と書く」「false と書く」です。
- 確かめるときも、答えの中身は変えません。項目の種類で書ける形にするだけです。

### 6. パスワードなど（`secret` が true の項目）

- 答えの値は、チャットの文や表に書きません。
- 今の値は、空なら「（空）」、空でなければ「＊＊＊」と書きます。
- `get` で取り出して見せることもしません。
- まず、渡し方を ask_user で聞きます。
  - 質問：「<key>：<comment>。どの方法で渡しますか。」（<comment> が「。」で終わるときは、「。」を重ねません）
    `comment` は、「利用者に見せる言葉」のとおりに言い換えてから使います。
  - `env_alternative` があるときの選択肢：
    1. 「環境変数で渡す（おすすめ。値をチャットにもファイルにも書きません）」
    2. 「自分でファイルを書き換える（値はチャットに出ません）」
    3. 「ここで入力して書き込む（入力した値は、Copilot CLI の画面と記録に残ります）」
    4. 「今のまま」（今の値が空なら、`can_be_empty` が true のときは「空のまま」）
       今の値が空で、`can_be_empty` が false なら、「あとで決める」にします。
  - `env_alternative` がないときは、2〜4 だけにし、2 に「（おすすめ）」を付けます。
- 「環境変数で渡す」なら：
  1. `env_alternative` の項目を、「4. 1つの項目の聞き方」で聞いて、環境変数の名前を書きます。
  2. 環境変数に値を入れるのは利用者です。次の入れ方だけを伝えます。
     「Copilot CLI を一度終え、同じ端末で `export 名前=値` を実行してから、Copilot CLI を起動し直してください。」
  3. もとの項目に値が入っていれば、消すかを ask_user で聞きます。消すなら、空の値を書きます。
- 「ここで入力して書き込む」なら：
  1. 値を ask_user で聞きます。選択肢は付けません（自由に書く答えだけにします）。
  2. 答えは、ほかの項目と同じく、`--stdin` で渡して書き込みます（「値の渡し方」のとおり）。

- 「自分でファイルを書き換える」なら、利用者が書き終えるまで待ちます。
  1. ファイルの場所と、項目の名前を伝えます。
     このとき、ほかのコマンドは実行しません。次の項目にも進みません。
  2. ask_user で「書き換えたら教えてください。」と聞きます。
     選択肢は「書き換えた」「あとでやる」の2つです。
  3. 「書き換えた」なら、`show` でファイルを読み直します。
     その項目の `empty` と `value_digest` を、書き換える前と比べます。
     書き換える前の値は、1 の前に最後に実行した `show` の結果のものです。
     - どちらかが変わっていれば、「<key> が書き換わりました。」と伝えて、次に進みます。
       値は見せません。
     - どちらも同じなら、まだ書き換わっていません。
       前が空なら「<key> は、まだ空のままです。」と伝えます。
       前が空でなければ「<key> は、まだ前の値のままです。」と伝えます。
       そして、2 をもう一度聞きます。
       前が空でなければ、選択肢に「前の値のままにする」を足します。
     - 書き換わったと確かめられないときに、書き換わったとは言いません。
       「新しい値」のような言い方もしません。
     - 読み直した後は、ほかの項目も、新しい `show` の値を使います。
  4. 「あとでやる」なら、次に進みます。
     その項目は、終わりの報告で「あとで書き換える項目」として伝えます。
  5. 「前の値のままにする」なら、何も書き込まずに、次に進みます。

### 7. 終わりの報告

設定を終えるときは、どんな終わり方でも、最後に必ずこの報告をします。
全部のファイルが終わったときも、途中で止めたときも同じです。
ほかのものから呼ばれて、呼び出し元がこの後に別の作業を続けるときも、省きません。

- この報告が、このスキルでする最後のことです。
- 報告は、チャットの文として、利用者に必ず見せます。
- ファイルごとに `show` をもう一度実行し、その結果を受け取ってから報告を書きます。
- `show` と、ほかのコマンドやツールを、一緒に呼びません。
- 報告を書く前に、ほかのコマンドやツールを呼びません。

ファイルごとに、次を短く伝えます。

1. ファイルの場所
2. 項目と値の表
   - `show` の結果の `table` を、そのまま貼ります。作り直しません。
   - `table` は、空の値を「（空）」、`secret` が true で空でない値を「＊＊＊」にしてあります。
     長い値は、真ん中を「…」で省いて、60 文字ほどにしてあります。
     値の頭と終わりは残してあります。
3. 必須なのに空のままの項目（`missing`）があれば、その名前と説明
4. 「あとでやる」と答えた項目があれば、「あとで書き換える項目：<key>」
5. `env_defined` が false の項目があれば、「Copilot CLI を起動した端末には、環境変数 <名前> がありません。」
   <名前> は、その項目の値（環境変数の名前）です。
6. 最後に、次の文を添えます。
   「このファイルは、直接書き換えてもかまいません。各項目の意味は、項目のすぐ上のコメントにあります。」

報告の後のこと：

- 報告の後は、呼び出し元の作業に戻ります。
- 呼び出し元は、報告の後に、自分の作業を続けてかまいません。
  このスキルの報告で、呼び出し元の手番を終えることはしません。
- 利用者がこのスキルだけを使ったときは、報告で終わります。

## 守ること

- 値は、利用者が選んだか書いたものだけを書きます。推測で書きません。
- 設定ファイルは、`set` でだけ書き換えます。ほかの方法で書き換えません。
- `set` の値は、コマンドの引数に書きません。いつも `--stdin` で渡します。
- 自由に書かれた答えを、例に合わせて直しません。直した案も出しません。
- ないファイルは作りません。項目を足したり消したりもしません。
- コメントにない説明はしません。意味を聞かれたら、コメントを示し、それ以上は分からないと伝えます。
- 設定を使って何かを動かしたり、試したりしません。
- 質問のツール（ask_user）が使えないときは、何も書き換えません。
  ファイルごとに、場所と、必須なのに空の項目（`missing`）を伝えて終えます。