agentworkshop 0.7.34 → 0.7.38

package/sdk/examples/line-sentinel/index.mjs

@@ -19,7 +19,9 @@ export default {
 
     // 平台服务消费:启动时经 SDK API 客户端读取产线清单(自环调用)
     try {
-      const lines = await ctx.api.lines.list()
+      // ⚠️ GET /api/workshop/dcw/lines 返回的是 { lines, states } —— **不是数组**。
+      // 旧写法 Array.isArray(lines) 恒为 false,linesTotal 永远是 0(静默错误)。
+      const { lines } = await ctx.api.lines.list()
       ctx.kv.set('linesTotal', Array.isArray(lines) ? lines.length : 0)
       ctx.logger.info(`平台产线清单: ${ctx.kv.get('linesTotal')} 条`)
     }
@@ -81,7 +83,8 @@ export default {
         .map(([k, v]) => ({ nodeId: k.slice(6), ...v }))
       return {
         plugin: ctx.name,
-        version: ctx.version,
+        // ctx 上没有 version(插件版本由 manifest 记录);这里报 SDK 版本才有意义
+        sdkVersion: ctx.sdkVersion,
         running: ctx.kv.get('running') ?? false,
         runningCount: ctx.kv.get('runningCount') ?? 0,
         heartbeat: ctx.kv.get('heartbeat'),

package/sdk/examples/ops-notifier/client.mjs

@@ -8,7 +8,9 @@ export function setup(ctx) {
   ctx.root().prepend(toast)
 
   let timer = null
-  ctx.on('dcw:write', (w) => {
+  // scene 事件名是 'dcw.written'(写控 ACK 后对浏览器广播);服务端钩子 'dcw:write'
+  // 不过桥到浏览器,在这里订阅它只会得到永不触发的空订阅。
+  ctx.on('dcw.written', (w) => {
     toast.textContent = w.ok
       ? `✔ 写入 ${w.name} → ${w.eng}${w.source ? `(${w.source})` : ''}`
       : `✖ 写入失败 ${w.name}`

package/sdk/examples/sample-insight/client.mjs

@@ -10,12 +10,14 @@ export function setup(ctx) {
   ctx.root().append(badge)
 
   let n = 0
-  ctx.on('daq:sample', () => {
+  // scene 事件名直传('daq.reading' 是 DAQ 采样对浏览器广播的真实事件名)
+  ctx.on('daq.reading', () => {
     n++
     badge.textContent = `⌁ sample-insight · ${n} 样本`
   })
 
-  ctx.on('page:change', ({ path }) => {
+  // 生命周期钩子(含 page:change)不走 ctx.on —— 它只装 scene 事件。走 ctx.hooks 直订。
+  ctx.hooks.on('page:change', ({ path }) => {
     ctx.log.info('page →', path)
   })
 

package/sdk/index.d.mts

@@ -33,30 +33,120 @@ export interface PluginHttp {
   post(url: string, body?: unknown, opts?: { timeoutMs?: number, headers?: Record<string, string> }): Promise<Response>
 }
 
-/** 平台 REST 客户端(SDK 作为项目服务 client 的门面) */
+/** 资源面公共形状 —— 对应 sdk/api.mjs 的 `resource(root)`,每个资源都有完整五项。
+ *  (旧版声明只写了 list/create,导致 `api.products.update()` 等运行时可用、TS 却报错。) */
+export interface CrudResource {
+  list(query?: Record<string, unknown>): Promise<any>
+  get(id: string): Promise<any>
+  create(body: unknown): Promise<any>
+  update(id: string, patch: unknown): Promise<any>
+  remove(id: string): Promise<any>
+}
+
+/** 平台 REST 客户端(SDK 作为项目服务 client 的门面)
+ *  自动携带 Bearer token、自动解信封 `{code,message,data} → data`;
+ *  非 2xx 或信封 `code !== 0` 均抛错(错误上带 `status` / `code` / `body`)。 */
 export interface PlatformClient {
-  call<T = any>(method: string, path: string, body?: unknown): Promise<T>
+  call<T = any>(method: string, path: string, body?: unknown, opt?: { timeoutMs?: number, headers?: Record<string, string> }): Promise<T>
   get<T = any>(path: string, query?: Record<string, unknown>): Promise<T>
   post<T = any>(path: string, body?: unknown): Promise<T>
   patch<T = any>(path: string, body?: unknown): Promise<T>
   delete<T = any>(path: string): Promise<T>
   setToken(token: string | null): PlatformClient
+  /** 存活探测(免鉴权;GET /api/plugins/manifest) */
   ping(): Promise<any>
-  users: { list(q?: any): Promise<any>, get(id: string): Promise<any>, create(b: any): Promise<any>, login(email: string, password: string): Promise<any>, me(): Promise<any> }
-  lines: { list(q?: any): Promise<any>, get(id: string): Promise<any>, create(b: any): Promise<any>, update(id: string, p: any): Promise<any>, remove(id: string): Promise<any>, start(id: string, recipeId?: string): Promise<any>, stop(id: string): Promise<any> }
-  products: { list(q?: any): Promise<any>, create(b: any): Promise<any> }
-  recipes: { list(q?: any): Promise<any>, create(b: any): Promise<any> }
-  dcwNodes: { list(q?: any): Promise<any>, create(b: any): Promise<any> }
-  daqNodes: { list(q?: any): Promise<any>, create(b: any): Promise<any>, alarms(): Promise<any> }
+  users: CrudResource & { login(email: string, password: string): Promise<any>, me(): Promise<any> }
+  lines: CrudResource & { start(id: string, recipeId?: string): Promise<any>, stop(id: string): Promise<any> }
+  products: CrudResource
+  recipes: CrudResource
+  dcwNodes: CrudResource
+  daqNodes: CrudResource & { alarms(): Promise<any> }
   templates: { daq(): Promise<any[]>, dcw(): Promise<any[]> }
-  twins: { list(q?: any): Promise<any>, create(b: any): Promise<any> }
-  teams: { list(q?: any): Promise<any>, create(b: any): Promise<any> }
-  agents: { list(q?: any): Promise<any>, create(b: any): Promise<any> }
-  channels: { list(q?: any): Promise<any> }
+  twins: CrudResource
+  teams: CrudResource
+  agents: CrudResource
+  channels: CrudResource
+  /** 产线授权面(admin):overview() 全量总览,set() 批量写 { userId, grants:[{lineId,mode}] } */
+  permissions: { overview(): Promise<any>, set(payload: unknown): Promise<any> }
   plugins: { manifest(): Promise<any> }
 }
 
-export interface PluginContext {
+/** `config:changed` 载荷(host.mjs relayConfigEvents) */
+export interface ConfigChangedPayload {
+  type: 'config:changed'
+  /** 变更的顶层键 */
+  changed?: string[]
+  /** 合并后的有效配置快照 */
+  effective?: Record<string, any>
+  /** 各键来源(config.yml / runtime / env) */
+  sources?: Record<string, string>
+}
+
+/** 插件自带设置字段声明(manifest `settings[]`,等价于运行时 ctx.config.defineField)
+ *  校验规则(host.mjs setPluginSettings / context.mjs validatePluginSettings):
+ *  key 需匹配 /^[A-Za-z0-9_-]+$/;type 必须是下列四种之一;**default 必填**,否则整条跳过并告警;
+ *  select 的 options 必须包含 default;min/max 仅对 number 生效;label 与 labelKey 至少给一个。 */
+export interface PluginSettingDecl {
+  key: string
+  type: 'string' | 'number' | 'boolean' | 'select'
+  /** 必填:缺失的条目会被静默跳过(仅告警),不会出现在设置页 */
+  default: unknown
+  min?: number
+  max?: number
+  options?: string[]
+  /** i18n 键(形如 plugin.<name>.<key>);与 label 至少给一个 */
+  labelKey?: string
+  label?: string
+  description?: string
+  /** 归属分组 id(引用同一 manifest 的 configGroups[].id) */
+  group?: string
+}
+
+/** 插件自带配置分组声明 —— **manifest 字段名是 `configGroups`**(host.mjs `def.configGroups`),
+ *  写成 `groups` 会被静默忽略。两个内置插件(rag-bridge / diag-bridge)均用 `configGroups`。 */
+export interface PluginGroupDecl {
+  id: string
+  /** 与 labelKey 至少给一个(validatePluginGroups 取 label ?? labelKey) */
+  label?: string
+  labelKey?: string
+  description?: string
+  order?: number
+  collapsed?: boolean
+}
+
+/** 宿主注入的扩展面 —— 不在 sdk/context.mjs 内,由插件宿主 host.mjs 在 setup 前挂载。
+ *  类型在此内联声明,使 TS 插件作者无需宿主类型包即可获得提示。 */
+export interface PluginHostExtensions {
+  /** 数采扩展面(host.mjs):注册驱动/处理器/模板 + 帧订阅 + 免鉴权时序查询 */
+  daq?: {
+    registerDriver(driver: unknown): boolean
+    registerProcessor(kind: string, name: string, fn: (frame: any) => any): boolean
+    registerTemplate(def: unknown): boolean
+    onFrame(fn: (payload: any) => any): () => void
+    onSample(fn: (payload: any) => any): () => void
+    query(q: { nodeIds?: string[], lineId?: string, from?: number, to?: number, bucketMs?: number }): Promise<any>
+    nodes(): Promise<any>
+  }
+  /** Agent 工具注入面:注册的 host 工具热注入全部 harness 的会话(受团队插件开关过滤) */
+  omp?: {
+    registerTool(tool: {
+      name: string
+      label?: string
+      description?: string
+      parameters?: Record<string, unknown>
+      roles?: string[]
+      handler: (args: any, ctx?: any) => any
+    }): void
+  }
+  /** 后端运行时对象面:只读取数 + 跨插件服务(provide 自动加 `<plugin>.` 前缀) */
+  services?: {
+    names(): string[]
+    get<T = any>(name: string): Promise<T>
+    provide(name: string, getter: () => any): void
+  }
+}
+
+export interface PluginContext extends PluginHostExtensions {
   name: string
   /** 插件来源作用域(host.mjs discoverPluginDirs:builtin / project / user) */
   scope: 'builtin' | 'project' | 'user'
@@ -67,7 +157,16 @@ export interface PluginContext {
   config: {
     get(key: string): any
     all(): Record<string, any>
-    onChange(fn: (payload?: { at: string }) => any): () => void
+    onChange(fn: (payload?: ConfigChangedPayload) => any): () => void
+    /** 声明式注册本插件专属配置分组(id 收敛进 plugin-<name> 命名空间,卸载自动摘除) */
+    defineGroup(def: PluginGroupDecl): void
+    /** 声明式注册配置字段(等价 manifest settings[],key 自动编址 plugins.<name>.<key>) */
+    defineField(decl: PluginSettingDecl): void
+    removeGroup(id: string): void
+    removeField(key: string): void
+    /** 本插件当前已注册的分组 / 字段(只读快照) */
+    groups(): PluginGroupDecl[]
+    fields(): PluginSettingDecl[]
   }
   paths: { home: string, configRoot: string, dataDir: string }
   dataDir: string
@@ -101,6 +200,13 @@ export interface PluginDef {
   name: string
   version?: string
   description?: string
+  /** 插件 API 转发层鉴权:none(默认)| user | admin | agent-or-user(host.mjs registerRoute) */
+  auth?: 'none' | 'user' | 'admin' | 'agent-or-user' | string
+  /** 自带设置声明:宿主并入 SystemConfigService,设置页按分组渲染 */
+  settings?: PluginSettingDecl[]
+  /** 自带配置分组声明(settings[].group 引用其 id)。
+   *  ⚠️ 字段名就是 configGroups —— 宿主读的是 def.configGroups,写 `groups` 无效。 */
+  configGroups?: PluginGroupDecl[]
   setup?(ctx: PluginContext): void | Promise<void>
   client?: string
   routes?: PluginRouteDef[]
@@ -119,13 +225,24 @@ export declare function createRouteTable(): {
 export declare function validatePluginModule(mod: any, source: string): { ok: boolean, def?: PluginDef, error?: string }
 export declare function pluginKvExists(dataDir: string, name: string): boolean
 
+/** 路径包含判定(插件目录越界防护;同前缀兄弟目录不会被误放行) */
+export declare function isPathInside(dir: string, p: string): boolean
+/** 把插件声明的分组 id 收敛进 plugin-<name>[-<suffix>] 命名空间;非法 id 回落到主分组 */
+export declare function resolvePluginGroupId(pluginName: string, declaredId?: string): string
+/** 校验 manifest.configGroups;返回 { groups, errors }(无 ok 字段 —— 只看 groups.length) */
+export declare function validatePluginGroups(pluginName: string, defs: unknown): { groups: PluginGroupDecl[], errors: string[] }
+/** 校验 manifest.settings;default 缺失的条目会被跳过并记入 errors */
+export declare function validatePluginSettings(pluginName: string, defs: unknown, opts?: { defaultGroup?: string }): { descriptors: PluginSettingDecl[], errors: string[] }
+
 export declare function createPlatformClient(opts?: { baseUrl?: string, token?: string, logger?: PluginLogger, timeoutMs?: number }): PlatformClient
 
-export declare const LIFECYCLE_EVENTS: readonly ['plugin:host:init', 'config:changed', 'permissions:changed', 'event:*', 'daq:sample', 'daq:frame', 'dcw:write', 'line:start', 'line:stop', 'server:close']
-export declare const CLIENT_EVENTS: readonly ['client:init', 'event:*', 'page:change', 'client:destroy']
+export declare const LIFECYCLE_EVENTS: readonly ['plugin:host:init', 'plugins:reloaded', 'config:changed', 'event:permissions:changed', 'event:*', 'daq:sample', 'daq:frame', 'dcw:write', 'line:start', 'line:stop', 'server:close']
+export declare const CLIENT_EVENTS: readonly ['client:init', 'event:*', 'page:change', 'i18n:changed', 'client:destroy']
 
 /** 客户端插件上下文(sdk/client.mjs);完整声明见 agentworkshop/sdk/client */
 export declare const CLIENT_SDK_VERSION: string
+/** DOM 构建助手(client.mjs 的具名导出,经本包再导出) */
+export declare function el(tag: string, attrs?: Record<string, unknown>, children?: Array<Node | string> | Node | string): HTMLElement
 
 /** ctx.ui.registerPanel 入参(命名插槽 -> 宿主容器挂载) */
 export interface ClientPanelEntry {

package/sdk/index.mjs

@@ -16,13 +16,13 @@
 import { SDK_VERSION, definePlugin, createPluginContext, createRouteTable, validatePluginModule, validatePluginSettings, validatePluginGroups, resolvePluginGroupId, pluginKvExists } from './context.mjs'
 import { HookBus } from './hooks.mjs'
 import { createPlatformClient } from './api.mjs'
-import { CLIENT_SDK_VERSION, createClientContext } from './client.mjs'
+import { CLIENT_SDK_VERSION, createClientContext, el } from './client.mjs'
 import { LIFECYCLE_EVENTS, CLIENT_EVENTS } from './lifecycle.mjs'
 
 export { SDK_VERSION, definePlugin, createPluginContext, createRouteTable, validatePluginModule, validatePluginSettings, validatePluginGroups, resolvePluginGroupId, pluginKvExists, isPathInside } from './context.mjs'
 export { HookBus } from './hooks.mjs'
 export { createPlatformClient } from './api.mjs'
-export { CLIENT_SDK_VERSION, createClientContext } from './client.mjs'
+export { CLIENT_SDK_VERSION, createClientContext, el } from './client.mjs'
 export { LIFECYCLE_EVENTS, CLIENT_EVENTS } from './lifecycle.mjs'
 
 export default {
@@ -39,6 +39,7 @@ export default {
   createPlatformClient,
   CLIENT_SDK_VERSION,
   createClientContext,
+  el,
   LIFECYCLE_EVENTS,
   CLIENT_EVENTS,
 }

package/sdk/lifecycle.mjs

@@ -4,11 +4,15 @@
 
 /** 服务端生命周期事件清单(宿主触发;文档见 docs/plugins.md 与文档站 /sdk/lifecycle)。
  *  daq:frame 与 daq:sample 同由数采管线发射(host.mjs emitDaqFrame,帧入账路径),
- *  入册使清单与实际发射面一致。 */
+ *  入册使清单与实际发射面一致。
+ *  plugins:reloaded 由宿主热重载收尾时发射(host.mjs 重装载流程),
+ *  permissions:changed 经 emitPluginEvent 前缀化后实际是 `event:permissions:changed`
+ *  —— 订阅要走 ctx.events.on('permissions:changed')(它会补 `event:` 前缀)。 */
 export const LIFECYCLE_EVENTS = Object.freeze([
   'plugin:host:init',
+  'plugins:reloaded',
   'config:changed',
-  'permissions:changed',
+  'event:permissions:changed',
   'event:*',
   'daq:sample',
   'daq:frame',
@@ -18,11 +22,12 @@ export const LIFECYCLE_EVENTS = Object.freeze([
   'server:close',
 ])
 
-/** 客户端生命周期事件清单 */
+/** 客户端生命周期事件清单(宿主 loader / 客户端 HookBus 触发) */
 export const CLIENT_EVENTS = Object.freeze([
   'client:init',
   'event:*',
   'page:change',
+  'i18n:changed',
   'client:destroy',
 ])
 

package/server/api/workshop/agent-tools/bindings/index.post.ts

@@ -11,6 +11,7 @@ import { getAgentNodeBindingRepo } from '@/server/services/workshop/agents/node-
 import { lineMode } from '@/server/services/workshop/permissions'
 import { getDaqController } from '@/server/services/workshop/daq/daq-controller'
 import { getDcwController } from '@/server/services/workshop/dcw/dcw-controller'
+import { getWorkshopManager } from '@/server/plugins/workshop'
 import { AppError, ErrorCodes } from '@/server/utils/errors'
 
 export default defineApiHandler(async (event) => {
@@ -18,6 +19,25 @@ export default defineApiHandler(async (event) => {
   const body = await readBody<{ agentId?: string, nodeId?: string, kind?: 'dcw' | 'daq', mode?: 'auto' | 'manual' }>(event) ?? {}
   const kind = body.kind ?? 'dcw'
   const nodeId = String(body.nodeId ?? '')
+  const agentId = String(body.agentId ?? '')
+
+  // 绑定主体必须是**已部署的 Channel 成员实例**(运行时就是它持这条绑定做工具鉴权)。
+  // 传 Agent 模板 id 是极易发生的误用:旧实现照单全收,绑定落在模板 id 上,
+  // 成员侧 daq_query / dcw_control 一律报"尚未绑定节点" —— 一条**静默失效**的授权,
+  // 排查成本极高(实测:脚本按 /api/workshop/agents 返回的 id 绑定,任务全被拒绝)。
+  // 这里把无声错误变成可执行提示:模板 id → 告知应改用哪个成员 id;两者都不是 → 404。
+  const manager = getWorkshopManager()
+  if (!manager.findChannelAgentById(agentId)) {
+    const instances = manager.listChannelAgentInstances(agentId)
+    if (instances.length > 0) {
+      const hint = instances.map(i => `${i.id}(频道「${i.name}」)`).join('、')
+      throw new AppError(400, 'AGENT_ID_NOT_MEMBER',
+        `agentId 是 Agent 模板而非频道成员实例,绑定不会生效。请改用成员 id:${hint}`)
+    }
+    throw new AppError(404, ErrorCodes.NOT_FOUND,
+      `Agent 成员不存在: ${agentId || '(空)'}(需传频道成员 id,可经 GET /api/workshop/channels/:id/agents 获取)`)
+  }
+
   // 绑定前置:节点必须存在,且用户对其所属产线有足额权限
   const lineId = kind === 'daq'
     ? getDaqController().byId(nodeId)?.lineId
@@ -30,11 +50,6 @@ export default defineApiHandler(async (event) => {
   if (mode === 'none' || (needOperate && mode !== 'operate')) {
     throw new AppError(403, 'LINE_FORBIDDEN', `无该产线权限:绑定${kind === 'daq' ? '数采' : '写控'}节点需对产线「${lineId}」拥有${needOperate ? '可操控' : '仅查看'}及以上权限`)
   }
-  const binding = getAgentNodeBindingRepo().bind(
-    String(body.agentId ?? ''),
-    nodeId,
-    kind,
-    body.mode ?? 'auto',
-  )
+  const binding = getAgentNodeBindingRepo().bind(agentId, nodeId, kind, body.mode ?? 'auto')
   return { binding }
-})
+})

package/server/api/workshop/aml/datasets/[id].delete.ts

@@ -0,0 +1,39 @@
+/**
+ * DELETE /api/workshop/aml/datasets/:id —— 删除数据集(元数据行 + 实体目录)。
+ * 引用保护:被实验或模型引用的数据集**拒绝删除**(否则模型工件会指向不存在的数据源,
+ * 训练可复现性断裂)。需要连带删除时先删对应作业/模型。
+ * 权限:admin/editor + 产线 operate。
+ */
+import { getRouterParam } from 'h3'
+import { defineApiHandler } from '@/server/utils/response'
+import { requireRole } from '@/server/api/workshop/caller'
+import { requireLineMode } from '@/server/services/workshop/permissions'
+import { AppError } from '@/server/utils/errors'
+import { getAmlRuntime } from '@/server/services/workshop/aml/runtime'
+import { removeEntityDir } from '@/server/services/workshop/aml/entity'
+import { recordOps } from '@/server/services/workshop/ops/ops'
+
+export default defineApiHandler(async (event) => {
+  const user = requireRole(event, ['admin', 'editor'])
+  const id = getRouterParam(event, 'id') ?? ''
+  const rt = getAmlRuntime()
+  const row = rt.repo.dataset.get(id)
+  if (!row) throw new AppError(404, 'AML_DATASET_MISSING', `数据集 ${id} 不存在`)
+  requireLineMode(user, row.lineId, 'operate')
+
+  const refs = rt.repo.dataset.referenceCount(id)
+  if (refs.experiments > 0 || refs.models > 0) {
+    throw new AppError(409, 'AML_DATASET_REFERENCED',
+      `数据集 ${id} 仍被引用(实验 ${refs.experiments} 条 / 模型 ${refs.models} 个),拒绝删除。请先删除对应作业与模型,以保住模型的可复现性溯源。`)
+  }
+  const ent = removeEntityDir(rt, 'dataset', id)
+  rt.repo.dataset.remove(id)
+  recordOps({
+    actor: user.id, actorName: user.name, actorKind: 'user',
+    action: 'aml.dataset.delete', kind: 'system',
+    summary: `删除数据集 ${id}${ent.removed ? '(含实体目录)' : '(实体目录本就不存在)'}`,
+    targetKind: 'aml_dataset', targetId: id,
+    lineId: row.lineId, productId: row.productId, recipeId: row.recipeId,
+  })
+  return { deleted: true, entityRemoved: ent.removed, dir: ent.dir }
+})

package/server/api/workshop/aml/datasets/[id].get.ts

@@ -1,24 +1,46 @@
 /**
- * GET /api/workshop/aml/datasets/:id —— 数据集详情(注册表行 + 统计/清洗报告)。
+ * GET /api/workshop/aml/datasets/:id —— 数据集详情(元数据行 + 实体装载)。
+ * 实体经 entity.loadDatasetEntity 按 <amlRoot>/datasets/<id> 规范路径加载并校验契约,
+ * 不信任元数据行里的 path 字段(历史写入/被搬移后可能失效)。
+ * 实体缺失时返回 410 + 元数据行,让 UI 能提示"元数据在、数据没了"而不是整个 500。
  */
 import { getRouterParam } from 'h3'
-import { existsSync, readFileSync } from 'node:fs'
-import { join } from 'node:path'
 import { defineApiHandler } from '@/server/utils/response'
 import { resolveUser } from '@/server/api/workshop/caller'
 import { requireLineMode } from '@/server/services/workshop/permissions'
 import { AppError } from '@/server/utils/errors'
 import { getAmlRuntime } from '@/server/services/workshop/aml/runtime'
+import { loadDatasetEntity } from '@/server/services/workshop/aml/entity'
 
 export default defineApiHandler(async (event) => {
   const user = resolveUser(event)
   const id = getRouterParam(event, 'id') ?? ''
-  const ds = getAmlRuntime().repo.dataset.get(id)
+  const rt = getAmlRuntime()
+  const ds = rt.repo.dataset.get(id)
   if (!ds) throw new AppError(404, 'AML_DATASET_MISSING', `数据集 ${id} 不存在`)
   requireLineMode(user, ds.lineId, 'readonly')
-  const reportPath = join(ds.path, 'report.json')
-  const report = existsSync(reportPath)
-    ? JSON.parse(readFileSync(reportPath, 'utf8'))
-    : null
-  return { dataset: ds, report }
+  try {
+    const ent = loadDatasetEntity(id)
+    return {
+      dataset: ds,
+      report: ent.report,
+      manifest: ent.manifest,
+      spec: ent.spec,
+      entity: {
+        dir: ent.dir,
+        arrays: ent.arrays,
+        sizeBytes: ent.sizeBytes,
+        healthy: true,
+        // 实体是否自带 spec.json(自描述);false = 规格仅存于元数据行(旧快照)
+        specFromEntity: ent.specFromEntity,
+      },
+    }
+  }
+  catch (err) {
+    if (err instanceof AppError && err.statusCode === 410) {
+      // 元数据仍在但实体丢了:仍然 200 返回元数据 + 明确的实体告警,便于 UI 展示与清理引导
+      return { dataset: ds, report: null, manifest: null, spec: null, entity: { dir: null, arrays: [], sizeBytes: 0, healthy: false, specFromEntity: false, warning: err.message } }
+    }
+    throw err
+  }
 })

package/server/api/workshop/aml/datasets/[id].patch.ts

@@ -0,0 +1,30 @@
+/**
+ * PATCH /api/workshop/aml/datasets/:id —— 更新数据集元数据(备注)。
+ * body: { note: string }
+ * 仅改元数据(可检索的描述信息);实体数据不可变(数据集的 sha256 是训练可复现性的锚)。
+ */
+import { getRouterParam, readBody } from 'h3'
+import { defineApiHandler } from '@/server/utils/response'
+import { requireRole } from '@/server/api/workshop/caller'
+import { requireLineMode } from '@/server/services/workshop/permissions'
+import { getAmlRuntime } from '@/server/services/workshop/aml/runtime'
+import { recordOps } from '@/server/services/workshop/ops/ops'
+
+export default defineApiHandler(async (event) => {
+  const user = requireRole(event, ['admin', 'editor'])
+  const id = getRouterParam(event, 'id') ?? ''
+  const body = await readBody<{ note?: string }>(event) ?? {}
+  const rt = getAmlRuntime()
+  const row = rt.repo.dataset.get(id)
+  if (!row) return { dataset: null }
+  requireLineMode(user, row.lineId, 'operate')
+  if (typeof body.note === 'string') rt.repo.dataset.updateNote(id, body.note.slice(0, 2000))
+  recordOps({
+    actor: user.id, actorName: user.name, actorKind: 'user',
+    action: 'aml.dataset.update', kind: 'system',
+    summary: `更新数据集 ${id} 元数据(备注)`,
+    targetKind: 'aml_dataset', targetId: id,
+    lineId: row.lineId, productId: row.productId, recipeId: row.recipeId,
+  })
+  return { dataset: rt.repo.dataset.get(id) }
+})

package/server/api/workshop/aml/entities/index.get.ts

@@ -0,0 +1,13 @@
+/**
+ * GET /api/workshop/aml/entities —— 元数据 ↔ 实体 对账(只读)。
+ * 返回两侧计数与差异清单(entity_missing / orphan_dir / contract_missing)。
+ * 用途:数据集/模型"列表里在、实际打不开"这类问题的定位入口。
+ */
+import { defineApiHandler } from '@/server/utils/response'
+import { resolveUser } from '@/server/api/workshop/caller'
+import { inventory } from '@/server/services/workshop/aml/entity'
+
+export default defineApiHandler(async (event) => {
+  resolveUser(event)
+  return inventory()
+})

package/server/api/workshop/aml/entities/prune.post.ts

@@ -0,0 +1,28 @@
+/**
+ * POST /api/workshop/aml/entities/prune —— 清理孤儿实体目录(磁盘有、元数据无)。
+ * body: { dryRun?: boolean } —— dryRun=true 只报告;缺省 false 执行删除。
+ * 只删 <amlRoot>/{datasets,jobs,models}/<id> 形状的目录(带根内越界防护);
+ * **不会**删除"元数据在、实体缺失"的行(那需要人工判断是重建还是清元数据)。
+ * 权限:admin/editor。
+ */
+import { readBody } from 'h3'
+import { defineApiHandler } from '@/server/utils/response'
+import { requireRole } from '@/server/api/workshop/caller'
+import { pruneOrphans } from '@/server/services/workshop/aml/entity'
+import { recordOps } from '@/server/services/workshop/ops/ops'
+
+export default defineApiHandler(async (event) => {
+  const user = requireRole(event, ['admin', 'editor'])
+  const body = await readBody<{ dryRun?: boolean }>(event) ?? {}
+  const dryRun = body.dryRun === true
+  const result = pruneOrphans(dryRun)
+  if (!dryRun && result.removed.length > 0) {
+    recordOps({
+      actor: user.id, actorName: user.name, actorKind: 'user',
+      action: 'aml.entity.prune', kind: 'system',
+      summary: `清理 AML 孤儿实体目录 ${result.removed.length} 个`,
+      targetKind: 'aml_env', targetId: 'entities',
+    })
+  }
+  return result
+})

package/server/api/workshop/aml/env/index.get.ts

@@ -0,0 +1,13 @@
+/**
+ * GET /api/workshop/aml/env —— AML 运行环境自检(只读)。
+ * 返回 uv/Python 探测结果、./aml/.venv 就绪状态、资产根布局、进行中的环境任务与作业前置条件。
+ * 前端「运行环境」面板的数据源:未装 uv 时据 uv.ok 显示「一键安装 uv」。
+ */
+import { defineApiHandler } from '@/server/utils/response'
+import { resolveUser } from '@/server/api/workshop/caller'
+import { envStatus } from '@/server/services/workshop/aml/env-manager'
+
+export default defineApiHandler(async (event) => {
+  resolveUser(event)
+  return envStatus()
+})

package/server/api/workshop/aml/env/recheck.post.ts

@@ -0,0 +1,14 @@
+/**
+ * POST /api/workshop/aml/env/recheck —— 清空 uv/Python 探测缓存并重新探测。
+ * 场景:用户在系统里手工装了 uv 或 Python,不想重启服务就让它生效。
+ * 之后读 GET /aml/env 即拿到最新结论。
+ */
+import { defineApiHandler } from '@/server/utils/response'
+import { requireRole } from '@/server/api/workshop/caller'
+import { envStatus, recheck } from '@/server/services/workshop/aml/env-manager'
+
+export default defineApiHandler(async (event) => {
+  requireRole(event, ['admin', 'editor'])
+  recheck()
+  return envStatus()
+})

package/server/api/workshop/aml/env/uv.post.ts

@@ -0,0 +1,21 @@
+/**
+ * POST /api/workshop/aml/env/uv —— 一键安装 uv 到 <amlRoot>/tools。
+ * 异步:立即返回任务快照(kind=install-uv,status=running),进度经 GET /aml/env 轮询。
+ * 权限:admin/editor —— 安装动作会在服务器上落可执行文件并触发网络下载。
+ */
+import { defineApiHandler } from '@/server/utils/response'
+import { requireRole } from '@/server/api/workshop/caller'
+import { recordOps } from '@/server/services/workshop/ops/ops'
+import { startInstallUv } from '@/server/services/workshop/aml/env-manager'
+
+export default defineApiHandler(async (event) => {
+  const user = requireRole(event, ['admin', 'editor'])
+  const task = startInstallUv()
+  recordOps({
+    actor: user.id, actorName: user.name, actorKind: 'user',
+    action: 'aml.env.install_uv', kind: 'system',
+    summary: `一键安装 uv(任务 ${task.id}),安装目录 = ./aml/tools`,
+    targetKind: 'aml_env', targetId: task.id,
+  })
+  return { task }
+})

package/server/api/workshop/aml/env/venv.post.ts

@@ -0,0 +1,24 @@
+/**
+ * POST /api/workshop/aml/env/venv —— 创建/重建训练环境 ./aml/.venv。
+ * body: { force?: boolean } —— force=true 时先删旧环境再重建(依赖升级/环境损坏时用)。
+ * 异步:立即返回任务快照(kind=create-venv),进度经 GET /aml/env 轮询。
+ * 权限:admin/editor。
+ */
+import { readBody } from 'h3'
+import { defineApiHandler } from '@/server/utils/response'
+import { requireRole } from '@/server/api/workshop/caller'
+import { recordOps } from '@/server/services/workshop/ops/ops'
+import { startCreateVenv } from '@/server/services/workshop/aml/env-manager'
+
+export default defineApiHandler(async (event) => {
+  const user = requireRole(event, ['admin', 'editor'])
+  const body = await readBody<{ force?: boolean }>(event) ?? {}
+  const task = startCreateVenv({ force: body.force === true })
+  recordOps({
+    actor: user.id, actorName: user.name, actorKind: 'user',
+    action: body.force ? 'aml.env.rebuild_venv' : 'aml.env.create_venv', kind: 'system',
+    summary: `${body.force ? '重建' : '创建'}训练环境 ./aml/.venv(任务 ${task.id})`,
+    targetKind: 'aml_env', targetId: task.id,
+  })
+  return { task }
+})

package/server/api/workshop/aml/index.get.ts

@@ -1,17 +1,30 @@
 /**
- * GET /api/workshop/aml —— 平台概览(运行时状态 + 近期数据集/模型/作业计数)。
+ * GET /api/workshop/aml —— 平台概览(运行时状态 + 环境自检 + 近期数据集/模型/作业计数)。
+ * env 内联进来让首屏一次请求就能渲染「运行环境」面板,避免额外往返;
+ * 完整环境详情(含任务日志)仍由 GET /aml/env 提供。
  */
 import { defineApiHandler } from '@/server/utils/response'
 import { resolveUser } from '@/server/api/workshop/caller'
 import { getAmlRuntime } from '@/server/services/workshop/aml/runtime'
 import { runtimeStatus } from '@/server/services/workshop/aml/job-orchestrator'
+import { envStatus } from '@/server/services/workshop/aml/env-manager'
 
 export default defineApiHandler(async (event) => {
   resolveUser(event)
   const rt = getAmlRuntime()
   const status = await runtimeStatus()
+  const env = await envStatus()
   return {
     runtime: status,
+    env: {
+      amlRoot: env.amlRoot,
+      amlRootSource: env.amlRootSource,
+      uv: env.uv,
+      venv: env.venv,
+      disk: env.disk,
+      preflight: env.preflight,
+      task: env.task ? { id: env.task.id, kind: env.task.kind, status: env.task.status } : null,
+    },
     counts: {
       datasets: rt.repo.dataset.list({ limit: 1000 }).length,
       models: rt.repo.model.list({ limit: 1000 }).length,