# moziplus v2.0 — AI 原生多Agent编排平台 架构设计

**版本**: v2.6（实现前终版）  
**日期**: 2026-05-14  
**作者**: 庞统（副军师）  
**状态**: 实现前终版，防降级机制 + 上下文管理 + spawn 首选 + Skill AI native  
**调研基础**: `docs/research/shared-consciousness-research.md`  
**变更记录**: 
- v2.0 初版（四相循环 + Blackboard 设计）
- v2.1 技术架构修订（Daemon+HTTP API+SQLite, 废弃sessions_send/cron）
- v2.2 完整设计（物理结构、API定义、经验沉淀、状态机、实现清单）
- v2.3 评审修订（司马懿两轮评审：openclaw agent CLI调度、质量治理框架、双写简化）
- v2.4 AI native 修正（恢复三个被妥协的核心目标：Agent 自主协作、实时共享感知、AI 持续参与）
- v2.5 AI native 完善（Skill 三层体系 + 调度五原则 + Iterative Refinement + Observation 自由格式 + spawn 实验 + 双模式调度）
- v2.6 实现前终版（spawn 首选 + 庞统上下文管理 + 防降级机制 + Skill AI native 方案 + 并行感知识别机制）

---

## 0. 设计哲学

> "可预测的骨架 + AI 驱动的填充" —— 不是纯 DAG，也不是纯 ReAct，而是混合模式。

六个核心信念：

1. **AI 参与每一个决策层** —— 编排/路由/渲染/异常处理/经验沉淀都有 AI 参与
2. **黑板是唯一真相源** —— 所有 Agent 通过黑板共享信息，没有私下通信
3. **产出物 > 消息** —— 共享产出物比共享消息更重要
4. **验证才算完** —— 不验证产出不算完成
5. **有界并行** —— 默认最多 4 个 Agent 并行（有学术依据）
6. **闭环学习** —— 执行→经验沉淀→下次改进

---

## 1. 系统总览

### 1.1 宏观架构

```
用户（自然语言）
     │
     ▼
┌─────────────────────────────────────────────────────────────┐
│                    对话入口（Conversation Layer）              │
│  庞统的持久 session，用户唯一交互点                             │
│  支持：WebChat / CLI / Cron 触发 / API 调用                  │
└───────────────────────┬─────────────────────────────────────┘
                        │
┌───────────────────────▼─────────────────────────────────────┐
│                 庞统 AI 指挥官（Control Unit）                 │
│                                                              │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐        │
│  │ Phase 1  │ │ Phase 2  │ │ Phase 3  │ │ Phase 4  │        │
│  │ 需求探索  │ │ 动态规划  │ │ 自主执行  │ │ 主动汇报  │        │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘        │
│                                                              │
│  内置机制：                                                   │
│  - /goal Ralph Loop：持久目标跨 turn 保持                    │
│  - Scope Reduction Detection：防偷懒                          │
│  - 幻觉门控：验证产出再算完成                                  │
│  - Fidelity 路由：按需分发信息                                │
│  - Boids 规则注入：Agent 协作行为塑造                         │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐    │
│  │              Blackboard（共享意识空间）                 │    │
│  │                                                      │    │
│  │  TaskCtx │ Moments │ Artifacts │ Decisions │ Plan    │    │
│  │  AgentStates │ Experience │ EventLog                 │    │
│  └──────────────────────────────────────────────────────┘    │
└───────────────────────┬─────────────────────────────────────┘
                        │ Fidelity 三档读写
          ┌─────────────┼─────────────┐
          │             │             │
     ┌────▼────┐  ┌────▼────┐  ┌────▼────┐
     │  张飞   │  │  关羽   │  │  赵云   │  ...
     │  编码   │  │  风控   │  │  数据   │
     └─────────┘  └─────────┘  └─────────┘
     每个 Agent: isolated session + SOUL.md + Skills
     写入保护: propose → validate → commit
```

### 1.2 与 v1.0 的关系

| 维度 | v1.0 | v2.0 |
|------|------|------|
| 编排 | 固定 DAG 模板 + 确定性状态机 | 庞统 AI 动态规划 + 持续指挥 |
| 通信 | Sanguo Mail（异步邮件轮询） | Blackboard（实时共享读写） |
| 入口 | CLI + Dashboard | 自然语言对话 |
| 计划 | 一次性生成不可变 | 持续演进，可随时调整 |
| Agent 调度 | 按模板固定分配 | 按能力画像动态选择 |
| 信息可见性 | 每个 Agent 只看自己 | Fidelity 三档按需 |
| 异常处理 | Report Watcher（规则） | 庞统 AI 判断 |
| 验证 | output.md frontmatter | 幻觉门控 + AI 验证 |
| 经验 | 无闭环 | DISCOVER→DISTILL→APPLY→IMPROVE |

**v2.0 独立仓库、独立代码、独立部署**。v1.0 继续运行，互不干扰。

---

## 2. 核心模块详细设计

### 2.1 Blackboard（共享意识空间）

#### 2.1.1 物理结构

```
~/.sanguo_projects/sanguo_moziplus_v2/
├── blackboard/                         # 共享意识空间根目录
│   ├── tasks/                          # 任务空间
│   │   └── {task-id}/                  # 每个任务独立目录
│   │       ├── context.json            # 任务上下文（目标/约束/状态）
│   │       ├── moments.jsonl           # 原子事件流（追加写入）
│   │       ├── plan.json               # 动态计划图谱
│   │       ├── decisions.jsonl         # 决策记录（不可变）
│   │       ├── agents/                 # 各 Agent 工作区
│   │       │   ├── {agent-id}/
│   │       │   │   ├── state.json      # Agent 当前状态
│   │       │   │   ├── output/         # Agent 产出物
│   │       │   │   └── inbox/          # Agent 专属信箱（通知类）
│   │       │   └── ...
│   │       └── artifacts/              # 共享产出物索引
│   │           └── index.json          # 产出物注册表
│   ├── global/                         # 全局共享空间
│   │   ├── agent-registry.json         # Agent 能力画像注册表
│   │   ├── experience/                 # 跨任务经验库
│   │   │   ├── {domain}.jsonl          # 按领域组织
│   │   │   └── index.json              # 经验索引
│   │   └── templates/                  # 任务模板库
│   │       └── {template-id}.json
│   ├── events/                         # 不可变全局事件日志
│   │   └── {date}.jsonl                # 按日期分文件
│   ├── inbox/                          # 用户需求入口
│   │   └── {req-id}.json               # 待处理需求
│   └── locks/                          # 写入锁目录
│       └── {resource-path}.lock        # 文件锁
├── daemon/                             # 守护进程代码
├── skills/                             # Skill 包
├── docs/                               # 文档
└── config/                             # 配置
```

#### 2.1.2 数据结构定义

**context.json** — 任务上下文：
```json
{
  "task_id": "task-20260514-001",
  "title": "均线策略回测",
  "goal": "对双均线交叉策略在沪深300上进行5年回测",
  "intent": "验证该策略在A股市场的有效性",
  "end_state": "回测报告完整，包含收益曲线、最大回撤、夏普比率",
  "constraints": [
    "数据范围：2020-2025",
    "标的：沪深300指数",
    "初始资金：100万"
  ],
  "state": "executing",           // exploring → planning → executing → reviewing → completed
  "phase": 3,                     // 当前四相阶段
  "created_at": "2026-05-14T08:00:00+08:00",
  "updated_at": "2026-05-14T08:15:00+08:00",
  "parent_task": null,            // 子任务指向父任务
  "tags": ["backtest", "strategy", "moving-average"],
  "confidence": 0.0               // 庞统对"需求理解程度"的自评
}
```

**moments.jsonl** — 原子事件流（每行一个 JSON）：
```json
{"type":"task_created","ts":"...","agent":"pangtong","data":{"goal":"..."}}
{"type":"requirement_clarified","ts":"...","agent":"pangtong","data":{"clarifications":[...]}}
{"type":"plan_generated","ts":"...","agent":"pangtong","data":{"plan_id":"p1","steps":5}}
{"type":"plan_approved","ts":"...","agent":"pangtong","data":{"approved_by":"user"}}
{"type":"agent_assigned","ts":"...","agent":"pangtong","data":{"agent":"zhaoyun","step":"s1"}}
{"type":"agent_started","ts":"...","agent":"zhaoyun","data":{"step":"s1"}}
{"type":"artifact_produced","ts":"...","agent":"zhaoyun","data":{"file":"data.csv","summary":"5年日线数据","confidence":0.95}}
{"type":"agent_completed","ts":"...","agent":"zhaoyun","data":{"step":"s1","status":"success"}}
{"type":"anomaly_detected","ts":"...","agent":"pangtong","data":{"type":"data_quality","severity":"warning"}}
{"type":"plan_adjusted","ts":"...","agent":"pangtong","data":{"reason":"数据质量问题","added_step":{...}}}
{"type":"consensus_reached","ts":"...","agent":"pangtong","data":{"result":"回测通过"}}
{"type":"task_completed","ts":"...","agent":"pangtong","data":{"final_state":"success"}}
```

**plan.json** — 动态计划图谱：
```json
{
  "plan_id": "p1",
  "task_id": "task-20260514-001",
  "version": 3,
  "steps": [
    {
      "id": "s1",
      "type": "data_fetch",
      "intent": "获取沪深300的5年日线数据",
      "end_state": "数据文件就绪，通过质量检查",
      "constraints": ["使用AKShare", "保存为CSV"],
      "agent": "zhaoyun",
      "status": "completed",
      "artifacts": ["data/hs300_daily.csv"],
      "started_at": "...",
      "completed_at": "...",
      "confidence": 0.95
    },
    {
      "id": "s2",
      "type": "strategy_implementation",
      "intent": "实现双均线交叉策略",
      "end_state": "策略代码可运行，通过单元测试",
      "constraints": ["使用vnpy框架", "参数可配置"],
      "agent": "zhangfei",
      "status": "executing",
      "depends": ["s1"],
      "started_at": "..."
    },
    {
      "id": "s2.5",
      "type": "data_cleaning",
      "intent": "清洗异常数据点",
      "end_state": "异常值处理完毕，数据连续无缺失",
      "agent": "zhaoyun",
      "status": "pending",
      "depends": [],
      "added_dynamically": true,
      "add_reason": "s1 完成后发现数据有缺失值"
    }
  ],
  "changelog": [
    {"version":1,"change":"初始计划","ts":"..."},
    {"version":2,"change":"添加 s2.5 数据清洗步骤","reason":"发现数据质量问题","ts":"..."},
    {"version":3,"change":"调整 s3 约束","reason":"用户要求改为vnpy框架","ts":"..."}
  ]
}
```

**agent-registry.json** — Agent 能力画像：
```json
{
  "agents": {
    "zhaoyun-data": {
      "name": "赵云",
      "role": "数据总管",
      "capabilities": ["data_fetch", "data_cleaning", "data_validation", "quality_check"],
      "tools": ["exec", "read", "write", "web_fetch"],
      "model_preference": "auto",
      "max_parallel_tasks": 1,
      "priority": 2,
      "performance": {
        "tasks_completed": 42,
        "avg_confidence": 0.91,
        "avg_duration_minutes": 8,
        "strengths": ["data_quality", "python"],
        "last_active": "..."
      },
      "session_key": "agent:zhaoyun-data:main"
    },
    "zhangfei-dev": {
      "name": "张飞",
      "role": "编码先锋",
      "capabilities": ["coding", "backtest", "strategy_implementation", "scripting"],
      "tools": ["exec", "read", "write", "edit"],
      "model_preference": "auto",
      "max_parallel_tasks": 1,
      "priority": 1,
      "performance": { ... },
      "session_key": "agent:zhangfei-dev:main"
    },
    "guanyu-dev": {
      "name": "关羽",
      "role": "风控守将",
      "capabilities": ["risk_check", "position_sizing", "stop_loss", "live_audit"],
      "tools": ["exec", "read", "write", "edit"],
      "model_preference": "auto",
      "max_parallel_tasks": 1,
      "priority": 3,    // 风控最高优先级
      "performance": { ... },
      "session_key": "agent:guanyu-dev:main"
    },
    "simayi-challenger": {
      "name": "司马懿",
      "role": "质量总监",
      "capabilities": ["code_review", "challenge", "final_acceptance"],
      "tools": ["exec", "read", "write", "edit"],
      "model_preference": "auto",
      "max_parallel_tasks": 1,
      "priority": 2,
      "performance": { ... },
      "session_key": "agent:simayi-challenger:main"
    },
    "jiangwei-infra": {
      "name": "姜维",
      "role": "平台总督",
      "capabilities": ["deployment", "docker", "nas", "backtest_server", "vnpy"],
      "tools": ["exec", "read", "write", "edit"],
      "model_preference": "auto",
      "max_parallel_tasks": 1,
      "priority": 1,
      "performance": { ... },
      "session_key": "agent:jiangwei-infra:main"
    }
  }
}
```

**decisions.jsonl** — 决策记录（不可变）：
```json
{"ts":"...","agent":"pangtong","decision":"assign_s2_to_zhangfei","reason":"张飞擅长策略编码","alternatives_considered":["关羽(风控优先)"]}
{"ts":"...","agent":"pangtong","decision":"add_s2.5","reason":"数据清洗步骤缺失","trigger":"s1 confidence=0.7 低于阈值"}
```

#### 2.1.3 写入保护：propose → validate → commit

借鉴 Network-AI 的三阶段原子写入：

```
Agent A:
  1. propose: 写入 agents/{agent-id}/proposed/{change-id}.json
     包含：target_path, proposed_content, priority, reason
     
Control Unit (庞统):
  2. validate: 
     a. 格式校验（JSON schema）
     b. 冲突检测（target 是否被其他 propose 锁定）
     c. 优先级检查（是否有更高优先级的 propose）
     d. 业务校验（状态流转是否合法）
     
  3. commit: 
     a. 获取文件锁 (locks/{resource}.lock)
     b. 原子写入（tmp → rename）
     c. 追加 Moment 事件
     d. 释放锁
     
  或 abort:
     a. 记录拒绝原因
     b. 通知提议 Agent
```

