@iqiyi-intl-nadoupro/nadoupro-cli 1.0.0-test.2

package/skills/nadou/commands/schedule.md

@@ -0,0 +1,112 @@
+# 定时任务（`schedule`）
+
+定时功能默认关闭，必须明确选择执行模式、未来执行时间和 IANA 时区。本地模式与服务端模式之间不得自动切换。
+
+画布定时的执行时间必须按用户时区的 30 分钟卡点填写，例如 `21:00` 或 `21:30`，且秒数必须为 `00`；CLI
+会在任何估价或提交前拒绝其他时间。普通服务端定时沿用服务端既有时间规则；该限制不适用于本地
+`schedule create/update` 计划。
+
+向用户询问画布节点定时时，提示示例只能使用整点或半点，例如：
+
+> 请输入未来的日期和时间，例如 `2026-08-06 21:00`、`2026-08-06 21:30` 或 `2026-08-06 22:00`；画布定时只支持每小时整点或半点。
+
+不得用任意其他分钟作为示例；用户若提供非 `:00` / `:30` 的时间，必须明确提示不支持并请用户重新选择，不能静默取整或替换。
+该交互约束只针对画布节点服务端定时，普通图片/视频服务端定时和本地计划仍按各自规则处理。
+
+## 服务端模式
+
+普通图片/视频服务端定时仍是普通任务：
+
+```bash
+nadou image "prompt" \
+  --schedule-mode server \
+  --scheduled-at "2026-08-03T21:30:00" \
+  --timezone "Asia/Shanghai" \
+  --dry-run --json
+```
+
+保存 `data.request` 后，使用完全相同的文件依次执行：
+
+```bash
+nadou points summary --json
+nadou task estimate --body-file request.json --json
+nadou task submit --body-file request.json --json
+```
+
+提交最多一次；结果未知时不得重提。保存任务 ID 后使用 `task status/wait/events` 观察。后端按分钟扫描到期任务，不能承诺毫秒级准点。原子文本不开放服务端定时。
+
+单个既有画布节点的服务端定时不使用请求文件，而从实时 Graph 派生唯一请求：
+
+```bash
+nadou canvas node generate --canvas-id <canvas-id> --node-id <node-id> \
+  --schedule-mode server --scheduled-at "2026-08-03T21:30:00" \
+  --timezone "Asia/Shanghai" --dry-run --json
+
+nadou canvas node generate --canvas-id <canvas-id> --node-id <node-id> \
+  --schedule-mode server --scheduled-at "2026-08-03T21:30:00" \
+  --timezone "Asia/Shanghai" --confirm-preview-sha256 <digest> \
+  --max-points <authorized-points> --json
+```
+
+预览必须先核对原始/规范化时间、账号配置、账号哈希、当前计费空间、画布目标空间、目标空间类型、目标目录、
+节点、模型、数量、预计积分、余额、预计余额和不锁价说明。画布目标空间和目录来自按 `workflowId` 精确查询
+`/apis/nadouai/canvas/workflow/detail` 的 `data.groupId/groupType/directoryId`；不读取其中 graph，Graph 仍以
+`graph/query` 为准。正式调用重新派生事实，摘要不匹配即零写失败；通过后只发送一次普通任务提交。
+该命令不接受请求体文件，不自动切换到本地模式。
+
+## 本地模式
+
+先用普通图片/视频 `--dry-run` 或独立 `TEXT2TEXT` 预览生成不带 `scheduledTime` 的请求：
+
+```bash
+nadou schedule create \
+  --body-file request.json \
+  --scheduled-at "2026-08-03T21:30:00" \
+  --timezone "Asia/Shanghai" \
+  --max-points 20 --json
+```
+
+创建时会验证权威账号、当前计费空间、余额和估价，但不会提交任务。身份读取复用现有
+`/apis/ping`，该接口可能更新服务端登录时间/IP 或初始化个人空间；它不是完全无副作用的身份查询。
+结果会显示创建时的结构化 `balance`、`projected_balance`、`estimated_points` 和
+`estimate_locked=false`。当余额为 `value=null/display=∞` 时，仅跳过本地数值不足比较；创建和到期
+仍重新估价并校验 `--max-points`，服务端最终校验不变。`--max-points`
+是显式费用授权，不被 `--yes` 替代。
+
+文本计划只允许无项目/画布绑定和无外部引用的独立 `TEXT2TEXT`。`IMG2TEXT`、凭证、签名 URL、
+引用 URL 或无法权威估价的请求在创建前拒绝；明确 `points=0` 是合法的精确零积分估价，缺失、负数或非数值积分按契约错误失败。到期提交冻结的普通请求，请求体
+不含 `scheduledTime`。
+
+管理命令：
+
+```bash
+nadou schedule list --json
+nadou schedule status <schedule-id> --json
+nadou schedule update <schedule-id> --scheduled-at <time> --timezone <IANA> --json
+nadou schedule cancel <schedule-id> --yes --json
+```
+
+只有未被执行程序取得的 `PENDING` 计划可改期或取消。`BLOCKED`、`OUTCOME_UNKNOWN` 等状态不可原地恢复，修复原因后必须显式创建新计划。
+
+本地计划需要显式前台执行程序，或由外部操作系统调度器周期性唤醒：
+
+```bash
+nadou schedule worker --jsonl
+nadou schedule worker --once --json
+```
+
+CLI 首版不会自行安装 Windows Task Scheduler、launchd 或 systemd。进入 `SUBMITTING` 后，无论崩溃发生在 POST 前后，重启都只会转为 `OUTCOME_UNKNOWN`，不会再次提交。
+
+本地列表/状态查询只输出计划摘要和证据，不输出完整请求、提示词、引用 URL、凭证或签名 URL。
+
+以上 `schedule` 管理命令只操作本机持久化计划，不代表服务端任务已取消或改期。已知服务端任务 ID 使用：
+
+```bash
+nadou task reschedule <task-id> --scheduled-at <time> --timezone <IANA> --json
+nadou task cancel-scheduled <task-id> --yes --json
+```
+
+服务端命令只处理 `SCHEDULED`，写一次并回读确认；上下文任务或取消操作在任务状态没有权威项目 ID
+时还必须显式提供 `--workflow-id`、`--thread-id` 或 `--project-id`，不得从当前空间猜测。独立任务的
+`reschedule` 可以省略上下文，由服务端按当前用户和任务 ID 校验；`cancel-scheduled` 仍要求上下文。
+CLI 仍不调用 `/task/page` 或任何 `/task/plan/*` 接口。

