@zephyrdeng/pi-review 0.5.0 → 0.6.0

package/README.md

@@ -154,6 +154,8 @@ pi-review --continue <sessionHandle> --mode challenge --model provider/model --
 
 Agent hosts like Claude Code, Cursor, and Codex typically buffer a Bash tool's stdout until the command exits, so a multi-minute review can look like a silent wait followed by one large dump — even though `pi-review` streams by default. `--progress-log <path>` sidesteps this: it runs the child in `--mode json` and writes its event log to a file in real time, independent of what the calling tool does with stdout.
 
+The bundled **pi-review** agent skill tells parent agents to use `--progress-log` by default on those hosts (Pi `/rv` stays on default streaming). Details: [`skills/pi-review/SKILL.md`](skills/pi-review/SKILL.md) and [`skills/pi-review/references/codex-tools.md`](skills/pi-review/references/codex-tools.md).
+
 ```bash
 # Start the review in the background, writing structured progress events to a file
 pi-review --progress-log /tmp/pi-review.jsonl -- @src/foo.ts &
@@ -220,7 +222,13 @@ The `/rv` command injects a task message for the parent agent (Pi host rules: de
 /rv --mode challenge --keep-session @docs/design.md
 ```
 
-Argument completions (`--mode`, `@`, `models`, etc.) are hints only; execution is skill-driven.
+Argument completions are context-aware. After the host session starts, `/rv` reads the live model registry and offers:
+
+- **Model list** after `--model `, ranked by review fit (reasoning, context window, cross-vendor bonus for adversarial review) with a `★ 推荐` marker and a one-line reason.
+- **Thinking suffix** after `provider/model:` — only levels the chosen model actually supports (e.g. `:high`, `:xhigh`); non-reasoning models offer none.
+- **`--mode` / `--thinking` / flag** completions with hints, and **scene templates** (e.g. “审代码改动（推荐配置）”) at the top level that pre-fill a recommended command.
+
+Completions are a hint layer only; execution remains skill-driven. When the model registry is unavailable (e.g. non-TUI mode), `/rv` falls back to the static hint list.
 
 ## Security
 

package/README.zh-CN.md

@@ -66,7 +66,9 @@ pi-review models
 
 跟进审查时，`--continue` 与首次 `/rv` 一样可**选填** `--mode`、`--model`（以及后续 CLI 支持的其它选项由 skill 直接调用 CLI 时传入）。
 
-`/rv` 会向主会话注入**英文任务说明**（Pi 宿主策略：默认流式、**不要**自动加 `--no-stream` / `--progress-log`），由主 Agent 调用 `pi-review` CLI。普通 `/rv @path` 无需额外参数。需要整段缓冲时显式 `/rv --no-stream`；Claude Code 等宿主见英文 README 的 `--progress-log`。
+`/rv` 会向主会话注入**英文任务说明**（**仅 Pi 宿主**：默认流式、**不要**自动加 `--no-stream` / `--progress-log`），由主 Agent 调用 `pi-review` CLI。普通 `/rv @path` 无需额外参数。需要整段缓冲时显式 `/rv --no-stream`。
+
+**Claude Code / Codex 等 Agent 宿主**：Bash 工具会缓冲 stdout，不能指望“默认流式”在对话里逐字出现；**pi-review skill 默认建议** `--progress-log <path>` + 后台运行 + tail 日志。详见 `skills/pi-review/SKILL.md`、`skills/pi-review/references/codex-tools.md` 与英文 README。
 
 ## 输出格式
 

package/extensions/review.ts

