www 工作副本（2026-10-21 Asia/Shanghai） 双轨：正文迁自 mvdocs toolflow（v1.9）。语义仍以该拍板为准；本页不改 T9 / Diagnostic 码表。 实现边界：include/vyntek/toolflow/** 为 NON-STABLE / STUB。RunSession::Run 可在工具仅报 NotImplemented 时仍为 Succeeded。GetOutput 空串 不是 KeepLatest。观察面在 output_inspector.hpp。RequestCancel 不停采集。详见文末对拍。 关联：cpp-headers · host-integration · output-inspection · session-lifecycle · csharp-binding · examples

Tool / ToolFlow 基建设计Copy Anchor Link

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

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

明确不接入：现有 MPF_ToolBlock / InsToolBlock 合入方案。 旧「DAG 图像流转」专题已废止并移除文件；勿再作编排对照或历史权威阅读。编排专题目径统一为 Tool / ToolFlow（本文）。

关联（成像与显示基建，非编排执行模型）：图像模型 · 内存 · 显示 · 输出观察（ T10 集合事件） · C++ 头文件 · C# 绑定（ T11） · 宿主集成（ R7） · 测试契约表（ R4 · §10.1 全文； Arden · R13 T13 索引对齐） · 术语终检（ R8；撞号含 R13）

1.1 目标Copy Anchor Link

1.2 非目标Copy Anchor Link

1.3 设计立场（一句话）Copy Anchor Link

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

2. 术语Copy Anchor Link

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

Tool vs ToolFlow

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

3.1 核心类型与职责Copy Anchor Link

示意关系（非 UML 定稿）：

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

3.2 所有权与生命周期原则Copy Anchor Link

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

1. 工具流拥有子工具：ToolFlow/ToolGroup 拥有 tools[] 的生命周期；移除或销毁工具流时销毁子树（除非显式「抽出」到另一所有者，MVP 不做共享所有权）。
2. 链接不拥有数据：Link 只描述赋值关系；值落在属性或终端上。
3. 图像值有明确句柄语义（与 image-model.md / memory-management.md 用语对齐）：属性/终端持有成像基建句柄；交给下游（经链接赋值写入目标输入）前须 稳定发布为 Access=ReadOnly（典型路径：Complete / CompleteAndOpenRead / ShareImage 等，见成像专题）。已交下游的输入句柄不得再改写；工具不得在 Run 结束后继续写已交给下游的稳定结果。链接赋值只传句柄/值，不是 DAG 边调度。细节实现复用成像包契约，编排模型仍以本文顺序 Run 为准。交接路径与可测断言见 §3.4（T6）。
4. 一次 Run 的结果可见性：Run 返回后，Outputs 终端与工具输出属性可读，直到下次 Run 覆盖或工具流被重置；UI「最近结果」是观察层，不是第二次执行的隐式输入源。
5. 线程：MVP 规定 同一 RunSession 同时只允许一次 Run；并发第二次调用 拒绝（明确错误）。排队留到后阶段。跨会话并行由宿主多开 Session。

3.3 ToolFlow：对外终端与对内列表Copy Anchor Link

3.4 PixelImageHandle 交接对照表（T6 · P0）Copy Anchor Link

Alive 拍板（T6）：工具流内图像交接以本表 + §3.2 + image-model.md / memory-management.md 为准。 三条硬规则：（1）交给下游前须 稳定发布为 Access=ReadOnly；（2）已交下游的输入句柄不得再改写；（3）链接赋值只传句柄/值，不是 DAG 边调度（执行仍是 §4 列表序 Run）。 执行器检查发布契约，不为工具代申请像素权限或代 Complete；生产者负责在输出可被链接拉走之前完成稳定发布。

下列路径对齐成像公开表面（Share / Complete / CompleteAndOpenRead / ShareImage / Clone 等）。「下游」指经 Link 赋值写入目标输入属性/终端 后、即将被后续工具 Run 消费的句柄。

勾选约定（勿误勾）：下表「契约勾选」列以 test-contracts.md 为权威（列标题即 → test-contracts TC-H*），本表不独立验收。该文件 line 3 与四份薄摘明确规定「smoke 与 Controls.Tests 不等于本表通过」「外形 ≠ 验收」：验收另需供应商 SDK 实机与真实渲染/GPU/context 重建等条件。tests/orchestration_contracts.cpp 已覆盖 TC-H1…H10 的单测断言，但不构成勾选依据，故本表保持全 [ ]。单测覆盖情况见 test-contracts.md 文末《单测覆盖度记录》。

与成像文档的对齐要点（勿另造语义）

• 稳定发布路径：Complete / CompleteAndOpenRead + ShareImage，或工厂/Copy 直接得到的 ReadOnly 句柄；见 image-model「ShareImage / Clone」段与 memory「写入提交」。
• 工具流输入统一按 ReadOnly 消费；公共表面可有 OpenWrite，输入以能力上限立即拒绝。
• 链接 ≠ DAG：本表只约束句柄能力与发布时机；调度权威仍是 §4.1 顺序 Run。

4.1 主模型：自上而下顺序 RunCopy Anchor Link

本方案权威调度（自研定稿；非 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_tool_failure:
      record_and_abort
      return
  apply_links_to_flow_outputs()         // 工具流级 Outputs

4.2 链接何时推 / 拉Copy Anchor Link

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

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

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

4.3 失败、禁用、嵌套、连续采集Copy Anchor Link

4.4 与「流程图 UI」的关系Copy Anchor Link

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

5. 链接与类型系统Copy Anchor Link

Alive 拍板（T3）：TypeDesc / Value / PropertyBag 以本节 MVP 子集为准；属性路径不做表达式/脚本；图像跨格式禁止；几何/ROI/Fixture 仅为工具语义字段，不是第二套图模型。命名与 cpp-headers.md / §7.4 一致：类型描述符一律 TypeDesc（勿另造 TypeDescriptor / PortType）。

5.1 端口与属性路径Copy Anchor Link

端点定位（编辑期与持久化共用同一语法；无表达式、脚本、函数调用路径）：

规则：

终端与属性都带 TypeDesc（运行时与 .avtf 共用）。

5.2 TypeDesc MVP 子集Copy Anchor Link

TypeDesc 描述「可链接 / 可持久化」的值类型；与 §7.4 示意 TypeDesc{Type::…} / vyntek::toolflow::TypeDesc 同名。

5.2.1 Type 枚举（MVP 闭集）Copy Anchor Link

MVP 不纳入：任意 blob、脚本闭包、多态 any、未登记像素格式、表达式类型。

示意：

// 与 §7.4 / cpp-headers 一致；非已发布 ABI
namespace vyntek::toolflow {
  enum class Type : uint16_t {
    Bool, Int32, Int64, Float32, Float64, String,
    ImageGray8, ImageRgb24, ImageBgr24, ImageDepth16,
    Point2d, Line2d, Circle2d, Rect2d, Affine2d, Pose2d,
    Region, Fixture, RunStatus, Enum
  };
  struct TypeDesc {
    Type type;
    // Enum 时可选：std::string enum_id;
  };
}

5.3 Value / PropertyBagCopy Anchor Link

约束：

• 图像载荷为 vyntek::imaging 公开句柄（如 PixelImageHandle），不是像素拷贝；交给下游前须 ReadOnly 发布（§3.2）。
• 配置态属性可写入 .avtf；结果态属性默认不持久化（§6.4）。
• PropertyBag::Get/Set 按 TypeDesc 校验；类型不符 → DiagnosticCode::TypeMismatch（§7.4.6）。
• 已知 type、缺必填配置属性：Validate 报 MissingRequiredProperty（T8）；不得在 Load/Validate 用静默默认值把缺失必填糊成成功。可选属性可缺省；与「未知 type_id → Load UnknownTypeId」分轨。

// 示意
struct Value {
  TypeDesc type;
  // variant: bool/int32/…/PixelImageHandle/Point2d/… 
};
class PropertyBag {
 public:
  bool Has(std::string_view name) const;
  TypeDesc GetType(std::string_view path) const;   // 支持 a.b
  expected<Value, Diagnostic> Get(std::string_view path) const;
  expected<void, Diagnostic> Set(std::string_view path, const Value& v);
};

5.4.1 可链接类型表（MVP）Copy Anchor Link

未列出的组合一律 不兼容。

5.4.2 数值提升白名单（正向；反向禁止）Copy Anchor Link

5.4.3 图像格式：精确匹配Copy Anchor Link

5.4.4 方向、序与其它Copy Anchor Link

工具流终端与序：

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

5.5 几何 / ROI / Fixture 最小字段Copy Anchor Link

与历史 §5.4 口径一致并写死字段：定位 → 夹具 → 测量 是工具链语义，不是第二套编排图 / Region 图模型 / 坐标系拓扑单元类型。

5.5.1 语义链（非图模型）Copy Anchor Link

1. 定位工具输出 Pose2d / Affine2d；
2. Fixture 工具输出 Fixture（空间名 + 变换），在图像坐标解释上附着新空间；
3. 下游工具的 Region 落在 Fixture 空间；输入图像句柄常仍为原图像（同像素，不同空间解释）。

5.5.2 最小字段（MVP）Copy Anchor Link

禁止：

• 引入「坐标系节点 / Region 边 / 几何图」作为编排一等公民；
• 把 Fixture 当成第二套图像句柄模型；
• 在属性路径中写脚本计算 ROI。

6.1 需求（先定需求，不臆造二进制）Copy Anchor Link

6.2 非目标（持久化）Copy Anchor Link

• 不承诺兼容 Cognex .vpp。
• 不承诺兼容 MPF 既有序列化。
• 不在本文规定加密与签名（若产线需要，另文）。
• 加载器不得尝试「静默迁移」 MPF / VisionPro 文件为 .avtf；遇异格式应明确失败。

6.3 文档 / 配方格式目标Copy Anchor Link

顶层字段写法（已定稿倾向；实现以本结构为准，不要来回改名）：

{
  "schema_version": 1,
  "kind": "toolflow",
  "meta": { "name": "InspectA", "created": "...", "author": "...", "component_version": "…" },
  "flow": { /* inputs[]、outputs[]、tools[]、links[]、disabled、flags — 嵌套见 §6.6 */ },
  "assets": [ /* 可选；kind/path；见 §6.6.3 */ ]
}

