@a9i5k4/dsh-auto-memory 2.5.3 → 3.0.1

package/lib/rules-layer.js

@@ -0,0 +1,261 @@
+/**
+ * 规则层抽取（rules_layer_v1）—— P6A 的"分类"部分（Phase 6 拆分中的 6A）。
+ *
+ * 2026-09-14 建立（P0 第五步）。**它解决的是用户最痛的病之一**：
+ *   注入开场白原来把所有记忆统一降格为「只是背景事实与规则参考」（`lib/index.js` 的
+ *   `DEFAULT_PROMPT_LAYERS.snapshotHead`），**规则与资料混在一句措辞里** ⇒ 模型注意力不落在规矩上。
+ *   用户原话：「这个 just for reference 说得太轻了，模型注意力没有在这上面。」
+ *
+ * **本模块只做一件事**：从记忆文本里**认出规则类条目**，把它们与参考类分开。
+ * 措辞分层（不同引导语）与节奏（每轮在场）由调用方负责。
+ *
+ * **真源纪律（v2 修正，必须遵守）**：用户级规则＝**既有用户级记忆文件**（`~/.dsh/memory/MEMORY.md`）
+ * 里的类型化规则，**不是新增 `RULES.md`**。`ROUND3 §2.3` 记录了我方曾在两处写了两个真源，
+ * 被 GPT 抓出。若将来真要独立真源，必须补迁移/去重/旧模式读取/回滚四类测试。
+ *
+ * **两级判定**（T7-4 的"双保险"，v2 修正后的形态）：
+ *   ① **结构化前缀**（高置信）：`【用户硬性规则…】` 这类显式标记 —— 这是既有记忆的真实形态
+ *      （实测：`~/.dsh/memory/MEMORY.md` 首条即 `【用户硬性规则 - 文件编码】`）。
+ *   ② **约束语汇**（中置信）：`严禁` / `绝不` / `必须` / `不得` 等。
+ *
+ *   ⚠️ **v2 明确纠正过我方原设计**：不能"命中关键词就无条件升级为规则"。
+ *   反例（GPT 给）：`"文档写着必须重启"`、`"曾经要求必须 X 但已取消"` —— 这类是**描述**不是**要求**。
+ *   故本模块对 ② 类的结果标注 `confidence:'medium'` 并**保留原文里的引用/历史语境标记**
+ *   （`引文` / `已取消` / `据文档` 等），由调用方决定是否只作为「待确认候选」。
+ *   本模块**不把中置信项冒充高置信**——那正是 T7-4 要防的误报。
+ *
+ * **依赖边界（如实标注，不宣称已保证）**：本模块保证的是"规则段被**注入函数**产出且不受节流与裁剪"。
+ *   "模型**真的收到了**"取决于宿主最终请求 messages 的确认（`MASTER-PLAN-3.0.md §7` 的 **U6**，
+ *   尚未具备）⇒ **不得**据此宣称"规则的遵守问题已解决"（T7-7 的纪律）。
+ *
+ * S9 合规：零 IO、零依赖、纯函数、无网络/无 LLM/无子进程/无 await。UTF-8 无 BOM。
+ */
+
+export const RULES_LAYER_VERSION = 'rules_layer_v1'
+
+/**
+ * ★P6B（2026-09-15 · 用户裁定开工）：日志行内 kind 标记 —— 规则分类的**持久化**落点。
+ *
+ * 权威依据：`TODO-GRAPH.html` V2-P6B 卡 points[1]（"分类时机：不做独立 LLM 调用，
+ * memory_log 本来就在本轮内由模型直接写，顺手打 kind 标记＝零额外成本"）+ crit[1]（T7-5）。
+ *
+ * **形态选行内标记** `- HH:MM [kind:rule] 内容`：日志是 append-only 纯文本，行内标记
+ * 可被本模块的条目切分生态直接消费，且重启/迁移不丢（不依赖任何 sidecar）。
+ * kind 作**可选参数**（缺省 fact）：不传时写入行与旧版逐字节一致（新旧并存 + 开关回退纪律）。
+ */
+export const LOG_KINDS_V1 = Object.freeze(['rule', 'preference', 'fact', 'todo'])
+
+/** 行内标记的正则形态（渲染/解析两侧共用，不各写一套）。 */
+export const LOG_KIND_TAG_RE_V1 = /\s*\[kind:(rule|preference|fact|todo)\]\s*/
+
+/** 结构化前缀（高置信）：既有用户级记忆的真实形态。 */
+export const RULE_MARKERS_V1 = Object.freeze([
+  '【用户硬性规则', '【硬性规则', '【规则】', '【必须遵守', '【禁止', '【用户规则',
+])
+
+/** 约束语汇（中置信）—— 单靠它**不足以**判定为规则（见文件头 T7-4 说明）。 */
+export const RULE_CONSTRAINT_WORDS_V1 = Object.freeze([
+  '严禁', '绝不', '必须', '不得', '禁止', '务必', '一律', '永远不', '不要再', '不准',
+])
+
+/**
+ * 引用/历史语境标记：出现这些 ⇒ 该段说的是"别处这么写"或"曾经如此"，
+ * **不是**当前有效的规则要求 ⇒ 降级为 `candidate`（待确认候选），不得自动取得不可裁地位。
+ * 这是 v2 §3.3（Q7 第 2 条）给的反例在代码里的落点。
+ */
+export const RULE_DESCRIPTION_MARKERS_V1 = Object.freeze([
+  '据文档', '文档写着', '文档说', '曾经', '已取消', '已废弃', '不再要求', '原要求', '旧规则', '据说',
+])
+
+/** 条目切分锚点：与 `l0-extract.js` 的记忆锚点完全一致（不另立一套）。 */
+const MEM_ANCHOR_LINE_RE = /^<!--\s*memory:(mem_[0-9a-f]{32})\s*-->$/
+
+/** 条目内的日期小节（`## 2026-08-14`）——既有记忆文件的实际结构。 */
+const DATE_SECTION_RE = /^##\s*\d{4}-\d{2}-\d{2}\s*$/
+
+const clean = (s) => String(s == null ? '' : s)
+
+/**
+ * 把记忆文本按锚点切成条目（保持既有文件结构语义：无锚点的前置内容归入首条）。
+ *
+ * @param {string} text 用户级/工作区级记忆文件全文
+ * @returns {Array<{id:string, anchorLine:number, text:string, lines:string[]}>}
+ */
+export function splitMemoryEntriesPre(text) {
+  const src = clean(text).replace(/^\uFEFF/, '')
+  if (!src.trim()) return []
+  const lines = src.split('\n')
+  const out = []
+  let cur = null
+  for (let i = 0; i < lines.length; i++) {
+    const m = MEM_ANCHOR_LINE_RE.exec(lines[i].replace(/\r$/, ''))
+    if (m) {
+      if (cur) out.push(cur)
+      cur = { id: m[1], anchorLine: i + 1, lines: [] }
+      continue
+    }
+    if (cur) cur.lines.push(lines[i])
+  }
+  if (cur) out.push(cur)
+  if (!out.length) {
+    // 无锚点文件（旧格式）⇒ 整篇算一条，不丢内容
+    return [{ id: '', anchorLine: 0, lines, text: src.trim() }]
+  }
+  return out.map((e) => ({ id: e.id, anchorLine: e.anchorLine, lines: e.lines, text: e.lines.join('\n').trim() }))
+}
+
+/** 单条文本的规则分类（返回置信度与理由，不抛异常）。 */
+function classifyText(rawText) {
+  const text = clean(rawText)
+  if (!text.trim()) return { kind: 'reference', confidence: 'none', reasons: ['空内容'] }
+  const marker = RULE_MARKERS_V1.find((k) => text.includes(k))
+  if (marker) {
+    return { kind: 'rule', confidence: 'high', reasons: ['结构化前缀 ' + marker] }
+  }
+  const words = RULE_CONSTRAINT_WORDS_V1.filter((w) => text.includes(w))
+  if (!words.length) return { kind: 'reference', confidence: 'none', reasons: ['无规则标记与约束语汇'] }
+  const desc = RULE_DESCRIPTION_MARKERS_V1.filter((w) => text.includes(w))
+  if (desc.length) {
+    // ★ v2 修正的落点：含"必须"但是**描述/引文**，不得自动升级为规则
+    return {
+      kind: 'candidate', confidence: 'low',
+      reasons: ['约束语汇（' + words.slice(0, 3).join('/') + '）但含引用/历史语境（' + desc.slice(0, 3).join('/') + '）⇒ 仅作待确认候选，不自动取得规则地位'],
+    }
+  }
+  return { kind: 'rule', confidence: 'medium', reasons: ['约束语汇 ' + words.slice(0, 3).join('/')] }
+}
+
+/**
+ * 从记忆文本里抽出规则层（分项，供注入侧分层措辞与"不参与裁剪"）。
+ *
+ * @param {object} input
+ * @param {string} [input.userText] 用户级记忆（跨工作区恒定；**规则真源**，见文件头）
+ * @param {string} [input.notesText] 工作区级项目笔记（第二层）
+ * @param {string} [input.rulesLayeringMode] 'off' | 'self' | 'none'
+ *   - `'off'`：**默认**。返回空规则层（调用方回落旧行为：统一措辞 + 原有节奏）。这就是"新旧并存 + 开关回退"。
+ *   - `'self'`：只看**当前 agent 自己写的** user 层（隔离子代理/外部导入的规则，防串线）。
+ *   - `'none'`：不看任何 user 层（只保留工作区级）。
+ * @param {string} [input.ownerSessionId] `rulesLayeringMode='self'` 时用于判定"是不是我自己写的"
+ * @returns {{version:string, mode:string, enabled:boolean, text:string, rules:Array, candidates:Array,
+ *            references:Array, counts:object, chars:{rules:number,candidates:number,total:number}}}
+ */
+export function extractRulesLayerPre(input = {}) {
+  const o = input && typeof input === 'object' ? input : {}
+  const mode = clampMode(o.rulesLayeringMode)
+  const empty = {
+    version: RULES_LAYER_VERSION, mode, enabled: false, text: '', rules: [], candidates: [], references: [],
+    counts: { entries: 0, rules: 0, candidates: 0, references: 0 }, chars: { rules: 0, candidates: 0, total: 0 },
+  }
+  if (mode === null) return empty
+
+  const sources = []
+  const pushAll = (layer, text) => {
+    for (const e of splitMemoryEntriesPre(text)) sources.push({ layer, ...e })
+  }
+  // 模式语义（与文件头一致，别写反）：
+  //   'self'  ⇒ 看用户级（跨工作区恒定）+ 工作区级
+  //   'none'  ⇒ **不看任何用户级**，只看工作区级（用于"工作区规则覆盖用户规则"的场景）
+  if (mode !== 'none') pushAll('user', o.userText)
+  pushAll('project', o.notesText)
+
+  const rules = []
+  const candidates = []
+  const references = []
+  for (const e of sources) {
+    const c = classifyText(e.text)
+    const rec = { layer: e.layer, id: e.id, anchorLine: e.anchorLine, kind: c.kind, confidence: c.confidence, reasons: c.reasons, text: e.text }
+    if (c.kind === 'rule') rules.push(rec)
+    else if (c.kind === 'candidate') candidates.push(rec)
+    else references.push(rec)
+  }
+
+  // 规则层文本：只含规则条目（高/中置信），逐条一行摘要，**不掺参考类**
+  const renderLine = (r) => '- ' + ruleSummaryPre(r.text)
+  const parts = []
+  if (rules.length) parts.push(rules.map(renderLine).join('\n'))
+  const text = parts.join('\n')
+  return {
+    version: RULES_LAYER_VERSION, mode, enabled: true, text, rules, candidates, references,
+    counts: { entries: sources.length, rules: rules.length, candidates: candidates.length, references: references.length },
+    chars: { rules: text.length, candidates: candidates.reduce((a, r) => a + ruleSummaryPre(r.text).length + 2, 0), total: text.length },
+  }
+}
+
+/** 模式解析：`null` 表示"未启用"（调用方沿用旧行为）。 */
+function clampMode(v) {
+  const s = clean(v).trim().toLowerCase()
+  if (!s || s === 'off' || s === 'false' || s === '0') return null
+  if (s === 'self' || s === 'none' || s === 'all') return s
+  return null // 非法值一律当"未启用"（fail-soft，不因配置写错而改变注入）
+}
+
+/** 取第一条非空行并裁剪（规则条目往往首行就是规则名，够用且省 token）。 */
+export function firstLine(text, max = 200) {
+  const lines = clean(text).split('\n').map((l) => l.trim()).filter(Boolean)
+  const first = lines[0] || ''
+  return first.length > max ? first.slice(0, Math.max(1, max - 1)) + '…' : first
+}
+
+/**
+ * 规则条目的**摘要行**（渲染用）：跳过日期小节标题（`## 2026-08-14`）与纯标点行，
+ * 取第一条实质内容。
+ *
+ * **为什么需要它**（实测踩坑）：既有记忆文件的条目结构是「锚点 → `## 日期` → 正文」，
+ * 直接用 `firstLine` 会渲染成 `- ## 2026-08-14` —— 规则内容全丢，只剩日期，
+ * 而且**看起来还挺正常**（这条断言首跑就红在"连续 6 轮规则都在"上，因为摘要里没有规则文本）。
+ *
+ * ★P6B：`[kind:x]` 行内标记在此**剥离**（标记只服务盘上审计与分类持久化，
+ * 注入摘要保持干净）；时间戳 `HH:MM` 一并剥离（对规则语义是噪声）。
+ */
+export function ruleSummaryPre(text, max = 200) {
+  const lines = clean(text).split('\n').map((l) => l.trim()).filter(Boolean)
+  for (const l of lines) {
+    if (DATE_SECTION_RE.test(l)) continue
+    if (/^<!--/.test(l)) continue
+    if (/^[-*+]\s*$/.test(l)) continue
+    // 去掉列表前缀再返回，保持一条一行
+    let body = l.replace(/^[-*+]\s+/, '')
+    // ★P6B：剥行内 kind 标记与前置时间戳（只影响渲染，不回写盘上原文）
+    body = body.replace(LOG_KIND_TAG_RE_V1, ' ').trim()
+    body = body.replace(/^\d{1,2}:\d{2}\s+/, '').trim()
+    return body.length > max ? body.slice(0, Math.max(1, max - 1)) + '…' : body
+  }
+  return ''
+}
+
+/**
+ * 规则段渲染（**供注入侧直接使用**）：标题 + 引导语 + 逐条规则。
+ *
+ * 措辞分层的关键（T7-3）：**规则类用约束语**（"必须遵守"），**参考类保留"参考"语义**。
+ * 两段引导语必须**不相同** —— 断言直接锁这一点，防止有人改回统一措辞。
+ *
+ * @param {object} rules `extractRulesLayerPre` 的返回值
+ * @param {object} [opts]
+ * @param {string} [opts.title] 段标题（默认常量）
+ * @param {string} [opts.guide] 引导语（默认常量）
+ * @returns {{text:string, chars:number, guide:string}}
+ */
+export function renderRulesSectionPre(rules, opts = {}) {
+  const r = rules && typeof rules === 'object' ? rules : {}
+  const list = Array.isArray(r.rules) ? r.rules : []
+  if (!list.length) return { text: '', chars: 0, guide: '' }
+  const title = clean((opts && opts.title) || RULES_SECTION_TITLE_V1)
+  const guide = clean((opts && opts.guide) || RULES_SECTION_GUIDE_V1)
+  const text = '\n' + title + '\n' + guide + '\n' + list.map((x) => '- ' + ruleSummaryPre(x.text)).join('\n')
+  return { text, chars: text.length, guide }
+}
+
+/**
+ * 规则段标题（T7-3：与参考段的措辞**必须不同**；断言直接比对两者）。
+ * 用户可通过 `promptLayerOverrides.snapshotRulesTitle` 覆盖。
+ */
+export const RULES_SECTION_TITLE_V1 = '[规则 — 用户级硬性约束 · 必须遵守]'
+
+/**
+ * 规则段引导语：**约束语**（"以下为必须遵守的约束"），不是"只是参考"。
+ * 这句话就是 P6A「措辞」要修的病：旧开场白把规矩与资料统一降格为「只是背景事实与规则参考」。
+ */
+export const RULES_SECTION_GUIDE_V1 = '以下条目是用户明确要求长期遵守的约束，不是可选背景。凡与其它内容冲突，以本节为准；无法满足时必须显式说明。'
+
+/** 参考段引导语（保留"参考"语义，与规则段措辞不同）。 */
+export const REFERENCE_SECTION_GUIDE_V1 = '以下为背景资料与历史记录，供参考与检索定位；与上面的规则冲突时不适用。'

