nx-kv 0.21.0 → 0.23.0

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 本文件记录对外可见的变更。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)。
 
+## [0.23.0] - 2026-11-05 定位轨可拖动
+
+### Added
+
+- **任务页 ack 定位轨支持拖动（任务 #55）**：按住汉堡钮把整条轨拖到正文区内任意位置，
+  双击回默认钉位；落点存 localStorage，重开面板还在。单击（位移 <4px）仍是展开/收起，
+  拖动不会误触；拖到容器边缘自动钳回界内。
+  - 实现注意一：钉位态的轨盒子被 `top/bottom` 双锚拉满（`bottom:44px` → 高 760），
+    钳制必须用**临时解除底锚量出的自然高**（同帧同步量取再恢复，子元素本来就堆在
+    顶部，无视觉跳动）——直接用拉伸盒高会把第一次拖动错钳到容器顶部。
+  - 实现注意二：落点存盘用**拖动会话里的最终落点**（`pointerup` 时 React 状态可能
+    还未提交，读 state 会存回拖动前的旧位置，等于白拖）。
+  - 落点纯逻辑（钳制 + 存取）独立成 `modules/board/ack-rail-pos.js`，node 单测
+    `tests/unit/ack-rail-pos.test.mjs` 6 条；端到端 Playwright 探针（隔离 store +
+    临时端口 7879 + 本机 Chrome）11 条断言全过：跟手、越界钳制、拖完即持久化、
+    拖后 click 不误触、展开态拖动、重开还原、双击回默认位、零 console error。
+
+## [0.22.0] - 2026-11-05 任务页 ack 定位轨
+
+### Added
+
+- **任务页 ack 定位轨（任务 #48）**：反复 ack 反馈的任务（正文一轮一轮变长，#34 有 5 轮、
+  正文 13903 字符）在右侧多一条定位轨——**一轮一个节点**，点一下直接跳到那一轮的
+  「上一轮完成总结」。复用简介页那套定位轨的视觉（`.doc-rail`），但定位方式不同：
+  按**块序号**跳，不按标题锚点跳。
+  - 为什么不用标题锚点：实时预览态逐块渲染，每块各有一套标题 id 生成器，于是同名标题在
+    DOM 里拿到的是**重复的同一个 id**（两个「## 上一轮完成总结」都是同一个 id）——
+    按 id 跳永远落在第一轮。块序号（`data-i`）才唯一。
+  - 阅读态（整篇一次性渲染）没有块元素，改按「第 N 个 ack 标题」定位——该态标题 id 互不相同。
+  - 轮次从**正文**抽（每轮一个「## 上一轮完成总结」段）：正文即历史，改完正文轨立刻跟着变。
+  - 只有一个节点时不显示（没有可跳的多轮，挂了也是噪音）。
+
 ## [0.21.0] - 2026-11-05 队列与编排的职责单一化 + store 损坏防护
 
 ### Fixed
@@ -42,51 +74,23 @@
   - 闸门徽章升级：显示被挡后续数（`闸门×N`，悬停列出 #id）。
 - 组任务行尾新增「⋮」行菜单（编排依赖 / 闸门开关），待领取行悬停可见。
 
+- `localtask config --suffix-list "一条,二条"` / `--ack-list "一条,二条"`：**整体替换**多条
+  提示词列表（逗号分隔；HTTP body 传数组）。此前 action 只暴露单条 `--suffix`/`--ack`，
+  面板的多条保存无处可传（#41 实测发现并修）。
+
 ### 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 验收反馈重开）**：目录与项目组**共用**一块编排面板，
   从任务面板**头部右侧的绿色超链**进入（开在右侧主内容区）：
@@ -107,13 +111,27 @@
   - **项目级「持续 get」一句话配置**：选模板（内置默认 + 全局回调提示词条目）→ 改一句话
     （`%s` = 任务编号，存取时与 `{{task.id}}` 互转）→ 添加；不再手写整段模板。
 
-### Added
+### Fixed
 
