#企业智能体工程体系v1.1 企业智能体工程卷 · 第1期技能即契约——把能力做成可检查的声明作者技术治理研究组系列企业智能体工程卷发布版 v1.1主案例CASE-CR-0042信用提额申请本集对象SkillContract · AuditEvent核心协议P2 契约 vs 权限适合读者架构师、技术负责人、AI 产品经理、企业级 Agent 开发者 本文档声明性质本文为企业智能体工程化设计参考框架的第 1 期聚焦 Agent 能力边界的契约化设计提供架构思路与教学级示意代码不构成生产级实现方案或法律合规意见。证据锚定文中案例CASE-CR-0042为教学示意不对应任何真实客户系统。系列定位本篇在第 0 期企业公民 · 身份与审计基础上引入 SkillContract 对象与 P2 协议后续各期将进一步叠加 DecisionRecord、ToolSpec、MemoryItem 等对象。摘要在第 0 期中我们建立了 Agent 的身份Identity与审计AuditEvent基础——明确了“谁在行动”和“留下了什么痕迹”。但仅有身份和审计还远远不够我们仍然不知道 Agent“凭什么”能做某件事。本期回答一个核心问题如何让 Agent 的能力边界从“提示词里的口头约束”变成“调用前可检查的硬契约”CASE-CR-0042 中客服“口头禁止”改额度、数据 Agent“理论上”不该缓存证件号——这些边界靠自觉不靠系统。本期引入SkillContract技能契约对象将每个 Agent 的能力、副作用、前置授权、信任等级声明为可编程检查的结构化契约并通过P2 协议解决契约与权限系统的冲突裁决问题。一句话核心契约不是写在提示词里的“客气话”是挂在调用路径上的“硬约束”。1. 问题为什么“口头禁止”永远拦不住1.1 CASE-CR-0042 的真实困境在 CASE-CR-0042 的链路中三个角色有不同的能力边界角色“应该”能做的事“不应该”能做的事客服support.intake建单、澄清信息、转交工单不能改额度数据data.credit只读查询信用快照不能裁决额度不能写业务系统财务finance.limit提额裁决不能绕过四轴直接通过但在传统的 Agent 实现中这些边界靠什么保障保障方式可靠性问题提示词约束❌ 极低“你是一个客服不能改额度”——越狱/注入可绕过代码注释❌ 极低没人读注释维护者可能不知道口头约定❌ 极低新人不知道赶进度时“顺手”就破了API 权限仅靠 IAM⚠️ 中等只能管“能不能调”管不了“调了干什么”结论无契约技能 边界靠自觉。企业公民不靠自觉。1.2 生产事故的常见前奏“顺手”模式 客服看到额度字段 → “顺手”改了一下 → 测试没发现 → 上线后出了事故 事后复盘 “我以为只有财务才能调用……不对啊为什么客服的 Agent 有这个权限”P2 协议要解决的核心问题契约与权限两张皮是生产事故的标配前奏。2. SkillContract能力即对象2.1 什么是 SkillContractSkillContract ├── skill_id # 唯一标识如 limit.decide ├── role # 允许执行的角色 ├── capabilities # 具体能做什么只读/可写/可裁决 ├── preconditions # 调用前需要哪些授权grants ├── side_effects # 允许的副作用集合如 limit.write ├── trust_required # 信任等级0 low / 1 mid / 2 high └── evidence_ref # 设计/测试依据的追溯编号核心理念技能不是松散的自然语言描述而是调用前可 assert 的结构化对象。2.2 为什么这比提示词可靠维度提示词约束SkillContract可检查❌ 运行时无法自动验证✅ 调用前断言检查可审计❌ 自然语言无结构化痕迹✅ 每次检查都有审计事件可测试❌ 无法单元测试✅ 契约即测试规格可追溯❌ 改提示词不留痕✅ Git 变更可追溯可组合❌ 难以叠加✅ 可组合多个契约3. CASE-CR-0042 的三项契约以下将三个角色的能力声明为结构化的 SkillContractskill_idrolecapabilityside_effectstrustpreconditionscase.acceptsupport.intake建单、澄清、转交无写额度1case:writecredit.snapshotdata.credit读信用快照无写1credit:readlimit.decidefinance.limit提额裁决limit.write2limit:write关键观察客服没有limit.decide契约——不是“提示词里不许”而是“对象里没有”财务的limit.decide显式声明了副作用limit.write——调用前系统会检查信任等级 2高信任对应了财务裁决的高风险操作4. 协议 P2契约 vs 权限——以更严者为准4.1 两张皮的问题运行时同时存在两套控制体系控制体系来源管什么契约SkillContract设计阶段声明能力边界、副作用、信任等级权限Grants身份系统授予具体资源/操作的访问权限问题两者可能不一致。不一致场景后果契约说只读权限给了写Agent 可能“越权”执行未声明操作权限不足契约允许Agent 无法完成本职工作两者冲突且都有效系统陷入不确定性4.2 P2 裁决规则P2 裁决契约 vs 权限 1. 以更严者为准契约和权限的交集决定实际能力 2. 若契约说只读、权限却给了写 → 拒绝调用记缺陷「权限过宽」 3. 若权限不足、契约允许 → 拒绝调用记「授权不足」 4. 禁止“先执行、后补授权/补契约” 5. 上线前须证明契约与权限矩阵一致联动第8期 Assurance4.3 P2 在 CASE-CR-0042 中的应用场景契约权限P2 裁决客服受理工单case.accept允许有case:write✅ 允许客服“顺手”改额度无limit.decide有limit:write❌ 拒绝契约不存在数据拉信报credit.snapshot只读有limit:write过宽❌ 拒绝P2权限宽于契约财务裁决提额limit.decide需limit:write有limit:write✅ 允许需配合四轴见第2期5. 契约生命周期定义 → 授信assign trust → 注册register to skill registry → 调用前检查P2 → 审计AuditEvent 记录 → 有证据演化基于反馈更新6. 最小代码三项契约 P2 实现以下为教学级示意代码展示 SkillContract 的定义与 P2 裁决逻辑from__future__importannotationsfromdataclassesimportdataclassdataclass(frozenTrue)classSkillContract:技能契约能力边界的结构化声明。skill_id:strrole:strcapabilities:frozenset[str]side_effects:frozenset[str]trust_required:intpreconditions:frozenset[str]dataclassclassCallContext:调用上下文包含调用者的身份信息与权限。role:strgrants:set[str]trust_level:intrequested_effects:set[str]classContractViolation(Exception):契约违反异常。pass# 注册三项契约 SKILLS{case.accept:SkillContract(skill_idcase.accept,rolesupport.intake,capabilitiesfrozenset({accept,handoff}),side_effectsfrozenset(),# 无写额度trust_required1,preconditionsfrozenset({case:write}),),credit.snapshot:SkillContract(skill_idcredit.snapshot,roledata.credit,capabilitiesfrozenset({read_snapshot}),side_effectsfrozenset(),# 只读trust_required1,preconditionsfrozenset({credit:read}),),limit.decide:SkillContract(skill_idlimit.decide,rolefinance.limit,capabilitiesfrozenset({decide_limit}),side_effectsfrozenset({limit.write}),trust_required2,preconditionsfrozenset({limit:write}),),}# P2 裁决引擎 defassert_p2(skill:SkillContract,ctx:CallContext)-None:P2: 契约与权限取更严者不一致则拒绝。# 1. 角色匹配ifctx.role!skill.role:raiseContractViolation(f角色不匹配: ctx{ctx.role}skill{skill.role})# 2. 前置授权检查权限是否满足契约要求missingskill.preconditions-ctx.grantsifmissing:raiseContractViolation(f授权不足:{sorted(missing)})# 3. 权限不得宽于契约副作用P2 核心# 如果权限中有写额度但契约未声明 limit.write → 拒绝iflimit:writeinctx.grantsandlimit.writenotinskill.side_effects:raiseContractViolation(P2: 权限含 limit:write 但契约未声明 limit.write)# 4. 信任等级检查ifctx.trust_levelskill.trust_required:raiseContractViolation(f信任不足: 需要{skill.trust_required}, 当前{ctx.trust_level})# 5. 请求的副作用必须在契约声明范围内illegalctx.requested_effects-skill.side_effectsifillegal:raiseContractViolation(f未声明副作用:{sorted(illegal)})definvoke(skill_id:str,ctx:CallContext,action:str)-str:调用一个技能带 P2 检查。skillSKILLS[skill_id]assert_p2(skill,ctx)returnfOK{skill_id} CASE-CR-0042 ::{action}# 测试用例CASE-CR-0042 if__name____main__:print( 场景1客服正常受理 )ctx_okCallContext(rolesupport.intake,grants{case:write},trust_level1,requested_effectsset(),)print(invoke(case.accept,ctx_ok,受理 T-CR-0042))print(\n 场景2客服试图走提额技能角色不匹配 )try:invoke(limit.decide,CallContext(rolesupport.intake,grants{limit:write},trust_level2,requested_effects{limit.write},),改额度,)exceptContractViolationase:print(拦截:,e)print(\n 场景3数据角色权限过宽P2 拦截 )try:invoke(credit.snapshot,CallContext(roledata.credit,grants{credit:read,limit:write},# 多了一个不该有的权限trust_level1,requested_effectsset(),),拉信报,)exceptContractViolationase:print(P2 拦截:,e)print(\n 场景4财务正常裁决需四轴见第2期 )ctx_financeCallContext(rolefinance.limit,grants{limit:write},trust_level2,requested_effects{limit.write},)print(invoke(limit.decide,ctx_finance,提额至 120000))运行输出 场景1客服正常受理 OK case.accept CASE-CR-0042 :: 受理 T-CR-0042 场景2客服试图走提额技能角色不匹配 拦截: 角色不匹配: ctxsupport.intake skillfinance.limit 场景3数据角色权限过宽P2 拦截 P2 拦截: P2: 权限含 limit:write 但契约未声明 limit.write 场景4财务正常裁决需四轴见第2期 OK limit.decide CASE-CR-0042 :: 提额至 120000代码要点场景契约权限结果客服受理✅✅通过客服改额度❌无此契约✅拒绝角色不匹配数据拉信报✅只读⚠️过宽拒绝P2 拦截财务裁决✅✅通过需叠加四轴7. 三个教训基于 CASE-CR-0042 的设计经验教训含义证据契约必须挂在调用路径上不能只在文档/注释里写必须由调用前检查强制执行第 6 节代码中的assert_p2()改契约 改边界变更契约需要证据与回归测试不能“改个提示词就上线”联动第 8 期 AssuranceP2 两张皮是事故前奏契约与权限不一致时系统进入不确定状态必须拒绝场景 3 展示核心推论如果 CASE-CR-0042 上线前只做了权限配置IAM没做契约声明SkillContract那么“客服顺手改额度”的边界是不存在的——权限系统只知道“客服能调用写 API”不知道“客服不该调用提额 API”。8. 思考题以下问题供团队内部讨论帮助将 SkillContract 概念落地到具体场景契约盘点在 CASE-CR-0042 上还有哪些“口头禁止”或“隐含边界”尚未写成 SkillContract例如数据 Agent 能否缓存证件号客服能否查看其他客户的工单特批流程若业务临时要求客服“特批改额度”紧急场景按 P2 协议应走什么流程提示不应是“改提示词”而应是“申请临时契约 双人复核 8h 回滚”参见总览 P4 Hotfix-8h。权限过宽排查场景 3 中数据角色被授予了limit:write权限但契约只读。这种“权限过宽”在生产中可能通过什么途径产生如何预防9. 下期预告第 2 期决策四轴Decision Axes财务在limit.decide内用四轴目标轴、约束轴、价值轴、后果轴做提额裁决引入P1 协议任一轴失败默认拒绝。本期将 SkillContract 四轴 P1 组合为完整的财务提额决策链路。10. 延伸阅读资源说明Contractual Skills: A GovernSpec Design Framework for Enterprise AI AgentsarXiv:2605.22634技能契约设计的学术框架本卷第 0 期企业公民——Identity AuditEvent身份与审计基础本卷总览冲突与例外协议 P1–P5P2 在五条协议中的位置本卷第 2 期决策四轴预告P1 四轴裁决本卷第 8 期落地验收预告AssuranceReport 上线前契约与权限一致性证明本文是「企业智能体工程卷」十期专栏的第 1 期。技能即契约——把能力做成可检查的声明让 Agent 的边界从“口头约束”变成“系统强制”。欢迎转载请注明出处与原文标题。 #企业智能体工程体系v1.1｜ 企业智能体工程卷 · 第1期· 技能即契约——把能力做成可检查的声明
#企业智能体工程体系v1.1 企业智能体工程卷 · 第1期技能即契约——把能力做成可检查的声明作者技术治理研究组系列企业智能体工程卷发布版 v1.1主案例CASE-CR-0042信用提额申请本集对象SkillContract · AuditEvent核心协议P2 契约 vs 权限适合读者架构师、技术负责人、AI 产品经理、企业级 Agent 开发者 本文档声明性质本文为企业智能体工程化设计参考框架的第 1 期聚焦 Agent 能力边界的契约化设计提供架构思路与教学级示意代码不构成生产级实现方案或法律合规意见。证据锚定文中案例CASE-CR-0042为教学示意不对应任何真实客户系统。系列定位本篇在第 0 期企业公民 · 身份与审计基础上引入 SkillContract 对象与 P2 协议后续各期将进一步叠加 DecisionRecord、ToolSpec、MemoryItem 等对象。摘要在第 0 期中我们建立了 Agent 的身份Identity与审计AuditEvent基础——明确了“谁在行动”和“留下了什么痕迹”。但仅有身份和审计还远远不够我们仍然不知道 Agent“凭什么”能做某件事。本期回答一个核心问题如何让 Agent 的能力边界从“提示词里的口头约束”变成“调用前可检查的硬契约”CASE-CR-0042 中客服“口头禁止”改额度、数据 Agent“理论上”不该缓存证件号——这些边界靠自觉不靠系统。本期引入SkillContract技能契约对象将每个 Agent 的能力、副作用、前置授权、信任等级声明为可编程检查的结构化契约并通过P2 协议解决契约与权限系统的冲突裁决问题。一句话核心契约不是写在提示词里的“客气话”是挂在调用路径上的“硬约束”。1. 问题为什么“口头禁止”永远拦不住1.1 CASE-CR-0042 的真实困境在 CASE-CR-0042 的链路中三个角色有不同的能力边界角色“应该”能做的事“不应该”能做的事客服support.intake建单、澄清信息、转交工单不能改额度数据data.credit只读查询信用快照不能裁决额度不能写业务系统财务finance.limit提额裁决不能绕过四轴直接通过但在传统的 Agent 实现中这些边界靠什么保障保障方式可靠性问题提示词约束❌ 极低“你是一个客服不能改额度”——越狱/注入可绕过代码注释❌ 极低没人读注释维护者可能不知道口头约定❌ 极低新人不知道赶进度时“顺手”就破了API 权限仅靠 IAM⚠️ 中等只能管“能不能调”管不了“调了干什么”结论无契约技能 边界靠自觉。企业公民不靠自觉。1.2 生产事故的常见前奏“顺手”模式 客服看到额度字段 → “顺手”改了一下 → 测试没发现 → 上线后出了事故 事后复盘 “我以为只有财务才能调用……不对啊为什么客服的 Agent 有这个权限”P2 协议要解决的核心问题契约与权限两张皮是生产事故的标配前奏。2. SkillContract能力即对象2.1 什么是 SkillContractSkillContract ├── skill_id # 唯一标识如 limit.decide ├── role # 允许执行的角色 ├── capabilities # 具体能做什么只读/可写/可裁决 ├── preconditions # 调用前需要哪些授权grants ├── side_effects # 允许的副作用集合如 limit.write ├── trust_required # 信任等级0 low / 1 mid / 2 high └── evidence_ref # 设计/测试依据的追溯编号核心理念技能不是松散的自然语言描述而是调用前可 assert 的结构化对象。2.2 为什么这比提示词可靠维度提示词约束SkillContract可检查❌ 运行时无法自动验证✅ 调用前断言检查可审计❌ 自然语言无结构化痕迹✅ 每次检查都有审计事件可测试❌ 无法单元测试✅ 契约即测试规格可追溯❌ 改提示词不留痕✅ Git 变更可追溯可组合❌ 难以叠加✅ 可组合多个契约3. CASE-CR-0042 的三项契约以下将三个角色的能力声明为结构化的 SkillContractskill_idrolecapabilityside_effectstrustpreconditionscase.acceptsupport.intake建单、澄清、转交无写额度1case:writecredit.snapshotdata.credit读信用快照无写1credit:readlimit.decidefinance.limit提额裁决limit.write2limit:write关键观察客服没有limit.decide契约——不是“提示词里不许”而是“对象里没有”财务的limit.decide显式声明了副作用limit.write——调用前系统会检查信任等级 2高信任对应了财务裁决的高风险操作4. 协议 P2契约 vs 权限——以更严者为准4.1 两张皮的问题运行时同时存在两套控制体系控制体系来源管什么契约SkillContract设计阶段声明能力边界、副作用、信任等级权限Grants身份系统授予具体资源/操作的访问权限问题两者可能不一致。不一致场景后果契约说只读权限给了写Agent 可能“越权”执行未声明操作权限不足契约允许Agent 无法完成本职工作两者冲突且都有效系统陷入不确定性4.2 P2 裁决规则P2 裁决契约 vs 权限 1. 以更严者为准契约和权限的交集决定实际能力 2. 若契约说只读、权限却给了写 → 拒绝调用记缺陷「权限过宽」 3. 若权限不足、契约允许 → 拒绝调用记「授权不足」 4. 禁止“先执行、后补授权/补契约” 5. 上线前须证明契约与权限矩阵一致联动第8期 Assurance4.3 P2 在 CASE-CR-0042 中的应用场景契约权限P2 裁决客服受理工单case.accept允许有case:write✅ 允许客服“顺手”改额度无limit.decide有limit:write❌ 拒绝契约不存在数据拉信报credit.snapshot只读有limit:write过宽❌ 拒绝P2权限宽于契约财务裁决提额limit.decide需limit:write有limit:write✅ 允许需配合四轴见第2期5. 契约生命周期定义 → 授信assign trust → 注册register to skill registry → 调用前检查P2 → 审计AuditEvent 记录 → 有证据演化基于反馈更新6. 最小代码三项契约 P2 实现以下为教学级示意代码展示 SkillContract 的定义与 P2 裁决逻辑from__future__importannotationsfromdataclassesimportdataclassdataclass(frozenTrue)classSkillContract:技能契约能力边界的结构化声明。skill_id:strrole:strcapabilities:frozenset[str]side_effects:frozenset[str]trust_required:intpreconditions:frozenset[str]dataclassclassCallContext:调用上下文包含调用者的身份信息与权限。role:strgrants:set[str]trust_level:intrequested_effects:set[str]classContractViolation(Exception):契约违反异常。pass# 注册三项契约 SKILLS{case.accept:SkillContract(skill_idcase.accept,rolesupport.intake,capabilitiesfrozenset({accept,handoff}),side_effectsfrozenset(),# 无写额度trust_required1,preconditionsfrozenset({case:write}),),credit.snapshot:SkillContract(skill_idcredit.snapshot,roledata.credit,capabilitiesfrozenset({read_snapshot}),side_effectsfrozenset(),# 只读trust_required1,preconditionsfrozenset({credit:read}),),limit.decide:SkillContract(skill_idlimit.decide,rolefinance.limit,capabilitiesfrozenset({decide_limit}),side_effectsfrozenset({limit.write}),trust_required2,preconditionsfrozenset({limit:write}),),}# P2 裁决引擎 defassert_p2(skill:SkillContract,ctx:CallContext)-None:P2: 契约与权限取更严者不一致则拒绝。# 1. 角色匹配ifctx.role!skill.role:raiseContractViolation(f角色不匹配: ctx{ctx.role}skill{skill.role})# 2. 前置授权检查权限是否满足契约要求missingskill.preconditions-ctx.grantsifmissing:raiseContractViolation(f授权不足:{sorted(missing)})# 3. 权限不得宽于契约副作用P2 核心# 如果权限中有写额度但契约未声明 limit.write → 拒绝iflimit:writeinctx.grantsandlimit.writenotinskill.side_effects:raiseContractViolation(P2: 权限含 limit:write 但契约未声明 limit.write)# 4. 信任等级检查ifctx.trust_levelskill.trust_required:raiseContractViolation(f信任不足: 需要{skill.trust_required}, 当前{ctx.trust_level})# 5. 请求的副作用必须在契约声明范围内illegalctx.requested_effects-skill.side_effectsifillegal:raiseContractViolation(f未声明副作用:{sorted(illegal)})definvoke(skill_id:str,ctx:CallContext,action:str)-str:调用一个技能带 P2 检查。skillSKILLS[skill_id]assert_p2(skill,ctx)returnfOK{skill_id} CASE-CR-0042 ::{action}# 测试用例CASE-CR-0042 if__name____main__:print( 场景1客服正常受理 )ctx_okCallContext(rolesupport.intake,grants{case:write},trust_level1,requested_effectsset(),)print(invoke(case.accept,ctx_ok,受理 T-CR-0042))print(\n 场景2客服试图走提额技能角色不匹配 )try:invoke(limit.decide,CallContext(rolesupport.intake,grants{limit:write},trust_level2,requested_effects{limit.write},),改额度,)exceptContractViolationase:print(拦截:,e)print(\n 场景3数据角色权限过宽P2 拦截 )try:invoke(credit.snapshot,CallContext(roledata.credit,grants{credit:read,limit:write},# 多了一个不该有的权限trust_level1,requested_effectsset(),),拉信报,)exceptContractViolationase:print(P2 拦截:,e)print(\n 场景4财务正常裁决需四轴见第2期 )ctx_financeCallContext(rolefinance.limit,grants{limit:write},trust_level2,requested_effects{limit.write},)print(invoke(limit.decide,ctx_finance,提额至 120000))运行输出 场景1客服正常受理 OK case.accept CASE-CR-0042 :: 受理 T-CR-0042 场景2客服试图走提额技能角色不匹配 拦截: 角色不匹配: ctxsupport.intake skillfinance.limit 场景3数据角色权限过宽P2 拦截 P2 拦截: P2: 权限含 limit:write 但契约未声明 limit.write 场景4财务正常裁决需四轴见第2期 OK limit.decide CASE-CR-0042 :: 提额至 120000代码要点场景契约权限结果客服受理✅✅通过客服改额度❌无此契约✅拒绝角色不匹配数据拉信报✅只读⚠️过宽拒绝P2 拦截财务裁决✅✅通过需叠加四轴7. 三个教训基于 CASE-CR-0042 的设计经验教训含义证据契约必须挂在调用路径上不能只在文档/注释里写必须由调用前检查强制执行第 6 节代码中的assert_p2()改契约 改边界变更契约需要证据与回归测试不能“改个提示词就上线”联动第 8 期 AssuranceP2 两张皮是事故前奏契约与权限不一致时系统进入不确定状态必须拒绝场景 3 展示核心推论如果 CASE-CR-0042 上线前只做了权限配置IAM没做契约声明SkillContract那么“客服顺手改额度”的边界是不存在的——权限系统只知道“客服能调用写 API”不知道“客服不该调用提额 API”。8. 思考题以下问题供团队内部讨论帮助将 SkillContract 概念落地到具体场景契约盘点在 CASE-CR-0042 上还有哪些“口头禁止”或“隐含边界”尚未写成 SkillContract例如数据 Agent 能否缓存证件号客服能否查看其他客户的工单特批流程若业务临时要求客服“特批改额度”紧急场景按 P2 协议应走什么流程提示不应是“改提示词”而应是“申请临时契约 双人复核 8h 回滚”参见总览 P4 Hotfix-8h。权限过宽排查场景 3 中数据角色被授予了limit:write权限但契约只读。这种“权限过宽”在生产中可能通过什么途径产生如何预防9. 下期预告第 2 期决策四轴Decision Axes财务在limit.decide内用四轴目标轴、约束轴、价值轴、后果轴做提额裁决引入P1 协议任一轴失败默认拒绝。本期将 SkillContract 四轴 P1 组合为完整的财务提额决策链路。10. 延伸阅读资源说明Contractual Skills: A GovernSpec Design Framework for Enterprise AI AgentsarXiv:2605.22634技能契约设计的学术框架本卷第 0 期企业公民——Identity AuditEvent身份与审计基础本卷总览冲突与例外协议 P1–P5P2 在五条协议中的位置本卷第 2 期决策四轴预告P1 四轴裁决本卷第 8 期落地验收预告AssuranceReport 上线前契约与权限一致性证明本文是「企业智能体工程卷」十期专栏的第 1 期。技能即契约——把能力做成可检查的声明让 Agent 的边界从“口头约束”变成“系统强制”。欢迎转载请注明出处与原文标题。