企业官网建设流程全解析

最近我把 pi agent 的默认 harness 彻底拆了一遍，按自己团队的需求做了一次深度定制。整个过程走下来，最大的感触是：网上讲“harness 和 agent 区别”的文章一大堆，但绝大多数都在重复概念，真正能把“从默认状态到生产可用”这条定制路径讲清楚的，几乎没有。这篇文章就把我这次 pi agent 定制全流程的完整思考、实施步骤和踩过的坑整理出来，给正在做或者准备做 Agent 定制的人一个可以直接照抄的参考。

这篇内容不是 pi agent 的官方文档翻译，也不是通用 AI 概念科普，而是我实际动手后沉淀出来的 best practice。适合这几类人看：已经接触过 pi agent、想改掉默认行为的人；正在纠结“agent 和 harness 到底是什么关系”的人；以及那些把 agent 集成进业务、想避免上线后反复返工的人。下面从最基础的认知问题开始，一步步拆开讲。

1. 先理清一个核心问题：pi agent、Harness 与 Agent 到底各负责什么

1.1 为什么网上总把 harness 和 agent 搞混

我观察了很久，发现大家混淆这两个概念，根源在于：绝大多数的 coding agent 产品，包括 pi agent，本身就把 harness 和 agent 打包在一起交付了。用户看到的只是一个对话框 + 自动执行的脚本，自然分不清哪里是“脑子”，哪里是“骨架”。

简单来说，agent 是决策者，它负责理解用户意图、拆解任务、决定下一步调用哪个工具；而harness 是承载这个决策过程的运行环境，包括工具集、上下文管理逻辑、执行循环、权限控制、失败重试机制等等。打个比方：agent 是司机，harness 是车。司机负责判断什么时候转弯、什么时候超车，但方向盘、油门、刹车、仪表盘、安全气囊这些“基础设施”全部是车决定的。司机可以很厉害，但如果车的方向盘不跟手、刹车有延迟，再好的司机也跑不出好成绩。

pi agent 默认自带的 harness 是围绕“通用编程场景”调校的，它能帮你在仓库里改代码、跑测试、提 PR。但一旦你的使用场景变得具体——比如必须调用内部发布平台、必须遵守某种提交信息格式、必须在高成本操作前强制人工确认——默认 harness 就不够用了。这时候规划者就得去动 harness，而不是去换一个“更聪明的模型”。

1.2 “agent + harness + 长上下文 + CoT”这条范式怎么理解

在 pi agent 的工作流里，有一个经常被反复提到的组合范式：agent + harness + 长上下文 + CoT。这四个词不是并列的四个组件，而是一条完整链路上的四个关键环节。

• Agent：任务拆解与决策中心，负责“做什么、先做哪步”。
• Harness：执行环境与工具容器，负责“用什么做、在什么约束下做”。
• 长上下文：agent 的“工作记忆”，让它能跨文件、跨步骤记住前面发生了什么。
• CoT（Chain of Thought）：决策过程的思考链，让 agent 在动手前先推理，而不是蒙头猜。

我自己的理解是：长上下文给 agent 视野，CoT 给 agent 路径，harness 给 agent 手脚，agent 本身则负责把这条链路串起来。定制 pi agent 的真正含义，就是按自己的业务需求重新设计这四者的协作方式。很多人以为定制只是改 prompt，实际上 prompt 只是 CoT 引导的一部分，更关键的部分——比如长上下文怎么存、工具怎么暴露、权限怎么控制——全部落在 harness 层。

1.3 定制的重心在 harness，而不是模型权重或咒语式 prompt

这里我想先打破一个常见的期待：如果你希望 pi agent 做出某种行为改变，首先不要想“要不要微调模型”。绝大多数情况下，通过调整 harness 就能覆盖 80% 的需求。模型的推理能力是底座，但你给它的工具、上下文、约束边界，才是决定它行为表现的上层建筑。

举个例子。我最初想让 pi agent 在提交代码前自动跑一遍指定的 lint 脚本。我尝试在系统 prompt 里写“每次提交前必须执行 npm run lint”，结果它在简单仓库里遵守得很好，一旦任务链路变长就经常忘记。我后来把 lint 工具直接挂到 harness 的工具列表，并且在“提交”这个工具前设置了一个前置校验钩子。效果完全不同——因为我不再依赖 agent 记住规则，而是 harness 在结构上强制了这条规则。

这就是定制 harness 和调 prompt 的本质区别：prompt 是建议，harness 是约束。建议可以被忽略，约束不会。

2. 定制前必须想明白的需求清单：别让默认设置替你决定一切

2.1 先画出“agent 自主范围”的边界图

