archify

Archify

创建经过检查的独立 HTML，将其作为原生图表或用于回答问题的单页解说。

从工作目录运行命令。除非用户指定其他位置，否则每个新的制品请求都在此目录下使用独立文件夹 .archify/<type>-<slug>-<YYYYMMDD-HHMMSS>/（本地时间，只选择一次）：将候选文件和 <slug>.html 保存在其中，并在修复时重复使用该文件夹。原生图表使用 candidate.json，其 meta.output 路径相对于工作目录；解说页可以使用 candidate.archify.md 和可移植的输出文件名。后续请求使用新的文件夹。每条命令中的 bin/archify.mjs 都要替换为已安装软件包的绝对路径，或相对于工作目录的路径；CLI 输入和输出路径均相对于该目录解析。

为真实代码库创建原生图表时，在追踪所请求的行为过程中阅读仓库编写指南。系统描述使用下方的原生步骤；冻结候选文件使用交接流程。

选择制品类型

• 用户要求绘制或可视化系统、流程、架构或历史记录时，使用原生图表和类型路由器。
• 用户要求以页面形式给出答案时，使用 explainer：例如页面、单页、解说页、可分享的内容（“做成一页”“用页面讲”“answer with a page”）。如果没有此类要求，就用文字回答或绘制所需图表。按要求制作的页面，其回复结尾要附上 Output 中的一行模式选项。
• 上下文中的规则行会改变这一点。[archify explainer: proactive]：对于需要表格、步骤或多个部分来说明、比较、权衡、决策、诊断、评审或规划的内容，即使用户未要求，也制作页面。[archify explainer: always-on]：每个得出结论的回复都附带一个最多包含四个面板的简洁页面，不打开页面，将其链接放在回复末尾。[archify explainer: on-demand]：仅在用户要求时制作页面，且绝不提供模式选项。
• 在任何模式下，页面都必须基于有一定结构的结论：聊天、一句话回答、原始命令输出和纯文本请求均不制作页面。
• 对于 explainer，阅读解说页编写指南，了解其结论、理由、范围、画布布局和可选的原生图表。撰写完整草稿，然后运行 finalize explainer 进行验证、原子交付和制品检查。局部修改内容时使用面板补丁。

现有候选文件交接

用户提供冻结候选文件时，先通过一次 CLI 调用运行 finalize。通过的回执即表示自动检查已完成；在宣称视觉质量之前，遵循 Delivery 中的任何视觉审查建议。修复时遵循步骤 5。

finalize 的交付回执包含范围有限的更新检查；请参阅 Update awareness。

原生图表编写

普通生成任务使用此流程。仅在满足所述触发条件时阅读分支参考资料。

1. 根据问题，从 architecture、workflow、sequence、dataflow、lifecycle、erd、class、tree、timeline 或 waterfall 中选择。

2. 使用 Type router 中的准确 schema 和示例路径，不要列出其目录。阅读 Authoring defaults 和该模式的示例；将它们与项目文档及完整 schema 分开，分批读取，以免内容被截断；写作前补齐任何缺失的部分。对于 Architecture，使用匹配的 showcase 示例。除 Architecture 外，每种模式还要阅读该模式和通用 schema。选择任何新字段、枚举或受约束文本之前，先阅读相关的 schema 定义，尤其是边界类型。示例仅用于说明结构，不代表事实。使用新的 ID、措辞和布局。直接处理候选内容，不要先提供帮助、运行 doctor 或 starter validation、创建临时图表或列出输出路径。只有明确要求标志时才查询品牌；对于未知标志且用户提供了 URL 的情况，阅读 Brand marks。

