yorishiro 0.1.0 → 0.2.0

data/docs/ja/README.md

@@ -34,7 +34,9 @@ use provider: :anthropic, api_key: ENV["ANTHROPIC_API_KEY"], model: "claude-sonn
 
 allow_tool Yorishiro::Tools::ReadFile.new
 allow_tool Yorishiro::Tools::WriteFile.new
+allow_tool Yorishiro::Tools::EditFile.new
 allow_tool Yorishiro::Tools::ListFiles.new
+allow_tool Yorishiro::Tools::Grep.new
 allow_tool Yorishiro::Tools::ExecuteCommand.new,
   allow_commands: ["ls", "git *", "bundle exec *", "cat *"]
 
@@ -63,12 +65,17 @@ assistant> Hi! How can I help you today?
 - メッセージを入力し、**Enterを2回**押して送信
 - `Ctrl+C` または `/exit` で終了
 
+### セッションの永続化と再開
+
+会話は起動ディレクトリ配下の `.yorishiro/sessions/` に自動保存されます（毎ターン後と、長いツールループの途中でも逐次保存）。`yorishiro --continue`（直近）、`yorishiro --resume [ID]`（IDは前方一致可、省略時は選択画面）、または REPL 内の `/resume` で再開できます。`/clear` は新しいセッションを開始しますが、以前のセッションはディスクに残り再開可能です。セッションには作成時のプロバイダ/モデルが記録され、異なる構成で再開すると通知した上で現在の設定で続行します。ディレクトリごとに新しい50セッションが保持されます。
+
 ### スラッシュコマンド
 
 | コマンド | 説明 |
 |---------|------|
 | `/plan` | Planモードの切り替え |
-| `/clear` | 会話履歴をクリア |
+| `/clear` | 会話履歴をクリア（新しいセッションを開始） |
+| `/resume` | 保存済みセッションの一覧から再開 |
 | `/tools` | 登録済みツール一覧 |
 | `/skills` | 登録済みスキル一覧 |
 | `/exit` | 終了 |
@@ -80,6 +87,8 @@ assistant> Hi! How can I help you today?
 yorishiro --provider anthropic   # プロバイダ指定
 yorishiro --model gpt-4o         # モデル指定
 yorishiro --plan                 # Planモードで起動
+yorishiro --continue             # 直近のセッションを再開
+yorishiro --resume [ID]          # 保存済みセッションを再開（ID省略時は選択画面）
 yorishiro --version              # バージョン表示
 yorishiro --help                 # ヘルプ表示
 ```
@@ -119,14 +128,34 @@ use provider: :ollama, model: "llama3.1"
 # 基本ツール（許可不要）
 allow_tool Yorishiro::Tools::ReadFile.new
 allow_tool Yorishiro::Tools::ListFiles.new
+allow_tool Yorishiro::Tools::Grep.new
 
-# 書き込みツール（毎回許可確認）
+# 書き込み・編集ツール（毎回許可確認、diffプレビュー付き）
 allow_tool Yorishiro::Tools::WriteFile.new
+allow_tool Yorishiro::Tools::EditFile.new
 
 # コマンド実行ツール（パターンベース許可）
 allow_tool Yorishiro::Tools::ExecuteCommand.new,
   allow_commands: ["ls", "git *", "bundle exec *"]
+
+# サブエージェント（読み取り専用の調査を新しいコンテキストウィンドウへ委譲）
+allow_tool Yorishiro::Tools::Task.new
+```
+
+### サブエージェント（`task` ツール）
+
+`task` ツールを使うと、LLM は読み取り専用の調査タスク（定義箇所の特定、複数ファイルの要約など）を、独立したコンテキストウィンドウでエージェントループを回すサブエージェントに委譲できます。サブエージェントは登録済みの読み取り専用ツール（`read_file` / `list_files` / `grep`。`task` 自身は渡されないためネストしません）を使い、最終的なテキスト要約だけが親の会話に入ります。
+
+探索中のツール出力が親のコンテキストに入らないため、小さいローカルコンテキスト（例: Ollama の `num_ctx 8192`）では特に有効です。数ファイル読むだけでコンテキストを使い切る、という状況を避けられます。サブエージェントのツール呼び出しはインデント付きの進捗行として表示されます:
+
 ```
+[Tool] Executing: task(prompt: Find where sessions are persisted...)
+  [task] grep(pattern: def save)
+  [task] read_file(path: lib/yorishiro/session_store.rb)
+[Tool] Result: Sessions are saved to .yorishiro/sessions/<id>.json by...
+```
+
+ライフサイクルフック（`before_tool_use` / `after_tool_use`）はサブエージェントのツール呼び出しにも適用され、ループは最大15回で打ち切られます。読み取り専用ツールのため許可プロンプトは不要で、プランモードでも利用できます。
 
 ### コマンド実行の許可モデル
 