**简化规则**：
- Agent 对自己工作区（`agents/{agent-id}/`）的写入：**自动 commit**，不需要 propose
- Agent 对共享区域（`artifacts/`, `plan.json`, `context.json`）的写入：**必须 propose → commit**
- Agent 对其他 Agent 工作区的写入：**禁止**（覆盖保护原则）

#### 2.1.4 文件锁实现

借鉴 ClawTeam 的 fcntl + 原子 rename：

```python
import fcntl, tempfile, os
from pathlib import Path

def atomic_write(path: Path, content: str):
    """原子写入：先写临时文件，再 rename"""
    path.parent.mkdir(parents=True, exist_ok=True)
    fd, tmp = tempfile.mkstemp(dir=path.parent, prefix=f"{path.stem}-", suffix=".tmp")
    with os.fdopen(fd, 'w') as f:
        f.write(content)
    Path(tmp).replace(path)  # atomic on same filesystem

class BlackboardLock:
    """文件系统互斥锁"""
    def __init__(self, lock_dir: Path):
        self.lock_dir = lock_dir
    
    def acquire(self, resource: str, holder: str, timeout_ms=10000) -> bool:
        lock_path = self.lock_dir / f"{resource.replace('/', '_')}.lock"
        lock_path.parent.mkdir(parents=True, exist_ok=True)
        start = time.monotonic()
        while (time.monotonic() - start) * 1000 < timeout_ms:
            try:
                fd = os.open(str(lock_path), os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
                os.write(fd, json.dumps({"holder": holder, "acquired_at": time.time()}).encode())
                os.close(fd)
                return True
            except FileExistsError:
                # stale lock check (> 30s)
                age = time.time() - lock_path.stat().st_mtime
                if age > 30:
                    lock_path.unlink(missing_ok=True)
                time.sleep(0.1)
        return False
    
    def release(self, resource: str, holder: str):
        lock_path = self.lock_dir / f"{resource.replace('/', '_')}.lock"
        if lock_path.exists():
            data = json.loads(lock_path.read_text())
            if data.get("holder") == holder:
                lock_path.unlink()
```

---

### 2.2 Control Unit（庞统 AI 指挥官）

#### 2.2.1 四相循环

```
Phase 1: 需求探索
├── 苏格拉底对话，帮用户发现真实需求
├── 歧义评分（0-1），高歧义时深入追问
├── 输出：context.json（goal/intent/end_state/constraints）
├── 自评 confidence，>0.8 才进入 Phase 2
└── 人的参与：🔴 高（全程对话）

Phase 2: 动态规划
├── 根据 context.json 生成 plan.json
├── AI 挑战：庞统自己审视计划的弱点
├── 三方共识（可选）：庞统+司马懿+用户审核
├── Plan 审批：用户确认后才执行
├── 人的参与：🟡 可选（简单任务可跳过审批）
└── 输出：plan.json（version 1）

Phase 3: 自主执行
├── 按 plan.json 调度 Agent
├── 每步执行：
│   ├── 选择 Agent（能力画像匹配）
│   ├── 注入任务上下文（Fidelity 按角色）
│   ├── Agent 写入黑板
│   ├── 幻觉门控（验证产出存在）
│   ├── 异常检测（超时/质量低/Agent 崩溃）
│   └── 动态调整计划（如需）
├── /goal Ralph Loop：跨 turn 保持目标专注
├── 人的参与：🟢 几乎不参与（可随时介入 steer）
└── 输出：artifacts/ + moments 流

Phase 4: 主动汇报
├── AI 推送进展摘要（不等人查）
├── 验收：庞统自审 + 司马懿终审
├── 经验沉淀：提取关键经验写入 experience/
├── 人的参与：🔵 验收
└── 输出：最终报告 + experience 条目
```

#### 2.2.2 庞统的运行模式

**事件驱动 + 持久 session**：

```
庞统 session 始终在线（OpenClaw persistent session）

触发方式：
1. 用户发消息 → 直接在 session 中处理
2. Agent 写入黑板 → daemon 更新状态 → `openclaw agent` CLI 通知庞统
3. Agent 完成/失败 → 写入 moments → wake 庞统
4. 异常检测 → daemon 事件循环 → `openclaw agent` CLI 通知庞统
5. 用户 steer（中途干预）→ 直接注入 session

空闲时：
- 不消耗资源
- 被 wake 事件唤醒后立即恢复上下文
- 通过黑板恢复状态（不需要重载全部历史）
```

#### 2.2.3 信息路由（Fidelity 三档）

```python
def route_information(target_agent: str, task_ctx: dict, moments: list) -> dict:
    """根据目标 Agent 的角色，选择合适的信息保真度"""
    role = get_agent_role(target_agent)
    
    if role == "control_unit":  # 庞统自己
        return {
            "fidelity": "full",
            "context": task_ctx,
            "moments": moments,              # 全量事件
            "artifacts": all_artifacts,       # 全部产出物
            "agent_states": all_agent_states  # 所有Agent状态
        }
    
    elif role in get_collaborators(task_ctx):  # 同任务协作伙伴
        return {
            "fidelity": "summary",
            "context": task_ctx,              # 完整任务上下文
            "relevant_steps": filter_relevant(moments, target_agent),
            "artifacts": get_dependent_artifacts(target_agent),
            "summary": ai_summarize(moments)  # AI 压缩摘要
        }
    
    else:  # 外围 Agent
        return {
            "fidelity": "signal",
            "action_required": get_pending_actions(target_agent),
            "final_result": task_ctx.get("result"),
            "notification": True
        }
```

#### 2.2.4 Agent 选择算法

```python
def select_agent(step: dict, registry: dict) -> str:
    """根据步骤需求和Agent能力画像选择最合适的Agent"""
    required_caps = step.get("required_capabilities", infer_caps(step))
    
    candidates = []
    for agent_id, profile in registry["agents"].items():
        # 能力匹配
        cap_overlap = len(set(required_caps) & set(profile["capabilities"]))
        if cap_overlap == 0:
            continue
        
        # 可用性检查
        if profile["performance"]["tasks_in_progress"] >= profile["max_parallel_tasks"]:
            continue
        
        # 评分：能力匹配度 * 历史表现 * 当前空闲度
        score = (
            cap_overlap / len(required_caps) * 0.4 +          # 能力匹配
            profile["performance"]["avg_confidence"] * 0.3 +   # 历史表现
            (1 - profile["performance"]["tasks_in_progress"] / 
             profile["max_parallel_tasks"]) * 0.3              # 当前空闲度
        )
        candidates.append((agent_id, score))
    
    if not candidates:
        return None  # 需要排队或调整计划
    
    return max(candidates, key=lambda x: x[1])[0]
```

---

### 2.3 Agent 层

#### 2.3.1 Agent 工作流程

```
1. 接收任务
   ├── 庞统通过 daemon API 创建任务步骤
   ├── 消息包含：step intent + end_state + constraints + 相关黑板内容
   └── 不包含：完整计划、其他Agent的详情（Fidelity 控制）

2. 执行任务
   ├── 读取黑板中自己需要的上下文
   ├── 执行实际工作（编码/数据分析/风控检查等）
   ├── 写入产出到 agents/{agent-id}/output/
   └── 追加 Moments 事件

3. 提交产出
   ├── propose 共享产出物到 artifacts/
   ├── 庞统 validate + commit
   ├── 自评 [confidence: 0.X]
   └── 元认知：confidence < 0.6 时推荐人工审核

4. 等待下一步
   ├── 庞统根据执行结果决定下一步
   └── Agent 进入空闲状态
```

#### 2.3.2 Agent 行为注入

每个 Agent 的 SOUL.md / prompt 中注入**Boids 协作规则**：

```markdown
## 协作规则（Boids 群体智能）
1. **Separation（不重复）**：开始工作前检查黑板，确认没有其他 Agent 在做相同的事
2. **Alignment（风格一致）**：遵循团队的编码规范、产出格式、命名约定
3. **Cohesion（主动共享）**：发现重要信息时主动写入黑板共享区域
4. **Boundary（不越界）**：只在自己的工作区和共享区域操作，不修改其他 Agent 的产出
```

以及**元认知自评**：

```markdown
## 自评要求
完成任务后，标注置信度：
- `[confidence: 0.X]` 其中 X 为 0-10
- confidence < 0.6 时说明不确定之处并推荐人工审核
- 遇到专业外的问题主动上报，不硬撑
```

以及**Auftragstaktik 任务式指挥**：

```markdown
## 任务执行方式
你会收到：Intent（意图）、End State（终态）、Constraints（约束）
- 自主决定如何达成目标
- 可以选择任何合理的方法
- 但必须遵守所有 Constraints
- 遇到 Constraints 阻碍目标时，上报而不是绕过
```

---

### 2.4 事件系统

#### 2.4.1 Moments 事件类型

```python
class MomentType(str, Enum):
    # 任务生命周期
    TASK_CREATED = "task_created"
    REQUIREMENT_CLARIFIED = "requirement_clarified"
    TASK_COMPLETED = "task_completed"
    TASK_FAILED = "task_failed"
    
    # 计划
    PLAN_GENERATED = "plan_generated"
    PLAN_APPROVED = "plan_approved"
    PLAN_ADJUSTED = "plan_adjusted"
    
    # Agent 调度
    AGENT_ASSIGNED = "agent_assigned"
    AGENT_STARTED = "agent_started"
    AGENT_COMPLETED = "agent_completed"
    AGENT_FAILED = "agent_failed"
    AGENT_BLOCKED = "agent_blocked"
    
    # 产出
    ARTIFACT_PRODUCED = "artifact_produced"
    ARTIFACT_VALIDATED = "artifact_validated"
    
    # 决策
    DECISION_MADE = "decision_made"
    CHALLENGE_RAISED = "challenge_raised"
    CHALLENGE_VERDICT = "challenge_verdict"
    
    # 异常
    ANOMALY_DETECTED = "anomaly_detected"
    TIMEOUT_WARNING = "timeout_warning"
    
    # 用户交互
    USER_STEER = "user_steer"
    USER_APPROVED = "user_approved"
    USER_REJECTED = "user_rejected"
    
    # 经验
    EXPERIENCE_CAPTURED = "experience_captured"
```

#### 2.4.2 事件驱动唤醒

```python
# 庞统的唤醒条件
WAKE_CONDITIONS = {
    # 事件驱动：Agent 回报触发下一步
    "blackboard_change": {
        "trigger": "moments.jsonl 有新行",
        "action": "wake pangtong session",
        "context": "新增的 moments"
    },
    # Agent 完成
    "agent_completed": {
        "trigger": "agents/{id}/state.json status=completed",
        "action": "wake pangtong",
        "context": "agent_id + step_id"
    },
    # 超时检测
    "step_timeout": {
        "trigger": "step started_at + 30min < now",
        "action": "wake pangtong with alert",
        "context": "step_id + duration"
    },
    # 用户消息
    "user_message": {
        "trigger": "inbox/ 有新文件",
        "action": "wake pangtong",
        "context": "消息内容"
    }
}
```

---

### 2.5 经验沉淀系统

#### 2.5.1 闭环学习

```
DISCOVER（发现）
├── 任务执行过程中 Agent 发现好做法
├── 异常处理中发现新模式
└── 写入 blackboard/tasks/{id}/agents/{id}/discoveries.json

DISTILL（蒸馏）
├── 任务完成后庞统自动提取关键转折点
├── 从 decisions.jsonl + moments.jsonl 提炼经验
├── 压缩为经验条目：{pattern, context, outcome, applicability}
└── 写入 blackboard/global/experience/{domain}.jsonl

APPLY（应用）
├── 新任务开始时，庞统检索相关经验
├── 按任务类型+标签匹配
├── 注入 Agent prompt 作为参考
└── 标记"来自经验 X"

IMPROVE（改进）
├── 验证经验是否真的有效
├── 无效经验标记 deprecated
├── 有效经验提升 confidence
└── 定期合并相似经验
```

#### 2.5.2 经验数据结构

```json
{
  "id": "exp-001",
  "pattern": "数据清洗应在策略编码前完成",
  "context": "量化策略开发任务",
  "outcome": "减少返工率 40%",
  "applicability": ["backtest", "strategy_development"],
  "source_task": "task-20260514-001",
  "confidence": 0.85,
  "times_applied": 3,
  "times_validated": 2,
  "created_at": "...",
  "last_validated_at": "..."
}
```

---

### 2.6 监控与运维

#### 2.6.1 健康检查

```python
class HealthChecker:
    """定期检查黑板和 Agent 健康状态"""
    
    checks = [
        # Agent 存活检测
        "agent_heartbeat",      # 检查 state.json 更新时间
        "agent_zombie",         # 运行超过 2 小时的 Agent
        "agent_stale_lock",     # 超过 30 秒的锁
        
        # 任务健康
        "step_timeout",         # 步骤超时
        "plan_stuck",           # 计划卡住（所有 pending 步骤都有未完成的依赖）
        "artifact_missing",     # Agent 声称产出但文件不存在（幻觉门控）
        
        # 系统健康
        "blackboard_disk",      # 磁盘空间
        "moment_flood",         # 事件洪泛检测
    ]
```

#### 2.6.2 Token 成本治理

借鉴 Network-AI FederatedBudget + ClawTeam 成本追踪：

```python
class TokenBudget:
    """Token 预算管理"""
    
    def __init__(self):
        self.global_ceiling = 500_000      # 每任务全局上限
        self.per_agent_ceiling = 100_000   # 每 Agent 上限
        self.spent = {}                     # agent_id → tokens used
    
    def check(self, agent_id: str, estimated: int) -> bool:
        total = sum(self.spent.values())
        if total + estimated > self.global_ceiling:
            return False  # 全局预算不足
        if self.spent.get(agent_id, 0) + estimated > self.per_agent_ceiling:
            return False  # Agent 预算不足
        return True
```

---

## 3. 技术实现方案（v2.1 修订）

> ⚠️ v2.1 关键修正：
> - ❌ 废弃 sessions_send（不稳定、timeout）
> - ❌ 废弃 sessions_spawn（sub-agent 大爆炸、session 文件堆积）
> - ❌ 废弃 cron wake（不稳定）
> - ✅ 采用自建 Daemon HTTP API + SQLite（v1.0 已验证可靠）
> - ✅ Agent 复用主 session，通过 Daemon API 回报
> - ✅ 所有状态/流转/事件类型从配置文件加载，不硬编码

