Background

This issue tracks a narrator-ai-cli / agent workflow problem observed during a Fast Path run: the client-side agent repeatedly created generate_fast_writing_clip_data tasks for the same upstream fast-writing output while trying parameter variants.

This is not scoped as a refund or billing-return issue. The goal is to reduce repeated create requests from agent users by improving CLI affordances, state persistence, and recovery guidance.

User-Side Investigation Raw Info

The following is the user-side investigation conclusion preserved as original input for this issue:

根因：用户/Agent 在本地反复编写 Python 脚本并通过 subprocess 多次重复提交 create_generate_fast_writing_clip_data 请求，每次创建任务后未在客户端做幂等检查（如检查 task_id 是否已存在），而是持续尝试不同参数变种。前 2 次因参数错误（缺少 negative_oss_key 等）导致失败（status=3，但仍扣点 70），随后 3 次成功（status=2）。5 次请求均使用同一个上行任务和同一份文案文件。

明确两点：

1. 不存在 API 后端自行重复创建——每一个 task_id/order_num 唯一且独立，说明每次 POST 都正常返回了一个新任务。
2. 不存在幂等缺失——API 没有 idempotency key，客户端每次 POST 都算新任务。问题出在客户端没有做到"创建前检查、创建后持久化、不重复创建"。

Evidence

Same upstream fast-writing task and script file:

• upstream fast_generate_writing task_id: 1012c1b43c7e4fa59c611d1417aa1090
• script file_id: 764789bb31d2452d91a377878412117b

Repeated fast-clip-data tasks:

Common core parameters:

• task_id: 1012c1b43c7e4fa59c611d1417aa1090
• file_id: 764789bb31d2452d91a377878412117b
• bgm: d9b111ab-98f2-49e7-8c95-4f8986cab8a5
• dubbing: mercury_ln-xiaobei_24k
• dubbing_type: 普通话
• episodes_data[0].video_oss_key: a94677c94fd2442c9061b7652a67b5d9
• episodes_data[0].num: 1

Observed differences were limited to optional or variant fields such as negative_oss_key and srt_oss_key.

Problem

Agent users can easily create duplicate paid or expensive tasks when a create call succeeds but subsequent polling, parameter validation, or local script iteration is unclear.

The repeated task creation pattern appears to be:

1. Agent writes a local Python script to invoke narrator-ai-cli or directly POST to the API.
2. First create attempt returns a new task, but the run fails or output is unclear.
3. Agent adjusts parameters and creates another task instead of querying/reusing the existing task.
4. Successful tasks are not treated as terminal state for the same input hash, so later attempts can still create more duplicates.

Requested CLI / Skill Improvements

Please evaluate whether narrator-ai-cli can add client-side guardrails for agent workflows:

• Persist each create request into a local run state file, for example narrator-run-state.json, containing request hash, task type, task_id, task_order_num, input file IDs, and output file IDs.
• Add or document a resume / create-or-query style workflow: for the same task type and same business parameters, query and reuse the existing task before creating a new one.
• For fast-clip-data, compute a deterministic local request key from fields such as task_id + file_id + episodes_data + bgm + dubbing + dubbing_type.
• If the same key was already created recently, print a warning and require explicit confirmation before creating another task.
• If task creation succeeded but polling failed, guide the agent to run task query <task_id> instead of re-running task create.
• Update the Codex skill / CLI docs to require: create success -> persist task_id -> poll/query existing task -> only create again after explicit user confirmation and after showing parameter differences.

Acceptance Criteria

• Agent users have a documented way to resume a partially completed Fast Path run without issuing duplicate create requests.
• Re-running an identical fast-clip-data request either reuses the known task or clearly warns before creating another task.
• Documentation explains the recovery path for "create succeeded, poll failed/unclear" and explicitly says not to create again before querying the existing task.
• Any new state file or warning mechanism avoids storing secrets such as app keys, webhook tokens, or authorization headers.

Owner

Suggested owner: @pluckhuang