引言：AI Agent时代，我们真正缺少的是什么
当Sam Altman断言Agent将成为AI的杀手级应用，当Andrew Ng反复强调Agentic Workflow的核心价值，我们正身处一个AI技术从概念走向实用的关键转折点。如今市面上充斥着各种大模型教程，API调用指南，框架使用手册，却很少有人愿意揭开那个最核心的秘密，一个真正能让大模型从"只会说话的大脑"变成"能解决问题的智能体"的关键组件。
这个秘密就是Harness。
如果我们用一个最简单的公式来定义AI Agent，那就是Agent等于LLM加上Harness。大语言模型提供推理能力，思考能力，理解能力，就像人的大脑。而Harness则提供工具，权限，记忆，编排，就像人的身体，手脚，感官和控制系统。在一个完整的Agent系统中，LLM本身只占代码量的极小部分，大约只有百分之一。剩下百分之九十九的代码，都在构建围绕LLM的运行时框架，也就是Harness。
这就像Andrej Karpathy曾将LLM类比为新的操作系统内核，如果LLM是内核，那么工具系统是系统调用，权限模型是访问控制，上下文管理是内存管理，多Agent编排是进程调度。这整套包裹在LLM外层的基础设施，就是Harness。几乎所有人都在谈论等号左边的Agent和右边的LLM，但很少有人系统地讲清楚Harness到底怎么造。而这正是构建生产级AI Agent的核心所在。
今天，我将基于一套完整的AI Agent工程学体系，为你揭开构建实用AI Agent的全部秘密。这不是某个特定产品的实现细节，而是一整套构建可信AI Agent的工程方法论，是从数百万日活开发者，每周数千万次子Agent调用的生产级系统中提炼出的实战经验。无论你是AI应用开发者，架构师，LLM研究者，还是对AI Agent好奇的技术人员，这篇文章都将为你打开一扇全新的大门。
一、理解核心：Agent与Harness的本质
1.1 LLM的四个致命缺陷
要理解Harness的价值，我们首先要认清纯大语言模型的局限性。一个拥有超强能力，读过几乎所有公开书籍，代码和论文的LLM，当你要求它把一段代码写进文件时，它会面临一个尴尬的事实，它做不到。这不是能力不够，而是结构性缺陷。
LLM作为纯推理引擎，有四个致命的短板。第一，没有手，能描述操作步骤，但无法执行任何一条命令，写入任何一个字节。第二，没有眼，对你的文件系统，Git状态，运行环境一无所知，每次对话都从零开始。第三，没有记忆，每次API调用都是无状态的，除非你把历史对话重新喂回去，它连自己上一句话说了什么都不知道。第四，没有缰绳，它可能建议你执行危险命令，但完全没有应不应该执行的判断力。
这四个缺陷不是LLM的bug，而是它的设计边界。LLM被设计为一个纯函数，输入token序列，输出token序列，无副作用。这个设计是正确的，一个能直接操作文件系统的语言模型会带来灾难性的安全风险。但这也意味着，要让LLM变成有用的Agent，必须有另一层系统来补全这些缺陷，这层系统就是Harness。
1.2 Harness：让大脑长出身体
Harness不参与思考，它不生成文本，不做推理。它的全部工作是让LLM的思考能够落地。具体来说，它补全了LLM的四个缺陷。工具系统给了LLM双手，让它能够执行各种操作。上下文注入给了LLM眼睛，让它能够感知环境信息。对话管理给了LLM记忆，让它能够记住历史对话。权限守卫给了LLM缰绳，让它能够安全地执行操作。
这个设计就像CSS的层叠模型，LLM提供默认行为，生成文本，Harness在上面叠加了一层又一层的能力增强和行为约束，最终组合出Agent的完整行为。从工程角度看，Harness远不是简单的胶水层，它包含了性能工程，并行预取，API预连接，安全工程，多层权限检查，默认保守策略，可靠性工程，优雅退出，运行时时序感知和隐私工程，信任后才采集遥测。
1.3 六层架构：Agent的完整解剖图
一个生产级的Agent系统，拥有六层清晰的架构。入口层负责CLI解析，模式选择，决定交互还是非交互模式。引擎层是Agent的核心，驱动思考，行动，观察的主循环。工具层是Agent的手和脚，实现与外部世界的交互接口。状态层记住Agent做了什么，管理会话状态和UI状态。服务层支撑Agent做得好，包括API通信，MCP，压缩，分析，认证等。表现层展示Agent做的结果，提供终端UI交互。
这六层之间的依赖关系是自上而下的，入口层调用引擎层，引擎层调度工具层，工具层依赖服务层，表现层消费状态层，反向依赖极少。这个分层和Web应用的经典架构异曲同工，但多了两个Agent特有的层，引擎层和工具层。理解了这一点，你就可以把Agent系统当作一个会调API的Web应用来理解，只是它的用户请求来自LLM的响应。
二、核心循环：Agent的心跳机制
2.1 不是一问一答，而是循环往复
Agent的本质不是简单的一问一答，当你告诉它帮我重构这个函数，它可能要读文件，理解上下文，写代码，跑测试，发现报错，再改代码，一连串动作构成一个循环。学术界有一个被广泛接受的Agent模型，Message，Think，Act，Observe，Loop，接收指令，思考做什么，执行动作，观察结果，决定继续还是停下。
该系统忠实地实现了这个模型，但加了一层关键的工程抽象，把整个循环拆成两层。外层查询引擎负责会话生命周期，状态管理，消息录制，预算控制。内层查询函数负责单轮推理循环，调API，执行工具，决定是否继续。这就像一家餐厅，查询引擎是前厅经理，负责接待顾客，记账，控制翻台率。查询函数是厨房，负责实际做菜。前厅不关心菜怎么做，厨房不操心账怎么算。
2.2 AsyncGenerator：消息流动的最佳模式
消息在系统里怎么流动，为什么不用回调，事件发射器或Promise？该系统面临一个独特的挑战，消息的种类繁多，LLM输出，工具结果，流式事件，进度报告，系统通知，而且消费者的节奏和生产者不同。UI需要逐字显示，日志需要完整记录，SDK调用者需要结构化数据。
AsyncGenerator恰好解决这个问题。生产者，查询函数，通过yield推送消息，消费者，查询引擎，按自己的节奏拉取。这形成了一条背压友好的管道，如果消费者处理不过来，生产者自然暂停。更巧妙的是，AsyncGenerator支持嵌套组合，循环函数yield给查询函数，查询函数yield给引擎的提交方法，提交方法yield给外部调用者。每一层可以拦截，转换，过滤消息，而不破坏流式语义。
2.3 循环的终止：多重保险机制
Agent Loop不能永远转下去，什么时候停，谁来决定？终止条件的设计体现了一个原则，多重保险。不能只靠一个条件来停止循环，因为任何单一机制都可能失效。该系统至少有七种终止方式，分布在查询函数和查询引擎两层。
最核心的判断很简单，LLM的回复里有没有工具调用块。有就继续，没有说明LLM认为任务完成了。但即使LLM说我做完了，还要过一关，Stop Hooks。Stop Hooks是用户自定义的验证逻辑，比如每次写代码后必须跑测试，如果LLM写了代码但没跑测试就要停下，Hook会阻止终止，注入一条错误消息让循环继续。
在查询引擎层面还有额外的硬性限制，USD预算，累计花费达到上限时立即终止，最大轮数，轮数超出设定值时终止，结构化输出重试上限，JSON Schema验证失败超5次时终止。这些是断路器，防止Agent因为LLM幻觉或Hook死循环而无限运转。
2.4 流式响应：提升用户体验的关键
LLM生成一段回复可能需要5到30秒，如果等它完全生成好再一次性返回，用户会盯着一个空白屏幕发呆。答案是流式传输，LLM边生成边发送，用户能看到文字逐字出现。这不只是体验问题，在Agent场景下，流式传输还有一个关键用途，让工具执行和LLM输出并行。
LLM的API返回一系列事件，message_start，content_block_start，content_block_delta，多次，content_block_stop，message_delta，message_stop。每个content_block_delta携带一小段增量内容，一个文本片段，一段JSON碎片，一段思考过程。
流式传输还带来了一个巧妙的优化机会，流式工具并行执行。当LLM流式输出中出现一个完整的工具调用块，不必等整个响应结束就可以开始执行工具。想象LLM说我要同时读三个文件，传统方式是等LLM说完，再依次读取。流式执行则在LLM还在输出第二个工具调用块时，第一个文件已经开始读了，在多文件操作场景下，这能显著缩短延迟。
三、工具系统：Agent的手和脚
3.1 工具设计哲学：统一接口，灵活扩展
LLM本身不能读文件，不能执行命令，不能访问网络，它唯一能做的事情是输出文本。工具系统的使命，是把文本输出变成真实世界的操作。但这不是给每个功能写个函数那么简单，当你有40多个功能各异的工具，你需要回答一连串架构问题，如何定义统一的接口让工具之间互操作，如何注册和发现工具，让LLM知道自己有哪些能力。
该系统选择了用TypeScript的类型系统替代继承层次，工具在这个系统中是满足特定结构的对象，不是某个类的实例。三个泛型参数为每个工具提供精确的类型约束，BashTool的输入包含command字段，FileReadTool的输入包含file_path字段，类型系统在编译期就能捕获接口不匹配。
这种选择背后有一个工程理由，当你有40多个工具，且每个工具的输入输出结构完全不同时，类继承几乎无法提供有意义的复用。一个统一的结构类型反而更灵活，任何满足接口契约的对象都是合法的工具，不需要知道彼此的存在。
3.2 工具接口：每个字段都有意义
Tool接口的每个字段都在回答一个具体的问题。identity字段定义工具是谁，name是主标识符，aliases处理重命名的向后兼容，searchHint弥补工具名和用户意图之间的语义鸿沟。execution字段定义工具怎么干活，call是工具的心脏，执行具体操作，description是动态的，可以根据输入参数变化。
safety字段定义工具的安全性，三个布尔方法构成了工具的安全分类体系，isReadOnly判断这次调用是否只读，isDestructive判断是否不可逆，isConcurrencySafe判断能否与其他工具并行执行。关键细节，这三个方法都接受input参数，安全性不是工具的静态属性，而是每次调用的动态判断。
budget字段控制工具输出大小，maxResultSizeChars限制工具结果的持久化阈值，超过此大小的结果会被写入磁盘文件，只给模型发送一个预览。presentation字段控制工具在UI中的呈现，六个渲染方法让简单工具只需定义执行方法，复杂工具可以完全控制用户看到的每一帧。
3.3 三个代表性工具：设计取舍的典范
BashTool：最危险工具的安全化
BashTool是整个工具系统中最复杂的单体组件，超过2000行代码。它的复杂性不来自功能实现本身，而来自一个根本矛盾，你需要让LLM拥有执行任意shell命令的能力，同时防止它做出不可逆的破坏。
BashTool的输入schema使用宽松解析器，容忍模型的不精确，LLM有时会把true输出为字符串"true"，把数字5000输出为"5000"，宽松解析器静默转换吸收差异。它的并发安全性是命令的函数，不是工具的常量，只有整条命令链都是只读时，才允许并行。
BashTool实现了多层安全防护，沙箱模式限制对文件系统和网络的访问，命令分类驱动UI折叠，权限匹配解析命令AST，确保安全策略准确执行。即使是这样强大的工具，也被严格约束在安全框架内，确保能力与安全的平衡。
FileReadTool：最常用工具的高效化
文件读取是Agent最频繁的操作，当18%的读取是重复的，怎么在不影响正确性的前提下节省token？FileReadTool实现了基于文件修改时间的智能去重，如果文件未修改且读取范围相同，返回一个文件未变化的存根，而不是重新发送全部内容。
FileReadTool定义了一组被阻断的设备路径，/dev/zero，/dev/random等，防止无限输出或阻塞等待。它还实现了token计数的两阶段策略，先用粗估函数做快速估算，只有粗估值接近或超过限额时，才调用精确计数，节省API调用开销。
每次读取文件时，系统还会检查文件路径是否触发技能发现，读取package.json可能激活Node.js相关技能，读取Cargo.toml可能激活Rust技能，这种按需激活的技能机制让Agent更智能。
AgentTool：最复杂工具的抽象化
AgentTool不是一个普通的工具，它是整个Agent系统的递归入口。调用AgentTool等于从内部再造一个完整的Agent，拥有独立的上下文，工具集，甚至独立的权限模式。
AgentTool的输入schema根据运行时条件动态变形，根据feature flag裁剪参数，确保模型永远不会看到它不能使用的参数。子Agent不能使用所有工具，系统定义了禁用工具列表，防止子Agent越权操作。
AgentTool支持五种执行模式，同步Agent，异步后台Agent，Teammate Agent，Remote Agent，Worktree隔离，这五条路径共享同一个入口点和schema，模型不需要知道底层的分发逻辑，只需要说给我启动一个Agent做这件事，系统根据参数组合自动路由到正确的路径。
3.4 工具编排：并发，进度与预算控制
当LLM一次可能输出多个工具调用块，三个文件读取，一条shell命令，一次搜索，五个工具调用同时到来，哪些可以并行，执行中怎么报告进度，结果太大怎么控制？
StreamingToolExecutor实现了并发执行的状态机，四个状态，queued，executing，completed，yielded，确保工具按序执行，结果按序返回。它的并发判断规则很简单，如果没有工具在执行，任何工具都可以开始，如果有工具在执行，新工具只有在自己和所有正在执行的工具都是并发安全的情况下才能开始。
系统实现了两层结果预算控制，第一层是单工具持久化，超过阈值的结果写入磁盘，模型收到预览。第二层是消息级聚合预算，控制单条消息的总大小，采用贪心算法替换最大的结果，直到总大小降到预算以内。
为了保护prompt cache，系统设计了不可变的内容替换状态，每个工具调用一旦被看见，它的命运就被冻结了，后续不会修改早期的替换决策，确保prompt cache的稳定性。
四、安全与权限：Agent的缰绳
4.1 权限模型：四层纵深防御
Agent有能力做一切，但不应该做一切，权限系统是Harness最沉重的职责。传统软件的权限模型建立在确定性之上，用户点击删除按钮，程序删除文件，因果链清晰可控。AI Agent彻底打破了这个范式，模型输出是概率性的，同一个prompt在不同上下文下可能产生完全不同的工具调用序列。
该系统的解决方案可以用机场安检来类比，四层纵深防御。第一层是工具自检，安检门，每个工具知道自己的危险边界，主动检查输入。第二层是规则引擎，X光机，根据配置的deny/allow/ask规则做确定性判断。第三层是ML分类器，人工抽检，用另一个模型判断灰色地带的操作。第四层是用户审批，登机口确认，最终兜底，人类做出最后决策。
所有工具调用的权限检查都汇聚在一个统一入口函数中，它创建一个Promise，将整个四层决策流封装为异步操作，返回值只有三种，allow，deny，ask，简洁的三值语义让后续所有层的处理逻辑都清晰可控。
4.2 五种权限模式：安全与效率的刻度盘
权限模式是系统层面的安全刻度盘，可以把它想象成汽车的驾驶模式，同一辆车，不同模式下操控感完全不同。default模式是日常驾驶，未匹配规则的操作都需用户确认，这是最安全的模式，适合日常交互。acceptEdits模式是半自动，工作目录内的文件编辑自动允许，但shell命令，MCP工具等仍需确认。
auto模式是自动驾驶，用ML分类器代替用户做出大部分决策。dontAsk模式是静默拒绝，将所有ask转为deny，绝不弹窗，适合非交互式批处理环境。bypassPermissions模式是全信任，几乎所有操作自动允许，但即使在这个最宽松的模式下，安全检查仍然生效，敏感路径依然受保护。
这五种模式不是孤立存在的，plan模式可以和bypassPermissions组合，当用户原本在bypass模式下进入plan模式时，plan模式继承了bypass的宽松度，避免了模式切换时的体验断裂。
4.3 风险分级与自动审批
不是所有操作都一样危险，读文件和删文件，风险完全不同。自动化的安全判断如何区分这两者？答案是分层，在分类器介入之前，有大量确定性规则已经排除了两端的极端情况，明显安全的操作被白名单直接放行，明显危险的操作被黑名单直接拦截，分类器只处理中间的灰色地带。
系统定义了三级风险评估框架，LOW，MEDIUM，HIGH，每个评估附带explanation，发生了什么，reasoning，为什么有风险，risk，最坏情况，这让权限弹窗不再是无上下文的Allow/Deny，而是带有充分信息的安全决策。
分类器采用双阶段决策流，第一阶段是快速阶段，最大64 tokens，温度为0，保守判断，宁可误杀，不可放过。第二阶段是思考阶段，只在第一阶段说阻止时才运行，最大4096 tokens，深入推理，纠偏第一阶段的误报。两阶段设计的效果是，大部分安全操作在第一阶段就通过了，低延迟，只有可疑操作才需要第二阶段的深度分析，高准确率。
4.4 Hooks：可编程的安全策略
声明式的deny/allow规则无法表达只拒绝git push到main分支这类需要理解操作内容的策略。Hooks就是为此而生的，一个可编程的策略扩展点，让用户用自己的代码参与权限决策。
系统支持四种Hook类型，Command Hook执行shell命令，Prompt Hook用独立的LLM评估操作，HTTP Hook将事件POST到远程URL，Agent Hook启动一个完整的Agent来执行验证。每种Hook都支持if预过滤，只在匹配特定模式时触发，避免不必要的开销。
Hook通过stdin/stdout的JSON协议与主进程通信，不依赖任何编程语言或运行时，Python脚本，Node.js程序，curl调用，甚至一个jq管道，只要能读stdin写stdout，就能成为安全策略。Hook在权限流程中有两个介入时机，PreToolUse在工具执行前触发，可一票否决，PermissionRequest与用户对话框竞赛，快速决策可避免弹窗。
五、多智能体：从独行侠到团队
5.1 子Agent：任务分解的利器
一个Agent为什么不够用？让Agent重构一个认证模块，它需要先调研现有实现，再修改代码，最后跑测试验证，三件事串行执行效率低下，更麻烦的是，调研过程产生的大量中间信息会污染工作上下文，等到真正动手改代码时，关键信息已被淹没在几十轮对话里。
子Agent要解决的根本问题是，如何让一个Agent体系既能并行工作，又能保持每个工作者的上下文纯净。该系统给出的答案是分，隔，通，分，把大任务拆给多个子Agent，隔，每个子Agent拥有独立的消息历史，文件缓存和中止控制器，通，父子之间通过结构化的消息协议交换结果。
子Agent有两条创建路径，空白Agent轻装上阵，从零开始，只携带当前任务需要的信息。fork Agent继承父Agent的全部对话历史和系统提示词，用共享的上下文前缀换取API cache命中，大幅降低成本。fork路径的精妙之处在于，所有从同一父消息分叉出的子Agent，其API请求前缀是字节级完全一致的，只有最后的指令文本不同，让多个子Agent共享同一份prompt cache。
5.2 协调者模式：项目经理的智慧
从全能选手到项目经理，普通模式下，主Agent身兼数职，既是规划者又是执行者。协调者模式的核心洞察来自一个古老的管理学原理，理解问题和解决问题应该分离。协调者只做三件事，理解用户意图，分配任务给Worker，综合结果回复用户，它自己不读文件，不改代码，不跑命令。
协调者的工具集极度精简，只有三个核心工具，Agent创建Worker，SendMessage继续Worker，TaskStop停止Worker，连一个文件操作工具都没有。这是刻意的约束，如果协调者能直接读写文件，它就会忍不住自己动手，LLM的本能倾向是直接解决问题而非委派问题，去掉直接操作工具，从架构层面强制协调者必须通过Worker间接完成任务。
协调者采用四阶段工作流，Research调研，Synthesis综合，Implementation实施，Verification验证。四个阶段不能简化，Research阶段收集信息，Synthesis阶段综合分析，Implementation阶段执行任务，Verification阶段验证结果，每个阶段都有明确的职责，确保任务高质量完成。
5.3 任务系统：后台并行的基础设施
当子Agent在后台运行时，系统需要一个集中的基础设施层来追踪它们的状态，进度，崩溃恢复，优雅中止。任务系统就是这个层，它不直接参与业务逻辑，但为上层的Coordinator，Agent协作，Team机制提供了统一的状态管理，持久化和生命周期控制。
系统定义了七种任务类型，local_bash后台shell命令，local_agent本地异步子Agent，remote_agent云端执行Agent，in_process_teammate同一进程内的teammate，local_workflow工作流编排，monitor_mcp MCP服务监控，dream记忆巩固Agent。每种类型都有明确的使用场景和生命周期。
任务ID采用一眼看穿类型的前缀设计，每种类型有一个单字母前缀，后面跟8位随机字符，人类可读性强，安全性高，大小写安全。任务状态机简单但严格，只有五种状态，pending，running，completed，failed，killed，状态转移是单向的，没有暂停状态，没有重试状态，避免复杂的状态机bug。
5.4 Team与Swarm：群体智能的实现
从树形到网状的质变，子Agent和Coordinator模式都是树形结构，一个父级派生多个子级，子级只向父级汇报，兄弟之间互不通信。Team与Swarm实现了网状通信，让Agent之间可以直接对话，横向协作。
Team的核心配置结构是TeamFile，基于文件系统的配置中心，存储在~/.agent/teams/{team-name}/config.json，包含团队名称，创建时间，leader ID，成员列表等信息。选择文件系统是因为它是唯一天然的跨进程共享介质，不需要额外的IPC机制，消息中间件，数据库进程，在容器，远程服务器，CI流水线中都能开箱即用。
通信核心机制是Mailbox，每个teammate有一个独立的收件箱文件，基于文件的消息总线。Mailbox采用文件锁确保并发安全，支持普通文本消息和十二种结构化协议消息，权限协调，生命周期，配置同步，计划审批，任务分配，共用同一管道，在消费端分流。
六、Prompt与记忆：Agent的灵魂和笔记本
6.1 System Prompt组装流水线
System Prompt是Agent的入职说明书，你是谁，能做什么，怎么做。一个要在真实代码仓库中干活的Agent，它的说明书需要包含身份声明，安全红线，工具规范，代码风格，当前环境快照，用户个人记忆，MCP服务器说明等。
核心矛盾是，Prompt越丰富Agent越聪明，但越丰富也越贵。该系统的解决方案是把System Prompt当作一条流水线，不同工位负责不同段落，静态的段落跨用户缓存，动态的段落按需重算。这条流水线的产出不是一个字符串，而是一个字符串数组，每个元素是一个独立段落，下游的缓存切分器可以精确地在段落边界上动刀。
System Prompt分成两半世界，静态半区和动态半区。静态半区包括身份声明，安全规则，工具指南，风格要求，变化频率低，版本发布时才变，支持全局缓存。动态半区包括环境信息，记忆，MCP指令，语言偏好，每会话甚至每轮变，不缓存或会话内缓存。两半之间有一条清晰的分界线，动态边界标记字符串。
6.2 记忆系统：让Agent拥有经验
记忆的问题更深层，LLM的上下文窗口是高速但易失的工作记忆，每次新会话，模型面对的是一片空白。用户说我上次跟你说过不要用mock测试了，Agent却一脸茫然，这种失忆的体验像和一个健忘的同事合作。
该系统的记忆理念很简单，记忆就是文件，不需要向量数据库，不需要embedding服务，只需要Markdown文件和一套管理机制。记忆的完整生命周期包括发现，注入，提取，检索，整合。
系统实现了五层AGENT.md的发现策略，从项目根目录到子目录，逐级查找记忆文件。四类自动记忆的提取触发，用户指令，工具执行，对话总结，梦境整合。相关性检索采用关键词匹配，从200条记忆里找最相关的5条。Dream系统实现了记忆的后台整合，会睡的Agent，在后台默默运行记忆巩固，清理碎片，更新长期记忆文件。
七、扩展机制：开放的Agent生态
7.1 MCP：连接外部世界的协议
Agent的能力边界在哪里？内置工具覆盖了软件开发的常见场景，但世界在变化，团队可能需要调用内部API，查询私有数据库，集成特定的CI/CD系统。MCP，Model Context Protocol，是连接外部工具和数据源的标准协议，通过标准协议连接外部工具和数据源，MCP服务器可以用任何语言编写，通过stdio或SSE与Agent通信。
MCP实现了连接状态机，五种状态的精确报告，建立连接从自我介绍到工具发现，认证挑战支持OAuth与XAA双轨制，七层配置从企业到本地的合并策略，去重处理同一个Server从多个渠道来的情况，断线重连不是简单重试，而是有状态机管理的重连机制。
MCP的安全策略支持allowlist，denylist与三维匹配，连接并发控制批量大小，确保连接稳定高效。MCP是最推荐的扩展方式，因为它完全解耦，MCP服务器对Agent的内部实现一无所知。
7.2 Skills：用户自定义能力
Skills是用户自定义能力，可复用的提示词模板，教会Agent新的技能。比如一个Skill可以教Agent如何按照团队规范写代码评审。Skills不涉及代码执行，只是结构化的上下文注入。
Skill的物理形态是一个目录，一个文件，支持多源并行加载，五路竞速。Skill通过注册，解析机制变成Command，内置Skills编译进二进制，提供专业知识。条件激活通过文件路径触发Skills，动态发现运行中找到新Skills。
Skills与MCP是互补关系，MCP提供外部工具连接，Skills提供内部知识增强，两者结合让Agent的能力无限扩展。
7.3 Commands与Plugin体系
Commands是用户交互的入口，系统支持三种命令类型，不同的执行模型，命令注册采用memoized的大数组，Feature-Gated命令支持编译期裁剪，未启用的特性对应的代码直接从bundle中消除。
Plugin体系是比Skill更重的扩展，插件可以注册新工具，新命令，新MCP服务器，甚至修改权限规则。系统有完整的插件生命周期管理，安装，启用，禁用，更新，市场分发。
Commands，Skills，Plugins，MCP构成了四层扩展体系，按侵入性从低到高排列，大多数用户的需求可以通过MCP或Skills满足，零侵入，只有深度定制才需要Hooks或Plugins。
八、设计哲学：构建可信AI Agent的原则
8.1 七条核心设计原则
从这套完整的Agent Harness工程学中，我们可以提炼出七条构建可信AI Agent的核心原则。
第一，默认保守，安全优先，所有安全相关的默认值都倾向于更保守的行为，未知情况下，选择限制而非放行。第二，纵深防御，多层防护，从工具自检，规则引擎，ML分类器到用户审批，任何单一层次的失败都不会导致整个系统的安全崩溃。
第三，职责分离，清晰边界，查询引擎管生命周期，查询函数管推理循环，协调者管编排，Worker管执行，每个组件有明确的职责，不越权。第四，渐进式增强，从简单到复杂，基础功能稳定可靠，高级功能按需启用，不追求一步到位。
第五，缓存友好，成本可控，所有设计都考虑prompt cache的稳定性，静态内容缓存，动态内容最小化，降低token消耗。第六，可观测性，可审计性，每一个操作，每一个决策都有记录，可追溯，可分析，可调试。
第七，以人为本，用户可控，最终决策权始终在用户手中，自动化是辅助，不是替代，Agent是工具，不是主人。
8.2 四根支柱：从Harness模式到部署架构
构建生产级Agent Harness有四根支柱，第一，Agent等于LLM加Harness，明确分工，LLM负责思考，Harness负责执行，安全，记忆，扩展。第二，Agent Loop是核心循环，思考，行动，观察，迭代执行，驱动整个系统运转。
第三，工具系统是能力接口，统一接口，动态注册，安全检查，并发控制，让Agent能够与真实世界交互。第四，安全与权限是必要约束，四层防御，风险分级，可编程策略，确保Agent安全可控。
基于这四根支柱，可以构建从简单到复杂的各种Agent部署架构，从本地单Agent，到云端多Agent，从个人助手，到企业级智能体团队。
结语：AI Agent的时代已经到来
今天，我们完整梳理了构建AI Agent Harness的全部工程学体系，从核心心智模型，Agent等于LLM加Harness，到六层架构，核心循环，工具系统，安全权限，多智能体，Prompt记忆，扩展机制，设计哲学。这不是某个特定产品的实现细节，而是一整套构建可信AI Agent的通用工程方法论。
当我们理解了Harness的重要性，我们就真正理解了Agent是什么。LLM只是大脑，Harness才是让大脑变成能行动，能感知，能记忆，能协作的智能体的关键。在AI Agent从概念走向产品的爆发期，掌握Harness工程学，就是掌握了构建下一代AI应用的核心能力。
无论你是开发者准备构建自己的Agent产品，架构师评估Agent框架，LLM研究者探索模型能力的边界，还是技术人员好奇Agent背后的原理，这套工程学体系都将是你最宝贵的指南。它来自生产级系统的实战经验，经过数百万用户的考验，提炼出可迁移的设计模式和架构决策。
AI Agent的时代不再是将来时，而是现在进行时。最好的Agent产品还没有被写出来，也许它就在你读完这篇文章之后诞生。理解了Harness怎么造，你就真正理解了Agent是什么，你就有能力创造出更强大，更安全，更实用的AI智能体，让AI真正走进现实世界，解决实际问题。当前文件内容过长，豆包只阅读了前 76%。
