一个代理，随处可用：我们如何构建 Kiro 代理框架

HN LLM Code Research 2026-08-11T07:05:47.990656

在 Kiro 开发初期，我们就在讨论一个问题：在开发者的日常工作中，智能体（agent）开发应该是什么体验？我们反复想到的场景是，会话可以在笔记本电脑、云端沙箱之间无缝流转，来回切换毫无阻碍。一天工作结束，你合上电脑，Kiro 会话照样在云端继续运行。买咖啡的间隙，掏出手机就能查看进度。第二天早上打开 Kiro IDE，接着昨天的进度继续干。你在 Kiro 网页版上启动一个项目，在 Kiro IDE 里补充上下文，然后到你正在跑测试、改代码的 Kiro 命令行终端里继续工作，顺便还能在 Slack 上随时查看进展。智能体开发应该是一段连续的对话，贯穿你使用的每一个终端界面。

今年早些时候，我们意识到一个问题：现有的代理架构正在阻碍我们实现这个愿景。当时，Kiro IDE、命令行和网页版各自运行着一套专为本客户端定制的代理，每套都有自己的会话格式、工具集和配置模型。想要让会话在客户端和环境之间自由迁移，就必须有一个统一的代理，无论你用的是哪个客户端、跑在什么环境里，它的工作方式都保持一致。而在这套「每个客户端一套代理」的架构下，从一个客户端启动的会话无法迁移到另一个客户端，因为各代理之间缺乏足够的共性。这篇文章要讲的，就是我们如何把这三套代理代码库合并成一个统一的 Kiro 代理框架（顺带一提，这个框架是用 Kiro 自己构建的），以及那些让我们的愿景触手可及的架构决策。

三个各自为政的框架

在 Kiro 刚起步的时候，我们优先追求速度和快速迭代，所以鼓励每个客户端团队各自构建自己的代理框架。所谓代理框架，就是负责编排的那一层，它管理着代理循环、工具执行、子代理委派、会话管理、配置加载以及与模型的通信。IDE 团队用 TypeScript 构建，以适配 Code OSS 的扩展模型；命令行团队用 Rust 构建，追求性能；网页版团队则用 Python 构建，以便紧跟最新的代理研究成果。

各个客户端各自独立的框架让团队可以独立发布、快速迭代，但也意味着各团队做出了不同的选择。会话存储在不同客户端上的实现方式不同；权限系统各自设计，语法互不兼容：CLI 使用基于正则表达式的 allowedCommands/deniedCommands，而 IDE 对 trustedCommands 采用前缀匹配，对黑名单采用子串匹配；压缩策略各不相同；子代理上下文共享采用不同模型；自定义代理在每个客户端的行为也都不一样。功能集同样分化：规范驱动开发和增强功能只有 IDE 才有，计划模式和代码智能只存在于 CLI。

实现成本随时间不断累积。每新增一项能力都得在三个地方各自实现和维护，有时还会导致代理行为略有差异；修一个 bug 也要修三次。用户使用不同客户端时，体验到的功能不一致。我们想让会话在客户端和计算环境之间移动的愿景在架构上根本无法实现，因为没有统一的会话格式、工具集和配置模型。我们曾考虑在各客户端之间约定代理行为契约，然后在三套框架中分别实现，以保持各团队的独立性和开发速度。然而，接口对齐同样会带来协调成本，而且这个成本会随着每个新功能不断增加：每个新功能都需要一份规范、三份实现，以及持续验证它们行为完全一致。

转折点出现在我们准备公开发布 Kiro 网页版的时候。与其给网页版单独开发一套代理，继续承担不断累积的实现成本，我们决定构建一个统一的代理框架，把三个团队各自学到的东西中最好的部分融汇到一处。一个统一框架消除了团队间的重复劳动，也让我们能把所有精力都投入到同一个地方。

Kiro agent harness 架构

我们早期做的一个关键架构决策，是把 harness 构建成独立的服务器进程，而不是编译进每个客户端的库。从之前的尝试中我们看到，共享库无法建立起足够强的边界。客户端代码最终会调用那些本不该导出的内部方法，或者在库之上叠加自己的 agent 逻辑，结果又回到了实现分叉的老路上。独立的进程让这种分离变得真实。harness 和客户端不需要共享同一种语言或运行时，因此每个客户端都可以使用适合其平台的任何技术栈。

