详细数据流转1️⃣ 用户发起指令与系统组装 (CLI Initialization)用户动作在终端输入 RuiZNrun --goal 读取当前目录下的 README.md。数据流转cli/main.py接收到原生命令行参数argparse将其解析为字符串goal。AgentRunner启动生成全局唯一的run_id如20260722-182000-a1b2c3并创建ExecutionContext将goal写入上下文作为初始目标。建立订阅网络AgentRunner将负责终端 UI 的StdoutPrinter和负责写日志的EventWriter绑定到EventBus上。发布起点事件EventBus广播RunStartedEventEventWriter收到后立刻在events.jsonl中追加写入第一行 JSON 数据并flush刷盘。2️⃣ 第一次 Loop发送 Context 给 LLM (Plan 阶段)数据流转AgentLoop读取当前ExecutionContext中的messages此时包含系统 prompt 和用户的goal。构造 API 请求AnthropicProvider从ToolRegistry获取所有工具的 Schema如ReadFileTool的输入参数结构并向systemprompt 和工具列表末尾注入cache_control: {type: ephemeral}标记。发起 HTTP/gRPC 流式请求数据发送给 Anthropic Claude API。流式 Token 处理API 逐字返回文本 ChunkAnthropicProvider捕获到 Chunk 后向EventBus发布LlmTokenEvent。StdoutPrinter收到LlmTokenEvent调用print(token, end, flushTrue)在终端呈现打字机效果并将内部标志位_inline置为True表示当前处于未换行的流式输出状态。3️⃣ LLM 决策使用工具 (Observe 阶段)数据流转API 响应接收完毕LLM 判断需要调用工具返回响应stop_reason:tool_usecontent: 包含ToolCallBlock(idcall_123, nameread_file, input{path: README.md})解析与入栈AnthropicProvider将其包装为LlmResponse数据对象并返回给AgentLoop。AgentLoop将 LLM 的这条带有tool_use的assistant消息完整追加到ExecutionContext.messages中作为对后续工具调用的上下文约束。4️⃣ 安全调度与工具执行 (Act Result 阶段)数据流转响应格式化AgentLoop发现 LLM 的返回中包含tool_calls发起invoke_tool()调用。发布启动事件向EventBus发布ToolCallStartedEvent。StdoutPrinter收到事件检查到_inline True先调用_ensure_newline()补打一个\n换行然后再打印[tool] read_file {path: README.md}避免日志与流式 Token 粘在一起。安全拦截与执行以ReadFileTool为例路由查找ToolRegistry查找是否存在名为read_file的工具。必填校验校验path参数是否存在。安全防线 1路径检查检查path中是否包含..。若包含直接抛出PermissionError安全防线 2超时控制通过asyncio.wait_for(..., timeout10.0)执行异步读取安全防线 3内存防爆读取文件二进制流若超过512KB截断前面部分并追加\n[truncated]。封装结果若成功返回ToolResult(content文件内容..., is_errorFalse)。若报错例如文件不存在或越界被invoke_tool()内部的try...except捕获不让异常抛出崩溃而是转换为ToolResult(contentPermissionError: ..., is_errorTrue)。写回上下文AgentLoop将ToolResult包装成user角色的tool_result格式追加回ExecutionContext.messages如果一轮中有多个工具调用ExecutionContext内部会自动进行数据合并。5️⃣ 第二次 Loop 与优雅收尾 (Final Step Termination)数据流转再次发起 API 请求AgentLoop带有最新的messages包含上一步读取到的文件内容/错误信息再次调用AnthropicProvider。缓存命中因为头部 Prompt 和 Tools 未变Anthropic 服务端直接命中 Prompt Caching响应速度大幅提升。生成最终回答LLM 结合文件内容生成总结文本通过流式 Token 实时打字呈现在终端。检测终止标志本次 API 返回的stop_reason end_turn且没有新的tool_calls。AgentLoop识别到任务完成退出while循环更新context.status success。生命周期闭环 (AgentRunner)AgentRunner捕获到 Loop 结束向EventBus发布RunFinishedEvent。StdoutPrinter打印最终统计日志如[run] success 2 steps 1.5s。EventWriter写入最后一条 JSONL 日志在async with上下文退出时安全关闭events.jsonl文件句柄。整个进程以 Exit Code0干净退出。核心组件与名称含义全解析1. 入口与生命周期管理层 (CLI Lifecycle)RuiZN含义与职责本 AI Agent 框架的 CLI 命令行工具名称。main.py/commands.py含义与职责CLI 命令入口。解析参数如--goal捕获系统级信号如 UNIX SIGINT /KeyboardInterrupt并驱动异步主协程启动。AgentRunner(运行组装车间)含义与职责Agent 的“工厂与收尾车间”。干什么的生成本次调用的唯一编号run_id如20260511-161020-abc123。实例化并组装所有零散组件EventBus, ExecutionContext, Provider, Registry。注册订阅者StdoutPrinter和EventWriter。负责安全收尾无论 Agent 是成功退出、超步数崩溃还是被CtrlC中断都保证发布RunFinishedEvent并在安全关闭日志文件后再重新抛出CancelledError。2. 状态与内存管理层 (Context Events)ExecutionContext(工作记忆与状态机)含义与职责Agent 的“大脑内存卡”与“运行状态追踪器”。干什么的存储当前任务的goal、run_id、当前步数step、终止状态status以及核心的对话历史messages。关键细节封装了 Anthropic API 的消息合并逻辑同一轮次中的多个tool_result必须合并进同一条user消息中。EventBus(事件总线)含义与职责解耦的“内部广播中心”。干什么的维护订阅者列表_subscribers。当 Loop、Tool 或 Provider 发生关键动作时发布事件如 Token 生成、工具启动、运行完成总线按顺序并发通知所有订阅者。EventWriter(日志写入器)含义与职责持久化“黑匣子”日志记录员。干什么的订阅 EventBus每收到一个事件就将其序列化为 JSON 并立刻写入events.jsonl文件无缓冲区打折强制flush保证进程突发崩溃时日志不丢失。StdoutPrinter(终端输出格式化器)含义与职责终端 UI 渲染控制者。干什么的订阅 EventBus将事件转化为终端看得懂的打印输出。关键细节维护_inline标志位。当 LLM 处于流式打字机输出状态未换行时突然收到工具调用通知_ensure_newline()会先自动补全一个换行避免输出混成一团。3. 大模型与通信层 (LLM Provider)AnthropicProvider(模型适配器)含义与职责与 Anthropic (Claude) API 通信的底层驱动。干什么的封装流式请求Streaming将 API 返回的文本片段实时转化为LlmTokenEvent抛给 EventBus同时负责将本地ToolRegistry的工具定义转为 API 格式。Prompt Caching(提示词缓存机制)含义与职责API 成本与性能优化手段。干什么的在systemprompt 和tools列表末尾加上cache_control: {type: ephemeral}标记让后续轮次的重复上下文命中服务端缓存降低 90% 的 Token 费用并加快响应。4. 主循环控制器 (Control Loop)AgentLoop(主循环状态机)含义与职责Agent 的“核心发动机/调度控制器”。干什么的驱动Observe ──► Act状态循环。按顺序完成调用 LLM 决策 $\rightarrow$ 记录 LLM 回复到上下文 $\rightarrow$ 执行工具 $\rightarrow$ 记录工具返回结果 $\rightarrow$ 检查终止条件如end_turn或达到max_steps。5. 工具系统 (Tool System)BaseTool(工具基类/模板)含义与职责所有工具必须遵循的抽象接口规范继承自abc.ABC。干什么的定义工具的元数据name,description,input_schema并强制实现async def invoke()方法。ToolResult(工具返回数据结构)含义与职责工具执行结果的标准数据包dataclass。核心字段content: str给 LLM 看的工具输出内容。is_error: bool标记工具执行是否出错即使出错也不抛出 Python 异常而是作为结果返回。error_type: str | None错误类型标记如timeout,permission_error,runtime_error。ToolRegistry(工具注册表)含义与职责工具的“仓库管理者”。干什么的维护工具字典_tools。提供tool_schemas()方法直接导出适配 Anthropic API 的tools格式供 LLM 了解当前可用的工具列表。invoke_tool()(安全执行包装器)含义与职责工具调用的“安全隔离舱/调度员”。干什么的查找与校验检查工具是否存在、必填参数required是否缺失。超时控制使用asyncio.wait_for(..., timeout10.0)防死锁。异常捕获与_fail()兜底捕获所有运行时报错与超时不让异常冒泡到AgentLoop统一转为带is_errorTrue的ToolResult。ReadFileTool(内置读取文件工具)含义与职责S1 阶段内置的具体工具示例。内部三层安全边界防路径穿越若路径包含..则抛出PermissionError禁止读取上层路径。防内存/Token 溢出文件超过512KB时自动截断并在末尾追加\n[truncated]告知 LLM。错误转化触发任何错误后由invoke_tool()捕获并转为错误结果给 LLM触发 LLM 的自我纠错机制。
