agentworkshop 0.7.34 → 0.7.38

package/cli/core/args.mjs

@@ -8,6 +8,69 @@
 //   --                 → 之后全部为位置参数
 // ============================================================
 
+/**
+ * 全局选项规格 —— **取值边界的事实源**。
+ *
+ * 为什么需要这张表:`--root <dir>` 后面跟着的 `<dir>` 是取值,不是位置参数。
+ * 不知道该信息的两处逻辑都会出错:
+ *   - 指令名提取(extractCommandName):`aw --root /x version` 会把 `/x` 当成指令名
+ *     → "未知指令: /x"(用户只能被迫写 `--root=/x` 等号形式);
+ *   - 全局项剥离(stripGlobals):布尔项 `--json` 后面若跟位置参数,会被误当成它的取值吞掉
+ *     → `aw --json build` 里 `build` 消失。
+ * 因此两处统一读这张表,而不是各自猜。
+ */
+export const GLOBAL_OPTS = [
+  { name: '--json', value: false },
+  { name: '--debug', value: false },
+  { name: '--help', value: false, short: '-h' },
+  { name: '--version', value: false, short: '-v' },
+  { name: '--root', value: true },
+]
+
+/** 带取值的全局选项名(如 ['--root']) */
+export function globalValueNames() {
+  return GLOBAL_OPTS.filter(o => o.value).map(o => o.name)
+}
+
+/** 全部全局选项名(布尔 + 带值) */
+export function globalNames() {
+  return GLOBAL_OPTS.map(o => o.name)
+}
+
+/**
+ * 提取指令名:首个**位置 token**(自动跳过全局选项及其取值)。
+ *
+ * `aw --root /x version`  → 'version'(旧实现返回 '/x',指令派发直接失败)
+ * `aw --json build`       → 'build'
+ * `aw -- build`           → 'build'(`--` 之后一律位置参数)
+ * `aw -`                  → '-'(单个连字符按 stdin 约定视为位置参数)
+ *
+ * @param {string[]} argv
+ * @param {{ valueNames?: string[] }} [opts] 带取值的选项名(缺省用全局表)
+ */
+export function extractCommandName(argv, opts = {}) {
+  const valueNames = new Set(opts.valueNames ?? globalValueNames())
+  let afterDash = false
+  for (let i = 0; i < argv.length; i++) {
+    const tok = argv[i]
+    if (afterDash) return tok
+    if (tok === '--') {
+      afterDash = true
+      continue
+    }
+    if (tok.startsWith('--')) {
+      const eq = tok.indexOf('=')
+      // 等号形式自带取值;分离形式才需要连带跳过下一个 token
+      if (eq < 0 && valueNames.has(tok)) i++
+      continue
+    }
+    // 短选项:-h/-v 这类布尔项只占一位;'-' 单独出现是位置参数
+    if (tok.length > 1 && tok.startsWith('-')) continue
+    return tok
+  }
+  return null
+}
+
 /**
  * 解析 argv（不含 node/script 前两项）。返回 { flags, positionals, unknown }
  *
@@ -108,14 +171,22 @@ export function parseArgs(argv, { shortMap = {}, skip } = {}) {
  *   ['--name=--json']       同理（等号形式的值）
  *   ['--json', 'x']         位置 0 的 --json 才是真正的全局选项
  * 这里复用 parseArgs 的消费逻辑,只在 token 处于「选项位」时剔除,
- * 值位上的同名 token 原样保留;带值的全局选项连同其取值 token 一起移除。
+ * 值位上的同名 token 原样保留。
+ *
+ * **取值边界必须显式声明**:布尔项(`--json`/`--debug`)只占一个 token,
+ * 绝不吞掉紧随其后的位置参数 —— 旧实现对所有被剔除项一律套用"下一 token 非选项
+ * 就当取值吃掉",于是 `aw build --json x` 里的 `x` 会静默消失。
+ * 带值项(`--root`)经 opts.valueNames 声明后,才连同取值 token 一起移除。
  *
  * @param {string[]} argv
  * @param {string[]} names 需剔除的长选项名（含 -- 前缀）,如 ['--json','--debug']
+ * @param {{ valueNames?: string[] }} [opts]
+ *   valueNames: names 中**带取值**的子集(缺省 [] = 全部按布尔处理)
  * @returns {string[]} 剔除全局选项后的 argv（保序;其余 token 原样保留）
  */