### 3.1 技术栈

| 层级 | 技术 | 说明 |
|------|------|------|
| 编排引擎 | **自建 Daemon** (FastAPI + uvicorn) | HTTP API + 事件循环，PM2 管理 |
| 数据存储 | **SQLite** (WAL mode) | 任务/计划/事件/Agent状态/经验 |
| 文件存储 | **文件系统** (artifacts) | 产出物（代码/数据/文档），git 可追踪 |
| Agent 运行时 | **OpenClaw Gateway** | Agent 的主 session 管理 |
| Agent 通信 | **Daemon HTTP API** | Agent 回报结果、查询黑板 |
| Agent 调度 | **`openclaw agent` CLI** | 发消息到 Agent 主 session（不创建 sub-agent） |
| 庞统通信 | **`openclaw agent` CLI** | Daemon → 庞统主 session 注入 systemEvent |
| 配置管理 | **YAML/JSON 配置文件** | 状态/流转/事件/模板全部配置化 |
| 文件锁 | **fcntl / O_EXCL** | 零依赖，跨进程安全 |
| 前端 | **OpenClaw Control Center** | 对话式入口（庞统主 session） |
| 经验检索 | **ripgrep + SQLite FTS** | 文本搜索 |
| 同步 | **sanguo_git_sync** | 已有的三端 Git 同步 |

### 3.2 为什么不用 OpenClaw 原生调度？

| 方案 | 问题 | 结论 |
|------|------|------|
| sessions_send | 不稳定，经常 timeout | ❌ 废弃 |
| cron wake | 各种问题，不可靠 | ❌ 废弃 |
| sessions_spawn | 每次创建新 session，文件堆积（庞统 296个/354MB），sub-agent 缺少 SOUL.md | ❌ 废弃 |
| **自建 Daemon HTTP API** | v1.0 已验证（FastAPI + SQLite + PM2），可靠 | ✅ 采用 |

### 3.3 Agent 调度方式：主 session + HTTP 回报

**核心原则：不创建 sub-agent，复用 Agent 主 session。**

```
Daemon 需要调度张飞执行编码任务：

1. Daemon 通过 `openclaw agent` CLI 发消息到 agent:zhangfei-dev:main
   - 消息内容：step intent + end_state + constraints
   - 张飞在自己的主 session 里收到消息

2. 张飞执行任务
   - 读取 daemon API 获取需要的上下文
   - 在自己的 workspace 里工作

3. 张飞通过 daemon HTTP API 回报结果
   - curl POST http://localhost:8080/api/step/{id}/complete
   - body: { artifacts: [...], confidence: 0.9, summary: "..." }
   - daemon 做幻觉门控（验证文件存在）
   - daemon 更新 SQLite 状态
   - daemon 触发下一步

4. daemon 调 `openclaw agent` CLI 通知庞统进展
   - 庞统在主 session 收到 systemEvent
   - 庞统决定下一步操作
```

**为什么不用 sub-agent？**
- 每个 sub-agent 产生 3-5 个磁盘文件（.jsonl + .trajectory + .path）
- 庞统已有 296 个 session 文件 354MB，姜维 227 个 1.4GB
- sub-agent 没有 SOUL.md/IDENTITY.md，行为不够可控
- cleanup: delete 只是从 UI 隐藏，文件仍然在磁盘上

**主 session 的上下文膨胀怎么办？**
- Agent 每完成一个任务步骤后，daemon 发 systemEvent 触发 reset
- OpenClaw 的 reset 会压缩历史，释放上下文空间
- 或者：每 N 个步骤后自动 reset 一次

### 3.4 用户查看进展的流程

```
用户: "任务进展如何？"
  │
  ▼
庞统主 session 收到消息
  │
  ▼
庞统调用 Daemon API:
  GET http://localhost:8080/api/task/{task_id}/status
  │
  ▼
Daemon 返回:
  {
    "task": { "title": "...", "state": "executing", "phase": 3 },
    "plan": { "steps": [...], "completed": 3, "total": 5 },
    "current_step": {
      "agent": "zhangfei",
      "status": "executing",
      "started_at": "...",
      "progress": "正在编码策略逻辑"
    },
    "recent_moments": [
      { "type": "agent_completed", "agent": "zhaoyun", "summary": "数据获取完成" },
      { "type": "plan_adjusted", "reason": "发现数据质量问题" }
    ],
    "anomalies": [],
    "token_budget": { "used": 120000, "total": 500000 }
  }
  │
  ▼
庞统用 AI 生成人类可读的进展汇报，回复用户
```

**关键设计：庞统是无状态的**
- 所有任务状态在 Daemon 的 SQLite 里
- 庞统 session 不保存任务状态
- 每次被问到进展，实时查询 Daemon API
- 这比 v1.0 好：v1.0 庞统需要在 session 里记住所有任务，上下文很快就爆了

### 3.5 配置化（零硬编码）

```
config/
├── states.yaml              # 任务状态定义 + 合法流转
├── step-states.yaml         # 步骤状态定义 + 合法流转
├── events.yaml              # 事件类型定义
├── agent-registry.json      # Agent 能力画像
├── templates/               # 任务模板
│   ├── backtest.yaml
│   ├── strategy-research.yaml
│   └── deployment.yaml
└── settings.yaml            # 全局设置
```

**states.yaml**:
```yaml
# 任务级状态定义（v2.0）
# 基于 v1.0 state_machine.py 的成熟经验，新增 AI native 场景
# Daemon 启动时加载，代码里不允许出现硬编码的状态名

# ── 终态（不可变）──
terminal_states: [completed]

# ── 任务状态 ──
states:
  # === Phase 1: 需求探索 ===
  - name: exploring
    description: "AI 与用户需求探索中"
    phase: 1
    type: active
    transitions_to: [planning, cancelled]
    user_actions: [cancel, steer, takeover]
    auto_triggers:
      - trigger: confidence >= 0.8
        to: planning
        description: "AI 判断需求已足够清晰"

  # === Phase 2: 动态规划 ===
  - name: planning
    description: "AI 生成/调整执行计划"
    phase: 2
    type: active
    transitions_to: [executing, planning, paused, cancelled]
    user_actions: [cancel, pause, steer, approve, reject]
    auto_triggers:
      - trigger: plan_approved
        to: executing
        description: "计划被批准（用户或 AI 自动）"
      - trigger: plan_revise
        to: planning  # 自转换
        description: "challenge 驳回，修订计划"

  # === Phase 3: 自主执行 ===
  - name: executing
    description: "Agent 自主执行中"
    phase: 3
    type: active
    transitions_to: [reviewing, paused, escalated, failed, executing, cancelled]
    user_actions: [cancel, pause, steer, takeover, intervene]
    auto_triggers:
      - trigger: all_steps_done
        to: reviewing
        description: "所有步骤完成"
      - trigger: critical_step_failed
        to: escalated
        description: "关键步骤失败，需人工"

  # === Phase 3.5: 执行中暂停 ===
  - name: paused
    description: "用户暂停，等待恢复"
    phase: 3
    type: active
    transitions_to: [executing, planning, cancelled]
    user_actions: [cancel, resume, replan]
    auto_triggers:
      - trigger: resume
        to: executing
        description: "用户恢复"
      - trigger: goal_changed
        to: planning
        description: "用户改需求，重新规划"

  # === 人工介入 ===
  - name: escalated
    description: "AI 主动升级，需要用户决策"
    phase: 3
    type: active
    transitions_to: [executing, planning, cancelled]
    user_actions: [cancel, rollback, replan]
    auto_triggers:
      - trigger: user_decision
        to: executing
        description: "用户给出决策，继续执行"
      - trigger: goal_changed
        to: planning
        description: "用户决定改需求"

  # === Phase 4: 验收 ===
  - name: reviewing
    description: "AI 向用户汇报，等待验收"
    phase: 4
    type: active
    transitions_to: [completed, executing, cancelled]
    user_actions: [accept, reject, cancel, steer]
    auto_triggers:
      - trigger: user_accept
        to: completed
        description: "用户验收通过"
      - trigger: user_reject
        to: executing
        description: "用户不满意，继续执行"

  # === 终态 ===
  - name: completed
    description: "任务完成"
    phase: 4
    type: terminal
    transitions_to: []

  - name: cancelled
    description: "已取消（可 resume 重新激活）"
    phase: null
    type: normal  # 非终态，可恢复
    transitions_to: [executing]
    user_actions: [resume]

  - name: failed
    description: "任务失败（可 retry/escalate）"
    phase: null
    type: normal
    transitions_to: [executing, escalated, cancelled]
    user_actions: [retry, escalate, cancel]

# ── 用户动作定义（AI native 扩展）──
user_actions:
  cancel:
    description: "取消任务"
    available_from: "任何非终态"
  pause:
    description: "暂停，冻结所有执行"
    available_from: [planning, executing]
  resume:
    description: "恢复执行"
    available_from: [paused, cancelled]
  steer:
    description: "用户中途改方向（不改 goal，只调整执行策略）"
    available_from: [exploring, planning, executing, reviewing]
    ai_native: true  # v2.0 新增：用户在对话中说“改成MACD”即触发
  takeover:
    description: "用户接管某个步骤"
    available_from: [executing, escalated]
    ai_native: true  # v2.0 新增：用户说“这部分我来”
  intervene:
    description: "用户主动干预（查看/修改产出物）"
    available_from: [executing]
    ai_native: true  # v2.0 新增：用户随时可以介入
  approve:
    description: "批准计划"
    available_from: [planning]
  reject:
    description: "驳回计划"
    available_from: [planning, reviewing]
  replan:
    description: "重新规划"
    available_from: [paused, escalated]
    ai_native: true
  accept:
    description: "验收通过"
    available_from: [reviewing]
  retry:
    description: "失败后重试"
    available_from: [failed]
  escalate:
    description: "升级到人工"
    available_from: [failed]
  rollback:
    description: "回滚到执行态"
    available_from: [escalated]
```

**step-states.yaml**:
```yaml
# 步骤级状态定义（v2.0）
# 基于 v1.0 NODE_STATES 成熟经验

step_states:
  - name: pending
    description: "待分配"
    transitions_to: [assigned, cancelled]

  - name: assigned
    description: "已分配 Agent"
    transitions_to: [executing, cancelled]

  - name: executing
    description: "Agent 执行中"
    transitions_to: [completed, failed, blocked, reviewing, waiting_human, cancelled]
    # reviewing: 执行完进入审查（v1.0 challenge 机制）
    # waiting_human: Agent 请求人工确认

  - name: reviewing
    description: "产出审查中（challenge）"
    transitions_to: [completed, pending, failed, escalated]
    # v1.0 挑战循环：pass → completed, iterate → pending, fail → failed

  - name: blocked
    description: "被阻塞"
    transitions_to: [pending, failed, cancelled]
    max_retries: 3

  - name: waiting_human
    description: "等待人工确认（Checkpoint）"
    transitions_to: [executing, completed, cancelled]
    # v2.0: AI 主动请求用户确认关键产出

  - name: completed
    description: "完成"
    transitions_to: []
    type: terminal

  - name: failed
    description: "失败（可重试）"
    transitions_to: [pending, escalated, cancelled]
    max_retries: 3

  - name: escalated
    description: "升级到人工"
    transitions_to: [executing, pending, cancelled]

  - name: cancelled
    description: "已取消"
    transitions_to: []
    type: terminal

# ── 步骤执行方式 ──
execution_modes:
  - name: sub_agent
    description: "创建 isolated sub-agent 执行（sessions_spawn）"
    when: "复杂任务（编码、文档、调研）"
    cleanup: "delete"
    archive_transcript_to: "artifacts/task-{id}/steps/{step_id}/"

  - name: main_session
    description: "在 Agent 主 session 中执行"
    when: "简单任务（数据获取、文件操作）"
    record_to: "artifacts/task-{id}/steps/{step_id}/transcript.jsonl"

  - name: human
    description: "用户自己执行"
    when: "用户说'这部分我来'"
    trigger: "takeover"
```

**代码中禁止出现硬编码状态名**：
```python
# ❌ 禁止
if task.state == "executing":

# ✅ 正确
EXECUTING = config.get_state("executing")
if task.state == EXECUTING:
```

### 3.6 核心代码模块

```
sanguo_moziplus_v2/
├── daemon/                        # 守护进程
│   ├── main.py                    # FastAPI 入口
│   ├── api/                       # HTTP API 路由
│   │   ├── tasks.py               # 任务 CRUD
│   │   ├── steps.py               # 步骤 CRUD + 回报
│   │   ├── board.py               # 黑板查询
│   │   ├── moments.py             # 事件查询
│   │   └── agents.py              # Agent 状态/心跳
│   ├── engine/                    # 编排引擎
│   │   ├── orchestrator.py        # 编排主循环（事件驱动）
│   │   ├── planner.py             # 动态规划
│   │   ├── selector.py            # Agent 选择
│   │   ├── validator.py           # 产出验证（幻觉门控）
│   │   ├── archiver.py            # 执行历史归档
│   │   └── experience.py          # 经验沉淀引擎
│   ├── cli_client.py             # openclaw agent CLI 调用封装
│   ├── db.py                      # SQLite 数据层
│   ├── lock.py                    # 文件锁实现
│   ├── health.py                  # 健康检查（daemon 内部定时）
│   ├── budget.py                  # Token 预算管理
│   └── config_loader.py           # YAML/JSON 配置加载
├── config/                        # 配置文件
│   ├── states.yaml
│   ├── step-states.yaml
│   ├── events.yaml
│   ├── agent-registry.json
│   ├── templates/
│   └── settings.yaml
├── artifacts/                     # 产出物 + 执行历史（git 追踪）
│   └── task-{id}/                 # 每个任务一个目录
│       ├── context.json           # 任务上下文
│       ├── plan.json              # 执行计划
│       ├── steps/                 # 各步骤产出
│       │   ├── s1/
│       │   │   ├── output.json    # 步骤产出元数据
│       │   │   ├── transcript.jsonl  # 执行历史（从 OpenClaw 归档）
│       │   │   └── ...             # 实际产出文件
│       │   └── s2/
│       ├── moments.jsonl           # 关键事件流
│       └── experience.md           # 提取的经验教训
├── skills/                        # Skill 包（供 Agent 加载）
│   ├── task-bootstrap/            # Agent 任务引导 Skill
│   │   └── SKILL.md               # Boids + 元认知 + Auftragstaktik
│   └── wiki-query/                # 复用已有
├── docs/
│   ├── design/
│   └── research/
├── scripts/
│   ├── create-task.sh             # CLI: 创建任务
│   ├── status.sh                  # CLI: 查看状态
│   └── bootstrap.sh               # 初始化脚本
└── README.md
```

