@modusensus/dsh-mneme 0.8.15 → 0.9.0

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-standalone.js

@@ -18,6 +18,7 @@ import { randomBytes, timingSafeEqual } from "node:crypto";
 import { TYPES } from "./store.js";
 import { bootstrapFromDirectory } from "./bootstrap.js";
 import { PACKAGE_VERSION } from "./version-check.js";
+import { parseReclaimJson, readReclaimFields, reclaimReply, RECLAIM_UNAVAILABLE } from "./reclaim-http.js";
 
 const DEFAULT_PORT = 8790;
 const DEFAULT_HOST = "127.0.0.1";
@@ -482,54 +483,36 @@ export function createStandaloneApi({ service, store, config = {}, logger, setti
       // 默认 dry-run：只有显式 confirm:true 才真改数据。这两步都是不可逆的内容丢弃
       // （历史 run 的输入快照置空、归档行向量置空），所以不给「带 body 就执行」这种
       // 省事路径——确认必须建立在看得见的数字上。
+      //
+      // 口径（错误码字符串、默认值、报告形状）不在这里写：与宿主内的面板路由
+      // /api/dsh-mneme/maintenance/reclaim 共用 src/reclaim-http.js，两张皮只有鉴权
+      // 与路径不同。这条曾经是整段复制的，于是面板侧修好之后这边还停在旧形态（#411）。
       if (req.method === "POST" && pathname === "/maintenance/reclaim") {
         void readBody(req).then((text) => {
-          let body;
-          try {
-            body = JSON.parse(text || "{}");
-          } catch {
-            sendJson(res, 400, { error: "invalid-json" });
-            return;
-          }
-          if (body === null || typeof body !== "object" || Array.isArray(body)) {
-            sendJson(res, 400, { error: "invalid-body" });
+          const parsed = parseReclaimJson(text);
+          if (!parsed.ok) {
+            sendJson(res, 400, { error: parsed.error });
             return;
           }
+          // 顺序敏感：端点整个没接线时报「窗口不合法」是误导，503 必须赢过字段校验。
           if (!maintenance) {
-            sendJson(res, 503, { error: "maintenance-unavailable" });
+            sendJson(res, 503, { error: RECLAIM_UNAVAILABLE });
             return;
           }
-          const dryRun = body.dryRun !== false;
-          // 只收 JSON 数字：`Number()` 会把 ""/[]/false 都化成 0，而 0 在这里是
-          // 「清掉全部快照」——最坏解释绝不能让一个畸形输入静默拿到。
-          const olderThanDays = body.olderThanDays === undefined || body.olderThanDays === null
-            ? undefined
-            : body.olderThanDays;
-          if (olderThanDays !== undefined && (!Number.isInteger(olderThanDays) || olderThanDays < 0)) {
-            sendJson(res, 400, { error: "invalid-older-than-days" });
+          const fields = readReclaimFields(parsed.body);
+          if (!fields.ok) {
+            sendJson(res, 400, { error: fields.error });
             return;
           }
-          if (body.vacuum !== undefined && typeof body.vacuum !== "boolean") {
-            sendJson(res, 400, { error: "invalid-vacuum" });
-            return;
-          }
-          if (!dryRun && body.confirm !== true) {
-            // 拒执行，但把 dry-run 报告一并回给调用方：确认的依据就是这份数字。报告
-            // 必须描述**将要执行的那个动作**，所以 vacuum 原样带上——否则调用方看到
-            // 的是「不 VACUUM」的数字，却带着 vacuum 去执行。
-            sendJson(res, 400, {
-              error: "confirm-required",
-              hint: "先看 dry-run 报告，确认后带 {\"dryRun\":false,\"confirm\":true} 再发",
-              report: maintenance.reclaim({ olderThanDays, vacuum: body.vacuum === true, dryRun: true })
-            });
-            return;
-          }
-          try {
-            sendJson(res, 200, maintenance.reclaim({ olderThanDays, vacuum: body.vacuum === true, dryRun }));
-          } catch (error) {
-            logger?.warn?.(`[dsh-mneme] storage reclaim failed: ${String(error)}`);
-            sendJson(res, 500, { error: "internal" });
-          }
+          const { status, body } = reclaimReply({
+            maintenance,
+            dryRun: fields.dryRun,
+            olderThanDays: fields.olderThanDays,
+            vacuum: fields.vacuum,
+            confirm: fields.confirm,
+            warn: (msg) => logger?.warn?.(msg)
+          });
+          sendJson(res, status, body);
         });
         return;
       }