6.4 必须持久化 vs 运行时态Copy Anchor Link

原则：配方描述「是什么、怎么连」；不描述「上一次跑成什么样」。 演示图/金样若需要，以可选附件引用表达，默认不嵌入。旁路字段见 §6.6：assets[].path + kind: "golden_image"。

6.5 版本字段、向前兼容、未知工具与缺属性（Alive 拍板 · T8）Copy Anchor Link

两条版本轴互不替代：schema_version 管文档形状门禁；component_version 管组件/配方信息标签。缺属性与未知 type 分属 Validate / Load，不得用静默默认值糊弄。

对照（勿混）：

6.6 .avtf 嵌套 schema（Alive 拍板 · T5）Copy Anchor Link

不改已拍板顶层名：schema_version / kind / meta / flow（见 §6.3）。本节展开嵌套对象与 assets[]；像素不嵌入文档。

6.6.1 顶层与 flow 嵌套字段Copy Anchor Link

终端元素（inputs[] / outputs[]）：

工具元素（tools[]）：

链接元素（links[]）：

6.6.2 正样例（最小合法）Copy Anchor Link

{
  "schema_version": 1,
  "kind": "toolflow",
  "meta": {
    "name": "InspectA",
    "component_version": "1.2.0"
  },
  "flow": {
    "id": "flow_inspect_a",
    "name": "InspectA",
    "abort_on_tool_failure": true,
    "inputs": [
      { "id": "tin_img", "name": "InputImage", "type": "ImageGray8" }
    ],
    "outputs": [
      { "id": "tout_cnt", "name": "DefectCount", "type": "Int32" },
      { "id": "tout_ok", "name": "OkNg", "type": "Bool" }
    ],
    "tools": [
      {
        "id": "acq",
        "type_id": "acq_fifo",
        "name": "Acq",
        "props": { "TimeoutMs": 1000 }
      },
      {
        "id": "align",
        "type_id": "pm_align",
        "name": "Align",
        "props": { "AcceptThreshold": 0.6 }
      },
      {
        "id": "blob",
        "type_id": "blob",
        "name": "Blob",
        "props": {
          "Region": { "space": "", "shape": { "x": 10, "y": 10, "width": 200, "height": 120 } }
        }
      }
    ],
    "links": [
      { "id": "l1", "src": "flow.Inputs.InputImage", "dst": "acq.PassthroughImage" },
      { "id": "l2", "src": "acq.OutputImage", "dst": "align.InputImage" },
      { "id": "l3", "src": "align.OutputImage", "dst": "blob.InputImage" },
      { "id": "l4", "src": "blob.Count", "dst": "flow.Outputs.DefectCount" }
    ],
    "disabled": []
  },
  "assets": [
    {
      "kind": "golden_image",
      "path": "assets/golden/board_a.png",
      "role": "template",
      "tool_id": "align"
    }
  ]
}

