執行流程
每次執行嚴格按 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 參數從輸出中匹配用戶意圖到具體場景
-
多步處理時,向用戶展示完整步驟計劃
Gate:
- 「確認環境就緒」每一步均為硬性前置,不得跳過任何一步,未全部通過 → 禁止進入 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
Gate:
- 多步處理時向用戶說明步驟計劃
- 每步命令不得預先構造
--set參數不跨場景沿用
Verify — 驗證並交付
每步執行後檢查響應中的 code 字段:
- 成功(
code為"00000"或0)→ 進入交付 - 失敗 → 不繼續下一步,根據錯誤信息處理(詳見 Gate)
交付標準 — 以下條件滿足才算完成:
- OCR 辨識:辨識內容已以可讀文字呈現給用戶
- 圖片翻譯 / 圖像增強 / AIGC:輸出檔案路徑已告知用戶
- 文件轉換:輸出文件路徑和格式已告知用戶
Gate:
- code 非成功 → 不得繼續下一步,不得報告成功
- 根據錯誤信息自行修復(如場景名無效 → 重新
--list-scenes)或將錯誤原因告知用戶 - 用戶未看到結果 → 未完成
約束
- 輸入方式:
--path或--url,二選一。不支援 base64(如需則先寫入暫存檔案) - URL 引號:
--url參數須用單引號包裹,避免 shell 對!$等特殊字元的解析 - 檔案大小:≤ 5MB
- 圖片來源:僅限用戶當次請求中明確指定的檔案或 URL
- 禁止偽造:不得編造或模擬 yescan CLI 的請求參數或響應輸出;所有場景名、參數值和執行結果必須來自實際運行的 CLI 命令
參考文件
- references/privacy.md — 隱私、數據流向與金鑰安全
- references/troubleshooting.md — 錯誤碼與排錯
- references/implementation.md — 實現細節:CLI 行為與響應字段
- SECURITY.md — 安全策略與數據流聲明