SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场agentic-mermaid-live-editor-development

agentic-mermaid-live-editor-development

前端与建站

查看项目

更新于 10-15 10:32

技能介绍

用途

本技能用于开发和调试 Agentic Mermaid 浏览器编辑器，包括其模块化 UI、渲染/验证流水线、示例、配置、导出、URL 分享以及网站集成。目标是编辑模块化编辑器源码，并维护独立编辑器与已部署网站共享的契约。

源码地图

  • editor/js/：编辑器行为。将 sharing.js、rendering.js 和 state.js 视为契约来源。
  • editor/css/：编辑器样式。
  • editor/html/：顶栏与工作区局部模板。
  • editor/examples.ts：规范的编辑器示例。
  • scripts/site/editor.ts：组装独立的 editor.html。
  • website/build.ts：组装已部署的 /editor/ 以及所有链接到它的公开页面。
  • scripts/site/editor-state-url.ts：编辑器状态 URL 的规范构建期编码器与校验器。
  • src/browser.ts：以 window.__mermaid 暴露的浏览器渲染器 API。

不要直接编辑生成的 editor.html 或 website/public/ 文件。

构建与测试循环

运行拥有被改动表面的目标：

  • bun run editor：独立 editor.html
  • bun run website：生产网站/public，包含 /editor/
  • bun run website:check：干净的内存中网站 + Worker 产物契约
  • bun run typecheck

对于行为变更，还需运行聚焦的编辑器单元测试和浏览器测试通道。浏览器通道需要 Playwright Chromium 和 AM_BROWSER_TESTS=1。

状态契约

保持编辑器状态采用 editor/js/state.js 中的规范形状：

state = { palette: 'paper', style: 'crisp', seed: 0, zoom: 1, config: {}, }

  • palette 存储已注册的调色板输入名称。
  • style 存储已注册的 Look 输入名称或 crisp。
  • seed 影响带样式墨迹而不改变布局。
  • config 包含被接纳的可序列化渲染选项。

浏览器界面深色/浅色模式与图表外观分离，不得重写 state.palette。

添加状态时，需一并更新序列化、净化、恢复、控件注水和测试。

渲染与验证边界

遵循 editor/js/rendering.js 中的流水线：

editor input -> scheduleRender() -> doRender() -> buildOptions() -> renderMermaidSVGWithReceipt() -> verifyNoExternalRefs() -> insertStrictRenderedSvg() -> verifyMermaid() -> 仅当验证成功时保留带回执的产物

保持 security: "strict" 和 embedFontImport: false 由宿主拥有。通过 SHARED_RENDER_OPTION_FIELDS 和 validateSerializableRenderOptions 接纳恢复的配置；永远不要直接信任 hash 或 storage 数据。使用 replaceChildren 插入一个解析后的 SVG 节点，而不是任意共享 HTML。

不要从陈旧 DOM 启用分享或导出操作。要求当前源码、回执摘要、已验证产物和预览 SVG 一致。

URL 分享契约

将 URL 负载视为带版本的生产者/消费者边界。规范状态是：

{ source: string palette?: string style?: string seed?: number config?: Record<string, unknown> }

hash 编解码器：

deflate:<base64url(deflate-raw(UTF-8(JSON(state))))>

使用 editor/js/sharing.js 作为浏览器的真相来源。对于 Node/构建期链接，从 scripts/site/editor-state-url.ts 导入 editorStateHref() 或 hostedEditorStateHref()。永远不要在其他生产者中手写 base64、压缩、字段名或 /editor/ URL 组装。

保持以下行为：

  • 拒绝未知字段，例如已移除的 theme 别名。
  • 限制编码和解码后的字节数。
  • 对损坏、不受支持或过大的 hash 失败关闭（fail closed）。
  • hash 解码失败后，不要恢复草稿、查询示例或看似合理的默认值。
  • ?example=<id> 仅用于规范编辑器示例；使用状态 hash 表示源码/配置/样式快照。
  • 仅当当前渲染成功验证后才更新 hash。

更改此契约时，需在同一变更中更新浏览器编解码器、构建期编解码器、每个生产者、已检入的深链接，以及单元测试和真实导航测试。

配置控件

对于现有渲染选项：

  • 在 editor/html/left-panel.html 或相关局部模板中添加可访问控件。
  • 在 editor/js/config-panel.js 中存储 UI 状态。
  • 在 readConfig() 中包含该值，并在 hydrateConfigControls() 中恢复它。
  • 保持 state.config 可序列化，并被共享渲染选项 schema 接纳。
  • 通过 buildOptions() 渲染；不要把预览修补成渲染器无法复现的状态。

对于新的公开选项，先更新库契约，再更新编辑器。不要创建仅编辑器可用的别名。

示例

在 editor/examples.ts 中添加或编辑示例。保持稳定的 ID，因为 /editor/?example=<id>、侧边栏、网站示例和测试都依赖它们。示例可提供源码和被接纳的配置；加载示例时必须保留用户选择的 Palette，除非 URL 快照显式携带 palette。

导出行为

保持 SVG、PNG、ASCII 和 Unicode 导出源自当前带回执的产物。保留严格的 SVG 验证和自托管字体处理。PNG 缩放会改变输出尺寸；它不得改变图表语义，也不得在出错后静默回退。

回归门禁

在触及编辑器链接或状态时使用这些测试：

  • bun test src/tests/editor-link-contract.test.ts
  • bun test src/tests/editor-security-closures.test.ts
  • bun test src/tests/website-build.test.ts
  • AM_BROWSER_TESTS=1 bun test src/tests/website-browser-a11y.test.ts --timeout 600000

仓库范围的链接契约必须解码每个已检入的托管编辑器深链接。网站构建契约必须解码每个生成的 HTML/JSON 编辑器状态链接，并拒绝旧式 hash 或未知字段。浏览器测试必须从真实公开页面导航到编辑器，并验证初始化保留了 hash 和源码。

常见陷阱

  • 更新了解码器却没有迁移每个生产者。
  • 将单元测试夹具更新到新编解码器，却未触动公开链接。
  • 在编辑器状态契约要求 palette 的地方重新引入 theme。
  • 仅用在编辑器测试套件内部制造的 hash 测试编辑器。
  • 编辑生成输出而不是模块化源码。
  • 让深色/浅色界面改变图表外观。
  • 在损坏的分享 URL 后恢复草稿，这可能使不相关的本地内容看起来像被分享了。
  • 从陈旧或未验证的预览启用复制/导出。

适用场景与限制

适用场景：Agentic Mermaid 浏览器编辑器本身的开发、调试、构建与测试，以及其状态、分享、导出、示例与网站集成相关契约的维护。

限制：不得直接编辑生成的 editor.html 或 website/public/ 文件；security: "strict" 与 embedFontImport: false 由宿主控制；不得信任 hash 或 storage 数据；分享与导出必须基于已验证的当前产物；其他具体收费、价格、平台或效果信息暂未提供。