最近在深入探究 GLSL，每次想写一段 shader 看下效果，都要新开一个 HTML、写 <script> 标签、配 <canvas>、引入threejs包、起本地服务、改完刷新看效果 —— 即便有 AI 加持，这一套流程的心智负担还是太重了。我其实只是想验证一些变换公式，查看顶点变换或颜色变化等效果，而不是搭一个项目。

试了一圈现成的在线 GLSL playground，要么功能停在能跑就行，要么稍微改点代码就出 bug，再要么就是必须登录或者收费的复杂产品。于是决定自己撸一个 playground —— ShaderPad

目标：

• 「打开浏览器 30 秒内跑起一个 shader」：零登录、零配置、零下载，面向 Web 着色器学习和调试的极简 playground
• 支持分享和快速复现3d场景
• 提供可快速插入 mdx 文本里的 npm 包

在线体验 ，对应的 github 仓库

整体效果​

整体页面结构跟大部分在线编辑器类似，左边是代码编辑区，提供了顶点着色器和片元着色器的编辑功能，会高亮 glsl 语法。右边是基于 threejs 的3d场景，实时预览当前编辑的代码的效果，并且提供了悬浮的控制台面板，方便查看一些报错或log

为了方便观察，3d场景内置了辅助网格和辅助坐标轴，并且引入了 OrbitControls，用户可以通过鼠标旋转场景，查看不同的角度

技术栈​

为什么选 Astro？​

做 ShaderPad 之前我其实没怎么用过 Astro。这次之所以选它，是被它的「默认零 JS」设计打动了。它并非基于 React 构建，而是允许你通过 integrations 把 React / Vue / Svelte 等当作「岛屿」嵌入到静态 HTML 中。

对比 Gatsby、Docusaurus 或 Next.js 这些默认把整个 React 运行时推到浏览器的重型方案，Astro 显得非常克制。在「孤岛架构」下，它把整个页面当成一片静态海洋，里面散落着几个交互小岛。对 ShaderPad 来说，文档内容就是静态海面，只有 Playground 这个组件才是真正的交互孤岛。

底层原理上的优势：

1. 极致的编译时剥离：Astro 的渲染模式是 SSG。在 build 时它会把 .astro 组件全跑一遍，暴力剥离掉所有不需要在客户端执行的 JS 逻辑，只输出纯 HTML。
2. 精准的按需水合：因为 Playground 强依赖 WebGL（完全没法在 Node 端执行），我给它加了 client:only="react" 指令。Astro 遇到它时，只会在 HTML 里留个带有 astro-island 标签的占位 DOM，并注入极轻量的调度器（几 KB）。等页面加载完，调度器才会去拉取 React 运行时和组件代码，在客户端完成「水合」。

落到实际产物上：构建出来的文档站 index 页面只有 6.84 kB（Gzip 后 2.73 kB），大头全在按需加载的 Playground 孤岛里（约 500+ kB）。这种「主静态、副交互」的颗粒度控制，完美契合了重客户端工具的需求，彻底甩掉了全站 React 渲染的性能包袱。这也是为什么 Astro 在「文档站 + 工具型网站」场景下越来越受欢迎的原因——它把"该省的省到极致"这件事做得很彻底。

架构设计​

Monorepo 结构​

monorepo 算是现在多仓管理的标配。它不光能在一个仓库里管多个 package，更像是在逼我面对一个问题："如果这个项目要嵌进别人的网页里，边界该画在哪？"。所以从一开始我就带着 SDK 视角在搭：核心引擎、UI 组件、样式层各管一摊，公共部分一律上提到 packages/，主站只负责壳子和体验。

• @shaderpad/runtime 抽离出 LanguageAdapter 接口（GLSL 轻量语法预检），未来扩展到 Node / Tauri 桌面端可直接复用。
• @lucascv/shaderpad-playground 把 Playground 抽成独立 npm 包，独立发版、可嵌入到任何 React 文档站。
• apps/web 主站保持轻量，作为包的消费者，部署产物也更加干净。

shaderPad/
├── apps/
│   └── web/                        # 主站（Astro）
│       ├── src/
│       │   ├── pages/              # 路由（index / play / learn/*）
│       │   ├── components/         # React 组件
│       │   ├── lib/
│       │   │   ├── runtime/        # 浏览器侧渲染引擎
│       │   │   └── share/          # URL/localStorage 持久化
│       │   └── shaders/examples.ts # 内置示例库
│       └── astro.config.mjs
├── packages/
│   ├── shader-runtime/             # 跨端共享核心（未来扩展桌面端）
│   │   └── src/languages/          # GLSL / TSL / WGSL adapter
│   └── shader-playground/          # 可独立发版的 npm 包
│       ├── src/
│       │   ├── runtime/three-engine.ts
│       │   ├── ui/                 # ShaderPlayground / CodeEditor / PreviewCanvas
│       │   └── styles/playground.css
│       └── tsup.config.ts
└── .github/workflows/
    ├── deploy-web.yml              # 主站部署
    └── release.yml                 # npm 自动发版（OIDC）

数据流​

[Monaco Editor]  --change-->  Playground state (codeRef)
                              |
                              |--auto save (1s debounce)--> localStorage
                              |
                              '--compileAndRun()--> [ShaderEngine]
                                                            |
                                                  +---------+---------+
                                                  |                  |
                                            (vertex/fragment)  (uniforms)
                                                  |                  |
                                                  v                  v
                                            Three.js RawShaderMaterial  <--  OrbitControls / Grid / Axes

核心渲染模块​

ShaderEngine（运行时核心）​

要让代码在网页上跑起来，必须有一套稳定、高效的渲染器。我封装了 ShaderEngine 这个核心类来处理 Three.js 的脏活累活。

它不仅是对 WebGLRenderer 的简单包装，更重要的是它接管了渲染的生命周期与错误捕获，对外只暴露最极简的 API：

class ShaderEngine {
  init()                        // 创建 WebGLRenderer + 透视相机 + 辅助坐标系
  applyShader(source, mode)     // 将用户的源码注入 RawShaderMaterial
  forceCompile()                // 绕过 Three.js 顶层，直接调用 WebGL API 预编译并捕获行号
  setGeometry(type)             // 无缝切换几何体（复用 Material，不闪烁）
  start() / stop() / dispose()  // 挂载 RAF 动画循环，并确保销毁时不漏内存
}

内置模块​

提供了以下几种 threejs 常见的几何体：

• PlaneGeometry 平面
• BoxGeometry 立方体
• SphereGeometry 球体

默认是 PlaneGeometry，用户可以自行切换。针对不同几何体提供了几种不同的常见 shader 示例，比如时间渐变、鼠标跟随、噪声效果等，选中后就可以查看效果，用户可以根据需要选择。

