Files

T

cfdaily f1350c90fb auto-sync: 2026-05-14 11:01:57

2026-05-14 11:01:57 +08:00

90 KiB

Raw Blame History

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

版本: v2.4（AI native 修正版）
日期: 2026-05-14
作者: 庞统（副军师）
状态: 草案，v2.4 修正：恢复 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 持续参与）

0. 设计哲学

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

六个核心信念：

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

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 — 任务上下文：

{
  "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）：

{"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 — 动态计划图谱：

{
  "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 能力画像：

{
  "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 — 决策记录（不可变）：

{"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：

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 三档）

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 选择算法

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 协作规则：

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

以及元认知自评：

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

以及Auftragstaktik 任务式指挥：

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

2.4 事件系统

2.4.1 Moments 事件类型

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 事件驱动唤醒

# 庞统的唤醒条件
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 经验数据结构

{
  "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 健康检查

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 成本追踪：

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:

# 任务级状态定义（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:

# 步骤级状态定义（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"

代码中禁止出现硬编码状态名：

# ❌ 禁止
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 调度的具体实现

# 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 — 创建任务

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

GET /api/tasks/{id}/status — 轻量状态查询（庞统用，返回人类可读摘要）

{
  "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 回报完成

// 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 回报失败

// 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 — 经验检索

// 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 — 用户改方向

// 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）

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 核心目标：

Agent 自主协作 → 退化为中央调度

实时共享感知 → 退化为按需查询

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”，还包含：

## 任务：{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 立即通知庞统
  → 庞统决定：暂停后续步骤，要求张飞修改
  → 不需要等步骤“完成”才发现问题

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 可感知

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

核心原则：质量是第一优先级，成本和工期可以为质量妥协，但不能无限妥协。

参考：Wanman TokenBudget（per-agent ceiling + 全局 ceiling）、Network-AI FederatedBudget（双层预算）、Network-AI QualityGate（两层门控：规则+AI）。

三层预算体系

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

# 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 学会绕规则）

质量提升的分级投入

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

# 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 决策必须记录完整的推理过程（司马懿评审意见）。

-- 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'))
);

经验生命周期

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

-- 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（不检索）

异常处理策略表

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

# 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] 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 产出是否真实存在
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 使用中发现过时立即修复

90 KiB Raw Blame History Unescape Escape

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