@mingxy/ocosay 1.0.2 → 1.0.4

package/TECH_PLAN.md

@@ -1,352 +0,0 @@
-# ocosay - OpenCode TTS 播放插件技术方案
-
-## 项目概述
-
-**ocosay** 是 OpenCode 的 TTS（文本转语音）播放插件，支持：
-- 文本转语音自动播放
-- 暂停/停止/恢复控制
-- 多 TTS 模型可扩展架构
-- 同步/异步/流式 多种合成模式
-
-## 架构设计
-
-### 核心原则
-- **可扩展架构**：抽象 TTS Provider 接口，MiniMax 作为第一个实现，未来可扩展其他提供商
-- **Provider 隔离**：每个 TTS 模型独立 Provider 实现，核心逻辑与模型无关
-- **合成模式可配置**：通过 `model` 参数指定 `sync` | `async` | `stream`
-
-### 目录结构
-
-```
-ocosay/
-├── src/
-│   ├── providers/
-│   │   ├── base.ts           # TTS Provider 接口定义
-│   │   ├── minimax.ts         # MiniMax TTS Provider
-│   │   └── index.ts          # Provider 导出
-│   ├── core/
-│   │   ├── player.ts         # 音频播放引擎
-│   │   ├── speaker.ts        # 统一调用入口
-│   │   └── types.ts          # 公共类型定义
-│   ├── tools/
-│   │   └── tts.ts            # OpenCode 自定义工具
-│   ├── index.ts              # Plugin 入口
-│   └── config.ts             # 配置管理
-├── package.json
-├── tsconfig.json
-└── README.md
-```
-
----
-
-## 核心接口设计
-
-### 错误类型
-
-```typescript
-// 错误类型定义
-enum TTSErrorCode {
-  NETWORK = 'NETWORK',
-  AUTH = 'AUTH',
-  QUOTA = 'QUOTA',
-  INVALID_VOICE = 'INVALID_VOICE',
-  INVALID_PARAMS = 'INVALID_PARAMS',
-  PLAYER_ERROR = 'PLAYER_ERROR',
-  UNKNOWN = 'UNKNOWN'
-}
-
-class TTSError extends Error {
-  constructor(
-    message: string,
-    code: TTSErrorCode,
-    provider: string,
-    details?: unknown
-  ) {
-    super(message)
-    this.name = 'TTSError'
-    this.code = code
-    this.provider = provider
-    this.details = details
-  }
-  
-  code: TTSErrorCode
-  provider: string
-  details?: unknown
-}
-```
-
-### 音色定义
-
-```typescript
-interface Voice {
-  id: string
-  name: string
-  language?: string  // 'zh-CN' | 'en-US' 等
-  gender?: 'male' | 'female' | 'neutral'
-  previewUrl?: string  // 音色预览 URL
-}
-```
-
-### 能力定义
-
-```typescript
-interface TTSCapabilities {
-  // 基础能力（必有）
-  speak: true
-  
-  // 高级能力
-  voiceClone?: boolean   // 音色克隆支持
-  stream?: boolean       // 流式合成支持
-  voiceList?: boolean    // 音色列表支持
-  
-  // 合成模式支持
-  sync?: boolean         // 同步合成支持
-  async?: boolean        // 异步合成支持
-}
-```
-
-### 合成配置
-
-```typescript
-// 合成模式枚举
-type SynthesisModel = 'sync' | 'async' | 'stream'
-
-// Speak 配置参数
-interface SpeakOptions {
-  voice?: string                    // 音色 ID
-  model?: SynthesisModel           // 合成模式，默认 stream
-  speed?: number                   // 语速 0.5-2.0
-  volume?: number                  // 音量 0-100
-  pitch?: number                   // 音调 0.5-2.0
-  
-  // 音色克隆参数（可选）
-  sourceVoice?: string             // 克隆源音色 URL
-}
-
-interface AudioResult {
-  audioData: Buffer | ReadableStream
-  sampleRate?: number
-  channels?: number
-  duration?: number
-  format: string  // 'mp3' | 'wav' | 'flac'
-  isStream: boolean
-}
-```
-
-### TTSProvider 接口
-
-```typescript
-interface TTSProvider {
-  name: string
-  capabilities: TTSCapabilities
-  
-  // 生命周期
-  initialize(): Promise<void>
-  destroy(): Promise<void>
-  
-  // 核心能力
-  speak(text: string, options?: SpeakOptions): Promise<AudioResult>
-  pause(): Promise<void>
-  resume(): Promise<void>
-  stop(): Promise<void>
-  listVoices(): Promise<Voice[]>
-  
-  // 查询能力
-  getCapabilities(): TTSCapabilities
-}
-```
-
-### Provider 注册机制
-
-```typescript
-// 静态注册
-const providers = new Map<string, TTSProvider>()
-
-export function registerProvider(name: string, provider: TTSProvider): void {
-  providers.set(name, provider)
-}
-
-export function getProvider(name: string): TTSProvider {
-  const provider = providers.get(name)
-  if (!provider) {
-    throw new TTSError(
-      `TTS Provider "${name}" not found`,
-      TTSErrorCode.UNKNOWN,
-      'system'
-    )
-  }
-  return provider
-}
-
-export function listProviders(): string[] {
-  return Array.from(providers.keys())
-}
-
-export function hasProvider(name: string): boolean {
-  return providers.has(name)
-}
-```
-
----
-
-## 事件系统
-
-```typescript
-// 事件类型
-type TTSEvent = 
-  | 'start'      // 开始播放
-  | 'end'        // 播放结束
-  | 'error'      // 错误发生
-  | 'progress'  // 播放进度（流式场景）
-  | 'pause'      // 暂停
-  | 'resume'     // 恢复
-  | 'stop'       // 停止
-
-// 事件处理器
-interface SpeakerEvents {
-  on(event: 'start', handler: (text: string) => void): void
-  on(event: 'end', handler: (text: string) => void): void
-  on(event: 'error', handler: (error: TTSError) => void): void
-  on(event: 'progress', handler: (progress: { current: number; total: number }) => void): void
-  on(event: 'pause', handler: () => void): void
-  on(event: 'resume', handler: () => void): void
-  on(event: 'stop', handler: () => void): void
-  
-  off(event: TTSEvent, handler: Function): void
-}
-```
-
----
-
-## OpenCode Plugin 集成
-
-```typescript
-// src/index.ts
-export default {
-  name: 'ocosay',
-  version: '1.0.0',
-  
-  tools: [
-    {
-      name: 'tts_speak',
-      description: '将文本转换为语音并播放',
-      input: {
-        text: { type: 'string', required: true },
-        provider: { type: 'string', default: 'minimax' },
-        voice: { type: 'string', optional: true },
-        model: { type: 'string', enum: ['sync', 'async', 'stream'], default: 'stream' },
-        speed: { type: 'number', optional: true },
-        volume: { type: 'number', optional: true },
-        pitch: { type: 'number', optional: true }
-      }
-    },
-    {
-      name: 'tts_stop',
-      description: '停止当前播放'
-    },
-    {
-      name: 'tts_pause',
-      description: '暂停当前播放'
-    },
-    {
-      name: 'tts_resume',
-      description: '恢复暂停的播放'
-    },
-    {
-      name: 'tts_list_voices',
-      description: '列出可用音色',
-      input: {
-        provider: { type: 'string', default: 'minimax' }
-      }
-    },
-    {
-      name: 'tts_list_providers',
-      description: '列出所有已注册的 TTS 提供商'
-    }
-  ],
-  
-  session: {
-    idle: () => { /* 清理资源 - 调用所有 Provider.destroy() */ }
-  }
-}
-```
-
----
-
-## MiniMax Provider 实现
-
-### API 能力映射
-
-| MiniMax API | 映射到 ocosay | 说明 |
-|-------------|--------------|------|
-| T2A v2.5 (WebSocket) | `model: 'stream'` | 流式播放 |
-| T2A v3 (同步) | `model: 'sync'` | 同步返回 |
-| T2A v2 (异步) | `model: 'async'` | 异步轮询 |
-| 音色列表 | `listVoices()` | |
-| 音色克隆 | `voiceClone()` (via sourceVoice) | 通过 sourceVoice 参数指定克隆源 |
-
-### 配置项
-
-```typescript
-interface MiniMaxConfig {
-  apiKey: string
-  appId?: string
-  voiceId?: string           // 默认音色
-  model?: SynthesisModel     // 默认合成模式
-  audioFormat?: 'mp3' | 'wav' | 'flac'
-  speed?: number            // 0.5 - 2.0
-  volume?: number           // 0 - 100
-  pitch?: number            // 0.5 - 2.0
-}
-
-function validateConfig(config: MiniMaxConfig): void {
-  if (!config.apiKey) {
-    throw new TTSError('API key is required', TTSErrorCode.AUTH, 'minimax')
-  }
-  if (config.speed !== undefined && (config.speed < 0.5 || config.speed > 2.0)) {
-    throw new TTSError('Speed must be between 0.5 and 2.0', TTSErrorCode.INVALID_PARAMS, 'minimax')
-  }
-  if (config.volume !== undefined && (config.volume < 0 || config.volume > 100)) {
-    throw new TTSError('Volume must be between 0 and 100', TTSErrorCode.INVALID_PARAMS, 'minimax')
-  }
-}
-```
-
----
-
-## 评审修复记录
-
-| 日期 | 修复内容 | 评审来源 |
-|------|---------|---------|
-| 2026-04-04 | speak() 添加 SpeakOptions 配置参数 | 萍萍 |
-| 2026-04-04 | pause()/stop()/resume() 改为返回 Promise | 凤雏 |
-| 2026-04-04 | 添加 TTSError 类型定义 | 凤雏 |
-| 2026-04-04 | 同步/异步/流式 改为 model 参数可配置 | 老爷确认 |
-| 2026-04-04 | 添加 Speaker 事件系统 | 小猪 |
-| 2026-04-04 | 添加 listProviders() 方法 | 萍萍 |
-| 2026-04-04 | 添加 Provider 生命周期 initialize()/destroy() | 凤雏 |
-
----
-
-## 技术栈
-
-- **语言**: TypeScript
-- **运行时**: Node.js
-- **音频播放**: node-simplespeaker / node-player / play-sound
-- **HTTP 客户端**: axios
-- **WebSocket**: ws (for MiniMax 流式)
-- **构建**: npm
-
-## 下一步计划
-
-1. 创建项目结构
-2. 实现 types.ts - 核心类型定义
-3. 实现 base.ts - Provider 接口
-4. 实现 config.ts - 配置管理
-5. 实现 MiniMax Provider
-6. 实现 player.ts - 音频播放引擎
-7. 实现 speaker.ts - 统一调用入口
-8. 实现 tools/tts.ts - OpenCode 工具
-9. 实现 index.ts - Plugin 入口
-10. 单元测试
-11. 文档编写

