Archify 技能安装与使用指南

Archify 是一个专业技术图表生成技能，能将自然语言描述或 Mermaid 代码转化为精美的自包含 HTML 图表。每张图都内置暗色/亮色主题切换、一键导出（PNG / JPEG / WebP / SVG），零依赖即可在浏览器中打开。

---

目录

1. 支持的图表类型
2. 安装步骤
3. 快速上手
4. 五种图表详解
5. Mermaid 转换
6. 常见问题

---

1. 支持的图表类型

类型	用途	典型场景
architecture	系统组件、云资源、安全边界	微服务架构图、云基础设施图、网络拓扑图
workflow	技术流程、审批流、CI/CD	发布流水线、审批流、操作 runbook
sequence	API 调用链、请求生命周期	接口调用时序、缓存穿透流程、认证流程
dataflow	数据管道、ETL、数据血缘	大数据管线、数据仓同步、PII 隔离边界
lifecycle	状态机、生命周期、状态转换	订单状态流转、Agent 生命周期、任务状态机

---

2. 安装步骤

方式一：从 GitHub 一键安装

直接在 Tokeny 对话中输入：

安装技能 https://github.com/tt-a1i/archify

系统会自动识别为 install_skill_from_url，克隆仓库并注册技能。

方式二：手动下载后从工作空间安装

# 1. 克隆仓库
git clone https://github.com/tt-a1i/archify.git

# 2. 将 archify/ 目录放入你的工作空间

# 3. 在 Tokeny 中说：安装 archify 技能

安装渲染器依赖（推荐）

渲染器使用 Node.js 和 ajv 进行 JSON Schema 校验：

cd archify-skill   # 或你的技能目录名
npm install

即使不安装，渲染器仍可运行（仅跳过 schema 校验），内置的布局检查不受影响。

---

3. 快速上手

安装完成后，在 Tokeny 中激活技能：

/archify 画一个简单的微服务架构图：用户 -> Nginx -> API -> PostgreSQL

技能会：

1. 自动识别为 architecture 类型
2. 生成 JSON 输入文件
3. 调用渲染器生成 .html 输出
4. 自检通过后打开预览

输出文件是一个自包含的 HTML，双击即可在浏览器中查看，支持主题切换和导出。

---

4. 五种图表详解

4.1 架构图（Architecture）

触发词：架构图、系统图、云架构、基础设施图、网络拓扑

用法示例：

/archify 画一个电商系统的云架构图：
- 用户通过 CDN 访问
- Nginx 负载均衡
- API 服务集群（3 副本）
- Redis 缓存
- PostgreSQL 主从
- RabbitMQ 消息队列 + 异步 Worker
- 用 AWS region 边界框包裹

输出效果：组件自由摆放、region/security-group 边界框自动计算、连线自动路由、图例自动生成。

---

4.2 工作流图（Workflow）

触发词：工作流、流程图、审批流、CI/CD、发布流水线、runbook

用法示例：

/archify 画一个代码发布工作流：
开发 -> Code Review -> 自动化测试 -> 预发布环境 -> 生产审批 -> 部署上线

结构特点：

• 使用泳道（lane）分组参与者
• 节点按列（col）顺序排布
• 支持 blocking tag、条件分支、回滚路径

Mermaid 转换：

/archify 把这个 Mermaid 转成 archify 工作流：

flowchart LR
    A[PR Open] --> B{CI Pass?}
    B -->|Yes| C[Deploy Staging]
    B -->|No| D[Fix & Retry]
    C --> E[Manual Approve]
    E --> F[Deploy Prod]

---

4.3 时序图（Sequence）

触发词：时序图、调用链、交互流程、请求生命周期、谁调用谁

用法示例：

/archify 画一个缓存穿透的请求时序：
浏览器 -> API -> Redis(缓存未命中) -> PostgreSQL -> 回写缓存 -> 返回 JSON

结构特点：

