theinfluencecompany/dsh-realtimeavatar

dsh-realtimeavatar

ci
npm

Realtime Avatar for the DeepSeek Harness：由 harness 持有开发者的 API 密钥，将公开文档作为按需加载的技能，通过公开 REST API 提供 rta_ 工具，以及一个 /rta 命令，引导开发者从没有密钥到发起实时通话。

Realtime Avatar 将实时 AI 角色带入语音或视频通话。开发者接口是 realtime-avatar npm SDK（源码）以及位于 https://realtimeavatar.ai/api/v1 的 REST API。从编码代理驱动它通常意味着将 API 密钥粘贴到聊天中、每次会话都重新解释文档，并让代理调用会消耗额度而无人察觉的端点。此插件将头像作为原语提供给 harness：密钥是一个凭证引用，由 harness 在每次调用时解析，模型永远看不到；文档是五个技能，模型在相关时加载它们；API 是十八个类型化工具，位于写入审批门之后；而 /rta 无需模型参与即可完成入门引导。

写入默认启用，但需审批，任何消耗额度的操作都会询问。readOnly:true 会关闭所有写入。

你将获得

工具

读取工具无需审批即可运行，并标记为并发安全，因此 harness 可以并行运行它们。rta_docs 和 rta_quickstart 完全不需要密钥。

| 工具 | 范围 | 功能 |
|---|---|---|
| rta_status | credits:read, realtime:write | 自检：是否配置了密钥（来源及 live/test 标签，绝不显示值）、额度余额、实时容量、写入姿态以及下一步该做什么。出问题时首先运行它。 |
| rta_balance | credits:read | 额度余额：可用、预留和终身额度，以及大约可通话的分钟数（1 额度 = 1 秒）。 |
| rta_capacity | realtime:write | 实时通话容量快照：空闲和活跃槽位、队列深度、是否开放准入、建议的重试延迟。仅供参考——它不能预测是否会授予 mint，因此绝不要用它来限制 mint；直接 mint，并将 queued 响应视为信号。 |
| rta_avatars | avatars:read | 列出工作区的头像及其 status 和 idleVideoStatus（最近更新的在前，最多 100 个）。 |
| rta_avatar | avatars:read | 获取单个头像。在 rta_avatar_create 之后每隔几秒轮询此工具，直到 status 为 ready。 |
| rta_clips | avatars:read | 一个化身的动作片段库（clipId、角色、状态、whenHint），以及 rta_clips_set 可用于比对的 revision。 |
| rta_assets | avatars:read | 列出已上传的资产；图像资产 id 就是 rta_avatar_create 作为 sourceAssetId 接收的内容。 |
| rta_usage | usage:read | 计费会话：默认最近 30 天，上限为 90 天，按游标分页，可缩小到单个最终用户。每一行都带有 activeSeconds（规范字段）、avatarName 和 endUserId（取自 metadata.user_id）。只有 released 和 failed 行会被结算，总计也只汇总这些行。 |
| rta_session_release | realtime:write | 提前释放已创建通话的槽位。免费且幂等，因此它位于读取层级。 |
| rta_docs | none | 某个公开文档页面的当前 markdown：14 个文档页面加上 index（llms.txt）和 openapi（操作表）。可选的 heading 返回某一节。 |
| rta_quickstart | none | 某个框架（nextjs、tanstack-start、express、hono、react）的集成页面，其中提取了服务端和客户端两半的代码骨架；离线时回退到随附的快照。 |

无写入成本工具会改变状态但不消耗额度。它们默认请求批准，只有在 writeApproval:false 时才无需提示直接运行。

| 工具 | 作用域 | 功能 |
|---|---|---|
| rta_asset_remote | avatars:write | 将平台通过绝对 http(s) URL 获取的文件注册为资产（image、video 或 audio）。 |
| rta_avatar_update | avatars:write | 部分更新化身：显示名称、默认语音、llmProvider 和模型、人设、艺术指导、stylePreset、设置、元数据、anchorTimeMs。llmProvider 和 stylePreset 是封闭枚举：local、gemini、openai 以及 cinematic-founder、editorial-companion、warm-anime、luxury-realism、soft-3d、noir-avatar。肖像替换是独立通道：单独传入 sourceAssetId（一个图像资产），可选附带 anchorTimeMs——它与其他所有字段互斥。 |
| rta_avatar_delete | avatars:write | 软删除一个化身；此后它会从所有读取中消失。 |

