dym-archify-migrate-workflow-v2

用途

该技能用于把工作流源文件从 schema_version: 1 升级到 2。当你仍保留按 v1 编写、使用手工固定几何坐标的 *.workflow.json 文件，并希望迁移到 v2 更易读的布局契约（自动求解坐标、带最小间隙约束）时使用。

迁移结果是生成一个新的 v2 JSON 文件，或者生成一组诊断信息，明确指出 v1 在哪些地方无法满足 v2 约束、需要手动修改。

该技能仅适用于 workflow 类型，其他类型没有迁移路径。

使用方式

设置变量：

export A=~/.claude/skills/archify

运行迁移命令：

node $A/bin/archify.mjs migrate workflow old.workflow.json new.workflow.json --to-schema 2 --json

语法严格，定义于 bin/archify.mjs 中的 commandMigrate()：必须正好三个位置参数（workflow、源、目标），并且必须带 --to-schema 2。任何一项不符合，返回 rc 2，并输出：

Usage: archify migrate workflow <old.json> <new.json> --to-schema 2 [--json]

源和目标必须是两个不同的文件（migration/source-destination）。不支持原地覆盖，这是有意设计的。

migrate 没有 --quality 标志。它会按文档已有的 meta.quality_profile 固定所有阶段（默认 standard），并主动移除环境中悬空的 profile。

已验证的路径

在打包的 v1 fixture 上运行：

node $A/bin/archify.mjs migrate workflow \
  $A/test/fixtures/v1-workflow-explicit-coordinates.workflow.json \
  /tmp/migrated.workflow.json --to-schema 2

返回 rc 0。另外三个 fixture 也返回 rc 0：v1-workflow-700x400.workflow.json、automatic-routing-node-border-clearance.workflow.json。

并非所有 v1 源都能自动转换。在 test/fixtures/v1-baseline/agent-tool-call.workflow.json 上运行会返回 rc 1，并输出如下诊断：

{
  "ok": false,
  "command": "migrate",
  "type": "workflow",
  "source": { "path": "…/v1-baseline/agent-tool-call.workflow.json", "sha256": "4903056b…", "bytes": 5360 },
  "fromSchemaVersion": 1,
  "toSchemaVersion": 2,
  "preExistingDiagnostics": [],
  "migrationDiagnostics": [],
  "newSchemaDiagnostics": [
    {
      "code": "workflow/route-preset-conflict",
      "severity": "error",
      "message": "Workflow edge \"chat->planner\" cannot satisfy route preset \"drop\" under readable-v2 constraints (minimum 8px endpoint stubs, 16px interior turns, and 28px direct clearance)."
    }
  ]
}

三类诊断，三种处理

回执分为三个数组，不要混淆：

preExistingDiagnostics：v1 源本身早已有错。处理方式：先修 v1 文件，再重新迁移。
migrationDiagnostics：转换本身失败（路径、文件重复、JSON 无法读取）。处理方式：修正命令行。
newSchemaDiagnostics：转换成功，但结果不满足 v2 约束。处理方式：手动修改 v2 中的几何/route。

上面的 workflow/route-preset-conflict 属于第三类：该边的 route preset drop 在 readable-v2 约束下无法成立（端点 stub ≥8px、内部拐弯 ≥16px、直接间隙 ≥28px）。修复方式是更改 route preset 或放宽布局，而不是强行使用工具。

迁移之后

使用前始终先验证新文件：

node $A/bin/archify.mjs validate workflow /tmp/migrated.workflow.json --quality showcase --json

v2 几何诊断使用稳定的 compiler 回执：

node $A/bin/archify.mjs validate workflow /tmp/migrated.workflow.json --layout-json

solver 的内部不是用于编辑的控制点，只能通过源中已声明的字段来影响。

何时不应迁移

来自 SKILL.md：当现有源需要旧的固定几何时，保留 schema_version: 1——例如已打印到文档中、坐标必须逐像素匹配的图表。新的 workflow 源则始终使用 v2。

关于布局、pin、迁移和回执的标准契约位于 renderers/workflow/README.md 的 "Layout contracts" 一节。