sage-mem 2.1.14 → 2.1.15

package/README.md

@@ -12,7 +12,7 @@
 
 **Cross-session memory for DeepSeek Harness — plain markdown files, no database, no worker.**
 
-**Current release: `2.1.14`** — the npm badge above is the dynamic source of truth. **Contract baseline: `1.0.0`** — the first stable release, whose public commitments, the capability boundaries and the list of things it explicitly cannot do are frozen in the
+**Current release: `2.1.15`** — the npm badge above is the dynamic source of truth. **Contract baseline: `1.0.0`** — the first stable release, whose public commitments, the capability boundaries and the list of things it explicitly cannot do are frozen in the
 [frozen contract](https://github.com/gezi-wen/sage-mem/blob/main/docs/1.0.0-contract.md).
 
 If it is useful to you, a Star is the most direct feedback.

package/README.zh.md

@@ -14,7 +14,7 @@
 
 > File-based cross-session memory for DeepSeek Harness — every memory is a plain markdown file you can open, edit and delete. No database, no worker, no port.
 
-**当前发布版本：`2.1.14`** —— 顶部 npm 徽章是动态权威。**契约基线：`1.0.0`** —— 第一个稳定版，公开承诺、能力边界与「明确做不到」的清单冻结在
+**当前发布版本：`2.1.15`** —— 顶部 npm 徽章是动态权威。**契约基线：`1.0.0`** —— 第一个稳定版，公开承诺、能力边界与「明确做不到」的清单冻结在
 [契约冻结](https://github.com/gezi-wen/sage-mem/blob/main/docs/1.0.0-contract.md)。
 
 如果它对你有用，给个 Star 是最直接的反馈。

package/lib/memory/checkpoint.js

@@ -497,26 +497,22 @@ export async function writeCheckpoint(taskId, text, opts) {
 /** 注入用的短句柄硬上限（字节）。它要跟正文抢上下文，不能自己长起来。 */
 const HANDLE_MAX_BYTES = 160
 
-/** 按**码点**截断到不超过 maxBytes 字节：不许把一个字符切成半个（注入文本里会变 U+FFFD）。 */
-function truncateByBytes(s, maxBytes) {
-  if (Buffer.byteLength(s, 'utf8') <= maxBytes) return s
-  let out = ''
-  let used = 0
-  for (const ch of s) {
-    const b = Buffer.byteLength(ch, 'utf8')
-    if (used + b > maxBytes) break
-    out += ch
-    used += b
-  }
-  return out
-}
+/**
+ * 句柄里相对路径的**基准标记**：相对路径只说「相对谁」，不说清基准就是歧义的
+ * （去记忆目录里找？去状态根里找？）。生成与解析**共用这一个常量** ——
+ * 两边各写一份字符串，改了一边就会静默给出读不到的路径（Q12 的旧句柄正是这么坏的）。
+ */
+const HANDLE_BASE_MARK = '状态根下'
 
 /**
- * 注入用的短句柄（一行，≤ 160 字节）：说清「有这个检查点、revision 几、怎么读」。
+ * 注入用的短句柄（一行，≤ 160 字节）：说清「有这个检查点、revision 几、去哪读」。
  *
- * 预算是硬的，所以按优先级退化：**id 与 revision 不可丢**（它们才是身份），项目是可选线索
- * （放不下就截短或整个丢掉），最后连「重复一次 id 的完整相对路径」放不下时（64 字符的
- * 极端 id），退成不含重复路径的说法。绝不把多字节字符截半个。taskId 非法返回 ''。
+ * 预算是硬的，按优先级退化：**可解析路径与 revision 不可丢**，项目名是可选线索
+ * （放不下就整个丢掉），「续做前先读」是纯提示（再放不下就丢它）。taskId 非法返回 ''。
+ *
+ * ⚠️ **id 只出现一次**：完整相对路径 `tasks/<id>/WORKING.md` 已经含它了。
+ * 旧版在头部又重复了一遍 id，预算被耗光后退化成一条**不存在的路径**
+ * `tasks/WORKING.md`（2026-10-31 外部审查 Q12）—— 短了，但不再是准确的读取指令。
  *
  * revision 缺省按 0（与 renderCheckpoint 的缺省一致）。
  */
@@ -526,21 +522,43 @@ export function checkpointHandleText({ taskId, revision, project } = {}) {
   const rev = Number.isInteger(revision) && revision >= 0 ? revision : 0
   const proj = String(project ?? '').replace(/\s+/g, ' ').trim()
 
-  const head = `检查点 ${id}（revision ${rev}）：`
-  const detail = `读 tasks/${id}/WORKING.md`
+  // 身份只表达一次：id 在路径里，revision 在头部。
+  const head = `检查点 revision ${rev}：`
+  const rel = `${TASKS_DIR_NAME}/${id}/${CHECKPOINT_FILE_NAME}`
   const tail = '，续做前先读'
-  const build = (p) => `${head}${p === '' ? '' : `项目 ${p}，`}${detail}${tail}`
-
-  let line = build(proj)
-  if (Buffer.byteLength(line, 'utf8') > HANDLE_MAX_BYTES) {
-    // 项目放不下：按剩余预算截断它，截不下就整个丢掉。
-    const fixed = Buffer.byteLength(build(''), 'utf8')
-    const room = HANDLE_MAX_BYTES - fixed - Buffer.byteLength('项目 ，', 'utf8')
-    line = build(room > 0 ? truncateByBytes(proj, room) : '')
-  }
-  if (Buffer.byteLength(line, 'utf8') > HANDLE_MAX_BYTES) {
-    // 到这儿只剩「id 太长」一种可能：完整相对路径（id 出现两次）放不下，退成不重复的写法。
-    line = `${head}读 ${TASKS_DIR_NAME}/${CHECKPOINT_FILE_NAME}`
-  }
+  const build = (p, withTail) =>
+    `${head}${HANDLE_BASE_MARK} ${rel}${withTail ? tail : ''}${p === '' ? '' : `（项目 ${p}）`}`
+
+  let line = build(proj, true)
+  if (Buffer.byteLength(line, 'utf8') > HANDLE_MAX_BYTES) line = build('', true)
+  if (Buffer.byteLength(line, 'utf8') > HANDLE_MAX_BYTES) line = build('', false)
+  // 到这儿只剩「revision 是天文数字」一种可能，合法整数不会触发。宁可给一条超长句柄，
+  // 也不截断路径：截出来的路径定位不到真实文件，比多占几个字节更糟。
   return line
 }
+
+/**
+ * 从短句柄里解析回检查点身份（生成规则见 `checkpointHandleText`）。
+ *
+ * 为什么需要它：句柄是**给模型执行的读取指令**，必须能被机器核对「它说的是不是真实文件」。
+ * 旧版退化成 `读 tasks/WORKING.md`，字节数达标、也含 id —— 只断言「≤160 字节 + 包含 id」
+ * 的测试正是这么放它过去的。断言要看的是**用同一解析规则能不能定位到真实文件**。
+ *
+ * 解析要求基准标记 + `tasks/<id>/WORKING.md`：没有基准的裸相对路径是歧义的，按失败处理。
+ *
+ * @param {string} text
+ * @returns {{taskId: string, revision: number} | null}
+ */
+export function parseCheckpointHandle(text) {
+  if (typeof text !== 'string') return null
+  const file = CHECKPOINT_FILE_NAME.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const re = new RegExp(
+    `检查点\\s+revision\\s+(\\d+)[：:]\\s*${HANDLE_BASE_MARK}\\s+${TASKS_DIR_NAME}/([A-Za-z0-9._-]{1,64})/${file}`,
+  )
+  const m = text.match(re)
+  if (!m) return null
+  const id = normalizeTaskId(m[2])
+  if (id === null) return null
+  const revision = Number(m[1])
+  return Number.isSafeInteger(revision) ? { taskId: id, revision } : null
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sage-mem",
   "description": "Cross-session memory for DeepSeek Harness — plain markdown files, no database, no worker.",
-  "version": "2.1.14",
+  "version": "2.1.15",
   "type": "module",
   "main": "lib/index.js",
   "icon": "./icon.png",