cfdaily
110 KiB
110 KiB
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，而是混合模式。
六个核心信念：
- 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 agentCLI 命令（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 agentCLI + 文件系统），变的是设计理念—— 从“中央控制”变为“中央协调 + 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 立即通知庞统
→ 庞统决定：暂停后续步骤，要求张飞修改
→ 不需要等步骤“完成”才发现问题
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）：
# 数据获取 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 配置（已应用）：
// ~/.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 自动管理 │
└───────────────────────────────────────────┘
具体机制：
-
庞统被唤醒时：
- read
status.json（当前全局状态） - read
decisions.jsonl（之前做过的决策及理由） - read
moments.jsonl（最近 10 条事件） - 这三步重建 L2 工作记忆
- read
-
庞统做决策时：
- 关键决策写入
decisions.jsonl（不只在对话历史里） - 格式：
{decision, reason, alternatives_rejected, timestamp} - 下次被唤醒时能看到自己之前为什么做这个决策
- 关键决策写入
-
防止“忘了”的兜底：
- 每个 observation 写入时，daemon 同时记录到
moments.jsonl - 庞统被唤醒时看到的 moments 包含所有 Agent 的 observation 摘要
- 即使庞统“忘了”对话中的推理，通过文件系统能找回来
- 每个 observation 写入时，daemon 同时记录到
-
并行步骤完成后的识别：
- 两个并行步骤都完成后，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 检查：
- 产出物文件存在且非空
- 产出物与 end_state 描述匹配（AI 语义检查）
- 没有未处理的 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）。
三层预算体系
每个任务创建时分配三重预算，任何一重耗尽都触发干预：
# 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] 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.putCLI，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 等）