-- `localtask config --suffix-list "一条,二条"` / `--ack-list "一条,二条"`：**整体替换**多条
-  提示词列表（逗号分隔；HTTP body 传数组）。此前 action 只暴露单条 `--suffix`/`--ack`，
-  面板的多条保存无处可传（#41 实测发现并修）。
+- **改归属项目即搬家（任务 #43「提交任务后发现归属项目填错了，重新修改提交无效」）**：
+  此前「归属决定落点」只在提交那一刻生效——提交后发现归属填错，改正文里的 project 再保存，
+  正文改了队列没动：任务还挂在旧项目队列里，旧项目的 agent 照旧领走，新项目的 agent 永远
+  看不见，组面板/目录页也都显示旧归属。现在 `localtask update --text` / `localtask reopen --text`
+  / 面板「保存并同步 / 重做」走与派任务同一套落点判定：effective frontmatter.project 解析到
+  哪个登记项目，任务就迁到哪个队列；介绍引用（projectIntro/projectDesc）随归属刷新。
+  约束如实说明：已领取的任务不能改归属（要改先 reopen）；带队列内依赖/闸门的任务搬运会
+  跨队列断链，先解除再改（明确报错，不静默）；搬家后任务拿到**新队列的 id**（面板页签自动
+  跟到新号，CLI 输出标注迁移）；指向它的跨队列引用（`topicKey:id`）改写到新地址。
+  另自愈历史脏数据：归属字段与所在队列对不上（上一轮只改字段没搬队列的残留）时，
+  保存即搬到归属队列；已领取/带队列内依赖的脏数据不搬也不拦普通编辑。
 
-### Fixed
+- **顶部面包屑真正可见 + 补返回键（任务 #42）**：面包屑此前**渲染了却看不见**——
+  FlexLayout 的根是绝对定位（inset:0），铺满工作区把 26px 的路径条盖在下面
+  （侧栏面板压在上面，路径条点不到也看不见）。现在工作区有面包屑时布局整体下移一条；
+  侧栏也不再出页签条（#33「无页签化」的残留，页签条同样压在路径条上）。
+  面包屑条左侧新增「← 返回」：按**来处**返回（会话内路由历史栈）——
+  从项目组点任务（任务住在 dir 队列里，详情页落在 dir 作用域）时，返回会回到**组**
+  而不是掉进目录；没有上一级时不画返回键。
 
 - **首次打开设置面板爆栈**（任务 #41 实测发现，#33 遗留）：`openPanel` 按区域分发时
   FLOAT → `openFloatingPanel` → `openPanel`（未带 area）→ 又判成 FLOAT → 无限递归
@@ -575,7 +593,6 @@
   - **实时预览块级查找**：Ctrl/⌘F 在预览态可用，n/m 计数 + 命中块高亮 + 滚动定位
   - **无障碍**：编辑区 aria-label 补齐、状态栏小字对比度提到 WCAG AA
 
-
 - **仓库获得全局唯一 key，导入导出改以 key 为身份（v3）+ 全屏导入导出面板**：
   - **key**：归一化远程地址派生（`git@c:o/r.git`、`https://c/o/r`、
     `ssh://git@ssh.github.com:443/o/r.git`、带端口、带 `.git` 都是同一个

package/package.json

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

package/src/core/workflow/project.js

@@ -64,16 +64,20 @@ export function applySnapshotToTopic(topic, snap) {
     syncTaskFromNode(task, node);
   }
 