另外比较关键的是，我还内置了一些开发中常见的 uniform 变量，如下：

uniform float u_time;       // 自启动以来的秒数，每帧递增
uniform vec2  u_resolution; // 画布宽高（像素）
uniform vec2  u_mouse;      // 鼠标位置，归一化到 [0,1]（Y 已翻转）
uniform float u_random;     // applyShader 时的随机数 [0,1)

这样就可以在 shader 中直接使用这些变量来做一些动态效果。

当然目前没法完全自定义 uniform，暂时是逐步加入一些常见变量，有需求的可以评论或者追加 github issue

为什么用 RawShaderMaterial？​

在实现 ShaderEngine 时，我面临一个取舍：用 ShaderMaterial 还是 RawShaderMaterial？

ShaderMaterial 很方便，它会自动帮你注入一堆 Three.js 内置的 uniforms 和 attributes（比如 cameraPosition、modelViewMatrix 等）。但在「教学和调试」场景下，这反而成了致命缺点——用户会很困惑：「我明明没声明这个变量，为什么它能跑？」

为了做到「所见即所得」，我最终选择了 RawShaderMaterial。它是一张白纸，不注入任何隐藏代码，用户写的 source 就是最终跑在 GPU 里的 GLSL。 这也意味着报错行号能做到 1:1 绝对对应，不会出现「明明只有 10 行代码，控制台却报第 150 行错误」的灵异事件。代价是用户必须在代码开头显式声明所需的内置矩阵：

attribute vec3 position;
attribute vec2 uv;
uniform mat4 projectionMatrix;
uniform mat4 viewMatrix;
uniform mat4 modelMatrix;

但这换来的是运行机制的完全透明，对于一个学习工具来说，这个权衡是非常值得的。

编译错误的精确定位​

Three.js 编译失败的报错信息默认是「WebGL: ERROR: 0:5: 'foo' : undeclared identifier」这种字符串，没法结构化处理。Playground 在 ShaderEngine 里直接绕过 Three.js 的封装，调底层 gl.getShaderInfoLog + gl.getShaderSource 自己解析，把行号 / 列号 / 错误消息拆成结构体再浮条展示：

{ line: 5, column: 12, message: "'foo' : undeclared identifier" }

这样写 GLSL 时，看到的都是真实可定位的错误，而不是"WebGL: ERROR: 0:5"这种天书。

模块沉淀：从单一工具到通用的 npm 包​

做完主站后我意识到——「实时编辑 + 实时预览」这套交互本身非常有价值，它不应该只局限在 ShaderPad 自己的网站里。如果能在任何 MDX 文档或技术博客里直接嵌入一个能跑的 Shader，阅读体验会呈指数级上升。

比如现在你可以直接修改下面的代码，实时查看效果（试试把 cos 改成 sin，或者调一下 vec3(0, 2, 4) 的颜色偏移）：

于是我把 Playground 抽成了一个独立的 npm 包：@lucascv/shaderpad-playground，5 行代码就能嵌进任何 React 文档站。

pnpm add @lucascv/shaderpad-playground react three monaco-editor @monaco-editor/react

import { ShaderPlayground } from "@lucascv/shaderpad-playground";
import "@lucascv/shaderpad-playground/styles";

<ShaderPlayground
  code="void main() { gl_FragColor = vec4(1.0, 0.0, 0.0, 1.0); }"
  storageKey="my-article/hello"
/>;

Live Demo：shaderpad.lucaslib.net/embed-test ｜ npm：@lucascv/shaderpad-playground

封装过程踩到几个值得记一笔的点：

为什么必须是 MDX（前提中的前提）​

这事能成立，关键在 MDX 这个东西本身。普通 Markdown 只能写文字 + 代码块，碰到 <ShaderPlayground /> 这种 JSX 直接懵——<div> 都识别不了，更别说塞交互组件。

MDX（Markdown + JSX）就是为这个问题生的：它扩展了 Markdown 语法，允许在文档里直接写 React 组件。原理不复杂——编译期用 @mdx-js/mdx 这类工具把 .mdx 文件解析成 React 树：Markdown 部分走 remark 管线出 React 元素，JSX 部分原样透传，最后合成一棵完整的组件树渲染。

而且目前主流文档框架几乎都原生支持 MDX：Docusaurus（你正在看的这个博客就是）、Astro、Nextra、VitePress 都是开箱即用，不用额外搭脚手架。如果你的博客 / 文档站已经在用这些技术栈，零迁移成本就能接入——这点很关键，意味着 Playground 的受众不是只有 React 重度用户，而是几乎所有写技术文档的人。

这套机制让「散文 + 代码块 + 实时 demo」在同一个文件里无缝混排。其他路线都做不到这种程度：

• iframe 嵌外部 playground：样式割裂、跨域通信麻烦、宿主主题融不进去
• 截图 + 跳 CodePen / ShaderToy：读者被迫跳出当前阅读流
• 录视频：完全丧失可编辑性，等于把核心价值阉了

MDX 路线能让交互组件和正文真正长在一起

持久化代码​

用户编辑过的代码要保留下来（下次打开还是他改过的版本），但如果作者改了文章的示例代码，旧草稿就会"幽灵生效"——看起来加载了，但内容是上一版的。

包里的做法是把源文件内容用 djb2 算一个短 hash，写进 localStorage key 里：

// v2 key 格式：embed-test/pair-box:a3f9b1c2
function buildKey(storageKey, source) {
  return `${storageKey}:${shortHash(source)}`;
}

源文件一变 hash 就变，自动生成新 key，旧草稿自然绕过。这套机制上线后，文档示例库再迭代也没出过"代码不匹配"的玄学问题。

单 / 双着色器配置​

最简的用法是只传一个 code 字段，跑单 stage。但有些场景（顶点动画、varying 传递）必须 vertex + fragment 联动才能跑起来，所以包内同时提供了 pair 配置：

<ShaderPlayground
  pair={{
    vertex: `void main() { gl_Position = vec4(position, 1.0); }`,
    fragment: `void main() { gl_FragColor = vec4(1.0, 0.0, 0.0, 1.0); }`,
  }}
  storageKey="docs/glsl/coords"
/>

传 pair 时画布会自动切到 Vertex / Fragment 双 tab，编辑器用单一实例、两边各自一份代码，互不打架。

组件包打包​

为什么选 tsup？ESM/CJS 格式怎么控？

在抽离 @lucascv/shaderpad-playground 这个独立的 npm 包时，我需要一个打包工具。之所以选 tsup，是因为它底层基于 esbuild，打包速度极快，而且开箱即用支持 .d.ts 类型生成。对于这种不用配复杂 Webpack loader 的纯 TS/React UI 组件库来说，体验简直是降维打击。

