feishu-voice-bridge 2026.3.31

package/.env.example

@@ -0,0 +1,21 @@
+# 说明：
+# 1. 该文件只作为变量清单示例，不会被插件自动加载。
+# 2. 请通过 shell、launchd、CI Secret 或 OpenClaw 本地配置注入真实值。
+# 3. 不要把真实密钥提交到仓库。
+
+FEISHU_APP_ID=your_feishu_app_id
+FEISHU_APP_SECRET=your_feishu_app_secret
+FEISHU_CHAT_ID=ou_or_oc_target_id
+
+# 可选：覆盖 OpenClaw 本地配置文件路径
+OPENCLAW_JSON=/path/to/openclaw.json
+
+# 可选：语音转写默认参数
+OPENCLAW_STT_LANGUAGE=zh-CN
+OPENCLAW_STT_MODEL=small
+
+# 可选：Whisper 运行参数
+WHISPER_MODEL=small
+WHISPER_MODEL_DIR=/path/to/whisper-models
+WHISPER_BEAM_SIZE=5
+WHISPER_BEST_OF=5

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# 更新日志
+
+## 2026.3.31
+
+### 原生能力对齐重构
+
+- 重构插件内部结构，拆分为运行时探测、会话路由、状态存储、回复分发、文本清洗、摘要处理等独立模块。
+- 自动语音回复继续优先复用 OpenClaw 原生 `messages.tts` 链路。
+- 长文本语音回复摘要调整为“原生摘要优先，规则摘要兜底”模式。
+- 飞书入站语音转写现在优先调用 OpenClaw 原生 `api.runtime.stt.transcribeAudioFile(...)`。
+- 原生 TTS / STT 不可用时，仍保留脚本兜底能力。
+- 继续跳过 emoji、Markdown、代码块等不适合语音朗读的内容。
+- 增加运行时能力探测日志，便于确认当前是否命中 native TTS / STT / summary。
+- 修复发布清单，确保打包时包含 `lib/` 与相关运行文件。
+- 补充 README 与回归测试，`npm test`、`npm run check` 均已通过。
+
+### 早期更新
+
+- 新增长文本语音摘要能力，避免超长回复被直接截断。
+- 补充 `maxCapturedReplyChars` 与 `voiceReplySummary*` 相关配置项。
+- 将项目内介绍性文档、注释和插件描述统一为中文。
+- 补齐插件项目基础文件：`package.json`、`.gitignore`、`LICENSE`、`CHANGELOG.md`。

package/CONTRIBUTING.md

