From b22dec3a060663c9baba4ec407a88fd497693e33 Mon Sep 17 00:00:00 2001 From: cfdaily Date: Sun, 17 May 2026 23:21:00 +0800 Subject: [PATCH] auto-sync: 2026-05-17 23:21:00 --- docs/design/v2.7-three-tier-hierarchy.md | 527 +++++++++++++---------- 1 file changed, 310 insertions(+), 217 deletions(-) diff --git a/docs/design/v2.7-three-tier-hierarchy.md b/docs/design/v2.7-three-tier-hierarchy.md index a41d736..3ab0639 100644 --- a/docs/design/v2.7-three-tier-hierarchy.md +++ b/docs/design/v2.7-three-tier-hierarchy.md @@ -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=冷，按需加载 |