Repository navigation
spec(IR-0001): agent 自治生产系统 条款级规格 v1 #129
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,40 @@ | ||
| # ADR-XXXX: 第一期允许直连 provider API（AR-3 的第一期形态） | ||
|
|
||
| > 状态：草案（随 spec IR-0001 评审；批准后编号并正式落于 agent-registry/decisions/） | ||
| > 修订对象：GOVERNANCE.yaml AR-3（"模型接入一律经 LLM Gateway；provider key 仅存 gateway secret store"） | ||
| > 关联：IR-0001 spec DECISION-01；ADR-0002 rev1（llm-gateway 部署） | ||
|
|
||
| ## 上下文 | ||
|
|
||
| AR-3 的意图有三：① agent 声明与 provider 解耦（alias 间接层）；② 明文 key 不出现在仓库/配置； | ||
| ③ 用量可按团队计量、配额可控。llm-gateway（LiteLLM）是满足全部三条的实现，但它要求一台 | ||
| 常驻机器（VPS/家用盒/NAS）。GitHub 生态内不存在免费托管持久服务的途径（Actions 不能当服务器）； | ||
| 免 VM 的 serverless 替代品（如 Cloudflare AI Gateway）缺少 per-team 虚拟 key 配额能力， | ||
| 且仍引入新的外部服务依赖。owner 裁定：第一期的运维成本大于收益。 | ||
|
|
||
| ## 决定 | ||
|
|
||
| 第一期（自本 ADR 生效起，至"回切触发条件"任一满足止）： | ||
|
|
||
| 1. 模型接入允许直连 provider API；provider key 只存 org secret `LLM_API_KEY`， | ||
| 仓库/agent 配置/声明中零明文 key 的要求**不变**（AR-3 的意图②保留）。 | ||
| 2. 一切 LLM 调用必须经计量 wrapper，逐次落盘 model/prompt 版本/采样参数/用量 | ||
| （意图③降级为"只计量不熔断"，数据保留供后续预算化）。 | ||
| 3. alias 间接层（意图①）以 `pipeline/models.yaml` 的"角色档 → 具体模型 + 采样参数" | ||
| 解析表实现，版本化、改动走 PR；agent 声明仍只引用角色档，不直写 provider 模型名。 | ||
| 4. registry/models.yaml 的 alias 语义与 AR-8 族级独立要求**继续有效**，作为角色档的定义源。 | ||
|
|
||
| ## 回切触发条件（任一满足即重启 gateway 评估） | ||
|
|
||
| - 需要 per-team/per-agent 配额或预算熔断； | ||
| - 需要多 provider failover； | ||
| - 需要按角色档的成本归账（wrapper 计量显示成本结构失控）； | ||
| - 组织有了事实上的常驻机器（家用盒/便宜 VPS 被用于其他目的，gateway 可搭车）。 | ||
|
|
||
| ## 后果 | ||
|
|
||
| - 正面：零新增基础设施，编排闭环可立即开工；计量数据不丢，回切无障碍。 | ||
| - 负面：无集中 kill switch（只能靠轮换 org secret）；无配额硬限制（只有事后计量）； | ||
| provider key 的暴露面从"gateway secret store"变为"GitHub org secrets + Actions runner 内存"。 | ||
| - 缓解：key 轮换流程文档化；cost-check 的 LLM 预算通道数据源从 gateway usage 端点 | ||
| 改为 wrapper 落盘的 artifact 汇总（原定 pending 项的替代实现）。 | ||
|
coderabbitai[bot] marked this conversation as resolved.
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,134 @@ | ||
| --- | ||
| taskId: IR-0001 | ||
| specVersion: 1 | ||
| title: agent 自治生产系统（意图→实现闭环） | ||
| irRef: plan/IR-0001.md（签署 2026-08-20，正式 issue #128（本文件即其 spec PR）） | ||
| acceptanceCriteria: | ||
| - id: AC-1 | ||
| given: 任一仓存在已登记的 IR issue | ||
| when: owner 打 state:ir-signed 标签（或评论 /start） | ||
| then: 10 分钟内 spec-author 阶段启动，spec PR 自动出现且过 g010；失败则在 issue 评论原因 | ||
| observability: e2e | ||
| - id: AC-2 | ||
| given: 一个含 state:ready 卡的产品仓 | ||
| when: 陌生 coding agent 打开该仓并仅阅读 AGENTS.md | ||
| then: 它能找到找活命令、认领该卡、开工并提交 PR | ||
| observability: e2e | ||
| - id: AC-3 | ||
| given: 一张进入 implement 阶段的卡 | ||
| when: 检查该卡分支的 git 历史 | ||
| then: 测试 commit 早于实现 commit，且新测试在实现前全部红 | ||
| observability: api | ||
| - id: AC-4 | ||
| given: 已合并锁定的验收测试 | ||
| when: 任何非 owner 身份的 PR 改动锁定路径 | ||
| then: g060 以 exit 2 阻断并升级；owner 经 spec 变更流程可解锁 | ||
| observability: e2e | ||
| - id: AC-5 | ||
| given: 一套故意写弱的验收套件（存在可钻的洞） | ||
| when: 恶意合规 adversary 攻击该套件 | ||
| then: 它产出通过全部测试的退化实现，check 判"套件不充分"并 blocking | ||
| observability: api | ||
| - id: AC-6 | ||
| given: verdict 阶段运行 | ||
| when: 揭封 holdout 并执行 | ||
| then: PR check 只显示通过计数；详情写入 holdout 仓；实现阶段日志审计无 holdout 内容 | ||
| observability: api | ||
| - id: AC-7 | ||
| given: 一个故意脏的 PR（高复杂度函数/浅模块/跨层依赖/eslint-disable） | ||
| when: 整洁关卡运行 | ||
| then: 各违规被对应关卡逐条拦下且每条带 fixHint；修复后同一 PR 全绿 | ||
| observability: e2e | ||
| - id: AC-8 | ||
| given: verdict 通过且 riskScore 低于 contract.yaml 的 ceiling | ||
| when: PR 全部 blocking check 绿 | ||
| then: 系统以 App 身份 squash auto-merge，无 LLM 参与合并判定 | ||
| observability: e2e | ||
| - id: AC-9 | ||
| given: 同一关卡在同一任务上连续失败 | ||
| when: 达到 contract.yaml 的 sameGateFailureLimit | ||
| then: 回滚到最后绿点、PR/issue 打 needs-human 并 assign owner | ||
| observability: api | ||
| - id: AC-10 | ||
| given: 系统运行若干周 | ||
| when: 审计 baseline.json 历史 | ||
| then: 全仓指标单调改善（棘轮方向），且阈值只存在于 quality/contract.yaml 一处 | ||
| observability: api | ||
| nonGoals: | ||
| - 不引入多 agent 框架；git+文件+Actions 即编排底座 | ||
| - LLM 无合并判定/approve 权；绝大多数 PR 维持自动合并 | ||
| - 第一期不新建常驻 LLM 服务器（直连 provider API，见 DECISION-01） | ||
| - 不追求全仓 100% 覆盖；diff 上严、全仓棘轮 | ||
| - 不启用 Projects v2（与 BP-4 仓基线一致） | ||
| blastRadius: | ||
| - "Cloudbird-Software/.github: .github/workflows/**, .github/ISSUE_TEMPLATE/**, governance/**, specs/**" | ||
| - "Cloudbird-Software/CI-Workflows: .github/workflows/**" | ||
| - "Cloudbird-Software/agent-registry: decisions/**（AR-3 修订 ADR）" | ||
| - "Cloudbird-Software/template-service 及全部 L2 产品仓: quality/**, Makefile, AGENTS.md, tests/**, .github/workflows/**" | ||
| apiDelta: { public: true, file: specs/IR-0001/api-delta.md } | ||
|
There was a problem hiding this comment. 2. Missing api-delta artifact The spec frontmatter declares a public api-delta file at specs/IR-0001/api-delta.md, but this PR does not add that file, leaving the declared contract surface incomplete. Any consumer (human or future automation) following apiDelta.file will hit a broken reference. Agent Prompt
|
||
| dataMigration: false | ||
| rollback: "全部设施新增式落地；删除 conductor workflow 与 state 标签即整体停用，现有 rulesets 语义不变" | ||
| --- | ||
|
|
||
| # Spec IR-0001：条款 | ||
|
|
||
| > 只含 INV/BEH/IFACE/BUDGET/DECISION/ASSUMPTION/NONGOAL 七类条款。设计细节不进本文，进 ADR。 | ||
|
|
||
| ## INV 不变量（每条绑定可执行断言） | ||
|
|
||
| - INV-01 合并决策仅由确定性脚本做出。断言：auto-merge 触发链路（conductor/verdict workflow）静态扫描无 LLM 调用步骤；riskScore 计算为纯脚本。 | ||
| - INV-02 `state:*` 标签只能由 owner 或 conductor workflow 设置。断言：conductor 校验事件 sender ∈ {owner, app/cloudbrid-agent}，否则回退标签并评论。 | ||
| - INV-03 验收测试 commit 先于实现 commit 且实现前为红；合并后锁定路径 sha256 记入 quality/locks.json；任何身份（含 bypassPermissions 的 agent）写锁定路径必被 g060 以 exit 2 阻断。例外仅：commit trailer 含 `Spec-Change: <TASK> vN->vM` 且 specVersion 已递增。 | ||
| - INV-04 每阶段全新冷上下文，阶段间只经 git/artifact 通信；holdout 内容不得出现在 planner/implementer 的输入与 workflow 日志。断言：阶段产物 hash 落盘；日志正则审计。 | ||
| - INV-05 凡可判定的整洁规则只以关卡形式存在。断言：仓库 lint 扫描 AGENTS.md/CLAUDE.md 出现可判定规则（阈值数字/禁用 API 清单）即 fail；两文件各 ≤100 行（CLAUDE.md）/≤30 行（AGENTS.md，对齐 CG-1）。 | ||
| - INV-06 模型调用凭据只存 org secret（`LLM_API_KEY`），仓库与 agent 配置零明文 key；一切 LLM 调用经计量 wrapper（落盘 model/prompt版本/采样参数/用量）。断言：gitleaks + 调用点静态扫描（直连 SDK 裸调用即 fail）。注：本条是 AR-3 修订后的第一期形态，正式化依赖 DECISION-01 的 ADR。 | ||
| - INV-07 每任务 token/美元/墙钟三重预算；任一触顶回滚最后绿点并升级。断言：wrapper 计量记录存在；预算字段过 schema。 | ||
|
|
||
| ## BEH 行为（EARS） | ||
|
|
||
| - BEH-01 When IR issue 被打 `state:ir-signed`（或 owner 评论 `/start`），conductor shall 在 10 分钟内启动 spec-author 阶段，在目标仓开 spec PR；启动失败 shall 在原 issue 评论原因。 | ||
| - BEH-02 When spec PR 合并，conductor shall 依次启动分歧度量与恶意合规红队，结果作为该 spec 后续卡工作的 blocking 前置。 | ||
| - BEH-03 When 红队全过，wave-planner shall 开出卡 issues：每卡含 AC 表（Given-When-Then + observability）、blastRadius 预测文件集、依赖卡编号、预算；以 tasklist 挂到 spec issue。 | ||
| - BEH-04 When 卡的前置卡全部合并，conductor shall 将其置 `state:ready`。 | ||
| - BEH-05 When 卡 PR 打开，gate workflow shall 解析 PR body 卡元数据，自动选中该卡 AC 对应测试集运行（required workflow 不用 paths 过滤，内部选择）。 | ||
| - BEH-06 If 关卡失败，系统 shall 按 gate report 的 ownerRole 路由修复角色；同一关卡失败达上限 → 回滚最后绿点 + `needs-human` + assign owner。 | ||
| - BEH-07 When verdict 通过且 riskScore < ceiling，系统 shall 以 cloudbrid-agent 身份 squash auto-merge；否则推 quarantine 分支 + `needs-human`。 | ||
| - BEH-08 When 本地 agent 打开任一产品仓，AGENTS.md shall 提供找活三命令（查 ready 卡/认领/跑关卡），agent 无需人类转述即可开工。 | ||
| - BEH-09 When 任一阶段产物落盘，系统 shall 记录 model/prompt 版本/采样参数/产物 hash（过程确定性，可重放）。 | ||
|
|
||
| ## IFACE 契约 | ||
|
|
||
| - IFACE-01 IR issue form 字段 ≡ IR schema v1（job/触发场景/痛点证据/期望可观察变化/非目标/约束/验收证据/可逆性偏好/质量速度旋钮）。 | ||
| - IFACE-02 spec.md frontmatter 过 `spec.schema.json`（本文件即其非正规实例；正规 schema 在 W1-C1 交付）。 | ||
| - IFACE-03 转移表 `governance/transitions.yaml` schema：`{from_state, event, to_state, action, guard}`；conductor 只解释不内嵌逻辑。 | ||
| - IFACE-04 关卡统一 CLI 契约：env `GATE_*`、exit 0/1/2/3、report 过 `gate-report.schema.json`（引用 issue #127 §3，逐字采用）。 | ||
| - IFACE-05 测试↔AC 绑定：Python 仓 `pytest` marker `ac("AC-n")`；TS 仓测试标题前缀 `[AC-n]`；g160 断言每条 AC ≥1 个通过的绑定测试。 | ||
| - IFACE-06 模型角色映射语义（对齐 registry/models.yaml 的分层与 AR-8 族级独立）：spec-author/test-author → reviewer 档；implementer/refactorer → coder-fast 档；恶意合规/对抗 → judge-deep 档（必须独立于 builder/test-author 模型族）；分歧度量 → k=5 跨族混编（各族至少 1 路）。第一期的"档 → 具体 provider 模型名 + 采样参数"解析表落 `pipeline/models.yaml`（版本化、过 schema、改动走 PR）；gateway 启用后改由 gateway alias 解析，本表退役。 | ||
|
There was a problem hiding this comment. 🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -eu
printf '%s\n' '--- candidate files ---'
git ls-files | rg '(^|/)(agent\.schema\.yaml|models\.yaml|spec\.md)$|specs/IR-0001'
printf '%s\n' '--- relevant references ---'
rg -n -C 4 'IFACE-06|BUDGET-04|INV-07|DECISION-01|DECISION-02|model\.alias|registry/models\.yaml|pipeline/models\.yaml|gateway' \
standards specs pipeline 2>/dev/null || true
printf '%s\n' '--- schema section ---'
sed -n '35,60p' standards/agent/agent.schema.yaml
printf '%s\n' '--- IR-0001 section map ---'
rg -n '^(#|##|###)|IFACE-06|BUDGET-04|INV-07|DECISION-01|DECISION-02' specs/IR-0001/spec.mdRepository: Cloudbird-Software/.github Length of output: 14857 🏁 Script executed: #!/bin/bash
set -eu
printf '%s\n' '--- relevant specification context ---'
sed -n '70,125p' specs/IR-0001/spec.md
printf '%s\n' '--- ADR context ---'
sed -n '7,42p' specs/IR-0001/ADR-draft-ar3-phase1-direct-api.md
printf '%s\n' '--- all model and role references ---'
rg -n -C 2 '角色档|档 →|alias|family|models\.yaml|AR-8|spec-author|test-author|implementer|refactorer|judge-deep|coder-fast|reviewer' \
--glob '*.md' --glob '*.yaml' --glob '*.yml' .Repository: Cloudbird-Software/.github Length of output: 21601 补充模型映射的可执行 schema 断言。
🤖 Prompt for AI Agents |
||
| - IFACE-07 holdout 条目 schema：`{id, ir_ref|ac_ref, type: golden-scenario|trajectory, payload, sealed_sha256, created_at}`；揭封事件 append-only 记录。 | ||
| - IFACE-08 本地封装命令（每产品仓 Makefile）：`make card-test CARD=<id>` / `make gates-fast` / `make gates-pr`——agent 与 CI 跑同一编排器入口。 | ||
|
|
||
| ## BUDGET 预算（数字，唯一来源 quality/contract.yaml） | ||
|
|
||
| - BUDGET-01 perTask：usd 12 / tokens 3M / wallClock 90min；perStage contextTokens ≤150K、maxAttempts 3。 | ||
| - BUDGET-02 PR 关卡总时长 ≤8min；hook 快关 ≤15s；nightly ≤120min。 | ||
| - BUDGET-03 Actions 分钟：本期不设上限；cost-check 既有 20000 分钟预算与 AUTO_MERGE_DISABLED 熔断参数相应调整（走 C1 变更）。 | ||
| - BUDGET-04 LLM token：第一期只计量不熔断，由调用 wrapper 逐次落盘 artifact（供后续预算化）。 | ||
|
coderabbitai[bot] marked this conversation as resolved.
Outdated
|
||
| - BUDGET-05 单次 agent 调用 prompt ≤2KB；violations 每批 ≤20 条（#127 §6.2）。 | ||
|
|
||
| ## DECISION（含理由与可逆性） | ||
|
|
||
| - DECISION-01 第一期模型接入直连 provider API（org secret `LLM_API_KEY` + 计量 wrapper），不使用 llm-gateway。理由：gateway（LiteLLM，ADR-0002）必须常驻一台机器（VPS/家用机），GitHub 内无免费托管持久服务的途径，owner 裁定运维成本大于第一期收益。后果：违反 AR-3 字面（provider key 应仅存 gateway secret store）——须以 ADR 修订 AR-3 的第一期形态（草案随本 spec：`specs/IR-0001/ADR-draft-ar3-phase1-direct-api.md`，正式落到 agent-registry/decisions/ 后本条生效）。回切触发条件（任一满足即重启 gateway 评估）：需要 per-team 配额 / 多 provider failover / 按角色成本归账。可逆：是（换调用端点即切回）。 | ||
|
There was a problem hiding this comment. 3. Missing adr draft file DECISION-01 claims an AR-3 revision ADR draft is included at specs/IR-0001/ADR-draft-ar3-phase1-direct-api.md, but this PR does not add that draft, making the decision’s rationale and compliance plan unverifiable. This breaks the traceability that the spec itself requires for governance changes. Agent Prompt
There was a problem hiding this comment. 🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -e
printf '%s\n' '--- candidate files ---'
git ls-files | rg '(^|/)(specs/IR-0001/spec\.md|specs/IR-0001/ADR-draft-ar3-phase1-direct-api\.md|agent-registry/|.*README.*|.*\.ya?ml$)' | head -200
printf '%s\n' '--- relevant terms ---'
rg -n -i -C 3 'llm-gateway|DECISION-01|AR-3|ADR-draft-ar3-phase1-direct-api|PR objective|objective|IFACE-06|BUDGET-04|INV-07|holdout|App install|per-team|provider API' specs/IR-0001 agent-registry .github 2>/dev/null | head -300Repository: Cloudbird-Software/.github Length of output: 12260 🏁 Script executed: #!/bin/bash
set -e
printf '%s\n' '--- AR-3 and related governance text ---'
rg -n -i -C 8 'AR-3|llm-gateway|gateway secret|provider key|LLM_API_KEY|ADR-0002' governance standards specs agent-registry 2>/dev/null | head -260
printf '%s\n' '--- ADR draft ---'
cat -n specs/IR-0001/ADR-draft-ar3-phase1-direct-api.md
printf '%s\n' '--- repository references to the stated PR objective ---'
rg -n -i -C 3 '使用既有|既有.*llm-gateway|use.*llm-gateway|existing.*llm-gateway|PR objective|objective' . 2>/dev/null | head -200
printf '%s\n' '--- agent-registry decision files ---'
git ls-files 'agent-registry/**' | head -100Repository: Cloudbird-Software/.github Length of output: 18633 在合并前正式落地 AR-3 的第一期修订。
🤖 Prompt for AI Agents |
||
| - DECISION-02 holdout 仓为公开仓（owner 已裁：agent 读公开仓是不确定风险，私有化的运维是确定支出）。隔离机制 = cloudbrid-agent 不安装到该仓 + 揭封凭据仅 verdict workflow 可用 + 日志计数化。可逆：转为私有只需一次仓设置变更 + ADR。 | ||
|
There was a problem hiding this comment. 1. Holdout visibility conflict The spec declares the holdout repo must be public, but the wave plan schedules a private holdout repo as a prerequisite, creating an implementer-blocking contradiction about isolation/security posture. This will lead to incompatible infra decisions (App install model, token scope, audit expectations) depending on which document downstream teams follow. Agent Prompt
coderabbitai[bot] marked this conversation as resolved.
Outdated
|
||
| - DECISION-03 自动合并为常态（owner 已裁）：riskScoreCeiling 初始值在 contract.yaml 设定，按 #127 P3 的"零逃逸则渐升"机制演进，而非人工审批常态化。可逆：改一个阈值。 | ||
| - DECISION-04 状态机以 label 为载体，不建 Projects v2（对齐 BP-4 仓基线"projects 关"）。可逆：看板随时可加，纯展示层。 | ||
| - DECISION-05 不新建编排仓：conductor 与 transitions.yaml 放 .github 仓、阶段可复用 workflow 放 CI-Workflows——路由规则即治理意图，接受每次变更走 C1（PR+ADR+owner-merge）的迭代成本，正好 dogfood ADR 流程。可逆：迁出即建仓流程。 | ||
|
|
||
| ## ASSUMPTION（每条绑定监控） | ||
|
|
||
| - ASSUMPTION-01 GitHub-hosted runner 可稳定访问 provider API 端点。监控：W0-C1 的连通性 check workflow，失败开 issue。 | ||
| - ASSUMPTION-02 基建引导期 owner 会提供具备 .github 仓 contents/issues/PRs 写权限的凭据（或亲跑 bootstrap 脚本）。监控：本 spec 第一个执行动作即验证。 | ||
| - ASSUMPTION-03 公开 holdout 被 agent 读取的概率低且影响可接受（DECISION-02 的另一半）。监控：holdout 失败率异常升高（实现疑似过拟合 holdout）时重估，转私有。 | ||
|
|
||
| ## NONGOAL | ||
|
|
||
| 继承 frontmatter nonGoals 五条，不再重复。 | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,62 @@ | ||
| # IR-0001 波次计划（预览版，spec 签署后转为正式 Card issues） | ||
|
|
||
| > 波次边界按"何时能接触现实"切（#126 §3），不按工作量切。 | ||
| > 每波次结束产出一个人类 5 分钟内可验收的东西。 | ||
|
|
||
| ## W0 编排底座 —— "签一条意图，spec PR 自己出现" | ||
| | 卡 | 内容 | 关键 AC | | ||
| |---|---|---| | ||
| | W0-C1 | org secret `LLM_API_KEY`（直连 provider，DECISION-01）+ 计量 wrapper（model/prompt版本/采样参数/用量落盘 artifact）+ AR-3 修订 ADR 正式落 agent-registry；secret 登记进 expected-state.json | secret 存在性被 drift-check §5 覆盖；wrapper 输出过 schema；连通性 check workflow 绿 | | ||
| | W0-C2 | `.github/ISSUE_TEMPLATE/intent.yml`（IR schema 表单）+ `state:*`/`needs-human` label 集；apply.sh 新增 §7 label 同步 | 表单字段与 IR schema 一一对应；label 漂移可检测 | | ||
| | W0-C3 | conductor workflow 骨架：仅一条通路（issues.labeled=state:ir-signed → 调 spec-author 可复用 workflow → 开 spec PR）；转移表 transitions.yaml | 签署测试意图后 spec PR 自动出现；非 owner 打 state 标签被回退 | | ||
| | W0-C4 | spec-author 可复用 workflow（CI-Workflows 仓，冷上下文，输出 spec.md + AC 表） | 产物过 g010-spec-schema 校验 | | ||
| | W0-C5 | AGENTS.md「找活协议」标准块 + `ghcb next`（查 state:ready 卡）+ label 认领协议 | 在一个测试仓实测：陌生 agent 仅读 AGENTS.md 完成认领一张演示卡 | | ||
|
|
||
| **W0 人类验收**：签一条真实意图 → 什么都不做 → spec PR 出现。 | ||
|
|
||
| ## W1 测试合规内核 —— "测试先行、锁定、可追溯" | ||
| | 卡 | 内容 | 关键 AC | | ||
| |---|---|---| | ||
| | W1-C1 | spec.schema.json + g010（条款 ID/AC≥1/禁实现细节关键词/blastRadius 非空） | 非法 spec 被 blocking | | ||
| | W1-C2 | AC 注册表 + 追溯闭合 check（IR↔SPEC↔AC↔Card 双向闭合，防镀金防丢失） | 孤儿条款/孤儿卡/无测试 AC 全部 fail | | ||
| | W1-C3 | 测试产物拓扑：test-author 先行 commit + fail-before 门禁（新测试在 HEAD 必须红）+ lock-tests 哈希锁定 + g060 防篡改 | 测试 commit 早于实现；实现前全红；改锁定测试 exit 2 只人类可解 | | ||
| | W1-C4 | 测试存放规约：`tests/acceptance/`（锁定）按 AC-ID 组织，pytest marker `@pytest.mark.ac("AC-n")` / vitest 标题 `[AC-n]`；g160 AC 追溯 | 每条 AC ≥1 个通过的测试且位置合规 | | ||
| | W1-C5 | 卡 PR 自动测试门：PR 解析卡元数据 → 自动选中该卡 AC 对应测试运行（required workflow 不用 paths 过滤，内部选择）+ Makefile 封装 `make card-test CARD=…` / `make gates-fast` / `make gates-pr` | 卡 PR 上该卡测试自动跑；agent 本地一条 make 命令复现 CI 同一套关卡 | | ||
|
|
||
| **W1 人类验收**：一张演示卡走完 test-author→implementer，git 历史上测试先于实现且曾红。 | ||
|
|
||
| ## W2 红队与 holdout —— "spec 有洞会被发现" | ||
| | 卡 | 内容 | 关键 AC | | ||
| |---|---|---| | ||
| | W2-C1 | holdout 私有仓 + ADR（ADR-0020 全公开政策的唯一例外）+ holdout 条目 schema + 版本化封存（hash） | cloudbrid-agent 未安装到该仓（drift-check 断言）；条目过 schema | | ||
| | W2-C2 | 只读凭据通道：第二个 App `cloudbird-holdout`（read-only，仅装 holdout 仓）或 HOLDOUT_TOKEN，仅在 verdict 可复用 workflow 内可用 | 实现阶段 workflow 日志审计：无 holdout 内容；揭封运行记录留痕 | | ||
| | W2-C3 | 分歧度量：k=5 冷上下文 matrix（混模型档位/家族）→ 决策表 artifact → 确定性比对 job 定位歧义热点，blocking | 人造歧义 spec 被定位到条款 ID；热点未清零不能合 | | ||
| | W2-C4 | 恶意合规：adversary 用最偷懒实现攻验收套件，通过=套件不充分（blocking） | 对故意弱套件必报不充分；对强套件报通过 | | ||
| | W2-C5 | holdout gate：verdict 阶段揭封跑；PR check 只显示通过计数，失败详情写私有 holdout 仓 issue | 实现 agent 日志无泄漏；人类在私有仓看到详情 | | ||
|
Comment on lines
+31
to
+35
There was a problem hiding this comment. 🔒 Security & Privacy | 🟠 Major | 🏗️ Heavy lift 统一 holdout 的可见性与凭据边界（严重级别：Major）。 Line 31 将 holdout 写为私有仓。PR 目标要求公开 holdout 仓。 请在 🤖 Prompt for AI Agents |
||
|
|
||
| **W2 人类验收**：红队对一个真实 spec 的完整攻击报告 + holdout 揭封记录。 | ||
|
|
||
| ## W3 质量关卡全量（#127 P0→P3 压缩版）—— "谓词守门，人看一页" | ||
| | 卡 | 内容 | | ||
| |---|---| | ||
| | W3-C1 | quality/ 骨架 + contract.yaml + 全关卡 non-blocking 跑通 + 首版 baseline.json + g900 棘轮（唯一 blocking） | | ||
| | W3-C2 | diff 硬化转 blocking：lint/typecheck/forbidden/test-tamper/blast-radius/tests/coverage-diff | | ||
| | W3-C3 | 结构+变异转 blocking：deps-arch/api-surface/module-shape/crap-diff/mutation-diff（diff 硬零存活）/flake + refine 循环（gate 报告驱动路由） | | ||
| | W3-C4 | adversary 黑盒阶段 + risk-score + 自动合并（复用 App automerge 通道，ceiling 从 20 起渐升）+ human-brief 一页阅读面 | | ||
|
|
||
| **W3 人类验收**：连续若干 PR 无误报；一份真实 human-brief 一页内读完。 | ||
|
|
||
| ## W4 度量与自进化 —— "系统自己变强" | ||
| 缺陷归因标签（intent/spec/decomposition/test/impl/env）、规划逃逸率等指标落库、 | ||
| 规划回归集（改 planner 必重放历史意图）、thrash-detect、每周抽样审计→立法循环 | ||
| （审计判断当周转成新关卡/forbidden-pattern，否则作废）。 | ||
|
|
||
| ## 依赖 DAG（简） | ||
| W0 → W1 → W2（W2-C1/C2 可在 W1 并行）→ W3 → W4 | ||
| 同波次内的卡预测文件集不相交（W0-C2/C3 都碰 .github/workflows，须串行）。 | ||
|
|
||
| ## 变更分级提示（DECISION-05） | ||
| 不新建编排仓。W0/W1 的卡绝大多数落在 C1 路径（.github workflows、governance/、 | ||
| CI-Workflows workflows/），每张卡的 PR 须附 ADR（新建或引用）——基建期 | ||
| 每张卡 = 一张 ADR + 一个 PR，这是刻意的（dogfood 治理流程）。 | ||
| holdout 仓（W2-C1）走 flows.new_repo + GM-4 申报入 REPOS.yaml。 | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🎯 Functional Correctness | 🟠 Major | 🏗️ Heavy lift
🧩 Analysis chain
🏁 Script executed:
sed -n '1,80p' specs/IR-0001/ADR-draft-ar3-phase1-direct-api.mdRepository: Cloudbird-Software/.github
Length of output: 1616
🌐 Web query:
LiteLLM Proxy virtual keys multi-tenant spend management rate limits official documentation💡 Result:
LiteLLM Proxy supports multi-tenant spend management and rate limiting through Virtual Keys and a hierarchical architecture [1][2]. To utilize these features, you must deploy the proxy with a supported database (e.g., PostgreSQL) [3][4]. Key concepts and implementation details: Virtual Keys and Multi-Tenancy Virtual Keys act as the authentication layer that links requests to specific users or teams for cost tracking and policy enforcement [1][2]. Teams provide the primary tenant boundary [1]. You can define organizations, teams, and users in a hierarchy where spend and limits flow downward [1]. A request's cost is attributed to the key, user, team, and organization simultaneously [1]. Spend Management Budgets are enforced at the Key, User, and Team levels [2]. The proxy enforces budgets by checking spend against data stored in the database [5]. If a deployment is database-less, these budget features are unavailable [5]. Budgets are hierarchical: a team budget cannot exceed its organization's budget, and a user budget cannot exceed the team's [1]. A request is blocked if any level along its hierarchy exceeds its budget [1]. You can set budgets (e.g., max_budget, budget_duration) when creating or updating teams and keys via management endpoints like /team/new or /key/generate [3][6]. Rate Limiting Rate limits (TPM/RPM) can be applied per key, user, or team [5][2]. You can set TPM (tokens per minute) and RPM (requests per minute) limits on virtual keys [3][5]. For teams, you can set per-model rate limits that apply to all keys belonging to that team [6]. The proxy also supports Dynamic TPM/RPM Allocation, allowing you to reserve model capacity for specific priority levels [7]. Automation For multi-tenant environments, you can use JWT-to-Virtual Key mapping [8]. This allows you to automatically provision virtual keys and assign them to teams/users based on JWT claims (e.g., client_id), providing granular control without manual key generation [9][8]. Documentation References - For virtual key management and generation: [3][4] - For team budgets and hierarchical enforcement: [1][6] - For rate limiting configurations: [5][7] - For multi-tenant architecture and identity provisioning: [1][9]
Citations:
🌐 Web query:
Cloudflare AI Gateway spend limit team user application BYOK budget rate limits official documentation💡 Result:
Cloudflare AI Gateway provides distinct features for managing costs and traffic, specifically through spend limits and rate limiting [1][2]. Spend Limits Spend limits allow you to set cost-based budgets in dollars rather than just counting requests [1][2]. - Functionality: These limits track cumulative spend in real time based on token usage and model pricing [1]. They function independently of traditional rate limiting [2]. - Configuration: You can define up to 20 spend limit rules per gateway via the dashboard or API [1]. Rules use rolling or fixed time windows (e.g., daily, weekly, monthly) [2]. - Scoping: Limits can be scoped by model, provider, or custom metadata dimensions such as user ID, team, or application [1][2]. To use these custom dimensions, your application must pass the relevant metadata in requests [1][2]. - Enforcement: When a limit is reached, AI Gateway returns a 429 Too Many Requests response [1]. By default, requests are blocked, but you can configure dynamic routes to fall back to a cheaper model instead [1][2]. - Compatibility: Spend limits apply to both Unified Billing and BYOK (Bring Your Own Keys) requests, provided the model has known pricing [1][3]. Rate Limiting Rate limiting manages traffic volume by restricting the number of requests within a specified time window [4]. - Functionality: It is a request-count-based mechanism that helps prevent spikes and suspicious activity [4]. - Limits: There is a specific system-level rate limit for Unified Billing requests, currently 200 requests per 60 seconds per gateway [5]. This system limit does not apply to BYOK requests [5]. BYOK (Bring Your Own Keys) BYOK allows you to store your own provider API keys securely in the Cloudflare dashboard [6]. - Management: It eliminates the need for hardcoded keys in your application and simplifies key rotation [6]. - Relation to limits: You can apply rate limits and spend limits to BYOK-configured gateways [6]. Unlike Unified Billing, BYOK requests are not subject to the 200 requests/60s system rate limit [5]. Cost Tracking Note: Spend limit calculations are best-effort estimations based on token counts and model pricing [1][7]. For exact billing, always refer to your specific provider's dashboard [1][7]. If you have negotiated rates, you can override default pricing using the custom costs feature [8][7].
Citations:
修正 gateway 能力和部署前提，并重新评估
DECISION-01。LiteLLM Proxy 需要部署和维护运行环境，但不限定为 VPS、家用盒或 NAS；其 virtual key、team budget 和限流能力还需要支持的数据库。Cloudflare AI Gateway 不等同于 LiteLLM 的 virtual key 模型，但支持通过请求元数据按 team、user 或 application 设置 spend limit，并支持 BYOK；其成本计算为 best-effort。请据此改写相关表述，并重新评估
DECISION-01。🤖 Prompt for AI Agents
Source: MCP tools