refactor: update canvas-dev skill aligned with workflow.md and online prompts

2026-01-01 07:29:33 +08:00 · 2026-01-01 07:29:33 +08:00 · ec229a736e
parent bfa2de8177
commit ec229a736e
2 changed files with 135 additions and 186 deletions
--- a/i18n/zh/skills/01-AI工具/canvas-dev/SKILL.md
+++ b/i18n/zh/skills/01-AI工具/canvas-dev/SKILL.md
@ -1,37 +1,80 @@
 ---
 name: canvas-dev
-description: "Canvas白板驱动开发技能：从代码生成架构白板、根据白板生成代码、校验白板与代码一致性。使用场景：接手新项目快速理解架构、新功能开发先画白板再编码、架构重构可视化、团队协作共享架构图。"
+description: "Canvas白板驱动开发技能：Canvas白板作为唯一真相源，代码是其序列化形式。使用场景：生成架构白板、白板驱动编码、白板驱动重构、Code Review、团队协作、接手遗留项目。"
 ---

 # canvas-dev Skill

-Canvas白板驱动开发：图形是第一公民，代码是白板的序列化形式。通过 Obsidian Canvas 实现人类与AI的共享工作区。
+Canvas白板驱动开发：图形是第一公民，代码是白板的序列化形式。人类负责架构设计，AI负责代码实现。

 ## When to Use This Skill

 触发条件（满足任一即可）：
- 需要快速理解现有项目架构（接手遗留代码）
- 新功能开发前需要设计架构（先画后写）
- 架构重构需要可视化依赖关系
- Code Review 需要全局视角
- 团队协作需要共享架构图
- 需要生成 Obsidian Canvas 格式的 `.canvas` 文件
+- 需要生成项目架构白板（从代码 → 白板）
+- 需要根据白板生成代码（从白板 → 代码）
+- 需要白板驱动代码重构
+- 需要用白板辅助 Code Review
+- 需要用白板加速团队协作
+- 接手遗留项目需要快速理解架构

 ## Not For / Boundaries

 此技能不适用于：
- 纯文本文档生成（使用 Markdown 即可）
+- 纯文本文档生成（使用 Markdown）
 - 流程图/时序图（使用 Mermaid）
- 数据库 ER 图（使用专用工具）
 - 不需要双向同步的静态架构图

 必要输入（缺失时需询问）：
-1. 项目代码路径或代码片段
-2. 分析粒度（file/class/service）
-3. 技术栈（用于生成代码时）
+1. 项目类型：A) 单体应用 B) 微服务架构 C) 前后端分离？
+2. 白板粒度：A) 文件级 B) 类/函数级 C) 服务级？

 ## Quick Reference

+### 核心理念
+
+```
+传统：代码 → 口头沟通 → 脑补架构 → 代码失控
+Canvas：代码 ⇄ 白板 ⇄ AI ⇄ 人类（白板为单一真相源）
+```
+
+| 痛点 | 解法 |
+|:---|:---|
+| AI看不懂项目结构 | AI直接读白板JSON，秒懂架构 |
+| 人类记不住复杂依赖 | 连线清晰，牵一发动全身一目了然 |
+| 团队协作靠嘴说 | 指着白板讲，新人5分钟看懂 |
+
+### 15步完整工作流
+
+1. **理解核心理念**：Canvas白板作为唯一真相源，代码是其序列化形式；图形语言优于文字描述；人类负责架构设计，AI负责代码实现
+
+2. **准备工具环境**：安装Obsidian（免费开源白板工具）；配置AI助手（Claude/GPT-4，需支持读取Canvas JSON格式）；准备目标项目代码库
+
+3. **生成初始架构白板**：向AI提供项目代码路径；使用架构分析提示词让AI扫描项目结构；AI自动生成.canvas文件，包含模块节点和依赖连线
+
+4. **用Obsidian打开.canvas文件**：导入生成的架构白板；检查自动识别的模块、文件、API调用关系；验证关键依赖连线是否准确
+
+5. **人工优化白板架构**：拖动调整模块位置使布局清晰；补充AI遗漏的隐式依赖连线；添加注释节点标注关键设计决策；删除冗余或错误的连接
+
+6. **建立代码-白板同步机制**：配置代码变更监听脚本；设置白板自动更新规则（新文件→新节点，新import→新连线）；或手动维护：每次代码改动后更新对应白板区域
+
+7. **用白板驱动AI编程（新功能开发）**：在白板上画出新模块框和预期调用关系；导出白板JSON发送给AI；指令："按照这个架构图实现具体代码"；AI根据节点名称、连线方向生成文件和函数调用
+
+8. **用白板驱动代码重构**：在白板上删除/重连模块间的依赖线；标注需要拆分的大模块；发送修改后的白板给AI："按新架构重构代码，列出需要修改的文件清单"
+
+9. **用白板辅助Code Review**：Review前先看白板全局架构；识别异常连线（如前端直接连数据库、循环依赖）；在白板上标注问题点；讨论时指着白板说明
+
+10. **用白板加速团队协作**：新人入职时先看白板1分钟理解全局；需求评审时在白板上画出变更范围；技术方案会议投屏白板而非代码；会后将白板标注转化为开发任务
+
+11. **维护白板与代码一致性**：每次PR/MR合并前检查白板是否需要更新；定期运行自动校验脚本；发现不一致时优先修正白板（白板是事实来源）
+
+12. **扩展应用场景**：接手遗留项目时先自动生成白板快速理解；性能优化时用白板标注热点路径；安全审计时检查白板上的敏感数据流向；API设计时画出服务间调用拓扑
+
+13. **明确项目类型**：A) 单体应用（单进程多模块） B) 微服务架构（多服务RPC通信） C) 前后端分离（前端框架+后端API）
+
+14. **选择白板粒度**：A) 文件级（每个代码文件一个节点）- 推荐新手 B) 类/函数级（每个类一个节点） C) 服务级（仅显示大模块）- 推荐复杂项目
+
+15. **持续迭代工作流**：每周回顾白板是否反映真实架构；收集团队反馈优化节点命名和布局规则；探索白板与CI/CD集成
+
 ### Canvas JSON 基础结构

 ```json
@ -45,202 +88,102 @@ Canvas白板驱动开发：图形是第一公民，代码是白板的序列化
 }
 ```

