@unifan/pi-unifan-zh 1.0.0

package/extensions/review/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@unifan/pi-review-zh",
+  "version": "1.0.0",
+  "description": "Pi AI 并发代码审查扩展（多专家子代理并发 + 门禁裁判系统，中文增强版）",
+  "type": "module",
+  "license": "MIT",
+  "author": "821869798",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/821869798/pi-unifan-zh.git"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "code-review",
+    "reviewer",
+    "chinese"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-ai": ">=0.74.0 <1.0.0",
+    "@earendil-works/pi-coding-agent": ">=0.74.0 <1.0.0",
+    "pi-subagents": ">=0.41.0 <1.0.0"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "subagents": {
+      "agents": [
+        "./agents"
+      ]
+    }
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.0"
+  }
+}

package/extensions/review/reference/README.md

@@ -0,0 +1,20 @@
+# pi-review reference
+
+Design references and version planning. Read these before changing pipeline shape, reviewer roster, or gate behavior so we do not drift from agreed intent.
+
+| Document | Contents |
+|----------|----------|
+| [claude-code-review.md](./claude-code-review.md) | Official Claude `/code-review` pipeline (source of truth: `commands/code-review.md`) |
+| [cursor-review-skills.md](./cursor-review-skills.md) | Cursor Bugbot / Security Review skills (what to borrow, what not to) |
+| [pi-review-roadmap.md](./pi-review-roadmap.md) | pi-review adaptation, phase mapping, version plan |
+| [v0.2-plan.md](./v0.2-plan.md) | **v0.2.0 task list**, acceptance criteria, implementation order |
+| [structured-output.md](./structured-output.md) | Child capture extension env contract |
+
+**Primary upstream (Claude):**  
+https://github.com/anthropics/claude-plugins-official/blob/main/plugins/code-review/commands/code-review.md
+
+**When to update this folder**
+
+- Upstream Claude command changes
+- Reviewer roster or pipeline phase changes in pi-review
+- Default threshold / gate semantics change

package/extensions/review/reference/claude-code-review.md

