dsh-plugin-agentflow 0.3.1 → 0.4.1

package/lib/observe.js

@@ -0,0 +1,286 @@
+/**
+ * 观察器（阶段 1）：只记录，不拦不改。
+ *
+ * 为什么先观察：在动手做「强制工作流」之前，得先看清模型实际怎么走 ——
+ * 每步进了哪些消息、调了哪个工具、参数长什么样、成功还是被拒、哪一步收工。
+ * 没这份数据就设计白名单，等于闭着眼画闸门。
+ *
+ * 挂在三个官方钩子上（都是 waterfall/serial，回调必须原样把下游结果返回）：
+ *   agent/pre-step         看每一步的输入与决策
+ *   tools/post-execute     看每一次工具调用（含被 deny 的，deny 也过这条管线）
+ *   agent/turn-stopping    看模型在哪里收工
+ *
+ * 落盘：`<root>/<agent>.jsonl`，一行一个事件，方便 jq 或脚本直接看。
+ *    {t:'step', turn, step, msgs:[{kind,form,chars}], decision:{kind,msgs}}
+ *    {t:'tool', turn, step, name, args, ms, isError, text}
+ *    {t:'stop', turn}
+ *
+ * 纪律：所有写入 fire-and-forget，任何异常只 warn。
+ * 观察器坏了不能连累对话 —— 钩子里抛错会直接结束当前 turn。
+ *
+ * @module lib/observe
+ */
+
+import fsp from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+/** 单条文本/参数最多记多少字符：够判断意图，又不至于把日志灌爆。 */
+const MAX_TEXT = 240;
+/** 单个 agent 最多记多少行，防止长会话把盘写满。 */
+const MAX_LINES = 5000;
+
+/** 默认落盘目录，跟画布数据放一起。 */
+const DEFAULT_ROOT = path.join(os.homedir(), '.dsh', 'agent-flow-data', 'observe');
+
+/** 把任意值压成一行可读文本；循环引用/巨对象都不许抛。 */
+function asText(value) {
+  if (typeof value === 'string') return value;
+  try {
+    return JSON.stringify(value);
+  } catch {
+    try {
+      return String(value);
+    } catch {
+      return '(unserializable)';
+    }
+  }
+}
+
+/** 截断到 MAX_TEXT（或指定长度），末尾加省略号。 */
+function clip(value, limit = MAX_TEXT) {
+  const text = asText(value);
+  return text.length > limit ? `${text.slice(0, limit)}…` : text;
+}
+
+/** 一条消息里所有 text block 的字符数 —— 只看体量，不存正文。 */
+function messageChars(message) {
+  const content = message && Array.isArray(message.content) ? message.content : [];
+  let total = 0;
+  for (const block of content) {
+    if (block && typeof block.text === 'string') total += block.text.length;
+  }
+  return total;
+}
+
+/**
+ * 消息摘要：谁产的（source.kind）、什么形态（form）、多大。
+ * 不存正文 —— 对话内容留在 DSH 自己的 session log 里，这里只留形状。
+ */
+function describeMessages(messages) {
+  if (!Array.isArray(messages)) return [];
+  return messages.map((message) => ({
+    kind: message?.source?.kind ?? '?',
+    form: message?.source?.form,
+    chars: messageChars(message),
+  }));
+}
+
+/** 工具结果的可读摘要：优先纯文本内容，其次 value，最后错误信息。 */
+function describeResult(result) {
+  if (!result || typeof result !== 'object') return '';
+  if (Array.isArray(result.content)) {
+    const text = result.content
+      .map((block) => (block && typeof block.text === 'string' ? block.text : ''))
+      .join(' ')
+      .trim();
+    if (text) return text;
+  }
+  if (result.value !== undefined) return asText(result.value);
+  if (result.error && typeof result.error.message === 'string') return result.error.message;
+  return '';
+}
+
+/** 文件名安全化：agent id 是宿主给的，别让它逃出目录。 */
+function safeFileName(agentId) {
+  return String(agentId).replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 120) || 'agent';
+}
+
+/** agent 身份：本体 id 就是 session id。 */
+function agentKey(agent) {
+  return agent && agent.id !== undefined ? String(agent.id) : 'unknown';
+}
+
+/**
+ * 每 agent 一个 append 串行队列。
+ * 不串行的话并发工具调用会把行写乱（appendFile 本身原子，但顺序会漂）。
+ */
+class JsonlWriter {
+  constructor(root) {
+    this.root = root;
+    this.chains = new Map();
+    this.counts = new Map();
+    this.dirReady = null;
+  }
+
+  async ensureDir() {
+    if (this.dirReady === null) {
+      this.dirReady = fsp.mkdir(this.root, { recursive: true }).catch((err) => {
+        this.dirReady = null; // 允许下一行重试
+        throw err;
+      });
+    }
+    return this.dirReady;
+  }
+
+  /** 记一行。同步返回，绝不 await —— 钩子里不能因为落盘慢拖住对话。 */
+  append(agentId, event) {
+    const key = safeFileName(agentId);
+    const count = this.counts.get(key) ?? 0;
+    if (count >= MAX_LINES) return;
+    this.counts.set(key, count + 1);
+
+    const file = path.join(this.root, `${key}.jsonl`);
+    const line = `${JSON.stringify(event)}\n`;
+    const previous = this.chains.get(key) ?? Promise.resolve();
+    const next = previous
+      .then(async () => {
+        await this.ensureDir();
+        await fsp.appendFile(file, line);
+      })
+      .catch((err) => {
+        console.warn('[agentflow] 观察记录写失败（已忽略）：' + (err && err.message ? err.message : err));
+      });
+    this.chains.set(key, next);
+    return next;
+  }
+
+  /** 测试与卸载用：等所有在途写入落完。 */
+  async flush() {
+    await Promise.all([...this.chains.values()]);
+  }
+}
+
+/**
+ * 挂上观察器。
+ *
+ * @param {object} ctx 插件上下文（只用 ctx.on）
+ * @param {object} [options]
+ * @param {string} [options.root] 落盘目录，默认 `~/.dsh/agent-flow-data/observe`
+ * @param {(agentId: string, event: object) => void} [options.sink] 替代落盘（测试用）
+ * @returns {{ dispose: () => void, flush: () => Promise<void> }}
+ */
+export function startObserver(ctx, options = {}) {
+  // 没有 ctx.on 的宿主（极简嵌入、测试桩）不该让整个插件加载失败：
+  // 观察器只是旁路，缺了这个能力就当它不存在。
+  if (typeof ctx?.on !== 'function') {
+    console.warn('[agentflow] 宿主没有 ctx.on，观察器不启用');
+    return { dispose() {}, flush: async () => {} };
+  }
+
+  const writer = new JsonlWriter(options.root || DEFAULT_ROOT);
+  const sink = typeof options.sink === 'function' ? options.sink : null;
+  /** exec.token -> 真实执行耗时（由 tools/execute 记，post-execute 消费后删除）。 */
+  const timings = new Map();
+  /** 当前 agent 走到第几步 —— 工具调用本身不带 turn/step，得靠 pre-step 记住。 */
+  const position = new Map();
+  const disposers = [];
+
+  const write = (agentId, event) => {
+    if (sink) {
+      try {
+        sink(agentId, event);
+      } catch (err) {
+        console.warn('[agentflow] 观察 sink 失败（已忽略）：' + (err && err.message ? err.message : err));
+      }
+      return;
+    }
+    void writer.append(agentId, event);
+  };
+
+  // ---- 每一步的输入与决策 -------------------------------------------------
+  disposers.push(
+    ctx.on('agent/pre-step', async (payload, next) => {
+      const decision = await next(); // 先让下游决定，观察器永远不改结果
+      try {
+        const agentId = agentKey(payload?.agent);
+        position.set(agentId, { turn: payload?.turn, step: payload?.step });
+        write(agentId, {
+          t: 'step',
+          at: Date.now(),
+          agent: agentId,
+          turn: payload?.turn,
+          step: payload?.step,
+          msgs: describeMessages(payload?.messages),
+          decision:
+            decision && decision.kind === 'reject'
+              ? { kind: 'reject' }
+              : { kind: decision?.kind ?? '?', msgs: describeMessages(decision?.messages) },
+        });
+      } catch (err) {
+        console.warn('[agentflow] 观察 step 失败（已忽略）：' + (err && err.message ? err.message : err));
+      }
+      return decision;
+    }),
+  );
+
+  // ---- 每一次工具调用（deny 也过这条管线） -------------------------------
+  // 第二个参数 `_result` 才是工具真实结果（content/isError/error）；
+  // next() 返回的是管线决策对象，只有 kind，不能当结果记。
+  disposers.push(
+    // 真实耗时只能在 around-dispatch 这一层量：post-execute 的 next() 只回决策，
+    // 它包住的不是工具执行本身（早期版本因此把 ms 全记成了 0）。
+    ctx.on('tools/execute', async (exec, next) => {
+      const token = exec && exec.token;
+      const startedAt = Date.now();
+      try {
+        return await next();
+      } finally {
+        if (token !== undefined) timings.set(token, Date.now() - startedAt);
+      }
+    }),
+    ctx.on('tools/post-execute', async (exec, _result, next) => {
+      const started = Date.now();
+      const downstream = await next();
+      try {
+        const agentId = agentKey(exec?.agent);
+        const spot = position.get(agentId) ?? {};
+        const result = _result && typeof _result === 'object' ? _result : {};
+        write(agentId, {
+          t: 'tool',
+          at: started,
+          agent: agentId,
+          turn: spot.turn,
+          step: spot.step,
+          name: exec?.name ?? '?',
+          args: clip(exec?.arguments, 300),
+          ms: (exec && exec.token !== undefined && timings.get(exec.token)) || 0,
+          isError: Boolean(result.isError),
+          text: clip(describeResult(result), 200),
+        });
+        if (exec && exec.token !== undefined) timings.delete(exec.token);
+      } catch (err) {
+        console.warn('[agentflow] 观察 tool 失败（已忽略）：' + (err && err.message ? err.message : err));
+      }
+      return downstream;
+    }),
+  );
+
+  // ---- 模型想收工的地方 ---------------------------------------------------
+  disposers.push(
+    ctx.on('agent/turn-stopping', (payload) => {
+      try {
+        const agentId = agentKey(payload?.agent);
+        write(agentId, { t: 'stop', at: Date.now(), agent: agentId, turn: payload?.turn });
+      } catch (err) {
+        console.warn('[agentflow] 观察 stop 失败（已忽略）：' + (err && err.message ? err.message : err));
+      }
+    }),
+  );
+
+  return {
+    dispose() {
+      for (const dispose of disposers) {
+        try {
+          dispose?.();
+        } catch {
+          /* 卸载失败没有补救动作 */
+        }
+      }
+      disposers.length = 0;
+    },
+    flush: () => writer.flush(),
+  };
+}
+
+export default startObserver;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-agentflow",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "DeepSeek Harness tool plugin: run AgentFlow (material-canvas agent orchestrator) boards from the model",
   "keywords": [
     "dsh",
@@ -28,14 +28,16 @@
   "bugs": "https://github.com/CC19990113/dsh-plugin-agentflow/issues",
   "main": "index.js",
   "scripts": {
-    "check": "node --check index.js && node --check lib/bridge.js && node --check scripts/sync-runtime.mjs && tsc --noEmit",
-    "test": "node test/bridge.selftest.mjs && node test/client.selftest.mjs",
+    "check": "node --check index.js && node --check lib/bridge.js && node --check lib/observe.js && node --check lib/commands.js && node --check lib/flow.js && node --check scripts/sync-runtime.mjs && node --check scripts/observe-report.mjs && tsc --noEmit",
+    "test": "node test/bridge.selftest.mjs && node test/client.selftest.mjs && node test/observe.selftest.mjs && node test/commands.selftest.mjs && node test/flow.selftest.mjs",
     "build": "node scripts/build-client.mjs",
+    "observe": "node scripts/observe-report.mjs",
     "sync": "node scripts/sync-runtime.mjs"
   },
   "type": "module",
   "dependencies": {
     "@deepseek-ai/cordis": "^4.0.5",
+    "@deepseek-ai/dsh-llm": "0.2.1-rc.2",
     "@deepseek-ai/dsh-tools": "^0.2.1-rc.2"
   },
   "files": [

package/runtime/boards.mjs

@@ -13,7 +13,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { dataDir, writeJsonAtomic, exclusive } from './store.mjs';
-import { orchestratorPersona, orchestratorCriteria } from './preset-gen.mjs';
+import { orchestratorPersona, orchestratorCriteria } from './orchestrator.mjs';
 
 export const FLOW_BOARD_ID = 'flow-agentflow';
 
@@ -428,6 +428,13 @@ export async function deleteBoard(id) {
     await fs.rm(boardFile(id), { force: true });
     await removeDraftUnlocked(id);
     legacyActive.delete(id);
+    // 画布没了，指向它的命令也该消失（失败不阻塞删画布）
+    try {
+      const { deleteCommandsForBoard } = await import('./commands.mjs');
+      await deleteCommandsForBoard(id);
+    } catch {
+      /* 命令清理是附带动作，删画布本身已经成功 */
+    }
     return { ok: true, id };
   });
 }

