From ec229a736e1ca02ecf4054a2be9269795c150e35 Mon Sep 17 00:00:00 2001 From: tukuaiai Date: Thu, 1 Jan 2026 07:29:33 +0800 Subject: [PATCH] refactor: update canvas-dev skill aligned with workflow.md and online prompts --- i18n/zh/skills/01-AI工具/canvas-dev/SKILL.md | 285 +++++++----------- .../01-AI工具/canvas-dev/references/index.md | 36 ++- 2 files changed, 135 insertions(+), 186 deletions(-) diff --git a/i18n/zh/skills/01-AI工具/canvas-dev/SKILL.md b/i18n/zh/skills/01-AI工具/canvas-dev/SKILL.md index 9e11d9a..0d1012f 100644 --- 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 格式 diff --git a/i18n/zh/skills/01-AI工具/canvas-dev/references/index.md b/i18n/zh/skills/01-AI工具/canvas-dev/references/index.md index 4136b79..c1104c4 100644 --- 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) - 能抄不写，能连不造