一、权限最小化:两道白名单
第一道:任务工具白名单(编排层)。 主智能体(编排者)通过 permission 声明:Task 工具默认拒绝一切派发,只放行 10 个具名子智能体(planner、deep-worker、oracle、reviewer、consultant、ui-builder、explore、librarian、light-orchestrator、vision)。效果有三:
- 路由闭环:所有路由决策收敛到一张显式路由表,不存在"即兴派发";
- 防幻觉派发:模型无法临时发明一个不存在的子智能体;
- 边界即文档:谁允许被派发、谁不允许,配置本身就是权威文档。
第二道:技能白名单(每个子智能体)。 每个 agent 独立声明自己只能加载哪些技能,其余一律拒绝。例如:实现者(deep-worker)只加载 remove-deadcode、git-release、resolving-merge-conflicts 等执行类技能;审查者(reviewer)只加载 code-review、security-review;探索者(explore)只加载 codemap;分析师(oracle)只加载 reflect、simplify。
动机很关键:在不少框架里,加载一个技能隐含"自我实现授权"------读到了实现指南就等于拿到了动手许可。白名单把"能读什么技能"与"能做什么事"彻底解耦,同时明确了一条纪律:加载技能不等于授权自我实现,多文件改动仍然必须走 planner → 实现者的路径。
二、模型分层与成本核算
flash / pro 分层。 flash 负责路由、搜索、查找、规划、常规实现;pro 负责深度推理、根因分析、代码审查、重型多文件实现。边界模糊时先走 flash,不行再升级。对应的推理开关:flash 温度 0、厂商侧 thinking: disabled(官方认证的省成本手段);pro 保持思考开启------注意思考是模型级别的开关,不是 agent 前端配置项,温度等参数在 pro 上会被静默忽略。
按模型声明成本元数据。 为每个模型显式配置 input / output / cache_read / cache_write 单价。这里踩过一个实坑:DeepSeek 的缓存写入没有单独公布的价目,实际按缓存未命中时的 input 价计费。所以配置里缓存写直接记账为未命中输入价,避免成本被系统性低估。
提示词缓存字节稳定性纪律。 缓存命中省钱的前提是前缀稳定,于是立了几条硬规则:
- agent 提示词、全局规则、规则顺序保持字节级一致,早期重排一次 = 全额重付输入成本;
- 易变内容(时间戳、随机 ID、动态文件列表)一律追加在载荷末尾,绝不进头部;
- 标题、摘要、压缩这类单次任务走 flash,让易变内容永远不污染 pro 的前缀缓存。
三、OpenAI 兼容网关的适配层
DeepSeek 的 OpenAI 兼容网关与官方 API 有两个不兼容点,直接使用会静默出错:
- 不支持
role: "developer"的系统提示,必须回退为role: "system"; - 不支持
max_completion_tokens输出上限,必须回退为max_tokens。
做法是在 provider 配置里声明一个 compat 块(supportsDeveloperRole: false、maxTokensField: "max_tokens"),让框架自动完成字段回退。经验:对接任何"兼容 OpenAI"的网关,与其靠运行时试错,不如把已知差异显式写进配置,作为一等公民的适配声明。
四、上下文管理:从百分比到绝对值
阈值必须与模型能力解耦。 上下文自动压缩的触发阈值最初用百分比(60% / 30%)。当模型上下文窗口从 128K 跳到 1M 后,百分比阈值折算下来高达 600K / 300K,常规会话(20K--200K)永远触发不了压缩,机制形同虚设。修复是改成绝对 token 值(77K / 38K),与窗口大小彻底解耦。教训一句话:凡是依赖模型能力的阈值,一律用绝对值,不要用与模型能力挂钩的比例。
空结果回退(P0 级规则)。 子智能体返回空结果且工作区无任何变化 → 缩小任务范围重试一次 → 仍失败就停下,明确报告子智能体基础设施故障。绝不把重型实现内联回编排层自己干------那会把顶层上下文烧穿。
循环检测。 连续 3 次以上相同工具调用且零进展 = 空转。立即停下,换策略或升级,绝不重复调用烧 token。这一条被写进了全局反模式清单,和"禁止空 catch"、"禁止注释掉的代码"并列。
五、配置的工程化交付
插件版本锁定。 插件从 @latest 改为精确版本号/提交锁定,并关闭自动更新。理由:AI 配置高度依赖提示词内容,插件的一次"小升级"可能改变整个 agent 的行为。可复现的构建,优先于永远最新。
同步脚本 + 过期文件对账。 写了一个 PowerShell 脚本把仓库配置同步到全局配置目录。值得记录的三个设计点:
- 独立副本而非符号链接:仓库切换不会影响全局运行中的配置;
- 过期文件对账 :目标目录里"仓库已不再管理"的文件要主动删除,判断依据是
git ls-files与git log --diff-filter=D的并集------当前受管文件 ∪ 历史上被删除的文件,之外的一律不动; - 对账范围限定 :只在 skills / agents / commands 三个目录内对账,用户在全局目录自建的文件永远不会被误删;并支持
-WhatIf干跑预览。
六、知识的持久化与技能治理
/learn:把隐性经验沉淀为目录级规则。 新增一条命令,把会话中非显而易见的经验提炼成 1--3 行洞察,写入目录级 AGENTS.md(root、packages/foo/、src/auth/ 各有各的)。目录级意味着规则只在相关上下文生效,避免全局规则无限膨胀。这是对"经验要沉淀、但不要污染全局"的平衡解。
技能做减法,并且新技能必须"接线"。 技能库从 24 个精简到 20 个:删掉 6 个低使用率技能,新增 2 个面向 GitHub 工作流的(to-tickets:把规格拆成可跟踪的 issue;triage:基于标签的 issue 分流)。删与增背后还有一条治理规则:技能存在但没有被任何 agent 白名单引用 = 死配置,要么接线,要么删除。
结语
这轮演进的技术含量不在任何单一改动里,而在整体的方向:把人的纪律编码成机器的约束。权限白名单防止越权,字节稳定前缀保住缓存命中,绝对阈值防止机制失效,空结果回退防止静默降级,过期文件对账保证交付干净。它们都不炫技,但恰恰是这些东西决定了一套多智能体配置能否长期可维护、成本可控、行为可复现。如果你的多智能体配置已经开始遇到"改不动、说不清、对不准"的问题,可以从这六条里挑一条最小的先做起来。