archify

Archify Skill

用于创建专业技术图表的工具，生成内含内联 SVG、主题切换和内置图片/SVG 导出菜单的自包含（Self-contained）HTML 文件。

每个由渲染器驱动的图表均自带事实性图表指南（Diagram Guide，方便查找当前操作与快捷键）、确定性语义节点 Hook、带选择性内联图例入口的双类语义透镜（Semantic Lens）、支持精准指针/键盘聚焦前操作的意图轨迹（Intent Trace）、基于自定义有向关系的双端点路径探测（Route Probe）、可搜索的节点查找器（Node Finder）、可通过键盘访问且带有渲染器自带 Semantic Passport 和可复制深层链接的单跳聚焦功能、实时的语义雷达（Semantic Radar）全景、可选的具名章节轨（Named Chapter Rail，带静态 Chapter Delta Preview）、原生的故事节拍导航器（Story Beat Navigator，配备镜头跟随、导播条与 Story Horizon）以及稳定的故事瞬间（Shareable Story Moment）分享链接、供读者控制轨迹渲染的动静调节器（Live/Still Motion Governor）、面向单次嵌入的仅查看者分享章节提示（Share Chapter Cue）、演示舞台（Presentation Stage）、无依赖平移/缩放、深色/浅色主题切换（状态持久化在 localStorage 中，并自动适配 prefers-color-scheme）、导出菜单（可复制 PNG 到剪贴板；原生支持最高 4 倍分辨率导出 PNG/JPEG/WebP 位图；下载双主题 SVG；将带有轨迹的图表录制为 WebM 视频），以及确保两套主题色彩一致的 CSS 变量色彩系统。图表指南、语义透镜、图例预览、意图轨迹、路径探测、查找器、聚焦、雷达、章节变动预览、故事轨迹叠加层、导播条、Story Horizon、节拍状态、引导视图、播放、演示、动画控制与视口状态等临时交互均不会修改标准的完整图表导出结果。

渐进式阅读深度（Reading Depth）随读者放大视口逐步呈现渲染器上下文与精细细节，而语义交互则能在任意缩放比例下准确展示所需的局部事实。

直接关系固定（Direct Relationship Pin）功能使得每一个编译生成的独立连线关系都可直接交互操作，且不会改变原有的代码定义。可以通过标准标识符语法为重要的 connections、edges、messages、flows 和 transitions 指定可选的作者控制 id；ID 在其关系集合内必须唯一。渲染器会保留其数值型的 data-edge-key 用于运行时去重，并单独将作者指定的身份输出为 data-edge-id。在运行时，系统会拒绝存在冲突的 source/target/label/ID 元数据，并仅将 path/line/polyline 几何体克隆到节点下方的一个视图所有叠加层中。使用 24px 的透明非缩放描边进行点击命中测试（Hit testing），外加单独的虚线聚焦轨；严格保留一个 tabindex="0" 的关系按钮，并使用方向键、Home 和 End 键移动焦点。精细指针悬停与键盘聚焦会临时复用精确的关系预览（Relationship Preview）。点击、轻触、Enter 或空格键将打开源节点的 Semantic Passport 并固定当前透镜行。当关系包含作者定义的 ID 时，固定操作会写入 #relation=<id>，将操作变更为 Copy relation，并在重新排序后恢复相同的源、目标、标签、路径和受限相机视图；过期的 ID 会按失败关闭处理。不带 ID 的旧版关系保留为页内固定，保持 Copy node，且绝不暴露其数值 Key。再次触发相同关系、真实的背景激活、Clear 或 Escape 均可清除该状态。aria-pressed 用于传达固定状态，同时源/目标/标签名称保持稳定。触控操作无需等待悬停，端点附近的节点优先响应，平移绝不会触发关系，且更强的聚焦（Focus）、故事（Story）、路径（Route）、语义透镜（Semantic Lens）、章节（Chapter）与嵌入状态拥有优先权。请勿另外添加面板、工具栏操作、外部依赖、存储或自定义几何体。在嵌入、打印和标准导出时，会自动移除所有命中、固定、预览和脉冲状态；同时保留作者定义的 data-edge-id 作为语义 SVG 身份标识。