package/skills/nadou/commands/space.md

@@ -0,0 +1,253 @@
+# 团队空间
+
+登录后可查看当前所处的团队空间、列出可用空间并切换。生图、生视频、积分查询都以当前空间为上下文。
+
+## 查看当前空间
+
+```sh
+nadou space current --profile <profile> --no-interactive --json
+```
+
+`data` 字段：`current`（当前空间 `id`/`name`/`type`）、`personal`（个人空间）、`has_group`。当前空间以服务端为权威来源。
+
+原子图片、视频或音频费用预检执行一次 `space current`，同时取得当前计费空间身份和
+`data.personal.id`。当前空间只表示计费范围；未指定交付目录时，必须在估价和提交确认前读取个人空间目录候选，
+由用户选择后再绑定交付目标。计费空间与交付目录必须分别表达，不能先生成再补问目录，也不能默认个人空间根目录。
+底层 `/apis/ping` 可能附带用户初始化或更新副作用，因此不用于高频轮询。
+该命令通过 `/apis/ping` 读取权威空间；接口可能更新登录信息或初始化个人空间，
+所以副作用为 `remote_read + remote_write`，不应高频轮询。
+
+## 列出可用空间
+
+```sh
+nadou space list --profile <profile> --no-interactive --json
+nadou space list --profile <profile> --type group --no-interactive --json   # 仅团队；--type personal 仅个人
+```
+
+`data`：`spaces[]`（按创建时间倒序，当前空间标注 `is_current`）、`current_id`。
+为了标记当前空间，`space list` 也会额外调用 `/apis/ping`，具有相同的
+`remote_read + remote_write` 附带副作用。
+
+## 切换空间
+
+```sh
+nadou space use <space-id> --profile <profile> --json        # 别名：nadou space switch <space-id>
+```
+
+- 成功返回 `kind=space_switch`、`switched_to`、`current`（切换后重新读取的权威当前空间）。
+- 切换是**服务端有状态**操作，会同时改变该账号在网页端的当前空间（预期行为），不提供"仅本次会话"的临时切换。
+- CLI 还会更新本地账号配置，并通过 `/apis/ping` 回读权威结果；副作用为
+  `remote_read + remote_write + local_write`。
+- 切换只发送一次请求且不自动重试；超时、断网或结果不明确时，先运行 `space current` 核对服务端实际状态。
+- 切换到无权限/不存在的空间会返回稳定错误，且不改动本地绑定。
+
+## 自动化建议
+
+- 需要在特定空间生成时，先 `space list` 确认计费空间 ID，再 `space use <id>`；独立图片、视频或音频还必须在提交前
+  解析并确认交付目录、完成余额与估价确认，不能因空间已切换就直接提交任务。
+- `space current` / `space list` 是动态事实来源，不要猜测空间 ID 或名称。
+
+## 遍历空间目录内容
+
+`space directory list --group-id <group-id>` 用于一次发现空间目录树；
+`space directory contents` 用于读取根目录或某个目录中的真实直接子项：
+
+```sh
+nadou space directory contents --group-id <group-id> --page 0 --size 20 --profile <profile> --no-interactive --json
+nadou space directory contents --directory-id <directory-id> --type image --profile <profile> --no-interactive --json
+nadou space directory contents --group-id <group-id> --recursive --type image --profile <profile> --no-interactive --jsonl
+```
+
+- `--group-id` 与 `--directory-id` 必须且只能提供一个；直接模式是零基分页，只读取一页。
+- 只有显式 `--recursive` 才执行广度优先遍历。递归时 CLI 向后端读取 `ALL`，再对输出应用
+  `--type`，因此图片、视频或音频过滤不会截断子目录发现。
+- `--jsonl` 只用于递归模式。每个 `space_directory_content_item` 都带单调递增的
+  `sequence`；成功时最后且仅有一个 `space_directory_traversal_summary`。
+- 终止错误不会伪造成功汇总；应检查错误 `details.complete=false`、已读取页数、已返回条目数和
+  失败目录/页，再由用户决定是否重新执行读取。
+- 后端 `B00001` 同时覆盖参数错误和空间/目录/素材不存在，CLI 稳定返回
+  `SPACE_DIRECTORY_SCOPE_REJECTED`，不会根据本地化消息猜测 `NOT_FOUND`。
+- 目录条目的 `items` 只是服务端预览，不能替代对子目录的独立分页。画布以 `workflow_id`
+  标识；旧项目保持 `kind=legacy_project`；素材 URL 只有通过公网安全校验时才输出。
+- 此命令只读，不切换当前空间，也不把发现到的素材自动写入画布节点。
+
+### 画布图片导入时读取预览元数据
+
+默认目录输出继续隐藏后端原始 `metadata`。当 Agent 需要把个人空间中的既有图片承接为画布上传节点时，显式增加
+`--include-metadata`，CLI 才返回受限的 `metadata` 投影（资产 ID/名称、宽高、时长和通过公网校验的
+`thumbnail_url`、`medium_thumbnail_url`、`preview_url`、`first_frame_url`）：
+
+```sh
+nadou space directory contents --directory-id <directory-id> --type image \
+  --include-metadata --profile <profile> --no-interactive --json
+```
+
+将同一条目的 `id`、`material_url` 和安全 metadata 映射到已有的上传节点命令；不要再次上传、不要自行拼接缩略图地址：
+
+```sh
+nadou canvas node create-image-upload --canvas-id <canvas-id> \
+  --material-id <id> --url <material_url> \
+  --metadata '{"assetId":<id>,"assetName":"<asset_name>","width":<width>,"height":<height>,"thumbnailUrl":"<thumbnail_url>","mediumThumbnailUrl":"<medium_thumbnail_url>"}' \
+  --profile <profile> --json
+```
+
+该流程仍只创建 `imageNodeOrigin=upload`、`isCustomNode=true` 的初始节点；metadata 只是初始预览信息，不能借此写入任务状态、回调产物或生成字段。没有 medium 缩略图时不伪造 URL，节点仍使用服务端提供的其他可信地址。
+
+## 创建空间目录
+
+CLI 已支持显式创建空间目录。目录创建必须选择空间；父目录可选，省略时只接受该空间唯一的根目录：
+
+```sh
+nadou space directory create \
+  --group-id <group-id> --name <directory-name> \
+  [--parent-directory-id <parent-directory-id>] \
+  --profile <profile> --no-interactive --json
+```
+
+- `--group-id` 和 `--name` 必填；名称会去除首尾空白，不得包含控制字符，最长 100 个
+  UTF-16 代码单元。
+- CLI 先通过空间和目录列表核对目标。团队空间还会读取父目录角色：只有
+  `manager/member` 继续，`viewer` 明确拒绝，空角色和未来角色失败关闭；个人空间不依赖可能
+  为空的团队角色字段，但实际创建接口仍执行最终鉴权。
+- 请求体只发送 `groupId/name/directoryId`，不会接受或发送后端特殊字段 `assertGroupId`。
+- 一条命令最多发送一次创建请求。成功响应的新目录 ID 必须在目录列表中按相同 ID、空间、名称、
+  父目录和根目录回读一致后才报告 `state=created`。
+- 同一父目录允许同名目录；名称不能用于未知请求的权威对账。网络错误、408/5xx、空/畸形成功响应
+  或写后回读失败返回 `REQUEST_OUTCOME_UNKNOWN`。人工按 ID 核对前不得自动重试。
+- 当前命令只创建目录，不创建空间，不改名、删除或移动目录，也不切换当前空间。
+
+## 重命名空间素材
+
+只在用户明确要求修改素材展示名时执行，并显式提供素材当前所在的空间、直接父目录和素材 ID：
+
+```sh
+nadou space file rename \
+  --group-id <group-id> --directory-id <directory-id> \
+  --material-id <material-id> --name <new-display-name> \
+  --profile <profile> --no-interactive --json
+```
+
+- 先用 `space list`、`space directory list` 和直接模式的 `space directory contents` 获取真实 ID。
+  不得按名称、URL、列表序号或相似内容猜测目标，也不得使用递归结果代替直接父目录关系。
+- 名称会去除首尾空白，不得为空或包含控制字符，最长 100 个 UTF-16 代码单元。
+- 团队目录只有角色明确为 `manager/member` 时才继续；`viewer` 写前拒绝，空角色和未来角色失败关闭。
+  个人空间不依赖团队角色字段，实际写接口仍执行最终鉴权。
+- 同名请求返回 `state=unchanged` 且不发送写请求。其他请求最多写一次；只有写后在同一目录按同一
+  `material-id` 回读到新名称，才返回 `state=renamed`。
+- 该操作只改变服务端素材展示名，不移动素材、不改变存储对象或 URL，也不会修改画布节点。
+- 网络错误、408/5xx、畸形响应、写后素材消失或名称不一致均返回
+  `REQUEST_OUTCOME_UNKNOWN`。保留请求/空间/目录/素材/名称信息，人工按 ID 核对前
+  不得自动重试。
+
+## 将任务产物交付到显式目录
+
+先用 `task outputs --task-id` 查看受信候选，再选择唯一输出：
+
+```sh
+nadou space artifact deliver \
+  --task-id <task-id> --job-id <job-id> --output-index <index> \
+  --group-id <group-id> --directory-id <directory-id> \
+  --mode copy [--fallback-to-personal] \
+  --profile <profile> --no-interactive --json
+```
+
+### 目录层级展示约定
+
+`space directory list` 的机器结果保留 `id`、`group_id`、`name`、`parent_id`、`root_id`、`is_root` 等扁平字段，并可增加：
+
+- `path`：CLI 根据同一空间内的 `parent_id`/`root_id` 解析出的展示路径，例如“根目录 / 角色 / 喵喵”；
+- `level`：根目录为 1 的层级；
+- `path_source=cli_parent_chain`：明确该路径是本地父链解析事实。
+
+同名目录必须同时展示完整层级路径和目录 ID。列表出现重复 ID、多个根、断链、循环或跨空间父节点时失败关闭，不按名称、返回顺序或 URL 猜测。列表派生路径不是服务端 `directory_path`、网页 URL 或写权限证明；空间内容和交付结果如果返回服务端 `directory_path`，应优先展示该权威值。
+
+## `atomic_media_permission_fallback_prompt`
+
+该提示契约只适用于独立 `image`、`video`、`audio` 任务的空间交付。团队目录被服务端以
+`PERMISSION_DENIED` 或 `DELIVERY_PERMISSION_DENIED` 拒绝，且错误详情为
+`fallback_eligible=true` 时，必须先展示原团队空间/目录和个人空间候选目录，再询问用户是否回退；
+生成任务已经完成，不得重新生成。
+
+- `fallback_confirmation_required`：用户确认并选择个人目录前，个人空间写请求数必须为 0。
+- `fallback_confirmation_declined`：拒绝、取消或未回答时保留 `generation_status=COMPLETED`，单独报告交付未完成和恢复命令，不切换空间、不重试写入。
+- `non_interactive_fallback_blocked`：`--no-interactive` 且没有预先授权的个人目录时，只返回原目标、`fallback_eligible=true`、`task_id/job_id/output-index` 和下一步显式命令。
+- `original_task_reuse_only`：确认后只复用同一次任务的可信 `task_id`、`job_id`、`output-index` 执行一次显式个人交付。用户只确认回退并选择个人目录，任务标识由 Agent 自动传入，同一流程中不得要求用户再次填写；不按 URL、名称、顺序或提示词猜测产物。
+
+超时、网络中断、目录事实缺失、通用错误或写入结果未知时不触发回退提示；应先人工核对。只有个人目录写入成功并完成目录回读后，才能报告实际个人空间路径和素材标识。
+
+- `--mode copy|transfer` 默认 `copy`；一次命令只执行所选模式一次，失败或未知时绝不自动切换。
+- `job-id`、`asset-id`、`output-index` 是同时过滤条件，必须唯一；命令没有 `--url`。
+- CLI 先确认目录属于显式 group，再读取服务端空间类型和目录角色。`manager/member` 继续由实际写接口
+  做最终鉴权；团队目录 `viewer` 明确只读；空角色和未来角色返回
+  `DELIVERY_PERMISSION_UNVERIFIED`，不得根据名称、身份或本地化消息猜测。
+- `--fallback-to-personal` 是显式保底策略。启用后，CLI 从空间列表选择唯一个人空间、从目录列表选择
+  唯一 `is_root=true` 根目录；团队目标明确为 `viewer`，或目录内容预检明确返回
+  `PERMISSION_DENIED` 时不向团队目录写入，当前命令唯一写请求直接发往个人根目录。个人空间或
+  根目录缺失/不唯一时写前失败关闭；通用业务错误、网络错误和未知结果不适用该分支。
+- 写接口返回的新素材 ID 必须在实际写入目录回读命中后才输出 `SUCCEEDED`。成功结果分别包含
+  `requested_destination`、带真实 `directory_path` 的 `actual_destination`；如果同一任务产物提供非下载在线地址，
+  还返回 `online_url`，应直接作为查看链接使用，不要改用签名 `download_url` 或自行拼接地址；只有实际目标变化时返回
+  `fallback_reason=TARGET_DIRECTORY_PERMISSION_DENIED`。
+- 写前可写但写时明确返回 `PERMISSION_DENIED` 时，当前命令不发送第二次写；启用保底策略的错误 `details`
+  返回 `fallback_eligible=true` 和个人根目录 ID，供 Agent 使用原任务/作业/产物执行新的显式交付。
+- `REQUEST_OUTCOME_UNKNOWN` 可能表示写已生效；保留请求/任务/产物/空间/目录信息，以及
+  请求目标、实际尝试目标和已知时的 `server_correlation_id`，同时返回
+  `fallback_eligible=false`；人工核对前不得回退或重试。
+- 当前目录枚举不能证明未知写请求的因果关系，不得按同名、同 URL 或相似内容自动对账。
+
+生成前没有已批准的只读“目录可写”预检：目录可读、可列出、当前空间身份或个人空间身份都不能
+证明可以写入，也不得通过试写或隐藏写进行权限预检。因此不承诺在提交前识别空间权限不足。目标空间或目录本身不明确时，
+仍须在提交前让用户选择；但目标已明确而实际交付才收到 `PERMISSION_DENIED` 或
+`DELIVERY_PERMISSION_DENIED` 时，不必等待新增后端接口：立即停止原交付、保留原任务/作业/产物和
+被拒绝的空间/目录，向用户说明受限位置，并引导其选择新的显式位置。
+
+## 独立媒体提交前的个人目录解析
+
+入口 Skill 对“未指定画布、未指定个人/团队交付目录且非仅下载”的独立图片、视频或音频在费用确认前
+读取个人空间和目录并展示全部候选；不得把服务端根目录绑定为默认目标，底层交付命令始终只接受用户确认的显式 ID：
+
+1. 提交前用 `space current` 读取 `data.personal.id`，再用
+   `space directory list --group-id <data.personal.id>` 读取完整目录候选。该命令底层
+   `/apis/ping` 可能附带服务端写入副作用，因此每轮预检只调用一次，不高频轮询。
+2. 候选展示名称、完整层级、`directory_id`、`parent_id` 和 `root_id`；同名目录必须附层级和 ID。未指定目录时
+   必须等待用户从候选中选择，不得直接选用根目录（不能直接使用根目录）；目录分页/层级不完整或空间不唯一时在提交前失败关闭。
+3. 目标和费用确认前空间写请求数为 0。用户确认后，再报告目标和
+   待交付产物数量；目录创建是单独显式操作，创建并回读后重新列出候选。
+4. 每个成功产物仅在可信时使用一条
+   `space artifact deliver --job-id <job-id> --output-index <index>` 命令。两个值必须来自同一次任务
+   产物结果并同时传入；重新查询后顺序变化时应失败关闭，不得只按序号猜测。任务产物交付不是
+   `material upload`，不得重复上传生成结果。
+5. 用户生成前明确指定个人/团队目录时沿用目标并跳过选择；明确画布或仅下载时进入对应流程。
+   团队目标需要个人保底时必须在提交前披露并传入 `--fallback-to-personal`。写时明确权限拒绝且
+   `fallback_eligible=true` 只返回可恢复信息，不自动发送第二次写；其他拒绝和未知态只报告交付失败，
+   不得重新生成或自动改投。
+6. 生成状态与交付状态分开报告；已处于 `delivery_status=AWAITING_DESTINATION` 的任务恢复目录选择，交付失败或未知也不改变生成结论。
+   独立图片、视频和音频默认交付在线结果和空间素材；只有用户明确要求本地下载时才披露并执行本地副本；画布写入和媒体处理仍不是默认动作；
+   媒体本地状态是入口 Skill 组合流程状态，不改变底层 `nadou image/video/audio` 响应封装；
+   明确画布流程不同时创建个人空间副本。
+
+## 团队空间在生成期间撤权
+
+任务生成成功后，若原团队目标明确返回 `PERMISSION_DENIED`，保留原任务/作业/产物、团队目标和
+拒绝原因，不得重试原目录或重新生成。未启用个人空间保底时，引导用户选择新的显式位置；已启用
+`--fallback-to-personal` 且返回 `fallback_eligible=true` 时，只使用错误详情中的个人根目录和原产物
+执行一条新的显式交付命令。当前失败命令自身不发送第二次写；个人目标不唯一、再次被拒绝或结果未知时
+立即停止，不继续换目录、换模式或重提任务。
+
+## 素材清单导出与差异
+
+```sh
+nadou space inventory export --group-id <group-id> \
+  --output ./inventory-before.json --profile <profile> --json
+nadou space inventory export --directory-id <directory-id> \
+  --output ./inventory-after.json --profile <profile> --json
+nadou space inventory diff --before ./inventory-before.json \
+  --after ./inventory-after.json --json
+```
+
+导出复用既有目录遍历，只记录稳定素材身份、类型、名称、父目录和目录路径，不把素材 URL 当持久身份。
+输出默认不覆盖；遍历中断时仍可保存 `complete=false` 的版本化清单和失败位置，不能伪装完整快照。
+
+差异按稳定 `kind:id` 比较新增、删除、移动、修改和未变化。任一侧遍历不完整时，缺失项归入
+`unknown`，不得推断为删除或新增；范围不一致默认拒绝比较。显式使用 `--allow-scope-mismatch` 只会给出
+保守的不可比结果，不会把不同空间或目录的差异包装为确定结论。

