diff --git a/governance/GOVERNANCE.yaml b/governance/GOVERNANCE.yaml index 2c492e5..b9bd7aa 100644 --- a/governance/GOVERNANCE.yaml +++ b/governance/GOVERNANCE.yaml @@ -139,6 +139,37 @@ domains: intent: "agent 工具/技能定义放仓库不放本地(可审计防漂移)" strength: advisory + agent_runtime: + # 标准本体: standards/agent/{tool,skill,agent,team,event}.schema.yaml + # 注册条目: Cloudbird-Software/agent-registry + measures: + - id: AR-1 + intent: "agent/skill/tool/team 四类声明 + 模型注册表唯一落盘 agent-registry;本地运行目录仅为部署产物;运行实例可追溯到声明+版本" + strength: enforced + platform: {github: {mechanism: repo, name: agent-registry, validate: agent-registry/scripts/validate.py}} + verify: {method: registry-validate, on: PR} + - id: AR-2 + intent: "引用 status!=approved 的注册条目 = CI 拒绝;proposed→approved 必须走 PR" + strength: enforced + platform: {github: {mechanism: script, entry: agent-registry/scripts/validate.py}} + - id: AR-3 + intent: "模型接入一律经 LLM Gateway:声明只引用 alias;provider key 仅存 gateway secret store;任何仓库/agent 配置零明文 key" + strength: enforced + - id: AR-4 + intent: "agent 凭据最小权限:per-agent/per-team 作用域 token(衔接 AG-1);声明中只写 env 引用" + strength: enforced + - id: AR-5 + intent: "双层控制:软引导(AGENTS.md/identity/skill 正文)+ 硬边界(工具面裁剪→权限引擎→凭据→平台防线);冲突时硬控制优先;拦截记录进事件流" + strength: enforced + - id: AR-6 + intent: "团队必须声明 lifecycle;ephemeral 团队 archive_to+handoff 全部完成才允许销毁;persistent 团队(governance-core)对治理资产持续负责" + strength: enforced + platform: {github: {mechanism: script, entry: agent-registry/scripts/validate.py, check: lifecycle}} + - id: AR-7 + intent: "过程数据三分离:声明/决策→git(registry/ADR);事件→数据层(JSONL 起步);原始轨迹→对象存储滚动30天;项目仓仅 AGENTS.md+team 引用行" + strength: enforced + schema: standards/agent/event.schema.yaml + flows: new_repo: steps: @@ -154,6 +185,12 @@ flows: - {step: 5, action: "差分 job 进 gate", policy: T-09} - {step: 6, action: "mutation 周跑盯 score", policy: T-10} - {step: 7, action: "v2 发布走环境审批+升级/回滚测试", policies: [RL-1, R-01..R-05]} + agent_team_lifecycle: + rules: + - {step: 1, action: "从 agent-registry 声明实例化 team(引用 id@version)", gate: AR-1} + - {step: 2, action: "运行期事件按 event.schema 追加到数据层;拦截记录 tool_called.denied_by", policies: [AR-5, AR-7]} + - {step: 3, action: "ephemeral 完成→执行 handoff:artifacts 走 PR、经验提炼 skill、关键决策升 ADR、轨迹归档", policy: AR-6} + - {step: 4, action: "persistent 团队(governance-core)审核归档资产入库;handoff_done 审计", policy: AR-6} portability: neutral: [intent, strength, verify, risk_posture, flows] # 平台无关,直接搬运 diff --git a/standards/agent/agent.schema.yaml b/standards/agent/agent.schema.yaml new file mode 100644 index 0000000..b822589 --- /dev/null +++ b/standards/agent/agent.schema.yaml @@ -0,0 +1,75 @@ +$schema: "https://json-schema.org/draft/2020-12/schema" +$id: "cloudbird/agent-standard/agent@1" +title: Agent Declaration +description: | + 单智能体声明。Agent = Identity + Model + Capabilities + Permissions + Memory + Workspace + IO Contract。 + 条目落盘 agent-registry/registry/agents/.yaml。 + 约束:所有引用一律用注册表 id(model 用 alias),禁止内联实现细节与密钥。 +type: object +required: [id, version, role, model, capabilities, permissions] +properties: + id: {type: string, pattern: "^[a-z0-9][a-z0-9-]*$", description: "引用形式 agent:"} + version: {type: string, pattern: "^[0-9]+\\.[0-9]+\\.[0-9]+$"} + status: {enum: [proposed, approved, deprecated, rejected]} + role: {type: string, description: "一句话职责;决定团队装配"} + identity: + type: object + required: [prompt_ref] + properties: + prompt_ref: {type: string, description: "提示词文件(registry 内路径);提示词版本随本声明 PR 一起评审"} + style: {type: string, description: "交互风格提示,可缺省"} + model: + type: object + required: [alias] + properties: + alias: {type: string, description: "必须存在于 registry/models.yaml;运行时经 LLM Gateway 路由(AR-3)"} + temperature: {type: number, maximum: 1} + reasoning_level: {enum: [off, low, medium, high]} + capabilities: + type: object + properties: + skills: {type: array, items: {type: string, pattern: "^skill:"}, description: "引用 skill:"} + tools: {type: array, items: {type: string, pattern: "^tool:"}, description: "工具面白名单;未列出=不可见(供给侧裁剪)"} + permissions: + type: object + properties: + inherit: {type: string, description: "继承的策略基线(如 org-default)"} + mode: {enum: [normal, strict], description: "tiered_policy 模式;高危 agent 应为 strict"} + overrides: + type: array + description: "参数级规则;语义继承 openjiuwen tiered_policy(severity 或显式 action)" + items: + type: object + required: [tools] + properties: + tools: {type: array, items: {type: string}} + pattern: {type: string, description: "glob 或 re: 前缀正则"} + severity: {enum: [LOW, MEDIUM, HIGH, CRITICAL]} + action: {enum: [allow, ask, deny]} + credential: + type: object + description: "凭据引用:只写 env 变量名,绝不写值(AR-4 最小权限)" + properties: + github_app: {type: string, description: "如 cloudbird-agent;作用域见 GOVERNANCE AG-1"} + secrets: {type: array, items: {type: string, pattern: "^[A-Z_]+$", description: "运行时注入的 env 名"}} + memory: + type: object + properties: + types: {type: array, items: {enum: [user_profile, episodic, semantic]}, description: "记忆类别;敏感信息过滤默认开启"} + retention: {type: string, description: "如 30d;episodic 默认随 ephemeral team 归档"} + io_contract: + type: object + description: "被作为 tool / A2A 调用时必需;未声明则不可被 expose" + properties: + input: {type: object, required: [schema_ref], properties: {schema_ref: {type: string}}} + output: {type: object, required: [schema_ref], properties: {schema_ref: {type: string}}} + expose: + type: object + properties: + as_tool: {type: boolean, description: "agent-as-tool:被其他 agent 以 tool: 调用"} + a2a_card: {enum: [auto, none], description: "auto=对外发布 Agent Card"} + workspace: + type: object + properties: + scope: {enum: [private, team]} + root: {type: string, description: "private 工作区根;team 则写相对团队共享根的子路径"} diff --git a/standards/agent/event.schema.yaml b/standards/agent/event.schema.yaml new file mode 100644 index 0000000..4bf572a --- /dev/null +++ b/standards/agent/event.schema.yaml @@ -0,0 +1,64 @@ +$schema: "https://json-schema.org/draft/2020-12/schema" +$id: "cloudbird/agent-standard/event@1" +title: Agent Process Event +description: | + 过程数据的事件标准。所有事件 append-only 写入数据层(JSONL 起步,见 ADR-0003), + 不进任何 git 仓库。五类事件覆盖 agent 运行全过程;沉淀/审计/用量统计均从事件流派生。 + 原始轨迹(完整对话、工具入出参全文)不属于本 schema,按 trace_id 关联存放于对象存储/本地滚动目录。 +type: object +required: [event, ts, trace_id] +properties: + event: {enum: [run_started, tool_called, skill_used, decision_made, run_finished]} + ts: {type: string, format: date-time} + trace_id: {type: string, description: "贯穿一次任务全链路"} + session_id: {type: string} + team_id: {type: string, description: "team:;单 agent 任务可缺省"} + agent_id: {type: string, description: "agent:[@version]"} + parent_trace_id: {type: string, description: "子任务派生时回链"} + payload: {type: object, description: "按 event 类型见 $defs"} +$defs: + run_started: + type: object + properties: + goal: {type: string} + team_snapshot: {type: string, description: "实例化所用 team 声明+版本的摘要"} + tool_called: + type: object + properties: + tool: {type: string, description: "tool:"} + ok: {type: boolean} + duration_ms: {type: integer} + severity: {enum: [LOW, MEDIUM, HIGH, CRITICAL]} + denied_by: {type: string, description: "被权限引擎拦截时记录命中的规则 id(硬控制审计依据)"} + cost: {type: number, description: "计费工具的计量值"} + skill_used: + type: object + properties: + skill: {type: string, description: "skill:@"} + acceptance_results: + type: array + description: "验收断言逐条结果" + items: + type: object + properties: + check: {type: string} + kind: {enum: [ci, llm]} + passed: {type: boolean} + decision_made: + type: object + description: "开发过程中的认识与决策数据(为什么这么做)" + properties: + question: {type: string} + choice: {type: string} + alternatives: {type: array, items: {type: string}} + rationale: {type: string} + adr_ref: {type: string, description: "若升级为正式决策,指向 registry decisions/ 编号"} + run_finished: + type: object + properties: + status: {enum: [success, failed, aborted]} + model_alias: {type: string} + tokens_in: {type: integer} + tokens_out: {type: integer} + duration_ms: {type: integer} + handoff_done: {type: boolean, description: "ephemeral team:handoff 是否全部完成"} diff --git a/standards/agent/skill.schema.yaml b/standards/agent/skill.schema.yaml new file mode 100644 index 0000000..5c87a69 --- /dev/null +++ b/standards/agent/skill.schema.yaml @@ -0,0 +1,45 @@ +$schema: "https://json-schema.org/draft/2020-12/schema" +$id: "cloudbird/agent-standard/skill@1" +title: Skill Declaration (SKILL.md frontmatter) +description: | + 流程性知识。skill = 可复用的专业操作规程,载体为 SKILL.md: + YAML frontmatter(本 schema 校验)+ Markdown 正文(给 LLM 的执行指令,不做结构化)。 + 声明段管治理(检索/权限/编排/验收),正文管执行。目录落盘 agent-registry/registry/skills//SKILL.md。 +type: object +required: [name, version, description, allowed_tools, acceptance] +properties: + name: + type: string + pattern: "^[a-z0-9][a-z0-9-]*$" + description: 唯一 id(即目录名);引用形式 "skill:" + version: {type: string, pattern: "^[0-9]+\\.[0-9]+\\.[0-9]+$"} + author: {type: string} + description: + type: string + description: 一句话用途说明;不得含 "<" ">";供技能检索与编排消费 + tags: + description: 检索标签;列表或逗号分隔字符串 + oneOf: + - {type: array, items: {type: string}} + - {type: string} + allowed_tools: + description: 本技能执行中允许调用的工具,引用 "tool:";实际生效以 agent 工具面与权限引擎取交集 + oneOf: + - {type: array, items: {type: string}} + - {type: string} + requires: + type: array + items: {type: string} + description: 前置技能(skill:)或能力声明 + acceptance: + type: array + minItems: 1 + items: {type: string} + description: | + 验收断言。分两类,前缀标注: + [ci] 机器可判定 → 对应 CI 检查项(gate) + [llm] 需语义判定 → 由 reviewer agent / 人复核 + 无前缀视为 [llm]。 + status: + enum: [proposed, approved, deprecated, rejected] + description: 与 tool.status 同语义;默认 proposed,PR 评审后 approved diff --git a/standards/agent/team.schema.yaml b/standards/agent/team.schema.yaml new file mode 100644 index 0000000..66f665d --- /dev/null +++ b/standards/agent/team.schema.yaml @@ -0,0 +1,67 @@ +$schema: "https://json-schema.org/draft/2020-12/schema" +$id: "cloudbird/agent-standard/team@1" +title: Team (Swarm) Declaration +description: | + 多智能体团队声明。Team = Members + Topology + Orchestration + Workspace + Storage + Lifecycle。 + 条目落盘 agent-registry/registry/teams/.yaml。 + 核心规则:团队必须声明 lifecycle;ephemeral 团队销毁前必须完成 handoff(AR-6), + 其资产沉淀给 archive_to 指向的 persistent 团队。 +type: object +required: [id, goal, members, topology, lifecycle] +properties: + id: {type: string, pattern: "^[a-z0-9][a-z0-9-]*$", description: "引用形式 team:"} + version: {type: string, pattern: "^[0-9]+\\.[0-9]+\\.[0-9]+$"} + status: {enum: [proposed, approved, active, archived, deprecated]} + goal: {type: string, description: "团队目标;persistent 团队写持续职责"} + members: + type: array + minItems: 1 + items: + type: object + required: [agent] + properties: + agent: {type: string, pattern: "^(registry:)?agent:", description: "agent:[@version],缺省 latest approved"} + count: {type: integer, minimum: 1, description: "同型多实例"} + as_tool: {type: boolean, description: "该成员以 agent-as-tool 方式被 leader 调用"} + role_override: {type: [string, "null"], description: "实例级角色覆盖"} + topology: + enum: [leader-teammate, flat, hub-spoke] + description: 分布式运行时(pyzmq/A2X 注册中心)由编排框架按此装配 + orchestration: + type: object + properties: + assign: {enum: [leader-dispatch, claim, hybrid], description: "任务分配方式"} + merge: {enum: [leader-aggregate, shared-store, debate], description: "结果合并方式"} + workflow_ref: {type: string, description: "团队级流程文件(阶段/波次/验收门);复杂流程引用,不在此内联"} + workspace: + type: object + description: "团队共享工作区;中间产物可追溯" + properties: + shared: + type: object + properties: + root: {type: string, description: "共享根路径或 env: 引用;分布式部署须各方可见(如 NFS)"} + version_control: {type: boolean} + layout: {type: object, description: "约定子目录", properties: {inbox: {type: string}, artifacts: {type: string}, decisions: {type: string}}} + storage: + type: object + properties: + type: {enum: [local, postgresql]} + ref: {type: string, description: "env: 变量引用(如 env:TEAM_DB_DSN);禁止明文连接串"} + lifecycle: + type: object + required: [type] + properties: + type: {enum: [ephemeral, persistent], description: "persistent=常设,持有仓库/治理职责;ephemeral=任务制,完成即归档"} + archive_to: + type: string + description: "ephemeral 必填:资产沉淀目标 persistent 团队(team:)" + handoff: + type: array + description: "销毁前强制移交动作;全部完成才允许销毁(AR-6)" + items: {enum: [artifacts-pr, memory-distill, skill-extract, adr-write, trace-archive, retrospective]} + destroy_policy: {enum: [after-handoff, manual], description: "after-handoff=移交完成自动销毁"} + channels: + type: array + description: "对外通道(web/tui/a2a/频道);缺省仅内部" + items: {type: string} diff --git a/standards/agent/tool.schema.yaml b/standards/agent/tool.schema.yaml new file mode 100644 index 0000000..42a85ac --- /dev/null +++ b/standards/agent/tool.schema.yaml @@ -0,0 +1,45 @@ +$schema: "https://json-schema.org/draft/2020-12/schema" +$id: "cloudbird/agent-standard/tool@1" +title: Tool Declaration +description: | + 能力原子。tool = agent 可调用的最小能力单元(内置函数/MCP/Shell/脚本/A2A端点)。 + 治理关注点:副作用、严重度基线、I/O 契约、实现位置、生命周期状态。 + 条目落盘于 agent-registry/registry/tools/.yaml。 +type: object +required: [id, version, kind, severity, side_effects, status] +properties: + id: + type: string + pattern: "^[a-z0-9][a-z0-9-]*$" + description: 全局唯一 id;注册表内一切引用(agent.allowed_tools 等)使用 "tool:" + version: {type: string, pattern: "^[0-9]+\\.[0-9]+\\.[0-9]+$"} + kind: {enum: [builtin, mcp, a2a, shell, script, api]} + severity: + enum: [LOW, MEDIUM, HIGH, CRITICAL] + description: 默认严重度基线;权限引擎按 tiered_policy(normal/strict 模式)映射 allow/ask/deny + side_effects: + type: array + items: {enum: [none, filesystem_write, vcs_write, network, shell_exec, cost, mutation_external]} + description: 只读工具必须显式声明 [none];有 cost 的按配额计量 + input: {$ref: "#/$defs/schemaRef"} + output: {$ref: "#/$defs/schemaRef"} + implementation: {$ref: "#/$defs/implRef"} + status: + enum: [proposed, approved, deprecated, rejected] + description: "approved 才可被 agent/skill 引用(CI gate 强制,见 GOVERNANCE AR-2)" + owner: + type: string + description: 负责审批与维护的持久团队(team id)或人 +$defs: + schemaRef: + type: object + required: [schema_ref] + properties: + schema_ref: {type: string, description: "相对 registry 的 JSON Schema 路径"} + implRef: + type: object + required: [repo, path] + properties: + repo: {type: string} + path: {type: string} + ref: {type: string, description: "缺省跟随默认分支"}