技术文档

Angles Code CLI 的完整技术参考：架构、安装、构建、配置、Provider、工具命令、系统提示与安全策略。

概述 #

Angles Code CLI 是一个基于终端的 agentic 编码助手，用 Rust 编写，作为单二进制分发。它把 LLM 变成一个能在你的文件系统、终端、Git 仓库里真正干活的 agent——通过一组 angles-* 工具命令操作环境，配合可配置的审批策略在自主与安全之间平衡。

架构 #

源码组织为 9 个 Rust 模块，职责清晰、单一：

仓库结构：

angles-cli/
├── src/
│   ├── main.rs          # 入口 & 命令路由
│   ├── cli.rs           # Clap CLI 定义
│   ├── config.rs        # 配置 load/save/display
│   ├── provider.rs      # 11 provider 注册表
│   ├── gateway.rs       # TUI 向导 (dialoguer)
│   ├── instructions.rs  # 系统提示模板 (handlebars)
│   ├── api.rs           # API client + 流式 + 工具循环
│   ├── search.rs        # 搜索 URL 构造
│   └── tools.rs         # 30+ 工具 + doctor
├── instructions.txt     # 13K 系统提示模板
├── providers.toml       # Provider 数据源
├── gateway-flow.md      # TUI 向导流程规范
├── AGENTS.md            # Agent 工具参考
├── Cargo.toml / Makefile / Cross.toml
└── install.sh / install.ps1

安装 #

四种官方安装方式，装到的二进制完全相同：

1. npm（全平台推荐）

npm i -g @angleschina/angles && angles install

npm 包内含 bin/angles.js 启动器与 install.sh / install.ps1。angles install 子命令根据平台调用对应脚本安装 Rust 二进制；其它子命令转发给已安装的二进制。postinstall 钩子只打印提示，不强制编译，不会破坏 npm install 体验。

2. curl 单行（Linux / macOS / WSL2）

curl -fsSL https://raw.githubusercontent.com/ZSJ305/angles-cli/main/install.sh | bash

3. wget 单行

wget -qO- https://raw.githubusercontent.com/ZSJ305/angles-cli/main/install.sh | bash

4. PowerShell 单行（原生 Windows）

irm https://raw.githubusercontent.com/ZSJ305/angles-cli/main/install.ps1 | iex

安装器内部流程

install.sh / install.ps1 共享同一套四步流程，带进度条与剩余时间估算：

1. 准备环境 — 先探测预编译二进制 URL 是否可用：
   • ✅ 可用 → 跳过编译工具 / Git / Rust 安装，直接进 Step 2 下二进制
   • ❌ 不可用 → 装 apt / apk / dnf / yum / pacman / zypper / emerge / xbps / homebrew / winget / VS Build Tools + Git + Rust (≤ 1.75 则升级)
2. 安装 Angles — 优先拉取预编译 tar.gz（angles-<os>-<arch>.tar.gz），失败则 clone 仓库从源码 cargo build --release
3. 配置 PATH — 写入 ~/.bashrc / .zshrc / .fish / .nu，可选 symlink 到 /usr/local/bin
4. 验证 & 初始配置 — 执行 angles --version 确认，首次安装（无 config.json）触发 angles gateway 向导

支持的环境变量：NO_PROMPT=1（跳过交互）、NO_GATEWAY=1（跳过向导）、DRY_RUN=1（只演示不改）、ANGLES_REPO（自定义仓库）、ANGLES_INSTALL_DIR（自定义安装目录）。

预编译支持矩阵

不是所有平台都有预编译二进制——没有的会 fallback 到源码编译（需要 Rust 工具链）。下表列出 Release v0.1.0 当前覆盖的情况：

源码构建 #

本地构建

# 装 Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# clone & build
git clone https://github.com/ZSJ305/angles-cli.git
cd angles-cli
cargo build --release

# 安装到 PATH
cp target/release/angles ~/.local/bin/

交叉编译（via Makefile）

Release profile

Cargo.toml 的 release profile 已优化体积：opt-level = "s"、lto = true、strip = true。

快速开始 #

# 首次配置（交互式向导）
angles gateway

# 默认进入对话
angles

# 非交互模式，执行单条指令后退出
angles exec "写一个 Python HTTP 服务器"

# 查看当前配置
angles config

# 查看所有命令
angles help

# 诊断安装 / 配置 / 网络
angles doctor