3. 确认已覆盖用户要求的范围，以及真实代码库的 source evidence 后，直接完整写出候选内容，不要先用文字规划坐标。确定 Architecture 的抽象层级和连接布局时，先参考 Authoring defaults，再确定坐标：展示主要用户旅程和必要分支，保留控制角色及会改变行为的条件，并为实际关系标签留出足够空间。节点、关系、来源、视图、卡片或边界的数量都不是目标，也没有上限。优先使用自动路由；仅在必要的分支、返回路径、提供的几何信息或经测量确认需要修复时，才添加显式路由。除非用户要求使用密集的 standard，否则将 meta.quality_profile 设为 "showcase"。对于 ERD，采用以表为先的布局：在 entities[].attributes 中展示每个物理列，保留其 SQL 类型和来源注释，注明每列承担的所有键角色（key 可取一个角色或角色列表，因此连接表中的列应为 ["pk", "fk"]；每个 fk 列还必须包含类似 "orders.id" 的 references），绝不能用卡片代替表来展示列。先按功能领域对表分类，再进行布局；为每个领域指定简洁的 tag，并将其成员放入一个由网格单元构成的实心矩形中——可以是一行、一列或填满的矩形块，不能是 L 形或对角线排列。带有 tag 的表必须指定 row/col，因为绝对坐标没有网格单元；如果某个领域的表无法填满一个矩形，就无法将其绘制为条带：渲染器会报告 erd/domain-not-drawn，而不会发布一个无法标注该领域的图表。多领域 schema 最适合每个领域各占一列的布局——每个 tag 形成垂直排列——因为读者会将宽画布缩放到阅读器宽度，并将高画布缩小到适合页面，因此较宽的布局才能在笔记本电脑视口中保持完整且清晰。当以 schema 为主的 ERD 超过大约 8 张表或 50 个字段时，本身就属于密集地图：先以 standard 完成包含所有字段的首轮编写，只有在布局仍清晰易读时才升级。

4. 完成完整的首份候选内容后，直接运行 finalize。其第一道门槛是 showcase validation；首轮草稿通过后，无需单独进行预验证。命令运行期间保持候选内容不变：

   node bin/archify.mjs finalize <type> <candidate.json> <output.html> --quality showcase --json
   

   对于基于代码库的候选内容，首稿中要包含证据，并使用完整的首条命令：node bin/archify.mjs finalize <type> <candidate.json> <output.html> --repo-root <repo-root> --quality showcase --json。传入与 meta.quality_profile 匹配的 --quality，例如，密集 ERD 首轮使用 standard。

   通过回执即可证明其中包含的 validate、deliver、严格 check 和真实浏览器 browser-check 门槛均已通过。使用其精简摘要；仅在用户另有要求或需要针对性诊断失败时，才运行独立命令。

5. 非零退出码绝不表示成功。阅读精简的 stdout 或 evidence.summaryReceipt，然后修复失败的门禁，包括修复次数限制。保留所要求的含义和源证据。对于几条相互纠缠的 Architecture 路由，请阅读 Architecture 布局修复；对于测量值或几何方面的失败，请阅读 创作规范。编辑相互关联的部分，并从步骤 4 重新运行完整的 finalize 命令。一旦某次运行到达 browser-check，该输出路径便归该证据所有：之后的每次运行都使用各自的 --out-dir <folder>/review-<n>。

更新须知

finalize 和独立的 deliver 都会在回执中包含 update。不要为同一次交付单独检查更新。如果 update.noticeRequired 为 true，请阅读 references/update-awareness.md，并在给用户的最终回复中保留一条简短的更新通知，即使质量门禁失败也不例外。对于包含多个图表的任务，在最终回复中只提及一次更新。只有用户明确要求时，才暂缓或忽略提醒；绝不要主动安装或更新。

创建第一个候选版本之前，请使用创作参考资料和相关仓库源代码，而不是 Archify 的实现或测试。如果经过有针对性的修复后，诊断仍无法采取行动，再检查 Archify 的实现。

类型路由