动手改 harness 之前，我建议你先花半小时完成一张“自主范围边界图”。说白了，就是把 agent 可能执行的所有动作分成三类：可以完全自主的、需要中间确认的、永远禁止触碰的。

这一步看起来简单，却是整个定制流程里最容易跳过的关键环节。因为 pi agent 的默认行为是偏向“多干活”的，它倾向于自主执行完一个长链路任务再回报结果。如果你的场景里存在不可逆的高风险操作（比如删除分支、发布上线、直接改生产数据），就必须在 harness 层把这些动作的权限降级为“必须人工确认”。

我自己给某个项目定的边界是这样的：

这张表后面会直接映射到 harness 里每个工具的权限元数据上。没有这张表，你的定制大概率会在“太保守导致 agent 没用”和“太激进导致事故”之间摆动。

2.2 长上下文和 CoT 在 harness 层怎么取舍

第二个必须提前想清楚的问题是：你的任务到底需要多长的上下文，以及你愿意为每一步推理支付多少 token 成本。

先说长上下文。很多人看到模型支持 100k 甚至 200k 上下文,就觉得“那我全塞进去就好了”。实际用下来完全不是这样。上下文越长，单轮成本越高，响应延迟越大，而且模型对中段信息的注意力会被稀释。我见过一个团队把整个仓库的文档全部塞进上下文，结果 agent 在改代码的时候频繁引用过时信息，因为靠前的旧文档比靠后的关键约束更抢注意力。

在定制 harness 时，你要设计的是“上下文的入口规则”：哪些目录默认加载、哪些文件按需读取、哪些历史对话需要被压缩成摘要。我一般把上下文策略设计成三层：核心信息常驻（项目结构、当前任务目标）、中间层按需拉取（相关源码文件、测试报告）、边缘层用摘要替代（早前的对话、不相关模块的日志）。

CoT 也有同样的取舍问题。全量开放 CoT 能提升复杂任务的推理质量，但也会带来两个副作用：一是 token 消耗暴涨，二是当 CoT 输出过长时，模型容易被自己写出的错误推理带偏。我通常在 harness 里给 CoT 设置一个“分层开关”：简单任务直接行动，中等任务默认简短推理，只有复杂任务才输出完整思考链。

2.3 明确失败容忍度，再决定护栏强度

最后一项需求清单是失败容忍度。你要问自己：如果 agent 在某个环节判断失误，最坏后果是什么？这个问题的答案直接决定了你在 harness 上投入多少精力做护栏。

如果 agent 只负责写代码草稿，失败容忍度很高，护栏可以很薄，让 agent 自由发挥；但如果你让 agent 操作 Git 远端或触发构建发布，失败容忍度就很低，must have 的护栏包括：操作前确认、可回滚快照、超时熔断、敏感动作黑名单。我自己的经验是，先按照“失败后需要人工恢复的时间”来定义容忍度：超过 10 分钟才能恢复的动作，一律进入强护栏区；超过 1 小时才能恢复的动作，默认禁止 agent 直接执行。

3. Harness 定制全流程：一条可以直接照做的实施路径

3.1 第一步：拆解认知循环，找到每个环节的定制入口

整个 harness 的核心是一条认知循环：观察 → 思考 → 行动 → 验证。pi agent 的每一次任务推进，本质都是在快速重复这个循环。定制 harness，首先要把这条循环的数据流看清楚。

• 观察：agent 获取当前环境信息的方式。包括读取哪些文件、执行什么命令来感知状态（比如 git status、测试结果）。
• 思考：agent 基于观察结果做推理。这里会用到 CoT，也依赖长上下文提供背景。
• 行动：agent 调用工具改变状态。工具是行动的唯一入口。
• 验证：agent 检查行动是否达到预期。比如重新跑测试、检查 diff。

我建议你拿到 pi agent 后，第一步不是改任何配置，而是打开日志接口，跑两三个典型任务，把这条循环中每步的输入输出录下来。你会很快发现：bottleneck 到底在观察环节（信息不足）、思考环节（没理解约束）还是行动环节（工具不好用）。这份日志就是定制的需求清单，比任何凭空设计都准确。

3.2 第二步：把工具集装进 harness，并给工具写“说明书”

工具是 agent 和真实世界交互的桥梁。pi agent 默认提供了一套基础工具（文件读写、终端命令执行、代码搜索等），但这些工具是通用化的，缺少领域信息。定制时要做两件事：增删工具和丰富工具描述。

很多人容易忽略第二点。其实工具的描述（也就是常说的 tool schema）直接决定 agent 能不能正确使用它。描述写得模糊，agent 就只能靠猜。我给你看一个我自己的工具配置片段作为参考（字段结构按你的 harness 实际情况调整）：

