@zephyrdeng/pi-review 0.4.4 → 0.4.5

package/README.md

@@ -22,10 +22,18 @@ Works as a standalone CLI, a Pi package (extension + skill), or integrated into
 - **Model-agnostic** — use any model available in your Pi installation
 - **Session continuity** — keep sessions alive for follow-up questions with `--keep-session`
 - **Customizable presets** — extend or override review modes via JSON configuration
-- **Pi package integration** — `/pi-review` slash command and agent skill included
+- **Pi package integration** — `/rv` slash command and agent skill included
+
+## Language policy
+
+- **Source code** (CLI, extensions, presets, prompts, TUI strings emitted from code): **English only**.
+- **Documentation** may be bilingual. See [README.zh-CN.md](./README.zh-CN.md) for 中文说明.
+- **Git commits**: [Husky](https://typicode.github.io/husky/) runs `ai-commit` on `prepare-commit-msg` / `commit-msg` / `pre-commit` (see [`.husky/`](./.husky/)). Config: [`.ai-commit.yaml`](./.ai-commit.yaml) (English, `ai_footer: off`, **ai-commit v0.1.45+** on PATH). Or run `ai-commit commit` / `ai-commit generate` directly after `git add`.
 
 ## Installation
 
+Dev dependencies use the [public npm registry](https://registry.npmjs.org/) (see [`.npmrc`](./.npmrc)); run `npm install` in the repo root for Husky hooks.
+
 ### CLI (recommended)
 
 ```bash
@@ -122,8 +130,8 @@ PI_REVIEW_META: {"reviewMode":"code","verdict":"request_changes","verdictSource"
 # Keep a review session for follow-up
 pi-review --mode challenge --keep-session -- @docs/design.md
 
-# Continue a previous session
-pi-review --mode challenge --continue <sessionHandle> -- "expand finding 2"
+# Continue a previous session (same optional flags as an initial run)
+pi-review --continue <sessionHandle> --mode challenge --model provider/model -- "expand finding 2"
 ```
 
 ## CLI Reference
@@ -166,7 +174,16 @@ After installing as a Pi package, use the `/rv` slash command:
 /rv --mode challenge @docs/design.md
 ```
 
-The `/rv` command sends the review request to the agent, which uses the pi-review skill to run an isolated review session.
+The `/rv` command injects a task message for the parent agent (mode-specific instructions + the `pi-review` CLI to run). The agent follows the **pi-review** skill and runs an isolated child session.
+
+```
+/rv models
+/rv @src/foo.ts
+/rv --mode plan @docs/architecture.md
+/rv --mode challenge --keep-session @docs/design.md
+```
+
+Argument completions (`--mode`, `@`, `models`, etc.) are hints only; execution is skill-driven.
 
 ## Security
 

package/README.zh-CN.md

@@ -0,0 +1,85 @@
+# pi-review
+
+[English README](./README.md)
+
+**在命令行中运行隔离的 AI 代码与方案审查。**
+
+`pi-review` 把审查工作交给一次全新的、隔离的 [Pi](https://github.com/anthropics/pi) 子会话，并返回结构化结论。子会话只读、只评，不改文件、不打补丁、不提交。
+
+可作为独立 CLI、Pi 包（扩展 + skill），或接入 CI / 编辑器工作流。
+
+## 语言约定
+
+| 范围 | 语言 |
+|------|------|
+| 源码（CLI、扩展、`review-presets.json`、提示词、代码里的用户可见文案） | **仅英文** |
+| 文档（本页与英文 README） | **中英均可** |
+
+实现与对外协议（如 `PI_REVIEW_META`、Verdict 枚举）保持英文，便于自动化与跨工具一致。
+
+## 前置条件
+
+- 已安装并配置好 [Pi CLI](https://pi.dev)，且至少有一个可用模型
+
+## 安装
+
+```bash
+npm install -g @zephyrdeng/pi-review
+# 或 Pi 包
+pi install npm:@zephyrdeng/pi-review
+# 或安装 skill 到各 Agent
+npx @zephyrdeng/pi-review install-skill
+```
+
+## 快速开始
+
+```bash
+pi-review -- @src/foo.ts
+pi-review --model openai/gpt-5.5 -- @src/foo.ts
+pi-review --mode plan -- @docs/architecture.md
+pi-review --mode challenge -- @docs/design.md
+pi-review models
+```
+
+## 审查模式
+
+| 模式 | 说明 |
+|------|------|
+| `code`（默认） | 代码、diff、MR、文件与仓库审查 |
+| `plan` | 多视角方案 / 架构审查 |
+| `challenge` | 对抗式审查，压测假设与证据缺口 |
+
+## Pi 包：`/rv` 命令
+
+安装 Pi 包后可在 Pi 里使用 `/rv`：
+
+```
+/rv models
+/rv @src/foo.ts
+/rv --mode challenge @docs/design.md
+/rv --continue <handle> --mode challenge --model provider/model "expand finding 2"
+```
+
+跟进审查时，`--continue` 与首次 `/rv` 一样可**选填** `--mode`、`--model`（以及后续 CLI 支持的其它选项由 skill 直接调用 CLI 时传入）。
+
+`/rv` 会向主会话注入**英文任务说明**（按 `--mode` 等参数区分），由主 Agent 按 **pi-review** skill 调用 `pi-review` CLI 跑子会话。Tab 补全是固定选项提示，不是另一套实现。
+
+## 输出格式
+
+审查结果包含 `## Verdict`、`## Summary`、`## Findings` 等章节，并以 `PI_REVIEW_META: {...}` 结尾（英文 JSON，便于脚本解析）。
+
+## 配置
+
+提交代码：`npm install` 后会启用 **Husky** 钩子（`.husky/` → `ai-commit` 的 prepare-commit-msg / commit-msg / pre-commit）。也可 `git add` 后直接 `ai-commit commit`。配置见 `.ai-commit.yaml`（英文、`ai_footer: off`，需本机安装 ai-commit ≥ v0.1.45）。
+
+可通过 `PI_REVIEW_HOME`、`PI_REVIEW_PRESETS`、`PI_REVIEW_SYSTEM_PROMPT` 等环境变量覆盖预设与系统提示词路径。预设与审查指令文件内容均为英文。
+
+## 安全
+
+- 每次审查在隔离子进程中运行
+- 默认不保留子会话；`--keep-session` 仅用于显式跟进
+- 审查会话只读，不编辑、不部署
+
+## 许可
+
+[MIT](LICENSE) © ZephyrDeng

package/extensions/review.ts

@@ -1,27 +1,41 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  buildRvOrchestrationPrompt,
+  parseRvArgs,
+  RV_COMPLETIONS,
+  validateRvParsed,
+} from "./rv-prompts.js";
 
 export default function piReviewExtension(pi: ExtensionAPI) {
   pi.registerCommand("rv", {
-    description: "Delegate a pi-review to the agent. Usage: /rv @file-or-text",
+    description:
+      "Delegate pi-review to the agent. Usage: /rv [--mode plan|challenge] [--model id] [--keep-session] @target | /rv --continue <handle> [opts] [text] | models",
     getArgumentCompletions: (prefix) => {
-      const items = [
-        "@",
-        "--mode challenge",
-        "--mode plan",
-        "--model ",
-        "--keep-session",
-        "models",
-      ];
-      const filtered = items.filter((item) => item.startsWith(prefix));
-      return filtered.length ? filtered.map((value) => ({ value, label: value })) : null;
+      const filtered = RV_COMPLETIONS.filter((item) => item.value.startsWith(prefix));
+      return filtered.length
+        ? filtered.map(({ value, hint }) => ({ value, label: value, description: hint }))
+        : null;
     },
     handler: async (rawArgs, ctx) => {
       const trimmed = rawArgs.trim();
       if (!trimmed) {
-        ctx.ui.notify("Usage: /rv [--mode challenge] @file-or-text", "warning");
+        ctx.ui.notify("/rv needs a target or `models`. Try: /rv @path or /rv models", "warning");
         return;
       }
-      pi.sendUserMessage(`使用 pi-review 审查: ${trimmed}`);
+
+      const parsed = parseRvArgs(trimmed);
+      const validation = validateRvParsed(parsed);
+      if (!validation.ok) {
+        ctx.ui.notify(validation.message, "warning");
+        return;
+      }
+
+      if (!parsed.modelsOnly && !parsed.target && !parsed.continueHandle) {
+        ctx.ui.notify("/rv needs a target, --continue <handle>, or `models`.", "warning");
+        return;
+      }
+
+      pi.sendUserMessage(buildRvOrchestrationPrompt(parsed));
     },
   });
-}
+}

