设备自动化控制平面

Asset

ADP-DLV-FEAT-DOC-0010

Feature

device-automation-control-plane

领域

delivery-integrations

作用域

application-level

文档状态

draft

产品生命周期

active

文档 Owner

DOC

事实源

canonical-docs

工程 Owner

WSI

Development Ready

not-ready

更新

2026/10/14

FEATURE DEVELOPMENT PACKAGE

工程就绪状态

工程 Owner：WSI · 仓库：DSP / PLN / WSI

BLOCKED

development · not ready

• ×原子需求与验收
• ✓设计与工程合同
• ✓代码与仓库定位
• ×里程碑与工作包
• ×验证计划
• ✓无阻断决策

verification · not ready

• ×Development Ready 已通过
• ×验收标准已覆盖
• ✓正式测试已登记
• ×Fixture 与环境已定义
• ×测试规格已物化到正式测试

release · not ready

• ×Verification Ready 已通过
• ✓实现修订可定位
• ×发布证据已登记
• ×兼容与迁移已定义
• ×Runbook 与回滚已定义

查看阻断项（3）

• Development Ready 缺少：原子需求与验收
• Development Ready 缺少：里程碑与工作包
• Development Ready 缺少：验证计划

查看完整 readiness查看关联资产

功能目标

为 AutoDev 管理的设备与外部集成提供可评审、可计划、受审批约束的自动化控制合同，同时把 Git source、live runtime、secret 与 evidence 的责任面严格分开。

功能结论

主题	结论
Producer 入口	通过 AutoDev Platform Project Workspace 确认 owner、目标范围和 approval class；source 变更进入 Workspace Integration MR，运行变更必须另行审批 exact plan。
可见结果	可评审的 desired-state/source revision、只读 plan、明确目标集合、approval 绑定和脱敏 runtime evidence。
系统保证	source 与 apply 分离；任何 apply 只接受 exact plan、exact targets、未过期 scoped approval，且由 owning runtime fail closed。
明确不做	不把 Plane、Project Workspace、Git 或文档当作设备安装状态、在线 inventory、credential 或 runtime truth owner；不因 MR 合并自动激活。
事实源 / owner	canonical docs：长期合同；Project Workspace：路由与 gates；Workspace Integration/：reviewed source；secret store：secret；设备及 owning runtime：live state；runtime/evidence store：执行证据。
当前成熟度	draft，仅完成 source-governance 合同与 owner 路由；尚无 runtime activation、设备接入、安装、apply 或可用性声明。

Managed scope

设备自动化控制平面管理以下源代码与治理合同：

• Integration/ 下的设备控制 schema、desired-state 模板、provider adapter source、离线 validator、只读 plan 与 apply 实现源；
• 稳定的 logical device key、target selector、capability 和 desired-state 字段定义；这些只描述期望输入，不证明设备当前存在或在线；
• 对 Runner/BuildKit、TeamCity 与未来设备控制工具的 owner 路由、变更评审、plan/apply 边界和 approval class；
• plan/evidence 的 redaction、identity binding、失败停止条件和 owner-local recovery 合同。

首个 Workspace 实现必须通过独立 MR 提交，并以该 MR 的 source revision 为准。本页面不依赖未合并实现，也不声明任何预定目录已经可执行。

Excluded scope

以下内容不属于 canonical docs、Project Workspace 或 reviewed source truth：

• 设备是否已安装 agent、当前在线状态、网络可达性、OS/firmware、进程、服务、容器、卷和实际配置；
• Runner 注册、TeamCity VCS root/publication、MDM/SSH/远程执行会话、TEST/PROD mutation 和服务重启；
• token、password、private key、certificate private material、authorization header、private DSN 或其它 credential value；
• 第三方 MDM、GitLab、TeamCity、操作系统或设备自身控制面的内部真相；
• 由 source MR、docs MR、Plane Work Item 状态或 approval comment 推断 live activation。

Ownership boundary

Surface	Owns	Does not own
Canonical docs	稳定产品合同、managed/excluded scope、approval 与验收语义	当前设备清单、runtime readiness、secret、一次性执行结果
AutoDev Platform Project Workspace	repo registry、principal routing、跨 surface 决策与 approval gate 定位	device install、runtime command execution、credential value
Workspace repo	Integration/ 下 reviewed source revision 与 repo-local validation	live device state、secret value、runtime activation
Integration source	schemas、templates、adapters、plan/apply implementation source 与 runbook	当前安装状态、在线 inventory、runtime authority
Secret owner	credential 创建、保存、轮换、撤销与 access policy	desired state、plan verdict、设备运行状态
Device / owning runtime	实际安装、连接、inventory observation、命令执行、状态与 owner-local recovery	产品合同、Git review truth、Producer intent
Evidence surface	绑定 source/plan/target/attempt 的脱敏观测和结果	secret material、未观测成功的推断
Plane	Producer work intent；若未来接线，只保存外部 plan/evidence reference	设备安装、在线 inventory、runtime command、secret 或 apply truth

