# ARES **Repository Path**: dboy019/ares ## Basic Information - **Project Name**: ARES - **Description**: 程序员自己的定制化AI Harness编程助手 - **Primary Language**: Python - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 9 - **Forks**: 4 - **Created**: 2026-05-04 - **Last Updated**: 2026-11-20 ## Categories & Tags **Categories**: ai **Tags**: Harness, AI, Agent ## README # ARES CLI — 单 Agent 归一执行框架 > v1.9.8(pure-base-v1)· Python 3.11+ · 单 Agent 归一架构(v1.7.31 起默认) > 可视化管理界面已年久失修、不随版本发布,本文专注 **CLI**。 **一句话定位**:一个在终端里干活的单 Agent 执行框架——规划、检索、读代码、改代码、执行命令、并行子任务、收敛汇报,全部由一个统一执行 Agent 完成;用一套**可观测、可审计、可还原**的治理体系把长任务的上下文膨胀、轮次空转、答非所问摁在地板上。 **为什么不是又一个 Agent 壳子**:多数 Agent 框架把精力花在「能跑」,ARES 把精力花在「跑了 200 轮之后还能不能记得自己读过什么、改坏了能不能还原、答完的到底全不全」。本文全部特性均经代码级 review(22 项逐一核到文件+行号,无一虚标)。 ## 一、系统能力总览 ARES 的特性不是散装工具堆砌,而是围绕「长任务三大杀手」组织的六层能力体系: | 层 | 杀手 | 核心特性(本节号=下文章节) | |---|---|---| | 执行层 | 任务干一半就烂尾 | 单 Agent 归一主循环 + 任务树进度分子(§二) | | 上下文层 | 200 轮后上下文爆炸 | 列车清单 + 外部化 + 缓存纪律(§三) | | 读写层 | 重复读空转 / 改坏没得还原 | 读取治理四件套 + 骨架写作 + 审计还原(§四) | | 命令层 | LLM 傻等后台命令白烧 token | 代码态监控,LLM 只在检查点介入(§五) | | 知识层 | 经验不沉淀、每次从零学 | Skills / Wiki 记忆 / 上下文索引(§六) | | 质量层 | 出了问题说不清根因 | trace 底座 + 申诉通道 + 观察点体系(§七) | **两个差异化主张**: 1. **单 Agent 归一**:不做 Mastermind→Army→Scout→Soldier 的四角色接力,规划/调研/执行/收敛由同一个 Agent 完成——角色间交接即信息损耗,长任务最贵的就是交接。旧四角色链路保留为 `ARES_UNIFIED_AGENT=0` 显式回退,非死代码。 2. **治理点即能力**:每条治理都对应可量化的 trace 指标(重复读率、缓存命中率、轮次空转率),不是「感觉变快了」——CheckList 十四章观察点就是这套度量体系的手册(`ARES流程观察点CheckList.md`),README 只讲能力本身。 ## 二、执行架构:单 Agent 归一 + 任务树 + 并行子任务 **主循环**(`unified_agent/agent.py`):一个 Agent 吃下规划、检索、读改代码、命令执行、收敛汇报全链路。每轮 LLM 调用返回工具批(FC),执行层并行跑同轮独立工具,结果回灌进入下一轮;直到 Agent 判定目标达成调 `task_done` 收敛。收敛前强制对照北极星段与计划逐项核对——「干一半留遗留项」在流程上是会被拦截的(进度分子未满即拦截,需逐项说明)。 **任务树进度分子**(`create_plan` / `update_task_node`):复杂任务先建计划(≥2 子任务、可验证的 success_criteria),推送到前端展示;每个子任务完成必须回写状态,否则进度恒为 0/N——分子是唯一进度真源,防止「嘴上说完成了」。本 README 的重写就是一次活演示:4 子任务计划,逐项回写。 **并行子任务**(`subtask_runner.py` · `spawn_subtask`):一次调用下发 1-5 个独立子 Agent,各自拥有完整工具池、上下文隔离(intent 必须自足),结果以 ≤800 字符摘要汇聚,单个失败不影响其他。适合分组调研(本轮 README 的 22 特性 review 就是 3 个并行子任务完成的,295s 拿回三组代码级证据)。 **单次执行 / REPL 双模式**:`ares-cli -p "任务"` 脚本化一次性执行;`ares-cli` 进交互 REPL(prompt_toolkit 输入层 + Rich Live 渲染)。`--session-id` 恢复历史会话,中断任务下次「继续」接力(挂起意图自动提示)。 ## 三、上下文治理:列车清单 + 外部化 + 缓存纪律 长任务的真正敌人不是模型不够聪明,是上下文越滚越大之后模型开始「失忆+空转」。ARES 用三件武器正面治理: **ContextTrain 列车清单**(`fsm_agent/context_train.py`):所有进入上下文的资源(文件/技能/规则/记忆/搜索结果)上车登记——content_hash+mtime 双指纹,同内容不重复发全文。每轮头部刷新一帧「列车清单」:车上有什么、已读勿重读、缺哪段用 offset 精读。读者现在看到的这行列表就是它。v1.7.45 起单槽刷新(不再追加膨胀),容量水位打点。 **工具结果外部化**(`agent.py` · `_externalize_tool_result`):超 1500 字符的工具结果全量落盘 `.ares/session_artifacts/`(v1.7.68 起按 session/turn 四层分目录),上下文只留 ≤500 字符摘要+回读路径——要细节按路径 offset 精读。**嵌套豁免**(v1.9.24):结果里已含外部化标记的原样内联,杜绝「外部化的再外部化」死循环(实测曾致单用例重读 8 次)。开关:`ARES_UNIFIED_EXTERNALIZE=0` 整体关闭;`ARES_UNIFIED_EXTERNALIZE_FORCE=1` 强制全量外部化。 **历史瘦身 + 缓存纪律**:旧轮消息按「入史瘦身」裁剪(保数据行数、裁叙述性长文),幂等闸门防标记套标记;系统提示词的时间块只到天粒度(A103)——分秒级时间戳每轮变化会击穿 LLM 前缀缓存,天粒度使 system prompt 前缀稳定,缓存命中率的下限由结构保证。这套组合拳的量化效果:轮数治理专项实测 LLM 推理占耗时 89%、串行单工具轮占 60%——结论「压耗时唯一有效路径=压轮数」,对应工具层提供 ranges 批量读、同轮并行工具批等并轮手段(见 §四)。 ## 四、读写纪律:读取治理四件套 + 骨架写作 + 审计还原 **读取治理四件套**(`read_governance.py` 237 行纯函数库 + `tool_executor.py` 读取链路 ContextTrain.check_file 拦截点)——治「磨叽」的因果链闭环(读取无标注→不信任→cat/grep 绕道→无行号→再全量读→上下文膨胀→空转): 1. **来源标注头**(P0-4):每次读取返回带文件名+行段+模式,附「📖 此前已读 N 次」摘要——不翻历史即知重复度。 2. **同段重复读拦截**(P0-1):区间重叠检测(covered_pct/reads/recent_round),命中返回轻量提示而非全文重发,文案带「上下文第 N 轮」回溯指针,直接告诉 LLM 去哪一轮回看。 3. **拦截后行为引导**:拦截不是死胡同——5 条出路(回看上下文 / grep 定位自动放行 / ranges 批量 / force 穿透兜底 / 写后自动放行)。行为引导型而非硬拦截,过度拦截会制造任务阻塞申诉。 4. **长输出首尾保留 + ranges 批量段**(P0-2/3 + P1-1):超长输出不粗暴截断,保首尾带行号可精确续读;`ranges` 参数一次调用取多文件多段(`'文件A:L10-50,文件B:L100-130'`),直接砍往返轮次。 **骨架先行写作**(`write_file` + `fill_placeholder`):超 8000 字符的长文档禁止一次性写入(LLM 调用超长会超时)——先写骨架(章节 + `{{ __SECTION_N__ }}` 形式占位符),再逐段填充,每段 <60s。本文就是 12 段骨架一次一次填出来的。 **写操作审计 + 快照还原**(`audit_logger.py` + `restore_file`):每次 write/str_replace 前先存 before 快照(gzip),`get_operation_history` 按文件/工具/时间审计操作轨迹,改坏了 `restore_file` 一条命令回滚到任意历史版本——「改坏了没得救」在结构上不可能发生。 ## 五、命令执行:代码态监控,LLM 只在检查点介入 后台命令(构建/安装/部署)等完是 token 黑洞:LLM 每 10s 轮询一次 = 每次一轮完整 LLM 往返。ARES v1.9.5 起改为**代码态监控**(`watch_command`): - **10 秒代码对比**:后台进程每 10s 对比 stdout/stderr 增量,零 LLM 参与——输出有变化才值得 LLM 看,纯等待期 token 消耗为零。 - **60s LLM 检查点**:每 60s 给 LLM 一次裁决机会(判断是暂时卡住还是真结束),`max_wait_s` 总超时兜底;续看用 `continue_wait=true` 续接时钟。 - **多任务 join 语义**:`task_ids` 数组 + `wait_mode=any`(任一 done 即返回)/ `all`(join 等全部)——并行构建多个目标时按需选择,由 Agent 判断。 - 兜底:`poll_command` 仅快照查询(历史兼容),禁止循环轮询——「轮询即烧钱」是明文纪律。 配套铁律:预计 >60s 的命令必须 `background=true` 后台启动拿 task_id,禁止同步干等;短命令直接同步执行。 ## 六、三层知识引导:Skills / Wiki 记忆 / 上下文索引 Agent 的上限不在工具池,在「经验是否沉淀」。三层引导各管一段: **① Skills(`skill_manager.py`)——「怎么做某类任务」的活文档** 全局+项目级目录自动合并;YAML frontmatter(name/description/tags)+ Markdown 指令正文,子文件可挂 references/scripts/templates。三入口:`list_skills` 发现 → `get_skill_instruction` 加载指令 → `get_skill_resources` 取参考资源;另有 `upsert_skill`/`write_skill_file`/`delete_skill` 全生命周期管理。磁盘 mtime 变更检测增量刷新,不全量重索引。 **② Wiki 记忆(`wiki_manager.py` 1063 行)——「跨会话知识」的持久层** 七类记忆模型(constraint/assertion/commitment/procedure/event/belief/preference,`wiki_memory_service.py` MEMORY_TYPE_ORDER),`wiki_write`/`wiki_read` 读写。**知识图谱自动建边**(G3):写页时自动提取三格式结构化引用——`wiki:` 前缀、`[[双链]]`、mem 注释——纯文本提及不建边(防误报);整页替换先删旧边再提取新边(防膨胀)。**图扩展检索**(G1):关键词命中后沿 depends_on 边 1 跳扩展召回,每个扩展项带 `expanded_from` 留痕可审计;种子页无出边自动回退 top2/top3(生产桶实测第一个坑)。 **③ 上下文索引(`add_context_index`)——会话内热知识** 执行中发现的高置信信息登记为 strong/medium/weak 三档:strong 全轮强制注入(硬性规则),medium 每轮概览可见,weak 按需查询。防止「第 3 轮发现的规则第 20 轮忘了」。 **检索底座**:统一 `search` 入口(代码+KB+记忆+联网一次全查)+ AST 级 `search_symbol`(SQLite+tree-sitter 索引,符号定义/调用链毫秒级)+ `kb_graph_view` 知识库 Mermaid 图谱。检索 query 自动提炼(jieba 分词提关键词,无 jieba 回退正则)——治「口语噪声淹没关键词」。 **MCP 接入**:外部 MCP Server 懒启动注入工具池,`ARES_MCP_FASTPATH` 闸按需开。 ## 七、质量保障:trace 底座 + 申诉通道 + 观察点体系 出了问题说不清根因的框架没有排障能力。ARES 把「每一次运行」变成可审计的数据: **trace 数据底座**:每会话落盘 `logs/traces/cli_*/trace.jsonl`(llm_call / tool_execution / agent_decision / externalize_audit 等事件全量),写失败有静默失败防护(曾发生 3h40m 会话 trace 全缺被 `except:pass` 吞掉的事故,此后列为防护红线)。trace 分析有方法论纪律:流式逐行处理(单文件 70MB+)、按包构建时间做版本分段(防新旧包事件混入误判)、「提及≠调用」唯一以 tool_execution 事件为准。 **申诉通道**(`raise_concern`):Agent 遇到工具异常/流程卡点/约束冲突时主动落盘申诉(含四要素:下一步意图/上下文缺口/瞎猜补齐/根因预估),开发者定期 triage——Agent 的痛点自己会说话,问题清单不靠用户口述攒。 **观察点体系**(CheckList 十四章):5 大观察点 + 后续扩展(1~9 号 + 套件健康度/跨进程/产物登记/A88-A90)可量化检查项——重复读率、拦截提示驻留比、记忆四段链路评分(0-10 分/段)、G1 扩展命中数、trace 时间线连续性、申诉复现统计、轮数治理、产物分层、外部化嵌套专项……每个观察点都配「检查方法(trace 取证)+ 量化指标 + 健康基线」。这套手册使任何一次会话都能按 10 分钟快速检查流程出一份对比报告——治理不是玄学,是可复现的度量。 **产物四层分层**(v1.7.68):temp(L1 随对话清) / process(L2 保 7 天) / answer(L3) / workspace(L4 永久),按 session/turn 目录隔离——多会话产物结构性防串台,「临时产物随对话结束清理」成为可能。 **回写校验**:task_done 收敛前校验计划项回写状态,漏回写会被拦截——本文档这份 README 的 4 项计划正受同一机制约束。 ## 八、安装 **前置**:Python 3.11+,macOS / Linux。 **源码方式(开发者)**: ```bash git clone ares && cd ares/backend python3.11 -m venv .venv && .venv/bin/pip install -r requirements.txt .venv/bin/python cli_main.py # 进 REPL .venv/bin/python cli_main.py -p "任务" # 单次执行 ``` **二进制方式(推荐给使用者)**: ```bash # 1. 构建(PyInstaller 单文件) cd backend && .venv/bin/pyinstaller ares-cli.spec --noconfirm # 2. 安装(多入口同步脚本:枚举 which -a 全部路径逐一替换,防 PATH 遮蔽断链) bash scripts/install.sh 1.9.8 # 3. 验证 ares-cli --version # → ares-cli 1.9.8 ``` 安装脚本自动处理:`ares` / `ares-cli` 双入口同步、旧副本 `.bak.时间戳` 备份、`--version` 实测、md5 全量核对。**安装后务必 `ares-cli --version` 实测**——历史上多次发生「源码已改、装机仍是旧包」(教训锚:版本实装核查 A 组),实测是唯一可信验收。 首次使用:`/model add` 配置 LLM(API key / base url / model id),配置落 `~/Library/Application Support/ARES/`(macOS)/ `~/.local/share/ARES/`(Linux)。 ## 九、快速开始 ```bash $ ares-cli ╭──────────────────────────────╮ │ ARES · 会话 xxx 已就绪 │ ╰──────────────────────────────╯ > 帮我看看这个项目的登录模块怎么实现的 💭 我先搜索登录相关的 Controller... 🔧 search_symbol("LoginController") → 3 个定义 📖 读取 LoginController.java L1-120(📖 此前已读 0 次) ✅ 登录走 JWT + Redis 双 token,入口在... ``` **三种运行模式**: | 模式 | 命令 | 场景 | |---|---|---| | 交互 REPL | `ares-cli` | 日常使用,多轮对话 | | 单次执行 | `ares-cli -p "任务描述"` | 脚本化/CI | | 指定会话 | `ares-cli -p "任务" --session-id my-sid` | 恢复/新建指定会话 | **第一次使用建议**: 1. `/model add` 配 LLM → 2. 在项目根目录启动(工作空间=当前目录)→ 3. 直接自然语言下任务 4. 复杂任务 Agent 自动建计划(TaskTree 推送展示)逐项执行;长任务中断后重进提示挂起意图,输入「继续」接力 **会话与多会话**:会话存储 `~/Library/Application Support/ARES/sessions/`,`/new` 新开、`/sessions` 列出、`/resume ` 恢复;多终端各开一个 `ares-cli` 天然隔离(session_id + turn 粒度产物分层,结构性防串台)。 ## 十、斜杠命令速查 REPL 内输入 `/` 开头命令(注册于 `app/cli_commands.py`,**权威以 `/help` 实时输出为准**,此处为速查): | 类别 | 命令 | |---|---| | 会话 | `/new` `/new_session` 新会话 · `/sessions` 列会话 · `/resume ` 恢复 · `/history [N\|all\|prev]` 历史 · `/prev` 上一轮 · `/clear` 清屏 | | 模型/配置 | `/model add/list/use` LLM 配置 · `/models` 可用模型 · `/config` 当前配置 | | 知识/技能 | `/skills` 技能列表 · `/wiki` Wiki 记忆 · `/rules` 规则 · `/mcp` MCP 状态 | | 任务/诊断 | `/tasks` 任务树 · `/trace` 最近 trace · `/status` 运行状态 · `/env` 环境变量开关 | | 其他 | `/help` `/h` 帮助 · `/exit` `/quit` `/q` 退出 | 高频三招:`/model add`(首次配置)、`/resume`(接力中断任务)、`/trace`(排障先看 trace)。 ## 十一、架构与目录结构 ``` cli_main.py ──► app/cli_repl.py(REPL 主循环 + prompt_toolkit 输入层 + Rich Live 渲染) │ ▼ app/cli_setup.py(装配:工具池/技能/记忆/规则/MCP;双轨开关默认 unified) ▼ app/services/unified_agent/(★ 单 Agent 归一核心) ├── agent.py 主循环(LLM 调用/工具批执行/事件发射/外部化) ├── entry.py 装配栈(UnifiedFacade.process 单入口) ├── prompts.py system prompt 构建(北极星段/A103 天粒度时间块) ├── subtask_runner.py 并行子任务 └── tools.py 新工具注入 ▼ app/services/tool_executor.py(工具执行层:全部 FC 工具落点 + SKIP-DUP 拦截) app/services/fsm_agent/context_train.py(列车清单) app/services/read_governance.py(读取治理纯函数库) ``` ``` ares/ ├── ARES流程观察点CheckList.md # 治理度量手册(一~十四章,trace 审计对照) ├── README.md # 本文档 ├── backend/ │ ├── cli_main.py # CLI 入口(-p 单次 / REPL / --session-id) │ ├── app/cli_repl.py # REPL 主循环(4000+ 行) │ ├── app/cli_commands.py # 斜杠命令分发 │ ├── app/services/ │ │ ├── unified_agent/ # 单 Agent 归一核心(默认链路) │ │ ├── fsm_agent/ # 旧四角色链路(ARES_UNIFIED_AGENT=0 回退用) │ │ ├── tool_executor.py # 工具执行层 │ │ ├── wiki_manager.py / wiki_memory_service.py # Wiki 记忆+图检索 │ │ ├── skill_manager.py # Skills 索引 │ │ ├── audit_logger.py # 写操作审计快照 │ │ └── mcp/ # MCP Server 接入 │ ├── attic/ # 归档旧物(不维护) │ └── dev/analysis/ # 治理分析报告 + llm_concerns 申诉落盘 ├── frontend/ # 旧可视化界面(年久失修,仅存档不随版本发布) └── audit/ · workdir/ # 历史审计与迭代产物 ``` **环境开关速查**:`ARES_UNIFIED_AGENT=0` 回退旧链路 · `ARES_UNIFIED_EXTERNALIZE=0` 关外部化 · `ARES_MCP_FASTPATH=1` MCP 加速 · `ARES_EXTRA_BUILTIN_EXPERTS` 追加业务专家角色(JSON)。 ## 十二、排障与版本节点 **排障三步**: 1. `/trace` 定位最近 trace(或 `~/Library/Application Support/ARES/logs/traces/cli_*/trace.jsonl`,流式逐行处理) 2. 版本分段——先确认 `ares-cli --version` 与预期包一致(历史多次「源码已改、装机旧包」),只统计分界后事件 3. 文件改坏 → `get_operation_history` 查轨迹 → `restore_file` 快照还原;流程卡点 → 查 `dev/analysis/llm_concerns/` 申诉落盘 **版本节点速览**(完整版史见 `cli_main.py` 头部,每版含根因分析): | 版本 | 架构级节点 | |---|---| | v1.7.0 | 读取治理四件套(来源标注/重复读拦截/引导出路/ranges) | | v1.7.31 | 单 Agent 归一架构成为默认链路 | | v1.7.44/45 | 外部化阈值与开关 / 列车清单单槽刷新 | | v1.7.68 | 产物四层分层(session/turn 目录粒度) | | v1.7.99 | 历史瘦身(入史裁剪 + 幂等闸门) | | v1.9.5 | watch_command 代码态监控(10s 对比 + 60s 检查点) | | v1.9.8 | pure-base-v1:业务约束下沉应用层,基座回归通用 | | v1.9.24 | 外部化嵌套豁免强制治理 + 审计事件 | | v1.9.25 | 意图理解专项:预算型指令感知(打满/做满/预算N小时→收敛判据切预算剩余驱动)+ execute_command 纯读命令机制层拦截 + llm_io 日轮换 + REPL FileHistory 持久化 | | v1.9.26 | 清债三连:traces/llm_io 陈旧数据自动清理(trace_gc)+ search 0命中/截断降层引导(CJK 双轨判据)+ 管道 stdin EOF 退出保护(哨兵+旁路防确认门死锁) | | v1.9.27 | C130 豁免收紧为 python 执行语义 + 裁剪中段结构预告(文件/行号/符号指纹,35次trim实测)+ 预算三态判定打包态 e2e 实证 | | v1.9.28 | C177 预算时钟域修复:epoch/monotonic 混用根因(过期判定恒假+播报≈498321h 天文数字),epoch 基点归一 monotonic 域,四场景回归 ALL PASS——由讲义十轮挑战 R8 抓获 | | v1.9.29 | 第二波挑战 R66-75:C180 build 假成功根治(PyInstaller 预检+rc 双检查)+ C181 预算 label 残留/死代码 + C178 讲义锚点校验机制(check_lecture_anchors.py,68 锚点 0 超界)+ C182 版本代号窜位定谳 | > 本 README 22 项特性均经代码级 review 核到文件+行号(2026-11-03),无一虚标;评审过程本身即由本框架的 3 个并行子任务+任务树回写完成——框架吃自己的狗粮。 ---

Made with ☕ by the ARES team