嵌套 ToolFlow 正样（节选）：外层 tools[] 中一项带内层 flow，外层 links 只连内层终端名（经内层工具 id + Outputs.* 或文档约定的终端路径），禁止写内层私有子工具属性路径。

6.6.3 assets[]（像素不嵌入）Copy Anchor Link

规则：

• 像素不嵌入：.avtf 正文无图像字节；金样/演示图一律旁路文件。
• 缺失旁路文件：Load 结构仍可成功；Run/Validate 若工具需要该资产再报 IoFailure / 工具级失败（实现择一，须进诊断列表）。
• component_version（meta 或未来工具级）可选；缺失、空串、非 semver 均不拦 Load（T8；不作 schema 门禁）。

6.6.4 反样例（须拒绝或校验失败）Copy Anchor Link

7.1 C++ 核心提供什么Copy Anchor Link

7.2 进程形态倾向Copy Anchor Link

MVP：先交付可静态/动态链接的 C++ API；C# 绑定同一库时 MVP = PInvoke（C++/CLI 非默认；细则见 csharp-binding.md）；headless runner 直接链库。若后续要独立进程，保持 同一领域 API 外形，仅换传输。

7.3 上层分工Copy Anchor Link

依赖方向：

UI / Runner / 产线宿主  →  Tool / ToolFlow C++ API（vyntek::toolflow）  →  vyntek::imaging（C++ 像素/句柄权威）

成像与显示基建文档（image-model / memory / display）继续作为像素与显示契约来源；像素/句柄权威在 C++ vyntek::imaging，C# 仅为绑定/显示投影。不把历史上的「DAG 编排」叙述带回本编排核心。

