@yandy0725/pi-ask-user 0.1.0 → 0.2.0

package/README.md

@@ -97,17 +97,43 @@ Effective order:
 
 1. Per-call `displayMode` parameter (if provided)
 2. `PI_ASK_USER_DISPLAY_MODE` (if set to `"overlay"` or `"inline"`)
-3. Fallback default: `"overlay"`
+3. Project config file `.pi/ask-user.json` `displayMode` field (if exists)
+4. User config file `~/.pi/agent/ask-user.json` `displayMode` field (if exists)
+5. Fallback default: `"overlay"`
 
 Unrecognised values are silently ignored and fall back to `"overlay"`.
 
+## Personal preferences via config files
+
+In addition to environment variables, you can use JSON config files:
+
+**Locations:**
+- User-level (global): `~/.pi/agent/ask-user.json`
+- Project-level: `.pi/ask-user.json`
+
+Fields in the project-level file override same-named fields in the user-level file. Priority: call param > env var > project config > user config > default.
+
+**Example `~/.pi/agent/ask-user.json`:**
+
+```json
+{
+  "displayMode": "inline",
+  "overlayToggleKey": "alt+h",
+  "commentToggleKey": "alt+c"
+}
+```
+
+All fields are optional. Missing files or malformed JSON are silently ignored, equivalent to no configuration.
+
 ### Shortcuts
 
 Effective order for both `overlayToggleKey` and `commentToggleKey`:
 
 1. Per-call parameter (if provided)
 2. Matching env var (`PI_ASK_USER_OVERLAY_TOGGLE_KEY` / `PI_ASK_USER_COMMENT_TOGGLE_KEY`)
