From db4a371ef055157bb8a49c81481a42dec8d88d9c Mon Sep 17 00:00:00 2001 From: cfdaily Date: Thu, 14 May 2026 09:18:17 +0800 Subject: [PATCH] auto-sync: 2026-05-14 09:18:17 --- docs/design/architecture-v2.md | 346 ++++++++++++++++++++++++++++++++- 1 file changed, 345 insertions(+), 1 deletion(-) diff --git a/docs/design/architecture-v2.md b/docs/design/architecture-v2.md index 0fb3a70..ff8fb00 100644 --- a/docs/design/architecture-v2.md +++ b/docs/design/architecture-v2.md @@ -1325,16 +1325,360 @@ sub-agent 完成后，archiver 自动把 transcript 归档到任务目录。 | 庞统对话 | 庞统主 session (webchat) | 用户通过 Control Center 对话 | | 庞统查进展 | curl GET daemon API | 实时查询 SQLite，AI 生成汇报 | | 庞统操作任务 | curl POST daemon API | 创建/规划/启动/暂停/恢复任务 | -| Agent 调度 | Gateway WS API → Agent 主 session | 发消息到 agent:xxx:main，不创建 sub-agent | +| Agent 调度 | Gateway WS API → Agent 主 session | 简单步骤发到主 session | +| Agent 调度(复杂) | sessions_spawn + cleanup=delete | 复杂步骤用 sub-agent 隔离 | | Agent 回报 | curl POST daemon API | 完成/失败/进度上报 | | Agent 查黑板 | curl GET daemon API | 查询任务上下文/计划/产出物 | | Daemon 通知庞统 | Gateway WS API systemEvent | 步骤完成/异常/需要裁决时 | | Agent 上下文管理 | Gateway reset | 定期 reset Agent 主 session 防止膨胀 | | 知识检索 | wiki-query skill (Agent 侧) | Agent 需要时可调用 | | 数据持久化 | SQLite (daemon) + 文件系统 (artifacts) | 状态在 SQLite，产出物在文件系统 | +| 执行历史归档 | daemon archiver | sub-agent 完成后 transcript 复制到任务目录 | --- +### 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/ + │ └── ... + │ + ├── 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.10 Daemon API 接口定义 + +> RESTful + JSON，端口 8080（沿用 v1.0）。 +> 所有请求/响应都记录到 moments 表。 + +#### 3.10.1 任务生命周期 API + +``` +POST /api/tasks # 创建任务 +GET /api/tasks/{id} # 查询任务状态 +GET /api/tasks/{id}/status # 轻量状态查询（给庞统用） +PUT /api/tasks/{id}/context # 更新任务上下文 +POST /api/tasks/{id}/plan # 提交执行计划 +POST /api/tasks/{id}/start # 启动执行（Phase 3） +POST /api/tasks/{id}/pause # 暂停 +POST /api/tasks/{id}/resume # 恢复 +POST /api/tasks/{id}/cancel # 取消 +POST /api/tasks/{id}/replan # 重新规划（用户改需求或异常调整） +GET /api/tasks/{id}/moments # 查询事件流 +GET /api/tasks/{id}/decisions # 查询决策记录 +``` + +**POST /api/tasks** — 创建任务 +```json +// Request +{ + "title": "均线策略回测", + "goal": "对沪深300做双均线交叉策略回测", + "constraints": ["5年日线数据", "滑点0.2%"], + "metadata": {} // 可选 +} +// Response +{ + "ok": true, + "task_id": "t-uuid-001", + "state": "exploring" +} +``` + +**GET /api/tasks/{id}/status** — 轻量状态查询（庞统用，返回人类可读摘要） +```json +{ + "task": { "title": "均线策略回测", "state": "executing", "phase": 3 }, + "plan": { + "steps": [ + { "id": "s1", "title": "数据获取", "state": "completed", "agent": "zhaoyun" }, + { "id": "s2", "title": "策略编码", "state": "executing", "agent": "zhangfei" } + ], + "completed": 1, "total": 4 + }, + "current_step": { + "id": "s2", "agent": "zhangfei", "started_at": "...", + "progress": null // Agent 可选上报进度 + }, + "recent_moments": [ + { "type": "step_completed", "agent": "zhaoyun", "summary": "数据获取完成" } + ], + "anomalies": [], + "token_budget": { "used": 120000, "limit": 500000 } +} +``` + +#### 3.10.2 步骤执行 API + +``` +POST /api/steps/{id}/assign # 分配 Agent +POST /api/steps/{id}/start # 标记开始执行 +POST /api/steps/{id}/complete # Agent 回报完成 +POST /api/steps/{id}/fail # Agent 回报失败 +POST /api/steps/{id}/block # Agent 回报阻塞 +POST /api/steps/{id}/progress # Agent 上报进度（可选） +POST /api/steps/{id}/escalate # Agent 请求人工介入 +GET /api/steps/{id} # 查询步骤详情 +GET /api/steps/{id}/output # 查询步骤产出 +``` + +**POST /api/steps/{id}/complete** — Agent 回报完成 +```json +// Request +{ + "artifacts": [ + { "path": "artifacts/task-xxx/steps/s1/hs300_daily.csv", "type": "data", "size_bytes": 1048576 } + ], + "confidence": 0.95, + "summary": "获取沪深300 5年日线数据，共1218条记录，含缺失值处理报告" +} +// Response +{ + "ok": true, + "state": "completed", + "validation": { + "files_exist": true, + "sizes_reasonable": true, + "passed": true + } +} +``` + +**POST /api/steps/{id}/fail** — Agent 回报失败 +```json +// Request +{ + "error": "数据源返回403，权限不足", + "retry_suggested": true, + "partial_artifacts": [] +} +``` + +#### 3.10.3 查询 & 管理API + +``` +GET /api/agents # 所有 Agent 状态 +GET /api/agents/{id}/status # 单个 Agent 状态 +POST /api/agents/{id}/heartbeat # Agent 心跳 + +GET /api/experiences # 经验检索（给 AI 用） +POST /api/experiences # 写入经验 + +GET /api/health # Daemon 健康检查 +GET /api/stats # 统计信息（任务数、成功率等） +``` + +**GET /api/experiences** — 经验检索 +```json +// Query: ?tags=data_cleaning,backtest&limit=5 +{ + "experiences": [ + { + "id": 1, + "source_task": "t-uuid-001", + "category": "pitfall", + "title": "数据缺失值必须在策略编码前处理", + "content": "...", + "tags": ["data_cleaning", "backtest"], + "relevance_score": 0.92 + } + ] +} +``` + +#### 3.10.4 AI Native 扩展 API + +``` +POST /api/tasks/{id}/steer # 用户中途改方向（不改 goal） +POST /api/tasks/{id}/takeover/{step_id} # 用户接管某步骤 +POST /api/tasks/{id}/intervene # 用户主动干预 +POST /api/steps/{id}/review # 触发 challenge 审查 +POST /api/tasks/{id}/distill # 触发经验蒸馏 +``` + +**POST /api/tasks/{id}/steer** — 用户改方向 +```json +// Request +{ + "direction": "改用MACD策略", + "reason": "用户要求", + "affected_steps": ["s2"] // 哪些步骤受影响（可选，AI自动判断） +} +// Response +{ + "ok": true, + "action": "replanning", + "paused_steps": ["s2"], + "message": "正在重新规划受影响的步骤..." +} +``` + +--- + +### 3.11 经验沉淀引擎 + +> 每次任务完成后自动触发，提取可复用的经验存入经验库。 + +#### 3.11.1 沉淀流程 + +``` +任务完成 + │ + ▼ +Daemon 检测到任务 state = completed + │ + ▼ +Daemon 通过 Gateway 触发 AI session 做经验蒸馏 + - 输入: task context + plan + 所有 steps 的 transcript.jsonl + moments + - AI 分析： + 1. 哪些决策是好的？（pattern） + 2. 哪些坑踩了？（pitfall） + 3. 有什么可复用的做法？（best_practice） + 4. 工具使用技巧？（tool_usage） + - 输出: 3-5 条经验 + │ + ▼ +Daemon 写入 SQLite experiences 表 + 生成 experience.md + │ + ▼ +下次创建类似任务时，Daemon 自动检索相关经验注入 context +``` + +#### 3.11.2 经验检索时机 + +| 时机 | 触发者 | 检索内容 | +|------|--------|----------| +| Phase 2 规划 | Daemon | 检索与任务 goal 相关的经验，注入 plan 上下文 | +| Phase 3 Agent 选择 | Daemon | 检索与步骤类型相关的经验（如"这类任务哪个 Agent 做得好"） | +| Agent 执行前 | Daemon | 注入与步骤相关的经验到 task 描述 | +| 异常处理 | Daemon/庞统 | 检索类似异常的历史处理方式 | + ## 4. 已决策 & 待讨论 ### 已决策