archscribe

Archscribe

将文章、系统描述、流程或参考图转化为精美的手绘图表。默认浏览器渲染器可生成 PNG、GIF、MP4、SVG、可编辑的 Excalidraw 和交互式 HTML。

1. 检查环境

每个会话运行一次：

python -X utf8 -c "import PIL, svg.path"
python -X utf8 -c "from playwright.sync_api import sync_playwright"
python -X utf8 scripts/doctor.py

• 缺少基础软件包：python -m pip install -r requirements.txt
• 缺少 Playwright：python -m pip install -r requirements-browser.txt && python -m playwright install chromium
• 缺少 ffmpeg：将跳过 MP4；其他浏览器格式仍可使用。
• Chromium 不可用：使用 --renderer pillow。Pillow 支持 PNG、GIF 和 Excalidraw，并采用经典的流动动画。

内置字体、图标和 rough.js 让主要视觉系统具有良好的可移植性。Chromium、ffmpeg 和罕见的 CJK 后备字体仍是环境依赖项。

2. 选择布局

布局	适用场景	容量
panorama	包含输入、核心、决策和详细信息面板的完整系统	2-6 个输入、2-4 张核心卡片、0-3 个面板
swimlane	分类带／对比行（DailyDoseOfDS 风格）、跨角色工作流、目录	2-5 条泳道，每条包含标题列和副标题列，每条最多 5 个步骤，泳道内设虚线回路通道
graph	每个项目拥有自定义回路拓扑（重试／重新规划／回忆……）的自由形式工作流	2-24 个节点、最多 40 条边、自动 DAG 布局和回路泳道

选择规则：

• 包含多个区域的完整系统 → panorama
• 并行分类、变体、角色或对比（“X 的 N 种类型”）→ swimlane（每条泳道都有着色带、颜色较深的标题列和可选的 subtitle，例如 “Triggered by: ...”；泳道内从右向左的连接会自动延伸到卡片下方的虚线回路通道）
• 拥有自身拓扑的内容：线性阶段、分叉／汇合、多条不同的回路 → graph（声明 nodes + edges；kind: "loop" 边会变成虚线返回通道，在前向流程推进后触发）。向右延伸较长的图表会自动向下堆叠，以避免两侧内容被裁切或布局过于靠上。

3. 编写并验证规范

从 assets/default-spec.json 或 assets/examples/ 下的文件开始。完整的字段参考见 references/spec-format.md。

标题应简短，使用用户的语言，并将详细内容放入正文、注释或交互式 HTML 侧边栏。

python -X utf8 scripts/render_animated_diagram.py --spec spec.json --outdir out --validate-only

修复所有错误。警告会指出文本过长、图标未知、字段被忽略、内容超出布局容量、图表自动堆叠，或图表画布宽度／高度被忽略等问题。

4. 选择视觉主题

两种风格均为一等支持：

• default：黑色画布上的霓虹手绘风格——发光光束、颗粒感、暗角。这是品牌主视觉风格。
• paper：暖白色纸张风格（DailyDoseOfDS 风格）——鼠尾草绿／长春花蓝色带、近黑色墨迹、带彩色描边的白色卡片；流动动画会变成沿箭头移动的小实心圆点，而非霓虹光束。

风格会控制完整的配色和效果。使用 --style 覆盖规范。其他风格名称均无法通过验证。

5. 选择动画

• flow：连续的数据流动；安全的默认选择
• draw：白板绘制过程
• relay：每次显示一条连接
• trace：跟踪请求路径
• chapter：分阶段逐步构建讲解内容
• failure-recovery：围绕故障／重试叙事设计时间节奏

最后三种动画使用确定性的叙事编排，并具有更长的最短时间线。除经典 Pillow flow 外，所有预设均需要浏览器渲染器。

6. 渲染和验证

先渲染 PNG，以便检查布局：

python -X utf8 scripts/render_animated_diagram.py --spec spec.json --outdir out --basename diagram --formats png --check

然后渲染发布文件集：

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

--formats 是精确指定的：只会生成请求且受支持的文件。未知格式会导致失败。发布时使用 --strict-formats，这样缺少 MP4/SVG/HTML 时会直接失败，而不是静默回退。--check 必须返回 "ok": true。

目视检查 PNG，查看是否存在元素重叠、连接线交叉、标签拥挤、层级不清、边缘裁切以及留白不均衡等问题。在将文字缩小到难以阅读之前，应先精简文案或更换布局。

7. 图标和品牌标识

规格使用稳定的语义图标键。核心键包括 file、folder、scan、shield、db、package、message、api、clock、brain、gear、eye、terminal、globe、server、lock、check 和 clipboard。

其他语义别名涵盖云基础设施、数据、AI、安全、业务角色和状态，包括 cloud、cluster、container、queue、cache、vector-db、agent、model、rag、tool-call、guardrail、evaluation、identity、audit、user、success、failure 和 retry。

对于自定义徽标或彩色图标，请使用 icon_file 并指定本地 SVG/PNG 路径。全景面板的品牌标识请使用 left_panel.badge_file。路径相对于规格文件解析。

插画系统

所有支持 icon 的项目也支持：

• icon_style：outline、illustrated 或 hero。
• icon_size：compact、standard 或 hero。
• icon_motion：auto（播放图标内置的任务叙事）或 none（定格在静止姿态）。仍接受旧版预设名称（think-pulse、gear-spin、eye-scan、memory-write、shield-check、scope-scan、budget-gauge、trigger-ping、tool-spark、output-pop），其行为与 auto 相同。

密集的次要节点使用 outline，常规概念卡片使用 illustrated，承载故事的 1-3 个概念使用 hero。浏览器渲染器会绘制无底板的“霓虹手绘双色调”插画：以主题墨色绘制手绘笔触，并在运动部件上使用一种语义强调色；约 56 个语义系列各自呈现独有的无缝循环任务叙事（突触信号、齿轮俯仰、芯片掉落、镣铐咔嗒声——参见 references/illustrated-icons.md）。其中包括专门的循环工作流套件（loop、decision、split、merge、wait、orchestrator、subagent、handoff、human、plan、score、compare、sandbox、checkpoint、error、rollback、emit、ingest、……），用于 Agent 循环和流水线图——示例规格：assets/examples/loop-icon-pack-spec.json。Pillow 会渲染简化的离线双色调回退版本；Excalidraw 会保留可编辑的图标占位符。

制作 DailyDoseOfDS 风格的短循环时，使用 1210×1138、20 FPS、41 帧、稳定镜头、每次 1-3 条活动路径、在主要概念上使用 illustrated/hero 图标，以及 flow 动画。从 assets/examples/illustrated-loop-spec.json（深色全景）或 assets/examples/swimlane-spec.json（浅色纸面色带）开始。

8. 交付

• 适用时内嵌显示 GIF。
• 发布和社交平台优先使用 MP4。
• 附上 PNG，方便快速查看。
• 需要可编辑时，附上 .excalidraw。
• 提供交互式 HTML，供探索或演示使用。
• 静态出版需要可缩放时，使用 SVG。

更改此 SKILL.md 后，请开启新任务或刷新会话，再测试触发行为。脚本和资源的更改可立即测试。