RA.Aid — 总览与阅读地图
30 秒导读: RA.Aid（读作 "raid"）是一个在终端里跑的自主编码 agent——你给它一句自然语言任务，它会像一个工程师那样，先研究你的代码库、再规划出分步的实现计划、然后逐步实现这些步骤(改文件、跑命令)。它建在 LangGraph 之上，用一个本地 SQLite 数据库当"长期记忆"在这三个阶段之间传递上下文。
本章是这一组文档的入口：只讲全景、不下钻代码细节。看完你应该能说清"RA.Aid 是什么、大致怎么转、该按什么顺序读后面各章"。具体机制留给 01–05 章。
1. 这是什么(零基础也能懂)
一句话定义: RA.Aid 是一个能自主开发软件的命令行编码 agent——安装后你得到一个 ra-aid 命令，在项目目录里运行它、给它一个任务，它就自己动手把任务做完。
它的入口就是这条命令。pyproject.toml:74-75 里把 ra-aid 这个命令绑定到 Python 函数 ra_aid.__main__:main：
[project.scripts]
ra-aid = "ra_aid.__main__:main"
建立在什么之上: RA.Aid 不自己发明"agent 循环"，而是站在 LangGraph(LangChain 的 agent 执行框架，负责"模型思考→调用工具→看结果→再思考"的循环)之上。它还可选集成 aider(一个专门做代码编辑的工具)——加 --use-aider 开关就用 aider 来落地改动，否则用自带的文件编辑工具。
解决什么问题 / 给谁用: 给需要在真实、较大代码库里做多步开发任务的工程师。普通的"单次 code 补全"只能改一小段；RA.Aid 面向那种"要先读懂现有架构、再拆成若干步、再一步步改多个文件"的活。README 把这一点概括为它能跨多个文件规划并实现较大的代码改动、也能回答关于代码库架构的问题。
用起来什么样: 最小用法就是一行命令 + 一句任务(示意):
# 在你的 git 项目里
ra-aid -m "给用户模块加上邮箱格式校验，并补上单元测试"
⚠ 它会真的执行 shell 命令、真的改代码（README 明确警告）。所以官方建议只在受版本控制的仓库里用、改完先看
git diff。--cowboy-mode开关会跳过 shell 命令的人工确认——威力更大，风险也更大。
README 的"三阶段"卖点，用白话复述: 它把"开发一个功能"这件事拆成三步，依次做——
| 阶段 | 白话它在干嘛 |
|---|---|
| Research(研究) | 先读你的代码库、搞清楚现状和相关文件，攒下"关键事实/代码片段" |
| Planning(规划) | 把任务拆成一条条具体、可执行的步骤 |
| Implementation(实现) | 一步一步落地：改文件、跑命令、跑测试 |
一句话直觉: 把它想成一个照着"先调研、再列计划、再动手"工作法办事的初级工程师——你给需求，它自己走完这套流程，而不是一上来就瞎改。
2. 顶层全景(它大概怎么转)
怎么读这张图
从上到下是控制流：一条 ra-aid 命令进入 __main__.main()，先起研究阶段；研究阶段的 agent 在它自己的循环里用一个"请求实现"的工具把接力棒交给规划阶段，规划阶段再用"请求任务实现"的工具把每个计划步骤交给实现阶段。三个阶段都不是"硬编码顺序调用"，而是agent 通过调用工具自己触发下一棒(详见 01 章)。左侧竖线是共享底座：所有阶段都从同一个 agent 工厂拿到 agent、共用工具箱、共用 SQLite 记忆。
ra-aid -m "任务"
│
▼
┌──────────────────────────────────┐
│ CLI 入口 __main__.main() │ 解析参数、建 Session、起第一阶段
└──────────────────────────────────┘
│ 起研究阶段
▼
┌───────────┐ 请求实现 ┌───────────┐ 请求任务实现 ┌───────────────┐
│ ① 研究 │────────────▶│ ② 规划 │──────────────▶│ ③ 实现 │
│ research │ (工具触发) │ planning │ (每步一个) │ implementation │
│ _agent │◀─ ─ ─ ─ ─ ─ │ _agent │ │ _agent │
└───────────┘ 攒事实/片段 └───────────┘ 计划(plan) └───────────────┘
│ │ │
└───────────┬──────────────┴──────────────┬───────────┘
▼ ▼
┌──────────────────────────┐ ┌──────────────────────────────┐
│ 共享 agent 工厂 │ │ 工具箱 │
│ agent_utils.create_agent │ │ tool_configs + tools/ │
│ ├ ReAct 后端 │ │ (读文件/搜代码/改文件/专家/HIL) │
│ └ CIAYN 后端(代码即调用)│ └──────────────────────────────┘
└──────────────────────────┘
│ 所有阶段读写同一份记忆
▼
┌──────────────────────────────────────────┐
│ SQLite 记忆 database/ (peewee ORM) │
│ Session / KeyFact / KeySnippet / │
│ ResearchNote / Trajectory(成本&轨迹) │
└──────────────────────────────────────────┘
部件一句话职责
| 部件 | 干什么 | 文件 |
|---|---|---|
| CLI 入口 | 解析命令行、建 Session、初始化模型与记忆、启动 研究阶段 | ra_aid/__main__.py(main) |
| 三阶段 agent | 研究 / 规划 / 实现各一个 runner 函数，各自带专属 prompt 与工具子集 | ra_aid/agents/research_agent.py、planning_agent.py、implementation_agent.py |
| 阶段接力工具 | agent 用它触发下一阶段(研究→规划→实现) | ra_aid/tools/agent.py(request_implementation、request_task_implementation) |
| 共享 agent 工厂 | 按模型能力造出一个 agent，挑 ReAct 或 CIAYN 后端 | ra_aid/agent_utils.py(create_agent) |
| 两种后端 | ReAct(用模型原生 function-calling)；CIAYN(模型不支持函数调用时，让它输出代码来调工具) | langgraph.create_react_agent / ra_aid/agent_backends/ciayn_agent.py(CiaynAgent) |
| 工具箱 | 按阶段裁出该阶段能用的工具集合(只读/修改/研究/专家/HIL) | ra_aid/tool_configs.py + ra_aid/tools/ |
| SQLite 记忆 | 用 peewee ORM 把事实、片段、笔记、轨迹落到本地库，跨阶段共享 | ra_aid/database/(models.py、repositories/) |
主线走一遍(高层，不进代码)
- 你运行
ra-aid -m "..."，main()(ra_aid/__main__.py:1106)解析参数、建好本次运行的Session记录，然后只启动研究阶段——它不硬编码三步顺序。 - 研究 agent(
run_research_agent,ra_aid/agents/research_agent.py:76)读你的代码库，把有用的东西以"关键事实 / 关键代码片段 / 研究笔记"的形式写进 SQLite。研究完成时，它调用request_implementation工具把棒子交给规划。 - 规划 agent(
run_planning_agent,ra_aid/agents/planning_agent.py:69)读到刚才那些记忆，产出一份分步计划，并对计划里每一步调用request_task_implementation。 - 每次调用都起一个实现 agent(
run_task_implementation_agent,ra_aid/agents/implementation_agent.py:51)，它拿到这一步的规格 + 之前所有记忆，真正去改文件、跑命令、跑测试。 - 记忆是暗线：三个阶段本身是独立的 agent 运行，彼此不直接传参，而是都读写同一份 SQLite——上一阶段攒下的事实/片段/计划，下一阶段开局就注入进 prompt。这就是"上下文在阶段间传递"的真实机制(03 章细讲)。
3. 阅读地图(建议顺序)
后面五章由浅入深。建议按顺序读；只关心某一点也可以直接跳。
| 章 | 讲什么 | 什么时候读 |
|---|---|---|
| 01 三阶段主线与 CLI 编排 | main() 如何起步、三阶段如何靠 工具接力串起来、Session/计划怎么流动 | 想先看懂"整条主线怎么跑通"——优先读这章 |
| 02 两种 agent 后端:ReAct 与 CIAYN | create_agent 如何按模型能力选后端；CIAYN 如何让"不支持函数调用"的模型也能用工具——代码即工具调用 | 想懂 RA.Aid 最独特的技术点 |
| 03 记忆与持久化 | SQLite 表结构(事实/片段/笔记/会话)、上下文如何跨阶段注入、记忆 GC 如何防膨胀 | 想懂"agent 的长期记忆"怎么实现 |
| 04 工具箱、专家模型与人类协作 | 每个阶段能用哪些工具、如何"临时升级到更强的专家模型"啃硬骨头、如何在关键点问人 | 想加/改工具，或理解 expert 与 HIL |
| 05 健壮性:重试、回退、裁剪与成本 | API 出错的重试、工具连续失败后的模型回退、Token 裁剪防溢出、每步成本与轨迹追踪 | 想懂它在真实环境里如何"不轻易崩" |
4. 巧妙之处速览
每条一句话，详见对应章。这是读完这套文档你该带走的"精华"。
- CIAYN(Code Is All You Need,代码即工具调用): 对不支持原生 function-calling 的模型，让它直接输出一段 Python 代码来调用工 具，RA.Aid 用
eval()执行这段代码——把"工具调用"变成"写代码"。见ra_aid/agent_backends/ciayn_agent.py:691(_execute_tool里的eval(code, globals_dict))。→ 02 章 - SQLite 当长期记忆 + GC: 关键事实/片段既是跨阶段的上下文载体，又会在数量超阈值时由专门的"垃圾回收 agent"删掉最没价值的条目，防止记忆无限膨胀。见
ra_aid/agents/key_facts_gc_agent.py(delete_key_facts)。→ 03 章 - 专家模型升级: 平时用普通模型，遇到难题时把上下文喂给一个更强的"专家/推理模型"求解,再把答案带回主流程。见
ra_aid/tools/expert.py(emit_expert_context、ask_expert)。→ 04 章 - Fallback 重试与模型回退: agent 运行带重试;工具连续失败到阈值时触发
FallbackHandler切换到备用工具/模型。见ra_aid/agent_utils.py:567(run_agent_with_retry)、ra_aid/fallback_handler.py:25(FallbackHandler)。→ 05 章 - 轨迹与成本追踪: 每一步工具调用连同它的 token 用量和花费都落进
Trajectory表,可回放、可核算成本。见ra_aid/database/models.py:239(Trajectory.current_cost/input_tokens/output_tokens)。→ 05 章
5. 代码地图(导 航索引)
顶层锚点，指向各章真正下钻的位置。符号名比行号抗漂移——行号失效时用符号名 grep。
| 主题 | 文件 | 符号 |
|---|---|---|
| 命令入口(命令→函数) | pyproject.toml:74 | [project.scripts] ra-aid = ra_aid.main:main |
| CLI 主流程、起研究阶段 | ra_aid/__main__.py:1106 | main |
| 研究阶段 runner | ra_aid/agents/research_agent.py:76 | run_research_agent |
| 规划阶段 runner | ra_aid/agents/planning_agent.py:69 | run_planning_agent |
| 实现阶段 runner | ra_aid/agents/implementation_agent.py:51 | run_task_implementation_agent |
| 阶段接力(研究→规划) | ra_aid/tools/agent.py:562 | request_implementation |
| 阶段接力(规划→实现) | ra_aid/tools/agent.py:391 | request_task_implementation |
| agent 工厂、选后端 | ra_aid/agent_utils.py:133 | create_agent |
| 后端选择(ReAct vs CIAYN) | ra_aid/model_detection.py:117 | should_use_react_agent |
| CIAYN 后端(代码即工具调用) | ra_aid/agent_backends/ciayn_agent.py:98 | CiaynAgent(_execute_tool:339) |
| 按阶段裁剪工具集 | ra_aid/tool_configs.py:204 | get_research_tools / get_planning_tools / get_implementation_tools |
| SQLite 数据模型 | ra_aid/database/models.py:113 | Session / KeyFact / KeySnippet / ResearchNote / Trajectory |
| 重试 + 回退 | ra_aid/agent_utils.py:567;ra_aid/fallback_handler.py:25 | run_agent_with_retry;FallbackHandler |
| 专家模型 | ra_aid/tools/expert.py:57 | emit_expert_context / ask_expert |
| 记忆 GC | ra_aid/agents/key_facts_gc_agent.py:35 | delete_key_facts |