但我在这里踩了一个经典的 ESM/CJS 双格式导出的坑。

一开始打包后，Astro 主站引入组件时报了页面水合（Hydration）失败的 SyntaxError。排查后发现，是因为包的 package.json 声明了 "type": "module"，导致宿主在解析依赖时，拿到了格式不匹配的产物。

为了同时完美支持现代框架（需要 ESM 以支持 Tree-shaking）和类似 Docusaurus 2.x 这种可能依赖旧版 Webpack 设定的工具（需要 CJS），必须在 tsup.config.ts 里手动接管输出扩展名：

export default defineConfig({
  format: ["esm", "cjs"],
  outExtension({ format }) {
    // 强制把 ESM 产物后缀设为 .js（因为 type: module），CJS 产物后缀设为 .cjs
    return { js: format === "cjs" ? ".cjs" : ".js" };
  },
});

同时，package.json 里的 exports 字段必须严丝合缝地对齐：

"exports": {
  ".": {
    "types": "./dist/index.d.ts",
    "import": "./dist/index.js",     // ESM 消费者走这里
    "require": "./dist/index.cjs"    // CJS 消费者走这里
  }
}

只有当这两边绝对对齐，各种宿主框架在根据自身环境 import 或 require 时，才能精准命中正确的模块，彻底消灭 Hydration 报错。

几个工程取舍​

• CSS 变量全用 spg- 前缀：颜色 / 边框 / 强调色全部走 CSS 变量，主题跟随 documentElement[data-theme]，和宿主站主题自然融合，不会突兀地"白底黑字"。
• 响应式断点 720px：宽屏左右分屏（编辑器 + 画布），窄屏自动堆叠成上下结构，手机也能直接看效果。
• React 17 / 18 / 19 全兼容：react / react-dom / three / monaco-editor 全是 peerDependencies，不打包进 dist，包体核心 ~66KB（gzip），按需由消费方装。本网站基于 Docusaurus 2.4 + React 17 这个老古董环境，也都支持集成。

URL 分享功能​

作为一个在线调试工具，如果不做后端数据库，怎么分享代码？

这里的方案是：把整个 Shader 源码通过 LZString 压缩 + Base64 编码后，直接塞进 URL 的 hash 路由参数里。可以在 ShaderPad 右上角点击 share，然后新打开标签页粘贴体验

为什么是这套组合​

https://shaderpad.lucaslib.net/?a=1&b=2#/playground?code=xxx
                          └── query ──┘  └────── hash ──────┘

整段 URL 只有 hash 留在客户端，query 和 path 都会被发到服务器——意味着要后端配合、还要防日志和 CDN 污染。改 hash 不触发 HTTP 请求，对「无后端 + 静态部署」是天然选择。

• LZString 压缩。 GLSL 天然高冗余，关键字和模板片段反复出现。LZString 是为「短字符串 + URL」场景设计的，输出本身就是 string，压缩比通常 3~5x。
• Base64 兜底「URL 安全」。 压缩后的字节流是二进制，里面可能混着控制字符。Base64 把任意字节映射到 64 个 URL-safe 字符，~33% 的体积代价被上一层的压缩比覆盖。

浏览器对 URL 长度有隐性上限（实测 Chrome 大概在 8KB～32KB 之间），代码长了会被截断。所以分享出去的链接天然适合"短小精悍的示例"——这其实和调试场景挺契合的，单文件 shader 本来就不该太长。

这样任何人拿到链接，打开就能直接还原当前的编辑状态，完全不需要后端的介入，真正做到了「无状态」的极简分享。

部署​

刚好最近换了台新服务器，ShaderPad 就作为第一个部署的应用上线了。关于新服务器配置环境，还专门写了一篇文章 《linux个人云服务器开荒指南》

顺便吐槽一句某某云：旧那台 1 核 2G 的云服务器续费依旧贵得离谱，反而新买一台 2 核 4G 首年还有大折扣，算下来差不多。旧机器上也没跑几个应用，迁移成本不高，索性换台配置高一点的。

部署的核心组件是 Nginx Proxy Manager（下文简称 NPM，注意和 Node 的 npm 不是一回事）。

Nginx Proxy Manager​

NPM 是一个基于 Nginx 的可视化反向代理管理工具，包装成 Docker 镜像后一行命令就能起，很香。

• 提供 Web 管理界面，不用手写 nginx.conf、不用 nginx -s reload
• SSL 证书申请 + 部署一条龙（Let's Encrypt 自动化），告别以前去某某云控制台手动申请再 vim nginx.conf 的繁琐

端口规划（默认会占三个，记得在某某云防火墙里放行规则）：

自动化部署​

走 GitHub Actions + rsync：

• push 到 main → 触发 .github/workflows/deploy-web.yml
• 跑 pnpm install + pnpm --filter web build，产物在 apps/web/dist/
• rsync-deployments action 把 dist/ 推到服务器的 /var/www/shaderpad/dist/（与 NPM 静态资源目录保持一致）

踩过的坑​

Nginx 与 CI 环境的琐碎坑点​

• Nginx 500 错误：启动 NPM 容器的时候没正确挂载宿主机的静态资源目录（如 /home），导致 Nginx 找不到文件，修改 docker-compose.yml 补上 volumes 映射即可。
• pnpm@10 lockfile 冲突：GitHub Actions CI 环境默认拉了最新的 pnpm v10，解析项目 v8 的 pnpm-lock.yaml 时报 ERR_PNPM_LOCKFILE_BREAKING_CHANGE 错误。解决方案是在 CI 步骤里明确指定安装 pnpm@8.11.0 版本。

总结与思考​

以前我一直想做个在线工具，但总觉得市面上轮子已经够多了，加上开发和部署成本，迟迟没有动手。这次在 AI 的加持下（核心代码大量借助了 Minimax-M3 等大模型），极大地压缩了「从想法到上线」的周期。

ShaderPad 不仅让我调试和学习 glsl 代码更方便，也让我跑通了从「单体应用开发」到「通用组件抽离」，再到「自动化发版部署」的完整工程化闭环。

第一版先保持极简，后续如果大家觉得好用，会考虑扩展对 TSL 和 WGSL 的支持。欢迎来玩！

在线体验地址：ShaderPad ，对应 github 仓库

其实我的需求很简单。原先自己的知识库网站基于 Algolia 的纯文本检索有点落后了，于是想接入 AI 问答，可以同时检索多处内容并做对话式的总结，而不是简单的返回带有文本字符串的文章列表。（Algolia 后面推出了 NeuralSearch，不过得额外开启还要付费）。

作为前端，我一直想找个切入点探索 AI Agent 相关技术，而给自己的知识库接入基于 RAG（检索增强生成）的 AI 问答，无疑是跑通 Prompt 工程和 RAG 技术最好的练手项目。

