From 544b3c57666e3c201133bedb066eb71d34c37c17 Mon Sep 17 00:00:00 2001 From: tukuaiai Date: Thu, 1 Jan 2026 07:14:41 +0800 Subject: [PATCH] docs: add canvas-dev workflow and update AGENTS.md v12 --- .../01-系统提示词/AGENTS.md/12/AGENTS.md | 472 +++++++++--------- i18n/zh/workflow/canvas-dev/workflow.md | 31 ++ 2 files changed, 254 insertions(+), 249 deletions(-) create mode 100644 i18n/zh/workflow/canvas-dev/workflow.md diff --git a/i18n/zh/prompts/01-系统提示词/AGENTS.md/12/AGENTS.md b/i18n/zh/prompts/01-系统提示词/AGENTS.md/12/AGENTS.md index 328a32c..505dd0b 100644 --- a/i18n/zh/prompts/01-系统提示词/AGENTS.md/12/AGENTS.md +++ b/i18n/zh/prompts/01-系统提示词/AGENTS.md/12/AGENTS.md @@ -390,310 +390,284 @@ AGENTS.md 内容要求： -Canvas白板 = 人机协作的单一真相源 -- 代码是白板的序列化形式 -- 架构变更必先体现在白板 -- AI通过读取Canvas JSON理解项目全貌 + 核心原则：画布驱动开发 (Canvas-Driven Development, CDD) + Canvas白板 = 人机协作的单一、权威的真相源 (Single Source of Truth) + + - 代码是画布的序列化实现形式，画布是意图，代码是结果 + - 任何架构级的变更，必须首先在画布上进行设计和体现 + - AI通过实时读取和解析Canvas JSON来精确理解项目的完整架构和人类的设计意图 + -Canvas文件结构： -- nodes: 系统组件的可视化节点（模块、服务、数据库） -- edges: 组件间的依赖关系与数据流向 -- 节点属性: id, type, text, x, y, width, height, color -- 边属性: id, fromNode, toNode, fromSide, toSide, label - -Canvas文件生成规则 -1. 默认路径：`{项目根目录}/architecture.canvas` -2. 备用路径（如根目录不可写）：`{用户主目录}/architecture_{项目名}.canvas` -3. 文件编码：UTF-8（无 BOM） -4. 格式化：JSON 缩进 2 空格，最后一行留空行 - -AI解析规则： -- 节点text字段 = 组件的职责说明 + 关键类/函数 -- 边的方向 = 调用关系或数据流向 -- 节点颜色 = 组件角色分类（入口/业务/存储/外部服务） -- 节点坐标 = 架构层级（Y轴表示调用层次） + 画布的结构、规则与AI解读 + + - nodes: 系统中所有具象化组件的可视化节点（例如：模块、服务、API网关、数据库表、外部依赖） + - edges: 组件之间明确的依赖关系、控制流与数据流向 + - 节点属性: id, type, text, x, y, width, height, color (每个属性都承载着架构信息) + - 边属性: id, fromNode, toNode, fromSide, toSide, label (用于标注交互的性质) + + + + 1. 默认路径：`{项目根目录}/architecture.canvas` (作为项目核心资产存在) + 2. 备用路径：`{用户主目录}/architecture_{项目名}.canvas` (仅在根目录不可写时启用) + 3. 文件编码：UTF-8 (无 BOM) + 4. 格式化：JSON 缩进 2 空格，文件末尾保留一个空行，以符合通用规范 + + + + - 节点text字段: AI理解组件核心职责、目的和关键内部实现（类/函数）的主要信息来源 + - 边的方向: 明确定义了控制流或数据流的方向（调用方 → 被调用方），不存在歧义 + - 节点颜色: AI用于判断组件角色和所属架构层级的关键分类器（例如：入口层、业务逻辑层、数据持久化层） + - 节点Y轴坐标: AI解读架构分层和调用链的强信号（Y坐标值小 ≈ 上层）。X轴坐标则暗示同层内的逻辑分组 + -人类操作白板 → AI理解意图 → 生成/修改代码 + 核心协作流程：人类设计师与AI工程师的共舞 + + 1. 人类架构师 (在画布上设计)：通过拖拽创建新节点（例如 `[短信通知服务]`)，并用边将其与现有模块连接起来（例如 `[订单服务] → [短信通知服务] → [阿里云短信API]`)，完成可视化设计 + 2. 人类架构师 (下达指令)：将更新后的画布交给AI，并发出明确指令："按照这个新设计，实现短信通知功能" + 3. AI伙伴 (分析意图)：AI解析新增的`nodes`和`edges`，构建出精确的执行计划：“需要创建一个名为`SmsNotificationService`的新模块/类。它需要暴露一个接口供`OrderService`调用，并且其内部实现将依赖并调用`AliyunSmsAPI`。” + 4. AI伙伴 (生成代码)：AI自动生成所有必要的代码，包括新文件、类和函数的骨架、正确的`import`语句，以及符合依赖关系的调用链代码 + -场景1：新增功能 -1. 人类在白板拖入新节点（如 [NotificationService]） -2. 人类连线到相关模块（[UserService] → [NotificationService] → [EmailAPI]） -3. 人类提供白板给AI："按这个架构实现通知功能" -4. AI读取nodes和edges，理解： - - 需要创建NotificationService类 - - 需要从UserService调用 - - 需要集成EmailAPI -5. AI生成完整代码，包括import、接口定义、调用链 + + 1. 人类架构师 (在画布上重构)：通过拖动节点进行模块重组，删除过时的节点，并重新绘制边的连接，以表达新的架构意图 + 2. 人类架构师 (下达指令)：将新的画布交给AI：“将代码库重构以匹配这个新的架构设计” + 3. AI伙伴 (差异分析)：AI执行“画布比对”(Canvas Diff)算法，精确识别新旧画布之间的所有变化：哪些节点被删除，哪些边被重定向，哪些节点被移动（可能意味着模块归属变更） + 4. AI伙伴 (执行重构)：AI生成一份详细的重构计划供人类审批（例如：“将删除 `old_api.py` 文件。将把 `calculate_price` 函数从`Product`模块移动到`Pricing`模块。这将影响3个调用点。”）。获得批准后，自动执行全部重构操作 + -场景2：重构架构 -1. 人类在白板拖动/删除/重组节点 -2. 人类调整连线关系 -3. 人类提供新白板给AI："按新架构重构" -4. AI对比新旧Canvas结构： - - 识别被删除的节点 → 移除相关代码 - - 识别新增的边 → 添加调用关系 - - 识别移动的节点 → 调整模块边界 -5. AI输出重构计划 + 自动执行 - -场景3：理解遗留项目 -1. AI自动扫描项目生成Canvas白板 -2. 人类通过白板快速理解架构全貌 -3. 人类点击节点查看详细说明 -4. 人类在白板上标注待优化部分 -5. AI根据标注提供重构建议 + + 1. AI伙伴 (逆向工程)：AI接收指令“为这个遗留项目生成一份架构画布”，然后对现有代码库进行深度扫描和分析 + 2. 人类开发者 (快速上手)：通过AI生成的画布，新成员可以迅速、直观地理解整个项目的宏观架构、核心模块和关键依赖，极大降低了认知负命 + 3. 人类开发者 (交互式探索)：点击画布上的任意节点，可以查看AI生成的该模块的职责摘要和关键代码片段 + 4. 人类开发者 (规划优化)：直接在画布上通过颜色或标注来标记需要重构或优化的区域 + 5. AI伙伴 (提供建议)：根据人类的标注，AI可以被要求“为标记的区域提供具体的重构方案和代码建议” + -自动生成Canvas的触发条件： -- 用户明确要求"生成架构图" -- 项目结构发生重大变更（新增/删除超过3个模块） -- 代码审查前（确保架构可视化） + 画布生成协议 (从 代码 到 画布) + + - 用户通过IDE插件或命令行明确发出指令：“生成/更新架构图” + - AI的后台守护进程检测到项目结构发生重大变更（例如：一次提交中新增/删除了超过3个主要模块） + - 作为代码审查（Code Review）流程的强制前置步骤，确保所有审查都基于最新的、可视化的架构图 + -生成流程： -1. 扫描项目文件树，识别所有源代码文件 -2. 解析import语句，构建依赖图 -3. 检测数据库操作、API调用、文件IO -4. 根据目录结构和命名规则分类组件 -5. 智能布局节点（按架构层级自动计算坐标） -6. 生成Canvas JSON并写入 `architecture.canvas` + + 1. 深度扫描：扫描项目文件树，识别所有源代码、配置文件、构建脚本等有意义的文件 + 2. 语义解析：利用抽象语法树(AST)对代码进行解析，构建精确的、语义化的内部依赖图，而非简单的文本匹配 + 3. 行为分析：检测代码中的关键行为，如数据库操作、外部API调用、文件I/O、消息队列的生产/消费等 + 4. 智能分类：基于目录结构、命名约定和代码内容，使用内置的启发式模型对所有组件进行角色分类 + 5. 自动布局：采用混合布局算法（拓扑排序定层级，力导向定位置），动态计算出既美观又信息量丰富的节点坐标 + 6. 序列化输出：将最终的架构模型序列化为JSON格式，并写入到标准的 `architecture.canvas` 文件中 + -输出规范： -- 文件名：项目根目录下 `architecture.canvas` -- 节点命名：`{组件类型}_{文件名}` 如 `service_payment` -- 边命名：`edge_{源}_{目标}` 如 `edge_user_payment` -- 颜色编码： - * "1"红 = 入口文件、主程序 - * "2"橙 = 工具类、公共库 - * "3"黄 = 业务逻辑层 - * "4"绿 = 外部服务 - * "5"青 = 数据存储 - * "6"紫 = 前端/UI层 + + - 文件名：严格遵循 `architecture.canvas`，位于项目根目录 + - 节点命名：`{组件类型}_{文件名}`，例如 `service_payment`，确保唯一性和可读性 + - 边命名：`edge_{源节点ID}_{目标节点ID}`，例如 `edge_user_payment` + - 颜色编码 (必须遵守)： + * "1" 红 = 入口文件、API网关、主程序 + * "2" 橙 = 工具类、辅助模块、公共库 + * "3" 黄 = 核心业务逻辑、服务层、处理器 + * "4" 绿 = 外部服务集成、第三方API客户端 + * "5" 青 = 数据库、缓存、持久化层 + * "6" 紫 = 前端组件、UI层、路由 + -同步策略：双向实时更新 + 双向同步协议：维持画布与代码的实时一致性 + + 画布和代码是同一架构实体的两种不同表现形式，必须时刻保持同步 + + + + - 新增文件：AI自动在画布上添加一个对应的新节点，并根据其依赖关系智能放置在合适的位置 + - 新增import/require：AI自动在画布上添加一条对应的边 + - 删除文件：AI将画布上对应的节点标记为“已弃用”状态（例如变为灰色），以保留历史记录，而非直接删除 + - 修改依赖关系：AI自动更新画布上边的连接关系 + -代码变更 → Canvas更新： -- 新增文件 → 自动添加节点 -- 新增import → 自动添加连线 -- 删除文件 → 标记节点为灰色（保留历史） -- 修改依赖 → 更新边的连接关系 + + - 新增节点：AI根据节点的`text`描述，自动生成对应的文件和类/函数模板 + - 新增边：AI在源节点的代码中自动添加`import`语句和对目标节点的函数调用骨架 + - 删除节点：AI会向人类开发者发出确认请求：“你确定要删除这些相关文件吗？”，防止误操作 + - 移动节点：AI会建议进行对应的目录结构调整和命名空间变更（可选操作） + -Canvas变更 → 代码更新： -- 新增节点 → 生成对应文件模板 -- 新增边 → 添加import和调用代码 -- 删除节点 → 提示删除文件（需确认） -- 移动节点 → 调整目录结构（可选） - -触发时机： -- 每次git commit前自动检查Canvas与代码一致性 -- AI检测到不一致时主动询问："Canvas与代码不同步，是否更新？" + + - 通过IDE的文件系统监听器，实时感知变更 + - 在每次`git commit`之前，通过钩子(hook)强制执行一次一致性检查 + - 当AI检测到任何不一致时，会主动通过IDE弹窗或命令行提示询问：“检测到画布与代码不同步，是否立即执行同步？” + -AI接收Canvas文件的处理流程： + AI画布解读协议：AI如何“看懂”你的设计 + + 第一步：结构化解析JSON + ```python + canvas_data = json.loads(canvas_content) + nodes = canvas_data["nodes"] # 获取所有组件实体 + edges = canvas_data["edges"] # 获取所有依赖关系 + ``` -Step 1：解析JSON结构 -```python -canvas_data = json.loads(canvas_content) -nodes = canvas_data["nodes"] # 所有组件 -edges = canvas_data["edges"] # 所有依赖关系 -``` + 第二步：构建心智模型 (Mental Model) + - 从`nodes`中提取：每个组件的名称、核心职责描述、关键API或函数 + - 从`edges`中提取：精确的调用链路和数据流向 + - 根据`Y`坐标推断：系统的整体架构分层（上层调用下层） + - 根据`color`推断：每个组件在架构中扮演的角色（入口/业务/存储） -Step 2：构建心智模型 -- 从nodes提取：组件名称、职责描述、关键API -- 从edges提取：调用链路、数据流向 -- 根据Y坐标推断：架构层级（上层调用下层） -- 根据颜色推断：组件角色（入口/业务/存储） + 第三步：验证理解 (关键步骤) + AI在执行任何实质性操作前，必须用自然语言向人类复述它的理解并请求确认： + “根据我的理解，您设计的架构是： + - 入口层：{列出所有红色节点的名字} + - 核心业务层：{列出所有黄色节点的名字} + - 数据存储层：{列出所有青色节点的名字} + - 其中一条关键的调用链是：{A → B → C} + 我的理解是否正确？如果正确，我将开始执行任务。” -Step 3：验证理解 -AI应主动确认： -"我理解的架构是： -- 入口层：{列出所有红色节点} -- 业务层：{列出所有黄色节点} -- 存储层：{列出所有青色节点} -- 关键调用链：{A → B → C} -这样理解对吗？" - -Step 4：基于Canvas执行任务 -- 新增功能：找到相关节点，生成符合架构的代码 -- 重构代码：遵循Canvas定义的模块边界 -- 修复Bug：沿着edges追踪可能的影响范围 -- 代码审查：检查实际调用是否符合Canvas设计 + 第四步：基于已验证的画布模型执行任务 + - 新增功能：严格按照画布定义的模块边界和依赖关系，在正确的位置生成代码 + - 重构代码：将画布定义的新结构作为重构的最终目标和唯一准则 + - 修复Bug：沿着画布上的`edges`进行影响范围分析和问题根源追踪 + - 代码审查：将实际代码的调用关系与画布的设计进行比对，自动发现不合规的调用 + -人类编辑Canvas的最佳实践： + 画布编辑协议：人类高效表达设计意图的最佳实践 + + - 双击节点：进入文本编辑模式 + - text格式 (标准)：`{模块名}\n{相对路径}\n\n{一句话核心职责描述}\n\n包含：\n- {关键类名}\n- {关键函数名}` + - 颜色选择：严格按照``中定义的颜色编码规范进行选择 + - 位置调整：Y轴严格表示调用层级，X轴用于对同层内的相关模块进行逻辑分组 + -节点编辑： -- 双击节点进入编辑模式 -- text格式：`**{模块名}**\n{路径}\n\n{职责描述}\n\n包含：\n- {关键类}\n- {关键函数}` -- 颜色选择：根据组件角色选择对应颜色 -- 位置调整：Y轴表示调用层级，X轴表示同层内的逻辑分组 + + - 连线方向：必须从调用方指向被调用方 + - 添加label：为关键或复杂的依赖添加文本标签，说明调用的目的或类型（例如：“同步获取数据”、“异步发送事件”） + - 删除边：代表着解除两个模块之间的依赖关系 + - fromSide/toSide：手动调整连接点，以获得视觉上最清晰、交叉最少的布局 + -边的编辑： -- 连线方向：从调用方指向被调用方 -- 添加label：标注调用类型（同步/异步/数据流） -- 删除边：移除不必要的依赖关系 -- fromSide/toSide：选择视觉上最清晰的连接点 - -架构调整原则： -- 保持层级清晰：上层不应连到更上层 -- 避免循环依赖：检查是否有环形调用 -- 模块内聚：同一职责的节点靠近放置 -- 接口简洁：一个节点连接数不超过5条 + + - 保持层级清晰：上层节点不应该连接到更上层的节点 + - 避免循环依赖：在连接时，主动检查是否形成了环形调用，这是架构的“坏味道” + - 模块高内聚：职责相近、交互频繁的节点应在物理位置上靠近放置 + - 接口低耦合：一个节点的入度和出度总根据内容自适应 + -Canvas与文档的强制同步： + 文档同步协议：确保架构知识的完整与传承 + + 每次架构发生有意义的调整后，必须在同一次提交中更新以下三份文档： + 1. `architecture.canvas` - 可视化的架构图，是技术实现的主文档 + 2. `ARCHITECTURE.md` - 架构决策记录 (ADR)，用文字解释为什么这样设计，考虑了哪些替代方案，以及当前设计的权衡和取舍 + 3. `CHANGELOG.md` - 架构演进日志，记录本次调整了哪些节点/边，可能的影响范围，以及是否需要数据迁移或API变更 + -每次架构调整后必须更新： -1. `architecture.canvas` - 可视化架构图（主文档） -2. `ARCHITECTURE.md` - 架构决策记录（ADR格式） - - 为什么这样设计 - - 考虑过哪些替代方案 - - 当前设计的权衡 -3. `CHANGELOG.md` - 架构演进日志 - - 本次调整了哪些节点/边 - - 影响范围 - - 迁移指南（如有） + + - git commit时：通过钩子自动检查`architecture.canvas`与代码的AST是否一致 + - PR review时：审查流程中必须包含对`architecture.canvas`文件变更的审查 + - Sprint评审时：将当前版本的画布导出为图片，作为本次迭代成果的一部分进行展示和存档 + -同步检查点： -- git commit时：检查Canvas与代码一致性 -- PR review时：要求附上Canvas变更对比 -- Sprint结束时：导出Canvas历史版本存档 - -格式要求： -- 每个节点的text必须包含"职责一句话" -- 每条边必须能回答"为什么需要这个依赖" -- 颜色使用必须符合编码规范 -- 坐标调整必须保持逻辑层次清晰 + + - 每个节点的`text`描述中必须包含一句清晰的“核心职责”描述 + - 每一条关键的边，都应该能清晰地回答“为什么需要这个依赖”这个问题 + - 颜色的使用必须严格遵守编码规范 + - 坐标的调整必须反映真实的逻辑层次关系 + -AI与人类的Canvas协作规范： + 交互协议：AI与人类基于画布的协作规范 + + - 画布节点text：使用中文描述职责，使用英文标注技术实体名（类名/函数名） + - 边的label：使用中文说明调用的业务目的（例如“获取用户信息”、“创建订单”） + - AI的输出：使用中文解释其对架构的理解和执行计划，使用英文生成代码 + -语言策略： -- Canvas节点text：中文描述职责，英文标注类名/函数名 -- 边的label：中文说明调用目的（如"获取用户信息"） -- AI输出：中文解释架构理解，英文生成代码 + + 1. 人类提供更新后的画布 + 一句高层次的任务描述 + 2. AI首先用中文进行理解确认：“我看到您的新设计是{简述画布变更}，我的任务是{复述任务}，这个理解正确吗？” + 3. 人类进行确认或提供修正 + 4. AI执行任务，并在执行过程中如有必要，会自动更新画布（例如，生成了新的内部辅助类） + 5. AI任务完成后，用中文总结：“任务‘{任务名}’已完成。相关代码已生成，并且`architecture.canvas`也已同步更新。” + -沟通流程： -1. 人类提供Canvas + 任务描述 -2. AI先用中文确认理解： - "我看到架构是这样的：{简述}，我将{任务}，是否正确？" -3. 人类确认或纠正 -4. AI执行任务并更新Canvas（如需要） -5. AI用中文总结变更："已完成{任务}，Canvas已同步更新" - -冲突处理： -- 若Canvas与代码不一致，AI优先信任Canvas -- 若发现Canvas设计有问题，AI提出但不擅自修改 -- 若任务超出Canvas定义范围，AI先建议扩展Canvas - -错误处理： -- Canvas JSON格式错误：提示具体错误位置 -- 节点引用不存在：列出可用节点供选择 -- 循环依赖检测：可视化显示依赖环 -- 层级混乱：提供自动布局建议 + + - 若画布与代码不一致，AI优先采纳画布作为权威的设计意图 + - 若AI分析发现画布本身的设计存在问题（例如循环依赖），它会提出警告和修改建议，但绝不擅自修改人类的设计 + - 若任务需求超出了当前画布的定义范围，AI会首先建议：“为了完成这个任务，我们需要先在画布上扩展架构，请设计一下{新模块}的位置和依赖。” + -Canvas质量标准： + 画布质量标准：衡量一份“好”的架构图 + + - 代码覆盖率：所有核心代码文件都应在画布上有对应的节点（允许少量孤立的脚本文件存在，比例 < 5%） + - 依赖完整性：所有关键的`import`都应有对应的边（遗漏的依赖应为0） + - 分层合理性：整个架构的层级深度以3-7层为宜，过少则抽象不足，过多则过于复杂 + - 边密度适中：每个节点的平均连接数在2-4条比较健康，过多可能意味着职责不清 + -结构完整性： -- 所有代码文件都有对应节点（孤立文件 < 5%） -- 所有import都有对应边（遗漏依赖 = 0） -- 节点分层合理（3-7层为宜） -- 边密度适中（每节点平均2-4条边） - -可读性： -- 节点大小适中（width=250-300, height自适应） -- 文字清晰简洁（每个节点 < 150字） -- 颜色使用一致（同类组件同颜色） -- 布局整齐（同层Y坐标相近，X轴等间距） - -准确性： -- 节点描述与实际代码一致 -- 边的方向正确反映调用关系 -- 颜色编码符合组件角色 -- 坐标位置反映真实架构层次 - -维护性： -- 重大变更有注释（在节点text中标注版本） -- 历史版本可追溯（git管理.canvas文件） -- 定期清理过时节点（标记为灰色或删除） -- 复杂区域有子图拆分（如微服务拆分多个Canvas） + + - 节点尺寸适中：宽度内容自适应，高度根据内容自适应 + - 文字清晰简洁：每个节点的`text`描述根据内容自适应 + - 颜色使用一致：同类角色（例如所有Service）的组件必须使用同一种颜色 + - 布局整齐美观：同层级的节点Y坐标应大致对齐，X轴方向上间距均匀 + -高级协作模式： + 高级协作模式：发掘画布驱动开发的全部潜力 + + - 在画布上用不同颜色标注重构状态：绿=已完成，黄=正在进行，红=待办 + - AI可以根据颜色优先级，自动生成分阶段的重构计划和代码 + - 每次`commit`都对应着画布上部分节点颜色的变化，使进度可视化 + -模式1：渐进式重构 -- 在Canvas上用不同颜色标注：绿=已重构，黄=进行中，红=待重构 -- AI按颜色优先级生成重构计划 -- 每次commit更新节点颜色 + + - 将`architecture.canvas`文件纳入git管理，作为团队共享的、唯一的架构设计板 + - 每个开发者或小组负责的模块可以用专属的颜色或图标进行标记 + - 在开始一个新功能前，先在画布上创建节点“占位”，并标注负责人，以避免架构层面的冲突 + -模式2：多人协作 -- Canvas作为团队共享架构图 -- 每人负责的模块用专属颜色标记 -- 新增功能前在Canvas上"占位"避免冲突 + + - 为每个重要的产品版本（例如v1.0, v2.0）创建一个git tag，并保存当时的`architecture.canvas`快照 + - 可以通过`git diff v1.0 v2.0 -- architecture.canvas`来清晰地对比两个版本之间的架构演进 + -模式3：版本演进 -- 为每个大版本保存Canvas快照 -- 对比不同版本Canvas：git diff architecture.canvas -- 生成架构演进动画（可选工具） - -模式4：AI自主优化 -- 定期让AI分析Canvas："这个架构有什么问题？" -- AI建议：循环依赖、单点故障、性能瓶颈 -- 人类决策是否采纳，AI执行重构 - -模式5：跨项目复用 -- 建立Canvas模板库（Web后端/微服务/数据管道） -- 新项目直接导入模板Canvas -- AI根据模板生成项目脚手架 + + - 定期向AI提问：“请审查当前的架构画布，并找出潜在的设计问题。” + - AI会基于其内置的架构知识库，自动识别出循环依赖、“上帝对象”（God Object）、性能瓶颈等问题，并直接在画布上提出修改建议 + - 人类决策是否采纳建议，然后由AI执行具体的重构操作 + -Canvas丢失或损坏的应急方案： + 应急预案：处理画布丢失或损坏的情况 + + - 强制版本控制：`architecture.canvas`文件必须纳入git版本控制，并作为受保护的分支的一部分 + - 定期自动备份：配置CI/CD流程，每周自动将画布文件备份到云存储 + -预防措施： -- Canvas文件纳入git版本控制 -- 每周自动备份到云端 -- 重要节点手动导出JSON备份 - -恢复流程： -1. 尝试从git历史恢复 -2. 若git无记录，触发AI重新生成： - "紧急重建Canvas，扫描当前代码生成架构图" -3. AI在30秒内生成基础Canvas -4. 人类补充关键设计决策和注释 -5. 标记为"重建版本"并记录原因 - -降级方案： -- 若Canvas完全不可用，AI切换到传统模式（基于代码理解） -- 提示人类："Canvas不可用，建议尽快重建以恢复最佳协作效率" -- 生成临时的文本版架构树（Markdown格式）作为过渡 + + 1. 首选方案：尝试从git历史记录中恢复最近的健康版本 + 2. 次选方案：若git记录丢失，立即触发AI的紧急重建流程：“紧急重建画布，立即扫描当前代码库生成最新架构图” + 3. AI将在短时间内（例如30秒内）生成一份基础的、功能性的画布 + 4. 人类团队在此基础上，快速补充关键的设计决策、注释和分组信息 + 5. 将恢复后的画布标记为“重建版本”，并记录事故原因 + - -Canvas驱动开发的核心原则： - -1. Canvas First：架构变更先改Canvas，代码跟随 -2. 单一真相源：Canvas = 唯一权威架构文档 -3. 实时同步：代码与Canvas必须保持一致 -4. 人机共享：Canvas既是给人看的图，也是给AI读的数据 -5. 渐进演进：Canvas随项目成长持续更新，永不过时 -6. 可视优先：用图形表达的永远比文字清晰 -7. 零翻译成本：人类编辑Canvas = 直接指挥AI -8. 架构透明：任何人打开Canvas立刻理解系统全貌 - - diff --git a/i18n/zh/workflow/canvas-dev/workflow.md b/i18n/zh/workflow/canvas-dev/workflow.md new file mode 100644 index 0000000..b491f26 --- /dev/null +++ b/i18n/zh/workflow/canvas-dev/workflow.md @@ -0,0 +1,31 @@ +🚀 Canvas驱动开发法 - 完整工作流 + +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. 用白板驱动代码重构（架构调整场景）：在白板上删除/重连模块间的依赖线；标注需要拆分的大模块（如payment_service拆分为payment_processor和payment_validator）；发送修改后的白板给AI："按新架构重构代码，列出需要修改的文件清单" +/ +9. 用白板辅助Code Review：Review前先看白板全局架构；识别异常连线（如前端直接连数据库、循环依赖）；在白板上标注问题点；讨论时指着白板说明："这条调用链不应该存在" +/ +10. 用白板加速团队协作：新人入职时先看白板1分钟理解全局；需求评审时在白板上画出变更范围；技术方案会议投屏白板而非代码；会后将白板标注转化为开发任务 +/ +11. 维护白板与代码一致性：每次PR/MR合并前检查白板是否需要更新；定期运行自动校验脚本：对比白板JSON与实际代码依赖；发现不一致时优先修正白板（因为白板是事实来源） +/ +12. 扩展应用场景：接手遗留项目时先自动生成白板快速理解；性能优化时用白板标注热点路径；安全审计时检查白板上的敏感数据流向；API设计时画出服务间调用拓扑 +/ +13. 【缺口澄清】明确你的项目类型以优化流程：A) 单体应用（单进程多模块） B) 微服务架构（多服务RPC通信） C) 前后端分离（前端框架+后端API）？默认假设A继续 +/ +14. 【缺口澄清】选择白板粒度级别：A) 文件级（每个代码文件一个节点） B) 类/函数级（每个类一个节点） C) 服务级（仅显示大模块）？推荐新手选A，复杂项目选C +/ +15. 持续迭代工作流：每周回顾白板是否反映真实架构；收集团队反馈优化节点命名和布局规则；探索白板与CI/CD集成（如PR触发白板diff检查）；分享最佳实践案例到团队知识库 \ No newline at end of file