-### 节点类型
+### 白板自动生成示例

-| 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
+```python
+# 你写了新文件 payment_service.py
+class PaymentService:
+    def process(self):
+        db.save()  # ← AI检测到数据库写入
+        stripe.charge()  # ← AI检测到外部API调用
 ```

-### 颜色编码（Obsidian Canvas）
-
-| color | 含义 |
-|:---|:---|
-| `1` | 红色 - 缓存/热点 |
-| `2` | 橙色 - 消息队列 |
-| `3` | 黄色 - 上游依赖 |
-| `4` | 绿色 - 数据库 |
-| `5` | 蓝色 - 搜索/外部服务 |
-| `6` | 紫色 - 注释/设计决策 |
+**白板自动生成：**
+```
+[PaymentService] ──写入──> [数据库]
+       │
+       └──调用──> [Stripe API]
+```

 ## Rules & Constraints

 ### MUST（必须遵守）

- 节点 `id` 必须唯一且有意义（如 `svc-user`，非 `node1`）
- 连线必须反映真实的代码依赖关系
- 生成的 `.canvas` 文件必须是合法 JSON
+- Canvas白板是唯一真相源，代码是其序列化形式
 - 白板修改后必须同步更新相关代码
+- 发现不一致时优先修正白板

 ### SHOULD（强烈建议）

- 按功能域分组（API层/服务层/数据层）
- 节点 text 使用 Markdown 格式（`# 标题` + 列表）
- 保持布局整洁（对齐、等间距）
- 为复杂依赖添加 label 说明
+- 人类负责架构设计（在白板拖拽模块）
+- AI负责细节实现（根据白板连线生成代码）
+- 都编辑同一个白板，而不是来回传递文本

 ### NEVER（禁止）

- 不要生成与代码不一致的白板
- 不要在白板中包含敏感信息（密钥/密码）
- 不要创建循环依赖的连线（除非代码确实如此）
+- 不要让白板与代码长期不同步
+- 不要在白板中包含敏感信息

 ## Examples

-### Example 1: 从代码生成架构白板
+### Example 1: 给AI派活（新功能开发）

-**Input:**
-```
-项目路径: /home/user/my-api
-技术栈: Python FastAPI
-粒度: file
-```
+**传统方式:**
+> "帮我写个用户注册功能，要连数据库，发邮件，记日志"

-**Steps:**
-1. 扫描项目目录，识别 `.py` 文件
-2. 分析 `import` 语句提取依赖关系
-3. 识别 FastAPI 路由、数据库模型、外部调用
-4. 按三层架构布局节点
-5. 生成 `.canvas` JSON
+**Canvas方式:**
+1. 在白板画3个框：`RegisterAPI` → `Database` / `EmailService` / `Logger`
+2. 告诉AI："按这个图实现"
+3. AI一次性写对所有文件和调用关系

-**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: Code Review

-### Example 2: 根据白板生成代码
+**传统方式:** 一行行看代码，看晕了

-**Input:**
-```
-Canvas JSON: (包含 UserAPI → UserService → UserModel 的白板)
-技术栈: Python FastAPI + SQLAlchemy
-目标目录: /home/user/new-project
-```
+**Canvas方式:**
+1. 看白板："咦，为什么前端直接连数据库？"
+2. 拖动节点调整架构
+3. AI自动重构代码

-**Steps:**
-1. 解析节点 → 生成文件/类
-2. 解析连线 → 生成 import 和调用
-3. 按技术栈最佳实践填充代码
+### Example 3: 接手他人项目

-**Expected Output:**
-```python
-# user_router.py
-from fastapi import APIRouter
-from .user_service import UserService
+**传统方式:** 看3天代码还没懂

-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
-```
+**Canvas方式:**
+1. 运行自动生成工具 → 1分钟得到架构白板
+2. 点开感兴趣的模块看详情
+3. 直接在白板上画出要改的部分，AI帮你定位代码位置

 ## FAQ

