1ay1/agentty · 上手攻略
- 仓库：1ay1/agentty
- 链接：https://github.com/1ay1/agentty
- 分类：AI 编程工具 · 终端 Agent
- 作者：Tom
- 更新：2026-09-08
是什么
agentty 是一个用 C++26 编写的终端 AI 结对编程工具，以单文件静态二进制分发（16.7 MB），冷启动约 3 ms，号称是 Claude Code 的平替。核心特点：零运行时依赖（无 Node/Python/npm）、智能代码检索（Hybrid BM25 + Embeddings + GraphRAG）、支持任意 LLM 提供者（Anthropic/OpenAI/Groq/OpenRouter/Cerebras/DeepSeek/xAI/Mistral/Gemini/Fireworks/Ollama）。
项目采用 MIT 协议开源，可在 Zed 编辑器中通过 ACP 协议运行。
解决什么问题
现有主流终端编程 Agent（如 Claude Code、GPT-Reply、Aider）普遍存在三大痛点：
- 运行时负担重：基于 Node.js 或 Python，每次启动需加载大量依赖，冷启动慢
- 上下文膨胀：每次调用把整个仓库或大段代码全部发送给模型，上下文成本极高
- 供应商锁定：与特定云服务深度绑定，切换模型成本大
agentty 的解法：编译成单一原生二进制 + 精准代码检索（按需只取最相关片段）+ 开放式模型路由。
快速安装
一条命令安装（Linux/macOS）
curl -fsSL https://raw.githubusercontent.com/1ay1/agentty/master/install.sh | sh
手动下载
# 访问 https://github.com/1ay1/agentty/releases/latest 下载对应平台的二进制
# 下载后添加执行权限
chmod +x agentty
# 放入 PATH 或用绝对路径运行
./agentty
⚠️ 官方 release 为单二进制（无 Node/Python 依赖），首次运行会引导输入 API Key 或配置本地模型。
仓库编译（开发者）
git clone https://github.com/1ay1/agentty.git
cd agentty
# 需要 C++26 兼容的编译器（Clang 19+ 或 GCC 14+）
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build . --parallel
核心用法
启动与认证
agentty
首次启动会提示输入 API Key：
- Anthropic Claude：sk-ant-... 格式的 API Key，或使用 Claude Pro/Max OAuth 登录
- OpenAI/Groq/OpenRouter 等：对应提供商的 API Key
- 本地 Ollama：无需 Key，直接运行 ollama serve 即可
模型切换
支持运行时切换模型，按 Ctrl+P 调出模型选择菜单。常用示例：
agentty -m claude-opus-4-5 # Claude（需 API Key 或 Pro/Max OAuth）
agentty --provider openai -m gpt-4o # OpenAI GPT-4o
agentty --provider groq -m llama-3.3-70b # Groq Llama
agentty --provider openrouter -m <model> # OpenRouter 任意模型
agentty --provider deepseek -m deepseek-v4-pro # DeepSeek
agentty --provider xai -m grok-4.6 # xAI Grok
agentty --provider gemini -m gemini-3.7-flash # Google Gemini
agentty --provider ollama -m qwen2.5-coder # 本地 Ollama，无需 Key
--provider 参数会持久化保存，下次启动默认使用。
内置工具集
| 工具 | 用途 |
|---|---|
read |
读取文件 |
write |
写入文件 |
edit |
编辑文件（精准修改） |
bash |
执行 Shell 命令（在沙箱中运行） |
grep |
文本搜索 |
glob |
按模式匹配文件 |
git |
Git 操作 |
web |
网页搜索/访问 |
search_docs |
从知识库检索（文档/技能/记忆/MCP） |
search_code |
语义代码搜索 |
task |
创建子任务 |
⚠️ 所有 Shell 命令在 Linux 上通过
bwrap（ bubblewrap）、macOS 上通过sandbox-exec沙箱隔离运行。文件操作拒绝访问工作区外的路径。
智能检索（RAG）体系
agentty 内置完整本地检索引擎，两大检索工具：
search_docs：搜索知识库（docs 文件夹 + 已安装技能 + 记忆 + 可选 MCP 资源）。从第一个问题即可使用，技能和记忆始终被索引。search_code：语义搜索代码库，按语义理解查询（如"retry backoff 在哪里处理"），不需要知道具体变量名。
检索流程（每次 search_docs 调用）： 1. 混合检索：BM25（关键词，Porter 词干）+ Dense Embeddings（HNSW 索引）并行检索，RRF 融合 2. 伪相关反馈（RM3）：从 top 结果中提取区分性术语，追加下加权二次检索 3. 上下文检索：每个 Chunk 用所在文档标题+标题路径作为面包屑索引，跨标题搜索依然命中 4. 重排序：确定性特征融合重排（词覆盖、词距 proximity、标题匹配、余弦相似度），可选批量 Embedding Cross-Encoder 和生成式 0-10 裁判 5. MMR 多样化：贪心选择相关且不重复的命中结果 6. 压缩：将每个存活结果裁剪到最相关片段（"20k 噪声 tokens" → "2k 有效 tokens"） 7. 父文档扩展：将命中的精确片段与其相邻块拼接，恢复完整上下文 8. GraphRAG 扩展：构建文档图（节点=文档，边=Markdown 链接+tf·idf 共现实体），PageRank + 社区检测，取 top 命中周围四层支撑文档
启用语义检索（可选，BM25 默认即开）：
ollama pull nomic-embed-text && ollama serve # 本地 Embedding 服务
export AGENTTY_DOCS_DIR=~/my-project/docs # 可选；技能和记忆始终被索引
agentty # 自动检测到 Ollama 即升级为混合检索
Smart Mode（智能路由）
agentty 不会每次都调用最强最贵的模型，而是： - 强模型做规划：用高端模型处理复杂决策 - 便宜模型做执行：简单任务路由到廉价模型 - 级联重试：便宜模型失败时自动升级重试 - 跨会话学习：路由器会记住代码库特点，持续优化路由
可通过 AGENTTY_SMART_MODE=off 完全关闭智能路由。
安全功能
- 沙箱隔离：所有 Shell 命令在严格沙箱中执行
- 路径限制：文件工具拒绝工作区以外的路径
- SSH 隔离：可用一条命令把整个会话通过 TLS 端到端加密中继到离线机器
典型适用场景
- 大型代码库重构：语义搜索精准定位，混合检索只取相关片段，上下文效率提升 80%+
- 本地模型优先：用 Ollama 跑 qwen2.5-coder 等本地模型，完全离线工作，零 API 费用
- 多模型对比：同一条任务，用
Ctrl+P快速切换不同模型对比效果 - 离线安全开发：通过 SSH 隔离模式，在完全空气隔离的机器上开发
- 快速原型任务：sub-ms 启动，无需任何环境准备，下载即用
- 文档问答：本地 RAG 引擎对项目文档进行检索增强回答
坑与注意
- C++26 编译要求高：如需从源码编译，需要 C++26 兼容工具链（Clang 19+ / GCC 14+），普通系统默认编译器可能不支持
- Ollama Embedding 可选：不安装 Ollama Embedding 服务时，检索退化为纯 BM25 关键词模式，仍然可用但语义能力受限
- API Key 安全：首次运行时需粘贴 Key，注意终端历史记录风险；建议优先使用 Claude Pro/Max OAuth 认证
- 沙箱限制：部分系统命令在沙箱中可能无法执行（如需访问
/proc等特殊路径） - 发布节奏：项目用 C++26 编写，相对年轻，稳定性与生态（技能/MCP 集成）不如 Claude Code 成熟
- 模型支持范围：虽然支持任意 OpenAI-compatible 端点，但部分提供商的具体模型 ID 可能需要手动确认
与同类对比
| agentty | Claude Code | Aider | GPT-Reply | |
|---|---|---|---|---|
| 语言 | C++26 | TypeScript | Python | Go |
| 二进制大小 | ~16.7 MB | 需 Node.js | 需 Python | 单一二进制 |
| 冷启动 | ~3 ms | 较慢（Node 加载） | 较慢 | 较快 |
| 上下文策略 | 精准检索（-80%） | 全量上下文 | 全量或按需 | 按需 |
| 模型支持 | 任意（多提供者） | Anthropic 为主 | 任意 | 主要 OpenAI |
| RAG | Hybrid BM25+Embedding+GraphRAG | 基础 | 有限 | 有限 |
| 沙箱 | bwrap/sandbox-exec | 无（直接执行） | 无 | 有限 |
| SSH 隔离 | ✅ | ❌ | ❌ | ❌ |
| 开源 | ✅ MIT | ❌ | ✅ GPL | ❌ |
| Zed 集成 | ✅（ACP） | ❌ | ❌ | ❌ |
agentty 的核心差异化优势：C++ 原生二进制（极快启动）+ GraphRAG 精准检索（上下文压缩）+ 完全离线 RAG 能力（不依赖云服务做检索）。
一句话推荐结论
如果你追求极致启动速度、需要本地离线 AI 编程、或希望在各种模型之间灵活切换，agentty 是目前最值得关注的开源终端编程 Agent——C++ 单二进制零依赖，GraphRAG 精准上下文，上下文成本直降 80%。