@hongmaple0820/scale-engine 0.40.0 → 0.40.2

package/docs/start/quickstart.md

@@ -32,27 +32,48 @@ cd scale-demo
 scale init --governance-pack standard
 ```
 
-初始化会生成 `.scale/`、`docs/`、`scripts/` 以及对应 Agent 入口文件。已有项目升级不要盲目重跑 `init`，优先使用：
+初始化会生成 `.scale/`、`docs/`、`scripts/` 以及对应 Agent 入口文件。已有项目升级不要盲目重复 `init`，优先使用升级向导：
+
+```bash
+scale upgrade --dir .
+```
+
+向导会生成升级计划、写入 HTML 报告，并在安全时询问是否应用。CI 或高级用户仍可使用分步命令：
 
 ```bash
 scale upgrade check --dir . --lang zh
 scale upgrade plan --dir . --html --lang zh
+scale upgrade apply --dir . --confirm --lang zh
 ```
 
 ## 3. 交互式安装第三方能力
 
-默认输出语言是中文。需要英文时加 `--lang en`，也可以设置 `SCALE_LANG=en`。
+默认语言是中文。需要英文时加 `--lang en`，也可以设置 `SCALE_LANG=en`。
 
-推荐先只查看计划：
+直接进入交互式安装：
+
+```bash
+scale setup
+```
+
+交互式安装会询问：
+
+- 语言：默认中文。
+- 安装包：标准、前端/UI、AI OS、完整、自定义。
+- 记忆供应商：默认 `gbrain`，也可切换到 `scale-local`。
+- 记忆路由模式：默认 `external-first`。
+- 是否执行安装：可跳过、全量安装、或只安装选中的第三方项。
+
+只查看计划：
 
 ```bash
 scale setup --pack full
 ```
 
-确认后安装：
+确认后执行安装：
 
 ```bash
-scale setup --pack full --yes
+scale setup --pack full --apply --yes
 ```
 
 机器可读输出：
@@ -61,38 +82,46 @@ scale setup --pack full --yes
 scale setup --pack full --json
 ```
 
-`setup` 和 `bootstrap deps` 都会输出 `runtimeChecks`。如果机器缺少 `python`、`bun`、`cargo`、`uv/pipx`、`node/npm/npx`，会先显示缺失项和修复建议，再决定是否执行 `--yes` 或 `--apply`，避免安装中途卡住。
+`setup` 和 `bootstrap deps` 都会输出 `runtimeChecks`。如果机器缺少 `python`、`bun`、`cargo`、`uv/pipx`、`node/npm/npx`，会先显示缺失项和修复建议，再决定是否执行 `--apply`，避免安装中途卡住。
 
-记忆供应商可以在安装入口直接切换，不需要手改 `.scale/memory-providers.json`：
+记忆供应商可在安装入口直接切换，不需要手改 `.scale/memory-providers.json`：
 
 ```bash
 scale setup --pack memory --memory-provider scale-local --json
 scale setup --pack memory --memory-provider gbrain --memory-mode external-first --json
 ```
 
-第三方能力的职责边界：
+## 4. UI Skills 默认策略
+
+| 能力 | 默认定位 | 安装方式 | 关键验证 |
+| --- | --- | --- | --- |
+| `awesome-design-md` | 品牌、视觉语言、`DESIGN.md` 来源 | `scale setup --pack ui --include awesome-design-md --apply` | 生成 `~/.agents/skills/awesome-design-md/SKILL.md`，同步 `~/.scale/vendor/awesome-design-md` |
+| `ui-ux-pro-max` | UX、状态、可访问性、响应式验收 | `scale setup --pack ui --include ui-ux-pro-max --apply` | 生成 `~/.agents/skills/ui-ux-pro-max/SKILL.md`，同步 `~/.scale/vendor/ui-ux-pro-max` |
+| `frontend-design` | 可选实现陪跑，不再是 UI 默认必装项 | `scale setup --pack ui --include frontend-design --apply` | 需要时显式安装 |
+
+安装器优先使用 `git clone --depth 1` 同步上游仓库；如果没有 Git 但有 npx，会退回 `npx degit`。缺少两者时不会硬跑失败，会在安装计划里标记为需要人工处理并给出下一步。
+
+## 5. 其他第三方能力边界
 
 | 能力 | 默认定位 | 关键验证 |
 | --- | --- | --- |
