[AIW Spec] UniLab AI 原生工作区控制面与 Agent 自动化

[TablewareBox]

Problem Statement

UniLab Workbench 目前把本地 OS、工作区投影、前端会话和进程管理部分耦合在 Theia/Node 生命周期中。Agent 能编写代码，却不能通过一个稳定、跨 UI 生命周期的公开控制面完成环境启停、工作流运行、结果观察、物料画布截图和布局迭代；绕过 Workbench 直接杀 Python 或临时调用内部 RPC 会使 App 中的 PID、日志、generation 和事实状态失真。设备进程重启还可能连带影响 Authoring、画布与本地数据，使“编辑代码—实时诊断—运行—观察—调整”的 AI 原生闭环不可靠。

Solution

把一个工作区建模为 Managed Local Environment：Workspace Host 是唯一生命周期权威；常驻 Local Backend 同时承载 Authoring API、last-valid 投影、诊断、SSE 和 local Domain Authority；一次性 Authoring Worker 只隔离执行不可信工作区代码的编译故障域；可重启 OS Edge Runtime 只负责 EdgeExecution、ROS、驱动和设备动作。前端、CLI 和 MCP 共享 Backend-shaped /api/v1 与 Workspace Host Client，不再各自管理进程。

产品上 Authoring 与常驻 Local Backend 合并：用户和 Agent 只连接一个稳定 Backend 地址。Authoring Worker 不构成第二套 Backend，不监听业务端口、不持久化业务状态，按稳定文件代返回候选或诊断后退出。

Agent 的基础能力由 unilab CLI 提供，MCP 仅做类型化 Adapter，Skill 只描述工作流。物料画布通过同一公共 scene/layout/render engine 提供结构检查、attached capture、布局 preview/apply CAS 和 headless capture，使模板与设备布局可以在 Workbench 打开或关闭时得到可重复反馈。

User Stories

1. As a Workbench user, I want to open a workspace and immediately browse workflows, devices and materials before starting device control, so that authoring is not coupled to hardware readiness.
2. As a workflow author, I want invalid Python to produce structured diagnostics while the last-valid canvas remains visible, so that one edit cannot destroy my working view.
3. As a workflow author, I want file saves to update Authoring projections and SSE in real time, so that code and canvas stay synchronized.
4. As a driver developer, I want a bad import or compiler crash isolated from the Local Backend, so that the Workbench remains usable.
5. As a Workbench user, I want one stable Local Backend address for the whole workspace session, so that UI caches and subscriptions survive device restarts.
6. As a Workbench user, I want “restart OS” to restart only the Edge Runtime, so that Authoring, inventory, task history and frontend state remain available.
7. As an operator, I want reset-local-state to be distinct from restart-OS, so that destructive data rebuilding is explicit and audited.
8. As an Agent, I want unilab workspace status/start/stop/restart/logs to use the same Managed Local session as Workbench, so that App state never diverges from command-line actions.
9. As an Agent, I want stable JSON output, operation IDs, generations and cursors, so that I can retry and resume safely.
10. As a Workbench user, I want browser reloads or Electron renderer crashes not to stop Backend, Edge, PLC-Sim or an active task, so that UI lifecycle is not process ownership.
11. As a local operator, I want Local Scheduler to drive the same Edge Runtime protocol used by the production Backend, so that local testing exercises production execution semantics.
12. As a deployment operator, I want to atomically choose local or backend Domain Authority, so that two schedulers never write the same aggregate.
13. As a Workbench user, I want Authoring and Runtime contexts to have isolated source identities and cache namespaces, so that candidates are not mistaken for execution facts.
14. As an Agent, I want to run, watch, inspect and command workflows through unilab, so that coding and execution share one automatable interface.
15. As an Agent, I want MCP workflow tools to delegate to the same SDK and contracts as CLI, so that MCP never becomes another state authority.
16. As an Agent, I want task and node events as bounded JSONL with resumable cursors, so that long-running workflows can be monitored without scraping UI text.
17. As an Agent, I want to inspect the material scene structurally and capture the attached Workbench canvas, so that I can reason about both scene facts and rendered output.
18. As a layout author, I want layout preview and apply protected by revision CAS, so that Agent changes cannot silently overwrite a human edit.
19. As a template developer, I want a headless renderer to validate and capture templates when Workbench is closed, so that visual regression can run in CI.
20. As a product owner, I want the same lifecycle, path, lock, token and renderer contracts verified on macOS, Windows and Linux, so that the Workbench is not accidentally macOS-only.
21. As an operator, I want every process action and real workflow action recorded, while PLC-Sim remains simulation and does not require hardware approval, so that audit and safety match the selected environment.
22. As a maintainer, I want Local Backend routes that overlap the Go Backend to follow the Go repository’s /api/v1 contracts, with OS-only Authoring extensions explicitly allowlisted, so that frontend clients do not fork.

