@a9i5k4/dsh-auto-memory 3.0.0 → 3.1.0

package/lib/rules-edit.js

@@ -0,0 +1,159 @@
+/**
+ * rules-edit.js —— 「用户级硬性约束」的**条目级**解析与增删改（R7 需求）。
+ *
+ * ## 背景（用户 2026-09-20 明确要求「这个功能必须要落在前端」）
+ *
+ * `[规则 — 用户级硬性约束 · 必须遵守]` 这一段是**每轮无条件注入**的硬约束，
+ * 真源 = `~/.dsh/memory/MEMORY.md`（见 `rules-layer.js:12` 的真源纪律）。
+ * 它**不走语义层** —— 即没有检索/打分/淘汰环节 ⇒ **过时条目不会被自动清理**；
+ * 而 AI（`memory_user`）也会往里写错东西。
+ * ⇒ 用户必须能**自己增/删/改**，否则错一条就每轮都被误导。
+ *
+ * ## 与既有渲染层的关系（重要：本模块不改变注入语义）
+ *
+ * `rules-layer.js` 的 `extractRulesLayerPre()` 负责**读**（把 MEMORY.md 解析成规则段），
+ * `renderRulesSectionPre()` 负责**渲染**。本模块只做**编辑定位**：
+ * 给定原文，找出「哪一段是规则段、每条规则在第几行」，以及产出改后的新全文。
+ * 它**不碰**注入、不碰检索、不碰 store。
+ *
+ * ## 条目模型
+ *
+ * 用户级 MEMORY.md 由若干 `## YYYY-MM-DD` 日期段 + `- ` 条目行组成。
+ * `rules-layer.js` 的渲染器只取 `- ` 开头的行（且跳过日期段）。
+ * ⇒ **一条规则 = 一个 `- ` 行**。本模块据此提供：
+ *   - `listRuleItemsPre(text)`      → [{ line, indent, text, source }]
+ *   - `updateRuleItemPre(text, i, next)` / `removeRuleItemPre(text, i)` / `appendRuleItemPre(text, body)`
+ *
+ * `source` 的判定：条目若落在 `## YYYY-MM-DD` 段内 ⇒ 归该日期（多为 AI 写入）；
+ * 落在段外（文件头部）⇒ 记为 `user`（多为用户手写）。这是 R7-3「标注来源」的依据。
+ *
+ * ## 纪律
+ *   - 纯函数：输入文本、输出文本，**不做任何 IO**（IO 由调用方走既有 writeFull 事务）。
+ *   - **删除 = 真删**（见 R7-4）：本层渲染器不认任何状态标记，软删标记会被当正文注入模型。
+ *   - 零运行时依赖。CRLF、无 BOM。
+ */
+
+/** 日期段标题（与 rules-layer.js 的 DATE_SECTION_RE 同口径）。 */
+export const RULE_DATE_SECTION_RE_V1 = /^##\s*\d{4}-\d{2}-\d{2}\s*$/
+
+/** 条目行：允许前导缩进 + `- `（渲染器同样只看 `- ` 行）。 */
+export const RULE_ITEM_RE_V1 = /^(\s*)-\s+(.*)$/
+
+/** 单条规则长度上限（与写闸门同量级，防止一次塞进整篇文档）。 */
+export const RULE_ITEM_MAX_CHARS_V1 = 2000
+
+/**
+ * 列出所有规则条目（**行号从 0 开始**，供后续增删改定位）。
+ *
+ * @param {string} text  MEMORY.md 全文
+ * @returns {Array<{line:number, indent:string, text:string, source:string, dateSection:string|null}>}
+ */
+export function listRuleItemsPre(text) {
+  const lines = String(text == null ? '' : text).split(/\r?\n/)
+  const out = []
+  let curDate = null
+  for (let i = 0; i < lines.length; i++) {
+    const l = lines[i]
+    if (RULE_DATE_SECTION_RE_V1.test(l)) { curDate = l.replace(/^##\s*/, '').trim(); continue }
+    const m = RULE_ITEM_RE_V1.exec(l)
+    if (!m) continue
+    const body = m[2].trim()
+    if (!body) continue
+    out.push({
+      line: i,
+      indent: m[1] || '',
+      text: body,
+      // 落在日期段内 ⇒ 多为 AI（memory_user 会带日期标题）写入；否则视为用户手写
+      source: curDate ? 'ai' : 'user',
+      dateSection: curDate,
+    })
+  }
+  return out
+}
+
+/** 内部：切行（保留原始行尾风格判定所需的信息交给 join 处理）。 */
+function splitLinesPre(text) { return String(text == null ? '' : text).split(/\r?\n/) }
+
+function joinLinesPre(lines) { return lines.join('\n') }
+
+/**
+ * **替换**第 idx 条规则（按 listRuleItemsPre 的顺序）。
+ *
+ * @returns {{ok:boolean, text?:string, error?:string}}
+ */
+export function updateRuleItemPre(text, idx, nextBody) {
+  const items = listRuleItemsPre(text)
+  const body = String(nextBody == null ? '' : nextBody).trim()
+  if (!Number.isInteger(idx) || idx < 0 || idx >= items.length) return { ok: false, error: 'index-out-of-range' }
+  if (!body) return { ok: false, error: 'empty-body' }
+  if (body.length > RULE_ITEM_MAX_CHARS_V1) return { ok: false, error: 'too-long' }
+  if (/\r|\n/.test(body)) return { ok: false, error: 'multiline-not-allowed' }
+  const lines = splitLinesPre(text)
+  const it = items[idx]
+  lines[it.line] = it.indent + '- ' + body
+  return { ok: true, text: joinLinesPre(lines) }
+}
+
+/**
+ * **删除**第 idx 条规则（真删，见 R7-4）。
+ *
+ * ⚠️ 本层渲染器（`renderRulesSectionPre`）不认任何状态标记 ⇒ 软删标记会被当正文注入模型；
+ *    故这里**直接移除该行**。不可撤销 —— 调用方必须做二次确认。
+ */
+export function removeRuleItemPre(text, idx) {
+  const items = listRuleItemsPre(text)
+  if (!Number.isInteger(idx) || idx < 0 || idx >= items.length) return { ok: false, error: 'index-out-of-range' }
+  const lines = splitLinesPre(text)
+  lines.splice(items[idx].line, 1)
+  return { ok: true, text: joinLinesPre(lines) }
+}
+
+/**
+ * **追加**一条规则。
+ *
+ * 落点规则（与用户手写习惯一致，且保证渲染器一定能读到）：
+ *   - `dateSection` 为空 ⇒ 追加到**文件头部**（用户手写区，`source` 会是 `user`）；
+ *   - 给了 `dateSection` ⇒ 追加到该日期段的**末尾**（AI 写入区）。
+ */
+export function appendRuleItemPre(text, body, opts = {}) {
+  const b = String(body == null ? '' : body).trim()
+  if (!b) return { ok: false, error: 'empty-body' }
+  if (b.length > RULE_ITEM_MAX_CHARS_V1) return { ok: false, error: 'too-long' }
+  if (/\r|\n/.test(b)) return { ok: false, error: 'multiline-not-allowed' }
+  const lines = splitLinesPre(text)
+  const want = opts && opts.dateSection ? String(opts.dateSection).trim() : ''
+  const newLine = '- ' + b
+  if (!want) {
+    // 头部插入：跳过开头的空行，避免把条目顶到文件最上面的空行之前
+    let at = 0
+    while (at < lines.length && lines[at].trim() === '') at++
+    lines.splice(at, 0, newLine)
+    return { ok: true, text: joinLinesPre(lines) }
+  }
+  // 找目标日期段，插到该段内最后一个非空行之后
+  let secAt = -1
+  for (let i = 0; i < lines.length; i++) {
+    if (RULE_DATE_SECTION_RE_V1.test(lines[i]) && lines[i].replace(/^##\s*/, '').trim() === want) { secAt = i; break }
+  }
+  if (secAt < 0) return { ok: false, error: 'date-section-not-found' }
+  let end = secAt + 1
+  while (end < lines.length && !RULE_DATE_SECTION_RE_V1.test(lines[end])) end++
+  let ins = end
+  while (ins > secAt + 1 && lines[ins - 1].trim() === '') ins--
+  lines.splice(ins, 0, newLine)
+  return { ok: true, text: joinLinesPre(lines) }
+}
+
+/**
+ * **预览**：把规则条目渲染成注入时会长的样子（R7-6）。
+ *
+ * 只做**只读**格式化，不引入 rules-layer.js 的其它依赖（避免循环 import 风险）。
+ */
+export function previewRulesPre(text) {
+  const items = listRuleItemsPre(text)
+  return items.map((x) => '- ' + x.text).join('\n')
+}
+
+/** 空规则段判定（给 UI 显示空态用）。 */
+export function isEmptyRulesPre(text) { return listRuleItemsPre(text).length === 0 }
+

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,
@@ -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'