[Wayfinder] WorkCell 组合定义、注册编译与分层 Action 暴露

[TablewareBox]

冻结设计（commit 8841d27）：候选工作单元（WorkCell）组合定义、启动与分层动作设计
变更审阅：PR #188

Outcome

作为候选工作单元（WorkCell）组合定义、启动、投影、动作（Action）暴露与跨仓验收的 Wayfinder 总导航。本票只维护目标、已接受决策、子票顺序、阻塞与跨票冲突；不再承载各协议面的完整 Schema、语法和验收细节。

已接受决策（Accepted Decisions）

1. 候选工作单元定义（WorkCell Definition）拥有独立一等定义身份；启用后产生独立候选工作单元实例（WorkCell Instance）身份。

2. v1 使用固定结构；保留 @workcell 函数语法，Python 定义文件可直接作为启动输入；不支持候选结构选择（StructuralChoice）或动态拓扑。

3. Python 与规范 JSON/结构化画布允许双向语义创作；同一草稿同一时刻只有一种可写模式，不承诺源码字节无损，发布前要求规范 digest 固定点。

4. D2-01～03=A（D2-01 已按维护者编辑器模型修订）：物理位姿采用右手 Z-up、毫米/度和固定 XYZ 欧拉合同；父子组合使用 assign_child_resource(..., pose=Pose(...))；嵌套世界位姿通过矩阵递归组合。2D/3D 编辑共用唯一物理 pose，不增加节点级 ui_layout；定义级可选 layout_plane 选择 XY/XZ/YZ 观察与编辑平面。

5. D3-02=A：零覆盖不创建或持久化空 params 文件/记录；参数输入缺席表示“无覆盖”，但每次启用仍生成并持久化脱敏候选启用快照（Activation Snapshot）。

6. D3-03=A：一次启用最多接受一个外部覆盖对象；多个外部来源同时出现时在硬件副作用前失败，不做隐式叠加或优先级合并。

7. D3-04=A：Phase 0 仅支持 Python-only 零外部参数路径；完整 v1 保留单一外部覆盖对象合同。

8. D3-05：复用现有 -g/--graph 作为唯一启动定义来源参数，不新增 --workcell。

9. D3-06=A：-g/--graph 严格按 .py、.json、.graphml 后缀分派；未知或无后缀失败，不做内容探测。

10. D3-07=A：一个 .py 启动文件必须恰好声明一个顶层 @workcell 根定义；零个或多个失败，被引用的嵌套定义不计入。

11. D3-08=A：任意已登记设备作者句柄只消费已发布目录的 init_param_schema.config；现代 @device 由带类型的 __init__ 静态生成，作者句柄不另建合同。

12. D3-09=A：公开 InitParam 使用封闭类型闭集，fan-out 取全部目标 Schema 的无隐式转换安全交集。

13. D3-10=A：唯一外部输入规范化为封闭候选启用请求（Activation Request），并由 definition_digest 绑定精确定义；零外部输入时整个对象缺席。

14. D3-11=A：v1 仅从 workspace/package 内显式文件启动；未来目录引用必须固定 exact revision/digest，禁止 latest。

15. D3-12=A：实例身份、根世界位姿、外部连接和 Edge/机器放置属于实例部署字段，不属于公开 InitParam。

16. D3-13=A：敏感配置（Secret）只接受 SecretRef，不保存或传递明文，版本变化要求显式重新启用。

17. D3-14=A：Uni-Lab OS 在驱动创建前原子持久化内容寻址候选启用快照（Activation Snapshot），Backend 只接收副本/投影。

18. D3-15=A：候选启用解析器（Activation Resolver）只公开 prepare_activation(...) 深模块接口，CLI/UI 不自行编排内部阶段。

19. 工作流支持动作（Workflow-backed Action）在 v1 以组合工作流调用（CompositeWorkflowInvocation）静态展开到同一个工作流任务（WorkflowTask）与执行计划（ExecutionPlan）；不创建嵌套调度权威。

20. 真实物料（Material）、库存、库位占用（SiteOccupancy）、任务物料预留（TaskMaterialReservation）、作业执行占用（JobExecutionClaim）与设备遥测投影（DeviceTelemetryProjection）不归候选工作单元定义或每次启动所有。

21. D1-06=A：v1 使用失败关闭 AST allowlist，动态控制流、任意调用/I/O 与未知节点一律拒绝。

22. D1-07=A：定义使用 PackageCatalog fqid、发布 revision 与摘要，成员 id= 是稳定 member_id。

23. D1-09=A：双向创作采用单草稿 CAS、完整语义 diff、显式 rebase 和无效草稿隔离。

24. D1-10=A：v1 显式 .py 启动与 PackageCatalog 固定依赖/资产闭包，workspace、wheel 和缓存 archive 必须一致。

25. D1-11=A：Draft → Candidate → Published 分层，只有 Published 可被引用/启用，发布原子失败关闭。

26. D1-08=A：规范 JSON 采用现有字段优先的 NetworkX node-link 形态；复用当前节点/连接字段，只新增必要的 config_bindings，并冻结规范排序、精确闭包、sidecar 与运行权威字段排除。

27. D2-04=A、D2-06 已决策延期：候选工作单元定义（WorkCell Definition）拥有固定结构、物料设计约束和只读投影；库存权威（Inventory Authority）独占真实物料（Material）与库位占用（SiteOccupancy）动态事实。v1 只描述和校验物料设计预期，启用、重启和定义升级均为零真实物料/库位占用写入；command_id、request_digest、整批预置事务和持久回执推迟到 v2+。

28. D2-05=A：v1 复用 config.sites[].label/content_type/position/size，冻结成员内稳定 key、毫米几何、容量 1、允许资源模板（ResourceTemplate）解析与 Backend sort_order 投影；定义禁止携带占用者。

29. D2-07=A（已修订）：遗留位置由离线适配器（Adapter）输出规范图与迁移报告；2D 编辑器毫米坐标也迁移到物理 pose，唯一来源归一、等价重复告警、冲突失败；运行事实不进入定义。

