feat(notes): 时间戳回链接上毫秒并修复死链

Author: Aparencia

app/src/components/NoteMarkdown.test.tsx

@@ -11,7 +11,7 @@
  *              components.mark 按 hast tagName 匹配实际从未命中=无样式）。
  */
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { cleanup, render } from "@testing-library/react";
+import { cleanup, fireEvent, render } from "@testing-library/react";
 import type { Note } from "../types";
 import NoteMarkdown from "./NoteMarkdown";
 
@@ -89,3 +89,75 @@ describe("NoteMarkdown 换行语义（v0.15 remark-breaks）", () => {
     expect(container.querySelector("div")).toBeNull();
   });
 });
+
+/**
+ * 批 6 T26 —— `[[ts:ms]]` 回链**把 ms 接上**（R5.5 顺带④：今天 ms 只进 `title` 文案、`onClick` 丢弃它只跳会话）。
+ *
+ * @ai-context 判据锚点 = 回链芯片（`span[title*="跳转到会话"]`，title 文案本任务**一字未改**）。
+ *              四条各自独立：①带 ms 分支的调用次数+实参（两分支互斥）②缺省退回既有单参回调
+ *              ③四个边界值的 ms **逐字**（不得按秒截断）④普通链接不受影响（反例守卫）。
+ *              诚实边界：这里只证明 **ms 被传出本组件**；「到会话页后播放头真的跳」不在此判据面内。
+ */
+describe("NoteMarkdown [[ts:ms]] 接上毫秒（批 6 T26）", () => {
+  /** 回链芯片（title 文案是它的既有锚点；本任务未改文案） */
+  const chipOf = (container: HTMLElement): HTMLElement => {
+    const el = container.querySelector<HTMLElement>('span[title*="跳转到会话"]');
+    expect(el, "回链芯片未渲染").toBeTruthy();
+    return el as HTMLElement;
+  };
+
+  it("① 点击回链 ⇒ onOpenSessionAt 恰一次收到 (sessionId, ms)，且不再走单参回调", () => {
+    const at = vi.fn();
+    const plain = vi.fn();
+    const { container } = render(
+      <NoteMarkdown note={note("跳转 [⏱ 00:52]([[ts:52500]]) 处")} searchQuery="" onTaskToggle={noop} onOpenSession={plain} onOpenSessionAt={at} onImageOpen={noop} />,
+    );
+
+    fireEvent.click(chipOf(container));
+
+    expect(at).toHaveBeenCalledTimes(1);
+    expect(at).toHaveBeenCalledWith(42, 52_500);
+    expect(plain, "两分支必须互斥：带 ms 分支命中时不得再调单参回调（会重复导航）").toHaveBeenCalledTimes(0);
+  });
+
+  it("② 不传 onOpenSessionAt ⇒ 仍调既有 onOpenSession(sessionId)（向后兼容一字不变）", () => {
+    const plain = vi.fn();
+    const { container } = render(
+      <NoteMarkdown note={note("跳转 [⏱ 00:52]([[ts:52500]]) 处")} searchQuery="" onTaskToggle={noop} onOpenSession={plain} onImageOpen={noop} />,
+    );
+
+    fireEvent.click(chipOf(container));
+
+    expect(plain).toHaveBeenCalledTimes(1);
+    expect(plain).toHaveBeenCalledWith(42);
+  });
+
+  it("③ 四个边界值 ⇒ ms 逐字传出（不得经 sec*1000 / 按秒截断）", () => {
+    for (const ms of [0, 1, 59_999, 3_600_000]) {
+      const at = vi.fn();
+      const view = render(
+        <NoteMarkdown note={note(`跳转 [⏱ t]([[ts:${ms}]]) 处`)} searchQuery="" onTaskToggle={noop} onOpenSessionAt={at} onImageOpen={noop} />,
+      );
+      fireEvent.click(chipOf(view.container));
+      expect(at, `[[ts:${ms}]] 的 ms 未逐字传出`).toHaveBeenCalledWith(42, ms);
+      view.unmount();
+    }
+  });
+
+  it("④ 非 ts 链接不受影响：仍渲染 <a href>，点击不触发任何会话回调", () => {
+    const at = vi.fn();
+    const plain = vi.fn();
+    // 用同页 hash 链接做反例点击（jsdom 里外链点击会打印 navigation 未实现告警，噪声无益）
+    const { container } = render(
+      <NoteMarkdown note={note("[普通链接](#section)")} searchQuery="" onTaskToggle={noop} onOpenSession={plain} onOpenSessionAt={at} onImageOpen={noop} />,
+    );
+    const anchor = container.querySelector("a");
+    expect(anchor?.getAttribute("href")).toBe("#section");
+    expect(container.querySelectorAll('span[title*="跳转到会话"]'), "普通链接被误渲染成回链芯片").toHaveLength(0);
+
+    fireEvent.click(anchor as HTMLAnchorElement);
+
+    expect(at).toHaveBeenCalledTimes(0);
+    expect(plain).toHaveBeenCalledTimes(0);
+  });
+});

