dsh-paoding 0.3.6 → 0.3.8

package/tools/lib/compose.mjs

@@ -6,7 +6,11 @@
  * （renderCustomRoleBlocks / firstLine / insertCustomRoles）、roles_remove 委派行
  * span 删除（delegationRowSpan / composeMainPersonaEdit）、角色专用模型注入
  * （injectRoleAgentOptions，roles.<toolName>.model / .provider → 内置角色委派块
- * 的 agentOptions 子块）、角色可续模式改写/兜底注入（injectRoleBackgroundMode，
+ * 的 agentOptions 子块）、角色启动方式改写（injectRoleStartMode，
+ * roles.<toolName>.start_mode = 'fork' → 内置角色委派块的块级 provider 行原位
+ * 改写为 fork；'fresh' 不动源行 —— 源模板四块各预置 `provider: spawn`，全默认
+ * 产物与源零 diff；块内无该行时不兜底注入，与 backgroundMode 的兜底口径不同，
+ * 见函数注释）、角色可续模式改写/兜底注入（injectRoleBackgroundMode，
  * roles.<toolName>.background_mode = 'continuable' → 内置角色委派块的
  * backgroundMode 行：源模板已预置该行时原位改写其值，块内无该行时在 toolName
  * 行行尾兜底注入；'one-shot' 不动源行 —— 源模板四块各预置
@@ -16,6 +20,9 @@
  * allow 过滤走白名单语义（usableWith / presetUniverse ∪ inventory，见
  * filterUsableTools 上方说明）：手写进配置、既不在 preset 自带工具面也不在
  * 检测库存的名字一律从 allow 丢弃，不再「非 host 依赖名直通」。
+ * workflow worker 行按宿主版本生成期适配（adaptWorkflowWorkerRow：≥0.1.6 把
+ * 0.1.5-only 的 workflow-worker-thread 条目换成 workflow-ptc；探测不到版本
+ * 保守保留源行，产物零 diff 性质随之保留）。
  * 自定义角色另有三道防护/自动化：toolName 保留名校验（assertCustomToolName，
  * 内置角色 / restrictBase / subagent* / mcp__ 前缀 / YAML 字面量一律 throw）；
  * tools 为空时拒绝安装零工具角色（renderCustomRoleBlocks 直接 throw，防
@@ -29,6 +36,43 @@
 import { DEFAULT_MAIN_AGENT_PERSONA_EXTRA, ROLES, warn } from './util.mjs'
 import { normalizeModelRef, yamlScalar } from './config.mjs'
 import { isHostDependent } from './host.mjs'
+import { isPtcWorkerHost } from './preset-system.mjs'
+
+// ── workflow worker 行的宿主版本适配 ─────────────────────────────────────────
+
+// 源模板里 workflow worker 行的原样块（delegation 组 config 内，4 空格条目缩进）。
+// 宿主 ≥0.1.6 时整块换成 workflow-ptc（0.1.6-alpha.1 起
+// @deepseek-ai/dsh-workflow-worker-thread 包已删除，残留行让 preset 的
+// delegation 组报 never started，0.2.0 Plugin Manager 显示「加载失败」；
+// workflow-ptc 是 0.1.6–0.2.0 各版 standard 组合的统一形态，ptcRuntime 服务由
+// base bundle 提供，preset 内不需要再列 ptc-runtime 行）。行不在任何 span 定位
+// 区间内，调用点在全部 edits 应用之后，与偏移量零交互。
+const WORKER_THREAD_BLOCK = [
+  '    - id: workflow-worker-thread',
+  "      name: '@deepseek-ai/dsh-workflow-worker-thread'",
+  '      config:',
+  '        provider: spawn',
+].join('\n')
+const WORKER_PTC_BLOCK = [
+  '    - id: workflow-ptc',
+  "      name: '@deepseek-ai/dsh-workflow-ptc'",
+  '      config:',
+  '        provider: spawn',
+].join('\n')
+
+/**
+ * Host-version adaptation of the delegation group's workflow worker row:
+ * ≥0.1.6 swaps the 0.1.5-only workflow-worker-thread entry for workflow-ptc
+ * (see isPtcWorkerHost). A missing source block means template drift — a hard
+ * error, mirroring how missing role blocks abort generation.
+ */
+export function adaptWorkflowWorkerRow(text, hostVersionTriple) {
+  if (!isPtcWorkerHost(hostVersionTriple)) return text
+  if (!text.includes(WORKER_THREAD_BLOCK)) {
+    throw new Error('workflow-worker-thread block not found in source agent.cordis.yml')
+  }
+  return text.replace(WORKER_THREAD_BLOCK, WORKER_PTC_BLOCK)
+}
 
 // ── restrict.mjs main-agent allow base ──────────────────────────────────────
 
@@ -76,6 +120,35 @@ function normalizeRoleModel(toolName, rawModel, rawProvider) {
   return { model, provider }
 }
 