30. D4-01～07=A：嵌套边固定 exact definition revision/digest，子成员 UUID 按根实例与 member_id 路径确定性派生；private | exported 与显式 re_export 失败关闭；候选可查看性与候选可寻址性分离；公共能力只允许收窄；Published 制品、PackageCatalog、设备注册表（Device Registry）和启用运行时权威分离；前端展开只影响视图；完整定义与公共合同使用双摘要。

31. D5-01～08 已冻结：工作流支持动作（Workflow-backed Action）只由 cell.expose_workflow_action(...) 显式导出；不引入 implementation.kind，复用 node_type="workflow" 与 x-unilabos-workflow-contract；复用既有工作流输入/输出、真实 Handle、物料占位符（ResourceSlot）、SiteSelector 和组合工作流调用（CompositeWorkflowInvocation），静态降低到唯一执行计划（ExecutionPlan）。不同调用的内部作业可以交错，不承诺整次调用数量上限或容量 N，不建立调用级持久许可，只由完整逐作业执行占用（JobExecutionClaim）保护设备、物料（Material）与源/目标库位（Site）；取消、不确定性和物理结算（PhysicalSettlement）沿既有安全合同处理。

32. G1-01/02 按 B′ 冻结：永久支持 .json/.graphml 并无损保留旧字段，但所有格式共用单一规范编译、发布、候选启用解析器（Activation Resolver）与运行权威；无法分类的非空 data 无损保存后仍阻止发布/启用。G1-03～08=A：双夹具、双摘要固定点、真实跨仓集成、故障执行与按拥有仓交付。

子票

1. [候选工作单元（WorkCell）D1] 定义身份、AST 与双向创作 #182 — 候选工作单元定义（WorkCell Definition）身份、AST、规范定义图和 Python/JSON/画布双向创作。
2. [候选工作单元（WorkCell）D2] 装配拓扑、物理位姿与物料边界 #183 — 装配拓扑（Assembly Topology）、物理位姿、库位（Site）、资源模板（ResourceTemplate）与真实物料（Material）边界。
3. [候选工作单元（WorkCell）D3] 启用参数、启动解析与敏感配置（Secret）合同 #184 — 候选工作单元初始化合同（WorkCell Init Contract）、启动参数、候选启用快照（Activation Snapshot）、Secret Provider 和 activation resolver。
4. [候选工作单元（WorkCell）D4] 嵌套组合、公开边界与设备注册表（Device Registry）投影 #185 — 嵌套组合、private/export/re-export、可查看/可寻址、设备注册表（Device Registry）与前端投影。
5. [候选工作单元（WorkCell）D5] 工作流支持动作的发布、降低与并发语义 #186 — 工作流支持动作（Workflow-backed Action）的发布、静态降低、并发、取消与物理结算（PhysicalSettlement）。
6. [候选工作单元（WorkCell）G1] 遗留启动图迁移与跨仓验收 #187 — 遗留启动 JSON/trusted-exec 迁移、SZLab fixture 与 OS/FE/SZLab/Core 跨仓验收。

GitHub native sub-issue hierarchy 是唯一分解关系；后续 repository-local delivery Issue 应挂到拥有其协议的决策子票下，不直接平铺到本地图。

Frontier

D1～D5 与 G1 的协议决策已全部收口，名义未冻结决策共 0 项。当前进入交付阶段：Uni-Lab-OS #22、uni-lab-fe #24 与 Uni-Lab-SZLab #8 已作为 #187 的 native sub-issue 建立；Core 负责跨仓黄金测试、submodule pin 和最终接受门。

依赖顺序仍为 D1 → D2 → D3 → D4 → D5 → G1；交付可以在已冻结合同边界内拆仓并行，但不得在实现中建立第二套编译、调度器（Scheduler）、库存权威（Inventory Authority）或运行权威。

跨图约束

• [Wayfinder] 领域设备包仓库架构：根单包、Workspace 自动发现与 Package Catalog #147：普通设备定义与 deployment topology 边界；候选工作单元（WorkCell）的内部装配蓝图是需要显式回链的精化。
• [功能目录] Action typed contract 与结果提交 #135：动作（Action）typed contract 与结果提交。
• [功能目录] 子工作流组合、边界 Handle 与 Task output #136：组合工作流调用（CompositeWorkflowInvocation）与父子工作流边界。
• [跨仓决策 R2] EdgeScheduler 统一 ExecutionPlan、Admission 与 DAG 生命周期 #164：唯一执行计划（ExecutionPlan）、调度器（Scheduler）权威与任务生命周期。
• [跨仓决策 C1] 冻结 Composite Workflow Invocation authoring contract #178：工作流（Workflow）投影、句柄和创作/运行身份一致性。

Blocked

当前无外部阻塞。协议已冻结，三个仓库本地交付子问题已建立；实现、跨仓测试、Core submodule pin 与回滚包尚未完成，因此 #181/#187 仍不得进入 stage:accepted。

Fog

• 候选工作单元（WorkCell）及候选可查看性/候选可寻址性术语仍待根规范词汇表（Canonical Glossary）正式收录；
• SZLab 夹具 11 个非空 data 的逐项归类是已定合同下的实现清单，不再是协议未决项。

Notes

2026-08-04 按维护者要求完成拆票。拆分前的完整设计正文与 Grill 记录保留在 Issue 编辑历史和既有评论中；后续新增细节写入对应子票，本票只更新导航和跨票状态。

Agent report

agent_report:
  stage: implementation
  reporter: Codex
  execution_mode: agent
  agent_product: Codex
  agent_name: WorkCell Wayfinder decomposition
  result: protocol-frozen-delivery-active
  human_reviewer: active

[github-actions]

GitHub → Feishu OKF synchronization

Feishu snapshot: Uni-Lab-Core #181
Knowledge stage: implementation
Issue updated: 2026-08-04T18:42:03Z

[TablewareBox]

领域语言与 v1 运行模型复核

状态：候选设计（Candidate Design）。本评论不替换正文，而是补充当前地图中最容易形成第二套领域语义的四个收口点，并给出建议的 v1 停止线。

