From 54f223e9bd9e620340f29958bbec0f90fb1af1a1 Mon Sep 17 00:00:00 2001 From: cfdaily Date: Thu, 14 May 2026 08:22:15 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20v2.0=20=E5=AE=8C=E6=95=B4=E6=9E=B6?= =?UTF-8?q?=E6=9E=84=E8=AE=BE=E8=AE=A1=20-=20=E5=9B=9B=E7=9B=B8=E5=BE=AA?= =?UTF-8?q?=E7=8E=AF=20+=20Blackboard=20+=20=E6=8A=80=E6=9C=AF=E5=AE=9E?= =?UTF-8?q?=E7=8E=B0=E6=96=B9=E6=A1=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/design/architecture-v2.md | 964 +++++++++++++++++++++++++++++++++ 1 file changed, 964 insertions(+) create mode 100644 docs/design/architecture-v2.md diff --git a/docs/design/architecture-v2.md b/docs/design/architecture-v2.md new file mode 100644 index 0000000..8bdf28e --- /dev/null +++ b/docs/design/architecture-v2.md @@ -0,0 +1,964 @@ +# moziplus v2.0 — AI 原生多Agent编排平台 架构设计 + +**版本**: v2.0 +**日期**: 2026-05-14 +**作者**: 庞统（副军师） +**状态**: 草案，待用户确认 +**调研基础**: `docs/research/shared-consciousness-research.md` + +--- + +## 0. 设计哲学 + +> "可预测的骨架 + AI 驱动的填充" —— 不是纯 DAG，也不是纯 ReAct，而是混合模式。 + +六个核心信念： + +1. **AI 参与每一个决策层** —— 编排/路由/渲染/异常处理/经验沉淀都有 AI 参与 +2. **黑板是唯一真相源** —— 所有 Agent 通过黑板共享信息，没有私下通信 +3. **产出物 > 消息** —— 共享产出物比共享消息更重要 +4. **验证才算完** —— 不验证产出不算完成 +5. **有界并行** —— 默认最多 4 个 Agent 并行（有学术依据） +6. **闭环学习** —— 执行→经验沉淀→下次改进 + +--- + +## 1. 系统总览 + +### 1.1 宏观架构 + +``` +用户（自然语言） + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ 对话入口（Conversation Layer） │ +│ 庞统的持久 session，用户唯一交互点 │ +│ 支持：WebChat / CLI / Cron 触发 / API 调用 │ +└───────────────────────┬─────────────────────────────────────┘ + │ +┌───────────────────────▼─────────────────────────────────────┐ +│ 庞统 AI 指挥官（Control Unit） │ +│ │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │ Phase 1 │ │ Phase 2 │ │ Phase 3 │ │ Phase 4 │ │ +│ │ 需求探索 │ │ 动态规划 │ │ 自主执行 │ │ 主动汇报 │ │ +│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ +│ │ +│ 内置机制： │ +│ - /goal Ralph Loop：持久目标跨 turn 保持 │ +│ - Scope Reduction Detection：防偷懒 │ +│ - 幻觉门控：验证产出再算完成 │ +│ - Fidelity 路由：按需分发信息 │ +│ - Boids 规则注入：Agent 协作行为塑造 │ +│ │ +│ ┌──────────────────────────────────────────────────────┐ │ +│ │ Blackboard（共享意识空间） │ │ +│ │ │ │ +│ │ TaskCtx │ Moments │ Artifacts │ Decisions │ Plan │ │ +│ │ AgentStates │ Experience │ EventLog │ │ +│ └──────────────────────────────────────────────────────┘ │ +└───────────────────────┬─────────────────────────────────────┘ + │ Fidelity 三档读写 + ┌─────────────┼─────────────┐ + │ │ │ + ┌────▼────┐ ┌────▼────┐ ┌────▼────┐ + │ 张飞 │ │ 关羽 │ │ 赵云 │ ... + │ 编码 │ │ 风控 │ │ 数据 │ + └─────────┘ └─────────┘ └─────────┘ + 每个 Agent: isolated session + SOUL.md + Skills + 写入保护: propose → validate → commit +``` + +### 1.2 与 v1.0 的关系 + +| 维度 | v1.0 | v2.0 | +|------|------|------| +| 编排 | 固定 DAG 模板 + 确定性状态机 | 庞统 AI 动态规划 + 持续指挥 | +| 通信 | Sanguo Mail（异步邮件轮询） | Blackboard（实时共享读写） | +| 入口 | CLI + Dashboard | 自然语言对话 | +| 计划 | 一次性生成不可变 | 持续演进，可随时调整 | +| Agent 调度 | 按模板固定分配 | 按能力画像动态选择 | +| 信息可见性 | 每个 Agent 只看自己 | Fidelity 三档按需 | +| 异常处理 | Report Watcher（规则） | 庞统 AI 判断 | +| 验证 | output.md frontmatter | 幻觉门控 + AI 验证 | +| 经验 | 无闭环 | DISCOVER→DISTILL→APPLY→IMPROVE | + +**v2.0 独立仓库、独立代码、独立部署**。v1.0 继续运行，互不干扰。 + +--- + +## 2. 核心模块详细设计 + +### 2.1 Blackboard（共享意识空间） + +#### 2.1.1 物理结构 + +``` +~/.sanguo_projects/sanguo_moziplus_v2/ +├── blackboard/ # 共享意识空间根目录 +│ ├── tasks/ # 任务空间 +│ │ └── {task-id}/ # 每个任务独立目录 +│ │ ├── context.json # 任务上下文（目标/约束/状态） +│ │ ├── moments.jsonl # 原子事件流（追加写入） +│ │ ├── plan.json # 动态计划图谱 +│ │ ├── decisions.jsonl # 决策记录（不可变） +│ │ ├── agents/ # 各 Agent 工作区 +│ │ │ ├── {agent-id}/ +│ │ │ │ ├── state.json # Agent 当前状态 +│ │ │ │ ├── output/ # Agent 产出物 +│ │ │ │ └── inbox/ # Agent 专属信箱（通知类） +│ │ │ └── ... +│ │ └── artifacts/ # 共享产出物索引 +│ │ └── index.json # 产出物注册表 +│ ├── global/ # 全局共享空间 +│ │ ├── agent-registry.json # Agent 能力画像注册表 +│ │ ├── experience/ # 跨任务经验库 +│ │ │ ├── {domain}.jsonl # 按领域组织 +│ │ │ └── index.json # 经验索引 +│ │ └── templates/ # 任务模板库 +│ │ └── {template-id}.json +│ ├── events/ # 不可变全局事件日志 +│ │ └── {date}.jsonl # 按日期分文件 +│ ├── inbox/ # 用户需求入口 +│ │ └── {req-id}.json # 待处理需求 +│ └── locks/ # 写入锁目录 +│ └── {resource-path}.lock # 文件锁 +├── daemon/ # 守护进程代码 +├── skills/ # Skill 包 +├── docs/ # 文档 +└── config/ # 配置 +``` + +#### 2.1.2 数据结构定义 + +**context.json** — 任务上下文： +```json +{ + "task_id": "task-20260514-001", + "title": "均线策略回测", + "goal": "对双均线交叉策略在沪深300上进行5年回测", + "intent": "验证该策略在A股市场的有效性", + "end_state": "回测报告完整，包含收益曲线、最大回撤、夏普比率", + "constraints": [ + "数据范围：2020-2025", + "标的：沪深300指数", + "初始资金：100万" + ], + "state": "executing", // exploring → planning → executing → reviewing → completed + "phase": 3, // 当前四相阶段 + "created_at": "2026-05-14T08:00:00+08:00", + "updated_at": "2026-05-14T08:15:00+08:00", + "parent_task": null, // 子任务指向父任务 + "tags": ["backtest", "strategy", "moving-average"], + "confidence": 0.0 // 庞统对"需求理解程度"的自评 +} +``` + +**moments.jsonl** — 原子事件流（每行一个 JSON）： +```json +{"type":"task_created","ts":"...","agent":"pangtong","data":{"goal":"..."}} +{"type":"requirement_clarified","ts":"...","agent":"pangtong","data":{"clarifications":[...]}} +{"type":"plan_generated","ts":"...","agent":"pangtong","data":{"plan_id":"p1","steps":5}} +{"type":"plan_approved","ts":"...","agent":"pangtong","data":{"approved_by":"user"}} +{"type":"agent_assigned","ts":"...","agent":"pangtong","data":{"agent":"zhaoyun","step":"s1"}} +{"type":"agent_started","ts":"...","agent":"zhaoyun","data":{"step":"s1"}} +{"type":"artifact_produced","ts":"...","agent":"zhaoyun","data":{"file":"data.csv","summary":"5年日线数据","confidence":0.95}} +{"type":"agent_completed","ts":"...","agent":"zhaoyun","data":{"step":"s1","status":"success"}} +{"type":"anomaly_detected","ts":"...","agent":"pangtong","data":{"type":"data_quality","severity":"warning"}} +{"type":"plan_adjusted","ts":"...","agent":"pangtong","data":{"reason":"数据质量问题","added_step":{...}}} +{"type":"consensus_reached","ts":"...","agent":"pangtong","data":{"result":"回测通过"}} +{"type":"task_completed","ts":"...","agent":"pangtong","data":{"final_state":"success"}} +``` + +**plan.json** — 动态计划图谱： +```json +{ + "plan_id": "p1", + "task_id": "task-20260514-001", + "version": 3, + "steps": [ + { + "id": "s1", + "type": "data_fetch", + "intent": "获取沪深300的5年日线数据", + "end_state": "数据文件就绪，通过质量检查", + "constraints": ["使用AKShare", "保存为CSV"], + "agent": "zhaoyun", + "status": "completed", + "artifacts": ["data/hs300_daily.csv"], + "started_at": "...", + "completed_at": "...", + "confidence": 0.95 + }, + { + "id": "s2", + "type": "strategy_implementation", + "intent": "实现双均线交叉策略", + "end_state": "策略代码可运行，通过单元测试", + "constraints": ["使用vnpy框架", "参数可配置"], + "agent": "zhangfei", + "status": "executing", + "depends": ["s1"], + "started_at": "..." + }, + { + "id": "s2.5", + "type": "data_cleaning", + "intent": "清洗异常数据点", + "end_state": "异常值处理完毕，数据连续无缺失", + "agent": "zhaoyun", + "status": "pending", + "depends": [], + "added_dynamically": true, + "add_reason": "s1 完成后发现数据有缺失值" + } + ], + "changelog": [ + {"version":1,"change":"初始计划","ts":"..."}, + {"version":2,"change":"添加 s2.5 数据清洗步骤","reason":"发现数据质量问题","ts":"..."}, + {"version":3,"change":"调整 s3 约束","reason":"用户要求改为vnpy框架","ts":"..."} + ] +} +``` + +**agent-registry.json** — Agent 能力画像： +```json +{ + "agents": { + "zhaoyun-data": { + "name": "赵云", + "role": "数据总管", + "capabilities": ["data_fetch", "data_cleaning", "data_validation", "quality_check"], + "tools": ["exec", "read", "write", "web_fetch"], + "model_preference": "auto", + "max_parallel_tasks": 1, + "priority": 2, + "performance": { + "tasks_completed": 42, + "avg_confidence": 0.91, + "avg_duration_minutes": 8, + "strengths": ["data_quality", "python"], + "last_active": "..." + }, + "session_key": "agent:zhaoyun-data:main" + }, + "zhangfei-dev": { + "name": "张飞", + "role": "编码先锋", + "capabilities": ["coding", "backtest", "strategy_implementation", "scripting"], + "tools": ["exec", "read", "write", "edit"], + "model_preference": "auto", + "max_parallel_tasks": 1, + "priority": 1, + "performance": { ... }, + "session_key": "agent:zhangfei-dev:main" + }, + "guanyu-dev": { + "name": "关羽", + "role": "风控守将", + "capabilities": ["risk_check", "position_sizing", "stop_loss", "live_audit"], + "tools": ["exec", "read", "write", "edit"], + "model_preference": "auto", + "max_parallel_tasks": 1, + "priority": 3, // 风控最高优先级 + "performance": { ... }, + "session_key": "agent:guanyu-dev:main" + }, + "simayi-challenger": { + "name": "司马懿", + "role": "质量总监", + "capabilities": ["code_review", "challenge", "final_acceptance"], + "tools": ["exec", "read", "write", "edit"], + "model_preference": "auto", + "max_parallel_tasks": 1, + "priority": 2, + "performance": { ... }, + "session_key": "agent:simayi-challenger:main" + }, + "jiangwei-infra": { + "name": "姜维", + "role": "平台总督", + "capabilities": ["deployment", "docker", "nas", "backtest_server", "vnpy"], + "tools": ["exec", "read", "write", "edit"], + "model_preference": "auto", + "max_parallel_tasks": 1, + "priority": 1, + "performance": { ... }, + "session_key": "agent:jiangwei-infra:main" + } + } +} +``` + +**decisions.jsonl** — 决策记录（不可变）： +```json +{"ts":"...","agent":"pangtong","decision":"assign_s2_to_zhangfei","reason":"张飞擅长策略编码","alternatives_considered":["关羽(风控优先)"]} +{"ts":"...","agent":"pangtong","decision":"add_s2.5","reason":"数据清洗步骤缺失","trigger":"s1 confidence=0.7 低于阈值"} +``` + +#### 2.1.3 写入保护：propose → validate → commit + +借鉴 Network-AI 的三阶段原子写入： + +``` +Agent A: + 1. propose: 写入 agents/{agent-id}/proposed/{change-id}.json + 包含：target_path, proposed_content, priority, reason + +Control Unit (庞统): + 2. validate: + a. 格式校验（JSON schema） + b. 冲突检测（target 是否被其他 propose 锁定） + c. 优先级检查（是否有更高优先级的 propose） + d. 业务校验（状态流转是否合法） + + 3. commit: + a. 获取文件锁 (locks/{resource}.lock) + b. 原子写入（tmp → rename） + c. 追加 Moment 事件 + d. 释放锁 + + 或 abort: + a. 记录拒绝原因 + b. 通知提议 Agent +``` + +**简化规则**： +- Agent 对自己工作区（`agents/{agent-id}/`）的写入：**自动 commit**，不需要 propose +- Agent 对共享区域（`artifacts/`, `plan.json`, `context.json`）的写入：**必须 propose → commit** +- Agent 对其他 Agent 工作区的写入：**禁止**（覆盖保护原则） + +#### 2.1.4 文件锁实现 + +借鉴 ClawTeam 的 fcntl + 原子 rename： + +```python +import fcntl, tempfile, os +from pathlib import Path + +def atomic_write(path: Path, content: str): + """原子写入：先写临时文件，再 rename""" + path.parent.mkdir(parents=True, exist_ok=True) + fd, tmp = tempfile.mkstemp(dir=path.parent, prefix=f"{path.stem}-", suffix=".tmp") + with os.fdopen(fd, 'w') as f: + f.write(content) + Path(tmp).replace(path) # atomic on same filesystem + +class BlackboardLock: + """文件系统互斥锁""" + def __init__(self, lock_dir: Path): + self.lock_dir = lock_dir + + def acquire(self, resource: str, holder: str, timeout_ms=10000) -> bool: + lock_path = self.lock_dir / f"{resource.replace('/', '_')}.lock" + lock_path.parent.mkdir(parents=True, exist_ok=True) + start = time.monotonic() + while (time.monotonic() - start) * 1000 < timeout_ms: + try: + fd = os.open(str(lock_path), os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) + os.write(fd, json.dumps({"holder": holder, "acquired_at": time.time()}).encode()) + os.close(fd) + return True + except FileExistsError: + # stale lock check (> 30s) + age = time.time() - lock_path.stat().st_mtime + if age > 30: + lock_path.unlink(missing_ok=True) + time.sleep(0.1) + return False + + def release(self, resource: str, holder: str): + lock_path = self.lock_dir / f"{resource.replace('/', '_')}.lock" + if lock_path.exists(): + data = json.loads(lock_path.read_text()) + if data.get("holder") == holder: + lock_path.unlink() +``` + +--- + +### 2.2 Control Unit（庞统 AI 指挥官） + +#### 2.2.1 四相循环 + +``` +Phase 1: 需求探索 +├── 苏格拉底对话，帮用户发现真实需求 +├── 歧义评分（0-1），高歧义时深入追问 +├── 输出：context.json（goal/intent/end_state/constraints） +├── 自评 confidence，>0.8 才进入 Phase 2 +└── 人的参与：🔴 高（全程对话） + +Phase 2: 动态规划 +├── 根据 context.json 生成 plan.json +├── AI 挑战：庞统自己审视计划的弱点 +├── 三方共识（可选）：庞统+司马懿+用户审核 +├── Plan 审批：用户确认后才执行 +├── 人的参与：🟡 可选（简单任务可跳过审批） +└── 输出：plan.json（version 1） + +Phase 3: 自主执行 +├── 按 plan.json 调度 Agent +├── 每步执行： +│ ├── 选择 Agent（能力画像匹配） +│ ├── 注入任务上下文（Fidelity 按角色） +│ ├── Agent 写入黑板 +│ ├── 幻觉门控（验证产出存在） +│ ├── 异常检测（超时/质量低/Agent 崩溃） +│ └── 动态调整计划（如需） +├── /goal Ralph Loop：跨 turn 保持目标专注 +├── 人的参与：🟢 几乎不参与（可随时介入 steer） +└── 输出：artifacts/ + moments 流 + +Phase 4: 主动汇报 +├── AI 推送进展摘要（不等人查） +├── 验收：庞统自审 + 司马懿终审 +├── 经验沉淀：提取关键经验写入 experience/ +├── 人的参与：🔵 验收 +└── 输出：最终报告 + experience 条目 +``` + +#### 2.2.2 庞统的运行模式 + +**事件驱动 + 持久 session**： + +``` +庞统 session 始终在线（OpenClaw persistent session） + +触发方式： +1. 用户发消息 → 直接在 session 中处理 +2. Agent 写入黑板 → cron 定期扫描黑板变化 → wake 庞统 +3. Agent 完成/失败 → 写入 moments → wake 庞统 +4. 异常检测 → cron 检查 → wake 庞统 +5. 用户 steer（中途干预）→ 直接注入 session + +空闲时： +- 不消耗资源 +- 被 wake 事件唤醒后立即恢复上下文 +- 通过黑板恢复状态（不需要重载全部历史） +``` + +#### 2.2.3 信息路由（Fidelity 三档） + +```python +def route_information(target_agent: str, task_ctx: dict, moments: list) -> dict: + """根据目标 Agent 的角色，选择合适的信息保真度""" + role = get_agent_role(target_agent) + + if role == "control_unit": # 庞统自己 + return { + "fidelity": "full", + "context": task_ctx, + "moments": moments, # 全量事件 + "artifacts": all_artifacts, # 全部产出物 + "agent_states": all_agent_states # 所有Agent状态 + } + + elif role in get_collaborators(task_ctx): # 同任务协作伙伴 + return { + "fidelity": "summary", + "context": task_ctx, # 完整任务上下文 + "relevant_steps": filter_relevant(moments, target_agent), + "artifacts": get_dependent_artifacts(target_agent), + "summary": ai_summarize(moments) # AI 压缩摘要 + } + + else: # 外围 Agent + return { + "fidelity": "signal", + "action_required": get_pending_actions(target_agent), + "final_result": task_ctx.get("result"), + "notification": True + } +``` + +#### 2.2.4 Agent 选择算法 + +```python +def select_agent(step: dict, registry: dict) -> str: + """根据步骤需求和Agent能力画像选择最合适的Agent""" + required_caps = step.get("required_capabilities", infer_caps(step)) + + candidates = [] + for agent_id, profile in registry["agents"].items(): + # 能力匹配 + cap_overlap = len(set(required_caps) & set(profile["capabilities"])) + if cap_overlap == 0: + continue + + # 可用性检查 + if profile["performance"]["tasks_in_progress"] >= profile["max_parallel_tasks"]: + continue + + # 评分：能力匹配度 * 历史表现 * 当前空闲度 + score = ( + cap_overlap / len(required_caps) * 0.4 + # 能力匹配 + profile["performance"]["avg_confidence"] * 0.3 + # 历史表现 + (1 - profile["performance"]["tasks_in_progress"] / + profile["max_parallel_tasks"]) * 0.3 # 当前空闲度 + ) + candidates.append((agent_id, score)) + + if not candidates: + return None # 需要排队或调整计划 + + return max(candidates, key=lambda x: x[1])[0] +``` + +--- + +### 2.3 Agent 层 + +#### 2.3.1 Agent 工作流程 + +``` +1. 接收任务 + ├── 庞统通过 OpenClaw sessions_send 发送任务消息 + ├── 消息包含：step intent + end_state + constraints + 相关黑板内容 + └── 不包含：完整计划、其他Agent的详情（Fidelity 控制） + +2. 执行任务 + ├── 读取黑板中自己需要的上下文 + ├── 执行实际工作（编码/数据分析/风控检查等） + ├── 写入产出到 agents/{agent-id}/output/ + └── 追加 Moments 事件 + +3. 提交产出 + ├── propose 共享产出物到 artifacts/ + ├── 庞统 validate + commit + ├── 自评 [confidence: 0.X] + └── 元认知：confidence < 0.6 时推荐人工审核 + +4. 等待下一步 + ├── 庞统根据执行结果决定下一步 + └── Agent 进入空闲状态 +``` + +#### 2.3.2 Agent 行为注入 + +每个 Agent 的 SOUL.md / prompt 中注入**Boids 协作规则**： + +```markdown +## 协作规则（Boids 群体智能） +1. **Separation（不重复）**：开始工作前检查黑板，确认没有其他 Agent 在做相同的事 +2. **Alignment（风格一致）**：遵循团队的编码规范、产出格式、命名约定 +3. **Cohesion（主动共享）**：发现重要信息时主动写入黑板共享区域 +4. **Boundary（不越界）**：只在自己的工作区和共享区域操作，不修改其他 Agent 的产出 +``` + +以及**元认知自评**： + +```markdown +## 自评要求 +完成任务后，标注置信度： +- `[confidence: 0.X]` 其中 X 为 0-10 +- confidence < 0.6 时说明不确定之处并推荐人工审核 +- 遇到专业外的问题主动上报，不硬撑 +``` + +以及**Auftragstaktik 任务式指挥**： + +```markdown +## 任务执行方式 +你会收到：Intent（意图）、End State（终态）、Constraints（约束） +- 自主决定如何达成目标 +- 可以选择任何合理的方法 +- 但必须遵守所有 Constraints +- 遇到 Constraints 阻碍目标时，上报而不是绕过 +``` + +--- + +### 2.4 事件系统 + +#### 2.4.1 Moments 事件类型 + +```python +class MomentType(str, Enum): + # 任务生命周期 + TASK_CREATED = "task_created" + REQUIREMENT_CLARIFIED = "requirement_clarified" + TASK_COMPLETED = "task_completed" + TASK_FAILED = "task_failed" + + # 计划 + PLAN_GENERATED = "plan_generated" + PLAN_APPROVED = "plan_approved" + PLAN_ADJUSTED = "plan_adjusted" + + # Agent 调度 + AGENT_ASSIGNED = "agent_assigned" + AGENT_STARTED = "agent_started" + AGENT_COMPLETED = "agent_completed" + AGENT_FAILED = "agent_failed" + AGENT_BLOCKED = "agent_blocked" + + # 产出 + ARTIFACT_PRODUCED = "artifact_produced" + ARTIFACT_VALIDATED = "artifact_validated" + + # 决策 + DECISION_MADE = "decision_made" + CHALLENGE_RAISED = "challenge_raised" + CHALLENGE_VERDICT = "challenge_verdict" + + # 异常 + ANOMALY_DETECTED = "anomaly_detected" + TIMEOUT_WARNING = "timeout_warning" + + # 用户交互 + USER_STEER = "user_steer" + USER_APPROVED = "user_approved" + USER_REJECTED = "user_rejected" + + # 经验 + EXPERIENCE_CAPTURED = "experience_captured" +``` + +#### 2.4.2 事件驱动唤醒 + +```python +# 庞统的唤醒条件 +WAKE_CONDITIONS = { + # 黑板变化检测（cron 每 30s 扫描） + "blackboard_change": { + "trigger": "moments.jsonl 有新行", + "action": "wake pangtong session", + "context": "新增的 moments" + }, + # Agent 完成 + "agent_completed": { + "trigger": "agents/{id}/state.json status=completed", + "action": "wake pangtong", + "context": "agent_id + step_id" + }, + # 超时检测 + "step_timeout": { + "trigger": "step started_at + 30min < now", + "action": "wake pangtong with alert", + "context": "step_id + duration" + }, + # 用户消息 + "user_message": { + "trigger": "inbox/ 有新文件", + "action": "wake pangtong", + "context": "消息内容" + } +} +``` + +--- + +### 2.5 经验沉淀系统 + +#### 2.5.1 闭环学习 + +``` +DISCOVER（发现） +├── 任务执行过程中 Agent 发现好做法 +├── 异常处理中发现新模式 +└── 写入 blackboard/tasks/{id}/agents/{id}/discoveries.json + +DISTILL（蒸馏） +├── 任务完成后庞统自动提取关键转折点 +├── 从 decisions.jsonl + moments.jsonl 提炼经验 +├── 压缩为经验条目：{pattern, context, outcome, applicability} +└── 写入 blackboard/global/experience/{domain}.jsonl + +APPLY（应用） +├── 新任务开始时，庞统检索相关经验 +├── 按任务类型+标签匹配 +├── 注入 Agent prompt 作为参考 +└── 标记"来自经验 X" + +IMPROVE（改进） +├── 验证经验是否真的有效 +├── 无效经验标记 deprecated +├── 有效经验提升 confidence +└── 定期合并相似经验 +``` + +#### 2.5.2 经验数据结构 + +```json +{ + "id": "exp-001", + "pattern": "数据清洗应在策略编码前完成", + "context": "量化策略开发任务", + "outcome": "减少返工率 40%", + "applicability": ["backtest", "strategy_development"], + "source_task": "task-20260514-001", + "confidence": 0.85, + "times_applied": 3, + "times_validated": 2, + "created_at": "...", + "last_validated_at": "..." +} +``` + +--- + +### 2.6 监控与运维 + +#### 2.6.1 健康检查 + +```python +class HealthChecker: + """定期检查黑板和 Agent 健康状态""" + + checks = [ + # Agent 存活检测 + "agent_heartbeat", # 检查 state.json 更新时间 + "agent_zombie", # 运行超过 2 小时的 Agent + "agent_stale_lock", # 超过 30 秒的锁 + + # 任务健康 + "step_timeout", # 步骤超时 + "plan_stuck", # 计划卡住（所有 pending 步骤都有未完成的依赖） + "artifact_missing", # Agent 声称产出但文件不存在（幻觉门控） + + # 系统健康 + "blackboard_disk", # 磁盘空间 + "moment_flood", # 事件洪泛检测 + ] +``` + +#### 2.6.2 Token 成本治理 + +借鉴 Network-AI FederatedBudget + ClawTeam 成本追踪： + +```python +class TokenBudget: + """Token 预算管理""" + + def __init__(self): + self.global_ceiling = 500_000 # 每任务全局上限 + self.per_agent_ceiling = 100_000 # 每 Agent 上限 + self.spent = {} # agent_id → tokens used + + def check(self, agent_id: str, estimated: int) -> bool: + total = sum(self.spent.values()) + if total + estimated > self.global_ceiling: + return False # 全局预算不足 + if self.spent.get(agent_id, 0) + estimated > self.per_agent_ceiling: + return False # Agent 预算不足 + return True +``` + +--- + +## 3. 技术实现方案 + +### 3.1 技术栈 + +| 层级 | 技术 | 说明 | +|------|------|------| +| Agent 运行时 | **OpenClaw Gateway** | 已有的 session 管理、agent 调度、工具执行 | +| Agent 通信 | **Blackboard 文件系统** | JSON/JSONL/Markdown，git 可追踪 | +| 指挥官 | **庞统 persistent session** | OpenClaw session + cron wake | +| Agent 调度 | **sessions_send / sessions_spawn** | OpenClaw 原生能力 | +| 文件锁 | **fcntl / O_EXCL** | 零依赖，跨进程安全 | +| 事件驱动 | **cron 扫描 + wake** | OpenClaw 原生能力 | +| 前端 | **OpenClaw Control Center + 自定义 UI** | 对话式入口 | +| 数据存储 | **文件系统** | 不引入数据库，保持简单 | +| 经验检索 | **ripgrep** | 文本搜索，无额外依赖 | +| 同步 | **sanguo_git_sync** | 已有的三端 Git 同步 | + +### 3.2 核心代码模块 + +``` +sanguo_moziplus_v2/ +├── blackboard/ # 共享意识空间（数据目录，git 追踪） +├── daemon/ # 守护进程 +│ ├── main.py # 入口 +│ ├── blackboard.py # Blackboard 读写 API +│ ├── lock.py # 文件锁实现 +│ ├── health.py # 健康检查 +│ ├── budget.py # Token 预算管理 +│ ├── experience.py # 经验沉淀引擎 +│ └── scanner.py # 黑板变化扫描器 +├── skills/ # Skill 包 +│ ├── control-unit/ # 庞统指挥官 Skill +│ │ └── SKILL.md # 四相循环 prompt + 路由逻辑 +│ ├── agent-bootstrap/ # Agent 引导 Skill +│ │ └── SKILL.md # Boids 规则 + 元认知 + Auftragstaktik 注入 +│ └── wiki-query/ # 复用已有 wiki 查询 Skill +├── config/ +│ ├── agent-registry.json # Agent 能力画像 +│ └── settings.json # 全局配置 +├── docs/ +│ ├── design/ # 设计文档 +│ └── research/ # 调研报告 +├── scripts/ +│ ├── create-task.py # CLI: 创建任务 +│ ├── status.py # CLI: 查看状态 +│ └── bootstrap.sh # 初始化脚本 +└── README.md +``` + +### 3.3 关键交互流程 + +#### 流程 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 能力） + │ ├── sessions_send 给赵云 + │ ├── 赵云执行，写入 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. scanner 通过 cron wake 庞统 +3. 庞统： + a. 检查赵云 session 是否存活（sessions_list） + b. 存活 → steer 赵云（sessions_send "进度如何？"） + 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.4 与 OpenClaw 的集成点 + +| v2.0 功能 | OpenClaw 能力 | 集成方式 | +|-----------|--------------|----------| +| Agent 调度 | sessions_send / sessions_spawn | 直接调用 | +| 指挥官持久化 | persistent session | 庞统 session 保持在线 | +| 事件唤醒 | cron wake + systemEvent | 定期扫描黑板 + wake | +| Agent 间通信 | ~~sessions_send~~ → **Blackboard** | Agent 读写黑板，不走邮件 | +| 文件操作 | read / write / edit | 直接操作黑板文件 | +| 前端交互 | webchat | 用户通过对话入口交互 | +| 成本控制 | session_status | 获取 token 消耗 | +| 知识检索 | wiki-query skill | 复用已有 skill | + +--- + +## 4. 开放问题（需讨论） + +| # | 问题 | 选项 | 建议 | +|---|------|------|------| +| 1 | 黑板用文件系统还是 SQLite？ | A) 纯文件系统 B) SQLite + 文件 | A — 简单、可 git 追踪 | +| 2 | 庞统用 persistent session 还是 cron 唤醒？ | A) persistent session B) cron 事件驱动 | B — 更省资源，更稳定 | +| 3 | Agent 团队是继续用三国还是重新定义？ | A) 复用三国 B) 新定义 | A — 角色映射清晰 | +| 4 | v1.0 的 Agent 是否同时服务 v2.0？ | A) 共享 Agent session B) 独立 session | B — 隔离，v1.0 和 v2.0 并行运行 | +| 5 | 前端是什么？ | A) 纯对话（Control Center）B) 对话 + 可视化 | 先 A，后续加 B | +| 6 | 第一版先做什么？ | 见下方里程碑 | — | + +--- + +## 5. 里程碑建议 + +``` +M1: 黑板核心 + 指挥官原型 + ├── blackboard/ 目录结构 + 读写 API + ├── lock.py 文件锁 + ├── moments.jsonl 追加写入 + ├── 庞统 cron 唤醒 + 黑板扫描 + └── 端到端测试：一个简单任务的完整生命周期 + +M2: Agent 调度 + 动态规划 + ├── agent-registry.json 能力画像 + ├── Agent 选择算法 + ├── plan.json 动态计划 + ├── propose→validate→commit 写入保护 + └── 端到端测试：多步骤任务（3个Agent协作） + +M3: 四相完善 + 经验沉淀 + ├── Phase 1 苏格拉底对话 + ├── Phase 2 Plan 审批 + ├── Phase 4 主动汇报 + ├── experience/ 经验沉淀 + ├── 健康检查 + 幻觉门控 + └── 端到端测试：异常场景（超时、Agent崩溃、用户干预） + +M4: 生产化 + ├── 成本治理 + ├── 监控面板 + ├── 文档完善 + ├── 与 v1.0 并行运行验证 + └── 切换：v1.0 → v2.0 +``` + +--- + +## 附录：术语表 + +| 术语 | 含义 | +|------|------| +| Blackboard | 共享意识空间，所有 Agent 的唯一信息共享中枢 | +| Control Unit | AI 指挥官（庞统），负责动态规划、Agent 选择、异常处理 | +| Moment | 原子事件，任务执行过程中的最小信息单元 | +| Fidelity | 信息保真度，控制不同 Agent 看到多少信息 | +| propose→validate→commit | 三阶段原子写入，防止并发竞态 | +| Boids | 群体智能规则，让 Agent 自行涌现协作行为 | +| Auftragstaktik | 任务式指挥，只给目标不给步骤 | +| 幻觉门控 | 验证 Agent 产出是否真实存在 | +| Ralph Loop | 持久目标跨 turn 保持机制 |