有写入成本工具会消耗额度，并且始终请求批准，无论 writeApproval 如何设置。

| 工具 | 作用域 | 功能 |
|---|---|---|
| rta_avatar_create | avatars:write | 从肖像图像资产创建化身（一次生成）。返回 preprocessing；轮询 rta_avatar 直到 ready。 |
| rta_loop_set | avatars:write | 根据新的动作提示重新渲染化身的静息循环（一次生成）。需要化身上有肖像（否则返回 422 loop_not_generatable）；不要以 sourceKind 作为判断条件——一旦生成的循环附加，就绪的化身会读取为 video。发送 Idempotency-Key，因此重试绝不会渲染两次。 |
| rta_clips_set | avatars:write | 声明完整的片段库：新片段会渲染，匹配的片段会保留，被移除的片段会退役，空数组会让所有片段退役。最多 12 个条目；每个 clipId 匹配 ^[a-z0-9][a-z0-9_-]$（≤64 个字符），whenHint ≤280 个字符，durationSeconds 是 4–8 的整数，source 是 { motionPrompt } 或 { assetId }。Idempotency-Key 加上可选的基于 expectedRevision 的比较并交换。 |
| rta_session_mint | realtime:write | 铸造一个实时通话会话：预留一个容量槽位，并在客户端加入时计费一次。策略字段：instructions（≤4000 个字符）、initialContext（≤32 条消息）、maxSessionSeconds（受配置上限约束）、mode（avatar 或 voice）、voiceId（一个语音 id，以 voice_id 发送）或 voice（一个完整对象 { provider, voice_id, … }）、clientMetadata（≤16 个字符串对，键 ≤64 个字符，值 ≤200）、transcriptWebhook（url 为 https 且 ≤500 个字符，secret 为 16–200）。容量已满的应答会以 queued 加一张票据返回，而不是错误。除非 includeToken:true，否则参与者令牌会被扣留；该选项会返回令牌并将其渲染在聊天文本中。使用 rta_session_release 释放。

每个工具都会将 harness 的取消信号转发给 HTTP 请求，因此被取消或超时的调用会中止请求，而不是在后台继续运行；harness 会将其报告为 ABORTED 结果。有三个公开操作被有意不暴露：POST /api-keys（在仪表盘中铸造密钥）、POST /assets（多部分上传——请使用 rta_asset_remote）以及已弃用的 POST /avatars/{avatarId}/clips。

上游错误会被解析出消息和代码，并映射到一种类型。403 不仅仅是缺少作用域：非活动工作区也会返回 403，片段端点上的 clip_library_not_enabled 发布门控也是如此——在铸造更宽权限的密钥之前，请先阅读错误文本。

技能

五个技能携带 14 个公开文档页面的带日期快照。目录中只包含名称和描述；正文在模型调用 skill 工具或你输入 / 时加载。

| 技能 | 页面 |
|---|---|
| realtimeavatar-quickstart | 概览、快速开始、身份验证——前面是经过验证的关键事实标头：套餐、作用域、密钥格式、公开代理提示词 |
| realtimeavatar-integrate | Next.js、TanStack Start、Express、Hono/Workers/Bun/Deno、React 和 React Native |
| realtimeavatar-avatars | 创建头像、编辑角色 |
| realtimeavatar-calls | 通话（会话策略、五种客户端状态）、工具调用、实验性功能 |
| realtimeavatar-api | API 参考——前面是操作表，包含每个端点的作用域、积分成本和包装它的 rta_ 工具 |

/rta 命令

无需模型参与即可运行。

/rta setup           — 如何获取密钥并进行第一次调用
/rta key      — 将你的 API 密钥存储到 harness 凭据存储中（不会记录在会话日志中；绝不会展示给模型）
/rta key             — 密钥状态（来源、live/test 标签；绝不显示密钥值）
/rta key clear       — 移除已存储的密钥
/rta status          — 密钥、额度、容量、写入状态
/rta prompt          — 面向编码代理的公开“构建我的第一个应用”提示词
/rta docs [page]     — 公开文档页面