建议先冻结的两句话

1. Python 是组合/组态创作源；规范定义与激活快照才是运行时输入。 源码、Published revision、content digest、激活参数和降低后的图均须可追踪，但运行时不得 import/exec 作者源码。
2. v1 的工作流支持动作（Workflow-backed Action）在创作层呈现为动作（Action），在任务创建前降低为同一工作流任务（WorkflowTask）中的组合工作流调用（CompositeWorkflowInvocation）/计划片段；不创建嵌套工作流任务（WorkflowTask），不复用 WorkstationBase.execute_workflow()，不产生第二个调度权威。

这两句与正文的单一执行计划（ExecutionPlan）、预建作业和单一调度器（Scheduler）目标一致，也为 #178 的第 6 个 Grill 问题提供了明确默认答案。

1. 术语必须先标为候选，暂不写入共享 Schema

根 CONTEXT.md 尚未定义 WorkCell、WorkCell Definition、WorkCell Instance、Assembly Graph、Activation Graph、Workflow-backed Action 等词；当前 Issue 正文却把它们作为英文标题与完整领域对象传播。用户原始表述又是“工站”，正文 Outcome 使用“工作站”，三者尚未完成身份、权威、生命周期、持久事实和失败语义对齐。

在人工确认前，建议讨论中统一显式标为候选，例如候选工作单元（WorkCell）、候选工作单元定义（WorkCell Definition）和候选激活图（Activation Graph）；不要把任一中文名直接提升为规范词汇（Canonical Vocabulary）。协议冻结时再按根 CONTEXT.md 格式补齐中文定义、中文 Avoid、English 与 _Avoid_。

2. 工作流支持的动作（Workflow-backed Action）不能先假装成真实设备动作

正文已正确要求统一有类型动作合同（Action typed contract），但目录投影身份仍需进一步收紧：

• public input/output 可以复用 A1/I1/C1 的动作合同（ActionContract）、工作流输入合同（WorkflowInputContract）、工作流结果记录（WorkflowResultRecord）和物料占位符（ResourceSlot）；
• implementation.kind = workflow 必须保持可辨识，不能在 PackageCatalog/Registry 中丢成普通 direct device Action；
• 父工作流（Workflow）里的节点身份，v1 建议是组合工作流调用（CompositeWorkflowInvocation）的动作形态投影；Task commit 前静态展开或合入候选计划片段；
• 展示层折叠可以 opaque，但执行计划（ExecutionPlan）必须保留内部作业、执行要求、占用意图（ClaimIntent）、源码映射和物理结算（PhysicalSettlement）证据；
• 当前动作重试策略（ActionRetryPolicy）仍为 never。整站/整单元失败不能因为外层看起来是一个动作（Action）就自动创建执行重试（ExecutionRetry）。

不建议把 WorkstationBase.execute_workflow(...)->bool 包成 @action：布尔“启动成功”既不是工作流任务业务终态（WorkflowTask Business Terminal State），也不是物理结算（PhysicalSettlement）；进程重启后还会丢失 WorkflowStatus。

3. 候选计划片段不能成为第二种运行时计划

正文的 Candidate Plan / Frozen Plan 方向可行，但名称和生命周期必须固定：

• Task commit 前：工作单元/生成器只产生候选计划片段，允许验证、拒绝、canonicalize 和计算 digest；
• Task commit 时：候选片段被唯一 ExecutionPlan Builder 合入规范执行计划（ExecutionPlan）并预建工作流节点作业尝试（WorkflowNodeJobAttempt）；
• Task commit 后：只有执行计划（ExecutionPlan）是调度器（Scheduler）的静态输入。不得再保留一个可独立补事实、改图或解释失败的 Frozen Plan 权威。

同理，候选激活快照（Activation Snapshot）只描述 definition closure、实例 namespace、初始化参数和降低后的部署图；它不是第二份工作流快照或执行计划（ExecutionPlan）。

4. 旧启动 JSON 的 data 必须分流，不能整包迁入 Python/Activation Snapshot

当前实现证据：

• Uni-Lab-OS/Uni-Lab-OS@735318ad92ad7fb5742a4d0ecee26bec11505148:unilabos/app/main.py：--graph、startup_json_path 或远端 startup JSON 进入同一加载路径；
• Uni-Lab-OS/Uni-Lab-OS@735318ad92ad7fb5742a4d0ecee26bec11505148:unilabos/resources/graphio.py：节点/连接降低为资源树集合（ResourceTreeSet）和 NetworkX 图；
• Uni-Lab-OS/Uni-Lab-OS@735318ad92ad7fb5742a4d0ecee26bec11505148:unilabos/registry/decorators.py 与 unilabos/registry/ast_registry_scanner.py：已有 @device / @resource / @action 的纯 AST 先例；
• Uni-Lab-OS/Uni-Lab-OS@735318ad92ad7fb5742a4d0ecee26bec11505148:unilabos/devices/workstation/workstation_base.py：遗留整站工作流状态仍是内存事实，不能成为新权威。

旧 JSON 把类型/实例、parent/children、连接、画布位置、初始化 config 和运行 data 混在一起。迁移时至少拆成：

1. 候选工作单元定义（WorkCell Definition）：可复用成员、Containment、库位（Site）绑定、端口/连接、公共合同和资产；
2. 候选激活图/快照（Activation Graph/Snapshot）：实例身份、部署参数、外部连接、secret reference 与允许 override；
3. 测试 seed / 一次性 bootstrap：仅在显式环境和幂等策略下使用；
4. 运行时权威：物料（Material）、库存权威（Inventory Authority）、库位占用（SiteOccupancy）、设备遥测投影（DeviceTelemetryProjection）、任务物料预留（TaskMaterialReservation）和作业执行占用（JobExecutionClaim）继续留在各自持久事实源。

尤其不能在每次重启时用 Python 中的“烧杯现在位于某处”覆盖库存权威（Inventory Authority）的最新库位占用（SiteOccupancy）。

5. 还需加入的并发/失败压测