@@ -0,0 +1,133 @@
+# Claude Code Review — reference
+
+> **Source of truth:** `anthropics/claude-plugins-official` → `plugins/code-review/commands/code-review.md`  
+> **Secondary (may be stale):** `plugins/code-review/README.md` — describes 4 agents and “2× CLAUDE.md compliance”; the command file is authoritative and lists **5 distinct content agents**.
+
+Last verified: 2026-07-19.
+
+## Product intent
+
+Automated PR review: multiple independent agents audit the same change from different angles, then **confidence scoring** filters false positives so only high-signal issues are posted.
+
+- **Trigger:** `/code-review` (GitHub PR context, uses `gh`)
+- **Output:** PR comment with issues ≥ threshold (default **80/100**), or no comment if none qualify
+- **Not in scope:** auto-fix, harness gating merges, worktree isolation
+
+## Pipeline (ordered phases)
+
+Claude is **not** “spawn N reviewers and done”. It is a **sequential pipeline** with one parallel batch in the middle.
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ Phase 1 — Eligibility (Haiku)                                   │
+│ Skip if: closed, draft, trivial/automated, already reviewed     │
+│ → STOP if ineligible                                            │
+└────────────────────────────┬────────────────────────────────────┘
+                             ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ Phase 2 — Prep (Haiku, sequential)                              │
+│ 2a. List paths to relevant CLAUDE.md files (not full contents)  │
+│ 2b. Summarize PR / change                                       │
+└────────────────────────────┬────────────────────────────────────┘
+                             ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ Phase 3 — Content review (5× Sonnet, PARALLEL)                  │
+│ Each returns issues + reason flagged (compliance, bug, history…)  │
+└────────────────────────────┬────────────────────────────────────┘
+                             ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ Phase 4 — Confidence scoring (Haiku, PARALLEL per issue)        │
+│ One scorer agent per issue from Phase 3                         │
+│ Rubric: 0 / 25 / 50 / 75 / 100 (verbatim in command)            │
+└────────────────────────────┬────────────────────────────────────┘
+                             ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ Phase 5 — Filter                                                │
+│ Drop issues with score < 80 (configurable in command)           │
+│ → STOP if no issues remain (no comment posted)                  │
+└────────────────────────────┬────────────────────────────────────┘
+                             ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ Phase 6 — Re-eligibility (Haiku)                                │
+│ Repeat Phase 1 checks before posting                            │
+└────────────────────────────┬────────────────────────────────────┘
+                             ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ Phase 7 — Output (`gh pr comment`)                              │
+│ Brief markdown; link file:line with full SHA                    │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Phase 3 — five content agents (command file)
+
+| # | Task | Focus |
+|---|------|--------|
+| 1 | CLAUDE.md compliance | Rules in CLAUDE.md; not every writing-time instruction applies at review time |
+| 2 | Bug detector | Shallow scan of **diff only**; large bugs; ignore nitpicks and likely FPs |
+| 3 | History | `git blame` + history on modified code; bugs in light of historical context |
+| 4 | Previous PRs | PRs that touched same files; comments that may apply to current PR |
+| 5 | Code comments | Inline comments in modified files; change must comply with comment guidance |
+
+Agents run **in parallel** after prep. They do **not** score their own issues for final output.
+
+## Phase 4 — confidence rubric (0–100)
+
+Given verbatim to each scorer (summarized):
+
+| Score | Meaning |
+|-------|---------|
+| **0** | False positive; does not survive scrutiny; or pre-existing |
+| **25** | Might be real; cannot verify; stylistic without explicit CLAUDE.md callout |
+| **50** | Real but minor / nitpick / rare in practice |
+| **75** | Verified likely real and important; or explicitly in CLAUDE.md |
+| **100** | Certain; will happen in practice; direct evidence |
+
+**CLAUDE.md issues:** scorer must verify the guideline **explicitly** mentions the issue.
+
+**Default threshold:** 80 — issues below are dropped.
+
+## Documented false positives (Phases 3–4)
+
+Scorers are instructed to down-rank:
+
+- Pre-existing issues not introduced in the PR
+- Things that look like bugs but are not
+- Pedantic nitpicks a senior engineer would skip
+- Linter / typechecker / formatter / import / test failures (CI handles)
+- General quality (tests, docs, generic security) **unless** CLAUDE.md requires it
+- Issues silenced in code (e.g. lint-ignore)
+- Intentional functional changes related to the PR scope
+- Real issues on lines the author did not modify
+
+**Explicit non-goals:** do not build or typecheck; do not use web fetch for GitHub (use `gh`).
+
+## README vs command discrepancies
+
+| Topic | README | Command (`code-review.md`) |
+|-------|--------|----------------------------|
+| Content agent count | 4 (2× compliance + bug + history) | **5** distinct roles |
+| Agent #2 | Second compliance | **Bug detector** |
+| Agents #4–5 | Not listed | Previous PRs + code comments |
+| Scoring | “Nx confidence scorers” | One Haiku per issue, parallel |
+
+**For pi-review alignment, follow the command file.**
+
+## Architecture notes (from README technical section)
+
+- Compliance redundancy in README (“2×”) is **not** what the current command specifies.
+- Scoring is **per issue**, not one aggregating judge.
+- GitHub integration: `gh pr view`, `gh pr diff`, blame/history, post comment.
+
+## Implications for pi-review
+
+| Claude phase | pi-review adaptation (v0.4) |
+|--------------|-------------------------|
+| 1 Eligibility | PR ref / `--diff` / git repo; optional trivial probe for local-git only |
+| 2 Prep | Rule-file paths + lightweight `gh pr view` / hint metadata (no full diff) |
+| 3 Content (5) | Bundled reviewers **obtain the change themselves** (gh/git/read playbook) |
+| 4 Scoring | Gate + optional per-issue scorers on reviewer evidence (no full diff embed) |
+| 5 Filter | Code-side threshold (map 80/100 → 8/10) |
+| 6 Re-eligibility | Target still present before render |
+| 7 Output | TUI markdown + `appendEntry`; no `gh pr comment` yet |
+
+**v0.4 design note:** Claude `/code-review` is an instruction document for the main agent. pi-review keeps parallel spawn + structured_output + gate enforce in the plugin, but must not hard-fail on `gh pr diff` — oversized PRs are handled inside reviewer tool loops.

package/extensions/review/reference/cursor-review-skills.md

