Linear 讲解 Linear Agent 的构建方法与设计取舍

大多数软件的设计目标都是行为一致。所谓好的工程实践，通常就是尽量收窄可能结果的范围，让同一个操作稳定地产生同一个结果。

AI 在某种程度上把这套逻辑反了过来。Linear Agent 的价值，很大一部分恰恰在于它能做我们没预料到的事，而且用的还是我们从未明确定义过的方式；如果把它的行为规定得太死，反而会削弱它之所以有用的那份灵活性。所以，我们没有为 Linear Agent 设计一条固定路径，而是划定了它可以在其中自行寻找路径的边界。

这些边界体现在几个地方：智能体的系统提示词、工具的设计、智能体对 Linear 的理解模型、每次运行的范围，以及底层一套自研的执行框架。

系统提示词

我们把 Linear Agent 的提示词集中在少数几条基本原则之上。

沟通风格

智能体应当表达清晰、自然，既不能太像企业公文，也不能过于随意。它还要根据所处的场景调整语气，比如在 Slack 里可以更口语化，而在 Loop 里则不必如此。

硬性边界

智能体不应对政治、宗教、人际关系等敏感话题发表看法。它也不应在未征得确认的情况下，采取会大幅扩大用户请求范围的行动。

对 Linear 特有概念的解释

智能体需要理解产品的分类体系，才能正确解读用户的请求，并代表用户采取正确的操作。

关于如何使用某些功能的默认判断

用户的提示词往往很短，因此智能体要能很好地判断什么时候该推断意图，什么时候该追问澄清。 

这样一份高层级的系统提示词给了智能体方向，同时也为那些显得即兴、贴合语境的行为留出了空间。比如在 Slack 里，Linear Agent 可能会察觉到对话的气氛，适时插一句玩笑。与此同时，提示词里的边界又能确保：如果玩笑涉及敏感话题，它就不会接话。

智能体工具的设计

我们发现，把约束编码进 Linear Agent 的工具设计里，比在提示词里逐条写明更有效。我们设计每个工具时，都让它的参数容易理解，并让无效操作实际上难以执行。这个原则类似于构建良好的代码抽象或用户界面：符合直觉的行为不需要额外解释。

这也为智能体随着模型进步而变得更强留出了空间。它的行动空间没有被过度脚本化，工具又能灵活组合，因此更聪明的模型可以协调这些工具去处理越来越复杂的任务。

智能体对 Linear 的理解模型

只有让智能体理解自己所处的环境，给它即兴发挥的空间才行得通。对 Linear Agent 来说，这意味着要教会它产品的结构和语义，而这项挑战与构建编程智能体有着很不一样的面貌。

编程智能体拥有的是一小组深度工具，比如 read_file、write_file 和 run_command，它们所做的几乎所有事情，都是这些基础原语如何组合的结果。代码和 shell 命令在模型的训练数据中也有很强的体现，所以这类智能体即使面对陌生情况，往往也能对这些工具形成良好的直觉。

Linear Agent 的形态正好相反。它拥有大量相对浅层的工具，每个工具都对应一项具体的产品操作，比如创建问题或修改文档。要用好这些工具，还需要理解一些产品概念，而模型现有的知识对这些概念的覆盖并不充分（Linear 或许出现在训练数据中，但相比代码和 shell，其比重微乎其微）。

因此，要让 Linear Agent 能够处理产品的任何部分，需要三样东西：

• 用于读取和修改相关数据的工具
• 说明这些数据代表什么，以及它与产品其余部分的关系
• 一套用好该功能的基本原则

以 Customer Requests 为例。对应的技能为智能体提供了跨问题、项目和客户创建、更新和列出请求的工具。它解释了每个请求都记录了来自特定客户的反馈，通常关联到某个问题或项目，并概括了所请求的内容。它还写入了使用该功能的最佳实践；例如，在起草项目规格时，它会引导智能体汇总客户请求中的模式。

每次运行的范围

下一个挑战是如何把所有这些上下文和工具暴露给智能体，又不让它不堪重负。由于大多数用户请求只需要 Linear 产品表面的一小部分，我们引入了系统技能，作为智能体的组合单元。

每个系统技能都打包了一些基本元数据、一段系统提示词和一组工具。它们共同代表了一组独立的能力，可以在需要时逐步向智能体披露。（这与用户创建的 skills 不同，后者是用户为自己的工作流编写的。那些是在智能体之上创建的可复用指令，不属于这里描述的内置系统技能。）

