feat(chat): Phase G — 链式时间线网状结构

steve02081504 · steve02081504 · commit 11d193a434d0 · 2026-04-14T19:35:40.000+08:00
新增 prevMessageEventId 字段：AI 消息写入 DAG 时记录生成时的上文 eventId，
使具有相同 prevMessageEventId 的多条回复成为同一分支点的 alternatives。

新增 buildDisplayChain：基于 activeBranches 指针从所有消息中
遍历出当前活跃分支路径，替代旧的线性 mergeChannelMessagesForDisplay。

前端链式导航：
- 每个 alternative 消息下方显示 '◀ N/M ▶' 导航条，点击切换分支
- 切换时更新 activeBranches 并持久化到 localStorage
- 切换某处的 alternative 自动带动后续消息跟随对应分支

Swipe 手势扩展到所有消息类型（不再仅限 char 消息），
有 branchData 时沿链切换，无时退化为旧 modifyTimeLine。

向后兼容：无 prevMessageEventId 的旧数据直接返回原始消息列表。
diff --git a/src/public/parts/shells/chat/public/src/group.mjs b/src/public/parts/shells/chat/public/src/group.mjs
@@ -133,6 +133,33 @@ async function applyGroupHash() {
 	sessionStorage.setItem('group:wsClientId', wsClientId)
 	setLocalGroupRpcClientNodeId(wsClientId)
 
+	/**
+	 * 从 localStorage 恢复指定频道的 activeBranches。
+	 * @param {string} gId 群组 ID
+	 * @param {string} chId 频道 ID
+	 * @returns {Map<string, string>} prevMessageEventId 到选中 eventId 的映射
+	 */
+	function loadActiveBranches(gId, chId) {
+		try {
+			const raw = localStorage.getItem(`fount:branches:${gId}:${chId}`)
+			return new Map(raw ? JSON.parse(raw) : [])
+		} catch { return new Map() }
+	}
+
+	/**
+	 * 将 activeBranches 持久化到 localStorage（最多保留 500 个分支点）。
+	 * @param {string} gId 群组 ID
+	 * @param {string} chId 频道 ID
+	 * @param {Map<string, string>} map 当前 activeBranches
+	 * @returns {void}
+	 */
+	function saveActiveBranches(gId, chId, map) {
+		try {
+			const entries = [...map].slice(-500)
+			localStorage.setItem(`fount:branches:${gId}:${chId}`, JSON.stringify(entries))
+		} catch { /* ignore */ }
+	}
+
 	/** 共享可变状态（消息列表、虚拟列表、流式渲染、AV 会话等） */
 	const channelState = {
 		/** @type {object | null} */
@@ -154,6 +181,10 @@ async function applyGroupHash() {
 		patchScheduled: false,
 		/** @type {object | null} */
 		avSession: null,
+		/** @type {Map<string, string>} prevMessageEventId -> 选中的 eventId */
+		activeBranches: loadActiveBranches(groupId, channelId),
+		/** @type {Map<string, { alternatives: object[], selectedIdx: number, branchKey: string }>} */
+		branchInfo: new Map(),
 	}
 
 	signal.addEventListener('abort', () => {
@@ -485,6 +516,20 @@ async function applyGroupHash() {
 		 * @returns {void}
 		 */
 		onOpenThread: threadChannelId => { threadDrawerInstance?.open(threadChannelId) },
+		/**
+		 * @returns {Map<string, { alternatives: object[], selectedIdx: number, branchKey: string }>} 当前分支信息
+		 */
+		getBranchInfo: () => channelState.branchInfo,
+		/**
+		 * @param {string} branchKey prevMessageEventId 分支点 key
+		 * @param {string} selectedEventId 选中的消息 eventId
+		 * @returns {void}
+		 */
+		onBranchSelect: (branchKey, selectedEventId) => {
+			channelState.activeBranches.set(branchKey, selectedEventId)
+			saveActiveBranches(groupId, channelId, channelState.activeBranches)
+			void loadMessages()
+		},
 	})
 
 	// ─── Thread Drawer ────────────────────────────────────────────────────────
@@ -622,6 +667,10 @@ async function applyGroupHash() {
 		setAsDefaultChannel,
 		renderMessageItem,
 		attachLastMessageTimeline,
+		/**
+		 * @returns {Map<string, string>} 当前 activeBranches
+		 */
+		getActiveBranches: () => channelState.activeBranches,
 	}))
 
 	await pullIncrementalDagEvents()
diff --git a/src/public/parts/shells/chat/public/src/ui/channelView.mjs b/src/public/parts/shells/chat/public/src/ui/channelView.mjs
@@ -5,7 +5,7 @@ import { createVirtualList } from '../../../../../../pages/scripts/virtualList.m
 import { geti18n, setLocalizeLogic } from '../../../../../../scripts/i18n.mjs'
 import { handleUIError } from '../utils.mjs'
 
-import { escapeHtml, mergeChannelMessagesForDisplay, orderedActivePinTargets, plainPreviewFromLine } from './dagMessageUtils.mjs'
+import { buildDisplayChain, escapeHtml, mergeChannelMessagesForDisplay, orderedActivePinTargets, plainPreviewFromLine } from './dagMessageUtils.mjs'
 import { addDragAndDropSupport } from './dragAndDrop.mjs'
 
 /**
@@ -26,6 +26,7 @@ import { addDragAndDropSupport } from './dragAndDrop.mjs'
  * @param {Function} params.setAsDefaultChannel 设为默认频道
  * @param {Function} params.renderMessageItem 渲染单条消息 DOM
  * @param {Function} params.attachLastMessageTimeline 附加时间线到末尾消息
+ * @param {Function} params.getActiveBranches 获取当前 activeBranches Map
  * @returns {{ loadMessages: Function, scheduleMessagePatch: Function }} 频道视图控制函数集合
  */
 export function createChannelView({
@@ -44,6 +45,7 @@ export function createChannelView({
 	setAsDefaultChannel,
 	renderMessageItem,
 	attachLastMessageTimeline,
+	getActiveBranches,
 }) {
 	/**
 	 * 将 DAG 消息行调度进增量 patch 队列（同一 eventId 后写覆盖）。
@@ -79,7 +81,10 @@ export function createChannelView({
 					}
 				}
 				if (!changed) return
-				state.displayMessages = mergeChannelMessagesForDisplay(state.rawMessages)
+				const mergedPatch = mergeChannelMessagesForDisplay(state.rawMessages)
+				const { messages: chainMessagesPatch, branchInfo: branchInfoPatch } = buildDisplayChain(mergedPatch, getActiveBranches?.() ?? new Map())
+				state.displayMessages = chainMessagesPatch
+				state.branchInfo = branchInfoPatch
 				state.msgVirtualList?.refresh?.()
 			}
 			catch (e) {
@@ -164,7 +169,9 @@ export function createChannelView({
 		const { messages } = await r.json()
 		state.rawMessages = Array.isArray(messages) ? [...messages] : []
 		const merged = mergeChannelMessagesForDisplay(state.rawMessages)
-		state.displayMessages = merged
+		const { messages: chainMessages, branchInfo } = buildDisplayChain(merged, getActiveBranches?.() ?? new Map())
+		state.displayMessages = chainMessages
+		state.branchInfo = branchInfo
 		const volHold = state.volatileStreamEl
 		if (volHold?.parentNode) volHold.parentNode.removeChild(volHold)
 		state.msgVirtualList?.destroy()
diff --git a/src/public/parts/shells/chat/public/src/ui/dagMessageUtils.mjs b/src/public/parts/shells/chat/public/src/ui/dagMessageUtils.mjs
@@ -81,6 +81,62 @@ function mergeChannelMessagesForDisplay(messages) {
 	return out
 }
 
+/**
+ * 基于 prevMessageEventId 链式指针和 activeBranches 选择，从所有消息中构建当前显示路径。
+ * 在 mergeChannelMessagesForDisplay 的结果之上运行（edit/delete 已折叠完毕）。
+ * @param {object[]} mergedMessages mergeChannelMessagesForDisplay 返回的消息数组
+ * @param {Map<string, string>} activeBranches Key=prevMessageEventId, Value=选中的 eventId
+ * @returns {{ messages: object[], branchInfo: Map<string, { alternatives: object[], selectedIdx: number, branchKey: string }> }} 当前分支路径上的消息列表及各分支点信息
+ */
+function buildDisplayChain(mergedMessages, activeBranches) {
+	const hasPrevPointer = mergedMessages.some(m => m.content?.prevMessageEventId)
+	if (!hasPrevPointer)
+		return { messages: mergedMessages, branchInfo: new Map() }
+
+	const byEventId = new Map()
+	const childrenOf = new Map()
+	for (const m of mergedMessages) {
+		if (m.eventId) byEventId.set(m.eventId, m)
+		const prev = m.content?.prevMessageEventId
+		if (prev) {
+			if (!childrenOf.has(prev)) childrenOf.set(prev, [])
+			childrenOf.get(prev).push(m)
+		}
+	}
+
+	const roots = mergedMessages.filter(m => !m.content?.prevMessageEventId)
+	const result = [...roots]
+	const branchInfo = new Map()
+
+	let cursor = roots[roots.length - 1]?.eventId ?? null
+
+	const visited = new Set()
+	while (cursor !== null && !visited.has(cursor)) {
+		visited.add(cursor)
+		const children = childrenOf.get(cursor)
+		if (!children?.length) break
+
+		if (children.length === 1) {
+			result.push(children[0])
+			cursor = children[0].eventId
+		}
+		else {
+			const activeId = activeBranches.get(cursor)
+			const selected = children.find(m => m.eventId === activeId) ?? children[children.length - 1]
+			const selectedIdx = children.indexOf(selected)
+			branchInfo.set(selected.eventId, {
+				alternatives: children,
+				selectedIdx,
+				branchKey: cursor,
+			})
+			result.push(selected)
+			cursor = selected.eventId
+		}
+	}
+
+	return { messages: result, branchInfo }
+}
+
 /**
  * 按时间线重放 pin/unpin，得到当前仍置顶的 targetEventId 列表（最近置顶在前）。
  * @param {object[]} messages 频道原始消息行（未 merge）
@@ -323,6 +379,7 @@ export {
 	escapeHtml,
 	senderColor,
 	mergeChannelMessagesForDisplay,
+	buildDisplayChain,
 	orderedActivePinTargets,
 	flattenChannelTree,
 	plainPreviewFromLine,
diff --git a/src/public/parts/shells/chat/public/src/ui/messageItem.mjs b/src/public/parts/shells/chat/public/src/ui/messageItem.mjs
@@ -29,6 +29,8 @@ import { showEmojiPicker } from './emojiPicker.mjs'
  *   getEditedIds?: () => Set<string>,
  *   onContentResize?: () => void,
  *   onOpenThread?: (threadChannelId: string) => void,
+ *   getBranchInfo?: () => Map<string, { alternatives: object[], selectedIdx: number, branchKey: string }>,
+ *   onBranchSelect?: (branchKey: string, selectedEventId: string) => void,
  * }} ctx 群聊 UI 依赖（消息列表、头像缓存、表情与文件处理等）。
  * @returns {{ renderMessageItem: (m: object, index: number) => Promise<HTMLElement>, showMessageMenu: (e: MouseEvent, m: object, bubble: HTMLElement) => void, attachLastMessageTimeline: (merged: object[]) => Promise<void> }} 渲染与菜单、时间线方法集合
  */
@@ -49,6 +51,8 @@ export function createMessageItemRenderer(ctx) {
 		getEditedIds,
 		onContentResize,
 		onOpenThread,
+		getBranchInfo,
+		onBranchSelect,
 	} = ctx
 
 	const standaloneHtmlCache = new WeakMap()
@@ -99,10 +103,12 @@ export function createMessageItemRenderer(ctx) {
 
 	/**
 	 * 在最后一条非用户消息上附加时间线导航（◀/▶ + swipe）。
+	 * 若已有链式分支信息（branchInfo），则导航已由 renderMessageItem 处理，跳过。
 	 * @param {object[]} merged 合并后的消息列表
 	 * @returns {Promise<void>}
 	 */
 	async function attachLastMessageTimeline(merged) {
+		if (getBranchInfo?.()?.size > 0) return
 		const lastMsg = [...merged].reverse().find(m => m.type === 'message' && m.sender && m.sender !== 'local')
 			|| [...merged].reverse().find(m => m.type === 'message')
 		if (!lastMsg?.eventId) return
@@ -862,19 +868,79 @@ export function createMessageItemRenderer(ctx) {
 			}
 		}
 
+		const branchData = getBranchInfo?.()?.get(m.eventId)
+		if (branchData && branchData.alternatives.length > 1) {
+			const { alternatives, selectedIdx, branchKey } = branchData
+			const nav = document.createElement('div')
+			nav.className = 'flex items-center gap-1 mt-1 text-xs opacity-70'
+			nav.setAttribute('data-timeline-nav', '1')
+
+			const prevBtn = document.createElement('button')
+			prevBtn.type = 'button'
+			prevBtn.className = 'btn btn-xs btn-ghost px-1'
+			prevBtn.textContent = '◀'
+			prevBtn.disabled = selectedIdx <= 0
+			prevBtn.addEventListener('click', () => {
+				const newSelected = alternatives[selectedIdx - 1]
+				if (newSelected) onBranchSelect?.(branchKey, newSelected.eventId)
+			})
+
+			const label = document.createElement('span')
+			label.className = 'px-1'
+			label.textContent = `${selectedIdx + 1}/${alternatives.length}`
+
+			const nextBtn = document.createElement('button')
+			nextBtn.type = 'button'
+			nextBtn.className = 'btn btn-xs btn-ghost px-1'
+			nextBtn.textContent = '▶'
+			nextBtn.disabled = selectedIdx >= alternatives.length - 1
+			nextBtn.addEventListener('click', async () => {
+				const newSelected = alternatives[selectedIdx + 1]
+				if (newSelected)
+					onBranchSelect?.(branchKey, newSelected.eventId)
+				else {
+					setCurrentChannel(groupId, channelId, 'chat')
+					await modifyTimeLine(1)
+					await loadMessages()
+				}
+			})
+
+			nav.appendChild(prevBtn)
+			nav.appendChild(label)
+			nav.appendChild(nextBtn)
+
+			if (bubble) bubble.after(nav)
+			else div.appendChild(nav)
+		}
+
 		const isCharRoleMessage = m.role === 'char' || (m.type === 'message' && !!m.charId)
-		if (isCharRoleMessage) {
+		if (branchData || isCharRoleMessage) {
 			bubble.setAttribute('data-char-swipe-timeline', '1')
 			let touchStartX = 0
 			bubble.addEventListener('touchstart', e => {
 				touchStartX = e.touches[0].clientX
 			}, { passive: true })
-			bubble.addEventListener('touchend', e => {
+			bubble.addEventListener('touchend', async e => {
 				const dx = e.changedTouches[0].clientX - touchStartX
 				if (Math.abs(dx) <= SWIPE_THRESHOLD) return
 				e.stopPropagation()
-				setCurrentChannel(groupId, channelId, 'chat')
-				void modifyTimeLine(dx < 0 ? 1 : -1).then(() => loadMessages())
+				const direction = dx < 0 ? 1 : -1
+
+				if (branchData) {
+					const { alternatives, selectedIdx, branchKey } = branchData
+					const newIdx = selectedIdx + direction
+					if (newIdx >= 0 && newIdx < alternatives.length)
+						onBranchSelect?.(branchKey, alternatives[newIdx].eventId)
+					else if (newIdx >= alternatives.length) {
+						setCurrentChannel(groupId, channelId, 'chat')
+						await modifyTimeLine(direction)
+						await loadMessages()
+					}
+				}
+				else {
+					setCurrentChannel(groupId, channelId, 'chat')
+					void modifyTimeLine(direction).then(() => loadMessages())
+				}
 			}, { passive: true })
 		}
 		return div
diff --git a/src/public/parts/shells/chat/src/chat/session.mjs b/src/public/parts/shells/chat/src/chat/session.mjs
@@ -1269,6 +1269,11 @@ async function syncChatLogEntryToDag(groupId, entry, username) {
 		const channelIdForDag = typeof groupCh === 'string' && /^[\w.-]+$/.test(groupCh) && groupCh.length <= 128
 			? groupCh
 			: await getDefaultChannelId(username, groupId)
+		try {
+			const recentMessages = await listChannelMessages(username, groupId, channelIdForDag, { limit: 1 })
+			const prevMessageEventId = recentMessages[recentMessages.length - 1]?.eventId
+			if (prevMessageEventId) content.prevMessageEventId = prevMessageEventId
+		} catch { /* ignore，prevMessageEventId 缺失时退化为旧行为 */ }
 		await appendEvent(username, groupId, {
 			type: 'message',
 			channelId: channelIdForDag,