怎么交互呢？因为原先 Algolia 的检索窗口在右上角，所以我直接在旁边加上 AI 问答按钮，触发对话窗口。效果如下：

点击本网站右上角【Ask AI】就可以体验

这有点像客服助手——说起来，客服助手可以算是入门 AI Agent 最好的项目了，根据问题设计多种回复 Prompt，通过 Function Calling 调用 API 方法或查询数据库，我刚开始练手就是搞了一个客服助手，熟悉了 AI Agent 的基本体系。

接下来，我需要一个轻量的后端服务来实现 RAG 服务接口，对接向量数据库。

整体设计与技术选型​

做全栈开发，第一步是定技术栈。我的核心诉求是轻量、低成本、免运维：

• 前端：docusaurus (SSG)。博客原有的基建，负责展示和发起问答。
• 后端：hono。没有选 Express，Hono 是一个极度轻量的 Web 框架 (12-15kb)，原生支持 Web Standard API，不仅能在 Node.js 跑，还能跨运行时支持 Bun/Deno。API 风格跟 Express 很接近，这次主要是尝鲜，服务也不复杂，就用 Hono 来实现。
• 向量数据库：chroma db。这是一个轻量的向量数据库，基于 SQLite（文件型存储），Node.js 也能快速接入。我的知识库属于个人场景，单用户访问，不需要分布式高 QPS。关于向量，可以先记住这句话：语义相近的文本，向量在空间中的距离就小。
• 大模型：deepseek-v3。这种场景只是简单的总结和问答，不需要复杂的模型，性价比极高。
• 向量模型：阿里的 text-embedding-3。中文支持好，费用低。

关键工程问题​

下面这几个模块，刚好按 RAG 的数据流转顺序铺开：离线数据生产（切片 -> 灌库） -> 在线服务接口（Prompt 拼接 -> LLM 流式透传） -> 前端展示（流式渲染）。

1. 文档切片 (Chunking)​

切片策略：根据标题栏和段落，按语义切分文本。

我们需要将 Docusaurus 项目中 docs/ 和 blog/ 目录下的所有 Markdown (.md/.mdx) 文档提取出来，进行合理的切片处理，以便后续进行向量化 (Embedding)。 因为 Markdown 本身就是结构化的，H1/H2/H3 天然是语义边界，切出来的每片都是一个完整的小主题，直接喂给 embedding 模型。每个切片必须保留路由信息 (sourceUrl)，以便于前端问答时回显来源链接。

这里使用了几个库来协助处理：

• unified + remark-parse：用于解析 Markdown 生成 AST（抽象语法树）。如果不这么做，只能正则匹配 #，碰到代码块里的 # 就误判。
• remark-frontmatter：用于识别并提取文件头部的 YAML 属性（如 title/tags）。切片丢了标题，回显时无法显示"这是哪篇文档"。
• mdast-util-to-string：用于将 AST 节点转回纯文本进行分析。因为经过上述处理后拿到的还是带结构的对象，没法直接喂给 embedding。

整个 pipeline：

.md 源文件
  → unified + remark-parse：解析成 AST（树状结构）
  → remark-frontmatter：把头部的 YAML 抽出来作为 metadata
  → 遍历 AST 找 H2/H3 节点作为切片锚点
  → mdast-util-to-string：把切片节点的文本内容转成纯文本
  → 输出：{ sourceUrl, title, content, ...metadata }

为什么不一步到位？Markdown 看似简单，其实头部的 YAML、代码块、链接、图片都是「结构化信息」，得先把它们都识别出来，才能精准地切、按层级地切、不破坏语境地切。

注意：只切到 H2/H3 比较合适，再细就碎了；遇到特别长的章节，可以按段落再细分。

可以配置 package.json 的 scripts 命令，这样在 GitHub Workflow 流程里就能执行脚本触发文档切片，并自动上传向量数据库：

"scripts": {
    "rag:parse": "tsx scripts/rag/test-parser.ts"
}

2. 文本向量化与增量灌库​

借助 text-embedding-3 模型，把切好的文本转成向量表示（就是把「文字」转成「坐标」，后续在向量空间里找距离最近的那几个）。

存到 ChromaDB 时有几个细节：

• 向量维度：text-embedding-3 默认输出 1024 维，每片文本对应一个 1024 维的浮点数数组。
• 元数据一起存：除了向量，把原文、文档路径、章节标题作为 metadata 一起入库，召回时靠 metadata 做过滤和展示。

切完的真实数据格式如下：

{
  "content": "[文档路径: /docs/afreshjs/Node.js/高级核心概念 | 章节: 高级核心概念 > 高级核心概念 > 3. 模块化的底层原理 (CJS vs ESM) > 3.2 循环引用 (Circular Dependency)]\n### 3.2 循环引用 (Circular Dependency)\n\n当 `a.js` 引用 `b.js`，同时 `b.js` 又引用 `a.js` 时：\n\n- **CommonJS 的表现**：\n  CJS 在加载模块时，会优先在 `require.cache` 中创建该模块的空对象 `module.exports`。当发生循环引用时，`b.js` 会拿到 `a.js` **还没执行完的、不完整的 `exports` 对象**。这会导致运行时拿到 `undefined` 而报错。\n  _(CJS 导出的是值的拷贝/浅拷贝)_\n\n- **ESM (ECMAScript Modules) 的表现**：\n  ESM 的加载分为“解析”、“实例化”、“执行”三个阶段。ESM 导出的是**实时绑定 (Live Bindings)**，即导出的变量和原模块内部的变量指向同一块内存地址。\n  因此在处理循环引用时，只要你不立刻去读取那个还没初始化的变量，引擎就能完美处理好模块的依赖图谱。\n\n---",
  "metadata": {
    "sourceUrl": "/docs/afreshjs/Node.js/高级核心概念",
    "title": "高级核心概念",
    "h1": "高级核心概念",
    "h2": "3. 模块化的底层原理 (CJS vs ESM)",
    "h3": "3.2 循环引用 (Circular Dependency)",
    "chunkIndex": 5
  }
}

增量灌库​

第一次全量灌库时有个小插曲：接口携带的数据太大，导致 Nginx 报了 body 体积过大的异常 (413)。除了调整 Nginx 阈值 (client_max_body_size)，稳妥起见还用了多个接口分批上传，避免触发接口超时 (504)。

后续更新采用增量灌库：基于 Git Diff 仅对变更文件重新 Embedding，避免每次修改知识库都要全量上传。这部分逻辑写在 GitHub Actions 中。

ChromaDB 的 API 设计非常契合这种场景，底层 HNSW 索引是自维护的，不用手动 rebuild：