/rta key 以 recordInput:false 注册，并且不经过模型运行，因此粘贴的密钥不会被记录在会话日志中，也绝不会展示给模型。Web 编辑器在你输入时确实会将草稿保存在浏览器 localStorage 中；如果这有影响，请在启动 shell 中导出 REALTIME_AVATAR_API_KEY。/rta key clear 仅移除凭据文件中的条目，并报告之后还有什么仍在提供密钥。

/rta 在交互式配置文件（Web UI）中可用。无头运行和一次性运行没有命令界面：在启动 dsh 的 shell 中导出 REALTIME_AVATAR_API_KEY，或者按照密钥所在位置中所示，将该条目添加到 $DSH_HOME/.credentials.yaml。

系统提示词指引

一个简短的章节（tool:rta）告诉模型存在 rta_ 工具以及它们涵盖的内容；在设计集成之前应加载哪个技能，以及 rta_docs 中有当前文本；密钥由 harness 以凭据引用的形式持有，绝不能在聊天中请求、打印或放入客户端代码（不得使用 NEXT_PUBLIC_/VITE_ 名称）；某个工具报告 RTA_KEY_MISSING 意味着“在 Web UI 中运行 /rta setup，或在启动 dsh 之前导出该变量”；seed-rin-ashfall 是任何密钥都可以调用的公开示例虚拟形象，因此第一个应用永远不必等待创建虚拟形象；哪些工具会消耗额度；以及每个铸造的会话都必须释放。文档本身绝不会进入提示词。

安装

从 npm 安装。配置文件目录是 pnpm 工作区根目录，因此 pnpm 需要 -w：

dsh plugin --profile web add -w dsh-realtimeavatar

npm tarball 附带预构建的 lib/，因此没有需要批准的构建步骤。该
包通过 CI 发布，并带有 provenance；
npm audit signatures 会验证该证明。

在开发期间，从本地检出安装：

cd dsh-realtimeavatar && npm install && npm run build
dsh plugin --profile web add -w /absolute/path/to/dsh-realtimeavatar

直接从 git 安装（github:theinfluencecompany/dsh-realtimeavatar）则会通过 prepare 脚本构建 lib/。pnpm 会阻止 prepare 构建，直到你允许一次：在配置文件的 pnpm-workspace.yaml 中的 allowBuilds 下添加 pnpm 打印的条目（较旧的 pnpm 10 会改为打印一行 onlyBuiltDependencies），然后重新运行安装。

需要 Node 22.13 或更新版本。该插件没有运行时依赖。

五分钟内获取密钥

这与 /rta setup 打印的路径相同。
1. 注册免费的 Sandbox 套餐，网址为 ：每月 $0，1,020 积分（约 17 分钟通话时长），1 个并发流，1 个虚拟形象，无需信用卡。1 积分 = 1 秒通话时长；实时对话约为每小时 $5。套餐详情：。
2. 打开仪表盘，网址为 。API 密钥位于 。
3. 创建密钥。 它只显示一次，格式类似 tic_test_… 或 tic_live_…。标签仅用于组织管理，并非沙盒——两者消耗相同的积分。仪表盘密钥默认拥有除  之外的所有权限范围：取消勾选此密钥不应执行的权限（尤其是 api_keys:write），并设置每个密钥的支出限额。
4. 存储密钥，在 Web UI 中使用 /rta key tic_…。它会保存到 $DSH_HOME/.credentials.yaml 中的 REALTIME_AVATAR_API_KEY 下；该命令无需模型即可运行，且不会记录在会话日志中。或者，在启动 dsh 的 shell 中执行 export REALTIME_AVATAR_API_KEY=…——这是无头运行的唯一途径，因为无头运行没有 /rta。切勿使用 NEXT_PUBLIC_/VITE_ 前缀的名称：密钥应保留在你的服务器上。
5. 验证，使用 /rta status：查看积分、容量、密钥标签。
6. 构建。 执行 npm install realtime-avatar，然后将 /rta prompt 交给你的 agent，这是仪表盘在新密钥旁显示的公开提示词：

