jinzd-ai-cli 0.4.42 → 0.4.44

package/README.md

@@ -1,388 +1,388 @@
-**English** | [中文](README.zh-CN.md)
-
-# ai-cli
-
-> 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-brightgreen)](https://nodejs.org)
-[![Tests](https://img.shields.io/badge/tests-343%20passing-brightgreen)]()
-[![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 8 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
-
-- **8 Built-in Providers** — Claude, Gemini, DeepSeek, OpenAI, Zhipu GLM, Kimi, 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 (up to 25 rounds)
-- **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
-- **Headless Mode** — `ai-cli -p "prompt"` for CI/CD pipelines and scripting
-- **40 REPL Commands** — Session management, checkpointing, code review, security review, rewind, scaffolding, and more
-- **GitHub Actions CI/CD** — Automated testing on Node 20/22 + npm publish on release tags
-- **Cross-Platform** — Windows, macOS, Linux
-
-## Installation
-
-### npm (recommended)
-
-```bash
-npm install -g jinzd-ai-cli
-```
-
-Requires Node.js >= 20. 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:3456
-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-Chat (V3), Reasoner (R1) | [platform.deepseek.com](https://platform.deepseek.com) |
-| **OpenAI** | GPT-5.4, GPT-4o, 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** | Moonshot, Kimi-K2 | [platform.moonshot.cn](https://platform.moonshot.cn) |
-| **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 19 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) |
-| `google_search` | safe | Google Custom Search API |
-| `run_interactive` | safe | Run interactive programs with stdin input |
-| `run_tests` | safe | Auto-detect and run project tests (JUnit XML parsing) |
-| `spawn_agent` | safe | Delegate subtasks to isolated child agents |
-| `ask_user` | safe | Pause and ask the user a question |
-| `save_memory` | safe | Persist important info across sessions |
-| `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 |
-
-**Safety levels**: `safe` = auto-execute, `write` = diff preview + confirmation, `destructive` = prominent warning + confirmation.
-
-## Key REPL Commands
-
-| Command | Description |
-|---------|-------------|
-| `/provider` | Switch AI provider |
-| `/model` | Switch model |
-| `/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` | Branch conversation from current point |
-| `/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 |
-
-**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 40 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
-```
-
-### 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 |
-
-**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_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/AICLI.md` | Personal preferences across all projects |
-| Project | `<git-root>/AICLI.md` | Project rules (commit to git for team sharing) |
-| Subdirectory | `<cwd>/AICLI.md` | Directory-specific instructions |
-
-Also supports `CLAUDE.md` as an alternative filename at each layer.
-
-### 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              # Run all 343 tests
-npm run test:watch    # Watch mode
-```
-
-21 test suites covering: authentication, sessions, tool types & danger levels, permissions, output truncation, diff rendering, edit-file similarity, error hierarchy, config management, env loading, provider registry, web-fetch, grep-files, hub renderer, hub discussion, hub presets, dev-state.
-
-## Documentation
-
-- [Chinese README](README.zh-CN.md) — 中文说明文档
-
-## License
-
-[MIT](LICENSE)
+**English** | [中文](README.zh-CN.md)
+
+# ai-cli
+
+> 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-brightgreen)](https://nodejs.org)
+[![Tests](https://img.shields.io/badge/tests-343%20passing-brightgreen)]()
+[![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 8 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
+
+- **8 Built-in Providers** — Claude, Gemini, DeepSeek, OpenAI, Zhipu GLM, Kimi, 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 (up to 25 rounds)
+- **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
+- **Headless Mode** — `ai-cli -p "prompt"` for CI/CD pipelines and scripting
+- **40 REPL Commands** — Session management, checkpointing, code review, security review, rewind, scaffolding, and more
+- **GitHub Actions CI/CD** — Automated testing on Node 20/22 + npm publish on release tags
+- **Cross-Platform** — Windows, macOS, Linux
+
+## Installation
+
+### npm (recommended)
+
+```bash
+npm install -g jinzd-ai-cli
+```
+
+Requires Node.js >= 20. 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:3456
+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-Chat (V3), Reasoner (R1) | [platform.deepseek.com](https://platform.deepseek.com) |
+| **OpenAI** | GPT-5.4, GPT-4o, 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** | Moonshot, Kimi-K2 | [platform.moonshot.cn](https://platform.moonshot.cn) |
+| **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 19 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) |
+| `google_search` | safe | Google Custom Search API |
+| `run_interactive` | safe | Run interactive programs with stdin input |
+| `run_tests` | safe | Auto-detect and run project tests (JUnit XML parsing) |
+| `spawn_agent` | safe | Delegate subtasks to isolated child agents |
+| `ask_user` | safe | Pause and ask the user a question |
+| `save_memory` | safe | Persist important info across sessions |
+| `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 |
+
+**Safety levels**: `safe` = auto-execute, `write` = diff preview + confirmation, `destructive` = prominent warning + confirmation.
+
+## Key REPL Commands
+
+| Command | Description |
+|---------|-------------|
+| `/provider` | Switch AI provider |
+| `/model` | Switch model |
+| `/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` | Branch conversation from current point |
+| `/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 |
+
+**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 40 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
+```
+
+### 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 |
+
+**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_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/AICLI.md` | Personal preferences across all projects |
+| Project | `<git-root>/AICLI.md` | Project rules (commit to git for team sharing) |
+| Subdirectory | `<cwd>/AICLI.md` | Directory-specific instructions |
+
+Also supports `CLAUDE.md` as an alternative filename at each layer.
+
+### 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              # Run all 343 tests
+npm run test:watch    # Watch mode
+```
+
+21 test suites covering: authentication, sessions, tool types & danger levels, permissions, output truncation, diff rendering, edit-file similarity, error hierarchy, config management, env loading, provider registry, web-fetch, grep-files, hub renderer, hub discussion, hub presets, dev-state.
+
+## Documentation
+
+- [Chinese README](README.zh-CN.md) — 中文说明文档
+
+## License
+
+[MIT](LICENSE)