// 新增
await collection.add({ ids, documents, embeddings, metadatas });
// 有则更新、无则新增（按 id）—— 灌库最常用
await collection.upsert({ ids, documents, embeddings, metadatas });
// 更新已有（不存在会报错）
await collection.update({ ids, embeddings, metadatas });
// 删除
await collection.delete({ ids: [...] });

3. Prompt 设计​

针对 AI 问答的回复，我设计了如下 Prompt，严格限制 AI 的行为，避免幻觉：

# 角色

你是一个知识库助手，只能基于「参考文档」回答用户问题，不要编造。

# 回答要求

1. 先用 1-2 句话直接回答用户问题
2. 再补充关键细节（来自参考文档）
3. 最后列出引用来源（仅列文档名 + 章节，不要贴 URL 长链接）
4. 如果参考文档不足以回答，明确说"知识库没有相关内容"

# 参考文档

${retrieved_chunks}

# 用户问题

${user_query}

4. 流式问答 (SSE) 与 Nginx 代理坑点​

这就是 SSE 的典型应用场景：用户输入问题，后端检索数据库将最相关的数据喂给模型，然后将模型返回的结果处理成一个流式响应，前端实时接收并展示给用户（打字机效果）。

开启 SSE 接口，三件事缺一不可：响应头 + 后端实现 + Nginx 反代配置。

1. 响应头

content-type: text/event-stream
cache-control: no-cache          # 防止中间代理缓存
connection: keep-alive           # 保持长连接
x-accel-buffering: no            # 告诉 Nginx 不要缓冲（关键）

2. 后端实现 (Hono) 用 hono/streaming 的 streamSSE（把后端响应包成 SSE 格式 data: ...\n\n），上游 stream: true 让 DeepSeek 边想边吐，核心是「透传上游流」：

import { Hono } from "hono";
import { streamSSE } from "hono/streaming";

const app = new Hono();

app.get("/rag-api/ask", async (c) => {
  return streamSSE(c, async (stream) => {
    // 1. 请求上游 LLM，开启流式
    const upstream = await fetch("https://api.deepseek.com/chat/completions", {
      method: "POST",
      headers: {
        /* ... */
      },
      body: JSON.stringify({ /* ... */ stream: true }),
    });

    if (!upstream.body) return;

    // 2. 透传上游流：read → 解析 → writeSSE
    const reader = upstream.body.getReader();
    const decoder = new TextDecoder();
    let buffer = "";

    // 监听客户端断开，清理上游（不浪费 token）
    stream.onAbort(async () => {
      await reader.cancel();
    });

    while (true) {
      const { done, value } = await reader.read();
      if (done) break;

      buffer += decoder.decode(value, { stream: true });
      const lines = buffer.split("\n");
      buffer = lines.pop() || ""; // 最后一行可能不完整，留到下轮

      for (const line of lines) {
        if (!line.startsWith("data: ")) continue;
        const data = line.slice(6).trim();
        if (data === "[DONE]") {
          await stream.writeSSE({ data: "[DONE]" });
          continue;
        }
        try {
          const json = JSON.parse(data);
          const content = json.choices[0]?.delta?.content || "";
          if (content)
            await stream.writeSSE({ data: JSON.stringify({ content }) });
        } catch (e) {
          console.error("SSE 解析错误:", e);
        }
      }
    }
  });
});

3. Nginx 反代必须关缓冲（最常踩的坑） Nginx 默认会缓冲响应，SSE 会被"卡住"看不到流，等缓冲满了才一次性吐出来。必须加：

location /rag-api/ {
    proxy_pass http://127.0.0.1:3000/;
    proxy_buffering off;          # 关键！禁用缓冲
    proxy_cache off;              # 禁用缓存
    proxy_http_version 1.1;       # SSE 需要 HTTP/1.1
    chunked_transfer_encoding on;
    proxy_read_timeout 60s;       # 防止超时断流
}

总结下易踩的坑：

为啥要用 @microsoft/fetch-event-source 这个库来做前端 SSE 请求？

• 原生 EventSource 只支持 GET 请求，header 也不能自定义（传个 token 都麻烦）。
• fetch + getReader() 在微信内置浏览器（X5/WKWebView）会拿到 null 直接抛异常。

这个库底层用 fetch 发请求，支持 POST 和自定义 Header，内部封装了 ReadableStream 兼容处理，业务代码只关心 onmessage 回调即可。

总结下上述流程：

DeepSeek API (ReadableStream)
    │ raw bytes (SSE 格式: data: {...}\n\n)
    ▼
getReader() 异步迭代
    │
    ▼
TextDecoder → buffer 累积 → 按 \n 切行
    │
    ▼
JSON.parse → 提取 content
    │
    ▼
writeSSE({ data: JSON.stringify({content}) })
    │
    ▼
Hono 内部写到 response.body (writable)
    │
    ▼
Nginx 不缓冲 → 客户端立即可见

评估模型回复的质量​

RAG 跑起来之后，怎么知道它"答得好不好"？靠人工抽查显然不靠谱。这里用了一个比较简单的评估流程：

一、建立「黄金评测集」 人工标注一批「问题-标准答案」对，覆盖知识库核心知识点。起步 50~100 条就够，跟着系统一起迭代。

二、给每个回答打个分 省事打法：直接让 LLM 当裁判 A/B 评分，准备一份评分 Prompt，让 LLM 对比「标准答案」和「模型回答」打分。

三、问答日志落库 每次问答记录 query, retrievedChunks, finalAnswer, feedback (用户点赞/踩)。落库后方便每周抽样核对，找出「召回失败」的反例。

四、指标差了怎么调优——先定位再下手

黄金思路：召回问题比生成问题更常见，先看召回。90% 的"AI 答错"案例其实是"压根没找到对的资料"。

Token 消耗把控​

目前只是通过 Prompt 限制输入输出 token，以及增量灌库减少向量模型 token 的消耗。如果后面要用上高级模型的话，肯定得做好更精细的把控，毕竟真的贵。

自动化部署​

最近 vibe coding 了几个 Web App，基本都走的这个流程，还挺方便的：

• GitHub Actions 编写 workflow deploy 脚本，push 代码后自动触发镜像构建。
• 编写 Dockerfile，上传 Docker Hub。
• 个人服务器从 Docker Hub 拉取镜像部署。

注意：要先在 GitHub 设置 secrets，以及在服务器相关项目目录里设置环境变量，避免明文存储敏感信息。

最后​

坦白说，这只是一个简单的 RAG 服务，仅仅是向量召回和模型总结回复（Naive RAG）。在实际使用中，你会发现搜极度具体的专有名词时，纯向量检索很容易漏召回。

