pi-voice-input 0.1.2 → 0.2.0

package/AGENTS.md

@@ -13,8 +13,8 @@ Development workflow for this repo.
 
 ## Secrets and local data
 
-- Never commit API keys, `.env`, recordings, logs, caches, or `node_modules`.
-- User credentials belong in `~/.pi/agent/voice-input.env`, usually written by `/voice key`.
+- Never commit API keys, `.env`, local config JSON, recordings, logs, caches, or `node_modules`.
+- User credentials and plugin settings belong in `~/.pi/agent/voice-input.config.json`, usually written by `/voice key` or `/voice init`.
 - Do not print or copy real API keys into commits, docs, tests, or command output.
 - The explicit VolcEngine API key URL that should be shown to users is:
   `https://console.volcengine.com/speech/new/setting/apikeys?projectName=default`
@@ -33,7 +33,6 @@ npm pack --dry-run
 Check that `npm pack --dry-run` includes only publishable files, normally:
 
 ```text
-.env.example
 AGENTS.md
 README.md
 extensions/voice-input.ts
@@ -50,7 +49,7 @@ Then check:
 
 ```bash
 git status --short
-rg -n "VOLC_API_KEY=|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}" \
+rg -n '"volcApiKey"\\s*:\\s*"[^"]+"|VOLC_API_KEY=|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}' \
   --glob '!node_modules/**' --glob '!package-lock.json' . || true
 ```
 

package/README.md

@@ -23,6 +23,8 @@ pi extension: extensions/voice-input.ts
   ├─ parses the WAV container in TypeScript and extracts raw PCM
   ├─ 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()
 ```
 
@@ -43,18 +45,6 @@ Install the published package with pi:
 pi install npm:pi-voice-input
 ```
 
-To pin a specific version:
-
-```bash
-pi install npm:pi-voice-input@0.1.0
-```
-
-If pi is already running, reload extensions after installation:
-
-```text
-/reload
-```
-
 ## Providers
 
 The extension is structured around a provider boundary: recording, editor insertion, and command handling are generic; ASR transport/protocol logic is provider-specific.
@@ -68,92 +58,49 @@ Planned provider direction:
 - add more ASR providers without changing the shortcut/user workflow
 - keep provider credentials and options isolated in config
 
-## Configure credentials
+## Configure
 
-In pi, run:
+All plugin settings live in one JSON file:
 
 ```text
-/voice key
+~/.pi/agent/voice-input.config.json
 ```
 
-Paste your VolcEngine Speech API key into the prompt. The extension saves it for future sessions and keeps it out of your project files.
+Package-local and project-local env files are not read.
 
-The key URL is also shown inside pi when the key is missing, when you run `/voice key`, and in `/voice help`:
+Create or normalize the file from inside pi:
 
 ```text
-https://console.volcengine.com/speech/new/setting/apikeys?projectName=default
+/voice init
 ```
 
-Then verify:
+Then set the VolcEngine Speech API key:
 
 ```text
-/voice config
+/voice key
 ```
 
-You can get/manage the key here:
+The key URL is also shown inside pi when the key is missing, when you run `/voice key`, and in `/voice help`:
 
 https://console.volcengine.com/speech/new/setting/apikeys?projectName=default
 
-If `VOLC_API_KEY` is missing, the extension does not silently fail. It shows an error notification explaining:
-
-- that the current provider API key is missing
-- to run `/voice key`
-- the VolcEngine API-key settings URL
-- that `/voice config` can be used to verify detection
+The config file is plain JSON and can be edited directly:
 
-Manual fallback:
-
-```bash
-mkdir -p ~/.pi/agent
-cp .env.example ~/.pi/agent/voice-input.env
-$EDITOR ~/.pi/agent/voice-input.env
+```json
+{
+  "volcApiKey": "",
+  "polishModel": "deepseek/deepseek-v4-flash"
+}
 ```
 
-## Configuration reference
-
-Example:
-
-```bash
-# Required for the current provider. Usually set by /voice key.
-VOLC_API_KEY=your_volcengine_speech_api_key
-
-# Current provider: VolcEngine WebSocket ASR endpoint and resource
-VOLC_WS_URL=wss://openspeech.bytedance.com/api/v3/sauc/bigmodel_nostream
-VOLC_STREAM_RESOURCE_ID=volc.seedasr.sauc.duration
-
-# Empty means auto-detect. Example: zh-CN.
-ASR_LANGUAGE=
-
-# Optional contextual prompt for ASR.
-ASR_PROMPT=
+`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.
 
-# Faster for post-recording batch transcription. Use 200 for realtime-like packet size.
-STREAM_SEGMENT_MS=5000
-ASR_REQUEST_TIMEOUT_MS=90000
+Verify the effective non-secret config:
 
-# Empty means use PipeWire's default source.
-RECORDER_TARGET=
-RECORDING_FINALIZE_DELAY=0.1
-
-# Storage for recordings, logs, and state.
-VOICE_INPUT_HOME=~/.pi/agent/voice-input
-RECORDINGS_DIR=recordings
-RECORDER_STATE=recording.json
-RECORDER_LOG_DIR=logs
-
-# Shortcut. Default: ctrl+shift+r
-VOICE_INPUT_SHORTCUT=ctrl+shift+r
+```text
+/voice config
 ```
 
-Config loading order, later values override earlier ones:
-
-1. `~/.pi/agent/voice-input.env`
-2. package-local `.env`
-3. current-working-directory `.env`
-4. shell environment variables
-
-Do not commit real credentials. Prefer `/voice key`, or keep private local values in `.env` or `~/.pi/agent/voice-input.env`.
-
 ## Usage
 
 Shortcut:
