English | 中文

ai-cli

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

特性亮点

• 10 大内置 Provider — Claude、Gemini、DeepSeek、OpenAI、智谱 GLM、Kimi、Qwen、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），把 30 个内置工具（含 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.md、Claude 兼容 CLAUDE.md、Codex 兼容 AGENTS.md 及 override 文件
• 无头模式 — aicli -p "提示词" 用于 CI/CD 管道和脚本
• 48 个 REPL 命令 — 会话管理、检查点、代码审查、安全审查/扫描、对话回退、脚手架、聊天记忆召回、智能模型路由（/route）等
• GitHub Actions CI/CD — Node 20/22 自动测试 + Release tag 自动发布 npm
• 跨平台 — Windows、macOS、Linux

安装

npm 安装（推荐）

npm install -g jinzd-ai-cli

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

Electron 桌面应用（Windows）

从 GitHub Releases 下载安装包，无需 Node.js：

| 平台 | 下载 | |------|------| | Windows x64 | ai-cli-setup.exe |

独立可执行文件

预编译 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

aicli

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

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

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

Web UI

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

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

用户管理

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 | | Gemini | 2.5 Pro, 2.5 Flash | aistudio.google.com | | DeepSeek | deepseek-v4-flash（默认）, deepseek-v4-pro | platform.deepseek.com | | OpenAI | GPT-5.4, GPT-5, GPT-4.1, o3, o4-mini | platform.openai.com | | OpenRouter | 300+ 模型（Claude/GPT/Gemini/Llama/Qwen/Mistral...） | openrouter.ai | | Zhipu（智谱） | GLM-4, GLM-5 | open.bigmodel.cn | | Kimi | Kimi K2.6, K2.5, K2 Thinking | platform.moonshot.cn | | Qwen | qwen-plus, qwen-max, qwen-turbo, qwen-coder-plus | bailian.console.aliyun.com | | MiniMax | MiniMax-M3（默认）、M2.7、M2.5、M2.1、M2 | platform.minimaxi.com | | Ollama | 任意本地模型（Llama、Qwen、Gemma、Mistral...） | 无需 API Key — ollama.com |

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

Ollama（本地模型）

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

# 从 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 在对话中可自主调用 30 个工具：

| 工具 | 安全级别 | 说明 | |------|---------|------| | 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） | | web_search | 安全 | 无需 Key 的 Bing/Google 网页搜索，弱结果自动降级 | | google_search | 安全 | Google 自定义搜索 | | run_interactive | 写入 | 运行交互式程序并输入；任意可执行程序均需确认 | | run_tests | 安全 | 自动检测并运行测试（JUnit XML 解析） | | spawn_agent | 安全 | 委派子任务给命名隔离 agent（agent: explorer/worker/reviewer/security/tester） | | 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，自然语言查询，中英文均可） | | recall_memory | 安全 | 从历史聊天会话中语义召回相关片段 |

安全级别：安全 = 自动执行，写入 = 需要确认（文件编辑工具还会显示 diff 预览），破坏性 = 醒目警告 + 确认。

文档深入阅读

• docs/TUTORIAL.zh-CN.md — 10 节动手教程，1 小时从零到熟练
• docs/USAGE.zh-CN.md — 完整参考手册（所有命令、工具、配置）
• docs/ADVANCED.zh-CN.md — 架构与内部原理（开发者向）
• docs/RECIPES.zh-CN.md — 实战配方（按场景查）
• docs/SECURITY.zh-CN.md — 安全模型、部署清单、审计历史。 把 aicli web 暴露到网络前请先读。
• 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 查看全部 48 个命令。

CLI 参数

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 小时处理窗口。

# 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。

无头模式

# 单次提问
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 打开交互式向导，或直接编辑：

