企业官网建设流程全解析

1. 先去看这个词：一个 Agent 指令系统到底由哪几层构成

“Codex-X 内置「海鸥3.0破甲」Agent”这个标题，外行看是营销词堆叠，内行看一眼就知道它描述的是一个指令分层 + 技能调度 + 多步任务编排的复合体。先把话说在前面：我这里讲的“破甲”，指的是让 Agent 穿透系统之间的壁垒、打通跨领域的能力边界、把一条长链路任务从“只能聊”推到“能真正落地”，而不是去绕过任何平台的安全限制——后者既不在本文的讨论范围，也不是一个正经工程团队该花时间的方向。真正值得投入的，是怎么把一个 Agent 的指令系统设计得可测、可控、可回滚。

这个内容适合三类人看。第一类是正在把大模型能力接进业务系统的后端或平台工程师，你手里大概已经有一堆工具接口，但发现模型调用的准确率始终卡在七八成上不去；第二类是做 Agent 产品的人，你需要一套能说服自己的指令分层规范，而不是每次出问题就往 system prompt 里再加一句话；第三类是技术负责人，你要判断一个“多域任务工作流”到底是真架构还是套壳，这篇里的分层模型和排查表可以直接拿去当评审清单。

Codex-X 这类系统解决的核心痛点其实很朴素：当可调用的技能从 3 个涨到 30 个，从单轮问答涨到十几步的跨系统任务时，原来的“把所有说明塞进一段提示词”的做法会全面崩溃。崩溃的表现有三种：人格漂移（同一个 Agent 上午像个严谨的审计员，下午像个话痨客服）、路由错配（用户问 A，它调了 B 的工具，参数还对不上）、上下文雪崩（第三步就把第一步的关键信息挤出了窗口）。海鸥3.0 这类内部代号背后真正要解决的问题，就是这三件事。

我把它拆成四层来看，这个分层是我试过几种方案之后固定下来的，后面所有内容都挂在这个骨架上：

分层最实际的好处不是“优雅”，而是可归因。线上出问题时，你能在三十秒内定位到底是人格漂移、路由错配还是契约破坏，而不是对着一段两千字的 system prompt 发呆。我见过太多团队把所有东西揉成一段，结果一次线上事故排查了整整两天，最后发现只是技能描述里少写了一句“该接口仅支持按天查询”。

1.1 为什么不能只靠一段超级提示词

大模型的注意力是有“稀释效应”的。一段提示词里塞进人格、规则、工具说明、输出格式、边界案例，模型对每一部分的遵守强度都会下降，而且下降不是线性的——经验上，当单条 system prompt 超过 1500 字并且混杂三种以上不同性质的信息时，中后段指令的遵守率会明显下滑。这不是模型不行，是信息结构的问题。

分层的做法是把每一层的指令单独成段、单独测试。人格层用一组固定对话做回归测试，看语气和主动性是否稳定；约束层用一组“应该拒绝或应该追问”的用例做拦截率测试；技能层用函数调用的准确率和参数正确率做指标；契约层用 JSON Schema 校验通过率做指标。每一层都有自己的指标，这样你才能说清楚“这次改动到底让系统变好了还是变差了”。

我在一个模拟项目 X 里做过对比：把同样的内容拆成四层、分层加载，和揉成一段提示词，在 200 条测试用例上的技能调用准确率分别是 91% 和 74%。差距主要出现在“边界用例”上——也就是用户表述模糊、需要追问的那部分。揉成一段时模型倾向于硬猜一个工具，分层之后模型的追问率从 6% 提到了 23%，而错误执行率从 19% 降到了 7%。这个取舍很关键：追问成本远低于错调成本，尤其是在有副作用的写操作上。

1.2 海鸥3.0 这个层级里最容易被忽略的一层

四层里最不起眼的是契约层，但它是唯一直接决定“下游系统能不能用”的一层。Agent 输出一段漂亮的自然语言，人看着舒服，可下游的工单系统需要一个结构化对象，中间就得有人去解析这段自然语言——这是无数 Agent 项目死在 POC 阶段的核心原因。