现在，不再是三对紧密耦合的客户端-agent 组合：

我们得到了客户端与单个 agent harness 之间的清晰分离：

Kiro agent harness 是一个轻量级进程，与你的代码库并行运行，启动迅速，并拥有 agent 侧的一切。客户端则负责用户如何与 agent 交互，以及如何呈现 agent 的工作成果。跨越这条边界的唯一方式是通过已定义的协议接口。由于它是独立进程而不是编译进客户端的库，它可以在任何计算环境上运行。同一个 harness 既可以在你的笔记本上启动，也可以运行在云端的虚拟机中，而客户端完全不需要关心这些。

服务器与客户端之间定义良好的接口意味着 agent 代码可以独立于客户端演进。如果 harness 的改动不涉及协议接口（例如添加新工具、改进规划、调优 agent 循环），那么它会在所有客户端中立即生效，客户端无需任何改动。举个例子，我们最近加入了自定义 agent 热重载：你可以编辑 .kiro/agents/mid-session 中的文件，harness 会立刻捕捉到这一变化，并向客户端重新通告可用的命令。这不需要客户端做任何修改，因为可用命令的通知类型在协议中已经存在。所有客户端都免费获得了这一能力。

运行框架并不是一套方案走天下，因为它要支撑的客户端实在太多了。不同客户端能力各有差异，有些操作放在客户端层面、用客户端原生功能来实现反而更合理。客户端可以自带工具，也可以屏蔽内置工具，以便选用最适合自身形态的方案。比如 IDE 就用 Code OSS 的 API 来处理文件操作，提供了自己的文件读写工具，而不是用运行框架内置的、直接操作文件系统的那些工具。当 Agent 需要调用这些客户端提供的工具时，会先通知客户端，由客户端执行完再把结果返回。

协议：Agent Client Protocol（ACP）

客户端和运行框架之间的边界，我们选用了 Agent Client Protocol（ACP）来划分。ACP 是一套标准化的智能体与客户端通信规范，2026 年 6 月发布了 1.0 版本。JetBrains 系列 IDE、Xcode、Zed，以及 Obsidian、Emacs、Neovim 等编辑器都支持该协议。其实今年早些时候，我们在 Kiro CLI 里就已经用过 ACP，让用户能直接在这些应用里和 Kiro 交互。这次构建统一运行框架，我们决定继续用 ACP——不只是面向第三方编辑器，也作为 Kiro 自家客户端与我们自己 Agent 之间的接口。ACP 的两个特性让这成为可能：一是支持扩展自定义方法，二是传输方式足够灵活。

ACP 官方支持用 stdio（标准输入输出）作为传输方式。这对本地客户端非常合适：运行框架以编辑器或终端的子进程方式运行即可。但像 Kiro 网页版、iOS 应用这样的远程客户端，就需要另一种传输方式。为此，我们新增了一条基于 WebSocket 的自定义传输，让这些客户端能连接上运行在云端沙箱里的框架。无论客户端走哪种传输方式，底层的二进制、工具和 Agent 行为都完全一致。

Beyond transports, we extended ACP’s method set into what we call Kiro-ACP. Standard ACP handles the fundamentals (session lifecycle, message streaming, and tool call reporting), but Kiro’s features needed more. For example, we added live steering so users can send a message that gets injected at the next inference turn while the agent is working, shaping its direction without cancelling or waiting. ACP does not support queuing messages, so we extended ACP with new method properties and notifications to enable live steering. We also modeled Kiro’s spec-driven development workflow as a set of dedicated methods, extended ACP’s basic tool approval into a rich multi-scope permission system, and added notifications for context window usage and hook execution. In total, Kiro-ACP adds more than 20 agent-callable methods, 15 client-callable methods, and 20 notification types on top of the base protocol. ACP’s extensibility model keeps this clean: custom methods use an underscore prefix per the spec, and all of Kiro’s extensions live under the_kiro/namespace. We can extend the protocol for Kiro-specific features without forking it.

