1. 先去看这个词一个 Agent 指令系统到底由哪几层构成“Codex-X 内置「海鸥3.0破甲」Agent”这个标题外行看是营销词堆叠内行看一眼就知道它描述的是一个指令分层 技能调度 多步任务编排的复合体。先把话说在前面我这里讲的“破甲”指的是让 Agent 穿透系统之间的壁垒、打通跨领域的能力边界、把一条长链路任务从“只能聊”推到“能真正落地”而不是去绕过任何平台的安全限制——后者既不在本文的讨论范围也不是一个正经工程团队该花时间的方向。真正值得投入的是怎么把一个 Agent 的指令系统设计得可测、可控、可回滚。这个内容适合三类人看。第一类是正在把大模型能力接进业务系统的后端或平台工程师你手里大概已经有一堆工具接口但发现模型调用的准确率始终卡在七八成上不去第二类是做 Agent 产品的人你需要一套能说服自己的指令分层规范而不是每次出问题就往 system prompt 里再加一句话第三类是技术负责人你要判断一个“多域任务工作流”到底是真架构还是套壳这篇里的分层模型和排查表可以直接拿去当评审清单。Codex-X 这类系统解决的核心痛点其实很朴素当可调用的技能从 3 个涨到 30 个从单轮问答涨到十几步的跨系统任务时原来的“把所有说明塞进一段提示词”的做法会全面崩溃。崩溃的表现有三种人格漂移同一个 Agent 上午像个严谨的审计员下午像个话痨客服、路由错配用户问 A它调了 B 的工具参数还对不上、上下文雪崩第三步就把第一步的关键信息挤出了窗口。海鸥3.0 这类内部代号背后真正要解决的问题就是这三件事。我把它拆成四层来看这个分层是我试过几种方案之后固定下来的后面所有内容都挂在这个骨架上层级职责变更频率谁来维护人格层决定 Agent 是谁、语气如何、主动性多高低月级产品 提示词工程师约束层决定什么不能做、什么必须确认中周级安全/风控 平台技能层决定有哪些能力、什么条件下调用高天级业务开发契约层决定输出长什么样、如何被下游消费中前后端 数据分层最实际的好处不是“优雅”而是可归因。线上出问题时你能在三十秒内定位到底是人格漂移、路由错配还是契约破坏而不是对着一段两千字的 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 技能注册表该有哪些字段这是整个路由的基础字段设计得好后面的路由逻辑会简单很多。我用的字段集如下字段作用备注name技能唯一标识用动词_名词格式如 query_order_by_regiondescription给模型看的自然语言描述最关键字段写不好路由必错when_to_use什么场景该用比 description 更重要单独拆出来when_not_to_use什么场景不该用反向约束能干掉大量误触发params_schema参数 JSON Schema必填/可选/枚举值要写全side_effectread / write / delete / send决定是否需要确认闸门cost预估耗时与配额消耗用于排序与并发控制permission_scope所需权限域与账号权限做交集校验examples2-3 条正例 1 条反例few-shot 用性价比极高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 个错误候选里硬选一个。置信度阈值我用了三档置信区间处理方式理由 0.85直接执行高置信度下追问反而伤体验0.60 - 0.85追问澄清给出 2 个候选这个区间错判率最高必须拦 0.60走通用对话说明自己能力边界硬调用的错误成本远高于不调这套阈值不是拍脑袋定的是拿 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。摘要规格按类型定数据类型进入上下文的形态原始数据位置列表查询总数 前 3 条关键字段 引用 ID外部 KV按引用 ID 取详情查询全字段通常不大上下文直接保留长文本前 200 字 引用 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用户账号带一组权限域取交集之后得到这个会话的“可用技能集”。这个交集在会话开始时就固定下来后续所有路由都只在可用技能集里进行——不可用的技能根本不出现在候选里而不是先让模型选了再拒绝。这个先后顺序很重要先选再拒会在上下文里留下“有个技能被拒绝了”的痕迹模型会尝试用别的方式达成目的反而更危险。再往上还有一层是操作确认闸门。我把写类、删类、发送类操作分成三档档位触发条件确认方式普通写影响单条记录Agent 自述操作内容后直接执行留审计批量写影响 10 条以上必须展示影响范围与样本等待确认不可逆删除、对外发送、状态流转双人确认且不可批量“展示影响范围与样本”这个设计解决了一个很实际的问题用户看到“将删除 327 条记录样本如下……”的时候往往能立刻意识到自己说错了。纯文字确认“确定要删除吗”是无效的用户会条件反射点确定。5.2 审计字段与回放能力审计日志我要求记录这些字段缺一不可会话 ID、用户标识、任务 ID、节点 ID、技能名、脱敏后的入参、返回状态码、耗时、模型版本、提示词版本。其中提示词版本这个字段经常被忽略但它是排查“为什么昨天好好的今天变差了”的唯一依据。回放能力是审计的自然延伸。给定一个任务 ID能把这个任务的完整执行链路重放出来每一步输入什么、模型输出什么、工具返回什么、判定走了哪个分支。实现上就是把每步的上下文快照存一份体积不小所以只保留 30 天且只存摘要需要详细信息时按引用 ID 去冷存储捞。我做这块的动机很实在有一次线上的路由表现突然变差查了半天发现是有人改了一个技能的 description把“查询订单”改成了“获取订单信息”语义没变但关键词丢了。没有提示词版本记录和回放这种问题能查一整天。6. 排查实录六类高频故障的现象、成因与处置这一段是我把过去半年踩的坑整理成的速查表按出现频率排序。每一条都能对应到前面某一层的设计缺陷。现象大概率成因定位方式处置反复调用同一工具结果一样失败后未终止模型误以为会变看审计里的重复调用人格层加“同参数最多重试一次”技能选对、参数错一个字段参数描述语义模糊对比失败入参与 schema补 description 里的单位与格式长任务到第五六步开始胡说上下文污染或超限看每步的 token 占用曲线历史步骤改摘要 引用 ID同样的话术早上对下午错人格漂移或提示词被改比对提示词版本人格层收敛 版本管理该追问的时候直接执行了主动性档位缺失或被稀释看人格层是否声明档位把确认规则放进约束层输出结构下游解析失败契约层没做 schema 强约束用 JSON Schema 跑校验强制结构化输出 校验重试6.1 那个让我改了整个路由逻辑的故障说一个具体的。有一次用户问“帮我看下华东区最近的告警情况”Agent 调了订单查询技能返回空结果然后它很自然地说“华东区最近没有告警”。这个回答错得非常隐蔽——工具调错了但它给出的是一个看起来合理的结论用户很可能就信了。排查下来是三个问题叠加。第一技能描述里订单查询写了“支持按区域筛选”告警查询也写了“支持按区域筛选”两个描述在向量空间里几乎重合。第二向量召回返回的 top-5 里两个都在模型选了排在前面的那个。第三也是最要命的一条工具返回空结果时模型没有区分“没有数据”和“调错了工具”直接按前者解释。修复做了三件事。给两个技能都加上了when_not_to_use明确写出对方擅长的场景把“工具返回空结果时必须确认是否选错技能”写进约束层给所有查询类技能的空结果统一约定返回结构包含一个skill_used字段让模型有机会复核。改完之后这类问题基本消失。这件事让我意识到了一个更普遍的道理Agent 的错误很少是单点错误通常是路由、约束、契约三层同时存在漏洞。所以修的时候不要只修一处要顺着链路往上找。6.2 几个不太上台面的小技巧第一个给模型看的技能描述里加“典型用户说法”比加“功能说明”有用。写三段功能说明不如写三句用户真的会说的话。第二个判定节点的分支枚举值不要用英文用中文短句模型的稳定性更好而且日志更可读。第三个人格卡里的规则尽量用“必须/禁止”这类硬词少用“尽量/建议”。后者在长上下文里会被当成软约束忽略。第四个如果把技能描述改成了否定句一定要测模型的否定理解不总是可靠的有时候“不要用于查询告警”反而会让它更倾向于选这个技能。否定句要跑回归测试才敢上线。第五个任何你希望模型“稳定做到”的事都准备一个代码层的兜底。提示词是提高概率的代码是保证下限的。两者不冲突缺一个都会在某个时刻还债。7. 我踩过的坑与几条实操体会先说一个我到现在都觉得有点吃亏的教训不要过早追求人格的“拟人化”。早期我给这个 Agent 写了一份相当细致的人格有说话习惯、有情绪基调、有主动关怀的设定。结果是它在执行失败的时候会安慰用户“抱歉没能帮上忙不过你可以试试……”这种表述看起来友好实际掩盖了错误信息用户根本不知道是哪一步挂了。后来我把人格卡里的关怀部分全部删掉换成“失败时明确说明停在哪一步、缺什么信息”可用性立刻上了一个台阶。内部工具的 Agent专业感来自确定性而不是温度。第二个体会是关于提示词迭代的节奏。我的做法是任何提示词改动都必须过一遍固定测试集测试集分三块正常用例、边界用例、恶意用例。正常用例看能力边界用例看稳定性恶意用例看约束层是否守得住。这三块的比例大概是 5:3:2。恶意用例不是去研究怎么攻击别人而是拿自己系统做健壮性自测——比如故意输入矛盾指令、故意输入超长输入、故意让工具返回异常结构看系统会不会崩或者做出危险动作。这套自测跑下来抓出的问题比任何一次人工 review 都多。第三个体会关于“多域”这件事的真实难点。很多人以为多域的难点是技术栈多其实不是。真正的难点是术语在不同域里的含义不一样。举个例子“区域”在这个系统里有三种含义订单域指的是销售大区告警域指的是机房片区权限域指的是数据可见范围。模型不知道这些它会混用。解决办法是在技能层为每个域维护一份术语映射表作为该技能的附加上下文一起加载。这个东西维护起来很烦但它是多域 Agent 能不能用的分水岭。最后分享一个我们内部一直在用的自检清单五项每次上线前过一遍每个技能的when_not_to_use是否写了至少一条所有写操作是否都有确认闸门且闸门里展示了影响范围长任务的历史步骤是否做了摘要压缩是否留有引用 ID提示词版本号是否写进了审计日志失败路径是否执行过而不只是测了成功路径这五项里第五项最容易漏也最容易出事。成功路径的测试是开发的本能失败路径的测试得靠纪律。我现在形成了一个习惯新技能上线前故意把它的接口调成超时、返回空、返回异常结构各跑一遍看 Agent 的反应。这个习惯帮我拦下过至少两次会直接写坏数据的发布。说到这儿差不多了。这套东西没有终点技能在加、域在扩、模型在换能保证的只有一件事分层要清楚指标要能测出事要能查。做到这三条Agent 就不会变成一个你不敢动的黑盒。