-| `awesome-design-md` | 品牌、视觉语言、`DESIGN.md` 来源 | 是否同步上游 DESIGN.md catalog |
-| `ui-ux-pro-max` | UX、状态、可访问性、响应式验收 | 是否通过官方 `uipro-cli` 安装 |
-| `frontend-design` | 可选实现灵感，不再是 UI 默认必装项 | 需要时显式 `--include frontend-design` |
 | `rtk` | CLI proxy/token 节省能力 | `rtk gain` 和 `rtk init -g --codex` |
-| `gbrain` | 默认记忆供应商 | 检查 brain 是否已配置且连接/schema 可用，未初始化会提示 `gbrain init --pglite` |
+| `gbrain` | 默认记忆供应商 | 检查 brain 是否已配置且连接/schema 可用；未初始化会提示 `gbrain init --pglite` |
 | `graphify` | 知识图谱产物供应商 | `graphify install --platform codex` 和 `graphify-out/graph.json` |
 | `codegraph` | 代码结构索引供应商 | `codegraph init -i` 和 `.codegraph/` |
 
-低层命令仍可直接使用：
+底层命令仍可直接使用：
 
 ```bash
 scale bootstrap deps --profile advanced --governance-pack frontend-app --lang zh
 scale bootstrap deps --profile advanced --governance-pack frontend-app --apply --lang zh
 ```
 
-## 4. 验证闭环
+## 6. 验证闭环
 
 ```bash
 scale doctor
+scale setup --verify --pack full --json
 scale preflight --preflight-profile quick
 scale status
 scale assets scan --dir .
@@ -114,11 +143,11 @@ npm run smoke:graphify -- --large-project /path/to/large-project
 
 验证语义：
 
-- `smoke:gbrain` 会先确认 gbrain 已配置且召回关键健康检查可用，通过后写入一个临时记忆页，再用独立 CLI 进程 `get/query/search` 回放，证明不是本地 mock。
+- `smoke:gbrain` 会先确认 gbrain 已配置且关键健康检查可用，通过后写入一个临时记忆页，再用独立 CLI 进程 `get/query/search` 回放，证明不是本地 mock。
 - `smoke:graphify` 默认对真实项目执行 `graphify update <project> --no-cluster`，走 AST/Python 无模型路径，检查 `graph.json`，再执行 `graphify query`；只有显式 `--semantic-extract` 才允许语义模型提取。
-- `graphify-out/` 是生成产物，不应该提交到 Git；长期知识沉淀应进入经过评审的 `memory/`、docs 或规则文件。
+- `graphify-out/` 是生成产物，不应该提交到 Git；长期知识沉淀应进入经过评审的 `memory/`、`docs` 或规则文件。
 
-## 5. 建立任务上下文
+## 7. 建立任务上下文
 
 ```bash
 scale context init --name "Scale Demo"
@@ -139,7 +168,7 @@ scale memory settle --task-id 2026-05-18-oauth-hardening --session-id 2026-05-18
 
 `memory settle` 默认只生成学习候选，不会自动把一次会话判断提升成长线规则。存在失败证据时，候选会要求先解决失败，避免把未闭环问题沉淀成经验。
 
-## 6. MOE/多仓工作区
+## 8. MOE/多仓工作区
 
 多仓项目使用：
 
@@ -151,31 +180,12 @@ MOE 默认把子工程配置为兄弟仓库或绝对路径，不建议把独立
 
 ```json
 {
-  "topology": "moe",
-  "repositories": [
-    { "name": "root", "path": ".", "role": "root", "required": true },
-    { "name": "api", "path": "../api", "role": "external", "required": true, "remote": "origin" }
-  ]
+  "workspace": {
+    "type": "moe",
+    "repositories": [
+      { "name": "api", "path": "../api", "role": "service" },
+      { "name": "web", "path": "../web", "role": "frontend" }
+    ]
+  }
 }
 ```