在传输层之外，我们还将ACP的方法集扩展为所谓的Kiro-ACP。标准ACP覆盖了基础能力（会话生命周期、消息流式传输和工具调用上报），但Kiro的功能需求不止于此。例如，我们加入了实时操控（live steering），让用户在代理工作时发送一条消息，这条消息会在下一次推理回合被注入，从而引导代理的方向，而不必取消当前操作或干等结果。ACP本身不支持消息排队，因此我们为ACP新增了方法属性和通知来支持实时操控。我们还将Kiro的规格驱动开发工作流建模为一组专用方法，把ACP基础的工具审批扩展为丰富的多范围权限系统，并新增了上下文窗口使用量和钩子执行的通知。总体而言，Kiro-ACP在基础协议之上增加了20多个代理可调用的方法、15个客户端可调用的方法，以及20种通知类型。ACP的扩展模型保证了这一切的整洁性：按规范，自定义方法使用下划线前缀，Kiro的所有扩展都位于_kiro/命名空间下。我们可以为Kiro特有功能扩展协议，而无需分叉它。

The result is that third-party clients connect the same way our first-party clients do. Any ACP-compatible client gets the full agent with tools, sub-agents, session management, and MCP connectivity. First-party clients (IDE, CLI, web, iOS) additionally use the Kiro-ACP extensions for features like live steering, specs, rich permissions UI, and context usage tracking.

最终的结果是，第三方客户端以与我们第一方客户端完全相同的方式连接。任何兼容ACP的客户端都能获得完整的代理能力，包括工具、子代理、会话管理和MCP连接。第一方客户端（IDE、CLI、Web、iOS）则额外使用Kiro-ACP扩展，获取实时操控、规格、富权限界面和上下文用量追踪等功能。

Specs, agents, and hooks — everywhere

规格、代理与钩子——无处不在

The immediate payoff of a single harness is that features previously locked to one client are now available everywhere, with the same configuration format and the same behavior.

统一harness的直接回报是：以前被锁定在单一客户端中的功能，现在以相同的配置格式和相同的行为随处可用。

规格驱动开发此前仅限 IDE 中使用，现在它也能在 CLI（用 /spec new 启动）和网页版 Kiro 中运行。Agent 负责处理驱动规格工作流的 LLM 交互与自动推理——生成需求、产出技术设计、将工作拆解为任务——每个客户端则根据自身形态以合适的方式呈现结果。IDE 以并排面板展示规格产物；CLI 在终端中渲染；网页版 Kiro 在浏览器中显示，并支持内联评审与多人协作，让团队可以共同迭代规格。Agent 通过 ACP 通信，客户端决定如何呈现输出。

自定义 Agent 在所有界面统一使用 .kiro/agents/ Markdown 格式。你可以通过描述、系统提示词、基于标签的工具选择（使用 read、write、shell 等简单标签，而非具体工具名）、可访问的子 Agent、内联 MCP 服务器定义以及内联权限规则来定义一个 Agent。将自定义 Agent 的配置提交到版本控制后，每个团队成员都能在所有客户端中获得它：

