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