-export function stripGlobals(argv, names) {
+export function stripGlobals(argv, names, opts = {}) {
   const drop = new Set(names)
+  const takesValue = new Set(opts.valueNames ?? [])
   const kept = []
   let i = 0
   let afterDoubleDash = false
@@ -143,8 +214,9 @@ export function stripGlobals(argv, names) {
       const willConsumeNext = !hasInlineValue
         && next !== undefined && !next.startsWith('-') && next !== ''
       if (drop.has(name)) {
-        // 全局选项及其值一并移除;--json=1 这类内联值随 token 一起消失
-        i += 1 + (willConsumeNext ? 1 : 0)
+        // 仅**声明了带值**的全局项才连取值一起移除;布尔项只移除自身
+        const eats = willConsumeNext && takesValue.has(name)
+        i += 1 + (eats ? 1 : 0)
         continue
       }
       kept.push(tok)

package/cli/core/help.mjs

@@ -38,7 +38,9 @@ export function renderHelp({ registry, root, version }) {
   lines.push('    --debug           调试日志')
   lines.push('')
   lines.push(color.dim('设置优先级:') + '  config.yml 默认 < data/runtime-settings.json 运行时覆盖 < 环境变量 / CLI 参数')
-  lines.push(color.dim('指令注册:') + '    内建(随包) + 用户 ~/.agentworkshop/commands + 项目 .agentworkshop/commands（同名的后者覆盖前者）')
+  // 目录名必须与 registry.mjs / home.mjs 的 HOME_DIRNAME 一致(.AgentWorkShop)。
+  // Linux/macOS 大小写敏感,小写写法会让用户把指令放进永远扫不到的目录。
+  lines.push(color.dim('指令注册:') + '    内建(随包) + 用户 ~/.AgentWorkShop/commands + 项目 .AgentWorkShop/commands(同名的后者覆盖前者)')
   lines.push(color.dim('新指令:') + `        ${color.cyan('aw register <path|url|npm:pkg>')}  或直接放入上述目录(导出 {meta, run})`)
   lines.push('')
   return lines.join('\n')

package/cli/core/meta.mjs

@@ -0,0 +1,38 @@
+// ============================================================
+// CLI 包元信息(叶子模块 —— 不 import 任何 CLI 内部模块)
+// ------------------------------------------------------------
+// 为什么单独一个文件:packageVersion/packageRoot 原本定义在 cli/aw.mjs,
+// 而 cli/commands/*.mjs 又要用它们 → 命令模块反向 import '../aw.mjs'。
+// 于是当 **cli/aw.mjs 自己作为入口**(node cli/aw.mjs ...)时形成循环依赖死锁:
+//   aw.mjs 顶层 await main() → main() await registry.scanDirs()
+//   → 动态 import 命令模块 → 命令模块 import '../aw.mjs'
+//   → 而 aw.mjs 尚未求值完成(卡在自己的顶层 await 上)
+//   → 模块图永远等不到对方 → Node 报 unsettled top-level await 并以**退出码 13**
+//     收场,且 stdout 已排队的写入未 flush → `aw --help` 变成"无输出 + 13"。
+// 经 bin/aw.mjs 入口时 aw.mjs 是副作用-free 的被导入方,循环不显形 ——
+// 所以这个缺陷只在直接跑 cli/aw.mjs(以及任何把自己当入口的调用)时暴露。
+//
+// 规矩:本文件只依赖 node 内建,任何人(含命令模块)都可以安全 import。
+// ============================================================
+import { readFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/** 本包版本(cli/core/meta.mjs → ../../package.json) */
+export function packageVersion() {
+  try {
+    return JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version ?? '0.0.0'
+  }
+  catch {
+    return '0.0.0'
+  }
+}
+
+/** 本包根目录(全局安装副本同样成立;必须走 fileURLToPath,Windows 下
+ *  URL pathname 是 '/D:/...' 形态,直接 path.resolve 会得到 'D:\D:\...' 垃圾路径,
+ *  导致内建指令目录扫描全部静默失败 —— 指令注册失效的根因) */
+export function packageRoot() {
+  return resolve(dirname(fileURLToPath(import.meta.url)), '..', '..')
+}
+
+export default { packageVersion, packageRoot }

package/cli/core/post-build.mjs

@@ -0,0 +1,96 @@
+// ============================================================
+// 构建产物后处理 —— nuxt build 完成**之后**必须做的事
+// ------------------------------------------------------------
+// 为什么要有这一步(而不是全塞进 nuxt.config 的 compiled 钩子):
+//   `compiled` 钩子与 nitro 的 chunk 落盘存在竞态 —— 实测出现过 nitro.mjs /
+//   virtual/entry.mjs 在钩子跑完之后才被写回,补丁静默失效。失效的后果很重:
+//   `globalThis._importMeta_.url` 保持占位符 "file:///_entry.js",任何模块级
+//   fileURLToPath(import.meta.url) 在启动瞬间抛 ERR_INVALID_FILE_URL_PATH,
+//   整进程起不来(且报错指向内部 URL 代码,很难定位到构建期)。
+//   因此这里在 nuxt build **返回之后**再做一遍,并且**校验失败即报错**,
+//   把"静默失效"变成"构建失败"。
+//
+// 三件事:
+//   ① import-meta 占位符补丁(必须命中,否则产物不可启动)
+//   ② 随产物分发的外置资产:prompts / schema.json / AML python 资产
+//      (运行时经 fs 读取,nitro 不会打包它们)
+//   ③ 结果汇报(便于 CI 与排障)
+// ============================================================
+import { copyFileSync, cpSync, existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** nitropack 2.13.4 写入的 import.meta.url 占位兜底 */
+const PLACEHOLDER = 'globalThis._importMeta_||{url:"file:///_entry.js",env:process.env}'
+const PATCHED = 'globalThis._importMeta_||{url:import.meta.url,env:process.env}'
+
+/** 需要打补丁的 chunk(相对 .output/server/chunks) */
+const PATCH_TARGETS = [
+  ['_', 'nitro.mjs'],
+  ['virtual', 'entry.mjs'],
+]
+
+/**
+ * 执行全部后处理。
+ * @param {string} root 项目根(nuxt build 的 cwd)
+ * @returns {{ patched: string[], alreadyOk: string[], missing: string[], assets: string[] }}
+ * @throws {Error} import-meta 占位符仍残留在**已生成**的 chunk 里时抛错(产物不可启动)
+ */
+export function postBuildArtifacts(root) {
+  const outputRoot = join(root, '.output')
+  const chunks = join(outputRoot, 'server', 'chunks')
+  const patched = []
+  const alreadyOk = []
+  const missing = []
+  const unresolved = []
+
+  for (const parts of PATCH_TARGETS) {
+    const file = join(chunks, ...parts)
+    const rel = parts.join('/')
+    if (!existsSync(file)) {
+      missing.push(rel)
+      continue
+    }
+    const src = readFileSync(file, 'utf8')
+    if (!src.includes(PLACEHOLDER)) {
+      // 要么本就没有占位符(nitro 版本变更),要么已被 compiled 钩子修好
+      alreadyOk.push(rel)
+      continue
+    }
+    writeFileSync(file, src.replaceAll(PLACEHOLDER, PATCHED))
+    // 复读校验:确认真的落盘(防写入失败静默通过)
+    const after = readFileSync(file, 'utf8')
+    if (after.includes(PLACEHOLDER)) unresolved.push(rel)
+    else patched.push(rel)
+  }
+
+  // 外置资产随产物分发(运行时 fs 读取;缺了它们不是启动失败而是运行期才炸)
+  const assets = []
+  const ship = (src, dest, label, { recursive = false } = {}) => {
+    try {
+      if (!existsSync(src)) return
+      if (recursive) cpSync(src, dest, { recursive: true })
+      else copyFileSync(src, dest)
+      assets.push(label)
+    }
+    catch (err) {
+      console.error(`[build] ${label} 复制失败:`, err?.message ?? err)
+    }
+  }
+  const asDir = join(outputRoot, '.AgentWorkShop')
+  ship(join(root, '.AgentWorkShop', 'prompts'), join(asDir, 'prompts'), 'prompts', { recursive: true })
+  ship(join(root, 'shared', 'config', 'schema.json'), join(asDir, 'schema.json'), 'schema.json')
+  ship(
+    join(root, 'server', 'services', 'workshop', 'aml', 'python'),
+    join(asDir, 'aml-python'),
+    'aml-python',
+    { recursive: true },
+  )
+
+  if (unresolved.length > 0) {
+    throw new Error(
+      `[build] import-meta 占位符补丁未能生效:${unresolved.join(', ')} —— `
+      + '产物启动会抛 ERR_INVALID_FILE_URL_PATH。请检查 .output 是否被其他进程占用或只读。',
+    )
+  }
+  return { patched, alreadyOk, missing, assets }
+}

package/cli/core/registry.mjs

@@ -100,12 +100,15 @@ export class CommandRegistry {
 }
 
 /** 拼接指令扫描目录清单（内建 → 用户级 → 项目级;配合同名后者覆盖,项目级优先级最高）
- *  目录名与 shared/config/home.mjs 的 HOME_DIRNAME 保持一致(.AgentWorkShop):
- *  Windows 大小写不敏感无感,Linux/macOS 下小写目录会导致注册的指令永远扫描不到。 */
+ *  `homeDir` 语义 = **已解析的 AW Home**(= shared/config/home.mjs 的 `awHome(env)`,
+ *  即 `$AW_HOME` 或 `~/.AgentWorkShop`),用户级指令目录是它的 `commands/` 子目录。
+ *  以前这里收的是 OS 家目录再自己拼 `.AgentWorkShop`,与 `aw register --global`
+ *  (写 `join(awHome(), 'commands')`)只在 AW_HOME 未设置时巧合一致 —— 设了 AW_HOME,
+ *  注册的指令会落到扫描器永远不看的地方。 */
 export function commandDirs({ packageRoot, projectRoot, homeDir }) {
   const dirs = []
   if (packageRoot) dirs.push(join(packageRoot, 'cli', 'commands'))
-  if (homeDir) dirs.push(join(homeDir, '.AgentWorkShop', 'commands'))
+  if (homeDir) dirs.push(join(homeDir, 'commands'))
   if (projectRoot) dirs.push(join(projectRoot, '.AgentWorkShop', 'commands'))
   return dirs
 }

package/config.yml

@@ -1,16 +1,18 @@
 # ============================================================
-# AgentWorkShop 运行配置 —— 单一事实来源（Single Source of Truth）
+# AgentWorkShop 运行配置 —— 运行时默认值的单一事实来源
 # ------------------------------------------------------------
 # 本文件由 nuxt.config.ts（构建/开发期）与 scripts/start.mjs（生产启动期）
 # 读取并解析，驱动整个运行时。修改后重启对应模式即可生效：
 #   开发：pnpm dev     -> 读取 server.dev
 #   生产：pnpm start   -> 读取 server.prod
+# 例外：app.version 的权威值在 package.json（nuxt.config.ts 以包版本优先，
+#   本字段仅作回退）—— 长期不同步过（曾停在 0.7.9 而包已 0.7.35），勿再依赖它。
 # ============================================================
 
 app:
   name: AgentWorkShop
   title: AgentWorkShop
-  version: 0.7.9
+  version: 0.7.36
   description: 基于 Nuxt 4 的配置驱动运行范式
 
 # 运行模式（dev/prod 实际由启动命令决定，此处仅作运行时展示）
@@ -142,27 +144,27 @@ retention:
 # 服务端日志(env AWSHOP_LOG_LEVEL)
 log:
   level: info  # debug | info | warn | error
-
-# AML 自动建模平台(Python 训练运行时/作业限额/GC 保留/评测门禁;全部键见 shared/config/schema.json)
-aml:
-  python:
-    pythonBin: ''   # 空=自动探测 python / py -3
-    uvBin: ''       # 空=自动探测 uv(存在则优先)
-    indexUrl: ''    # PyPI 兼容镜像,空=默认源;仅 venv 供给阶段联网,训练进程不联网
-  job:
-    timeoutMs: 1800000
-    maxConcurrent: 2
-    diskQuotaMb: 2048
-    stallMs: 600000
-  dataset:
-    maxRows: 200000
-    retentionDays: 30
-    allowCrossRecipe: false
-  model:
-    retiredKeepDays: 90
-  gates:
-    nrmse: 0.10
-    rolloutNrmse: 0.25
-    valTestGap: 0.20
-    minRows: 500
-    minRuns: 3
+
+# AML 自动建模平台(Python 训练运行时/作业限额/GC 保留/评测门禁;全部键见 shared/config/schema.json)
+aml:
+  python:
+    pythonBin: ''   # 空=自动探测 python / py -3
+    uvBin: ''       # 空=自动探测 uv(存在则优先)
+    indexUrl: ''    # PyPI 兼容镜像,空=默认源;仅 venv 供给阶段联网,训练进程不联网
+  job:
+    timeoutMs: 1800000
+    maxConcurrent: 2
+    diskQuotaMb: 2048
+    stallMs: 600000
+  dataset:
+    maxRows: 200000
+    retentionDays: 30
+    allowCrossRecipe: false
+  model:
+    retiredKeepDays: 90
+  gates:
+    nrmse: 0.10
+    rolloutNrmse: 0.25
+    valTestGap: 0.20
+    minRows: 500
+    minRuns: 3

package/docs/aml.md

@@ -0,0 +1,99 @@
+# AML —— Agent 驱动的自动深度学习拟合 / MPC 影子孪生建模平台
+
+> 模块代号 `aml`(Auto Modeling Lab)。设计计划全文见 `.omc/plans/2026-09-10-agent-aml-mpc-shadow-platform.md`(含文献映射与 ADR)。
+
+## 是什么
+
+在 MAS 镜像数采(daq)与时序库之上,由**内置深度学习专家团队**全自主完成:
+
+```
+拉数(隔离三元组) → 自动清洗 → 写代码训练 → 平台权威评测 → 门禁迭代 → HITL 晋升 → 影子模型参考
+```
+
+调控 Agent 调参前通过 `aml_model_reference` 查询生产模型,获得"拟议参数 → 预测输出轨迹"的影子参考(数字孪生/MPC 前置);REST 侧另有 `/api/workshop/aml/models/:id/predict` 显式预测入口。
+
+## 架构速览
+
+| 层 | 位置 | 说明 |
+|---|---|---|
+| 环境自检 | `aml/env-manager.ts` + `aml/python-runtime.ts` | 探测 uv/Python → 一键安装 uv 到 `./aml/tools` → 供给 `./aml/.venv`;异步任务 + 进度轮询(`GET /aml/env`) |
+| 元数据↔实体 | `aml/entity.ts` | SQLite 四表为索引、`./aml` 目录为实体;逐 id 对账(缺失/孤儿/契约不齐)、按规范路径装载实体、孤儿清理 |
+| 数据集层 | `server/services/workshop/aml/dataset-builder.ts` | 隔离三元组 (line/product/recipe) 必填;state/量程/Hampel 清洗 → beatMs 对齐 → byRun 滑窗切分 → 快照落 `./aml/datasets/<id>/`(manifest+report+float32 数组+sha256) |
+| 统计引擎 | `aml/stats.ts`、`aml/clean.ts` | 逐节点概要/相关/控制→目标滞后互相关(时滞估计),进 dataset report |
+| 作业运行器 | `aml/job-orchestrator.ts` | FIFO 队列、并发上限、双段子进程(train → 平台评估)、停摆看门狗、`##AML` NDJSON 协议、`aml.job` WS 帧 |
+| Python 桥 | `aml/python-runtime.ts` + `aml/python/` | 探测 python/uv → 共享 `./aml/.venv`(marker 幂等);`amlkit.py`(平台种)/`aml_eval.py`(权威评估器)/`train-example.py`(参考实现);训练进程不联网 |
+| 门禁 | `aml/gates.ts` | G1 单步 NRMSE≤0.10 / G2 多步滚动 NRMSE≤0.25 / G3 泛化差≤20% / G4 行数≥500 批次≥3 / G5 工件完整;阈值 `aml.gates.*` live 可调 |
+| 注册表 | `aml/model-registry.ts` | candidate→shadow→production→retired;生产晋升前 ONNX 深检;同组旧生产自动退役;REST 晋升=产线 operate 权限,Agent 晋升=HITL 审批 |
+| 预测服务 | `aml/predictor.ts` | onnxruntime-node 懒加载(可选依赖)+ session LRU(4);one-step 闭环滚动与评估器同口径 |
+| GC | `aml/retention.ts` | 无引用数据集 30 天 / retired 工件 90 天 / 失败作业目录 7 天;磁盘配额 `aml.job.diskQuotaMb` |
+
+## 资产根布局(`./aml`)
+
+AML 的全部产物收敛在**项目根下的 `./aml`**(与配置根 `.AgentWorkShop` 分离 —— 这里是可移植资产,
+不是运行时状态),整体可拷贝、可删除重建:
+
+```
+aml/
+  .venv/            uv 创建/管理的 Python 环境(依赖锁定在 aml/python/requirements.txt)
+  datasets/<id>/    spec.json 取数规格 · manifest.json 列定义 · report.json 质量报告 · arrays/*.f32
+  jobs/<id>/        job.json 提交契约 · workspace/(train.py+amlkit.py) · run.log · artifacts/
+  models/<id>/      model.onnx + io_spec.json(输入输出契约,不可变)
+  runtime/          uv.json(一键安装记录)/ env.json
+  tools/            平台自动安装的 uv 二进制(免管理员、不改系统 PATH)
+  README.md         目录自述   .gitignore  忽略运行时资产
+```
+
+根解析优先级(源码 `shared/config/home.mjs` 的 `resolveAmlRoot`,五级):
+`AW_AML_DIR` 环境变量(显式覆盖)> 检出根 `./aml`(cwd 向上找到 `config.yml` + `nuxt.config.ts`)
+> `<awHome>/aml`(`AW_MODE=home`;`AW_HOME` 可重定向,不是写死 `~/.AgentWorkShop`)
+> cwd 向上真实存在的 `.AgentWorkShop/aml`(不越过 `$HOME`)> `<cwd>/aml` 兜底。
+`GET /api/workshop/aml/env` 返回实际生效路径与来源,UI「运行环境」面板直接展示。
+
+## 元数据 CRUD
+
+平台是「SQLite 元数据 + 磁盘实体」两段式,两者以 id 一一对应:
+
+| 操作 | 端点 | 说明 |
+|---|---|---|
+| C | `POST /aml/datasets`、`POST /aml/jobs` | 建快照 / 提交训练(实体目录同步落盘) |
+| R | `GET /aml/{datasets,jobs,models}`、`GET /aml/{datasets,jobs}/:id` | 详情按**规范路径**装载实体并校验契约,不信任元数据 `path` 字段 |
+| U | `PATCH /aml/datasets/:id`、`PATCH /aml/models/:id` | 更新备注(数据不可变:sha256 是复现锚) |
+| D | `DELETE /aml/{datasets,models,jobs}/:id` | 元数据行 + 实体目录;带引用保护 |
+| 对账 | `GET /aml/entities`、`POST /aml/entities/prune` | 逐 id 报缺失/孤儿/契约不齐;清理孤儿实体目录(带根内越界防护) |
+
+删除保护:被实验或模型引用的数据集、production 阶段模型、运行中作业、已产出模型的作业一律拒绝删除
+(保住模型工件的可复现性溯源)。
+
+## 模型 IO 契约(MPC 面向)
+
+canonical one-step:输入 `history [batch, H, nAll]`(归一化)→ 输出 `y_next [batch, nTgt]`(归一化)。多步=闭环滚动:预测回填 target 列、control 列取未来 U(对应 Recipe 参数,见 io_spec)、feature 列持最后观测(persistence)。评估器与预测服务同口径实现,保证门禁指标可复现于推理。
+
+## 使用
+
+- **UI**:侧导航「建模」(`/aml`):运行环境(uv/venv/对账)/ 数据集 / 作业 / 排行榜 / 注册表 / 预测控制台。
+- **Agent**:内置团队「AML 影子建模团队」(`team-aml-shadow`,部署前先加成员)或任意成员直接调用工具族 `aml_node_catalog / aml_dataset_build / aml_dataset_stats / aml_job_submit / aml_job_status / aml_job_logs / aml_job_cancel / aml_leaderboard / aml_model_promote(lead 专属)/ aml_model_reference`(见 `.AgentWorkShop/prompts/host-tools.json`);调参 what-if 经 `aml_model_reference` 的 `controls` 参数传入拟议参数值。
+- **REST**:`/api/workshop/aml/{env,entities,datasets,jobs,experiments,models}`(见各路由文件头注释)。
+
+## Python 运行时
+
+首次训练自动探测 uv 与 Python,并在 `./aml/.venv` 供给锁定依赖(`aml/python/requirements.txt`;仅此阶段联网,可配 `aml.python.indexUrl` 镜像)。
+
+UI「运行环境」面板(`/aml` 页)提供完整引导:
+
+1. **uv 检测** —— 探测顺序:`aml.python.uvBin` 配置 > `./aml/tools`(平台装过的)> `./aml/runtime/uv.json` 记录 > 系统 PATH;来源随状态一并显示。
+2. **一键安装 uv** —— 未检测到时按钮可用:调官方安装脚本并令 `UV_INSTALL_DIR=./aml/tools`、`UV_NO_MODIFY_PATH=1`,
+   **不改系统 PATH、不需要管理员**;失败自动回退 `python -m pip install --target ./aml/tools uv`。
+3. **创建/重建训练环境** —— 有 uv 走 `uv venv` + `uv pip install`(快);无 uv 回退 `python -m venv`(慢但可用)。
+   环境就绪以 marker 文件(`.aml-ok-<requirements摘要>`)为准,依赖或镜像变更即视为需重建。
+4. **重新检测** —— 手工在系统里装了 uv/Python 后免重启生效。
+5. **元数据↔实体对账** —— 见上文「元数据 CRUD」;孤儿实体可一键清理。
+
+安装与建环境都是分钟级动作:接口异步返回任务快照(`kind`/`status`/`log`),页面按 1.5s 轮询刷新进度。
+无 Python 时作业报 `AML_PYTHON_MISSING` 指引;`AML_STUB=1` 启动可用存根运行器走通全链路(存根模型不可预测,晋升被深检拦截)。
+
+## 治理与安全边界
+
+- 训练代码仅运行于作业工作区(`./aml/jobs/<id>/workspace/`),平台以独立子进程执行、墙钟/停摆/并发三重限制、杀树回收;权威指标由平台评估器复算,不采信 Agent 自报。
+- 数据集节点集 ⊆ Agent 的 daq 绑定(只缩不放);REST 侧走产线 line grants。
+- 全部副作用过 `recordOps`(audit_log + ops.log 实时帧),Agent 行为归属「Channel/成员」。
+- SQL 全参数绑定;工作区路径收敛校验(amlkit `_safe_job_path`);Mimosa 审计通过。