package/lib/semantic-decide.js

@@ -27,16 +27,49 @@ const PLAN_TOKENS = ['准备', '打算', '计划', '之后', '接下来', '继
 const WS_RUN = /\s\s+/g
 // Python `(?u)\b\w\w+\b` 中 \w 含 CJK;JS 的 \w 默认只含 ASCII,须显式加 CJK
 // 否则中文词不被切分 → 无 gram → 中文意图全靠 intercept(严重偏差)。
-const WORD_RE = /[A-Za-z0-9_\u4e00-\u9fff]+/g
+// ★ issue #68 修复（2026-09-19）：**加 `{2,}` 下限** —— Python 侧是 `\b\w\w+\b`（**≥2 字**），
+//   旧实现允许 1 字词（`+`）⇒ 中文单字（如「好」「是」）在 JS 侧会生成 gram、Python 侧不会，
+//   两版对**同一输入**给出不同 gram 集合 ⇒ 判定分叉。
+const WORD_RE = /[A-Za-z0-9_\u4e00-\u9fff]{2,}/g
+
+/**
+ * 与 Python `normalize_text` 逐字对齐。
+ * ★ issue #68 修复（2026-09-19）：旧实现有三处分叉，现全部按 **Python 为权威** 对齐：
+ *   ① **整删非字母数字**：旧实现 `.replace(/[^…\s]/g, ' ')` 把标点变**空格** ⇒ `"a-b"` 得到 `"a b"`（两词），
+ *      而 Python 是 `''.join(ch for ch in text.lower() if ch.isalnum() or CJK)` ⇒ `"ab"`（**一词**）；
+ *   ② **`isalnum()` 语义**：Python 的 `str.isalnum()` 对**全角数字**（`１２３`）、带音标字母（`é`）为真，
+ *      而 JS 正则 `[a-z0-9]` 只认 ASCII ⇒ 这类字符在 JS 侧被丢弃、Python 侧保留；
+ *   ③ **不再额外压空白**：Python 整删后**不插空格**，故 `"a  b"` → `"a  b"`（原样）而非 `"a b"`。
+ *   修法用 `codePointAt` + `isAlnumPythonish()` 复刻 `isalnum()`，而不是改正则字符类。
+ */
+function isAlnumPythonish(cp) {
+  // ASCII 字母数字
+  if (cp >= 0x30 && cp <= 0x39) return true // 0-9
+  if (cp >= 0x61 && cp <= 0x7a) return true // a-z（已 lower）
+  if (cp >= 0x41 && cp <= 0x5a) return true // A-Z（防御：未 lower 时）
+  // CJK 统一表意文字（与既有 \u4e00-\u9fff 口径一致）
+  if (cp >= 0x4e00 && cp <= 0x9fff) return true
+  // 全角数字 ０-９
+  if (cp >= 0xff10 && cp <= 0xff19) return true
+  // 全角字母 ａ-ｚ / Ａ-Ｚ（★ 首轮遗漏：`toLowerCase()` 会把 Ａ(U+FF21) 折叠成 ａ(U+FF41)，
+  // 若只覆盖数字，全角字母会在折叠后**整段消失**，与 Python `isalnum()` 仍为真的语义分叉）
+  if (cp >= 0xff21 && cp <= 0xff3a) return true // Ａ-Ｚ（防御：未 lower 时）
+  if (cp >= 0xff41 && cp <= 0xff5a) return true // ａ-ｚ（lower 后的实际落点）
+  // 拉丁补充字母（含 é 等带音标字符，覆盖 Latin-1 Supplement 的字母区）
+  if (cp >= 0x00c0 && cp <= 0x00ff && cp !== 0x00d7 && cp !== 0x00f7) return true
+  if (cp >= 0x0100 && cp <= 0x017f) return true // Latin Extended-A
+  return false
+}
 
-/** 与 Python normalize_text 对齐(大小写折叠 + 保留 [a-z0-9]+CJK + 去其他)。 */
 function normalizeText(text) {
-  return String(text || '')
-    .toLowerCase()
-    .replace(WS_RUN, ' ')
-    // 保留字母数字与 CJK,其余变空格(近似 Python 的 keep [a-z0-9] and CJK)
-    .replace(/[^a-z0-9\u4e00-\u9fff\s]/g, ' ')
-    .trim()
+  const lower = String(text || '').toLowerCase()
+  let out = ''
+  // 按码点遍历（避免代理对拆断），复刻 Python 的 `if ch.isalnum()` 整删语义
+  for (const ch of lower) {
+    const cp = ch.codePointAt(0)
+    if (isAlnumPythonish(cp)) out += ch
+  }
+  return out
 }
 
 /** char_wb n-gram 计数(与 Python _char_wb_ngram_counts 对齐)。 */

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,
@@ -342,7 +381,22 @@ export function createJsSemanticEnginePre(opts = {}) {
         return null // fail closed:词法回退由调用方自然发生
       }
     },
