Automation Spec

Automation Spec 描述一个不可变自动化版本怎样接收输入、使用登录身份、执行步骤并返回结果。它不保存 Cookie、密码或浏览器二进制。

顶层字段

字段	说明
id	当前版本 ID
workspace_id	内部数据隔离键，用户无需填写或切换
automation_id	稳定的自动化入口 ID
plugin_id	插件身份
version	递增版本号
status	draft、analyzing、self_testing、ready、published、deprecated 或 blocked
input_schema	JSON Schema 2020-12 输入约束
ui_schema	各输入的展示方式
output_schema	最终输出约束
account_schema	所需登录身份能力
auth_rule_ids	已验证登录规则引用
api_plan	强类型 API 步骤
dom_plan	CloakBrowser 页面步骤
desktop_plan	桌面软件步骤
artifact_rules	文件和大数据结果规则
permissions	域名、方法、目录和能力
tests	发布前确定性自检
provenance	录制、助手、编译器和父版本来源
content_hash	64 位小写 SHA-256

ValueSource

步骤参数不直接拼字符串，而是声明来源：

• fixed：固定值。
• input：运行输入字段。
• step_output：前序步骤命名输出。
• account：登录身份字段。
• secret：本地 SecretRef。
• expression：受限表达式。
• time：结构化相对时间。

API Step

API Step 必须声明 Method、URL、Header/Query/Body 来源、认证、CSRF、响应映射、成功条件、副作用和回退策略。

安全约束：

• idempotent 写操作必须提供稳定 idempotency_key。
• fallback_policy=verify 必须提供 GET 或 HEAD 的回退前核验。
• non_idempotent 结果不确定时不能自动切换 DOM 重复提交。

DOM Step

类型包括 navigate、click、input、select、check、upload、wait、extract、download 和 screenshot。

每个目标保存多个 Locator 候选：测试 ID、Role、Label、稳定属性、文本、CSS、XPath，最后才是坐标。网站 DOM Plan 只在 CloakBrowser 中执行。

Desktop Step

桌面动作包括启动、点击、输入、选择、键盘、滚动、等待、提取、截图和文件操作。正式版本可声明的定位策略只有 macOS AX、Windows UIA、Electron CDP、WebView 调试和坐标。

OCR 不是 Desktop Plan 的回放策略。当前只有 macOS 录制选点器会把 OCR 作为识别辅助；发布前必须把结果整理成上述可执行策略，无法获得稳定元素时通常使用坐标。Windows 当前不提供正式 OCR 录制或回放能力。

发布规则

只有 ready 草稿可以发布。发布版本不可修改；调整和修复必须创建新版本并重新计算内容哈希。