tools: - name: run_service_test description: >- 运行指定服务的集成测试，并返回测试报告摘要。 仅在修改了该服务的源码或配置后使用。 不要用此工具运行全量测试，全量测试请使用 run_full_test。 parameters: service_name: string timeout_seconds: type: integer default: 300 permission: auto post_validate: - check_exit_code - extract_failed_cases

注意描述里的两个关键点：第一，说明工具的适用时机（“仅在修改了该服务的源码或配置后使用”），这能帮 agent 在思考环节过滤掉错误选择；第二，明确指出该工具和其他工具的边界（“不要用来跑全量测试”），避免 agent 偷懒用轻量工具完成重型任务。

一个好的经验是：工具列表宁可精简也不要贪多。每次给 harness 加一个工具前，先问自己——“没有这个工具，agent 是否真的完不成任务？”如果只是“有了它可能更快”，我建议先不加。工具越多，agent 的选择空间越大，出错概率也越高。

3.3 第三步：上下文管理与记忆分层

定制流程中最关键、也最容易被低估的一步，是上下文管理。pi agent 默认的长上下文机制是一个持续增长的对话记录，但真正生产级的使用场景，必须建立分层记忆。

我采用的是三层记忆结构，在 harness 里分别对应不同的存储和处理逻辑：

1. 短期记忆（会话内）：记录当前任务执行过程中的中间状态，包括已修改的文件、已执行过的命令、已获得的测试结果。这一层最活跃，需要严格控制体积，通常每轮只保留最近 N 条决策记录，更早的内容折叠成摘要。

2. 项目长期记忆（跨会话）：保存这个仓库的架构决策、技术约束、历史变更原因。pi agent 在处理一个陌生仓库时，默认行为是“现场读代码”，但有了项目长期记忆，它可以直接从历史记录里获取“为什么这个模块不能直接删除”之类的关键背景。

3. 全局偏好（跨项目）：记录用户或团队的习惯。比如“提交信息必须遵循 Conventional Commits 规范”“错误处理优先使用 Result 模式而非抛异常”。这些偏好一旦写入，agent 在任意项目里都会遵循。

要在 harness 里实现这三层，常见的做法是：给每个记忆条目打上元信息标签（来源、时间、重要度），并在每次注入上下文前执行一次排序和过滤——只保留与当前任务相关的高优先级条目。

3.4 第四步：护栏、回退与失败处理

定制 harness 的最后一步是搭护栏。护栏不是用来限制 agent 的上限，而是用来兜住能预见的失败模式。

我归纳了四个必装的“安全件”：

• 确认闸门：针对环境不可逆类操作，在工具调用前插入确认环节。实现上可以在工具定义里增加require_confirmation: true标记，并映射到具体的交互模式（比如在操作前输出变更清单，等待用户确认后再执行）。
• 超时熔断：给所有外部子进程设置超时上限。默认情况下，一个命令卡住可能会导致整个 agent 流程挂死，加了超时后至少能及时报错退出。
• 重试策略：区分“可重试错误”和“不可重试错误”。网络抖动、临时锁文件这类错误可以自动重试 2~3 次；而编译失败、测试断言失败这类错误不能盲目重试，因为 agent 可能是在重复同一个错误路径。重试逻辑要搭配“重试前修改策略”的约束，而不是原样重放。
• 操作审计：记录每一次工具调用、执行结果、关键参数。这一步在开发阶段像是多余的，上线后它就是排查事故的唯一线索。

4. 定制过程中最容易翻车的 4 个隐性坑

4.1 坑一：把业务规则写进 Prompt，写完才发现 Harness 才是该管这个的地方

我在一次定制里，为了约束 pi agent 生成的代码风格，在系统提示词里写满了两百多行的规范要求：变量命名怎么定、函数长度不能超过多少、注释必须是什么语言。结果跑起来后我发现，长任务中 agent 对规则的遵守率显著低于预期，而且规则之间经常互相冲突。

后来我复盘，问题的根源在于：这些规则属于“硬约束”，硬约束应该由 harness 通过工具和校验器来强制执行。我的修改方案是：把代码风格校验规则做成 harness 里的一个code_style_check工具，agent 每次改完代码后必须调用它；调用结果中如果有违规项，agent 必须修正后才能继续下一步。这样 agent 记住不记住规则都不重要了，框架保证它绕不过去。这个转变帮我省下了巨大的调试成本。

4.2 坑二：长上下文裸奔，任务一长 token 就爆炸

第二个坑是一次真实事故。当时我给 pi agent 接了一个大型仓库的文档梳理任务，图省事把整个 docs 目录加进了上下文。任务执行到一半，日志显示 token 消耗飞速上涨，响应越来越慢，最后直接把上下文窗口塞满了。更尴尬的是，早期加载的文档内容早就被截断，agent 在后半程已经“失忆”，开始胡编乱造。