Build a one-button page that opens a live video call with the example avatar Rin (seed-rin-ashfall): she speaks first, two-way voice, her portrait while she connects, a hang-up button. Stop there for testing. Key in REALTIME_AVATAR_API_KEY. Follow https://realtimeavatar.ai/llms.txt.

Optional — to use your own avatar instead: create Nova from nova.png with a warm mid-pitch voice, poll until ready, and repoint the same button at her without changing the page.

它从公开的示例虚拟形象 seed-rin-ashfall 开始，因此无需等待创建虚拟形象。agent 可以加载 realtimeavatar-quickstart / realtimeavatar-integrate，或根据其框架调用 rta_quickstart。
7. 使用你自己的虚拟形象。 使用 rta_asset_remote 注册肖像，使用 rta_avatar_create 创建（会消耗积分，需先确认），轮询 rta_avatar 直到状态为 ready，然后替换 id。

公开套餐，如定价页面所示：

| 套餐 | $/月 | 积分 | ≈ 分钟 | 并发流 | 虚拟形象 | 备注 |
|---|---|---|---|---|---|---|
| Sandbox | 0 | 1,020 | 17 | 1 | 1 | 无需信用卡；足够创建第一个虚拟形象并进行几分钟通话 |
| Starter | 9 | 7,200 | 120 | 2 | 5 | 超额 $0.095/分钟 |
| Developer | 24 | 36,000 | 600 | 5 | 25 | 超额 $0.085/分钟 |
| Studio | 119 | 180,000 | 3000 | 20 | 100 | 超额 $0.08/分钟；实验性功能 |

权限范围，如认证页面所述：

| 权限范围 | 授予权限 |
|---|---|
| realtime:write | 开始和结束通话 |
| avatars:read | 列出并获取虚拟形象和资源 |
| avatars:write | 创建和更新虚拟形象、上传资源、同步片段 |
| credits:read | 读取余额 |
| usage:read | 用量报告（读取） |
| usage:write | 用量报告（写入） |
| api_keys:write | 再生成密钥——除非后台任务需要，否则不要勾选 |
|  | 所有权限，包括之后新增的 scope——除受信任的后台任务外，请避免使用 |

此插件的密钥需要 realtime:write、avatars:read、credits:read 和 usage:read 才能使用读取工具，另外如果你打算创建或编辑头像，还需要 avatars:write。它永远不需要 api_keys:write 或 。

配置

该包已经在你的 profile 中插入了一行 realtimeavatar。请通过 profile 的 cordis.patch.yml 使用以 id 为目标的条目覆盖其 config——而不是再添加一个 insert 条目，否则会加载插件两次。API 密钥永远不属于此配置的一部分；请参阅下一节。

- id: realtimeavatar
name: 'dsh-realtimeavatar'
config:
apiKeyEnv: REALTIME_AVATAR_API_KEY   # 凭据引用（一个环境变量风格的名称），绝不是密钥本身
readOnly: false                      # 默认 false；true 会拒绝所有写入工具
writeApproval: true                  # 默认 true；false 允许无写入的工具无需确认即可运行（消耗额度的工具仍会询问）
maxSessionSeconds: 300               # 应用于 rta_session_mint 的上限（1–1800，会被钳制）
requestTimeoutMs: 30000              # 每次 API 请求（5 秒 – 2 分钟，会被钳制）
docsTimeoutMs: 20000                 # 每次文档获取（5 秒 – 2 分钟，会被钳制）
docsMaxChars: 24000                  # rta_docs / rta_quickstart 的输出上限（2000–200000，会被钳制）

apiKeyEnv 必须是环境变量风格的名称（字母、数字、下划线）。以 tic_ 开头的值会被拒绝：apiKeyEnv 是凭据的名称，它从不保存密钥。布尔值必须是布尔值；数字必须为正数，并会被四舍五入并钳制到其范围内。如果配置无效，插件会在启动时记录一条警告，使用默认值运行，并且 rta_status / /rta status 会打印配置错误。带有注释的此条目副本位于 examples/cordis.patch.yml。

