vivideo

Vivideo 工具链

面向 Vivideo API 的开发者与 Agent 集成层——包含共享客户端、MCP 服务、CLI 和 Skills。Agent 是主要用户，而非事后才考虑的对象。

所有内容都构建在公共 API 之上（它是事实来源）。这里不会重复实现任何后端业务逻辑——工具链只增添客户端易用性和防护措施。

vivideo-toolchain/            npm workspaces monorepo (TypeScript)
├── packages/core   @vivideo/core   one typed API client + guardrails (shared)
├── packages/mcp    @vivideo/mcp    MCP server (stdio) — 13 agent tools
├── packages/cli    @vivideo/cli    `vivideo` CLI — humans, scripts, CI, agents
├── skills/                          reusable agent Skills (SKILL.md)
└── docs/                            installation, configuration, workflows

架构

一个客户端、一套类型，均由 packages/core/openapi.yaml 派生。MCP 服务和 CLI 都调用 @vivideo/core——每个请求和响应都只有一种表示形式，因此工具、CLI、文档和 OpenAPI 保持一致。

@vivideo/core 只处理客户端相关事项，不涉及业务逻辑：

防护措施	功能
速率限制	使用令牌桶限制请求速率（默认 8 次/秒）——客户端不会变成请求洪流。
并发上限	使用信号量限制进行中的请求数量（默认 4 个）。
有界重试	只重试 retryable 故障，使用完全随机抖动退避，且限制尝试次数。
遵循 Retry-After	遇到 429 时，先等待 API 指定的延迟再重试。
幂等性	每次创建视频请求都会发送 Idempotency-Key；重试时复用该键 → 不会重复扣费。
超时	为每个请求设置 AbortController 超时时间（默认 30 秒）。
安全等待	waitForVideo 按 API 建议的间隔轮询，并设有硬超时——绝不会使用 while(true)。
机密信息脱敏	从所有日志、错误和输出中移除 API 密钥和签名密钥。

这些措施与 API 自身的身份验证、速率限制、幂等性、额度检查、高级功能限制、所有权检查和错误模型相辅相成，绝不会绕过这些机制。

快速开始

# from the repo (until packages are published to npm)
npm install
npm run build

# authenticate (stored 0600 in ~/.vivideo/config.json), or use VIVIDEO_API_KEY
export VIVIDEO_API_KEY="vv_live_..."   # from https://app.vivideo.ai/account/api-keys

# CLI
node packages/cli/dist/index.js account
node packages/cli/dist/index.js create auto --prompt "A 20s product teaser" --wait

# MCP server (stdio) — point an MCP client at this command
node packages/mcp/dist/index.js

发布后：运行 npm i -g @vivideo/cli（提供 vivideo），并运行 npx @vivideo/mcp 启动服务。

文档

• MCP 服务——安装、配置、连接客户端、工具参考
• CLI——安装、身份验证、命令参考、JSON 与非交互式用法、退出码
• Skills——安装与使用
• 工作流——人工与 Agent 端到端指南
• 安全、速率限制、幂等性、额度与高级功能、故障排查

身份验证与安全

• 密钥按以下顺序读取：显式选项 → VIVIDEO_API_KEY 环境变量 → ~/.vivideo/config.json（以仅所有者可读写的 0600 权限写入）。
• 密钥绝不会被打印——所有输出都会经过机密信息脱敏；configure 会存储密钥，但不会将其回显。
• 密钥是账户级机密。请将其保留在服务端；每个集成使用一个密钥，这样泄露后便可单独撤销。

不包含的内容（明确说明范围）

• 取消——公共 API 没有取消端点，因此不提供取消工具或命令。失败或卡住的渲染任务会由 API 自动退款。
• Agent/聊天模式——公共 API 不提供此功能，因此工具链也不包含此功能。
• 此处不会发布到 npm、配置 DNS 或部署——这些都是外部步骤（请参阅 docs/mcp.md 的最后一节）。

开发

npm run build       # build all three packages (tsc -b)
npm run typecheck   # type-check the whole workspace
npm test            # vitest

需要 Node ≥ 18.17。