Hooks 在所有客户端中统一使用 .kiro/hooks/*.json 格式，采用相同的触发器（SessionStart、PreToolUse、PostToolUse、FileCreate、FileSave），行为也完全一致。

一个代理，处处可用：我们如何构建 Kiro 代理框架

除了功能的一致性，统一的框架还意味着在那些难以做到正确的领域，你能获得稳定的行为表现。无论你使用哪个客户端，上下文管理、压缩和摘要的工作方式都完全一致。以前，每个框架都有自己的压缩策略，这意味着随着会话变长，在 IDE、CLI 或 Web 客户端中的表现可能会各不相同。现在，只有一种实现方式，并且在同一个地方进行测试和改进。自从我们在所有客户端中推出统一的框架以来，已经在其中内置了改进的压缩提示，以更好地保留上下文。我们还深度改进了框架的韧性和性能：改进了模型推理请求的重试逻辑，提升了权限评估的速度，以及增强了 MCP 服务器连接的稳定性。每个客户端都能从这些改进中受益。结果是：无论你喜欢用哪个界面，质量和可靠性都始终如一。

统一的策略语言

在统一框架出现之前，每个客户端都有自己的权限系统，语法不同、语义不同，配置位置也各异。CLI 使用基于正则表达式的 allowedCommands / deniedCommands。IDE 则使用带前缀匹配的 trustedCommands，以及单独的采用子串匹配的 commandDenylist。这两种客户端下的权限都是按工具划分的：像“禁止读取 .env”这样一个简单的意图，必须在每一个能读取文件的工具（read、glob、grep、代码智能）中单独配置。只要漏掉一个，代理就可能通过其他工具访问到该文件。用户陷入两难：要么在每次工具调用时都按‘y’，要么选择完全信任，没有中间地带可选。我们想要一种权限模型，能够在能力层面表达意图，并通过持久且可组合的同意授权机制，减少用户反复确认的疲劳感。

现在，我们有了一个基于能力（capability）的单一权限模型，底层由 Cedar——一种经过形式化验证的策略语言——提供支持。一条规则就能覆盖所有工具中某一整个类别的操作。

能力（capabilities）是按功能对工具进行的分组：fs_read、fs_write、shell、web_fetch、mcp、subagent 等等。只要对 fs_read 设置了 deny，所有读取文件的工具（read_file、grep_search、file_search 以及未来任何读取类工具）都会被一并拦截，不需要逐个枚举。

策略可以在多个作用域之间组合，合并时遵循「拒绝优先」（deny-always-wins）的语义。Kiro 自身会强制执行不可变的安全不变量，比如 agent 不能修改自己的权限文件。企业管理员可以通过移动设备管理（MDM）下发限制；用户可以在用户级或工作区级配置自己的规则；Agent profile 可以声明适合其角色的权限；会话级的授权决定会随着工作不断累积。整个过程不需要任何前置配置。策略会随着你做出的一个个授权决定自然地生长，你也可以把它们保存到任意合适的作用域。

harness 让愿景落地

新的 agent harness 架构带来的回报已经显现。所有客户端都迁移到统一的 harness 之后，我们跨客户端发布了多项功能，而客户端代码零改动——包括全局钩子和策略预设。全局钩子（global hooks）让你只需在 ~/.kiro/hooks/ 里定义一次，钩子就会在每个工作区自动触发；像保存时 lint、提交前安全检查这类横切行为，再也不需要每个项目重复配置了。策略预设（policy presets）是可组合的命名规则集，比如 edit-workspace 和 dev-shell，用来减少常见工作流中的授权提示疲劳。当你在权限里加上策略预设（如 policies: [dev-shell, edit-workspace, read-all]）时，harness 的策略引擎会在加载时把它们展开成具体规则。这两个功能都只靠一次 harness 更新，就推到了所有客户端。

我们在本文开头描述的愿景需要一些我们仍需构建的 agent 能力，例如用于跨环境移动会话的会话打包，以及从任何客户端控制本地和云端会话的能力。统一 harness 意味着我们只需把每项新能力构建一次。在很多情况下，就像全局钩子和策略预设那样，我们可以在所有客户端上直接发布它们，而无需改动任何客户端。有些功能则需要在新的 agent 能力之上再做客户端适配。统一 harness 并没有完全消除客户端工作，我们也不希望这样。终端、桌面 IDE、浏览器和手机有着不同的交互模型，我们希望每个界面都能贴合自身的形态，而不是提供一套放之四海而皆准的体验。借助新的 agent harness 架构，agent 逻辑在所有客户端上保持一致，每个客户端团队可以专注于如何以最佳方式与之交互。

对于 Kiro 用户来说，新的 agent harness 架构意味着新能力会更快到来、行为一致，并且无论你偏好哪个界面，都能使用相同的配置。

试试新的 Kiro agent harness

新的 Kiro agent harness 已在全部四个 Kiro 客户端上线，今天就试试吧：

GPT‑5.6 更新：降低 Terra 和 Luna 的信用乘数

推出 Kiro Crew

查看原文