Skip to content
Back to search

archscribe

Create premium hand-drawn architecture, workflow, and swimlane diagrams in a dark neon or light paper style, with editable Excalidraw sources, PNG/SVG previews, animated GIF/MP4 output, and interactive HTML. Use whenever the user asks for 岚叔动态架构图、手绘架构图、Excalidraw 风格图、DailyDoseOfDS 风格技术图、动态流程图、泳道图、系统可视化,或希望复刻并提升参考架构图。

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/lazypay-archscribe/badge.svg)](/listings/lazypay-archscribe)

HTML

<a href="/listings/lazypay-archscribe"><img src="/api/listings/lazypay-archscribe/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

把本文件夹放进你的 Codex 技能目录:

~/.codex/skills/archscribe

常见的本地安装路径:

${CODEX_HOME:-$HOME/.codex}/skills/archscribe

安装运行依赖:

python3 -m pip install -r requirements.txt

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 120 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: archscribe
  3. description: Create premium hand-drawn architecture, workflow, and swimlane diagrams in a dark neon or light paper style, with editable Excalidraw sources, PNG/SVG previews, animated GIF/MP4 output, and interactive HTML. Use whenever the user asks for 岚叔动态架构图、手绘架构图、Excalidraw 风格图、DailyDoseOfDS 风格技术图、动态流程图、泳道图、系统可视化,或希望复刻并提升参考架构图。
  4. ---
  5. # Archscribe
  6. Turn an article, system description, process, or reference image into a polished hand-drawn diagram. The default browser renderer can produce PNG, GIF, MP4, SVG, editable Excalidraw, and interactive HTML.
  7. ## 1. Check the environment
  8. Run once per session:
  9. ```bash
  10. python -X utf8 -c "import PIL, svg.path"
  11. python -X utf8 -c "from playwright.sync_api import sync_playwright"
  12. python -X utf8 scripts/doctor.py
  13. ```
  14. - Missing base packages: `python -m pip install -r requirements.txt`
  15. - Missing Playwright: `python -m pip install -r requirements-browser.txt && python -m playwright install chromium`
  16. - Missing ffmpeg: MP4 is skipped; other browser formats still work.
  17. - Chromium unavailable: use `--renderer pillow`. Pillow supports PNG, GIF, and Excalidraw with the classic flow animation.
  18. Bundled fonts, icons, and rough.js keep the main visual system portable. Chromium, ffmpeg, and rare CJK fallback fonts remain environment dependencies.
  19. ## 2. Pick a layout
  20. | Layout | Use it for | Capacity |
  21. | --- | --- | --- |
  22. | `panorama` | complete systems with inputs, core, decisions, and detail panels | 2-6 inputs, 2-4 core cards, 0-3 panels |
  23. | `swimlane` | category bands / comparison rows (DailyDoseOfDS-style), cross-role workflows, catalogs | 2-5 lanes with title + subtitle column, up to 5 steps each, in-lane dashed loop channels |
  24. | `graph` | free-form per-project workflows with custom loop topology (retry/replan/recall...) | 2-24 nodes, up to 40 edges, auto DAG layout + loop lanes |
  25. Decision rule:
  26. - Whole system with multiple regions → `panorama`
  27. - Parallel categories, variants, roles, or a comparison ("the N types of X") → `swimlane` (each lane gets a tinted band, a darker title column with optional `subtitle` such as "Triggered by: ...", and right-to-left in-lane connections automatically drop into a dashed loop channel under the cards)
  28. - Anything with its own topology: linear stages, forks/joins, multiple distinct loops → `graph` (declare `nodes` + `edges`; `kind: "loop"` edges become dashed return channels that fire after the forward wave). Long rightward graphs auto-stack downward to prevent clipped sides and top-heavy layouts.
  29. ## 3. Write and validate the spec
  30. Start from `assets/default-spec.json` or a file under `assets/examples/`. The complete field reference is `references/spec-format.md`.
  31. Keep titles short, use the user's language, and move detail into bodies, notes, or an interactive HTML sidebar.
  32. ```bash
  33. python -X utf8 scripts/render_animated_diagram.py --spec spec.json --outdir out --validate-only
  34. ```
  35. Fix every error. Warnings identify long text, unknown icons, ignored fields, content that exceeds a layout's capacity, graph auto-stacking, or ignored graph canvas width/height.
  36. ## 4. Choose a visual theme
  37. Two styles, both first-class:
  38. - `default`: black-canvas neon hand drawing — glowing beams, grain, vignette. The brand hero look.
  39. - `paper`: light warm-white paper (DailyDoseOfDS-style) — sage/periwinkle band tints, near-black ink, white cards with colored strokes; the flow animation becomes small solid dots traveling the arrows instead of neon beams.
  40. Styles control the full palette and finish. Use `--style` to override the spec. Any other style name fails validation.
  41. ## 5. Choose animation
  42. - `flow`: continuous data movement; safe default
  43. - `draw`: whiteboard construction
  44. - `relay`: one connection at a time
  45. - `trace`: follow a request path
  46. - `chapter`: staged explanatory build-up
  47. - `failure-recovery`: failure/retry-oriented narrative timing
  48. The last three use deterministic narrative choreography and longer minimum timelines. The browser renderer is required for every preset except classic Pillow `flow`.
  49. ## 6. Render and verify
  50. First render a PNG for layout review:
  51. ```bash
  52. python -X utf8 scripts/render_animated_diagram.py --spec spec.json --outdir out --basename diagram --formats png --check
  53. ```
  54. Then render the publishing set:
  55. ```bash
  56. python -X utf8 scripts/render_animated_diagram.py --spec spec.json --outdir out --basename diagram --formats gif,mp4,png,excalidraw,svg,html --verify --check --strict-formats
  57. ```
  58. `--formats` is exact: only requested, supported files are emitted. Unknown formats fail. Use `--strict-formats` for publishing so missing MP4/SVG/HTML fails instead of silently falling back. `--check` must return `"ok": true`.
  59. Visually inspect the PNG for overlap, crossing connectors, cramped labels, weak hierarchy, clipped edges, and empty-space imbalance. Shorten copy or switch layout before reducing text below a readable size.
  60. ## 7. Icons and brands
  61. Specs use stable semantic icon keys. Core keys include `file`, `folder`, `scan`, `shield`, `db`, `package`, `message`, `api`, `clock`, `brain`, `gear`, `eye`, `terminal`, `globe`, `server`, `lock`, `check`, and `clipboard`.
  62. Additional semantic aliases cover cloud infrastructure, data, AI, security, business roles, and states, including `cloud`, `cluster`, `container`, `queue`, `cache`, `vector-db`, `agent`, `model`, `rag`, `tool-call`, `guardrail`, `evaluation`, `identity`, `audit`, `user`, `success`, `failure`, and `retry`.
  63. For a custom logo or colorful icon, use `icon_file` with a local SVG/PNG path. Use `left_panel.badge_file` for a panorama panel brand mark. Paths resolve relative to the spec.
  64. ### Illustration system
  65. Every item that accepts `icon` also accepts:
  66. - `icon_style`: `outline`, `illustrated`, or `hero`.
  67. - `icon_size`: `compact`, `standard`, or `hero`.
  68. - `icon_motion`: `auto` (plays the icon's built-in job story) or `none` (freeze at rest pose). Legacy preset names (`think-pulse`, `gear-spin`, `eye-scan`, `memory-write`, `shield-check`, `scope-scan`, `budget-gauge`, `trigger-ping`, `tool-spark`, `output-pop`) are still accepted and behave like `auto`.
  69. Use `outline` for dense secondary nodes, `illustrated` for normal concept cards, and `hero` for the 1-3 concepts that carry the story. The browser renderer draws plate-free "Neon Sketch Duotone" illustrations: theme-ink hand-drawn strokes plus one semantic accent on the moving part, where each of ~56 semantic families performs its own seamless-looping job story (synapse signals, gear pitches, chip drops, shackle clicks — see `references/illustrated-icons.md`). This includes a dedicated loop-workflow pack (`loop`, `decision`, `split`, `merge`, `wait`, `orchestrator`, `subagent`, `handoff`, `human`, `plan`, `score`, `compare`, `sandbox`, `checkpoint`, `error`, `rollback`, `emit`, `ingest`, …) for agent-loop and pipeline diagrams — sample spec `assets/examples/loop-icon-pack-spec.json`. Pillow renders a simplified offline duotone fallback; Excalidraw keeps editable icon placeholders.
  70. For a DailyDoseOfDS-style short loop, use 1210×1138, 20 FPS, 41 frames, stable camera, 1-3 active paths at a time, illustrated/hero icons on the main concepts, and `flow` animation. Start from `assets/examples/illustrated-loop-spec.json` (dark panorama) or `assets/examples/swimlane-spec.json` (light paper bands).
  71. ## 8. Delivery
  72. - Show GIF inline when useful.
  73. - Prefer MP4 for publishing and social platforms.
  74. - Include PNG for quick viewing.
  75. - Include `.excalidraw` when editability matters.
  76. - Offer interactive HTML for exploration or presentations.
  77. - Use SVG for scalable static publication.
  78. After changing this `SKILL.md`, open a new task or refresh the session before testing trigger behavior. Script and asset changes can be tested immediately.
README.md · README · 379 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. # Archscribe
  3. **高级手绘风动态架构 / 流程图,深色霓虹与浅色纸面双风格,专为文章、系统与工作流讲解打造。**
  4. [![Codex Skill](https://img.shields.io/badge/Codex-Skill-22C86F?style=for-the-badge)](./SKILL.md)
  5. [![Python](https://img.shields.io/badge/Python-3.9%2B-3776AB?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/)
  6. [![Pillow](https://img.shields.io/badge/Pillow-Renderer-8A2BE2?style=for-the-badge)](https://python-pillow.org/)
  7. [![Excalidraw](https://img.shields.io/badge/Excalidraw-JSON-6965DB?style=for-the-badge)](https://excalidraw.com/)
  8. [![Animated GIF](https://img.shields.io/badge/Animated-GIF-FFB000?style=for-the-badge)](./scripts/render_animated_diagram.py)
  9. [![License](https://img.shields.io/badge/License-MIT-111827?style=for-the-badge)](./LICENSE)
  10. `JSON 配置` -> `.excalidraw` + `.png` + 动画 `.gif`
  11. **简体中文** · [English](./README.en.md)
  12. </div>
  13. <p align="center">
  14. <a href="#画廊">画廊</a> ·
  15. <a href="#布局模板">布局</a> ·
  16. <a href="#风格">风格</a> ·
  17. <a href="#快速开始">快速开始</a> ·
  18. <a href="#功能特性">功能特性</a> ·
  19. <a href="#配置结构">配置</a> ·
  20. <a href="#校验">校验</a>
  21. </p>
  22. `archscribe` 是一个 Codex / Claude 技能 + 本地渲染器,用于生成高级感的手绘技术图:手绘字体、可编辑的 Excalidraw 源文件、静态 PNG 预览,以及真正会动的 GIF。
  23. 它适合用来做文章讲解、系统架构图、流程图,以及 DailyDoseOfDS 风格的技术草图——深色霓虹与浅色纸面两套观感。
  24. ## 画廊
  25. 三套首页案例分别展示 `panorama`、`swimlane`、`graph`。每个案例单独占一行,保留足够细节;同一份配置也可以通过 `--style default|paper` 切换深色霓虹或浅色纸面观感。
  26. ### 1. 系统全景:Skill Runtime (`panorama` + `default`)
  27. 适合把一个系统、产品、Agent 或文章主题拆成输入、核心流程、判断节点与交付产物。
  28. ![Archscribe panorama case](./assets/previews/homepage-panorama.gif)
  29. ```text
  30. 用 $archscribe 把这个 Skill / Agent 的工作机制整理成深色霓虹手绘全景图,展示输入、核心流程、质量检查和最终产物,输出 GIF、PNG 和 Excalidraw。
  31. ```
  32. ### 2. 分类对比:Agent Loops (`swimlane` + `paper`)
  33. 适合做 DailyDoseOfDS 风格的分类横带、对比表、角色泳道和知识卡片。
  34. ![Archscribe swimlane case](./assets/previews/homepage-swimlane.gif)
  35. ```text
  36. 用 $archscribe 画一张浅色纸面风格的分类泳道图,主题是「四种 Agent Loops」,每条泳道说明触发条件、关键步骤和回路关系。
  37. ```
  38. ### 3. 自定义拓扑:HTML to Motion (`graph` + `paper`)
  39. 适合表达 CI/CD、渲染管线、故障恢复、审核回路等不规则流程。长链路会自动向下堆叠,避免左右裁切和下半部分空白。
  40. ![Archscribe graph case](./assets/previews/homepage-graph.gif)
  41. ```text
  42. 用 $archscribe 把 HyperFrames 从 HTML composition 到校验、视觉检查、渲染和修复回路画成 graph 布局动态图,用浅色纸面风格输出 GIF。
  43. ```
  44. ## 布局模板
  45. 三套模板覆盖绝大多数讲解场景。在配置里用 `"layout"` 字段选择;内容数量弹性适配,画布高度自动计算。
  46. | 布局 | 适合的内容 | 预览 |
  47. | --- | --- | --- |
  48. | `panorama`(默认) | 完整系统全景:输入源 → 核心管线 → 存储/产出面板 | <img src="./assets/previews/memory-pack.png" alt="panorama 布局" width="320" /> |
  49. | `swimlane` | 分类横带 / 对比行(「N 种 X」)、跨角色协作、图标目录 | <img src="./assets/previews/paper-loops.png" alt="swimlane 布局" width="320" /> |
  50. | `graph` | 自由节点/边 + 自动 DAG + 专属回路通道,随项目定制 | <img src="./assets/previews/layout-graph.png" alt="graph 布局" width="320" /> |
  51. 弹性说明:panorama 支持 2-6 个输入、2-4 张核心卡片,三个底部面板均可省略;swimlane 支持 2-5 条横带,每带 1-5 步,左侧标题列可加副标题(如 "Triggered by: ..."),带内从右往左的连线自动落入卡片下方的虚线回路通道;graph 支持 2-24 节点、40 条边的自由拓扑与 `kind: "loop"` 回路边——线性流程也用它表达,超过 7 个顺序层级的右向长链会自动向下堆叠。
  52. ## 风格
  53. Archscribe 内置 **2 套风格**。图的布局、动画、图标完全一致,只有配色与收尾处理不同。通过命令行 `--style` 或配置文件里的 `"style"` 字段选择。
  54. | 风格 | 观感 | 预览 |
  55. | --- | --- | --- |
  56. | `default` | 纯黑底手绘霓虹:流光光束、颗粒、暗角(品牌默认) | <img src="./assets/previews/memory-pack.png" alt="default 风格" width="320" /> |
  57. | `paper` | 暖白纸面:鼠尾草绿 / 长春花蓝交替色带、近黑墨线、白卡彩描边,流动动画换成沿箭头移动的小圆点 | <img src="./assets/previews/paper-loops.png" alt="paper 风格" width="320" /> |
  58. 在命令行选择风格(优先级高于配置文件):
  59. ```bash
  60. python3 scripts/render_animated_diagram.py \
  61. --spec assets/examples/swimlane-spec.json \
  62. --outdir outputs \
  63. --basename my-diagram \
  64. --style paper
  65. ```
  66. 或写进配置 JSON,让该图始终用这套风格渲染:
  67. ```json
  68. {
  69. "style": "paper",
  70. "canvas": { "fps": 20, "frames": 41 }
  71. }
  72. ```
  73. 两者同时存在时,`--style` 优先;都不设置时使用 `default`。其余风格名会直接报错。`graph` 布局不建议手写 `canvas.width/height`;它会使用自然画布避免裁切和大面积空白。
  74. ## 功能特性
  75. - 3 套布局模板(配置 `layout` 字段):`panorama` 系统全景、`swimlane` 分类横带(参考图同款:副标题列 + 交替色带 + 带内虚线回路)、`graph` 自由节点/边 + 自动 DAG + 回路通道;长 graph 会自动改为纵向堆叠防止裁切
  76. - 浏览器主渲染器(默认):无头 Chromium 内用 rough.js 手绘每个形状 + 内置 Excalifont / 思源黑体 webfont——真正的 Excalidraw 观感,任何系统渲染结果一致
  77. - 6 套动画预设(`--animation`):`flow`、`draw`、`relay`、`trace`、`chapter`、`failure-recovery`,布局全部支持
  78. - 一份 JSON 配置生成 `.excalidraw`、`.png`、`.gif`、`.mp4`、独立 `.svg` 和交互 `.html`(`--formats` 选择)
  79. - 交互 HTML:点击模块高亮它的连接,勾选「整条链路」看 BFS 全链传播,悬停显示提示,支持键盘;单文件可直接分享
  80. - MP4 体积远小于 GIF,X / 微信公众号原生支持;GIF 使用全局共享调色板,体积小
  81. - 2 套内置风格:`default` 深色霓虹、`paper` 浅色纸面(浅色下流光自动换成小圆点,无颗粒无暗角)
  82. - `outline / illustrated / hero` 三级图标系统,以及脑部脉冲、齿轮旋转、眼睛扫描、记忆写入等确定性微动画(详见 `references/illustrated-icons.md`)
  83. - 渲染前配置预检(`--validate-only` 或渲染时自动执行):字段级 `path` / `message` / `fix` 报错,方便 agent 自动修正
  84. - 品牌定制:任意条目用 `icon_file` 指向本地 SVG/PNG 当彩色图标 / 产品 logo(保留原色);`left_panel.badge_file` 在面板头放品牌标;`input_style: "plain"` 输出参考图同款无框彩色输入图标;`down_label` / `up_label` / `yes_label` 改写内置箭头标签;超长签名(如域名)自动左移 + 下划线拉伸,不再裁剪
  85. - `.excalidraw` 源文件保持可编辑、纯文本
  86. - 内置字体(OFL)与 Tabler SVG 图标子集(MIT),完全离线渲染;`flow` 预设下图标还有波次弹跳微动效
  87. - `--check` 校验完整输出契约(尺寸、帧数、真实动效、MP4 流参数、SVG 字体内嵌、HTML 热区、Excalidraw 不变量),并检查 graph 是否裁切、是否垂直失衡、长链是否安全换向;`--verify` 打印帧差报告
  88. - 经典 Pillow 管线保留为 `--renderer pillow` 兜底
  89. ## 输出产物
  90. 默认渲染(`--renderer browser`)生成:
  91. ```text
  92. <basename>.excalidraw
  93. <basename>.png
  94. <basename>.gif
  95. <basename>.mp4
  96. ```
  97. 可选:`<basename>.svg`(内嵌字体,可独立打开)、`<basename>.html`(点击探索的交互页面)。画布宽 1210,高度由布局按内容计算(经典 panorama 为 `1210 x 1138`)@ 20 fps;`flow` 41 帧(约 2 秒循环),`draw` 至少 72 帧,`relay` 至少 88 帧。
  98. ## 快速开始
  99. ```bash
  100. git clone https://github.com/lazypay/Archscribe.git
  101. cd Archscribe
  102. python3 -m pip install -r requirements.txt
  103. python3 -X utf8 scripts/render_animated_diagram.py \
  104. --spec assets/default-spec.json \
  105. --outdir outputs \
  106. --basename sample \
  107. --verify \
  108. --check
  109. ```
  110. ## 安装
  111. 把本文件夹放进你的 Codex 技能目录:
  112. ```bash
  113. ~/.codex/skills/archscribe
  114. ```
  115. 常见的本地安装路径:
  116. ```bash
  117. ${CODEX_HOME:-$HOME/.codex}/skills/archscribe
  118. ```
  119. 安装运行依赖:
  120. ```bash
  121. python3 -m pip install -r requirements.txt
  122. ```
  123. ## 在 Codex 中使用
  124. 按技能名直接调用:
  125. ```text
  126. 用 $archscribe 把这篇文章做成高级感手绘动态架构 GIF。
  127. ```
  128. 中文提示词示例:
  129. ```text
  130. 用 $archscribe 把这篇文章整理成手绘动态架构图(岚叔 / DailyDoseOfDS 风格),输出 GIF、PNG 和 Excalidraw。
  131. ```
  132. ```text
  133. 用 $archscribe 画一个 CI/CD 发布流程图(graph 布局),带失败重试回路,再给我一个能点击探索的 HTML。
  134. ```
  135. > 关于浏览器图标引擎:`browser` 引擎是脚本通过 Playwright **自己拉起的无头 Chromium**,与 "Codex 内置浏览器" 无关,无需手动启动。只要装好 `requirements-browser.txt` 与 `python -m playwright install chromium`,后续会自动启用;未安装时会静默回退到 `pillow` 引擎。
  136. ## 命令行用法
  137. 从内置模板开始:
  138. ```bash
  139. cp assets/default-spec.json work/my-diagram-spec.json
  140. ```
  141. 渲染:
  142. ```bash
  143. python3 -X utf8 scripts/render_animated_diagram.py \
  144. --spec work/my-diagram-spec.json \
  145. --outdir outputs \
  146. --basename my-diagram \
  147. --style default \
  148. --animation flow \
  149. --verify \
  150. --check
  151. ```
  152. 关键参数:
  153. - `--renderer auto|browser|pillow` — `browser`(可用时的默认)在无头 Chromium 里用 rough.js 重放布局;`pillow` 为经典栅格兜底。
  154. - `--animation flow|draw|relay|trace|chapter|failure-recovery` — 动画预设(浏览器渲染器),优先级高于配置文件的 `animation` 字段。
  155. - `--formats gif,mp4,png,svg,html,excalidraw` — 选择产物;浏览器渲染器默认 `gif,mp4,png,excalidraw`。
  156. - `--style default|paper` — 配色,详见 [风格](#风格)。
  157. - `--validate-only` — 只做配置预检并退出(JSON 格式的字段级报错/警告,有错误时退出码 2);正常渲染前也会自动预检。
  158. - `--verify` — 打印抽样帧间差异(变化像素非零 = 真动画)。
  159. - `--check` — 校验完整输出契约(PNG/GIF 尺寸、帧数、FPS、动效、MP4 流参数、SVG 字体内嵌、HTML 热区、Excalidraw 不变量),不通过则以非零码退出。
  160. - `--strict-formats` — 发布时使用;只要请求的格式没有实际生成就失败,避免浏览器或 ffmpeg 缺失时静默少产物。
  161. - `--icon-engine` — 仅影响 pillow 兜底管线的图标质量。
  162. 调试排版时先用 `--formats png` 快速出静态图(几秒),布局确认后再跑完整渲染。
  163. ## 配置结构
  164. 从示例配置起步:`assets/default-spec.json`(panorama)、`assets/examples/swimlane-spec.json`(paper 风格的「四种 agent 回路」参考款)、`assets/examples/graph-workflow-spec.json`(自由图),以及 `illustrated-loop` / `loop-icon-pack` / `illustrated-icon-catalog` 插画样例。
  165. 所有布局共享的字段:
  166. ```text
  167. layout (可选: panorama | swimlane | graph)
  168. style (可选: default | paper)
  169. animation (可选: flow | draw | relay | trace | chapter | failure-recovery)
  170. signature
  171. title.prefix
  172. title.highlight
  173. title.subtitle
  174. ```
  175. `panorama` 专属:`inputs`(2-6)、`core.cards`(2-4)、`decision`、`output`、`left_panel` / `center_panel` / `right_panel`(均可省略)。
  176. `swimlane` 专属:`lanes`(2-5,每条含 `title` / 可选 `subtitle` / 可选 `accent` / `steps`(1-5 个,每个含 `id` / `title` / 可选 `icon`))、可选 `connections`(`from` / `to` / `label` / `style` / `accent`;带内从右往左的连线自动走虚线回路通道)。
  177. `graph` 专属:`nodes`(2-24)、`edges`(最多 40,支持 `kind: "loop"` 回路边)、`direction`(`right` 或 `down`)。超过 7 个顺序层级的右向长链会自动向下堆叠;`canvas.width/height` 会触发诊断警告并交由布局规划器计算自然尺寸。完整字段见 [references/spec-format.md](./references/spec-format.md);具象插画见 [references/illustrated-icons.md](./references/illustrated-icons.md)。
  178. 自定义图标 / logo:任何带 `icon` 的条目都可以改用 `icon_file`(本地 `.svg` / `.png`,相对路径以配置文件所在目录为基准),浏览器渲染器按原色嵌入,适合品牌 logo;`left_panel.badge_file` 则把面板头的文字徽标换成 logo 图片。
  179. 支持的图标键:
  180. ```text
  181. folder file scan shield db hash
  182. package message event api clock brain
  183. gear eye terminal globe video snapshot
  184. server lock check clipboard
  185. ```
  186. 详细说明见 [references/spec-format.md](./references/spec-format.md)。
  187. ## 校验
  188. 校验技能结构:
  189. ```bash
  190. python3 -X utf8 ${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-creator/scripts/quick_validate.py \
  191. ${CODEX_HOME:-$HOME/.codex}/skills/archscribe
  192. ```
  193. 校验 GIF 媒体参数:
  194. ```bash
  195. ffprobe -v error -select_streams v:0 -count_frames \
  196. -show_entries stream=width,height,r_frame_rate,avg_frame_rate,nb_read_frames \
  197. -show_entries format=duration \
  198. -of default=noprint_wrappers=1 outputs/my-diagram.gif
  199. ```
  200. 校验动画:
  201. ```bash
  202. python3 -X utf8 scripts/render_animated_diagram.py \
  203. --spec assets/default-spec.json \
  204. --outdir outputs \
  205. --basename sample \
  206. --verify \
  207. --check
  208. ```
  209. ## 依赖
  210. 必需:
  211. - Python 3.9+
  212. - Pillow 10.0.0+
  213. - svg.path 7.0+
  214. 安装 Python 包:
  215. ```bash
  216. python3 -m pip install -r requirements.txt
  217. ```
  218. 推荐(浏览器主渲染器——手绘形状、动画预设、SVG 输出):
  219. ```bash
  220. python3 -m pip install -r requirements-browser.txt
  221. python3 -m playwright install chromium
  222. ```
  223. 可选工具:
  224. - `ffmpeg`:MP4 输出(缺失时自动跳过);`ffprobe`:检查媒体参数
  225. - Excalidraw 网页版或编辑器插件:手动编辑生成的 `.excalidraw` 文件
  226. 内置资产(渲染时零下载):
  227. - `assets/fonts/` — Excalifont + 思源黑体子集(OFL-1.1),见 `assets/fonts/README.md`
  228. - `assets/vendor/rough.js` — rough.js 4.6.6(MIT)
  229. - `assets/icons/tabler/` — Tabler 图标子集(MIT)
  230. ## 项目结构
  231. ```text
  232. archscribe/
  233. ├── SKILL.md
  234. ├── README.md # 中文说明(本文件,默认)
  235. ├── README.en.md # English
  236. ├── LICENSE
  237. ├── requirements.txt
  238. ├── requirements-browser.txt
  239. ├── agents/
  240. │ └── openai.yaml
  241. ├── assets/
  242. │ ├── default-spec.json # panorama 示例
  243. │ ├── examples/ # 各布局与插画样例
  244. │ ├── fonts/ # 内置 Excalifont + 思源黑体(OFL)
  245. │ ├── vendor/ # rough.js(MIT)
  246. │ ├── icons/
  247. │ │ └── tabler/
  248. │ └── previews/ # GitHub 首页画廊与布局预览
  249. ├── docs/
  250. │ └── interactive-output-design.md # 2.0 路线图
  251. ├── references/
  252. │ ├── spec-format.md
  253. │ └── illustrated-icons.md
  254. ├── scripts/
  255. │ ├── render_animated_diagram.py # CLI + 配置预检 + pillow 管线 + op 录制
  256. │ ├── svg_renderer.py # rough.js 浏览器渲染器 + 动画引擎 + 交互 HTML
  257. │ ├── graph_model.py # 布局规划器(几何 + 图拓扑)
  258. │ ├── doctor.py # 环境自检
  259. │ ├── prepare_fonts.py # 一次性字体资产构建
  260. │ └── icon_browser.py # 旧图标引擎(pillow 管线用)
  261. └── tests/
  262. ```
  263. ## 设计理念
  264. 本项目刻意把视觉系统收得很窄:
  265. - 手绘标题、右上角签名、两套精修配色(深色霓虹 / 浅色纸面)——三种布局共用同一套视觉语言
  266. - 三套布局模板覆盖系统全景 / 分类横带 / 自由图,数量弹性但坐标全部由布局规划器计算
  267. - 所有几何出自 `graph_model.py` 单一来源:Pillow、浏览器渲染器、动画路径、交互热区共享同一份 plan,不存在双渲染漂移
  268. - 静态图保持克制,动效只加在 GIF/MP4 叠层(深色是路径光束,浅色是小圆点 + 小幅图标微动)
  269. 这种约束保证不同架构主题下的输出都一致、精致。
  270. ## 致谢
  271. 深色手绘动态视觉风格,灵感来自 **岚叔** 的动态架构图;浅色纸面风格与分类横带模板,灵感来自 **DailyDoseOfDS**(akshay_pachaar)的手绘技术图。Archscribe 是对这些观感的独立、开源再实现;原创美学的全部功劳归属于这些创作者。
  272. ## 许可证
  273. MIT
  274. `assets/icons/tabler` 中内置的图标来自 Tabler Icons,采用 MIT 许可,详见 `assets/icons/tabler/LICENSE`。

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.