@@ -0,0 +1,57 @@
+# 贡献指南
+
+感谢你参与维护 `feishu-voice-bridge`。
+
+## 开发原则
+
+- 优先遵循 OpenClaw 官方插件机制，不修改渠道插件核心实现。
+- 飞书特有逻辑尽量收敛在本插件内部。
+- 文本、语音和最终用户可见回复必须尽量保持一致。
+- 新增能力时，优先补测试，再补实现。
+
+## 本地开发
+
+### 环境要求
+
+- Node.js 20 及以上
+- `ffmpeg`
+- `edge-tts`
+- `whisper`
+
+### 常用命令
+
+```bash
+npm test
+npm run check
+```
+
+## 提交规范
+
+- 文档、配置、代码和测试尽量同一批次提交，避免上下文割裂。
+- 如果改动影响语音发送策略，请同步更新 `README.md` 和 `CHANGELOG.md`。
+- 如果新增配置项，请同步更新：
+  - `openclaw.plugin.json`
+  - `README.md`
+  - 对应测试
+
+## 敏感信息要求
+
+- 不要提交真实的 `appId`、`appSecret`、token、聊天标识或任何其他生产凭证。
+- `.env.example` 只保留变量名和占位值，不写入真实配置。
+- 如果需要展示日志，请先脱敏 `Authorization`、`tenant_access_token`、`file_key` 等字段。
+
+## 测试要求
+
+- 修改 `index.js` 中的桥接逻辑后，至少运行一次 `npm test`。
+- 修改脚本参数或帮助文本后，检查 `README.md` 中的示例是否仍然准确。
+- 如果修复的是飞书语音时序问题，建议补一条对应的回归测试。
+
+## 发布前检查
+
+发布前建议确认以下事项：
+
+1. `npm test` 通过。
+2. `README.md` 中的配置示例与当前实现一致。
+3. `openclaw.plugin.json` 中的配置 schema 已同步更新。
+4. `CHANGELOG.md` 已记录本次版本变化。
+5. 需要的 git tag 已创建。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alpar Wen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,308 @@
+# 飞书语音桥接插件
+
+`feishu-voice-bridge` 是一个 OpenClaw 原生插件，用于：
+
+1. 注册 `feishu-voice` TTS provider
+2. 注册飞书语音转写 provider
+3. 在飞书场景把最终文本回复补发为语音消息
+
+## 安装
+
+推荐方式：
+
+```bash
+git clone git@github.com:alpar/feishu-voice-bridge.git ~/feishu-voice-bridge
+openclaw plugins install ~/feishu-voice-bridge
+```
+
+开发场景也可以 link：
+
+```bash
+openclaw plugins install -l ~/feishu-voice-bridge
+```
+
+如果你不走 `openclaw plugins install`，而是手动复制到默认扩展目录，推荐放在：
+
+```bash
+~/.openclaw/extensions/feishu-voice-bridge
+```
+
+安装后可检查：
+
+```bash
+openclaw plugins info feishu-voice-bridge
+```
+
+## 依赖安装
+
+系统依赖：
+
+```bash
+yum install -y ffmpeg       # CentOS / OpenCloudOS
+apt-get install -y ffmpeg   # Ubuntu / Debian
+brew install ffmpeg         # macOS
+```
+
+Python 依赖：
+
+```bash
+python3 -m pip install edge-tts
+python3 -m pip install openai-whisper  # 可选
+```
+
+依赖检查：
+
+```bash
+python3 --version
+ffmpeg -version
+ffprobe -version
+edge-tts --help >/dev/null && echo "edge-tts ok"
+whisper --help >/dev/null && echo "whisper ok"  # 可选
+```
+
+脚本链路检查：
+
+```bash
+cd ~/feishu-voice-bridge
+bash scripts/send_voice.sh -t "这是一条测试语音" --no-send -o /tmp/feishu-voice-test.opus
+test -f /tmp/feishu-voice-test.opus && echo "tts script ok"
+```
+
+如果你使用的是复制安装，也可以进入：
+
+```bash
+cd ~/.openclaw/extensions/feishu-voice-bridge
+```
+
+如安装了 Whisper，可继续测试：
+
+```bash
+bash scripts/openclaw_stt.sh /tmp/feishu-voice-test.opus
+```
+
+## 配置
+
+OpenClaw 配置文件通常位于：
+
+```bash
+~/.openclaw/openclaw.json
+```
+
+必填配置只有两部分：
+
+1. `channels.feishu.*`
+2. `plugins.entries.feishu-voice-bridge.*`
+
+`messages.tts.*` 是可选增强配置。
+
+### 最小可运行配置
+
+这是推荐默认示例，和你当前使用方式一致：
+
+```json5
+{
+  channels: {
+    feishu: {
+      appId: "cli_xxxxxxxxxxxxx",
+      appSecret: "xxxxxxxxxxxxx"
+    }
+  },
+  messages: {
+    tts: false
+  },
+  plugins: {
+    entries: {
+      "feishu-voice-bridge": {
+        enabled: true,
+        config: {
+          voiceReplyEnabled: true,
+          voiceReplyMode: "inbound",
+          voiceReplyWindowMs: 1200000,
+          voiceReplyCooldownMs: 30000,
+          voiceReplyDebounceMs: 2500,
+          maxReplyChars: 280,
+          maxCapturedReplyChars: 6000,
+          voiceReplySummaryEnabled: true,
+          voiceReplySummaryMaxSentences: 3
+        }
+      }
+    }
+  }
+}
+```
+
+说明：
+
+- `messages.tts: false` 是合法配置
+- 插件仍可工作，并使用自己的脚本完成语音合成
+- 超长文本仍会走插件内置摘要逻辑
+
+### 可选：启用原生 TTS 复用
+
+如果你希望优先复用 OpenClaw 原生 TTS / 摘要模型，把上面的 `messages.tts` 改成：
+
+```json5
+{
+  messages: {
+    tts: {
+      provider: "edge",
+      mode: "final",
+      auto: "off",
+      summaryModel: "openai/gpt-4.1-mini",
+      providers: {
+        microsoft: {
+          voice: "zh-CN-XiaoxiaoNeural",
+          rate: "+20%",
+          pitch: "0"
+        }
+      }
+    }
+  }
+}
+```
+
+注意：
+
+- `messages.tts: false` 和 `messages.tts: {...}` 二选一
+- 不需要原生 TTS 复用时，保持 `messages.tts: false` 即可
+
+### 常用插件配置
+
+```json5
+{
+  plugins: {
+    entries: {
+      "feishu-voice-bridge": {
+        enabled: true,
+        config: {
+          defaultVoice: "zh-CN-XiaoxiaoNeural",
+          defaultRate: "+20",
+          defaultPitch: "0",
+          voiceReplySummaryPrefix: "语音摘要：",
+          voiceReplySummarySuffix: "（完整内容请查看文字回复）",
+          promptToolTtsForText: false
+        }
+      }
+    }
+  }
+}
+```
+
+常用字段：
+
+- `voiceReplyEnabled`：是否启用自动语音回复
+- `voiceReplyMode`：`inbound` / `always` / `off`
+- `voiceReplyWindowMs`：最近一次飞书入站消息后的语音回复窗口
+- `voiceReplyCooldownMs`：两次自动语音回复最小间隔
+- `voiceReplyDebounceMs`：等待文本稳定后再发送
+- `maxReplyChars`：最终朗读文本上限
+- `maxCapturedReplyChars`：摘要前缓存文本上限
+- `voiceReplySummaryEnabled`：长文本是否改为摘要朗读
+- `voiceReplySummaryMaxSentences`：摘要最多保留几句
+
+如果没有配置 `channels.feishu.appId` 或 `channels.feishu.appSecret`，插件即使已加载，也无法发送飞书语音。
+
+## 生效
+
+修改配置后重启：
+
+```bash
+openclaw gateway restart
+```
+
+## 验证
+
+先做本地自检：
+
+```bash
+cd ~/feishu-voice-bridge
+npm run check
+npm test
+```
+
+如果你使用的是复制安装，也可以在 `~/.openclaw/extensions/feishu-voice-bridge` 下执行。
+
+再确认插件已加载：
+
+```bash
+openclaw plugins info feishu-voice-bridge
+```
+
+重点看：
+
+- 插件状态为已加载
+- `speech` 中有 `feishu-voice`
+- `media-understanding` 中有 `feishu-voice`
+- 如果你是直接手动放入扩展目录、但没有通过 `openclaw plugins install` 建立安装记录，看到 `loaded without install/load-path provenance` 警告是正常的
+- 如果你使用的是 `openclaw plugins install -l <path>`，通常应由 `plugins.load.paths` 管理，不建议把它和上面的警告视为同一种情况
+
+## 功能测试
+
+建议按顺序测试：
+
+1. 发一条飞书语音给机器人
+2. 确认能转写并正常回文本
+3. 确认插件额外补发了一条飞书语音
+4. 发一条超长问题，确认语音读的是摘要
+5. 发一条包含 emoji 的文本，确认语音会跳过 emoji
+
+`voiceReplyMode: "inbound"` 下，自动语音回复只会在最近一次飞书入站消息后的窗口内触发。
+
+## 常见问题
+
+- 拉了代码但没执行 `openclaw plugins install <path>`
+- 插件未正确安装，或源码目录没有通过 `plugins.load.paths` 加入加载路径
+- 没配置 `channels.feishu.appId` / `channels.feishu.appSecret`
+- 改完配置没有重启 Gateway
+- 本机缺少 `ffmpeg` / `ffprobe` / `edge-tts`
+- 误以为 `.env.example` 会被自动加载
+
+## 排查
+
+建议按这个顺序排查：
+
+```bash
+cd ~/feishu-voice-bridge
+npm run check
+npm test
+openclaw plugins info feishu-voice-bridge
+```
+
+如果你使用的是复制安装，也可以改为进入 `~/.openclaw/extensions/feishu-voice-bridge` 后执行。
+
+如果还不对，再执行：
+
+```bash
+openclaw status --all
+```
+
+再看日志关键词：
+
+- `runtime ready: nativeTts=...`
+- `feishu-voice synthesized via OpenClaw TTS`
+- `feishu-voice transcribed via OpenClaw runtime`
+- `feishu-voice auto reply sent`
+- `feishu-voice skip auto reply: ...`
+
+## 安全说明
+
+插件运行时读取的是：
+
+- `channels.feishu.appId`
+- `channels.feishu.appSecret`
+
+手工调用 `scripts/send_voice.sh` 时，还会读取：
+
+- `FEISHU_APP_ID`
+- `FEISHU_APP_SECRET`
+- `FEISHU_CHAT_ID`
+- `OPENCLAW_JSON`
+
+不要把真实密钥、token、聊天标识提交进仓库。
+
+## 开发命令
+
+```bash
+npm run check
+npm test
+```

