@yolk_vat-y/dsh-project-memory 0.5.3 → 0.5.5

package/src/auto-inject.js

@@ -13,9 +13,18 @@ import { insightMatchText } from './similarity.js'
 import { normalizedTokenOverlap } from './similarity.js'
 import { cfgInsight, GlobalStore, defaultGlobalFile } from './insight-store.js'
 import { projectTags } from './project-profile.js'
+import { rankEntriesMergedScored } from './util/search.js'
+import { insightToEntry } from './recall.js'
+import { buildReadinessContext, hintQueryText, matchTrigger, relativeHits } from './readiness.js'
 
 export const INJECT_MARK = '[Memory Inject]'
 
+/**
+ * 注入正文的最小可用长度：预算塞不下这么多就宁可不注入（记 dropped）。
+ * 与其输出 `- [ins_xxx] procedure ` 这种 stub，不如保持沉默——stub 只消耗 token 不传递信息。
+ */
+const MIN_BODY_CHARS = { trigger: 48, hint: 120 }
+
 /** 注入引擎配置：insight 默认之上叠加 autoContext 预算/门控参数。 */
 export function cfgEngine(config) {
   const c = (config && config.autoContext) || {}
@@ -24,11 +33,25 @@ export function cfgEngine(config) {
     ...base,
     maxTokens: typeof c.maxTokens === 'number' ? c.maxTokens : 400,
     entryMaxInsights: typeof c.entryMaxInsights === 'number' ? c.entryMaxInsights : 6,
-    relevanceMin: typeof c.relevanceMin === 'number' ? c.relevanceMin : 0.25,
+    // 提示通道的相对阈值（层内最高分的比例）：尺度无关，取代旧的"绝对 overlap"常量。
+    // 旧判据 normalizedTokenOverlap = |交集| / max(|A|,|B|) 对长消息必然趋零（实测 0.014–0.057）。
+    signalMinRatio: typeof c.signalMinRatio === 'number' ? c.signalMinRatio : 0.5,
+    // 兼容闸门：显式配置 relevanceMin 时仍走旧的绝对 overlap 判据；不配置则为 null（走相对阈值）。
+    relevanceMin: typeof c.relevanceMin === 'number' ? c.relevanceMin : null,
     // resident 任务卡最多显示几个"编辑中"文件（纯写权重，最近写优先）
     editedMax: typeof c.editedMax === 'number' ? c.editedMax : 3,
     // 模型自己写/维护任务清单后、尚无新人类消息时，不把任务卡再回声给模型（省 token）
     skipEchoSelfTodo: c.skipEchoSelfTodo !== false,
+    // 预算审计日志级别（stderr）。默认 off：预算挤掉低优先级条目是正常降级，不是故障，
+    // 而终端是用户可见面——默认打印会让一次启动刷出多行，代价远大于那点可观测性收益。
+    //   off  : 永不打印（默认）
+    //   once : 每个会话最多一行（首次出现预算丢弃时），够定位又不刷屏
+    //   all  : 丢弃组合每变化一次打一行（作者排查用）
+    budgetLog: ['off', 'once', 'all'].includes(c.budgetLog) ? c.budgetLog : 'off',
+    // 同一条 insight 在本会话里重复注入的冷却（单位：pre-step 步数）。
+    // 0（默认）= 内容没变就不再注入：注入消息会留在会话历史里（宿主不压缩历史），
+    // 整块重发同一条 1200 字 procedure 只是重复占位。>0 用于历史可能被外部裁剪的场景。
+    reinjectItemsAfter: typeof c.reinjectItemsAfter === 'number' && c.reinjectItemsAfter >= 0 ? c.reinjectItemsAfter : 0,
   }
 }
 
@@ -40,16 +63,20 @@ function textOf(message) {
     .join('\n')
 }
 
