導入（#0）メンター用メモ

参加者向けの内容は導入（#0）のページをご覧ください。 このメモは運営・メンター用です。参加者には見せなくてOKです。

体制・時間

  • 導入の担当1名。本編は別進行。
  • 90分想定（インストール25分＋安全設定20分＋アプリ作成35分＋予備10分）。
  • 60分しかない日は、アプリ作成を候補1（公衆無線LAN）のみに絞る。
  • 目標：帰るまでに「Desktopアプリが動く＋外部フォルダ制限あり＋1ページアプリをブラウザで見る」。

方針（旧版からの変更）

  • 今回はOpenCode Desktop（GUIアプリ）を使う。WSL/Ubuntu/ターミナルは使わない。
  • 安全設定は全プロジェクト共通で C:\Users\<名前>\.config\opencode\opencode.jsonc に置く（external_directory: * → deny が要）。プロジェクト単位で変えたいときだけ、その直下に置く（プロジェクト側が優先）。
  • 旧 setup-opencode-wsl.ps1（WSL手順）は今回使わない。

事前準備（前日まで）

  • OpenCode DesktopのWindows用インストーラ（x64 / ARM64）をDLし、会場でも配れるようUSB等に控える
    • 公式: https://opencode.ai/v2/docs/ の「Desktop」
  • 当日使う無料モデルを決め、/models で無料が出ることを予行
  • 認証の運用を決めておく（重要）
    • 参加者側に事前アカウント登録が必要か（不要な無料プロバイダを使うのか）を確定する
    • 必要なら「当日メンターがキーを配る／共通アカウントでログインさせる」段取りを用意
    • 自分のAIを持ち込む人向けに /connect の個別対応枠を確保
  • 会社PC対策を事前アナウンス（重要）
    • 募集ページ・事前連絡メールに「管理者権限のない会社支給PCでは動かない場合があります。個人用PCをご持参ください」を明記
  • 会場Wi-Fi・プロキシで opencode.ai と各AIプロバイダに到達できるか確認
  • 設定ファイル opencode.jsonc の雛形を用意（下記）
  • サンプル完成品（候補1のindex.html）を1つ用意（AI不調時の代替）
  • 実習用データの配布用コピー（候補1〜3のCSV。UTF-8変換版も）を用意（下記）
  • 「外部フォルダ拒否テスト」が期待どおり断られるか予行
  • 当日のスライド（/slides-0/）を予行（←→で進行。オフラインでも動く）

設定ファイル雛形（全員に配る）

既定は「全プロジェクト共通」：C:\Users\<名前>\.config\opencode\opencode.jsonc に置く。これでどのプロジェクトでも効く。プロジェクト単位で変えたいときだけ、そのフォルダ直下に置く（プロジェクト側が優先）。

{
  "$schema": "https://opencode.ai/config.json",
  "permissions": [
    { "action": "external_directory", "resource": "*", "effect": "deny" },
    { "action": "shell", "resource": "*", "effect": "ask" },
    { "action": "read", "resource": "*.env", "effect": "deny" },
    { "action": "read", "resource": "*.env.*", "effect": "deny" },
    { "action": "read", "resource": "~/.ssh/*", "effect": "deny" },
    { "action": "edit", "resource": "*.env", "effect": "deny" },
    { "action": "edit", "resource": "*.env.*", "effect": "deny" },
    { "action": "edit", "resource": "~/.ssh/*", "effect": "deny" },
    { "action": "webfetch", "resource": "*", "effect": "ask" }
  ]
}
  • ~ はWindowsでは C:\Users\<名前> を指す（home展開される。パスは \ でも / でも可）。
  • 版：この雛形は v2（Desktop 2.x） 用。v1 では項目名が違う（permission・bash）。当日インストールする版が v2 であることを公式（opencode.ai/v2/docs）で確認する。
  • 既定は全プロジェクト共通（グローバル設定 ~/.config/opencode/opencode.jsonc）。プロジェクト単位で変えたいときはそのフォルダ直下に置く（プロジェクトが優先）。
  • OpenCode自身の作業用フォルダ（一時領域・設定・ツール出力）は引き続き使えるので、external_directory:* deny でも通常動作は壊れない。
  • 配布する雛形はコメント無しの純粋なJSONとして配る（// を足さない）。JSONC非対応のツールで読ませても壊れないように。

進行スクリプト（声かけ例）

  1. 「黒い画面は使いません。アプリの画面だけでやります」
  2. インストールのSmartScreenは、ダウンロード元・発行元を確認してから「詳細情報 → 実行」を全員で一緒に
  3. ファイル作成の前に、エクスプローラーの「表示 → ファイル名拡張子」にチェックを入れさせる（opencode.jsonc.txt 事故の予防）
  4. 安全設定は「作業フォルダの外は触れないようにする」と意味を先に説明してから
  5. 設定後は再起動→「C:\Windowsを読んで」で断られることを見せる（安心の可視化）
  6. アプリは候補1（公衆無線LAN・UTF-8）推奨。データのダウンロードでつまずいたら配布CSVを渡す

