Archify 中文实战指南：把系统描述变成可校验、可交互的独立 HTML 系统地图

Archify 中文实战指南：把系统描述变成可校验、可交互的独立 HTML 系统地图

【免费下载链接】archifyAgent skill for beautiful, verifiable architecture, workflow, sequence,>项目地址: https://gitcode.com/GitHub_Trending/arch/archify

Archify 是一个基于 Node.js 的渲染与校验系统，以 Agent Skill 形式支持 Cursor、Claude Code、Codex CLI、OpenCode 和 Raven：Agent 负责生成 Typed JSON IR，Archify 负责校验并确定性编译为便携、独立的 HTML/SVG 成品。本篇基于仓库中文文档与配套源码、Schema、CLI 实现展开，覆盖安装、五类图选型、完整命令流程、结构化诊断修复、视觉预设与主题、探索分享能力以及多平台安装方式。读完你可以独立完成：在任意 Agent 对话中生成一张经过全部门禁校验的交互式架构图，并理解其背后的校验链与诊断机制。

一、Archify 是什么：Agent Skill 形态的图表交付系统

当前开发版本为v2.17.0-dev.1（与 archify/package.json 中的version字段一致），采用 MIT 许可证。它的定位可以用四句话概括：

• 打开就是成品—— 五种技术图、四套视觉预设、深浅主题、内置品牌徽标，以及显式启用的有限动态；
• 合并前先看清架构变化—— 把两份已校验快照对比为 Before / Delta / After，准确区分新增、删除、语义变化、移动和重路由；
• 每次探索都有依据—— 搜索节点、按需打开版本校验过的源码、追踪作者定义的上下游可达范围与精确路径、对比角色、播放故事，但不编造拓扑；
• 一个文件即可放心交付—— Typed JSON IR 和确定性校验生成独立 HTML，支持 PNG、SVG、WebM 与 1200×630 分享卡片。

从源码结构看，整个系统分为三层：

1. CLI 入口archify/bin/archify.mjs，统一分发render、validate、deliver、preview、compare、guide等子命令；
2. 渲染器archify/renderers/下五个目录分别实现 architecture、workflow、sequence、dataflow、lifecycle 五种图；
3. 共享校验与几何层archify/renderers/shared/ 提供 validator、diagnostics、geometry、brand-marks 等模块。

仓库的 SKILL.md 是 Agent 与 Renderer 之间的权威契约，规定了从“选择图类型”到“交付验收”的完整流程；本文的命令与行为描述均以该契约和源码为准。

二、安装：一条命令装进 Agent 工作流

2.1 标准安装

npx skills add tt-a1i/archify -g

显式、非交互地安装到 Cursor：

npx -y skills add tt-a1i/archify --skill archify --agent cursor --global --copy --yes

只想临时体验时（以 Codex CLI 为例）：

npx skills use tt-a1i/archify@archify --agent codex

2.2 其他集成入口

• DeepSeek Harness（社区集成、显式启用）：运行dsh plugin --profile web add @tt-a1i/archify-dsh@0.1.0，兼容范围、限制与安全说明见 integrations/deepseek-harness/README.md；
• Raven 仅支持 ZIP 手动安装：将 archify.zip 解压到~/.raven/workspace/skills，解压后得到~/.raven/workspace/skills/archify。

2.3 内置的更新检查机制

安装后的 Skill 包含一个低频、失败静默的发布检查，最多只显示可选更新提醒，绝不会自行下载或安装更新。其行为边界：

• 一次成功检查后，下次网络请求通常约在 72 小时（±20%）后发出；检查失败后，活跃使用可能在首次 6 小时、后续 24 小时退避到期时重试；
• 请求只访问https://tt-a1i.github.io/archify/skill-updates/archify/stable.json这一个清单地址；
• 检查器不发送本地版本、Agent、项目数据、用户输入、账户/设备标识，也不保存或回传 ETag；
• 如需完全关闭（包括网络请求和提醒状态写入），在 Agent 环境中设置ARCHIFY_UPDATE_CHECK_DISABLED=1。

SKILL.md 中的 "Update awareness" 一节进一步约束：更新通知只是信息而非许可，已安装的 Skill 保持不变，是否更新以及何时更新始终由用户决定。

三、快速开始：从一句描述到可交付成品

3.1 不需要绑定代码库

在任意 Agent 对话里直接描述系统即可：