密钥存放位置

apiKeyEnv 是一个凭据引用，默认值为 REALTIME_AVATAR_API_KEY——与公开文档中各处使用的名称相同。其背后的值在每次调用时解析，绝不在启动时解析。

- 凭据存储。 当 dsh 组合其凭据服务时，该值会通过它解析。该存储分层了四个来源，第一个拥有该名称的来源胜出：
1. 启动 dsh 的进程的环境——只读，始终胜出；
2. $DSH_HOME/.credentials.yaml——/rta key 写入的文件；
3. 工作目录中的 .env（报告为 project-env）；
4. dsh home 中的 .env（报告为 user-env）。
- /rta key tic_… 校验其格式（tic_live_… 或 tic_test_…，可打印 ASCII 字符，不含空白字符），写入凭据文件，并仅以标签和长度作为响应。它无需模型即可运行，并以 recordInput:false 注册，因此粘贴的密钥不会被记录到会话日志中，也绝不会展示给模型。Web 编辑器在你输入时将草稿保存在浏览器 localStorage 中；如果这有影响，请在启动 shell 中导出 REALTIME_AVATAR_API_KEY。由启动环境提供的名称是只读的：该命令拒绝覆盖它（RTA_KEY_SHADOWED）。
- /rta key clear 仅移除凭据文件中的条目，并报告之后仍由什么提供密钥（例如 project-env，即工作目录中的 .env）。由启动环境提供的密钥无法从此处清除。
- 无头模式。 /rta 仅存在于交互式配置文件（Web UI）中；无头模式和一次性运行没有命令界面。请在启动 shell 中导出 REALTIME_AVATAR_API_KEY，或将条目添加到 $DSH_HOME/.credentials.yaml（权限模式 600）：

version: 1
refs:
REALTIME_AVATAR_API_KEY: tic_…

- 无凭据服务。 没有凭据服务的配置文件会直接从启动 dsh 的环境中读取引用；在那里 /rta key 会返回 RTA_KEY_STORE_UNAVAILABLE。
- 绝不渲染。 该值仅存在于请求闭包中。rta_status 和 /rta key 报告密钥的来源以及它是实时密钥还是测试密钥，但绝不报告其值。密钥缺失时会以 RTA_KEY_MISSING 的形式出现，并提示在 Web UI 中运行 /rta setup，或在启动 dsh 之前导出该变量。

绝不要将密钥放入客户端代码。它授权针对你的额度进行调用和生成；SDK 的路由适配器将其保留在服务器端，而 NEXT_PUBLIC_/VITE_ 名称会将其发送到每个浏览器。

安全

tools/pre-execute 门控按工具层级进行判定：