1. 稳定身份：把源码变量 pump 重命名为 solvent_pump，不得静默创建新的 runtime device/Site identity；必须由稳定 definition identity + member alias/显式迁移决定。
2. 部分物理成功：内部取料成功、放料前断电，外层不能只得到 failed 后重发整站动作；相关物料、工具、来源/目标库位（Site）、作业执行占用（JobExecutionClaim）与栅栏必须保持不确定并进入对账恢复（Reconciliation）。
3. 并发调用：两个工作流任务（WorkflowTask）同时调用同一候选工作单元（WorkCell），必须明确允许内部节点交错、整次调用串行，还是容量 N。若要求整次调用独占，不能把任务生命周期权利伪装成单次作业执行占用（JobExecutionClaim）；需要单独的持久协议决策。
4. 依赖升级：内层 definition 发布新 revision，不得改变已发布外层 definition 或已创建工作流任务（WorkflowTask）；必须显式 re-link、preview、validate、publish。
5. 折叠不删证据：前端可折叠候选工作单元调用，但展开后必须能定位真实工作流节点作业尝试（WorkflowNodeJobAttempt）、参数、回执（Receipt）、占用和源码位置。

建议调整 Frontier 顺序

1. P0：人工对齐 WorkCell 的规范中文名和对象边界；
2. P1：冻结 AST vocabulary、canonical definition、identity/digest/source map；
3. P2：关闭 [跨仓决策 C1] 冻结 Composite Workflow Invocation authoring contract #178 投影问题，接受 v1 “动作形态 + 单任务静态降低”；
4. P3：冻结 Activation Snapshot 与旧 JSON config/data 分流；
5. P4：单独 Grill 并发容量、整次调用独占、Planning Snapshot 与任务物料准入（TaskMaterialAdmission）时序；
6. P5：再创建 OS/FE/SZLab delivery children 和 Core acceptance gate。

建议加入 Acceptance gates

• 工作流支持动作（Workflow-backed Action）在目录和计划中保留 implementation kind 与 source digest，不冒充 direct device Action；
• Task commit 后只有一个执行计划（ExecutionPlan），不存在可独立推进/补事实的 Frozen Plan；
• 旧 JSON data 完成分类清单，运行时物料/库位/遥测/预留/占用事实不会被 WorkCell source 或 Activation Snapshot 覆盖；
• 断电、部分物理成功、并发调用和内层 revision 升级均通过失败关闭测试；
• 协议冻结前所有尚未对齐的 WorkCell 领域词都显式标记为候选，未写入共享 Schema/Glossary。

[TablewareBox]

分期计划与 Grill 01：先冻结定义身份

状态：候选计划（Candidate Plan）。目标合理；本轮只建立决策顺序并开始逐题 Grill，不启动实现，不创建交付子票。每道题确认后再进入下一道，直到形成共享理解。

为什么值得做

现有代码已经具备三块可复用基础：纯 AST 的设备/资源/动作注册扫描、启动 JSON 到资源树集合（ResourceTreeSet）的归一化，以及组合工作流调用（CompositeWorkflowInvocation）的静态展开方向。因此，Python 友好的组合/组态创作并不要求重写调度器（Scheduler）。

收益也足够明确：

1. 人和 AI 可以围绕有类型、可补全、可重构的 Python 创作，而不是编辑大型位置敏感 JSON；
2. 同一候选工作单元（WorkCell）可复用设备搭建、内部工作流（Workflow）、公共初始化合同和对外动作（Action）；
3. 发布产物仍是确定、可验证、可签名的规范定义，运行时不 import/exec 作者源码；
4. 上层可以调用整单元能力，同时底层仍保留唯一工作流任务（WorkflowTask）、执行计划（ExecutionPlan）和物理结算（PhysicalSettlement）证据。

成立条件是：不得把 Python 源码变成运行时权威，不得把候选工作单元（WorkCell）变成第二套物料（Material）/库存/调度模型，也不得把遗留 execute_workflow() 包装成伪动作（Action）。

分期计划

第 0 期：协议 Grill 与 v1 停止线

逐题冻结：

• 候选工作单元（WorkCell）的定义身份、实例身份及规范中文名；
• 候选装配拓扑（Assembly Topology）与候选激活拓扑（Activation Topology）的边界；
• 成员公开、可查看与可寻址三种权限；
• 初始化参数、敏感配置和旧 JSON config/data 的权威分流；
• 工作流支持动作（Workflow-backed Action）的身份投影与并发语义；
• v1 明确不做的动态能力。

退出门：每项决策都有身份、权威、生命周期、持久事实和失败语义；#181 正文与关联决策无冲突。

第 1 期：静态 Python 编译最小闭环

交付受限 Python AST → 规范候选工作单元定义（WorkCell Definition）的纯编译链：

• 闭合 AST vocabulary；
• 稳定 definition/member identity；
• canonical codec、revision、digest 和 source map；
• workspace 与 clean wheel 结果一致；
• 禁止 import/exec、I/O 和硬件副作用；
• 旧 JSON 只通过显式遗留适配器（Legacy Adapter）转换，不成为新创作接口。

退出门：相同输入得到字节级稳定产物；非法引用、环和动态 Python 全部失败关闭。

第 2 期：激活与启动替换

把已发布定义与部署参数降低为候选激活快照（Activation Snapshot）：

• file: 草稿与 pinned catalog: 定义走同一个 resolver；
• 公共初始化合同与内部设备初始化合同类型校验；
• direct binding/fan-out 的约束交集；
• secret reference、脱敏与失败前置；
• 在任何 driver import、硬件连接和物料 bootstrap 前完成验证；
• --graph、--workcell、OS --config 语义互斥且冲突失败关闭。

退出门：选定仿真工站可由 Python 冷启动；重启可比较定义 digest、激活 digest 与实例 identity。

第 3 期：注册表与前端投影

将已激活的候选工作单元（WorkCell）投影为复合设备，同时保留原始定义类型：