app/src/components/NoteMarkdown.tsx

@@ -12,10 +12,13 @@
  *              React 托管 DOM（surroundContents 与虚拟 DOM 协调冲突）。
  * @ai-context: M5 修复——标题行号索引渲染前 useMemo 一次预计算（Map + 出现
  *              序号消歧同名标题），替代每个标题 O(n) findIndex + as string 断言。
+ * @ai-context: 批 6 T26——`[[ts:ms]]` 的 ms 不再只进 title：新增**可选** `onOpenSessionAt` 把它逐字
+ *              传出（缺省时与今天逐字相同；title 一字未改）。前置缺陷见 `noteUrlTransform`：
+ *              `react-markdown@10.1.0` 的默认 URL 消毒把它清成空串 ⇒ 回链芯片此前从未渲染。
  */
 import { isValidElement, cloneElement, useMemo, useRef } from "react";
 import type { ReactElement, ReactNode } from "react";
-import ReactMarkdown from "react-markdown";
+import ReactMarkdown, { defaultUrlTransform } from "react-markdown";
 import remarkBreaks from "remark-breaks";
 import remarkGfm from "remark-gfm";
 import remarkMath from "remark-math";
@@ -42,6 +45,11 @@ interface Props {
   searchQuery: string;
   onTaskToggle: (newContent: string) => void;
   onOpenSession?: (sessionId: number) => void;
+  /** `[[ts:ms]]` 回链的**带毫秒**分支（批 6 T26 · R5.5 顺带④）：跳会话**并**把目标毫秒带出去。
+   *  @ai-context 两参而不是 `onSeekMs(ms)`：ms 只在**知道哪条会话**时才有意义 ⇒ 会话 id 由本件补；
+   *  缺省 ⇒ 退回既有 `onOpenSession(sessionId)`（两分支**互斥**，都调会重复导航；既有 6 条判据不动）。
+   *  边界：定位精度受音频对齐的块粒度 **±200 ms** 限制（不得声称毫秒级定位）。 */
+  onOpenSessionAt?: (sessionId: number, ms: number) => void;
   onImageOpen: (src: string, title?: string) => void;
   /**
    * **只许追加、不许替换**的 remark 插件槽（C8）。
@@ -55,6 +63,21 @@ interface Props {
   remarkPluginsExtra?: readonly RemarkPlugin[];
 }
 
+/**
+ * `[[ts:ms]]` 回链的**内部锚点**语法 + URL 消毒的唯一出口（批 6 T26 实测）。
+ *
+ * @ai-context 为什么必须显式放行：href 到 hast 阶段是**百分号编码**的 `%5B%5Bts:52500%5D%5D`，
+ *   而 `react-markdown@10.1.0` 的 `defaultUrlTransform` 把无协议 URL 一律清空 ⇒ 回链芯片此前
+ *   **根本没渲染**（落成 `<a href="">⏱ 00:52</a>`，下面的 `tsMatch` 永不命中；比 R5.5 顺带④ 记的还坏）。
+ *   安全面零放松：只放行这一种形态（解码回规范形），其余全交回默认消毒器；该 href 仅用于识别，最终渲染成 `<span>`。
+ */
+const TS_HREF_RE = /^\[\[ts:(\d+)\]\]$/;
+const TS_HREF_ENCODED_RE = /^%5B%5Bts:(\d+)%5D%5D$/i;
+const noteUrlTransform = (url: string): string => {
+  const m = TS_HREF_ENCODED_RE.exec(url);
+  return m ? `[[ts:${m[1]}]]` : defaultUrlTransform(url);
+};
+
 /** 递归展平 React 子节点为纯文本（ReactNode 收窄——替代 as string 断言） */
 function flattenText(node: ReactNode): string {
   if (node == null || typeof node === "boolean") return "";
@@ -113,7 +136,7 @@ function highlightNode(node: ReactNode, query: string): ReactNode {
   return walk(node, "hl");
 }
 
-export default function NoteMarkdown({ note, searchQuery, onTaskToggle, onOpenSession, onImageOpen, remarkPluginsExtra }: Props) {
+export default function NoteMarkdown({ note, searchQuery, onTaskToggle, onOpenSession, onOpenSessionAt, onImageOpen, remarkPluginsExtra }: Props) {
   // H1：任务行索引（源文本中每个任务行的行号，按出现顺序）
   // 正则与 remark-gfm 清单语法对齐：-/*/+ 无序 + 有序列表（\d{1,9}[.)]），
   // 勾选框大小写均认（[x]/[X]）——否则渲染序号与索引数组错位会写错行
@@ -180,6 +203,9 @@ export default function NoteMarkdown({ note, searchQuery, onTaskToggle, onOpenSe
       // 存量笔记内容零数据变更自动修复；`\` 与两空格强断行语义保留）
       remarkPlugins={[remarkGfm, remarkMath, remarkMarkHighlight, remarkBreaks, ...(remarkPluginsExtra ?? [])]}
       rehypePlugins={[rehypeKatex]}
+      // 批 6 T26：放行内部 `[[ts:ms]]` 锚点（默认消毒器会清空它 ⇒ 回链芯片曾整条不可达；
+      // 见 `noteUrlTransform`）。**不是**放松消毒：其余 URL 仍走 `defaultUrlTransform`。
+      urlTransform={noteUrlTransform}
       components={{
         // v0.14 B：==文本== 荧光笔（remark 插件产出 mdast mark 节点 + hName/hProperties）
         // v0.16.1：多色——className 由插件注入（note-mark[-{colorId}]，样式见 note-mark.css）；
@@ -210,7 +236,7 @@ export default function NoteMarkdown({ note, searchQuery, onTaskToggle, onOpenSe
         li: ({ node, children, ...props }) => <li {...props}>{hl(children)}</li>,
         // 时间戳回链渲染（P1/A5 预览预备；L6：parseInt 补 radix 10）
         a: ({ node, href, children, ...props }) => {
-          const tsMatch = href?.match(/^\[\[ts:(\d+)\]\]$/);
+          const tsMatch = href?.match(TS_HREF_RE);
           if (tsMatch) {
             const ms = parseInt(tsMatch[1], 10);
             const sec = Math.floor(ms / 1000);
@@ -220,7 +246,10 @@ export default function NoteMarkdown({ note, searchQuery, onTaskToggle, onOpenSe
               <span
                 style={{ cursor: "pointer", color: "#0d9488", borderBottom: "1px dashed #14b8a6", background: "#f0fdfa", borderRadius: 3, padding: "0 4px" }}
                 onClick={() => {
-                  if (note.session_id) onOpenSession?.(note.session_id);
+                  if (!note.session_id) return;
+                  // T26：带 ms 的分支优先（ms 逐字传出，不截断）；缺省退回既有单参回调
+                  if (onOpenSessionAt) onOpenSessionAt(note.session_id, ms);
+                  else onOpenSession?.(note.session_id);
                 }}
                 title={`⏱ 跳转到会话 ${Math.floor(ms / 60000)}:${secStr} 处 —— 点击查看视频对应片段`}
               >

app/src/components/NoteReadingView.tsx

@@ -59,6 +59,8 @@ interface Props {
   onDelete: () => void;
   onTagClick: (tag: string) => void;
   onOpenSession: (sessionId: number) => void;
+  /** 批 6 T26：`[[ts:ms]]` 回链的**带毫秒**分支（缺省 ⇒ `NoteMarkdown` 退回既有 `onOpenSession`） */
+  onOpenSessionAt?: (sessionId: number, ms: number) => void;
   onTaskToggle: (newContent: string) => void;
   onImageOpen: (src: string, title?: string) => void;
   /** 批 8（REQ-317）：正文选区菜单行动类动作上抛（转问题/模型卡预填——
@@ -70,7 +72,7 @@ export default function NoteReadingView({
   note, editing, editor, auxPanels, headerExtra,
   outlineFolded = false, outlineWidth = columnSpec("notes-outline").default,
   onOutlineResize, onOutlineReset, externalSearch = null, onToggleOutline,
-  onEdit, onPinToggle, onDelete, onTagClick, onOpenSession, onTaskToggle, onImageOpen,
+  onEdit, onPinToggle, onDelete, onTagClick, onOpenSession, onOpenSessionAt, onTaskToggle, onImageOpen,
   onSelectionAction,
 }: Props) {
   // A2：搜索高亮（M6：匹配集合=渲染产物只读查询，计数经此状态驱动）
@@ -316,6 +318,7 @@ export default function NoteReadingView({
                 searchQuery={searchActive ? searchQuery : ""}
                 onTaskToggle={onTaskToggle}
                 onOpenSession={onOpenSession}
+                onOpenSessionAt={onOpenSessionAt}
                 onImageOpen={onImageOpen}
               />
             </div>

app/src/components/notes/NotesReadingColumn.tsx

@@ -103,6 +103,8 @@ interface Props {
   onTagClick: (tag: string) => void;
   /** 来源会话反跳（缺省=不可跳） */
   onOpenSession?: (sessionId: number) => void;
+  /** 批 6 T26：`[[ts:ms]]` 回链的带毫秒分支（透传给 `NoteReadingView`；缺省 ⇒ 退回 `onOpenSession`） */
+  onOpenSessionAt?: (sessionId: number, ms: number) => void;
   /** 图片放大预览入口（阅读态与编辑态共用同一遮罩） */
   onImageOpen: (src: string, title?: string) => void;
   /** 空组清理留痕上抛（移组触发，父层 toast） */
@@ -114,7 +116,7 @@ interface Props {
 export default function NotesReadingColumn({
   selected, editing, setEditing, readerSearch, noteColors, groups, editorRef, outlineCol,
   onChanged, onError, onCreateSystem, onOpenAi, onOpenModelCard, onSelectionAction,
-  onPinToggle, onDelete, onTaskToggle, onTagClick, onOpenSession, onImageOpen, onCleanNotice,
+  onPinToggle, onDelete, onTaskToggle, onTagClick, onOpenSession, onOpenSessionAt, onImageOpen, onCleanNotice,
   views,
 }: Props) {
   // H3：辅助面板插槽——VersionPanel（知识补充已迁移至编辑态 🤖 AI 菜单——
@@ -168,6 +170,7 @@ export default function NotesReadingColumn({
   const isDefault = viewKey === defaultKey;
   const LazyView = isDefault ? null : lazyOf.get(viewKey) ?? null;
   /** 非默认视图的槽（数据全在这里，视图自身零取数 —— C14②）；空态 ⇒ `null`（连卡片流都不挂） */
+  // ⚠️ T26：`onOpenSessionAt` **不进** NoteViewSlot（该槽类型属批 6 T24 的规范面，本任务不改）⇒ 卡片流视图的时间码回链仍无 ms，已登记为残余
   const slot: NoteViewSlot | null = selected
     ? { note: selected, onTaskToggle, onOpenSession, onImageOpen }
     : null;
@@ -230,6 +233,7 @@ export default function NotesReadingColumn({
       onDelete={() => void onDelete(selected.id)}
       onTagClick={onTagClick}
       onOpenSession={(id) => onOpenSession?.(id)}
+      onOpenSessionAt={onOpenSessionAt}
       onTaskToggle={onTaskToggle}
       onImageOpen={(src, title) => onImageOpen(src, title)}
       // 批 8（REQ-317）：阅读态选区行动类（转问题/模型卡预填）

app/src/pages/NotesPage.test.tsx

@@ -118,3 +118,57 @@ describe("NotesPage 编辑完成即时刷新", () => {
     await waitFor(() => expect(screen.getByRole("heading", { name: "ESC 新标题" })).toBeTruthy());
   });
 });
+
+/**
+ * 批 6 T26 —— 笔记侧链路的**末端**判据：`[[ts:ms]]` 回链的 ms 必须**离开笔记页**
+ * （`NotesPage` → `NotesReadingColumn` → `NoteReadingView` → `NoteMarkdown`）。
+ *
+ * @ai-context 这条判据的牙口覆盖**整条链**：任一跳把 ms 丢掉（只传 sessionId）都会在这里红。
+ *             ⚠️ 诚实边界：它**不**证明「到会话页后播放头跳到该毫秒」—— 那一跳要改
+ *             `App.tsx` / `SessionsPage.tsx` / `SessionDetailPanel.tsx`（全在本任务禁改面内）⇒ 未交付，
+ *             见 `.superpowers/sdd/2026-09-12-frontend-redesign-batch6-motion/task-26-report.md`。
+ */
+describe("NotesPage [[ts:ms]] 带上毫秒（批 6 T26）", () => {
+  beforeEach(() => {
+    invokeMock.mockReset();
+    confirmMock.mockReset();
+    invokeMock.mockImplementation(async (cmd: string) => {
+      switch (cmd) {
+        case "list_notes":
+          return [{ ...baseNote("带时间码"), content: "开头 [⏱ 00:05]([[ts:5000]]) 结尾" }];
+        case "list_note_groups":
+        case "list_fragments":
+        case "note_versions_list":
+        case "note_versions_usage":
+        case "list_knowledge_systems":
+        case "list_knowledge_links":
+        case "list_tag_colors":
+        case "list_links_by_target":
+          return [];
+        case "get_feature_flags":
+          return { feedCapture: true };
+        default:
+          return null;
+      }
+    });
+  });
+
+  afterEach(() => cleanup());
+
+  it("点回链 ⇒ onOpenSessions 收到 (sessionId, ms)", async () => {
+    const onOpenSessions = vi.fn();
+    const { container } = render(<NotesPage onOpenSessions={onOpenSessions} />);
+    // 选中笔记 ⇒ 右栏进入阅读态（回链芯片由 NoteMarkdown 渲染）
+    fireEvent.click(await screen.findByText("带时间码"));
+
+    const chip = await waitFor(() => {
+      const el = container.querySelector<HTMLElement>('span[title*="跳转到会话"]');
+      expect(el, "回链芯片未渲染（阅读栏未进入阅读态？）").toBeTruthy();
+      return el as HTMLElement;
+    });
+    fireEvent.click(chip);
+
+    expect(onOpenSessions).toHaveBeenCalledTimes(1);
+    expect(onOpenSessions).toHaveBeenCalledWith(42, 5000);
+  });
+});

app/src/pages/NotesPage.tsx

@@ -47,7 +47,13 @@ interface Props {
    *  该组（groupId=null 保留为全量语义，当前无调用方——组侧栏全量按钮已随
    *  无被动提醒裁决移除）；消费在 ReviewPage，本页只透传 */
   onOpenReview?: (groupId: number | null, name: string) => void;
-  onOpenSessions?: (sessionId: number) => void;
+  /**
+   * 会话深链入口（App 注入 `goSessions`）。批 6 T26：第二实参 = `[[ts:ms]]` 回链的目标毫秒。
+   * ⚠️ 今天的生产实现（`App.tsx` 的 `goSessions`）只读第一个实参 ⇒ **「到会话页后跳到该毫秒」那一跳
+   * 本任务不交付**（需改 `App.tsx` + `SessionsPage.tsx` + `SessionDetailPanel.tsx`，三者都在本任务禁改面内）；
+   * 本件只保证 ms **离开笔记页**、交给深链入口（见 task-26-report 的 STOP 记录）。
+   */
+  onOpenSessions?: (sessionId: number, ms?: number) => void;
   /** 打开体系页并选中体系（v0.13.7 触点① 组行徽标） */
   onOpenSystem?: (systemId: number) => void;
   /** TD-2026-09-05-A：空体系引导——跳体系页并打开建体系向导 */
@@ -264,6 +270,7 @@ export default function NotesPage({ focusNoteId, focusNoteSearch, focusGroupId,
         onTaskToggle={handleTaskToggle}
         onTagClick={(t) => { list.setTagFilter(t); list.setKeyword(""); setView("notes"); }}
         onOpenSession={onOpenSessions}
+        onOpenSessionAt={onOpenSessions}
         onImageOpen={(src, title) => setPreviewImg({ src, title })}
         onCleanNotice={notifyCleanNotice}
         views={viewsFor("note")}