安装与设置

无需安装额外依赖。本 Skill 分发包内置了由全部 5 个 JSON Schema 编译而成的独立校验器，因此安装后即可立刻进行 Schema 校验与布局验证。生成的 HTML 页面与渲染器运行时均不依赖外部库。

运行 node bin/archify.mjs doctor 检查安装状态。在创建首个自定义图表前，可运行 node bin/archify.mjs demo [输出目录] 生成可直接打开的示例图表。

如果你完全没有终端 Shell 操作权限（例如本 Skill 是作为项目知识库添加的），则请在响应每个需求时回退到架构模式（architecture mode）：按照下文的【设计系统】规范，将 SVG 手动填入 assets/template.html，并在交付前完成自检清单。

选择图表类型

当用户需求较为模糊时，在选择渲染器之前，请先运行 node bin/archify.mjs guide "<用户的场景描述>"。内置的零依赖指南工具会在 11 种限定场景方案中匹配最合适的一种，并给出解答、适用与忌用场景、所需证据、演示设置以及可直接复制的提示词。--json 参数提供用于自动化调用的相同契约，--lang en|zh 可覆盖语言检测。请将推荐方案作为起点，再结合用户的实际问题与仓库上下文进行二次确认。

每个内置场景方案均有 examples/ 目录下已校验的示例文件以及生成的 Proof Lab 卡片作为支撑。请将这些示例作为结构参考，而不是直接复制其中的具体业务事实。在仓库中修改方案或示例时，请重新生成 docs/guide.html 和 docs/gallery.html；测试用例会严格检查所有 11 个方案 Proof ID 能否正常解析，并确保每个 Proof 保留 3 个具名读者视图。

类型	适用场景	实现方式
`architecture`	系统组件、云资源、服务架构、安全边界、基础设施拓扑	`renderers/architecture/render-architecture.mjs` + JSON（渲染器无法运行时可手动排版 SVG）
`workflow`	技术流程、审批节点、工具调用链、Runbook、CI/CD 流程、应急响应流程	`renderers/workflow/render-workflow.mjs` + JSON
`sequence`	API 调用链、请求生命周期、缓存降级机制、异步追踪、返回路径	`renderers/sequence/render-sequence.mjs` + JSON
`dataflow`	数据管道、ETL/ELT、PII 数据隔离、数据血缘、数据仓库同步、数据消费者映射	`renderers/dataflow/render-dataflow.mjs` + JSON
`lifecycle`	状态机、状态流转、等待状态、重试机制、终态控制	`renderers/lifecycle/render-lifecycle.mjs` + JSON

触发词参考："架构图/系统图/云架构图" → architecture（除非明显偏向过程流程）。"工作流/流程/过程/runbook/审批/CI-CD/故障处理" → workflow。"时序图/交互图/调用链/谁调用谁" → sequence。"数据流/管道/ETL/血缘/PII/数据治理" → dataflow。"状态/生命周期/状态机/重试/终态" → lifecycle。

Mermaid 作为输入方言

当用户粘贴 Mermaid 代码时，不要尝试对其进行机械解析或渲染 —— 应当读取其结构信息，并在对应的 archify 模式下从零重新排版布局：

Mermaid 方言	Archify 模式	映射规则
`flowchart` / `graph`	`workflow`（若为组件拓扑图则用 `architecture`）	`subgraph` → 泳道或区域边界；节点形状 `{}`（菱形） → 决策/安全节点；`-->` 上的标签 → 边标签（谨慎使用）；`classDef`/`style` → 映射至最接近的语义类型
`sequenceDiagram`	`sequence`	`participant` → 参与者（从名称中提取语义 `type`）；`->>` → 消息，`-->>` → `return` 变体；`Note` → 消息 `note`；`rect` 块 → 分段（segments）
`stateDiagram`	`lifecycle`	states → 状态节点（根据名称识别 `start`/`active`/`waiting`/`success`/`failure`）；`[*]` 开始/结束 → `start` 类型 / `terminal` 泳道；流转标签 → 事件风格的标签