{
  "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 等在国内需要代理：

方式一：配置文件（持久）

{
  "proxy": "http://127.0.0.1:10809"
}

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

方式二：环境变量（临时）

# Windows
set HTTPS_PROXY=http://127.0.0.1:10809
aicli

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

权限规则（Permission Rules）

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

{
  "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 确认次数：

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

Auto Mode

/auto on|off|status 会开启会话级规则分类器，用来减少确认疲劳，但不会扩大 /yolo 的边界：/yolo 仍然只跳过 write 确认，destructive 仍需确认。

Auto Mode 可自动通过低风险动作，例如 workspace/temp 根目录内的显式写入、只读 HTTP 工具、非 force 的普通 git push、已经写在 package.json 或 lockfile 中的依赖安装。它会拒绝 curl | bash、force push、疑似 secret 外传；生产部署、数据库迁移、IaC destroy、IAM/token/key/权限变更、第三方 agent loop 默认进入确认。

Auto Mode 不会被项目配置静默开启。用 /permissions recently-denied 查看最近被 Auto Mode 拒绝的动作，用 /permissions clear-denied 清空本会话列表。

Agent Team

spawn_agent 现在支持命名角色，来源包括内置角色以及 ~/.aicli/agents/、.aicli/agents/ 下的 JSON 配置。内置角色包括 explorer、worker、reviewer、security、tester。agent 配置可声明 description、provider/model、system instructions、allowed/blocked tools、permission profile、max tool rounds、context policy；这些配置只能在继承的子代理安全边界内继续收窄，不能越权放宽。使用 /agent list|switch|stop|summary 查看角色和最近子代理运行记录。

可信 Hooks 生命周期

旧版 preToolExecution / postToolExecution 仍然兼容。新版生命周期 hooks 配置在 hooks.events.<EventName> 下，通过 AICLI_HOOK_EVENT_JSON 接收 JSON 事件；命令 stdout 如果输出 JSON，ai-cli 会读取 allow、deny、ask、warning 或 warnings 等决策。

{
  "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 }
    }
  }
}

支持的事件包括 SessionStart、UserPromptSubmit、PreToolUse、PermissionRequest、PostToolUse、PreCompact、PostCompact、Stop、SubagentStart、SubagentStop。source: "project" 的 hook 默认不会执行，必须通过 /hooks trust <id> 写入本地信任记录；命令内容变化后 hash 会变化，需要重新信任。

使用 /hooks list、/hooks inspect <id>、/hooks trust <id>、/hooks untrust <id>、/hooks disable 管理 hooks。/status、/security status 和 Web 状态栏会显示待信任项目 hooks 数量。

环境变量

| 变量 | 说明 | |------|------| | 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_API_KEY_QWEN | Qwen / Alibaba Cloud API Key | | AICLI_API_KEY_MINIMAX | MiniMax API Key | | AICLI_PROVIDER | 默认 Provider | | AICLI_NO_STREAM | 设为 1 禁用流式输出 | | HTTPS_PROXY / HTTP_PROXY | 代理地址 |

三层级上下文文件

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

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

每层按以下优先级加载第一个非空文件：AICLI.override.md → AGENTS.override.md → AICLI.md → CLAUDE.md → AGENTS.md。AICLI.md 是 ai-cli 原生文件名；CLAUDE.md 和 AGENTS.md 分别用于兼容 Claude Code 与 Codex 风格项目。

MCP 集成

接入外部 MCP 服务器，动态发现工具。配置格式兼容 Claude Desktop：

