[候选工作单元（WorkCell）D3] 启用参数、启动解析与敏感配置（Secret）合同

[TablewareBox]

独立设计文档（审阅中）：候选工作单元（WorkCell）组合定义、启动与分层动作设计
变更审阅：PR #188

父地图：#181

Outcome

冻结候选工作单元定义（WorkCell Definition）如何绑定一个真实或仿真部署的启动值，并在任何驱动 import、设备连接或物料 bootstrap 前生成确定、脱敏的候选启用快照（Activation Snapshot）。

已接受决策（Accepted Decisions）

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

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

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

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

• D3-06=A：-g/--graph 严格按 .py、.json、.graphml 后缀分派；未知或无后缀失败，不做内容探测；.py 只进行受限 AST 编译，不 import/exec 作者源码。

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

• D3-08=A：任意已登记设备作者句柄只消费已发布目录的 init_param_schema.config；现代 @device 由带类型的 __init__ 静态生成并在发布时冻结，作者句柄不另建合同；遗留 YAML 只作为遗留设备生成同一字段的兼容来源。

• D3-09=A：公开 InitParam 使用封闭类型闭集；fan-out 必须满足全部目标 Schema 的安全交集，不做字符串、数字或单位隐式转换。

• D3-10=A：唯一外部输入规范化为封闭候选启用请求（Activation Request），顶层只有 schema_version、必需 definition_digest、instance 和 params；零外部输入时整个对象缺席。

• D3-11=A：v1 不实现 catalog: 启动引用；生产从 workspace/package 内显式文件启动并固定源码/目录 digest；未来目录引用只允许 exact revision/digest，禁止 latest。

• D3-12=A：稳定实例身份、根世界位姿、外部连接和 Edge/机器放置属于 instance 部署字段，不属于公开 InitParam；改变 instance_id 创建新实例，改变其他部署字段为同一实例创建新快照。

• D3-13=A：敏感配置（Secret）只接受封闭 SecretRef {provider, key, version?}；Provider 是候选启用解析器（Activation Resolver）的内部 Adapter；v1 不热轮换。

• D3-14=A：Uni-Lab OS 在驱动创建前原子持久化不可变、内容寻址的候选启用快照（Activation Snapshot）；Backend 只接收副本/投影；重启只复用完全相同 digest。

• D3-15=A：候选启用解析器（Activation Resolver）只公开 prepare_activation(request) -> PreparedActivation | ActivationDiagnostics 深模块接口；全部副作用前诊断使用稳定 code/path/source_span/message/hint。

• @workcell 函数签名是候选工作单元初始化合同（WorkCell Init Contract）的作者入口。

• 只有公开 InitParam 可以由 CLI 或持久候选启用图（Activation Graph）提供；私有设备配置不能穿透覆盖。

• v1 允许 direct binding/fan-out，不允许启动参数改变固定结构。

• Python 定义文件通过现有 -g/--graph 直接作为启动输入；不新增 --workcell；每个文件恰好一个顶层 @workcell 根定义。

• 参数输入是可选的覆盖层，不是每个项目必须提交的第二个文件：

  • 没有公开 InitParam 时，只需 Python 定义；
  • 所有公开 InitParam 都有默认值且本次不覆盖时，也只需 Python 定义；
  • Phase 0 遇到无默认值、现场覆盖或敏感配置（Secret）引用时明确拒绝启用；完整 v1 后续按 D3-03 接受单一外部覆盖对象。

• 固定、非敏感且对该定义所有启用一致的站内设备值可以写在 Python 定义中；会随物理安装变化或需要外部选择的值必须显式提升为公开 InitParam。

• 敏感值只以 secret reference 流转，不进入定义、目录、日志、诊断或候选启用快照（Activation Snapshot）明文。

• 无论是否存在参数输入，activation resolver 都必须冻结候选启用快照（Activation Snapshot）；运行时审计与重启比较不能退化为“直接运行 Python 后不留解析事实”。

已接受制品模型

一个候选工作单元（WorkCell）项目具有：

1. 一个必需的作者制品：workcell.py，拥有固定结构、相对位姿、私有固定配置和候选工作单元初始化合同（WorkCell Init Contract）；
2. 一个按需存在的启用参数输入：小型强类型 JSON、表单提交或持久部署记录，只保存公开参数覆盖和敏感配置（Secret）引用；空覆盖不得强制生成文件；
3. 一个每次启用都生成的系统制品：候选启用快照（Activation Snapshot），保存已解析参数、来源、定义/目录指纹和稳定身份，但不保存敏感值明文。

