nx-kv 0.18.0 → 0.20.0

package/CHANGELOG.md

@@ -2,6 +2,173 @@
 
 本文件记录对外可见的变更。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)。
 
+## [0.20.0] - 2026-11-04 任务编排（DAG）进面板 + 面包屑/设置面板收拾 + 改归属项目即搬家
+
+### Added
+
+- **任务编排（DAG）进面板（任务 #40）**：目录落地页任务表与项目组「本组任务」列表支持编排——
+  - **拖动排序**：目录任务表待领取行可拖动换位（落点=上半行前/下半行后，青绿线指示），
+    走既有 `localtask reorder`（已领取行是固定历史，不可拖）；
+  - **编排编辑器**（行尾「⋮」→「编排依赖…」）：闸门开关、上游依赖（我等谁）、
+    下游任务（谁等我，逐条改对方 blockBy）三段勾选，保存前客户端查环——
+    会成环的组合直接禁用；闸门开启时上游段禁用并清空、下游自动覆盖（引擎约束对齐：
+    闸门的隐含边与上游边成环，`applySnapshotToTopic` 亦把闸门显式后继按冗余剪除）；
+  - **组页按队列表达**：组任务横跨多个成员队列，编排以**该任务所属队列**为作用域
+    （候选/闸门下游都取本队列），闸门×N 与锁定徽章上屏；
+  - 闸门徽章升级：显示被挡后续数（`闸门×N`，悬停列出 #id）。
+- 组任务行尾新增「⋮」行菜单（编排依赖 / 闸门开关），待领取行悬停可见。
+
+### Changed
+
+- **设置面板观感重做（任务 #41 重开反馈「ui 太丑了」→ 二轮「更丑了」）**：交互语义不变，只收拾
+  密度与层级——「提示词 / 模板」栏的竖排 tab 侧栏改成顶部一排药丸、内容限宽；提示词条目行去描边、
+  编号不用圆圈、**收起标题洗掉原始模板标记**（不再直接甩 `{{#goal}}〔…〕` 给人看）；操作条分隔线分组；
+  项目级设置从大卡片改成紧凑行（项目多时一屏 8 个而不是 2 个），「持续 get」关着时只留一枚行内小开关；
+  「提示词 / 模板」栏不再套卡（盒中盒显脏）。：交互语义不变，只收拾
+  密度与层级——「提示词 / 模板」栏的竖排 tab 侧栏改成顶部一排药丸、内容限宽；
+  提示词条目行去描边、编号不用圆圈；操作条分隔线分组；项目级设置从大卡片改成
+  紧凑行（项目多时一屏 8 个而不是 2 个），「持续 get」关着时只留一枚行内小开关。
+
+### Changed
+
+- **面包屑移到 maincontent 面板内顶部（任务 #44）**：路径条不再占窗口顶部通栏
+  （那是侧栏的地盘），改成挂在**当前主面板**顶部的一枚小药丸——目录任务表 /
+  任务详情页 / 项目组 / 全部目录总览 / 云端总览 / 仓库管理 / 任务模板 各面板
+  根部都有一条；MD 工作台里则直接放进顶部工具栏（`mdw-top`）内、标题左侧；
+  「← 返回」随路径条一起搬进面板（按来处返回的行为不变）。：路径条不再占窗口顶部通栏
+  （那是侧栏的地盘），改成挂在**当前主面板**顶部的一枚小药丸——目录任务表 /
+  任务详情页 / 项目组 / 全部目录总览 / 云端总览 / 仓库管理 / 任务模板 各面板
+  根部都有一条；「← 返回」随路径条一起搬进面板（按来处返回的行为不变）。
+
+### Fixed
+
+- **改归属项目即搬家（任务 #43「提交任务后发现归属项目填错了，重新修改提交无效」）**：
+  此前「归属决定落点」只在提交那一刻生效——提交后发现归属填错，改正文里的 project 再保存，
+  正文改了队列没动：任务还挂在旧项目队列里，旧项目的 agent 照旧领走，新项目的 agent 永远
+  看不见，组面板/目录页也都显示旧归属。现在 `localtask update --text` / `localtask reopen --text`
+  / 面板「保存并同步 / 重做」走与派任务同一套落点判定：effective frontmatter.project 解析到
+  哪个登记项目，任务就迁到哪个队列；介绍引用（projectIntro/projectDesc）随归属刷新。
+  约束如实说明：已领取的任务不能改归属（要改先 reopen）；带队列内依赖/闸门的任务搬运会
+  跨队列断链，先解除再改（明确报错，不静默）；搬家后任务拿到**新队列的 id**（面板页签自动
+  跟到新号，CLI 输出标注迁移）；指向它的跨队列引用（`topicKey:id`）改写到新地址。
+  另自愈历史脏数据：归属字段与所在队列对不上（上一轮只改字段没搬队列的残留）时，
+  保存即搬到归属队列；已领取/带队列内依赖的脏数据不搬也不拦普通编辑。
+
+- **顶部面包屑真正可见 + 补返回键（任务 #42）**：面包屑此前**渲染了却看不见**——
+  FlexLayout 的根是绝对定位（inset:0），铺满工作区把 26px 的路径条盖在下面
+  （侧栏面板压在上面，路径条点不到也看不见）。现在工作区有面包屑时布局整体下移一条；
+  侧栏也不再出页签条（#33「无页签化」的残留，页签条同样压在路径条上）。
+  面包屑条左侧新增「← 返回」：按**来处**返回（会话内路由历史栈）——
+  从项目组点任务（任务住在 dir 队列里，详情页落在 dir 作用域）时，返回会回到**组**
+  而不是掉进目录；没有上一级时不画返回键。
+
+### Changed
+
+- **可视化编排面板（任务 #40 验收反馈重开）**：目录与项目组**共用**一块编排面板，
+  从任务面板**头部右侧的绿色超链**进入（开在右侧主内容区）：
+  - **节点 = 小圆角卡片**，画布带网格底；节点纵向位置 = 队列顺序；
+  - **拖拽排序**：拖节点即改队列顺序（已领取节点是固定历史，不可拖）；
+  - **连线建立有向依赖**：从节点左侧把手拉到另一个节点 = 后者等前者（写入 blockBy）；
+    依赖边以曲线 + 箭头画在画布左侧，节点上显示「等 #N」芯片（可一键解除）；
+  - **节点工具**：设为闸门（挡住后续）/ 加时间目标（timegoal）/ 打开任务；
+  - 组视图进来可在**成员队列之间切换**（DAG 的排序/依赖/闸门都是队列内的）；
+  - 编排只改被碰过的那几项，没编排过的节点保持原队列序。
+- **设置面板交互收敛（任务 #41）**：
+  - **左边 tab 悬停即切换**（设置外层分区导航 + 「提示词 / 模板」栏内的三个分类），
+    点击保留为兜底；少一次点击。
+  - **提示词条目默认收起成标题行**（首行截断 + 字数），**点击才展开编辑**（单开手风琴）；
+    「添加一条…」新增后直接展开待填。
+  - **说明文字全部删除**：设置面板右侧的静态说明段（工作区/任务工具/项目级等）与
+    提示词栏的提示段一并清掉，只留状态与操作。
+  - **项目级「持续 get」一句话配置**：选模板（内置默认 + 全局回调提示词条目）→ 改一句话
+    （`%s` = 任务编号，存取时与 `{{task.id}}` 互转）→ 添加；不再手写整段模板。
+
+### Added
+
+- `localtask config --suffix-list "一条,二条"` / `--ack-list "一条,二条"`：**整体替换**多条
+  提示词列表（逗号分隔；HTTP body 传数组）。此前 action 只暴露单条 `--suffix`/`--ack`，
+  面板的多条保存无处可传（#41 实测发现并修）。
+
+### Fixed
+
+- **首次打开设置面板爆栈**（任务 #41 实测发现，#33 遗留）：`openPanel` 按区域分发时
+  FLOAT → `openFloatingPanel` → `openPanel`（未带 area）→ 又判成 FLOAT → 无限递归
+  （"Maximum call stack size exceeded"）。老布局因已存着设置浮窗、走 existing 早退而侥幸
+  没踩到，全新档案首次打开必崩。内层调用显式指定 `AREA.MAIN` 后收敛。
+- **回调 / ack 提示词在面板上保存不了**（任务 #41 实测发现，#32 遗留）：面板打的是
+  `taskSuffix`/`ackPrompt` 字段，action 未声明 → 请求 400 且**静默无效**（面板回显旧列表，
+  看起来像保存成功）。改为 `suffixList`/`ackList`（对应上面新增的列表 flag）后真正落库。
+- 侧栏搜索框降高响应式（任务 #38）：`label.sbox` 28px→24px 显式定高；「＋」按钮
+  `flex:none` 永不被挤掉；侧栏按实际像素宽分档降级（≤256 收间距 / ≤195 藏撤销重做 /
+  ≤150 藏标题+放大镜 / ≤125 藏品牌字+匹配数），高频件（搜索框、＋、收起/关闭、齿轮）
+  永远在场；`nx-title` 窄宽折两行一并修复。
+- 面板 maximize 键全线下线（任务 #39）：`tabSetEnableMaximize=false` 一关全断
+  （页签条 Maximize/Restore 按钮、右键菜单最大化项、双击标题栏最大化都走
+  `canMaximize()` 门控）；连带清理死翻译与死 CSS 变量。
+- 目录/组任务行的「⋮」菜单点击不再冒泡打开任务详情（stopPropagation）。
+
+## [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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nx-kv",
-  "version": "0.18.0",
+  "version": "0.20.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,114 @@
+// 主题队列（localtask topic.tasks）↔ WorkflowSnapshot 双向投影。
+// 存盘形状仍是任务行；快照是引擎视图。正文不进快照（payload.textRef）。
+// 跨队列 blockBy（"topicKey:id"）不进引擎边，投影回写时必须保留。
+
+import { BUILTIN_GOALS, edgesFromTasks, taskToNode } from './types.js';
+import { normalizeBlockBy, parseDepRef } from './readiness.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 keepForeign = normalizeBlockBy(task.blockBy, task.id).filter(
+      (d) => parseDepRef(d)?.kind === 'foreign',
+    );
+    const incoming = (snap.edges || []).filter((e) => String(e.to) === String(task.id));
+    const localDeps = [];
+    for (const e of incoming) {
+      // 跳过「闸门挡后续」推出来的边：from 是闸门且闸门在数组序上早于本任务时由 blocksFollowing 覆盖
+      if (gateIds.has(String(e.from))) continue;
+      const n = Number(e.from);
+      if (Number.isFinite(n) && n > 0) localDeps.push(n);
+    }
+    task.blockBy = normalizeBlockBy([...localDeps, ...keepForeign], task.id);
+  }
+
+  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 现算）
+}