从那以后，我的上下文策略彻底改成了“按需加载 + 滚动摘要”：初始只注入目录结构和当前任务描述，agent 需要某个文件时再通过工具按需读取；每轮循环结束，把已处理过的内容压缩成 200 字以内的摘要，替换掉原始全长内容。按这个方案跑长任务，token 消耗基本只有原来的三分之一，稳定性还更高。

4.3 坑三：CoT 全量开放，推理过程变成不可控的话痨

有一段时间我迷信“思考链越长越聪明”，于是把 harness 里的 CoT 限制全部放开。效果在复杂算法任务上确实有提升，但在日常任务上带来了两个麻烦：一是每次决策前都要输出一长段推理，token 成本直接翻倍；二是当累计的 CoT 太长时，模型会把前面推理中某个片段的错误当成既定事实，沿着歪路越走越远。

我的解决办法是给 CoT 加“带宽限制”：对简单任务（改个文案、跑个测试），直接禁止输出推理过程，只给结论；对中等任务，允许输出最多 3 条关键决策理由；只有对跨多文件的复杂任务，才开放完整思考链。这个分级策略是在 harness 的判断节点里完成的，比单纯依赖模型自觉可靠得多。

4.4 坑四：没有可观测性，出了问题只能盲猜

最后一个坑是架构层面的。一开始我的定制只关注“agent 能不能把事做成”，完全忽略了“我能不能看到它怎么做的”。结果一次生产任务出错后，我手里只有最后一句错误信息，完全不知道 agent 前置做了哪几步、哪个工具的返回值导致了最终失败。

被逼无奈，我在 harness 里加了一条强约束：所有工具调用的输入输出都必须结构化落盘，并且每个循环节点都生成一条 trace 记录。后来排查问题的时间从小时级降到了分钟级。如果你也在做 harness 定制，我强烈建议第一版就把可观测性做进去，不要等出问题再补。你不可能优化一个看不见的系统。

5. 打包成生产级流程：测试、版本管理与团队协作

5.1 用“harness 即代码”的方式管理配置

当你把 pi agent 的 harness 定制到一定程度后，会面临一个新的问题：这些配置、工具定义、权限策略散落在各处，团队其他人怎么同步？我的做法是严格执行“harness 即代码”的原则——所有 harness 相关内容全部用纯文本配置文件管理，纳入代码仓库，走和业务代码一样的评审、合并、发布流程。

这样做的价值在于：任何人改了一条工具描述或一个权限配置，都会留下 review 记录和变更历史。出问题时可以快速 diff 出是哪个变更引入的，也能方便地回滚到上一个可靠版本。我见过太多团队在聊天软件里传配置文件，结果最后每个人手里的版本都不一样，这种混乱就是事故的温床。

5.2 建立评测集和回归任务，不能靠感觉验收

harness 一旦开始持续演进，就必须解决一个核心问题：怎么判断一次改动是变好了还是变坏了？只有靠评测集。我整理了一套针对 pi agent 定制场景的回归任务集，大概二十个任务，覆盖典型的高频操作和边界场景：普通 bug 修复、跨文件重构、带约束的提交、需要多轮确认的操作、以及一些故意设计的“诱导违规”场景。

每次修改 harness，我都先在评测集上跑一遍。比对的维度包括：任务完成率、平均耗时、工具调用次数、人为干预次数。这套评测集最大的作用是防止“修一个坑，出一个新坑”。没有它，你对 harness 质量的全部感知只能来自零散的线上反馈，那是没法做工程化迭代的。

5.3 团队协作时改 harness 的节奏与回滚方案

团队共用同一个 pi agent harness 时，最忌讳的是“边改边用”。我一个人改的时候，出了问题可以立即定位；团队共享后，A 的改动可能正在影响 B 的任务执行，这种干扰非常难排查。

我现在采用的节奏是：小步快跑加固定发布窗口。harness 的改动永远通过分支合入主分支，合入前必须跑完回归评测集。发布后观察两天线上任务日志，如果有异常就立即回滚到上一个 tag，而不是在线热修。这套节奏看起来保守，但在团队协作场景下反而是效率最高的，因为它把“不确定性”限制在了可控范围内。

最后分享一个我自己的小习惯：每次改完 harness，我会随手记录一个“这次改动的判断依据”小笔记，不是形式化的文档，就是一两句话，比如“因为上次长任务丢失了中间决策，所以给思考节点加了摘要折叠”。隔一段时间回看，会发现当初的一些直觉其实错了，但那些被验证为正确的判断，恰好是你对这个系统最深刻的理解。定制 pi agent 本身就是一个持续迭代的过程，别指望一次设计就完美，先让系统跑起来，再用观测数据一步步逼近你想要的效果。