# alice-cli

**Repository Path**: andershsueh/alice-cli

## Basic Information

- **Project Name**: alice-cli
- **Description**: 中文友好的通用 LLM Agent Harness — 多 Provider 路由、本地模型优先、自动降级
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-31
- **Last Updated**: 2026-07-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# alice-cli

> **中文友好的通用 LLM Agent Harness**
>
> Multi-provider LLM agent harness with local-model priority, automatic degradation, and routing as a first-class tool.

[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![Runtime](https://img.shields.io/badge/runtime-Bun-f9f1e1.svg)](https://bun.sh)
[![Language](https://img.shields.io/badge/TypeScript-strict-blue.svg)](https://www.typescriptlang.org/)

## 为什么是 alice-cli？

市面上的 AI 编程工具**把"用哪家模型"和"用什么工具"绑死了**——用 Claude Code 就只能调 Anthropic，用 Copilot 就只能调 OpenAI。

我们不信这个。**alice-cli 把"模型选择"做成一个一等公民**：

- **主控 / 规划 / 复杂任务** → 强模型（如 Claude / GLM / Kimi）
- **文档读写 / 日志整理 / 重复劳动** → 本地小模型（Qwen3-4B / Phi / MLX，零成本零延迟）
- **批量执行 / 工具调用** → 便宜快模型（DeepSeek-Flash / GLM-Flash）
- **任意环节崩了** → 自动降级到备胎，**用户不感知**

## 核心设计

### Router 是工具，不是配置项
模型在处理请求时**自己调用 `select_model(task, constraints)` 这个 tool** 来决定走哪条路。
这让路由决策：
- **可被审计、可被记录、可被用户看到**
- **用户可 override**："这个任务用 X 模型"
- **可学习**：哪类任务哪个模型表现好，Router 自己会学

### Provider Adapter 把协议差异吞掉
`Anthropic`、`OpenAI-compatible (DeepSeek/Qwen/GLM/Kimi)`、`Gemini`、`本地 MLX`……每家 function calling 格式不一样，**Adapter 层统一掉**，上层只看到一种 message 格式。

### Harness 思想
学自 Anthropic Claude Code 的 `Tool.ts` / `QueryEngine.ts`：
- **Tool 是能力对象**，不是函数
- **默认危险，显式声明安全**
- **Loop 是状态机**，每次推进一个 turn

## 路线图

- [x] v0.1.0 骨架：Provider 接口 + 最小 Loop + 项目脚手架
- [ ] v0.2.0 Anthropic + OpenAI-compatible 双 Provider 跑通端到端
- [ ] v0.3.0 Router（规则版）+ 本地 MLX 接入
- [ ] v0.4.0 Tool 系统（file_read / file_write / bash / grep / glob）
- [ ] v0.5.0 权限系统（规则 + hook + classifier）
- [ ] v0.6.0 上下文压缩（autoCompact + 9 段式摘要）
- [ ] v0.7.0 MCP 客户端
- [ ] v0.8.0 Subagent / Worktree 隔离
- [ ] v0.9.0 TUI（基于 Ink）
- [ ] v1.0.0 第一个稳定版

## 安装

```bash
# 需要 Bun >= 1.3
curl -fsSL https://bun.sh/install | bash

# 克隆
git clone https://gitee.com/andershsueh/alice-cli.git
cd alice-cli
bun install
```

## 使用

```bash
# 跑起来
bun start

# 测连通性
bun start --ping
```

> **当前状态（v0.1.0）**：仅有骨架，Provider 还没实现。下一个版本会接入真实模型。

## 协议

Apache-2.0。详情见 [LICENSE](LICENSE)。

## 致谢

- **Anthropic Claude Code** — Harness 设计的灵感来源（详见 [docs/design-notes.md](docs/design-notes.md) 待写）
- **[`gitee-cli`](https://gitee.com/andershsueh/gitee-cli)** — 本项目使用的 Gitee 操作 CLI
- 所有站在巨人肩膀上的开源项目