sanguo/sanguo_moziplus_v2
8
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2c9680cfa94de29517e822203e2a94e05f074f94
sanguo_moziplus_v2/docs/design/archive/v2.7-three-tier-hierarchy.md
T
cfdaily 254a03a821 auto-sync: 2026-05-18 10:52:32
2026-05-18 10:52:32 +08:00

15 KiB
Raw Blame History

v2.7 三级层次结构完整设计文档

日期：2026-05-17 版本：v1.0 作者：庞统 状态：待评审 变更记录：与用户 6 轮讨论后定稿

一、核心架构

1.1 三层结构

Project（项目）
  └── Card（卡片/策略/工作流）
        └── Task（原子任务）
层级 语义 例子 生命周期
Project 业务领域/产品线 sanguo_quant_live、General、Mail 长期
Card 独立的工作流/策略 动量策略v1、v2.7开发 中期（天/周）
Task 原子执行单元 编写回测脚本、清洗分钟线 短期（小时/天）

1.2 隔离策略

一个 Project 一个 DB + card_id 逻辑隔离。

理由：

  • Jira/Linear/Asana 均采用逻辑隔离，是成熟模式
  • 跨 Card 查询天然支持（同一 DB）
  • 备份/迁移按 Project 独立
  • 单 DB <5000 Task，SQLite 性能无忧

跨 Card 依赖不支持——策略间应独立，数据引用用 artifacts 路径。

1.3 Card 状态 = Task 状态聚合

Card 不独立维护状态机，状态从内部 Task 推导（取最高水位）：

Card 状态 推导规则 可创建 Task Ticker 扫描
pending 所有 Task 都是 pending ✅ ✅
working 有 Task 在 working ✅ ✅
review 有 Task 在 review ✅ ✅
done 所有 Task 都是 done ❌ ❌
failed 有 Task failed 且无 active Task ❌ ❌
blocked 有 Task blocked 且无 active Task ❌ ✅（检查是否解除）
cancelled 用户/AI 取消 ❌ ❌
archived 用户/AI 归档 ❌ ❌
deleted 系统清理 ❌ ❌

额外两个状态（超出 Task 语义）：

  • archived：人工/AI 归档决策，默认视图不显示，可切换查看
  • deleted：archived 后 7-30 天物理清理

1.4 Stage 进度（AI 动态生成）

Card 创建时 AI 根据目标描述生成初始 Stages，执行中可动态调整：

Card: 动量策略v1
Stages（AI 生成，可演进）:
  [因子研究 ✅] → [策略编码 ✅] → [历史回测 🔄] → [参数优化 ⬜]
                                         ↑
                              AI 发现需要先做数据质量检查，动态插入新 Stage

数据模型：

  • cards.stages_json：存当前 stages 定义
  • tasks.stage：Task 绑定到某个 stage id

Stage 不是状态机——Task 可以在任意 stage 创建，stage 只用于分组显示进度。

二、特殊 Project

2.1 General（一般性任务）

  • Project ID：_general
  • 用途：无项目归属的 ad-hoc 任务
  • 用户随口说的"帮我下载分钟线"→ 自动创建到 General
  • 在 Dashboard 中作为一个普通 Project 显示

2.2 Mail（邮件系统）

  • Project ID：_mail
  • 用途：Agent 间 Mail 通信
  • 独立 Tab 页面，list 形式展示
  • 显示字段：时间 | From | To | Title | 状态（已读/未读/已执行）
  • 未来用户说"给司马懿发 mail"→ 在此 Project 创建 Task
  • 不在主 Dashboard 的 Card 看板中显示

2.3 特殊 Project 列表

Project ID 显示位置 展示形式
_general Dashboard（普通 Project） Card 看板
_mail 独立 Tab 页 列表
其他用户 Project Dashboard Card 看板

三、项目管理

3.1 项目发现

