dsh-paoding 0.2.2 → 0.3.0

package/tools/lib/skills.mjs

@@ -1,8 +1,12 @@
 /**
- * 技能发现与 SKILL.md 元数据解析：detectSkills 扫描四类根目录（$DSH_HOME/
- * $DSH_AGENTS_HOME/项目 .dsh|.agents skills），findSkillMeta 定位并读取一个
- * SKILL.md、解析 frontmatter description（skillDescriptionOf /
- * stripSkillDescription）。依赖 node:fs / node:os / node:path；被 state 引用。
+ * 技能发现与 SKILL.md 元数据解析：detectSkills / findSkillMeta 共用同一组根
+ * 目录——用户级两根（$DSH_HOME/skills、$DSH_AGENTS_HOME|~/.agents/skills）
+ * 恒扫；项目级两根（<cwd>/.dsh/skills、<cwd>/.agents/skills）仅在 cwd 显式
+ * 传入具体工作区目录时追加，cwd 为 null/undefined/空串即「全局语义」，只扫
+ * 用户级（技能扫描不跟随 GUI 进程启动目录，项目根按工作区按需传入）。
+ * findSkillMeta 定位并读取一个 SKILL.md、解析 frontmatter description
+ * （skillDescriptionOf / stripSkillDescription）。依赖 node:fs / node:os /
+ * node:path；被 state 引用。
  */
 import { readFileSync, readdirSync } from 'node:fs'
 import { homedir } from 'node:os'
@@ -13,18 +17,21 @@ import path from 'node:path'
 /**
  * Discover installed skills from the same roots dsh-skill-filesystem scans:
  * user roots ($DSH_HOME/skills, $DSH_AGENTS_HOME/skills or ~/.agents/skills)
- * plus project roots (<cwd>/.dsh/skills, <cwd>/.agents/skills).  A skill is a
+ * always, plus the project roots (<cwd>/.dsh/skills, <cwd>/.agents/skills)
+ * only when `cwd` is a non-empty string — null / undefined / '' means the
+ * global view (user roots only; scanning never follows the GUI process start
+ * directory, project roots are per-workspace opt-in).  A skill is a
  * directory or a .md file; its name is the basename.  Roots that do not exist
  * are skipped.
  */