### 3.6.1 执行历史归档机制

**目标**：每个步骤的完整执行过程都归档到任务目录，可追溯、可检索、可提炼经验。

```
执行流程：

1. Daemon 调度 Agent 执行步骤（sub-agent 或主 session）
2. Agent 执行完毕，回报结果
3. Daemon archiver 做以下事情：
   a. 读取 OpenClaw session transcript（.jsonl 文件）
   b. 提取与该步骤相关的部分（按时间范围裁剪）
   c. 写入 artifacts/task-{id}/steps/{step_id}/transcript.jsonl
   d. 如果是 sub-agent，transcript 包含完整对话历史
   e. 如果是主 session，只裁剪该步骤执行期间的对话
4. 经验沉淀时，读取 transcript.jsonl 做 AI 分析
```

**transcript.jsonl 包含什么**：
- user 消息（用户的指令/反馈）
- assistant 消息（Agent 的回复/决策）
- tool 调用及结果（执行的命令、文件操作、API 调用）
- token 消耗统计
- 错误和异常信息

**价值**：
- 🔍 可追溯：每个步骤的每个决策都有据可查
- 📚 可学习：经验提取时能看完整上下文，不只是结论
- 🐛 可复盘：坑和踩坑过程一目了然
- 🧹 可清理：归档后 OpenClaw 原始 session 文件可以安全删除

### 3.6.2 Agent 调度混合方案

简单步骤用主 session，复杂步骤用 sub-agent：

| 步骤类型 | 调度方式 | 原因 |
|---------|---------|------|
| 数据获取/文件操作 | 主 session + Gateway 发消息 | 简单快速，不需要隔离 |
| 编码/文档/调研 | sessions_spawn + cleanup=delete | 复杂任务需要隔离，防上下文污染 |
| 用户自己执行 | takeover，不调度 | 用户说"这部分我来" |

sub-agent 完成后，archiver 自动把 transcript 归档到任务目录。

### 3.7 关键交互流程

#### 流程 1：完整任务生命周期

```
用户: "帮我做一个均线策略回测"
  │
  ▼
庞统 Phase 1（需求探索）
  ├── 苏格拉底对话 2-3 轮
  ├── 澄清：标的？周期？资金？评价指标？
  ├── 写入 context.json，confidence=0.9
  └── 转入 Phase 2
  │
  ▼
庞统 Phase 2（动态规划）
  ├── 检索经验库 → 找到"数据清洗应先于策略编码"
  ├── 生成 plan.json（5步）
  ├── 用户确认（或跳过）
  └── 转入 Phase 3
  │
  ▼
庞统 Phase 3（自主执行）
  │
  ├── Step s1: 数据获取 → 选择赵云（data_fetch 能力）
  │   ├── `openclaw agent` CLI 调度赵云
  │   ├── 赵云执行，写入 output/hs300_daily.csv
  │   ├── 赵云 propose → 庞统 validate → commit
  │   ├── 幻觉门控：文件存在？大小合理？ ✓
  │   └── confidence=0.95 ✓
  │
  ├── 发现：数据有缺失值（anomaly_detected）
  │   └── 庞统动态添加 s1.5 数据清洗步骤
  │
  ├── Step s1.5: 数据清洗 → 选择赵云
  │   └── ... 执行并完成
  │
  ├── Step s2: 策略编码 → 选择张飞
  │   └── ... 执行并完成
  │
  ├── Step s3: 风控审查 → 选择关羽
  │   └── ... 执行并完成
  │
  ├── Step s4: 质量评审 → 选择司马懿
  │   ├── 司马懿发现问题 → challenge_raised
  │   ├── 庞统裁决 → 要求张飞修正
  │   ├── 张飞修正 → 重新评审
  │   └── 司马懿通过 ✓
  │
  └── 转入 Phase 4
  │
  ▼
庞统 Phase 4（主动汇报）
  ├── 生成最终报告
  ├── 经验沉淀：提取 3 条经验写入 experience/
  ├── 向用户推送完成通知
  └── 用户验收
```

#### 流程 2：异常处理

```
场景：赵云执行超时

1. health scanner 检测到 zhaoyun state.json 30分钟未更新
2. daemon 事件循环检测到超时，通知庞统
3. 庞统：
   a. 检查赵云 session 是否存活（sessions_list）
   b. 存活 → `openclaw agent --agent zhaoyun` 询问进度
   c. 不存活 → 标记 s1 为 failed，重新分配给其他 Agent 或调整计划
   d. 记录 decision: "赵云超时，重新分配"
4. 追加 Moment: agent_failed + decision_made
```

#### 流程 3：用户中途干预

```
场景：执行到 s2 时用户说"改成 MACD 策略"

1. 用户消息注入庞统 session
2. 庞统：
   a. 暂停当前执行（通知张飞停止）
   b. 修改 context.json（goal 改为 MACD 策略）
   c. 重新规划 plan.json（s2 需要修改）
   d. 向用户确认修改方案
   e. 用户确认后继续执行
3. 追加 Moment: user_steer + plan_adjusted
```

### 3.8 与 OpenClaw 的集成点（v2.3 修正）

> ⚠️ v2.3 关键修正（司马懿第二轮评审反馈）：
> - ❌ 废弃自建 Gateway WS Client（不稳定、需维护长连接）
> - ✅ 改用 `openclaw agent` CLI 命令（Gateway 原生、有超时和 fallback、零连接管理）
> - ✅ 全程推送式事件链路，零轮询零 cron

| v2.0 功能 | 实现方式 | 说明 |
|-----------|---------|------|
| 庞统对话 | 庞统主 session (webchat) | 用户通过 Control Center 对话 |
| 庞统查进展 | curl GET daemon API | 实时查询 SQLite，AI 生成汇报 |
| 庞统操作任务 | curl POST daemon API | 创建/规划/启动/暂停/恢复任务 |
| **Daemon 调度 Agent** | **`openclaw agent` CLI** | daemon 调用 CLI 发消息到 Agent 主 session |
| Agent 调度(复杂) | sessions_spawn + cleanup=delete | 复杂步骤用 sub-agent 隔离 |
| Agent 回报 | curl POST daemon API | 完成/失败/进度上报 |
| Agent 查黑板 | curl GET daemon API | 查询任务上下文/计划/产出物 |
| **Daemon 通知庞统** | **`openclaw agent` CLI** | daemon 调用 CLI 注入消息到庞统 session |
| Agent 上下文管理 | Gateway reset | 定期 reset Agent 主 session 防止膨胀 |
| 知识检索 | wiki-query skill (Agent 侧) | Agent 需要时可调用 |
| 数据持久化 | SQLite (daemon) + 文件系统 (artifacts) | 状态在 SQLite，产出物在文件系统 |
| 执行历史归档 | daemon archiver | 归档后物理删除原始 session 文件 |

#### 3.8.1 Agent 调度的具体实现

```bash
# Daemon 调度 Agent（简单步骤：主 session）
openclaw agent --agent zhangfei-dev \
  --message "执行步骤 s2: 编码均线策略逻辑。上下文见 http://localhost:8080/api/steps/s2" \
  --json

# Daemon 通知庞统
openclaw agent --agent pangtong-fujunshi \
  --message "[systemEvent] 步骤 s1 完成，zhaoyun 回报：数据获取成功" \
  --json
```

**并行调度**：daemon 用 `subprocess.Popen` 异步启动多个 `openclaw agent` 命令，poll 等待结果。

**事件传播链（全程推送，零轮询）**：
```
Agent 完成任务
  → curl POST http://localhost:8080/api/steps/{id}/complete（回报 daemon）
  → daemon 更新 SQLite + 验证产出
  → daemon 调 openclaw agent --agent pangtong-fujunshi（通知庞统）
  → 庞统收到消息，决定下一步
  → daemon 调 openclaw agent --agent zhangfei-dev（调度下一个 Agent）
```

#### 3.8.2 庞统上下文恢复协议

庞统是"无任务状态"的（状态在 daemon SQLite），但需要"推理上下文"。
庞统每次被 daemon 通知时，第一步总是 `GET /api/tasks/{id}/status` 重建认知。

#### 3.8.3 Agent 任务消息模板

Daemon 调度 Agent 时发送的标准消息格式：

```
[moziplus v2] 任务步骤分配

任务: {task_title}
步骤: {step_id} - {step_title}
目标: {step_intent}
预期产出: {step_end_state}

上下文获取:
  任务状态: curl http://localhost:8080/api/tasks/{task_id}
  步骤详情: curl http://localhost:8080/api/steps/{step_id}
  前序产出: curl http://localhost:8080/api/steps/{prev_step_id}/output

约束:
  产出物必须写到 artifacts/task-{task_id}/steps/{step_id}/ 目录
  完成后回报: curl -X POST http://localhost:8080/api/steps/{step_id}/complete
  失败回报: curl -X POST http://localhost:8080/api/steps/{step_id}/fail
``` |

---

### 3.9 共享意识空间物理结构

> "可预测骨架 + AI 动态填充" 的物理载体。
> SQLite 存状态（查询快、事务安全），文件系统存内容（代码/数据/文档，git 可追踪）。
> 同一信息只存在一个地方，不重复。

#### 3.9.1 SQLite 表结构

```sql
-- 任务表
CREATE TABLE tasks (
    id TEXT PRIMARY KEY,               -- UUID
    title TEXT NOT NULL,
    goal TEXT NOT NULL,                 -- 用户原始需求
    state TEXT NOT NULL DEFAULT 'exploring',
    phase INTEGER NOT NULL DEFAULT 1,  -- 1=探索, 2=规划, 3=执行, 4=验收
    context_json TEXT,                  -- {goal, constraints, clarifications, confidence}
    plan_json TEXT,                     -- {steps: [{id, title, intent, agent_hint, depends_on}]}
    created_at TEXT NOT NULL,
    updated_at TEXT NOT NULL,
    created_by TEXT DEFAULT 'user',     -- user | pangtong
    token_budget_used INTEGER DEFAULT 0,
    token_budget_limit INTEGER DEFAULT 500000
);

-- 步骤表
CREATE TABLE steps (
    id TEXT PRIMARY KEY,               -- "{task_id}-s{seq}"
    task_id TEXT NOT NULL REFERENCES tasks(id),
    seq INTEGER NOT NULL,
    title TEXT NOT NULL,
    intent TEXT NOT NULL,               -- 步骤目标（给 Agent 的指令）
    end_state TEXT,                     -- Agent 应该达到的产出状态
    state TEXT NOT NULL DEFAULT 'pending',
    assigned_agent TEXT,                -- agent-id 或 null（待分配）
    execution_mode TEXT DEFAULT 'sub_agent',  -- sub_agent | main_session | human
    depends_on TEXT,                    -- JSON array of step_ids
    output_json TEXT,                   -- {artifacts: [...], confidence, summary}
    started_at TEXT,
    completed_at TEXT,
    retry_count INTEGER DEFAULT 0,
    max_retries INTEGER DEFAULT 3
);

-- 事件流（Moments）
CREATE TABLE moments (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    task_id TEXT NOT NULL REFERENCES tasks(id),
    step_id TEXT,                       -- nullable（任务级事件没有 step_id）
    type TEXT NOT NULL,                 -- 事件类型（从 events.yaml 加载）
    agent TEXT,                         -- 触发 Agent
    data_json TEXT NOT NULL,            -- 事件详情
    created_at TEXT NOT NULL DEFAULT (datetime('now'))
);
CREATE INDEX idx_moments_task ON moments(task_id, created_at);

-- Agent 状态（心跳）
CREATE TABLE agent_status (
    agent_id TEXT PRIMARY KEY,
    status TEXT NOT NULL DEFAULT 'idle',  -- idle | busy | offline
    current_task_id TEXT,
    current_step_id TEXT,
    last_heartbeat TEXT,
    capabilities TEXT                    -- JSON array（从 agent-registry.json 加载）
);

-- AI 决策记录（可追溯）
CREATE TABLE decisions (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    task_id TEXT NOT NULL REFERENCES tasks(id),
    step_id TEXT,
    decision_type TEXT NOT NULL,        -- agent_selected | plan_adjusted | anomaly_handled | escalated
    reasoning TEXT NOT NULL,             -- AI 的思考过程
    outcome TEXT NOT NULL,               -- 决策结果
    model TEXT,                          -- 使用的模型
    token_cost INTEGER,
    created_at TEXT NOT NULL DEFAULT (datetime('now'))
);

-- 经验库
CREATE TABLE experiences (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    source_task_id TEXT NOT NULL,
    source_step_id TEXT,
    category TEXT NOT NULL,              -- pattern | pitfall | best_practice | tool_usage
    title TEXT NOT NULL,
    content TEXT NOT NULL,               -- Markdown 格式
    tags TEXT,                           -- JSON array
    relevance_score REAL DEFAULT 0.5,
    created_at TEXT NOT NULL DEFAULT (datetime('now'))
);
```

#### 3.9.2 文件系统结构