@@ -1,4 +1,8 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  buildRvCompletions,
+  type ModelInfo,
+} from "./rv-completions.js";
 import {
   buildRvOrchestrationPrompt,
   parseRvArgs,
@@ -6,11 +10,65 @@ import {
   validateRvParsed,
 } from "./rv-prompts.js";
 
+/**
+ * Captured at `session_start` so the synchronous-ish `getArgumentCompletions`
+ * callback (which receives only the argument prefix) can read the live model
+ * registry without ctx. Stays undefined in non-TUI/print mode; completions then
+ * gracefully degrade to the static `RV_COMPLETIONS` fallback.
+ */
+let capturedModels: ModelInfo[] | undefined;
+let capturedPrimaryProvider: string | undefined;
+
+function toModelInfo(m: {
+  provider: string;
+  id: string;
+  name?: string;
+  reasoning?: boolean;
+  contextWindow?: number;
+  thinkingLevelMap?: Record<string, string | null | undefined>;
+}): ModelInfo {
+  const levels: string[] = [];
+  const map = m.thinkingLevelMap ?? {};
+  for (const k of ["off", "minimal", "low", "medium", "high", "xhigh"]) {
+    // A level is supported unless explicitly disabled (null) and is present in the map.
+    if (k in map && map[k] !== null && map[k] !== undefined) levels.push(k);
+  }
+  return {
+    provider: m.provider,
+    id: m.id,
+    label: `${m.provider}/${m.id}`,
+    name: m.name ?? m.id,
+    reasoning: Boolean(m.reasoning),
+    contextWindow: m.contextWindow ?? 0,
+    thinkingLevels: levels,
+  };
+}
+
 export default function piReviewExtension(pi: ExtensionAPI) {
+  pi.on("session_start", (_event, ctx) => {
+    try {
+      const available = ctx.modelRegistry?.getAvailable?.() ?? [];
+      capturedModels = available.map((m) => toModelInfo(m as unknown as Parameters<typeof toModelInfo>[0]));
+      capturedPrimaryProvider = ctx.model?.provider;
+    } catch {
+      capturedModels = undefined;
+      capturedPrimaryProvider = undefined;
+    }
+  });
+
   pi.registerCommand("rv", {
     description:
-      "Delegate pi-review to the agent. Usage: /rv [--mode plan|challenge] [--model id] [--keep-session] [--no-stream] @target | /rv --continue <handle> [opts] [text] | models",
-    getArgumentCompletions: (prefix) => {
+      "Delegate pi-review to the agent. Usage: /rv [--mode plan|challenge] [--model id] [--thinking level] [--keep-session] [--no-stream] @target | /rv --continue <handle> [opts] [text] | models",
+    getArgumentCompletions: (prefix): ReturnType<typeof buildRvCompletions> => {
+      // Try dynamic completion first (models + thinking + scene templates).
+      if (capturedModels && capturedModels.length > 0) {
+        const dynamic = buildRvCompletions(prefix, {
+          models: capturedModels,
+          primaryProvider: capturedPrimaryProvider,
+        });
+        if (dynamic && dynamic.length) return dynamic;
+      }
+      // Graceful fallback to static hint list when registry is unavailable.
       const filtered = RV_COMPLETIONS.filter((item) => item.value.startsWith(prefix));
       return filtered.length
         ? filtered.map(({ value, hint }) => ({ value, label: value, description: hint }))

package/extensions/rv-completions.test.ts

@@ -0,0 +1,221 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+  buildRvCompletions,
+  extractSignals,
+  fuzzyMatch,
+  MODE_HINTS,
+  rankModelsForReview,
+  scoreModelForReview,
+  tokenizeArgPrefix,
+  type ModelInfo,
+} from "./rv-completions.js";
+
+function model(partial: Partial<ModelInfo> & Pick<ModelInfo, "provider" | "id">): ModelInfo {
+  return {
+    label: `${partial.provider}/${partial.id}`,
+    name: partial.id,
+    reasoning: false,
+    contextWindow: 200_000,
+    thinkingLevels: ["off", "low", "medium", "high"],
+    ...partial,
+  };
+}
+
+const MODELS: ModelInfo[] = [
+  model({ provider: "anthropic", id: "claude-opus-4-6", reasoning: true, contextWindow: 200_000, thinkingLevels: ["off", "low", "medium", "high", "xhigh"] }),
+  model({ provider: "openai", id: "gpt-5.5", reasoning: true, contextWindow: 400_000, thinkingLevels: ["off", "minimal", "low", "medium", "high", "xhigh"] }),
+  model({ provider: "zenmux", id: "gemini-3-flash", reasoning: false, contextWindow: 1_000_000, thinkingLevels: [] }),
+];
+
+describe("tokenizeArgPrefix", () => {
+  it("splits head and tail on the last space", () => {
+    const t = tokenizeArgPrefix("@src/foo.ts --model ope");
+    assert.deepEqual(t.head, ["@src/foo.ts", "--model"]);
+    assert.equal(t.tail, "ope");
+    assert.equal(t.prev, "--model");
+  });
+
+  it("treats a single token as tail with empty head", () => {
+    const t = tokenizeArgPrefix("--mode");
+    assert.deepEqual(t.head, []);
+    assert.equal(t.tail, "--mode");
+    assert.equal(t.prev, null);
+  });
+
+  it("handles trailing space as empty tail", () => {
+    const t = tokenizeArgPrefix("@a.ts ");
+    assert.deepEqual(t.head, ["@a.ts"]);
+    assert.equal(t.tail, "");
+    assert.equal(t.prev, "@a.ts");
+  });
+
+  it("strips surrounding quotes in head tokens", () => {
+    const t = tokenizeArgPrefix('"@a b.ts" --mode ');
+    assert.deepEqual(t.head, ["@a b.ts", "--mode"]);
+    assert.deepEqual(t.rawHead, ['"@a b.ts"', "--mode"]);
+    assert.equal(t.prev, "--mode");
+  });
+});
+
+describe("extractSignals", () => {
+  it("detects target extension and explicit mode", () => {
+    const sig = extractSignals(["@docs/design.md", "--mode", "plan"], {});
+    assert.equal(sig.mode, "plan");
+    assert.equal(sig.targetExt, "md");
+    assert.equal(sig.hasTarget, true);
+  });
+
+  it("defaults mode to code", () => {
+    const sig = extractSignals(["@src/foo.ts"], {});
+    assert.equal(sig.mode, "code");
+    assert.equal(sig.targetExt, "ts");
+  });
+
+  it("carries primary provider for cross-vendor bonus", () => {
+    const sig = extractSignals([], { primaryProvider: "anthropic" });
+    assert.equal(sig.primaryProvider, "anthropic");
+  });
+});
+
+describe("scoreModelForReview / rankModelsForReview", () => {
+  it("scores reasoning + cross-vendor + xhigh higher than a cheap non-reasoning model", () => {
+    const sig = { mode: "challenge", hasTarget: true, targetExt: "md", primaryProvider: "anthropic" };
+    const opus = scoreModelForReview(MODELS[0], sig);
+    const gpt = scoreModelForReview(MODELS[1], sig);
+    const flash = scoreModelForReview(MODELS[2], sig);
+    assert.ok(gpt.score > opus.score, `gpt (${gpt.score}) should beat opus (${opus.score}) for challenge+cross-vendor`);
+    assert.ok(opus.score > flash.score, "opus should beat the non-reasoning flash");
+    assert.ok(flash.score >= 2, "flash still gets context-window points");
+  });
+
+  it("ranks descending by score", () => {
+    const sig = { mode: "plan", hasTarget: false, primaryProvider: "anthropic" };
+    const ranked = rankModelsForReview(MODELS, sig);
+    assert.equal(ranked[0].id, "gpt-5.5");
+    assert.equal(ranked[ranked.length - 1].id, "gemini-3-flash");
+  });
+});
+
+describe("fuzzyMatch", () => {
+  it("matches subsequence case-insensitively", () => {
+    assert.equal(fuzzyMatch("anthropic/claude-opus-4-6", "aclaude"), true);
+    assert.equal(fuzzyMatch("Anthropic/Claude", "acl"), true);
+    assert.equal(fuzzyMatch("openai/gpt-5.5", "zzz"), false);
+  });
+});
+
+describe("buildRvCompletions", () => {
+  const deps = { models: MODELS, primaryProvider: "anthropic" };
+
+  it("returns dynamic model list after --model, with recommended marker on top items", () => {
+    const items = buildRvCompletions("@x.md --model ", deps);
+    assert.ok(items, "expected items");
+    assert.ok(items!.some((i) => i.label === "openai/gpt-5.5"));
+    const top = items!.find((i) => i.description?.includes("★ 推荐"));
+    assert.ok(top, "expected at least one recommended item");
+    // value carries the head so applyCompletion replaces the whole arg safely
+    assert.ok(top!.value.startsWith("@x.md --model "));
+  });
+
+  it("filters models by a partial query", () => {
+    const items = buildRvCompletions("--model ope", deps);
+    assert.ok(items);
+    assert.ok(items!.every((i) => i.label.includes("openai")));
+  });
+
+  it("completes thinking suffix after provider/id: for a reasoning model", () => {
+    const items = buildRvCompletions("--model openai/gpt-5.5:", deps);
+    assert.ok(items);
+    const labels = items!.map((i) => i.label);
+    assert.ok(labels.includes("high"));
+    assert.ok(labels.includes("xhigh"));
+    assert.ok(items!.every((i) => i.value.startsWith("--model openai/gpt-5.5:")));
+  });
+
+  it("does not offer thinking suffix for a non-reasoning model", () => {
+    const items = buildRvCompletions("--model zenmux/gemini-3-flash:", deps);
+    // flash has empty thinkingLevels → no suffix candidates
+    assert.equal(items, null);
+  });
+
+  it("completes --mode values with hints", () => {
+    const items = buildRvCompletions("--mode pl", deps);
+    assert.ok(items);
+    assert.deepEqual(items!.map((i) => i.label), ["plan"]);
+    assert.equal(items![0].description, MODE_HINTS["plan"]);
+  });
+
+  it("completes --thinking levels", () => {
+    const items = buildRvCompletions("--thinking h", deps);
+    assert.ok(items);
+    assert.deepEqual(items!.map((i) => i.label).sort(), ["high"]);
+  });
+
+  it("completes flags when tail starts with --", () => {
+    const items = buildRvCompletions("--keep", deps);
+    assert.ok(items);
+    assert.deepEqual(items!.map((i) => i.label), ["--keep-session"]);
+    assert.ok(items![0].value === "--keep-session");
+  });
+
+  it("defers to built-in file completion when tail starts with @", () => {
+    assert.equal(buildRvCompletions("@src/foo", deps), null);
+  });
+
+  it("defers --continue value to the handler (no static list)", () => {
+    assert.equal(buildRvCompletions("--continue abc", deps), null);
+  });
+
+  it("offers scene templates + models keyword at empty top level", () => {
+    const items = buildRvCompletions("", deps);
+    assert.ok(items);
+    assert.ok(items!.some((i) => i.label === "models"));
+    assert.ok(items!.some((i) => i.label.startsWith("审代码改动")));
+    // template values end with " @" so the user can keep typing a path
+    const tmpl = items!.find((i) => i.label.startsWith("审代码改动"))!;
+    assert.ok(tmpl.value.endsWith(" @"));
+  });
+
+  it("every returned value preserves the head prefix (整段替换安全)", () => {
+    const cases = ["@a.ts --mode ", "@a.ts --model ", "@a.ts --thinking ", "@a.ts --"];
+    for (const c of cases) {
+      const items = buildRvCompletions(c, deps);
+      if (!items) continue;
+      for (const it of items) {
+        assert.ok(
+          it.value.startsWith(c),
+          `value "${it.value}" must preserve head "${c}"`,
+        );
+      }
+    }
+  });
+
+  it("preserves quotes in headPrefix for paths with spaces (note #2 fix)", () => {
+    const items = buildRvCompletions('"@a b.ts" --model ', deps);
+    assert.ok(items);
+    for (const it of items) {
+      assert.ok(
+        it.value.startsWith('"@a b.ts" --model '),
+        `value "${it.value}" must preserve quoted head`,
+      );
+    }
+  });
+
+  it("scene templates omit the thinking colon for non-reasoning models (note #1 fix)", () => {
+    const nonReasoning = [{ ...MODELS[2], thinkingLevels: [] }] as ModelInfo[];
+    const items = buildRvCompletions("", { models: nonReasoning });
+    assert.ok(items);
+    const tmpl = items!.find((i) => i.label.startsWith("审代码改动"));
+    assert.ok(tmpl, "expected a scene template even for non-reasoning models");
+    // Must NOT contain a dangling colon like `gemini-3-flash: @`
+    assert.doesNotMatch(tmpl!.value, /flash:\s@/);
+    assert.match(tmpl!.value, /flash @/);
+  });
+
+  it("falls back gracefully when models are unavailable (static flags still work)", () => {
+    const items = buildRvCompletions("--mode ", {});
+    assert.ok(items);
+    assert.ok(items!.some((i) => i.label === "code" || i.label === "plan" || i.label === "challenge"));
+  });
+});

package/extensions/rv-completions.ts

@@ -0,0 +1,450 @@
+/**
+ * Pure, testable /rv argument-completion logic.
+ *
+ * This module deliberately avoids importing pi types so the tokenizer, state
+ * machine, and model scorer can be unit-tested with `node:test` and reused
+ * across hosts. The thin runtime adapter (registry capture + AutocompleteItem
+ * shaping) lives in `review.ts`.
+ *
+ * Completion items are returned "续写式": `value` always carries the already-typed
+ * head tokens because pi-tui's `applyCompletion` replaces the *entire* argument
+ * text after the slash command with `item.value`.
+ */
+
+export type AutocompleteItem = {
+  value: string;
+  label: string;
+  description?: string;
+};
+
+export const RV_MODE_VALUES = ["code", "plan", "challenge"] as const;
+export const THINKING_LEVELS = [
+  "off",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+] as const;
+export const RV_FLAGS = [
+  "--mode",
+  "--model",
+  "--thinking",
+  "--keep-session",
+  "--no-stream",
+  "--continue",
+] as const;
+
+export const MODE_HINTS: Record<string, string> = {
+  code: "代码 / diff / MR 审核",
+  plan: "架构 / 计划评审",
+  challenge: "对抗性方案评审",
+};
+
+export const FLAG_HINTS: Record<string, string> = {
+  "--mode": "审核模式 code|plan|challenge",
+  "--model": "provider/model[:thinking]",
+  "--thinking": "off|minimal|low|medium|high|xhigh",
+  "--keep-session": "保留会话，可用 /rv --continue 追问",
+  "--no-stream": "缓冲输出到结束（非默认）",
+  "--continue": "继续既有 review 会话",
+};
+
+/** Minimal model metadata we need; converted from the host's Model registry. */
+export interface ModelInfo {
+  provider: string;
+  id: string;
+  /** `${provider}/${id}` */
+  label: string;
+  name: string;
+  reasoning: boolean;
+  contextWindow: number;
+  /** Lowercased thinking levels the model actually supports; empty if non-reasoning. */
+  thinkingLevels: string[];
+}
+
+export interface ReviewSignals {
+  mode: string;
+  hasTarget: boolean;
+  targetExt?: string;
+  /** Provider of the host session's primary model, for cross-vendor bonus. */
+  primaryProvider?: string;
+}
+
+export interface CompletionDeps {
+  models?: ModelInfo[];
+  primaryProvider?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Tokenizer
+// ---------------------------------------------------------------------------
+
+export interface TokenizedArgs {
+  /** Fully typed tokens before the in-progress tail. */
+  head: string[];
+  /** Raw head tokens (quotes preserved) for safe reconstruction. */
+  rawHead: string[];
+  /** The token currently being typed (may be ""). */
+  tail: string;
+  /** Last token of `head`, or null. Used to detect value-position flags. */
+  prev: string | null;
+}
+
+const TOKEN_RE = /(?:[^\s"']+|"[^"]*"|'[^']*')+/g;
+
+export function tokenizeArgPrefix(prefix: string): TokenizedArgs {
+  const lastSpace = prefix.lastIndexOf(" ");
+  if (lastSpace === -1) {
+    return { head: [], rawHead: [], tail: prefix, prev: null };
+  }
+  const headRaw = prefix.slice(0, lastSpace);
+  const tail = prefix.slice(lastSpace + 1);
+  const matches = headRaw.match(TOKEN_RE) ?? [];
+  const rawHead = matches.slice();
+  const head = matches.map((t) => t.replace(/^['"]|['"]$/g, ""));
+  const prev = head.length > 0 ? head[head.length - 1] : null;
+  return { head, rawHead, tail, prev };
+}
+
+// ---------------------------------------------------------------------------
+// Signal extraction
+// ---------------------------------------------------------------------------
+
+const CODE_EXTS = new Set([
+  "ts", "tsx", "js", "jsx", "mjs", "cjs", "py", "rb", "go", "rs", "java", "kt",
+  "c", "cc", "cpp", "h", "hpp", "cs", "php", "swift", "scala", "sh", "sql",
+  "vue", "svelte",
+]);
+const PLAN_EXTS = new Set(["md", "markdown", "txt", "rst", "adoc"]);
+
+function extOf(token: string): string | undefined {
+  const cleaned = token.replace(/^['"]|['"]$/g, "").replace(/^@/, "");
+  const m = cleaned.match(/\.([a-zA-Z0-9]+)$/);
+  return m ? m[1].toLowerCase() : undefined;
+}
+
+export function extractSignals(head: string[], deps: CompletionDeps): ReviewSignals {
+  const target = head.find((t) => t.startsWith("@"));
+  const modeIdx = head.indexOf("--mode");
+  const mode = modeIdx >= 0 ? head[modeIdx + 1] : "code";
+  return {
+    mode,
+    hasTarget: Boolean(target),
+    targetExt: target ? extOf(target) : undefined,
+    primaryProvider: deps.primaryProvider,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Model scoring (P2 rule engine — pure, no LLM in the completion hot path)
+// ---------------------------------------------------------------------------
+
+export function scoreModelForReview(
+  m: ModelInfo,
+  sig: ReviewSignals,
+): { score: number; reason: string } {
+  let score = 0;
+  const reasons: string[] = [];
+  if (m.reasoning) {
+    score += 3;
+    reasons.push("reasoning");
+  }
+  if (m.contextWindow >= 200_000) score += 2;
+  else if (m.contextWindow >= 100_000) score += 1;
+  if (sig.primaryProvider && m.provider !== sig.primaryProvider) {
+    score += 1;
+    reasons.push("跨厂商交叉审核");
+  }
+  if ((sig.mode === "plan" || sig.mode === "challenge") && m.thinkingLevels.includes("xhigh")) {
+    score += 2;
+    reasons.push("xhigh 思考");
+  } else if (m.thinkingLevels.includes("high")) {
+    score += 1;
+  }
+  if (sig.targetExt && PLAN_EXTS.has(sig.targetExt) && m.reasoning) {
+    score += 1;
+    reasons.push("适合文档评审");
+  }
+  return { score, reason: reasons.filter(Boolean).join(" · ") };
+}
+
+export function rankModelsForReview(
+  models: ModelInfo[],
+  sig: ReviewSignals,
+): ModelInfo[] {
+  return models
+    .map((m) => ({ m, s: scoreModelForReview(m, sig).score }))
+    .sort((a, b) => b.s - a.s)
+    .map((x) => x.m);
+}
+
+// ---------------------------------------------------------------------------
+// Fuzzy filtering (subsequence match, case-insensitive)
+// ---------------------------------------------------------------------------
+
+export function fuzzyMatch(text: string, query: string): boolean {
+  if (!query) return true;
+  const t = text.toLowerCase();
+  const q = query.toLowerCase();
+  let i = 0;
+  for (const ch of t) {
+    if (ch === q[i]) i++;
+    if (i === q.length) return true;
+  }
+  return false;
+}
+
+function filterList(list: readonly string[], query: string): string[] {
+  if (!query) return [...list];
+  const prefixed = list.filter((item) => item.startsWith(query));
+  if (prefixed.length) return prefixed;
+  // Only fall back to subsequence matching when nothing starts with the query.
+  return list.filter((item) => fuzzyMatch(item, query));
+}
+
+function uniqueFlat(lists: string[][]): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const list of lists) {
+    for (const v of list) {
+      if (!seen.has(v)) {
+        seen.add(v);
+        out.push(v);
+      }
+    }
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Completion builders
+// ---------------------------------------------------------------------------
+
+function wrap(
+  candidates: string[],
+  headPrefix: string,
+  hints?: Record<string, string>,
+): AutocompleteItem[] | null {
+  if (candidates.length === 0) return null;
+  return candidates.map((c) => ({
+    value: `${headPrefix}${c}`,
+    label: c,
+    description: hints?.[c],
+  }));
+}
+
+function thinkingDescription(level: string, sig: ReviewSignals): string {
+  const recommended = sig.mode === "code" ? "high" : "xhigh";
+  const star = level === recommended ? "★ 推荐 " : "";
+  const map: Record<string, string> = {
+    off: "不思考（最快）",
+    minimal: "极简思考",
+    low: "低强度",
+    medium: "中强度",
+    high: "高强度（review 默认）",
+    xhigh: "极致思考（plan/challenge 推荐）",
+  };
+  return `${star}${map[level] ?? level}`;
+}
+
+function contextLabel(ctx: number): string {
+  if (ctx >= 1_000_000) return "1M+ ctx";
+  if (ctx >= 1000) return `${Math.round(ctx / 1000)}k ctx`;
+  return `${ctx} ctx`;
+}
+
+function modelItems(
+  models: ModelInfo[],
+  sig: ReviewSignals,
+  headPrefix: string,
+  tail: string,
+): AutocompleteItem[] | null {
+  const ranked = rankModelsForReview(models, sig);
+  const items = ranked.map((m, i) => {
+    const { score, reason } = scoreModelForReview(m, sig);
+    const recommended = i < 3 && score > 0;
+    const tag =
+      sig.mode === "plan" || sig.mode === "challenge" ? "plan/challenge" : "review";
+    return {
+      value: `${headPrefix}${m.label}`,
+      label: m.label,
+      description: [
+        recommended ? "★ 推荐" : "",
+        tag,
+        m.reasoning ? "reasoning" : "",
+        contextLabel(m.contextWindow),
+        reason,
+      ]
+        .filter(Boolean)
+        .join(" · "),
+    };
+  });
+  // Contiguous matching for model ids (subsequence is too loose for ids like
+  // "claude-opus" which would match "ope" via o-p...-e).
+  const q = tail;
+  const filtered = items.filter((it) => {
+    const label = it.label;
+    return (
+      label.startsWith(q) ||
+      label.includes(q) ||
+      // also allow matching by bare id / provider segment
+      label.split("/")[1]?.startsWith(q) ||
+      label.split("/")[0]?.startsWith(q)
+    );
+  });
+  return filtered.length ? filtered : null;
+}
+
+function thinkingSuffixItems(
+  tail: string,
+  models: ModelInfo[],
+  headPrefix: string,
+  sig: ReviewSignals,
+): AutocompleteItem[] | null {
+  const colonIdx = tail.lastIndexOf(":");
+  const modelPart = tail.slice(0, colonIdx);
+  const levelPart = tail.slice(colonIdx + 1);
+  if (!modelPart.includes("/")) return null;
+
+  const exact = models.filter((m) => m.label === modelPart);
+  const pool = exact.length
+    ? exact
+    : models.filter((m) => m.label.startsWith(modelPart) || m.id.startsWith(modelPart));
+  if (pool.length === 0) return null;
+
+  const levels = uniqueFlat(pool.map((m) => m.thinkingLevels));
+  const filtered = filterList(levels, levelPart);
+  if (filtered.length === 0) return null;
+  return filtered.map((level) => ({
+    value: `${headPrefix}${modelPart}:${level}`,
+    label: level,
+    description: thinkingDescription(level, sig),
+  }));
+}
+
+function sceneTemplates(
+  top: ModelInfo | undefined,
+  headPrefix: string,
+  tail: string,
+): AutocompleteItem[] {
+  if (!top) return [];
+  const pref = (m: ModelInfo, want: string): string => {
+    if (m.thinkingLevels.includes(want)) return want;
+    if (m.thinkingLevels.includes("high")) return "high";
+    return m.thinkingLevels[0] ?? "";
+  };
+  const suffix = (want: string): string => {
+    const lvl = pref(top, want);
+    return lvl ? `:${lvl}` : "";
+  };
+
+  const templates = [
+    {
+      cmd: `--mode code --model ${top.label}${suffix("high")} @`,
+      label: "审代码改动（推荐配置）",
+    },
+    {
+      cmd: `--mode plan --model ${top.label}${suffix("high")} @`,
+      label: "架构 / 计划评审",
+    },
+    {
+      cmd: `--mode challenge --keep-session --model ${top.label}${suffix("xhigh")} @`,
+      label: "对抗性方案评审（可追问）",
+    },
+  ];
+  return templates
+    .filter((t) => fuzzyMatch(t.label, tail) || t.cmd.includes(tail))
+    .map((t) => ({
+      value: `${headPrefix}${t.cmd}`,
+      label: t.label,
+      description: t.cmd,
+    }));
+}
+
+function flagItems(head: string[], tail: string, headPrefix: string): AutocompleteItem[] | null {
+  // Don't re-suggest boolean flags already present.
+  const present = new Set(head);
+  const candidates = filterList(RV_FLAGS, tail).filter((f) => {
+    if (f === "--keep-session" || f === "--no-stream") return !present.has(f);
+    return true;
+  });
+  return wrap(candidates, headPrefix, FLAG_HINTS);
+}
+
+function topLevelCompletions(
+  head: string[],
+  tail: string,
+  deps: CompletionDeps,
+  headPrefix: string,
+  sig: ReviewSignals,
+): AutocompleteItem[] | null {
+  const items: AutocompleteItem[] = [];
+
+  // Scene templates (only at top level, before any target/mode chosen is fine).
+  const ranked = deps.models?.length ? rankModelsForReview(deps.models, sig) : [];
+  items.push(...sceneTemplates(ranked[0], headPrefix, tail));
+
+  // `models` keyword.
+  if (fuzzyMatch("models", tail) || "models".startsWith(tail)) {
+    items.push({
+      value: `${headPrefix}models`,
+      label: "models",
+      description: "仅列出 pi-review 可用模型",
+    });
+  }
+
+  // Flags.
+  const flags = flagItems(head, tail, headPrefix);
+  if (flags) items.push(...flags);
+
+  return items.length ? items : null;
+}
+
+// ---------------------------------------------------------------------------
+// Public entry point
+// ---------------------------------------------------------------------------
+
+export function buildRvCompletions(
+  prefix: string,
+  deps: CompletionDeps,
+): AutocompleteItem[] | null {
+  const { head, rawHead, tail, prev } = tokenizeArgPrefix(prefix);
+  const joinedHead = rawHead.join(" ");
+  const headPrefix = joinedHead ? `${joinedHead} ` : "";
+  const sig = extractSignals(head, deps);
+
+  // 1) --model value position (model list or :thinking suffix).
+  if (prev === "--model") {
+    const colonIdx = tail.lastIndexOf(":");
+    if (colonIdx !== -1 && tail.slice(0, colonIdx).includes("/")) {
+      const items = thinkingSuffixItems(tail, deps.models ?? [], headPrefix, sig);
+      return items;
+    }
+    return modelItems(deps.models ?? [], sig, headPrefix, tail);
+  }
+
+  // 2) --mode value position.
+  if (prev === "--mode") {
+    return wrap(filterList(RV_MODE_VALUES, tail), headPrefix, MODE_HINTS);
+  }
+
+  // 3) --thinking value position.
+  if (prev === "--thinking") {
+    return wrap(filterList(THINKING_LEVELS, tail), headPrefix);
+  }
+
+  // 4) --continue value position: defer (no static list; handler owns it).
+  if (prev === "--continue") return null;
+
+  // 5) Flag completion (tail starts with "--").
+  if (tail.startsWith("--")) {
+    return flagItems(head, tail, headPrefix);
+  }
+
+  // 6) File attachment in progress → defer to built-in file completion.
+  if (tail.startsWith("@")) return null;
+
+  // 7) Top-level: scene templates + `models` + flags.
+  return topLevelCompletions(head, tail, deps, headPrefix, sig);
+}

package/extensions/rv-prompts.test.ts

@@ -42,6 +42,21 @@ describe("parseRvArgs / validateRvParsed", () => {
     ]);
   });
 
+  it("parses --thinking and threads it into CLI argv", () => {
+    const p = parseRvArgs("--thinking xhigh --model openai/gpt-5.5 @x.md");
+    assert.equal(p.thinking, "xhigh");
+    assert.equal(p.model, "openai/gpt-5.5");
+    assert.deepEqual(buildPiReviewArgv(p, "@x.md"), [
+      "pi-review",
+      "--model",
+      "openai/gpt-5.5",
+      "--thinking",
+      "xhigh",
+      "--",
+      "@x.md",
+    ]);
+  });
+
   it("orchestration prompt forbids default no-stream and progress-log in Pi", () => {
     const p = parseRvArgs("@src/foo.ts");
     const prompt = buildRvOrchestrationPrompt(p);

package/extensions/rv-prompts.ts

@@ -3,11 +3,12 @@
 export const RV_MODES = ["code", "plan", "challenge"] as const;
 export type RvMode = (typeof RV_MODES)[number];
 
-const FLAGS_REQUIRING_VALUE = ["--mode", "--model", "--continue"] as const;
+const FLAGS_REQUIRING_VALUE = ["--mode", "--model", "--thinking", "--continue"] as const;
 
 export type RvParsed = {
   mode: string;
   model?: string;
+  thinking?: string;
   keepSession: boolean;
   noStream: boolean;
   continueHandle?: string;
@@ -25,6 +26,7 @@ export function parseRvArgs(raw: string): RvParsed {
 
   let mode = "code";
   let model: string | undefined;
+  let thinking: string | undefined;
   let keepSession = false;
   let noStream = false;
   let continueHandle: string | undefined;
@@ -63,6 +65,15 @@ export function parseRvArgs(raw: string): RvParsed {
       model = cleaned[++i];
       continue;
     }
+    if (t === "--thinking") {
+      const v = cleaned[i + 1];
+      if (!v || v.startsWith("--")) {
+        rest.push(t);
+        continue;
+      }
+      thinking = cleaned[++i];
+      continue;
+    }
     if (t === "--continue") {
       const v = cleaned[i + 1];
       if (!v || v.startsWith("--")) {
@@ -78,6 +89,7 @@ export function parseRvArgs(raw: string): RvParsed {
   return {
     mode,
     model,
+    thinking,
     keepSession,
     noStream,
     continueHandle,
@@ -108,6 +120,7 @@ export function buildPiReviewArgv(parsed: RvParsed, target: string): string[] {
   }
   if (parsed.mode !== "code") parts.push("--mode", parsed.mode);
   if (parsed.model) parts.push("--model", parsed.model);
+  if (parsed.thinking) parts.push("--thinking", parsed.thinking);
   if (parsed.noStream) parts.push("--no-stream");
   parts.push("--", target);
   return parts;
@@ -168,8 +181,10 @@ export function buildRvOrchestrationPrompt(parsed: RvParsed): string {
   const cliLine = buildPiReviewArgv(parsed, target).join(" ");
 
   const modelStep = parsed.model
-    ? `Use model exactly as given: ${parsed.model} (must appear in pi-review models output).`
-    : "Run pi-review models first if needed; pick a suitable listed ID or omit --model for Pi default.";
+    ? `Use model exactly as given: ${parsed.model}${parsed.thinking ? ` at thinking ${parsed.thinking}` : ""} (model must appear in pi-review models output).`
+    : parsed.thinking
+      ? `Run pi-review models first if needed; pick a suitable listed ID or omit --model for Pi default. Use thinking ${parsed.thinking}.`
+      : "Run pi-review models first if needed; pick a suitable listed ID or omit --model for Pi default.";
 
   const continueNote = parsed.continueHandle
     ? "Continuing an existing review session. Optional --mode and --model match the same flags as an initial /rv run."
@@ -197,6 +212,7 @@ export const RV_COMPLETIONS: { value: string; hint: string }[] = [
   { value: "--mode plan", hint: "architecture or plan review" },
   { value: "--mode challenge", hint: "adversarial plan review" },
   { value: "--model ", hint: "provider/model from pi-review models" },
+  { value: "--thinking ", hint: "off|minimal|low|medium|high|xhigh" },
   { value: "--keep-session", hint: "persist session for follow-up" },
   { value: "--no-stream", hint: "rare: buffer until exit (not default in Pi)" },
   { value: "--continue ", hint: "resume session; same optional flags as initial /rv" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zephyrdeng/pi-review",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Isolated AI-powered code and plan reviews from the command line",
   "type": "module",
   "author": "ZephyrDeng <zephyrTang@aliyun.com>",
@@ -67,8 +67,8 @@
     "build": "tsc",
     "check": "tsc --noEmit",
     "smoke": "node dist/cli.js --help >/dev/null",
-    "test": "npx --yes tsx --test src/child-process.test.ts src/review.meta.test.ts src/meta-footer.test.ts src/json-events.test.ts src/install-args.test.ts extensions/rv-prompts.test.ts",
-    "test:rv": "npx --yes tsx --test extensions/rv-prompts.test.ts",
+    "test": "npx --yes tsx --test src/child-process.test.ts src/review.meta.test.ts src/meta-footer.test.ts src/json-events.test.ts src/install-args.test.ts extensions/rv-prompts.test.ts extensions/rv-completions.test.ts",
+    "test:rv": "npx --yes tsx --test extensions/rv-prompts.test.ts extensions/rv-completions.test.ts",
     "prepublishOnly": "npm run build",
     "pack:dry": "npm pack --dry-run"
   },

package/skills/pi-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pi-review
-description: Use pi-review to delegate isolated code, diff, repository, architecture, or plan reviews to a fresh Pi session and return only the review conclusion. Use when the user asks for Pi review, isolated review, code review, plan review, challenge review, review status/progress, or wants to avoid context pollution.
+description: Use pi-review to delegate isolated code, diff, repository, architecture, or plan reviews to a fresh Pi session and return only the review conclusion. On Claude Code or Codex, default to --progress-log with a background shell run and tail the log (chat tools buffer stdout). Use when the user asks for Pi review, isolated review, code review, plan review, challenge review, review status/progress, or wants to avoid context pollution.
 ---
 
 # Pi Review
@@ -23,17 +23,36 @@ node ../../bin/pi-review.js --help
 
 When resolving this fallback, use the actual directory that contains this `SKILL.md`.
 
+## Codex / Claude Code
+
+- Map skill mentions of `Bash` to your host shell tool.
+- Read **[references/codex-tools.md](./references/codex-tools.md)** (next to this `SKILL.md`) for Codex/Claude Code defaults: `--progress-log` + background run + tail.
+- Do not use a blocking foreground shell alone for live progress; follow **Default workflow by host** below.
+
+## Default workflow by host
+
+| Host | How to run `pi-review` |
+|------|-------------------------|
+| **Pi** (`/rv`) | Foreground CLI, **default streaming** only. Do **not** add `--no-stream` or `--progress-log` unless the user explicitly asks. |
+| **Claude Code, Codex, Cursor**, and similar AI agents | **Default: `--progress-log <path>` + background run + tail** (see below). Do **not** rely on foreground Bash stdout for “streaming” — the tool buffers until exit. |
+| Scripts / CI | Foreground is fine; use `--no-stream` only when you must buffer until exit. |
+
 ## Pi host (`/rv`)
 
 - In **Pi interactive** sessions, run `pi-review` with **default streaming only** — do **not** add `--no-stream` or `--progress-log` unless the user explicitly asks.
 - The `/rv` extension injects these rules into the parent agent; ordinary `/rv @path` needs no extra flags.
 
-## Streaming vs agent hosts
+## Streaming vs agent hosts (Claude Code / Codex)
 
-- `pi-review` **streams** child `pi` stdout/stderr to the process terminal by default (`--no-stream` buffers until exit).
-- **Pi** with `/rv` or a foreground bash that inherits stdio: users often see output arrive live.
-- **Claude Code, Cursor, Codex**, and similar hosts usually **buffer tool stdout** until the bash command exits, so the chat may show the review **all at once** even though the CLI is streaming. That is expected—not a misconfiguration. Also note: pi-review's default `text` mode produces **no output at all** during the tool-use/thinking phase (only the final answer), so even a local terminal looks silent for most of a multi-minute review.
-- For **live** progress in those hosts, prefer `--progress-log <path>`: it runs the child in `--mode json` and writes a structured, incremental event log to that file, independent of host stdout buffering. Run `pi-review --progress-log <path> ...` with a background/async tool call, then tail the file (e.g. with a Monitor-style tool) filtering out `message_update`/`tool_execution_update` (high-frequency token deltas) to surface milestone events. Fall back to a **local terminal** running the same command only if the host has no way to run a background command or tail a file.
+- `pi-review` **streams** child `pi` stdout/stderr to the process terminal by default (`--no-stream` buffers until exit). That helps **Pi** and real terminals, not most agent chat UIs.
+- **Claude Code, Cursor, Codex**, and similar hosts **buffer tool stdout** until the bash command exits, so the chat shows the review **all at once** even though the CLI is streaming. That is expected—not a misconfiguration.
+- Default `text` mode also produces **no stdout** during tool-use/thinking (only the final answer), so even a local terminal stays quiet for most of a multi-minute review.
+- **Recommended for Claude Code / Codex (live progress):** always use `--progress-log <path>` unless the user explicitly wants a silent blocking wait:
+  1. Pick a writable path (e.g. `/tmp/pi-review-<id>.jsonl`).
+  2. Start `pi-review --progress-log <path> ...` in a **background** or **async** shell invocation (not a blocking foreground Bash that you wait on with no updates).
+  3. While the child runs, **tail** the log and summarize milestones to the user (filter out `message_update` / `tool_execution_update` unless they asked for token-level detail).
+  4. When the process exits, show the Markdown body and ASCII `── pi-review` footer from the command result (or re-read the final output as the skill’s step 4 describes).
+- Fall back to a **local terminal** with default streaming only if the host cannot run background commands or tail a file.
 
 ## Review status (no slash command)
 
@@ -87,8 +106,9 @@ Do not implement findings from a status check; status is informational only.
    - Use `--continue <handle>` only with a **Session** path from a prior ASCII footer or `sessionHandle` in `PI_REVIEW_META_JSON`.
    - Put file references as `@path` after `--`.
    - Do not ask `pi-review` to edit, patch, commit, or implement.
-   - Default streams child output live; add `--no-stream` only when the caller must buffer until exit (cannot combine with `--progress-log`).
-   - In a host that buffers tool stdout (Claude Code, Codex, ...), prefer running with `--progress-log <path>` in the background and tailing the file for live progress instead of waiting on the blocking call.
+   - **Pi `/rv`:** default streaming; no `--progress-log` unless the user asked.
+   - **Claude Code / Codex / Cursor:** **include `--progress-log <path>` by default**; background the CLI and tail the log for user-visible progress. Foreground Bash alone does not stream in chat.
+   - Add `--no-stream` only when the caller must buffer until exit (cannot combine with `--progress-log`).
    Completion criterion: the command includes the resolved model/default choice and a concrete review target.
 
 4. Return the result:

package/skills/pi-review/references/codex-tools.md

@@ -0,0 +1,34 @@
+# Agent host tool notes (Codex / Claude Code)
+
+Skills may use Claude Code tool names. On **Codex** or **Claude Code**, map them to your native tools:
+
+| Skill references | Typical host equivalent |
+|-----------------|-------------------------|
+| `Bash` (run commands) | Native shell / terminal tool |
+| `Read`, `Write`, `Edit` | Native file tools |
+| `Skill` | Load and follow the skill instructions directly |
+
+General Codex subagent and worktree mappings live in the **using-superpowers** skill (`references/codex-tools.md`) when that skill is installed; this file is **pi-review–specific** and ships with the pi-review package.
+
+## Long-running `pi-review` (default on Codex / Claude Code)
+
+Native shell tools usually **buffer stdout/stderr until the command exits**. A multi-minute `pi-review` run can look like a silent wait, then one large dump—even though the CLI streams by default. Default `text` mode also emits **no stdout** during tool-use/thinking (only the final answer).
+
+When the **pi-review** skill applies on Codex, Claude Code, or Cursor:
+
+1. **Default:** `pi-review --progress-log <path> ...` (writable file, e.g. `/tmp/pi-review-<id>.jsonl`).
+2. Start that command in a **background** or **async** shell invocation—not a single blocking call with no interim updates.
+3. **Tail** the log while the child runs; summarize milestones to the user (skip `message_update` / `tool_execution_update` unless they want token-level detail).
+4. After exit, show the Markdown review and ASCII `── pi-review` footer (skill step 4).
+
+**Pi interactive (`/rv`)** is different: foreground `pi-review`, default streaming only—do **not** auto-add `--progress-log` unless the user asked.
+
+See the parent skill: sections *Default workflow by host* and *Streaming vs agent hosts (Claude Code / Codex)*.
+
+Example tail (milestone events only):
+
+```bash
+tail -f -n +1 /tmp/pi-review.jsonl | jq -c --unbuffered '
+  select(.type != "message_update" and .type != "tool_execution_update")
+'
+```