类型	适用场景	架构	示例
architecture	组件、服务、云／安全边界、基础设施；日常事物由什么构成	schemas/architecture.schema.json	系统描述、服务、库和 CLI 仓库：examples/web-app.architecture.json；部署仓库：examples/production-deployment.architecture.json
workflow	流程、审批关卡、工具调用、运行手册、CI/CD；计划和逐步展开的生活过程	schemas/workflow.schema.json	examples/agent-tool-call.workflow.json
sequence	API 调用链、请求生命周期、异步跟踪、返回；人与人之间的来回交互	schemas/sequence.schema.json	examples/cache-miss-request.sequence.json
dataflow	流水线、ETL/ELT、沿袭、治理、使用者；资金或文档的流向	schemas/dataflow.schema.json	examples/product-analytics.dataflow.json
lifecycle	状态／状态值转换、重试、等待状态和终止状态；应用或订单当前所处的阶段	schemas/lifecycle.schema.json	examples/deployment-release.lifecycle.json
erd	表／实体、属性、主键／外键／唯一键，以及它们之间的基数关系	schemas/erd.schema.json	examples/orders.erd.json
tree	单父级包含关系：仓库／模块树、能力或功能分解、组织式分解	schemas/tree.schema.json	examples/payment-platform.tree.json
class	类、接口、选定成员，以及类型之间的依赖／关联／继承／实现／组合关系	schemas/class.schema.json	examples/payments.class.json
timeline	事件发生的时间：事故复盘、发布历史、沿比例时钟排列且带有来源泳道的带时间戳事件	schemas/timeline.schema.json	examples/payment-incident.timeline.json
waterfall	时间花在哪里：跨度时长、重叠，以及一个请求或 Agent 运行在共同时间轴上的嵌套关系	schemas/waterfall.schema.json	examples/checkout-request.waterfall.json

在选择原生图表类型时遇到歧义，请运行 node bin/archify.mjs guide "<scenario>" --json。场景示例是结构参考，不是可照搬的事实。

对于日常主题，保留相同的图表模式和语义类型，然后使用读者熟悉的名称：采用日常的 icon 值和 meta.legend 标签，如 节点图标 所示。缺少个人事实时，请询问，而不要编造日期、金额或规则。

Mermaid 输入

读取 Mermaid 以了解拓扑和含义，然后重新编写 Archify JSON；不要机械地渲染 Mermaid 样式。

• flowchart / graph → workflow；若为组件图，则使用 architecture。
• sequenceDiagram → sequence；参与者对应语义参与者，箭头对应消息。
• stateDiagram → lifecycle；状态和转换保留其含义，而非 Mermaid 样式。
• erDiagram → erd；实体和关系名称、键及基数保留其含义，而非 Mermaid 样式。
• classDiagram → class；类型种类、选定成员和关系种类保留其含义，而非 Mermaid 样式。

交付

首个候选版本以及修复后，都使用上文的 finalize 命令。

finalize 会在首个未通过的门槛处停止。其精简的标准输出和 <output-stem>.finalize-summary.json 都是常规证据。通过的运行不会创建截图，并会报告 visualReview: "not-requested"。

当通过的 Architecture 回执报告 visualReviewRecommendation.signals.resolvedCrossovers 时，先将候选版本另存一份，然后在一次编辑中应用提示，且只更改节点的位置和尺寸：每个节点、关系（包括其 from 和 to）、标签和来源都必须保持不变。使用 --out-dir <folder>/review-2 完整重新运行一次 finalize，因为先前的 HTML 已占用其浏览器证据。--out-dir 会更改新的浏览器检查回执和默认 finalize 回执的存放位置，不会移动 HTML 或其交付回执。成功交付后，会在指定输出路径重写这两份回执；此前的审查证据仍绑定于原始工件字节。请参阅审查证据路径。如果该次运行失败、报告更多交叉，或报告相同的交叉但 signals.routesOverSuggestedBends 数值更高，请恢复副本，并使用 --out-dir <folder>/review-3 对其运行 finalize。不要开始第二轮布局调整。仅提示增加弯折是可选的。

当 layoutReviewRecommendation.action 为 inspect-sequence-width 时，在交付新编写的 Sequence 前，请遵循Sequence 宽度审查。