-  // 边 → blockBy（显式依赖）；闸门边由 blocksFollowing 表达，不写进每条 blockBy
+  // 边 → blockBy（显式依赖）；闸门边由 blocksFollowing 表达，不写进每条 blockBy。
+  // 本地依赖取「现有 ∪ 快照边」的**并集**而不是按边重建：快照可能滞后于外部任务行写
+  // （引擎在途写），按边重建会把外部刚设好的 blockBy 洗掉。依赖是「只能多、不能凭空少」
+  // 的保守口径——解除依赖一律走外部 clear 先落盘，再由 syncTaskDagUpdate 拆边，
+  // 不存在「只删引擎边、不删任务行」的路径，所以并集不会让解除失效。
   const gateIds = new Set(
     (snap.nodes || []).filter((n) => isGateNode(n)).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 keep = normalizeBlockBy(task.blockBy, task.id);
+    const keepForeign = keep.filter((d) => parseDepRef(d)?.kind === 'foreign');
+    const keepLocal = keep.filter((d) => parseDepRef(d)?.kind === 'local');
     const incoming = (snap.edges || []).filter((e) => String(e.to) === String(task.id));
     const localDeps = [];
     for (const e of incoming) {
@@ -82,7 +86,7 @@ export function applySnapshotToTopic(topic, snap) {
       const n = Number(e.from);
       if (Number.isFinite(n) && n > 0) localDeps.push(n);
     }
-    task.blockBy = normalizeBlockBy([...localDeps, ...keepForeign], task.id);
+    task.blockBy = normalizeBlockBy([...keepLocal, ...localDeps, ...keepForeign], task.id);
   }
 
   topic.workflowRevision = Number(snap.revision) || 0;

package/src/modules/localtask/move-prims.js

@@ -2,7 +2,7 @@
 // 迁出 tombstone（目标端写成功后才调用）、撤销迁出、云端回插待领取首位。
 import { badInput } from '../../core/errors.js';
 import { normalizeCwd, resolveTaskKey } from './paths.js';
-import { loadStore, saveStore, stampNow, normalizeText, topicOf, nextTaskId } from './store-io.js';
+import { loadStore, saveStore, stampNow, normalizeText, topicOf, nextTaskId, bumpWorkflowRevision } from './store-io.js';
 import { normalizeTask, isPending } from './task-view.js';
 // ─── 迁移原语（task move 用；store 封装不外泄）─────────────────────
 //
@@ -43,6 +43,7 @@ export async function markTaskMigrated({ cwd: rawCwd, key: rawKey, id, migratedT
   }
   raw.migratedTo = { side: 'cloud', topic: String(migratedTo.topic || ''), targetId: Number(migratedTo.targetId) || 0, at: String(migratedTo.at || stampNow()) };
   t.updatedAt = stampNow();
+  bumpWorkflowRevision(t);
   await saveStore(store);
   return { status: 'ok', key, cwd: t.cwd || '', name: t.name, task: normalizeTask(raw) };
 }
@@ -70,6 +71,7 @@ export async function clearTaskMigrated({ cwd: rawCwd, key: rawKey, id, toTop =
     t.tasks.unshift(raw);
   }
   t.updatedAt = stampNow();
+  bumpWorkflowRevision(t);
   await saveStore(store);
   return { status: 'ok', restored: true, key, cwd: t.cwd || '', name: t.name, task: normalizeTask(raw) };
 }
@@ -90,6 +92,7 @@ export async function insertTaskAtTop({ cwd: rawCwd, key: rawKey, text, from = '
   if (firstPending >= 0) t.tasks.splice(firstPending, 0, task);
   else t.tasks.unshift(task);
   t.updatedAt = stampNow();
+  bumpWorkflowRevision(t);
   await saveStore(store);
   return { status: 'ok', key, cwd: t.cwd || cwd, name: t.name, task };
 }

package/src/modules/localtask/store-io.js

@@ -248,6 +248,19 @@ export function nextTaskId(tasks) {
   }
   return max + 1;
 }
+
+// 外部写（不经引擎 Mutator）落盘前把主题的 workflowRevision 顶一格。
+// 为什么必须：引擎侧落盘有 revision CAS（saveAtomic），但这条 CAS 只对「引擎自己的写」
+// 成立——外部改任务行（设 blockBy / 领取 / 完成 / 删除）不动 revision，引擎**在途**的
+// 过期快照（scheduler 定时器 / close 没等到的 runOnce）落盘时 CAS 照样通过，
+// applySnapshotToTopic 会把过期边**重建**回全队列 blockBy，把刚写进去的依赖洗掉
+// （现场：CI 上 localtask-attribution「历史脏数据但带本地依赖」偶发搬家，就是依赖被
+// 在途写洗空后守卫放行）。顶一格让过期快照必然 CAS 冲突 → fail-open 丢弃；
+// 引擎写全是任务行的可重投影，丢了无副作用，下一次 sync 会按新任务行重新投影。
+export function bumpWorkflowRevision(topic) {
+  if (!topic) return;
+  topic.workflowRevision = (Number(topic.workflowRevision) || 0) + 1;
+}
 // "YYYY-MM-DD HH:mm:ss"（本地）→ epoch ms；无法解析返回 NaN
 export function parseStampMs(s) {
   const m = /^(\d{4})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2}):(\d{2})$/.exec(String(s || ''));

package/src/modules/localtask/task-lifecycle.js

@@ -6,7 +6,7 @@ import { formatDuration } from '../../core/instruction-template.js';
 import { preserveFrontmatter } from '../../shared/frontmatter.js';
 import { findFirstReadyPending } from './dag.js';
 import { isGlobalKey, resolveTaskKey } from './paths.js';