自动发现 + 注册表补充元数据，不强制。

  • 系统启动时扫描 ~/.sanguo_projects/ 目录
  • 新发现的目录自动添加到 registry（标记 source=auto_discovered）
  • 用户可手动补充名称、描述、配置
  • 已注册的项目以注册表为准

3.2 项目 CRUD

操作 实现
自动发现 扫描 sanguo_projects 目录
手动创建 POST /api/projects
修改元数据 PATCH /api/projects/{pid}
归档 PATCH /api/projects/{pid} status→archived（级联归档所有 Card）
删除 archived 后 7-30 天物理清理

四、数据模型

4.1 Registry DB（全局）

路径：data/registry.db

CREATE TABLE IF NOT EXISTS projects (
    id          TEXT PRIMARY KEY,
    name        TEXT NOT NULL,
    description TEXT DEFAULT '',
    status      TEXT DEFAULT 'active',
    source      TEXT DEFAULT 'manual',     -- manual / auto_discovered
    config_json TEXT DEFAULT '{}',
    created_at  TEXT NOT NULL,
    updated_at  TEXT
);

4.2 Project DB（per-project）

路径：data/{pid}/blackboard.db

新增 cards 表：

CREATE TABLE IF NOT EXISTS cards (
    id          TEXT PRIMARY KEY,
    name        TEXT NOT NULL,
    description TEXT DEFAULT '',
    card_type   TEXT DEFAULT 'default',    -- default/strategy/data_pipeline/research
    stages_json TEXT DEFAULT '[]',         -- AI 生成的阶段定义
    labels_json TEXT DEFAULT '[]',
    created_at  TEXT NOT NULL,
    updated_at  TEXT,
    archived_at TEXT
);
CREATE INDEX IF NOT EXISTS idx_cards_id ON cards(id);

所有现有表加 card_id：

ALTER TABLE tasks ADD COLUMN card_id TEXT;
ALTER TABLE tasks ADD COLUMN stage TEXT DEFAULT NULL;
CREATE INDEX IF NOT EXISTS idx_tasks_card ON tasks(card_id);

ALTER TABLE outputs ADD COLUMN card_id TEXT;
ALTER TABLE reviews ADD COLUMN card_id TEXT;
ALTER TABLE comments ADD COLUMN card_id TEXT;
ALTER TABLE events ADD COLUMN card_id TEXT;
CREATE INDEX IF NOT EXISTS idx_events_card ON events(card_id);
ALTER TABLE task_attempts ADD COLUMN card_id TEXT;
ALTER TABLE routing_decisions ADD COLUMN card_id TEXT;

DDL 变更策略：

  • 新 DB：CREATE TABLE 直接包含 card_id 和 stage
  • 旧 DB：_migrate_v27() ALTER TABLE + 创建默认 Card + 回填

4.3 默认 Card

  • 每个 Project 自动创建一个 default Card
  • 迁移时所有现有数据的 card_id 设为 default
  • 用户可以直接在 default Card 上工作（不感知 Card 层）

4.4 目录结构

data/
├── registry.db
├── _general/
│   ├── blackboard.db
│   └── artifacts/
├── _mail/
│   ├── blackboard.db
│   └── artifacts/
├── sanguo_quant_live/
│   ├── blackboard.db
│   └── artifacts/
├── sanguo_vnpy/
│   ├── blackboard.db
│   └── artifacts/
└── sanguo_moziplus_v2/
    ├── blackboard.db
    └── artifacts/

五、API 路由

5.1 Project 级

GET    /api/projects                    → 列出所有项目（含自动发现的）
POST   /api/projects                    → 手动创建项目
GET    /api/projects/{pid}              → 项目详情 + 聚合统计
PATCH  /api/projects/{pid}              → 更新项目元数据
DELETE /api/projects/{pid}              → 删除项目（archived 后）

5.2 Card 级

