Feat/opt

README.md

@@ -14,11 +14,16 @@
 
 ## ✨ What it can do
 
-| Capability                                                                                                                          | Runs on            | Status         |
-| ----------------------------------------------------------------------------------------------------------------------------------- | ------------------ | -------------- |
-| **AI** — video enhancement · subtitle removal                                                                                       | cloud              | ✅ Available   |
-| **Editing** (11) — trim · concat · watermark · subtitle · speed · flip · extract / mux audio · image-to-video                       | cloud **or** local | ✅ Available   |
-| **More AI workflows** — video understanding · translation · highlight clipping · script extraction · commentary · anime restyling … | cloud              | 🚧 Rolling out |
+**40+ capabilities across 5 domains** — run `mediakit-cli --help-full` to list them all.
+
+| Domain               | Capabilities                                                                                                                                                                                                     | Runs on            | Status       |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ------------ |
+| 🎬 **Editing** (17)  | trim · concat · watermark · subtitle · speed · volume · filter · flip · fade · mix · mux · extract audio · image-to-video                                                                                        | cloud **or** local | ✅ Available |
+| 🎚️ **Audio** (2)     | voice / background separation · audio metadata probe                                                                                                                                                             | cloud              | ✅ Available |
+| 🖼️ **Image AI** (5)  | enhance · object / text erase · quality scoring · OCR · background removal                                                                                                                                       | cloud              | ✅ Available |
+| 🎥 **Video AI** (14) | enhancement (+ generative restore) · subtitle removal · ASR subtitles · OCR · highlight clipping (short-drama / mini-game) · storyline analysis · scene split · portrait & green-screen matting · metadata probe | cloud              | ✅ Available |
+| 🔧 **Shared** (2)    | async task query · remote-file fetch                                                                                                                                                                             | local / cloud      | ✅ Available |
+| 🚧 **Coming**        | video translation · commentary generation · anime restyling                                                                                                                                                      | cloud              | Rolling out  |
 
 > AI capabilities run in the cloud (elastic compute, async). Editing runs **either** in the cloud **or** locally (sync, zero cost) — pick per command with `--cloud` / `--local`.
 
@@ -44,7 +49,10 @@ mediakit-cli --local editing trim-video --video-url ./in.mp4 --start-time 3 --en
 ## 📦 Install
 
 ```bash
-# npm (recommended, cross-platform — pulls the right build for your OS / arch)
+# One-click install (CLI + AI agent Skills)
+npx @volcengine/mediakit-cli install -y
+
+# npm only (CLI, recommended, cross-platform — pulls the right build for your OS / arch)
 npm install -g @volcengine/mediakit-cli
 
 # npx (no install)
@@ -58,6 +66,18 @@ Pin a version or path: `VERSION=<version> INSTALL_DIR="$HOME/.local/bin" curl -f
 
 Verify: `mediakit-cli doctor` (checks cloud readiness + local tool deps + install hints).
 
+### Update
+
+The CLI checks the npm registry for new releases once a day (TTL 24h). When an update is available you'll see a hint in `stderr` and a `_notice.update` field in the stdout JSON.
+
+```bash
+mediakit-cli version --check       # report current vs latest as JSON
+mediakit-cli update --check        # check only, no install
+mediakit-cli update                # install the latest via `npm install -g`
+```
+
+Suppress the check with `MEDIAKIT_DISABLE_UPDATE_CHECK=1` or in CI (`CI` env set).
+
 ---
 
 ## 🤖 Use with AI Agents
@@ -78,7 +98,7 @@ Every capability is also **MCP-compatible** — `mediakit-cli <domain> <tool> --
 ## 🧩 How it works
 
 - **Two modes, one command surface.** `--cloud` runs heavy AI in Volcengine's cloud (elastic compute, async `task_id`); `--local` runs deterministic editing locally (sync, zero cloud cost). Default mode is `cloud-first`; per-command flags override it.
-- **Command structure:** `mediakit-cli [--cloud|--local] <domain> <tool> [flags]` — domains are `editing` · `video` · `shared`.
+- **Command structure:** `mediakit-cli [--cloud|--local] <domain> <tool> [flags]` — domains are `editing` · `audio` · `image` · `video` · `shared`.
 - **Outputs:** cloud results are returned as URLs; local results write to `~/.mediakit/temp` (override with `--output-path` or `MEDIAKIT_OUTPUT_PATH`).
 
 ---
@@ -87,6 +107,7 @@ Every capability is also **MCP-compatible** — `mediakit-cli <domain> <tool> --
 
 - Volcengine AI MediaKit product docs & pricing: https://www.volcengine.com/docs/6448
 - Full command reference & FAQ: see the docs site.
+- [Error codes & exit code contract](./docs/error-codes.md) — stdout JSON protocol and exit-code rules.
 
 ---
 