@@ -0,0 +1,72 @@
+# Cursor Bugbot & Security Review — reference
+
+> **Source:** Cursor built-in skills `review-bugbot`, `review-security` (subagent invocation patterns).
+
+Last verified: 2026-07-19.
+
+## Product intent (Cursor)
+
+**Single-purpose review skills** — user manually invokes `/review-bugbot` or `/review-security`. Each launches **one** specialized subagent. There is **no** multi-phase pipeline, no gate, no per-issue confidence loop.
+
+Cursor’s general `/review` skill routes to these specialists; they are **not** a full clone of Claude code-review.
+
+## Invocation contract
+
+Both skills use the same prompt shape:
+
+```text
+Full Repository Path: <absolute path>
+Diff: <"branch changes" | "uncommitted changes">
+Base Branch: <optional; only when comparing against a known non-default base>
+Custom Instructions: <optional>
+```
+
+| `Diff` value | Meaning |
+|--------------|---------|
+| `branch changes` (default) | Merge-base vs default branch; includes committed + staged + unstaged |
+| `uncommitted changes` | Working tree only |
+
+Subagent computes diff internally — caller should **not** pre-compute diff.
+
+**PR / branch special case:** checkout target branch before launch; stash only with user confirmation.
+
+## Subagent types
+
+| Skill | `subagent_type` | Purpose |
+|-------|-----------------|---------|
+| `/review-bugbot` | `bugbot` | Correctness / logic bugs in the change |
+| `/review-security` | `security-review` | Security issues in the change |
+
+## Output discipline
+
+After subagent completes, parent summarizes:
+
+- Empty diff → one-line “no diff”
+- No issues → one-line status
+- Issues → markdown table: **Severity | Location (file:line) | Finding**, sorted by severity
+
+**Do not** auto-fix or re-run unless user asks.
+
+## Retry policy
+
+- Wrong invocation shape → fix and retry once
+- Other failures → retry once with same prompt
+- Still failing → stop, report error (no infinite retry)
+
+## What to borrow for pi-review
+
+| Borrow | Do not borrow |
+|--------|----------------|
+| Bug-focused diff scope (no whole-repo nitpicks) | Single-subagent-only UX (we use parallel reviewers) |
+| Security category checklist mindset | Letting subagent compute diff (we resolve diff in parent) |
+| Compact table-friendly findings | Separate `/review-bugbot` commands (use `/review --reviewer`) |
+| “Only changed lines” discipline | Cursor’s Task/subagent harness |
+
+## Mapping to pi-review agents
+
+| Cursor | pi-review agent (planned) | Notes |
+|--------|---------------------------|-------|
+| `bugbot` | `bugbot` (rename from `bug-detector`) | Align prompt with Cursor output discipline |
+| `security-review` | `security-review` (new) | `category: security` in schema already exists |
+
+These are **Phase 3 content reviewers** in our pipeline, not replacements for eligibility, prep, or gate.

package/extensions/review/reference/pi-review-roadmap.md