セキュリティチェック（必ず確認）

  • グローバル設定 C:\Users\<名前>\.config\opencode\opencode.jsonc が存在し、external_directory → deny がある
  • 設定反映のため、アプリ/セッションを再起動済み
  • 外部フォルダ拒否テストで、AIの言葉ではなくツールが拒否されることを確認（言葉だけの「読めません」は根拠にならない）
  • 「アクセスを制限する設定」であり完全な隔離ではない旨を伝える（グローバル設定はプロジェクト側で上書き可）
  • 参加者に「許可」を毎回読ませる。「常に許可」は安易に押させない
  • プロジェクトフォルダの中に本当の秘密（個人情報・鍵）を置いていない（.env を使う設計なら *.env deny 前提で運用できているか確認）
  • 無料モデル利用者には「入力は改善に使われることがある」を口頭でも伝える
  • より強固にしたい参加者には、専用のWindowsユーザーアカウント or VMでの利用を案内（shell はホスト権限で動くため、これが最も確実）

秘密情報（.env 等）の扱い（メンター向け）

  • 初回は秘密情報を使わないで統一。参加者には「今回は個人情報やパスワードなどの秘密情報を使いません。必要になったらメンターに相談」と伝える。
  • 設定の read/edit の .env 禁止は部分的な対策。shell は実行ユーザーの権限で動くため、許可したコマンド経由のアクセスまで防げるわけではない（公式v2も注意）。
  • 秘密情報の保管・受渡し（環境変数やシークレット管理など）は、「これで安全」と言い切れるものではない。実務の運用はチームで相談する。

つまずきTOP5＋対処

  1. インストーラが止まる（SmartScreen / ウイルス対策）
    • ダウンロード元・発行元を確認して「詳細情報 → 実行」。会社PCの権限エラーは個人PC推奨、または見学＋後日対応
    • x64 / ARM64 の取り違えに注意
  2. モデルが選べない・接続できない
    • ネット確認→ /models で一覧。当日モデル変更に備え予備名を共有
    • 自分のAIは /connect で個別対応
  3. フォルダが開けない / 違う場所を開いてしまう
    • 「プロジェクトを追加 / フォルダを開く」で新しいフォルダ（例: ドキュメント\my-first-app）を作って開く
    • 意図した作業フォルダを開いているかをエクスプローラーのパス表示で確認させる（設定は全プロジェクト共通なので、場所が違っても設定自体は効く）
  4. opencode.jsonc が作れない・効かない
    • 拡張子の隠蔽が最頻出：実際は opencode.jsonc.txt になっている。エクスプローラーの「表示 → ファイル名拡張子」にチェックを入れて確認させる
    • JSONのカンマ抜けに注意（コメント無しの雛形をそのまま配る）
    • 置いた後はアプリを再起動。効かないときは場所（~/.config/opencode）と、プロジェクト側 opencode.jsonc が上書きしていないかを確認
  5. アプリが動かない（ボタン無反応・真っ白）
    • 追加プロンプト：「ボタンが動かない。直して」「スマホで見やすくして」
    • ダメなら予備の完成index.htmlを渡す。index.html のダブルクリックで開けることを確認

実習用データ（候補・前日までに確認）

当日は参加者が富山市の公式オープンデータからCSVを自分で選んでダウンロードします。候補（いずれも富山市・CC BY・確認済み）：

候補 データ 公式ページ 主な列 形式
1 公衆無線LANアクセスポイント一覧 https://opdt.city.toyama.lg.jp/dataset/f9b8cc06-aba0-4d27-aefc-347c50e62726 名称・所在地・緯度・経度・設置者・電話・SSID CSV / UTF-8
2 福祉避難所 https://opdt.city.toyama.lg.jp/dataset/34b42b25-42f9-455c-aa7b-63f76b1f160d 施設・場所名・かな・住所・緯度・経度・連絡先 CSV / Shift-JIS
3 富山市地域・年齢別人口（H30.10.1時点） https://opdt.city.toyama.lg.jp/dataset/2585b8cf-e176-4273-bac1-a082eff60ca1 地域名・総人口・男性・女性・年齢階級別・世帯数 CSV / Shift-JIS
  • 前日までに自分でダウンロードして列名を確認（ページ・ファイル名・ライセンス=CC BY）
  • ダウンロードに失敗した人向けに、同じCSVを配布できるよう用意（USB/共有フォルダ。UTF-8変換版もあると親切）
  • 候補2・3は Shift-JIS。「文字化けしたらUTF-8に変換して読んで」とAIに頼めるよう案内（変換は許可が必要）
  • 「データが見つからないときはAIに創作させない」を徹底（プロンプトに含めてある）
  • 出典（富山市オープンデータ／CC BY）・取得日を画面に入れさせる
  • 補足：ゴミ収集日は富山市にCSVが無い（地区別はPDF/カレンダーのみ）ため候補にしない。子育て施設等はポータルでXLSX提供のため今回はCSV候補から除外。

メンター向け技術メモ（時間を溶かさないために）

  • 当日のアプリはデータをHTMLに埋め込む（実行時にCSVを読まない）方針。そのため index.html をダブルクリック（file:///C:/...）で開いても動作し、ローカルサーバーを立てる必要はない。
  • 逆に、外部ファイル（CSV等）を fetch する作りにすると file:// ではCORSで失敗する。CSVを差し替えて更新する作りは#3以降で扱う。
  • 会場で「サーバーを立てる」「python -m http.server」の話が出ても、今回は不要と伝えて止める。
  • 文字コードでつまずく場合（CSVのShift-JIS）：AIに「UTF-8に変換して読んで」と頼むか、メンターがUTF-8版を渡す。

終了条件・引き継ぎ

  • 参加者の画面でOpenCode Desktopが動いた
  • opencode.jsonc（外部フォルダdeny）が入り、拒否テストで断られた
  • index.html をブラウザで表示できた
  • 未完の人は氏名・進捗をメモし、もくもく会に引き継ぐ（無理に本編合流させない）