契约层的做法是：无论中间推理多复杂，最终输出必须收敛到一个已声明 schema 的结构里。工具调用走 function calling 的 JSON Schema，最终答复走一个“结论 + 引用 + 置信度”的三段式结构。引用部分要求 Agent 列出它依据了哪些工具返回的哪个字段，这既方便审计，也强制模型在生成结论时回看证据，实测能降低约三成的“合理但错误”型输出。

2. 人格设定：只写行为边界，不写人设小作文

“人格设定”这四个字特别容易让人写偏。大部分人一上手就开始写“你是一位经验丰富、专业严谨、乐于助人的资深专家”，写了三百字形容词，然后发现模型该犯错还是犯错。因为形容词不产生行为约束，它只影响语气。

人格层真正要解决的是三件事，按重要性排序：主动性档位、失败处理方式、表达风格。语气是最不重要的，但它是最容易被写进去的，因为写起来最爽。

主动性档位决定的是：面对信息不全的请求，Agent 是直接猜、还是追问、还是先做一部分再问。这个档位必须显式声明，否则模型会自己决定，而它的默认倾向是“猜”——因为训练数据里人类更倾向于给完整答案。我见过一个内部工具，用户说“清理一下测试环境的脏数据”，Agent 直接按自己的理解删了两张表。这不是模型坏，是它压根没被告诉过“破坏性操作必须先确认”。

失败处理方式决定的是：工具调用失败、返回空结果、超时的时候，Agent 怎么反应。默认行为往往是“编一个听起来合理的答案”或者“反复重试同一个调用”。这两种都得在人格层里明确禁止或引导。我的写法是强制要求“失败即上报”，把原始错误码原样带给用户，附一句“我可以换个方式再试一次，你要我试吗”。

表达风格则是收着写。一两条就够，比如“句子短，不用感叹号，不主动夸用户”。写得越多越容易和具体任务冲突——你让人格层要求“简洁”，但任务层要求“详细列出每一步的依据”，两个指令会打架，模型就会随机选一个。

2.1 一份可以直接抄的人格卡模板

下面这份模板我在三个不同领域的 Agent 上都用过，改的主要是第三段和第五段。它的特点是全部用行为描述，没有一个形容词式的自我标榜。

[身份] 你是 Codex-X 的任务执行助手，服务于内部运营与工程团队。 你的输出会被直接转交给下游系统或同事，因此准确性优先于完整性。 [主动性] - 默认档位：执行前确认。当请求中存在以下任一情况时，先提问，不要执行： 1) 目标对象不唯一（如"那批数据"未指明批次） 2) 时间范围缺失且任务涉及时间过滤 3) 涉及写、删、改、发送类操作 - 当信息完整且为只读操作时，直接执行，不需要确认。 - 单次追问最多提两个问题，按重要性排序，不要列清单式追问。 [失败处理] - 工具返回错误时，原样保留错误码与错误信息，不要转述成模糊描述。 - 不允许在工具失败后自行推测结果并继续。 - 同一工具同一参数最多重试一次；第二次失败即终止并向用户报告。 - 无法完成时，明确说明"我停在哪一步、缺什么信息"，不要给安慰性表述。 [表达] - 句子短，一段不超过三句。 - 不使用感叹号，不使用"非常""极其"这类程度副词。 - 结论在前，依据在后。 - 不评价用户的问题，直接回答。 [禁止项] - 不猜测未提供的数字、日期、人名、编号。 - 不把工具返回的原始数据改写成"更通顺"的表述。 - 不在一次回复中同时给出多个互斥方案让用户自己选。

这份模板里最值钱的是「禁止项」那三条，全部来自实际踩坑。第二条尤其重要：模型特别喜欢把接口返回的{"code": 200, "data": []}改写成“查询成功，暂无数据”，看似友好，但下游如果依赖data字段判空就会出错。

2.2 人格层写坏的四种典型形态