我也是刚接触 ai agent 开发，修行尚浅，望路过大佬们见谅。后面其实还能做进阶优化，这也是我打算在这个专栏接着探索的尝试：

1. Hybrid Search (混合检索)：可叠加 BM25 关键词，解决专业术语丢失的问题。
2. Re-ranking (重排)：引入专门的重排模型（如 BGE-Reranker），精准过滤无效的“相似废话”。
3. Agentic Flow (智能体)：接入 Function Calling，从「问答」走向「任务执行」，比如让其检索其他数据库的内容或者联网搜索外部资源。

拥抱 AI 时代，把手弄脏，我们下篇见。

autopilot 需要数据才能跑起来，想了下自己造数据太麻烦了，所以基于 konva(canvas)做一个场景编辑器来造点数据，目标是通过编辑器编辑地图和基于地图编辑一个基础场景(自车+车道+环境车+行驶模拟)，并在 autopilot 应用中跑起来

这里咱直接用成熟的 canvas 库 konva 来搭建页面，这个库可以先用官网的 editor-demo 体验下。konva 的图层层级结构分为 Stage -> Layer(层) (-> Group) -> Shape(元素)，可以先熟悉下这几个概念，不熟的话可能比较难以看懂下面的示例代码

页面布局​

稍微设计一下：中间画布+顶部操作栏+右侧属性面板。关于组件库的话，antd 够用了，如下图所示：

暂时先只做一个地图和一个场景，后面再扩展下多对多的情况

数据管理​

通过 mobx 和 mobx-react-lite 来管理编辑器的数据。新建变量的时候，很多情况下你只需要一个全局变量而不是响应式变量，所以还是建议在 makeObservable 指定变量是否可观察（而不是一味 makeAutoObservable 虽然用这个有点爽），另外可以善用下observable.shallow 做浅层的观察，毕竟复杂的大对象在生成响应式对象时还是有一定开销的

// store/index.ts
import Konva from "konva";
import { makeObservable, observable, computed, action } from "mobx";

class EditorStore {
  stage: IStage = {
    ref: null, // 暂存konva画布实例
  };
  editMode = EditMode.Map; // 编辑模式，分为地图和场景编辑
  isEdit = false; // 编辑锁
  isDrawLine = false; // 画线锁
  // 统一处理场景元素的绘制
  drawCallForScene = (type: ESceneElement) => {
    this.isEdit = true;
    switch (type) {
      case ESceneElement.Vehicle: {
        break;
      }
      default: {
        break;
      }
    }
    this.isEdit = false;
  };
  // 统一处理地图元素的绘制
  drawCallForMap = (type: EMapElement) => {
    this.isEdit = true;
    switch (type) {
      case EMapElement.Line: {
        this.isDrawLine = true;
        break;
      }
      default: {
        break;
      }
    }
    this.isEdit = false;
  };
  // 在初始化画布时执行，挂载画布事件
  initStage = () => {
    const stage = this.stage.ref!;
    const layer = stage.getLayers()[0];
    // ...
  };
  // 地图
  mapList = [];
  currentMap = "";
  // 场景
  sceneList = [];
  currentScene = "";
  // 元素
  selectedElement = null;
  // 当前选中的元素的属性，基础属性包括位置、颜色、旋转、大小、名称等
  selectedElementProps = null;

  constructor() {
    makeObservable(this, {
      stage: observable.shallow,
      editMode: observable,
      // ...文章代码可能不全，感兴趣自行查阅github源码
    });
  }
}

初始化页面​

新建一个 react 路由页面，初始化画布，监听画布事件比如点击、鼠标事件等，并自适应容器宽高

// scene-editor/index.tsx
const SceneEditor = observer(() => {
  const { stage } = editorStore;
  const containerRef = useRef<HTMLDivElement>(null);
  const [shapes, setShapes] = useState<Konva.ShapeConfig[]>([]);
  const [selectedId, setSelectedId] = useState<string>();

  // 初始化画布
  useEffect(() => {
    if (containerRef.current) {
      const container = containerRef.current;
      stage.ref = new Konva.Stage({
        container: containerRef.current,
        width: container.clientWidth,
        height: container.clientHeight,
        draggable: true,
      });
      // 初始化图层
      const layer = new Konva.Layer();
      stage.ref.add(layer);
      const resizeStage = () => {
        stage.ref!.width(container.clientWidth);
        stage.ref!.height(container.clientHeight);
        // 批量绘制（放到同一帧绘制）
        stage.ref!.batchDraw();
      };
      editorStore.initStage();
      // 监听窗口变化
      window.addEventListener("resize", resizeStage);
      // 监听缩放
      stage.ref.on("wheel", (e) => {
        e.evt.preventDefault();
        handleWheel(e.evt);
      });
      return () => {
        stage.ref?.destroy();
        window.removeEventListener("resize", resizeStage);
      };
    }
  }, []);

  return (
    <div className="scene-editor">
      {/* 顶部状态栏 */}
      <Header />
      <div ref={containerRef} style={{ width: "100%", height: "100%" }} />
      {/* 侧边栏 */}
      <RightSider />
    </div>
  );
});

代码可能不全，可以查阅 github 源码

自车​

自车默认位于原点位置，这里先简单用一个绿色矩形框来替代，在初始化的时候就自动添加到场景中。并且这里要先加一个元素控制器 Konva.Transformer，便于调整矩形框的大小和旋转角度

// store/index.ts
// ...
initStage = () => {
  // ...
  // 初始化控制器
  this.transformer = new Konva.Transformer({
    // 启用旋转
    rotateEnabled: true,
    // 设置旋转吸附角度
    rotationSnaps: [0, 90, 180, 270],
  });
  layer.add(this.transformer);
  // ...然后监听点击事件，在点击到具体shape的时候动态加上控制器
  stage.on("click", (e) => {
    if (e.target === stage) {
      this.transformer!.nodes([]);
    } else {
      const target = e.target as Konva.Shape;
      // 这里其实可以做下限制，有些元素可能是不允许编辑的
      // 比如地图元素在场景编辑模式下是不可编辑的
      // if (target !== this.currentLine) {
      this.transformer!.nodes([target]);
      this.selectedElement = target;
      // }
    }
  });
};

自车相关的代码如下：

// store/index.ts
// ...
initStage = () => {
  //...
  // 绘制自车
  const autoCar = createRect({
    fill: "green",
    x: 0,
    y: 0,
    width: 30,
    height: 20,
    strokeWidth: 1,
  });
  layer.add(autoCar);
};

基础图形封装​

其实 konva 本身已经封装了现成的图形绘制函数，这里是二次封装简化下代码量，基类代码如下：

import Konva from "konva";

type ShapeType = "rect" | "circle" | "line" | "polygon" | "triangle";

