webhand 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.ja.md ADDED
@@ -0,0 +1,89 @@
1
+ # webhand
2
+
3
+ [English](README.md) | 日本語
4
+
5
+ **人がサービスに慣れるように、サービスを学んでから操作するブラウザエージェントです。** Claude Code のプラグインとして動き、予約や申し込み、フォームへの入力などを言葉で頼むと、学んだことをもとにブラウザを操作して片付けます。
6
+
7
+ ```text
8
+ /webhand HOTEL PLANISPHERE で来月の土曜から2泊、2名で予約して
9
+ ```
10
+
11
+ - **サービスを学ぶ。** 人の操作の記録やサービスのソースコードから、ページの構成、手順、注意点を学び、サービス情報と手順書にまとめます。
12
+ - **学んだことをもとに操作する。** Claude が学んだ内容から GOAL、手順、入力値を計画し、Jev がサービス情報と計画をもとにクリックと入力を選びます。届かなければ、Claude が原因を考えて計画を見直します。
13
+ - **学ぶ前から使える。** 初めてのサイトでも、頼んだ内容から計画して操作します。よく使うサービスから学ばせていけます。
14
+
15
+ > ⚠️ **webhand が操作するページの内容は Jev(TypeSafe の API)に送られます。** 保存プロファイルを使う場合は、ログインしたページも含みます。[安全とプライバシー](#安全とプライバシー)を参照してください。
16
+
17
+ ## はじめに
18
+
19
+ 1. プラグインを追加します(Claude Code)。
20
+
21
+ ```text
22
+ /plugin marketplace add sakamoto66/webhand
23
+ /plugin install webhand@webhand
24
+ ```
25
+
26
+ 2. Jev の API キーを環境変数に設定し、Claude Code を起動し直します(`TYPESAFE_MODEL` で使うモデルも変えられます)。
27
+
28
+ ```bash
29
+ echo 'export TYPESAFE_API_KEY=...' >> ~/.bashrc # 使っているシェルの設定ファイルに
30
+ ```
31
+
32
+ 3. 用事を頼みます。
33
+
34
+ ```text
35
+ /webhand HOTEL PLANISPHERE で来月の土曜から2泊、2名で予約して
36
+ ```
37
+
38
+ 必要なもの: Node.js 22 以上と Google Chrome(Linux、または WSL から Windows 側。[WSL で Windows 側の Chrome を使う](docs/reference.ja.md#wsl-で-windows-側の-chrome-を使う)を参照)。CLI はインストール不要で、スキルが `npx -y webhand@0.3 ...` で実行します。毎回の起動を速くしたい場合は `npm i -g webhand` で入れておくと、スキルは `webhand ...` を使います。
39
+
40
+ ```bash
41
+ npx -y webhand@0.3 catalog # 動作確認
42
+ ```
43
+
44
+ ## しくみ
45
+
46
+ ```mermaid
47
+ flowchart LR
48
+ U([ユーザー]) -->|依頼| P[Claude: GOAL・手順・入力値を計画]
49
+ P --> R[Jev: 次の操作を選ぶ]
50
+ R -->|操作| B[(Chrome)]
51
+ B -->|観測| R
52
+ R -->|GOAL 到達 / 助けが必要| C{Claude: 確認}
53
+ C -->|完了| F([finish])
54
+ C -->|未達| P
55
+ C -->|入力値の不足・ログイン・CAPTCHA| U
56
+ ```
57
+
58
+ 1. **学習する**: `/webhand-learn` で、人の操作の記録、ソースコード、または過去の実行ログから、サービス情報と手順書を作ります。
59
+ 2. **頼む**: `/webhand ホテルを予約して` のように投稿します。Claude が学習済みのデータから GOAL、手順、入力値を計画し、足りない情報はユーザーに質問します。
60
+ 3. **セッションを選ぶ**: 新規(使い捨て、既定)か、ログイン状態を残した保存プロファイルかを選びます。
61
+ 4. **実行する**: 計画した URL を開きます。Jev は、サービス情報、計画、表示中のページ、これまでの操作履歴をもとに次の操作を選び、GOAL までループします。
62
+ 5. **見直す**: GOAL に届かなければ、Claude が原因を書いて計画を見直し、再挑戦します(既定で最大3回)。
63
+
64
+ 判断(計画、入力値、確認、見直し)は Claude が、クリックと入力の繰り返しは Jev が担います。Jev は、ページで見つけた要素と Claude が書いた入力値の中から選ぶだけです。Claude に制御が戻るのは、Jev が GOAL 到達を報告したとき、入力値や人の操作が必要なとき、行き詰まったとき、操作が効いたか分からないときだけです。一覧は[役割分担](docs/reference.ja.md#役割分担)にあります。
65
+
66
+ ## 安全とプライバシー
67
+
68
+ - **外部に送られるもの**: 操作中のページの文字と操作対象は Jev(TypeSafe の API)に送られます。保存プロファイルを使う場合は、ログインしたページも含みます。実行のたびに、送ってよい画面か判断してください。
69
+ - **プロファイル**: 既定では使い捨てのプロファイルを使い、実行が終わると削除します。ログイン状態は webhand 専用の保存プロファイル(`--session profile:NAME`)にだけ残し、実行ごとにユーザーが選びます。普段使いの Chrome プロファイルには接続しません。
70
+ - **資格情報**: パスワードや確認コードは、ユーザーが Chrome に直接入力します。Claude は受け取らず、webhand は password 欄の値を読みません。
71
+ - **推測で入力しない**: 入力されるのは、Claude が計画で書いた値と、あなたが渡した値だけです。足りなければ尋ねます。
72
+ - **やみくもに再試行しない**: ページへの変更操作はリトライしません。操作が効いたか分からないときは、繰り返さずに停止します。
73
+ - **ページの本文は信頼しない**: ページの内容はデータとして扱い、指示としては扱いません。
74
+ - **記録とログ**: 学習モードでは、パスワード、ワンタイムコード、カード番号などの欄と、URL のクエリ値をすべて伏せます。実行ログには、入力した値ではなく値のラベルを残します。それでも `~/.webhand/runs/` のログにはページの文字が残るため、共有しないでください。
75
+ - **使う前に確認**: 手順書は `draft` で作られ、ユーザーが `approved` にするまで通常の実行には使いません。秘密情報や個人情報は手順書に書かず、`params` で渡します。
76
+
77
+ ## ドキュメント
78
+
79
+ | 文書 | 内容 |
80
+ | --- | --- |
81
+ | [リファレンス](docs/reference.ja.md) | 保存場所、役割分担と結果、セッション、コマンド、学習モード、ページの領域、ログ |
82
+ | [利用ガイド](docs/usage.ja.md) | スキルと CLI の使い方、よくあるつまずき |
83
+ | [DEVELOPMENT.ja.md](DEVELOPMENT.ja.md) | 開発に参加する人向け。コード構成、規則、テスト、研究、リリース手順 |
84
+
85
+ ## ライセンス
86
+
87
+ MIT License(`LICENSE`)。
88
+
89
+ `assets/snapshot.js`、`src/policies/base.ts`、`src/policies/jev.ts`、`tasks/fixtures/hotel.html` は [jev-ultrafast](https://github.com/browser-use/jev-ultrafast)(MIT)を改変したものです。`THIRD_PARTY_LICENSE_jev-ultrafast.txt` を参照してください。
package/README.md CHANGED
@@ -1,253 +1,89 @@
1
1
  # webhand
2
2
 
3
- Claude が頭、Jev が手。Claude Code のスキルとして、Web ページでの用事を Claude と Jev が役割を分担して進めます。Claude は GOAL と手順の計画、入力値、結果の確認、計画の見直しを担い、Jev(TypeSafe)は GOAL までの操作を選びます。
3
+ English | [日本語](README.ja.md)
4
4
 
5
- Anthropic の API キーは使いません。作業中の Claude Code がスキルの手順に沿って CLI を実行し、Claude の役割を担います。**操作中のページの内容は Jev(TypeSafe の API)に送られます。**
5
+ **A browser agent that learns a service before operating it, the way people get used to a service.** It runs as a Claude Code plugin: ask in plain words for a booking, an application, or a form to fill in, and it operates the browser based on what it has learned.
6
6
 
7
- ## インストール
8
-
9
- 1. プラグインを追加します(Claude Code)。
10
-
11
- ```text
12
- /plugin install webhand --marketplace sakamoto66/webhand
13
- ```
14
-
15
- 2. Jev の API キーを環境変数に設定し、Claude Code を起動し直します(`TYPESAFE_MODEL` で使うモデルも変えられます)。
16
-
17
- ```bash
18
- echo 'export TYPESAFE_API_KEY=...' >> ~/.bashrc # 使っているシェルの設定ファイルに
19
- ```
20
-
21
- CLI はインストール不要です。スキルが `npx -y webhand@0.2 ...` で実行します。Node.js 22 以上と Google Chrome(Linux、または WSL から Windows 側)が必要です。毎回の起動を速くしたい場合は、`npm i -g webhand` で入れておくと、スキルは `webhand ...` を使います。
22
-
23
- ```bash
24
- npx -y webhand@0.2 catalog # 動作確認
7
+ ```text
8
+ /webhand On HOTEL PLANISPHERE, book 2 nights for 2 people starting next month's first Saturday
25
9
  ```
26
10
 
27
- ### 保存場所
28
-
29
- Claude Code の `~/.claude/` と `.claude/` と同じように、ユーザー単位とプロジェクト単位の2か所を使います。
11
+ - **It learns services.** From a recording of a person using a service, or from the service's source code, it learns the pages, the steps, and the pitfalls, and writes them down as service information and runbooks.
12
+ - **It operates from what it learned.** Claude plans the GOAL, steps, and input values from what was learned, and Jev picks each click and entry from the service information and the plan. If the GOAL is not reached, Claude works out why and replans.
13
+ - **It works before learning, too.** On a site it has never seen, it plans from your request alone. You can teach it the services you use most, one at a time.
30
14
 
31
- | 場所 | パス | 内容 |
32
- | --- | --- | --- |
33
- | ユーザー | `~/.webhand/`(`WEBHAND_HOME` で変更可) | `runbooks/`(どのプロジェクトでも使うサービス情報と手順書)、`runs/`(実行と学習の記録。ページ本文を含む)、`state/`(実行中のセッションと保存プロファイル) |
34
- | プロジェクト | 現在のディレクトリから上にたどって最初に見つかる `.webhand/`(ホームディレクトリで止まる) | `runbooks/`(そのプロジェクトのサービス情報と手順書。git で共有できる) |
15
+ > ⚠️ **The content of the pages webhand operates is sent to Jev (the TypeSafe API)**, including pages you are logged in to when you use a saved profile. See [Safety and privacy](#safety-and-privacy).
35
16
 
36
- - 手順書とサービス情報は、プロジェクト、ユーザーの順に探します。同じ名前ならプロジェクトのものを使います。`catalog` は両方を一覧し、それぞれの出所を `(project)` / `(user)` で示します。
37
- - `learn` は既定でプロジェクトに書きます(`.webhand/` がなければ git のルート、なければ現在のディレクトリに作ります)。`--scope user` でユーザーに書きます。
38
- - ログイン状態と実行記録はユーザー単位にだけ置き、プロジェクトには置きません。API キーはファイルに置かず、環境変数(`TYPESAFE_API_KEY`)からだけ読みます。
17
+ ## Quick start
39
18
 
40
- ```
41
- Claude Code ── /webhand-learn ──> .webhand/runbooks/<service>/ または ~/.webhand/runbooks/<service>/
42
- │
43
- └──────── /webhand ── CLI webhand ── CDP ──> Chrome(新規 / 保存プロファイル、WSL では Windows 側も可)
44
- 計画・入力値・確認・見直し └── run ──> Jev(GOAL までの操作を選択)
45
- ```
19
+ 1. Add the plugin in Claude Code.
46
20
 
47
- ## ユーザー体験
48
-
49
- 1. **学習する**: `/webhand-learn` で、人の操作の記録またはソースコードから、サービス情報と手順書を作ります。
50
- 2. **頼む**: `/webhand ホテルを予約して` のように投稿します。Claude が学習済みのデータから GOAL、手順、入力値を計画し、足りない情報はユーザーに質問します。
51
- 3. **セッションを選ぶ**: 新規(使い捨て)か、ログイン状態を残した保存プロファイルかを選びます。
52
- 4. **実行する**: 計画した URL を開きます。Jev は、サービス情報、計画、表示中のページ、これまでの操作履歴をもとに次の操作を選び、GOAL までループします。
53
- 5. **見直す**: GOAL に届かなければ、Claude が原因を書いて計画を見直し、再挑戦します(既定で最大3回)。
54
-
55
- ## 役割分担
56
-
57
- | 担当 | 役割 |
58
- | --- | --- |
59
- | Claude | GOAL と手順を計画する、入力値を書く、足りない情報を質問する、結果を確認する、計画を見直す、実行を締める |
60
- | Jev | GOAL までの操作ごとに、対象の要素と Claude の入力値のどれを使うかを番号で選ぶ |
61
- | コード | 選択を観測済み要素と Claude の値に限定し、鮮度を確認して実行する。独立検証を行う |
21
+ ```text
22
+ /plugin marketplace add sakamoto66/webhand
23
+ /plugin install webhand@webhand
24
+ ```
62
25
 
63
- `run` は、次のいずれかの場合にだけ Claude に制御を返します。
26
+ 2. Set Jev's API key as an environment variable and restart Claude Code. (`TYPESAFE_MODEL` selects the model.)
64
27
 
65
- | 結果 | 発生条件 | Claude の対応 |
66
- | --- | --- | --- |
67
- | `GOAL_REPORTED` | Jev が GOAL 達成を申告した | ページを GOAL と照合し、`finish` か `replan` |
68
- | `NEEDS_VALUE` | 入力欄に合う値が計画にない | `run --value "ラベル=値"`。わからなければユーザーに聞く |
69
- | `NEEDS_HUMAN` | ログイン、認証コード、CAPTCHA、`[person]` の手順 | ユーザーに依頼し、`run --human-done` |
70
- | `BLOCKED` / `STUCK` / `ATTEMPT_BUDGET` | 進めなくなった | `replan` で再挑戦、`act` で1手補う、または `finish` |
71
- | `JEV_FAILED` | Jev の応答が使えない(何も実行していない) | もう一度 `run`、`replan`、または `act` |
72
- | `UNCERTAIN` | 操作が実行されたかどうか不明 | 繰り返さず、`finish --status error` |
28
+ ```bash
29
+ echo 'export TYPESAFE_API_KEY=...' >> ~/.bashrc # or your shell's profile
30
+ ```
73
31
 
74
- 確信度は記録しますが、Jev を止める条件には使いません。
32
+ 3. Ask for something.
75
33
 
76
- ## セッション
34
+ ```text
35
+ /webhand On HOTEL PLANISPHERE, book 2 nights for 2 people starting next month's first Saturday
36
+ ```
77
37
 
78
- | `--session` | 内容 |
79
- | --- | --- |
80
- | `new`(既定) | 一時プロファイル。ログインしていない状態で始まり、終了時に削除されます |
81
- | `profile:NAME` | webhand 専用の保存プロファイル。ログイン状態が次回も残ります |
38
+ Requirements: Node.js 22 or later and Google Chrome (on Linux, or the Windows side from WSL; see [Using Windows Chrome from WSL](docs/reference.md#using-windows-chrome-from-wsl)). The CLI needs no installation: the skills run it with `npx -y webhand@0.3 ...`. For faster startup, install it globally with `npm i -g webhand`; the skills then use `webhand ...`.
82
39
 
83
40
  ```bash
84
- webhand profile login work --url https://example.com/login # 人がログインしてウィンドウを閉じる
85
- webhand profile list
86
- webhand profile delete work
87
- ```
88
-
89
- 普段使いの Chrome プロファイルには接続しません。Chrome 136 以降は、既定のプロファイルへのデバッグ接続ができないためです。保存プロファイルは、Linux では `~/.webhand/state/profiles/`、Windows では `%LOCALAPPDATA%\webhand\profiles\` に置かれます。
90
-
91
- **ログイン後のページの内容は Jev(TypeSafe の API)に送られます。** 個人情報を含む画面を扱うかどうかは、実行前に判断してください。
92
-
93
- ## WSL で Windows 側の Chrome を使う
94
-
95
- `--chrome auto`(既定)は、WSL 上で Windows の `chrome.exe` に接続できればそれを使い、できなければ Linux の Chrome を使います。`--chrome windows` または `--chrome linux` で固定でき、`WEBHAND_CHROME` でも指定できます。
96
-
97
- Windows の Chrome は、デバッグポートを Windows の 127.0.0.1 で待ち受けます。そのため、WSL のネットワークを mirrored にする必要があります。
98
-
99
- ```ini
100
- # %USERPROFILE%\.wslconfig
101
- [wsl2]
102
- networkingMode=mirrored
103
- ```
104
-
105
- 設定したら、PowerShell で `wsl --shutdown` を実行して WSL を再起動します。ローカルファイルの URL は `file://wsl.localhost/...` に変換して開きます。
106
-
107
- ## 使い方
108
-
109
- Claude Code のセッションで、スキルを呼び出します。
110
-
111
- ```text
112
- /webhand HOTEL PLANISPHERE で来月の土曜から2泊、2名で予約して
41
+ npx -y webhand@0.3 catalog # smoke check
113
42
  ```
114
43
 
115
- 下の表の `webhand` は、インストールしていなければ `npx -y webhand@0.2` と読み替えてください。`webhand --version` で版を確認できます。
116
-
117
-
118
- | コマンド | 担当 | 内容 |
119
- | --- | --- | --- |
120
- | `webhand catalog` | Claude | 学習済みのサービス、手順書、保存プロファイルを一覧する |
121
- | `webhand start --goal G --url U --step S ... --value L=V ... --session ...` | Claude | 計画を記録し、Chrome で開始 URL を開く |
122
- | `webhand run` | Jev | GOAL まで操作する |
123
- | `webhand replan --reason R [--step ...] [--value ...] [--focus ...] [--skip ...] [--restart]` | Claude | 計画を見直して、次の試行を始める |
124
- | `webhand act OP [TARGET]` | Claude | Jev の代わりに操作を1つ実行する |
125
- | `webhand observe` | Claude | 現在のページを表示する |
126
- | `webhand finish --status STATUS` | Claude | 独立検証、ログ記録、Chrome の終了 |
127
- | `webhand learn --name NAME --url URL [--scope project\|user]` | 人 | 操作を記録する |
128
- | `webhand profile login/list/delete` | 人 | 保存プロファイルを管理する |
129
-
130
- 手順の先頭に `[person]` を付けると、人が行う手順になります(`--headed` が必須です)。`start` と `replan` の `--focus REGION` / `--skip REGION` で、観測する領域を選べます(下の「ページの領域」)。`--runbook NAME --param k=v` を指定すると、手順書の GOAL、開始 URL、手順が既定値になり、params は入力値として Jev に渡されます。
131
-
132
- ## 学習モード
133
-
134
- 人の操作、またはサービスのソースコードから、次の2種類のファイルを作ります。
135
-
136
- | ファイル | 内容 | 使われ方 |
137
- | --- | --- | --- |
138
- | `runbooks/<service>/service.toml` | サービスの説明、ログインの要否、ページと領域の一覧、Jev 向けの事実 | `catalog` で Claude が読み、`--service` で Jev に渡す |
139
- | `runbooks/<service>/<name>.toml` | 手順書(goal、params、steps、hints、done_when、focus、skip) | Claude の計画の下敷き。手順と hints は Jev にも渡す |
140
-
141
- どちらも、プロジェクトの `.webhand/` かユーザーの `~/.webhand/` に置きます(「保存場所」)。`learn` は書き込み先を `WRITE THE RUNBOOK TO ...` として表示します。`start_url` にローカルファイルの相対パスを書くと、その `.webhand/` を含むディレクトリからのパスになります。
142
-
143
- ```text
144
- /webhand-learn --name myservice/search --url https://example.com
44
+ ## How it works
45
+
46
+ ```mermaid
47
+ flowchart LR
48
+ U([You]) -->|request| P[Claude: plan GOAL, steps, values]
49
+ P --> R[Jev: pick the next action]
50
+ R -->|act| B[(Chrome)]
51
+ B -->|observe| R
52
+ R -->|GOAL reached or needs help| C{Claude: check}
53
+ C -->|done| F([finish])
54
+ C -->|not yet| P
55
+ C -->|missing value, login, CAPTCHA| U
145
56
  ```
146
57
 
147
- 1. `webhand learn` が Chrome を開き、ユーザーの操作を記録します。ウィンドウを閉じると終了します。ログインした状態で操作を見せる場合は、`--session profile:NAME` を付けます。バックグラウンドのジョブを止めても(SIGTERM、または npx の終了)、記録を保存して Chrome を閉じます。
148
- 2. Claude が記録またはソースコードから、サービス情報と手順書の下書きを書きます。
149
- 3. `--runbook NAME --param k=v --allow-draft` で試行します。
150
- 4. ユーザーが内容を確認し、`status = "approved"` にします。
151
-
152
- 手順書は機械的に再生しません。
153
-
154
- 記録の扱い:
155
-
156
- - キー入力は記録しません。パスワード、ワンタイムコード、カード番号などの欄の値は `<redacted>` になります。ただし秘匿の判定は欄の属性と名前によるため、見分けられない欄の値は `runs/` の記録に残ります
157
- - URL のクエリの値はすべて伏せます
158
- - 記録はワークスペースの `runs/` に保存されます。ページ本文を含むため、共有しないでください
159
- - iframe 内の操作、ファイル選択、新しいタブは再現できないため、`unsupported` として残します
160
- - ページのスクリプトは記録を偽装できるため、記録は信頼せず、手順書はユーザーが承認します
161
-
162
- ## ページの領域
58
+ 1. **Learn**: `/webhand-learn` turns a recorded demonstration, the service's source code, or the log of an earlier run into service information and a runbook.
59
+ 2. **Ask**: Post a request such as `/webhand book a hotel`. Claude plans the GOAL, steps, and input values from what webhand has learned, and asks you for anything missing.
60
+ 3. **Choose a session**: A fresh, throwaway session (the default), or a saved profile that keeps you logged in.
61
+ 4. **Run**: The planned URL opens. Jev picks the next action from the service information, the plan, the current page, and the action history, and loops until the GOAL.
62
+ 5. **Replan**: If the GOAL is not reached, Claude writes down why, revises the plan, and tries again (up to 3 attempts by default).
163
63
 
164
- 観測は、テキスト 6000 文字、操作 250 件が上限です。ページは領域(header、nav、main、form、fieldset、table、dialog、ラベル付きの section など)に分けて観測します。領域のキーは、外側の領域からの並びです。
64
+ Claude makes the judgment calls (the plan, the values, the check, the replan), and Jev makes the many clicks and entries in between. Jev only chooses among the elements found on the page and the values Claude wrote. Control returns to Claude only when Jev reports the GOAL, needs a value or a person, gets stuck, or cannot tell whether an action took effect. The full list is in [Division of roles](docs/reference.md#division-of-roles).
165
65
 
166
- ```text
167
- main/form:宿泊予約/fieldset:追加プラン # 種類:名前。名前は aria-label、legend、caption、領域の先頭の見出しから取る
168
- nav#2 # 名前のない同じ種類が並ぶときは順番
169
- ```
170
-
171
- - 観測結果の `regions` には、領域ごとに位置(`above` / `visible` / `below`)、テキストと操作の表示数と全数、画面外の操作の数が入ります。Claude には `REGIONS`、Jev には `page.regions` として渡ります。何が切り捨てられたかがわかります。
172
- - `focus` の領域は先頭に並び、テキストはページ全体から取ります。`skip` の領域は要約にだけ出ます。どちらもないときは、今までどおり画面内を DOM 順に取ります。開いた dialog は、view があるときは常に先頭です。
173
- - パターンはキーのどこに一致してもよく、一致した領域の内側も含みます。名前や番号のない段(`form`)は、その種類のどの領域にも一致します。focus と skip の両方に一致したら、深いほうが勝ちます(同じ深さなら focus)。
174
- - 操作の対象は今までどおり画面内だけです。鮮度の判定(`marker`、`page_key`、`guards`)は、view に関係なく同じ入力から計算します。
175
- - view は、service.toml の `default`、手順書の `focus` / `skip`、Claude の `--focus` / `--skip` の順に重ね、後のものが勝ちます。`run_start` と `plan` のイベントに `view` が残ります。
176
-
177
- ```toml
178
- # service.toml
179
- [[pages.regions]]
180
- key = "main/form:宿泊予約"
181
- purpose = "予約フォーム"
182
- [[pages.regions]]
183
- key = "footer"
184
- purpose = "サイト共通のリンク"
185
- default = "skip" # focus か skip。なしなら通常
186
-
187
- # 手順書
188
- focus = ["form:宿泊予約"]
189
- skip = ["header", "footer"]
190
- ```
66
+ ## Safety and privacy
191
67
 
192
- 学習の記録では、`page` イベントに領域の要約(キーと件数だけ)、`action` イベントに対象の領域キーが入ります。秘密に見える名前の段は `form:<redacted>` になります。
68
+ - **What leaves your machine**: The text and actions of the page being operated go to Jev (the TypeSafe API). With a saved profile, that includes pages you are logged in to. Decide before each run whether that is acceptable.
69
+ - **Profiles**: Runs use a temporary profile by default, deleted when the run ends. Login state lives only in profiles dedicated to webhand (`--session profile:NAME`), which you choose per run. webhand never connects to your everyday Chrome profile.
70
+ - **Credentials**: You type passwords and codes into Chrome yourself. Claude does not receive them, and webhand does not read the values of password fields.
71
+ - **No guessed input**: The only values entered are the ones Claude wrote in the plan and the ones you gave. If something is missing, it asks.
72
+ - **No blind retries**: A change to the page is never retried. If webhand cannot tell whether an action took effect, it stops instead of trying again.
73
+ - **Page text is untrusted**: Content on the page is treated as data, never as instructions.
74
+ - **Recordings and logs**: Learning mode masks password, one-time code, and card fields and all URL query values. Run logs keep the label of each typed value, not the value. Logs under `~/.webhand/runs/` still contain page text, so do not share them.
75
+ - **Review before use**: Runbooks start as `draft` and are used for normal runs only after you set them to `approved`. Keep secrets and personal data out of runbooks; pass them as `params`.
193
76
 
194
- `verify()` のないサービスでは `verified` は `None` です。手順書の `done_when` は Claude の確認材料で、成功の証拠にはなりません。
77
+ ## Documentation
195
78
 
196
- ## ログ
197
-
198
- ワークスペースの `runs/<時刻>/` に JSONL で出力されます。
199
-
200
- | type | 内容 |
79
+ | Document | Contents |
201
80
  | --- | --- |
202
- | `run_start` | 目標、Chrome(linux / windows)、セッションの種類、git commit、手順書、サービス |
203
- | `plan` | 試行ごとの手順、入力値のラベル、その出所(`claude` / `runbook`)、`restart` |
204
- | `call` | Jev の呼び出しごとのトークンと遅延 |
205
- | `step` / `step_result` | 実行した操作、試行番号、判断者、確信度、ページの変化 |
206
- | `escalation` | `run` が Claude に返した結果 |
207
- | `human_step` / `values` | 人の手順の依頼と完了、追加された入力値のラベル |
208
- | `attempt_end` | 試行の結果と、Claude が書いた見直しの理由 |
209
- | `handoff` | Claude が読む CLI 出力の文字数 |
210
- | `run_end` | 自己申告の状態、独立検証の結果、試行回数と試行ごとの結果、役割ごとの集計 |
211
-
212
- 成功判定は `run_end.verified` です。`status=done` は申告にすぎません。Claude Code のトークン数は取得しないため、`handoffs`(Claude に戻した回数)と `handoff_chars`(読ませた文字数)を代理指標にします。
213
-
214
- ## タスクの追加(研究用)
215
-
216
- タスクは研究用リポジトリの `tasks/` にだけ置き、npm の配布物には含めません。`tasks/<名前>.ts` で次を export します。
217
-
218
- - `GOAL`: 自然言語の目標
219
- - `startUrl(root)`: 開始 URL(`root` はリポジトリのルート)
220
- - `verify(browser)`: `{success, evidence}` を返す独立検証(async)
221
- - `SCRIPT`: 基盤の動作確認用の固定手順
222
-
223
- `--task` はリポジトリのルートで実行します。Node の型除去でそのまま読み込むため、型注釈を消すだけで動く構文で書きます(Node 22.18 以上)。
224
-
225
- ## 開発
226
-
227
- このリポジトリは研究基盤も兼ねています(実験設計は `docs/research-plan.md`)。TypeScript で書かれ、Node.js 22 以上で動きます(開発は Node 24)。リポジトリの `.webhand/runbooks/` が、このリポジトリのプロジェクト単位の手順書です。
228
-
229
- ```bash
230
- npm ci
231
- npm run build && npm link # webhand コマンドを作業ツリーのビルドに向ける
232
- claude --plugin-dir .
233
- ```
234
-
235
- 実行記録をリポジトリの `runs/` に残したい場合は、`.claude/settings.local.json` に `{"env": {"WEBHAND_HOME": "<このリポジトリの絶対パス>"}}` を書きます。このときユーザー単位の手順書は `~/.webhand/runbooks/` ではなく、リポジトリの `runbooks/` から読みます。
236
-
237
- ```bash
238
- npm run lint # Biome
239
- npm run typecheck
240
- npm test # 有料 API は呼びません。Linux の Chrome を使います
241
- npm run test:coverage # カバレッジ(coverage/index.html)
242
- npm run smoke -- --task hotel_filter # モデルなしの動作確認
243
- ```
244
-
245
- `tests/golden/` は Python 版の出力の記録です。Claude と Jev が読む文字列(`render`、`report`、Jev への state と質問など)が移行の前後で同じであることを確かめます。
246
-
247
- 公開は `npm publish`(`prepublishOnly` で lint、型チェック、ビルド)です。`package.json` と `.claude-plugin/plugin.json` の版を揃え、スキルの `webhand@0.2` も合わせて更新します。
81
+ | [Reference](docs/reference.md) | Where files live, roles and results, sessions, commands, learning mode, page regions, logs |
82
+ | [Usage guide](docs/usage.md) | Skills and CLI step by step, common pitfalls |
83
+ | [DEVELOPMENT.md](DEVELOPMENT.md) | For contributors: code layout, rules, tests, research, release steps |
248
84
 
249
- ## ライセンス
85
+ ## License
250
86
 
251
- MIT License(`LICENSE`)。
87
+ MIT License (`LICENSE`).
252
88
 
253
- `assets/snapshot.js`、`src/policies/base.ts`、`src/policies/jev.ts`、`tasks/fixtures/hotel.html` は [jev-ultrafast](https://github.com/browser-use/jev-ultrafast)(MIT)を改変したものです。`THIRD_PARTY_LICENSE_jev-ultrafast.txt` を参照してください。
89
+ `assets/snapshot.js`, `src/policies/base.ts`, `src/policies/jev.ts`, and `tasks/fixtures/hotel.html` are modified from [jev-ultrafast](https://github.com/browser-use/jev-ultrafast) (MIT). See `THIRD_PARTY_LICENSE_jev-ultrafast.txt`.
@@ -528,7 +528,12 @@
528
528
  }
529
529
  chosen = chosen.slice(0, MAX_ACTIONS);
530
530
  const omitted_actions = actions.length - chosen.length;
531
- for (const action of chosen) actionRegions.get(action).shown_actions++;
531
+ // The region key goes on the action for the run log only; the marker above was taken without it.
532
+ for (const action of chosen) {
533
+ const region = actionRegions.get(action);
534
+ region.shown_actions++;
535
+ action.region = region.key;
536
+ }
532
537
  chosen.forEach((action, index) => action.id = 'e' + (index + 1));
533
538
  if (scrollY + innerHeight < height - 2) {
534
539
  chosen.push({id: 'scroll_down', kind: 'scroll', label: 'Scroll down', delta: SCROLL_STEP});
package/dist/agent.js CHANGED
@@ -3,7 +3,8 @@
3
3
  *
4
4
  * The loop returns to Claude only when it cannot continue on its own. The task's verify() decides success.
5
5
  */
6
- import { pyRepr, pyRound } from "./py.js";
6
+ import { quote } from "./format.js";
7
+ import { pageEvent, safeUrl } from "./metrics.js";
7
8
  import { MutationUncertain, PolicyError, StalePage, } from "./types.js";
8
9
  // Why the loop handed control back to Claude.
9
10
  export const GOAL_REPORTED = "GOAL_REPORTED"; // Jev chose DONE. Claude checks the page; finish verifies.
@@ -36,6 +37,16 @@ function stuck(history, attempt = 1) {
36
37
  const recent = history.filter((h) => (h.attempt ?? 1) === attempt && h.kind !== "human").slice(-3);
37
38
  return recent.length === 3 && recent.every((s) => s.page_changed === false && s.kind !== "wait");
38
39
  }
40
+ /** A step for the run log: the value's label instead of the typed text, and the URL without query values. */
41
+ function logged(step, region, values) {
42
+ const { text, url, ...rest } = step;
43
+ const entry = { ...rest, region: typeof region === "string" ? region : null };
44
+ entry.url = safeUrl(url);
45
+ entry.value = text === null ? null : (values.find((v) => v.value === text)?.label ?? null);
46
+ if (text !== null)
47
+ entry.text_chars = [...String(text)].length;
48
+ return entry;
49
+ }
39
50
  /** Runs once. Logged before the next observation so a navigation cannot erase it. */
40
51
  export async function execute(browser, page, decision, history, recorder, options) {
41
52
  const onChange = options.onChange ?? (() => { });
@@ -54,11 +65,13 @@ export async function execute(browser, page, decision, history, recorder, option
54
65
  page_changed: null,
55
66
  };
56
67
  history.push(step);
57
- recorder.event("step", step);
68
+ recorder.event("step", logged(step, action.region, options.values ?? []));
58
69
  onChange(page);
59
70
  const newPage = await browser.observe();
60
71
  step.page_changed = !sameMarker(newPage.marker, page.marker);
61
72
  recorder.event("step_result", { step: step.step, page_changed: step.page_changed });
73
+ if (step.page_changed)
74
+ recorder.event("page", pageEvent(newPage, options.attempt));
62
75
  onChange(newPage);
63
76
  return newPage;
64
77
  }
@@ -86,7 +99,7 @@ export async function runAgent(browser, policy, plan, recorder, budget = new Bud
86
99
  page,
87
100
  actions: actionsIn(history, attempt).length,
88
101
  decisions,
89
- elapsed_ms: pyRound(performance.now() - started),
102
+ elapsed_ms: Math.round(performance.now() - started),
90
103
  ...extra,
91
104
  });
92
105
  while (true) {
@@ -136,6 +149,7 @@ export async function runAgent(browser, policy, plan, recorder, budget = new Bud
136
149
  decidedBy: policy.name,
137
150
  attempt,
138
151
  onChange,
152
+ values: plan.values,
139
153
  });
140
154
  }
141
155
  catch (error) {
@@ -149,7 +163,7 @@ export async function runAgent(browser, policy, plan, recorder, budget = new Bud
149
163
  attempt,
150
164
  operation: "STALE",
151
165
  kind: STALE,
152
- action: `${decision.operation} ${pyRepr(decision.action.label)} did not run: ${error.message}`,
166
+ action: `${decision.operation} ${quote(decision.action.label)} did not run: ${error.message}`,
153
167
  text: null,
154
168
  url: observed.url,
155
169
  // Unchanged: the same choice would be refused again, so it counts toward STUCK.
package/dist/bin.js CHANGED
File without changes
package/dist/browser.js CHANGED
@@ -2,7 +2,7 @@
2
2
  import { readFileSync } from "node:fs";
3
3
  import { isDeepStrictEqual } from "node:util";
4
4
  import { chromium, } from "playwright-core";
5
- import { sleep } from "./py.js";
5
+ import { sleep } from "./format.js";
6
6
  import { MutationUncertain, StalePage } from "./types.js";
7
7
  export function asset(name) {
8
8
  return readFileSync(new URL(`../assets/${name}`, import.meta.url), "utf8");