README.zh.md

@@ -14,11 +14,16 @@
 
 ## ✨ 能做什么
 
-| 能力                                                                                              | 运行             | 状态        |
-| ------------------------------------------------------------------------------------------------- | ---------------- | ----------- |
-| **AI 能力** — 画质增强 · 字幕擦除                                                                 | 云端             | ✅ 已上线   |
-| **剪辑能力**（11 个）— 裁剪 · 拼接 · 加水印 · 加字幕 · 调速 · 翻转 · 提取 / 合成音频 · 图片转视频 | 云端 **或** 本地 | ✅ 已上线   |
-| **更多 AI 工作流** — 视频理解 · 视频翻译 · 高光智剪 · 剧本还原 · 解说 · 漫剧转绘 …                | 云端             | 🚧 陆续上线 |
+**5 大领域、40+ 能力** —— 运行 `mediakit-cli --help-full` 可列全。
+
+| 领域 | 能力 | 运行 | 状态 |
+| --- | --- | --- | --- |
+| 🎬 **剪辑** (17) | 裁剪 · 拼接 · 加水印 · 加字幕 · 调速 · 调音量 · 滤镜 · 翻转 · 淡入淡出 · 混音 · 合成 · 提取音频 · 图片转视频 | 云端 **或** 本地 | ✅ 已上线 |
+| 🎚️ **音频** (2) | 人声 / 背景音分离 · 音频元信息探测 | 云端 | ✅ 已上线 |
+| 🖼️ **图像 AI** (5) | 画质增强 · 擦除修复 · 画质评分 · OCR · 背景移除 | 云端 | ✅ 已上线 |
+| 🎥 **视频 AI** (14) | 画质增强（含生成式修复）· 字幕擦除 · ASR 字幕 · OCR · 高光智剪（短剧 / 小游戏）· 剧情线分析 · 场景切分 · 人像 & 绿幕抠图 · 元信息探测 | 云端 | ✅ 已上线 |
+| 🔧 **通用** (2) | 异步任务查询 · 远程文件拉取 | 本地 / 云端 | ✅ 已上线 |
+| 🚧 **即将上线** | 视频翻译 · 解说生成 · 漫剧转绘 | 云端 | 陆续上线 |
 
 > AI 能力跑在云端（弹性算力、异步）；剪辑能力**云端或本地**皆可（本地跑，同步、零成本）—— 每条命令用 `--cloud` / `--local` 选。
 
@@ -44,7 +49,10 @@ mediakit-cli --local editing trim-video --video-url ./in.mp4 --start-time 3 --en
 ## 📦 安装
 
 ```bash
-# npm（推荐，跨平台——自动拉取对应平台 / 架构的构建产物）
+# 一键安装（CLI + AI Agent Skill）
+npx @volcengine/mediakit-cli install -y
+
+# 仅装 CLI（推荐，跨平台——自动拉取对应平台 / 架构的构建产物）
 npm install -g @volcengine/mediakit-cli
 
 # npx（免安装）
@@ -58,11 +66,23 @@ curl -fsSL https://raw.githubusercontent.com/volcengine/mediakit-cli/main/script
 
 验证环境：`mediakit-cli doctor`（检查云端就绪 + 本地工具依赖 + 安装指引）。
 
+### 更新
+
+CLI 每天会向 npm registry 检查一次新版本（TTL 24h）。有更新时，`stderr` 会出现提示，stdout JSON 会带上 `_notice.update` 字段。
+
+```bash
+mediakit-cli version --check       # 以 JSON 输出当前版本 vs 最新版本
+mediakit-cli update --check        # 只检查，不安装
+mediakit-cli update                # 通过 `npm install -g` 安装最新版
+```
+
+如需关闭自动检查，设置 `MEDIAKIT_DISABLE_UPDATE_CHECK=1`，或在 CI 中运行（`CI` 环境变量被设置时也会自动抑制）。
+
 ---
 
 ## 🤖 配合 AI Agent 使用
 
-`mediakit-cli` 自带 **AI Agent Skill**——教 Agent 怎么调它。于是用户只需说一句*“把这个视频增强到 1080p，再剪出最精彩的 5 秒”*，Agent 就能自动编排命令。
+`mediakit-cli` 自带 **AI Agent Skill**——教 Agent 怎么调它。于是用户只需说一句*"把这个视频增强到 1080p，再剪出最精彩的 5 秒"*，Agent 就能自动编排命令。
 
 ```bash
 # 一个命令把 Skill 装进本机所有支持的 Agent
@@ -78,7 +98,7 @@ npx skills add volcengine/mediakit-cli -g -y
 ## 🧩 工作原理
 
 - **两种模式，同一套命令。** `--cloud` 把重算力 AI 跑在火山引擎云端（弹性算力、异步 `task_id`）；`--local` 在本机跑确定性剪辑（同步、零云端成本）。默认 `cloud-first`，单命令 flag 可覆盖。
