agent.yaml 参考 / agent.yaml Reference

最后更新：2026-06-29

概述

agent.yaml 是 Agent 包的核心清单文件，使用 YAML 格式声明 Agent 的元数据、权限边界和交付信息。所有字段均为机器可读，用于自动校验和目录展示。

必填字段

字段	类型	说明
`name`	string	Agent 唯一标识，格式 `@agenthr/agent-name`
`version`	string	语义化版本号（semver）
`description`	string	简短功能描述，不超过 200 字
`riskLevel`	string	风险等级 R0-R4
`permissions`	string[]	所需权限列表，如 `["read:files", "write:workspace"]`
`entrypoint`	string	入口文件路径，如 `system_prompt.md`

可选字段

字段	类型	说明
`tools`	string[]	兼容工具列表
`deliveryMethods`	string[]	交付方式
`complianceNotes`	string	合规备注
`tags`	string[]	标签
`language`	string	主要语言

安全红线 / Security Redlines

禁止嵌入 secrets — agent.yaml 中不得包含 API key、密码、token 或任何凭证
禁止声明自动执行 — permissions 不得包含 execute:auto 或类似绕过审核的权限
禁止动态脚本路径 — entrypoint 必须指向包内明确存在的静态文件
禁止网络回调 — permissions 不得包含 network:callback 等可能用于数据外传的权限

违反以上红线的 agent.yaml 将被自动校验拒绝，不进入人工审核流程。

示例 / Example

name: "@agenthr/contract-reviewer"
version: "1.0.0"
description: "Review legal contracts and flag asymmetric clauses"
riskLevel: "R1"
permissions:
  - "read:files"
entrypoint: "system_prompt.md"
tools:
  - "claude-code"
deliveryMethods:
  - "api"
  - "package"