kimi-cli 内核 sidecar 化改造用 WireBackedSoul 接入 Rust kagent 的设计方案解析【免费下载链接】kimi-cliKimi Code CLI is your next CLI agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kimi-cliKLIP-15 是 kimi-cli 仓库中的一份设计提案klips/klip-15-kagent-sidecar-integration.md状态为 Draft它规划了如何在不删除现有 Python kernel 的前提下将 Rust 版 kagent 作为独立的 sidecar 进程接入 kimi-cliPython 侧继续负责 UIshell/print、ACP server 与配置/会话/技能发现Rust kernel 则通过已稳定的 stdio Wire 协议与 Python 通讯。读完本文你将理解这套「Python 壳 Rust 内核」架构的完整动机、WireBackedSoul 代理层的职责划分、kernel 运行时切换与失败回退机制以及配套的打包、测试与迁移策略。背景与现状为什么需要引入 Rust kernel当前仓库中 Python 版 kimi-cli 的 Agent kernel 由KimiSoul驱动实现位于 src/kimi_cli/soul/kimisoul.py。在运行时Shell UI 与 ACP server 通过 Wire 事件与 kernel 交互二者之间是一条消息队列通道Wire类在 src/kimi_cli/wire/init.py 中定义向 kernel 暴露soul_side、向 UI 暴露ui_side而 kernel 侧发送消息的统一入口是wire_send见 src/kimi_cli/soul/init.py 中的SoulProtocol 与run_soul编排函数。这个 Wire 协议本身已经稳定采用JSON-RPC 2.0 over stdio每条消息一行 JSON协议版本当前为1.10完整规范见 docs/zh/customization/wire-mode.md。也就是说kernel 与 UI 之间的边界已经是一条定义清晰的「网络协议」而不是进程内函数调用——这为内核替换创造了天然条件Rust 版 kagent 已经实现了相同的 Wire 协议与核心 Agent 逻辑它的目标是替换 Python kernel但保留 Python UI/ACP由于双方只通过协议通信Python 侧 UI 甚至不需要感知 kernel 换了实现。值得注意Wire 协议的initialize握手与外部工具协商ToolCallRequest/ApprovalResponse对称的 request/response 模型正是由姊妹提案 KLIP-12 落地的见 klips/klip-12-wire-initialize-external-tools.md状态为 Implemented它让 server 能回传 soul-level 的slash_commands、让 client 能注册external_tools。KLIP-15 的 WireBackedSoul 设计正是建立在这套已经可用的协议之上。目标与非目标替换内核但不碰协议、不删 PythonKLIP-15 的核心目标可以概括为四点在保留 Python kernel 的前提下引入 Rust kagent 作为默认或可选 kernelPython 侧仍负责 UIshell/print、ACP server、配置/会话/技能发现kernel 实现通过stdio wire 协议与 Python 通讯与现有外部 Wire 客户端保持一致的交互方式支持fallbackRust kernel 启动失败或运行异常时回退到 Python kernel并支持多平台Linux/macOS/Windows含 Linux ARM打包分发在 wheel 中携带 kagent 二进制。提案同时明确划定了非目标避免过度设计不做 Pyo3 绑定不把 Rust kernel 直接嵌入 Python 进程不移除 Python kernel 代码仅在运行时切换不修改 wire 协议协议保持冻结降低兼容成本。这三条约束决定了后续所有设计走向既然不能嵌入、不能改协议那么唯一自然的方案就是「进程外 sidecar 协议代理」。总体架构sidecar stdio wire方案概览非常清晰将 Rust kagent 视为一个实现 wire 协议的外部 serverPython 侧新增一个WireBackedSoul代理 Soul负责启动子进程并转发消息。提案给出的数据流如下Python UI/ACP - Python Wire - WireBackedSoul - stdio - kagent在这条链路上Python UI/ACP 仍然只感知本地Wire无需任何改动WireBackedSoul实现 Soul 接口run()/status/available_slash_commands用 Rust 进程替代KimiSoul执行 Agent 逻辑所有Approval/ToolCall/StatusUpdate事件都由 Rust 侧产生Python 仅做消息转发与本地 UI 适配。这种分层的好处在于Python 侧保持了对SoulProtocol 的既有抽象。从源码看Soul是一个runtime_checkable的 Protocolsrc/kimi_cli/soul/init.py定义了name、model_name、status、available_slash_commands等属性以及async run(user_input, ...)方法——WireBackedSoul只需要按同样的协议实现就能被现有的run_soul编排逻辑无缝使用这正是「代理 Soul」一词的由来。核心组件WireBackedSoul 的职责、最小行为与对象模型职责WireBackedSoul承担四件事启动/管理 Rust kagent 进程kagent --wire通过 stdio 与 Rust kernel 进行 JSON-RPC 交互将 Rust 发来的event透传为wire_send(...)送到 Python UI/ACP将 Rust 发来的requestApproval / ToolCall映射为本地 Wire 请求收集 UI 响应后再回写给 Rust。其中第 3、4 步正是「Python 仅做消息转发与本地 UI 适配」的具体落点kernel 侧看到的 UI 行为和现有KimiSoul场景完全一致因为交互表面仍是同一个本地Wire。最小行为WireBackedSoul需要实现的最小方法集对应 Wire 协议的三个核心请求方法行为initialize可选握手获取 slash commands / server info协商协议版本prompt触发一轮执行Rust 侧持续发送事件与请求直到返回PromptResultcancel将取消请求转发给 Rust这三个方法一一对应 docs/zh/customization/wire-mode.md 中initialize、prompt、cancel三个协议方法——WireBackedSoul本质上就是一个「把 Rust server 伪装成本地 Soul」的协议桥。对象模型WireBackedSoul持有四个关键状态processsubprocess handle即 Rust kagent 进程句柄clientwire client负责 JSON-RPC 的 request/response 编解码与收发status来自StatusUpdate事件的最新状态供status属性返回slash_commands来自initialize结果的斜杠命令列表供available_slash_commands属性返回。对照现有实现StatusUpdate与SlashCommandInfo的类型定义均已存在于 docs/zh/customization/wire-mode.md 的协议类型中Rust 侧只要按协议输出Python 侧就能直接消费。Approval/ToolCall 双向转发以本地 Wire 为交互表面Rust → Python 方向Rust 通过 wirerequest发送ApprovalRequest/ToolCallRequestPython 侧创建本地ApprovalRequest/ToolCallRequest对象wire_send到 UIUI resolve 之后Python 将结果作为 JSON-RPC response 回写给 Rust。提案特别强调了一个关键点不复制/重建 Rust-side 的 pending future而是用本地 wire 作为交互表面。这意味着审批弹窗、工具调用 UI 的行为与现有一致Python 侧不必为 Rust kernel 单独实现一套交互逻辑只是把 UI 的响应结果如{request_id: ..., response: approve}原样翻译回 JSON-RPC response。协议侧这两个请求/响应的对称结构ApprovalResponse与ToolResult在 docs/zh/customization/wire-mode.md 中已有完整定义实现时无需扩展协议。进程生命周期与容错WireBackedSoul对 kagent 子进程的生命周期管理设计如下启动执行kagent --wire必要时附加--config或环境变量正常退出Rust 自行退出Python 检测到 stdin/stdout 的 EOF 后结束run异常退出Python 检测 stderr / exit code决定回退到 Python kernel 或直接报错取消通过 wirecancel请求转发给 Rust失败回退kernel 可配置为rust或python当rust启动或运行失败时自动 fallback 到 Python kernel。这一设计把「进程崩溃」从「Agent 逻辑异常」中隔离出来Python 侧永远有一个可用的 kernel 兜底不会因为新内核的缺陷导致整个 CLI 不可用。运行时选择与配置三种切换方式提案建议按以下优先级提供 kernel 运行时切换能力CLI flag--kernel rust|python默认可为rust环境变量KIMI_KERNELrust|python配置文件[runtime] kernel rust。选择逻辑落在KimiCLI.create中根据解析结果创建KimiSoul或WireBackedSoul。这与当前仓库的创建路径一致——src/kimi_cli/app.py 中正是通过KimiSoul(agent, contextcontext)构造 kernel并通过soul属性暴露给上层src/kimi_cli/app.py。接入WireBackedSoul后这里就变成一个「按配置二选一」的工厂点UI/ACP 层完全不受影响。打包与分发wheel 携带 sidecar 二进制KLIP-15 提议使用maturin构建 Python package 并打包 sidecar 二进制产物Python wheel 内包含kagent可执行文件Python 代码负责定位并调用该二进制运行时二进制查找优先级KIMI_KERNEL_BIN环境变量显式覆盖package 内嵌二进制路径wheel 自带系统 PATH最后兜底平台矩阵Linux x86_64 / ARM64、macOS ARM64、Windows x86_64。需要说明的是这是一份设计提案当前仓库根目录的 pyproject.toml 实际使用的构建后端是uv_buildrequires [uv_build0.8.5,0.10.0]因此 maturin 的引入属于提案设想具体落地时构建后端如何选择、sidecar 二进制如何注入 wheel都以后续实现为准。但「环境变量 → 内嵌路径 → PATH」的三级查找策略是值得沿用的通用做法它同时满足了「用户自建二进制」与「开箱即用」两种场景。兼容与迁移策略为了保证改造平滑提案制定了四条迁移约束Python kernel 保留并可通过配置显式启用Rust kernel 失败自动 fallback不阻断用户工作流既有 wire/client 协议不变外部客户端零改动e2e 测试可通过KIMI_E2E_WIRE_CMD指定 Rust kernel实现一套测试代码双内核验证。最后一点在仓库中已有对应设施tests_e2e/wire_helpers.py中定义了WIRE_COMMAND_ENV KIMI_E2E_WIRE_CMDtests_e2e/wire_helpers.py用于覆盖被测试的 CLI 命令本身tests_e2e/AGENTS.md也说明测试默认通过uv run kimi运行可用KIMI_E2E_WIRE_CMD覆盖基础命令。也就是说只要把该环境变量指向 kagent 的 wire server 入口整条tests_e2e测试套件即可用于验证 Rust kernel 的协议兼容性。测试与验证矩阵提案规划了三层验证层面手段Rust 侧cargo fmt/cargo check/cargo testPython 侧现有 UI/ACP 测试继续全量运行保证代理层不破坏原行为e2eKIMI_E2E_WIRE_CMD... uv run pytest tests_e2e用真实协议流量验证双内核等价性CI增加多平台 Rust 构建 e2e 覆盖这套矩阵的核心思路是「协议等价性验证」Rust kernel 只要能通过既有的 Wire e2e 测试就证明它在协议层面与 Python kernel 行为一致UI 无需为它做任何特判。替代方案对比为什么不用 Pyo3提案明确评估并否决了Pyo3 绑定in-process Rust kernel方案优点更低延迟、无进程管理开销缺点绑定维护成本高、生命周期/async 与 GIL 交互复杂、进程隔离性差。结论是sidecar 模式更符合现有 wire 设计与业界「binary Python wrapper」的实践。从架构角度看sidecar 方案把「语言边界」变成了「进程边界 协议边界」任何一侧的崩溃、升级、替换都不会影响另一侧这与本项目 UI 与 kernel 已经通过 Wire 解耦的现状是一脉相承的。开放问题与演进方向提案末尾列出了三个尚未定论的开放问题它们直接决定了后续实现的工作量Runtime 信息注入Rust kernel 是否需要从 Python 侧注入更多 runtime 信息如 workdir listing / skills初始化元数据扩展是否需要在 wireinitialize中扩展 metadata如 kernel capabilities / feature flags回退默认策略失败回退是默认启用还是仅在kernelauto时启用这三个问题本质上是「Python 壳与 Rust 内核之间职责边界」的进一步细化信息注入决定了 Python 侧需要向 kernel 透传多少上下文元数据扩展决定了协议是否需要为多 kernel 场景做能力协商回退策略则决定了默认配置的激进程度。它们的答案将直接体现在后续 WireBackedSoul 的initialize握手实现与KimiCLI.create的 kernel 选择逻辑中。【免费下载链接】kimi-cliKimi Code CLI is your next CLI agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kimi-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 kimi-cli 内核 sidecar 化改造：用 WireBackedSoul 接入 Rust kagent 的设计方案解析
kimi-cli 内核 sidecar 化改造用 WireBackedSoul 接入 Rust kagent 的设计方案解析【免费下载链接】kimi-cliKimi Code CLI is your next CLI agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kimi-cliKLIP-15 是 kimi-cli 仓库中的一份设计提案klips/klip-15-kagent-sidecar-integration.md状态为 Draft它规划了如何在不删除现有 Python kernel 的前提下将 Rust 版 kagent 作为独立的 sidecar 进程接入 kimi-cliPython 侧继续负责 UIshell/print、ACP server 与配置/会话/技能发现Rust kernel 则通过已稳定的 stdio Wire 协议与 Python 通讯。读完本文你将理解这套「Python 壳 Rust 内核」架构的完整动机、WireBackedSoul 代理层的职责划分、kernel 运行时切换与失败回退机制以及配套的打包、测试与迁移策略。背景与现状为什么需要引入 Rust kernel当前仓库中 Python 版 kimi-cli 的 Agent kernel 由KimiSoul驱动实现位于 src/kimi_cli/soul/kimisoul.py。在运行时Shell UI 与 ACP server 通过 Wire 事件与 kernel 交互二者之间是一条消息队列通道Wire类在 src/kimi_cli/wire/init.py 中定义向 kernel 暴露soul_side、向 UI 暴露ui_side而 kernel 侧发送消息的统一入口是wire_send见 src/kimi_cli/soul/init.py 中的SoulProtocol 与run_soul编排函数。这个 Wire 协议本身已经稳定采用JSON-RPC 2.0 over stdio每条消息一行 JSON协议版本当前为1.10完整规范见 docs/zh/customization/wire-mode.md。也就是说kernel 与 UI 之间的边界已经是一条定义清晰的「网络协议」而不是进程内函数调用——这为内核替换创造了天然条件Rust 版 kagent 已经实现了相同的 Wire 协议与核心 Agent 逻辑它的目标是替换 Python kernel但保留 Python UI/ACP由于双方只通过协议通信Python 侧 UI 甚至不需要感知 kernel 换了实现。值得注意Wire 协议的initialize握手与外部工具协商ToolCallRequest/ApprovalResponse对称的 request/response 模型正是由姊妹提案 KLIP-12 落地的见 klips/klip-12-wire-initialize-external-tools.md状态为 Implemented它让 server 能回传 soul-level 的slash_commands、让 client 能注册external_tools。KLIP-15 的 WireBackedSoul 设计正是建立在这套已经可用的协议之上。目标与非目标替换内核但不碰协议、不删 PythonKLIP-15 的核心目标可以概括为四点在保留 Python kernel 的前提下引入 Rust kagent 作为默认或可选 kernelPython 侧仍负责 UIshell/print、ACP server、配置/会话/技能发现kernel 实现通过stdio wire 协议与 Python 通讯与现有外部 Wire 客户端保持一致的交互方式支持fallbackRust kernel 启动失败或运行异常时回退到 Python kernel并支持多平台Linux/macOS/Windows含 Linux ARM打包分发在 wheel 中携带 kagent 二进制。提案同时明确划定了非目标避免过度设计不做 Pyo3 绑定不把 Rust kernel 直接嵌入 Python 进程不移除 Python kernel 代码仅在运行时切换不修改 wire 协议协议保持冻结降低兼容成本。这三条约束决定了后续所有设计走向既然不能嵌入、不能改协议那么唯一自然的方案就是「进程外 sidecar 协议代理」。总体架构sidecar stdio wire方案概览非常清晰将 Rust kagent 视为一个实现 wire 协议的外部 serverPython 侧新增一个WireBackedSoul代理 Soul负责启动子进程并转发消息。提案给出的数据流如下Python UI/ACP - Python Wire - WireBackedSoul - stdio - kagent在这条链路上Python UI/ACP 仍然只感知本地Wire无需任何改动WireBackedSoul实现 Soul 接口run()/status/available_slash_commands用 Rust 进程替代KimiSoul执行 Agent 逻辑所有Approval/ToolCall/StatusUpdate事件都由 Rust 侧产生Python 仅做消息转发与本地 UI 适配。这种分层的好处在于Python 侧保持了对SoulProtocol 的既有抽象。从源码看Soul是一个runtime_checkable的 Protocolsrc/kimi_cli/soul/init.py定义了name、model_name、status、available_slash_commands等属性以及async run(user_input, ...)方法——WireBackedSoul只需要按同样的协议实现就能被现有的run_soul编排逻辑无缝使用这正是「代理 Soul」一词的由来。核心组件WireBackedSoul 的职责、最小行为与对象模型职责WireBackedSoul承担四件事启动/管理 Rust kagent 进程kagent --wire通过 stdio 与 Rust kernel 进行 JSON-RPC 交互将 Rust 发来的event透传为wire_send(...)送到 Python UI/ACP将 Rust 发来的requestApproval / ToolCall映射为本地 Wire 请求收集 UI 响应后再回写给 Rust。其中第 3、4 步正是「Python 仅做消息转发与本地 UI 适配」的具体落点kernel 侧看到的 UI 行为和现有KimiSoul场景完全一致因为交互表面仍是同一个本地Wire。最小行为WireBackedSoul需要实现的最小方法集对应 Wire 协议的三个核心请求方法行为initialize可选握手获取 slash commands / server info协商协议版本prompt触发一轮执行Rust 侧持续发送事件与请求直到返回PromptResultcancel将取消请求转发给 Rust这三个方法一一对应 docs/zh/customization/wire-mode.md 中initialize、prompt、cancel三个协议方法——WireBackedSoul本质上就是一个「把 Rust server 伪装成本地 Soul」的协议桥。对象模型WireBackedSoul持有四个关键状态processsubprocess handle即 Rust kagent 进程句柄clientwire client负责 JSON-RPC 的 request/response 编解码与收发status来自StatusUpdate事件的最新状态供status属性返回slash_commands来自initialize结果的斜杠命令列表供available_slash_commands属性返回。对照现有实现StatusUpdate与SlashCommandInfo的类型定义均已存在于 docs/zh/customization/wire-mode.md 的协议类型中Rust 侧只要按协议输出Python 侧就能直接消费。Approval/ToolCall 双向转发以本地 Wire 为交互表面Rust → Python 方向Rust 通过 wirerequest发送ApprovalRequest/ToolCallRequestPython 侧创建本地ApprovalRequest/ToolCallRequest对象wire_send到 UIUI resolve 之后Python 将结果作为 JSON-RPC response 回写给 Rust。提案特别强调了一个关键点不复制/重建 Rust-side 的 pending future而是用本地 wire 作为交互表面。这意味着审批弹窗、工具调用 UI 的行为与现有一致Python 侧不必为 Rust kernel 单独实现一套交互逻辑只是把 UI 的响应结果如{request_id: ..., response: approve}原样翻译回 JSON-RPC response。协议侧这两个请求/响应的对称结构ApprovalResponse与ToolResult在 docs/zh/customization/wire-mode.md 中已有完整定义实现时无需扩展协议。进程生命周期与容错WireBackedSoul对 kagent 子进程的生命周期管理设计如下启动执行kagent --wire必要时附加--config或环境变量正常退出Rust 自行退出Python 检测到 stdin/stdout 的 EOF 后结束run异常退出Python 检测 stderr / exit code决定回退到 Python kernel 或直接报错取消通过 wirecancel请求转发给 Rust失败回退kernel 可配置为rust或python当rust启动或运行失败时自动 fallback 到 Python kernel。这一设计把「进程崩溃」从「Agent 逻辑异常」中隔离出来Python 侧永远有一个可用的 kernel 兜底不会因为新内核的缺陷导致整个 CLI 不可用。运行时选择与配置三种切换方式提案建议按以下优先级提供 kernel 运行时切换能力CLI flag--kernel rust|python默认可为rust环境变量KIMI_KERNELrust|python配置文件[runtime] kernel rust。选择逻辑落在KimiCLI.create中根据解析结果创建KimiSoul或WireBackedSoul。这与当前仓库的创建路径一致——src/kimi_cli/app.py 中正是通过KimiSoul(agent, contextcontext)构造 kernel并通过soul属性暴露给上层src/kimi_cli/app.py。接入WireBackedSoul后这里就变成一个「按配置二选一」的工厂点UI/ACP 层完全不受影响。打包与分发wheel 携带 sidecar 二进制KLIP-15 提议使用maturin构建 Python package 并打包 sidecar 二进制产物Python wheel 内包含kagent可执行文件Python 代码负责定位并调用该二进制运行时二进制查找优先级KIMI_KERNEL_BIN环境变量显式覆盖package 内嵌二进制路径wheel 自带系统 PATH最后兜底平台矩阵Linux x86_64 / ARM64、macOS ARM64、Windows x86_64。需要说明的是这是一份设计提案当前仓库根目录的 pyproject.toml 实际使用的构建后端是uv_buildrequires [uv_build0.8.5,0.10.0]因此 maturin 的引入属于提案设想具体落地时构建后端如何选择、sidecar 二进制如何注入 wheel都以后续实现为准。但「环境变量 → 内嵌路径 → PATH」的三级查找策略是值得沿用的通用做法它同时满足了「用户自建二进制」与「开箱即用」两种场景。兼容与迁移策略为了保证改造平滑提案制定了四条迁移约束Python kernel 保留并可通过配置显式启用Rust kernel 失败自动 fallback不阻断用户工作流既有 wire/client 协议不变外部客户端零改动e2e 测试可通过KIMI_E2E_WIRE_CMD指定 Rust kernel实现一套测试代码双内核验证。最后一点在仓库中已有对应设施tests_e2e/wire_helpers.py中定义了WIRE_COMMAND_ENV KIMI_E2E_WIRE_CMDtests_e2e/wire_helpers.py用于覆盖被测试的 CLI 命令本身tests_e2e/AGENTS.md也说明测试默认通过uv run kimi运行可用KIMI_E2E_WIRE_CMD覆盖基础命令。也就是说只要把该环境变量指向 kagent 的 wire server 入口整条tests_e2e测试套件即可用于验证 Rust kernel 的协议兼容性。测试与验证矩阵提案规划了三层验证层面手段Rust 侧cargo fmt/cargo check/cargo testPython 侧现有 UI/ACP 测试继续全量运行保证代理层不破坏原行为e2eKIMI_E2E_WIRE_CMD... uv run pytest tests_e2e用真实协议流量验证双内核等价性CI增加多平台 Rust 构建 e2e 覆盖这套矩阵的核心思路是「协议等价性验证」Rust kernel 只要能通过既有的 Wire e2e 测试就证明它在协议层面与 Python kernel 行为一致UI 无需为它做任何特判。替代方案对比为什么不用 Pyo3提案明确评估并否决了Pyo3 绑定in-process Rust kernel方案优点更低延迟、无进程管理开销缺点绑定维护成本高、生命周期/async 与 GIL 交互复杂、进程隔离性差。结论是sidecar 模式更符合现有 wire 设计与业界「binary Python wrapper」的实践。从架构角度看sidecar 方案把「语言边界」变成了「进程边界 协议边界」任何一侧的崩溃、升级、替换都不会影响另一侧这与本项目 UI 与 kernel 已经通过 Wire 解耦的现状是一脉相承的。开放问题与演进方向提案末尾列出了三个尚未定论的开放问题它们直接决定了后续实现的工作量Runtime 信息注入Rust kernel 是否需要从 Python 侧注入更多 runtime 信息如 workdir listing / skills初始化元数据扩展是否需要在 wireinitialize中扩展 metadata如 kernel capabilities / feature flags回退默认策略失败回退是默认启用还是仅在kernelauto时启用这三个问题本质上是「Python 壳与 Rust 内核之间职责边界」的进一步细化信息注入决定了 Python 侧需要向 kernel 透传多少上下文元数据扩展决定了协议是否需要为多 kernel 场景做能力协商回退策略则决定了默认配置的激进程度。它们的答案将直接体现在后续 WireBackedSoul 的initialize握手实现与KimiCLI.create的 kernel 选择逻辑中。【免费下载链接】kimi-cliKimi Code CLI is your next CLI agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kimi-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考