Agent Harness（智能体支撑架构） 本质上是包裹在大模型（LLM）外层的"底盘工程"与操作系统。如果把大模型比作一台引擎，Harness 就是把方向盘、油门、仪表盘、刹车和外部工具全部组装起来的整车架构。
现代通用 Agent Harness 的设计并非盲目堆砌功能，而是建立在 PTC 设计原则 之上，由 6 大工具拼图、3 个系统事件与 7 层系统提示词 组成。
一、 核心设计哲学：PTC 原则（代码化工具调用）
在设计 Harness 的工具之前，必须先理清工具的抽象层级：
-
朴素陷阱（Atomic Tool 堆叠）： 早期开发习惯根据业务需求一个接一个加工具（如查订单做
queryPending、查业务员做queryCommissioner）。这会导致工具定义占满 System Prompt（即 Prefill 膨胀），像 Anthropic 曾测算 58 个原子工具就会吃掉 55K 的 Token，严重挤占对话上下文。 -
PTC 解法（Programmatic Tool Calling）： 既然大模型的代码生成能力已经极强，且编程语言本身是图灵完备的，直接给 Agent 提供编写与执行代码的能力即可。Agent 面对新需求时，自己写脚本（如 Python/Bash）、调 SDK 处理数据并输出结果。
-
复杂度转移： PTC 将"定义成百上千个业务工具"的工程复杂度，转移到了"大模型自身的 Coding 能力与执行沙箱的安全隔离"上。
二、 Agent Harness 标准架构：六大拼图
一个完整的通用 Harness 需要装配以下 6 个维度的工具与机制：
| 模块分类 | 核心工具 / 机制 | 角色与通俗解释 |
|---|---|---|
| 1. PTC 工具组 | write、read、edit、bash |
基础动手能力。Agent 可以创建代码文件、查看局部内容、精准替换代码片段并在命令行里运行它。 |
| 2. 规划与子智能体 | task、enter_plan、exit_plan、todo_write |
大脑指挥部 。复杂任务由 task 委派只读或专能子智能体执行；规划模式与待办清单用来防止目标漂移、随时恢复上下文。 |
| 3. 上下文补齐 | ask_user、grep、glob、web_search、web_fetch |
防幻觉情报网 。信息不足时向人询问（ask_user），查本地代码/文件（grep/glob），或者联网搜索并提取网页文本。 |
| 4. 循环工程 | get_goal、set_goal |
长程目标校准。维持长期目标的锚点，属于相对低频的持久化指引工具。 |
| 5. 记忆持久化 | read_skill 工具 + 项目基建发现 |
知识加载器 。按需将特定专业技能（如 SKILL.md）调入上下文，避免一开始全量注入。 |
| 6. 上下文压缩 | compact（系统事件） |
内存垃圾回收。对话历史快撑满时自动压缩。 |
三、 系统事件（System Events）：不能让模型自己决定的机制
并非所有逻辑都适合做成模型自主调用的 Tool。为了保证系统的确定性与稳定性，以下三件事被设计为无须模型思考、触发即执行的系统底层事件：
-
SKILL 自动发现（创建新 Session 时触发）： 系统扫描工作区所有的技能文件，仅把 Skill 的名称、简介和调用方式提取成目录写入提示词，具体内容待调用时再读。
-
AGENTS.md 自动发现（创建新 Session 时触发）： 自动读取项目的全局开发规范、项目约束，直接灌入提示词顶层。
-
上下文压缩 Compact（上下文占用达到约 80% 时自动触发）： 绝不能让模型自己决定何时清内存，当 Token 消耗接近阈值，底盘自动截断早期执行轨迹并做摘要总结，替换下一轮请求的上下文。
四、 架构粘合剂：七层 System Prompt 设计
将上述组件串联起来注入大模型的，是一套严密的结构化系统提示词（System Prompt）：
-
身份定位（Identity）： 说明 Agent 是谁、主要角色与核心目标。
-
行为准则（Guidelines）： 设定语气风格、思考方式与通用操作禁忌。
-
操作边界（Boundaries）： 明确 PTC 的权限红线（如限制在特定目录内操作，超出路径必须调用
ask_user征求授权）。 -
工具定义（Tool Schema）： 注入
write、read、bash等工具的参数规范。 -
技能索引（Skills）： 注入已发现的 Skill 列表与简要描述。
-
项目规则（AGENTS.md）： 注入项目级的代码规范、提交规范等硬性约束。
-
记忆管理（Memory Policy）： 规定哪些工作经验可以存入长期记忆、存放路径及更新机制。
五、 落地该架构时的现实权衡
设计这套 Harness 时，需要注意两个现实边界：
-
安全性沙箱： 给予 Agent
bash权限意味着它拥有毁灭性操作的能力（如误删数据、修改关键配置），必须配合容器/沙箱进行网络隔离与权限截断。 -
基模门槛： 这套架构要求底层模型不仅能听懂人话，还必须具备极高的代码编写可靠性（Coding 能力）与工具规划逻辑（Agentic 能力）。