dskcode 0.1.46 → 0.1.48

package/README.md

@@ -57,6 +57,15 @@
 - **多回合选择** — `/rewind` 进入选择模式，↑↓ 选择任意历史检查点回退
 - **上下文压缩** — 长会话自动摘要，保留最近 N 回合完整内容，Prefix Cache 命中继续享半价
 
+### 🎤 语音输入
+
+- **`/voice` 命令** — 在 `ChatSession` 输入框直接录入语音，边说边转写，结果落回输入框
+- **F2 快捷键** — 一键开关录音，按 `ESC` 取消
+- **流式识别** — 边录边出字（partial result），识别完成时落回最终文本（final）
+- **火山 ASR 大模型** — 走 `bigmodel_async` WebSocket 流式协议，识别准确率实测 100%
+- **跨平台录音** — 自动探测 `ffmpeg` / `sox` / `arecord`，macOS / Linux / Windows 三平台零配置
+- **独立调试子命令** — `dskcode voice` 跳过 UI，把识别结果直接打印到 stdout，便于排查
+
 ### 🎮 内置工具
 
 - **股票行情** — `dskcode stock` 交互式 A 股行情终端，键盘选择 + 详情折线图 + 5s 倒计时自动刷新
@@ -113,6 +122,7 @@ dskcode init
 | `dskcode init` | 在当前项目生成 AGENTS.md 项目记忆文件 |
 | `dskcode game <name>` | 启动内置小游戏，不指定名称则显示交互式游戏列表 |
 | `dskcode stock [codes...]` | 交互式股票行情，↑/↓ 选择，Enter 查看分时折线图，5s 倒计时自动刷新 |
+| `dskcode voice` | 独立语音识别调试：录音并把识别结果（partial/final）直接打印到 stdout |
 | `dskcode config-ui` | 启动本地 WebSocket 服务（端口固定 `54006`），仅供 Chrome 扩展编辑 `settings.json`，需 `Ctrl+C` 退出 |
 | `dskcode --ws` | 与 `dskcode config-ui` 等价，适用于桌面快捷方式 |
 | `dskcode completion` | 生成 shell 自动补全配置 |
@@ -152,6 +162,8 @@ dskcode init
 | `/version` | 显示版本信息 |
 | `/game` | 启动内置小游戏 |
 | `/stock` | 跳转到股票行情 |
+| `/voice` | 开启/结束语音录入（等价于按 F2）；录音中再按 `ESC` 可取消 |
+| `F2` | 同 `/voice`，按住开启/再次按下结束；适合不想敲命令时用 |
 
 对话结束后若 AI 修改了文件，2 秒后原 spinner 位置会自动出现提示：
 
