# 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`

```sql
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 表：**

```sql
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：**

```sql
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 扫描逻辑

```python
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 的数据：

```python
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 进度计算

```python
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 只是查询过滤条件

---

## 十二、数据迁移

```python
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 验证