-**Q: 为什么选择 Obsidian Canvas 而不是其他工具？**
- A: Obsidian Canvas 是免费开源的，`.canvas` 文件是纯 JSON 格式，AI 可以直接读写，支持双向同步。
+**Q: 为什么图形语言优于文字描述？**
+- A: 图形语言是人类大脑的母语。你能瞬间理解地铁线路图，但看不懂等效的换乘文字说明。AI解析JSON比解析自然语言描述准确10倍。

-**Q: 白板粒度选 file 还是 class？**
- A: 小项目（<20文件）选 file，大项目选 class 或 service。关键是保持白板可读性。
+**Q: 白板粒度怎么选？**
+- A: 新手选文件级（A），复杂项目选服务级（C）。关键是保持白板可读性。

-**Q: 如何处理循环依赖？**
- A: 如果代码确实存在循环依赖，在白板中如实标注，并添加注释节点说明这是技术债务。
+**Q: 代码生成已经商品化，为什么还需要这个？**
+- A: 架构设计才是稀缺能力。未来程序员的工作：设计白板架构；AI的工作：把白板翻译成代码。

-## Troubleshooting
+## 金句总结

-| 症状 | 可能原因 | 解决方案 |
-|:---|:---|:---|
-| Obsidian 无法打开 .canvas | JSON 格式错误 | 用 `jq .` 验证 JSON |
-| 节点重叠 | x/y 坐标冲突 | 调整布局，保持 200+ 间距 |
-| 连线不显示 | fromNode/toNode id 错误 | 检查节点 id 是否匹配 |
-| AI 生成代码与白板不符 | 白板描述不够具体 | 在节点 text 中添加更多细节 |
+> "当代码变成白板上的方块，编程就从打字变成了搭积木。"
+
+> "最好的文档不是Markdown，是能直接驱动AI工作的架构图。"
+
+> "AI看懂你的图，比看懂你的话，容易一万倍。"

 ## References

- `references/index.md` - 导航索引
- `references/canvas-json-spec.md` - Canvas JSON 完整规范
- `references/workflow-guide.md` - 完整工作流指南
- `references/prompts.md` - 提示词集合
-
-外部资源：
+- [Canvas白板生成提示词](https://docs.google.com/spreadsheets/d/1Ifk_dLF25ULSxcfGem1hXzJsi7_RBUNAki8SBCuvkJA/edit?gid=1777853069#gid=1777853069&range=A1) - 自动生成架构白板的完整提示词（最新）
+- [Canvas驱动开发完整工作流](../../workflow/canvas-dev/workflow.md) - 15步完整流程
+- [Canvas白板驱动开发详解](../../documents/02-方法论/图形化AI协作-Canvas白板驱动开发.md) - 方法论详解
+- [白板驱动开发系统提示词](../../prompts/01-系统提示词/AGENTS.md/12/AGENTS.md) - 适配Canvas白板驱动开发的AGENTS.md
 - [Obsidian Canvas 官方文档](https://obsidian.md/canvas)
- [Canvas白板驱动开发详解](../../documents/02-方法论/图形化AI协作-Canvas白板驱动开发.md)
- [Canvas开发工作流](../../workflow/canvas-dev/README.md)
+- `references/index.md` - 本地参考文档导航

 ## Maintenance

- Sources: Obsidian Canvas 官方文档 + 本地工作流实践
+- Sources: workflow.md + 在线提示词表格 + 方法论文档
 - 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. ✅ 无虚构内容，不确定处标注验证路径
+- Known limits: 仅支持 Obsidian Canvas 格式
--- a/i18n/zh/skills/01-AI工具/canvas-dev/references/index.md
+++ b/i18n/zh/skills/01-AI工具/canvas-dev/references/index.md
@ -2,33 +2,39 @@

 ## 导航索引

+### 最新资源（优先参考）
+
+| 资源 | 链接 | 说明 |
+|:---|:---|:---|
+| Canvas白板生成提示词 | [在线表格](https://docs.google.com/spreadsheets/d/1Ifk_dLF25ULSxcfGem1hXzJsi7_RBUNAki8SBCuvkJA/edit?gid=1777853069#gid=1777853069&range=A1) | 自动生成架构白板的完整提示词（最新） |
+| Canvas驱动开发完整工作流 | [workflow.md](../../../workflow/canvas-dev/workflow.md) | 15步完整流程 |
+
 ### 核心文档

-| 文档 | 说明 |
-|:---|:---|
-| [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` | 方法论详解 |
+| 白板驱动开发系统提示词 | `../../prompts/01-系统提示词/AGENTS.md/12/AGENTS.md` | 适配Canvas的AGENTS.md |
+| Canvas JSON 规范 | [canvas-json-spec.md](./canvas-json-spec.md) | Obsidian Canvas JSON 格式 |

-### 相关资源
+### 工作流提示词

-| 资源 | 路径 |
+| 提示词 | 路径 |
 |:---|:---|
-| 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/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` |
+| 项目白板模板 | `../../../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)
+- [胶水编程](../../documents/00-基础指南/胶水编程.md) - 能抄不写，能连不造