pi-voice-input 0.1.1 → 0.1.3

package/AGENTS.md

@@ -0,0 +1,94 @@
+# AGENTS.md
+
+Development workflow for this repo.
+
+## Project
+
+- Package: `pi-voice-input`
+- GitHub: `git@github.com:tr-nc/pi-voice-input.git`
+- npm: `pi-voice-input`
+- Main extension: `extensions/voice-input.ts`
+- Current provider: VolcEngine WebSocket ASR only
+- Provider architecture should remain extensible so more ASR providers can be added later.
+
+## 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`.
+- 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`
+
+## Before committing
+
+Run from the repo root:
+
+```bash
+npm install --package-lock=false
+npx tsc --noEmit --module NodeNext --moduleResolution NodeNext --target ES2022 --skipLibCheck --types node extensions/voice-input.ts
+PI_OFFLINE=1 pi -e ./extensions/voice-input.ts --list-models
+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
+package.json
+```
+
+Clean local generated files before committing:
+
+```bash
+rm -rf node_modules package-lock.json logs recordings
+```
+
+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}" \
+  --glob '!node_modules/**' --glob '!package-lock.json' . || true
+```
+
+Use conventional commit messages, for example:
+
+- `feat: add voice API key setup command`
+- `fix: handle missing recorder cleanly`
+- `docs: clarify npm installation`
+- `chore: update package metadata`
+
+## Release workflow
+
+1. Bump `package.json` version. npm versions are immutable.
+2. Validate with the commands above.
+3. Commit with a conventional commit message.
+4. Push to GitHub:
+
+```bash
+git push origin main
+```
+
+5. Publish to npm:
+
+```bash
+npm publish --access public
+```
+
+6. Update the local installed pi package and verify startup:
+
+```bash
+pi update npm:pi-voice-input
+PI_OFFLINE=1 pi --list-models
+```
+
+If testing a local checkout instead of the npm package, use:
+
+```bash
+pi -e ./extensions/voice-input.ts
+```
+
+Do not leave local development wrappers in `~/.pi/agent/extensions/voice-input.ts` when validating the npm installation path.

package/README.md

@@ -43,18 +43,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.
@@ -78,76 +66,18 @@ In pi, run:
 
 Paste your VolcEngine Speech API key into the prompt. The extension saves it for future sessions and keeps it out of your project files.
 
-Then verify:
-
-```text
-/voice config
-```
-
 You can get/manage the key here:
 
 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 key URL is also shown inside pi when the key is missing, when you run `/voice key`, and in `/voice help`:
 
-Manual fallback:
-
-```bash
-mkdir -p ~/.pi/agent
-cp .env.example ~/.pi/agent/voice-input.env
-$EDITOR ~/.pi/agent/voice-input.env
-```
-
-## 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=
-
-# Faster for post-recording batch transcription. Use 200 for realtime-like packet size.
-STREAM_SEGMENT_MS=5000
-ASR_REQUEST_TIMEOUT_MS=90000
-
-# 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
+Then verify:
 
-# 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:
@@ -166,6 +96,7 @@ Slash commands:
 /voice status   # show recorder state
 /voice config   # show effective non-secret config and whether API key is detected
 /voice key      # prompt for and save the current provider API key
