dsh-expert-group 0.1.1

package/install.ps1

@@ -0,0 +1,219 @@
+# 安装 dsh-expert-group 到 DSH 的全局插件位置（$DSH_HOME\profiles\packages\dsh-expert-group），
+# 与工程/源码目录完全解耦：删除本脚本所在的原始目录后插件仍可正常运行。
+# 支持从解压后的包目录直接运行：powershell -ExecutionPolicy Bypass -File .\install.ps1
+# 同时清理同名旧安装位置（profiles\web\packages\*）。
+# 复制面 = package.json 的 files 白名单：test/、test-support/、bench/、.scratch/ 等
+# 开发内容与构建产物 tgz 不会进入用户目录。
+# 维护用干跑模式（不做任何写入，仅供发布门禁/人工核对安装清单）：
+#   powershell -ExecutionPolicy Bypass -File .\install.ps1 -DryRun [-DryRunListPath <文件>]
+param(
+  # 干跑模式：只解析并输出安装白名单，不做任何写入、不构建 bundle、不调用 dsh CLI。
+  # 发布门禁测试用它核对「实际安装清单 == package.json 的 files 白名单」。
+  [switch]$DryRun,
+  # 干跑清单的落盘路径：显式以 UTF-8 写出，避免控制台代码页差异影响测试读取。
+  [string]$DryRunListPath
+)
+
+$ErrorActionPreference = "Stop"
+
+$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$sourcePath = $scriptDir
+$packageName = "dsh-expert-group"
+
+<#
+  解析安装白名单：以 package.json 的 files 字段（npm 发布面的唯一事实源）为准。
+  设计要点：
+  - 旧实现整目录复制（只排除 node_modules），会把 test/、test-support/、bench/、
+    .scratch/ 开发草稿与构建产物 tgz 一并带进用户 profiles，既膨胀体积又泄露开发内容，
+    因此这里改为逐项复制 files 声明的条目。
+  - files 缺省或为空时直接抛错而不是回退整目录：宁可安装中断，也不放大安装面。
+  - npm 语义下 package.json 自身始终随包发布（files 里通常不写它），显式补入，
+    否则 dsh plugin add 与 Node 的包解析都无法识别安装目录。
+  - 每项必须是仓库内相对路径：绝对路径、drive 前缀与 .. 越界项一律拒绝。
+  - 该函数被 DryRun 与真实复制共用，保证发布门禁验证的就是实际安装行为。
+#>
+function Get-InstallWhitelistEntries {
+  param([string]$Source)
+
+  $manifestPath = Join-Path $Source "package.json"
+  if (-not (Test-Path -LiteralPath $manifestPath)) {
+    throw "源目录缺少 package.json，无法解析安装白名单：$Source"
+  }
+  try {
+    # -Encoding UTF8：WinPS 5.1 的 Get-Content 默认按 ANSI 读取，UTF-8 manifest 的
+    # 中文 description 会被读成乱码导致 ConvertFrom-Json 失败；pwsh 7 默认 UTF-8 无此
+    # 问题，显式声明让两个宿主行为一致。
+    $sourceManifest = Get-Content -LiteralPath $manifestPath -Raw -Encoding UTF8 | ConvertFrom-Json -ErrorAction Stop
+  } catch {
+    throw "无法解析源 package.json $manifestPath：$($_.Exception.Message)"
+  }
+
+  $declared = @($sourceManifest.files | Where-Object { $_ -is [string] -and -not [string]::IsNullOrWhiteSpace($_) })
+  if ($declared.Count -eq 0) {
+    throw "源 package.json 的 files 白名单为空，拒绝整目录复制。请先在 package.json 中声明发布面。"
+  }
+
+  $entries = @($declared + @("package.json"))
+  $normalized = @()
+  foreach ($entry in $entries) {
+    # 统一分隔符为 /（npm 约定）并剥掉 ./ 前缀与尾部斜杠，得到仓库内相对路径。
+    $relative = ([string]$entry).Trim() -replace '\\', '/'
+    while ($relative.StartsWith("./")) { $relative = $relative.Substring(2) }
+    $relative = $relative.TrimEnd('/')
+    if ($relative -eq "" -or $relative.StartsWith("/") -or $relative -match "(^|/)\.\.(/|$)" -or $relative.Contains(":")) {
+      throw "package.json files 含越界或非相对路径项，拒绝安装：$entry"
+    }
+    $normalized += $relative
+  }
+  # 去重，避免同一路径被复制两次（例如 files 同时列了目录与其子项）。
+  return @($normalized | Select-Object -Unique)
+}
+
+if ($DryRun) {
+  # 干跑：只输出白名单相对路径（每行一项，/ 分隔），不做任何文件系统写入、
+  # 不构建 client bundle、不调用 dsh CLI，因此在测试与 CI 中可安全执行。
+  $dryRunEntries = @(Get-InstallWhitelistEntries -Source $sourcePath)
+  if (-not [string]::IsNullOrWhiteSpace($DryRunListPath)) {
+    # 显式 UTF-8 落盘（PS 5.1 会带 BOM，读取方需容忍 BOM）：非 ASCII 条目也不会因
+    # 控制台代码页差异被读成乱码，测试因此可在任意 Windows/locale 下稳定断言。
+    $dryRunEntries | Set-Content -LiteralPath $DryRunListPath -Encoding UTF8
+  }
+  foreach ($dryRunEntry in $dryRunEntries) { Write-Output $dryRunEntry }
+  exit 0
+}
+
+# 源码目录和正式 npm 包都携带组合脚本；安装前统一刷新唯一的 classic client bundle，
+# 保证复制到 profile 的生成物与三个源文件严格同步。
+$clientAssembler = Join-Path $sourcePath "scripts\assemble-client.mjs"
+if (Test-Path -LiteralPath $clientAssembler) {
+  Write-Host "生成 Expert Group 客户端 bundle ..." -ForegroundColor Cyan
+  & node $clientAssembler
+  if ($LASTEXITCODE -ne 0) { throw "客户端 bundle 生成失败，退出码 $LASTEXITCODE" }
+}
+
+# 全局安装位置必须位于 $DSH_HOME\profiles 目录树内：这样 Node 的父目录查找能找到
+# $DSH_HOME\profiles\node_modules 的平坦依赖回退（@deepseek-ai/schemastery 等 Host
+# 运行时依赖都在那里）。直接 link 工程源码目录会让 index.js 的嵌套 import 无法解析，
+# 且工程目录删除后插件即失效——全局安装正是为了避免这一点。
+$dshHome = if ($env:DSH_HOME) { $env:DSH_HOME } else { Join-Path $env:USERPROFILE ".dsh" }
+$profileDir = Join-Path $dshHome "profiles\web"
+$installTarget = Join-Path $dshHome "profiles\packages\$packageName"
+
+Write-Host "全局安装 $packageName ..." -ForegroundColor Cyan
+Write-Host "  源目录：$sourcePath"
+Write-Host "  全局安装位置：$installTarget"
+
+# 使用解析后的 profile 对象判断插件是否已经完成正式登记；不靠原始文本猜测。
+$profileManifest = Join-Path $profileDir "package.json"
+$manifest = $null
+if (Test-Path -LiteralPath $profileManifest) {
+  try {
+    # 同上：profile manifest 由 dsh/插件写入 UTF-8，WinPS 5.1 需显式编码读取。
+    $manifest = Get-Content -LiteralPath $profileManifest -Raw -Encoding UTF8 | ConvertFrom-Json -ErrorAction Stop
+  } catch {
+    throw "无法解析 DSH profile manifest $profileManifest：$($_.Exception.Message)"
+  }
+}
+
+$dependencyProperty = $null
+if ($null -ne $manifest -and $null -ne $manifest.dependencies) {
+  $dependencyProperty = $manifest.dependencies.PSObject.Properties[$packageName]
+}
+$dependencyValue = if ($null -ne $dependencyProperty) { [string]$dependencyProperty.Value } else { $null }
+$bundleValues = @()
+if ($null -ne $manifest -and $null -ne $manifest.dsh -and $null -ne $manifest.dsh.profile -and $null -ne $manifest.dsh.profile.bundles) {
+  $bundleValues = @($manifest.dsh.profile.bundles)
+}
+$hasDependency = $null -ne $dependencyProperty -and -not [string]::IsNullOrWhiteSpace($dependencyValue)
+$hasBundle = @($bundleValues | Where-Object { $_ -is [string] -and $_ -eq $packageName }).Count -gt 0
+$profileRegistered = $hasDependency -and $hasBundle
+
+# CLI 可用时仍由 DSH 正式管理注册；CLI 不在 PATH 时只能升级已登记插件。
+$dsh = Get-Command dsh -ErrorAction SilentlyContinue
+$dshCommand = $null
+if ($null -ne $dsh) {
+  $dshCommand = if (-not [string]::IsNullOrWhiteSpace([string]$dsh.Source)) {
+    [string]$dsh.Source
+  } else {
+    [string]$dsh.Name
+  }
+}
+$hasDshCommand = -not [string]::IsNullOrWhiteSpace($dshCommand)
+if (-not $hasDshCommand -and -not $profileRegistered) {
+  throw "未找到 dsh 命令，且 profile 尚未有效登记 $packageName。请先安装 @deepseek-ai/dsh 并确保其 bin 目录在 PATH 中，再通过 DSH CLI 执行首次注册；脚本不会手工修改 profile。"
+}
+if ($hasDshCommand) {
+  Write-Host "  已检测到 DSH CLI，将执行正式 remove/add 注册流程。" -ForegroundColor DarkGray
+} else {
+  Write-Host "  未找到 DSH CLI，但 profile 已有效登记 $packageName。将仅同步源码。" -ForegroundColor Yellow
+}
+
+# 卸载本包已有依赖，避免同一行重复注册导致工具重名。
+if ($hasDshCommand) {
+  foreach ($pkg in @($packageName)) {
+    $installed = $false
+    if ($null -ne $manifest -and $null -ne $manifest.dependencies) {
+      $installed = $null -ne $manifest.dependencies.PSObject.Properties[$pkg]
+    }
+    if ($installed) {
+      Write-Host "  卸载已有依赖 $pkg ..." -ForegroundColor Yellow
+      & $dshCommand plugin --profile web remove $pkg
+      if ($LASTEXITCODE -ne 0) { throw "$dshCommand plugin remove $pkg 失败，退出码 $LASTEXITCODE" }
+    }
+  }
+}
+
+# 清理目标安装副本（profiles\web\packages\*）。
+foreach ($legacy in @("$profileDir\packages\$packageName")) {
+  if (Test-Path $legacy) {
+    Remove-Item $legacy -Recurse -Force
+    Write-Host "  已删除旧安装副本 $legacy" -ForegroundColor DarkGray
+  }
+}
+
+# 同步全局安装副本：先清理旧副本，再严格按 package.json 的 files 白名单逐项复制。
+# 白名单外的一切（test/、test-support/、bench/、.scratch/、tgz、docs/、node_modules）
+# 都不会进入用户目录；目录项递归复制，文件项直接复制。
+# 若脚本本身就运行在安装目标目录内（重新安装场景），跳过自复制。
+if ($sourcePath -ne $installTarget) {
+  if (Test-Path $installTarget) { Remove-Item $installTarget -Recurse -Force }
+  New-Item -ItemType Directory -Path $installTarget -Force | Out-Null
+
+  $whitelist = @(Get-InstallWhitelistEntries -Source $sourcePath)
+  foreach ($entry in $whitelist) {
+    # 白名单在解析阶段已统一为 / 分隔并校验过相对性；这里再转成本机分隔符拼路径。
+    $relativePath = $entry -replace '/', '\'
+    $sourceItem = Join-Path $sourcePath $relativePath
+    if (-not (Test-Path -LiteralPath $sourceItem)) {
+      throw "安装白名单项在源目录中不存在：$relativePath（请同步修正 package.json 的 files）"
+    }
+
+    # 关键：先确保父目录存在，再把条目复制到父目录里，让 Copy-Item 自行拼接叶子名。
+    # 若直接以该条目自身的完整目标路径作为 -Destination 且该路径已存在，Copy-Item 会
+    # 在目标下多套一层同名目录，导致安装目录结构错位。
+    $targetParent = Split-Path -Parent (Join-Path $installTarget $relativePath)
+    if (-not (Test-Path -LiteralPath $targetParent)) {
+      New-Item -ItemType Directory -Path $targetParent -Force | Out-Null
+    }
+
+    # 白名单可能出现重叠（既列目录又列其子项）或重复项：先删除同名目标，避免
+    # Copy-Item 把源目录合并进已有同名目录而产生「新旧混合」的安装副本。
+    $copied = Join-Path $targetParent (Split-Path -Leaf $relativePath)
+    if (Test-Path -LiteralPath $copied) { Remove-Item -LiteralPath $copied -Recurse -Force }
+    Copy-Item -LiteralPath $sourceItem -Destination $targetParent -Recurse -Force
+  }
+  Write-Host ("  已按 files 白名单复制 {0} 项到安装目录（node_modules 与未声明内容不复制）" -f $whitelist.Count) -ForegroundColor DarkGray
+} else {
+  Write-Host "  脚本位于安装目标目录内，跳过复制" -ForegroundColor DarkGray
+}
+
+# CLI 可用时通过 DSH 的正式流程加入 web profile；无 CLI 时仅保留现有登记并同步源码。
+if ($hasDshCommand) {
+  & $dshCommand plugin --profile web add $installTarget
+  if ($LASTEXITCODE -ne 0) {
+    throw "$dshCommand plugin add 失败，退出码 $LASTEXITCODE"
+  }
+  Write-Host "完成 CLI 注册与源码同步。请重启 DSH Web（dsh web）后刷新页面。验证：$dshCommand --profile web --dump-config" -ForegroundColor Green
+} else {
+  Write-Host "已跳过 CLI 注册，保留现有 profile 登记。源码已同步。请重启 DSH Web（dsh web）后刷新页面。" -ForegroundColor Green
+}

