开源项目archify的源码分析二：JSON-IR-与-SchemaJSON IR 与 Schema Archify 的

JSON IR 与 Schema

Archify 的源文件不是 Markdown 指令也不是绘图工具的序列化格式，而是一份带类型的 JSON 中间表示。IR 同时是人可读的创作载体、Agent 的修复对象和可复现渲染的唯一输入。

Schema 契约

五份 Schema 位于 archify/schemas/，采用 JSON Schema 2020-12，全部通过 archify/schemas/common.schema.json 共享枚举与子定义。契约有三个硬性特征：

封闭字段：每层对象 additionalProperties: false。拼错字段名、虚构一个属性都会在校验阶段被拒绝。
枚举约束：节点类型、边界种类、连线变体、视觉预设等全部枚举化，渲染器不需要处理未知语义。
显式必填：顶层固定要求 schema_version、diagram_type、meta 和该类型的节点集合。

验证器代码生成

AJV 只出现在开发依赖里。archify/scripts/generate-validators.mjs 在构建期把五份 Schema 编译成一个独立 ESM 文件 renderers/shared/generated-validators.mjs：

使用 AJV 的 standalone code 生成，产物本身不依赖 ajv 包。
连 AJV 运行时的 ucs2length 辅助函数都被内联替换；生成结束后断言产物中不再包含任何 require(，否则构建失败。
npm run check:validators 校验生成文件与 Schema 同步，CI 中过期生成会被拦截。

因此最终安装到用户机器上的 Skill 是真正的零运行时依赖：只靠 Node.js 标准库完成所有校验。

架构图 IR（architecture）

以 web-app.architecture.json 为典型结构：

{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": {
    "title": "Sample Web App",
    "output": "web-app-rendered.html",
    "quality_profile": "showcase"
  },
  "components": [
    { "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"] }
  ],
  "connections": [
    { "id": "jwt-verification", "from": "auth", "to": "api",
      "label": "verify JWT", "variant": "security",
      "fromSide": "right", "toSide": "top",
      "via": [[620, 142], [620, 246], [735, 246]] }
  ],
  "cards": [
    { "dot": "emerald", "title": "Application", "items": ["..."] }
  ]
}

核心集合：

字段	说明
`components[]`	节点：`id`、语义 `type`、`label`/`sublabel`/`tag`、自由坐标 `pos` 与 `size`
`boundaries[]`	边界：通过 `wraps` 引用成员 id 推导矩形，支持 region、security-group 等语义种类
`connections[]`	有向关系：`from`/`to`、可选 `variant`（emphasis/security/dashed 等）、可选作者布线
`cards[]`	说明卡片：辅助信息放进卡片而不是增加连线

节点 type 与语义配色一一对应：frontend、backend、database、cloud、security、messagebus、external。颜色只表达类别，不做装饰。

作者布线是可选项。只给 from/to 时走自动正交布线；fromSide/toSide 指定连接面，via 指定折线拐点。创作契约建议先用自动路由，仅在分支、回流或测量后的修复中显式指定。

其余四种类型

类型	节点集合	特有结构
workflow	`nodes[]` + 泳道	参与者、顺序、分支、异常；schema v2 由编译器从意图模型生成几何，v1 输入经 migrate 升级
sequence	`participants[]` + `messages[]`	固定参与者列、生命线、请求与返回消息、异步副作用；画布宽度有专项宽度评审
dataflow	节点 + 数据流	来源、转换、存储、消费者，敏感数据与边界语义
lifecycle	`states[]` + 转换	schema v2 在共享 `col` 0–4 网格上每个泳道一行，起始态 UML 标记、无出口态双边框

五种类型共享同一套 meta、证据、品牌、图例与 i18n 机制；meta.repository 与节点 sources 在 v3.0 起对全部五种类型开放。

meta 中的创作开关

字段	取值	效果
`quality_profile`	`showcase` / `standard`	选择门禁强度与默认密度
`animation`	`trace`	显式开启路径动画；缺省完全静态
`visual_preset`	`classic`（默认）/ `signal-flow` / `editorial` / `blueprint`	材质与氛围预设，几何不变
`locale`	合法语言标签	Viewer UI 语言与 `<html lang>`
`translations`	消息键到译文的映射	为非内置语言提供 UI 译文
`engineering_profile`	`deployment-ownership`	显式启用部署归属校验，负责人、区域归属、数据库私有边界缺失即阻断
`viewBox`	`[宽, 高]`	显式画布，宽有下限（320/240）
`repository`	对象	声明源码证据所属仓库与固定修订
`views` / `legend`	对象	引导视图与图例的作者配置

本地化的数据化设计

内置目录只有英语和简中。locale 设为任意合法语言标签后，渲染器按消息键从 translations 取译文，逐键叠加在英语之上：缺失键、未知键、{placeholder} 不匹配都会回退英语并在 stderr 披露覆盖率，而不是让渲染失败。archify/examples/locales/ 下提供了完整的韩语目录和故意不完整的法语示例。增加一门语言因此是数据变更，不需要改渲染器或 Schema 枚举。作者写的标题、节点名、卡片正文属于创作内容，不参与这套机制也不会被机器翻译。

对 Agent 的创作约束

archify/SKILL.md 与 references/authoring-defaults.md 把人类布局经验固化成创作顺序：先判断叙事（主路径、分支、回流、第二入口、扇出），再按语义选择节点类型与相邻落位，最后才写坐标。节点和关系的数量没有目标值也没有上限；辅助信息进卡片而不是加线；示例只教结构形状，不允许照抄其中的事实。