@@ -0,0 +1,183 @@
+# pi-review — design & version roadmap
+
+> **Positioning:** Pure **skills** extension — user manually runs `/review`. No harness, no auto-fix, no GitHub bot in v1.  
+> **Pattern:** Claude code-review **pipeline shape** + Cursor **bug/security prompt discipline**.  
+> **See also:** [claude-code-review.md](./claude-code-review.md), [cursor-review-skills.md](./cursor-review-skills.md)
+
+Last updated: 2026-07-19.
+
+## Design principles
+
+1. **Pipeline, not a bag of agents** — eligibility → prep → parallel content → score/filter → output.
+2. **High signal** — default threshold aligned with Claude’s 80/100 (our **8/10**).
+3. **Local-first** — `git diff` / diff file; no `gh` required in v1.
+4. **Manual invocation only** — no `registerTool`, no CI hooks in v1.
+5. **Gate = Phase 4+5 compression** — one cheap spawn for dedupe + re-score + verdict; optional per-issue scorers in a later version.
+
+## Phase mapping (Claude → pi-review)
+
+| Claude phase | pi-review module (planned) | v1 behavior |
+|--------------|----------------------------|-------------|
+| **0 Eligibility** | `src/eligibility.ts` | Empty diff, non-git, optional trivial skip |
+| **1 Prep** | `src/prep.ts` | Rule paths (`AGENTS.md`, `CLAUDE.md`, `.pi/`) + diff summary injected into reviewer task |
+| **2 Content (×5)** | `src/review.ts` + `agents/*.md` | Parallel subagents; bundled prompts as `--system-prompt` |
+| **3 Score + filter** | `src/gate.ts` + `prompts/gate.md` | Dedupe, apply Claude rubric (adapted to 1–10), threshold, verdict |
+| **4 Re-check** | `index.ts` | Optional: re-verify diff non-empty before render |
+| **5 Output** | `src/report.ts` | `sendMessage` + `appendEntry("pi-review", …)` |
+
+```text
+/review
+  │
+  ├─ Phase 0  eligibility()          → notify + exit if skip
+  ├─ Phase 1  resolveDiff()            → git-input / path / @file
+  ├─ Phase 1  prepareContext()         → rule paths + summary (sync or 1 cheap spawn)
+  ├─ Phase 2  runReviewers()           → 5 parallel (cap 4 concurrency → 2 waves)
+  ├─ Phase 3  runGate()                → unless --no-gate
+  └─ Phase 4  buildReport + render     → TUI markdown
+```
+
+## Default reviewer roster (v0.2 target)
+
+Aligned to Claude’s five content agents, adapted for local use:
+
+| ID | Claude agent | Status | Tools (default) |
+|----|--------------|--------|-----------------|
+| `claude-md-compliance` | #1 CLAUDE.md | exists | read, grep, find, ls |
+| `bugbot` | #2 Bug detector | rename `bug-detector` | read, grep, find |
+| `history-context` | #3 History | exists | read, bash |
+| `security-review` | *(pi addition)* | **new** | read, grep, find |
+| `code-comments` | #5 Code comments | **new** | read, grep |
+
+**Dropped / deferred**
+
+| ID | Reason |
+|----|--------|
+| `pr-context` (Claude #4) | Requires `gh` + PR metadata — **v1 out of scope** |
+| `conventions` | Overlaps compliance + Claude false-positive list; keep as **optional** `enabled: false` |
+
+**Concurrency:** hard cap 4 → five reviewers run as batch of 4 + batch of 1 (or user passes `--reviewer` subset).
+
+## Confidence scale
+
+| System | Scale | Default keep |
+|--------|-------|--------------|
+| Claude Phase 4 | 0–100 | ≥ 80 |
+| pi-review reviewer + gate | 1–10 | ≥ **8** (change default from 3) |
+
+Gate prompt must embed Claude’s rubric (translated to 1–10) for **re-scoring**, not only filtering reviewer self-reported confidence.
+
+## Known gaps (v0.1.0 codebase)
+
+| Gap | Blocks |
+|-----|--------|
+| Missing `index.ts` | Extension load |
+| `agents/*.md` not used as system prompt | Reviewer quality |
+| `PI_SUBAGENT_STRUCTURED_OUTPUT_*` not handled by stock `pi` | Subagent spawn |
+| No eligibility / prep phases | Claude alignment |
+| Default threshold 3 | Too noisy vs Claude |
+
+## Version plan
+
+### v0.1.0 — current (incomplete)
+
+**Shipped:** core libs, 4 agent templates, gate schema, tests (92).  
+**Not shipped:** `index.ts`, npm publish, end-to-end run.
+
+No further work on 0.1.0 except tagging reality in CHANGELOG if needed.
+
+---
+
+### v0.2.0 — “skills MVP” (target)
+
+**Goal:** User can `pi -e .` or install package and run `/review` on local diff with Claude-shaped pipeline.
+
+| Work item | Priority |
+|-----------|----------|
+| `index.ts` — `/review`, `/review-config`, `/review-agents` | P0 |
+| `src/structured-output-capture.ts` — minimal child extension OR document `-e` flag for structured output | P0 |
+| Wire `agents/<id>.md` + `prompts/gate.md` as system prompts | P0 |
+| `src/eligibility.ts` — empty diff, non-git, trivial diff heuristic | P0 |
+| `src/prep.ts` — rule file paths + diff summary in task preamble | P1 |
+| Rename `bug-detector` → `bugbot`; add `security-review.md`, `code-comments.md` | P1 |
+| Default threshold **8**; gate prompt Claude rubric | P1 |
+| `conventions` default `enabled: false` | P2 |
+| Update README + CHANGELOG | P1 |
+| `reference/` in package `files` | P1 |
+
+**Out of scope v0.2:** `gh`, per-issue scorers, `registerTool`, worktree, retry loop.
+
+**Implementation:** see [v0.2-plan.md](./v0.2-plan.md) for the full task list (54 tasks, 7 tracks).
+
+**Exit criteria**
+
+- [ ] `pi -e /path/to/pi-review` → `/review` on dirty repo produces report
+- [ ] Gate drops low-confidence issues; empty high-confidence → clear message
+- [ ] `bun test` + `bun run check` pass
+- [ ] npm publish `@georgedong32/pi-review@0.2.0`
+
+---
+
+### v0.3.0 — “quality & optional GH”
+
+| Work item | Notes |
+|-----------|-------|
+| Per-issue scorer mode (`--score-per-issue`) | True Claude Phase 4; higher cost |
+| `pr-context` reviewer (optional) | Behind `gh` detection + config flag |
+| Reviewer failure retry (1×) | Only on spawn/timeout errors |
+| `registerMessageRenderer` for collapsible report | TUI polish |
+| Eligibility: “already reviewed” via session `appendEntry` hash | Optional |
+
+---
+
+### v1.0.0 — stable API
+
+- Frozen config schema v1
+- Documented reviewer add/replace contract
+- Published pi gallery entry
+- No breaking changes without `schemaVersion` bump
+
+## File layout (target)
+
+```text
+index.ts                      Extension entry
+src/
+  eligibility.ts              Phase 0
+  prep.ts                     Phase 1
+  git-input.ts                Diff resolution (existing)
+  review.ts                   Phase 2 fan-out (existing)
+  gate.ts                     Phase 3 (existing)
+  report.ts                   Phase 5 output (existing)
+  structured-output-capture.ts  Child pi extension for spawn (new)
+agents/
+  claude-md-compliance.md
+  bugbot.md                     (was bug-detector)
+  history-context.md
+  security-review.md            (new)
+  code-comments.md              (new)
+  conventions.md                (optional, disabled)
+prompts/
+  gate.md
+reference/                      This folder
+```
+
+## Commands (unchanged UX)
+
+```text
+/review [path | @path] [--threshold N] [--reviewer id ...] [--no-gate] [--gate-model id] [--no-spawn]
+/review-config
+/review-agents
+```
+
+## Decision log
+
+| Date | Decision | Rationale |
+|------|----------|-----------|
+| 2026-07-19 | Pure skills, manual `/review` only | User intent; avoid harness scope |
+| 2026-07-19 | Follow Claude **pipeline**, not just parallel agents | User correction; command file is SoT |
+| 2026-07-19 | Keep `history-context` in default roster | Claude agent #3; not merged into bugbot |
+| 2026-07-19 | Add `security-review` (Cursor-inspired) | Orthogonal to bug + compliance |
+| 2026-07-19 | Gate compresses Phase 4+5 for v0.2 | Cost vs fidelity; document in reference |
+| 2026-07-19 | Skip `pr-context` until v0.3+ | Requires `gh`; local-first v1 |
+| 2026-07-19 | Default threshold 8/10 | Maps to Claude 80/100 |
+| 2026-07-26 | CLI collapsed to `--lite` dual-mode; per-issue scorer default off; gate default Haiku | Lighten the CLI surface + align with Claude code-review |
+| 2026-07-26 | Foreground directive mode via `sendUserMessage` (relies on pi-subagents); `--gate-model` restored; spawn path kept as fallback | Review visible in chat; gate model user-configurable |

package/extensions/review/reference/structured-output.md

@@ -0,0 +1,26 @@
+# Structured output capture (child extension)
+
+Child `pi` processes spawned by pi-review load `src/structured-output-capture.ts` via:
+
+```text
+pi --no-session --no-extensions --no-skills -e <path/to/structured-output-capture.ts> ...
+```
+
+## Environment variables
+
+| Variable | Purpose |
+|----------|---------|
+| `PI_SUBAGENT_STRUCTURED_OUTPUT_SCHEMA` | Path to JSON Schema file (written by parent; informs model via system prompt) |
+| `PI_SUBAGENT_STRUCTURED_OUTPUT_CAPTURE` | Path where child must write final JSON payload |
+
+## Tool contract
+
+The capture extension registers a single tool: `structured_output`.
+
+- Parameters: open object (`additionalProperties: true`) — parent validates with TypeBox after spawn.
+- `execute`: writes `JSON.stringify(params)` to capture path; returns `terminate: true`.
+- Parent passes `--tools structured_output` (reviewers also include read/grep/… as configured).
+
+## Parent validation
+
+`src/spawn.ts` reads the capture file and validates against `ReviewerOutputSchema` or `GateOutputSchema`.