nx-kv 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -2,6 +2,68 @@
 
 本文件记录对外可见的变更。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)。
 
+## [0.19.0] - 2026-11-04 提示词/模板收敛到设置面板 + 面板无页签化（面包屑 + 区域策略）+ DAG 引擎与 goal 插件族
+
+### Added
+
+- **提示词 / 模板统一收敛到设置面板一栏（任务 #32）**：此前提示词与模板散在
+  「模板与任务工具」区、模板页、项目级设置三处，各抄一份编辑器、风格也不一。
+  现在设置面板新增「**提示词 / 模板**」一栏，三样收在一起：
+  - **任务模板**：正文里的 `{{槽位}}` 是槽位，**骨架固定**（内置模板不可改结构）
+    只填槽位内容——设置面板与模板页都能填（`template update --values`）；
+    新建任务时正文按槽位值渲染。
+  - **回调提示词**（全局，多条）：与收尾指令同一份存储与语义。
+  - **ack 完成总结提示词**（全局，多条，**新增**）：agent 写完成总结（ack）时的
+    格式要求，随领取交付的 `instruction` 一起给到 agent；占位符语法与收尾指令
+    同款（`{{task.id}}` / `{{goal.*}}` / 段落 `{{#goal}}…{{/goal}}`）。
+    **默认不配置 = 交付里不追加任何东西**（默认交付逐字不变）。
+    CLI 同口径：`localtask config --ack "<提示词>"`。
+- **共享的提示词编辑器**（`modules/prompts/`）：文本框 + 「占位符」插入菜单 +
+  已用占位符标记，回调提示词 / ack 提示词 / 持续 get 模板 / 模板槽位共用一份实现
+  ——此前三套长得不一样的编辑器，现在只有一套。
+- **面板模型收敛（任务 #33）**：工作区统一为四个区域——sidebar / maincontent /
+  rightSidebar / float；面板落点由一张**策略表**声明（单例与否一并声明），
+  打开新面板即替换主内容区（主区是**单面板位**）。页签与页签条彻底删除：
+  面板头部不再有 float / popup 标识，「清空本组全部页签」垃圾桶按钮一并移除；
+  顶部新增**面包屑**显示当前位置（如 `[ nx / nx-kv / #28 ]`）。老布局读盘
+  自动愈合（关页签条、补右侧栏）。
+- **DAG 依赖与闸门（任务 #34）**：`localtask add --block-by 12,13`（依赖：这些
+  任务全部完成后本条才可领取）、`--gate`（闸门：自身未完成前挡住队列里排在
+  后面的 pending）；`localtask update` 可改依赖 / 设清闸门。领取按 D-first 取
+  第一条**可领**的 pending，目录任务列表带「闸门 / 锁定」徽标。
+- **workflow 契约与引擎骨架（任务 #34 阶段 0）**：`core/workflow/` 冻结类型契约
+  （workflowId → 主题 key；对外稳定门面只有 submit / get；goal 是插件族：
+  block=调度侧、wait/time=消费侧）；`localtask` 拆出 store / bus / mutator /
+  scheduler 分层（唯一写快照入口 Mutator，原子覆盖）；`tasktool/plugins/`
+  目录扫描自注册（base / blockgoal / container / taskgoal / timegoal /
+  waitgoal），`tasktool/facade/` 收敛 submit / get / wait 门面。
+- **评论任务旁路原文**：工具栏「原文」或 Ctrl/⌘⇧O 在主区右侧并排打开锚定
+  原文（`frontmatter.parent`，旧数据从「锚定自…」回推），可单独关掉、不改路由。
+- **验收条 ack 按 md 渲染**：完成总结走正文同一套渲染；过长默认夹紧、
+  可展开全文（任务 #20）。
+
+### Changed
+
+- **面板贴图嵌入修复（任务 #15 再开）**：实时预览的块内光标坐标与源码全文偏移
+  分开（`insertAttachmentSnippet` 双坐标），落点禁止进 frontmatter；已落库任务
+  贴图后立刻 PATCH 同步服务端，不再等「保存并同步」——修掉「贴图上传成功但
+  正文未嵌入、agent 领取 attachments count: 0」。
+- **frontmatter 键自愈**：贴图误插撕出的残留键（`board:` 被撕成 `oard:` / `d:`）
+  解析时升回规范键、保存时写回（#15 / #23 案例），组面板不再丢任务。
+- **模板槽位不露 {{标记}}**：新建任务正文一律按槽位值渲染（缺省用内置默认值
+  兜底），`{{背景}}` 之类标记不再出现在任务正文里；设置面板「提示词 / 模板」
+  栏改左 tab 布局，槽位显示名字不给标记。
+- **右栏可关 + 进程面板跟随**：进程面板可关闭（右栏随之收起）；主区切到别的
+  任务时已开的进程面板同步跟随（#33 验收反馈）；侧栏收起入口挪到品牌行。
+- **面包屑带组名**：目录页面包屑显示 `[ 组 / 目录 / 任务 ]`（层级抽成纯函数
+  `crumbs.js`，面板与单测共用）。
+
+### Fixed
+
+- **float 面板（设置）自调用栈溢出**：`openPanel` 的 float 分支原先递归调
+  `openFloatingPanel`，表现是「设置按钮点了没反应」；改为直接走
+  「加进主区 → floatTab 浮出」，`openFloatingPanel` 只做委托。
+
 ## [0.18.0] - 2026-11-04 描述绑定文档 + 描述弹窗
 
 ### Changed

