SuperAPI AI 工具集

dym-archify-compare-architecture-delta

编程与开发

查看项目

更新于 10-18 01:25

技能介绍

用途:该技能用于对比两份架构声明(Architecture Delta),服务设计评审与 PR 评审场景。它不要求读者用眼睛比对两张架构图,而是比较两个已校验的架构来源,生成 Before / Delta / After 页面及机器可读回执。

主要能力:输出一个自包含的 HTML 差异页和一个 sidecar *.receipt.json,后者精确列出新增、删除、修改、移动的内容,不做推断。回执包含 schemaVersion、ok、command、type、comparatorVersion、canonicalVersion、completeness、proofLevel、base、head、summary、changes、identity、view、limitations、artifact、validation 等顶层键。base 与 head 各含 title、rawSha256、semanticSha256、bytes;rawSha256 在字节变化时改变(包括仅重新格式化),semanticSha256 仅在语义变化时改变。summary 按 components、connections、boundaries 分组统计 added、changed、evidenceChanged、removed、moved、rerouted、geometryChanged 等,并给出 presentationChanged 与 provenanceChanged。identity 说明何为“同一对象”:组件按 components[].id,连接按 connections[].id(必填),边界按 boundaries[].kind + boundaries[].label(派生)。因此修改组件 id 会被读作删除一个、新增一个,而非重命名;保持 id 稳定才能让差异有意义;连接未设置 id 则无法正常对比。

使用方式:设置环境变量 export A=~/.claude/skills/archify,运行 node $A/bin/archify.mjs compare architecture base.json head.json out/delta.html --json。示例已用内置示例实际跑通:node $A/bin/archify.mjs compare architecture $A/examples/checkout-platform.base.architecture.json $A/examples/checkout-platform.head.architecture.json out/delta.html --json,rc 0,生成 delta.html(1.9M)与 delta.receipt.json(5.2K)。回执默认与 HTML 同目录同名,可用 --receipt 改位置:node $A/bin/archify.mjs compare architecture base.json head.json out/delta.html --receipt out/delta-receipt.json --json。其他标志与 CLI 其余部分一致:--quality standard|showcase,以及当两个来源声明了代码证据时使用 --repo-root <path>。

接入 PR 评审:当架构来源位于仓库中时,可在 main 与分支之间运行:git show main:docs/architecture.json > /tmp/base.json;node $A/bin/archify.mjs compare architecture /tmp/base.json docs/architecture.json /tmp/delta.html --json > /tmp/delta-summary.json;然后将 /tmp/delta.html 附到 PR,或从 /tmp/delta-summary.json 摘取摘要写入描述。

适用场景与限制:仅支持 architecture 类型。回执原文限制为“Authored Architecture IR only; no runtime impact, causality, risk, or mergeability is inferred.”以及“Boundary identity is conservatively derived from kind + label.”。completeness 为 complete,proofLevel 为 authored,即差异基于作者声明的事实,不是影响分析;该页面不得用于宣称“此变更可安全合并”或“风险低”,它只说明声明中改了什么。在查看器中,读者可选择某个已声明变更,或运行一次有限的 Review 仅用于查看;查看器不推断影响、风险或合并安全性。