• 已发布定义进入包目录（Package Catalog）；
• 已激活实例进入设备注册表（Device Registry）；
• private/exported/re-exported 成员边界；
• 可查看性（Inspectability）与可寻址性（Addressability）分离；
• 前端只消费规范 DTO，不解析 Python，不计算 UUID/closure；
• 支持折叠展示与授权后的内部诊断。

退出门：未公开成员无法被外层创作引用；维护者仍可审计真实内部拓扑和状态。

第 4 期：工作流支持动作（Workflow-backed Action）

只允许显式发布、作用域闭合的内部工作流（Workflow）成为对外动作（Action）：

• 输入复用工作流输入合同（WorkflowInputContract）；
• 输出复用工作流结果记录（WorkflowResultRecord）；
• 物料边界复用物料占位符（ResourceSlot）；
• 目录保留 implementation.kind = workflow；
• 任务创建前降低为同一组合工作流调用（CompositeWorkflowInvocation）和唯一执行计划（ExecutionPlan）；
• 内部工作流节点作业尝试（WorkflowNodeJobAttempt）、占用意图（ClaimIntent）、回执（Receipt）与源码映射可审计；
• 动作重试策略（ActionRetryPolicy）继续为 never。

退出门：不创建嵌套工作流任务（WorkflowTask），不产生第二调度权威；断电与部分物理成功不会触发盲目物理重放（Blind Physical Replay）。

第 5 期：条件计划生成器

这一期默认推迟，只有静态工作流无法表达一个已验证真实需求时才开启：

• 生成器只在任务提交前产生候选计划片段；
• 输入必须来自冻结任务输入和版本化规划快照；
• 输出经校验、canonicalize、hash 后由唯一 Builder 合入执行计划（ExecutionPlan）；
• 任务提交后禁止改图；
• 超时、超预算、副作用、状态漂移全部失败关闭。

退出门：系统仍只有一种运行时执行计划（ExecutionPlan）和一个调度器（Scheduler）权威。

第 6 期：迁移与跨仓验收

建议采用双夹具：

1. 一个最小仿真候选工作单元（WorkCell），覆盖嵌套、初始化、公开边界和动作发布；
2. 一个真实 SZLab/光刻胶工站，验证 JSON → Python 等价迁移与真实设备链路。

验收覆盖节点/连接/库位（Site）身份、冷启动、重启、目录漂移、并发调用、取消、部分物理成功、内部 revision 升级、前端折叠/展开和 Feishu 知识同步。通过后才依次推进 stage:implementation、stage:testing、stage:accepted。

推荐的总体切法

v1 停在第 4 期：先完成静态定义、激活、注册和工作流支持动作（Workflow-backed Action）。第 5 期计划生成器不应成为首版门槛，它会把规划快照、任务物料准入（TaskMaterialAdmission）与并发安全同时引入，风险明显更高。

---

Grill 01：候选工作单元（WorkCell）发布后是否拥有独立、可引用的定义身份？

这是后续所有 revision、嵌套依赖、公开边界与 digest 的根决策。

A. 独立的一等定义身份（推荐）

候选工作单元定义（WorkCell Definition）拥有稳定 UUID、revision、digest 和 public contract；可以嵌套引用。激活后再产生独立实例身份，并向设备注册表（Device Registry）投影为复合设备。它不是普通设备定义，也不是物料（Material）。

推荐原因：只有此方案能稳定表达嵌套依赖、版本固定、公开/私有成员、升级预览和前端折叠，同时不把可复用定义与真实运行实例混为一体。

B. 仅作为 Python 语法糖

编译后完全展开成设备/资源图，不保留候选工作单元（WorkCell）的定义身份。

代价：实现最简单，但 revision、依赖升级、公共合同、嵌套复用和诊断边界都会丢失，只适合一次性启动脚本。

C. 直接作为特殊设备定义

候选工作单元（WorkCell）就是一种特殊 Device Definition，复用相同身份和生命周期。

代价：目录统一，但很容易把“可复用组合定义”“激活实例”和“在线设备”折叠成一个对象；后续 public init、nested revision 与局部激活会持续泄漏特殊规则。

我的建议：选择 A。

请先确认 A / B / C，或指出你希望的第四种身份模型。本题确认前不进入 Grill 02，也不启动实现。

[TablewareBox]

Grill 01 决策记录与 Grill 02：定义/激活边界

Grill 01 已确认

维护者选择 A：候选工作单元（WorkCell）拥有独立的一等定义身份。

本轮确认的直接约束：

• 候选工作单元定义（WorkCell Definition）拥有独立稳定身份、revision、digest、公共合同和嵌套依赖；
• 候选工作单元实例（WorkCell Instance）在激活时产生独立实例身份，并可向设备注册表（Device Registry）投影为复合设备；
• 候选工作单元定义（WorkCell Definition）不是普通设备定义，也不是编译后消失的 Python 语法糖；
• 定义 revision 更新不得静默改变既有激活实例或已创建工作流任务（WorkflowTask）；
• 具体规范中文名、UUID 派生算法、目录 closed-union wire 形态尚未确认，继续保留候选标记。

该决定已在协议 Grill 中确认，但 #181 仍处于 stage:protocol-definition；在完整决策链和规范词汇条目冻结前，不描述为已实施能力。

---

Grill 02：候选工作单元定义与激活之间允许多大结构变化？

A. 定义声明允许的完整结构，激活只做受限选择与绑定（推荐）

候选工作单元定义（WorkCell Definition）拥有最大允许成员集合、containment、端口/连接、公开边界和显式可选性。候选激活（Activation）可以：

• 为实例和成员绑定部署身份；
• 填充已声明的初始化参数与 secret reference；
• 选择定义中显式声明为 optional/variant 的成员；
• 绑定已声明的外部端口和 Edge/host placement。

但候选激活（Activation）不能发明新成员、新动作（Action）、新端口或未在定义中允许的内部连接；必需成员不得省略。只有两端均被激活且定义已声明的连接才可进入候选激活快照（Activation Snapshot）。

优点：同一 revision 的公共合同与安全边界稳定，同时允许同一设备组合在不同实验室做受控部署裁剪。

B. 定义是完全固定图，激活只能填参数

任何成员和连接都不可选择；每次激活必须实例化完整定义。

