dsh-knj-workflow 2026.8.25 → 2026.8.280

package/README.md

@@ -42,13 +42,11 @@
 ## 安装
 
 ```sh
-# 在插件目录打包
-pnpm pack                     # 生成 dsh-knj-workflow-0.1.0.tgz
-
-# 安装到 dsh web profile（重启 dsh web 生效）
-dsh plugin --profile web add ./dsh-knj-workflow-0.1.0.tgz
+dsh plugin --profile web add dsh-knj-workflow
 ```
 
+> npm 包 [`dsh-knj-workflow`](https://www.npmjs.com/package/dsh-knj-workflow)；安装后重启 dsh web 生效。
+
 配置（可选，在 profile 的 `cordis.patch.yml` 中按 id `knj-workflow` 覆盖）：
 
 | 键 | 默认 | 说明 |

package/lib/client.js

@@ -157,8 +157,8 @@ window.__ModuleLoader__.load({
 .knj-item-foot{display:flex;align-items:center;gap:10px;margin-top:10px}
 .knj-item-foot .knj-progress{flex:1;width:auto}
 .knj-item-pct{font-size:12px;color:var(--dsw-alias-label-secondary);min-width:36px;text-align:right;font-variant-numeric:tabular-nums}
-/* 分页器 */
-.knj-pager{display:flex;align-items:center;justify-content:center;gap:14px;margin-top:14px}
+/* 分页器（sticky 钉在看板底部可见区，列表内部滚动时无需滚到底即可翻页） */
+.knj-pager{display:flex;align-items:center;justify-content:center;gap:14px;margin-top:10px;position:sticky;bottom:0;background:var(--dsw-specific-menu);padding:10px 0 6px;border-top:1px solid var(--dsw-alias-border-l2);z-index:2}
 .knj-pager button{background:var(--dsw-alias-bg-layer-1);border:1px solid var(--dsw-alias-border-l2);border-radius:8px;width:32px;height:32px;cursor:pointer;color:var(--dsw-alias-label-primary);font-size:16px}
 .knj-pager button:hover{background:var(--dsw-alias-interactive-bg-hover)}
 .knj-pager button:disabled{opacity:.4;cursor:not-allowed}
@@ -1592,6 +1592,14 @@ window.__ModuleLoader__.load({
 						const title = view.title || view.name || (path ? path.replace(/[\\/]+$/, '').split(/[\\/]/).pop() : '');
 						if (path) cwdOptions.push({ path, title: title || path });
 					}
+					// 没有活跃会话时，「默认（当前工作区）」没有可继承的 cwd（服务端会直接报
+					// 「无法确定任务工作目录」）：预选第一个工作区，让无会话直建任务也能一次成功。
+					// 探测失败则保持默认，由服务端校验兜底。
+					try {
+						const ag = _ctx?.get?.('agents');
+						const live = ag?.currentInitiator?.() ?? ag?.roots?.()?.[0];
+						if (!live && cwdOptions.length > 0 && !this.state.cwd) this.setState({ cwd: cwdOptions[0].path });
+					} catch { /* 探测失败保持默认 */ }
 					this.setState({ cwdOptions });
 				} catch { /* 加载失败保持空 */ }
 			}

package/lib/index.js

@@ -317,7 +317,7 @@ function defaultWorkflow() {
 // ---------------------------------------------------------------------------
 // workflow 桥接：启动、事件监听
 // ---------------------------------------------------------------------------
-class WorkflowBridge {
+export class WorkflowBridge {
   constructor(ctx, store, orchestratorScript) {
     this.ctx = ctx;
     this.store = store;
@@ -335,37 +335,70 @@ class WorkflowBridge {
 
     // 为每个任务动态创建一个专用顶层会话作为 parent（隔离用户现有会话，
     // 不让 workflow 的 subagent 挂在「随机」的当前会话下）；失败则回退现有会话。
+    // seed（可继承配置的现有会话）不是必需的：任务自带 cwd 时，即使宿主里没有
+    // 任何活跃会话（刚启动 dsh web 直接在插件面板建任务：HTTP 链路无 initiator、
+    // roots 为空）也能自建专用 parent；无 seed 时 preset 用默认、模型用任务配置
+    // 或宿主默认。
     const agents = this.ctx.get('agents');
     let parent = null;
     let parentHandle = null;
-    if (typeof agents?.create === 'function') {
-      const seed = agents.currentInitiator?.() ?? agents.roots?.()?.[0];
-      if (seed) {
-        try {
-          // 关键：专用 parent 必须带 cwd（工作目录），否则它的 subagent 继承不到 cwd，
-          // 会以「no working directory for the child」启动即失败（task 被误标 success）。
-          // 优先用任务 cwd，其次继承 seed 会话的 cwd。
-          const seedCwd = seed.session?.header?.cwd;
-          const parentCwd = task.cwd || seedCwd;
-          parentHandle = await agents.create({
-            sessionId: `knj-task-${task.id}-${randomUUID().slice(0, 8)}`,
-            agentOptions: {
-              // 任务级模型配置优先（新建任务表单指定，如当前会话模型额度不足换其他模型）；
-              // 未配置则继承发起会话（seed）的模型。
-              ...((task.model || seed.options?.model) != null ? { model: task.model || seed.options?.model } : {}),
-              ...((task.provider || seed.options?.provider) != null ? { provider: task.provider || seed.options?.provider } : {}),
-              ...(seed.options?.maxTokens != null ? { maxTokens: seed.options.maxTokens } : {}),
+    const seed = agents?.currentInitiator?.() ?? agents?.roots?.()?.[0] ?? null;
+    // 关键：专用 parent 必须带 cwd（工作目录），否则它的 subagent 继承不到 cwd，
+    // 会以「no working directory for the child」启动即失败（task 被误标 success）。
+    // 优先用任务 cwd，其次继承 seed 会话的 cwd；两者皆无且无 seed 时不创建，
+    // 走下面的可操作报错（选个工作目录 / 先打开一个会话）。
+    const parentCwd = task.cwd || seed?.session?.header?.cwd || null;
+    if (typeof agents?.create === 'function' && (seed || parentCwd)) {
+      try {
+        // 关键：专用 parent 必须挂 agent preset（与宿主 apiproxy 的 composeAgent 同构）。
+        // agents.create 出来的新 agent scope 没有 parent：不挂 preset 时它——以及经
+        // composeFrom 继承其组合的全部 workflow subagent——只能看到宿主全局层，
+        // skill 工具与 catalog（含 ~/.dsh/skills 用户级 skills）、write/bash/pwsh 等
+        // preset 层工具全部缺失（subagent 只能瞎猜 write_file/shell 之类幻觉工具名）。
+        // preset id 必须在创建会话之前 resolve：header 在 session 边界快照 meta 时
+        // 定型，setup 里才发现的 id 永远进不了 header。挂载本身放在 setup 里，
+        // 失败会回滚整个创建（外层 catch 回退到现有会话，其 preset 天然可用）。
+        // 无 seed 时 resolve(undefined) 回落到默认 preset，与 apiproxy 行为一致。
+        const presets = this.ctx.get('agentPresets');
+        const presetId = presets
+          ? (await presets.resolve(seed?.session?.header?.agentPreset))?.id
+          : undefined;
+        parentHandle = await agents.create({
+          sessionId: `knj-task-${task.id}-${randomUUID().slice(0, 8)}`,
+          agentOptions: {
+            // 任务级模型配置优先（新建任务表单指定，如当前会话模型额度不足换其他模型）；
+            // 未配置则继承发起会话（seed）的模型；无 seed 时省略 → 宿主默认模型。
+            ...((task.model || seed?.options?.model) != null ? { model: task.model || seed?.options?.model } : {}),
+            ...((task.provider || seed?.options?.provider) != null ? { provider: task.provider || seed?.options?.provider } : {}),
+            ...(seed?.options?.maxTokens != null ? { maxTokens: seed.options.maxTokens } : {}),
+          },
+          meta: {
+            ...(parentCwd ? { cwd: parentCwd } : {}),
+            ...(presetId ? { agentPreset: presetId } : {}),
+          },
+          ...(presets ? {
+            setup: async (agentCtx) => {
+              await presets.mount(agentCtx, presetId);
             },
-            ...(parentCwd ? { meta: { cwd: parentCwd } } : {}),
-          });
-          parent = parentHandle?.agent;
-        } catch (error) {
-          this.ctx.logger?.warn?.(`dsh-knj-workflow: 创建专用 parent 会话失败，回退现有会话: ${error?.message || error}`);
-        }
+          } : {}),
+        });
+        parent = parentHandle?.agent;
+      } catch (error) {
+        this.ctx.logger?.warn?.(`dsh-knj-workflow: 创建专用 parent 会话失败，回退现有会话: ${error?.message || error}`);
       }
     }
     if (!parent) parent = agents?.currentInitiator?.() ?? agents?.roots?.()?.[0];
-    if (!parent) throw new Error('no active agent to own the workflow run');
+    if (!parent) {
+      // 到这里说明：宿主没有任何活跃会话（currentInitiator/roots 皆空），且上面没能
+      // 自建专用 parent。给出能直接照做的提示，而不是让人摸不着头脑的内部错误。
+      if (typeof agents?.create !== 'function') {
+        throw new Error('no active agent to own the workflow run（agents.create 不可用：需加载 agent-loop 插件）');
+      }
+      if (!parentCwd) {
+        throw new Error('无法确定任务工作目录：当前没有活跃会话可继承。请在「新建任务」表单中选择工作目录，或先打开任意一个会话再启动任务');
+      }
+      throw new Error('no active agent to own the workflow run（专用 parent 会话创建失败，详见宿主日志；也可先打开一个会话再试）');
+    }
 
     // 记录 parent 会话 id（agent.id === session.id，见 agent-loop enter 校验），
     // 前端「执行记录」用它 refreshSubagents 并把每个节点 subagent 跳转回原生会话。
@@ -497,6 +530,17 @@ class WorkflowBridge {
         this.listeners.delete(task.id);
         this.runs.delete(task.id);
       }
+      // 关键：run 是 holder-owned，契约要求持有者在 result 落定后调用 run.dispose()
+      // 释放引擎侧资源（等待子清理收敛）。不调用的话引擎 run 持续占用 parent 的
+      // machine，下面的 parentHandle.dispose() 会挂在 machine.whenIdle() 上永不返回，
+      // detachAgent（注册表注销）永远执行不到——实测复现：每个成功任务都遗留一个
+      // 常驻 knj-task-* root agent。与 dsh-tool-workflow 的规范持有方式
+      // （finally { await run.dispose() }）对齐。dispose 失败不阻塞终态，记 warn 可观测。
+      try {
+        await run.dispose?.();
+      } catch (error) {
+        this.ctx.logger?.warn?.(`dsh-knj-workflow: run dispose 失败（parent 可能泄漏）: ${error?.message || error}`);
+      }
       // 终态后释放专用 parent 会话（按 runId，避免误删新 run 的 parent）
       const handle = this.parentHandles.get(run.id);
       if (handle) {
@@ -697,7 +741,19 @@ function registerRoutes(ctx, store, bridge, prefix) {
       };
       await store.saveTask(task);
       if (body.autoStart !== false) {
-        await bridge.startTask(task);
+        try {
+          await bridge.startTask(task);
+        } catch (e) {
+          // 启动失败必须落库为 failed（与 /tasks/:id/start 一致），否则任务永远停在
+          // pending，界面只剩一个瞬时 toast，用户不知道可以在修复后点「启动」重试。
+          await store.mutateTask(task.id, (tt) => {
+            tt.status = 'failed';
+            tt.error = `启动失败：${e instanceof Error ? e.message : String(e)}`;
+            tt.finishedAt = nowIso();
+          }).catch(() => {});
+          sendJson(c.res, 500, { error: e instanceof Error ? e.message : String(e) });
+          return;
+        }
         task.status = 'running';
         task.startedAt = nowIso();
         await store.saveTask(task);
@@ -1019,7 +1075,17 @@ function registerCommands(ctx, store, bridge) {
             createdAt: nowIso(),
           };
           await store.saveTask(task);
-          await bridge.startTask(task);
+          try {
+            await bridge.startTask(task);
+          } catch (e) {
+            // 与 POST /tasks 一致：启动失败落库为 failed，避免任务永久停在 pending
+            await store.mutateTask(task.id, (tt) => {
+              tt.status = 'failed';
+              tt.error = `启动失败：${e instanceof Error ? e.message : String(e)}`;
+              tt.finishedAt = nowIso();
+            }).catch(() => {});
+            return { success: false, text: `任务 ${task.id} 已创建但启动失败：${e instanceof Error ? e.message : String(e)}。可在「开发任务」面板修复后重新启动。` };
+          }
           task.status = 'running';
           task.startedAt = nowIso();
           await store.saveTask(task);

package/lib/index.test.js

@@ -0,0 +1,176 @@
+/**
+ * dsh-knj-workflow WorkflowBridge.startTask 测试（node:test）
+ *
+ * 背景缺陷：专用 parent 会话经 agents.create() 创建时没挂 agent preset，
+ * 导致 workflow subagent（composeFrom 继承 parent 的组合）看不到 preset 层的
+ * skill 工具与 catalog（~/.dsh/skills 等用户级/项目级 skills 全部缺失），
+ * 连 write/bash 等 preset 层工具都没有。
+ *
+ * 运行：node --test lib/index.test.js（需能 resolve @deepseek-ai/schemastery，
+ * 建议在已安装副本目录 ~/.dsh/profiles/web/node_modules/dsh-knj-workflow 下跑）
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { WorkflowBridge } from './index.js';
+
+/** 最小 workflow 快照：start → task → end。 */
+const WF = {
+  id: 'wf1', name: 'WF',
+  nodes: [
+    { id: 'start', type: 'start' },
+    { id: 'n1', type: 'task', title: '做一件事', body: { prompt: '干活' } },
+    { id: 'end', type: 'end' },
+  ],
+  edges: [
+    { from: 'start', to: 'n1' },
+    { from: 'n1', to: 'end' },
+  ],
+};
+
+function makeTask() {
+  return { id: 'task-x', title: 'T', workflowId: 'wf1', cwd: 'D:/w', workflowSnapshot: WF };
+}
+
+/** 默认的 agentPresets mock：resolve(undefined) 回落 'standard'，mount 记录调用。 */
+function defaultPresetService(recorded) {
+  return {
+    async resolve(id) { return { id: id ?? 'standard' }; },
+    async mount(agentCtx, id) { recorded.mountCalls.push([agentCtx?.tag, id]); },
+  };
+}
+
+/** 构造 mock 环境：agents 服务（create/currentInitiator）、agentPresets 服务、workflowEngine。
+ *  live='seed'（默认）：存在可继承的 seed 会话；live='none'：宿主无任何活跃会话
+ *  （刚启动 dsh web 直接在插件面板建任务的场景：HTTP 链路无 initiator、roots 为空）。 */
+function makeEnv({ seedPreset = 'standard', presetService = 'default', live = 'seed' } = {}) {
+  const recorded = { createOpts: null, mountCalls: [], engineStartOpts: null, runDisposeCalls: 0 };
+  const presetSvc = presetService === 'default'
+    ? defaultPresetService(recorded)
+    : presetService === 'none' ? undefined : presetService;
+  const engine = {
+    start(opts) {
+      recorded.engineStartOpts = opts;
+      return {
+        id: 'run-1',
+        cancel() {},
+        dispose() { recorded.runDisposeCalls += 1; },
+        result: Promise.resolve({ stopReason: 'completed', value: { results: {} } }),
+      };
+    },
+  };
+  const parentAgent = {
+    id: 'parent-1',
+    scope: { ctx: { get: (n) => (n === 'workflowEngine' ? engine : undefined) } },
+  };
+  const seed = {
+    session: { header: { cwd: 'D:/w', ...(seedPreset ? { agentPreset: seedPreset } : {}) } },
+    options: {},
+  };
+  const agents = {
+    currentInitiator: () => (live === 'none' ? undefined : seed),
+    roots: () => (live === 'none' ? [] : [seed]),
+    async create(opts) {
+      recorded.createOpts = opts;
+      return { agent: parentAgent, dispose: async () => {} };
+    },
+  };
+  const ctx = {
+    on() {}, off() {},
+    logger: { info() {}, warn() {} },
+    get(name) {
+      if (name === 'agents') return agents;
+      if (name === 'agentPresets') return presetSvc;
+      return undefined;
+    },
+  };
+  const store = {
+    tasksDir: '.tasks',
+    getWorkflow: async () => WF,
+    saveTask: async () => {},
+    mutateTask: async () => {},
+    saveResults: async () => {},
+    writeStage: async () => {},
+  };
+  return { ctx, store, recorded, agents };
+}
+
+test('startTask: 专用 parent 必须挂 agent preset（setup 调 agentPresets.mount）', async () => {
+  const { ctx, store, recorded } = makeEnv();
+  const bridge = new WorkflowBridge(ctx, store, 'script');
+  await bridge.startTask(makeTask(), {});
+
+  assert.ok(recorded.createOpts, 'agents.create 应被调用');
+  assert.equal(typeof recorded.createOpts.setup, 'function',
+    'agents.create 必须传 setup：否则 parent（及其全部 workflow subagent）不挂 preset，' +
+    'skill 工具/catalog 与 write/bash 等 preset 层工具全部缺失');
+  const agentCtx = { tag: 'parent-scope' };
+  await recorded.createOpts.setup(agentCtx);
+  assert.equal(recorded.mountCalls.length, 1, 'setup 应调用 agentPresets.mount 一次');
+  assert.equal(recorded.mountCalls[0][0], 'parent-scope', 'mount 收到的是 agent scope ctx');
+});
+
+test('startTask: meta.agentPreset 需写入会话头（继承 seed 的 preset）', async () => {
+  const { ctx, store, recorded } = makeEnv({ seedPreset: 'standard' });
+  const bridge = new WorkflowBridge(ctx, store, 'script');
+  await bridge.startTask(makeTask(), {});
+  assert.equal(recorded.createOpts?.meta?.agentPreset, 'standard',
+    'header 在 session 边界快照 meta 时定型，preset id 必须随 meta 传入（供持久化/前端展示/subagent 继承语义）');
+});
+
+test('startTask: seed 无 preset 时用默认 preset（resolve(undefined) → defaultId）', async () => {
+  const { ctx, store, recorded } = makeEnv({ seedPreset: undefined });
+  const bridge = new WorkflowBridge(ctx, store, 'script');
+  await bridge.startTask(makeTask(), {});
+  assert.equal(typeof recorded.createOpts?.setup, 'function');
+  await recorded.createOpts.setup({ tag: 'x' });
+  assert.equal(recorded.mountCalls[0]?.[1], 'standard', 'resolve(undefined) 应回落到默认 preset id');
+  assert.equal(recorded.createOpts.meta?.agentPreset, 'standard');
+});
+
+test('startTask: 无 agentPresets 服务时优雅降级（不传 setup 也不炸）', async () => {
+  const { ctx, store, recorded } = makeEnv({ presetService: 'none' });
+  const bridge = new WorkflowBridge(ctx, store, 'script');
+  await bridge.startTask(makeTask(), {});
+  assert.ok(recorded.createOpts, '仍应创建专用 parent');
+  assert.equal(recorded.createOpts.setup, undefined,
+    '无 roster 部署没有 preset 可挂，行为应与 apiproxy composeAgent 一致：什么都不挂');
+  assert.equal(recorded.engineStartOpts?.parent?.id, 'parent-1', 'workflow 引擎仍以专用 parent 启动');
+});
+
+test('startTask: 无活跃会话但任务带 cwd → 仍自建专用 parent（默认 preset）', async () => {
+  const { ctx, store, recorded } = makeEnv({ live: 'none' });
+  const bridge = new WorkflowBridge(ctx, store, 'script');
+  const task = makeTask(); // cwd: 'D:/w'
+  await bridge.startTask(task, {});
+
+  assert.ok(recorded.createOpts, '无 seed 也应自建专用 parent（此前直接抛 no active agent）');
+  assert.equal(recorded.createOpts.meta?.cwd, 'D:/w', 'cwd 来自任务配置');
+  assert.equal(recorded.createOpts.meta?.agentPreset, 'standard', '无 seed 时 resolve(undefined) 回落默认 preset');
+  assert.equal(recorded.createOpts.agentOptions?.model, undefined, '无 seed 无任务模型时省略 model → 宿主默认');
+  assert.equal(recorded.engineStartOpts?.parent?.id, 'parent-1', 'workflow 引擎以自建 parent 启动');
+});
+
+test('startTask: 无活跃会话且无 cwd → 抛可操作错误（指引选工作目录/先开会话）', async () => {
+  const { ctx, store, recorded } = makeEnv({ live: 'none' });
+  const bridge = new WorkflowBridge(ctx, store, 'script');
+  const task = makeTask();
+  delete task.cwd;
+
+  await assert.rejects(
+    () => bridge.startTask(task, {}),
+    (err) => /工作目录/.test(err.message) && /no active agent|会话/.test(err.message),
+    '错误信息必须说清「无法确定工作目录」并给出可照做的下一步，而不是裸的内部错误');
+  assert.equal(recorded.createOpts, null, '无 cwd 无 seed 时不应调用 agents.create（建出来 subagent 也会因缺 cwd 失败）');
+});
+
+test('startTask: run 终态后必须调用 run.dispose（否则引擎占用 parent machine，parent 永不注销）', async () => {
+  const { ctx, store, recorded } = makeEnv();
+  const bridge = new WorkflowBridge(ctx, store, 'script');
+  await bridge.startTask(makeTask(), {});
+  // run.result 立即 resolve，.then 回调（finalizeTask → 清理 → dispose）在微任务链执行：
+  // setImmediate 排空后再断言，保证回调已跑完。
+  await new Promise((resolve) => setImmediate(resolve));
+  assert.equal(recorded.runDisposeCalls, 1,
+    'result 落定后应恰好调用一次 run.dispose()（holder 契约，与 dsh-tool-workflow 的 finally { await run.dispose() } 对齐）；' +
+    '否则引擎 run 不释放，parentHandle.dispose 挂在 machine.whenIdle() 上，knj-task-* parent 永久泄漏');
+});

package/package.json

@@ -1,6 +1,6 @@
-{
+{
   "name": "dsh-knj-workflow",
-  "version": "2026.8.25",
+  "version": "2026.8.280",
   "description": "KNJ 开发任务编排插件：配置驱动的工作流 + 开发任务管理 + 可视化阶段进度（DeepSeek Harness）",
   "author": "knj",
   "license": "MIT",