用 Archify 画出：Browser -> API -> Redis 缓存 -> PostgreSQL 回源。

需要源码证据时，打开仓库后改用：

分析这个仓库，然后使用 archify 生成一张高层运行时架构图。 只保留 8–12 个核心组件，突出一条主要路径，并标出外部依赖与信任边界。 辅助信息放进说明卡片，不要继续增加连线。

3.2 在对话中细调

继续说增加 Redis、把鉴权移到左侧、突出回滚路径，Archify 会保留 Typed Source，只修改相关部分，而不是整图重画。

3.3 一个完整的 Typed JSON IR 长什么样

以仓库自带示例 archify/examples/web-app.architecture.json 为例，一个 architecture 源文件的核心结构是：

{ "schema_version": 1, "diagram_type": "architecture", "meta": { "title": "Sample Web App", "quality_profile": "showcase", "views": [ { "id": "request-path", "label": "Primary request path", "focus": ["users", "cdn", "lb", "api", "db"], "note": "Follow the primary customer request from the edge to durable state." } ] }, "components": [ { "id": "api", "type": "backend", "label": "API Server", "sublabel": "FastAPI :8000", "pos": [670, 300], "size": [130, 60] }, { "id": "cache", "type": "database", "label": "Redis", "sublabel": "cache :6379", "pos": [670, 150], "size": [130, 60] } ], "boundaries": [ { "kind": "region", "label": "AWS Region: us-west-2", "wraps": ["cdn", "lb", "api", "cache", "db", "s3", "queue", "worker"] }, { "kind": "security-group", "label": "sg-api :443/:8000", "wraps": ["lb", "api"] } ], "connections": [ { "id": "cache-read-through", "from": "api", "to": "cache", "label": "read-through", "fromSide": "top", "toSide": "bottom", "labelDy": -68 }, { "id": "api-sql", "from": "api", "to": "db", "label": "SQL" } ], "cards": [ { "dot": "emerald", "title": "Application", "items": ["FastAPI behind an HTTPS load balancer", "Redis read-through cache"] } ] }

几个值得注意的字段：

• components[].type限定为frontend、backend、database、cloud、security、messagebus、external七类（与 archify/schemas/common.schema.json 中componentType定义一致）；
• 连线可以显式指定fromSide/toSide端点侧和via折点、labelDy标签纵向偏移——但这些几何旋钮只在诊断要求时才加（见第五节）；
• meta.views最多五个引导章节，每个包含唯一id、读者可见的label和指向已有语义节点的非空focus列表；
• cards是 SVG 下方的摘要卡片块，用来承载“不要继续增加连线”的辅助信息。

3.4 SKILL.md 的受限创作路径

SKILL.md 的 "Fast authoring path" 对 Agent 规定了五步受限流程：

1. 从architecture、workflow、sequence、dataflow、lifecycle中选出图类型；
2. 只读一个匹配的 schema（schemas/下对应文件 +schemas/common.schema.json）和一个匹配示例（examples/下）——示例用于字段形状参考，不用于抄袭事实；新 workflow 源使用schema_version: 2；
3. Artifact first：下一个工具动作必须是写候选 JSON，先画一条清晰主路径、短侧支、稀疏标签、至多 12 个主节点；默认meta.quality_profile为showcase；诊断出现前不加via、channelX、channelY、labelAt，每轮修复最多施加一个几何控制；
4. 每次候选编辑后、交付前执行node bin/archify.mjs validate <type> <candidate.json> --quality showcase --json；通过的最终校验即冻结候选，之后不再编辑；
5. 交付 HTML 时用deliver作为最终验收命令。

同一份成品也可以在本机浏览器直接打开，例如 examples/web-app.html 即可体验完整 Viewer。

四、选择合适的图表类型

不知道选哪一种时，可以直接询问零依赖 CLI：

node archify/bin/archify.mjs guide "展示带 Redis 缓存未命中的 API 请求" node archify/bin/archify.mjs guide "梳理 Kafka Topic、消费者组、重放和死信队列" --json

SKILL.md 还给出了 Mermaid 输入的映射规则：flowchart/graph映射到workflow（或组件地图场景下的architecture），sequenceDiagram映射到sequence，stateDiagram映射到lifecycle——注意是读取 Mermaid 的拓扑与语义后重新创作Archify JSON，而不是机械渲染 Mermaid 样式。

Workflow 用泳道保持主路径清晰：

