dsh-plugin-agentflow 0.0.0-stage → 0.2.1

package/lib/client.js

@@ -0,0 +1,4 @@
+window.__ModuleLoader__.load({ id: "dsh-plugin-agentflow", factory: (require) => {
+var module = { exports: {} }; var exports = module.exports;
+var k=Object.defineProperty;var B=Object.getOwnPropertyDescriptor;var A=Object.getOwnPropertyNames;var F=Object.prototype.hasOwnProperty;var j=(e,n)=>{for(var o in n)k(e,o,{get:n[o],enumerable:!0})},L=(e,n,o,r)=>{if(n&&typeof n=="object"||typeof n=="function")for(let l of A(n))!F.call(e,l)&&l!==o&&k(e,l,{get:()=>n[l],enumerable:!(r=B(n,l))||r.enumerable});return e};var D=e=>L(k({},"__esModule",{value:!0}),e);var nt={};j(nt,{apply:()=>G,inject:()=>Y,name:()=>M});module.exports=D(nt);var t=require("react"),x="agentflow",H=30;function U(){let[e,n]=(0,t.useState)(w),o=(0,t.useRef)(!1);return(0,t.useEffect)(()=>(S.add(n),()=>{S.delete(n)}),[]),(0,t.createElement)("iframe",{src:E(e),onLoad:()=>{try{fetch("http://127.0.0.1:8791/api/plugin-alive?stage=iframe-load",{mode:"no-cors"}).catch(()=>{})}catch{}},onError:()=>{try{fetch("http://127.0.0.1:8791/api/plugin-alive?stage=iframe-error",{mode:"no-cors"}).catch(()=>{})}catch{}},title:"AgentFlow",style:{width:"100%",height:"100%",border:"none",display:"block",background:"#f7f8fa"}})}function W(e){let n=typeof e.size=="number"?e.size:16;return(0,t.createElement)("svg",{width:n,height:n,viewBox:"0 0 16 16",fill:"none",stroke:"currentColor",strokeWidth:1.4,strokeLinecap:"round",strokeLinejoin:"round"},(0,t.createElement)("rect",{x:1.5,y:6,width:4,height:4,rx:1}),(0,t.createElement)("rect",{x:10.5,y:1.5,width:4,height:4,rx:1}),(0,t.createElement)("rect",{x:10.5,y:10.5,width:4,height:4,rx:1}),(0,t.createElement)("path",{d:"M5.5 8h2.5V3.5h2.5M8 8v4.5h2.5"}))}var p="http://127.0.0.1:8791",b=null,w="",S=new Set;function N(e){w=String(e||"");for(let n of S)try{n(w)}catch{}}function _(){try{if(document.body&&document.body.hasAttribute("data-ds-dark-theme")||document.documentElement.classList.contains("dark"))return"dark"}catch{}try{if(window.matchMedia&&window.matchMedia("(prefers-color-scheme: dark)").matches)return"dark"}catch{}return"light"}function E(e){let n=new URLSearchParams;return e&&n.set("board",e),n.set("theme",_()),`${p}/?${n.toString()}`}function O(){try{if(b&&typeof b.selectPanel=="function")return b.selectPanel(x),!0}catch{}return!1}var M="agentflow",Y=["slots","layout"];function m(e,n){try{let o=`${e}: ${n?.stack||String(n)}`;fetch(`${p}/api/plugin-alive?stage=apply-error&detail=${encodeURIComponent(o.slice(0,800))}`,{mode:"no-cors"}).catch(()=>{})}catch{}}function G(e,n){try{J(e,n)}catch(o){m("apply",o),console.error("[agentflow] \u5BA2\u6237\u7AEF\u63D2\u4EF6\u521D\u59CB\u5316\u5931\u8D25\uFF1A",o)}}function J(e,n){n&&typeof n.agentflowUrl=="string"&&n.agentflowUrl&&(p=n.agentflowUrl);let o=null;try{o=e.layout??null}catch(r){m("layout",r),o=null}b=o,e.slots.inject("main",()=>e.slots.register({name:"main",key:x},U));try{e.slots.inject("settings.section",()=>e.slots.register({name:"settings.section",id:"agentflow",order:90,label:()=>"AgentFlow",inject:()=>({})},tt))}catch(r){m("settings.section",r)}try{e.slots.inject("plugins.add.actions",()=>e.slots.register({name:"plugins.add.actions",id:"agentflow-export",inject:()=>({})},et))}catch(r){m("plugins.add.actions",r)}e.slots.inject("sidebar.panellist",()=>e.slots.register({name:"sidebar.panellist",id:x,order:H,label:()=>"AgentFlow"},r=>(0,t.createElement)(W,r)))}var V={border:"1px solid rgba(128,130,120,0.28)",borderRadius:12,padding:"14px 16px",background:"rgba(128,130,120,0.06)",maxWidth:560},T={border:"none",borderRadius:8,padding:"8px 14px",fontSize:13,fontWeight:600,color:"#fff",background:"#24543F",cursor:"pointer"},q={...T,opacity:.55,cursor:"not-allowed"};function C(){let[e,n]=(0,t.useState)(!1),[o,r]=(0,t.useState)(null),[l,s]=(0,t.useState)(null);return{busy:e,result:o,error:l,run:()=>{e||(n(!0),s(null),r(null),fetch(`${p}/api/export/preset`,{method:"POST",headers:{"content-type":"application/json"},body:"{}"}).then(async c=>{let f=await c.json().catch(()=>({}));if(!c.ok)throw new Error(f.error||`HTTP ${c.status}`);return f}).then(c=>r(c)).catch(c=>s(String(c&&c.message||c))).finally(()=>n(!1)))}}}function K(){let[e,n]=(0,t.useState)(null),[o,r]=(0,t.useState)(null),l=()=>{r(null),fetch(`${p}/api/board`).then(async s=>{if(!s.ok)throw new Error(`HTTP ${s.status}`);return await s.json()}).then(n).catch(s=>r(String(s&&s.message||s)))};return(0,t.useEffect)(l,[]),{board:e,error:o,reload:l}}function Q({busy:e,result:n,error:o}){return o?(0,t.createElement)("div",{style:{marginTop:10,fontSize:12,color:"#B4451F",lineHeight:1.6}},`\u5BFC\u51FA\u5931\u8D25\uFF1A${o}`):e?(0,t.createElement)("div",{style:{marginTop:10,fontSize:12,opacity:.7}},"\u6B63\u5728\u5199\u5165 profile\u2026"):n?(0,t.createElement)("div",{style:{marginTop:10,fontSize:12,lineHeight:1.7}},(0,t.createElement)("div",null,`\u5DF2${n.replaced?"\u66F4\u65B0":"\u5199\u5165"}\u9884\u8BBE `,(0,t.createElement)("b",null,n.presetId||"")),(0,t.createElement)("div",{style:{opacity:.7,wordBreak:"break-all"}},n.file||""),(0,t.createElement)("div",{style:{marginTop:4,fontWeight:600}},"\u91CD\u542F DSH \u540E\u751F\u6548")):null}function X(){let[e,n]=(0,t.useState)(null),[o,r]=(0,t.useState)(null),[l,s]=(0,t.useState)(null),g=()=>{r(null),fetch(`${p}/api/presets`).then(async a=>{if(!a.ok)throw new Error(`HTTP ${a.status}`);let i=await a.json();if(i.error)throw new Error(i.error);n(i.presets||[])}).catch(a=>r(String(a&&a.message||a)))};return(0,t.useEffect)(g,[]),{presets:e,error:o,busyId:l,reload:g,copy:a=>{s(a.id),r(null),fetch(`${p}/api/presets/${encodeURIComponent(a.id)}/copy`,{method:"POST",headers:{"content-type":"application/json"},body:JSON.stringify({name:`${a.name} \u526F\u672C`})}).then(async i=>{let u=await i.json().catch(()=>({}));if(!i.ok)throw new Error(u.error||`HTTP ${i.status}`);return u}).then(()=>g()).catch(i=>r(String(i&&i.message||i))).finally(()=>s(null))},remove:a=>{window.confirm(`\u5220\u9664\u9884\u8BBE\u300C${a.name}\u300D\uFF1F\u53EA\u5220 profile \u91CC\u7684\u8FD9\u4E00\u884C\uFF0C\u91CD\u542F DSH \u751F\u6548\u3002`)&&(s(a.id),r(null),fetch(`${p}/api/presets/${encodeURIComponent(a.id)}`,{method:"DELETE"}).then(async i=>{let u=await i.json().catch(()=>({}));if(!i.ok)throw new Error(u.error||`HTTP ${i.status}`);return u}).then(()=>g()).catch(i=>r(String(i&&i.message||i))).finally(()=>s(null)))}}}var Z={display:"inline-block",padding:"1px 7px",borderRadius:999,fontSize:11,border:"1px solid rgba(128,130,120,0.35)",opacity:.85};function h({children:e,onClick:n,disabled:o,danger:r}){return(0,t.createElement)("button",{type:"button",onClick:n,disabled:o,style:{border:`1px solid ${r?"rgba(180,69,31,0.45)":"rgba(128,130,120,0.35)"}`,borderRadius:7,padding:"4px 10px",fontSize:12,background:"transparent",color:r?"#B4451F":"inherit",cursor:o?"not-allowed":"pointer",opacity:o?.5:1}},e)}function tt(e){let[n,o]=(0,t.useState)(!1),r=d=>{if(N(d),O()){try{typeof e?.close=="function"&&e.close()}catch{}return}o(!0)},{board:l,error:s,reload:g}=K(),{busy:c,result:f,error:a,run:i}=C(),{presets:u,error:v,busyId:y,reload:$,copy:I,remove:P}=X(),R=l?.nodes?.length??0,z=l?.edges?.length??0;return(0,t.createElement)("div",{style:V},n?(0,t.createElement)("div",{style:{position:"fixed",inset:0,zIndex:9999,background:"rgba(0,0,0,0.45)",display:"flex",flexDirection:"column"}},(0,t.createElement)("div",{style:{display:"flex",alignItems:"center",justifyContent:"space-between",padding:"8px 12px",background:"#17181B",color:"#EDEDE8",fontSize:13}},(0,t.createElement)("span",null,"AgentFlow \u753B\u5E03"),(0,t.createElement)("button",{type:"button",onClick:()=>o(!1),style:{border:"1px solid rgba(255,255,255,0.25)",borderRadius:7,padding:"4px 12px",fontSize:12,background:"transparent",color:"inherit",cursor:"pointer"}},"\u5173\u95ED")),(0,t.createElement)("iframe",{src:E(w),title:"AgentFlow \u753B\u5E03",style:{flex:1,width:"100%",border:"none",background:"#F4F5F2"}})):null,(0,t.createElement)("div",{style:{fontSize:14,fontWeight:600,marginBottom:6}},"AgentFlow \u753B\u5E03 \u2192 \u9884\u8BBE"),(0,t.createElement)("div",{style:{fontSize:12.5,lineHeight:1.7,opacity:.78}},s?`\u8BFB\u4E0D\u5230\u753B\u5E03\uFF1A${s}\uFF08\u786E\u8BA4 AgentFlow \u670D\u52A1\u5728 ${p} \u8FD0\u884C\uFF09`:l?`\u5F53\u524D\u753B\u5E03\u300C${l.name||"\u672A\u547D\u540D"}\u300D${R} \u4E2A\u8282\u70B9 / ${z} \u6761\u8FDE\u7EBF`:"\u6B63\u5728\u8BFB\u53D6\u753B\u5E03\u2026"),(0,t.createElement)("div",{style:{marginTop:12,display:"flex",gap:10,alignItems:"center"}},(0,t.createElement)("button",{type:"button",onClick:i,disabled:c||s!==null,style:c||s!==null?q:T},c?"\u5BFC\u51FA\u4E2D\u2026":"\u5BFC\u51FA\u5F53\u524D\u753B\u5E03\u4E3A\u9884\u8BBE"),(0,t.createElement)("button",{type:"button",onClick:g,style:{border:"1px solid rgba(128,130,120,0.35)",borderRadius:8,padding:"7px 12px",fontSize:12.5,background:"transparent",color:"inherit",cursor:"pointer"}},"\u5237\u65B0\u753B\u5E03\u4FE1\u606F")),(0,t.createElement)("div",{style:{marginTop:16,borderTop:"1px solid rgba(128,130,120,0.25)",paddingTop:12}},(0,t.createElement)("div",{style:{display:"flex",alignItems:"center",justifyContent:"space-between",marginBottom:8}},(0,t.createElement)("div",{style:{fontSize:13,fontWeight:600}},"\u81EA\u5B9A\u4E49\u9884\u8BBE"),h({children:"\u5237\u65B0",onClick:$,disabled:y!==null})),v?(0,t.createElement)("div",{style:{fontSize:12,color:"#B4451F"}},`\u8BFB\u53D6\u5931\u8D25\uFF1A${v}`):null,u?u.length===0?(0,t.createElement)("div",{style:{fontSize:12,opacity:.7}},"\u8FD8\u6CA1\u6709\u81EA\u5B9A\u4E49\u9884\u8BBE"):(0,t.createElement)("div",{style:{display:"flex",flexDirection:"column",gap:8}},u.map(d=>(0,t.createElement)("div",{key:d.id,style:{display:"flex",alignItems:"center",gap:10,padding:"8px 10px",borderRadius:9,background:"rgba(128,130,120,0.08)"}},(0,t.createElement)("div",{style:{minWidth:0,flex:1}},(0,t.createElement)("div",{style:{fontSize:13,fontWeight:600}},d.name),(0,t.createElement)("div",{style:{fontSize:11,opacity:.65,display:"flex",gap:6,flexWrap:"wrap",marginTop:2}},(0,t.createElement)("span",null,d.id),(0,t.createElement)("span",{style:Z},d.source==="profile"?"profile":d.packageName||"\u63D2\u4EF6\u5305"))),h({children:y===d.id?"\u5904\u7406\u4E2D\u2026":"\u590D\u5236",onClick:()=>I(d),disabled:y!==null}),d.editable?h({children:"\u5220\u9664",onClick:()=>P(d),disabled:y!==null,danger:!0}):null,h({children:"\u7F16\u8F91",onClick:()=>r(d.id)})))):(0,t.createElement)("div",{style:{fontSize:12,opacity:.7}},"\u8BFB\u53D6\u4E2D\u2026"),(0,t.createElement)("div",{style:{fontSize:11,opacity:.6,marginTop:8,lineHeight:1.6}},"\u63D2\u4EF6\u5305\u81EA\u5E26\u7684\u9884\u8BBE\uFF08Sharp Agent / \u7FA4\u53CB\u8154\uFF09\u53EA\u80FD\u590D\u5236\u6210\u81EA\u5DF1\u7684\u518D\u6539\uFF1B\u5220\u9664\u4E0E\u7F16\u8F91\u53EA\u5BF9 profile \u91CC\u7684\u9884\u8BBE\u5F00\u653E\u3002\u6539\u5B8C\u8BB0\u5F97\u91CD\u542F DSH\u3002")),(0,t.createElement)(Q,{busy:c,result:f,error:a}))}function et(){let{busy:e,error:n,run:o}=C();return(0,t.createElement)("button",{type:"button",onClick:o,disabled:e,style:{display:"block",width:"100%",textAlign:"left",border:"none",background:"transparent",color:"inherit",padding:"8px 12px",fontSize:13,cursor:e?"not-allowed":"pointer",opacity:e?.6:1}},e?"\u6B63\u5728\u5BFC\u51FA AgentFlow \u9884\u8BBE\u2026":"\u4ECE AgentFlow \u753B\u5E03\u751F\u6210\u9884\u8BBE",n?(0,t.createElement)("span",{style:{display:"block",fontSize:11,color:"#B4451F"}},n):null)}
+return module.exports; } });

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "dsh-plugin-agentflow",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1",
+  "description": "DeepSeek Harness tool plugin: run AgentFlow (material-canvas agent orchestrator) boards from the model",
+  "main": "index.js",
+  "scripts": {
+    "check": "node --check index.js && node --check lib/bridge.js && node --check scripts/sync-runtime.mjs",
+    "test": "node test/bridge.selftest.mjs",
+    "build": "node scripts/build-client.mjs",
+    "sync": "node scripts/sync-runtime.mjs"
+  },
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@deepseek-ai/cordis": "^4.0.5",
+    "@deepseek-ai/dsh-tools": "^0.2.1-rc.2"
+  },
+  "type": "module",
+  "files": [
+    "index.js",
+    "lib/**/*.js",
+    "runtime/**",
+    "cordis.patch.yml",
+    "scripts/**/*.mjs",
+    "README.md"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [],
+      "platform": "web"
+    }
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.2"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./client": "./lib/client.js",
+    "./package.json": "./package.json"
+  }
+}

