auto-sync: 2026-05-17 23:21:00
This commit is contained in:
cfdaily
@@ -1,71 +1,135 @@
|
||||
# v2.7 三级层次结构设计：Project / Card / Task
|
||||
# v2.7 三级层次结构完整设计文档
|
||||
|
||||
> 日期：2026-05-17
|
||||
> 作者：庞统 + 司马懿（共识）→ 用户确认逻辑隔离方案
|
||||
> 状态：待用户确认最终版
|
||||
> 版本：v1.0
|
||||
> 作者：庞统
|
||||
> 状态：待评审
|
||||
> 变更记录：与用户 6 轮讨论后定稿
|
||||
|
||||
---
|
||||
|
||||
## 一、核心设计决策
|
||||
## 一、核心架构
|
||||
|
||||
### 1.1 三层定义
|
||||
### 1.1 三层结构
|
||||
|
||||
```
|
||||
Project（项目）
|
||||
└── Card（卡片/策略）
|
||||
├── Task（任务）
|
||||
├── Output（产出）
|
||||
├── Review（审查）
|
||||
├── Comment（评论）
|
||||
├── Event（事件）
|
||||
└── routing_decisions（路由审计）
|
||||
└── Card（卡片/策略/工作流）
|
||||
└── Task（原子任务）
|
||||
```
|
||||
|
||||
| 层级 | 语义 | 例子 | 生命周期 |
|
||||
|------|------|------|---------|
|
||||
| **Project** | 业务领域/产品线 | sanguo_quant_live、sanguo_vnpy | 长期（月/年） |
|
||||
| **Card** | 独立的工作流/策略 | 动量策略v1、数据平台P3 | 中期（天/周） |
|
||||
| **Task** | 具体执行单元 | 编写回测脚本、清洗分钟线 | 短期（小时/天） |
|
||||
| **Project** | 业务领域/产品线 | sanguo_quant_live、General、Mail | 长期 |
|
||||
| **Card** | 独立的工作流/策略 | 动量策略v1、v2.7开发 | 中期（天/周） |
|
||||
| **Task** | 原子执行单元 | 编写回测脚本、清洗分钟线 | 短期（小时/天） |
|
||||
|
||||
### 1.2 隔离策略：一个 Project 一个 DB + card_id 逻辑隔离
|
||||
### 1.2 隔离策略
|
||||
|
||||
**物理隔离**（一 Card 一 DB）vs **逻辑隔离**（一 Project 一 DB + card_id 字段）：
|
||||
**一个 Project 一个 DB + card_id 逻辑隔离。**
|
||||
|
||||
| 维度 | 物理隔离 | 逻辑隔离 ✅ 选定 |
|
||||
|------|---------|----------------|
|
||||
| 业界参考 | 无主流先例 | Jira（单表+类型字段）、Linear（单DB+team_id）、Asana（单DB+workspace_id） |
|
||||
| DB 文件数 | Card 数量级（可能上百） | Project 数量级（个位数） |
|
||||
| 跨 Card 查询 | 不可能（跨库） | 天然支持（同一 DB） |
|
||||
| 事务 | Card 内完整，跨 Card 不可能 | Project 内任意事务 |
|
||||
| 归档 | 关闭连接即可 | 按 card_id UPDATE status |
|
||||
| Agent prompt | 天然干净 | 查询时加 WHERE card_id=? 过滤 |
|
||||
| 复杂度 | DB 文件管理复杂 | 所有表加一列，查询统一 |
|
||||
| 备份 | 按 Card 备份（碎片化） | 按 Project 备份（完整） |
|
||||
理由：
|
||||
- Jira/Linear/Asana 均采用逻辑隔离，是成熟模式
|
||||
- 跨 Card 查询天然支持（同一 DB）
|
||||
- 备份/迁移按 Project 独立
|
||||
- 单 DB <5000 Task，SQLite 性能无忧
|
||||
|
||||
**选逻辑隔离的理由：**
|
||||
1. **优秀实践一致**：Jira/Linear/Asana 都用逻辑隔离，说明这是成熟模式
|
||||
2. **调研报告建议**（5.4 节）："单实例 + Card 级命名空间"
|
||||
3. **跨 Card 查询有需求**：用户看 Project 概览时需要聚合所有 Card 的 tasks
|
||||
4. **运维简单**：一个 Project 一个文件，备份/迁移/清理都方便
|
||||
5. **Card 数量可控**：Ticker 查询 `WHERE card_id IN (active_cards)` 性能无问题
|
||||
**跨 Card 依赖不支持**——策略间应独立，数据引用用 artifacts 路径。
|
||||
|
||||
### 1.3 归档/恢复 — 只改 metadata
|
||||
### 1.3 Card 状态 = Task 状态聚合
|
||||
|
||||
- cards 表 status 字段：`active` / `closed` / `archived` / `deleted`
|
||||
- 归档 = `UPDATE cards SET status='archived'` → Ticker 跳过 → 不 dispatch 新任务
|
||||
- 恢复 = `UPDATE cards SET status='active'`
|
||||
- 删除 = status=deleted + 7 天后异步清理关联数据
|
||||
Card 不独立维护状态机，状态从内部 Task 推导（取最高水位）：
|
||||
|
||||
### 1.4 跨 Card 依赖 — 不支持
|
||||
| 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** | 系统清理 | ❌ | ❌ |
|
||||
|
||||
- 业务上策略之间应该独立
|
||||
- 如果策略B 用策略A 的数据，那是数据层面的事（artifacts 路径引用），不是编排层面的事
|
||||
额外两个状态（超出 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 Registry DB（全局唯一，管理 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`
|
||||
|
||||
@@ -74,16 +138,15 @@ CREATE TABLE IF NOT EXISTS projects (
|
||||
id TEXT PRIMARY KEY,
|
||||
name TEXT NOT NULL,
|
||||
description TEXT DEFAULT '',
|
||||
status TEXT DEFAULT 'active', -- active/archived/deleted
|
||||
config_json TEXT DEFAULT '{}', -- agents、routing 等项目级配置
|
||||
status TEXT DEFAULT 'active',
|
||||
source TEXT DEFAULT 'manual', -- manual / auto_discovered
|
||||
config_json TEXT DEFAULT '{}',
|
||||
created_at TEXT NOT NULL,
|
||||
updated_at TEXT
|
||||
);
|
||||
```
|
||||
|
||||
**职责**：只管 Project 列表 + 指向 DB 文件路径。Card 信息在 Project DB 内部管理。
|
||||
|
||||
### 2.2 Project DB（per-project，逻辑隔离）
|
||||
### 4.2 Project DB（per-project）
|
||||
|
||||
路径：`data/{pid}/blackboard.db`
|
||||
|
||||
@@ -94,285 +157,315 @@ CREATE TABLE IF NOT EXISTS cards (
|
||||
id TEXT PRIMARY KEY,
|
||||
name TEXT NOT NULL,
|
||||
description TEXT DEFAULT '',
|
||||
status TEXT DEFAULT 'active', -- active/closed/archived/deleted
|
||||
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_status ON cards(status);
|
||||
CREATE INDEX IF NOT EXISTS idx_cards_id ON cards(id);
|
||||
```
|
||||
|
||||
**现有所有表加 card_id 字段：**
|
||||
**所有现有表加 card_id：**
|
||||
|
||||
```sql
|
||||
-- tasks 表
|
||||
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);
|
||||
|
||||
-- outputs 表
|
||||
ALTER TABLE outputs ADD COLUMN card_id TEXT;
|
||||
CREATE INDEX IF NOT EXISTS idx_outputs_card ON outputs(card_id);
|
||||
|
||||
-- reviews 表
|
||||
ALTER TABLE reviews ADD COLUMN card_id TEXT;
|
||||
|
||||
-- comments 表
|
||||
ALTER TABLE comments ADD COLUMN card_id TEXT;
|
||||
|
||||
-- events 表
|
||||
ALTER TABLE events ADD COLUMN card_id TEXT;
|
||||
CREATE INDEX IF NOT EXISTS idx_events_card ON events(card_id);
|
||||
|
||||
-- task_attempts 表
|
||||
ALTER TABLE task_attempts ADD COLUMN card_id TEXT;
|
||||
|
||||
-- routing_decisions 表
|
||||
ALTER TABLE routing_decisions ADD COLUMN card_id TEXT;
|
||||
```
|
||||
|
||||
**DDL 变更策略：**
|
||||
- CREATE TABLE 语句直接包含 card_id（新 DB）
|
||||
- 旧 DB 通过 `_migrate_v27()` 添加列 + 创建默认 Card + 回填 card_id
|
||||
- 每个查询都加 WHERE card_id=? 过滤
|
||||
- 新 DB：CREATE TABLE 直接包含 card_id 和 stage
|
||||
- 旧 DB：`_migrate_v27()` ALTER TABLE + 创建默认 Card + 回填
|
||||
|
||||
### 2.3 默认 Card
|
||||
### 4.3 默认 Card
|
||||
|
||||
迁移策略：每个旧 DB 自动创建一个默认 Card（id=`default`），将所有现有数据的 card_id 设为 `default`。
|
||||
- 每个 Project 自动创建一个 `default` Card
|
||||
- 迁移时所有现有数据的 card_id 设为 `default`
|
||||
- 用户可以直接在 default Card 上工作（不感知 Card 层）
|
||||
|
||||
新建 Project 时也自动创建一个默认 Card，用户可以直接在默认 Card 上工作（不感知 Card 层），也可以手动创建新 Card。
|
||||
|
||||
### 2.4 目录结构
|
||||
### 4.4 目录结构
|
||||
|
||||
```
|
||||
data/
|
||||
├── registry.db ← Project 列表
|
||||
├── registry.db
|
||||
├── _general/
|
||||
│ ├── blackboard.db
|
||||
│ └── artifacts/
|
||||
├── _mail/
|
||||
│ ├── blackboard.db
|
||||
│ └── artifacts/
|
||||
├── sanguo_quant_live/
|
||||
│ ├── blackboard.db ← Project 级 DB（含 cards 表 + card_id 隔离）
|
||||
│ └── artifacts/ ← 产出物文件
|
||||
│ ├── strategy-momentum-v1/
|
||||
│ ├── strategy-mean-reversion/
|
||||
│ └── default/
|
||||
│ ├── blackboard.db
|
||||
│ └── artifacts/
|
||||
├── sanguo_vnpy/
|
||||
│ ├── blackboard.db
|
||||
│ └── artifacts/
|
||||
└── inbox/ ← 快捷单 Card 项目
|
||||
└── fetch-data-001/
|
||||
├── blackboard.db
|
||||
└── artifacts/
|
||||
└── sanguo_moziplus_v2/
|
||||
├── blackboard.db
|
||||
└── artifacts/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、API 路由变更
|
||||
## 五、API 路由
|
||||
|
||||
### 3.1 新路由
|
||||
### 5.1 Project 级
|
||||
|
||||
```
|
||||
# Project 级
|
||||
GET /api/projects → 列出所有项目
|
||||
POST /api/projects → 创建项目（自动创建默认 Card）
|
||||
GET /api/projects/{pid} → 项目详情
|
||||
PATCH /api/projects/{pid} → 更新项目配置
|
||||
DELETE /api/projects/{pid} → 删除项目
|
||||
GET /api/projects → 列出所有项目（含自动发现的）
|
||||
POST /api/projects → 手动创建项目
|
||||
GET /api/projects/{pid} → 项目详情 + 聚合统计
|
||||
PATCH /api/projects/{pid} → 更新项目元数据
|
||||
DELETE /api/projects/{pid} → 删除项目（archived 后）
|
||||
```
|
||||
|
||||
# Card 级
|
||||
GET /api/projects/{pid}/cards → 列出项目下所有 Card
|
||||
### 5.2 Card 级
|
||||
|
||||
```
|
||||
GET /api/projects/{pid}/cards → 列出所有 Card
|
||||
POST /api/projects/{pid}/cards → 创建 Card
|
||||
GET /api/projects/{pid}/cards/{cid} → Card 详情（含聚合统计）
|
||||
PATCH /api/projects/{pid}/cards/{cid} → 更新 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（策略迭代）
|
||||
```
|
||||
|
||||
# Task 级（嵌套在 Card 下）
|
||||
GET /api/projects/{pid}/cards/{cid}/tasks → 列出 Card 下所有 Task
|
||||
### 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 → 添加评论
|
||||
GET /api/projects/{pid}/cards/{cid}/events → Card 事件流
|
||||
|
||||
# 便利路由（前端兼容/项目概览）
|
||||
GET /api/projects/{pid}/tasks → 该 Project 所有 active cards 的 tasks（合并）
|
||||
GET /api/projects/{pid}/events → 该 Project 所有 active cards 的事件（合并）
|
||||
```
|
||||
|
||||
### 3.2 向后兼容
|
||||
### 5.4 便利路由
|
||||
|
||||
- `GET /api/projects/{pid}/tasks` 保留，内部查所有 active cards 的 tasks
|
||||
- 旧前端不传 card_id 时，自动使用 `default` Card
|
||||
- 渐进迁移：前端可以先不感知 Card 层，按需升级
|
||||
```
|
||||
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 变更
|
||||
## 六、Ticker 变更
|
||||
|
||||
### 4.1 当前逻辑
|
||||
### 6.1 扫描逻辑
|
||||
|
||||
```python
|
||||
for project_id in registry.projects:
|
||||
db_path = data_root / project_id / "blackboard.db"
|
||||
_tick_project(db_path, ...)
|
||||
```
|
||||
|
||||
### 4.2 变更后
|
||||
|
||||
```python
|
||||
for project_id in registry.list_projects(status='active'):
|
||||
db_path = data_root / project_id / "blackboard.db"
|
||||
# 查出所有 active cards
|
||||
active_cards = queries.list_cards(db_path, status='active')
|
||||
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, ...)
|
||||
tick_card(db_path, card.id)
|
||||
```
|
||||
|
||||
### 4.3 性能
|
||||
### 6.2 性能
|
||||
|
||||
- 单 DB 内按 card_id 查询，SQLite 索引命中，微秒级
|
||||
- 无打开/关闭多个 DB 的开销
|
||||
- active cards 过多时加 `LIMIT` 分批
|
||||
- 单 DB 内按 card_id 查询，索引命中，微秒级
|
||||
- active cards 过多时加 LIMIT 分批
|
||||
|
||||
---
|
||||
|
||||
## 五、Blackboard 操作变更
|
||||
## 七、上下文隔离
|
||||
|
||||
### 5.1 现有接口签名变更
|
||||
### 7.1 Agent 视角
|
||||
|
||||
所有 Blackboard/Queries 方法加 `card_id` 参数：
|
||||
Agent 执行 Task 时，prompt 只注入当前 Card 的数据：
|
||||
|
||||
```python
|
||||
# Before
|
||||
bb.create_task(task)
|
||||
|
||||
# After
|
||||
bb.create_task(task, card_id="strategy-momentum-v1")
|
||||
|
||||
# Before
|
||||
q.tasks_by_status("pending")
|
||||
|
||||
# After
|
||||
q.tasks_by_status("pending", card_id="strategy-momentum-v1")
|
||||
context = queries.build_agent_context(db_path, task_id, card_id=task.card_id)
|
||||
```
|
||||
|
||||
### 5.2 Card 管理
|
||||
### 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
|
||||
class CardOps:
|
||||
"""Card CRUD（操作 Project DB 内的 cards 表）"""
|
||||
def create_card(self, db_path, card_id, name, card_type="default") -> dict
|
||||
def get_card(self, db_path, card_id) -> dict | None
|
||||
def list_cards(self, db_path, status=None) -> list[dict]
|
||||
def update_card(self, db_path, card_id, **kwargs) -> bool
|
||||
def archive_card(self, db_path, card_id) -> bool
|
||||
def restore_card(self, db_path, card_id) -> bool
|
||||
def delete_card(self, db_path, card_id) -> bool
|
||||
|
||||
def card_stats(self, db_path, card_id) -> dict:
|
||||
"""聚合统计：task数、完成率、活跃agent等"""
|
||||
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 归入"未分类"组。
|
||||
|
||||
---
|
||||
|
||||
## 六、路由方案兼容性
|
||||
## 九、联动功能
|
||||
|
||||
**完全兼容：**
|
||||
|
||||
- routing_decisions 表加 card_id，审计按 Card 隔离
|
||||
- current_agent / previous_agent 在 task 级别，通过 card_id 自然隔离
|
||||
- agent_profiles 和 routing 配置在 Project 级（registry.db 的 config_json 或项目级配置文件）
|
||||
- AgentRouter 实例 per-Project，Card 只是查询过滤条件
|
||||
| 阶段 | 操作 | 粒度 | 谁触发 |
|
||||
|------|------|------|--------|
|
||||
| **创建** | 创建 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 | 用户 |
|
||||
|
||||
---
|
||||
|
||||
## 七、前端变更
|
||||
## 十、前端设计
|
||||
|
||||
### 7.1 导航结构
|
||||
### 10.1 页面结构
|
||||
|
||||
```
|
||||
当前: Project List → Task List
|
||||
变更: Project List → Card List → Task List
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ [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 列表] [事件流] │
|
||||
└─────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 7.2 新增组件
|
||||
### 10.2 Mail Tab
|
||||
|
||||
- **CardList**：卡片式展示（名称、状态 badge、task 进度条、操作按钮）
|
||||
- **CardDetail**：单 Card 概览（聚合统计 + 事件流）
|
||||
- 新建 Card 对话框
|
||||
| 时间 | From | To | Title | 状态 |
|
||||
|------|------|----|-------|------|
|
||||
| 22:30 | simayi | pangtong | 路由方案评审通过 | ✅ 已读 |
|
||||
| 22:15 | pangtong | simayi | 代码评审请求 | 📬 未读 |
|
||||
| 21:40 | zhangfei | pangtong | e2e-rt-002 完成 | ✅ 已执行 |
|
||||
|
||||
### 7.3 便利模式
|
||||
### 10.3 Card 详情
|
||||
|
||||
Project 概览页：展示所有 active cards 的 tasks 合并视图（按 Card 分组折叠）
|
||||
|
||||
### 7.4 渐进迁移
|
||||
|
||||
- Phase 1：后端支持 Card，前端不感知（所有操作走 default Card）
|
||||
- Phase 2：前端加 CardList 导航
|
||||
- Phase 3：Card 模板、归档管理、可视化
|
||||
- 顶部：Stage 进度条
|
||||
- 中部：Task 列表（按 stage 分组）
|
||||
- 底部：事件流 / 评论
|
||||
|
||||
---
|
||||
|
||||
## 八、数据迁移
|
||||
## 十一、路由方案兼容性
|
||||
|
||||
### 8.1 迁移脚本
|
||||
完全兼容：
|
||||
- routing_decisions 表加 card_id
|
||||
- agent_profiles 和 routing 配置在 Project 级
|
||||
- AgentRouter per-Project，Card 只是查询过滤条件
|
||||
|
||||
---
|
||||
|
||||
## 十二、数据迁移
|
||||
|
||||
```python
|
||||
def migrate_v27(db_path: Path):
|
||||
"""将旧 DB 升级到 v2.7 三级结构"""
|
||||
def migrate_v27(db_path):
|
||||
# 1. 创建 cards 表
|
||||
# 2. 所有表加 card_id 列
|
||||
# 3. 创建默认 Card（id='default'）
|
||||
# 4. 回填所有现有数据的 card_id = 'default'
|
||||
# 2. 所有表加 card_id + stage
|
||||
# 3. 创建 default Card
|
||||
# 4. 回填 card_id = 'default'
|
||||
# 5. 创建索引
|
||||
```
|
||||
|
||||
### 8.2 Registry 迁移
|
||||
|
||||
```python
|
||||
def migrate_registry(data_root: Path):
|
||||
"""将 _registry.yaml 迁移为 registry.db"""
|
||||
# 读 _registry.yaml → 写 registry.db projects 表
|
||||
# 每个 project 目录下已有 blackboard.db，路径不变
|
||||
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 + 迁移 | 0.5 天 |
|
||||
| 3 | CardOps + Blackboard/Queries 接口加 card_id | 1 天 |
|
||||
| 4 | API 路由（Card CRUD + Task 嵌套） | 1 天 |
|
||||
| 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 | 前端 CardList + 导航 | 1 天 |
|
||||
| 7 | 端到端测试 + 迁移验证 | 0.5 天 |
|
||||
| **合计** | | **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 验证
|
||||
|
||||
### 不在 v2.7.0 范围
|
||||
|
||||
- 跨 Card 依赖（不支持）
|
||||
- Card 模板
|
||||
- 向量检索/摘要（Phase 2）
|
||||
- 冷存储迁移脚本
|
||||
|
||||
---
|
||||
|
||||
## 十、与调研报告的对齐
|
||||
|
||||
| 调研发现 | 方案对齐 |
|
||||
|---------|---------|
|
||||
| Jira：单表 + 类型字段 + project_id 隔离 | ✅ 单 DB + card_id 字段，完全一致 |
|
||||
| Linear：单DB + team_id 过滤 | ✅ 单 DB + card_id 过滤，完全一致 |
|
||||
| LangGraph：Subgraph 独立 State | Card 是查询隔离，非物理隔离 |
|
||||
| Context Folding：子任务折叠为摘要 | Card 归档时折叠，保留元数据索引 |
|
||||
| Hot/Cold Memory 分离 | active=热、archived=冷，按需加载 |
|
||||
|
||||
Reference in New Issue
Block a user