package/skills/nadou/commands/system.md

@@ -0,0 +1,50 @@
+# 系统与 Agent 能力
+
+每个用户回合首次执行纳逗Pro产品操作前，先运行 `nadou version --json`，检查
+`_notice.update`；同一回合后续命令复用该结果。存在更新提示时，在继续生成、任务、
+空间、素材或画布操作前告知当前版本、最新版本和建议的 `nadou update` 命令，并询问
+是否升级。未经明确确认不得升级。确认后执行：
+
+```sh
+nadou update --json --no-interactive
+nadou version --json
+```
+
+升级失败时报告错误，不猜测版本或重复写操作。需要检查本机依赖和配置健康状态时使用
+`nadou doctor --json`；它与版本检查含义不同。字幕处理不能只看 `ffmpeg=available`，
+还要确认 `subtitle_filter=available`；其他值按 `subtitle_hint` 修复本机 FFmpeg 构建。
+`nadou capability list --json` 是命令能力、
+作用域、副作用、异步性、可用状态和参考文档的本地索引；读取单项使用
+`capability describe <id>`。
+
+`--json` 中的字段名、枚举、命令和摘要使用稳定英文协议，不随系统语言变化；不要在自动化中匹配翻译文本。
+需要中文用途、参数、安全边界和恢复规则时，读取每项 `reference` 指向的随包文档。非 JSON 的人类输出
+未来可以独立本地化，但不能改变默认机器协议。
+
+业务命令失败时，向用户保留稳定错误码、`error.message`、`meta.request_id` 及已经取得的任务、画布、
+节点或变更标识；这些是服务排查和原任务恢复的最小证据。`nadou doctor --json` 只诊断本机环境，
+不能替代服务端错误信息，也不能把失败授权解释为允许重新提交。不得要求用户粘贴凭据或未脱敏日志。
+
+能力项的 `operation` 表达用户意图，`effects` 表达执行时实际可能读写的状态，
+两者不能互相推断。HTTP `GET` 或 `operation=read` 也可能包含 `remote_write`；
+一个命令同时读远端、修改远端并写本地时会返回多个副作用。`remote_write`
+不等同于破坏性操作，删除或终止使用单独的 `remote_destructive`。
+
+机器结果使用 `--json`，事件流使用 `--jsonl`。同一编排可统一传安全的
+`--trace-id <id>`；`meta.trace_id` 关联本地证据，每条命令仍有独立
+`meta.request_id`。跟踪 ID 不是凭证、任务 ID、变更 ID 或幂等键。
+
+`nadou doctor --json` 检查 CLI 运行环境。Skill 自描述与同步使用：
+
+```sh
+nadou skill list --json
+nadou skill read --json
+nadou skill status --json
+```
+
+`status` 只读本地同步状态，适合快速检查；只有需要扫描所有 Agent 安装目标时才使用较慢的
+`nadou skill doctor --json`。`_notice.skills` 仅表示随包版本与最近同步版本不同，不影响业务命令。
+`nadou skill install`、`nadou update` 和安装器同步会覆盖已安装的 Nadou Skill；升级和 Skill
+安装会修改本机，必须获得用户同意。
+
+配置命令只管理本机账号配置。不得把令牌或 Cookie 写入配置。`completion` 是 Cobra 提供的命令行辅助能力，不属于 Nadou 产品能力目录。

