把 Unity(C#)插件按行为一比一复刻到 LayaAir(TypeScript)的移植体系:一个总指挥技能 /port + 4 个智能体工种 + 18 个带文档的命令行工具 + 会进化的知识库。
设计蓝图(宪法 + 路线图):unity-to-laya-skill-blueprint-final.html。本仓库是它的落地实现。
# 1. 填任务说明(唯一前置输入,六类信息)
# 编辑 porting-task.yaml
# 2. 环境自检 + 源材料校验(硬问题会打回,循环到 0 才放行)
node tools/port-doctor/port-doctor.mjs --task porting-task.yaml
# 3. 在 Claude Code 里执行总指挥技能
# /port.claude/
├─ skills/port/SKILL.md ← 总指挥 /port(九阶段编排:自检→打样→剖析→人确认→闭环→回归→人工清单→产品化→收割)
└─ agents/ ← 4 个智能体工种(实例健忘,积累靠知识库)
├─ surveyor.md ← 剖析员:源码 → 移植用例卡
├─ porting.md ← 复刻员:按卡写 Laya 地道实现(取数纪律:查库→读源码→标 inferred)
├─ detection.md ← 检测员:逐层验证 + 失败分类路由(结构错/缺映射/噪声/真分叉/升级)
└─ productizer.md ← 产品化员:文档/示例/打包
tools/ ← 18 个确定性命令行工具,每个自带 docs/<名>.md(强制文档规范,§14)
├─ port-doctor/ code-scan/ capture-unity/ capture-laya/ compare/
├─ kb/ (kb-query|update|validate|index|stage|promote|edit)
├─ gen-status/ gen-human-checklist/ regress/
└─ gen-api-docs/ upstream-diff/ package/
knowledge/ ← 会进化的知识库(文档即代码的映射注册表,§9)
├─ INDEX.md mappings.json ← 派生镜像(kb-index 生成,勿手改)
├─ verify-matrix.md ← 类型×层验证配方(标准流程资产,§5)
├─ mappings/ decisions/ ← 条目:状态机(guessed→verified→broken)+ 来源阶梯 + 证据溯源
└─ _candidates/ ← 暂存区:记录始终做,入库可选(kb-promote 人工门)
oracles/ ← 真值回归集(带溯源头;regress 重跑全套)
reports/ ← env-report / validation-report / port-manifest / STATUS.md / 人工清单
porting-task.yaml ← 任务说明模板(唯一前置输入)
- 黄金标准:同输入必同输出 → 工具;要判断 → 智能体。分层 技能→智能体→工具,不套娃。
- 分层验证:L0 静态 → L1 单元 → L2 逐帧 → L3 集成 → L4 人工;低层不过不验高层。
- 硬路由:每卡 lane ∈ auto/semi-auto/human/blocked/skip;
blocked(缺料)≠human(人验)。 - 失败分类学:结构错→修采集 · 缺映射→补知识库 · 噪声→白名单(人确认)· 真分叉→改实现 · 连败→升级人工。
- 两道门:质量门(自动全 passed + 人工清单全绿)≠ 商品门(文档/示例/打包/版本齐)。
- 自学习回路:闭环让经验可信(真值验证),知识库把可信经验存下来(kb-stage 暂存 → kb-promote 收割);探索成本付一次,无限摊销。
| 工具 | 职责 | 文档 |
|---|---|---|
| port-doctor | 环境自检 + 源材料校验(能力矩阵/硬问题打回) | tools/port-doctor/docs/ |
| code-scan | C# 解析 + 代码类型分类建议(A~G) | tools/code-scan/docs/ |
| capture-unity | Unity 端真值采集(隔离副本+反射探针+batchmode) | tools/capture-unity/docs/ |
| capture-laya | Laya 真实运行时行为采集(Playwright;裸 Node 仅降级退路) | tools/capture-laya/docs/ |
| compare | 坐标归一→容差→序列对齐→白名单→五类裁决(纯函数) | tools/compare/docs/ |
| kb-query/update/validate/index/stage/promote/edit | 知识库读写套件(结构约定永不腐坏) | tools/kb/docs/ |
| gen-status | 状态面板 STATUS.md(兼知识入库决策界面) | tools/gen-status/docs/ |
| gen-human-checklist | 人工验证清单(只收 human/semi-auto) | tools/gen-human-checklist/docs/ |
| regress | 回归护栏(重跑全部已验证真值) | tools/regress/docs/ |
| gen-api-docs / upstream-diff / package | 产品化三件套 | 各自 docs/ |
全部工具零外部依赖(Node.js ≥ 18 内置模块),capture-laya --url 模式需要 Laya 项目侧装 playwright。
⚠ capture-unity 环境前提:依赖 Unity 许可证已激活(否则 batchmode 报
Access token is unavailable起不来)+ 工程首次需预热编译(bee_backend,可能超--timeout)。因此 capture-unity → capture-laya → compare 全链路以 Unity 环境就绪为前提,非任意环境开箱即用(详见tools/capture-unity/docs/)。门禁:
npm test(=tools/gate/gate.mjs)跑四道自包含检查 —— kb-validate + 工具文档完整性 + 语法 smoke + regress 真值回归,提交前/CI 用。