优点：最简单、digest 最直观。代价是测试/生产、不同站点和可选模块需要复制定义，容易产生近似版本分叉。

C. 激活可以任意增删成员和重连

定义只提供基础模板，激活文件可自由 patch 拓扑。

优点：最灵活。代价是公共合同、digest、静态验证、权限边界和升级兼容都失去稳定含义，实际上重新制造另一种启动 JSON。

我的建议：选择 A，并把 v1 的变化能力限制为显式 optional/variant + 参数/secret/placement 绑定；不支持任意拓扑 patch。

请确认 A / B / C，或提出第四种边界。本题确认前不进入 Grill 03。

[TablewareBox]

Grill 02 已确认：v1 固定结构，定义文件直接作为启动输入

维护者已确认以下协议方向；状态为已接受决策（Accepted Decision），不代表当前实现（Current Implementation）已经交付。

1. v1 保留既有 @workcell 工厂语法：函数签名声明候选工作单元初始化合同（WorkCell Init Contract），函数体声明固定内部结构、稳定成员 id、父子包含和内部初始化绑定。
2. 候选工作单元（WorkCell）Python 定义文件本身直接作为 --workcell file:... 启动输入；不再增加顶层 startup = activate(...) 第二套作者接口。
3. 启动参数来自 --workcell-params 或持久化部署记录，并且只能绑定函数签名公开的 InitParam；敏感值使用 Secret/secret reference。启动器完成校验后自动冻结候选启用快照（Activation Snapshot）。
4. 候选工作单元定义（WorkCell Definition）身份与运行实例身份继续分离；同处一个文件不等于共享身份或生命周期。
5. v1 不提供候选结构选择（StructuralChoice），也不允许普通 Python if、循环、动态工厂或初始化参数改变成员 class、alias、父子关系、库位（Site）、导出或动作（Action）合同。
6. 为后续兼容保留：规范中间表示必须带 schema_version，固定成员具有稳定 member_id 与可判别的 kind: fixed。未来若确有需求，以显式 member_choice(...) / absent() AST 节点和新的版本化 IR 分支增量加入，不重新解释既有 InitParam，也不使旧 v1 源码失效。
7. 修改固定结构仍产生新的不可变定义 revision/digest；只修改部署参数产生新的候选启用快照（Activation Snapshot），不得原地改写既有定义或运行实例。

因此，先前 Grill 02 中“v1 要求显式 optional/variant”的建议被本决策收窄取代：v1 只有固定结构；候选结构选择（StructuralChoice）是保留扩展方向，不是首版能力。

[TablewareBox]

Grill 03：Python 创作源与 JSON 中间表示，谁拥有可写权威？

对“JSON 与 Python 哪个更适合 AI”的收敛

格式本身不是决定因素。对本功能应拆开三个生命周期：

1. 创作期：受限 Python AST 对人和 AI 更有杠杆率。它提供 import/symbol、类型注解、稳定局部名称、复用、代码差异和编译诊断；AI 可以通过 check -> 精确诊断 -> 修改 闭环工作。
2. 发布期：规范 JSON/对象中间表示更适合 Schema 校验、稳定排序、引用闭包、内容摘要、签名、缓存、跨语言消费和前端投影。
3. 运行期：运行时消费不可变的已发布候选工作单元定义（WorkCell Definition）与候选启用快照（Activation Snapshot），既不执行作者 Python，也不读取可变创作草稿。

因此不能笼统宣布“JSON 是唯一事实源”。更准确的权威分配是：

可写 Python 创作源
  -> AST 编译 / link / validate
  -> 规范 JSON 定义（不可变发布事实）
  -> 启用参数绑定
  -> 候选启用快照（Activation Snapshot，运行事实）

同一个阶段只能有一个可写权威。若 Python 与 JSON 都允许独立编辑并要求自动双向同步，注释、变量命名、导入、源码位置、稳定成员身份和格式都会产生不可判定冲突。

对嵌套组合的纠正

JSON 当然可以表达引用和嵌套，但“能表示”不决定运行语义：

• 候选工作单元（WorkCell）嵌套应保存带精确 revision/digest 的定义引用、稳定成员 alias、公开端口和显式导出；不默认复制无限内联树。
• 父工作流调用子工作流在创作 JSON 中可以表现为 subworkflow 引用节点，但 v1 仍按已接受的组合工作流调用（CompositeWorkflowInvocation）合同，在任务创建前静态展开进同一个工作流任务（WorkflowTask）与执行计划（ExecutionPlan）。
• “为子工作流创建独立运行实例，单独暂停、重试、取消”不是 JSON 自带能力，而是一整套新的父子身份、调度权威、投递重放（DeliveryReplay）、执行重试（ExecutionRetry）、占用和物理结算（PhysicalSettlement）协议；不能在本功能中顺手引入。

推荐的 v1 决策

对新候选工作单元（WorkCell）定义：

• Python AST 源是唯一可写的语义创作权威；
• 规范 JSON 中间表示是编译产物、发布产物和跨语言接口，不允许手工原地修改；
• 遗留启动 JSON 只经兼容适配器（Adapter）导入同一中间表示，不建立第二套新创作权威；
• AI 默认修改 Python，随后调用统一 compiler/check 接口获得精确 source-mapped diagnostics；
• v1 可视化界面先负责渲染、检查和预览。若要编辑，必须通过有类型编辑命令回写 Python 源并重新编译；直接保存 JSON 后再尝试反向猜回原 Python 不进入 v1。

本轮唯一问题：是否确认上述单向可写权威，尤其接受 v1 不承诺 JSON 与 Python 的无损双向编辑？

[TablewareBox]

Grill 03 修订候选：允许受控双向创作；补入物理位姿

状态：候选设计（Candidate Design），用于取代上一条“v1 单向可写权威”的推荐；等待维护者确认。

当前实现核验

工作流创作（Workflow Authoring）已经具备可复用的受控双向骨架，但尚不是任意 Python/原始 JSON 同时可写：

