从录音硬件，
到你的 Agent From recording hardware
to your Agent

首次初始化与管理边界First-time setup and administration boundaries

服务首次启动后会生成一个仅所有者可读的高熵 Setup Token。它只用于创建第一位 System Admin；初始化完成后，日常操作都在 /admin 中进行。On first start, the service creates a high-entropy, owner-readable Setup Token. It is used only to create the first System Admin; ongoing work then happens in /admin.

用浏览器连接一台设备Connect a device from the browser

Device Platform 的管理端负责授权，具备蓝牙的用户电脑负责 BLE 操作。服务器部署在 NAS 或无蓝牙主机上也没有关系。Admin owns authorization while the user's Bluetooth-capable computer performs BLE operations. The server itself can run on a NAS or another host without Bluetooth.

为应用开放最小必要能力Expose only the capabilities an application needs

REST、stdio MCP、远程 MCP 和 Webhook 使用同一套 Permission Catalog、配额与审计。Application 属于一个 Group，凭证不能越过这个边界。REST, stdio MCP, remote MCP and Webhooks share one Permission Catalog, quota and audit model. An Application belongs to one Group and its credentials cannot cross that boundary.

把初始化页面里的每一个值准备好Prepare every value required by Studio setup

Studio 不是自动获得整个平台的权限。先在 Device Platform 为它创建一个独立 Application、一次性显示的 API Token 和签名 Webhook，再根据运行档位准备处理服务。下面的路径与字段和 Demo 当前界面一一对应。Studio does not inherit platform-wide access. Create a dedicated Application, a one-time API Token and a signed Webhook in Device Platform, then prepare processors for the selected deployment profile. The paths below map directly to the current Demo fields.

Channels     rest, webhook
Permissions  recordings:read
             recordings:download_link:create
Webhook      https://<studio-host>/webhooks/voicecan
Events       file.synced, recording.deleted

让 Agent 使用你的设备与录音数据Let agents use your device and recording data

平台提供两个互相隔离的 MCP 权限面：Local Admin MCP 用于操作本机安装；Application MCP 只暴露某个应用被授权的设备、录音、命令和事件能力。The platform exposes two isolated MCP permission planes: Local Admin MCP operates the local installation, while Application MCP exposes only the Device, recording, command and event capabilities granted to one Application.

voicecan-device mcp connect --application <application-id> --client generic --output json

该命令创建 stdio 凭证，将它保存为仅所有者可读的 Secret Reference，并返回不含明文 Token 的 Host 配置。远程 MCP 则使用 OAuth、PKCE 与显式授权绑定到一个可访问的 Application。This command creates a stdio credential, stores it as an owner-only Secret Reference and returns a Host configuration without a plaintext token. Remote MCP instead uses OAuth, PKCE and explicit consent bound to an accessible Application.

Remote MCP · OAuth consent

Codex 连接前，先明确授权范围Define the permission boundary before Codex connects

远程连接会展示目标 Application、请求权限与本地回调地址。用户确认后，Agent 才能在这组明确的权限内访问设备、录音、命令和事件。The remote flow shows the target Application, requested permissions and local callback. Only after explicit consent can an agent access Devices, recordings, commands and events within that boundary.

1. 01确认要连接的 ApplicationConfirm the target Application
2. 02检查最小必要权限Review the minimum required permissions
3. 03确认回调地址并授权连接Verify the callback and authorize

安全获取一段录音Retrieve a recording safely

Open Platform API 和 MCP 都不会直接携带录音字节。应用先查询元数据，再创建短时、一次性的 Download Grant；授权消费时会重新检查 Application、凭证、录音状态与设备当前 Group。Neither Open Platform APIs nor MCP carry recording bytes. An app first queries metadata, then creates a short-lived, one-use Download Grant. Consumption rechecks the Application, credential, recording lifecycle and the Device's current Group.

POST /api/v1/recordings/file_xxx/download-links
Authorization: Bearer vcd_app_...
Idempotency-Key: stable-request-id
Content-Type: application/json

{"purpose":"download","ttl_seconds":300,"reason":"Reviewed export"}

上线与日常运维Production and day-two operations

公开部署需要明确区分应用/API 地址和设备 WSS 地址。备份必须同时覆盖数据库、录音对象和部署密钥；只复制数据库不构成有效备份。Public deployments require explicit application/API and Device WSS URLs. A valid backup covers the database, recording objects and deployment keys; a database-only copy is not sufficient.

• TLS / WSS通过经过审核的反向代理终止 TLS 1.2+，保留 /device/v1/ws 的 WebSocket Upgrade，并关闭大文件代理缓冲。Terminate TLS 1.2+ at a reviewed reverse proxy, preserve WebSocket Upgrade for /device/v1/ws, and disable proxy buffering for large files.
• BACKUP定期执行 Backup Create 和 Verify；只在服务器停止时恢复到新的空目录，并抽样读取不可变录音验证结果。Run Backup Create and Verify regularly. Restore only while stopped into a new empty directory, then sample an immutable recording.
• UPGRADE先停止或排空服务、验证备份、记录版本与校验信息，再显式执行迁移。不要让两个 SQLite 实例共享同一数据目录。Drain or stop, verify a backup, record versions and checksums, then run migrations explicitly. Never run two SQLite instances against one data directory.
• LOGS / METRICS日志默认滚动并脱敏；将 /metrics 保留在内网、回环地址或 VPN 中，不要直接暴露到公网。Logs rotate and redact secrets by default. Keep /metrics on loopback, a private network or VPN rather than exposing it publicly.