@rennimars/dsh-weknora-memory 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.3.0 — 写入侧随包发布（可选组件）
+
+- **新增 `lib/weknora.js`**：读侧与写入侧共用的唯一 HTTP 客户端（base URL 拼接、`X-API-Key` 头、超时、`no_api_url|timeout|transport|http_<status>` 错误词表）。`lib/retrieve.js` 的两处内联 fetch 已改为调用它，59 个既有用例保持全绿。
+- **新增 `writers/`（默认不启用）**：`ingest.mjs` 会话原文入库①、`distill.mjs` 结论蒸馏入库②、`dream.mjs` 事实卡裁决 S0–S4、`profile-writer.mjs` 画像唯一写入者。四者都支持 `--config` / `--dry-run` / `--verbose`，失败返回可读错误与明确退出码，`--dry-run` 不写库、不写文件、不写 state。
+- **新增 `writers/register-tasks.ps1`** 与 **`writers/run-all.cmd`**：幂等注册/撤销计划任务（当前用户级，不需要管理员），以及手动跑一轮（可选单步）。
+- **凭证纪律**：`writer.config.json` 的 `apiKey` 字段被忽略，只从 `WEKNORA_API_KEY` 环境变量读取；发布包内不含任何密钥、知识库 id 或本机绝对路径。
+- **新增测试 `test/writers.test.mjs`（5 项）**：import 零副作用、`--help` 退出 0、桩地址 dry-run 不落盘且错误可读、`proposed→active`/`degrade→disputed` 只改状态字段、发布树无凭证/无机器路径。总计 64 个用例。
+- 安装后**不会**自动注册任何计划任务，读侧行为与 0.2.2 完全一致。
+
+## 0.2.2 — 补上写入侧（文档）
+
+- 新增「写入侧：这些记忆是谁写进去的」一节：三条管道（每小时会话原文入库① / 每日 04:30 结论蒸馏入库② / 每日 03:30 夜间做梦裁决事实卡）与画像写入器的闸门（`proposed` → 隔夜复核 → `active`，被标记 degrade 的卡转 `disputed`），含触发时间、配额与失败策略。
+- 明确边界：这些定时任务属于**宿主侧**，不随本包分发；装上插件不会自动获得写入能力。写清这点是为了不让"记忆插件"的想象越界成实际行为。
+- 补三库分工（原文 / 结论 / 原始材料）与"为什么写入必须独立于读侧"的取舍说明。
+- 代码与默认配置未改动。
+
 ## 0.2.1 — 介绍重写（仅文档）
 
 - README 从“功能清单”改写为**机制说明**：三层上下文（常驻 / 画像 / 检索）各自的独立预算、一轮之内的完整检索管线（分库并发 → RRF → 来源权重 → 时效衰减 → 冷热分层 → 阈值 → 会话去重 → 邻块扩展 → 事实卡冲突 → 渲染），以及每处设计取舍的理由。

package/README.md

@@ -48,7 +48,58 @@ agent/pre-step
 
 最后一步的细节很重要：注入块是**一条独立的 user-role 消息**，不是对你的提问的改写，模型能分辨"这是检索来的历史材料"而不是"用户刚说的新任务"。
 