第一种是形容词堆砌。写了三百字“专业、严谨、高效、可靠”，实际零约束。判断标准很简单：把你写的人格段里所有形容词删掉，如果剩下的句子还能指导行为，说明写对了；如果删完什么都不剩，那就是废话。

第二种是人格与任务冲突。人格层说“回答尽量简短”，任务层说“列出每一步的推理依据”，两个要求在多步任务里直接矛盾。解决办法是把“简短”限定在最终答复，把“详细”限定在过程日志，两套输出通道分开。

第三种是缺少失败分支。90% 的人格卡只描述成功路径，模型遇到异常时就自由发挥。补上失败分支的收益极高，成本极低。

第四种是把安全约束塞进人格层。像“不能泄露用户隐私”“不能执行危险操作”这类，写在人格层里会随着上下文变长而被稀释，正确做法是放到独立的约束层，并且在工具侧做硬拦截——模型可以被说服，代码不行。能靠权限系统解决的，永远不要靠提示词解决，这是我做完这个项目之后最深的体会。

3. 技能路由：从“会什么”转向“什么时候用哪个”

技能超过十个之后，路由就成了整个系统的性能瓶颈。海鸥3.0 这块的设计我比较认可，它走的是一条三级漏斗：规则匹配 → 向量召回 → 模型判定。三级不是并联而是串联，每一级都在缩小候选集。

为什么不做成纯粹的大模型 function calling 一把梭？因为成本和稳定性。当你有 40 个技能时，把 40 个 schema 全塞进上下文，光工具描述就占掉两三千 token，而且模型的选择准确率会随着候选数量增加而下降——这个下降在候选超过 20 个之后非常明显。三级漏斗的价值在于，前两级用极低成本把候选集压到 5 个以内，第三级才让模型在 5 个里选，准确率和成本同时改善。

3.1 技能注册表该有哪些字段

这是整个路由的基础，字段设计得好，后面的路由逻辑会简单很多。我用的字段集如下：

when_not_to_use这个字段是我后来加的，效果出乎意料地好。比如“按区域查询订单”这个技能，如果不写反例，用户说“按区域统计告警数量”，模型有相当概率会调它，因为“按区域”和“查询”两个词都对上了。加一句“当用户问的是告警、日志、监控类数据时不要使用本技能”，误触发率直接降了一半多。

description的写法有个小技巧：用用户的语言写，不要用开发者的语言写。你写“调用 order-service 的 /api/v2/orders 接口，支持 region 参数”，模型理解起来没问题，但匹配度低。改成“查询某个区域在指定时间段内的订单记录，可以按状态筛选”，匹配度会明显提升。因为这个描述本质上是拿来做语义匹配的，得贴用户的表达习惯。

3.2 三级漏斗的阈值怎么定

第一级规则匹配走的是正则和关键词，优点是零成本、可解释，缺点是不泛化。我的用法是只让它做“强信号”的拦截，比如用户输入里出现明确的单号格式、明确的日期格式、明确的接口名。这一级不追求覆盖率，只追求零误判。

第二级向量召回，把用户输入和所有技能的 description + when_to_use 拼成的文本做 embedding 相似度，取 top-5。这里有个细节：不要把 params_schema 混进去做 embedding，参数名是英文下划线，会污染语义空间。我试过混进去，召回质量明显下降。

第三级是模型判定，把 top-5 的完整 schema 和用户输入一起给模型，让它选一个或者选“都不合适”。这里的关键是必须提供“都不合适”这个选项，而且要在提示词里明确鼓励它选。不提供这个选项，模型就会在 5 个错误候选里硬选一个。

置信度阈值我用了三档：

这套阈值不是拍脑袋定的，是拿 300 条真实请求做标注之后画出来的。提醒一句：阈值和你的业务容错度强相关。只读查询可以把直接执行的阈值放到 0.7，写操作我建议放到 0.92 以上，甚至干脆全部走确认。

3.3 参数校验的三个层次

