这篇内容详细记录了从零开始构建AI编程助手Koder的全过程，深入剖析了Agent架构的核心细节。通过实际开发经验，揭示了工具调用、并发控制、流式输出等关键技术的实现原理，为理解AI编程助手的底层逻辑提供了独特视角。
智能速览
Koder是一个实验性质的终端AI编程助手，开源且可定制
通过懒加载设计优化Agent启动性能，避免不必要的资源消耗
StreamingDisplayManager解决了工具调用与文字输出交错的问题
实现了token感知的上下文压缩，有效控制长对话的Token消耗
工具注册采用装饰器模式，配合技能限制护栏实现精准权限控制
指数退避重试机制提高了API调用的稳定性
精华内容
从使用AI工具到亲手打造一个，这种转变带来的认知提升远超预期。下面深入探讨Koder架构中的几个关键设计细节。
启动流程优化
Koder采用了懒加载设计来优化启动性能。AgentScheduler初始化时并不直接创建Agent，而是等到收到第一条消息时才调用_ensure_agent_initialized()方法。创建Agent需要加载工具、连接MCP服务器、初始化模型客户端等重操作，如果用户只是查看配置，没必要启动整个Agent。这个设计能显著节省资源，提升响应速度。
CLI入口会先解析参数，然后加载当前目录的AGENTS.md作为项目上下文。这是AI Agent的标配设计，每个项目可以有自己的指令文件，定义技术栈、代码规范等，让Agent的输出更贴合项目实际。
流式输出管理
流式输出是开发中最耗时的部分。Agent的输出是交错的：可能先输出文字，然后发起多个工具调用，工具执行完又继续输出文字。如果不处理，用户看到的内容会杂乱无章。
解决方案是StreamingDisplayManager，维护一个pending_tool_calls计数器。只有计数器为零时才立即显示文字；如有工具调用在进行，文字先缓存，等所有工具完成再输出。同时用active_tool_calls字典以call_id为key存储调用记录，确保结果精准匹配。对于没有call_id的特殊情况，退化成先进先出队列模式。
工具权限控制
工具通过装饰器注册：@function_tool def read_file(model: FileReadModel) -> str。所有工具通过get_all_tools()收集，然后动态挂上skill_restriction_guardrail护栏。
护栏检查当前激活的Skill是否允许使用该工具。比如只能文件读写的Skill，就无法调用Shell命令。这种设计把工具定义和权限控制解耦，开发者专注工具功能，权限统一由护栏处理，维护更方便。
会话管理优化
长对话会导致Token消耗激增。EnhancedSQLiteSession继承OpenAI Agents SDK的SQLiteSession，增加了token感知的上下文压缩功能。
每次添加消息时用tiktoken估算Token数，超过阈值(默认50k)自动触发压缩：保留所有用户消息(代表核心需求)，对Assistant回复进行摘要。这样既不丢失关键需求，又有效控制上下文长度，减少Token消耗，避免响应变慢或出错。目前实现还比较简陋，后续会优化更多Context Engineering实践。
错误处理机制
LLM API偶尔抽风是常态，必须做好错误处理。RetryingLitellmModel封装了指数退避重试机制：@backoff.on_exception(backoff.expo, (ServiceUnavailable, RateLimit, APIConnection, Timeout), max_tries=3, jitter=backoff.full_jitter)
遇到服务不可用、限流、连接错误、超时等异常时自动重试3次，间隔按指数增长并加入随机抖动，避免多个重试同时发起。在API调用高峰期特别有用，第一次失败往往第二次就能成功。
通过亲手构建Koder，对AI Agent的理解从表面深入到骨髓。真正的技术成长来自于实践中的探索，就像学游泳必须跳进水里。在AI Agent大潮中，与其旁观不如入局，亲手拆解构建一个属于自己的Agent，收获将远超预期。
