@speclip/pi-speech

面向 Pi 与 Speclip 的工作区安全语音工具包。ASR 默认调用本机 FireRedASR，TTS 默认调用本机 DotsTTS，两者都无需 API Key；同时保留 OpenRouter 与阿里云百炼适配器。每次调用的输入指纹、尝试、请求 ID、用量、估算费用和输出指纹都会记录在工作区中。

V1 能力

• 默认 ASR：本地 fireredasr2-ctc-int8（provider：fireredasr-local，无 API Key、无云端 API 费用）
• 默认 TTS：本地 dots-tts-mf（provider：dotstts-local，无 API Key、无云端 API 费用）
• 本地服务：FireRedASR.app（http://127.0.0.1:8734）与 DotsTTS.app（http://127.0.0.1:7860）
• 可选本地 TTS：dots-tts-soar（偏向质量）
• 可选云端 ASR：OpenRouter openai/whisper-large-v3-turbo
• 可选云端 TTS：OpenRouter fish-audio/s2.1-pro-free:free（免费测试/原型路由）
• 可选供应商：aliyun-bailian，华北 2（北京）
• 工作区相对路径、拒绝目录逃逸和输出覆盖
• 明确拒绝的临时错误最多重试 3 次；结果不明时停止并记录 uncertain
• 供应商返回用量 + 带版本价格快照的费用估算
• 追加式 .speech/generations/ 生成记录

ASR 支持 wav、mp3、opus、aac、m4a，当前统一的工作区快照上限为 10 MiB。本地 ASR adapter 使用 multipart 调用 FireRedASR 的 POST /v1/audio/transcriptions；本地 TTS adapter 在健康与模型检查通过后调用 DotsTTS 的 POST /v1/audio/speech，并开放 speed 与 dots.* 模型控制。pi-speech 的统一 TTS 输出开放 MP3/WAV，OpenRouter TTS 固化为 MP3。实时麦克风、长音频异步转写、说话人分离，以及在 pi-speech 内注册/删除克隆音色不在当前范围内。

OpenRouter 正式模型 ID 带有免费路由后缀 :free。fish-audio/s2.1-pro-free 是模型名称的常见简写，实际请求必须使用 fish-audio/s2.1-pro-free:free。截至 2026-08-25，该 TTS 路由价格为 0，但 OpenRouter 的 STT 目录没有免费模型；可选的 Whisper Turbo ASR 仍可能产生费用。免费模型面向测试、原型和低用量场景，不承诺生产延迟或可用性。

安装与检查

从 npm 安装正式版本：

pi install npm:@speclip/pi-speech

在仓库根目录执行：

npm install
npm run check
pi install ./

要求 Node.js 22.19+ 与 Pi 0.85.x。npm 包本身没有 FFmpeg、模型或平台专属二进制依赖。使用默认本地模型前，需要在 Apple Silicon Mac 上另行安装并启动 FireRedASR.app 与 DotsTTS.app，等待各自面板显示服务和模型均已就绪。模型生命周期、推理运行时和模型文件由两个整合包负责，不会复制进 npm tarball；其他平台可显式选择已配置的云模型。

发布到 npm

发布动作由 GitHub Release 触发。Release 标签必须严格使用 v<package.json version>，例如 package.json 为 0.1.4 时使用 v0.1.4。工作流会检出 Release 标签，依次执行 npm ci、npm run check 和 npm pack --dry-run，全部通过后通过 npm Trusted Publishing（OIDC）发布公开包 @speclip/pi-speech，不读取长期 npm Token。正式 Release 发布到 latest，Prerelease 发布到 next。

在 npm 包设置中一次性配置 Trusted Publisher：

1. Provider 选择 GitHub Actions。
2. Organization/User 填写 linyqh，Repository 填写 pi-speech。
3. Workflow filename 填写 publish.yml，Allowed actions 启用 npm publish。

每次发布前同时更新 package.json 和 package-lock.json 的版本并提交，然后创建标签与版本完全匹配的 GitHub Release。0.1.1 已经发布，不能再次使用相同版本。

