@sakki_chin/dsh-codex-orchestrate 1.0.0

package/server/turn-reduce.js

@@ -0,0 +1,77 @@
+/* ============================================================
+ * turn-reduce.js — codex 事件 → 节点终局判定（纯函数）
+ * 从 codex-runner 抽出的判定逻辑，唯一目的是可单测：
+ * 「已自愈的传输恢复」不能把一个成功 turn 判成失败。
+ *
+ * 实测事件序列（本机 codex 0.153.4，WebSocket 不可达时）：
+ *   thread.started → turn.started → error("Reconnecting... 2/5 (request timed out)") ×4
+ *   → item.completed(error: "Falling back from WebSockets to HTTPS transport")
+ *   → item.completed(agent_message) → turn.completed(usage)
+ * 这些 error 是**恢复过程**的通知，不是失败；终局只认 turn.completed / turn.failed，
+ * 其余 error 只在 turn 没有正常完成时才充当失败原因。
+ * ============================================================ */
+'use strict';
+
+/** 自愈性传输通知（重连/N-of-M 退避）——出现它不等于失败。 */
+const TRANSIENT_TRANSPORT_NOTICE = /^Reconnecting\.\.\.|^Falling back from WebSockets/i;
+
+function isTransientTransportNotice(message) {
+  return TRANSIENT_TRANSPORT_NOTICE.test(String(message || '').trim());
+}
+
+/** 新建一轮归约状态。 */
+function createTurnState() {
+  return {
+    finalMessage: null, usage: null,
+    turnCompleted: false, turnError: null, itemError: null,
+    transportNotice: null,   // 最近一条自愈性传输通知（诊断用，不构成失败）
+  };
+}
+
+/**
+ * 应用一个 codex 事件。
+ * @param {object} state 由 createTurnState() 建立、逐事件传入
+ * @param {object} event @openai/codex-sdk 的 streamed event（不修改入参）
+ * @param {(message:string)=>string} explain 错误文案翻译（注入以便单测）
+ * @returns {object} 新状态（纯函数：不修改传入的 state）
+ */
+function reduceEvent(state, event, explain = message => String(message || '')) {
+  const next = { ...state };
+  if (event.type === 'turn.completed') {
+    next.usage = event.usage || null;
+    next.turnCompleted = true;
+    return next;
+  }
+  if (event.type === 'turn.failed') {
+    next.turnError = explain(event.error?.message || 'turn failed');
+    return next;
+  }
+  if (event.type === 'error') {
+    /* 重连中的 error 事件只是传输层通知：记诊断，不记失败 */
+    if (isTransientTransportNotice(event.message)) next.transportNotice = event.message;
+    else next.turnError = explain(event.message);
+    return next;
+  }
+  if (event.type === 'item.started' || event.type === 'item.updated' || event.type === 'item.completed') {
+    if (event.item?.type === 'agent_message') next.finalMessage = event.item.text;
+    if (event.item?.type === 'error' && event.item.message) {
+      if (isTransientTransportNotice(event.item.message)) next.transportNotice = event.item.message;
+      else if (!next.itemError) next.itemError = explain(event.item.message);
+    }
+  }
+  return next;
+}
+
+/**
+ * 由归约状态得出节点结果。
+ * 优先级：turn.failed / 真实 error 事件 > （turn 未完成时的 item 级 error）> 成功。
+ * @returns {{status:'completed'|'failed', finalMessage:string|null, usage:object|null, failure?:string}}
+ */
+function finalizeTurn(state) {
+  const failure = state.turnError || (state.turnCompleted ? null : state.itemError);
+  return failure
+    ? { status: 'failed', finalMessage: state.finalMessage, usage: state.usage, failure }
+    : { status: 'completed', finalMessage: state.finalMessage, usage: state.usage };
+}
+
+module.exports = { createTurnState, reduceEvent, finalizeTurn, isTransientTransportNotice };

package/server/turn-reduce.test.cjs