package/index.js

@@ -0,0 +1,39 @@
+"use strict";
+
+const { resolvePluginConfig } = require("./lib/config");
+const { loadGeneratedAudioArtifact } = require("./lib/audio");
+const { createPluginRuntime, logRuntimeReadiness } = require("./lib/runtime");
+const {
+  extractAssistantTextFromAgentMessage,
+  extractMessageSentText,
+  mergeVoiceReplyCandidate,
+  prepareVoiceReplyText
+} = require("./lib/text");
+const { buildMediaUnderstandingProvider, buildProvider } = require("./lib/providers");
+const { registerVoiceReplyHooks } = require("./lib/voice-reply-hooks");
+
+// 入口文件只负责组装插件，复杂逻辑拆到 lib/ 下，便于后续单独维护和测试。
+const plugin = {
+  id: "feishu-voice-bridge",
+  name: "飞书语音桥接插件（STT + TTS）",
+  description: "OpenClaw 原生飞书语音桥接插件，提供本地 STT、TTS 与官方语音链路兼容能力。",
+  register(api) {
+    const cfg = resolvePluginConfig(api);
+    cfg.runtime = createPluginRuntime(cfg, api.runtime || null);
+    logRuntimeReadiness(cfg.runtime, api.logger);
+    api.registerSpeechProvider(buildProvider(cfg, api.logger, cfg.runtime));
+    api.registerMediaUnderstandingProvider(buildMediaUnderstandingProvider(cfg, api.logger, cfg.runtime));
+    registerVoiceReplyHooks(api, cfg);
+  }
+};
+
+module.exports = plugin;
+module.exports.default = plugin;
+module.exports.__private = {
+  extractAssistantTextFromAgentMessage,
+  extractMessageSentText,
+  loadGeneratedAudioArtifact,
+  mergeVoiceReplyCandidate,
+  prepareVoiceReplyText,
+  registerVoiceReplyHooks
+};