# Tool / ToolFlow 基建设计

本轮产品模型（优先）。目标设计草案，尚未实施。总体边界见设计概述。

醒目声明：心智上借用 VisionPro 的 Tool /（原 CogToolBlock）容器思路，自有命名为 Tool / ToolFlow。除该心智模型外，整体设计与 VisionPro 完全不一样——架构、服务边界、实现、持久化、与 UI 关系等均为自研重建，不以复刻 VisionPro 为设计目标，不承诺任何兼容。基建以 UI 无关的 C++ 底层服务实现；上层可接 C# 编辑/显示、其它 UI，以及 纯编排运行（无 UI）。

明确不接入：现有 MPF_ToolBlock / InsToolBlock 合入方案。
旧 DAG 文已废止：原 dag-dataflow.md（「DAG 图像流转」）已废止，仅为防 404 的短文；勿再作编排对照或历史权威阅读。编排专题目径统一为 Tool / ToolFlow。

关联（成像与显示基建，非编排执行模型）：图像模型 · 内存 · 显示 · 输出观察

# 1. 目标与非目标

# 1.1 目标

# 1.2 非目标

# 1.3 设计立场（一句话）

C++ 服务层拥有 Tool / ToolFlow / Terminal / Link / Run 的真相；UI 只是编辑与可视化绑定；执行主模型是工具流（或组）内自上而下顺序 Run + 链接赋值，连续采集用多次 Run，不用环。除 Tool / 容器心智外，与 VisionPro 完全不同。

# 2. 术语

心智上借用 VisionPro 的 Tool / CogToolBlock 容器思路；名称、架构与实现均为自有。下表中英对照；不假称与 Cognex API 同名同义兼容，也不以复刻 VisionPro 为目标。

Tool vs ToolFlow

• Tool：做一件视觉事；接口是自身属性。
• ToolFlow：把多件视觉事收成可复用黑盒；对外只有终端契约；Run = 跑完内部有序工具（及日后脚本）。

# 3. 对象模型（C++ 服务层）

# 3.1 核心类型与职责

示意关系（非 UML 定稿）：

RunSession
  └── root ToolFlow
        ├── Terminals: Inputs[], Outputs[]
        ├── tools[]: Tool | ToolFlow | ToolGroup   (有序)
        ├── links[]: Link
        └── disabled: set of tool ids

# 3.2 所有权与生命周期原则

自洽原则（旧 DAG 文已废止，不以之为权威）：

1. 工具流拥有子工具：ToolFlow/ToolGroup 拥有 tools[] 的生命周期；移除或销毁工具流时销毁子树（除非显式「抽出」到另一所有者，MVP 不做共享所有权）。
2. 链接不拥有数据：Link 只描述赋值关系；值落在属性或终端上。
3. 图像值有明确句柄语义：图像属性/终端持有由成像基建提供的句柄（见 image-model / memory）；工具不得在 Run 结束后继续写已交给下游的稳定结果。细节实现可复用成像包契约，但编排不以 DAG 边模型描述。
4. 一次 Run 的结果可见性：Run 返回后，Outputs 终端与工具输出属性可读，直到下次 Run 覆盖或工具流被重置；UI「最近结果」是观察层，不是第二次执行的隐式输入源。
5. 线程：默认假设单会话内 Run 可重入策略由宿主约定；MVP 规定 同一 RunSession 同时只允许一次 Run（可排队或拒绝）。跨会话并行由宿主多开 Session。

# 3.3 ToolFlow：对外终端与对内列表

# 4. 执行模型

# 4.1 主模型：自上而下顺序 Run

本方案权威调度（自研定稿；非 VisionPro 复刻）：

运行工具组/工具流时，按列表自上而下依次调用每个（未禁用）子工具的 Run。

这是本方案的权威调度模型，不是「由全局依赖边推导就绪即跑」的 DAG 引擎。

伪代码：

ToolGroup::Run(ctx):
  for tool in tools:                    // 列表序
    if tool in disabled: continue
    apply_links_into(tool)              // 见 §4.2
    status = tool.Run(ctx)              // 若 tool 是嵌套工具流，递归同样模型
    if failed(status) and abort_on_failure:
      record_and_abort
      return
  apply_links_to_flow_outputs()         // 工具流级 Outputs

# 4.2 链接何时推 / 拉

外部公开材料未钉死实现细节；本方案自研定稿如下（可落地）：

失败中止时：已跑工具的输出可保留供诊断；未跑工具不更新；工具流 Outputs 标记不完整/失败状态。

推模型等价实现：若实现选择「源 Run 后立即推到所有目标」，须保证与「目标 Run 前拉」对同一次顺序表结果一致，并处理禁用导致的目标跳过。

# 4.3 失败、禁用、嵌套、连续采集