宿主集成（Arden · R7）：headless / C# 显示宿主同核、示意 C 导出（vyntek_toolflow_* / vyntek_imaging_*，非稳定 ABI）、跨边界 opaque / Diagnostic 上抛 / UI 只消费投影 / 观察不驱动 Run、停止矩阵宿主侧分派——见专文 host-integration.md。本节 §7.2–7.4 语义与 Diagnostic 不因 R7 改动（保持 v1.9）。

7.4 公共 API 表面（示意）Copy Anchor Link

示意 API，非已发布头文件。 类型名、命名空间、错误码与头文件路径均可在实现期调整；与 §9.4 手感一致，用于钉住宿主能力边界，不是稳定 ABI，也不承诺与 VisionPro / MPF 同形。

7.4.1 创建、注册、AddTool、终端Copy Anchor Link

// 示意、非已发布 ABI。命名空间 vyntek::toolflow；头文件见 cpp-headers.md
#include <vyntek/toolflow/toolflow.hpp>
#include <vyntek/toolflow/registry.hpp>

using namespace vyntek::toolflow;

ToolRegistry registry;
register_builtin_tools(registry);

auto flow = ToolFlow::Create("InspectA");           // 拥有所有权的根
auto* acq = flow->AddTool(registry.Create("acq_fifo", "Acq"));  // 所有权转入 flow
// ToolId id = acq->id();                           // 对外稳定标识

flow->AddInput("InputImage", TypeDesc{Type::ImageGray8});
flow->AddOutput("DefectCount", TypeDesc{Type::Int32});

7.4.2 Link 建立与校验Copy Anchor Link

Link 校验规则（与 §5.4 / §4.3 对齐，API 层必须执行）：

校验失败路径（示意）：

#include <vyntek/toolflow/link.hpp>

// 建链：类型或列表序不合规则拒绝（不留下半条边）
auto link_result = flow->Link(acq, "OutputImage", align, "InputImage");
if (!link_result) {
  // link_result.error(): TypeMismatch / OrderViolation / Encapsulation …
  return;
}

// 批量编辑后统一校验
std::vector<Diagnostic> diags;
if (!flow->Validate(diags)) {
  for (const auto& d : diags) {
    // d.severity / d.tool_id / d.message — 编辑器标红或日志
  }
  return;
}
// 或：flow->ValidateOrThrow();  // 抛 ToolFlowValidationError

7.4.3 Run、RunSession、取消与失败中止Copy Anchor Link

#include <vyntek/toolflow/run_session.hpp>
#include <vyntek/imaging/handle.hpp>   // 只依赖成像公开句柄头

RunSession session(flow.get());    // MVP：session 不抢 flow 所有权
session.SetInput("InputImage", image_handle);  // vyntek::imaging::PixelImageHandle（ReadOnly）

RunContext ctx;                    // 可选：取消令牌、截止时间
RunResult r = session.Run(ctx);
if (!r.ok) {
  // r.failed_tool_id / r.message / diagnostics（含 Cancelled / Aborted）
  // abort_on_tool_failure=true 时后续子工具未 Run
}
// 同 session 并发第二次 Run → 拒绝（Busy）

# 停止矩阵（RunSession / 采集 / 显示 · Alive 拍板 · T9）Copy Anchor Link

三层勿混成一层：编排取消（RunSession）≠ 宿主停相机（采集）≠ 显示解除引用（ImageDisplay）。双向对齐： session-lifecycle.md · camera-acquisition.md · image-display.md。

硬规则（Alive）：

1. Cancel Run = 协作式 + 不再启动后续 Tool（码 Cancelled）；不做工具内抢占进 MVP。
2. 宿主停相机 ≠ 自动 Cancel 已在跑的 Run（两层写清；宿主若要两端都停，须显式既停采集又 RequestCancel）。
3. 显示只观察、不停编排（也不停相机）。

7.4.4 只读查询（上次状态与 Outputs）Copy Anchor Link

7.4.5 加载 .avtf 与查询（示意）Copy Anchor Link

#include <vyntek/toolflow/serialize.hpp>

auto loaded = ToolFlow::Load("recipes/inspect_a.avtf", registry);
if (!loaded) {
  // loaded.error(): UnknownTypeId / SchemaTooNew / IoFailure …
  return;
}
std::unique_ptr<ToolFlow> flow = std::move(*loaded);

RunSession session(flow.get());
session.SetInput("InputImage", grab_one_frame());
RunResult r = session.Run();
if (r.ok) {
  int count = session.GetOutput<int>("DefectCount");
  (void)count;
}

持久化字段分层与未知类型策略见 §6.3–6.6；Diagnostic 见 §7.4.6；未知工具 type id → 严格失败。

7.4.6 Diagnostic（Alive 拍板 · T4）Copy Anchor Link

对齐本示意 API（§7.4）与 MVP 退出（§10.1）：Validate / Run / Load 均返回结构化 Diagnostic 列表（可与 expected/RunResult 并存；不得只丢一条裸字符串）。

# 结构Copy Anchor Link

// 示意、非已发布 ABI；命名空间 vyntek::toolflow
enum class Severity : uint8_t { Error, Warning, Info };