package/skills/nadou/commands/task-request.md

@@ -0,0 +1,188 @@
+# 任务请求构造
+
+`task submit` / `estimate` 通过 `--body-file` 接收完整 NadouAI
+任务请求对象（通常含长提示词与模型参数，适合落盘）。`canvas node generate` 默认不需要请求文件，
+它会从画布目标节点和入边依赖自动派生任务请求；普通 Agent 流程不应为画布生成构造任务文件。
+画布节点/连线的短结构 JSON 不要走本页，
+改用 `--stdin`，约定见 [canvas.md](canvas.md)。Agent 不应手写或猜测通用外壳；优先让当前 CLI
+根据当前账号的动态模型目录构造请求。
+
+## UTF-8 输入约定
+
+`--body-file` 文件必须使用 UTF-8。Windows PowerShell 不要把包含中文的字符串直接管道到原生命令的
+`--stdin`，因为字符串管道可能在 CLI 收到数据前把中文替换为 `?`。需要保留中文时，先将 JSON 写成
+UTF-8 文件再传入；CLI 会在请求前校验 UTF-8，并兼容 UTF-8 BOM。已经被上游转换为 `?` 的字符无法由
+CLI 恢复，不能通过重试解决。
+
+## 推荐：用预览模式生成请求
+
+图片请求：
+
+```sh
+nadou image --prompt-file prompt.txt --model <image-model> \
+  --profile <profile> --dry-run --json
+```
+
+视频请求：
+
+```sh
+nadou video --prompt-file prompt.txt --model <video-model> \
+  --scenario <scenario> --profile <profile> --dry-run --json
+```
+
+`--dry-run` 会执行登录检查和模型目录读取，但不会估算积分、提交任务或写画布。成功响应的 `data.request` 是待提交的任务对象；将**该字段本身**保存为 `request.json`，不要把外层 CLI 响应封装一起写入文件。
+
+在 dry-run、estimate 和 submit 前，CLI 会对最终请求中的媒体 URL 做提交前预检：检查 URL 是否完整可解析、`params.image`/`form.referenceImages`/`thumbsOrder` 等重复字段是否一致，并对每个唯一 URL 做有界可访问性和内容探测（图片会读取有限片段并验证可解码，错误页/非媒体响应会拒绝）。预检不按内网/外网域名单独判定，不会改写、补全或跟随重定向；失败时返回 `MEDIA_REFERENCE_PREFLIGHT_FAILED`、来源字段和脱敏 URL 指纹，`request_sent=false`，不得继续估价或提交。
+
+模型必须来自本次账号动态目录。使用 `nadou model list --scenario <scenario> --json` 和 `model schema` 获取当前图片、视频或音频场景的可用模型及参数；参考素材只按模型参数结构和用户意图提供，不猜 URL、枚举或默认值。
+
+## 原子图片/视频/音频费用预检
+
+入口 Skill 对独立图片、视频和音频使用以下顺序，确认前不得提交：
+
+```sh
+nadou space current --profile <profile> --no-interactive --json
+nadou points summary --profile <profile> --no-interactive --json
+nadou task estimate --body-file request.json --profile <profile> --json
+```
+
+`space current` 返回当前激活计费空间的权威 ID、名称和类型。其底层 `/apis/ping` 可能附带用户初始化
+或更新副作用，因此每轮费用预检只读取一次，不用于轮询。未指定个人/团队目录时，本阶段读取目录列表
+并展示全部候选，等待用户选择后绑定为计划目标；任务取得可信产物后只向该目标执行交付。不得直接选根目录。
+`points summary` 只返回当前激活空间的服务端权威余额投影，不返回可用于展示的空间身份，不能单独用它
+猜测空间。当前计费空间与后续交付目标是不同概念，不能根据交付目标推断计费钱包。
+Agent 优先读取 `balance.value` 和 `balance.display`。数值余额执行本地不足校验；当
+`value=null/display=∞` 时不做数值减法，当前余额与预计执行后余额都展示 `∞`，但仍执行同请求估价、
+费用确认、任务级积分上限和服务端最终校验。余额策略不明确时失败关闭。
+
+`task estimate` 必须读取刚才预览生成的同一个请求文件。记录服务端返回的 `points`、
+`estimable`、`binding`、`use_activity_point` 和可用请求 ID；明确的 `points=0` 是
+`estimable=true` 的精确零积分估价，缺失、负数或非数值积分按后端契约错误处理。估价失败、
+数值余额未知或不足、余额策略无法确定时停止。向用户展示：
+
+- 模型、场景、影响费用的关键参数和生成数量；
+- 预计积分、当前余额和标为“按当前估价推算”的执行后余额；多产物或批量任务展示总预计积分；
+- 当前激活计费空间与计划交付目标；
+- 估价不锁价、不预占积分，最终校验和实际扣费以服务端提交结果为准。
+
+推荐费用确认摘要使用固定字段，避免 Agent 在多轮对话中丢失含义：
+
+```text
+模型/场景：<model> / <scenario>
+关键参数：duration=<...>, ratio=<...>, resolution=<...>, audio=<...>, count=<...>
+预计消耗：<points> 积分（use_activity_point=<true|false>, binding=false）
+当前余额：<balance.display>
+预计执行后余额：<数值余额减去 points，或 ∞>（仅按当前估价推算）
+计费空间：<active-space-id/name>
+计划交付：<用户从候选中选择的 personal/team-space/directory/canvas 目标；未选择时列出候选>
+附加动作：<必要输入上传、本地下载、画布写入或派生媒体；没有则写“无”>
+说明：估价不锁价、不预占积分，最终扣费以后端提交结果为准。
+```
+
+确认只授权执行摘要中明确列出的动作。生成请求本身只获得同一请求的一次任务提交授权；必要输入上传、
+画布写入、媒体变换以及未披露的本地下载都不在授权范围内。独立图片、视频和音频默认只交付
+在线结果与空间素材；本地下载是显式旁路动作，只有“附加动作”明确包含用户指定的本地目录和不覆盖规则时，
+本轮确认才授权创建本地文件。非交互自动化也必须预先明确授权该动作和目标，不能静默写文件。未指定空间目录
+时仍须先列出候选并等待明确目录授权；用户指定团队目录或画布后，目标变化使旧确认失效。
+
+生成完成且取得可信产物后，入口编排使用提交前绑定的交付计划执行显式交付；它是 Skill 组合状态，
+不改变底层原子命令 JSON 参数结构。只有已处于 `delivery_status=AWAITING_DESTINATION` 的任务才恢复目录选择；
+正常提交不在生成完成后临时询问。
+
+用户最初提出创作要求不等于接受未知费用。产品尚未定义统一高成本阈值前，所有预计消耗
+大于零的交互式图片/视频/音频任务都需要估价后确认。用户事先给出的明确任务级积分上限，只能用于
+当前请求、账号配置和计费空间；估价不超过上限、数值余额充足（或权威非数值余额）且请求未变化时
+可以免去再次询问。
+`--no-interactive` 和现有 `--yes` 都不是费用授权。非交互流水线如果没有本轮外部确认或任务级预算
+授权，必须返回需要费用确认的结果，不能静默调用 `task submit`。
+
+模型、场景、提示词、参考素材、时长、比例、清晰度、音频、数量、账号配置、当前计费空间
+或请求文件内容任一变化，旧估价和旧确认全部失效，必须从预览开始重新执行。不要分别
+缓存并拼接旧余额、旧估价或旧确认。
+
+## 显式选择目录
+
+当用户明确要求选择目标目录或拒绝默认个人根目录时，入口 Agent 必须在确认或提交前列出候选目录：
+
+```sh
+nadou space directory list --group-id <personal-space-id> --profile <profile> --no-interactive --json
+```
+
+展示每个权威候选的 `name`、`id`/`directory_id`、`parent_id`、`root_id` 和 `is_root`；名称重复时必须带层级。不得根据名称推断 ID 或路径。将这些候选与同一请求的估价、模型参数和余额合并到一份确认摘要中。用户必须在同一条回复中选择目录并授权费用/提交（例如 `确认，目录 17846`）；不得把目录选择与费用确认拆成两次询问。根据同一份权威响应校验所选 ID；请求、账号配置、计费空间和目录事实均未变化时，可以复用估价。用户取消或目录列表不完整时，提交次数和空间写入次数都保持为零。
+
+## 定时请求
+
+定时默认关闭。只有用户明确选择模式、未来时间和 IANA 时区后才进入
+[schedule.md](schedule.md)：
+
+- `server`：在图片/视频预览上同时传
+  `--schedule-mode server --scheduled-at <time> --timezone <zone>`。CLI 将唯一
+  `scheduledTime` 写入 `data.request` 顶层；保存该字段本身后，估价和提交必须读取
+  同一文件。画布任务执行时间必须按用户时区是每小时 `00` 或 `30` 分钟且秒数为 `00`；向用户询问该时间时，
+  示例只能使用 `HH:00` 或 `HH:30`，不得给出其他分钟。普通服务端
+  任务沿用服务端既有时间规则。确认后时间已过期时，`task submit`
+  会在网络前拒绝，必须重新取得用户时间选择和费用确认。
+- `local`：先运行不带任何定时参数的普通预览，确保请求没有 `scheduledTime`，再把同一
+  请求文件交给 `schedule create`。本地计划保存原始请求字节和摘要，到期只由显式执行程序
+  提交一次。
+
+不得手写 `scheduledTime`、把本地请求改造成服务端请求，或在两种模式之间自动切换。
+
+## 提交到独立任务
+
+只有完成费用预检并取得本轮确认或有效任务级预算授权后，才执行：
+
+```sh
+nadou task submit --body-file request.json --profile <profile> --no-interactive --json
+```
+
+`estimate` 不提交任务。`submit` 和估价必须使用同一个请求文件且只执行一次；确认后不得
+重新运行 `nadou image`、`nadou video` 或 `nadou audio` 来重建请求。结果未知时保留请求 ID 和已知
+任务 ID，不得自动重新估价、重新构造或重复提交。
+
+费用预检覆盖原子图片、视频和音频。原子文本是否支持同等估价需要单独的真实环境证据；
+在公开帮助和验收契约更新前，不得对文本作相同承诺。
+
+## 提交到既有画布节点
+
+先确认明确的画布和节点。默认提交不需要请求文件：
+
+```sh
+nadou canvas get --canvas-id <canvas-id> --node-id <node-id> \
+  --profile <profile> --no-interactive --json
+nadou canvas node estimate --canvas-id <canvas-id> --node-id <node-id> \
+  --profile <profile> --no-interactive --json
+nadou canvas node generate --canvas-id <canvas-id> --node-id <node-id> \
+  --profile <profile> --no-interactive --json
+```
+
+`canvas node estimate` 可重复传入最多 20 个不同的 `--node-id`，从当前 Graph 为每个节点派生与生成相同的
+请求并汇总积分，但不提交任务或写 Graph。估价不锁定价格，后续生成会重新读取画布。
+
+`canvas node generate` 会校验节点存在，并从目标节点 `data.prompt`、`data.modelName`、`data.modelType`、
+`data.taskType`、`data.modelParams` 自动构建请求。若任务需要参考素材，先创建从参考节点到目标节点的边；
+CLI 会从入边源节点读取 `data.url` / `outputUrls` 填入请求。它不创建节点；任务提交成功后仅通过
+`canvas node generate` 的受控运行态补丁写入生成中投影，普通修改仍不能写这些字段。
+节点的 `data.modelParams.model` 是画布界面的模型选择锚点，必须存在并与 `data.modelName` 使用同一个
+真实模型 ID；不要直接把不含 `model` 的 `model schema.defaults` 原样写入节点。
+后端接受任务后，CLI 先保存返回的任务 ID 和运行态投影，再用
+`canvas node wait --node-id <node-id> --task-id <task-id>`
+观察任务终态并确认回调已同步到目标节点。
+
+高级调试或回放才显式启用隐藏的请求文件选项；CLI 会把所选 `workflowId/nodeId` 注入请求，
+如果文件中已有冲突值，会在提交前拒绝，并继续校验请求与目标节点已保存配置一致。普通 Agent 不走这条路径。
+
+`image/video --dry-run --json` 只用于独立任务预览或高级回放准备；它不是画布节点创建。画布路径中，
+先把提示词/模型配置写入目标节点、创建依赖边，再触发 `canvas node generate`。
+
+## 边界
+
+- `data.request` 来自当前 CLI 与当前模型目录；不要复用其他环境或过期目录生成的请求。
+- `--dry-run` 只是无任务写入的预览，不是服务端最终成功保证。
+- 估价不锁价；本地计算的预计余额只能作为展示性推算，不能替代服务端最终校验。
+- 不自行调用后端，不在请求中加入 Cookie、令牌、Authorization、结果 URL 或回调状态。
+- 长提示词继续使用 `--prompt-file` 或 `--stdin`，不要展开到命令行。
+- 独立任务或高级回放的完整请求用 `--body-file`；不要为了“少写文件”把大 JSON 塞进命令行参数。
+- 请求文件可能包含完整提示词或参考素材地址，只保留到本次提交和恢复取证所需的最短时间，不写入日志或版本库。
+- 本地计划确需跨重启保存完整请求；只能由 `schedule create` 写入其作用域私有目录，不能复制到日志、
+  工作区或普通状态文件。`schedule list/status` 只输出安全摘要。