@zhuxixi/pi-agent-board 0.3.1 → 0.4.0

package/docs/superpowers/specs/2026-08-22-cwd-favorites-design.md

@@ -0,0 +1,131 @@
+# Spec: Launch 对话框 cwd 常用目录榜（频率排名 + 模糊补全）
+
+- Date: 2026-08-22
+- Status: draft（待 review）
+
+## Background
+
+Ctrl+N 打开 launch 对话框后，`cwd` 字段进入目录选择器，目前只能从 `~` 开始逐层
+浏览 + 输入过滤（`src/core/launch-options.mjs` 的 `listDirectorySuggestions`，
+`src/ui/dashboard.ts` 的 launch picker）。launch-prefs.json 只记忆上一次的 cwd，
+没有「常用目录」概念。
+
+本机现状（2026-08-22 实测）：agent-board 共 177 个 view，cwd 分布高度集中——
+`/home/elling` 107 次、`zima-blue-cli` 20、`jfox` 17、`.pi/agent/extensions` 10、
+`pi-agent-board` 10，其余个位数。用户每次起 session 都要手动浏览目录，重复劳动。
+
+用户需求：按**真实使用频率自动排名**的候选目录榜，用得越多排越前；纯键盘快速
+选择；并且输入时能做**路径补全**（输入 `jfox` → 出现完整路径 → tab/回车补全），
+类似 zsh 的 cd 补全体验。
+
+## Goals
+
+1. 持久化的 cwd 使用统计：每次成功发起 session 时对 cwd 计数 +1；统计独立于
+   session 生命周期（删 view 不减计数）。
+2. 首次使用时从现有 view 的 meta.json 一次性导入计数，立即有榜单数据。
+3. cwd 选择器交互升级：
+   - 打开选择器（未输入）时显示频率榜 Top 8，↑↓ 选 + 回车直接确认；
+   - 输入时先对候选榜做大小写不敏感子串匹配（路径任意部分）；
+   - 有匹配 → 候选模式显示匹配项；无匹配 → 回落现有文件系统浏览（旧能力完整保留）；
+   - tab 把高亮项的完整路径补全进输入框（picker 保持打开，可继续微调），
+     回车最终确认；输入框内容本身就是有效路径时回车直接生效。
+4. 候选行显示 `~` 简写路径 + 使用次数（如 `107×`）。
+
+## Non-goals
+
+- 不做手动收藏/置顶编辑（无配置文件 UI）。
+- 不做模糊 subsequence 匹配（先做子串，不够再升级）。
+- 不改 launch-prefs.json 结构。
+- 不改 launch 对话框的其他字段（model/thinking/action）。
+
+## Design
+
+### 新模块：`src/core/cwd-stats.mjs`
+
+- 新文件 `~/.pi/agent/agent-board/cwd-stats.json`（root 由现有
+  `paths.mjs` 的 `defaultRoot()` 派生，尊重 `$AGENT_BOARD_ROOT`）：
+
+```json
+{
+  "version": 1,
+  "entries": {
+    "/home/elling": { "count": 107, "lastUsed": 1756332000000 }
+  }
+}
+```
+
+- `paths.mjs` 增加 `cwdStatsPath(root)`，风格与 `launchPrefsPath` 一致。
+- 函数：
+  - `readCwdStats(root)`：缺失/损坏 → 返回空 entries（沿用 store.mjs 的容错读风格）。
+  - `seedCwdStatsFromViews(root)`：仅当 cwd-stats.json 不存在时执行；遍历
+    roster 全部 view 的 meta.json，按 cwd 聚合计数，lastUsed 取该 cwd 下 view 的
+    updatedAt 最大值（缺失则用当前时间）；原子写（`atomicWriteJson`）。
+  - `recordCwdLaunch(root, cwd)`：count +1、lastUsed 更新，原子写；cwd 非法
+    （空/不存在）直接忽略。
+  - `rankedCwdCandidates(root, limit)`：count 降序、lastUsed 降序；末尾始终补
+    home 目录兜底（若不在榜内则 count 0 排最后），保证「用户根目录」永远可一键选。
+- 写入用 `src/core/atomic.mjs` 的 `atomicWriteJson`（temp + rename，防并发写坏），
+  与 board 现有 meta.json 写入同款。
+
+### 埋点
+
+- `src/ui/dashboard.ts` 的 `submitDispatch`：`res.ok` 分支内
+  `recordCwdLaunch(root, launchCwd)`，try/catch 尽力而为，失败不影响派发。
+- lazy seed：launch 对话框首次打开（`openLaunchDialog`）时若 cwd-stats.json
+  不存在则调用 `seedCwdStatsFromViews`（同步、一次性、容错）。
+
+### 选择器交互
+
+`LaunchState` 增加字段：
+- `cwdRanked: {path, count}[]`：打开 picker 时由 `rankedCwdCandidates(root, 8)` 生成；
+- `cwdPickerMode: "favorites" | "browse"`：候选模式 / 文件系统浏览模式。
+
+行为规则（`openLaunchPicker("cwd")` 与 `handleLaunchPickerKey`）：
+
+| 输入（cwdQuery） | 模式 | 建议列表 |
+| --- | --- | --- |
+| 空 | favorites | 频率榜 Top 8，首项高亮 |
+| 非空，候选榜有子串匹配（大小写不敏感、路径任意部分） | favorites | 匹配项（保持排名序） |
+| 非空，无匹配 | browse | 现有 `listDirectorySuggestions` 文件系统浏览 |
+
+- 打开 picker 时 cwdQuery 置空（不再 seed 成 `~`）；在 launch 主对话框 cwd 字段上
+  直接打字进入 picker 时，query = 已输入字符（现有 type-to-jump 行为保留）。
+  输入 `~` 等无候选匹配时自然进入 browse 模式，旧浏览能力保留。
+- tab（favorites 模式）：`cwdQuery = 高亮项完整路径`，picker 保持打开；
+  此时输入框即完整路径，回车经现有 `resolveDirectoryValue` 直接生效。
+- 回车（favorites 模式）：选中高亮项。
+- esc：关闭 picker（现有行为）。
+- ↑↓：移动高亮（现有逻辑复用）。
+
+### 渲染
+
+- favorites 模式候选行：`displayPath(value)`（`~` 简写）+ 右侧 dim 次数
+  （`{count}×`）；browse 模式渲染不变。
+- 底部提示区分文案：
+  - favorites：`常用目录 · type to search · tab complete · enter choose · esc back`
+  - browse：现有 `type to filter folders · enter choose · esc back`
+
+## Error handling
+
+- 统计读写全部容错：损坏的 cwd-stats.json 视为空表，永不抛到 UI。
+- seed 与 record 的失败静默忽略（console 调试输出可选）。
+- 榜单为空（无 stats、无 home）时 picker 直接进入 browse 模式，行为与现状一致。
+
+## Testing
+
+- `test/cwd-stats.test.mjs`（新）：seed 从 views 导入、record 累加与 lastUsed、
+  排序（count 优先、lastUsed tie-break）、损坏文件容错、home 兜底、空表行为。
+- 候选匹配逻辑（新函数，放 launch-options.mjs 或 cwd-stats.mjs）：大小写不敏感、
+  路径任意部分匹配、无匹配判定。
+- `test/dashboard-render.test.mjs`：repo 现状无 DashboardComponent 单测 harness，picker
+  渲染断言由 Task 5 手工验收覆盖（路径 + 次数、browse 模式渲染不变）。
+- 所有测试用 tmp dir 作 root（沿 paths.mjs「显式 root 可测」约定）。
+
+## Verification
+
+- 启动后打开 launch 对话框 cwd 选择器：Top 榜应为 `~`（107×）、zima-blue-cli 等，
+  与现有 view 统计一致。
+- 输入 `jfox`：`~/git-repo/github/jfox` 出现在榜中；tab 补全完整路径；回车发起
+  session；再次打开选择器 jfox 计数 +1。
+- 输入 `~`：回落文件系统浏览，旧行为不变。
+- 删除某 view 后计数不变（stats 独立于 view 生命周期）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhuxixi/pi-agent-board",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Agent-board dashboard for Pi: dispatch, monitor, peek/reply, and attach to background Pi sessions.",
   "type": "module",
   "main": "./index.ts",

