agentworkshop 0.2.1

package/README.md

@@ -0,0 +1,424 @@
+<div align="center">
+
+<img src="docs/readme-assets/hero.png" alt="AgentWorkShop — Agents that run the production line" width="100%" />
+
+# AgentWorkShop
+
+**Where AI agent teams meet the production line.**
+
+[![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:sqlite-003B57?logo=sqlite&logoColor=white)](https://nodejs.org/api/sqlite.html)
+
+**[中文文档 →](./README-zh.md)**
+
+*A configuration-driven platform where **AI agent teams** and an **industrial digital twin** share one runtime — agents query real telemetry, issue supervisory setpoints through human-approved write control, and every event streams live to a 3D twin.*
+
+</div>
+
+> [!IMPORTANT]
+> **Positioning: supervisory layer.** AgentWorkShop is a *supervisory* (SCADA-adjacent) layer for production-line management, digital twins, DAQ and agent orchestration, operating at **second-level soft real-time**. It is **not** a hard real-time controller: any time-critical loop (**< 10 ms**, interlocks, safety, servo) **must live inside the PLC**. Setpoints written here are advisory — plant-side logic may veto.
+
+---
+
+## What is this?
+
+AgentWorkShop started as a **multi-agent software workshop** — channels of coding agents with a lead-agent scheduler, a 7-state task machine, persistent memory, and four interoperable entry points (WebSocket / MCP / A2A / REST).
+
+It grew an **industrial half**: a full data-acquisition and write-control stack (Modbus TCP / OPC UA), production lines with recipes and batch runs, a 3D digital-twin town — and the bridge that makes it unique: **agents can be granted bound, permission-scoped access to real industrial nodes**, query their live telemetry with physical semantics attached, and drive write operations through an interlock → human-in-the-loop → readback pipeline.
+
+The result: submit a goal like *"analyze the melt temperature trend and optimize the setpoint"* — and an agent team reads real sensor history, computes statistics, proposes a new setpoint, waits for your approval in the HITL panel, writes it to the PLC, verifies the readback, and reports the numbers back. **End to end, verified by automated E2E.**
+
+<div align="center">
+<img src="docs/readme-assets/town-demo.gif" alt="3D digital twin — live production line" width="86%" />
+<br><sub><b>Live 3D twin.</b> Line equipment, device health, DAQ channels and trend analysis — all driven by real-time telemetry.</sub>
+</div>
+
+---
+
+## Highlights
+
+| Capability | Why it matters |
+|---|---|
+| **Agent teams, industrial scope** | Agents bind to DAQ/DCW nodes and see semantic cards — physical meaning, units, safe range, recipe window — never raw registers. |
+| **Human-approved write control** | DCW writes flow through **safe-range ∩ recipe-window** interlock → optional **HITL approval** → PLC write → **readback verification** → signed write history. |
+| **Real field buses** | Modbus TCP with per-connection op queues; OPC UA with session pools. Linear calibration hooks (PLC value ↔ engineering unit) on every node. |
+| **Line operations** | Lines → products → recipes → batch runs. Recipe windows gate acquisition and interlock writes; every sample is tagged `product/recipe/run` for per-batch isolation. |
+| **Lead-agent orchestration** | Each channel has one lead: decomposes goals, dispatches to idle workers, reassigns failures, judges goal satisfaction. LLM decisions with a deterministic rule-engine fallback — the system never stalls. |
+| **Three execution modes** | `goal` (satisfaction judging) · `loop` (fixed-interval replay) · `pipeline` (ordered stages). 7-state task machine with progress, artifacts and full history. |
+| **Four entry points** | One manager behind every door: **WS** (AEP v1 event stream with seq-resume), **MCP** (in-process tools), **A2A** (JSON-RPC 2.0 + AgentCard), **REST**. |
+| **Persistent memory** | Private + channel-shared domains; FTS5 with CJK segmentation, optional vector hybrid recall, token-budgeted injection. |
+| **Harness-agnostic** | One `AgentInterface`: `mock` (in-process), `omp` (real agent subprocess via RPC), `claude` (SDK adapter). The platform never knows which one runs. |
+| **3D digital twin** | Three.js town: place line equipment and channel territories, watch device health, alarms and live values — driven by the same event bus. |
+
+---
+
+## Interface
+
+<div align="center">
+
+| Agent Workbench | Line Operations |
+|:---:|:---:|
+| ![Agent workbench](docs/readme-assets/workshop.png) | ![Line operations](docs/readme-assets/dcw.png) |
+
+| DAQ Center | Digital Twin Town |
+|:---:|:---:|
+| ![DAQ center](docs/readme-assets/daq.png) | ![Digital twin town](docs/readme-assets/town.png) |
+
+</div>
+
+---
+
+## Architecture
+
+```mermaid
+flowchart TB
+    subgraph FE["Frontend — Nuxt 4 / Vue 3"]
+        UI["Workshop UI · 3D Twin · Dashboards"]
+        WS["AEP client — seq resume"]
+    end
+    subgraph SRV["Server — Nitro / h3"]
+        REST["REST /api/workshop/**"]
+        HUB["WS Hub — AEP v1"]
+        A2A["A2A JSON-RPC"]
+        MCP["MCP Server"]
+        subgraph RT["Runtime"]
+            MGR["AgentChannelManager"]
+            SCH["SchedulerLoop — lead supervision"]
+            TE["TaskEngine — 7-state machine"]
+            AR["AgentRuntime × N"]
+            MEM["AgentMemory — FTS5 + vector"]
+            BUS["ChannelBus — per-channel seq + ring"]
+        end
+        subgraph IND["Industrial"]
+            DAQ["DAQ gateway — per-node edge runtimes"]
+            DCW["DCW gateway — write control"]
+            BR["Bus — inproc / MQTT"]
+            TSDB["TSDB — SQLite / Timescale"]
+        end
+        subgraph HB["Harness adapters"]
+            MOCK["mock"]
+            OMP["omp — real subprocess"]
+            CLD["claude — SDK"]
+        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 & CLD
+    MGR & TE & MEM & BUS --> DB
+    DAQ <--> BR --> TSDB
+    DCW --> BR
+    DAQ & DCW --> BUS
+```
+
+**The agent × machine bridge** (the part worth reading the source for):
+
+```
+agent ──binds to──▶ node (daq: auto / dcw: manual)
+  │                    │
+  │  my_industrial_nodes  ◀── semantic card: meaning · unit · safe range · recipe window
+  │  daq_query             ◀── TSDB history, stats + physical semantics
+  │  dcw_control           ──▶ interlock (safe range ∩ recipe window)
+  │                           ──▶ HITL approval (manual mode, 180 s timeout)
+  │                           ──▶ PLC write → readback check → ACK + write history
+  ◀── result text with numbers the agent can cite
+```
+
+---
+
+## Quick start
+
+### Prerequisites
+
+```bash
+node -v   # ≥ 23.4.0  (needs built-in node:sqlite)
+```
+
+> The `omp` harness (recommended for real work) requires the `omp` CLI on PATH. The `mock` harness works out of the box for demos and CI. Optional DAQ infrastructure (MQTT broker + TimescaleDB) auto-starts via Docker when reachable (`docker compose up -d`).
+
+### Option A — install from npm (recommended)
+
+```bash
+npm install -g agentworkshop     # → `aw` / `agentworkshop` on PATH
+aw start                         # first run builds once (~2-3 min) → http://localhost:3001
+```
+
+That's it — no checkout, no build tools. On first launch everything initializes into the config root **`~/.AgentWorkShop`**: the default `config.yml`, a generated `.env` holding a random session secret, `runtime-settings.json`, a docker-compose seed and an empty `data/` directory. All runtime data (SQLite, JSON repos, backups, logs) lives there too — config and data stay with the install, not the working directory.
+
+Prefer a one-off run without installing?
+
+```bash
+npx agentworkshop start          # fetch + run, nothing persisted globally
+```
+
+### Option B — from source
+
+```bash
+git clone https://github.com/kingdol666/AgentWorkShop.git && cd AgentWorkShop
+pnpm install
+pnpm dev          # → http://localhost:3000  (port from config.yml)
+```
+
+Production from source:
+
+```bash
+pnpm build        # nuxt build → .output/
+pnpm start        # port from config.yml → server.prod.port
+```
+
+> In a source checkout the config root is the project's **`.AgentWorkShop/`** folder (runtime overrides, data, project-level commands), while `config.yml` / `.env` stay at the checkout root, version-controlled as the factory defaults.
+
+### Updating
+
+```bash
+aw update                              # check + self-update the global install
+aw update --check                      # only report; nothing is installed
+npm install -g agentworkshop@latest    # manual equivalent
+```
+
+Releases follow semver. Every `aw start` verifies the config root and migrates it in place when a new version changes the layout — your data survives upgrades.
+
+### Your first agent × line session (~2 minutes)
+
+1. **Sign in** — register in the sidebar (or `POST /api/users/register`).
+2. **Build a line** — `Line Operations` → create a line, add DAQ nodes (e.g. `daq-temp-tc`) and control nodes (e.g. `dcw-temp-sp`), create a product + recipe, hit **Start**. Live values start flowing.
+3. **Create a team** — `Agent Workshop` → pick a lead + workers, **deploy** into a channel.
+4. **Bind nodes** — open the agent's detail panel → bind the DAQ node (*auto*) and the control node (*manual* = needs your approval).
+5. **Submit the goal** — *"Analyze the last 5 minutes of melt temperature; if deviation from 182 °C exceeds 1 °C, correct the setpoint (wait for my approval)."*
+6. **Approve** — the agent reads real history, computes the mean, requests the write → approve in the HITL panel → watch the setpoint change and the goal close with a numeric report.
+
+---
+
+## Configuration & CLI — config-driven by design
+
+One runtime, one source of truth. **`config.yml`** declares defaults; **`runtime-settings.json`** inside the config root carries runtime overrides; environment variables and CLI flags sit on top. Every editable key is described once in `shared/config/schema.json` (type, range, enum, live-vs-restart) and surfaced through the same descriptors in **both the UI and the CLI**.
+
+```
+config.yml (defaults)  <  .AgentWorkShop/runtime-settings.json (runtime)  <  env vars / CLI flags
+```
+
+The config root is **`~/.AgentWorkShop`** for a global install (`npm i -g`) — wherever you run `aw` from — and **`<repo>/.AgentWorkShop`** in a source checkout (with `config.yml` / `.env` staying at the checkout root as version-controlled factory defaults). `AW_HOME` redirects it; `AW_MODE=home` forces the global shape.
+
+### Live settings, persisted, hot-reloaded
+
+- The **Settings → Runtime config** tab renders every editable key from the descriptors — change server ports, theme, API timeouts, locale or the approval gate, hit save.
+- `live` keys apply instantly (theme, title, timeouts, approval gate…) over a server-sent event stream — no reload, no restart.
+- `restart` keys (ports, hosts) persist to disk and take effect on the next launch of the matching mode (`aw dev` / `aw start`).
+- One channel for every writer: the UI, the CLI and the server's file watcher all converge on the same settings file, so a change made anywhere shows up everywhere.
+
+### The `aw` CLI
+
+| Command | What it does |
+|---|---|
+| `aw start · aw dev · aw build` | Production server / dev server / build — ports from the effective config; first `start` builds once |
+| `aw config list · get · set · unset · reset` | Read & write runtime settings (validated against the schema, atomic writes) |
+| `aw home` | Inspect / initialize the config root `.AgentWorkShop` |
+| `aw init <dir>` | Scaffold a runnable project (full config system + CLI included) |
+| `aw register <path\|url\|npm:pkg>` | Register a new command — project-local or `--global` |
+| `aw update` | Check npm for the latest release and self-update the global install |
+| `aw doctor` | Environment + project health check (node, config, ports, keys) |
+| `aw status` | Live overview: mode, config sources, running server, command table |
+
+Global flags: `--help/-h` · `--version/-v` · `--json` (machine-readable) · `--root <dir>` · `--debug`.
+
+### Command registration
+
+Commands are plain modules exporting `{ meta, run }`. Drop one into a scanned directory and it's live on the next invocation — no registry bookkeeping, convention over configuration:
+
+| Scope (highest wins) | Directory |
+|---|---|
+| project | `<root>/.AgentWorkShop/commands/` |
+| user | `~/.AgentWorkShop/commands/` |
+| built-in | packaged with the CLI (`cli/commands/`) |
+
+`aw register <file|url|npm:pkg>` copies a command into the right scope (`--global` for user scope); `aw help` lists everything that's registered.
+
+```js
+// ~/.AgentWorkShop/commands/hello.mjs
+export const meta = { name: 'hello', group: 'Custom', summary: 'Say hi', usage: 'aw hello [--name <n>]' }
+export async function run(argv, ctx) {
+  console.log(`Hi ${argv.flags.name ?? 'AW'} — mode: ${ctx.mode}`)
+}
+```
+
+---
+
+## The industrial stack in detail
+
+### Data acquisition (DAQ)
+
+- **Per-node edge runtimes**: independent sampling cadence, publish cadence, in-flight mutex per node — one slow driver never blocks its neighbors.
+- **Pipeline**: driver → queue (in-process or MQTT, offline buffer on disconnect) → consumer with out-of-order defense → three-way fan-out: WS live push (gated), TSDB batch write, device-twin writeback.
+- **Robustness**: TSDB single-in-flight writes with bounded retries, buffer backpressure with drop counters, real loss metrics exposed on `daq.controller` frames.
+- **Alarms**: recipe-scoped monitoring windows with **2 % hysteresis + 3-tick debounce**; alarm/offline transitions are instant (safety first).
+
+### Write control (DCW)
+
+- Engineering-unit writes: `linear` calibration (scale/offset) PLC↔physical, **readback verification** with deadband tolerance, ACK states and write history.
+- **Interlock**: with a line running, the active recipe's parameter window *replaces* the node's global safe range for that node.
+- **HITL**: `manual`-mode bindings suspend the write for user approval (deduped per agent+node; re-validation at approval time — permission is re-checked when you click approve).
+
+### Recipe & batch
+
+`Line → Product → Recipe → Run`. Starting a run applies recipe params node-by-node (each write verified), gates acquisition per line, and tags every sample with `line/product/recipe/run` — per-product data isolation with five-dimension queries (line × product × recipe × time × node).
+
+---
+
+## Usage
+
+### Authentication
+
+Email + password login issues a **bearer token** (multiple tokens per user, individually revocable).
+
+```bash
+# register
+curl -X POST http://localhost:3000/api/users/register \
+  -H 'content-type: application/json' \
+  -d '{"email":"you@example.com","password":"secret","name":"you"}'
+
+# every workshop call
+curl http://localhost:3000/api/workshop/channels \
+  -H 'authorization: Bearer <token>'
+```
+
+### Execution modes
+
+Prefix the task description (or pick in the composer UI):
+
+| Mode | Semantics | Config |
+|---|---|---|
+| `goal` | lead decomposes → workers deliver → **lead judges satisfaction**; unmet → more subtasks; met → parent completes. | `goalCriteria` |
+| `loop` | replay the same task on a fixed interval. | `intervalMs` (default 60 000), `maxIterations` (default ∞) |
+| `pipeline` | ordered stages; stage N+1 consumes stage N's output. | `stages: [{name, description, assigneeId?}]` |
+
+### The four entry points
+
+| Entry | Endpoint | Audience |
+|---|---|---|
+| **WS** | `/api/workshop/ws?channelId=…` | Dashboards / UI — AEP v1 envelopes, per-channel monotonic `seq`, 5 000-event ring, `lastSeq` resume, snapshot fallback. |
+| **MCP** | in-process server, ~20 tools | Agents (omp host tools) — management + job-face tools, channel-scoped. |
+| **A2A** | `POST /api/workshop/a2a/:agentId/rpc` | External agents — JSON-RPC 2.0, `AgentCard` at `/card`, `tasks/sendSubscribe` SSE. |
+| **REST** | `/api/workshop/**` | Humans / scripts — full management face. |
+
+### Task state machine
+
+```
+SUBMITTED ─▶ ASSIGNED ─▶ WORKING ─▶ WAITING ─▶ COMPLETED
+    │            │           │           │
+    └────────────┴───────────┴──▶ CANCELED / FAILED ─▶ (retry ≤ 3 or cancel)
+```
+
+---
+
+## Verified end-to-end
+
+The repo ships live E2E that exercises the full loop against a running server — the numbers below are from an actual run:
+
+| Check | Result |
+|---|---|
+| Line start → recipe writes setpoint (180 °C) | ✅ |
+| Interlock: write 170 (<176) and 200 (>188) → **400 rejected** | ✅ |
+| Team deploy → goal dispatch (lead → omp worker) | ✅ t + 3 s |
+| Worker reads real history: **mean 168.05 °C, 96 samples, min/max/latest** | ✅ |
+| HITL approval → setpoint **180 → 182 °C** written & read back | ✅ |
+| Goal closes with structured summary | ✅ |
+| Batch tagging: samples carry product/recipe/run | ✅ |
+
+Reproduce: `node scripts/_dbg-full-feature-e2e.mjs` (against a running server).
+
+---
+
+## Project layout
+
+```
+AgentWorkShop/
+├── bin/ · cli/                 # aw CLI — command registry · built-in commands · config engine
+├── app/                        # Nuxt 4 frontend (srcDir)
+│   ├── pages/                  # / · /workshop · /town · /daq · /dcw · /monitor · /users · /tokens
+│   ├── components/workshop/    # timeline · lanes · task board · memory panel · 3D town
+│   └── stores/composables/     # Pinia + AEP client
+├── server/
+│   ├── api/                    # REST + WS + A2A + MCP routes
+│   ├── services/workshop/
+│   │   ├── runtime/            # manager · scheduler-loop · task-engine · memory · mailbox
+│   │   ├── agents/             # AgentInterface: mock · omp · claude (+ industrial tools)
+│   │   ├── daq/ dcw/           # edge runtimes · drivers · bus · storage
+│   │   └── db/                 # repos over node:sqlite
+│   ├── mcp/                    # MCP server (tools)
+│   └── plugins/                # runtime assembly (singletons)
+├── shared/
+│   └── config/                 # schema.json (settings descriptors) + engine (merge/validate/persist) + mode/path resolver
+├── config.yml                  # ⚙ single source of truth (factory defaults)
+├── .AgentWorkShop/             # config root — prompts (versioned) + runtime overrides · data · logs · commands (git-ignored)
+├── data/                       # legacy pre-migration location (auto-migrated into the config root)
+└── scripts/                    # launchers · home bootstrap · E2E · verification suites
+```
+
+## Tech stack
+
+| Layer | Tech |
+|---|---|
+| Framework | [Nuxt 4](https://nuxt.com) + Nitro (WebSocket) |
+| UI | Vue 3.5 · Pinia · Ant Design Vue · UnoCSS · Three.js · ECharts |
+| Language | TypeScript 5.7 across the stack; `shared/` used by both sides |
+| CLI | Node ESM CLI with a pluggable command registry (`bin/aw.mjs`) |
+| Persistence | `node:sqlite` (zero native deps) + FTS5 + optional `sqlite-vec`; TimescaleDB for time-series |
+| Validation | `zod` at every message boundary |
+| Interop | `@modelcontextprotocol/sdk` · A2A (JSON-RPC 2.0) · AEP v1 (in-house WS protocol) |
+| Field bus | `modbus-serial` · `node-opcua` · `mqtt` |
+
+## Development
+
+```bash
+pnpm dev          # dev server (port from effective config)
+pnpm aw …         # the CLI is available in-repo too: pnpm aw config list
+pnpm build && pnpm start
+pnpm typecheck
+pnpm lint
+node scripts/_dbg-full-feature-e2e.mjs    # full-feature live E2E (server must be running)
+```
+
+## Roadmap
+
+| Capability | Status |
+|---|---|
+| Channel runtime, lead orchestration, 7-state task engine | Shipped |
+| Four entry points: WS (AEP v1) · MCP · A2A · REST | Shipped |
+| Persistent memory (FTS5 + optional vector hybrid) | Shipped |
+| Industrial stack: DAQ · DCW write control · lines/recipes/runs | Shipped |
+| Agent ↔ node binding + HITL approval + interlock | Shipped |
+| 3D digital-twin town · line operations UI · dashboards | Shipped |
+| Full-feature live E2E (agent reads/writes a real line, 23 checks) | Shipped |
+| Runtime configuration system: settings persistence · hot reload · settings UI | Shipped |
+| `aw` CLI: config · run · init · register · doctor | Shipped |
+| Claude Agent SDK adapter — full parity with `mock`/`omp` | In progress |
+| Production hardening: TLS, MQTT auth, OPC UA sign+encrypt defaults, structured audit log | Planned |
+| Edge deployment shape: standalone edge-agent + central broker | Planned |
+| Alarm outbound delivery (email/webhook) + ack workflow | Planned |
+| CI pipeline (typecheck + lint + e2e) | Planned |
+| License file | Pending |
+
+## License
+
+AgentWorkShop is an independent project and is **not an official product of Anthropic** or any LLM vendor. It integrates with agent harnesses (e.g. `omp`) through their public interfaces.
+
+**License is TBD** — the license file will be added before the `v1.0` release.
+
+<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>

package/app/.mimosa/hook-state/sess_05189059-e42d-4188-8911-4f7baabe009b.json

@@ -0,0 +1 @@
+{"touched":["D:\\codes\\ABO\\AgentWorkShop\\app\\composables\\workshop\\apiClient.ts","D:\\codes\\ABO\\AgentWorkShop\\app\\composables\\workshop\\useDaqStream.ts","D:\\codes\\ABO\\AgentWorkShop\\app\\composables\\workshop\\useDcwStream.ts","D:\\codes\\ABO\\AgentWorkShop\\app\\composables\\workshop\\useDeviceTwins.ts"],"bashMutation":true,"reportedFindings":[],"findingEvents":[],"baseline":{"storageId":"mtg0vz68-49792-75b0709555","createdAt":"2026-08-30T16:27:28.592Z","files":{"composables/workshop/apiClient.ts":{"existed":false},"composables/workshop/useDaqStream.ts":{"existed":true,"snapshot":"c2991e909c70c5c12b90a407c7adcf63384c51668a2b334e6e047fa675c268fe.source"},"composables/workshop/useDcwStream.ts":{"existed":true,"snapshot":"e09129039d1e27e3fac24becc9bdafd2d1a7c8049bff24173df007be865f0165.source"},"composables/workshop/useDeviceTwins.ts":{"existed":true,"snapshot":"1459e6269990a5d229b9228c8b2f62ffaa7d350068380ae8b875fee0db45cca6.source"}},"complete":false,"candidateLimit":5000,"discoveredFiles":0,"capturedFiles":4,"truncated":false,"omittedAtLeast":0,"firstOmitted":"","errors":[{"stage":"baseline-capture","target":".","reason":"global task baseline was unavailable; captured only the touched file"},{"stage":"baseline-snapshot","target":"../nuxt.config.ts","reason":"file is outside project"}]},"stateErrors":[],"omittedReportedFindings":0,"omittedFindingEvents":0,"processing":null,"updatedAt":"2026-08-31T05:07:01.176Z"}

package/app/.mimosa/hook-state/sess_05189059-e42d-4188-8911-4f7baabe009b.mtg0vz68-49792-75b0709555.baseline/1459e6269990a5d229b9228c8b2f62ffaa7d350068380ae8b875fee0db45cca6.source

@@ -0,0 +1,180 @@
+/**
+ * useDeviceTwins —— 数字孪生设备(前端注册表 + REST 拉取/创建/控制/遥测)。
+ *
+ * 职责:
+ *  - 拉取设备列表(GET /api/workshop/device-twins);
+ *  - 拖模型进 3D 场景时创建设备(POST)+ 绑定实体模型 modelRef;
+ *  - 下发指令(POST /:id/control)、推送遥测(POST /:id/telemetry);
+ *  - 轮询刷新 telemetry/state(驱动 3D 设备节点颜色/偏移)。
+ * 单例挂 globalThis,跨组件安全;store 为 reactive(异步刷新后驱动组件重渲染)。
+ */
+import { reactive } from 'vue'
+
+export interface DeviceTwinView {
+  id: string
+  workspaceId: string
+  name: string
+  modelRef: string
+  boundAgentId: string | null
+  kind: string
+  telemetry: Record<string, number | string | boolean>
+  desired: Record<string, number | string | boolean>
+  state: 'idle' | 'running' | 'offline' | 'alarm'
+  controls: string[]
+  /** 3D 场景落点 / 朝向 / 缩放(undefined = 未放入场景) */
+  posX?: number
+  posZ?: number
+  rotationY?: number
+  scale?: number
+  /** 所属产线(数采/智控节点;场景光晕分色) */
+  lineId?: string
+  /** 产线光晕色(Hex) */
+  lineColor?: string
+  updatedAt: string
+}
+
+const GLOBAL_KEY = '__deviceTwins'
+
+/** 设备孪生 scene transform 补丁(供拖拽/滑杆结束防抖保存) */
+export interface DeviceTransformPatch {
+  name?: string
+  modelRef?: string
+  posX?: number
+  posZ?: number
+  rotationY?: number
+  scale?: number
+}
+
+interface DeviceTwinStore {
+  twins: DeviceTwinView[]
+  loaded: boolean
+  error: string
+  /** in-flight 请求 promise(去重用) */
+  __loading?: Promise<void> | null
+  load(): Promise<void>
+  applyRemote(twin: DeviceTwinView): void
+  removeRemote(id: string): void
+  byId(id: string): DeviceTwinView | undefined
+  create(input: { name: string, modelRef?: string, workspaceId?: string, kind?: string, controls?: string[], telemetry?: Record<string, number | string | boolean>, posX?: number, posZ?: number, rotationY?: number, scale?: number }): Promise<DeviceTwinView>
+  update(id: string, patch: DeviceTransformPatch): Promise<DeviceTwinView>
+  control(id: string, command: string, args?: Record<string, unknown>): Promise<DeviceTwinView>
+  pushTelemetry(id: string, telemetry: Record<string, number | string | boolean>): Promise<DeviceTwinView>
+  remove(id: string): Promise<void>
+}
+
+function headers(json = true): Record<string, string> {
+  const cookieToken = typeof document !== 'undefined'
+    ? (document.cookie.match(/(?:^|;\s*)token=([^;]+)/)?.[1] ?? '')
+    : ''
+  const h: Record<string, string> = {}
+  if (cookieToken) h.authorization = `Bearer ${decodeURIComponent(cookieToken)}`
+  if (json) h['content-type'] = 'application/json'
+  return h
+}
+
+function createStore(): DeviceTwinStore {
+  const twins: DeviceTwinView[] = []
+  const store: DeviceTwinStore = reactive({
+    twins,
+    loaded: false,
+    error: '',
+    async load() {
+      // in-flight 去重:多消费方同帧触发只发一次请求(轮询 + 事件回灌叠加期防请求风暴)
+      if (store.__loading) return store.__loading
+      store.__loading = (async () => {
+        try {
+          const res = await fetch('/api/workshop/device-twins', { headers: headers() })
+          const json = await res.json().catch(() => ({}))
+          // 经 reactive 代理变更,驱动 DeviceTwinPanel 等组件重渲染
+          store.twins.splice(0, store.twins.length, ...(json?.data?.twins ?? []))
+          store.loaded = true
+          store.error = ''
+        }
+        catch (err) {
+          store.loaded = false
+          store.error = err instanceof Error ? err.message : String(err)
+        }
+        finally {
+          store.__loading = null
+        }
+      })()
+      return store.__loading
+    },
+    /** WS 增量合并(device.updated 事件直推;免全量重拉) */
+    applyRemote(twin: DeviceTwinView) {
+      const i = store.twins.findIndex(t => t.id === twin.id)
+      if (i >= 0) Object.assign(store.twins[i]!, twin)
+      else store.twins.push({ ...twin })
+    },
+    /** WS 删除收敛 */
+    removeRemote(id: string) {
+      const i = store.twins.findIndex(t => t.id === id)
+      if (i >= 0) store.twins.splice(i, 1)
+    },
+    byId(id) {
+      return twins.find(t => t.id === id)
+    },
+    async create(input) {
+      const res = await fetch('/api/workshop/device-twins', {
+        method: 'POST',
+        headers: headers(),
+        body: JSON.stringify(input),
+      })
+      const json = await res.json().catch(() => ({}))
+      if (!res.ok || !json?.data?.twin) throw new Error(json?.message ?? '创建设备失败')
+      store.loaded = false
+      await store.load()
+      return json.data.twin
+    },
+    async update(id, patch) {
+      const res = await fetch(`/api/workshop/device-twins/${id}`, {
+        method: 'PATCH',
+        headers: headers(),
+        body: JSON.stringify(patch),
+      })
+      const json = await res.json().catch(() => ({}))
+      if (!res.ok || !json?.data?.twin) throw new Error(json?.message ?? '更新设备失败')
+      store.loaded = false
+      await store.load()
+      return json.data.twin
+    },
+    async control(id, command, args) {
+      const res = await fetch(`/api/workshop/device-twins/${id}/control`, {
+        method: 'POST',
+        headers: headers(),
+        body: JSON.stringify({ command, args: args ?? {} }),
+      })
+      const json = await res.json().catch(() => ({}))
+      if (!res.ok || !json?.data?.twin) throw new Error(json?.message ?? '指令下发失败')
+      store.loaded = false
+      await store.load()
+      return json.data.twin
+    },
+    async pushTelemetry(id, telemetry) {
+      const res = await fetch(`/api/workshop/device-twins/${id}/telemetry`, {
+        method: 'POST',
+        headers: headers(),
+        body: JSON.stringify({ telemetry }),
+      })
+      const json = await res.json().catch(() => ({}))
+      if (!res.ok || !json?.data?.twin) throw new Error(json?.message ?? '遥测推送失败')
+      store.loaded = false
+      await store.load()
+      return json.data.twin
+    },
+    async remove(id) {
+      await fetch(`/api/workshop/device-twins/${id}`, { method: 'DELETE', headers: headers() })
+      store.loaded = false
+      await store.load()
+    },
+  })
+  return store
+}
+
+export function useDeviceTwins(): DeviceTwinStore {
+  const g = globalThis as unknown as Record<string, DeviceTwinStore | undefined>
+  if (!g[GLOBAL_KEY]) g[GLOBAL_KEY] = createStore()
+  const store = g[GLOBAL_KEY]!
+  void store.load()
+  return store
+}