package/__mocks__/@opencode-ai/plugin.ts

@@ -1,32 +0,0 @@
-const schema = {
-  string: () => ({
-    describe: (desc: string) => ({ describe: desc }),
-    optional: () => ({
-      describe: (desc: string) => ({ describe: desc })
-    }),
-    number: () => ({
-      describe: (desc: string) => ({ describe: desc }),
-      optional: () => ({
-        describe: (desc: string) => ({ describe: desc })
-      })
-    }),
-    enum: (values: string[]) => ({
-      describe: (desc: string) => ({ describe: desc }),
-      optional: () => ({
-        describe: (desc: string) => ({ describe: desc })
-      })
-    })
-  })
-}
-
-function tool({ description, args, execute }: any) {
-  return {
-    description,
-    args,
-    execute,
-    schema
-  }
-}
-
-export { tool, schema }
-export const Plugin = jest.fn()

package/jest.config.js

@@ -1,15 +0,0 @@
-export default {
-  preset: 'ts-jest',
-  testEnvironment: 'node',
-  roots: ['<rootDir>/tests', '<rootDir>/src'],
-  testMatch: ['**/*.test.ts'],
-  moduleFileExtensions: ['ts', 'js', 'json'],
-  collectCoverageFrom: ['src/**/*.ts'],
-  coverageDirectory: 'coverage',
-  transform: {
-    '^.+\\.tsx?$': ['ts-jest', { 
-      useESM: true
-    }]
-  },
-  extensionsToTreatAsEsm: ['.ts']
-}

