dsh-mega-chat-nav 0.1.1

package/src/compat.ts

@@ -0,0 +1,161 @@
+/**
+ * dsh 版本校验器（纯函数，零依赖：宿主侧 / 单测均可用）。
+ *
+ * 语义（对齐官方 deepseek-harness tag 线，如 dsh-v0.1.1-rc.2）：
+ * - 比较按语义化版本：主/次/修订号数值比较优先；
+ * - 同基线预发布排序：alpha < rc（标识符字典序），数字标识按数值比较；
+ * - 正式版（无预发布）高于同基线任意预发布（0.1.1 > 0.1.1-rc.2）；
+ * - 支持操作符：>  <  =（另附 >=  <=）；
+ * - 通配：仅 '=' 支持，如 '0.1.1-*' 匹配该基线的任意预发布（0.1.1-rc.1 / 0.1.1-rc.2 …）；
+ *   '*' 作为标识段时吞掉其后的全部剩余标识。
+ */
+export type DshCmpOp = '>' | '>=' | '<' | '<=' | '='
+
+/** 兼容策略：当前 dsh 版本与目标的比较约束。 */
+export interface DshCompatPolicy {
+  op: DshCmpOp
+  /**
+   * 目标版本（可含通配，如 0.1.1-*，仅 op='=' 生效）。
+   * 支持数组：命中其中任一版本即通过，如 ['0.1.1-*', '0.1.2-rc.1']。
+   */
+  target: string | readonly string[]
+}
+
+export interface DshVersionParts {
+  /** [major, minor, patch] */
+  base: [number, number, number]
+  /** 预发布标识数组（rc、alpha、数字…）；无预发布 = null */
+  pre: string[] | null
+}
+
+const VERSION_RE = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/
+
+/** 解析 dsh 版本串；非法返回 null（不支持 x.y / 纯数字 etc.）。 */
+export function parseDshVersion(v: string): DshVersionParts | null {
+  const m = VERSION_RE.exec(v.trim())
+  if (!m) return null
+  const pre = m[4] !== undefined ? m[4].split('.') : null
+  if (pre !== null && pre.some((s) => s === '')) return null
+  return { base: [Number(m[1]), Number(m[2]), Number(m[3])], pre }
+}
+
+function compareIdent(a: string, b: string): number {
+  const na = /^\d+$/.test(a)
+  const nb = /^\d+$/.test(b)
+  if (na && nb) {
+    const x = Number(a)
+    const y = Number(b)
+    return x === y ? 0 : x < y ? -1 : 1
+  }
+  if (na) return -1 // 数字标识 < 字母标识
+  if (nb) return 1
+  return a === b ? 0 : a < b ? -1 : 1
+}
+
+function comparePre(a: string[], b: string[]): number {
+  const n = Math.min(a.length, b.length)
+  for (let i = 0; i < n; i++) {
+    const c = compareIdent(a[i], b[i])
+    if (c !== 0) return c
+  }
+  return a.length === b.length ? 0 : a.length < b.length ? -1 : 1
+}
+
+/**
+ * 语义化比较：a < b → -1；相等 → 0；a > b → 1；任一无法解析 → NaN。
+ */
+export function compareDshVersions(a: string, b: string): number {
+  const pa = parseDshVersion(a)
+  const pb = parseDshVersion(b)
+  if (pa === null || pb === null) return NaN
+  for (let i = 0; i < 3; i++) {
+    if (pa.base[i] !== pb.base[i]) return pa.base[i] < pb.base[i] ? -1 : 1
+  }
+  if (pa.pre === null && pb.pre === null) return 0
+  if (pa.pre === null) return 1 // 正式版高于同基线任意预发布
+  if (pb.pre === null) return -1
+  return comparePre(pa.pre, pb.pre)
+}
+
+/** 操作符比较（非法版本一律 false）。 */
+export function checkDshVersion(current: string, op: DshCmpOp, target: string): boolean {
+  const c = compareDshVersions(current, target)
+  if (Number.isNaN(c)) return false
+  switch (op) {
+    case '>':
+      return c > 0
+    case '>=':
+      return c >= 0
+    case '<':
+      return c < 0
+    case '<=':
+      return c <= 0
+    default:
+      return c === 0
+  }
+}
+
+/** 标识段匹配：'*' 吞掉 ≥1 个剩余标识；静态段全等（全数字按数值比较）。 */
+function matchIdents(cur: string[], pat: string[]): boolean {
+  const f = (i: number, j: number): boolean => {
+    if (i === cur.length && j === pat.length) return true
+    if (j === pat.length) return false
+    if (pat[j] === '*') {
+      if (i >= cur.length) return false // * 至少匹配 1 个
+      for (let k = i + 1; k <= cur.length; k++) {
+        if (f(k, j + 1)) return true
+      }
+      return false
+    }
+    if (i >= cur.length) return false
+    if (compareIdent(pat[j], cur[i]) !== 0) return false
+    return f(i + 1, j + 1)
+  }
+  return f(0, 0)
+}
+
+/**
+ * 通配相等（仅配合 op='='）：pattern 形如 0.1.1-*（任意预发布）、0.1.1-rc.*、
+ * 0.1.*（任意小版本）等；'*' 匹配 ≥1 个标识。例：0.1.1-* 命中 0.1.1-rc.1 / 0.1.1-rc.2。
+ */
+export function wildcardEqual(version: string, pattern: string): boolean {
+  const pv = parseDshVersion(version)
+  if (pv === null) return false
+  const dash = pattern.indexOf('-')
+  const basePat = (dash >= 0 ? pattern.slice(0, dash) : pattern).split('.')
+  const prePat = dash >= 0 ? pattern.slice(dash + 1).split('.') : null
+  if (basePat.length !== 3) return false
+  const baseHasStar = basePat.some((t) => t === '*')
+  for (let i = 0; i < 3; i++) {
+    const t = basePat[i]
+    if (t === '*') continue
+    if (!/^\d+$/.test(t)) return false
+    if (Number(t) !== pv.base[i]) return false
+  }
+  if (prePat === null) {
+    // 无预发布子句：基线精确时要求同为正式版；基线含通配（0.1.*）则任意预发布也算命中
+    return baseHasStar || pv.pre === null
+  }
+  if (pv.pre === null) return false // 模式含预发布通配：当前必须有预发布
+  return matchIdents(pv.pre, prePat)
+}
+
+/** 单项命中：target 含 '*' 时仅接受 op='=' 的通配比较，否则按操作符数值比较。 */
+function entryPasses(current: string, op: DshCmpOp, target: string): boolean {
+  if (target.includes('*')) {
+    if (op !== '=') return false
+    return wildcardEqual(current, target)
+  }
+  return checkDshVersion(current, op, target)
+}
+
+/** 策略校验：target 为数组时命中任一即通过；通配（如 0.1.1-*）仅在 op='=' 时参与。 */
+export function checkDshPolicy(current: string, policy: DshCompatPolicy): boolean {
+  const targets = Array.isArray(policy.target) ? policy.target : [policy.target]
+  return targets.some((t) => entryPasses(current, policy.op, t))
+}
+
+/** 不兼容时的控制台提示文案（xxx = 检测到的当前 dsh 版本）。 */
+export function dshCompatMessage(pluginName: string, currentDshVersion: string): string {
+  return pluginName + ' 可能不适配 dsh ' + currentDshVersion + ' 版本，请慎重使用'
+}