因此，“两个制品”不是“每个项目必须有 Python + JSON 两个文件”，而是定义与启用参数具有不同权威；在零外部参数或全默认场景中，作者只维护 Python 文件。

协议冻结状态

D3-01～D3-15 已全部由维护者确认。当前剩余设计决策为 0 项；本票继续保持打开和 stage:protocol-definition，等待 #182/#183 前置合同对齐、正式 Schema/实现子票与跨仓验收，不把“Grill 完成”误作功能已实现。

Acceptance gates

• 零公开参数和全默认参数场景均可只用 workcell.py 启动，不要求空 params 文件；
• Phase 0 通过 -g/--graph 启动 Python 定义；任何外部参数输入明确失败但仍生成默认值快照；
• 一次启用最多接受一个外部覆盖对象；多个来源同时出现时在硬件副作用前失败；
• 未知、缺失、越界、单位不符和 private override 在硬件副作用前失败；
• 任意已登记设备作者句柄只按冻结的 init_param_schema.config 校验，不直接读取或 import 运行时驱动；
• secret plaintext 不进入 Git、CLI history、日志、Registry 或 snapshot；
• 修改启动值产生新候选启用快照（Activation Snapshot），不产生新定义 revision；
• -g/--graph 是唯一启动定义来源参数，所有输入种类经过同一候选启用解析器（activation resolver）；
• -g/--graph 只接受 .py、.json、.graphml；未知或无后缀失败，.py 不 import/exec 且恰好一个顶层 @workcell 根定义；
• 失败启动留下零 partial driver、零 live Registry instance、零物料 bootstrap。

关联

• [Wayfinder] 领域设备包仓库架构：根单包、Workspace 自动发现与 Package Catalog #147
• [Wayfinder] WorkCell 组合定义、注册编译与分层 Action 暴露 #181

[TablewareBox]

D3-01 已确认：启用参数输入按需存在

维护者确认：当候选工作单元（WorkCell）没有公开 InitParam，或者所有公开参数都有默认值且本次不需要覆盖时，workcell.py 本身就足以作为启动输入；不得强制生成空 JSON。

边界补充：

• 固定、非敏感、对该定义所有启用一致的站内设备配置可以留在 Python 定义；
• 随物理安装变化的值、外部需要选择的值或敏感配置（Secret）必须显式进入候选工作单元初始化合同（WorkCell Init Contract），不能通过 devices.plc.url 一类深路径绕过公开边界；
• 参数输入可以缺席，但候选启用快照（Activation Snapshot）不能缺席。resolver 仍需把默认值、身份、根位姿、定义/目录指纹和来源冻结为可审计事实。

下一题 D3-02

零覆盖时是否需要持久化空参数记录？

推荐 A：不创建空 params 文件/记录；启动请求把“无覆盖”表示为缺席，resolver 仍生成并持久化完整候选启用快照（Activation Snapshot）。

• A（推荐）：参数覆盖缺席，快照始终存在；
• B：自动生成并保存 {} 参数记录；
• C：两者都不保存，直接从 Python 启动。

等待维护者确认 A / B / C。

[github-actions]

GitHub → Feishu OKF synchronization

Feishu snapshot: Uni-Lab-Core #184
Knowledge stage: protocol-definition
Issue updated: 2026-08-04T12:53:08Z

[TablewareBox]

D3-02 已确认：选择 A

维护者确认 D03-02 选择 A，现冻结为：

• 零覆盖时不创建或持久化空 params 文件/记录；
• 参数输入缺席就是“无覆盖”，不使用空 {} 作为第二种等价表示；
• 候选启用解析器（activation resolver）仍解析默认值，并为每次成功启用生成、持久化完整脱敏的候选启用快照（Activation Snapshot）；
• 快照记录值来源为默认值/定义固定值，但不保存敏感配置（Secret）明文。

已同步到独立设计文档与本票验收门，审阅见 #188。

[TablewareBox]

Grill D3-03：多个外部覆盖来源是否允许叠加？

依赖已经明确：workcell.py 提供定义固定值与默认值；参数覆盖可以完全缺席；零覆盖不保存空记录；每次启用仍冻结候选启用快照（Activation Snapshot）。下一步必须决定一次启用能否同时混用 params 文件、持久部署记录、UI/API 表单或 CLI inline 值。

