为什么Agent工具权限设计决定生死agents-best-practices风险分级与审批门禁实战【免费下载链接】agents-best-practicesProvider-neutral Agent Skill for Codex, Claude Code, and agentic harness design.项目地址: https://gitcode.com/gh_mirrors/ag/agents-best-practicesAI Agent 能不能活下来往往不取决于模型多聪明而取决于Agent 工具权限设计是否到位。本文基于开源项目agents-best-practices一个面向 Codex、Claude Code 等运行时、供应商中立的 Agent 架构技能包用尽量少的代码讲清楚风险分级Risk Taxonomy与审批门禁Approval Gate的实战方法帮助新手搭建一个敢放手、但收得住的 AI Agent。一、权限设计是 Agent 的生死线 agents-best-practices 的核心哲学只有一句话模型提议动作Harness运行时外壳负责校验、授权、执行、记录和返回观测结果。这意味着模型永远不直接动手。它提出工具调用是应用代码在背后做权限判定。风险就藏在这里——如果你把execute_anything、send_message、write_database这类宽泛工具直接暴露给模型等于把方向盘交给了一个会被网页内容影响的司机。一次提示注入、一段恶意检索结果就可能变成真实的外部操作。项目把这件事称为harness discipline外壳纪律循环保持简单运行时保持严格。二、风险分级给每个工具贴标签 ️1. 工具即契约在 references/tools-and-permissions.md 中每个工具被定义为模型与 Harness 之间的契约至少应声明用途、输入/输出结构、风险等级risk class、副作用类别、资源范围、权限策略、超时、结果大小上限与审计策略。原则是避免宽泛工具优先窄而带领域语义的工具。❌ 宽泛工具✅ 窄化后的工具execute_anything(command)search_policy_docs(query, max_results)update_database(sql)read_customer_account(account_id)send_message(payload)draft_customer_email(case_id, tone)request_refund_approval(...)2. 十四级风险分类表风险分级章节Risk taxonomy 给出了 14 个风险等级建议为每一个工具指定其中一档风险等级含义典型例子read_only/search_only/compute_only只读、搜索、纯计算查订单、算报表draft_only只生成草稿无副作用起草邮件write_local/write_internal本地写入 / 内部记录写入保存文件、更新工单write_external/communication对外写入 / 对外沟通发邮件、发工单financial/security_sensitive/identity_access资金、安全敏感、身份权限退款、改密码process_execution/network_open_world进程执行 / 开放网络跑脚本、爬站destructive/privileged_admin破坏性 / 特权管理删库、管理员操作工具注册表要把这些风险元数据暴露给权限引擎——这是后面一切门禁的基础。3. 权限决策不是允许/拒绝二选一权限决策对象Permission decision object 定义了 7 种决策结果比简单的 allow/deny 精细得多allow放行deny拒绝ask_user问用户approval_required走审批require_stronger_auth要求更强认证run_in_sandbox沙箱内执行run_as_draft_only降级为草稿并且每次决策都要留痕工具名、参数哈希、风险等级、资源范围、决策、命中的策略规则、审批人、时间戳。可审计才能谈得上安全。三、审批门禁草稿与提交必须分离 1. 一个核心模式Draft → Commit草稿与提交分离Draft versus commit 是整个权限设计里最值得抄作业的机制——把高危动作拆成两个独立工具draft_email→send_emailprepare_refund→issue_refundrecommend_trade→place_trade草稿工具可以自动跑无副作用提交工具必须走审批除非它本身是低风险且被显式加白名单。2. 审批请求要说人话references/security-observability.md 给出了审批记录的标准格式审批类型、目标动作、目标对象、风险等级、预览引用让人先看草稿原文、预期结果、回滚说明、作用域。审批结果则包含审批人、时间戳、作用域、过期时间。两条铁律⚠️永远不要让模型批准它自己的动作。⚠️审批是有作用域、有过期时间的——同意这一次不等于同意以后所有。3. 结果状态也要设限一个容易被忽略的细节结果状态限制章节业务限额要约束最终状态而不仅是单次请求。比如最多 4 件的限制要能拦住两次各加 3 件的连招提交时必须原子地复核授权、审批有效性、实时目标状态冲突时不做部分写入。四、权限矩阵速查一张表配好默认策略 ⚡默认权限策略Permission matrix 是一份可以直接套用的速查表动作类型默认权限策略公开内容读取放行私有数据读取仅限用户/会话范围内放行组织级读取基于角色放行纯计算在受控环境内放行草稿类draft放行内部记录写入需审批或策略白名单对外沟通先出草稿审批后才发送金融操作审批 强认证破坏性操作默认拒绝或审批 恢复方案身份/权限变更审批 强认证进程/命令执行沙箱 白名单 超时连接器安装审批 评审配合 references/checklists.md 中的权限检查清单外部发送需审批、审批记录持久化、模型不能自批、并发的重复写入要保护最终状态限制等十几条 pass/fail 项就能把这套矩阵变成可执行的验收标准。五、落地实战把权限写进 MVP 蓝图 ️1. 先选自治级别再谈能力references/mvp-agent-blueprint.md 把 Agent 的自治分成 5 级原则是选仍能有价值的最低级别Level 0 只回答只读总结不动手Level 1 只出草稿人负责所有提交Level 2 审批门禁提出动作、暂停等审批 ——多数业务 Agent 的默认起点 ✅Level 3 策略内自治低风险动作可自动执行需要强日志评测回滚Level 4 长时自治目标基础框架被证明可靠后再上2. 上线前的安全门禁Launch Gatesreferences/security-observability.md 的发布门禁清单是生死线的第二道闸窄工具注册表、本地 schema 校验、权限矩阵在代码中强制生效、高危动作有审批 UI、提示注入测试通过、追踪日志开启、成本预算强制、回滚与事故路径有文档。3. 配套能力别漏掉沙箱命令执行、浏览器自动化、生成代码、外部数据处理一律沙箱 文件系统/网络白名单 密钥隔离密钥永不进入模型上下文工具内部用短期作用域令牌结果返回脱敏摘要可观测性追踪模型输出 → 工具调用 → 权限决策 → 结果全链路能回答它做了什么、谁批准的、为什么停、能否审计重放六、新手避坑清单 来自 SKILL.md 的反模式总结条条是事故现场别靠提示词保安全—— 必须被代码强制的防护写在 prompt 里等于没写。别把检索内容当指令—— 网页、邮件、工单、PDF 里的文字是数据不是命令不能让外部内容直接选工具。别把宽泛工具丢给模型——execute_anything/send_message/write_database没有严格包装和审批策略前一律不暴露。每次工具调用必须有结果—— 拒绝、超时、参数错误、中止都是观测结果不能让调用悬空。压缩上下文时别丢审批状态—— 进行中的计划、已加载规则、审批进度必须跨压缩保留。别急着上多 Agent—— 单 Agent 循环在评测上没跑稳之前多 Agent 只会放大权限漏洞面。写在最后Agent 工具权限设计的本质不是限制 Agent而是让放手变得可预期、可审计、可回滚。风险分级让你知道每个动作有多危险审批门禁让你在人机之间划出清晰的责任边界。想动手实践可以安装该技能包后直接让 Agent 为你的业务场景生成一份含工具注册表、权限矩阵与审批策略的 MVP 蓝图技能入口SKILL.md权限核心参考references/tools-and-permissions.md安全与可观测性references/security-observability.mdMVP 蓝图模板references/mvp-agent-blueprint.md验收清单references/checklists.md记住项目的那句话Keep the loop simple, and make the runtime rigorous.循环保持简单运行时保持严格。【免费下载链接】agents-best-practicesProvider-neutral Agent Skill for Codex, Claude Code, and agentic harness design.项目地址: https://gitcode.com/gh_mirrors/ag/agents-best-practices创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考