enum class DiagnosticCode : uint16_t {
  TypeMismatch,      // 链接/赋值/Set 类型不兼容（含图像跨格式）
  OrderViolation,    // 列表序无法解释链接（源不在目标之上）
  Encapsulation,     // 跨越 ToolFlow 封装边界（绑内层私有属性）
  Busy,              // 同 RunSession 重入 / 并发第二次 Run
  UnknownTypeId,     // 注册表无此 type_id（Load/Create）
  SchemaTooNew,      // schema_version 高于加载器
  IoFailure,         // 文件读写/旁路资产打开失败等
  SourceDisabled,    // 拉值时源工具本轮禁用（MVP 严格失败）
  InvalidBinding,    // 端点不存在、方向非法、残缺链接等
  MissingRequiredProperty, // 已知 type 缺必填配置属性（Validate；T8）
  Aborted,           // abort_on_tool_failure 中止后续
  Cancelled,         // 协作式取消后未再启动后续
  // 实现可增内部码；对外文档以本表为准
};

struct Diagnostic {
  DiagnosticCode code;
  Severity severity;           // Error / Warning / Info
  std::string message;         // 人类可读；可本地化键另议
  std::string tool_id;         // 可选；相关工具稳定 id
  std::string path;            // 可选；属性路径或终端路径（§5.1）
  std::string link_id;         // 可选
};

# DiagnosticCode 表（MVP）Copy Anchor Link

未列出的内部码不得替代上表语义；新增对外码须改本文。

# 返回约定Copy Anchor Link

与 §10.1 / test-contracts.md 对齐的可测点：类型/序/禁用源/重入 Busy/过高 schema/未知 type id/缺必填属性（MissingRequiredProperty）/取消与失败中止，均须能在诊断列表中断言对应 DiagnosticCode（契约表 §8 码覆盖清单）。

7.5 头文件与模块边界Copy Anchor Link

完整 include 树、公开头列表、detail/ 边界及与 ImageDisplay（C#）分界见专文：

→ cpp-headers.md（命名空间 vyntek::toolflow / vyntek::imaging；公开前缀 / ）

摘要：

7.6 Tool 作者最小契约与 MVP 测试替身（T7 · P0）Copy Anchor Link

Alive 拍板（T7）：MVP 工具作者（含内置示意工具与 fake 替身）必须满足本节最小契约；注册约定与反序列化共用同一 ToolRegistry。fake 清单供 §9.1 / §10.1 headless 验收，不要求真实 Acq/PMAlign/相机 SDK。

7.6.1 作者必须实现什么Copy Anchor Link

示意表面（非已发布 ABI）：

// 示意：作者实现 ITool；勿当作已定头文件
struct ITool {
  ToolId id() const;
  std::string_view type_id() const;
  std::string_view name() const;
  bool enabled() const;

  // 属性袋：按名/路径读写 TypeDesc 约束下的 Value
  Span<const PropertyDesc> properties() const;
  expected<Value, Status> GetProperty(std::string_view name) const;
  Status SetProperty(std::string_view name, const Value& v);

  // 一次 Run：失败用 Status / 结构化诊断，勿抛未文档化异常穿过边界（实现期可定）
  ToolRunStatus Run(RunContext& ctx);
  // LastRun 状态：ok / failed / skipped / cancelled …
};

7.6.2 Registry 注册约定Copy Anchor Link

7.6.3 MVP fake 替身清单（headless §9.1 / §10.1）Copy Anchor Link

示意名；实现可放测试库。目标：无相机/无真实算法即可勾选 §10.1「执行 / 注册」相关项，并覆盖 §3.4 关键断言。

最小 headless 拼法（等价 §9.1）：FakeAcq → FakePMAlign → Passthrough（或 Blob 的 ConstantScalar 替身），链接图像与 Pose；断言 Outputs 与 §3.4 H6。真实工具落地后，fake 仍保留作回归。

8. 与现有文档关系Copy Anchor Link

9.0 场景规划索引Copy Anchor Link

成体系的可测场景目录（目的 / 前置 / 步骤骨架 / 期望断言 / 文档回链）见专文，避免把本节心智图与 §9.4 试想撑成验收剧本：

→ examples-scenarios.md（S01–S08； R6 S09a–d； Arden · R9–R12 S10–S13）

与 §10.1 / T13 / test-contracts.md（TC-* ↔ S01–S13； Arden · R13 索引对齐）勾选对照；成像契约片段见 examples.md。

9.1 单工具流水线Copy Anchor Link

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() 一次 = 一工具流内自上而下跑完。

MVP / headless：可用 §7.6.3 fake 替身等价拼装（如 fake_acq → fake_pm_align → fake_passthrough / fake_constant），无需真实 Acq/PMAlign/相机；句柄交接断言见 §3.4 / §10.1 H1–H10。

9.2 两工具流串联Copy Anchor Link

可测骨架（可选正路径）： examples-scenarios.md S09d · 契约 TC-RUN-07。

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 嵌套工具流Copy Anchor Link