常规生成时，感知审查是可选的，包括对新调整位置的 Architecture 进行审查。当用户要求视觉审查、开展开发审计，或存在具体的路线／浏览器问题时，请使用可选捕获证据，并指定 --out-dir <folder>/visual-check。visualReviewRecommendation 仅供参考。请先检查捕获内容，再声称视觉质量良好；如果尚未进行感知审查，任何检查结论都应注明为自动化检查。

有关未通过的门槛、独立命令、来源追溯／恢复、重复交付、导出或打开内容，请阅读交付契约。原生图表恢复流程为 deliver → 严格来源追溯 check → browser-check。捕获内容需要严格来源追溯。说明文的交付流程则按照其编写指南，使用 validate、deliver 和 check。

如果工作流视口溢出，请在进行下一次布局编辑前阅读工作流视口修复。

报告验证细节时，请区分工件检查、浏览器证据、捕获内容和实际感知审查。对于明确要求立即预览或正在进行的桌面循环，请参阅可选打开。

可选查看器功能

默认情况下，所有渲染后的图表都会启用实时动效；请省略 meta.animation。查看器的 Live/Still 按钮可控制播放。

仅当用户明确要求 Share Cards、Route/Reach 卡片、动效、深层链接、演示、搜索／聚焦或其他 Viewer Runtime 功能时，才阅读 references/viewer-runtime.md。

设置与备用方案

此技能包内无需安装。若要诊断设置问题，请使用以下内容进行验证：

node bin/archify.mjs doctor
node bin/archify.mjs demo <output-directory>

对于原生图表，如果无法使用 shell，请将 Architecture SVG 手动放入 assets/template.html，使用 CSS 语义类而非内联颜色，并遵循 references/delivery-contract.md 中的视觉审查契约。说明文需要其渲染器和实际交付门槛；若无法使用这些内容，请说明限制，并在有帮助时提供文本回答，不要声称已交付 HTML。

输出

使用用户的语言回复，并尽可能简洁；图表承载了内容，因此通常用一行介绍单张图表即可。

• 开头放置指向 HTML 的可点击 Markdown 链接：使用描述性标题，而非文件名；链接使用绝对路径，路径包含空格时用 <...> 包裹。
• 如果用户想了解某个系统或代码库，而非绘制所描述的主题，则补充一两句话说明关键结论。跳过那些只是在复述图表显而易见内容的句子。
• 说明会影响图表解读的事项：读者可能会预期但实际有意省略的抽象层级或部分、仅供说明而非实测的数据、缺失的源证据，或修复过程中被删除或合并的用户要求内容。
• 如果有多张图表，只报告一次完成情况，并提供现有概览的链接或简洁的单图表链接；不要提供目录路径。

不要复述命令、修复轮次、哈希值、质量配置或检查清单；这些内容会保留在回执中。如果有人询问图表是否经过验证，用一行回答，例如“自动检查已通过；未进行视觉审查。”仅在用户要求复现或排障时提供回执链接和详情。说明无法进行的用户要求的视觉审查，只有实际进行过时才声称做过视觉检查。必需的更新提示应放在 Update awareness 下方。

示例：已创建[结账请求时序图](/abs/path/checkout-timing.html)。时长仅供说明，并非实测数据。

对于说明类页面，用两三行回复：给出结论和页面链接。仅当某项门槛未通过或仍有警告时才提及；不要粘贴草稿。

按要求制作说明类页面后，如果上下文中没有 [archify explainer: ...] 行，则在回复末尾添加一行可选提示，主动模式每次对话只提示一次，例如：“需要的话，以后遇到解释、对比、排查这类问题，我可以主动做成这样的页面，要开启吗？”如果用户同意，请将 [archify explainer: proactive] Make an Archify explainer page, unasked, for explanations, comparisons, decisions, diagnoses, reviews and plans that need a table, steps or several sections. 添加到当前 Agent 的全局规则文件（例如 ~/.claude/CLAUDE.md、~/.codex/AGENTS.md 或 ~/.config/devin/AGENTS.md），并说明文件名；删除该行即可关闭。如果用户拒绝，则提供添加 [archify explainer: on-demand] 的选项，以免再次询问。