@modusensus/dsh-mneme 0.8.16 → 0.9.0

package/README.md

@@ -5,7 +5,7 @@
 [![npm version](https://img.shields.io/npm/v/@modusensus/dsh-mneme?color=blue&label=npm)](https://www.npmjs.com/package/@modusensus/dsh-mneme)
 [![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 [![Awesome](https://awesome-dsh-plugin.com/badge.svg)](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)
-[![tests](https://img.shields.io/badge/tests-1695%20passed-success)](https://github.com/slow-stack/mneme)
+[![tests](https://img.shields.io/badge/tests-1869%20passed-success)](https://github.com/slow-stack/mneme)
 [![CI](https://img.shields.io/github/actions/workflow/status/slow-stack/mneme/ci.yml)](https://github.com/slow-stack/mneme/actions)
 [![node](https://img.shields.io/badge/node-22%2B-blue)](https://nodejs.org)
 [![npm downloads](https://img.shields.io/npm/d18m/@modusensus/dsh-mneme.svg?color=blue&label=downloads)](https://www.npmjs.com/package/@modusensus/dsh-mneme)
@@ -390,6 +390,7 @@ dsh web
 | `reflectionFailureTracking` | `true` | 失败追踪总开关 |
 | `reflectionUpdateMaxPerRun` | `2` | 每次整理最多 update 数 |
 | `reflectionUpdateMinAgeHours` | `24` | 新建记忆保护期（小时） |
+| `reflectionFailureRetentionDays` | `90` | 失败表（`failure_memories`）启动期清理保留天数（1-3650；此前写死 90） |
 | `codingRetrospect` | `false` | 编码记忆蒸馏（v0.7.13，默认关）：完整转录提炼编码原子记忆（rejected_solution/pitfall/constraint 三类型） |
 | `codingKeywords` | 内置词表 | 编码任务识别词表（读取侧门控）：命中即视为编码类任务，编码记忆才注入 |
 | `codingBoostFactor` | `2` | 编码记忆注入排序的 boost 倍数（1-5） |
@@ -617,7 +618,7 @@ src/
 ├── api.js            # HTTP 路由（Web 面板数据通道，含 /conflicts 冲突队列）
 └── index.js          # 插件接线
 lib/                  # src 的同步分发产物（npm run sync；发布前由 root prepack 的 check-sync.js 校验一致性；唯一手写例外 lib/client.js——Web 面板 bundle，sync 不覆盖）
-test/                 # 1695 个 node:test 测试（审计与三轴线压测不变量；src↔lib 一致性由 scripts/check-sync.js 发布闸门校验）
+test/                 # 1869 个 node:test 测试（审计与三轴线压测不变量；src↔lib 一致性由 scripts/check-sync.js 发布闸门校验）
 scripts/              # e2e-dsh.js 端到端演示 · stress-dsh.js 三轴线压测 · sync-lib.js 同步 · check-sync.js 发布闸门 · benchmark-recall.js / benchmark-embed.js / benchmark-rerank.js 基准 · sync-test-badge.mjs 测试徽章 · build-runtime-manifest.mjs 运行时清单
 ```
 
@@ -626,7 +627,7 @@ scripts/              # e2e-dsh.js 端到端演示 · stress-dsh.js 三轴线压
 ```bash
 cd dsh-mneme
 npm install        # 安装 peer 依赖（以 devDependencies 形式，用于本地测试）
-npm test           # 运行 1695 个测试
+npm test           # 运行 1869 个测试
 npm run stress     # 三轴线压测：长会话检索 / 冲突仲裁 / 多 Agent 并发（离线 mock LLM）
 npm run sync       # 把 src/ 同步到 lib/（发布时由 prepack 钩子自动执行）
 ```
@@ -655,6 +656,18 @@ autoDream 的理念溯源（理念借鉴、实现原创）：
 
 在上述工作之上，dsh-mneme 做了自己的工程发展：K-Means++ 聚类预分组（`src/dream/clustering.js`）、类型化决策清单（keep / merge / archive / conflict / update，及 sleep 侧 supersede / differentiate）与可回放的 sha256 摘要审计链（`dream_runs` / `receipt_chain`）。如有遗漏的灵感来源，欢迎提 issue 指出。
 
+## 📚 相关研究
+
+dsh-mneme 的机制设计与下列公开研究相互印证（以下引用均逐一核对过 arXiv 收录页；机制对应关系为我们自己的映射，非原论文观点）：
+
+- **在线写入 + 离线巩固**：[Dual-Layer Agentic Memory with Fast Write Routing and Slow Consolidation](https://arxiv.org/abs/2608.22215)（arXiv:2608.22215）——与 autoDream 的「快写慢巩固」分工同构。
+- **热度衰减与访问强化**：[FadeMem](https://arxiv.org/abs/2601.18642)（arXiv:2601.18642）——heat 记忆热度模型（指数衰减 × 访问强化 × 重要性调制）的学术近亲。
+- **冲突裁决与状态追踪**：[StateMemBench](https://arxiv.org/abs/2608.19652)（arXiv:2608.19652）——记忆系统追踪演化状态的考卷；C1 冲突裁决（supersede 后不再引用旧值）以其为验收靶子。
+- **何时该忘 / scope 门控**：[PersistBench](https://arxiv.org/abs/2602.01146)（arXiv:2602.01146）；呈现层缓解见 [Structured Memory](https://arxiv.org/abs/2608.08300)（arXiv:2608.08300）——scope 语义域门控的问题出处与零契约变更改法。
+- **领域全景**：[Write–Manage–Read 综述](https://arxiv.org/abs/2603.07670)（arXiv:2603.07670）——「写入 / 管理 / 读取」三段式与插件整体形状互证。
+- **数月尺度的可靠性工程**：[Memory as Infrastructure](https://arxiv.org/abs/2609.05510)（arXiv:2609.05510）——与 sha256 审计链、fail-safe 降级同属「记忆即基础设施」路线。
+- **相邻系统（对照）**：[Zep](https://arxiv.org/abs/2501.13956)（时序知识图谱）、[Mem0](https://arxiv.org/abs/2504.19413)（生产级抽取式记忆）、[Hindsight](https://arxiv.org/abs/2512.12818)（retain / recall / reflect 三操作）走「写入时 LLM 抽取 + 向量/图检索」路线；dsh-mneme 的差异点在于：巩固由 LLM 参与但产物全程留痕可回放，冲突冻结待人工复核，默认离线。
+
 ## 📜 License
 
 MIT

package/assets/icon.svg

@@ -1,3 +1,3 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="48" height="48" viewBox="0 0 16 16" fill="none" stroke="#4176e6" stroke-width="1" stroke-linecap="round" stroke-linejoin="round">
-  <path d="M4.43 12.31C2.19 10.17 2.27 6.81 4.18 4.84C6.10 2.88 9.06 2.99 10.74 4.68C12.43 6.37 12.28 8.92 10.82 10.33C9.35 11.74 7.22 11.55 6.08 10.32C4.95 9.08 5.18 7.35 6.18 6.50C6.57 6.17 7.03 5.99 7.48 5.97"/>
+<svg xmlns="http://www.w3.org/2000/svg" width="48" height="48" viewBox="0 0 16 16" fill="none" stroke="#718AA3" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+  <path d="M12 18V5M15 13a4.17 4.17 0 0 1-3-4 4.17 4.17 0 0 1-3 4M17.598 6.5A3 3 0 1 0 12 5a3 3 0 1 0-5.598 1.5M17.997 5.125a4 4 0 0 1 2.526 5.77M18 18a4 4 0 0 0 2-7.464M19.967 17.483A4 4 0 1 1 12 18a4 4 0 1 1-7.967-.517M6 18a4 4 0 0 1-2-7.464M6.003 5.125a4 4 0 0 0-2.526 5.77" transform="scale(0.666667)"/>
 </svg>

package/docs/CONFIGURATION.md

@@ -25,7 +25,7 @@
 
 | 键 | 默认 | 作用 | 开启后果 / 冲突 |
 |---|---|---|---|
-| `scopeEnabled` | `false` | 存储层总开关：写入标注 agent_scope / workspace_scope，去重键扩展；检索与注入排序按当前会话作用域加权（命中 ×1.25、他 scope ×0.5 保留可见，issue #339 补齐注入通道） | opt-in；关 = 写入不标注、行为与 A1 前逐字节一致 |
+| `scopeEnabled` | `false` | 存储层总开关：**两条写入路径**（工具调用 `memory_save`/`memory_update`，以及机器提炼·会话蒸馏）都自动标注 agent_scope / workspace_scope（标注只贴**新建行**：并入既有行时不重贴，既有行的归属属于它原来被提炼出来的语境），去重键扩展；检索与注入排序按当前会话作用域加权（命中 ×1.25、他 scope ×0.5 保留可见，issue #339 补齐注入通道） | opt-in；关 = 写入不标注、行为与 A1 前逐字节一致 |
 | `strictScope` | `false` | 硬过滤模式（A3）：他 scope 完全不可见、未标注恒可见（fail-closed）；硬过滤先于软加权执行 | 依赖 `scopeEnabled` 打开才有意义；关 = A2 软隔离（他 scope 降权保留可见，检索与注入同权重） |
 
 ## 审计
@@ -175,6 +175,7 @@
 | `reflectionFailureTracking` | `true` | 失败经验追踪 | — |
 | `reflectionUpdateMaxPerRun` | `2` | 单轮 update 上限（0–5） | — |
 | `reflectionUpdateMinAgeHours` | `24` | 可更新记忆的最短年龄（小时，≤168） | — |
+| `reflectionFailureRetentionDays` | `90` | `failure_memories`（失败/纠正记录）的启动期清理保留天数（1–3650） | 只读 bundle 配置：未进 feature_flags 白名单，面板改不了。`dsh-mneme reclaim` 不读这个键（它对三个表用同一条 `--older-than`，本表不在其中）。此前这个 90 天是写死的（#275 伞下的欠账） |
 | `conflictFreezeEnabled` | `false` | 冲突不自动合并、冻结待人工复核 | opt-in |
 | `conflictFreezeMaxPending` | `100` | 冻结队列上限（≤1000） | — |
 

package/docs/CONTINUITY.md

@@ -31,9 +31,24 @@ Next Step / Critical Context 等），**系统提示段里的东西不进这次
 
 ## 3. 触发
 
-**不自定阈值**，就是订阅宿主真的压缩：`compaction/start` / `compaction/summary` /
-`compaction/end`（都在宿主的事件白名单里）。理由：「压缩边缘」由宿主定义，我们再校准
-一份阈值参数只会与之漂移，还多一份没人维护的旋钮。
+**不自定阈值**，就是订阅宿主真的压缩（都在宿主的事件白名单里）。理由：「压缩边缘」由宿主
+定义，我们再校准一份阈值参数只会与之漂移，还多一份没人维护的旋钮。
+
+**但「发过压缩事件」不等于「这段历史真的被折叠了」**：宿主的压缩插件在**每一步**都会试一次
+（`agent/pre-step` 里的 `compactIfNeeded`），而代理层（如 billion-context）会拒掉原生压缩。
+一次失败的尝试什么都没折叠，不需要抢救 —— 按「试过就救」记账，触发器就退化成「每步一次」。
+所以只认**内容真的被移除过**的三种事件（判定在 `src/continuity.js` 的 `isCompactionEdge`）：
+
+| 事件 | 算不算边缘 | 为什么 |
+|---|---|---|
+| `compaction/summary` | ✅ | 宿主压缩成功才落（`dsh-compaction-basic` 的 `commitCompactionBody`） |
+| `compaction/prune` | ✅ | 宿主把超预算的旧 tool/result 折叠出表面 —— 「表面真的变短了」最直接的证据 |
+| `compaction/end` **不带 error** | ✅ | 成功路的收尾 |
+| `compaction/end` **带 error** | ❌ | 成败两条路都发这个事件，失败路额外带 `error`；整笔事务失败 |
+| `compaction/start` | ❌ | 只是开锁标记（「有人试过」） |
+
+本机实测（2026-10-14，两个长会话、12,000+ 事件，原生压缩被 100% 拒绝）：按 `start|summary|end`
+记账置位 1,287 / 2,895 次，改成「真落地」后降到 39 / 161 次。
 
 DSH 没有 in-memory 消息改写钩子，所以本机制一律是「注入 + 序号引用寻址」，**不改写
 历史消息本体**。

package/docs/WORKFLOWS.md

@@ -0,0 +1,299 @@
+# dsh-mneme 工作流（M.O. · 手法）——本体住项目，证据住记忆库
+
+- **日期**：2026-10-15
+- **状态**：🚧 第一刀（项目级读侧 + 条目清单；执行侧未做）
+- **范围**：把「做法」从记忆库里的一行文字，变成项目里可提交、可 review、可被 CI 读的一份文件
+- **相关文档**：[配置参考](CONFIGURATION.md) · [蒸馏与溯源](DISTILL.md) · [存储与回收](STORAGE.md)
+
+## 1. 问题
+
+记忆库解决的是「这件事**为什么**这么办」——一条教训、一个决定、一次否决，都带着出处。
+但它答不了另一个问题：**这件事到底怎么跑。**
+
+「怎么跑」现在活在三个地方，哪一个都不是它该在的地方：宿主会话里的临时提示、某个 agent
+的系统提示词、以及人的记忆里。三者有同一个毛病——**改不动，也不留痕**：改了没人知道你改了什么，
+没改也没人知道它已经过时了。
+
+## 2. 住址：为什么是**项目**的仓库，不是插件包
+
+工作流是要**跑**的东西，所以它得住在一个能跑它的地方：
+
+| 要求 | 记忆库 | 项目仓库 |
+|---|---|---|
+| 能提交、能 diff、能整版回退 | ✗（表里改一行，没有 diff） | ✓ |
+| 能 PR、能 review、能拦在合并前 | ✗ | ✓ |
+| 能被 CI 读 | ✗ | ✓ |
+| 记「为什么这么定」 | ✓ | ✗（注释装不下证据） |
+| 记「跑得怎么样」 | ✓ | ✗ |
+
+结论是一句话：**记忆是「为什么」，仓库是「怎么跑」，图是「看起来怎么样」。**
+三者不下同一张桌子——把工作流塞进记忆库，它会长成一份死文档；把证据塞进仓库，
+它会变成一摊没人维护的注释。
+
+**第二句话是「哪个仓库」。** 第一版把住址写成了 `dsh-mneme/pipelines/`，也就是**插件包自己**
+的目录，于是不管在哪个项目、哪个会话打开，读到的都是同一套——「项目级」这个词当时根本没落地。
+插件是**工具**，它的目录跟着人走遍所有项目；工作流是**这个项目的做法**，不该跟着人走。
+所以住址是项目，插件包那份降级为兜底的「全局层」。
+
+这条不是口味问题。本机 7,647 条记忆里带 `workspace_scope` 的只有 227 条（≈3%），活跃的
+2,629 条里 2,517 条（95.7%）为空——「全局」实际上变成了谁都不看的杂物堆。默认全局等于
+把一条本地规约推给所有项目，会原样重演这一幕。
+
+## 3. 形态：一条工作流一个 JSON，两层来源
+
+```
+<项目>/.mneme/pipelines/<id>.json     ← 项目层（默认；跟着项目提交、能 review）
+<插件包>/pipelines/<id>.json          ← 全局层（兜底；今天包里没有这个目录，这是有意的）
+```
+
+读的时候**项目层在前、全局层在后，顺序即优先级**。同一条 `id` 两处都有，项目层赢，
+被挡住的那份进 `shadowed` 报出来——不静默丢弃，否则以后有人往全局层加一条同名工作流，
+会去翻文件系统而不是查这条遮蔽记录。
+
+跨项目复用是一个**要留痕的显式动作**（把文件放进那个项目的 `.mneme/pipelines/`），不是默认行为。
+
+为什么不是 YAML：本包运行时依赖只有 `morphicons` 一个，为一个配置文件引 YAML 解析器不划算；
+手写子集解析器则是给未来埋一个「读起来对、跑起来错」的坑。人读的形态交给面板渲染，
+不靠文件格式。
+
+```jsonc
+{
+  "id": "dsh-mneme-release",        // 小写 kebab
+  "name": "dsh-mneme 发版",
+  "project": "slow-stack/mneme",    // 作者声明的归属；与「从哪一层读出来」是两件事
+  "version": 0,                     // 从 0 起；回写是新版本，不是改旧版本
+  "status": "active",               // draft / active / retired（退役不删文件）
+  "done": "整条怎么算完成",
+  "trigger": [{ "kind": "phrase", "value": "发版" }],
+  "inputs": ["版本号"],
+  "steps": [
+    {
+      "id": "P1", "phase": "准备", "title": "确认在哪个分支上",
+      "when": "开始发版之前", "do": "git branch --show-current",
+      "who": "main",                // main / subagent / human / ci
+      "tool": "git",
+      "done": "分支名与预期一致",
+      "risk": "R1",                 // R0–R3，一步跨多档按最高档
+      "needs": [],                  // 依赖的步骤 id
+      "why": "为什么要有这一步",
+      "evidence": ["反事实对照：没有它，这次会不会失败"],
+      "gate": false                 // true = 闸门，图上会显出来
+    }
+  ]
+}
+```
+
+校验很硬：**任何一处不合规就整条读不出来**，不做「跳过坏文件继续」。半个工作流比没有
+工作流更危险，因为它会被当成完整的跑。
+
+一处例外：**项目层的坏文件不拖死全局层**。它进 `unreadable`（带 `scope` / `dir` / `detail`，
+`detail` 里点名是哪个文件），其余照读；全局层是自家发出去的包，坏了照抛。
+
+## 4. 对外接口
+
+```
+GET /api/dsh-mneme/pipeline                       # 全局层；包里没有 pipelines/，所以通常为空
+GET /api/dsh-mneme/pipeline?project=<绝对路径>     # 该项目的清单（项目层优先）
+GET /api/dsh-mneme/pipeline?project=…&id=<id>     # 指定一条
+
+GET /api/dsh-mneme/candidates?project=<绝对路径>   # 该项目的**候选**（见 §9）
+```
+
+两条路由读的是**两处不同的东西**，别混：`/pipeline` 读定稿（住仓库），
+`/candidates` 读候选（住本地）。分开是刻意的，理由见 §9。
+
+**`project` 必须是绝对路径**，否则回 `400 {"error":"project-not-absolute","detail":"…"}`。
+忽略了它就会静默退成「全局」，而全局看起来一切正常——那正是这一版要修掉的那类错。
+
+项目根由**客户端从会话里读出来带过去**（`ctx.get("sessions")` 的 `header.cwd`），不是服务端猜的：
+插件侧的 `ctx` 上只有 `logger` / `llm` / `reflect` / `webServer` / `inject` / `commands`，
+没有 cwd。取不到时**返回 null 并如实标「项目未知」，绝不回退 `process.cwd()`**——回退会把
+「读不到」变成「读到别处」，而后者在界面上看不出来。
+
+只读，刻意不做功能旗标闸门：旗标管的是**客户端座位**（关 = 一个座位都不注册），不是数据面；
+多一个只读端点不会让任何人看见它，而给它加闸门只会让「为什么面板打不开」多一种成因。
+
+整个目录读不出来时回 `500` + `{"error":"pipeline-unreadable","detail":"…"}`。工作流是人手写的
+JSON，报错本身就是给人看的：`detail` 里是校验器**一次列全**的问题清单，说清哪一条、坏在哪，
+而不是回一句 internal 让人去翻日志。
+
+答复的契约是 `mneme.pipeline/v1`——**前端渲染与 agent 读的是同一份数据**，画面只是它的投影。
+只画不存，agent 就什么也读不到。
+
+```
+{ "contract": "mneme.pipeline/v1",
+  "pipeline": { "id", "title", "scope", "scopeLabel", "project", "file", "status",
+                "version", "done", "trigger", "inputs", "updatedAt" },
+  "nodes": [ { "id", "kind", "title", "phase", "situation", "action", "why",
+               "who", "tool", "done", "risk", "state", "credit",
+               "counterfactual", "source" } ],
+  "edges": [ { "id", "from", "to", "kind", "label" } ],
+  "runs": [],
+  "sources": [ { "scope": "project", "label": "mneme", "dir": "…", "present": true },
+               { "scope": "global",  "label": null,     "dir": "…", "present": false } ],
+  "available": [ { "id", "title", "scope", "scopeLabel", "project", "status", "file",
+                   "done", "trigger", "steps", "gates", "contrast", "states" } ],
+  "shadowed": [ { "id", "hidden", "by" } ],
+  "unreadable": [ { "scope", "dir", "detail" } ] }
+```
+
+`scope` 是**从哪儿读出来的**，不是作者写的：同一条文件放进项目层就是项目级。
+`scopeLabel` 只取项目目录名——绝对路径里有本机用户名，而面板是会被截图的那一面。
+
+`available` 是清单页的**全部输入**：够渲染「名字 + 一句话 + 状态 + 作用域 + 规模」，
+不必先把整张图读出来。其中 `contrast` 是带反事实对照的步骤数——19/19 与 6/19 是两条
+完全不同的工作流，第一屏就该看得出来。
+
+`kind` 是画法，不是第二套数据：`gate`（闸门，这里会停下）／`branch`（有多个上游汇进来）／
+`step`。三者都由步骤自己的 `gate` 与 `needs` 推出来，没有额外字段。
+
+## 5. 状态是推出来的，不是写上去的
+
+节点状态四值，全部由**运行记录**推：
+
+| 状态 | 什么时候 |
+|---|---|
+| `refuted` | 被推翻过（有一次算一次，最扎眼） |
+| `trusted` | 用过、没砸，且距今不超过 90 天 |
+| `stale` | 有记录但久未使用（> 90 天），或被跳过 ≥3 次 |
+| `candidate` | 没有任何记录 |
+
+**没有运行记录时，全体是 `candidate`。** 这是实话，也正是面板上那句 beta 免责必须摆在
+脸上的原因：一张全是候选的图不说明这套做法不管用，只说明它还没被对照过。
+
+每一步的处置有**三种**，计数各自独立（谁都不冒充谁）：
+
+| 处置 | 含义 | 推动什么 |
+|---|---|---|
+| 走了 | 照图执行 | 信用曲线的分子 |
+| **跳过** | 这一步**这次**不用（图上还在） | 跳过 ≥3 次 → 提议删掉**这一步** |
+| **绕开** | 从这一步岔出去走了图上没有的路 | 绕开 ≥3 次 → 提议重看**这条路径** |
+
+「跳过」与「绕开」的区别是这一版的核心：**跳过 = 这次不用；绕开 = 这条路整个不对。**
+只有绕开才动「路径」那一层。两者混在一起数，两种提议就都发不出来。
+
+**绕行不给节点染色。** 被绕开不等于这一步坏了（可能只是这次不需要），所以它只累加计数、
+不改状态。染色留给真正被推翻过的 `refuted`——那是唯一有硬判据的信号。
+
+`counterfactual` 装的是**准入判据**（「没有它，这次会不会失败」），不是备注：答不出对照的步骤，
+在图上要显得比答得出的虚。
+
+## 6. 内部文件
+
+| 文件 | 干什么 |
+|---|---|
+| `src/pipeline.js` | 两层来源 → 读盘 → 校验 → 投影，零运行时依赖 |
+| `<项目>/.mneme/pipelines/*.json` | 工作流本体（**不进包**，见 §7） |
+| `lib/client.js` 的 M.O. 段 | 清单 + 图：会话头图标、会话头浮层、右栏 tab、对话行结算卡，四个座位读同一份投影 |
+
+## 7. 已知坑
+
+- **`pipelines/` 不许进 `package.json` 的 `files`**。第一版写反了：那时住址是插件包，
+  必须进包才读得到；现在住址是项目，进包就意味着**装完之后每个项目都能读到它**，
+  「项目级」又悄悄退回全局级——而这一幕在任何一次本地测试里都看不出来，因为测试读的是
+  仓库目录（`test/pipeline.test.js` 两头都锁）。
+- **`project` 参数被忽略比被拒绝危险得多**。忽略 → 静默读全局 → 面板看着一切正常；
+  拒绝 → 一条 400，谁都得面对。所以路由写死「不是绝对路径就 400」。
+- **`needs` 指向不存在的步骤、图里有环，都在校验期报错。** 环的提示是「回写是新版本，
+  不是回到自己」——这是最容易犯的一个：想把「发现要改」连回前面某一步。
+- **`lib/client.js` 是唯一手写处，没有 `src/` 对应物**，所以它不进 `npm run sync`；
+  改完直接 `node --check`。
+- **四个座位读的必须是一份缓存**（按项目 + 按工作流分桶）。分家的事故长这样——会话头说有
+  3 条、右栏说有 5 条，两个数字都对，没人查得出来；不分桶则是把 A 项目的清单端给 B 项目看，
+  而画面同样看不出错（`test/client.test.js` 有锁）。
+- **清单与图必须是两个组件**，不能在一个组件里按 `openId` 分支：hook 不能条件调用，
+  那样写会在点开那一下炸成「Rendered more hooks than during the previous render」，
+  运行期才看得见。
+- **面板第一版是硬编码假数据**（`PIPELINE_MOCK`）。接上真数据之后那份常量已经删掉，
+  测试锁的就是「它不再出现」：留着它，面板随时可能退回展示一份并不存在的工作流。
+
+---
+
+## 8. 还没做的
+
+- **执行侧**：今天只有读侧。触发、拆子 agent、接进 CI/CD 都还没做。
+  所以 §9 的绕行**只有判定与落账的代码，没有触发它的地方**——提议与批准的动作也还没有落点。
+- **运行记录的写入**：「哪一次跑走过了哪几步」还没有落点，所以状态目前恒为 `candidate`。
+- **画布观感**：清单这一屏先落地；图那部分还是能看、不好看。
+- **记忆侧的对照表**：`source.memoryIds` 是留给本机的一个口子（记忆 id 是本机私有数据，
+  不进仓库文件），今天还没有人填它。
+
+---
+
+## 9. 绕行与候选分层：图上没有的路，留一个出口
+
+### 9.1 为什么要有出口
+
+一张只会被照着走的图，会让 agent 失去自主性——它要么**沉默地服从**（照着走，做错了也不知道
+错在哪），要么**沉默地偏离**（觉得不适用就跳了，不记账，没人知道这次执行了几成）。
+
+一条规矩如果没留出口，走不通的人不会遵守它，会**自己凿一个，而且不告诉你**。
+所以图上必须有一扇**合法的逃生门**：agent 可以判断「这条路这次可能不对」，然后
+按风险档决定是记账先走，还是停下问人。
+
+分界是一句话：**护栏，不是轨道**——允许偏离，但偏离要**响**。
+
+### 9.2 分档（自主性住在 R0/R1）
+
+| 情形 | 谁决定 | 行为 |
+|---|---|---|
+| 自报 R0/R1 **且**不跨闸门 **且**兜底清单没命中 | `model` | **记账先走** |
+| 其余 | `human` | **停下等点头** |
+
+三条各自独立、都要过：
+
+1. **风险档**——这是模型自报的，单靠它不够。
+2. **兜底清单**（`IRREVERSIBLE_PATTERNS`）——机械匹配，**不看自报**。自报说 R0 但命令里有
+   `git push`，照样拦。这是「模型在自己上下文里给自己打分不可靠」的直接应用：
+   不是不信任，是**不给单点判断**。清单可审计、可 diff、可追责；让模型再判一次
+   只是把同一个错误问两遍。
+3. **闸门保护**——这条绕行如果走下去，图上某个 `gate` 会不会永远不被经过？会就拦住。
+   **与风险档无关**：闸门本来就放在「错了很难撤」的地方，绕开它等于把安全阀绕掉，
+   哪怕这条绕行本身全是只读动作。
+
+### 9.3 住址：候选不进仓库
+
+```
+<项目>/.mneme/pipelines/<id>.json              定稿（进仓库、可 review、可回退）
+<memoryDir>/candidates/<项目键>/<id>.json       候选（只在本地，永不进仓库）
+```
+
+候选是草稿，一天可能长十条、死掉九条；进仓库就是垃圾，也会被当成规程引用。
+**候选是定稿的唯一入口，而定稿只放人亲手批过的东西。**
+
+`<项目键>` 取「目录名 + 路径哈希前 8 位」：同一个项目每次算到同一个键，
+但**不把绝对路径写进文件名**（那里面是本机用户名）。
+
+### 9.4 升格：跑通一次 ≠ 够格
+
+两条都要满足：
+
+1. **走过两次**（至少一次 `worked`）——「复用第二次才算类型，第一次只是实例」；
+2. **写得出反事实**（「没有它，这次会不会失败」）——写不出来，它就还是实例。
+
+够格之后系统**提议**，不自己写进仓库：提交是 R1、推送是 R2，分开两档，人始终握着一道。
+
+`promoteCandidate()` 只**返回内容、不写盘**，而且补出来的东西照样要过
+`validatePipeline`——**升格不是降低标准，是补齐标准**。
+
+### 9.5 怎么死
+
+- 只走过 1 次、30 天内没再被走到 → 归档（`status: dropped`，**文件留着**当负清单的邻居）
+- 走不通的（`outcome: failed`）→ 直接进「走不通」那一栏，仍是知识，留痕
+- 人否掉 → `status: dropped` + 记否决理由
+
+**候选不需要人维护。** 它只增不减地长，死掉的是「没被再走到」的那些，
+不是「没人管」的那些。
+
+### 9.6 这一节**不做**的事
+
+写在契约的 `boundaries` 里，免得以后有人以为忘了做：
+
+```jsonc
+{ "autoPromote": false, "autoApprove": false, "injectIntoMemory": false }
+```
+
+- **不做自动升格**：跑通两次只是「够格被提议」，不是「自动进图」
+- **不做绕行的自动批准**：一律 R0/R1 记账先走、R2/R3 停下问人，没有「全都可以先走」
+- **不把候选塞进注入路径**：它是草稿，不是知识
+- **不做「图自动重写」**：图的变化一律经过提议 + 人批；回写是新版本，不是改旧版本

package/lib/api.js

@@ -1,16 +1,19 @@
 import { URL } from "node:url";
+import { isAbsolute } from "node:path";
 import { timingSafeEqual, randomBytes } from "node:crypto";
 import { FEATURE_FLAG_SPEC } from "./settings.js";
 import { TYPES } from "./store.js";
 import { TYPE_FILE, renderMirrorText, renderFileHeader, parseHumanEdits, MIRROR_READONLY_TYPES } from "./mirror.js";
 import { langOf } from "./lang.js";
 import { computeHeat } from "./heat.js";
-import { describeStreamFailure, resolveRoute } from "./dream.js";
+import { EFFORT_REJECT_RE, describeStreamFailure, resolveRoute, withEffortFallback } from "./dream.js";
 import { getInjectionSnapshot } from "./inject.js";
 import { describeLocalRuntime, publicRuntimeStatus } from "./runtime/loader.js";
 import { hostModulesDir, provisionRuntime } from "./runtime/provision.js";
 import { classify, fetchLatestVersion, PACKAGE_VERSION } from "./version-check.js";
 import { parseReclaimQuery, parseReclaimJson, readReclaimFields, reclaimReply, RECLAIM_UNAVAILABLE } from "./reclaim-http.js";
+import { readPipelineDoc } from "./pipeline.js";
+import { readCandidateDoc } from "./candidates.js";
 
 // headers：少数端点（/export 附件下载）需要追加 Content-Disposition 等响应头。
 function sendJson(res, status, payload, headers = {}) {
@@ -376,13 +379,30 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   // the same error wording the audit rows carry. Optional reasoningEffort
   // mirrors what the consolidation would send — the panel can verify a model
   // actually accepts the configured effort without tripping a full run.
+  //
+  // 档位被拒时探针必须和真实 run 一样降级：这里是全仓唯一「接受并转发调用方档位、
+  // 却此前没有兜底」的调用面——巩固/睡眠/蒸馏/总览/实体抽取都包在 withEffortFallback
+  // 里，档位被拒就丢掉字段重试一次（issue #9/#109/#135）。直调 llm.stream 的其余各面
+  // 要么本来就在兜底之内（dream.js/summarize.js/sleep.js 的共用辅助），要么是
+  // src/index.js 的手写版兜底，要么像 pre-inject-gate 的判定池那样根本不转发档位。
+  // 探针原先没有这层，于是同一份配置「后台真的跑得通、点一下测试就报红」，把用户
+  // 引向「换哪家 Provider 都失败」的错误诊断（issue #215 的后续）。降级跑通后响应带
+  // effortDropped:true，面板据此说明「档位不被接受、已按无档位连通」，而不是与「真的
+  // 连不上」同色。
   async function testLlmConnectivity(llm, provider, model, reasoningEffort) {
     const startedAt = Date.now();
     const elapsed = () => Date.now() - startedAt;
     const modelId = `${provider}:${model}`;
-    try {
+    // 流级失败原因：withEffortFallback 只用它做拒收甄别，回给面板的仍是同一条
+    // describeStreamFailure 文案（与审计行同口径，不制造第二套措辞）。
+    let streamError = "";
+    // 降级标记刻意放在 attempt 之外：fallback 里置位、attempt 里读出，结果对象
+    // 据此带上 effortDropped——降级是「换个姿势跑通了」，不是失败。
+    let droppedEffort = false;
+
+    const attempt = async (effort) => {
+      streamError = "";
       let reply = "";
-      let error = "";
       for await (const chunk of llm.stream({
         provider,
         model,
@@ -391,7 +411,7 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
         // reply 恒为空，「真的答了 ok」对思考模型不成立。按实际用量计费，手动
         // 按钮无放大风险。
         maxTokens: 1024,
-        ...(reasoningEffort && reasoningEffort !== "none" ? { reasoningEffort } : {}),
+        ...(effort && effort !== "none" ? { reasoningEffort: effort } : {}),
         // role 用 user 而非 system（#189 后续）：0.1.6-alpha.1 起适配器把 system
         // 抽成顶层参数，system-only 对话会被官方 API 以
         // 「messages: at least one message is required」整单拒绝——探测按钮 502。
@@ -406,12 +426,39 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
       })) {
         if (chunk.type === "text-delta" && typeof chunk.text === "string") reply += chunk.text;
         if (chunk.type === "finish" && (chunk.reason?.kind === "error" || chunk.reason?.kind === "aborted")) {
-          error = describeStreamFailure(chunk.reason);
+          streamError = describeStreamFailure(chunk.reason);
           break;
         }
       }
-      if (error) return { ok: false, durationMs: elapsed(), error, modelId };
-      return { ok: true, durationMs: elapsed(), modelId, reply: reply.trim().slice(0, 100) };
+      const dropped = droppedEffort ? { effortDropped: true } : {};
+      if (streamError) {
+        // 只在「确实带了档位」时把流级拒收交回给 withEffortFallback 的 undefined
+        // 分支——rc.1 的适配器不抛错，把 provider 的拒收折叠成终止 finish chunk，
+        // 不看这里那次重试就是死代码。不带档位时原样上报：探针不该因为一句文案
+        // 没匹配上正则就退化成 500。
+        if (effort && effort !== "none" && EFFORT_REJECT_RE.test(streamError)) return undefined;
+        // 失败行不带 effortDropped：该字段只有一个含义——「连通了，但不是用你配的
+        // 档位连通的」（见下方成功分支的注释），失败时它只是噪音。
+        return { ok: false, durationMs: elapsed(), error: streamError, modelId };
+      }
+      return { ok: true, durationMs: elapsed(), modelId, reply: reply.trim().slice(0, 100), ...dropped };
+    };
+
+    try {
+      const result = await withEffortFallback(
+        ctx,
+        reasoningEffort,
+        () => attempt(reasoningEffort),
+        () => { droppedEffort = true; return attempt(""); },
+        () => streamError
+      );
+      // result === undefined 只可能来自上面那次「判据一致」的主动交还（两边用同
+      // 一份 EFFORT_REJECT_RE，走到这里等于假设被推翻）：退回已捕获的流失败原
+      // 因，绝不让探针 500。
+      if (result === undefined) {
+        return { ok: false, durationMs: elapsed(), error: streamError || "no stream result", modelId };
+      }
+      return result;
     } catch (error) {
       return { ok: false, durationMs: elapsed(), error: String(error?.message ?? error), modelId };
     }
@@ -1596,8 +1643,77 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
     }
   });
 
+  // --- M.O.（Modus Operandi · 手法）工作流 ---
+  // 只读端点，读的是**项目里**的 `<项目>/.mneme/pipelines/*.json`（文件头在
+  // src/pipeline.js），项目层优先、插件包里那份降级成全局层；投影成
+  // mneme.pipeline/v1 交给面板与 agent——两边读同一份，画面只是它的投影。
+  // 刻意不做旗标闸门：旗标管的是**客户端座位**（关=一个座位都不注册），不是数据面；
+  // 多一个只读端点不会让任何人看见它，而给它加闸门只会让「为什么面板打不开」多一种成因。
+  register({
+    kind: "exact",
+    path: "/api/dsh-mneme/pipeline",
+    handler(req, res) {
+      try {
+        const url = new URL(req.url, "http://localhost");
+        const id = url.searchParams.get("id") || null;
+        const project = url.searchParams.get("project");
+        // project 是**会话工作目录**，由面板侧解析后带过来——工作目录只有客户端拿得到
+        // （宿主会话头里的 header.cwd），服务端没有「当前项目」这个概念。
+        // 不是绝对路径就**拒掉**，不能忽略：忽略了会静默退成「全局」，而全局看起来
+        // 一切正常——那正是这版要修掉的那类错。
+        if (project !== null && !isAbsolute(project)) {
+          sendJson(res, 400, { error: "project-not-absolute", detail: project });
+          return;
+        }
+        sendJson(res, 200, readPipelineDoc({ projectRoot: project, id }));
+      } catch (error) {
+        // 工作流是人手写的 JSON，报错本身就是给人看的：说清哪一条、坏在哪，
+        // 而不是回一句 internal 让人去翻日志。
+        sendJson(res, 500, {
+          error: "pipeline-unreadable",
+          detail: String((error && error.message) || error)
+        });
+      }
+    }
+  });
+
+  // --- M.O. 候选层（绕行走出来、还没进仓库的那些路） ---
+  // 和 /pipeline 读的是两处不同的东西，别混：
+  //   /pipeline    定稿，住**仓库**（<项目>/.mneme/pipelines/），可提交、可 review
+  //   /candidates  候选，住**本地**（<memoryDir>/candidates/<项目键>/），随时长、随时扔
+  // 分开是刻意的：候选是草稿，一天可能长十条死九条，进仓库就是垃圾；
+  // 而定稿只放人亲手批过的东西——候选是定稿的唯一入口。
+  //
+  // 这一刀只给**读**：提议与批准的动作还没有落点（那要等执行侧）。
+  // 契约里显式写着 boundaries.autoPromote/autoApprove/injectIntoMemory 三个 false，
+  // 免得以后有人以为忘了做。
+  register({
+    kind: "exact",
+    path: "/api/dsh-mneme/candidates",
+    handler(req, res) {
+      try {
+        const url = new URL(req.url, "http://localhost");
+        const project = url.searchParams.get("project");
+        if (project !== null && !isAbsolute(project)) {
+          sendJson(res, 400, { error: "project-not-absolute", detail: project });
+          return;
+        }
+        // memoryDir 从 config 拿（与 store 同源）；取不到就退回默认，与 config.js 的默认值一致。
+        const memoryDir = (config && typeof config.memoryDir === "string" && config.memoryDir.trim())
+          ? config.memoryDir
+          : "~/.dsh/memory";
+        sendJson(res, 200, readCandidateDoc({ memoryDir, projectRoot: project }));
+      } catch (error) {
+        sendJson(res, 500, {
+          error: "candidates-unreadable",
+          detail: String((error && error.message) || error)
+        });
+      }
+    }
+  });
+
   return {
-    routes: 34,
+    routes: 36,
     dispose: () => {
       for (const dispose of disposers) dispose();
     }