```
sanguo_moziplus_v2/
└── artifacts/
    └── task-{uuid}/
        ├── context.json                # 任务上下文（冗余 SQLite 的 context_json，供 Agent 直接 read）
        │   # {goal, constraints, clarifications, confidence, phase_history}
        │
        ├── plan.json                   # 执行计划（冗余 SQLite 的 plan_json，供 Agent 直接 read）
        │   # {steps: [{id, title, intent, end_state, assigned_agent, depends_on, state}]}
        │
        ├── steps/                      # 各步骤产出物
        │   ├── s1/
        │   │   ├── output.json         # {artifacts: [{path, type, size}], confidence, summary, duration_s}
        │   │   ├── transcript.jsonl     # 执行历史归档（从 OpenClaw session transcript 复制）
        │   │   ├── hs300_daily.csv      # ← 实际产出文件（Agent 直接写到这里）
        │   │   └── data_quality.json    # ← 数据质量报告
        │   ├── s2/
        │   │   ├── output.json
        │   │   ├── transcript.jsonl
        │   │   ├── strategy.py         # ← 策略代码
        │   │   └── backtest_result.json
        │   └── s3/
        │       └── ...
        │
        ├── observations/                # Agent 主动观察与建议（v2.4 新增）
        │   # Agent 执行中发现的异常、建议、洞察
        │   # 其他 Agent 和庞统可直接 read 获取
        │   ├── zhaoyun-001.md           # "数据有缺失值，建议加清洗步骤"
        │   ├── zhangfei-001.md          # "建议用 MACD 替代均线"
        │   └── ...
        │
        ├── status.json                  # 全局状态摘要（v2.4 新增，daemon 实时维护）
        │   # {phase, steps: {s1: {state, agent}, ...}, anomalies, observations}
        │   # Agent 执行前第一步 read 此文件获取全局视野
        │
        ├── moments.jsonl               # 原子事件流（冗余 SQLite moments 表，追加写入）
        │   # 每行: {"type":"step_completed","ts":"...","agent":"zhaoyun","data":{...}}
        │
        ├── decisions.jsonl             # AI 决策记录（冗余 SQLite decisions 表）
        │   # 每行: {"type":"agent_selected","ts":"...","reasoning":"...","outcome":"zhangfei"}
        │
        └── experience.md               # 任务完成后 AI 提取的经验（Markdown）
```

**为什么 SQLite 和文件都有？**
- **SQLite**：给 daemon 内部用（查询、事务、索引、复杂条件筛选）
- **文件系统**：给 Agent 用（`read` 工具直接读，Agent 不能访问 daemon 的 SQLite）
- 两者通过 daemon API 同步，SQLite 是权威源，文件是缓存/视图

#### 3.9.3 产出物门控（Gating）设计

> 参考 OpenAI Codex Cookbook 的 gating check："Do not advance until required files are present"

```
步骤完成回报 POST /api/steps/{id}/complete
  │
  ▼
Daemon validator 做三层检查：
  1. 文件存在性检查
     - output_json 中声明的每个 artifact.path 都必须存在
     - ls -la 验证
  2. 内容完整性检查
     - 文件大小 > 0（空文件不算）
     - 文件大小在合理范围内（非异常值）
     - 如果是 JSON/CSV，验证 schema/parsing
  3. 语义检查（可选，消耗 token）
     - AI 检查产出物是否与 end_state 描述匹配
     - 只在 confidence < 0.7 时触发
  │
  ▼
三层全过 → 同一事务内：
  - UPDATE steps SET state='completed'
  - INSERT INTO moments (type='step_completed')
  - INSERT INTO moments (type='validation_passed')
任何一层失败 → 回报 validation_failed，步骤保持 executing
```

---

### 3.10 Daemon API 接口定义

> RESTful + JSON，端口 8080（沿用 v1.0）。
> 所有请求/响应都记录到 moments 表。

#### 3.10.0 API 设计原则（调研审视）

| 原则 | 来源 | 实现方式 |
|------|------|----------|
| **幂等性** | Wanman JSON-RPC | 所有写操作可安全重试，重复回报不产生副作用 |
| **标准错误码** | Wanman JSON-RPC | 统一错误格式 `{ok: false, error: {code, message}}` |
| **事务保护** | Edict Outbox | 关键写操作（步骤完成）原子化：产出验证 + 状态更新 + 事件记录同一事务 |
| **版本化** | Gstack | API 版本号前缀 `/api/v1/...`，未来升级不破坏兼容性 |
| **Agent 零SDK** | Wanman CLI | Agent 只需 curl，不需要任何 SDK |

#### 3.10.1 任务生命周期 API

```
POST   /api/tasks                          # 创建任务
GET    /api/tasks/{id}                      # 查询任务状态
GET    /api/tasks/{id}/status               # 轻量状态查询（给庞统用）
PUT    /api/tasks/{id}/context              # 更新任务上下文
POST   /api/tasks/{id}/plan                 # 提交执行计划
POST   /api/tasks/{id}/start                # 启动执行（Phase 3）
POST   /api/tasks/{id}/pause                # 暂停
POST   /api/tasks/{id}/resume               # 恢复
POST   /api/tasks/{id}/cancel               # 取消
POST   /api/tasks/{id}/replan               # 重新规划（用户改需求或异常调整）
GET    /api/tasks/{id}/moments               # 查询事件流
GET    /api/tasks/{id}/decisions             # 查询决策记录
```

**POST /api/tasks** — 创建任务
```json
// Request
{
  "title": "均线策略回测",
  "goal": "对沪深300做双均线交叉策略回测",
  "constraints": ["5年日线数据", "滑点0.2%"],
  "metadata": {}  // 可选
}
// Response
{
  "ok": true,
  "task_id": "t-uuid-001",
  "state": "exploring"
}
```

**GET /api/tasks/{id}/status** — 轻量状态查询（庞统用，返回人类可读摘要）
```json
{
  "task": { "title": "均线策略回测", "state": "executing", "phase": 3 },
  "plan": {
    "steps": [
      { "id": "s1", "title": "数据获取", "state": "completed", "agent": "zhaoyun" },
      { "id": "s2", "title": "策略编码", "state": "executing", "agent": "zhangfei" }
    ],
    "completed": 1, "total": 4
  },
  "current_step": {
    "id": "s2", "agent": "zhangfei", "started_at": "...",
    "progress": null  // Agent 可选上报进度
  },
  "recent_moments": [
    { "type": "step_completed", "agent": "zhaoyun", "summary": "数据获取完成" }
  ],
  "anomalies": [],
  "token_budget": { "used": 120000, "limit": 500000 }
}
```

#### 3.10.2 步骤执行 API

```
POST   /api/steps/{id}/assign              # 分配 Agent
POST   /api/steps/{id}/start                # 标记开始执行
POST   /api/steps/{id}/complete             # Agent 回报完成
POST   /api/steps/{id}/fail                 # Agent 回报失败
POST   /api/steps/{id}/block                # Agent 回报阻塞
POST   /api/steps/{id}/progress             # Agent 上报进度（可选）
POST   /api/steps/{id}/escalate             # Agent 请求人工介入
GET    /api/steps/{id}                       # 查询步骤详情
GET    /api/steps/{id}/output                # 查询步骤产出
```

**POST /api/steps/{id}/complete** — Agent 回报完成
```json
// Request
{
  "artifacts": [
    { "path": "artifacts/task-xxx/steps/s1/hs300_daily.csv", "type": "data", "size_bytes": 1048576 }
  ],
  "confidence": 0.95,
  "summary": "获取沪深300 5年日线数据，共1218条记录，含缺失值处理报告"
}
// Response
{
  "ok": true,
  "state": "completed",
  "validation": {
    "files_exist": true,
    "sizes_reasonable": true,
    "passed": true
  }
}
```

**POST /api/steps/{id}/fail** — Agent 回报失败
```json
// Request
{
  "error": "数据源返回403，权限不足",
  "retry_suggested": true,
  "partial_artifacts": []
}
```

#### 3.10.3 查询 & 管理API

```
GET    /api/agents                          # 所有 Agent 状态
GET    /api/agents/{id}/status               # 单个 Agent 状态
POST   /api/agents/{id}/heartbeat            # Agent 心跳

GET    /api/experiences                      # 经验检索（给 AI 用）
POST   /api/experiences                      # 写入经验

GET    /api/health                           # Daemon 健康检查
GET    /api/stats                            # 统计信息（任务数、成功率等）
```

**GET /api/experiences** — 经验检索
```json
// Query: ?tags=data_cleaning,backtest&limit=5
{
  "experiences": [
    {
      "id": 1,
      "source_task": "t-uuid-001",
      "category": "pitfall",
      "title": "数据缺失值必须在策略编码前处理",
      "content": "...",
      "tags": ["data_cleaning", "backtest"],
      "relevance_score": 0.92
    }
  ]
}
```

#### 3.10.4 AI Native 扩展 API

```
POST   /api/tasks/{id}/steer                # 用户中途改方向（不改 goal）
POST   /api/tasks/{id}/takeover/{step_id}   # 用户接管某步骤
POST   /api/tasks/{id}/intervene             # 用户主动干预
POST   /api/steps/{id}/review                # 触发 challenge 审查
POST   /api/tasks/{id}/distill               # 触发经验蒸馏
```

**POST /api/tasks/{id}/steer** — 用户改方向
```json
// Request
{
  "direction": "改用MACD策略",
  "reason": "用户要求",
  "affected_steps": ["s2"]  // 哪些步骤受影响（可选，AI自动判断）
}
// Response
{
  "ok": true,
  "action": "replanning",
  "paused_steps": ["s2"],
  "message": "正在重新规划受影响的步骤..."
}
```

---

### 3.11 经验沉淀引擎

> 每次任务完成后自动触发，提取可复用的经验存入经验库。

#### 3.11.1 沉淀流程

```
任务完成
  │
  ▼
Daemon 检测到任务 state = completed
  │
  ▼
Daemon 通过 Gateway 触发 AI session 做经验蒸馏
  - 输入: task context + plan + 所有 steps 的 transcript.jsonl + moments
  - AI 分析：
    1. 哪些决策是好的？（pattern）
    2. 哪些坑踩了？（pitfall）
    3. 有什么可复用的做法？（best_practice）
    4. 工具使用技巧？（tool_usage）
  - 输出: 3-5 条经验
  │
  ▼
Daemon 写入 SQLite experiences 表 + 生成 experience.md
  │
  ▼
下次创建类似任务时，Daemon 自动检索相关经验注入 context
```

#### 3.11.2 经验检索时机

| 时机 | 触发者 | 检索内容 |
|------|--------|----------|
| Phase 2 规划 | Daemon | 检索与任务 goal 相关的经验，注入 plan 上下文 |
| Phase 3 Agent 选择 | Daemon | 检索与步骤类型相关的经验（如"这类任务哪个 Agent 做得好"） |
| Agent 执行前 | Daemon | 注入与步骤相关的经验到 task 描述 |
| 异常处理 | Daemon/庞统 | 检索类似异常的历史处理方式 |

#### 3.11.3 调研审视：经验沉淀引擎的改进方向

基于 wiki 知识管理体系 + Nuwa 五层蒸馏 + Corpus2Skill + A-MEM + MemAgents ICLR 2026 的调研：

**改进 1：闭环四阶段（当前只有 DISTILL+APPLY）**

```
DISCOVER（发现问题）:
  - 异常即知识源：步骤失败、数据质量异常、Agent 超时都是潜在的待沉淀知识
  - 反向触发：Agent 主动发现好实践时建议"这个做法可以固化"
  - 外部注入：用户丢链接/文章，评估适用性

DISTILL（蒸馏提取）:
  - 参考 Nuwa 五层：表象 → 模式 → 决策启发式 → 反模式 → 边界
  - 不是简单的"踩坑记录"，而是提炼出可复用的决策规则
  - AI 分析 transcript.jsonl，不只是看结论，看完整决策过程

APPLY（应用）:
  - 规划时：检索与 goal 相关的经验注入 plan 上下文
  - 执行时：检索与步骤相关的经验注入 task 描述
  - 异常时：检索类似异常的历史处理方式

IMPROVE（持续改进）:
  - 新经验可能让旧经验过时（A-MEM 的 Zettelkasten 思路）
  - 检测冲突：新经验与旧经验矛盾时，标注差异，等待下次应用时验证
  - 不删除旧经验，标记为 superseded + 关联新经验
```

**改进 2：经验→Skill 转化（参考 Corpus2Skill）**

高频使用的经验可以自动转化为 Agent Skill：

```
经验使用频率 >= 5次
  → 自动转化为 skills/auto-generated/{experience-name}/SKILL.md
  → 下次同类任务直接注入 Skill，不需要检索经验库
  → 减少 token 消耗（Skill 注入比检索更精炼）
```

**改进 3：经验蒸馏的五层结构（参考 Nuwa）**

```yaml
experience:
  title: "数据清洗应先于策略编码"
  layers:
    - layer: surface          # 表象：发生了什么
      content: "赵云获取数据后有缺失值，张飞直接编码导致回测结果异常"
    - layer: pattern           # 模式：这类问题的通用模式
      content: "数据质量和策略逻辑是两个独立关注点，应串行处理"
    - layer: heuristic         # 决策启发式：下次怎么做
      content: "IF 任务涉及数据分析 THEN 第一步必须是数据质量检查"
    - layer: anti_pattern      # 反模式：绝对不做的事
      content: "绝对不要假设数据是干净的，即使数据源声称已清洗"
    - layer: boundary          # 边界：什么时候不适用
      content: "如果是纯模拟数据回测，不需要数据清洗步骤"
```

### 3.12 中央协调 + Agent 自主（v2.4 核心设计修正）

> **问题**：v2.3 设计在三轮评审后逐渐妥协了三个 AI native 核心目标：
> 1. Agent 自主协作 → 退化为中央调度
> 2. 实时共享感知 → 退化为按需查询
> 3. AI 持续参与 → 退化为完成时通知
>
> **根因**：遇到技术难点时采纳降级方案，而非在约束下找实现目标的方法。
>
> **v2.4 修正**：技术栈不变（Daemon + SQLite + `openclaw agent` CLI + 文件系统），变的是**设计理念**——
> 从“中央控制”变为“中央协调 + Agent 自主”。
>
> **调研来源**：
> - Edict 朝堂议政：TurnScheduler + phaseMask（Agent 声明在哪些阶段主动发言）
> - Ouroboros：后台意识循环 consciousness.py（任务间主动思考）
> - Network-AI：Blackboard + CRDT（Agent 读黑板、看到变化、自己决定行动）
> - Open Multi-Agent：sharedMemory + delegate_to_agent（Agent 可主动委派）
> - oh-my-claudecode：Team staged pipeline（team-plan → team-prd → team-exec → team-verify → team-fix）
> - Hermes Agent：kanban board + dispatcher（Agent 通过 kanban_* 工具集自主 claim task）
> - Claude Code：Grove（共享项目工作区）、Swarm/Team（hub-spoke 协调）
> - MCP + A2A：MCP 提供上下文共享，A2A 提供 Agent 间直接通信
> - 学术：Multi-Agent Blackboard System (arXiv:2510.01285) 消除中央协调器先验知识需求