Implementation Decisions

• A Managed Local Environment comprises Workspace Host, Local Backend, disposable Authoring Workers, OS Edge Runtime, optional PLC-Sim and attached/headless renderers.
• Workspace Host owns the workspace lock, session manifest, local token, lifecycle operations, readiness, logs, process generations and stable file-generation monitoring. Theia, Electron, CLI and MCP are clients.
• Local Backend stays alive for the workspace session and owns Authoring projection/state, local Domain data in local mode, diagnostics, revisions, SSE and last-valid results.
• Authoring and Local Backend are one product service. Compilation that imports newly edited workspace code runs in a disposable subprocess and returns a versioned JSON result; it is not another network service.
• OS Edge Runtime is the only object affected by “start/stop/restart OS”. It owns EdgeExecution, edge control state, HostLink/ROS, drivers, device actions and physical completion/reconciliation.
• Domain Authority is exactly one of local | backend. There is no authoring-only Domain Mode and no per-endpoint fallback.
• Authoring Context always reads the Local Backend projection. Runtime Context atomically selects Local Domain Adapter or Go Backend Adapter, including base URL, source ID, credentials, SSE cursor and cache namespace.
• Local execution reuses the production durable Edge Interface: HTTP carries persistent facts and WebSocket carries short commands/notifications. A new ad-hoc Node RPC is not introduced for device control.
• Overlapping Local Backend HTTP routes conform to the Uni-Lab-OS organization’s Go uni-lab-backend contracts. OS-only Authoring/lifecycle extensions are explicit.
• unilab CLI is the stable automation surface. MCP delegates to the same client SDK; Skills do not implement control logic.
• Lifecycle commands and Domain commands are separate. os.restart never implies local.reset-state.
• Material automation shares one scene/layout/render engine across kernel-web, Workbench, attached automation and headless automation.
• Layout writes use explicit preview/apply with revision CAS and return structured diffs, diagnostics and capture artifacts.
• Session and renderer discovery is local-token protected and loopback by default. Remote exposure is a separately authenticated Workbench deployment concern.
• Durable edge_control.db is deferred only where explicitly noted; no code may silently claim exactly-once physical execution without it.

Testing Decisions

• The highest public seams are the Workspace Host Client/CLI, Backend-shaped /api/v1, durable Edge Interface and renderer automation contract. Tests assert externally visible state, identity, revision, diagnostics and artifacts rather than child-process implementation details.
• Browser E2E runs against a real Managed Local Workbench. It verifies Workflow and Material canvases, invalid-draft last-valid behavior, stable Backend identity and runtime state.
• OS integration tests use real workspace packages and assert a compiler subprocess cannot mutate the live registry on failure.
• Lifecycle tests assert PID/generation/log changes through Workspace Host, not by scanning and killing processes directly.
• Edge tests cover duplicate command, disconnect, crash/restart, outcome replay and UNKNOWN reconciliation at the durable protocol boundary.
• Authority tests prove local/backend mutual exclusion and fail-closed switching, including cache/SSE identity.
• CLI/MCP contract tests compare JSON results for the same session, task and node states.
• Renderer tests compare structural scene facts plus screenshots; image-only assertions are insufficient. Visual tests run at fixed viewport/theme and preserve artifacts.
• Cross-platform tests cover dynamic ports, absolute interpreter discovery, locks, process-tree stop and token permissions on macOS, Windows and Linux.

Out of Scope

• A third Authoring Domain Control Plane or a second Authoring Backend.
• Agent-owned PID files, direct process killing, UI text scraping or an MCP-only implementation of lifecycle/domain logic.
• Cloud multi-tenant orchestration, automatic public internet exposure or centralized fleet management.
• Silent local/backend endpoint fallback or merged lists that pretend two Authorities are one.
• Automatic approval of real physical hardware actions. Existing policy remains: real-device actions require the product’s explicit human approval boundary; PLC-Sim does not.
• Formal persistent Edge store delivery in the first slice where it was explicitly deferred, though the final Edge Runtime slice must close the durability contract before claiming production resilience.

Further Notes

The detailed architecture and migration rationale are recorded in docs/research/ai-native-workspace-control-architecture-2026-08-12.md. Implementation baseline: Uni-Lab OS product/durable-scheduler-kernel-new@870cf0a5 and the corresponding Workbench frontend development line. Earlier Workbench decisions remain authoritative where this spec does not replace them.

[github-actions]

GitHub → Feishu OKF synchronization

Feishu snapshot: Uni-Lab-Core #215
Knowledge stage: implementation
Issue updated: 2026-08-13T12:01:02Z