package/src/commands/agent-board.ts

@@ -88,6 +88,7 @@ export async function openDashboard(
 				};
 				const comp = new DashboardComponent(tui, theme as never, keybindings, wrappedDone, {
 					service,
+					root: service.getRoot(),
 					defaultCwd: ctx.cwd,
 					initialSelectedId: options.initialSelectedId,
 					availableModels,

package/src/core/cwd-stats.mjs

@@ -0,0 +1,112 @@
+/**
+ * Persistent cwd usage stats for the launch dialog's directory favorites.
+ *
+ * Counts every successfully dispatched session per cwd, independent of the
+ * view lifecycle (deleting a view does not decrement). The dashboard reads
+ * the ranked list for the cwd picker's favorites mode. Pure node, no Pi imports.
+ */
+import { existsSync } from "node:fs";
+import * as os from "node:os";
+import { atomicWriteJson, readJson } from "./atomic.mjs";
+import * as P from "./paths.mjs";
+import { readMeta, readRoster } from "./store.mjs";
+
+/**
+ * @typedef {Object} CwdStatsEntry
+ * @property {number} count
+ * @property {number} lastUsed  epoch ms, like meta.updatedAt
+ */
+
+/** @returns {{version: number, entries: Record<string, CwdStatsEntry>}} */
+function emptyStats() {
+	return { version: 1, entries: {} };
+}
+
+/** @param {string} root @returns {{version: number, entries: Record<string, CwdStatsEntry>}} */
+export function readCwdStats(root) {
+	const raw = readJson(P.cwdStatsPath(root), null);
+	if (!raw || typeof raw !== "object" || typeof raw.entries !== "object" || raw.entries === null) return emptyStats();
+	/** @type {Record<string, CwdStatsEntry>} */
+	const entries = {};
+	for (const [dir, entry] of Object.entries(raw.entries)) {
+		if (!entry || typeof entry.count !== "number") continue;
+		entries[dir] = {
+			count: Math.max(0, Math.floor(entry.count)),
+			lastUsed: typeof entry.lastUsed === "number" ? entry.lastUsed : 0,
+		};
+	}
+	return { version: 1, entries };
+}
+
+/**
+ * One-time seed: aggregate cwd counts from every roster view's meta.json.
+ * No-op when cwd-stats.json already exists.
+ * @param {string} root
+ */
+export function seedCwdStatsFromViews(root) {
+	if (existsSync(P.cwdStatsPath(root))) return;
+	/** @type {Record<string, CwdStatsEntry>} */
+	const entries = {};
+	for (const viewId of readRoster(root).views ?? []) {
+		const meta = readMeta(root, viewId);
+		const cwd = meta?.cwd;
+		if (!cwd) continue;
+		const lastUsed = typeof meta.updatedAt === "number" ? meta.updatedAt : Date.now();
+		const existing = entries[cwd];
+		if (existing) {
+			existing.count += 1;
+			existing.lastUsed = Math.max(existing.lastUsed, lastUsed);
+		} else {
+			entries[cwd] = { count: 1, lastUsed };
+		}
+	}
+	atomicWriteJson(P.cwdStatsPath(root), { version: 1, entries });
+}
+
+/**
+ * Seed when the stats file is missing; tolerate every failure (dashboard UX
+ * must never break because of stats bookkeeping).
+ * @param {string} root
+ */
+export function ensureCwdStatsSeeded(root) {
+	if (existsSync(P.cwdStatsPath(root))) return;
+	try {
+		seedCwdStatsFromViews(root);
+	} catch {
+		/* best effort */
+	}
+}
+
+/**
+ * Record one successful dispatch for `cwd`. Invalid dirs are ignored.
+ * @param {string} root @param {string} cwd
+ */
+export function recordCwdLaunch(root, cwd) {
+	if (!cwd || !existsSync(cwd)) return;
+	const stats = readCwdStats(root);
+	const existing = stats.entries[cwd] ?? { count: 0, lastUsed: 0 };
+	stats.entries[cwd] = { count: existing.count + 1, lastUsed: Date.now() };
+	atomicWriteJson(P.cwdStatsPath(root), stats);
+}
+
+/**
+ * Ranked candidates: count desc, then lastUsed desc; home appended at the
+ * end when absent so the user's home dir is always one keystroke away.
+ * @param {string} root @param {number=} limit
+ * @returns {Array<{path: string, count: number}>}
+ */
+export function rankedCwdCandidates(root, limit = 8) {
+	const stats = readCwdStats(root);
+	const rows = Object.entries(stats.entries).map(([dir, entry]) => ({
+		path: dir,
+		count: entry.count,
+		lastUsed: entry.lastUsed,
+	}));
+	rows.sort((a, b) => b.count - a.count || b.lastUsed - a.lastUsed);
+	const out = rows.slice(0, Math.max(1, limit)).map(({ path, count }) => ({ path, count }));
+	const home = os.homedir();
+	if (out.some((entry) => entry.path === home)) return out;
+	const homeRow = rows.find((entry) => entry.path === home);
+	out.push(homeRow ? { path: home, count: homeRow.count } : { path: home, count: 0 });
+	return out;
+}

package/src/core/launch-options.mjs

@@ -315,3 +315,50 @@ function existsDir(dir) {
 		return false;
 	}
 }
+
+/**
+ * Keep only candidates whose path is an existing directory.
+ * @param {CwdCandidate[]} candidates
+ * @returns {CwdCandidate[]}
+ */
+export function existingCwdCandidates(candidates) {
+	return candidates.filter((entry) => existsDir(entry.path));
+}
+
+/**
+ * @typedef {Object} CwdCandidate
+ * @property {string} path
+ * @property {number} count
+ */
+
+/**
+ * Filter ranked cwd candidates by case-insensitive substring match anywhere
+ * in the path (empty query keeps the full ranked list).
+ * @param {CwdCandidate[]} candidates
+ * @param {string} query
+ * @returns {CwdCandidate[]}
+ */
+export function filterCwdCandidates(candidates, query) {
+	const q = String(query ?? "").trim().toLowerCase();
+	if (!q) return candidates;
+	return candidates.filter((entry) => entry.path.toLowerCase().includes(q));
+}
+
+/**
+ * Decide cwd picker mode + suggestions for a query: favorites when the query
+ * is empty or matches ranked candidates, filesystem browse otherwise.
+ * @param {string} query
+ * @param {CwdCandidate[]} ranked
+ * @param {string} baseCwd
+ * @returns {{mode: "favorites"|"browse", suggestions: string[]}}
+ */
+export function nextCwdPickerState(query, ranked, baseCwd) {
+	if (!ranked || ranked.length === 0) {
+		return { mode: "browse", suggestions: listDirectorySuggestions(query, baseCwd) };
+	}
+	const matches = filterCwdCandidates(ranked, query);
+	if (String(query ?? "").trim() === "" || matches.length > 0) {
+		return { mode: "favorites", suggestions: matches.map((entry) => entry.path) };
+	}
+	return { mode: "browse", suggestions: listDirectorySuggestions(query, baseCwd) };
+}

package/src/core/paths.mjs

@@ -21,6 +21,8 @@ export const rosterPath = (root) => path.join(root, "roster.json");
 export const launchPrefsPath = (root) => path.join(root, "launch-prefs.json");
 /** @param {string} root */
 export const gcHistoryPath = (root) => path.join(root, "gc-history.jsonl");
+/** @param {string} root */
+export const cwdStatsPath = (root) => path.join(root, "cwd-stats.json");
 
 /** @param {string} root */
 export const viewsDir = (root) => path.join(root, "views");

package/src/runtime/service.mjs

@@ -763,6 +763,10 @@ export function createService(opts) {
 			return { ok: true, viewId: meta.id, reused: false };
 		},
 
+		getRoot() {
+			return root;
+		},
+
 		getLaunchPrefs() {
 			return readLaunchPrefs(root);
 		},

package/src/ui/dashboard.ts

@@ -17,11 +17,14 @@ import {
 	canonicalModelRef,
 	clampThinkingLevel,
 	listDirectorySuggestions,
+	existingCwdCandidates,
+	nextCwdPickerState,
 	resolveDirectoryValue,
 	resolveLaunchContext,
 	supportedThinkingLevels,
 } from "../core/launch-options.mjs";
 import { createPrewarmScheduler } from "../core/prewarm-schedule.mjs";
+import { ensureCwdStatsSeeded, rankedCwdCandidates, recordCwdLaunch } from "../core/cwd-stats.mjs";
 import { filterRows, groupRowsByFolder, rowState, stateGlyph } from "../core/rows.mjs";
 import { loadSessionView } from "../core/session-view.mjs";
 import { GROUP_LABELS } from "../core/types.mjs";
@@ -81,6 +84,11 @@ interface InputNotice {
 	expiresAt: number;
 }
 
+interface CwdCandidate {
+	path: string;
+	count: number;
+}
+
 interface LaunchState {
 	fieldIndex: number;
 	picker: LaunchPicker;
@@ -89,6 +97,8 @@ interface LaunchState {
 	cwdQuery: string;
 	cwdSuggestions: string[];
 	cwdSuggestionIndex: number;
+	cwdRanked: CwdCandidate[];
+	cwdPickerMode: "favorites" | "browse";
 	choices: LaunchChoice[];
 	scopeSource: "scoped" | "all";
 	model: LaunchModel | null;
@@ -102,6 +112,7 @@ interface LaunchState {
 
 export interface DashboardDeps {
 	service: Service;
+	root: string;
 	defaultCwd: string;
 	availableModels: LaunchModel[];
 	currentModel: LaunchModel | null;
@@ -562,11 +573,24 @@ export class DashboardComponent implements Component {
 			launch.picker = null;
 			return;
 		}
+		if (launch.picker === "cwd" && matchesKey(data, Key.tab)) {
+			if (launch.cwdPickerMode === "favorites" && launch.cwdSuggestions.length > 0) {
+				const completed = launch.cwdSuggestions[launch.cwdSuggestionIndex] ?? launch.cwdSuggestions[0];
+				launch.cwdQuery = completed;
+				const state = nextCwdPickerState(launch.cwdQuery, launch.cwdRanked, launch.cwd);
+				launch.cwdPickerMode = state.mode;
+				launch.cwdSuggestions = state.suggestions;
+				launch.cwdSuggestionIndex = Math.max(0, state.suggestions.indexOf(completed));
+			}
+			return;
+		}
 		if (launch.picker === "cwd") {
 			const next = this.applyLaunchQueryInput(launch.cwdQuery, data);
 			if (next !== null) {
 				launch.cwdQuery = next;
-				launch.cwdSuggestions = listDirectorySuggestions(next, launch.cwd);
+				const state = nextCwdPickerState(next, launch.cwdRanked, launch.cwd);
+				launch.cwdPickerMode = state.mode;
+				launch.cwdSuggestions = state.suggestions;
 				launch.cwdSuggestionIndex = 0;
 			}
 			return;
@@ -611,6 +635,11 @@ export class DashboardComponent implements Component {
 		const prompt = this.input.trim();
 		if (!prompt) return this.toListMode();
 		const defaults = this.launchDefaults();
+		try {
+			ensureCwdStatsSeeded(this.deps.root);
+		} catch {
+			/* best effort: favorites degrade to browse mode */
+		}
 		this.launch = this.buildLaunchState(defaults.cwd, defaults.model, defaults.thinking);
 		this.mode = "launch";
 		this.inputNotice = null;
@@ -647,7 +676,6 @@ export class DashboardComponent implements Component {
 			thinkingOptions: ThinkingLevel[];
 			scopeSource: "scoped" | "all";
 		};
-		const initialBrowserCwd = homeLaunchRoot(cwd);
 		const modelFiltered = filterLaunchChoices(context.choices, "");
 		const modelIndex = Math.max(0, modelFiltered.findIndex((choice) => sameLaunchModel(choice.model, context.selectedModel)));
 		const thinkingOptions = supportedThinkingLevels(context.selectedModel) as ThinkingLevel[];
@@ -658,9 +686,11 @@ export class DashboardComponent implements Component {
 			picker: null,
 			action: "background",
 			cwd,
-			cwdQuery: initialBrowserCwd,
-			cwdSuggestions: listDirectorySuggestions(initialBrowserCwd, cwd),
+			cwdQuery: "",
+			cwdSuggestions: [],
 			cwdSuggestionIndex: 0,
+			cwdRanked: [],
+			cwdPickerMode: "browse",
 			choices: context.choices,
 			scopeSource: context.scopeSource,
 			model: context.selectedModel,
@@ -678,8 +708,16 @@ export class DashboardComponent implements Component {
 		if (!launch) return;
 		launch.picker = picker;
 		if (picker === "cwd") {
-			launch.cwdQuery = seed ?? launch.cwdQuery ?? homeLaunchRoot(launch.cwd);
-			launch.cwdSuggestions = listDirectorySuggestions(launch.cwdQuery, launch.cwd);
+			try {
+				ensureCwdStatsSeeded(this.deps.root);
+				launch.cwdRanked = existingCwdCandidates(rankedCwdCandidates(this.deps.root, 8));
+			} catch {
+				launch.cwdRanked = [];
+			}
+			launch.cwdQuery = seed ?? "";
+			const state = nextCwdPickerState(launch.cwdQuery, launch.cwdRanked, launch.cwd);
+			launch.cwdPickerMode = state.mode;
+			launch.cwdSuggestions = state.suggestions;
 			launch.cwdSuggestionIndex = 0;
 			return;
 		}
@@ -794,6 +832,11 @@ export class DashboardComponent implements Component {
 		if (!res.ok) this.notice(res.error ?? "Dispatch failed", "error");
 		else {
 			this.lastLaunchPrefs = { ...this.deps.service.getLaunchPrefs?.(), cwd: launchCwd, model: launchModel, thinkingLevel: launchThinking };
+			try {
+				recordCwdLaunch(this.deps.root, launchCwd);
+			} catch {
+				/* best effort: stats must never block dispatch */
+			}
 			try {
 				this.deps.service.saveLaunchPrefs?.(this.lastLaunchPrefs);
 			} catch {
@@ -1474,9 +1517,19 @@ export class DashboardComponent implements Component {
 		lines.push("");
 		if (launch.picker === "cwd") {
 			lines.push(t.fg("warning", `cwd› ${singleLineInput(launch.cwdQuery)}${cursor()}`));
-			lines.push(...this.renderLaunchSuggestions(inner, launch.cwdSuggestions, launch.cwdSuggestionIndex, (value) => displayPath(value)));
-			lines.push("");
-			lines.push(t.fg("dim", "type to filter folders · enter choose · esc back"));
+			if (launch.cwdPickerMode === "favorites") {
+				const counts = new Map(launch.cwdRanked.map((entry) => [entry.path, entry.count]));
+				lines.push(...this.renderLaunchSuggestions(inner, launch.cwdSuggestions, launch.cwdSuggestionIndex, (value) => {
+					const count = counts.get(value) ?? 0;
+					return `${displayPath(value)}${count > 0 ? `  ${count}×` : ""}`;
+				}));
+				lines.push("");
+				lines.push(t.fg("dim", "常用目录 · type to search · tab complete · enter choose · esc back"));
+			} else {
+				lines.push(...this.renderLaunchSuggestions(inner, launch.cwdSuggestions, launch.cwdSuggestionIndex, (value) => displayPath(value)));
+				lines.push("");
+				lines.push(t.fg("dim", "type to filter folders · enter choose · esc back"));
+			}
 		} else if (launch.picker === "model") {
 			lines.push(t.fg("warning", `model› ${singleLineInput(launch.modelQuery)}${cursor()}`));
 			lines.push(...this.renderLaunchSuggestions(inner, launch.modelFiltered, launch.modelIndex, (choice) => `${formatLaunchModel(choice.model)}${choice.thinkingLevel ? ` · ${choice.thinkingLevel}` : ""}`));
@@ -1662,10 +1715,6 @@ function stripBracketedPaste(data: string): string {
 	return data.replace(/\x1b\[200~|\x1b\[201~/g, "");
 }
 
-function homeLaunchRoot(fallback: string): string {
-	return process.env.HOME || process.env.USERPROFILE ? "~" : fallback;
-}
-
 function renderCenteredBox(lines: string[], width: number, height: number, theme: ThemeLike): string[] {
 	const innerWidth = Math.max(20, Math.min(width - 6, Math.max(...lines.map((line) => visibleWidth(line)), 20)));
 	const boxWidth = Math.min(width, innerWidth + 4);