-
-这样可以避免子工程 Git 状态、分支、提交和主工程互相污染。
-
-## 7. 安装烟测
-
-仓库开发和发版前可以一键验证安装入口：
-
-```bash
-npm run smoke:setup
-npm run smoke:providers
-make setup-smoke
-```
-
-`smoke:setup` 只验证安装计划、双语输出、运行时依赖诊断、记忆供应商切换和 CodeGraph/Graphify 状态路径，不会执行真实第三方安装。
-`smoke:providers` 会执行真实供应商回放；未配置 gbrain 或 graphify 时输出 `blocked` 和修复命令，只有 `smoke:gbrain`/`smoke:graphify` 或显式 `--require-*` 才会失败退出。
-
-遇到跨系统命令兼容、PATH 或运行时依赖问题时，先导出环境诊断：
-
-```bash
-scale doctor env --json
-```

package/docs/start/workflow-upgrade.md

@@ -51,7 +51,14 @@ scale init --governance-pack frontend-app
 
 ## 更新已有工作流
 
-按这个顺序运行：
+默认使用升级向导：
+
+```bash
+scale upgrade --dir .
+scale preflight --dir . --service all --preflight-profile quick
+```
+
+向导会生成计划和 HTML 报告；如果计划可安全应用，会在交互式终端询问是否立即应用。需要 CI 或精确控制时，再使用分步命令：
 
 ```bash
 scale upgrade check --dir .

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hongmaple0820/scale-engine",
-  "version": "0.40.0",
+  "version": "0.40.2",
   "description": "Executable AI agent governance with workflow gates, evidence, skill/tool orchestration, and traceable HTML artifacts",
   "repository": {
     "type": "git",
@@ -48,6 +48,7 @@
     "docs/workflow",
     "image",
     "examples/demo-projects/agent-governance-demo",
+    "scripts/workflow/lib",
     "scripts/workflow/setup-smoke.mjs",
     "scripts/workflow/provider-rehearsal.mjs"
   ],
@@ -65,7 +66,7 @@
     "smoke:providers": "node scripts/workflow/provider-rehearsal.mjs",
     "smoke:gbrain": "node scripts/workflow/provider-rehearsal.mjs --skip-graphify --require-gbrain",
     "smoke:graphify": "node scripts/workflow/provider-rehearsal.mjs --skip-gbrain --require-graphify",
-    "release:check": "npm run typecheck && npm run lint && npm test && npm run smoke:setup && npm run build && npm audit --omit=dev && git diff --check && npm pack --dry-run",
+    "release:check": "npm run typecheck && npm run lint && npm test && npm run smoke:setup && npm run smoke:providers -- --write-report && npm run build && npm audit --omit=dev && git diff --check && npm pack --dry-run",
     "mcp": "node dist/api/mcp.js",
     "serve": "node dist/api/http.js"
   },

package/scripts/workflow/lib/gbrain-runtime.mjs

@@ -0,0 +1,185 @@
+import { createHash } from 'node:crypto'
+import { cpSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+
+const MIRROR_META_FILE = '.scale-gbrain-runtime.json'
+const GBRAIN_TIMEOUT_RECOVERY_COMMANDS = new Set(['--version', 'version', 'doctor', 'list', 'get', 'query', 'search'])
+
+export function resolveDirectWindowsGbrainInvocation(command, args, resolveCommandPath) {
+  if (process.platform !== 'win32' || command !== 'gbrain') return null
+  const gbrainShim = resolveCommandPath('gbrain')
+  if (!gbrainShim || !/\.cmd$/i.test(gbrainShim) || !existsSync(gbrainShim)) return null
+  try {
+    const content = readFileSync(gbrainShim, 'utf8')
+    const match = content.match(/call\s+"([^"]*bun\.cmd)"\s+"([^"]*src[\\/]cli\.ts)"/i)
+    const cliPath = match?.[2]
+    const bunShim = match?.[1] ?? resolveCommandPath('bun')
+    const bunExe = bunShim ? join(dirname(bunShim), 'node_modules', 'bun', 'bin', 'bun.exe') : ''
+    if (cliPath && bunExe && existsSync(bunExe)) {
+      return {
+        command: bunExe,
+        args: [cliPath, ...args],
+        cwd: dirname(dirname(cliPath)),
+        cliPath,
+      }
+    }
+  } catch {
+    return null
+  }
+  return null
+}
+
+export function shouldRetryWithMirroredGbrain(invocation, result) {
+  if (!invocation?.cliPath) return false
+  if (result.status === 0) return false
+  const output = `${String(result.stdout ?? '')}\n${String(result.stderr ?? '')}\n${String(result.error?.message ?? '')}`
+  if (!/EPERM reading/i.test(output)) return false
+  return normalizeForCompare(output).includes(normalizeForCompare(invocation.cliPath))
+}
+
+export function ensureMirroredGbrainInvocation(invocation) {
+  const packageRoot = invocation.cwd
+  const cliMtimeMs = statSync(invocation.cliPath).mtimeMs
+  const version = readPackageVersion(packageRoot)
+  const mirrorKey = `${resolve(packageRoot)}|${version ?? ''}|${cliMtimeMs}`
+  const mirrorRoot = join(
+    tmpdir(),
+    'scale-engine',
+    'gbrain-runtime',
+    createHash('sha1').update(mirrorKey).digest('hex').slice(0, 16),
+  )
+  const cliRelativePath = invocation.cliPath.slice(packageRoot.length + 1)
+  const mirrorCliPath = join(mirrorRoot, cliRelativePath)
+  let selectedRoot = mirrorRoot
+  if (!isMirrorFresh(mirrorRoot, packageRoot, version, cliMtimeMs, mirrorCliPath)) {
+    const stagedRoot = `${mirrorRoot}-staging-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2, 8)}`
+    rmSync(stagedRoot, { recursive: true, force: true })
+    mkdirSync(dirname(mirrorRoot), { recursive: true })
+    cpSync(packageRoot, stagedRoot, { recursive: true, force: true })
+    writeFileSync(join(stagedRoot, MIRROR_META_FILE), JSON.stringify({
+      sourceRoot: packageRoot,
+      version,
+      cliMtimeMs,
+    }, null, 2), 'utf8')
+    const stagedCliPath = join(stagedRoot, cliRelativePath)
+    if (!isMirrorFresh(mirrorRoot, packageRoot, version, cliMtimeMs, mirrorCliPath)) {
+      try {
+        renameSync(stagedRoot, mirrorRoot)
+      } catch {
+        if (isMirrorFresh(mirrorRoot, packageRoot, version, cliMtimeMs, mirrorCliPath)) {
+          rmSync(stagedRoot, { recursive: true, force: true })
+        } else {
+          selectedRoot = stagedRoot
+        }
+      }
+    } else {
+      rmSync(stagedRoot, { recursive: true, force: true })
+    }
+    if (selectedRoot === mirrorRoot && !existsSync(mirrorCliPath) && existsSync(stagedCliPath)) selectedRoot = stagedRoot
+  }
+  return {
+    ...invocation,
+    args: [join(selectedRoot, cliRelativePath), ...invocation.args.slice(1)],
+    cwd: selectedRoot,
+    cliPath: join(selectedRoot, cliRelativePath),
+  }
+}
+
+export function normalizeGbrainSpawnResult(args, result) {
+  const stdout = String(result.stdout ?? '')
+  const stderr = `${String(result.stderr ?? '')}${result.error ? `\n${result.error.message}` : ''}`.trim()
+  const exitCode = typeof result.status === 'number' ? result.status : 1
+  const timedOut = /ETIMEDOUT/i.test(String(result.error?.message ?? ''))
+  const recoveredTimeout = shouldRecoverGbrainTimeout(args, stdout, stderr, exitCode, timedOut)
+  return {
+    stdout,
+    stderr: recoveredTimeout ? stripRecoverableTimeoutNoise(stderr) : stderr,
+    exitCode: recoveredTimeout ? 0 : exitCode,
+    timedOut: recoveredTimeout ? false : timedOut,
+    recoveredTimeout,
+  }
+}
+
+function isMirrorFresh(mirrorRoot, sourceRoot, version, cliMtimeMs, mirrorCliPath) {
+  if (!existsSync(mirrorCliPath)) return false
+  const metadataPath = join(mirrorRoot, MIRROR_META_FILE)
+  if (!existsSync(metadataPath)) return false
+  try {
+    const parsed = JSON.parse(readFileSync(metadataPath, 'utf8'))
+    return parsed.sourceRoot === sourceRoot
+      && parsed.version === version
+      && parsed.cliMtimeMs === cliMtimeMs
+  } catch {
+    return false
+  }
+}
+
+function readPackageVersion(packageRoot) {
+  try {
+    const parsed = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8'))
+    return typeof parsed.version === 'string' ? parsed.version : undefined
+  } catch {
+    return undefined
+  }
+}
+
+function normalizeForCompare(value) {
+  return String(value).replace(/\//g, '\\').toLowerCase()
+}
+
+function shouldRecoverGbrainTimeout(args, stdout, stderr, exitCode, timedOut) {
+  if (!timedOut || exitCode === 0) return false
+  const command = String(args?.[0] ?? '').trim().toLowerCase()
+  if (!command || !GBRAIN_TIMEOUT_RECOVERY_COMMANDS.has(command)) return false
+  const cleanedStderr = stripRecoverableTimeoutNoise(stderr)
+  if (cleanedStderr) return false
+  return hasRecoverableGbrainOutput(command, stdout.trim())
+}
+
+function hasRecoverableGbrainOutput(command, stdout) {
+  if (!stdout) return false
+  switch (command) {
+    case '--version':
+    case 'version':
+      return /\bgbrain\b/i.test(stdout) || /\d+\.\d+\.\d+/.test(stdout)
+    case 'doctor':
+      return looksLikeJsonOutput(stdout)
+    case 'list':
+      return /no pages found/i.test(stdout)
+        || /^\d+\.\s+\S+/m.test(stdout)
+        || /^\[\d+(?:\.\d+)?\]\s+/m.test(stdout)
+    case 'get':
+      return /^---$/m.test(stdout)
+        || /^#\s+\S+/m.test(stdout)
+        || looksLikeJsonOutput(stdout)
+    case 'query':
+    case 'search':
+      return looksLikeJsonOutput(stdout)
+        || /no (pages|results) found/i.test(stdout)
+        || /^\[\d+(?:\.\d+)?\]\s+/m.test(stdout)
+        || /^\d+\.\s+\S+/m.test(stdout)
+    default:
+      return false
+  }
+}
+
+function looksLikeJsonOutput(stdout) {
+  const trimmed = String(stdout ?? '').trim()
+  if (!trimmed || (!trimmed.startsWith('{') && !trimmed.startsWith('['))) return false
+  try {
+    JSON.parse(trimmed)
+    return true
+  } catch {
+    return false
+  }
+}
+
+function stripRecoverableTimeoutNoise(stderr) {
+  return String(stderr ?? '')
+    .replace(/\n?spawnSync .*?\bETIMEDOUT\b\s*/gim, '\n')
+    .replace(/\n?Command failed: .*?\bETIMEDOUT\b\s*/gim, '\n')
+    .replace(/\n?timed out after .*$/gim, '\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim()
+}

package/scripts/workflow/lib/report-output.mjs

@@ -0,0 +1,107 @@
+function stripAnsi(value) {
+  return String(value ?? '').replace(/\u001B\[[0-9;]*m/g, '')
+}
+
+export function summarizeCommandOutput(name, stream, value, max = 1600) {
+  const sanitized = sanitizeCommandOutput(name, stream, stripAnsi(value))
+  if (!sanitized.trim()) return ''
+  const summary = commandSpecificSummary(name, stream, sanitized)
+  return compactText(summary ?? sanitized, max)
+}
+
+export function summarizeCommandRecord(record) {
+  if (!record) return record
+  const {
+    stdout,
+    stderr,
+    ...rest
+  } = record
+  return {
+    ...rest,
+    stdoutTail: summarizeCommandOutput(record.name, 'stdout', stdout ?? record.stdoutTail ?? ''),
+    stderrTail: summarizeCommandOutput(record.name, 'stderr', stderr ?? record.stderrTail ?? ''),
+  }
+}
+
+function sanitizeCommandOutput(name, stream, value) {
+  let text = String(value ?? '').replace(/\r\n/g, '\n').replace(/[�]+/g, '')
+  if (isGbrainCommand(name)) {
+    if (stream === 'stderr') {
+      text = text
+        .replace(/^\s*The system cannot find the path specified\.\s*$/gim, '')
+        .replace(/\n?={20,}\n[\s\S]*?The user owns this decision\.\n={20,}\n?/g, '\n')
+    }
+    if (stream === 'stdout' && /init/i.test(name)) {
+      text = text
+        .replace(/\n?═{10,}\n\[gbrain\] search mode tentatively set[\s\S]*?To see what is running: gbrain search modes\n*/g, '\n')
+        .replace(/\n--- GBrain Mod Status ---[\s\S]*$/g, '')
+    }
+  }
+  return normalizeMultiline(text)
+}
+
+function commandSpecificSummary(name, stream, value) {
+  if (stream !== 'stdout') return undefined
+  if (name === 'gbrain-init' || name === 'gbrain-init-isolated-home') {
+    return collectMatchingLines(value, [
+      /migration\(s\) applied/i,
+      /^Brain ready at /i,
+      /^0 pages\./i,
+      /^Next: /i,
+      /^When you outgrow local:/i,
+    ])
+  }
+  if (name === 'graphify-update' || name === 'graphify-extract') {
+    return collectMatchingLines(value, [
+      /Rebuilt/i,
+      /graph\.json updated/i,
+      /^Code graph updated\./i,
+      /^Tip:/i,
+    ])
+  }
+  if (name === 'graphify-benchmark') {
+    return collectMatchingLines(value, [
+      /^graphify token reduction benchmark$/i,
+      /^\s*Corpus:/i,
+      /^\s*Graph:/i,
+      /^\s*Avg query cost:/i,
+      /^\s*Reduction:/i,
+    ])
+  }
+  if (name === 'graphify-query') {
+    return firstInterestingLines(value, 12)
+  }
+  return undefined
+}
+
+function collectMatchingLines(value, patterns) {
+  const lines = normalizeMultiline(value).split('\n').map(line => line.trim()).filter(Boolean)
+  const selected = lines.filter(line => patterns.some(pattern => pattern.test(line)))
+  return selected.length > 0 ? selected.join('\n') : undefined
+}
+
+function firstInterestingLines(value, maxLines) {
+  const lines = normalizeMultiline(value)
+    .split('\n')
+    .map(line => line.trim())
+    .filter(Boolean)
+    .filter(line => !/^[=._-]{6,}$/.test(line))
+  return lines.slice(0, maxLines).join('\n')
+}
+
+function compactText(value, max) {
+  const normalized = normalizeMultiline(value)
+  if (normalized.length <= max) return normalized
+  return `${normalized.slice(0, max - 1)}…`
+}
+
+function normalizeMultiline(value) {
+  return String(value ?? '')
+    .replace(/[ \t]+\n/g, '\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim()
+}
+
+function isGbrainCommand(name) {
+  return /^gbrain-/i.test(String(name ?? ''))
+}