GET    /api/projects/{pid}/cards                  → 列出所有 Card
POST   /api/projects/{pid}/cards                  → 创建 Card
GET    /api/projects/{pid}/cards/{cid}            → Card 详情 + Stage 进度
PATCH  /api/projects/{pid}/cards/{cid}            → 更新 Card（改名/归档/调整 stages）
DELETE /api/projects/{pid}/cards/{cid}            → 删除 Card
POST   /api/projects/{pid}/cards/{cid}/fork       → Fork Card（策略迭代）

5.3 Task 级

GET    /api/projects/{pid}/cards/{cid}/tasks              → Card 下所有 Task
POST   /api/projects/{pid}/cards/{cid}/tasks              → 创建 Task
GET    /api/projects/{pid}/cards/{cid}/tasks/{tid}        → Task 详情
POST   /api/projects/{pid}/cards/{cid}/tasks/{tid}/status → 更新状态
POST   /api/projects/{pid}/cards/{cid}/tasks/{tid}/outputs → 添加产出
POST   /api/projects/{pid}/cards/{cid}/tasks/{tid}/reviews → 添加审查
POST   /api/projects/{pid}/cards/{cid}/tasks/{tid}/comments → 添加评论

5.4 便利路由

GET    /api/projects/{pid}/tasks          → Project 下所有 active cards 的 tasks（合并）
GET    /api/projects/{pid}/events         → Project 下所有事件

5.5 Mail Tab

GET    /api/mail                          → Mail 列表（from/to/title/status/time）
GET    /api/mail/{id}                     → Mail 详情
PATCH  /api/mail/{id}                     → 标记已读/已执行

5.6 向后兼容

  • 旧路由 /api/projects/{pid}/tasks 保留，内部查所有 active cards
  • 不传 card_id 时自动使用 default Card
  • 前端渐进迁移

六、Ticker 变更

6.1 扫描逻辑

for project in registry.list_projects(status='active'):
    db_path = data_root / project.id / "blackboard.db"
    active_cards = card_ops.list_cards(db_path, status='active')
    for card in active_cards:
        tick_card(db_path, card.id)

6.2 性能

  • 单 DB 内按 card_id 查询，索引命中，微秒级
  • active cards 过多时加 LIMIT 分批

七、上下文隔离

7.1 Agent 视角

Agent 执行 Task 时，prompt 只注入当前 Card 的数据：

context = queries.build_agent_context(db_path, task_id, card_id=task.card_id)

7.2 写入自动带 card_id

Agent 写 output、改 status 时，API 自动从 Task 关联获取 card_id，Agent 不感知。

7.3 跨 Card 引用

Fork Card 时可注入源 Card 的摘要。写入仍在当前 Card。

八、Stage 进度

8.1 AI 动态生成

  1. Card 创建时，AI 根据目标描述生成初始 stages → 写入 stages_json
  2. 执行中 Agent 可提议修改 stages（新增/删除/重排）→ 更新 stages_json
  3. 用户可手动调整
  4. Task 绑定 stage，前端按 stage 分组显示

8.2 进度计算

def card_progress(db_path, card_id, stages):
    for stage in stages:
        total = count(tasks WHERE card_id=? AND stage=?)
        done = count(tasks WHERE card_id=? AND stage=? AND status='done')
        active = count(tasks WHERE card_id=? AND stage=? AND status IN ('working','review'))

8.3 默认 Stage

不指定 stage 的 Task 归入"未分类"组。

九、联动功能