| 层级 | 工具 | readOnly:true | writeApproval:true（默认） | writeApproval:false |
|---|---|---|---|---|
| read | rta_status, rta_balance, rta_capacity, rta_avatars, rta_avatar, rta_clips, rta_assets, rta_usage, rta_session_release, rta_docs, rta_quickstart | allow | allow | allow |
| write-free | rta_asset_remote, rta_avatar_update, rta_avatar_delete | deny | ask | allow |
| write-costly | rta_avatar_create, rta_loop_set, rta_clips_set, rta_session_mint | deny | ask | ask（始终） |
- 这道门禁只是 harness 链条中的一环。 dsh 按顺序运行其 tools/pre-execute 监听器，每个监听器都可以通过 next() 将调用传递下去。该插件从不强制放行：上文的“允许”意味着读取——以及当 writeApproval:false 时的免费写入——会沿链条向下传递，因此后续的策略插件（计划模式、部署策略）仍然能看到它们。对于审批询问，它会先调用 next()，下游的拒绝会胜过它的提示。readOnly:true 会立即拒绝，先于其他任何操作运行；每个写入工具在执行时还会再次拒绝，作为第二层防护。
- 审批通过 dsh 的审批服务进行。在 Web UI 中，你会看到一张确认卡片，其中包含对写入内容的一行脱敏描述（工具、avatar id、提示长度、片段数量、会话上限）。在无人能够应答的情况下——没有交互式应答器的无头配置文件、没有审批服务的配置文件，或 DSH_PERMISSION_MODE=danger-full-access（dsh 将审批策略设为 never）——该询问会被自动拒绝。在这些模式下，消耗额度的工具完全无法运行，而无写入的工具只有在 writeApproval:false 时才能运行。
- writeApproval:false 仅为三个无写入工具解除门禁；当两个标志都关闭时，插件会在启动时记录一条警告。
- 脱敏。 任何形如 tic_live_… / tic_test_… 的令牌以及任何 Bearer 值，都会在每条错误消息、渲染的工具输出、审批理由和命令结果中被脱敏；请求的确切密钥也会被清除。上游错误响应体会被解析以提取其消息和代码——原始响应文本绝不会被暴露出来。
- 参与者令牌默认被保留。 除非显式传入 includeToken:true，否则 rta_session_mint 返回的会话不包含可加入的参与者令牌。传入该参数后，令牌会在结果中返回，并且*会渲染在聊天文本中，模型和记录都能看到它——只有当你打算从这里加入时才请求它。
- 会话必须被释放。 已铸造的会话会占用一个容量槽位，并在客户端加入时计费。完成后，请使用 sessionId（或 queueTicketId）调用 rta_session_release；该预留也会自行过期。maxSessionSeconds 会在调用所请求的值之上受配置上限约束（默认 300 秒）。
- 重试绝不会渲染两次。 rta_loop_set 和 rta_clips_set 会发送一个 Idempotency-Key（除非你自行传入，否则自动生成）。你自行传入的密钥必须不超过 180 个 header 安全字符（字母、数字、.、_、:、-）；API 会忽略更长的密钥，这将使该保护失效。
- 输入在到达 URL 之前会被收窄：id 必须是字母、数字、点、下划线或短横线；远程资源 URL 必须是绝对 http(s) 地址；线上 schema 的大小限制（指令、上下文消息、元数据对、片段字段、webhook URL）会在本地强制执行，超过 1 MB 的请求体会在离开进程之前被拒绝。
- tic_test_ 密钥不是沙盒。 它消耗的额度与 tic_live_ 密钥相同。免费的 Sandbox 计划才是无需付费即可试用各种功能的方式。

文档与时效性

这五项技能是公开文档的带日期的快照。每个文件的 frontmatter 记录了 snapshot: YYYY-MM-DD 和来源页面，正文开头也标明了日期。公开页面经常变动——其 Updated 时间戳几乎每天都在变——因此请将快照视为起点，而将 rta_docs（它会获取实时页面）视为权威来源。npm run sync-docs -- --check 会显示已发布的快照与实时页面之间已经偏离了多远。

该快照在发布时由 npm run sync-docs 重新生成，而非在构建时：该脚本会获取 14 个公开页面和 openapi.json，校验每个页面的结构（标题行、页脚、最小大小），当 src/facts.ts 中的操作表与实时规范发生偏离时拒绝写入，对生成的文本运行泄漏检查，并通过临时文件和重命名的方式写入每个文件，因此即使失败也绝不会留下半更新的快照。realtimeavatar-api 技能内嵌了操作表。捆绑技能在优先级上低于所有技能发现根目录，因此你自己技能目录中的副本会遮蔽捆绑的那一个。

当时效性很重要时，rta_docs 会在每次调用时获取实时页面。它只接受封闭的 slug 集合（14 个页面加上 index 和 openapi），绝不接受任意 URL；会剥离站点页脚；可按请求返回单个章节；并将输出限制在每次调用的 maxChars 之内，而该值本身又受 docsMaxChars 限制。rta_quickstart 也会获取实时内容，并在不得不回退时报告 source: live 或 source: snapshot。

公开的机器可读入口点：

- 智能体指南：（完整文本见 ）
- OpenAPI：
- 文档： — 在任意页面后追加 .md 即可获取 markdown

手工维护的事实信息（URL、计划、作用域、操作表、错误表、智能体提示词）存放在 src/facts.ts 中，并附有它们最后一次对照实时站点验证的日期。

许可证

MIT