export function createRect(config: Konva.RectConfig) {
  return createShape("rect", {
    width: 100,
    height: 80,
    ...config,
  });
}

export function createCircle(config: Konva.CircleConfig) {
  return createShape("circle", {
    radius: config?.radius || 50,
    ...config,
  });
}

export function createTriangle(config: Konva.ShapeConfig) {
  return createShape("triangle", {
    offset: { x: 0, y: -15 }, // 居中调整
    ...config,
  });
}

/**
 * 图形基类
 */
export function createShape(type: ShapeType, config: any) {
  const defaults = {
    x: 0,
    y: 0,
    fill: Konva.Util.getRandomColor(),
    draggable: true,
    stroke: "#333",
    strokeWidth: 2,
  };

  const shapeConfig = { ...defaults, ...config };
  let shape: Konva.Shape;

  switch (type) {
    case "rect":
      shape = new Konva.Rect(shapeConfig);
      break;
    case "circle":
      shape = new Konva.Circle({
        radius: 50,
        ...shapeConfig,
      });
      break;
    case "line":
      shape = new Konva.Line({
        points: [0, 0, 100, 100], // 默认对角线
        lineCap: "round",
        ...shapeConfig,
      });
      break;
    case "polygon":
      shape = new Konva.RegularPolygon({
        sides: 5, // 默认五边形
        radius: 60,
        ...shapeConfig,
      });
      break;
    case "triangle":
      shape = new Konva.Shape({
        sceneFunc: function (context: Konva.Context, shape: Konva.Shape) {
          context.beginPath();
          context.moveTo(0, -30);
          context.lineTo(30, 30);
          context.lineTo(-30, 30);
          context.closePath();
          context.fillStrokeShape(shape);
        },
        ...shapeConfig,
      });
      break;
  }
  shape!.on("click", () => console.log(`${type} clicked`));
  shape!.on("dragend", () => console.log(`${type} moved`));
  return shape!;
}

交互实现​

整体交互是先在场景编辑器编辑地图和交通场景，通过 localStorage 保存数据，然后通过指定按钮快速跳转到 autopilot 3d 页面查看仿真效果，可以翻到最后先看下录屏效果

地图交互​

地图拖动。配置支持 draggable

new Konva.Stage({
  container: containerRef.current,
  width: container.clientWidth,
  height: container.clientHeight,
  draggable: true,
});

地图缩放。下面以鼠标滚轮缩放为例，基于鼠标位置做画布的缩放

// scene-editor/index.tsx
// 监听鼠标滚轮事件
const MIN_SCALE = 0.5; // 最小缩放比例
const MAX_SCALE = 3; // 最大缩放比例
const handleWheel = (e: any) => {
  const stageRef = stage.ref!;
  const step = 1.1;
  const oldScale = stageRef.scaleX();
  const pointer = stageRef.getPointerPosition()!;
  let newScale = e.deltaY < 0 ? oldScale * step : oldScale / step;
  // 有最大和最小范围限制
  newScale = Math.min(Math.max(newScale, MIN_SCALE), MAX_SCALE);
  const mousePointTo = {
    x: (pointer.x - stageRef.x()) / oldScale,
    y: (pointer.y - stageRef.y()) / oldScale,
  };
  stageRef.scale({ x: newScale, y: newScale });
  const newPos = {
    x: pointer.x - mousePointTo.x * newScale,
    y: pointer.y - mousePointTo.y * newScale,
  };
  stageRef.position(newPos);
  stageRef.batchDraw();
};
// ...

一键返回原点。可以在左上角加个悬浮按钮居中画布原点

// store/index.ts
focusOrigin = () => {
  if (this.stage.ref) {
    // 清除拖拽产生的位移偏差
    this.stage.ref.x(0);
    this.stage.ref.y(0);
    const centerX = -this.stage.ref.width() / 2;
    const centerY = -this.stage.ref.height() / 2;
    this.stage.ref.offset({ x: centerX, y: centerY });
  }
};

线段绘制​

• 支持绘制直线和虚线
• 编辑过程加绘制锁，按 Q 键（Quit）退出线段绘制

这里需要在 initStage 监听鼠标点击和移动事件，具体看代码注释清晰点：

// store/index.ts
// 暂存的线段对象，用于绘制多段直线
// ...
isDrawLine = false;
currentLine: Konva.Line | null = null;
// 点击顶部操作栏的线段按钮，会加编辑锁，便于多段线段的绘制
drawCallForMap = (type: EMapElement) => {
  this.isEdit = true;
  switch (type) {
    case EMapElement.Line: {
      this.isDrawLine = true;
      break;
    }
    default: {
      break;
    }
  }
  this.isEdit = false;
};
// 在初始化画布时执行，挂载画布事件
initStage = () => {
  const stage = this.stage.ref!;
  const layer = stage.getLayers()[0];
  // 点击时新建线段
  stage.on("mousedown", () => {
    if (this.isDrawLine) {
      const pos = stage.getPointerPosition()!;
      this.currentLine = new Konva.Line({
        points: [pos.x, pos.y],
        fill: "yellow",
        stroke: "yellow",
        strokeWidth: 2,
      });
      layer.add(this.currentLine);
    }
  });
  // 移动鼠标可以选择下一段线段的落点
  // TODO 这里其实可以做下节流
  stage.on("mousemove", () => {
    if (this.currentLine && this.isDrawLine) {
      const pos = stage.getPointerPosition()!;
      let newPoints = [];
      if (this.currentLine.points().length > 2) {
        newPoints = this.currentLine
          .points()
          .slice(0, -2)
          .concat([pos.x, pos.y]);
      } else {
        newPoints = this.currentLine.points().concat([pos.x, pos.y]);
      }
      this.currentLine.points(newPoints);
      layer.batchDraw();
    }
  });
  // 监听键盘事件，这里设定在点击ESC键时结束线段的绘制
  const onKeydown = (e: any) => {
    if (e.key === "q") {
      if (this.isDrawLine && this.currentLine) {
        const newPoints = this.currentLine.points().slice(0, -2);
        this.currentLine.points(newPoints);
        layer.batchDraw();
        this.isDrawLine = false;
        this.currentLine = null;
      }
    }
  };
  window.addEventListener("keydown", onKeydown);
};

车道绘制​

这里设计为三段式编辑，第一二次点击确定车道宽度，第三次点击确定长度，并且结束车道绘制。在第三次点击前有一个框体的高亮效果辅助定位范围

