@flow3d/devtools

Flow3D 开发者工具（M6 交付）：文档校验 CLI、浏览器图检查器面板与性能 HUD。 本包不引入 three，仅依赖 @flow3d/core 的公共 API 与 DOM，可在 Node 与浏览器两端使用。

安装

pnpm add @flow3d/devtools

CLI（Node 端）

# 静态校验一份图文档；error>0 退出码 1，--strict 时 warning>0 也退出码 1
flow3d-devtools validate path/to/doc.json [--strict]

# 输出结构化的检查摘要（节点/流计数、单位、布局策略、归一化位置）
flow3d-devtools inspect path/to/doc.json

validate 复用 core 的 validateStatic；inspect 在通过静态校验后额外调用 normalizeGraph 补全每个节点的解析后位置与状态。文件读取失败退出码 2。

浏览器端（面板 / HUD）

import { createInspector, createHud } from '@flow3d/devtools';
import type { SceneHandle } from '@flow3d/devtools';

// 检查器面板：列出节点/流，点击节点即聚焦（FR-22）
const inspector = createInspector({ container: canvas.parentElement!, scene });
// 性能 HUD：悬浮显示 FPS / 节点数 / 流数 / 最近一次 apply 耗时
const hud = createHud({ container: canvas.parentElement!, scene });

// 不再需要时清理（移除 DOM 与事件订阅）
inspector.dispose();
hud.dispose();

scene 的类型是导出的结构接口 SceneHandle——它只描述 listNodes() / listFlows() / focus() / events 子集，刻意不引用 core 的 FlowScene 类本身，便于解耦与 tree-shaking。 真实的 FlowScene 因结构兼容可直接传入。

公共 API

• 纯函数：validateDocument(doc)、inspectDocument(doc)、defaultValidationContext()
• 面板：createInspector(options) / createHud(options)（返回带 dispose() 的句柄）
• 类型：InspectSummary / InspectNodeSummary / InspectFlowSummary / InspectorOptions / InspectorHandle / HudOptions / HudHandle / SceneHandle
• 常量：VERSION

设计依据

见仓库 docs/01-Flow3D-技术设计文档.md 与 docs/03-Flow3D-实现确定性附录.md。 任何实现细节以这两份文档为准。

License

MIT