@aswless_854771076/ai_short_studio_cli 0.1.97 → 0.1.99

package/README.md

@@ -7,31 +7,29 @@ npm view @aswless_854771076/ai_short_studio_cli dist-tags.latest
 npm install --global @aswless_854771076/ai_short_studio_cli@latest
 ai-short-studio --version
 ai-short-studio auth login --google
+ai-short-studio auth login --memhub
 ai-short-studio project list --json
 ai-short-studio canvas node types --json
-ai-short-studio canvas node quote <nodeId> --project <projectId> --json
 ```
 
-npm 包仅内置 `using-vvicat-ai-short-studio-cli` 一个 Agent Skill。短剧编剧、文风润色、逐镜复刻、动作预演、声音字幕、Remotion 剪辑等方法按主 Skill 索引读取随包参考资料；不要求另装创作 Skill。安装或升级 CLI 时，`postinstall` 会自动安装或更新主 Skill。仅校验为旧版 CLI 托管且未修改的 `short-drama`、`humanizer` 目录会被清理；用户修改或非托管目录保留并在状态中提示。设置 `VVICAT_SKIP_SKILL_INSTALL=1` 可关闭自动安装。
+npm 包只内置一个 `using-vvicat-ai-short-studio-cli` Agent Skill。hypit、短剧和 humanizer 等第三方资料统一放在该 Skill 的 `references/` 下。安装或升级 CLI 时，`postinstall` 会自动安装或更新这个 Skill；用户修改过或不由 CLI 管理的副本不会被覆盖。设置 `VVICAT_SKIP_SKILL_INSTALL=1` 可关闭自动安装。
 
-`skill install/status/update` 只管理主 Skill。旧 `--skill short-drama`、`--skill humanizer` 是指向主 Skill 的弃用别名，会输出提示；不再创建旧目录。编剧和润色按主 Skill 索引完成，画布选版是唯一项目状态。
+`skill install/status/update` 管理这个唯一 Skill。短剧创作、humanizer 审计和 hypit 视频制作资料通过主 Skill 的 references 按需读取。
 
-邮箱注册和登录从 stdin 读取密码：
+生产环境登录使用 MemHub 浏览器授权；兼容 Supabase 的邮箱注册和登录从 stdin 读取密码：
 
 ```bash
 ai-short-studio auth signup --email user@example.com --password-stdin
 ai-short-studio auth login --email user@example.com --password-stdin
