charieswei
/
vibe-coding-cn
mirror of https://github.com/tukuaiai/vibe-coding-cn.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

feat: add canvas-dev skill with full references and prompts

This commit is contained in:
tukuaiai 2026-01-01 07:22:44 +08:00
parent 76e7a9a0fb
commit bfa2de8177
6 changed files with 830 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
i18n/zh/skills/01-AI工具/canvas-dev/README.md Normal file
View File

@ -0,0 +1,39 @@
# Canvas-Dev Skill
Canvas白板驱动开发技能，用于 AI 辅助架构设计与代码生成。
## 概述
此技能实现「图形是第一公民，代码是白板的序列化形式」的开发范式。
## 核心能力
1. **架构分析** - 从代码自动生成 Obsidian Canvas 白板
2. **白板驱动编码** - 根据白板生成/修改代码
3. **一致性检查** - 校验白板与代码同步状态
## 文件结构
```
canvas-dev/
├── SKILL.md # 技能入口（触发条件、模式、示例）
├── references/
│ ├── index.md # 导航索引
│ ├── canvas-json-spec.md # Canvas JSON 规范
│ ├── workflow-guide.md # 工作流指南
│ └── prompts.md # 提示词集合
├── scripts/ # 自动化脚本（预留）
└── assets/ # 模板资源（预留）
```
## 快速开始
1. 阅读 `SKILL.md` 了解触发条件和使用模式
2. 参考 `references/workflow-guide.md` 了解完整工作流
3. 使用 `references/prompts.md` 中的提示词
## 相关资源
- [Canvas白板驱动开发详解](../../documents/02-方法论/图形化AI协作-Canvas白板驱动开发.md)
- [Canvas开发工作流](../../workflow/canvas-dev/)
- [元技能: claude-skills](../00-元技能/claude-skills/SKILL.md)

246
i18n/zh/skills/01-AI工具/canvas-dev/SKILL.md Normal file
View File