@@ -171,6 +118,7 @@ Slash commands:
 /voice cancel   # stop recording without transcribing
 /voice status   # show recorder state
 /voice config   # show effective non-secret config and whether API key is detected
+/voice init     # create or normalize ~/.pi/agent/voice-input.config.json
 /voice key      # prompt for and save the current provider API key
 /voice help     # show setup help, including the explicit VolcEngine API key URL
 ```
@@ -178,8 +126,10 @@ Slash commands:
 ## Notes
 
 - 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 `STREAM_SEGMENT_MS=5000` is intentionally larger than realtime packet sizes because this workflow sends already-recorded audio.
+- 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.
+- While recording, the status line and tool panel show `Recording with [device name]`.
 
 ## Development
 
@@ -209,7 +159,7 @@ After changing the extension while pi is open, run:
 /reload
 ```
 
-## Volcengine links
+## Links
 
 - API key settings: https://console.volcengine.com/speech/new/setting/apikeys?projectName=default
 - ASR product page: https://www.volcengine.com/product/asr

package/extensions/voice-input.ts

@@ -1,4 +1,5 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { completeSimple, type Api, type Model } from "@earendil-works/pi-ai";
 import { Key } from "@earendil-works/pi-tui";
 import { spawn, spawnSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
@@ -15,15 +16,23 @@ import {
 } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
 import { gzipSync, gunzipSync } from "node:zlib";
 import WebSocket from "ws";
 
-const EXTENSION_DIR = path.dirname(fileURLToPath(import.meta.url));
-const PACKAGE_ROOT = path.resolve(EXTENSION_DIR, "..");
-const PRIVATE_CONFIG_PATH = path.join(homedir(), ".pi", "agent", "voice-input.env");
+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 文本改写为可直接提交给编码智能体的用户指令。
+
+规则：
+- 只输出优化后的用户指令正文，不要输出解释、标题、前后缀、引号、代码围栏或寒暄。
+- 结合上下文理解省略指代、当前任务、文件/项目名称和用户意图；上下文仅用于理解，不要重复上下文内容，除非原始语音明确要求引用或修改它。
+- 修正明显的语音识别错误、同音/近音错误、断句和标点错误；保留代码标识符、命令、路径、URL、模型名、包名和专有名词。
+- 如果用户口误后自我更正（例如“不是……是……”“不对……”“算了改成……”），只保留更正后的正确指令，删除错误说法和更正过程。
+- 让结果完整、符合逻辑、指令明确、有指导性；必要时拆成条目或步骤。
+- 不要凭空添加原始语音没有表达的新需求；不确定时保留原意并用更清晰的措辞表达。
+- 输出语言通常与原始语音一致。`;
 
 const MSG_TYPE_CLIENT_FULL_REQUEST = 0b0001;
 const MSG_TYPE_CLIENT_AUDIO_ONLY_REQUEST = 0b0010;
@@ -35,9 +44,15 @@ const SERIALIZATION_NONE = 0b0000;
 const SERIALIZATION_JSON = 0b0001;
 const COMPRESSION_GZIP = 0b0001;
 
-type EnvMap = Record<string, string>;
+type JsonObject = Record<string, unknown>;
+
+type VoiceInputConfigFile = {
+  volcApiKey: string;
+  polishModel: string;
+};
 
 type VoiceConfig = {
+  configPath: string;
   apiKey: string;
   wsUrl: string;
   resourceId: string;
@@ -56,6 +71,11 @@ type VoiceConfig = {
   enablePunc: boolean;
   enableDdc: boolean;
   showUtterances: boolean;
+  postprocessEnabled: boolean;
+  postprocessModel: string;
+  postprocessTimeoutMs: number;
+  postprocessMaxTokens: number;
+  postprocessContextChars: number;
 };
 
 type RecordingState = {
@@ -64,6 +84,7 @@ type RecordingState = {
   logPath: string;
   startedAt: string;
   recorderTarget?: string;
+  deviceName?: string;
 };
 
 type DecodedFrame = {
@@ -85,139 +106,94 @@ type TranscriptionResult = {
   };
 };
 
-function parseEnvText(text: string): EnvMap {
-  const env: EnvMap = {};
-  for (const rawLine of text.split(/\r?\n/)) {
-    const line = rawLine.trim();
-    if (!line || line.startsWith("#")) continue;
-    const match = line.match(/^([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/);
-    if (!match) continue;
-    const key = match[1];
-    let value = match[2] ?? "";
-    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
-      value = value.slice(1, -1);
-    }
-    env[key] = value;
-  }
-  return env;
-}
-
-function loadEnvFiles(): EnvMap {
-  const candidates = [
-    PRIVATE_CONFIG_PATH,
-    path.join(PACKAGE_ROOT, ".env"),
-    path.join(process.cwd(), ".env"),
-  ];
-  const merged: EnvMap = {};
-  for (const file of candidates) {
-    if (!existsSync(file)) continue;
-    Object.assign(merged, parseEnvText(readFileSync(file, "utf8")));
-  }
-  return merged;
-}
-
-function setting(env: EnvMap, name: string, fallback = ""): string {
-  const value = process.env[name] ?? env[name];
-  return value == null ? fallback : value;
+function ensureDir(dir: string) {
+  mkdirSync(dir, { recursive: true });
 }
 
-function settingAny(env: EnvMap, names: string[], fallback = ""): string {
-  for (const name of names) {
-    const value = process.env[name] ?? env[name];
-    if (value != null && value !== "") return value;
-  }
-  return fallback;
+function defaultConfigFile(): VoiceInputConfigFile {
+  return {
+    volcApiKey: "",
+    polishModel: DEFAULT_POSTPROCESS_MODEL,
+  };
 }
 
-function boolSetting(env: EnvMap, name: string, fallback: boolean): boolean {
-  const raw = setting(env, name, fallback ? "true" : "false").trim().toLowerCase();
-  if (["1", "true", "yes", "on"].includes(raw)) return true;
-  if (["0", "false", "no", "off"].includes(raw)) return false;
-  return fallback;
+function isObject(value: unknown): value is JsonObject {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
 
-function numberSetting(env: EnvMap, name: string, fallback: number): number {
-  const raw = setting(env, name, String(fallback)).trim();
-  const value = Number(raw);
-  return Number.isFinite(value) ? value : fallback;
+function stringField(source: JsonObject, name: string, fallback: string): string {
+  const value = source[name];
+  return typeof value === "string" ? value : fallback;
 }
 
-function clamp(value: number, min: number, max: number): number {
-  return Math.min(max, Math.max(min, value));
+function normalizeConfigFile(input: unknown): VoiceInputConfigFile {
+  const defaults = defaultConfigFile();
+  const root = isObject(input) ? input : {};
+  return {
+    volcApiKey: stringField(root, "volcApiKey", defaults.volcApiKey).trim(),
+    polishModel: stringField(root, "polishModel", defaults.polishModel).trim(),
+  };
 }
 
-function expandHome(value: string): string {
-  if (value === "~") return homedir();
-  if (value.startsWith("~/")) return path.join(homedir(), value.slice(2));
-  return value;
+function writeConfigFile(config: unknown) {
+  ensureDir(path.dirname(CONFIG_PATH));
+  writeFileSync(CONFIG_PATH, `${JSON.stringify(normalizeConfigFile(config), null, 2)}\n`, { mode: 0o600 });
+  chmodSync(CONFIG_PATH, 0o600);
 }
 
-function resolvePath(value: string, baseDir: string): string {
-  const expanded = expandHome(value);
-  return path.isAbsolute(expanded) ? expanded : path.resolve(baseDir, expanded);
+function loadConfigFile(): VoiceInputConfigFile {
+  if (!existsSync(CONFIG_PATH)) return defaultConfigFile();
+  try {
+    return normalizeConfigFile(JSON.parse(readFileSync(CONFIG_PATH, "utf8")));
+  } catch (error) {
+    throw new Error(`Failed to read voice input config ${CONFIG_PATH}: ${error instanceof Error ? error.message : String(error)}`);
+  }
 }
 
 function getConfig(): VoiceConfig {
-  const env = loadEnvFiles();
-  const defaultHome = path.join(homedir(), ".pi", "agent", "voice-input");
-  const voiceHome = resolvePath(setting(env, "VOICE_INPUT_HOME", defaultHome), process.cwd());
+  const fileConfig = loadConfigFile();
+  const voiceHome = path.join(homedir(), ".pi", "agent", "voice-input");
+  const polishModel = fileConfig.polishModel.trim();
 
   return {
-    apiKey: settingAny(env, ["VOLC_API_KEY", "VOLCENGINE_API_KEY", "DOUBAO_ASR_API_KEY"]).trim(),
-    wsUrl: setting(env, "VOLC_WS_URL", "wss://openspeech.bytedance.com/api/v3/sauc/bigmodel_nostream").trim(),
-    resourceId: setting(env, "VOLC_STREAM_RESOURCE_ID", "volc.seedasr.sauc.duration").trim(),
-    language: settingAny(env, ["ASR_LANGUAGE", "VOLC_ASR_LANGUAGE"], "").trim(),
-    uid: setting(env, "ASR_UID", "pi-voice-input").trim(),
-    prompt: setting(env, "ASR_PROMPT", "").trim(),
-    segmentMs: clamp(Math.round(numberSetting(env, "STREAM_SEGMENT_MS", 5000)), 100, 20000),
-    requestTimeoutMs: clamp(Math.round(numberSetting(env, "ASR_REQUEST_TIMEOUT_MS", 90000)), 1000, 10 * 60 * 1000),
-    finalizeDelayMs: clamp(numberSetting(env, "RECORDING_FINALIZE_DELAY", 0.1) * 1000, 0, 5000),
-    recorderTarget: setting(env, "RECORDER_TARGET", "").trim(),
-    recordingsDir: resolvePath(setting(env, "RECORDINGS_DIR", "recordings"), voiceHome),
-    statePath: resolvePath(setting(env, "RECORDER_STATE", "recording.json"), voiceHome),
-    logDir: resolvePath(setting(env, "RECORDER_LOG_DIR", "logs"), voiceHome),
-    shortcut: setting(env, "VOICE_INPUT_SHORTCUT", DEFAULT_SHORTCUT).trim() || DEFAULT_SHORTCUT,
-    enableItn: boolSetting(env, "ENABLE_ITN", true),
-    enablePunc: boolSetting(env, "ENABLE_PUNC", true),
-    enableDdc: boolSetting(env, "ENABLE_DDC", false),
-    showUtterances: boolSetting(env, "SHOW_UTTERANCES", false),
+    configPath: CONFIG_PATH,
+    apiKey: fileConfig.volcApiKey.trim(),
+    wsUrl: "wss://openspeech.bytedance.com/api/v3/sauc/bigmodel_nostream",
+    resourceId: "volc.seedasr.sauc.duration",
+    language: "",
+    uid: "pi-voice-input",
+    prompt: "",
+    segmentMs: 5000,
+    requestTimeoutMs: 90000,
+    finalizeDelayMs: 100,
+    recorderTarget: "",
+    recordingsDir: path.join(voiceHome, "recordings"),
+    statePath: path.join(voiceHome, "recording.json"),
+    logDir: path.join(voiceHome, "logs"),
+    shortcut: DEFAULT_SHORTCUT,
+    enableItn: true,
+    enablePunc: true,
+    enableDdc: false,
+    showUtterances: false,
+    postprocessEnabled: polishModel.length > 0,
+    postprocessModel: polishModel,
+    postprocessTimeoutMs: 30000,
+    postprocessMaxTokens: 2048,
+    postprocessContextChars: 6000,
   };
 }
 
-function ensureDir(dir: string) {
-  mkdirSync(dir, { recursive: true });
-}
-
-function envValue(value: string): string {
-  if (/^[A-Za-z0-9_./:@+-]*$/.test(value)) return value;
-  return JSON.stringify(value);
+function ensureConfigFile(): boolean {
+  const existed = existsSync(CONFIG_PATH);
+  writeConfigFile(loadConfigFile());
+  return !existed;
 }
 
-function writePrivateEnvValue(name: string, value: string) {
-  if (/\r|\n/.test(value)) throw new Error(`${name} must be a single-line value`);
-  ensureDir(path.dirname(PRIVATE_CONFIG_PATH));
-
-  const original = existsSync(PRIVATE_CONFIG_PATH) ? readFileSync(PRIVATE_CONFIG_PATH, "utf8") : "";
-  const lines = original ? original.split(/\r?\n/) : [];
-  const replacement = `${name}=${envValue(value)}`;
-  let replaced = false;
-
-  const nextLines = lines.map((line) => {
-    if (new RegExp(`^\\s*${name}\\s*=`).test(line)) {
-      replaced = true;
-      return replacement;
-    }
-    return line;
-  });
-
-  if (!replaced) {
-    if (nextLines.length > 0 && nextLines[nextLines.length - 1] !== "") nextLines.push("");
-    nextLines.push("# Managed by pi-voice-input. You can also update this with /voice key.");
-    nextLines.push(replacement);
-  }
-
-  writeFileSync(PRIVATE_CONFIG_PATH, nextLines.join("\n").replace(/\n*$/, "\n"), { mode: 0o600 });
-  chmodSync(PRIVATE_CONFIG_PATH, 0o600);
+function writeConfigApiKey(apiKey: string) {
+  if (/\r|\n/.test(apiKey)) throw new Error("volcApiKey must be a single-line value");
+  const config = loadConfigFile();
+  config.volcApiKey = apiKey.trim();
+  writeConfigFile(config);
 }
 
 function timestampForFilename(): string {
@@ -228,6 +204,12 @@ function commandExists(command: string): boolean {
   return spawnSync("sh", ["-lc", `command -v ${command}`], { stdio: "ignore" }).status === 0;
 }
 
+function commandOutput(command: string, args: string[], timeoutMs = 1500): string {
+  const result = spawnSync(command, args, { encoding: "utf8", timeout: timeoutMs });
+  if (result.status !== 0) return "";
+  return (result.stdout || "").trim();
+}
+
 function recorderCommand(config: VoiceConfig, outputPath: string): string[] {
   if (commandExists("pw-record")) {
     const cmd = ["pw-record", "--rate", "16000", "--channels", "1", "--format", "s16"];
@@ -241,6 +223,98 @@ function recorderCommand(config: VoiceConfig, outputPath: string): string[] {
   throw new Error("No recorder found. Install PipeWire tools (pw-record) or alsa-utils (arecord).");
 }
 
+type PipeWireSource = {
+  id: string;
+  name: string;
+  description: string;
+};
+
+function parsePactlSources(text: string): PipeWireSource[] {
+  const sources: PipeWireSource[] = [];
+  let current: PipeWireSource | null = null;
+  for (const line of text.split(/\r?\n/)) {
+    const sourceMatch = line.match(/^Source #(\S+)/);
+    if (sourceMatch) {
+      if (current) sources.push(current);
+      current = { id: sourceMatch[1], name: "", description: "" };
+      continue;
+    }
+    if (!current) continue;
+    const nameMatch = line.match(/^\s*Name:\s*(.+)$/);
+    if (nameMatch) {
+      current.name = nameMatch[1].trim();
+      continue;
+    }
+    const descriptionMatch = line.match(/^\s*Description:\s*(.+)$/);
+    if (descriptionMatch) current.description = descriptionMatch[1].trim();
+  }
+  if (current) sources.push(current);
+  return sources;
+}
+
+function wpctlProperty(text: string, property: string): string {
+  const escaped = property.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const match = text.match(new RegExp(`(?:^|\\n)\\s*\\*?\\s*${escaped}\\s*=\\s*"([^"]+)"`));
+  return match?.[1]?.trim() ?? "";
+}
+
+function inspectPipeWireSource(target: string): string {
+  if (!commandExists("wpctl")) return "";
+  const inspect = commandOutput("wpctl", ["inspect", target]);
+  return (
+    wpctlProperty(inspect, "node.description") ||
+    wpctlProperty(inspect, "node.nick") ||
+    wpctlProperty(inspect, "node.name")
+  );
+}
+
+function defaultPipeWireSourceFromStatus(): string {
+  if (!commandExists("wpctl")) return "";
+  const status = commandOutput("wpctl", ["status"]);
+  let inSources = false;
+  for (const line of status.split(/\r?\n/)) {
+    if (/Sources:/.test(line)) {
+      inSources = true;
+      continue;
+    }
+    if (inSources && /^\s*[├└]─/.test(line)) break;
+    if (!inSources) continue;
+    const match = line.match(/^\s*│\s+\*\s+\d+\.\s+(.+?)(?:\s+\[|$)/);
+    if (match) return match[1].trim();
+  }
+  return "";
+}
+
+function pipeWireSourceName(target: string): string {
+  const sources = commandExists("pactl") ? parsePactlSources(commandOutput("pactl", ["list", "sources"])) : [];
+
+  if (!target) {
+    const defaultName = commandExists("pactl") ? commandOutput("pactl", ["get-default-source"]) : "";
+    const source = sources.find((item) => item.name === defaultName);
+    return (
+      source?.description ||
+      source?.name ||
+      inspectPipeWireSource("@DEFAULT_SOURCE@") ||
+      defaultPipeWireSourceFromStatus() ||
+      defaultName ||
+      "default microphone"
+    );
+  }
+
+  const source = sources.find((item) => item.id === target || item.name === target || item.description === target);
+  return source?.description || source?.name || (/^\d+$/.test(target) ? inspectPipeWireSource(target) : "") || target;
+}
+
+function recordingDeviceName(config: VoiceConfig, recorderExecutable: string): string {
+  if (recorderExecutable === "pw-record") return pipeWireSourceName(config.recorderTarget);
+  if (recorderExecutable === "arecord") return "ALSA default microphone";
+  return config.recorderTarget || "default microphone";
+}
+
+function recordingStatusText(deviceName: string): string {
+  return `Recording with ${deviceName || "default microphone"}`;
+}
+
 function readState(config: VoiceConfig): RecordingState | null {
   if (!existsSync(config.statePath)) return null;
   return JSON.parse(readFileSync(config.statePath, "utf8")) as RecordingState;
@@ -457,8 +531,9 @@ function parseRecordedWav(filePath: string): { pcm: Buffer; durationMs: number }
 
 function missingCredentialsMessage(): string {
   return [
-    "Missing VOLC_API_KEY for the current VolcEngine ASR provider.",
+    "Missing VolcEngine API key in the pi voice input config.",
     "Run /voice key and paste your VolcEngine Speech API key.",
+    `Config file: ${CONFIG_PATH}`,
     `Get/create the key here: ${VOLC_API_KEY_URL}`,
     "Run /voice config to verify whether the key is detected.",
   ].join("\n");
@@ -611,6 +686,196 @@ async function transcribePcm(pcm: Buffer, durationMs: number, config: VoiceConfi
   };
 }
 
+function tailText(text: string, maxChars: number): string {
+  if (maxChars <= 0) return "";
+  if (text.length <= maxChars) return text;
+  return `…${text.slice(-maxChars)}`;
+}
+
+function truncateText(text: string, maxChars: number): string {
+  if (maxChars <= 0) return "";
+  if (text.length <= maxChars) return text;
+  return `${text.slice(0, maxChars)}…`;
+}
+
+function textFromContent(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .map((part) => {
+      if (!part || typeof part !== "object") return "";
+      const block = part as { type?: unknown; text?: unknown };
+      if (block.type === "text" && typeof block.text === "string") return block.text;
+      return "";
+    })
+    .filter(Boolean)
+    .join("\n");
+}
+
+function getEditorContext(ctx: ExtensionContext, maxChars: number): string {
+  if (maxChars <= 0) return "";
+  try {
+    return tailText(ctx.ui.getEditorText().trim(), maxChars);
+  } catch {
+    return "";
+  }
+}
+
+function getRecentSessionContext(ctx: ExtensionContext, maxChars: number): string {
+  if (maxChars <= 0) return "";
+  const lines: string[] = [];
+  for (const entry of ctx.sessionManager.getBranch()) {
+    if (entry.type !== "message") continue;
+    const message = entry.message as { role?: unknown; content?: unknown };
+    if (message.role !== "user" && message.role !== "assistant") continue;
+    const text = textFromContent(message.content).replace(/\s+/g, " ").trim();
+    if (!text) continue;
+    lines.push(`${message.role}: ${truncateText(text, 1200)}`);
+  }
+  return tailText(lines.slice(-8).join("\n"), maxChars);
+}
+
+function simplifyModelReference(value: string): string {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "");
+}
+
+function stripThinkingSuffix(value: string): string {
+  return value.replace(/:(?:off|minimal|low|medium|high|xhigh)$/i, "");
+}
+
+function modelLabel(model: Model<Api>): string {
+  return `${model.provider}/${model.id}`;
+}
+
+function resolvePostprocessModel(ctx: ExtensionContext, reference: string): Model<Api> {
+  const requested = stripThinkingSuffix(reference.trim());
+  if (!requested) throw new Error("polishModel is empty in voice input config");
+
+  const models = ctx.modelRegistry.getAll();
+  const lower = requested.toLowerCase();
+  const simple = simplifyModelReference(requested);
+
+  const exactCanonical = models.filter((model) => modelLabel(model).toLowerCase() === lower);
+  if (exactCanonical.length === 1) return exactCanonical[0];
+
+  const exactBare = models.filter((model) => model.id.toLowerCase() === lower || model.name.toLowerCase() === lower);
+  if (exactBare.length === 1) return exactBare[0];
+  if (exactBare.length > 1) {
+    throw new Error(
+      `Ambiguous postprocess model "${reference}". Use provider/model, e.g. ${exactBare.map(modelLabel).slice(0, 5).join(", ")}`,
+    );
+  }
+
+  const exactSimple = models.filter(
+    (model) =>
+      simplifyModelReference(modelLabel(model)) === simple ||
+      simplifyModelReference(model.id) === simple ||
+      simplifyModelReference(model.name) === simple,
+  );
+  if (exactSimple.length === 1) return exactSimple[0];
+  if (exactSimple.length > 1) {
+    throw new Error(
+      `Ambiguous postprocess model "${reference}". Use provider/model, e.g. ${exactSimple.map(modelLabel).slice(0, 5).join(", ")}`,
+    );
+  }
+
+  const fuzzy = models.filter(
+    (model) =>
+      modelLabel(model).toLowerCase().includes(lower) ||
+      model.id.toLowerCase().includes(lower) ||
+      model.name.toLowerCase().includes(lower) ||
+      simplifyModelReference(modelLabel(model)).includes(simple) ||
+      simplifyModelReference(model.id).includes(simple) ||
+      simplifyModelReference(model.name).includes(simple),
+  );
+  if (fuzzy.length === 1) return fuzzy[0];
+  if (fuzzy.length > 1) {
+    throw new Error(
+      `Ambiguous postprocess model "${reference}". Use provider/model, e.g. ${fuzzy.map(modelLabel).slice(0, 5).join(", ")}`,
+    );
+  }
+
+  throw new Error(`Postprocess model "${reference}" not found. Run pi --list-models to see available models.`);
+}
+
+function extractAssistantText(message: { content: unknown }): string {
+  return textFromContent(message.content).trim();
+}
+
+function cleanPostprocessOutput(output: string): string {
+  let text = output.trim();
+  const fence = text.match(/^```[a-zA-Z0-9_-]*\s*\n([\s\S]*?)\n```$/);
+  if (fence) text = fence[1].trim();
+  text = text.replace(/^(?:优化后的(?:用户)?指令|整理后的(?:用户)?指令|改写后的(?:用户)?指令)\s*[：:]\s*/u, "").trim();
+  return text;
+}
+
+function buildPostprocessPrompt(ctx: ExtensionContext, rawText: string, config: VoiceConfig): string {
+  const contextBudget = config.postprocessContextChars;
+  const editorContext = getEditorContext(ctx, Math.floor(contextBudget / 2));
+  const sessionContext = getRecentSessionContext(ctx, Math.ceil(contextBudget / 2));
+
+  return [
+    "请根据上下文优化下面的原始语音识别结果。",
+    "如果上下文为空，直接依据原始文本优化。",
+    "不要重复上下文本身；只输出原始语音对应的最终用户指令。",
+    "",
+    "--- 上下文：当前编辑器已有内容 ---",
+    editorContext || "（空）",
+    "",
+    "--- 上下文：最近会话 ---",
+    sessionContext || "（空）",
+    "",
+    "--- 原始语音识别结果 ---",
+    rawText.trim(),
+  ].join("\n");
+}
+
+async function postprocessTranscript(ctx: ExtensionContext, rawText: string, config: VoiceConfig): Promise<string> {
+  if (!config.postprocessEnabled) return rawText;
+
+  const raw = rawText.trim();
+  if (!raw) return rawText;
+
+  const model = resolvePostprocessModel(ctx, config.postprocessModel);
+  const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+  if (!auth.ok) {
+    throw new Error(`Postprocess model ${modelLabel(model)} is not ready: ${auth.error}`);
+  }
+
+  const response = await completeSimple(
+    model,
+    {
+      systemPrompt: POSTPROCESS_SYSTEM_PROMPT,
+      messages: [
+        {
+          role: "user",
+          content: buildPostprocessPrompt(ctx, raw, config),
+          timestamp: Date.now(),
+        },
+      ],
+      tools: [],
+    },
+    {
+      apiKey: auth.apiKey,
+      headers: auth.headers,
+      temperature: 0,
+      maxTokens: config.postprocessMaxTokens,
+      timeoutMs: config.postprocessTimeoutMs,
+      maxRetries: 0,
+      cacheRetention: "none",
+      signal: ctx.signal,
+    },
+  );
+
+  if (response.stopReason === "error" || response.stopReason === "aborted") {
+    throw new Error(response.errorMessage || `Postprocess model stopped with ${response.stopReason}`);
+  }
+
+  const polished = cleanPostprocessOutput(extractAssistantText(response));
+  return polished || rawText;
+}
+
 function appendToEditor(ctx: ExtensionContext, text: string) {
   const trimmed = text.trim();
   if (!trimmed) return;
@@ -628,8 +893,9 @@ async function startRecording(ctx: ExtensionContext) {
   const config = getConfig();
   const existing = readState(config);
   if (existing && pidAlive(existing.pid)) {
-    ctx.ui.notify(`Already recording: pid=${existing.pid}`, "warning");
-    ctx.ui.setStatus("voice-input", ctx.ui.theme.fg("error", "● recording"));
+    const deviceName = existing.deviceName || recordingDeviceName(config, commandExists("pw-record") ? "pw-record" : "arecord");
+    ctx.ui.notify(`Already recording: pid=${existing.pid}. ${recordingStatusText(deviceName)}`, "warning");
+    ctx.ui.setStatus("voice-input", ctx.ui.theme.fg("error", recordingStatusText(deviceName)));
     return;
   }
   if (existing) clearState(config);
@@ -639,6 +905,7 @@ async function startRecording(ctx: ExtensionContext) {
   const outputPath = path.join(config.recordingsDir, `recording-${timestampForFilename()}.wav`);
   const logPath = path.join(config.logDir, `recording-${timestampForFilename()}.log`);
   const cmd = recorderCommand(config, outputPath);
+  const deviceName = recordingDeviceName(config, cmd[0]);
 
   ctx.ui.setStatus("voice-input", ctx.ui.theme.fg("warning", "● starting mic"));
   const logFd = openSync(logPath, "a");
@@ -656,10 +923,11 @@ async function startRecording(ctx: ExtensionContext) {
     logPath,
     startedAt: new Date().toISOString(),
     recorderTarget: config.recorderTarget || undefined,
+    deviceName,
   });
 
-  ctx.ui.setStatus("voice-input", ctx.ui.theme.fg("error", "● recording"));
-  ctx.ui.notify("Voice recording started. Press Ctrl+Shift+R again to stop/transcribe.", "info");
+  ctx.ui.setStatus("voice-input", ctx.ui.theme.fg("error", recordingStatusText(deviceName)));
+  ctx.ui.notify(`${recordingStatusText(deviceName)}. Press Ctrl+Shift+R again to stop/transcribe.`, "info");
 }
 
 async function stopRecording(ctx: ExtensionContext, transcribe = true) {
@@ -691,9 +959,9 @@ async function stopRecording(ctx: ExtensionContext, transcribe = true) {
   const { pcm, durationMs } = parseRecordedWav(state.path);
   const decodeMs = Date.now() - decodeStart;
   const result = await transcribePcm(pcm, durationMs, config);
-  ctx.ui.setStatus("voice-input", undefined);
 
   if (!result.text.trim()) {
+    ctx.ui.setStatus("voice-input", undefined);
     ctx.ui.notify(
       `Transcription finished but no text was returned. audio=${(durationMs / 1000).toFixed(2)}s total=${result.timings.totalMs}ms`,
       "warning",
@@ -701,9 +969,31 @@ async function stopRecording(ctx: ExtensionContext, transcribe = true) {
     return;
   }
 
-  appendToEditor(ctx, result.text);
+  let finalText = result.text;
+  let postprocessMs = 0;
+  let postprocessUsed = false;
+  if (config.postprocessEnabled) {
+    ctx.ui.setStatus("voice-input", ctx.ui.theme.fg("warning", "● polishing"));
+    const postprocessStart = Date.now();
+    try {
+      finalText = await postprocessTranscript(ctx, result.text, config);
+      postprocessMs = Date.now() - postprocessStart;
+      postprocessUsed = finalText.trim() !== result.text.trim();
+    } catch (error) {
+      postprocessMs = Date.now() - postprocessStart;
+      ctx.ui.notify(
+        `Voice postprocess failed; inserting raw transcript. ${error instanceof Error ? error.message : String(error)}`,
+        "warning",
+      );
+    }
+  }
+
+  ctx.ui.setStatus("voice-input", undefined);
+  appendToEditor(ctx, finalText);
   ctx.ui.notify(
-    `Voice text inserted. audio=${(durationMs / 1000).toFixed(2)}s decode=${decodeMs}ms asr=${result.timings.totalMs}ms packets=${result.packets}`,
+    `Voice text inserted. audio=${(durationMs / 1000).toFixed(2)}s decode=${decodeMs}ms asr=${result.timings.totalMs}ms${
+      config.postprocessEnabled ? ` postprocess=${postprocessMs}ms${postprocessUsed ? " polished" : ""}` : ""
+    } packets=${result.packets}`,
     "info",
   );
 }
@@ -722,8 +1012,11 @@ function setupHelp(config = getConfig()): string {
   return [
     "pi Voice Input setup:",
     "- Current provider: VolcEngine WebSocket ASR",
+    `- Config file: ${config.configPath}`,
     `- API key: ${config.apiKey ? "set" : "missing"}`,
+    "- To create/update the JSON config file, run: /voice init",
     "- To save/update the key, run: /voice key",
+    `- Polish: ${config.postprocessEnabled ? config.postprocessModel : "disabled"}`,
     `- Get/create a VolcEngine Speech API key here: ${VOLC_API_KEY_URL}`,
     "- After saving the key, run: /voice config",
   ].join("\n");
@@ -734,12 +1027,12 @@ async function configureApiKey(ctx: ExtensionContext, providedKey = "") {
 
   if (!apiKey) {
     if (!ctx.hasUI) {
-      ctx.ui.notify(`Run /voice key in interactive pi, or get a key from ${VOLC_API_KEY_URL} and set VOLC_API_KEY.`, "error");
+      ctx.ui.notify(`Run /voice key in interactive pi, or edit ${CONFIG_PATH}. Get a key from ${VOLC_API_KEY_URL}.`, "error");
       return;
     }
     ctx.ui.notify(`Get/create a VolcEngine Speech API key here:\n${VOLC_API_KEY_URL}`, "info");
     const current = getConfig().apiKey;
-    const placeholder = current ? "Paste a new VolcEngine API key (current key is already set)" : "Paste VOLC_API_KEY";
+    const placeholder = current ? "Paste a new VolcEngine API key (current key is already set)" : "Paste VolcEngine API key";
     apiKey = (await ctx.ui.input("VolcEngine API key", placeholder))?.trim() ?? "";
   }
 
@@ -748,25 +1041,21 @@ async function configureApiKey(ctx: ExtensionContext, providedKey = "") {
     return;
   }
 
-  writePrivateEnvValue("VOLC_API_KEY", apiKey);
-  ctx.ui.notify("VolcEngine API key saved for pi voice input. Run /voice config to verify it is detected.", "info");
+  writeConfigApiKey(apiKey);
+  ctx.ui.notify(`VolcEngine API key saved in ${CONFIG_PATH}. Run /voice config to verify it is detected.`, "info");
 }
 
 function configSummary(config: VoiceConfig): string {
+  const recorderExecutable = commandExists("pw-record") ? "pw-record" : commandExists("arecord") ? "arecord" : "";
+  const currentDevice = recorderExecutable ? recordingDeviceName(config, recorderExecutable) : "no recorder found";
   return [
     "Voice input config:",
-    `- api key: ${config.apiKey ? "set" : "missing"} (update with /voice key)`,
-    `- ws url: ${config.wsUrl}`,
-    `- resource id: ${config.resourceId}`,
-    `- language: ${config.language || "auto"}`,
-    `- recorder target: ${config.recorderTarget || "PipeWire/default"}`,
-    `- segment: ${config.segmentMs}ms`,
-    `- recordings: ${config.recordingsDir}`,
-    `- state: ${config.statePath}`,
-    `- shortcut: ${config.shortcut}`,
-    "Run /voice key to save/update the current provider API key.",
+    `- config file: ${config.configPath}${existsSync(config.configPath) ? "" : " (missing; run /voice init to create it)"}`,
+    `- volcApiKey: ${config.apiKey ? "set" : "missing"} (update with /voice key)`,
+    `- polishModel: ${config.postprocessEnabled ? config.postprocessModel : "disabled"}`,
+    `- current recording device: ${currentDevice}`,
+    "Config keys: volcApiKey, polishModel. Leave polishModel empty to disable polish.",
     `VolcEngine API key URL: ${VOLC_API_KEY_URL}`,
-    "Config files checked: ~/.pi/agent/voice-input.env, package .env, current .env; shell env overrides them.",
   ].join("\n");
 }
 
@@ -786,7 +1075,7 @@ export default function (pi: ExtensionAPI) {
   });
 
   pi.registerCommand("voice", {
-    description: "Voice input: start | stop | status | toggle | cancel | config | key | help",
+    description: "Voice input: start | stop | status | toggle | cancel | config | init | key | help",
     handler: async (args, ctx) => {
       const input = (args || "toggle").trim();
       const action = (input.split(/\s+/, 1)[0] || "toggle").toLowerCase();
@@ -814,6 +1103,11 @@ export default function (pi: ExtensionAPI) {
           ctx.ui.notify(configSummary(getConfig()), "info");
           return;
         }
+        if (action === "init") {
+          const created = ensureConfigFile();
+          ctx.ui.notify(`${created ? "Created" : "Updated"} voice input config: ${CONFIG_PATH}`, "info");
+          return;
+        }
         if (["key", "api-key", "apikey", "setup", "configure"].includes(action)) {
           await configureApiKey(ctx, rest);
           return;
@@ -826,7 +1120,7 @@ export default function (pi: ExtensionAPI) {
           await toggleRecording(ctx);
           return;
         }
-        ctx.ui.notify("Usage: /voice start | stop | status | toggle | cancel | config | key | help", "error");
+        ctx.ui.notify("Usage: /voice start | stop | status | toggle | cancel | config | init | key | help", "error");
       } catch (error) {
         ctx.ui.setStatus("voice-input", undefined);
         ctx.ui.notify(`Voice command error: ${error instanceof Error ? error.message : String(error)}`, "error");
@@ -842,7 +1136,8 @@ export default function (pi: ExtensionAPI) {
     ctx.ui.notify(
       [
         `Voice input loaded: ${startupConfig.shortcut} toggles recording.`,
-        "API key is missing. Run /voice key to set it up.",
+        "API key is missing. Run /voice key to set it up, or edit the JSON config file.",
+        `Config file: ${startupConfig.configPath}`,
         `Get/create a VolcEngine Speech API key here: ${VOLC_API_KEY_URL}`,
       ].join("\n"),
       "warning",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-voice-input",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "provider-extensible voice input extension for pi",
   "type": "module",
   "keywords": [
@@ -12,9 +12,10 @@
     "asr"
   ],
   "license": "MIT",
+  "author": "tr-nc",
   "repository": {
     "type": "git",
-    "url": "git+ssh://git@github.com/tr-nc/pi-voice-input.git"
+    "url": "git+https://github.com/tr-nc/pi-voice-input.git"
   },
   "bugs": {
     "url": "https://github.com/tr-nc/pi-voice-input/issues"
@@ -22,7 +23,6 @@
   "homepage": "https://github.com/tr-nc/pi-voice-input#readme",
   "files": [
     "extensions",
-    ".env.example",
     "README.md",
     "AGENTS.md"
   ],
@@ -35,6 +35,7 @@
     "ws": "^8.20.1"
   },
   "devDependencies": {
+    "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*",
     "@types/node": "^25.8.0",
@@ -42,10 +43,14 @@
     "typescript": "^6.0.3"
   },
   "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*"
   },
   "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
     "@earendil-works/pi-coding-agent": {
       "optional": true
     },

package/.env.example

@@ -1,27 +0,0 @@
-# Copy to ~/.pi/agent/voice-input.env or to this package as .env.
-# Do not commit real credentials.
-
-# Required for the current provider: VolcEngine speech API key.
-VOLC_API_KEY=
-
-# Optional ASR settings.
-VOLC_WS_URL=wss://openspeech.bytedance.com/api/v3/sauc/bigmodel_nostream
-VOLC_STREAM_RESOURCE_ID=volc.seedasr.sauc.duration
-ASR_LANGUAGE=
-ASR_PROMPT=
-STREAM_SEGMENT_MS=5000
-ASR_REQUEST_TIMEOUT_MS=90000
-
-# Optional recorder settings.
-# Leave empty to let PipeWire choose the default microphone.
-RECORDER_TARGET=
-RECORDING_FINALIZE_DELAY=0.1
-
-# Optional storage settings. Defaults to ~/.pi/agent/voice-input.
-VOICE_INPUT_HOME=~/.pi/agent/voice-input
-RECORDINGS_DIR=recordings
-RECORDER_STATE=recording.json
-RECORDER_LOG_DIR=logs
-
-# Optional shortcut. Default is Ctrl+Shift+R.
-VOICE_INPUT_SHORTCUT=ctrl+shift+r