wavedrom-gen

WaveDrom 生成器

将自然语言转换为可编辑的 WaveJSON/JSON5，并使用固定版本的官方 wavedrom 主包引擎进行渲染。将 [email protected] 的 renderAny 行为作为语法依据；自定义 lint 仅作为质量检查层。

必需输出

• 将可编辑源文件保存为 <descriptive-name>.json5。
• 默认渲染为 <descriptive-name>.svg。
• 用于栅格交付或视觉检查时，添加 PNG。
• 添加独立 HTML，以便离线编辑、实时渲染、验证、缩放、复制和下载。
• 可选的 Datasheet 尺寸标注保存在同一 JSON5 文件的顶层 datasheet.annotations 中。
• 说明会实质影响时序语义的假设。
• 返回每个产物的绝对路径。

工作流

1. 对请求分类。 自然语言时序图使用 signal。若明确要求，则保留或生成官方 assign 和 reg 图。将提供的规范、RTL、跟踪记录或时序表视为权威依据。

2. 建立时序约定。 确定时间单位或时钟域、有效边沿、初始状态、信号及有效电平、事件顺序、延迟、传输条件、最终状态和未解决的假设。

3. 消除重要歧义。 只有缺少的信息会实质改变实现精确的图时，才提出问题。对于概念草稿，采用惯例默认值并说明。

4. 阅读官方语法参考。 编写 WaveJSON 前，阅读 references/wavejson-official.md。对于标准协议，也阅读 references/protocol-questions.md。对于同步或实现精确的工作，阅读 references/semantic-review.md。对于规格表时序尺寸标注，阅读 references/datasheet-annotations.md。

5. 编写官方 WaveJSON。 保留所有官方字段。根据所需图表使用 signal、assign 或 reg。对于时序图，始终一致地使用一个时隙，除非需要 period、phase 或官方的 <...> 子周期语法。因果关系放在 edge 中；Datasheet 尺寸标注放在 datasheet.annotations 中。不要在两处重复同一对端点。

6. 使用官方引擎验证。 优先使用 wavedrom_validate MCP。否则运行：

   node <skill-dir>/scripts/validate-wavejson.mjs --input <source.json5>
   

   默认情况下，只有 JSON5、官方渲染或 Datasheet 扩展错误会导致验证失败；语义 lint 仅提供建议，不会阻止官方语法通过。对于自然语言生成的交付内容，如果每条警告都必须导致质量门禁失败，请添加 --strict。

7. 在本地渲染。 优先使用 wavedrom_render MCP。否则运行：

   node <skill-dir>/scripts/render-wavedrom.mjs --input <source.json5> --svg <output.svg>
   

   根据需要添加 --png <output.png> 或 --html <output.html>。渲染器对 SVG 和离线 HTML 使用相同的固定版本官方引擎以及所有随附皮肤。它仅对 signal 图处理 datasheet.annotations，并对 PNG 和 HTML 一致地使用增强版 SVG。不要静默安装依赖；获准安装时，请在 skill 目录中运行 npm ci --omit=dev。

8. 检查并调整。 检查标签、转换、分组、箭头、裁切、皮肤和裁剪情况。对于 Datasheet 尺寸标注，还要检查投影线、箭头、下标、堆叠和隐藏的节点标签。将渲染结果与时序约定进行核对；能够渲染并不能证明协议正确。

自然语言策略

• 保留明确事实，不要用协议默认值替代。
• 区分未知状态 x、高阻态 z、保持状态 .、间隙 |、数据框 =/2-9，以及子周期 <...>。
• 切勿仅为让图示看起来完整而虚构信号。
• 如果指定的协议存在歧义，请询问协议参数，或生成明确标注为概念示例的内容。
• 每张图聚焦一个主题；如果拆分不相关的阶段或时钟域能提高清晰度，就应拆分。
• 将有关建立时间／保持时间／脉宽／周期样式的请求视为对可选 datasheet.annotations 的修改，而非替换官方 WaveJSON。
• 除非用户要求修改，否则原样保留现有官方语法。

质量门槛

• JSON5 可解析。
• 固定版本的官方引擎可根据 signal、assign 或 reg 生成 SVG。
• 请求严格模式时，严格 lint 不报告未解析的标签、节点、未记录的波形字符或可疑配置。
• 存在数据手册注释时，注释应指向现有的 signal 节点，且不得重复 edge 对。
• 同步转换和传输周期符合时序约定。
• SVG 文件存在且非空，并包含 SVG 根元素。
• 如果请求 HTML，则 HTML 为自包含格式，可在无需网络访问的情况下重新渲染嵌入的源内容。
• 最终交付应链接源文件和渲染产物，并列出假设。

依赖基线

要求使用 Node.js 20 或更高版本。将官方主包固定为 [email protected]，并加载随包附带的六款皮肤：default、narrow、dark、lowkey、narrower 和 narrowerer。仅使用 @resvg/resvg-js 从规范的官方 SVG 生成 PNG。

官方主包的 CLI 仍可单独使用：npx wavedrom --input source.json5 > output.svg；此技能会直接调用同一包的引擎，以确保 MCP、SVG、PNG 和离线 HTML 共用同一兼容性基线。

如果 MCP 工具尚未注册，而用户需要使用这些工具，请阅读 references/mcp-registration.md，并优先使用随附的注册脚本。