+/voice help     # show setup help, including the explicit VolcEngine API key URL
 ```
 
 ## Notes
@@ -202,7 +133,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

@@ -22,6 +22,7 @@ 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 VOLC_API_KEY_URL = "https://console.volcengine.com/speech/new/setting/apikeys?projectName=default";
 const DEFAULT_SHORTCUT = Key.ctrlShift("r");
 
 const MSG_TYPE_CLIENT_FULL_REQUEST = 0b0001;
@@ -458,7 +459,7 @@ function missingCredentialsMessage(): string {
   return [
     "Missing VOLC_API_KEY for the current VolcEngine ASR provider.",
     "Run /voice key and paste your VolcEngine Speech API key.",
-    "API key settings: https://console.volcengine.com/speech/new/setting/apikeys?projectName=default",
+    `Get/create the key here: ${VOLC_API_KEY_URL}`,
     "Run /voice config to verify whether the key is detected.",
   ].join("\n");
 }
@@ -717,14 +718,26 @@ async function toggleRecording(ctx: ExtensionContext) {
   else await startRecording(ctx);
 }
 
+function setupHelp(config = getConfig()): string {
+  return [
+    "pi Voice Input setup:",
+    "- Current provider: VolcEngine WebSocket ASR",
+    `- API key: ${config.apiKey ? "set" : "missing"}`,
+    "- To save/update the key, run: /voice key",
+    `- Get/create a VolcEngine Speech API key here: ${VOLC_API_KEY_URL}`,
+    "- After saving the key, run: /voice config",
+  ].join("\n");
+}
+
 async function configureApiKey(ctx: ExtensionContext, providedKey = "") {
   let apiKey = providedKey.trim();
 
   if (!apiKey) {
     if (!ctx.hasUI) {
-      ctx.ui.notify("Run /voice key in interactive pi, or set VOLC_API_KEY in the environment.", "error");
+      ctx.ui.notify(`Run /voice key in interactive pi, or get a key from ${VOLC_API_KEY_URL} and set VOLC_API_KEY.`, "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";
     apiKey = (await ctx.ui.input("VolcEngine API key", placeholder))?.trim() ?? "";
@@ -752,6 +765,7 @@ function configSummary(config: VoiceConfig): string {
     `- state: ${config.statePath}`,
     `- shortcut: ${config.shortcut}`,
     "Run /voice key to save/update the current provider API key.",
+    `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");
 }
@@ -772,7 +786,7 @@ export default function (pi: ExtensionAPI) {
   });
 
   pi.registerCommand("voice", {
-    description: "Voice input: start | stop | status | toggle | cancel | config | key",
+    description: "Voice input: start | stop | status | toggle | cancel | config | key | help",
     handler: async (args, ctx) => {
       const input = (args || "toggle").trim();
       const action = (input.split(/\s+/, 1)[0] || "toggle").toLowerCase();
@@ -804,11 +818,15 @@ export default function (pi: ExtensionAPI) {
           await configureApiKey(ctx, rest);
           return;
         }
+        if (["help", "doctor"].includes(action)) {
+          ctx.ui.notify(setupHelp(getConfig()), "info");
+          return;
+        }
         if (action === "toggle" || action === "") {
           await toggleRecording(ctx);
           return;
         }
-        ctx.ui.notify("Usage: /voice start | stop | status | toggle | cancel | config | key", "error");
+        ctx.ui.notify("Usage: /voice start | stop | status | toggle | cancel | config | 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");
@@ -817,6 +835,17 @@ export default function (pi: ExtensionAPI) {
   });
 
   pi.on("session_start", (_event, ctx) => {
-    ctx.ui.notify(`Voice input loaded: ${startupConfig.shortcut} toggles recording.`, "info");
+    if (getConfig().apiKey) {
+      ctx.ui.notify(`Voice input loaded: ${startupConfig.shortcut} toggles recording.`, "info");
+      return;
+    }
+    ctx.ui.notify(
+      [
+        `Voice input loaded: ${startupConfig.shortcut} toggles recording.`,
+        "API key is missing. Run /voice key to set it up.",
+        `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.1",
+  "version": "0.1.3",
   "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": "https://github.com/tr-nc/pi-voice-input.git"
   },
   "bugs": {
     "url": "https://github.com/tr-nc/pi-voice-input/issues"
@@ -23,7 +24,8 @@
   "files": [
     "extensions",
     ".env.example",
-    "README.md"
+    "README.md",
+    "AGENTS.md"
   ],
   "pi": {
     "extensions": [