diff --git a/docs/02-架构设计/专项设计/AI原生上下文地图与去AI化进化系统-2026-06-26.md b/docs/02-架构设计/专项设计/AI原生上下文地图与去AI化进化系统-2026-06-26.md new file mode 100644 index 0000000..8dd897c --- /dev/null +++ b/docs/02-架构设计/专项设计/AI原生上下文地图与去AI化进化系统-2026-06-26.md @@ -0,0 +1,401 @@ +# AI 原生工作模式：上下文地图与去 AI 化进化系统 + +> **文档状态**：构想 → 架构设计 +> **创建日期**：2026-06-26 +> **关联灵感**：Idea `84797cb1-37f2-4599-ba5f-ae8d8555dc0f` +> **核心理念**：让 AI 做得越来越少——高频路径逐步结晶为确定性逻辑，AI 退守到真正需要推理的边界。 + +--- + +## 0. 问题诊断：当前 AI 工作流的资源浪费 + +### 0.1 现状痛点 + +| 症状 | 根因 | 代价 | +|------|------|------| +| 每次对话都从零检索项目结构 | 无持久化的工程地图 | 30-40% token 浪费在重复探索 | +| 简单文件操作也要 LLM 推理 | 无模式结晶机制 | 推理延迟 + API 成本 | +| AI 不知道上次改了什么 | 无上下文缓存层 | 重复扫描 + 上下文断裂 | +| 高频任务路径无法优化 | 无执行频度感知 | 永远全量推理，无法降级 | + +### 0.2 核心洞察 + +> AI 原生不等于"什么都让 AI 做"。真正的 AI 原生是：**AI 构建认知基础设施，然后将高频路径交给确定性逻辑，自身退守到创造性边界。** + +--- + +## 1. 架构总览：三层地图 + 缓存层 + 结晶器 + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ AI Agentic Loop │ +│ │ +│ ┌──────────┐ ┌──────────────┐ ┌───────────┐ ┌────────────┐ │ +│ │ Working │ │ Coding │ │ Tool │ │ Context │ │ +│ │ Map │──▶│ Map │──▶│ Map │──▶│ Cache │ │ +│ │ (任务态) │ │ (代码态) │ │ (工具态) │ │ (会话态) │ │ +│ └──────────┘ └──────────────┘ └───────────┘ └─────┬──────┘ │ +│ │ │ +│ ┌──────────▼───────┐ │ +│ │ Pattern │ │ +│ │ Crystallizer │ │ +│ │ (模式结晶器) │ │ +│ └──────────┬───────┘ │ +└─────────────────────────────────────────────────┼─────────┼────────┘ + │ │ + ┌─────────────▼─┐ ┌───▼──────────┐ + │ Deterministic │ │ Frequency │ + │ Scripts │ │ Tracker │ + │ (确定性脚本) │ │ (频度追踪) │ + └───────────────┘ └──────────────┘ +``` + +### 1.1 设计原则 + +1. **地图先行**：AI 的每次操作都基于预构建的地图，而非实时盲搜 +2. **缓存就近**：会话级上下文缓存，避免跨轮重复推理 +3. **频度驱动结晶**：高频路径自动进入结晶候选队列 +4. **渐进去 AI 化**：结晶后的路径从 LLM 推理降级为确定性脚本 + +--- + +## 2. 三层地图设计 + +### 2.1 Working Map（工作地图 — 任务态） + +**职责**：描述"当前在做什么"——任务、项目、灵感、工作流的实时状态拓扑。 + +``` +WorkingMap +├── active_projects[] // 活跃项目清单（含 stack/path/bind 状态） +├── active_tasks[] // 进行中任务（含 status/assignee/blocker） +├── task_dependencies[] // 任务间依赖（子任务/阻塞关系） +├── recent_decisions[] // 近期决策记录（灵感→任务转化轨迹） +├── workflow_state // 当前工作流执行状态 +└── project_modules[] // 多工程结构（复用 modules 表） +``` + +**DevFlow 现状对接**： +- `projects` 表 → `active_projects` +- `tasks` 表 → `active_tasks` +- `ideas` 表 → `recent_decisions`（灵感→任务转化链） +- `modules` + `module_dependencies` 表 → `project_modules`（多工程功能，子1-5 任务在建） + +**构建时机**： +- 冷启动：从 SQLite 全量加载活跃实体 +- 热更新：CRUD 操作触发增量更新（事件驱动，复用全局事件总线） + +### 2.2 Coding Map（代码地图 — 结构态） + +**职责**：描述"代码长什么样"——文件树、符号索引、依赖图、技术栈。 + +``` +CodingMap +├── module_index[] // 每个工程的文件树 + 技术栈 +│ ├── file_tree // 目录结构（懒加载，按需展开） +│ ├── symbol_index // AST 符号索引（函数/结构体/类） +│ └── stack_signature // 技术栈指纹（Cargo.toml/package.json/...） +├── cross_module_deps[] // 跨工程依赖（API 调用/类库引入/消息通信） +├── recent_changes[] // 近期文件变更（git diff + 时间窗口） +└── hotspots[] // 热点文件（高频访问/修改的文件） +``` + +**DevFlow 现状对接**： +- `read_symbol` 工具 → `symbol_index` 的查询入口 +- `detect_stack` 逻辑 → `stack_signature` +- `modules` + `module_dependencies` → `cross_module_deps` +- 知识库 Tier1 → `CodingMap` 的知识层补充 + +**构建策略**： +- 符号索引：按需解析（首次访问某文件时触发 AST 解析，结果缓存） +- 依赖图：module 绑定目录时构建，变更时增量更新 +- 热点追踪：记录工具调用中的文件访问频度 + +### 2.3 Tool Map（工具地图 — 能力态） + +**职责**：描述"AI 能做什么"——工具注册表、工具调用历史、工具审批策略。 + +``` +ToolMap +├── registered_tools[] // 已注册工具清单（名称/参数schema/风险等级） +├── tool_call_history[] // 近期调用历史（参数/结果/耗时/是否审批） +├── approval_policies[] // 审批策略（自动批准/人工审批/拒绝） +├── tool_success_rate // 各工具成功率统计 +└── parameter_patterns[] // 常见参数模式（用于结晶候选识别） +``` + +**DevFlow 现状对接**： +- 工具注册表（68 IPC commands）→ `registered_tools` +- 工具审批机制（Agentic Loop + 审批）→ `approval_policies` +- `tool_call_history` → 新增，记录到 SQLite 或内存环形缓冲 + +--- + +## 3. Context Cache（上下文缓存层） + +**职责**：在 Agentic Loop 的多轮对话中，缓存已检索/已推理的上下文，避免重复劳动。 + +### 3.1 缓存结构 + +```rust +pub struct ContextCache { + /// 会话级：当前对话已探索的文件/符号 + explored_files: HashMap, + + /// 任务级：当前任务关联的上下文窗口 + task_context: HashMap, + + /// 推理缓存：相同输入的推理结果（短 TTL） + inference_cache: LruCache, + + /// 工具结果缓存：相同参数的工具调用结果 + tool_result_cache: LruCache, +} +``` + +### 3.2 缓存失效策略 + +| 缓存类型 | TTL | 失效条件 | +|----------|-----|----------| +| `explored_files` | 会话级 | 文件被修改（mtime 变化） | +| `task_context` | 任务级 | 任务状态变更 | +| `inference_cache` | 5 分钟 | 时间过期或上下文窗口滑动 | +| `tool_result_cache` | 10 分钟 | 时间过期或目标文件变更 | + +### 3.3 预期收益 + +- 减少 **50-60%** 的重复推理量 +- 工具调用延迟降低（缓存命中直接返回） +- 对话连续性增强（AI"记得"上次探索的结果） + +--- + +## 4. Pattern Crystallizer（模式结晶器） + +**职责**：识别高频任务路径，将其从 LLM 推理降级为确定性脚本/规则。 + +### 4.1 结晶流水线 + +``` +Frequency Tracker Pattern Analyzer Crystallizer +┌──────────────┐ ┌──────────────┐ ┌──────────────┐ +│ 记录每次工具 │──▶ N 次 ─▶│ 分析参数模式 │──▶ 稳定 ─▶│ 生成确定性 │──▶ 注册为 +│ 调用的签名 │ 以上 │ + 成功率 │ 模式 │ 脚本/规则 │ 新工具 +└──────────────┘ └──────────────┘ └──────────────┘ +``` + +### 4.2 数据结构 + +```rust +pub struct FrequencyTracker { + /// 工具调用签名 → 出现次数 + call_signatures: HashMap, + + /// 参数模式聚类（相同工具 + 相似参数归为一类） + parameter_clusters: HashMap>, +} + +pub struct CrystallizedPattern { + id: String, + /// 触发条件（何时使用此结晶路径） + trigger: PatternTrigger, + /// 确定性执行逻辑（脚本/规则/模板） + execution: DeterministicExecution, + /// 置信度（基于历史成功率） + confidence: f32, + /// 回退策略（结晶路径失败时回退到 LLM 推理） + fallback: FallbackStrategy, +} + +pub enum DeterministicExecution { + /// 预定义脚本（Shell/Python） + Script(PathBuf), + /// 参数化模板（填充变量后直接执行） + Template(Template), + /// 规则引擎（条件→动作映射） + Rule(RuleSet), +} +``` + +### 4.3 结晶示例 + +| 高频模式 | 结晶前（LLM 推理） | 结晶后（确定性逻辑） | +|----------|-------------------|---------------------| +| 创建新 Rust crate | LLM 推理目录结构 + Cargo.toml | 脚本：`cargo new --lib` + 模板填充 | +| 添加 IPC command | LLM 生成 handler + 注册代码 | 模板：参数化生成 + 自动注册 | +| 运行测试套件 | LLM 推理测试命令 | 直接执行 `cargo test` | +| 代码审查 | LLM 全量分析 | 规则引擎：lint 规则 + diff 分析 | + +### 4.4 回退机制 + +结晶路径不是"永久替代"——当确定性执行失败或结果异常时，自动回退到 LLM 推理： + +``` +执行结晶路径 + ├── 成功 → 直接返回结果（跳过 LLM） + ├── 失败 → 记录失败 + 回退到 LLM 推理 + └── 连续失败 N 次 → 标记结晶路径为"待审查"，暂停使用 +``` + +--- + +## 5. 演进路线图 + +### Phase 1：地图构建（预计减少 30-40% 无效检索） + +**目标**：三张地图的基础设施就位，AI 操作基于地图而非盲搜。 + +| 工作项 | 依托 | 状态 | +|--------|------|------| +| Working Map 数据层 | projects/tasks/ideas/modules 表 | ✅ 已有 | +| Coding Map 符号索引 | read_symbol 工具 | ✅ 已有 | +| Coding Map 跨工程依赖 | module_dependencies 表 | 🔨 子1-5 在建 | +| Tool Map 注册表 | 68 IPC commands | ✅ 已有 | +| Tool Map 调用历史 | 新增 tool_call_log 表 | ❌ 待建 | +| 地图查询 API | 新增 IPC commands | ❌ 待建 | + +### Phase 2：上下文缓存（预计减少 50-60% 推理量） + +**目标**：Agentic Loop 内置缓存层，跨轮复用已检索上下文。 + +| 工作项 | 说明 | +|--------|------| +| ContextCache Rust 结构 | 内存级缓存 + LRU 淘汰 | +| 文件快照机制 | mtime 监控 + 增量失效 | +| 工具结果缓存 | 签名匹配 + TTL 失效 | +| 缓存命中率指标 | 可观测性面板 | + +### Phase 3：模式结晶器（高频任务去 AI 化） + +**目标**：高频路径自动结晶为确定性逻辑，LLM 退守创造性边界。 + +| 工作项 | 说明 | +|--------|------| +| FrequencyTracker | 工具调用签名记录 + 聚类 | +| PatternAnalyzer | 参数模式分析 + 稳定性评估 | +| Crystallizer 引擎 | 确定性脚本/模板/规则生成 | +| 回退机制 | 结晶失败自动回退 LLM | +| 结晶管理 UI | 查看/审批/禁用结晶路径 | + +### Phase 4：自治进化（长期愿景） + +**目标**：系统自主识别优化机会，提出并验证新的结晶路径。 + +| 工作项 | 说明 | +|--------|------| +| 异常检测 | 识别低效路径（高 token / 低成功率） | +| 结晶提案 | 自动生成结晶候选方案 | +| A/B 验证 | 结晶路径 vs LLM 路径对比 | +| 自治注册 | 验证通过后自动注册新工具 | + +--- + +## 6. 与 DevFlow 现有架构的融合点 + +``` +DevFlow 现有架构 本方案融合点 +┌────────────────────┐ +│ Vue 3 前端 │ ← 结晶管理 UI / 缓存命中率面板 / 地图可视化 +├────────────────────┤ +│ Tauri IPC 层 │ ← 地图查询 API / 缓存管理 IPC / 结晶审批 IPC +├────────────────────┤ +│ Rust 后端 │ +│ ├─ df-storage │ ← tool_call_log 表 / crystallized_patterns 表 +│ ├─ df-project │ ← Working Map + Coding Map 数据源 +│ ├─ df-workflow │ ← 结晶路径作为工作流节点 +│ ├─ df-agent │ ← ContextCache 注入 Agentic Loop +│ └─ df-tools │ ← Tool Map + FrequencyTracker + Crystallizer +├────────────────────┤ +│ SQLite │ ← 新增迁移 V17+（patterns/tool_call_log） +└────────────────────┘ +``` + +### 6.1 新增 Crate 规划 + +| Crate | 职责 | 依赖 | +|-------|------|------| +| `df-context` | ContextCache + 三张地图的内存结构 | df-storage, df-project | +| `df-crystallize` | FrequencyTracker + PatternAnalyzer + Crystallizer | df-tools, df-context | + +### 6.2 新增数据表（V17+ 迁移） + +```sql +-- 工具调用历史 +CREATE TABLE tool_call_log ( + id TEXT PRIMARY KEY, + task_id TEXT, + tool_name TEXT NOT NULL, + parameters TEXT, -- JSON + result_summary TEXT, -- 截断的结果摘要 + success INTEGER NOT NULL, + duration_ms INTEGER, + approved INTEGER, + created_at INTEGER NOT NULL +); + +-- 结晶模式 +CREATE TABLE crystallized_patterns ( + id TEXT PRIMARY KEY, + trigger_condition TEXT NOT NULL, -- JSON: 何时触发 + execution_type TEXT NOT NULL, -- script / template / rule + execution_body TEXT NOT NULL, -- 脚本路径 / 模板内容 / 规则集 + confidence REAL NOT NULL, + status TEXT NOT NULL, -- active / suspended / reviewing + success_count INTEGER DEFAULT 0, + failure_count INTEGER DEFAULT 0, + created_at INTEGER NOT NULL, + updated_at INTEGER NOT NULL +); +``` + +--- + +## 7. 关键设计决策 + +### 7.1 为什么是"三层地图"而非"一张大地图"？ + +- **职责分离**：任务态（Working）、结构态（Coding）、能力态（Tool）的生命周期和更新频率不同 +- **按需加载**：AI 当前操作只需要相关地图层，避免全量加载 +- **独立演进**：每层地图可以独立优化数据结构和索引策略 + +### 7.2 为什么结晶器需要回退机制？ + +- 结晶路径基于历史模式，无法覆盖所有边界情况 +- 回退到 LLM 推理是安全网，确保系统鲁棒性 +- 连续失败自动暂停，避免反复走死路 + +### 7.3 为什么缓存层放在 Rust 后端而非前端？ + +- Rust 后端是 Agentic Loop 的执行体，缓存就近放置延迟最低 +- 避免前后端数据同步的复杂性 +- Rust 的内存管理适合 LRU 缓存场景 + +--- + +## 8. 风险与缓解 + +| 风险 | 影响 | 缓解措施 | +|------|------|----------| +| 地图数据过期 | AI 基于过期信息做决策 | mtime 监控 + 事件驱动增量更新 | +| 结晶路径覆盖不全 | 部分场景回退频繁 | 回退机制 + 逐步扩大结晶覆盖 | +| 缓存内存膨胀 | 内存占用过高 | LRU 淘汰 + TTL 过期 + 容量上限 | +| 结晶脚本安全风险 | 恶意/错误脚本执行 | 审批机制 + 沙箱执行 + 权限限制 | + +--- + +## 9. 总结 + +本方案的核心贡献是将 AI 工作流从"每次全量推理"进化为"地图导航 + 缓存加速 + 高频结晶"的三级加速体系： + +1. **地图层**解决"去哪找"——减少 30-40% 无效检索 +2. **缓存层**解决"别重复"——减少 50-60% 推理量 +3. **结晶器**解决"别想了，直接做"——高频路径去 AI 化 + +最终愿景：**AI 构建认知基础设施，然后将确定性路径交给脚本/规则，自身专注于真正需要创造力的边界问题。这才是 AI 原生的终局——让 AI 做得越来越少，但每一步都精准。** + +--- + +> **下一步行动**： +> 1. 将 Phase 1 中待建项（tool_call_log 表、地图查询 API）拆解为具体任务 +> 2. 在 `df-context` crate 中实现 ContextCache 原型 +> 3. 设计 FrequencyTracker 的数据采集埋点方案 diff --git a/docs/02-架构设计/专项设计/项目知识图谱与任务队列系统-2026-06-26.md b/docs/02-架构设计/专项设计/项目知识图谱与任务队列系统-2026-06-26.md new file mode 100644 index 0000000..6050f9d --- /dev/null +++ b/docs/02-架构设计/专项设计/项目知识图谱与任务队列系统-2026-06-26.md @@ -0,0 +1,832 @@ +# 项目知识图谱与任务队列系统 — 设计 + +> **日期**: 2026-06-26 +> **状态**: 设计阶段（待评审） +> **前提**: AI Working — AI 是系统的主要操作者，人是监督者与决策者 +> **关联**: ARCHITECTURE.md §AI Working 定位体系 / 多工程方案（子1-子5）/ todo.md 灵感模块 + AI 对话目标丢失 + +--- + +## 〇、核心命题 + +**DevFlow 的终局是：AI 拥有完整的项目信息知识图谱，比任何人都了解项目。** + +人在 AI Chat 中描述目标，AI 基于图谱自主分解任务、编排依赖、执行推进、自检完成度。人的角色是决策确认和方向把控，不是填表单和翻列表。 + +本文档定义支撑这一终局所需的数据结构、关联关系和实现路径。 + +--- + +## 一、问题诊断 + +### 1.1 当前缺失 + +| 缺失 | 后果 | +|------|------| +| **无全局工作队列** | 任务散落在各项目下，无法跨项目看"所有待办" | +| **需求无承载体** | Idea 是模糊灵感，Task 是具体执行，中间缺"已确认要做但还没排期"的需求层 | +| **决策无队列** | AI Agentic Loop 中产生的"需要人决策"事项散落在对话流里，错过即丢失 | +| **任务无纵向关联** | 无法表达"一个需求拆出多个子任务"（当前用 `[子N]` 标题前缀硬编码） | +| **任务无横向关联** | 无法表达任务间依赖关系，AI 无法做拓扑排序编排 | +| **需求无结构化规格** | description 是纯文本，AI 无法提取验收标准做自检 | +| **无基础设施记录** | AI 不知道项目用了什么数据库/缓存/MQ | +| **无统一事件流** | 回答"上周做了什么"需跨 6 张表 JOIN | +| **溯源链断裂** | 无法从任务回溯到灵感、从灵感到对话、从对话到决策 | + +### 1.2 核心原则 + +> **每一条数据结构都不是给人填的表单，是给 AI 消费的上下文。** +> +> 前端可视化是最后的投影层，不是数据结构存在的原因。 + +--- + +## 二、数据模型设计 + +> 当前迁移版本 V27（V21=消息拆分 / V22=灵感评估 / V23=嵌入状态 / V24=灵感关联 / V25=评估唯一约束 / V26=任务索引 / V27=审批状态统一）。本设计从 V28 起。 + +### 2.1 Task 表扩展（V28 迁移） + +```sql +-- 队列字段：AI 行为约束信号 +ALTER TABLE tasks ADD COLUMN queue TEXT NOT NULL DEFAULT 'todo'; + -- backlog(需求池) / todo(待办池) / decision(待决策池) / active(执行中) / done(已完成) + +-- 父任务 ID：AI 分解-执行编排结构 +ALTER TABLE tasks ADD COLUMN parent_id TEXT REFERENCES tasks(id); + -- NULL = 叶子任务；非空 = 子任务（限制 1 级，不允许孙任务） + +-- 结构化需求规格：AI 可读写的执行规格 +ALTER TABLE tasks ADD COLUMN content_json TEXT; + -- JSON: { background, acceptance_criteria[], scope[], technical_design, custom_fields } +``` + +#### queue 字段语义 + +| queue 值 | 含义 | AI 行为约束 | +|----------|------|------------| +| `backlog` | 需求池：确认有价值，未排期 | AI **不自主推进**，等待人确认排期 | +| `todo` | 待办池：已排期，待执行 | AI **可自主推进**到 active + in_progress | +| `decision` | 待决策池：需要人拍板 | AI **暂停执行**，请求人类输入 | +| `active` | 执行中：正在推进 | AI **按状态机推进** | +| `done` | 已完成 | 终态 | + +#### queue 与 status 的关系 + +两个正交维度，各管各的： + +``` +queue（管理维度）：backlog → todo → active → done + ↑ + decision（临时池） + +status（执行维度）：todo → in_progress → in_review → testing → done + ↑ + blocked / cancelled +``` + +**一致性约束**（IPC 层校验，不进状态机）： +- queue=done 时 status 必须=done +- queue=backlog 时 status 必须=todo +- queue=active 时 status ∈ {in_progress, in_review, testing} +- status=blocked 时 queue 可为 decision 或 active + +#### parent_id 纵向关联 + +- **限制 1 级嵌套**：parent 有 parent_id 时拒绝再创建子任务 +- **父任务=容器模型**：父任务 status 不走状态机（不能 advance_task），由子任务聚合计算 +- **聚合规则**： + +| 子任务状态 | 父任务推导 status | +|-----------|-----------------| +| 全 todo | todo | +| 任一 in_progress | in_progress | +| 任一 blocked | blocked | +| 全 done/cancelled | done | + +#### content_json 结构 + +```jsonc +{ + "background": "当前 DevFlow 一个项目只能绑一个目录...", // 背景：AI 理解动机 + "acceptance_criteria": [ // 验收标准：AI 自检清单 + "看板三列拖拽", + "跨项目展示任务" + ], + "scope": ["前端 Board.vue", "task_repo", "router"], // 影响范围：AI 操作边界 + "technical_design": "新增 queue 字段 + task_links 表...", // 技术方案：AI 执行路径 + "custom_fields": {} // 扩展字段 +} +``` + +**定位**：不是人填的表单，是 AI 和人协作填充的结构化规格。AI 从对话中提取信息填充，人确认后 AI 执行中用 acceptance_criteria 自检。 + +### 2.2 task_links 表（横向关联） + +```sql +CREATE TABLE task_links ( + id TEXT PRIMARY KEY, + source_id TEXT NOT NULL REFERENCES tasks(id), + target_id TEXT NOT NULL REFERENCES tasks(id), + link_type TEXT NOT NULL, -- depends_on / blocks / relates_to + remark TEXT, -- 可选备注 + created_at TEXT NOT NULL +); +CREATE INDEX idx_task_links_source ON task_links(source_id); +CREATE INDEX idx_task_links_target ON task_links(target_id); +``` + +#### link_type 语义 + +| 类型 | 语义 | AI 用途 | +|------|------|---------| +| `depends_on` | source 依赖 target（target 完成后 source 才能开始） | **拓扑排序调度** | +| `blocks` | source 阻塞 target（source 不完成则 target 无法推进） | 依赖的反向声明 | +| `relates_to` | 弱关联，无执行约束 | 上下文提示 | + +#### 为什么不用 JSON 列（仿 Idea related_ids） + +Idea 的 related_ids JSON 方案是 todo.md 待修的 P1 问题（#8 关联双向同步）。JSON 列的缺陷： +- 无类型区分（不能表达 depends_on vs relates_to） +- 单向（A 关联 B 不意味着 B 知道） +- 无法高效反向查询（"谁依赖了我"需全表扫描 JSON） + +独立表方案：有类型、双向查询、可扩展。 + +#### 边界约束 + +| 约束 | 规则 | +|------|------| +| 循环依赖 | 创建 link 时 BFS 检测环，拒绝 A→B→A | +| 跨项目 | 允许（现实中有跨项目依赖） | +| 软删除 | Task 软删除时保留 link（恢复后关系还在） | +| 执行约束 | AI **应遵守** depends_on（检查依赖全 done 才推进），人**可绕过** | + +### 2.3 project_services 表（基础设施配置） + +```sql +CREATE TABLE project_services ( + id TEXT PRIMARY KEY, + project_id TEXT NOT NULL REFERENCES projects(id), + name TEXT NOT NULL, -- "主数据库" / "缓存" / "消息队列" + service_type TEXT NOT NULL, -- mysql/postgresql/sqlite/redis/mongodb/mq/api/other + endpoint TEXT, -- 连接地址（localhost:3306 / URL） + config_json TEXT, -- 类型相关配置 JSON + environment TEXT NOT NULL DEFAULT 'development', -- development/staging/production + remark TEXT, + created_at TEXT NOT NULL, + updated_at TEXT NOT NULL +); +``` + +**定位**：AI 执行任务时的基础设施上下文。AI 知道"这个项目用了什么数据库、Redis 在哪、有没有 MQ"。 + +**边界**： +- ⚠️ **不存敏感凭证**（密码/密钥）—— 只存连接信息，凭证走环境变量/外部密钥管理 +- 这是元数据，不是运维工具 —— 不做连接池/健康检查 + +### 2.4 project_events 表（统一事件流） + +```sql +CREATE TABLE project_events ( + id TEXT PRIMARY KEY, + project_id TEXT NOT NULL REFERENCES projects(id), + event_type TEXT NOT NULL, + -- idea_created / idea_promoted / idea_evaluated + -- task_created / task_advanced / task_blocked / task_completed + -- workflow_started / workflow_completed + -- knowledge_extracted / knowledge_referenced + -- service_added / service_updated + -- module_bound / module_unbound + -- decision_made + entity_type TEXT, -- idea/project/task/workflow/knowledge/module/service + entity_id TEXT, -- 对应实体 ID + from_state TEXT, -- 状态变化前 + to_state TEXT, -- 状态变化后 + context_json TEXT, -- 事件附加上下文 + source TEXT, -- ai / human / system + conversation_id TEXT, -- 触发事件的对应对话（AI Working 溯源） + created_at TEXT NOT NULL +); +CREATE INDEX idx_project_events_project ON project_events(project_id, created_at); +CREATE INDEX idx_project_events_entity ON project_events(entity_type, entity_id); +``` + +**定位**：AI 精准检索的基础。回答"上周做了什么""这个任务为什么 blocked""这个决策是什么时候做的"。 + +**与 knowledge_events 的关系**：knowledge_events 保持不变（知识库专属，向后兼容）。project_events 是全局事件流，knowledge 事件同时写入两者。 + +**埋点策略**：在现有 IPC 命令（create_task / advance_task / create_project 等）的执行后追加事件写入。不侵入业务逻辑，用 hook/after 模式。 + +### 2.5 Inbox 项目（project_id NOT NULL 兼容） + +需求池的任务可能还没决定归到哪个项目。保持 `project_id NOT NULL` 约束，系统初始化自动创建 Inbox 项目： + +- name = "收件箱" +- status = planning +- 特殊标记不可删除 +- 不参与 Dashboard 统计 + +--- + +## 三、完整图谱视图 + +``` + 💡 Idea + ╱ │ ╲ + evaluations related_ids + │ + promoted_to + │ + ▼ + ┌────── 📂 Project ──────────────────────────────────┐ + │ ╱ │ ╲ │ + │ modules services project_events │ + │ (多工程) (基础设施) (统一事件流) │ + │ │ + │ ╱ │ ╲ │ + │ parent links workflow │ + │ (纵向) (横向) (执行) │ + │ │ │ │ │ + │ ▼ ▼ ▼ │ + │ 🔀 Task ── Task ── ⚙️ Workflow │ + │ │ ╱ ╲ │ + │ content_json nodes branches │ + │ (执行规格) (节点执行) (分支) │ + │ │ + │ queue (管理池: backlog/todo/decision/active/done) │ + │ │ + │ ai_tool_executions ←─ conversation_id ──→ 💬 对话 │ + │ (AI 操作审计) (AI Working 留痕) │ + │ │ + │ knowledges ←── knowledge_events │ + │ (经验沉淀) (知识事件) │ + └────────────────────────────────────────────────────┘ + + 每条线都是 AI 可查询、可推理的关系。 +``` + +--- + +## 四、AI 上下文注入 + +### 4.1 get_project_context 工具 + +AI "比人懂项目"的技术实现 —— 一次调用获得完整心智模型： + +```jsonc +// get_project_context(project_id) → +{ + "project": { + "id", "name", "status", "stack", + "created_from": { "idea_id", "ai_analysis", "score" } + }, + "modules": [ + { "name", "path", "stack", "dependencies": [...] } + ], + "services": [ + { "type", "endpoint", "environment" } + ], + "task_summary": { + "total", "by_status", "by_queue", + "blocked_tasks": [{ "id", "title", "blocked_by" }], + "in_progress": [{ "id", "title", "progress" }] + }, + "task_graph": { + "parent_children": { "parent_id": ["child_id", ...] }, + "dependencies": [{ "from", "to", "type" }] + }, + "recent_events": [/* 最近 20 条事件 */], + "key_decisions": [/* 重要决策记录 */], + "known_pitfalls": [/* knowledges kind=pitfall */] +} +``` + +### 4.2 自动注入策略 + +此上下文可自动注入到每次 AI 对话的 system prompt（类似现有 useAiContext），让 AI 在每轮交互中都带着完整的项目认知。 + +**Token 预算**：完整上下文可能较大，需分级注入： +- **L0（始终注入）**：project 基础信息 + task_summary（~500 token） +- **L1（对话开始注入）**：task_graph + recent_events（~2000 token） +- **L2（按需调用）**：full context（get_project_context 工具） + +--- + +## 五、AI 工具注册表 + +| 工具 | 用途 | 风险等级 | +|------|------|---------| +| `create_task` | 创建任务（支持 queue/parent_id/content_json） | low | +| `list_tasks` | 查询（支持 queue/parent_id/status 筛选） | low（只读） | +| `move_task_queue` | 跨池移动（backlog→todo→active→done） | medium | +| `create_task_link` | 建立任务关联（depends_on/blocks/relates_to） | medium | +| `remove_task_link` | 解除关联 | medium | +| `list_task_links` | 查询任务关联（AI 编排调度用） | low（只读） | +| `get_task_tree` | 获取父子任务树（含子任务进度聚合） | low（只读） | +| `update_content` | 更新 content_json 结构化规格 | medium | +| `get_project_context` | 获取项目完整图谱投影 | low（只读） | +| `get_project_timeline` | 查询项目事件流 | low（只读） | +| `add_project_service` | 添加基础设施配置 | medium | +| `list_project_services` | 查询基础设施 | low（只读） | + +已有工具（扩展参数）：`advance_task`、`update_task`、`list_tasks`。 + +--- + +## 六、AI Working 完整工作流 + +``` +人在 AI Chat 说："我想给 DevFlow 加队列看板功能" + │ + ▼ ① AI 创建需求 + create_task( + title="队列看板功能", + queue="backlog", + content_json={ background, acceptance_criteria, scope, technical_design } + ) + │ + ▼ ② 人确认需求（AI Chat 内审批） + 人修改 content_json → AI 执行 move_task_queue(backlog → todo) + │ + ▼ ③ AI 自主分解 + AI 创建子任务（parent_id 指向父任务）： + child-1: "V28 迁移 + queue 列 + task_links 表" + child-2: "TaskRecord + Repo 扩展" + child-3: "Board.vue 看板视图" + child-4: "AI 工具注册" + │ + ▼ ④ AI 建立依赖 + create_task_link(child-3, depends_on, child-1) + create_task_link(child-3, depends_on, child-2) + create_task_link(child-4, depends_on, child-2) + │ + ▼ ⑤ AI 按拓扑序执行 + 拓扑排序：child-1 → child-2 → child-3 ∥ child-4 + AI 逐个 advance_task(todo → in_progress → ... → done) + 每完成一个检查后继解锁 + 每步操作写入 project_events + │ + ▼ ⑥ AI 自检 + 对照 content_json.acceptance_criteria 逐项检查 + │ + ▼ ⑦ 父任务聚合 + 全部子任务 done → 父任务自动聚合 done + AI 报告人类："队列看板功能已完成" +``` + +--- + +## 七、改动影响评估 + +| 层 | 改动 | 量级 | 风险 | +|---|------|------|------| +| df-storage V28 | queue 列 + parent_id 列 + content_json 列 + task_links 表 + project_services 表 + project_events 表 | 中 | 低（纯加列加表） | +| df-types | TaskRecord 加 3 字段 + TaskLink / ProjectService / ProjectEvent 类型 | 小 | 低 | +| task_repo | insert/update 补字段 + TaskLinkRepo / ProjectServiceRepo / ProjectEventRepo | 中 | 低 | +| task_state_machine | **不改** | 无 | 无 | +| 父任务聚合逻辑 | 新增（子任务 status 变化时重算父 status） | 中 | 中（需定义聚合规则） | +| 事件埋点 | 在现有 IPC 命令后追加事件写入 | 中 | 低（hook 模式，不侵入） | +| IPC | create_task 加可选参数 + link/service/event CRUD + move_task_queue | 中 | 低 | +| AI 工具 | 新增 12 个工具注册 + create_task 参数扩展 | 中 | 低 | +| 前端 Board 看板 | 新增视图 | 中 | 低 | +| 前端 Task 详情 | 结构化渲染 content_json + 子任务列表 + 关联面板 | 中 | 低 | +| 前端项目详情 | 基础设施面板 + 时间线面板 | 中 | 低 | +| Inbox 项目 | 系统初始化创建 | 小 | 低 | + +--- + +## 八、实现路径（按 AI 价值排序） + +### Phase 1 — 任务网络基础（AI 编排的地基） + +| 任务 | 内容 | 依赖 | +|------|------|------| +| V28 迁移 | queue + parent_id + content_json 列 + task_links 表 | 无 | +| TaskRecord 扩展 | df-types + df-storage models 补字段 | V28 | +| TaskLinkRepo | CRUD + 按 source/target 查询 + 循环依赖检测 | V28 | +| task_repo 扩展 | insert/update 补 queue/parent_id/content_json | TaskRecord | +| IPC: create_task 扩展 | 加 queue/parent_id/content_json 可选参数 | task_repo | +| IPC: task_link CRUD | create/remove/list_task_links | TaskLinkRepo | +| IPC: move_task_queue | 跨池移动 + 一致性约束校验 | task_repo | +| 父任务聚合 | 子任务 status 变化时重算父 status | task_repo | +| AI 工具注册 | create_task_link / remove_task_link / list_task_links / get_task_tree / move_task_queue / update_content | IPC | + +### Phase 2 — 统一事件流（AI 精准检索的地基） + +| 任务 | 内容 | 依赖 | +|------|------|------| +| project_events 表 | V28（或 V29 独立迁移） | 无 | +| ProjectEventRepo | CRUD + 按 project_id 查询 + 按 entity 查询 | project_events | +| 事件埋点 | create_task / advance_task / create_project / idea_promote 等追加事件写入 | ProjectEventRepo | +| IPC: get_project_timeline | 事件流查询（支持时间范围/事件类型筛选） | ProjectEventRepo | +| AI 工具注册 | get_project_timeline | IPC | + +### Phase 3 — 项目基础设施（AI 上下文补全） + +| 任务 | 内容 | 依赖 | +|------|------|------| +| project_services 表 | V28（或 V30 独立迁移） | 无 | +| ProjectServiceRepo | CRUD | project_services | +| IPC: service CRUD | add/update/remove/list_project_services | ProjectServiceRepo | +| modules 表 | 复用多工程方案子1 | 无 | +| AI 工具注册 | add_project_service / list_project_services | IPC | + +### Phase 4 — AI 上下文注入（AI 使用知识图谱的接口） + +| 任务 | 内容 | 依赖 | +|------|------|------| +| get_project_context 工具 | 聚合查询返回完整图谱投影 | Phase 1-3 | +| 分级注入策略 | L0 始终注入 / L1 对话开始 / L2 按需调用 | get_project_context | +| useAiContext 扩展 | 对接现有上下文注入机制 | 分级注入策略 | + +### Phase 5 — 前端可视化（人的查看层） + +| 任务 | 内容 | 依赖 | +|------|------|------| +| Board 看板 | 三列拖拽 + 跨项目展示 + 快速录入 | Phase 1 | +| Task 详情增强 | content_json 结构化渲染 + 子任务列表 + 关联面板 | Phase 1 | +| 项目时间线 | 事件流可视化 | Phase 2 | +| 基础设施面板 | 服务列表 + 增删改 | Phase 3 | +| 项目图谱视图 | 全景关系图（可选，优先级最低） | Phase 1-3 | + +--- + +## 九、关键设计决策记录 + +| # | 决策点 | 选择 | 理由 | +|---|--------|------|------| +| D1 | queue vs status 扩展 | 新增 queue 字段 | 正交维度，状态机不动，职责分离 | +| D2 | parent_id 嵌套深度 | 限制 1 级 | 避免递归复杂度和进度幻觉 | +| D3 | 父任务语义 | 容器模型，status 聚合计算 | 父任务不执行工作流 | +| D4 | 横向关联 | 独立 task_links 表 | 有类型、可双向查询，避免 JSON 方案已知缺陷 | +| D5 | 需求结构化 | content_json + description 并存 | 结构化渲染 + 自由描述互补 | +| D6 | project_id 约束 | 保持 NOT NULL + Inbox 项目 | 最小改动，GTD 收件箱模式 | +| D7 | depends_on 执行约束 | AI 应遵守，人可绕过 | 过强约束会被绕过 | +| D8 | 循环依赖检测 | 创建 link 时 BFS 检测 | task_links 数据量小，检测成本低 | +| D9 | 事件流与 knowledge_events | 并存不替代 | knowledge_events 向后兼容 | +| D10 | 敏感凭证 | 不存入 project_services | 安全边界，凭证走环境变量 | +| D11 | 数据结构定位 | 为 AI 消费设计，非为人填表单 | AI Working 核心原则 | +| D12 | 实现优先级 | 按 AI 价值排序非按 UI 需求 | AI Working 核心原则 | + +--- + +## 十、任务全景视图设计（Mission Control） + +> **核心目标**：一个页面，看清全部项目的任务推进过程、状态分布、依赖关系、时间维度、卡点阻塞。 + +### 10.1 信息架构 + +用户要的是五个维度的清晰呈现，对应五种视图模式： + +| 维度 | 视图 | 核心问题 | 数据来源 | +|------|------|---------|---------| +| **推进过程** | 看板视图 | 任务在 backlog→todo→active→done 各池的分布和流动 | tasks.queue | +| **状态分布** | 热力矩阵 | 每个项目 × 每个状态的交叉分布，一眼看全局 | tasks GROUP BY project, status | +| **依赖关系** | DAG 图 | 任务间依赖链、拓扑序、关键路径 | task_links + parent_id | +| **时间维度** | 时间线 | 任务的创建/推进/完成时间线，最近活跃度 | tasks.created_at/updated_at + project_events | +| **卡点阻塞** | 阻塞面板 | 哪些任务 blocked、为什么 blocked、阻塞了谁 | tasks.status=blocked + task_links(blocks) | + +### 10.2 路由 & 页面结构 + +``` +/mission-control → MissionControl.vue（壳页面，顶部 Tab 切换五种视图） + ├── Tab 1: 看板（KanbanView.vue） — 默认视图 + ├── Tab 2: 矩阵（MatrixView.vue） + ├── Tab 3: 依赖图（DagView.vue） + ├── Tab 4: 时间线（TimelineView.vue） + ├── Tab 5: 阻塞（BlockedView.vue） + └── 公共侧栏: 筛选器（项目/优先级/负责人） +``` + +侧栏新增导航项：**🚀 任务全景**（Mission Control），位于"任务"和"知识库"之间。 + +### 10.3 各视图详细设计 + +#### 10.3.1 看板视图（KanbanView）— 推进过程 + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ 💡 需求池(3) │ 📋 待办(5) │ 🔨 执行中(2) │ ✅ 完成(12) │ +│ │ │ │ │ +│ ┌───────────────┐ │ ┌────────────────┐ │ ┌──────────────┐ │ ┌──────────┐ │ +│ │ 队列看板功能 │ │ │ V28 迁移+表结构 │ │ │ TaskRecord扩 │ │ │ 软删除 │ │ +│ │ DevFlow · P1 │ │ │ DevFlow · P0 │ │ │ DevFlow·P1 │ │ │ B-13 │ │ +│ │ 🔗 4 子任务 │ │ │ 🔗 → Board.vue │ │ │ ▓▓▓▓▓░░ 70% │ │ │ 06-16 │ │ +│ └───────────────┘ │ └────────────────┘ │ └──────────────┘ │ └──────────┘ │ +│ ┌───────────────┐ │ ┌────────────────┐ │ │ +│ │ 插件机制 │ │ │ DagView 依赖图 │ │ │ +│ │ DevFlow · P2 │ │ │ DevFlow · P1 │ │ │ +│ └───────────────┘ │ └────────────────┘ │ │ +│ │ │ │ +│ ⚠️ 待决策(1) │ │ 🚫 阻塞(1) │ +│ ┌───────────────┐ │ │ ┌──────────────┐ │ +│ │ API 协议选型 │ │ │ │ IPC 层封装 │ │ +│ │ ❓需确认 │ │ │ │ 被 V28 阻塞 │ │ +│ └───────────────┘ │ │ └──────────────┘ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +**列定义**（对应 queue 值）： + +| 列 | queue | 子列 | 说明 | +|----|-------|------|------| +| 需求池 | backlog | — | 确认有价值，未排期 | +| 待决策 | decision | — | 需要人拍板，**红色高亮** | +| 待办 | todo | — | 已排期，可执行 | +| 执行中 | active | 正常 | 按状态机推进中 | +| 执行中 | active | 阻塞 | status=blocked，**红色边框 + 阻塞原因** | +| 完成 | done | — | 终态 | + +**卡片信息密度**： +``` +┌──────────────────────────┐ +│ 任务标题（1 行截断） │ ← title +│ 项目名 · 优先级标签 │ ← project.name + priority badge +│ 🔗 3 子任务 / 🔗→ 依赖任务 │ ← parent_id 子任务计数 / depends_on 链 +│ ▓▓▓▓░░ 60% │ ← 子任务完成率（父任务）/ 状态机进度（叶子） +│ 🚫 被 xxx 阻塞 │ ← blocked 时显示阻塞源（仅红色卡片） +│ 06-26 │ ← updated_at（相对时间） +└──────────────────────────┘ +``` + +**交互**： +- 点击卡片 → 跳转 TaskDetail +- 卡片左滑/右滑 → 快捷 move_task_queue（需确认） +- 列头显示计数 + 拖拽提示 +- 顶部全局筛选：项目（多选）/ 优先级 / 负责人 + +**跨项目展示**：卡片左上角的项目色条（3px）区分项目归属，悬停显示项目全名。 + +#### 10.3.2 热力矩阵（MatrixView）— 状态分布 + +``` + todo in_progress in_review testing blocked done 总计 +DevFlow 3 2 1 0 2 12 20 +u-ask 1 0 0 0 0 5 6 +u-img 0 1 0 0 0 3 4 +workpod 2 0 0 0 0 1 3 +───────────────────────────────────────────────────────────────────────── +总计 6 3 1 0 2 21 33 +``` + +**视觉**：每个格子是一个色块，数字越大颜色越深（热力图）。blocked 列**红色系**，done 列**绿色系**，其他列**蓝色系**。 + +**交互**： +- 点击格子 → 展开该项目该状态的任务列表（inline accordion 或侧抽屉） +- 行/列可排序（按总计降序） +- 顶部摘要条：`33 任务 · 2 阻塞 · 3 执行中 · 完成率 64%` + +**AI 消费价值**：get_project_context 的 task_summary.by_status / by_queue 就是这个矩阵的数据源。AI 读到 `blocked: 2` 就知道要主动排查阻塞。 + +#### 10.3.3 依赖图（DagView）— 依赖关系 + +``` + ┌──────────┐ + │ V28 迁移 │ ← 无依赖，可立即执行 + │ (done) │ + └────┬─────┘ + │ depends_on + ▼ + ┌──────────┐ + │ TaskRepo │ + │ 扩展(todo) │ + └──┬────┬──┘ + │ │ + ▼ ▼ + ┌─────────┐ ┌──────────┐ + │ IPC 封装 │ │ AI 工具 │ + │(blocked)│ │ 注册(todo) │ ← 被 V28 阻塞（虚线 blocks） + └────┬────┘ └──────────┘ + │ + ▼ + ┌─────────┐ + │Board.vue │ + │ (todo) │ + └─────────┘ +``` + +**节点视觉**： +- 状态颜色：todo=灰 / in_progress=蓝 / in_review=黄 / testing=橙 / done=绿 / blocked=红 +- 父任务=大圆角矩形，子任务=小圆角矩形，用虚线框分组 +- depends_on=实线箭头 → / blocks=红色虚线箭头 ⇢ / relates_to=灰色点线 ⋯ + +**布局算法**： +- 拓扑排序分层（Sugiyama / 简化版：按依赖深度分层） +- 同层节点水平排列 +- 父子关系用虚线框圈住 + +**交互**： +- 点击节点 → 高亮该节点的所有依赖链（上游+下游路径加粗） +- 双击节点 → 跳转 TaskDetail +- 悬停节点 → 显示 tooltip（标题/状态/阻塞原因） +- 右键节点 → 快捷操作（推进/解除阻塞/编辑依赖） +- 顶部工具栏：仅看阻塞链 / 仅看关键路径 / 按项目着色 + +**关键路径标注**：拓扑排序后，从入度=0 的节点到出度=0 的节点的最长路径，用粗线标注。 + +**数据量控制**： +- 默认只渲染 active + todo + blocked 的任务（隐藏 done/cancelled） +- 超过 30 个节点时提示"节点过多，请按项目筛选" +- 支持按项目过滤 + +#### 10.3.4 时间线（TimelineView）— 时间维度 + +两种模式： + +**模式 A：甘特图（横向时间轴）** + +``` + 06-24 06-25 06-26 06-27 06-28 06-29 06-30 +V28迁移 ████████←done +TaskRepo ████████←in_progress 70% +IPC封装 ██████←blocked(等V28) +Board.vue ░░░░░░←todo(未开始) +AI工具注册 ░░░░░░←todo +``` + +- 横轴=日期（created_at → 预估完成 / 实际 updated_at） +- 每行一个任务，条形颜色=状态色 +- blocked 段叠加红色斜纹 +- 父任务行展开显示子任务 + +**模式 B：事件流（纵向时间轴）** + +``` + 今天 06-26 + │ + ├─ 14:30 ✅ V28 迁移完成 DevFlow + ├─ 13:15 🔨 TaskRepo 扩展开始 DevFlow + ├─ 11:00 🚫 IPC 封装被阻塞 DevFlow ← 红色高亮 + │ 原因：等待 V28 迁移完成 + ├─ 09:45 💡 创建需求"队列看板" DevFlow + │ + 昨天 06-25 + │ + ├─ 22:10 ✅ B-27 审批状态统一 DevFlow + ├─ 18:30 🔨 V28 迁移开始 DevFlow + ... +``` + +- 来源：project_events 表 +- 事件类型图标 + 颜色区分 +- blocked/decision 事件**红色高亮** +- 按天分组，可折叠 +- 支持按项目/事件类型筛选 +- 无限滚动加载 + +**切换**：顶部 Toggle 切换甘特/事件流两种模式。 + +#### 10.3.5 阻塞面板（BlockedView）— 卡点 + +**这是最重要的视图** —— 回答"哪里卡住了、为什么、阻塞了谁"。 + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ 🚫 阻塞任务 (2) │ +├─────────────────────────────────────────────────────────────────────┤ +│ │ +│ 🔴 IPC 层封装 DevFlow · P1 │ +│ 状态: blocked ← 3 天 │ +│ 阻塞原因: 等待 V28 迁移完成 │ +│ 阻塞了谁: ↓ │ +│ └─ Board.vue 看板视图 (todo，无法开始) │ +│ └─ AI 工具注册 (todo，无法开始) │ +│ 连锁影响: 2 个下游任务被阻塞 │ +│ [解除阻塞] [查看详情] │ +│ │ +│ 🔴 API 协议选型 u-ask · P0 │ +│ 状态: blocked ← 7 天 ⚠️ 长时间阻塞 │ +│ 阻塞原因: 需要确认 REST vs GraphQL │ +│ 阻塞了谁: ↓ │ +│ └─ 后端 API 重构 (todo) │ +│ └─ 前端适配 (todo) │ +│ 连锁影响: 3 个下游任务被阻塞 │ +│ [解除阻塞] [查看详情] │ +│ │ +├─────────────────────────────────────────────────────────────────────┤ +│ ⚠️ 待决策 (1) │ +├─────────────────────────────────────────────────────────────────────┤ +│ │ +│ ❓ 缓存策略选型 workpod · P2 │ +│ 队列: decision ← 2 天 │ +│ 决策内容: Redis vs 本地缓存 │ +│ 阻塞了谁: ↓ │ +│ └─ 缓存模块实现 (backlog) │ +│ [做出决策] [查看详情] │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +**数据来源**： +- `tasks WHERE status = 'blocked'` → 阻塞任务列表 +- `task_links WHERE target_id = :blocked_task_id AND link_type = 'depends_on'` → 查谁被它阻塞 +- `tasks WHERE queue = 'decision'` → 待决策列表 +- BFS 遍历依赖链计算"连锁影响数"（下游被间接阻塞的任务总数） + +**关键视觉**： +- 阻塞时间 > 3 天 → 黄色警告标记 +- 阻塞时间 > 7 天 → 红色闪烁标记 + 置顶 +- 连锁影响 > 3 → 加粗影响数 +- 每个阻塞项可展开"阻塞链"树形图 + +**排序策略**： +1. 连锁影响数降序（阻塞越多越优先处理） +2. 阻塞时间降序（越久越紧急） +3. 优先级降序 + +### 10.4 公共筛选器（侧栏） + +所有视图共享的筛选维度： + +``` +┌──────────────────────┐ +│ 🔍 筛选 │ +│ │ +│ 项目 │ +│ ☑ DevFlow │ +│ ☑ u-ask │ +│ ☐ u-img │ +│ ☑ workpod │ +│ │ +│ 优先级 │ +│ ☑ P0 紧急 │ +│ ☑ P1 高 │ +│ ☑ P2 中 │ +│ ☐ P3 低 │ +│ │ +│ 负责人 │ +│ [全部 ▾] │ +│ │ +│ 隐藏已完成 │ +│ [开关] │ +│ │ +│ 仅看阻塞链 │ +│ [开关] │ +└──────────────────────┘ +``` + +### 10.5 后端 API 设计 + +| IPC Command | 用途 | 参数 | +|-------------|------|------| +| `get_mission_kanban` | 看板视图数据（按 queue 分组） | project_ids?, priority? | +| `get_mission_matrix` | 热力矩阵数据（project × status 交叉统计） | project_ids? | +| `get_mission_dag` | DAG 依赖图数据（节点+边） | project_ids?, include_done? | +| `get_mission_timeline` | 时间线数据（事件流 or 甘特图） | project_ids?, date_from?, date_to?, mode | +| `get_mission_blocked` | 阻塞面板数据（含连锁影响计算） | project_ids? | + +**性能考虑**： +- 任务量级 ~50-200（桌面应用单用户），全量查询无压力 +- DAG 连锁影响用 Rust BFS 遍历，不走 SQL 递归 +- 时间线分页加载（每次 50 条事件） +- 矩阵统计用 SQL `GROUP BY project_id, status` 一次查询 + +### 10.6 AI 消费场景 + +这些视图的数据结构同时也是 AI 的上下文： + +| AI 场景 | 数据来源 | 对应视图 | +|---------|---------|---------| +| "项目进展如何？" | get_mission_matrix | 热力矩阵 | +| "有什么卡住了？" | get_mission_blocked | 阻塞面板 | +| "下一步做什么？" | get_mission_dag（拓扑排序入度=0 的 todo 任务） | 依赖图 | +| "上周做了什么？" | get_mission_timeline（事件流） | 时间线 | +| "这个需求拆得对不对？" | get_task_tree + get_mission_dag | 看板 + 依赖图 | + +**AI 自动排查阻塞**：当 get_project_context 返回 blocked_tasks 非空时，AI 可主动在对话中提示"检测到 2 个任务被阻塞，是否需要排查？"并附带阻塞链摘要。 + +### 10.7 实现优先级 + +| 优先级 | 视图 | 理由 | +|--------|------|------| +| **P0** | 阻塞面板 | 最高价值：一眼看卡点，当前完全缺失 | +| **P0** | 看板视图 | 核心交互：queue 流动可视化 | +| **P1** | 热力矩阵 | 全局分布：跨项目状态一览 | +| **P1** | 时间线（事件流模式） | 追溯能力：做了什么/何时做的 | +| **P2** | 依赖图（DAG） | 编排可视化：需要 task_links 先落地 | +| **P2** | 时间线（甘特图模式） | 锦上添花：需要预估完成时间字段 | + +**P0 可独立先做**：阻塞面板 + 看板视图只需要 tasks 表的 queue/status 字段（Phase 1），不依赖 task_links（依赖图才需要）。 + +--- + +## 十一、边界与风险 + +### 10.1 已识别风险 + +| 风险 | 影响 | 缓解 | +|------|------|------| +| queue 与 status 一致性 | 两个字段可能不同步 | IPC 层强制校验约束规则 | +| 父任务聚合性能 | 子任务变化触发父重算 | 项目内任务量小（~50），实时计算无压力 | +| 事件流写入失败 | 埋点失败影响事件完整性 | 事件写入失败不阻断主操作（best-effort） | +| get_project_context 体积 | 大项目上下文可能超 token 预算 | 分级注入 L0/L1/L2 | +| task_links 循环依赖 | 死锁 | BFS 检测 + 拒绝创建 | + +### 10.2 不做的事 + +- ❌ 不做无限嵌套任务树（限制 1 级） +- ❌ 不做凭证存储/管理（安全边界外） +- ❌ 不做事件流回填（历史数据不补事件，从上线时间点开始记录） +- ❌ 不做前端拖拽排序的 sort_order（queue 内排序按 priority + created_at） +- ❌ 不做看板的 WIP 限制（列宽限制，过度设计）