@@ -222,6 +234,26 @@ dskcode 使用 JSON 格式的配置文件，支持多层级合并（优先级从
 }
 ```
 
+### 语音输入
+
+`voice` 段为可选配置。开启后在 `ChatSession` 中可用 `/voice` 或 `F2` 调起语音录入：
+
+```jsonc
+{
+  "voice": {
+    "enabled": true,                                    // 总开关
+    "provider": "volc",                                  // 目前仅支持 volc（火山引擎 ASR）
+    "token":        "${env.VOLC_ASR_TOKEN}",             // 推荐从环境变量读，勿入仓
+    "secretKey":    "${env.VOLC_ASR_SECRET}",
+    "resourceId":   "volc.bigasr.sauc.duration",         // 默认即可
+    "sampleRate":   16000,                                // 16k 精度高
+    "language":     "zh-CN"                               // zh-CN / en-US / ja-JP
+  }
+}
+```
+
+凭据建议通过环境变量注入；填明文仅供本地调试。运行依赖系统命令其一：`ffmpeg`（三平台通用）/ `sox`（macOS）/ `arecord`（Linux）。
+
 ### 股票行情
 
 `dskcode stock` 交互式 A 股行情终端，↑/↓ 选择股票，Enter 查看分时折线图、实时刷新。
@@ -252,7 +284,6 @@ Chrome 扩展启动后会自动连这个 URL，无需在 popup 粘贴。
 **关闭后台 server**：传 `--no-config-ui` 或设置 `DSKCODE_CONFIG_UI=0`。
 如果 54006 已被另一个 `dskcode` 占用，本进程会跳过 ws 并打出一行提示，扩展连不到。
 
-**端口常量**：在 `src/config/port.ts` 定义，与扩展 `src/lib/connection.ts` 中的 `WS_URL` 一一对应，迁移端口同时改两边。
 
 ---
 
@@ -307,24 +338,26 @@ dskcode 默认启用三层防护，**0 配置即可用**：
 
 ## 架构
 
-```
-src/
-├── index.ts          # 入口，shebang + 异常处理
-├── cli/              # commander 命令路由
-├── config/           # JSON 配置加载与合并
-├── provider/         # LLM Provider 接口（DeepSeek）+ CostTracker
-├── tool/             # 内置工具（Registry + 10 个内置工具）
-├── plugin/           # MCP 插件管理器
-├── security/         # 权限决策引擎：黑名单 + 规则引擎 + 4 个 Gate
-├── agent/            # Agent 会话循环 + 检查点（Checkpoint）
-├── checkpoint/       # git stash 驱动的文件状态检查点（/rewind 基础）
-├── session-store/    # 会话持久化与恢复
-├── stock/            # 股票行情（交互式终端 + asciichart）
-├── game/             # 内置小游戏
-├── types/            # 共享类型定义
-├── utils/            # 工具函数（渐变、模型工具等）
-└── ui/               # Ink 交互式终端 UI
-```
+项目采用「领域模块 + 入口骨架」的扁平分层，每个能力点都封成独立目录，便于按需替换或复用：
+
+| 模块 | 职责 |
+|------|------|
+| 入口 | shebang + 全局异常处理 |
+| 命令路由 | commander 子命令、参数解析、补全生成 |
+| 配置层 | JSON 多层级加载与合并（全局 / 项目 / 环境变量 / flag） |
+| Provider | LLM 接口抽象（DeepSeek 实现）+ CostTracker 成本统计 |
+| 工具 | 内置工具注册表与 10 个原子工具 |
+| MCP 插件 | Model Context Protocol 插件管理器 |
+| 安全 | 权限决策引擎：硬编码黑名单 + 规则引擎 + 多级 Gate |
+| Agent | 会话主循环、上下文压缩、Token 计费 |
+| 检查点 | git stash 驱动的文件状态快照（`/rewind` 基础） |
+| 会话存储 | 对话持久化与重启恢复 |
+| 股票 | 交互式 A 股行情（ink + asciichart） |
+| 游戏 | 内置小游戏 |
+| 语音 | 火山 ASR 协议客户端 + 跨平台录音 + 状态编排 |
+| 类型 / 工具 / UI | 共享类型、辅助函数、Ink 交互式终端组件 |
+
+详细源码布局请参考仓库内项目。
 
 ---
 
@@ -347,9 +380,6 @@ npm test
 
 # 类型检查
 npm run type-check
-
-# 代码检查
-npm run lint
 ```
 
 ### 项目要求
@@ -359,6 +389,20 @@ npm run lint
 
 ---
 
+## 录音依赖（可选，使用 `/voice` 时需要）
+
+`/voice` 需要系统装好一个录音 CLI；dskcode 会按平台自动探测可用命令：
+
+| 平台 | 推荐命令 | 安装 |
+|------|----------|------|
+| macOS  | `sox`    | `brew install sox`（首次会触发 TCC 麦克风授权弹窗） |
+| Linux  | `arecord`（alsa-utils）或 `ffmpeg` | `sudo apt install alsa-utils` |
+| Windows| `ffmpeg`（portable 也可） | 手动下 https://www.gyan.dev/ffmpeg/builds/ 解压到 `PATH` |
+
+验证装好后在终端里跑 `dskcode voice`，看到「[recording]」后说话，出现 partial 后台有字出现即接入成功。报错通常是麦克风权限、设备名或 `ffmpeg` 未入 `PATH`，详见 `docs/语音识别voice命令接入.md` §12.1。
+
+---
+
 ## 反馈
 
 Bug / 需求 / 改进建议欢迎加入 QQ 群沟通