系统技能在后台加载，可以在智能体开始处理任务之前加载，也可以在任务展开过程中按需加载。每次运行之前，Linear Agent 会根据用户的提示词以及调用它的上下文，推断哪些技能可能相关。例如，从 Slack 频道或项目的 Linear 页面调用的智能体，很可能会预加载“projects”技能。

更间接的任务可能会在过程中暴露出额外需求。如果用户要求智能体为某个项目起草更新，我们最初可能只加载“projects”和“project updates”技能。随着工作开始，智能体可能会意识到需要查看最近的问题和 PR，然后自行加载相应的技能。

这样既能让每个线程的上下文保持聚焦，又能让 Linear Agent 整体上支持广泛的能力。它还让我们可以随时间扩展智能体的能力，而不必让每次交互都背负不断增长的提示词和工具集。

在构建过程中，我们考虑过让智能体直接访问 Linear SDK 和编码环境、CLI 或 GraphQL API。暴露这些底层原语可以说能实现更复杂的行为，但也会增加出错的范围。

底层数据模型支持的操作范围很广，而有些 UI 概念需要先经过解读，才能映射到该模型上。一种潜在的失败模式是长尾请求：这类请求没有明显的完成路径，智能体可能会试图通过越来越投机性的操作来完成任务。

做出这一决定，我们是用一部分广度换取了可预测性。智能体偶尔会拒绝它无法安全完成的任务，但它犯错的余地要小得多。

底层定制的 harness

在底层，Linear Agent 运行在一套我们自有的定制技术栈上，从模型提供方的 API 往上全部由我们掌控。它包括：

• 一个与提供方无关的 AI 客户端，为 LLM 线程提供一致的传输和存储表示
• 一个构建在持久化工作流引擎之上的智能体循环
• 一个高层的流式传输与存储层，在提及、小组件等富元素到达产品之前先对其进行解析

我们选择定制技术栈，是因为现成的 harness 库往往对智能体的执行流程有很强的预设。其核心做法是：预先提供提示词和一组工具，调用“run”，然后等待智能体发起工具调用并给出最终响应。这种方式对简单的交互很有效，但我们希望对 Linear Agent 的执行有更精细的控制，以支持某些在运行尚未结束时就要发生的编排行为。

通过技能动态注入工具

当智能体加载一项技能时，它需要在工具调用返回后立即访问该技能的工具，以便在回复用户之前调用新的工具。我们还希望以保留提供方前缀缓存的方式来实现这一点——如果实现得过于简单直接，就无法做到，因为重新处理已有上下文会推高成本。

有条件的工具调用审批

当某个操作有风险或难以撤销时，智能体应在运行中途暂停，先向用户请求确认再继续。大多数 harness 库通过粗粒度的规则来支持这一点，仅根据工具名称及其参数决定是否需要审批，而我们希望审批逻辑更具上下文感知。例如，智能体可以不经询问就删除它在当前对话中创建的内容，但在删除一个已存在的问题之前仍需确认。同样，它可以不经审批就向大多数评论串发帖，但在向与公开仓库同步的评论串发帖之前应当暂停。

异步子智能体执行

子智能体执行时，父智能体往往会连续空闲好几秒。对父智能体来说，这应当表现为一次同步的工具调用，但在底层，它需要被挂起，以免在等待子智能体期间占用服务端资源。这意味着要能够在工具调用中途挂起智能体的一个回合，异步完成工作，然后在就绪时恢复该线程。

这些编排模式不用定制 harness 也能实现，但需要别扭的变通做法，因为现成的方案是为支持多种不同类型的智能体而设计的。通过让 harness 贴合 Linear Agent 的编排需求，我们可以在不牺牲优雅与效率的前提下，朝着理想的产品体验推进。

自己掌握这套运行框架，也让我们能快速应对大规模使用中冒出的各种长尾错误和边缘情况，尤其是在使用模型提供商那些尚未被广泛采用、也还没被现有库充分验证过的功能时。

不断移动的目标

构建 Linear Agent，意味着要用一种更有意识的控制方式，取代软件传统上对可预测性的追求。这里的每一个决定，都是在押注可能性与可预测性之间的界线该划在哪里；而我们相信，这条线会随着时间不断移动。