package/orchestrator.js

@@ -0,0 +1,239 @@
+/**
+ * DSH 根会话的主代理（orchestrator）提示词。
+ *
+ * 该模块只生成插件拥有的 root system section。root workflow 必须保留在 system
+ * 层级；动态 routing 和 child persona 只携带各自 scope 所需的短契约，避免把同一
+ * 段等待/委派说明复制到每个 tool schema 后触发宿主展示或上下文上限。
+ *
+ * @module dsh-expert-group/orchestrator
+ */
+
+import { getRole, listRoles } from "./role-registry.js";
+
+/**
+ * DSH 中由当前插件注册到 ctx.tools 的唯一命名空间专家工具。
+ * 角色集合与顺序来自统一角色注册表：这里不再维护第二份清单。
+ */
+export const ORCHESTRATOR_ROLES = Object.freeze(listRoles().map((entry) => entry.id));
+
+/**
+ * 每个角色的 prompt lane 文案（英文）。首行 "@role" 标记与职责摘要由注册表派生，
+ * 因此这里只保留角色特有的派发/不派发指引；缺失任一注册角色的 lane 会在模块加载时
+ * 显式失败，避免新增角色静默漏进 root prompt。
+ */
+const ROLE_LANES = {
+  explorer: [
+    "- Lane: fast, read-only codebase reconnaissance",
+    "- Capabilities: locate files, symbols, and patterns, then return compressed factual context",
+    "- Delegate when: the scope is broad or uncertain, or independent searches can run in parallel",
+    "- Do not delegate when: you already know the exact path and need its contents",
+  ],
+  librarian: [
+    "- Lane: read-only external documentation and library research",
+    "- Capabilities: verify current APIs, official examples, version-specific behavior, and upstream fixes",
+    "- Delegate when: a library API or current external fact materially affects the implementation",
+    "- Do not delegate when: the answer is stable, local, or already established in the conversation",
+  ],
+  oracle: [
+    "- Lane: read-only architecture, risk, debugging strategy, and code review",
+    "- Capabilities: assess tradeoffs, persistent failures, security, scalability, and simplification opportunities",
+    "- Delegate when: the decision is high-risk or the root cause remains unclear after ordinary diagnosis",
+    "- Do not delegate when: the change is routine and the correct approach is already clear",
+  ],
+  designer: [
+    "- Lane: UI/UX and visual implementation",
+    "- Capabilities: own layout, hierarchy, spacing, responsive behavior, accessibility, and interaction quality",
+    "- Delegate when: users see the result and visual or interaction polish matters",
+    "- Do not delegate when: the work is headless logic with no visual decision",
+  ],
+  fixer: [
+    "- Lane: bounded implementation and test completion",
+    "- Capabilities: execute a clear scoped change across files and report validation results",
+    "- Delegate when: implementation is non-trivial, multi-file, mechanical, or benefits from parallel ownership",
+    "- Do not delegate when: the action is one small, isolated, low-risk edit or requires unresolved design judgment",
+  ],
+  observer: [
+    "- Lane: read-only image, screenshot, chart, diagram, and PDF analysis",
+    "- Capabilities: inspect visual files with read_image and return structured observations",
+    "- Delegate when: understanding visual content is required; always include the full workspace file path",
+    "- Do not delegate when: plain text inspection is sufficient",
+  ],
+};
+
+const FANOUT_DESCRIPTION = [
+  "fanout",
+  "- Generic same-role fan-out: submit one role with an ordered shards array.",
+  "- Each shard is an independent child attempt with bounded per-role concurrency, wait-all aggregation, cancellation, and manual retry.",
+  "- Use explicit unique shardId values and affectedPaths for write-role conflict checks; the call returns a parentTaskId immediately.",
+];
+
+for (const entry of listRoles()) {
+  if (!Array.isArray(ROLE_LANES[entry.id])) {
+    throw new Error("orchestrator 缺少注册角色的 lane 描述: " + entry.id);
+  }
+}
+
+/** 角色的插件工具名来自注册表；未知角色显式失败而不是回落到原始字符串。 */
+function toolNameOf(role) {
+  const entry = getRole(role);
+  if (entry === undefined) throw new Error("orchestrator 收到未注册的角色: " + String(role));
+  return entry.toolName;
+}
+
+/** 完整 root system section 的结构边界；诊断只读这些 marker，不修改实际文本。 */
+export const ORCHESTRATOR_SECTION_MARKERS = Object.freeze([
+  "<Identity>",
+  "</Identity>",
+  "<Role>",
+  "</Role>",
+  "<Scope>",
+  "</Scope>",
+  "<Agents>",
+  "</Agents>",
+  "<Notifications>",
+  "</Notifications>",
+  "<Workflow>",
+  "</Workflow>",
+  "<Communication>",
+  "</Communication>",
+  "<DelegationContract>",
+  "</DelegationContract>",
+]);
+
+/**
+ * 判断一次 DSH 提示词组装是否属于根 Agent。只有带 agent 且没有 parentSession
+ * 的在线会话才是根上下文；无 agent 的诊断组装保持不注入主代理提示词。
+ * @param {object} [assemblyContext] - DSH AssembleContext。
+ * @returns {boolean} 仅在线根 Agent 返回 true。
+ */
+export function isRootAgentContext(assemblyContext) {
+  const agent = assemblyContext?.agent;
+  return agent !== void 0 && agent.session?.header?.parentSession === void 0;
+}
+
+/**
+ * 对已生成的 root system 文本提供轻量完整性诊断。插件不能知道宿主或模型的外部
+ * 上限，因此这里不截断、不重写文本，只报告 UTF-8 长度、section marker 完整性和
+ * 常见截断痕迹，供测试与宿主诊断使用。
+ * @param {string} [prompt] - buildOrchestratorPrompt() 的完整结果。
+ * @returns {{utf8Bytes:number, markersPresent:boolean, markerCounts:object, hasTruncationMarker:boolean, complete:boolean}}
+ */
+export function inspectOrchestratorPrompt(prompt = "") {
+  const text = typeof prompt === "string" ? prompt : "";
+  const encoder = typeof TextEncoder === "function" ? new TextEncoder() : void 0;
+  const utf8Bytes = encoder === void 0 ? text.length : encoder.encode(text).length;
+  const markerCounts = {};
+  for (const marker of ORCHESTRATOR_SECTION_MARKERS) {
+    markerCounts[marker] = text.split(marker).length - 1;
+  }
+  const markersPresent = ORCHESTRATOR_SECTION_MARKERS.every((marker) => markerCounts[marker] === 1);
+  // 这些标记不属于插件契约；若宿主将它们混入结果，诊断应明确提示而非猜测修复。
+  const hasTruncationMarker = /(?:\.\.\.|TRUNCAT(?:ED|ION)|截断)/i.test(text);
+  return {
+    utf8Bytes,
+    markersPresent,
+    markerCounts,
+    hasTruncationMarker,
+    complete: text.length > 0 && markersPresent && !hasTruncationMarker,
+  };
+}
+
+/**
+ * 构建根 Agent 的完整编排提示词，作为 system-prompt section 使用。
+ * routing section 不再复制这里的 workflow；child 也不会收到这里的内容。
+ * @param {object} [options]
+ * @param {string[]} [options.roles] - 当前实际可用的专家角色。
+ * @param {boolean} [options.providerReady] - spawn provider 是否就绪。
+ * @param {boolean} [options.observerPreferred] - 是否将带图请求优先交给 Observer。
+ * @param {string} [options.rootSessionId] - 当前根 Agent 的 session id，用于绑定第一人称身份。
+ * @returns {string} 可直接注册为 system-prompt section 的完整文本。
+ */
+export function buildOrchestratorPrompt({ roles = ORCHESTRATOR_ROLES, providerReady = true, observerPreferred = false, rootSessionId } = {}) {
+  const enabledRoles = ORCHESTRATOR_ROLES.filter((role) => roles.includes(role));
+  const available = enabledRoles.map((role) => toolNameOf(role));
+  const fanoutAvailable = providerReady && enabledRoles.length > 0;
+  if (fanoutAvailable) available.push("fanout");
+  // 每个角色段落：注册表派生的 "@toolName" 标记与"显示名 — 职责摘要"，
+  // 再加上该角色特有的 lane 指引。注册表是角色身份与职责的唯一来源。
+  const roleText = enabledRoles.map((role) => {
+    const entry = getRole(role);
+    return ["@" + entry.toolName, "- Role: " + entry.label + " — " + entry.description, ...ROLE_LANES[role]].join("\n");
+  }).join("\n\n")
+    + (fanoutAvailable ? "\n\n" + FANOUT_DESCRIPTION.join("\n") : "");
+  const unavailable = providerReady
+    ? ""
+    : "\n\nThe expert subagent team is currently unavailable because the spawn provider is not ready. Do not call expert tools until the provider becomes available.\n";
+  const availableText = providerReady && available.length > 0
+    ? "\n\nAvailable expert tools: " + available.join(", ") + "."
+      + (fanoutAvailable ? " The fanout tool accepts one role and an ordered shards array, returns immediately with a parentTaskId, and exposes wait-all results through the task list/RPC." : "")
+      + "\n"
+    : "";
+  const imageRoutingText = enabledRoles.includes("observer")
+    ? observerPreferred === true
+      ? "\n\nImage routing: Observer优先 is enabled. For image input, use Observer only when its model explicitly declares image support; any role-named tool may receive the image directly when its selected model explicitly declares image support. Unknown capability is an error. Only pass the image parameter when forwarding a real image attachment from the current conversation; omit it entirely otherwise and never fabricate placeholder attachment metadata. Use a real .png durable copy for extensionless images; never change a suffix in place.\n"
+      : "\n\nImage routing: Observer优先 is disabled. Keep the main model first; use Observer only after the main model explicitly declares image input is unsupported. Any role-named tool may receive an image directly when its selected model explicitly declares image support. Unknown capability remains main-first. Only pass the image parameter when forwarding a real image attachment from the current conversation; omit it entirely otherwise and never fabricate placeholder attachment metadata. Use a real .png durable copy for extensionless images; never change a suffix in place.\n"
+    : "";
+  // session id 来自 Host 组装上下文。去掉换行，避免动态值破坏 system 分段。
+  const identitySessionId = rootSessionId === void 0
+    ? "(unavailable)"
+    : String(rootSessionId).replace(/[\r\n]+/g, " ");
+
+  const identity = [
+    "<Identity>",
+    "YOU are the current root/parent orchestrator for this conversation. There is no separate outer main agent above you. When the user says ‘主代理’, ‘parent’, or ‘root agent’, they mean YOU, the model executing this turn.",
+    "Your current root session id is " + identitySessionId + ". Treat that id as your own identity, never as a remote controller to prompt.",
+    "Never call session.prompt, HTTP/RPC, browser automation, or CLI commands against your own root session. That is self-messaging, not parent-to-child delegation.",
+    "To control a plugin-managed child for an explicit user-requested new pause, stop, redirect, or follow-up task, invoke the same role-named plugin tool again with a different prompt. queue=true is delivered through the public subagents.sendMessage API; queue=false may first call public subagents.interrupt, then also uses public subagents.sendMessage. RC1 sendMessage may steer a running child at its nearest step boundary or start/resume an idle child; do not await whenIdle or direct-steer a child, and do not claim an unpublished FIFO queue. A child in ready state has no current turn: do not send it a fake completion/stop prompt. dsh_expert_group_finalize is a root-only semantic action; it never ends a child and finalize ends only the current root turn. If terminal feedback arrived but the DEG scope is stale, use dsh_expert_group_release_scope with the exact childId; that tool releases only the DEG scope and does not stop the child. Never use tools.send_message, send_message, interrupt_agent, a generic subagent tool, Harness outer subagent_<role>, or raw Agent messages. Never use this control path merely to wait for a background result; the normal later-turn feedback mechanism delivers it. provider cancellation or teardown can affect delivery.",
+    "</Identity>",
+  ].join("\n");
+
+  const role = [
+    "<Role>",
+    "You are the primary workflow manager for coding work: understand the request, choose the lightest reliable plan, delegate bounded lanes, integrate findings, and verify the result. For non-trivial or uncertain work, default to delegating a bounded lane to an enabled expert when that expert can materially contribute. Handle work directly only when it is isolated, clear, low-risk, and delegation overhead materially exceeds the benefit, or when no enabled expert fits; verify proportionately with project tests and diagnostics.",
+    "</Role>",
+  ].join("\n");
+
+  const scope = [
+    "<Scope>",
+    "This complete workflow is root-only. Expert children receive only their own persona and tool limits: each is a leaf worker and must not delegate, and reports to its parent. Never treat a child or routing note as another root orchestrator.",
+    "</Scope>",
+  ].join("\n");
+
+  const notifications = [
+    "<Notifications>",
+    "Notifications are fully automatic and have no tool: the plugin Host keeps this root run's authoritative termination snapshot (completed, blocked, error, aborted, interrupted, max-tokens) together with the running state of every recursive descendant expert, and the browser client surfaces pending approval, plan-review, or question operations on their own. Do not call, invent, or emulate a notify/announce tool, and never send a task-level notification just because an individual child finished. Integrate the results and reach your normal user-facing conclusion.",
+    "</Notifications>",
+  ].join("\n");
+
+  const workflow = [
+    "<Workflow>",
+    "1. Understand explicit requirements and acceptance criteria; choose the lightest path balancing quality, speed, cost, and reliability.",
+    "2. For non-trivial work, identify independent lanes, dependencies, validation ownership, and allowed affectedPaths.",
+    "3. Dispatch the intended expert calls first. Summarize the accepted tasks and later integration/review/verification, then inspect every result, including started:false advisory or failure outcomes. Preserve each admissionEpoch and complete admissionToken set.",
+    "4. Dispatch only independent, non-overlapping lanes; admission is non-blocking. Set continue_parent_turn:true only for explicitly confirmed immediate safe non-overlapping work. When no safe work remains, call root-only dsh_expert_group_finalize last with summaryCompleted:true, outcomesChecked:true, safeParallelWork:false, current admissionEpoch, and every token. Finalize pauses the root goal before concluding only the current root turn; it never waits for, stops, resumes, or concludes a child. For ask_user_question or exit_plan_mode, use that same user-wait handoff and resume the saved exact goal ref after the root user/message when all waits release; grill-me/to-spec user replies use it too. Do not use update_goal pause because it injects context and continues the root. A pure continue_parent_turn batch has no handoff to finalize and may remain open only for the explicitly safe work it authorized. Do not continue with another tool call, wait, poll, list_agents, status query, planning step, or child intervention after finalize.",
+    "5. A dependent task waits for prerequisite feedback: dispatch the prerequisite first, return DSH ready, let DSH deliver its feedback in a later turn, then dispatch the dependent task with a compressed result. Never poll, use plugin-internal waiting or an ordinary waiting timeout, or intervene in a child; use DSH's existing feedback mechanism.",
+    "6. Keep at most one active continuable child per parent session per role. An identical task is reused; an explicit user-requested new pause/stop/redirect/follow-up task uses the same role tool with a different prompt. run_in_background is a compatibility input only: omitted, true, and false all use non-blocking admission. queue=true is delivered by public subagents.sendMessage and is not a waiting mechanism; queue=false may request cancellation through public subagents.interrupt before that same sendMessage admission. Do not call Agent.whenIdle/Agent.steer directly or claim an unpublished FIFO queue. A ready child is already between turns; never use finalize or a role tool merely to end it. Do not call the same role-named tool again merely to wait, confirm, or restate the same result. Non-success non-cancellation turns use bounded manager sendMessage before definitive failure; only a destroyed, not-resumable, or route-changed child is rebuilt.",
+    "7. After independent work, process only feedback already delivered in this turn; otherwise finalize the checked batch. Do not call a role tool again merely to wait, confirm, or restate the same result. After normal completion, abnormal completion, or expert report, reassess work and return DSH ready again when nothing is executable.",
+    "8. Route only to enabled roles. Read-only findings return for root integration; the root owns synthesis, review, tests, and user-facing completion. Verify proportionately with project test/build/diagnostic commands.",
+    "9. Every new delegation declares affectedPaths. Missing scope is not conflict-free; affected paths intersect an active expert task when their normalized ranges overlap. The root must also avoid direct work whose affected paths intersect an active expert task; this restriction applies even when the root is not creating a new delegation. An overlap advisory means do not start, steer, or follow up unless allowOverlap:true is explicitly safe. Independent scopes may run in parallel; prerequisite and dependent work may not share a round or run in parallel. Keep todo_write current for multi-step work; preserve existing order/statuses and append new work unless the user explicitly replaces or reprioritizes it.",
+    "</Workflow>",
+  ].join("\n");
+
+  const communication = [
+    "<Communication>",
+    "Ask a concise targeted question when a critical requirement, permission, or choice blocks execution. Do not guess critical paths or architecture; state minor assumptions briefly. Keep updates brief and final output focused on result and verification.",
+    "</Communication>",
+  ].join("\n");
+
+  const delegationContract = [
+    "<DelegationContract>",
+    "每次向专家子代理派发任务时，prompt 必须统一使用中文，第一句必须是“你是 XXX 子代理。”，且必须作为第一行；任务正文必须自包含，写明相关 workspace 路径、允许范围和预期验证。固定 child 纪律由 persona、toolFilter 和 runtime guard 注入和执行，主代理不要在任务正文重复写入 send_message、叶子 worker 或最终 assistant 输出规则。",
+    "每条派发 prompt 必须自包含，写明相关 workspace 路径、允许范围和预期验证；只能使用本插件启用的 role-named 工具，禁止使用 Harness outer subagent_<role>、PTC run_code 或 generic subagent 替代；不要把 root workflow 或固定 child 纪律重复写入任务正文。",
+    "</DelegationContract>",
+  ].join("\n");
+
+  return identity + "\n\n" + role + "\n\n" + scope + "\n\n<Agents>\n"
+    + (roleText || "No expert agents are currently enabled.") + "\n</Agents>"
+    + availableText + imageRoutingText + unavailable + "\n" + notifications + "\n\n"
+    + workflow + "\n\n" + communication + "\n\n" + delegationContract;
+}

