@yolk_vat-y/dsh-project-memory 0.4.4 → 0.5.1

package/src/project-profile.js

@@ -0,0 +1,78 @@
+// PR 2 项目技术栈画像（tags）：解析 package.json / go.mod / Cargo.toml → 内存缓存
+// 用途：global procedure 的 trigger.scope 过滤（与画像 tags 取交集为空则跳过）
+import { readFileSync, statSync } from 'node:fs'
+import path from 'node:path'
+
+const cache = new Map() // root -> { tags: string[], mtimeMs: number }
+
+function tryRead(file) {
+  try {
+    return readFileSync(file, 'utf8')
+  } catch {
+    return null
+  }
+}
+
+function depsOf(manifest, fields) {
+  const tags = new Set()
+  for (const f of fields) {
+    const deps = manifest && manifest[f]
+    if (deps && typeof deps === 'object') {
+      for (const name of Object.keys(deps)) {
+        tags.add(name.toLowerCase())
+        if (name.startsWith('@')) tags.add(name.split('/')[1].toLowerCase())
+      }
+    }
+  }
+  return tags
+}
+
+/**
+ * 解析项目技术栈 tags。带 mtime 缓存；任何解析失败返回空集（不抛）。
+ * @param {string} root
+ * @returns {string[]}
+ */
+export function projectTags(root) {
+  if (!root) return []
+  try {
+    const cached = cache.get(root)
+    const pkgPath = path.join(root, 'package.json')
+    const marker = pkgPath
+    const mtime = statSync(marker).mtimeMs
+    if (cached && cached.mtimeMs === mtime) return cached.tags
+    const tags = collectTags(root)
+    cache.set(root, { tags, mtimeMs: mtime })
+    return tags
+  } catch {
+    const tags = collectTags(root)
+    cache.set(root, { tags, mtimeMs: 0 })
+    return tags
+  }
+}
+
+function collectTags(root) {
+  const tags = new Set()
+  try {
+    const pkg = JSON.parse(tryRead(path.join(root, 'package.json')) || '{}')
+    for (const t of depsOf(pkg, ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'])) tags.add(t)
+    for (const k of Array.isArray(pkg.keywords) ? pkg.keywords : []) if (typeof k === 'string') tags.add(k.toLowerCase())
+    if (pkg.name) tags.add(String(pkg.name).toLowerCase())
+  } catch {
+    // package.json 缺失或损坏 → 继续尝试其它清单
+  }
+  const go = tryRead(path.join(root, 'go.mod'))
+  if (go) {
+    const m = go.match(/^module\s+(\S+)/m)
+    if (m) tags.add(m[1].toLowerCase())
+  }
+  const cargo = tryRead(path.join(root, 'Cargo.toml'))
+  if (cargo) {
+    const m = cargo.match(/^\s*name\s*=\s*"([^"]+)"/m)
+    if (m) tags.add(m[1].toLowerCase())
+  }
+  return [...tags]
+}
+
+export function clearProjectTagsCache() {
+  cache.clear()
+}

package/src/reflection-pipeline.js

@@ -0,0 +1,146 @@
+// PR 1b 反思管线（v0.5，默认关）
+// - 触发：select_task 切走旧任务 / archive_task 与 /task archive /（预留空闲与 compaction 前）
+// - 输入不依赖对话原文：task 快照（title + steps + files）相对上次反思的摘要变更（digest 门控）
+// - 冷却：同任务 cooldownMs 内、内容摘要未变 → 跳过（LLM 零调用）
+// - 产出只写 task 级草稿（source: reflect, draft: true），不直接写 project/global；
+//   由 insight-store 的跨任务去重/自动提升语义处理（2 个独立任务命中同一坑 → 升 project）
+// - 任何失败只记日志，绝不抛出、不阻塞调用方
+import { createHash } from 'node:crypto'
+import { ProjectMemoryStore } from './store.js'
+import { memoryRootFor } from './util/fs.js'
+import { cfgInsight, saveInsight, GlobalStore, defaultGlobalFile } from './insight-store.js'
+import { chatText, parseStructuredJson } from './llm.js'
+
+export const REFLECT_SYSTEM =
+  'You distill task work into durable lessons and decisions for project memory. ' +
+  'Only record things worth remembering: a real pitfall hit and fixed, a correction received, or a deliberate tradeoff decision. ' +
+  'Normal development does not produce entries. ' +
+  'Return a STRICT JSON object: {"lessons":[{"pattern":"具体错误模式","fix":"修正做法","files":["rel/path.ts"],"symbols":["fnName"],"confidence":0.8}], ' +
+  '"decisions":[{"topic":"主题","choice":"选了什么","reason":"为什么","confidence":0.9}]}. ' +
+  'No markdown fences, no commentary, only the JSON object.'
+
+export function taskReflectionSnapshot(task) {
+  return {
+    title: task ? task.title : '',
+    steps: ((task && task.steps) || []).map((s) => (typeof s === 'string' ? s : s.content || s.text || '')).filter(Boolean).join('\n'),
+    files: ((task && task.files) || []).join('\n'),
+  }
+}
+
+export function taskDigest(task) {
+  const snap = taskReflectionSnapshot(task)
+  return createHash('sha256')
+    .update(JSON.stringify({ steps: snap.steps, files: snap.files }))
+    .digest('hex')
+    .slice(0, 16)
+}
+
+/** 反思是否到期（enabled / 未反思过 / 摘要已变 / 冷却已过）。 */
+export function isReflectDue(config, task, nowMs = Date.now()) {
+  const rc = (config && config.reflection) || {}
+  if (rc.enabled === false || rc.enabled == null) return { due: false, reason: 'disabled' }
+  if (!task) return { due: false, reason: 'no-task' }
+  const last = task.reflection || {}
+  if (!last.lastAt) return { due: true, reason: 'never' }
+  if (last.digest === taskDigest(task)) return { due: false, reason: 'unchanged' }
+  const cooldown = typeof rc.cooldownMs === 'number' ? rc.cooldownMs : 1800000
+  if (nowMs - Date.parse(last.lastAt) < cooldown) return { due: false, reason: 'cooldown' }
+  return { due: true, reason: 'changed' }
+}
+
+function normalizeList(arr, max) {
+  if (!Array.isArray(arr)) return []
+  return arr.filter((x) => x && typeof x === 'object').slice(0, max)
+}
+
+/**
+ * 对某任务做一次反思（可归档任务照做——归档正是收割时机）。
+ * 全程 try/catch：调用方 fire-and-forget 即可。
+ */
+export async function reflectTaskAfter({ config, llm, root, taskId, reason = 'transition' }) {
+  const rc = (config && config.reflection) || {}
+  const fallback = { ok: false, skipped: 'disabled' }
+  if (!rc.enabled) return fallback
+  if (!llm) return { ok: false, skipped: 'no-llm' }
+  try {
+    const store = new ProjectMemoryStore(memoryRootFor(root, config.memoryDir)).load()
+    const task = store.getTask(taskId)
+    const gate = isReflectDue(config, task)
+    if (!gate.due) return { ok: false, skipped: gate.reason }
+
+    const snap = taskReflectionSnapshot(task)
+    const user =
+      `Task: ${snap.title || '(untitled)'}\n` +
+      (snap.steps ? `Steps:\n${snap.steps.slice(0, 2000)}\n` : '') +
+      (snap.files ? `Files touched:\n${snap.files.slice(0, 1000)}\n` : '') +
+      `Trigger: ${reason}\n\nReturn the JSON object.`
+
+    const raw = await chatText(llm, REFLECT_SYSTEM, user, { timeoutMs: 90000 })
+    const parsed = parseStructuredJson(raw)
+    if (!parsed) return { ok: false, skipped: 'unparsable' }
+
+    const cfg = cfgInsight(config)
+    const globalStore = new GlobalStore(cfg.globalFile || defaultGlobalFile()).load()
+    const maxLessons = typeof rc.maxLessonsPerReflect === 'number' ? rc.maxLessonsPerReflect : 3
+    const maxDecisions = typeof rc.maxDecisionsPerReflect === 'number' ? rc.maxDecisionsPerReflect : 2
+    const written = []
+
+    for (const l of normalizeList(parsed.lessons, maxLessons)) {
+      if (!(l.pattern || l.title)) continue
+      const res = store.commit((s) =>
+        saveInsight({
+          store: s,
+          globalStore,
+          raw: {
+            title: l.title || l.pattern,
+            kind: 'lesson',
+            pattern: l.pattern,
+            fix: l.fix,
+            files: l.files,
+            symbols: l.symbols,
+            confidence: typeof l.confidence === 'number' ? l.confidence : 0.7,
+            draft: true,
+          },
+          scope: 'task',
+          taskId,
+          cfg,
+          source: 'reflect',
+        }),
+      )
+      if (res && res.ok) written.push({ kind: 'lesson', id: res.id, action: res.action })
+    }
+    for (const d of normalizeList(parsed.decisions, maxDecisions)) {
+      if (!(d.topic || d.choice)) continue
+      const res = store.commit((s) =>
+        saveInsight({
+          store: s,
+          globalStore,
+          raw: { title: d.topic, kind: 'decision', choice: d.choice, reason: d.reason, confidence: typeof d.confidence === 'number' ? d.confidence : 0.7, draft: true },
+          scope: 'task',
+          taskId,
+          cfg,
+          source: 'reflect',
+        }),
+      )
+      if (res && res.ok) written.push({ kind: 'decision', id: res.id, action: res.action })
+    }
+    // 标记反思进度（冷却/摘要以磁盘为准）
+    const now = new Date().toISOString()
+    store.commit((s) => s.updateTask(taskId, { reflection: { lastAt: now, digest: taskDigest(task) } }))
+    globalStore.commit() // task 路径可能链到 global（命中既有知识）
+    return { ok: true, reason, written }
+  } catch (err) {
+    console.error(`[dsh-project-memory] reflection failed for ${taskId}: ${err?.message || err}`)
+    return { ok: false, skipped: 'error', error: String(err?.message || err) }
+  }
+}
+
+/** 工具/命令层 fire-and-forget：默认关时立刻廉价返回，绝不让错误上抛。 */
+export function fireReflect(config, host, root, taskId, reason) {
+  const rc = (config && config.reflection) || {}
+  if (!rc.enabled) return Promise.resolve({ ok: false, skipped: 'disabled' })
+  return reflectTaskAfter({ config, llm: host?.llm, root, taskId, reason }).catch((err) => {
+    console.error(`[dsh-project-memory] fireReflect error: ${err?.message || err}`)
+    return { ok: false, skipped: 'error' }
+  })
+}

package/src/similarity.js

@@ -0,0 +1,52 @@
+// 通用文本相似度：双向 token overlap（归一化 0..1）
+// v0.5 去重 / 合并 / 强化共用的**唯一**相似度指标；BM25 只用于排序，禁止当阈值。
+//
+// 归一化定义：normalized = 共同 token 数 / 两文本中较长者的 token 数（= min(ratioA, ratioB)）。
+// 它与 v0.4 experience 层 "双向 ratio ≥ t" 判定等价：
+//   ratioA ≥ t 且 ratioB ≥ t  ⟺  overlap / max(lenA, lenB) ≥ t
+// 因此 "≥ 0.7 合并 / 0.65~0.7 强化" 只需在此单一尺度上比较，跨库/跨长度可比。
+import { tokenize } from './util/search.js'
+
+/**
+ * 归一化双向 token overlap。
+ * @param {string} a
+ * @param {string} b
+ * @returns {number} 0..1
+ */
+export function normalizedTokenOverlap(a, b) {
+  if (!a || !b) return 0
+  const ta = tokenize(String(a))
+  const tb = tokenize(String(b))
+  if (!ta.length || !tb.length) return 0
+  const sa = new Set(ta)
+  const sb = new Set(tb)
+  let overlap = 0
+  for (const t of sa) if (sb.has(t)) overlap++
+  return overlap / Math.max(sa.size, sb.size)
+}
+
+/** 一条 insight 参与相似度判定的文本（标题 + kind 专属正文）。 */
+export function insightMatchText(ins) {
+  return `${ins.title || ''} ${ins.problem || ''} ${ins.pattern || ''} ${ins.topic || ''} ${ins.choice || ''} ${ins.body || ''}`.trim()
+}
+
+/**
+ * 在候选列表里找与 text 重叠分最高（且未归档）的一条。
+ * @param {string} text
+ * @param {Array<object>} items
+ * @param {(item: object) => string} [getText]
+ * @returns {{ item: object, score: number } | null}
+ */
+export function findBestOverlapMatch(text, items, getText = (it) => insightMatchText(it)) {
+  let best = null
+  let bestScore = 0
+  for (const item of items) {
+    if (item && item.archived) continue
+    const score = normalizedTokenOverlap(text, getText(item))
+    if (score > bestScore) {
+      bestScore = score
+      best = item
+    }
+  }
+  return best ? { item: best, score: bestScore } : null
+}

package/src/store.js

@@ -10,6 +10,7 @@ const EXPERIENCE_FILE = 'experience.json'
 const TASKS_FILE = 'tasks.json'
 const BINDING_FILE = 'binding.json'
 const WATCH_FILE = 'watch.json'
+const INSIGHTS_FILE = 'insights.json'
 const SHARDS_DIR = 'shards'
 
 const storeCache = new Map()
@@ -60,12 +61,14 @@ export class ProjectMemoryStore {
     this.files = {}
     this.entries = {}
     this.experience = []
+    this.insights = { version: 1, migratedAt: null, items: [] }
     this.tasks = []
     this.binding = {}
     this.watchlist = []
     this._dirtyShards = new Set()
     this._removedShards = new Set()
     this._dirtyExperience = false
+    this._dirtyInsights = false
     this._dirtyTasks = false
     this._dirtyBinding = false
     this._dirtyWatch = false
@@ -80,6 +83,7 @@ export class ProjectMemoryStore {
     if (hot && hot !== this) return hot
     this._migrateLegacyIfNeeded()
     this._loadSharded()
+    this._loadInsights()
     storeCache.set(key, this)
     return this
   }
@@ -146,6 +150,71 @@ export class ProjectMemoryStore {
     this._formatWritten = existsSafe(path.join(this.dir, FORMAT_FILE))
   }
 
+  // ---- v0.5 insights：project 级 insight 文档（任务级在 task.insights[]） ----
+  // 迁移语义（与初版方案的差异，见 PLAN §10 风险 / 收尾说明）：
+  // v0.4 experience.json 仍由 remember/forget/query_memory 服务，不删除；
+  // 首次加载把旧笔记**复制导入** insights.json（kind: experience, source: migrate），
+  // migratedAt 落盘保证跨进程/崩溃幂等。销毁式收敛放到 recall 统一 PR。
+  _loadInsights() {
+    const doc = loadJson(path.join(this.dir, INSIGHTS_FILE), null)
+    this.insights = doc && typeof doc === 'object' && Array.isArray(doc.items) ? doc : { version: 1, migratedAt: null, items: [] }
+    this._migrateExperienceToInsights()
+  }
+
+  _migrateExperienceToInsights() {
+    if (this.insights.migratedAt) return
+    const legacy = this.experience
+    if (!Array.isArray(legacy) || legacy.length === 0) return
+    const now = new Date().toISOString()
+    const known = new Set(this.insights.items.map((it) => it.id))
+    let imported = 0
+    for (const item of legacy) {
+      if (!item || !item.problem || known.has(item.id)) continue
+      known.add(item.id)
+      this.insights.items.push({
+        id: item.id,
+        kind: 'experience',
+        scope: 'project',
+        title: String(item.problem).slice(0, 120),
+        problem: item.problem,
+        solution: item.solution,
+        files: item.sourceFile ? [item.sourceFile] : [],
+        symbols: [],
+        sourceTaskIds: [],
+        source: 'migrate',
+        confidence: 1,
+        hitCount: 0,
+        createdAt: item.createdAt || now,
+        updatedAt: item.updatedAt || now,
+      })
+      imported++
+    }
+    this.insights.migratedAt = now
+    try {
+      mkdirSync(this.dir, { recursive: true })
+      writeJsonAtomic(path.join(this.dir, INSIGHTS_FILE), this.insights)
+    } catch (err) {
+      console.error(`[dsh-project-memory] insights migration write failed: ${err.message}`)
+    }
+  }
+
+  insightsDoc() {
+    return this.insights
+  }
+
+  insightItems() {
+    return this.insights.items
+  }
+
+  replaceInsightItems(items) {
+    this.insights.items = items
+    this._dirtyInsights = true
+  }
+
+  markTasksDirty() {
+    this._dirtyTasks = true
+  }
+
   cleanStaleTmp() {
     const scanDirs = [this.dir, path.join(this.dir, SHARDS_DIR)]
     const now = Date.now()
@@ -195,6 +264,10 @@ export class ProjectMemoryStore {
       writeJsonAtomic(path.join(this.dir, EXPERIENCE_FILE), this.experience)
       this._dirtyExperience = false
     }
+    if (this._dirtyInsights) {
+      writeJsonAtomic(path.join(this.dir, INSIGHTS_FILE), this.insights)
+      this._dirtyInsights = false
+    }
     if (this._dirtyTasks) {
       writeJsonAtomic(path.join(this.dir, TASKS_FILE), this.tasks)
       this._dirtyTasks = false

package/src/tools/lesson-tools.js

@@ -0,0 +1,101 @@
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { memoryRootFor, resolveIndexRoot } from '../util/fs.js'
+import { ProjectMemoryStore } from '../store.js'
+import { truncate } from '../util/text.js'
+import { cfgInsight, saveInsight, defaultGlobalFile, GlobalStore } from '../insight-store.js'
+import { ensureGlobalInit } from '../global-seed.js'
+import { INSIGHT_KINDS, INSIGHT_SCOPES } from '../insight-store.js'
+
+function sessionIdOf(exec) {
+  return exec?.agent?.session?.id || exec?.ctx?.session?.id
+}
+
+export function lessonTool(config) {
+  const kindDesc = `insight 语义：lesson(曾踩坑/纠偏, pattern→fix) | decision(权衡选型, choice→reason) | procedure(多步指南, steps+可选 trigger) | experience(problem→solution，v0.4 兼容)。默认 lesson。`
+  const scopeDesc =
+    '作用域：task(任务私有，随任务归档，不进共享注入) | project(项目资产) | global(个人能力库，跨项目，建议配 trigger 关键词以便将来技能命中)。' +
+    '解析顺序：显式 scope > task_id > 当前绑定任务 > project。'
+  return defineTool({
+    name: 'save_lesson',
+    description:
+      'Save a lesson/decision/procedure/experience into the tiered memory (single insight entity). ' +
+      'Call it when the task hit a real pitfall, got corrected, or made a deliberate choice worth remembering — not for routine work. ' +
+      'Similar entries auto-merge (bidirectional token overlap >= 0.7) or reinforce (0.65~0.7, accumulating task hits); ' +
+      'when the same insight is hit by 2+ tasks it auto-promotes task -> project, 3+ tasks project -> global. ' + kindDesc + ' ' + scopeDesc,
+    parameters: {
+      title: { type: 'string', description: 'One-line title (lesson: the failure pattern; decision: the topic; procedure: the name).' },
+      kind: { type: 'string', enum: INSIGHT_KINDS, description: kindDesc },
+      scope: { type: 'string', enum: INSIGHT_SCOPES, description: scopeDesc },
+      pattern: { type: 'string', description: 'kind=lesson: 具体错误模式（同 title 时二选一）' },
+      fix: { type: 'string', description: 'kind=lesson: 修正做法' },
+      choice: { type: 'string', description: 'kind=decision: 选了什么' },
+      reason: { type: 'string', description: 'kind=decision: 为什么（权衡点）' },
+      steps: { type: 'array', items: { type: 'string' }, description: 'kind=procedure: 有序步骤（未来静默注入的正文）' },
+      trigger: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          keywords: { type: 'array', items: { type: 'string' } },
+          symbols: { type: 'array', items: { type: 'string' } },
+          scope: { type: 'array', items: { type: 'string' } },
+        },
+        description: 'kind=procedure: "作为 Skill" 的触发关键词（keywords/symbols + scope tags）',
+      },
+      task_id: { type: 'string', description: '目标任务 id（scope 缺省时优先于绑定任务）' },
+      files: { type: 'array', items: { type: 'string' }, description: '关联文件（项目相对路径）' },
+      symbols: { type: 'array', items: { type: 'string' }, description: '关联符号' },
+      confidence: { type: 'number', description: '置信 0..1（默认 0.8）' },
+      root: { type: 'string', description: 'Project root. Defaults to current working directory.' },
+    },
+    output: { schema: { type: 'string' }, render: (_a, v) => [{ type: 'text', text: v }] },
+    async execute(args, exec) {
+      const root = resolveIndexRoot(exec, args.root)
+      const memoryDir = memoryRootFor(root, config.memoryDir)
+      const store = new ProjectMemoryStore(memoryDir).load()
+      const cfg = cfgInsight(config)
+      const sid = sessionIdOf(exec)
+      const boundTaskId = sid ? store.getBoundTaskId(sid) : undefined
+      const taskId = args.task_id || boundTaskId
+
+      const raw = {
+        title: args.title,
+        kind: args.kind,
+        pattern: args.pattern,
+        fix: args.fix,
+        choice: args.choice,
+        reason: args.reason,
+        steps: args.steps,
+        trigger: args.trigger,
+        files: args.files,
+        symbols: args.symbols,
+        confidence: args.confidence,
+      }
+      if (!raw.title && !raw.pattern && !raw.choice) {
+        return truncate(JSON.stringify({ success: false, error: '需要 title / pattern / choice 之一' }), config.maxOutputChars || 8000)
+      }
+      if (!INSIGHT_KINDS.includes(raw.kind)) raw.kind = 'lesson'
+
+      let scope = args.scope
+      if (!scope) scope = taskId ? 'task' : 'project'
+      if (scope === 'task' && !taskId) {
+        return truncate(JSON.stringify({ success: false, error: 'task 级写入需要 task_id（或先 select_task 绑定会话）' }), config.maxOutputChars || 8000)
+      }
+
+      ensureGlobalInit(config) // 幂等确保 global 文件结构就绪
+      const globalStore = new GlobalStore(cfg.globalFile || defaultGlobalFile()).load()
+
+      let result
+      store.commit((s) => {
+        result = saveInsight({ store: s, globalStore, raw, scope, taskId, cfg, source: 'agent' })
+        return result
+      })
+      // global 变更（global scope 直写或 project 自动提升）单独落盘
+      globalStore.commit()
+      if (!result) result = { ok: false, error: '写入未完成' }
+      const body = result.ok
+        ? `Saved insight ${result.id} [scope=${result.scope || scope}] action=${result.action}${result.hint ? ` — ${result.hint}` : ''}`
+        : `Failed: ${result.error}`
+      return truncate(body, config.maxOutputChars || 8000)
+    },
+  })
+}

package/src/tools/task-tools.js

@@ -3,6 +3,7 @@ import { memoryRootFor, resolveIndexRoot } from '../util/fs.js'
 import { ProjectMemoryStore } from '../store.js'
 import { truncate } from '../util/text.js'
 import { genTaskId, hash8, adoptStepsToSession, shouldAdoptToHost } from '../setup/taskbridge.js'
+import { fireReflect } from '../reflection-pipeline.js'
 import { createHash } from 'node:crypto'
 
 function sessionIdOf(exec) {
@@ -51,7 +52,7 @@ export function listTasksTool(config) {
   })
 }
 
-export function selectTaskTool(config) {
+export function selectTaskTool(config, host) {
   return defineTool({
     name: 'select_task',
     description:
@@ -68,6 +69,7 @@ export function selectTaskTool(config) {
       const sid = sessionIdOf(exec)
       const now = new Date().toISOString()
       const error = (msg) => truncate(JSON.stringify({ success: false, error: msg }), config.maxOutputChars)
+      const prevBound = sid ? store.getBoundTaskId(sid) : undefined
 
       if (!args.taskId && !args.title) {
         return error('需要 taskId 或 title（先 list_tasks；未绑定会话出现 todo 时会自动新建任务）')
@@ -133,11 +135,17 @@ export function selectTaskTool(config) {
         adoptStepsToSession(exec?.agent?.session || exec?.ctx?.session, task)
       }
 
+      // 反思钩子：切走旧任务时异步收割（默认关，零成本；失败只记日志）
+      if (prevBound && prevBound !== task.id) {
+        fireReflect(config, host, root, prevBound, 'switch-away')
+      }
+
       const card = {
         taskId: task.id,
         title: task.title,
         steps: task.steps,
         files: task.files,
+        insights: task.insights || [], // v0.5：任务级 lessons/decisions/procedures
         hint: hint + '；请据此用 todo_write 重建本会话清单',
       }
       return truncate(JSON.stringify(card), config.maxOutputChars)
@@ -164,7 +172,7 @@ export function showTaskPanelTool(config) {
   })
 }
 
-export function archiveTaskTool(config) {
+export function archiveTaskTool(config, host) {
   return defineTool({
     name: 'archive_task',
     description: 'Archive a task: hide from default views, exclude from capacity, stop syncing. Restore by selecting it again.',
@@ -182,6 +190,8 @@ export function archiveTaskTool(config) {
       task.archived = true
       task.updatedAt = new Date().toISOString()
       store.save()
+      // 反思钩子：归档即收割最终教训（默认关）
+      fireReflect(config, host, root, args.taskId, 'archive')
       return truncate(JSON.stringify({ success: true, archived: true, hint: '已归档，select_task 可恢复' }), config.maxOutputChars)
     },
   })

package/src/types.js

@@ -0,0 +1,56 @@
+// JSDoc 类型定义（服务端一律 .js；本文件仅供编辑器/阅读共享心智，无运行时导出）。
+// v0.5 单一 insight 实体：kind 区分语义，scope 分层，提升 = scope 字段变更。
+
+/**
+ * @typedef {'lesson' | 'decision' | 'procedure' | 'experience'} InsightKind
+ *  lesson: 曾踩坑/纠偏（pattern→fix）；decision: 曾权衡的选型（topic→choice+reason）；
+ *  procedure: 多步操作指南（steps）；experience: v0.4 旧笔记迁移而来（problem→solution）。
+ *
+ * @typedef {'task' | 'project' | 'global'} InsightScope
+ *  task: tasks.json 内嵌于任务实体 task.insights[]（私有草稿）；
+ *  project: .dsh-project-memory/insights.json（团队/项目资产）；
+ *  global: ~/.config/dsh-project-memory/global.json（个人能力库，跨项目）。
+ *
+ * @typedef {object} Insight
+ * @property {string} id 全局唯一（新条目 "ins_…"；迁移条目沿用旧 uuid）
+ * @property {InsightKind} kind
+ * @property {InsightScope} scope
+ * @property {boolean} [draft] true = 反思自动产出，未审核、不参与注入
+ * @property {string} title 一句话标题
+ * @property {string} [body] 正文
+ * @property {string[]} [steps] procedure 有序步骤
+ * @property {string} [choice] decision：选项
+ * @property {string} [reason] decision：理由
+ * @property {string} [pattern] lesson：错误模式
+ * @property {string} [fix] lesson：修正做法
+ * @property {string} [problem] experience：问题（旧字段保留）
+ * @property {string} [solution] experience：解法（旧字段保留）
+ * @property {string[]} [files] 关联代码位置
+ * @property {string[]} [symbols] 关联符号
+ * @property {string[]} [sourceTaskIds] 曾在哪些任务中出现/被命中（提升判定唯一依据）
+ * @property {'reflect' | 'agent' | 'user' | 'migrate'} [source] 来源
+ * @property {{ scope: string, id: string, at: string }} [movedFrom] 提升/降级审计
+ * @property {{ keywords: string[], symbols?: string[], scope?: string[] }} [trigger]
+ *   procedure 的 "生成 Skill" 触发规则（无独立 skill 实体）
+ * @property {number} [confidence] 0..1
+ * @property {number} [hitCount] 被注入/命中的次数（强化信号，无 LLM）
+ * @property {string} [lastHitAt] 最近一次命中时间 ISO（衰减/归档依据）
+ * @property {boolean} [archived] 归档 = 软删：不进召回/注入，可恢复
+ * @property {string[]} [tags]
+ * @property {string} createdAt
+ * @property {string} updatedAt
+ */
+
+/**
+ * @typedef {object} InsightConfig
+ * @property {number} [dedupOverlap] 双向 token overlap 阈值（≥ 合并/取代）
+ * @property {number} [reinforceBand] 近重复强化带下界（0.65~dedupOverlap → 强化）
+ * @property {number} [maxProject] project insights 容量（归档区另计）
+ * @property {number} [maxGlobalProcedures] global insights 容量
+ * @property {number} [promoteConfidence] 提升 project 所需最低 confidence
+ * @property {number} [globalPromoteTasks] sourceTaskIds ≥ N → 提升 global
+ * @property {number} [decayDays] 久置归档启发：hitCount==0 超该天数 → 归档（软删）
+ * @property {string} [globalFile] global.json 绝对路径（默认 ~/.config/dsh-project-memory/global.json）
+ */
+
+export {}