阶段 操作 粒度 谁触发
创建 创建 Project Project 用户/AI
创建 Card Card 用户/AI
创建 Task Task 用户/AI/Ticker
发现 扫描 sanguo_projects 目录 Project 系统
手动补充元数据 Project 用户
规划 AI 生成 Stages Card AI
AI 动态调整 Stages Card AI 提议
用户调整 Stages Card 用户
执行 Agent 执行 Task Task Ticker
Review 流转 Task Ticker/Agent
重试/暂停/取消 Task Task Ticker/用户/AI
进度 Stage 进度条 Card 自动推导
Card 状态聚合 Card 自动推导
Project 整体进度 Project 自动推导
查询 单 Card 查询 Card 用户/AI
单 Project 查询 Project 用户/AI
全局任务列表 跨 Project 用户/AI
暂停 暂停 Card Card 用户/AI
暂停 Project Project 用户
取消 取消 Card Card 用户/AI
取消 Project Project 用户
归档 归档 Card Card 用户/AI
归档 Project（级联 Card） Project 用户
查看归档数据 Card/Project 用户
删除 物理清理（归档 7-30 天后） Card/Project 系统
立即删除 Card/Project 用户
恢复 归档 → active Card/Project 用户
已删除 → 恢复（7天内） Card/Project 用户
Fork 从已有 Card 创建新 Card Card 用户/AI
移动 Task 跨 Card 移动 Task 用户
Card 跨 Project 移动 Card 用户

十、前端设计

10.1 页面结构

┌─────────────────────────────────────────────────┐
│  [Dashboard]  [Mail]  [Settings]                │  ← 顶部 Tab
├─────────────────────────────────────────────────┤
│  左侧：Project 导航                             │
│  ├── General                                     │
│  ├── sanguo_quant_live                          │
│  ├── sanguo_vnpy                                │
│  └── sanguo_moziplus_v2                         │
├─────────────────────────────────────────────────┤
│  右侧：Card 看板 / Mail 列表                     │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐        │
│  │ Card 1   │ │ Card 2   │ │ Card 3   │        │
│  │ ■■■□ 75% │ │ ■□□□ 20% │ │ □□□□  0% │        │
│  └──────────┘ └──────────┘ └──────────┘        │
│                                                  │
│  [Stage 进度条]  [Task 列表]  [事件流]           │
└─────────────────────────────────────────────────┘

10.2 Mail Tab

时间 From To Title 状态
22:30 simayi pangtong 路由方案评审通过 ✅ 已读
22:15 pangtong simayi 代码评审请求 📬 未读
21:40 zhangfei pangtong e2e-rt-002 完成 ✅ 已执行

10.3 Card 详情

  • 顶部：Stage 进度条
  • 中部：Task 列表（按 stage 分组）
  • 底部：事件流 / 评论

十一、路由方案兼容性

完全兼容：

  • routing_decisions 表加 card_id
  • agent_profiles 和 routing 配置在 Project 级
  • AgentRouter per-Project，Card 只是查询过滤条件

十二、数据迁移

def migrate_v27(db_path):
    # 1. 创建 cards 表
    # 2. 所有表加 card_id + stage
    # 3. 创建 default Card
    # 4. 回填 card_id = 'default'
    # 5. 创建索引

def migrate_registry(data_root):
    # 读 _registry.yaml → 写 registry.db
    # 扫描 sanguo_projects 目录 → 补充 auto_discovered

十三、实施计划

v2.7.0 范围

序号 任务 预计
1 registry.db + ProjectRegistry + 自动发现 0.5 天
2 cards 表 + 所有表加 card_id + stage + 迁移 0.5 天
3 CardOps + Blackboard/Queries 加 card_id 1 天
4 API 路由（Card CRUD + Task 嵌套 + Mail） 1 天
5 Ticker 适配（per-card 扫描） 0.5 天
6 前端 Dashboard 重构（Card 看板 + Stage 进度） 1.5 天
7 前端 Mail Tab 0.5 天
8 端到端测试 + 迁移验证 0.5 天
合计 6 天

不在 v2.7.0 范围

  • Card 模板系统（Phase 2）
  • 全局搜索/FTS（Phase 2）
  • 跨 Project 统计报表（Phase 2）
  • 冷存储迁移脚本（按需）

前置条件

  • ✅ v2.6.1 路由方案已落地并 E2E 验证
Reference in New Issue View Git Blame Copy Permalink