Archify 图作者手册从 JSON 源文件到可信交付物的完整命令行工作流【免费下载链接】archifyAgent skill for beautiful, verifiable architecture, workflow, sequence,>项目地址: https://gitcode.com/GitHub_Trending/arch/archifyArchify 是一套面向 Agent 的架构图生成 Skill它把自然语言描述编译为五种类型架构、工作流、时序、数据流、生命周期的可验证 HTML/SVG 图。本手册以docs/authoring-cookbook.md为主线展开讲解集成者、贡献者与排障者真正需要的手动工作流如何检查安装、选择图类型、编写单一有界的 JSON 源文件、用validate与inspect校验、用deliver原子交付、用compare对比架构快照最后用visual-check收集浏览器证据。读完你将掌握 Archify CLIarchify/bin/archify.mjs从源文件到可信交付物的完整调用链以及故障回执repair receipt中diagnostics[]、supportedFixes的正确消费方式。1. 面向 Agent 的 Skill还是手动工作流Archify 本质上是Agent-facing Skill。普通用户可以要求任何具备 Skill 能力的 Agent 直接生成图无需学习 schema也无需亲自运行validate、inspect或deliver。下面这套手动流程是为三类人群准备的参考集成者把 Archify 嵌入自己的 Agent 或 CI 管道贡献者为仓库提交新场景、修复渲染器或校验规则排障者当 Agent 自动生成失败、或需要精确控制交付物时逐条核对。本手册中的命令假设你位于仓库的archify/目录或在已安装 Skill 的根目录下执行。CLI 的完整命令面可以在 archify/bin/archify.mjs 的usage()中查看其子命令包括render、compare、deliver、preview、validate、migrate、inspect、check、visual-check、guide、brands、examples、doctor与demo。2. 检查安装doctor 与环境前提Archify 要求Node.js 18 或更高版本。在编写任何图之前先运行诊断命令node bin/archify.mjs doctordoctor并不是一次简单的版本检查。从 commandDoctor 实现 可以看到它逐项验证Node.js 主版本是否 ≥ 18核心模板assets/template.html是否存在示例渲染器、Live Preview 运行时、visual-check 运行时、输出路径安全模块是否就位场景配方指南recipes/scenarios.mjs是否存在渐进式作者参考references/authoring-contract.md、viewer-runtime.md、delivery-contract.md是否齐全Architecture 对比运行时与证明夹具delta/architecture-delta.mjs及examples/checkout-platform.base/head.architecture.json独立 schema 校验器renderers/shared/generated-validators.mjs能否为全部五种类型导出校验函数五种类型的render-type.mjs、type.schema.json与对应示例文件是否成组存在。只有当所有检查通过、且缺失文件数为零时doctor才会输出Archify is ready.任何一项缺失都会以非零退出码结束。对于从 npm 兼容的 Skill 工具链安装的用户全局安装命令为npx skills add tt-a1i/archify -g3. 选择图类型五种模式与场景向导先想清楚这张图要让读者回答什么问题再选择类型。官方对照表如下类型适用场景推荐起点architecture组件、服务、存储与边界examples/web-app.architecture.jsonworkflow有序工作流、审批、分支与 runbookexamples/agent-tool-call.workflow.jsonsequence调用、返回、缓存未命中与时序examples/cache-miss-request.sequence.jsondataflow数据移动、转换与消费方examples/product-analytics.dataflow.jsonlifecycle状态、重试、等待与终态examples/agent-run.lifecycle.json注意上表路径均位于archify/examples/目录例如架构示例的实际位置是 archify/examples/web-app.architecture.json。这五类文件同时被doctor与examples子命令引用是比从零抄大图更安全的起点。当类型不明确时使用内置场景向导。它会根据自然语言提问推荐类型并返回一份配方recipe但不会替你生成图node bin/archify.mjs guide Show an API request with a Redis cache miss --json向导底层是 archify/recipes/scenarios.mjs 中的场景配方库。每个配方都带有中英文双语的signals关键词与权重、useWhen/avoidWhen判断、以及include建议。例如system-overview→architecture适合新人上手、方案评审与仓库梳理deployment-ownership→architecture启用engineering_profile适合云上评审与多区域规划agent-tool-call→workflow适合解释 Agent Runtime、MCP/工具编排与审批delivery-workflow→workflow适合 CI/CD 设计与发布评审incident-runbook→workflow适合故障预案与 On-call 交接api-request→sequence适合 API 调用链与缓存回退。guide支持--lang en|zh切换配方语言不带查询参数时--json模式会列出全部可用配方。4. 编写一个有界的源文件每个图都从一个清晰的故事开始。首图建议控制在8–12 个主节点、一条主路径只保留有助于回答问题的分支。仓库中已检入的示例是比复制大图更安全的起点。4.1 最小 IR 骨架每个源文件都必须包含四个要素schema_version——当前 architecture/sequence/dataflow/lifecycle 固定为1workflow 支持1与2新工作流建议用 v2详见下文diagram_type——五选一meta.title——图的标题该渲染器要求的结构化数组——见 archify/schemas/README.md 中的逐模式对照Schema 文件治理的diagram_type结构化数组workflow.schema.jsonworkflowlanes、phases、groups、mainPath、nodes、edgessequence.schema.jsonsequenceparticipants、segments、messages、activationsdataflow.schema.jsondataflowstages、nodes、flowslifecycle.schema.jsonlifecyclelanes、states、transitionsarchitecture.schema.jsonarchitecturecomponents、boundaries、connections所有模式 schema 都在每一层设置了additionalProperties: false未知字段会被拒绝而不是静默忽略跨集合事实重复的 view ID、指向不存在节点的 focus ID、重复的关系 ID由renderers/shared/validator.mjs在 schema 校验之后另行检查。meta还接受可选的animation: trace生成 HTML 中的 SVG/CSS 动效、locale: en|zh-CN只本地化 Viewer 界面与图例不翻译作者内容、visual_presetclassic/signal-flow/blueprint/editorial以及最多五个引导视图views。4.2 以 web-app 为例读懂架构 IR以 archify/examples/web-app.architecture.json 为例{ schema_version: 1, diagram_type: architecture, meta: { title: Sample Web App, output: web-app-rendered.html, quality_profile: showcase, views: [ { id: request-path, label: Primary request path, focus: [users, cdn, lb, api, db], note: ... } ] }, components: [ { id: users, type: external, label: Users, pos: [40, 300], size: [120, 60] }, { id: api, type: backend, label: API Server, sublabel: FastAPI :8000, pos: [670, 300], size: [130, 60] } ], boundaries: [ { kind: region, label: AWS Region: us-west-2, wraps: [cdn, lb, api, cache, db, s3, queue, worker] } ], connections: [ { id: users-to-cdn, from: users, to: cdn, label: HTTPS, variant: emphasis } ], cards: [ { dot: cyan, title: Edge, items: [CloudFront CDN fronts all traffic] } ] }值得注意的语义约定componentType只取frontend、backend、database、cloud、security、messagebus、external七种variant取default、emphasis、security、dashed。关系上的label是语义数据——当标签与路由冲突时修复顺序是移动标签 → 调整路由/间距 → 在保留语义的前提下缩短措辞删除标签不属于合法的间距修复。所有 ID 遵循^[a-zA-Z][a-zA-Z0-9_-]*$模式且在同一集合内必须唯一。4.3 仓库证据Repository Evidence对于需要反映真实代码的 Architecture 图可以在 JSON 中加入修订固定的仓库元数据与源码范围然后把本地仓库路径传给命令node bin/archify.mjs validate architecture path/to/diagram.json \ --repo-root path/to/repository --quality showcase --json校验器会核对 Git origin、commit、blob 与请求的行范围。Archify 在meta.repository公开 URL 完整 commit SHA与组件上的sourcesrepo 相对路径、可选行范围、可选标签形状通过 schema 校验后要求必须提供--repo-root本地 Git origin 必须匹配Git 必须证明该 commit、blob 与行确实存在。当仓库或修订无法验证时绝不添加源码证据。从 CLI 实现看--repo-root目前仅对architecture类型开放其他四种类型会以cli/unsupported-option拒绝见 assertEvidenceType。已验证的证据会嵌入生成 HTML 的archify-source-evidence-data脚本中供 Semantic Passport 与 Node Finder 使用普通文档与视觉导出不携带任何仓库证据。5. 验证validate、质量档位与修复回执5.1 探索用 standard交付用 showcasenode bin/archify.mjs validate architecture examples/web-app.architecture.json \ --quality showcase --json探索阶段用standard允许更密集的图打磨交付物或检入证明时用showcase。--quality在 CLI 中解析为环境变量ARCHIFY_QUALITY_PROFILE传给渲染器见 extractQualityArgs只接受standard与showcase两个值其他值以cli/invalid-option-value拒绝。注意只有 4 项 artifact 检查的通过不算 showcase 验收——showcase 通过必须报告全部 9 项 artifact 检查、0 个 composition 错误与 0 个警告。5.2 成功与失败的回执结构成功时JSON 回执包含 artifact 检查结果checks[]与合成摘要composition含profile、status、errors、warnings。失败时回执包含stage与diagnostics[]{ schemaVersion: 1, ok: false, command: validate, stage: check, diagnostics: [ { code: composition/label-route-clearance, severity: error, message: Final artifact failed composition/label-route-clearance., subject: { relationship: cache-read-through }, evidence: { ...: measured metrics }, supportedFixes: [adjust labelAt, labelDx, labelDy, labelSegment, ...] } ] }修复的正确姿势是只修改diagnostics[]中被点名的subject核对evidence并且只采用supportedFixes中列出的修复手段然后重新运行 validate。底层维护了一套稳定的修复控制见 COMPOSITION_FIXES例如composition/label-route-clearance→ 调整labelAt/labelDx/labelDy/labelSegment等composition/desktop-readability→ 收窄 viewBox 宽度、精简节点文案或拆分图composition/micro-segment→ 移动路由点使每个可见段 ≥ 8pxcomposition/short-interior-segment→ 使每个内部拐角 ≥ 16px。非零退出码永远不会代表校验成功。validate的退出码直接透传渲染器与 artifact 检查器的退出状态见 exitFrom。当修复进入平台期连续两轮修正未降低最佳错误数时应当如实报告未解决的诊断而不是继续盲目重试。5.3 布局检查inspect当几何诊断点名某个路由或放置问题时使用渲染器的机器可读布局输出node bin/archify.mjs inspect architecture path/to/diagram.jsoninspect目前仅支持 architecture其他类型直接报错它实际是validate --layout-json的别名见 inspect 分发。CLI 上--layout-json对 architecture 与 workflow 开放会把渲染器编译出的布局契约 JSON 直接写到 stdout用于几何诊断的机器消费。workflow v2 的几何诊断需要运行node bin/archify.mjs validate workflow candidate.json --layout-json并读取稳定的编译回执——求解器内部不是作者控制项。5.4 关于 schema 版本与迁移Workflow 是唯一支持多 schema 版本的类型v1 是固定布局的兼容契约v2 选择可读的 workflow 编译器可用archify migrate workflow old.json new.json --to-schema 2 --json显式产出实现见 commandMigrate迁移全程经过渲染与 artifact 检查双门。v2 还接受可选的semanticChecksallowedRoots、allowedTerminals、requiredEdges、requiredPaths在布局前由编译器求值并返回类型化的workflow/*诊断。迁移语义、布局契约与回执字段的完整规范见 renderers/workflow/README.md 与 archify/migrations/workflow-v2.mjs。一个今天通过校验的文件必须在整个 2.x 版本线内保持按声明版本继续校验与渲染破坏性 IR 变更必须升版本附加且向后兼容的字段则不需要。6. 交付可信产物deliver、--open 与 compare6.1 render 与 deliver 的分工render适合快速本地输出不做最终验收deliver适用于交接物、发布工件或 CI 输出node bin/archify.mjs deliver architecture examples/web-app.architecture.json \ web-app.html --quality showcase --jsondeliver是先验证后替换的原子流程实现见 commandDeliver读取输入规格一次把这些精确字节冻结到输出目录旁的私有快照specification.snapshot.json渲染该快照生成同目录候选文件对候选文件运行完整 artifact 检查scripts/check-render-output.mjs只有全部门通过后才用一次同文件系统 rename 替换目标文件清理临时目录保留上一次可信输出。其回执同时包含specification 与 artifact 的 SHA-256 与字节数以及validation.checksPassed/checkCount、compositionProfile/compositionStatus等字段。渲染、检查、回执或提交任一阶段失败都会以非零退出并保留旧工件——因此在交付失败时不要对该输出路径运行visual-check那会测量到陈旧的 last-good 产物而不是被拒绝的候选。6.2 --open仅用于交互式本地交接node bin/archify.mjs deliver architecture examples/web-app.architecture.json \ web-app.html --quality showcase --open --json--open只应在用户需要立即本地预览时添加它在原子提交之后执行使用单个 OS opener 调用并受 5 秒超时约束opener 失败不会使交付失效回执只记录open.status。CI、无人值守 Agent 与非交互环境应保持关闭。6.3 compare对比两个架构快照node bin/archify.mjs compare architecture base.json head.json \ architecture-delta.html --quality showcase --jsoncompare把两张已校验快照渲染为Before / Delta / After三视图 HTML并在其旁写出侧车回执architecture-delta.receipt.json。从 commandCompare 的实现看它先分别对 base 与 head 做渲染检查再把两侧集合序规范化以保证确定性字节最后通过delta/architecture-delta.mjs计算新增/删除/变更/移动/重路由等语义事实。回执包含两侧的原始与语义 SHA-256、字节数、completeness、proofLevel与合并校验计数回执必须与 HTML 同目录且提交前会对整对目标做预检与回滚保护。仓库中现成的对比夹具是 archify/examples/checkout-platform.base.architecture.json 与 archify/examples/checkout-platform.head.architecture.json。7. 检查最终文件visual-check 与交付契约7.1 为什么还需要 visual-check确定性检查不会在浏览器中驱动 Viewer。当本机有 Chrome/Chromium 时对精确交付的 HTML收集自动化浏览器证据node bin/archify.mjs visual-check web-app.html --json该命令零依赖通过 DevTools pipe 驱动浏览器测量亮色主题在 1440×900、1600×1000、1920×1080、2048×1320 四种视口下的 containment要求scrollWidth innerWidth且scrollHeight innerHeight并在 1440×900 与 2048×1320 各拍亮/暗两套截图。它写出四张 PNG sidecar、一张相对路径 HTML 联系表与一份 JSON 回执。回执绑定源工件的 SHA-256 与字节数、标记evidenceKind: automated-browser、记录 READ 与 Still 运行时状态并始终报告visualReview: pending——自动化浏览器证据永远不能声称完成了感知评审perceptual review。Chrome/Chromium 不可用时以退出码 2 返回status: skipped运行或截图失败留下不完整证据不得规范化为skipped。7.2 交付的三重分离主张archify/references/delivery-contract.md 明确区分三个独立主张一个通过绝不蕴含另一个deliver证明确定性 artifact 检查与字节同一性visual-check从精确工件收集自动化浏览器证据Perceptual visual review 记录人工或可读图 reviewer对渲染效果的判断。在交付契约中这三者对应回执里的browser_evidence: passed|failed|skipped与visual_review: passed|skipped (image reader unavailable)|failed外加correction_rounds: 0|1|2最多两轮聚焦修正超过则如实上报。交接回执的标准格式为diagram_type: architecture|workflow|sequence|dataflow|lifecycle output: /absolute/path/to/file.html specification_sha256: receipt value artifact_sha256: receipt value validation: 9/9 showcase, 0 errors, 0 warnings browser_evidence: passed|failed|skipped visual_review: passed|skipped (image reader unavailable)|failed correction_rounds: 0|1|2契约还补充了两条关键约束输出路径必须最终解析为.html回执路径为.json见 output-path 解析防止意外覆盖别的文件类型preview是显式的仅回环loopback桌面模式监听单个 JSON、失败时保持上一个已验证输出、Ctrl-C 停止绝不应默认启动或在 CI/无人值守环境中使用。完整规范见 archify/references/delivery-contract.md作者不变式与有界修复合约见 archify/SKILL.md 与 archify/references/authoring-contract.md。8. 端到端工作流速查把整条链串起来一次可信交付的完整流程是# 1. 环境就绪 node bin/archify.mjs doctor # 2. 不确定类型时先问向导 node bin/archify.mjs guide Show an API request with a Redis cache miss --json # 3. 编写候选 JSON8–12 主节点、一条主路径、schema_version/diagram_type/meta.title 齐全 # 4. 每次编辑后验证 node bin/archify.mjs validate architecture examples/web-app.architecture.json \ --quality showcase --json # 失败 → 只修 diagnostics[] 点名的 subject采用 supportedFixes再验证 # 5. 几何问题用 inspect 定位 node bin/archify.mjs inspect architecture path/to/diagram.json # 6. 最终验收交付所有门通过才替换目标 node bin/archify.mjs deliver architecture examples/web-app.architecture.json \ web-app.html --quality showcase --json # 7. 对精确交付物收集浏览器证据可选需 Chrome/Chromium node bin/archify.mjs visual-check web-app.html --json # 8. 感知评审后按交付契约记录 visual_review 与 correction_rounds从环境诊断、类型决策、有界编写、机器校验、原子交付到浏览器证据每一步都有稳定代码、精确 subject 与受支持的修复控制——这正是 Archify 让图可以像代码一样被审查、被验证、被可信交接的原因。【免费下载链接】archifyAgent skill for beautiful, verifiable architecture, workflow, sequence,>项目地址: https://gitcode.com/GitHub_Trending/arch/archify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考