package/extensions/rv-prompts.test.ts

@@ -0,0 +1,53 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { buildPiReviewArgv, parseRvArgs, validateRvParsed } from "./rv-prompts.js";
+
+describe("parseRvArgs / validateRvParsed", () => {
+  it("parses continue with optional mode and model", () => {
+    const p = parseRvArgs("--continue abc123 --mode challenge --model zenmux/foo expand finding 2");
+    assert.equal(p.continueHandle, "abc123");
+    assert.equal(p.mode, "challenge");
+    assert.equal(p.model, "zenmux/foo");
+    assert.equal(p.target, "expand finding 2");
+    assert.equal(validateRvParsed(p).ok, true);
+  });
+
+  it("passes custom preset mode through to CLI argv", () => {
+    const p = parseRvArgs("--mode plan-bigbang @x.md");
+    assert.equal(p.mode, "plan-bigbang");
+    assert.equal(validateRvParsed(p).ok, true);
+    assert.deepEqual(buildPiReviewArgv(p, "@x.md"), ["pi-review", "--mode", "plan-bigbang", "--", "@x.md"]);
+  });
+
+  it("rejects keep-session with continue", () => {
+    const p = parseRvArgs("--keep-session --continue h -- foo");
+    const v = validateRvParsed(p);
+    assert.equal(v.ok, false);
+  });
+
+  it("buildPiReviewArgv matches for initial and continue", () => {
+    const initial = parseRvArgs("--mode plan --model m/a @doc.md");
+    assert.deepEqual(buildPiReviewArgv(initial, "@doc.md"), [
+      "pi-review",
+      "--mode",
+      "plan",
+      "--model",
+      "m/a",
+      "--",
+      "@doc.md",
+    ]);
+
+    const cont = parseRvArgs("--continue h --mode plan --model m/a more");
+    assert.deepEqual(buildPiReviewArgv(cont, "more"), [
+      "pi-review",
+      "--continue",
+      "h",
+      "--mode",
+      "plan",
+      "--model",
+      "m/a",
+      "--",
+      "more",
+    ]);
+  });
+});