package/src/config.ts

@@ -1,149 +0,0 @@
-import * as fs from 'fs'
-import * as path from 'path'
-import * as os from 'os'
-import type { OcosayConfig } from './types/config'
-import { DEFAULT_CONFIG } from './types/config'
-
-const CONFIG_PATH = path.join(os.homedir(), '.config', 'opencode', 'ocosay.jsonc')
-
-export function generateDefaultConfig(): OcosayConfig {
-  return {
-    ...DEFAULT_CONFIG,
-    providers: {
-      minimax: {
-        apiKey: '',
-        baseURL: '',
-        voiceId: '',
-        model: 'stream',
-        ttsModel: 'speech-2.8-hd',
-        audioFormat: 'mp3'
-      }
-    }
-  }
-}
-
-export function stripComments(jsonc: string): string {
-  let result = ''
-  let inString = false
-  let stringChar = ''
-  let i = 0
-
-  while (i < jsonc.length) {
-    const char = jsonc[i]
-
-    if (!inString && (char === '"' || char === "'" || char === '`')) {
-      inString = true
-      stringChar = char
-      result += char
-      i++
-      continue
-    }
-
-    if (inString && char === stringChar && jsonc[i - 1] !== '\\') {
-      inString = false
-      result += char
-      i++
-      continue
-    }
-
-    if (inString) {
-      result += char
-      i++
-      continue
-    }
-
-    if (char === '/' && jsonc[i + 1] === '/') {
-      while (i < jsonc.length && jsonc[i] !== '\n') {
-        i++
-      }
-      continue
-    }
-
-    if (char === '/' && jsonc[i + 1] === '*') {
-      i += 2
-      while (i < jsonc.length - 1 && !(jsonc[i] === '*' && jsonc[i + 1] === '/')) {
-        i++
-      }
-      i += 2
-      continue
-    }
-
-    result += char
-    i++
-  }
-
-  return result
-}
-
-export function mergeWithDefaults(
-  loaded: Partial<OcosayConfig>,
-  defaults: Omit<OcosayConfig, 'providers'>
-): Omit<OcosayConfig, 'providers'> {
-  return {
-    enabled: loaded.enabled ?? defaults.enabled,
-    autoPlay: loaded.autoPlay ?? defaults.autoPlay,
-    autoRead: loaded.autoRead ?? defaults.autoRead,
-    streamMode: loaded.streamMode ?? defaults.streamMode,
-    streamBufferSize: loaded.streamBufferSize ?? defaults.streamBufferSize,
-    streamBufferTimeout: loaded.streamBufferTimeout ?? defaults.streamBufferTimeout,
-    speed: loaded.speed ?? defaults.speed,
-    volume: loaded.volume ?? defaults.volume,
-    pitch: loaded.pitch ?? defaults.pitch
-  }
-}
-
-export function loadOrCreateConfig(): OcosayConfig {
-  const configDir = path.dirname(CONFIG_PATH)
-
-  if (!fs.existsSync(configDir)) {
-    try {
-      fs.mkdirSync(configDir, { recursive: true })
-    } catch (err) {
-      throw new Error(`[ocosay] 无法创建配置目录 ${configDir}: ${err}`)
-    }
-  }
-
-  if (!fs.existsSync(CONFIG_PATH)) {
-    console.info('[ocosay] 配置文件不存在，正在创建默认配置...')
-    const defaultConfig = generateDefaultConfig()
-    const configContent = JSON.stringify(defaultConfig, null, 2)
-    try {
-      fs.writeFileSync(CONFIG_PATH, configContent, 'utf-8')
-      try {
-        fs.chmodSync(CONFIG_PATH, 0o600)
-      } catch (err) {
-        console.warn(`[ocosay] 无法设置配置文件权限: ${err}`)
-      }
-    } catch (err) {
-      throw new Error(`[ocosay] 无法写入配置文件 ${CONFIG_PATH}: ${err}`)
-    }
-    console.info(`[ocosay] 配置文件已创建: ${CONFIG_PATH}`)
-    console.info('[ocosay] 请编辑配置文件填入 API Key 和 Base URL')
-    return defaultConfig
-  }
-
-  try {
-    const content = fs.readFileSync(CONFIG_PATH, 'utf-8')
-    const stripped = stripComments(content)
-    const loaded = JSON.parse(stripped) as Partial<OcosayConfig>
-
-    const merged = mergeWithDefaults(loaded, DEFAULT_CONFIG)
-
-    return {
-      ...merged,
-      providers: {
-        minimax: {
-          apiKey: loaded.providers?.minimax?.apiKey ?? '',
-          baseURL: loaded.providers?.minimax?.baseURL ?? '',
-          voiceId: loaded.providers?.minimax?.voiceId ?? '',
-          model: loaded.providers?.minimax?.model ?? 'stream',
-          ttsModel: loaded.providers?.minimax?.ttsModel ?? 'speech-2.8-hd',
-          audioFormat: loaded.providers?.minimax?.audioFormat ?? 'mp3'
-        }
-      }
-    }
-  } catch (error) {
-    console.error('[ocosay] 配置文件读取失败，使用默认配置:', error)
-    return generateDefaultConfig()
-  }
-}