-# 或复用网页端 MemHub 身份（会自动打开浏览器）
-ai-short-studio auth login --provider memhub
 ```
 
 Agent 代操作时，用户已在当前会话明确提供的密码只能直接写入正在等待的隐藏密码提示，不得复述、拼入 shell 命令、落盘或跨会话保存。
 
-注册响应中的 `confirmationRequired` 表示是否需要先完成邮件验证。Supabase 直接返回会话时，CLI 会立即登录并把 refresh token 保存到系统钥匙串；需要邮件验证时不会写入空凭据，验证后再执行登录。
+注册响应中的 `confirmationRequired` 表示是否需要先完成邮件验证。Supabase 直接返回会话时，CLI 会立即登录并把 refresh token 保存到系统钥匙串；需要邮件验证时不会写入空凭据，验证后再执行登录。MemHub 登录成功后使用短期 API Key 访问服务。
 
 注册确认链接使用当前 profile 的 `baseUrl` 和 `--locale`，指向同域的 `/{locale}/auth/callback`。API 与网页需保持同域，并在 Supabase Redirect URLs 中允许各环境的 `/**`；Site URL 只作为未显式传入回调时的生产兜底。
 
-Supabase 登录只把 refresh token 保存到系统钥匙串；MemHub 登录保存由服务端签发的 `cli:access` 专用凭据，不保存 MemHub access/refresh/ID token。MemHub 使用浏览器 OIDC、loopback 回调、PKCE 和一次性授权码交换，长期凭据不会进入浏览器 URL。短期 access token 会写入权限为 `0600` 的本机 session 缓存；同一 profile 的并发进程通过跨进程锁共享刷新结果。`auth logout` 会清除缓存，并撤销 MemHub CLI 凭据。CI 可用 `VVICAT_ACCESS_TOKEN` 直接注入临时令牌。未配置服务地址时默认连接 `https://ai-short-studio.vvicat.dev`，`--base-url`、`VVICAT_BASE_URL` 和当前 profile 可依次覆盖。Supabase 登录会从 bootstrap 取得公共配置；MemHub 登录不依赖 Supabase 公共配置。服务地址、认证提供方和其他非敏感 profile 数据写入系统配置目录；切换环境时必须使用独立的 `--profile`。
+CLI 只把 refresh token 保存到系统钥匙串。短期 access token 会写入权限为 `0600` 的本机 session 缓存；同一 profile 的并发进程通过跨进程锁共享刷新结果，只有缓存缺失或确实需要刷新时才访问钥匙串，从而避免 Agent 批量操作反复触发 macOS Keychain。退出登录会清除该缓存，CI 可用 `VVICAT_ACCESS_TOKEN` 直接注入临时令牌。未配置服务地址时默认连接 `https://ai-short-studio.vvicat.dev`，`--base-url`、`VVICAT_BASE_URL` 和当前 profile 可依次覆盖。首次登录会从服务端 bootstrap 取得 Supabase 公共配置，也可用 `VVICAT_SUPABASE_URL`、`VVICAT_SUPABASE_PUBLISHABLE_KEY` 显式覆盖。Google 登录在 Windows 上直接调用系统 URL Handler，确保带 `&` 的 PKCE 授权参数完整传给浏览器。服务地址和非敏感 profile 写入系统配置目录；切换环境时必须使用独立的 `--profile`，避免复用旧认证。
 
 创作前运行 `ai-short-studio preflight --json`。CLI 会通过公开的 `/api/v1/bootstrap` 检查服务连通性、取得 Supabase 公共配置、读取 npm `latest` 稳定版本并默认更新当前全局包，再检查登录态和文本、人物、场景、故事版、视频模型配置。npm registry 暂时不可用时服务端使用配置版本降级。更新后必须按输出重跑；明确不允许全局写入时使用 `--no-update`。
 
@@ -48,30 +46,11 @@ Supabase 登录只把 refresh token 保存到系统钥匙串；MemHub 登录保
 - `ai-short-studio canvas folder`：画布资产目录管理（5 预设 + 用户子目录 + 软删 + 跨项目复制）。
 - `ai-short-studio canvas episode`：列出或创建无限画布分集。其他画布命令用 `--episode <ID|集数>` 选择分集。
 - `ai-short-studio task`：异步任务读取、批量等待和取消。
-- `ai-short-studio config`：读取管理员发布的全局模型，管理个人默认模型和能力默认值；CLI 会拒绝写入 Provider、模型目录或工作流并发。
-- `ai-short-studio config ai-provider`（管理员）：列出、查看、部分更新、连通性测试、拉取模型目录与上报能力诊断。仅供管理员账号使用。
+- `ai-short-studio config`：读取管理员发布的全局模型，管理个人默认模型、能力默认值和并发配置；CLI 会拒绝写入 Provider 或模型目录。
 
 CLI 不提供分集删除或任务人工复核提交；这两类需要确认生产资产或保留范围的操作继续在网页端完成。
 
-`config get` 返回管理员发布的全局模型与个人默认值，不返回供应商密钥。已保存的默认模型失效时，服务端会改用同类型的首个已启用模型，并用实时选项的第一项补齐该模型缺失的能力默认值。Comfly 和 RunningHub 的凭据、服务地址与工作流均由服务端维护；CLI 预检只检查默认模型及能力选项。`config set` 会拒绝写入任何供应商、模型目录或工作流并发；工作流并发由管理员在用户管理中配置。
-
-`config ai-provider` 把管理员侧的 AI Provider 管理从网页端下沉到 CLI，方便部署/CI 与 Agent 复核：
-
-```bash
-ai-short-studio config ai-provider list --json
-ai-short-studio config ai-provider get --id <providerId> --json
-ai-short-studio config ai-provider set --id <providerId> [--base-url <url>] [--api-key <key>] [--protocol <mode>] [--enabled true|false] [--json]
-ai-short-studio config ai-provider test --id <providerId> --json
-ai-short-studio config ai-provider models --id <providerId> --json
-ai-short-studio config ai-provider capabilities --json
-```
-
-- `--api-key <key>` 仅写入、不会回显，但会留在 shell 历史里。**CI / 脚本场景改用 `--file <path.json>`**（省略 `--file` 时从 stdin 读完整 JSON body），避免密钥进命令行。
-- `--protocol <mode>` 取值 `openai` / `comfyui-official` / `runninghub`；`--api-mode` 用于 gateway 协议族字段。
-- `--file` 传完整 JSON body；`--create` 强制走 POST 创建（默认 PATCH 404 时自动回退 create）。
-- `test` 输出延迟与 HTTP 状态，不消耗配额外的 token。`models` 只在 `enabled` 且最近一次 `test` 成功时返回目录。
-- `capabilities` 报告当前生效的私有/LAN baseUrl 白名单（来自环境变量 `VVICAT_ALLOW_PRIVATE_PROVIDER_BASE_URLS`，CSV `host:port`）、已注册 Provider 数量、未配置 Provider 类型与缺失项，方便 Agent 明确自己能做什么、缺什么。
-- 设置 Provider `baseUrl` 时若目标是私有/LAN 主机（如 `http://127.0.0.1:8188`、`http://192.168.3.30:8188` 本地 ComfyUI），必须在运行 Next.js 的环境里把 `VVICAT_ALLOW_PRIVATE_PROVIDER_BASE_URLS=127.0.0.1:8188,192.168.3.30:8188` 显式打开；公网 URL 仍强制 HTTPS 与公网 IP 校验。
+`config get` 返回管理员发布的全局模型与个人默认值，不返回供应商密钥。已保存的默认模型失效时，服务端会改用同类型的首个已启用模型，并用实时选项的第一项补齐该模型缺失的能力默认值。Comfly 和 RunningHub 的凭据、服务地址与工作流均由服务端维护；CLI 预检只检查默认模型及能力选项。`config set` 会拒绝写入任何供应商或模型目录。
 
 ```bash
 ai-short-studio canvas edge add --project <projectId> --from <sourceNodeId>:<sourceHandle> --to <targetNodeId>:<targetHandle> --json
@@ -88,195 +67,6 @@ ai-short-studio canvas folder copy-cross-project --project <sourceProjectId> --a
 
 `canvas folder copy-cross-project` 可用 `--target-episode-id` 指定复制品所属分集；省略 `--target-folder-id` 时，复制品进入该分集的未分类资产。目标目录必须属于目标项目和目标分集。两个参数都会去除首尾空白并拒绝空白值。该命令只复制资产及版本，不复制源目录结构。
 
-## 命令参考
-
-本节按 `src/commands/**` 的实际命令定义逐条列出。退出码由 `src/base-command.ts` 的 `exitCode()` 统一映射：`0` 成功、`3` 未认证（HTTP 401）、`4` 不存在（HTTP 404）、`5` 禁止或冲突（HTTP 403 / 409）、`6` 参数错误（HTTP 400 / 422）、`7` 其他错误（其他 HTTP 状态或本地异常）、`8` 仅 `task wait` 专有——批量等待结束但仍有任务未 `completed` 时以 8 退出。
-
-### 全局 flag
-
-所有命令继承 `BaseCommand.baseFlags`（`src/base-command.ts`）：
-
-| Flag | 类型 | 默认值 | 必填 | 说明 |
-| ---- | ---- | ------ | ---- | ---- |
-| `--base-url` | string | 无 | 否 | VVICAT 服务地址；env `VVICAT_BASE_URL` |
-| `--json` | boolean | `false` | 否 | 输出稳定 JSON |
-| `--locale` | string | `zh` | 否 | 响应语言，可选 `zh` / `en` |
-| `--profile` | string | 无 | 否 | 配置档案名称 |
-| `--episode` | string | 无 | 否 | 画布分集 ID 或集数；env `VVICAT_CANVAS_EPISODE` |
-
-`--project <projectId>`（`command-helpers.ts` 的 `projectFlag`）在所有画布/项目子命令中**必填**。
-
-### preflight
-
-| 命令 | 用途 | 参数 / flag | 示例 | 失败退出码 |
-| ---- | ---- | ----------- | ---- | ---------- |
-| `preflight` | 创作前检查 CLI 版本、服务连通性、认证和模型配置 | `--update`（boolean，默认 `true`，`allowNo`，用 `--no-update` 关闭；服务端声明的 `minCliVersion` 强制升级时不可跳过） | `ai-short-studio preflight --json` | 3 / 4 / 7 |
-
-更新成功后输出 `restartRequired: true` 与 `nextAction`，必须重跑 preflight。
-
-### auth
-
-| 命令 | 用途 | 参数 / flag | 示例 | 失败退出码 |
-| ---- | ---- | ----------- | ---- | ---------- |
-| `auth signup` | 使用邮箱和密码注册账号 | `--email`、`--password-stdin`（boolean，默认 `false`）、`--supabase-url`（env `VVICAT_SUPABASE_URL`）、`--supabase-publishable-key`（env `VVICAT_SUPABASE_PUBLISHABLE_KEY`）、`--locale` | `ai-short-studio auth signup --email user@example.com --password-stdin` | 6 / 7 |
-| `auth login` | 使用 Supabase 或网页端 MemHub 身份登录 | `--email`、`--google`、`--provider memhub`、`--password-stdin`、`--supabase-url`、`--supabase-publishable-key` | `ai-short-studio auth login --provider memhub` | 3 / 7 |
-| `auth logout` | 注销并清除本机 refresh token 与 session 缓存 | 仅全局 flag | `ai-short-studio auth logout --json` | 7 |
-| `auth status` | 检查当前登录状态 | 仅全局 flag | `ai-short-studio auth status --json` | 3 / 7 |
-
-`auth signup` 输出 `registrationAccepted` / `authenticated` / `confirmationRequired`。
-
-### project
-
-| 命令 | 用途 | 参数 / flag | 示例 | 失败退出码 |
-| ---- | ---- | ----------- | ---- | ---------- |
-| `project list` | 列出无限画布项目 | `--page`（integer，默认 `1`）、`--page-size`（integer，默认 `50`）、`--search` | `ai-short-studio project list --json` | 3 / 7 |
-| `project create` | 创建无限画布项目 | `--name`（**必填**）、`--description` | `ai-short-studio project create --name "CLI Draft" --json` | 5 / 6 / 7 |
-| `project get` | 读取单个项目 | 位置参数 `projectId`（**必填**） | `ai-short-studio project get <projectId> --json` | 4 / 7 |
-| `project update` | 更新项目名称与描述 | 位置参数 `projectId`（**必填**）、`--name`、`--description` | `ai-short-studio project update <projectId> --name "新名称" --json` | 4 / 5 / 7 |
-| `project delete` | 删除项目（不可逆） | 位置参数 `projectId`（**必填**）、`--yes`（**必填** boolean） | `ai-short-studio project delete <projectId> --yes --json` | 4 / 5 / 6 |
-
-项目创建与列表固定限定 `INFINITE_CANVAS`。
-
-### project provider（Pexels 素材供应商）
-
-| 命令 | 用途 | 参数 / flag | 示例 | 失败退出码 |
-| ---- | ---- | ----------- | ---- | ---------- |
-| `project provider get` | 读取项目 Pexels 供应商配置 | 位置参数 `projectId`（**必填**） | `ai-short-studio project provider get <projectId> --json` | 4 / 7 |
-| `project provider set` | 写入项目 Pexels 供应商配置 | 位置参数 `projectId`（**必填**）、`--file`（JSON 文件，省略时读 stdin） | `ai-short-studio project provider set <projectId> --file pexels.json --json` | 4 / 6 / 7 |
-| `project provider test` | 测试项目 Pexels 供应商连通性 | 位置参数 `projectId`（**必填**） | `ai-short-studio project provider test <projectId> --json` | 4 / 7 |
-
-### canvas（读取与图补丁）
-
-| 命令 | 用途 | 参数 / flag | 示例 | 失败退出码 |
-| ---- | ---- | ----------- | ---- | ---------- |
-| `canvas get` | 读取整张画布（节点 + 连线） | `--project`（必填） | `ai-short-studio canvas get --project "$PROJECT_ID" --json` | 4 / 7 |
-| `canvas inspect` | 一次读取并筛选节点、连线、资产、设置与节点目录 | `--include`（multiple，默认 `['summary','nodes','edges']`，可选 `summary/nodes/edges/assets/settings/node-types`）、`--kind`（multiple）、`--status`（multiple）、`--search`、`--operation`、`--resource-type`、`--producer-node` | `ai-short-studio canvas inspect --project "$PROJECT_ID" --include assets --include node-types --json` | 4 / 7 |
-| `canvas apply` | 执行低层画布图补丁（节点/连线/删除/视口） | `--file`（patch JSON，省略时读 stdin）、`--canvas-id`（已知画布 ID）、`--expected-version`（integer） | `ai-short-studio canvas apply --project "$PROJECT_ID" --canvas-id "$CANVAS_ID" --expected-version 7 --file patch.json --json` | 4 / 5 / 6 / 7 |
-
-`--canvas-id` 与 `--expected-version` 同时提供时跳过保存前的全图预读。
-
-### canvas settings
-
-| 命令 | 用途 | 参数 / flag | 示例 | 失败退出码 |
-| ---- | ---- | ----------- | ---- | ---------- |
-| `canvas settings get` | 读取项目设置（覆盖值 / 生效值 / 来源 + 实时 options） | `--project`（必填） | `ai-short-studio canvas settings get --project "$PROJECT_ID" --json` | 4 / 7 |
-| `canvas settings set` | 原子更新项目设置 | `--field` + `--value`（互斥于 `--file`）、`--file`（JSON 文件，省略时读 stdin） | `ai-short-studio canvas settings set --project "$PROJECT_ID" --file settings.json --json` | 4 / 5 / 6 / 7 |
-
-`--field` 与 `--value` 必须成对提供；`--file` 与二者互斥。批量写入时 `expectedVersion` 取最近一次 `settings get` 返回的 `version`；409 冲突后重新 `get` 再重试。
-
-### canvas node
-
-| 命令 | 用途 | 参数 / flag | 示例 | 失败退出码 |
-| ---- | ---- | ----------- | ---- | ---------- |
-| `canvas node types` | 读取服务端实时节点类型、默认配置与 schema | 位置参数 `kind`（可选，只看单个 kind） | `ai-short-studio canvas node types tts --json` | 4 / 7 |
-| `canvas node list` | 列出节点（客户端过滤） | `--kind`（multiple）、`--status`（multiple）、`--search`、`--producer-node` | `ai-short-studio canvas node list --project "$PROJECT_ID" --kind storyboard-shot --json` | 4 / 7 |
-| `canvas node get` | 读取单个节点 | 位置参数 `nodeId`（**必填**） | `ai-short-studio canvas node get <nodeId> --project "$PROJECT_ID" --json` | 4 / 7 |
-| `canvas node quote` | 只读核对节点计费参数与已发布价格，不提交任务 | 位置参数 `nodeId`（**必填**）、`--project` | `ai-short-studio canvas node quote <nodeId> --project "$PROJECT_ID" --json` | 4 / 7 |
-| `canvas node add` | 新建节点（只提交 kind + 配置，版本由服务端固定） | 位置参数 `kind`（**必填**）、`--x`（默认 `0`）、`--y`（默认 `0`）、`--title`、`--config`（JSON 文件） | `ai-short-studio canvas node add video-frame-extract --project "$PROJECT_ID" --config extract.json --json` | 5 / 6 / 7 |
-| `canvas node update` | 字段级更新单个节点 | 位置参数 `nodeId`（**必填**）、`--set 'key=<JSON>'`（multiple）、`--unset key`（multiple）、`--title`、`--x`、`--y`、`--config`（兼容旧入口，省略且无字段 flag 时读 stdin） | `ai-short-studio canvas node update <nodeId> --project "$PROJECT_ID" --set 'gridSize=9' --unset legacyField --json` | 4 / 5 / 6 / 7 |
-| `canvas node update-many` | 一次画布版本基线上原子更新多个节点 | `--file`（含 `updates` 数组的 JSON，省略时读 stdin） | `ai-short-studio canvas node update-many --project "$PROJECT_ID" --file updates.json --json` | 4 / 5 / 6 / 7 |
-| `canvas node delete` | 删除节点 | 位置参数 `nodeId`（**必填**）、`--yes`（**必填** boolean） | `ai-short-studio canvas node delete <nodeId> --project "$PROJECT_ID" --yes --json` | 4 / 5 / 6 |
-| `canvas node run` | 提交节点执行，可批量并等待 | 位置参数 `nodeId`（可选）、`--node`（multiple，批量）、`--concurrency`（默认 `4`，范围 1–16）、`--wait`（默认 `false`）、`--interval`（默认 `1000` ms）、`--max-wait-ms`（默认 `0` = 不超时）、`--max-attempts`（默认 `0` = 不重试）、`--auto-select-version`（默认 `false`） | `ai-short-studio canvas node run --project "$PROJECT_ID" --node <node1> --node <node2> --concurrency 4 --wait --json` | 4 / 5 / 7 |
-| `canvas node edit-shot` | 编辑镜头并追加人工 DOCUMENT 版本 | 位置参数 `nodeId`（**必填**，必须 `kind=storyboard-shot`）、`--file`（镜头 JSON，省略时读 stdin） | `ai-short-studio canvas node edit-shot <nodeId> --project "$PROJECT_ID" --file shot.json --json` | 4 / 5 / 6 / 7 |
-| `canvas node edit-resource` | 编辑结构化资源并追加人工版本 | 位置参数 `nodeId`（**必填**，必须 `artifact.type=GENERATED_RESOURCE`）、`--file`（结构化资源 JSON，省略时读 stdin） | `ai-short-studio canvas node edit-resource <nodeId> --project "$PROJECT_ID" --file resource.json --json` | 4 / 5 / 6 / 7 |
-
-`--max-attempts > 0` 只在单节点下生效，批量时 CLI 打印 warn 并忽略。`edit-shot` / `edit-resource` 具有独立并发基线，409 后需重新读取画布与当前选版。
-
-### canvas edge
-
-| 命令 | 用途 | 参数 / flag | 示例 | 失败退出码 |
-| ---- | ---- | ----------- | ---- | ---------- |
-| `canvas edge add`（别名实现 `edge connect`） | 创建连线 | `--from <sourceNodeId>:<sourceHandle>`（**必填**）、`--to <targetNodeId>:<targetHandle>`（**必填**） | `ai-short-studio canvas edge add --project "$PROJECT_ID" --from <n1>:image --to <n2>:start-frame --json` | 4 / 6 / 7 |
-| `canvas edge delete`（别名实现 `edge disconnect`） | 删除连线 | 位置参数 `edgeId`（**必填**）、`--yes`（**必填** boolean） | `ai-short-studio canvas edge delete <edgeId> --project "$PROJECT_ID" --yes --json` | 4 / 5 / 6 |
-| `canvas edge list` | 列出连线 | `--project`（必填） | `ai-short-studio canvas edge list --project "$PROJECT_ID" --json` | 4 / 7 |
-
-### canvas continuity
-
-| 命令 | 用途 | 参数 / flag | 示例 | 失败退出码 |
-| ---- | ---- | ----------- | ---- | ---------- |
-| `canvas continuity analyze` | 生成视频前零费用分析镜头依赖，可修复已具备源视频的首尾帧连线 | `--apply-ready`（boolean，默认 `false`；开启后以分析返回的 `canvasVersion` 为 `expectedVersion` 提交 `applyAll: true`） | `ai-short-studio canvas continuity analyze --project "$PROJECT_ID" --apply-ready --json` | 4 / 5 / 7 |
-
-### canvas asset
-
-| 命令 | 用途 | 参数 / flag | 示例 | 失败退出码 |
-| ---- | ---- | ----------- | ---- | ---------- |
-| `canvas asset list` | 列出画布资产 | `--kind`、`--search` | `ai-short-studio canvas asset list --project "$PROJECT_ID" --json` | 4 / 7 |
-| `canvas asset get` | 读取单个资产及版本 | 位置参数 `assetId`（**必填**） | `ai-short-studio canvas asset get <assetId> --project "$PROJECT_ID" --json` | 4 / 7 |
-| `canvas asset upload` | 上传资产到 `/api/assets/upload` | 位置参数 `file`（**必填**，本地文件路径）、`--kind`（可选 `image` / `video` / `audio` / `voice`；缺省按扩展名推断，无法识别时报错） | `ai-short-studio canvas asset upload ./voice.wav --project "$PROJECT_ID" --kind voice --json` | 4 / 6 / 7 |
-| `canvas asset download` | 下载资产媒体 | 位置参数 `assetId`（**必填**）、`--version`（缺省用 selected version）、`--output`（默认 `.`） | `ai-short-studio canvas asset download <assetId> --project "$PROJECT_ID" --output ./downloads` | 4 / 7 |
-| `canvas asset select-version`（实现 `asset select`） | 选择资产版本 | 位置参数 `assetId`（可选，与 `--asset` 二选一，不能同时给）、`--asset`、`--version`（**必填**） | `ai-short-studio canvas asset select-version <assetId> --project "$PROJECT_ID" --version <versionId> --json` | 4 / 6 / 7 |
-
-`--kind voice` 只接受音频文件（CLI 本地先拦截，不发必然 400 的请求）。下载先写 `.part` 再原子改名，文件名中的 `\/:*?"<>|` 替换为 `_`。
-
-### canvas folder
-
-| 命令 | 用途 | 参数 / flag | 示例 | 失败退出码 |
-| ---- | ---- | ----------- | ---- | ---------- |
-| `canvas folder list` | 列出目录树 | `--include-soft-deleted`（boolean，默认 `false`） | `ai-short-studio canvas folder list --project "$PROJECT_ID" --json` | 4 / 7 |
-| `canvas folder create` | 新建子目录 | `--name`（**必填**）、`--parent-id`（别名 `--parent`，省略挂到项目根） | `ai-short-studio canvas folder create --project "$PROJECT_ID" --name "武器" --json` | 4 / 5 / 7 |
-| `canvas folder rename` | 重命名目录 | `--folder-id`（别名 `--folder`，**必填**）、`--name`（**必填**） | `ai-short-studio canvas folder rename --project "$PROJECT_ID" --folder <folderId> --name "新名称" --json` | 4 / 5 / 7 |
-| `canvas folder move` | 同项目内移动目录 | `--folder-id`（**必填**）、`--parent-id`（**必填**） | `ai-short-studio canvas folder move --project "$PROJECT_ID" --folder <folderId> --parent-id <newParentId> --json` | 4 / 5 / 7 |
-| `canvas folder delete` | 软删目录 | `--folder-id`（**必填**） | `ai-short-studio canvas folder delete --project "$PROJECT_ID" --folder <folderId> --json` | 4 / 5 / 7 |
-| `canvas folder restore` | 恢复 30 天回收窗口内的软删目录 | `--folder-id`（**必填**） | `ai-short-studio canvas folder restore --project "$PROJECT_ID" --folder <folderId> --json` | 4 / 5 / 7 |
-| `canvas folder copy-cross-project` | 跨项目/跨分集复制资产（只复制资产与版本，不复制目录结构） | `--asset-id`（别名 `--asset`，**必填**）、`--target-project`（**必填**）、`--target-folder-id`（省略进未分类）、`--target-episode-id`（省略沿用服务端默认分集）；后两者拒绝空白值 | `ai-short-studio canvas folder copy-cross-project --project <src> --asset-id <assetId> --target-project <dst> --target-episode-id <epId> --target-folder-id <folderId> --json` | 4 / 5 / 6 / 7 |
-
-目录类错误码见 zh/en 用户手册的 `FOLDER_*` 对照表（`FOLDER_NOT_FOUND` 404 / `FOLDER_CONFLICT` 409 / `FOLDER_PRESET_IMMUTABLE` 409 / `FOLDER_IN_USE` 409 / `FOLDER_CYCLE_DETECTED` 409 / `FOLDER_INVALID_PARAMS` 422 / `FOLDER_FORBIDDEN` 403 / `FOLDER_GONE` 410）。
-
-### canvas episode
-
-| 命令 | 用途 | 参数 / flag | 示例 | 失败退出码 |
-| ---- | ---- | ----------- | ---- | ---------- |
-| `canvas episode list` | 列出分集 | `--project`（必填） | `ai-short-studio canvas episode list --project "$PROJECT_ID" --json` | 4 / 7 |
-| `canvas episode create` | 创建分集 | `--number`（integer，**必填**，`min: 1`）、`--name` | `ai-short-studio canvas episode create --project "$PROJECT_ID" --number 2 --json` | 4 / 5 / 6 |
-
-其他画布命令用 `--episode <ID|集数>` 选择分集（env `VVICAT_CANVAS_EPISODE`）。CLI 不提供分集删除。
-
-### task
-
-| 命令 | 用途 | 参数 / flag | 示例 | 失败退出码 |
-| ---- | ---- | ----------- | ---- | ---------- |
-| `task get` | 读取单个异步任务 | 位置参数 `taskId`（**必填**） | `ai-short-studio task get <taskId> --json` | 4 / 7 |
-| `task wait` | 轮询等待任务完成 | 位置参数 `taskId`（可选）、`--task`（multiple，批量）、`--concurrency`（默认 `4`，范围 1–16）、`--interval`（默认 `1000` ms）、`--max-wait-ms`（默认 `0` = 不超时） | `ai-short-studio task wait --task <task1> --task <task2> --concurrency 4 --json` | 4 / 7 / **8** |
-| `task cancel` | 取消异步任务 | 位置参数 `taskId`（**必填**）、`--yes`（**必填** boolean） | `ai-short-studio task cancel <taskId> --yes --json` | 4 / 5 / 6 |
-
-`task wait` 在批量结果中仍有任务未 `completed` 时以退出码 **8** 结束（`src/commands/task/wait.ts`），其他命令不产生 8。
-
-### config
-
-| 命令 | 用途 | 参数 / flag | 示例 | 失败退出码 |
-| ---- | ---- | ----------- | ---- | ---------- |
-| `config get` | 读取个人默认值与管理员已发布的全局模型（不含供应商密钥） | 仅全局 flag | `ai-short-studio config get --json` | 3 / 7 |
-| `config set` | 写入个人默认模型与能力默认值 | `--file`（JSON，省略时读 stdin）、`--verify`（boolean，默认 `false`；set 后再 GET 一次并 diff 请求值与服务端实际值） | `ai-short-studio config set --file ./config.json --verify --json` | 3 / 5 / 6 / 7 |
-
-`config set` 拒绝写入 `providers`、`models` 或工作流并发（CLI 与服务端双重校验）。
-
-### config ai-provider（仅管理员）
-
-| 命令 | 用途 | 参数 / flag | 示例 | 失败退出码 |
-| ---- | ---- | ----------- | ---- | ---------- |
-| `config ai-provider list` | 列出所有 AI Provider（apiKey 脱敏） | 仅全局 flag | `ai-short-studio config ai-provider list --json` | 3 / 5 / 7 |
-| `config ai-provider get` | 查看单个 Provider 详情 | 位置参数 `providerId`（**必填**） | `ai-short-studio config ai-provider get comfyui --json` | 3 / 4 / 5 |
-| `config ai-provider set` | 配置 Provider 的 baseUrl / apiKey / 协议 / enabled 等 | 位置参数 `providerId`（**必填**）、`--base-url`、`--api-key`、`--api-mode`、`--name`、`--protocol`、`--enabled`（`allowNo`，即 `--no-enabled`）、`--sort-order`、`--file`（完整 JSON body，省略时读 stdin）、`--create`（默认 `false`；默认 PATCH 404 时自动回退 create） | `ai-short-studio config ai-provider set comfyui --base-url http://127.0.0.1:8188 --enabled true --json` | 3 / 4 / 5 / 6 / 7 |
-| `config ai-provider test` | 触发服务端连通性探测（`GET /models` 或 `/system_stats`） | 位置参数 `providerId`（**必填**） | `ai-short-studio config ai-provider test comfyui --json` | 3 / 4 / 5 / 7 |
-| `config ai-provider models` | 拉取 Provider 远端真实模型清单 | 位置参数 `providerId`（**必填**） | `ai-short-studio config ai-provider models comfyui --json` | 3 / 4 / 5 / 7 |
-| `config ai-provider capabilities` | 聚合视图：当前能跑哪些模型、缺什么配置 | `--no-reachability`（默认 `false`，跳过连通性探测）、`--reachability-concurrency`（默认 `4`） | `ai-short-studio config ai-provider capabilities --json` | 3 / 5 / 7 |
-
-`--file` 模式要求 JSON body 含 `type` + `name`，此时 CLI 不再叠加任何 flag。`models` 只在 provider `enabled` 且最近一次 `test` 成功时返回目录。
-
-### skill
-
-| 命令 | 用途 | 参数 / flag | 示例 | 失败退出码 |
-| ---- | ---- | ----------- | ---- | ---------- |
-| `skill install`（实现与 `skill update` 相同） | 安装/更新内置 Agent Skill | `--target`（默认 `codex`，可选 `codex` / `agents`）、`--skill`（默认 `all`，可选 `all` / `using-vvicat-ai-short-studio-cli`；旧名称仅作弃用别名）、`--root`（主 Skill 根目录）、`--directory`（兼容旧版，主 Skill 精确目录；与 `--root` 互斥）、`--force`（覆盖非托管或已修改的 Skill） | `ai-short-studio skill update --target codex --json` | 7 |
-| `skill status` | 查看已安装 Skill 版本与修改状态 | 同上（无 `--force`） | `ai-short-studio skill status --target codex --json` | 7 |
-| `skill path` | 打印内置 Skill 打包路径与目标安装路径 | 同上（无 `--force`） | `ai-short-studio skill path --target agents --json` | 7 |
-
-`--target agents` 安装到 `~/.agents/skills`，`--target codex`（默认）安装到 `~/.codex/skills`。`--root` 对应 env `VVICAT_SKILLS_ROOT`；旧 env `VVICAT_SKILL_DIRECTORY` 保持主 Skill 精确目录语义。`VVICAT_SKIP_SKILL_INSTALL=1` 关闭 `postinstall` 自动安装。
-
-### 未覆盖细节的说明
-
-上表覆盖 `src/commands/**` 下全部 61 个命令入口（含 `select-version`/`select`、`edge add`/`connect`、`edge delete`/`disconnect`、`skill install`/`update` 等实现别名）。个别后端业务错误码（如 `MODEL_PRICING_NOT_CONFIGURED`、目录类 `FOLDER_*` 细分码）的完整枚举以 `ai-short-studio <命令> --help` 与 `packages/ai_short_studio_cli/api-surface.json` 的 `notes` 字段为准，本表不臆造未在源码中出现的取值。
-
 ## 项目配置
 
 ```bash
@@ -313,22 +103,22 @@ ai-short-studio canvas inspect --project "$PROJECT_ID" --include summary --inclu
 ai-short-studio canvas inspect --project "$PROJECT_ID" --kind storyboard-image --status stale --operation image-resource --json
 ai-short-studio canvas node update <nodeId> --project "$PROJECT_ID" --set 'gridSize=9' --unset legacyField --json
 ai-short-studio canvas node update-many --project "$PROJECT_ID" --file updates.json --json
+ai-short-studio canvas asset upload ./reference.wav --project "$PROJECT_ID" --json
+ai-short-studio canvas node add audio --project "$PROJECT_ID" --asset-id <assetId> --json
+# --asset-id 只允许 image、video、audio 节点，其他节点会在写入前拒绝
+ai-short-studio canvas node add recreation-shot-extract --project "$PROJECT_ID" --config ./shot.json --json
 ai-short-studio canvas node run --project "$PROJECT_ID" --node <node1> --node <node2> --concurrency 4 --wait --json
 ai-short-studio task wait --task <task1> --task <task2> --concurrency 4 --json
 ```
 
 `canvas node update` 的 `--set key=<JSON>`、`--unset key`、`--title`、`--x` 和 `--y` 只修改指定字段；旧 `--config` 仍兼容。`update-many` 在一次画布版本校验中原子更新多个节点。结构化生成资源仍必须使用 `edit-resource` 或 `edit-shot`，不能通过字段更新改写 artifact。批量执行与等待默认并发为 4、上限为 16；Agent 应优先单进程批处理，避免为每个节点启动一个 CLI 进程。
 
-节点执行若返回 `MODEL_PRICING_NOT_CONFIGURED`，表示所选模型能力参数没有匹配的已发布价格档位；应修正模型参数或由管理员发布价格，不能直接重复提交。
-
 使用 `canvas node edit-shot <nodeId> --project <projectId> --file shot.json` 编辑镜头。命令会追加并选中不可变的人工 DOCUMENT 版本，不允许修改 `shotKey`、`shotIndex` 或来源身份，旧版本继续可选。
 
 使用 `canvas node edit-resource <nodeId> --project <projectId> --file resource.json` 编辑剧本、人物、人物视觉、场景、子场景或道具结构化资源。命令只替换完整父文档中的目标实体，追加并选中人工版本；名称、资源键、ID 和所属关系不可修改，兄弟资源节点保持原选版。资源版本写入不属于 `canvas apply` 图补丁，409 后需重新读取画布与当前选版。
 
 CLI 通过 `/api/v1/bootstrap` 完成版本、连通性与 Supabase 公共配置预检，并直接使用现有 `/api/projects`、`/api/canvas/node-types`、项目画布与资产路由。
 
-> 2026-09-05：资产管理 SSOT Phase 1.1 — 删除 5 个已迁移的 `/api/asset-hub/*` 路由（`generate-image` / `modify-image` / `select-image` / `undo-image` / `update-asset-label`），并移除 5 个多方法路由的 GET handler。CLI 不直接调用这些端点，因此不影响 CLI 行为。详见 `docs/asset-management-api-matrix.md`（Phase 1.1 段）。
-
 `canvas node types [kind] --json` 同时兼容节点目录 schema v1/v2，并原样返回动态节点的 `source`、`definitionId` 和 `definitionVersionId`。后台发布后重新执行该命令即可读取新目录；归档节点不能新建，但已有实例仍按画布中的固定版本 schema 更新和执行。CLI 创建节点只提交 `kind` 与配置，版本由服务端固定，不能由客户端伪造。
 
 新建视频生成节点按实时模型能力执行：首尾帧模型使用 `start-frame` + `end-frame`，普通图生视频使用 `start-frame`，图片参考使用 `references`。Ark 两个 Seedance 2.0 和 StarRouter 两个内置 Dreamina Seedance 2.0 可使用 `reference-videos` 和 `reference-audios`，上限为 9 张参考图、3 个参考视频和 3 个参考音频；部署方启用的内部 RunningHub MiniMax H3 模型支持纯文本零媒体输入，参考图、参考视频和独立参考音频范围分别为 0–9、0–2 和 0–2。RunningHub 参考视频只传画面，需要声音时须单独连接参考音频。它的实时 `durationOptions` 为 5–15 秒的每个整数，服务端把 1–4 秒兼容输入归一为 5 秒。其他 StarRouter 和自定义模型不会按名称猜能力。参考音频不能作为唯一媒体输入；纯文本指不连接任何媒体，不是只连参考音频。多模态参考不能与首尾帧混用。历史节点未声明新版输入语义时继续按原多图参考逻辑执行，不会被读取或保存自动迁移。
@@ -339,7 +129,7 @@ CLI 通过 `/api/v1/bootstrap` 完成版本、连通性与 Supabase 公共配置
 
 `storyboard-breakdown` 还可按实时 schema 写入 `targetDurationSeconds`、`pacingPreset` 和 `maxShotCount`。它们是镜头规划预算，超出只提示而不阻塞源文完整覆盖；留空时不限制镜头数，也不启用时长硬门禁。生成链采用滚动异步调度：单镜分镜图完成后立即进入视频提示词，提示词通过审计后立即提交该镜视频，可恢复失败不阻塞其他镜头。内置 Skill 同时补全字幕、人物/场景首次介绍角标、有动机的镜头衔接、声音平衡和成片验收流程。
 
-标准短剧制作按主 Skill 的编剧参考生成和复核专业剧本，再按文风参考审计模板化台词、虚浮修辞与机械节奏，随后重跑画布剧本审校（已有专业剧本直接复用）。Humanizer 只润色表达，不改剧情事实、人物关系、专有名词、数字、时间线、世界观规则、场次结构或拍摄标记。剧本确认后再选择目标集数、创建或复用项目，并只建立目标集实际出现的人物、场景、道具和可选音色设定。拆镜前必须完成资产—剧情匹配审计；拆镜后逐镜全量检查重复、无效、缺失、冲突、穿帮、连续性、道具交互朝向、语言和来源身份。P0/P1 未清零时不得进入图片、声音或视频生产。
+标准短剧制作读取主 Skill `references/short-drama/` 与 `references/humanizer/`：先生成和复核专业剧本，再审计模板化台词、虚浮修辞与机械节奏，最后检查剧情连贯性。hypit 视频制作流程读取 `references/hypit/`。Humanizer 只润色表达，不改剧情事实、人物关系、专有名词、数字、时间线、世界观规则、场次结构或拍摄标记。剧本确认后再选择目标集数、创建或复用项目，并只建立目标集实际出现的人物、场景、道具和可选音色设定。拆镜前必须完成资产—剧情匹配审计；拆镜后逐镜全量检查重复、无效、缺失、冲突、穿帮、连续性、道具交互朝向、语言和来源身份。P0/P1 未清零时不得进入图片、声音或视频生产。
 
 `character-visual-design` schema 暴露 `candidateCount`，范围为 1～3，默认值为 1。CLI 按实时 schema 校验和写入；多个视觉描述仍分别进入独立三视图和图片资产链。
 
@@ -372,22 +162,6 @@ npm run test:local-e2e
 
 该命令先构建真实 CLI，再启动隔离的本地 mock API，通过多个 `bin/run.js` 子进程验证聚合查询、字段级与多节点更新、`canvas apply` 免预读、批量执行/等待和旧位置参数兼容；同时启动 8 个独立认证进程，确认共享 session 缓存只触发一次模拟 Keychain 读取和一次刷新。测试不连接生产服务、不调用模型，所有配置、令牌、画布和任务数据均在系统临时目录中创建并在结束时清理。
 
-### 真环境只读冒烟（T3 · Phase 1.7 SC4 / D-14）
-
-发布链 `release:ci` / `release:ci:test` 在 `publish --verify` 之后追加 `node scripts/smoke-remote.mjs`，对远端 dev 环境跑认证态全链路四条只读命令：
-
-```bash
-# 凭据就绪时（CI secret / 本地 export）：
-export VVICAT_BASE_URL="https://dev.example.com"      # 远端 dev 13002 公网入口
-export VVICAT_ACCESS_TOKEN="<专用测试账号长期令牌>"     # CI 加密变量名沿用此约定
-node scripts/smoke-remote.mjs                          # 真实冒烟
-
-# 无凭据 / CI 结构自检：
-node scripts/smoke-remote.mjs --dry-run                # 打印命令清单 + 白名单断言
-```
-
-只读约束：`scripts/smoke-remote.mjs` 命令白名单硬编码为 `preflight --json` / `project list --json` / `canvas node types --json` / `config get --json`，任何写命令（`upload` / `run` / `update`）一律禁入；即使专用测试账号也不放宽（远端是共享 dev 环境，写命令会产生真实数据与费用）。凭据纪律：`token` 只从环境变量读，不入参数/不入 Git/不入日志；脚本输出过滤 token 后再回放到 stdout/stderr。
-
 标准创作中，用户未指定时角色、道具、场景/背景和分镜图统一使用 `16:9`。视频时长以当前模型实时 `durationOptions` 为准；只有实时模型仅提供 5、10、15 秒时，才按镜头目标时长向上取这三档为剪辑保留余量，其他模型不硬编码三档。每批生成后 Agent 必须重新读取任务与资产、核对最终时长在实时合法选项中，并实际检查预览，完成自我审计后才能继续或交付。
 
 ```bash
@@ -397,7 +171,7 @@ ai-short-studio skill update --target codex
 ai-short-studio skill update --target codex --json
 ```
 
-手动恢复或安装到其他 Agent 时，可使用 `--target agents`；自定义主 Skill 的父目录使用 `--root <path>`。旧版 `--directory <path>` 保留为兼容入口，只把主 CLI Skill 精确安装到该目录。自动安装对应使用 `VVICAT_SKILLS_ROOT`；旧变量 `VVICAT_SKILL_DIRECTORY` 仍保持主 Skill 精确目录语义。CLI 会记录版本和 SHA-256；已安装 Skill 被用户修改后，更新默认停止，只有显式 `--force` 才覆盖。自动安装可通过 `VVICAT_SKIP_SKILL_INSTALL=1` 跳过。
+手动恢复或安装到其他 Agent 时，可使用 `--target agents`；自定义全部内置 Skills 的父目录使用 `--root <path>`。旧版 `--directory <path>` 保留为兼容入口，只把主 CLI Skill 精确安装到该目录。自动安装对应使用 `VVICAT_SKILLS_ROOT`；旧变量 `VVICAT_SKILL_DIRECTORY` 仍保持主 Skill 精确目录语义。CLI 会记录版本和 SHA-256；已安装 Skill 被用户修改后，更新默认停止，只有显式 `--force` 才覆盖。自动安装可通过 `VVICAT_SKIP_SKILL_INSTALL=1` 跳过。
 
 ## 发布
 
@@ -438,75 +212,3 @@ npm run release:ci:test -- --version 0.1.1-beta.0
 ```
 
 `release:ci` 会依次运行测试和类型检查、发布 npm、等待 registry 可见，再从 npm 安装该精确版本并验证 CLI 与配套 Skill。无需配置自有 Runner；只有访问内网或需要固定出口 IP 时才使用自有构建集群。
-
-
-
-## 包身份与升级协议
-
-CLI 与服务端 `/api/v1/bootstrap` 必须就包身份（`name` + `latestVersion`）达成一致，否则 `preflight` 会抛"服务端返回的 CLI 包名与当前安装包不一致"并阻塞所有 CLI 命令。
-
-- 仓库内 `package.json` 的 `name` 字段硬绑定为 `@aswless_854771076/ai_short_studio_cli`，pre-commit guard `npm run check:cli-package-identity` 强制。
-- 升级发布流程见 `.github/workflows/cli-publish.yml`（push main 自动 `npm run release -- --verify`）。
-- 手动 release SOP 见本仓库 `.agents/skills/vvicat-cli-adapter/references/cli-release-sop.md`。
-- 服务端 `/api/v1/bootstrap` 现暴露 `data.cliDrift` 字段，drift 时返回 `reason` + `manifest` + `npm` 三组对照信息；Agent 进入新环境跑 `config ai-provider capabilities --json` 即可看到。
-
-### 最低兼容版本（minCliVersion · Phase 1.7 SC3 / D-12/D-13）
-
-服务端 `/api/v1/bootstrap` 在 `data.cli.minCliVersion` 下发最低兼容 CLI 版本（Phase 1.7 SC3）；当前版本低于该值时 `preflight` **强制升级**，且 `--no-update` 不可跳过。
-
-- 声明载体优先级：env `VVICAT_CLI_MIN_VERSION`（紧急回滚通道）> 仓库 `packages/ai_short_studio_cli/cli-min-version.json`（PR 可审查 + 历史可追溯）> 未声明（additive 缺省）。
-- bump 时机与 merge gate 联动（D-13）：breaking PR 必须同步 bump；声明 `CLI-Impact: verified-none` 的 PR 无需 bump；`CLI-Impact: deferred` 补适配时随适配 PR bump。
-- 非法 SemVer（env 或文件值都不匹配 `x.y.z`）→ 中文告警后按未声明降级，不静默吞掉，确保运维能从日志发现兜底失效。
-
-## 维护流程
-
-本节描述维护 CLI ↔ 后端契约时必须走的流程与门禁，适用于包维护者与 Agent。
-
-### 1. 契约方向约定（2026-09-29 定）
-
-- **`public/api-docs/openapi.json`（OpenAPI spec）是后端契约的唯一事实源。** 它描述后端实际暴露的路由、方法、请求/响应结构。
-- **`packages/ai_short_studio_cli/api-surface.json` 是 CLI 侧的调用声明**，登记 CLI 实际会打的端点（当前 45 条，见下文"消费面清单"）。
-- 方向是 **CLI 向 spec 适配**，不是让后端迁就 CLI 的手写清单。`api-surface.json` 不是新的契约来源，它必须随时反映 CLI 源码真实调用点，并与 spec 覆盖关系保持一致（`--require-spec` 校验 spec 覆盖 ⊇ 清单路径集合）。**不得**为了保清单而要求后端保留已废弃路由。
-
-### 2. 后端接口变更 → CLI 适配的 checklist
-
-- [ ] **1. 后端改路由/字段 → 先同步更新 `public/api-docs/openapi.json`。** spec 是唯一事实源，spec 未更新等于契约未定义。
-- [ ] **2. CLI 侧调用点变化 → 同步更新 `packages/ai_short_studio_cli/api-surface.json`。** 新增/改名/删除调用端点时，编辑对应条目的 `path` / `httpMethod` / `cliCaller` / `backendFile`（必要时补 `notes`）。CLI 新增一个 API 调用 = 必须新增或修改一条清单条目；**清单失真会让所有下游门禁失真**。
-- [ ] **3. 本地跑门禁**（两条都要过）：
-    ```bash
-    node scripts/guards/cli-api-surface-guard.mjs --json          # CLI 源码调用点 ↔ 清单条目双向对账
-    node scripts/guards/cli-api-surface-guard.mjs --require-spec   # 追加 spec 覆盖 ⊇ 清单路径集合校验
-    ```
-      正常输出应显示 `ok: true`、`specCheck.ok: true`、无 `errors`、无 `missing`；对账条数应等于调用点数（当前为 45）。
-- [ ] **4. 破坏性变更需追加 commit trailer 豁免。** 后端变更若触及 CLI 消费面而 CLI 本次未适配，merge gate（`scripts/guards/cli-contract-gate.mjs`）会拦截，需在 commit message 末尾追加：
-      - `CLI-Impact: verified-none` —— 声明本次变更不影响 CLI 契约语义，无需 bump `minCliVersion`；
-      - `CLI-Impact: deferred` —— 声明需后续补适配，CI 自动开跟踪 issue（凭据缺失时降级为 issue 草稿 artifact）；补适配 PR 需同步 bump `minCliVersion`。
-      **枚举值与 `.husky/commit-msg` 和 `cli-contract-gate.mjs` 保持同源，合法值只有 `verified-none` 与 `deferred` 两个**（commit-msg 用 `LEGAL_VALUES="verified-none deferred"` 校验，其他值或多余尾随内容 abort）。豁免是可选项：提交不含该 trailer 时 hook 一律放行。**用 trailer 走可审计通道，不要用 `--no-verify` 绕过 hook。**
-- [ ] **5. 破坏性变更还要 bump 最低兼容版本。** 编辑 `packages/ai_short_studio_cli/cli-min-version.json` 的 `minCliVersion`（格式 `x.y.z`；`verified-none` 无需 bump，`deferred` 在补适配 PR bump）。服务端 `/api/v1/bootstrap` 在 `data.cli.minCliVersion` 下发该值，低于它的 CLI 会被 `preflight` 强制升级。
-
-### 3. 端点迁移实例：`/api/assets/upload` 收敛（2026-09-29）
-
-这是"后端收敛后 CLI 必须跟上"的真实案例。
-
-- **后端动作**：commit `9a55588c`（asset-core P3 收口，41→16 路由）把 `/api/asset-hub/creative-assets/upload` **合并进** `/api/assets/upload`，并删除旧路由。`/api/assets/upload` 成为资产域 SSOT 的单一上传入口。
-- **CLI 后果**：CLI 的 `canvas asset upload` 当时仍指向旧路径，运行时**必然 404**——但这类"后端已删、CLI 未跟"的漂移不会在编译期暴露，只在真实调用时炸。直到 2026-09-29 才修复。
-- **修复内容**：CLI 改指 `/api/assets/upload`；同时补上 `kind` 参数。后端按 `kind` 分发资产域——`voice` → `GlobalVoice`，`image` / `video` / `audio` → `GlobalCreativeAsset`；`kind=voice` **仅接受音频**（CLI 本地先拦截，避免发必然 400 的请求）。清单中 `assets-upload` 条目的 `notes` 已记录本次迁移与契约要点。
-- **教训**：后端合并/删除端点时，必须同步 grep CLI 是否有调用点（本例通过 `cli-api-surface-guard` 对账发现并修复）。**只要 api-surface 中登记的路径被后端删改，就必须走上面的完整 checklist 重新对账。**
-
-### 4. 新增/废弃 CLI 命令的登记义务
-
-- **新增一个会打后端 API 的 CLI 命令** → 必须在 `api-surface.json` 增一条登记（`path` / `httpMethod` / `cliCaller` / `backendFile`），否则 `cli-api-surface-guard` 的双向对账会报"清单缺失调用点"。
-- **废弃/下线一个 CLI 命令** → 必须**同步从 `api-surface.json` 移除对应条目**。若命令已下线但清单条目仍在，门禁会因"清单条目陈旧"（源码已无对应调用点）报错。移除清单条目同样要跑 `node scripts/guards/cli-api-surface-guard.mjs --json` 确认对账通过。
-- 纯本地命令（如 `skill *`、`preflight` 之外的若干不涉及 API 的辅助命令）不进清单；`preflight` 的 `/api/v1/bootstrap` 与 `/api/auth/session` 已单独登记。
-
-### 消费面清单（`api-surface.json`）
-
-`api-surface.json` 当前登记 45 条 CLI 消费端点，字段含义：
-
-- `id` —— 稳定条目 ID；
-- `path` —— 端点路径（动态段用 `{param}` 占位，查询串已剥离）；
-- `httpMethod` —— HTTP 方法；
-- `cliCaller` —— CLI 侧调用点（API 方法名或命令）；
-- `backendFile` —— 后端实现文件；
-- `deadEndpoint` —— 标记后端已删、运行时必 404 的死端点（spec/T1/冒烟排除；当前为 0 条）；
-- `notes` —— 契约要点与迁移备注。

package/dist/base-command.d.ts

@@ -6,13 +6,7 @@ export declare abstract class BaseCommand extends Command {
         locale: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         episode: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
-        output: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
-    /**
-     * 输出 JSON。指定了 --output / CLI_OUTPUT_FILE 时改由 Node 以 utf-8 写文件，
-     * 不经过终端句柄 —— 这是 Windows 非 UTF-8 代码页下唯一可靠的应用层通道
-     * （见 P0-4）。未指定时保持原有 stdout 行为。
-     */
     protected print(value: unknown): void;
     catch(error: unknown): Promise<void>;
 }