Sequence 解释一次交互随时间如何推进；Data Flow 突出数据移动和敏感边界；Lifecycle 区分正常进展、等待、重试和终态。五类图对应的 JSON 源与渲染结果均收录在 archify/examples/ 中（如 agent-tool-call.workflow.json、cache-miss-request.sequence.json、product-analytics.dataflow.json、agent-run.lifecycle.json）。

4.1 deployment-ownership 工程画像

做生产部署评审时，Architecture 可以按需启用deployment-ownership工程画像：负责人缺失、单一区域归属缺失、数据库未放入私有安全边界、或边界穿越机制缺失时会直接阻断校验。它不会被静默开启，只校验作者写入的事实，不代表线上基础设施已经核验。

校验事实清单（来自 archify/schemas/README.md）：

• 每个非external组件必须在tag中写明 owner，且恰好属于一个region；
• 文档必须同时包含region与security-group两种边界；
• 每个database必须位于某个security-group内；
• 每个安全组的成员必须来自同一共享 region；
• 任何 region 或安全组成员发生变化的连接，必须在label中写明真实的穿越机制。

如果某个事实未知，应省略该画像或先去获取事实，而不是编造。

4.2 Architecture Delta：合并前先看清架构变化

做设计或 PR 评审时，可以把两份已校验快照对比为 Before / Delta / After 与机器回执：

node archify/bin/archify.mjs compare architecture base.json head.json architecture-delta.html --json

精确选择任一作者变更，或播放一次有限 Review；全程只读，不推断影响、风险或合并安全。仓库内置了成对示例 checkout-platform.base.architecture.json 与 checkout-platform.head.architecture.json，对应成品见 examples/checkout-platform-delta.html。

五、工作原理：五步流水线与常用命令

仓库常用命令（在 skill 根目录archify/下执行，要求 Node.js ≥ 18，见 archify/package.json 的engines字段）：

node bin/archify.mjs doctor node bin/archify.mjs demo /tmp/archify-demo node bin/archify.mjs guide "展示 CI/CD 检查、审批、部署和回滚" node bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --quality showcase --json node bin/archify.mjs preview workflow examples/agent-tool-call.workflow.json /tmp/workflow.html --quality showcase node bin/archify.mjs deliver workflow examples/agent-tool-call.workflow.json /tmp/workflow.html --quality showcase --open --json

从 archify/bin/archify.mjs 的 usage 文本看，完整子命令集还包括：render（直接渲染）、migrate workflow <old> <new> --to-schema 2（workflow v1 固定布局到 v2 可读布局编译器迁移）、inspect、check（检查 HTML 成品）、visual-check（浏览器证据）、brands/brands capture <url>（品牌徽标查询与摘要固定捕获）、examples。

5.1 校验链：Schema → 布局 → 几何 → 交付门禁

“原子交付前校验”是 Archify 的核心设计：Schema、布局、HTML/SVG、线路和标签到其他路径的净空检查必须全部通过，Showcase 成品才会替换上一份可信结果。具体机制：

• 五种图各有一份 JSON Schema：workflow.schema.json、sequence.schema.json、dataflow.schema.json、lifecycle.schema.json、architecture.schema.json，共享定义在 common.schema.json。所有层级设置additionalProperties: false，未知字段会被拒绝而不是静默忽略；
• 生成式校验器：开发期scripts/generate-validators.mjs用 ajv 的 draft 2020-12 standalone 生成器（strict: true、allErrors: true）编译全部 schema，产物renderers/shared/generated-validators.mjs随 skill 一起提交和分发，运行时校验零 npm、零网络依赖；
• 跨集合事实：schema 之后，共享加载器再检查 JSON Schema 难以表达的事实，例如重复的 view ID、重复或指向不存在节点的 focus ID、同一关系集合内重复的作者关系 ID；
• 几何问题归渲染器：Schema 抓形状错误（类型、枚举、范围、未知字段），重叠、标签碰撞等几何问题是各渲染器的职责。

Schema 版本策略同样明确：workflow 同时支持 1 和 2 两个版本（v1 是固定布局兼容契约，v2 走可读工作流编译器），其余四图固定schema_version: 1；2.x 发布线内“今天能校验通过的文件必须保持能校验通过并渲染”。