// store/index.ts
isDrawMapElement: EMapElement | null = null;
// 车道辅助绘制，计算当前点击的次数
drawLaneCount = 0;
// 当前车道，多边形对象
currentLane: Konva.Shape | null = null;
stage.on("mousedown", () => {
  // ...
  if (this.isDrawMapElement === EMapElement.Lane) {
    // 第一次点击，先绘制宽度线
    if (this.drawLaneCount === 0) {
      this.currentLine = new Konva.Line({
        points: [pointX, pointY],
        fill: "yellow",
        stroke: "yellow",
        strokeWidth: 2,
      });
      layer.add(this.currentLine);
      // 第二次点击，确定宽度
    } else if (this.drawLaneCount === 1) {
      this.currentLine!.points().push(pointX, pointY);
      // 第三次点击，确定长度
    } else if (this.drawLaneCount === 2) {
      this.currentLane?.destroy();
      const points = [
        this.currentLine!.points()[0],
        this.currentLine!.points()[1],
        this.currentLine!.points()[2],
        this.currentLine!.points()[3],
        pointX,
        pointY,
        pointX -
          (this.currentLine!.points()[2] - this.currentLine!.points()[0]),
        pointY -
          (this.currentLine!.points()[3] - this.currentLine!.points()[1]),
      ];
      this.currentLane = new Konva.Shape({
        // 顶点坐标数组
        points,
        fill: "yellow",
        stroke: "green",
        opacity: 0.2,
        strokeWidth: 2,
        sceneFunc: function (ctx, shape) {
          const points = shape.getAttr("points");
          ctx.beginPath();
          ctx.moveTo(points[0], points[1]);
          for (let i = 2; i < points.length; i += 2) {
            ctx.lineTo(points[i], points[i + 1]);
          }
          ctx.closePath();
          ctx.fillStrokeShape(shape);
        },
      });
      layer.add(this.currentLane);
      this.drawDone(EMapElement.Lane);
    }
    this.drawLaneCount++;
  }
})
stage.on("mousemove", () => {
  // ...
  if (this.currentLine && this.isDrawMapElement === EMapElement.Lane) {
    const pos = stage.getPointerPosition()!;
    const pointX = stage.offset().x + pos.x;
    const pointY = stage.offset().y + pos.y;
    let newPoints = [];
    if (this.drawLaneCount === 1) {
      if (this.currentLine.points().length > 2) {
        newPoints = this.currentLine
          .points()
          .slice(0, -2)
          .concat([pointX, pointY]);
      } else {
        newPoints = this.currentLine.points().concat([pointX, pointY]);
      }
      this.currentLine.points(newPoints);
      layer.batchDraw();
    } else if (this.drawLaneCount === 2) {
      this.currentLane?.destroy();
      // NOTE 注意按逆时针排，和threejs自定义多边形点集一致
      const points = [
        this.currentLine!.points()[0],
        this.currentLine!.points()[1],
        this.currentLine!.points()[2],
        this.currentLine!.points()[3],
        pointX,
        pointY,
        pointX -
          (this.currentLine!.points()[2] - this.currentLine!.points()[0]),
        pointY -
          (this.currentLine!.points()[3] - this.currentLine!.points()[1]),
      ];
      this.currentLane = new Konva.Shape({
        points,
        fill: "yellow",
        stroke: "green",
        opacity: 0.2,
        strokeWidth: 2,
        sceneFunc: function (ctx, shape) {
          const points = shape.getAttr("points");
          ctx.beginPath();
          ctx.moveTo(points[0], points[1]);
          for (let i = 2; i < points.length; i += 2) {
            ctx.lineTo(points[i], points[i + 1]);
          }
          ctx.closePath();
          ctx.fillStrokeShape(shape);
        },
      });
      layer.add(this.currentLane);
    }
  }
})
// 在这里统一处理绘制结束的逻辑
drawDone = (type: EMapElement | ESceneElement) => {
  // ...
  if (type === EMapElement.Lane) {
    const contour = _.chunk(this.currentLane?.getAttr("points"), 2).map(
      (item) =>
        ({
          x: item[0],
          y: item[1],
          z: 0,
        } as { x: number; y: number; z: number })
    );
    const data: IFreespace = {
      id: "freespace" + this.mapElements.lanes.length,
      contour,
    };
    this.mapElements.lanes.push(data);
    this.currentLine?.destroy();
    this.currentLane = null;
    this.currentLine = null;
    this.drawLaneCount = 0;
  }
}

场景编辑​

先支持他车的编辑，以矩形框替代，可以设置高度，看看这个交互是咋样的：

1. 点击他车按钮
2. 点击画布任意处新增他车矩形框
3. 添加他车矩形框，矩形框支持旋转、改变大小和拖动
4. 处于选中状态时，右侧表单自动回填属性，包括名称、宽高、位置等，可以修改，保存场景时会以最新的属性为准

添加代码参考：

// store/index.ts
// 当前正在绘制的场景元素
isDrawSceneElement: ESceneElement | null = null;
drawCallForScene = (type: ESceneElement) => {
  this.isEdit = true;
  switch (type) {
    case ESceneElement.Vehicle: {
      this.isDrawSceneElement = ESceneElement.Vehicle;
      break;
    }
    default: {
      break;
    }
  }
  this.isEdit = false;
};
// ...
stage.on("click", (e) => {
  if (e.target === stage) {
    // ...
    if (this.isDrawSceneElement === ESceneElement.Vehicle) {
      const pos = stage.getPointerPosition()!;
      const pointX = stage.offset().x + pos.x;
      const pointY = stage.offset().y + pos.y;
      const vehicle = createRect({
        fill: "blue",
        x: pointX,
        y: pointY,
        width: 40,
        height: 30,
        strokeWidth: 1,
        // 居中
        offsetX: 15,
        offsetY: 10,
      });
      layer.add(vehicle);
      layer.batchDraw();
      // 自动选中
      this.transformer!.nodes([vehicle]);
      this.isDrawSceneElement = null;
    }
  } else {
    // ...
  }
});

自车或他车路线编辑​

这里先做成匀速的场景，后面可以扩展到更多行驶场景，当然这需要一定的算法 ~ 路线绘制的话，可以复用上面的画线逻辑

选中目标后，路线编辑按钮可点击，这个时候可以编辑对应的路线，路线起点是选中目标的原点，不过这里要注意加一下和他车或自车的关联。另外选中状态下，可以在右侧表单中设置速度

下面是绘制自车路线的示例，环境车其实也类似，注意和路线做下关联就行了：

和 autopilot 交互​

顶部右侧有一个按钮，可以点击后跳转到 autopilot 页面，快速预览 3d 效果，先简单从 localStorage 读取数据。数据结构方面，2d 元素这里其实和 3d 元素只有一个 z 轴的区别，其他结构其实差不多，场景元素主要都是点集，这里注意下坐标轴方向（编辑器现在 y 轴是反向...有点别扭其实）

保存场景数据​

需要遍历场景元素，转换成 autopilot 能接受的接口数据（json），场景数据参考下面的类型定义：