Kaku终端AI引擎源码剖析Agent循环、流式事件与提示词缓存完整指南【免费下载链接】Kaku A fast, out-of-the-box terminal built for AI coding.项目地址: https://gitcode.com/gh_mirrors/kaku5/KakuKaku 是一款为 AI 编码打造的极速终端A fast, out-of-the-box terminal built for AI coding内置了完整的 AI 聊天引擎按CmdL呼出 AI 助手它能读文件、跑命令、搜代码还能自动续写任务。本文带你从源码层面拆解 Kaku 终端 AI 引擎的三大核心设计——Agent 循环、流式事件系统与提示词缓存帮你理解一个生产级终端 AI 助手是怎么做出来的 一、先认识引擎三个文件看懂整体架构Kaku 的 AI 引擎代码高度集中入门只需盯住三个地方模块路径职责共享聊天引擎ai_chat_engine/mod.rsAgent 循环、流式事件、系统提示词组装API 客户端ai_client.rsOpenAI 兼容 / Responses 双协议流式请求工具注册表ai_tools/registry.rs暴露给模型的全部函数工具与 JSON Schema这个引擎同时服务于两个入口GUI 里CmdL弹出的覆盖层以及独立的k命令行聊天见 cli_chat/mod.rs。注释里写得很清楚引擎不含任何 GUI 依赖纯 Rust 类型 消息通道这正是它能在两个表面复用且行为一致的原因。二、Agent循环让模型自主干满25轮的run_agent打开 mod.rsrun_agent函数就是整个引擎的心脏。它在独立后台线程上运行核心逻辑是一个简单的for循环调用模型(chat_step) → 有工具调用 ├─ 没有 → 发送 Done本轮结束 └─ 有 → 逐个执行工具 → 结果回灌 messages → 进入下一轮每轮开始前有三道防御性动作是源码里最值得抄的设计微压缩micro_compact调用 compact.rs 对上一轮的工具输出瘦身——fs_read只留前 300 行、grep_search只留前 100 行、shell_exec留头 100 行 尾 40 行超过 16KB 的超长输出只保留头 12KB 尾 3KB并插入[N bytes elided]标记。摘要折叠历史接近 120KB 预算时优先用更便宜的 fast_model做一次原地摘要而不是硬截断摘要失败会进入 3 轮冷却避免每轮都发一次阻塞请求。软警告第 20 轮SOFT_ROUND_WARN时向消息历史注入一条只剩 5 轮请收尾的提醒引导模型自己总结收尾而不是硬生生砍在任务中间。循环上限是MAX_AGENT_ROUNDS 25。触发上限时不会静默失败而是发送一条明确的错误事件告诉用户任务可能只做了一半可以继续追问。审批门写操作必须经人点头工具执行前有一道安全关卡见 approval.rs凡是变更类操作如fs_write、fs_delete、fs_patchAgent 线程会发出ApprovalRequired事件并阻塞等待——渲染端弹出确认框用户点允许后通过SyncSenderbool回复最长等待 600 秒超时视为拒绝。模型还会收到一条用户拒绝了该操作的工具错误从而自我纠正而不是死循环重试。三、流式事件10个StreamMsg消息撑起整个界面Agent 线程和渲染线程之间只靠一个mpsc::SenderStreamMsg通道通信事件定义极其干净事件触发时机AssistantStart模型即将输出文本渲染端插入空占位气泡Token/Reasoning正文 token / 隐藏的推理内容分开存储、分开渲染ToolStart/ToolDone/ToolFailed工具开始 / 完成带结果预览/ 失败ApprovalRequired需要同步审批携带回复通道ResponsesStateResponses 协议的无状态转录快照Done/Err结束 / 出错两个细节很见功力结果预览按工具定制fs_read显示共 N 行、grep_search显示N 条匹配、web_fetch显示抓取 N 字节tool_result_preview函数UI 状态栏因此紧凑可读。输出总量硬预算整轮用户对话最多向 UI 推送 480KB 的文本/推理内容MAX_STREAMED_OUTPUT_BYTES。超出即显式报错本轮是部分完成绝不把没执行完的工具轮次当成成功——这个宁错勿假的取舍是新手最容易忽略的健壮性设计。另外ai_client.rs 对 SSE 流也设置了层层熔断单行 1MB、事件数 65536、工具调用 32 次……防的是失控循环的流而不是限制正常长回答。四、提示词缓存设计三个省钱的隐藏技巧这是全文最精妙的一节。LLM 计费里系统提示词每轮都要重新发送如果前缀逐字节稳定就能命中 Anthropic 等厂商的提示词缓存折扣。Kaku 为此做了三层设计技巧1静态系统提示词 6个片段按固定顺序拼接build_system_prompt()用include_str!编译期内联 assets/prompts/chat/ 下的 6 个片段voice.txt人格与文风禁止 emoji、禁止列表、禁止 filler 套话safety.txt安全边界output_format.txt输出格式tool_discipline.txt工具调用纪律root_cause.txt根因分析要求external_helpers.txt外部工具使用固定顺序 每轮字节完全一致 缓存前缀天然稳定。每个片段开头还有!-- name: ... kakuVersion: 0.12.0 --元数据块由strip_prompt_metadata在运行时剥掉——这样文件可以版本化 diff注入的提示词却保持纯净。技巧2动态信息全部挪到环境消息日期、当前目录、locale、终端尺寸这些每轮都在变的字段坚决不放进系统提示词而是由build_environment_message()组装成一条独立的 user 消息排在提示词之后。源码注释直言其动机让静态系统提示词能命中 Anthropic 的 prompt-cache 折扣。技巧3MEMORY.md 故意避开缓存前缀Kaku 支持 Soul 机制SOUL/STYLE/SKILL/MEMORY 四个身份文件见 soul.rs。其中SOUL/STYLE/SKILL用户手写的稳定身份→ 追加在系统提示词末尾MEMORY.md后台管家模型自动改写的滚动记忆→ 放进环境消息注释写着避免管家改写记忆时每一轮都打爆提示词缓存。稳定内容前置、易变内容后置三条规则贯穿始终——这就是提示词缓存设计的全部心法 五、工具注册表模型能做什么由代码说了算registry.rs 中的all_tools()一次性声明了全部工具fs_read / fs_list / fs_write / fs_patch / fs_delete、shell_exec / shell_bg / shell_poll、grep_search / symbol_search、project_summary / file_tree、web_fetch / web_search、memory_read / soul_read、http_request。每个工具都是名称 描述 JSON Schema三件套。Agent 循环执行前会做白名单校验模型只准调用本轮实际宣告的工具。若模型模仿历史对话里的旧工具名比如切换搜索引擎前的web_search记录系统不杀轮次而是回一条该工具不可用的错误工具结果让模型自我纠正——错误信息也是上下文的一部分这比直接崩溃优雅得多。六、新手能带走的3个设计要点Agent 循环本质是带预算的 while轮数25、历史字节120KB、输出字节480KB三道预算 摘要降级 软警告收尾缺一不可。事件驱动比回调简单十倍一个枚举 一条 mpsc 通道就能把模型思考中 → 工具运行中 → 等待审批的复杂状态干净地推给 UI。提示词是产品也是工程静态化、分段化、版本化、易变内容后置——省的是真金白银的 token 费用。想继续深挖推荐阅读顺序mod.rsAgent 循环→ compact.rs上下文瘦身→ ai_client.rs流式协议→ assets/prompts/提示词全文。看完你会发现一个优秀的终端 AI 引擎靠的不是魔法而是每一处都写清楚的取舍。【免费下载链接】Kaku A fast, out-of-the-box terminal built for AI coding.项目地址: https://gitcode.com/gh_mirrors/kaku5/Kaku创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Kaku终端AI引擎源码剖析：Agent循环、流式事件与提示词缓存完整指南
Kaku终端AI引擎源码剖析Agent循环、流式事件与提示词缓存完整指南【免费下载链接】Kaku A fast, out-of-the-box terminal built for AI coding.项目地址: https://gitcode.com/gh_mirrors/kaku5/KakuKaku 是一款为 AI 编码打造的极速终端A fast, out-of-the-box terminal built for AI coding内置了完整的 AI 聊天引擎按CmdL呼出 AI 助手它能读文件、跑命令、搜代码还能自动续写任务。本文带你从源码层面拆解 Kaku 终端 AI 引擎的三大核心设计——Agent 循环、流式事件系统与提示词缓存帮你理解一个生产级终端 AI 助手是怎么做出来的 一、先认识引擎三个文件看懂整体架构Kaku 的 AI 引擎代码高度集中入门只需盯住三个地方模块路径职责共享聊天引擎ai_chat_engine/mod.rsAgent 循环、流式事件、系统提示词组装API 客户端ai_client.rsOpenAI 兼容 / Responses 双协议流式请求工具注册表ai_tools/registry.rs暴露给模型的全部函数工具与 JSON Schema这个引擎同时服务于两个入口GUI 里CmdL弹出的覆盖层以及独立的k命令行聊天见 cli_chat/mod.rs。注释里写得很清楚引擎不含任何 GUI 依赖纯 Rust 类型 消息通道这正是它能在两个表面复用且行为一致的原因。二、Agent循环让模型自主干满25轮的run_agent打开 mod.rsrun_agent函数就是整个引擎的心脏。它在独立后台线程上运行核心逻辑是一个简单的for循环调用模型(chat_step) → 有工具调用 ├─ 没有 → 发送 Done本轮结束 └─ 有 → 逐个执行工具 → 结果回灌 messages → 进入下一轮每轮开始前有三道防御性动作是源码里最值得抄的设计微压缩micro_compact调用 compact.rs 对上一轮的工具输出瘦身——fs_read只留前 300 行、grep_search只留前 100 行、shell_exec留头 100 行 尾 40 行超过 16KB 的超长输出只保留头 12KB 尾 3KB并插入[N bytes elided]标记。摘要折叠历史接近 120KB 预算时优先用更便宜的 fast_model做一次原地摘要而不是硬截断摘要失败会进入 3 轮冷却避免每轮都发一次阻塞请求。软警告第 20 轮SOFT_ROUND_WARN时向消息历史注入一条只剩 5 轮请收尾的提醒引导模型自己总结收尾而不是硬生生砍在任务中间。循环上限是MAX_AGENT_ROUNDS 25。触发上限时不会静默失败而是发送一条明确的错误事件告诉用户任务可能只做了一半可以继续追问。审批门写操作必须经人点头工具执行前有一道安全关卡见 approval.rs凡是变更类操作如fs_write、fs_delete、fs_patchAgent 线程会发出ApprovalRequired事件并阻塞等待——渲染端弹出确认框用户点允许后通过SyncSenderbool回复最长等待 600 秒超时视为拒绝。模型还会收到一条用户拒绝了该操作的工具错误从而自我纠正而不是死循环重试。三、流式事件10个StreamMsg消息撑起整个界面Agent 线程和渲染线程之间只靠一个mpsc::SenderStreamMsg通道通信事件定义极其干净事件触发时机AssistantStart模型即将输出文本渲染端插入空占位气泡Token/Reasoning正文 token / 隐藏的推理内容分开存储、分开渲染ToolStart/ToolDone/ToolFailed工具开始 / 完成带结果预览/ 失败ApprovalRequired需要同步审批携带回复通道ResponsesStateResponses 协议的无状态转录快照Done/Err结束 / 出错两个细节很见功力结果预览按工具定制fs_read显示共 N 行、grep_search显示N 条匹配、web_fetch显示抓取 N 字节tool_result_preview函数UI 状态栏因此紧凑可读。输出总量硬预算整轮用户对话最多向 UI 推送 480KB 的文本/推理内容MAX_STREAMED_OUTPUT_BYTES。超出即显式报错本轮是部分完成绝不把没执行完的工具轮次当成成功——这个宁错勿假的取舍是新手最容易忽略的健壮性设计。另外ai_client.rs 对 SSE 流也设置了层层熔断单行 1MB、事件数 65536、工具调用 32 次……防的是失控循环的流而不是限制正常长回答。四、提示词缓存设计三个省钱的隐藏技巧这是全文最精妙的一节。LLM 计费里系统提示词每轮都要重新发送如果前缀逐字节稳定就能命中 Anthropic 等厂商的提示词缓存折扣。Kaku 为此做了三层设计技巧1静态系统提示词 6个片段按固定顺序拼接build_system_prompt()用include_str!编译期内联 assets/prompts/chat/ 下的 6 个片段voice.txt人格与文风禁止 emoji、禁止列表、禁止 filler 套话safety.txt安全边界output_format.txt输出格式tool_discipline.txt工具调用纪律root_cause.txt根因分析要求external_helpers.txt外部工具使用固定顺序 每轮字节完全一致 缓存前缀天然稳定。每个片段开头还有!-- name: ... kakuVersion: 0.12.0 --元数据块由strip_prompt_metadata在运行时剥掉——这样文件可以版本化 diff注入的提示词却保持纯净。技巧2动态信息全部挪到环境消息日期、当前目录、locale、终端尺寸这些每轮都在变的字段坚决不放进系统提示词而是由build_environment_message()组装成一条独立的 user 消息排在提示词之后。源码注释直言其动机让静态系统提示词能命中 Anthropic 的 prompt-cache 折扣。技巧3MEMORY.md 故意避开缓存前缀Kaku 支持 Soul 机制SOUL/STYLE/SKILL/MEMORY 四个身份文件见 soul.rs。其中SOUL/STYLE/SKILL用户手写的稳定身份→ 追加在系统提示词末尾MEMORY.md后台管家模型自动改写的滚动记忆→ 放进环境消息注释写着避免管家改写记忆时每一轮都打爆提示词缓存。稳定内容前置、易变内容后置三条规则贯穿始终——这就是提示词缓存设计的全部心法 五、工具注册表模型能做什么由代码说了算registry.rs 中的all_tools()一次性声明了全部工具fs_read / fs_list / fs_write / fs_patch / fs_delete、shell_exec / shell_bg / shell_poll、grep_search / symbol_search、project_summary / file_tree、web_fetch / web_search、memory_read / soul_read、http_request。每个工具都是名称 描述 JSON Schema三件套。Agent 循环执行前会做白名单校验模型只准调用本轮实际宣告的工具。若模型模仿历史对话里的旧工具名比如切换搜索引擎前的web_search记录系统不杀轮次而是回一条该工具不可用的错误工具结果让模型自我纠正——错误信息也是上下文的一部分这比直接崩溃优雅得多。六、新手能带走的3个设计要点Agent 循环本质是带预算的 while轮数25、历史字节120KB、输出字节480KB三道预算 摘要降级 软警告收尾缺一不可。事件驱动比回调简单十倍一个枚举 一条 mpsc 通道就能把模型思考中 → 工具运行中 → 等待审批的复杂状态干净地推给 UI。提示词是产品也是工程静态化、分段化、版本化、易变内容后置——省的是真金白银的 token 费用。想继续深挖推荐阅读顺序mod.rsAgent 循环→ compact.rs上下文瘦身→ ai_client.rs流式协议→ assets/prompts/提示词全文。看完你会发现一个优秀的终端 AI 引擎靠的不是魔法而是每一处都写清楚的取舍。【免费下载链接】Kaku A fast, out-of-the-box terminal built for AI coding.项目地址: https://gitcode.com/gh_mirrors/kaku5/Kaku创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考