sync: update from private repo (2336949a)

2026-09-17 11:29:31 +00:00
parent 28f74c4e37
commit 57702b4f34
2139 changed files with 321270 additions and 17494 deletions
@@ -0,0 +1,55 @@
+# RequestCaptchaHelp
+
+検索が「人かどうかの確認（CAPTCHA）」で**完全に塞がれた**ときに、人が確認を済ませるまで作業を止めて待つためのツール（issue #1199 段階 2）。
+
+## いつ使うか
+
+`WebSearch` がこの形で失敗したときだけ:
+
+```
+WebSearch error: ブラウザ検索がすべて CAPTCHA で止められ、SearXNG も結果を返しませんでした。
+検索そのものが実行できていません。
+```
+
+そのうえで、**検索なしではその依頼を達成できない**ときに呼ぶ。
+
+呼ぶ前に確かめること:
+
+- URL が分かっているなら `WebFetch` で直接開けば済まないか
+- すでに手元にある資料や `Read` で足りないか
+- 検索がそもそも本筋でない依頼ではないか（雑談・要約・書き換えなど）
+
+止まっているあいだ、利用者は確認画面を開いて操作する必要がある。**避けられるなら避けたい手間**なので、他に道が無いときだけ呼ぶこと。
+
+## 引数
+
+| 引数 | 必須 | 説明 |
+|------|------|------|
+| `reason` | いいえ | 検索が通らないと進められない理由。カードを見る人が読む |
+
+## 呼んだあと何が起きるか
+
+1. その movement が畳まれ、ジョブが「人の確認待ち」で**停車**する（ワーカーは解放される）
+2. 確認カードが出るのは**元のタスクのチャット**。サブタスクの中で呼んだ場合も、親をたどった先の元のタスクへ出る（#1225）
+3. 誰かが確認を済ませて「解決した」を押すと、**その確認画面で止まっているジョブがまとめて再開**する
+4. 「スキップ」を押した場合は、押したタスクのジョブと**その配下で確認待ちのサブタスク**だけが、検索が使えないまま再開する
+5. 再開すると同じステップの頭からやり直しになるので、もう一度 `WebSearch` を呼ぶこと
+
+## 止まらないことがある
+
+次のときは停車せず、エラーとして「続けてください」が返る。**呼べば必ず止まるツールではない**。
+
+| 返る内容 | 意味 |
+|---|---|
+| この実行では人の確認を待てません | 親をたどっても元のタスクに行き着かない実行（チャットに紐づかない実行）。確認カードを出す先が無いので、止めても押す相手が居ない。検索抜きで組み立てるか `complete` で中断する |
+| まだ検索が塞がっていません | この実行の `WebSearch` が上のエラーで失敗していない。SearXNG 経由で結果が出ているなら塞がっていない |
+| 未解決の求めは残っていません | 確認画面に立っていた旗がもう下りている（誰かが解いた・画面が無い）。もう一度 `WebSearch` を試す |
+
+待てるかどうかの判断は「サブタスクかどうか」では決まらない（#1225）。サブタスクでも、親をたどって元のタスクに行き着くなら待てる。行き着かない実行だけが上の 1 行目に当たる。
+
+確認画面はワークスペース単位で共有される。同じワークスペースの誰かが一度解けば、そのあとの検索は通る。
+
+## 関連
+
+- 検索そのものは [WebSearch](websearch.md)
+- 停車と再開の仕組み（sentinel）は [movement 制御フローツール](../movement-control-flow-tools.md)