dsh-sessions-manager 3.2.2 → 3.3.0

package/src/client/index.jsx

@@ -11,7 +11,7 @@
  */
 
 import React, { useEffect, useMemo, useRef, useState } from 'react'
-import { canDropOnWorkspace, dotStateFor, sessionForNodes, workspaceForNodes } from './logic.js'
+import { canDropOnWorkspace, dotStateFor, sessionForNodes, starredOf, workspaceForNodes } from './logic.js'
 
 export const inject = ['slots']
 
@@ -55,6 +55,11 @@ const CSS = `
 .archv-id{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:10.5px;color:var(--dsw-alias-label-tertiary);flex:none}
 .archv-dot{color:var(--dsw-alias-border-l3);flex:none}
 .archv-check{width:15px;height:15px;accent-color:var(--dsw-alias-state-business-primary);flex:none;cursor:pointer}
+.archv-star{appearance:none;width:24px;height:24px;flex:none;display:inline-flex;align-items:center;justify-content:center;border:none;background:0 0;border-radius:7px;cursor:pointer;color:var(--dsw-alias-label-tertiary);transition:color .15s ease,background-color .15s ease}
+.archv-star:hover{background:var(--dsw-alias-interactive-bg-hover);color:var(--dsw-alias-label-secondary)}
+.archv-star svg{fill:none;stroke:currentColor;stroke-width:1.5;stroke-linejoin:round}
+.archv-star-on,.archv-star-on:hover{color:var(--dsw-alias-state-business-primary)}
+.archv-star-on svg{fill:currentColor}
 .archv-body{flex:1;min-width:0;display:flex;align-items:center;gap:12px}
 .archv-actions{display:flex;gap:8px;flex:none;flex-wrap:nowrap;justify-content:flex-end}
 .archv-btn{appearance:none;min-height:32px;padding:0 12px;border:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-fill-subtle);color:var(--dsw-alias-label-secondary);border-radius:9px;font-size:12px;font-weight:500;cursor:pointer;white-space:nowrap;display:inline-flex;align-items:center;justify-content:center;gap:6px;text-align:center;transition:background-color .15s ease,border-color .15s ease,color .15s ease}
@@ -100,6 +105,9 @@ const CSS = `
 .dtl-k{font-size:11px;color:var(--dsw-alias-label-tertiary)}
 .dtl-v{font-size:12px;color:var(--dsw-alias-label-primary);word-break:break-all}
 .dtl-sec{margin-top:12px}
+.dtl-export{display:flex;align-items:center;gap:8px;flex-wrap:wrap}
+.dtl-export .archv-btn{text-decoration:none}
+.dtl-note{margin-top:8px;font-size:11px;color:var(--dsw-alias-label-tertiary);line-height:1.5}
 .dtl-sec-t{font-size:11px;font-weight:600;color:var(--dsw-alias-label-secondary);text-transform:uppercase;letter-spacing:.03em;margin-bottom:6px}
 .dtl-tags{display:flex;flex-wrap:wrap;gap:6px}
 .dtl-tag{display:inline-flex;font-size:11px;color:var(--dsw-alias-label-secondary);background:var(--dsw-alias-fill-elevated);border:1px solid var(--dsw-alias-border-l2);border-radius:var(--dsm-radius-tag);padding:2px 8px}