-## 四、几个刻意的设计取舍
+## 四、写入侧：这些记忆是谁写进去的
+
+本包只做**读**（每轮注入）和**人工编辑**（面板）。把原文、结论、画像写进 WeKnora 与 `data/profile.json` 的，是宿主侧的定时任务——**装上本插件不会自动获得这些任务**，它们是同一套体系的另一半，这里把契约写清楚，方便你自己实现或用别的工具替代。
+
+| 任务 | 触发 | 做什么 | 写到哪里 |
+|---|---|---|---|
+| `DSH-Session-Ingest` | 每小时 | 把**已结束且空闲 ≥10 分钟**的会话转录**原样**入库，跳过子代理会话；单篇 ≤200,000 字符，最多保留 150 篇；失败重试 3 次，入库后轮询索引 ≤600 秒 | 库① 会话记忆 |
+| `DSH-Session-Distill` | 每日 04:30 | 从最近会话里抽取结论 / 约束 / 偏好 / 教训，一次最多 3 个会话、3 篇文档，输入 ≤30,000 字符、每轮 ≤1500 字符、每会话 ≤8 条，语义去重阈值 0.66 | 库② 知识 |
+| `DSH-Memory-Dream` | 每日 03:30 | **夜间做梦**：五阶段 S0 收拢 → S1 分组 → S2 裁决 → S3 落账 → S4 报告。裁决同主题事实卡的取代 / 冲突 / 重复，**只改 header 里的状态字段，正文逐字保留**；单夜 ≤60 次 LLM 调用、≤20 次更新；支持 `--dry-run` / `--no-llm` 零成本演练 | 库② 知识（事实卡状态） |
+| `profile-writer` | 紧接做梦之后，且**只在做梦 rc=0 时** | `data/profile.json` 的**唯一写入者**：新卡一律 `proposed`，至少等一夜才复核；复核必须同时满足「有来源 / 不重复 / 不冲突 / 正文 ≤60 字」才转正，否则保持 `proposed` 并记日志；被插件标了 degrade 的 `active` 卡转 `disputed`，下一轮起不再进常驻块 | 常驻层画像 |
+| `DSH-Memory-Weekly` | 每周 | 体检：跨库重复、失效文档、状态异常 | 三库 |
+
+三库的分工不是随手划的：
+
+- **库① 会话记忆**存原文，回答"当时到底怎么说的"；
+- **库② 知识**存结论，一条结论一张事实卡，回答"这件事定了没有、为什么"；
+- **库③ 资料**存你手工入库的原始文件，回答"这份规范里怎么写的"。
+
+**为什么写入侧必须独立于插件：** 写要 LLM、要数据库权限、要能被人工审计；而读侧每轮都跑，必须零依赖、可静默失败。两者混在一起，任何一次写入故障都会变成一次会话故障。
+
+**为什么画像文件只允许一个写入者：** 常驻内容每轮注入、跨会话传播——一旦被污染，后面没有任何一次检索能把它纠正回来。所以插件侧只读，任何新内容只能走 `proposed → 隔夜复核 → active` 这条闸门。
+
+### 本包自带的写入侧参考实现（`writers/`，默认不启用）
+
+上面那张表是**它应该长什么样**；本包把同一套约定做成了可复制的实现，放在 `writers/`，**随包分发但默认不运行**——装上插件不会创建任何计划任务、不会写任何文档。
+
+| 文件 | 作用 |
+|---|---|
+| `writers/ingest.mjs` | 会话转录 → 库①（幂等：同名文档走 PUT 复用 id） |
+| `writers/distill.mjs` | 会话 → 结论 → 库②（含语义去重，LLM 走 WeKnora 会话网关） |
+| `writers/dream.mjs` | 事实卡裁决 S0–S4，只改 header 状态；`--self-test` 可离线跑 |
+| `writers/profile-writer.mjs` | `data/profile.json` 的唯一写入者；不带 `--write` 就只打印 diff |
+| `writers/register-tasks.ps1` | 幂等注册/更新计划任务（`-Unregister` 撤销，`-Prefix`、`-Times` 可改） |
+| `writers/run-all.cmd` | 手动跑一轮：`run-all.cmd [--dry-run] [ingest|distill|dream|profile]` |
+
+三步启用：
+
+```powershell
+cd node_modules/@rennimars/dsh-weknora-memory
+copy writers\config.example.json writers\writer.config.json   # 填 apiUrl / sessionsRoot / kbs
+$env:WEKNORA_API_KEY = "<你的 key>"                            # 只从环境变量读，不落文件
+powershell -ExecutionPolicy Bypass -File writers\register-tasks.ps1
+```
+
+四条纪律：
+
+- **凭证只在环境变量**：`writer.config.json` 里的 `apiKey` 字段会被忽略；缺 `WEKNORA_API_KEY` 时只提示，不带该请求头。
+- **演练零成本**：四个脚本都支持 `--dry-run`（不写库、不写文件、不写 state）；`dream.mjs --dry-run --no-llm` 连一次 LLM 都不发。
+- **共用一份 HTTP**：读侧 `lib/retrieve.js` 与写入侧全部走 `lib/weknora.js`，`X-API-Key` 头与错误词表只有一处实现。
+- **失败可见**：退出码 0/1/2/3 有明确语义，失败是一条可读错误而不是异常栈——这与读侧「失败即静默」刻意相反，因为定时任务没有人在看着。
+
+## 五、几个刻意的设计取舍
 
 **不改用户原话。** 注入永远走追加，避免任何"提示词污染"式的隐蔽改写。
 
