Skip to content

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

Merged
randypanding merged 1 commit into
mainfrom
agent-standard
Aug 18, 2026
Merged

feat: agent 声明标准与 agent_runtime 治理域#6
randypanding merged 1 commit into
mainfrom
agent-standard

Conversation

@randypanding

@randypanding randypanding commented Aug 18, 2026

Copy link
Copy Markdown
Contributor

内容

  • standards/agent/: tool/skill/agent/team/event 五个 JSON Schema(YAML 书写,AI-first)
  • GOVERNANCE.yaml: agent_runtime 域(AR-1..AR-7)+ flows.agent_team_lifecycle
  • 配套 L1 注册层:agent-registry 仓(已建,含校验器与 ADR-0001..0005)

关联

  • AR-2 状态门禁由 agent-registry/scripts/validate.py 强制(已验证通过)
  • 决策背景见 agent-registry/decisions/

Summary by CodeRabbit

  • 新功能
    • 新增智能体、技能、工具和团队的标准化声明规范。
    • 新增智能体运行事件规范,覆盖运行开始、工具调用、技能使用、决策记录和运行结束。
    • 新增团队生命周期管理规范,支持临时团队交接归档及持久团队审核。
    • 增加模型注册、权限、凭据、记忆、输入输出及工作区等配置约束。
    • 增加各类声明的字段校验、版本管理和生命周期状态规范。

@randypanding
randypanding merged commit 4c14717 into main Aug 18, 2026
1 of 2 checks passed
@coderabbitai

coderabbitai Bot commented Aug 18, 2026

Copy link
Copy Markdown

Review Change Stack

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: d4f955f9-6cc6-4dc8-b6a9-40cb9b6c489e

📥 Commits

Reviewing files that changed from the base of the PR and between 3df8023 and 95e3f48.

📒 Files selected for processing (6)
  • governance/GOVERNANCE.yaml
  • standards/agent/agent.schema.yaml
  • standards/agent/event.schema.yaml
  • standards/agent/skill.schema.yaml
  • standards/agent/team.schema.yaml
  • standards/agent/tool.schema.yaml

📝 Walkthrough

Walkthrough

新增 agent、skill、tool、team 声明和运行事件的 JSON Schema,并新增 agent runtime 治理域及团队生命周期流程。

Changes

Agent runtime standards

Layer / File(s) Summary
声明契约
standards/agent/agent.schema.yaml, standards/agent/skill.schema.yaml, standards/agent/tool.schema.yaml
新增 Agent、Skill 和 Tool 声明 Schema,定义身份、版本、能力、权限、引用、状态及安全约束。
运行与团队契约
standards/agent/event.schema.yaml, standards/agent/team.schema.yaml
新增五类 append-only 运行事件及 Team 声明 Schema,定义事件 payload、团队成员、编排、存储和生命周期字段。
治理与生命周期流程
governance/GOVERNANCE.yaml
新增 agent runtime 治理要求,以及团队实例化、运行记录、工具拦截、交接归档和持久团队审核流程。

Suggested labels: security, feature

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch agent-standard

Comment @coderabbitai help to get the list of available commands.

@randypanding
randypanding deleted the agent-standard branch August 18, 2026 09:49
randypanding added a commit that referenced this pull request Aug 18, 2026
drift-check.sh:
- §8 直推检测去掉消息后缀预筛(qodo #1:后缀可伪造——直推挂 "(#N)" 假
  后缀即绕过预筛被报 clean)。唯一权威判据 = 关联 PR API,窗口内每个
  commit 都复核
