cfdaily
1989 lines
90 KiB
Markdown
1989 lines
90 KiB
Markdown
# AI Native DevOps Platform 架构设计 v3.0
|
||
|
||
**版本**: v3.0（PRD 3.0 对齐版）
|
||
**基于**: PRD-v3.0 + architecture-v2.6 + v2.7~v3.0 增量设计 + 实际源码回溯
|
||
**作者**: 庞统（副军师）
|
||
**日期**: 2026-05-28（最后更新 2026-06-04）
|
||
**状态**: v3.0 正式版（T1 清理完成，T 阶段规划已补充）
|
||
|
||
---
|
||
|
||
## §1. 版本信息和变更历史
|
||
|
||
### 1.1 版本演进
|
||
|
||
| 版本 | 日期 | 变更内容 |
|
||
|------|------|---------|
|
||
| v2.0 | 2026-05-04 | 初始版本：SQLite 4表 + 状态机 + DAG 引擎 |
|
||
| v2.6 | 2026-05-15 | 架构重构：Shared Workspace(Blackboard) 取代 DAG 引擎 |
|
||
| v2.6.1 | 2026-05-15 | 司马懿评审 + Mail 退役 + 质量门控 + 决策记录 |
|
||
| v2.6.2 | 2026-05-15 | 三层执行模型 + 续杯机制 + Guardrail 体系 |
|
||
| v2.6.3 | 2026-05-15 | 事件驱动 + Inbox JSONL + 依赖驱动 |
|
||
| v2.6.4 | 2026-05-15 | 分级审查流水线 + 反驳权 + reviews 表 |
|
||
| v2.6.5 | 2026-05-15 | 模板组件库 + 四层上下文架构 (L0-L3) |
|
||
| v2.6.7 | 2026-05-15 | 经验沉淀闭环 |
|
||
| v2.7 | 2026-05-18 | Card 层回滚 → Task 自引用 SubTask 模型 |
|
||
| v2.8 | 2026-05-18 | 3 新状态 (paused/escalated/waiting_human) + 归档机制 |
|
||
| v2.7.2 | 2026-05-26 | 防重复调用 & 防无限续杯 + counter v2.1 |
|
||
| v3.0 | 2026-05-28 | **本版**：PRD 3.0 对齐 + 源码回溯 + 完整现状记录 |
|
||
| v3.0.1 | 2026-05-28 | 补充6个讨论话题（§6.5/§10.4~10.6）+ 新增§21 T阶段规划（T1~T6） |
|
||
| v3.0.2 | 2026-05-29 | §12.3 Mail API 防御 + Prompt 约束设计（纳入司马懿评审意见）；§6.5 补充 spawn 改造方向 |
|
||
| v3.0.3 | 2026-05-30 | §6.3.1 Session Lock 实测结论 + L3a/L3b/L3c 有效性分析 + Bug 修复（outcome 白名单 + 详细日志） |
|
||
| v3.0.4 | 2026-06-04 | 新增 §22 Pipeline 强工作流设计（TODO）+ §8.1 Router 标注 TODO |
|
||
|
||
### 1.2 v3.0 定位
|
||
|
||
本文档是基于 PRD-v3.0 和实际源码的回溯性架构文档。目的：
|
||
|
||
1. **以 PRD 3.0 为准绳**，记录系统的设计目标
|
||
2. **以代码实际状态为事实**，记录已实现和未实现的功能
|
||
3. **记录所有设计矛盾和差异**，作为后续迭代的输入
|
||
4. **不盲从旧设计（v2.6）**，以 7 条分类原则确定每项功能的真实状态
|
||
|
||
### 1.3 7 条分类原则
|
||
|
||
| # | 情况 | 处理 | 标记 |
|
||
|---|------|------|------|
|
||
| 1 | PRD ✅ + 代码 ✅ + 设计 ✅ | 直进 v3.0 | ✅ **已实现** |
|
||
| 2 | PRD ✅ + 代码 ❌ + 设计 ❌ | v3.0 标"待实现" | ❌ **未实现** |
|
||
| 3 | 调研/专题 ✅ + PRD ✅ + 代码 ❌ | v3.0 标"待实现" | ❌ **未实现** |
|
||
| 4 | 调研 ✅ + PRD ❌ | 标记为 PRD 新增项 | 📋 **PRD 待升级** |
|
||
| 5 | 代码 ✅ + PRD ❌ + 设计 ❌ | 找来源 → 归入1~3 或标"幽灵实现" | 👻 **幽灵实现** |
|
||
| 6 | 设计文档间矛盾 | 以 PRD 为准 | 🔀 **矛盾** |
|
||
| 7 | 调研有但 PRD 不值得进 | 归档保留，不进 v3.0 | 📦 **归档** |
|
||
|
||
---
|
||
|
||
## §2. 架构总览
|
||
|
||
### 2.1 核心变革：从 DAG 状态机到 Shared Workspace
|
||
|
||
v2.0 的核心是 **DAG 引擎 + 状态机 + 邮件通信**，本质是给 AI 团队做 ERP。v2.6+ 变革为 **Shared Workspace (Blackboard) + Agent 自主决策 + Daemon 投递**。
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 用户 / 触发器 │
|
||
│ (Web Dashboard / CLI / Agent 对话) │
|
||
└──────────────────────────┬──────────────────────────────────┘
|
||
│ HTTP API / Agent 对话
|
||
┌──────────────────────────▼──────────────────────────────────┐
|
||
│ FastAPI (端口 8083) │
|
||
│ ┌───────────────┐ ┌──────────────┐ ┌──────────────────┐ │
|
||
│ │ blackboard │ │ mail_routes │ │ project_routes │ │
|
||
│ │ _routes.py │ │ (Mail Tab) │ │ (项目管理) │ │
|
||
│ └───────┬───────┘ └──────┬───────┘ └────────┬─────────┘ │
|
||
│ └────────────┬────┘ │ │
|
||
└───────────────────────┼─────────────────────────┼───────────┘
|
||
│ SQLite │ registry.db
|
||
┌───────────────────────▼─────────────────────────▼───────────┐
|
||
│ Shared Workspace (黑板) │
|
||
│ ┌────────────────────────────────────────────────────────┐ │
|
||
│ │ per-project blackboard.db (SQLite WAL) │ │
|
||
│ │ tasks / comments / outputs / decisions / observations │ │
|
||
│ │ events / reviews / task_attempts / checkpoints │ │
|
||
│ └────────────────────────────────────────────────────────┘ │
|
||
│ ┌──────────────┐ │
|
||
│ │ registry.db │ ← 多项目注册表 (ProjectRegistry) │ │
|
||
│ └──────────────┘ │
|
||
└──────────────────────────┬──────────────────────────────────┘
|
||
│ Daemon tick (30s) + Inbox JSONL (1s)
|
||
┌──────────────────────────▼──────────────────────────────────┐
|
||
│ Daemon (管家) │
|
||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │
|
||
│ │ Ticker │ │ Dispatcher │ │ Spawner │ │
|
||
│ │ 30s 主循环 │ │ 路由决策+执行│ │ 进程管理+监控 │ │
|
||
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────────┘ │
|
||
│ │ │ │ │
|
||
│ ┌──────▼───────┐ ┌──────▼───────┐ ┌──────▼───────────┐ │
|
||
│ │ Router │ │ Counter │ │ Guardrails │ │
|
||
│ │ 确定性路由 │ │ 并发控制 │ │ 安全红线引擎 │ │
|
||
│ └──────────────┘ └──────────────┘ └──────────────────┘ │
|
||
│ │
|
||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │
|
||
│ │ Health │ │ Experience │ │ InboxWatcher │ │
|
||
│ │ 僵尸检测 │ │ 经验蒸馏 │ │ 秒级事件推送 │ │
|
||
│ └──────────────┘ └──────────────┘ └──────────────────┘ │
|
||
│ │
|
||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │
|
||
│ │ Bootstrap │ │ SSE Broker │ │ ReviewPipeline │ │
|
||
│ │ 上下文构建 │ │ 实时推送 │ │ 产出验证流水线 │ │
|
||
│ └──────────────┘ └──────────────┘ └──────────────────┘ │
|
||
└──────────────────────────┬──────────────────────────────────┘
|
||
│ openclaw agent --agent <id> --session-id <uuid>
|
||
┌──────────────────────────▼──────────────────────────────────┐
|
||
│ Agent 层 (将军们) │
|
||
│ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │
|
||
│ │庞统 │ │司马懿│ │姜维 │ │关羽 │ │张飞 │ │赵云 │ │
|
||
│ │策划 │ │质量 │ │平台 │ │风控 │ │编码 │ │数据 │ │
|
||
│ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ │
|
||
│ 每个 Agent: SOUL.md + IDENTITY.md + Skills + Workspace │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 2.2 核心原则 ✅
|
||
|
||
> **黑板是唯一真相源，所有 agent 读它、想、行动，写回结果。Daemon 是投递员，不是决策者。**
|
||
|
||
| # | 原则 | 实现状态 |
|
||
|---|------|---------|
|
||
| 1 | Agent 决策，Daemon 执行 | ✅ 已实现 — Router 做确定性路由，模糊场景 delegate 庞统 |
|
||
| 2 | 产出在黑板，不在邮件 | ✅ 已实现 — outputs 表 + content_path 模式 |
|
||
| 3 | Daemon 不阻塞 Agent | ✅ 已实现 — async spawn + counter 并发控制 |
|
||
| 4 | Session 用完即清 | ⚠️ 部分实现 — spawn 隔离 session ✅，jsonl 存档和清理代码存在但未完全集成 |
|
||
| 5 | 双入口，对等地位 | ⚠️ 部分实现 — API ✅，Dashboard 前端存在但 AI Native 化未完成 |
|
||
|
||
### 2.3 v2.0 vs v3.0 对比
|
||
|
||
| 维度 | v1.0 (v2.0 原型) | v3.0 现状 |
|
||
|------|-----------------|----------|
|
||
| 编排核心 | DAG 引擎 + 状态机 | Blackboard (Shared Workspace) |
|
||
| 决策者 | Daemon (状态机驱动) | Agent (确定性路由 + delegate 庞统) |
|
||
| Daemon 角色 | 调度器 | 投递员 + 路由 + 监控 |
|
||
| Agent 通信 | Sanguo Mail (异步邮件) | 黑板 Comment + Mail Tab (兼容保留) |
|
||
| 信息位置 | 分散 | 集中 (per-project SQLite) |
|
||
| 状态机 | 8 个状态 | 11 个状态 (v2.8) |
|
||
| 上下文 | 全量注入 | L0-L3 四层分层 |
|
||
|
||
---
|
||
|
||
## §3. 核心原则（对齐 PRD 四条信念）
|
||
|
||
### 3.1 B1: AI 帮人想清楚要什么 ⚠️
|
||
|
||
| 方面 | PRD 目标 | 实际状态 |
|
||
|------|---------|---------|
|
||
| 苏格拉底式对话 | 需求探索的核心入口 | ✅ 已有 skill — `requirement-clarification`（加权模糊度评分 + 节奏守卫 + 停止守卫） |
|
||
| 多轮需求澄清 | 庞统通过对话帮用户梳理需求 | ✅ 已有 skill — `requirements-analysis`（需求规格化 + 假设标注 + 交付物定义） |
|
||
| 需求探索自动触发 | PRD Phase 1 自动启动 | ❌ 未实现 — Skill 存在但无 Daemon 自动触发机制 |
|
||
|
||
**现状**: Skill 层面完备（`requirement-clarification` + `requirements-analysis` 覆盖需求澄清全流程），但编排层面缺少自动触发。当前依赖 Agent 手动加载 Skill 或用户显式触发。
|
||
|
||
**差距**: 需要一个"需求探索"入口，当用户提一个模糊方向时，自动触发苏格拉底式对话。可在庞统主 session 通过 Skill 匹配实现，或在 Dashboard 新建任务时自动引导。
|
||
|
||
### 3.2 B2: 编排层是 AI 指挥官 ✅
|
||
|
||
| 方面 | PRD 目标 | 实际状态 |
|
||
|------|---------|---------|
|
||
| AI 驱动决策 | 庞统全程指挥 | ✅ 已实现 — Router 模糊场景 delegate 庞统 (v3.0) |
|
||
| 确定性兜底 | 底层执行保障 | ✅ 已实现 — Ticker 30s 循环 + 状态机 |
|
||
| 动态规划 | 计划可演进 | ⚠️ 基础机制存在（任务创建/状态流转），但无活的计划调整 |
|
||
|
||
### 3.3 B3: Agent 共享意识 ✅
|
||
|
||
| 方面 | PRD 目标 | 实际状态 |
|
||
|------|---------|---------|
|
||
| 共享状态空间 | Daemon HTTP API | ✅ 已实现 — FastAPI 端点齐全 |
|
||
| 实时感知 | Agent 按需查询黑板 | ✅ 已实现 — API 契约完整 |
|
||
| 不传消息 | 黑板评论替代邮件 | ✅ 已实现 — comments 表 + @mention |
|
||
|
||
### 3.4 B4: 人退到系统边缘 ✅
|
||
|
||
| 方面 | PRD 目标 | 实际状态 |
|
||
|------|---------|---------|
|
||
| 安全红线拦截 | 危险操作强制人工确认 | ✅ 已实现 — GuardrailEngine 6 条红线 |
|
||
| 关键决策点介入 | escalated/waiting_human 状态 | ✅ 已实现 — v2.8 新增 3 个状态 |
|
||
| SSE 实时推送 | AI 主动汇报 | ✅ 已实现 — SSEBroker + 前端 EventSource |
|
||
|
||
---
|
||
|
||
## §4. 系统架构图
|
||
|
||
### 4.1 数据流
|
||
|
||
```
|
||
用户 (Web/对话)
|
||
│
|
||
├─ POST /api/projects/{pid}/tasks → 创建任务 → blackboard.db
|
||
├─ POST /api/mail → 发送邮件 → _mail/blackboard.db
|
||
├─ GET /api/projects/{pid}/tasks → 查看任务
|
||
│
|
||
▼
|
||
Daemon Ticker (30s 循环)
|
||
│
|
||
├─ 扫描 active 项目
|
||
├─ 依赖推进 (blocked → pending)
|
||
├─ 超时检测 (claimed 5min → pending, working 30min → failed)
|
||
├─ 调度 pending 任务 → Router → Dispatcher → Spawner
|
||
├─ 调度 review 任务 → Router → 匹配审查者
|
||
├─ 僵尸检测 (HealthChecker)
|
||
├─ 父 Task 聚合刷新
|
||
└─ daemon_tick 事件写入
|
||
|
||
▼
|
||
Spawner (进程管理)
|
||
│
|
||
├─ counter acquire (per session key)
|
||
├─ session state 检查 (防 webchat 冲突)
|
||
├─ spawn openclaw agent 进程
|
||
├─ _monitor_process (630s 超时监控)
|
||
│ ├─ A1~A12: 进程退出场景分类
|
||
│ └─ B1~B4: 进程不退出场景分类
|
||
├─ 续杯机制 (Gateway timeout → 复用 session)
|
||
└─ wrapped_on_complete → counter release
|
||
|
||
▼
|
||
Agent 执行
|
||
│
|
||
├─ 读黑板 (GET /tasks, GET /tasks/{id}?expand=all)
|
||
├─ 认领任务 (POST /tasks/{id}/claim) — CAS 原子操作
|
||
├─ 写产出 (POST /tasks/{id}/outputs)
|
||
├─ 写评论 (POST /tasks/{id}/comments)
|
||
├─ 更新状态 (POST /tasks/{id}/status)
|
||
├─ 写观察 (POST /tasks/{id}/observations — 通过 comments)
|
||
└─ 写决策 (POST /tasks/{id}/decisions — 通过 comments)
|
||
```
|
||
|
||
### 4.2 并发控制流
|
||
|
||
```
|
||
Ticker._dispatch_pending()
|
||
│
|
||
├─ 确定性路径:
|
||
│ ├─ retry → 原执行者
|
||
│ ├─ next_capability → 能力匹配
|
||
│ ├─ 有 assignee → 直接分
|
||
│ └─ review 生命周期 → 能力匹配
|
||
│
|
||
└─ 模糊路径 → delegate 庞统
|
||
```
|
||
|
||
---
|
||
|
||
## §5. 数据模型
|
||
|
||
### 5.1 数据库架构 ✅
|
||
|
||
**per-project SQLite**：每个项目独立 `blackboard.db`，全局 `registry.db` 管理项目注册表。
|
||
|
||
#### 5.1.1 tasks 表 ✅
|
||
|
||
```sql
|
||
CREATE TABLE tasks (
|
||
id TEXT PRIMARY KEY,
|
||
title TEXT NOT NULL,
|
||
description TEXT,
|
||
status TEXT NOT NULL DEFAULT 'pending',
|
||
CHECK (status IN ('pending','claimed','working','review','paused',
|
||
'escalated','waiting_human','done','failed',
|
||
'blocked','cancelled')),
|
||
assignee TEXT,
|
||
assigned_by TEXT,
|
||
depends_on TEXT, -- JSON array of task IDs
|
||
parent_task TEXT, -- 父任务 (Task 自引用)
|
||
priority INTEGER NOT NULL DEFAULT 5,
|
||
task_type TEXT,
|
||
created_at TEXT NOT NULL DEFAULT (datetime('now')),
|
||
updated_at TEXT NOT NULL DEFAULT (datetime('now')),
|
||
claimed_at TEXT,
|
||
started_at TEXT,
|
||
completed_at TEXT,
|
||
deadline TEXT,
|
||
retry_count INTEGER NOT NULL DEFAULT 0,
|
||
max_retries INTEGER NOT NULL DEFAULT 2,
|
||
must_haves TEXT, -- JSON
|
||
risk_level TEXT DEFAULT 'standard',
|
||
estimated_duration_minutes INTEGER,
|
||
escalated INTEGER DEFAULT 0,
|
||
current_agent TEXT, -- v2.6.1 路由扩展
|
||
previous_agent TEXT,
|
||
next_capability TEXT,
|
||
stage TEXT, -- v2.7 所属 Stage 标签
|
||
stages_json TEXT DEFAULT '[]', -- v2.7 动态 Stage 定义
|
||
archived INTEGER DEFAULT 0, -- v2.8 归档
|
||
archived_at TEXT
|
||
);
|
||
```
|
||
|
||
**实现状态**:
|
||
- ✅ 11 个状态完整实现 (db.py `VALID_STATUSES`)
|
||
- ✅ `VALID_TRANSITIONS` 完整状态机 (v3.1 扩展了 paused 的恢复)
|
||
- ✅ `stages_json` 字段 (v2.7 SubTask 模型)
|
||
- ✅ `archived` / `archived_at` (v2.8 归档)
|
||
- ✅ `resumed_from` 字段 (v3.1 暂停恢复，在 models.py 中)
|
||
- ⚠️ `escalated INTEGER` 保留但设计要求改用 `status == 'escalated'`（向后兼容）
|
||
|
||
#### 5.1.2 comments 表 ✅
|
||
|
||
```sql
|
||
CREATE TABLE comments (
|
||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||
task_id TEXT NOT NULL,
|
||
author TEXT NOT NULL,
|
||
comment_type TEXT NOT NULL DEFAULT 'general',
|
||
CHECK (comment_type IN ('general', 'handoff', 'observation', 'rebuttal',
|
||
'rebuttal_response', 'debate_argument', 'debate_rebuttal', 'debate_judgment')),
|
||
body TEXT NOT NULL,
|
||
mentions TEXT, -- JSON array
|
||
created_at TEXT NOT NULL DEFAULT (datetime('now'))
|
||
);
|
||
```
|
||
|
||
- ✅ 8 种 comment_type 全部实现
|
||
- ✅ @mention 支持 (JSON 数组)
|
||
|
||
#### 5.1.3 outputs 表 ✅
|
||
|
||
```sql
|
||
CREATE TABLE outputs (
|
||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||
task_id TEXT NOT NULL,
|
||
agent TEXT NOT NULL,
|
||
output_type TEXT NOT NULL,
|
||
title TEXT NOT NULL,
|
||
content_path TEXT,
|
||
summary TEXT,
|
||
metadata TEXT, -- JSON
|
||
attempt_number INTEGER DEFAULT 1,
|
||
created_at TEXT NOT NULL DEFAULT (datetime('now'))
|
||
-- v2.8 M3 扩展字段:
|
||
file_name TEXT,
|
||
file_size INTEGER,
|
||
file_path TEXT,
|
||
mime_type TEXT
|
||
);
|
||
```
|
||
|
||
- ✅ 核心字段全部实现
|
||
- ✅ content_path 模式 (文件路径引用)
|
||
- ✅ content 直传模式 (后端自动写文件)
|
||
- ✅ M3 扩展字段 (file_name/file_size/file_path/mime_type)
|
||
|
||
#### 5.1.4 其他表 ✅
|
||
|
||
| 表名 | 状态 | 说明 |
|
||
|------|------|------|
|
||
| decisions | ✅ | 决策记录 (decider + decision + rationale + alternatives) |
|
||
| observations | ✅ | 观察记录 (observer + severity + body + resolved_by) |
|
||
| events | ✅ | 事件日志 (task_id + agent + event_type + detail JSON) |
|
||
| agents | ✅ | Agent 注册表 (agent_id + role + current_status + capabilities) |
|
||
| task_attempts | ✅ | 任务尝试记录 (attempt_number + outcome + exit_code + metadata) |
|
||
| reviews | ✅ | 审查记录 (review_type + verdict + confidence + round) |
|
||
| experiences | ✅ | 经验记录 (category + summary + confidence + tags) |
|
||
| experience_tags | ✅ | 经验标签 |
|
||
| checkpoints | ✅ | Checkpoint (M3: type + payload + status) |
|
||
|
||
### 5.2 状态机 ✅
|
||
|
||
**v3.1 完整状态转换矩阵** (11 个状态):
|
||
|
||
```python
|
||
VALID_TRANSITIONS = {
|
||
"pending": {"claimed", "paused", "blocked", "cancelled"},
|
||
"claimed": {"working", "paused", "pending", "cancelled"},
|
||
"working": {"review", "done", "blocked", "failed", "paused",
|
||
"escalated", "waiting_human", "cancelled"},
|
||
"paused": {"working", "claimed", "review", "escalated",
|
||
"waiting_human", "cancelled"},
|
||
"review": {"done", "pending", "failed", "paused", "escalated",
|
||
"waiting_human", "cancelled"},
|
||
"blocked": {"pending", "escalated", "cancelled"},
|
||
"failed": {"pending", "escalated", "cancelled"},
|
||
"escalated": {"working", "pending", "paused", "cancelled"},
|
||
"waiting_human": {"working", "done", "paused", "cancelled"},
|
||
"done": {"cancelled"},
|
||
"cancelled": {"pending"},
|
||
}
|
||
```
|
||
|
||
**与 v2.8 设计的差异** 🔀:
|
||
|
||
| 状态 | v2.8 设计 | v3.1 代码 | 差异 |
|
||
|------|----------|----------|------|
|
||
| paused 恢复 | → working | → working/claimed/review/escalated/waiting_human | 代码更灵活：恢复到 `resumed_from` 记录的状态 |
|
||
| pending | → {claimed, cancelled} | → {claimed, paused, blocked, cancelled} | 代码多了 paused、blocked |
|
||
| done | → set() | → {cancelled} | 代码允许取消已完成任务 |
|
||
| cancelled | → set() | → {pending} | 代码允许重新启动已取消任务 |
|
||
|
||
**手动状态** (不参与聚合): `cancelled`, `paused`
|
||
|
||
**聚合优先级**: escalated > waiting_human > review > working/claimed > pending > failed > blocked
|
||
|
||
### 5.3 项目注册表 ✅
|
||
|
||
- ✅ `registry.db` (SQLite) 管理多项目元数据
|
||
- ✅ `ProjectRegistry` 类：CRUD + 自动发现 + YAML 迁移
|
||
- ✅ 虚拟项目：`_mail` (飞鸽传书)、`_general` (一般任务)
|
||
- ✅ 自动发现：扫描含 `blackboard.db` 的目录
|
||
- ✅ `discover_sanguo_projects()`：扫描 `sanguo_projects/` 下的正式项目
|
||
|
||
### 5.4 版本迁移 ✅
|
||
|
||
| 迁移 | 文件位置 | 说明 |
|
||
|------|---------|------|
|
||
| v2.6.1 | `db._migrate_v261()` | current_agent, previous_agent, next_capability 字段 |
|
||
| v2.7 | `db._migrate_v27()` | stages_json, stage 字段 |
|
||
| v2.8 | `db._migrate_v28()` | 3 新状态 CHECK 约束重建 + 归档字段 + checkpoints 表 + outputs M3 扩展 |
|
||
|
||
---
|
||
|
||
## §6. Daemon 设计
|
||
|
||
### 6.1 Ticker 主循环 ✅
|
||
|
||
**文件**: `src/daemon/ticker.py` (~960 行)
|
||
|
||
```
|
||
Ticker.tick()
|
||
├─ 遍历 active 项目 (registry.list_projects())
|
||
├─ _tick_project(project_id, project_info):
|
||
│ ├─ init_db (首次)
|
||
│ ├─ 依赖推进 (blocked → pending)
|
||
│ ├─ _check_timeouts()
|
||
│ │ ├─ claimed 超时 (5min) → pending / escalated
|
||
│ │ ├─ working 超时 (30min) → failed
|
||
│ │ └─ 进程存活性检查 (PID alive)
|
||
│ ├─ _dispatch_pending()
|
||
│ │ └─ Dispatcher.dispatch() → Router → Spawner
|
||
│ ├─ _dispatch_reviews()
|
||
│ ├─ 僵尸检测 (HealthChecker.check())
|
||
│ ├─ 经验蒸馏 (ExperienceDistiller)
|
||
│ ├─ 父 Task 聚合刷新
|
||
│ └─ daemon_tick 事件写入
|
||
├─ 虚拟项目 _general (如果存在)
|
||
└─ 虚拟项目 _mail (如果存在)
|
||
```
|
||
|
||
**配置**:
|
||
- `tick_interval`: 30s
|
||
- `claim_timeout_minutes`: 5.0
|
||
- `default_task_timeout_minutes`: 30.0
|
||
- `max_dispatch_per_tick`: 3
|
||
|
||
**实现状态**:
|
||
- ✅ 30s 主循环
|
||
- ✅ per-project 扫描
|
||
- ✅ 依赖推进
|
||
- ✅ 超时检测 (claimed + working)
|
||
- ✅ 调度 pending/review 任务
|
||
- ✅ 僵尸检测
|
||
- ✅ 经验蒸馏调用
|
||
- ✅ 父 Task 聚合
|
||
- ✅ InboxWatcher 集成
|
||
- ✅ `max_dispatch_per_tick` 限制已实现，广播认领已实现（ticker.py `_broadcast_claim()`）
|
||
|
||
### 6.2 Dispatcher 调度器 ✅
|
||
|
||
**文件**: `src/daemon/dispatcher.py` (~618 行)
|
||
|
||
**职责**:
|
||
1. 从 Router 获取路由决策
|
||
2. 执行 spawn (通过 Spawner)
|
||
3. 安全红线检查 (调度前拦截)
|
||
4. 写路由审计日志 (routing_decisions)
|
||
|
||
**调度级别**:
|
||
| 级别 | 说明 |
|
||
|------|------|
|
||
| LOCAL | Daemon 本地执行 |
|
||
| FULL_AGENT | Full Agent spawn |
|
||
| ESCALATE | 升级庞统 |
|
||
| BLOCKED | 安全红线拦截 |
|
||
|
||
**实现状态**:
|
||
- ✅ Router/Dispatcher 分层
|
||
- ✅ Guardrail 安全红线前置检查
|
||
- ✅ 路由审计日志
|
||
- ✅ Mail 自动标 working (v2.7.1)
|
||
- ✅ 续杯 message 构建
|
||
|
||
### 6.3 Spawner 进程管理 ✅
|
||
|
||
**文件**: `src/daemon/spawner.py` (~1270 行)
|
||
|
||
**核心能力**:
|
||
- ✅ `spawn_full_agent()`: 异步 spawn，含 counter acquire/release
|
||
- ✅ `_monitor_process()`: 630s 超时监控
|
||
- ✅ 情况 A (进程退出) 12 个场景分类 (A0~A12)
|
||
- ✅ 情况 B (进程不退出) 4 个场景分类 (B1~B4)
|
||
- ✅ 续杯机制 (Gateway timeout → 复用 session_id)
|
||
- ✅ spawn 前 session state 检查 (防 webchat 冲突)
|
||
- ✅ Mail 专用 prompt 模板 (inform/request)
|
||
- ✅ Spawn prompt 模板 (含完整 API 操作指引)
|
||
- ✅ BootstrapBuilder 集成
|
||
|
||
**spawn_full_agent 生命周期** (v2.7.2):
|
||
```
|
||
1. 分配 session_id
|
||
2. session state 检查 (main session 时)
|
||
3. counter.can_acquire() 三层检查
|
||
4. counter.acquire() 占用
|
||
5. spawn 进程
|
||
6. wrapped_on_complete 闭包 → counter.release (try/finally 保证)
|
||
```
|
||
|
||
### 6.3.1 Session Lock 实测结论 (v3.0.3)
|
||
|
||
> 2026-05-30 基于实际 Gateway 日志 + daemon 日志的联合分析
|
||
|
||
#### 三层防线 (L3a/L3b/L3c)
|
||
|
||
spawn 前检查 main session 状态（`_check_session_state`），三层防线：
|
||
|
||
```python
|
||
# spawner.py spawn_full_agent() 内
|
||
if use_main_session:
|
||
session_state = self._check_session_state(agent_id)
|
||
# L3a: lock 文件检查（唯一有效防线）
|
||
if session_state.get("lock_pid_alive"):
|
||
raise AgentBusyError(...)
|
||
# L3b: sessions.json status 检查（实测无效）
|
||
if session_state.get("status") == "running":
|
||
raise AgentBusyError(...)
|
||
# L3c: compact 检查
|
||
if session_state.get("recent_compact"):
|
||
raise AgentBusyError(...)
|
||
```
|
||
|
||
#### 实测数据 (2026-05-30 双邮件测试)
|
||
|
||
| 时间 | 事件 | status | lock_pid | alive | 拦截者 |
|
||
|------|------|--------|----------|-------|--------|
|
||
| 00:25:35 | spawn simayi (测试1) | done | None | False | ✅ 通过 |
|
||
| 00:26:05 | ticker 重试 simayi (测试2) | **done** | **75279** | **True** | **L3a** |
|
||
| 00:26:05 | spawn pangtong (处理回复) | done | None | False | ✅ 通过 |
|
||
| 00:26:36 | ticker 再试 simayi | done | 75279 | True | L3a |
|
||
| 00:30:38 | ticker 尝试 pangtong | **failed** | **75279** | **True** | **L3a** |
|
||
| 00:31:09 | spawn pangtong (回复) | done | None | False | ✅ 通过 |
|
||
|
||
#### 关键发现
|
||
|
||
1. **`sessions.json` 的 `status` 全程未出现 `running`**
|
||
- Gateway 处理 Agent turn 时，`sessions.json` 的 status 在 daemon 30s 采样间隔内不会变为 `running`
|
||
- 唯一可靠信号是 lock 文件（L3a）
|
||
- L3b 的 `status == "running"` 检查在实际场景中**从未触发**
|
||
|
||
2. **L3a（lock check）是唯一有效防线**
|
||
- 所有拦截都是 `lock_pid_alive=True`（L3a）
|
||
- L3b 修复（`"processing"` → `"running"`）是正确的但实测无效
|
||
|
||
3. **Gateway 内部存在二次 lock 竞争**
|
||
- Gateway 处理 CLI turn 时（持有 session write lock 5+ 分钟），内部会产生另一个请求也想写同一 session
|
||
- 表现为 `SessionWriteLockTimeoutError: timeout 60000ms`
|
||
- 这是 Gateway 内部并发问题，daemon 无法解决
|
||
- 02 架构改造（统一 main session）是根本解法
|
||
|
||
4. **status 字段可能出现 `failed`**
|
||
- 00:30:38 检查 pangtong 时 `status=failed`（上一次 turn lock 超时后 Gateway 写入）
|
||
- L3b 不检查 `failed`，此时只有 L3a 在守
|
||
|
||
#### 已修复的 Bug
|
||
|
||
| Bug | 问题 | 修复 | 影响 |
|
||
|-----|------|------|------|
|
||
| L3b 枚举值 | `"processing"` 应为 `"running"` | ✅ 已修复 | L3b 形同虚设，现恢复理论作用 |
|
||
| outcome 白名单 | `process_crash`/`unknown_status` 不在 CHECK 约束中 | ✅ 已映射到 `crashed`/`agent_error` | daemon 崩溃根因 |
|
||
| 无详细日志 | session state 检查通过时不打日志 | ✅ 已加 INFO 日志 | 下次出问题可追溯 |
|
||
|
||
#### TOCTOU 竞态（已知限制）
|
||
|
||
L3a 检查和 CLI subprocess 获取 write lock 之间存在时间差：
|
||
1. daemon 检查 `lock_pid_alive=False` → 通过
|
||
2. spawn CLI subprocess
|
||
3. CLI 连接 Gateway 请求 session write lock
|
||
4. 此时用户通过 webchat 发消息 → Gateway 持有 lock
|
||
5. CLI 等 60s 超时 → `SessionWriteLockTimeoutError`
|
||
|
||
这不是 daemon 能解决的问题，需要 02 架构改造（不再用 CLI spawn，统一投递到 main session）。
|
||
|
||
### 6.4 关键差异: 设计 vs 实现
|
||
|
||
| 设计文档 | 实际代码 | 状态 |
|
||
|---------|---------|------|
|
||
| 广播认领 (v3.0-router-refactor) | ticker.py `_broadcast_claim()` 已完整实现 | ✅ |
|
||
| Session 存档清理 | spawner 有 `_sessions` 注册表但清理逻辑未完整集成 | ⚠️ |
|
||
| L2 Subagent spawn | `spawner.spawn_subagent()` 存在但标注 TODO: F17 | ⚠️ 骨架已有 |
|
||
| `_parse_stdout_json` P0 修复 | 代码已修正为 `data["response"]["meta"]` 路径 | ✅ 已修复 |
|
||
|
||
---
|
||
|
||
### 6.5 Daemon 退化 + Agent 进化方向 📋
|
||
|
||
> 来源：v2.8-direction-notes §一~§二，2026-05-27 讨论
|
||
|
||
**核心理念**：Daemon 从调度器退化成投递员，Agent 从被动执行者进化成自主决策者。
|
||
|
||
> **黑板是精髓，不是任何单个 Agent。** 所有 Agent 读黑板、想、行动、写回。Daemon 是投递员，不是决策者。
|
||
|
||
**当前 vs 未来**：
|
||
|
||
| 维度 | 当前（v2.7 实现） | 未来（AI Native v3.0） |
|
||
|------|------------------|---------------------|
|
||
| Daemon 角色 | 调度器 + 路由器 + 决策者 | 投递员 + 看护人 |
|
||
| Agent 角色 | 被动执行者（固定步骤 prompt） | 自主决策者（读黑板→想→干→写回） |
|
||
| 谁决定执行路径 | Daemon（if/else + YAML） | Agent（根据黑板信息自主判断） |
|
||
| Agent 间通信 | 无（Daemon 中央调度） | 黑板 comment + observation + @mention |
|
||
| Session 管理 | `--session-id UUID` → 新 session → 爆炸 | main session + subagent delegation |
|
||
|
||
**业界印证**：
|
||
|
||
| 系统 | 做法 | 关键点 |
|
||
|------|------|--------|
|
||
| Claude Code Agent Teams | Agent 自己 flock() claim 任务 | Agent 自己决定看什么、干什么 |
|
||
| Hermes Kanban | Agent 有 kanban_* 工具直接操作黑板 | 工具驱动，不是 prompt 指令驱动 |
|
||
| PRD v3.0 | "黑板是唯一真相源" | peer-to-peer 感知 |
|
||
|
||
**明确不做的事**：
|
||
1. ❌ Pipeline 框架（PipelineRouter 等不需要，Agent 自己决定执行策略）
|
||
2. ❌ 黑板摘要注入（Agent 已有 API 能力，让 Agent 自己决定看什么更 AI Native）
|
||
3. ❌ blackboard_* 工具封装（优先级低，当前 curl + API 方式可用）
|
||
4. ❌ Skill 集群模板（和 Agent 自主决策矛盾）
|
||
|
||
**Spawn 改造方向**（详见 `docs/design/02-main-session-delegation.md`）：
|
||
|
||
现行 `openclaw agent --session-id UUID` 导致 session 爆炸（E2E 测试 6 Agent 产生 68 个 session）。改造为：
|
||
- 所有 spawn 统一走 `spawn_full_agent(use_main_session=True)`（复用 Mail 路径已验证的模式）
|
||
- Agent main session 收到任务后自主决定执行方式（直接做 / sessions_spawn subagent / @mention 协作）
|
||
- subagent 通过 `cleanup: "delete"` 用完即删，不堆积
|
||
- 三层幻觉门控：Daemon 确定性检查 → 文件存在性验证 → AI 验证
|
||
|
||
> ⚠️ **澄清**：§10.5 Handoff Schema 不是 Pipeline 框架。Handoff 是 Agent 间的结构化交接文档（上家写给下家），是信息传递，不是执行编排。Pipeline 框架指的是 PipelineRouter/SingleStepPipeline 等代码级执行模式抽象，已明确不做。
|
||
|
||
**涉及文件**: `src/daemon/ticker.py`、`src/daemon/dispatcher.py`、`src/daemon/spawner.py`、`src/daemon/router.py`
|
||
|
||
**状态**: ❌ 方向已定，代码未动
|
||
|
||
---
|
||
|
||
## §7. Agent 交互设计
|
||
|
||
### 7.1 Agent-Backend API 契约 ✅
|
||
|
||
**文件**: `src/api/blackboard_routes.py` (~478 行)
|
||
|
||
| API | 方法 | 状态 | 说明 |
|
||
|-----|------|------|------|
|
||
| `/api/projects/{pid}/tasks` | GET | ✅ | 任务列表，支持 status/assignee/parent_task 过滤 |
|
||
| `/api/projects/{pid}/tasks` | POST | ✅ | 创建任务，自动生成 ID 和 title |
|
||
| `/api/projects/{pid}/tasks/{tid}` | GET | ✅ | 任务详情，expand=all 含全部关联数据 |
|
||
| `/api/projects/{pid}/tasks/{tid}/claim` | POST | ✅ | 原子 CAS 认领 |
|
||
| `/api/projects/{pid}/tasks/{tid}/status` | POST | ✅ | 状态更新，含合法转换校验 + SSE 推送 |
|
||
| `/api/projects/{pid}/tasks/{tid}/outputs` | GET/POST | ✅ | 产出 CRUD |
|
||
| `/api/projects/{pid}/tasks/{tid}/comments` | GET/POST | ✅ | 评论 CRUD |
|
||
| `/api/projects/{pid}/tasks/{tid}/decisions` | GET/POST | ✅ | 决策记录 |
|
||
| `/api/projects/{pid}/tasks/{tid}/observations` | GET/POST | ✅ | 观察记录 |
|
||
| `/api/projects/{pid}/tasks/{tid}/reviews` | GET/POST | ✅ | 审查记录 |
|
||
| `/api/projects/{pid}/tasks/{tid}/experiences` | GET/POST | ✅ | 经验记录 |
|
||
| `/api/projects/{pid}/tasks/{tid}/progress` | GET | ✅ | Stage 进度 + 子 Task 统计 |
|
||
| `/api/projects/{pid}/tasks/{tid}/archive` | POST | ✅ | 归档/取消归档 |
|
||
| `/api/projects/{pid}/tasks/archive-done` | POST | ✅ | 一键归档 |
|
||
| `/api/projects/{pid}/tasks/{tid}/outputs/{oid}/download` | GET | ✅ | 产出物下载 |
|
||
|
||
**Agent 友好的错误响应** ✅:
|
||
```json
|
||
{
|
||
"error": "invalid_transition",
|
||
"detail": "Cannot transition from claimed to review",
|
||
"valid_transitions": {"claimed": ["working", "pending", "cancelled"]},
|
||
"hint": "From 'claimed', valid targets are: ['working', 'pending', 'cancelled']"
|
||
}
|
||
```
|
||
|
||
**Title 自动生成** ⚠️ TODO: `blackboard_routes._generate_title()` 直接用 OpenAI client 调 zhipu API 生成标题（不走 Gateway），绕过了 Gateway 统一路由 + 计费。保留此函数，待未来替换为本地 LLM 调用。当前前端已支持传 title，LLM 生成只是 fallback。
|
||
|
||
### 7.2 CLI 工具 ✅
|
||
|
||
**文件**: `src/cli/blackboard.py` (~330 行)
|
||
|
||
支持的命令：
|
||
- `read` — 读取任务
|
||
- `create` — 创建任务
|
||
- `claim` — 认领任务
|
||
- `output` — 写产出
|
||
- `comment` — 写评论
|
||
- `decide` — 记录决策
|
||
- `observe` — 写观察
|
||
- `review` — 写审查
|
||
|
||
### 7.3 Agent 被 Spawn 后的工作流 ✅
|
||
|
||
```
|
||
1. 收到 spawn message (含 API 指引)
|
||
2. 标记 working (POST /tasks/{id}/status)
|
||
3. 执行任务 (编码/审查/数据等)
|
||
4. 写产出 (POST /tasks/{id}/outputs)
|
||
5. 写评论 (POST /tasks/{id}/comments) — 含 Handoff
|
||
6. 标记 review/done/failed
|
||
7. 进程退出 → Daemon 清理
|
||
```
|
||
|
||
### 7.4 Handoff Comment ✅
|
||
|
||
- ✅ comment_type = "handoff" 支持
|
||
- ✅ Schema 校验设计（schemas/ 目录定义）但 CLI 未集成校验
|
||
|
||
---
|
||
|
||
## §8. 路由与调度
|
||
|
||
### 8.1 AgentRouter 确定性路由 ✅
|
||
|
||
> **⚠️ TODO: Pipeline 强工作流**：当前 Router 只支持确定性路由 + 广播两种模式。Pipeline 强工作流（按 task_type 路由 + 状态机约束 + 直接 assign）待实现。详见文档末尾 §22 "Pipeline 强工作流设计" 章节。
|
||
|
||
**文件**: `src/daemon/router.py` (~180 行)
|
||
|
||
**v3.0 核心变更**: 去掉独立 LLM (LLMDriver)，模糊场景 delegate 庞统。
|
||
|
||
**路由模式**:
|
||
```
|
||
route(task_info, action_type):
|
||
├─ LOCAL_ACTIONS → daemon 本地执行
|
||
├─ retry → 原执行者
|
||
├─ next_capability → 能力匹配 (排除当前 Agent)
|
||
├─ 生命周期流转 (review → review capability)
|
||
├─ 有 assignee → 直接分
|
||
└─ 模糊场景 → delegate 庞统 (L3 spawn, 走 Gateway)
|
||
```
|
||
|
||
**Agent 能力画像** ✅:
|
||
|
||
| Agent | 能力 | can_review | is_fallback |
|
||
|-------|------|-----------|------------|
|
||
| zhangfei-dev | coding, implementation, scripting | false | false |
|
||
| simayi-challenger | review, quality_check, debate | true | false |
|
||
| guanyu-dev | risk, compliance, position_check | true | false |
|
||
| zhaoyun-data | data, acquisition, cleaning, verification | false | false |
|
||
| jiangwei-infra | deploy, infrastructure, docker, vnpy | false | false |
|
||
| pangtong-fujunshi | planning, coordination, escalation, strategy | true | **true** |
|
||
|
||
**RouteDecision** ✅:
|
||
- `mode`: "deterministic" | "agent_handoff" | "delegate" | "fallback"
|
||
- `confidence`: 0.0~1.0
|
||
- `latency_ms`: 路由耗时
|
||
|
||
### 8.2 并发控制 ✅
|
||
|
||
**文件**: `src/daemon/counter.py` (~170 行)
|
||
|
||
**v2.1: per (agent, session) 粒度，三层控制**:
|
||
|
||
| 层级 | 配置 | 默认值 | 作用 |
|
||
|------|------|--------|------|
|
||
| per session key | `max_per_session` | 1 | 同一 (agent, session) 不能并发 spawn |
|
||
| per agent | `max_concurrent_sessions` | 3 | 同一 agent 最多同时跑 N 个不同 session |
|
||
| global | `max_global_agents` | 5 | 全局总并发上限 |
|
||
|
||
**冷却机制** ✅:
|
||
- `set_cooldown(agent_id, seconds=120)`: API 429 后冷却
|
||
- `is_cooling_down(agent_id)`: 检查冷却状态
|
||
|
||
### 8.3 广播认领 ✅（已实现，司马评审确认）— 定义修正 2026-06-04
|
||
|
||
**定义**：一轮广播 = 所有 Agent 都收到了任务并给出了反馈（认领/NO_REPLY），才算一轮完成。
|
||
|
||
**机制**：
|
||
- 每个 pending 广播任务，维护 `notified_agents` 追踪已通知和已反馈的 Agent
|
||
- 每次 tick：spawn 空闲且尚未被通知的 Agent
|
||
- Agent 返回（认领/NO_REPLY/observation）→ 记录为已反馈
|
||
- Agent 忙（counter 阻塞）→ 不算已通知，下次 tick 继续尝试
|
||
- 当所有 Agent 都已反馈且没人认领 → 一轮结束 → retry_count +1
|
||
- 有人认领 → 广播立即结束（不需要等其他 Agent 反馈）
|
||
- 连续 3 轮广播无人认领 → 升级庞统
|
||
|
||
**实际代码 (ticker.py L540 `_broadcast_claim()`)**:
|
||
- ✅ 完整实现，包含：全局并发检查（counter.is_near_limit）、空闲 Agent 列表（_get_idle_agents）、批量广播（攒一批任务一次广播）、spawn 广播、无人认领检测（retry_count >= 3 → escalated）、审计事件记录（events 表 broadcast_claim 类型）
|
||
- ✅ 确定性路径也完整（Router → Dispatcher → Spawner）
|
||
|
||
**与旧实现的区别**：
|
||
- 旧：每次 tick spawn 所有空闲 Agent = 一轮，Agent 忙就跳过，retry_count 不递增
|
||
- 新：追踪每个 Agent 的通知/反馈状态，全部反馈才算一轮，防止忙 Agent 被反复跳过导致无限循环
|
||
|
||
**注**: 庞统初版误判为"未实现"，因检查 router.py/spawner.py 时未查 ticker.py。司马懿评审纠正。
|
||
|
||
---
|
||
|
||
## §9. 质量门控/审查体系
|
||
|
||
### 9.1 ReviewPipeline ✅
|
||
|
||
**文件**: `src/daemon/review.py` (~335 行)
|
||
|
||
**验证链**: 产出物存在性 → 格式合规 → 内容质量 → 评分
|
||
|
||
| 步骤 | 检查内容 | 状态 |
|
||
|------|---------|------|
|
||
| Step 1: 存在性 | 产出文件是否存在 | ✅ |
|
||
| Step 2: 格式合规 | markdown/JSON 格式检查 | ✅ |
|
||
| Step 3: 内容质量 | 自定义检查 + 文件大小检查 | ✅ |
|
||
| Step 4: Guardrail 门控 | 低/中/高风险分级 | ✅ |
|
||
|
||
**门控级别**:
|
||
|
||
| 风险等级 | 门控 | 说明 |
|
||
|---------|------|------|
|
||
| low | automatic | 自动检查通过即完成 |
|
||
| standard | mandatory | 需人工审查 |
|
||
| high | dual | 双重审查 (对抗辩论) |
|
||
| extreme | dual | 双重审查 + 强制审批 |
|
||
|
||
### 9.2 分级审查流水线 ⚠️
|
||
|
||
**设计 (v2.6.4)**:
|
||
- ✅ high/standard/low/research 四级
|
||
- ✅ 三阶段: 方案审查 → Guardrail 自动 → 产出审查
|
||
- ✅ 反驳权 (Rebuttal Phase)
|
||
|
||
**实现状态**:
|
||
- ✅ ReviewPipeline 验证链
|
||
- ✅ reviews 表 + verdict 字段 (approved/rejected/needs_revision)
|
||
- ⚠️ 方案审查 (plan_review) — reviews 表支持 plan_review 类型 (db.py REVIEW_TYPES)，但 Daemon 流程未自动触发方案审查
|
||
- ✅ 反驳权 — RebuttalManager (review.py) + 8 种 comment_type 含 rebuttal/debate 系列 + 前端 UI 支持
|
||
- ❌ 审查协议注册表 (review_protocols/) 未实现 — bootstrap.py 有 `_load_review_protocols` 但 review_protocols/ 目录不存在
|
||
- ❌ 对抗辩论模式未实现 — 无自动 spawn 正反方辩论
|
||
|
||
### 9.3 Guardrail 安全红线 ✅
|
||
|
||
**文件**: `src/daemon/guardrails.py` (~140 行) + `config/guardrails.yaml`
|
||
|
||
**PRD §10.1 六条红线**:
|
||
|
||
| 红线 | ID | 配置 | 代码 | 说明 |
|
||
|------|-----|------|------|------|
|
||
| 实盘交易 | live_trading | ✅ | ✅ | pattern 匹配 + task_type |
|
||
| 数据删除 | data_deletion | ✅ | ✅ | pattern 匹配 |
|
||
| 配置变更 | config_change | ✅ | ✅ | pattern 匹配 |
|
||
| 大额 Token | high_token_usage | ✅ | ✅ | token_threshold 检查 |
|
||
| Agent 不受控 | agent_uncontrolled | ✅ | ⚠️ | 规则定义在，但 step 超限检查未集成 |
|
||
| 连续失败 | consecutive_failure | ✅ | ✅ | consecutive_failures 检查 |
|
||
|
||
**GuardrailEngine 能力**:
|
||
- ✅ `check_task()`: 任务调度前检查
|
||
- ✅ `check_token_usage()`: Token 消耗检查
|
||
- ✅ `check_consecutive_failure()`: 连续失败检查
|
||
- ✅ pattern 正则匹配 + task_type 匹配
|
||
- ✅ action 分级: block_and_notify / pause_and_notify / terminate_and_escalate
|
||
|
||
---
|
||
|
||
## §10. 上下文管理
|
||
|
||
### 10.1 BootstrapBuilder 四层上下文 ✅
|
||
|
||
**文件**: `src/daemon/bootstrap.py` (~216 行)
|
||
|
||
| 层 | 内容 | Token 估算 | 状态 |
|
||
|----|------|-----------|------|
|
||
| L0 铁律层 | Hook 注入，不占 bootstrap | ~500 | ❌ 未集成到 Daemon |
|
||
| L1 角色层 | SOUL.md / IDENTITY.md (Agent 自带) | ~2000 | ✅ Agent 自有 |
|
||
| L2 引擎注入 | 操作规范 + 任务上下文 + 前序信息 + Guardrail + 审查协议 | ~1500 | ✅ BootstrapBuilder |
|
||
| L3 被动参考 | Skill description | 按需 | ✅ SkillRegistry |
|
||
|
||
**L2 注入内容 (按 role)**:
|
||
|
||
| 角色 | 注入内容 |
|
||
|------|---------|
|
||
| executor | role_template + 项目背景 + 任务上下文 + 前序产出 + Guardrail + 审查协议 + 经验 |
|
||
| reviewer | role_template + 项目背景 + 任务上下文 + 审查协议 |
|
||
| planner | role_template + 项目背景 + 任务上下文 + 审查协议 |
|
||
| pangtong | role_template + 项目背景 + 任务上下文 + 审查协议 |
|
||
|
||
**Token 预算**:
|
||
- `max_tokens`: 4096 (默认)
|
||
- 超限时自动截断
|
||
|
||
### 10.2 上下文预算 ✅
|
||
|
||
| 组件 | 预算 | 实际 |
|
||
|------|------|------|
|
||
| System Prompt + SOUL.md | ~3000-5000 | Agent 自有 |
|
||
| L2 引擎注入 | ~1000-2000 | BootstrapBuilder |
|
||
| 工作空间 | ~30000-50000 | Agent 剩余 context |
|
||
| **总计** | **~35K-60K** | 远小于 128K，安全 |
|
||
|
||
### 10.3 prompt_templates 目录 ⚠️
|
||
|
||
**设计**: `prompt_templates/executor.md`, `reviewer.md`, `planner.md` 等角色模板
|
||
|
||
**实现**: BootstrapBuilder 支持 `_load_template()` 加载模板文件，但实际的 prompt template 文件未完整创建。
|
||
|
||
### 10.4 Prompt 进化（固定步骤 → 自主决策）📋
|
||
|
||
> 来源：v2.8-direction-notes §三(2)，2026-05-27 讨论
|
||
|
||
**问题**：当前 spawner 的 spawn prompt 把 Agent 限制在固定步骤（标 working → 干活 → 写产出 → 标 review），不够 AI Native。
|
||
|
||
**设计方向**：从"固定步骤指令"变成"身份 + 目标 + 能做什么 + 约束 + 交接责任"：
|
||
|
||
```markdown
|
||
# 你的身份
|
||
你是 {agent_name}，{agent_role}。擅长 {agent_capabilities}。
|
||
|
||
# 你的任务
|
||
{task_title}: {task_description}
|
||
类型: {task_type} | 风险: {risk_level}
|
||
必要条件: {must_haves}
|
||
|
||
# 你能做什么
|
||
通过 API 操作黑板（{api_base}）:
|
||
- 读任何任务详情: GET /api/projects/{pid}/tasks/{id}?expand=all
|
||
- 读所有活跃任务: GET /api/projects/{pid}/tasks
|
||
- 写产出: POST /api/projects/{pid}/tasks/{id}/outputs
|
||
- 写评论: POST /api/projects/{pid}/tasks/{id}/comments
|
||
- 更新状态: POST /api/projects/{pid}/tasks/{id}/status
|
||
- 创建子任务: POST /api/projects/{pid}/tasks
|
||
|
||
# 约束
|
||
- 完成后必须写产出 + 标 review
|
||
- 安全红线: {guardrails_summary}
|
||
- 超时: {timeout} 分钟
|
||
```
|
||
|
||
**核心变化**：
|
||
1. Agent 自己根据黑板信息决定执行策略，不按固定步骤走
|
||
2. 给 Agent 黑板 API 完整能力列表，让 Agent 自主选择
|
||
3. 对齐 v3.0 "Daemon 退化 + Agent 进化"方向
|
||
|
||
> ⚠️ **注意**：新 prompt 中"约束"部分必须保留安全红线摘要（当前 GuardrailEngine 6 条红线已注入 prompt）。「自主决策」不意味着省略红线，红线是底线。
|
||
|
||
**涉及文件**: `src/daemon/spawner.py`（spawn prompt 构建）、`prompt_templates/executor.md`（新建）
|
||
|
||
**状态**: ❌ 方向已定，prompt 模板未重写
|
||
|
||
### 10.5 Handoff 上下文（Agent 间交接）📋
|
||
|
||
> 来源：v2.8-direction-notes §三(3)，2026-05-27 讨论
|
||
|
||
**问题**：Agent 完成任务后没有结构化的交接文档，下一个 Agent 缺少上下文。当前 handoff comment_type 已支持（§7.4），但无 Schema 约束和自动注入。
|
||
|
||
**设计方向**：
|
||
1. 新建 `schemas/handoff.schema.json` — 定义 handoff comment 的结构化格式
|
||
2. `bootstrap.py` 增强 — spawn 时读取上一个 Agent 的 handoff comment 注入 prompt
|
||
3. Review 流程增加 handoff 检查 — 无 handoff comment 则提醒
|
||
4. `GET /comments?comment_type=handoff` API 已实现（§7.4），无需改动
|
||
|
||
**灵感来源**: MattPocock Handoff（Agent 主动写交接文档传递上下文）
|
||
|
||
**涉及文件**: `schemas/handoff.schema.json`（新建）、`src/daemon/bootstrap.py`、`src/daemon/review.py`
|
||
|
||
**状态**: ❌ Schema 未创建，bootstrap 未增强
|
||
|
||
> 💡 **设计原则**：handoff.schema.json 不要过度设计。核心字段建议只留：what_was_done（做了什么）、key_decisions（关键决策）、next_steps（建议下一步）、risks（已知风险）。其他让 Agent 自由写，不强制 Schema。
|
||
|
||
### 10.6 知识注入（L3 Wiki 知识 → Agent Prompt）📋
|
||
|
||
> 来源：v2.8-direction-notes §三(4) + §六，2026-05-27 讨论
|
||
|
||
**问题**：Agent prompt 缺少领域知识，决策质量依赖 prompt 中的硬编码信息。当前 L3 层（§10.1）设计为"项目知识"，但注入机制未实现。
|
||
|
||
**设计方向**：
|
||
1. `spawner.py` 新增 `_inject_wiki_knowledge()` — 含 rg 检索 + grep fallback
|
||
2. `bootstrap.py` 内部调用 wiki knowledge 层
|
||
3. LLM Wiki 三层架构直接复用，不另建
|
||
|
||
> **澄清**：LLM Wiki 指的是 `sanguo_mozi` 技能包中的 wiki 技能体系（wiki-vault 三层：practices/observations/patterns），位于 `/Volumes/KnowledgeBase/wiki-vault/`。复用方式：spawner 在 spawn Agent 前通过 rg 检索相关知识文档，将匹配结果注入 prompt（不依赖 Agent 自己调用 wiki skill）。
|
||
|
||
4. 知识检索日志记录（什么知识被注入了，效果如何）
|
||
|
||
**调研结论**（来自 v2.8-direction-notes §六）：
|
||
|
||
| 方案 | 评估 | 结论 |
|
||
|------|------|------|
|
||
| Ripgrep 直接检索 | ✅ 最简单有效 | 采纳，作为主方案 |
|
||
| CodeGraph AST 索引 | ❌ 对知识文档无用 | 不采纳 |
|
||
| Understand Anything | ⚠️ 适合人工探索 | 不用于运行时注入 |
|
||
| MattPocock Handoff | ✅ Agent 交接 | 已采纳为 §10.5 |
|
||
|
||
**前置条件**: NAS `/Volumes/KnowledgeBase` 挂载路径问题需先解决（当前 `/Volumes/KnowledgeBase-1`）
|
||
|
||
**涉及文件**: `src/daemon/spawner.py`、`src/daemon/bootstrap.py`
|
||
|
||
**状态**: ❌ 未实施
|
||
|
||
---
|
||
|
||
## §11. 前端
|
||
|
||
### 11.1 现有前端 ✅
|
||
|
||
**目录**: `frontend/` (Vite + React + TypeScript)
|
||
|
||
| 组件 | 状态 | 说明 |
|
||
|------|------|------|
|
||
| EdictBoard.tsx | ✅ | 任务看板 (卡片布局) |
|
||
| TaskModal.tsx | ✅ | 任务详情弹窗 |
|
||
| MailTab.tsx | ✅ | 邮件 Tab |
|
||
| SSE 集成 | ✅ | EventSource 实时推送 |
|
||
| 通知中心 | ✅ | SSE 事件通知 |
|
||
| CheckpointPanel.tsx | ✅ | Checkpoint 交互面板，集成到 TaskModal (waiting_human 状态) |
|
||
| ArtifactPanel.tsx | ✅ | 成果物预览/下载面板，集成到 TaskModal outputs tab |
|
||
|
||
### 11.2 v2.8 设计 vs 实现 ⚠️
|
||
|
||
| 设计 (v2.8-state-enhancement) | 实际前端 | 状态 |
|
||
|------|---------|------|
|
||
| 两行筛选栏 | 项目下拉 + 状态/搜索筛选 | ✅ 已实现 |
|
||
| 卡片快捷按钮 (⏸▶🚫) | TaskActionButtons 组件 | ✅ 已实现（含 resumed_from 恢复逻辑） |
|
||
| 新状态颜色 | STATUS_STYLES 映射表 | ✅ 已实现（11 个状态各有颜色标签） |
|
||
| 归档筛选 | 活跃/归档/全部三档 | ✅ 已实现 |
|
||
| Checkpoint 面板 | CheckpointPanel 集成 | ✅ 已实现 |
|
||
| Artifact 成果物 | ArtifactPanel 集成 | ✅ 已实现 |
|
||
|
||
### 11.3 Dashboard AI Native 化 ❌
|
||
|
||
**PRD 目标**: AI Briefing + 智能摘要 + 上下文感知布局
|
||
|
||
**实际**: 前端是传统的 CRUD 看板，无 AI Native 特性。
|
||
|
||
---
|
||
|
||
## §12. Mail 系统
|
||
|
||
### 12.1 Mail Tab ✅
|
||
|
||
**文件**: `src/api/mail_routes.py` (~240 行)
|
||
|
||
**设计**: Mail 是特殊的 Project (`_mail`)，每封 Mail 是一个 Task。
|
||
|
||
| API | 方法 | 状态 |
|
||
|-----|------|------|
|
||
| `/api/mail` | GET | ✅ | 邮件列表 (时间倒序) |
|
||
| `/api/mail` | POST | ✅ | 发送邮件 (创建 Task) |
|
||
| `/api/mail/{id}` | GET | ✅ | 邮件详情 (含 comments 线程) |
|
||
| `/api/mail/agents/list` | GET | ✅ | 参与过 Mail 的 Agent 列表 |
|
||
| `/api/mail/summary` | GET | ✅ | 未读数 + 总数 |
|
||
|
||
**特性**:
|
||
- ✅ `conversation_id` 自动管理 (回复继承)
|
||
- ✅ `in_reply_to` 关联
|
||
- ✅ `type` 自动处理 (回复默认 inform 防循环)
|
||
- ✅ Mail spawn 时系统自动标 working
|
||
- ✅ Mail 续杯专用 prompt (不含状态转换指令)
|
||
|
||
### 12.2 与 v2.6 设计的关系 ✅（已澄清）
|
||
|
||
**v2.6 原文**: "Mail 完全退役，黑板替代所有功能" — 这里的 Mail 指的是 **sanguo_mail**（旧邮件系统），已被 v2.0 黑板完全替代。
|
||
|
||
**当前 Mail Tab**: 是 moziplus v2 内置的飞鸽传书功能（`_mail` 虚拟项目），是全新的实现，与 sanguo_mail 无关。两者不是同一个系统。
|
||
|
||
### 12.3 Mail API 防御 + Prompt 约束 📋
|
||
|
||
> 来源：#02 Main Session + Delegation 设计过程中发现的 Mail 自环问题
|
||
> 司马懿评审：mail-1780058519676 回复（M1/M2/S1-S3/A9），已纳入
|
||
|
||
#### 问题
|
||
|
||
Agent 回复邮件时把 `to` 写成自己，导致自环（mail-1780056763652 事件）。根因：
|
||
1. **API 层无防御**：`send_mail` 不校验 `to` 的合法性，不自动推断回复收件人
|
||
2. **Prompt 层无约束**：回复模板中 `to` 字段要求 Agent 手动填写，Agent 容易写错
|
||
|
||
#### 设计约束
|
||
|
||
1. **Mail 是 Agent 间 1 对 1 通信**。`from` 和 `to` 都必须是有效 Agent，`from="user"` 不允许（用户收不到邮件）
|
||
2. **严格 1 对 1**。禁止第三方插入会话。多 Agent 协作走 Task（广播/mention）
|
||
3. **有效 Agent 列表**统一维护一份，API 校验和 Prompt 模板共用同一数据源
|
||
|
||
#### API 层防御（`mail_routes.py` `send_mail`）
|
||
|
||
**校验执行顺序**（按此顺序逐条校验，任一失败立即返回 400）：
|
||
|
||
| 顺序 | # | 场景 | 校验逻辑 | 错误处理 |
|
||
|------|---|------|---------|----------|
|
||
| 1 | A1 | `from` 缺失/为空 | 必填校验 | 400："`from` 必填" |
|
||
| 2 | A9 | `from` 不是有效 Agent | 从注册 Agent 列表校验 | 400："`from` 不是有效的 Agent" |
|
||
| 3 | A5 | `in_reply_to` 指向不存在的邮件 | 原邮件存在性校验 | 400："回复的邮件不存在" |
|
||
| 4 | A6/A7 | `in_reply_to` 存在时自动纠正 `to` | 自动从原邮件取 `assigned_by`（原发件者）作为 `to` | 静默纠正，响应中加 `auto_corrected` 提示 |
|
||
| 5 | A2 | `to` 缺失/为空（非回复） | 必填校验 | 400："`to` 必填" |
|
||
| 6 | A3 | `from == to`（自环） | 防自环 | 400："不能给自己发邮件" |
|
||
| 7 | A4 | `to` 不是有效 Agent | 从注册 Agent 列表校验 | 400："`to` 不是有效的 Agent" |
|
||
| 8 | A8 | `in_reply_to` 存在，`from` 不是原邮件的 `assignee` 或 `assigned_by` | 严格 1 对 1：只有原邮件的双方能回复 | 400："只有邮件的发送者或接收者可以回复" |
|
||
| 9 | A10 | `text` 和 `description` 都为空 | 正文非空校验 | 400："邮件正文不能为空" |
|
||
|
||
**关键设计说明**：
|
||
|
||
- **A6/A7 自动纠正**：有 `in_reply_to` 时，无论 Agent 传什么 `to`，都自动从原邮件取 `assigned_by`（黑板字段，即原发件者）作为回复的 `to`。回复方向固定为 reply → original sender，不支持自定义收件人
|
||
- **A8 严格 1 对 1**：只有原邮件的 `assigned_by`（发件者）和 `assignee`（收件者）可以回复。其他人想参与需开新邮件，不能用 `in_reply_to` 插入别人的对话
|
||
- **A9 `from` 校验**：`from` 必须是有效 Agent。现有代码 `body.get("from", "user")` 的默认值 `"user"` 需移除，改为必填
|
||
- **A4/A9 有效 Agent 列表**：同一数据源（从 ticker `self.agents` 或配置读取）。Prompt 模板也用此列表的 `{valid_agents}` 变量替换
|
||
|
||
**A6 自动纠正响应格式**：
|
||
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"mail_id": "mail-xxx",
|
||
"auto_corrected": {"field": "to", "original": "simayi-challenger", "corrected": "pangtong-fujunshi"}
|
||
}
|
||
```
|
||
|
||
让调用者知道 `to` 被纠正了，Agent 下次可以避免同样的错误。
|
||
|
||
#### Prompt 层约束（`spawner.py` 模板）
|
||
|
||
**当前问题**：
|
||
1. 回复模板中 curl 命令的 JSON 双花括号转义，Agent 容易写错
|
||
2. 没有告诉 Agent "to 会自动推断"，Agent 手动填写容易出错
|
||
3. 没有给 Agent "发新邮件" 的模板，Agent 自己猜格式
|
||
4. Agent ID 列表硬编码在模板字符串里，加 Agent 要改代码
|
||
|
||
**改动**：
|
||
|
||
```python
|
||
MAIL_REQUEST_TEMPLATE = """你收到一封飞鸽传书，需要你处理并回复。
|
||
|
||
发件者: {from_agent}
|
||
主题: {title}
|
||
内容: {text}
|
||
|
||
### 如何回复发件者
|
||
|
||
curl -s -X POST http://localhost:8083/api/mail \\
|
||
-H 'Content-Type: application/json' \\
|
||
-d '{{"from": "{agent_id}", "in_reply_to": "{task_id}", "title": "回复: {title}", "text": "你的回复内容"}}'
|
||
|
||
⚠️ 不需要填 "to"，系统自动回复给发件者。
|
||
|
||
### 如何给其他人发新邮件
|
||
|
||
curl -s -X POST http://localhost:8083/api/mail \\
|
||
-H 'Content-Type: application/json' \\
|
||
-d '{{"from": "{agent_id}", "to": "对方agent-id", "title": "标题", "text": "正文", "type": "inform"}}'
|
||
|
||
⚠️ to 必须是有效的 agent id: {valid_agents}
|
||
⚠️ 纯通知用 type=inform，需要对方回复不填 type（默认 request）
|
||
⚠️ 不能给自己发邮件
|
||
⚠️ 不要执行任何状态转换命令（标 working/done/review/failed 等），系统会自动处理。
|
||
"""
|
||
|
||
MAIL_INFORM_TEMPLATE = """你收到一封飞鸽传书（纯通知）。
|
||
|
||
发件者: {from_agent}
|
||
主题: {title}
|
||
内容: {text}
|
||
|
||
已阅即可。如需回复，用 in_reply_to 回复发件者（不需要填 to）。
|
||
⚠️ 不要执行任何状态转换命令。
|
||
"""
|
||
```
|
||
|
||
**关键改动**：
|
||
1. 回复模板去掉 `to` 字段，告诉 Agent "系统自动回复给发件者"
|
||
2. 新增"给其他人发新邮件"模板
|
||
3. Agent ID 列表用 `{valid_agents}` 运行时替换（和 A4/A9 同一数据源），不硬编码
|
||
4. 三条 ⚠️ 覆盖三种错误场景（自环 / 幻觉 agent / 状态误操作）
|
||
5. inform 模板也加上回复指引
|
||
|
||
#### 涉及文件
|
||
|
||
| 文件 | 改动 |
|
||
|------|------|
|
||
| `src/api/mail_routes.py` | `send_mail` 加 A1-A10 校验 + 自动推断 + 有效 Agent 列表 |
|
||
| `src/daemon/spawner.py` | 模板更新 + `{valid_agents}` 运行时替换 |
|
||
|
||
#### 状态
|
||
|
||
📋 设计已纳入司马懿评审意见，待确认 → 实施 → 验收
|
||
|
||
---
|
||
|
||
## §13. 经验沉淀
|
||
|
||
### 13.1 ExperienceDistiller ✅
|
||
|
||
**文件**: `src/daemon/experience.py` (~290 行)
|
||
|
||
**经验分类**:
|
||
|
||
| 类别 | 关键词 |
|
||
|------|--------|
|
||
| pitfall | bug/error/fail/陷阱/踩坑 |
|
||
| best_practice | should/recommend/最佳实践 |
|
||
| environment | install/configure/环境 |
|
||
| pattern | 通用模式 |
|
||
| decision | 决策记录 |
|
||
|
||
**ExperienceStore** ✅:
|
||
- JSONL 持久化
|
||
- add/get/search/delete/list_all
|
||
|
||
**ExperienceDistiller** ✅:
|
||
- 从 review 结果提取 pitfall
|
||
- 从 task 产出提取 best_practice
|
||
- 模式关键词匹配
|
||
|
||
### 13.2 经验注入 ✅
|
||
|
||
**BootstrapBuilder** 支持 `experiences` 参数，在 L2 层注入最多 5 条相关经验。
|
||
|
||
### 13.3 经验闭环 ⚠️
|
||
|
||
**设计 (v2.6.7)**: DISCOVER → DISTILL → APPLY → IMPROVE 闭环
|
||
|
||
**实际**:
|
||
- ✅ DISTILL: ExperienceDistiller 自动蒸馏
|
||
- ✅ APPLY: BootstrapBuilder 注入经验
|
||
- ❌ IMPROVE: 经验使用后反馈/更新机制未实现
|
||
- ❌ 一级蒸馏 (实时) + 二级蒸馏 (周期) 未区分
|
||
|
||
### 13.4 experiences 表 ✅
|
||
|
||
```sql
|
||
CREATE TABLE experiences (
|
||
experience_id TEXT PRIMARY KEY,
|
||
source TEXT,
|
||
task_id TEXT,
|
||
summary TEXT,
|
||
category TEXT,
|
||
confidence REAL DEFAULT 0.8,
|
||
status TEXT DEFAULT 'active',
|
||
skill_id TEXT,
|
||
usage_count INTEGER DEFAULT 0,
|
||
last_used_at TEXT,
|
||
created_at TEXT,
|
||
created_by TEXT,
|
||
updated_at TEXT,
|
||
deprecated_reason TEXT
|
||
);
|
||
```
|
||
|
||
---
|
||
|
||
## §14. Guardrail 体系
|
||
|
||
### 14.1 GuardrailEngine ✅
|
||
|
||
详见 §9.3。补充架构层信息：
|
||
|
||
**Guardrail 检查位置**:
|
||
1. **Dispatcher.dispatch()** — 调度前检查 ✅
|
||
2. **ReviewPipeline** — 产出写入后检查 ✅
|
||
3. **Ticker._check_timeouts()** — 超时触发检查 ✅
|
||
|
||
**违反后的行为**:
|
||
|
||
| action | 行为 |
|
||
|--------|------|
|
||
| block_and_notify | 阻止调度 + 写黑板事件 |
|
||
| pause_and_notify | 暂停任务 + 通知 |
|
||
| terminate_and_escalate | 终止 Agent + 升级 |
|
||
| pause_and_escalate | 暂停 + 升级 |
|
||
|
||
### 14.2 verification_commands ❌
|
||
|
||
**设计 (v2.6.9 借鉴1)**: 任务 Plan 中声明验证命令 (pytest, flake8 等)，Daemon Guardrail 自动执行。
|
||
|
||
**实际**: ❌ 未实现。tasks 表无 `verification_commands` 字段。
|
||
|
||
### 14.3 Runaway Guard ⚠️
|
||
|
||
**设计 (v2.6.9 借鉴3)**: 每个任务最大 tick 上限 (max_ticks=100)，超限暂停 + 告警。
|
||
|
||
**实际**: ⚠️ 部分实现。Ticker 有 `max_ticks` 参数（当前用于测试，限制 Ticker 自身运行次数），但不是 per-task 的 Runaway Guard。tasks 表无 `tick_count` / `max_ticks` 字段。需要扩展为 per-task 粒度。
|
||
|
||
---
|
||
|
||
## §15. 事件驱动
|
||
|
||
### 15.1 InboxWatcher ✅
|
||
|
||
**文件**: `src/daemon/inbox.py` (~306 行)
|
||
|
||
- ✅ JSONL 文件监听 (1s 轮询)
|
||
- ✅ truncate 模式 (清空内容不删除文件)
|
||
- ✅ 原子追加写入 (OS 保证 append 原子性)
|
||
- ✅ 异步回调处理
|
||
- ✅ 支持的事件: agent_output / agent_claim / agent_status / agent_heartbeat
|
||
|
||
**与 Ticker 的关系**:
|
||
```
|
||
Ticker.start()
|
||
├─ InboxWatcher.start() → 1s 轮询 inbox/daemon.jsonl
|
||
└─ _loop() → 30s 全量 tick
|
||
|
||
InboxWatcher 发现事件 → process_callback → mini-tick?
|
||
实际: process_callback 由 Ticker 注入，触发针对性处理
|
||
```
|
||
|
||
### 15.2 SSE 实时推送 ✅
|
||
|
||
**文件**: `src/daemon/sse.py` (~313 行)
|
||
|
||
- ✅ SSEBroker: 发布/订阅模式
|
||
- ✅ SSEEvent: 结构化事件 (id + type + data + timestamp)
|
||
- ✅ 100 条事件历史缓存
|
||
- ✅ subscriber 队列 (maxsize=100)
|
||
|
||
**Hook 系统** ✅:
|
||
- HookType: webhook / script / callback
|
||
- HookManager: 注册/注销/触发
|
||
- 支持超时控制 (10s)
|
||
|
||
### 15.3 事件类型 ✅
|
||
|
||
```python
|
||
SSEEventType:
|
||
TASK_CREATED, TASK_UPDATED, TASK_COMPLETED, TASK_FAILED,
|
||
OBSERVATION_ADDED, AGENT_SPAWNED, AGENT_COMPLETED,
|
||
DAEMON_TICK, REVIEW_RESULT, HOOK_TRIGGERED
|
||
```
|
||
|
||
---
|
||
|
||
## §16. 多项目支持
|
||
|
||
### 16.1 架构 ✅
|
||
|
||
**设计 (v2.6.10 方案C)**: 单 Daemon + 多数据库 + per-project 并发
|
||
|
||
**实际实现**:
|
||
|
||
| 组件 | 状态 | 说明 |
|
||
|------|------|------|
|
||
| per-project blackboard.db | ✅ | 每个项目独立 SQLite |
|
||
| registry.db | ✅ | 全局项目注册表 |
|
||
| ProjectRegistry | ✅ | CRUD + 自动发现 + YAML 迁移 |
|
||
| 虚拟项目 | ✅ | `_mail`, `_general` |
|
||
| 任务跨项目移动 | ✅ | `POST /api/projects/{pid}/tasks/{tid}/move` |
|
||
| per-project 并发线程 | ❌ | 当前是 asyncio 单线程顺序处理 |
|
||
|
||
### 16.2 项目管理 API ✅
|
||
|
||
| API | 方法 | 状态 |
|
||
|-----|------|------|
|
||
| `/api/projects` | GET | ✅ | 项目列表 (含实时任务统计) |
|
||
| `/api/projects` | POST | ✅ | 创建项目 |
|
||
| `/api/projects/{pid}` | GET | ✅ | 项目详情 |
|
||
| `/api/projects/{pid}` | PATCH | ✅ | 更新项目 |
|
||
| `/api/projects/{pid}/archive` | POST | ✅ | 归档项目 |
|
||
| `/api/projects/{pid}` | DELETE | ✅ | 逻辑删除 |
|
||
| `/api/projects/{pid}/tasks/{tid}/move` | POST | ✅ | 跨项目移动任务 |
|
||
|
||
---
|
||
|
||
## §17. 待实现项汇总（原则 2/3）
|
||
|
||
> ⚠️ 以下为庞统初判 + 用户复查 + 司马懿评审后的修正版本（v3）。
|
||
>
|
||
> **已清理的问题**（不在此列表中）：
|
||
> - ~~P3 遗留 (404/4xx 响应码)~~: 已修复
|
||
> - ~~续杯设计矛盾~~: 已验证代码与设计一致
|
||
> - ~~广播认领矛盾~~: 已验证完整实现
|
||
> - ~~BUG-22 (list_mail from 内存过滤)~~: T1 修复，改为 SQL WHERE (assigned_by 参数)
|
||
> - ~~OBS-25 (send_mail from 冗余存储)~~: T1 修复，from 统一用 assigned_by，must_haves 不再存 from
|
||
> - ~~OBS-26 (polling 不刷新 Mail)~~: T1 修复，loadAll 在 mail tab 时调 loadMails()
|
||
|
||
### 17.1 PRD 明确要求但未实现
|
||
|
||
| # | 功能 | PRD 来源 | 当前状态 | 优先级 |
|
||
|---|------|---------|---------|--------|
|
||
| 1 | **需求探索自动触发** | PRD B1/C1 | ⚠️ Skill 已有（requirement-clarification + requirements-analysis），但缺少 Daemon 自动触发机制 | P2 |
|
||
| 2 | **动态规划** (活计划, 全程可调) | PRD B2/C2 | ❌ 基础机制存在（任务创建/状态流转），但无活的计划调整 | P1 |
|
||
| 3 | **持续指挥** (庞统全程在线) | PRD B2/C3 | ❌ 庞统只在 delegate 时被 spawn，无持续指挥 session | P1 |
|
||
| 4 | **主动汇报** (AI 推送自然语言摘要) | PRD B4/C7 | ⚠️ SSE 推送已有，但推送的是原始事件，不是 AI 生成的自然语言摘要 | P2 |
|
||
| 5 | **工具链集成** (lint/test/build) | PRD C10 | ❌ 未实现，toolchain-proposal.md 处于信息收集阶段 | P3 |
|
||
| 6 | **经验闭环 IMPROVE** | PRD C8 | ⚠️ DISTILL + APPLY 已实现，IMPROVE（使用后反馈/更新）未实现 | P3 |
|
||
|
||
### 17.2 设计文档有详细方案但未实现（经复查）
|
||
|
||
| # | 功能 | 设计文档 | 复查结果 | 优先级 |
|
||
|---|------|---------|---------|--------|
|
||
| 7 | ~~**广播认领** (自主 claim 调度)~~ | v3.0-router-refactor §3.3 | ✅ 已完整实现（ticker.py `_broadcast_claim()`），司马评审确认。移至 §17.3 | ~~P2~~ |
|
||
| 8 | **方案审查自动流程** | v2.6.4 §9.3 | ⚠️ reviews 表支持 plan_review 类型，但 Daemon 不会自动触发方案审查流程 | P2 |
|
||
| 9 | **审查协议注册表** (review_protocols/) | v2.6.4 §9.4 | ❌ bootstrap.py 有 `_load_review_protocols` 但 review_protocols/ 目录不存在 | P2 |
|
||
| 10 | **对抗辩论模式** (high 风险任务) | v2.6.4 §9.10 | ❌ 无自动 spawn 正反方辩论。comment_type 支持 debate 系列但无自动编排 | P3 |
|
||
| 11 | **verification_commands** (验证脚本层) | v2.6.9 借鉴1 | ❌ tasks 表无 verification_commands 字段，Guardrail 无脚本执行 | P2 |
|
||
| 12 | **Shadow Checkpoint** (git 自动 commit) | v2.6.9 借鉴5 | ❌ 无 git 集成 | P3 |
|
||
| 13 | **Skill 生命周期** (draft→active→deprecated) | v2.6.7 | ❌ SkillRegistry 只有注册/匹配，无生命周期管理 | P3 |
|
||
| 14 | **prompt_templates 角色模板** (完整文件) | v2.6.5 | ⚠️ BootstrapBuilder 支持 `_load_template()` 加载模板文件，但 prompt_templates/ 目录不存在 | P2 |
|
||
| 15 | **CLI Schema 校验** (schemas/ 目录) | v2.6.3 §3.7 | ❌ schemas/ 目录不存在 | P2 |
|
||
| 16 | **per-provider 冷却** | v2.7.2 §5 | ❌ Counter 只有 per-agent 冷却，无 per-provider 粒度 | P4 |
|
||
|
||
### 17.3 已确认实现（从待实现列表移除）
|
||
|
||
| # | 功能 | 证据 | 移除原因 |
|
||
|---|------|------|---------|
|
||
| — | **反驳权 (Rebuttal)** | ✅ RebuttalManager (review.py:273) + comment_type 含 rebuttal/debate_* + 前端 UI | 用户复查确认 |
|
||
| — | **Checkpoint 机制** | ✅ checkpoint_routes.py (6 端点) + CheckpointPanel.tsx + db.py checkpoints 表 | 用户复查确认 |
|
||
| — | **Artifact 成果物面板** | ✅ ArtifactPanel.tsx + ArtifactList.tsx + API 预览/下载端点 | 用户复查确认 |
|
||
| — | **广播认领** | ✅ ticker.py `_broadcast_claim()` 完整实现（全局并发检查 + 批量广播 + retry 3 次 + 庞统兜底） | **司马懿评审纠正** |
|
||
| — | **L2 Subagent spawn** | ⚠️ 骨架已有：spawner.spawn_subagent() 存在但标注 TODO: F17 | 部分实现 |
|
||
| — | **假死复活术** | ⚠️ health.py zombie 检测 + spawner._revive_session() | 部分实现 |
|
||
| — | **Runaway Guard** | ⚠️ Ticker 有 max_ticks（测试用），但不是 per-task 粒度 | 部分实现 |
|
||
|
||
---
|
||
|
||
## §18. PRD 新增建议（原则 4/5）
|
||
|
||
### 18.1 调研有但 PRD 未涵盖（原则 4）
|
||
|
||
| # | 内容 | 来源 | 建议 |
|
||
|---|------|------|------|
|
||
| 1 | Skill System (三层自由度: 原则/模板/脚本) | SkillRegistry 代码 | PRD 应补充 C11: 可插拔技能体系 |
|
||
| 2 | Hook 系统 (webhook/script/callback) | SSEBroker + HookManager | PRD 应补充事件扩展机制 |
|
||
| 3 | per-project 并发隔离 | v2.6.10 方案C | PRD 应明确多项目并发模型 |
|
||
| 4 | Mail 保留 (与 PRD "Mail 退役"矛盾) | 实际代码 | PRD 应更新: Mail 作为辅助通道保留 |
|
||
|
||
### 18.2 幽灵实现（原则 5: 代码有但设计没提）
|
||
|
||
| # | 内容 | 代码位置 | 分析 |
|
||
|---|------|---------|------|
|
||
| 1 | **Title LLM 自动生成** | blackboard_routes._generate_title() | 代码直接调 zhipu API 生成标题，不走 Gateway。类似 v3.0 删除的 LLMDriver 问题（不走 Gateway，需单独维护凭据） |
|
||
| 2 | **任务跨项目移动** | project_routes.move_task() | 完整实现含子任务一起移动，但无对应设计文档 |
|
||
| 3 | **Mail conversation_id 自动管理** | mail_routes.send_mail() | 自动继承回复的 conversation_id，无设计文档记录 |
|
||
| 4 | **routing_decisions 审计日志** | dispatcher._record_routing() | 路由审计写入 routing_decisions 表，但 db.py 中该表定义在 schema 但未在模型中暴露 |
|
||
|
||
---
|
||
|
||
## §19. 设计矛盾记录（原则 6）
|
||
|
||
> ⚠️ 以下为庞统初判 + 用户复查后的修正版本。司马懿需重点验证：这些矛盾是否真实存在？是否是我们漏看了某个最新的设计专项？
|
||
|
||
### 19.1 状态机：v2.8 设计 vs v3.1 代码 ✅（已解决，以代码为准）
|
||
|
||
**决策**: 以代码实际实现为准，v2.8 设计文档已归档至 `archive-2.0/v2.8-state-enhancement.md`。
|
||
|
||
**代码实际状态机**（§5.2 已完整记录）:
|
||
- 11 个状态，VALID_TRANSITIONS 完整定义
|
||
- `TERMINAL_STATUSES = frozenset()` — 无终态，全靠转换矩阵校验
|
||
- `MANUAL_STATUSES = {cancelled, paused}` — 不参与聚合推导
|
||
- paused 恢复通过 `resumed_from` 字段记录暂停前状态
|
||
- done → cancelled、cancelled → pending 支持"反悔"操作
|
||
|
||
**与 v2.8 设计的关键差异**（已归档，不再维护）:
|
||
- v2.8 定义了终态（done/cancelled），代码取消终态概念
|
||
- v2.8 paused 只能恢复到 working，代码支持恢复到任意 paused 前状态
|
||
- v2.8 pending 只能到 claimed/cancelled，代码多了 paused/blocked
|
||
|
||
这些差异都是工程实践中的合理扩展，代码更灵活实用。
|
||
|
||
### 19.2 广播认领 vs Delegate 庞统 ✅（已解决，非矛盾）
|
||
|
||
**v3.0-router-refactor 设计**: 双路径调度
|
||
- 确定性路径：已知下一步谁做 → 直接 spawn
|
||
- 广播认领路径：不确定 → spawn 所有空闲 Agent → 自主 claim
|
||
- 无人认领 → retry 3 次 → 庞统兜底
|
||
|
||
**实际代码 (已确认实现)**:
|
||
- ✅ 确定性路径：Router → Dispatcher → Spawner
|
||
- ✅ 广播认领路径：ticker.py `_broadcast_claim()` 完整实现
|
||
- ✅ 庞统兜底：retry_count >= 3 → escalated → delegate
|
||
|
||
**结论**: 设计和代码一致，双路径都完整实现。从矛盾列表移除。
|
||
|
||
**纠正记录**: 庞统初版只检查了 router.py/spawner.py，遗漏了 ticker.py L540。司马懿评审纠正。
|
||
|
||
**⚠️ 已知问题（2026-06-04 发现）**：
|
||
- 广播计数器不递增：`_broadcast_claim` 中只检查 `retry_count >= 3` 但不递增 retry_count
|
||
- retry_count 只在 `_check_timeouts` 的 claimed 超时路径递增
|
||
- 导致广播任务无限循环：每 tick 广播一次，没人认领也不计数
|
||
- **修复方案**：见 `docs/design/12-pipeline-design.md` §5 广播定义修正
|
||
|
||
### 19.3 `_generate_title()` 绕过 Gateway ⚠️ TODO（保留，待替换本地 LLM）
|
||
|
||
**现状**: `blackboard_routes._generate_title()`（line 138-175）直接用 OpenAI client 调 zhipu API，不走 Gateway。
|
||
|
||
**决策**: 保留此函数，不删除。未来替换为本地 LLM 调用。
|
||
|
||
**替换方向**: 本地 LLM（如 Ollama）或走 Gateway API。当前前端已支持传 title，LLM 只是 fallback，不影响正常使用。
|
||
|
||
### 19.4 续杯设计 ✅（已验证一致）
|
||
|
||
**spawner-monitor-design v2.0**: 续杯只有 A2/A3（Gateway timeout）触发。
|
||
|
||
**实际 spawner 代码**: `_handle_exit` 中 `cls["should_retry"]` 为 True 时才走 `_do_retry`，注释明确 "只有 A2/A3（gateway_timeout）触发续杯，其他都不 retry"。
|
||
|
||
**结论**: 代码和设计一致，不存在矛盾。删除此矛盾项。
|
||
|
||
---
|
||
|
||
### 19.5 Mail 模块硬编码问题 ⚠️ TODO（最后做 — 等其他专题稳定后再统一解决）
|
||
|
||
**现状**: `_mail` 作为虚拟 Project ID，在 dispatcher、spawner、blackboard_routes 中大量硬编码：
|
||
|
||
| 文件 | 硬编码位置 | 用途 |
|
||
|------|-----------|------|
|
||
| dispatcher.py L127,186 | `project_id == "_mail"` | 跳过 guardrail、标 working、on_complete |
|
||
| spawner.py L242,251,256 | `project_id == "_mail"` | 精简 prompt、直接 done 不走 review |
|
||
| blackboard_routes.py | `project_id == "_mail"` | 邮件 API 路由 |
|
||
|
||
**问题**:
|
||
1. 新增 Task 类型时需要到处加 `if project_id == "_xxx"` 分支
|
||
2. Mail 的特殊行为（精简 prompt、不走 review、auto-working）分散在多个文件
|
||
3. 没有统一的 Task 类型配置表
|
||
|
||
**设计方向**（v2.8 TaskType Pipeline）:
|
||
- 每个 Project 有 `task_type` 配置（mail/general/custom）
|
||
- 行为差异通过策略模式解决：`TaskPipeline.execute(route → pre_spawn → spawn → post_complete → verify)`
|
||
- Mail 特殊逻辑收敛到 `MailPipeline` 类
|
||
|
||
**参考**: `docs/design/archive-2.0/v2.8-task-type-pipeline.md`（已设计未实施）
|
||
|
||
**当前 on_checks_passed 方案**（v2.7.3 临时修复）:
|
||
- spawner 新增 `on_checks_passed` 参数，check 通过后、subprocess 前回调
|
||
- dispatcher 传入 `_mail_auto_working` 作为回调
|
||
- subprocess 失败时通过 `_mail_marked_working` flag 决定是否 revert
|
||
- VALID_TRANSITIONS[working] 已加入 pending（正式合法化）
|
||
|
||
---
|
||
|
||
## §20. 技术选型
|
||
|
||
### 20.1 核心技术栈 ✅
|
||
|
||
| 需求 | 选型 | 理由 |
|
||
|------|------|------|
|
||
| Web 框架 | FastAPI (Python) | 异步 + 自动文档 + 类型安全 |
|
||
| 数据库 | SQLite (per-project) | 原子性 + WAL + 零外部依赖 |
|
||
| 前端 | React + Vite + TypeScript | SPA + 快速构建 |
|
||
| 进程管理 | asyncio.create_subprocess_exec | 异步非阻塞 spawn |
|
||
| 实时推送 | SSE (Server-Sent Events) | 单向推送，比 WebSocket 简单 |
|
||
| 事件加速 | Inbox JSONL | agent-chorus 模式，跨进程通信 |
|
||
| 配置 | YAML (default.yaml + guardrails.yaml) | 人可读 + 可版本化 |
|
||
| 进程守护 | PM2 (Node.js) | 自动重启 + 日志管理 |
|
||
| Agent CLI | openclaw agent | OpenClaw 原生能力 |
|
||
| LLM 路由 | OpenClaw Gateway | 统一模型路由 + fallback + 计费 |
|
||
|
||
### 20.2 关键配置参数
|
||
|
||
```yaml
|
||
daemon:
|
||
tick_interval: 30
|
||
max_global_agents: 5
|
||
max_per_session: 1
|
||
max_concurrent_sessions: 3
|
||
max_dispatch_per_tick: 3
|
||
claim_timeout_minutes: 5.0
|
||
default_task_timeout_minutes: 30.0
|
||
agent_timeout: 630
|
||
gateway_timeout: 600
|
||
max_retries: 3
|
||
max_monitor_timeouts: 3
|
||
api_host: "127.0.0.1"
|
||
api_port: 8083
|
||
zombie_threshold: 20
|
||
```
|
||
|
||
### 20.3 数据库连接配置 ✅
|
||
|
||
```python
|
||
PRAGMA journal_mode=WAL # 并发读写
|
||
PRAGMA foreign_keys=ON # 外键约束
|
||
PRAGMA busy_timeout=5000 # 写锁等待 5s
|
||
```
|
||
|
||
### 20.4 参考系统映射
|
||
|
||
| 参考系统 | 借鉴点 | 映射到 |
|
||
|---------|--------|--------|
|
||
| Hermes Kanban | SQLite + Dispatcher tick | 黑板 + Ticker 30s |
|
||
| agent-chorus | JSONL inbox 跨进程通信 | InboxWatcher |
|
||
| open-multi-agent | TaskQueue.complete() → unblockDependents | 依赖推进 |
|
||
| Claude Code | file reference 模式 | outputs.content_path |
|
||
| Opal-Bridge | Fidelity 三档 | L1/L2/L3 上下文分层 |
|
||
| GSD Wave Execution | 隔离 session + 新鲜 context | per-task session |
|
||
| TradingAgents | Bull vs Bear 对抗辩论 | 审查体系 (设计) |
|
||
| superpowers | 三种 reviewer 角色 | ReviewPipeline 分级 |
|
||
| Aider | lint→test→commit | verification_commands (设计) |
|
||
| claude-goal | Stop Hook + 完成审计 | Guardrail + Runaway Guard (设计) |
|
||
| Cline | Shadow Git Checkpoint | Shadow Checkpoint (设计) |
|
||
|
||
---
|
||
|
||
## 附录 A: 文件清单
|
||
|
||
### A.1 后端源码
|
||
|
||
| 文件 | 行数(约) | 职责 |
|
||
|------|---------|------|
|
||
| `src/main.py` | 300 | FastAPI 入口 + 组件初始化 + 生命周期 |
|
||
| `src/blackboard/db.py` | 450 | DB schema + 迁移 + 状态机常量 |
|
||
| `src/blackboard/models.py` | 200 | 数据类 (Task/Comment/Output/...) |
|
||
| `src/blackboard/operations.py` | 830 | 黑板 CRUD 操作 |
|
||
| `src/blackboard/queries.py` | 357 | 黑板只读查询 |
|
||
| `src/blackboard/registry.py` | 326 | 多项目注册表 |
|
||
| `src/daemon/ticker.py` | 960 | Ticker 主循环 |
|
||
| `src/daemon/dispatcher.py` | 618 | 调度器 (路由+spawn) |
|
||
| `src/daemon/spawner.py` | 1270 | 进程管理 + 监控 + 续杯 |
|
||
| `src/daemon/router.py` | 180 | 确定性路由决策 |
|
||
| `src/daemon/bootstrap.py` | 216 | 上下文构建 (L0-L3) |
|
||
| `src/daemon/counter.py` | 170 | 并发控制 + 冷却 |
|
||
| `src/daemon/guardrails.py` | 140 | 安全红线引擎 |
|
||
| `src/daemon/review.py` | 335 | 产出验证流水线 |
|
||
| `src/daemon/inbox.py` | 306 | Inbox JSONL 监听 |
|
||
| `src/daemon/experience.py` | 290 | 经验蒸馏 |
|
||
| `src/daemon/health.py` | 160 | 僵尸检测 |
|
||
| `src/daemon/sse.py` | 313 | SSE + Hook 系统 |
|
||
| `src/daemon/skill_system.py` | 248 | Skill 注册/匹配/执行 |
|
||
| `src/api/blackboard_routes.py` | 478 | 黑板 API 路由 |
|
||
| `src/api/mail_routes.py` | 240 | Mail API 路由 |
|
||
| `src/api/project_routes.py` | 190 | 项目管理 API |
|
||
| `src/cli/blackboard.py` | 330 | CLI 工具 |
|
||
|
||
### A.2 配置文件
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `config/default.yaml` | 全局配置 (daemon/agent_profiles/inbox/review/experience) |
|
||
| `config/guardrails.yaml` | 安全红线 6 条规则 |
|
||
|
||
### A.3 设计文档
|
||
|
||
| 文档 | 说明 |
|
||
|------|------|
|
||
| `docs/PRD-v3.0.md` | 产品需求文档 |
|
||
| `docs/design/architecture-v2.6.md` | v2.6 架构设计 (~2070 行) |
|
||
| `docs/design/v2.7-subtask-model.md` | SubTask 模型 (Task 自引用) |
|
||
| `docs/design/v2.8-state-enhancement.md` | 状态增强 + 归档 + Checkpoint |
|
||
| `docs/design/v2.7.2-counter-lifecycle-fix.md` | 防重复调用 & 防无限续杯 |
|
||
| `docs/design/v3.0-router-refactor.md` | 路由重构 (去 LLM, 广播认领) |
|
||
| `docs/design/spawner-monitor-design.md` | Spawner Monitor 设计 |
|
||
| `docs/design/agent-api-contract.md` | Agent API 契约 |
|
||
|
||
---
|
||
|
||
## 附录 B: 实现状态总览
|
||
|
||
| 模块 | 已实现 | 部分实现 | 未实现 |
|
||
|------|--------|---------|--------|
|
||
| **数据模型** | SQLite schema, 11 状态, Task 自引用, 归档, Checkpoint | — | — |
|
||
| **Daemon Ticker** | 30s 循环, 依赖推进, 超时, 僵尸检测, 广播认领 | — | — |
|
||
| **路由调度** | Router 确定性路由, delegate 庞统, 广播认领 | — | L2 Subagent |
|
||
| **Spawner** | 进程管理, 监控, 续杯, counter | Session 清理集成 | 假死复活术 |
|
||
| **质量门控** | ReviewPipeline, Guardrails 6 红线 | — | 方案审查, 反驳权, 对抗辩论 |
|
||
| **上下文** | BootstrapBuilder L0-L3 | prompt_templates 文件 | — |
|
||
| **前端** | 任务看板, Mail Tab, SSE | 新状态 UI | AI Native, Checkpoint/Artifact |
|
||
| **Mail** | 完整 Mail Tab + API | — | — |
|
||
| **经验沉淀** | Distiller, Store, 注入 | — | 闭环 IMPROVE, 一/二级蒸馏 |
|
||
| **事件驱动** | InboxWatcher, SSE Broker, Hook | — | — |
|
||
| **多项目** | Registry, per-project DB, 移动 | — | per-project 并发线程 |
|
||
| **安全** | Guardrails 6 线, Counter 并发 | — | verification_commands, Runaway Guard |
|
||
| **Skill** | SkillRegistry 三层自由度 | — | Skill 生命周期 |
|
||
| **需求探索** | — | — | 苏格拉底对话, 动态规划 |
|
||
| **主动汇报** | SSE 推送 | — | 自然语言摘要 |
|
||
|
||
**总计**: ✅ 已实现 25 项 | ⚠️ 部分实现 8 项 | ❌ 未实现 12 项
|
||
|
||
> 上述数据经 2026-05-28 用户复查 + 司马懿评审修正。广播认领从未实现移至已实现。
|
||
|
||
---
|
||
|
||
## §21. T 阶段规划（T1~T8）
|
||
|
||
> 2026-05-28 新增，v3.0.1 更新。基于 architecture-v3.0 回溯 + v2.8-direction-notes 讨论话题 + §17/§19 待实现项 + 设计矛盾 + MEMORY/HEARTBEAT 遗留。
|
||
|
||
### 21.1 遗留问题完整清单（A/B/C/D 编号）
|
||
|
||
> 2026-05-28 08:44 规划，来源于 architecture-v3.0.md §17/§19 + HEARTBEAT.md + MEMORY.md 三路汇总。
|
||
|
||
| # | 来源 | 问题 | 类型 | 优先级 |
|
||
|---|------|------|------|--------|
|
||
| A1 | §17.1 #2 | **动态规划**（活计划，全程可调） | PRD 核心差距 | P1 |
|
||
| A2 | §17.1 #3 | **持续指挥**（庞统全程在线） | PRD 核心差距 | P1 |
|
||
| A3 | §19.1 | **状态机矛盾**（v2.8 设计 vs 代码，以代码为准更新文档） | 设计矛盾 | ~~P1~~ ✅ T1 已解决 |
|
||
| A4 | §19.3 | **`_generate_title()` 绕过 Gateway** | Bug | ~~P1~~ ✅ T1 已保留，待替换本地 LLM |
|
||
| B1 | §17.1 #1 | **需求探索自动触发**（Skill 已有，缺 Daemon 触发机制） | PRD 差距 | P2 |
|
||
| B2 | §17.1 #4 | **主动汇报**（SSE 推原始事件，不是 AI 摘要） | PRD 差距 | P2 |
|
||
| B3 | §17.2 #8 | **方案审查自动流程**（reviews 表有，Daemon 不触发） | 设计未落地 | P2 |
|
||
| B4 | §17.2 #9 | **审查协议注册表**（review_protocols/ 不存在） | 设计未落地 | P2 |
|
||
| B5 | §17.2 #11 | **verification_commands**（Guardrail 验证脚本层） | 设计未落地 | P2 |
|
||
| B6 | §17.2 #14 | **prompt_templates 角色模板**（目录不存在） | 设计未落地 | P2 |
|
||
| B7 | §17.2 #15 | **CLI Schema 校验**（schemas/ 不存在） | 设计未落地 | P2 |
|
||
| B8 | MEMORY | **BUG-7** planning 暂停失败 | Bug | P2 |
|
||
| B9 | MEMORY | **BUG-8** cancel→resume 空图完成 | Bug | P2 |
|
||
| B10 | MEMORY | **P3 遗留** 404/4xx 响应码 | Bug | ~~P3~~ ✅ 已修复 |
|
||
| B11 | MEMORY | **v2.7 遗留** BUG-22/OBS-25/OBS-26 | P3 | ~~P3~~ ✅ T1 已修复 |
|
||
| C1 | §17.2 #10 | **对抗辩论模式** | 设计未落地 | P3 |
|
||
| C2 | §17.2 #12 | **Shadow Checkpoint**（git 自动 commit） | 设计未落地 | P3 |
|
||
| C3 | §17.2 #13 | **Skill 生命周期** | 设计未落地 | P3 |
|
||
| C4 | §17.1 #5 | **工具链集成** | PRD 差距 | P3 |
|
||
| C5 | §17.1 #6 | **经验闭环 IMPROVE** | PRD 差距 | P3 |
|
||
| C6 | §17.2 #16 | **per-provider 冷却** | 设计未落地 | P4 |
|
||
| C7 | §6.3.1 | **Gateway 内部 session lock 竞争**（已知限制，02 架构改造解决） | 已知限制 | P2 |
|
||
| C8 | §6.3.1 | **TOCTOU 竞态**（L3a 检查和 CLI 获取 lock 之间的窗口期） | 已知限制 | P2 |
|
||
| D1 | HEARTBEAT | **v2.8 executor-prompt-design 漏洞**（3 个设计漏洞未修） | 设计暂停 | P3 |
|
||
| D2 | HEARTBEAT | **Pipeline 架构调研**（暂停，已废弃——不搞 Pipeline 框架） | 设计暂停 | ~~P3~~ 📦 已归档 |
|
||
| D3 | MEMORY | **M2 进程管理**（同步 vs 异步） | 待讨论 | P2 |
|
||
| D4 | MEMORY | **Agent 上下文膨胀** | 待讨论 | P2 |
|
||
|
||
### 21.2 T 阶段总览
|
||
|
||
| 阶段 | 名称 | 状态 | 核心目标 | 编号 |
|
||
|------|------|------|---------|------|
|
||
| **T1** | 文档对齐 + Bug 清理 | ✅ 已完成 | 状态机文档对齐 + BUG-22/OBS-25/OBS-26 修复 + 司马懿评审 | A3, A4, B10, B11 |
|
||
| **T2** | 持续指挥 + 动态规划 | 📋 待开始 | 庞统持续在线 + 活计划 + Daemon 退化 + BUG-7/BUG-8 | A1, A2, B8, B9 |
|
||
| **T3** | 主动汇报 + 需求探索触发 | 📋 待开始 | SSE 推 AI 摘要 + Daemon 自动触发需求探索 Skill | B1, B2 |
|
||
| **T4** | 审查体系完善 | 📋 待开始 | 方案审查自动流程 + 审查协议注册表 + verification_commands + 对抗辩论 | B3, B4, B5, C1 |
|
||
| **T5** | 上下文管理 | 📋 待开始 | prompt_templates + Prompt 进化 + Handoff + 知识注入 + CLI Schema + executor 漏洞 + 上下文膨胀 | B6, B7, D1, D4 |
|
||
| **T6** | 进程管理 M2 | 📋 待开始 | 同步进程管理方案 + Shadow Checkpoint | D3, C2 |
|
||
| **T7** | 经验闭环 + Skill 体系 | 📋 待开始 | Skill 生命周期 + IMPROVE 阶段 | C3, C5 |
|
||
| **T8** | 工具链 + 冷却 + Mail 统一 | 📋 最后做 | 工具链集成 + per-provider 冷却 + Mail 硬编码统一 | C4, C6, 话题1 |
|
||
|
||
### 21.3 各阶段详细规划
|
||
|
||
#### T1: 文档对齐 + Bug 清理 ✅ 已完成
|
||
|
||
**周期**: 2026-05-27 ~ 2026-05-28
|
||
|
||
**完成内容**：
|
||
- ✅ architecture-v3.0.md 回溯性架构文档（20+ 章节，58KB）
|
||
- ✅ 7 条分类原则逐项审查
|
||
- ✅ A3: 状态机文档对齐（以代码为准更新）
|
||
- ✅ A4: `_generate_title()` 保留，标注未来替换成本地 LLM
|
||
- ✅ B10: P3 遗留 404/4xx 已修复（之前已修）
|
||
- ✅ B11: BUG-22/OBS-25/OBS-26 修复
|
||
- ✅ 广播认领从"未实现"纠正为"已实现"（司马懿评审纠正）
|
||
- ✅ 5 个设计矛盾逐个解决（§19.1~19.5）
|
||
- ✅ §17 待实现项分级（P1~P4）
|
||
- ✅ Gateway Watchdog 设计 + 部署
|
||
- ✅ 司马懿评审通过
|
||
|
||
#### T2: 持续指挥 + 动态规划 📋 待开始
|
||
|
||
**编号**: A1, A2, B8, B9
|
||
|
||
**核心目标**：庞统从"被动 delegate"变为"持续在线指挥官" + 先修已知 bug
|
||
|
||
**对应 PRD**：B2（编排层是 AI 指挥官）、C2（动态规划）、C3（持续指挥）
|
||
|
||
**关键变更**：
|
||
1. 庞统持续指挥 session（当前只在 delegate 时被 spawn，无持续 session）
|
||
2. 动态规划（活的执行方案，全程可调）
|
||
3. Daemon 角色退化（从调度器 → 投递员 + 看护人）（§6.5）
|
||
4. Agent 自主决策（读黑板 → 想 → 干 → 写回）
|
||
|
||
**涉及文件**: `src/daemon/ticker.py`、`src/daemon/dispatcher.py`、`src/daemon/router.py`
|
||
|
||
**前置条件**: T1 完成 ✅ + #02 Main Session Delegation 架构方案确认
|
||
|
||
**bug 修复**（T2 前置）：
|
||
- B8: BUG-7 planning 暂停失败 — 需在功能开发前修复
|
||
- B9: BUG-8 cancel→resume 空图完成 — 需在功能开发前修复
|
||
|
||
**已知限制**（T2 需解决）：
|
||
- C7: Gateway 内部 session lock 竞争 — 02 架构改造（统一 main session）根治
|
||
- C8: TOCTOU 竞态 — 同上，不再用 CLI spawn
|
||
|
||
**来源**: v2.8-direction-notes §一~§二 + §17 #2/#3
|
||
|
||
#### T3: 主动汇报 + 需求探索触发 📋 待开始
|
||
|
||
**编号**: B1, B2
|
||
|
||
**核心目标**：补齐 PRD 四相循环的 Phase 1 和 Phase 4
|
||
|
||
**对应 PRD**：B1（AI 帮人想清楚要什么）、B4（主动汇报）
|
||
|
||
**关键变更**：
|
||
1. 需求探索自动触发：Skill 已有（requirement-clarification + requirements-analysis），缺 Daemon 自动触发机制
|
||
2. 主动汇报 AI 摘要：SSE 推送已有，但推送原始事件，不是 AI 自然语言摘要
|
||
|
||
**涉及文件**: `src/daemon/ticker.py`、`src/daemon/sse.py`、前端
|
||
|
||
**前置条件**: T2 完成
|
||
|
||
#### T4: 审查体系完善 📋 待开始
|
||
|
||
**编号**: B3, B4, B5, C1
|
||
|
||
**核心目标**：补齐质量门控的自动化环节
|
||
|
||
**对应 PRD**：C4（质量门禁）、C9（安全红线）
|
||
|
||
**关键变更**：
|
||
1. 方案审查自动流程：reviews 表支持 plan_review，但 Daemon 不自动触发
|
||
2. 审查协议注册表：review_protocols/ 目录创建
|
||
3. verification_commands：验证脚本层
|
||
4. Runaway Guard：per-task max_ticks + 超限暂停告警（§14.3）
|
||
5. 对抗辩论模式：high 风险任务自动 spawn 正反方
|
||
|
||
**涉及文件**: `src/daemon/ticker.py`、`src/daemon/review.py`、`review_protocols/`（新建）
|
||
|
||
**前置条件**: T2 完成
|
||
|
||
#### T5: 上下文管理 📋 待开始
|
||
|
||
**编号**: B6, B7, D1, D4
|
||
|
||
**核心目标**：Agent 拥有自主决策的 prompt + 结构化交接 + 领域知识 + 解决上下文膨胀
|
||
|
||
**对应 PRD**：B3（共享意识）、C6（上下文管理）
|
||
|
||
**关键变更**：
|
||
1. prompt_templates 角色模板：创建 executor.md / reviewer.md / planner.md（§10.4）
|
||
2. Prompt 进化：从固定步骤 → 自主决策（§10.4）
|
||
3. Handoff 上下文：handoff.schema.json + bootstrap 增强（§10.5）
|
||
4. 知识注入：spawner 新增 `_inject_wiki_knowledge()`（§10.6）
|
||
5. CLI Schema 校验：schemas/ 目录
|
||
6. executor-prompt-design 3 个漏洞修复（D1）
|
||
7. Agent 上下文膨胀解决方案（D4）
|
||
|
||
**涉及文件**: `src/daemon/spawner.py`、`src/daemon/bootstrap.py`、`schemas/`（新建）、`prompt_templates/`（新建）
|
||
|
||
**前置条件**: T2 完成（Prompt 进化依赖 Daemon 退化方向确定）
|
||
|
||
**来源**: v2.8-direction-notes §三(2)(3)(4) + §六
|
||
|
||
#### T6: 进程管理 M2 📋 待开始
|
||
|
||
**编号**: D3, C2
|
||
|
||
**核心目标**：解决 M2 进程管理问题 + Shadow Checkpoint
|
||
|
||
**关键变更**：
|
||
1. M2 进程管理：当前 `subprocess.run()` 无法中途 kill，需讨论同步/异步方案（D3）
|
||
2. Shadow Checkpoint：git 自动 commit（C2）
|
||
|
||
**前置条件**: T2 完成
|
||
|
||
**约束**: openclaw 不支持异步，需讨论替代方案（MEMORY 记录）
|
||
|
||
#### T7: 经验闭环 + Skill 体系 📋 待开始
|
||
|
||
**编号**: C3, C5
|
||
|
||
**核心目标**：完成经验沉淀闭环
|
||
|
||
**关键变更**：
|
||
1. Skill 生命周期管理（draft→active→deprecated）
|
||
2. 经验闭环 IMPROVE 阶段（使用后反馈/更新）
|
||
|
||
**前置条件**: T5 完成
|
||
|
||
#### T8: 工具链 + 冷却 + Mail 统一 📋 最后做
|
||
|
||
**编号**: C4, C6, 话题1
|
||
|
||
**核心目标**：工具链集成 + per-provider 冷却 + Mail 硬编码统一
|
||
|
||
**关键变更**：
|
||
1. 工具链集成（lint/test/build）
|
||
2. per-provider 冷却（Counter 扩展）
|
||
3. Mail 硬编码统一（§19.5，等稳定后再动）
|
||
|
||
**前置条件**: T2~T7 完成
|
||
|
||
**建议执行顺序**: T1 ✅ → T2（核心）→ T3 → T4 → T5 → T6 → T7 → T8（最后）
|
||
|
||
### 21.4 话题与 T 阶段映射
|
||
|
||
| 话题 | T 阶段 | 编号 | 状态 |
|
||
|------|--------|------|------|
|
||
| 话题1: Mail 硬编码独立 | **T8**（最后做） | C4, C6, 话题1 | ❌ 未实施 |
|
||
| 话题2: Prompt 进化 | **T5** | B6, D1 | ❌ 未实施 |
|
||
| 话题3: Handoff 上下文 | **T5** | B6 | ❌ 未实施 |
|
||
| 话题4: 知识注入 | **T5** | B6 | ❌ 未实施 |
|
||
| 话题5: Runaway Guard | **T4** | B5 | ⚠️ 部分实现 |
|
||
| 话题6: Daemon 退化 + Agent 进化 | **T2** | A1, A2 | ❌ 未实施 |
|
||
|
||
### 21.5 编号与 T 阶段完整映射
|
||
|
||
| 编号 | 问题 | T 阶段 | 状态 |
|
||
|------|------|--------|------|
|
||
| A1 | 动态规划 | T2 | ❌ |
|
||
| A2 | 持续指挥 | T2 | ❌ |
|
||
| A3 | 状态机矛盾 | T1 | ✅ 已解决 |
|
||
| A4 | _generate_title() 绕过 Gateway | T1 | ✅ 已保留 |
|
||
| B1 | 需求探索自动触发 | T3 | ❌ |
|
||
| B2 | 主动汇报 AI 摘要 | T3 | ❌ |
|
||
| B3 | 方案审查自动流程 | T4 | ❌ |
|
||
| B4 | 审查协议注册表 | T4 | ❌ |
|
||
| B5 | verification_commands | T4 | ❌ |
|
||
| B6 | prompt_templates 角色模板 | T5 | ❌ |
|
||
| B7 | CLI Schema 校验 | T5 | ❌ |
|
||
| B8 | BUG-7 planning 暂停失败 | T2 | ❌ |
|
||
| B9 | BUG-8 cancel→resume 空图 | T2 | ❌ |
|
||
| B10 | P3 遗留 404/4xx | T1 | ✅ 已修复 |
|
||
| B11 | BUG-22/OBS-25/OBS-26 | T1 | ✅ 已修复 |
|
||
| C1 | 对抗辩论模式 | T4 | ❌ |
|
||
| C2 | Shadow Checkpoint | T6 | ❌ |
|
||
| C3 | Skill 生命周期 | T7 | ❌ |
|
||
| C4 | 工具链集成 | T8 | ❌ |
|
||
| C5 | 经验闭环 IMPROVE | T7 | ❌ |
|
||
| C6 | per-provider 冷却 | T8 | ❌ |
|
||
| C7 | Gateway 内部 session lock 竞争 | T2 | ⚠️ 已知限制 |
|
||
| C8 | TOCTOU 竞态 | T2 | ⚠️ 已知限制 |
|
||
| D1 | executor-prompt-design 漏洞 | T5 | ❌ |
|
||
| D2 | Pipeline 架构调研 | — | 📦 已废弃 |
|
||
| D3 | M2 进程管理 | T6 | ❌ |
|
||
| D4 | Agent 上下文膨胀 | T5 | ❌ |
|
||
|
||
### 21.6 §17 待实现项与 T 阶段映射
|
||
|
||
| §17 # | 待实现项 | 编号 | T 阶段 |
|
||
|--------|---------|------|--------|
|
||
| 1 | 需求探索自动触发 | B1 | T3 |
|
||
| 2 | 动态规划 | A1 | T2 |
|
||
| 3 | 持续指挥 | A2 | T2 |
|
||
| 4 | 主动汇报 AI 摘要 | B2 | T3 |
|
||
| 5 | 工具链集成 | C4 | T8 |
|
||
| 6 | 经验闭环 IMPROVE | C5 | T7 |
|
||
| 8 | 方案审查自动流程 | B3 | T4 |
|
||
| 9 | 审查协议注册表 | B4 | T4 |
|
||
| 10 | 对抗辩论模式 | C1 | T4 |
|
||
| 11 | verification_commands | B5 | T4 |
|
||
| 12 | Shadow Checkpoint | C2 | T6 |
|
||
| 13 | Skill 生命周期 | C3 | T7 |
|
||
| 14 | prompt_templates 角色模板 | B6 | T5 |
|
||
| 15 | CLI Schema 校验 | B7 | T5 |
|
||
| 16 | per-provider 冷却 | C6 | T8 |
|
||
| — | Gateway 内部 session lock 竞争 | C7 | T2 (02 架构改造) |
|
||
| — | TOCTOU 竞态 | C8 | T2 (02 架构改造) |
|
||
|
||
---
|
||
|
||
## §22. Pipeline 强工作流设计（TODO）
|
||
|
||
> 2026-06-04 新增。基于 #12 Pipeline 设计专题讨论确认的方向。本节所有内容均为 **待实现**，标注 TODO。
|
||
|
||
### 22.1 设计方向（2026-06-04 #12 讨论确认）
|
||
|
||
#### 两种模式
|
||
|
||
**自由模式（AI native）**：
|
||
- 不指定 task_type → 广播认领
|
||
- Agent 自主判断、自主认领、自主决定执行方式
|
||
- Agent 是决策主体
|
||
- 当前已实现
|
||
|
||
**Pipeline 强工作流（TODO）**：
|
||
- 指定 task_type → 确定性路由 + 状态机约束
|
||
- 系统控制流程、指定执行者、规定步骤顺序
|
||
- Agent 是执行主体，不是决策主体
|
||
- 不走 claim，直接 assign
|
||
- 引擎提示词需严格约束 Agent 行为边界，防止不可预料分支
|
||
|
||
#### Pipeline 灵活流转
|
||
|
||
- **顺序（sequence）**：A → B → C
|
||
- **条件分支（branch）**：review 通过 → done，review 拒绝 → working
|
||
- **退回（rollback）**：review 失败退回上一个 stage
|
||
- **循环重试（loop）**：max_retries 控制
|
||
|
||
#### 已确认的设计决策
|
||
|
||
| # | 决策 | 内容 |
|
||
|---|------|------|
|
||
| D1 | Pipeline vs 自由模式二选一 | task_type 决定走哪条路 |
|
||
| D2 | Pipeline 是强工作流，不可偏离 | Agent 必须按流程走 |
|
||
| D3 | @mention 在 Pipeline 模式下只做通知不改变执行者 | 流程控制权在系统 |
|
||
| D4 | task_type 默认 None（不指定 = 自由模式） | 向后兼容 |
|
||
| D5 | 前端下拉 + Chat 入口 | 用户选择 Pipeline 模式 |
|
||
|
||
#### 待深入设计的问题
|
||
|
||
1. **提示词约束**：强工作流下提示词模板如何约束 Agent 不产生不可预料分支
|
||
2. **模式共存**：自由模式和强工作流模式如何共存（同一系统、不同任务）
|
||
3. **差异化需求**：两种模式对 Spawner/Ticker/Router 的差异化需求
|
||
4. **排队处理**：Pipeline 任务直接 assign 后 Agent 忙时的处理（Spawner 排队 vs 升级）
|
||
5. **错误处理**：强工作流下的错误处理（Agent 失败是流程回退，不是自主重试）
|
||
|
||
#### 相关设计文档
|
||
|
||
| 文档 | 说明 |
|
||
|------|------|
|
||
| `docs/design/12-pipeline-design.md` | Pipeline 设计专题 v2.1（已 approved） |
|
||
| `docs/design/08-classify-outcome-optimization.md` | Classify Outcome v3.1 |
|
||
| `docs/design/09-rebuttal-and-goal-gate.md` | Rebuttal 流程 |
|
||
|
||
### 22.2 与现有架构的关系
|
||
|
||
- **Router（§8.1）**：当前只有确定性路由 + 广播认领两种模式。Pipeline 需要新增按 task_type 匹配 Pipeline 定义的路由模式
|
||
- **Ticker（§6.1）**：Pipeline 任务不走 `_broadcast_claim()`，走直接 assign + 状态机流转
|
||
- **Spawner（§6.3）**：Pipeline 任务的 spawn prompt 需严格约束行为边界，防止 Agent 偏离流程
|
||
- **状态机（§5.2）**：Pipeline 流转的 branch/rollback/loop 需要状态机支持更丰富的转换规则
|
||
|
||
### 22.3 实施建议
|
||
|
||
- 优先级：P2（核心架构增强，但不阻塞 T2 持续指挥）
|
||
- 前置条件：T2 完成后再启动（避免与 Daemon 退化方向冲突）
|
||
- 建议阶段：T4 审查体系完善之后，或独立为 T4.5
|
||
- 里程碑：先实现单一顺序 Pipeline（A→B→C），再扩展条件分支
|