package/runtime/boards.mjs

@@ -0,0 +1,486 @@
+// boards.mjs —— 多画布存储层（每个自定义预设一张画布）。
+//
+// 索引：<DATA_DIR>/boards.json
+//   结构见 docs/boards-contract.md：{ order: [id...], boards: { id: {id,name,presetId,createdAt,updatedAt} } }
+// 画布：<DATA_DIR>/boards/<id>.json，内容就是 Board（id/name/nodes/edges）。
+//
+// 迁移：boards.json 不存在且 <DATA_DIR>/board.json 存在 → 复制成 flow-agentflow，原文件不动。
+// 过渡：flow-agentflow 与旧 board.json 做 mtime 仲裁的兼容 ——
+//   旧文件比画布文件新（说明有人在直接写 board.json）时，先导入再读写；
+//   一旦发生过这种导入，后续保存会同步镜像回旧文件（否则旧测试/旧前端读不到结果）。
+//   迁移后没人动旧文件时，旧文件永远保持原样。
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { dataDir, writeJsonAtomic, exclusive } from './store.mjs';
+
+export const FLOW_BOARD_ID = 'flow-agentflow';
+
+// id 会拼进文件路径：只允许字母数字开头，禁止 .. 之类
+const ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+/** 带 HTTP 状态码的错误，server.mjs 直接把它翻成响应码。 */
+export function httpError(status, message) {
+  return Object.assign(new Error(message), { status });
+}
+
+export function boardsDir() {
+  return path.join(dataDir(), 'boards');
+}
+
+export function indexFile() {
+  return path.join(dataDir(), 'boards.json');
+}
+
+/** 旧单画布文件（迁移来源 / 过渡兼容目标） */
+export function legacyBoardFile() {
+  return path.join(dataDir(), 'board.json');
+}
+
+export function boardFile(id) {
+  return path.join(boardsDir(), `${id}.json`);
+}
+
+/** 草稿目录：手动保存前的未落定修改，一张画布一份 */
+export function draftsDir() {
+  return path.join(dataDir(), 'drafts');
+}
+
+export function draftFile(id) {
+  return path.join(draftsDir(), `${id}.json`);
+}
+
+export function isValidBoardId(id) {
+  return typeof id === 'string' && ID_RE.test(id) && !id.includes('..');
+}
+
+async function exists(file) {
+  try {
+    await fs.access(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function mtimeMs(file) {
+  try {
+    return (await fs.stat(file)).mtimeMs;
+  } catch {
+    return -1;
+  }
+}
+
+async function readJson(file) {
+  try {
+    return JSON.parse(await fs.readFile(file, 'utf8'));
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+// ---------- 索引 ----------
+
+function emptyIndex() {
+  return { order: [], boards: {} };
+}
+
+/** 容错：剔除 order 里不存在的 id、补上 boards 里有但 order 漏了的 id。 */
+function normalizeIndex(raw) {
+  const source = raw && typeof raw === 'object' ? raw : {};
+  const boards = source.boards && typeof source.boards === 'object' ? source.boards : {};
+  const seen = new Set();
+  const order = [];
+  for (const rawId of Array.isArray(source.order) ? source.order : []) {
+    const id = String(rawId);
+    if (!boards[id] || seen.has(id)) continue;
+    seen.add(id);
+    order.push(id);
+  }
+  const missing = Object.keys(boards)
+    .filter((id) => !seen.has(id))
+    .sort((a, b) => (boards[a]?.createdAt || 0) - (boards[b]?.createdAt || 0));
+  order.push(...missing);
+  return { order, boards };
+}
+
+export async function readIndex() {
+  return normalizeIndex(await readJson(indexFile()));
+}
+
+export async function writeIndex(index) {
+  const normalized = normalizeIndex(index);
+  await writeJsonAtomic(indexFile(), normalized);
+  return normalized;
+}
+
+// ---------- 迁移 / 旧文件过渡 ----------
+
+async function readLegacyBoard() {
+  return readJson(legacyBoardFile());
+}
+
+/** 迁移只跑一次：索引存在就直接返回；原 board.json 一个字节都不改。 */
+export async function migrateIfNeeded() {
+  return exclusive(async () => {
+    if (await exists(indexFile())) return { migrated: false };
+    const legacy = await readLegacyBoard();
+    if (!legacy) return { migrated: false };
+
+    const now = Date.now();
+    const board = {
+      ...legacy,
+      id: FLOW_BOARD_ID,
+      name: legacy.name || 'AgentFlow',
+      nodes: Array.isArray(legacy.nodes) ? legacy.nodes : [],
+      edges: Array.isArray(legacy.edges) ? legacy.edges : [],
+    };
+    const meta = {
+      id: FLOW_BOARD_ID,
+      name: board.name,
+      presetId: FLOW_BOARD_ID,
+      createdAt: now,
+      updatedAt: now,
+    };
+    await writeJsonAtomic(boardFile(FLOW_BOARD_ID), board);
+    await writeJsonAtomic(indexFile(), { order: [FLOW_BOARD_ID], boards: { [FLOW_BOARD_ID]: meta } });
+    return { migrated: true, board, meta };
+  });
+}
+
+// 发生过旧文件导入的 id：之后保存时把内容镜像回旧文件（仅过渡期用）
+const legacyActive = new Set();
+
+/**
+ * 旧 board.json 比 flow-agentflow 画布文件新时，按旧文件为准导入一次。
+ * 只在 exclusive 内部调用，调用方不需要再上锁。
+ */
+async function importLegacyIfNewerUnlocked(id) {
+  if (id !== FLOW_BOARD_ID) return false;
+  const legacyMs = await mtimeMs(legacyBoardFile());
+  if (legacyMs < 0) return false;
+  if ((await mtimeMs(boardFile(id))) >= legacyMs) return false;
+
+  const legacy = await readLegacyBoard();
+  if (!legacy) return false;
+
+  const board = {
+    ...legacy,
+    id,
+    name: legacy.name || 'AgentFlow',
+    nodes: Array.isArray(legacy.nodes) ? legacy.nodes : [],
+    edges: Array.isArray(legacy.edges) ? legacy.edges : [],
+  };
+  await writeJsonAtomic(boardFile(id), board);
+
+  const index = await readIndex();
+  const now = Date.now();
+  const meta = index.boards[id] || {
+    id,
+    name: board.name,
+    presetId: FLOW_BOARD_ID,
+    createdAt: now,
+    updatedAt: now,
+  };
+  meta.name = board.name;
+  meta.updatedAt = now;
+  index.boards[id] = meta;
+  if (!index.order.includes(id)) index.order.push(id);
+  await writeIndex(index);
+
+  legacyActive.add(id);
+  return true;
+}
+
+// ---------- 画布 ----------
+
+async function readBoardRaw(id) {
+  if (!isValidBoardId(id)) return null;
+  return readJson(boardFile(id));
+}
+
+/** 读一张画布；不存在 / id 非法返回 null。 */
+export async function getBoard(id) {
+  if (!isValidBoardId(id)) return null;
+  return exclusive(async () => {
+    await importLegacyIfNewerUnlocked(id);
+    return readBoardRaw(id);
+  });
+}
+
+/** 列表：索引顺序 + 每张的 nodeCount / 是否有草稿。 */
+export async function listBoards() {
+  const index = await readIndex();
+  const withDraft = await draftIdSet();
+  const out = [];
+  for (const id of index.order) {
+    const meta = index.boards[id];
+    const board = await readBoardRaw(id);
+    out.push({
+      id,
+      name: board?.name || meta?.name || id,
+      presetId: meta?.presetId ?? null,
+      nodeCount: Array.isArray(board?.nodes) ? board.nodes.length : 0,
+      updatedAt: meta?.updatedAt || meta?.createdAt || 0,
+      hasDraft: withDraft.has(id),
+      // 改了画布但还没点「保存」（预设没跟着更新）
+      presetOutdated: Boolean(meta?.presetOutdated),
+    });
+  }
+  return out;
+}
+
+/** 默认画布 = 索引里的第一张。找不到返回 null。 */
+export async function resolveBoard(id) {
+  const wanted = id ? String(id) : (await readIndex()).order[0];
+  if (!wanted) return null;
+  const board = await getBoard(wanted);
+  return board ? { id: wanted, board } : null;
+}
+
+function slugify(name) {
+  const s = String(name || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return s || 'board';
+}
+
+/** 新建画布：presetId 有值就用它当 id（冲突报 409），否则由名字生成唯一 id。 */
+export async function createBoard({ name, presetId } = {}) {
+  const safeName = String(name || '').trim() || '未命名画布';
+  const wantedPreset = presetId === undefined || presetId === null || presetId === ''
+    ? null
+    : String(presetId);
+  if (wantedPreset && !isValidBoardId(wantedPreset)) {
+    throw httpError(400, `预设 id 不合法：${wantedPreset}`);
+  }
+
+  return exclusive(async () => {
+    const index = await readIndex();
+    let id;
+    if (wantedPreset) {
+      if (index.boards[wantedPreset] || (await exists(boardFile(wantedPreset)))) {
+        throw httpError(409, `画布已存在：${wantedPreset}`);
+      }
+      id = wantedPreset;
+    } else {
+      const base = slugify(safeName);
+      id = base;
+      let n = 2;
+      while (index.boards[id] || (await exists(boardFile(id)))) id = `${base}-${n++}`;
+    }
+
+    const now = Date.now();
+    const board = { id, name: safeName, nodes: [], edges: [] };
+    const meta = { id, name: safeName, presetId: wantedPreset, createdAt: now, updatedAt: now };
+    await writeJsonAtomic(boardFile(id), board);
+    await writeIndex({
+      order: [...index.order, id],
+      boards: { ...index.boards, [id]: meta },
+    });
+    return { board, meta };
+  });
+}
+
+/** 持久化一张画布（读-改-写用同一个锁）。opts.clearDraft：正式保存后清草稿。 */
+async function persistUnlocked(id, board, opts = {}) {
+  const index = await readIndex();
+  const now = Date.now();
+  const prev = index.boards[id];
+  const meta = prev
+    ? { ...prev }
+    : { id, name: board.name || id, presetId: id === FLOW_BOARD_ID ? FLOW_BOARD_ID : null, createdAt: now, updatedAt: now };
+
+  const next = { ...board, id };
+  if (legacyActive.has(id) && id === FLOW_BOARD_ID) {
+    // 先写旧文件、后写画布文件：保证画布文件 mtime 更新，不会触发下一次导入
+    await writeJsonAtomic(legacyBoardFile(), next);
+  }
+  await writeJsonAtomic(boardFile(id), next);
+
+  if (next.name) meta.name = next.name;
+  meta.updatedAt = now;
+  // 画布内容变了，预设就落后了：列表上要能提示「预设未更新」。
+  // 导出预设成功后由 markPresetSynced 清掉。
+  if (!opts.keepPresetSynced) meta.presetOutdated = true;
+  index.boards[id] = meta;
+  if (!index.order.includes(id)) index.order.push(id);
+  await writeIndex(index);
+  // 只有「正式保存」才让草稿失效：节点 patch / 跑图结果也走底层的 mutateBoardById，
+  // 那些不该顺手丢掉用户还没保存的草稿。
+  if (opts.clearDraft) await removeDraftUnlocked(id);
+  return { ok: true, meta, board: next };
+}
+
+/** 读-改-写一张画布；画布不存在抛 404。opts.clearDraft 透传给 persistUnlocked。 */
+export async function mutateBoardById(id, fn, opts = {}) {
+  if (!isValidBoardId(id)) throw httpError(404, `画布不存在：${id}`);
+  return exclusive(async () => {
+    await importLegacyIfNewerUnlocked(id);
+    const index = await readIndex();
+    const existing = await readBoardRaw(id);
+    if (!existing && !index.boards[id]) throw httpError(404, `画布不存在：${id}`);
+    const base = existing || { id, name: index.boards[id]?.name || id, nodes: [], edges: [] };
+    const next = await fn(base);
+    if (!next || typeof next !== 'object' || Array.isArray(next)) {
+      throw new Error('mutateBoardById 的回调必须返回画布对象');
+    }
+    return persistUnlocked(id, next, opts);
+  });
+}
+
+/** 整体保存一张画布（PUT /api/boards/:id）：正式保存，成功后草稿失效。 */
+export async function saveBoard(id, board) {
+  if (!board || typeof board !== 'object' || Array.isArray(board)) {
+    throw httpError(400, '缺少画布数据');
+  }
+  const out = await mutateBoardById(id, () => ({ ...board, id }), { clearDraft: true });
+  return { ok: true, meta: out.meta };
+}
+
+/** 导出预设成功后调用：画布与预设重新对齐，清掉「预设未更新」。 */
+export async function markPresetSynced(id) {
+  if (!isValidBoardId(id)) return { ok: false };
+  return exclusive(async () => {
+    const index = await readIndex();
+    const meta = index.boards[id];
+    if (meta) {
+      meta.presetOutdated = false;
+      index.boards[id] = meta;
+      await writeIndex(index);
+    }
+    return { ok: true };
+  });
+}
+
+/** 改元信息（目前只有 name）。 */
+export async function renameBoard(id, name) {
+  if (!isValidBoardId(id)) throw httpError(404, `画布不存在：${id}`);
+  const safeName = String(name ?? '').trim();
+  if (!safeName) throw httpError(400, '画布名不能为空');
+
+  return exclusive(async () => {
+    const index = await readIndex();
+    const meta = index.boards[id];
+    if (!meta) throw httpError(404, `画布不存在：${id}`);
+    const board = await readBoardRaw(id);
+    if (board) {
+      board.name = safeName;
+      await writeJsonAtomic(boardFile(id), board);
+    }
+    meta.name = safeName;
+    meta.updatedAt = Date.now();
+    index.boards[id] = meta;
+    await writeIndex(index);
+    return { ok: true, meta };
+  });
+}
+
+/** 删除画布；最后一张不许删。 */
+export async function deleteBoard(id) {
+  if (!isValidBoardId(id)) throw httpError(404, `画布不存在：${id}`);
+  return exclusive(async () => {
+    const index = await readIndex();
+    if (!index.boards[id]) throw httpError(404, `画布不存在：${id}`);
+    if (index.order.length <= 1) throw httpError(400, '至少要保留一张画布');
+
+    const order = index.order.filter((x) => x !== id);
+    const boards = { ...index.boards };
+    delete boards[id];
+    // 先落索引再删文件：中途崩溃最多留下孤儿文件，不会出现索引指向缺失文件
+    await writeIndex({ order, boards });
+    await fs.rm(boardFile(id), { force: true });
+    await removeDraftUnlocked(id);
+    legacyActive.delete(id);
+    return { ok: true, id };
+  });
+}
+
+// ---------- 草稿（手动保存 + 未保存修改） ----------
+//
+// 画布定位收窄成「预设工作流配置器」后，编辑不再自动落盘：
+// 前端把未保存的修改 PUT 到草稿，正式保存时草稿清掉。
+// 文件：<DATA_DIR>/drafts/<id>.json，内容 { board, updatedAt }。
+
+/** 扫目录拿有草稿的画布 id（只看文件名，不读内容）。 */
+async function draftIdSet() {
+  try {
+    const entries = await fs.readdir(draftsDir());
+    return new Set(
+      entries
+        .filter((name) => name.endsWith('.json'))
+        .map((name) => name.slice(0, -'.json'.length)),
+    );
+  } catch (err) {
+    if (err.code === 'ENOENT') return new Set();
+    throw err;
+  }
+}
+
+/** 是否有草稿；id 非法按没有处理。 */
+export async function hasDraft(id) {
+  return isValidBoardId(id) && (await exists(draftFile(id)));
+}
+
+/** 读草稿：返回 { board, updatedAt }，没有 / id 非法返回 null。 */
+export async function getDraft(id) {
+  if (!isValidBoardId(id)) return null;
+  const rec = await readJson(draftFile(id));
+  if (!rec || typeof rec !== 'object' || !rec.board) return null;
+  return { board: rec.board, updatedAt: Number(rec.updatedAt) || 0 };
+}
+
+/** 写草稿（原子写）。画布必须存在，否则 404。 */
+export async function saveDraft(id, board) {
+  if (!isValidBoardId(id)) throw httpError(404, `画布不存在：${id}`);
+  if (!board || typeof board !== 'object' || Array.isArray(board)) {
+    throw httpError(400, '缺少画布数据');
+  }
+  return exclusive(async () => {
+    const index = await readIndex();
+    if (!index.boards[id] && !(await exists(boardFile(id)))) {
+      throw httpError(404, `画布不存在：${id}`);
+    }
+    const updatedAt = Date.now();
+    await writeJsonAtomic(draftFile(id), { board: { ...board, id }, updatedAt });
+    return { ok: true, updatedAt };
+  });
+}
+
+/** 无锁删除草稿：只在 exclusive 内部调用（正式保存 / 删画布时顺手清）。 */
+async function removeDraftUnlocked(id) {
+  if (!isValidBoardId(id)) return false;
+  const file = draftFile(id);
+  if (!(await exists(file))) return false;
+  await fs.rm(file, { force: true });
+  return true;
+}
+
+/** 删草稿（幂等）。 */
+export async function deleteDraft(id) {
+  if (!isValidBoardId(id)) throw httpError(404, `画布不存在：${id}`);
+  return exclusive(async () => ({ ok: true, removed: await removeDraftUnlocked(id) }));
+}
+
+/**
+ * 启动时调用：先迁移；一张画布都没有时用 makeBoard() 造默认的 flow-agentflow。
+ * @param {() => object} makeBoard 造默认画布内容的函数
+ */
+export async function ensureDefaultBoard(makeBoard) {
+  const migrated = await migrateIfNeeded();
+  const index = await readIndex();
+  if (index.order.length) {
+    return { created: false, migrated: migrated.migrated, id: index.order[0] };
+  }
+
+  const seed = typeof makeBoard === 'function' ? makeBoard() : { nodes: [], edges: [] };
+  const created = await createBoard({ name: 'AgentFlow', presetId: FLOW_BOARD_ID });
+  await saveBoard(FLOW_BOARD_ID, {
+    ...seed,
+    id: FLOW_BOARD_ID,
+    name: created.board.name,
+  });
+  return { created: true, migrated: migrated.migrated, id: FLOW_BOARD_ID };
+}