package/dist/base-command.js

@@ -1,7 +1,6 @@
-import { writeFileSync } from 'node:fs';
 import { Command, Flags } from '@oclif/core';
 import { CliApiError } from './client/errors.js';
-import { formatJson, resolveOutputFile } from './output/formatter.js';
+import { formatJson } from './output/formatter.js';
 export class BaseCommand extends Command {
     static baseFlags = {
         'base-url': Flags.string({ description: 'VVICAT 服务地址', env: 'VVICAT_BASE_URL' }),
@@ -9,30 +8,8 @@ export class BaseCommand extends Command {
         locale: Flags.string({ description: '响应语言', default: 'zh', options: ['zh', 'en'] }),
         profile: Flags.string({ description: '配置档案名称' }),
         episode: Flags.string({ description: '画布分集 ID 或集数', env: 'VVICAT_CANVAS_EPISODE' }),
-        output: Flags.string({
-            description: '把 JSON 输出以 UTF-8 写入指定文件（绕开终端代码页）。也可用环境变量 CLI_OUTPUT_FILE 设置。',
-        }),
     };
-    /**
-     * 输出 JSON。指定了 --output / CLI_OUTPUT_FILE 时改由 Node 以 utf-8 写文件，
-     * 不经过终端句柄 —— 这是 Windows 非 UTF-8 代码页下唯一可靠的应用层通道
-     * （见 P0-4）。未指定时保持原有 stdout 行为。
-     */
     print(value) {
-        // oclif 把 this.parsed 定义为 boolean，不保留 flags；--output 只能从 argv 原样读取。
-        // 两种写法都支持：--output <file> 与 --output=<file>。
-        const flagValue = readOutputFlag(this.argv);
-        const file = resolveOutputFile(flagValue);
-        if (file) {
-            try {
-                writeFileSync(file, formatJson(value), { encoding: 'utf8' });
-            }
-            catch (error) {
-                throw new Error(`写入 --output 文件失败（${file}）：${error instanceof Error ? error.message : String(error)}`);
-            }
-            this.logToStderr(`JSON 输出已写入 ${file}`);
-            return;
-        }
         this.log(formatJson(value));
     }
     async catch(error) {
@@ -50,21 +27,6 @@ export class BaseCommand extends Command {
         this.error(error instanceof Error ? error.message : String(error), { exit: 7 });
     }
 }
-/** 从原始 argv 中取 --output 的值；不支持 --output 后跟 -- 时按 oclif 规则视为缺值。 */
-function readOutputFlag(argv) {
-    if (!argv)
-        return undefined;
-    for (let index = 0; index < argv.length; index += 1) {
-        const token = argv[index];
-        if (token === '--output') {
-            const next = argv[index + 1];
-            return next && !next.startsWith('-') ? next : undefined;
-        }
-        if (token.startsWith('--output='))
-            return token.slice('--output='.length) || undefined;
-    }
-    return undefined;
-}
 function exitCode(status) {
     if (status === 401)
         return 3;

package/dist/client/api-client.js

@@ -18,21 +18,8 @@ export class ApiClient {
         if (response.status === 401 && options.auth !== false) {
             response = await this.send(path, options, await this.session.refreshAccessToken());
         }
-        if (!response.ok) {
-            // root cause: undici fetch close + @napi-rs/keyring handle race;
-            // setImmediate alone not enough, need real delay.
-            //
-            // 抛出前必须给 undici 真实时间完成内部 cleanup：在 Node 21+ / Windows 上，
-            // setImmediate 只 flush 微任务队列，但 undici 内部的 socket close 是异步且
-            // 至少需要几十毫秒完成。若 await response.json() / apiError(response) 解析
-            // body 时 undici 已经发出 close 信号，但底层 libuv handle（被
-            // @napi-rs/keyring 持有）尚未 close，就会触发
-            // `UV_HANDLE_CLOSING assertion failed`（src\win\async.c:76），进程异常
-            // 退出 3221226505。先 sleep 50ms 让 undici 内部 cleanup 完成，再读 body
-            // / throw 才是安全的。详见 preflight.ts 的同源注释。
-            await new Promise((resolve) => setTimeout(resolve, 50));
+        if (!response.ok)
             throw await apiError(response);
-        }
         if (response.status === 204)
             return undefined;
         return await response.json();
@@ -43,12 +30,8 @@ export class ApiClient {
         if (response.status === 401 && options.auth !== false) {
             response = await this.send(path, options, await this.session.refreshAccessToken());
         }
-        if (!response.ok) {
-            // 同 request：throw 前需要真实 delay 让 undici 收尾，否则同样触发
-            // UV_HANDLE_CLOSING。response() 路径同样需要 sleep 50ms。
-            await new Promise((resolve) => setTimeout(resolve, 50));
+        if (!response.ok)
             throw await apiError(response);
-        }
         return response;
     }
     async send(path, options, accessToken) {

package/dist/commands/auth/login.d.ts

@@ -4,7 +4,7 @@ export default class AuthLogin extends BaseCommand {
     static flags: {
         email: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         google: import("@oclif/core/interfaces").BooleanFlag<boolean>;
-        provider: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        provider: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         'password-stdin': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'supabase-publishable-key': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'supabase-url': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
@@ -13,7 +13,6 @@ export default class AuthLogin extends BaseCommand {
         locale: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         episode: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
-        output: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
 }

package/dist/commands/auth/login.js

@@ -1,10 +1,8 @@
 import { Flags } from '@oclif/core';
 import { BaseCommand } from '../../base-command.js';
 import { createRuntime } from '../../runtime.js';
-import { ProfileStore } from '../../config/profiles.js';
 import { promptLine, promptPassword, readStdinText } from '../../terminal/prompt.js';
 import { loginWithMemHubPkce } from '../../auth/memhub-oauth.js';
-import { resolveLoginProvider } from '../../auth/login-provider.js';
 export default class AuthLogin extends BaseCommand {
     static description = '通过 Supabase 或 MemHub 登录，并将长期凭据保存到系统钥匙串';
     static flags = {
@@ -14,6 +12,7 @@ export default class AuthLogin extends BaseCommand {
         provider: Flags.string({
             description: '登录提供方',
             options: ['supabase', 'memhub'],
+            default: 'supabase',
         }),
         'password-stdin': Flags.boolean({ description: '从标准输入读取密码', default: false }),
         'supabase-publishable-key': Flags.string({ description: 'Supabase publishable key', env: 'VVICAT_SUPABASE_PUBLISHABLE_KEY' }),
@@ -21,9 +20,7 @@ export default class AuthLogin extends BaseCommand {
     };
     async run() {
         const { flags } = await this.parse(AuthLogin);
-        const profiles = new ProfileStore();
-        const selected = flags.profile ? await profiles.get(flags.profile) : await profiles.current();
-        const authProvider = resolveLoginProvider(flags.provider, selected);
+        const authProvider = flags.provider;
         if (authProvider === 'memhub' && (flags.google || flags.email || flags['password-stdin'])) {
             throw new Error('MemHub 登录使用浏览器授权，不能同时传入邮箱、Google 或密码参数');
         }

package/dist/commands/auth/logout.d.ts

@@ -7,7 +7,6 @@ export default class AuthLogout extends BaseCommand {
         locale: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         episode: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
-        output: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
 }