jinzd-ai-cli 0.4.273 → 0.4.276

package/README.md

@@ -1,610 +1,610 @@
-**English** | [中文](README.zh-CN.md)
-
-# ai-cli
-
-<!-- AICLI:DOCS_DEFAULT_WEB_PORT=3000 -->
-<!-- AICLI:DOCS_BUILTIN_TOOL_COUNT=30 -->
-<!-- AICLI:DOCS_REPL_COMMAND_COUNT=48 -->
-<!-- AICLI:DOCS_BUILTIN_PROVIDER_COUNT=10 -->
-<!-- AICLI:DOCS_MEMORY_SOURCE=memory.jsonl -->
-
-> A cross-platform AI coding assistant — CLI, Web UI, and Desktop App — with multi-provider support and agentic tool calling
-
-[![npm version](https://img.shields.io/npm/v/jinzd-ai-cli)](https://www.npmjs.com/package/jinzd-ai-cli)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D20.18.1-brightgreen)](https://nodejs.org)
-[![GitHub Release](https://img.shields.io/github/v/release/jinzhengdong/ai-cli)](https://github.com/jinzhengdong/ai-cli/releases)
-[![CI](https://github.com/jinzhengdong/ai-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/jinzhengdong/ai-cli/actions/workflows/ci.yml)
-
-**ai-cli** is a powerful AI assistant that connects to 10 providers (including local Ollama models) and executes tasks autonomously through agentic tool calling. Use it as a terminal REPL, a browser-based Web UI, or a standalone Electron desktop app.
-
-<p align="center">
-  <img src="https://img.shields.io/badge/CLI-Terminal-blue" alt="CLI" />
-  <img src="https://img.shields.io/badge/Web_UI-Browser-green" alt="Web UI" />
-  <img src="https://img.shields.io/badge/Desktop-Electron-purple" alt="Desktop" />
-</p>
-
-## Highlights
-
-- **10 Built-in Providers** — Claude, Gemini, DeepSeek, OpenAI, Zhipu GLM, Kimi, Qwen, **MiniMax (海螺)**, OpenRouter (300+ models), **Ollama** (local models, no API key needed)
-- **3 Interfaces** — Terminal CLI, browser Web UI (`aicli web`), Electron desktop app
-- **Agentic Tool Calling** — AI autonomously runs shell commands, reads/writes files, searches code, fetches web, runs tests (default 200 rounds, configurable up to 10000 via `config.maxToolRounds` or `--max-tool-rounds`)
-- **Prompt Caching** *(v0.4.70+)* — System prompt split into stable/volatile halves so Claude caches the stable part with `cache_control: ephemeral`; cached tokens bill at ~10% of the input price
-- **Unified-Diff Patch Edits** *(v0.4.72+)* — `edit_file` accepts standard `@@ -a,b +c,d @@` hunks for the most compact way to apply many scattered small changes to a large file (±200-line drift tolerance + whitespace fallback)
-- **Anthropic Batches API** *(v0.4.73+)* — `aicli batch submit/list/status/results/cancel` for 50%-off, 24-hour async processing — ideal for offline analysis and bulk evals
-- **Web UI Session Replay** *(v0.4.71+)* — 🎬 button on every saved session opens a timeline replay: every message, tool call, reasoning, and cache-aware token usage at a glance
-- **Conversation Branching** *(v0.4.74+)* — `/branch list/new/switch/delete/rename` inside the REPL, plus a 🌿 "fork here" button on every replay step — explore alternate directions without losing the original thread
-- **Symbol Index** *(v0.4.76+, multi-language since v0.4.143)* — persistent tree-sitter index for TypeScript / JavaScript / TSX / Python / Go / Rust / Java / C/C++ powers three new AI tools: `find_symbol`, `get_outline`, `find_references`. Orders of magnitude faster than grep for definition lookups; background refresh on REPL startup, `/index status|rebuild|clear` to manage
-- **Semantic Code Search** *(v0.4.77+)* — `search_code` tool finds code by meaning, not name. Local sentence embeddings (multilingual MiniLM, 117 MB one-time download) score symbols by cosine similarity against natural-language queries in English or Chinese ("where are users authenticated", "哪里做了速率限制"). No API key, runs on CPU. Manage with `/index semantic-rebuild|semantic-clear`
-- **MCP Server Mode** *(v0.4.84+)* — `aicli mcp-serve` reverses ai-cli into an MCP server (JSON-RPC 2.0 over stdio), exposing its 30 built-in tools (incl. `find_symbol` / `search_code` / `run_tests`) to Claude Desktop / Cursor / any MCP client. Opt-in destructive-tool allow, `--tools` whitelist, `--cwd` override
-- **Session Sensitive-Data Redaction** *(v0.4.88+)* — unified redactor scrubs `password=` / `api_key` / bearer tokens / OpenAI-style keys from every message **before it hits disk**. Query text is redacted too, so secrets never reach embeddings or logs. `/security status` + `/security scan` to audit
-- **Human-like Long-Term Memory** *(v0.4.89+, B4)* — semantic index over every past chat session + `recall_memory` AI tool + `/memory rebuild|refresh|status|recall` commands. AI is prompted to auto-recall when it sees "last time" / "之前" / ambiguous references. Reuses the same MiniLM embedder as semantic code search
-- **Governed Persistent Memory** *(v0.4.217+)* — `save_memory` and `/memory add` write auditable `memory.jsonl` entries with id/scope/source/sensitivity/approval/expiry; AI-written entries (`save_memory`) always stay pending until `/memory approve <id>` (v0.4.242+), low-risk manual entries auto-approve, project-scoped memories only inject inside the same project, and `/memory clear` confirms + keeps a timestamped backup
-- **Package Plugin Ecosystem** *(v0.4.218+)* — install shareable .aicli-plugin/plugin.json packages with skills, hooks, commands, MCP servers, agents, and permission hints; only trusted+enabled plugins load, hooks still require hook trust, and MCP/tools remain under permission profiles/network policy
-- **Web UI Memory Panel** *(v0.4.90+, B4)* — new 🧠 Memory sidebar tab with semantic search across past chats; each hit has **➕ Inject** (quotes the snippet into the chat input as a markdown blockquote so you can review/edit before sending — no silent context injection) and **↗ Load** (jumps to source session). Bulk "Inject top 3" for recall bundles
-- **Streaming Tool Use** — Real-time streaming of AI reasoning and tool calls as they happen
-- **Sub-Agents** — Delegate complex subtasks to isolated child agents with independent tool loops
-- **Extended Thinking** — Claude deep reasoning mode with `/think` toggle
-- **Plan Mode** — Read-only planning phase (`/plan`) where AI analyzes before executing, with loop detection
-- **Auto-Pause** — Automatically pauses every 10 rounds for user review and redirection
-- **MCP Protocol** — Connect external MCP servers for dynamic tool discovery
-- **Multi-User Auth** — Web UI supports multiple users with password authentication
-- **PWA Support** — Install Web UI as a desktop/mobile app, accessible over LAN
-- **Hierarchical Context** — 3-layer context files (global / project / subdirectory) auto-injected; supports native AICLI.md, Claude-compatible CLAUDE.md, and Codex-compatible AGENTS.md with override files
-- **Headless Mode** — `ai-cli -p "prompt"` for CI/CD pipelines and scripting
-- **48 REPL Commands** — Session management, checkpointing, code review, security review/scan, rewind, scaffolding, cross-session history search, chat-memory recall, smart model routing (`/route`), and more
-- **GitHub Actions CI/CD** — Automated testing on Node 20/22 + npm publish on release tags
-- **PR Review CLI** *(v0.4.216+)* — `aicli pr review|security-review|summarize` reviews `main...HEAD`, custom `--base/--head`, or GitHub PR URLs; optional `--agents security,bugs,tests,maintainability`; never posts comments unless `--post` is explicit
-- **CI Review Artifacts** *(v0.4.216+)* — `aicli ci` emits Markdown, JSON, or SARIF and gates on security-high, test-failure, and lint-failure findings in read-only review mode
-- **Cross-Platform** — Windows, macOS, Linux
-
-## Installation
-
-### npm (recommended)
-
-```bash
-npm install -g jinzd-ai-cli
-```
-
-Requires Node.js >= 20.18.1. After installation, use `aicli` to start.
-
-### Electron Desktop App (Windows)
-
-Download the installer from [GitHub Releases](https://github.com/jinzhengdong/ai-cli/releases) — no Node.js required:
-
-| Platform | Download |
-|----------|----------|
-| Windows x64 | [`ai-cli-setup.exe`](https://github.com/jinzhengdong/ai-cli/releases/latest) |
-
-### Standalone CLI Executables
-
-Pre-built CLI binaries (no Node.js required, ~56 MB):
-
-| Platform | File |
-|----------|------|
-| Windows x64 | `ai-cli-win.exe` |
-| macOS arm64 | `ai-cli-mac` |
-| macOS x64 | `ai-cli-mac-x64` |
-| Linux x64 | `ai-cli-linux` |
-
-## Quick Start
-
-### Terminal CLI
-
-```bash
-aicli
-```
-
-On first run, an interactive setup wizard guides you through setting up your profile and entering your API key. Your identity is persisted and injected into every AI conversation.
-
-```
-[deepseek] > Hello! Tell me about this project
-[deepseek] > @src/main.ts Review this file for bugs
-[deepseek] > @screenshot.png What's in this image?
-[deepseek] > /help
-```
-
-Use `@filepath` to reference files or images directly in your prompt.
-
-### Web UI
-
-```bash
-aicli web                    # Start on localhost:3000
-aicli web --port 8080        # Custom port
-aicli web --host 0.0.0.0    # LAN access (shows QR-friendly URL)
-```
-
-Features: multi-tab sessions, file tree panel, drag & drop images, prompt templates, 8 DaisyUI themes, PWA installable, keyboard shortcuts, diff syntax highlighting.
-
-### User Management
-
-```bash
-aicli user create admin      # Create user (enables auth)
-aicli user list              # List all users
-aicli user reset-password x  # Reset password
-aicli user delete x          # Delete user
-```
-
-## Supported Providers
-
-| Provider | Models | Get API Key |
-|----------|--------|-------------|
-| **Claude** | Opus 4, Sonnet 4, Haiku 4 | [console.anthropic.com](https://console.anthropic.com) |
-| **Gemini** | 2.5 Pro, 2.5 Flash | [aistudio.google.com](https://aistudio.google.com) |
-| **DeepSeek** | deepseek-v4-flash (default), deepseek-v4-pro | [platform.deepseek.com](https://platform.deepseek.com) |
-| **OpenAI** | GPT-5.4, GPT-5, GPT-4.1, o3, o4-mini | [platform.openai.com](https://platform.openai.com) |
-| **OpenRouter** | 300+ models (Claude, GPT, Gemini, Llama, Qwen, Mistral...) | [openrouter.ai](https://openrouter.ai) |
-| **Zhipu** | GLM-4, GLM-5 | [open.bigmodel.cn](https://open.bigmodel.cn) |
-| **Kimi** | Kimi K2.6, K2.5, K2 Thinking | [platform.moonshot.cn](https://platform.moonshot.cn) |
-| **Qwen** | qwen-plus, qwen-max, qwen-turbo, qwen-coder-plus | [bailian.console.aliyun.com](https://bailian.console.aliyun.com) |
-| **MiniMax** | MiniMax-M3 (default), M2.7, M2.5, M2.1, M2 | [platform.minimaxi.com](https://platform.minimaxi.com) |
-| **Ollama** | Any locally installed model (Llama, Qwen, Gemma, Mistral...) | No API key — [ollama.com](https://ollama.com) |
-
-Any OpenAI-compatible API can also be used via `customBaseUrls` in config.
-
-### Ollama (Local Models)
-
-Run AI models entirely on your own hardware — no API key, no usage fees, no data leaving your machine.
-
-```bash
-# Install Ollama from https://ollama.com, then pull a model:
-ollama pull qwen3:4b      # recommended: good tool-calling support
-ollama pull gemma3:4b
-ollama pull llama3.1:8b
-
-# Start aicli and switch to Ollama:
-aicli
-[deepseek] > /provider ollama   # auto-discovers installed models
-[ollama] > /model               # select from your local models
-```
-
-> **Note**: Use models 4B+ for best results with tool calling. Small models (<4B) may struggle with the tool definitions injected by MCP servers.
-
-## Built-in Tools (Agentic)
-
-AI autonomously invokes these 30 tools during conversations:
-
-| Tool | Safety | Description |
-|------|--------|-------------|
-| `bash` | varies | Execute shell commands (PowerShell on Windows, $SHELL on Unix) |
-| `read_file` | safe | Read file contents (10 MB limit, image support) |
-| `write_file` | write | Create/overwrite files (diff preview + confirmation) |
-| `edit_file` | write | Precise string replacement with fuzzy matching hints + `replaceAll` mode |
-| `list_dir` | safe | List directory contents |
-| `grep_files` | safe | Regex search across files |
-| `glob_files` | safe | Match files by glob pattern |
-| `web_fetch` | safe | Fetch web pages as Markdown (SSRF-protected) |
-| `web_search` | safe | Keyless Bing/Google web search with weak-result fallback |
-| `google_search` | safe | Google Custom Search API |
-| `run_interactive` | write | Run interactive programs with stdin input; arbitrary executables require confirmation |
-| `run_tests` | safe | Auto-detect and run project tests (JUnit XML parsing) |
-| `spawn_agent` | safe | Delegate subtasks to named isolated agents (`agent`: explorer/worker/reviewer/security/tester) |
-| `ask_user` | safe | Pause and ask the user a question |
-| `save_memory` | safe | Persist governed memory across sessions; AI-written entries stay pending until `/memory approve <id>` |
-| `write_todos` | safe | Task breakdown with live progress rendering |
-| `save_last_response` | write | Save AI response to file |
-| `task_create` | write | Start a command running in the background |
-| `task_list` | safe | List background tasks and their status/output |
-| `task_stop` | write | Stop a running background task |
-| `git_status` | safe | Show working tree status (branch, staged, modified, untracked) |
-| `git_diff` | safe | Show file diffs (staged/unstaged, stat summary) |
-| `git_log` | safe | Show commit history (oneline/full, filter by file/author) |
-| `git_commit` | write | Create a git commit (stage files, message) |
-| `notebook_edit` | write | Edit Jupyter notebook cells (add/edit/delete/move) |
-| `find_symbol` | safe | Locate symbol definitions via persistent tree-sitter index (TS/JS/TSX/Python/Go/Rust/Java/C++) |
-| `get_outline` | safe | Enumerate all top-level declarations in one source file |
-| `find_references` | safe | Search indexed files for references to a symbol name |
-| `search_code` | safe | Semantic (meaning-based) code search via local sentence embeddings — bilingual, "grep by meaning" |
-| `recall_memory` | safe | Semantically recall relevant excerpts from earlier chat sessions |
-
-**Safety levels**: `safe` = auto-execute, `write` = confirmation required (file-editing tools also show a diff preview), `destructive` = prominent warning + confirmation.
-
-## Key REPL Commands
-
-| Command | Description |
-|---------|-------------|
-| `/provider` | Switch AI provider |
-| `/model` | Switch model; `/model refresh [provider]` refreshes live model cache |
-| `/plan` | Enter read-only planning mode |
-| `/think` | Toggle Claude extended thinking |
-| `/test` | Auto-detect and run project tests |
-| `/review` | AI code review of current git diff |
-| `/security-review` | Security vulnerability scan on git diff |
-| `/rewind` | Rewind conversation + restore files to checkpoint state |
-| `/scaffold <desc>` | AI generates project skeleton |
-| `/init` | AI generates project context file (AICLI.md) |
-| `/compact` | Compress conversation history |
-| `/session` | Session management (new / list / load) |
-| `/checkpoint` | Save/restore conversation checkpoints |
-| `/fork` | Fork the current session into a new session file |
-| `/branch` | Create/switch/delete branches *within* the current session (B2) |
-| `/index` | Manage symbol + semantic index (status/rebuild/clear/semantic-rebuild/semantic-clear) — powers `find_symbol` / `get_outline` / `find_references` / `search_code` (C1+C2) |
-| `/search <keyword>` | Full-text search across all sessions |
-| `/skill` | Manage agent skill packs |
-| `/mcp` | View MCP server status and tools |
-| `/cost` | Show token usage statistics |
-| `/undo` | Undo last file operation |
-| `/doctor` | Health check (API keys, MCP, context) |
-| `/export` | Export session as Markdown or JSON |
-| `/profile` | View/edit your identity (AI knows who you are across all providers) |
-| `/config` | Open configuration wizard |
-| /help | Show all available commands |
-| /plugin | Install, trust, enable, disable, and inspect package plugins |
-
-**Multi-line input**: Use `\` at end of line for continuation, or paste multi-line content directly (auto-detected and merged).
-
-Type `/help` in the REPL to see all 48 commands.
-
-## CLI Parameters
-
-```bash
-aicli [options]
-
-Options:
-  --provider <name>        Set AI provider
-  -m, --model <name>       Set model
-  -p, --prompt <text>      Headless mode: single prompt, then exit
-  --system <prompt>        Override system prompt (headless)
-  --json                   Output JSON response (headless)
-  --output-format <fmt>    text | streaming-json (NDJSON)
-  --resume <id>            Resume a previous session
-  --allowed-tools <list>   Comma-separated tool whitelist
-  --blocked-tools <list>   Comma-separated tool blacklist
-  --no-stream              Disable streaming output
-
-Subcommands:
-  aicli web [options]      Start Web UI server
-  aicli config             Run configuration wizard
-  aicli providers          List all providers and status
-  aicli sessions           List recent sessions
-  aicli user <action>      Manage Web UI users
-  aicli batch <action>     Anthropic Batches API (submit | list | status | results | cancel)
-```
-
-### Batch Mode (Anthropic Message Batches)
-
-For offline analysis, bulk evals, or any workload where latency is flexible, use the Batches API for **50% off** tokens with a 24-hour processing window.
-
-```bash
-# 1. Prepare a JSONL file (one request per line):
-#    {"customId":"req-1","messages":[{"role":"user","content":"..."}],"maxTokens":1024}
-aicli batch submit prompts.jsonl         # validate + submit + track locally
-aicli batch submit --dry-run prompts.jsonl  # parse only, no network
-
-aicli batch list                          # live status of recent batches
-aicli batch status <id>                   # detailed status + request counts
-aicli batch results <id> out.jsonl        # download results (stdout if no path)
-aicli batch cancel <id>                   # cancel an in-progress batch
-```
-
-Local tracking file: `~/.aicli/batches.json` (last 200 submissions). Requires `AICLI_API_KEY_CLAUDE` or a Claude API key configured via `aicli config`.
-
-### Headless Mode
-
-```bash
-# Single prompt
-aicli -p "Explain recursion in one sentence"
-
-# Pipe stdin
-cat src/main.ts | aicli -p "Review this code"
-
-# JSON output for scripting
-aicli -p "hello" --json
-
-# Streaming JSON (NDJSON)
-aicli -p "write a poem" --output-format streaming-json
-```
-
-## Configuration
-
-Configuration is stored at `~/.aicli/config.json`. Run `aicli config` for the interactive wizard, or edit directly:
-
-```json
-{
-  "defaultProvider": "deepseek",
-  "apiKeys": {
-    "deepseek": "sk-...",
-    "claude": "sk-ant-...",
-    "openrouter": "sk-or-..."
-  },
-  "proxy": "http://127.0.0.1:10809",
-  "mcpServers": { },
-  "ui": {
-    "theme": "dark",
-    "wordWrap": 0,
-    "notificationThreshold": 10000
-  }
-}
-```
-
-### Permission Rules
-
-Control when tools require confirmation. Rules are checked in order — first match wins:
-
-```json
-{
-  "permissionRules": [
-    { "tool": "read_file", "action": "auto-approve" },
-    { "tool": "list_dir", "action": "auto-approve" },
-    { "tool": "grep_files", "action": "auto-approve" },
-    { "tool": "glob_files", "action": "auto-approve" },
-    { "tool": "write_todos", "action": "auto-approve" },
-    { "tool": "bash", "action": "auto-approve", "when": { "dangerLevel": "safe" } },
-    { "tool": "write_file", "action": "auto-approve", "when": { "pathPattern": "src/" } },
-    { "tool": "bash", "action": "deny", "when": { "pathPattern": "rm -rf" } },
-    { "tool": "*", "action": "confirm" }
-  ]
-}
-```
-
-| Field | Description |
-|-------|-------------|
-| `tool` | Tool name, or `*` for all tools |
-| `action` | `auto-approve` (skip confirmation), `deny` (block), `confirm` (ask user) |
-| `when.dangerLevel` | Only match when danger level is `safe`, `write`, or `destructive` |
-| `when.pathPattern` | Substring match against tool's `path` or `command` argument |
-
-### Permission Profiles
-
-Permission profiles provide coarse-grained safety boundaries before fine-grained `permissionRules` run. The default profile is `legacy`, so existing configs keep their old behavior.
-
-Built-in profiles:
-
-| Profile | Behavior |
-|---------|----------|
-| `legacy` | Backward-compatible mode. Uses `permissionRules` and `defaultPermission` as before. |
-| `read-only` | Allows known read-only/safe tools and safe MCP tools; blocks write and destructive tools. |
-| `workspace-write` | Allows explicit file writes only inside the workspace roots or temp dirs; destructive tools still require confirmation. |
-| `danger-full-access` | Auto-approves non-destructive tools by default; destructive tools still require confirmation. Use only in isolated environments. |
-
-```json
-{
-  "defaultPermissionProfile": "workspace-write",
-  "allowedPermissionProfiles": ["legacy", "read-only", "workspace-write", "danger-full-access"],
-  "permissionProfiles": {
-    "workspace-write": {
-      "workspaceRoots": ["D:/github/ai-cli"],
-      "allowTemp": true,
-      "rules": [
-        { "tool": "read_file", "action": "auto-approve" },
-        { "tool": "list_dir", "action": "auto-approve" }
-      ]
-    }
-  },
-  "permissionRules": [
-    { "tool": "bash", "action": "deny", "when": { "pathPattern": "rm -rf" } }
-  ]
-}
-```
-
-`/status` and `/security status` show the active profile. The Web status payload also includes `permissionProfile` for UI surfaces.
-### Auto Mode
-
-`/auto on|off|status` enables a session-scoped, rule-based action classifier. It is designed to reduce confirmation fatigue without widening `/yolo`: `/yolo` still only skips write confirmations, while destructive tools still require confirmation.
-
-Auto Mode may auto-approve low-risk actions such as explicit writes inside the workspace/temp roots, read-only HTTP tools, plain non-force `git push`, and dependency installs already declared in `package.json` or a lockfile. It denies high-risk shapes such as `curl | bash`, force push, and likely secret exfiltration. Production deploys, database migrations, IaC destroy, credential/permission changes, and third-party agent loops fall back to confirmation.
-
-Auto Mode is not enabled by project config. Use `/permissions recently-denied` to inspect actions it blocked, or `/permissions clear-denied` to clear that session list.
-### Agent Team
-
-`spawn_agent` can now use named roles from built-ins or JSON configs in `~/.aicli/agents/` and `.aicli/agents/`. Built-ins are `explorer`, `worker`, `reviewer`, `security`, and `tester`. Agent configs may set description, provider/model, system instructions, allowed/blocked tools, permission profile, max tool rounds, and context policy; they can only narrow the inherited sub-agent safety boundary. Use `/agent list|switch|stop|summary` to inspect roles and recent sub-agent runs.
-
-### Network Policy
-`networkPolicy` is disabled by default for backward compatibility. When enabled, it governs network-facing tools before execution: `web_fetch`, `web_search`, `google_search`, MCP tools, and shell commands that look like network access (`curl`, `wget`, `git clone/fetch/pull/push`, package installs, SSH/SCP, etc.).
-
-```json
-{
-  "networkPolicy": {
-    "enabled": true,
-    "defaultAction": "confirm",
-    "allowDomains": ["github.com", "docs.anthropic.com", "platform.openai.com"],
-    "denyDomains": ["example-danger.test"],
-    "allowPrivateNetwork": false,
-    "tools": {
-      "web_fetch": "confirm",
-      "web_search": "allow",
-      "google_search": "confirm",
-      "shell": "confirm",
-      "mcp": "confirm"
-    }
-  }
-}
-```
-
-Actions are `allow`, `confirm`, or `deny`. Domain entries match the exact host or subdomains; port lists match the resolved URL port. Private/internal hosts such as `localhost`, `127.0.0.1`, `10.0.0.0/8`, `192.168.0.0/16`, and private IPv6 ranges are blocked unless `allowPrivateNetwork` is true.
-### Trusted Hooks Lifecycle
-
-Legacy `preToolExecution` / `postToolExecution` hooks still work. New lifecycle hooks live under `hooks.events.<EventName>` and receive a JSON payload through `AICLI_HOOK_EVENT_JSON`; if the command prints JSON, ai-cli reads decisions such as `allow`, `deny`, `ask`, `warning`, or `warnings`.
-
-```json
-{
-  "hooks": {
-    "events": {
-      "PreToolUse": {
-        "command": "node ./scripts/aicli-pre-tool-hook.mjs",
-        "source": "project",
-        "description": "Block unsafe local commands"
-      },
-      "UserPromptSubmit": "node ./scripts/aicli-prompt-hook.mjs",
-      "Stop": { "command": "npm test -- --runInBand", "timeoutMs": 10000 }
-    }
-  }
-}
-```
-
-Supported lifecycle names are `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PermissionRequest`, `PostToolUse`, `PreCompact`, `PostCompact`, `Stop`, `SubagentStart`, and `SubagentStop`. Project-sourced hooks must be trusted before execution; ai-cli stores trust records locally under the user config directory, keyed by hook hash, so changing hook content requires re-trust.
-
-Use `/hooks list`, `/hooks inspect <id>`, `/hooks trust <id>`, `/hooks untrust <id>`, and `/hooks disable` to manage them. `/status`, `/security status`, and Web status show pending project hooks that require trust.
-**Recommended minimal config** — auto-approve all read-only tools to reduce y/N prompts:
-
-```json
-{
-  "permissionRules": [
-    { "tool": "read_file", "action": "auto-approve" },
-    { "tool": "list_dir", "action": "auto-approve" },
-    { "tool": "grep_files", "action": "auto-approve" },
-    { "tool": "glob_files", "action": "auto-approve" },
-    { "tool": "web_fetch", "action": "auto-approve" },
-    { "tool": "write_todos", "action": "auto-approve" },
-    { "tool": "ask_user", "action": "auto-approve" },
-    { "tool": "run_tests", "action": "auto-approve" }
-  ]
-}
-```
-
-### Environment Variables
-
-Environment variables take precedence over config file values:
-
-| Variable | Description |
-|----------|-------------|
-| `AICLI_API_KEY_CLAUDE` | Claude API Key |
-| `AICLI_API_KEY_GEMINI` | Gemini API Key |
-| `AICLI_API_KEY_DEEPSEEK` | DeepSeek API Key |
-| `AICLI_API_KEY_OPENAI` | OpenAI API Key |
-| `AICLI_API_KEY_OPENROUTER` | OpenRouter API Key |
-| `AICLI_API_KEY_ZHIPU` | Zhipu API Key |
-| `AICLI_API_KEY_KIMI` | Kimi API Key |
-| `AICLI_API_KEY_QWEN` | Qwen / Alibaba Cloud API Key |
-| `AICLI_API_KEY_MINIMAX` | MiniMax API Key |
-| `AICLI_PROVIDER` | Default provider ID |
-| `AICLI_NO_STREAM` | Set to `1` to disable streaming |
-| `HTTPS_PROXY` / `HTTP_PROXY` | Proxy URL |
-
-### Hierarchical Context Files
-
-ai-cli automatically discovers and injects context files into the system prompt:
-
-| Layer | Path | Purpose |
-|-------|------|---------|
-| Global | `~/.aicli/<context-file>` | Personal preferences across all projects |
-| Project | `<git-root>/<context-file>` | Project rules (commit to git for team sharing) |
-| Subdirectory | `<cwd>/<context-file>` | Directory-specific instructions |
-
-At each layer, ai-cli loads the first non-empty file in this priority order: `AICLI.override.md`, `AGENTS.override.md`, `AICLI.md`, `CLAUDE.md`, `AGENTS.md`. `AICLI.md` is the native filename; `CLAUDE.md` and `AGENTS.md` are compatibility filenames for Claude Code and Codex-style projects.
-
-### MCP Integration
-
-Connect external [MCP](https://modelcontextprotocol.io/) servers for dynamic tool discovery. Configuration is compatible with Claude Desktop format:
-
-```json
-{
-  "mcpServers": {
-    "filesystem": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"],
-      "timeout": 30000
-    }
-  }
-}
-```
-
-Project-level `.mcp.json` files are also supported and automatically merged with global config.
-
-## Web UI Features
-
-The Web UI (`aicli web`) provides a full-featured browser interface:
-
-- **Multi-Tab Sessions** — parallel conversations in separate browser tabs
-- **File Tree Panel** — browse project files, click to insert `@path` references
-- **Image Upload** — drag & drop or Ctrl+V paste images into chat
-- **Prompt Templates** — CRUD with tags, search, import/export
-- **8 Themes** — DaisyUI themes with code highlight auto-sync
-- **Diff Syntax Highlighting** — colored diff in tool confirm dialogs
-- **Keyboard Shortcuts** — `Esc` stop, `Ctrl+L` clear, `↑↓` history
-- **Export** — `/export md` or `/export json` browser download
-- **PWA** — installable as desktop/mobile app
-- **LAN Access** — `--host 0.0.0.0` for phone/tablet access
-- **Multi-User Auth** — password authentication with per-user data isolation
-- **Auto-Reconnect** — heartbeat + exponential backoff reconnection
-
-## Testing
-
-```bash
-npm test              # Offline regression suite
-npm run test:providers # Real-provider smoke tests (network/API-key dependent)
-npm run test:e2e-web  # Playwright browser smoke; may need browser-process permission in sandboxes
-npm run test:watch    # Watch mode
-```
-
-Offline tests cover authentication, sessions, tool types and danger levels, permissions, output truncation, diff rendering, edit-file similarity, error hierarchy, config management, env loading, provider registry, web-fetch, grep-files, Hub, dev-state, token estimation, tool registry budgets, parallel tool execution, cost tracking, and session tool history.
-
-## Releasing (Version Bump → Git Tag → Trusted npm Publish)
-
-> **For contributors and AI agents: the entire release is driven by [`scripts/release.mjs`](scripts/release.mjs). Never manually bump the version or run `npm publish` yourself** — a hand-publish of `0.4.207` shipped a version that reported the wrong number and forced a corrective re-release (`0.4.208`). The script's guards exist precisely to stop that.
-
-**Prerequisites**
-
-- You are on the `main` branch and the changes to ship are already in the working tree.
-- `npx tsc --noEmit` is clean and `npm test` is green (the script enforces both and rolls the bump back on failure).
-- npm Trusted Publishing is configured for `jinzd-ai-cli` and `.github/workflows/release.yml`.
-- You have push access to the GitHub remote.
-
-**Step 1 — Write the milestone entry FIRST (Guard A).** Add a one-line entry to the `## 最近里程碑` section of [`CLAUDE.md`](CLAUDE.md) that contains the exact full-width-parenthesis marker `（vX.Y.Z）` for the target version. The script refuses to start without it. (Full narrative goes in `CHANGELOG.md`; this section is just the index line.)
-
-**Step 2 — Run the release script.**
-
-```bash
-# patch: 0.4.209 → 0.4.210  (also accepts: minor / major / an explicit x.y.z)
-node scripts/release.mjs patch -m "fix(scope): one-line commit title"
-
-# preview only — validates guards, writes nothing:
-node scripts/release.mjs patch -m "..." --dry-run
-```
-
-- Do **not** put a `(vX.Y.Z)` suffix in `-m`; the script appends it automatically.
-- On Windows PowerShell, call `node` directly — `npm run release -- -m ...` swallows the `-m` argument.
-
-**What the script does, in order:**
-
-1. **Guard A** — asserts `CLAUDE.md` contains the `（vX.Y.Z）` milestone entry.
-2. Bumps the version in **three** places: `package.json`, `src/core/constants.ts` (`VERSION`), and `CLAUDE.md` (`**当前版本**`).
-3. **Guard B** — re-reads all three files from disk and asserts every bump landed.
-4. **Guard C** — `tsc --noEmit` must be zero-error (rolls the bump back on failure).
-5. `npm test` must pass (rolls the bump back on failure).
-6. Prints the exact file list entering the release commit and blocks if any looks sensitive (`.env`, `*.pem`, `*.key`, `secret`, …). Override consciously with `--allow-sensitive`.
-7. `git add -A` + commit `"<title> (vX.Y.Z)"` (message passed via argv, not shell-interpolated).
-8. Creates an annotated `vX.Y.Z` release tag.
-9. Pushes `main` and the tag. The pinned GitHub Actions workflow verifies the project and publishes to npm through OIDC, without a long-lived npm token.
-
-**Optional flags:** `--dry-run` · `--skip-tests` · `--no-tag` · `--no-push` · `--allow-sensitive`. The old `--no-publish` flag remains an alias for `--no-tag`.
-
-### Which files a release touches
-
-Two groups: what **you** write by hand (the script never touches these, and Guard A refuses to start without them) and what the **script** rewrites (never edit these by hand).
-
-| File | Written by | What changes |
-|---|---|---|
-| `CHANGELOG.md` | **By hand, before releasing** | A new `## [X.Y.Z] - YYYY-MM-DD` section with the full narrative: root cause / fix / tests. This is the only place detail lives |
-| `CLAUDE.md` → `## 最近里程碑` | **By hand, before releasing** | **One** index line at the top, which must carry the full-width marker `（vX.Y.Z）` — this exact line is what Guard A checks |
-| `package.json` | Script | `"version"` |
-| `src/core/constants.ts` | Script | The `VERSION` constant (what `aicli --version` and the help banner actually read — drift here ships a package that reports the wrong version) |
-| `CLAUDE.md` → `**当前版本**` | Script | The version number (a *second*, separate spot from the hand-written milestone line) |
-| `docs/USAGE.md`, `docs/USAGE.zh-CN.md`, `docs/ADVANCED*.md`, `docs/TUTORIAL*.md`, `docs/RECIPES*.md`, `SECURITY.md`, `docs/SECURITY*.md` | Script | Only the **document-header** baseline lines (`> **Version**: vX.Y.Z`, security baseline, `当前 vX.Y.Z`). Deliberately first-match-only — "feature introduced in v0.4.246+" markers in the body must keep their original versions |
-| `dist/` | Script | Built once before the test gate so `dist` matches the new version (the `version-drift` guard compares the build output); `prepublishOnly` builds again from scratch at publish time |
-
-**Guard B only watches the first three** (`package.json` / `constants.ts` / `CLAUDE.md` current version) — it re-reads them from disk after the bump and asserts each one landed. Both historical incidents (`0.4.207`, `0.4.239`) were drift across exactly these three, and both happened by bypassing the script.
-
-**If the change itself touches any of the following, sync it too** (guards will catch these, but knowing up front saves a round):
-
-- Adding/removing a provider, built-in tool, or REPL command → the `docs-drift` guard requires the count markers and tables across all four docs to match
-- Adding a provider → it must be added to the matrix in `tests/unit/providers/quirk-contracts.test.ts`
-- Node minimum version, the `bin` name, or recovery-path wording → covered by the `version-drift` guard
-
-## Documentation
-
-- [`docs/USAGE.md`](docs/USAGE.md) — Complete reference manual (commands, tools, config)
-- [`docs/TUTORIAL.md`](docs/TUTORIAL.md) — Hands-on tutorial, zero to fluent in an hour
-- [`docs/ADVANCED.md`](docs/ADVANCED.md) — Architecture and internals (for developers)
-- [`docs/MIGRATION.md`](docs/MIGRATION.md) — Migration guide from Claude Code, Codex, Claude Desktop, and Cursor
-- [`docs/RECIPES.md`](docs/RECIPES.md) — Practical recipes by scenario
-- [`docs/SECURITY.md`](docs/SECURITY.md) — **Security model, deployment checklist, audit history.** Read before exposing `aicli web` to a network.
-- [`CHANGELOG.md`](CHANGELOG.md) — Per-version change log
-- [`CONTRIBUTING.md`](CONTRIBUTING.md) · [`SUPPORT.md`](SUPPORT.md) · [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) — Community guides
-- [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md) — Licenses for vendored browser assets
-- [`docs/OPEN_SOURCE_CHECKLIST.md`](docs/OPEN_SOURCE_CHECKLIST.md) — Repository-owner launch checklist
-- [Chinese README](README.zh-CN.md) — 中文说明文档
-
-## License
-
-[MIT](LICENSE)
+**English** | [中文](README.zh-CN.md)
+
+# ai-cli
+
+<!-- AICLI:DOCS_DEFAULT_WEB_PORT=3000 -->
+<!-- AICLI:DOCS_BUILTIN_TOOL_COUNT=30 -->
+<!-- AICLI:DOCS_REPL_COMMAND_COUNT=48 -->
+<!-- AICLI:DOCS_BUILTIN_PROVIDER_COUNT=10 -->
+<!-- AICLI:DOCS_MEMORY_SOURCE=memory.jsonl -->
+
+> A cross-platform AI coding assistant — CLI, Web UI, and Desktop App — with multi-provider support and agentic tool calling
+
+[![npm version](https://img.shields.io/npm/v/jinzd-ai-cli)](https://www.npmjs.com/package/jinzd-ai-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20.18.1-brightgreen)](https://nodejs.org)
+[![GitHub Release](https://img.shields.io/github/v/release/jinzhengdong/ai-cli)](https://github.com/jinzhengdong/ai-cli/releases)
+[![CI](https://github.com/jinzhengdong/ai-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/jinzhengdong/ai-cli/actions/workflows/ci.yml)
+
+**ai-cli** is a powerful AI assistant that connects to 10 providers (including local Ollama models) and executes tasks autonomously through agentic tool calling. Use it as a terminal REPL, a browser-based Web UI, or a standalone Electron desktop app.
+
+<p align="center">
+  <img src="https://img.shields.io/badge/CLI-Terminal-blue" alt="CLI" />
+  <img src="https://img.shields.io/badge/Web_UI-Browser-green" alt="Web UI" />
+  <img src="https://img.shields.io/badge/Desktop-Electron-purple" alt="Desktop" />
+</p>
+
+## Highlights
+
+- **10 Built-in Providers** — Claude, Gemini, DeepSeek, OpenAI, Zhipu GLM, Kimi, Qwen, **MiniMax (海螺)**, OpenRouter (300+ models), **Ollama** (local models, no API key needed)
+- **3 Interfaces** — Terminal CLI, browser Web UI (`aicli web`), Electron desktop app
+- **Agentic Tool Calling** — AI autonomously runs shell commands, reads/writes files, searches code, fetches web, runs tests (default 200 rounds, configurable up to 10000 via `config.maxToolRounds` or `--max-tool-rounds`)
+- **Prompt Caching** *(v0.4.70+)* — System prompt split into stable/volatile halves so Claude caches the stable part with `cache_control: ephemeral`; cached tokens bill at ~10% of the input price
+- **Unified-Diff Patch Edits** *(v0.4.72+)* — `edit_file` accepts standard `@@ -a,b +c,d @@` hunks for the most compact way to apply many scattered small changes to a large file (±200-line drift tolerance + whitespace fallback)
+- **Anthropic Batches API** *(v0.4.73+)* — `aicli batch submit/list/status/results/cancel` for 50%-off, 24-hour async processing — ideal for offline analysis and bulk evals
+- **Web UI Session Replay** *(v0.4.71+)* — 🎬 button on every saved session opens a timeline replay: every message, tool call, reasoning, and cache-aware token usage at a glance
+- **Conversation Branching** *(v0.4.74+)* — `/branch list/new/switch/delete/rename` inside the REPL, plus a 🌿 "fork here" button on every replay step — explore alternate directions without losing the original thread
+- **Symbol Index** *(v0.4.76+, multi-language since v0.4.143)* — persistent tree-sitter index for TypeScript / JavaScript / TSX / Python / Go / Rust / Java / C/C++ powers three new AI tools: `find_symbol`, `get_outline`, `find_references`. Orders of magnitude faster than grep for definition lookups; background refresh on REPL startup, `/index status|rebuild|clear` to manage
+- **Semantic Code Search** *(v0.4.77+)* — `search_code` tool finds code by meaning, not name. Local sentence embeddings (multilingual MiniLM, 117 MB one-time download) score symbols by cosine similarity against natural-language queries in English or Chinese ("where are users authenticated", "哪里做了速率限制"). No API key, runs on CPU. Manage with `/index semantic-rebuild|semantic-clear`
+- **MCP Server Mode** *(v0.4.84+)* — `aicli mcp-serve` reverses ai-cli into an MCP server (JSON-RPC 2.0 over stdio), exposing its 30 built-in tools (incl. `find_symbol` / `search_code` / `run_tests`) to Claude Desktop / Cursor / any MCP client. Opt-in destructive-tool allow, `--tools` whitelist, `--cwd` override
+- **Session Sensitive-Data Redaction** *(v0.4.88+)* — unified redactor scrubs `password=` / `api_key` / bearer tokens / OpenAI-style keys from every message **before it hits disk**. Query text is redacted too, so secrets never reach embeddings or logs. `/security status` + `/security scan` to audit
+- **Human-like Long-Term Memory** *(v0.4.89+, B4)* — semantic index over every past chat session + `recall_memory` AI tool + `/memory rebuild|refresh|status|recall` commands. AI is prompted to auto-recall when it sees "last time" / "之前" / ambiguous references. Reuses the same MiniLM embedder as semantic code search
+- **Governed Persistent Memory** *(v0.4.217+)* — `save_memory` and `/memory add` write auditable `memory.jsonl` entries with id/scope/source/sensitivity/approval/expiry; AI-written entries (`save_memory`) always stay pending until `/memory approve <id>` (v0.4.242+), low-risk manual entries auto-approve, project-scoped memories only inject inside the same project, and `/memory clear` confirms + keeps a timestamped backup
+- **Package Plugin Ecosystem** *(v0.4.218+)* — install shareable .aicli-plugin/plugin.json packages with skills, hooks, commands, MCP servers, agents, and permission hints; only trusted+enabled plugins load, hooks still require hook trust, and MCP/tools remain under permission profiles/network policy
+- **Web UI Memory Panel** *(v0.4.90+, B4)* — new 🧠 Memory sidebar tab with semantic search across past chats; each hit has **➕ Inject** (quotes the snippet into the chat input as a markdown blockquote so you can review/edit before sending — no silent context injection) and **↗ Load** (jumps to source session). Bulk "Inject top 3" for recall bundles
+- **Streaming Tool Use** — Real-time streaming of AI reasoning and tool calls as they happen
+- **Sub-Agents** — Delegate complex subtasks to isolated child agents with independent tool loops
+- **Extended Thinking** — Claude deep reasoning mode with `/think` toggle
+- **Plan Mode** — Read-only planning phase (`/plan`) where AI analyzes before executing, with loop detection
+- **Auto-Pause** — Automatically pauses every 10 rounds for user review and redirection
+- **MCP Protocol** — Connect external MCP servers for dynamic tool discovery
+- **Multi-User Auth** — Web UI supports multiple users with password authentication
+- **PWA Support** — Install Web UI as a desktop/mobile app, accessible over LAN
+- **Hierarchical Context** — 3-layer context files (global / project / subdirectory) auto-injected; supports native AICLI.md, Claude-compatible CLAUDE.md, and Codex-compatible AGENTS.md with override files
+- **Headless Mode** — `ai-cli -p "prompt"` for CI/CD pipelines and scripting
+- **48 REPL Commands** — Session management, checkpointing, code review, security review/scan, rewind, scaffolding, cross-session history search, chat-memory recall, smart model routing (`/route`), and more
+- **GitHub Actions CI/CD** — Automated testing on Node 20/22 + npm publish on release tags
+- **PR Review CLI** *(v0.4.216+)* — `aicli pr review|security-review|summarize` reviews `main...HEAD`, custom `--base/--head`, or GitHub PR URLs; optional `--agents security,bugs,tests,maintainability`; never posts comments unless `--post` is explicit
+- **CI Review Artifacts** *(v0.4.216+)* — `aicli ci` emits Markdown, JSON, or SARIF and gates on security-high, test-failure, and lint-failure findings in read-only review mode
+- **Cross-Platform** — Windows, macOS, Linux
+
+## Installation
+
+### npm (recommended)
+
+```bash
+npm install -g jinzd-ai-cli
+```
+
+Requires Node.js >= 20.18.1. After installation, use `aicli` to start.
+
+### Electron Desktop App (Windows)
+
+Download the installer from [GitHub Releases](https://github.com/jinzhengdong/ai-cli/releases) — no Node.js required:
+
+| Platform | Download |
+|----------|----------|
+| Windows x64 | [`ai-cli-setup.exe`](https://github.com/jinzhengdong/ai-cli/releases/latest) |
+
+### Standalone CLI Executables
+
+Pre-built CLI binaries (no Node.js required, ~56 MB):
+
+| Platform | File |
+|----------|------|
+| Windows x64 | `ai-cli-win.exe` |
+| macOS arm64 | `ai-cli-mac` |
+| macOS x64 | `ai-cli-mac-x64` |
+| Linux x64 | `ai-cli-linux` |
+
+## Quick Start
+
+### Terminal CLI
+
+```bash
+aicli
+```
+
+On first run, an interactive setup wizard guides you through setting up your profile and entering your API key. Your identity is persisted and injected into every AI conversation.
+
+```
+[deepseek] > Hello! Tell me about this project
+[deepseek] > @src/main.ts Review this file for bugs
+[deepseek] > @screenshot.png What's in this image?
+[deepseek] > /help
+```
+
+Use `@filepath` to reference files or images directly in your prompt.
+
+### Web UI
+
+```bash
+aicli web                    # Start on localhost:3000
+aicli web --port 8080        # Custom port
+aicli web --host 0.0.0.0    # LAN access (shows QR-friendly URL)
+```
+
+Features: multi-tab sessions, file tree panel, drag & drop images, prompt templates, 8 DaisyUI themes, PWA installable, keyboard shortcuts, diff syntax highlighting.
+
+### User Management
+
+```bash
+aicli user create admin      # Create user (enables auth)
+aicli user list              # List all users
+aicli user reset-password x  # Reset password
+aicli user delete x          # Delete user
+```
+
+## Supported Providers
+
+| Provider | Models | Get API Key |
+|----------|--------|-------------|
+| **Claude** | Opus 4, Sonnet 4, Haiku 4 | [console.anthropic.com](https://console.anthropic.com) |
+| **Gemini** | 2.5 Pro, 2.5 Flash | [aistudio.google.com](https://aistudio.google.com) |
+| **DeepSeek** | deepseek-v4-flash (default), deepseek-v4-pro | [platform.deepseek.com](https://platform.deepseek.com) |
+| **OpenAI** | GPT-5.4, GPT-5, GPT-4.1, o3, o4-mini | [platform.openai.com](https://platform.openai.com) |
+| **OpenRouter** | 300+ models (Claude, GPT, Gemini, Llama, Qwen, Mistral...) | [openrouter.ai](https://openrouter.ai) |
+| **Zhipu** | GLM-4, GLM-5 | [open.bigmodel.cn](https://open.bigmodel.cn) |
+| **Kimi** | Kimi K2.6, K2.5, K2 Thinking | [platform.moonshot.cn](https://platform.moonshot.cn) |
+| **Qwen** | qwen-plus, qwen-max, qwen-turbo, qwen-coder-plus | [bailian.console.aliyun.com](https://bailian.console.aliyun.com) |
+| **MiniMax** | MiniMax-M3 (default), M2.7, M2.5, M2.1, M2 | [platform.minimaxi.com](https://platform.minimaxi.com) |
+| **Ollama** | Any locally installed model (Llama, Qwen, Gemma, Mistral...) | No API key — [ollama.com](https://ollama.com) |
+
+Any OpenAI-compatible API can also be used via `customBaseUrls` in config.
+
+### Ollama (Local Models)
+
+Run AI models entirely on your own hardware — no API key, no usage fees, no data leaving your machine.
+
+```bash
+# Install Ollama from https://ollama.com, then pull a model:
+ollama pull qwen3:4b      # recommended: good tool-calling support
+ollama pull gemma3:4b
+ollama pull llama3.1:8b
+
+# Start aicli and switch to Ollama:
+aicli
+[deepseek] > /provider ollama   # auto-discovers installed models
+[ollama] > /model               # select from your local models
+```
+
+> **Note**: Use models 4B+ for best results with tool calling. Small models (<4B) may struggle with the tool definitions injected by MCP servers.
+
+## Built-in Tools (Agentic)
+
+AI autonomously invokes these 30 tools during conversations:
+
+| Tool | Safety | Description |
+|------|--------|-------------|
+| `bash` | varies | Execute shell commands (PowerShell on Windows, $SHELL on Unix) |
+| `read_file` | safe | Read file contents (10 MB limit, image support) |
+| `write_file` | write | Create/overwrite files (diff preview + confirmation) |
+| `edit_file` | write | Precise string replacement with fuzzy matching hints + `replaceAll` mode |
+| `list_dir` | safe | List directory contents |
+| `grep_files` | safe | Regex search across files |
+| `glob_files` | safe | Match files by glob pattern |
+| `web_fetch` | safe | Fetch web pages as Markdown (SSRF-protected) |
+| `web_search` | safe | Keyless Bing/Google web search with weak-result fallback |
+| `google_search` | safe | Google Custom Search API |
+| `run_interactive` | write | Run interactive programs with stdin input; arbitrary executables require confirmation |
+| `run_tests` | safe | Auto-detect and run project tests (JUnit XML parsing) |
+| `spawn_agent` | safe | Delegate subtasks to named isolated agents (`agent`: explorer/worker/reviewer/security/tester) |
+| `ask_user` | safe | Pause and ask the user a question |
+| `save_memory` | safe | Persist governed memory across sessions; AI-written entries stay pending until `/memory approve <id>` |
+| `write_todos` | safe | Task breakdown with live progress rendering |
+| `save_last_response` | write | Save AI response to file |
+| `task_create` | write | Start a command running in the background |
+| `task_list` | safe | List background tasks and their status/output |
+| `task_stop` | write | Stop a running background task |
+| `git_status` | safe | Show working tree status (branch, staged, modified, untracked) |
+| `git_diff` | safe | Show file diffs (staged/unstaged, stat summary) |
+| `git_log` | safe | Show commit history (oneline/full, filter by file/author) |
+| `git_commit` | write | Create a git commit (stage files, message) |
+| `notebook_edit` | write | Edit Jupyter notebook cells (add/edit/delete/move) |
+| `find_symbol` | safe | Locate symbol definitions via persistent tree-sitter index (TS/JS/TSX/Python/Go/Rust/Java/C++) |
+| `get_outline` | safe | Enumerate all top-level declarations in one source file |
+| `find_references` | safe | Search indexed files for references to a symbol name |
+| `search_code` | safe | Semantic (meaning-based) code search via local sentence embeddings — bilingual, "grep by meaning" |
+| `recall_memory` | safe | Semantically recall relevant excerpts from earlier chat sessions |
+
+**Safety levels**: `safe` = auto-execute, `write` = confirmation required (file-editing tools also show a diff preview), `destructive` = prominent warning + confirmation.
+
+## Key REPL Commands
+
+| Command | Description |
+|---------|-------------|
+| `/provider` | Switch AI provider |
+| `/model` | Switch model; `/model refresh [provider]` refreshes live model cache |
+| `/plan` | Enter read-only planning mode |
+| `/think` | Toggle Claude extended thinking |
+| `/test` | Auto-detect and run project tests |
+| `/review` | AI code review of current git diff |
+| `/security-review` | Security vulnerability scan on git diff |
+| `/rewind` | Rewind conversation + restore files to checkpoint state |
+| `/scaffold <desc>` | AI generates project skeleton |
+| `/init` | AI generates project context file (AICLI.md) |
+| `/compact` | Compress conversation history |
+| `/session` | Session management (new / list / load) |
+| `/checkpoint` | Save/restore conversation checkpoints |
+| `/fork` | Fork the current session into a new session file |
+| `/branch` | Create/switch/delete branches *within* the current session (B2) |
+| `/index` | Manage symbol + semantic index (status/rebuild/clear/semantic-rebuild/semantic-clear) — powers `find_symbol` / `get_outline` / `find_references` / `search_code` (C1+C2) |
+| `/search <keyword>` | Full-text search across all sessions |
+| `/skill` | Manage agent skill packs |
+| `/mcp` | View MCP server status and tools |
+| `/cost` | Show token usage statistics |
+| `/undo` | Undo last file operation |
+| `/doctor` | Health check (API keys, MCP, context) |
+| `/export` | Export session as Markdown or JSON |
+| `/profile` | View/edit your identity (AI knows who you are across all providers) |
+| `/config` | Open configuration wizard |
+| /help | Show all available commands |
+| /plugin | Install, trust, enable, disable, and inspect package plugins |
+
+**Multi-line input**: Use `\` at end of line for continuation, or paste multi-line content directly (auto-detected and merged).
+
+Type `/help` in the REPL to see all 48 commands.
+
+## CLI Parameters
+
+```bash
+aicli [options]
+
+Options:
+  --provider <name>        Set AI provider
+  -m, --model <name>       Set model
+  -p, --prompt <text>      Headless mode: single prompt, then exit
+  --system <prompt>        Override system prompt (headless)
+  --json                   Output JSON response (headless)
+  --output-format <fmt>    text | streaming-json (NDJSON)
+  --resume <id>            Resume a previous session
+  --allowed-tools <list>   Comma-separated tool whitelist
+  --blocked-tools <list>   Comma-separated tool blacklist
+  --no-stream              Disable streaming output
+
+Subcommands:
+  aicli web [options]      Start Web UI server
+  aicli config             Run configuration wizard
+  aicli providers          List all providers and status
+  aicli sessions           List recent sessions
+  aicli user <action>      Manage Web UI users
+  aicli batch <action>     Anthropic Batches API (submit | list | status | results | cancel)
+```
+
+### Batch Mode (Anthropic Message Batches)
+
+For offline analysis, bulk evals, or any workload where latency is flexible, use the Batches API for **50% off** tokens with a 24-hour processing window.
+
+```bash
+# 1. Prepare a JSONL file (one request per line):
+#    {"customId":"req-1","messages":[{"role":"user","content":"..."}],"maxTokens":1024}
+aicli batch submit prompts.jsonl         # validate + submit + track locally
+aicli batch submit --dry-run prompts.jsonl  # parse only, no network
+
+aicli batch list                          # live status of recent batches
+aicli batch status <id>                   # detailed status + request counts
+aicli batch results <id> out.jsonl        # download results (stdout if no path)
+aicli batch cancel <id>                   # cancel an in-progress batch
+```
+
+Local tracking file: `~/.aicli/batches.json` (last 200 submissions). Requires `AICLI_API_KEY_CLAUDE` or a Claude API key configured via `aicli config`.
+
+### Headless Mode
+
+```bash
+# Single prompt
+aicli -p "Explain recursion in one sentence"
+
+# Pipe stdin
+cat src/main.ts | aicli -p "Review this code"
+
+# JSON output for scripting
+aicli -p "hello" --json
+
+# Streaming JSON (NDJSON)
+aicli -p "write a poem" --output-format streaming-json
+```
+
+## Configuration
+
+Configuration is stored at `~/.aicli/config.json`. Run `aicli config` for the interactive wizard, or edit directly:
+
+```json
+{
+  "defaultProvider": "deepseek",
+  "apiKeys": {
+    "deepseek": "sk-...",
+    "claude": "sk-ant-...",
+    "openrouter": "sk-or-..."
+  },
+  "proxy": "http://127.0.0.1:10809",
+  "mcpServers": { },
+  "ui": {
+    "theme": "dark",
+    "wordWrap": 0,
+    "notificationThreshold": 10000
+  }
+}
+```
+
+### Permission Rules
+
+Control when tools require confirmation. Rules are checked in order — first match wins:
+
+```json
+{
+  "permissionRules": [
+    { "tool": "read_file", "action": "auto-approve" },
+    { "tool": "list_dir", "action": "auto-approve" },
+    { "tool": "grep_files", "action": "auto-approve" },
+    { "tool": "glob_files", "action": "auto-approve" },
+    { "tool": "write_todos", "action": "auto-approve" },
+    { "tool": "bash", "action": "auto-approve", "when": { "dangerLevel": "safe" } },
+    { "tool": "write_file", "action": "auto-approve", "when": { "pathPattern": "src/" } },
+    { "tool": "bash", "action": "deny", "when": { "pathPattern": "rm -rf" } },
+    { "tool": "*", "action": "confirm" }
+  ]
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `tool` | Tool name, or `*` for all tools |
+| `action` | `auto-approve` (skip confirmation), `deny` (block), `confirm` (ask user) |
+| `when.dangerLevel` | Only match when danger level is `safe`, `write`, or `destructive` |
+| `when.pathPattern` | Substring match against tool's `path` or `command` argument |
+
+### Permission Profiles
+
+Permission profiles provide coarse-grained safety boundaries before fine-grained `permissionRules` run. The default profile is `legacy`, so existing configs keep their old behavior.
+
+Built-in profiles:
+
+| Profile | Behavior |
+|---------|----------|
+| `legacy` | Backward-compatible mode. Uses `permissionRules` and `defaultPermission` as before. |
+| `read-only` | Allows known read-only/safe tools and safe MCP tools; blocks write and destructive tools. |
+| `workspace-write` | Allows explicit file writes only inside the workspace roots or temp dirs; destructive tools still require confirmation. |
+| `danger-full-access` | Auto-approves non-destructive tools by default; destructive tools still require confirmation. Use only in isolated environments. |
+
+```json
+{
+  "defaultPermissionProfile": "workspace-write",
+  "allowedPermissionProfiles": ["legacy", "read-only", "workspace-write", "danger-full-access"],
+  "permissionProfiles": {
+    "workspace-write": {
+      "workspaceRoots": ["D:/github/ai-cli"],
+      "allowTemp": true,
+      "rules": [
+        { "tool": "read_file", "action": "auto-approve" },
+        { "tool": "list_dir", "action": "auto-approve" }
+      ]
+    }
+  },
+  "permissionRules": [
+    { "tool": "bash", "action": "deny", "when": { "pathPattern": "rm -rf" } }
+  ]
+}
+```
+
+`/status` and `/security status` show the active profile. The Web status payload also includes `permissionProfile` for UI surfaces.
+### Auto Mode
+
+`/auto on|off|status` enables a session-scoped, rule-based action classifier. It is designed to reduce confirmation fatigue without widening `/yolo`: `/yolo` still only skips write confirmations, while destructive tools still require confirmation.
+
+Auto Mode may auto-approve low-risk actions such as explicit writes inside the workspace/temp roots, read-only HTTP tools, plain non-force `git push`, and dependency installs already declared in `package.json` or a lockfile. It denies high-risk shapes such as `curl | bash`, force push, and likely secret exfiltration. Production deploys, database migrations, IaC destroy, credential/permission changes, and third-party agent loops fall back to confirmation.
+
+Auto Mode is not enabled by project config. Use `/permissions recently-denied` to inspect actions it blocked, or `/permissions clear-denied` to clear that session list.
+### Agent Team
+
+`spawn_agent` can now use named roles from built-ins or JSON configs in `~/.aicli/agents/` and `.aicli/agents/`. Built-ins are `explorer`, `worker`, `reviewer`, `security`, and `tester`. Agent configs may set description, provider/model, system instructions, allowed/blocked tools, permission profile, max tool rounds, and context policy; they can only narrow the inherited sub-agent safety boundary. Use `/agent list|switch|stop|summary` to inspect roles and recent sub-agent runs.
+
+### Network Policy
+`networkPolicy` is disabled by default for backward compatibility. When enabled, it governs network-facing tools before execution: `web_fetch`, `web_search`, `google_search`, MCP tools, and shell commands that look like network access (`curl`, `wget`, `git clone/fetch/pull/push`, package installs, SSH/SCP, etc.).
+
+```json
+{
+  "networkPolicy": {
+    "enabled": true,
+    "defaultAction": "confirm",
+    "allowDomains": ["github.com", "docs.anthropic.com", "platform.openai.com"],
+    "denyDomains": ["example-danger.test"],
+    "allowPrivateNetwork": false,
+    "tools": {
+      "web_fetch": "confirm",
+      "web_search": "allow",
+      "google_search": "confirm",
+      "shell": "confirm",
+      "mcp": "confirm"
+    }
+  }
+}
+```
+
+Actions are `allow`, `confirm`, or `deny`. Domain entries match the exact host or subdomains; port lists match the resolved URL port. Private/internal hosts such as `localhost`, `127.0.0.1`, `10.0.0.0/8`, `192.168.0.0/16`, and private IPv6 ranges are blocked unless `allowPrivateNetwork` is true.
+### Trusted Hooks Lifecycle
+
+Legacy `preToolExecution` / `postToolExecution` hooks still work. New lifecycle hooks live under `hooks.events.<EventName>` and receive a JSON payload through `AICLI_HOOK_EVENT_JSON`; if the command prints JSON, ai-cli reads decisions such as `allow`, `deny`, `ask`, `warning`, or `warnings`.
+
+```json
+{
+  "hooks": {
+    "events": {
+      "PreToolUse": {
+        "command": "node ./scripts/aicli-pre-tool-hook.mjs",
+        "source": "project",
+        "description": "Block unsafe local commands"
+      },
+      "UserPromptSubmit": "node ./scripts/aicli-prompt-hook.mjs",
+      "Stop": { "command": "npm test -- --runInBand", "timeoutMs": 10000 }
+    }
+  }
+}
+```
+
+Supported lifecycle names are `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PermissionRequest`, `PostToolUse`, `PreCompact`, `PostCompact`, `Stop`, `SubagentStart`, and `SubagentStop`. Project-sourced hooks must be trusted before execution; ai-cli stores trust records locally under the user config directory, keyed by hook hash, so changing hook content requires re-trust.
+
+Use `/hooks list`, `/hooks inspect <id>`, `/hooks trust <id>`, `/hooks untrust <id>`, and `/hooks disable` to manage them. `/status`, `/security status`, and Web status show pending project hooks that require trust.
+**Recommended minimal config** — auto-approve all read-only tools to reduce y/N prompts:
+
+```json
+{
+  "permissionRules": [
+    { "tool": "read_file", "action": "auto-approve" },
+    { "tool": "list_dir", "action": "auto-approve" },
+    { "tool": "grep_files", "action": "auto-approve" },
+    { "tool": "glob_files", "action": "auto-approve" },
+    { "tool": "web_fetch", "action": "auto-approve" },
+    { "tool": "write_todos", "action": "auto-approve" },
+    { "tool": "ask_user", "action": "auto-approve" },
+    { "tool": "run_tests", "action": "auto-approve" }
+  ]
+}
+```
+
+### Environment Variables
+
+Environment variables take precedence over config file values:
+
+| Variable | Description |
+|----------|-------------|
+| `AICLI_API_KEY_CLAUDE` | Claude API Key |
+| `AICLI_API_KEY_GEMINI` | Gemini API Key |
+| `AICLI_API_KEY_DEEPSEEK` | DeepSeek API Key |
+| `AICLI_API_KEY_OPENAI` | OpenAI API Key |
+| `AICLI_API_KEY_OPENROUTER` | OpenRouter API Key |
+| `AICLI_API_KEY_ZHIPU` | Zhipu API Key |
+| `AICLI_API_KEY_KIMI` | Kimi API Key |
+| `AICLI_API_KEY_QWEN` | Qwen / Alibaba Cloud API Key |
+| `AICLI_API_KEY_MINIMAX` | MiniMax API Key |
+| `AICLI_PROVIDER` | Default provider ID |
+| `AICLI_NO_STREAM` | Set to `1` to disable streaming |
+| `HTTPS_PROXY` / `HTTP_PROXY` | Proxy URL |
+
+### Hierarchical Context Files
+
+ai-cli automatically discovers and injects context files into the system prompt:
+
+| Layer | Path | Purpose |
+|-------|------|---------|
+| Global | `~/.aicli/<context-file>` | Personal preferences across all projects |
+| Project | `<git-root>/<context-file>` | Project rules (commit to git for team sharing) |
+| Subdirectory | `<cwd>/<context-file>` | Directory-specific instructions |
+
+At each layer, ai-cli loads the first non-empty file in this priority order: `AICLI.override.md`, `AGENTS.override.md`, `AICLI.md`, `CLAUDE.md`, `AGENTS.md`. `AICLI.md` is the native filename; `CLAUDE.md` and `AGENTS.md` are compatibility filenames for Claude Code and Codex-style projects.
+
+### MCP Integration
+
+Connect external [MCP](https://modelcontextprotocol.io/) servers for dynamic tool discovery. Configuration is compatible with Claude Desktop format:
+
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"],
+      "timeout": 30000
+    }
+  }
+}
+```
+
+Project-level `.mcp.json` files are also supported and automatically merged with global config.
+
+## Web UI Features
+
+The Web UI (`aicli web`) provides a full-featured browser interface:
+
+- **Multi-Tab Sessions** — parallel conversations in separate browser tabs
+- **File Tree Panel** — browse project files, click to insert `@path` references
+- **Image Upload** — drag & drop or Ctrl+V paste images into chat
+- **Prompt Templates** — CRUD with tags, search, import/export
+- **8 Themes** — DaisyUI themes with code highlight auto-sync
+- **Diff Syntax Highlighting** — colored diff in tool confirm dialogs
+- **Keyboard Shortcuts** — `Esc` stop, `Ctrl+L` clear, `↑↓` history
+- **Export** — `/export md` or `/export json` browser download
+- **PWA** — installable as desktop/mobile app
+- **LAN Access** — `--host 0.0.0.0` for phone/tablet access
+- **Multi-User Auth** — password authentication with per-user data isolation
+- **Auto-Reconnect** — heartbeat + exponential backoff reconnection
+
+## Testing
+
+```bash
+npm test              # Offline regression suite
+npm run test:providers # Real-provider smoke tests (network/API-key dependent)
+npm run test:e2e-web  # Playwright browser smoke; may need browser-process permission in sandboxes
+npm run test:watch    # Watch mode
+```
+
+Offline tests cover authentication, sessions, tool types and danger levels, permissions, output truncation, diff rendering, edit-file similarity, error hierarchy, config management, env loading, provider registry, web-fetch, grep-files, Hub, dev-state, token estimation, tool registry budgets, parallel tool execution, cost tracking, and session tool history.
+
+## Releasing (Version Bump → Git Tag → Trusted npm Publish)
+
+> **For contributors and AI agents: the entire release is driven by [`scripts/release.mjs`](scripts/release.mjs). Never manually bump the version or run `npm publish` yourself** — a hand-publish of `0.4.207` shipped a version that reported the wrong number and forced a corrective re-release (`0.4.208`). The script's guards exist precisely to stop that.
+
+**Prerequisites**
+
+- You are on the `main` branch and the changes to ship are already in the working tree.
+- `npx tsc --noEmit` is clean and `npm test` is green (the script enforces both and rolls the bump back on failure).
+- npm Trusted Publishing is configured for `jinzd-ai-cli` and `.github/workflows/release.yml`.
+- You have push access to the GitHub remote.
+
+**Step 1 — Write the milestone entry FIRST (Guard A).** Add a one-line entry to the `## 最近里程碑` section of [`CLAUDE.md`](CLAUDE.md) that contains the exact full-width-parenthesis marker `（vX.Y.Z）` for the target version. The script refuses to start without it. (Full narrative goes in `CHANGELOG.md`; this section is just the index line.)
+
+**Step 2 — Run the release script.**
+
+```bash
+# patch: 0.4.209 → 0.4.210  (also accepts: minor / major / an explicit x.y.z)
+node scripts/release.mjs patch -m "fix(scope): one-line commit title"
+
+# preview only — validates guards, writes nothing:
+node scripts/release.mjs patch -m "..." --dry-run
+```
+
+- Do **not** put a `(vX.Y.Z)` suffix in `-m`; the script appends it automatically.
+- On Windows PowerShell, call `node` directly — `npm run release -- -m ...` swallows the `-m` argument.
+
+**What the script does, in order:**
+
+1. **Guard A** — asserts `CLAUDE.md` contains the `（vX.Y.Z）` milestone entry.
+2. Bumps the version in **three** places: `package.json`, `src/core/constants.ts` (`VERSION`), and `CLAUDE.md` (`**当前版本**`).
+3. **Guard B** — re-reads all three files from disk and asserts every bump landed.
+4. **Guard C** — `tsc --noEmit` must be zero-error (rolls the bump back on failure).
+5. `npm test` must pass (rolls the bump back on failure).
+6. Prints the exact file list entering the release commit and blocks if any looks sensitive (`.env`, `*.pem`, `*.key`, `secret`, …). Override consciously with `--allow-sensitive`.
+7. `git add -A` + commit `"<title> (vX.Y.Z)"` (message passed via argv, not shell-interpolated).
+8. Creates an annotated `vX.Y.Z` release tag.
+9. Pushes `main` and the tag. The pinned GitHub Actions workflow verifies the project and publishes to npm through OIDC, without a long-lived npm token.
+
+**Optional flags:** `--dry-run` · `--skip-tests` · `--no-tag` · `--no-push` · `--allow-sensitive`. The old `--no-publish` flag remains an alias for `--no-tag`.
+
+### Which files a release touches
+
+Two groups: what **you** write by hand (the script never touches these, and Guard A refuses to start without them) and what the **script** rewrites (never edit these by hand).
+
+| File | Written by | What changes |
+|---|---|---|
+| `CHANGELOG.md` | **By hand, before releasing** | A new `## [X.Y.Z] - YYYY-MM-DD` section with the full narrative: root cause / fix / tests. This is the only place detail lives |
+| `CLAUDE.md` → `## 最近里程碑` | **By hand, before releasing** | **One** index line at the top, which must carry the full-width marker `（vX.Y.Z）` — this exact line is what Guard A checks |
+| `package.json` | Script | `"version"` |
+| `src/core/constants.ts` | Script | The `VERSION` constant (what `aicli --version` and the help banner actually read — drift here ships a package that reports the wrong version) |
+| `CLAUDE.md` → `**当前版本**` | Script | The version number (a *second*, separate spot from the hand-written milestone line) |
+| `docs/USAGE.md`, `docs/USAGE.zh-CN.md`, `docs/ADVANCED*.md`, `docs/TUTORIAL*.md`, `docs/RECIPES*.md`, `SECURITY.md`, `docs/SECURITY*.md` | Script | Only the **document-header** baseline lines (`> **Version**: vX.Y.Z`, security baseline, `当前 vX.Y.Z`). Deliberately first-match-only — "feature introduced in v0.4.246+" markers in the body must keep their original versions |
+| `dist/` | Script | Built once before the test gate so `dist` matches the new version (the `version-drift` guard compares the build output); `prepublishOnly` builds again from scratch at publish time |
+
+**Guard B only watches the first three** (`package.json` / `constants.ts` / `CLAUDE.md` current version) — it re-reads them from disk after the bump and asserts each one landed. Both historical incidents (`0.4.207`, `0.4.239`) were drift across exactly these three, and both happened by bypassing the script.
+
+**If the change itself touches any of the following, sync it too** (guards will catch these, but knowing up front saves a round):
+
+- Adding/removing a provider, built-in tool, or REPL command → the `docs-drift` guard requires the count markers and tables across all four docs to match
+- Adding a provider → it must be added to the matrix in `tests/unit/providers/quirk-contracts.test.ts`
+- Node minimum version, the `bin` name, or recovery-path wording → covered by the `version-drift` guard
+
+## Documentation
+
+- [`docs/USAGE.md`](docs/USAGE.md) — Complete reference manual (commands, tools, config)
+- [`docs/TUTORIAL.md`](docs/TUTORIAL.md) — Hands-on tutorial, zero to fluent in an hour
+- [`docs/ADVANCED.md`](docs/ADVANCED.md) — Architecture and internals (for developers)
+- [`docs/MIGRATION.md`](docs/MIGRATION.md) — Migration guide from Claude Code, Codex, Claude Desktop, and Cursor
+- [`docs/RECIPES.md`](docs/RECIPES.md) — Practical recipes by scenario
+- [`docs/SECURITY.md`](docs/SECURITY.md) — **Security model, deployment checklist, audit history.** Read before exposing `aicli web` to a network.
+- [`CHANGELOG.md`](CHANGELOG.md) — Per-version change log
+- [`CONTRIBUTING.md`](CONTRIBUTING.md) · [`SUPPORT.md`](SUPPORT.md) · [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) — Community guides
+- [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md) — Licenses for vendored browser assets
+- [`docs/OPEN_SOURCE_CHECKLIST.md`](docs/OPEN_SOURCE_CHECKLIST.md) — Repository-owner launch checklist
+- [Chinese README](README.zh-CN.md) — 中文说明文档
+
+## License
+
+[MIT](LICENSE)