package/src/core/backends/afplay-backend.ts

@@ -1,162 +0,0 @@
-/**
- * Afplay Backend - macOS 平台音频播放后端
- * 使用系统内置的 afplay 命令
- */
-
-import { execFile, ChildProcess } from 'child_process'
-import { AudioBackend, AudioBackendEvents, BackendOptions } from './base'
-import { tmpdir } from 'os'
-import { join } from 'path'
-import { writeFileSync, unlinkSync, existsSync } from 'fs'
-
-// 白名单：只允许特定路径格式（禁止 - 防止命令注入）
-const SAFE_PATH_REGEX = /^[\w\/\.]+$/
-
-/**
- * AfplayBackend - macOS 原生音频播放后端
- * 不支持真正的流式播放，需要先将数据写入临时文件
- */
-export class AfplayBackend implements AudioBackend {
-  readonly name = 'afplay'
-  readonly supportsStreaming = false
-  
-  private process?: ChildProcess
-  private tempFile?: string
-  private events?: AudioBackendEvents
-  private _started = false
-  private _paused = false
-  private _stopped = false
-  // P0-4: 缓冲所有chunk，等end()时一次性写入文件
-  private chunks: Buffer[] = []
-  private hasEnded = false
-  
-  constructor(options: BackendOptions = {}) {
-    this.events = options.events
-  }
-  
-  start(filePath: string): void {
-    if (this._started) return
-    
-    if (!SAFE_PATH_REGEX.test(filePath)) {
-      throw new Error(`Invalid file path: ${filePath}`)
-    }
-    
-    this.tempFile = filePath
-    this._started = true
-    this._stopped = false
-    
-    this.events?.onStart?.()
-    
-    // 启动播放进程
-    this.process = execFile('afplay', [filePath], (error) => {
-      if (this._stopped) return
-      
-      if (error) {
-        this.handleError(error)
-        return
-      }
-      
-      // 播放正常结束
-      this._started = false
-      this.events?.onEnd?.()
-    })
-    
-    this.process.on('error', (error) => {
-      this.handleError(error)
-    })
-  }
-  
-  write(chunk: Buffer): void {
-    if (this._stopped) return
-    // P0-4: 缓冲所有chunk，等end()时一次性写入
-    this.chunks.push(chunk)
-  }
-  
-  end(): void {
-    if (this._stopped || this.hasEnded) return
-    this.hasEnded = true
-    
-    if (this.chunks.length === 0) return
-    
-    // P0-4: 所有chunk缓冲完毕后，一次性写入文件并播放
-    this.tempFile = join(tmpdir(), `ocosay-${Date.now()}.wav`)
-    writeFileSync(this.tempFile, Buffer.concat(this.chunks))
-    this.chunks = []
-    this.start(this.tempFile)
-  }
-  
-  pause(): void {
-    if (!this._started || this._paused || this._stopped) return
-    
-    if (this.process) {
-      try {
-        this.process.kill('SIGSTOP')
-        this._paused = true
-        this.events?.onPause?.()
-      } catch (e) {
-        // SIGSTOP 可能失败
-      }
-    }
-  }
-  
-  resume(): void {
-    if (!this._paused || this._stopped) return
-    
-    if (this.process) {
-      try {
-        this.process.kill('SIGCONT')
-        this._paused = false
-        this.events?.onResume?.()
-      } catch (e) {
-        // SIGCONT 可能失败
-      }
-    }
-  }
-  
-  stop(): void {
-    this._stopped = true
-    this._started = false
-    this._paused = false
-    
-    if (this.process) {
-      try {
-        this.process.kill('SIGTERM')
-      } catch (e) {
-        // 忽略错误
-      }
-      this.process = undefined
-    }
-    
-    // 清理临时文件
-    this.cleanup()
-    this.chunks = []
-    this.hasEnded = false
-    
-    this.events?.onStop?.()
-  }
-  
-  setVolume(_volume: number): void {
-    // afplay 不支持命令行设置音量
-  }
-  
-  destroy(): void {
-    this.stop()
-  }
-  
-  private cleanup(): void {
-    if (this.tempFile && this.tempFile.startsWith(tmpdir())) {
-      try {
-        if (existsSync(this.tempFile)) {
-          unlinkSync(this.tempFile)
-        }
-      } catch (e) {
-        // 忽略清理错误
-      }
-      this.tempFile = undefined
-    }
-  }
-  
-  private handleError(error: Error): void {
-    this.events?.onError?.(error)
-  }
-}