剔除 Mermaid 原有的样式设置，仅保留其拓扑结构和语义表达。由你来决定分组、泳道顺序以及需要重点突出的内容 —— 这种设计决策才是核心价值所在。

布局原则（排版前必读）

Archify 的可读性来自于空间叙事能力，而不是简单地把每一个依赖都画成箭头。在编写坐标或边列表之前，先规划好一条清晰的主线故事：

单一主路径 — 从左到右（架构图）或从泳道到列（工作流图）。读者应能顺畅追踪正常流程（Happy path）而不会遇到交叉线条。
精简边标签 — 仅在主路径上的跨边界或非直观流转处添加标签，相邻步骤保持无标签状态。
短侧枝路由 — 权限、存储、Bot 机器人、CI 等辅助节点：从主路径上最近的节点向上或向下连接。切勿让次要边斜穿无关组件。
卡片承载细节 — 策略、技术栈说明以及“同时连接到 X”等辅助信息应放入摘要卡片中，而不是画成额外的箭头。
模式契合度 — 过程/审批/工具调用类故事 → workflow 或 sequence。节点数 ≤12 的组件图 → architecture。如果图表需要 20+ 条连线，请持续删减连线直到主路径清晰可见。

模式参考示例：examples/archify-repo.architecture.json（本仓库）以及 examples/maka-architecture.architecture.json（第三方桌面应用）。

当标签重叠导致校验失败时，请阅读Suggested fix提示行（坐标 / labelAt / labelDy）并直接应用修补措施 —— 切勿盲目猜测偏移量。

渲染器模式 (architecture / workflow / sequence / dataflow / lifecycle)

所有 5 种模式均遵循相同的开发循环：

先读规范：阅读 Schema 文件（schemas/<type>.schema.json）和完整的示例文件（examples/*.{architecture,workflow,sequence,dataflow,lifecycle}.json）—— 复制现有的字段模式，避免凭空猜测。
编写 <name>.<type>.json。
渲染生成：node bin/archify.mjs render <type> <input>.json <output>.html（路径相对于本 Skill 所在文件夹）。
校验产物：node bin/archify.mjs validate <type> <input>.json --json，针对密集型工程图显式加上 --quality standard，针对精致交付图加上 --quality showcase；或者使用 node bin/archify.mjs check <output>.html 检查已有 HTML 文件。此步骤会捕获格式错误的 SVG 输出、非有限值、两点斜向箭头、穿越图例的箭头以及感知配置文件的关系交叉问题。
若任意步骤报错，错误信息会明确指出 JSON 路径或修复建议（阈值、有效范围、需调整的参数）。修改 JSON 后重新运行即可；切勿

你可能还喜欢

vue-patterns

240Kfrontend

Vue.js 3 Composition API patterns, component architecture, reactivity best practices, Pinia state management, Vue Router navigation, and Nuxt SSR patterns. Activates for Vue, Nuxt, Vite, or Pinia projects. Use when building or reviewing Vue 3, Nuxt, or Pinia code — Composition API, reactivity, or router navigation.

affaan-m

获取

motion-advanced

237Kfrontend

React / Next.js 高阶动效设计模式——涵盖拖拽交互、手势操作、文本动画、SVG 路径绘制、自定义 Hook、命令式序列动画（useAnimate）、加载器（Loaders）及完整的 API 选型决策树。需先配置 motion-foundations。

affaan-m

获取

frontend-ui-dark-ts

46Kfrontend

A modern dark-themed React UI system using Tailwind CSS and Framer Motion. Designed for dashboards, admin panels, and data-rich applications with glassmorphism effects and tasteful animations.