# 4.4 与「流程图 UI」的关系

• 编辑器核心可以是 树/列表 + 属性连线 + I/O 终端页（对应工具流编辑心智）。
• 允许另做画布视图，但执行真相仍是有序列表 + 链接，画布不得引入与列表序冲突的隐式并行，除非未来单独立项并改本文。

# 5. 链接与类型系统

# 5.1 端口与端点

端点定位：

• tool_id.property_path（如 pmalign.OutputImage、blob.Result.Count）
• flow.Inputs.name / flow.Outputs.name

终端与属性都带 类型描述符（运行时与持久化共用）。

# 5.2 类型类别（MVP）

# 5.3 兼容规则

工具流终端与序：

• Inputs 终端视为在所有子工具之前已就绪（宿主或父级注入）。
• Outputs 终端只能由内部源写入，且在工具流结束时固化。
• 子工具之间：若存在 A→B 的链接，则列表中 A 必须在 B 之前（编辑器自动排序或拒绝非法序）。

# 5.4 Fixture / Region（强调）

定位 → 夹具 → 测量 是工具链语义，不是第二套编排图：

1. 定位工具输出位姿/变换；
2. Fixture 工具在图像坐标树上附着新空间；
3. 下游工具的 Region 落在 Fixture 空间，输入图常仍为原图像句柄。

文档与 API 用属性表达空间与 ROI，不引入「坐标系节点类型 / Region 图模型」。

# 6. 持久化与复用

# 6.1 需求（先定需求，不臆造二进制）

# 6.2 非目标（持久化）

• 不承诺兼容 Cognex .vpp。
• 不承诺兼容 MPF 既有序列化。
• 不在本文规定加密与签名（若产线需要，另文）。

# 7. 服务边界

# 7.1 C++ 核心提供什么

# 7.2 进程形态倾向

MVP：先交付可静态/动态链接的 C++ API；C# 通过 P/Invoke 或 C++/CLI 绑定同一库；headless runner 直接链库。若后续要独立进程，保持 同一领域 API 外形，仅换传输。

# 7.3 上层分工

依赖方向：

UI / Runner / 产线宿主  →  Tool / ToolFlow C++ API  →  Imaging（图像句柄/内存，可 C++ 或经边界）

成像与显示基建文档（image-model / memory / display）继续作为像素与显示契约来源；不把其历史上的「DAG 编排」叙述带回本编排核心。

# 8. 与现有文档关系

# 9. 示例

# 9.1 单工具流水线

ToolFlow "InspectA"
  Inputs:  (none; 内部 Acq 自取) 或 InputImage
  Tools (序):
    1. AcqFifoTool      → OutputImage
    2. PMAlignTool      ← InputImage ← (1).OutputImage
                        → Pose
    3. FixtureTool      ← InputImage ← (1).OutputImage
                        ← Pose       ← (2).Pose
                        → OutputImage (同像素, Fixture 空间)
    4. BlobTool         ← InputImage ← (3).OutputImage
                        ← Region in Fixture space
                        → Count, Results
  Outputs:
    OkNg     ← script 或判定工具 / 后续钩子；MVP 可用计数工具写 bool
    Defects  ← (4).Count

宿主：session.Run() 一次 = 一工具流内自上而下跑完。

# 9.2 两工具流串联

ToolFlow "Locate"
  Outputs: FixturedImage, Pose

ToolFlow "Defect"
  Inputs:  Image, Pose
  Tools:   Fixture 或直接测 → Blob/Caliper …
  Outputs: OkNg, DefectCount

Job:
  tools: [Locate, Defect]
  links: Locate.Outputs.FixturedImage → Defect.Inputs.Image
         Locate.Outputs.Pose          → Defect.Inputs.Pose

外层也可以是 ToolGroup/Job 级有序列表；同样自上而下，先 Locate.Run 再 Defect.Run。

# 9.3 嵌套工具流

ToolFlow "OuterMeasure"
  Tools:
    1. ToolFlow "InnerLocate"   # 采集+定位+Fixture，对外只露 FixturedImage
    2. CaliperTool / BlobTool    ← Image ← InnerLocate.Outputs.FixturedImage
  Outputs: Width, OkNg

排障时只打开 InnerLocate 看定位链；外层保持干净。

# 9.4 C++ 用法试想（设计示意，非已定 API）

下列为 试想中的宿主写法，用来钉住「创建 → 组流水线 → Run → 取结果」的手感。类型名、头文件、命名空间均可在实现期调整；不是已发布头文件，也不承诺与 VisionPro / MPF 同形。

目标手感（最小闭环）：

1. 创建（或加载）一个 ToolFlow
2. AddTool 按序放入原子 Tool（或嵌套 ToolFlow）
3. 建 Terminal / Link（或用便捷 API 连属性）
4. Run
5. 从 Outputs（或工具属性）取结果

