Execution Flow
Each execution must strictly follow the Plan → Execute → Verify sequence. Do not skip or reorder.
Plan — Understand Intent, Discover Capabilities
-
Verify Environment Readiness (mandatory before every execution, do not skip):
- Installation & Upgrade:
- Run
yescan --version— if not installed, executepip3 install yescan; if version < 1.0.5, executepip3 install yescan --upgrade, and only proceed after the upgrade is complete. - Run
pip3 index versions yescan— if INSTALLED < LATEST, inform the user of the new version and provide the upgrade command:pip3 install yescan --upgrade. The user decides whether to upgrade.
- Run
- Key Check: Run
yescan config get SCAN_WEBSERVICE_KEY. If not configured, guide the user to configure it.- Setting command:
yescan config set SCAN_WEBSERVICE_KEY <your_api_key>
How to obtain the key: https://scan.quark.cn/business → Developer Console → API Key
- Setting command:
Checkpoint: Version < 1.0.5 → must upgrade before proceeding. Version ≥ 1.0.5 but not the latest → may proceed after prompting the user. If the key is not configured, guide configuration before proceeding.
- Installation & Upgrade:
-
Discover Capabilities:
yescan --list-scenes # Get all scenes and their intent descriptions yescan --list-scenes <scene> # Get the --set parameters for that sceneMatch the user's intent to a specific scene from the output.
-
For multi-step processing, show the user the complete step plan.
Gate:
- Each step of "Verify Environment Readiness" is a hard prerequisite. Do not skip any step. If all are not passed, do not enter Execute:
- Did not run
yescan --versionto confirm installation status → must not proceed. - Version < 1.0.5 and upgrade not completed → must not proceed.
- Did not run
pip3 index versions yescanto confirm latest version status → must not proceed. - Did not run
yescan config get SCAN_WEBSERVICE_KEYto confirm the key is configured → must not proceed.
- Did not run
- Only execute scenes the user explicitly requests. Do not proactively add extra steps. Auxiliary operations to improve the current task's outcome are exempt from this rule.
- Document conversion (Word/Excel/PDF) directly processes images and does not rely on OCR results. Both inputs are images; they are independent operations.
- Scene names and
--setparameters must come from the current session's CLI output. - If
--list-sceneshas not been executed, do not enter Execute. - If a scene has
--setparameters and the user has not specified them, present the optional parameters to the user for confirmation before execution.
Execute — Execute the Scene
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]
Use
--pathfor local file paths,--urlfor http/https links.
Replace
${AGENT_NAME}with the current Agent platform name (e.g., openclaw, hermes, qoderWork, wukong, coze, claudecode, etc.). If unsure, usecommunity. Do not guess or invent.
- Single step: Execute directly.
- Multi-step processing: Use a step-by-step Execute → Verify loop. The command for step N+1 is constructed only after step N's Verify passes. The
--pathis taken fromdata.pathin the response of step N.
Gate:
- For multi-step processing, explain the step plan to the user.
- Do not construct commands for future steps in advance.
--setparameters are not carried over across scenes.
Verify — Verify and Deliver
After each step, check the code field in the response:
- Success (
codeis"00000"or0) → Proceed to delivery. - Failure → Do not proceed to the next step. Handle according to the error message (see Gate).
Delivery criteria — a step is considered complete only when the following conditions are met:
- OCR Recognition: The recognized content has been presented to the user as readable text.
- Image Translation / Image Enhancement / AIGC: The output file path has been communicated to the user.
- Document Conversion: The output document path and format have been communicated to the user.
Gate:
- If the code is not successful → do not proceed to the next step, do not report success.
- Automatically fix the issue based on the error message (e.g., if the scene name is invalid, re-run
--list-scenes) or inform the user of the error reason. - If the user has not seen the result → the task is not complete.
Constraints
- Input Method: Use
--pathor--url, choose one. Base64 is not supported. If base64 is provided, first write it to a temporary file. - URL Quoting: The
--urlparameter must be enclosed in single quotes to prevent the shell from interpreting special characters like!or$. - File Size: ≤ 5MB.
- Image Source: Only files or URLs explicitly specified in the user's current request.
- No Fabrication: Do not fabricate or simulate
yescanCLI request parameters or response output. All scene names, parameter values, and execution results must come from actual CLI commands that were run.
Reference Documentation
- references/privacy.md — Privacy, data flow, and key security
- references/troubleshooting.md — Error codes and troubleshooting
- references/implementation.md — Implementation details: CLI behavior and response fields
- SECURITY.md — Security policy and data flow statement