89088414/16gagent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b87cac57cea1e934c81083bc5897fbb9db5bd53c
16gagent/PORTFOLIO.md
T
大海 a188ee1426 🎉 init: 小龙的工作空间
2026-06-06 10:40:48 +08:00

15 KiB
Raw Blame History

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.

§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

# 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

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

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.

Reference in New Issue View Git Blame Copy Permalink