@@ -62,7 +113,7 @@ agent/pre-step
 
 **自动写入与人工编辑分权。** `data/profile.json` 的自动更新属于夜间任务，插件本身只读；面板里的编辑是用户显式动作。这条边界防的是"每轮注入、每轮重算"的自我强化——一个被污染的事实否则会跨会话传播。
 
-## 五、可观测性
+## 六、可观测性
 
 侧边栏「记忆」页签，三个视图：
 
@@ -74,7 +125,7 @@ agent/pre-step
 
 日志只记元数据：会话 id、耗时、命中数、字符数、结果。**不写提问原文，也不写片段正文**。
 
-## 六、依赖
+## 七、依赖
 
 | 项 | 要求 |
 |---|---|
@@ -82,7 +133,7 @@ agent/pre-step
 | Node | `>= 20.11` |
 | WeKnora | 一个可访问实例（默认 `http://127.0.0.1:8080/api/v1`），以及至少一个知识库 |
 
-## 七、安装
+## 八、安装
 
 **从插件市场**：插件页 → 插件市场 → 搜索 `weknora` → 安装。
 
@@ -96,7 +147,7 @@ git clone https://github.com/RenniMars/dsh-weknora-memory node_modules/@rennimar
 
 然后在同目录 `package.json` 的 `dsh.profile.bundles` 里加一行 `"@rennimars/dsh-weknora-memory"`，重启客户端。
 
-## 八、配置
+## 九、配置
 
 复制模板，填三样东西：
 
@@ -122,13 +173,13 @@ cp wk-inject.config.example.json wk-inject.config.json
 
 其余参数（超时、字符上限、命中数、阈值、RRF k、邻块扩展、衰减半衰期与下限、冷热分层配额、画像卡配额、事实卡权重、日志路径）见 `lib/config.js` 的 `DEFAULT_CONFIG`，每一项都带注释说明为什么取这个值；一般不用动。
 
-## 九、隐私与边界
+## 十、隐私与边界
 
 - `data/profile.json`、`data/profile-stats.json`、`data/tier-state.json`、`logs/inject.log` 全部留在本机，不进仓库、不进包（`.gitignore` / `.npmignore` 都排除了）。
 - 本插件不向任何第三方上报数据；所有请求只发往你自己配置的 `apiUrl`。
 - 子代理会话默认不检索（`skipSubagents: true`）：子代理拿到的是被裁剪过的任务，用它的文本去检索只会污染主会话的记忆。
 
-## 十、开发
+## 十一、开发
 
 ```bash
 npm test          # node --test test/*.mjs，59 个用例
@@ -144,6 +195,8 @@ npm test          # node --test test/*.mjs，59 个用例
 | `lib/decay.js` | 时效衰减与命中回写（原子 JSON 状态） |
 | `lib/config.js` | 配置加载、钳制、日志 |
 | `lib/panel.js` / `lib/client.js` | 面板同源路由 / GUI 侧渲染 |
+| `lib/weknora.js` | 唯一 HTTP 客户端：读侧与写入侧共用 |
+| `writers/*.mjs` | 可选写入侧：ingest / distill / dream / profile-writer |
 
 ## License
 

package/lib/retrieve.js

@@ -25,6 +25,7 @@
  * that call. Any failure there is silent: the hit is injected exactly as it arrived.
  */
 import { TIMEOUT_CAP_MS } from "./config.js";
+import { request } from "./weknora.js";
 import { applyDecay, readState } from "./decay.js";
 import { cleanText } from "./format.js";
 
