89088414/16gagent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

🎉 init: 小龙的工作空间

Browse Source
This commit is contained in:
大海
2026-06-06 10:40:48 +08:00
commit a188ee1426
3201 changed files with 231817 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
PORTFOLIO.md
+520
View File
@@ -0,0 +1,520 @@
# PORTFOLIO.md — Portfolio Management Protocol 📊
> **Canonical Reference.** This file defines the Portfolio Management layer.
> Portfolio Management controls multi-project orchestration across the workspace.
> Every project in the workspace MUST be registered in this protocol.
<!-- openclaw:portfolio:doctag -->
---
## §0 Purpose
| Layer | File | Scope |
|-------|------|-------|
| Execution Protocol | AGENTS.md | 单任务怎么做 |
| Execution Governance | GOVERNANCE.md | 单项目怎么管 |
| **Portfolio Management** | **PORTFOLIO.md** | **多项目怎么排** |
**Execution Governance 管理单项目。Portfolio Management 管理多项目。**
### Core Objective
最大化：
| Metric | Why |
|--------|-----|
| **Delivery** | 按时交付率 |
| **ROI** | 投入产出比 |
| **Agent Utilization** | 人力不空转 |
| **Learning Reuse** | 知识不重复造 |
最小化：
| Metric | Why |
|--------|-----|
| **Context Waste** | 上下文切换开销 |
| **Idle Agents** | 空转成本 |
| **Duplicate Work** | 两个项目写同一份代码 |
| **Failed Projects** | 及早止损 |
---
## §1 Portfolio Registry
必须维护 `portfolio.md`（项目根目录）。
### §1.1 Schema
```markdown
# Portfolio Registry
<!-- Last Updated: YYYY-MM-DDTHH:mm:ss+08:00 -->
<!-- Canonical Reference: PORTFOLIO.md §1 -->
## Projects
| Project-ID | Name | Status | Priority | Health | Agents | Progress | Last Updated | ROI |
|------------|------|--------|----------|--------|--------|----------|-------------|-----|
| P-001 | Project Alpha | ACTIVE | P1 | 85 | 3 | 65% | YYYY-MM-DD | 2.4 |
| P-002 | Project Beta | PLANNING | P2 | — | 1 | 0% | YYYY-MM-DD | 1.8 |
```
### §1.2 Field Definitions
| Field | Required | Values | Description |
|-------|----------|--------|-------------|
| Project-ID | ✅ | `P-NNN` | 唯一项目标识 |
| Name | ✅ | string | 项目名称 |
| Status | ✅ | §2 Allowed States | 当前项目状态 |
| Priority | ✅ | §3 Priority System | 优先级 |
| Health | ✅ | 0–100, or `—` if PLANNING | 从 Project Health Aggregation (§7) 同步 |
| Agents | ✅ | ≥1 | 分配 Agent 数 |
| Progress | ✅ | 0–100% | 完成进度 |
| Last Updated | ✅ | ISO-8601 | 最后更新 |
| ROI | ✅ | float | ROI 评分 |
### §1.3 Registry Update Rule
| Event | Action |
|-------|--------|
| 新项目创建 | 立即注册，状态 PLANNING |
| 项目状态变更 | 更新 Status + Last Updated |
| Health Score 更新 | 同步 Health 列 |
| Agent 分配变更 | 更新 Agents 列 |
| 每日审计 | 检查所有字段一致性 |
---
## §2 Project States
### §2.1 Allowed States (7)
```
PLANNING
ACTIVE
BLOCKED
RECOVERY
PAUSED
COMPLETED
ARCHIVED
```
禁止自定义状态。
### §2.2 State Transition Diagram
```mermaid
stateDiagram-v2
[*] --> PLANNING
PLANNING --> ACTIVE
PLANNING --> ARCHIVED
ACTIVE --> BLOCKED
ACTIVE --> RECOVERY
ACTIVE --> COMPLETED
ACTIVE --> PAUSED
BLOCKED --> ACTIVE
BLOCKED --> PAUSED
BLOCKED --> RECOVERY
RECOVERY --> ACTIVE
RECOVERY --> PAUSED
PAUSED --> ACTIVE
PAUSED --> ARCHIVED
COMPLETED --> ARCHIVED
ARCHIVED --> [*]
```
### §2.3 Transition Rules
| From | To | Condition |
|------|----|-----------|
| PLANNING | ACTIVE | 资源已分配，可以启动 |
| PLANNING | ARCHIVED | 取消启动 |
| ACTIVE | BLOCKED | 遇到阻塞，见 GOVERNANCE.md §3 |
| ACTIVE | RECOVERY | Health < 50 或连续失败 > 3 |
| ACTIVE | COMPLETED | 所有交付物完成，Governance Quality Gate 通过 |
| ACTIVE | PAUSED | 低优先级 / 资源不足 / 依赖阻塞 |
| BLOCKED | ACTIVE | 阻塞解除 |
| BLOCKED | PAUSED | 阻塞短期内无法解决 |
| BLOCKED | RECOVERY | 需要恢复计划 |
| RECOVERY | ACTIVE | Recovery Plan 通过审批 |
| RECOVERY | PAUSED | Recovery 无法推进 |
| PAUSED | ACTIVE | 条件满足，恢复执行 |
| PAUSED | ARCHIVED | 确认不再恢复 |
| COMPLETED | ARCHIVED | 归档 |
### §2.4 Prohibited Transitions
```
PLANNING → COMPLETED ❌
ACTIVE → ARCHIVED ❌（必须经过 COMPLETED 或 PAUSED）
BLOCKED → COMPLETED ❌
RECOVERY → COMPLETED ❌
RECOVERY → ARCHIVED ❌（必须经过 PAUSED）
PAUSED → COMPLETED ❌（必须经过 ACTIVE）
```
---
## §3 Priority System
### §3.1 Priority Levels
| Level | Label | Description | Action |
|-------|-------|-------------|--------|
| P0 | Mission Critical | 生产事故 / 安全漏洞 / 合同违约风险 | 立即暂停其他项目，全资源投入 |
| P1 | High Value | 核心交付 / 里程碑 / 高 ROI | 优先分配 Agent，保留资源 |
| P2 | Normal | 日常任务 / 迭代交付 | 按计划进行 |
| P3 | Low Priority | 探索 / 优化 / 非紧急 | 资源空闲时执行，随时可 PAUSE |
### §3.2 Priority Escalation
| Event | Action |
|-------|--------|
| 新 P0 出现 | 自动暂停所有 < P1 项目 |
| P1 项目连续 3 次 heartbeat 无进展 | 评估是否升级 |
| P3 项目 Health 持续 > 90 | 评估是否升级到 P2 |
### §3.3 Priority Collision Resolution
如果多个 P0 同时出现：
1. 按 ROI 排序
2. 按 Agent 依赖链排序（阻塞其他项目的优先）
3. 如无法抉择 → 通知红尘
---
## §4 Resource Allocation
### §4.1 Agent Inventory
| Metric | Definition |
|--------|------------|
| Total Agents | workspace 可用 Agent 总数 |
| Busy Agents | 当前 ACTIVE 项目占用的 Agent 数 |
| Idle Agents | Total − Busy − Blocked − Recovery |
| Blocked Agents | 在 BLOCKED 项目中的 Agent 数 |
| Recovery Agents | 在 RECOVERY 项目中的 Agent 数 |
### §4.2 Agent Utilization Score
```
Utilization = Busy_Agents / Total_Agents
```
| Range | Rating | Action |
|-------|--------|--------|
| ≥ 90% | **Optimal** | 满负荷运转，监控疲劳风险 |
| ≥ 80% | Good | 正常利用 |
| ≥ 70% | Acceptable | 有轻微空闲，可接受 |
| < 70% | **Waste** | 资源严重浪费，启动新项目或合并 |
### §4.3 Resource Rebalancing
| Condition | Action |
|-----------|--------|
| Utilization < 70% | 启动 backlog 中的 P1/P2 项目 |
| P0 出现且 Utilization > 90% | 暂停 P2/P3 项目释放资源 |
| 某个项目连续 idle > 3 heartbeats | 评估是否应该 PAUSE |
| Blocked Agents > 30% | 优先解除阻塞或 kill 项目 |
---
## §5 Project Health Aggregation
### §5.1 Health Dimensions
Portfolio-level Project Health 综合 GOVERNANCE.md §7 的各维度，并且增加 Portfolio 层的维度：
| Dimension | Weight | Source |
|-----------|--------|--------|
| **Delivery Score** | 25% | GOVERNANCE.md §7 (D1) |
| **Quality Score** | 20% | GOVERNANCE.md §7 (D2) |
| **Learning Score** | 15% | GOVERNANCE.md §7 (D5) |
| **Execution Score** | 25% | 基于 progress.log 的心跳密度和状态迁移频率 |
| **Risk Score** | 15% | Blocker 数量 / 严重度 / Duration 的加权 |
### §5.2 Execution Score (Portfolio-specific)
```
Execution_Score = max(0, 100 - staled_heartbeats_ratio × 50 - stalled_transitions × 20)
```
- `staled_heartbeats_ratio`: 过期心跳占总心跳比例
- `stalled_transitions`: 同一状态停留超过 2 倍 stale 阈值的次数
### §5.3 Risk Score (Portfolio-specific)
```
Risk_Score = max(0, 100 - active_blockers × 15 - critical_blockers × 30 - avg_blocker_age_hours × 2)
```
### §5.4 Final Project Health
```
Project_Health = Delivery × 0.25 + Quality × 0.20 + Learning × 0.15 + Execution × 0.25 + Risk × 0.15
```
---
## §6 Portfolio Health Score
### §6.1 Calculation
```
Portfolio_Health = Σ(Project_Health_i × Agent_Count_i) / Σ(Agent_Count_i)
```
按 Agent 数加权的项目健康度平均值。大项目权重高。
### §6.2 Rating
| Range | Rating | Meaning |
|-------|--------|---------|
| 90–100 | **EXCELLENT** | 所有项目健康运转 |
| 80–89 | GOOD | 整体良好，个别关注 |
| 70–79 | ACCEPTABLE | 有风险项目需关注 |
| 60–69 | AT RISK | 多个项目有问题 |
| < 60 | **CRITICAL** | 整条 Portfolio 出问题 |
---
## §7 Learning Reuse Detector
### §7.1 Detection
检查 workspace 中是否多个项目在解决同一问题。
| Signal | Detection Method |
|--------|-----------------|
| 重复模块 | 跨项目文件结构对比 |
| 重复技术选型问题 | Memory Search / ctx_search |
| 重复错误模式 | Reflection 中的 Pattern Class 比较 |
| 重复工具配置 | Shell 配置 / CI config 对比 |
### §7.2 Duplicate Work Criteria
如果满足 **任意两条**：
1. 两个项目的文件清单有 > 30% 重叠
2. 两个项目的 Reflection 中有相同 Pattern Class
3. 两个项目引用了相同的外部依赖且版本相同
4. 两个项目处理了相同的业务域（如 "Auth Module" × 2）
→ 判定 **DUPLICATE WORK**
### §7.3 Required Action
检测到 DUPLICATE WORK 后：
1. **Stop** — 暂停重复部分的开发
2. **Extract** — 抽象为 Shared Package / Shared Service
3. **Refactor** — 两个项目都依赖共享包
4. **Audit** — 记录在 portfolio-audit.md 中
5. **Promote** — 如果 Shared Package 质量过关，纳入 workspace 固化工具集
### §7.4 Prevention
- 新项目启动前，先搜索 workspace 中是否有可复用模块
- 使用 `ctx_search` 或 `memory_search` 检查已有 Pattern
- 设计阶段标注 "可能复用" 候选
---
## §8 Portfolio Audit
### §8.1 Daily Generation
每日生成 `portfolio-audit.md`。
**文件位置:** `<workspace>/portfolio-audit.md`（覆盖式写入）
### §8.2 Audit Schema
See `protocol-reference/templates.md` §portfolio-audit for full schema.
---
## §9 Project Kill Rule
### §9.1 Kill Conditions
满足**任意一条**：
| # | Condition | Threshold |
|---|-----------|-----------|
| K1 | Project Health | < 50 |
| K2 | Continuous Recovery Failure | > 3 次 |
| K3 | ROI Score | < threshold（由项目类型决定） |
| K4 | Scope Explosion × Low Priority | SCOPE EXPLOSION + P3 |
### §9.2 Kill Procedure
1. 标记为 KILL CANDIDATE
2. 生成 Kill Report（包含 Kill Condition、累计投入、已产出）
3. 通知用户审批
4. 审批通过 → 归档项目（PLANNING → ARCHIVED 跳过 ACTIVE）
5. 审计记录 kill 原因和 lessons learned
### §9.3 Graceful Shutdown
即使 kill，也要完成：
- 代码提交（如果写了任何有价值的东西）
- Reflection（记录为什么失败）
- 文档归档（Knowledge 不浪费）
---
## §10 Project Pause Rule
### §10.1 Pause Conditions
满足**任意一条**：
| # | Condition | Threshold |
|---|-----------|-----------|
| P1 | Priority | P3 |
| P2 | Resource Scarcity | Utilization > 90% + 有 P0/P1 等待 |
| P3 | Dependency Blocked | 依赖链阻塞，预计 > 48h 无法解除 |
### §10.2 Pause Procedure
1. 状态 → PAUSED
2. 释放 Agent 资源
3. 在 portfolio.md 中记录 pause reason
4. 设置自动唤醒条件（如：dependency resolved / P0 cleared）
### §10.3 Resume Decision
PAUSED 项目在满足以下条件时评估是否恢复：
- 阻塞原因已解除
- 有可用 Agent 资源（Utilization < 80%）
- Priority 未被降级
---
## §11 Project Promotion Rule
### §11.1 Fast Track Criteria
满足**全部**条件：
| # | Condition | Threshold |
|---|-----------|-----------|
| F1 | Project Health | > 90 |
| F2 | Progress | > 80% |
| F3 | Risk Score | < 20（无高严重度 blocker） |
### §11.2 Fast Track Benefits
- 优先分配 Agent（可抢占 P2/P3 资源）
- 加速 Review 周期
- 更多 Learning Reuse 资源（协助提取 Shared Package）
### §11.3 Demotion
如果 Fast Track 项目连续 2 个心跳不满足 F1/F2/F3 → 自动降级回正常轨道。
---
## §12 Executive Dashboard
### §12.1 Dashboard Generation
生成 `dashboard.md`。
**文件位置:** `<workspace>/dashboard.md`（覆盖式写入，每日更新）
### §12.2 Dashboard Schema
See `protocol-reference/templates.md` §dashboard for full schema.
---
## §13 Portfolio Quality Gate
### §13.1 Pre-Output Checklist
See `protocol-reference/quality-gates.md` §PORTFOLIO for full checklist.
### §13.2 Gate Failure
若任意一项未通过：
```
❌ PORTFOLIO GOVERNANCE FAILED — Portfolio 治理失败。
```
必须修复后才能继续 Portfolio 管理。
---
## §14 Integration Summary
```text
AGENTS.md (Execution) GOVERNANCE.md (Governance) PORTFOLIO.md (Portfolio)
│ │ │
├─ §0 Classify ├─ §0 Purpose ├─ §0 Purpose
├─ §1 Task Tree ├─ §1 State Machine ├─ §1 Portfolio Registry
├─ §2 PLAN ├─ §2 Heartbeat ├─ §2 Project States
├─ §3 Pre-flight ├─ §3 Blocker ├─ §3 Priority System
├─ §4 Failure Replanning ├─ §4 Replanning ├─ §4 Resource Allocation
├─ §5 Verification ├─ §5 Scope Explosion ├─ §5 Project Health Aggregation
│ ├─ §6 Execution Audit ├─ §6 Portfolio Health Score
│ ├─ §7 Health Score ├─ §7 Learning Reuse Detector
│ ├─ §8 Auto-Stop ├─ §8 Portfolio Audit
│ ├─ §9 Quality Gate ├─ §9 Project Kill Rule
│ ├─ §10 State Initialization ├─ §10 Project Pause Rule
│ └─ §11 Integration ├─ §11 Project Promotion Rule
│ ├─ §12 Executive Dashboard
│ ├─ §13 Portfolio Quality Gate
│ └─ §14 Integration Summary
```
### §14.1 Data Flow
```
AGENTS.md §5 Verification
→ Governance Quality Gate (GOVERNANCE.md §9)
→ Project Health (GOVERNANCE.md §7)
→ Portfolio Registry (PORTFOLIO.md §1)
→ Portfolio Health (PORTFOLIO.md §6)
→ Portfolio Audit (PORTFOLIO.md §8)
→ Dashboard (PORTFOLIO.md §12)
```
### §14.2 Lifecycle
```
Project Start
→ PORTFOLIO.md §1: Register project
→ GOVERNANCE.md §10: Init governance state
→ AGENTS.md §0: Start execution
Project Active
→ AGENTS.md §1–5: Execute
→ GOVERNANCE.md: Heartbeat / Blocker / Audit
→ PORTFOLIO.md §8: Portfolio Audit
Project End
→ GOVERNANCE.md §9: Governance Quality Gate
→ PORTFOLIO.md §2: Mark COMPLETED
→ PORTFOLIO.md §1: Update Registry
→ PORTFOLIO.md §8: Final Audit
→ PORTFOLIO.md §12: Update Dashboard
```
---
> **Integrity Check:** This document completes the three-layer architecture.
> PORTFOLIO.md, GOVERNANCE.md, and AGENTS.md form a coherent stack.
> Any amendment to one layer must check consistency with the other two.