workctl-operatorlisted

# Workctl Operator 使用 `workctl` 管理 Work Agent 平台能力。默认相信 CLI 已做 Agent-Friendly 收口：成功输出尽量极简，失败输出只给可执行修复动作，大结果自动落 artifact。不要在 skill 里重复写 CLI 内部策略。 ## 快速流程 1. 确认 CLI 和测试登录态： ```bash workctl version --format json workctl auth login --provider alibaba --format json workctl auth status --format json ``` 2. 发现命令，先搜再看 schema： ```bash workctl schema --search '<关键词>' --limit 10 --format json workctl schema <product.group.action> --format json ``` 3. 执行业务命令： ```bash workctl <product> <group> <action> --format json <flags...> ``` 4. 多个互不依赖的只读查询不要逐条串行跑，生成 batch spec 后用： ```bash workctl batch call --file batch.json --format json ``` 5. 写操作、发送消息、投广告、发布/编辑商品前，先展示对象、影响范围和关键参数，得到明确确认后再执行。 ## 并行和异步策略 - 先画依赖：只有 token、receipt、categoryKey、taskId 这类上游 ID 必须串行；拿到 ID 后，后续只读查询尽量 `batch call` 并行。 - 报表、诊断、商品/流量/转化/IM/物流等只读 fan-out，优先生成一个临时 batch JSON；结果统一落 artifact，再用 `artifact get --jq` 精确读取。 - 生成、发品、图片、视频、建站等长任务，优先 `--wait --poll-interval ... --wait-timeout ...`；需要后台提交时用 `--async`，再 `task status/wait` 恢复。 - CLI 当前 `batch call` 不做步骤间变量引用；有依赖的前置步骤先在 batch 外执行，或用 `workflow run` 顺序执行固定参数步骤。 - 避免 Agent 自己开多个 shell 后台进程、手写 sleep/while 或把多个大 JSON 读进上下文。 ## Agent 读取规则 - 成功：优先读顶层业务字段和 `success`；对象型业务结果通常已平铺，数组/字符串才放在 `data`。 - 失败：优先读 `error.reason` 和 `error.next_action`；不要盲目重试同一入参。 - 动态命令返回形态可能是 `model/items/result/records/data`，不要假设一定有 `.data`。 - `--jq/--fields` 作用于完整 structured envelope；在线过滤常从 `.data.*` 读，读默认 stdout 时先看顶层字段。 - `--output` 保存完整结果，可能保留 `meta`；