#### 3.12.1 三层自主模型

```
┌──────────────────────────────────────────────────────┐
│                  庞统（中央协调）                       │
│  定方向、定约束、异常干预、持续观察                       │
│  不微观管理：不指定每一步怎么做                          │
└────────────┬─────────────────────┬───────────────────┘
             │                     │
    ┌────────▼────────┐  ┌────────▼────────┐
    │   Agent 自主权    │  │   Agent 自主权    │
    │ 执行方式自主决定   │  │ 执行方式自主决定   │
    │ 可主动发现问题    │  │ 可主动发现问题    │
    │ 可主动建议       │  │ 可主动建议       │
    └────────┬────────┘  └────────┬────────┘
             │                     │
    ┌────────▼─────────────────────▼────────┐
    │        共享意识空间（文件系统）            │
    │  status.json    → 全局状态实时摘要       │
    │  observations/  → Agent 主动观察        │
    │  moments.jsonl  → 原子事件流           │
    │  steps/         → 各步骤产出物          │
    └──────────────────────────────────────┘
```

**与 v2.3 的核心区别**：

| 维度 | v2.3（妥协版） | v2.4（AI native） |
|------|-------------|----------------|
| 调度模式 | daemon 全权调度 | 庞统定方向，Agent 自主执行 |
| 信息获取 | Agent curl 查 API | Agent 直接 read 共享目录文件 |
| AI 参与 | 步骤完成后通知 | 持续推送执行摘要，庞统主动干预 |
| Agent 主动性 | 无 | observations 目录 + 主动建议机制 |
| 协作方式 | 庞统串行分配 | Agent 可观察其他 Agent 产出并主动调整 |

#### 3.12.2 Agent 自主执行协议

Agent 被调度后，不只是“执行指令”，而是执行一套自主行为协议：

```
Agent 收到任务消息后：

1. 【感知】read artifacts/task-{id}/status.json
   → 了解全局：当前 phase、各步骤状态、异常列表

2. 【感知】read artifacts/task-{id}/observations/
   → 了解其他 Agent 的观察和建议
   → 特别是前序步骤 Agent 的发现

3. 【感知】read artifacts/task-{id}/steps/{前序步骤}/output.json
   → 获取前序步骤的具体产出

4. 【执行】基于全局信息自主决定执行方式
   → 不需要庞统指定“用什么工具、什么方法”
   → 根据任务意图 + 全局上下文自行判断

5. 【主动观察】如果执行中发现异常/有价值的发现：
   → write artifacts/task-{id}/observations/{agent}-{seq}.md
   → 内容：发现的问题、建议的调整、重要的洞察
   → 格式自由（Markdown），由庞统或其他 Agent 读取

6. 【回报】完成/失败后回报 daemon API
   → POST /api/steps/{id}/complete 或 /fail
```

**关键设计**：步骤 1-3（感知）是**强制的**，写入 Agent 的 task-bootstrap Skill。
这确保每个 Agent 执行前都有全局视野，而不是盲人摸象。

#### 3.12.3 Agent 任务消息模板（v2.4 增强）

调度 Agent 时，消息内容不仅是“执行 X”，还包含：

```markdown
## 任务：{step_title}

### 意图
{step_intent} → 目标状态：{end_state}

### 全局上下文
- 任务：{task_title}
- Phase：{current_phase}
- 前序步骤：{completed_steps_summary}
- **请先感知全局**：read artifacts/task-{id}/status.json 和 observations/

### 你的自主权
- 执行方式由你决定（工具、方法、顺序）
- 发现异常请写入 observations/
- 遇到专业外的问题主动回报，不硬撑

### 约束
- 产出物必须写到 artifacts/task-{id}/steps/{step_id}/
- 超时 {timeout_minutes} 分钟自动标记 blocked

### 完成后
POST /api/steps/{step_id}/complete
body: {artifacts: [...], confidence: 0-1, summary: "...", observations: [...]}
```

#### 3.12.4 庞统持续意识机制

庞统不是被动的审批节点，而是持续观察的指挥官。

**实现方式**：daemon 通过 `openclaw agent` CLI 定期推送执行摘要给庞统。

```
触发时机（不是 cron，是事件驱动）：

1. 步骤完成事件
   → daemon 立即通知庞统
   → 庞统判断：正常→无干预 / 异常→主动发指令

2. Agent 写入 observation
   → daemon 检测到新文件（inotify/fswatch）
   → 推送给庞统："赵云发现数据异常"
   → 庞统决定：加步骤 / 调整方案 / 通知用户

3. 定期心跳（每 N 分钟，可配置）
   → daemon 推送当前全局摘要
   → 庞统判断是否有异常趋势（如某步骤超时、Agent 连续失败）
   → 正常→回"继续" / 异常→主动干预

4. AI 质量评估点（Phase 2/3 交界处）
   → 庞统审查当前执行计划 vs 实际进展
   → 主动调整步骤、重新分配 Agent、升级问题
```

**Token 消耗控制**（通过质量分级）：
- `critical` 任务：每个事件都推送
- `standard` 任务：步骤完成 + observation 时推送
- `exploratory` 任务：仅步骤完成时推送

#### 3.12.5 文件系统 = 实时共享感知

**核心洞察**：文件系统天然就是“实时共享”的——一个 Agent write 了文件，另一个 Agent 立刻可以 read。
不需要 WebSocket、不需要推送、不需要轮询 API。

关键在于让 Agent **知道去读什么**。这就是 `status.json` + `observations/` 的作用：

- `status.json`：daemon 在每次状态变化后立即更新，Agent read 即可获得全局视野
- `observations/`：Agent 发现问题时主动写入，其他 Agent read 即可感知
- `steps/`：前序步骤的产出物就在文件系统里，不需要通过 API 传输

**为什么不用 WebSocket/实时推送？**
因为 Agent 的执行是 `openclaw agent` CLI 调用——每次调用是一个独立进程。
Agent 不需要“订阅”事件流，而是在被调用时通过 read 文件获取全部所需上下文。
这比实时推送更简单、更可靠（无连接断开问题）。

#### 3.12.6 Agent 主动协作场景

```
场景 1：赵云发现数据异常
  → 赵云写入 observations/zhaoyun-001.md
  → daemon 检测到 → 通知庞统
  → 庞统判断：需要加清洗步骤
  → 庞统调整计划 → daemon 更新 status.json + plan.json
  → 张飞被调度时 read status.json，看到新增的清洗步骤
  → 张飞 read observations/zhaoyun-001.md，了解数据异常详情
  → 张飞自主决定：在策略编码前加入数据清洗逻辑

场景 2：张飞主动建议
  → 张飞执行策略编码时，发现更好的技术指标
  → 张飞写入 observations/zhangfei-001.md
  → daemon 通知庞统
  → 庞统判断：值得尝试，修改计划允许探索
  → 关羽审核时 read observations/，看到张飞的建议，针对性审查

场景 3：关羽主动拦截
  → 关羽审核代码时发现风险
  → 关羽写入 observations/guanyu-001.md（标记为 blocking）
  → daemon 立即通知庞统
  → 庞统决定：暂停后续步骤，要求张飞修改
  → 不需要等步骤“完成”才发现问题
```

#### 3.12.7 实现注意事项（司马懿第四轮评审反馈，v2.4 补充）

> 司马懿判定：v2.4 设计方向正确，可进入实现。以下为实现时必须注意的 5 个细节。

**1. Agent 自主的真实边界**

Agent 在执行开始时获取全局快照（read status.json + observations/），**执行过程中不感知变化**。
并行执行场景下，如果需要运行时感知，由庞统通过 steer 触发。
不在文件监控或实时推送上过度承诺。

**2. Observation 通知机制**

不依赖 inotify/fswatch（macOS 可靠性存疑，SMB 挂载不工作）。
改为：**Agent 写入 observation 后主动 POST `/api/observations` 通知 daemon**，daemon 再通知庞统。
更简单、更可靠、不依赖文件系统事件。

**3. daemon vs 庞统的角色透明化**

不要把 daemon 的确定性决策包装成"庞统定方向"。

| 决策类型 | 执行者 | 性质 |
|---------|-------|------|
| Agent 选择算法 | daemon (selector.py) | 确定性 |
| 状态流转规则 | daemon (orchestrator.py) | 确定性 |
| 超时检测 | daemon (watchdog.py) | 确定性 |
| 产出验证 | daemon (validator.py) | 确定性 + 可选 AI |
| Phase 2 规划 | **庞统 AI** | AI 决策 |
| Phase 3 异常裁决 | **庞统 AI** | AI 决策 |
| 计划调整审批 | **庞统 AI** | AI 决策 |
| 用户意图一致性检查 | **庞统 AI** | AI 决策 |

**4. 文件系统可靠性细节**

- `status.json` 更新必须使用 `atomic_write`（tmp → rename），复用 Section 2.1.4 的实现
- observations 文件命名改为 `{agent}-{timestamp}-{uuid短}.md`，避免命名冲突
- artifacts 目录在本地文件系统（Mac mini SSD），不写在 SMB 挂载上

**5. Observation 写入标准与频率限制**

task-bootstrap Skill 中必须明确写入标准：
```
observation 写入条件（必须满足至少一条）：
- 发现了可能影响后续步骤的问题
- 有能提升最终产出质量的建议
- 遇到了专业外需要上报的问题
禁止写入：进度报告、正常状态确认、无关细节
```

频率限制：每个步骤每个 Agent 最多 3 个 observation，超过由 daemon 丢弃并记录 warning。

**6. 庞统上下文管理**

每次被触发时，不把历史推理过程带入上下文，只带入当前状态快照。
类似"每次被唤醒都是全新视角"——避免庞统 session 的上下文膨胀。

**7. B1 贯穿性：用户意图一致性检查**

当用户在执行中途改方向时（steer），庞统不只重新规划，还应先评估影响并帮用户决策：
- "改成周线意味着数据量减少到 1/5，统计显著性可能不够。你确定吗？"
- "增加止损条件会导致策略复杂度上升，回测时间可能翻倍。要继续吗？"

这是 PRD B1（AI 帮用户想清楚要什么）的全程贯穿，不限于 Phase 1。
在庞统的 prompt 中加入"用户意图一致性检查"规则。

#### 3.12.8 AI native Skill 体系（v2.6 修订）

> **v1.0 的 Skill 问题**：把命令操作手册写到 Skill 里——"数据获取步骤：1. 连接数据库 2. 执行 SQL 3. 保存 CSV"。
> 这不是 AI native，这是给 AI 写操作流程。AI 自己会决定怎么操作。
>
> **v2.0 AI native Skill**：不是告诉 AI 怎么做，而是设定边界——做什么是好的、做什么是错的、遇到什么情况该怎么想。
> AI 自己决定具体步骤。

**三层 Skill 模型**：

| 层级 | 名称 | 内容 | 类比 |
|------|------|------|------|
| L1 | **Principles**（原则） | 做事的底线和方向 | 宪法 |
| L2 | **Patterns**（模式） | 遇到什么情况应该怎么想 | 判例法 |
| L3 | **Anti-patterns**（反模式） | 绝对不能做的事 | 刑法 |

**具体 Skill 内容示例**（`data-acquisition/SKILL.md`）：

```markdown
# 数据获取 Skill（赵云）

## L1 原则
- 数据获取后必须先检查质量再回报
- 任何数据源声称已清洗都不能信任
- 产出物必须包含数据质量报告

## L2 模式
- 如果发现缺失值 < 5%：前值填充，记录在 observation
- 如果发现缺失值 > 5%：标记异常区间，在 observation 中建议后续步骤如何处理
- 如果发现数据时间范围与任务要求不符：立即回报，不自行裁剪
- 如果数据源有多个版本：选择最完整的，在 observation 中说明选择理由

## L3 反模式
- 绝不能假设数据是干净的
- 绝不能默默修复数据问题而不在 observation 中记录
- 绝不能返回未经检查的数据
- 绝不能跳过数据质量报告直接标记步骤完成
```

**与 v1.0 的核心区别**：
- v1.0："连接 jqdatasdk，执行 get_price()，保存到 CSV"（操作手册）
- v2.0："获取后必须检查质量，缺失值要记录"（行为准则）
- AI 自己决定用什么工具、什么 API、什么格式

**v2.0 预设 Skill 目录**：

```
skills/
├── task-bootstrap/SKILL.md          # Agent 启动协议（感知→执行→观察）
├── task-report/SKILL.md             # Agent 完成报告协议
├── quality-gate/SKILL.md            # 产出物自检协议
├── orchestration-strategy/SKILL.md  # 庞统调度策略（五原则 + 防降级）
├── data-acquisition/SKILL.md        # 数据获取行为准则（赵云）
├── strategy-coding/SKILL.md         # 策略编码行为准则（张飞）
├── risk-review/SKILL.md             # 风控审核行为准则（关羽）
├── infra-management/SKILL.md        # 基础设施管理行为准则（姜维）
└── experience-distill/SKILL.md      # 经验蒸馏行为准则
```

**Skill 格式**：Markdown（LLM 理解最好、token 最省、自由度最高）。
每个 Skill 包含完整的 L1 + L2 + L3 三层。

**Skill 加载方式**：
- 每个 Agent 的 SOUL.md 中引用自己的专属 Skill
- task-bootstrap 和 quality-gate 通过任务消息模板注入（所有 Agent 通用）
- orchestration-strategy 通过庞统的 SOUL.md 注入
- 经验蒸馏完成后，相关经验自动注入到后续任务的上下文中（半自动 Skill 更新）

#### 3.12.9 庞统调度策略 Skill（v2.5 新增）

> 综合 Microsoft Azure Checker Pattern、Google RouterAgent、oh-my-claudecode Team pipeline、AWS Strands ReWOO。

**调度五原则**：

| # | 原则 | 说明 | 业界来源 |
|---|------|------|---------|
| 1 | **Capability Matching** | 根据 Agent 能力画像匹配任务，不是轮询分配 | Google RouterAgent |
| 2 | **Dependency-Aware Scheduling** | 先调度无依赖步骤（可并行），有依赖的等前置完成 | AWS Strands ReWOO |
| 3 | **Iterative Refinement** | 执行→验证→如有问题→第二轮修正→再验证（设上限） | Microsoft Azure Checker Pattern |
| 4 | **Quality-Gated Advancement** | 当前步骤通过门控后才调度下一步 | oh-my-claudecode verify→fix loop |
| 5 | **Escalation Over Failure** | 失败不放弃：重试→换 Agent→升级到用户 | Hermes per-task retry |