配置

本地 FireRedASR 与 DotsTTS 使用固定回环地址，不读取凭证；默认安装无需创建任何 speech 配置文件。选择 OpenRouter 或百炼云端模型时，包只读配置，Speclip 或 CLI 使用者负责写入；凭证文件必须是普通文件、权限 0600，不能是符号链接。

agentDir 由 Pi SDK 的 getAgentDir() 解析，方案与 pi-media 一致：

• 在 Speclip 中，应用通过 PI_CODING_AGENT_DIR 将其指向 ~/.speclip/agent/，凭证路径是 ~/.speclip/agent/speech-credentials.json。
• 在未设置 PI_CODING_AGENT_DIR 的裸 Pi CLI 中，才回退到 ~/.pi/agent/speech-credentials.json。

Speclip 用户应优先在「设置 → Speech」中保存 API Key，不要手工写入 ~/.pi/agent/。

仅使用本地模型时无需 speech-credentials.json。如需云模型，文件示例如下：

{
  "schemaVersion": 1,
  "providers": {
    "openrouter": {
      "type": "api-key",
      "apiKey": "sk-or-..."
    }
  }
}

<agentDir>/speech-config.json：

{
  "schemaVersion": 1,
  "providers": {},
  "defaults": {
    "asr": {
      "provider": "fireredasr-local",
      "model": "fireredasr2-ctc-int8"
    },
    "tts": {
      "provider": "dotstts-local",
      "model": "dots-tts-mf",
      "voice": "default",
      "format": "mp3"
    }
  }
}

两个本地 adapter 都不读取 speech-credentials.json，也不发送 Authorization。FireRedASR 与 DotsTTS 必须分别是 127.0.0.1:8734 和 127.0.0.1:7860 上的无鉴权回环服务。DotsTTS 合成前会检查 /health 与 /v1/models，不会擅自触发多 GB 模型下载；使用已注册克隆音色时，将 DotsTTS 返回的 voice_... ID 传给 speech_synthesize。

当调用方省略 TTS 模型、音色和格式时，工具会优先读取已有 speech-config.json 的 defaults.tts；文件不存在才回退到 dots-tts-mf / default / MP3。配置文件存在但损坏时会显式报错，不会静默忽略保存值。speed 与 dots 仅适用于 DotsTTS，本地参数传给云模型会在调用前被拒绝。

OpenRouter 作为可选云端 provider，只需要 API Key。Base URL 固定为 https://openrouter.ai/api/v1，不接受配置文件覆盖，以免凭证被发送到非预期主机。voice 是 Fish Audio 音色 ID，可替换为该模型支持的其他音色。

阿里云百炼仍可通过工具的模型参数显式选择，也可通过 readAliyunBailianSettings() 和适配器直接使用。百炼默认业务空间只需 API Key；显式子业务空间才增加 workspaceId。备用云供应商的 voice、format 和 sampleRate 保存在其私有 provider 配置中，不会覆盖本地默认值。

Pi 工具

| 工具 | 作用 | | --- | --- | | speech_models | 读取本地及云端模型、计费单位与价格快照，不联网 | | speech_transcribe | 默认通过本机 FireRedASR 转写工作区音频并写入新的 JSON 文件；可显式选择云模型 | | speech_synthesize | 默认通过本机 DotsTTS 合成并固化为新的 MP3/WAV 文件；可显式选择云模型 | | speech_generation_get | 读取一个生成记录 | | speech_generation_list | 按类型、状态读取生成历史 |

本地模型的目录项使用 catalogVersion: "local"、单价 0，表示没有云端 provider API 费用，不代表设备电力等本地运行成本为零。云端价格只是以记录中 catalogVersion 为准的估算值，不是 OpenRouter 或上游供应商最终账单。API Key 不会写入生成记录。

FireRedASR 接口字段、响应映射和错误语义见 docs/fireredasr-local.md。

DotsTTS 接口字段、模型/音色边界和错误语义见 docs/dotstts-local.md。

Speclip 对接契约见 docs/speclip-integration.md。