-    _resetForTest() { tier = null; tierPromise = null; degraded = ''; idx = { miv: null, entries: [] }; rebuilding = null },
+    /**
+     * 2026-09-14（三层契约 C3）：暴露**批量段落嵌入**通道 —— L0 向量索引接线
+     * （`lib/l0-index-sync.js`）需要把 L0 摘要本身变成向量，而 rank() 只返回
+     * 「查询 vs 内部缓存索引」的余弦分，**不产出向量**（此前宿主没有任何拿向量的口子，
+     * 这是 `createL0IndexPre` 一直零引用、无法接线的原因之一）。
+     *
+     * 语义：裸文本数组 → `Float32Array[]`（e5 口径为 384 维已归一化；前缀 `passage: ` 由引擎内部加，
+     * 与 rank 的 `query: ` 前缀对称，调用方传**裸文本**）。
+     * 失败语义：模型资产缺失/加载失败 → 抛错（**不吞**）—— 由调用方 fail-soft（索引侧只 diag 一行，
+     * 不阻塞任何检索路径）。本方法不改任何内部状态（不缓存、不动 idx），纯计算。
+     */
+    async embedPassages(texts) {
+      const t = await ensureTier()
+      return t.embedPassages(Array.isArray(texts) ? texts : [])
+    },
+    _resetForTest() { tier = null; tierPromise = null; degraded = ''; degradedAt = 0; statsRetries = 0; idx = { miv: null, entries: [] }; rebuilding = null },
   }
 }
 
