@modusensus/dsh-mneme 0.8.15 → 0.9.0

package/src/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;
       }

package/src/api.js

@@ -1,14 +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 = {}) {
@@ -92,7 +97,10 @@ function parseBody(text) {
   }
 }
 
-export function createApi(ctx, service, settings, commands, embedder, semantic = null, apiToken = "", config = null) {
+// maintenance 是第 9 个位置参数，默认 null：既有调用点（测试里的 14 处）全是位置传参、
+// 不传它，必须继续工作——不传时 /maintenance/reclaim 回 503 maintenance-unavailable，
+// 而不是把「没接线」伪装成崩溃（#386 第 4 条）。
+export function createApi(ctx, service, settings, commands, embedder, semantic = null, apiToken = "", config = null, maintenance = null) {
   const disposers = [];
 
   // #182 注入状态探测：面板状态页的「极简模式下注入按宿主设计关闭」提示需要
@@ -146,7 +154,11 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
     // Issue #380：注入前判定。漏登记的后果是 effective 静默缺键、面板盲——
     // 上面的 round-trip 测试专门锁这张表与白名单成对。
     "preInjectGate.enabled": ["preInjectGate", "enabled"],
-    "preInjectGate.enforce": ["preInjectGate", "enforce"]
+    "preInjectGate.enforce": ["preInjectGate", "enforce"],
+    // Issue #399：蒸馏原文留存 + 溯源。两个键都是嵌套子字段（enabled 开关 +
+    // retentionDays 整数），漏登记的后果同上——effective 静默缺键。
+    "distillRecords.enabled": ["distillRecords", "enabled"],
+    "distillRecords.retentionDays": ["distillRecords", "retentionDays"]
     // sensitiveScanEnabled（#164 A2）是顶层扁平键，不需要进这张表——走 configFlagValue
     // 的默认分支即可。
   };
@@ -367,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,
@@ -382,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。
@@ -397,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 };
     }
@@ -602,6 +658,165 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
     }
   });
 
