# Soia Dev Archify Diagrams

> 用 Archify 将架构、数据流和流程说明生成可维护 JSON 图表及 PNG 预览。触发：「用 Archify 画」「Archify 架构图」「Archify 时序图」

- Skill: `soia-team/soia-dev-archify-diagrams` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add soia-team/soia-dev-archify-diagrams`
- Raw SKILL.md: https://api.skillmd.com/api/skills/soia-team/soia-dev-archify-diagrams/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: soia-team (https://skillmd.com/u/soia-team)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/soia-team/soia-dev-archify-diagrams

---


# soia-dev-archify-diagrams

Use this skill to turn architecture and process explanations into polished Archify diagrams with maintainable JSON source files and README-friendly PNG previews.

The skill owns the reusable workflow and helper scripts. Archify itself remains an external renderer.

```text
soia-dev-archify-diagrams/
├── SKILL.md
├── scripts/
│   ├── render-archify-diagrams.mjs
│   └── export-archify-previews.mjs
└── assets/examples/
    ├── minimal-architecture.architecture.json
    ├── minimal-dataflow.dataflow.json
    └── minimal-workflow.workflow.json
```

## 客户可读说明

### 这个技能可以做什么

Draw, improve, validate, or publish Archify architecture / data-flow / sequence / lifecycle diagrams with JSON IR and PNG previews

| 客户想要 | 技能会做 | 客户能看到 |
|---|---|---|
| 完成本技能覆盖的工作 | 读取用户请求、必要上下文和本技能正文流程，执行最小可靠步骤 | 客户会看到执行计划、命令输出摘要、代码/文档变更、验证结果和风险说明。 |
| 缺少依赖、权限、配置或 key | 停止需要外部状态的动作，明确指出缺什么 | 安装命令、申请地址、配置路径或需要客户确认的问题 |
| 执行完成 | 汇总成功、跳过、失败、文件变更和验证结果 | 一段可复制进工单/日志的完成回执 |

### 客户如何使用

1. 用自然语言说明目标，并提供必要输入：文件、URL、repo、workspace、proposal、vault 或平台账号状态。
2. 能 dry-run 或预览的动作先给预览；涉及删除、覆盖、发送、发布、写远端状态时先征求客户确认。

### 依赖与安装

仅在客户明确选择整个 dev 插件时安装：

```bash
claude plugin marketplace add soia-team/soia-open-skills
```

```bash
claude plugin install soia-dev@soia
```

Codex 整域入口为 `codex plugin marketplace add soia-team/soia-open-skills` 与 `codex plugin add soia-dev@soia`；仍须先确认安装范围。

默认在已选项目内定向安装；不加全局或全部宿主参数。同一使用范围选插件或单技能一种来源：

```bash
npx skills add soia-team/soia-open-dev-skills -a <agent> -s soia-dev-archify-diagrams -y
```

配置约定：

```text
~/.config/soia-skills/soia-dev-archify-diagrams/config.yml
SOIA_DEV_ARCHIFY_DIAGRAMS_CONFIG_FILE=<custom-config-path>
```

- 如果本技能不需要私有配置，可以不创建 `config.yml`。
- 凭据只进 provider 官方登录态或系统凭据库，不进入普通 config、命令或日志；私有 config 只保存路径和非秘密偏好。
- 第三方 skill 只能声明依赖和安装方式，不直接修改第三方 skill 文件。

**WorkBuddy** 的装载单位是角色化专家而不是插件，`npx skills add -a '*'` 覆盖不到它，需要单独安装，见 [docs/install/workbuddy.md](https://github.com/soia-team/soia-open-skills/blob/main/docs/install/workbuddy.md)。

### 输出目录契约

输出目录按以下优先级解析：

1. 命令行 `--output-dir <path>`；
2. 进程环境变量或私有配置中的 `ARCHIFY_OUTPUT_DIR`；
3. 安全默认值 `~/Downloads/soia-dev-archify-diagrams/`。

`--output-dir` 可以是绝对路径或相对当前工作目录的路径。技能不会把用户交付物默认写入当前目录，也不会把 `~/.soia/workspaces/` 当作通用输出目录。

按交付场景显式指定目录：

- 仓库 README / 文档：`--output-dir assets/diagrams`；
- 已明确确认的 SOIA proposal：`--output-dir <workspace>/proposals/<proposal-id>/design/diagrams`；
- 普通临时预览或未指定项目目录：使用上述 `~/Downloads/soia-dev-archify-diagrams/` 默认值。

使用 `--png-only` 时，HTML 只作为输出目录内的临时中间文件，PNG 导出成功后会删除 HTML；不使用 `--png-only` 时保留 HTML，便于浏览器预览和排错。

### 日志与完成回执

每次执行都要让客户看见过程和结果。最低回执格式：

```markdown
完成：<一句话说明本次完成了什么>。

日志摘要：
- started: <检查到的输入/配置/依赖，不打印秘密值>
- processed: <数量或范围>
- created/updated: <数量或路径>
- skipped/failed: <数量和原因>

文件变化：
- <绝对路径或“未改动文件”>

验证：
- <运行过的检查、命令或人工核对点>