-- **命令结构：** `mediakit-cli [--cloud|--local] <domain> <tool> [flags]`——domain 为 `editing` · `video` · `shared`。
+- **命令结构：** `mediakit-cli [--cloud|--local] <domain> <tool> [flags]`——domain 为 `editing` · `audio` · `image` · `video` · `shared`。
 - **输出：** 云端结果以 URL 返回；本地结果写到 `~/.mediakit/temp`（可用 `--output-path` 或 `MEDIAKIT_OUTPUT_PATH` 覆盖）。
 
 ---
@@ -87,6 +107,7 @@ npx skills add volcengine/mediakit-cli -g -y
 
 - Volcengine AI MediaKit 产品文档 & 定价：https://www.volcengine.com/docs/6448
 - 完整命令参考 & FAQ：见文档站。
+- [错误码与退出码契约](./docs/error-codes.md) —— stdout JSON 协议与退出码规则。
 
 ---
 

cmd/mediakit/main.go

@@ -1,15 +1,22 @@
 package main
 
 import (
-    "fmt"
-    "os"
+	"errors"
+	"fmt"
+	"os"
 
-    "mediakit-cli/internal/commands"
+	"mediakit-cli/internal/cliexit"
+	"mediakit-cli/internal/commands"
 )
 
 func main() {
-    if err := commands.Execute(); err != nil {
-        fmt.Fprintln(os.Stderr, err)
-        os.Exit(1)
-    }
+	err := commands.Execute()
+	if err == nil {
+		return
+	}
+	// 业务失败：结构化错误已写入 stdout JSON，stderr 不重复打印
+	if !errors.Is(err, cliexit.ErrBusinessFailure) {
+		fmt.Fprintln(os.Stderr, err)
+	}
+	os.Exit(1)
 }

docs/error-codes.md

