@a9i5k4/dsh-auto-memory 3.0.0 → 3.0.1

package/lib/semantic-js.js

@@ -17,6 +17,7 @@ import { existsSync, readFileSync, mkdirSync, readdirSync, renameSync, statSync,
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import { createRequire } from 'node:module'
 import path from 'node:path'
+import { resolveDshHomePre } from './dsh-home.js'
 import { homedir } from 'node:os'
 
 export const JS_SEMANTIC_ENGINE_VERSION = 'js_semantic_engine_v1'
@@ -70,7 +71,8 @@ const E5_MODELS_SUBDIR = 'multilingual-e5-small'
 function defaultModelsDirCandidates(pluginDir) {
   // 用户目录优先(#15 后续/B 修复):~/.dsh/models/js-semantic/ 跨插件升级存活——
   // 包目录(lib/models)在 npm 更新时会被整体重装,下载的 130MB 模型曾被冲掉。
-  const dshHome = (process.env.DSH_HOME && process.env.DSH_HOME.trim()) || path.join(homedir(), '.dsh')
+  // ★#86-3：统一口径
+  const dshHome = resolveDshHomePre()
   return [
     path.join(dshHome, 'models', 'js-semantic'),
     path.join(pluginDir, 'models'),
@@ -161,9 +163,20 @@ export function deepScanPeerTransformers(roots) {
  * semanticAssetProbe 共享实现(index.js 的 status API / 档位解析 / 引导卡同源):
  * 模型资产=发行包 lib/models 优先,其次开发树;peer=resolvePeerTransformersDir。
  * extraDirs 透传给 peer 探测(深度扫描热接入位)。返回形状与 v0.1.36 完全一致。
+ *
+ * ★ issue #70 修复（2026-09-19）：新增 `degraded` 字段。
+ *   旧实现是纯 `existsSync` 探测 —— **资产在磁盘上存在 ≠ 引擎可用**：
+ *   一旦运行期 `ensureTier()` 失败（onnx 损坏 / 维度不符 / peer 加载失败），引擎置 `degraded`
+ *   并此后恒抛；但探针只回 `ready = assetPresent && peerPresent` ⇒
+ *   **引导卡显示「✓ 就绪」、档位解析给出 c2，而实际每次检索都在静默走词法兜底**（状态自相矛盾）。
+ *   现把降级状态并进 `ready`（并单列 `degraded` 供诊断），使三条用户可见路径（引导卡 / 档位 / status）一致。
+ * @param {string} pluginDir
+ * @param {string[]} [extraDirs]
+ * @param {string} [degradedReason] 当前引擎的降级原因（空串=未降级）
  */
-export function probeJsSemanticAssets(pluginDir, extraDirs) {
-  const dshHome = (process.env.DSH_HOME && process.env.DSH_HOME.trim()) || path.join(homedir(), '.dsh')
+export function probeJsSemanticAssets(pluginDir, extraDirs, degradedReason) {
+  // ★#86-3：统一口径
+  const dshHome = resolveDshHomePre()
   const modelCands = [
     path.join(dshHome, 'models', 'js-semantic', E5_MODELS_SUBDIR, 'onnx', 'model_quantized.onnx'),
     path.join(pluginDir, 'models', E5_MODELS_SUBDIR, 'onnx', 'model_quantized.onnx'),
@@ -172,10 +185,15 @@ export function probeJsSemanticAssets(pluginDir, extraDirs) {
   const modelOnnx = modelCands.find((c) => existsSync(c)) || modelCands[0]
   const assetPresent = existsSync(modelOnnx)
   const peerDir = resolvePeerTransformersDir(pluginDir, extraDirs)
+  const filesReady = Boolean(assetPresent && peerDir)
+  const degraded = String(degradedReason || '')
   return {
     assetPresent,
     peerPresent: Boolean(peerDir),
-    ready: Boolean(assetPresent && peerDir),
+    // ★ 资产齐备**且未降级**才算就绪（否则 UI 报"就绪"而实际降级）
+    ready: filesReady && !degraded,
+    filesReady,
+    degraded,
     assetBytes: assetPresent ? statSync(modelOnnx).size : 0,
     assetPath: modelOnnx,
   }
@@ -213,6 +231,8 @@ export function createJsSemanticEnginePre(opts = {}) {
   let tier = null            // {embedQuery, embedPassages, model}
   let tierPromise = null
   let degraded = ''          // 非空 = 初始化失败原因(调用方回退词法)
+  let degradedAt = 0         // ★ issue #70：最近一次置位的时刻（用于有界自动重试的冷却判定）
+  let statsRetries = 0       // ★ issue #70：因冷却到期而清空降级态的累计次数（诊断用）
   let lastRankError = ''     // 运行期排名失败原因(诊断用;rank 恒返回 null 由调用方回退)
   let idx = { miv: null, entries: [] } // entries [{memoryId, vec}]
   let rebuilding = null      // 单飞行重建 promise
@@ -223,7 +243,21 @@ export function createJsSemanticEnginePre(opts = {}) {
 
   async function ensureTier() {
     if (tier) return tier
-    if (degraded) throw new Error(degraded)
+    // ★ issue #70 修复（2026-09-19）：`degraded` 由**单向闩锁**改为**有界自动重试**。
+    //   旧行为：首次 `ensureTier()` 失败 ⇒ `degraded` 置位 ⇒ 此后恒抛，
+    //   **唯一清除出口是测试钩子 `_resetForTest`** ⇒ 用户补齐资产 / 修好 onnx 后，
+    //   本进程内**永久** C2 降级（只能重启宿主），且 UI 仍显示"✓ 就绪"（见 probeJsSemanticAssets 的修复）。
+    //   现行为：冷却期（默认 60s，可配 `degradedRetryMs`）过后允许**再试一次**；
+    //   重试仍失败则更新时间戳继续冷却 —— 既不会每轮都去加载大模型，也不会永久闩死。
+    if (degraded) {
+      const since = Date.now() - degradedAt
+      const retryMs = Number((opts && opts.degradedRetryMs) || 60000)
+      if (since < retryMs) throw new Error(degraded)
+      // 冷却已过 ⇒ 清空降级态、允许重建（tierPromise 也一并清掉，避免复用已失败的 promise）
+      degraded = ''
+      tierPromise = null
+      statsRetries++
+    }
     if (!tierPromise) {
       tierPromise = (async () => {
         if (opts.injectEmbedder) return opts.injectEmbedder
@@ -268,6 +302,7 @@ export function createJsSemanticEnginePre(opts = {}) {
       return tier
     } catch (e) {
       degraded = String(e && e.message || e).slice(0, 160)
+      degradedAt = Date.now()   // ★ issue #70：记时刻，供冷却判定
       tierPromise = null
       throw e
     }
@@ -305,6 +340,10 @@ export function createJsSemanticEnginePre(opts = {}) {
         assetPresent: existsSync(path.join(modelsDir(), E5_MODELS_SUBDIR, 'onnx', 'model_quantized.onnx')),
         ready: !!tier,
         degraded,
+        // ★ issue #70：暴露降级时刻与重试计数，供面板/诊断判断"是否处于冷却期、下次何时可重试"
+        degradedAt: degraded ? degradedAt : 0,
+        degradedRetryMs: Number((opts && opts.degradedRetryMs) || 60000),
+        degradedRetries: statsRetries,
         lastRankError,
         model: tier ? tier.model : null,
         indexedRecords: idx.entries.length,
@@ -357,7 +396,7 @@ export function createJsSemanticEnginePre(opts = {}) {
       const t = await ensureTier()
       return t.embedPassages(Array.isArray(texts) ? texts : [])
     },
-    _resetForTest() { tier = null; tierPromise = null; degraded = ''; idx = { miv: null, entries: [] }; rebuilding = null },
+    _resetForTest() { tier = null; tierPromise = null; degraded = ''; degradedAt = 0; statsRetries = 0; idx = { miv: null, entries: [] }; rebuilding = null },
   }
 }
 
@@ -413,6 +452,12 @@ export function createSemanticDownloaderPre(opts = {}) {
     const total = Number(res.headers.get('content-length')) || fileRec.bytes
     mkdirSync(tmpDir(), { recursive: true })
     const dst = path.join(tmpDir(), path.basename(fileRec.rel))
+    // ★ 每次尝试从零开始（2026-09-19 上游 PR #79 / issue #65 同步落地）：
+    //   tmp 只在 run() 开始清一次，但 fetchToFile 会被**多个镜像依次调用**；
+    //   而写入用 flag:'a' 追加 ⇒ 源 A 断流留下的半截文件会被续上源 B 的完整流。
+    //   致命处：sha256 只对**网络流**累积（hash.update）、**不回读文件** ⇒ 拼接体校验照样通过并落位，
+    //   直到加载期才失败。故每次尝试前必须清掉残留。
+    try { rmSync(dst, { force: true }) } catch (_) {}
     const hash = createHash('sha256')
     const reader = res.body.getReader()
     const fd = writeFileSync // 占位避免未用告警;真正写入走手动缓冲

package/lib/shadow-host.js

@@ -10,6 +10,7 @@
  */
 import { mkdirSync, appendFileSync, writeFileSync, readFileSync, readdirSync, existsSync, statSync, rmSync } from 'node:fs'
 import path from 'node:path'
+import { resolveDshHomeForEnginePre } from './dsh-home.js'
 import { homedir } from 'node:os'
 import { createHash } from 'node:crypto'
 import {
@@ -126,11 +127,8 @@ export function createShadowHost({ engine }) {
   /** durable audit 目录与日期分片。 */
   function auditDir() { return path.join(dshHome(), 'memory', 'retrieval-pre', 'audit') }
   function dshHome() {
-    const env = process.env.DSH_HOME
-    if (env && env.trim()) return env.trim()
-    // M4-4 修复:必须拼接 .dsh(此前漏拼导致 audit 写到 <home>/memory 错误位置)
-    const base = engine.__homedirFn ? engine.__homedirFn() : (process.env.USERPROFILE || process.env.HOME || '')
-    return base ? path.join(base, '.dsh') : '.'
+    // ★#86-3：统一口径（M4-4 的「必须拼 .dsh」约定已由 resolveDshHomePre 保证）。
+    return resolveDshHomeForEnginePre(engine)
   }
 
   /** 串行 durable append(§15.4):engine 级链式;失败只计 audit-write-failed 不重试不污染 Session。 */

package/lib/skill-export-host.js

@@ -0,0 +1,153 @@
+/**
+ * M9-3 Skill 导出层 · 宿主侧（IO 落地）。
+ *
+ * 纯渲染在 `skill-export.js`；本文件只负责**写盘**与**项目标注解析**。
+ *
+ * ★ 用户 2026-09-19 拍板：
+ *   - ⑪-2 **晋升为 `active` 后自动导出** ⇒ 由 host 在 `activate` 成功后调用 `exportSkillForPre()`。
+ *   - ⑪-3 目录 = **用户级**（`<dshHome>/skills/`，DSH 四条发现路径之一，可跨项目迁移）；
+ *          导出物**必须标注适用项目**。
+ *
+ * 设计纪律：
+ *   ① **fail-soft 但可观察**：返回 `{ok:false, reason}`，不抛出、不静默；
+ *   ② **不自动执行**任何导出程序（程序只是参考资料）；
+ *   ③ 写盘走**临时文件 + rename**（避免半截文件被 DSH 当成合法 SKILL.md）；
+ *   ④ 不覆盖**非本插件产出**的同名目录（有 `mem-skill-` 前缀 + 自检标记才接管）。
+ */
+
+import { mkdirSync, writeFileSync, renameSync, existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { renderSkillMarkdownPre, validateSkillMarkdownPre } from './skill-export.js'
+
+/** 导出目录前缀（用于识别"这是本插件的产物"，避免误覆盖用户手写技能）。 */
+export const SKILL_EXPORT_PREFIX_V1 = 'mem-skill-'
+/** 自检标记：出现在 SKILL.md 里即证明是本插件导出物。 */
+export const SKILL_EXPORT_STAMP_V1 = 'mem-skill-export-v1'
+
+/**
+ * 解析技能导出根目录。
+ * 优先级：opts.skillsRoot > <dshHome>/skills
+ * （`<dshHome>` 由调用方从 DSH 环境取得；本函数不猜路径。）
+ */
+export function resolveSkillsRootPre(opts = {}) {
+  if (opts.skillsRoot) return String(opts.skillsRoot)
+  const home = String(opts.dshHome || '').trim()
+  if (!home) return null
+  return join(home, 'skills')
+}
+
+/** 从项目根路径推出一个稳定的项目名（用于 ⑪-3 的「适用项目」标注）。 */
+export function projectNameFromPre(projectPath) {
+  const p = String(projectPath || '').trim().replace(/[\\/]+$/, '')
+  if (!p) return ''
+  const base = p.split(/[\\/]/).filter(Boolean).pop() || ''
+  return base
+}
+
+/** 收集可附带的程序文件（⑪-1）：只收**明确的程序后缀**，不递归、不猜。 */
+export function collectProgramsPre(projectPath, names) {
+  const out = []
+  if (!Array.isArray(names) || !names.length) return out
+  for (const n of names) {
+    const s = String(n || '').trim()
+    if (!s) continue
+    // 只认相对文件名，防目录穿越
+    if (s.includes('..') || /^[\\/]/.test(s) || /^[a-zA-Z]:/.test(s)) continue
+    out.push(s)
+  }
+  return out
+}
+
+function readIfExists(p) {
+  try { return existsSync(p) ? readFileSync(p, 'utf8') : null } catch (_) { return null }
+}
+
+/**
+ * 导出一个 procedure 为 `<skillsRoot>/<dirName>/SKILL.md`。
+ *
+ * @param {object} procedure  procedure 记录（stage 应为 active）
+ * @param {object} opts
+ * @param {string} opts.skillsRoot  技能根目录（必填；见 resolveSkillsRootPre）
+ * @param {string} opts.projectPath 项目根绝对路径
+ * @param {string} opts.projectName 项目名（缺省由 projectPath 推导）
+ * @param {string[]} opts.programs  附带程序相对路径列表
+ * @param {string} opts.exportedAt  ISO 时间
+ * @param {boolean} opts.force      为 true 时允许覆盖**非本插件**的同名目录
+ * @returns {{ok:boolean, reason?:string, dir?:string, file?:string, bytes?:number}}
+ */
+export function exportSkillForPre(procedure, opts = {}) {
+  try {
+    const skillsRoot = String(opts.skillsRoot || '')
+    if (!skillsRoot) return { ok: false, reason: 'no-skills-root' }
+
+    const projectPath = String(opts.projectPath || '')
+    const projectName = String(opts.projectName || '').trim() || projectNameFromPre(projectPath)
+    if (!projectName) return { ok: false, reason: 'no-project-name' }
+
+    const programs = collectProgramsPre(projectPath, opts.programs)
+    const r = renderSkillMarkdownPre(procedure, {
+      projectName,
+      projectPath,
+      programs,
+      exportedAt: opts.exportedAt || new Date().toISOString(),
+    })
+    if (!r.ok) return { ok: false, reason: r.reason }
+
+    // 自带标记 + 完整性自检（判据 = 用户 ⑪-1/⑪-3 的硬要求）
+    const content = r.content + '\n<!-- ' + SKILL_EXPORT_STAMP_V1 + ' -->\n'
+    const v = validateSkillMarkdownPre(content, { projectName, hasPrograms: programs.length > 0 })
+    if (!v.ok) return { ok: false, reason: 'notice-incomplete:' + v.problems.join('|') }
+
+    const dir = join(skillsRoot, r.dirName)
+    // 防误覆盖：目录已存在且**不是**本插件产物 ⇒ 拒绝（除非 force）
+    if (existsSync(dir) && !opts.force) {
+      const old = join(dir, 'SKILL.md')
+      const prev = readIfExists(old)
+      const isOurs = prev != null && prev.includes(SKILL_EXPORT_STAMP_V1)
+      const isOursByName = r.dirName.startsWith(SKILL_EXPORT_PREFIX_V1)
+      if (!isOurs && isOursByName) {
+        // 按名字是我们的，但内容不是 ⇒ 用户手写过，别动
+        if (prev != null) return { ok: false, reason: 'dir-occupied-by-foreign' }
+      }
+    }
+
+    mkdirSync(dir, { recursive: true })
+    // 临时文件 + rename ⇒ 避免半截文件被 DSH 扫描到
+    const tmp = join(dir, '.SKILL.md.tmp-' + process.pid + '-' + Date.now())
+    const file = join(dir, 'SKILL.md')
+    writeFileSync(tmp, content, 'utf8')
+    renameSync(tmp, file)
+
+    return { ok: true, dir, file, bytes: Buffer.byteLength(content, 'utf8'), dirName: r.dirName }
+  } catch (e) {
+    return { ok: false, reason: 'export-failed:' + String((e && e.message) || e) }
+  }
+}
+
+/** 列出已导出的技能（供诊断/GUI）。 */
+export function listExportedSkillsPre(skillsRoot) {
+  const root = String(skillsRoot || '')
+  if (!root || !existsSync(root)) return []
+  const out = []
+  let entries = []
+  try { entries = readdirSync(root) } catch (_) { return [] }
+  for (const name of entries) {
+    if (!name.startsWith(SKILL_EXPORT_PREFIX_V1)) continue
+    const dir = join(root, name)
+    try { if (!statSync(dir).isDirectory()) continue } catch (_) { continue }
+    const prev = readIfExists(join(dir, 'SKILL.md'))
+    if (prev == null || !prev.includes(SKILL_EXPORT_STAMP_V1)) continue
+    const nameLine = /^name:\s*(.+)$/m.exec(prev)
+    const projLine = /适用项目\*\*：`([^`]+)`/.exec(prev)
+    out.push({
+      dirName: name,
+      dir,
+      name: nameLine ? nameLine[1].trim() : name,
+      project: projLine ? projLine[1] : '',
+      bytes: Buffer.byteLength(prev, 'utf8'),
+    })
+  }
+  return out
+}
+
+export { renderSkillMarkdownPre, validateSkillMarkdownPre } from './skill-export.js'

package/lib/skill-export.js

@@ -0,0 +1,239 @@
+/**
+ * M9-3 Skill 导出层（procedure → SKILL.md 目录束）。
+ *
+ * ★ 2026-09-19 用户拍板（三项）：
+ *   ⑪-1 形态：`SKILL.md` + **附上过程中用到的程序**（如 `.py`），且 SKILL.md 里
+ *        必须明写：这些程序**只是参考性的** —— 若当前做的事情与之前**根本不同**，
+ *        可以用来**迁移**，**不能直接运行**。
+ *   ⑪-2 时机：**晋升为 `active` 后自动导出**。
+ *   ⑪-3 目录：**用户级**（软件层面，可跨项目迁移）；但导出物**必须标注适用于哪个项目**，
+ *        项目不一样时**只作参考，不能直接用**。
+ *
+ * 本模块是**纯渲染层**（无 IO、无状态），便于直接单测：
+ *   - `renderSkillMarkdownPre(procedure, opts)` → SKILL.md 文本
+ *   - `skillDirNamePre(procedure)` → 目录名（稳定、可预测）
+ *   - `SKILL_USAGE_NOTICE_V1` → 使用约束条款（导出物必须原样包含）
+ *
+ * 设计纪律（与 procedure 引擎同源）：
+ *   ① **不新增状态源** —— 导出物是 procedure 的**派生物**，不是新的事实来源；
+ *   ② **不自动执行任何导出的程序** —— 程序是**参考资料**，不是可调用入口；
+ *   ③ 全部 fail-soft，但**返回可观察结果**（ok/reason），不静默。
+ */
+
+// ★ T7-b（2026-09-20）：纯计算依赖，用于给「纯中文标题」生成稳定的 ASCII 目录名。
+//   node 内建模块，不引入外部依赖、不做 IO、不持有状态 —— 与本模块「纯渲染层」定位不冲突。
+import { createHash } from 'node:crypto'
+
+/** 导出物的使用约束条款 —— **必须原样出现在每个 SKILL.md 中**（用户 ⑪-1 硬要求）。 */
+export const SKILL_USAGE_NOTICE_V1 = [
+  '> **⚠️ 使用约束（必读）**',
+  '>',
+  '> 本技能由 **dsh-auto-memory** 从一次真实工作过程**自动沉淀**而来，**不是通用最佳实践**。',
+  '>',
+  '> 1. **附带程序仅供参考**：本目录下的脚本（如 `.py`）是**当时那次工作用过的程序**，',
+  '>    **不是可直接调用的工具**。它们可能依赖当时的路径、环境变量、数据格式或版本。',
+  '> 2. **场景根本不同时 → 只做迁移，不要直接运行**：若当前任务与下方「来源」描述的场景',
+  '>    **有根本差异**，请把附带的程序**当作思路参考**，按当前场景**重写**，而不是直接执行。',
+  '> 3. **跨项目使用须先核对**：本技能的「适用项目」若与当前项目**不一致**，',
+  '>    **一律只作参考**，不得直接套用其路径、命令与判据。',
+  '> 4. **高风险步骤需人工确认**：涉及删除、发布、付费、外部发送等动作，必须先向用户复述确认。',
+].join('\n')
+
+/** SKILL.md 中必须出现的约束锚点（供套件断言，防止被后续改动悄悄删掉）。 */
+export const SKILL_NOTICE_ANCHORS_V1 = Object.freeze([
+  '使用约束（必读）',
+  '附带程序仅供参考',
+  '只做迁移，不要直接运行',
+  '跨项目使用须先核对',
+  '高风险步骤需人工确认',
+])
+
+const MAX_TITLE_LEN = 80
+
+/**
+ * 目录名 / `name:` 字段：`mem-skill-<slug>-<procId前12位>` —— 稳定、可预测、不冲突。
+ *
+ * ★ T7-b（2026-09-20 用户报「所有中文技能都叫 untitled」）修复：
+ *   **根因**：原实现 `title.replace(/[^a-z0-9]+/g,'-')` 只保留 ASCII ⇒ **纯中文标题 slug 成空串**
+ *   ⇒ 一律回落字面量 `'untitled'`。后果是每个中文技能都叫 `mem-skill-untitled-<id>`，
+ *   用户看到的技能列表名字毫无意义（实测：本机导出的
+ *   `~/.dsh/skills/mem-skill-untitled-aa2153f33507/SKILL.md`）。
+ *
+ *   **为什么不能用「保留中文」这个修法**：DSH 宿主对 skill name 是**硬校验**，不是建议 ——
+ *   `SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/`（宿主 `index.js:17`），且
+ *   `:481` 直接 `throw new Error('loaded skill has invalid name "…"')`。
+ *   ⇒ 中文进 name 会让**技能加载直接失败**（比 untitled 更糟）。故必须产出 ASCII 安全名。
+ *
+ *   **采用的修法**：slug 为空时，取标题的 **sha1 前 8 位十六进制**做 `t-<hash>` 前缀。
+ *   - ASCII 安全：`t-1a2b3c4d` 完全符合上面的 SKILL_NAME 正则；
+ *   - 稳定：同一 title ⇒ 同一 hash ⇒ 目录名不变（自动化重导出不会产生新目录）；
+ *   - 可区分：不同标题 hash 不同，不再出现「一堆 untitled」；
+ *   - 中文原文**不丢**：仍完整出现在 SKILL.md 的 `# <title>` 与 `description` 里，
+ *     用户/模型在技能列表看到的是中文标题，name 只承担「唯一标识」职责。
+ *
+ *   ⚠️ 哈希算法用 node 内建 `createHash('sha1')`（纯计算，不引入 IO/状态），
+ *   与 FNV-1a 那种"自造哈希"区分开 —— 本仓有过 sha256Hex 同名异义的教训（#86-1）。
+ */
+export function skillDirNamePre(procedure) {
+  const id = String((procedure && procedure.procedureId) || '')
+  const short = id.replace(/^proc_/, '').slice(0, 12)
+  const title = String((procedure && procedure.title) || '')
+  const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40)
+  // 纯中文（或纯符号）标题：ASCII slug 为空 ⇒ 用标题哈希代替，绝不留 'untitled'
+  const stem = slug || ('t-' + createHash('sha1').update(title, 'utf8').digest('hex').slice(0, 8))
+  return 'mem-skill-' + stem + '-' + (short || 'noid')
+}
+
+/** 一句话摘要（取步骤首条或标题）——用于 SKILL.md 的 description。 */
+/**
+ * 一句话摘要 —— 用于 SKILL.md 的 `description:` 字段。
+ *
+ * ★ T7-b（2026-09-20）修正取值优先级：**title 优先，steps[0] 兜底**（原来是反的）。
+ *   为什么反了不行：`description` 是模型在技能目录里看到的那句话，应当回答
+ *   「这个技能**是干什么的**」—— title 正是这件事；而 steps[0] 是**第一个动作**
+ *   （实测导出的描述成了「备份：Copy-Item lib/index.js …」，完全看不出技能用途）。
+ *   仅当 title 缺失时才用 steps[0] 兜底（此时有总比没有好）。
+ */
+function summaryOfPre(p) {
+  const t = String(p.title || '').trim()
+  const step = Array.isArray(p.steps) && p.steps.length ? String(p.steps[0]).trim() : ''
+  const s = t || step
+  return s.length > MAX_TITLE_LEN ? s.slice(0, MAX_TITLE_LEN - 1) + '…' : s
+}
+
+/**
+ * 渲染 SKILL.md。
+ *
+ * @param {object} procedure  procedure 记录（stage 应为 active）
+ * @param {object} opts
+ * @param {string} opts.projectName   适用项目名（**必填**，⑪-3）
+ * @param {string} opts.projectPath   项目根绝对路径（用于溯源）
+ * @param {string[]} opts.programs     附带程序文件名列表（⑪-1，仅列名）
+ * @param {string} opts.exportedAt    导出时间（ISO 字符串；缺省由调用方给）
+ * @returns {{ok:true, fileName:string, dirName:string, content:string} | {ok:false, reason:string}}
+ */
+export function renderSkillMarkdownPre(procedure, opts = {}) {
+  const p = procedure || {}
+  if (!p.procedureId) return { ok: false, reason: 'no-procedure-id' }
+  if (!p.title) return { ok: false, reason: 'no-title' }
+  const projectName = String(opts.projectName || '').trim()
+  if (!projectName) return { ok: false, reason: 'no-project-name' }   // ⑪-3 硬要求：必须标项目
+  const projectPath = String(opts.projectPath || '').trim()
+  const programs = Array.isArray(opts.programs) ? opts.programs.filter(Boolean).map(String) : []
+  const exportedAt = String(opts.exportedAt || '')
+
+  const L = []
+  L.push('---')
+  L.push('name: ' + skillDirNamePre(p))
+  L.push('description: ' + summaryOfPre(p).replace(/\r?\n/g, ' '))
+  L.push('---')
+  L.push('')
+  L.push('# ' + String(p.title).trim())
+  L.push('')
+  L.push(SKILL_USAGE_NOTICE_V1)
+  L.push('')
+
+  // ── 来源（⑪-3：必须标注适用于哪个项目）──
+  L.push('## 来源')
+  L.push('')
+  L.push('- **适用项目**：`' + projectName + '`' + (projectPath ? '（`' + projectPath + '`）' : ''))
+  L.push('- **沉淀自**：dsh-auto-memory 技能库（procedure `' + p.procedureId + '`）')
+  if (p.riskLevel) L.push('- **风险等级**：`' + p.riskLevel + '`' + (p.requiresApproval ? '（需人工批准）' : ''))
+  if (exportedAt) L.push('- **导出时间**：' + exportedAt)
+  L.push('')
+  L.push('> 若你的当前项目**不是** `' + projectName + '`，请**只作参考**，不要直接套用下方路径与命令。')
+  L.push('')
+
+  // ── 适用条件 ──
+  if (Array.isArray(p.preconditions) && p.preconditions.length) {
+    L.push('## 何时适用')
+    L.push('')
+    for (const x of p.preconditions) L.push('- ' + String(x))
+    L.push('')
+  }
+
+  // ── 步骤 ──
+  if (Array.isArray(p.steps) && p.steps.length) {
+    L.push('## 步骤')
+    L.push('')
+    p.steps.forEach((s, i) => L.push(String(i + 1) + '. ' + String(s)))
+    L.push('')
+  }
+
+  // ── 检查点 ──
+  if (Array.isArray(p.checks) && p.checks.length) {
+    L.push('## 检查点')
+    L.push('')
+    for (const x of p.checks) L.push('- [ ] ' + String(x))
+    L.push('')
+  }
+
+  // ── 成功判据 ──
+  if (Array.isArray(p.successCriteria) && p.successCriteria.length) {
+    L.push('## 成功判据')
+    L.push('')
+    for (const x of p.successCriteria) L.push('- ' + String(x))
+    L.push('')
+  }
+
+  // ── 回滚 ──
+  if (Array.isArray(p.rollback) && p.rollback.length) {
+    L.push('## 回滚')
+    L.push('')
+    for (const x of p.rollback) L.push('- ' + String(x))
+    L.push('')
+  }
+
+  // ── 附带程序（⑪-1）──
+  if (programs.length) {
+    L.push('## 附带程序（**参考性**）')
+    L.push('')
+    L.push('以下文件是**当时那次工作用过的程序**，随本技能一起导出：')
+    L.push('')
+    for (const f of programs) L.push('- `' + f + '`')
+    L.push('')
+    L.push('> **不要直接运行**。先读一遍，判断它与当前场景的差异；')
+    L.push('> 若场景根本不同，请**按当前场景迁移重写**；确需运行时，先向用户说明并确认。')
+    L.push('')
+  }
+
+  // ── 证据 ──
+  if (Array.isArray(p.sourceEpisodes) && p.sourceEpisodes.length) {
+    L.push('## 依据')
+    L.push('')
+    L.push('- 来源 episode 数：' + p.sourceEpisodes.length)
+    if (p.evidence && typeof p.evidence === 'object') {
+      const ev = p.evidence
+      const parts = []
+      if (Number.isFinite(ev.seen)) parts.push('seen=' + ev.seen)
+      if (Number.isFinite(ev.success)) parts.push('success=' + ev.success)
+      if (Number.isFinite(ev.correction)) parts.push('correction=' + ev.correction)
+      if (parts.length) L.push('- 证据统计：' + parts.join(' / '))
+    }
+    L.push('')
+  }
+
+  return { ok: true, fileName: 'SKILL.md', dirName: skillDirNamePre(p), content: L.join('\n') + '\n' }
+}
+
+/**
+ * 导出完整性校验（供套件与调用方共用）。
+ * **判据是"用户 ⑪-1/⑪-3 的硬要求"本身**，不是实现细节。
+ */
+export function validateSkillMarkdownPre(content, expect = {}) {
+  const s = String(content == null ? '' : content)
+  const problems = []
+  if (!s.trim()) problems.push('empty')
+  for (const a of SKILL_NOTICE_ANCHORS_V1) if (!s.includes(a)) problems.push('missing-notice:' + a)
+  if (!/^---\r?\n[\s\S]*?\r?\n---/.test(s)) problems.push('no-frontmatter')
+  if (!/^name:\s*\S+/m.test(s)) problems.push('no-name')
+  if (!/^description:\s*\S+/m.test(s)) problems.push('no-description')
+  if (expect.projectName && !s.includes('`' + expect.projectName + '`')) problems.push('no-project-tag')
+  // ⑪-1：附带程序必须被运行约束**包裹**，而不是只列个名。
+  // ★ 判据必须锚定属于「程序块」的形态：
+  //   顶层约束条款里也出现「不要直接运行」四字（后接 `**：`），
+  //   只用该四字做判据会**同义反复**（永远为真）——套件 [5] 组已实跑抓到这一版缺陷。
+  //   程序块独有形态 = 加粗短语**后紧跟句号**：`**不要直接运行**。`
+  if (expect.hasPrograms && !/\*\*不要直接运行\*\*。/.test(s)) problems.push('programs-not-constrained')
+  return { ok: problems.length === 0, problems }
+}

package/lib/storage-manage.js

@@ -116,6 +116,12 @@ export function createStorageManagerPre(opts = {}) {
   /** 读取既有 sidecar(尽力而为):用于 rebuildSidecar 继承 epoch/version,避免无谓的 epoch 漂移。 */
   function readSidecarPrev(file) {
     try {
+      // ★ issue #55 修复（2026-09-18，2026-09-19 补回）：函数体内**自行活读** docStore。
+      //   旧写法直接引用闭包里的 `docStore`，但该名只在 `repair`/`deleteMemory` 内部局部声明
+      //   ⇒ 本函数作用域内**未定义** ⇒ 每次调用抛 ReferenceError ⇒ 被下方 `catch (_)` 吞掉
+      //   ⇒ **恒返回 null** ⇒ `rebuildSidecar` 拿不到 prev ⇒ epoch 漂移、fresh 被翻成 stale。
+      //   必须走 `docStoreOf()` 工厂活读（getter 语义：memoryAnchorEnabled 后续生效也能拿到）。
+      const docStore = docStoreOf()
       if (!docStore || typeof docStore.sidecarPath !== 'function') return null
       const sp = docStore.sidecarPath(file)
       if (!sp) return null