-import { loadStore, saveStore, stampNow, normalizeSummary, normalizeText } from './store-io.js';
+import { loadStore, saveStore, stampNow, normalizeSummary, normalizeText, bumpWorkflowRevision } from './store-io.js';
 import { normalizeTask, foreignResolver, isPending, relocateInStore } from './task-view.js';
 import { markConsumed } from './waiters.js';
 // 把一条任务重新开放（用户的**修改反馈** → 重新进入执行循环）。
@@ -51,6 +51,8 @@ export async function reopenTask({ cwd: rawCwd, key: rawKey, id, text, moveTo }
     }
   }
   host.updatedAt = stampNow();
+  bumpWorkflowRevision(host);
+  if (host !== t) bumpWorkflowRevision(t);
   await saveStore(store);
   return {
     status: 'ok',
@@ -81,6 +83,7 @@ export async function consumeFirstPending(key, roundSummary, by) {
     byName: by && by.name,
   });
   t.updatedAt = stampNow();
+  bumpWorkflowRevision(t);
   await saveStore(store);
   return normalizeTask(task);
 }
@@ -145,6 +148,7 @@ export async function completeTask({ cwd: rawCwd, key: rawKey, id, summary: rawS
   task.completedAt = stampNow();
   task.roundSummary = summary;
   t.updatedAt = stampNow();
+  bumpWorkflowRevision(t);
   await saveStore(store);
   // 单一写路径：完成 → Mutator 标 success + 调度一轮（fail-open）
   try {

package/src/modules/localtask/task-ops.js

@@ -14,6 +14,7 @@ import {
   normalizeText,
   topicOf,
   nextTaskId,
+  bumpWorkflowRevision,
 } from './store-io.js';
 import { GLOBAL_KEY, GLOBAL_NAME, GLOBAL_CWD, isGlobalKey, normalizeCwd, resolveTaskKey, topicKeyFor } from './paths.js';
 import { normalizeTask, foreignResolver, queueRelationsOf, relocateInStore } from './task-view.js';
@@ -131,6 +132,7 @@ export async function addTask({
     }
   }
 
+  bumpWorkflowRevision(t);
   await saveStore(store); // 先落盘再唤醒：wait 返回时数据必然一致
   if (wake) wake(normalizeTask(task));
 
@@ -273,6 +275,9 @@ export async function updateTask({
   }
   host.updatedAt = stampNow();
   if (host !== t) t.updatedAt = stampNow();
+  // 搬家动了两个队列，源/目标都要顶 revision（引擎在途快照对两个都可能过期）
+  bumpWorkflowRevision(host);
+  if (host !== t) bumpWorkflowRevision(t);
   await saveStore(store);
   if (hasDagInput) {
     try {

package/src/modules/localtask/task-remove.js

@@ -2,7 +2,7 @@
 // 与 purge 彻底摘除两套词汇；reorder 只在 pending 子序列内换位。
 import { badInput } from '../../core/errors.js';
 import { normalizeCwd, resolveTaskKey } from './paths.js';
-import { loadStore, saveStore, stampNow } from './store-io.js';
+import { loadStore, saveStore, stampNow, bumpWorkflowRevision } from './store-io.js';
 import { normalizeTask, topicView } from './task-view.js';
 export async function removeTask({ cwd: rawCwd, key: rawKey, id, purge = false } = {}) {
   const key = resolveTaskKey({ key: rawKey, cwd: rawCwd });
@@ -22,6 +22,7 @@ export async function removeTask({ cwd: rawCwd, key: rawKey, id, purge = false }
     // 彻底清除：把行真的摘出去（不可恢复）。软删除区里的"清干净"用这个。
     t.tasks.splice(index, 1);
     t.updatedAt = stampNow();
+    bumpWorkflowRevision(t);
     await saveStore(store);
     return { status: 'ok', purged: true, key, cwd: t.cwd || cwd, name: t.name, removed: normalizeTask(task) };
   }
@@ -32,6 +33,7 @@ export async function removeTask({ cwd: rawCwd, key: rawKey, id, purge = false }
   task.deletedAt = stampNow();
   task.trashIndex = index; // 恢复时放回原位
   t.updatedAt = stampNow();
+  bumpWorkflowRevision(t);
   await saveStore(store);
   return { status: 'ok', purged: false, key, cwd: t.cwd || cwd, name: t.name, removed: normalizeTask(task) };
 }
@@ -77,6 +79,7 @@ export async function removeTasks({ cwd: rawCwd, key: rawKey, ids, purge = false
   }
   if (removed.length) {
     t.updatedAt = stampNow();
+    bumpWorkflowRevision(t);
     await saveStore(store);
   }
   return {
@@ -114,6 +117,7 @@ export async function restoreTask({ cwd: rawCwd, key: rawKey, id } = {}) {
   task.deletedAt = '';
   delete task.trashIndex;
   t.updatedAt = stampNow();
+  bumpWorkflowRevision(t);
   await saveStore(store);
   return { status: 'ok', restored: true, key, cwd: t.cwd || cwd, name: t.name, task: normalizeTask(task) };
 }
@@ -161,6 +165,7 @@ export async function reorderTasks({ cwd: rawCwd, key: rawKey, id, beforeId, aft
   const ti = t.tasks.indexOf(target); // 删除 drag 后目标下标自动修正
   t.tasks.splice(hasBefore ? ti : ti + 1, 0, drag);
   t.updatedAt = stampNow();
+  bumpWorkflowRevision(t);
 
   await saveStore(store);
   return { status: 'ok', key, cwd: t.cwd || '', name: t.name, topic: topicView(t) };

package/src/web/frontend/components/md/ack-rail.jsx

@@ -0,0 +1,263 @@
+// 任务页的「ack 定位轨」——反复 ack 反馈的长任务页里，一键跳到某一轮。
+//
+// 复用的是简介页那套定位轨（components/Introduction/rail.jsx 的 .doc-rail 视觉），
+// 但**定位方式不同**：简介页按标题锚点跳，本轨按**块序号**跳。
+// 原因见 modules/board/ack-nodes.js 的注释——实时预览态逐块渲染，同名标题在 DOM 里
+// 拿到的是重复的同一个 id，按 id 跳永远落在第一轮；块序号（data-i）才唯一。
+//
+// 两种渲染态都要能用：
+//   - 实时预览（.mdw-lp）：块有 data-i，按序号直接取
+//   - 阅读态（.mdw-preview）：整篇一次性渲染，没有块元素，按「第 N 个 ack 标题」取
+//
+// 轨可拖动（任务 #55）：汉堡钮是拖把——按住拖整条轨（Pointer Events，>4px 算拖、
+// 否则算点击），双击回默认钉位；落点经 modules/board/ack-rail-pos.js 钳制并
+// 存 localStorage，重开面板还在。拖动语义只在任务页这层加，简介页轨不受影响。
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { ackNodeTitle } from '../../modules/board/ack-nodes.js';
+import { clampRailPos, loadRailPos, saveRailPos } from '../../modules/board/ack-rail-pos.js';
+
+// 位移阈值：超过才算拖动（否则 pointerup 后的 click 照常展开/收起）
+const DRAG_THRESHOLD = 4;
+
+/**
+ * 在滚动容器里按块序号找到目标块。
+ *
+ * 两种渲染态的 DOM 形状不同：
+ *   - 实时预览（.mdw-lp）：每块一个 .mdw-lp-block，带 data-i → 直接取
+ *   - 阅读态（.mdw-preview）：整篇一次性渲染成一段 HTML，**没有块元素**；
+ *     此时改用「第 N 个 ack 标题元素」定位（同名标题在阅读态是整篇共享 usedIds，
+ *     id 各不相同，所以能按序号取到）
+ *
+ * @param {Element|null} root 滚动容器
+ * @param {number} idx 块序号
+ * @param {number} ackOrdinal 该轮是第几个 ack（0 基；阅读态按标题序号取）
+ * @returns {Element|null}
+ */
+function blockAt(root, idx, ackOrdinal) {
+  if (!root || idx < 0) return null;
+  // 实时预览：每块带 data-i
+  const live = root.querySelector(`.mdw-lp-block[data-i="${idx}"]`);
+  if (live) return live;
+  // 阅读态：整篇渲染 → 按「第 N 个 ack 标题」取
+  const heads = [...root.querySelectorAll('h2')].filter(
+    (h) => (h.textContent || '').trim() === '上一轮完成总结'
+  );
+  if (heads[ackOrdinal]) return heads[ackOrdinal];
+  return null;
+}
+
+/**
+ * @param {{nodes: {round:number, blockIndex:number, feedbackBlockIndex:number, ackText:string}[],
+ *            scrollRoot: Element|null,
+ *            onJump?: (node:object)=>void}} props
+ */
+export default function AckRail({ nodes = [], scrollRoot = null, onJump = null }) {
+  const [open, setOpen] = useState(false);
+  const [activeRound, setActiveRound] = useState(0);
+  // 拖动落点：null = 默认钉位（CSS）；有值 = inline left/top 自由落点
+  const [pos, setPos] = useState(loadRailPos);
+  const [dragging, setDragging] = useState(false);
+  const railRef = useRef(null);
+  const dragRef = useRef(null); // 拖动会话：起点、容器/轨尺寸、是否已过阈值、最终落点
+  const draggedRef = useRef(false); // 刚结束的是拖动 → 吃掉紧随的 click，别误触展开
+
+  // 持久化落点钳回当前容器内（视口可能比上次拖动时小）
+  useEffect(() => {
+    const el = railRef.current;
+    const parent = el && el.parentElement;
+    if (!el || !parent) return undefined;
+    const fix = () => {
+      // 经 setPos updater 读最新落点(不另设 ref);钳制是纯函数,重复调用幂等
+      setPos((cur) => {
+        if (!cur) return cur;
+        const pr = parent.getBoundingClientRect();
+        const rr = el.getBoundingClientRect();
+        const fixed = clampRailPos({
+          x: cur.x, y: cur.y, parentW: pr.width, parentH: pr.height, railW: rr.width, railH: rr.height,
+        });
+        return fixed && (fixed.x !== cur.x || fixed.y !== cur.y) ? fixed : cur;
+      });
+    };
+    fix();
+    // 窗口缩放时也别出界
+    window.addEventListener('resize', fix, { passive: true });
+    return () => window.removeEventListener('resize', fix);
+  }, []);
+
+  // ─── 拖动（汉堡钮 = 拖把）────────────────────────────────────────
+  const beginDrag = useCallback((e) => {
+    if (e.pointerType === 'mouse' && e.button !== 0) return;
+    const el = railRef.current;
+    const parent = el && el.parentElement;
+    if (!el || !parent) return;
+    // 钉位态盒子被 top/bottom 双锚拉满（bottom:44 → 高 760），实测高 ≠ 拖后自由态
+    // 自然高——拿它钳制会把上限错钳到容器顶部（第一次拖只能落在 y≤132）。
+    // 临时解除底锚量一次自然高再恢复：同帧同步、子元素本来就从顶部堆叠，无视觉跳动。
+    const prevBottom = el.style.bottom;
+    el.style.bottom = 'auto';
+    const rr = el.getBoundingClientRect();
+    if (prevBottom) el.style.bottom = prevBottom;
+    else el.style.bottom = '';
+    const pr = parent.getBoundingClientRect();
+    dragRef.current = {
+      pointerId: e.pointerId,
+      startX: e.clientX,
+      startY: e.clientY,
+      startLeft: rr.left - pr.left, // 轨在容器内的当前左/上（含钉位态）——位移在此基础上叠加
+      startTop: rr.top - pr.top,
+      parentW: pr.width,
+      parentH: pr.height,
+      railW: rr.width,
+      railH: rr.height, // 自然高（已解除底锚量取）
+      moved: false,
+    };
+    try {
+      e.currentTarget.setPointerCapture(e.pointerId);
+    } catch {
+      /* 老浏览器不支持捕获时照常工作（指针没离开按钮的话） */
+    }
+  }, []);
+
+  const onDragMove = useCallback((e) => {
+    const d = dragRef.current;
+    if (!d || e.pointerId !== d.pointerId) return;
+    const dx = e.clientX - d.startX;
+    const dy = e.clientY - d.startY;
+    if (!d.moved) {
+      if (Math.hypot(dx, dy) < DRAG_THRESHOLD) return;
+      d.moved = true;
+      draggedRef.current = true;
+      setDragging(true);
+      document.body.style.userSelect = 'none'; // 拖动别顺带选中正文
+    }
+    // 抓握点跟随手指：轨在容器内的落点 = 指针按下时的轨位置 + 指针位移
+    //（startLeft 按下时实测，grabDX 的偏移天然已含在内，不需要再修正）
+    const fixed = clampRailPos({
+      x: d.startLeft + dx,
+      y: d.startTop + dy,
+      parentW: d.parentW,
+      parentH: d.parentH,
+      railW: d.railW,
+      railH: d.railH,
+    });
+    if (fixed) {
+      d.last = fixed; // 最终落点记在会话里——pointerup 直接取，不等 React 提交
+      setPos(fixed);
+    }
+  }, []);
+
+  const endDrag = useCallback((e) => {
+    const d = dragRef.current;
+    if (!d || e.pointerId !== d.pointerId) return;
+    dragRef.current = null;
+    if (!d.moved) return; // 没过阈值 = 点击，交给 onClick 展开/收起
+    setDragging(false);
+    document.body.style.userSelect = '';
+    saveRailPos(d.last); // 拖完落点才存（拖动过程不写盘；存会话里的最终落点，不读可能未提交的 state）
+  }, []);
+
+  const resetPos = useCallback(() => {
+    setPos(null);
+    saveRailPos(null); // 清记录 = 回 CSS 默认钉位
+  }, []);
+
+  const items = useMemo(() => (nodes || []).map((n) => ({ ...n, title: ackNodeTitle(n) })), [nodes]);
+
+  // 当前视口里最近的一个 ack 段 → 高亮对应节点
+  useEffect(() => {
+    const root = scrollRoot;
+    if (!root || !items.length) return undefined;
+    const sync = () => {
+      const rootRect = root.getBoundingClientRect();
+      let cur = 0;
+      for (const it of items) {
+        const el = blockAt(root, it.blockIndex, it.round - 1);
+        if (!el) continue;
+        const r = el.getBoundingClientRect();
+        if (r.top - rootRect.top <= 40) cur = it.round;
+      }
+      setActiveRound(cur);
+    };
+    sync();
+    root.addEventListener('scroll', sync, { passive: true });
+    return () => root.removeEventListener('scroll', sync);
+  }, [scrollRoot, items]);
+
+  const jump = useCallback(
+    (node) => {
+      const root = scrollRoot;
+      const el = root ? blockAt(root, node.blockIndex, node.round - 1) : null;
+      if (el) {
+        el.scrollIntoView({ behavior: 'smooth', block: 'start' });
+        setActiveRound(node.round);
+      }
+      onJump?.(node);
+    },
+    [scrollRoot, onJump]
+  );
+
+  if (!items.length) return null;
+
+  return (
+    <aside
+      ref={railRef}
+      className={'doc-rail ack-rail' + (open ? ' open' : '') + (dragging ? ' dragging' : '')}
+      style={pos ? { left: pos.x, top: pos.y, right: 'auto', bottom: 'auto' } : undefined}
+      aria-label="验收轮次"
+    >
+      <button
+        type="button"
+        className="doc-rail-menu"
+        title={open ? '收起轮次（双击回默认位）' : '展开轮次 · 按住拖动 · 双击回默认位'}
+        aria-expanded={open}
+        onClick={() => {
+          if (draggedRef.current) {
+            draggedRef.current = false; // 这下 click 是拖动结束带出来的，别当点击
+            return;
+          }
+          setOpen((v) => !v);
+        }}
+        onPointerDown={beginDrag}
+        onPointerMove={onDragMove}
+        onPointerUp={endDrag}
+        onPointerCancel={endDrag}
+        onDoubleClick={resetPos}
+      >
+        <span /><span /><span />
+      </button>
+
+      <div className="doc-rail-ticks" role="navigation" aria-label="验收轮次">
+        {items.map((it) => (
+          <button
+            key={it.round}
+            type="button"
+            className={'doc-rail-tick' + (activeRound === it.round ? ' on' : '')}
+            style={{ '--tw': '18px' }}
+            title={it.title}
+            aria-current={activeRound === it.round ? 'true' : undefined}
+            onClick={() => jump(it)}
+          />
+        ))}
+      </div>
+
+      {open && (
+        <div className="doc-rail-panel">
+          <div className="doc-rail-sec">
+            <div className="doc-rail-sec-lab">验收轮次</div>
+            {items.map((it) => (
+              <button
+                key={it.round}
+                type="button"
+                className={'doc-rail-row' + (activeRound === it.round ? ' on' : '')}
+                title={it.ackText}
+                onClick={() => jump(it)}
+              >
+                第 {it.round} 轮
+              </button>
+            ))}
+          </div>
+        </div>
+      )}
+    </aside>
+  );
+}