@ia-ccun/code-agent-cli 0.0.52 → 0.0.53-beta.1

package/config/agent/skills/zread/references/stdio-protocol.md

@@ -0,0 +1,312 @@
+# zread `--stdio` protocol
+
+Every zread command accepts `--stdio`, switching the process from an interactive
+TUI into a JSON-line machine protocol on stdin/stdout. This is the contract used
+by GUI / programmatic clients to drive zread.
+
+## Architecture
+
+zread internally uses a Driver / Client split:
+
+- **Driver** holds all business logic (loading config, calling LLMs, running the
+  doc server, managing drafts). It is framework-agnostic and only talks to a
+  `Transport`.
+- **Client** is either a Bubbletea TUI or `StdioClient`. With `--stdio`, the
+  cobra command instantiates `transport.NewLocalTransport()` (a channel pair),
+  spawns the driver in a goroutine, then runs `StdioClient.Run(ctx)`.
+- `StdioClient` reads JSON lines from `os.Stdin` and forwards them as commands
+  to the driver, while encoding `Event`s from the driver to `os.Stdout` (one
+  JSON object per line). It returns when an event with `"done": true` is
+  received.
+
+Result: stdin = command stream, stdout = event stream, both newline-delimited
+JSON. stderr is reserved for logs/errors and should not be parsed.
+
+## Event format (driver → client, stdout)
+
+```json
+{
+  "vm": { ... },
+  "waiting_for": ["..."],
+  "done": false,
+  "error": ""
+}
+```
+
+- `vm`: full ViewModel snapshot for the current state (shape varies per command — see below).
+- `waiting_for`: command `type` values the client may legally send right now. `quit` is always accepted regardless.
+- `done`: `true` on the final event; the process will exit on its own.
+- `error`: non-empty when the previous command was rejected; `vm`/`waiting_for` remain unchanged.
+
+Rules:
+- An event is emitted after every state transition. Treat `vm` as the full current state (no diffs).
+- `waiting_for: []` with `done: false` means the driver is awaiting an internal async result — do not send any command; just keep reading.
+- The very last event always has `done: true` and an empty `waiting_for`.
+
+## Command format (client → driver, stdin)
+
+One JSON object per line:
+
+```json
+{"type": "<command_type>", "params": { ... }}
+```
+
+- `type` is required. `params` may be omitted (treated as `{}`).
+- Universal command: `{"type":"quit","params":{}}` — every driver handles it and shuts down cleanly.
+- Command types prefixed with `_` are driver-internal. They never appear in `waiting_for`; clients must not send them.
+- Sending a command not in `waiting_for` returns an event with `error` set while `vm`/`waiting_for` remain unchanged.
+- Error message format: `"command \"xxx\" not allowed in state yyy"` / `"invalid params: ..."` / `"invalid JSON: ..."`.
+
+## Driving a session
+
+1. Spawn `zread <command> --stdio` with piped stdin/stdout.
+2. Read the first event — it carries the initial ViewModel and `waiting_for`.
+3. Render or inspect `vm`; pick a legal command from `waiting_for` and write it as a single JSON line followed by `\n`.
+4. Loop: read next event, react, write next command.
+5. Stop when `done: true` arrives. The process will exit on its own. Sending `quit` at any time triggers the same shutdown.
+
+---
+
+## `zread browse --stdio`
+
+### ViewModel fields
+
+| Field | Type | Notes |
+|---|---|---|
+| `state` | string | `"loading"` `"serving"` `"select_version"` `"no_wiki"` `"error"` |
+| `url` | string | Local server URL; present when `state="serving"` |
+| `browser_opened` | bool | Whether the browser was auto-launched |
+| `has_current` | bool | Whether a "current" wiki version exists |
+| `versions` | array | Present when `state="select_version"` |
+| `versions[].id` | string | Wiki version ID |
+| `versions[].timestamp` | string | Version timestamp |
+| `versions[].is_current` | bool | Whether this is the current version |
+| `error` | string | Present when `state="error"` |
+
+### Commands
+
+| State | `waiting_for` | Command | Params |
+|---|---|---|---|
+| `select_version` | `["select_version","quit"]` | `select_version` | `{"wiki_id":"<id>"}` or `{"current":true}` |
+| `serving` | `["quit"]` | — | — |
+| `no_wiki` | `["quit"]` | — | — |
+| `loading` | `[]` | *(wait for internal event)* | — |
+| `error` | `[]` | — | — |
+
+### State machine
+
+```
+loading ──(server ok)──────────────────► serving
+loading ──(error)──────────────────────► error (terminal)
+select_version ──(select_version cmd)──► loading ──► serving
+no_wiki ───────────────────────────────► (terminal, done=true)
+```
+
+---
+
+## `zread generate --stdio`
+
+### ViewModel fields
+
+| Field | Type | Notes |
+|---|---|---|
+| `state` | string | `"select_action"` `"running"` `"done"` `"error"` |
+| `max_retries` | int | Configured max retries per page |
+| `select_action.scenario` | string | `"has_wiki"` `"has_draft"` `"empty"` |
+| `select_action.wiki_date` | string | Date of existing wiki (when `scenario="has_wiki"`) |
+| `select_action.draft_done` | int | Pages already done in draft |
+| `select_action.draft_total` | int | Total pages in draft |
+| `select_action.next_action` | string | Pre-suggested action: `"generate"` `"browse"` `""` |
+| `catalog.status` | string | `"idle"` `"running"` `"done"` `"resumed"` `"error"` |
+| `catalog.tool_name` | string | Currently-running LLM tool (if any) |
+| `catalog.error` | string | Catalog error message |
+| `catalog.auto_retry` | int | Auto-retry count so far |
+| `pages.tasks` | array | Per-page task list |
+| `pages.tasks[].id` | int | Task ID (used for `retry` command) |
+| `pages.tasks[].title` | string | Page title |
+| `pages.tasks[].slug` | string | Page slug |
+| `pages.tasks[].state` | string | `"pending"` `"running"` `"retry_pending"` `"done"` `"failed"` `"resumed"` |
+| `pages.tasks[].retry_count` | int | Retries attempted so far |
+| `pages.tasks[].max_retries` | int | Retry limit for this task |
+| `pages.tasks[].error` | string | Error message if failed |
+| `pages.done` | int | Completed page count |
+| `pages.total` | int | Total page count |
+| `pages.waiting_retry` | bool | `true` when driver is paused waiting for retry/skip decision |
+| `done_total` | int | Total pages done (in `state="done"`) |
+| `error` | string | Fatal error message |
+
+### Commands
+
+| State / condition | `waiting_for` | Command | Params |
+|---|---|---|---|
+| `select_action` | `["select_action","cancel","quit"]` | `select_action` | `{"action":"generate"}` or `"browse"` or `"resume"` or `"clear"` or `"cancel"` |
+| `running` (normal) | `["quit"]` | — | — |
+| `running` (catalog error) | `["quit","retry_catalog"]` | `retry_catalog` | `{}` |
+| `running` (pages waiting retry) | `["quit","retry","skip_all"]` | `retry` | `{"task_id":<int>}` |
+| `running` (pages waiting retry) | `["quit","retry","skip_all"]` | `skip_all` | `{}` |
+| `running` | `["quit","cancel"]` | `cancel` | `{}` |
+
+### CLI flags that affect stdio flow
+
+- `--yes` / `-y`: skips the `select_action` gate; generation starts immediately.
+- `--draft-action <resume|clear|cancel>`: pre-answers the draft prompt.
+- `--skip-failed`: equivalent to auto-sending `skip_all` when pages fail.
+
+### State machine
+
+```
+select_action ──(generate/resume)──► running ──(all done, no failures)──► done
+select_action ──(cancel/browse)────► done (immediate)
+running ──(pages failed)───────────► waiting_retry=true, accepts retry/skip_all
+running ──(cancel)─────────────────► done
+```
+
+---
+
+## `zread config --stdio`
+
+### ViewModel fields
+
+| Field | Type | Notes |
+|---|---|---|
+| `fields` | array (9 items) | Ordered config fields |
+| `fields[].title_key` | string | Display label key |
+| `fields[].json_key` | string | Key to use in `update_fields`; empty = read-only |
+| `fields[].initial` | string | Value at load time |
+| `fields[].value` | string | Current (possibly edited) value |
+| `dirty` | bool | `true` if any field differs from `initial` |
+| `saved` | bool | `true` after successful save |
+| `error` | string | Validation error |
+
+Field index → `json_key` mapping:
+
+| Index | `json_key` | Notes |
+|---|---|---|
+| 0 | `language` | generation language |
+| 1 | `doc_language` | doc language |
+| 2 | *(empty)* | read-only LLM provider display |
+| 3 | `max_concurrent` | int |
+| 4 | `max_retries` | int |
+| 5 | `llm_provider` | editable in stdio mode |
+| 6 | `llm_base_url` | editable in stdio mode |
+| 7 | `llm_model` | editable in stdio mode |
+| 8 | `llm_api_key` | editable in stdio mode |
+
+### Commands
+
+No state machine. Fixed `waiting_for`: `["update_fields","save","reload_llm","quit"]`.
+
+| Command | Params | Effect |
+|---|---|---|
+| `update_fields` | `{"fields":{"<json_key>": "<value>", ...}}` | Partial update; only listed keys change |
+| `save` | `{}` | Persists config and terminates (`done=true`) |
+| `reload_llm` | `{}` | Re-validates LLM provider settings |
+| `quit` | `{}` | Exits without saving |
+
+---
+
+## `zread login --stdio`
+
+### ViewModel fields
+
+| Field | Type | Notes |
+|---|---|---|
+| `state` | string | See states below |
+| `authorize_url` | string | OAuth URL to open; present in `open_browser` state |
+| `auth_timeout` | int | Nanoseconds until auth expires; present in `waiting` state |
+| `browser_warn` | string | Warning if browser launch failed |
+| `username` | string | Logged-in username; present in `done` state |
+| `avail_models` | array of string | Models to choose from; present in `select_model` state |
+| `selected_model` | string | Currently selected model |
+| `error` | string | Error message in `error` state |
+| `wants_llm_provider_editor` | bool | `true` (with `done=true`) when `--custom` flag was used |
+
+States: `"select_region"` → `"init_flow"` → `"open_browser"` → `"waiting"` → `"select_model"` → `"saving"` → `"done"` / `"error"`
+
+### Commands
+
+| State | `waiting_for` | Command | Params |
+|---|---|---|---|
+| `select_region` | `["select_region","quit"]` | `select_region` | `{"region":"<provider_key>"}` or `{"region":"__use_own_key__"}` |
+| `select_model` | `["select_model","quit"]` | `select_model` | `{"model":"<model_id>"}` |
+| all others | `[]` | *(wait for internal auth events)* | — |
+
+### Special cases
+
+- `--custom` flag: driver immediately emits `done: true` with `wants_llm_provider_editor: true`. Client should then launch `zread config --stdio` to configure a custom LLM provider.
+
+### State machine
+
+```
+select_region ──(cmd)──► init_flow ──► open_browser ──► waiting ──► select_model
+select_model ──(cmd)───► saving ──► done
+any ────────────────────────────────────────────────────────────────► error
+```
+
+---
+
+## `zread update --stdio`
+
+### ViewModel fields
+
+| Field | Type | Notes |
+|---|---|---|
+| `state` | string | See states below |
+| `current_version` | string | Installed version |
+| `latest_version` | string | Available version; present in `has_update`+ |
+| `download_url` | string | Asset URL for the update binary |
+| `package_manager` | string | e.g. `"brew"`; present in `package_manager` state |
+| `downloaded_bytes` | int | Bytes downloaded so far |
+| `total_bytes` | int | Total download size |
+| `download_percent` | float | 0–100 |
+| `error` | string | Error message in `error` state |
+
+States: `"checking"` → `"up_to_date"` / `"package_manager"` / `"has_update"` → `"downloading"` → `"confirm_restart"` / `"error"`
+
+Terminal states (emit `done=true`): `up_to_date`, `package_manager`, `error`, and after restart/skip.
+
+### Commands
+
+| State | `waiting_for` | Command | Params |
+|---|---|---|---|
+| `has_update` | `["download","quit"]` | `download` | `{}` |
+| `confirm_restart` | `["restart","skip_restart","quit"]` | `restart` | `{}` |
+| `confirm_restart` | `["restart","skip_restart","quit"]` | `skip_restart` | `{}` |
+| all others | `[]` | *(wait for internal events)* | — |
+
+### State machine
+
+```
+checking ──► up_to_date (terminal)
+         ──► package_manager (terminal)
+         ──► has_update ──(download)──► downloading ──► confirm_restart
+                                                     ──(restart/skip)──► done
+checking / downloading ──(error)──► error (terminal)
+```
+
+---
+
+## `zread version --stdio`
+
+Emits a single event with `done: true` immediately. No commands are accepted.
+
+### ViewModel fields
+
+| Field | Type | Notes |
+|---|---|---|
+| `version` | string | e.g. `"1.2.3"` |
+| `channel` | string | Release channel (if set) |
+| `go_version` | string | Go runtime version |
+| `os` | string | OS name |
+| `arch` | string | CPU architecture |
+
+---
+
+## Practical tips
+
+- Always flush stdin after writing a command (the driver reads line-by-line).
+- Treat any line on stdout that fails to parse as JSON as a bug — log it but do not crash; zread should not print non-JSON to stdout in `--stdio` mode.
+- When `waiting_for` is `[]` and `done` is `false`, keep reading — the driver is awaiting an internal async result and will emit the next event on its own.
+- For long-running commands (`generate`), keep reading events continuously; there is no heartbeat, but progress events arrive whenever state changes.
+- To cancel cleanly, send `{"type":"quit","params":{}}` and then drain events until `done` rather than killing the process.
+- `done: true` events are always terminal. Do not send further commands.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ia-ccun/code-agent-cli",
-  "version": "0.0.52",
-  "description": "AI Coding Agent CLI - 基于OpenClaw🦞底层Agent（pi）原理封装的编码智能体（供学习使用）。",
+  "version": "0.0.53-beta.1",
+  "description": "AI Coding Agent CLI - 基于OpenClaw🦞底层Agent原理封装的编码智能体（供学习使用）。",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -35,10 +35,10 @@
     "prepare": "husky"
   },
   "dependencies": {
-    "@earendil-works/pi-agent-core": "^0.74.0",
-    "@earendil-works/pi-ai": "^0.74.0",
-    "@earendil-works/pi-coding-agent": "^0.74.0",
-    "@earendil-works/pi-tui": "^0.74.0"
+    "@earendil-works/pi-agent-core": "^0.85.0",
+    "@earendil-works/pi-ai": "^0.85.0",
+    "@earendil-works/pi-coding-agent": "^0.85.0",
+    "@earendil-works/pi-tui": "^0.85.0"
   },
   "overrides": {
     "glob": "^11.0.0",
@@ -60,6 +60,7 @@
     "@typescript-eslint/parser": "^8.57.0",
     "eslint": "^10.0.3",
     "husky": "^9.1.7",
+    "pi-lean-ctx": "^3.8.11",
     "playwright": "^1.60.0",
     "shx": "^0.4.0",
     "typescript": "^5.7.2",

package/scripts/postinstall.js

@@ -6,6 +6,7 @@ import { symlink as fsSymlink } from 'fs/promises';
 import { join, dirname, relative } from 'path';
 import { homedir } from 'os';
 import { fileURLToPath } from 'url';
+import { spawn } from 'child_process';
 
 // Get __dirname equivalent for ES modules
 const __filename = fileURLToPath(import.meta.url);
@@ -240,7 +241,6 @@ const FORCE_OVERWRITE_LIST = [
   'APPEND_SYSTEM.md',
   'SYSTEM.md',
   'dangerous-patterns.json',
-  'settings.json',
   'help.md',
   'extensions/*.ts',
   'prompts/*.md',
@@ -463,6 +463,63 @@ logSecurity('install_complete', {
   piDir,
 });
 
+// ============================================================================
+// Auto-install codegraph (optional dependency)
+// ============================================================================
+
+const CODEGRAPH_PKG = '@colbymchenry/codegraph@0.9.7';
+
+async function installCodegraph() {
+  return new Promise((resolve) => {
+    const child = spawn('npm', ['i', '-g', CODEGRAPH_PKG], {
+      stdio: 'pipe',
+      shell: process.platform === 'win32',
+    });
+    
+    let stderr = '';
+    
+    child.stderr.on('data', (data) => {
+      stderr += data.toString();
+    });
+    
+    child.on('close', (code) => {
+      if (code === 0) {
+        console.log('✓ Installed codegraph globally,See UniDoc《2026.5 aicode+codegraph 安装与使用》');
+        logSecurity('codegraph_install', { 
+          package: CODEGRAPH_PKG, 
+          success: true 
+        });
+      } else {
+        // 静默失败，不中断主流程
+        if (process.env.DEBUG) {
+          console.log(`⚠ Could not install codegraph: ${stderr.slice(0, 100)}`);
+        }
+        logSecurity('codegraph_install', { 
+          package: CODEGRAPH_PKG, 
+          success: false, 
+          error: stderr.slice(0, 200) 
+        }, 'warn');
+      }
+      resolve();
+    });
+    
+    child.on('error', (err) => {
+      if (process.env.DEBUG) {
+        console.log(`⚠ Could not install codegraph: ${err.message}`);
+      }
+      logSecurity('codegraph_install', { 
+        package: CODEGRAPH_PKG, 
+        success: false, 
+        error: err.message 
+      }, 'warn');
+      resolve();
+    });
+  });
+}
+
+// Execute codegraph installation
+await installCodegraph();
+
 console.log('\n✨ Setup complete!');
 console.log('📝 Configuration files are in ~/.aicode-cli/');
 console.log('🔗 ~/.pi is linked to ~/.aicode-cli (ensuring model configs work)');

package/scripts/regression/README.md

@@ -0,0 +1,224 @@
+# aicode-cli 回归测试套件
+
+> 用于验证每次升级 pi 底层依赖后，aicode-cli 的功能完整性不受影响。
+> 也可用于新 aicode 版本发布前的本地预检。
+
+## 设计目标
+
+| 维度 | 验证内容 |
+|---|---|
+| **版本对齐** | aicode 二进制版本 + 4 个 pi 依赖包主版本一致 |
+| **aicode 特色功能** | 20 个自定义 TS 扩展全部加载，无冲突 / 无语法错误 |
+| **RPC 协议兼容** ⭐ | AicodeRpcClient.kt 实际用到的 17 个 RPC 命令 + 7 个事件类型 + 字段 schema |
+| **预置资产** | 5 个 Prompt + 21+ 个 Skill 全部通过 `get_commands` 注册 |
+| **核心能力** | prompt → message_update 完整事件流、tool_execution 配对 |
+| **pi 0.85 新功能** | `clear_queue` RPC、GPT-6 Astra、thinking 持久化、`usage.cacheWrite1h` |
+
+> ⭐ **RPC 协议兼容** 是本套件的核心重点 — 任何 RPC 命令的字段格式变化都会在 case 03 失败。
+
+## 快速开始
+
+### 前置依赖
+
+```bash
+brew install jq
+```
+
+### 运行全部测试
+
+```bash
+# 默认（使用 PATH 中的 aicode，配置目录 ~/.aicode-cli）
+./run-all.sh
+
+# 指定 aicode 二进制（测试本地包）
+AICODE_BIN=$(pwd)/bin/cli.js ./run-all.sh
+```
+
+### 只跑部分 case
+
+```bash
+# 只跑 RPC 兼容性（升级后必跑）
+./run-all.sh --only 03
+
+# 跑 RPC + 新功能验证（最小升级预检）
+./run-all.sh --only 03,07
+
+# 跑核心 4 个
+./run-all.sh --only 01,02,03,07
+```
+
+### 单个 case 直接跑
+
+```bash
+./cases/01-version-and-deps.sh
+./cases/02-extension-loading.sh
+./cases/03-rpc-protocol.sh
+./cases/04-prompt-stream.sh
+./cases/05-slash-commands-and-skills.sh
+./cases/06-tool-execution.sh
+./cases/07-pi-new-features.sh
+```
+
+## Case 清单
+
+| Case | 文件 | 主题 | 关键断言 |
+|---|---|---|---|
+| **01** | `01-version-and-deps.sh` | 版本与依赖 | `aicode -v` 格式合规 + 4 个 pi 包主版本匹配 |
+| **02** | `02-extension-loading.sh` | aicode 扩展加载 | 启动无 `Failed to load`/`conflict`/`SyntaxError`；aicode-* 命令注册 |
+| **03** ⭐ | `03-rpc-protocol.sh` | **RPC 协议兼容性矩阵** | 17 个 RPC 命令 + 7 个事件类型 + 字段 schema + stopReason 枚举值 |
+| **04** | `04-prompt-stream.sh` | prompt 事件流 | `agent_start`/`turn_start`/`message_update`(thinking_delta/text_delta)/`turn_end`/`agent_end` 序列 |
+| **05** | `05-slash-commands-and-skills.sh` | Prompts + Skills | `/git-commit` `/workflow` 等 5 个 prompt + `/skill:code-review` 等核心 skill |
+| **06** | `06-tool-execution.sh` | 工具调用 | `tool_execution_start` 必带 `toolCallId`+`toolName`（0.84.3 修复点） |
+| **07** | `07-pi-new-features.sh` | pi 0.85 新功能 | `clear_queue` RPC、GPT-6、thinking 持久化、`cacheWrite1h` |
+
+## RPC 协议覆盖矩阵（case 03）
+
+### RPC 命令（17 个）
+
+| 命令 | 来源 | 用途 |
+|---|---|---|
+| `prompt` / `steer` / `follow_up` / `abort` | AicodeRpcClient.streamPrompt/Steer/FollowUp/abort | 消息流 |
+| `compact` | AicodeRpcClient.compact | 上下文压缩 |
+| `extension_ui_response` | AicodeRpcClient.respondExtensionUi | 扩展 UI 回调 |
+| `get_state` / `get_session_stats` / `get_commands` | fetchState/fetchSessionStats/getCommands | 状态查询 |
+| `get_available_models` / `get_available_thinking_levels` | AicodeRpcClient | 模型/thinking 选择 |
+| `get_messages` / `get_entries` / `get_tree` | AicodeRpcClient | 会话历史 |
+| `set_thinking_level` / `cycle_thinking_level` / `set_model_provider` | AicodeRpcClient | 模型控制 |
+| `set_tools` | AicodeRpcClient.setTools | 工具开关 |
+| `new_session` / `clear_queue` | AicodeRpcClient.newSession/clearQueue | 会话管理 + 队列 |
+
+### 事件类型（11 个）
+
+| 事件 | AicodeStreamItem 映射 |
+|---|---|
+| `agent_start` / `turn_start` | lifecycle |
+| `message_start` / `message_end` | lifecycle |
+| `message_update` | Text / Thinking |
+| `turn_end` / `agent_end` | TurnEnd / lifecycle |
+| `tool_execution_start` / `_update` / `_end` | ToolStart / ToolUpdate / ToolEnd |
+| `queue_update` | QueueUpdate |
+| `auto_retry_end` | Error |
+
+### 字段 schema（关键）
+
+- `message_start.message.role` ∈ {user, assistant, toolResult}
+- `message_update.assistantMessageEvent.{type, delta, contentIndex}`
+- `turn_end.message.usage.{input, output, cost, ...}`
+- `tool_execution_start.{toolCallId, toolName, args}` （0.84.3 修复点）
+- `tool_execution_end.{isError: "true"|"false"}`
+- `message_end.message.stopReason` ∈ {end_turn, tool_use, error, max_tokens, aborted}
+- `agent_end.willRetry` ∈ {"true", "false"}
+
+## 升级后必跑
+
+```bash
+# 1. 改完 package.json，npm install
+# 2. 编译
+npm run build
+
+# 3. RPC 兼容性是首要重点
+./scripts/regression/run-all.sh --only 03
+
+# 4. 全量回归
+./scripts/regression/run-all.sh
+
+# 5. 看 results/*.log
+ls scripts/regression/results/
+```
+
+## 验收标准
+
+升级可发布的最低条件：
+
+| Case | 最低要求 |
+|---|---|
+| 01 version-and-deps | 全部 pass |
+| 02 extension-loading | fail_count = 0 |
+| **03 rpc-protocol** | **全部 pass 或 skip（已知不支持）** |
+| 04 prompt-stream | 全部 pass |
+| 05 slash-commands-and-skills | 注册率 ≥ 80% |
+| 06 tool-execution | 至少 1 个 tool 事件配对成功 |
+| 07 pi-new-features | skip 都标 "pi < 0.85.0 不支持" |
+
+## 输出位置
+
+| 文件 | 内容 |
+|---|---|
+| `results/<case-name>.log` | 每个 case 的 stdout（pass/fail 行 + RPC 事件 log） |
+| `results/.last_pid` | 最近一次 spawn 的 RPC 进程 PID（调试用） |
+
+## 隔离机制
+
+每个 case 独立 spawn 一个 `aicode --mode rpc --no-session` 子进程，使用临时目录（`mktemp -d`）作为 configDir，**不污染**用户 `~/.aicode-cli/`。结束后自动清理。
+
+但 `02-extension-loading.sh` 需要真实加载扩展（不能用 `-ne`），所以它会用临时目录作为 configDir 跑全量加载，验证 20 个扩展都能正常启动。
+
+## 依赖扩展的 case
+
+- **02、05** 都需要正常启动扩展 → 不传 `-ne`
+- **03、04、06、07** 主要测 RPC 协议 → 用 `-ne` 跳过扩展避免冲突
+
+## 调试
+
+### 单独看 RPC 事件流
+
+```bash
+# 看 03 的 RPC 命令响应
+jq -c 'select(.type=="response")' scripts/regression/results/03-rpc-protocol.log | head -20
+
+# 看 message_update delta 流
+grep message_update scripts/regression/results/04-prompt-stream.log | \
+    jq -c '{event: .assistantMessageEvent.type, delta: .assistantMessageEvent.delta}'
+```
+
+### 验证 RPC schema 漂移
+
+```bash
+# 列出所有 turn_end 的 usage keys
+jq -c 'select(.type=="turn_end") | .message.usage | keys | sort' \
+    scripts/regression/results/03-rpc-protocol.log | sort -u
+
+# 对比不同 pi 版本
+diff <(jq -c '...' results-v0.80.log) <(jq -c '...' results-v0.85.log)
+```
+
+## 与 aicode-plugin-swing 的关系
+
+| 层 | 测试位置 |
+|---|---|
+| aicode CLI 功能（命令/扩展/skills） | 本套件（scripts/regression/） |
+| RPC 协议兼容性 | 本套件 case 03 ⭐ |
+| Kotlin 客户端逻辑 | `~/icode/aicode-idea-plugin-swing/src/test/kotlin/com/nu/aicode/rpc/` |
+| 升级兼容性评估 | `~/icode/aicode-idea-plugin-swing/docs/spec/upgrade-code-agent-cli-to-pi-085.md` |
+| 端到端 IDE 集成 | aicode-plugin-swing 实际 IDE 测试 |
+
+**本套件（CLI 侧）+ Kotlin 单元测试 + 实际 IDE 集成 = 完整回归链路。**
+
+## 添加新 case
+
+1. 复制 `cases/06-tool-execution.sh` → `cases/08-my-feature.sh`
+2. 修改 `CURRENT_CASE`
+3. 调用 `source "$SCRIPT_DIR/../lib/common.sh"`
+4. 用 `pass` / `fail` / `skip` 报告结果
+5. 最后 `summary; exit $?`
+
+## 添加新的 RPC 命令到 case 03
+
+编辑 `03-rpc-protocol.sh` 的 `RPC_COMMANDS` 数组：
+
+```bash
+RPC_COMMANDS=(
+    ...
+    "my_new_command|{\"foo\":\"bar\"}"
+)
+```
+
+格式：`type|payload`，payload 会拼到 `{...,"id":"rpcN"}` 中。
+
+## 修订记录
+
+| 日期 | 修订 |
+|---|---|
+| 2026-09-12 | 初版：6 个 case |
+| 2026-09-12 v2 | 新增 case 03 RPC 协议兼容性矩阵（17 命令 + 11 事件 + schema）|
+| 2026-09-12 v2 | 重新编号：03 RPC / 04 prompt / 05 slash / 06 tool / 07 pi-new |