内容
# ada
[](https://www.npmjs.com/package/ada-agent)
[](https://github.com/black141312/ada/actions/workflows/ci.yml)
[](LICENSE)
[](package.json)
从零开始构建的编码代理 — 一个终端客户端，其理念灵感来自 pi / Codex / Cursor，能持有每个提供商的密钥，并与客户端使用一种线路格式进行通信。
客户端仅与后端进行 **OpenAI 聊天补全** 操作。后端根据模型 ID 将每个请求路由到正确的提供商，并将每个提供商的标准格式转换为该格式。因此，新的模型 **无需代码**，新的 OpenAI 兼容提供商 **仅需两行代码**。
---
## 功能特点
- **智能循环** — 流式传输、调用工具、反馈结果、重复直到完成。
- **工具** — `read_file`、`write_file`、`edit_file`（精确匹配）、`apply_patch`（多文件）、`bash`、`ls`、`grep`（如果存在则使用 `rg`）、`glob`、`web_fetch`、`web_search`、`lsp_diagnostics`、`ask_user`（澄清问题）。
- **自动格式化** — 编写的代码会使用项目格式化工具（prettier/gofmt/rustfmt/ruff/shfmt）在受信任的项目中进行格式化；通过 `ADA_NO_FORMAT` 关闭。
- **LSP 诊断** — `lsp_diagnostics` 运行语言服务器（typescript-language-server、pyright、gopls、rust-analyzer）并返回错误/警告；服务器被重用，仅限受信任项目。
- **真正的 PTY shell** — `bash` 运行在伪终端（node-pty）中，因此 TTY-only 程序、颜色和进度输出表现正常；ANSI 从模型看到的内容中剥离。
- **两个前端** — 经典的 readline REPL 和内联 **TUI**（ `--tui` ）带有动态“思考”spinner 和 Claude-style 转折标记。
- **权限模式** — `ask`、`plan`、`auto` — `/ask` 确认每个工具，`/plan` 只读（ada 计划，`/run` 执行），`/auto` 自由运行（破坏性 `bash` 仍然确认）。每个审批状态用纯文字表示它想要什么（“ada 想要运行 shell 命令…”）而不是原始参数。
- **实际生效的技能** — 约 285 个内置技能；ada 路由每个请求并 **自动应用** 明确匹配的技能（注入其过程），或建议加载技能。参见 [技能](#技能)。
- **待办事项**、**检查点/撤销**（恢复代理的编辑）、**保护路径**、**git 工作树**、**工作区快照**（`/snapshot` `/restore`）、**命名代理** 和 **子代理**（`spawn_agent`）。
- **会话** — 每个回合都持久化； `--continue` / `--resume` 继续上次会话。
- **上下文压缩** — 随着上下文增长，自动总结旧回合。
- **使用 GitHub 或 Google 登录** （RFC 8628 设备流）— 零客户端配置。
- **可扩展** — 扩展（工具 + 钩子 + 命令）、提示模板、技能和 MCP 服务器。
- **无构建步骤** — TypeScript 通过 `tsx` 运行。
## 提供商
后端代理任何 OpenAI 兼容的上游并翻译不兼容的提供商（Anthropic）：
| 提供商 | 模型 | 密钥环境变量 |
|---|---|---|
| OpenAI | `gpt-*`, `o*` | `OPENAI_API_KEY` |
| Anthropic | `claude-*` | `ANTHROPIC_API_KEY` |
| Google Gemini | `gemini-*`, `gemma-*` | `GEMINI_API_KEY` |
| Mistral | `mistral-*`, `codestral-*`, … | `MISTRAL_API_KEY` |
| DeepSeek | `deepseek-*` | `DEEPSEEK_API_KEY` |
| xAI (Grok) | `grok-*` | `XAI_API_KEY` |
| DashScope (Qwen) | `qwen-*`, `qwq-*` | `DASHSCOPE_API_KEY` |
| **Cloudflare** (Workers AI / AI Gateway) | `@cf/*` (例如 `@cf/moonshotai/kimi-k2.7-code`) | `CLOUDFLARE_API_TOKEN` (+ `CLOUDFLARE_ACCOUNT_ID`) |
| Groq | `groq/<model>` | `GROQ_API_KEY` |
| Together | `together/<model>` | `TOGETHER_API_KEY` |
| OpenRouter | 其他所有 | `OPENROUTER_API_KEY` |
| **Ollama（本地）** | `name:tag` (例如 `qwen2.5-coder:latest`) | *无密钥* |
路由：模型 ID 包含 `:` → 本地 Ollama；`@cf/*` → Cloudflare；`groq/…`/`together/…` 选择这些提供商（它们是模糊的，因此是明确的）；否则按前缀；明确的 `provider` 字段始终获胜。仅设置您拥有的密钥 — 其余保持休眠（供应商 SDK 延迟加载）。
**Cloudflare** (Workers AI 或 AI Gateway) 是其自己的逐步过程 — 参见 **[docs/cloudflare.md](docs/cloudflare.md)**。
---
## 安装
需要 **Node ≥ 18** （和 C 工具链，因为 `node-pty` 本地构建）。
**无需安装即可运行 — `npx`：**
```bash
npx ada-agent # 客户端 （发布到 npm）
npx -p ada-agent ada-server # 后端 （同一个包中的第二个二进制文件）
# 直接从源代码开始，无需发布：
npx github:black141312/ada
```
**全局安装** （将 `ada` 和 `ada-server` 放在您的 PATH 中）：
```bash
npm install -g ada-agent
ada
```
**从克隆仓库开始** （用于修改）：
```bash
git clone https://github.com/black141312/ada.git
cd ada && npm install
npm link # 全局 `ada` / `ada-server` · 或 `npm start`
```
> 已发布的 npm 命令在维护者运行 `npm publish` 后生效；`github:` 表单适用于今天的仓库。
## 快速开始
ada 是两个进程：一个 **后端** （持有密钥，路由）和 `ada` 客户端。
`ada` **自动启动 `ada-server`** 在后台如果它尚未运行 — 一个终端足够用于单独使用。 （设置 `ADA_BACKEND_URL` 为远程 URL 以跳过自动启动，或设置 `ADA_NO_AUTOSTART=1` 以完全退出。）
**选项 A — 本地，无密钥（Ollama）：**
```bash
ada # 选择本地模型并聊天（后端自动生成）
```
**选项 B — 云提供商：**
```bash
export ANTHROPIC_API_KEY=sk-ant-... # 和/或 OPENAI_API_KEY, GEMINI_API_KEY, …
ada --model claude-opus-4-8
```
Windows PowerShell： `$env:ANTHROPIC_API_KEY="sk-ant-..."` 。
要将 `ada-server` 作为长期共享后端运行（多客户端设置，或只是保持其温暖），请先手动启动它 — `ada` 将检测并重用它。
---
## 使用 `ada`
```bash
ada # 交互式；选择第一个运行的模型
ada --tui # 内联 TUI 前端
ada --model <id> # 在特定模型上启动
ada --list-models # 您的密钥可以访问的所有模型（通过后端）
ada --continue # 继续最近的会话
ada --resume # 选择要继续的会话
ada --yolo # 自动批准工具调用（跳过提示）
ada -p "修复构建" # 一次性：打印答案并退出
```
**斜杠命令** （在一个会话中）： `/ask` · `/plan` · `/auto` · `/mode` （循环权限模式） · `/run` · `/model [id]` · `/models` · `/reasoning low|medium|high|off` · `/strategy react|single|plan|multi|toolsmith` · `/agent [name]` · `/todos` · `/undo` · `/snapshot` · `/restore` · `/jobs` · `/fork` · `/tree` · `/rewind` · `/compact` · `/context` · `/cost` · `/image <path>` · `/paste` · `/login` · `/logout` · `/exit`。
**权限模式** — 使用 `/ask` · `/plan` · `/auto` （或 `/mode` 循环）；当前模式显示在提示行中。 在 **ask** 模式下，每个受限工具都带有明确的文字提示（“ada 想要运行 shell 命令…”）和一个密钥： `[y]es` · `[a]uto` （无提示运行其余部分） · `[p]lan` · `[n]o`。 **plan** 是只读的 — ada 计划但不编辑； `/run` 批准并执行。 **auto** 无需询问即可运行工具（破坏性 `bash` 仍然确认）。 `--yolo` 以 **auto** 开始。
**子命令：** `ada mcp …` （连接器） · `ada skill add <url>` · `ada worktree add <name>` · `ada catalog [provider]` （离线模型/价格目录） · `ada serve` （HTTP API — 一次性和类似 Cursor 的流式会话，用于将 ada 集成到您自己的 IDE 中） · `ada share` （查看会话） · `ada acp` （编辑器桥接）。有关 HTTP API （包括实时 SSE 会话和批准门控）、类型化 SDK 和 ACP，请参见 [docs/integrations.md](docs/integrations.md)。
**编排策略** — 代理运行可插拔的代理架构（ `--strategy <name>` 或 `/strategy`）：`react` （默认循环）、`single` （一次性）、`plan` （计划→执行）、`multi` （子代理分发）和 `toolsmith` （读取连接的集成的文档并让子代理为其编写技能）。参见 [docs/orchestration.md](docs/orchestration.md)。
**登录** （可选 — 将您标识为后端）：运行 `/login`，选择 GitHub 或 Google，并输入浏览器中的设备代码。令牌存储在本地并作为客户端密钥发送。
## 技能
ada 配备了 **约 285 个内置技能**，涵盖约 30 个类别 — 专门的指令，模型仅在任务需要时调用（渐进式披露）。 ada **路由** 每个请求，并使用相关性排名器进行排名；在名称和描述上；当一个技能明确匹配时，ada **自动应用** 它 — 注入其过程，以便即使弱模型也遵循它（宣布为 `↳ skill: <name>`）；当匹配模糊时，它只是建议它们。模型还可以使用 **`list_skills`** （按 `category`/`filter`）、搜索 **`find_skill`** （排名），并使用 **`use_skill`** 加载一个技能 — 因此，除非使用，否则不会增加提示膨胀。技能类别示例：
`git` · `review` · `testing` · `debugging` · `refactoring` · `docs` · `security` · `ci-cd` · `performance` · `database` · `api` · `frontend` · `ui-design` · `html` · `pptx` · `image` · `graphics` · `languages` · `frameworks` · `mobile` · `cloud` · `observability` · `data-ml` · `agent-llm` · `web3` · `networking` · `shell` · `connectors` · `compliance` · …
示例： `commit`、`code-review`、`dockerize`、`migration`、`react-hooks`、`terraform-module`、`rag-pipeline`、`security-audit`、`project-overview`、`architecture-diagram`、`graphify`、`ponytail`。
添加您自己的技能作为 `.ada/skills/<name>/` （项目）或 `~/.ada/skills/<name>/` （全局）下的 `SKILL.md` 文件 — 只需要 `---\ndescription: …\ncategory: …\n---` 前置元数据即可。项目技能覆盖全局技能，全局技能覆盖内置技能。使用 `ada skill add <url>` 安装远程技能（`SKILL.md` 或 JSON 索引）；`ada skill list` 显示它们。
## 连接器（MCP）
ada 通过 MCP 服务器访问外部工具和数据。浏览目录并添加一个：
```bash
ada mcp # 列出目录（文件系统，github，postgres，slack，sentry，…）
ada mcp add github # 将其写入 .ada/mcp.json，然后设置它打印的令牌
```
支持 **本地stdio** 服务器（ `{ command, args }` ）和 **远程HTTP** 服务器（ `{ url, headers }` ）；它们的工具在受信任的项目中作为 `<server>__<tool>` 出现，带有批准门控。参见 [docs/connectors.md](docs/connectors.md)，或 `connectors` 技能类别以进行每个连接器的设置。
## 配置
**客户端** （`ada`）：
| 环境变量 | 默认值 | 用途 |
|---|---|---|
| `ADA_BACKEND_URL` | `http://localhost:8787/v1` | 后端的位置 |
| `ADA_CLIENT_KEY` | 存储的登录令牌，否则 `dev` | 发送到后端的 Bearer |
| `ADA_MODEL` | — | 默认模型 ID |
| `ADA_COMPACT_AT` | `100000` | 触发压缩的令牌估计 |
| `ADA_AUTO_APPROVE` | — | `1` ⇒ 像 `--yolo` 一样行为 |
| `NO_COLOR` / `ADA_THEME` | — | 禁用颜色 / 主题覆盖 |
**后端** （`ada-server`）：
| 环境变量 | 默认值 | 用途 |
|---|---|---|
| `ADA_PORT` | `8787` | 监听端口 |
| `ADA_CLIENT_KEYS` | *(未设置 = 开发/无身份验证)* | 逗号分隔的允许客户端密钥 |
| `ADA_REQUIRE_LOGIN` / `ADA_ALLOWED_USERS` | — | 访问验证的 GitHub/Google 用户的权限 |
| `OLLAMA_BASE_URL` | `http://localhost:11434/v1` | 本地 Ollama 端点 |
| *(提供商密钥)* | — | 参见 [提供商](#提供商) 表 |
---
## 开发
```bash
npm run typecheck # tsc --noEmit
npm run selfcheck # 离线检查（工具，会话，路由，解析器，TUI）
npm start # 从源代码运行客户端
npm run server # 从源代码运行后端
```
参见 **[docs/architecture.md](docs/architecture.md)** 获取设计（适配器，路由，请求流程，文件布局）， **[docs/orchestration.md](docs/orchestration.md)** 获取代理策略， **[docs/integrations.md](docs/integrations.md)** 获取 HTTP API / SDK / ACP。
## 企业
`ada-server` 作为组织 **控制平面** ：每个用户座位密钥，组织策略（服务器强制模型允许列表 + 工具规则推送到每个客户端），每个用户使用情况计量和审计日志 — 仅当您创建座位时激活，文件备份，在您自己的网络中自行托管。参见 **[docs/enterprise.md](docs/enterprise.md)** 获取 2 分钟启动。
**SSO（OIDC）** — 将登录联合到您的 IdP（Okta，Entra 单租户，Auth0，Keycloak，Google Workspace）： `ADA_OIDC_ISSUER=… ada-server`，然后开发者运行 `ada login oidc`。后端 **JIT-provisions** 一个座位用于验证身份，立即离职。仅限库 RS256/JWKS 验证，无新依赖； fail-closed 构造。参见 **[docs/enterprise-stage2-oidc.md](docs/enterprise-stage2-oidc.md)**。
**部署** — 一个 `Dockerfile` + `docker-compose.yml` 在任何地方运行后端（`docker compose up`）；使用 `ADA_BACKEND_URL` / `ada.backendUrl` 将客户端指向它。使用 Cloudflare Workers AI 模型（`@cf/*`）或 AI Gateway，无需代码更改。参见 **[docs/deploy.md](docs/deploy.md)**。
## 基准测试
ada 可以运行 **SWE-bench Verified** — 它为真正的 GitHub 问题生成补丁（每个任务隔离的仓库克隆），发出官方格式的 `predictions.jsonl`，官方 `swebench` Docker 套件会对其进行评分。 `node bench/swebench.mjs --dataset … --model … --out runs/x`。参见 **[bench/README.md](bench/README.md)** 获取完整流程（数据集，先决条件，评分命令）。
## 贡献
欢迎提出问题和 PR — 这是一个小型，无构建的代码库。 在 PR 之前运行 `npm run typecheck && npm run selfcheck` 并保持更改精简。参见 **[CONTRIBUTING.md](CONTRIBUTING.md)**；通过 **[SECURITY.md](SECURITY.md)** 报告漏洞。
## 许可证
[MIT](LICENSE) © 2026 Aditya