问题与下一步：
- <缺 key / 缺依赖 / 需要客户确认 / 建议下一条命令；没有则写“无”>
```

## Choose Diagram Type

| User intent | Archify type | JSON suffix |
|---|---|---|
| System components, repos, services, local directories, runtime boundaries | `architecture` | `.architecture.json` |
| Installation paths, data movement, lineage, where files flow | `dataflow` | `.dataflow.json` |
| Maintenance process, approval flow, tool-call flow, CI/release steps | `workflow` | `.workflow.json` |
| Who calls whom over time, request/response, fallback behavior | `sequence` | `.sequence.json` |
| State/status transitions, terminal outcomes, retry/cancel paths | `lifecycle` | `.lifecycle.json` |

If a rough Mermaid flowchart mixes components and process, choose one story and split the rest into a second diagram.

## Diagram Rules

1. Keep JSON IR as the source of truth.
2. Generate HTML as a render/check intermediate; with `--png-only`, delete it after PNG export succeeds.
3. Commit PNG previews for README-visible diagrams.
4. Do not commit generated HTML unless the user explicitly asks for interactive diagrams.
5. Make the main path left-to-right.
6. Put side concerns in cards, not in long crossing arrows.
7. Use few edge labels; label only non-obvious boundaries, policy/security paths, or async/batch paths.
8. Run Archify `validate`, `render`, and `check` before claiming the diagram is done.

## Standard Layout

For repository README/docs diagrams, prefer:

```text
assets/diagrams/
├── <slug>.architecture.json
└── <slug>.png
```

For an explicitly confirmed SOIA proposal, write diagrams under:

```text
<workspace>/proposals/<proposal-id>/design/diagrams/
```

Do not infer a proposal workspace from the current directory, and do not hardcode a maintainer-specific workspace path in SKILL.md, JSON examples, README files, or scripts. If the caller has not supplied a project destination, use the output-directory contract above.

## Setup

Do not copy the Archify upstream source into a skill repository. Use one of these locations at runtime:

1. Explicit binary: `ARCHIFY_BIN=<path-to-archify.mjs>`
2. Command arg: `--archify-root <path-to-archify-root>`
3. Explicit root: `ARCHIFY_ROOT=<path-to-archify-root>`
4. Installed skill locations:
   - `.agents/skills/archify` (current workspace)
   - `~/.gemini/antigravity-cli/skills/archify`
   - `~/.agents/skills/archify`
   - `~/.codex/skills/archify`
   - `~/.claude/skills/archify`

If Archify is not available, clone it outside the skill repo and point `ARCHIFY_ROOT` to that checkout:

```bash
git clone https://github.com/tt-a1i/archify.git <workspace>/archify
cd <workspace>/archify/archify
npm install
```

## Render Workflow

Render all diagrams in a directory and keep only JSON + PNG:

```bash
node skills/soia-dev-archify-diagrams/scripts/render-archify-diagrams.mjs \
  --dir assets/diagrams \
  --output-dir assets/diagrams \
  --png-only \
  --theme light \
  --width 1400 \
  --height 1000 \
  --scale 2
```

Render one diagram:

```bash
node skills/soia-dev-archify-diagrams/scripts/render-archify-diagrams.mjs \
  --file assets/diagrams/system.architecture.json \
  --output-dir assets/diagrams \
  --png-only
```

The helper:

- Finds `*.architecture.json`, `*.workflow.json`, `*.sequence.json`, `*.dataflow.json`, and `*.lifecycle.json`
- Runs `archify validate`
- Runs `archify render`
- Runs `archify check`
- Writes HTML previews to the resolved output directory
- With `--png-only`, exports PNG previews to the same directory and deletes temporary HTML files
- Without `--output-dir`, uses `ARCHIFY_OUTPUT_DIR` and then `~/Downloads/soia-dev-archify-diagrams/`

## README Preview Workflow

GitHub README should use committed PNG previews:

1. Render Archify HTML.
2. Export a PNG preview.
3. Delete the temporary HTML.
4. Commit JSON source and PNG preview.
5. Embed the PNG directly.

Use the bundled exporter when HTML already exists:

```bash
node skills/soia-dev-archify-diagrams/scripts/export-archify-previews.mjs \
  --dir assets/diagrams \
  --output-dir assets/diagrams \
  --theme light \
  --width 1400 \
  --height 1000 \
  --scale 2
```

Markdown:

```markdown
![Diagram](assets/diagrams/example.png)
```

Centered HTML:

```html
<p align="center">
  <img src="assets/diagrams/example.png" alt="Example architecture diagram" width="100%">
</p>
```

## Minimal JSON Patterns

Start from `assets/examples/` when creating new diagrams. Use the suffix to select the renderer:

- `*.architecture.json`
- `*.dataflow.json`
- `*.workflow.json`

Keep examples generic. Do not include personal directories, private repo paths, tokens, cookies, or private workspace names.

## Layout Debugging

Archify validation errors are usually actionable. Apply its suggestions directly:

- label collision: set `labelDy`, `labelDx`, `labelAt`, or `labelSegment`
- node collision: move `row` / `col`, change `pos`, or reduce `size` / `width`
- short workflow edge: skip adjacent columns or route through `drop` / `bottom-channel`
- viewBox overflow: increase `meta.viewBox` or reduce node count

Do not ignore overlap errors. Fix JSON and re-render.

## Output Checklist

Before final response:

- JSON IR exists and is ready to commit.
- Temporary HTML rendered and passed `archify check`.
- README PNG exists if the diagram should be visible on GitHub.
- README-visible diagram HTML was deleted unless explicitly requested.
- Markdown links/images resolve locally.
- Report the resolved output directory and whether it came from `--output-dir`, `ARCHIFY_OUTPUT_DIR`, or the safe default.
- Report which scripts were used and which checks passed.

## 私密信息与中间数据

只读取客户授权的图表与素材，不上传源文件；JSON 和交付预览写指定输出，临时数据使用 OS 临时目录。凭据不进入配置、图表或回执。脚本生成的 HTML 仅在本次成功导出并确认属于临时输出后清理；不自动提交、发布或安装 Archify。

## 前向验证

使用 assets/examples 中的公开 fixture 或客户授权图表，实际运行 validate → render → check，核对节点/边与 PNG 预览，不只检查退出码。缺少真实 Archify 时可检查输入和包装器，但必须保留实际渲染未验证的说明。