**Iterative Refinement 具体流程**：

```
庞统调度张飞 → 张飞产出 → 庞统/司马懿审核
  → 通过：调度下一步
  → 未通过：调度张飞第二轮（带上审核意见 + 相关 observation）
    → 张飞 read observations/ → 自主调整 → 再提交
    → 通过：调度下一步
    → 未通过 + 达到迭代上限（3次）：升级到用户
```

**并行步骤的处理**：
并行步骤间不需要实时感知。庞统在两个并行步骤都完成后，
检查 observation 是否有关联。如果有关联，调度受影响的 Agent 做第二轮。

#### 3.12.10 Observation 设计方案（v2.5 完善）

**Observation 生命周期**：

```
1. Agent 执行中发现问题
   → 判断是否符合写入标准（影响后续步骤/提升质量/专业外问题）
   → 不符合标准就不写（禁止进度报告、正常确认、无关细节）

2. 写入 observation
   → write artifacts/task-{id}/observations/{agent}-{timestamp}-{uuid短}.md
   → 唯一强制：第一行必须是 [SEVERITY: blocking/warning/info]
   → 内容格式完全自由（不固定 JSON 或 Markdown）
   → POST /api/observations 通知 daemon

3. daemon 收到通知
   → blocking：立即通知庞统
   → warning/info：步骤完成时一起通知

4. 庞统处理
   → 评估影响 → 决策（忽略/调整计划/通知后续 Agent/调度第二轮）

5. 后续 Agent 感知
   → 被调度时 read observations/ → 自主决定是否调整
```

**为什么内容格式不固定**：
固定 JSON 或 Markdown 格式会束缚 AI 的表达能力。
Agent 根据发现的情况自由选择最合适的表达方式。
唯一强制 severity 标记是因为 daemon 需要它来决策通知级别。

**频率限制**：每个步骤每个 Agent 最多 3 个 observation。

**observation 的 pav 执行记录**（v2.5 新增）：
Agent 执行过程中的关键决策点用 severity=audit 记录：
- 为什么选这个方法
- 做了什么取舍
- 发现了什么
audit 级别不通知庞统，只记录在文件系统供事后审查。

#### 3.12.11 Agent 调度方式（v2.6 终版确认）

**实验结论**（2026-05-14 两轮 spawn 实验）：
- `sessions_spawn` 配置 `allowAgents: ["*"]` 后可以指定其他 agentId
- 跨 Agent spawn 读写文件、结论回传、cleanup:delete 全部正常
- **spawn 是 v2.0 调度将军的首选方式**

**Gateway 配置**（已应用）：
```json
// ~/.openclaw/openclaw.json → agents.list[id=pangtong-fujunshi]
{ "subagents": { "allowAgents": ["*"] } }
```

**v2.0 调度方式（按优先级排序）**：

| 优先级 | 方式 | 用途 | 特点 |
|--------|------|------|------|
| **首选** | `sessions_spawn(agentId="xxx", cleanup="delete")` | 调度将军执行步骤 | 不走 Gateway、并行、自动清理、结论回传 |
| Fallback | `openclaw agent --agent xxx --local --json` | spawn 不可用时 | `--local` 本地运行，自动 fallback |
| 内部 | `sessions_spawn()` (无 agentId) | 庞统内部复杂分析 | 子 session 继承上下文 |

**spawn 的关键优势**（vs `openclaw agent` CLI）：
- 不依赖 Gateway（Gateway 挂了也能调度）
- 庞统可以通过 `subagents list` 实时监控子 session 状态
- 完成后自动回传结果，不需要轮询
- 支持嵌套调度（`maxSpawnDepth: 2`）
- 支持并行（`maxConcurrent: 8`）

#### 3.12.12 庞统上下文管理（v2.6 新增）

> **核心问题**：庞统在一个 session 里处理多个任务时，上下文会膨胀。如果“每次唤醒全新视角”，
> 之前的推理过程丢失，决策质量下降。如果保留全部上下文，token 爆炸。
> **必须找到平衡**。

**调研来源**：
- **get-shit-done**：Wave Execution——每个 plan 用独立新鲜上下文，避免 context rot
- **Claude Code**：session linked by parent_session_id + auxiliary-LLM compression
- **学术：Episodic Memory**（arXiv:2502.06975）：episodic memory 是长期 Agent 的缺失拼图
- **学术：Memory as Action**（arXiv:2509.25250）：自主上下文策展

**方案：三层上下文架构**

```
┌───────────────────────────────────────────┐
│ L1: 永久记忆（跨任务保留）                    │
│ MEMORY.md + 经验库 + Skill 体系               │
│ 每次启动自动注入，不受上下文窗口限制             │
└───────────────────────────────────────────┘

┌───────────────────────────────────────────┐
│ L2: 任务工作记忆（单任务内保留）                │
│ decisions.jsonl + moments.jsonl + status.json  │
│ 存文件系统，庞统被唤醒时 read 获取              │
│ → 这就是“上下文恢复协议”的实质                  │
└───────────────────────────────────────────┘

┌───────────────────────────────────────────┐
│ L3: 推理上下文（每次唤醒重建）                  │
│ 当前推理过程，对话历史中的近期部分               │
│ 通过 OpenClaw compaction 自动管理              │
└───────────────────────────────────────────┘
```

**具体机制**：

1. **庞统被唤醒时**：
   - read `status.json`（当前全局状态）
   - read `decisions.jsonl`（之前做过的决策及理由）
   - read `moments.jsonl`（最近 10 条事件）
   - 这三步重建 L2 工作记忆

2. **庞统做决策时**：
   - 关键决策写入 `decisions.jsonl`（不只在对话历史里）
   - 格式：`{decision, reason, alternatives_rejected, timestamp}`
   - 下次被唤醒时能看到自己之前为什么做这个决策

3. **防止“忘了”的兜底**：
   - 每个 observation 写入时，daemon 同时记录到 `moments.jsonl`
   - 庞统被唤醒时看到的 moments 包含所有 Agent 的 observation 摘要
   - 即使庞统“忘了”对话中的推理，通过文件系统能找回来

4. **并行步骤完成后的识别**：
   - 两个并行步骤都完成后，daemon 生成一个“并行步骤关联分析”
   - 检查两个步骤的 observation 是否有关联
   - 如果有关联，写入 moments 并通知庞统
   - 庞统不需要“记住”并行步骤的关系——文件系统替他记着

**与之前“全新视角”方案的区别**：
- 之前：每次唤醒清空一切，只看 status.json
- 现在：每次唤醒有 L1（永久）+ L2（文件系统工作记忆）+ L3（对话上下文）
- L2 是关键创新——决策理由和 observation 摘要存在文件里，不依赖对话历史

#### 3.12.13 防降级机制（v2.6 新增）

> **核心问题**：调度策略本身如何防止在执行过程中逐渐妥协？
> 庞统如何保证不为了“完成任务”而降级目标？

**四个防降级机制**：

**机制 1：反合理化表（Anti-Rationalization Table）**

来源：Agent Skills 生命周期实践

写入 orchestration-strategy Skill 的 L3（反模式）层：

```
庞统自检清单——每个调度决策前必须过：
❌ “这个步骤简化一下”   → 问：PRD 目标是否被覆盖？
❌ “时间不够跳过验证”   → 没有验证的产出不算完成
❌ “这个Agent做不到就算了” → 换 Agent 或拆步骤
❌ “先用简单方案后续优化” → v2.0 就是完整实现
❌ “用户应该不在意”     → 你的判断 ≠ 用户需求
```

**机制 2：目标锚定（Goal Anchoring）**

每个任务的原始 goal 和 PRD 需求写入 `context.json`，不可修改。
庞统每次做调度决策时必须对照 goal：
- 决策是否更接近 goal？
- 如果偏离 goal，必须升级到用户，不能自行降级

**机制 3：范围缩减检测（Scope Reduction Detection）**

来源：get-shit-done 实践

planner.py 在 Phase 2 生成计划时，每个步骤必须标注覆盖哪些需求。
daemon 在执行完所有步骤后，反向检查：每个需求是否被至少一个步骤覆盖。
如果有遗漏，不允许进入 Phase 4，必须 replan。

**机制 4：验证前不完成（Verification-Before-Completion）**

来源：superpowers 实践

Agent 声称完成时，validator.py 检查：
1. 产出物文件存在且非空
2. 产出物与 end_state 描述匹配（AI 语义检查）
3. 没有未处理的 blocking observation
任何一项不通过，步骤状态不变为 completed。

---

## 4. 已决策（全部）

| # | 决策 | 结论 | 理由 |
|---|------|------|------|
| 1 | 黑板载体 | **SQLite + 文件系统** | SQLite 存状态（查询快、事务安全），文件系统存产出物（git 可追踪） |
| 2 | 庞统运行方式 | **主 session + daemon API** | 庞统在正常 session 里与用户对话，通过 HTTP API 调度 daemon |
| 3 | Agent 调度 | **`openclaw agent` CLI（简单）+ sessions_spawn（复杂）** | CLI 是 Gateway 原生能力，有超时和 fallback；复杂步骤用 sub-agent 隔离 |
| 4 | 事件触发 | **daemon 内部事件循环** | Agent 回报时触发下一步，不用 cron |
| 5 | 配置化 | **YAML/JSON 配置文件** | 状态/流转/事件/模板全部配置化，代码零硬编码 |
| 6 | Agent 团队 | 复用三国角色 | 角色映射清晰 |
| 7 | v1.0 共存 | 独立 session，并行运行 | v1.0 和 v2.0 互不干扰 |
| 8 | 前端 | 先纯对话（Control Center） | 后续加可视化 |
| 9 | 状态机 | 继承 v1.0 + AI native 扩展 | steer/takeover/intervene/replan 等 |
| 10 | 执行历史 | sub-agent transcript 归档到任务目录 | 可追溯、可学习、可复盘 |
| 11 | Daemon 通知庞统 | `openclaw agent` CLI | 步骤完成/异常/需要裁决时 |
| 12 | 经验沉淀 | 任务完成后自动触发 AI 蒸馏 | + 规划/执行/异常时自动检索 |
| 13 | 实现方式 | **一次性完整实现** | 不做最小集迭代，避免做着做着偏离 |
| 14 | 治理原则 | **质量优先，成本和工期为质量让步，但有硬性上限** | 见 4.1 治理框架 |
| 15 | Agent 调度机制 | **`openclaw agent` CLI** | 司马懿评审：废弃自建 WS Client，改用 CLI |
| 16 | 数据存储 | **SQLite 为唯一权威，文件系统为索引缓存** | 司马懿评审：消除双写一致性问题 |
| 17 | 经验蒸馏 | **先两层（surface+heuristic），验证后扩展** | 司马懿评审：五层过重，YAGNI |
| 18 | 实施策略 | **分批集成（设计一次做完，实现分批验证）** | 司马懿评审：骨架→智能→高级 |
| 19 | Agent 协作模式 | **中央协调 + Agent 自主**（非纯中央调度） | v2.4 修正：庞统定方向约束，Agent 自主执行+主动观察 |
| 20 | 信息共享方式 | **文件系统直读**（非 API 查询） | v2.4 修正：status.json + observations/ 目录，Agent 直接 read |
| 21 | AI 参与方式 | **事件驱动持续参与**（非完成时通知） | v2.4 修正：步骤完成/observation/心跳/质量评估点四类触发 |
| 22 | Agent 主动性 | **observations 目录 + 自主行为协议** | v2.4 新增：Agent 可主动写观察、建议、异常，其他 Agent 可感知 |
| 23 | Skill 体系 | **三层模型（Principles + Patterns + Anti-patterns）** | v2.5 新增：综合 oh-my-claudecode/Hermes/Nuwa/Agent Skills |
| 24 | 调度策略 | **五原则（Capability/Dependency/Iterative/QualityGate/Escalation）** | v2.5 新增：综合 Azure/Google/OMC/AWS |
| 25 | Observation 格式 | **自由格式 + 强制 severity 标记** | v2.5 确认：不固定 JSON/MD，唯一强制 [SEVERITY: xxx] |
| 26 | Agent 调度方式 | **双模式（openclaw agent CLI + sessions_spawn）** | v2.5 确认：CLI 调度将军，spawn 庞统内部分析 |
| 27 | 并行感知方案 | **多轮迭代（非实时感知）** | v2.5 确认：庞统判断是否需第二轮，不依赖运行时感知 |
| 28 | 信息隔离预留 | **agent-registry.json 中 visibility 字段** | v2.6 预留：v2.0 全部 full，v2.1+ 按需开启 |
| 29 | Agent 调度首选 | **sessions_spawn（allowAgents配置已生效）** | v2.6 确认：实验验证跨 Agent spawn 可用 |
| 30 | 庞统上下文管理 | **三层架构（永久记忆+文件工作记忆+对话上下文）** | v2.6 新增：防止“全新视角”丢信息 |
| 31 | 防降级机制 | **四个机制（反合理化+目标锚定+范围缩减+验证前不完成）** | v2.6 新增：确保调度不降级 |
| 32 | Skill 本质 | **行为准则（L1原则+L2模式+L3反模式），非操作手册** | v2.6 明确：告诉 AI 做什么是对的，不告诉怎么做 |
| 33 | 评审模式 | **单任务单评审+汇总后再评审，交叉评审按需** | v2.6 确认 |

### 4.1 质量/成本/工期治理框架

> 核心原则：**质量是第一优先级，成本和工期可以为质量妥协，但不能无限妥协。**
>
> 参考：Wanman TokenBudget（per-agent ceiling + 全局 ceiling）、Network-AI FederatedBudget（双层预算）、Network-AI QualityGate（两层门控：规则+AI）。

#### 三层预算体系

每个任务创建时分配三重预算，任何一重耗尽都触发干预：