- §8 fail-closed(qodo #2):关联 PR 查询改用全 SHA;响应须为数组
  (error 对象此前被 length>0 读作 has-pr、传输失败读作非 none——
  均静默放行)。查询失败 = 无法验证 = 判漂移,绝不静默放行
- §8 分页(qodo #7):commit 列表全分页;超 MAX_COMMITS=300 显式报
  漂移而非静默截断
- §4 fail-closed:org 仓库清单拉取失败时此前 REPOS 为空 → 全部循环
  静默跳过 → 检测整体假绿;现显式 exit 2
- §10 新增 ADR 引用存在性后验(qodo #5):窗口内合并 PR 的 ADR-NNNN
  引用须真实存在于 agent-registry/decisions/——gate 的存在性校验受
  私有仓跨读权 + PR 上下文 secret 暴露面约束(见 gate.yml 注释),
  后验防线与其互补

apply.sh:前置 GET 参与失败计数(qodo #3)——ruleset 清单/CS 清单/
org 仓库清单拉取失败时此前静默跳过或走错误分支,违反 loud-failure
契约;现显式计 FAIL 并在汇总中 exit 1

gate.yml:adr-required 的 PR 文件清单 --paginate(qodo #4:>100 文件
的 C1 变更不再漏检);正则词边界(防 NOTADR-0013junk 子串绕过);
存在性校验后移至 drift-check §10 的原因记录在案(org secret 不可进
PR 触发的 workflow——PR 控制的代码 + secret = zizmor secret-exposure)

governance-drift.yml:issue 归属判定改用专属 label auto-drift-report
(qodo #8:标题搜索会把人工开的同名 issue 误评论/误关闭;label 幂等
创建,创建/评论/关闭全部 label-scoped)

GOVERNANCE.yaml:C1 scope 补 scripts/、.github/、CODEOWNERS、profile/
(qodo #6:机器可读声明与 gate adr-required 实际执法路径一致——
声明与执行不得互斥)

Refs: ADR-0013, #17, #18
randypanding added a commit that referenced this pull request Aug 18, 2026
…19)

* feat: 红队修复批次——gate 硬化、每日漂移+自动关闭、apply loud-failure、App 名统一(ADR-0013)

- gate.yml:timeout-minutes=10;JSON 校验覆盖 expected-state.json(此前只验 rulesets);
  adr-required 实装——C1 路径变更 PR 必须引用 ADR-NNNN(flows "无 ADR 不合并"的机器执行)
- governance-drift.yml:周检→每日(盲区 7 天→1 天);漂移消除自动关闭 issue(防陈旧报告噪音)
- drift-check.sh §8 重写:消息后缀快速筛 + associated-PR API 复核(防伪造/漏报);
  超 24h 未回填直推标记 P0
- apply.sh:loud failure(HTTP 非 2xx 计数汇总 exit 1,防检测→修复死循环);
  头部显式声明不可自动修复类别(§5-§9)及人工路径
- new-repo-init.sh:environment/app 挂载失败 exit 1(此前静默"完成");引导改 pin commit
- App 名统一 cloudbrid-agent(线上真实 slug id=4632704;cloudbird-agent 404)
- GOVERNANCE.yaml:governance-core→team:stewardship(ADR-0004 规划名的落地形态);
  C1 scope 纳入 template-service(供应链入口);GM-1 每日+自动关闭;frequency 对齐
- expected-state.json:org_secrets_required 登记 GOVERNANCE_TOKEN(drift workflow 实际依赖)
- languages.yaml:依赖审批 approver+SLA(防永久挂起);SECURITY.md:响应 SLA/接收人/披露
- AGENTS.md 创建(CG-1 声明的契约文件,此前缺失);agent.schema.yaml profiles 指向 agent-registry

* fix: 评审修复——直推检测去后缀预筛、fail-closed、分页;幽灵 ADR 后验;C1 scope 对齐(ADR-0013)

drift-check.sh:
- §8 直推检测去掉消息后缀预筛(qodo #1:后缀可伪造——直推挂 "(#N)" 假
  后缀即绕过预筛被报 clean)。唯一权威判据 = 关联 PR API,窗口内每个
  commit 都复核
- §8 fail-closed(qodo #2):关联 PR 查询改用全 SHA;响应须为数组
  (error 对象此前被 length>0 读作 has-pr、传输失败读作非 none——
  均静默放行)。查询失败 = 无法验证 = 判漂移,绝不静默放行
- §8 分页(qodo #7):commit 列表全分页;超 MAX_COMMITS=300 显式报
  漂移而非静默截断
- §4 fail-closed:org 仓库清单拉取失败时此前 REPOS 为空 → 全部循环
  静默跳过 → 检测整体假绿;现显式 exit 2
- §10 新增 ADR 引用存在性后验(qodo #5):窗口内合并 PR 的 ADR-NNNN
  引用须真实存在于 agent-registry/decisions/——gate 的存在性校验受
  私有仓跨读权 + PR 上下文 secret 暴露面约束(见 gate.yml 注释),
  后验防线与其互补

apply.sh:前置 GET 参与失败计数(qodo #3)——ruleset 清单/CS 清单/
org 仓库清单拉取失败时此前静默跳过或走错误分支,违反 loud-failure
契约;现显式计 FAIL 并在汇总中 exit 1

gate.yml:adr-required 的 PR 文件清单 --paginate(qodo #4:>100 文件
的 C1 变更不再漏检);正则词边界(防 NOTADR-0013junk 子串绕过);
存在性校验后移至 drift-check §10 的原因记录在案(org secret 不可进
PR 触发的 workflow——PR 控制的代码 + secret = zizmor secret-exposure)

governance-drift.yml:issue 归属判定改用专属 label auto-drift-report
(qodo #8:标题搜索会把人工开的同名 issue 误评论/误关闭;label 幂等
创建,创建/评论/关闭全部 label-scoped)

GOVERNANCE.yaml:C1 scope 补 scripts/、.github/、CODEOWNERS、profile/
(qodo #6:机器可读声明与 gate adr-required 实际执法路径一致——
声明与执行不得互斥)

Refs: ADR-0013, #17, #18

* fix: CodeRabbit 评审修复——权限下沉 job 级、仓库枚举分页、C1 路径三处统一、App 令牌最小作用域(ADR-0013)

- gate.yml:permissions 下沉 gate job(顶层 permissions: {}——防后续
  新增 job 继承 workflow 级权限,对齐 agent-registry validate.yml 同款防御)
- apply.sh/drift-check.sh §4:org 仓库枚举改全分页(>100 仓的 org 不再
  漏应用/漏检基线);apply 侧空清单同样计 FAIL(loud-failure)
- GOVERNANCE.yaml/AGENTS.md/gate.yml:C1 路径定义三处统一——GOVERNANCE
  C1 scope 改 governance/ 整目录并补 tests/(agent-registry 元验证);
  AGENTS.md 硬规则补 profile/;与两个仓的机器执法路径集完全一致
- gh-app-token.sh:REPO 改必填(此前不设=令牌作用域为全部已安装仓库,
  违反最小权限);用法注释禁止交互 shell 内联 PEM(history+子进程
  环境双暴露面),本地走 AGENT_APP_SECRET_FILE、CI 走 Actions secret
- new-repo-init.sh:远端脚本 pin 指引改为"审阅过的合并提交 SHA"
  (gh pr view mergeCommit),不再建议运行时取 main HEAD

Refs: ADR-0013, #17, #18

---------

Co-authored-by: randypanding <randypanding@users.noreply.github.com>
randypanding added a commit that referenced this pull request Aug 19, 2026
* feat: drift-check 新增 §11 CI-Workflows 大版本指针完整性检测(红队 #6-A,ADR-0016)

全部业务仓 gate 引用 CI-Workflows@v1 浮动指针,release-tags ruleset 的
admin bypass 使指针可被强移且此前无任何检测。§11 每日校验不变式
vN==最高 vN.x.y 的 commit(附注 tag 解引用后比对)——强移 24h 内检出。

* fix: drift-check §11 分页聚合 + 必需指针存在性(review 修复)

回应 qodo 意见(2 条 High 落码,1 条 Medium 凭据项以设计依据回复):

1. Tag 分页假绿(High):matching-refs 此前只读第一页,tag 超过单页后
   HIGHEST 计算基于残缺集合。改为 per_page=100 逐页聚合,每页验证为
   数组,任一页失败 fail-closed 拒用部分结果;>50 页(5000+ tag)视为
   异常同样 fail-closed。

2. 缺失 v1 判正常(High):删除 v1 后旧逻辑输出"无大版本指针(不变式
   不适用)"=假绿。v1 是全部业务仓 gate 的供应链入口(REPOS.yaml:
   "业务仓引用 @v1"),指针缺失必须报漂移。新增 CW_REQUIRED_POINTERS
   存在性检查;v2+ 出现后仍由既有循环自动纳入锚点/一致性校验。

3. 凭据项(Medium,不落码):§11 与 §1-§10 共用 GOVERNANCE_TOKEN 是
   AGENTS.md 声明的 drift-check 接口("GH_TOKEN=<org admin> bash
   governance/drift-check.sh");组织级检测本就需要 org 权限,本节
   只读公开仓 refs,复用不扩大暴露面;工作流仅 schedule/dispatch 于
   可信 main 运行。已在代码注释中固化该威胁模型说明。

验证:对真实 API 全量跑通——"指针 'v1' == v1.2.0(8cccf1b)"+"必需
大版本指针存在(v1)"双双 OK;bash -n 通过。

---------

Co-authored-by: randypanding <randypanding@users.noreply.github.com>
Co-authored-by: randypanding <66171646@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant