0. 先和大家打个招呼吧 
你是谁： 一名大二学生&独立开发者，平时需要画大量流程图、架构图、概念图来梳理思路、讲解方案、做技术分享，现有的 Mermaid 原生渲染网站不支持 Markdown/TeX 多语言支持，丰富度极其有限。
你是怎么用 TRAE 把 Demo 做出来的：
CodeGraph 整个项目是我和 TRAE「一句一句聊出来的」。最初脑子里只有一个模糊画面：输入一句话，出来一张可以拖、可以改、无限放大的矢量图。但怎么落地，完全没头绪。
我把这个大目标拆成小步讲给它听：
- 先让它帮我设计一套 DSL（领域特定语言）来描述节点、边、样式；
- 再让它接 dagre 布局引擎算出每个节点的坐标；
- 最后把 DSL + 布局结果渲染成 SVG，并套一个可拖拽、可缩放、可编辑的编辑器壳。
每一步它都先给出实现，我再根据真实体验指出哪里别扭。比如"拖节点的时候连线没跟着动"、“主题切换后缩放状态丢了”、“撤销 redo 把当前状态吃掉了”——它就一点点修，修到对。
最让我感到"原来这么简单"的瞬间有两个：
- 当我随口说"想让节点文字支持 Markdown 和 TeX 公式"时，TRAE 直接引入 marked.js + KaTeX，并设计了一套用
\转义、data-raw-text存原文的机制，一次跑通。这种原本以为要折腾一整天的功能，几轮对话就跨过去了。 - 撤销/重做的快照时机问题，我原本以为只能靠"操作后存快照"硬怼，结果 TRAE 主动提出
node-interaction-start事件 +dragSnapshotTaken标志位的方案——在交互开始前先存快照，拖拽中第一次 move 才 push。这种细节它考虑得比我还周到。
整个开发过程中，TRAE 不只是"代码生成器"，更像一个会反问、会建议、会踩刹车的搭档。它会提醒我"用 koa-connect 包装会泄漏 ctx，要换原生 Koa 中间件"；会在我把 Mermaid 引擎和 dagre 引擎双轨并行时，劝我合并成一条中转翻译链路。这些判断帮我避开了不少坑。
一、Demo 简介
1.1 作品是什么
CodeGraph 是一款纯前端的智能矢量绘图 Web 应用。用户只需用自然语言描述想要的图形内容（例如"绘制一个微服务架构图"、“画一张 MOF-74 催化流程图”），或粘贴一段 Mermaid 代码，系统即可自动生成对应的 SVG 矢量图形，并支持节点的拖拽、连线、缩放、旋转、富文本编辑、图层管理等可视化二次编辑。
它不是一款只能"看"的 AI 生图玩具，而是一套"生成 → 编辑 → 持久化"的完整工程链路。CodeGraph 的命名来源于 Code + Graph——用代码（DSL）描述图形结构，用矢量保证无限缩放与可编辑性，用自然语言降低上手门槛。
与传统画图工具相比，CodeGraph 试图回答一个核心问题：当一个人脑子里已经有图的画面，能不能跳过"找模板 → 拖控件 → 对齐 → 调样式"这一整套繁琐流程，直接让 AI 把脑中的画面落到一张可继续精修的矢量画布上？
1.2 面向谁
CodeGraph 面向的不是单一画像，而是一组真实存在、彼此共享同一种痛苦的人：
- 开发者和架构师 —— 需要快速产出系统架构图、调用时序图、服务依赖图，但又不想在 draw.io 里一格一格对齐；
- 产品经理和技术写作者 —— 写文档、写方案时需要配一张流程图，但 Visio 太重、ProcessOn 模板太死；
- 教师和讲师 —— 备课、讲课需要概念图、知识图谱，希望"说一句话就出图"；
- 学生和研究者 —— 整理思路、做汇报，希望画图这件事不要打断思考节奏；
- 任何"想画图但不想手动对齐"的人 —— 哪怕完全不会代码，只要能把图的内容描述出来，就能得到一张可继续改的矢量图。
这些画像背后有一个共同的痛点：画图工具的门槛，远远高于"想清楚要画什么"的门槛。 很多人不是不会画，而是被工具的复杂度劝退。CodeGraph 想做的，就是把这道门槛压到最低。
1.3 主要功能
CodeGraph 包含六大核心功能模块：
| 功能模块 | 核心能力 | 解决痛点 |
|---|---|---|
| 自然语言 / Mermaid 双输入 | 输入中文描述或粘贴 Mermaid 代码，AI 生成 SVG 矢量图 | 不会画图、不会 Mermaid 也能出图 |
| 所见即所得编辑器 | 节点拖拽、智能吸附（8px）、贝塞尔曲线连线、节点伸缩旋转、双击内联编辑 | AI 出图后还能继续精修 |
| 富文本与公式 | 节点文字支持 Markdown（加粗、代码、列表）和 TeX 公式（行内/块级） | 流程图里写不了公式和代码 |
| 图层管理 | 图层显隐、排序、删除、选中，支持图片图层 | 节点一多就乱，没法分层管理 |
| 工程能力 | 撤销/重做、复制/剪贴/粘贴、框选多选、手型平移、清空确认 | 真正能用、不只是 Demo 的工具 |
| 主题与工作区 | 日夜主题切换、工作区隔离、视觉回归测试基线 | 不同场景、不同项目互不干扰 |
1.4 产品形态与技术栈
| 维度 | 说明 |
|---|---|
| 形态 | 纯前端 Web 应用，浏览器直接访问，无需登录 |
| 渲染 | 原生 SVG 直接操作（非 Canvas、非双引擎），100% 可编辑、零像素噪点 |
| 布局 | dagre 有向图布局引擎（本地化 vendor） |
| 解析 | marked.js（Markdown）+ KaTeX（TeX 公式），均本地化 |
| 样式 | Tailwind CSS（CDN，预览环境回退内联） |
| 部署 | GitHub Pages + GitHub Actions 自动部署 |
| 数据 | DSL → Layout → AST 三层结构，可序列化保存/加载 |
【封面图 / 产品总览】
二、Demo 创作思路
2.1 灵感来源
灵感来自日常工作的真实痛点。我是一名学生，在专业学习期间，软件开发过程中经常要画图——给客户讲方案画架构图、给团队对齐画流程图、给自己整理思路画概念图，专业图表还需要对 TeX 公式进行支持。长期在三类工具之间反复切换：
- 拖拽式工具（draw.io、ProcessOn、Visio）：可控但累，光是对齐和连线就要花掉一半时间；
- 代码式工具（Mermaid、PlantUML）：快但死板，样式不可控，出图后无法局部微调，改一个节点要重写整段代码；
- AI 生图（Midjourney、DALL·E）：出的位图放大就糊，完全不可编辑，没法用在严肃文档里。
一直在想：能不能有一个工具，让我说一句话就出图，出来还能继续改，改完还是矢量？
这就是 CodeGraph 的起点。
2.2 想解决的问题
CodeGraph 针对的是一组真实存在、长期被忽视的痛点：
痛点一：画图工具的门槛高于思考的门槛。
很多人脑子里已经有图的画面，却被工具的复杂度劝退。draw.io 的控件库有上百个，Visio 的模板嵌套三层，光是"怎么开始"就让人放弃。
痛点二：AI 生图多是位图，不可编辑。
主流 AI 生图工具产出的是 PNG/JPG，放大就糊，改一个字要重新生成。严肃场景（文档、汇报、技术分享）需要的是矢量图——无限缩放、100% 可编辑、零像素噪点。
痛点三：代码式画图样式死板，无法局部微调。
Mermaid 这类工具虽然快，但出图后改不了。想加个图标、调个颜色、挪个节点位置？只能改代码重渲染，整张图重排。
痛点四：现有工具的"生成"和"编辑"是割裂的。
要么纯生成（AI 生图），要么纯编辑（拖拽工具），中间没有桥梁。用户在两边来回横跳，效率极低。
2.3 为什么做这个方向
判断一：矢量图天然适合"AI 生成 + 人工精修"的工作流。
矢量图本质是结构化数据（节点、边、坐标、样式），AI 擅长把自然语言转成结构，人擅长做局部微调。两者分工清晰，没有位图那种"生成即定型"的死结。
判断二：全程 SVG 直接操作，而非引入双引擎。
项目早期我曾同时维护 Mermaid 渲染引擎和 dagre 引擎，结果发现 Mermaid 不支持 Markdown/TeX、节点不可缩放、双引擎状态同步 bug 不断。最终决定彻底移除 Mermaid 引擎，改用"中转翻译"——Mermaid 代码先翻译成 DSL，再统一走 dagre 渲染。这样所有功能（富文本、缩放、旋转、编辑）只维护一套，工程量大幅下降。这个"砍掉一个引擎"的决定，是整个项目最关键的取舍。
判断三：选择 DSL → Layout → AST 三层架构，而非直接渲染。
很多人会觉得"AI 生成 SVG 字符串"就够了，但这样不可编辑——改一个节点要重新生成整段 SVG。CodeGraph 的三层架构让"生成"和"编辑"彻底解耦：DSL 描述结构，Layout 算坐标，AST 做序列化，任何一层都可以独立替换。这也是后来能顺利加撤销/重做、复制粘贴、图层管理的前提。
判断四：所有第三方库本地化到 vendor/ 目录。
TRAE 预览环境会拦截外部 CDN，一开始项目跑不起来。把 dagre、marked、KaTeX、Fabric.js、Resemble.js 全部本地化后，任何环境都能稳定运行。这个决定看似工程细节，但直接决定了 Demo 的可访问性。
【架构 / 创作思路图（由CodeGraph渲染）】
三、Demo 体验地址
CodeGraph 为纯静态部署，浏览器直接访问即可体验，无需登录、无需安装。
| 入口 | 地址 | 说明 |
|---|---|---|
| 展示页 | https://codegraph.shengxia.me | 项目介绍与亮点展示 |
| Demo 主应用 | CodeGraph Demo - 自然语言驱动的智能矢量绘图 | 完整可交互编辑器 |
| 源码仓库 | https://github.com/panda-lsy/CodeGraph | 全部代码开源 |
建议从 Demo 主应用进入，左侧输入框试试"绘制一个微服务架构图"或点"化学流程"示例按钮。
四、TRAE 实践过程
4.1 完整开发流程
CodeGraph 的开发并非一次性生成，而是通过多轮对话逐步迭代。整体流程如下：
第一步：需求拆解与架构设计
与 TRAE 对话梳理出"自然语言 → DSL → dagre 布局 → SVG 渲染 → 编辑器"的技术链路。TRAE 帮我判断出"直接生成 SVG 字符串不可编辑"这个坑，建议走三层架构。
第二步：DSL 与渲染层
用 TRAE 设计 DSL 结构（nodes、edges、style）、normalizeDSL 规范化、buildAST 序列化、renderResult 渲染函数族。这一层定下了"任何修改都走 DSL → Layout → 重渲染"的单一数据流。
第三步：编辑器核心
在 TRAE 协助下实现 svg-editor.js：节点拖拽、滚轮缩放、画布平移、智能吸附（8px 阈值）、动态扩展 viewBox（节点拖到边缘自动扩画布）。这是工程量最大的一块，也是后续所有交互的基础。
第四步：组件库
注册制组件系统，19 个组件跨 4 类（基础形状、流程图、容器、装饰），响应式网格展示（grid-cols-4 → sm:grid-cols-6 → md:grid-cols-8）。
第五步：富文本与图层
Markdown/TeX 渲染（marked.js + KaTeX）、浮动文字工具栏（字体 8 种、字号 10-32px、12 色调色板、自定义取色器、加粗斜体）、图层管理面板（显隐、排序、删除、选中）。
第六步：工程增强
撤销/重做（undoStack/redoStack + node-interaction-start 预快照）、框选多选（SVG rect 框 + 包围盒相交检测）、复制/剪贴/粘贴（剪贴板 + ID 重映射 + 偏移）、清空确认（自定义 cgConfirm 弹框）、手型/选择模式切换。
第七步：踩坑修复与重构
移除 Mermaid 引擎改用中转翻译、CDN 拦截改本地化 vendor、Koa 中间件 ctx 泄漏换原生、网格背景 pattern 引发 bug 改透明背景、"同步回 DSL"功能 bug 太多直接砍掉。
4.2 开发关键步骤截图
- 与 TRAE 对话设计 DSL 结构的截图
- svg-editor.js 节点拖拽 + 智能吸附实现过程截图
- 撤销/重做快照时机方案讨论截图
- 移除 Mermaid 引擎、改用中转翻译的决策截图
4.3 关键任务对话 Session ID
| Session ID | 对应任务 |
|---|---|
2637057080702148:e4741269eae5b48f532f9a96b495d0c0_6a4cebb2bc45846481030aae.6a4d43c8c8e366cbff5a80cd.6a4d43c8c8e366cbff5a80cb:TRAE Work CN.0.1.30.no_sid.no_ppe.T(2026/7/8 02:22:00) |
Mermaid 编辑器 5 大问题修复 + 富文本渲染 + 图层管理 + 移除 Mermaid 引擎改中转翻译（核心功能迭代） |
2637057080702148:3f8490d7229dae7aa3ca7899bd77420a_6a4cebb2bc45846481030aae.6a4ced02bc45846481030ad4.6a4ced02bc45846481030ad2:TRAE Work CN.0.1.30.no_sid.no_ppe.T(2026/7/7 20:11:46) |
DSL / dagre 渲染层搭建 |
2637057080702148:06332dadce9a63f1be2539981e77eb08_6a4cebb2bc45846481030aae.6a4d084cbc45846481030d58.6a4d084cbc45846481030d56:TRAE Work CN.0.1.30.no_sid.no_ppe.T(2026/7/7 22:08:12) |
svg-editor 编辑器核心实现（拖拽、缩放、吸附） |
五、对应的报名审核通过的帖子链接
【学习工作赛道】CodeGraph - 自然语言驱动的智能矢量绘图助手 - TRAE AI 创造力大赛 / 【大赛报名专区】 - TRAE 官方中文社区
六、经验总结与踩坑复盘
6.1 最大的坑：双引擎并行的诱惑与代价
项目早期我同时维护了 Mermaid 渲染引擎和 dagre 引擎，理由是"Mermaid 用户多，要兼容"。结果维护成本爆炸：Mermaid 不支持 Markdown/TeX、节点不可缩放、两套引擎的状态同步 bug 不断。最终在 TRAE 的建议下彻底移除 Mermaid 引擎，改用"Mermaid 代码 → mermaidToDSL() → dagre 渲染"的中转翻译链路。这个"砍掉一个引擎"的决定，让后续所有功能（富文本、缩放、旋转、编辑）只维护一套，是整个项目最关键的取舍。
6.2 撤销/重做的快照时机
最初 pushHistory 放在操作完成后（onNodeDrag、node-resized、node-rotated），结果 undo 把当前状态也吃掉了，等于无效。TRAE 帮我设计出 node-interaction-start 事件方案：编辑器在 resize/rotate 开始前 dispatch 这个事件，demo 监听后立即 pushHistory；拖拽则用 dragSnapshotTaken 标志位，在第一次 node-moved 事件时 push（此时坐标还没改）。这样 undo 才能真正回到操作前状态。
6.3 预览环境的 CDN 拦截
TRAE 预览环境会拦截外部 CDN，一开始项目在预览里跑不起来。把 dagre、marked、KaTeX、Fabric.js、Resemble.js 全部下载到 vendor/ 目录后，任何环境都能稳定运行。这个看似是工程细节，但直接决定了 Demo 的可访问性——评审点开链接就能用，不会卡在白屏。
6.4 "同步回 DSL"功能的诱惑
曾经实现过"编辑 SVG 后同步回 DSL"的功能，结果 bug 太多——用户拖了一下节点，DSL 被重写，下次渲染整张图重排，体验崩坏。最终决定砍掉这个功能，改为"直接编辑 SVG，DSL 只在生成时写入，之后只读"。这个决定让数据流变成单向，bug 量大幅下降。有时候"少做"比"多做"更难。
6.5 和 TRAE 协作的体感
TRAE 不只是代码生成器，更像一个会反问、会建议、会踩刹车的搭档。它的价值体现在三个时刻：
- 我说不清要什么时，它会先给一个实现，我再根据真实体验指出别扭的地方，它再修；
- 我方向错了时，它会主动提醒（如 koa-connect 会泄漏 ctx、双引擎维护成本高）；
- 我忽略细节时，它会补全（如撤销快照时机、viewBox 保留、CDN 本地化）。
这种协作模式让我这个独立开发者不再"一个人扛所有决策"，效率提升非常明显。