@@ -158,32 +159,17 @@ function keyOf(hit, group) {
 
 /** One scoped search call; kbId "" means "no scope" (search everything). */
 async function searchOnce(query, config, kbId, deps) {
-  const fetchImpl = deps.fetchImpl ?? globalThis.fetch;
-  const timeoutMs = timeoutOf(config);
-  const base = String(config.apiUrl ?? "").replace(/\/+$/, "");
-  if (!base) return { ok: false, reason: "no_api_url" };
-  const url = base + "/knowledge-search";
-  const signals = [AbortSignal.timeout(timeoutMs)];
-  if (deps.signal) signals.push(deps.signal);
-  const headers = { "Content-Type": "application/json", Accept: "application/json" };
-  if (config.apiKey) headers["X-API-Key"] = config.apiKey;
   const body = { query, top_k: topKOf(config) };
   if (kbId) body.knowledge_base_ids = [kbId];
-  try {
-    const response = await fetchImpl(url, {
-      method: "POST",
-      headers,
-      body: JSON.stringify(body),
-      signal: signals.length > 1 ? AbortSignal.any(signals) : signals[0],
-    });
-    if (!response.ok) return { ok: false, reason: "http_" + response.status };
-    const payload = await response.json();
-    const hits = Array.isArray(payload?.data) ? payload.data : [];
-    return { ok: true, hits };
-  } catch (error) {
-    const name = error?.name;
-    return { ok: false, reason: name === "TimeoutError" || name === "AbortError" ? "timeout" : "transport" };
-  }
+  const result = await request(config, "POST", "/knowledge-search", {
+    body,
+    timeoutMs: timeoutOf(config),
+    signal: deps.signal,
+    fetchImpl: deps.fetchImpl,
+  });
+  if (!result.ok) return { ok: false, reason: result.reason };
+  const hits = Array.isArray(result.body?.data) ? result.body.data : [];
+  return { ok: true, hits };
 }
 
 /**
@@ -289,30 +275,19 @@ function sliceHead(text, limit) {
  * binarySearchPage() over the page index ranges instead of giving up.
  */
 async function fetchChunkPage(knowledgeId, page, config, deps, timeoutMs) {
-  const fetchImpl = deps.fetchImpl ?? globalThis.fetch;
-  const base = String(config?.apiUrl ?? "").replace(/\/+$/, "");
-  if (!base) return null;
-  const url = base + "/chunks/" + encodeURIComponent(knowledgeId) + "?page=" + page + "&page_size=" + CHUNK_PAGE_SIZE;
-  const headers = { Accept: "application/json" };
-  if (config.apiKey) headers["X-API-Key"] = config.apiKey;
-  const signals = [AbortSignal.timeout(Math.max(MIN_REQUEST_MS, timeoutMs))];
-  if (deps.signal) signals.push(deps.signal);
-  try {
-    const response = await fetchImpl(url, {
-      method: "GET",
-      headers,
-      signal: signals.length > 1 ? AbortSignal.any(signals) : signals[0],
-    });
-    if (!response.ok) return null;
-    const payload = await response.json();
-    return {
-      list: Array.isArray(payload?.data) ? payload.data : [],
-      total: Number.isFinite(payload?.total) ? Number(payload.total) : null,
-      pageSize: Number.isFinite(payload?.page_size) && payload.page_size > 0 ? Number(payload.page_size) : null,
-    };
-  } catch {
-    return null;
-  }
+  const result = await request(
+    config,
+    "GET",
+    "/chunks/" + encodeURIComponent(knowledgeId) + "?page=" + page + "&page_size=" + CHUNK_PAGE_SIZE,
+    { timeoutMs: Math.max(MIN_REQUEST_MS, timeoutMs), signal: deps.signal, fetchImpl: deps.fetchImpl }
+  );
+  if (!result.ok) return null;
+  const payload = result.body;
+  return {
+    list: Array.isArray(payload?.data) ? payload.data : [],
+    total: Number.isFinite(payload?.total) ? Number(payload.total) : null,
+    pageSize: Number.isFinite(payload?.page_size) && payload.page_size > 0 ? Number(payload.page_size) : null,
+  };
 }
 
 /** One fetched page, indexed by chunk id and by chunk_index, with its index range. */

package/lib/weknora.js

@@ -0,0 +1,80 @@
+/**
+ * The one WeKnora HTTP client.
+ *
+ * Both sides of the memory system go through here: the injector (lib/retrieve.js,
+ * read path, every step) and the optional writers (writers/*, write path, scheduled).
+ * They were two hand-rolled fetch blocks before this module existed, which is exactly
+ * how a header or an error string drifts apart between the two.
+ *
+ * Nothing in here throws for transport, timeout or HTTP status: a call resolves to
+ * { ok, status, body, reason } and the caller decides whether that is fatal. The read
+ * path is required to degrade silently, the writers are required to log and exit
+ * non-zero, so the decision has to stay with them.
+ */
+
+/** Request ceiling applied when a caller names no timeout of its own. */
+export const DEFAULT_TIMEOUT_MS = 4000;
+
+/** The configured base URL without trailing slashes, or "" when unset. */
+export function baseUrlOf(config) {
+  return String(config?.apiUrl ?? "").replace(/\/+$/, "");
+}
+
+/** Join a base URL and a path, tolerating a missing or extra leading slash. */
+export function joinUrl(base, path) {
+  const root = String(base ?? "").replace(/\/+$/, "");
+  const tail = String(path ?? "");
+  return root + (tail.startsWith("/") ? tail : "/" + tail);
+}
+
+/**
+ * Request headers: X-API-Key only when a key is configured, and the JSON content
+ * type only when a body is actually sent (a GET with Content-Type is noise).
+ */
+export function headersFor(config, { json = false } = {}) {
+  const headers = json
+    ? { "Content-Type": "application/json", Accept: "application/json" }
+    : { Accept: "application/json" };
+  const key = config?.apiKey;
+  if (typeof key === "string" && key) headers["X-API-Key"] = key;
+  return headers;
+}
+
+/**
+ * One request. `reason` is one of no_api_url / timeout / transport / http_<status>,
+ * which is the vocabulary lib/retrieve.js already reports in its stats.
+ *
+ * @param {object} config  clamped config (apiUrl / apiKey)
+ * @param {string} method  HTTP method
+ * @param {string} path    path below the base URL, e.g. "/knowledge-search"
+ * @param {object} [options]
+ * @param {object} [options.body]      JSON body; omit for a body-less request
+ * @param {number} [options.timeoutMs] per-request ceiling; omitted means no deadline
+ * @param {AbortSignal} [options.signal] caller's own deadline/cancellation
+ * @param {Function} [options.fetchImpl] injected fetch (tests)
+ * @param {"json"|"none"} [options.expect] parse the body as JSON (default) or ignore it
+ */
+export async function request(config, method, path, options = {}) {
+  const { body, timeoutMs, signal, fetchImpl = globalThis.fetch, expect = "json" } = options;
+  const base = baseUrlOf(config);
+  if (!base) return { ok: false, reason: "no_api_url" };
+
+  const signals = [];
+  if (Number.isFinite(timeoutMs) && timeoutMs > 0) signals.push(AbortSignal.timeout(timeoutMs));
+  if (signal) signals.push(signal);
+
+  const init = { method, headers: headersFor(config, { json: body !== undefined }) };
+  if (body !== undefined) init.body = JSON.stringify(body);
+  if (signals.length === 1) init.signal = signals[0];
+  else if (signals.length > 1) init.signal = AbortSignal.any(signals);
+
+  try {
+    const response = await fetchImpl(joinUrl(base, path), init);
+    if (!response.ok) return { ok: false, status: response.status, reason: "http_" + response.status };
+    if (expect === "none") return { ok: true, status: response.status, body: null };
+    return { ok: true, status: response.status, body: await response.json() };
+  } catch (error) {
+    const name = error?.name;
+    return { ok: false, reason: name === "TimeoutError" || name === "AbortError" ? "timeout" : "transport" };
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rennimars/dsh-weknora-memory",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Layered context engine for DeepSeek Harness: per-kb WeKnora retrieval fused by RRF, recency decay and hot/warm/cold tiering, standing profile cards and fact-conflict surfacing — budgeted, auditable, editable.",
   "type": "module",
   "main": "./lib/index.js",
@@ -11,6 +11,7 @@
   },
   "files": [
     "lib",
+    "writers",
     "cordis.patch.yml",
     "wk-inject.config.example.json",
     "README.md",

package/writers/README.md

@@ -0,0 +1,24 @@
+# writers/ — 写入侧（可选）
+
+本目录是**参考实现**，不随插件默认启用，安装后不会注册任何计划任务。它把会话转录、结论、事实卡状态与画像写进 WeKnora 与 `data/profile.json`；插件的读侧（每轮注入）只读这些东西。
+
+## 契约（四个脚本都必须遵守）
+
+1. **配置**：默认读本目录的 `writer.config.json`，`--config <path>` 可覆盖；缺文件时用 `config.example.json` 的默认值并在日志里说明。
+2. **凭证**：`apiUrl` 形如 `http://127.0.0.1:8080/api/v1`（**含**版本前缀，与插件配置一致）；`apiKey` 留空，从环境变量 `WEKNORA_API_KEY` 取；环境变量优先。
+3. **HTTP**：一律通过 `../lib/weknora.js` 的 `request()`，不自己写 fetch。
+4. **路径**：`profile.path` / `profile.statsPath` 相对**包根目录**（本目录的上一级）解析，与插件一致。
+5. **演练**：每个脚本都支持 `--dry-run`（只打印计划，不写库、不写文件）与 `--verbose`。
+6. **退出码**：0 成功；非 0 失败。失败必须写日志并返回非 0，不能静默。
+7. **幂等**：同一轮重复执行不得产生重复文档（按标题前缀 + 内容哈希判定）。
+
+## 脚本
+
+| 文件 | 触发建议 | 作用 |
+|---|---|---|
+| `ingest.mjs` | 每小时 | 会话转录原样入库① |
+| `distill.mjs` | 每日 04:30 | 会话 → 结论 → 库② |
+| `dream.mjs` | 每日 03:30 | 事实卡裁决（S0..S4） |
+| `profile-writer.mjs` | 紧接 dream（rc=0 后） | 画像唯一写入者 |
+
+`register-tasks.ps1` 按上面的触发时间注册计划任务（幂等，`--unregister` 反注册）；`run-all.cmd` 手动跑一轮。

package/writers/config.example.json

@@ -0,0 +1,57 @@
+{
+  "$comment": "Writers config. Copy to writer.config.json next to this file. No credential belongs in this file: leave apiKey out and set WEKNORA_API_KEY in the environment.",
+  "apiUrl": "http://127.0.0.1:8080/api/v1",
+  "apiKey": "",
+  "sessionsRoot": "",
+  "kbs": {
+    "session": "",
+    "knowledge": "",
+    "material": ""
+  },
+  "ingest": {
+    "enabled": true,
+    "titlePrefix": "会话记录 ",
+    "settleMinutes": 10,
+    "maxDocBytes": 200000,
+    "maxSessionDocs": 150,
+    "skipSubagentSessions": true,
+    "maxAttempts": 3,
+    "pollTimeoutSec": 600
+  },
+  "distill": {
+    "enabled": true,
+    "titlePrefix": "记忆 ",
+    "maxSessionsPerRun": 3,
+    "maxDocsPerRun": 3,
+    "maxInputChars": 30000,
+    "perTurnChars": 1500,
+    "maxEntriesPerSession": 8,
+    "semanticDedupe": {
+      "enabled": true,
+      "scoreMin": 0.66
+    }
+  },
+  "dream": {
+    "enabled": true,
+    "titlePrefix": "[fact] ",
+    "maxLlmCalls": 60,
+    "maxUpdates": 20,
+    "grouping": {
+      "searchTopK": 5,
+      "queryChars": 120,
+      "sameRootScore": 0.5,
+      "crossRootScore": 0.6,
+      "maxCluster": 5
+    }
+  },
+  "profile": {
+    "enabled": true,
+    "path": "data/profile.json",
+    "statsPath": "data/profile-stats.json"
+  },
+  "llm": {
+    "mode": "weknora-session-chat",
+    "modelName": "builtin-deepseek-flash",
+    "timeoutMs": 240000
+  }
+}