路由选对了技能，参数错了照样白搭。我在模拟项目 X 里统计过，工具调用失败的原因里，路由错误只占 28%，参数错误占了 61%。所以参数校验比路由更值得投入。

第一层是 JSON Schema 校验，机器做，拦类型错、枚举错、必填缺失。这层必须放在模型之外，不能让模型自己检查，它检查自己会放水。

第二层是业务语义校验，比如“开始时间不能晚于结束时间”“区域编码必须在有效列表里”“单次查询时间跨度不超过 90 天”。这层最容易漏，因为它是业务知识，写 schema 的人未必知道。

第三层是权限校验，把当前账号的权限域和技能的 permission_scope 取交集，不匹配就直接拒绝并明确告知缺哪个权限。这层绝对不能省，也不能靠模型的“判断”来实现。

三层里任何一层失败，都应该把结构化的失败原因回传给模型，让它有机会修正参数重试一次。注意是回传结构化的原因，不是回传一句“参数错误”。前者模型能改，后者它只能瞎猜。

4. 多域任务工作流：拆成可回滚的状态机

“多域”这个词听着玄，落到工程上就是一件事：一个任务需要跨多个系统、多种能力组合完成，中间任何一步都可能失败。这类任务的正确抽象是带检查点的状态机，不是一条 while 循环。

我见过的最常见误区是把 Agent 的主循环写成“想一步、做一步、再想一步”，靠上下文记住进度。这种写法在三四步的任务里勉强能用，到七八步必然出问题：上下文超了、某一步失败之后不知道该回退到哪、并发跑两个任务互相污染。海鸥3.0 的做法是先规划后执行，把任务拆成 DAG，再按拓扑序执行节点，每个节点完成就落一个检查点。

4.1 节点类型与编排规则

节点分四类，这个分类决定了很多细节：

编排上有两条硬规则。第一条：只读节点可并发，写节点必须串行。理由是写操作的顺序不可交换，并发之后结果不确定，回滚也做不了。第二条：确认节点之后必须重新校验权限，因为挂起可能挂几个小时，期间权限可能已经变更。

判定节点的分支必须是有限枚举这一点，听起来是废话，但我见过有人让判定节点输出自由文本然后下游去正则匹配，这就是给自己挖坑。让模型输出一个枚举值，哪怕只有三个选项，稳定性都比自由文本高一个数量级。

4.2 上下文预算：不太被讨论但非常关键的问题

多步任务的上下文管理有个反直觉的结论：不是上下文越长越好，而是越“干净”越好。第 8 步的时候，第 1 步的原始工具返回（可能是一坨 JSON）还留在窗口里，除了占位置没有任何价值，而且会干扰模型判断。

我的做法是给每个节点定义“输出摘要规格”，工具节点的原始返回只保留在外部存储里，进入上下文的只有摘要加一个引用 ID。摘要规格按类型定：

这套做法的一个副作用是：模型有时候需要拿原始数据做二次计算，但它手里只有摘要。解决办法是在技能层提供一个fetch_by_ref的技能，让它能按引用 ID 取回原始数据，但取回的数据不进上下文的主体区，而是作为一个“临时块”放在最末尾，用完即弃。这个细节看着小，实测能把长任务的上下文超限率从 30% 降到 5% 以内。

再说一个 token 预算的经验值。一个八到十步的任务，我的分配大致是：人格层与约束层固定占 800-1000 token，技能描述按候选集动态加载控制在 1500 以内，历史步骤摘要每步 150 字左右，当前步骤的输入最多 2000。加起来留出四分之一的余量给模型输出。如果你的系统经常撞到窗口上限，多半是历史步骤的原始输出没做压缩，而不是窗口太小。

4.3 幂等、重试与断点续跑

幂等这件事在 Agent 场景里比在普通服务里更重要，因为 Agent 会“自作主张”重试。给每个写操作生成一个request_id，在服务端做结果缓存，同一个request_id重复请求直接返回上次结果，不做第二次执行。这个幂等键由工作流引擎生成，不能让模型生成——模型可能会在重试时生成一个新的。