package/src/index.ts

@@ -0,0 +1,66 @@
+/**
+ * Host half of the dsh-mega-chat-nav plugin — runs in the DSH host process.
+ * Registers the `msgNavMessages` session projection unit (the ordered list
+ * of user questions, each tagged with its turn) and the plugin's durable
+ * settings namespace. Both registries are optional capabilities, so each
+ * registration rides `ctx.inject`: without them the host half contributes
+ * nothing and the browser strip falls back to live-window questions and
+ * default rail alignment.
+ */
+import { readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import type { Context } from '@deepseek-ai/cordis'
+import { msgNavProjectionDefinition } from './projection.ts'
+import { registerSearchRoute } from './search.ts'
+import { megaChatNavSettingsNamespace, NavSettingsSchema } from './settings.ts'
+import { checkDshPolicy, dshCompatMessage, type DshCompatPolicy } from './compat.ts'
+
+/** Cordis plugin name. */
+export const name = 'dsh-mega-chat-nav'
+
+/**
+ * 兼容策略（按需修改）：
+ * - '= 0.1.1-*' = 支持 dsh-v0.1.1 整条预发布线（0.1.1-rc.1 / rc.2）；
+ * - target 支持数组：命中任一即通过，如 ['0.1.1', '0.1.2-rc.1']；
+ * - 关系约束示例：{ op: '>=', target: '0.1.1-rc.2' }。
+ */
+const DSCH_COMPAT_POLICY: DshCompatPolicy = { op: '=', target: '0.1.1-*' }
+
+const dshRequire = createRequire(import.meta.url)
+
+/** 探测当前 dsh 版本：@deepseek-ai/dsh 本体 → dsh → dsh-client-runtime（与 tag 线 lockstep） */
+function detectDshVersion(): string | null {
+  for (const pkg of ['@deepseek-ai/dsh', 'dsh', '@deepseek-ai/dsh-client-runtime']) {
+    try {
+      const pkgJson = dshRequire.resolve(pkg + '/package.json')
+      const parsed = JSON.parse(readFileSync(pkgJson, 'utf8')) as { version?: string }
+      if (typeof parsed.version === 'string' && parsed.version.length > 0) return parsed.version
+    } catch {
+      /* 尝试下一候选 */
+    }
+  }
+  return null
+}
+
+export function apply(ctx: Context): void {
+  // dsh 版本兼容校验：检测失败或不合规只打印警示，不阻断插件加载
+  try {
+    const dshVer = detectDshVersion()
+    if (dshVer !== null && !checkDshPolicy(dshVer, DSCH_COMPAT_POLICY)) {
+      console.warn(dshCompatMessage(name, dshVer))
+    }
+  } catch {
+    /* 校验器自身异常不应影响插件 */
+  }
+  ctx.inject(['sessionProjections'], (inner) => {
+    inner.sessionProjections.register(msgNavProjectionDefinition)
+  })
+  ctx.inject(['settings'], (settingsCtx) => {
+    settingsCtx.settings.register(megaChatNavSettingsNamespace, NavSettingsSchema)
+  })
+  try {
+    registerSearchRoute(ctx)
+  } catch (e) {
+    console.error('[dsh-mega-chat-nav] search route failed:', e)
+  }
+}

package/src/projection.ts

@@ -0,0 +1,174 @@
+/**
+ * The `msgNavMessages` session projection unit: a pure fold of the session
+ * event log into the ordered list of user questions, each tagged with the
+ * turn that claimed it. Registered on `ctx.sessionProjections` by the host
+ * half (src/index.ts); persistence, replay, and client delivery are the
+ * projection seam's (session-projection-cache checkpoints the state, the
+ * api-proxy carriers seed + push the wire view).
+ *
+ * Fold rules mirror the chat messageDefinition classification: an
+ * append-origin `user/message` with a human (`user`) source is a question;
+ * replacement copies (compaction checkpoints) and injected context are not.
+ * Turns come from `turn/start` boundaries, so retry/goal-continuation turns
+ * without a question simply produce no entry — dots may skip turn numbers,
+ * staying exactly aligned with the Trajectory view's turn labels.
+ *
+ * @module dsh-mega-chat-nav/projection
+ */
+
+import { z } from 'zod'
+import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection'
+
+/** 注册本投影单元到框架的合并扩展表（接口声明于 /types 出口，须在声明处合并） */
+declare module '@deepseek-ai/dsh-session-projection/types' {
+  interface SessionProjectionStateMap {
+    msgNavMessages: QuestionIndexState
+  }
+  interface SessionProjectionMap {
+    msgNavMessages: NavItem[]
+  }
+}
+
+/** 投影条目：一条 user/message 提问的轻量索引（正文零驻留） */
+export interface NavItem {
+  /** 归属回合号（turn/start 之后的第一个提问） */
+  turn: number
+  /** 消息稳定 id（跳转锚点推导源） */
+  id: string
+  /** 事件 seq（排序与锚点序号） */
+  seq: number
+  /** Unix 毫秒时间戳 */
+  time: number
+  /** 首文本块（悬停/级联卡正文） */
+  text: string
+  /** 该轮性能指标（view 附加；缺数据时省略） */
+  metrics?: { durationMs: number; firstTokenMs: number; tokensPerSec: number }
+}
+
+/** Fold state: the last opened turn plus every question recorded so far. */
+/** 一轮的性能指标（由 turn/start、assistant/chunk、assistant/message 折叠） */
+interface TurnMetric {
+  /** 轮开始时间（turn/start） */
+  startedAt: number
+  /** 首个内容增量块时间（assistant/chunk 首 text/reasoning delta）；未流式时为 null */
+  firstTokenAt: number | null
+  /** 轮结束时间（assistant/message）；未完成时为 null */
+  finishedAt: number | null
+  /** 累计输出 token（assistant/message 的 usage.outputTokens 求和） */
+  outputTokens: number
+}
+
+interface QuestionIndexState {
+  /** Turn of the last `turn/start` (0 before any; turns are 1-based). */
+  turn: number
+  /** Every recorded question, in event order. */
+  questions: NavItem[]
+  /** 每轮性能指标（turn 号 → 指标） */
+  metrics: Record<number, TurnMetric>
+}
+
+const navEntrySchema = z.object({
+  turn: z.number(),
+  id: z.string(),
+  seq: z.number(),
+  time: z.number(),
+  text: z.string(),
+  metrics: z.object({
+    durationMs: z.number(),
+    firstTokenMs: z.number(),
+    tokensPerSec: z.number(),
+  }).optional(),
+})
+
+const turnMetricSchema = z.object({
+  startedAt: z.number(),
+  firstTokenAt: z.number().nullable(),
+  finishedAt: z.number().nullable(),
+  outputTokens: z.number(),
+})
+
+const msgNavMessagesStateSchema = z.object({
+  turn: z.number(),
+  questions: z.array(navEntrySchema),
+  metrics: z.record(z.number(), turnMetricSchema),
+}).strict()
+
+/** Validates the wire payload before it leaves the host. */
+const msgNavMessagesViewSchema = z.array(navEntrySchema)
+
+/** First text block of a user message; empty string when absent. */
+function messageText(content: readonly { type?: string; text?: string }[] | undefined): string {
+  const block = content?.find((part) => typeof part?.text === 'string')
+  return block?.text ?? ''
+}
+
+/** The `msgNavMessages` unit registered on `ctx.sessionProjections`. */
+export const msgNavProjectionDefinition: Omit<ProjectionDefinition<'msgNavMessages', QuestionIndexState>, 'wire'> & {
+  wire: NonNullable<ProjectionDefinition<'msgNavMessages', QuestionIndexState>['wire']>
+} = {
+  key: 'msgNavMessages',
+  stateVersion: 2,
+  stateSchema: msgNavMessagesStateSchema,
+  init: () => ({ turn: 0, questions: [], metrics: {} }),
+  apply: (state: QuestionIndexState, event) => {
+    // Every uninteresting event returns the same reference (Object.is gates
+    // the change feed and the persisted-cache dirty check).
+    switch (event.type) {
+      case 'turn/start': {
+        if (event.data.turn === state.turn) return state
+        const metrics = { ...state.metrics }
+        metrics[event.data.turn] = { startedAt: event.time, firstTokenAt: null, finishedAt: null, outputTokens: 0 }
+        return { ...state, turn: event.data.turn, metrics }
+      }
+      case 'user/message': {
+        if (event.surfaceOp !== 'append') return state
+        if (event.data.source?.kind !== 'user') return state
+        const entry: NavItem = {
+          turn: state.turn,
+          id: String(event.data.id),
+          seq: event.seq,
+          time: event.time,
+          text: messageText(event.data.content),
+        }
+        return { ...state, questions: [...state.questions, entry] }
+      }
+      case 'assistant/chunk': {
+        // 只记录每轮首个内容增量块（首 token 时间）；后续增量块不产生新 state
+        const turn = event.data.turn
+        const chunk = event.data.chunk
+        const current = state.metrics[turn]
+        if (current === undefined) return state
+        if (current.firstTokenAt !== null) return state
+        if (chunk?.type !== 'text-delta' && chunk?.type !== 'reasoning-delta') return state
+        const metrics = { ...state.metrics, [turn]: { ...current, firstTokenAt: event.time } }
+        return { ...state, metrics }
+      }
+      case 'assistant/message': {
+        const turn = event.data.turn
+        const current = state.metrics[turn]
+        if (current === undefined) return state
+        const output = typeof event.data.usage?.outputTokens === 'number' ? event.data.usage.outputTokens : 0
+        if (output === 0 && current.finishedAt !== null) return state
+        const metrics = {
+          ...state.metrics,
+          [turn]: { ...current, finishedAt: event.time, outputTokens: current.outputTokens + output },
+        }
+        return { ...state, metrics }
+      }
+      default:
+        return state
+    }
+  },
+  wire: {
+    viewSchema: msgNavMessagesViewSchema,
+    view: (state: QuestionIndexState) => state.questions.map((q) => {
+      const m = state.metrics[q.turn]
+      if (m === undefined || m.finishedAt === null || m.startedAt <= 0) return q
+      const durationMs = m.finishedAt - m.startedAt
+      if (durationMs <= 0) return q
+      const firstTokenMs = m.firstTokenAt !== null ? m.firstTokenAt - m.startedAt : 0
+      const tokensPerSec = durationMs > 0 ? Math.round((m.outputTokens * 1000) / durationMs) : 0
+      return { ...q, metrics: { durationMs, firstTokenMs, tokensPerSec } }
+    }),
+  },
+}