[English](README.md) | **中文**

# ai-cli

> 跨平台 AI 编程助手 — CLI 终端、Web 界面、桌面应用三合一，支持 9 大 Provider（含本地 Ollama）与 Agentic 工具调用

[![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-1097%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)

## 特性亮点

- **9 大内置 Provider** — Claude、Gemini、DeepSeek、OpenAI、智谱 GLM、Kimi、**MiniMax（海螺）**、OpenRouter（300+ 模型）、**Ollama**（本地模型，无需 API Key）
- **三种使用方式** — 终端 CLI、浏览器 Web UI（`aicli web`）、Electron 桌面应用
- **Agentic 工具调用** — AI 自主执行 bash 命令、读写文件、搜索代码、抓取网页、运行测试（默认 200 轮，可通过 `config.maxToolRounds` 或 `--max-tool-rounds` 调整，上限 10000）
- **Prompt Caching**（v0.4.70+）— system prompt 拆分稳定/易变两段，Claude 对稳定段启用 `cache_control: ephemeral`，命中时按 10% 计费
- **Unified Diff Patch 编辑**（v0.4.72+）— `edit_file` 支持标准 `@@ -a,b +c,d @@` hunk，大文件多处小改最省 token；容忍 ±200 行漂移与空白差异
- **Anthropic Batches API**（v0.4.73+）— `aicli batch submit/list/status/results/cancel` 包 Message Batches（50% 折扣 + 24 小时窗口），适合离线分析和批量 eval
- **Web UI 会话回放**（v0.4.71+）— 会话列表每项 🎬 按钮打开时间轴回放：消息、工具调用、推理内容、cache-aware token 用量一目了然
- **对话分支**（v0.4.74+）— REPL 内 `/branch list/new/switch/delete/rename/diff/cherry-pick`，Web UI 回放面板每条消息旁 🌿 "fork here" 按钮，任意位置开辟新分支探索不同方向，原对话保持不变；v0.4.81 起所有子命令支持 id / title / 唯一前缀
- **符号索引**（v0.4.76+，C1；v0.4.143 起多语言）— tree-sitter 持久化索引（TS / JS / TSX / JSX / Python / Go / Rust / Java / C/C++）+ 3 个只读 AI 工具（`find_symbol` / `get_outline` / `find_references`）+ `/index status/rebuild/clear`；启动后台增量刷新，`write_file` 后自动 upsert
- **语义代码搜索**（v0.4.77+，C2）— `search_code` AI 工具 + 本地 sentence embedding（`paraphrase-multilingual-MiniLM-L12-v2`，117 MB 一次性下载，384 维，CPU 运行）；支持中英文自然语言查询代码；`/index semantic-rebuild/semantic-clear` 管理
- **MCP Server 模式**（v0.4.84+，E1）— `aicli mcp-serve` 把 aicli 反转为 MCP 服务器（JSON-RPC 2.0 over stdio），把 28 个内置工具（含 `find_symbol` / `search_code` / `run_tests`）输出给 Claude Desktop / Cursor / 任何 MCP 客户端；支持 `--tools` 白名单、`--cwd` 覆盖、`--allow-destructive`
- **Session 敏感数据脱敏**（v0.4.88+）— 统一 redactor 在 session **落盘前**自动替换 `password=` / `api_key` / bearer token / OpenAI key 为 `[REDACTED:*]`；查询文本也走脱敏，secret 不会进 embedding 或日志；`/security status` + `/security scan` 审计
- **类人长期记忆**（v0.4.89+，B4）— 聊天记录语义索引跨 session 可召回 + `recall_memory` AI 工具 + `/memory rebuild/refresh/status/recall/index-clear`；AI 看到"上次"/"之前"/指代不明时自动回忆。复用 C2 的 MiniLM embedder
- **Web UI Memory 面板**（v0.4.90+，B4）— sidebar 新增 🧠 Memory 标签页，跨 session 语义搜索；每条 hit 带 **➕ Inject**（把片段作为 markdown 引用块塞进聊天输入框，用户可在上面继续打字编辑——不是静默注入上下文）和 **↗ Load**（跳转对应 session）；顶部"➕ Inject top 3"一键批量
- **流式工具调用** — 实时流式展示 AI 推理过程和工具调用
- **子代理系统** — 将复杂子任务委派给独立子代理执行
- **深度推理** — Claude Extended Thinking，`/think` 一键切换
- **规划模式** — `/plan` 进入只读规划，AI 先分析后执行，内置死循环检测
- **自动暂停** — 每 10 轮自动暂停，用户可审查进度或重定向 AI
- **MCP 协议** — 接入外部 MCP 服务器，动态发现工具
- **多用户认证** — Web UI 支持多用户密码登录
- **PWA 支持** — Web UI 可安装为桌面/移动应用，支持局域网访问
- **三层级上下文** — 全局 / 项目 / 子目录上下文文件自动注入
- **无头模式** — `aicli -p "提示词"` 用于 CI/CD 管道和脚本
- **44 个 REPL 命令** — 会话管理、检查点、代码审查、安全审查/扫描、对话回退、脚手架、聊天记忆召回、智能模型路由（`/route`）等
- **GitHub Actions CI/CD** — Node 20/22 自动测试 + Release tag 自动发布 npm
- **跨平台** — Windows、macOS、Linux

## 安装

### npm 安装（推荐）

```bash
npm install -g jinzd-ai-cli
```

需要 Node.js >= 20。安装后使用 `aicli` 启动。

### Electron 桌面应用（Windows）

从 [GitHub Releases](https://github.com/jinzhengdong/ai-cli/releases) 下载安装包，无需 Node.js：

| 平台 | 下载 |
|------|------|
| Windows x64 | [`ai-cli-setup.exe`](https://github.com/jinzhengdong/ai-cli/releases/latest) |

### 独立可执行文件

预编译 CLI 二进制（无需 Node.js，约 56 MB）：

| 平台 | 文件 |
|------|------|
| Windows x64 | `ai-cli-win.exe` |
| macOS arm64 | `ai-cli-mac` |
| macOS x64 | `ai-cli-mac-x64` |
| Linux x64 | `ai-cli-linux` |

## 快速开始

### 终端 CLI

```bash
aicli
```

首次运行会进入交互式配置向导，先设置你的身份档案，再选择 Provider 并输入 API Key。身份信息会注入每次 AI 对话。

```
[deepseek] > 你好！帮我分析一下这个项目
[deepseek] > @src/main.ts 审查这个文件有没有 bug
[deepseek] > @screenshot.png 这张图片里有什么？
[deepseek] > /help
```

使用 `@文件路径` 在提示词中引用文件或图片。

### Web UI

```bash
aicli web                    # 在 localhost:3456 启动
aicli web --port 8080        # 自定义端口
aicli web --host 0.0.0.0    # 局域网访问（手机/平板）
```

功能：多 Tab 会话、文件树面板、拖拽/粘贴图片、Prompt 模板库、8 套 DaisyUI 主题、PWA 可安装、键盘快捷键、Diff 语法高亮。

### 用户管理

```bash
aicli user create admin      # 创建用户（启用认证）
aicli user list              # 列出所有用户
aicli user reset-password x  # 重置密码
aicli user delete x          # 删除用户
```

## 支持的 Provider

| Provider | 模型 | 获取 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+ 模型（Claude/GPT/Gemini/Llama/Qwen/Mistral...） | [openrouter.ai](https://openrouter.ai) |
| **智谱清言** | GLM-4, GLM-5 | [open.bigmodel.cn](https://open.bigmodel.cn) |
| **Kimi** | Moonshot, Kimi-K2 | [platform.moonshot.cn](https://platform.moonshot.cn) |
| **Ollama** | 任意本地模型（Llama、Qwen、Gemma、Mistral...） | 无需 API Key — [ollama.com](https://ollama.com) |

也可通过 `customBaseUrls` 配置接入任意 OpenAI 兼容 API。

### Ollama（本地模型）

在自己的硬件上完全本地运行 AI，无需 API Key，无使用费，数据不离开本机。

```bash
# 从 https://ollama.com 安装 Ollama，然后拉取模型：
ollama pull qwen3:4b      # 推荐：工具调用支持好
ollama pull gemma3:4b
ollama pull llama3.1:8b

# 启动 aicli，切换到 Ollama：
aicli
[deepseek] > /provider ollama   # 自动发现已安装的模型
[ollama] > /model               # 从本地模型中选择
```

> **注意**：建议使用 4B 及以上的模型以获得较好的工具调用支持。小模型（<4B）在 MCP 服务器注入大量工具定义时可能无法正常工作。

## 内置工具（Agentic 能力）

AI 在对话中可自主调用 28 个工具：

| 工具 | 安全级别 | 说明 |
|------|---------|------|
| `bash` | 动态判断 | 执行 shell 命令（Windows: PowerShell，Unix: $SHELL） |
| `read_file` | 安全 | 读取文件内容（10 MB 限制，支持图片） |
| `write_file` | 写入 | 创建/覆盖文件（diff 预览 + 确认） |
| `edit_file` | 写入 | 精确字符串替换，模糊匹配提示 + `replaceAll` 全局替换模式 |
| `list_dir` | 安全 | 列出目录内容 |
| `grep_files` | 安全 | 正则搜索文件内容 |
| `glob_files` | 安全 | 按 glob 模式匹配文件 |
| `web_fetch` | 安全 | 抓取网页转 Markdown（防 SSRF） |
| `google_search` | 安全 | Google 自定义搜索 |
| `run_interactive` | 安全 | 运行交互式程序并输入 |
| `run_tests` | 安全 | 自动检测并运行测试（JUnit XML 解析） |
| `spawn_agent` | 安全 | 委派子任务给隔离子代理 |
| `ask_user` | 安全 | 暂停并向用户提问 |
| `save_memory` | 安全 | 跨会话持久化重要信息 |
| `write_todos` | 安全 | 任务拆解，终端实时渲染进度 |
| `save_last_response` | 写入 | 保存 AI 回复到文件 |
| `task_create` | 写入 | 在后台启动命令 |
| `task_list` | 安全 | 列出后台任务及其状态/输出 |
| `task_stop` | 写入 | 停止运行中的后台任务 |
| `git_status` | 安全 | 显示工作区状态（分支、暂存、已修改、未跟踪） |
| `git_diff` | 安全 | 显示文件差异（暂存/未暂存，统计摘要） |
| `git_log` | 安全 | 显示提交历史（单行/完整，按文件/作者过滤） |
| `git_commit` | 写入 | 创建 git 提交（暂存文件、提交信息） |
| `notebook_edit` | 写入 | 编辑 Jupyter notebook 单元格（增/改/删/移动） |
| `find_symbol` | 安全 | 按名称精确查找函数/类/方法定义（C1，tree-sitter 索引） |
| `get_outline` | 安全 | 获取文件的符号大纲（类 → 方法树）（C1） |
| `find_references` | 安全 | 查找符号的所有引用（C1） |
| `search_code` | 安全 | 语义代码搜索（C2，自然语言查询，中英文均可） |

**安全级别**：`安全` = 自动执行，`写入` = diff 预览 + 确认，`破坏性` = 醒目警告 + 确认。

### 文档深入阅读

- [`docs/TUTORIAL.zh-CN.md`](docs/TUTORIAL.zh-CN.md) — **10 节动手教程**，1 小时从零到熟练
- [`docs/USAGE.zh-CN.md`](docs/USAGE.zh-CN.md) — 完整参考手册（所有命令、工具、配置）
- [`docs/ADVANCED.zh-CN.md`](docs/ADVANCED.zh-CN.md) — 架构与内部原理（开发者向）
- [`docs/RECIPES.zh-CN.md`](docs/RECIPES.zh-CN.md) — 实战配方（按场景查）
- [`docs/SECURITY.zh-CN.md`](docs/SECURITY.zh-CN.md) — **安全模型、部署清单、审计历史。** 把 `aicli web` 暴露到网络前请先读。
- [`CHANGELOG.md`](CHANGELOG.md) — 每个版本的更新记录

## 主要 REPL 命令

| 命令 | 说明 |
|------|------|
| `/provider` | 切换 AI Provider |
| `/model` | 切换模型 |
| `/plan` | 进入只读规划模式 |
| `/think` | 切换 Claude 深度推理 |
| `/test` | 自动检测并运行测试 |
| `/review` | AI 代码审查 git diff |
| `/security-review` | 安全漏洞扫描 git diff |
| `/rewind` | 回退对话 + 恢复文件到检查点状态 |
| `/scaffold <描述>` | AI 生成项目骨架 |
| `/init` | AI 生成项目上下文文件 |
| `/compact` | 压缩对话历史 |
| `/session` | 会话管理（new / list / load） |
| `/checkpoint` | 保存/恢复会话检查点 |
| `/fork` | 复制整个会话为新的 session 文件 |
| `/branch` | 在当前 session **内部**创建/切换/删除分支（B2）|
| `/search <关键词>` | 跨会话全文搜索 |
| `/skill` | 管理 Agent 技能包 |
| `/mcp` | 查看 MCP 服务器状态 |
| `/cost` | 显示 Token 用量统计 |
| `/undo` | 撤销上次文件操作 |
| `/doctor` | 健康检查（API Key、MCP、上下文） |
| `/export` | 导出会话为 Markdown 或 JSON |
| `/profile` | 查看/编辑身份档案（AI 跨 Provider 认识你） |
| `/config` | 打开配置向导 |
| `/help` | 显示所有命令 |

**多行输入**：行末加 `\` 续行，或直接粘贴多行内容（自动检测合并）。

在 REPL 中输入 `/help` 查看全部 40 个命令。

## CLI 参数

```bash
aicli [选项]

选项:
  --provider <名称>        设置 AI Provider
  -m, --model <名称>       设置模型
  -p, --prompt <文本>      无头模式：单次提问后退出
  --system <提示词>        覆盖 system prompt
  --json                   输出 JSON（无头模式）
  --output-format <格式>   text | streaming-json (NDJSON)
  --resume <id>            恢复之前的会话
  --allowed-tools <列表>   逗号分隔的工具白名单
  --blocked-tools <列表>   逗号分隔的工具黑名单
  --no-stream              禁用流式输出

子命令:
  aicli web [选项]         启动 Web UI 服务器
  aicli config             运行配置向导
  aicli providers          列出所有 Provider
  aicli sessions           列出最近会话
  aicli user <操作>        管理 Web UI 用户
  aicli batch <操作>       Anthropic Batches API（submit | list | status | results | cancel）
```

### 批处理模式（Anthropic Message Batches）

离线分析、批量 eval 等对延迟不敏感的场景，使用 Batches API 可享 **50% 折扣** + 24 小时处理窗口。

```bash
# 1. 准备 JSONL 输入（每行一个请求）：
#    {"customId":"req-1","messages":[{"role":"user","content":"..."}],"maxTokens":1024}
aicli batch submit prompts.jsonl         # 校验 + 提交 + 本地追踪
aicli batch submit --dry-run prompts.jsonl  # 只解析不提交

aicli batch list                          # 实时查看已追踪批次状态
aicli batch status <id>                   # 单批详情 + 请求计数分解
aicli batch results <id> out.jsonl        # 下载结果（省略文件名则输出到 stdout）
aicli batch cancel <id>                   # 取消进行中的批次
```

本地追踪文件：`~/.aicli/batches.json`（保留最近 200 次提交）。需配置 `AICLI_API_KEY_CLAUDE` 或通过 `aicli config` 设置 Claude API Key。

### 无头模式

```bash
# 单次提问
aicli -p "用一句话解释递归"

# 管道输入
cat src/main.ts | aicli -p "审查这段代码"

# JSON 输出用于脚本
aicli -p "hello" --json

# 流式 JSON (NDJSON)
aicli -p "写一首诗" --output-format streaming-json
```

## 配置

配置文件位于 `~/.aicli/config.json`。运行 `aicli config` 打开交互式向导，或直接编辑：

```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
  }
}
```

### 代理配置（国内用户）

Gemini、Claude 等在国内需要代理：

**方式一：配置文件（持久）**
```json
{
  "proxy": "http://127.0.0.1:10809"
}
```

运行 `aicli config` → 选择 `Configure proxy` 即可配置。

**方式二：环境变量（临时）**
```bash
# Windows
set HTTPS_PROXY=http://127.0.0.1:10809
aicli

# macOS / Linux
HTTPS_PROXY=http://127.0.0.1:10809 aicli
```

### 权限规则（Permission Rules）

控制工具何时需要用户确认。规则按顺序匹配，第一条命中的生效：

```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" }
  ]
}
```

| 字段 | 说明 |
|------|------|
| `tool` | 工具名，`*` 匹配所有工具 |
| `action` | `auto-approve`（跳过确认自动执行）、`deny`（拒绝）、`confirm`（需用户确认） |
| `when.dangerLevel` | 仅当危险级别为 `safe`、`write` 或 `destructive` 时匹配 |
| `when.pathPattern` | 子串匹配工具的 `path` 或 `command` 参数 |

**推荐配置** — 自动放行所有只读工具，减少 y/N 确认次数：

```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" }
  ]
}
```

### 环境变量

| 变量 | 说明 |
|------|------|
| `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` | 智谱 API Key |
| `AICLI_API_KEY_KIMI` | Kimi API Key |
| `AICLI_PROVIDER` | 默认 Provider |
| `AICLI_NO_STREAM` | 设为 `1` 禁用流式输出 |
| `HTTPS_PROXY` / `HTTP_PROXY` | 代理地址 |

### 三层级上下文文件

ai-cli 自动发现并注入上下文文件到 system prompt：

| 层级 | 路径 | 用途 |
|------|------|------|
| 全局层 | `~/.aicli/AICLI.md` | 所有项目通用的个人偏好 |
| 项目层 | `<git-root>/AICLI.md` | 项目级规则（提交到 git 供团队共享） |
| 子目录层 | `<cwd>/AICLI.md` | 当前子目录的特定指令 |

每层也支持 `CLAUDE.md` 作为备选文件名。

### MCP 集成

接入外部 [MCP](https://modelcontextprotocol.io/) 服务器，动态发现工具。配置格式兼容 Claude Desktop：

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"],
      "timeout": 30000
    }
  }
}
```

支持项目级 `.mcp.json`，与全局配置自动合并。

## Web UI 功能

Web UI（`aicli web`）提供功能完备的浏览器界面：

- **多 Tab 会话** — 多个浏览器标签页并行对话
- **文件树面板** — 浏览项目目录，点击插入 `@path` 引用
- **图片上传** — 拖拽或 Ctrl+V 粘贴图片到聊天
- **Prompt 模板库** — CRUD + 标签 + 搜索 + 导入导出
- **8 套主题** — DaisyUI 主题，代码高亮自动联动
- **Diff 语法高亮** — 工具确认对话框中彩色 diff
- **键盘快捷键** — `Esc` 停止、`Ctrl+L` 清屏、`↑↓` 历史
- **导出** — `/export md` 或 `/export json` 浏览器下载
- **PWA** — 可安装为桌面/移动应用
- **局域网访问** — `--host 0.0.0.0` 供手机/平板访问
- **多用户认证** — 密码认证 + 用户数据隔离
- **自动重连** — 心跳 + 指数退避重连

## 测试

```bash
npm test              # 运行全部 515 个测试（30 suites）
npm run test:watch    # 监听模式
```

26 个测试套件覆盖：认证、会话、工具类型与危险级别、权限、输出截断、diff 渲染、edit-file 相似度、错误层级、配置管理、环境变量、Provider 注册、web-fetch、grep-files、Hub 渲染、Hub 讨论、Hub 预设、开发状态、Token 估算、工具注册表预算、并行工具执行、费用追踪、会话工具历史。

## 文档

- [English README](README.md) — English documentation

## License

[MIT](LICENSE)
