@ia-ccun/code-agent-cli 0.0.52-release → 0.0.53

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,6 +1,6 @@
 {
   "name": "@ia-ccun/code-agent-cli",
-  "version": "0.0.52-release",
+  "version": "0.0.53",
   "description": "AI Coding Agent CLI - 基于OpenClaw🦞底层Agent原理封装的编码智能体（供学习使用）。",
   "type": "module",
   "main": "./dist/index.js",
@@ -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.80.0",
+    "@earendil-works/pi-ai": "^0.80.0",
+    "@earendil-works/pi-coding-agent": "^0.80.0",
+    "@earendil-works/pi-tui": "^0.80.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/config/agent/dangerous-patterns.json

@@ -1,106 +0,0 @@
-{
-  "_comment": "危险命令模式配置 - 放置位置: config/agent/dangerous-patterns.json",
-  "_comment2": "安装后会复制到 ~/.aicode-cli/agent/",
-  "_comment3": "commandPrefix: 命令必须以该前缀开头才触发拦截（防止误拦截路径中的字符串）",
-  "patterns": [
-    {
-      "pattern": "rm\\s+-rf",
-      "commandPrefix": "rm",
-      "name": "rm -rf",
-      "risk": "🔴 高危",
-      "description": "递归强制删除文件和目录",
-      "impact": "删除后数据不可恢复",
-      "explanation": "rm -rf 是 Linux/Unix 中最危险的命令之一。-r 表示递归遍历所有子目录，-f 表示强制执行不提示确认。这意味着将无提示地删除指定路径下的所有文件和目录，且无法通过回收站或普通方式恢复。"
-    },
-    {
-      "pattern": "git\\s+reset\\s+--hard",
-      "commandPrefix": "git",
-      "name": "git reset --hard",
-      "risk": "🔴 高危",
-      "description": "强制重置到指定提交",
-      "impact": "丢失未提交的更改",
-      "explanation": "git reset --hard 会将 HEAD 指针移动到指定提交，并丢弃所有未提交的更改。这包括工作区和暂存区的修改，执行后这些更改将永久丢失，无法通过 git 恢复。"
-    },
-    {
-      "pattern": "git\\s+push\\s+(--force|-f)",
-      "commandPrefix": "git",
-      "name": "git push --force",
-      "risk": "🔴 高危",
-      "description": "强制推送到远程",
-      "impact": "覆盖远程历史，可能丢失他人提交",
-      "explanation": "git push --force 会强制用本地分支覆盖远程分支，忽略远程的更新历史。在多人协作项目中，这可能覆盖他人的提交，导致协作者的提交丢失或造成分支冲突。"
-    },
-    {
-      "pattern": "git\\s+push\\s+--delete",
-      "commandPrefix": "git",
-      "name": "git push --delete",
-      "risk": "🔴 高危",
-      "description": "删除远程分支",
-      "impact": "分支删除后不可恢复",
-      "explanation": "git push --delete 会从远程仓库删除指定的分支。分支一旦删除，如果没有本地备份或其他人有该分支的副本，所有提交历史都将永久丢失。"
-    },
-    {
-      "pattern": "git\\s+branch\\s+-D",
-      "commandPrefix": "git",
-      "name": "git branch -D",
-      "risk": "🔴 高危",
-      "description": "强制删除本地分支",
-      "impact": "分支删除后不可恢复",
-      "explanation": "git branch -D 会强制删除本地分支（不检查是否已合并）。所有在该分支上的提交历史都将丢失，除非有其他分支包含这些提交。"
-    },
-    {
-      "pattern": "git\\s+rebase\\s+-i",
-      "commandPrefix": "git",
-      "name": "git rebase -i",
-      "risk": "🔴 高危",
-      "description": "交互式变基",
-      "impact": "改变提交历史，多人协作时易冲突",
-      "explanation": "git rebase -i 允许你交互式地修改、合并、删除或重排提交。这会改变提交的历史哈希值，在已推送的分支上使用会导致后续 push 需要 --force，可能影响协作者。"
-    },
-    {
-      "pattern": "git\\s+clean\\s+-f(d)?",
-      "commandPrefix": "git",
-      "name": "git clean",
-      "risk": "🔴 高危",
-      "description": "删除未跟踪文件",
-      "impact": "删除的文件不可恢复",
-      "explanation": "git clean 会删除工作区中未被 git 跟踪的文件（新建的文件）。这些文件不在版本控制中，删除后无法通过 git 恢复。"
-    },
-    {
-      "pattern": "shutdown|halt|init\\s+0",
-      "commandPrefix": "shutdown",
-      "name": "系统关机",
-      "risk": "🔴 高危",
-      "description": "关闭或停止系统",
-      "impact": "系统将关机或停止服务",
-      "explanation": "这些命令会立即关闭或停止系统。如果在服务器上执行，可能导致正在运行的服务中断，数据丢失或损坏。在 SSH 会话中执行可能导致无法重新连接的严重后果。"
-    },
-    {
-      "pattern": "kill\\s+(-9)?\\s*\\$?(1|init|sshd|systemd)",
-      "commandPrefix": "kill",
-      "name": "杀系统进程",
-      "risk": "🔴 高危",
-      "description": "终止系统关键进程",
-      "impact": "可能导致系统不稳定或崩溃",
-      "explanation": "kill 命令用于终止进程。杀死 PID 1 (init/systemd)、sshd 等系统关键进程可能导致系统服务崩溃、SSH 连接中断或系统完全无法响应。"
-    },
-    {
-      "pattern": "chmod\\s+0[0-7]{3}\\s+\\/",
-      "commandPrefix": "chmod",
-      "name": "修改根目录权限",
-      "risk": "🔴 高危",
-      "description": "修改系统关键路径权限",
-      "impact": "可能导致系统无法正常启动",
-      "explanation": "chmod 修改文件或目录权限。将根目录 / 的权限改为 0xxx 会影响所有系统文件和程序，导致系统服务无法正常运行，甚至无法重启恢复。"
-    },
-    {
-      "pattern": "dd\\s+if=.*of=\\/(dev|sd)",
-      "commandPrefix": "dd",
-      "name": "dd 磁盘操作",
-      "risk": "🔴 高危",
-      "description": "直接写入磁盘设备",
-      "impact": "可能导致数据永久丢失",
-      "explanation": "dd 直接读取和写入磁盘设备，绕过文件系统。如果目标指向 /dev/sda 等磁盘设备，会直接覆盖磁盘数据，导致分区表、文件系统、所有数据永久丢失，无法恢复。"
-    }
-  ]
-}