@ -0,0 +1,246 @@
---
name: canvas-dev
description: "Canvas白板驱动开发技能：从代码生成架构白板、根据白板生成代码、校验白板与代码一致性。使用场景：接手新项目快速理解架构、新功能开发先画白板再编码、架构重构可视化、团队协作共享架构图。"
---
# canvas-dev Skill
Canvas白板驱动开发：图形是第一公民，代码是白板的序列化形式。通过 Obsidian Canvas 实现人类与AI的共享工作区。
## When to Use This Skill
触发条件（满足任一即可）：
- 需要快速理解现有项目架构（接手遗留代码）
- 新功能开发前需要设计架构（先画后写）
- 架构重构需要可视化依赖关系
- Code Review 需要全局视角
- 团队协作需要共享架构图
- 需要生成 Obsidian Canvas 格式的 `.canvas` 文件
## Not For / Boundaries
此技能不适用于：
- 纯文本文档生成（使用 Markdown 即可）
- 流程图/时序图（使用 Mermaid）
- 数据库 ER 图（使用专用工具）
- 不需要双向同步的静态架构图
必要输入（缺失时需询问）：
1. 项目代码路径或代码片段
2. 分析粒度（file/class/service）
3. 技术栈（用于生成代码时）
## Quick Reference
### Canvas JSON 基础结构
```json
{
"nodes": [
{"id": "n1", "type": "text", "x": 0, "y": 0, "width": 200, "height": 100, "text": "# ModuleName\n- method1()\n- method2()"}
],
"edges": [
{"id": "e1", "fromNode": "n1", "toNode": "n2", "fromSide": "right", "toSide": "left", "label": "调用"}
]
}
```
### 节点类型
| type | 用途 | 示例 |
|:---|:---|:---|
| `text` | 模块/类/文件 | `{"type": "text", "text": "# UserService"}` |
| `group` | 功能分组 | `{"type": "group", "label": "API层"}` |
| `file` | 链接文件 | `{"type": "file", "file": "src/user.py"}` |
### 连线方向
| fromSide/toSide | 含义 |
|:---|:---|
| `right` → `left` | 水平调用（推荐） |
| `bottom` → `top` | 垂直依赖 |
| `top` → `bottom` | 继承关系 |
### 常用 label 标注
- `调用` - 函数/方法调用
- `依赖` - import/require
- `继承` - extends/implements
- `数据流` - 参数传递
- `FK: field` - 外键关系
### 分层布局约定
```
x轴: -400 (前端) → 0 (API) → 400 (服务) → 800 (数据)
y轴: 每层内按功能分组，间距 120-150
```
### 颜色编码（Obsidian Canvas）
| color | 含义 |
|:---|:---|
| `1` | 红色 - 缓存/热点 |
| `2` | 橙色 - 消息队列 |
| `3` | 黄色 - 上游依赖 |
| `4` | 绿色 - 数据库 |
| `5` | 蓝色 - 搜索/外部服务 |
| `6` | 紫色 - 注释/设计决策 |
## Rules & Constraints
### MUST（必须遵守）
- 节点 `id` 必须唯一且有意义（如 `svc-user`，非 `node1`）
- 连线必须反映真实的代码依赖关系
- 生成的 `.canvas` 文件必须是合法 JSON
- 白板修改后必须同步更新相关代码
### SHOULD（强烈建议）
- 按功能域分组（API层/服务层/数据层）
- 节点 text 使用 Markdown 格式（`# 标题` + 列表）
- 保持布局整洁（对齐、等间距）
- 为复杂依赖添加 label 说明
### NEVER（禁止）
- 不要生成与代码不一致的白板
- 不要在白板中包含敏感信息（密钥/密码）
- 不要创建循环依赖的连线（除非代码确实如此）
## Examples
### Example 1: 从代码生成架构白板
**Input:**
```
项目路径: /home/user/my-api
技术栈: Python FastAPI
粒度: file
```
**Steps:**
1. 扫描项目目录，识别 `.py` 文件
2. 分析 `import` 语句提取依赖关系
3. 识别 FastAPI 路由、数据库模型、外部调用
4. 按三层架构布局节点
5. 生成 `.canvas` JSON
**Expected Output:**
```json
{
"nodes": [
{"id": "api-user", "type": "text", "x": -200, "y": 0, "width": 200, "height": 100, "text": "# user_router.py\n- POST /users\n- GET /users/{id}"},
{"id": "svc-user", "type": "text", "x": 100, "y": 0, "width": 200, "height": 100, "text": "# user_service.py\n- create_user()\n- get_user()"},
{"id": "model-user", "type": "text", "x": 400, "y": 0, "width": 200, "height": 100, "text": "# user_model.py\n- User\n- id, name, email"}
],
"edges": [
{"id": "e1", "fromNode": "api-user", "toNode": "svc-user", "fromSide": "right", "toSide": "left", "label": "调用"},
{"id": "e2", "fromNode": "svc-user", "toNode": "model-user", "fromSide": "right", "toSide": "left", "label": "操作"}
]
}
```
### Example 2: 根据白板生成代码
**Input:**
```
Canvas JSON: (包含 UserAPI → UserService → UserModel 的白板)
技术栈: Python FastAPI + SQLAlchemy
目标目录: /home/user/new-project
```
**Steps:**
1. 解析节点 → 生成文件/类
2. 解析连线 → 生成 import 和调用
3. 按技术栈最佳实践填充代码
**Expected Output:**
```python
# user_router.py
from fastapi import APIRouter
from .user_service import UserService
router = APIRouter()
service = UserService()
@router.post("/users")
def create_user(data: dict):
return service.create_user(data)
```
### Example 3: 白板与代码一致性检查
**Input:**
```
Canvas: architecture.canvas
项目: /home/user/my-project
```
**Steps:**
1. 提取白板节点列表
2. 扫描项目文件列表
3. 对比差异
**Expected Output:**
```
🔴 严重不一致:
- 白板缺失: payment_service.py (代码存在但白板未记录)
- 错误连线: UserService → Database (代码中无直接调用)
🟢 覆盖率: 85%
📋 修复建议:
1. 在白板添加 payment_service 节点
2. 删除 UserService → Database 连线，改为 UserService → UserRepository → Database
```
## FAQ
**Q: 为什么选择 Obsidian Canvas 而不是其他工具？**
- A: Obsidian Canvas 是免费开源的，`.canvas` 文件是纯 JSON 格式，AI 可以直接读写，支持双向同步。
**Q: 白板粒度选 file 还是 class？**
- A: 小项目（<20文件）选 file，大项目选 class 或 service。关键是保持白板可读性。
**Q: 如何处理循环依赖？**
- A: 如果代码确实存在循环依赖，在白板中如实标注，并添加注释节点说明这是技术债务。
## Troubleshooting
| 症状 | 可能原因 | 解决方案 |
|:---|:---|:---|
| Obsidian 无法打开 .canvas | JSON 格式错误 | 用 `jq .` 验证 JSON |
| 节点重叠 | x/y 坐标冲突 | 调整布局，保持 200+ 间距 |
| 连线不显示 | fromNode/toNode id 错误 | 检查节点 id 是否匹配 |
| AI 生成代码与白板不符 | 白板描述不够具体 | 在节点 text 中添加更多细节 |
## References
- `references/index.md` - 导航索引
- `references/canvas-json-spec.md` - Canvas JSON 完整规范
- `references/workflow-guide.md` - 完整工作流指南
- `references/prompts.md` - 提示词集合
外部资源：
- [Obsidian Canvas 官方文档](https://obsidian.md/canvas)
- [Canvas白板驱动开发详解](../../documents/02-方法论/图形化AI协作-Canvas白板驱动开发.md)
- [Canvas开发工作流](../../workflow/canvas-dev/README.md)
## Maintenance
- Sources: Obsidian Canvas 官方文档 + 本地工作流实践
- Last updated: 2026-01-01
- Known limits: 仅支持 Obsidian Canvas 格式，不支持其他白板工具
## Quality Gate
发布前检查：
1. ✅ `description` 包含具体触发关键词
2. ✅ "When to Use" 列出可判定的触发条件
3. ✅ "Not For / Boundaries" 明确边界
4. ✅ Quick Reference <= 20 个模式
5. ✅ >= 3 个可复现的示例
6. ✅ 长内容放入 `references/`
7. ✅ 无虚构内容，不确定处标注验证路径

205
i18n/zh/skills/01-AI工具/canvas-dev/references/canvas-json-spec.md Normal file
View File

@ -0,0 +1,205 @@
# Obsidian Canvas JSON 规范
## 文件格式
Canvas 文件是 `.canvas` 扩展名的 JSON 文件。
## 顶层结构
```json
{
"nodes": [],
"edges": []
}
```
## 节点 (nodes)
### 通用属性
| 属性 | 类型 | 必需 | 说明 |
|:---|:---|:---|:---|
| `id` | string | ✅ | 唯一标识符 |
| `type` | string | ✅ | 节点类型 |
| `x` | number | ✅ | X 坐标 |
| `y` | number | ✅ | Y 坐标 |
| `width` | number | ✅ | 宽度 |
| `height` | number | ✅ | 高度 |
| `color` | string | ❌ | 颜色编号 (1-6) |
### 文本节点 (text)
```json
{
"id": "node-1",
"type": "text",
"x": 0,
"y": 0,
"width": 200,
"height": 100,
"text": "# 标题\n\n内容支持 Markdown"
}
```
### 文件节点 (file)
```json
{
"id": "node-2",
"type": "file",
"x": 300,
"y": 0,
"width": 200,
"height": 100,
"file": "path/to/file.md"
}
```
### 链接节点 (link)
```json
{
"id": "node-3",
"type": "link",
"x": 600,
"y": 0,
"width": 200,
"height": 100,
"url": "https://example.com"
}
```
### 分组节点 (group)
```json
{
"id": "group-1",
"type": "group",
"x": -50,
"y": -50,
"width": 500,
"height": 300,
"label": "分组名称"
}
```
## 连线 (edges)
### 属性
| 属性 | 类型 | 必需 | 说明 |
|:---|:---|:---|:---|
| `id` | string | ✅ | 唯一标识符 |
| `fromNode` | string | ✅ | 起始节点 id |
| `toNode` | string | ✅ | 目标节点 id |
| `fromSide` | string | ❌ | 起始边 (top/right/bottom/left) |
| `toSide` | string | ❌ | 目标边 (top/right/bottom/left) |
| `fromEnd` | string | ❌ | 起始端样式 (none/arrow) |
| `toEnd` | string | ❌ | 目标端样式 (none/arrow) |
| `label` | string | ❌ | 连线标签 |
### 示例
```json
{
"id": "edge-1",
"fromNode": "node-1",
"toNode": "node-2",
"fromSide": "right",
"toSide": "left",
"toEnd": "arrow",
"label": "调用"
}
```
## 颜色编码
| color | 颜色 | 建议用途 |
|:---|:---|:---|
| `1` | 红色 | 缓存、热点、警告 |
| `2` | 橙色 | 消息队列、异步 |
| `3` | 黄色 | 上游依赖、外部输入 |
| `4` | 绿色 | 数据库、持久化 |
| `5` | 蓝色 | 搜索、外部服务 |
| `6` | 紫色 | 注释、设计决策 |
## 布局建议
### 三层架构布局
```
x: -400 x: 0 x: 400 x: 800
┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
│ 前端 │→│ API │→│ 服务 │→│ 数据 │
└────────┘ └────────┘ └────────┘ └────────┘
```
### 间距建议
- 节点宽度: 200-280
- 节点高度: 80-150
- 水平间距: 100-150
- 垂直间距: 120-150
## 完整示例
```json
{
"nodes": [
{
"id": "group-api",
"type": "group",
"x": -50,
"y": -50,
"width": 300,
"height": 200,
"label": "API 层"
},
{
"id": "api-user",
"type": "text",
"x": 0,
"y": 0,
"width": 200,
"height": 100,
"text": "# UserAPI\n\n- GET /users\n- POST /users"
},
{
"id": "svc-user",
"type": "text",
"x": 350,
"y": 0,
"width": 200,
"height": 100,
"text": "# UserService\n\n- get_user()\n- create_user()"
},
{
"id": "db",
"type": "text",
"x": 700,
"y": 0,
"width": 200,
"height": 80,
"text": "# PostgreSQL",
"color": "4"
}
],
"edges": [
{
"id": "e1",
"fromNode": "api-user",
"toNode": "svc-user",
"fromSide": "right",
"toSide": "left",
"label": "调用"
},
{
"id": "e2",
"fromNode": "svc-user",
"toNode": "db",
"fromSide": "right",
"toSide": "left"
}
]
}
```

34
i18n/zh/skills/01-AI工具/canvas-dev/references/index.md Normal file
View File

@ -0,0 +1,34 @@
# Canvas-Dev Skill References
## 导航索引
### 核心文档
| 文档 | 说明 |
|:---|:---|
| [canvas-json-spec.md](./canvas-json-spec.md) | Obsidian Canvas JSON 完整规范 |
| [workflow-guide.md](./workflow-guide.md) | 完整工作流指南 |
| [prompts.md](./prompts.md) | 提示词集合 |
### 相关资源
| 资源 | 路径 |
|:---|:---|
| Canvas白板驱动开发详解 | `../../documents/02-方法论/图形化AI协作-Canvas白板驱动开发.md` |
| Canvas开发工作流 | `../../workflow/canvas-dev/` |
| 架构分析提示词 | `../../workflow/canvas-dev/prompts/01-架构分析.md` |
| 白板驱动编码提示词 | `../../workflow/canvas-dev/prompts/02-白板驱动编码.md` |
| 白板同步检查提示词 | `../../workflow/canvas-dev/prompts/03-白板同步检查.md` |
### 模板
| 模板 | 路径 |
|:---|:---|
| 项目白板模板 | `../../workflow/canvas-dev/templates/project.canvas` |
| 模块白板模板 | `../../workflow/canvas-dev/templates/module.canvas` |
| 示例项目白板 | `../../workflow/canvas-dev/examples/demo-project.canvas` |
### 外部链接
- [Obsidian Canvas 官方文档](https://obsidian.md/canvas)
- [Obsidian 下载](https://obsidian.md/download)

143
i18n/zh/skills/01-AI工具/canvas-dev/references/prompts.md Normal file
View File

@ -0,0 +1,143 @@
# Canvas 开发提示词集合
## 1. 架构分析提示词
从现有代码生成 Obsidian Canvas 架构白板。
```markdown
你是一个代码架构分析专家。请分析以下项目结构，生成 Obsidian Canvas 格式的架构白板。
## 输入
项目路径：{PROJECT_PATH}
分析粒度：{file/class/service}
## 输出要求
生成符合 Obsidian Canvas JSON 格式的 .canvas 文件，包含：
1. **节点 (nodes)**：每个模块/文件/类作为一个节点
2. **连线 (edges)**：表示模块间的依赖/调用关系
3. **分组 (groups)**：按功能域分组
## 布局规则
- x轴: -400 (前端) → 0 (API) → 400 (服务) → 800 (数据)
- 节点宽度: 200-280，高度: 80-150
- 间距: 水平 100-150，垂直 120-150
## 输出格式
直接输出 JSON，可保存为 .canvas 文件
```
## 2. 白板驱动编码提示词
根据 Canvas 白板生成代码。
```markdown
你是一个根据架构白板生成代码的专家。请根据以下 Obsidian Canvas 白板 JSON，生成对应的代码实现。
## 输入
Canvas JSON：
```json
{CANVAS_JSON}
```
技术栈：{TECH_STACK}
目标目录：{TARGET_DIR}
## 解析规则
1. 节点 text 标题 → 文件名/类名
2. 节点 text 列表项 → 方法/函数
3. 连线 fromNode → toNode = import/调用关系
4. edge label 决定关系类型
## 输出格式
```
文件：{文件路径}
```{语言}
{代码内容}
```
```
## 3. 白板同步检查提示词
校验白板与代码一致性。
```markdown
你是一个代码与架构一致性检查专家。请对比以下白板和代码，找出不一致之处。
## 输入
Canvas 白板 JSON：
```json
{CANVAS_JSON}
```
项目代码路径：{PROJECT_PATH}
## 检查项
1. 节点完整性：白板节点是否都有对应代码？
2. 连线准确性：连线是否反映真实依赖？
3. 分组正确性：分组是否与目录结构一致？
## 输出格式
### 🔴 严重不一致
| 类型 | 白板 | 代码 | 建议 |
### 🟡 轻微不一致
| 类型 | 白板 | 代码 | 建议 |
### 🟢 一致性良好
- 覆盖率：{X}%
```
## 4. 增量更新提示词
白板修改后同步更新代码。
```markdown
白板已更新，请对比新旧版本，只修改变化的部分：
旧白板：
```json
{OLD_CANVAS_JSON}
```
新白板：
```json
{NEW_CANVAS_JSON}
```
## 输出
1. 需要新增的文件
2. 需要修改的文件（只输出 diff）
3. 需要删除的文件
```
## 5. 快速理解项目提示词
接手新项目时快速生成架构概览。
```markdown
我需要快速理解这个项目的架构。请：
1. 扫描 {PROJECT_PATH} 目录
2. 识别核心模块和入口文件
3. 生成一个简化的架构白板（只包含关键模块）
4. 用 3-5 句话总结项目架构
粒度：service（只显示大模块）
重点：数据流向、外部依赖、核心业务逻辑
```
## 使用技巧
### 提高生成质量
1. **明确粒度**：小项目用 file，大项目用 service
2. **指定重点**：告诉 AI 关注什么（API/数据库/外部服务）
3. **提供上下文**：附上 README 或技术栈说明
### 迭代优化
1. 第一次生成后，手动调整布局
2. 补充 AI 遗漏的隐式依赖
3. 添加注释节点说明设计决策
4. 再次发给 AI 验证理解是否正确

163
i18n/zh/skills/01-AI工具/canvas-dev/references/workflow-guide.md Normal file
View File

@ -0,0 +1,163 @@
# Canvas 白板驱动开发工作流指南
## 核心理念
```
传统开发：代码 → 口头沟通 → 脑补架构 → 代码失控
Canvas方式：代码 ⇄ 白板 ⇄ AI ⇄ 人类（白板为单一真相源）
```
**图形是第一公民，代码是白板的序列化形式。**
## 工具准备
1. **Obsidian** - 免费开源白板工具
- 下载: https://obsidian.md/download
- 启用 Canvas 功能（默认已启用）
2. **AI 助手** - Claude/GPT-4
- 需支持读取 Canvas JSON 格式
- 推荐使用 Claude Code 或 Codex CLI
## 完整工作流
### Phase 1: 生成架构白板
**场景**: 接手新项目，快速理解架构
```
1. 提供项目代码路径给 AI
2. 使用架构分析提示词
3. AI 生成 .canvas 文件
4. 用 Obsidian 打开查看
```
**提示词模板**:
```
分析 {PROJECT_PATH} 项目，生成 Obsidian Canvas 架构白板。
粒度: {file/class/service}
重点关注: API路由、数据库模型、外部服务调用
```
### Phase 2: 人工优化白板
**场景**: 调整自动生成的白板
```
1. 拖动节点调整布局
2. 补充遗漏的依赖连线
3. 添加注释节点标注设计决策
4. 删除错误的连接
```
**布局原则**:
- 按功能分层（前端 → API → 服务 → 数据）
- 同层节点垂直对齐
- 保持连线不交叉
### Phase 3: 白板驱动编码
**场景**: 新功能开发
```
1. 在白板上画出新模块框
2. 添加预期的调用连线
3. 导出白板 JSON 发给 AI
4. AI 根据白板生成代码
```
**提示词模板**:
```
根据以下 Canvas 白板生成代码:
{CANVAS_JSON}
技术栈: {TECH_STACK}
目标目录: {TARGET_DIR}
```
### Phase 4: 白板驱动重构
**场景**: 架构调整
```
1. 在白板上删除/重连依赖线
2. 标注需要拆分的大模块
3. 发送修改后的白板给 AI
4. AI 生成重构代码
```
**提示词模板**:
```
白板已更新，请对比新旧版本重构代码:
旧白板: {OLD_CANVAS}
新白板: {NEW_CANVAS}
只输出需要修改的文件
```
### Phase 5: 一致性检查
**场景**: PR/MR 合并前
```
1. 运行一致性检查脚本
2. 对比白板节点与实际文件
3. 修复不一致之处
4. 优先修正白板（白板是事实来源）
```
## 场景速查
| 场景 | 操作 | 提示词关键词 |
|:---|:---|:---|
| 接手新项目 | 生成白板 | "分析项目，生成架构白板" |
| 新功能开发 | 画白板 → 生成代码 | "按这个白板实现代码" |
| 架构重构 | 改白板 → 重构代码 | "按新白板重构" |
| Code Review | 看白板全局 | "检查这条调用链" |
| 团队协作 | 共享白板 | "指着白板讲" |
## 最佳实践
### DO ✅
- 每次代码变更后更新白板
- 用颜色区分不同类型的模块
- 为复杂依赖添加 label 说明
- 定期运行一致性检查
### DON'T ❌
- 不要让白板与代码长期不同步
- 不要在白板中包含敏感信息
- 不要创建过于复杂的白板（拆分为多个）
- 不要忽略循环依赖警告
## 与其他工具集成
### CI/CD 集成
```yaml
# .github/workflows/canvas-check.yml
name: Canvas Sync Check
on:
pull_request:
paths: ['**.py', '**.canvas']
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: python scripts/canvas_sync_check.py
```
### VS Code 集成
1. 安装 Obsidian 插件
2. 配置 `.canvas` 文件关联
3. 使用 Claude Code 读取白板
## 相关资源
- [Canvas白板驱动开发详解](../../../documents/02-方法论/图形化AI协作-Canvas白板驱动开发.md)
- [架构分析提示词](../../../workflow/canvas-dev/prompts/01-架构分析.md)
- [白板驱动编码提示词](../../../workflow/canvas-dev/prompts/02-白板驱动编码.md)
- [白板同步检查提示词](../../../workflow/canvas-dev/prompts/03-白板同步检查.md)