-3. Built-in defaults: `alt+o` and `ctrl+g`
+3. Project config file `.pi/ask-user.json` (if exists)
+4. User config file `~/.pi/agent/ask-user.json` (if exists)
+5. Built-in defaults: `alt+o` and `ctrl+g`
 
 Pass `"off"`, `"none"`, or `"disabled"` (at any level) to disable the shortcut entirely. Invalid specs are silently dropped and the next source is used. Specs follow the Pi-TUI [`KeyId`](https://github.com/earendil-works/pi-mono/blob/main/packages/tui/src/keys.ts) format: `[mod+]...key` where modifiers are `ctrl`, `shift`, `alt`, `super`, in any order, joined by `+` (e.g. `ctrl+g`, `alt+shift+x`, `escape`, `tab`).
 

package/README.zh.md

@@ -80,17 +80,43 @@ export PI_ASK_USER_COMMENT_TOGGLE_KEY=alt+c
 
 1. 每次调用时的 `displayMode` 参数（如提供）
 2. `PI_ASK_USER_DISPLAY_MODE`（如设置为 `"overlay"` 或 `"inline"`）
-3. 回退默认值：`"overlay"`
+3. 项目配置文件 `.pi/ask-user.json`（如存在）中的 `displayMode`
+4. 用户配置文件 `~/.pi/agent/ask-user.json`（如存在）中的 `displayMode`
+5. 回退默认值：`"overlay"`
 
 无法识别的值会被静默忽略并回退到 `"overlay"`。
 
+## 通过配置文件设置个人偏好
+
+除了环境变量，也可以通过 JSON 配置文件设置：
+
+**文件位置：**
+- 用户级（全局）：`~/.pi/agent/ask-user.json`
+- 项目级：`.pi/ask-user.json`
+
+项目级文件中的字段会覆盖用户级文件中同名字段。配置优先级：调用参数 > 环境变量 > 项目配置 > 用户配置 > 默认值。
+
+**示例 `~/.pi/agent/ask-user.json`：**
+
+```json
+{
+  "displayMode": "inline",
+  "overlayToggleKey": "alt+h",
+  "commentToggleKey": "alt+c"
+}
+```
+
+所有字段可选。文件不存在或 JSON 格式错误时静默忽略，等效于未配置。
+
 ### 快捷键
 
 `overlayToggleKey` 和 `commentToggleKey` 的生效优先级：
 
 1. 每次调用时的参数（如提供）
 2. 对应的环境变量（`PI_ASK_USER_OVERLAY_TOGGLE_KEY` / `PI_ASK_USER_COMMENT_TOGGLE_KEY`）
-3. 内置默认值：`alt+o` 和 `ctrl+g`
+3. 项目配置文件 `.pi/ask-user.json`（如存在）
+4. 用户配置文件 `~/.pi/agent/ask-user.json`（如存在）
+5. 内置默认值：`alt+o` 和 `ctrl+g`
 
 传入 `"off"`、`"none"` 或 `"disabled"`（任意级别）可以完全禁用快捷键。无效的键位格式会被静默丢弃，使用下一个来源。键位格式遵循 Pi-TUI 的 [`KeyId`](https://github.com/earendil-works/pi-mono/blob/main/packages/tui/src/keys.ts) 格式：`[mod+]...key`，修饰键为 `ctrl`、`shift`、`alt`、`super`，可任意顺序用 `+` 连接（如 `ctrl+g`、`alt+shift+x`、`escape`、`tab`）。
 

package/index.ts

@@ -5,7 +5,10 @@
  * and a custom box border instead of manual ANSI box drawing.
  */
 
+import { existsSync, readFileSync } from "node:fs";
 import { createRequire } from "node:module";
+import { homedir } from "node:os";
+import { join } from "node:path";
 import type { ExtensionAPI, Theme } from "@earendil-works/pi-coding-agent";
 import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
 import {
@@ -15,6 +18,7 @@ import {
 	Editor,
 	type EditorTheme,
 	fuzzyFilter,
+	isKeyRelease,
 	Key,
 	type Keybinding,
 	type KeybindingsManager,
@@ -317,12 +321,58 @@ function buildShortcut(spec: string): ResolvedShortcut {
 	};
 }
 
+interface AskUserConfig {
+	displayMode?: string;
+	overlayToggleKey?: string;
+	commentToggleKey?: string;
+}
+
+function filterConfigFields(raw: Record<string, unknown>): Partial<AskUserConfig> {
+	const str = (v: unknown): string | undefined => (typeof v === "string" ? v : undefined);
+	return {
+		displayMode: typeof raw.displayMode === "string" ? raw.displayMode : undefined,
+		overlayToggleKey: str(raw.overlayToggleKey),
+		commentToggleKey: str(raw.commentToggleKey),
+	};
+}
+
+function loadAskUserConfig(cwd?: string): Partial<AskUserConfig> {
+	const homeDir = homedir();
+	const userConfigPath = join(homeDir, ".pi", "agent", "ask-user.json");
+
+	let config: Partial<AskUserConfig> = {};
+	try {
+		if (existsSync(userConfigPath)) {
+			const raw = readFileSync(userConfigPath, "utf-8");
+			config = filterConfigFields(JSON.parse(raw));
+		}
+	} catch {
+		// User config file missing or invalid — silently ignore.
+	}
+
+	if (cwd) {
+		const projectConfigPath = join(cwd, ".pi", "ask-user.json");
+		try {
+			if (existsSync(projectConfigPath)) {
+				const raw = readFileSync(projectConfigPath, "utf-8");
+				const projectConfig = filterConfigFields(JSON.parse(raw));
+				config = { ...config, ...projectConfig };
+			}
+		} catch {
+			// Project config file missing or invalid — silently ignore.
+		}
+	}
+
+	return config;
+}
+
 function resolveShortcut(
 	paramValue: string | null | undefined,
 	envValue: string | undefined,
+	configValue: string | null | undefined,
 	defaultSpec: string,
 ): ResolvedShortcut {
-	const candidates: Array<string | null | undefined> = [paramValue, envValue, defaultSpec];
+	const candidates: Array<string | null | undefined> = [paramValue, envValue, configValue, defaultSpec];
 	for (const raw of candidates) {
 		const normalized = normalizeShortcutSpec(raw);
 		if (normalized === undefined) continue; // not provided, fall through
@@ -1565,19 +1615,24 @@ export default function (pi: ExtensionAPI) {
 				commentToggleKey,
 				timeout,
 			} = params as AskParams;
+			const config = loadAskUserConfig(ctx.cwd);
+			const configDisplayMode: AskDisplayMode | undefined =
+				config.displayMode === "overlay" || config.displayMode === "inline" ? config.displayMode : undefined;
 			const envMode = process.env.PI_ASK_USER_DISPLAY_MODE;
 			const envDisplayMode: AskDisplayMode | undefined =
 				envMode === "overlay" || envMode === "inline" ? envMode : undefined;
-			const effectiveDisplayMode: AskDisplayMode = displayMode ?? envDisplayMode ?? "overlay";
+			const effectiveDisplayMode: AskDisplayMode = displayMode ?? envDisplayMode ?? configDisplayMode ?? "overlay";
 			const shortcuts: ResolvedAskShortcuts = {
 				overlayToggle: resolveShortcut(
 					overlayToggleKey,
 					process.env.PI_ASK_USER_OVERLAY_TOGGLE_KEY,
+					config.overlayToggleKey,
 					DEFAULT_OVERLAY_TOGGLE_KEY,
 				),
 				commentToggle: resolveShortcut(
 					commentToggleKey,
 					process.env.PI_ASK_USER_COMMENT_TOGGLE_KEY,
+					config.commentToggleKey,
 					DEFAULT_COMMENT_TOGGLE_KEY,
 				),
 			};
@@ -1669,6 +1724,12 @@ export default function (pi: ExtensionAPI) {
 				if (effectiveDisplayMode === "overlay" && !overlayToggle.disabled && typeof ctx.ui.onTerminalInput === "function") {
 					removeOverlayInputListener = ctx.ui.onTerminalInput((data) => {
 						if (!overlayToggle.matches(data) || !overlayHandle) return undefined;
+						// Ignore Kitty keyboard protocol key release events.
+						// matchesKittySequence ignores event type, so both press (:1u)
+						// and release (:3u) events match the same key binding. Without
+						// this filter, releasing the toggle key chord would immediately
+						// re-show a just-hidden overlay, causing a visible flicker.
+						if (isKeyRelease(data)) return undefined;
 						const nextHidden = !overlayHandle.isHidden();
 						overlayHandle.setHidden(nextHidden);
 						if (nextHidden && !hasAnnouncedHide) {

package/package.json

@@ -3,7 +3,7 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"description": "Interactive ask_user tool for pi-coding-agent with searchable split-pane selection UI, multi-select, and freeform input",
 	"license": "MIT",
 	"repository": {