quality_profile控制校验严格度：standard是日常密度，showcase是展示级门禁。SKILL.md 规定，只报 4 项 artifact 检查的回执只是基础校验，永远不算 showcase 通过；showcase 通过必须报告全部 9 项 artifact 检查、0 个构图错误、0 个警告。

5.2 preview：显式启用的桌面创作循环

preview是显式启用的桌面创作模式，不是默认后台服务。从 archify/bin/preview.mjs 的源码可以确认其边界：

• 只在127.0.0.1上以server.listen(0, loopbackHost)方式监听随机端口（loopback 常量127.0.0.1硬编码在源码中）；
• 只观察指定 JSON，只有最新候选通过全部门禁才刷新，半写入或无效保存时继续显示上一份验证成品；
• 通过 Ctrl-C 停止；测试或准备手动打开打印出的本地 URL 时可加--no-open；
• 生成的 HTML 不携带 Preview Runtime。

deliver --open适合一次性的本地交互交付：默认关闭，且只在验证成品原子提交后执行；系统无法打开时交付仍保持成功，JSON 只写 stdout，stderr 给出可手动打开的绝对路径。

deliver本身会把精确的规格字节冻结成同目录私有快照，渲染并检查该快照，原子提交 HTML，并报告规格与成品的 SHA-256 及字节数——这是确定性 artifact 证据。交付之后还可以运行node bin/archify.mjs visual-check <output.html> --json收集有界的浏览器证据（不修改、不重渲染受信任 HTML）。SKILL.md 强调三条声明必须分开：deliver证明确定性 artifact 检查，visual-check证明真实浏览器中的有界行为，感知层面的视觉复核需要真人或图像能力评审者。

六、失败时的结构化诊断与聚焦修复

失败时，validate --json和deliver --json仍然只输出一个 JSON 对象。读取diagnostics[]，只修改其中subject指向的对象，并使用supportedFixes列出的修复方式；不要整图重写，也不要突破 Skill 最多两轮的聚焦修复上限。确定性诊断仍不等于视觉复核。

从 archify/renderers/shared/diagnostics.mjs 的源码结构看，每条诊断在抛出前都会经过normalizedDiagnostic归一化，保留subject（出问题的对象，如{ type }、{ input }、带id/label的节点路径）、evidence（测量证据）和去重后的supportedFixes数组；CLI 参数错误也走同一套archifyArgument结构（code、subject、evidence、supportedFixes），而不是自由文本。SKILL.md 给出的修复纪律是：只改被诊断的subject、核对evidence、从supportedFixes中选择；当客观错误数达到新低就继续聚焦修正，若连续两轮没有改进最优错误数，就停止并如实汇报未解决的诊断。

架构级诊断示例（来自 archify/schemas/README.md 的错误格式说明）：

workflow schema validation failed: /nodes/3 (id/label: "router") must NOT have additional properties {"additionalProperty":"colour"}

实例路径会标注最近包围元素的id或label，让 Agent 能精确定位到“哪个对象”而不是“哪段日志”。

七、动态、视觉预设、主题与本地化

动态和演示样式需要显式选择，在源文件meta中声明：

{ "meta": { "locale": "zh-CN", "animation": "trace", "visual_preset": "signal-flow" } }

各字段语义（以 archify/schemas/README.md 的契约为准）：

• animation：省略或设为"none"时结果完全静态；"trace"显式开启生成 HTML 中的 SVG/CSS 动效；
• visual_preset：classic是稳定默认；signal-flow是偏运动的发光呈现；blueprint是高对比工程评审风格；editorial是暖纸张与深墨色的编辑风格，适合设计评审、发布说明和技术文档——预设只改 Viewer 样式，不改变语义 ID 或几何；
• locale："en"或"zh-CN"，选择<html lang>、默认图例、无障碍文案和所有固定 Viewer UI；不会机器翻译作者编写的标题、节点、关系、章节和卡片。未带该字段的旧文件仍然有效并默认英文。对于其他创作语言，应省略meta.locale、保持 authored content 使用用户要求的语言，并告知用户固定 Viewer UI 与<html lang>回退为英文，该成品不属于完整本地化；
• Sequence 的column_fit：默认fixed保持历史 108px 列间距与 86px 参与者盒子，画布再宽坐标也不变；spread从 viewBox 推导间距与盒宽，把宽画布转化为列距和标签空间而不是右侧空白，泳道顺序、ID 与消息语义不变；
• meta.views：最多五个引导章节，用于“播放故事”；
• meta.legend：支持mode: auto | all | hidden与按渲染器支持的 kind 覆盖label/visible；标签只是呈现层，不重命名稳定 kind、不改变节点与关系事实；
• 品牌徽标：语义节点可携带一个可选brand，取archify brands --json返回的规范内置 ID，或archify brands capture <url> --json返回的{ "url", "sha256" }摘要固定对象；渲染与校验从不执行未固定的网络捕获，不安全、不可用、已变更或不支持的内容会失败关闭。

