Archify 中文实战指南把系统描述变成可校验、可交互的独立 HTML 系统地图【免费下载链接】archifyAgent skill for beautiful, verifiable architecture, workflow, sequence,>项目地址: https://gitcode.com/GitHub_Trending/arch/archifyArchify 是一个基于 Node.js 的渲染与校验系统以 Agent Skill 形式支持 Cursor、Claude Code、Codex CLI、OpenCode 和 RavenAgent 负责生成 Typed JSON IRArchify 负责校验并确定性编译为便携、独立的 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 分享卡片。从源码结构看整个系统分为三层CLI 入口archify/bin/archify.mjs统一分发render、validate、deliver、preview、compare、guide等子命令渲染器archify/renderers/下五个目录分别实现 architecture、workflow、sequence、dataflow、lifecycle 五种图共享校验与几何层archify/renderers/shared/ 提供 validator、diagnostics、geometry、brand-marks 等模块。仓库的 SKILL.md 是 Agent 与 Renderer 之间的权威契约规定了从“选择图类型”到“交付验收”的完整流程本文的命令与行为描述均以该契约和源码为准。二、安装一条命令装进 Agent 工作流2.1 标准安装npx skills add tt-a1i/archify -g显式、非交互地安装到 Cursornpx -y skills add tt-a1i/archify --skill archify --agent cursor --global --copy --yes只想临时体验时以 Codex CLI 为例npx skills use tt-a1i/archifyarchify --agent codex2.2 其他集成入口DeepSeek Harness社区集成、显式启用运行dsh plugin --profile web add tt-a1i/archify-dsh0.1.0兼容范围、限制与安全说明见 integrations/deepseek-harness/README.mdRaven 仅支持 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_DISABLED1。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 规定了五步受限流程从architecture、workflow、sequence、dataflow、lifecycle中选出图类型只读一个匹配的 schemaschemas/下对应文件 schemas/common.schema.json和一个匹配示例examples/下——示例用于字段形状参考不用于抄袭事实新 workflow 源使用schema_version: 2Artifact first下一个工具动作必须是写候选 JSON先画一条清晰主路径、短侧支、稀疏标签、至多 12 个主节点默认meta.quality_profile为showcase诊断出现前不加via、channelX、channelY、labelAt每轮修复最多施加一个几何控制每次候选编辑后、交付前执行node bin/archify.mjs validate type candidate.json --quality showcase --json通过的最终校验即冻结候选之后不再编辑交付 HTML 时用deliver作为最终验收命令。同一份成品也可以在本机浏览器直接打开例如 examples/web-app.html 即可体验完整 Viewer。四、选择合适的图表类型类型最适合Prompt 中应包含Architecture组件、服务、存储和系统边界范围、核心组件、主要路径WorkflowCI/CD、审批、工具调用、Runbook参与者、顺序、分支、异常SequenceAPI 调用、缓存回源、鉴权、异步链路调用方、被调用方、返回、时序Data Flow数据管线、血缘、PII、下游消费者来源、转换、存储、边界Lifecycle状态、重试、等待、终态状态、事件、重试与取消路径不知道选哪一种时可以直接询问零依赖 CLInode archify/bin/archify.mjs guide 展示带 Redis 缓存未命中的 API 请求 node archify/bin/archify.mjs guide 梳理 Kafka Topic、消费者组、重放和死信队列 --jsonSKILL.md 还给出了 Mermaid 输入的映射规则flowchart/graph映射到workflow或组件地图场景下的architecturesequenceDiagram映射到sequencestateDiagram映射到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。五、工作原理五步流水线与常用命令步骤发生什么生成Agent 根据描述创建 Typed JSON IR。校验内置 Validator 和布局规则检查源文件失败时用机器可读 JSON 指出准确的局部修复。预览可选仅 loopback 的桌面会话监听一个源文件只刷新验证版本失败时保留最后好图。交付在目标同目录生成并检查候选只有通过门禁的结果才原子替换目标文件随后可选用--open打开这个确切成品。迭代Agent 修改源文件不干扰无关结构。仓库常用命令在 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 2workflow v1 固定布局到 v2 可读布局编译器迁移、inspect、check检查 HTML 成品、visual-check浏览器证据、brands/brands capture url品牌徽标查询与摘要固定捕获、examples。5.1 校验链Schema → 布局 → 几何 → 交付门禁“原子交付前校验”是 Archify 的核心设计Schema、布局、HTML/SVG、线路和标签到其他路径的净空检查必须全部通过Showcase 成品才会替换上一份可信结果。具体机制五种图各有一份 JSON Schemaworkflow.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: 12.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 只写 stdoutstderr 给出可手动打开的绝对路径。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_presetclassic是稳定默认signal-flow是偏运动的发光呈现blueprint是高对比工程评审风格editorial是暖纸张与深墨色的编辑风格适合设计评审、发布说明和技术文档——预设只改 Viewer 样式不改变语义 ID 或几何localeen或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 内置完整的读者能力不是额外的创作工作操作控制方式打开事实型 Diagram Guide?查找并聚焦语义节点/追踪作者定义的上游 / 下游可达范围聚焦节点 →Upstream/Downstream探查有向路径并逐站检查R或“路径”对比一种或两种语义角色L或“透镜”打开实时全局雷达M或“地图”播放故事 / 切换章节P/[]进入 Presentation StageF选择视觉风格 / 切换主题 / 打开 ExportS/T/E缩放或复位/-/0稳定链接可以恢复#focusid、#focusidreachupstream|downstream、#relationid、#routesource~target、#lenskind~kind和#viewview-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.mdmeta.repository声明公开 GitHub URL 与完整 commit SHA组件可携带一至三个sources仓库相对 POSIX 路径、可选行范围与标签渲染时要求--repo-root本地 Git origin 必须匹配且 Git 必须证明 commit、blob 与请求的行都存在。已验证证据嵌在标准 SVG 之外供 Semantic Passport 与 Node Finder 使用普通成品与视觉导出不携带仓库证据。九、多平台安装方式对照使用位置安装位置或方法能力RavenZIP 手动安装将archify.zip解压到~/.raven/workspace/skills完整 Renderer Validation 工作流Claude Code~/.claude/skills/或.claude/skills/完整 Renderer Validation 工作流Codex CLI~/.agents/skills/或.agents/skills/完整 Renderer Validation 工作流opencode~/.config/opencode/skills/、.opencode/skills/或.agents/skills/完整 Renderer Validation 工作流Claude.aiSettings → Capabilities → Skills 中上传archify.zip取决于沙箱是否提供 Node.jsProject Knowledge把archify.zip上传到项目Prompt 驱动的 Architecture FallbackDeepSeek Harness显式启用dsh plugin --profile web add tt-a1i/archify-dsh0.1.0卸载dsh plugin --profile web remove tt-a1i/archify-dsh面向开发者预览版deepseek-ai/dsh0.1.0-rc.6的社区集成Node^22.19.0 \|\| 24.0.0不是 DeepSeek 官方产品无遥测详见 integrations/deepseek-harness/README.md十、边界、参考与参与方式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.mdShare Cards、深链、演示等 Viewer 运行时特性、brand-marks.mddocs/authoring-cookbook.zh-CN.md —— Agent 编图手册中文版另有 英文版CHANGELOG.md —— 版本历史当前开发版本v2.17.0-dev.1ROADMAP.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Archify 中文实战指南：把系统描述变成可校验、可交互的独立 HTML 系统地图
Archify 中文实战指南把系统描述变成可校验、可交互的独立 HTML 系统地图【免费下载链接】archifyAgent skill for beautiful, verifiable architecture, workflow, sequence,>项目地址: https://gitcode.com/GitHub_Trending/arch/archifyArchify 是一个基于 Node.js 的渲染与校验系统以 Agent Skill 形式支持 Cursor、Claude Code、Codex CLI、OpenCode 和 RavenAgent 负责生成 Typed JSON IRArchify 负责校验并确定性编译为便携、独立的 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 分享卡片。从源码结构看整个系统分为三层CLI 入口archify/bin/archify.mjs统一分发render、validate、deliver、preview、compare、guide等子命令渲染器archify/renderers/下五个目录分别实现 architecture、workflow、sequence、dataflow、lifecycle 五种图共享校验与几何层archify/renderers/shared/ 提供 validator、diagnostics、geometry、brand-marks 等模块。仓库的 SKILL.md 是 Agent 与 Renderer 之间的权威契约规定了从“选择图类型”到“交付验收”的完整流程本文的命令与行为描述均以该契约和源码为准。二、安装一条命令装进 Agent 工作流2.1 标准安装npx skills add tt-a1i/archify -g显式、非交互地安装到 Cursornpx -y skills add tt-a1i/archify --skill archify --agent cursor --global --copy --yes只想临时体验时以 Codex CLI 为例npx skills use tt-a1i/archifyarchify --agent codex2.2 其他集成入口DeepSeek Harness社区集成、显式启用运行dsh plugin --profile web add tt-a1i/archify-dsh0.1.0兼容范围、限制与安全说明见 integrations/deepseek-harness/README.mdRaven 仅支持 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_DISABLED1。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 规定了五步受限流程从architecture、workflow、sequence、dataflow、lifecycle中选出图类型只读一个匹配的 schemaschemas/下对应文件 schemas/common.schema.json和一个匹配示例examples/下——示例用于字段形状参考不用于抄袭事实新 workflow 源使用schema_version: 2Artifact first下一个工具动作必须是写候选 JSON先画一条清晰主路径、短侧支、稀疏标签、至多 12 个主节点默认meta.quality_profile为showcase诊断出现前不加via、channelX、channelY、labelAt每轮修复最多施加一个几何控制每次候选编辑后、交付前执行node bin/archify.mjs validate type candidate.json --quality showcase --json通过的最终校验即冻结候选之后不再编辑交付 HTML 时用deliver作为最终验收命令。同一份成品也可以在本机浏览器直接打开例如 examples/web-app.html 即可体验完整 Viewer。四、选择合适的图表类型类型最适合Prompt 中应包含Architecture组件、服务、存储和系统边界范围、核心组件、主要路径WorkflowCI/CD、审批、工具调用、Runbook参与者、顺序、分支、异常SequenceAPI 调用、缓存回源、鉴权、异步链路调用方、被调用方、返回、时序Data Flow数据管线、血缘、PII、下游消费者来源、转换、存储、边界Lifecycle状态、重试、等待、终态状态、事件、重试与取消路径不知道选哪一种时可以直接询问零依赖 CLInode archify/bin/archify.mjs guide 展示带 Redis 缓存未命中的 API 请求 node archify/bin/archify.mjs guide 梳理 Kafka Topic、消费者组、重放和死信队列 --jsonSKILL.md 还给出了 Mermaid 输入的映射规则flowchart/graph映射到workflow或组件地图场景下的architecturesequenceDiagram映射到sequencestateDiagram映射到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。五、工作原理五步流水线与常用命令步骤发生什么生成Agent 根据描述创建 Typed JSON IR。校验内置 Validator 和布局规则检查源文件失败时用机器可读 JSON 指出准确的局部修复。预览可选仅 loopback 的桌面会话监听一个源文件只刷新验证版本失败时保留最后好图。交付在目标同目录生成并检查候选只有通过门禁的结果才原子替换目标文件随后可选用--open打开这个确切成品。迭代Agent 修改源文件不干扰无关结构。仓库常用命令在 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 2workflow v1 固定布局到 v2 可读布局编译器迁移、inspect、check检查 HTML 成品、visual-check浏览器证据、brands/brands capture url品牌徽标查询与摘要固定捕获、examples。5.1 校验链Schema → 布局 → 几何 → 交付门禁“原子交付前校验”是 Archify 的核心设计Schema、布局、HTML/SVG、线路和标签到其他路径的净空检查必须全部通过Showcase 成品才会替换上一份可信结果。具体机制五种图各有一份 JSON Schemaworkflow.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: 12.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 只写 stdoutstderr 给出可手动打开的绝对路径。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_presetclassic是稳定默认signal-flow是偏运动的发光呈现blueprint是高对比工程评审风格editorial是暖纸张与深墨色的编辑风格适合设计评审、发布说明和技术文档——预设只改 Viewer 样式不改变语义 ID 或几何localeen或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 内置完整的读者能力不是额外的创作工作操作控制方式打开事实型 Diagram Guide?查找并聚焦语义节点/追踪作者定义的上游 / 下游可达范围聚焦节点 →Upstream/Downstream探查有向路径并逐站检查R或“路径”对比一种或两种语义角色L或“透镜”打开实时全局雷达M或“地图”播放故事 / 切换章节P/[]进入 Presentation StageF选择视觉风格 / 切换主题 / 打开 ExportS/T/E缩放或复位/-/0稳定链接可以恢复#focusid、#focusidreachupstream|downstream、#relationid、#routesource~target、#lenskind~kind和#viewview-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.mdmeta.repository声明公开 GitHub URL 与完整 commit SHA组件可携带一至三个sources仓库相对 POSIX 路径、可选行范围与标签渲染时要求--repo-root本地 Git origin 必须匹配且 Git 必须证明 commit、blob 与请求的行都存在。已验证证据嵌在标准 SVG 之外供 Semantic Passport 与 Node Finder 使用普通成品与视觉导出不携带仓库证据。九、多平台安装方式对照使用位置安装位置或方法能力RavenZIP 手动安装将archify.zip解压到~/.raven/workspace/skills完整 Renderer Validation 工作流Claude Code~/.claude/skills/或.claude/skills/完整 Renderer Validation 工作流Codex CLI~/.agents/skills/或.agents/skills/完整 Renderer Validation 工作流opencode~/.config/opencode/skills/、.opencode/skills/或.agents/skills/完整 Renderer Validation 工作流Claude.aiSettings → Capabilities → Skills 中上传archify.zip取决于沙箱是否提供 Node.jsProject Knowledge把archify.zip上传到项目Prompt 驱动的 Architecture FallbackDeepSeek Harness显式启用dsh plugin --profile web add tt-a1i/archify-dsh0.1.0卸载dsh plugin --profile web remove tt-a1i/archify-dsh面向开发者预览版deepseek-ai/dsh0.1.0-rc.6的社区集成Node^22.19.0 \|\| 24.0.0不是 DeepSeek 官方产品无遥测详见 integrations/deepseek-harness/README.md十、边界、参考与参与方式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.mdShare Cards、深链、演示等 Viewer 运行时特性、brand-marks.mddocs/authoring-cookbook.zh-CN.md —— Agent 编图手册中文版另有 英文版CHANGELOG.md —— 版本历史当前开发版本v2.17.0-dev.1ROADMAP.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