@@ -0,0 +1,96 @@
+/* eslint-disable no-console */
+/* turn-reduce 单测：codex 事件的终局判定。
+ * 重点是真实遇到过的坑：WebSocket 超时→HTTPS 回退会以 error 条目出现，
+ * 但 turn 随后正常完成——不能把已自愈的传输恢复判成节点失败。 */
+'use strict';
+const assert = require('node:assert');
+const { createTurnState, reduceEvent, finalizeTurn } = require('./turn-reduce.js');
+const { explainFailure } = require('./codex-runner.js');
+
+/** 按顺序喂事件，返回终局结果。 */
+function run(events, explain) {
+  return finalizeTurn(events.reduce((state, event) => reduceEvent(state, event, explain), createTurnState()));
+}
+
+(async () => {
+  /* 1. 正常完成 */
+  {
+    const result = run([
+      { type: 'item.completed', item: { type: 'agent_message', text: '答案' } },
+      { type: 'turn.completed', usage: { input_tokens: 3, output_tokens: 7 } },
+    ]);
+    assert.deepStrictEqual(result, { status: 'completed', finalMessage: '答案', usage: { input_tokens: 3, output_tokens: 7 } });
+    console.log('✓ 正常完成 → completed');
+  }
+
+  /* 2. 已自愈的传输恢复 + 正常完成 → completed（真实回归：实测事件序列） */
+  {
+    const result = run([
+      { type: 'turn.started' },
+      { type: 'error', message: 'Reconnecting... 2/5 (request timed out)' },
+      { type: 'error', message: 'Reconnecting... 3/5 (request timed out)' },
+      { type: 'error', message: 'Reconnecting... 4/5 (request timed out)' },
+      { type: 'error', message: 'Reconnecting... 5/5 (request timed out)' },
+      { type: 'item.completed', item: { type: 'error', message: 'Falling back from WebSockets to HTTPS transport. request timed out' } },
+      { type: 'item.completed', item: { type: 'agent_message', text: '该目录是 Git 仓库，当前分支为 main' } },
+      { type: 'turn.completed', usage: { input_tokens: 41183, output_tokens: 190 } },
+    ]);
+    assert.strictEqual(result.status, 'completed', '自愈的传输恢复不得判成失败');
+    assert.strictEqual(result.finalMessage, '该目录是 Git 仓库，当前分支为 main');
+    assert.strictEqual(result.usage.output_tokens, 190);
+    console.log('✓ 传输恢复（重连 error 事件 + 回退条目）+ turn.completed → completed');
+  }
+
+  /* 2b. 传输通知保留为诊断信息，不污染 error 字段 */
+  {
+    const state = reduceEvent(
+      createTurnState(),
+      { type: 'error', message: 'Reconnecting... 5/5 (request timed out)' },
+    );
+    assert.strictEqual(state.turnError, null);
+    assert.match(state.transportNotice, /Reconnecting/);
+    console.log('✓ 传输通知记入 transportNotice 而非 turnError');
+  }
+
+  /* 3. turn.failed → failed，并且带原因（订阅登录拒绝 slug 的场景） */
+  {
+    const result = run([
+      { type: 'turn.failed', error: { message: '{"detail":"The \'gpt-5-codex\' model is not supported when using Codex with a ChatGPT account."}' } },
+    ], message => explainFailure(message, 'gpt-5-codex'));
+    assert.strictEqual(result.status, 'failed');
+    assert.match(result.failure, /not supported when using Codex with a ChatGPT account/);
+    assert.match(result.failure, /gpt-5\.6-sol/, '报错要给出可操作建议（缺省模型）');
+    console.log('✓ turn.failed → failed 且给出可操作建议');
+  }
+
+  /* 4. 只有 item 级 error、turn 从未完成 → failed（不给静默 completed） */
+  {
+    const result = run([
+      { type: 'item.completed', item: { type: 'error', message: 'stream closed unexpectedly' } },
+    ]);
+    assert.strictEqual(result.status, 'failed');
+    assert.match(result.failure, /stream closed unexpectedly/);
+    console.log('✓ 无 turn.completed 的 error 条目 → failed');
+  }
+
+  /* 5. 流内 error 事件优先于 item 级 error */
+  {
+    const result = run([
+      { type: 'item.completed', item: { type: 'error', message: 'item 级噪音' } },
+      { type: 'error', message: 'stream 级失败' },
+      { type: 'turn.completed' },
+    ]);
+    assert.strictEqual(result.status, 'failed');
+    assert.match(result.failure, /stream 级失败/);
+    console.log('✓ turn 级 error 覆盖 item 级噪音');
+  }
+
+  /* 6. 认证失效的报错翻译给出 `codex login` */
+  {
+    const translated = explainFailure('401 unauthorized', 'gpt-5.6-sol');
+    assert.match(translated, /codex login/);
+    console.log('✓ 认证失效报错指向 codex login');
+  }
+
+  console.log('\nturn 判定测试通过');
+})().catch(error => { console.error(error); process.exit(1); });

package/server/validate.js

