better doc

2026-05-12 11:16:35 +08:00 · 2026-02-27 01:11:57 +08:00
parent aea8844bac
commit 665831c774
46 changed files with 1217 additions and 3505 deletions
--- a/docs/ja/s02-tool-use.md
+++ b/docs/ja/s02-tool-use.md
@@ -1,37 +1,43 @@
-# s02: Tools
+# s02: Tool Use

-> ディスパッチマップがツール呼び出しをハンドラ関数にルーティングする -- ループ自体はまったく変更しない。
+`s01 > [ s02 ] s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
+
+> *"The loop didn't change"* -- ツール追加はハンドラ追加であり、ループの書き換えではない。

 ## 問題

-`bash`だけでは、エージェントはすべてをシェル経由で行う: ファイルの読み取り、書き込み、編集。これは動くが脆弱だ。`cat`の出力は予期しないタイミングで切り詰められる。`sed`による置換は特殊文字で失敗する。直接的な関数呼び出しの方がシンプルなのに、モデルはシェルパイプラインの構築にトークンを浪費する。
+`bash`だけでは、エージェントは何でもシェル経由で行う。`cat`は予測不能に切り詰め、`sed`は特殊文字で壊れ、すべてのbash呼び出しが制約のないセキュリティ面になる。`read_file`や`write_file`のような専用ツールなら、ツールレベルでパスのサンドボックス化を強制できる。

-さらに重要なのは、bashがセキュリティ上の攻撃面であること。bashの呼び出しはシェルでできることなら何でもできてしまう。`read_file`や`write_file`のような専用ツールがあれば、モデルが危険な操作を避けることを期待するのではなく、ツールレベルでパスのサンドボックス化や危険なパターンのブロックを強制できる。
-
-重要な洞察は、ツールを追加してもループを変更する必要がないということだ。s01のループはそのまま同一で維持される。ツール配列にエントリを追加し、ハンドラ関数を追加し、ディスパッチマップで接続するだけだ。
+重要な点: ツールを追加してもループの変更は不要。

 ## 解決策

 ```
-+----------+      +-------+      +------------------+
-|   User   | ---> |  LLM  | ---> | Tool Dispatch    |
-|  prompt  |      |       |      | {                |
-+----------+      +---+---+      |   bash: run_bash |
-                      ^          |   read: run_read |
-                      |          |   write: run_wr  |
-                      +----------+   edit: run_edit |
-                      tool_result| }                |
-                                 +------------------+
+--------+      +-------+      +------------------+
+|  User  | ---> |  LLM  | ---> | Tool Dispatch    |
+| prompt |      |       |      | {                |
+--------+      +---+---+      |   bash: run_bash |
+                    ^           |   read: run_read |
+                    |           |   write: run_wr  |
+                    +-----------+   edit: run_edit |
+                    tool_result | }                |
+                                +------------------+

-The dispatch map is a dict: {tool_name: handler_function}
+The dispatch map is a dict: {tool_name: handler_function}.
 One lookup replaces any if/elif chain.
 ```

 ## 仕組み

-1. 各ツールのハンドラ関数を定義する。各関数はツールのinput_schemaに対応するキーワード引数を受け取り、文字列の結果を返す。
+1. 各ツールにハンドラ関数を定義する。パスのサンドボックス化でワークスペース外への脱出を防ぐ。

 ```python
+def safe_path(p: str) -> Path:
+    path = (WORKDIR / p).resolve()
+    if not path.is_relative_to(WORKDIR):
+        raise ValueError(f"Path escapes workspace: {p}")
+    return path
+
 def run_read(path: str, limit: int = None) -> str:
    text = safe_path(path).read_text()
    lines = text.splitlines()
@@ -40,7 +46,7 @@ def run_read(path: str, limit: int = None) -> str:
    return "\n".join(lines)[:50000]
 ```

-2. ツール名とハンドラを結びつけるディスパッチマップを作成する。
+2. ディスパッチマップがツール名とハンドラを結びつける。

 ```python
 TOOL_HANDLERS = {
@@ -52,13 +58,14 @@ TOOL_HANDLERS = {
 }
 ```

-3. agent loop内で、ハードコードの代わりに名前でハンドラをルックアップする。
+3. ループ内で名前によりハンドラをルックアップする。ループ本体はs01から不変。

 ```python
 for block in response.content:
    if block.type == "tool_use":
        handler = TOOL_HANDLERS.get(block.name)
-        output = handler(**block.input)
+        output = handler(**block.input) if handler \
+            else f"Unknown tool: {block.name}"
        results.append({
            "type": "tool_result",
            "tool_use_id": block.id,
@@ -66,51 +73,7 @@ for block in response.content:
        })
 ```

-4. パスのサンドボックス化により、モデルがワークスペースの外に出ることを防ぐ。
-
-```python
-def safe_path(p: str) -> Path:
-    path = (WORKDIR / p).resolve()
-    if not path.is_relative_to(WORKDIR):
-        raise ValueError(f"Path escapes workspace: {p}")
-    return path
-```
-
-## 主要コード
-
-ディスパッチパターン(`agents/s02_tool_use.py` 93-129行目):
-
-```python
-TOOL_HANDLERS = {
-    "bash":       lambda **kw: run_bash(kw["command"]),
-    "read_file":  lambda **kw: run_read(kw["path"], kw.get("limit")),
-    "write_file": lambda **kw: run_write(kw["path"], kw["content"]),
-    "edit_file":  lambda **kw: run_edit(kw["path"], kw["old_text"],
-                                        kw["new_text"]),
-}
-
-def agent_loop(messages: list):
-    while True:
-        response = client.messages.create(
-            model=MODEL, system=SYSTEM, messages=messages,
-            tools=TOOLS, max_tokens=8000,
-        )
-        messages.append({"role": "assistant", "content": response.content})
-        if response.stop_reason != "tool_use":
-            return
-        results = []
-        for block in response.content:
-            if block.type == "tool_use":
-                handler = TOOL_HANDLERS.get(block.name)
-                output = handler(**block.input) if handler \
-                    else f"Unknown tool: {block.name}"
-                results.append({
-                    "type": "tool_result",
-                    "tool_use_id": block.id,
-                    "content": output,
-                })
-        messages.append({"role": "user", "content": results})
-```
+ツール追加 = ハンドラ追加 + スキーマ追加。ループは決して変わらない。

 ## s01からの変更点

@@ -121,10 +84,6 @@ def agent_loop(messages: list):
 | Path safety    | None               | `safe_path()` sandbox      |
 | Agent loop     | Unchanged          | Unchanged                  |

-## 設計原理
-
-ディスパッチマップパターンは線形にスケールする -- ツールの追加はハンドラ関数とスキーマエントリを1つずつ追加するだけだ。ループは決して変更しない。この関心の分離(ループ vs ハンドラ)こそが、エージェントフレームワークが制御フローの複雑さを増すことなく数十のツールをサポートできる理由だ。このパターンはまた、各ハンドラの独立テストも可能にする。ハンドラはループとの結合がない純粋関数だからだ。ディスパッチマップを超えるエージェントは、スケーリングの問題ではなく設計の問題を抱えている。
-
 ## 試してみる

 ```sh
@@ -132,10 +91,7 @@ cd learn-claude-code
 python agents/s02_tool_use.py
 ```

-試せるプロンプト例:
-
 1. `Read the file requirements.txt`
 2. `Create a file called greet.py with a greet(name) function`
 3. `Edit greet.py to add a docstring to the function`
 4. `Read greet.py to verify the edit worked`
-5. `Run the greet function with bash: python -c "from greet import greet; greet('World')"`