package/assets/kv-get/references/wait-workflow.md

@@ -97,6 +97,10 @@ wait 必带一句当前现状总结（≤2000 字，连续空白会折叠为单
   `{{goal.name}} {{goal.remainingHuman}} {{goal.prompt}} {{task.text}} {{source}} {{name}}…`，
   段落 `{{#goal}}…{{/goal}}` 上下文缺失整段消失；`--no-suffix` 关闭、
   `--reset-suffix` 恢复默认）。字段缺席 = 已关闭或本轮没有可渲染内容。
+- **ack 提示词（完成总结的格式要求）**：`nx-kv localtask config --ack "<提示词>"`
+  （占位符同上，多条）。配置后，它会随 `instruction` 一起交给你——按它要求的格式
+  写 `localtask done --summary "<完成总结>"` 即可；没配置时 `instruction` 里没有
+  这段，格式自便。设置面板「提示词 / 模板」一栏也能配。
 
 超时（exit 0，业务结果而非错误）：
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nx-kv",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "nx-kv — KV 清单管理中枢（远程）+ 本机本地任务队列（localtask）：serve 驱动 CLI 与 Web 面板，同源同构，附带可安装 skill 供 agent 提交 / 领取 / 阻塞接收任务",
   "type": "module",
   "bin": {

package/src/core/workflow/edges.js

@@ -0,0 +1,31 @@
+import { edgesFromTasks } from './types.js';
+
+export { edgesFromTasks };
+
+/**
+ * 从快照边表收集某节点的前驱 id。
+ * @param {import('./types.js').WorkflowSnapshot} snap
+ * @param {string|number} nodeId
+ */
+export function predecessorsOf(snap, nodeId) {
+  const id = String(nodeId);
+  const out = [];
+  for (const e of snap?.edges || []) {
+    if (String(e.to) === id) out.push(e.from);
+  }
+  return out;
+}
+
+/**
+ * 某节点的后继 id。
+ * @param {import('./types.js').WorkflowSnapshot} snap
+ * @param {string|number} nodeId
+ */
+export function successorsOf(snap, nodeId) {
+  const id = String(nodeId);
+  const out = [];
+  for (const e of snap?.edges || []) {
+    if (String(e.from) === id) out.push(e.to);
+  }
+  return out;
+}

package/src/core/workflow/event-names.js

@@ -0,0 +1,10 @@
+/** workflow EventBus 事件名（冻结） */
+export const EVENTS = Object.freeze({
+  WORKFLOW_CREATED: 'workflow:created',
+  DAG_MUTATED: 'dag:mutated',
+  NODE_STATE_CHANGED: 'node:stateChanged',
+  GOAL_BOUND: 'goal:bound',
+  GOAL_UNBOUND: 'goal:unbound',
+  GOAL_CONFIG_UPDATED: 'goal:configUpdated',
+  WORKFLOW_COMPLETED: 'workflow:completed',
+});

package/src/core/workflow/layout.js

@@ -0,0 +1,119 @@
+// workflow 目标目录规范（按 nx-kv 分层 + 语义子目录）。
+//
+// 原则
+//   1. 禁止平行顶层 src/{facade,store,mutator,scheduler,plugins}/。
+//      同名语义**必须**落在 modules 或 core/workflow 的子目录里。
+//   2. **全部 goal 同一目录、每种一份**——block / wait / time / task 都在
+//      tasktool/plugins/；禁止再拆「core 一份 + modules 一份」。
+//   3. localtask = 写侧（store/mutator/scheduler/bus）；
+//      tasktool = 消费门面 + goal 族；二者成对，允许互引
+//      （scheduler 调 blockgoal → import tasktool/plugins 即可）。
+//   4. 面板只吃 /api；两端同构投影才进 shared/。
+//   5. JS ESM only；子目录均带 index.js 桶文件对外导出。
+//
+// 依赖方向（单向）
+//   web → modules → core/workflow → Node 内置
+//   tasktool/facade ──▶ localtask/{store,mutator}
+//   localtask/scheduler ──▶ tasktool/plugins/blockgoal + core readiness + bus
+//   localtask/mutator ──▶ localtask/store
+//   tasktool/plugins/runtime ──▶ 同目录各 goal
+//
+// ---------------------------------------------------------------------------
+// 目标树（✅ 已有 / ○ 待落地 / → 自现状迁入）
+// ---------------------------------------------------------------------------
+//
+// src/core/workflow/
+// ├── types.js                          ✅
+// ├── snapshot.example.json             ✅
+// ├── layout.js                         ✅ 本规范
+// ├── readiness.js                      ✅ 自 dag 下沉
+// ├── edges.js                          ✅
+// ├── event-names.js                    ✅
+// └── plugin-registry.js                ✅ 按 name / scope 校验
+//
+// src/modules/localtask/
+// ├── index.js / service.js             ✅ 模块壳；complete → refreshTopicAfterComplete
+// ├── dag.js                            ✅ 再导出 readiness
+// ├── engine.js / writes.js             ✅ 主题引擎；DAG 日常写经 Mutator
+// ├── store/                            ✅ SnapshotStore + memory/file/topic adapter
+// ├── bus/ mutator/ scheduler/          ✅
+//
+// src/modules/tasktool/
+// ├── index.js                          ✅
+// ├── facade/                           ✅ submit/get/wait 再导出
+// ├── plugins/                          ✅ 目录扫描 IoC + 实现同目录
+// │   ├── discover.js                   扫描注册（跳过 *-store/*-config）
+// │   ├── *-store.js / waitgoal-config  原 timegoal/taskgoal/getloop 迁入
+// │   └── block|wait|time|task goal.js  definePlugin
+// ├── facade/                           ✅ submit→store+入队；get→AsyncIterable
+// ├── groupctx.js / attach.js           ✅
+// └── getloop/timegoal/taskgoal.js      ✅ 薄再导出 → plugins/*
+//
+// 为何 blockgoal 也进 tasktool/plugins（不留 core）
+//   goal 是插件族，视觉与注册平级；拆到 core 会造成「调度 goal 一套路径、
+//   消费 goal 另一套路径」。localtask↔tasktool 本就可配对互引，scheduler
+//   直接 import blockgoal 即可，无需为避依赖把家族拆开。
+//
+// ---------------------------------------------------------------------------
+
+/** @type {Readonly<Record<string, string>>} */
+export const TARGET_PATHS = Object.freeze({
+  'core types': 'src/core/workflow/types.js',
+  'snapshot example': 'src/core/workflow/snapshot.example.json',
+  'this layout norm': 'src/core/workflow/layout.js',
+  readiness: 'src/core/workflow/readiness.js',
+  'plugin registry': 'src/core/workflow/plugin-registry.js',
+  'store/': 'src/modules/localtask/store/',
+  'store barrel': 'src/modules/localtask/store/index.js',
+  'store file-adapter': 'src/modules/localtask/store/file-adapter.js',
+  'store memory-adapter': 'src/modules/localtask/store/memory-adapter.js',
+  'bus/': 'src/modules/localtask/bus/',
+  'bus barrel': 'src/modules/localtask/bus/index.js',
+  'mutator/': 'src/modules/localtask/mutator/',
+  'mutator barrel': 'src/modules/localtask/mutator/index.js',
+  'mutator validate': 'src/modules/localtask/mutator/validate.js',
+  'scheduler/': 'src/modules/localtask/scheduler/',
+  'scheduler barrel': 'src/modules/localtask/scheduler/index.js',
+  'scheduler state-drive': 'src/modules/localtask/scheduler/state-drive.js',
+  'facade/': 'src/modules/tasktool/facade/',
+  'facade barrel': 'src/modules/tasktool/facade/index.js',
+  'facade submit': 'src/modules/tasktool/facade/submit.js',
+  'facade get': 'src/modules/tasktool/facade/get.js',
+  'facade wait': 'src/modules/tasktool/facade/wait.js',
+  'plugins/': 'src/modules/tasktool/plugins/',
+  'plugins barrel': 'src/modules/tasktool/plugins/index.js',
+  'plugins runtime': 'src/modules/tasktool/plugins/runtime.js',
+  blockgoal: 'src/modules/tasktool/plugins/blockgoal.js',
+  waitgoal: 'src/modules/tasktool/plugins/waitgoal.js',
+  timegoal: 'src/modules/tasktool/plugins/timegoal.js',
+  taskgoal: 'src/modules/tasktool/plugins/taskgoal.js',
+});
+
+/** 全部 goal 唯一落点（同一目录；禁止第二份） */
+export const GOAL_HOMES = Object.freeze({
+  blockgoal: 'src/modules/tasktool/plugins/blockgoal.js',
+  waitgoal: 'src/modules/tasktool/plugins/waitgoal.js',
+  timegoal: 'src/modules/tasktool/plugins/timegoal.js',
+  taskgoal: 'src/modules/tasktool/plugins/taskgoal.js',
+});
+
+/** 必须出现的语义子目录（相对仓库根） */
+export const REQUIRED_SEMANTIC_DIRS = Object.freeze([
+  'src/modules/localtask/store',
+  'src/modules/localtask/bus',
+  'src/modules/localtask/mutator',
+  'src/modules/localtask/scheduler',
+  'src/modules/tasktool/facade',
+  'src/modules/tasktool/plugins',
+]);
+
+/** 禁止的平行顶层 */
+export const FORBIDDEN_TOP_LEVEL = Object.freeze([
+  'src/facade',
+  'src/store',
+  'src/mutator',
+  'src/scheduler',
+  'src/plugins',
+  'src/bus',
+  'src/core/types',
+]);

package/src/core/workflow/lifecycle.js

@@ -0,0 +1,58 @@
+// Workflow / Node / Plugin 生命周期（冻结）。插件只挂钩子，不拥有可变状态。
+//
+// ┌─ Workflow ──────────────────────────────────────────────┐
+// │  created ──▶ active ──▶ completed | failed              │
+// │     │           │                                       │
+// │     │           ├─ Mutator 改拓扑/goal → dag:mutated     │
+// │     │           ├─ Scheduler onSchedule（永不 onGet）     │
+// │     │           └─ Facade get → onGet 消费流             │
+// └─────────────────────────────────────────────────────────┘
+//
+// ┌─ Node ──────────────────────────────────────────────────┐
+// │  pending ──▶ ready ──▶ running ──▶ success | failed     │
+// │     ▲          │          │                             │
+// │     └─ 屏障加回  │          └─ done / worker              │
+// │                └─ Scheduler driveReadyStates            │
+// └─────────────────────────────────────────────────────────┘
+//
+// ┌─ Plugin 实例钩子（按绑定点注入）──────────────────────────┐
+// │  onBind        Mutator.bindPlugin 时：校验并规范化 config │
+// │  onSchedule    Scheduler 轮：仅 scope=control（blockgoal）│
+// │  onGet         Facade get：scope=workflow|node 消费流     │
+// │  onUnbind      Mutator.unbindPlugin 时：可选清理（无状态） │
+// │                                                         │
+// │  叠加：workflow.timegoal 包裹 node.waitgoal               │
+// │  约束：调度链禁止调 onGet；消费链禁止写快照（只读 ctx）     │
+// └─────────────────────────────────────────────────────────┘
+
+/** @typedef {'created'|'active'|'completed'|'failed'} WorkflowPhase */
+/** @typedef {'pending'|'ready'|'running'|'success'|'failed'} NodePhase */
+/** @typedef {'onBind'|'onSchedule'|'onGet'|'onUnbind'} PluginHook */
+
+export const WORKFLOW_PHASES = Object.freeze([
+  'created',
+  'active',
+  'completed',
+  'failed',
+]);
+
+export const NODE_PHASES = Object.freeze([
+  'pending',
+  'ready',
+  'running',
+  'success',
+  'failed',
+]);
+
+/** 插件可实现的钩子；未实现视为空操作 */
+export const PLUGIN_HOOKS = Object.freeze(['onBind', 'onSchedule', 'onGet', 'onUnbind']);
+
+/**
+ * 哪条执行链会调用哪个钩子。
+ * @type {Readonly<Record<'schedule'|'get'|'mutate', PluginHook[]>>}
+ */
+export const HOOK_CHAINS = Object.freeze({
+  mutate: Object.freeze(['onBind', 'onUnbind']),
+  schedule: Object.freeze(['onSchedule']),
+  get: Object.freeze(['onGet']),
+});

package/src/core/workflow/plugin-registry.js

@@ -0,0 +1,47 @@
+import { BUILTIN_GOALS, GOAL_SCOPES } from './types.js';
+
+/** @typedef {import('./types.js').GoalScope} GoalScope */
+/** @typedef {import('./types.js').PluginSpec} PluginSpec */
+
+/** @type {Map<string, { name: string, scope: GoalScope }>} */
+const registry = new Map();
+
+export function registerPluginMeta(name, scope) {
+  if (!name || typeof name !== 'string') throw new Error('plugin name required');
+  if (!GOAL_SCOPES.includes(scope)) throw new Error(`invalid goal scope: ${scope}`);
+  registry.set(name, { name, scope });
+  return registry.get(name);
+}
+
+export function getPluginMeta(name) {
+  return registry.get(name) || null;
+}
+
+export function listPluginMetas() {
+  return [...registry.values()];
+}
+
+/** 校验 PluginSpec：已注册且 scope 匹配（未注册则只认内置名） */
+export function assertPluginSpec(spec) {
+  if (!spec || typeof spec !== 'object') throw new Error('PluginSpec required');
+  const name = String(spec.name || '');
+  if (!name) throw new Error('PluginSpec.name required');
+  const meta = registry.get(name);
+  const scope = spec.scope || meta?.scope;
+  if (!scope || !GOAL_SCOPES.includes(scope)) {
+    throw new Error(`PluginSpec.scope invalid for ${name}`);
+  }
+  if (meta && meta.scope !== scope) {
+    throw new Error(`plugin ${name} scope must be ${meta.scope}, got ${scope}`);
+  }
+  if (!meta && !Object.values(BUILTIN_GOALS).includes(name) && name !== 'taskgoal') {
+    throw new Error(`unknown plugin: ${name}`);
+  }
+  return { name, scope, config: spec.config && typeof spec.config === 'object' ? spec.config : {} };
+}
+
+// 内置登记（实现落在 tasktool/plugins；此处只登记元数据）
+registerPluginMeta(BUILTIN_GOALS.blockgoal, 'control');
+registerPluginMeta(BUILTIN_GOALS.waitgoal, 'node');
+registerPluginMeta(BUILTIN_GOALS.timegoal, 'workflow');
+registerPluginMeta('taskgoal', 'node');

package/src/core/workflow/project.js

@@ -0,0 +1,108 @@
+// 主题队列（localtask topic.tasks）↔ WorkflowSnapshot 双向投影。
+// 存盘形状仍是任务行；快照是引擎视图。正文不进快照（payload.textRef）。
+
+import { BUILTIN_GOALS, edgesFromTasks, taskToNode } from './types.js';
+
+/** @typedef {import('./types.js').WorkflowSnapshot} WorkflowSnapshot */
+/** @typedef {import('./types.js').WfNode} WfNode */
+
+/**
+ * @param {object} topic  localtask 主题桶
+ * @returns {WorkflowSnapshot}
+ */
+export function topicToSnapshot(topic) {
+  const workflowId = String(topic?.key || topic?.workflowId || '');
+  const tasks = Array.isArray(topic?.tasks) ? topic.tasks : [];
+  const nodes = tasks.filter((t) => t && !t.deletedAt && !t.migratedTo).map(taskToNode);
+  const edges = edgesFromTasks(tasks);
+  const revision = Number(topic?.workflowRevision) || 0;
+  /** @type {WorkflowSnapshot} */
+  return {
+    workflowId,
+    state: topic?.workflowState || 'active',
+    nodes,
+    edges,
+    workflowPlugins: Array.isArray(topic?.workflowPlugins) ? topic.workflowPlugins : [],
+    revision,
+    updatedAt: topic?.updatedAt || new Date().toISOString(),
+    meta: {
+      cwd: topic?.cwd || '',
+      name: topic?.name || '',
+    },
+  };
+}
+
+/**
+ * 把快照写回主题任务行（保守：不改 text；按 id 对齐）。
+ * @param {object} topic
+ * @param {WorkflowSnapshot} snap
+ */
+export function applySnapshotToTopic(topic, snap) {
+  if (!topic || !snap) return topic;
+  const tasks = Array.isArray(topic.tasks) ? topic.tasks : (topic.tasks = []);
+  const byId = new Map(tasks.map((t) => [String(t.id), t]));
+
+  for (const node of snap.nodes || []) {
+    let task = byId.get(String(node.id));
+    if (!task) {
+      // 引擎新建的节点 → 补一条占位任务（正文外置占位）
+      task = {
+        id: Number(node.id) || node.id,
+        text: '',
+        status: 'pending',
+        createdAt: new Date().toISOString().replace('T', ' ').slice(0, 19),
+        completedAt: '',
+        deletedAt: '',
+        blockBy: [],
+        blocksFollowing: false,
+      };
+      tasks.push(task);
+      byId.set(String(task.id), task);
+    }
+    syncTaskFromNode(task, node);
+  }
+
+  // 边 → blockBy（显式依赖）；闸门边由 blocksFollowing 表达，不写进每条 blockBy
+  const gateIds = new Set(
+    (snap.nodes || [])
+      .filter(
+        (n) =>
+          n.kind === 'control' ||
+          (n.plugins || []).some((p) => p.name === BUILTIN_GOALS.blockgoal),
+      )
+      .map((n) => String(n.id)),
+  );
+
+  for (const task of tasks) {
+    if (task.deletedAt || task.migratedTo) continue;
+    const incoming = (snap.edges || []).filter((e) => String(e.to) === String(task.id));
+    const deps = [];
+    for (const e of incoming) {
+      // 跳过「闸门挡后续」推出来的边：from 是闸门且闸门在数组序上早于本任务时由 blocksFollowing 覆盖
+      if (gateIds.has(String(e.from))) continue;
+      deps.push(e.from);
+    }
+    task.blockBy = deps.map((d) => Number(d)).filter((n) => Number.isFinite(n) && n > 0);
+  }
+
+  topic.workflowRevision = Number(snap.revision) || 0;
+  topic.workflowState = snap.state || 'active';
+  topic.workflowPlugins = Array.isArray(snap.workflowPlugins) ? snap.workflowPlugins : [];
+  if (snap.updatedAt) topic.updatedAt = snap.updatedAt;
+  return topic;
+}
+
+/** @param {object} task @param {WfNode} node */
+function syncTaskFromNode(task, node) {
+  const hasBlock = (node.plugins || []).some((p) => p.name === BUILTIN_GOALS.blockgoal);
+  task.blocksFollowing = node.kind === 'control' || hasBlock;
+
+  if (node.state === 'success') {
+    if (!task.completedAt) {
+      task.completedAt = new Date().toISOString().replace('T', ' ').slice(0, 19);
+    }
+  } else if (node.state === 'running' && task.status !== 'consumed') {
+    task.status = 'consumed';
+  }
+  // pending/ready：不改 status（领取态由 wait/get 管；ready 由 isReadyToClaim 现算）
+}

package/src/core/workflow/readiness.js

@@ -0,0 +1,98 @@
+// 拓扑就绪（自 localtask/dag.js 下沉）。任务行与快照节点两套入口。
+
+/** 规范化 blockBy：正整数 id、去重、丢掉自身 */
+export function normalizeBlockBy(raw, selfId) {
+  const self = Number(selfId);
+  const seen = new Set();
+  const out = [];
+  for (const x of Array.isArray(raw) ? raw : []) {
+    const n = Number(x);
+    if (!Number.isFinite(n) || n <= 0) continue;
+    if (Number.isFinite(self) && n === self) continue;
+    if (seen.has(n)) continue;
+    seen.add(n);
+    out.push(n);
+  }
+  return out;
+}
+
+function isAlive(t) {
+  return t && !t.deletedAt && !t.migratedTo;
+}
+
+function isCompleted(t) {
+  return isAlive(t) && !!t.completedAt;
+}
+
+function isPendingLike(t) {
+  return isAlive(t) && t.status !== 'consumed';
+}
+
+/**
+ * 某条 pending 现在能不能领（任务行模型）。
+ * @param {object} task
+ * @param {object[]} all
+ */
+export function isReadyToClaim(task, all = []) {
+  if (!isPendingLike(task)) return false;
+  const byId = new Map((all || []).filter(isAlive).map((t) => [Number(t.id), t]));
+
+  const deps = normalizeBlockBy(task.blockBy, task.id);
+  for (const id of deps) {
+    const dep = byId.get(id);
+    if (!dep) continue;
+    if (!isCompleted(dep)) return false;
+  }
+
+  const idx = (all || []).indexOf(task);
+  const order = all || [];
+  const myPos = idx >= 0 ? idx : order.findIndex((t) => Number(t.id) === Number(task.id));
+  if (myPos < 0) return true;
+  for (let i = 0; i < myPos; i += 1) {
+    const prev = order[i];
+    if (!isAlive(prev) || !prev.blocksFollowing) continue;
+    if (!isCompleted(prev)) return false;
+  }
+  return true;
+}
+
+/** 按数组序找第一条可领取的 pending；没有 → null */
+export function findFirstReadyPending(tasks = []) {
+  for (const t of tasks || []) {
+    if (isReadyToClaim(t, tasks)) return t;
+  }
+  return null;
+}
+
+/**
+ * 快照节点是否就绪（边 + control/blockgoal 前驱须 success）。
+ * @param {import('./types.js').WorkflowSnapshot} snap
+ * @param {import('./types.js').WfNode} node
+ * @param {(snap: import('./types.js').WorkflowSnapshot, nodeId: string|number) => boolean} [isBarrierOpen]
+ */
+export function isNodeReady(snap, node, isBarrierOpen) {
+  if (!node || node.state === 'success' || node.state === 'failed' || node.state === 'running') {
+    return false;
+  }
+  if (node.state !== 'pending' && node.state !== 'ready') return false;
+
+  const preds = (snap.edges || []).filter((e) => String(e.to) === String(node.id));
+  const byId = new Map((snap.nodes || []).map((n) => [String(n.id), n]));
+
+  for (const e of preds) {
+    const pred = byId.get(String(e.from));
+    if (!pred) continue;
+    const isControl =
+      pred.kind === 'control' ||
+      (pred.plugins || []).some((p) => p.name === 'blockgoal' || p.scope === 'control');
+    if (isControl) {
+      const open = isBarrierOpen
+        ? isBarrierOpen(snap, pred.id)
+        : pred.state === 'success';
+      if (!open) return false;
+      continue;
+    }
+    if (pred.state !== 'success') return false;
+  }
+  return true;
+}

package/src/core/workflow/snapshot.example.json

@@ -0,0 +1,46 @@
+{
+  "workflowId": "local/nx-kv",
+  "state": "active",
+  "revision": 1,
+  "updatedAt": "2026-11-04T08:00:00.000Z",
+  "workflowPlugins": [
+    {
+      "name": "timegoal",
+      "scope": "workflow",
+      "config": { "duration": "45m", "prompt": "目录级静默超时示例" }
+    }
+  ],
+  "nodes": [
+    {
+      "id": 10,
+      "kind": "task",
+      "state": "success",
+      "plugins": [],
+      "payload": { "textRef": true }
+    },
+    {
+      "id": 11,
+      "kind": "control",
+      "state": "running",
+      "plugins": [{ "name": "blockgoal", "scope": "control", "config": {} }],
+      "payload": { "textRef": true }
+    },
+    {
+      "id": 12,
+      "kind": "task",
+      "state": "pending",
+      "plugins": [
+        {
+          "name": "waitgoal",
+          "scope": "node",
+          "config": { "waitMinutes": 3 }
+        }
+      ],
+      "payload": { "textRef": true }
+    }
+  ],
+  "edges": [
+    { "from": 10, "to": 11 },
+    { "from": 11, "to": 12 }
+  ]
+}