feat: 新增readme

README.md

@@ -1,114 +1,122 @@
-# MediaKit CLI
+# AI MediaKit CLI
 
-`mediakit-cli` is the MediaKit command-line interface. It supports local and cloud execution modes, generated domain commands, and multi-platform binary distribution.
+[简体中文](./README.zh.md)
 
-## Install
+<p align="center">
+  <img src="./assets/cover.en.png" alt="AI MediaKit CLI — interface rebuilt for LLMs · agent-native · cloud + local" width="880" />
+</p>
 
-### npm
+> The agent-native command-line toolkit for audio & video. Run Volcengine's cloud AI and local editing through **one unified command** — built to be driven by AI agents (Claude Code, Trae, Cursor …) or by you in the terminal.
+
+`mediakit-cli` packs video enhancement, subtitle removal, and a full editing toolbox into a single tool. Heavy AI runs in the cloud; lightweight editing runs locally — switch with one flag, same command surface.
+
+---
+
+## ✨ 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 |
+
+> 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`.
+
+---
+
+## 🚀 Quick Start
 
 ```bash
 npm install -g @volcengine/mediakit-cli
-mediakit-cli version
-```
+npx skills add volcengine/mediakit-cli -g -y   # optional — install agent Skills (Claude Code / Trae / Cursor …)
+export MEDIAKIT_API_KEY=<your-api-key>         # from the AI MediaKit console
 
-### npx
+# Cloud AI (async): enhance to 1080p, then poll for the result
+mediakit-cli --cloud video enhance-video --video-url <url> --resolution 1080p
+mediakit-cli shared query-task --task-id <task_id> --poll-complete
 
-```bash
-npx @volcengine/mediakit-cli version
+# Local editing (sync, no key needed): runs on your machine
+mediakit-cli --local editing trim-video --video-url ./in.mp4 --start-time 3 --end-time 8
 ```
 
-### curl
+---
+
+## 📦 Install
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/volcengine/mediakit-cli/main/scripts/install.sh | bash
-mediakit-cli version
-```
+# npm (recommended, cross-platform — pulls the right build for your OS / arch)
+npm install -g @volcengine/mediakit-cli
 
-Install a specific version or custom path:
+# npx (no install)
+npx @volcengine/mediakit-cli version
 
-```bash
-VERSION=v0.1.0 INSTALL_DIR="$HOME/.local/bin" \
+# curl (macOS / Linux)
 curl -fsSL https://raw.githubusercontent.com/volcengine/mediakit-cli/main/scripts/install.sh | bash
 ```
 
-## AI Agent Skills
+Pin a version or path: `VERSION=<version> INSTALL_DIR="$HOME/.local/bin" curl -fsSL …/install.sh | bash`
+
+Verify: `mediakit-cli doctor` (checks cloud readiness + local tool deps + install hints).
+
+---
 
-`mediakit-cli` pairs with AI agent skills (Claude Code, etc.) that
-teach the agent MediaKit CLI patterns, best practices, and workflows.
+## 🤖 Use with AI Agents
 
-Install all skills:
+`mediakit-cli` ships **AI agent Skills** that teach an agent how to call it — so a user can just say _"enhance this video to 1080p and trim the best 5 seconds"_ and the agent orchestrates the commands.
 
 ```bash
+# One command installs the Skills into every supported agent on your machine
 npx skills add volcengine/mediakit-cli -g -y
 ```
 
-Or pick specific domains:
+This auto-detects and installs to **10+ runtimes** — Claude Code, Trae (CN & Global), Cursor, Codex, Gemini CLI, GitHub Copilot, OpenCode, OpenClaw, Antigravity, and more.
 
-```bash
-npx skills add volcengine/mediakit-cli -s byted-mediakit-editing -y
-npx skills add volcengine/mediakit-cli -s byted-mediakit-video -y
-npx skills add volcengine/mediakit-cli -s byted-mediakit-shared -y
-```
+Every capability is also **MCP-compatible** — `mediakit-cli <domain> <tool> --schema` emits a JSON Schema for MCP / Anthropic Tool Use / function-calling, no hand-written adapter needed.
 
