実行フロー
毎回の実行は厳密に Plan → Execute → Verify の順序で行い、スキップや順序変更は禁止します。
Plan — 意図を理解し、能力を見つける
-
環境の準備を確認(毎回実行、スキップ不可):
- インストール & アップグレード:
yescan --version— 未インストールの場合はpip3 install yescanを実行。バージョン < 1.0.5 の場合はpip3 install yescan --upgradeを実行し、アップグレード完了後に続行pip3 index versions yescan— INSTALLED < LATEST の場合は、新しいバージョンが利用可能であることをユーザーに伝え、アップグレードコマンドpip3 install yescan --upgradeを提示。ユーザーがアップグレードするかどうかを決定
- キーチェック:
yescan config get SCAN_WEBSERVICE_KEYを実行し、設定されていない場合はユーザーに設定を促す- 設定コマンド:
yescan config set SCAN_WEBSERVICE_KEY <your_api_key>
Key の取得方法: https://scan.quark.cn/business → 開発者バックエンド → API Key
- 設定コマンド:
Checkpoint: バージョン < 1.0.5 → アップグレードが必須、完了後に続行。バージョン ≥ 1.0.5 で最新でない場合 → ユーザーに通知後、続行可能。キーが未設定の場合は設定を促してから続行。
- インストール & アップグレード:
-
能力の発見:
yescan --list-scenes # 全シナリオとその意図説明を取得 yescan --list-scenes <scene> # 指定シナリオの --set パラメータを取得出力からユーザーの意図を具体的なシナリオにマッチング
-
複数ステップの処理の場合、完全なステップ計画をユーザーに表示
ゲート:
- 「環境の準備確認」の各ステップは必須の前提条件であり、いずれもスキップ不可。全てをパスしない場合は Execute への進入禁止:
yescan --versionを実行してインストール状況を確認していない → 続行禁止- バージョン < 1.0.5 でアップグレードを完了していない → 続行禁止
pip3 index versions yescanを実行して最新バージョン状況を確認していない → 続行禁止yescan config get SCAN_WEBSERVICE_KEYを実行してキーの設定を確認していない → 続行禁止
- ユーザーが明示的に必要とするシナリオのみを実行し、不要なステップを追加しない。ただし、現在のタスクの効果を高めるための補助操作はこの限りではない
- 文書変換(Word/Excel/PDF)は画像を直接処理し、OCR 結果に依存しない。両方の入力は画像であり、独立した操作
- シナリオ名と
--setパラメータは、今回のセッションの CLI 出力から取得する必要がある --list-scenesを実行していない場合は Execute に進入不可- シナリオに
--setパラメータがあり、ユーザーが明示的に指定していない場合は、オプションパラメータをユーザーに表示し、確認後に実行する必要がある
Execute — シナリオを実行
yescan --scene <SCENE> --path <FILE> --platform "${AGENT_NAME}" [--output <DIR>] [--set key=value]
yescan --scene <SCENE> --url <URL> --platform "${AGENT_NAME}" [--output <DIR>] [--set key=value]
--pathにはローカルファイルパスを、--urlには http/https リンクを指定します。
${AGENT_NAME}は現在の Agent プラットフォーム名(例: openclaw、hermes、qoderWork、wukong、coze、claudecode など)に置き換えます。判別できない場合はcommunityと入力し、推測や創作は禁止です。
- 単一ステップ: 直接実行
- 複数ステップの処理は、Execute → Verify のループで段階的に行う: step N+1 のコマンドは、step N の Verify が成功した後にのみ構築。
--pathは step N のレスポンス内のdata.pathから取得
ゲート:
- 複数ステップの処理の場合は、ステップ計画をユーザーに説明
- 各ステップのコマンドは事前に構築しない
--setパラメータはシナリオ間で引き継がない
Verify — 検証して納品
各ステップの実行後、レスポンス内の code フィールドをチェック:
- 成功(
codeが"00000"または0)→ 納品へ - 失敗 → 次のステップに進まず、エラー情報に基づいて処理(詳細はゲートを参照)
納品基準 — 以下の条件をすべて満たして初めて完了:
- OCR 認識: 認識内容が読みやすいテキストとしてユーザーに提示されている
- 画像翻訳 / 画像強調 / AIGC: 出力ファイルのパスがユーザーに通知されている
- 文書変換: 出力ドキュメントのパスと形式がユーザーに通知されている
ゲート:
- code が成功以外 → 次のステップに進まず、成功を報告しない
- エラー情報に基づいて自己修復(例: 無効なシナリオ名 → 再度
--list-scenesを実行)するか、エラー原因をユーザーに通知 - ユーザーが結果を確認していない → 未完了
制約
- 入力方法:
--pathまたは--urlのいずれか。base64 は非対応(必要な場合は一時ファイルに書き込んでから) - URL 引用符:
--urlパラメータはシングルクォートで囲む必要があります。シェルによる!$などの特殊文字の解釈を防ぐため - ファイルサイズ: ≤ 5MB
- 画像ソース: ユーザーの当該リクエストで明示的に指定されたファイルまたは URL のみ
- 偽造禁止: yescan CLI のリクエストパラメータや応答出力をでっち上げたりシミュレートしてはなりません。すべてのシナリオ名、パラメータ値、実行結果は実際に実行された CLI コマンドから取得する必要があります
参考ドキュメント
- references/privacy.md — プライバシー、データフロー、キーセキュリティ
- references/troubleshooting.md — エラーコードとトラブルシューティング
- references/implementation.md — 実装の詳細: CLI の動作とレスポンスフィールド
- SECURITY.md — セキュリティポリシーとデータフローの宣言