当你进入多 Agent 阶段后，很快会遇到第二类复杂度：
- 团队里有几十个工具、上百个 action，没人知道哪些还能用；
- 新 Agent 上线后，老 Agent 还在调过期接口；
- 一次能力升级影响多个工作流，事故半径不可控；
- “这个调用为什么被拒绝”无法快速解释。
这不是模型问题，而是能力治理缺位。
本章要解决的是：把 Agent 生态从“散养能力集合”升级为“可治理的能力平台”。
学习目标
完成本章后，你将能够：
- 设计能力注册中心（Capability Registry）核心模型。
- 为每项能力建立版本、权限、配额、SLO 与兼容策略。
- 用灰度发布与回滚机制降低能力升级风险。
- 通过治理流水线把“开发便利性”与“生产可控性”同时保住。
一、先定义“能力”是什么
在治理语境里，能力不是“一个函数”，而是：
- 可被 Agent 调用的业务动作；
- 有明确输入输出契约；
- 有权限边界与成本画像；
- 有可观测指标与生命周期。
1.1 能力元数据最小集合
capability_id: cap.order.issue.resolve
name: ResolveOrderIssue
owner_team: commerce-risk
version: 2.1.0
status: active
input_schema_ref: schema://order/resolve/v2
output_schema_ref: schema://order/resolve-result/v2
required_permissions:
- order:read
- ticket:create
risk_level: medium
slo:
p95_latency_ms: 1800
success_rate: 0.985
cost_budget:
daily_usd: 120这份元数据是后续权限、路由、评测、灰度、审计的统一基座。
二、注册中心不是“文档中心”，是“控制平面”
很多团队把能力目录做成 wiki，结果还是失控。注册中心必须具备“控制能力”：
- 注册：能力必须登记后才能被调用。
- 校验：调用前检查 schema、权限、版本策略。
- 路由：按策略决定调稳定版、灰度版还是降级版。
- 观测：按 capability_id 汇总成功率、时延、成本。
- 熔断：异常时可一键下线能力。
没有控制平面，目录再全也只是“说明书”。
三、版本策略：让升级可预测
能力升级不可避免，关键是让调用方知道“会发生什么”。
3.1 语义化版本建议
MAJOR：不兼容变更（字段删除、语义变化）。MINOR：向后兼容新增（新增可选字段）。PATCH：内部修复，不改契约。
3.2 兼容窗口策略
compatibility_policy:
cap.order.issue.resolve:
supported_majors: [1, 2]
default_version: 2.1.0
deprecate_schedule:
- version: 1.x
sunset_at: 2025-12-31注册中心应在调用阶段就给出“即将下线告警”，而不是事故当天才发现。
四、权限治理：能力访问必须是“最小授权”
Agent 越多，越不能用粗粒度权限。
4.1 双层授权模型
- Agent 身份权限：这个 Agent 能否访问某类能力。
- 任务上下文权限：在当前任务里是否允许执行该动作。
{
"agentId": "review-agent",
"capabilityId": "cap.order.issue.resolve",
"granted": false,
"reason": "missing_scope: ticket:create"
}拒绝结果必须结构化，便于自动补救与人工审计。
五、配额与成本：把“可用”变成“可持续”
如果不把能力成本纳入治理，系统会在增长中失稳。
5.1 配额维度建议
- 按团队配额：防止单团队挤占资源。
- 按能力配额：高成本能力有独立预算。
- 按优先级配额：核心链路与离线任务分池。
5.2 成本守护策略
- 达到 80% 预算：预警。
- 达到 100% 预算：自动切低成本路由。
- 达到 120% 预算：仅保留核心工作流，非核心降级。
“预算感知路由”比“月底算账”有效得多。
六、灰度发布：能力升级不再“全量豪赌”
6.1 灰度维度
- 按工作流灰度（先非核心流程）
- 按租户灰度（先内测租户）
- 按流量灰度（5% -> 20% -> 50% -> 100%）
6.2 自动回滚触发
rollback_rule:
capability_id: cap.order.issue.resolve
trigger:
- metric: success_rate
threshold: "< 0.95"
window: "15m"
- metric: policy_violation_rate
threshold: "> 0.02"
window: "10m"
action: rollback_to_previous_stable灰度不是“慢慢放量”，而是“有条件放量 + 可自动收敛”。
七、注册中心接口设计（Foundation 可复用）
7.1 C# 接口示例
public sealed class CapabilityDescriptor
{
public string CapabilityId { get; init; } = string.Empty;
public string Version { get; init; } = string.Empty;
public string OwnerTeam { get; init; } = string.Empty;
public string RiskLevel { get; init; } = "low";
public string Status { get; init; } = "active";
}
public interface ICapabilityRegistry
{
CapabilityDescriptor Get(string capabilityId, string? version = null);
IReadOnlyList<CapabilityDescriptor> ListByAgent(string agentId);
bool IsAllowed(string agentId, string capabilityId, string taskRunId);
}
public interface ICapabilityReleaseManager
{
void StartCanary(string capabilityId, string targetVersion, int trafficPercent);
void Promote(string capabilityId, string targetVersion);
void Rollback(string capabilityId, string fallbackVersion);
}这组接口让能力发现、授权校验、发布治理形成闭环。
八、治理流水线：把规则前置到 CI/CD
每次新增或升级能力时，流水线至少执行：
- Schema Diff 校验（兼容性检查）。
- 权限策略校验（是否最小授权）。
- 评测集回归（业务准确率与策略违规率）。
- 成本模拟（预估 token/调用费用）。
- 灰度计划校验（回滚条件是否完整）。
不通过任一项，禁止发布。
九、运维视角：你需要三个看板
9.1 能力健康看板
- 按 capability_id 展示成功率/时延/错误类型。
9.2 治理风险看板
- 过期版本调用数、越权尝试数、策略冲突数。
9.3 成本与收益看板
- 每个能力的成本、调用量、业务价值贡献。
没有收益视角，治理容易走向“一刀切限流”，伤害业务。
常见坑
1) 只注册，不管生命周期
能力一旦上线就没人维护，最终目录与现实脱节。
2) 版本号存在，但路由不按版本走
表面版本化，实则调用混乱。
3) 权限只看 Agent，不看任务上下文
同一个 Agent 在不同任务中的权限应不同，否则越权风险高。
4) 灰度无回滚阈值
出了问题还要人工讨论，错过最佳止损窗口。
下一章我们将进入《评测即发布门禁：把质量规则写进交付流水线》，把“测完再说”升级为“不过门禁就不上线”。