```yaml
# config/settings.yaml 中的默认预算
budget_defaults:
  token:
    per_task_ceiling: 500000       # 单任务总 token 上限
    per_step_ceiling: 100000        # 单步骤 token 上限
    per_agent_ceiling: 200000       # 单 Agent token 上限
  time:
    per_task_ceiling: 3600          # 单任务总时间上限（秒）
    per_step_ceiling: 600           # 单步骤时间上限（秒）
  depth:
    max_plan_adjustments: 5         # 计划调整次数上限
    max_retries_per_step: 3         # 单步骤重试次数上限
    max_challenge_rounds: 3         # 挑战循环次数上限
```

**预算耗尽时的行为**：

| 预算类型 | 耗尽行为 | 谁干预 |
|---------|---------|--------|
| step token 耗尽 | 步骤标记 failed，触发异常处理 | Daemon 自动 |
| step 时间耗尽 | 步骤标记 failed，检查 Agent 存活 | Daemon 自动 |
| task token 耗尽 | 任务暂停，通知庞统 + 用户 | Daemon → 庞统 → 用户 |
| task 时间耗尽 | 任务暂停，通知庞统 + 用户 | Daemon → 庞统 → 用户 |
| 计划调整次数耗尽 | 停止调整，用当前最佳计划继续 | Daemon 自动 |
| 重试次数耗尽 | 步骤标记 failed，升级到庞统 | Daemon → 庞统 |

#### 质量门控（Quality Gate）

参考 Network-AI 两层门控：

```
Agent 提交产出物
  │
  ▼
Layer 1: 规则验证（确定性，零成本，毫秒级）
  ├── 文件存在性检查
  ├── 文件非空检查
  ├── Schema 校验（JSON/CSV 格式正确）
  ├── Placeholder 检测（TODO/FIXME/...）
  └── 基础完整性（字段非空、数值范围合理）
  │
  ├─ 通过 → 进入 Layer 2
  └─ 失败 → reject（退回 Agent 修复）
  │
  ▼
Layer 2: AI 审查（有成本，秒级，仅当 confidence < 阈值时触发）
  ├── 产出物是否与 end_state 描述匹配
  ├── 代码质量（变量命名、异常处理、逻辑正确性）
  └── 幻觉检测（声称的结论是否有数据支撑）
  │
  ├─ approve → 完成
  ├─ quarantine → 隔离待人工审查（通知庞统 + 用户）
  └─ reject → 退回 Agent 修复
```

**成本控制**：Layer 2 不是每次都跑。默认只在以下情况触发：
- Agent 回报 confidence < 0.7
- 步骤是关键步骤（用户明确指定要审查的）
- 连续多个步骤 Layer 1 都一次通过（抽样审查，防止 Agent 学会绕规则）

#### 质量提升的分级投入

不是所有任务都需要极致质量。根据任务重要性分级投入：

```yaml
# config/settings.yaml
quality_levels:
  critical:          # 资金安全、实盘交易
    layer2_threshold: 0.8
    max_retries: 5
    always_ai_review: true
    human_approval_required: true
    token_budget_multiplier: 2.0
    
  standard:          # 策略回测、数据分析
    layer2_threshold: 0.7
    max_retries: 3
    always_ai_review: false
    human_approval_required: false
    token_budget_multiplier: 1.0
    
  exploratory:       # 探索性研究、快速验证
    layer2_threshold: 0.5
    max_retries: 1
    always_ai_review: false
    human_approval_required: false
    token_budget_multiplier: 0.5
```

任务创建时，AI 根据内容自动判定 quality_level，用户也可以手动指定。

#### 成本回收机制

高质量的产出如果被后续任务复用，相当于摊薄了成本：

- **经验沉淀**：高质量任务的产出自动蒸馏为经验，下次同类任务减少 token 消耗
- **Skill 转化**：高频经验固化为 Skill，直接注入减少检索成本
- **模板复用**：高质量的计划结构可以保存为模板，下次直接使用

#### 工期控制：何时干预

| 场景 | 判断标准 | 干预方式 |
|------|---------|----------|
| 明显死循环 | 同一步骤 retry > max_retries | 强制终止 + 升级 |
| 计划反复调整 | plan_adjustments > max | 锁定当前计划继续 |
| Agent 超时无响应 | step 执行时间 > per_step_ceiling | 检查存活 → 重试或换 Agent |
| 质量长期不达标 | 连续 3 个步骤 AI 审查 reject | 暂停任务 + 通知用户 |
| 成本超预期 | task token > 80% ceiling | 通知庞统评估是否值得继续 |
| 接近 deadline | task 时间 > 80% ceiling | AI 判断：是否降级质量等级以保工期 |

#### AI 决策结构化

每个 AI 决策必须记录完整的推理过程（司马懿评审意见）。

```sql
-- decisions 表结构化扩展
CREATE TABLE decisions (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    task_id TEXT NOT NULL,
    step_id TEXT,
    decision_type TEXT NOT NULL,  -- agent_selected / plan_adjusted / anomaly_classified / quality_review
    
    -- 结构化推理（司马懿要求：输入、选项、选择、原因、置信度）
    input_summary TEXT NOT NULL,       -- AI 看到了什么
    options_considered TEXT NOT NULL,   -- 考虑了哪些选项（JSON array）
    selected TEXT NOT NULL,            -- 选了什么
    reason TEXT NOT NULL,              -- 为什么选这个
    confidence REAL NOT NULL,          -- 置信度 0.0-1.0
    
    model TEXT,
    token_cost INTEGER,
    created_at TEXT NOT NULL DEFAULT (datetime('now'))
);
```

#### 经验生命周期

经验不是写进去就永远有效：

```sql
-- experiences 表扩展
ALTER TABLE experiences ADD COLUMN lifecycle TEXT DEFAULT 'draft';  -- draft / verified / superseded / expired
ALTER TABLE experiences ADD COLUMN verified_at TEXT;
ALTER TABLE experiences ADD COLUMN verified_by TEXT;  -- ai / human
ALTER TABLE experiences ADD COLUMN expires_at TEXT;   -- TTL，过期自动降权
ALTER TABLE experiences ADD COLUMN superseded_by INTEGER REFERENCES experiences(id);
```

| 生命周期 | 说明 | 检索权重 |
|---------|------|---------|
| draft | AI 自动蒸馏，未验证 | 0.5x |
| verified | 经过实际任务验证（引用 >= 2 次） | 1.0x |
| superseded | 被更好的经验替代 | 0.1x |
| expired | TTL 过期，自动降权 | 0.0x（不检索） |

#### 异常处理策略表

异常分类用确定性逻辑，处理策略用预设决策表（司马懿评审意见）：

```yaml
# config/exceptions.yaml
exceptions:
  - type: agent_timeout
    detection: "step execution time > per_step_ceiling"
    strategy:
      - action: check_agent_alive
      - action: retry
        max: 3
        backoff: exponential
      - action: reassign_agent  # 换一个 Agent
      - action: escalate_to_human
    
  - type: validation_failed
    detection: "quality gate Layer 1 failed"
    strategy:
      - action: reject_to_agent
        max: 3
      - action: escalate_to_human
    
  - type: ai_judgment_conflict
    detection: "two AI decisions contradict"
    strategy:
      - action: escalate_to_human  # AI 冲突必须人工裁决
    
  - type: resource_deadlock
    detection: "circular dependency detected"
    strategy:
      - action: break_cycle  # 随机释放一个等待
      - action: reassign_agent
      - action: escalate_to_human
    
  - type: budget_exceeded
    detection: "any budget ceiling reached"
    strategy:
      - action: pause_task
      - action: notify_pangtong
      - action: await_human_decision
    
  - type: unknown
    detection: "unclassified exception"
    strategy:
      - action: ai_classify  # 只有未知异常才让 AI 分类
      - action: apply_strategy  # 应用 AI 选择的策略
      - action: escalate_to_human  # 兜底
```

---

## 5. 实现清单

> 用户决策：一次性完整实现，不做最小集迭代。

```
核心基础设施:
  [x] Daemon HTTP API (FastAPI + uvicorn + SQLite WAL)
  [x] config/ 配置化体系（states.yaml / step-states.yaml / events.yaml / agent-registry.json）
  [x] SQLite 表结构（tasks / steps / moments / agent_status / decisions / experiences）
  [x] artifacts/ 文件系统结构
  [x] `openclaw agent` CLI 封装（daemon → Agent session 通信）
  [x] daemon 启动时补偿归档（检查未归档的 transcript）
  [x] observations/ 目录（Agent 主动观察与建议）
  [x] status.json 实时全局摘要（daemon 每次事件后更新）
  [x] Agent 自主行为协议（task-bootstrap Skill 中注入感知+执行+观察三段式）
  [x] 庞统持续意识机制（事件驱动通知 + 定期心跳）

四相循环:
  [x] Phase 1 需求探索（庞统苏格拉底对话）
  [x] Phase 2 动态规划（AI 生成 plan + 用户审批）
  [x] Phase 3 自主执行（daemon 事件循环 + Agent 调度）
  [x] Phase 4 主动汇报（AI 生成报告 + 用户验收）

Agent 管理:
  [x] agent-registry.json 能力画像
  [x] Agent 选择算法（基于能力匹配 + 历史表现）
  [x] 主 session 调度（简单步骤）
  [x] sub-agent 调度（复杂步骤 + cleanup=delete）
  [x] 执行历史归档（transcript → artifacts）

智能特性:
  [x] 幻觉门控（产出验证）
  [x] 挑战循环（reviewing → challenge pass/iterate/fail）
  [x] 动态计划调整（异常时 replan）
  [x] AI 决策记录（可追溯）
  [x] 经验沉淀引擎（任务完成后自动蒸馏）
  [x] 经验检索（规划/执行/异常时自动注入）

人工介入:
  [x] steer（用户改方向）
  [x] takeover（用户接管步骤）
  [x] intervene（用户主动干预）
  [x] escalated（AI 主动升级）
  [x] waiting_human（Agent 请求确认）

监控 & 运维:
  [x] 健康检查（daemon 内部定时 + API）
  [x] Token 预算管理
  [x] Agent 心跳
  [x] 与 v1.0 并行运行验证
```

---

## 附录：术语表

| 术语 | 含义 |
|------|------|
| Blackboard | 共享意识空间，所有 Agent 的唯一信息共享中枢 |
| Control Unit | AI 指挥官（庞统），负责动态规划、Agent 选择、异常处理 |
| Moment | 原子事件，任务执行过程中的最小信息单元 |
| Fidelity | 信息保真度，控制不同 Agent 看到多少信息 |
| propose→validate→commit | 三阶段原子写入，防止并发竞态 |
| Boids | 群体智能规则，让 Agent 自行涌现协作行为 |
| Auftragstaktik | 任务式指挥，只给目标不给步骤 |
| 幻觉门控 | 验证 Agent 产出是否真实存在 |
| Observations | Agent 主动观察与建议，写入共享目录供其他 Agent 和庞统感知 |
| Status.json | 全局状态摘要，daemon 实时维护，Agent 执行前必读 |
| 自主行为协议 | Agent 三段式行为：感知(read 全局) → 执行(自主决定) → 观察(write observations) |
| Ralph Loop | 持久目标跨 turn 保持机制 |

---

## 附录 B：调研参考来源

### 共享意识空间物理结构
- **OpenAI Codex Cookbook** — PM Agent 写 REQUIREMENTS.md / AGENT_TASKS.md，产出物 gating check
- **Wanman Agent Matrix** — `artifact.put` CLI，Agent 通过 bash 与系统交互，per-agent workspace 隔离
- **Wiki 知识管理体系** — 四层金字塔 L0-L3 + 7 种知识产物类型 + DISCOVER→DISTILL→APPLY→IMPROVE 闭环

### Daemon API 设计
- **Edict (三省六部)** — Transactional Outbox Pattern + Redis Streams 消费者组 + 死信队列
- **Wanman** — 30+ JSON-RPC 方法 + 标准错误码体系 + Agent 零SDK CLI 模式
- **Gstack** — 长存活守护进程模型 + 状态文件持久化 + 版本自动重启
- **Multica** — 任务生命周期状态机 + 分层事件总线（进程内同步 + WebSocket 实时推送）

### 经验沉淀引擎
- **Nuwa Skill (女娲)** — 五层蒸馏框架（表象→心智模型→决策启发式→反模式→诚实边界）
- **Corpus2Skill** (arXiv 2604.14572) — 离线蒸馏为可导航的层级 Skill 目录
- **A-MEM** (arXiv 2502.12110) — Zettelkasten 式记忆，新记忆触发已有记忆的更新
- **MemAgents** (ICLR 2026 Workshop) — 单次学习 + 上下文感知检索 + 整合为可泛化知识
- **Hermes** — skill_manage 使用中发现过时立即修复

### 中央协调 + Agent 自主（v2.4 新增）
- **Edict 朝堂议政** — TurnScheduler + phaseMask（Agent 声明在哪些阶段主动发言），MessageBus 消息总线
- **Ouroboros (joi-lab)** — 后台意识循环 consciousness.py，任务间主动思考，宪法驱动
- **Network-AI** — Blackboard + CRDT，Agent 读黑板、看到变化、自己决定行动
- **Open Multi-Agent** — sharedMemory + delegate_to_agent，Agent 可主动委派给其他 Agent
- **oh-my-claudecode** — Team staged pipeline（team-plan→team-prd→team-exec→team-verify→team-fix），hub-spoke 协调
- **Hermes Agent** — Durable SQLite-backed kanban board，Agent 通过 kanban_* 工具集自主 claim task，dispatcher 驱动
- **Claude Code** — Grove 共享项目工作区、Swarm/Team hub-spoke 协调、sidechain transcript 隔离
- **Claude Code Sub-Agent Collective** — task-orchestrator 路由枢纽 + 30+ 专业化 Agent + hook TDD 强制
- **agent-kanban (saltbo)** — Agent-first task board，Mission control for AI workforce
- **AgentsMesh** — PTY sandbox + git worktree 隔离 + ticket-pod binding + 内置 Kanban
- **Operator (untra)** — kanban-shaped git-versioned 软件开发，Agent 自主认领工单
- **MCP + A2A 协议** — MCP 提供上下文共享，A2A 提供 Agent 间直接通信（2026 H2 成熟）
- **Multi-Agent Blackboard System (arXiv:2510.01285)** — 消除中央协调器对 Agent 先验知识的需求
- **awesome-agent-orchestrators** — 2026 年活跃的 Agent 编排器汇总（nullclaw, agentsmesh 等）