重试策略我定的是：同一节点同一参数最多重试一次，且只对可重试错误重试。可重试的错误包括超时、限流、5xx；不可重试的包括参数错、权限错、4xx。让模型自己判断“要不要重试”是危险的，它会倾向于一直试。

断点续跑的价值在长任务上体现得最明显。假设一个任务跑到第 7 步失败，前面 6 步的结果都落库了，用户重新发起时是从头跑还是从第 7 步续？我从第 7 步续。实现上就是每个节点完成后写一条checkpoint记录，包含节点 ID、输入哈希、输出引用、时间戳。重新发起时，引擎先算输入哈希，命中的检查点直接跳过。这个机制让长任务的用户重试成本从“重跑十分钟”降到“几秒钟”。

5. 权限分层与审计：让“多域”不至于失控

能力越多，失控的爆炸半径越大。这一节其实是整个系统里我最坚持要做的部分，也是很多团队最容易砍掉的部分——因为它在演示里看不出来，只在出事后才体现价值。

核心原则一句话：能靠代码和权限系统解决的，绝不靠提示词。

5.1 能力白名单与最小权限

技能注册表里的每个技能都带permission_scope，用户账号带一组权限域，取交集之后得到这个会话的“可用技能集”。这个交集在会话开始时就固定下来，后续所有路由都只在可用技能集里进行——不可用的技能根本不出现在候选里，而不是先让模型选了再拒绝。这个先后顺序很重要：先选再拒，会在上下文里留下“有个技能被拒绝了”的痕迹，模型会尝试用别的方式达成目的，反而更危险。

再往上还有一层是操作确认闸门。我把写类、删类、发送类操作分成三档：

“展示影响范围与样本”这个设计解决了一个很实际的问题：用户看到“将删除 327 条记录，样本如下：……”的时候，往往能立刻意识到自己说错了。纯文字确认“确定要删除吗”是无效的，用户会条件反射点确定。

5.2 审计字段与回放能力

审计日志我要求记录这些字段，缺一不可：会话 ID、用户标识、任务 ID、节点 ID、技能名、脱敏后的入参、返回状态码、耗时、模型版本、提示词版本。其中提示词版本这个字段经常被忽略，但它是排查“为什么昨天好好的今天变差了”的唯一依据。

回放能力是审计的自然延伸。给定一个任务 ID，能把这个任务的完整执行链路重放出来：每一步输入什么、模型输出什么、工具返回什么、判定走了哪个分支。实现上就是把每步的上下文快照存一份，体积不小，所以只保留 30 天，且只存摘要，需要详细信息时按引用 ID 去冷存储捞。

我做这块的动机很实在：有一次线上的路由表现突然变差，查了半天发现是有人改了一个技能的 description，把“查询订单”改成了“获取订单信息”，语义没变但关键词丢了。没有提示词版本记录和回放，这种问题能查一整天。

6. 排查实录：六类高频故障的现象、成因与处置

这一段是我把过去半年踩的坑整理成的速查表，按出现频率排序。每一条都能对应到前面某一层的设计缺陷。

6.1 那个让我改了整个路由逻辑的故障

说一个具体的。有一次用户问“帮我看下华东区最近的告警情况”，Agent 调了订单查询技能，返回空结果，然后它很自然地说“华东区最近没有告警”。这个回答错得非常隐蔽——工具调错了，但它给出的是一个看起来合理的结论，用户很可能就信了。

排查下来是三个问题叠加。第一，技能描述里订单查询写了“支持按区域筛选”，告警查询也写了“支持按区域筛选”，两个描述在向量空间里几乎重合。第二，向量召回返回的 top-5 里两个都在，模型选了排在前面的那个。第三，也是最要命的一条，工具返回空结果时，模型没有区分“没有数据”和“调错了工具”，直接按前者解释。

修复做了三件事。给两个技能都加上了when_not_to_use，明确写出对方擅长的场景；把“工具返回空结果时必须确认是否选错技能”写进约束层；给所有查询类技能的空结果统一约定返回结构，包含一个skill_used字段，让模型有机会复核。改完之后这类问题基本消失。