package/package.json

@@ -0,0 +1,142 @@
+{
+  "name": "dsh-expert-group",
+  "version": "0.1.1",
+  "description": "DSH 专家子代理、Expert Group 任务侧边栏与设置页（双面 bundle）",
+  "type": "module",
+  "main": "./index.js",
+  "bin": {
+    "prompt-inspector": "bin/prompt-inspector.mjs"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./client": "./client-bundle.js",
+    "./client-freshness": "./client-freshness.js",
+    "./shared": "./shared.js",
+    "./role-registry": "./role-registry.js",
+    "./resource-budget": "./resource-budget.js",
+    "./orchestrator": "./orchestrator.js",
+    "./image-routing": "./image-routing.js",
+    "./storage": "./storage.js",
+    "./prompt-inspector": "./prompt-inspector.js",
+    "./prompt-sidecar": "./prompt-sidecar.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "client-bundle.js",
+    "client.js",
+    "client-notifications.js",
+    "client-expert-group-model.js",
+    "client-expert-group-sidebar.js",
+    "client-model-config.js",
+    "client-freshness.js",
+    "shared.js",
+    "role-registry.js",
+    "resource-budget.js",
+    "host/composition.js",
+    "host/expert-group-snapshot.js",
+    "host/expert-group-runtime.js",
+    "host/fanout-runtime.js",
+    "host/handoff.js",
+    "host/lineage.js",
+    "host/notifications.js",
+    "host/rpc-transport.js",
+    "host/settings-source.js",
+    "host/recovery.js",
+    "host/settings-runtime.js",
+    "host/storage-binding.js",
+    "host/persistence-health.js",
+    "host/system-toast.js",
+    "orchestrator.js",
+    "prompt-contracts.js",
+    "image-routing.js",
+    "storage.js",
+    "prompt-inspector.js",
+    "prompt-sidecar.js",
+    "fanout.js",
+    "fanout-host.js",
+    "rpc-host.js",
+    "assets/notification-whoosh.wav",
+    "scripts/assemble-client.mjs",
+    "scripts/build.mjs",
+    "bin/prompt-inspector.mjs",
+    "cordis.patch.yml",
+    "README.md",
+    "THIRD_PARTY_NOTICES.md",
+    "LICENSE",
+    "install.ps1",
+    "uninstall.ps1"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-modules",
+        "@deepseek-ai/dsh-client-connection",
+        "@deepseek-ai/dsh-client-ui-primitives",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-ui-workspace",
+        "@deepseek-ai/dsh-client-ui-sidebar-right",
+        "dsh-better-sidebar"
+      ]
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-agent": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-attachment": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-modules": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-connection": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-workspace": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-sidebar-right": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-scope": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-session": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-session-projection": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-settings": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-storage": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-storage-domain": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-subagent": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-user-approval": "^0.2.0-rc.1",
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "dsh-better-sidebar": "^0.19.1",
+    "react": "^18.2.0",
+    "zod": "^4.4.3"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-client-ui-sidebar-right": {
+      "optional": true
+    },
+    "dsh-better-sidebar": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "prepare": "npm run build",
+    "test": "node --test \"test/*.test.mjs\"",
+    "release-gate": "node --test test/release-gate.test.mjs test/package-portability.test.mjs test/client-shared-boundary.test.mjs test/model-config.test.mjs",
+    "release": "node scripts/sync-dsh-version.mjs && pnpm run build && pnpm run test && pnpm run release-gate"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dimensionli95-ship-it/dsh-expert-group.git"
+  },
+  "optionalDependencies": {
+    "sharp": "^0.35.4"
+  }
+}