npm - jinzd-ai-cli - Versions diffs - 0.4.104 → 0.4.106 - Mend

jinzd-ai-cli 0.4.104 → 0.4.106

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (42) hide show

package/README.zh-CN.md CHANGED Viewed

@@ -1,448 +1,448 @@
-[English](README.md) | **中文**
-# ai-cli
-> 跨平台 AI 编程助手 — CLI 终端、Web 界面、桌面应用三合一，支持 8 大 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-647%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)
-## 特性亮点
-- **8 大内置 Provider** — Claude、Gemini、DeepSeek、OpenAI、智谱 GLM、Kimi、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）— tree-sitter 持久化索引（TS/JS/TSX/JSX/Python）+ 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），把 26 个内置工具（含 `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) — 实战配方（按场景查）
-## 主要 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)
+[English](README.md) | **中文**
+# ai-cli
+> 跨平台 AI 编程助手 — CLI 终端、Web 界面、桌面应用三合一，支持 8 大 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-647%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)
+## 特性亮点
+- **8 大内置 Provider** — Claude、Gemini、DeepSeek、OpenAI、智谱 GLM、Kimi、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）— tree-sitter 持久化索引（TS/JS/TSX/JSX/Python）+ 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），把 26 个内置工具（含 `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) — 实战配方（按场景查）
+## 主要 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)