lanrtop 0cdaa3678c feat: add Blueprint feature to ProjectCard and commands

- Introduced BlueprintModal in ProjectCard for project blueprint visualization.
- Added state management for displaying the BlueprintModal.
- Implemented Blueprint-related interfaces and functions in commands.ts for handling blueprint data.

2026-04-02 19:12:53 +09:00

5.2 KiB

Raw Blame History

蓝图更新规则

本文件定义了 .blueprint/ 目录的维护规范，供 Claude 在对话中遵循。

目录结构

.blueprint/
├── manifest.yaml        ← 模块列表、关系、布局坐标
├── CONVENTIONS.md       ← 本文件（Claude 行为规则）
└── modules/
    └── <module-id>.md   ← 每个模块的详情 + 任务卡

何时更新蓝图

事件	操作
用户确认了新需求	在 manifest.yaml 新增模块，创建 modules/.md
完成了功能实现	更新模块 status → done，标记任务卡 ✅
拆分了大需求为子任务	在 modules/.md 中添加任务卡
调整了架构方向	更新 edges 关系，可能调整 area
放弃了某个方向	删除对应模块和文件，或标记 status: abandoned

模块状态定义

状态	含义	色标
`done`	已实现并验证	🟢 绿色
`in_progress`	正在开发	🔵 蓝色
`planned`	已规划，需求明确	🟡 黄色
`concept`	构思中，信息不完整	⚪ 灰色

任务卡格式

modules/.md 中的每个二级标题（###）是一张任务卡：

### 📋 任务标题
- status: todo
- complexity: M
- files: src/path/to/file.tsx, src-tauri/src/commands/xxx.rs
- depends: other-module-id
- acceptance: 简要描述完成标准

详细说明（可选）。

状态前缀

前缀	status	含义
✅	done	已完成
🔵	in_progress	进行中
📋	todo	可派发（信息充足）
💭	concept	构思中

可派发标准（📋）

任务卡同时满足以下条件时标记为 📋：

status 为 todo
有明确的 files（涉及哪些文件）
有明确的 acceptance（验收标准）
complexity 为 S 或 M

不满足条件的 todo 任务保持无前缀，说明还需补充信息。

manifest.yaml 规范

模块字段

- id: kebab-case-id        # 唯一标识，同时是 modules/ 下的文件名
  name: 显示名称
  area: frontend            # 所属领域 ID
  status: done              # done / in_progress / planned / concept
  progress: 100             # 0~100，done 自动视为 100
  position: [x, y]          # React Flow 画布坐标（可选）

边字段

- from: module-a
  to: module-b
  type: dependency          # dependency（实线）/ related（虚线）

领域字段

- id: frontend
  name: 前端
  color: "#3B82F6"          # 节点边框/分组背景色

进度计算

模块的 progress 由其任务卡的完成比例推算：

无任务卡的模块：手动设置 progress
有任务卡的模块：完成数 / 总数 × 100（取整）

决策记录格式

模块文件中可添加 ## 决策记录 段落，记录架构决策的 WHY：

## 决策记录

- 选择阿里云 OSS 而非 GitHub Releases 作为更新源，因为国内用户访问 GitHub 不稳定
- 使用 document-driven 蓝图而非数据库存储，因为 Claude 天然支持文件读写且可版本控制

桌面 App 会以琥珀色卡片展示在模块详情面板中。

飞轮工作流

Claude 在每次对话中应遵循以下流程：

阶段 1：进入对话 — 读取蓝图

读取 .blueprint/manifest.yaml → 了解项目全景和当前状态

识别哪些模块 in_progress，哪些有可派发任务
用简短话语告诉用户当前项目进展（如 "18/22 模块已完成，2 个进行中"）

阶段 2：讨论需求 — 同步更新蓝图

用户说的	Claude 应做的
"我想加个 XX 功能"	确认需求后：manifest 加模块 (status: concept)，创建 modules/.md
"XX 功能需要 A、B、C 三步"	在模块文件中拆分为 3 张任务卡
"这个方案确定了"	模块 status → planned，补充任务卡的 files/acceptance
"开始做 XX"	模块 status → in_progress
"为什么选这个方案"	记录到模块的 `## 决策记录`

阶段 3：实现功能 — 标记完成

完成代码 → 更新任务卡前缀为 ✅ → status: done
所有任务卡完成 → 模块 status: done
更新 manifest.yaml 的 updated 日期

阶段 4：回顾 — 用户在桌面 App 查看

用户打开蓝图可视化：

看到全景进度
在「下一步」面板查看可派发任务
点击「复制派发」→ 粘贴给新 Claude 会话

飞轮的反馈信号

Claude 应关注这些信号来决定是否更新蓝图：

用户说"这个做完了" → 标记 done
用户说"这个不做了" → 标记 abandoned 或删除
用户说"这个要拆一下" → 拆分任务卡
用户说"记住这个决策" → 写入决策记录
用户没提蓝图但在讨论功能 → 主动提议更新蓝图

注意事项

不要删除已完成的任务卡，它们是项目历史的一部分
模块 id 一旦确定尽量不要修改（会影响 edges 引用）
每次更新后修改 manifest.yaml 顶部的 updated 日期
progress 由桌面 App 自动从任务卡完成比例计算，不需要手动维护
当用户的操作隐含了蓝图变更但没有明说时，Claude 应主动提议更新（而非沉默）

5.2 KiB Raw Blame History Unescape Escape