A. 每次启用只允许一个外部覆盖对象（推荐）

• 定义默认值 + 一个 closed override object；
• 这个对象可以来自 params 文件、持久部署记录或 UI/API 提交，但一次启用只能选一个来源；
• 同时给出多个来源时，在硬件副作用前失败，不做隐式 merge；
• 候选启用快照（Activation Snapshot）记录该唯一来源及逐字段默认/覆盖来源。

优点：确定、易审计、AI 修改不会依赖隐藏优先级；未来若确有 overlay 需求，可以新增显式、版本化的合并操作。

B. 固定优先级自动叠加

例如 CLI inline > params 文件 > 持久部署记录 > 定义默认值。灵活，但同一命令上下文会悄悄改变最终启动值，审计和复现必须记录逐字段覆盖链。

C. 调用方自选优先级

最灵活，也最容易产生无法复现的部署差异，不建议进入 v1。

请确认 A / B / C。建议选择 A。

[TablewareBox]

D3-03 已确认：选择 A

维护者确认一次启用最多接受一个外部覆盖对象：

• 参数输入可以缺席；
• 存在外部覆盖时，只能选择一个 params 文档、持久部署记录或 UI/API 提交来源；
• 多个外部来源同时出现时，在任何硬件副作用前失败；
• 不做隐式叠加，也不定义 CLI、文件和持久记录之间的优先级；
• 候选启用快照（Activation Snapshot）记录每个最终值来自定义固定值、默认值还是该唯一覆盖对象。

已同步到父地图 #181、独立设计文档和 PR #188。

Grill D3-04：首个实现切片是否完全禁用外部参数输入？

这里必须区分“目标 v1 合同”和“首个可运行切片”。D3-03 已冻结目标合同最多一个外部来源；首个切片可以先只实现它的零来源子集。

A. Phase 0 仅支持 Python-only，v1 合同保留单一外部来源（推荐）

• --workcell-params、持久部署记录和 UI/API 参数提交在 Phase 0 明确报“尚未支持”，不能静默忽略；
• 只允许启动零公开 InitParam，或全部公开参数都有默认值且不需要敏感配置（Secret）引用的定义；
• 仍完成编译、合同校验、默认值解析并持久化脱敏候选启用快照（Activation Snapshot）；
• 下一切片再实现 D3-03 已冻结的单一外部覆盖对象，不需要修改协议或 Python 语法。

B. 整个 v1 都不允许外部参数输入

这会让公开 InitParam 的必填值、现场差异和敏感配置（Secret）引用无处绑定，迫使每个部署复制或修改定义，不建议。

C. 首个实现切片直接支持一个外部覆盖对象

交付价值更完整，但需要同时实现 params Schema、来源诊断、敏感配置（Secret）引用和快照来源追踪。

请确认 A / B / C。建议 A；它缩小首个交付面，但不牺牲已经冻结的定义/启用边界。

[TablewareBox]

D3-04 与 D3-05 已确认

维护者确认：

• D3-04=A：Phase 0 仅实现 Python-only 零外部参数路径；任何外部参数输入都明确失败，但仍校验默认值并持久化脱敏候选启用快照（Activation Snapshot）。完整 v1 保留 D3-03 的单一外部覆盖对象合同。
• D3-05：复用现有 -g/--graph 作为唯一启动定义来源参数，不新增 --workcell。

当前实现证据：Uni-Lab OS main（6501468e71bc78871ca6a37bea35f415aa10a74e）已经注册 -g/--graph，并按 .json 与其他格式分派。目标设计沿用该入口，但把帮助语义从“物理图文件”扩展为“启动定义来源”。

已同步到父地图 #181、独立设计文档和 PR #188。

Grill D3-06：-g 如何区分 Python、遗留 JSON 与 GraphML？

A. 严格按文件后缀分派（推荐）

unilab -g deployment/workcell.py       # 候选工作单元定义（WorkCell Definition），仅做受限 AST 编译
unilab -g legacy/startup.json          # 遗留 JSON 启动图（Legacy JSON Startup Graph）
unilab -g legacy/startup.graphml       # 遗留 GraphML 启动图（Legacy GraphML Startup Graph）

只接受 .py | .json | .graphml，未知或无后缀直接失败；不再保留当前“非 .json 一律当 GraphML”的模糊回退。后缀只决定解析器，所有格式仍需各自完整校验；.py 绝不通过普通 import/exec 执行。

