@andares/pi-toolkits 0.2.0 → 0.3.0

package/README.md

@@ -11,8 +11,8 @@
 [![pi >= 0.84](https://img.shields.io/badge/pi-%3E%3D0.84.0-blueviolet)](https://github.com/earendil-works/pi)
 [![GitHub](https://img.shields.io/badge/github-andares%2Fpi--toolkits-181717?logo=github)](https://github.com/andares/pi-toolkits)
 
-一句话介绍:目前包含三个开箱即用的功能——**只读咨询模式** `ask`、**模型收藏** `favorites`、**提示词暂存** `stash`,后续持续追加。
-Currently ships three ready-to-use capabilities — **ask mode**, **model favorites** and **prompt stash** — with more to come.
+一句话介绍:目前包含四个开箱即用的功能——**只读咨询模式** `ask`、**模型收藏** `favorites`、**提示词暂存** `stash`、**第三方代码评审** `third-review`,后续持续追加。
+Currently ships four ready-to-use capabilities — **ask mode**, **model favorites**, **prompt stash** and **third-party code review** — with more to come.
 
 ---
 
@@ -36,6 +36,7 @@ pi -e ./src/index.ts
 - `/ask` → footer 出现灰色 `ask` 状态,`write`/`edit` 被硬禁用
 - `/model`(或 `ctrl+l`)→ 选择器顶部出现收藏提示行
 - 输入框内按 `ctrl+alt+y` → 当前提示词被暂存并清空输入框
+- 完成一个开发任务后输入 `third-review` → 切换到评审模型执行查+修
 
 ---
 
@@ -46,6 +47,7 @@ pi -e ./src/index.ts
   - [🛡️ ask — 只读咨询模式](#ask)
   - [⭐ favorites — 模型收藏](#favorites)
   - [📥 stash — 提示词暂存](#stash)
+  - [🔎 review — 第三方代码评审](#review)
 - [开发 Development](#development)
 - [贡献 Contributing](#contributing)
 - [许可 License](#license)
@@ -61,6 +63,7 @@ pi -e ./src/index.ts
 | 🛡️ **ask** 只读咨询模式 | `/ask` | 进入只读问答模式,`write`/`edit` 硬禁用,`bash` 只读沙箱 |
 | ⭐ **favorites** 模型收藏 | `/model` 内 `ctrl+F` / `ctrl+J` | 收藏常用模型(加粗亮黄标记),`ctrl+p` 仅在收藏间循环 |
 | 📥 **stash** 提示词暂存 | `ctrl+alt+y` | 一段提示词的暂存槽,按键交换 / 连按两次暂存并清空输入框 |
+| 🔎 **review** 第三方代码评审 | `third-review` / `/third-review` | 召唤配置的评审模型,对刚完成的任务做查+修,重点检查「本轮需求实现 / 是否有遗漏 / 是否有错误」 |
 
 ---
 
@@ -137,6 +140,31 @@ pi -e ./src/index.ts
 
 ---
 
+## 🔎 review — 第三方代码评审
+
+<a name="review"></a>
+
+开发任务完成后,输入 `third-review`(或 `third review`、`/third-review`)召唤**另一个模型**以第三方身份,对刚完成的代码做「查 + 修」:评审模型拥有**完整工具权限**,确认的问题直接改,不是只读审计。评审回合留在当前会话记录里,评审完成后**会话保持评审模型**(不自动切回)。
+
+**评审提示词重点检查三点**(逐项给出结论):
+
+1. **本轮需求实现** —— 需求是否已完整、正确地实现,与需求描述是否一致
+2. **是否有遗漏** —— 功能点、边界情况、异常处理、兼容性、测试等
+3. **是否有错误** —— 逻辑错误、潜在 bug、类型/编译错误、安全与性能隐患等
+
+**评审模型配置**(`<agent-dir>/pi-toolkits-review.json`,默认 `~/.pi/agent/`):
+
+```json
+{ "model": "anthropic/claude-sonnet-4" }
+```
+
+- `/review-model` —— 查看/更换评审模型:弹出模型列表(标题显示当前配置),选中即写入;取消则不修改配置
+- **未配置 / 配置的模型已不可用**(如在 pi 的 models.json 里删掉了该模型)→ 提示「评审模型不存在」,弹出**可用模型选择列表**(与 `/model` 同源);选中后**写回配置并立即执行**
+- 任务仍在进行中(agent 未空闲)时触发 → 提示等待,不执行;同一时间只允许一个评审
+- footer 出现灰色 `review` 状态 = 已配置评审模型
+
+---
+
 ## 🛠️ 开发 Development
 
 <a name="development"></a>
@@ -160,6 +188,8 @@ src/
     │                     #           system prompt banner, tests
     ├── favorites/        # model favorites: selector + cycle patches,
     │                     #           persisted store, tests
+    ├── review/           # third-party review: input/command triggers,
+    │                     #           review-model config store, prompt, tests
     └── stash/            # prompt stash: hotkey state machine + tests
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andares/pi-toolkits",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Integrated toolkit extension for pi — currently provides ask mode (read-only Q&A); more features to come",
   "type": "module",
   "license": "MIT",
@@ -42,6 +42,7 @@
   "scripts": {
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "release": "node ./scripts/publish.mjs"
+    "release": "node ./scripts/publish.mjs",
+    "tag-current": "node ./scripts/tag-current.mjs"
   }
 }

package/src/features/review/constants.ts

@@ -0,0 +1,13 @@
+/**
+ * review feature — constants.
+ *
+ * The review-model config lives in `<agent-dir>/pi-toolkits-review.json`
+ * (same agent-dir convention as the favorites store) and holds a single
+ * model key `"provider/id"` — see store.ts.
+ */
+
+/** Config file name inside the pi agent dir. */
+export const REVIEW_FILE = "pi-toolkits-review.json";
+
+/** Footer status key shown while a review model is configured. */
+export const REVIEW_STATUS_KEY = "review";

package/src/features/review/index.ts

@@ -0,0 +1,232 @@
+/**
+ * review feature — third-review command.
+ *
+ * After a development task finishes, "summon another model" to review the
+ * just-completed work: the configured review model takes over the session
+ * (full tool access — this is check AND fix, not a read-only audit), runs a
+ * review turn, and the session then stays on that model (no auto-restore).
+ *
+ * Trigger paths (both share createReviewRunner()):
+ *  - bare message: typing exactly "third-review" / "third review" in the
+ *    input box (pi.on("input") interception, swallowed with "handled")
+ *  - slash command: /third-review
+ *
+ * Review-model config lives in `<agent-dir>/pi-toolkits-review.json`
+ * ("provider/id", see store.ts). When no model is configured, or the
+ * configured model is gone/unavailable (e.g. deleted from pi's models.json),
+ * the user is told the review model doesn't exist and is shown the available
+ * model list (ctx.ui.select, same getAvailable() source as /model); the pick
+ * is written back to the config and the review runs immediately.
+ *
+ * Guards: never fires while the agent is streaming (the review needs the
+ * just-finished work as context) and never runs two reviews concurrently.
+ */
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+	Theme,
+} from "@earendil-works/pi-coding-agent";
+import type { Api, Model } from "@earendil-works/pi-ai";
+import { REVIEW_STATUS_KEY } from "./constants.js";
+import { REVIEW_PROMPT, isReviewTrigger } from "./prompt.js";
+import { getReviewStore, modelKey, type ReviewStore } from "./store.js";
+
+/** Resolve the configured review model against the available model list. */
+export function resolveConfiguredModel(
+	ctx: ExtensionContext,
+	key: string | undefined,
+): Model<Api> | undefined {
+	if (!key) return undefined;
+	const slash = key.indexOf("/");
+	if (slash <= 0 || slash === key.length - 1) return undefined;
+	const provider = key.slice(0, slash);
+	const id = key.slice(slash + 1);
+	return ctx.modelRegistry
+		.getAvailable()
+		.find((m) => m.provider === provider && m.id === id);
+}
+
+/**
+ * Let the user pick a review model from the available list and persist the
+ * choice. Returns the picked model, or undefined when cancelled/unavailable.
+ *
+ * The picker title shows the current config so /review-model doubles as a
+ * view-and-change entry point; cancelling leaves the config untouched.
+ */
+export async function pickReviewModel(
+	ctx: ExtensionContext,
+	store: ReviewStore,
+): Promise<Model<Api> | undefined> {
+	// Dialog-capable UI exists in TUI and RPC modes (hasUI); json/print and
+	// headless contexts have no dialogs, so fall back to a manual-config hint.
+	if (!ctx.hasUI) {
+		ctx.ui.notify(
+			"third-review: 当前环境不支持模型选择对话框，请编辑 <agent-dir>/pi-toolkits-review.json 手动配置。",
+			"error",
+		);
+		return undefined;
+	}
+	const available = ctx.modelRegistry.getAvailable();
+	if (available.length === 0) {
+		ctx.ui.notify(
+			"third-review: 当前没有可用模型，请先在 pi 中配置模型。",
+			"error",
+		);
+		return undefined;
+	}
+	const configured = store.getModel();
+	// Same display source as the /model selector: name + [provider]/id.
+	const options = available.map((m) => `${m.name} (${m.provider}/${m.id})`);
+	const choice = await ctx.ui.select(
+		configured
+			? `选择评审模型 (当前: ${configured})`
+			: "选择评审模型 (third-review)",
+		options,
+	);
+	if (choice === undefined) {
+		ctx.ui.notify("third-review: 已取消，评审模型配置未变更。", "info");
+		return undefined;
+	}
+	const model = available[options.indexOf(choice)];
+	if (!model) return undefined;
+	store.setModel(modelKey(model));
+	return model;
+}
+
+/**
+ * Create the third-review runner bound to a pi instance.
+ *
+ * Exported separately from registerReview so tests can drive the flow with
+ * fake pi/ctx objects. The returned runner serializes concurrent triggers
+ * (one review at a time).
+ */
+export function createReviewRunner(
+	pi: ExtensionAPI,
+): (ctx: ExtensionContext) => Promise<void> {
+	let running = false;
+
+	return async (ctx) => {
+		if (running) {
+			ctx.ui.notify("third-review: 评审已在执行中，请稍候。", "warning");
+			return;
+		}
+		if (!ctx.isIdle()) {
+			ctx.ui.notify(
+				"third-review: 当前任务仍在进行中，请等待完成后再触发。",
+				"warning",
+			);
+			return;
+		}
+		running = true;
+		try {
+			const store = getReviewStore();
+			const configured = store.getModel();
+			let model = resolveConfiguredModel(ctx, configured);
+			if (!model) {
+				ctx.ui.notify(
+					configured
+						? `third-review: 配置的评审模型 ${configured} 不存在或不可用，请重新选择。`
+						: "third-review: 尚未配置评审模型，请选择。",
+					"warning",
+				);
+				model = await pickReviewModel(ctx, store);
+				if (!model) return;
+			}
+			const switched = await pi.setModel(model);
+			if (!switched) {
+				ctx.ui.notify(
+					`third-review: 无法切换到评审模型「${model.name}」（缺少 API key 或鉴权未配置）。`,
+					"error",
+				);
+				return;
+			}
+			ctx.ui.notify(
+				`third-review: 已切换到评审模型「${model.name}」执行评审（查+修）；评审完成后会话保持该模型。`,
+				"info",
+			);
+			pi.sendUserMessage(REVIEW_PROMPT);
+		} finally {
+			running = false;
+		}
+	};
+}
+
+export function registerReview(pi: ExtensionAPI): void {
+	const runReview = createReviewRunner(pi);
+
+	// Bare-message trigger: "third-review" / "third review" in the input box.
+	// Extension-injected messages are ignored so the runner's own prompts
+	// never re-trigger this path.
+	pi.on("input", (event, ctx) => {
+		if (event.source === "extension") {
+			return { action: "continue" };
+		}
+		if (isReviewTrigger(event.text)) {
+			// Fire-and-forget: the runner uses the live ctx proxy, so it is safe
+			// after this handler returns. A session switch mid-dialog can make
+			// the context assert-inactive; swallow that instead of leaking an
+			// unhandled rejection (a fresh extension instance owns the new
+			// session anyway).
+			void runReview(ctx).catch((error) => {
+				// pi-lens-ignore: no-console-except-error,console-statement, — deliberate degradation log
+				console.warn(
+					"[pi-toolkits/review] third-review aborted:",
+					error instanceof Error ? error.message : String(error),
+				);
+			});
+			return { action: "handled" };
+		}
+		return { action: "continue" };
+	});
+
+	// Slash-command trigger (pi resolves commands before the input event, so
+	// the two paths never double-fire).
+	pi.registerCommand("third-review", {
+		description:
+			"Summon the configured review model to review the just-completed work (check + fix)",
+		handler: async (_args, ctx) => {
+			await runReview(ctx);
+		},
+	});
+
+	// Manual config entry point: view and change the review model. Always
+	// opens the picker (title shows the current config); cancelling keeps
+	// the existing config, so it is also safe as a view-only command.
+	pi.registerCommand("review-model", {
+		description:
+			"Set or change the review model used by third-review (picker shows the current one)",
+		handler: async (_args, ctx) => {
+			await pickReviewModel(ctx, getReviewStore());
+		},
+	});
+
+	// Footer indicator: muted "review" while a review model is configured.
+	let theme: Theme | undefined;
+	let latestCtx: ExtensionContext | undefined;
+
+	const updateFooterStatus = (ctx: ExtensionContext): void => {
+		ctx.ui.setStatus(
+			REVIEW_STATUS_KEY,
+			getReviewStore().getModel() && theme
+				? theme.fg("muted", "review")
+				: undefined,
+		);
+	};
+
+	pi.on("session_start", (_event, ctx) => {
+		latestCtx = ctx;
+		try {
+			const t = ctx.ui.theme;
+			if (t) {
+				theme = t;
+			}
+		} catch {
+			// No theme in this mode — footer indicator stays off.
+		}
+		updateFooterStatus(ctx);
+	});
+
+	getReviewStore().subscribe(() => {
+		if (latestCtx) updateFooterStatus(latestCtx);
+	});
+}

package/src/features/review/prompt.ts

@@ -0,0 +1,37 @@
+/**
+ * review feature — third-party review prompt.
+ *
+ * The review model keeps FULL tool access: this is "check AND fix", not a
+ * read-only audit (confirmed with the user). The prompt is sent as a user
+ * message via pi.sendUserMessage(), so the review turn — including any fixes
+ * it makes — stays in the current session transcript right next to the work
+ * under review.
+ *
+ * The three focus points the user asked for (本轮需求实现 / 是否有遗漏 /
+ * 是否有错误) are spelled out verbatim in the prompt.
+ */
+
+/** Trigger words for the bare-message form of the third-review command. */
+export const TRIGGER_WORDS: ReadonlySet<string> = new Set([
+	"third-review",
+	"third review",
+]);
+
+/** Whether the input text is exactly a third-review trigger (case/space-insensitive). */
+export function isReviewTrigger(text: string): boolean {
+	return TRIGGER_WORDS.has(text.trim().toLowerCase());
+}
+
+export const REVIEW_PROMPT = `请以第三方代码评审的身份，对本次会话中刚完成的开发任务进行 Review。
+
+本轮需求、开发过程和代码改动都在当前会话上下文中，请结合上下文，并用 read/grep 等工具实际检查仓库代码，不要凭空猜测。
+
+请重点检查以下三点（逐项给出结论）：
+1. 本轮需求实现：本轮需求是否已完整、正确地实现？实现与需求描述是否一致？
+2. 是否有遗漏：需求中是否有遗漏的功能点、边界情况、异常处理、兼容性、测试等？
+3. 是否有错误：代码中是否存在逻辑错误、潜在 bug、类型/编译错误、安全与性能隐患等？
+
+要求：
+- 对确认的问题直接修复（write/edit），并简要说明改了什么、为什么改；
+- 无法确认或不宜直接改的问题，列出：位置（文件/行）、问题描述、建议方案；
+- 最后输出评审报告：发现问题清单（已修复 / 未修复）、修复说明、总体结论（通过 / 需修改）与剩余风险。`;

package/src/features/review/review.test.ts

@@ -0,0 +1,443 @@
+/**
+ * review feature — unit tests.
+ *
+ * Covers the logic behind the third-review command:
+ *  - trigger words (isReviewTrigger): exact bare-message match only
+ *  - store: set/get persistence round-trip + corrupted-file fallback
+ *  - modelKey / resolveConfiguredModel: provider/id resolution, incl. ids
+ *    that themselves contain "/" (e.g. openrouter/openai/gpt-5)
+ *  - createReviewRunner: busy guard, configured-model path, no-config /
+ *    stale-config select path (persist + run), cancel path, setModel
+ *    failure, reentrancy
+ *
+ * The runner reads the shared store via getReviewStore(); each test gets an
+ * isolated store backed by a temp file via setSharedReviewStore(). pi and
+ * ctx are minimal fakes (vi.fn()).
+ */
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+	ModelRegistry,
+} from "@earendil-works/pi-coding-agent";
+import type { Api, Model } from "@earendil-works/pi-ai";
+import {
+	afterAll,
+	beforeAll,
+	beforeEach,
+	describe,
+	expect,
+	it,
+	vi,
+} from "vitest";
+import {
+	createReviewRunner,
+	pickReviewModel,
+	resolveConfiguredModel,
+} from "./index.js";
+import { REVIEW_PROMPT, isReviewTrigger } from "./prompt.js";
+import {
+	ReviewStore,
+	getReviewStore,
+	modelKey,
+	setSharedReviewStore,
+} from "./store.js";
+
+// ─── fakes & setup ─────────────────────────────────────────────
+
+let tmpDir: string;
+let storeSeq = 0;
+
+beforeAll(() => {
+	tmpDir = mkdtempSync(join(tmpdir(), "pi-toolkits-review-"));
+});
+
+beforeEach(() => {
+	storeSeq += 1;
+	setSharedReviewStore(
+		new ReviewStore(join(tmpDir, `review-${storeSeq}.json`)),
+	);
+});
+
+afterAll(() => {
+	rmSync(tmpDir, { recursive: true, force: true });
+});
+
+function freshStoreFile(): string {
+	storeSeq += 1;
+	return join(tmpDir, `review-${storeSeq}.json`);
+}
+
+function fakeModel(provider: string, id: string, name = id): Model<Api> {
+	return {
+		id,
+		name,
+		provider,
+		api: "anthropic-messages",
+		baseUrl: "https://api.anthropic.com",
+		reasoning: false,
+		input: ["text"],
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+		contextWindow: 200000,
+		maxTokens: 8192,
+	};
+}
+
+const MODELS: Model<Api>[] = [
+	fakeModel("anthropic", "claude-sonnet-4", "Claude Sonnet 4"),
+	fakeModel("anthropic", "claude-opus-4", "Claude Opus 4"),
+	fakeModel("openrouter", "openai/gpt-5", "GPT-5"),
+];
+
+function fakeCtx(
+	overrides: {
+		idle?: boolean;
+		models?: Model<Api>[];
+		mode?: string;
+		hasUI?: boolean;
+		selectResult?: string | undefined;
+	} = {},
+) {
+	const notify = vi.fn();
+	const select = vi.fn(async () => overrides.selectResult);
+	const ctx = {
+		mode: overrides.mode ?? "tui",
+		hasUI: overrides.hasUI ?? true,
+		isIdle: () => overrides.idle ?? true,
+		modelRegistry: {
+			getAvailable: () => overrides.models ?? MODELS,
+		} as unknown as ModelRegistry,
+		ui: { notify, select },
+	} as unknown as ExtensionContext;
+	return { ctx, notify, select };
+}
+
+function fakePi(switched = true) {
+	const setModel = vi.fn(async () => switched);
+	const sendUserMessage = vi.fn();
+	const pi = { setModel, sendUserMessage } as unknown as ExtensionAPI;
+	return { pi, setModel, sendUserMessage };
+}
+
+// ─── trigger words ─────────────────────────────────────────────
+
+describe("isReviewTrigger", () => {
+	it("matches the bare trigger words case/space-insensitively", () => {
+		expect(isReviewTrigger("third-review")).toBe(true);
+		expect(isReviewTrigger("  Third-Review  ")).toBe(true);
+		expect(isReviewTrigger("third review")).toBe(true);
+		expect(isReviewTrigger("THIRD REVIEW")).toBe(true);
+	});
+
+	it("rejects non-trigger text (no prefix/suffix matching)", () => {
+		expect(isReviewTrigger("third-review now")).toBe(false);
+		expect(isReviewTrigger("third_review")).toBe(false);
+		expect(isReviewTrigger("thirdreview")).toBe(false);
+		expect(isReviewTrigger("/third-review")).toBe(false);
+		expect(isReviewTrigger("")).toBe(false);
+		expect(isReviewTrigger("review the code please")).toBe(false);
+	});
+});
+
+// ─── model key & resolution ────────────────────────────────────
+
+describe("modelKey", () => {
+	it("joins provider and id with a slash", () => {
+		expect(modelKey({ provider: "anthropic", id: "claude-sonnet-4" })).toBe(
+			"anthropic/claude-sonnet-4",
+		);
+	});
+
+	it("keeps slashes inside the id (openrouter-style ids)", () => {
+		expect(modelKey({ provider: "openrouter", id: "openai/gpt-5" })).toBe(
+			"openrouter/openai/gpt-5",
+		);
+	});
+});
+
+describe("resolveConfiguredModel", () => {
+	it("resolves a configured key to the available model", () => {
+		const { ctx } = fakeCtx();
+		expect(resolveConfiguredModel(ctx, "anthropic/claude-sonnet-4")).toBe(
+			MODELS[0],
+		);
+	});
+
+	it("resolves ids that contain a slash (split on the FIRST slash)", () => {
+		const { ctx } = fakeCtx();
+		expect(resolveConfiguredModel(ctx, "openrouter/openai/gpt-5")).toBe(
+			MODELS[2],
+		);
+	});
+
+	it("returns undefined when nothing is configured", () => {
+		const { ctx } = fakeCtx();
+		expect(resolveConfiguredModel(ctx, undefined)).toBeUndefined();
+	});
+
+	it("returns undefined when the configured model is gone from the registry", () => {
+		const { ctx } = fakeCtx();
+		// e.g. deleted from pi's models.json after being configured
+		expect(
+			resolveConfiguredModel(ctx, "anthropic/claude-opus-4-5"),
+		).toBeUndefined();
+	});
+
+	it("returns undefined for malformed keys", () => {
+		const { ctx } = fakeCtx();
+		expect(resolveConfiguredModel(ctx, "no-slash")).toBeUndefined();
+		expect(resolveConfiguredModel(ctx, "anthropic/")).toBeUndefined();
+		expect(resolveConfiguredModel(ctx, "/claude-sonnet-4")).toBeUndefined();
+	});
+});
+
+// ─── store ─────────────────────────────────────────────────────
+
+describe("ReviewStore", () => {
+	it("set/get round-trips within one instance", () => {
+		const store = new ReviewStore(freshStoreFile());
+		expect(store.getModel()).toBeUndefined();
+		store.setModel("anthropic/claude-sonnet-4");
+		expect(store.getModel()).toBe("anthropic/claude-sonnet-4");
+	});
+
+	it("persists across instances (file round-trip)", () => {
+		const file = freshStoreFile();
+		const a = new ReviewStore(file);
+		a.setModel("openrouter/openai/gpt-5");
+		const b = new ReviewStore(file);
+		expect(b.getModel()).toBe("openrouter/openai/gpt-5");
+	});
+
+	it("clears the configured model with undefined", () => {
+		const store = new ReviewStore(freshStoreFile());
+		store.setModel("anthropic/claude-sonnet-4");
+		store.setModel(undefined);
+		expect(store.getModel()).toBeUndefined();
+	});
+
+	it("falls back to unset on a corrupted file", () => {
+		const file = freshStoreFile();
+		try {
+			writeFileSync(file, "{ not json", "utf8");
+		} catch {
+			// A failed write still leaves the store to hit the read-error path.
+		}
+		const store = new ReviewStore(file);
+		expect(store.getModel()).toBeUndefined();
+	});
+
+	it("ignores a stored value without a slash", () => {
+		const file = freshStoreFile();
+		writeFileSync(file, JSON.stringify({ model: "no-slash-here" }), "utf8");
+		expect(new ReviewStore(file).getModel()).toBeUndefined();
+	});
+
+	it("notifies subscribers on set", () => {
+		const store = new ReviewStore(freshStoreFile());
+		const listener = vi.fn();
+		store.subscribe(listener);
+		store.setModel("anthropic/claude-sonnet-4");
+		expect(listener).toHaveBeenCalledTimes(1);
+	});
+});
+
+// ─── pickReviewModel ───────────────────────────────────────────
+
+describe("pickReviewModel", () => {
+	it("shows the available models and persists the pick", async () => {
+		const { ctx, select } = fakeCtx({
+			selectResult: "GPT-5 (openrouter/openai/gpt-5)",
+		});
+		const store = new ReviewStore(freshStoreFile());
+		const picked = await pickReviewModel(ctx, store);
+		expect(picked).toBe(MODELS[2]);
+		expect(select).toHaveBeenCalledWith("选择评审模型 (third-review)", [
+			"Claude Sonnet 4 (anthropic/claude-sonnet-4)",
+			"Claude Opus 4 (anthropic/claude-opus-4)",
+			"GPT-5 (openrouter/openai/gpt-5)",
+		]);
+		expect(store.getModel()).toBe("openrouter/openai/gpt-5");
+	});
+
+	it("returns undefined and does not persist when cancelled", async () => {
+		const { ctx, select } = fakeCtx({ selectResult: undefined });
+		const store = new ReviewStore(freshStoreFile());
+		expect(await pickReviewModel(ctx, store)).toBeUndefined();
+		expect(select).toHaveBeenCalledTimes(1);
+		expect(store.getModel()).toBeUndefined();
+	});
+
+	it("fails gracefully when no models are available", async () => {
+		const { ctx, notify, select } = fakeCtx({ models: [] });
+		const store = new ReviewStore(freshStoreFile());
+		expect(await pickReviewModel(ctx, store)).toBeUndefined();
+		expect(select).not.toHaveBeenCalled();
+		expect(notify).toHaveBeenCalledWith(
+			expect.stringContaining("没有可用模型"),
+			"error",
+		);
+	});
+
+	it("refuses when no dialog-capable UI is available", async () => {
+		const { ctx, notify, select } = fakeCtx({ hasUI: false });
+		const store = new ReviewStore(freshStoreFile());
+		expect(await pickReviewModel(ctx, store)).toBeUndefined();
+		expect(select).not.toHaveBeenCalled();
+		expect(notify).toHaveBeenCalledWith(
+			expect.stringContaining("不支持模型选择对话框"),
+			"error",
+		);
+	});
+
+	it("works in rpc mode (dialogs are available there)", async () => {
+		const { ctx, select } = fakeCtx({
+			mode: "rpc",
+			selectResult: "Claude Opus 4 (anthropic/claude-opus-4)",
+		});
+		const store = new ReviewStore(freshStoreFile());
+		const picked = await pickReviewModel(ctx, store);
+		expect(picked).toBe(MODELS[1]);
+		expect(select).toHaveBeenCalledTimes(1);
+		expect(store.getModel()).toBe("anthropic/claude-opus-4");
+	});
+
+	it("shows the current config in the picker title", async () => {
+		const store = new ReviewStore(freshStoreFile());
+		store.setModel("anthropic/claude-sonnet-4");
+		const { ctx, select } = fakeCtx({ selectResult: undefined });
+		await pickReviewModel(ctx, store);
+		expect(select).toHaveBeenCalledWith(
+			"选择评审模型 (当前: anthropic/claude-sonnet-4)",
+			expect.any(Array),
+		);
+		// Cancelling a change keeps the existing config.
+		expect(store.getModel()).toBe("anthropic/claude-sonnet-4");
+	});
+});
+
+// ─── createReviewRunner ────────────────────────────────────────
+
+describe("createReviewRunner", () => {
+	it("refuses to run while the agent is streaming", async () => {
+		const { pi } = fakePi();
+		const { ctx, notify } = fakeCtx({ idle: false });
+		await createReviewRunner(pi)(ctx);
+		expect(notify).toHaveBeenCalledWith(
+			expect.stringContaining("等待完成"),
+			"warning",
+		);
+		expect(pi.setModel).not.toHaveBeenCalled();
+		expect(pi.sendUserMessage).not.toHaveBeenCalled();
+	});
+
+	it("switches to the configured model and sends the review prompt", async () => {
+		getReviewStore().setModel("anthropic/claude-sonnet-4");
+		const { pi, setModel, sendUserMessage } = fakePi();
+		const { ctx, notify } = fakeCtx();
+		await createReviewRunner(pi)(ctx);
+		expect(setModel).toHaveBeenCalledWith(MODELS[0]);
+		expect(sendUserMessage).toHaveBeenCalledWith(REVIEW_PROMPT);
+		expect(notify).toHaveBeenCalledWith(
+			expect.stringContaining("已切换到评审模型"),
+			"info",
+		);
+	});
+
+	it("picks, persists and runs when no model is configured", async () => {
+		const { pi, setModel, sendUserMessage } = fakePi();
+		const { ctx, notify, select } = fakeCtx({
+			selectResult: "GPT-5 (openrouter/openai/gpt-5)",
+		});
+		await createReviewRunner(pi)(ctx);
+		expect(getReviewStore().getModel()).toBe("openrouter/openai/gpt-5");
+		expect(setModel).toHaveBeenCalledWith(MODELS[2]);
+		expect(sendUserMessage).toHaveBeenCalledWith(REVIEW_PROMPT);
+		expect(select).toHaveBeenCalledTimes(1);
+		expect(notify).toHaveBeenCalledWith(
+			expect.stringContaining("尚未配置评审模型"),
+			"warning",
+		);
+	});
+
+	it("re-picks, persists and runs when the configured model is unavailable", async () => {
+		getReviewStore().setModel("anthropic/claude-opus-4-5"); // deleted in pi
+		const { pi, setModel, sendUserMessage } = fakePi();
+		const { ctx, notify, select } = fakeCtx({
+			selectResult: "Claude Sonnet 4 (anthropic/claude-sonnet-4)",
+		});
+		await createReviewRunner(pi)(ctx);
+		expect(notify).toHaveBeenCalledWith(
+			expect.stringContaining("不存在或不可用"),
+			"warning",
+		);
+		expect(getReviewStore().getModel()).toBe("anthropic/claude-sonnet-4");
+		expect(setModel).toHaveBeenCalledWith(MODELS[0]);
+		expect(sendUserMessage).toHaveBeenCalledWith(REVIEW_PROMPT);
+		expect(select).toHaveBeenCalledTimes(1);
+	});
+
+	it("aborts when the user cancels the model pick", async () => {
+		const { pi, setModel, sendUserMessage } = fakePi();
+		const { ctx, select } = fakeCtx({ selectResult: undefined });
+		await createReviewRunner(pi)(ctx);
+		expect(select).toHaveBeenCalledTimes(1);
+		expect(setModel).not.toHaveBeenCalled();
+		expect(sendUserMessage).not.toHaveBeenCalled();
+		expect(getReviewStore().getModel()).toBeUndefined();
+	});
+
+	it("reports and aborts when switching to the review model fails", async () => {
+		getReviewStore().setModel("anthropic/claude-sonnet-4");
+		const { pi, setModel, sendUserMessage } = fakePi(false); // setModel → false
+		const { ctx, notify } = fakeCtx();
+		await createReviewRunner(pi)(ctx);
+		expect(setModel).toHaveBeenCalledWith(MODELS[0]);
+		expect(sendUserMessage).not.toHaveBeenCalled();
+		expect(notify).toHaveBeenCalledWith(
+			expect.stringContaining("无法切换到评审模型"),
+			"error",
+		);
+	});
+
+	it("serializes concurrent triggers (one review at a time)", async () => {
+		const { pi } = fakePi();
+		// First run blocks inside ui.select until we resolve it.
+		let release: ((v: string | undefined) => void) | undefined;
+		const select = vi.fn(
+			() => new Promise<string | undefined>((resolve) => (release = resolve)),
+		);
+		const ctx = {
+			mode: "tui",
+			hasUI: true,
+			isIdle: () => true,
+			modelRegistry: {
+				getAvailable: () => MODELS,
+			} as unknown as ModelRegistry,
+			ui: { notify: vi.fn(), select },
+		} as unknown as ExtensionContext;
+
+		const runner = createReviewRunner(pi);
+		const first = runner(ctx);
+		// Second trigger while the first is still picking — must be refused.
+		const notify2 = vi.fn();
+		const ctx2 = {
+			mode: "tui",
+			hasUI: true,
+			isIdle: () => true,
+			modelRegistry: { getAvailable: () => MODELS } as unknown as ModelRegistry,
+			ui: { notify: notify2, select: vi.fn(async () => undefined) },
+		} as unknown as ExtensionContext;
+		await runner(ctx2);
+		expect(notify2).toHaveBeenCalledWith(
+			expect.stringContaining("评审已在执行中"),
+			"warning",
+		);
+		release?.("Claude Sonnet 4 (anthropic/claude-sonnet-4)");
+		await first;
+		expect(pi.setModel).toHaveBeenCalledTimes(1);
+		expect(pi.sendUserMessage).toHaveBeenCalledTimes(1);
+	});
+});

package/src/features/review/store.ts

@@ -0,0 +1,137 @@
+/**
+ * review feature — persisted review-model config store.
+ *
+ * State lives in `<agent-dir>/pi-toolkits-review.json` (agent-dir from
+ * getAgentDir(), same convention as the favorites store). The file holds a
+ * single model key:
+ *
+ *   { "model": "anthropic/claude-sonnet-4" }
+ *
+ * Robustness mirrors the favorites store: corrupted/unreadable files fall
+ * back to "no model configured" with a console.warn; writes are atomic
+ * (tmp + rename) and never throw.
+ */
+import {
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	renameSync,
+	writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { REVIEW_FILE } from "./constants.js";
+
+/** Model identity used as the review-model key: "provider/id". */
+export function modelKey(model: { provider: string; id: string }): string {
+	return `${model.provider}/${model.id}`;
+}
+
+export class ReviewStore {
+	private model: string | undefined;
+	private readonly file: string;
+	private loaded = false;
+	private readonly listeners = new Set<() => void>();
+
+	constructor(file: string = join(getAgentDir(), REVIEW_FILE)) {
+		this.file = file;
+	}
+
+	private ensureLoaded(): void {
+		if (this.loaded) return;
+		this.loaded = true;
+		try {
+			if (!existsSync(this.file)) return;
+			const raw = readFileSync(this.file, "utf8");
+			const parsed = JSON.parse(raw) as { model?: unknown };
+			if (
+				parsed &&
+				typeof parsed.model === "string" &&
+				parsed.model.includes("/")
+			) {
+				this.model = parsed.model;
+			}
+		} catch (error) {
+			// pi-lens-ignore: no-console-except-error,console-statement, — deliberate degradation log
+			console.warn(
+				"[pi-toolkits/review] Failed to load review config, starting unset:",
+				error instanceof Error ? error.message : String(error),
+			);
+			this.model = undefined;
+		}
+	}
+
+	/** Atomically persist (tmp + rename). Never throws. */
+	save(): void {
+		try {
+			const dir = dirname(this.file);
+			if (!existsSync(dir)) {
+				mkdirSync(dir, { recursive: true });
+			}
+			const tmp = `${this.file}.tmp`;
+			writeFileSync(
+				tmp,
+				`${JSON.stringify({ model: this.model ?? null }, null, 2)}\n`,
+				"utf8",
+			);
+			renameSync(tmp, this.file);
+		} catch (error) {
+			// pi-lens-ignore: no-console-except-error,console-statement, — deliberate degradation log
+			console.warn(
+				"[pi-toolkits/review] Failed to save review config:",
+				error instanceof Error ? error.message : String(error),
+			);
+		}
+	}
+
+	/** The configured review model key ("provider/id"), or undefined. */
+	getModel(): string | undefined {
+		this.ensureLoaded();
+		return this.model;
+	}
+
+	/** Set (or clear with undefined) the review model key and persist. */
+	setModel(key: string | undefined): void {
+		this.ensureLoaded();
+		this.model = key;
+		this.save();
+		this.notify();
+	}
+
+	subscribe(listener: () => void): () => void {
+		this.listeners.add(listener);
+		return () => {
+			this.listeners.delete(listener);
+		};
+	}
+
+	private notify(): void {
+		for (const listener of [...this.listeners]) {
+			try {
+				listener();
+			} catch {
+				// A broken listener must not break review config handling.
+			}
+		}
+	}
+}
+
+/**
+ * Process-wide store shared by the runner and commands.
+ *
+ * Accessed via getReviewStore() (lazy) so tests can swap in an isolated
+ * store via setSharedReviewStore().
+ */
+let sharedStore: ReviewStore | undefined;
+
+export function getReviewStore(): ReviewStore {
+	if (!sharedStore) {
+		sharedStore = new ReviewStore();
+	}
+	return sharedStore;
+}
+
+/** Test hook — replace the shared store (e.g. with one backed by a temp file). */
+export function setSharedReviewStore(store: ReviewStore): void {
+	sharedStore = store;
+}

package/src/index.ts

@@ -8,15 +8,18 @@
  *  - ask — read-only Q&A mode (/ask)
  *  - favorites — model favorites (ctrl+F/ctrl+J in /model, favorites-only cycling)
  *  - stash — prompt stash (ctrl+alt+y swap / double-press stash-and-clear)
+ *  - review — third-party code review with a configured review model (third-review)
  */
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { registerAsk } from "./features/ask/index.js";
 import { registerFavorites } from "./features/favorites/index.js";
+import { registerReview } from "./features/review/index.js";
 import { registerStash } from "./features/stash/index.js";
 
 export default function piToolkits(pi: ExtensionAPI): void {
 	registerAsk(pi);
 	registerFavorites(pi);
+	registerReview(pi);
 	registerStash(pi);
 	// registerXxx(pi); // future features
 }