feat: agent 声明标准与 agent_runtime 治理域

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]  # 平台无关，直接搬运

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/<id>.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:<id>"}
+  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:<id>"}
+      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:<id> 调用"}
+      a2a_card: {enum: [auto, none], description: "auto=对外发布 Agent Card"}
+  workspace:
+    type: object
+    properties:
+      scope: {enum: [private, team]}
+      root: {type: string, description: "private 工作区根；team 则写相对团队共享根的子路径"}

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:<id>；单 agent 任务可缺省"}
+  agent_id: {type: string, description: "agent:<id>[@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:<id>"}
+      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:<name>@<version>"}
+      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 是否全部完成"}

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/<name>/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:<name>"
+  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:<id>"；实际生效以 agent 工具面与权限引擎取交集
+    oneOf:
+      - {type: array, items: {type: string}}
+      - {type: string}
+  requires:
+    type: array
+    items: {type: string}
+    description: 前置技能（skill:<id>）或能力声明
+  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

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/<id>.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:<id>"}
+  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:<id>[@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:<id>）"
+      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}

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/<id>.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:<id>"
+  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: "缺省跟随默认分支"}