pi-voice-input 0.2.0 → 0.2.2

package/README.md

@@ -1,12 +1,18 @@
 # pi Voice Input
 
-A publishable, pure TypeScript [pi](https://pi.dev/) extension for local voice input.
+A publishable, pure TypeScript [pi](https://pi.dev/) extension for Linux voice dictation into pi's editor.
 
 - Press `Ctrl+Shift+R` once to start recording.
 - Press `Ctrl+Shift+R` again to stop.
-- The extension sends the audio to an ASR provider.
+- The extension sends the audio to VolcEngine WebSocket ASR.
 - The recognized text is inserted into pi's editor without submitting.
 
+Current scope:
+
+- Linux only for now, using `pw-record` from PipeWire tools or `arecord` from alsa-utils.
+- A VolcEngine Speech API key is required.
+- This is not a local/offline ASR engine.
+
 The provider layer is intended to be extensible. **Current version supports only VolcEngine WebSocket ASR.**
 
 No Python, `uv`, upload service, or `ffmpeg` is required for normal shortcut usage.
@@ -24,8 +30,8 @@ pi extension: extensions/voice-input.ts
   ├─ sends PCM frames to the configured ASR provider via ws
   │    └─ current provider: VolcEngine /api/v3/sauc/bigmodel_nostream
   ├─ optionally post-processes raw ASR text with a configured pi model
-  │    └─ default: deepseek/deepseek-v4-flash, no reasoning option
-  └─ appends the final transcript to pi's editor with ctx.ui.setEditorText()
+  │    └─ default: disabled; set polishModel to enable it
+  └─ pastes the final transcript into pi's editor
 ```
 
 Runtime package dependency:
@@ -89,11 +95,11 @@ The config file is plain JSON and can be edited directly:
 ```json
 {
   "volcApiKey": "",
-  "polishModel": "deepseek/deepseek-v4-flash"
+  "polishModel": ""
 }
 ```
 
-`polishModel` is resolved from pi's model registry, so any model shown by `pi --list-models` can be used. Leave it empty to disable polish. If polishing fails, the raw ASR transcript is inserted instead.
+`polishModel` is disabled by default. Set it to any model shown by `pi --list-models` to enable transcript polish. If polishing fails, the raw ASR transcript is inserted instead.
 
 Verify the effective non-secret config:
 
@@ -128,7 +134,7 @@ Slash commands:
 - The extension uses post-recording WebSocket ASR: it records locally first, then sends the stopped recording in chunks. It is optimized for fast voice input, not live subtitles.
 - The default ASR segment size is intentionally larger than realtime packet sizes because this workflow sends already-recorded audio.
 - The transcript is inserted into the editor only; it is not submitted automatically.
-- When `polishModel` is set, polishing uses the current editor content and recent session messages as context, but outputs only the refined user instruction.
+- When `polishModel` is set, polishing uses the unsent editor draft and recent session messages as context, but outputs only the refined voice text. The final text is still pasted at the current cursor position without replacing the draft.
 - While recording, the status line and tool panel show `Recording with [device name]`.
 
 ## Development
@@ -159,6 +165,10 @@ After changing the extension while pi is open, run:
 /reload
 ```
 
+## Roadmap
+
+See [ROADMAP.md](ROADMAP.md) for planned user-visible work, including macOS support.
+
 ## Links
 
 - API key settings: https://console.volcengine.com/speech/new/setting/apikeys?projectName=default

package/ROADMAP.md

@@ -0,0 +1,30 @@
+# Roadmap
+
+This roadmap lists user-visible work planned for pi Voice Input. It is intentionally short so users can quickly understand what is supported now and what is coming next.
+
+## Current support
+
+- Linux voice input through `pw-record` or `arecord`
+- VolcEngine WebSocket ASR
+- Optional transcript polish through a configured pi model
+
+## Planned
+
+### macOS support
+
+Add first-class macOS recording support so users can dictate into pi without PipeWire or ALSA.
+
+Expected direction:
+
+- use a macOS-native recording command or a small bundled recorder helper
+- keep the existing user workflow: press `Ctrl+Shift+R` to start, press it again to stop and insert text
+- document required microphone permissions clearly
+- preserve the same config file and ASR provider behavior where possible
+
+Status: planned, not yet implemented.
+
+## Later candidates
+
+- additional ASR providers
+- configurable shortcut
+- better provider setup diagnostics

package/extensions/voice-input.ts

@@ -22,17 +22,19 @@ import WebSocket from "ws";
 const CONFIG_PATH = path.join(homedir(), ".pi", "agent", "voice-input.config.json");
 const VOLC_API_KEY_URL = "https://console.volcengine.com/speech/new/setting/apikeys?projectName=default";
 const DEFAULT_SHORTCUT = Key.ctrlShift("r");
-const DEFAULT_POSTPROCESS_MODEL = "deepseek/deepseek-v4-flash";
-const POSTPROCESS_SYSTEM_PROMPT = `你是 pi 语音输入插件的语音识别后处理器。你的唯一任务是把原始 ASR 文本改写为可直接提交给编码智能体的用户指令。
+const DEFAULT_POSTPROCESS_MODEL = "";
+const POSTPROCESS_SYSTEM_PROMPT = `你是 pi 语音输入插件的语音识别后处理器。你的唯一任务是润色原始 ASR 文本，使其成为可直接提交给编码智能体的用户指令。
 
 规则：
-- 只输出优化后的用户指令正文，不要输出解释、标题、前后缀、引号、代码围栏或寒暄。
+- 只输出润色后的用户指令正文，不要输出解释、标题、前后缀、引号、代码围栏或寒暄。
+- 绝对不要回答、执行或解决用户语音中提出的问题；即使原始语音是问题，也只能把这个问题本身整理成清晰文本，不要给出答案、方案、代码或结论。
+- 以忠实保留用户信息为最高优先级。不要一味概括、压缩或简述；不要删除条件、约束、例子、数值、文件名、错误信息、多个请求、前后顺序或语气重点。
 - 结合上下文理解省略指代、当前任务、文件/项目名称和用户意图；上下文仅用于理解，不要重复上下文内容，除非原始语音明确要求引用或修改它。
 - 修正明显的语音识别错误、同音/近音错误、断句和标点错误；保留代码标识符、命令、路径、URL、模型名、包名和专有名词。
 - 如果用户口误后自我更正（例如“不是……是……”“不对……”“算了改成……”），只保留更正后的正确指令，删除错误说法和更正过程。
-- 让结果完整、符合逻辑、指令明确、有指导性；必要时拆成条目或步骤。
+- 让结果完整、符合逻辑、指令明确、有指导性；必要时拆成条目或步骤，但不得丢失原始信息。
 - 不要凭空添加原始语音没有表达的新需求；不确定时保留原意并用更清晰的措辞表达。
-- 输出语言通常与原始语音一致。`;
+- 输出语言必须跟随用户原始语音的主要语言，而不是上下文语言；不要因为上下文是中文/英文就把用户语音翻译成上下文语言。`;
 
 const MSG_TYPE_CLIENT_FULL_REQUEST = 0b0001;
 const MSG_TYPE_CLIENT_AUDIO_ONLY_REQUEST = 0b0010;
@@ -715,7 +717,7 @@ function textFromContent(content: unknown): string {
 function getEditorContext(ctx: ExtensionContext, maxChars: number): string {
   if (maxChars <= 0) return "";
   try {
-    return tailText(ctx.ui.getEditorText().trim(), maxChars);
+    return tailText(ctx.ui.getEditorText(), maxChars);
   } catch {
     return "";
   }
@@ -816,12 +818,15 @@ function buildPostprocessPrompt(ctx: ExtensionContext, rawText: string, config:
   const sessionContext = getRecentSessionContext(ctx, Math.ceil(contextBudget / 2));
 
   return [
-    "请根据上下文优化下面的原始语音识别结果。",
-    "如果上下文为空，直接依据原始文本优化。",
-    "不要重复上下文本身；只输出原始语音对应的最终用户指令。",
+    "请根据上下文只润色下面的原始语音识别结果。",
+    "如果上下文为空，直接依据原始文本润色。",
+    "不要回答原始语音里的问题，也不要执行其中的请求；只输出原始语音对应的最终用户指令文本。",
+    "输出语言必须跟随原始语音的主要语言，不要跟随上下文语言，也不要翻译成上下文语言。",
+    "务必忠实保留原始语音中的信息和细节，不要为了简洁而概括、压缩或删减。",
+    "当前输入框草稿只是上下文：语音文本会由插件插入到用户当前光标位置。不要重写、重复、补全、删除或替换草稿里的既有内容。",
     "",
-    "--- 上下文：当前编辑器已有内容 ---",
-    editorContext || "（空）",
+    "--- 上下文：当前输入框未发送草稿 ---",
+    editorContext.trim() || "（空）",
     "",
     "--- 上下文：最近会话 ---",
     sessionContext || "（空）",
@@ -876,12 +881,10 @@ async function postprocessTranscript(ctx: ExtensionContext, rawText: string, con
   return polished || rawText;
 }
 
-function appendToEditor(ctx: ExtensionContext, text: string) {
+function insertIntoEditor(ctx: ExtensionContext, text: string) {
   const trimmed = text.trim();
   if (!trimmed) return;
-  const current = ctx.ui.getEditorText();
-  const separator = current.trim().length > 0 && !current.endsWith("\n") ? "\n" : "";
-  ctx.ui.setEditorText(`${current}${separator}${trimmed}`);
+  ctx.ui.pasteToEditor(trimmed);
 }
 
 async function isRecording(config: VoiceConfig): Promise<boolean> {
@@ -889,7 +892,14 @@ async function isRecording(config: VoiceConfig): Promise<boolean> {
   return Boolean(state && pidAlive(state.pid));
 }
 
+function requireInteractiveUi(ctx: ExtensionContext, action: string): boolean {
+  if (ctx.hasUI) return true;
+  ctx.ui.notify(`Voice ${action} requires interactive pi UI. Use /voice config or /voice help for setup information.`, "error");
+  return false;
+}
+
 async function startRecording(ctx: ExtensionContext) {
+  if (!requireInteractiveUi(ctx, "recording")) return;
   const config = getConfig();
   const existing = readState(config);
   if (existing && pidAlive(existing.pid)) {
@@ -931,6 +941,7 @@ async function startRecording(ctx: ExtensionContext) {
 }
 
 async function stopRecording(ctx: ExtensionContext, transcribe = true) {
+  if (transcribe && !requireInteractiveUi(ctx, "transcription")) return;
   const config = getConfig();
   const state = readState(config);
   if (!state) {
@@ -989,7 +1000,7 @@ async function stopRecording(ctx: ExtensionContext, transcribe = true) {
   }
 
   ctx.ui.setStatus("voice-input", undefined);
-  appendToEditor(ctx, finalText);
+  insertIntoEditor(ctx, finalText);
   ctx.ui.notify(
     `Voice text inserted. audio=${(durationMs / 1000).toFixed(2)}s decode=${decodeMs}ms asr=${result.timings.totalMs}ms${
       config.postprocessEnabled ? ` postprocess=${postprocessMs}ms${postprocessUsed ? " polished" : ""}` : ""
@@ -999,10 +1010,7 @@ async function stopRecording(ctx: ExtensionContext, transcribe = true) {
 }
 
 async function toggleRecording(ctx: ExtensionContext) {
-  if (!ctx.hasUI) {
-    ctx.ui.notify("voice input requires interactive pi UI", "error");
-    return;
-  }
+  if (!requireInteractiveUi(ctx, "input")) return;
   const config = getConfig();
   if (await isRecording(config)) await stopRecording(ctx, true);
   else await startRecording(ctx);

package/package.json

@@ -1,15 +1,18 @@
 {
   "name": "pi-voice-input",
-  "version": "0.2.0",
-  "description": "provider-extensible voice input extension for pi",
+  "version": "0.2.2",
+  "description": "Press Ctrl+Shift+R to dictate prompts into Pi using VolcEngine ASR",
   "type": "module",
   "keywords": [
     "pi-package",
     "pi-extension",
+    "pi",
     "voice-input",
     "speech-to-text",
     "dictation",
-    "asr"
+    "asr",
+    "volcengine",
+    "linux"
   ],
   "license": "MIT",
   "author": "tr-nc",
@@ -24,6 +27,7 @@
   "files": [
     "extensions",
     "README.md",
+    "ROADMAP.md",
     "AGENTS.md"
   ],
   "pi": {