{
  "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 供手机/平板访问
• 多用户认证 — 密码认证 + 用户数据隔离
• 自动重连 — 心跳 + 指数退避重连

测试

npm test              # 运行离线回归测试
npm run test:watch    # 监听模式

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

发布（版本提升 → Git Tag → npm 可信发布）

给贡献者与 AI 模型：整个发布流程一律走 scripts/release.mjs，切勿手动 bump 版本号或自己跑 npm publish。 曾经手工 publish 的 0.4.207 装上后 --version 报错版本号，被迫补发 0.4.208 对齐——脚本的四道守卫就是为拦住这类事故而存在。

前置条件

• 当前在 main 分支，待发布的改动已在工作区。
• npx tsc --noEmit 零错误、npm test 全绿（脚本会强制校验，失败自动回滚版本号）。
• 已为 jinzd-ai-cli 和 .github/workflows/release.yml 配置 npm Trusted Publishing。
• 有 GitHub 远端推送权限。

第 1 步 —— 先写里程碑条目（Guard A）。 在 CLAUDE.md 的 ## 最近里程碑 一节加一行，条目中必须含目标版本的全角括号标记 （vX.Y.Z），否则脚本拒绝启动。（完整叙事写进 CHANGELOG.md，本节只留一行式索引。）

第 2 步 —— 运行发布脚本。

# patch：0.4.209 → 0.4.210（也支持 minor / major / 显式 x.y.z）
node scripts/release.mjs patch -m "fix(scope): 一句话 commit 标题"

# 仅预览，只校验守卫、不改任何文件：
node scripts/release.mjs patch -m "..." --dry-run

• -m 里不要自带 (vX.Y.Z) 后缀，脚本会自动追加。
• Windows PowerShell 下请直接用 node 调用——npm run release -- -m ... 会把 -m 参数吞掉。

脚本执行顺序：

1. Guard A —— 断言 CLAUDE.md 已含 （vX.Y.Z） 里程碑条目。
2. bump 三处版本号：package.json、src/core/constants.ts（VERSION）、CLAUDE.md（**当前版本**）。
3. Guard B —— 从磁盘重读这三处，逐一断言都真的改到了。
4. Guard C —— tsc --noEmit 必须零错误（失败则回滚版本号）。
5. npm test 必须全绿（失败则回滚版本号）。
6. 打印进入发布 commit 的完整文件清单，若含疑似敏感文件（.env、*.pem、*.key、secret…）直接拦下，确认无误加 --allow-sensitive。
7. git add -A + commit "<标题> (vX.Y.Z)"（消息走 argv 传参，不经 shell 拼接）。
8. 创建带注释的 vX.Y.Z release tag。
9. 推送 main 和 tag；固定到完整 SHA 的 GitHub Actions 工作流会完成验证，并通过 OIDC 发布到 npm，无需长期 npm token。

可选 flag： --dry-run · --skip-tests · --no-tag · --no-push · --allow-sensitive。旧的 --no-publish 仍作为 --no-tag 的兼容别名。

一次发版到底改哪些文件

分两类：你手写的（脚本不管，缺了 Guard A 直接拒绝启动）和脚本自动改的（不要手动动）。

| 文件 | 谁改 | 改什么 | |---|---|---| | CHANGELOG.md | 手写（发版前） | 新增 ## [X.Y.Z] - YYYY-MM-DD 段落，写完整叙事：根因 / 修法 / 测试。这是唯一的详细记录处 | | CLAUDE.md → ## 最近里程碑 | 手写（发版前） | 顶部加一行索引，必须含全角括号标记 （vX.Y.Z）——Guard A 查的就是这一行 | | package.json | 脚本 | "version" | | src/core/constants.ts | 脚本 | VERSION 常量（aicli --version 与 help banner 读的是它，脱同步会发出"装了新版报旧版号"的包） | | CLAUDE.md → **当前版本** | 脚本 | 版本号（与上面手写的里程碑行是两处，别混） | | docs/USAGE.md、docs/USAGE.zh-CN.md、docs/ADVANCED*.md、docs/TUTORIAL*.md、docs/RECIPES*.md、SECURITY.md、docs/SECURITY*.md | 脚本 | 仅文档头部的版本基线行（> **版本**：vX.Y.Z、文档安全基线、当前 vX.Y.Z）。刻意只替换首个匹配——正文里 v0.4.246+ 这类"功能引入版本"标记必须保持原值 | | dist/ | 脚本 | 测试前先 build 一次让 dist 与新版本对齐（version-drift 守卫拿构建产物比对），publish 时 prepublishOnly 再全新构建一次 |

Guard B 只盯前三处（package.json / constants.ts / CLAUDE.md 当前版本）——bump 后从磁盘重读逐一断言。历史上 0.4.207 和 0.4.239 两次事故都是这三处脱同步，且都因为绕开了脚本。

改动本身若涉及以下内容，别忘了同步（有守卫会红，但先想到更省一轮）：

• 新增/删除 provider、内置工具、REPL 命令 → docs-drift 守卫要求四份文档的计数标记与表格同步
• 新增 provider → 必须加进 tests/unit/providers/quirk-contracts.test.ts 的矩阵
• Node 版本下限、bin 名称、恢复路径文案 → version-drift 守卫覆盖

文档

• English README — English documentation
• 贡献指南 · 支持指南 · 行为准则
• 第三方许可证声明
• 开源前检查清单

License

MIT