+/** 角色启动方式兜底（自定义块渲染与内置角色注入两处共用）：assignments 可能绕过
+ * config 规范化（UI 手工构造 / 测试直传），compose 层按「恰好 'fork' 才认」口径
+ * 兜底 —— 与 background_mode 的「非 'continuable' 即 one-shot」同款；其余一律
+ * 'fresh'（零 diff 不动源行）。 */
+function roleStartModeOf(role) {
+  return role?.start_mode === 'fork' ? 'fork' : 'fresh'
+}
+
+/**
+ * 角色专用模型解析（fork 互斥判定版，normalizeRoleModel 的调用方统一走这里）：
+ * 先归一 model / provider（含 provider-alone warn），再判 fork 互斥 ——
+ * start_mode: 'fork' 的子 agent 以主 agent（父级）的提供方与模型启动（DSH fork
+ * 后端为 KV cache 复用的硬约束），专用模型不生效：warn 说明后按缺省处理（不注入
+ * agentOptions），与 provider-alone 的「warn 后忽略」同款。fork + provider-alone
+ * 不叠加 fork warn（provider-alone 已在 normalizeRoleModel 里 warn 过）。'fresh'
+ * 行为与 normalizeRoleModel 完全一致。
+ */
+function resolveRoleModel(toolName, rawModel, rawProvider, startMode) {
+  const { model, provider } = normalizeRoleModel(toolName, rawModel, rawProvider)
+  if (startMode === 'fork' && model !== null) {
+    warn(
+      `roles.${toolName}: start_mode: 'fork' 的子 agent 继承主 agent 的模型，` +
+        `专用模型 '${model}' 不生效，已忽略（agentOptions 不注入）`,
+    )
+    return { model: null, provider: null }
+  }
+  return { model, provider }
+}
+
 /**
  * 自定义角色 toolName 保留名校验：与内置角色（ROLES）、restrict.mjs 主 agent
  * allow 白名单（restrictBase）、顶层 subagent / subagent_fork 撞名的 toolName
@@ -163,14 +236,19 @@ export function renderCustomRoleBlocks(roles, skillsMap, restrictBase = []) {
       toolName,
       skillsMap,
     )
-    // 角色专用模型与可续模式（roles.<toolName>.model / .provider / .background_mode）：
-    // 自定义角色与内置角色同形状（provider: spawn / toolName / agentOptions? /
-    // backgroundMode / persona / toolFilter）。先归一再判 provider-alone（防 UI /
-    // 手工构造的 assignments 绕过规范化）；仅 model 非 null 才插 agentOptions 子块，
-    // provider-alone 仅 warn 忽略。backgroundMode 行恒写（与内置块源模板预置口径
-    // 一致：行始终可见），continuable → continuable，one-shot/缺省/异常值 →
-    // one-shot（与 config 解析回落口径一致）。
-    const { model, provider } = normalizeRoleModel(toolName, role.model ?? null, role.provider ?? null)
+    // 角色专用模型、启动方式与可续模式（roles.<toolName>.model / .provider /
+    // .start_mode / .background_mode）：自定义角色与内置角色同形状（provider /
+    // toolName / agentOptions? / backgroundMode / persona / toolFilter）。启动方式
+    // 恰好 'fork' 才认（其余一律 fresh，见 roleStartModeOf）：fork 时块级
+    // provider 行落 fork（子 agent 以主 agent 已完成的对话轮次为初始内容启动），
+    // 否则恒 spawn。先归一再判 provider-alone（防 UI / 手工构造的 assignments 绕过
+    // 规范化）；fork 与专用模型互斥（fork 子 agent 继承主 agent 的提供方与模型），
+    // 经 resolveRoleModel 判定 —— 命中 warn 后按缺省处理，仅 model 非 null 才插
+    // agentOptions 子块，provider-alone 仅 warn 忽略。backgroundMode 行恒写（与
+    // 内置块源模板预置口径一致：行始终可见），continuable → continuable，
+    // one-shot/缺省/异常值 → one-shot（与 config 解析回落口径一致）。
+    const startMode = roleStartModeOf(role)
+    const { model, provider } = resolveRoleModel(toolName, role.model ?? null, role.provider ?? null, startMode)
     // agentOptions 子行（键序固定 provider 在前、model 在后，与 dsh-tool-subagent
     // Config 字段序一致）；model 缺省时整块不出现。
     const agentOptionsLines = []
@@ -188,7 +266,9 @@ export function renderCustomRoleBlocks(roles, skillsMap, restrictBase = []) {
         `    - id: delegation-${toolName}`,
         `      name: '@deepseek-ai/dsh-tool-subagent'`,
         '      config:',
-        '        provider: spawn',
+        // 块级 provider = 启动方式（spawn 全新启动 / fork 继承主 agent 已完成
+        // 轮次），与 10 空格缩进的 agentOptions.provider（LLM 路由）分属两处。
+        `        provider: ${startMode === 'fork' ? 'fork' : 'spawn'}`,
         // toolName / 工具条目过 yamlScalar：纯数字、YAML 字面量形态等歧义名
         // 必须带引号落盘，否则委派行会被解析成数字/布尔/null。
         `        toolName: ${yamlScalar(toolName)}`,
@@ -357,11 +437,12 @@ export function delegationRowSpan(srcText, role) {
 }
 
 /**
- * 内置角色委派块边界定位（roleToolNameLineEnd / injectRoleBackgroundMode 共用）：
+ * 内置角色委派块边界定位（roleToolNameLineEnd / injectRoleStartMode /
+ * injectRoleBackgroundMode 共用）：
  * 块定位 `- id: delegation-<rowId>`（rowId = 角色名 `_` 换 `-`，找不到 throw）；
  * 块结束 = min(其后首个 `\n    - id: delegation-` 下标, '# ── remaining
  * model-facing rows' 注释下标, srcText.length)，保证块内行搜索不越界命中
- * 别的块。errorKey 用于把报错归因到具体配置键（model / background_mode）。
+ * 别的块。errorKey 用于把报错归因到具体配置键（model / start_mode / background_mode）。
  */
 function roleDelegationBlockBounds(srcText, role, errorKey) {
   const rowId = role.replace(/_/g, '-') // 委派行 id 用连字符（toolName 用下划线）
@@ -463,6 +544,37 @@ export function injectRoleBackgroundMode(srcText, role) {
   return { start: lineEnd, end: lineEnd, text: '\n        backgroundMode: continuable' }
 }
 
+/**
+ * 角色启动方式改写（roles.<toolName>.start_mode = 'fork' 生效路径）：把该内置
+ * 角色委派块内 8 空格缩进的块级 `provider: spawn` 行原位改写为
+ * `provider: fork`，子 agent 以主 agent（父级）已完成的对话轮次为初始内容启动。
+ * 锚点定位复用 roleDelegationBlockBounds，行搜索限定块内（不越界命中别的块）；
+ * 行首带 \n 且恰 8 空格，10 空格缩进的 agentOptions.provider 子行（LLM 路由）
+ * 形态不匹配，天然区分 —— 块级 provider（启动提供方）与 agentOptions 子行
+ * （模型路由）分属两处，互不相干。
+ * 返回 span edit { start, end, text }（整行原位改写，坐标为源文本原坐标，与
+ * allow/persona/删除 edits 一起按 start 降序应用）。无任何改动时返回 null：
+ *  - 'fresh'（含缺省）：不动源行 —— 源模板四块各预置 `provider: spawn`，全默认
+ *    配置的生成产物与源逐字节一致（零 diff 不变量）；
+ *  - 行已是 fork：幂等返回 null；
+ *  - 块内无 provider 行：不兜底注入，静默保留原样 —— 与 injectRoleBackgroundMode
+ *    的「缺行兜底注入」口径刻意不同：backgroundMode 是产品旋钮（源模板为可见性
+ *    预置），而块级 provider 行是委派块的骨架配置，缺失即模板损坏；半截注入
+ *    救不了坏模板，静默保留比产出难排查的配置更稳妥，模板漂移由恒等性金测兜底。
+ * 调用方（composeGenerated）仅对 'fork' 调本函数。
+ */
+export function injectRoleStartMode(srcText, role) {
+  const { idx, blockEnd } = roleDelegationBlockBounds(srcText, role, 'start_mode')
+  // 块内 span 查块级 provider 行：8 空格缩进（config 键层），行首带 \n 保证不误
+  // 匹配块首部分行或 persona 内容行；锚点含 'spawn' 值，10 空格的
+  // agentOptions.provider（其缩进多两格，前缀不命中）天然被排除。
+  const providerMarker = '\n        provider: spawn'
+  const providerIdx = srcText.indexOf(providerMarker, idx)
+  if (providerIdx === -1 || providerIdx >= blockEnd) return null
+  const lineStart = providerIdx + 1 // 跳过行首 \n，定位到行首
+  return { start: lineStart, end: lineStart + providerMarker.length - 1, text: '        provider: fork' }
+}
+
 /**
  * 主 persona 整块改造（删委派 bullet + 自定义角色自动委派行），返回一个
  * span edit { start, end, text }（start/end 为源文本原坐标、随其它 edits 降序应用），
@@ -559,7 +671,7 @@ export function filterUsableTools(tools, presetUniverse, inventory) {
  * block / restrict config.allow injection) plus the per-role diff info for
  * the report.
  */
-export function composeGenerated(srcText, blocks, personaBlocks, assignments, inventory, restrictBase, mainAgentSkillMetas = {}) {
+export function composeGenerated(srcText, blocks, personaBlocks, assignments, inventory, restrictBase, mainAgentSkillMetas = {}, hostVersionTriple = null) {
   const skillsMap = assignments.skills ?? {}
   const customToolNames = Object.keys(assignments.roles).filter((n) => !ROLES.includes(n))
   // roles_remove：被删除的内置角色不产 allow/persona edits（委派行整条删除时避免重叠），
@@ -669,22 +781,31 @@ export function composeGenerated(srcText, blocks, personaBlocks, assignments, in
   const personaEdit = composeMainPersonaEdit(srcText, removedRoles, customBullets)
   if (personaEdit !== null) edits.push(personaEdit)
 
-  // 角色专用模型 / 可续模式注入（roles.<toolName>.model / .provider → 委派块
-  // agentOptions；roles.<toolName>.background_mode = 'continuable' → 委派块
-  // backgroundMode 行改写/兜底注入）：与 roles_remove 委派行删除 edits 同段收集。
-  // 被删角色不注入（委派行已整条删除，模型 / background_mode 配置 warn 忽略）；
-  // 仅 model 非 null 才注入 agentOptions，provider-alone 仅 warn 忽略（先 normalize
-  // 再判断，防手工构造的 assignments 绕过规范化）；background_mode 仅 'continuable'
+  // 角色专用模型 / 启动方式 / 可续模式注入（roles.<toolName>.model / .provider →
+  // 委派块 agentOptions；roles.<toolName>.start_mode = 'fork' → 委派块块级
+  // provider 行原位改写 fork；roles.<toolName>.background_mode = 'continuable' →
+  // 委派块 backgroundMode 行改写/兜底注入）：与 roles_remove 委派行删除 edits 同段
+  // 收集。被删角色不注入（委派行已整条删除，模型 / start_mode / background_mode
+  // 配置 warn 忽略）；fork 与专用模型互斥（fork 子 agent 继承主 agent 的提供方与
+  // 模型，KV cache 复用硬约束），经 resolveRoleModel 判定 —— 命中 warn 后按缺省
+  // 处理（不注入 agentOptions），provider-alone 仅 warn 忽略（先 normalize 再判断，
+  // 防手工构造的 assignments 绕过规范化）；start_mode 仅 'fork' 才调
+  // injectRoleStartMode（'fresh'/缺省不调 —— 源模板四块各预置的 `provider: spawn`
+  // 原样保留，全默认配置生成产物与源逐字节一致），background_mode 仅 'continuable'
   // 才调 injectRoleBackgroundMode（'one-shot'/缺省不调 —— 源模板四块各预置的
   // `backgroundMode: one-shot` 原样保留，全默认配置生成产物与源逐字节一致）。
   // 键序与收集序：源块已有该行时走改写路径（edit start = 既有行行首，位于
   // toolName 行行尾之后 → 降序应用先改写该行，agentOptions 随后插在更前的
   // toolName 行行尾，键序 toolName → agentOptions? → backgroundMode 自然成立）；
-  // 源块无该行时走兜底注入路径，与 agentOptions 同锚点（start 相等）→ backgroundMode
+  // startMode 改写的 provider 行在 toolName 行之前（块内键序 provider → toolName），
+  // edit start 更小 → 降序应用最后生效，与上述键序互不干扰；源块无该行时走兜底
+  // 注入路径，与 agentOptions 同锚点（start 相等）→ backgroundMode
   // edit 必须先于 agentOptions edit 收集（先收集者居后），与自定义块键序一致。
   for (const role of ROLES) {
     const rawModel = assignments.roles[role]?.model ?? null
     const rawProvider = assignments.roles[role]?.provider ?? null
+    // compose 层兜底：恰好 'fork' 才认，其余（缺省/异常值）一律 fresh（见 roleStartModeOf）。
+    const startMode = roleStartModeOf(assignments.roles[role])
     const rawBackgroundMode = assignments.roles[role]?.background_mode ?? null
     if (removedRoles.includes(role)) {
       const model = normalizeModelRef(rawModel, `roles.${role}.model`)
@@ -692,6 +813,9 @@ export function composeGenerated(srcText, blocks, personaBlocks, assignments, in
       if (model !== null || provider !== null) {
         warn(`roles.${role}.model: 该角色已在 roles_remove 中删除，模型配置被忽略`)
       }
+      if (startMode === 'fork') {
+        warn(`roles.${role}.start_mode: 该角色已在 roles_remove 中删除，start_mode 配置被忽略`)
+      }
       if (rawBackgroundMode === 'continuable') {
         warn(`roles.${role}.background_mode: 该角色已在 roles_remove 中删除，background_mode 配置被忽略`)
       }
@@ -701,8 +825,12 @@ export function composeGenerated(srcText, blocks, personaBlocks, assignments, in
       const backgroundModeEdit = injectRoleBackgroundMode(srcText, role)
       if (backgroundModeEdit !== null) edits.push(backgroundModeEdit)
     }
-    const { model, provider } = normalizeRoleModel(role, rawModel, rawProvider)
+    const { model, provider } = resolveRoleModel(role, rawModel, rawProvider, startMode)
     if (model !== null) edits.push(injectRoleAgentOptions(srcText, role, model, provider))
+    if (startMode === 'fork') {
+      const startModeEdit = injectRoleStartMode(srcText, role)
+      if (startModeEdit !== null) edits.push(startModeEdit)
+    }
   }
   // 注入 edit（零宽，位于 toolName 行行尾）与该块的 allow edit / persona edit
   // 区间天然不相交：委派块内 toolName 行先于 persona / toolFilter 出现，插入点
@@ -713,6 +841,9 @@ export function composeGenerated(srcText, blocks, personaBlocks, assignments, in
   edits.sort((a, b) => b.start - a.start)
   for (const edit of edits) out = out.slice(0, edit.start) + edit.text + out.slice(edit.end)
 
+  // workflow worker 行宿主版本适配（≥0.1.6 换 workflow-ptc；见 adaptWorkflowWorkerRow）。
+  out = adaptWorkflowWorkerRow(out, hostVersionTriple)
+
   const customBlock = renderCustomRoleBlocks(assignments.roles, skillsMap, restrictBase)
   if (customBlock !== '') out = insertCustomRoles(out, customBlock)
 

package/tools/lib/config.mjs

@@ -2,10 +2,12 @@
  * dsh-paoding.config.yml 键规范化与读写：main_agent_display_name /
  * roles.<toolName>.name /
  * roles.<toolName>.model / roles.<toolName>.provider（角色专用模型，生成层映射到
- * dsh-tool-subagent 的 agentOptions）/ roles.<toolName>.background_mode（可续模式，
+ * dsh-tool-subagent 的 agentOptions）/ roles.<toolName>.start_mode（角色启动方式，
+ * 生成层把内置委派块的块级 provider 行改写为 fork，'fresh' | 'fork'）/
+ * roles.<toolName>.background_mode（可续模式，
  * 生成层映射到 dsh-tool-subagent 的 backgroundMode，'one-shot' | 'continuable'）/
  * roles_remove 解析（normalizeRoleName /
- * normalizeModelRef / normalizeBackgroundMode / parseRolesRemove / yamlScalar）、
+ * normalizeModelRef / normalizeBackgroundMode / normalizeStartMode / parseRolesRemove / yamlScalar）、
  * 目标字段集合的规范化与写出（normalizeTargetFields / writeTargetFields —— 顶层与
  * workspaces.<path> 条目共用同一套）、按工作区条目段（normalizeWorkspaces）、
  * 文件加载与规范化（loadConfig / normalizeConfig）、序列化与落盘（serializeConfig /
@@ -86,6 +88,27 @@ export function normalizeBackgroundMode(value, label = 'background_mode') {
   return value
 }
 
+/**
+ * 校验并规范化 roles.<toolName>.start_mode（角色启动方式，映射到 dsh-tool-subagent
+ * 委派块的块级 provider 行：'fresh' = spawn 全新启动，'fork' = 以主 agent 已完成的
+ * 对话轮次为初始内容启动）。合法值仅 'fresh' | 'fork'：缺省/null → 缺省值
+ * 'fresh'（静默，与 name/model/provider 的 null 口径一致）；非字符串或字符串但
+ * 不在合法值集 → warn 后回落 'fresh'（与 normalizeBackgroundMode 的非法值处理
+ * 同款：类型/取值不对降级提醒而非中断加载）。返回恒为合法值之一，生成层
+ * （compose）据此决定是否把块级 provider 行改写为 fork。
+ * 注意：本键与 roles.<toolName>.provider（LLM 路由，与 model 配对映射到
+ * agentOptions 子行）毫无关系 —— 子 agent 的启动提供方只有委派块里那行块级
+ * provider，本键是它的配置面。
+ */
+export function normalizeStartMode(value, label = 'start_mode') {
+  if (value === null || value === undefined) return 'fresh'
+  if (typeof value !== 'string' || (value !== 'fresh' && value !== 'fork')) {
+    warn(`${label}: 非法值已忽略（${JSON.stringify(value)}），回落 'fresh'（可选: 'fresh' / 'fork'）`)
+    return 'fresh'
+  }
+  return value
+}
+
 /**
  * 解析配置键 roles_remove：string[]，只收 ROLES 内置角色名（search_external /
  * design / implement）；含其他名字 warn 并忽略；去重保序。非数组 → []。
@@ -138,7 +161,7 @@ function yamlFlowScalar(value) {
 /**
  * Load the config file when present.  Returns null when the file does not
  * exist; throws when it exists but cannot be parsed.  Shape:
- *   { profile, roles: { <toolName>: { name?, model?, provider?, background_mode?, persona?, tools[] } },
+ *   { profile, roles: { <toolName>: { name?, model?, provider?, start_mode?, background_mode?, persona?, tools[] } },
  *     roles_remove[] (内置角色删除), main_agent_extra[], main_agent_remove[],
  *     main_agent_skills[], main_agent_skills_inline[],
  *     main_agent_persona_extra? (string|null),
@@ -220,7 +243,7 @@ function normalizeWorkspaces(raw) {
 
 /**
  * 目标字段集合规范化：顶层（除 profile 外）与 workspaces.<path> 条目共用的
- * 同一套键 —— roles（条目含 background_mode）/ roles_remove / main_agent_extra（含 has_main_agent_extra
+ * 同一套键 —— roles（条目含 start_mode / background_mode）/ roles_remove / main_agent_extra（含 has_main_agent_extra
  * 内部标记）/ main_agent_remove / main_agent_skills / main_agent_skills_inline /
  * main_agent_persona_extra / main_agent_display_name / skills。
  * 语义与抽取前逐字一致；
@@ -243,18 +266,21 @@ export function normalizeTargetFields(raw) {
         warn(`roles.${toolName}.${key}: 非字符串值已忽略（${JSON.stringify(v)}）`)
       }
     }
-    // 角色条目字段顺序 { name?, model?, provider?, background_mode?, persona?, tools? }：
+    // 角色条目字段顺序 { name?, model?, provider?, start_mode?, background_mode?, persona?, tools? }：
     // name（roles.<toolName>.name，内置角色可选显示名）与主 agent 显示名同约束，
     // 仅字符串收（trim 后空/违规由 normalizeRoleName 处理）；缺省/null → null
     // （= 保持该角色默认身份句）。model / provider（roles.<toolName>.model /
     // .provider，角色专用模型）镜像同款收法，违规由 normalizeModelRef 处理；
     // 缺省/null → null（= 不注入 agentOptions，子 agent 继承主 agent 当前模型）。
-    // background_mode（roles.<toolName>.background_mode，角色可续模式）仅收
+    // start_mode（roles.<toolName>.start_mode，角色启动方式）仅收 'fresh' | 'fork'，
+    // 其余 warn 回落 'fresh'（normalizeStartMode）。background_mode
+    // （roles.<toolName>.background_mode，角色可续模式）仅收
     // 'one-shot' | 'continuable'，其余 warn 回落 'one-shot'（normalizeBackgroundMode）。
     roles[toolName] = {
       name: typeof raw.name === 'string' ? normalizeRoleName(raw.name, `roles.${toolName}.name`) : null,
       model: typeof raw.model === 'string' ? normalizeModelRef(raw.model, `roles.${toolName}.model`) : null,
       provider: typeof raw.provider === 'string' ? normalizeModelRef(raw.provider, `roles.${toolName}.provider`) : null,
+      start_mode: normalizeStartMode(raw.start_mode, `roles.${toolName}.start_mode`),
       background_mode: normalizeBackgroundMode(raw.background_mode, `roles.${toolName}.background_mode`),
       persona: typeof raw.persona === 'string' && raw.persona.trim() !== '' ? raw.persona : null,
       tools,
@@ -359,7 +385,7 @@ function writeTargetFields(lines, pad, target) {
     // roles.<toolName>.model / .provider：仅非 null 写出（null/缺省 = 不注入
     // agentOptions，子 agent 继承主 agent 当前模型）；写前过一次 normalizeModelRef
     // （与上方 name 写法一致，防手工构造的 config 绕过规范化），字段序 name →
-    // model → provider → background_mode → persona → tools 固定。
+    // model → provider → start_mode → background_mode → persona → tools 固定。
     if (role.model !== null && role.model !== undefined) {
       const model = normalizeModelRef(role.model, `roles.${toolName}.model`)
       if (model !== null) lines.push(`${pad}    model: ${yamlScalar(model)}`)
@@ -368,6 +394,10 @@ function writeTargetFields(lines, pad, target) {
       const provider = normalizeModelRef(role.provider, `roles.${toolName}.provider`)
       if (provider !== null) lines.push(`${pad}    provider: ${yamlScalar(provider)}`)
     }
+    // roles.<toolName>.start_mode：恒写出（含缺省 fresh）—— 与 background_mode 同
+    // 款「旋钮可见、读写往返幂等」口径（loadConfig 也恒收此键）。写前过一次判定
+    // （防手工构造的 config 绕过规范化）：非 'fork' 一律按 'fresh' 落盘。
+    lines.push(`${pad}    start_mode: ${role.start_mode === 'fork' ? 'fork' : 'fresh'}`)
     // roles.<toolName>.background_mode：恒写出（含缺省 one-shot）—— 配置文件里
     // 旋钮对用户可见、读写往返幂等（loadConfig 也恒收此键）。写前过一次判定
     // （防手工构造的 config 绕过规范化）：非 'continuable' 一律按 'one-shot' 落盘。

package/tools/lib/preset-system.mjs

@@ -20,8 +20,10 @@
  *      写盘并明确报错，与仓库「配置不可信时拒绝落盘」口径一致。
  *   4) 轨道迁移对账 backfillHomePatchRows / listOrchestratorPresetIds /
  *      parseGeneratorMarker / formatGeneratorMarker：宿主只升 dsh 不动插件时
- *      （标记版本一致、轨道翻转——升级最常见路径），按磁盘产物补写缺失声明行
- *      而不整盘重生成；生成器标记记「版本 + 轨道」两行，任一不符即触发自愈。
+ *      （标记版本一致、轨道翻转或 workflow worker 形态换代——升级最常见路径），
+ *      按磁盘产物补写缺失声明行而不整盘重生成；生成器标记记「版本 + 轨道 +
+ *      worker 形态」三行，任一不符即触发自愈（worker 形态换代必须整盘重生成，
+ *      见 detectHostVersionTriple / isPtcWorkerHost）。
  * 零运行时依赖（node:child_process / node:fs / node:path / node:url）；被 state 引用。
  */
 import { spawnSync } from 'node:child_process'
@@ -55,16 +57,20 @@ export function parseVersionTriple(text) {
   return [Number(m[1]), Number(m[2]), Number(m[3])]
 }
 
-/** 三元组是否达到声明行轨（0.1.7+）：逐段数值比较，prerelease 已在上游剥掉。 */
-export function isDeclarativeTriple(triple) {
-  if (!Array.isArray(triple) || triple.length !== 3 || triple.some((n) => !Number.isInteger(n))) return false
-  const base = [0, 1, 7]
+/** 三元组逐段与基准比较：≥ 基准返回 true（prerelease 已在上游剥掉）。 */
+function atOrAfterTriple(triple, base) {
   for (let i = 0; i < 3; i++) {
     if (triple[i] !== base[i]) return triple[i] > base[i]
   }
   return true
 }
 
+/** 三元组是否达到声明行轨（0.1.7+）：逐段数值比较，prerelease 已在上游剥掉。 */
+export function isDeclarativeTriple(triple) {
+  if (!Array.isArray(triple) || triple.length !== 3 || triple.some((n) => !Number.isInteger(n))) return false
+  return atOrAfterTriple(triple, [0, 1, 7])
+}
+
 /**
  * 探测当前宿主的预设安装轨道，返回 'declarative' | 'directory'。逐级降级：
  *   1) runtimeSystem 直通：Web 插件运行时对宿主服务的实时探测结果最权威；
@@ -536,10 +542,12 @@ export function backfillHomePatchRows(dshHome, presetIds) {
 }
 
 /**
- * 解析 .generator-version 标记文本为 { version, track }。v2 格式两行：首行
- * 生成器版本、次行预设安装轨道（declarative / directory）；旧格式（单行版本，
- * 0.3.4 及以前）解析出 track: null —— 恰是「宿主轨道已翻转但产物版本未动」的
- * 迁移触发态。空文本 / 全空白返回 null（按未生成处理）。
+ * 解析 .generator-version 标记文本为 { version, track, worker }。v3 格式三行：
+ * 首行生成器版本、次行预设安装轨道（declarative / directory）、三行 workflow
+ * worker 形态（ptc / worker-thread）；旧格式（v2 两行 = 0.3.6 及以前、单行 =
+ * 0.3.4 及以前）解析出 track / worker 为 null —— 恰是「宿主已换代但产物版本
+ * 未动」的迁移触发态（轨道翻转、worker 换代都靠它触发自愈）。空文本 / 全空白
+ * 返回 null（按未生成处理）。
  */
 export function parseGeneratorMarker(text) {
   const lines = String(text ?? '')
@@ -548,10 +556,49 @@ export function parseGeneratorMarker(text) {
     .filter((l) => l !== '')
   if (lines.length === 0) return null
   const track = lines[1] === 'declarative' || lines[1] === 'directory' ? lines[1] : null
-  return { version: lines[0], track }
+  const worker = lines[2] === 'ptc' || lines[2] === 'worker-thread' ? lines[2] : null
+  return { version: lines[0], track, worker }
+}
+
+/**
+ * 生成 .generator-version 标记文本（版本 + 轨道 + worker 形态三行，v3 格式）。
+ * worker 取 WORKER_PTC / WORKER_WORKER_THREAD（允许调用方先探测再传入）。
+ */
+export function formatGeneratorMarker(version, presetSystem, worker) {
+  return `${version}\n${presetSystem}\n${worker}\n`
 }
 
-/** 生成 .generator-version 标记文本（版本 + 轨道两行，v2 格式）。 */
-export function formatGeneratorMarker(version, presetSystem) {
-  return `${version}\n${presetSystem}\n`
+// ── workflow worker 形态（宿主版本 → 生成期换行）────────────────────────────
+
+/** 生成产物里 workflow worker 行的两种形态（标记第三行的合法取值）。 */
+export const WORKER_PTC = 'ptc'
+export const WORKER_WORKER_THREAD = 'worker-thread'
+
+/**
+ * 探测正在运行的宿主版本三元组：进程 argv 宿主版本（插件与宿主同进程时零开销
+ * 且反映正在运行的宿主）> PATH 上的 `dsh --version` > null。与
+ * detectPresetSystem 的前两级同源复用，但不再往下走文件探测——0.1.5 与 0.1.6
+ * 的磁盘形态没有可区分的单数包，探测不到就返回 null 由调用方按未知处理。
+ */
+export function detectHostVersionTriple() {
+  const argvVersion = hostVersionFromArgv()
+  if (argvVersion !== null) return parseVersionTriple(argvVersion)
+  const versionText = dshVersionText()
+  if (versionText !== null) return parseVersionTriple(versionText)
+  return null
+}
+
+/**
+ * 该宿主版本的 workflow worker 行形态：≥0.1.6 用 @deepseek-ai/dsh-workflow-ptc
+ * （0.1.6-alpha.1 起 workflow-worker-thread 包已删除，残留行会让 preset 的
+ * delegation 组报 never started，0.2.0 Plugin Manager 显示为「加载失败」）；
+ * 0.1.5 只认 @deepseek-ai/dsh-workflow-worker-thread。版本探测不到时返回 false
+ *（保守侧：保留源模板原行）——「探测不到」走不出插件运行时（argv 必命中），
+ * 多见于无 dsh 在 PATH 的原始环境；保守默认让 0.1.5 全场景可用，也与
+ * detectPresetSystem 的安全侧兜底哲学一致（产物零 diff 的 golden 性质随之保留：
+ * 显式 null 不改源文）。
+ */
+export function isPtcWorkerHost(triple) {
+  if (!Array.isArray(triple) || triple.length !== 3 || triple.some((n) => !Number.isInteger(n))) return false
+  return atOrAfterTriple(triple, [0, 1, 6])
 }

package/tools/lib/state.mjs

@@ -48,6 +48,7 @@ import { composeGenerated, extractMainAgentAllow } from './compose.mjs'
 import { smartDefaults } from './alloc.mjs'
 import {
   buildPresetRowText,
+  detectHostVersionTriple,
   detectPresetSystem,
   listOrchestratorPresetIds,
   presetRowId,
@@ -232,6 +233,10 @@ export async function collectState({ dshHome, configFile, profile = null, patche
   //（见 preset-system.detectPresetSystem 的降级链）。
   const presetSystem = await detectPresetSystem({ dshHome, runtimeSystem: runtimeFacts?.presetSystem ?? null })
 
+  // 宿主版本三元组（argv 宿主版本 > dsh --version > null，探测不到按未知处理）：
+  // workflow worker 行的生成期形态判定（isPtcWorkerHost）与标记 worker 行都从这里取。
+  const hostVersionTriple = detectHostVersionTriple()
+
   // 已落盘 preset 目录扫描（编排类）：.agent-presets 下的 orchestrator 基础
   // preset 与 orchestrator-<slug> 工作区专属 preset。扫描失败（目录尚不存在、
   // 无读权限等）一律降级为空列表，绝不影响检测结果本体；generateAndInstall
@@ -265,6 +270,8 @@ export async function collectState({ dshHome, configFile, profile = null, patche
     installedPresets,
     // 预设安装轨道（generateAndInstall 据此双轨收尾；serializeState 透传给面板）
     presetSystem,
+    // 宿主版本三元组（null = 探测不到）：workflow worker 行生成期形态判定用
+    hostVersionTriple,
     // 主 persona 尾部追加的默认常量（配置键 main_agent_persona_extra 缺省值）：
     // 供 UI state（serializeState → /api/paoding/state）展示与「恢复默认」用。
     mainPersonaExtraDefault: DEFAULT_MAIN_AGENT_PERSONA_EXTRA,
@@ -366,8 +373,9 @@ export function generateAndInstall(state, assignments, { dryRun = false, saveCon
   }
 
   // Compose the generated config; a composition error is a hard error.
-  //（这层包装无增值，让 composeGenerated 的原始错误直接上抛。）
-  const composed = composeGenerated(srcText, blocks, personaBlocks, assignments, inventory, restrictBase, mainAgentSkillMetas)
+  //（这层包装无增值，让 composeGenerated 的原始错误直接上抛。）宿主版本三元组
+  // 驱动 workflow worker 行的生成期换行（≥0.1.6 → workflow-ptc，null 按现代宿主）。
+  const composed = composeGenerated(srcText, blocks, personaBlocks, assignments, inventory, restrictBase, mainAgentSkillMetas, state?.hostVersionTriple ?? null)
   const generatedText = composed.text
   const roleResults = composed.roleResults