SuperAPI AI 工具集

dym-archify-repository-evidence

编程与开发

查看项目

更新于 10-18 01:23

技能介绍

用途

dym-archify-repository-evidence 是一个用于生成「带源码证据的架构图」的技能。它解决的核心问题是:架构图必须能证明自己反映的是真实代码,而不是某个人的记忆。图中的节点带有证据,会在 viewer 中自动标记为 SRC n,并可打开对应的文件与行号区间,同时固定到一个公开 commit 上。

最终产出是一个 HTML 架构图,其中各组件可反向链接到真实的文件/行号;并带有一道 fail-closed 关卡:如果证据无法验证,就拒绝渲染。

该技能仅适用于 architecture(架构)类型。workflow、sequence、dataflow、lifecycle 等类型会拒绝 --repo-root,返回 rc 2。

主要能力与校验规则

必须同时匹配的三项条件(读取自 renderers/shared/repository-evidence.mjs 中的 verifyRepositoryEvidence 函数,第 87 行起):

  1. meta.repository.url —— 必须是公开 GitHub URL,形式为 https://github.com/owner/repo。其他 host 或其他形式会报 repository-evidence/url-invalid。
  2. meta.repository.revision —— 必须是完整的 40 字符 commit SHA。7 字符缩写会被拒绝,报 repository-evidence/revision-invalid。
  3. --repo-root <path> —— 必须指向 Git checkout 的顶层目录,且其 origin 必须与 meta.repository.url 匹配。不是顶层目录会报 repository-evidence/root-not-top-level(并给出应使用的正确路径);origin 不一致会报 repository-evidence/origin-mismatch。

每个组件的 sources[] 结构(来自 schemas/architecture.schema.json):数组含 1–3 个元素,每个元素必填 path(≤240 字符),可选 line、end_line(整数 ≥1)、label(≤48 字符)。

使用方式

技能目录:export A=~/.claude/skills/archify

最小可运行示例(已在 archify 仓库上完整跑通):

REV=$(git -C /path/to/archify rev-parse HEAD) # 必须是 40 字符 SHA

cat > evidence.architecture.json <<JSON { "schema_version": 1, "diagram_type": "architecture", "meta": { "title": "Archify CLI — evidence probe", "quality_profile": "showcase", "repository": { "url": "https://github.com/tt-a1i/archify", "revision": "$REV" } }, "layout": { "mode": "grid" }, "components": [ { "id": "cli", "type": "backend", "label": "archify CLI", "row": 0, "col": 0, "sources": [ { "path": "archify/bin/archify.mjs", "line": 1, "end_line": 40, "label": "entry" } ] }, { "id": "renderer", "type": "backend", "label": "Renderer", "row": 0, "col": 1, "sources": [ { "path": "archify/renderers/architecture/render-architecture.mjs", "line": 1, "end_line": 30 } ] } ], "connections": [ { "from": "cli", "to": "renderer", "label": "spawns" } ] } JSON

node $A/bin/archify.mjs validate architecture evidence.architecture.json
--quality showcase --repo-root /path/to/archify

实际结果:

ok architecture /…/evidence.architecture.json (9 artifact checks; composition showcase: 0 errors, 0 warnings)

rc 0。

交付带证据的产物:--repo-root 被 render、validate、deliver、preview 和 compare 接受,且始终仅在 architecture 模式下:

node $A/bin/archify.mjs deliver architecture evidence.architecture.json out/arch.html
--quality showcase --repo-root /path/to/archify --json

两条已验证的失败路径

  1. spec 中声明了证据却忘记传 --repo-root —— fail-closed,rc 1:

This diagram declares source evidence. Pass --repo-root <repository> so Archify can verify it before rendering. [repository-evidence/root-required] … Fix: pass --repo-root with the matching local Git checkout.

  1. 对 architecture 以外的类型使用 --repo-root —— 用法错误,rc 2:

--repo-root is currently supported for architecture diagrams only.

这一区别在 CI 中很重要:rc 1 表示你的 spec 有误,rc 2 表示你的命令行有误。

证据收集纪律

来自 references/authoring-contract.md 的「Repository evidence」一节:

  • 在编写架构图之前,先查看 entrypoint、运行时边界、数据存储、传输、部署配置。
  • 只记录你真正核实过的证据。sources[] 是一项声明,不是注释。
  • 不要因为文件位置相近或名称相似就推断运行时的因果关系。同一目录并不意味着互相调用。
  • 普通产物(未声明 sources)仍然完全不涉及源码——证据是 opt-in,不是默认行为。

相关:deployment-ownership profile

architecture 还有一个可选的工程 profile,用于生产部署评审。它是 fail-closed 的:缺少已声明的 owner、缺少 region 位置、缺少独立 database 范围,或缺少边界切点名称,validate 都会失败。它从不隐式开启,也不会检查正在运行的基础设施。

仅当用户明确要求时才启用。图中出现 region/cluster/安全边界等措辞本身并不构成启用该 profile 的理由。而且一旦启用,就不能仅仅为了让 validate 通过而移除——应修正数据,或如实报告诊断结果。

适用场景与限制

适用场景:需要让架构图可追溯到真实代码、并在 CI 中强制校验证据完整性的场合。

限制:仅支持 architecture 类型;证据为 opt-in;要求公开 GitHub 仓库与完整 commit SHA;--repo-root 必须为 Git checkout 顶层目录且 origin 匹配。其他图类型、非公开仓库或非 GitHub 托管等情形暂未提供支持说明。