• uni-lab-fe 的 FE-D117 合同规定：一个工作流（Workflow）会话同一时刻只有一种可写表示；
• 代码模式由 Python 草稿可写，候选有向无环图（DAG）只读；
• 画布模式由画布缓冲可写，OS 生成的 Python 投影只读；
• 画布保存先生成完整规范 Python、展示完整 diff，确认后再写入草稿；
• 当前代码模式的 JSON 是只读候选图投影；并未交付任意 JSON 文本与 Python 文本的并发双写；
• 已有真实 OS/SQLite/compiler/SSE E2E 证明候选图经 generate-python 可以稳定往返，但当前持久画布操作仍是有限集合，位置拖动没有被伪装为持久语义编辑。

证据：uni-lab-fe integration/fe-os-migration@58f5165 的 docs/migration/workflow/fe-d117-single-edit-authority.md 与趋势报告，以及本地交付卡 LOCAL-77。

因此，复用会话隔离、CAS、compiler/generator、完整 diff、结构化诊断和发布门禁后，候选工作单元（WorkCell）的双向创作不是架构级难题；新增成本主要在候选工作单元（WorkCell）专用 AST vocabulary、逆向代码生成、稳定成员身份、source map 和物理位姿编辑。v1 固定结构使范围可控，但它不是一个前端开关。

修订推荐：一个草稿，多种互斥可写视图

同一个候选工作单元定义草稿（WorkCell Definition Draft）允许 Python 与规范 JSON/结构化画布双向创作，但每个草稿同一时刻只允许一种写入模式：

Python 写模式
  -> compile / link / validate
  -> 候选定义图（Candidate Definition Graph）

规范 JSON / 结构化画布写模式
  -> schema / semantic validate
  -> generate normalized Python
  -> 完整 diff + 接受
  -> 重新 compile
  -> 候选定义图固定点校验

冻结约束：

1. 这是语义往返，不承诺源码字节无损；从 JSON/画布生成 Python 时，注释、空行、局部变量风格和 import 排列可以规范化。
2. Python 与 JSON 不是两个可独立发布的权威；切换写模式必须先处理 dirty 状态，禁止自动增量合并与 force overwrite。
3. 发布前必须满足固定点：graph -> Python -> graph 的规范 digest 相同；否则失败关闭。
4. 稳定 member_id、引用、公共合同、嵌套 definition revision/digest 和 source map 不能靠变量名或数组顺序猜测。
5. AI 可选择修改 Python，或提交有类型的图编辑/JSON Patch；两条路径都必须经过同一个 compiler/generator/validator 深模块（Deep Module）。
6. 无效草稿可以保留和诊断，但不能发布、激活或替换最后一个有效 revision。
7. 原始 JSON 文本若开放编辑，也只是当前写模式的规范草稿视图；它不能绕过 Schema、语义校验、代码生成 diff 与 CAS。

这既给 AI 足够空间，也保持一个清楚的写入权威和可审计转换链。建议 v1 接受。

新增范围：物理位置与旋转必须进入定义

维护者指出此前 Python 示例漏掉了位置与旋转。核验现状后，此项应成为 v1 必备，而不是仅用于 UI 的可选装饰：

• 遗留启动 JSON 同时存在根级 position 和 pose.position / position3d / rotation，且部分 position 实际承担旧画布布局；新 IR 不应复制这种歧义。
• uni-lab-fe 当前物理场景已有 LabPose：位置使用毫米、旋转使用 XYZ 欧拉角度数，并支持父子位姿组合。候选工作单元（WorkCell）应复用同一空间合同，不再发明另一组单位和坐标系。
• 物理位姿与编辑器像素布局必须分字段：候选局部位姿（LocalPose）属于装配拓扑（Assembly Topology）；ui_layout 只属于展示投影，不能驱动物理执行。
• 内部成员位姿相对候选工作单元（WorkCell）根坐标系，归候选工作单元定义（WorkCell Definition）所有；候选工作单元实例（WorkCell Instance）在实验室中的根世界位姿归候选启用图（Activation Graph）所有。嵌套时按父子变换递归组合。
• 直接用定义文件启动且未提供部署根位姿时，根位姿可规范化为 identity；这不把绝对实验室坐标写回可复用定义。

候选 Python 形态：

from unilabos.workcell import Pose

cell.assign_child_resource(
    plc_1,
    local_pose=Pose(
        position_mm=(0.0, 0.0, 0.0),
        rotation_deg_xyz=(0.0, 0.0, 0.0),
    ),
)
cell.assign_child_resource(
    robot,
    local_pose=Pose(
        position_mm=(1200.0, 350.0, 0.0),
        rotation_deg_xyz=(0.0, 0.0, 90.0),
    ),
)

把 local_pose 放在组合关系上，而不是塞进设备工厂初始化参数：同一种设备可在不同候选工作单元（WorkCell）中有不同摆放，设备初始化合同不必理解父坐标系。

位姿的精确 owner、根位姿输入、旋转约定、是否允许实例级 override 作为 Grill 04 逐项冻结；本轮只确认双向创作模型。

本轮唯一确认项

是否确认：v1 允许上述“单草稿、单时刻单写模式”的 Python ↔ 规范 JSON/结构化画布双向语义创作，而不承诺两份文本同时可写或源码字节无损？推荐确认。

[TablewareBox]

Grill 03 已确认；Grill 04：物理设计与启动组态如何分工

Grill 03 已确认

维护者确认 v1 采用“一个草稿、同一时刻一种可写模式”的双向创作：

• Python 与规范 JSON/结构化画布可以双向语义往返；
• 不允许两份文本同时成为独立可写权威；
• 不承诺注释、格式和局部变量命名的字节级无损；
• 发布前必须通过 graph -> Python -> graph 规范 digest 固定点；
• AI 可以选择 Python patch 或有类型的图编辑/JSON Patch，但都经过同一 compiler/generator/validator 深模块（Deep Module）。

该项现为已接受决策（Accepted Decision），不代表候选工作单元（WorkCell）双向创作当前已经实现。

---

Grill 04：一个项目、两个制品，而不是一个混合文件

维护者把需求分成：