-## Commands
+---
 
-```bash
-mediakit-cli version
-mediakit-cli init
-mediakit-cli doctor
-mediakit-cli config show
-mediakit-cli --domains
-```
+## 🧩 How it works
 
-## Development
+- **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`.
+- **Outputs:** cloud results are returned as URLs; local results write to `~/.mediakit/temp` (override with `--output-path` or `MEDIAKIT_OUTPUT_PATH`).
 
-### Build
+---
 
-```bash
-make build
-```
+## 📖 Documentation
 
-### Build All Platforms
+- Volcengine AI MediaKit product docs & pricing: https://www.volcengine.com/docs/6448
+- Full command reference & FAQ: see the docs site.
 
-```bash
-make build-all
-```
+---
 
-### Snapshot Release
+## 🛠 Development
 
 ```bash
-make snapshot
+make build          # local build → .mediakit/build/dev/mediakit-cli
+make build-all      # all platforms
+make snapshot       # snapshot release
 ```
 
-The local build writes the binary to `.mediakit/build/dev/mediakit-cli`.
-
-## Release
+Releases are produced via `.goreleaser.yml`; npm distribution via `package.json` + `scripts/install.js`; curl install via `scripts/install.sh`.
 
-- GitHub Releases are produced with `.goreleaser.yml`
-- npm distribution uses `package.json`, `scripts/install.js`, and `scripts/run.js`
-- curl installation uses `scripts/install.sh`
-- the GitHub Actions entry is `.github/workflows/mediakit-cli-release.yml`
+<details>
+<summary><b>Local Tool Admission</b> (FFmpeg policy)</summary>
 
-## Local Tool Admission
+- `ffmpeg` / `ffprobe`: required, `5.1.x`, `LGPL v2.1 or later`, commercial use allowed
+- Optional FFmpeg features: `openh264`, `libmp3lame`, `libass`, `libfreetype`, `libfontconfig`, `libfribidi`, `libharfbuzz`, `zlib`, `libpng`, `libjpeg-turbo`
+- Boundary: external process execution only (no static/dynamic linking of local tools into the Go binary); FFmpeg stays in LGPL mode by default; no `non-free` components; no local intermediate artifacts retained (only final outputs + `fetch-file` downloads).
 
-Current local tool allowlist:
+</details>
 
-- `ffmpeg`: required, `5.1.x`, `LGPL v2.1 or later`, commercial use allowed
-- `ffprobe`: required, `5.1.x`, `LGPL v2.1 or later`, commercial use allowed
-- optional FFmpeg features: `openh264`, `demuxer`, `libmp3lame`, `libass`, `libfreetype`, `libfontconfig`, `libfribidi`, `libharfbuzz`, `zlib`, `libpng`, `libjpeg-turbo`
-- approved optional feature version anchors: `libass 0.17.3`, `libfreetype 2.13.3`, `libfontconfig 2.15.0`, `libfribidi 1.0.16`, `libharfbuzz 10.2.0`
-- built-in local helper: `fetch-file` downloads HTTP/HTTPS URLs to `MEDIAKIT_OUTPUT_PATH` and returns local paths unchanged
+---
 
-Admission boundary:
+## License
 
-- Only use external process execution via `os/exec`
-- Do not statically link or dynamically link local tools into the Go binary
-- Do not modify upstream source code
-- Keep FFmpeg in LGPL mode by default
-- Do not introduce `non-free` components by default
-- Do not keep local intermediate artifacts; only final user outputs and `fetch-file` downloads are retained
+This project is open-sourced under the [MIT License](./LICENSE).
 
-## Local File Output
+This software calls MediaKit APIs at runtime. Use of these APIs is subject to the following terms and privacy policies:
 
-- `MEDIAKIT_OUTPUT_PATH` overrides the local file output directory
-- Default output directory: `~/.mediakit/temp`
+- [Video Cloud Service Special Terms](https://www.volcengine.com/docs/6448/79646?lang=zh)
+- [Intelligent Processing Service Billing Rules](https://www.volcengine.com/docs/6448/104992?lang=zh)
+- [Intelligent Processing Service Level Agreement](https://www.volcengine.com/docs/6448/79648?lang=zh)

README.zh.md

@@ -0,0 +1,122 @@
+# AI MediaKit CLI
+
+[English](./README.md)
+
+<p align="center">
+  <img src="./assets/cover.png" alt="AI MediaKit CLI — 接口为模型重构 · Agent 原生 · 端云一体" width="880" />
+</p>
+
+> 面向 Agent 的音视频命令行工具集。用**一个统一的命令**调用火山引擎的云端 AI 能力、跑本地剪辑——既能让 AI Agent（Claude Code、Trae、Cursor……）自然语言调度，也能你自己在终端直接用。
+
+`mediakit-cli` 把画质增强、字幕擦除和一整套剪辑能力收进一个工具：重算力 AI 跑云端，轻量剪辑在本地跑——一个 flag 切换，命令写法不变。
+
+---
+
+## ✨ 能做什么
+
+| 能力                                                                                              | 运行             | 状态        |
+| ------------------------------------------------------------------------------------------------- | ---------------- | ----------- |
+| **AI 能力** — 画质增强 · 字幕擦除                                                                 | 云端             | ✅ 已上线   |
+| **剪辑能力**（11 个）— 裁剪 · 拼接 · 加水印 · 加字幕 · 调速 · 翻转 · 提取 / 合成音频 · 图片转视频 | 云端 **或** 本地 | ✅ 已上线   |
+| **更多 AI 工作流** — 视频理解 · 视频翻译 · 高光智剪 · 剧本还原 · 解说 · 漫剧转绘 …                | 云端             | 🚧 陆续上线 |
+
+> AI 能力跑在云端（弹性算力、异步）；剪辑能力**云端或本地**皆可（本地跑，同步、零成本）—— 每条命令用 `--cloud` / `--local` 选。
+
+---
+
+## 🚀 快速开始
+
+```bash
+npm install -g @volcengine/mediakit-cli
+npx skills add volcengine/mediakit-cli -g -y   # 可选 —— 装 Agent Skill（Claude Code / Trae / Cursor …）
+export MEDIAKIT_API_KEY=<你的 API Key>         # 在 AI MediaKit 控制台获取
+
+# 云端 AI（异步）：增强到 1080p，再轮询拿结果
+mediakit-cli --cloud video enhance-video --video-url <url> --resolution 1080p
+mediakit-cli shared query-task --task-id <task_id> --poll-complete
+
+# 本地剪辑（同步、无需 Key）：在本机跑
+mediakit-cli --local editing trim-video --video-url ./in.mp4 --start-time 3 --end-time 8
+```
+
+---
+
+## 📦 安装
+
+```bash
+# npm（推荐，跨平台——自动拉取对应平台 / 架构的构建产物）
+npm install -g @volcengine/mediakit-cli
+
+# npx（免安装）
+npx @volcengine/mediakit-cli version
+
+# curl（macOS / Linux）
+curl -fsSL https://raw.githubusercontent.com/volcengine/mediakit-cli/main/scripts/install.sh | bash
+```
+
+指定版本 / 路径：`VERSION=<version> INSTALL_DIR="$HOME/.local/bin" curl -fsSL …/install.sh | bash`
+
+验证环境：`mediakit-cli doctor`（检查云端就绪 + 本地工具依赖 + 安装指引）。
+
+---
+
+## 🤖 配合 AI Agent 使用
+
+`mediakit-cli` 自带 **AI Agent Skill**——教 Agent 怎么调它。于是用户只需说一句*“把这个视频增强到 1080p，再剪出最精彩的 5 秒”*，Agent 就能自动编排命令。
+
+```bash
+# 一个命令把 Skill 装进本机所有支持的 Agent
+npx skills add volcengine/mediakit-cli -g -y
+```
+
+它会自动检测并安装到 **10+ 种 runtime**——Claude Code、Trae（国内 & 海外）、Cursor、Codex、Gemini CLI、GitHub Copilot、OpenCode、OpenClaw、Antigravity 等。
+
+每个能力还**MCP 兼容**——`mediakit-cli <domain> <tool> --schema` 吐出 JSON Schema，直接喂 MCP / Anthropic Tool Use / function calling，无需手写适配器。
+
+---
+
+## 🧩 工作原理
+
+- **两种模式，同一套命令。** `--cloud` 把重算力 AI 跑在火山引擎云端（弹性算力、异步 `task_id`）；`--local` 在本机跑确定性剪辑（同步、零云端成本）。默认 `cloud-first`，单命令 flag 可覆盖。
+- **命令结构：** `mediakit-cli [--cloud|--local] <domain> <tool> [flags]`——domain 为 `editing` · `video` · `shared`。
+- **输出：** 云端结果以 URL 返回；本地结果写到 `~/.mediakit/temp`（可用 `--output-path` 或 `MEDIAKIT_OUTPUT_PATH` 覆盖）。
+
+---
+
+## 📖 文档
+
+- Volcengine AI MediaKit 产品文档 & 定价：https://www.volcengine.com/docs/6448
+- 完整命令参考 & FAQ：见文档站。
+
+---
+
+## 🛠 开发
+
+```bash
+make build          # 本地构建 → .mediakit/build/dev/mediakit-cli
+make build-all      # 全平台
+make snapshot       # snapshot release
+```
+
+发布走 `.goreleaser.yml`；npm 分发走 `package.json` + `scripts/install.js`；curl 安装走 `scripts/install.sh`。
+
+<details>
+<summary><b>本地工具 Admission</b>（FFmpeg 策略）</summary>
+
+- `ffmpeg` / `ffprobe`：必需，`5.1.x`，`LGPL v2.1 或更高`，允许商用
+- 可选 FFmpeg 能力：`openh264`、`libmp3lame`、`libass`、`libfreetype`、`libfontconfig`、`libfribidi`、`libharfbuzz`、`zlib`、`libpng`、`libjpeg-turbo`
+- 边界：仅通过外部进程调用（不把本地工具静态 / 动态链接进 Go 二进制）；FFmpeg 默认保持 LGPL 模式；默认不引入 `non-free` 组件；不保留本地中间产物（仅保留最终产物 + `fetch-file` 下载）。
+
+</details>
+
+---
+
+## License
+
+本项目基于 [MIT 许可证](./LICENSE) 开源。
+
+该软件运行时会调用 MediaKit 的 API，使用这些 API 需要遵守如下协议和隐私政策：
+
+- [视频云服务专用条款](https://www.volcengine.com/docs/6448/79646?lang=zh)
+- [智能处理服务计费结算规则](https://www.volcengine.com/docs/6448/104992?lang=zh)
+- [智能处理服务等级协议](https://www.volcengine.com/docs/6448/79648?lang=zh)

internal/cloud/request.go

@@ -87,6 +87,7 @@ func (c *Client) newRequest(method string, path string, query map[string]any, bo
 	req.Header.Set("Content-Type", "application/json")
 	req.Header.Set("x-surface", resolveSurface(c.Surface))
 	req.Header.Set("x-runtime", resolveRuntime(c.Runtime))
+	req.Header.Set("X-Amk-Task-Source", "cli")
 	if c.APIKey != "" {
 		req.Header.Set("Authorization", "Bearer "+c.APIKey)
 	}