这件事让我意识到了一个更普遍的道理：Agent 的错误很少是单点错误，通常是路由、约束、契约三层同时存在漏洞。所以修的时候不要只修一处，要顺着链路往上找。

6.2 几个不太上台面的小技巧

第一个，给模型看的技能描述里加“典型用户说法”比加“功能说明”有用。写三段功能说明，不如写三句用户真的会说的话。

第二个，判定节点的分支枚举值不要用英文，用中文短句，模型的稳定性更好，而且日志更可读。

第三个，人格卡里的规则尽量用“必须/禁止”这类硬词，少用“尽量/建议”。后者在长上下文里会被当成软约束忽略。

第四个，如果把技能描述改成了否定句，一定要测；模型的否定理解不总是可靠的，有时候“不要用于查询告警”反而会让它更倾向于选这个技能。否定句要跑回归测试才敢上线。

第五个，任何你希望模型“稳定做到”的事，都准备一个代码层的兜底。提示词是提高概率的，代码是保证下限的。两者不冲突，缺一个都会在某个时刻还债。

7. 我踩过的坑与几条实操体会

先说一个我到现在都觉得有点吃亏的教训：不要过早追求人格的“拟人化”。早期我给这个 Agent 写了一份相当细致的人格，有说话习惯、有情绪基调、有主动关怀的设定。结果是它在执行失败的时候会安慰用户，“抱歉没能帮上忙，不过你可以试试……”，这种表述看起来友好，实际掩盖了错误信息，用户根本不知道是哪一步挂了。后来我把人格卡里的关怀部分全部删掉，换成“失败时明确说明停在哪一步、缺什么信息”，可用性立刻上了一个台阶。内部工具的 Agent，专业感来自确定性，而不是温度。

第二个体会是关于提示词迭代的节奏。我的做法是任何提示词改动都必须过一遍固定测试集，测试集分三块：正常用例、边界用例、恶意用例。正常用例看能力，边界用例看稳定性，恶意用例看约束层是否守得住。这三块的比例大概是 5:3:2。恶意用例不是去研究怎么攻击别人，而是拿自己系统做健壮性自测——比如故意输入矛盾指令、故意输入超长输入、故意让工具返回异常结构，看系统会不会崩或者做出危险动作。这套自测跑下来，抓出的问题比任何一次人工 review 都多。

第三个体会，关于“多域”这件事的真实难点。很多人以为多域的难点是技术栈多，其实不是。真正的难点是术语在不同域里的含义不一样。举个例子，“区域”在这个系统里有三种含义：订单域指的是销售大区，告警域指的是机房片区，权限域指的是数据可见范围。模型不知道这些，它会混用。解决办法是在技能层为每个域维护一份术语映射表，作为该技能的附加上下文一起加载。这个东西维护起来很烦，但它是多域 Agent 能不能用的分水岭。

最后分享一个我们内部一直在用的自检清单，五项，每次上线前过一遍：

1. 每个技能的when_not_to_use是否写了至少一条？
2. 所有写操作是否都有确认闸门，且闸门里展示了影响范围？
3. 长任务的历史步骤是否做了摘要压缩，是否留有引用 ID？
4. 提示词版本号是否写进了审计日志？
5. 失败路径是否执行过，而不只是测了成功路径？

这五项里，第五项最容易漏，也最容易出事。成功路径的测试是开发的本能，失败路径的测试得靠纪律。我现在形成了一个习惯：新技能上线前，故意把它的接口调成超时、返回空、返回异常结构，各跑一遍，看 Agent 的反应。这个习惯帮我拦下过至少两次会直接写坏数据的发布。

说到这儿差不多了。这套东西没有终点，技能在加、域在扩、模型在换，能保证的只有一件事：分层要清楚，指标要能测，出事要能查。做到这三条，Agent 就不会变成一个你不敢动的黑盒。