@@ -212,7 +220,7 @@ function SessionPanel({ workspacesSvc }) {
   const [sessions, setSessions] = useState(null)
   const [workspaces, setWorkspaces] = useState([])
   const initialPrefs = useRef(loadPanelPrefs()).current
-  const [filter, setFilter] = useState(() => ['all', 'active', 'archived', 'trash'].includes(initialPrefs.filter) ? initialPrefs.filter : 'all')
+  const [filter, setFilter] = useState(() => ['all', 'active', 'archived', 'starred', 'trash'].includes(initialPrefs.filter) ? initialPrefs.filter : 'all')
   const [query, setQuery] = useState('')
   const [workspaceFilter, setWorkspaceFilter] = useState(() => initialPrefs.workspaceFilter || 'all')
   const [sortBy, setSortBy] = useState(() => ['newest', 'oldest', 'title'].includes(initialPrefs.sortBy) ? initialPrefs.sortBy : 'newest')
@@ -235,6 +243,9 @@ function SessionPanel({ workspacesSvc }) {
   const [details, setDetails] = useState({})
   const [openDetails, setOpenDetails] = useState(null)
   const [detailsLoading, setDetailsLoading] = useState(null)
+  const [mdBusy, setMdBusy] = useState(null)
+  const [zipOk, setZipOk] = useState(true)
+  const zipChecked = useRef(false)
   const [openMenu, setOpenMenu] = useState(null)
   const timer = useRef(null)
   const menuRef = useRef(null)
@@ -278,6 +289,53 @@ function SessionPanel({ workspacesSvc }) {
     try { localStorage.setItem(PANEL_PREFS_KEY, JSON.stringify({ filter, workspaceFilter, sortBy })) } catch (e) {}
   }, [filter, workspaceFilter, sortBy])
 
+  // 收藏切换：乐观更新 + 失败回滚（star 是高频轻操作，不等网络往返）。
+  const toggleStar = async (it) => {
+    const next = !it.starred
+    setSessions((s) => s && s.map((x) => (x.sessionId === it.sessionId ? { ...x, starred: next } : x)))
+    try {
+      await postJSON('/archived-sessions/star/set', { sessionId: it.sessionId, starred: next })
+    } catch (e) {
+      setSessions((s) => s && s.map((x) => (x.sessionId === it.sessionId ? { ...x, starred: !next } : x)))
+      showToast('收藏失败：' + String((e && e.message) || e))
+    }
+  }
+
+  // Markdown 导出：自有路由（/archived-sessions/export-md），blob 触发下载。
+  const exportMarkdown = async (it) => {
+    if (mdBusy) return
+    setMdBusy(it.sessionId)
+    try {
+      const res = await fetch('/archived-sessions/export-md?sessionId=' + encodeURIComponent(it.sessionId))
+      if (!res.ok) throw new Error('HTTP ' + res.status)
+      const blob = await res.blob()
+      const url = URL.createObjectURL(blob)
+      const a = document.createElement('a')
+      a.href = url
+      a.download = 'dsh-session-' + it.sessionId + '.md'
+      document.body.appendChild(a)
+      a.click()
+      a.remove()
+      URL.revokeObjectURL(url)
+      showToast('已导出 Markdown')
+    } catch (e) {
+      showToast('导出失败：' + String((e && e.message) || e))
+    } finally {
+      setMdBusy(null)
+    }
+  }
+
+  // 官方 ZIP 导出预检（一次性）：后端不支持 raw artifacts 时返回 501，
+  // 此时隐藏 ZIP 入口只留 Markdown（全局缓存，后端能力不会中途变）。
+  // 探针用非法 id 走 HEAD：命中 501 = 不支持；404/400 = 路由活着且支持。
+  useEffect(() => {
+    if (openDetails === null || zipChecked.current) return
+    zipChecked.current = true
+    fetch('/api/session.export?sessionId=probe&includeDescendants=false', { method: 'HEAD' })
+      .then((res) => setZipOk(res.status !== 501))
+      .catch(() => setZipOk(true))
+  }, [openDetails])
+
   // Close the ⋯ menu on outside click / Escape (no full-screen backdrop).
   useEffect(() => {
     if (openMenu === null) return
@@ -314,9 +372,10 @@ function SessionPanel({ workspacesSvc }) {
 
   const archivedList = sessions ? sessions.filter((x) => x.archived) : []
   const activeList = sessions ? sessions.filter((x) => !x.archived) : []
+  const starredList = starredOf(sessions)
   const list = useMemo(() => {
     if (filter === 'trash') return []
-    const base = filter === 'archived' ? archivedList : filter === 'active' ? activeList : sessions || []
+    const base = filter === 'archived' ? archivedList : filter === 'active' ? activeList : filter === 'starred' ? starredList : sessions || []
     const needle = query.trim().toLocaleLowerCase()
     const filtered = base.filter((item) => {
       if (workspaceFilter !== 'all' && (item.workspacePath || '') !== workspaceFilter) return false
@@ -569,6 +628,7 @@ function SessionPanel({ workspacesSvc }) {
             <button type="button" role="tab" aria-selected={filter === 'all'} className={'sess-fbtn' + (filter === 'all' ? ' sess-fbtn-on' : '')} onClick={() => { setFilter('all'); clearSel(); setConfirmBatch(false) }}>全部 ({sessions.length})</button>
             <button type="button" role="tab" aria-selected={filter === 'active'} className={'sess-fbtn' + (filter === 'active' ? ' sess-fbtn-on' : '')} onClick={() => { setFilter('active'); clearSel(); setConfirmBatch(false) }}>活动 ({activeList.length})</button>
             <button type="button" role="tab" aria-selected={filter === 'archived'} className={'sess-fbtn' + (filter === 'archived' ? ' sess-fbtn-on' : '')} onClick={() => { setFilter('archived'); clearSel(); setConfirmBatch(false) }}>已归档 ({archivedList.length})</button>
+            <button type="button" role="tab" aria-selected={filter === 'starred'} className={'sess-fbtn' + (filter === 'starred' ? ' sess-fbtn-on' : '')} onClick={() => { setFilter('starred'); clearSel(); setConfirmBatch(false) }}>已收藏 ({starredList.length})</button>
             <button type="button" role="tab" aria-selected={filter === 'trash'} className={'sess-fbtn' + (filter === 'trash' ? ' sess-fbtn-on' : '')} onClick={() => { setFilter('trash'); clearSel(); setConfirmBatch(false) }}>回收站 ({trash.length})</button>
           </div>
 
@@ -593,13 +653,13 @@ function SessionPanel({ workspacesSvc }) {
                   </select>
                 </div>
               </div>
-              <div className="sess-results" role="status">显示 {list.length} 个会话{query || workspaceFilter !== 'all' ? `，共 ${filter === 'archived' ? archivedList.length : filter === 'active' ? activeList.length : sessions.length} 个` : ''}</div>
+              <div className="sess-results" role="status">显示 {list.length} 个会话{query || workspaceFilter !== 'all' ? `，共 ${filter === 'archived' ? archivedList.length : filter === 'active' ? activeList.length : filter === 'starred' ? starredList.length : sessions.length} 个` : ''}</div>
             </>
           )}
 
           {filter !== 'trash' && list.length > 0 && (
             <div className="sess-batch">
-              <span className="sess-btntext">{selIds.length ? `已选 ${selIds.length} 项` : (filter === 'archived' ? `共 ${archivedList.length} 个归档会话` : `共 ${sessions.length} 个会话（活动 ${activeList.length} / 已归档 ${archivedList.length}）`)}</span>
+              <span className="sess-btntext">{selIds.length ? `已选 ${selIds.length} 项` : (filter === 'archived' ? `共 ${archivedList.length} 个归档会话` : filter === 'starred' ? `共 ${starredList.length} 个收藏会话` : `共 ${sessions.length} 个会话（活动 ${activeList.length} / 已归档 ${archivedList.length}）`)}</span>
               <button type="button" className="archv-btn" disabled={list.length === 0} onClick={selectAll}>全选</button>
               {selIds.length > 0 && (
                 <>
@@ -619,7 +679,7 @@ function SessionPanel({ workspacesSvc }) {
           )}
 
           {filter !== 'trash' && list.length === 0 ? (
-            <div className="archv-empty">{query || workspaceFilter !== 'all' ? '没有匹配的会话。请调整搜索词或工作区筛选。' : filter === 'archived' ? '目前没有归档会话。在“全部”里选中会话点“归档”即可收纳进来。' : filter === 'active' ? '目前没有活动会话。' : '暂无可管理的会话。'}</div>
+            <div className="archv-empty">{query || workspaceFilter !== 'all' ? '没有匹配的会话。请调整搜索词或工作区筛选。' : filter === 'archived' ? '目前没有归档会话。在“全部”里选中会话点“归档”即可收纳进来。' : filter === 'active' ? '目前没有活动会话。' : filter === 'starred' ? '还没有收藏的会话。点击会话左侧的星标即可收藏。' : '暂无可管理的会话。'}</div>
           ) : filter !== 'trash' ? (
             <div className="archv-list" role="list">
               {list.map((it) => {
@@ -635,6 +695,16 @@ function SessionPanel({ workspacesSvc }) {
                         onChange={() => toggle(it.sessionId)}
                         aria-label={'选择 ' + (it.title || it.sessionId)}
                       />
+                      <button
+                        type="button"
+                        className={'archv-star' + (it.starred ? ' archv-star-on' : '')}
+                        aria-pressed={!!it.starred}
+                        aria-label={(it.starred ? '取消收藏 ' : '收藏 ') + (it.title || it.sessionId)}
+                        title={it.starred ? '取消收藏' : '收藏'}
+                        onClick={(e) => { e.stopPropagation(); toggleStar(it) }}
+                      >
+                        <svg viewBox="0 0 24 24" width="15" height="15" aria-hidden="true" focusable="false"><path d="M12 2.5l2.9 5.9 6.6.9-4.8 4.6 1.2 6.5-5.9-3.1-5.9 3.1 1.2-6.5L2.5 9.3l6.6-.9z" /></svg>
+                      </button>
                       <div className="archv-body">
                         <div className="archv-main">
                           <div className="archv-name" title={it.title || ''}>{it.title || '(无标题)'}</div>
@@ -746,6 +816,20 @@ function SessionPanel({ workspacesSvc }) {
                                   </div>
                                 </div>
                               )}
+                              <div className="dtl-sec">
+                                <div className="dtl-sec-t">导出</div>
+                                <div className="dtl-export">
+                                  <a
+                                    className="archv-btn"
+                                    href={`/api/session.export?sessionId=${encodeURIComponent(it.sessionId)}&includeDescendants=true`}
+                                    onClick={(e) => e.stopPropagation()}
+                                    style={zipOk ? undefined : { pointerEvents: 'none', opacity: 0.45 }}
+                                    title={zipOk ? '含子会话与附件，由 DSH 提供' : '当前持久化后端不支持原始日志导出'}
+                                  >下载原始日志 (ZIP)</a>
+                                  <button type="button" className="archv-btn" disabled={mdBusy === it.sessionId} onClick={() => exportMarkdown(it)}>{mdBusy === it.sessionId ? '生成中…' : '导出 Markdown'}</button>
+                                </div>
+                                <div className="dtl-note">ZIP 含子会话与附件，由 DSH 提供 · Markdown 为本插件生成的可读对话记录</div>
+                              </div>
                             </div>
                           )
                         })()}

package/src/client/logic.js

@@ -51,3 +51,9 @@ export function workspaceForNodes(nodes) {
   }
   return null
 }
+
+// 收藏过滤：返回已收藏子集。star 是用户标记，与 DSH 的活动/归档状态正交
+// （可叠加），所以这里不做任何状态联合判断，只认 starred 字段。
+export function starredOf(items) {
+  return (items || []).filter((item) => item && item.starred)
+}

package/src/index.js

@@ -12,6 +12,8 @@ import { basename, dirname, isAbsolute, join } from 'node:path'
 import { readFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { rewriteFrame0Cwd } from './zstd-frame.js'
+import { renderSessionMarkdown } from './markdown.js'
+import { createStarIndex } from './star-index.js'
 
 export const name = 'dsh-sessions-manager'
 export const inject = ['webServer', 'workspaceRegistry', 'sessionPersistence', 'sessionQuery', 'storageDomain']
@@ -226,6 +228,21 @@ export function apply(ctx) {
     return operation
   }
 
+  // ---- Starred sessions (收藏, schema v3) -----------------------------------
+  // User marks, kept in the plugin's own index (never touches DSH logs). Stars
+  // survive archive & soft-delete — both are reversible — and are dropped only
+  // when the session is really gone (purge, or externally removed; the latter
+  // is caught by gcStars during list builds).
+  const stars = createStarIndex()
+  async function gcStars(validIds) {
+    try {
+      const store = await stars.read()
+      const valid = new Set(validIds.map(String))
+      const gone = store.starredSessionIds.filter((id) => !valid.has(id))
+      if (gone.length) await stars.removeIds(gone)
+    } catch (e) { /* best-effort */ }
+  }
+
   // Soft-delete one session: record it in the recycle-bin index but KEEP its
   // log in the original workspace directory. Moving the file out (and detaching
   // it from the workspace) orphaned the session into DSH's "未分组" group and
@@ -364,6 +381,7 @@ export function apply(ctx) {
       purged = true
     })
     if (!purged) throw new Error('彻底删除失败')
+    stars.removeIds([sid]).catch(() => {})
     return { ok: true, purged: true }
   }
 
@@ -644,9 +662,11 @@ export function apply(ctx) {
   async function allSessionItems() {
     let materialized = new Set()
     let live = ctx.get('sessions')
+    let headersOk = false
     try {
       const headers = await sp.list()
       materialized = new Set(headers.map((h) => String(h.id)))
+      headersOk = true
     } catch (e) { /* best-effort */ }
     const ids = []
     try { for (const header of await sp.list()) ids.push(String(header.id)) } catch (e) { /* ignore */ }
@@ -668,6 +688,12 @@ export function apply(ctx) {
       const res2 = await Promise.all(visibleIds.slice(i, i + CHUNK).map(resolveOne))
       for (const it of res2) items.push({ ...it, archived: currentArchived.has(it.sessionId) })
     }
+    // Annotate stars; GC only when we have a trustworthy id baseline, so a
+    // failing sp.list() can never wipe the whole index.
+    let starredSet = new Set()
+    try { starredSet = new Set((await stars.read()).starredSessionIds) } catch (e) {}
+    for (const it of items) it.starred = starredSet.has(String(it.sessionId))
+    if (headersOk) await gcStars(ids)
     return items
   }
 
@@ -1049,6 +1075,57 @@ export function apply(ctx) {
       },
     }))
 
+    // Star / unstar one or many sessions (收藏, schema v3).
+    disposers.push(ctx.webServer.register({
+      kind: 'exact',
+      path: '/archived-sessions/star/set',
+      handler: async (req, res) => {
+        try {
+          const body = await readJsonBody(req)
+          const starred = !!(body && body.starred)
+          let ids = parseIds(body)
+          if ((!ids || ids.length === 0) && body && typeof body.sessionId === 'string') {
+            ids = isSafeSessionId(body.sessionId) ? [body.sessionId] : null
+          }
+          if (!ids || ids.length === 0) return json(res, { ok: false, error: 'missing sessionId' }, 400)
+          const starredSessionIds = await stars.setStarred(ids, starred)
+          json(res, { ok: true, starredSessionIds })
+        } catch (e) {
+          json(res, { ok: false, error: String((e && e.message) || e) }, errorStatus(e))
+        }
+      },
+    }))
+
+    // Human-readable Markdown export (one session). Raw-log ZIP export is
+    // dsh's own GET /api/session.export — we deliberately do not duplicate it
+    // (see reports/HANDOFF-dsh-sessions-manager-roadmap.md §2.4).
+    disposers.push(ctx.webServer.register({
+      kind: 'exact',
+      path: '/archived-sessions/export-md',
+      handler: async (req, res) => {
+        try {
+          const url = new URL(req.url, 'http://localhost')
+          const sid = url.searchParams.get('sessionId')
+          requireSessionId(sid)
+          const r = await sp.readFrom(sid, 0)
+          if (!r || !r.meta) {
+            const error = new Error('无法读取该会话的日志')
+            error.status = 404
+            throw error
+          }
+          const md = renderSessionMarkdown({ ...r.meta, id: sid }, r.events || [])
+          res.writeHead(200, {
+            'content-type': 'text/markdown; charset=utf-8',
+            'content-disposition': `attachment; filename="dsh-session-${sid}.md"`,
+            'cache-control': 'no-store',
+          })
+          res.end(md)
+        } catch (e) {
+          json(res, { error: String((e && e.message) || e) }, errorStatus(e))
+        }
+      },
+    }))
+
     disposers.push(ctx.webServer.register({
       kind: 'exact',
       path: '/archived-sessions/sidebar-state',

package/src/markdown.js

@@ -0,0 +1,175 @@
+// Render a session log as human-readable Markdown.
+//
+// Pure: no DOM, no I/O, no dsh imports. Everything it needs arrives as
+// arguments, so the renderer is unit-testable without a running host.
+//
+// Field shapes below were read off real session logs (2026-09-01), not guessed:
+//   user/message       data.content            = [{ type:'text', text } | { type:'image', ... }]
+//   assistant/message  data.message.content    = [{ type:'text'|'reasoning'|'tool-call', ... }]
+//   tool/call          data.{name, arguments}  (arguments is a JSON *string*)
+//   tool/result        data.message.content    = [{ type:'tool-result', content:[{type:'text',text}] }]
+// Note the asymmetry: user text lives at data.content, assistant text one level
+// deeper at data.message.content. Streaming deltas (`assistant/chunk`,
+// `text-chunks`, `reasoning-chunks`) are never rendered — `assistant/message`
+// already carries the final text for each step.
+
+const MAX_TOOL_ARG = 200
+
+function isoTime(value) {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) return null
+  try { return new Date(value).toISOString() } catch { return null }
+}
+
+function yamlString(value) {
+  return `"${String(value).replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\r?\n/g, '\\n')}"`
+}
+
+function blocksOf(value) {
+  return Array.isArray(value) ? value.filter((b) => b && typeof b === 'object') : []
+}
+
+// Join the text blocks of a content array; image blocks are counted separately.
+function textFromBlocks(blocks) {
+  const parts = []
+  for (const block of blocks) {
+    if (block.type === 'text' && typeof block.text === 'string') parts.push(block.text)
+  }
+  return parts.join('\n\n').trim()
+}
+
+function imageCountOf(blocks) {
+  let count = 0
+  for (const block of blocks) if (block.type === 'image') count++
+  return count
+}
+
+function reasoningFromBlocks(blocks) {
+  const parts = []
+  for (const block of blocks) {
+    if (block.type === 'reasoning' && typeof block.text === 'string' && block.text.trim()) parts.push(block.text.trim())
+  }
+  return parts.join('\n\n')
+}
+
+// A short, human-usable summary of one tool call's arguments.
+export function summarizeToolArguments(name, rawArguments) {
+  let parsed = null
+  if (typeof rawArguments === 'string') {
+    try { parsed = JSON.parse(rawArguments) } catch { parsed = null }
+  } else if (rawArguments && typeof rawArguments === 'object') {
+    parsed = rawArguments
+  }
+  if (parsed === null) return typeof rawArguments === 'string' ? rawArguments.slice(0, MAX_TOOL_ARG) : ''
+  if (typeof parsed !== 'object') return String(parsed).slice(0, MAX_TOOL_ARG)
+  const preferred = ['command', 'file_path', 'path', 'query', 'url', 'pattern']
+  for (const key of preferred) {
+    if (typeof parsed[key] === 'string' && parsed[key].trim()) return parsed[key]
+  }
+  const keys = Object.keys(parsed)
+  if (keys.length === 0) return ''
+  const rest = {}
+  for (const key of keys.slice(0, 6)) {
+    const value = parsed[key]
+    rest[key] = typeof value === 'string' ? value : JSON.stringify(value)
+  }
+  return JSON.stringify(rest).slice(0, MAX_TOOL_ARG)
+}
+
+/**
+ * Render one session as Markdown.
+ * @param {object} meta - Session header (`{ id, cwd, createdAt, title? }`).
+ * @param {Array<object>} events - Session events as stored in the log.
+ * @param {object} [options]
+ * @param {boolean} [options.includeReasoning=false] - Emit assistant reasoning blocks.
+ * @param {boolean} [options.includeToolResults=false] - Emit tool results.
+ * @param {number} [options.exportedAt] - Override the export timestamp (tests).
+ * @returns {string} Markdown document.
+ */
+export function renderSessionMarkdown(meta, events, options = {}) {
+  const includeReasoning = options.includeReasoning === true
+  const includeToolResults = options.includeToolResults === true
+  const header = meta && typeof meta === 'object' ? meta : {}
+  const list = Array.isArray(events) ? events : []
+
+  // The last session/title event wins — DSH may retitle a session later on.
+  let title = typeof header.title === 'string' && header.title.trim() ? header.title.trim() : null
+  for (const ev of list) {
+    const data = ev && ev.data
+    if (ev && ev.type === 'session/title' && data && typeof data.title === 'string' && data.title.trim()) {
+      title = data.title.trim()
+    }
+  }
+
+  const front = ['---']
+  if (title) front.push(`title: ${yamlString(title)}`)
+  if (typeof header.id === 'string' && header.id) front.push(`sessionId: ${yamlString(header.id)}`)
+  if (typeof header.cwd === 'string' && header.cwd) front.push(`cwd: ${yamlString(header.cwd)}`)
+  const created = isoTime(header.createdAt)
+  if (created) front.push(`createdAt: ${created}`)
+  const exported = isoTime(options.exportedAt)
+  if (exported) front.push(`exportedAt: ${exported}`)
+  front.push('---')
+
+  const out = [front.join('\n')]
+  if (title) out.push('', `# ${title}`)
+
+  let turn = null
+  for (const ev of list) {
+    if (!ev || typeof ev !== 'object') continue
+    const data = ev.data && typeof ev.data === 'object' ? ev.data : {}
+    const type = ev.type
+
+    if (type === 'turn/start') {
+      const next = Number.isInteger(data.turn) ? data.turn : null
+      if (next !== null && next !== turn) {
+        turn = next
+        out.push('', `## 第 ${turn} 轮`)
+      }
+      continue
+    }
+
+    if (type === 'user/message') {
+      const blocks = blocksOf(data.content)
+      const text = textFromBlocks(blocks)
+      const images = imageCountOf(blocks)
+      if (!text && images === 0) continue
+      out.push('', '### 用户', '')
+      if (text) out.push(text)
+      for (let i = 0; i < images; i++) out.push('', `![图片 ${i + 1}](attachment)`)
+      continue
+    }
+
+    if (type === 'assistant/message') {
+      const message = data.message && typeof data.message === 'object' ? data.message : {}
+      const blocks = blocksOf(message.content)
+      const text = textFromBlocks(blocks)
+      const reasoning = includeReasoning ? reasoningFromBlocks(blocks) : ''
+      if (!text && !reasoning) continue
+      out.push('', '### 助手', '')
+      if (reasoning) out.push('> 思考：' + reasoning.split('\n').join('\n> '), '')
+      if (text) out.push(text)
+      continue
+    }
+
+    if (type === 'tool/call') {
+      const name = typeof data.name === 'string' && data.name ? data.name : 'tool'
+      const summary = summarizeToolArguments(name, data.arguments)
+      out.push('', `### 工具调用：\`${name}\``, '')
+      out.push(summary ? '```\n' + summary + '\n```' : '（无参数）')
+      continue
+    }
+
+    if (type === 'tool/result' && includeToolResults) {
+      const message = data.message && typeof data.message === 'object' ? data.message : {}
+      const blocks = blocksOf(message.content)
+      let text = ''
+      for (const block of blocks) {
+        if (block.type === 'tool-result') text = textFromBlocks(blocksOf(block.content))
+      }
+      if (text) out.push('', '<details><summary>工具结果</summary>', '', '```\n' + text.slice(0, 2000) + '\n```', '', '</details>')
+    }
+  }
+
+  out.push('')
+  return out.join('\n')
+}

package/src/star-index.js

@@ -0,0 +1,109 @@
+// Durable "starred sessions" index (schema v3).
+//
+// Deliberately mirrors the recycle-bin index in src/index.js: version field,
+// automatic upgrade of older shapes, atomic write (tmp + rename) and a single
+// chained mutation queue so two concurrent requests can never clobber each
+// other. Extracted from the host bundle so it can be unit-tested directly —
+// pass `dir` to point the index at a temp directory.
+import { mkdir, rename, writeFile } from 'node:fs/promises'
+import { readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+// v3 is the first star schema; it starts at 3 so it can never be confused with
+// the recycle bin's v1/v2 documents even if a file is copied between them.
+export const STAR_SCHEMA_VERSION = 3
+
+const DEFAULT_STAR_DIR = join(homedir(), '.dsh', 'sessions-manager')
+
+function isSafeSessionId(value) {
+  return typeof value === 'string' && value.length > 0 && value.length <= 200 && !/[\\/\0]/.test(value) && value !== '.' && value !== '..'
+}
+
+/**
+ * Coerce anything on disk (or nothing at all) into a valid v3 store.
+ * Accepts a bare array of ids (the pre-schema shape) and upgrades it.
+ */
+export function normalizeStarStore(raw) {
+  const legacy = Array.isArray(raw) ? raw : null
+  const source = legacy || (raw && typeof raw === 'object' ? raw : null)
+  const ids = source && Array.isArray(source.starredSessionIds) ? source.starredSessionIds : (legacy || [])
+  const clean = []
+  const seen = new Set()
+  for (const id of ids) {
+    // Strings only: silently coercing a number into an id would let junk into
+    // the index and mask a caller bug.
+    if (!isSafeSessionId(id)) continue
+    if (seen.has(id)) continue
+    seen.add(id)
+    clean.push(id)
+  }
+  return { schemaVersion: STAR_SCHEMA_VERSION, starredSessionIds: clean }
+}
+
+/**
+ * Open the star index.
+ * @param {object} [options]
+ * @param {string} [options.dir] - Directory holding the index (tests inject a temp dir).
+ * @param {string} [options.indexPath] - Full index path, overriding `dir`.
+ */
+export function createStarIndex(options = {}) {
+  const dir = options.dir || process.env.DSH_SESSIONS_MANAGER_STAR_DIR || DEFAULT_STAR_DIR
+  const indexPath = options.indexPath || join(dir, 'star.json')
+  let mutation = Promise.resolve()
+
+  async function read() {
+    try {
+      return normalizeStarStore(JSON.parse(readFileSync(indexPath, 'utf8')))
+    } catch {
+      return normalizeStarStore(null)
+    }
+  }
+
+  async function write(store) {
+    await mkdir(dir, { recursive: true })
+    const tmp = join(dir, `.star-${process.pid}-${Date.now()}.tmp`)
+    await writeFile(tmp, JSON.stringify(normalizeStarStore(store), null, 2), { encoding: 'utf8', mode: 0o600 })
+    await rename(tmp, indexPath)
+  }
+
+  // Serialize read-modify-write cycles: every mutator sees the store as left by
+  // the previous one, and a rejected mutator still keeps the chain alive.
+  function mutate(mutator) {
+    const operation = mutation.then(async () => {
+      const store = await read()
+      const result = await mutator(store)
+      await write(store)
+      return result
+    })
+    mutation = operation.catch(() => {})
+    return operation
+  }
+
+  /**
+   * Star or unstar sessions.
+   * @param {string[]} ids - Session ids to change.
+   * @param {boolean} starred - true to star, false to unstar.
+   * @returns {Promise<string[]>} The full starred set after the change.
+   */
+  function setStarred(ids, starred) {
+    const wanted = (Array.isArray(ids) ? ids : []).filter(isSafeSessionId).map(String)
+    return mutate((store) => {
+      const set = new Set(store.starredSessionIds)
+      for (const id of wanted) {
+        if (starred) set.add(id)
+        else set.delete(id)
+      }
+      store.starredSessionIds = [...set]
+      return store.starredSessionIds
+    })
+  }
+
+  // Drop ids once their session is gone (purged / deleted), otherwise the index
+  // would grow forever with ids that can never be listed again.
+  function removeIds(ids) {
+    return setStarred(ids, false)
+  }
+
+  return { read, write, mutate, setStarred, removeIds, indexPath, dir }
+}