+  // --- 新建一条记忆（面板写路径，与 /update、/delete 对称命名）---------------
+  // #386 第 5 条：CLI `add` 与 standalone `POST /memories` 都能建行，面板此前只
+  // 能看/改/删/导入。字段与 memory_save 工具对齐（type/title/content/importance/
+  // tags），走同一条 saveWithDedupe 路径——去重键仍是 (type, title, scope,
+  // sensitivity)，所以「面板建」与「工具建」同标题会并入同一行，不会长出两份。
+  //
+  // 三处刻意的口径差异（都写在代码里，免得下一个人以为是抄漏）：
+  //  1. content 要求 trim 后非空，与 /update 一致而非 standalone 的宽松版：
+  //     面板是人工输入，空正文只可能是误操作；standalone 面对的是程序化调用，
+  //     放宽是为了兼容「先建壳再补内容」的既有客户端。
+  //  2. document 直接 400：行铸造口唯一（registerDocument，#230），saveWithDedupe
+  //     会 throw，这里提前给干净错误码而不是让它落成 500。
+  //  3. 不接受 scope/sensitivity 字段——面板的 scope 编辑在详情抽屉里（带放宽
+  //     确认的安全阀，见 lib/client.js 的 MemoryDrawer），新建时就盖章 explicit
+  //     会绕过那道确认。传了也不报错，只是不生效（与 /update 的「字段出现即校验」
+  //     不同，因为这里根本没有该字段的语义）。
+  register({
+    kind: "exact",
+    path: "/api/dsh-mneme/create",
+    handler(req, res) {
+      try {
+        if (req.method !== "POST") {
+          sendJson(res, 404, { error: "not-found" });
+          return;
+        }
+        if (!requireAuth(req, res, apiToken)) return;
+        return readBody(req).then((text) => {
+          const body = parseBody(text);
+          if (!TYPES.has(body.type)) {
+            sendJson(res, 400, { error: "invalid-type" });
+            return;
+          }
+          if (body.type === "document") {
+            sendJson(res, 400, { error: "document-requires-register" });
+            return;
+          }
+          if (typeof body.title !== "string" || !body.title.trim()) {
+            sendJson(res, 400, { error: "invalid-title" });
+            return;
+          }
+          if (typeof body.content !== "string" || !body.content.trim()) {
+            sendJson(res, 400, { error: "invalid-content" });
+            return;
+          }
+          if (body.importance !== undefined
+            && (!Number.isInteger(body.importance) || body.importance < 1 || body.importance > 5)) {
+            sendJson(res, 400, { error: "invalid-importance" });
+            return;
+          }
+          if (body.tags !== undefined && (!Array.isArray(body.tags) || !body.tags.every((tag) => typeof tag === "string"))) {
+            sendJson(res, 400, { error: "invalid-tags" });
+            return;
+          }
+          try {
+            const result = service.saveWithDedupe({
+              type: body.type,
+              title: body.title.trim(),
+              content: body.content.trim(),
+              importance: body.importance,
+              tags: body.tags ?? [],
+              // 面板不是工具也不是外部程序，来源要能在详情抽屉里一眼认出是谁写的。
+              source: "panel"
+            });
+            // #254 写入准入在无会话身份时放行（write-admission.js 首行早退），面板
+            // 路由恰好不带 _sessionKey，所以今天到不了这个分支。仍然显式写出来：
+            // 将来若把会话身份接进面板，落到 toApiList([null]) 上会变成 500，把
+            // 「被拒」伪装成「服务器出错」——两者的处置完全不同。
+            if (result.action === "denied") {
+              sendJson(res, 422, { error: "write-rejected", reason: result.reason });
+              return;
+            }
+            // action 随行透出（created/merged）：面板据此提示「已并入同标题的既有条目」
+            // 还是「新建成功」——两者对用户是不同的事实，不能都报「已保存」。
+            sendJson(res, result.action === "created" ? 201 : 200, {
+              ...service.toApiList([result.memory])[0],
+              action: result.action
+            });
+          } catch (error) {
+            ctx.logger?.warn?.(`[dsh-mneme] panel create failed: ${String(error)}`);
+            sendJson(res, 500, { error: "internal" });
+          }
+        });
+      } catch {
+        sendJson(res, 500, { error: "internal" });
+      }
+    }
+  });
+
+  // --- maintenance/reclaim（#386 第 4 条：面板有了回收入口）------------------
+  // 与 standalone 数据面的 POST /maintenance/reclaim 是同一能力的两张皮：口径（错误码
+  // 字符串、默认值、报告形状）只写在 src/reclaim-http.js 里，这里与数据面都调它。
+  // 差别只有鉴权与路径——两张皮的其余部分必须没有第二份实现（#411 的教训：以前是整段
+  // 复制，于是 #410 修好这边之后那边还停在旧形态）。
+  //
+  // 为什么 GET 也能跑：dry-run 是只读的（src/maintenance.js 里 dry-run 与执行同一条
+  // 代码路径，只是不落 UPDATE/VACUUM），面板 mount 时拿它渲染「现在能回收多少」。
+  //
+  // 为什么两法都要 requireAuth：这是不可逆内容丢弃的入口，不能有例外。
+  register({
+    kind: "exact",
+    path: "/api/dsh-mneme/maintenance/reclaim",
+    handler(req, res) {
+      try {
+        if (req.method === "GET") {
+          if (!requireAuth(req, res, apiToken)) return;
+          if (!maintenance) {
+            sendJson(res, 503, { error: RECLAIM_UNAVAILABLE });
+            return;
+          }
+          const parsed = parseReclaimQuery(new URL(req.url, "http://localhost").searchParams.get("olderThanDays"));
+          if (!parsed.ok) {
+            sendJson(res, 400, { error: parsed.error });
+            return;
+          }
+          const { status, body } = reclaimReply({
+            maintenance,
+            dryRun: true,
+            olderThanDays: parsed.olderThanDays,
+            warn: (msg) => ctx.logger?.warn?.(msg)
+          });
+          sendJson(res, status, body);
+          return;
+        }
+        if (req.method !== "POST") {
+          sendJson(res, 404, { error: "not-found" });
+          return;
+        }
+        if (!requireAuth(req, res, apiToken)) return;
+        return readBody(req).then((text) => {
+          const parsed = parseReclaimJson(text);
+          if (!parsed.ok) {
+            sendJson(res, 400, { error: parsed.error });
+            return;
+          }
+          if (!maintenance) {
+            sendJson(res, 503, { error: RECLAIM_UNAVAILABLE });
+            return;
+          }
+          const fields = readReclaimFields(parsed.body);
+          if (!fields.ok) {
+            sendJson(res, 400, { error: fields.error });
+            return;
+          }
+          const { status, body } = reclaimReply({
+            maintenance,
+            dryRun: fields.dryRun,
+            olderThanDays: fields.olderThanDays,
+            vacuum: fields.vacuum,
+            confirm: fields.confirm,
+            warn: (msg) => ctx.logger?.warn?.(msg)
+          });
+          sendJson(res, status, body);
+        });
+      } catch {
+        sendJson(res, 500, { error: "internal" });
+      }
+    }
+  });
+
   // --- rules ---
   register({
     kind: "exact",
@@ -1428,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: 32,
+    routes: 36,
     dispose: () => {
       for (const dispose of disposers) dispose();
     }