同一张图，两套主题，一键切换（深色 / 浅色）：

八、探索与分享：交互不编造拓扑

生成 HTML 内置完整的读者能力（不是额外的创作工作）：

稳定链接可以恢复#focus=<id>、#focus=<id>&reach=upstream|downstream、#relation=<id>、#route=<source>~<target>、#lens=<kind>~<kind>和#view=<view-id>。读者触发的动态有限运行、遵守prefers-reduced-motion，并且不会进入标准导出。

导出与分享方面：

• Export 菜单支持复制 PNG，并下载静态或动态格式；导出永远是完整原图，不携带临时 Viewer 状态；
• 需要 README、Release 或社交平台的标准 1200×630 图片时，使用Copy Share Card；
• 路径解析后，Export → Route Share Card会把真实路径下载为 1200×630 PNG，并保留完整拓扑上下文；
• 完成 authoredUpstream/Downstreamreach 后，Export → Reach Share Card捕获这次阅读结果，但不冒充运行时影响分析——可达范围始终是作者定义的关系事实，不是推断出的真实故障传播。

有证据的 Architecture 节点会显示SRC n标记，点击可打开由 Git 校验、固定到公开 commit 的文件与行号。其机制（见 archify/schemas/README.md）：meta.repository声明公开 GitHub URL 与完整 commit SHA，组件可携带一至三个sources（仓库相对 POSIX 路径、可选行范围与标签）；渲染时要求--repo-root，本地 Git origin 必须匹配，且 Git 必须证明 commit、blob 与请求的行都存在。已验证证据嵌在标准 SVG 之外，供 Semantic Passport 与 Node Finder 使用；普通成品与视觉导出不携带仓库证据。

九、多平台安装方式对照

十、边界、参考与参与方式

Archify 不是通用绘图编辑器，也不是 Mermaid 主题——它负责把技术意图变成可交流的成品。自动 Mermaid Parser、通用自动布局、托管分享服务和 WYSIWYG 编辑器目前都不在产品范围内。

深入阅读的参考材料（均为仓库内文件）：

• archify/schemas/README.md —— JSON IR Schema 说明、图例契约、品牌徽标、schema_version 政策与错误格式；
• archify/SKILL.md —— Skill 与 Renderer 的完整契约（创作路径、交付、Viewer 能力）；
• archify/examples/ —— 五类图的 JSON 源与渲染结果；
• archify/references/ ——authoring-contract.md（字段枚举、间距数学、几何修复规则）、delivery-contract.md（交付回执字段与退出行为）、viewer-runtime.md（Share Cards、深链、演示等 Viewer 运行时特性）、brand-marks.md；
• docs/authoring-cookbook.zh-CN.md —— Agent 编图手册（中文版，另有 英文版）；
• CHANGELOG.md —— 版本历史（当前开发版本v2.17.0-dev.1）；
• ROADMAP.md —— 路线图。

参与贡献：欢迎提交 Issue、Pull Request 和真实场景图。较大功能或行为调整先通过 Issue 对齐价值、兼容边界和非目标，再基于最新main开发；一个 PR 尽量只解决一个问题；核心代码和回归测试先行，生成物最后统一重建。项目坚持 Agent-first，优先完善稳定的机器可读诊断和现有权威合同。仓库测试入口为npm test（在archify/下执行），会依次运行品牌徽标检查、校验器漂移检查、发布身份检查、golden 测试与全量测试套件。

适用前提小结：命令行流程需要 Node.js ≥ 18 与本地 shell 访问；deliver的确定性回执不替代浏览器视觉复核；deployment-ownership画像只校验作者写入的事实；Reach / 路径 / 透镜类交互只复用作者定义的拓扑，不输出运行时影响结论。

【免费下载链接】archifyAgent skill for beautiful, verifiable architecture, workflow, sequence,>项目地址: https://gitcode.com/GitHub_Trending/arch/archify