Qoder 从入门到精通
大规模工程 Harness 实践

Code Agent 架构原理——通用设计，而非 Qoder 专属 ​

前七章讲的都是 Qoder 的具体功能。但这一章不一样——我们不讨论 Qoder，而是讨论所有 Code Agent 背后的通用架构。

Qoder、Claude Code、Cursor、GitHub Copilot……市面上每一款 AI 编程工具，底层都跑着同一套设计原理。了解了这套原理，你就理解了所有 Code Agent 的能力边界和运行方式，用任何工具都会更有优势。

ReAct——思考和行动的循环 ​

所有 Code Agent 的核心都是 ReAct（Reasoning + Acting），一种"思考→行动→观察→再思考"的循环模式。

用户说："把这段代码提取成独立函数"
   ↓
1. LLM 推理（Thinking）→ "我需要先看这段代码在哪，理解它的依赖关系"
   ↓
2. 工具调用（Action）→ 调用 `grep` 搜索代码位置，`read` 读取文件
   ↓
3. 观察结果（Observation）→ 看到代码内容、上下文、依赖的变量和函数
   ↓
4. LLM 再推理（Thinking）→ "这里需要提取出函数，参数包括 dbContext 和 userId"
   ↓
5. 工具调用（Action）→ 调用 `edit` 修改文件，提取独立函数
   ↓
6. 观察结果（Observation）→ 检查 diff，确认编译通过
   ↓
...持续循环直到任务完成
   ↓
最终输出结果给用户

这不是魔法。每次"思考"就是一次 LLM 调用，每次"行动"就是一个工具函数的执行。Agent 就是在循环里反复跑：想一下 → 干一步 → 看看结果 → 再想下一步。

这就是为什么 Agent 比单轮 Chat 强——它不只是"你说一句，它回一句"，它可以在循环中自主决定下一步做什么。

Event Loop——驱动循环的引擎 ​

ReAct 循环图

ReAct 是模式，Event Loop（事件循环） 是把它跑起来的引擎。它的代码结构极其简单：

python
class CodeAgent:
    def __init__(self, tools, llm):
        self.tools = {t.name: t for t in tools}
        self.llm = llm
        self.history = []  # 完整的消息历史

    async def run(self, user_input: str):
        # 1. 把用户输入加到消息历史
        self.history.append({"role": "user", "content": user_input})

        # 2. 持续循环，直到 LLM 决定停止
        while True:
            # 思考：调用 LLM
            response = await self.llm.think(self.history)

            if response.has_tool_call:
                # 行动：执行工具
                tool_name = response.tool_call.name
                tool_args = response.tool_call.arguments
                result = await self.tools[tool_name].execute(**tool_args)

                # 观察：把结果加回历史
                self.history.append({
                    "role": "tool",
                    "name": tool_name,
                    "content": result
                })
                # 继续循环 → 回到 LLM 再思考
            else:
                # 没有工具调用 → 任务完成
                return response.text

关键设计决策就一个：循环的终止条件由 LLM 自己决定。它输出文本（最终答案）就停，输出工具调用就继续循环。

这就是所有 Code Agent 的通用骨架。Qoder 的 Agent 模式、Cursor 的 Agent、Claude Code 都是这个骨架的变体——差别只在于工具有哪些、LLM 是什么、消息历史如何管理。

Tool System——Agent 的双手 ​

有了大脑（LLM）和循环（Event Loop），还需要双手（Tools）。所有 Code Agent 都会提供一套操作代码的工具集，最核心的五个：

read——读取文件 ​

最基本也最常用的操作。Agent 需要先理解代码才能修改它。

python
async def read(path: str, start_line: int = None, end_line: int = None) -> str:
    """读取文件内容。建议只读当前需要看的部分，不要全量读入。"""

write——创建或覆写文件 ​

当 Agent 确认需要创建新文件或整体替换时使用。

python
async def write(path: str, content: str) -> None:
    """创建新文件或完全覆写已有文件。"""

search——搜索代码内容 ​