@@ -0,0 +1,263 @@
+/* ============================================================
+ * validate.js — YAML 解析 + JSON Schema 校验 + 语义校验
+ * 依赖策略：优先使用 DSH 自带的 yaml 包（经 DSH_CODEX_MODULES 指向），
+ * 不可用时回退到内置的子集解析器（覆盖 workflow schema 用到的语法：
+ * 块映射 / 块序列 / 内联数组 / 字面量块 | / 引号与裸标量）。
+ * ============================================================ */
+'use strict';
+
+const { createRequire } = require('node:module');
+
+function loadYamlParser() {
+  const dir = process.env.DSH_CODEX_MODULES;
+  if (dir) {
+    try {
+      const req = createRequire(dir + '/');
+      const yaml = req('yaml');
+      return text => yaml.parse(text);
+    } catch { /* fall through */ }
+  }
+  return parseYamlSubset;
+}
+
+/* ---------------- 内置 YAML 子集解析器 ---------------- */
+
+function parseYamlSubset(text) {
+  const lines = [];
+  let index = 0;
+  for (const raw of String(text).split(/\r?\n/)) {
+    const line = raw.replace(/\t/g, '  ');
+    const stripped = line.replace(/(^|\s)#.*$/, (m, p, offset, s) =>
+      /["']/.test(s.slice(0, offset).split('#')[0]) ? m : '');
+    if (!stripped.trim()) continue;
+    const indent = stripped.match(/^ */)[0].length;
+    lines.push({ indent, text: stripped.trim(), n: ++index });
+  }
+  let pos = 0;
+
+  function parseBlock(minIndent) {
+    if (pos >= lines.length) return null;
+    const { indent } = lines[pos];
+    if (indent < minIndent) return null;
+    if (lines[pos].text.startsWith('- ') || lines[pos].text === '-') return parseSeq(indent);
+    return parseMap(indent);
+  }
+
+  function parseSeq(indent) {
+    const items = [];
+    while (pos < lines.length && lines[pos].indent === indent &&
+           (lines[pos].text.startsWith('- ') || lines[pos].text === '-')) {
+      const body = lines[pos].text === '-' ? '' : lines[pos].text.slice(2);
+      if (!body) { pos++; items.push(parseBlock(indent + 1)); continue; }
+      // "- key: value" 就地开启一个映射
+      const kv = matchKey(body);
+      if (kv) {
+        const map = {};
+        assignScalar(map, kv.key, kv.rest, lines[pos].n);
+        const itemIndent = lines[pos].indent + 2;
+        pos++;
+        mergeMap(map, itemIndent);
+        items.push(map);
+      } else {
+        items.push(parseScalar(body));
+        pos++;
+      }
+    }
+    return items;
+  }
+
+  function parseMap(indent) {
+    const map = {};
+    mergeMap(map, indent);
+    return map;
+  }
+
+  function mergeMap(map, indent) {
+    while (pos < lines.length && lines[pos].indent === indent && !lines[pos].text.startsWith('- ')) {
+      const kv = matchKey(lines[pos].text);
+      if (!kv) throw new SyntaxError(`第 ${lines[pos].n} 行：期望 "key: value"，得到 "${lines[pos].text}"`);
+      if (kv.rest === '' || kv.rest === '|') {
+        pos++;
+        if (kv.rest === '|') map[kv.key] = parseLiteralBlock(indent);
+        else {
+          const child = parseBlock(indent + 1);
+          map[kv.key] = child === null ? null : child;
+        }
+      } else {
+        assignScalar(map, kv.key, kv.rest, lines[pos].n);
+        pos++;
+      }
+    }
+  }
+
+  function parseLiteralBlock(indent) {
+    const out = [];
+    let blockIndent = null;
+    while (pos < lines.length && lines[pos].indent > indent) {
+      if (blockIndent === null) blockIndent = lines[pos].indent;
+      out.push(' '.repeat(Math.max(0, lines[pos].indent - blockIndent)) + lines[pos].text);
+      pos++;
+    }
+    return out.join('\n');
+  }
+
+  function matchKey(text) {
+    const m = text.match(/^([A-Za-z_][\w.-]*)\s*:(?:\s+(.*))?$/);
+    if (!m) return null;
+    return { key: m[1], rest: m[2] === undefined ? '' : m[2].trim() };
+  }
+
+  function assignScalar(map, key, raw, lineNo) {
+    if (raw === '|') return; // 由调用方处理
+    if (raw.startsWith('|')) throw new SyntaxError(`第 ${lineNo} 行：字面量块 "|" 后不能有内容`);
+    map[key] = parseScalar(raw);
+  }
+
+  function parseScalar(raw) {
+    raw = raw.trim();
+    if (raw.startsWith('[') && raw.endsWith(']')) {
+      const inner = raw.slice(1, -1).trim();
+      return inner ? inner.split(',').map(part => parseScalar(part)) : [];
+    }
+    if ((raw.startsWith('"') && raw.endsWith('"')) || (raw.startsWith("'") && raw.endsWith("'"))) {
+      return raw.slice(1, -1);
+    }
+    if (raw === 'true') return true;
+    if (raw === 'false') return false;
+    if (raw === 'null' || raw === '~') return null;
+    if (/^-?\d+$/.test(raw)) return parseInt(raw, 10);
+    if (/^-?\d+\.\d+$/.test(raw)) return parseFloat(raw);
+    return raw;
+  }
+
+  const doc = parseBlock(0);
+  if (pos !== lines.length) throw new SyntaxError(`第 ${lines[pos].n} 行：无法解析的缩进或语法 "${lines[pos].text}"`);
+  return doc;
+}
+
+/* ---------------- JSON Schema 子集校验器 ---------------- */
+/* 支持：type/const/enum/required/properties/additionalProperties/items/
+   minItems/maxItems/uniqueItems/minLength/maxLength/minimum/maximum/pattern/
+   allOf/if-then/$ref(仅 #/$defs/...) */
+
+function validateAgainstSchema(value, schema, root, path = '') {
+  const errors = [];
+  const at = p => (p ? p : '(root)');
+
+  if (schema.$ref) {
+    const target = schema.$ref.replace(/^#\/?/, '').split('/').reduce((acc, key) => acc?.[key], root);
+    if (target) errors.push(...validateAgainstSchema(value, target, root, path));
+    /* JSON Schema 2020-12 允许 $ref 与 required 等关键字并列；引用约束与
+     * 本地约束都必须生效。workflow 创建节点借此在 nodeMutation 基础上
+     * 追加 prompt 必填，而 nodePatch 的既有节点更新可以只传变化字段。 */
+    schema = { ...schema };
+    delete schema.$ref;
+  }
+  if (schema.allOf) for (const sub of schema.allOf) errors.push(...validateAgainstSchema(value, sub, root, path));
+  if (schema.if) {
+    const ifErrors = validateAgainstSchema(value, schema.if, root, path);
+    if (ifErrors.length === 0 && schema.then) errors.push(...validateAgainstSchema(value, schema.then, root, path));
+    if (ifErrors.length > 0 && schema.else) errors.push(...validateAgainstSchema(value, schema.else, root, path));
+  }
+  if (schema.const !== undefined && value !== schema.const) errors.push(`${at(path)}：必须为 ${JSON.stringify(schema.const)}`);
+  if (schema.enum && !schema.enum.includes(value)) errors.push(`${at(path)}：必须为 ${schema.enum.map(v => JSON.stringify(v)).join(' / ')} 之一`);
+  if (schema.type) {
+    const typeOk = {
+      object: v => v && typeof v === 'object' && !Array.isArray(v),
+      array: Array.isArray,
+      string: v => typeof v === 'string',
+      integer: v => Number.isInteger(v),
+      number: v => typeof v === 'number',
+      boolean: v => typeof v === 'boolean',
+      null: v => v === null,
+    }[schema.type](value);
+    if (!typeOk) { errors.push(`${at(path)}：类型必须为 ${schema.type}，实际 ${Array.isArray(value) ? 'array' : typeof value}`); return errors; }
+  }
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    for (const key of schema.required || []) {
+      if (!(key in value)) errors.push(`${at(path)}：缺少必填字段 "${key}"`);
+    }
+    const props = schema.properties || {};
+    for (const key of Object.keys(value)) {
+      if (props[key]) errors.push(...validateAgainstSchema(value[key], props[key], root, path ? `${path}.${key}` : key));
+      else if (schema.additionalProperties === false) errors.push(`${at(path)}：不允许的未知字段 "${key}"`);
+    }
+  }
+  if (Array.isArray(value)) {
+    if (schema.minItems !== undefined && value.length < schema.minItems) errors.push(`${at(path)}：至少 ${schema.minItems} 项`);
+    if (schema.maxItems !== undefined && value.length > schema.maxItems) errors.push(`${at(path)}：至多 ${schema.maxItems} 项`);
+    if (schema.uniqueItems && new Set(value.map(v => JSON.stringify(v))).size !== value.length) errors.push(`${at(path)}：存在重复项`);
+    if (schema.items) value.forEach((item, i) => errors.push(...validateAgainstSchema(item, schema.items, root, `${path}[${i}]`)));
+  }
+  if (typeof value === 'string') {
+    if (schema.minLength !== undefined && value.length < schema.minLength) errors.push(`${at(path)}：长度至少 ${schema.minLength}`);
+    if (schema.maxLength !== undefined && value.length > schema.maxLength) errors.push(`${at(path)}：长度至多 ${schema.maxLength}`);
+    if (schema.pattern && !new RegExp(schema.pattern).test(value)) errors.push(`${at(path)}：不匹配模式 ${schema.pattern}`);
+  }
+  if (typeof value === 'number') {
+    if (schema.minimum !== undefined && value < schema.minimum) errors.push(`${at(path)}：最小值 ${schema.minimum}`);
+    if (schema.maximum !== undefined && value > schema.maximum) errors.push(`${at(path)}：最大值 ${schema.maximum}`);
+  }
+  return errors;
+}
+
+/* ---------------- 语义校验（schema 之外的业务不变量） ---------------- */
+
+function semanticCheck(doc, knownIds = [], { allowExternalDeps = false } = {}) {
+  const errors = [];
+  const nodes = doc.nodes || [];
+  const remove = doc.remove || [];
+  if (doc.kind === 'nodePatch') {
+    if (!nodes.length && !remove.length) errors.push('nodePatch 至少需要 nodes 或 remove 之一');
+    const removed = new Set(remove);
+    for (const n of nodes) {
+      if (removed.has(n.id)) errors.push(`节点 "${n.id}" 不能在同一补丁中同时修改和删除`);
+      if (Object.keys(n).every(key => key === 'id')) errors.push(`节点 "${n.id}" 没有任何需要修改的字段`);
+    }
+  }
+  if (doc.kind === 'workflow' && remove.length) errors.push('workflow 创建时不允许字段 "remove"');
+  if (doc.kind === 'workflowQuery') {
+    for (const field of ['title', 'goal', 'concurrency', 'nodes', 'remove']) {
+      if (doc[field] !== undefined) errors.push(`workflowQuery 不允许字段 "${field}"`);
+    }
+  }
+  const known = new Set([...knownIds, ...nodes.map(n => n.id)]);
+  const seen = new Set();
+  for (const n of nodes) {
+    if (seen.has(n.id)) errors.push(`节点 "${n.id}" 重复定义`);
+    seen.add(n.id);
+  }
+  for (const n of nodes) {
+    for (const dep of n.dependsOn || []) {
+      if (dep === n.id) errors.push(`节点 "${n.id}" 不能依赖自身`);
+      else if (!known.has(dep) && !allowExternalDeps) errors.push(`节点 "${n.id}" 依赖了未定义的 "${dep}"`);
+    }
+  }
+  // 环检测：DFS 三色标记（仅文档内部边；外部引用由 orchestrator 合并图检测）
+  const color = new Map(nodes.map(n => [n.id, 0]));
+  const graph = new Map(nodes.map(n => [n.id, n.dependsOn || []]));
+  const visit = id => {
+    if (color.get(id) === 1) { errors.push(`存在依赖环：包含节点 "${id}"`); return; }
+    if (color.get(id) === 2) return;
+    color.set(id, 1);
+    for (const dep of graph.get(id) || []) if (color.has(dep)) visit(dep);
+    color.set(id, 2);
+  };
+  for (const n of nodes) visit(n.id);
+  return errors;
+}
+
+/* ---------------- 对外入口 ---------------- */
+
+function parseWorkflowYaml(text, schema, options = {}) {
+  const parse = loadYamlParser();
+  const doc = parse(text);
+  if (!doc || typeof doc !== 'object') throw new Error('YAML 文档必须是一个映射（对象）');
+  const schemaErrors = validateAgainstSchema(doc, schema, schema);
+  if (schemaErrors.length) throw new Error('schema 校验失败：\n  - ' + schemaErrors.join('\n  - '));
+  const semanticErrors = semanticCheck(doc, options.knownIds || [], { allowExternalDeps: Boolean(options.allowExternalDeps) });
+  if (semanticErrors.length) throw new Error('语义校验失败：\n  - ' + semanticErrors.join('\n  - '));
+  return doc;
+}
+
+module.exports = { parseWorkflowYaml, parseYamlSubset, validateAgainstSchema, semanticCheck };