npm - agentworkshop - Versions diffs - 0.7.54 → 0.7.59 - Mend

agentworkshop 0.7.54 → 0.7.59

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1356) hide show

package/README-zh.md CHANGED Viewed

@@ -1,833 +1,928 @@
-<div align="center">
-<img src="https://raw.githubusercontent.com/kingdol666/AgentWorkShop/main/docs/readme-assets/hero.png" alt="AgentWorkShop —— 让 Agent 团队运行真实产线" width="100%" />
-<br />
-# AgentWorkShop
-**AI Agent 团队与产线在此交汇。**
-[![npm version](https://img.shields.io/npm/v/agentworkshop?logo=npm&logoColor=white&label=npm&color=CB3837)](https://github.com/kingdol666/AgentWorkShop)
-[![npm downloads](https://img.shields.io/npm/dm/agentworkshop?logo=npm&logoColor=white&label=downloads&color=CB3837)](https://github.com/kingdol666/AgentWorkShop)
-[![GitHub release](https://img.shields.io/github/v/release/kingdol666/AgentWorkShop?logo=github&label=release&color=35e0a0)](https://github.com/kingdol666/AgentWorkShop/releases)
-[![Stars](https://img.shields.io/github/stars/kingdol666/AgentWorkShop?logo=github&label=stars&color=35e0a0)](https://github.com/kingdol666/AgentWorkShop/stargazers)
-[![Last commit](https://img.shields.io/github/last-commit/kingdol666/AgentWorkShop?logo=git&logoColor=white&label=last%20commit)](https://github.com/kingdol666/AgentWorkShop/commits)
-[![Issues](https://img.shields.io/github/issues/kingdol666/AgentWorkShop?logo=github&label=issues)](https://github.com/kingdol666/AgentWorkShop/issues)
-[![License](https://img.shields.io/badge/license-PolyForm%20Noncommercial%201.0.0-8A2BE2?logo=openaccess&logoColor=white)](./LICENSE)
-[![Nuxt 4](https://img.shields.io/badge/Nuxt-4-00DC82?logo=nuxt&logoColor=white)](https://nuxt.com)
-[![Vue 3.5](https://img.shields.io/badge/Vue-3.5-42B883?logo=vuedotjs&logoColor=white)](https://vuejs.org)
-[![TypeScript 5.7](https://img.shields.io/badge/TypeScript-5.7-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org)
-[![Node ≥ 23.4](https://img.shields.io/badge/Node.js-%E2%89%A5%2023.4-3C873A?logo=nodedotjs&logoColor=white)](https://nodejs.org)
-[![SQLite node:sqlite](https://img.shields.io/badge/SQLite-node%3Asqlite-003B57?logo=sqlite&logoColor=white)](https://nodejs.org/api/sqlite.html)
-[![Modbus · OPC UA · MQTT · HTTP](https://img.shields.io/badge/%E7%8E%B0%E5%9C%BA%E6%80%BB%E7%BA%BF-Modbus%20%C2%B7%20OPC%20UA%20%C2%B7%20MQTT%20%C2%B7%20HTTP-41c8f4?logo=siemens&logoColor=white)](./docs/site/guide/daq-protocols.md)
-[![Plugins](https://img.shields.io/badge/%E6%8F%92%E4%BB%B6-%E7%83%AD%E9%87%8D%E8%BD%BD-8b5cf6?logo=puzzle&logoColor=white)](./docs/plugins.md)
-[![Docs](https://img.shields.io/badge/%E6%96%87%E6%A1%A3-VitePress%20%C2%B7%20%E4%B8%AD%2FEN-ffd75e?logo=vitepress&logoColor=black)](https://kingdol666.github.io/AgentWorkShop)
-[![PRs welcome](https://img.shields.io/badge/PRs-welcome-ff69b4?logo=git&logoColor=white)](https://github.com/kingdol666/AgentWorkShop/pulls)
-**[English](./README.md)** · **[在线文档](https://kingdol666.github.io/AgentWorkShop)** · **[版本发布](https://github.com/kingdol666/AgentWorkShop/releases)** · **[更新日志](./changelog.md)** · **[插件 API](./docs/plugins.md)** · **[SDK](./docs/sdk.md)**
-<sub><b>v0.7.54</b> · 14 个执行引擎 · 6 种现场协议（5 内置 + 串口插件）+ MES REST 集成 · 116 个运行时设置项 · 双语文档（简体中文 / English）</sub>
-<br />
-*一个配置驱动的平台：**AI Agent 团队**与**工业数字孪生**共享同一运行时——Agent 查询真实遥测、经人工审批的写控回路下发监督设定值，每个事件实时推送到 3D 孪生。*
-</div>
-> [!IMPORTANT]
-> **定位声明：监督层。** AgentWorkShop 是面向产线管理、数字孪生、数采与 Agent 编排的**监督层**（SCADA 同位）平台，运行在**秒级软实时**档位。
-> 它**不是**硬实时控制器：任何时序关键回路（**< 10 ms**、联锁、安全、伺服）**必须在 PLC 内实现**。本平台下发的设定值均为建议性——产线侧逻辑可否决。
----
-<table>
-<tr>
-<td width="33%" valign="top">
-**图例索引**
-`图 01` 闭环全流程<br/>
-`图 02` 数采中心<br/>
-`图 03` 产线运营<br/>
-`图 04` 数字孪生<br/>
-`图 05` 仪表盘<br/>
-`图 06` 自适应布局
-</td>
-<td width="33%" valign="top">
-**快速跳转**
-[这是什么？](#这是什么) · [特性总览](#特性总览)<br/>
-[界面一览](#界面一览) · [设计架构](#设计架构)<br/>
-[快速开始](#快速开始) · [配置与 CLI](#配置与-cli--真正的配置驱动)<br/>
-[工业栈详解](#工业栈详解) · [使用说明](#使用说明)<br/>
-[端到端验证](#端到端验证) · [项目结构](#项目结构)<br/>
-[技术栈](#技术栈) · [开发指南](#开发指南)<br/>
-[路线图](#路线图) · [许可证](#许可证)
-</td>
-<td width="33%" valign="top">
-**一眼看懂**
-监督层，秒级软实时<br/>
-14 个执行引擎 · 4 个接入入口<br/>
-6 种现场协议（5 内置 + 串口插件，读 + 写）<br/>
-7 状态任务机 · 根任务队列 + 执行租约<br/>
-群聊作业 · 定时任务 · HITL 审批<br/>
-FTS5 + 向量记忆 · 插件热重载<br/>
-SDK · CLI · TUI · 外部 MCP · 约 1100+ 条验收断言
-</td>
-</tr>
-</table>
----
-## 文档
-文档为双语——[VitePress 站点](https://kingdol666.github.io/AgentWorkShop) 在全站范围内提供语言切换（简体中文 / English）。深度页面同样随仓库发布，CLI 会把它们复制进发布的 tarball：
-| 主题 | 在线 | 仓库内 | 内容 |
-|---|---|---|---|
-| **上手指南** | [指南](https://kingdol666.github.io/AgentWorkShop/guide/getting-started) | `docs/site/guide/` | 安装 → 首次运行 → 第一次「Agent × 产线」会话、配置系统、数采协议、数控读写、HITL、配方版本、多 Harness 团队、产线权限、AML |
-| **插件开发** | [插件指南](https://kingdol666.github.io/AgentWorkShop/plugins/) | [`docs/plugins.md`](./docs/plugins.md) | 完整扩展契约：三种作用域、`index.mjs` 清单、`ctx` 服务端/浏览器能力面、`settings`/`groups` 声明、生命周期事件、i18n、面板、团队级开关、一个真实案例 |
-| **SDK** | [SDK 指南](https://kingdol666.github.io/AgentWorkShop/sdk/) | [`docs/sdk.md`](./docs/sdk.md) | `agentworkshop/sdk` 作为编程客户端（带信封处理的平台 REST 客户端）与插件扩展基座；TypeScript 类型；浏览器端 SDK |
-| **CLI** | [CLI 手册](https://kingdol666.github.io/AgentWorkShop/cli/) | [`docs/cli.md`](./docs/cli.md) | 全部 15 个 `aw` 指令、全局选项、退出码、双模式路径模型、指令注册系统、维护者发布指引 |
-| **AML** | [AML 指南](https://kingdol666.github.io/AgentWorkShop/guide/aml) | [`docs/aml.md`](./docs/aml.md) | 自动建模实验室：数据集构建、作业编排、模型注册表、晋级门禁、Agent 工具 |
-| **TUI** | — | [`docs/tui.md`](./docs/tui.md) · [`tui/README.md`](./tui/README.md) | 终端工作台：频道、Agent、任务、实时监控、HITL 应答 |
-| **多 Harness 架构** | — | [`docs/multi-harness-architecture.md`](./docs/multi-harness-architecture.md) | 引擎分类、归一化会话契约、供应商/模型目录、失败模式 |
----
-## 这是什么？
-AgentWorkShop 起家于**多智能体软件工作坊**——Channel 内的编码 Agent 团队，配备 lead 调度器、7 状态任务机、持久记忆，以及四个互操作入口（WebSocket / MCP / A2A / REST）。
-随后它长出了**工业半边**：完整的数采与写控栈（Modbus TCP / OPC UA）、带配方与批次运行的产线、3D 数字孪生小镇、一个**自动建模实验室**（数据集 → 训练作业 → 排行榜 → 门禁晋级）——以及让它独一无二的桥：**Agent 可被授予对真实工业节点的访问权——绑定到具体节点、按权限作用域收窄**，带着物理语义查询其实时遥测，并经「联锁 → 人工审批 → 回读校验」管线驱动写操作。
-它同时**天生可扩展**：一个自包含插件可以同时增强服务端（钩子、路由、Agent 工具、数采驱动、配置分组）与浏览器（面板、i18n），而同样的能力面也通过 SDK 开放给普通程序——见 [`docs/plugins.md`](./docs/plugins.md) 与 [`docs/sdk.md`](./docs/sdk.md)。
-最终效果：提交一个目标，比如「分析熔体温度趋势并优化设定值」——Agent 团队读取真实传感器历史、计算统计量、提议新设定值、在 HITL 面板等您批准、写入 PLC、校验回读、带着数值汇报。**端到端，自动化 E2E 已验证。**
-<div align="center">
-### 图 01 — 闭环全流程
-<img src="https://raw.githubusercontent.com/kingdol666/AgentWorkShop/main/docs/readme-assets/fig-01-closedloop.gif" alt="Agent 团队读取实时遥测、提议设定值、等待审批、写入 PLC 并校验回读" width="88%" />
-<sub><b>目标 → 读取 → 计算 → 审批 → 写控 → 回读 → 汇报。</b><br/>
-录制自运行中的实例：真实数采历史、真实写控、真实 HITL 审批。</sub>
-</div>
-> [!NOTE]
-> 本 README 中的每一张图都是**运行中实例**的录屏或截图，没有一张是效果图。屏幕上的数字来自流经产品同一套代码路径的工业数据。
-<div align="center">
-### 🎬 实机演示（4 分 11 秒，英文配音 + 字幕）
-<a href="https://github.com/kingdol666/AgentWorkShop/blob/main/docs/site/public/demo/agentworkshop-demo.mp4"><img src="docs/site/public/demo/poster.jpg" alt="AgentWorkShop 实机演示：数采中心、写控下发回读、串口插件、Agent 团队执行、闭环趋势与 3D 数字孪生" width="86%" /></a>
-<sub><b>点击封面观看完整演示。</b>真实 PLC 模拟器 + 真实串口枚举 + 真实 Agent 团队执行，全程无剪辑造假。<br/>场景：仪表盘 → 数采中心（实时） → 写控下发与回读 → 串口协议插件 → Agent 团队执行 → 闭环趋势 → 3D 数字孪生。</sub>
-</div>
----
-## 特性总览
-#### Agent 团队运行时
-| 能力 | 为何重要 |
-|---|---|
-| **Lead 编排** | 每个 Channel 一名 lead：分解目标、派发空闲 worker、失败重派、判定目标满足度。LLM 决策 + 确定性规则引擎兜底——系统永不停滞。 |
-| **三种执行模式** | `goal`（满意度判定）· `loop`（定间隔重放）· `pipeline`（顺序阶段）。7 状态任务机带进度、产物与完整历史。 |
-| **Harness 无关** | 一个 `AgentInterface`，**14 个引擎**分三类传输形态：**进程内**——`mock`（无 LLM）、`claude`（Claude Agent SDK，常驻会话，同轮 steer）；**经协议常驻会话**——`omp`（RPC 子进程）、`codex`（app-server JSON-RPC）、`dsh` / `qwen` / `hermes`（ACP）、`opencode`（serve + HTTP/SSE）；**带结构化事件流的无头 CLI**——`gemini`（stream-json）、`copilot`（JSONL）、`cursor`（stream-json）、`crush`（非交互运行）、`goose`（stream-json）、`pi`（`-p --mode json`）。平台永远不知道跑的是哪个。 |
-| **Channel 级 LLM 选择** | 每个 Channel 从 Harness 实时目录中选 **harness → provider → model（+effort）**（如 omp 的 `zhipu-coding-plan/glm-5.3-flash`）。成员未显式覆盖即继承——一个团队混用多种 harness 是一等公民设定，不是绕行。 |
-| **Harness 可用性检查** | `GET /api/workshop/harnesses` 逐引擎探测 PATH 上的 CLI。前端禁用未安装项，且每个入口在执行前都做强校验。 |
-| **停滞安全的监督与任务治理** | 提交的目标进入 **FIFO 根任务队列**，排队位次可见。**监督看门狗**区分「卡死」与「慢」——Agent 工具调用被当作活性信号，健康的长工业作业不会被误回收，真停滞仍会呈报 lead。每次派发携带**派发代 + 执行租约**，被取代 worker 的迟到事件在准入层直接丢弃，而不是寄希望于事后对账。 |
-| **Harness 连续性** | 每个引擎声明连续性形态（`persistent` / `per_turn`）；常驻会话在连续性租约下跨轮复用（pid / 会话 / 复用计数 / 最近重启原因），服务重启能恢复的恢复，而不是悄悄重新拉起。 |
-| **Channel 群聊与原生 HITL** | 频道时间线是真正的群聊：成员请求升级为**可追踪作业**（不是一条会丢的消息）；带原生 ask 能力的引擎（如 `omp`）把 HITL 提问路由进平台——您批准一次，引擎带着回执继续跑。成员权限与用户通知是一等公民。 |
-| **定时任务** | 任意 Channel 任务可挂上**调度**——固定 `interval`（60s 下限）或 `daily` 每日定点——在 `/workshop/schedules` 页或 REST API 管理，带逐次运行历史、忙等守卫（频道仍有在飞任务时触发顺延）与 Channel 级可见性。 |
-| **持久记忆与频道过程记忆** | 私有 + Channel 共享双域；FTS5 CJK 切分，可选向量混合检索，token 预算注入。其上是**过程记忆**：确定性的 root/child/lead 事件名契约、canonical root 摘要、持久 outbox（死信 + 补偿 worker），让一个目标的来龙去脉跨重启存活。 |
-| **四个入口** | 一个 manager 坐在每扇门后：**WS**（AEP v1 事件流，seq 续传）、**MCP**（约 25 个进程内工具）、**A2A**（JSON-RPC 2.0 + AgentCard）、**REST**。 |
-#### 工业栈
-| 能力 | 为何重要 |
-|---|---|
-| **六协议现场总线** | Modbus TCP、Modbus RTU-over-TCP（串口网关）、OPC UA、MQTT、HTTP/REST，外加**内置串口插件**（RS-232/485 直连：Modbus RTU + ASCII 行）——数采**与**写控双驱动带连接池、分类错误文案与逐驱动连接测试；`mock` 覆盖演示/CI；协议即插件：`ctx.daq.registerDriver` / `ctx.dcw.registerWriteDriver` 注入后，前端协议下拉与参数表单即插即现（带 ⌁ 徽标）。 |
-| **Agent 团队 × 工业作用域** | 把 Agent 绑定到数采/数控节点。Agent 看到的是语义卡（物理含义、单位、安全量程、配方窗口）——而不是裸寄存器。 |
-| **人工审批的写控** | 数控下发经过「**安全量程 ∩ 活动配方窗口**」联锁 → 可选 **HITL 审批** → PLC 写入 → **回读校验** → 带签名的写历史。 |
-| **数控读写通道** | 每个控制节点都能沿**写入时所用的同一条标定链路**读回 PLC 当前值：周期读 + 按需读 + Agent 读取，SET 与 ACT 并排呈现——读是被动观测，永不被写联锁阻断。 |
-| **Recipe 版本化治理** | 参数修改按版本入史（归因 用户/Agent/系统 + 操作者 + 原因）。可非破坏地回退到任意修订版或最近一次良好批次。失效节点参数跳过并明确标识。 |
-| **配方链路优化闭环** | Agent 像人类工艺员一样通过配方管理做优化：`recipe_trial` 把多参数候选**整批试验（不写版本）**→ 复测 → 有进步用 `recipe_update` 固化（同一配方 id，版本+1）→ 劣化触发**统一回退**（`recipe_rollback` 带 `dispatch:true` = 定义回退 + PLC 整批恢复）。单参数直调移出闭环；试验受四层限界与同线节拍卡控。 |
-| **频道绑定产线（只读授权）** | 频道可绑定一条产线：全员无需节点绑定即可读取该线的运维日志、配方历史与实时状态（工具回执标注「频道绑定，只读」），写操作仍需节点授权。产线简报自动注入成员提示词；换绑即时回收成员运行时。 |
-| **工艺参数语义映射与调控闭环** | Agent 用工程语义思考：`param_control(param, value)` 按**工艺参数**寻址（跨批次/换配方语义稳定），`param_read` 读回 PLC 当前值取证。每次写入被**四层限界**逐层收窄——节点安全量程 ∩ 工艺参数基准限界 ∩ 活动产品限界 ∩ 活动配方工艺窗口——且每次下发自动开一条调控记录，由 `dcw_judge` 落判定（keep / rollback / uncertain），`dcw_rollback` 执行回退。 |
-| **产线运营** | 产线 → 产品 → 配方 → 批次。配方窗口门控采集并联锁写入；每条样本打标 `product/recipe/run`，实现按批次隔离。 |
-| **多形态数采帧管线** | 多点轮廓（测厚仪/扫描仪）与 CCD 图像帧流经模板 sink 管线：向量与元数据入 Timescale（`daq_frames`），像素入对象存储（MinIO，不可达时自动降级到本地磁盘）；派生指标阈值越限走既有告警链路。 |
-| **Agent 自查工具** | `line_context`、`ops_log`、`recipe_log`、`recipe_versions`、`dcw_journal`——Agent 清楚自己操控的产线/产品/配方，谁做过什么，每个值怎么变。 |
-#### 治理、配置与扩展
-| 能力 | 为何重要 |
-|---|---|
-| **产线级权限** | 工业数据按**产线**三态门控（无权/仅查看/可操控），强制点在数据面——普通用户未授权前看不到任何产线数据。 |
-| **全操作审计日志** | 用户 / Agent / 系统 的每个动作都落进同一份可检索日志；操作者归属「Channel名/成员名」，与用户和系统天然区分。经 WS 实时推送。 |
-| **团队级插件开关** | 每个团队（Channel）持有**独立插件开关组**（`channel_plugins`）：被关闭插件的工具不注入该团队 Agent。插件本体经 `aw plugin` 与 `/plugins` 页热管理。 |
-| **插件扩展 API** | `plugins/<name>/` 下的一个自包含目录**同时增强两半**：`index.mjs`（服务端：钩子、路由、Agent 工具、**数采读驱动 / DCW 写驱动**/帧处理器/节点模板、配置分组、KV、定时器）与 `client.mjs`（浏览器：注入具名插槽的面板、i18n、设置 UI）。三种作用域——`builtin`（随包发布）> `project`（检出）> `user`（`~/.AgentWorkShop`）——启停**与代码修改**均有约 1 秒热重载；停用插件的驱动随热重载立即摘除。内置示例 **serial-bridge**（串口通信：读/写驱动 + 串口探针 API + 前端面板）。完整契约见 [`docs/plugins.md`](./docs/plugins.md)。 |
-| **AML —— 自动建模实验室** | 数据集构建 → 训练作业 → 排行榜 → 晋级门禁 → 模型引用，全部可在 `/aml` 页驱动，也可由 Agent 通过 **14 个 `aml_*` 工具**驱动。Python 运行时由 `uv` 引导至配置根内的 `aml/` 资产根；产物与元数据都留在配置根下。模型带人读身份——label（产线 · 配方 · 目标）、description 与产线/目标 id——可用 `aml_model_find` 按场景选型。 |
-| **AML 混合孪生 × MPC** | 灰箱物理主干 + 有界 PyTorch 残差；`TwinSnapshot` / `VirtualTrial` / `RecommendationCertificate` 配 UQ/OOD 筛查与全轨迹门禁；`hybrid_twin` profile 会额外注入 **12 个 profile 工具**（场景发现/编译/冻结、物理 spec 起草/校验/编译、快照、试验、MPC、门禁、Provider 目录）与通用工具 `twin_calibration_request`。试验按设计保持虚拟（`candidateExecuted=false`），证书签发前只做推荐、不落真实写入。 |
-| **双模式优化闭环** | 专属频道模板把闭环**结构性拆开**：*aml-training* 频道拿建模面（数据集、作业、场景编译、物理 spec、建模任务——无产线写入、无 MPC），*aml-optimization* 频道拿执行面（快照、试验、门禁、MPC、贝叶斯寻优 `twin_bayes_optimize`、受治理微写 `optimization_explore`）——边训边优在结构上不可能。**探索**模式走治理链写入并做响应回读配对（每笔写入落 `optimization_explorations` 台账）；**生产**模式要求绑定过门禁的模型（`aml` 模式，实例化时给 `boundModelId`）。 |
-| **运行时可观测** | `GET /api/system/monitor` 把 Agent 团队内部暴露成数字：根队列深度、看门狗介入次数、Harness 会话复用、记忆 outbox 积压——每项都有对应的文档化回退开关，新机制可以不重新部署就关掉。 |
-| **产线操作单页（`/operations`）** | 一页看全对产线的每一次触碰：实时操作流水（REST 快照 + WS 推流）把写控、数采、建模、配方、回退、报警、产线、人工、系统动作归入**九类分类**，写控行渲染结构化 **前值 → 后值 diff 徽章**（失败标红），并直接从事件流推断**闭环阶段**（监视 → 探索·小步 → 推荐搜索 → 影子验证 → 生产）。同一数据面也供工作台控制台的「产线作业」面板使用。 |
-| **外部 MCP 网关** | `aw mcp` 启动零依赖的 **stdio MCP 服务**（38 个工具），自动发现运行中的实例（环境变量 → 锁文件 → 配置文件），把产线、配方（含 mark-good）、受治理 DCW 写入、工艺参数语义映射、数采查询、频道、团队供给、模型晋升、判卷/回退与插件管理暴露给任意 MCP 客户端——受 `mcp.enabled` 运行时设置门控，附 `--doctor` 与 `--print-config` 辅助指令。 |
-| **全量配置驱动运行时** | 全部运行旋钮（记忆预算、上下文压缩、回退护栏、保留策略、备份、日志级别、系统时区、MCP 开关…）在设置描述符注册表声明一次，优先级 **config.yml < runtime-settings < env**——**113 个设置项、18 组**（37 live / 79 restart），代码零硬编码默认。 |
-| **可配置系统时区** | 一个 `time.timeZone` 设置项（IANA 时区，live 热生效）统一驱动人读时间——日志、聊天、审计、Agent 记录与定时任务；机器时间轴（数采样本、`timestamptz`）仍保存绝对时间。 |
-| **可配置节拍** | 采样与查询的默认值/下限全部是 **live 设置**（`daq.sampling.*`、`daq.query.*`）：热重载、create/patch 时钳制，Agent 工具描述实时携带当前值。 |
-#### 数字孪生
-| 能力 | 为何重要 |
-|---|---|
-| **3D 数字孪生** | Three.js 小镇：放置产线设备与 Channel 领地，实时查看设备健康、告警与数值——由同一事件总线驱动。自适应画质阶梯（DPR / 阴影 / Bloom 分档 + 墙钟 FPS 预算）自动匹配机器，`window.__townStats` 暴露真实渲染指标供性能探针使用。 |
----
-## 界面一览
-下面每一屏都是真实界面，1440×900，录制自正在运行的实例。
-<div align="center">
-### 图 01 — 闭环全流程
-<img src="https://raw.githubusercontent.com/kingdol666/AgentWorkShop/main/docs/readme-assets/fig-01-closedloop.gif" alt="Agent 团队读取实时遥测、提议设定值、等待审批、写入 PLC 并校验回读" width="88%" />
-<sub><b>目标 → 读取 → 计算 → 审批 → 写控 → 回读 → 汇报。</b><br/>
-录制自运行中的实例：真实数采历史、真实写控、真实 HITL 审批。</sub>
-<br />
-### 图 02 — 数采中心
-<img src="https://raw.githubusercontent.com/kingdol666/AgentWorkShop/main/docs/readme-assets/fig-02-daq.gif" alt="数采中心：节点台账、实时趋势、报警横条与事件流" width="92%" />
-<sub><b>端到端的采集链路。</b>量规统计带之下的节点台账与健康度、随样本落库而生长的趋势曲线、
-只保留真正未确认项的报警横条，以及滚动的事件流。</sub>
-<br />
-### 图 03 — 产线运营
-<img src="https://raw.githubusercontent.com/kingdol666/AgentWorkShop/main/docs/readme-assets/fig-03-dcw.gif" alt="产线运营：产线、产品、配方与写控制" width="92%" />
-<sub><b>产线 / 产品 / 配方 / 批次。</b>开跑产线即用配方窗口为采集设门，并给每个样本打上
-<code>产品/配方/批次</code> 标识；控制节点通过它写入时用的同一条标定路径呈现 <b>SET vs ACT</b>。</sub>
-<br />
-### 图 04 — 数字孪生
-<img src="https://raw.githubusercontent.com/kingdol666/AgentWorkShop/main/docs/readme-assets/fig-04-town.gif" alt="由实时遥测驱动的 3D 数字孪生小镇" width="92%" />
-<sub><b>孪生就是同一条事件总线的渲染结果。</b>设备、频道领地、报警与实时数值——自适应画质阶梯
-（DPR / 阴影 / 泛光，墙钟 FPS 预算）让它在中端机器上也保持诚实。</sub>
-<br />
-### 图 05 — 仪表盘
-<img src="https://raw.githubusercontent.com/kingdol666/AgentWorkShop/main/docs/readme-assets/fig-05-dashboard.gif" alt="带 KPI 量规与趋势的运行仪表盘" width="92%" />
-<sub><b>一屏看全工作坊。</b>频道、Agent、任务、数采吞吐与报警——读的是 API 服务的同一份状态，
-不是另建一套指标存储。</sub>
-<br />
-### 图 06 — 自适应布局
-<img src="https://raw.githubusercontent.com/kingdol666/AgentWorkShop/main/docs/readme-assets/fig-06-responsive.gif" alt="同一套界面从桌面到平板再到手机的形态变化" width="92%" />
-<sub><b>桌面 → 平板 → 手机。</b>刻度轨先收成图标轨、再变成抽屉；页头纵向堆叠，
-高密度表格变成可横向滚动的「账页条」，并把身份列钉在左缘。</sub>
-</div>
-<table>
-<tr>
-<td width="50%"><img src="https://raw.githubusercontent.com/kingdol666/AgentWorkShop/main/docs/readme-assets/shot-workshop.png" alt="Agent 工作台" width="100%" /><br/><sub><b>Agent 工作台。</b>频道时间线、lane、任务、记忆与 HITL 收在同一张工作台。</sub></td>
-<td width="50%"><img src="https://raw.githubusercontent.com/kingdol666/AgentWorkShop/main/docs/readme-assets/shot-monitor.png" alt="运行时监控" width="100%" /><br/><sub><b>运行时监控。</b>每条已接线频道、成员数、依赖环与归属用户。</sub></td>
-</tr>
-<tr>
-<td><img src="https://raw.githubusercontent.com/kingdol666/AgentWorkShop/main/docs/readme-assets/shot-settings.png" alt="系统设置" width="100%" /><br/><sub><b>系统设置。</b>18 组 113 个设置项，由描述符驱动——CLI 读的是同一份注册表。</sub></td>
-<td><img src="https://raw.githubusercontent.com/kingdol666/AgentWorkShop/main/docs/readme-assets/shot-plugins.png" alt="插件管理" width="100%" /><br/><sub><b>插件管理。</b>三种作用域、改代码即热重载、按团队开关。</sub></td>
-</tr>
-</table>
----
-## 设计架构
-```mermaid
-flowchart TB
-    subgraph FE["前端 — Nuxt 4 / Vue 3"]
-        UI["工作台 UI · 3D 孪生 · 大屏"]
-        WS["AEP 客户端 — seq 续传"]
-    end
-    subgraph SRV["服务端 — Nitro / h3"]
-        REST["REST /api/workshop/**"]
-        HUB["WS Hub — AEP v1"]
-        A2A["A2A JSON-RPC"]
-        MCP["MCP Server"]
-        subgraph RT["运行时"]
-            MGR["AgentChannelManager"]
-            SCH["SchedulerLoop — lead 监督"]
-            TE["TaskEngine — 7 态任务机"]
-            AR["AgentRuntime × N"]
-            MEM["AgentMemory — FTS5 + 向量"]
-            BUS["事件总线 (ManagerBus) — per-channel seq + 环形缓冲"]
-        end
-        subgraph IND["工业"]
-            DAQ["数采网关 — 逐节点边缘运行时"]
-            DCW["数控网关 — 写控"]
-            BR["队列 — inproc / MQTT"]
-            TSDB["时序库 — SQLite / Timescale"]
-        end
-        subgraph HB["Harness 适配器 — 14 个引擎"]
-            MOCK["mock · claude — 进程内"]
-            OMP["omp — RPC 子进程"]
-            CDX["codex — app-server"]
-            DSH["dsh · qwen · hermes — ACP"]
-            OC["opencode — serve"]
-            FAM["gemini · copilot · cursor · crush · goose · pi — 无头 CLI"]
-        end
-        DB[("SQLite — channels · agents · tasks
-messages · memories (FTS5) · events")]
-    end
-    UI <--> WS
-    WS --> BUS
-    REST & A2A & MCP --> MGR
-    MGR --> SCH & TE & AR
-    AR --> MEM
-    AR --> MOCK & OMP & CDX & DSH & OC & FAM
-    MGR & TE & MEM & BUS --> DB
-    DAQ <--> BR --> TSDB
-    DCW --> BR
-    DAQ & DCW --> BUS
-```
-**Agent × 机器之桥**（值得读源码的部分）：
-```
-agent ──绑定──▶ 节点 (daq: auto / dcw: manual)
-  │                    │
-  │  my_industrial_nodes  ◀── 语义卡：物理含义 · 单位 · 安全量程 · 配方窗口
-  │  daq_query             ◀── 时序库历史，统计 + 物理语义
-  │  dcw_control           ──▶ 联锁（安全量程 ∩ 配方窗口）
-  │                           ──▶ HITL 审批（manual 模式，180s 超时）
-  │                           ──▶ PLC 写入 → 回读校验 → ACK + 写历史
-  ◀── Agent 可引用数值的结果文本
-```
----
-## 快速开始
-### 前置条件
-```bash
-node -v   # ≥ 23.4.0（需要内置 node:sqlite）
-```
-> 真实 Agent harness 需要对应 CLI 在 PATH 中——`omp`、`codex`、`dsh`、`opencode`、`gemini`、`qwen`、`copilot`、`cursor`、`crush`、`goose`、`pi` 或 `hermes`（任选子集；同一 Channel 可混用）。`mock` 与 `claude`（SDK）**进程内运行**，无需 PATH 上的 CLI。仪表盘「执行引擎」面板以绿/灰状态点展示每个引擎的就绪度，未安装引擎可点击跳转官网安装页。可选数采基础设施（MQTT broker + TimescaleDB）在 Docker 可达时自动拉起（`docker compose up -d`）。
-### 方式 A —— 从 npm 安装（推荐）
-```bash
-npm install -g agentworkshop     # → `aw` / `agentworkshop` 进入 PATH
-aw start                         # → http://localhost:3001
-```
-发布出的包内含**预构建的生产产物**（`.output/`），所以 npm 安装后可直接启动——无需构建步骤，也无需构建工具。首次启动时一切初始化进配置根 **`~/.AgentWorkShop`**：默认 `config.yml`、自动生成含随机会话密钥的 `.env`、`runtime-settings.json`、docker-compose 种子、`prompts/`、`commands/`、`plugins/`（由 SDK 示例播种，**默认关闭**）与空的 `data/` 目录。全部运行数据（SQLite、JSON 仓库、备份、日志）也都落在配置根——配置与数据跟着安装走，与当前工作目录无关。
-不想全局安装、只想跑一次？
-```bash
-npx agentworkshop start          # 无需全局 npm 安装
-```
-> `npx` 同样会创建 `~/.AgentWorkShop`——不装全局并不等于在磁盘上不留任何痕迹。
-### 方式 B —— 源码运行
-```bash
-git clone https://github.com/kingdol666/AgentWorkShop.git && cd AgentWorkShop
-pnpm install
-pnpm dev          # → http://localhost:3000（端口取自 config.yml）
-```
-源码生产部署：
-```bash
-pnpm build        # nuxt build → .output/
-pnpm start        # 端口取自 config.yml → server.prod.port
-```
-> 在源码检出内，配置根是项目里的 **`.AgentWorkShop/`** 文件夹（运行时覆盖、数据、项目级指令），而 `config.yml` / `.env` 留在检出根，作为版本化的工厂默认值。
-### 版本更新
-```bash
-aw update                              # 检查 + 就地更新全局安装
-aw update --check                      # 只报告，不安装
-npm install -g agentworkshop@latest    # 手动等效
-```
-版本遵循 semver。每次 `aw start` 都会校验配置根，并把 `home` 之前的旧版 `data/` 布局迁移进来（以最新文件为准），因此数据可以跨版本存活。SQLite schema 迁移在服务端启动时执行。当前版本：**v0.7.54**——见[版本发布](https://github.com/kingdol666/AgentWorkShop/releases)。
-### 第一次「Agent × 产线」会话（约 2 分钟）
-1. **登录** —— 侧边栏注册（或 `POST /api/users/register`）。
-2. **搭产线** —— 「产线运营」→ 建产线，加数采节点（如 `daq-temp-tc`）与数控节点（如 `dcw-temp-sp`），建产品 + 配方，点**开跑**。实时值开始流动。
-3. **建团队** —— 「Agent 工作台」→ 选 lead + workers 后**部署（deploy）**进 Channel。
-4. **绑定节点** —— 打开 Agent 详情面板 → 绑定数采节点（*auto*）与数控节点（*manual* = 需您的批准）。
-5. **提交目标** —— 「分析最近 5 分钟熔体温度；若与 182 °C 偏差超过 1 °C，修正设定值（等我的批准）。」
-6. **审批** —— Agent 读取真实历史、计算均值、发起写请求 → 在 HITL 面板批准 → 看设定值变化，**目标**收口并给出数值报告。
----
-## 配置与 CLI —— 真正的配置驱动
-一个运行时，一个事实来源。**`config.yml`** 声明默认值；配置根内的 **`runtime-settings.json`** 承载运行时覆盖；环境变量与 CLI 参数在最上层。每个可编辑键在 `shared/config/schema.json` 中声明一次（类型、范围、枚举、实时/重启生效），**前端设置页与 CLI 消费同一份描述符**。
-```
-config.yml（默认值）  <  .AgentWorkShop/runtime-settings.json（运行时）  <  环境变量 / CLI 参数
-```
-配置根：全局安装（`npm i -g`）时为 **`~/.AgentWorkShop`**——无论在哪个目录运行 `aw`；源码检出时为项目内的 **`<repo>/.AgentWorkShop`**（`config.yml` / `.env` 留在检出根，作为版本化的工厂默认值）。`AW_HOME` 可重定向；`AW_MODE=home` 强制全局形态。
-### 设置持久化与热重载
-- **系统设置 → 运行配置**标签页按描述符渲染每个可编辑键——改服务端口、主题、API 超时、语言环境或审批闸门，点保存即可。
-- `live` 键立即生效（主题、标题、超时、审批闸门、数采采样节拍、时序查询桶宽……），经服务端事件流推送，**无需刷新、无需重启**。
-- `restart` 键（端口、主机）落盘持久化，在下一次以对应模式启动时生效（`aw dev` / `aw start`）。
-- 所有写入方共用一条通道：**设置页、CLI、服务端文件监听**最终都收敛到同一个设置文件——任何一端改，处处生效。
-示例——在线调节数采与查询节拍：
-```bash
-aw config set daq.sampling.defaultIntervalMs 2000   # 新节点每 2s 采样
-aw config set daq.sampling.minIntervalMs 500        # 节点级下限（create/patch 钳制）
-aw config set daq.query.defaultBucketMs 3000        # 时序查询缺省 3s 桶
-aw config set daq.query.minBucketMs 500             # 查询下限（samples/产线查询/Agent 工具共用）
-```
-注入 Agent 的工具描述会在每次装配时以当前配置值重新渲染——LLM 永远看到对自己 `daq_query` 调用真正生效的下限与缺省值。
-### `aw` CLI
-| 指令 | 作用 |
-|---|---|
-| `aw start · aw dev · aw build` | 生产服务 / 开发服务器 / 构建——端口取自有效配置；首次 `start` 构建一次 |
-| `aw stop` | 依单实例锁终止运行中的 aw 服务实例 |
-| `aw config list · get · set · unset · reset` | 读写运行时设置（schema 校验 + 原子写盘） |
-| `aw plugin list · create · enable · disable` | 跨三种作用域管理插件：查看、脚手架（默认 project 作用域；`--global` 为 user 作用域）、启停（写状态文件，运行中的服务约 1 秒热重载） |
-| `aw mcp` | 工业 MCP stdio 服务（38 个工具，覆盖平台 REST：产线、配方、DCW 写入、参数映射、数采、频道、团队、模型晋升、插件）——自动发现运行实例；`--doctor` 一次讲清发现/健康/鉴权，`--print-config` 直出可粘贴的 MCP 客户端配置 |
-| `aw home` | 查看/初始化配置根 `.AgentWorkShop` |
-| `aw init <dir>` | 脚手架一个可运行的新项目（含完整配置系统与 CLI） |
-| `aw register <路径\|URL\|npm:包名>` | 注册一条新指令——项目级或 `--global` 用户级 |
-| `aw update` | 对比 npm 远程最新版本，有新版就就地更新全局安装 |
-| `aw doctor` | 环境 + 项目健康检查（node、配置、端口、密钥） |
-| `aw status` | 运行态总览：模式、配置来源、运行中服务、指令表 |
-| `aw tui` | 终端工作台：频道/Agent 管理、任务下发、实时监控面板、HITL 作答（见 [`docs/tui.md`](./docs/tui.md) · [`tui/README.md`](./tui/README.md)） |
-| `aw version` | 打印 CLI/包版本（别名 `v`） |
-全局参数：`--help/-h` · `--version/-v` · `--json`（机器可读） · `--root <dir>` · `--debug`。
-退出码：**0** 成功 · **1** 运行时错误 · **2** 用法错误。带 `--json` 时，失败会以信封返回 `{ ok: false, error: 'unknown-command' \| 'no-project' \| 'usage' \| 'internal' \| … }`，自动化无需解析 stderr 即可分支。
-### 指令注册
-指令就是导出 `{ meta, run }` 的普通模块。把它放进扫描目录，下次调用即生效——无需任何登记清单，约定优于配置：
-| 作用域（高层级优先） | 目录 |
-|---|---|
-| 项目级 | `<检出>/.AgentWorkShop/commands/` |
-| 用户级 | `~/.AgentWorkShop/commands/` |
-| 内建 | 随 CLI 发布（`cli/commands/`） |
-`aw register <file|url|npm:pkg>` 把指令复制进对应作用域（`--global` 进用户级）；`aw help` 列出全部已注册指令。
-```js
-// ~/.AgentWorkShop/commands/hello.mjs
-export const meta = { name: 'hello', group: '自定义', summary: '问好', usage: 'aw hello [--name <n>]' }
-export async function run(argv, ctx) {
-  console.log(`你好 ${argv.flags.name ?? 'AW'} —— 模式: ${ctx.mode}`)
-}
-```
----
-## 工业栈详解
-### 数据采集（DAQ）
-- **六协议驱动**：Modbus TCP、Modbus RTU-over-TCP（串口网关）、OPC UA、MQTT、HTTP/REST，加 **serial-bridge 内置插件**（RS-232/485 直连：Modbus RTU 帧机 + ASCII 行协议，写侧带同址回读校验，附串口枚举/探针 API 与前端面板）——连接池、分类错误文案、逐驱动连接测试；驱动注册表接受插件注册任意新协议（协议自带自描述 meta 时，前端表单零改动）。
-- **逐节点边缘运行时**：独立采样节拍、下发节拍、节点级在飞互斥——一个慢驱动绝不拖累邻居。采样与查询的默认值/下限由 `daq.sampling.*`、`daq.query.*` live 设置驱动。
-- **管线**：驱动 → 队列（进程内 / MQTT，断连离线缓冲）→ 消费端乱序防御 → 三路分发：WS 实时直推（节拍门控）、TSDB 批量落库、设备孪生回写。
-- **鲁棒性**：TSDB 单 in-flight 写 + 有界重试，缓冲背压带丢弃计数，真实丢失指标随 `daq.controller` 帧暴露。
-- **告警**：配方级监控窗口，**2% 滞回 + 3 拍去抖**；alarm/offline 切换即时生效（安全优先）。
-- **查询默认按批次作用域**：`daq_query` 自动解析节点所属产线的**活动批次**，按该批次的 `run_id` + `recipe_id` 过滤——Agent 取证据时看到的永远是**当前正在跑的配方**，不会把上一轮配方的样本混进本轮判读。生效口径（`run=<id> 配方「名」(recipe_id)`）打印在结果表头，并在文末逐节点重申；这两个 id 可直接回传给 `daq_query` 或 `aml_dataset_build`。需要跨配方对比/历史复盘时传 `scope: 'all'`（或显式给 `recipe_id` / `run_id` / `product_id`）；产线未开跑则不做过滤，历史数据照常可查。
-### 写控制（DCW）
-- 工程量写入：`linear` 标定（scale/offset）PLC↔物理，**回读校验**（死区容差），ACK 状态 + 写历史。
-- **联锁**：产线运行时，活动配方的参数窗口对该节点**替代**全局安全量程。
-- **HITL**：`manual` 绑定挂起写入等用户批准（同 Agent+节点去重；批准时二次校验——权限在您点击批准那一刻重查）。
-### 配方与批次
-`产线 → 产品 → 配方 → 批次`。开跑逐节点应用配方参数（每次写都校验），逐线门控采集，每条样本打标 `line/product/recipe/run`——产品级数据隔离 + 五维查询（产线 × 产品 × 配方 × 时间 × 节点）。
-### AML —— 自动建模实验室
-这是闭环里的建模半边：`/aml` 用已打标的遥测构建**数据集**，把**训练作业**提交到 `uv` 托管的 Python 运行时，在**排行榜**上给各次运行排名，并且只有跨过配置的**门禁**（NRMSE、rollout NRMSE、验证/测试差距、最小行数与运行次数）才允许晋级。晋级后的模型按 id 引用，因此 MPC 或影子孪生控制器消费的是有版本号的产物，而不是含糊的「最新」。
-- Agent 通过 14 个工具做同样的事（`aml_dataset_build`、`aml_job_submit`、`aml_job_status`、`aml_leaderboard`、`aml_model_promote`、`aml_model_find`、`aml_training_plan_*`……）——提交一个目标，让团队去训练并汇报。
-- Python 运行时由 `uv` 自行引导进配置根内的 `./aml` 资产根；数据集/产物/元数据路径、磁盘配额、作业超时、并发与保留策略全部是**设置项**（`aml` 组共 16 项），而不是常量。
-- 治理默认保守：跨配方数据集除非显式允许否则拒绝，每个作业都有归属。
-- **混合孪生 × MPC 内核**：AML 同时承载**混合孪生**平面——`SceneContract` / `PhysicsModelManifest` / `TwinSnapshot` / `ObjectiveProfile` / `VirtualTrial` / `RecommendationCertificate`，底座是带**有界 PyTorch 残差**的灰箱物理主干，外加 UQ/OOD 筛查与全轨迹硬约束门禁。频道通过 `hybrid_twin` profile 显式启用，启用后会注入 12 个 profile 专属工具（`twin_provider_catalog`、`twin_scene_discover/compile/freeze`、`twin_physics_spec_draft/validate/compile`、`twin_scene_read`、`twin_snapshot_create`、`twin_trial_run`、`mpc_optimize`、`twin_gate_evaluate`）与通用工具 `twin_calibration_request`；试验按设计就是**虚拟**的（`candidateExecuted=false`），只有门禁与收益同时通过才签发推荐证书。服务端策略两档：`safe_small_step`(数据不足) 与 `precise_search`(模型过门禁)。计划与验收记录见 [`docs/aml-hybrid-twin-mpc-integration-plan.md`](./docs/aml-hybrid-twin-mpc-integration-plan.md)、[`docs/aml-hybrid-twin-implementation-acceptance.md`](./docs/aml-hybrid-twin-implementation-acceptance.md)。
-- **任意场景建模闭环**：闭环不绑定内置场景。绑定节点 → `twin_scene_discover` 带证据推断 control/state/disturbance/target/guard 语义 → `twin_scene_compile` 生成 `SceneContract` 草稿 → 您确认 → `twin_scene_freeze` 冻结（版本不可覆盖）→ `twin_physics_spec_draft` 起草骨架 PhysicsSpec（每个状态一条一阶弛豫方程，τ/增益为带先验盒的可校准参数）供您润色 → 校验/编译（白名单 AST，禁任意代码）→ `aml_job_submit { job_kind: 'hybrid_residual' }` **可不带代码**：内置参考训练器先做物理参数校准（stage A）、再拟合 3 成员有界残差集成（stage B）、最后报告 conformal q90 覆盖率（stage D）——校准后的 spec 回写，评估/预测/试验三侧同源。
-- **模型驱动孪生与持续校准**：`twin_trial_run` / `mpc_optimize` 可传 `model_id`——rollout 由训练出的 hybrid 模型驱动（校准后物理主干 + 残差集成 ONNX，`ModelBackedHybridProvider`），UQ 覆盖率与成员分歧来自训练工件；模型数据集与场景的产线/产品/配方不一致直接拒绝（`TWIN_MODEL_SCENE_MISMATCH`）。持续校准请求由 60s 定时 worker 消费，自动提交 `hybrid_residual` 重训**候选**；晋升仍走 HITL + Twin Gate（`AML_TWIN_WORKER_DISABLED=1` 可整体关闭）。
-- **双模式优化闭环**：随包附带两个频道模板——`chtpl-aml-training-default`（建模面：22 个工具，无产线写入、无 MPC）与 `chtpl-aml-optimization-default`（执行面：快照/试验/门禁/MPC/贝叶斯寻优，外加 `optimization_explore`——受治理微写，每笔设定值与响应回读配对落 `optimization_explorations` 台账）。两面按频道互斥注入；优化频道实例化时可选**探索**模式（治理小步，无需模型）或 **aml** 模式（必须给 `boundModelId`——过门禁的模型先绑定，执行面才解锁）。
-- **孪生 Provider 插件 SDK（热加载）**：工业场景的物理主干 / 场景包 / 目标 / 求解器经 `ctx.twin` 注册进 **Twin Provider Registry**（`registerPhysicsProvider` / `registerScenePack` / `registerObjectiveProfile` / `registerTrainingAdapter` / `registerSolverAdapter`，另有 `listProviders` / `getProviderHealth` / `resolveProvider` / `validateProvider` / `retireProvider` / `isRegistryAvailable`）。孪生工具按 `SceneContract.physicsProfileId` 解析 Provider（解析不到回退内置 `twin-injection-default`），**换场景不改工具与频道**；热重载按 **generation** 装载新代、排空旧代，试验与 MPC 持租约 ⇒ 在飞工作不被作废，`retireProvider` 等引用归零才下线。系统自带注塑 Provider 走的正是这套外部契约（`server/plugins-builtin/twin-injection-default/`），装法与其它插件同址、停用或热重载无需重启。清单字段与可运行示例见 [`docs/plugins.md`](./docs/plugins.md)「混合孪生 Provider 插件」，SDK 面见 [`docs/sdk.md`](./docs/sdk.md) §4.10。
----
-## 使用说明
-### 认证
-邮箱 + 密码登录签发 **bearer token**（每用户多 token，可单独吊销）。
-```bash
-# 注册
-curl -X POST http://localhost:3000/api/users/register \
-  -H 'content-type: application/json' \
-  -d '{"email":"you@example.com","password":"secret","name":"you"}'
-# 所有 workshop 调用
-curl http://localhost:3000/api/workshop/channels \
-  -H 'authorization: Bearer <token>'
-```
-### 产线级权限
-工业数据按**产线**三态管控，由管理员在内置「权限管理」页（`/permissions`，仅 admin 侧栏可见）维护：
-| 状态 | 数采节点 | 数控（写控）节点 | 可见性 |
-|---|---|---|---|
-| **无权**（普通用户默认） | 隐藏 | 隐藏 | 后端不返回该产线数据——产线运营/数采中心/数字孪生均不可见 |
-| **仅查看** | 只读 | ✕ | 产线可见、实时值可看，但不可写/不可下发/不可绑定设备 |
-| **可操控** | 读取 | 读取+写入 | 全量能力：设定值写入、任务下发、设备绑定 |
-- `admin` / `editor` 为运营角色，不受授权约束（全量全权）。
-- 普通用户**默认无权**——未授权前看不到任何产线数据。
-- 强制点在数据面：列表接口按授权过滤，写控/下发接口返回人类可读的 403，Agent↔节点绑定校验产线授权（数采需仅查看+，写控需可操控）。
-- 插件经 `ctx.permissions`（`lineMode` / `visibleLineIds` / `listGrants` / `setGrants`）获得同一能力面，并有 `permissions:changed` 生命周期钩子；SDK REST 客户端提供 `client.permissions.overview()` / `client.permissions.set(...)`。
-### 执行模式
-在任务描述中使用模式前缀（或在 composer UI 中选择）：
-| 模式 | 语义 | 配置 |
-|---|---|---|
-| `goal` | lead 分解 → worker 交付 → **lead 判定满意度**；不满足继续补发；满足收口父任务。 | `goalCriteria` |
-| `loop` | 固定间隔循环重放同一任务。 | `intervalMs`（默认 60000）、`maxIterations`（默认 ∞） |
-| `pipeline` | 有序阶段；阶段 N+1 消费阶段 N 产出。 | `stages: [{name, description, assigneeId?}]` |
-### 定时任务
-任意任务都可挂上**调度**，让频道在无人值守时也持续工作：
-| 维度 | 行为 |
-|---|---|
-| 模式 | `interval` —— 固定节拍（`intervalMs`，60s 下限）· `daily` —— 每日本地时间 `HH:MM` 定点一次 |
-| 管理 | `/workshop/schedules` 页面，或 `POST/PATCH /api/workshop/schedules` |
-| 护栏 | 忙等守卫（频道仍有在飞任务时本次触发顺延）、逐次运行历史带状态、**连续失败熔断**（`maxConsecutiveFailures`，异常调度自动停用） |
-| 典型用法 | 每日巡线（`daq_query` + 漂移摘要写入频道记忆）、周期性偏差检查 + 自动判定、每日 KPI 摘要 |
-```bash
-# 创建调度：每 30 分钟巡线一次
-curl -X POST http://localhost:3000/api/workshop/schedules \
-  -H 'authorization: Bearer <token>' -H 'content-type: application/json' \
-  -d '{"channelId":"<id>","name":"line-patrol","title":"巡线","description":"读取 1 号线全部数采节点,把漂移摘要写入频道记忆。","mode":"interval","intervalMs":1800000}'
-```
-### 四个入口
-| 入口 | 端点 | 面向 |
-|---|---|---|
-| **WS** | `/api/workshop/ws?channelId=…` | 仪表盘 / UI——AEP v1 信封，per-channel 单调 `seq`，5000 事件环形缓冲，`lastSeq` 续传，快照兜底。 |
-| **MCP** | 进程内服务，约 25 个工具 | Agent（omp host tools）——管理面 + 作业面工具，Channel 作用域。 |
-| **A2A** | `POST /api/workshop/a2a/:agentId/rpc` | 外部 Agent——JSON-RPC 2.0，`AgentCard` 在 `/card`，`tasks/sendSubscribe` SSE。 |
-| **REST** | `/api/workshop/**` | 人 / 脚本——完整管理面。 |
-### 任务状态机
-```
-SUBMITTED ─▶ ASSIGNED ─▶ WORKING ─▶ WAITING ─▶ COMPLETED
-    │            │           │           │
-    └────────────┴───────────┴──▶ CANCELED / FAILED ─▶（重试 ≤ 3 或取消）
-```
----
-## 端到端验证
-上面每一条论断，背后都有一个可复跑的套件。验收套件在**生产实例上、跑真实模拟产线协议**（Modbus TCP/RTU、OPC UA、MQTT、HTTP + MQTT/Timescale 管线），配真实引擎 CLI，断言落在数据库、事件流与 HTTP API 上——而不是 mock。2026-09-24 的两轮波次已归档：基础矩阵（约 **1100+ 条真实断言**，v0.7.45 生产构建、隔离 `AW_HOME`、真实浏览器）见 [`docs/audit/e2e-2026-09-24-full-coverage.md`](./docs/audit/e2e-2026-09-24-full-coverage.md)；补充功能波次（真实 **PLC 节点模拟器** + 注塑 AgentTeam 闭环、FIFO 多任务、定时任务、协作，合计约 **1400+ 条断言**）见 [`docs/audit/e2e-2026-09-24-all-features.md`](./docs/audit/e2e-2026-09-24-all-features.md)。
-| 套件 | 最新结果 | 覆盖 | 复现 |
-|---|---|---|---|
-| `real-injection-closed-loop.mjs` | **双 goal 全部 COMPLETED / 0 失败**（2026-09-24，真实 PLC 模拟器 + 真实 `omp` 团队） | 从模拟器供给注塑产线（11 个数控 + 14 个数采节点）→ 真实 AgentTeam(lead/分析/优化) → 受治理写入且**间隔 65.8s ≥ 60s 策略** → 数采复测 → `qualityOk`、判定 `keep` | `AW_BASE=<base> SIM_BASE=http://127.0.0.1:4010 AW_TOKEN=<token> node scripts/real-injection-closed-loop.mjs` |
-| `_run-real-injection-fifo-goals.mjs` | exit 0（2026-09-24） | **FIFO 根队列多任务串行**：GOAL-2 仅在 GOAL-1 收口后派发；角色门控切换；两次受治理写入间隔 65.04s；两条记录均判定；账本 4 条锚 | `AW_BASE=<base> SIM_BASE=… AW_TOKEN=<token> node scripts/_run-real-injection-fifo-goals.mjs` |
-| `e2e-plc-plugin-closedloop.mjs` | 核心 Stage A–D 全绿（2026-09-24） | PLC 模拟器 Modbus 16040 真实供给 → 数采交叉核对（AW 采样 197 vs 模拟器寄存器 197.37）→ HITL 闭环写 3 区（寄存器 40021/40023/40025 = 210，真实写穿）→ `dcw_judge` keep；插件段 E–H 需外部诊断服务，按约定显式 SKIP | `AW_BASE=<base> KB_BASE=http://127.0.0.1:8771 AW_E2E_USERS_DB=<home>/data/users.sqlite node scripts/e2e-plc-plugin-closedloop.mjs` |
-| `_dbg-schedule-e2e.mjs` | **35 / 0**（2026-09-24） | 定时任务：计划 CRUD + 参数校验、`next_run_at`、`scheduledCount`、忙等守卫 **409 CHANNEL_BUSY**、在途重复 **409 SCHEDULE_RUNNING**、取消对账（run FAILED + 失败计数）、**timer 到点自动触发**（`trigger_kind=timer`）、停用/启用状态机、删除后 404 | `SCHED_E2E_BASE=<base> node scripts/_dbg-schedule-e2e.mjs` |
-| `e2e-crash-cycle.mjs` | **5 / 5 阶段**（2026-09-24） | 常规执行 → 硬杀 → 持久化断言 → 重启 → 重投 → 自动恢复 → 消费缺口重投；每阶段独立进程 | `node scripts/e2e-crash-cycle.mjs --port 3300 --home .e2e-home-full` |
-| `e2e-full-closedloop.mjs` | **98 / 0**（2026-09-24，v0.7.45 生产构建） | 11 阶段：注册 → 产线/产品/配方建模 → 数采采样 → 帧管线 → 数控写入 + 回读 → 回退账本 → Agent 节点鉴权 → 桥越权边界 → 插件 → 数据根隔离 | `node scripts/e2e-full-closedloop.mjs <base>` |
-| 全协议矩阵（真实协议） | **46 / 0**（2026-09-24） | MQTT · Modbus TCP · Modbus RTU · OPC UA · HTTP——逐协议数采、受控下发 + 回读、配方窗联锁与真实 Agent 闭环 | `node scripts/_dbg-protocol-matrix.mjs` |
-| 生产 API 全链路 | 60 / 0（2026-09-24） | 跨重启持久化、模板 CRUD、任务 assign/complete/cancel/loop/pipeline、A2A + mailbox、WS 广播、MCP 端点、级联删除 | `AW_E2E_TOKEN=<token> node scripts/api-live-e2e.mjs` |
-| AgentTeam 群聊 + 原生 HITL | 112 通过 / 0 失败 / 1 阻塞（2026-09-24，真实 `omp`） | 群聊请求 → 可追踪作业；`omp` 原生 ask → HITL 审批 → 引擎带回执继续 | `node scripts/e2e-agentteam-chat.mjs --phase=all` |
-| 终端镜像 + 提示词组合 | **26 / 0** 与 **16 / 0**（2026-09-24，真实 `omp`） | 终端镜像帧、`input`/`abort`/`ui_response` 注入、原生 `ask` 往返；五段式 prompt 组合（场景 → 专长 → 记忆 → 手册 → 任务）在线上可观测 | `node scripts/test-terminal-e2e.mjs` · `node scripts/test-prompt-system.mjs` |
-| 真引擎协作 | 任务流真跑 **PASS**、`e2e-omp-workspace` **13 / 13**、群聊全真 **PASS**、多用户 HIL **PASS**（2026-09-24） | 真实 `omp` lead + worker：分解/派发/进度/成果/workspace 文件读取与卸载；多用户 HITL 可见性；多引擎团队 14/18（omp 与 dsh 全绿） | `npx tsx scripts/e2e-agentteam-task-flow-real.ts` · `npx tsx scripts/e2e-omp-workspace.ts` |
-| 前端验收 | 响应式门禁 **16 / 16** 页、抽屉交互 **10 / 10**（2026-09-24，真实 Chromium） | 全部产品页（含 3D 小镇）在门禁阈值下渲染通过；抽屉开合、滚动锁、路由跳转、零 pageerror | `node scripts/ui/verify-responsive.mjs --routes all` · `node scripts/ui/verify-nav.mjs` |
-| `_aw0746-stage12.mjs` | **10 / 0**（2026-09-25,全局安装的 **v0.7.49 打包系统**） | 健康门(version=0.7.49)→ 管理员登录/角色面 → 创建 Channel(真实 `omp` lead)→ 开群聊 → **真实 omp 群聊回复** → 系统监控可见 omp 子进程 | `AW_BASE=<base> node scripts/_aw0746-stage12.mjs` |
-| `_aw0746-stage34.mjs` | **13 / 0**（2026-09-25,v0.7.49 打包系统 + PLC 模拟器） | 模拟器建线（11 数控 + 14 数采）→ 产品/配方三元组 → 开跑后**样本逐条带 recipe_id/run_id** → `daq_query` **默认只取当前活动批次**（`scope=all` 可放开，实测 1 vs 4）→ 实例化 Hybrid Twin 模板（lead + 3 worker,注入孪生 6 件套 / 总 57 工具） | `AW_BASE=<base> node scripts/_aw0746-stage34.mjs` |
-| `_aw0746-stage6b-train-sweep.mjs` | 门禁**全绿**（2026-09-25,v0.7.46 打包系统,真实 torch 训练） | 1 s 拍格数据集（**1724 行 / 10 批次**）→ 内联 code 作业真实训练 → G1 单步 **0.0992**（≤0.10）/ G2 滚动 0.1092（≤0.25）/ G3 泛化 14.6%（≤20%）/ G4 行数与批次 → 模型注册并**晋升 production** | `AW_BASE=<base> AW_DATASET_ID=<ds> node scripts/_aw0746-stage6b-train-sweep.mjs` |
-| `_aw0746-stage7-twin.mjs` | **17 / 0**（2026-09-25,v0.7.49 打包系统,真实 DAQ + 真实模型） | 真实样本 → TwinSnapshot `fresh=true` → 65 组真实 VirtualTrial（12 条安全候选,`candidateExecuted=false`）→ 12 项推荐门禁 **write_eligible** → 门禁结论回写模型 `twinEligibility` → `mpc_optimize` 升档 **precise_search** → 全程 **0 DCW 写入** | `AW_BASE=<base> AW_REQUIRE_MODEL=1 node scripts/_aw0746-stage7-twin.mjs` |
-| `_aw0746-stage6c-jobsmoke.mjs` | **5 / 0**（2026-09-25,v0.7.49 打包系统） | AML 作业链路：内联 `code` 被接受（不再要求 `workspace/train.py`）→ 作业到终态 → 训练日志/ONNX 痕迹 → 实验与逐项门禁落库 | `AW_BASE=<base> node scripts/_aw0746-stage6c-jobsmoke.mjs` |
-| `_aw0748-failclosed-probe.mjs` | **7 / 0**（2026-09-25,v0.7.49 打包系统） | 硬约束**失败关闭**回归:auto_daq 按真实绑定取样建快照 → 可映射约束 `weight` 正常评估 → 不可映射的 `part_weight` 判不通过并给出明细（v0.7.47 会假通过）→ 空轨迹同样判不通过 | `AW_BASE=<base> node scripts/_aw0748-failclosed-probe.mjs` |
-| `_aw0748-mock-closedloop.mjs` | **13 / 0**（2026-09-25,v0.7.49 打包系统,进程内 `mock`,零额度） | 调度闭环回归:创建 mock Channel → 根任务被真实派发并收口 → `[mock:complex]` 强制委派出子任务 → 父任务汇总收口 → mock worker 就位后 [mock:complex] 委派子任务并汇总 → **第二个/第三个根任务同样被派发**（修复前:lead 空闲卸载后 `scheduler` 置空,后续根任务只落库、一直 SUBMITTED 直到 `ROOT_TIMEOUT`）→ mock 无 host tool 通道时工具桥显式拒绝 | `AW_BASE=<base> node scripts/_aw0748-mock-closedloop.mjs` |
-| 工业基准——integrated | **83 / 83 检查，硬门禁绿**（2026-09-21） | 五协议五产线基准：连通性、采样入 Timescale、受控下发、治理、Agent 闭环、工艺参数语义层 | `node bench/pipeline.mjs --profile integrated` |
-| 多场景闭环 | 4 场景 · 闭环达标（2026-09-21） | 注塑克重窗口寻优 · A²/O 污水排放达标 + 能耗最小化 · 连续退火质量窗与产能权衡 · BOPET 产线任务 | `node bench/scenarios.mjs --scenarios injection,wwtp,anneal` |
-| 产线权限 / 审计负向 | 21 / 21 + 9 / 9（2026-09-12） | 三态产线授权 + 人类可读 403、绑定主体校验、授权撤销收敛、无 token WS 零遥测 | `node scripts/_dbg-perms-e2e.mjs <base> <adminPass>` · `node scripts/_dbg-audit-neg-e2e.mjs <base> <adminPass>` |
-| 渲染回归 | 30 / 30（2026-09-12） | 数采表完整性（行数与 API 动态对齐）、WS 驱动行更新、筛选、详情页、3D 小镇 + 模型库、7 页 smoke、零 pageerror | `node scripts/_dbg-render-regression.mjs <base> <email> <pass>` |
-| AML 自动建模 | 25 / 0（2026-09-24，确定性训练器） | 数据集构建 → 跨配方拒绝 → 作业提交 → 门禁 → 晋级守卫 → 预测守卫 → 审计；`--real` 附加 uv/torch 真实运行时 | `node node_modules/tsx/dist/cli.mjs --tsconfig .nuxt/tsconfig.server.json scripts/e2e-aml.ts` |
-| 离线单元/属性套件 | 全绿 | AEP 事件索引（`test-events-index`）、LRU、数据根拆分（`test-data-root`）、日志洪泛、回退索引、插件加固、任务租约围栏（`test-task-lease-fencing`）、CLI 退出码（`test-cli-exit`）、SDK 能力面（`test-sdk-surface`） | `node scripts/test-<name>.mjs`（TS 套件经 tsx 运行） |
-历史上的 **v0.7.20** 验收基线——*156 断言、0 失败*——归档于 [`docs/audit/e2e-2026-09-07.md`](./docs/audit/e2e-2026-09-07.md)。性能探针：`scripts/_dbg-render-perf.mjs`。
----
-## 项目结构
-```
-AgentWorkShop/
-├── bin/ · cli/                 # aw CLI——指令注册表 · 内置指令 · 配置引擎接线
-├── app/                        # Nuxt 4 前端（srcDir）
-│   ├── pages/                  # / · /workshop · /workshop/agents · /workshop/teams
-│   │                           # /workshop/channel-templates · /workshop/schedules · /workshop/w/:id
-│   │                           # /town · /daq · /daq/:id · /dcw · /dcw/:id
-│   │                           # /aml · /operations · /monitor · /logs · /permissions
-│   │                           # /plugins · /users · /tokens · /settings
-│   ├── components/workshop/    # 时间线 · 泳道 · 任务板 · 记忆面板 · 3D 小镇
-│   └── stores/composables/     # Pinia + AEP 客户端
-├── server/
-│   ├── api/                    # REST + WS + A2A + MCP 路由
-│   ├── services/workshop/
-│   │   ├── runtime/            # manager · scheduler-loop · task-engine · memory · mailbox
-│   │   ├── agents/             # AgentInterface：14 个引擎（+ 工业工具）
-│   │   ├── daq/ dcw/ aml/      # 边缘运行时 · 驱动 · 队列 · 存储 · 建模实验室
-│   │   └── db/                 # node:sqlite 仓储层
-│   ├── mcp/                    # MCP 服务（25 个工具，进程内 workshop 面）
-│   ├── plugins-builtin/        # 随包发布的插件（serial-bridge · rag-bridge · diag-bridge · twin-injection-default）
-│   └── plugins/                # 运行时装配（单例）
-├── mcp/                        # aw mcp —— 零依赖 stdio MCP 网关（38 个工具，实例自动发现）
-├── sdk/                        # agentworkshop/sdk——插件上下文、钩子总线、REST 客户端、浏览器 SDK
-├── tui/                        # 终端工作台（aw tui）
-├── shared/
-│   └── config/                 # schema.json（113 个设置描述符）+ 引擎（合并/校验/持久化）+ 路径解析器
-├── config.yml                  # 工厂默认值（构建/启动时读取；版本号来自 package.json）
-├── .AgentWorkShop/             # 检出内的配置根——prompts（版本化）+ 运行时覆盖 · 数据 · 日志 · 指令（git 忽略）
-├── data/                       # 迁移前的旧版位置（自动迁移进配置根）
-└── scripts/                    # 启动器 · home 引导 · E2E · 验证套件
-```
-## 技术栈
-| 层 | 技术 |
-|---|---|
-| 框架 | [Nuxt 4](https://nuxt.com) + Nitro（WebSocket） |
-| UI | Vue 3.5 · Pinia · Ant Design Vue · UnoCSS · Three.js · ECharts |
-| 语言 | TypeScript 5.7 全栈；`shared/` 前后端共用 |
-| CLI | Node ESM CLI，可插拔指令注册表（`bin/aw.mjs`） |
-| 持久化 | `node:sqlite`（零原生依赖）+ FTS5 + 可选 `sqlite-vec`；时序用 TimescaleDB |
-| 校验 | `zod` —— 每个消息边界 |
-| 互操作 | `@modelcontextprotocol/sdk` · A2A（JSON-RPC 2.0）· AEP v1（自研 WS 协议） |
-| 现场总线 | `modbus-serial` · `node-opcua` · `mqtt` |
-## 开发指南
-```bash
-pnpm dev          # 开发服务（端口取自有效配置）
-pnpm cli …        # 仓库内使用 CLI：pnpm cli config list
-pnpm tui          # 终端工作台（连运行中的实例）
-pnpm build && pnpm start
-pnpm typecheck                            # 包装脚本：prepare → 剔除失效 volar 条目 → vue-tsc -b
-pnpm lint
-pnpm test:api-live                        # 针对运行中服务的 API 套件
-node scripts/e2e-full-closedloop.mjs      # 全链路闭环（需服务端运行中）
-node scripts/e2e-crash-cycle.mjs          # 硬杀 → 重启 → 重投（自带隔离实例管理）
-node scripts/test-sdk-surface.mjs         # SDK 导出面守卫
-```
-> 排障前先知道两条测试运行约定：（1）`pnpm typecheck` 走 [`scripts/typecheck.mjs`](./scripts/typecheck.mjs)，
-> 而不是裸 `nuxt typecheck`——Nuxt 4.5 仍会把 `vue-router/volar/sfc-route-blocks` 编译插件写进生成的
-> tsconfig，而 vue-router 4.6 已不再导出该子路径，裸 vue-tsc 在加载配置阶段就崩，类型检查其实一次都没跑；
-> （2）导入**真实路由 handler** 的 TS 套件（如 `scripts/e2e-memory-system.ts`）要走纯 node 路径
-> `node --experimental-transform-types --import ./scripts/_audit/ts-register-hook.mjs <suite>.ts`，
-> 该钩子把 Nuxt 的 `#imports` 虚拟模块映射到共享配置桩。
-文档站位于 `docs/site/`（VitePress），由 [`.github/workflows/deploy-docs.yml`](./.github/workflows/deploy-docs.yml) 部署到 GitHub Pages：
-```bash
-cd docs/site && npx vitepress dev        # 本地预览
-cd docs/site && npx vitepress build      # 生产构建 → .vitepress/dist
-```
-该工作流在构建前把 `docs/{cli,plugins,sdk}.md`（及其 `.en.md` 双语对照）同步进文档站，因此这些文件是单页指南的唯一事实来源。
-## 路线图
-| 能力 | 状态 |
-|---|---|
-| Channel 运行时、lead 编排、7 态任务引擎 | 已交付 |
-| 四入口：WS（AEP v1）· MCP · A2A · REST | 已交付 |
-| 持久记忆（FTS5 + 可选向量混合） | 已交付 |
-| 工业栈：数采 · 数控写控 · 产线/配方/批次 | 已交付 |
-| Agent ↔ 节点绑定 + HITL 审批 + 联锁 | 已交付 |
-| 3D 数字孪生小镇 · 产线运营 UI · 仪表盘 | 已交付 |
-| 全功能 live E2E（Agent 读写真实产线，23 项检查） | 已交付 |
-| 运行时配置系统：设置持久化 · 热重载 · 设置页 UI | 已交付 |
-| `aw` CLI：config · start/dev · init · register · doctor | 已交付 |
-| 多 Harness 注册表：omp · codex · dsh · opencode 子进程引擎 | 已交付 |
-| 六种现场协议：Modbus TCP · Modbus RTU-over-TCP · OPC UA · MQTT · HTTP + 内置 serial-bridge 串口插件（数采 + 数控双向） | 已交付 |
-| Harness 可用性探测 + 执行前引擎强校验（UI 禁选 + 409） | 已交付 |
-| Recipe 归因版本化 + 非破坏回退（界面 + Agent 工具） | 已交付 |
-| 配方链路优化闭环：recipe_trial 整批试验（不写版本）→ 进步才固化 → 统一回退（PLC 整批恢复） | 已交付 |
-| 频道绑定产线：全员只读日志/配方/状态 + 产线简报注入提示词 | 已交付 |
-| Agent 自查工具：line_context / ops_log / recipe_log / recipe_versions / dcw_journal | 已交付 |
-| 多 Harness 并行真实产线 live E2E（四引擎、一条产线） | 已交付 |
-| HITL 审批流经真实 OPC UA 写入验证 | 已交付 |
-| 双语文档（简体中文 / English，VitePress 语言切换） | 已交付 |
-| Channel 级 LLM provider/model 选择（取自实时 Harness 目录） | 已交付 |
-| 可配置数采/时序节拍（采样与查询的默认值 + 下限，live 热重载） | 已交付 |
-| 团队级插件开关（建队勾选 + 团队弹层，按 Channel 过滤工具注入） | 已交付 |
-| 插件热管理：`/plugins` 管理页 + `aw plugin list/enable/disable` | 已交付 |
-| 渲染性能专项（v0.7.27）：数采主线程阻塞 −90%、孪生 −69%，自适应画质回升最高档；`window.__townStats` 仪表化 | 已交付 |
-| 插件系统 v2：浏览器面板注入、插件级 settings/groups、插件 i18n、宿主运行时服务（`ctx.services`/`ctx.daq`/`ctx.omp`） | 已交付 |
-| Instrument Glass 材质层（v0.7.36）：三级半透明材质、通透感、高光边缘、弹簧动效、逐页路由转场 | 已交付 |
-| 实时管线优化：数采帧索引 O(n²)→O(n)、逐 Agent 增量事件索引、图表原地更新、按大小感知的 JSON 持久化 | 已交付 |
-| AML 自动建模实验室：数据集构建 · 作业编排（uv 托管 Python）· 排行榜 · 晋级门禁 · 14 个 Agent 工具 | 已交付 |
-| Claude Agent SDK 适配器——常驻会话、同轮 steer 与 `canUseTool` HITL | 已交付 |
-| 工艺参数语义映射：`param_control`/`param_read` 按工艺参数寻址、四层写入限界、调控闭环（`dcw_judge`/`dcw_rollback`） | 已交付 |
-| Channel 群聊：请求升级为可追踪作业；原生 HITL（`omp` ask → 审批 → 回执） | 已交付 |
-| 定时任务：`interval` / `daily` 双模式、逐次运行历史、忙等守卫 + 连续失败熔断 | 已交付 |
-| 根任务队列（FIFO、排队位次可见）+ 派发代与执行租约围栏 | 已交付 |
-| 监督看门狗 + Harness 连续性（`persistent`/`per_turn`、会话复用租约带重启原因） | 已交付 |
-| Channel 过程记忆：确定性事件契约、canonical root 摘要、持久 outbox + 补偿 worker | 已交付 |
-| 运行时可观测：`GET /api/system/monitor` 团队指标，每项带文档化回滚开关 | 已交付 |
-| 工业基准：integrated 档（83 项检查、硬门禁）+ 多场景闭环（注塑 / 污水 / 退火 / BOPET）+ 质量目标 optloop 寻优 | 已交付 |
-| 生产构建全覆盖验收波次矩阵（约 1100+ 条真实断言，2026-09-24） | 已交付 |
-| 孪生 Provider 插件 SDK：物理/场景/目标/训练/求解器 Provider 经 `ctx.twin` 热加载注册，按 generation 装载 + 租约排空，内置 Provider 走同一外部契约 | 已交付 |
-| 任意场景混合孪生建模闭环：场景发现 → 编译 → 冻结 → 物理 spec 起草/校验/编译 → 参考训练器作业（物理校准 + 残差集成 + conformal UQ）、模型驱动试验、持续校准 worker | 已交付 |
-| 双模式优化闭环：`aml-training` / `aml-optimization` 专属频道模板、互斥工具面、探索 ↔ 生产双模式、带回读配对的治理微写 | 已交付 |
-| 产线操作流水：`/operations` 单页 + 工作台控制台面板，九类操作时间线、结构化写控 diff、闭环阶段推断 | 已交付 |
-| 外部 MCP 网关：`aw mcp` stdio 服务（38 个工具）、实例自动发现、`mcp.enabled` 运行时门控 | 已交付 |
-| 可配置系统时区（`time.timeZone`，live 热生效）+ 配方参数级单步限幅 `stepLimit` + 配方 `description` 元字段 | 已交付 |
-| 生产硬化：TLS、MQTT 鉴权、OPC UA 签名+加密缺省、结构化审计日志 | 规划中 |
-| 边缘部署形态：独立 edge-agent + 中心 broker | 规划中 |
-| 报警外送（邮件/webhook）+ 确认工作流 | 规划中 |
-| CI 流水线（typecheck + lint + e2e）——文档部署已跑在 GitHub Actions 上 | 规划中 |
-| License：PolyForm Noncommercial 1.0.0（源码可得 · 禁止商用） | 已交付 |
-## 许可证
-AgentWorkShop 是独立项目，**不是 Anthropic 或任何 LLM 厂商的官方产品**。它通过公开接口与 Agent harness（如 `omp`）集成。
-**AgentWorkShop 为源码可得（source-available）软件，依据 [PolyForm Noncommercial 1.0.0](./LICENSE) 发布。**
-- **允许** —— 个人学习、科研、兴趣项目、教学，以及非商业组织（公益、教育、公共研究、政府机构）的使用。
-- **未经版权人事先书面许可不得商用** —— 任何**商业用途**：销售、付费服务、集成进商业产品、服务于经营活动的生产使用均未获授权。商用授权可向版权人申请。
-- **再分发时** 必须随附本协议条款与 `Required Notice` 版权声明行。
-商用授权联系：[GitHub @kingdol666](https://github.com/kingdol666) · kingdol6080@gmail.com
-<div align="center">
-<a href="https://star-history.com/#kingdol666/AgentWorkShop&Date">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=kingdol666/AgentWorkShop&type=Date&theme=dark" />
-    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=kingdol666/AgentWorkShop&type=Date" />
-    <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=kingdol666/AgentWorkShop&type=Date" width="80%" />
-  </picture>
-</a>
-</div>
----
-## 参与贡献
-欢迎提交 Issue 与 Pull Request。提 PR 之前请先：
-1. **先读你要改的那份契约**——扩展面见 [`docs/plugins.md`](./docs/plugins.md)，编程客户端见 [`docs/sdk.md`](./docs/sdk.md)，指令注册见 [`docs/cli.md`](./docs/cli.md)。
-2. **本地跑一遍门禁**：
-```bash
-pnpm typecheck                            # vue-tsc 覆盖 app + server + shared
-pnpm lint                                 # eslint 9，期望 0 warning
-node scripts/e2e-full-closedloop.mjs      # 全闭环 E2E，需要服务在跑
-node scripts/test-sdk-surface.mjs         # SDK 导出面不允许漂移
-node scripts/check-docs-sync.mjs          # docs/site 与 docs/*.md 保持同步
-```
-3. **提交信息走约定式**——`commit-msg` 钩子跑 `commitlint`（`feat:` / `fix:` / `docs:` / `refactor:` / `perf:` / `test:` / `chore:`），`lint-staged` 会在提交时自动修复暂存的 JS/TS/Vue。
-4. **改了行为就补测试。** 本仓库以 `scripts/` 下的**真实 E2E 脚本**为主，而不是 mock——一条新的工业链路应该能被证明可跑通。
-> [!TIP]
-> 报 bug 之前先跑 `aw doctor`：它会端到端体检环境（Node 版本、配置根、端口占用、SQLite、可选的 Docker 服务），大多数「起不来」在这一步就有答案。
-## 安全
-发现漏洞请**不要**开公开 Issue，而应通过 [GitHub Security Advisories](https://github.com/kingdol666/AgentWorkShop/security/advisories/new) 私下报告，并附上复现步骤与受影响版本。
-当你把 AgentWorkShop 指向真实设备时，它就在驱动真实设备：接入现场 PLC 之前，请先复核 `config.yml` 里的联锁、安全量程与 HITL 设置。默认姿态是建议性的——写操作要过联锁、要经审批、要回读校验——但产线侧逻辑始终拥有最终否决权。
----
-<div align="center">
-**如果这个项目对你有用，点一个 ⭐ 能让更多人找到它。**
-<a href="https://star-history.com/#kingdol666/AgentWorkShop&Date">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=kingdol666/AgentWorkShop&type=Date&theme=dark" />
-    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=kingdol666/AgentWorkShop&type=Date" />
-    <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=kingdol666/AgentWorkShop&type=Date" width="80%" />
-  </picture>
-</a>
-<br />
-**[在线文档](https://kingdol666.github.io/AgentWorkShop)** · **[上手指南](https://kingdol666.github.io/AgentWorkShop/guide/getting-started)** · **[插件 API](./docs/plugins.md)** · **[SDK](./docs/sdk.md)** · **[CLI](./docs/cli.md)** · **[English](./README.md)**
-<sub>基于 Nuxt 4 · Vue 3 · TypeScript · <code>node:sqlite</code> 构建 —— 监督层，秒级软实时。<br />
-时序关键回路请留在 PLC 内。</sub>
-</div>
+<div align="center">
+<img src="https://raw.githubusercontent.com/kingdol666/AgentWorkShop/main/docs/readme-assets/hero.png" alt="AgentWorkShop —— 让 Agent 团队运行真实产线" width="100%" />
+<br />
+# AgentWorkShop
+**AI Agent 团队与产线在此交汇。**
+[![npm version](https://img.shields.io/npm/v/agentworkshop?logo=npm&logoColor=white&label=npm&color=CB3837)](https://github.com/kingdol666/AgentWorkShop)
+[![npm downloads](https://img.shields.io/npm/dm/agentworkshop?logo=npm&logoColor=white&label=downloads&color=CB3837)](https://github.com/kingdol666/AgentWorkShop)
+[![GitHub release](https://img.shields.io/github/v/release/kingdol666/AgentWorkShop?logo=github&label=release&color=35e0a0)](https://github.com/kingdol666/AgentWorkShop/releases)
+[![Stars](https://img.shields.io/github/stars/kingdol666/AgentWorkShop?logo=github&label=stars&color=35e0a0)](https://github.com/kingdol666/AgentWorkShop/stargazers)
+[![Last commit](https://img.shields.io/github/last-commit/kingdol666/AgentWorkShop?logo=git&logoColor=white&label=last%20commit)](https://github.com/kingdol666/AgentWorkShop/commits)
+[![Issues](https://img.shields.io/github/issues/kingdol666/AgentWorkShop?logo=github&label=issues)](https://github.com/kingdol666/AgentWorkShop/issues)
+[![License](https://img.shields.io/badge/license-Apache%202.0-8A2BE2?logo=apache&logoColor=white)](./LICENSE)
+[![Nuxt 4](https://img.shields.io/badge/Nuxt-4-00DC82?logo=nuxt&logoColor=white)](https://nuxt.com)
+[![Vue 3.5](https://img.shields.io/badge/Vue-3.5-42B883?logo=vuedotjs&logoColor=white)](https://vuejs.org)
+[![TypeScript 5.7](https://img.shields.io/badge/TypeScript-5.7-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org)
+[![Node ≥ 23.4](https://img.shields.io/badge/Node.js-%E2%89%A5%2023.4-3C873A?logo=nodedotjs&logoColor=white)](https://nodejs.org)
+[![SQLite node:sqlite](https://img.shields.io/badge/SQLite-node%3Asqlite-003B57?logo=sqlite&logoColor=white)](https://nodejs.org/api/sqlite.html)
+[![Modbus · OPC UA · MQTT · HTTP](https://img.shields.io/badge/%E7%8E%B0%E5%9C%BA%E6%80%BB%E7%BA%BF-Modbus%20%C2%B7%20OPC%20UA%20%C2%B7%20MQTT%20%C2%B7%20HTTP-41c8f4?logo=siemens&logoColor=white)](./docs/site/guide/daq-protocols.md)
+[![Plugins](https://img.shields.io/badge/%E6%8F%92%E4%BB%B6-%E7%83%AD%E9%87%8D%E8%BD%BD-8b5cf6?logo=puzzle&logoColor=white)](./docs/plugins.md)
+[![Docs](https://img.shields.io/badge/%E6%96%87%E6%A1%A3-VitePress%20%C2%B7%20%E4%B8%AD%2FEN-ffd75e?logo=vitepress&logoColor=black)](https://kingdol666.github.io/AgentWorkShop)
+[![PRs welcome](https://img.shields.io/badge/PRs-welcome-ff69b4?logo=git&logoColor=white)](https://github.com/kingdol666/AgentWorkShop/pulls)
+**[English](./README.md)** · **[在线文档](https://kingdol666.github.io/AgentWorkShop)** · **[版本发布](https://github.com/kingdol666/AgentWorkShop/releases)** · **[更新日志](./changelog.md)** · **[插件 API](./docs/plugins.md)** · **[SDK](./docs/sdk.md)**
+<sub><b>v0.7.58</b> · 14 个执行引擎 · 6 种现场协议（5 内置 + 串口插件）+ MES REST 集成 · 118 个运行时设置项 · 双语文档（简体中文 / English）</sub>
+<br />
+*一个配置驱动的平台：**AI Agent 团队**与**工业数字孪生**共享同一运行时——Agent 查询真实遥测、经人工审批的写控回路下发监督设定值，每个事件实时推送到 3D 孪生。*
+</div>
+> [!IMPORTANT]
+> **定位声明：监督层。** AgentWorkShop 是面向产线管理、数字孪生、数采与 Agent 编排的**监督层**（SCADA 同位）平台，运行在**秒级软实时**档位。
+> 它**不是**硬实时控制器：任何时序关键回路（**< 10 ms**、联锁、安全、伺服）**必须在 PLC 内实现**。本平台下发的设定值均为建议性——产线侧逻辑可否决。
+---
+<table>
+<tr>
+<td width="33%" valign="top">
+**图例索引**
+`图 01` 闭环全流程<br/>
+`图 02` 数采中心<br/>
+`图 03` 产线运营<br/>
+`图 04` 数字孪生<br/>
+`图 05` 仪表盘<br/>
+`图 06` 自适应布局
+</td>
+<td width="33%" valign="top">
+**快速跳转**
+[这是什么？](#这是什么) · [特性总览](#特性总览)<br/>
+[界面一览](#界面一览) · [设计架构](#设计架构)<br/>
+[快速开始](#快速开始) · [配置与 CLI](#配置与-cli--真正的配置驱动)<br/>
+[工业栈详解](#工业栈详解) · [使用说明](#使用说明)<br/>
+[端到端验证](#端到端验证) · [项目结构](#项目结构)<br/>
+[技术栈](#技术栈) · [开发指南](#开发指南)<br/>
+[路线图](#路线图) · [许可证](#许可证)
+</td>
+<td width="33%" valign="top">
+**一眼看懂**
+监督层，秒级软实时<br/>
+14 个执行引擎 · 4 个接入入口<br/>
+6 种现场协议（5 内置 + 串口插件，读 + 写）<br/>
+7 状态任务机 · 根任务队列 + 执行租约<br/>
+群聊作业 · 定时任务 · HITL 审批<br/>
+FTS5 + 向量记忆 · 插件热重载<br/>
+SDK · CLI · TUI · 外部 MCP · 约 1100+ 条验收断言
+</td>
+</tr>
+</table>
+---
+## 文档
+文档为双语——[VitePress 站点](https://kingdol666.github.io/AgentWorkShop) 在全站范围内提供语言切换（简体中文 / English）。深度页面同样随仓库发布，CLI 会把它们复制进发布的 tarball：
+| 主题 | 在线 | 仓库内 | 内容 |
+|---|---|---|---|
+| **上手指南** | [指南](https://kingdol666.github.io/AgentWorkShop/guide/getting-started) | `docs/site/guide/` | 安装 → 首次运行 → 第一次「Agent × 产线」会话、配置系统、数采协议、数控读写、HITL、配方版本、多 Harness 团队、产线权限、AML |
+| **插件开发** | [插件指南](https://kingdol666.github.io/AgentWorkShop/plugins/) | [`docs/plugins.md`](./docs/plugins.md) | 完整扩展契约：三种作用域、`index.mjs` 清单、`ctx` 服务端/浏览器能力面、`settings`/`groups` 声明、生命周期事件、i18n、面板、团队级开关、一个真实案例 |
+| **SDK** | [SDK 指南](https://kingdol666.github.io/AgentWorkShop/sdk/) | [`docs/sdk.md`](./docs/sdk.md) | `agentworkshop/sdk` 作为编程客户端（带信封处理的平台 REST 客户端）与插件扩展基座；TypeScript 类型；浏览器端 SDK |
+| **CLI** | [CLI 手册](https://kingdol666.github.io/AgentWorkShop/cli/) | [`docs/cli.md`](./docs/cli.md) | 全部 15 个 `aw` 指令、全局选项、退出码、双模式路径模型、指令注册系统、维护者发布指引 |
+| **AML** | [AML 指南](https://kingdol666.github.io/AgentWorkShop/guide/aml) | [`docs/aml.md`](./docs/aml.md) | 自动建模实验室：数据集构建、作业编排、模型注册表、晋级门禁、Agent 工具 |
+| **TUI** | — | [`docs/tui.md`](./docs/tui.md) · [`tui/README.md`](./tui/README.md) | 终端工作台：频道、Agent、任务、实时监控、HITL 应答 |
+| **多 Harness 架构** | — | [`docs/multi-harness-architecture.md`](./docs/multi-harness-architecture.md) | 引擎分类、归一化会话契约、供应商/模型目录、失败模式 |
+---
+## 这是什么？
+AgentWorkShop 起家于**多智能体软件工作坊**——Channel 内的编码 Agent 团队，配备 lead 调度器、7 状态任务机、持久记忆，以及四个互操作入口（WebSocket / MCP / A2A / REST）。
+随后它长出了**工业半边**：完整的数采与写控栈（Modbus TCP / OPC UA）、带配方与批次运行的产线、3D 数字孪生小镇、一个**自动建模实验室**（数据集 → 训练作业 → 排行榜 → 门禁晋级）——以及让它独一无二的桥：**Agent 可被授予对真实工业节点的访问权——绑定到具体节点、按权限作用域收窄**，带着物理语义查询其实时遥测，并经「联锁 → 人工审批 → 回读校验」管线驱动写操作。
+它同时**天生可扩展**：一个自包含插件可以同时增强服务端（钩子、路由、Agent 工具、数采驱动、配置分组）与浏览器（面板、i18n），而同样的能力面也通过 SDK 开放给普通程序——见 [`docs/plugins.md`](./docs/plugins.md) 与 [`docs/sdk.md`](./docs/sdk.md)。
+最终效果：提交一个目标，比如「分析熔体温度趋势并优化设定值」——Agent 团队读取真实传感器历史、计算统计量、提议新设定值、在 HITL 面板等您批准、写入 PLC、校验回读、带着数值汇报。**端到端，自动化 E2E 已验证。**
+<div align="center">
+### 图 01 — 闭环全流程
+<img src="https://raw.githubusercontent.com/kingdol666/AgentWorkShop/main/docs/readme-assets/fig-01-closedloop.gif" alt="Agent 团队读取实时遥测、提议设定值、等待审批、写入 PLC 并校验回读" width="88%" />
+<sub><b>目标 → 读取 → 计算 → 审批 → 写控 → 回读 → 汇报。</b><br/>
+录制自运行中的实例：真实数采历史、真实写控、真实 HITL 审批。</sub>
+</div>
+> [!NOTE]
+> 本 README 中的每一张图都是**运行中实例**的录屏或截图，没有一张是效果图。屏幕上的数字来自流经产品同一套代码路径的工业数据。
+<div align="center">
+### 🎬 实机演示（4 分 11 秒，英文配音 + 字幕）
+<a href="https://github.com/kingdol666/AgentWorkShop/blob/main/docs/site/public/demo/agentworkshop-demo.mp4"><img src="docs/site/public/demo/poster.jpg" alt="AgentWorkShop 实机演示：数采中心、写控下发回读、串口插件、Agent 团队执行、闭环趋势与 3D 数字孪生" width="86%" /></a>
+<sub><b>点击封面观看完整演示。</b>真实 PLC 模拟器 + 真实串口枚举 + 真实 Agent 团队执行，全程无剪辑造假。<br/>场景：仪表盘 → 数采中心（实时） → 写控下发与回读 → 串口协议插件 → Agent 团队执行 → 闭环趋势 → 3D 数字孪生。</sub>
+</div>
+---
+## 特性总览
+#### Agent 团队运行时
+| 能力 | 为何重要 |
+|---|---|
+| **Lead 编排** | 每个 Channel 一名 lead：分解目标、派发空闲 worker、失败重派、判定目标满足度。LLM 决策 + 确定性规则引擎兜底——系统永不停滞。 |
+| **三种执行模式** | `goal`（满意度判定）· `loop`（定间隔重放）· `pipeline`（顺序阶段）。7 状态任务机带进度、产物与完整历史。 |
+| **Harness 无关** | 一个 `AgentInterface`，**14 个引擎**分三类传输形态：**进程内**——`mock`（无 LLM）、`claude`（Claude Agent SDK，常驻会话，同轮 steer）；**经协议常驻会话**——`omp`（RPC 子进程）、`codex`（app-server JSON-RPC）、`dsh` / `qwen` / `hermes`（ACP）、`opencode`（serve + HTTP/SSE）；**带结构化事件流的无头 CLI**——`gemini`（stream-json）、`copilot`（JSONL）、`cursor`（stream-json）、`crush`（非交互运行）、`goose`（stream-json）、`pi`（`-p --mode json`）。平台永远不知道跑的是哪个。 |
+| **Channel 级 LLM 选择** | 每个 Channel 从 Harness 实时目录中选 **harness → provider → model（+effort）**（如 omp 的 `zhipu-coding-plan/glm-5.3-flash`）。成员未显式覆盖即继承——一个团队混用多种 harness 是一等公民设定，不是绕行。 |
+| **Harness 可用性检查** | `GET /api/workshop/harnesses` 逐引擎探测 PATH 上的 CLI。前端禁用未安装项，且每个入口在执行前都做强校验。 |
+| **停滞安全的监督与任务治理** | 提交的目标进入 **FIFO 根任务队列**，排队位次可见。排队根**等待期间不消耗执行预算**——预算从入场起算，并有确定性的 **lead 救援扫**兜底（lead 运行时失活/任务卡排队时自动卸载重组并重新派发，不等人工察觉）。**监督看门狗**区分「卡死」与「慢」——Agent 工具调用被当作活性信号，健康的长工业作业不会被误回收，真停滞仍会呈报 lead。每次派发携带**派发代 + 执行租约**，被取代 worker 的迟到事件在准入层直接丢弃，而不是寄希望于事后对账。 |
+| **Harness 连续性** | 每个引擎声明连续性形态（`persistent` / `per_turn`）；常驻会话在连续性租约下跨轮复用（pid / 会话 / 复用计数 / 最近重启原因），服务重启能恢复的恢复，而不是悄悄重新拉起。 |
+| **Channel 群聊与原生 HITL** | 频道时间线是真正的群聊：成员请求升级为**可追踪作业**（不是一条会丢的消息）；带原生 ask 能力的引擎（如 `omp`）把 HITL 提问路由进平台——您批准一次，引擎带着回执继续跑。成员权限与用户通知是一等公民。 |
+| **定时任务** | 任意 Channel 任务可挂上**调度**——固定 `interval`（60s 下限）或 `daily` 每日定点——在 `/workshop/schedules` 页或 REST API 管理，带逐次运行历史、忙等守卫（频道仍有在飞任务时触发顺延）与 Channel 级可见性。 |
+| **持久记忆与频道过程记忆** | 私有 + Channel 共享双域；FTS5 CJK 切分，可选向量混合检索，token 预算注入。其上是**过程记忆**：确定性的 root/child/lead 事件名契约、canonical root 摘要、持久 outbox（死信 + 补偿 worker），让一个目标的来龙去脉跨重启存活。 |
+| **四个入口** | 一个 manager 坐在每扇门后：**WS**（AEP v1 事件流，seq 续传）、**MCP**（约 25 个进程内工具）、**A2A**（JSON-RPC 2.0 + AgentCard）、**REST**。 |
+#### 工业栈
+| 能力 | 为何重要 |
+|---|---|
+| **六协议现场总线** | Modbus TCP、Modbus RTU-over-TCP（串口网关）、OPC UA、MQTT、HTTP/REST，外加**内置串口插件**（RS-232/485 直连：Modbus RTU + ASCII 行）——数采**与**写控双驱动带连接池、分类错误文案与逐驱动连接测试；`mock` 覆盖演示/CI；协议即插件：`ctx.daq.registerDriver` / `ctx.dcw.registerWriteDriver` 注入后，前端协议下拉与参数表单即插即现（带 ⌁ 徽标）。 |
+| **Agent 团队 × 工业作用域** | 把 Agent 绑定到数采/数控节点。Agent 看到的是语义卡（物理含义、单位、安全量程、配方窗口）——而不是裸寄存器。 |
+| **人工审批的写控** | 数控下发经过「**安全量程 ∩ 活动配方窗口**」联锁 → 可选 **HITL 审批** → PLC 写入 → **回读校验** → 带签名的写历史。 |
+| **数控读写通道** | 每个控制节点都能沿**写入时所用的同一条标定链路**读回 PLC 当前值：周期读 + 按需读 + Agent 读取，SET 与 ACT 并排呈现——读是被动观测，永不被写联锁阻断。 |
+| **Recipe 版本化治理** | 参数修改按版本入史（归因 用户/Agent/系统 + 操作者 + 原因）。可非破坏地回退到任意修订版或最近一次良好批次。失效节点参数跳过并明确标识。 |
+| **配方链路优化闭环** | Agent 像人类工艺员一样通过配方管理做优化：`recipe_trial` 把多参数候选**整批试验（不写版本）**→ 复测 → 有进步用 `recipe_update` 固化（同一配方 id，版本+1）→ 劣化触发**统一回退**（`recipe_rollback` 带 `dispatch:true` = 定义回退 + PLC 整批恢复）。单参数直调移出闭环；试验受四层限界与同线节拍卡控。 |
+| **频道绑定产线（只读授权）** | 频道可绑定一条产线：全员无需节点绑定即可读取该线的运维日志、配方历史与实时状态（工具回执标注「频道绑定，只读」），写操作仍需节点授权。产线简报自动注入成员提示词；换绑即时回收成员运行时。 |
+| **工艺参数语义映射与调控闭环** | Agent 用工程语义思考：`param_control(param, value)` 按**工艺参数**寻址（跨批次/换配方语义稳定），`param_read` 读回 PLC 当前值取证。每次写入被**四层限界**逐层收窄——节点安全量程 ∩ 工艺参数基准限界 ∩ 活动产品限界 ∩ 活动配方工艺窗口——且每次下发自动开一条调控记录，由 `dcw_judge` 落判定（keep / rollback / uncertain），`dcw_rollback` 执行回退。 |
+| **产线运营** | 产线 → 产品 → 配方 → 批次。配方窗口门控采集并联锁写入；每条样本打标 `product/recipe/run`，实现按批次隔离。 |
+| **多形态数采帧管线** | 多点轮廓（测厚仪/扫描仪）与 CCD 图像帧流经模板 sink 管线：向量与元数据入 Timescale（`daq_frames`），像素入对象存储（MinIO，不可达时自动降级到本地磁盘）；派生指标阈值越限走既有告警链路。 |
+| **生产化硬化（v0.7.58）** | 保写心跳生命周期根治——失败写不占位（心跳不再直发幻影指令值）、驱动/连接/产线变更即清值、停线自动挂起保写；mock 静默兜底封堵（未知协议显式报错，插件卸载不再假成功）；帧像素 sha256 完整性指纹 + 对象存储按天 GC（删前 DB 交叉校验防误删）；Timescale 按天 chunk + 列存压缩（TSL）；堆水位监控 + 崩溃/失联/水位三重自动重生；写保持窗与试验节拍落盘（重启不绕频控）；grant 运行时复核并入频道绑线（撤权即失活无死角）。 |
+| **Agent 自查工具** | `line_context`、`ops_log`、`recipe_log`、`recipe_versions`、`dcw_journal`——Agent 清楚自己操控的产线/产品/配方，谁做过什么，每个值怎么变。 |
+#### 治理、配置与扩展
+| 能力 | 为何重要 |
+|---|---|
+| **产线级权限** | 工业数据按**产线**三态门控（无权/仅查看/可操控），强制点在数据面——普通用户未授权前看不到任何产线数据。 |
+| **全操作审计日志** | 用户 / Agent / 系统 的每个动作都落进同一份可检索日志；操作者归属「Channel名/成员名」，与用户和系统天然区分。经 WS 实时推送。 |
+| **团队级插件开关** | 每个团队（Channel）持有**独立插件开关组**（`channel_plugins`）：被关闭插件的工具不注入该团队 Agent。插件本体经 `aw plugin` 与 `/plugins` 页热管理。 |
+| **插件扩展 API** | `plugins/<name>/` 下的一个自包含目录**同时增强两半**：`index.mjs`（服务端：钩子、路由、Agent 工具、**数采读驱动 / DCW 写驱动**/帧处理器/节点模板、配置分组、KV、定时器）与 `client.mjs`（浏览器：注入具名插槽的面板、i18n、设置 UI）。三种作用域——`builtin`（随包发布）> `project`（检出）> `user`（`~/.AgentWorkShop`）——启停**与代码修改**均有约 1 秒热重载；停用插件的驱动随热重载立即摘除。内置示例 **serial-bridge**（串口通信：读/写驱动 + 串口探针 API + 前端面板）。完整契约见 [`docs/plugins.md`](./docs/plugins.md)。 |
+| **AML —— 自动建模实验室** | 数据集构建 → 训练作业 → 排行榜 → 晋级门禁 → 模型引用，全部可在 `/aml` 页驱动，也可由 Agent 通过 **14 个 `aml_*` 工具**驱动。Python 运行时由 `uv` 引导至配置根内的 `aml/` 资产根；产物与元数据都留在配置根下。模型带人读身份——label（产线 · 配方 · 目标）、description 与产线/目标 id——可用 `aml_model_find` 按场景选型。 |
+| **AML 混合孪生 × MPC** | 灰箱物理主干 + 有界 PyTorch 残差；`TwinSnapshot` / `VirtualTrial` / `RecommendationCertificate` 配 UQ/OOD 筛查与全轨迹门禁；`hybrid_twin` profile 会额外注入 **12 个 profile 工具**（场景发现/编译/冻结、物理 spec 起草/校验/编译、快照、试验、MPC、门禁、Provider 目录）与通用工具 `twin_calibration_request`。试验按设计保持虚拟（`candidateExecuted=false`），证书签发前只做推荐、不落真实写入。 |
+| **双模式优化闭环** | 专属频道模板把闭环**结构性拆开**：*aml-training* 频道拿建模面（数据集、作业、场景编译、物理 spec、建模任务——无产线写入、无 MPC），*aml-optimization* 频道拿执行面（快照、试验、门禁、MPC、贝叶斯寻优 `twin_bayes_optimize`、受治理微写 `optimization_explore`）——边训边优在结构上不可能。**探索**模式走治理链写入并做响应回读配对（每笔写入落 `optimization_explorations` 台账）；**生产**模式要求绑定过门禁的模型（`aml` 模式，实例化时给 `boundModelId`）。 |
+| **运行时可观测** | `GET /api/system/monitor` 把 Agent 团队内部暴露成数字：根队列深度、看门狗介入次数、Harness 会话复用、记忆 outbox 积压——每项都有对应的文档化回退开关，新机制可以不重新部署就关掉。 |
+| **产线操作单页（`/operations`）** | 一页看全对产线的每一次触碰：实时操作流水（REST 快照 + WS 推流）把写控、数采、建模、配方、回退、报警、产线、人工、系统动作归入**九类分类**，写控行渲染结构化 **前值 → 后值 diff 徽章**（失败标红），并直接从事件流推断**闭环阶段**（监视 → 探索·小步 → 推荐搜索 → 影子验证 → 生产）。同一数据面也供工作台控制台的「产线作业」面板使用。 |
+| **外部 MCP 网关** | `aw mcp` 启动零依赖的 **stdio MCP 服务**（38 个工具），自动发现运行中的实例（环境变量 → 锁文件 → 配置文件），把产线、配方（含 mark-good）、受治理 DCW 写入、工艺参数语义映射、数采查询、频道、团队供给、模型晋升、判卷/回退与插件管理暴露给任意 MCP 客户端——受 `mcp.enabled` 运行时设置门控，附 `--doctor` 与 `--print-config` 辅助指令。 |
+| **全量配置驱动运行时** | 全部运行旋钮（记忆预算、上下文压缩、回退护栏、保留策略、备份、日志级别、系统时区、MCP 开关…）在设置描述符注册表声明一次，优先级 **config.yml < runtime-settings < env**——**118 个设置项、18 组**（40 live / 78 restart），代码零硬编码默认。 |
+| **可配置系统时区** | 一个 `time.timeZone` 设置项（IANA 时区，live 热生效）统一驱动人读时间——日志、聊天、审计、Agent 记录与定时任务；机器时间轴（数采样本、`timestamptz`）仍保存绝对时间。 |
+| **可配置节拍** | 采样与查询的默认值/下限全部是 **live 设置**（`daq.sampling.*`、`daq.query.*`）：热重载、create/patch 时钳制，Agent 工具描述实时携带当前值。 |
+#### 数字孪生
+| 能力 | 为何重要 |
+|---|---|
+| **3D 数字孪生** | Three.js 小镇：放置产线设备与 Channel 领地，实时查看设备健康、告警与数值——由同一事件总线驱动。自适应画质阶梯（DPR / 阴影 / Bloom 分档 + 墙钟 FPS 预算）自动匹配机器，`window.__townStats` 暴露真实渲染指标供性能探针使用。 |
+---
+## 界面一览
+下面每一屏都是真实界面，1440×900，录制自正在运行的实例。
+<div align="center">
+### 图 01 — 闭环全流程
+<img src="https://raw.githubusercontent.com/kingdol666/AgentWorkShop/main/docs/readme-assets/fig-01-closedloop.gif" alt="Agent 团队读取实时遥测、提议设定值、等待审批、写入 PLC 并校验回读" width="88%" />
+<sub><b>目标 → 读取 → 计算 → 审批 → 写控 → 回读 → 汇报。</b><br/>
+录制自运行中的实例：真实数采历史、真实写控、真实 HITL 审批。</sub>
+<br />
+### 图 02 — 数采中心
+<img src="https://raw.githubusercontent.com/kingdol666/AgentWorkShop/main/docs/readme-assets/fig-02-daq.gif" alt="数采中心：节点台账、实时趋势、报警横条与事件流" width="92%" />
+<sub><b>端到端的采集链路。</b>量规统计带之下的节点台账与健康度、随样本落库而生长的趋势曲线、
+只保留真正未确认项的报警横条，以及滚动的事件流。</sub>
+<br />
+### 图 03 — 产线运营
+<img src="https://raw.githubusercontent.com/kingdol666/AgentWorkShop/main/docs/readme-assets/fig-03-dcw.gif" alt="产线运营：产线、产品、配方与写控制" width="92%" />
+<sub><b>产线 / 产品 / 配方 / 批次。</b>开跑产线即用配方窗口为采集设门，并给每个样本打上
+<code>产品/配方/批次</code> 标识；控制节点通过它写入时用的同一条标定路径呈现 <b>SET vs ACT</b>。</sub>
+<br />
+### 图 04 — 数字孪生
+<img src="https://raw.githubusercontent.com/kingdol666/AgentWorkShop/main/docs/readme-assets/fig-04-town.gif" alt="由实时遥测驱动的 3D 数字孪生小镇" width="92%" />
+<sub><b>孪生就是同一条事件总线的渲染结果。</b>设备、频道领地、报警与实时数值——自适应画质阶梯
+（DPR / 阴影 / 泛光，墙钟 FPS 预算）让它在中端机器上也保持诚实。</sub>
+<br />
+### 图 05 — 仪表盘
+<img src="https://raw.githubusercontent.com/kingdol666/AgentWorkShop/main/docs/readme-assets/fig-05-dashboard.gif" alt="带 KPI 量规与趋势的运行仪表盘" width="92%" />
+<sub><b>一屏看全工作坊。</b>频道、Agent、任务、数采吞吐与报警——读的是 API 服务的同一份状态，
+不是另建一套指标存储。</sub>
+<br />
+### 图 06 — 自适应布局
+<img src="https://raw.githubusercontent.com/kingdol666/AgentWorkShop/main/docs/readme-assets/fig-06-responsive.gif" alt="同一套界面从桌面到平板再到手机的形态变化" width="92%" />
+<sub><b>桌面 → 平板 → 手机。</b>刻度轨先收成图标轨、再变成抽屉；页头纵向堆叠，
+高密度表格变成可横向滚动的「账页条」，并把身份列钉在左缘。</sub>
+</div>
+<table>
+<tr>
+<td width="50%"><img src="https://raw.githubusercontent.com/kingdol666/AgentWorkShop/main/docs/readme-assets/shot-workshop.png" alt="Agent 工作台" width="100%" /><br/><sub><b>Agent 工作台。</b>频道时间线、lane、任务、记忆与 HITL 收在同一张工作台。</sub></td>
+<td width="50%"><img src="https://raw.githubusercontent.com/kingdol666/AgentWorkShop/main/docs/readme-assets/shot-monitor.png" alt="运行时监控" width="100%" /><br/><sub><b>运行时监控。</b>每条已接线频道、成员数、依赖环与归属用户。</sub></td>
+</tr>
+<tr>
+<td><img src="https://raw.githubusercontent.com/kingdol666/AgentWorkShop/main/docs/readme-assets/shot-settings.png" alt="系统设置" width="100%" /><br/><sub><b>系统设置。</b>18 组 118 个设置项，由描述符驱动——CLI 读的是同一份注册表。</sub></td>
+<td><img src="https://raw.githubusercontent.com/kingdol666/AgentWorkShop/main/docs/readme-assets/shot-plugins.png" alt="插件管理" width="100%" /><br/><sub><b>插件管理。</b>三种作用域、改代码即热重载、按团队开关。</sub></td>
+</tr>
+</table>
+---
+## 设计架构
+```mermaid
+flowchart TB
+    subgraph FE["前端 — Nuxt 4 / Vue 3"]
+        UI["工作台 UI · 3D 孪生 · 大屏"]
+        WS["AEP 客户端 — seq 续传"]
+    end
+    subgraph SRV["服务端 — Nitro / h3"]
+        REST["REST /api/workshop/**"]
+        HUB["WS Hub — AEP v1"]
+        A2A["A2A JSON-RPC"]
+        MCP["MCP Server"]
+        subgraph RT["运行时"]
+            MGR["AgentChannelManager"]
+            SCH["SchedulerLoop — lead 监督"]
+            TE["TaskEngine — 7 态任务机"]
+            AR["AgentRuntime × N"]
+            MEM["AgentMemory — FTS5 + 向量"]
+            BUS["事件总线 (ManagerBus) — per-channel seq + 环形缓冲"]
+        end
+        subgraph IND["工业"]
+            DAQ["数采网关 — 逐节点边缘运行时"]
+            DCW["数控网关 — 写控"]
+            BR["队列 — inproc / MQTT"]
+            TSDB["时序库 — SQLite / Timescale"]
+        end
+        subgraph HB["Harness 适配器 — 14 个引擎"]
+            MOCK["mock · claude — 进程内"]
+            OMP["omp — RPC 子进程"]
+            CDX["codex — app-server"]
+            DSH["dsh · qwen · hermes — ACP"]
+            OC["opencode — serve"]
+            FAM["gemini · copilot · cursor · crush · goose · pi — 无头 CLI"]
+        end
+        DB[("SQLite — channels · agents · tasks
+messages · memories (FTS5) · events")]
+    end
+    UI <--> WS
+    WS --> BUS
+    REST & A2A & MCP --> MGR
+    MGR --> SCH & TE & AR
+    AR --> MEM
+    AR --> MOCK & OMP & CDX & DSH & OC & FAM
+    MGR & TE & MEM & BUS --> DB
+    DAQ <--> BR --> TSDB
+    DCW --> BR
+    DAQ & DCW --> BUS
+```
+**Agent × 机器之桥**（值得读源码的部分）：
+```
+agent ──绑定──▶ 节点 (daq: auto / dcw: manual)
+  │                    │
+  │  my_industrial_nodes  ◀── 语义卡：物理含义 · 单位 · 安全量程 · 配方窗口
+  │  daq_query             ◀── 时序库历史，统计 + 物理语义
+  │  dcw_control           ──▶ 联锁（安全量程 ∩ 配方窗口）
+  │                           ──▶ HITL 审批（manual 模式，180s 超时）
+  │                           ──▶ PLC 写入 → 回读校验 → ACK + 写历史
+  ◀── Agent 可引用数值的结果文本
+```
+---
+## 快速开始
+### 前置条件
+```bash
+node -v   # ≥ 23.4.0（需要内置 node:sqlite）
+```
+> 真实 Agent harness 需要对应 CLI 在 PATH 中——`omp`、`codex`、`dsh`、`opencode`、`gemini`、`qwen`、`copilot`、`cursor`、`crush`、`goose`、`pi` 或 `hermes`（任选子集；同一 Channel 可混用）。`mock` 与 `claude`（SDK）**进程内运行**，无需 PATH 上的 CLI。仪表盘「执行引擎」面板以绿/灰状态点展示每个引擎的就绪度，未安装引擎可点击跳转官网安装页。可选数采基础设施（MQTT broker + TimescaleDB）在 Docker 可达时自动拉起（`docker compose up -d`）。
+### 方式 A —— 从 npm 安装（推荐）
+```bash
+npm install -g agentworkshop     # → `aw` / `agentworkshop` 进入 PATH
+aw start                         # → http://localhost:3001
+```
+发布出的包内含**预构建的生产产物**（`.output/`），所以 npm 安装后可直接启动——无需构建步骤，也无需构建工具。首次启动时一切初始化进配置根 **`~/.AgentWorkShop`**：默认 `config.yml`、自动生成含随机会话密钥的 `.env`、`runtime-settings.json`、docker-compose 种子、`prompts/`、`commands/`、`plugins/`（由 SDK 示例播种，**默认关闭**）与空的 `data/` 目录。全部运行数据（SQLite、JSON 仓库、备份、日志）也都落在配置根——配置与数据跟着安装走，与当前工作目录无关。
+不想全局安装、只想跑一次？
+```bash
+npx agentworkshop start          # 无需全局 npm 安装
+```
+> `npx` 同样会创建 `~/.AgentWorkShop`——不装全局并不等于在磁盘上不留任何痕迹。
+### 方式 B —— 源码运行
+```bash
+git clone https://github.com/kingdol666/AgentWorkShop.git && cd AgentWorkShop
+pnpm install
+pnpm dev          # → http://localhost:3000（端口取自 config.yml）
+```
+源码生产部署：
+```bash
+pnpm build        # nuxt build → .output/
+pnpm start        # 端口取自 config.yml → server.prod.port
+```
+> 在源码检出内，配置根是项目里的 **`.AgentWorkShop/`** 文件夹（运行时覆盖、数据、项目级指令），而 `config.yml` / `.env` 留在检出根，作为版本化的工厂默认值。
+### 版本更新
+```bash
+aw update                              # 检查 + 就地更新全局安装
+aw update --check                      # 只报告，不安装
+npm install -g agentworkshop@latest    # 手动等效
+```
+版本遵循 semver。每次 `aw start` 都会校验配置根，并把 `home` 之前的旧版 `data/` 布局迁移进来（以最新文件为准），因此数据可以跨版本存活。SQLite schema 迁移在服务端启动时执行。当前版本：**v0.7.58**——见[版本发布](https://github.com/kingdol666/AgentWorkShop/releases)。
+### 第一次「Agent × 产线」会话（约 2 分钟）
+1. **登录** —— 侧边栏注册（或 `POST /api/users/register`）。
+2. **搭产线** —— 「产线运营」→ 建产线，加数采节点（如 `daq-temp-tc`）与数控节点（如 `dcw-temp-sp`），建产品 + 配方，点**开跑**。实时值开始流动。
+3. **建团队** —— 「Agent 工作台」→ 选 lead + workers 后**部署（deploy）**进 Channel。
+4. **绑定节点** —— 打开 Agent 详情面板 → 绑定数采节点（*auto*）与数控节点（*manual* = 需您的批准）。
+5. **提交目标** —— 「分析最近 5 分钟熔体温度；若与 182 °C 偏差超过 1 °C，修正设定值（等我的批准）。」
+6. **审批** —— Agent 读取真实历史、计算均值、发起写请求 → 在 HITL 面板批准 → 看设定值变化，**目标**收口并给出数值报告。
+---
+## 配置与 CLI —— 真正的配置驱动
+一个运行时，一个事实来源。**`config.yml`** 声明默认值；配置根内的 **`runtime-settings.json`** 承载运行时覆盖；环境变量与 CLI 参数在最上层。每个可编辑键在 `shared/config/schema.json` 中声明一次（类型、范围、枚举、实时/重启生效），**前端设置页与 CLI 消费同一份描述符**。
+```
+config.yml（默认值）  <  .AgentWorkShop/runtime-settings.json（运行时）  <  环境变量 / CLI 参数
+```
+配置根：全局安装（`npm i -g`）时为 **`~/.AgentWorkShop`**——无论在哪个目录运行 `aw`；源码检出时为项目内的 **`<repo>/.AgentWorkShop`**（`config.yml` / `.env` 留在检出根，作为版本化的工厂默认值）。`AW_HOME` 可重定向；`AW_MODE=home` 强制全局形态。
+### 设置持久化与热重载
+- **系统设置 → 运行配置**标签页按描述符渲染每个可编辑键——改服务端口、主题、API 超时、语言环境或审批闸门，点保存即可。
+- `live` 键立即生效（主题、标题、超时、审批闸门、数采采样节拍、时序查询桶宽……），经服务端事件流推送，**无需刷新、无需重启**。
+- `restart` 键（端口、主机）落盘持久化，在下一次以对应模式启动时生效（`aw dev` / `aw start`）。
+- 所有写入方共用一条通道：**设置页、CLI、服务端文件监听**最终都收敛到同一个设置文件——任何一端改，处处生效。
+示例——在线调节数采与查询节拍：
+```bash
+aw config set daq.sampling.defaultIntervalMs 2000   # 新节点每 2s 采样
+aw config set daq.sampling.minIntervalMs 500        # 节点级下限（create/patch 钳制）
+aw config set daq.query.defaultBucketMs 3000        # 时序查询缺省 3s 桶
+aw config set daq.query.minBucketMs 500             # 查询下限（samples/产线查询/Agent 工具共用）
+```
+注入 Agent 的工具描述会在每次装配时以当前配置值重新渲染——LLM 永远看到对自己 `daq_query` 调用真正生效的下限与缺省值。
+### `aw` CLI
+| 指令 | 作用 |
+|---|---|
+| `aw start · aw dev · aw build` | 生产服务 / 开发服务器 / 构建——端口取自有效配置；首次 `start` 构建一次 |
+| `aw stop` | 依单实例锁终止运行中的 aw 服务实例 |
+| `aw config list · get · set · unset · reset` | 读写运行时设置（schema 校验 + 原子写盘） |
+| `aw plugin list · create · enable · disable` | 跨三种作用域管理插件：查看、脚手架（默认 project 作用域；`--global` 为 user 作用域）、启停（写状态文件，运行中的服务约 1 秒热重载） |
+| `aw mcp` | 工业 MCP stdio 服务（38 个工具，覆盖平台 REST：产线、配方、DCW 写入、参数映射、数采、频道、团队、模型晋升、插件）——自动发现运行实例；`--doctor` 一次讲清发现/健康/鉴权，`--print-config` 直出可粘贴的 MCP 客户端配置 |
+| `aw home` | 查看/初始化配置根 `.AgentWorkShop` |
+| `aw init <dir>` | 脚手架一个可运行的新项目（含完整配置系统与 CLI） |
+| `aw register <路径\|URL\|npm:包名>` | 注册一条新指令——项目级或 `--global` 用户级 |
+| `aw update` | 对比 npm 远程最新版本，有新版就就地更新全局安装 |
+| `aw doctor` | 环境 + 项目健康检查（node、配置、端口、密钥） |
+| `aw status` | 运行态总览：模式、配置来源、运行中服务、指令表 |
+| `aw tui` | 终端工作台：频道/Agent 管理、任务下发、实时监控面板、HITL 作答（见 [`docs/tui.md`](./docs/tui.md) · [`tui/README.md`](./tui/README.md)） |
+| `aw version` | 打印 CLI/包版本（别名 `v`） |
+全局参数：`--help/-h` · `--version/-v` · `--json`（机器可读） · `--root <dir>` · `--debug`。
+退出码：**0** 成功 · **1** 运行时错误 · **2** 用法错误。带 `--json` 时，失败会以信封返回 `{ ok: false, error: 'unknown-command' \| 'no-project' \| 'usage' \| 'internal' \| … }`，自动化无需解析 stderr 即可分支。
+### 指令注册
+指令就是导出 `{ meta, run }` 的普通模块。把它放进扫描目录，下次调用即生效——无需任何登记清单，约定优于配置：
+| 作用域（高层级优先） | 目录 |
+|---|---|
+| 项目级 | `<检出>/.AgentWorkShop/commands/` |
+| 用户级 | `~/.AgentWorkShop/commands/` |
+| 内建 | 随 CLI 发布（`cli/commands/`） |
+`aw register <file|url|npm:pkg>` 把指令复制进对应作用域（`--global` 进用户级）；`aw help` 列出全部已注册指令。
+```js
+// ~/.AgentWorkShop/commands/hello.mjs
+export const meta = { name: 'hello', group: '自定义', summary: '问好', usage: 'aw hello [--name <n>]' }
+export async function run(argv, ctx) {
+  console.log(`你好 ${argv.flags.name ?? 'AW'} —— 模式: ${ctx.mode}`)
+}
+```
+---
+## 工业栈详解
+### 数据采集（DAQ）
+- **六协议驱动**：Modbus TCP、Modbus RTU-over-TCP（串口网关）、OPC UA、MQTT、HTTP/REST，加 **serial-bridge 内置插件**（RS-232/485 直连：Modbus RTU 帧机 + ASCII 行协议，写侧带同址回读校验，附串口枚举/探针 API 与前端面板）——连接池、分类错误文案、逐驱动连接测试；驱动注册表接受插件注册任意新协议（协议自带自描述 meta 时，前端表单零改动）。
+- **逐节点边缘运行时**：独立采样节拍、下发节拍、节点级在飞互斥——一个慢驱动绝不拖累邻居。采样与查询的默认值/下限由 `daq.sampling.*`、`daq.query.*` live 设置驱动。
+- **管线**：驱动 → 队列（进程内 / MQTT，断连离线缓冲）→ 消费端乱序防御 → 三路分发：WS 实时直推（节拍门控）、TSDB 批量落库、设备孪生回写。
+- **鲁棒性**：TSDB 单 in-flight 写 + 有界重试，缓冲背压带丢弃计数，真实丢失指标随 `daq.controller` 帧暴露。
+- **告警**：配方级监控窗口，**2% 滞回 + 3 拍去抖**；alarm/offline 切换即时生效（安全优先）。
+- **查询默认按批次作用域**：`daq_query` 自动解析节点所属产线的**活动批次**，按该批次的 `run_id` + `recipe_id` 过滤——Agent 取证据时看到的永远是**当前正在跑的配方**，不会把上一轮配方的样本混进本轮判读。生效口径（`run=<id> 配方「名」(recipe_id)`）打印在结果表头，并在文末逐节点重申；这两个 id 可直接回传给 `daq_query` 或 `aml_dataset_build`。需要跨配方对比/历史复盘时传 `scope: 'all'`（或显式给 `recipe_id` / `run_id` / `product_id`）；产线未开跑则不做过滤，历史数据照常可查。
+### 写控制（DCW）
+- 工程量写入：`linear` 标定（scale/offset）PLC↔物理，**回读校验**（死区容差），ACK 状态 + 写历史。
+- **联锁**：产线运行时，活动配方的参数窗口对该节点**替代**全局安全量程。
+- **HITL**：`manual` 绑定挂起写入等用户批准（同 Agent+节点去重；批准时二次校验——权限在您点击批准那一刻重查）。
+### 配方与批次
+`产线 → 产品 → 配方 → 批次`。开跑逐节点应用配方参数（每次写都校验），逐线门控采集，每条样本打标 `line/product/recipe/run`——产品级数据隔离 + 五维查询（产线 × 产品 × 配方 × 时间 × 节点）。
+### AML —— 自动建模实验室
+这是闭环里的建模半边：`/aml` 用已打标的遥测构建**数据集**，把**训练作业**提交到 `uv` 托管的 Python 运行时，在**排行榜**上给各次运行排名，并且只有跨过配置的**门禁**（NRMSE、rollout NRMSE、验证/测试差距、最小行数与运行次数）才允许晋级。晋级后的模型按 id 引用，因此 MPC 或影子孪生控制器消费的是有版本号的产物，而不是含糊的「最新」。
+- Agent 通过 14 个工具做同样的事（`aml_dataset_build`、`aml_job_submit`、`aml_job_status`、`aml_leaderboard`、`aml_model_promote`、`aml_model_find`、`aml_training_plan_*`……）——提交一个目标，让团队去训练并汇报。
+- Python 运行时由 `uv` 自行引导进配置根内的 `./aml` 资产根；数据集/产物/元数据路径、磁盘配额、作业超时、并发与保留策略全部是**设置项**（`aml` 组共 16 项），而不是常量。
+- 治理默认保守：跨配方数据集除非显式允许否则拒绝，每个作业都有归属。
+- **混合孪生 × MPC 内核**：AML 同时承载**混合孪生**平面——`SceneContract` / `PhysicsModelManifest` / `TwinSnapshot` / `ObjectiveProfile` / `VirtualTrial` / `RecommendationCertificate`，底座是带**有界 PyTorch 残差**的灰箱物理主干，外加 UQ/OOD 筛查与全轨迹硬约束门禁。频道通过 `hybrid_twin` profile 显式启用，启用后会注入 12 个 profile 专属工具（`twin_provider_catalog`、`twin_scene_discover/compile/freeze`、`twin_physics_spec_draft/validate/compile`、`twin_scene_read`、`twin_snapshot_create`、`twin_trial_run`、`mpc_optimize`、`twin_gate_evaluate`）与通用工具 `twin_calibration_request`；试验按设计就是**虚拟**的（`candidateExecuted=false`），只有门禁与收益同时通过才签发推荐证书。服务端策略两档：`safe_small_step`(数据不足) 与 `precise_search`(模型过门禁)。计划与验收记录见 [`docs/aml-hybrid-twin-mpc-integration-plan.md`](./docs/aml-hybrid-twin-mpc-integration-plan.md)、[`docs/aml-hybrid-twin-implementation-acceptance.md`](./docs/aml-hybrid-twin-implementation-acceptance.md)。
+- **任意场景建模闭环**：闭环不绑定内置场景。绑定节点 → `twin_scene_discover` 带证据推断 control/state/disturbance/target/guard 语义 → `twin_scene_compile` 生成 `SceneContract` 草稿 → 您确认 → `twin_scene_freeze` 冻结（版本不可覆盖）→ `twin_physics_spec_draft` 起草骨架 PhysicsSpec（每个状态一条一阶弛豫方程，τ/增益为带先验盒的可校准参数）供您润色 → 校验/编译（白名单 AST，禁任意代码）→ `aml_job_submit { job_kind: 'hybrid_residual' }` **可不带代码**：内置参考训练器先做物理参数校准（stage A）、再拟合 3 成员有界残差集成（stage B）、最后报告 conformal q90 覆盖率（stage D）——校准后的 spec 回写，评估/预测/试验三侧同源。
+- **模型驱动孪生与持续校准**：`twin_trial_run` / `mpc_optimize` 可传 `model_id`——rollout 由训练出的 hybrid 模型驱动（校准后物理主干 + 残差集成 ONNX，`ModelBackedHybridProvider`），UQ 覆盖率与成员分歧来自训练工件；模型数据集与场景的产线/产品/配方不一致直接拒绝（`TWIN_MODEL_SCENE_MISMATCH`）。持续校准请求由 60s 定时 worker 消费，自动提交 `hybrid_residual` 重训**候选**；晋升仍走 HITL + Twin Gate（`AML_TWIN_WORKER_DISABLED=1` 可整体关闭）。
+- **双模式优化闭环**：随包附带两个频道模板——`chtpl-aml-training-default`（建模面：22 个工具，无产线写入、无 MPC）与 `chtpl-aml-optimization-default`（执行面：快照/试验/门禁/MPC/贝叶斯寻优，外加 `optimization_explore`——受治理微写，每笔设定值与响应回读配对落 `optimization_explorations` 台账）。两面按频道互斥注入；优化频道实例化时可选**探索**模式（治理小步，无需模型）或 **aml** 模式（必须给 `boundModelId`——过门禁的模型先绑定，执行面才解锁）。
+- **孪生 Provider 插件 SDK（热加载）**：工业场景的物理主干 / 场景包 / 目标 / 求解器经 `ctx.twin` 注册进 **Twin Provider Registry**（`registerPhysicsProvider` / `registerScenePack` / `registerObjectiveProfile` / `registerTrainingAdapter` / `registerSolverAdapter`，另有 `listProviders` / `getProviderHealth` / `resolveProvider` / `validateProvider` / `retireProvider` / `isRegistryAvailable`）。孪生工具按 `SceneContract.physicsProfileId` 解析 Provider（解析不到回退内置 `twin-injection-default`），**换场景不改工具与频道**；热重载按 **generation** 装载新代、排空旧代，试验与 MPC 持租约 ⇒ 在飞工作不被作废，`retireProvider` 等引用归零才下线。系统自带注塑 Provider 走的正是这套外部契约（`server/plugins-builtin/twin-injection-default/`），装法与其它插件同址、停用或热重载无需重启。清单字段与可运行示例见 [`docs/plugins.md`](./docs/plugins.md)「混合孪生 Provider 插件」，SDK 面见 [`docs/sdk.md`](./docs/sdk.md) §4.10。
+---
+## 使用说明
+### 认证
+邮箱 + 密码登录签发 **bearer token**（每用户多 token，可单独吊销）。
+```bash
+# 注册
+curl -X POST http://localhost:3000/api/users/register \
+  -H 'content-type: application/json' \
+  -d '{"email":"you@example.com","password":"secret","name":"you"}'
+# 所有 workshop 调用
+curl http://localhost:3000/api/workshop/channels \
+  -H 'authorization: Bearer <token>'
+```
+### 产线级权限
+工业数据按**产线**三态管控，由管理员在内置「权限管理」页（`/permissions`，仅 admin 侧栏可见）维护：
+| 状态 | 数采节点 | 数控（写控）节点 | 可见性 |
+|---|---|---|---|
+| **无权**（普通用户默认） | 隐藏 | 隐藏 | 后端不返回该产线数据——产线运营/数采中心/数字孪生均不可见 |
+| **仅查看** | 只读 | ✕ | 产线可见、实时值可看，但不可写/不可下发/不可绑定设备 |
+| **可操控** | 读取 | 读取+写入 | 全量能力：设定值写入、任务下发、设备绑定 |
+- `admin` / `editor` 为运营角色，不受授权约束（全量全权）。
+- 普通用户**默认无权**——未授权前看不到任何产线数据。
+- 强制点在数据面：列表接口按授权过滤，写控/下发接口返回人类可读的 403，Agent↔节点绑定校验产线授权（数采需仅查看+，写控需可操控）。
+- 插件经 `ctx.permissions`（`lineMode` / `visibleLineIds` / `listGrants` / `setGrants`）获得同一能力面，并有 `permissions:changed` 生命周期钩子；SDK REST 客户端提供 `client.permissions.overview()` / `client.permissions.set(...)`。
+### 执行模式
+在任务描述中使用模式前缀（或在 composer UI 中选择）：
+| 模式 | 语义 | 配置 |
+|---|---|---|
+| `goal` | lead 分解 → worker 交付 → **lead 判定满意度**；不满足继续补发；满足收口父任务。 | `goalCriteria` |
+| `loop` | 固定间隔循环重放同一任务。 | `intervalMs`（默认 60000）、`maxIterations`（默认 ∞） |
+| `pipeline` | 有序阶段；阶段 N+1 消费阶段 N 产出。 | `stages: [{name, description, assigneeId?}]` |
+### 定时任务
+任意任务都可挂上**调度**，让频道在无人值守时也持续工作：
+| 维度 | 行为 |
+|---|---|
+| 模式 | `interval` —— 固定节拍（`intervalMs`，60s 下限）· `daily` —— 每日本地时间 `HH:MM` 定点一次 |
+| 管理 | `/workshop/schedules` 页面，或 `POST/PATCH /api/workshop/schedules` |
+| 护栏 | 忙等守卫（频道仍有在飞任务时本次触发顺延）、逐次运行历史带状态、**连续失败熔断**（`maxConsecutiveFailures`，异常调度自动停用） |
+| 典型用法 | 每日巡线（`daq_query` + 漂移摘要写入频道记忆）、周期性偏差检查 + 自动判定、每日 KPI 摘要 |
+```bash
+# 创建调度：每 30 分钟巡线一次
+curl -X POST http://localhost:3000/api/workshop/schedules \
+  -H 'authorization: Bearer <token>' -H 'content-type: application/json' \
+  -d '{"channelId":"<id>","name":"line-patrol","title":"巡线","description":"读取 1 号线全部数采节点,把漂移摘要写入频道记忆。","mode":"interval","intervalMs":1800000}'
+```
+### 四个入口
+| 入口 | 端点 | 面向 |
+|---|---|---|
+| **WS** | `/api/workshop/ws?channelId=…` | 仪表盘 / UI——AEP v1 信封，per-channel 单调 `seq`，5000 事件环形缓冲，`lastSeq` 续传，快照兜底。 |
+| **MCP** | 进程内服务，约 25 个工具 | Agent（omp host tools）——管理面 + 作业面工具，Channel 作用域。 |
+| **A2A** | `POST /api/workshop/a2a/:agentId/rpc` | 外部 Agent——JSON-RPC 2.0，`AgentCard` 在 `/card`，`tasks/sendSubscribe` SSE。 |
+| **REST** | `/api/workshop/**` | 人 / 脚本——完整管理面。 |
+### 任务状态机
+```
+SUBMITTED ─▶ ASSIGNED ─▶ WORKING ─▶ WAITING ─▶ COMPLETED
+    │            │           │           │
+    └────────────┴───────────┴──▶ CANCELED / FAILED ─▶（重试 ≤ 3 或取消）
+```
+---
+## 端到端验证
+上面每一条论断，背后都有一个可复跑的套件。验收套件在**生产实例上、跑真实模拟产线协议**（Modbus TCP/RTU、OPC UA、MQTT、HTTP + MQTT/Timescale 管线），配真实引擎 CLI，断言落在数据库、事件流与 HTTP API 上——而不是 mock。2026-09-24 的两轮波次已归档：基础矩阵（约 **1100+ 条真实断言**，v0.7.45 生产构建、隔离 `AW_HOME`、真实浏览器）见 [`docs/audit/e2e-2026-09-24-full-coverage.md`](./docs/audit/e2e-2026-09-24-full-coverage.md)；补充功能波次（真实 **PLC 节点模拟器** + 注塑 AgentTeam 闭环、FIFO 多任务、定时任务、协作，合计约 **1400+ 条断言**）见 [`docs/audit/e2e-2026-09-24-all-features.md`](./docs/audit/e2e-2026-09-24-all-features.md)。
+| 套件 | 最新结果 | 覆盖 | 复现 |
+|---|---|---|---|
+| `real-injection-closed-loop.mjs` | **双 goal 全部 COMPLETED / 0 失败**（2026-09-24，真实 PLC 模拟器 + 真实 `omp` 团队） | 从模拟器供给注塑产线（11 个数控 + 14 个数采节点）→ 真实 AgentTeam(lead/分析/优化) → 受治理写入且**间隔 65.8s ≥ 60s 策略** → 数采复测 → `qualityOk`、判定 `keep` | `AW_BASE=<base> SIM_BASE=http://127.0.0.1:4010 AW_TOKEN=<token> node scripts/real-injection-closed-loop.mjs` |
+| `_run-real-injection-fifo-goals.mjs` | exit 0（2026-09-24） | **FIFO 根队列多任务串行**：GOAL-2 仅在 GOAL-1 收口后派发；角色门控切换；两次受治理写入间隔 65.04s；两条记录均判定；账本 4 条锚 | `AW_BASE=<base> SIM_BASE=… AW_TOKEN=<token> node scripts/_run-real-injection-fifo-goals.mjs` |
+| `e2e-plc-plugin-closedloop.mjs` | 核心 Stage A–D 全绿（2026-09-24） | PLC 模拟器 Modbus 16040 真实供给 → 数采交叉核对（AW 采样 197 vs 模拟器寄存器 197.37）→ HITL 闭环写 3 区（寄存器 40021/40023/40025 = 210，真实写穿）→ `dcw_judge` keep；插件段 E–H 需外部诊断服务，按约定显式 SKIP | `AW_BASE=<base> KB_BASE=http://127.0.0.1:8771 AW_E2E_USERS_DB=<home>/data/users.sqlite node scripts/e2e-plc-plugin-closedloop.mjs` |
+| `_dbg-schedule-e2e.mjs` | **35 / 0**（2026-09-24） | 定时任务：计划 CRUD + 参数校验、`next_run_at`、`scheduledCount`、忙等守卫 **409 CHANNEL_BUSY**、在途重复 **409 SCHEDULE_RUNNING**、取消对账（run FAILED + 失败计数）、**timer 到点自动触发**（`trigger_kind=timer`）、停用/启用状态机、删除后 404 | `SCHED_E2E_BASE=<base> node scripts/_dbg-schedule-e2e.mjs` |
+| `e2e-crash-cycle.mjs` | **5 / 5 阶段**（2026-09-24） | 常规执行 → 硬杀 → 持久化断言 → 重启 → 重投 → 自动恢复 → 消费缺口重投；每阶段独立进程 | `node scripts/e2e-crash-cycle.mjs --port 3300 --home .e2e-home-full` |
+| `e2e-full-closedloop.mjs` | **98 / 0**（2026-09-24，v0.7.45 生产构建） | 11 阶段：注册 → 产线/产品/配方建模 → 数采采样 → 帧管线 → 数控写入 + 回读 → 回退账本 → Agent 节点鉴权 → 桥越权边界 → 插件 → 数据根隔离 | `node scripts/e2e-full-closedloop.mjs <base>` |
+| 全协议矩阵（真实协议） | **46 / 0**（2026-09-24） | MQTT · Modbus TCP · Modbus RTU · OPC UA · HTTP——逐协议数采、受控下发 + 回读、配方窗联锁与真实 Agent 闭环 | `node scripts/_dbg-protocol-matrix.mjs` |
+| 生产 API 全链路 | 60 / 0（2026-09-24） | 跨重启持久化、模板 CRUD、任务 assign/complete/cancel/loop/pipeline、A2A + mailbox、WS 广播、MCP 端点、级联删除 | `AW_E2E_TOKEN=<token> node scripts/api-live-e2e.mjs` |
+| AgentTeam 群聊 + 原生 HITL | 112 通过 / 0 失败 / 1 阻塞（2026-09-24，真实 `omp`） | 群聊请求 → 可追踪作业；`omp` 原生 ask → HITL 审批 → 引擎带回执继续 | `node scripts/e2e-agentteam-chat.mjs --phase=all` |
+| 终端镜像 + 提示词组合 | **26 / 0** 与 **16 / 0**（2026-09-24，真实 `omp`） | 终端镜像帧、`input`/`abort`/`ui_response` 注入、原生 `ask` 往返；五段式 prompt 组合（场景 → 专长 → 记忆 → 手册 → 任务）在线上可观测 | `node scripts/test-terminal-e2e.mjs` · `node scripts/test-prompt-system.mjs` |
+| 真引擎协作 | 任务流真跑 **PASS**、`e2e-omp-workspace` **13 / 13**、群聊全真 **PASS**、多用户 HIL **PASS**（2026-09-24） | 真实 `omp` lead + worker：分解/派发/进度/成果/workspace 文件读取与卸载；多用户 HITL 可见性；多引擎团队 14/18（omp 与 dsh 全绿） | `npx tsx scripts/e2e-agentteam-task-flow-real.ts` · `npx tsx scripts/e2e-omp-workspace.ts` |
+| 前端验收 | 响应式门禁 **16 / 16** 页、抽屉交互 **10 / 10**（2026-09-24，真实 Chromium） | 全部产品页（含 3D 小镇）在门禁阈值下渲染通过；抽屉开合、滚动锁、路由跳转、零 pageerror | `node scripts/ui/verify-responsive.mjs --routes all` · `node scripts/ui/verify-nav.mjs` |
+| `_aw0746-stage12.mjs` | **10 / 0**（2026-09-25,全局安装的 **v0.7.49 打包系统**） | 健康门(version=0.7.49)→ 管理员登录/角色面 → 创建 Channel(真实 `omp` lead)→ 开群聊 → **真实 omp 群聊回复** → 系统监控可见 omp 子进程 | `AW_BASE=<base> node scripts/_aw0746-stage12.mjs` |
+| `_aw0746-stage34.mjs` | **13 / 0**（2026-09-25,v0.7.49 打包系统 + PLC 模拟器） | 模拟器建线（11 数控 + 14 数采）→ 产品/配方三元组 → 开跑后**样本逐条带 recipe_id/run_id** → `daq_query` **默认只取当前活动批次**（`scope=all` 可放开，实测 1 vs 4）→ 实例化 Hybrid Twin 模板（lead + 3 worker,注入孪生 6 件套 / 总 57 工具） | `AW_BASE=<base> node scripts/_aw0746-stage34.mjs` |
+| `_aw0746-stage6b-train-sweep.mjs` | 门禁**全绿**（2026-09-25,v0.7.46 打包系统,真实 torch 训练） | 1 s 拍格数据集（**1724 行 / 10 批次**）→ 内联 code 作业真实训练 → G1 单步 **0.0992**（≤0.10）/ G2 滚动 0.1092（≤0.25）/ G3 泛化 14.6%（≤20%）/ G4 行数与批次 → 模型注册并**晋升 production** | `AW_BASE=<base> AW_DATASET_ID=<ds> node scripts/_aw0746-stage6b-train-sweep.mjs` |
+| `_aw0746-stage7-twin.mjs` | **17 / 0**（2026-09-25,v0.7.49 打包系统,真实 DAQ + 真实模型） | 真实样本 → TwinSnapshot `fresh=true` → 65 组真实 VirtualTrial（12 条安全候选,`candidateExecuted=false`）→ 12 项推荐门禁 **write_eligible** → 门禁结论回写模型 `twinEligibility` → `mpc_optimize` 升档 **precise_search** → 全程 **0 DCW 写入** | `AW_BASE=<base> AW_REQUIRE_MODEL=1 node scripts/_aw0746-stage7-twin.mjs` |
+| `_aw0746-stage6c-jobsmoke.mjs` | **5 / 0**（2026-09-25,v0.7.49 打包系统） | AML 作业链路：内联 `code` 被接受（不再要求 `workspace/train.py`）→ 作业到终态 → 训练日志/ONNX 痕迹 → 实验与逐项门禁落库 | `AW_BASE=<base> node scripts/_aw0746-stage6c-jobsmoke.mjs` |
+| `_aw0748-failclosed-probe.mjs` | **7 / 0**（2026-09-25,v0.7.49 打包系统） | 硬约束**失败关闭**回归:auto_daq 按真实绑定取样建快照 → 可映射约束 `weight` 正常评估 → 不可映射的 `part_weight` 判不通过并给出明细（v0.7.47 会假通过）→ 空轨迹同样判不通过 | `AW_BASE=<base> node scripts/_aw0748-failclosed-probe.mjs` |
+| `_aw0748-mock-closedloop.mjs` | **13 / 0**（2026-09-25,v0.7.49 打包系统,进程内 `mock`,零额度） | 调度闭环回归:创建 mock Channel → 根任务被真实派发并收口 → `[mock:complex]` 强制委派出子任务 → 父任务汇总收口 → mock worker 就位后 [mock:complex] 委派子任务并汇总 → **第二个/第三个根任务同样被派发**（修复前:lead 空闲卸载后 `scheduler` 置空,后续根任务只落库、一直 SUBMITTED 直到 `ROOT_TIMEOUT`）→ mock 无 host tool 通道时工具桥显式拒绝 | `AW_BASE=<base> node scripts/_aw0748-mock-closedloop.mjs` |
+| 工业基准——integrated | **83 / 83 检查，硬门禁绿**（2026-09-21） | 五协议五产线基准：连通性、采样入 Timescale、受控下发、治理、Agent 闭环、工艺参数语义层 | `node bench/pipeline.mjs --profile integrated` |
+| 多场景闭环 | 4 场景 · 闭环达标（2026-09-21） | 注塑克重窗口寻优 · A²/O 污水排放达标 + 能耗最小化 · 连续退火质量窗与产能权衡 · BOPET 产线任务 | `node bench/scenarios.mjs --scenarios injection,wwtp,anneal` |
+| 产线权限 / 审计负向 | 21 / 21 + 9 / 9（2026-09-12） | 三态产线授权 + 人类可读 403、绑定主体校验、授权撤销收敛、无 token WS 零遥测 | `node scripts/_dbg-perms-e2e.mjs <base> <adminPass>` · `node scripts/_dbg-audit-neg-e2e.mjs <base> <adminPass>` |
+| 渲染回归 | 30 / 30（2026-09-12） | 数采表完整性（行数与 API 动态对齐）、WS 驱动行更新、筛选、详情页、3D 小镇 + 模型库、7 页 smoke、零 pageerror | `node scripts/_dbg-render-regression.mjs <base> <email> <pass>` |
+| AML 自动建模 | 25 / 0（2026-09-24，确定性训练器） | 数据集构建 → 跨配方拒绝 → 作业提交 → 门禁 → 晋级守卫 → 预测守卫 → 审计；`--real` 附加 uv/torch 真实运行时 | `node node_modules/tsx/dist/cli.mjs --tsconfig .nuxt/tsconfig.server.json scripts/e2e-aml.ts` |
+| 离线单元/属性套件 | 全绿 | AEP 事件索引（`test-events-index`）、LRU、数据根拆分（`test-data-root`）、日志洪泛、回退索引、插件加固、任务租约围栏（`test-task-lease-fencing`）、CLI 退出码（`test-cli-exit`）、SDK 能力面（`test-sdk-surface`） | `node scripts/test-<name>.mjs`（TS 套件经 tsx 运行） |
+历史上的 **v0.7.20** 验收基线——*156 断言、0 失败*——归档于 [`docs/audit/e2e-2026-09-07.md`](./docs/audit/e2e-2026-09-07.md)。性能探针：`scripts/_dbg-render-perf.mjs`。
+---
+## 项目结构
+```
+AgentWorkShop/
+├── bin/ · cli/                 # aw CLI——指令注册表 · 内置指令 · 配置引擎接线
+├── app/                        # Nuxt 4 前端（srcDir）
+│   ├── pages/                  # / · /workshop · /workshop/agents · /workshop/teams
+│   │                           # /workshop/channel-templates · /workshop/schedules · /workshop/w/:id
+│   │                           # /town · /daq · /daq/:id · /dcw · /dcw/:id
+│   │                           # /aml · /operations · /monitor · /logs · /permissions
+│   │                           # /plugins · /users · /tokens · /settings
+│   ├── components/workshop/    # 时间线 · 泳道 · 任务板 · 记忆面板 · 3D 小镇
+│   └── stores/composables/     # Pinia + AEP 客户端
+├── server/
+│   ├── api/                    # REST + WS + A2A + MCP 路由
+│   ├── services/workshop/
+│   │   ├── runtime/            # manager · scheduler-loop · task-engine · memory · mailbox
+│   │   ├── agents/             # AgentInterface：14 个引擎（+ 工业工具）
+│   │   ├── daq/ dcw/ aml/      # 边缘运行时 · 驱动 · 队列 · 存储 · 建模实验室
+│   │   └── db/                 # node:sqlite 仓储层
+│   ├── mcp/                    # MCP 服务（25 个工具，进程内 workshop 面）
+│   ├── plugins-builtin/        # 随包发布的插件（serial-bridge · rag-bridge · diag-bridge · twin-injection-default）
+│   └── plugins/                # 运行时装配（单例）
+├── mcp/                        # aw mcp —— 零依赖 stdio MCP 网关（38 个工具，实例自动发现）
+├── sdk/                        # agentworkshop/sdk——插件上下文、钩子总线、REST 客户端、浏览器 SDK
+├── tui/                        # 终端工作台（aw tui）
+├── shared/
+│   └── config/                 # schema.json（118 个设置描述符）+ 引擎（合并/校验/持久化）+ 路径解析器
+├── config.yml                  # 工厂默认值（构建/启动时读取；版本号来自 package.json）
+├── .AgentWorkShop/             # 检出内的配置根——prompts（版本化）+ 运行时覆盖 · 数据 · 日志 · 指令（git 忽略）
+├── data/                       # 迁移前的旧版位置（自动迁移进配置根）
+└── scripts/                    # 启动器 · home 引导 · E2E · 验证套件
+```
+## 技术栈
+| 层 | 技术 |
+|---|---|
+| 框架 | [Nuxt 4](https://nuxt.com) + Nitro（WebSocket） |
+| UI | Vue 3.5 · Pinia · Ant Design Vue · UnoCSS · Three.js · ECharts |
+| 语言 | TypeScript 5.7 全栈；`shared/` 前后端共用 |
+| CLI | Node ESM CLI，可插拔指令注册表（`bin/aw.mjs`） |
+| 持久化 | `node:sqlite`（零原生依赖）+ FTS5 + 可选 `sqlite-vec`；时序用 TimescaleDB |
+| 校验 | `zod` —— 每个消息边界 |
+| 互操作 | `@modelcontextprotocol/sdk` · A2A（JSON-RPC 2.0）· AEP v1（自研 WS 协议） |
+| 现场总线 | `modbus-serial` · `node-opcua` · `mqtt` |
+## 开发指南
+```bash
+pnpm dev          # 开发服务（端口取自有效配置）
+pnpm cli …        # 仓库内使用 CLI：pnpm cli config list
+pnpm tui          # 终端工作台（连运行中的实例）
+pnpm build && pnpm start
+pnpm typecheck                            # 包装脚本：prepare → 剔除失效 volar 条目 → vue-tsc -b
+pnpm lint
+pnpm test:api-live                        # 针对运行中服务的 API 套件
+node scripts/e2e-full-closedloop.mjs      # 全链路闭环（需服务端运行中）
+node scripts/e2e-crash-cycle.mjs          # 硬杀 → 重启 → 重投（自带隔离实例管理）
+node scripts/test-sdk-surface.mjs         # SDK 导出面守卫
+```
+> 排障前先知道两条测试运行约定：（1）`pnpm typecheck` 走 [`scripts/typecheck.mjs`](./scripts/typecheck.mjs)，
+> 而不是裸 `nuxt typecheck`——Nuxt 4.5 仍会把 `vue-router/volar/sfc-route-blocks` 编译插件写进生成的
+> tsconfig，而 vue-router 4.6 已不再导出该子路径，裸 vue-tsc 在加载配置阶段就崩，类型检查其实一次都没跑；
+> （2）导入**真实路由 handler** 的 TS 套件（如 `scripts/e2e-memory-system.ts`）要走纯 node 路径
+> `node --experimental-transform-types --import ./scripts/_audit/ts-register-hook.mjs <suite>.ts`，
+> 该钩子把 Nuxt 的 `#imports` 虚拟模块映射到共享配置桩。
+文档站位于 `docs/site/`（VitePress），由 [`.github/workflows/deploy-docs.yml`](./.github/workflows/deploy-docs.yml) 部署到 GitHub Pages：
+```bash
+cd docs/site && npx vitepress dev        # 本地预览
+cd docs/site && npx vitepress build      # 生产构建 → .vitepress/dist
+```
+该工作流在构建前把 `docs/{cli,plugins,sdk}.md`（及其 `.en.md` 双语对照）同步进文档站，因此这些文件是单页指南的唯一事实来源。
+## 部署（生产）
+目标形态：**内网单实例 + 反向代理终结 TLS**。服务本身刻意不做 TLS 监听 ——
+由 caddy/nginx 在前面终结（顺带获得 HTTP→HTTPS 跳转、访问日志与第二层限流）。
+```bash
+# 1) 构建并启动(缺 .output 产物时生产入口会拒启)
+pnpm build
+NUXT_SESSION_PASSWORD=$(node -e "console.log(require('crypto').randomBytes(24).toString('hex'))") \
+PORT=3000 node scripts/start.mjs
+```
+**TLS 反向代理。** caddy(自动证书,WebSocket 天然透传):
+```caddy
+aw.example.com {
+    reverse_proxy 127.0.0.1:3000
+}
+```
+nginx(注意 WebSocket `Upgrade` 头 —— 工作台、HITL 面板、实时日志全部走 WS):
+```nginx
+server {
+    listen 443 ssl;
+    server_name aw.example.com;
+    # ssl_certificate / ssl_certificate_key ...
+    location / {
+        proxy_pass http://127.0.0.1:3000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_read_timeout 300s;
+    }
+}
+```
+全站 HTTPS 后打开运行时设置 `security.hstsEnabled`,响应带 `Strict-Transport-Security`。
+**进程守护。** `scripts/start.mjs` 已自带子进程监管(崩溃退避重启、30s 健康探针、
+堆水位主动重启)—— 把**它**交给服务管理器,让守护进程本身也能扛住重启:
+```ini
+# /etc/systemd/system/agentworkshop.service
+[Service]
+WorkingDirectory=/opt/agentworkshop
+Environment=NUXT_SESSION_PASSWORD=<生成的密钥>
+Environment=PORT=3000
+ExecStart=/usr/bin/node scripts/start.mjs
+Restart=always
+User=aw
+[Install]
+WantedBy=multi-user.target
+```
+Windows 用 `nssm install AgentWorkShop "C:\Program Files\nodejs\node.exe" scripts\start.mjs`。
+**不要**对同一配置根起第二个实例 —— 单实例锁(`.runtime/aw.lock` 带心跳)会让新进程
+顶替、旧进程退出。
+**生产认证加固。** `security.allowRegistration` 缺省 **false**:首管理员就位后两个
+注册端点一律 403,账号由管理员创建;管理员建号/重置密码的账号带 `mustChangePassword`
+标记 —— 工作台在首次登录时强制改密(管理员重置会再次置位并吊销全部旧会话)。
+首启引导不受影响:零用户时首个注册账号仍自动成为管理员。
+**备份与恢复。** `server/plugins/backup.ts` 每 24h 快照(保留 7 份)到
+`<配置根>/.AgentWorkShop/data/backups/`:
+- 三个 SQLite 库(`workshop/users/daq-timeseries.sqlite`,WAL checkpoint + 原子改名)
+- 全部 JSON 仓储 + `config.yml` / `runtime-settings.json`(`files-<stamp>/`)
+- 本地对象存储与导出 `daq-objects/`、`daq-exports/`(`objects-<stamp>/`)——
+  超过 `AW_BACKUP_OBJECTS_MAX_MB`(缺省 200MB)时显式跳过并落日志
+- 每次附带 `manifest-<stamp>.json`;TimescaleDB/MinIO **docker 卷不在文件备份范围** ——
+  用 `pg_dump` / `mc mirror` 或卷快照另行备份
+恢复演练(上线前务必做一次):停服 → 移走 `backups/` → 用最新 `*.bak` + `files-*` +
+`objects-*` 重组数据目录 → 启动 → 核验 `/api/health`、管理员登录、产线/配方在册。
+`BACKUP_DISABLED=1`、`BACKUP_INTERVAL_HOURS`、`BACKUP_KEEP` 可调。
+**生产检查清单。** `NUXT_SESSION_PASSWORD` 随机生成(已知开发密钥会拒启) ·
+`security.allowRegistration=false`(缺省) · 反代 TLS + HSTS · 服务管理器就位 ·
+恢复演练已过 · `/api/health` + `/api/metrics` 接入监控 · `AW_HEAP_LIMIT_MB` 按主机
+配好 · `AW_RATE_LIMIT_OFF` **不设**(内置限流必须在线) ·
+`AW_BENCH_MODE` **不设**(写控联锁与限频必须全量在岗)。
+**基准开关 `AW_BENCH_MODE=1` 是实验专用,生产禁用。** 该开关服务于 `bench/` 论文
+基准管线(E1a 四臂消融),置 1 时:API 限流总闸停用;在线探索限频(单步步长上限/
+60s 最小写入间隔/写入保持窗)整体豁免;写接口接受 `x-aw-bench-arm` 头选择旁路
+软联锁层(no-interlock/no-readback/ungated;硬量程与结构层校验结构性不可旁路)。
+生产部署的唯一正确值是**不设置**:代码按 `=== '1'` 精确判断,缺省即恒 full 臂;
+开关在模块加载时读取,必须在进程启动前确认未设置(误配时启动日志会告警)。
+`AW_RATE_LIMIT_OFF=1` 只关 API 限流、不影响写控联锁,生产同样必须不设。
+## 路线图
+| 能力 | 状态 |
+|---|---|
+| Channel 运行时、lead 编排、7 态任务引擎 | 已交付 |
+| 四入口：WS（AEP v1）· MCP · A2A · REST | 已交付 |
+| 持久记忆（FTS5 + 可选向量混合） | 已交付 |
+| 工业栈：数采 · 数控写控 · 产线/配方/批次 | 已交付 |
+| Agent ↔ 节点绑定 + HITL 审批 + 联锁 | 已交付 |
+| 3D 数字孪生小镇 · 产线运营 UI · 仪表盘 | 已交付 |
+| 全功能 live E2E（Agent 读写真实产线，23 项检查） | 已交付 |
+| 运行时配置系统：设置持久化 · 热重载 · 设置页 UI | 已交付 |
+| `aw` CLI：config · start/dev · init · register · doctor | 已交付 |
+| 多 Harness 注册表：omp · codex · dsh · opencode 子进程引擎 | 已交付 |
+| 六种现场协议：Modbus TCP · Modbus RTU-over-TCP · OPC UA · MQTT · HTTP + 内置 serial-bridge 串口插件（数采 + 数控双向） | 已交付 |
+| Harness 可用性探测 + 执行前引擎强校验（UI 禁选 + 409） | 已交付 |
+| Recipe 归因版本化 + 非破坏回退（界面 + Agent 工具） | 已交付 |
+| 配方链路优化闭环：recipe_trial 整批试验（不写版本）→ 进步才固化 → 统一回退（PLC 整批恢复） | 已交付 |
+| 频道绑定产线：全员只读日志/配方/状态 + 产线简报注入提示词 | 已交付 |
+| Agent 自查工具：line_context / ops_log / recipe_log / recipe_versions / dcw_journal | 已交付 |
+| 多 Harness 并行真实产线 live E2E（四引擎、一条产线） | 已交付 |
+| HITL 审批流经真实 OPC UA 写入验证 | 已交付 |
+| 双语文档（简体中文 / English，VitePress 语言切换） | 已交付 |
+| Channel 级 LLM provider/model 选择（取自实时 Harness 目录） | 已交付 |
+| 可配置数采/时序节拍（采样与查询的默认值 + 下限，live 热重载） | 已交付 |
+| 团队级插件开关（建队勾选 + 团队弹层，按 Channel 过滤工具注入） | 已交付 |
+| 插件热管理：`/plugins` 管理页 + `aw plugin list/enable/disable` | 已交付 |
+| 渲染性能专项（v0.7.27）：数采主线程阻塞 −90%、孪生 −69%，自适应画质回升最高档；`window.__townStats` 仪表化 | 已交付 |
+| 插件系统 v2：浏览器面板注入、插件级 settings/groups、插件 i18n、宿主运行时服务（`ctx.services`/`ctx.daq`/`ctx.omp`） | 已交付 |
+| Instrument Glass 材质层（v0.7.36）：三级半透明材质、通透感、高光边缘、弹簧动效、逐页路由转场 | 已交付 |
+| 实时管线优化：数采帧索引 O(n²)→O(n)、逐 Agent 增量事件索引、图表原地更新、按大小感知的 JSON 持久化 | 已交付 |
+| AML 自动建模实验室：数据集构建 · 作业编排（uv 托管 Python）· 排行榜 · 晋级门禁 · 14 个 Agent 工具 | 已交付 |
+| Claude Agent SDK 适配器——常驻会话、同轮 steer 与 `canUseTool` HITL | 已交付 |
+| 工艺参数语义映射：`param_control`/`param_read` 按工艺参数寻址、四层写入限界、调控闭环（`dcw_judge`/`dcw_rollback`） | 已交付 |
+| Channel 群聊：请求升级为可追踪作业；原生 HITL（`omp` ask → 审批 → 回执） | 已交付 |
+| 定时任务：`interval` / `daily` 双模式、逐次运行历史、忙等守卫 + 连续失败熔断 | 已交付 |
+| 根任务队列（FIFO、排队位次可见）+ 派发代与执行租约围栏 | 已交付 |
+| 监督看门狗 + Harness 连续性（`persistent`/`per_turn`、会话复用租约带重启原因） | 已交付 |
+| Channel 过程记忆：确定性事件契约、canonical root 摘要、持久 outbox + 补偿 worker | 已交付 |
+| 运行时可观测：`GET /api/system/monitor` 团队指标，每项带文档化回滚开关 | 已交付 |
+| 工业基准：integrated 档（83 项检查、硬门禁）+ 多场景闭环（注塑 / 污水 / 退火 / BOPET）+ 质量目标 optloop 寻优 | 已交付 |
+| 生产构建全覆盖验收波次矩阵（约 1100+ 条真实断言，2026-09-24） | 已交付 |
+| 孪生 Provider 插件 SDK：物理/场景/目标/训练/求解器 Provider 经 `ctx.twin` 热加载注册，按 generation 装载 + 租约排空，内置 Provider 走同一外部契约 | 已交付 |
+| 任意场景混合孪生建模闭环：场景发现 → 编译 → 冻结 → 物理 spec 起草/校验/编译 → 参考训练器作业（物理校准 + 残差集成 + conformal UQ）、模型驱动试验、持续校准 worker | 已交付 |
+| 双模式优化闭环：`aml-training` / `aml-optimization` 专属频道模板、互斥工具面、探索 ↔ 生产双模式、带回读配对的治理微写 | 已交付 |
+| 产线操作流水：`/operations` 单页 + 工作台控制台面板，九类操作时间线、结构化写控 diff、闭环阶段推断 | 已交付 |
+| 外部 MCP 网关：`aw mcp` stdio 服务（38 个工具）、实例自动发现、`mcp.enabled` 运行时门控 | 已交付 |
+| 可配置系统时区（`time.timeZone`，live 热生效）+ 配方参数级单步限幅 `stepLimit` + 配方 `description` 元字段 | 已交付 |
+| 生产硬化：TLS、MQTT 鉴权、OPC UA 签名+加密缺省、结构化审计日志 | 规划中 |
+| 边缘部署形态：独立 edge-agent + 中心 broker | 规划中 |
+| 报警外送（邮件/webhook）+ 确认工作流 | 规划中 |
+| CI 流水线（typecheck + lint + e2e）——文档部署已跑在 GitHub Actions 上 | 规划中 |
+| License：Apache 2.0（宽松许可 · 允许商用与生产部署） | 已交付 |
+## 许可证
+AgentWorkShop 是独立项目，**不是 Anthropic 或任何 LLM 厂商的官方产品**。它通过公开接口与 Agent harness（如 `omp`）集成。
+**AgentWorkShop 为开源软件，依据 [Apache License 2.0](./LICENSE) 发布。**
+- **允许** —— 个人学习、科研、兴趣项目、教学，以及非商业组织（公益、教育、公共研究、政府机构）的使用。
+- **未经版权人事先书面许可不得商用** —— 任何**商业用途**：销售、付费服务、集成进商业产品、服务于经营活动的生产使用均未获授权。商用授权可向版权人申请。
+- **再分发时** 必须随附本协议条款与 `Required Notice` 版权声明行。
+商用授权联系：[GitHub @kingdol666](https://github.com/kingdol666) · kingdol6080@gmail.com
+<div align="center">
+<a href="https://star-history.com/#kingdol666/AgentWorkShop&Date">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=kingdol666/AgentWorkShop&type=Date&theme=dark" />
+    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=kingdol666/AgentWorkShop&type=Date" />
+    <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=kingdol666/AgentWorkShop&type=Date" width="80%" />
+  </picture>
+</a>
+</div>
+---
+## 参与贡献
+欢迎提交 Issue 与 Pull Request。提 PR 之前请先：
+1. **先读你要改的那份契约**——扩展面见 [`docs/plugins.md`](./docs/plugins.md)，编程客户端见 [`docs/sdk.md`](./docs/sdk.md)，指令注册见 [`docs/cli.md`](./docs/cli.md)。
+2. **本地跑一遍门禁**：
+```bash
+pnpm typecheck                            # vue-tsc 覆盖 app + server + shared
+pnpm lint                                 # eslint 9，期望 0 warning
+node scripts/e2e-full-closedloop.mjs      # 全闭环 E2E，需要服务在跑
+node scripts/test-sdk-surface.mjs         # SDK 导出面不允许漂移
+node scripts/check-docs-sync.mjs          # docs/site 与 docs/*.md 保持同步
+```
+3. **提交信息走约定式**——`commit-msg` 钩子跑 `commitlint`（`feat:` / `fix:` / `docs:` / `refactor:` / `perf:` / `test:` / `chore:`），`lint-staged` 会在提交时自动修复暂存的 JS/TS/Vue。
+4. **改了行为就补测试。** 本仓库以 `scripts/` 下的**真实 E2E 脚本**为主，而不是 mock——一条新的工业链路应该能被证明可跑通。
+> [!TIP]
+> 报 bug 之前先跑 `aw doctor`：它会端到端体检环境（Node 版本、配置根、端口占用、SQLite、可选的 Docker 服务），大多数「起不来」在这一步就有答案。
+## 安全
+发现漏洞请**不要**开公开 Issue，而应通过 [GitHub Security Advisories](https://github.com/kingdol666/AgentWorkShop/security/advisories/new) 私下报告，并附上复现步骤与受影响版本。
+当你把 AgentWorkShop 指向真实设备时，它就在驱动真实设备：接入现场 PLC 之前，请先复核 `config.yml` 里的联锁、安全量程与 HITL 设置。默认姿态是建议性的——写操作要过联锁、要经审批、要回读校验——但产线侧逻辑始终拥有最终否决权。
+---
+<div align="center">
+**如果这个项目对你有用，点一个 ⭐ 能让更多人找到它。**
+<a href="https://star-history.com/#kingdol666/AgentWorkShop&Date">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=kingdol666/AgentWorkShop&type=Date&theme=dark" />
+    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=kingdol666/AgentWorkShop&type=Date" />
+    <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=kingdol666/AgentWorkShop&type=Date" width="80%" />
+  </picture>
+</a>
+<br />
+**[在线文档](https://kingdol666.github.io/AgentWorkShop)** · **[上手指南](https://kingdol666.github.io/AgentWorkShop/guide/getting-started)** · **[插件 API](./docs/plugins.md)** · **[SDK](./docs/sdk.md)** · **[CLI](./docs/cli.md)** · **[English](./README.md)**
+<sub>基于 Nuxt 4 · Vue 3 · TypeScript · <code>node:sqlite</code> 构建 —— 监督层，秒级软实时。<br />
+时序关键回路请留在 PLC 内。</sub>
+</div>