原名 grep，按正则或关键字搜索代码。这是 Agent 理解项目结构的关键——不需要人告诉它代码在哪，它自己搜。

python
async def search(pattern: str, path: str = ".") -> list[SearchResult]:
    """搜索匹配的内容，返回文件路径和行号。"""

glob——按文件名定位 ​

按通配符找文件名，常用于"找到这个目录下所有测试文件"。

python
async def glob(pattern: str) -> list[str]:
    """按通配符搜索文件路径。"""

edit(或 search_replace)——精确修改文件 ​

这是最精细的工具。不是整文件替换，而是指定原文和目标文，精确替换。

python
async def edit(path: str, original: str, new: str) -> None:
    """在已有文件中找到原文并替换为目标文。"""

其他工具 ​

根据具体的 Agent 实现，还会提供：

  • terminal/run：在终端执行命令
  • thinking：思维链暂存区（不输出给用户，先自己想想）
  • list_dir：列出目录内容
  • file_tree：文件树概览

为什么就这五个 ​

这五个工具覆盖了所有 Code Agent 需要的核心操作：读、写、搜、找、改。任何代码任务都可以通过这五个操作的组合来完成。所以你会看到 Qoder 有 Read/Write/Grep/Glob/SearchReplace，Claude Code 也有类似的一套——名字可能不同，本质是一样的。

为什么了解这些很重要 ​

知道了 ReAct + Event Loop + Tool System 这套通用架构，你会有三个实际好处：

1. 知道 Agent 的能力边界在哪

Agent 能做的事取决于它的工具有哪些。如果你需要 Agent 执行一个不在工具集中的操作（比如直接操作数据库），要么给 Agent 加工具（MCP），要么换个方式描述需求。

2. 知道怎么写更好的提示词

理解了 ReAct 循环，你就知道为什么"一步步思考"这个提示词有效——它在提示 LLM 在 Event Loop 中多做几次推理迭代，而不是急着给出答案。

3. 跨工具迁移无成本

这套架构对 Qoder、Claude Code、Cursor、Copilot 都适用。你在这本书里学的 Qoder 使用技巧，换一个工具 80% 仍然有效——本质上都是同一个 ReAct 循环的不同皮肤。

那 Qoder 的架构是什么 ​

坦率地说，我们并不知道 Qoder 内部的具体实现。它可能有自己的装饰器管道、自己的 Agent 编排引擎、自己的上下文管理策略。但不管它怎么实现，它逃不出 ReAct + Event Loop + Tool System 这个通用框架。

前几章讲到的 Qoder 五大核心（Agent、Skill、Rule、Memory、MCP），本质上就是在 ReAct 循环的各个环节加料：

五大核心在 ReAct 循环中的位置作用
Agent整个循环驱动 ReAct 的执行引擎
SkillAction 环节告诉 Agent 按什么流程调用工具
RuleThinking 环节在 LLM 推理时注入约束条件
MemoryObservation 环节提供项目上下文，让观察更准确
MCPAction 环节扩展工具集，让 Agent 能做更多事

理解了这个关系，你就理解了前七章的每一章在全局中扮演什么角色。也理解了我们为什么花这么大篇幅讲 Skill 和 Rule——它们是唯一能让用户主动影响 ReAct 循环的环节。

产品实现：可视化工作流编排 ​

上述 ReAct + Event Loop + Tool System 的架构在 Growth AIOS 产品中落地为可视化的工作流编辑器。每个节点代表一个工具调用或 Agent 执行，节点间通过输入/输出端口连接，形成完整的自动化流程：

编辑器中可以看到多种节点类型：搜索文件、循环、裁剪头尾（视频处理）、代码执行、运行程序、Coze/Qoder Cloud Agent 等。每个节点都有明确的输入输出端口定义，循环体内嵌套子节点，形成完整的流程控制结构。

Growth AIOS 产品参考 ​

以下为 Growth AIOS 产品中对应的工作流编排界面截图：

工作流库工作流编辑器——节点编排与输入输出