Plane Automation 继续只拥有其自身 Issue execution truth。设备控制不是 Plane execution domain 的扩展；Plane business state、assignee、label、comment 或 Automation Result 都不得触发、替代或重开设备 apply。

Source、runtime、secret 与 evidence 分离

1. Source：Git commit/MR 保存 schema、desired state、adapter 与 validator；source revision 只证明评审内容。
2. Runtime：设备或 owning runtime 保存 observed inventory、安装与运行状态，并执行获批命令；runtime observation 才能证明现场状态。
3. Secret：credential 仅存在于批准的 secret owner；source、plan、MR、Plane、日志和 evidence 只能保存稳定 secret reference 或 redacted metadata。
4. Evidence：保存 source revision、plan digest、target snapshot digest、approval reference、attempt identity、timestamps、redacted output 和 observed result；不得复制 secret，也不得把 missing/partial observation 写成 success。

任一层缺失、identity 不匹配或 owner 不明确时必须停止，不能从另一层推断通过。

Out-of-band bootstrap

首台设备和每个新 trust domain 必须先由 owner 在控制平面之外完成 bootstrap，包括设备所有权确认、网络路径、最小身份、trust anchor、agent/adapter 安装和 secret injection。自动化系统只能在 bootstrap evidence 可读、logical device key 唯一、trust 未过期且 runtime owner 明确后纳管。

控制平面不得自举其尚未拥有的连接，也不得通过默认密码、通用共享密钥、扫描发现、Plane assignment 或未审批脚本绕过 bootstrap。bootstrap credential 与安装结果由 secret/runtime owner 持有，不进入 Git 或 canonical docs。

Plan / apply separation

Plan

Plan 是只读操作，只能从 pinned source revision 与有界 inventory snapshot 计算。结果至少绑定：

• source revision 和 desired-state digest；
• target logical keys 与 inventory snapshot digest；
• provider/capability preconditions、拟执行动作、风险/approval class；
• expected evidence、停止条件、有效期和不可计划项。

Plan 不安装、不注册、不重启、不写 credential、不变更 TeamCity/Runner/device/TEST/PROD，也不因生成成功获得 apply 权限。

Apply

Apply 是独立 mutation。runtime 必须在开始前重新读取 exact plan，验证 source、plan digest、target set、inventory preconditions、approval scope、expiry 和 actor；任何漂移都使 plan 失效并要求重新 plan/approve。Apply 不得扩大 targets、替换 provider、注入额外命令或复用失败 attempt 的 approval。

每个 attempt 产生唯一 identity 和逐目标 evidence。partial success 必须如实记录实际 mutation，不能回写为全量成功；owner-local recovery 只能在原 approval 与 plan 允许的边界内进行，否则重新审批。

Scoped approval gates

以下 gate 互不继承，approval 必须绑定 exact plan digest、source revision、target set、action class、environment、有效期和 single-use/复用规则：

• out-of-band bootstrap 与首次 trust/agent installation；
• credential 创建、注入、轮换或权限变更；
• Runner 注册、BuildKit/storage migration 或 release lane enablement；
• TeamCity live VCS root/publication、parameter/agent registration；
• device install/update/remove、service restart 或其它 runtime mutation；
• TEST apply、PROD apply、destructive operation 与重要数据处理。

Source/docs/Project Workspace MR 的创建或合并只完成评审，不授予上述 gate。缺少 approval、scope mismatch、expired plan、target drift、secret exposure 或 evidence sink 不可用时 fail closed。

Producer 可见表现与证据

Producer 应能分别看到：reviewed source/MR、plan 摘要、目标与风险、所需 gate、approval 状态、attempt identity、逐目标结果和 residual risk。验证至少覆盖：

• source、runtime、secret、evidence 四层没有互相冒充 truth；
• plan 为只读且 apply 拒绝 digest/target/precondition/approval 漂移；
• Plane business/Automation 状态不能触发设备命令；
• bootstrap 未完成、runtime owner 不明或 evidence 不完整时停止；
• secret redaction，以及 partial mutation 不被声明为 success。

当前差距与后续交付

当前只建立 canonical contract、Project Workspace owner route 和 review gate。后续仍需独立 Workspace MR 实现 Integration/ source、repo-local schemas/validators/tests，并由单独获批的 runtime 接线完成 bootstrap、credential、installation 与 activation。每一步必须返回 owning evidence；在真实 runtime readback 前，本 Feature 始终不得宣称设备已纳管或自动化可用。