可测骨架：合法嵌套 + Encapsulation → examples-scenarios.md S09a · 契约 TC-RUN-06 / TC-LNK-04。

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

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

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

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

目标手感（最小闭环）：

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

// 示意、非已发布 ABI（与 §7.4 / cpp-headers.md 一致）
#include <vyntek/toolflow/toolflow.hpp>
#include <vyntek/toolflow/registry.hpp>
#include <vyntek/toolflow/run_session.hpp>
#include <vyntek/imaging/handle.hpp>

using namespace vyntek::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", TypeDesc{Type::ImageGray8});   // 可选：由宿主注入
  flow->AddOutput("DefectCount", TypeDesc{Type::Int32});
  flow->AddOutput("OkNg",        TypeDesc{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 可用简单阈值或后续判定工具；示意略

  // 校验失败路径：也可 Validate(diags) 收集 Diagnostic 后返回
  if (auto vr = flow->Validate(); !vr) {
    // vr.error() / diagnostics：TypeMismatch、OrderViolation…
    return 1;
  }

  // 6) 运行会话：同一 session 同时只允许一次 Run
  RunSession session(flow.get());
  // 若使用 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<vyntek::imaging::PixelImageHandle>("OutputImage"); // LastRun 观察

  return count >= 0 ? 0 : 2;
}

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

auto locate = ToolFlow::Create("InnerLocate");
// … AddTool + Link …
locate->AddOutput("FixturedImage", TypeDesc{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 加载配方（示意）：

#include <vyntek/toolflow/serialize.hpp>

auto loaded = ToolFlow::Load("recipes/inspect_a.avtf", registry);
if (!loaded) {
  // UnknownTypeId / SchemaTooNew — 严格失败，不静默成功
  return 1;
}
RunSession session(loaded->get());
session.SetInput("InputImage", GrabOneFrame());  // ReadOnly 句柄
auto r = session.Run();
if (!r.ok) return 1;
auto n = session.GetOutput<int>("DefectCount");

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

10. 路线Copy Anchor Link

10.1 MVP 验收退出条件（可勾选 / 可测）Copy Anchor Link

下列为 MVP 完成 的退出条件摘要；须能在 无 UI 环境下用单测 + headless 证明。与 §11 清单对齐：清单管「文档口径」，本表管「可执行验收摘要」。

全文可勾选测试契约表（R4） → test-contracts.md 每条 = 前置 · 动作 · 期望 DiagnosticCode/状态 · 对应章节；覆盖注册/AddTool/Link/Validate/顺序 Run/Cancel/失败中止/Busy/Load·SchemaTooNew·UnknownTypeId·MissingRequiredProperty、 H1–H10、fake 注册、 S01–S13 映射（含嵌套/Encapsulation、SourceDisabled、InvalidBinding、IoFailure、停相机≠Cancel； Arden · R9–R12 OUT/ACQ/SESS/MEM/DISP）。§10.1 以下保留摘要勾选；细节与 ID（TC-*）以契约表为准。不写覆盖率 KPI。

勾选约定（勿误勾）：下列摘要勾选与 test-contracts.md 的 TC-* 表同属一套验收口径，权威在契约表。契约表 line 3 及四份薄摘（tc-acq/tc-sess/tc-out/tc-disp）明确规定「smoke 与 Controls.Tests 不等于本表通过」「外形 ≠ 验收」——验收另需供应商 SDK 实机适配与真实渲染/GPU 预算/图形 context 重建等条件。仓内 tests/orchestration_contracts.cpp、tests/smoke_headers.cpp 与 Vyntek.Controls.Tests 已覆盖对应单测断言，但不构成勾选依据，故本清单保持全 [ ]。覆盖情况与验收仍缺条件见 test-contracts.md 文末《单测覆盖度记录》。

对象模型与注册Copy Anchor Link

• ToolRegistry 可注册/创建至少一组内置示意工具（或测试替身 Tool），AddTool 后所有权在 ToolFlow 内。
• 可定义 Inputs/Outputs 终端（名称、类型、稳定 id）；嵌套 ToolFlow 仅通过终端对外链接（封装单测；场景 S09a）。
• （T7）register_fake_tools（或等价）可注册 §7.6.3 清单中至少：fake_acq、fake_pm_align、fake_passthrough、fake_fail_once；重复 type_id 注册被拒绝。
• （T7） 未知 type_id → UnknownTypeId；fake 与 builtin 共用同一 registry 契约（Create/Load）。

链接与校验Copy Anchor Link

• Link：类型兼容通过、不兼容拒绝；图像跨格式拒绝。
• 列表序：源在目标之下的链接被拒绝或 Validate 失败（无环 / 序一致）。
• 指向禁用工具：Run 时符合 §4.3 / §7.4.2（MVP：源禁用 → 下游严格失败）；诊断含 SourceDisabled（§7.4.6）；场景 S09b。
• Validate/Run/Load 失败路径可断言 DiagnosticCode（至少覆盖 TypeMismatch、OrderViolation、UnknownTypeId、SchemaTooNew、Busy、 MissingRequiredProperty）。
• （T8） 已知 type_id、缺必填配置属性 → Validate 失败（MissingRequiredProperty）；无静默默认值使校验通过。

执行Copy Anchor Link

• headless 加载或构建后跑通 §9.1 等价流水线（可用测试替身代替真实 Acq/PMAlign），Run 后 Outputs 可读且值符合链接赋值。
• abort_on_tool_failure=true：中途失败则后续子工具不 Run，RunResult 标识失败工具。
• 同一 RunSession 并发第二次 Run → 拒绝（有单测；不做排队）。
• 取消：RequestCancel 后不再启动后续子工具（协作式；码 Cancelled）；不测工具内抢占（T9）。
• （T9） 宿主停相机 不自动 Cancel 在途 Run；显示关闭 不停编排；停止矩阵三层可单测/文档对照（§7.4.3）；场景 S09c。
• 连续两次 Run 为两次独立执行；无环边；第二次覆盖上次 Outputs。

图像句柄交接（T6 · 对齐 §3.4 / §3.2）Copy Anchor Link

• H1–H2：Complete / CompleteAndOpenRead 提交语义可测；未 Complete 不得作为下游 ReadOnly 输入。
• H3–H4：ShareImage / ReadOnly Share → Access=ReadOnly；对下游输入 OpenWrite 立即拒绝。
• H5：ReadWrite 根上的 Share 不能冒充已稳定发布的下游输入。
• H6：链接赋值写入下游输入后句柄为 ReadOnly；链接不是 DAG 调度（序仍为列表 Run）。
• H7：已交下游的稳定结果在下游 Run 期间不可被生产者改写。
• H8：Clone 得新 BufferId 可写输出；源 ReadOnly 不变；再经稳定发布后可链接。
• H9–H10：ReadOnly ROI 不可写；失败/Invalid 输出不可假成功交给下游。

序列化Copy Anchor Link

• 保存 → 再加载 → 结构（序、终端、链接、禁用、参数）一致；可再次 headless Run。
• 含 schema_version；过高版本拒绝加载（SchemaTooNew）。
• （T8） 缺 / 坏 component_version不拦 Load；与 schema_version 门禁独立。
• 未知工具 type id → 严格失败；不静默当成功。
• 未知可选字段加载后仍保留在文档模型中（可告警、不剥掉）。
• 运行时态（LastRun 结果、注入值）默认不进配方；金样图不默认内嵌。

非目标门禁（MVP 不得误交付）Copy Anchor Link

• 无脚本引擎、无 MPF 合入、无 DAG 拓扑调度器、无 .vpp/MPF 文件加载、无完整产线 IO 协议。

§10.1 ↔ 测试生命周期映射（T13 · 薄表 · Arden · R13 索引对齐）Copy Anchor Link

验收勾选 ↔ 建议单测/集成测阶段。生命周期用语对齐工程文「注册→建流→Link/Validate→Run→Cancel/失败中止→Load 复载…」；可测、可勾。全文契约行（TC-*）与 S01–S13 映射见 test-contracts.md（含 Arden · R9–R12 OUT/ACQ/SESS/MEM/DISP）；本节为阶段索引。 Arden · R13 仅对齐索引/回链，不改 Diagnostic 码表 / T9 / v1.9 语义。

10.2 MVP 明确不做 / 归后续Copy Anchor Link

宿主形态对照与示意 C 导出（不做稳定 ABI / 不做编辑 UI / 不扩脚本）见 host-integration.md（ R7）；上表脚本等项仍仅占位，不因 R7 扩写。

开放风险只登记、不扩做：见 validation-and-roadmap.md「开放风险登记表」（ T15）。

11. 自检清单（入口是否醒目）Copy Anchor Link

• 标题下声明：本轮产品模型优先；心智借用 Tool /（原 CogToolBlock）；除心智外与 VP 完全不同；C++ 自研重建、多 UI / 无 UI。
• 不接入 MPF_ToolBlock；文首写明 旧 DAG 文已废止，编排专题目径为 Tool / ToolFlow。
• 产品类型名统一为 ToolFlow（容器）；不再用 ToolBlock / 工具块作本方案类型名；总称用「Tool / ToolFlow 基建」等，避免与类型名打架。
• 执行模型写明 自上而下顺序 Run，连续采集 多次 Run 非环。
• 术语自有命名，标明心智对照但不宣称 API 兼容、不以复刻 VP 为目标。
• 服务边界：C++ 核心 vs C# 显示 vs headless 共用。
• 与成像文档可引用；旧 DAG 文仅废止短文，不作对照权威。
• §7.4 公共 API 示意（创建/AddTool/Link/Run/Load .avtf/校验失败）并标明非已发布 ABI；与 §9.4 手感一致。
• §7.5 / cpp-headers.md 头文件与模块边界；公开头与 detail/ 分界；成像只依赖公开句柄头。
• §9.4 示例 #include 与公开头表一致（ / ）；类型名 TypeDesc / PixelImageHandle 全文统一。
• MVP 绑定倾向 PInvoke；C++/CLI 非默认；ImageDisplay 仅 C#；成像权威 C++ vyntek::imaging。
• §6.3–6.6 配方格式（.avtf）、持久化字段分层、版本与未知类型；§6.6 嵌套 schema + 正反样例；assets[]（kind:"golden_image" + path；可选 role/tool_id）；像素不嵌入；component_version 可选且不拦 Load；不承诺 MPF/VP 文件兼容。
• §5（T3） TypeDesc / Value / PropertyBag MVP；属性路径 tool_id.prop[.sub…]（无表达式）；可链接表 + 数值提升白名单 + 图像精确匹配；几何/ROI/Fixture 最小字段（非第二图模型）；与 cpp-headers TypeDesc 同名。
• §7.4.6（T4） DiagnosticCode 表与 severity；Validate/Run/Load 返回结构化 Diagnostic 列表；对齐 §7.4 / §10.1。
• §10.1 MVP 退出条件可勾选、可测，并与「明确不做」区分。
• §3.4（T6） PixelImageHandle 交接对照表；每条可测断言；回链 §10.1；对齐 image-model/memory/§3.2（ReadOnly 发布、已交下游不得改写、链接≠DAG）。
• §7.6（T7） Tool 作者最小契约、Registry 约定、MVP fake 替身清单（FakeAcq/FakePMAlign/Passthrough/FailOnce 等）；供 §9.1 / §10.1 headless。
• §6.5 / §7.4.6（T8）schema_version（过高→Load SchemaTooNew）与 component_version（可选、不拦 Load）分轨；已知 type 缺必填属性 → Validate MissingRequiredProperty（无静默默认）。
• §7.4.3（T9） 停止矩阵：Cancel=协作式/Cancelled；宿主停相机≠自动 Cancel Run；显示只观察不停编排；链 session-lifecycle / camera / display。
• 输出观察集合事件（T10） 见 output-inspection.md：EmptySnapshot / Unavailable / Evicted；失败保留上次成功；观察永不驱动 Run；对外 ToolId。
• C# 适配（T11） 见 csharp-binding.md：MVP=PInvoke；C++/CLI 非默认；opaque handle + Release/Dispose；ImageDisplay 仅 C#。
• §10.1 映射（T13） 验收勾选 ↔ 测试生命周期薄表（注册→…→fake； Arden · R13 增 OUT/ACQ/SESS/MEM/DISP + S10–S13 索引）。
• 测试契约表（R4） test-contracts.md：§10.1 / H1–H10 / Diagnostic / S01–S13 收成可勾选契约；§10.1 保留摘要并回链。
• 场景负路径与嵌套（R6） examples-scenarios.md S09a–d：嵌套+Encapsulation、SourceDisabled、InvalidBinding、IoFailure、停相机≠自动 Cancel、可选 §9.2 两流串联；契约映射已同步；不改本文 v1.9 语义与 §7.4.6 码表。
• 打包/库名（T14） 见 cpp-headers.md：libvyntek_toolflow / libvyntek_imaging；头树 / ；MVP 无稳定 ABI。
• 开放风险登记（T15） 见 validation-and-roadmap.md：只登记不扩做；与 §10.2 不做清单一致。
• 宿主集成（R7） 见 host-integration.md：headless / C# 显示宿主同核；示意 C 导出非稳定 ABI；停止矩阵宿主侧分派；不改本文 v1.9 语义与 §7.4.6 码表。
• 导读与术语终检（R8） 见 overview.md 角色化路径 + glossary.md：术语终检表；Arden R4–R8 vs T15 风险 R1–R10 撞号；S07↔host-integration 薄回链；保持本文 v1.9，不改语义与码表。
• 本批横切收束（Arden · R13） §10.1 T13 阶段索引对齐 test-contracts OUT/ACQ/SESS/MEM/DISP + S10–S13；过时 S01–S09 索引已更新；不改 Diagnostic / T9 / v1.9 语义。

文档状态：设计草案 v1.9（2026-10-21，Asia/Shanghai）。T3–T9； T10 输出集合事件； T11 C#/PInvoke；T12/T13； T14 打包/库名； T15 开放风险登记。 T16→T15 迭代清单文档侧已收口。 R4 测试契约表见 test-contracts.md（§10.1 摘要回链）。 R7 宿主集成见 host-integration.md。 R8 导读/术语终检见 overview.md / glossary.md。 Arden · R13 本批横切收束：§10.1 T13 索引对齐 OUT/ACQ/SESS/MEM/DISP + S10–S13（保持 v1.9；不改本文语义与 Diagnostic 码表 / T9）。Alive 拍板：.avtf 顶层名锁定、未知工具严格失败、同 session 重入拒绝、PInvoke 默认、component_version 不拦 Load、Cancel 协作式、停相机≠自动 Cancel Run、显示只观察、空快照必发事件、MVP 无稳定 ABI、废止 DAG 文仅指向本文。实施以代码与验收为准，不以本文完成度为功能完成。

本仓实现对拍Copy Anchor Link

勾选 TC-RUN / TC-LNK / TC-SER 未迁全文、未验收。