🎉 init: 小龙的工作空间
This commit is contained in:
大海
+432
@@ -0,0 +1,432 @@
|
||||
# GOVERNANCE.md — Execution Governance Protocol 🔒
|
||||
|
||||
> **Canonical Reference.** This file defines the Execution Governance layer.
|
||||
> AGENTS.md §4 mandates compliance; this file is the full specification.
|
||||
> Every Agent Package MUST follow this protocol. No exceptions.
|
||||
|
||||
<!-- openclaw:governance:doctag -->
|
||||
|
||||
---
|
||||
|
||||
## §0 Purpose
|
||||
|
||||
Execution Protocol（AGENTS.md）解决了 **做什么、谁来做、先做什么**。
|
||||
|
||||
Execution Governance 解决：
|
||||
|
||||
| 问题 | 回答 |
|
||||
|------|------|
|
||||
| 是否真的在做？ | 心跳 + 状态机 |
|
||||
| 是否按计划做？ | Execution Audit |
|
||||
| 是否偏离目标？ | Scope Explosion Detector |
|
||||
| 是否应该停止？ | Auto-Stop Rule |
|
||||
| 是否应该重规划？ | Replanning Trigger |
|
||||
|
||||
**核心理念：计划是廉价的，治理是不可协商的。**
|
||||
|
||||
---
|
||||
|
||||
## §1 State Machine
|
||||
|
||||
每个 Agent Package 必须遵循统一状态机。禁止自定义状态。
|
||||
|
||||
### §1.1 Allowed States (7)
|
||||
|
||||
```
|
||||
NOT_STARTED
|
||||
IN_PROGRESS
|
||||
BLOCKED
|
||||
WAITING_DEPENDENCY
|
||||
READY_FOR_REVIEW
|
||||
VERIFIED
|
||||
FAILED
|
||||
ARCHIVED
|
||||
```
|
||||
|
||||
### §1.2 State Transition Diagram
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> NOT_STARTED
|
||||
NOT_STARTED --> IN_PROGRESS
|
||||
|
||||
IN_PROGRESS --> BLOCKED
|
||||
IN_PROGRESS --> WAITING_DEPENDENCY
|
||||
IN_PROGRESS --> READY_FOR_REVIEW
|
||||
|
||||
BLOCKED --> IN_PROGRESS
|
||||
WAITING_DEPENDENCY --> IN_PROGRESS
|
||||
|
||||
READY_FOR_REVIEW --> VERIFIED
|
||||
READY_FOR_REVIEW --> FAILED
|
||||
|
||||
FAILED --> IN_PROGRESS
|
||||
|
||||
VERIFIED --> ARCHIVED
|
||||
|
||||
ARCHIVED --> [*]
|
||||
```
|
||||
|
||||
### §1.3 Transition Table
|
||||
|
||||
| From | To | Condition |
|
||||
|------|----|-----------|
|
||||
| NOT_STARTED | IN_PROGRESS | Agent Package 开始执行 |
|
||||
| IN_PROGRESS | BLOCKED | 遇到阻塞，无法继续（见 §6 Blocker） |
|
||||
| IN_PROGRESS | WAITING_DEPENDENCY | 依赖的其他 Agent Package 尚未完成 |
|
||||
| IN_PROGRESS | READY_FOR_REVIEW | 工作完成，提审 |
|
||||
| BLOCKED | IN_PROGRESS | 阻塞已解除 |
|
||||
| WAITING_DEPENDENCY | IN_PROGRESS | 依赖已完成 |
|
||||
| READY_FOR_REVIEW | VERIFIED | 审核通过 |
|
||||
| READY_FOR_REVIEW | FAILED | 审核不通过 |
|
||||
| FAILED | IN_PROGRESS | 修改后重新执行 |
|
||||
| VERIFIED | ARCHIVED | 项目归档 |
|
||||
|
||||
### §1.4 Prohibited Transitions
|
||||
|
||||
以下直接跳跃 **违规**：
|
||||
|
||||
```
|
||||
NOT_STARTED → VERIFIED ❌
|
||||
NOT_STARTED → FAILED ❌
|
||||
NOT_STARTED → ARCHIVED ❌
|
||||
IN_PROGRESS → VERIFIED ❌（必须经过 READY_FOR_REVIEW）
|
||||
IN_PROGRESS → FAILED ❌（必须经过 READY_FOR_REVIEW）
|
||||
BLOCKED → READY_FOR_REVIEW ❌
|
||||
BLOCKED → VERIFIED ❌
|
||||
BLOCKED → ARCHIVED ❌
|
||||
WAITING_DEPENDENCY → READY_FOR_REVIEW ❌
|
||||
VERIFIED → IN_PROGRESS ❌（如需修改，回退到 FAILED）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## §2 Heartbeat Rule
|
||||
|
||||
### §2.1 Mandatory Write
|
||||
|
||||
每个 Agent Package 必须定期写入 `progress.log`。
|
||||
|
||||
**格式（JSON Lines，每行一条记录）:**
|
||||
|
||||
```json
|
||||
{"ts":"2026-06-06T05:00:00+08:00","status":"IN_PROGRESS","completed":["T1","T2"],"remaining":["T3","T4"],"risk":"dependency T4 not started","next_action":"kickoff T3"}
|
||||
```
|
||||
|
||||
**字段说明:**
|
||||
|
||||
| 字段 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `ts` | ✅ | ISO-8601 时间戳，含时区 |
|
||||
| `status` | ✅ | 当前状态机的合法状态 |
|
||||
| `completed` | ✅ | 已完成的任务 ID 列表 |
|
||||
| `remaining` | ✅ | 剩余任务 ID 列表 |
|
||||
| `risk` | 条件 | 存在风险时必填 |
|
||||
| `next_action` | ✅ | 下一步具体操作 |
|
||||
|
||||
**文件位置:** `<agent-package-root>/progress.log`
|
||||
|
||||
### §2.2 Heartbeat Frequency
|
||||
|
||||
| Package Size | Max Interval Before Stale |
|
||||
|-------------|--------------------------|
|
||||
| Small | 30 分钟 |
|
||||
| Medium | 2 小时 |
|
||||
| Large | 8 小时 |
|
||||
|
||||
### §2.3 Stale Task Detection
|
||||
|
||||
未在 Max Interval 内写入心跳 → **判定为 `STALE`**。
|
||||
|
||||
STALE 检测器自动标记该 Agent Package 为 `BLOCKED`，并写入警报。
|
||||
|
||||
### §2.4 Heartbeat Format Template
|
||||
|
||||
见 `scripts/templates/progress.log.template`。
|
||||
|
||||
---
|
||||
|
||||
## §3 Blocker Management
|
||||
|
||||
### §3.1 Blocker Declaration
|
||||
|
||||
状态变为 `BLOCKED` 时，必须立即创建 `blocker.md`。
|
||||
|
||||
**文件位置:** `<agent-package-root>/blocker.md`
|
||||
|
||||
### §3.2 Blocker Schema
|
||||
|
||||
See `protocol-reference/templates.md` §blocker for the full schema.
|
||||
|
||||
### §3.3 Blocker Escalation
|
||||
|
||||
如果 `escalated: YES`，必须同时：
|
||||
|
||||
1. 写入 `blocker.md`
|
||||
2. 通知用户（如可送达）
|
||||
3. 停止当前 Agent Package 的后续执行
|
||||
|
||||
### §3.4 Blocker Resolution
|
||||
|
||||
在 blocker 解除时：
|
||||
|
||||
1. 填充 `resolved_at` 字段
|
||||
2. 状态迁移 `BLOCKED → IN_PROGRESS`
|
||||
3. 在心跳中记录解除信息
|
||||
|
||||
---
|
||||
|
||||
## §4 Replanning Trigger
|
||||
|
||||
### §4.1 Trigger Conditions
|
||||
|
||||
满足任意条件，必须触发 **REPLAN REQUIRED**：
|
||||
|
||||
| # | Condition | Source |
|
||||
|---|-----------|--------|
|
||||
| R1 | 某个 Agent Package 变为 `FAILED` | State Machine |
|
||||
| R2 | `BLOCKED` 持续时间超过 2 倍 Stale 阈值 | Heartbeat |
|
||||
| R3 | Dependency 失败（依赖的 Agent Package 进入 `FAILED`） | State Machine |
|
||||
| R4 | Quality Gate 失败（AGENTS.md §5 Pre-flight Compliance） | Execution Protocol |
|
||||
| R5 | Test 失败超过阈值 | Test Runner |
|
||||
| R6 | Scope Explosion 被触发（§7） | Scope Detector |
|
||||
| R7 | Project Health Score < 60（§9） | Health Score |
|
||||
| R8 | 连续失败 > 3 | Auto-Stop |
|
||||
|
||||
### §4.2 Replanning Protocol
|
||||
|
||||
1. **暂停**所有相关的 Agent Package（状态 → `BLOCKED`）
|
||||
2. **分析**失败原因 — 是否系统性？是否需要调整 Task Tree？
|
||||
3. **输出**修订后的 Task Tree 和 PLAN
|
||||
4. **记录** replan evidence 到 `execution-audit.md`
|
||||
5. **恢复**执行（状态 → `IN_PROGRESS`）
|
||||
|
||||
### §4.3 Replan Log Entry
|
||||
|
||||
每次 replan 必须在 `execution-audit.md` 中记录（格式见 `protocol-reference/templates.md` §replan）。
|
||||
|
||||
---
|
||||
|
||||
## §5 Scope Explosion Detector
|
||||
|
||||
### §5.1 Detection Rules
|
||||
|
||||
如果以下任意条件成立，判定为 **SCOPE EXPLOSION**：
|
||||
|
||||
| # | Condition | Measurement |
|
||||
|---|-----------|-------------|
|
||||
| S1 | 预计代码量增长 > 2x | 初始估算 vs 当前估算 |
|
||||
| S2 | 预计文件数增长 > 2x | 初始文件清单 vs 当前文件清单 |
|
||||
| S3 | 出现新的业务域 | 最初未包含的概念/模块 |
|
||||
| S4 | 依赖深度增加 > 1 | 初始依赖链 vs 当前依赖链 |
|
||||
|
||||
### §5.2 Required Actions
|
||||
|
||||
检测到 Scope Explosion 后必须：
|
||||
|
||||
1. **拆分**当前 Agent Package 成多个子包
|
||||
2. **重新规划** Task Tree
|
||||
3. **记录** scope change 证据到 `execution-audit.md`
|
||||
4. **通知**用户
|
||||
|
||||
### §5.3 Prevention
|
||||
|
||||
- 每个 Agent Package 声明 `Context Budget`（AGENTS.md §Agent Package Context Budget）
|
||||
- 如果 `Utilization > 90%`，在启动前就拆分，不要等爆发
|
||||
|
||||
---
|
||||
|
||||
## §6 Execution Audit
|
||||
|
||||
### §6.1 Daily Audit
|
||||
|
||||
每天生成 `execution-audit.md`。
|
||||
|
||||
**文件位置:** `<project-root>/execution-audit.md`
|
||||
|
||||
### §6.2 Audit Schema
|
||||
|
||||
See `protocol-reference/templates.md` §execution-audit for full schema.
|
||||
|
||||
## §7 Project Health Score
|
||||
|
||||
### §7.1 Dimension Definitions
|
||||
|
||||
#### D1 — Delivery Score (0–100)
|
||||
|
||||
度量：实际完成速度 vs 计划速度。
|
||||
|
||||
```
|
||||
Delivery Score = min(100, (completed_tasks / planned_tasks) × 100 × schedule_adjustment)
|
||||
```
|
||||
|
||||
其中 `schedule_adjustment` = 如果超出计划时间则衰减 0.9/天。
|
||||
|
||||
#### D2 — Quality Score (0–100)
|
||||
|
||||
度量：Failures / Reviews 比率。
|
||||
|
||||
```
|
||||
Quality Score = max(0, 100 - (failed_reviews / total_reviews) × 100)
|
||||
```
|
||||
|
||||
不通过率越高分越低。
|
||||
|
||||
#### D3 — Parallelism Score (0–100)
|
||||
|
||||
度量：实际并发 Agent Package 数 vs 最大可能并发。
|
||||
|
||||
```
|
||||
Parallelism Score = min(100, (avg_active_packages / max_possible_packages) × 100)
|
||||
```
|
||||
|
||||
一个都没并行起来 → 0。全在跑 → 100。
|
||||
|
||||
#### D4 — Dependency Score (0–100)
|
||||
|
||||
度量：依赖等待时间占总时间的比例。
|
||||
|
||||
```
|
||||
Dependency Score = max(0, 100 - (waiting_time / total_time) × 100)
|
||||
```
|
||||
|
||||
等依赖的时间越长，分越低。
|
||||
|
||||
#### D5 — Learning Score (0–100)
|
||||
|
||||
度量：Reflection 覆盖率和知识沉淀。
|
||||
|
||||
```
|
||||
Learning Score = min(100, reflections_written × 10 + patterns_promoted × 5)
|
||||
```
|
||||
|
||||
上限 100，鼓励写 Reflection 和 Promotion。
|
||||
|
||||
### §7.2 Final Score
|
||||
|
||||
```
|
||||
Health Score = Delivery × 0.30 + Quality × 0.25 + Parallelism × 0.15 + Dependency × 0.15 + Learning × 0.15
|
||||
```
|
||||
|
||||
### §7.3 Rating
|
||||
|
||||
See `protocol-reference/metrics.md` §Rating for the full rating table (EXCELLENT→CRITICAL).
|
||||
|
||||
---
|
||||
|
||||
## §8 Auto-Stop Rule
|
||||
|
||||
### §8.1 Stop Conditions
|
||||
|
||||
满足任意条件，**立即停止**执行：
|
||||
|
||||
| # | Condition | Threshold |
|
||||
|---|-----------|-----------|
|
||||
| A1 | 连续失败次数 | > 3 |
|
||||
| A2 | Project Health Score | < 60 |
|
||||
| A3 | Critical Dependency Failed | 依赖的 Agent Package 进入 FAILED，且该 Agent Package 是硬依赖 |
|
||||
|
||||
### §8.2 RECOVERY MODE
|
||||
|
||||
进入 RECOVERY MODE 后：
|
||||
|
||||
1. **禁止**创建新的 Agent Package
|
||||
2. **禁止**修改代码
|
||||
3. **必须**执行以下恢复步骤：
|
||||
- 生成 Recovery Report（包含所有 FAILED/BLOCKED/STALE 的状态快照）
|
||||
- 分析 root cause 链（为什么走到这一步？最早在哪个决策点出问题？）
|
||||
- 调整 Task Tree 和 PLAN
|
||||
- 提交 recovery plan 给用户审批
|
||||
4. **只有**用户明确批准后，才可退出 RECOVERY MODE
|
||||
|
||||
### §8.3 Recovery Report Template
|
||||
|
||||
见 `scripts/templates/recovery-report.md.template`。
|
||||
|
||||
---
|
||||
|
||||
## §9 Governance Quality Gate
|
||||
|
||||
### §9.1 Pre-Output Checklist
|
||||
|
||||
See `protocol-reference/quality-gates.md` §GOVERNANCE for full checklist.
|
||||
|
||||
### §9.2 Gate Failure
|
||||
|
||||
若任意一项未通过：
|
||||
|
||||
```
|
||||
❌ GOVERNANCE FAILED — 项目治理失败。禁止输出。
|
||||
```
|
||||
|
||||
必须修复所有未通过项后才能输出。
|
||||
|
||||
### §9.3 Integration with AGENTS.md
|
||||
|
||||
Governance Quality Gate 在 AGENTS.md §5 Verification Protocol 的 `## VERIFICATION` 块 **之后、输出之前** 执行。
|
||||
|
||||
---
|
||||
|
||||
## §10 Governance State Initialization
|
||||
|
||||
### §10.1 Project Start
|
||||
|
||||
每个新项目启动时：
|
||||
|
||||
1. 创建 `<project-root>/GOVERNANCE.md`（符号链接或副本指向本文档）
|
||||
2. 创建 `<project-root>/execution-audit.md`（空文件，等待 Audit 填充）
|
||||
3. 为每个 Agent Package 创建 `progress.log`
|
||||
4. 初始化所有 Agent Package 状态为 `NOT_STARTED`
|
||||
|
||||
### §10.2 Agent Package Handoff
|
||||
|
||||
当一个 Agent Package 完成（→ `VERIFIED` → `ARCHIVED`）：
|
||||
|
||||
1. 最后写入一条心跳（`status: ARCHIVED`）
|
||||
2. 更新 `execution-audit.md` 中的 Task Status Matrix
|
||||
3. 触发依赖等待的 Agent Package 检查（`WAITING_DEPENDENCY → IN_PROGRESS`）
|
||||
|
||||
### §10.3 Governance Override
|
||||
|
||||
Governance Protocol 可以通过以下方式被 override：
|
||||
|
||||
| Override | 权限 | 记录要求 |
|
||||
|----------|------|----------|
|
||||
| 跳过 State Transition Rules | 仅红尘 | 必须在 audit 中记录原因 |
|
||||
| 跳过 Auto-Stop | 仅红尘 | 必须在 audit 中记录风险接受声明 |
|
||||
| 修改 Stale 阈值 | 仅红尘 | 必须在 audit 中记录新阈值和理由 |
|
||||
| 修改 Health Score 权重 | 仅红尘 | 必须在 audit 中记录新权重 |
|
||||
|
||||
**任何 override 不代表协议失效，只是用户明确同意的偏差。** 每次 override 必须在 `execution-audit.md` 的 Override Log 中记录。
|
||||
|
||||
---
|
||||
|
||||
## §11 Integration Summary
|
||||
|
||||
```text
|
||||
AGENTS.md (Execution Protocol) GOVERNANCE.md (Governance Protocol)
|
||||
│ │
|
||||
├─ §0 Classify │
|
||||
├─ §1 Task Tree │
|
||||
├─ §2 PLAN │
|
||||
├─ §3 Pre-flight │
|
||||
├─ §4 (reference → GOVERNANCE.md) ─────┤
|
||||
│ ├─ §1 State Machine
|
||||
│ ├─ §2 Heartbeat
|
||||
│ ├─ §3 Blocker
|
||||
│ ├─ §4 Replanning
|
||||
│ ├─ §5 Scope Explosion
|
||||
│ ├─ §6 Execution Audit
|
||||
│ ├─ §7 Health Score
|
||||
│ ├─ §8 Auto-Stop
|
||||
│ └─ §9 Quality Gate
|
||||
│ │
|
||||
├─ §5 Verification │
|
||||
│ └─ Quality Gate ────────────────────┘
|
||||
├─ §6 Auto-Capture │
|
||||
└─ Learning Loop │
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
> **Integrity Check:** This document is version-locked. Any amendment to the state machine or transition rules requires updating the mermaid diagram and transition table simultaneously.
|
||||
Reference in New Issue
Block a user