OrkasVideoStudio
把你的编码 Agent 变成视频工作室：用自然语言描述视频需求，Agent 编写时间线并产出成片文件。
证据显示零密钥主干、BYO密钥、本地优先设计，测试中可见音频路径校验（COMPOSITION_MANIFEST_AUDIO_PATH_INVALID）等防越界逻辑，最低权限得分尚可；但未见明确的用户确认流程代码（Gate C仅存在于README叙述），密钥处理仅有一句'不打印凭据'，无密钥存储/轮转/掩码的实现证据；外部效果（写文件、付费生成调用）有账单计数校验但无用户侧确认；回滚仅靠'可编辑plan逐段重渲'的声明，无实际恢复/撤销机制文件；依赖安全仅见pin到hyperframes 0.7.60，无审计或lockfile审查证据。
README与测试文件自洽：验证错误码（E_SPEC_*、E_PROMISE_*）在edl.test.ts中可交叉印证；doctor命令与Node≥22/ffmpeg前置条件明确；测试表明路径错误与缺失运行时会给出可操作错误信息。扣分点：错误消息质量仅有测试与README断言，无CLI实际输出样例文件。
使用场景表覆盖说明、剪辑、生成、端到端多类受众，环境要求明确（Node 22、ffmpeg/ffprobe）；能力边界处理突出：MuAPI模型slug白名单、比例/时长校验、不支持操作显式拒绝并有测试。扣分点：video-router的触发/路由精度只有README流程描述，路由技能文件本身未在证据中，无法核实；跨平台（Windows）支持未提及。
信息架构清晰（core/tools/cli/mcp/skills分包），安装说明完整含源码安装回退与early-development披露，命名一致（ovs CLI、@orkas/*包）；已知限制文档化充分（npm未发布、MuAPI字段限制、resolution/audio被忽略等）；MIT许可证含第三方许可说明，得满分。扣分点：版本号为0.0.0且无CHANGELOG或版本策略文件；维护责任仅体现于CI工作流与pnpm verify，无治理、响应承诺或维护者文件。
输出可用性有支撑：plan. IR可diff、逐段重渲、promise-check交付守卫、确定性测试与基准；边际价值相对Remotion/SaaS/薄包装有清晰对比论证；成本收益上零密钥主干+账单计数校验（E_COST_COUNT_MISMATCH）体现成本意识。扣分点：所有效用声明均为静态断言，无执行验证，实际产出质量未知。
部分声明可由测试追溯（验证码、交付守卫行为、叙述签名要求在测试中有对应断言，README与测试交叉印证良好）；但'在Orkas内部端到端验证过'、'经过验证的Kling端点'等关键声明无法在提供文件中追溯；文档混合事实与营销性推断（如'真正的提示'），事实与推断分离不足。
- 发布者身份未经核实，企业采用前应独立确认维护方与响应路径。
- 敏感数据处理（API密钥存储、传输、日志脱敏）仅有README断言，建议审计实际实现后再接入自有密钥。
- 无用户确认流程代码，代理发起的付费生成调用与文件覆盖操作需在宿主agent侧自行加确认。
- npm包尚未发布，当前仅源码安装可用；版本0.0.0且无变更日志，升级无兼容性承诺。
- 路由技能（video-router）文件未在证据中，触发行为无法静态核实，建议运行时抽查。
这个 Agent 能做什么，适合哪些场景？
OrkasVideoStudio 是一个 MIT 许可的本地优先工具包，让任何能运行 shell 或使用 MCP 的编码 Agent（如 Claude Code、Codex、Cursor）驱动视频的合成、生成与剪辑。它并非黑盒视频 Agent：视频被表达为可读、可 diff、可重渲染的 plan. 中间表示，改动一行只重渲染对应片段。项目提供三条能力线——Compose（HTML 动效图形转 MP4）、Edit（剪切、去静音、字幕烧录、配音、本地化）、Generate（自带密钥调用图像/视频/TTS 供应商），以及一条自动端到端管线 Auto，通过 stage-plan、stage-assemble 编排跨模态计划。零密钥主干依赖 HyperFrames 0.7.60、ffmpeg 和 whisper.cpp；生成能力由用户自备 OpenAI、Gemini、豆包等密钥。它最初是 Orkas 桌面应用内置的视频 Agent，后被抽取为独立工具包，通过 ovs CLI 和 MCP 服务器对外提供能力。
Agent 首先读取 video-router 技能以锁定生产线，再读取 stage 技能（stage-plan、stage-compose、video-craft 等），撰写 composition-manifest. 与 plan.，然后调用确定性操作：ovs composition prepare / ovs draft / ovs render 完成基于 HyperFrames 的 HTML 动效合成；ovs edit 系列命令（probe、trim、concat、burnsubs、overlay、loudness、mix、trim-silence、remove-fillers）处理实拍素材；ovs transcribe 与 silence、scenes、quality 借助 whisper.cpp 与 ffmpeg 分析素材并选取高光；ovs speak、image、video 调用自备密钥的供应商生成旁白与画面；ovs plan validate / promise-check 作为交付守卫，验证成片保持承诺（如真实动态而非静帧幻灯）后才允许交付。生成计划的画幅、时长、操作会对照 video.provider 配置校验，MuAPI 适配器仅接受已验证的 Kling v2.1 端点。
- 内容创作者需要用 Claude Code 制作一条带中文旁白和字幕的 60 秒竖屏向量数据库科普视频——Compose 线自动完成 HTML 动效场景、旁白合成与字幕烧录。
- 剪辑师要把 1 小时的屏幕录像切成三条带字幕的 30 秒高光片段——Edit 线用 scenes/quality 定位精彩部分、rank-takes 挑选、trim-silence 去除冗余。
- 产品经理需要为 product-demo.mp4 添加英文配音、字幕并统一响度——Edit 线执行转写、本地化、speak、mix、burnsubs 与响度处理。
- 播客主想清理网络摄像头录像中的静音和口头填充词——Edit 线给出可审计证据链的确定性跳剪。
- 短视频团队要为宣传片的 15 秒 9:16 版本生成开场画面、合成功能亮点并叠加统一旁白——Auto 线在一个 plan. 中跨 generate + compose + narration 编排并经交付守卫验证。
- 独立开发者想在 Cursor 中用自备 OpenAI/Gemini/豆包密钥生成 5 秒城市黎明的电影感镜头——Generate 线直接调用自有供应商密钥，无托管后端。
这个 Agent 有哪些优点和局限？
- plan. 是可读、可 diff 的中间表示，每个片段、字幕和旁白都可独立重渲染，改动一行只重渲染对应部分，产出可审计。
- 零密钥主干（合成/剪辑/转写）即可用，不依赖任何托管后端；生成能力自带密钥（OpenAI、Gemini、豆包、MuAPI 等），无供应商锁定。
- 同时提供 CLI 与 1:1 镜像的 MCP 服务器，兼容 Claude Code、Codex 原生技能加载，也支持任何能运行 shell 的 Agent。
- 内置交付守卫（ovs plan promise-check）在交付前验证成片质量承诺，并对生成计划的画幅/时长/模型与已配置供应商做预校验。
- npm 包尚在发布过程中，现阶段必须从源码克隆、pnpm install && pnpm build 才能使用。
- 依赖 Node ≥ 22 和 PATH 上的 ffmpeg/ffprobe；合成草稿质量门依赖锁定版本的 HyperFrames 0.7.60，环境缺失时视频测试会失败。
- README 标注处于早期开发阶段，命令面与包结构可能变动，存在迁移与升级风险。
- MuAPI 适配器目前仅接受已验证的 Kling v2.1 端点（时长限 5/10 秒、画幅限 16:9/9:16/1:1），编辑与附加参考图控制被明确拒绝，扩展性受限。
如何安装或部署这个 Agent？
前置要求：Node ≥ 22，PATH 上需有 ffmpeg 与 ffprobe。当前 npm 包尚在发布中，推荐从源码安装：
git clone https://github.com/Orkas-AI/Orkas-VideoStudio.git
cd Orkas-VideoStudio
pnpm install && pnpm buildnode packages/cli/dist/index.js doctor # 验证 ffmpeg/ffprobe/node
alias ovs="node $PWD/packages/cli/dist/index.js" # 可选
npm 包发布后可用：npm i -g @orkas/video-studio，随后运行 ovs doctor 自检。生成能力（图像/视频/TTS）为可选项，需在 ~/.config/orkas-video-studio/config. 或环境变量（如 OVS_IMAGE_API_KEY、OVS_VIDEO_API_KEY、OVS_TTS_API_KEY 等）中配置自有密钥。
如何使用这个 Agent？
三种接入方式任选：
1) 原生技能：ovs skills --install --target claude（安装到 ~/.claude/skills，加 --scope repo 则装到 ./.claude/skills）；codex 用 --target codex 装到 ~/.agents/skills。
2) MCP 服务器：claude mcp add ovs -- npx -y @orkas/video-studio-mcp（源码阶段指向 node <repo>/packages/mcp/dist/index.js）。
3) 自描述 CLI：任何能跑 shell 的 Agent 可执行 ovs skills 列出技能、ovs skill video-router 打印完整指令、ovs --help 查看全部命令。
典型会话：Agent 读 video-router 锁定生产线，撰写 composition-manifest. 与 plan.，运行 ovs composition prepare、ovs draft composition --out draft.mp4 --report draft-report.，最后 ovs plan promise-check plan. 通过交付守卫后返回成片。