• 参与者按索引均匀排列（最多 8 个）
• 消息用 y 坐标定位，支持激活条（activation）
• 可用 segment 标注阶段（如 "01 / AUTH"）

---

4.4 数据流图（Dataflow）

触发词：数据流、数据管道、ETL、数据血缘、PII 治理

用法示例：

/archify 画一个用户行为分析数据流：
Web App 埋点 -> Kafka -> Flink 实时处理 -> ClickHouse 存储 -> Grafana 看板
同时标注 PII 数据路径

结构特点：

• 使用 stage（阶段列）和 row（行）网格布局
• 每条 flow 必须带 label，可用 classification 标注敏感级别
• 支持 PII touch / approved only / non-PII 分类

---

4.5 生命周期图（Lifecycle）

触发词：状态图、生命周期、状态机、状态转换、重试流程

用法示例：

/archify 画一个订单生命周期：
已创建 -> 已支付 -> 拣货中 -> 已发货 -> 已签收
包含异常路径：支付超时、用户取消、退货退款

结构特点：

• main lane 必选（主流程阶段）
• terminal lane 放终止态（成功/失败/取消）
• 其他 lane 共享中断事件区域
• 支持 step 编号、tag 标注

---

5. Mermaid 转换

Archify 支持将 Mermaid 代码作为输入方言，读取其结构和语义后按 archify 风格重新布局：

Mermaid 类型	Archify 映射
flowchart / graph	workflow（组件图则用 architecture）
sequenceDiagram	sequence
stateDiagram	lifecycle

用法：直接粘贴 Mermaid 代码块，说明"转成 archify 风格"即可。

/archify 转成 archify 风格：

stateDiagram-v2
    [*] --> Idle
    Idle --> Running: start
    Running --> Paused: pause
    Running --> Stopped: stop
    Paused --> Running: resume
    Stopped --> [*]

注意：Mermaid 的样式（颜色、粗细等）会被丢弃，只保留拓扑结构。布局由 archify 从零编排——这正是它的价值所在。

---

6. 常见问题

Q: 生成的 HTML 文件在哪里？

A: 在技能目录下，文件名由 meta.output 字段指定。你也可以用 Tokeny 的预览功能直接查看。

Q: 如何修改已生成的图？

A: 修改对应的 .json 输入文件后重新运行渲染器：

node renderers/架构类型/render-架构类型.mjs 输入.json 输出.html

Q: 中文标签是否支持？

A: 完全支持。渲染器对 CJK 文字按双倍宽度自动测量，确保不溢出、不重叠。

Q: 导出图片时文字模糊怎么办？

A: 导出菜单支持最高 4× 分辨率渲染。大尺寸图表会自动降为 3×/2× 以防超过浏览器 Canvas 限制。

Q: 暗色模式下导出 SVG 在 GitHub 上显示异常？

A: Archify 导出的 SVG 是双主题自包含的，会自动跟随宿主页面的 prefers-color-scheme。在 GitHub README 中引用时会根据用户系统主题自动适配。

Q: 渲染器报错怎么办？

A: 错误信息会精确指出问题所在的 JSON 路径和修复建议（如坐标越界、组件重叠、标签碰撞等）。根据提示修改 JSON 后重试，不要直接改渲染器代码。

---

快速参考卡片

安装：/archify 或 install_skill_from_url github.com/tt-a1i/archify

使用：/archify <自然语言描述或 Mermaid 代码>

图类型自动识别关键词：
  架构图/系统图/云架构     → architecture
  工作流/流程图/审批/CI-CD  → workflow
  时序图/调用链/交互流程     → sequence
  数据流/ETL/管道/血缘      → dataflow
  状态图/生命周期/状态机     → lifecycle

输出：自包含 HTML，支持主题切换 + PNG/JPEG/WebP/SVG 导出

---

GitHub 仓库：tt-a1i/archify
许可证：MIT
版本：v2.6