Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

docs(desktop): document speech adapter and registry follow-ups

JiangJiahaoda4c5b2192d5
diff --git a/apps/desktop/src/main/voice-conversation/models.ts b/apps/desktop/src/main/voice-conversation/models.ts
index 4fc5b5292d..e7f7c44d6f 100644
--- a/apps/desktop/src/main/voice-conversation/models.ts
+++ b/apps/desktop/src/main/voice-conversation/models.ts
@@ -41,6 +41,13 @@ function apiBase(raw: string): URL | null {
}
}
+/**
+ * Future Registry protocol/parameter metadata must describe the actual provider/model
+ * route, not a model family. Coordinate server declarations, client validation and the
+ * bundled copy; metadata alone neither installs an executor nor grants model access.
+ * Preserve undefined/null and explicit user-choice semantics during that migration.
+ * See docs/product-rules/companion-voice-mode.md, "后续扩展计划".
+ */
function nativeProtocol(catalog: Catalog, providerId: string, model: ProviderMediaModel) {
const declared =
model.nativeApi !== undefined
diff --git a/apps/desktop/src/main/voice-conversation/speechProtocols.ts b/apps/desktop/src/main/voice-conversation/speechProtocols.ts
index 593e5e3466..a30bd3f64c 100644
--- a/apps/desktop/src/main/voice-conversation/speechProtocols.ts
+++ b/apps/desktop/src/main/voice-conversation/speechProtocols.ts
@@ -8,6 +8,12 @@ export type SpeechConnection = {
};
export type SpeechInput = { modelId: string; voice: string; text: string };
+/**
+ * Follow-up before adding more native protocols: extract these branches and response
+ * decoders into protocol adapters, with shared UI/Main parameter validation and a
+ * common audio/completion/cancellation contract. Keep wire serialization in code.
+ * See docs/product-rules/companion-voice-mode.md, "后续扩展计划".
+ */
export function speechRequest(
connection: SpeechConnection,
input: SpeechInput,
diff --git a/docs/product-rules/companion-voice-mode.md b/docs/product-rules/companion-voice-mode.md
index 79c4dcb50c..b6c58773b7 100644
--- a/docs/product-rules/companion-voice-mode.md
+++ b/docs/product-rules/companion-voice-mode.md
@@ -42,6 +42,17 @@
原生接口依据:[ElevenLabs stream](https://elevenlabs.io/docs/api-reference/text-to-speech/stream)、[MiniMax HTTP TTS](https://platform.minimax.io/docs/api-reference/speech-t2a-http)。响应有类型、大小、超时和完整性检查,重定向被拒绝,上游原始错误不穿过 IPC。流式传输与插话取消共用原有代次检查和播放背压,不增加音频落盘。
+## 后续扩展计划
+
+以下为后续演进方向,本 PR 尚未实现适配器拆分、统一参数描述或公共 Registry schema 扩展,也不包含 Qwen / CosyVoice 原生执行器。
+
+- **独立协议适配器**:接入更多原生协议时,先将现有 OpenAI 兼容、ElevenLabs、MiniMax 分支及响应解码整理为独立的 TypeScript 适配器。适配器负责各协议的请求序列化、传输及响应解析;公共层统一音频格式、完成、错误与取消合同,继续复用账号/任务绑定、读取背压、资源上限和迟到音频丢弃,不增加第二套伙伴任务或播放状态机。Qwen / CosyVoice 按所接具体 API 的 HTTP、SSE 或 WebSocket 合同实现,不能只替换 URL。
+- **统一参数定义与校验**:用共享的类型化参数描述约定必填项、默认值、枚举、范围和错误语义,让 Renderer 表单与 Main 校验复用同一规则;Main 在执行前再次校验。音色及后续语速、语言等参数按实际协议和型号能力开放,各厂商字段映射仍由适配器负责。当前固定输出格式和参数限制需在迁移时保留,新增能力以适配器实际实现及验证为准。
+- **公共 Registry 扩展**:后续可补充已验证的原生协议标识、型号支持的参数与限制、资料来源。声明须对应实际供应商/型号路由:同一型号通过原厂端点与兼容 Gateway 接入时,协议可以不同;不能从品牌、型号名称或 `audio_speech` 推断。Registry 负责描述能力,协议执行继续保留在代码中,不引入远端 JSON 请求模板或脚本执行机制。
+- **正本与兼容性**:新增公共字段或协议枚举时,协调更新 cindy-server 正本、客户端 Bean/解析与校验、客户端离线副本及相应契约测试;按既有 schema/能力协商兼容旧客户端。保留未声明与显式 `null` 的区别及用户显式覆盖语义,未知协议不能因此成为已支持协议。分别记录客户端支持、服务端实现与生产部署状态;目录资料不新增用户可访问的模型、授权或执行路由。
+- **配置存储延续**:API base 和密钥继续复用已有供应商连接与凭证存储,伙伴模型、音色等偏好继续使用现有账号隔离的本地设置,不额外创建通用协议配置文件。若后续把接口覆盖从伙伴偏好调整为连接/型号路由配置,须兼容并保留已有显式选择,不能静默覆盖或丢失设置。
+- **扩展验收**:每个新适配器需覆盖参数错误、流式完成、业务错误、取消与迟到数据,再用真实供应商验证型号、音色和连续语音体验。新增 Registry 条目或测试替身通过均不能替代真实执行验收。
+
## 验证
自动化覆盖分段去重、乱序完成、空转写、连接轮换、权限与账号边界、取消启动、插话抢占、迟到音频、PCM 字节边界、回复关联、无模型空状态及现有 ASR 回归。BYOK 回归覆盖接口请求、SSE 断帧与结束聚合包、连接/密钥隔离、停用与账号切换、伙伴偏好重开与重置、未知接口须用户选择,以及合成失败不换供应商、不重发消息。