dsh-knj-workflow 0.1.94

package/lib/graph.js

@@ -0,0 +1,197 @@
+/**
+ * dsh-knj-workflow 图工作流纯函数（零依赖，Host 端与编排器脚本共用语义）
+ * ---------------------------------------------------------------
+ * validateWorkflow - 图结构校验（start/end、孤立节点、边、网关拓扑）
+ * nextNode         - 路由：给定当前节点 + 上下文 → 下一步节点 id
+ * resolveInputs    - 数据流：解析节点显式参数映射（inputs）
+ *
+ * 数据模型约定（见 WORKFLOW-DESIGN.md 第 6 节）：
+ *   - 节点 type：start | end | task | gateway-xor | gateway-and | human
+ *   - XOR 网关单入边多出边，when.field 相对唯一上游；至少一条 default 出边
+ *   - AND 网关 split（多出单入）或 join（多入单出），不混合
+ *   - human 节点路由由 routes（label + to 的多去向）决定，兼容旧 approveTo / rejectTo（不在 edges 上写 when）
+ *   - ctx 形状：{ <nodeId>: { <field>: value } }
+ */
+
+const NODE_TYPES = new Set(['start', 'end', 'task', 'gateway-xor', 'gateway-and', 'human']);
+
+/** 人工节点去向：routes 优先（多去向：label + to），兼容旧 approveTo/rejectTo（推导为 通过/驳回 两条）。 */
+function humanRoutes(node) {
+  if (Array.isArray(node.routes) && node.routes.length > 0) return node.routes;
+  const r = [];
+  if (node.approveTo) r.push({ label: '通过', to: node.approveTo });
+  if (node.rejectTo) r.push({ label: '驳回', to: node.rejectTo });
+  return r;
+}
+
+/**
+ * 图结构校验。返回 { ok, errors[] }。
+ */
+export function validateWorkflow(workflow) {
+  const errors = [];
+  if (!workflow || typeof workflow !== 'object') {
+    return { ok: false, errors: ['workflow 必须是对象'] };
+  }
+  const nodes = Array.isArray(workflow.nodes) ? workflow.nodes : [];
+  const edges = Array.isArray(workflow.edges) ? workflow.edges : [];
+
+  if (nodes.length === 0) errors.push('nodes 不能为空');
+
+  const ids = new Set();
+  const byId = new Map();
+  for (const n of nodes) {
+    if (!n || !n.id) { errors.push('存在缺少 id 的节点'); continue; }
+    if (ids.has(n.id)) errors.push(`节点 id 重复: ${n.id}`);
+    ids.add(n.id);
+    byId.set(n.id, n);
+    if (!NODE_TYPES.has(n.type)) errors.push(`节点 ${n.id} 的 type 非法: ${n.type}`);
+  }
+
+  // start / end 唯一
+  const starts = nodes.filter((n) => n.type === 'start');
+  const ends = nodes.filter((n) => n.type === 'end');
+  if (starts.length !== 1) errors.push(`必须有且仅有一个 start（当前 ${starts.length} 个）`);
+  if (ends.length !== 1) errors.push(`必须有且仅有一个 end（当前 ${ends.length} 个）`);
+
+  // 度数统计（用于孤立节点 / 网关拓扑）
+  const inDegree = new Map();
+  const outDegree = new Map();
+  for (const id of ids) { inDegree.set(id, 0); outDegree.set(id, 0); }
+
+  for (const e of edges) {
+    if (!e || !e.from || !e.to) { errors.push('存在缺少 from/to 的边'); continue; }
+    if (!byId.has(e.from)) errors.push(`边 from 指向不存在的节点: ${e.from}`);
+    if (!byId.has(e.to)) errors.push(`边 to 指向不存在的节点: ${e.to}`);
+    if (byId.has(e.from)) outDegree.set(e.from, (outDegree.get(e.from) || 0) + 1);
+    if (byId.has(e.to)) inDegree.set(e.to, (inDegree.get(e.to) || 0) + 1);
+  }
+
+  // 人工节点的去向目标：其"入边"来自人工决策、不写在 edges 里，豁免孤立检查
+  const humanTargets = new Set();
+  for (const n of nodes) {
+    if (n.type !== 'human') continue;
+    const routes = humanRoutes(n);
+    for (const r of routes) if (r.to) humanTargets.add(r.to);
+  }
+  // 孤立节点：除 start 外无入边（人工决策目标豁免）
+  for (const n of nodes) {
+    if (n.type === 'start') continue; // start 无入边正常
+    if ((inDegree.get(n.id) || 0) === 0 && !humanTargets.has(n.id)) errors.push(`节点 ${n.id} 无入边（孤立）`);
+  }
+
+  // 网关拓扑 / 人工节点去向
+  for (const n of nodes) {
+    if (n.type === 'gateway-xor') {
+      const out = edges.filter((e) => e.from === n.id);
+      if (out.length < 2) { errors.push(`排他网关 ${n.id} 出边数不足（需 ≥2）`); continue; }
+      if (!out.some((e) => e.default)) errors.push(`排他网关 ${n.id} 缺少 default 出边`);
+    }
+    if (n.type === 'gateway-and') {
+      const inN = inDegree.get(n.id) || 0;
+      const outN = outDegree.get(n.id) || 0;
+      const isSplit = outN > 1 && inN <= 1;
+      const isJoin = inN > 1 && outN <= 1;
+      if (!isSplit && !isJoin) {
+        errors.push(`并行网关 ${n.id} 拓扑非法：必须 split（多出单入）或 join（多入单出）`);
+      }
+    }
+    if (n.type === 'human') {
+      const routes = humanRoutes(n);
+      if (routes.length === 0) errors.push(`人工节点 ${n.id} 未配置任何去向（routes 或 approveTo/rejectTo）`);
+      const labels = new Set();
+      routes.forEach((r, i) => {
+        if (!r.label) errors.push(`人工节点 ${n.id} 的第 ${i + 1} 个去向缺少标签`);
+        else if (labels.has(r.label)) errors.push(`人工节点 ${n.id} 去向标签重复: ${r.label}`);
+        labels.add(r.label);
+        if (!r.to || !byId.has(r.to)) errors.push(`人工节点 ${n.id} 去向「${r.label || (i + 1)}」目标无效: ${r.to}`);
+      });
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+/** 评估结构化条件 when { field, op: eq|neq|in, value }，作用于上游输出。 */
+function matchCondition(upstream, when) {
+  if (!when || !when.field) return false;
+  const value = upstream[when.field];
+  switch (when.op) {
+    case 'eq': return value === when.value;
+    case 'neq': return value !== when.value;
+    case 'in': return Array.isArray(when.value) && when.value.includes(value);
+    default: return false;
+  }
+}
+
+/**
+ * 路由：给定当前节点 id + 上下文，返回下一个节点 id。
+ * - 普通节点（task/start）：唯一出边
+ * - XOR 网关：按 when 条件命中分支，否则 default；无 default 抛错
+ * - human 节点：返回 null（表示暂停，等待人工决策 approveTo/rejectTo）
+ */
+export function nextNode(workflow, nodeId, ctx = {}) {
+  const nodes = workflow.nodes || [];
+  const edges = workflow.edges || [];
+  const byId = new Map(nodes.map((n) => [n.id, n]));
+  const node = byId.get(nodeId);
+  if (!node) throw new Error(`节点不存在: ${nodeId}`);
+
+  const outEdges = edges.filter((e) => e.from === nodeId);
+
+  if (node.type === 'gateway-xor') {
+    const inEdge = edges.find((e) => e.to === nodeId);
+    const upstreamId = inEdge?.from;
+    const upstream = upstreamId ? (ctx[upstreamId] || {}) : {};
+    for (const e of outEdges) {
+      if (e.default) continue; // default 最后处理
+      if (e.when && matchCondition(upstream, e.when)) return e.to;
+    }
+    const def = outEdges.find((e) => e.default);
+    if (def) return def.to;
+    throw new Error(`排他网关 ${nodeId} 无匹配条件且无 default 边`);
+  }
+
+  if (node.type === 'human') {
+    return null; // 暂停等待人工决策
+  }
+
+  if (outEdges.length !== 1) {
+    throw new Error(`节点 ${nodeId} 出边数应为 1（当前 ${outEdges.length}）`);
+  }
+  return outEdges[0].to;
+}
+
+/**
+ * 数据流：解析节点显式参数映射（inputs: [{from, field|"*"}]）。
+ * 返回 { <from>: { <field>: value } }；字段/上游缺失抛错。
+ */
+export function resolveInputs(ctx, node) {
+  const inputs = Array.isArray(node.inputs) ? node.inputs : [];
+  if (inputs.length === 0) return {};
+  const result = {};
+  for (const ref of inputs) {
+    const src = ctx[ref.from];
+    if (src === undefined) throw new Error(`上游节点 ${ref.from} 无输出`);
+    if (ref.field === '*') {
+      result[ref.from] = src;
+    } else {
+      if (!(ref.field in src)) throw new Error(`上游 ${ref.from} 缺少字段 ${ref.field}`);
+      result[ref.from] = result[ref.from] || {};
+      result[ref.from][ref.field] = src[ref.field];
+    }
+  }
+  return result;
+}
+
+/**
+ * 保存前准备：校验 + 写 schemaVersion + revision 递增。
+ * 返回 { ok, errors? , workflow? }（纯函数，供 DevTaskStore.saveWorkflow 调用）。
+ */
+export function prepareWorkflowForSave(workflow, existing) {
+  if (!workflow || !workflow.id) return { ok: false, errors: ['workflow.id required'] };
+  const v = validateWorkflow(workflow);
+  if (!v.ok) return { ok: false, errors: v.errors };
+  workflow.schemaVersion = 2;
+  workflow.revision = (existing?.revision || 0) + 1;
+  return { ok: true, workflow };
+}

package/lib/graph.test.js

@@ -0,0 +1,274 @@
+/**
+ * dsh-knj-workflow 图工作流纯函数单元测试（node:test，零依赖）
+ * 覆盖：图校验 validateWorkflow、网关路由 nextNode、数据流 resolveInputs
+ * 运行：node --test lib/graph.test.js
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { validateWorkflow, nextNode, resolveInputs, prepareWorkflowForSave } from './graph.js';
+
+// 辅助：构造串行图
+function serialWorkflow(over = {}) {
+  return {
+    id: 'wf-serial', name: '串行', schemaVersion: 2, revision: 1,
+    inputs: [],
+    nodes: [
+      { id: 'start', type: 'start' },
+      { id: 'a', type: 'task', title: 'A', inputs: [], body: { prompt: 'A', mode: 'single', output: {} } },
+      { id: 'end', type: 'end' },
+    ],
+    edges: [
+      { from: 'start', to: 'a' },
+      { from: 'a', to: 'end' },
+    ],
+    ...over,
+  };
+}
+
+// 辅助：构造带 XOR 网关的图
+function xorWorkflow() {
+  return {
+    id: 'wf-xor', name: '分叉', schemaVersion: 2, revision: 1,
+    inputs: [],
+    nodes: [
+      { id: 'start', type: 'start' },
+      { id: 'analyze', type: 'task', title: '分析', inputs: [], body: { prompt: '', mode: 'single', output: {} } },
+      { id: 'gw', type: 'gateway-xor', title: '复杂度' },
+      { id: 'design', type: 'task', title: '设计', inputs: [], body: { prompt: '', mode: 'single', output: {} } },
+      { id: 'implement', type: 'task', title: '编码', inputs: [], body: { prompt: '', mode: 'single', output: {} } },
+      { id: 'end', type: 'end' },
+    ],
+    edges: [
+      { from: 'start', to: 'analyze' },
+      { from: 'analyze', to: 'gw' },
+      { from: 'gw', to: 'design', when: { field: 'complexity', op: 'eq', value: 'high' } },
+      { from: 'gw', to: 'implement', when: { field: 'complexity', op: 'eq', value: 'low' } },
+      { from: 'gw', to: 'design', default: true },
+      { from: 'design', to: 'end' },
+      { from: 'implement', to: 'end' },
+    ],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// validateWorkflow
+// ---------------------------------------------------------------------------
+test('validateWorkflow: 合法串行图通过', () => {
+  const r = validateWorkflow(serialWorkflow());
+  assert.equal(r.ok, true, JSON.stringify(r.errors));
+  assert.deepEqual(r.errors, []);
+});
+
+test('validateWorkflow: 缺 start 报错', () => {
+  const wf = serialWorkflow();
+  wf.nodes = wf.nodes.filter((n) => n.type !== 'start');
+  const r = validateWorkflow(wf);
+  assert.equal(r.ok, false);
+  assert.ok(r.errors.some((e) => /start/.test(e)), JSON.stringify(r.errors));
+});
+
+test('validateWorkflow: 缺 end 报错', () => {
+  const wf = serialWorkflow();
+  wf.nodes = wf.nodes.filter((n) => n.type !== 'end');
+  const r = validateWorkflow(wf);
+  assert.equal(r.ok, false);
+  assert.ok(r.errors.some((e) => /end/.test(e)));
+});
+
+test('validateWorkflow: 两个 start 报错', () => {
+  const wf = serialWorkflow();
+  wf.nodes.push({ id: 'start2', type: 'start' });
+  const r = validateWorkflow(wf);
+  assert.equal(r.ok, false);
+  assert.ok(r.errors.some((e) => /start/.test(e)));
+});
+
+test('validateWorkflow: 节点 id 重复报错', () => {
+  const wf = serialWorkflow();
+  wf.nodes.push({ id: 'a', type: 'task', title: 'A2', inputs: [], body: { prompt: '', mode: 'single', output: {} } });
+  const r = validateWorkflow(wf);
+  assert.equal(r.ok, false);
+  assert.ok(r.errors.some((e) => /重复|duplicate|unique/.test(e)), JSON.stringify(r.errors));
+});
+
+test('validateWorkflow: 边指向不存在节点报错', () => {
+  const wf = serialWorkflow();
+  wf.edges.push({ from: 'a', to: 'ghost' });
+  const r = validateWorkflow(wf);
+  assert.equal(r.ok, false);
+  assert.ok(r.errors.some((e) => /ghost/.test(e)));
+});
+
+test('validateWorkflow: 孤立节点（非 start/end 无入边）报错', () => {
+  const wf = serialWorkflow();
+  wf.nodes.push({ id: 'orphan', type: 'task', title: '孤儿', inputs: [], body: { prompt: '', mode: 'single', output: {} } });
+  const r = validateWorkflow(wf);
+  assert.equal(r.ok, false);
+  assert.ok(r.errors.some((e) => /orphan/.test(e)));
+});
+
+test('validateWorkflow: 非法节点 type 报错', () => {
+  const wf = serialWorkflow();
+  wf.nodes.push({ id: 'x', type: 'bogus', title: 'X' });
+  const r = validateWorkflow(wf);
+  assert.equal(r.ok, false);
+});
+
+test('validateWorkflow: XOR 网关无 default 边报错', () => {
+  const wf = xorWorkflow();
+  wf.edges = wf.edges.filter((e) => !(e.from === 'gw' && e.default));
+  const r = validateWorkflow(wf);
+  assert.equal(r.ok, false);
+  assert.ok(r.errors.some((e) => /default/.test(e)), JSON.stringify(r.errors));
+});
+
+test('validateWorkflow: XOR 网关有 default 边通过', () => {
+  const r = validateWorkflow(xorWorkflow());
+  assert.equal(r.ok, true, JSON.stringify(r.errors));
+});
+
+// ---------------------------------------------------------------------------
+// nextNode（路由）
+// ---------------------------------------------------------------------------
+test('nextNode: 串行普通节点走唯一出边', () => {
+  const wf = serialWorkflow();
+  assert.equal(nextNode(wf, 'start', {}), 'a');
+  assert.equal(nextNode(wf, 'a', {}), 'end');
+});
+
+test('nextNode: XOR 网关命中条件走对应分支', () => {
+  const wf = xorWorkflow();
+  // ctx 存上游节点输出；XOR 网关的 when.field 相对唯一上游（analyze）
+  const ctx = { analyze: { complexity: 'high' } };
+  assert.equal(nextNode(wf, 'gw', ctx), 'design');
+  assert.equal(nextNode(wf, 'gw', { analyze: { complexity: 'low' } }), 'implement');
+});
+
+test('nextNode: XOR 网关条件都不命中走 default 边', () => {
+  const wf = xorWorkflow();
+  assert.equal(nextNode(wf, 'gw', { analyze: { complexity: 'medium' } }), 'design'); // default 指向 design
+});
+
+test('nextNode: XOR 网关无 default 且不命中抛错', () => {
+  const wf = xorWorkflow();
+  wf.edges = wf.edges.filter((e) => !(e.from === 'gw' && e.default));
+  assert.throws(() => nextNode(wf, 'gw', { analyze: { complexity: 'medium' } }), /default|no path/i);
+});
+
+// ---------------------------------------------------------------------------
+// resolveInputs（数据流：显式参数映射）
+// ---------------------------------------------------------------------------
+test('resolveInputs: 引用存在字段返回对应值', () => {
+  const node = { id: 'b', type: 'task', inputs: [{ from: 'a', field: 'x' }] };
+  const ctx = { a: { x: 1, y: 2 } };
+  assert.deepEqual(resolveInputs(ctx, node), { a: { x: 1 } });
+});
+
+test('resolveInputs: field="*" 返回上游全部输出', () => {
+  const node = { id: 'b', type: 'task', inputs: [{ from: 'a', field: '*' }] };
+  const ctx = { a: { x: 1, y: 2 } };
+  assert.deepEqual(resolveInputs(ctx, node), { a: { x: 1, y: 2 } });
+});
+
+test('resolveInputs: 引用不存在的字段抛错', () => {
+  const node = { id: 'b', type: 'task', inputs: [{ from: 'a', field: 'missing' }] };
+  const ctx = { a: { x: 1 } };
+  assert.throws(() => resolveInputs(ctx, node), /missing/);
+});
+
+test('resolveInputs: 引用不存在的上游节点抛错', () => {
+  const node = { id: 'b', type: 'task', inputs: [{ from: 'ghost', field: 'x' }] };
+  const ctx = { a: { x: 1 } };
+  assert.throws(() => resolveInputs(ctx, node), /ghost/);
+});
+
+test('resolveInputs: 无 inputs 返回空对象', () => {
+  const node = { id: 'b', type: 'task', inputs: [] };
+  assert.deepEqual(resolveInputs({}, node), {});
+});
+
+// ---------------------------------------------------------------------------
+// prepareWorkflowForSave（保存前准备：校验 + revision 递增）
+// ---------------------------------------------------------------------------
+test('prepareWorkflowForSave: 首次保存 revision=1，再次递增', () => {
+  const r1 = prepareWorkflowForSave(serialWorkflow(), null);
+  assert.equal(r1.ok, true);
+  assert.equal(r1.workflow.revision, 1);
+  const r2 = prepareWorkflowForSave(serialWorkflow(), { revision: 3 });
+  assert.equal(r2.workflow.revision, 4);
+});
+
+test('prepareWorkflowForSave: 非法图返回 errors', () => {
+  const wf = serialWorkflow();
+  wf.nodes = wf.nodes.filter((n) => n.type !== 'end');
+  const r = prepareWorkflowForSave(wf, null);
+  assert.equal(r.ok, false);
+  assert.ok(r.errors.length > 0);
+});
+
+test('prepareWorkflowForSave: 缺 id 返回错误', () => {
+  const r = prepareWorkflowForSave({ nodes: [], edges: [] }, null);
+  assert.equal(r.ok, false);
+  assert.ok(r.errors.some((e) => /id/.test(e)));
+});
+
+test('validateWorkflow: human approveTo/rejectTo 目标（无 edges 入边）不报孤立', () => {
+  const wf = {
+    id: 'wf-human-end', nodes: [
+      { id: 'start', type: 'start' },
+      { id: 'verify', type: 'task', title: '验证', inputs: [], body: { prompt: '', mode: 'single', output: {} } },
+      { id: 'review', type: 'human', title: '评审', displayFrom: 'verify', approveTo: 'end', rejectTo: 'fix' },
+      { id: 'fix', type: 'task', title: '修复', inputs: [], body: { prompt: '', mode: 'single', output: {} } },
+      { id: 'end', type: 'end' },
+    ],
+    edges: [
+      { from: 'start', to: 'verify' },
+      { from: 'verify', to: 'review' },
+    ],
+  };
+  const r = validateWorkflow(wf);
+  assert.equal(r.ok, true, JSON.stringify(r.errors));
+});
+
+test('validateWorkflow: human 未配置通过/驳回去向 → 报错', () => {
+  const wf = {
+    id: 'wf-human-missing', nodes: [
+      { id: 'start', type: 'start' },
+      { id: 'verify', type: 'task', title: '验证', inputs: [], body: { prompt: '', mode: 'single', output: {} } },
+      { id: 'review', type: 'human', title: '设计评审', displayFrom: 'verify', approveTo: '', rejectTo: '' },
+      { id: 'end', type: 'end' },
+    ],
+    edges: [
+      { from: 'start', to: 'verify' },
+      { from: 'verify', to: 'review' },
+    ],
+  };
+  const r = validateWorkflow(wf);
+  assert.equal(r.ok, false);
+  assert.ok(r.errors.some((e) => e.includes('未配置任何去向')), JSON.stringify(r.errors));
+});
+
+test('validateWorkflow: human 多去向 routes 校验（目标无效 / 标签重复 / 缺标签）', () => {
+  const wf = {
+    id: 'wf-human-routes', nodes: [
+      { id: 'start', type: 'start' },
+      { id: 'verify', type: 'task', title: '验证', inputs: [], body: { prompt: '', mode: 'single', output: {} } },
+      { id: 'review', type: 'human', title: '设计评审', displayFrom: 'verify', routes: [
+        { label: '通过', to: 'end' },
+        { label: '驳回', to: 'nope' },       // 目标不存在
+        { label: '驳回', to: 'end' },        // 标签重复
+        { label: '', to: 'end' },            // 缺标签
+      ] },
+      { id: 'end', type: 'end' },
+    ],
+    edges: [
+      { from: 'start', to: 'verify' },
+      { from: 'verify', to: 'review' },
+    ],
+  };
+  const r = validateWorkflow(wf);
+  assert.equal(r.ok, false);
+  assert.ok(r.errors.some((e) => e.includes('目标无效: nope')), JSON.stringify(r.errors));
+  assert.ok(r.errors.some((e) => e.includes('去向标签重复: 驳回')), JSON.stringify(r.errors));
+  assert.ok(r.errors.some((e) => e.includes('缺少标签')), JSON.stringify(r.errors));
+});

package/lib/index.d.ts

@@ -0,0 +1,8 @@
+export declare const name: string;
+export declare const inject: string[];
+export declare const Config: import('@deepseek-ai/schemastery').Schema<{
+  dataRoot: string;
+  httpPrefix: string;
+  orchestratorScript: string;
+}>;
+export declare function apply(ctx: any, config: any): void;