@@ -0,0 +1,118 @@
+# mediakit-cli 错误码与退出码契约
+
+本文档描述 `mediakit-cli` 在 cloud / local 两种执行路径下的错误协议、字段含义与进程退出码（exit code）规则，作为 SDK / Skill / Plugin 等上层调用方解析的稳定契约。
+
+## 一、退出码总览
+
+| 退出码 | 含义                            | 触发场景                                                                                                       |
+| ------ | ------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `0`    | 命令成功                        | 所有路径成功完成；同步成功 / 异步提交成功（拿到 task_id）/ query-task 终态为 `completed`                       |
+| `1`    | 业务失败或框架/参数错误         | 任意 stdout JSON 出现 `success: false`（cloud）、`error` 字段（local）、`status: failed/canceled/cancelled`（query-task 终态），或参数解析失败 |
+
+> `mediakit-cli` 不再使用退出码区分"框架错误"和"业务错误"；上层调用方应**优先解析 stdout JSON**，把退出码当作辅助信号。
+
+## 二、cloud 路径（远程 API）
+
+### 2.1 输出落点
+
+- 业务结果与业务错误：stdout（一个 JSON 对象，pretty 缩进）
+- stderr：保留给 update notice、调试日志；**不再写业务错误**
+
+### 2.2 成功响应（同步 / 异步提交）
+
+异步主任务提交成功时（HTTP 2xx + `success=true`），CLI 直接透传：
+
+```json
+{
+  "success": true,
+  "task_id": "task_xxx",
+  "request_id": "req_xxx",
+  "result": { "...": "..." }
+}
+```
+
+退出码：`0`。
+
+### 2.3 业务失败响应
+
+任意以下情形都视为业务失败，CLI 写完 JSON 后退出码 `1`：
+
+| 情形                                              | 判定字段                                                       |
+| ------------------------------------------------- | -------------------------------------------------------------- |
+| 主调用 HTTP 2xx 但 `success=false`                | `success == false`                                             |
+| 主调用 HTTP ≥ 400 网络/服务错误                   | `errorResponse(...)` 统一写 `success: false` + `error: {...}`  |
+| `query-task` 终态为 `failed` / `canceled` / `cancelled` | `status` 字段（注意 queryTaskResponse 没有 `success` 字段） |
+
+业务失败 JSON 结构：
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "InvalidParameter",
+    "message": "video_url is required"
+  },
+  "task_id": "task_xxx",
+  "request_id": "req_xxx"
+}
+```
+
+### 2.4 query-task 终态字段
+
+`mediakit-cli shared query-task` 返回的 `status` 取值：
+
+| status      | 含义                       | 退出码 |
+| ----------- | -------------------------- | ------ |
+| `running`   | 进行中（非终态）           | `0`    |
+| `queued`    | 排队中（非终态）           | `0`    |
+| `completed` | 已完成（终态，成功）       | `0`    |
+| `failed`    | 已失败（终态，业务失败）   | `1`    |
+| `canceled`  | 已取消（终态，业务失败）   | `1`    |
+| `cancelled` | 同 `canceled`（兼容拼写）  | `1`    |
+
+只有 `failed/canceled/cancelled` 三个状态被识别为"业务失败终态"，退出码为 `1`；其他状态退出码 `0`。
+
+## 三、local 路径（本地执行）
+
+### 3.1 输出落点
+
+- 成功结果：stdout（平铺业务字段，与 swagger response schema 对齐，详见 Rule 23）
+- 业务失败：stdout 写 `{"error": {...}}` 结构化错误
+- stderr：保留给 update notice、调试日志
+
+### 3.2 业务失败响应
+
+```json
+{
+  "error": {
+    "type": "invalid_parameter | security_violation | environment_error | execution_error",
+    "code": "missing_required_param | invalid_param_type | param_out_of_range | param_insufficient | unsupported_value | forbidden_operation | not_whitelisted | unsafe_characters | handler_not_implemented | local_unsupported | dependency_missing | execution_failed | download_failed | unknown",
+    "message": "<原始错误信息（不截断、不摘要）>"
+  }
+}
+```
+
+退出码：`1`。
+
+`type` 与 `code` 取值范围见 `AGENTS.md` Rule 25。
+
+## 四、上层调用方解析建议
+
+1. 优先解析 stdout JSON：
+   - cloud：`success === false` 即业务失败；终态 `status` 为 `failed/canceled/cancelled` 也视为失败
+   - local：存在非空 `error` 字段即业务失败
+2. 退出码作为辅助信号：`exit code === 0` 表示无业务失败信号，`exit code === 1` 表示存在业务失败或框架/参数错误
+3. stderr 不再承载业务错误内容；只用来读取 update notice 与调试日志
+
+## 五、Boolean flag 传参
+
+所有 boolean 类型 flag 必须使用以下三种形式之一：
+
+- 裸 flag：`--enable-foo`（等价于 `--enable-foo=true`）
+- 显式赋值：`--enable-foo=true` / `--enable-foo=false`
+
+禁止使用空格分隔写法（`--enable-foo true`）：cobra 会把空格后的 token 视为 positional 参数。`mediakit-cli` 会在该 capability 含 boolean 参数时给出明确提示。
+
+## 六、--schema 输出中的 Async 字段
+
+每个 capability 命令的 `--schema` 输出在 description 中固定包含一行 `Async: 是/否`；异步 capability 额外打印 `轮询命令: mediakit-cli shared query-task --task-id <id> --poll-complete`，供上层 agent 识别"需要轮询拿终态结果"的语义。

go.mod

@@ -2,9 +2,9 @@ module mediakit-cli
 
 go 1.22
 
+require github.com/spf13/cobra v1.10.2
+
 require (
-	github.com/spf13/cobra v1.10.2
-	github.com/spf13/pflag v1.0.9
+	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/spf13/pflag v1.0.9 // indirect
 )
-
-require github.com/inconshreveable/mousetrap v1.1.0 // indirect

internal/cliexit/exit.go

@@ -0,0 +1,27 @@
+// Package cliexit 定义 CLI 业务失败的哨兵错误。
+//
+// "业务失败" 在 CLI 视角下采用宽口径定义：本次命令未达成功状态。
+// 涵盖三档：
+//  1. 业务级失败 — cloud success=false / query-task 失败终态 / local error 字段
+//  2. 框架/参数错误 — capability 参数校验失败、handler 未实现、依赖缺失
+//  3. 透传错误 — 底层 modes/cloud/local 抛出的非 sentinel 错误经 writeCapabilityError 包装
+//
+// 三档统一映射到 exit=1，但结构化错误已经写入 stdout JSON；
+// main.go 通过 errors.Is 识别此哨兵，跳过 stderr 重复打印。
+//
+// 详见 AGENTS.md Rule 32: CLI Exit Code Contract。
+package cliexit
+
+import "errors"
+
+// ErrBusinessFailure 表示 CLI 本次命令未达成功状态。
+//
+// 由以下三个 writer 统一抛出：
+//   - internal/cloud/executor.go::writeJSON（cloud 主路径与 query-task 终态）
+//   - internal/local/executor.go::writeJSON（local 主路径）
+//   - internal/commands/registry.go::writeCapabilityError（参数/依赖/兜底错误）
+//
+// cmd/mediakit/main.go 用 errors.Is 识别后：
+//   - 跳过 stderr 打印（错误结构已在 stdout JSON 中）
+//   - 进程退出码 os.Exit(1)
+var ErrBusinessFailure = errors.New("mediakit-cli: business failure")