package/runtime/commands.mjs

@@ -0,0 +1,195 @@
+// commands.mjs —— 斜杠命令的存储层（一条命令 = 一个画布的对话入口）。
+//
+// 落盘：<DATA_DIR>/commands/<name>.json
+//   { version: 1, name: 'agentflow-x', board: '<boardId>', createdAt: <ms> }
+//
+// 命令名同时是 DSH 的斜杠命令和这里的文件名，所以规则由 DSH 侧决定：
+//   ^[a-z][a-z0-9_-]*$，长度 <= 48。
+// 本模块只做存储：画布是否存在、节点是否为空这类业务判断在 server.mjs。
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { dataDir, writeJsonAtomic } from './store.mjs';
+
+export const COMMAND_VERSION = 1;
+/** 命令名规则：小写字母开头，只允许 a-z 0-9 _ - */
+export const COMMAND_NAME_RE = /^[a-z][a-z0-9_-]*$/;
+export const COMMAND_NAME_MAX = 48;
+
+/** 命令目录：<DATA_DIR>/commands（dataDir 每次现读 env，测试可切临时目录） */
+export function commandsDir() {
+  return path.join(dataDir(), 'commands');
+}
+
+/** 一条命令的落盘文件；名字必须先过 isValidCommandName（调用方负责） */
+export function commandFile(name) {
+  return path.join(commandsDir(), `${name}.json`);
+}
+
+/** 严格校验：命令名要能直接当文件名、当斜杠命令 */
+export function isValidCommandName(name) {
+  return (
+    typeof name === 'string'
+    && name.length > 0
+    && name.length <= COMMAND_NAME_MAX
+    && COMMAND_NAME_RE.test(name)
+  );
+}
+
+/** 扫目录拿命令名（只认 *.json，且文件名本身合法） */
+async function commandNames() {
+  let entries;
+  try {
+    entries = await fs.readdir(commandsDir());
+  } catch (err) {
+    if (err.code === 'ENOENT') return [];
+    throw err;
+  }
+  return entries
+    .filter((entry) => entry.endsWith('.json'))
+    .map((entry) => entry.slice(0, -'.json'.length))
+    .filter(isValidCommandName);
+}
+
+/**
+ * 读一条命令：不存在 / 半截 JSON / 内容不是对象 都返回 null。
+ * @returns {Promise<null | {version: number, name: string, board: string, createdAt: number, file: string}>}
+ */
+export async function readCommand(name) {
+  if (!isValidCommandName(name)) return null;
+  let raw;
+  try {
+    raw = await fs.readFile(commandFile(name), 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+  return {
+    version: Number(parsed.version) || COMMAND_VERSION,
+    // 文件名是权威：JSON 里的 name 只作展示，不参与定位
+    name,
+    board: String(parsed.board ?? ''),
+    createdAt: Number(parsed.createdAt) || 0,
+    file: commandFile(name),
+  };
+}
+
+/** 全部命令，按创建时间新的在前。 */
+export async function listCommands() {
+  const out = [];
+  for (const name of await commandNames()) {
+    const rec = await readCommand(name);
+    if (!rec) continue;
+    out.push({ name: rec.name, board: rec.board, createdAt: rec.createdAt, file: rec.file });
+  }
+  out.sort((a, b) => b.createdAt - a.createdAt || a.name.localeCompare(b.name));
+  return out;
+}
+
+/**
+ * 把任意字符串压成合法命令名：非法字符转 '-'、首字符非字母补 'b'、截断 48。
+ * 纯函数，不做重名处理（重名是 commandNameFor 的事）。
+ */
+export function normalizeCommandName(desired) {
+  const cleaned = String(desired ?? '')
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, '-') // 非法字符统一转 '-'
+    .replace(/-{2,}/g, '-')
+    .replace(/^[-_]+|[-_]+$/g, '')
+    .slice(0, COMMAND_NAME_MAX)
+    .replace(/[-_]+$/g, '');
+  // 首字符必须是字母：数字开头补 'b'（'9x' → 'b9x'，空串 → 'b'）
+  const head = /^[a-z]/.test(cleaned) ? cleaned : `b${cleaned}`;
+  return head || 'b';
+}
+
+/** 画布 id → 可读 slug（'flow-agentflow' → 'agentflow-flow-agentflow'） */
+function commandSlug(boardId) {
+  return String(boardId ?? '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/-{2,}/g, '-')
+    .replace(/^[-_]+|[-_]+$/g, '');
+}
+
+/**
+ * 按画布 id 生成一个不冲突的命令名：'agentflow-<slug>'，重名依次加 '-2'/'-3'…
+ * 后缀最多占 3 个字符，所以 base 先截到 45。
+ */
+export async function commandNameFor(boardId) {
+  const slug = commandSlug(boardId);
+  const wanted = normalizeCommandName(`agentflow-${slug || 'board'}`);
+  const base = wanted.slice(0, COMMAND_NAME_MAX - 3) || 'agentflow';
+  let name = base;
+  let n = 2;
+  while (await readCommand(name)) name = `${base}-${n++}`;
+  return name;
+}
+
+/**
+ * 写一条命令（同名文件直接覆盖）。
+ *
+ * @param {{board: string, name?: string}} opts
+ *   board 必填；name 缺省时按画布 id 生成并自动避开重名。
+ * @returns {Promise<{name: string, board: string, file: string, replaced: boolean, createdAt: number}>}
+ *   replaced=true 表示覆盖了同名旧命令；同一张画布重复导出时 createdAt 沿用第一次，
+ *   换绑到别的画布则算新建（时间刷新）。
+ */
+export async function writeCommand({ board, name } = {}) {
+  const boardId = typeof board === 'string' ? board.trim() : '';
+  if (!boardId) throw new Error('writeCommand 需要 board');
+  const wanted = typeof name === 'string' ? name.trim() : '';
+  // 显式传名字时也归一化：server 已经严格校验过，这里只兜底
+  const finalName = wanted ? normalizeCommandName(wanted) : await commandNameFor(boardId);
+  const existing = await readCommand(finalName);
+  const createdAt =
+    existing && existing.board === boardId ? existing.createdAt : Date.now();
+  const file = commandFile(finalName);
+  await writeJsonAtomic(file, {
+    version: COMMAND_VERSION,
+    name: finalName,
+    board: boardId,
+    createdAt,
+  });
+  return { name: finalName, board: boardId, file, replaced: Boolean(existing), createdAt };
+}
+
+/** 删一条命令；返回是否真的删掉了（不存在 / 名字非法都返回 false）。 */
+/**
+ * 删画布时级联清掉指向它的命令文件。
+ *
+ * 不清的话：画布没了命令还在（插件侧会跳过不注册），同名 id 再次出现时旧命令
+ * 会"复活"；用户也会在命令目录里堆一堆死文件。
+ *
+ * @param {string} boardId 被删的画布 id
+ * @returns {Promise<string[]>} 被删掉的命令名
+ */
+export async function deleteCommandsForBoard(boardId) {
+  const wanted = String(boardId ?? '');
+  if (!wanted) return [];
+  const removed = [];
+  for (const record of await listCommands()) {
+    if (record.board !== wanted) continue;
+    if (await deleteCommand(record.name)) removed.push(record.name);
+  }
+  return removed;
+}
+
+export async function deleteCommand(name) {
+  if (!isValidCommandName(name)) return false;
+  const file = commandFile(name);
+  const existed = await fs
+    .stat(file)
+    .then((st) => st.isFile())
+    .catch(() => false);
+  if (!existed) return false;
+  await fs.rm(file, { force: true });
+  return true;
+}

package/runtime/orchestrator.mjs

@@ -0,0 +1,57 @@
+// orchestrator.mjs —— 调度根节点（对话入口）的共享规则。
+//
+// 从 preset-gen.mjs 搬出来的最小集合：预设生成已下线，但画布仍然需要这些规则：
+//   1. 新建画布时给根节点一份默认人格与验收标准（boards.mjs 用）
+//   2. 根节点不能有上游（PUT /api/boards/:id 的校验，server.mjs 用）
+//
+// 「调度根节点」= type === 'orchestrator' 的节点，一张画布最多一张 ——
+// 它就是对话入口，也是（历史版本的）persona 来源。
+
+/** 所有要嵌进行内文本的字段先压成单行 */
+function flat(value) {
+  return String(value ?? '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/**
+ * 画布上的调度根节点（type === 'orchestrator'）。
+ * 产品约定：一张画布最多一张 —— 它就是对话入口。
+ */
+export function findOrchestrators(board) {
+  const nodes = Array.isArray(board?.nodes) ? board.nodes : [];
+  return nodes.filter((n) => n && n.type === 'orchestrator');
+}
+
+/**
+ * 根节点（对话入口）的默认人格：刻意写得很短。
+ * 子节点内容随时会变，所以只列一份 label + 一句用途的清单，不展开 criteria；
+ * 具体执行交给后续节点的 AgentFlow 流。
+ * 用户可以自己改写——只在新建调度卡时用这份默认值。
+ */
+export function orchestratorPersona(board) {
+  const name = flat(board?.name) || '未命名画布';
+  return [
+    `你是「${name}」的对话入口。`,
+    '',
+    '你只负责和用户对话：问清需求、确认关键信息。',
+    '',
+    '需求明确后，严格按照后续节点的 AgentFlow 流去执行，不要自己直接产出结果。',
+  ].join('\n');
+}
+
+/** 根节点的默认验收标准 */
+export function orchestratorCriteria() {
+  return '用户需求已确认清楚；后续节点按流程顺序全部执行完成，最终产出交给用户。';
+}
+
+/** 根节点不能有上游（它是流程起点、对话入口） */
+export function assertRootHasNoUpstream(board) {
+  const roots = findOrchestrators(board);
+  if (!roots.length) return;
+  const incoming = new Set((board?.edges || []).map((e) => String(e.to)));
+  const bad = roots.filter((n) => incoming.has(String(n.id)));
+  if (bad.length) {
+    throw Object.assign(new Error('根节点（调度卡）不能有上游节点'), { status: 400 });
+  }
+}