B. 要求显式来源前缀

例如 -g python:deployment/workcell.py、-g json:legacy/startup.json。更显式，但让日常命令变长，也偏离现有 -g path 习惯。

C. 读取内容后自动探测

无后缀也尝试判断 Python/JSON/XML。体验看似灵活，但错误诊断和安全审计最差，不建议。

请确认 A / B / C。建议 A；未来若加入目录引用，可继续在同一个 -g 下另行定义 catalog:，无需新增参数。

[TablewareBox]

D3-06 已接受：选择 A

-g/--graph 严格按文件后缀选择解析器：

• .py → 受限 AST 候选工作单元定义（WorkCell Definition）编译器；不得 import/exec 作者源码；
• .json → 遗留 JSON 启动图解析器；
• .graphml → 遗留 GraphML 启动图解析器；
• 未知或无后缀 → 在任何驱动构造、设备连接或物料 bootstrap 前失败；不做内容探测，不再把“非 JSON”回退成 GraphML。

该决策已同步父地图 #181、D3 子议题 #184、独立设计文档和 PR #188。当前设计文档提交：e938aee。

Grill D3-07：一个作为启动输入的 .py 文件允许几个顶层 @workcell 根定义？

A（推荐）— 恰好一个。 -g path/workcell.py 指向的文件必须声明且只声明一个顶层候选工作单元定义（WorkCell Definition）；零个或多个都报错。被根定义引用的嵌套定义不算额外启动根。这样文件本身就是入口，不需要再发明 file.py:id 选择语法。

B — 允许多个，-g 值同时携带 selector。 例如 -g path/workcells.py::szlab_poly_station。复用一个文件方便，但把第二套入口语法塞进路径，并增加补全、转义和歧义处理。

C — 允许多个并自动选择。 通过源码顺序或 default=True 决定；看似省参数，但重排源码或默认标记冲突会改变启动目标。

我推荐 A：它最贴合“候选工作单元定义文件就是启动文件”，同时为 AI、CLI、审计和 digest 留下唯一入口。

请选择 A / B / C。

[TablewareBox]

D3-07 已接受：选择 A

一个 .py 启动文件必须恰好声明一个顶层 @workcell 根定义：

• 零个根定义：失败；
• 多个根定义：失败；
• 根定义通过受控引用组合的嵌套候选工作单元定义（WorkCell Definition）不计为额外启动根；
• -g path/workcell.py 本身足以确定入口，不增加 file.py::id 选择器（selector）或 default=True。

该决策已同步父地图 #181、D3 子议题 #184、独立设计文档和 PR #188。当前设计文档提交：fe1c51c。

当前实现证据

Uni-Lab OS main（6501468e71bc78871ca6a37bea35f415aa10a74e）的当前代码已经形成一条可复用的单向合同链：ast_registry_scanner.py 静态提取设备类 __init__ 参数，registry.py 生成 init_param_schema.config，initialize_device.py 再把解析后的 config 传给运行时驱动。遗留 YAML 仍可携带 init_param_schema / init_param_enforce，所以现在必须冻结谁是新候选工作单元（WorkCell）创作的唯一合同权威。

Grill D3-08：workcell.py 中 plc(...) 可接受哪些初始化参数，由谁定义？

A（推荐）— 已发布目录中的 init_param_schema.config 是候选工作单元编译器的唯一消费合同。 对现代 @device，该 Schema 由带类型的驱动 __init__ 在发布时静态生成并校验；workcell.py 中的 plc(...) 只是已登记设备类型的作者句柄，不另建一份签名。候选工作单元编译器只读取固定的目录快照，不 import/inspect 运行时驱动。遗留 YAML 只作为遗留设备生成同一目录字段的兼容来源，不能成为并行覆盖层。

B — plc(...) 工厂函数签名拥有独立合同。 写法最像普通 Python，但工厂、目录 Schema 与驱动构造器会形成三份可能漂移的定义。

C — 每次编译候选工作单元时直接读取驱动 __init__。 少一份发布产物，但编译结果依赖现场包源码，难以固定目录版本，也会迫使编译器跨包读取甚至 import 驱动。

我推荐 A：作者仍获得 Python 类型体验，AI 只需面对一份固定、可校验的 Schema，运行时实现也不会泄漏进候选工作单元定义。

请选择 A / B / C。