# alice-cli
**Repository Path**: andershsueh/alice-cli
## Basic Information
- **Project Name**: alice-cli
- **Description**: 中文友好的通用 LLM Agent Harness — 多 Provider 路由、本地模型优先、自动降级
- **Primary Language**: TypeScript
- **License**: MulanPSL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-31
- **Last Updated**: 2026-08-17
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# ALICE-CLI
🤖 **ALICE** - 基于大语言模型的智能办公助手
[](https://gitee.com/andershsueh/alice-cli/tree/v3.1.2)
[](LICENSE)
[](https://nodejs.org/)
[](https://bun.sh)
## 📖 简介
ALICE 是一个现代化的命令行 AI 助手，支持 Function Calling 工具调用。支持多种 LLM 后端（本地和云端），ALICE 可以帮助您：
- 💬 自然语言对话交互
- 🎨 优雅的终端界面设计
- 🚀 快速响应，流畅体验
- 🔒 支持本地部署，保护隐私
- ⚡ 轻量高效，开箱即用
- 🔄 智能降级，保障可用性
### 🤖 Agent 产品体系
本仓库是一套完整的 Agent 产品体系，目前 **VERONICA** 与 **ALICE** 已上线运行；**DIANA**、**ANDERS** 仍在规划中。
| 名称 | 全称（英文） | 中文意涵 | 角色 | 状态 |
|------|----------------|----------|------|------|
| **VERONICA** | **V**erified **E**mbedded **R**esilient **O**rchestration **N**eural **I**ntelligent **C**ontrol **A**gent | 经验证的嵌入式弹性神经智能控制代理 | daemon 服务，常驻运行、会话与推理编排（`veronica` 命令管理） | ✅ 已上线 |
| **ALICE** | **A**ccelerated **L**ogic **I**nference **C**ore **E**xecutor | 加速逻辑推理核心执行器 | 主 CLI（TUI + 一次性对话），与 VERONICA 配合（`alice` 命令） | ✅ 已上线 |
| **DIANA** | **D**ynamic **I**ntelligent **A**ccessible **N**etworked **A**gent | 动态智能可及网络化代理 | 移动端 Agent，直接与用户快速沟通 | 📋 规划中 |
| **ANDERS** | **A**rchitectural **N**exus **D**isciplined **E**ngineering **R**easoning **S**ystem | 架构枢纽以及纪律化工程推理系统 | 架构师 Agent，专门用于处理复杂代码 | 📋 规划中 |
## ✨ 特性
### 🚀 v0.5.10 亮点（TUI 重构）
**生产级 Ink/React TUI**
- 🖥️ **完整移植 qwen-code TUI**：复用 qwen-code 的生产级 Ink 6 + React 19 终端界面（429 文件），彻底替换原不稳定的 readline+chalk 方案
- 🔌 **Shim 适配层**：通过 `src/shim/` 适配层将 qwen-code TUI 对接 Alice 的 daemon 后端，后端零修改
- ⚡ **useAliceStream**：全新流式适配器，将 Alice daemon 的 `ChatStreamEvent` 无缝映射到 qwen-code TUI 的消息历史系统
- 🎨 **功能丰富**：代码高亮、Markdown 渲染、工具调用可视化、会话管理、Vim 模式、多主题等全部开箱即用
### 🚀 v3.1.2 亮点（可信赖 Code Agent 闭环）
> **产品终局原则：从能力集合走向可信赖的 Code Agent 产品。** v3.1.2 将此前分散的 Analytics、Team、Voice 与 Plugin 能力接入真实用户入口，并为取消、超时、发布产物和测试安全建立可复现合同。
- 🛰️ **Analytics**：`/analytics`（别名 `/otel`）以 async stream 读取本地 OTEL JSONL，支持取消与读取上限，不再整文件载入内存
- 🤝 **Team**：`/team` 完成“consultant + researcher 并发 → bus/artifact → executor 计划 → reviewer”编排；worker 与普通 LLM 流均可随 HTTP/Unix Socket 断连取消
- 🧩 **Plugin**：`/plugins discover/install/list/invoke/uninstall` 完成本地 HMAC 签名插件闭环，权限 `deny`/`ask` fail closed，并发安装与会话 quota 重置均有真实入口回归
- 🎙️ **Voice**：`/voice status/start/stop` 提供诚实的受控降级；平台录音生命周期尚未产品化时不会伪报启动成功
- 🧪 **统一验证**：`bun run verify` 最终通过 30/30 个核心脚本、1085 PASS / 0 FAIL；release smoke 9/9、release contracts 5/5（168/0），并防止陈旧 `dist` 与测试写入真实 HOME
完整变更、边界和迁移说明见 [`release-notes/v3.1.2.md`](release-notes/v3.1.2.md)。
### 🚀 v3.1.1 历史亮点（P2 能力集合）
> `release-notes/v3.1.1.md` 的历史声明是 v3.1.0 基线 608 + P2 新增 565，共 1173 条断言 PASS；这是发布说明中的历史统计，不作为当前复现结果。当前统一 gate 基线为 30 个核心测试脚本、1085 PASS / 0 FAIL。
> 当前验证入口：`bun run typecheck` → `bun run test:core`；最终结果为 30/30 脚本、1085 PASS / 0 FAIL。发布级合同入口为 `bun run verify`：release final dist 仅构建 1 次并完成 smoke 9/9，#004 隔离矩阵 2 次，#005/#019/#020/#021 默认 dist 构建 0 次，release contracts 5/5、168/0；最终耗时约 27.0s。release contracts 只复用带本轮 nonce marker 的构建产物；core 执行前先阻断测试脚本对真实 HOME 派生路径的破坏性 I/O。
**📋 P2 × 4 入口闭环(12 个 PR；产品边界见下)**
| Issue | 标题 | PR 数 | PR 范围 |
|-------|------|-------|--------|
| #18 (IK8MWZ) | OTEL 数据聚合为本地 dashboard | 1 | !17 aggregator + renderer |
| #14 (IK8MWV) | Multi-Agent Team | 5 | !18-!22 teamMessageBus / tool / executor+reviewer / concurrentAgentRunner / workspace |
| #16 (IK8MWX) | Voice 语音输入 | 4 | !23-!26 interface / whisper.cpp / VoiceProcessor / EnergyWakeWord |
| #17 (IK8MWY) | Plugin Marketplace | 3 | !27-!29 manifest+registry / Sandbox / Marketplace+签名+端到端 |
**🔧 4 大新能力**
- 🛰️ **本地 Analytics**:`/analytics`（别名 `/otel`）读取本地 OTEL trace 并渲染统计，async stream 支持 abort 与 limits，已形成可验证本地闭环
- 🤝 **Team staged orchestrator-relay**:`/team` 已接通“调研并发 → bus/artifact → executor 计划 → reviewer”流程；这是编排器代 relay 的工作流，不宣称 worker 通过 teamMessage tool 互聊，也不直接替 worker 改文件
- 🎙️ **Voice 受控降级**:`/voice status/start/stop` 会探测并明确拒绝不可用启动；平台录音生命周期当前未接入，依赖就绪也不会假启动。flag 默认读取 `~/.alice/feature_flags.jsonc`，可由 `ALICE_FEATURE_VOICE_MODE` 覆盖
- 🧩 **本地签名插件**:`/plugins discover/install/list/invoke/uninstall` 完成本地 HMAC 签名声明式插件闭环；不是远程 marketplace，也不是身份认证系统
- ⚠️ **可信赖边界**:Team worker 默认 120s timeout 且可取消；核心测试脚本默认 120s timeout；Voice 平台录音、Plugin 远程市场/身份认证仍不在当前产品承诺内。verify 的 release final dist 只构建一次，避免把重复构建误报为发布闭环
### 🚀 v3.1.0 亮点(结构扩张 · P1 × 9 全部落地)
> 本 release 是 **结构扩张 release**,把 v3.0.1 路线图中的 P1 × 9 全部实现为可用代码。9 个 PR 合并入 main,608 断言全绿(168 基线 + 440 新增),`bun build.ts` 成功。
**📋 P1 × 9 全部落地**
| Issue | 标题 | PR | commit |
|-------|------|-----|--------|
| #9 | Zod v4 运行时 Schema 校验 | [PR !12](https://gitee.com/andershsueh/alice-cli/pulls/12) | `21092fa` |
| #7 | Coordinator 多 Agent 编排(7 角色先行 2 个) | [PR !14](https://gitee.com/andershsueh/alice-cli/pulls/14) | `46b6b60` |
| #8 | TeamMemorySync 跨端记忆同步(协议 + 本地 mock) | [PR !15](https://gitee.com/andershsueh/alice-cli/pulls/15) | `a1f2e72` |
| #11 | OpenTelemetry 三件套 + 可选 OTLP 出口 | [PR !13](https://gitee.com/andershsueh/alice-cli/pulls/13) | `192fea1` |
| #12 | Token Budget 接通 TUI 状态栏 | [PR #8](https://gitee.com/andershsueh/alice-cli/pulls/8) | (v3.0.1 后) |
| #13 | LSP 集成 · TypeScript Language Server 接入 | [PR !16](https://gitee.com/andershsueh/alice-cli/pulls/16) | `4927c63` |
| #10 | ripgrep 子进程替换 glob 性能 | [PR !11](https://gitee.com/andershsueh/alice-cli/pulls/11) | (v3.0.1 后) |
| #20 | karpathy-wiki-ingest bundled skill | [PR !9](https://gitee.com/andershsueh/alice-cli/pulls/9) | (v3.0.1 后) |
| #21 | karpathy-wiki-lint bundled skill | [PR !10](https://gitee.com/andershsueh/alice-cli/pulls/10) | `997903b` |
**🔧 重大架构变更**
- ⚡ **Zod v4 升级**:`^3.23.8` → `^4`(实际 `zod@4.4.3`)。7 处既有 `import { z } from 'zod'` 保持 v3 兼容入口,新代码走 `zod/v4`。5 个高频 builtin 工具切到 zod schema,`toolResultFormatter` 新增 `formatError()` 输出字段路径错误,自修重试上限 2。低风险工具(`getCurrentDateTime` 等)继续走 ajv JSONSchema。
- 📊 **OpenTelemetry 三件套**:`src/observability/{otelSDK, otlpConfig, spans}.ts`。**零 OTEL 全家桶依赖** —— 只硬引 `@opentelemetry/api ^1.9.1`(平台无关),SDK 与 OTLP exporter 全自研。配置门控:enabled=false 零开销;启用后 < 1% overhead。trace 落 `~/.alice/otel/trace.jsonl`(隐私过滤,不含 prompt 文本),OTLP HTTP 出口直接对接 Honeycomb / Datadog。
- 🤖 **Coordinator 多 Agent 编排**:`src/runtime/agent/coordinator/{agentProfile, profileRegistry, spawn, consultantRunner, researcherRunner}.ts` + `concurrentAgentRunner.ts` + `slashHandler.ts`。7 profile 框架(consultant/researcher/executor/writer/reviewer/security/tester),4 个可 spawn —— `/consult` 输出 5-8 条议题,`/research` 命中 `~/.alice/memories/*.md`;permissionGate 按 profile 收敛。
- 🧠 **TeamMemorySync 协议 v1**:`src/services/sync/{syncProtocol, localMock, teamMemorySync}.ts`。`teamId + memory payload + version` envelope,本地 mock 落 `~/.alice/team-sync/staging/.jsonl`,24h 滚动 TTL。远程 endpoint(`POST /v1/teams/{teamId}/memories:push` + `GET :pull`)为 v4.0.0 预留。失败 warn-and-continue,不阻塞本地对话。
- 🌐 **LSP 集成**:`src/services/lsp/{stdioRunner, serverProcess, client, locationFormat, index}.ts` + 3 个 builtin 工具(lspGotoDefinition / lspFindReferences / lspDocumentSymbol)。JSON-RPC 协议跨 Bun/Node runtime,Content-Length 帧协议,SIGTERM 优雅回收。ts ls 缺失时给安装提示而非崩溃。stub server 在 `test-case/fixtures/lsp-stub-server.mjs`(测试用)。
- 🦊 **Token Budget 接通 TUI**:`BudgetUsage` 类型 + `getUsage()` + `budget_update` 事件流。第 8-10 轮起 Footer 显示 `[ctx 78%]`,`nearCompletion` 触发"auto-compact 即将触发"提示。
- 🚀 **ripgrep 替换 glob**:`src/utils/ripgrepRunner.ts`,searchFiles 优先走 `rg --files --glob`,20k 文件级目录 ~800ms → ~50ms。无 rg 自动降级 glob。
- 🛠 **3 个 builtin skill 全员到齐**:`/karpathy-wiki-new`(v3.0.1)、`/karpathy-wiki-ingest`、`/karpathy-wiki-lint`。lint 5 项检查(BROKEN/ORPHAN/NOSUMMARY/NOSTAMP/LOWLINKS)输出 SUMMARY 行机器可读。
**🗺 路线图(按当前真实状态)**
- ✅ **v3.0.1** = P0 × 6(2026 Q3)
- ✅ **v3.1.0** = P1 × 9(2026 Q4)
- ✅ **v3.1.1** = P2 × 4 能力集合落地(2026-08-15)
- ✅ **v3.1.2**(当前 release) = 稳定入口、真实测试、取消链路与发布合同收官(2026-08-16)
- 🔮 **后续周期** = worker tool 互聊、平台录音生命周期、远程插件市场/身份认证与更高等级发布验收
详见 [`release-notes/v3.1.2.md`](release-notes/v3.1.2.md) + [`release-notes/v3.1.1.md`](release-notes/v3.1.1.md) + [`release-notes/v3.1.0.md`](release-notes/v3.1.0.md)
### 🚀 v3.0.1 亮点(结构强化 · 21 项行动)
> 上一 release。结构稳定性建立,P0 × 6 全部落地,4 条验收底线实测达成,`v3.0.1` TAG 2026-08-14 补打。
**📋 21 项 P0/P1/P2 行动清单**
- 🎯 **P0 × 6(全部已合并)**:#1 启动预取(冷启动 < 120ms,PR !2)/ #2 服务层补足(memory + compact,PR !3)/ #3 权限 5 mode(585 例决策,PR !4)/ #4 Feature Flag DCE(PR !5)/ **#5 ★ Workspace Backend 收敛(已完成,PR !6 守卫)** / #19 builtin-skill-new(PR !7)
- ✅ **P1 × 9**:见上方 v3.1.0 章节
- 🔮 **P2 × 4 + #15 挂起**:正式 P2 为 #14 Multi-Agent Team / #16 Voice / #17 Plugin Marketplace / #18 analytics；#15 remoteManagedSettings 独立挂起,不计入四项
- ❌ **#6 IDE Bridge** 按产品原则划掉
**🛠 内置 Skills**(本 release 全员到齐)
- `karpathy-wiki-new` — 一键建 Karpathy Wiki 知识库脚手架(3 目录 + 6 模板)
- `karpathy-wiki-ingest` — 把 raw/ 编译为结构化 wiki 页面(#20 ✅)
- `karpathy-wiki-lint` — 知识库健康检查(5 项检查,#21 ✅)
- 设计:bundled skill 由 `BundledSkillLoader` 暴露 slash command,确定性执行器按需调用;权限与审计由调用方负责,见 [`wiki/内置-Skills.md`](wiki/内置-Skills.md)
**🧹 Obsolete 清理(commit a104d85)**
- 删除 `QWEN.md` + `.github/copilot-instructions.md`(同构第一规则,统一入口到 `AGENTS.md`)
- `CLAUDE.md` 删除航海日志相关 3 段,新增「资源使用 · 无限 Token 模式」段
详见 [`release_note.md`](release_note.md) + [`wiki/结构优化路线图.md`](wiki/结构优化路线图.md)
### 🚀 v0.5.0 亮点
**飞书通道与 VERONICA 网关**
- 📡 **飞书 WebSocket 长连接**：无需公网 URL，本机直连飞书接收消息；支持文本与富文本（post）消息解析
- 🤖 **默认通道**：`defaultChannel: feishu` 时，daemon 启动即建立飞书长连接，`veronica start` 后提示连接状态
- ⌨️ **敲键盘反馈**：收到消息后在用户消息上加「敲键盘」reaction，处理完成后移除
- 🔁 **消息去重**：按 `message_id` 去重，避免飞书重复推送导致回复两次
- 📄 网关设计详见 [Veronica 通道网关设计](raw/docs/veronica通道网关设计.md)
**VERONICA 后台服务（veronica 命令）**
- 常驻 daemon，负责会话、推理编排与通道网关（如飞书）
- 配置 `~/.alice/daemon_settings.jsonc`，支持 `defaultChannel`、飞书 app_id/app_secret（或环境变量 `ALICE_FEISHU_APPID` / `ALICE_FEISHU_APP_SECRET`）
```bash
veronica start # 启动（飞书通道连接成功后提示）
veronica stop # 停止
veronica status # 查看状态（含 defaultChannel、连接状态）
veronica restart # 重启并重新加载配置
```
### 🔧 工具系统（Function Calling）
- **17 个内置工具**（以 `src/tools/builtin/index.ts` 的注册表为准）: 文件操作、系统信息、命令执行、技能加载、任务清单、用户确认、多步推理与 LSP 导航
- `readFile` / `writeFile` / `editFile` - 读取、写入、按行编辑文件
- `listFiles` / `searchFiles` - 列出与搜索文件
- `getCurrentDirectory` / `getGitInfo` / `getCurrentDateTime` - 工作目录、Git 与时间信息
- `executeCommand` - 执行系统命令（带安全确认）
- `ask_user` - 请求用户确认或选择
- `loadSkill` - 按需加载技能指令
- `TodoWrite` / `TodoRead` - 写入与读取会话任务清单
- `SequentialThinking` - 多步推理
- `lspGotoDefinition` / `lspFindReferences` / `lspDocumentSymbol` - TypeScript LSP 导航
- **智能工具调用**: AI 自动决定何时使用哪个工具
- **实时进度展示**: 工具执行状态可视化
- **安全机制**: 危险命令需要用户确认
- **跨平台支持**: Windows/macOS/Linux 全平台兼容
### 核心功能
- **多后端支持**: 支持 LM Studio、Ollama、OpenAI 等多种 LLM 服务
- **智能降级**: 主模型故障时自动切换到最快的备用模型
- **模型测速**: 内置 `--test-model` 工具，一键测试所有模型速度
- **提示词缓存**: 支持 API 端的提示词缓存，降低成本提升速度
- **智能对话**: 基于 LLM 的自然语言理解和生成
- **命令系统**: 内置快捷命令，提升操作效率
- **历史记录**: 支持上下箭头浏览历史输入
- **会话管理**: 自动保存对话上下文，支持会话恢复
- **流式输出**: 实时显示 AI 响应，支持中断
### 主题与个性化
- **主题系统**: 内置 2 个主题（tech-blue、ocean-dark），支持自定义主题
- **热重载**: 修改主题配置文件后自动更新（无需重启）
- **可配置键绑定**: 自定义快捷键映射（支持组合键）
### 会话与导出
- **会话恢复**: 自动创建和保存会话，优雅的退出汇报显示
- **会话导出**: 支持导出为 HTML（含样式）和 Markdown 格式
- **智能提问**: AI 可以主动向用户提问以澄清任务
### 🧠 Skills 技能系统（三阶段渐进式加载）
ALICE 采用 Anthropic 推荐的**渐进式加载**架构，按需加载技能，避免上下文窗口膨胀：
1. **Discovery（启动时）**: 扫描 `~/.agents/skills/` 目录，仅提取每个技能的名称和描述（~100 tokens/skill），注入系统提示词
2. **Instruction（按需）**: 当用户请求匹配某技能时，AI 通过 `loadSkill` 工具加载完整指令
3. **Resource（执行时）**: 技能附带的脚本和文件仅在实际执行时访问
**默认内置 6 个技能**（首次启动自动安装）：
- `find-skills` - 搜索和发现新技能
- `obsidian-markdown` / `json-canvas` / `obsidian-bases` / `obsidian-cli` - Obsidian 笔记集成
- `skill-creator` - 创建自定义技能
**安装更多技能**：
```bash
npx skills add --skill -g
npx skills find # 交互式搜索
```
### 🔌 MCP (Model Context Protocol)
ALICE 支持通过 MCP 连接外部工具服务器，大幅扩展能力：
- 独立配置文件 `~/.alice/mcp_settings.jsonc`
### 视觉体验
- 🎭 炫酷的启动 Banner 动画
- 🌈 主题化彩色设计（可自定义）
- 📊 清晰的信息层级展示
- ⚡ 流畅的打字机效果
## 🚀 快速开始
### 方式一：下载预编译版本（推荐）
直接从 [Releases 页面](https://github.com/AndersHsueh/Alice/releases) 下载适合您系统的版本：
| 操作系统 | 下载文件 | 说明 |
|---------|---------|------|
| Windows x64 | `alice-win-x64.zip` | 适用于 64 位 Windows |
| macOS Intel | `alice-macos-x64.tar.gz` | 适用于 Intel 芯片 Mac |
| macOS Apple Silicon | `alice-macos-arm64.tar.gz` | 适用于 M1/M2/M3 Mac |
| Linux x64 | `alice-linux-x64.tar.gz` | 适用于 64 位 Linux |
**Windows 用户**:
```powershell
# 解压后直接运行
.\alice.exe
```
**macOS / Linux 用户**:
```bash
# 解压
tar -xzf alice-*.tar.gz
# 添加执行权限
chmod +x alice-*
# 运行（可选：移动到系统路径）
sudo mv alice-* /usr/local/bin/alice
# 直接运行
alice
```
### 方式二：从源码构建
### 前置要求
- **Bun**: ≥ 1.0.0(构建工具链;`bun install` / `bun run build`)
- **Node.js**: ≥ 18.0.0(运行 dist 产物)
- **LM Studio**: 用于本地运行大语言模型
- 下载地址: [https://lmstudio.ai/](https://lmstudio.ai/)
- 启动本地服务器（默认端口 1234）
### 安装依赖
```bash
# 克隆仓库
git clone https://github.com/AndersHsueh/Alice.git
cd Alice
# 安装依赖
bun install
```
### 开发模式
```bash
# 启动开发服务（支持键盘输入）
bun run dev
# 跳过启动动画
bun run dev -- --no-banner
```
> ⚠️ **注意**: 不要使用 `bun run dev:watch` 进行交互测试，该模式会拦截 stdin，导致无法接收键盘输入。
### 构建与运行
```bash
# 编译 TypeScript
bun run build
# 运行生产版本
bun start
```
## 📚 使用指南
### 基本命令
启动 ALICE 后，您可以使用以下命令：
| 命令 | 说明 |
|------|------|
| `/help` | 显示帮助信息 |
| `/clear` | 清空对话历史 |
| `/config` | 查看当前配置 |
| `/theme [name]` | 查看/切换主题 |
| `/export [html\|md] [filename]` | 导出对话为 HTML 或 Markdown |
| `/quit` | 退出 ALICE（显示退出汇报） |
| `Ctrl+C` | 强制退出 |
### 命令行参数
| 参数 | 说明 |
|------|------|
| `--no-banner` | 跳过启动动画 |
| `--test-model` | 测试所有配置的模型并显示速度排名 |
```bash
# 跳过启动动画
alice --no-banner
# 测试所有模型速度
alice --test-model
```
### 🔧 工具使用示例
ALICE 支持 Function Calling，AI 可以自动调用工具完成任务：
```bash
# 示例 1: 查询时间
> You: 现在几点了？
[⏰ 获取当前时间] 正在执行...
[✅ 获取当前时间] 执行成功
Alice: 现在是 2026 年 2 月 10 日 21:40，星期二。
# 示例 2: 搜索文件
> You: 这个项目有多少个 TypeScript 文件？
[🔍 搜索文件] 正在搜索 **/*.ts...
[🔍 搜索文件] 找到 25 个文件
Alice: 项目中共有 25 个 TypeScript 文件，主要分布在 src/core、src/ui 等目录。
# 示例 3: 读取文件
> You: 帮我看看 package.json 的内容
[📄 读取文件] 正在读取 package.json...
[✅ 读取文件] 文件读取成功 (1024 bytes)
Alice: 你的项目名称是 alice-cli，版本 0.5.0，主要依赖包括...
# 示例 4: 危险命令（需确认）
> You: 删除 node_modules 文件夹
[⚠️ 危险命令警告]
命令: rm -rf node_modules
确认执行? (y/N): y
[🔧 执行命令] 执行中...
[✅ 执行命令] 命令执行完成
Alice: node_modules 已删除，你可以运行 bun install 重新安装依赖。
```
### 配置危险命令确认
编辑 `~/.alice/settings.jsonc` 中的 `dangerous_cmd` 字段：
```jsonc
{
// true: 危险命令需要确认 (默认，推荐)
// false: 直接执行，不需要确认
"dangerous_cmd": true
}
```
### 配置文件
配置文件位于 `~/.alice/settings.jsonc`（支持注释的 JSON 格式）：
```jsonc
{
// 默认使用的模型
"default_model": "lmstudio-local",
// 系统推荐的最快模型（由 --test-model 自动更新）
"suggest_model": "lmstudio-local",
// 多模型配置列表
"models": [
{
"name": "lmstudio-local",
"provider": "lmstudio",
"baseURL": "http://127.0.0.1:1234/v1",
"model": "qwen3-vl-4b-instruct",
"apiKey": "",
"temperature": 0.7,
"maxTokens": 2000,
"last_update_datetime": null,
"speed": null
},
{
"name": "ollama-local",
"provider": "ollama",
"baseURL": "http://localhost:11434/v1",
"model": "qwen2.5:7b",
"apiKey": "",
"temperature": 0.7,
"maxTokens": 2000,
"last_update_datetime": null,
"speed": null
},
{
"name": "openai-gpt4",
"provider": "openai",
"baseURL": "https://api.openai.com/v1",
"model": "gpt-4",
"apiKey": "${OPENAI_API_KEY}", // 从环境变量读取
"temperature": 0.7,
"maxTokens": 2000,
"last_update_datetime": null,
"speed": null
}
],
// UI 配置
"ui": {
"banner": {
"enabled": true,
"style": "particle"
},
"theme": "tech-blue"
},
// 主题系统（支持自定义主题在 ~/.alice/themes/）
"theme": "tech-blue",
// 键绑定配置
"keybindings": {
"quit": ["ctrl+d", "ctrl+c"],
"submit": ["enter"],
"clear": ["ctrl+u"],
"history_up": ["up"],
"history_down": ["down"]
},
// 提示词缓存（true: 云端缓存 | false: 本地）
"promptCaching": true,
// 工作区配置
"workspace": ".",
// 危险命令确认（true: 执行前需确认 | false: 直接执行）
"dangerous_cmd": true,
// 工具调用最大迭代次数（最小 5，最大 20，超出范围默认 10）
"maxIterations": 10
}
```
#### 支持的 LLM 提供商
ALICE 使用插件式 Provider 系统，支持以下提供商：
| 提供商 | provider 值 | 说明 | Function Calling |
|--------|-------------|------|------------------|
| **LM Studio** | `lmstudio` | 本地运行，默认端口 1234 | ✅ |
| **Ollama** | `ollama` | 本地运行，默认端口 11434 | ✅ |
| **OpenAI** | `openai` | GPT-4/3.5，支持提示词缓存 | ✅ |
| **Anthropic** | `anthropic` 或 `claude` | Claude 3.5/3，长上下文 | ✅ |
| **Google** | `google` 或 `gemini` | Gemini 1.5/2.0，多模态 | ✅ |
| **Mistral** | `mistral` | Mistral Large/Medium | ✅ |
| **Azure OpenAI** | `azure` | Azure 托管的 OpenAI | ✅ |
| **自定义** | `custom` | 任何兼容 OpenAI API 的服务 | ✅ |
**新特性**：
- 🔌 插件式注册，可动态添加新 Provider
- 📊 内置模型元数据（定价、能力、上下文窗口）
- ⚙️ 细粒度配置（每个 Provider 独立配置）
#### 环境变量配置
为了安全，建议将 API Key 存储在环境变量中：
```bash
# macOS / Linux
export OPENAI_API_KEY="sk-xxxxx"
export ANTHROPIC_API_KEY="sk-ant-xxxxx"
export GOOGLE_API_KEY="xxxxx"
export MISTRAL_API_KEY="xxxxx"
export AZURE_OPENAI_KEY="xxxxx"
# Windows
set OPENAI_API_KEY=sk-xxxxx
set ANTHROPIC_API_KEY=sk-ant-xxxxx
```
在配置文件中使用 `${VAR_NAME}` 格式引用环境变量：
```jsonc
{
"apiKey": "${OPENAI_API_KEY}"
}
```
#### Provider 特有配置
部分 Provider 支持额外配置：
```jsonc
{
"name": "claude-sonnet",
"provider": "anthropic",
"model": "claude-3-5-sonnet-20241022",
// Anthropic 特有配置
"providerConfig": {
"anthropic": {
"anthropicVersion": "2023-06-01",
"topK": 40
}
}
}
```
```jsonc
{
"name": "gemini-pro",
"provider": "google",
"model": "gemini-1.5-pro",
// Google 特有配置
"providerConfig": {
"google": {
"safetySettings": [
{
"category": "HARM_CATEGORY_HARASSMENT",
"threshold": "BLOCK_MEDIUM_AND_ABOVE"
}
]
}
}
}
```
#### 智能降级机制
ALICE 内置智能降级功能：
- 当 `default_model` 连接失败时，自动切换到 `suggest_model`
- `suggest_model` 由 `--test-model` 命令自动选择最快的模型
- 降级时会显示友好提示，建议用户重新测速
```
⚠️ 主模型 (openai-gpt4) 连接失败，已自动切换到备用模型 (ollama-local)
💡 提示：运行 'alice --test-model' 重新测速并更新推荐模型
```
### 系统提示词
系统提示词位于 `~/.alice/system-prompt.txt`，您可以自定义 AI 的行为和角色。
## 🏗️ 技术架构
### 技术栈
- **运行时**: Node.js (ESM)
- **语言**: TypeScript
- **UI 框架**: [Ink](https://github.com/vadimdemedes/ink) (React for CLI)
- **HTTP 客户端**: Axios
- **终端美化**: chalk, figlet, gradient-string
### 项目结构
目录与模块职责详见根目录 **[DEVELOPMENT_STRUCTURE.md](DEVELOPMENT_STRUCTURE.md)**，以下为简要结构：
```
alice-cli/
├── src/
│ ├── index.tsx # 入口文件（TUI 模式 + -p 一次性模式）
│ ├── ui/ # qwen-code TUI（Ink 6 + React 19，完整复用）
│ │ ├── AppContainer.tsx # 主 TUI 容器
│ │ ├── components/ # 终端 UI 组件（消息、工具调用、对话框等）
│ │ ├── hooks/ # TUI 专用 Hooks
│ │ ├── contexts/ # React Context（按键、会话、主题等）
│ │ ├── commands/ # /help /model /clear 等斜杠命令
│ │ └── themes/ # 内置主题
│ ├── shim/ # 适配层（qwen-code → Alice daemon）
│ │ ├── qwen-code-core.ts # @qwen-code/qwen-code-core 类型桩
│ │ └── hooks/
│ │ └── useAliceStream.ts # 替代 useGeminiStream，接入 DaemonClient
│ ├── daemon/ # VERONICA 后台服务
│ ├── core/ # 核心逻辑（命令注册、扩展等）
│ ├── tools/ # 工具系统（builtin、executor、MCP 等）
│ ├── utils/ # 工具函数（daemonClient、config 等）
│ ├── types/ # 全局类型定义
│ └── scripts/ # 独立脚本（test-model 等）
├── dist/ # 构建输出
└── package.json
```
## 🎨 设计理念
### 视觉风格
- **主色调**: 科技蓝 (#00D9FF)
- **辅助色**: 渐变紫 (#B030FF → #00D9FF)
- **设计原则**: 极简、现代、高效
### 交互体验
- ⚡ 快速响应，避免卡顿
- 💡 清晰的状态反馈
- 🎯 直观的错误提示
- ⌨️ 完善的键盘操作
## 🛠️ 开发指南
### ESM 模块系统
本项目使用 ESM 模块，注意事项：
```typescript
// ✅ 导入时必须包含 .js 扩展名
import { foo } from './utils.js';
// ❌ 错误的导入方式
import { foo } from './utils';
```
### 调试技巧
```bash
# 查看详细日志
DEBUG=* bun run dev
# 清理构建产物
bun run clean
```
### 代码规范
- 使用 async/await 处理异步操作
- 组件文件使用 `.tsx`，逻辑文件使用 `.ts`
- 遵循 TypeScript 严格模式
- 函数组件优先，使用 React Hooks
## 📋 开发路线图
### MVP 阶段 (当前)
- [x] 基础聊天界面
- [x] LLM API 集成
- [x] 启动 Banner 动画
- [x] 命令历史记录
- [x] 配置管理系统
- [x] 多 LLM 后端支持（LM Studio、Ollama、OpenAI 等）
- [x] 智能降级机制
- [x] 模型测速工具（--test-model）
- [x] 提示词缓存支持
- [x] 主题系统（内置 2 个主题，支持热重载）
- [x] 键绑定系统（可配置快捷键）
- [x] 会话导出（HTML/Markdown）
- [x] 智能提问（ask_user 工具）
- [x] 会话恢复基础（自动创建/保存会话，退出汇报）
- [x] 流式输出优化（完整版）
### 近期计划
- [ ] 会话树结构（JSONL + 分支支持）
- [ ] LLM 抽象层优化（更多提供商）
- [ ] 工具拦截机制（事件驱动）
### 未来计划
- [x] 完整的会话恢复（--continue/--resume/--session 参数）
- [x] 组件化 UI 架构（5 个内置组件）
- [x] MCP (Model Context Protocol) 支持
- [x] Skills 技能系统（三阶段渐进式加载）
- [x] 工具调用迭代次数可配置
- [ ] Overlay 系统（浮层组件）
- [ ] 扩展系统（Extension API）
- [ ] sudo 密码管理
## 🤝 贡献指南
欢迎提交 Issue 和 Pull Request！
### 开发流程
1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request
## 📄 许可证
本项目采用木兰宽松许可证第2版(MulanPSL2) - 详见 [LICENSE](LICENSE) 文件
## 🙏 致谢
- **[Anthropic](https://www.anthropic.com/)** - 技能渐进式加载（Discovery → Instruction → Resource）等设计思想参考
- **[qwen-code](https://github.com/QwenLM/qwen-code)** - TUI 层完整复用（Ink 6 + React 19 终端界面），并通过 shim 适配层对接 Alice daemon 后端
- **[OpenClaw](https://github.com/open-claw/OpenClaw)** - 飞书等通道的网关设计参考（长连接、无需公网）
- [Ink](https://github.com/vadimdemedes/ink) - 优秀的 CLI UI 框架
- [LM Studio](https://lmstudio.ai/) - 本地大语言模型运行环境
- [GitHub Copilot](https://github.com/features/copilot) - 设计灵感来源
## 📮 联系方式
- **作者**: Anders
- **项目地址**: [https://github.com/AndersHsueh/Alice](https://github.com/AndersHsueh/Alice)
- **问题反馈**: [Issues](https://github.com/AndersHsueh/Alice/issues)
---
Made with ❤️ by Anders