-export function detectSkills(dshHome, cwd) {
+export function detectSkills(dshHome, cwd = null) {
   const agentsHome = process.env.DSH_AGENTS_HOME || path.join(homedir(), '.agents')
+  // 用户级两根恒扫；cwd 非空（显式传入工作区目录）才追加项目级两根。
   const roots = [
     path.join(dshHome, 'skills'),
     path.join(agentsHome, 'skills'),
-    path.join(cwd, '.dsh', 'skills'),
-    path.join(cwd, '.agents', 'skills'),
   ]
+  if (cwd) roots.push(path.join(cwd, '.dsh', 'skills'), path.join(cwd, '.agents', 'skills'))
   const skills = new Set()
   for (const root of roots) {
     let entries
@@ -37,7 +44,9 @@ export function detectSkills(dshHome, cwd) {
       if (entry.isDirectory()) {
         if (entry.name.startsWith('.')) continue
         skills.add(entry.name)
-      } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      } else if (entry.isFile() && entry.name.endsWith('.md') && !entry.name.startsWith('.')) {
+        // 文件分支同样跳过点开头名：.foo.md 不是技能（编辑器/系统临时文件常是
+        // 点前缀），与目录分支口径一致。
         skills.add(entry.name.slice(0, -'.md'.length))
       }
     }
@@ -51,8 +60,10 @@ export function detectSkills(dshHome, cwd) {
  * default soft mode writes a compact skill row (name + description + absolute
  * SKILL.md path) into the persona and the main agent reads the full rules on
  * demand with its own read tool (zero directory injection); the optional hard
- * inline mode inlines the full body instead.  Uses the same four roots as
- * detectSkills; within each root a directory skill (<root>/<name>/SKILL.md)
+ * inline mode inlines the full body instead.  Uses the same roots as
+ * detectSkills (user roots always; project roots only for a non-empty `cwd`,
+ * i.e. the target workspace); within each root a directory skill
+ * (<root>/<name>/SKILL.md)
  * wins over a bare <root>/<name>.md file.  Strips the leading YAML
  * frontmatter when present, then trims.  `description` is parsed from the
  * frontmatter (single-line, quoted, folded `>` or literal `|` block — block
@@ -62,14 +73,15 @@ export function detectSkills(dshHome, cwd) {
  * { name, description, file, body } with `file` the absolute SKILL.md path,
  * or null when not found / empty body.
  */
-export function findSkillMeta(name, dshHome, cwd) {
+export function findSkillMeta(name, dshHome, cwd = null) {
   const agentsHome = process.env.DSH_AGENTS_HOME || path.join(homedir(), '.agents')
+  // 与 detectSkills 同款：用户级两根恒扫；cwd 非空（目标工作区目录）才追加
+  // 项目级两根——全局目标只解析用户级技能，工作区目标可解析该项目根里的技能。
   const roots = [
     path.join(dshHome, 'skills'),
     path.join(agentsHome, 'skills'),
-    path.join(cwd, '.dsh', 'skills'),
-    path.join(cwd, '.agents', 'skills'),
   ]
+  if (cwd) roots.push(path.join(cwd, '.dsh', 'skills'), path.join(cwd, '.agents', 'skills'))
   const fmRe = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/
   for (const root of roots) {
     for (const candidate of [path.join(root, name, 'SKILL.md'), path.join(root, `${name}.md`)]) {
@@ -79,6 +91,9 @@ export function findSkillMeta(name, dshHome, cwd) {
       } catch {
         continue
       }
+      // 先剥 UTF-8 BOM（Windows 编辑器常见）：否则 ^--- 锚点失配，frontmatter
+      // 整体解析失效（description 丢失、正文残留 frontmatter）。
+      if (text.startsWith('\uFEFF')) text = text.slice(1)
       const body = text.replace(fmRe, '').trim()
       if (body === '') return null
       const fm = text.match(fmRe)
@@ -94,47 +109,59 @@ export function findSkillMeta(name, dshHome, cwd) {
  * scalars (marker on the key line or on its own next line): block content is
  * the following indented lines up to the first key line at or above the
  * description key's indent (or the frontmatter end), whitespace-collapsed.
+ * 零缩进键优先：嵌套映射里的同名键（子对象的 description）不再抢在顶层
+ * frontmatter 键之前命中；没有零缩进键时回退到首个任意缩进的同名键（原行为）。
  * Returns '' when the key is absent or empty.
  */
 export function skillDescriptionOf(frontmatter) {
   const lines = frontmatter.split(/\r?\n/)
+  // 第一遍：只认零缩进 description 键（顶层 frontmatter 键）。
+  for (let i = 0; i < lines.length; i++) {
+    const key = lines[i].match(/^description:\s*(.*)$/)
+    if (key) return descriptionValueAt(lines, i, key[1], 0)
+  }
+  // 第二遍回退：首个任意缩进的同名键（原行为）。
   for (let i = 0; i < lines.length; i++) {
     const key = lines[i].match(/^(\s*)description:\s*(.*)$/)
-    if (!key) continue
-    const indent = key[1].length
-    let value = key[2]
-    let contentFrom = i + 1
-    if (value !== '') {
-      if (!/^[>|][+-]?\d*$/.test(value)) return stripSkillDescription(value)
-      // block marker on the key line: content starts on the next line
-    } else if (lines[i + 1] && /^\s*[>|][+-]?\d*\s*$/.test(lines[i + 1])) {
-      contentFrom = i + 2 // marker on its own line
-    } else {
-      return '' // empty value, no block scalar
-    }
-    let stop = lines.length
-    let minIndent = Infinity
-    for (let j = contentFrom; j < lines.length; j++) {
-      const line = lines[j]
-      if (line.trim() === '') continue
-      const lineIndent = (line.match(/^[ \t]*/) ?? [''])[0].length
-      if (lineIndent <= indent) {
-        stop = j
-        break
-      }
-      if (lineIndent < minIndent) minIndent = lineIndent
-    }
-    if (minIndent === Infinity) return ''
-    const parts = []
-    for (let j = contentFrom; j < stop; j++) {
-      const line = lines[j]
-      parts.push(line.trim() === '' ? '' : line.slice(Math.min(minIndent, line.length)))
-    }
-    return stripSkillDescription(parts.join(' '))
+    if (key) return descriptionValueAt(lines, i, key[2], key[1].length)
   }
   return ''
 }
 
+/** 从 lines[i] 的 description 键解析其值（value 为键行冒号后的原文，indent 为
+ * 键缩进；块标量正文取自后续行）。语义与抽出的原实现逐字一致。 */
+function descriptionValueAt(lines, i, rawValue, indent) {
+  let value = rawValue
+  let contentFrom = i + 1
+  if (value !== '') {
+    if (!/^[>|][+-]?\d*$/.test(value)) return stripSkillDescription(value)
+    // block marker on the key line: content starts on the next line
+  } else if (lines[i + 1] && /^\s*[>|][+-]?\d*\s*$/.test(lines[i + 1])) {
+    contentFrom = i + 2 // marker on its own line
+  } else {
+    return '' // empty value, no block scalar
+  }
+  let stop = lines.length
+  let minIndent = Infinity
+  for (let j = contentFrom; j < lines.length; j++) {
+    const line = lines[j]
+    if (line.trim() === '') continue
+    const lineIndent = (line.match(/^[ \t]*/) ?? [''])[0].length
+    if (lineIndent <= indent) {
+      stop = j
+      break
+    }
+    if (lineIndent < minIndent) minIndent = lineIndent
+  }
+  if (minIndent === Infinity) return ''
+  const parts = []
+  for (let j = contentFrom; j < stop; j++) {
+    const line = lines[j]
+    parts.push(line.trim() === '' ? '' : line.slice(Math.min(minIndent, line.length)))
+  }
+  return stripSkillDescription(parts.join(' '))
+}
+
 /** Collapse whitespace, strip one pair of surrounding quotes, cap at 200 chars. */
 export function stripSkillDescription(raw) {
   let value = raw.trim()

package/tools/lib/state.mjs

@@ -1,16 +1,19 @@
 /**
  * 公共状态管线：collectState（patch 分层扫描 / MCP 工具名解析 / 插件与技能检测 /
- * smart defaults，含可选 runtimeFacts 合并）与 generateAndInstall（compose +
- * yaml 校验 + dst 目录落盘 + saveConfig）。install.mjs 的公共导出
- * （collectState / generateAndInstall）即来自本模块。
- * 依赖 util / yaml / config / host / skills / spans / compose / alloc 与
- * node:fs / node:path；被 cli 与 plugins/paoding-config-ui 引用。
+ * smart defaults，含可选 runtimeFacts 合并 / 已落盘 preset 目录扫描）与
+ * generateAndInstall（compose + yaml 校验 + dst 目录落盘 + saveConfig，支持按
+ * 工作区落到 orchestrator-<slug> 独立 preset 目录并把条目并进配置 workspaces 段；
+ * 配置读取失败 / 状态不可信时拒绝破坏性落盘，成功后回收孤儿工作区 preset）。
+ * install.mjs 的公共导出（collectState / generateAndInstall）即来自本模块。
+ * 依赖 util / yaml / config / host / skills / spans / compose / alloc / workspaces
+ * 与 node:fs / node:path；被 cli 与 plugins/paoding-config-ui 引用。
  */
 import {
   chmodSync,
   copyFileSync,
   existsSync,
   mkdirSync,
+  readdirSync,
   readFileSync,
   rmSync,
   statSync,
@@ -19,7 +22,15 @@ import {
 import path from 'node:path'
 import { DEFAULT_MAIN_AGENT_PERSONA_EXTRA, ROLES, SRC_DIR, warn } from './util.mjs'
 import { flattenEntries, loadYaml, parsePatchFile } from './yaml.mjs'
-import { loadConfig, normalizeMainAgentName, saveConfig, yamlScalar } from './config.mjs'
+import {
+  loadConfig,
+  normalizeRoleName,
+  normalizeTargetFields,
+  saveConfig,
+  stripNonTargetKeys,
+  yamlScalar,
+} from './config.mjs'
+import { assignSlugs, presetIdOf } from './workspaces.mjs'
 import {
   extractMcp,
   isEntryEnabled,
@@ -69,21 +80,12 @@ export async function collectState({ dshHome, configFile, profile = null, patche
   } catch (err) {
     throw new Error(`cannot locate role blocks in ${path.join(SRC_DIR, 'agent.cordis.yml')}: ${err.message}`)
   }
-  let restrictBase
-  try {
-    restrictBase = extractMainAgentAllow(restrictSrc)
-  } catch (err) {
-    throw new Error(err.message)
-  }
+  // 这层包装无增值（错误文案原样透传），让原始错误直接上抛。
+  const restrictBase = extractMainAgentAllow(restrictSrc)
 
   // Load the existing config (null when absent); its profile wins unless an
-  // explicit profile was given.
-  let existing = null
-  try {
-    existing = loadConfig(configFile, yamlMod)
-  } catch (err) {
-    throw new Error(err.message)
-  }
+  // explicit profile was given. 读失败（存在但解析不了等）原样上抛，不做静默降级。
+  const existing = loadConfig(configFile, yamlMod)
   const effectiveProfile = profile ?? existing?.profile ?? 'web'
 
   // Scan the patch layers (home, profile, extra --patch files) in order.
@@ -145,7 +147,11 @@ export async function collectState({ dshHome, configFile, profile = null, patche
     for (const tool of plugin.tools) inventory.add(tool)
   }
 
-  const skills = detectSkills(dshHome, cwd)
+  // 技能检测走全局语义（cwd 传 null，只扫用户级两根）：state.skills 是全局
+  // 视角的用户级技能，不再跟随进程启动目录（GUI 场景下启动目录没有「当前
+  // 项目」含义）；工作区视角的项目级技能由插件路由按工作区目录另行检测。
+  // cwd 入参保留不动（patch 扫描外的其余用途与透传照旧）。
+  const skills = detectSkills(dshHome, null)
   const staticBase = {}
   for (const role of ROLES) staticBase[role] = blocks.get(role).names
   const suggested = smartDefaults(mcpReports, inventory, staticBase)
@@ -205,6 +211,19 @@ export async function collectState({ dshHome, configFile, profile = null, patche
     }
   }
 
+  // 已落盘 preset 目录扫描（编排类）：.agent-presets 下的 orchestrator 基础
+  // preset 与 orchestrator-<slug> 工作区专属 preset。扫描失败（目录尚不存在、
+  // 无读权限等）一律降级为空列表，绝不影响检测结果本体；generateAndInstall
+  // 成功落盘后以它为对账清单做孤儿工作区 preset 回收。
+  let installedPresets = []
+  try {
+    installedPresets = readdirSync(path.join(dshHome, '.agent-presets'))
+      .filter((name) => /^orchestrator(-[a-z0-9-]+)?$/.test(name))
+      .sort()
+  } catch {
+    installedPresets = []
+  }
+
   return {
     dshHome,
     cwd,
@@ -226,6 +245,9 @@ export async function collectState({ dshHome, configFile, profile = null, patche
     skills,
     staticBase,
     suggested,
+    // 已落盘的编排类 preset 目录名列表（含基础 orchestrator 与各工作区专属），
+    // 供 UI 的 workspaceMeta 对账「该工作区 preset 是否已生成」。
+    installedPresets,
     // 主 persona 尾部追加的默认常量（配置键 main_agent_persona_extra 缺省值）：
     // 供 UI state（serializeState → /api/paoding/state）展示与「恢复默认」用。
     mainPersonaExtraDefault: DEFAULT_MAIN_AGENT_PERSONA_EXTRA,
@@ -240,30 +262,73 @@ export async function collectState({ dshHome, configFile, profile = null, patche
 /**
  * Compose, validate and (unless dry-run) install the generated preset from an
  * assignments object. Shared by the CLI and the visual config UI.
- * Returns { text, roleResults, staleNote, wrote }.
+ * Returns { text, roleResults, staleNote, wrote, presetId }.
+ *
+ * 破坏性落盘护栏：配置读取失败直接抛错中止（不静默降级 prev=null 继续装）；
+ * 配置缺失（prev=null）而目标 preset 目录已存在时同样拒绝重建。落盘成功后对
+ * state.installedPresets 做孤儿工作区 preset 回收（不被 workspaces 引用的
+ * orchestrator-<slug> 目录 rmSync + warn；基础 preset 永不清）。
+ *
+ * workspacePath（可选）：传工作区绝对路径时生成落到 orchestrator-<slug> 独立
+ * preset 目录（slug 由磁盘配置现有 workspaces 键 ∪ 本路径统一分配，同名目录
+ * 冲突自动加 hash 后缀），preset 显示名按 main_agent_display_name >
+ * （工作区预设派生名）「SRC 名·目录名」取值，
+ * 存盘只把该条目并进配置 workspaces 段（顶层字段维持磁盘现状）；不传（null）
+ * 走全局路径，落点与存盘行为和旧版完全一致。
  */
-export function generateAndInstall(state, assignments, { dryRun = false, saveConfigOnWrite = false } = {}) {
-  const { srcText, blocks, personaBlocks, inventory, restrictBase, yamlMod, dshHome, cwd, dstDir, dstAgentFile, configFile, scanned, effectiveProfile } = state
+export function generateAndInstall(state, assignments, { dryRun = false, saveConfigOnWrite = false, workspacePath = null } = {}) {
+  const { srcText, blocks, personaBlocks, inventory, restrictBase, yamlMod, dshHome, configFile, scanned, effectiveProfile } = state
+
+  // assignments 剥污染键：profile / workspaces 不属于目标字段，UI/CLI 透传
+  // 一律丢弃，防其混进生成的 preset 或覆盖配置文件里对应的段。
+  assignments = stripNonTargetKeys(assignments)
+
+  // 工作区定位：路径归一（容忍尾斜杠 / 相对写法），空值一律视为全局。
+  const wsPath = workspacePath === null || workspacePath === undefined || workspacePath === ''
+    ? null
+    : path.normalize(path.resolve(workspacePath))
+  let dstDir = state.dstDir
+  let presetId = 'orchestrator'
+
+  // 配置现状读取（下方 slug 分配与 saveConfig 合并共用这一次，避免双读漂移）：
+  // 读失败（存在但解析不了 / 权限错）直接抛错中止 —— 旧版静默降级 prev=null 后
+  // 继续 rmSync / 覆写配置，等于对着不可信状态做破坏性落盘，已收紧为硬错误。
+  let prev = null
+  try {
+    prev = loadConfig(configFile, yamlMod)
+  } catch (err) {
+    throw new Error(`现有配置 ${configFile} 读取失败，已中止（未做任何落盘）: ${err.message}`)
+  }
+
+  if (wsPath !== null) {
+    // slug 取自磁盘配置的 workspaces 键集合 ∪ 本路径（prev 已在上方统一读取）：
+    // 整组统一分配才能让同 basename 的冲突方都拿到稳定的 hash 后缀。
+    const wsPaths = Object.keys(prev?.workspaces ?? {})
+    if (!wsPaths.includes(wsPath)) wsPaths.push(wsPath)
+    presetId = presetIdOf(assignSlugs(wsPaths).get(wsPath))
+    dstDir = path.join(dshHome, '.agent-presets', presetId)
+  }
+  const dstAgentFile = path.join(dstDir, 'agent.cordis.yml')
 
   // Pre-read the SKILL.md metas of the skills selected for the main-agent
   // persona (soft rows via main_agent_skills + optional hard inlining via
-  // main_agent_skills_inline; union, deduped).  Names whose file is missing
+  // main_agent_skills_inline; union, deduped).  技能按生成目标解析：工作区
+  // 目标用该工作区目录（wsPath，已归一为绝对路径）追加项目级两根，可解析该
+  // 工作区项目根里的技能（SKILL.md 绝对路径写进 persona，供主 agent read 按
+  // 需读）；全局目标传 null 只解析用户级。Names whose file is missing
   // simply do not enter the map — composeGenerated warns about them.
+  const skillCwd = wsPath
   const softNames = (assignments?.main_agent_skills ?? []).filter((n) => typeof n === 'string' && n !== '')
   const hardNames = (assignments?.main_agent_skills_inline ?? []).filter((n) => typeof n === 'string' && n !== '')
   const mainAgentSkillMetas = {}
   for (const name of [...new Set([...softNames, ...hardNames])]) {
-    const hit = findSkillMeta(name, dshHome, cwd)
+    const hit = findSkillMeta(name, dshHome, skillCwd)
     if (hit) mainAgentSkillMetas[name] = hit
   }
 
   // Compose the generated config; a composition error is a hard error.
-  let composed
-  try {
-    composed = composeGenerated(srcText, blocks, personaBlocks, assignments, inventory, restrictBase, mainAgentSkillMetas)
-  } catch (err) {
-    throw new Error(err.message)
-  }
+  //（这层包装无增值，让 composeGenerated 的原始错误直接上抛。）
+  const composed = composeGenerated(srcText, blocks, personaBlocks, assignments, inventory, restrictBase, mainAgentSkillMetas)
   const generatedText = composed.text
   const roleResults = composed.roleResults
 
@@ -292,23 +357,50 @@ export function generateAndInstall(state, assignments, { dryRun = false, saveCon
     )
   }
 
+  // preset.yml 显示名，两级优先：main_agent_display_name（仅显示名键，persona
+  // 身份行不可改名）> 工作区预设派生名（wsPath 非空且未设显示名时取
+  // 「SRC preset.yml 的 name 值·工作区目录名」，让预设选择器能分清多个工作区）；
+  // 全局路径未设显示名时维持 SRC 原名（行为与旧版一致）。displayNameSource
+  // 记住显示名来自哪个键：找不到可替换的 name: 行时 warn 按真实来源归因
+  // （派生名不来自任何键，单独措辞）。
+  let displayName = normalizeRoleName(assignments?.main_agent_display_name ?? null, 'main_agent_display_name')
+  let displayNameSource = displayName !== null ? 'main_agent_display_name' : null
+  if (displayName === null && wsPath !== null) {
+    try {
+      const srcPresetText = readFileSync(path.join(SRC_DIR, 'preset.yml'), 'utf8')
+      const m = /^name:[ \t]*(.+?)[ \t]*$/m.exec(srcPresetText)
+      if (m) displayName = `${m[1]}·${path.basename(wsPath)}`
+    } catch {
+      /* SRC preset 不可读 / 无 name 行：维持原名不改 */
+    }
+  }
+
   let wrote = false
   if (!dryRun) {
+    // 破坏性落盘护栏：配置不可信（读取失败已在上方抛错中止；此处 prev=null =
+    // 配置文件缺失）而目标 preset 目录已存在时，拒绝 rmSync 重建与随后的配置
+    // 覆写 —— 对着未知状态动刀可能毁掉用户仅存的落盘 preset。全新安装（无配置
+    // 且无目录）不受影响，仍照常装。
+    if (prev === null && existsSync(dstDir)) {
+      throw new Error(
+        `配置文件 ${configFile} 缺失但 preset 目录已存在（${dstDir}），已拒绝破坏性重建；` +
+          '请先恢复配置文件，或手动删除该目录后重试',
+      )
+    }
     mkdirSync(path.join(dshHome, '.agent-presets'), { recursive: true })
     rmSync(dstDir, { recursive: true, force: true })
     mkdirSync(dstDir, { recursive: true })
     for (const name of ['preset.yml', 'restrict.mjs']) {
       const src = path.join(SRC_DIR, name)
       const dst = path.join(dstDir, name)
-      const mainAgentName = normalizeMainAgentName(assignments?.main_agent_name ?? null)
-      if (name === 'preset.yml' && mainAgentName !== null) {
-        // main_agent_name 非空：preset 显示名改为配置名。读 SRC 文本、把首个
-        // （非注释的）顶层 `name:` 行值替换为安全 yaml 标量（含 ':' / '#' 等时
-        // 单引号包裹转义），其余字节原样；chmod 与下方一致。
+      if (name === 'preset.yml' && displayName !== null) {
+        // 显示名非空（配置了 main_agent_display_name 或工作区预设派生名）：读
+        // SRC 文本、把首个（非注释的）顶层 `name:` 行值替换为安全 yaml 标量
+        //（含 ':' / '#' 等时单引号包裹转义），其余字节原样；chmod 与下方一致。
         const presetText = readFileSync(src, 'utf8')
-        const next = presetText.replace(/^name:.*$/m, `name: ${yamlScalar(mainAgentName)}`)
+        const next = presetText.replace(/^name:.*$/m, `name: ${yamlScalar(displayName)}`)
         if (next === presetText) {
-          warn('preset.yml: 未找到可替换的顶层 name: 行（main_agent_name 未生效），已按原样写入')
+          warn(`preset.yml: 未找到可替换的顶层 name: 行（${displayNameSource ?? '工作区派生显示名'} 未生效），已按原样写入`)
         }
         writeFileSync(dst, next)
       } else {
@@ -319,10 +411,50 @@ export function generateAndInstall(state, assignments, { dryRun = false, saveCon
     writeFileSync(path.join(dstDir, 'agent.cordis.yml'), generatedText)
     chmodSync(path.join(dstDir, 'agent.cordis.yml'), statSync(path.join(SRC_DIR, 'agent.cordis.yml')).mode & 0o777)
     if (saveConfigOnWrite) {
-      saveConfig(configFile, { profile: effectiveProfile, ...assignments })
+      // 合并写盘（prev 已在函数开头读过，读失败早已中止，此处不做二次静默降
+      // 级）：全局应用只写顶层目标字段、workspaces 段原样保留；工作区应用只把
+      // 该条目并进 workspaces 段、顶层字段（含 profile）维持磁盘现状——两个对
+      // 象互不踩。顶层字段经 normalizeTargetFields 保留键存在性标记
+      // （has_main_agent_extra），老配置没有的键保存后仍缺省。
+      const next = wsPath === null
+        ? {
+            profile: effectiveProfile,
+            ...normalizeTargetFields(assignments),
+            workspaces: prev?.workspaces ?? {},
+          }
+        : {
+            profile: prev?.profile ?? effectiveProfile,
+            ...normalizeTargetFields(prev),
+            workspaces: { ...(prev?.workspaces ?? {}), [wsPath]: normalizeTargetFields(assignments) },
+          }
+      saveConfig(configFile, next)
     }
     wrote = true
   }
 
-  return { text: generatedText, roleResults, staleNote, wrote }
+  // ── 孤儿工作区 preset 回收（成功落盘后对账）──
+  // installedPresets 里 orchestrator-<slug> 形态、且不被配置 workspaces 任一条目
+  // （含本次并入的 wsPath）引用的目录按孤儿回收（rmSync + warn 行）。护栏：基础
+  // preset（orchestrator）与本次刚重建的 dstDir 永不清；prev 不可信（null，配置
+  // 缺失 / 未读到）时整体跳过 —— 没有可信引用清单可对账，宁可残留也不误删；
+  // 删除失败只 warn 保留，绝不让回收拖垮本次安装结果。
+  if (wrote && prev !== null && Array.isArray(state.installedPresets)) {
+    const wsEntries = Object.keys(prev.workspaces ?? {})
+    if (wsPath !== null && !wsEntries.includes(wsPath)) wsEntries.push(wsPath)
+    const referenced = new Set([...assignSlugs(wsEntries).values()].map(presetIdOf))
+    for (const name of state.installedPresets) {
+      if (name === 'orchestrator' || referenced.has(name)) continue
+      const dir = path.join(dshHome, '.agent-presets', name)
+      if (dir === dstDir) continue // 本次刚写出的目标目录绝不清
+      if (!existsSync(dir)) continue // 扫描后已被外部删除：无事可做
+      try {
+        rmSync(dir, { recursive: true, force: true })
+        warn(`孤儿工作区 preset 已回收: ${dir}（配置 workspaces 已无引用）`)
+      } catch (err) {
+        warn(`孤儿工作区 preset 回收失败（已保留）: ${dir}: ${err?.message ?? err}`)
+      }
+    }
+  }
+
+  return { text: generatedText, roleResults, staleNote, wrote, presetId }
 }

package/tools/lib/upgrade.mjs

@@ -0,0 +1,170 @@
+/**
+ * 面板一键升级执行器 —— spawn `dsh plugin --profile <profile> update dsh-paoding`
+ * 原地换版本（Web 面板「升级」按钮专用；CLI 不走这里）。
+ *
+ * 唯一官方安装通道是 DSH 插件通道：包由 pnpm 装进 profile
+ * （$DSH_HOME/profiles/<name>/node_modules/dsh-paoding），升级 = 让 dsh 的插件
+ * 转发器对该包做 pnpm update + bundle reconcile。本模块只负责「拿目标版本 →
+ * 探测自身 profile → 跑子进程」这一段编排；profile 名从本文件运行时真实路径
+ * 反推（registry 安装形态必然位于 <...>/profiles/<name>/node_modules/ 之下），
+ * 开发 link: 直连形态的真实路径在仓库里、匹配不到，如实报「无法就地升级」。
+ *
+ * 零依赖纯 Node（>=18）：目标版本复用 version.mjs 的 fetchLatestFromRegistry
+ * （npm registry 优先），子进程、时钟全部可注入便于单测。升级后不做磁盘后验
+ * ——本进程代码不随升级变化，无从对账；成功与否以 dsh 子进程退出码为准，
+ * 新版本在重启 DSH 后生效（preset 由新包的启动自愈钩子自动重生成）。
+ *
+ * 失败路径全部诚实暴露（不静默）：拿不到版本、开发形态、超时、退出码非 0，
+ * 都原样带回 error + 子进程输出尾部，调用方（面板路由）转成 500 醒目展示
+ * ——升级是用户主动点的高级操作，失败被吞掉比失败本身更糟。
+ */
+import os from 'node:os'
+import { spawn } from 'node:child_process'
+import { realpath } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import { currentVersion, compareVersions, fetchLatestFromRegistry } from './version.mjs'
+
+// 子进程输出上限：合并 stdout+stderr 后只保留最后 ~8KB（安装进度刷屏无排障
+// 价值，报错结论都在尾部）；累积过程中超过 1MB 就先截一版，防止异常刷爆内存。
+const OUTPUT_TAIL_BYTES = 8 * 1024
+const OUTPUT_HARD_CAP_BYTES = 1024 * 1024
+
+// 模块级互斥：同一进程同时只允许一个升级在跑（pnpm 双开操作同一 profile 必炸）。
+// 进行中再调立即返回失败，不排队——升级是分钟级操作，排队只会让面板转圈更久。
+let upgradeInFlight = false
+
+function tailOutput(text) {
+  const s = String(text ?? '')
+  return s.length > OUTPUT_TAIL_BYTES ? s.slice(-OUTPUT_TAIL_BYTES) : s
+}
+
+/**
+ * 缺省子进程执行器（可被 spawnImpl 注入替换，测试用）：spawn 任意命令，合并
+ * 收集 stdout+stderr，timeoutMs 到点 kill 并按超时收敛。永不 reject，统一收敛
+ * 为 { code, output, error? }（error 仅 spawn 本身失败（如 ENOENT）时存在）。
+ */
+function defaultSpawn(command, args, options, timeoutMs) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, options)
+    let output = ''
+    const onChunk = (chunk) => {
+      output += chunk.toString()
+      if (output.length > OUTPUT_HARD_CAP_BYTES) output = output.slice(-OUTPUT_TAIL_BYTES)
+    }
+    child.stdout?.on('data', onChunk)
+    child.stderr?.on('data', onChunk)
+    let timedOut = false
+    const timer = setTimeout(() => {
+      timedOut = true
+      child.kill('SIGTERM') // close 事件仍会触发，收尾统一在 close 里判定
+    }, timeoutMs)
+    child.on('error', (err) => {
+      clearTimeout(timer)
+      resolve({ code: null, output: tailOutput(output), error: String(err?.message ?? err) })
+    })
+    child.on('close', (code) => {
+      clearTimeout(timer)
+      resolve(timedOut
+        ? { code, output: tailOutput(output), error: `dsh plugin update 升级超时（${Math.round(timeoutMs / 1000)}s）` }
+        : { code, output: tailOutput(output) })
+    })
+  })
+}
+
+/**
+ * 从本模块运行时真实路径反推所属 profile 名。registry / git 依赖等插件通道
+ * 安装形态必然落在 <...>/profiles/<name>/node_modules/dsh-paoding/ 之下；开发
+ * link: 直连时真实路径是仓库目录，匹配不到返回 null（调用方据此拒绝就地升级
+ * 并指路手动命令）。realpath 必须走（macOS /tmp 等符号链接会遮住真实层级）；
+ * 分隔符两种都收，兼容 win32 路径。
+ * @returns {Promise<string|null>}
+ */
+export async function detectProfileName() {
+  try {
+    const real = await realpath(fileURLToPath(import.meta.url))
+    const m = /[/\\]profiles[/\\]([^/\\]+)[/\\]node_modules[/\\]/.exec(String(real))
+    return m ? m[1] : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 执行一键升级。
+ * @param {{profile?: string, fetchImpl?: Function, spawnImpl?: Function,
+ *           timeoutMs?: number, now?: Function|number}} opts
+ *   - profile 可选：显式指定目标 profile（跳过路径反推，测试 / 手动强制用）；
+ *     缺省经 detectProfileName() 从运行时真实路径反推。
+ *   - fetchImpl / spawnImpl / now 可注入（单测用）；缺省用 globalThis.fetch、
+ *     node:child_process 的 spawn、Date.now()。
+ *   - timeoutMs：dsh 子进程超时（含 pnpm 下载安装），默认 120s。
+ *   - spawnImpl 契约：(command, args, options, timeoutMs) → Promise resolving
+ *     { code, output, error? }（同 defaultSpawn 的收敛形状）。
+ * @returns {Promise<object>} 恒不抛错，收敛为：
+ *   - { ok: true, upToDate: true, current }                    本地已不落后 registry
+ *   - { ok: true, version, profile, output, elapsedMs }        升级成功（退出码 0）
+ *   - { ok: false, error, output?, elapsedMs? }                各类失败（原因见 error）
+ */
+export async function runUpgrade({ profile, fetchImpl, spawnImpl, timeoutMs = 120000, now } = {}) {
+  if (upgradeInFlight) return { ok: false, error: '升级正在进行中' }
+  upgradeInFlight = true
+  try {
+    return await doRunUpgrade({ profile, fetchImpl, spawnImpl, timeoutMs, now })
+  } catch (err) {
+    // 防御性兜底：上面的编排路径本应自捕一切，这里保证互斥锁绝不因意外泄漏
+    //（泄漏 = 本进程永远不能再升级）。
+    return { ok: false, error: '升级执行异常: ' + String(err?.message ?? err) }
+  } finally {
+    upgradeInFlight = false
+  }
+}
+
+async function doRunUpgrade({ profile, fetchImpl, spawnImpl, timeoutMs, now }) {
+  const startedAt = typeof now === 'function' ? now() : typeof now === 'number' ? now : Date.now()
+  const elapsedMs = () =>
+    Math.max(0, (typeof now === 'function' ? now() : typeof now === 'number' ? now : Date.now()) - startedAt)
+
+  // ① 版本预检：拿不到 registry latest 就不做半截升级（宁可不动现有安装）。
+  //    registry 超时给 10s：面板静默检测用 3s 够了，这里是用户显式点了「升级」、
+  //    本来就要等，多花几秒换一次成功率是划算的；仍超时就如实报失败。
+  const { version: current } = await currentVersion()
+  const reg = await fetchLatestFromRegistry({ fetchImpl, timeoutMs: 10000 })
+  if (!reg.ok) return { ok: false, error: `无法确定最新版本：${reg.error}` }
+  const target = reg.latest // 形如 v0.2.3
+  if (compareVersions(target, current) <= 0) return { ok: true, upToDate: true, current }
+  const targetVersion = target.replace(/^v/, '')
+
+  // ② profile 探测：开发 link: 直连形态无法就地升级，如实拒绝并指路手动命令。
+  const resolved = typeof profile === 'string' && profile !== '' ? profile : await detectProfileName()
+  if (!resolved) {
+    return {
+      ok: false,
+      error: '开发 link 形态无法就地升级，请手动执行 dsh plugin add dsh-paoding@latest 切换到 registry 版本',
+    }
+  }
+
+  // ③ spawn dsh 插件转发器：update = pnpm update + bundle reconcile。cwd 用
+  //    系统临时目录：子进程不该在仓库或 $DSH_HOME 里跑；DSH_HOME 经环境继承，
+  //    由子进程的 dsh 自行解析。win32 的 dsh 是 .cmd shim，必须借 shell 拉起
+  //    （Node 直接 spawn .cmd 会 EINVAL，见 CVE-2024-27980 加固），与
+  //    bin/dsh-paoding.mjs 同一方案；参数保持数组形式，转义交给 Node。
+  const useShell = process.platform === 'win32'
+  const command = useShell ? 'dsh.cmd' : 'dsh'
+  const run = typeof spawnImpl === 'function' ? spawnImpl : defaultSpawn
+  const proc = await run(command, ['plugin', '--profile', resolved, 'update', 'dsh-paoding'], {
+    cwd: os.tmpdir(),
+    env: process.env,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    shell: useShell,
+  }, timeoutMs)
+  const output = tailOutput(proc?.output)
+
+  // ④ 无磁盘后验（旧 npx 时代读 $DSH_HOME/dsh-paoding 对账的方案已随该目录
+  //    一并废弃）：本进程代码不随升级变化，无从对账；成功与否以退出码为准，
+  //    新版本重启 DSH 后生效（preset 由新版启动钩子自动重生成）。
+  if (proc?.error) return { ok: false, error: proc.error, output, elapsedMs: elapsedMs() }
+  if (proc?.code !== 0) {
+    return { ok: false, error: `dsh plugin update 退出码 ${proc?.code}`, output, elapsedMs: elapsedMs() }
+  }
+  return { ok: true, version: targetVersion, profile: resolved, output, elapsedMs: elapsedMs() }
+}