hraness/transmute

创建清晰的图表

使用已安装的 transmute CLI 作为确定性适配器。保留编写的 .diagram.json 源文件；将 .light.svg、.dark.svg、.light.png、.dark.png 和 .tldr 视为可替换的导出产物。

严格遵循提示

将用户的提示视为完整的内容规范。

• 保留提供的标签、值、关系、相对大小和省略的内容。
• 仅添加绘制这些事实所需的、中立的机制。
• 不要发明标题、副标题、图例、注释、示例、含义、类别、度量、刻度、连接器或装饰性声明。
• 不要将简短标签扩展为句子。优先使用用户自己的一到三个词的标签。
• 在更新时，删除被拒绝的内容，而不要用新的阐述替换它。

找到源文件

1. 阅读本地仓库说明，并查找 transmute.config.*。
2. 在创建新文件之前，先搜索现有的、主题相同的 .diagram.json。
3. 更新该源文件，而不是编辑生成的图像或创建重复文件。
4. 在包含 info/ 的知识库中，使用 info/diagrams/<slug>.diagram.json，并配合 info/notes/<slug>.md。在仍使用 kb/ 的仓库中，使用相同的相对路径。根据主机的惯例嵌入或链接渲染后的亮/暗图像，并通过笔记（而非二进制画布）链接知识。
5. 在知识库外部，默认使用 diagrams/<slug>.diagram.json。

编排视觉元素

在创建或大幅重新设计图表之前，阅读 visual-communication.md。

深层应用以下默认规则：

• 对普通概念使用圆角矩形。相同角色应具有相同的大小、圆角半径、描边粗细、图标大小和标签样式。
• 在相连的形状之间至少留出 96px（最好 120–200px）的间距，以便箭头被解读为关系而不是接缝。
• 将图标直接放置在其语义形状内部。不要将一个带边框的图标块放入另一个带边框的卡片内。
• 当提示允许抽象时，使用三到七个主要元素。
• 建立清晰的阅读顺序，并将同级元素对齐到共享网格。
• 使用空白（而非边框、颜色或文字）来分隔组。
• 颜色最多用于一种语义区分。切勿进行任意的尺寸或样式更改，以免暗示提示未提供的差异。
• 保持图标处于辅助地位：标签必须仍然承载含义。
• 每个对象仅使用一个可见边界，每个轴线或连接器仅使用一个可见描边。

不要为了满足这些偏好而“改进”字面数据。提示优先。

让确定性布局处理普通坐标

对于水平或垂直序列，使用无坐标的 stack 布局：

{
  "layout": {
    "type": "stack",
    "direction": "horizontal",
    "gap": 160,
    "align": "center"
  }
}

• 数组顺序仅控制放置位置。仅当提示提供了该关系时才绘制边。
• 保持堆叠形状为矩形或椭圆，并省略 x 和 y。
• 除非提示或发布框架要求不同的间距，否则使用默认的 160px 间距。
• 对于分支、非相邻边、图表、自由文本、线条或故意的不均匀放置，切换到定位模式。不要强行将这些含义塞入一维堆叠。
• 如果堆叠不适用，则显式增加画布或减少编写的尺寸。不要静默缩小形状或间距。

编写与渲染

使用公共模式 URL 或运行 transmute diagram init 获取起始模板：

transmute diagram check diagrams/<slug>.diagram.json --strict
transmute diagram render diagrams/<slug>.diagram.json

渲染命令会覆盖一致的同根导出文件。当布局或对比度不确定时，检查亮色和暗色输出。解决所有有用的 lint 发现；更改源文件，然后重新渲染。

如果仓库使用自己的字体或图标包，请阅读 customization.md。不要向仓库添加 MonoLisa 或其他许可字体。默认渲染使用系统无衬线字体栈。

在托管图像生成前进行身份认证

当托管生成报告 AUTH_REQUIRED 时，使用 OAuth 浏览器流程：

transmute auth login
transmute auth status

回调固定为 http://127.0.0.1:49671/oauth/callback。令牌仅属于操作系统凭据存储，通过 Bun.secrets 管理。永远不要要求用户粘贴令牌、将令牌复制到文件、在任务输出中打印令牌，或绕过发现过程。在支持的 macOS 和 Linux 主机上，transmute auth logout 会在可能的情况下撤销远程凭据并删除本地凭据。登录、刷新和注销使用进程作用域绑定的协调机制；在 Linux PID 命名空间之间共享其租约目录会静默失败（不会删除其他作用域的标记）。在 Windows 上，凭据变更会静默失败，直到 Transmute 拥有等效的私有原生协调原语。

严格按字面生成一张托管 WebP 图像

当用户明确要求托管光栅生成时，保留其提示而不是丰富它：

transmute image generate '<字面提示>' --output path/to/image.webp

默认模型是 recraft/recraft-v4.1-utility。仅当用户要求使用 openai/gpt-image-1.5 或其行为对请求结果至关重要时，才使用 --model openai/gpt-image-1.5。这些是唯一支持的 ID。

托管生成是一个经过身份认证的、有界限的免费预览。其 UTC 日账户限制为 10，全局日安全限制为 100。目前尚未强制执行付费。矢量化单独管理，保持本地、免费且无需身份认证。