-function lastUserText(messages) {
+export function lastUserText(messages) {
   if (!Array.isArray(messages)) return ''
+  let fallback = ''
   for (let i = messages.length - 1; i >= 0; i--) {
     const m = messages[i]
-    if (m && m.role === 'user') {
-      const t = textOf(m)
-      if (t.trim()) return t.trim()
-    }
+    if (!m || m.role !== 'user') continue
+    const t = textOf(m)
+    if (!t.trim()) continue
+    // 真人消息优先：本插件注入的块也是 role=user，若按"最后一条 user"取，
+    // 上一步的注入块会变成这一步的就绪查询（自激：拿自己注入的内容再检索一遍）。
+    if (m.source && m.source.kind === 'user') return t.trim()
+    if (!fallback) fallback = t.trim() // 无 source 的消息（老宿主 / 测试）兜底
   }
-  return ''
+  return fallback
 }
 
 function fingerprint(text) {
@@ -103,65 +130,144 @@ export function buildEntryContent(task, cfg, { withEdited = true } = {}) {
   return parts.join('\n')
 }
 
+/** 候选池：project + global + 绑定任务（同一 id 只取一次；归档/草稿不进注入）。 */
+function insightCandidates(store, globalStore, task) {
+  const out = []
+  const seen = new Set()
+  const push = (it) => {
+    if (!it || it.archived || it.draft) return
+    const key = it.id || `${it.kind}:${it.title}`
+    if (seen.has(key)) return
+    seen.add(key)
+    out.push(it)
+  }
+  for (const it of (store ? store.insightItems() : []) || []) push(it)
+  for (const it of (globalStore ? globalStore.items() : []) || []) push(it)
+  for (const it of (task && task.insights) || []) push(it)
+  return out
+}
+
+/** 一条 insight 的注入正文：procedure 给全步骤，其余给标题 + 结论。 */
+function insightBody(it) {
+  return it.kind === 'procedure' && Array.isArray(it.steps)
+    ? `【${it.title}】\n${it.steps.map((s, i) => `${i + 1}. ${s}`).join('\n')}`
+    : `- [${it.id}] ${it.title}${it.fix || it.solution || it.choice ? ` — ${it.fix || it.solution || it.choice}` : ''}`
+}
+
+/** 条目级去重键：注入正文的指纹（正文变了才允许再注入一次，见 cfg.reinjectItemsAfter）。 */
+export function insightItemHash(it) {
+  return createHash('sha256').update(insightBody(it)).digest('hex').slice(0, 12)
+}
+
+/** 把正文塞进剩余预算：放不下就截断；连"有用前缀"都留不下就返回 null（由调用方记 dropped）。 */
+export function fitBody(body, remaining, min = MIN_BODY_CHARS.hint) {
+  if (remaining <= min) return null
+  if (body.length <= remaining) return body
+  return `${body.slice(0, remaining - 1)}…`
+}
+
 /**
  * 构建注入内容（不写盘、无副作用）。
- * @param {object} opts { query, task, store, globalStore, projectTagsList, cfg }
- * @returns {{ text: string, labels: string[] }}
+ *
+ * 交付契约：**authored trigger（所有 kind）= 确定性全文注入，优先级 1；统计信号 = 截断提示，
+ * 优先级 2**。预算排程为：常驻任务卡 → trigger 命中 → 提示。每一步都记 `reasons`（为什么注入）
+ * 与 `dropped`（为什么没注入），让"注入/未注入"可审计——而不是只有静默的门槛。
+ * @param {object} opts { query, readiness, task, store, globalStore, projectTagsList, cfg, skipItem? }
+ * @param {(it: object) => boolean} [opts.skipItem] 条目级去重：返回 true 的条目直接退出排程
+ *   （本会话已注入过且正文未变）。在排程前过滤，省下的预算留给新条目。
+ * @returns {{ text: string, labels: string[], reasons: object[], dropped: object[] }}
  */
 export function buildInjection(opts) {
   const { query, task, globalStore, cfg } = opts
   const store = opts.store || null
   const tags = opts.projectTagsList || []
+  const ctx = buildReadinessContext(opts.readiness || { humanText: query || '' })
   const labels = []
+  const reasons = []
+  const dropped = []
   const parts = []
-  let budgetChars = (cfg.maxTokens || 400) * 3
-
-  // B) relevance：procedure（trigger 命中）全步骤优先
-  const gItems = globalStore ? globalStore.items() : []
-  const matched = []
-  for (const it of gItems) {
-    if (!it || it.archived || it.kind !== 'procedure' || !it.trigger) continue
-    const tr = it.trigger
-    const kwHit = (tr.keywords || []).some((k) => query.toLowerCase().includes(String(k).toLowerCase()))
-    const symHit = (tr.symbols || []).some((s) => query.includes(s))
-    if (!kwHit && !symHit) continue
-    if (Array.isArray(tr.scope) && tr.scope.length && tags.length) {
-      if (!tr.scope.some((s) => tags.includes(s))) continue // 画像过滤
-    }
-    matched.push({ it, score: 1 })
-  }
-  // procedure 之外的相关 insights（project + global 非草稿非归档），lexical top-k
-  const cands = [...(store ? store.insightItems() : []), ...gItems]
+  const budgetChars = (cfg.maxTokens || 400) * 3
+
+  const skipItem = typeof opts.skipItem === 'function' ? opts.skipItem : null
+  const cands = insightCandidates(store, globalStore, task).filter((it) => !(skipItem && skipItem(it)))
+
+  // 通道 1：authored trigger —— 确定性、全文、优先级 1。procedure 先于其它 kind（步骤更完整）。
+  const triggered = []
   for (const it of cands) {
-    if (!it || it.archived || it.draft) continue
-    if (it.kind === 'procedure') continue // procedure 只经 trigger 通道注入，避免绕过 scope 过滤
-    const score = normalizedTokenOverlap(query, insightMatchText(it))
-    if (score >= (cfg.relevanceMin || 0.25)) matched.push({ it, score })
+    const why = matchTrigger(it.trigger, ctx)
+    if (!why) continue
+    const scope = it.trigger?.scope
+    if (Array.isArray(scope) && scope.length && tags.length && !scope.some((s) => tags.includes(s))) continue
+    triggered.push({ it, why })
   }
-  matched.sort((a, b) => b.score - a.score)
-  const seen = new Set()
-  for (const { it } of matched) {
-    if (seen.has(it.id)) continue
-    seen.add(it.id)
-    const label = it.kind === 'procedure' ? 'procedure' : 'insight'
-    const body =
-      it.kind === 'procedure' && Array.isArray(it.steps)
-        ? `【${it.title}】\n${it.steps.map((s, i) => `${i + 1}. ${s}`).join('\n')}`
-        : `- [${it.id}] ${it.title}${it.fix || it.solution || it.choice ? ` — ${it.fix || it.solution || it.choice}` : ''}`
-    parts.push(body)
-    labels.push(label)
-    if (parts.join('\n').length > budgetChars) break
+  triggered.sort(
+    (a, b) => (a.it.kind === 'procedure' ? 0 : 1) - (b.it.kind === 'procedure' ? 0 : 1)
+      || String(a.it.id).localeCompare(String(b.it.id)),
+  )
+
+  // 通道 2：统计信号 —— 提示态、优先级 2，判据是层内相对阈值（尺度无关）。
+  // procedure 只走 trigger 通道：否则会被统计通道绕过 trigger.scope 的画像过滤。
+  const consumed = new Set(triggered.map((t) => t.it.id))
+  const hintCands = cands.filter((it) => !consumed.has(it.id) && it.kind !== 'procedure')
+  const hints = []
+  if (hintCands.length) {
+    if (typeof cfg.relevanceMin === 'number') {
+      // 兼容：显式 relevanceMin → 旧的绝对 overlap 判据（老 profile 行为不变）
+      for (const it of hintCands) {
+        const score = normalizedTokenOverlap(ctx.humanText || query || '', insightMatchText(it))
+        if (score >= cfg.relevanceMin) hints.push({ it, score, why: `overlap:${score.toFixed(3)}` })
+      }
+      hints.sort((a, b) => b.score - a.score)
+    } else {
+      const byId = new Map(hintCands.map((it) => [it.id, it]))
+      // 提示查询先剔除 1–2 字符的拉丁缩写（PR/CI/OS）：它们一个巧合命中就能当上该层最高分。
+      const scored = rankEntriesMergedScored(
+        hintCands.map(insightToEntry),
+        [hintQueryText(ctx.humanText), hintQueryText(ctx.actionText)].filter(Boolean),
+        hintCands.length,
+      )
+      for (const r of relativeHits(scored, { ratioMin: cfg.signalMinRatio })) {
+        const it = byId.get(r.entry.insightId)
+        if (it) hints.push({ it, score: r.score, why: `relative:${(r.score / (scored[0].score || 1)).toFixed(2)}` })
+      }
+    }
   }
+
   // 常驻块文本。去重指纹只看稳定内容（任务标题/步骤/insights + 相关 insights）：
   // “编辑中”随每次写文件变化，若参与指纹会导致每写一个文件就重发整块（噪音 + token 浪费）。
   const echo = shouldEchoTaskCard(task, cfg)
   const entry = echo ? buildEntryContent(task, cfg) : ''
   const entryStable = echo ? buildEntryContent(task, cfg, { withEdited: false }) : ''
+  let used = entry.length
+
+  for (const { it, why } of triggered) {
+    const body = fitBody(insightBody(it), budgetChars - used, MIN_BODY_CHARS.trigger)
+    if (body === null) {
+      dropped.push({ id: it.id, channel: 'trigger', reason: 'budget' })
+      continue
+    }
+    used += body.length + 1
+    parts.push(body)
+    labels.push(it.kind === 'procedure' ? 'procedure' : it.kind)
+    reasons.push({ id: it.id, channel: 'trigger', why, hash: insightItemHash(it) })
+  }
+  for (const { it, why } of hints) {
+    const body = fitBody(insightBody(it), budgetChars - used, MIN_BODY_CHARS.hint)
+    if (body === null) {
+      dropped.push({ id: it.id, channel: 'hint', reason: 'budget' })
+      continue
+    }
+    used += body.length + 1
+    parts.push(body)
+    labels.push('hint')
+    reasons.push({ id: it.id, channel: 'hint', why, hash: insightItemHash(it) })
+  }
+
   const total = [entry, ...parts].filter(Boolean)
-  if (!total.length) return { text: '', labels: [] }
-  const clamp = (t) => (t.length > budgetChars ? t.slice(0, budgetChars) + '\n…(截断)' : t)
+  if (!total.length) return { text: '', labels, reasons, dropped }
+  const clamp = (t) => (t.length > budgetChars ? `${t.slice(0, budgetChars)}\n…(截断)` : t)
   const dedupeText = clamp([entryStable, ...parts].filter(Boolean).join('\n'))
-  return { text: clamp(total.join('\n')), labels, dedupeText }
+  return { text: clamp(total.join('\n')), labels, reasons, dropped, dedupeText }
 }
 
 /** 注册 agent/pre-step 监听，向每步请求的 enter 决策追加记忆消息（默认开）。
@@ -175,6 +281,45 @@ export function installAutoInject(ctx, config) {
   // 每个会话一份“上次注入指纹”。用单个变量会让并发会话互相抑制注入。
   const lastFpBySession = new Map()
   const LAST_FP_MAX = 200
+  // 每个会话一份"上次预算丢弃指纹"：预算把条目挤出去时必须留痕一次，而不是静默（degraded 可见性）。
+  const lastDroppedBySession = new Map()
+  // 条目级去重记忆：sessionId → Map(insightId → { hash, step })。注入的消息留在会话历史里
+  // （宿主只追加、不压缩），所以"整块指纹变了"不等于"内容都是新的"——同一份 procedure 会因为
+  // 滑动工具窗口、任务卡更新、预算截断边界变化被整块重发（实测 66 步注入 20 次，其中同一份
+  // 1732 字 procedure 重发 3 次、另一份 1008 字的 6 次）。这里按条目记账，正文没变就不再排程。
+  const injectedBySession = new Map()
+  const INJECTED_ITEMS_MAX = 600
+  // 会话步数：为 reinjectItemsAfter 提供时间轴（>0 时才用得上）。
+  const stepBySession = new Map()
+  // 反应窗口：本会话最近观察到的 tool/call（参数里有 git commit / npm publish / 改动的路径）。
+  // 宿主没有"工具执行前拦截"钩子，所以这是 pre-step 之外唯一能拿到的动作事实。
+  const observedBySession = new Map()
+  const OBSERVED_MAX = 8
+  const OBSERVED_SESSIONS = 200
+  ctx.on('session/event', (session, event) => {
+    try {
+      if (!event || event.type !== 'tool/call') return
+      const sid = session && session.id
+      if (!sid) return
+      const data = event.data || {}
+      const rec = observedBySession.get(sid) || []
+      rec.push({ name: String(data.name || ''), arguments: String(data.arguments || '') })
+      while (rec.length > OBSERVED_MAX) rec.shift()
+      observedBySession.set(sid, rec)
+      while (observedBySession.size > OBSERVED_SESSIONS) {
+        observedBySession.delete(observedBySession.keys().next().value)
+      }
+    } catch {
+      // 观察失败绝不影响宿主请求
+    }
+  })
+  if (typeof ctx.effect === 'function') {
+    ctx.effect(() => () => {
+      observedBySession.clear()
+      injectedBySession.clear()
+      stepBySession.clear()
+    })
+  }
   ctx.on('agent/pre-step', async (payload, next) => {
     // 宿主契约是 waterfall(payload, next)，next 一定存在；但一旦宿主版本漂移、或事件被当
     // 普通事件调用，next 缺失会让本监听器 reject（历史事故正是 `next is not a function`）。
@@ -195,19 +340,77 @@ export function installAutoInject(ctx, config) {
       const globalStore = new GlobalStore(cfgInsight(config).globalFile || defaultGlobalFile()).load()
       const boundTaskId = store.getBoundTaskId(sessionId) ? store.getBoundTaskId(sessionId) : null
       const task = boundTaskId ? store.getTask(boundTaskId) : null
-      const built = buildInjection({ query: query || '', task, store, globalStore, projectTagsList: projectTags(root), cfg })
+      // 两个窗口合并进同一个就绪上下文：人类消息（先发）+ 已观察动作（反应）。
+      const observed = observedBySession.get(sessionId) || []
+      const readiness = buildReadinessContext({
+        humanText: query || '',
+        actionText: observed.map((c) => `${c.name} ${c.arguments}`).join('\n'),
+      })
+      // 条目级去重：本会话已注入过、且正文未变的条目不再参与排程（cfg.reinjectItemsAfter=0 时永久，
+      // >0 时走冷却步数，用于历史可能被外部裁剪的场景）。正文变了（编辑过 insight）立刻允许重发。
+      const stepNo = (stepBySession.get(sessionId) || 0) + 1
+      stepBySession.set(sessionId, stepNo)
+      while (stepBySession.size > LAST_FP_MAX) stepBySession.delete(stepBySession.keys().next().value)
+      const seen = injectedBySession.get(sessionId) || new Map()
+      injectedBySession.set(sessionId, seen)
+      while (injectedBySession.size > LAST_FP_MAX) injectedBySession.delete(injectedBySession.keys().next().value)
+      const cooldown = cfg.reinjectItemsAfter || 0
+      const skipItem = cooldown === 0
+        ? (it) => {
+            const rec = seen.get(it.id)
+            return Boolean(rec) && rec.hash === insightItemHash(it)
+          }
+        : (it) => {
+            const rec = seen.get(it.id)
+            return Boolean(rec) && rec.hash === insightItemHash(it) && stepNo - rec.step < cooldown
+          }
+      const built = buildInjection({ query: query || '', readiness, task, store, globalStore, projectTagsList: projectTags(root), cfg, skipItem })
       const fp = fingerprint(built.dedupeText ?? built.text)
-      if (built.text && fp !== lastFpBySession.get(sessionId)) {
+      const shouldInject = Boolean(built.text) && fp !== lastFpBySession.get(sessionId)
+      let injectMessage = null
+      if (shouldInject) {
         // 以宿主 createUserMessage 构造的完整 user 消息追加（带 id/source，plan-mode narration 同款）。
         // 裸 {role,content} 消息缺 source 会让宿主逐条读 message.source.kind 时崩溃。
         lastFpBySession.set(sessionId, fp)
         if (lastFpBySession.size > LAST_FP_MAX) lastFpBySession.delete(lastFpBySession.keys().next().value)
-        const injectMessage = createUserMessage({
+        // 只记真的进了上下文的那几条：dropped 的没被看到，不能记账（否则以后永远不再注入）。
+        for (const r of built.reasons) {
+          if (r && r.id && r.hash) seen.set(r.id, { hash: r.hash, step: stepNo })
+        }
+        while (seen.size > INJECTED_ITEMS_MAX) seen.delete(seen.keys().next().value)
+        injectMessage = createUserMessage({
           content: [{ type: 'text', text: `\n\n${INJECT_MARK} auto-context\n${built.text}` }],
-          source: { kind: 'plugin', plugin: 'dsh-project-memory', form: 'notice', summary: `记忆注入 ${built.text.length} 字符` },
+          // 这一块是「同一生产者后续快照会取代的当前状态」，不是一次性通知。
+          // 宿主 ContextFormed 是判别联合：snapshot 必须带 sections（notice 才需要 summary）。
+          // 通道不变（仍走 agent/pre-step 追加 user 消息），只修语义。
+          source: {
+            kind: 'plugin',
+            plugin: 'dsh-project-memory',
+            form: 'snapshot',
+            sections: [{ name: 'project-memory', text: built.text }],
+          },
         })
-        return { ...decision, messages: [...decision.messages, injectMessage] }
       }
+      // 未注入 ≠ 无事发生：因预算被挤掉的条目按 cfg.budgetLog 留痕（默认 off，见 cfgEngine）。
+      // 留痕仍然记账（去重 + 上限），只是默认不外泄到用户的终端。
+      if (built.dropped && built.dropped.length && cfg.budgetLog !== 'off') {
+        const sig = built.dropped.map((d) => `${d.id}:${d.reason}`).join(',')
+        if (lastDroppedBySession.get(sessionId) !== sig) {
+          const seenBefore = lastDroppedBySession.has(sessionId)
+          lastDroppedBySession.set(sessionId, sig)
+          while (lastDroppedBySession.size > LAST_FP_MAX) {
+            lastDroppedBySession.delete(lastDroppedBySession.keys().next().value)
+          }
+          // once：只有本会话第一次丢弃出声，之后继续记账但保持安静。
+          if (cfg.budgetLog === 'all' || !seenBefore) {
+            console.error(
+              `[dsh-project-memory] auto-inject degraded: ${built.dropped.length} insight(s) kept out by budget — `
+              + built.dropped.map((d) => `${d.id}(${d.reason})`).join(', '),
+            )
+          }
+        }
+      }
+      if (injectMessage) return { ...decision, messages: [...decision.messages, injectMessage] }
     } catch (err) {
       console.error(`[dsh-project-memory] auto-inject skipped: ${err?.message || err}`)
     }

package/src/client/MemoryView.tsx

@@ -75,12 +75,14 @@ export function MemoryView({
   sessionId,
   scope,
   boundTaskId,
+  showHints,
   t,
 }: {
   ctx: any
   sessionId: string | null
   scope: InsightScope
   boundTaskId: string | null
+  showHints: boolean
   t: any
 }) {
   const [payload, setPayload] = useState<ListPayload | null>(null)
@@ -258,7 +260,7 @@ export function MemoryView({
           {scope !== 'task' && !showNew && (
             <Button variant="outline" size="sm" disabled={busy} onClick={() => { setShowNew(true); setEditingId(null); setError(null) }}>{t('mem.new')}</Button>
           )}
-          <Button variant="outline" size="sm" onClick={() => void refresh(true)} disabled={loading} title={t('panel.refresh')} aria-label={t('panel.refresh')}>
+          <Button variant="outline" size="sm" onClick={() => void refresh(true)} disabled={loading} title={showHints ? t('panel.refresh') : undefined} aria-label={t('panel.refresh')}>
             ↻
           </Button>
         </span>
@@ -329,7 +331,7 @@ export function MemoryView({
                 {scope === 'project' && (
                   <>
                     <Button variant="outline" size="sm" disabled={busy} onClick={() => void act('promote', row.id)}>{t('mem.promote')}</Button>
-                    <Button variant="outline" size="sm" disabled={busy || !canDemoteToTask} title={!canDemoteToTask ? t('mem.needs-bound') : undefined} onClick={() => void act('demote', row.id)}>{t('mem.demote')}</Button>
+                    <Button variant="outline" size="sm" disabled={busy || !canDemoteToTask} title={showHints && !canDemoteToTask ? t('mem.needs-bound') : undefined} onClick={() => void act('demote', row.id)}>{t('mem.demote')}</Button>
                   </>
                 )}
                 {scope === 'global' && (

package/src/client/TaskComponents.tsx

@@ -117,13 +117,14 @@ function InlineEditor({ value, className, maxRows = 8, onValueChange, onCommit,
 interface MiniBarProps {
   label: string
   hint: string
+  showHints: boolean
   position: { x: number; y: number }
   theme: string
   onMove: (pos: { x: number; y: number }) => void
   open: () => void
 }
 
-export function MiniBar({ label, hint, position, theme, onMove, open }: MiniBarProps) {
+export function MiniBar({ label, hint, showHints, position, theme, onMove, open }: MiniBarProps) {
   const barRef = useRef<HTMLDivElement>(null)
   const down = useRef<{ dx: number; dy: number; sx: number; sy: number; moved: boolean } | null>(null)
 
@@ -163,7 +164,7 @@ export function MiniBar({ label, hint, position, theme, onMove, open }: MiniBarP
       data-theme={theme === 'native' ? undefined : theme}
       onMouseDown={onMouseDown}
       role="button"
-      title={hint}
+      title={showHints ? hint : undefined}
       aria-label={hint}
     >
       <IconFolderOpenOutline16 className={css.miniIcon} />
@@ -293,7 +294,7 @@ export function TaskCard({
             <span
               data-card-title
               className={`${css.cardTitle}${isBound ? ` ${css.cardTitleEditable}` : ''}`}
-              title={isBound ? t('task.title-edit') : undefined}
+              title={isBound && showHints ? t('task.title-edit') : undefined}
               onDoubleClick={(e) => {
                 e.preventDefault()
                 e.stopPropagation()
@@ -350,7 +351,7 @@ export function TaskCard({
                             className={css.stepToggle}
                             disabled={syncing}
                             onClick={(e) => { e.stopPropagation(); onCycleStatus(i) }}
-                            title={`${t('step.completed')}/${t('step.in-progress')}/${t('step.pending')}`}
+                            title={showHints ? `${t('step.completed')}/${t('step.in-progress')}/${t('step.pending')}` : undefined}
                           >
                             <StepIcon status={step.status} />
                           </button>
@@ -423,7 +424,7 @@ export function TaskCard({
                     <button
                       className={css.fileRow}
                       onClick={() => navigator.clipboard?.writeText(file.path)}
-                      title={`${t('file.copy')}: ${file.path}${file.line ? `:${file.line}` : ''}`}
+                      title={showHints ? `${t('file.copy')}: ${file.path}${file.line ? `:${file.line}` : ''}` : undefined}
                     >
                       <span className={css.fileDot} />
                       <span className={css.filePath}>{file.path}</span>
@@ -476,7 +477,7 @@ export function TaskCard({
               {t('task.switch')}
             </Button>
             {isBound && (
-              <Button variant="outline" size="sm" disabled={syncing} onClick={onUnbind} title={t('task.unbind')}>
+              <Button variant="outline" size="sm" disabled={syncing} onClick={onUnbind} title={showHints ? t('task.unbind') : undefined}>
                 {t('task.unbind')}
               </Button>
             )}

package/src/client/TaskPanel.module.css

@@ -83,6 +83,13 @@
   gap: 2px;
   margin-left: auto;
 }
+/* 提示信息开关处于「已隐藏」状态：图标变暗，给出无需悬停的可见反馈 */
+.hintsOff {
+  opacity: 0.45;
+}
+.hintsOff:hover {
+  opacity: 0.75;
+}
 .counts {
   font-size: 11px;
   line-height: 16px;

package/src/client/TaskPanel.tsx

@@ -75,7 +75,8 @@ function TaskPanelView({ ctx }: { ctx: any }) {
   const [syncing, setSyncing] = useState(false)
   const [syncedAt, setSyncedAt] = useState(0)
   const [syncError, setSyncError] = useState<string | null>(null)
-  const [showHints, setShowHints] = useState(true)
+  // 提示信息开关落在 UI store（持久化）：关掉后面板内所有悬停 title 气泡都不再弹出。
+  const showHints = ui.showHints
   const [view, setView] = useState<PanelView>('task')
   const cycleView = () => {
     const i = VIEW_CYCLE.indexOf(view)
@@ -288,6 +289,7 @@ function TaskPanelView({ ctx }: { ctx: any }) {
       <MiniBar
         label={label}
         hint={t('minibar.click-expand')}
+        showHints={showHints}
         position={ui.panelPosition}
         theme={style}
         onMove={uiActions.setPanelPosition}
@@ -308,7 +310,7 @@ function TaskPanelView({ ctx }: { ctx: any }) {
       style={{ left: ui.panelPosition.x, top: ui.panelPosition.y }}
       data-theme={style === 'native' ? undefined : style}
     >
-      <div className={css.dragHandle} onMouseDown={handleDragStart} title={t('task.drag')}>
+      <div className={css.dragHandle} onMouseDown={handleDragStart} title={showHints ? t('task.drag') : undefined}>
         <div className={css.handleGrip} />
       </div>
       <header className={css.header}>
@@ -317,7 +319,7 @@ function TaskPanelView({ ctx }: { ctx: any }) {
             type="button"
             className={css.headerIconBtn}
             onClick={cycleTheme}
-            title={styleLabel}
+            title={showHints ? styleLabel : undefined}
             aria-label={styleLabel}
           >
             <IconFolderOpenOutline16 className={css.headerIcon} />
@@ -330,7 +332,7 @@ function TaskPanelView({ ctx }: { ctx: any }) {
             size="sm"
             onClick={cycleView}
             aria-label={t('view.cycle')}
-            title={`${t('view.cycle')}（${view} → ${VIEW_CYCLE[(VIEW_CYCLE.indexOf(view) + 1) % VIEW_CYCLE.length]}）`}
+            title={showHints ? `${t('view.cycle')}（${view} → ${VIEW_CYCLE[(VIEW_CYCLE.indexOf(view) + 1) % VIEW_CYCLE.length]}）` : undefined}
           >
             {/* lucide notebook-tabs（视图循环图标） */}
             <svg
@@ -365,7 +367,9 @@ function TaskPanelView({ ctx }: { ctx: any }) {
           <Button
             variant="ghost"
             size="sm"
-            onClick={() => setShowHints(!showHints)}
+            className={showHints ? undefined : css.hintsOff}
+            onClick={() => uiActions.toggleHints()}
+            aria-pressed={!showHints}
             aria-label={showHints ? t('panel.hints-off') : t('panel.hints-on')}
             title={showHints ? t('panel.hints-off') : t('panel.hints-on')}
           >
@@ -376,7 +380,7 @@ function TaskPanelView({ ctx }: { ctx: any }) {
             size="sm"
             onClick={() => uiActions.minimize()}
             aria-label={t('panel.minimize')}
-            title={t('panel.minimize')}
+            title={showHints ? t('panel.minimize') : undefined}
           >
             <IconChevronDownOutline14 />
           </Button>
@@ -385,7 +389,7 @@ function TaskPanelView({ ctx }: { ctx: any }) {
             size="sm"
             onClick={() => uiActions.close()}
             aria-label={t('panel.close')}
-            title={t('panel.close')}
+            title={showHints ? t('panel.close') : undefined}
           >
             <IconCloseOutline16 />
           </Button>
@@ -396,7 +400,7 @@ function TaskPanelView({ ctx }: { ctx: any }) {
       {syncError && <div className={css.notice}>{t('panel.sync-failed')}: {syncError}</div>}
 
       {view !== 'task' ? (
-        <MemoryView ctx={ctx} sessionId={sessionId} scope={view as InsightScope} boundTaskId={data.boundTaskId} t={t} />
+        <MemoryView ctx={ctx} sessionId={sessionId} scope={view as InsightScope} boundTaskId={data.boundTaskId} showHints={showHints} t={t} />
       ) : activeTasks.length === 0 ? (
         <div className={css.emptyState}>
           <p className={css.emptyTitle}>{t('panel.empty')}</p>

package/src/client/task-ui-store.ts

@@ -1,5 +1,5 @@
 /**
- * Task UI Store — 仅管本地 UI 状态（closed、minimized、position、expandedIds、theme）
+ * Task UI Store — 仅管本地 UI 状态（closed、minimized、position、expandedIds、theme、showHints）
  * - 持久化到 localStorage（key: dsh-pm-task-panel-ui）
  * - 不跨标签页同步（每个标签页独立）
  * - 启动/刷新强制 closed: true，面板默认不显示
@@ -14,6 +14,8 @@ interface TaskUIState {
   minimized: boolean
   closed: boolean
   theme: string
+  /** 是否显示悬停提示信息（title 气泡）；false 时面板内所有功能提示都不弹出。 */
+  showHints: boolean
 }
 
 function defaultPosition(): { x: number; y: number } {
@@ -40,6 +42,7 @@ function getDefaultUIState(): TaskUIState {
           minimized: parsed.minimized !== false,
           closed: true,
           theme: typeof parsed.theme === 'string' ? parsed.theme : 'native',
+          showHints: parsed.showHints !== false,
         }
       }
     } catch { /* corrupt state — fall through to defaults */ }
@@ -50,6 +53,7 @@ function getDefaultUIState(): TaskUIState {
     minimized: true,
     closed: true,
     theme: 'native',
+    showHints: true,
   }
 }
 
@@ -103,6 +107,12 @@ export const taskUIStore = {
     setTheme(theme: string): void {
       setUIState({ ...uiState, theme })
     },
+    toggleHints(): void {
+      setUIState({ ...uiState, showHints: !uiState.showHints })
+    },
+    setShowHints(showHints: boolean): void {
+      setUIState({ ...uiState, showHints })
+    },
     reset(): void {
       setUIState(getDefaultUIState())
     },

package/src/commands/task-actions.js

@@ -7,6 +7,7 @@ import { ProjectMemoryStore } from '../store.js'
 import { projectRootFor, adoptStepsToSession, shouldAdoptToHost } from '../setup/taskbridge.js'
 import { renderTaskSnapshot, buildTaskPayload } from './tasks.js'
 import { fireReflect } from '../reflection-pipeline.js'
+import { resolveRoute } from '../llm-route.js'
 
 const VERBS = { switch: 'switch', archive: 'archive' }
 
@@ -138,7 +139,7 @@ export function taskCommandDefinition(config, ctx) {
           store.save()
           // 反思钩子：切走旧任务异步收割（默认关）
           if (prevBound && prevBound !== task.id) {
-            fireReflect(config, { llm: ctx?.llm }, root, prevBound, 'switch-away')
+            fireReflect(config, { llm: ctx?.llm }, root, prevBound, 'switch-away', resolveRoute(session ? { agent: { session } } : undefined, config))
           }
           // 反向接管：切换成功后把任务步骤推成宿主 todo/write（dsh 清单跟随）
           if (shouldAdoptToHost(config)) {
@@ -156,7 +157,7 @@ export function taskCommandDefinition(config, ctx) {
           task.updatedAt = new Date().toISOString()
           store.save()
           // 反思钩子：归档即收割（默认关）
-          fireReflect(config, { llm: ctx?.llm }, root, taskId, 'archive')
+          fireReflect(config, { llm: ctx?.llm }, root, taskId, 'archive', resolveRoute(session ? { agent: { session } } : undefined, config))
           const note = `已归档: ${describeTask(task)}（select_task 可恢复）`
           return withTaskSnapshot(config, cwd, sid, store, note)
         }