nx-kv 0.21.0 → 0.22.0

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 本文件记录对外可见的变更。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)。
 
+## [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 +57,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 +94,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 +576,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.22.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,133 @@
+// 任务页的「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 标题」取
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { ackNodeTitle } from '../../modules/board/ack-nodes.js';
+
+/**
+ * 在滚动容器里按块序号找到目标块。
+ *
+ * 两种渲染态的 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);
+
+  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 className={'doc-rail ack-rail' + (open ? ' open' : '')} aria-label="验收轮次">
+      <button
+        type="button"
+        className="doc-rail-menu"
+        title={open ? '收起轮次' : '展开轮次'}
+        aria-expanded={open}
+        onClick={() => setOpen((v) => !v)}
+      >
+        <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>
+  );
+}

package/src/web/frontend/modules/board/ack-nodes.js

@@ -0,0 +1,89 @@
+// 任务正文的「ack 节点」抽取 —— 反复 ack 反馈的长任务页要能快速定位到某一轮。
+//
+// 背景（任务 #48）：用户给了 DOM 定位器（`.doc-rail-ticks` 那个小定位轨），
+// 说「这个功能可以快速定位，而对于一些反复 ack 反馈的页面，这些任务页面很长，
+// 操作不便捷，想要复用这个组件，将每一次 ack 作为一个节点去快速定位」。
+//
+// 事实基础：每次「重做（带反馈）」都会把上一轮的 ack 与本轮反馈**追加**进任务正文
+// （见 modules/board/reopen-text.js 的 buildReopenText），所以正文里会出现**多个**
+// `## 上一轮完成总结` / `## 验收反馈` 段。任务 #34 就是 5 轮、正文 13903 字符。
+//
+// 为什么不能直接用 extractMdHeadings 的标题 id：它给同名标题生成 `上一轮完成总结` /
+// `-2` / `-3`… 的 id，但**实时预览态**（mdw-lp）是**逐块渲染**的——每块各自调
+// renderMarkdownHtml、各有一套 usedIds，于是同名标题在 DOM 里拿到的是**重复的同一个
+// id**（实测两个 `## 上一轮完成总结` 都是 id="上一轮完成总结"）。按 id 跳转会永远落在
+// 第一轮。所以这里按**块序号**定位：块切分口径直接复用 md-parse 的 liveBodyBlocks
+// （与实时预览渲染用的是同一个函数），序号才对得上 DOM 里的 data-i。
+//
+// 纯函数、零依赖（只 import 同为纯前端的 md-parse.js）：前端取节点、单测都能用。
+
+import { liveBodyBlocks } from '../md/md-parse.js';
+
+/** ack 段标题（与 reopen-text.js 同口径） */
+export const ACK_NODE_HEADING = '## 上一轮完成总结';
+/** 反馈段标题 */
+export const ACK_NODE_FEEDBACK_HEADING = '## 验收反馈';
+
+/**
+ * 从任务正文里抽出每一轮 ack 节点。
+ *
+ * @param {string} body 任务正文（Markdown）
+ * @returns {{ round:number, blockIndex:number, feedbackBlockIndex:number,
+ *            ackText:string, feedbackText:string }[]}
+ *   round 从 1 起。blockIndex 是该轮 ack 段标题在**正文块序列**里的序号（0 基，
+ *   对应实时预览的 data-i）；feedbackBlockIndex 同理，找不到为 -1。
+ */
+export function extractAckNodes(body) {
+  const blocks = liveBodyBlocks(String(body ?? ''));
+  if (!blocks.length) return [];
+
+  const out = [];
+  // cur = 正在填充的节点；phase = 当前内容属于它的哪一段
+  let cur = null;
+  let phase = '';
+
+  blocks.forEach((raw, i) => {
+    const b = String(raw || '').trim();
+    if (b === ACK_NODE_HEADING) {
+      cur = {
+        round: out.length + 1,
+        blockIndex: i,
+        feedbackBlockIndex: -1,
+        ackText: '',
+        feedbackText: '',
+      };
+      out.push(cur);
+      phase = 'ack';
+      return;
+    }
+    if (b === ACK_NODE_FEEDBACK_HEADING) {
+      // 反馈段归属**当前正在填的 ack 段**（没有则忽略——孤儿反馈段不算节点）
+      if (cur && phase === 'ack') {
+        cur.feedbackBlockIndex = i;
+        phase = 'feedback';
+      }
+      return;
+    }
+    if (!b || !cur) return;
+    if (phase === 'ack') cur.ackText += (cur.ackText ? '\n' : '') + b;
+    else cur.feedbackText += (cur.feedbackText ? '\n' : '') + b;
+  });
+
+  return out.filter((n) => n.ackText !== '');
+}
+
+/**
+ * 给节点起一个短标题（轨上显示用）：取 ack 首行（去掉 markdown 记号），
+ * 空则退到「第 N 轮」。过长截断。
+ * @param {{round:number, ackText:string}} node
+ * @returns {string}
+ */
+export function ackNodeTitle(node) {
+  const first = String(node?.ackText || '')
+    .split('\n')
+    .map((l) => l.replace(/^#+\s*/, '').replace(/\*\*/g, '').trim())
+    .find((l) => l !== '');
+  if (!first) return `第 ${node?.round ?? 1} 轮`;
+  const short = first.length > 24 ? `${first.slice(0, 24)}…` : first;
+  return `第 ${node.round} 轮 · ${short}`;
+}

package/src/web/frontend/modules/md/style.css

@@ -1053,6 +1053,12 @@
   background:var(--paper,#fff);border:1px solid var(--line,#E4E2DC);border-radius:10px;
   box-shadow:0 8px 24px rgba(20,22,26,.12);padding:8px 0;
 }
+
+/* 任务页的 ack 定位轨（任务 #48）：复用 .doc-rail 视觉，位置贴任务正文区
+   —— 任务页顶部有 mdw-top + mdw-toolbar 两条，轨往下挪，别压住工具栏。
+   .mdw 本身是 position:relative，absolute 轨锚在它上面。 */
+.mdw > .ack-rail{top:96px;bottom:44px}
+.mdw > .ack-rail .doc-rail-ticks{gap:12px}
 .doc-rail-sec{padding:4px 0 8px;border-bottom:1px solid var(--line,#E4E2DC)}
 .doc-rail-sec:last-child{border-bottom:0;padding-bottom:4px}
 .doc-rail-sec-lab{

package/src/web/frontend/page/dir/task.jsx

@@ -14,8 +14,10 @@ import { useToast } from '../../components/toast/index.jsx';
 import { useDialog } from '../../components/popup/index.jsx';
 import { GLOBAL_KEY } from '../../modules/board/board-view.js';
 import { buildReopenText } from '../../modules/board/reopen-text.js';
+import { extractAckNodes } from '../../modules/board/ack-nodes.js';
 import ToolBar from '../../components/md/tool-bar.jsx';
 import { MdPanes } from '../../components/md/md-panes.jsx';
+import AckRail from '../../components/md/ack-rail.jsx';
 import AttachBar from '../../components/md/attach-bar.jsx';
 import SelMenu from '../../components/md/sel-menu.jsx';
 import ShortcutSheet from '../../components/md/shortcut-sheet.jsx';
@@ -288,6 +290,24 @@ export default function PagePanel({ dirKey, task, beside = false, tabId, model }
     [taskRow?.roundSummary]
   );
 
+  // ack 定位轨（任务 #48）：反复 ack 反馈的长任务页，按轮次快速跳转。
+  // 轮次从正文里抽（每轮一个「## 上一轮完成总结」段）——正文即历史，正文变了轨也跟着变。
+  const ackNodes = useMemo(() => (doc ? extractAckNodes(doc.body) : []), [doc && doc.body]);
+  // 滚动容器：实时预览是 .mdw-lp（可滚），阅读态是 .mdw-preview。
+  // ⚠️ articleRef 指的是 **.mdw-lp-sheet**（live）/ **article**（阅读），两者都是
+  // 滚动容器的**子节点**——要往上找（closest），不是往下查（querySelector）。
+  // 两种态的 DOM 形状不同，轨内部按态分别定位（见 ack-rail.jsx 的 blockAt）。
+  const [ackScrollRoot, setAckScrollRoot] = useState(null);
+  useEffect(() => {
+    const root = articleRef.current;
+    if (!root) return undefined;
+    const pick = () => root.closest('.mdw-lp') || root.closest('.mdw-preview') || null;
+    setAckScrollRoot(pick());
+    const mo = typeof MutationObserver !== 'undefined' ? new MutationObserver(() => setAckScrollRoot(pick())) : null;
+    mo?.observe(root, { childList: true, subtree: true });
+    return () => mo?.disconnect();
+  }, [doc && doc.mode]);
+
   useEffect(() => {
     setSelMenu(null);
     lastSel.current = '';
@@ -961,6 +981,10 @@ export default function PagePanel({ dirKey, task, beside = false, tabId, model }
         )}
       </div>
 
+      {/* ack 定位轨（任务 #48）：反复 ack 反馈的长任务页，一轮一个节点，点击跳过去。
+          只有真的有多轮时才有内容（ackNodes 为空 → 组件自身返回 null）。 */}
+      <AckRail nodes={ackNodes} scrollRoot={ackScrollRoot} />
+
       <SelMenu
         at={selMenu}
         onFormat={(op) => {