package/extensions/rv-prompts.ts

@@ -0,0 +1,192 @@
+/** /rv → parent-agent task text; child review uses resources/review-presets.json */
+
+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;
+
+export type RvParsed = {
+  mode: string;
+  model?: string;
+  keepSession: boolean;
+  continueHandle?: string;
+  modelsOnly: boolean;
+  target: string;
+};
+
+export type RvValidation =
+  | { ok: true }
+  | { ok: false; message: string };
+
+export function parseRvArgs(raw: string): RvParsed {
+  const tokens = raw.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) ?? [];
+  const cleaned = tokens.map((t) => t.replace(/^['"]|['"]$/g, ""));
+
+  let mode = "code";
+  let model: string | undefined;
+  let keepSession = false;
+  let continueHandle: string | undefined;
+  let modelsOnly = false;
+  const rest: string[] = [];
+
+  for (let i = 0; i < cleaned.length; i++) {
+    const t = cleaned[i];
+    if (t === "models" && rest.length === 0 && i === cleaned.length - 1) {
+      modelsOnly = true;
+      continue;
+    }
+    if (t === "--keep-session") {
+      keepSession = true;
+      continue;
+    }
+    if (t === "--mode") {
+      const m = cleaned[i + 1];
+      if (!m || m.startsWith("--")) {
+        rest.push(t);
+        continue;
+      }
+      mode = cleaned[++i];
+      continue;
+    }
+    if (t === "--model") {
+      const v = cleaned[i + 1];
+      if (!v || v.startsWith("--")) {
+        rest.push(t);
+        continue;
+      }
+      model = cleaned[++i];
+      continue;
+    }
+    if (t === "--continue") {
+      const v = cleaned[i + 1];
+      if (!v || v.startsWith("--")) {
+        rest.push(t);
+        continue;
+      }
+      continueHandle = cleaned[++i];
+      continue;
+    }
+    rest.push(t);
+  }
+
+  return {
+    mode,
+    model,
+    keepSession,
+    continueHandle,
+    modelsOnly,
+    target: rest.join(" ").trim(),
+  };
+}
+
+export function validateRvParsed(parsed: RvParsed): RvValidation {
+  if (parsed.keepSession && parsed.continueHandle) {
+    return { ok: false, message: "--keep-session and --continue cannot be used together." };
+  }
+  for (const flag of FLAGS_REQUIRING_VALUE) {
+    if (parsed.target === flag) {
+      return { ok: false, message: `Missing value for ${flag}.` };
+    }
+  }
+  return { ok: true };
+}
+
+/** Same optional flags for initial review and --continue follow-up (all optional). */
+export function buildPiReviewArgv(parsed: RvParsed, target: string): string[] {
+  const parts = ["pi-review"];
+  if (parsed.continueHandle) {
+    parts.push("--continue", parsed.continueHandle);
+  } else if (parsed.keepSession) {
+    parts.push("--keep-session");
+  }
+  if (parsed.mode !== "code") parts.push("--mode", parsed.mode);
+  if (parsed.model) parts.push("--model", parsed.model);
+  parts.push("--", target);
+  return parts;
+}
+
+function baseRules(): string {
+  return [
+    "Follow the pi-review skill.",
+    "Run pi-review in an isolated child session; return only the review conclusion.",
+    "Do not edit, patch, commit, or implement findings unless the user asks separately.",
+    "Preserve the final PI_REVIEW_META line from pi-review output.",
+  ].join(" ");
+}
+
+export function buildRvOrchestrationPrompt(parsed: RvParsed): string {
+  if (parsed.modelsOnly) {
+    return [
+      "Run the pi-review model catalog step.",
+      baseRules(),
+      "Execute: pi-review models",
+      "Summarize briefly: provider count and 2–3 model IDs that fit code review vs plan/challenge.",
+      "Do not start a review until the user supplies a target (@path or text).",
+    ].join("\n\n");
+  }
+
+  const followUpDefault = "follow up on the previous review";
+  const target = parsed.target || (parsed.continueHandle ? followUpDefault : "");
+
+  if (!target && !parsed.continueHandle) {
+    return [
+      "/rv needs a review target.",
+      "Usage: /rv [--mode code|plan|challenge] [--model provider/model] [--keep-session] @files-or-brief",
+      "Continue: /rv --continue <handle> [--mode ...] [--model ...] [follow-up text]",
+      "Examples: /rv @src/foo.ts | /rv --mode challenge @docs/design.md | /rv models",
+    ].join("\n\n");
+  }
+
+  const modeBlock: Record<string, string> = {
+    code: [
+      "Mode: code (default).",
+      "Focus: correctness, regressions, security, concurrency, API contracts, edge cases, tests.",
+      "Use read-only inspection via pi-review; no file mutations.",
+    ].join(" "),
+    plan: [
+      "Mode: plan.",
+      "Review architecture, design, or strategy through engineering, product, security, QA, ops, and DX lenses.",
+      "Identify fatal flaws, trade-offs, sequencing risks, and minimal changes to de-risk the plan.",
+    ].join(" "),
+    challenge: [
+      "Mode: challenge (adversarial).",
+      "Pressure-test assumptions, boundaries, dependencies, failure modes, migration, and missing evidence.",
+      "One-shot conclusion; do not run a live Q&A interview.",
+    ].join(" "),
+  };
+
+  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.";
+
+  const continueNote = parsed.continueHandle
+    ? "Continuing an existing review session. Optional --mode and --model match the same flags as an initial /rv run."
+    : parsed.keepSession
+      ? "Use --keep-session so the user can follow up with /rv --continue <handle>."
+      : "";
+
+  return [
+    parsed.continueHandle ? "Continue a prior pi-review session." : "Run pi-review for the target below.",
+    baseRules(),
+    modeBlock[parsed.mode] ??
+      `Mode: ${parsed.mode}. Follow the preset named in review-presets.json when present.`,
+    modelStep,
+    continueNote,
+    `Execute:\n${cliLine}`,
+  ]
+    .filter(Boolean)
+    .join("\n\n");
+}
+
+export const RV_COMPLETIONS: { value: string; hint: string }[] = [
+  { value: "@", hint: "file path after @ (e.g. @src/foo.ts)" },
+  { value: "models", hint: "list pi-review models only" },
+  { value: "--mode code", hint: "code / diff / MR review" },
+  { 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: "--keep-session", hint: "persist session for follow-up" },
+  { value: "--continue ", hint: "resume session; same optional flags as initial /rv" },
+];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zephyrdeng/pi-review",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "description": "Isolated AI-powered code and plan reviews from the command line",
   "type": "module",
   "author": "ZephyrDeng <zephyrTang@aliyun.com>",
@@ -58,13 +58,16 @@
     }
   },
   "devDependencies": {
-    "typescript": "^5.8.0",
-    "@types/node": "^22.0.0"
+    "@types/node": "^22.0.0",
+    "husky": "^9.1.7",
+    "typescript": "^5.8.0"
   },
   "scripts": {
+    "prepare": "husky",
     "build": "tsc",
     "check": "tsc --noEmit",
     "smoke": "node dist/cli.js --help >/dev/null",
+    "test:rv": "npx --yes tsx --test extensions/rv-prompts.test.ts",
     "prepublishOnly": "npm run build",
     "pack:dry": "npm pack --dry-run"
   },