@@ -207,6 +236,66 @@ skill GitStatusSkill.new
 # => /git_status で利用可能
 ```
 
+文字列を返すスキルはその出力を表示するだけです。代わりに `prompt(...)` を返すと、
+そのテキストがユーザメッセージとしてLLMに注入され（Planモードも尊重して）実行されます。
+スキルからアシスタントにタスクを渡せます。
+
+```ruby
+class ReviewSkill < Yorishiro::Skill
+  def name = "review"
+  def description = "現在の git diff をレビュー"
+
+  def execute(_context)
+    prompt("あなたはコードレビュアーです。次のdiffをレビューして問題点を挙げてください:\n#{`git diff`}")
+  end
+end
+
+skill ReviewSkill.new
+# => /review で diff がLLMに渡り、エージェントループが実行される
+```
+
+スキルはファイル配置による自動読み込みもできます。`~/.yorishiro/skills/*.rb`（グローバル）
+または `./.yorishiro/skills/*.rb`（プロジェクトローカル）に `Yorishiro::Skill` の
+サブクラスを定義するだけで、起動時に自動登録されます（`skill ...` の呼び出しは不要）。
+同名のスキルが両方にある場合はプロジェクトローカル側が優先されます。
+
+```ruby
+# .yorishiro/skills/changelog.rb
+class ChangelogSkill < Yorishiro::Skill
+  def name = "changelog"
+  def description = "直近のコミットを要約"
+
+  def execute(_context)
+    prompt("次のコミットをチェンジログ向けに要約してください:\n#{`git log --oneline -20`}")
+  end
+end
+# => /changelog が自動で使えるようになる
+```
+
+### フック
+
+`.yorishirorc` からライフサイクルイベントにRubyブロックを登録できます:
+
+```ruby
+# 許可プロンプトの前にツール呼び出しを拒否する
+# （拒否理由はツール結果としてLLMに返り、LLMは方針転換できる）
+on :before_tool_use do |tool_name, args|
+  deny("rm is not allowed") if tool_name == "execute_command" && args["command"].to_s.include?("rm ")
+end
+
+# ツール実行結果の監査（フックが失敗しても警告表示のみ）
+on :after_tool_use do |tool_name, _args, result|
+  File.open(".yorishiro/audit.log", "a") { |f| f.puts "#{tool_name}: #{result.to_s[0, 100]}" }
+end
+
+# LLMに届く前にメッセージをブロックする
+on :user_prompt_submit do |input|
+  deny("秘密鍵は貼らないでください") if input.include?("BEGIN PRIVATE KEY")
+end
+```
+
+拒否は明示的に `deny("理由")`（または `:deny`）を返した場合のみです。それ以外の戻り値は続行するため、ログ出力だけのフックも安全に書けます。`before_tool_use` フックが例外を投げた場合は安全側に倒して拒否になります（fail closed）。フックはMCPツールとPlanモードにも適用されます。
+
 ### 設定例（フル）
 
 ```ruby
@@ -226,7 +315,9 @@ plan_mode false
 # 組み込みツール
 allow_tool Yorishiro::Tools::ReadFile.new
 allow_tool Yorishiro::Tools::WriteFile.new
+allow_tool Yorishiro::Tools::EditFile.new
 allow_tool Yorishiro::Tools::ListFiles.new
+allow_tool Yorishiro::Tools::Grep.new
 allow_tool Yorishiro::Tools::ExecuteCommand.new,
   allow_commands: [
     "ls *",
@@ -235,6 +326,7 @@ allow_tool Yorishiro::Tools::ExecuteCommand.new,
     "bundle exec *",
     "ruby *"
   ]
+allow_tool Yorishiro::Tools::Task.new
 
 # MCPサーバ
 mcp_server "filesystem",
@@ -248,8 +340,11 @@ mcp_server "filesystem",
 |-------|--------|------|------|
 | `read_file` | `Yorishiro::Tools::ReadFile` | ファイル内容を読み込む | 不要 |
 | `write_file` | `Yorishiro::Tools::WriteFile` | ファイルに書き込む | 毎回確認 |
+| `edit_file` | `Yorishiro::Tools::EditFile` | ファイル内の文字列を正確一致で置換 | 毎回確認 |
 | `list_files` | `Yorishiro::Tools::ListFiles` | ディレクトリ一覧・glob検索 | 不要 |
+| `grep` | `Yorishiro::Tools::Grep` | ファイル内容をRuby正規表現で検索 | 不要 |
 | `execute_command` | `Yorishiro::Tools::ExecuteCommand` | シェルコマンドを実行 | パターンベース |
+| `task` | `Yorishiro::Tools::Task` | 読み取り専用の調査を新しいコンテキストのサブエージェントへ委譲 | 不要 |
 
 ## 開発
 

data/docs/ja/ollama_setup.md

@@ -0,0 +1,148 @@
+# Ollama セットアップガイド（yorishiro 用）
+
+yorishiro をローカル Ollama で使うために必要な、Ollama サーバ側の設定手順。
+別の PC に環境を作るときはこのドキュメントに沿って設定する。
+
+## 検証済みの構成（このドキュメントの前提）
+
+| 項目 | 値 |
+|------|-----|
+| 実行環境 | WSL2 (Ubuntu) |
+| GPU | NVIDIA RTX 4070 Laptop (VRAM 8GB) |
+| Ollama | 0.30.9（systemd サービスとして稼働、実行ユーザー `ollama`） |
+| モデル | `gemma4:12b`（7.6GB — 8GB VRAM ではぎりぎり） |
+
+VRAM に余裕がある PC（12GB 以上など）では後述の KV キャッシュ量子化は必須ではないが、
+設定しておいて害はない。**VRAM がモデルサイズに対してぎりぎりの PC では必須**。
+
+## なぜ設定が必要か
+
+デフォルト設定のまま 8GB VRAM で `gemma4:12b` を動かすと、次の問題が起きる:
+
+- `num_ctx=8192` 時の KV キャッシュ／チェックポイントの読み書きが GB 単位で発生し、
+  ランナー（`llama-server`）が**長時間固まる**（クライアントのキャンセル後にスロット解放まで
+  21 分かかった実測あり）
+- WSL2 では CUDA のデバイス検出がタイムアウトし、Vulkan/D3D12 バックエンドへ
+  フォールバックすることがあり、これも固まりの一因になる
+- yorishiro は Ollama に対して read timeout を無効化している（ローカルモデルの初回
+  プロンプト評価が長いため）ので、サーバ側が固まると **CLI が無反応になり
+  クラッシュしたように見える**（実際にはクラッシュしていない）
+
+## サーバ側の設定（systemd オーバーライド）
+
+**重要:** Ollama は systemd サービス（実行ユーザー `ollama`）として動いているため、
+`~/.bashrc` などシェルの環境変数は**サーバに届かない**。
+サーバ向けの環境変数は必ず systemd の drop-in に書く。
+
+### 手順
+
+```bash
+sudo mkdir -p /etc/systemd/system/ollama.service.d
+sudo tee /etc/systemd/system/ollama.service.d/override.conf <<'EOF'
+[Service]
+Environment="OLLAMA_VULKAN=0"
+Environment="OLLAMA_FLASH_ATTENTION=1"
+Environment="OLLAMA_KV_CACHE_TYPE=q8_0"
+EOF
+
+sudo systemctl daemon-reload
+sudo systemctl restart ollama
+```
+
+### 各設定の意味
+
+| 環境変数 | 値 | 目的 |
+|----------|-----|------|
+| `OLLAMA_VULKAN` | `0` | Vulkan バックエンドを無効化。WSL2 で CUDA 検出がタイムアウトした際の Vulkan/D3D12 フォールバック（固まりの一因）を防ぐ |
+| `OLLAMA_FLASH_ATTENTION` | `1` | Flash Attention を有効化。KV キャッシュ量子化の前提条件でもある |
+| `OLLAMA_KV_CACHE_TYPE` | `q8_0` | KV キャッシュを 8bit に量子化。KV のメモリ使用量が約半分になり（実測 K/V 各 34MiB）、ぎりぎりの VRAM でも `num_ctx=8192` が回る |
+
+**q8_0 の副作用:** KV キャッシュのコンテキストシフトが無効になる。
+yorishiro は送信前に自前で履歴をコンテキスト予算内にトリム／要約するため、実用上問題ない。
+
+### 反映の確認
+
+```bash
+# 環境変数がサービスに載っているか
+systemctl show ollama -p Environment | tr ' ' '\n' | grep OLLAMA
+
+# 実際にランナーへ反映されているか（モデルロード直後のログに以下が出る）
+#   --cache-type-k q8_0 --cache-type-v q8_0 --flash-attn on
+journalctl -u ollama -n 100 --no-pager | grep "starting llama-server"
+```
+
+## モデルの用意
+
+```bash
+ollama pull gemma4:12b
+```
+
+VRAM が少ない PC ではより小さいモデル（`gemma3:4b`、`qwen2.5:3b` など）を検討する。
+yorishiro の対応モデルは Ollama インスタンスから動的に取得されるので、
+pull 済みのモデルなら何でも指定できる。
+
+## クライアント側（yorishiro）の設定
+
+`~/.yorishirorc`（または プロジェクトの `.lyorishirorc`）:
+
+```ruby
+use provider: :ollama, model: "gemma4:12b"
+```
+
+### コンテキストサイズ（重要な注意点）
+
+- yorishiro は Ollama へのリクエストに明示的な `num_ctx` を送る。デフォルトは **8192**
+- 変更する場合は `OLLAMA_NUM_CTX` 環境変数（クライアント側なのでシェルで OK）か、
+  rc ファイルの `ollama_num_ctx 16384` で指定
+- **4096 などに下げないこと。** yorishiro のコンテキスト予算は
+  `num_ctx − 2048（出力用リザーブ）` で計算されるため、4096 だと実質 2048 トークンしか
+  残らず、`read_file` 1回で溢れて「過剰トリム → 空応答」になる。デフォルトの 8192 を維持する
+- **上げる場合の目安（gemma4:12b + RTX 4070 8GB での実測、2026-07-07）:**
+  gemma4 はスライディングウィンドウ注意 + KV q8_0 のおかげで num_ctx を上げても
+  KV はほとんど増えない（131072 でも KV 合計 255MiB）。実測:
+
+  | num_ctx | 合計メモリ | CPU/GPU 分割 |
+  |---------|-----------|--------------|
+  | 8192    | 8.7 GB    | 32% / 68%    |
+  | 16384   | 8.7 GB    | 34% / 66%    |
+  | 32768   | 8.8 GB    | 35% / 65%    |
+  | 65536   | 9.0 GB    | 40% / 60%    |
+  | 131072  | 9.3 GB    | 45% / 55%    |
+  | 262144  | 10.0 GB   | 53% / 47%    |
+
+  **推奨は 16384**（メモリ増ほぼゼロで予算が 6144 → 14336 トークンに倍増。
+  prompt 評価 932 tok/s・生成 12.9 tok/s を実測）。32768 までは実用圏。
+  それ以上もロードは通るが GPU 比率が下がって生成が遅くなり、コンテキストを
+  実際に埋めたときの prompt 評価時間も長くなる（＝固まりと見分けにくくなる）
+- **上限は gemma4:12b の学習コンテキスト長 262144（256k）。** それを超える値
+  （524288 など）を指定しても Ollama がモデル上限へ黙ってクランプする
+  （`ollama ps` の CONTEXT 列とログの `n_ctx_slot` で確認可能）。
+  262144 はこの構成でもロード自体は通るが、GPU 比率が半分を切り、
+  仮にコンテキストを実際に埋めると prompt 評価だけで10分超かかる計算に
+  なるため実用は非推奨
+
+### その他のクライアント側環境変数
+
+| 環境変数 | デフォルト | 用途 |
+|----------|-----------|------|
+| `OLLAMA_NUM_CTX` | `8192` | コンテキストウィンドウ（上記の注意を参照） |
+| `OLLAMA_KEEP_ALIVE` | `10m` | モデルを VRAM に保持する時間。ターン間のロード待ちを防ぐ |
+| `OLLAMA_HOST` | `http://localhost:11434` | 別ホストの Ollama を使う場合に指定 |
+| `YORISHIRO_DEBUG` | - | `1` で Ollama へのリクエスト/レスポンスのデバッグログを出力 |
+
+## トラブルシューティング
+
+**症状: 応答が来ず CLI が無反応になる（クラッシュしたように見える）**
+
+1. まず本当に固まっているのか確認する。yorishiro は read timeout を無効化しているので、
+   初回のプロンプト評価（大きいコンテキストで数分）と固まりは見分けがつかない
+2. サーバ側の状態を見る:
+   ```bash
+   systemctl status ollama          # プロセス自体は生きているはず（Restart 履歴がないか）
+   journalctl -u ollama -f          # リクエストが処理中か、スロットが解放されないままか
+   nvidia-smi                       # VRAM 使用量とプロセスの有無
+   ```
+3. `starting llama-server` のログ行に `--cache-type-k q8_0 --flash-attn on` が
+   **含まれていない**場合、オーバーライドが効いていない。`daemon-reload` と `restart` を
+   やり直す（`sudo systemctl edit` で書いた場合はファイル名が `override.conf` かも確認）
+4. それでも固まりが頻発する場合は、より小さいモデルに切り替えるのが確実