#include <toolflow/toolflow.hpp>   // 示意

using namespace av::toolflow;

int main() {
  // 1) 注册表：按类型 id 创建工具（真实项目里通常进程启动时注册一遍）
  ToolRegistry registry;
  register_builtin_tools(registry);  // Acq、PMAlign、Fixture、Blob…

  // 2) 创建空工具流（也可 ToolFlow::Load("inspect.avtf")）
  auto flow = ToolFlow::Create("InspectA");

  // 3) 按列表序添加工具（返回非拥有观察指针 / id，所有权在 flow 内）
  auto* acq   = flow->AddTool(registry.Create("acq_fifo",  "Acq"));
  auto* align = flow->AddTool(registry.Create("pm_align",  "Align"));
  auto* fix   = flow->AddTool(registry.Create("fixture",   "Fixture"));
  auto* blob  = flow->AddTool(registry.Create("blob",      "Blob"));

  // 4) 对外终端（块级契约）；内部也可先不建终端、只链工具属性
  flow->AddInput ("InputImage", Type::ImageGray8);   // 可选：由宿主注入
  flow->AddOutput("DefectCount", Type::Int32);
  flow->AddOutput("OkNg",        Type::Bool);

  // 5) 链接：源 → 目标（校验类型 + 「源在列表中须先于目标」）
  flow->Link(acq,  "OutputImage", align, "InputImage");
  flow->Link(acq,  "OutputImage", fix,   "InputImage");
  flow->Link(align,"Pose",        fix,   "Pose");
  flow->Link(fix,  "OutputImage", blob,  "InputImage");
  flow->Link(blob, "Count",       flow->Output("DefectCount"));
  // OkNg：MVP 可用简单阈值或后续判定工具；示意略

  flow->ValidateOrThrow();  // 类型、序、环（按链接+列表序）

  // 6) 运行会话：同一 session 同时只允许一次 Run
  RunSession session(flow);
  // 若使用 InputImage 终端：
  // session.SetInput("InputImage", image_handle);

  RunResult r = session.Run();
  if (!r.ok) {
    // r.failed_tool_id / r.message / 已跑工具的 LastRun 可供诊断
    return 1;
  }

  // 7) 取结果：工具流 Outputs 或工具属性
  int count = session.GetOutput<int>("DefectCount");
  // bool ok = session.GetOutput<bool>("OkNg");
  // auto img = blob->GetProperty<ImageHandle>("OutputImage"); // LastRun 观察

  return count >= 0 ? 0 : 2;
}

嵌套工具流（示意）：内层先组好再 AddTool 进外层，外层只链内层终端。

auto locate = ToolFlow::Create("InnerLocate");
// … AddTool + Link …
locate->AddOutput("FixturedImage", Type::ImageGray8);

auto outer = ToolFlow::Create("OuterMeasure");
outer->AddTool(std::move(locate));           // 嵌套，所有权转入 outer
auto* caliper = outer->AddTool(registry.Create("caliper", "Width"));
outer->Link(outer->Tool("InnerLocate")->Output("FixturedImage"),
            caliper, "InputImage");

Headless 加载配方（示意）：

auto flow = ToolFlow::Load("recipes/inspect_a.avtf", registry);
RunSession session(flow);
session.SetInput("InputImage", GrabOneFrame());
auto r = session.Run();
auto n = session.GetOutput<int>("DefectCount");

设计约束提醒（与上文一致）：

# 10. 路线

# MVP 明确不做

• 脚本引擎、与 MPF 合入、DAG 调度器、VisionPro 文件兼容、完整产线 IO 协议。

# 11. 自检清单（入口是否醒目）

• [x] 标题下声明：本轮产品模型优先；心智借用 Tool /（原 CogToolBlock）；除心智外与 VP 完全不同；C++ 自研重建、多 UI / 无 UI。
• [x] 不接入 MPF_ToolBlock；文首写明 旧 DAG 文已废止，编排专题目径为 Tool / ToolFlow。
• [x] 产品类型名统一为 ToolFlow（容器）；不再用 ToolBlock / 工具块作本方案类型名；总称用「Tool / ToolFlow 基建」等，避免与类型名打架。
• [x] 执行模型写明 自上而下顺序 Run，连续采集 多次 Run 非环。
• [x] 术语自有命名，标明心智对照但不宣称 API 兼容、不以复刻 VP 为目标。
• [x] 服务边界：C++ 核心 vs C# 显示 vs headless 共用。
• [x] 与成像文档可引用；旧 DAG 文仅废止短文，不作对照权威。

文档状态：设计草案 v1.1（2026-10-21，Asia/Shanghai）。补充 §9.4 C++ 用法试想。实施以代码与验收为准，不以本文完成度为功能完成。