• 将必需的 .webp 输出路径保留在用户请求的工作区内。
• 让 CLI 创建幂等性 UUID。仅当调用方已拥有一个稳定的 16-128 字符密钥时，才提供 --idempotency-key。服务会在套件账户作用域内持久存储该密钥。
• 永远不要重试失败的生成调用：即使使用持久的账户作用域幂等性，错误也可能是模糊的。
• 不要自己解码、写入或信任图像。CLI 会限制规范的 base64 编码，验证 RIFF/WebP 媒体魔数，并原子性地发布它。

有意使用参考引导的 3D 和材质工作流

当用户要求将生成的或提供的图像转换为 Three.js 场景、低多边形对象、透明 3D 循环或金属质感的 logo 产品渲染时，请阅读 reference-led-3d.md。

这些是完整的本地 Code Mode 主机能力，目前随 Desktop 版一起分发。公共的无头 Bun 运行器可以生成图像并执行其四个固定的可移植操作，但不能执行 HTML 叠加层、Three.js 或私有项目渲染器。Desktop shell 提供原生捕获、权限和 UI，而不是另一种工作流模型。切勿暗示其他情况。在本地 Code Mode 中：

• 将图像到 Three 的工作划分为参考生成、源文件编写、审查、预览，然后最终渲染。切勿将模型生成的 JavaScript 直接发送给语义操作。
• 使用 createThreeReferenceScaffoldInput 将确切的参考工件绑定到审查的场景，即使它没有在视觉上合成。
• 对参考引导的方形产品处理使用 createMetallicLogoImageRequest。保持模型选择明确，并在接受结果前检查身份保真度。
• 首先以 1 倍比例渲染全长度预览。仅在选择了源和处理方法后，再提高分辨率或设备缩放比例。

矢量化光栅而不改变其含义

当用户要求将调用方拥有的光栅艺术作品转换为 SVG 时，将光栅保留为源文件，并将 SVG 视为可替换的派生文件：

transmute image vectorize path/to/input.png --output path/to/input.svg --json

• 矢量化不需要身份认证。转换是本地的，不会联系发现、OAuth、生成或任何其他网络端点。
• 不要重绘、重新标记、裁剪、重新着色或简化主题，超出命令测量的追踪机制范围。
• 仅当用户明确要求进行这种双色适配时，才使用 --duotone '#primary,#secondary'。
• 当可审计性重要时，将生成的收据保留在任务输出或相邻的来源记录中。
• 不要绕过输入、解码像素、持续时间、路径、字节或保真度门控。
• 在其预期尺寸下检查 SVG。成功的追踪并不能证明一个不熟悉的符号传达了预期的概念。

VTracer 在首次使用时从其校验和锁定的官方版本下载。仅对兼容的本地 0.6.4 二进制文件使用 TRANSMUTE_VTRACER_PATH；Transmute 仍然会记录其哈希值。永远不要添加放大模型、嵌入式光栅回退或商业字体来使追踪通过。

有界矢量化目前在 macOS 和 Linux 上受支持。在 Windows 上，报告故意的 tool_platform 失败；不要使用无界的临时输出文件绕过它。

狭窄地使用连接的工具服务器

当 Transmute MCP 连接后，保留专用的 check_diagram 和 render_diagram 工具用于简单的兼容性调用。使用 search_transmute 发现固定的语义注册表，并使用 execute_transmute 与一个精确返回的代码和类型化的 JSON。继续直接编辑已检查的图表源文件；没有工具会创建或重写源文件。

• 仅传递根相对路径的 .diagram.json 路径。
• 将 check_diagram 视为只读。
• 将 render_diagram 视为批准替换五个记录的已生成工件，绝不替换源文件。
• 对于超过 64 个形状或 128 条边的源文件，使用 CLI 而非 MCP。MCP 最多返回 40 个发现，并在列表被截断时报告。
• MCP 模式特意使用内置主题和图标，从不执行工作区配置。当需要受信任的本地配置时，在 MCP 之外使用 CLI。
• transmute.image.vectorize 接受根相对输入/输出路径，无需登录，并保持光栅字节在本地。
• transmute.image.generate 需要根相对 .webp 输出路径，原子性地写入有界图像，并仅返回编辑后的文件/请求元数据。仅使用两个注册表模型 ID，不要重试。
• 永远不要将源代码、shell 文本、动态导入文本、远程 URL 或未注册的操作名称传递给语义执行。

没有 MCP 时，等效的机器可读 CLI 界面为：

transmute code search '<terms>' --limit 4
transmute code execute <exact-operation-code> --input '<strict JSON object>'

有意使用 tldraw

生成的 .tldr 文件是可编辑的交换格式，不需要 tldraw SDK 或桌面应用程序即可创建。当有人想要直接编辑画布时，在 tldraw Offline 中打开它：

transmute canvas open diagrams/<slug>.tldr

如果可选应用程序不存在，transmute canvas install 会解析当前官方版本，验证其发布的 SHA-256 摘要，并启动平台安装程序。该应用程序将 .tldr 作为未保存的文档导入；在那里保存它会创建其较新的原生 .tldraw 包。永远不要直接重写原生的 .tldraw ZIP/SQLite 包。

验证

1. 运行 transmute diagram check <source> --strict。
2. 运行 transmute diagram render <source>。
3. 确认源文件旁边或请求的输出目录中存在所有五个工件。
4. 以实际尺寸检查亮色和暗色输出。
5. 确认同级形状不会暗示错误的差异。
6. 确认连接器足够长，在 .tldr 中绑定到预期的形状，并且不与标签交叉。
7. 如果需要配套笔记，请确认其路径和视觉参考。