@@ -398,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/shadow-retrieval.js

@@ -402,14 +402,14 @@ const MEMORY_ID_STRICT = /^mem_[0-9a-f]{32}$/
 
 /** §11 retrievalId(确定性,可重放;非长期内容身份)。 */
 export function buildRetrievalId(sessionId, contextVersion, triggerSegmentId, memoryIndexVersion) {
-  const sessionIdHash = first32(sha256Str('retrieval-pre-v1\u0000' + sessionId))
-  const parts = ['retrieval-pre-v1', sessionIdHash, contextVersion, triggerSegmentId, memoryIndexVersion, GATE_POLICY_VERSION, LEXICAL_POLICY_VERSION]
+  const sessionIdHash = first32(sha256Str('retrieval-v1\u0000' + sessionId))
+  const parts = ['retrieval-v1', sessionIdHash, contextVersion, triggerSegmentId, memoryIndexVersion, GATE_POLICY_VERSION, LEXICAL_POLICY_VERSION]
   return RETRIEVAL_PREFIX + first32(sha256Str(JSON.stringify(parts)))
 }
 
 /** §11 candidateId:同 memoryId 内容变化后 candidateId 因版本/digest 改变。 */
 export function buildCandidateId(retrievalId, memoryId, sourceEpoch, sourceVersion, recordDigest) {
-  const parts = ['candidate-pre-v1', retrievalId, memoryId, sourceEpoch, sourceVersion, recordDigest]
+  const parts = ['candidate-v1', retrievalId, memoryId, sourceEpoch, sourceVersion, recordDigest]
   return CANDIDATE_PREFIX + first32(sha256Str(JSON.stringify(parts)))
 }
 

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'