config.json 字段参考 #

配置存储在 ~/.angles/config.json。完整 schema：

{
  "language": "zh-CN",              // 全局默认响应语言
  "provider": "glm",              // provider id，见 providers.toml
  "base_url": "https://api.siliconflow.cn/v1",
  "wire_api": "chat",             // chat | anthropic | gemini
  "model": "zai-org/GLM-5.2",
  "api_key": "",                  // 空时读 ANGLES_API_KEY 环境变量
  "max_tokens": 16384,            // 单次回复 token 上限
  "daily_token_budget": 1000000, // 每日 token 预算
  "agent_persona": "你是一个专业、高效的编码助手。",
  "search_engine": "bing",        // bing | baidu | google | yahoo | custom | disabled
  "search_engine_url": "",         // custom 时使用，{q} 会被替换
  "approval_policy": "untrusted",  // never | untrusted | on-request
  "daily_tokens_used": 0,        // 当日已消耗 token（运行时维护）
  "daily_reset_date": "2026-07-20" // 每日预算重置日期
}

Gateway 设置向导 #

angles gateway 启动五步 TUI 向导（基于 dialoguer），任何配置字段都可在向导中修改：

1. 语言 — 中文 / English / 日本語，切换后续界面与 agent 默认语言
2. 模型提供方 — 11 家预设 + 自定义；选预设自动填 base_url 进入 Key 输入，选自定义先填 URL/Key/Model/协议
3. 模型选择 — 从 providers.toml 读取每个 provider 的预设列表，最后一项允许手动输入任意 model ID
4. 偏好 — max_tokens、daily_token_budget、agent_persona 文本、approval_policy
5. 联网搜索 — bing / baidu / google / yahoo / 自定义 URL / 关闭；自定义时填 https://.../?q={q} 模板

完成后向导写入 ~/.angles/config.json，显示配置摘要，并提示运行 angles chat。

Provider 体系 #

11 家预置 + 自定义，全部从 providers.toml 加载到 provider.rs 注册表：

API 协议适配 #

api.rs 同时支持三种协议：

所有协议都支持流式响应（SSE）。工具调用的循环逻辑统一在 api.rs 内处理：模型发出 angles-* 调用请求 → CLI 解析、根据审批策略决定是否询问 → 执行工具 → 把结果回灌给模型 → 直到模型不再发起新调用。

CLI 命令参考 #

用户可在终端直接调用的子命令：

Agent 工具命令 #

Agent 通过 angles-* 前缀的工具调用操作环境。全部 30+ 内置工具分组：

文件创建与写入 4

文件读取与搜索 5

文件修改与删除 7

目录与项目 5

终端与执行 3

网络与搜索 2

Git 操作 5

系统提示 & 模板 #

System prompt 模板存储在 instructions.txt（约 13KB），由 instructions.rs 用 Handlebars 渲染。模板中的 {{variable}} 占位符在运行时从 config 注入：

模板内置丰富指令：编码准则（修根因、避免复杂度、保持代码风格）、Preamble 消息原则、Planning（5-7 字步骤）、错误处理（重试 2 次、3 次后问用户）、Token 预算意识、危险操作的强制确认。

AGENTS.md 规范 #

仓库任何位置可放 AGENTS.md，为 agent 提供工作指令：

• 作用域 — 从包含该文件的目录起到整棵子树
• 对该子树内触碰的每个文件，必须遵从作用域覆盖它的 AGENTS.md 指令
• 冲突优先级 — 更深层嵌套的 AGENTS.md 胜出
• 最高优先级 — 直接的 system / developer / user 指令压过 AGENTS.md
• 自动加载 — 根目录与从 CWD 到根路径上的 AGENTS.md 已随 developer message 注入，无需重复读取；在子目录或 CWD 外工作时需主动检查

典型用法：编码规范、代码组织约定、运行 / 测试说明。

安全 & 审批策略 #

三档审批策略，配置在 approval_policy：

联网搜索引擎 #

angles-websearch 调用 search.rs 构造查询 URL 并返回摘要。

原则：准确性重要时优先搜索而非猜测；查询词要具体；搜索失败先简化查询再放弃。

Rust 依赖清单 #

来自 Cargo.toml：

许可与贡献

GPL-3.0 许可。源码、问题反馈、PR 欢迎：github.com/ZSJ305/angles-cli。