1. 确定设备以及物料相关资源的数量、选型、包含关系和位置摆放；
2. 确定真实设备如何启动，包括 endpoint、端口、机号、连接开关、超时和 secret。

推荐把它们放在同一个候选工作单元（WorkCell）创作项目中，但分成两个生命周期与两种最适表示。

制品 A：候选工作单元定义（WorkCell Definition），用 Python/规范图双向创作

workcell.py 拥有：

• 固定成员类型与数量；
• 稳定 member_id / alias；
• 父子包含、库位（Site）绑定和内部连接；
• 成员相对候选局部位姿（LocalPose）；
• 公共动作（Action）与内部工作流（Workflow）暴露；
• 公开候选工作单元初始化合同（WorkCell Init Contract）；
• public InitParam 到内部设备初始化字段的绑定；
• 可以安全固化且不随部署改变的私有配置，例如随包版本化的地址表资产路径。

它不拥有某实验室的 IP、串口、明文密码、真实设备实例 UUID、根世界位姿或当前物料（Material）状态。

候选目录：

szlab_poly_station/
├── workcell.py
├── activations/
│   ├── simulator.params.json
│   └── szlab-prod.params.json
└── assets/
    └── szlab_plc_0730.csv

workcell.py 仍是已确认的直接启动输入，并声明启动值的类型合同：

@workcell(
    id="szlab_poly_station",
    display_name="SZLab 聚合物工作站",
    version="1.0.0",
)
def szlab_poly_station(
    *,
    plc_url: Annotated[str, InitParam(pattern=r"^opc\.tcp://")],
    plc_password: Annotated[Secret[str], InitParam()],
    auto_connect: Annotated[bool, InitParam()] = True,
    pump_timeout_s: Annotated[
        float,
        InitParam(ge=0.1, le=30.0, unit="s"),
    ] = 5.0,
) -> WorkCell:
    cell = WorkCell()

    plc_1 = plc(
        id="plc",
        url=plc_url,
        password=plc_password,
        auto_connect=auto_connect,
        csv_path="assets/szlab_plc_0730.csv",
    )
    robot = mixer_robot(
        id="robot",
        plc_device=plc_1,
        auto_connect=auto_connect,
    )

    cell.assign_child_resource(
        plc_1,
        local_pose=Pose(
            position_mm=(0.0, 0.0, 0.0),
            rotation_deg_xyz=(0.0, 0.0, 0.0),
        ),
    )
    cell.assign_child_resource(
        robot,
        local_pose=Pose(
            position_mm=(1200.0, 350.0, 0.0),
            rotation_deg_xyz=(0.0, 0.0, 90.0),
        ),
    )
    return cell

制品 B：候选启用参数文档（Activation Parameter Document，候选术语），用小型强类型 JSON/表单创作

每个真实部署或仿真环境只提供定义公开的值：

{
  "plc_url": "opc.tcp://10.0.0.12:4840",
  "plc_password": {
    "secret_ref": "secret://szlab/poly-plc"
  },
  "auto_connect": true,
  "pump_timeout_s": 5.0
}

这里使用 JSON 的原因不是让人重新维护大图，而是它已经变成小型、平坦、Schema 可校验的数据：

• AI 不需要理解 Python 执行语义就能生成和修改；
• 前端可以直接由候选工作单元初始化合同（WorkCell Init Contract）生成表单；
• secret 只能是引用，不能进入 Python、JSON plaintext、日志或候选启用快照（Activation Snapshot）；
• 同一个候选工作单元定义（WorkCell Definition）可以绑定 simulator、SZLab production 等多个参数集，而不复制结构；
• 修改参数生成新的候选启用快照（Activation Snapshot），但不生成新的定义 revision。

本地启动仍保持一条入口：

unilabos ...   --workcell file:./workcell.py   --workcell-params ./activations/szlab-prod.params.json

若所有公开参数都有安全默认值，开发/仿真可以只给 --workcell file:./workcell.py。正式部署可以不用文件，改由持久候选启用图（Activation Graph）提供同一份参数对象。两条入口必须经过同一个 activation resolver。

为什么不建议全部放进一个 Python 文件

如果把真实 endpoint、serial、secret 和结构都写入 workcell.py：

• 同一结构的仿真/生产会复制或引入 v1 已禁止的动态 if；
• 修改 IP 会改变定义 digest，错误地表现为“物理设计升级”；
• 包无法安全共享；
• secret 容易进入 Git 和 AI 上下文；
• 部署回滚与定义回滚被绑成一个动作；
• AI 无法判断某个 diff 是改了产品设计还是只改了现场参数。

如果把两个制品做成完全独立、彼此不引用的文件，又会发生参数名漂移。正确的 seam 是：定义函数签名生成 closed JSON Schema；候选启用参数文档只能按该 Schema 填值，联合校验并冻结一次候选启用快照（Activation Snapshot）。

物料边界必须额外划清

“物料数量、选型、位置摆放”包含两种不同事实：

• 固定资源结构、资源模板（ResourceTemplate）引用、允许的库位（Site）和相对摆放，可以进入候选工作单元定义（WorkCell Definition）；
• 已存在的真实物料（Material）UUID、条码、当前数量和库位占用（SiteOccupancy）属于库存权威（Inventory Authority），不能由 workcell.py 或每次启动参数覆盖。

若工站安装时确实需要“首次自动创建 12 个瓶子并放到指定库位”，它应是显式的一次性 bootstrap/provision 操作，成功后留下持久回执；重启不得再次执行。这个细节后续单独 Grill。

三种选择

A. 一个 Python 文件同时写结构和现场启动值：文件最少，但混合 revision、secret 与部署生命周期，不推荐。

B. 一个候选工作单元（WorkCell）项目，workcell.py 写结构与参数合同，小型 JSON/持久记录填写启动值：推荐。

C. 两套完全独立定义：AI 各写各的，但容易漂移，必须维护重复 Schema，不推荐。

本轮唯一问题：是否确认选择 B——一个项目、两个制品，且候选工作单元（WorkCell）Python 定义文件继续作为启动入口？