agentworkshop 0.7.33 → 0.7.37

package/server/services/workshop/agents/dsh-agent.ts

@@ -79,13 +79,10 @@ export interface DshAgentConfig {
 export class DshAgentImpl extends BaseAgentImpl implements AgentInterface {
   private readonly config: DshAgentConfig
   private agentInfo: AgentInfo | null = null
-  private readonly bridgeCtx = {
-    identity: { agentId: '', channelId: '', role: 'worker' as 'lead' | 'worker', name: 'agent' },
-    state: this.toolState,
-    getWorkspace: () => this.workspace,
-  }
-
-  private agentRole: 'lead' | 'worker' = 'worker'
+  // 不要重新声明 bridgeCtx / agentRole(由 BaseAgentImpl 持有)。
+  // 子类字段初始化器在 super() 之后执行,会用空 identity 遮蔽基类已装配好的 bridgeCtx,
+  // 使 host tool 桥的 agentId 恒为 '' → 按 agentId 的鉴权全部误判(节点绑定/工业工具)。
+  // 同理 agentRole 会被重置为 'worker',lead 身份丢失。
   private client: StdioJsonRpcClient | null = null
   private clientStarting: Promise<void> | null = null
   private sessionId: string | null = null

package/server/services/workshop/agents/opencode-agent.ts

@@ -110,13 +110,11 @@ interface PendingHitl {
 export class OpenCodeAgentImpl extends BaseAgentImpl implements AgentInterface {
   private readonly config: OpenCodeAgentConfig
   private agentInfo: AgentInfo | null = null
-  private readonly bridgeCtx = {
-    identity: { agentId: '', channelId: '', role: 'worker' as 'lead' | 'worker', name: 'agent' },
-    state: this.toolState,
-    getWorkspace: () => this.workspace,
-  }
-
-  private agentRole: 'lead' | 'worker' = 'worker'
+  // 注意:不要在本类重新声明 bridgeCtx / agentRole —— 它们由 BaseAgentImpl 持有。
+  // 子类字段初始化器在 super() **之后**执行,会用一个空的 identity 覆盖基类已装配好的
+  // bridgeCtx(class field 遮蔽),导致 host tool 桥拿到的 agentId 恒为 '' ——
+  // 所有按 agentId 的鉴权(节点绑定/工业工具)都会误判为"未绑定"。
+  // 同理 agentRole 被重置为 'worker',lead 身份传不到桥里。
 
   // 服务进程与 API 面
   private child: ReturnType<typeof spawnLineProcess> | null = null

package/server/services/workshop/aml/aml.repo.ts

@@ -209,6 +209,10 @@ export function createAmlRepo(db: DatabaseSync) {
       remove(id: string): void {
         db.prepare('DELETE FROM aml_datasets WHERE id = ?').run(id)
       },
+      /** 元数据局部更新(备注;CRUD 的 U) */
+      updateNote(id: string, note: string): void {
+        db.prepare('UPDATE aml_datasets SET note = ? WHERE id = ?').run(note, id)
+      },
     },
 
     // ----- jobs -----
@@ -268,6 +272,14 @@ export function createAmlRepo(db: DatabaseSync) {
       requeue(id: string): void {
         jobRetryBump.run(id)
       },
+      remove(id: string): void {
+        db.prepare('DELETE FROM aml_jobs WHERE id = ?').run(id)
+      },
+      /** 删除作业时级联清实验谱系(否则实验行成为悬挂元数据) */
+      removeExperimentsOf(jobId: string): number {
+        const r = db.prepare('DELETE FROM aml_experiments WHERE job_id = ?').run(jobId)
+        return Number(r.changes)
+      },
     },
 
     // ----- experiments -----
@@ -361,6 +373,12 @@ export function createAmlRepo(db: DatabaseSync) {
       markPruned(id: string): void {
         modelPrune.run(id)
       },
+      remove(id: string): void {
+        db.prepare('DELETE FROM aml_models WHERE id = ?').run(id)
+      },
+      updateNote(id: string, note: string): void {
+        db.prepare('UPDATE aml_models SET note = ? WHERE id = ?').run(note, id)
+      },
     },
   }
 }

package/server/services/workshop/aml/dataset-builder.ts

@@ -403,6 +403,10 @@ export async function buildDataset(spec: AmlDatasetSpec, by: { id: string, kind:
     beatMs: beat,
   }
   writeFileSync(join(dir, 'manifest.json'), JSON.stringify(manifest, null, 2))
+  // spec.json:取数规格随实体落盘。元数据行里本来就有 spec_json,但那是**索引**;
+  // 把规格同时写进实体目录,./aml 才是自描述、可整体拷贝的资产 ——
+  // 拷到另一台机器(或 sqlite 丢了)时,仅凭 datasets/<id>/ 仍能还原"这份数据是怎么取的"。
+  writeFileSync(join(dir, 'spec.json'), JSON.stringify(spec, null, 2))
 
   // 7. 统计报告(基于 train 网格序列)
   const nodeSummaries: SeriesSummary[] = []

package/server/services/workshop/aml/entity.ts

@@ -0,0 +1,365 @@
+/**
+ * AML 元数据 ↔ 实体 对账与实体加载。
+ *
+ * 平台是「SQLite 元数据 + 磁盘实体」两段式:
+ *   元数据行(aml_datasets/jobs/models)给出可检索、可分页、可鉴权的索引;
+ *   实体目录(<amlRoot>/{datasets,jobs,models}/<id>/)给出真正的数据(数组/工件/契约)。
+ *
+ * 两者会漂移:手工删了目录、拷了别人的 ./aml 进来、作业被中途 kill 留下半成品、
+ * 元数据行指向的路径被搬走。本模块提供:
+ *   - inventory():两侧逐 id 对账,产出 missing / orphan / size 三类差异(只读);
+ *   - loadDatasetEntity() / loadModelEntity() / loadJobEntity():按元数据行加载实体,
+ *     并校验契约文件齐备 —— 实际作业(预测/训练/评审)直接用它的返回值,不各自拼路径;
+ *   - pruneOrphans():删除**孤儿实体目录**(磁盘有、元数据无),带根内越界防护。
+ *
+ * 纪律:元数据是权威索引,实体是权威内容。宁可报告"实体缺失"也不静默用空数据顶替
+ * (静默顶替会让预测用空权重跑出一堆看似正常的垃圾结果)。
+ */
+import { existsSync, readFileSync, readdirSync, rmSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { AppError } from '../../../utils/errors'
+import { createLogger } from '../logger'
+import { getAmlRuntime, isInsideAmlRoot, type AmlRuntime } from './runtime'
+
+const log = createLogger('aml.entity')
+
+export interface EntityIssue {
+  kind: 'dataset' | 'job' | 'model'
+  id: string
+  problem: 'entity_missing' | 'orphan_dir' | 'contract_missing'
+  path: string
+  detail: string
+}
+
+export interface AmlInventory {
+  root: string
+  counts: { datasets: number, jobs: number, models: number }
+  entities: { datasets: number, jobs: number, models: number }
+  issues: EntityIssue[]
+  ok: boolean
+}
+
+function listDirs(dir: string): string[] {
+  try {
+    return readdirSync(dir).filter((e) => {
+      try {
+        return statSync(join(dir, e)).isDirectory()
+      }
+      catch {
+        return false
+      }
+    })
+  }
+  catch {
+    return []
+  }
+}
+
+function fileSize(p: string): number {
+  const st = statSync(p, { throwIfNoEntry: false })
+  return st?.isFile() ? st.size : 0
+}
+
+/** 两侧逐 id 对账(只读;不修改任何东西) */
+export function inventory(): AmlInventory {
+  const rt = getAmlRuntime()
+  const issues: EntityIssue[] = []
+  const dsRows = rt.repo.dataset.list({ limit: 100_000 })
+  const jobRows = rt.repo.job.list({ limit: 100_000 })
+  const modelRows = rt.repo.model.list({ limit: 100_000 })
+
+  const check = (
+    kind: EntityIssue['kind'],
+    rows: Array<{ id: string, path?: string }>,
+    baseDir: string,
+    contract: string[],
+  ): number => {
+    const ids = new Set(rows.map(r => r.id))
+    for (const r of rows) {
+      const dir = join(baseDir, r.id)
+      if (!existsSync(dir)) {
+        issues.push({
+          kind, id: r.id, problem: 'entity_missing', path: dir,
+          detail: `元数据存在但实体目录缺失(可能是手工删除或从别处拷贝了元数据行)`,
+        })
+        continue
+      }
+      // 契约文件允许是"多选一"(例如模型:新实体有 io_spec.json,旧实体只有 REGISTERED)
+      if (contract.length > 0 && !contract.some(f => existsSync(join(dir, f)))) {
+        issues.push({
+          kind, id: r.id, problem: 'contract_missing', path: join(dir, contract[0]),
+          detail: `实体目录存在但缺少契约文件(${contract.join(' 或 ')}):作业被中途终止或落盘不完整`,
+        })
+      }
+    }
+    let n = 0
+    for (const d of listDirs(baseDir)) {
+      n++
+      if (!ids.has(d)) {
+        issues.push({
+          kind, id: d, problem: 'orphan_dir', path: join(baseDir, d),
+          detail: '磁盘有实体目录但元数据无对应行(可安全清理)',
+        })
+      }
+    }
+    return n
+  }
+
+  // 契约:数据集 = manifest.json(权威,列定义/归一化/形状);
+  //       作业 = job.json(提交契约);模型 = REGISTERED 或 io_spec.json(新旧两种形态)
+  const dsEntities = check('dataset', dsRows, rt.datasetsDir, ['manifest.json'])
+  const jobEntities = check('job', jobRows, rt.jobsDir, ['job.json'])
+  const modelEntities = check('model', modelRows, rt.modelsDir, ['REGISTERED', 'io_spec.json'])
+
+  return {
+    root: rt.root,
+    counts: { datasets: dsRows.length, jobs: jobRows.length, models: modelRows.length },
+    entities: { datasets: dsEntities, jobs: jobEntities, models: modelEntities },
+    issues,
+    ok: issues.length === 0,
+  }
+}
+
+/** 实体目录大小(递归;目录缺失 = 0) */
+export function entitySizeBytes(dir: string): number {
+  let total = 0
+  const walk = (d: string, depth: number) => {
+    if (depth > 8) return
+    let entries: string[]
+    try {
+      entries = readdirSync(d)
+    }
+    catch {
+      return
+    }
+    for (const e of entries) {
+      const p = join(d, e)
+      const st = statSync(p, { throwIfNoEntry: false })
+      if (!st) continue
+      if (st.isDirectory()) walk(p, depth + 1)
+      else total += st.size
+    }
+  }
+  walk(dir, 0)
+  return total
+}
+
+function readJson<T>(p: string, what: string): T {
+  try {
+    return JSON.parse(readFileSync(p, 'utf8')) as T
+  }
+  catch (err) {
+    throw new AppError(500, 'AML_ENTITY_CORRUPT', `${what} 读取失败(${p}):${(err as Error).message}`)
+  }
+}
+
+export interface DatasetEntity {
+  id: string
+  dir: string
+  spec: Record<string, unknown>
+  /** spec 是否来自实体自带的 spec.json(true)/ 回退元数据行(false,旧快照) */
+  specFromEntity: boolean
+  manifest: {
+    columns?: Array<{ name: string, kind?: string, count?: number }>
+    rowCount?: number
+    beatMs?: number
+    horizon?: number
+    targetColumns?: string[]
+    featureColumns?: string[]
+    [k: string]: unknown
+  }
+  report: Record<string, unknown> | null
+  arrays: Array<{ file: string, bytes: number }>
+  sizeBytes: number
+}
+
+/** 按元数据行加载数据集实体(实际训练/预览的数据入口)
+ *
+ *  契约文件:`manifest.json` 是**权威**(列定义/归一化/切分/形状),缺它无法训练;
+ *  `spec.json` 是自描述副本(取数规格),旧快照可能没有 —— 此时回退元数据行的 specJson,
+ *  而不是把可用的数据集判成损坏。
+ */
+export function loadDatasetEntity(id: string): DatasetEntity {
+  const rt = getAmlRuntime()
+  const row = rt.repo.dataset.get(id)
+  if (!row) throw new AppError(404, 'AML_DATASET_MISSING', `数据集 ${id} 不存在`)
+  const dir = join(rt.datasetsDir, id)
+  if (!existsSync(dir)) {
+    throw new AppError(410, 'AML_ENTITY_MISSING', `数据集 ${id} 的实体目录已丢失(${dir});元数据仍在。请重新构建数据集,或执行实体对账清理该元数据行。`)
+  }
+  const manifestPath = join(dir, 'manifest.json')
+  if (!existsSync(manifestPath)) {
+    throw new AppError(410, 'AML_ENTITY_CONTRACT_MISSING', `数据集 ${id} 缺少 manifest.json(权威契约,落盘不完整):${manifestPath}`)
+  }
+  const arraysDir = join(dir, 'arrays')
+  const arrays = existsSync(arraysDir)
+    ? readdirSync(arraysDir).map(f => ({ file: f, bytes: fileSize(join(arraysDir, f)) }))
+    : []
+  // spec 优先取实体自带的 spec.json(可移植),缺失回退元数据行(旧快照)
+  const specPath = join(dir, 'spec.json')
+  let spec: Record<string, unknown>
+  if (existsSync(specPath)) {
+    spec = readJson<Record<string, unknown>>(specPath, 'spec.json')
+  }
+  else {
+    try {
+      spec = JSON.parse(row.specJson || '{}') as Record<string, unknown>
+    }
+    catch {
+      spec = {}
+    }
+  }
+  return {
+    id,
+    dir,
+    spec,
+    specFromEntity: existsSync(specPath),
+    manifest: readJson<DatasetEntity['manifest']>(manifestPath, 'manifest.json'),
+    report: existsSync(join(dir, 'report.json'))
+      ? readJson<Record<string, unknown>>(join(dir, 'report.json'), 'report.json')
+      : null,
+    arrays,
+    sizeBytes: entitySizeBytes(dir),
+  }
+}
+
+export interface ModelEntity {
+  id: string
+  dir: string
+  onnxPath: string
+  onnxBytes: number
+  ioSpec: Record<string, unknown>
+  /** ioSpec 是否来自实体自带的 io_spec.json(true)/ 回退元数据行(false,旧模型) */
+  ioSpecFromEntity: boolean
+  metrics: Record<string, unknown>
+  sizeBytes: number
+}
+
+/** 按元数据行加载模型实体(预测入口;工件缺失直接报错,不用空权重蒙混)
+ *
+ *  契约:`REGISTERED` 标记或 `io_spec.json` 至少存在其一(旧模型只有 REGISTERED);
+ *  io_spec 优先取实体自带副本,缺失回退元数据行的 io_spec_json。
+ */
+export function loadModelEntity(id: string): ModelEntity {
+  const rt = getAmlRuntime()
+  const row = rt.repo.model.get(id)
+  if (!row) throw new AppError(404, 'AML_MODEL_MISSING', `模型 ${id} 不存在`)
+  const dir = join(rt.modelsDir, id)
+  if (!existsSync(dir)) {
+    throw new AppError(410, 'AML_ENTITY_MISSING', `模型 ${id} 的实体目录已丢失(${dir});元数据仍在。`)
+  }
+  const ioPath = join(dir, 'io_spec.json')
+  if (!existsSync(ioPath) && !existsSync(join(dir, 'REGISTERED'))) {
+    throw new AppError(410, 'AML_ENTITY_CONTRACT_MISSING', `模型 ${id} 既无 io_spec.json 也无 REGISTERED 标记(注册不完整):${dir}`)
+  }
+  let ioSpec: Record<string, unknown>
+  if (existsSync(ioPath)) {
+    ioSpec = readJson<Record<string, unknown>>(ioPath, 'io_spec.json')
+  }
+  else {
+    try {
+      ioSpec = JSON.parse(row.ioSpecJson || '{}') as Record<string, unknown>
+    }
+    catch {
+      ioSpec = {}
+    }
+  }
+  const onnxPath = join(dir, 'model.onnx')
+  return {
+    id,
+    dir,
+    onnxPath,
+    onnxBytes: fileSize(onnxPath),
+    ioSpec,
+    ioSpecFromEntity: existsSync(ioPath),
+    metrics: (() => {
+      try {
+        return JSON.parse(row.metricsJson || '{}') as Record<string, unknown>
+      }
+      catch {
+        return {}
+      }
+    })(),
+    sizeBytes: entitySizeBytes(dir),
+  }
+}
+
+export interface JobEntity {
+  id: string
+  dir: string
+  job: Record<string, unknown>
+  workspace: string[]
+  logTail: string
+  artifacts: Array<{ file: string, bytes: number }>
+  sizeBytes: number
+}
+
+/** 按元数据行加载作业实体(工作区/日志/工件;供日志查看与工件评审) */
+export function loadJobEntity(id: string): JobEntity {
+  const rt = getAmlRuntime()
+  const row = rt.repo.job.get(id)
+  if (!row) throw new AppError(404, 'AML_JOB_MISSING', `作业 ${id} 不存在`)
+  const dir = join(rt.jobsDir, id)
+  if (!existsSync(dir)) {
+    throw new AppError(410, 'AML_ENTITY_MISSING', `作业 ${id} 的实体目录已丢失(${dir});元数据仍在。`)
+  }
+  const wsDir = join(dir, 'workspace')
+  const artDir = join(dir, 'artifacts')
+  const logPath = join(dir, 'run.log')
+  let logTail = ''
+  try {
+    if (existsSync(logPath)) logTail = readFileSync(logPath, 'utf8').slice(-4000)
+  }
+  catch { /* 日志不可读不影响其余实体 */ }
+  return {
+    id,
+    dir,
+    job: existsSync(join(dir, 'job.json'))
+      ? readJson<Record<string, unknown>>(join(dir, 'job.json'), 'job.json')
+      : { note: 'job.json 缺失(作业提交时未落盘)' },
+    workspace: existsSync(wsDir) ? readdirSync(wsDir) : [],
+    logTail,
+    artifacts: existsSync(artDir)
+      ? readdirSync(artDir).map(f => ({ file: f, bytes: fileSize(join(artDir, f)) }))
+      : [],
+    sizeBytes: entitySizeBytes(dir),
+  }
+}
+
+/**
+ * 删除实体目录(带 AML 根内越界防护)。
+ * 只删 <amlRoot>/{datasets,jobs,models}/<id> 形状的路径 —— 元数据里的 path 字段
+ * 来自历史写入,不能无条件信任(它可能是任意绝对路径)。
+ */
+export function removeEntityDir(rt: AmlRuntime, kind: 'dataset' | 'job' | 'model', id: string): { removed: boolean, dir: string } {
+  const base = kind === 'dataset' ? rt.datasetsDir : kind === 'job' ? rt.jobsDir : rt.modelsDir
+  const dir = join(base, id)
+  if (!isInsideAmlRoot(rt, dir) || !dir.startsWith(base)) {
+    log.warn(`[aml-entity] 拒绝删除越界路径:${dir}`)
+    return { removed: false, dir }
+  }
+  if (!existsSync(dir)) return { removed: false, dir }
+  try {
+    rmSync(dir, { recursive: true, force: true })
+    return { removed: true, dir }
+  }
+  catch (err) {
+    throw new AppError(500, 'AML_ENTITY_DELETE_FAILED', `删除实体目录失败(${dir}):${(err as Error).message}`)
+  }
+}
+
+/** 清理孤儿实体目录(磁盘有、元数据无);dryRun=true 只报告不删除 */
+export function pruneOrphans(dryRun = false): { removed: string[], kept: number, dryRun: boolean } {
+  const rt = getAmlRuntime()
+  const inv = inventory()
+  const orphans = inv.issues.filter(i => i.problem === 'orphan_dir')
+  const removed: string[] = []
+  if (!dryRun) {
+    for (const o of orphans) {
+      const r = removeEntityDir(rt, o.kind, o.id)
+      if (r.removed) removed.push(r.dir)
+    }
+    if (removed.length > 0) log.info(`[aml-entity] 已清理 ${removed.length} 个孤儿实体目录`)
+  }
+  return { removed, kept: inv.issues.length - orphans.length, dryRun }
+}

package/server/services/workshop/aml/env-manager.ts

@@ -0,0 +1,242 @@
+/**
+ * AML 环境管理:环境自检状态 + 异步动作(一键安装 uv / 创建 .venv)。
+ *
+ * 为什么要有这层:
+ *  - 平台第一次被使用时,用户环境里可能既没有 uv 也没有可用的 Python。
+ *    把「检测 → 引导 → 一键修复」收敛成一个可读的状态对象,REST/UI/工具三面共用;
+ *  - 安装 uv 与创建 venv 都是**长耗时且有网络下载**的动作(数十秒到数分钟),
+ *    不能挂在同步 HTTP 请求里 —— 用进程内单任务 + 轮询进度(GET env 带 task),
+ *    与作业编排器的「异步 + 进度推送」纪律一致。
+ *
+ * 单任务约束:同一时刻只允许一个 env 动作(uv 安装与 venv 创建都要动同一个工具目录/
+ * 虚拟环境,并发只会互相破坏)。重复提交返回 409 + 当前任务状态。
+ */
+import { readdirSync, statSync } from 'node:fs'
+import { randomUUID } from 'node:crypto'
+import { AppError } from '../../../utils/errors'
+import { createLogger } from '../logger'
+import { amlSettings } from '../settings'
+import { amlRootSourceLabel, getAmlRuntime } from './runtime'
+import {
+  ensureVenv,
+  installUv,
+  isVenvReady,
+  probePython,
+  probeUv,
+  requirementsHash,
+  resetProbeCache,
+  venvDir,
+  venvPythonPath,
+  type ProgressFn,
+  type PythonProbe,
+  type UvProbe,
+} from './python-runtime'
+
+const log = createLogger('aml.env')
+
+export type AmlEnvTaskKind = 'install-uv' | 'create-venv'
+export type AmlEnvTaskStatus = 'running' | 'done' | 'failed'
+
+export interface AmlEnvTask {
+  id: string
+  kind: AmlEnvTaskKind
+  status: AmlEnvTaskStatus
+  startedAt: string
+  endedAt: string | null
+  /** 进度日志(尾部;安装输出可能很长,只保留最近 N 行) */
+  log: string[]
+  error: string | null
+}
+
+export interface AmlEnvStatus {
+  amlRoot: string
+  amlRootMode: string
+  amlRootSource: string
+  projectRoot: string | null
+  dirs: { datasets: string, jobs: string, models: string, venv: string, tools: string, runtime: string }
+  uv: UvProbe
+  python: PythonProbe
+  venv: { ready: boolean, dir: string, pythonPath: string, requirementsHash: string, sizeMb: number }
+  disk: { usedMb: number, quotaMb: number }
+  /** 一键安装 uv 是否可用(平台总能在项目内安装,恒 true;留给未来策略开关) */
+  canInstallUv: boolean
+  task: AmlEnvTask | null
+  /** 作业前置条件:不满足时 UI 直接给修复入口,而不是等作业失败 */
+  preflight: { canRunJobs: boolean, blockers: string[] }
+}
+
+const TASK_LOG_TAIL = 200
+
+const g = globalThis as typeof globalThis & { __amlEnvTask?: AmlEnvTask }
+
+function currentTask(): AmlEnvTask | null {
+  return g.__amlEnvTask ?? null
+}
+
+function pushLog(task: AmlEnvTask, line: string): void {
+  for (const l of line.split(/\r?\n/)) {
+    const t = l.trimEnd()
+    if (!t) continue
+    task.log.push(t)
+  }
+  if (task.log.length > TASK_LOG_TAIL) task.log.splice(0, task.log.length - TASK_LOG_TAIL)
+}
+
+function dirSizeMb(dir: string): number {
+  let total = 0
+  const walk = (d: string, depth: number) => {
+    if (depth > 6) return
+    let entries: string[]
+    try {
+      entries = readdirSync(d)
+    }
+    catch {
+      return
+    }
+    for (const e of entries) {
+      const p = `${d}/${e}`
+      const st = statSync(p, { throwIfNoEntry: false })
+      if (!st) continue
+      if (st.isDirectory()) walk(p, depth + 1)
+      else total += st.size
+    }
+  }
+  walk(dir, 0)
+  return total / 1024 / 1024
+}
+
+/** 组装环境自检状态(只读;不做任何写入) */
+export async function envStatus(): Promise<AmlEnvStatus> {
+  const rt = getAmlRuntime()
+  const uv = await probeUv(rt)
+  const python = await probePython()
+  const venvReady = isVenvReady(rt)
+  const blockers: string[] = []
+  if (!python.ok) blockers.push(python.reason ?? 'Python 解释器不可用')
+  if (!venvReady) blockers.push('训练环境(./aml/.venv)尚未创建:请在「运行环境」面板点击「创建训练环境」')
+  let usedMb = 0
+  try {
+    usedMb = dirSizeMb(rt.root)
+  }
+  catch { /* 目录不可读按 0 */ }
+  return {
+    amlRoot: rt.root,
+    amlRootMode: rt.rootMode,
+    amlRootSource: amlRootSourceLabel(rt.rootMode),
+    projectRoot: rt.projectRoot,
+    dirs: {
+      datasets: rt.datasetsDir,
+      jobs: rt.jobsDir,
+      models: rt.modelsDir,
+      venv: venvDir(rt),
+      tools: rt.toolsDir,
+      runtime: rt.runtimeDir,
+    },
+    uv,
+    python,
+    venv: {
+      ready: venvReady,
+      dir: venvDir(rt),
+      pythonPath: venvPythonPath(rt),
+      requirementsHash: requirementsHash(),
+      sizeMb: Number(dirSizeMb(venvDir(rt)).toFixed(1)),
+    },
+    disk: { usedMb: Number(usedMb.toFixed(1)), quotaMb: amlQuotaMb() },
+    canInstallUv: true,
+    task: currentTask(),
+    preflight: { canRunJobs: python.ok && venvReady, blockers },
+  }
+}
+
+function amlQuotaMb(): number {
+  try {
+    return amlSettings().job.diskQuotaMb
+  }
+  catch {
+    return 2048
+  }
+}
+
+/** 启动一个 env 任务(单任务互斥);返回任务快照供 UI 立即渲染 */
+function startTask(kind: AmlEnvTaskKind): AmlEnvTask {
+  const running = currentTask()
+  if (running && running.status === 'running') {
+    throw new AppError(409, 'AML_ENV_BUSY', `已有环境任务在执行中(${running.kind}),请等待完成后再操作`)
+  }
+  const task: AmlEnvTask = {
+    id: `env-${randomUUID().slice(0, 8)}`,
+    kind,
+    status: 'running',
+    startedAt: new Date().toISOString(),
+    endedAt: null,
+    log: [],
+    error: null,
+  }
+  g.__amlEnvTask = task
+  return task
+}
+
+function finishTask(task: AmlEnvTask, err?: unknown): void {
+  task.endedAt = new Date().toISOString()
+  if (err) {
+    task.status = 'failed'
+    task.error = err instanceof Error ? err.message : String(err)
+    pushLog(task, `失败:${task.error}`)
+    log.warn(`[aml-env] ${task.kind} 失败:`, task.error)
+  }
+  else {
+    task.status = 'done'
+    pushLog(task, '完成。')
+    log.info(`[aml-env] ${task.kind} 完成`)
+  }
+}
+
+/** 一键安装 uv(异步;立即返回任务快照,进度经 GET /aml/env 轮询) */
+export function startInstallUv(): AmlEnvTask {
+  const rt = getAmlRuntime()
+  const task = startTask('install-uv')
+  const emit: ProgressFn = line => pushLog(task, line)
+  void (async () => {
+    try {
+      emit(`AML 资产根:${rt.root}`)
+      emit(`目标安装目录:${rt.toolsDir}(免管理员,不改系统 PATH)`)
+      const r = await installUv(rt, emit)
+      if (!r.ok) throw new AppError(500, 'AML_UV_INSTALL_FAILED', r.log.slice(-600) || 'uv 安装失败')
+      resetProbeCache()
+      finishTask(task)
+    }
+    catch (err) {
+      finishTask(task, err)
+    }
+  })()
+  return task
+}
+
+/** 创建/重建训练环境 ./aml/.venv(异步) */
+export function startCreateVenv(opts: { force?: boolean } = {}): AmlEnvTask {
+  const rt = getAmlRuntime()
+  const task = startTask('create-venv')
+  const emit: ProgressFn = line => pushLog(task, line)
+  void (async () => {
+    try {
+      emit(`${opts.force ? '重建' : '创建'}训练环境:${venvDir(rt)}`)
+      const uv = await probeUv(rt)
+      emit(uv.ok
+        ? `使用 uv ${uv.version}(来源:${uv.source})`
+        : '未检测到 uv,将回退 python -m venv(建议先点「一键安装 uv」以获得更快更稳的供给)')
+      const vpy = await ensureVenv(rt, { force: opts.force, onLog: emit })
+      emit(`解释器:${vpy}`)
+      finishTask(task)
+    }
+    catch (err) {
+      finishTask(task, err)
+    }
+  })()
+  return task
+}
+
+/** 重新探测(用户在系统里手工装了 uv/Python 后,无需重启服务) */
+export function recheck(): void {
+  resetProbeCache()
+  log.info('[aml-env] 已清空探测缓存,下次读取将重新探测')
+}