@modusensus/dsh-mneme 0.9.0 → 0.9.1

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-1869%20passed-success)](https://github.com/slow-stack/mneme)
+[![tests](https://img.shields.io/badge/tests-2173%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)
@@ -17,7 +17,7 @@
 
 ## ⏱️ 30 秒理解
 
-**一句话**：给 Agent 装上跨会话记忆——记住你、记住项目，并在后台自动整理，越用越懂你；**v0.8.0 起**记忆可按 agent 与工作区隔离（`scopeEnabled`），多 Agent / 多项目互不串台。
+**一句话**：给 Agent 装上跨会话记忆——记住你、记住项目，并在后台自动整理，越用越懂你；**v0.8.0 起**记忆可按 agent 与工作区隔离（`scopeEnabled`），多 Agent / 多项目互不串台；**v0.9.0 起**「这件事怎么跑」也能落进项目仓库（M.O.，`actionPipelineEnabled`，默认关）。
 
 | ① 写入 | ② 存储 | ③ 进化 |
 |--------|--------|--------|
@@ -42,14 +42,14 @@ dsh web
 
 - **SQLite 主存储**：`~/.dsh/memory/memory.db`，`node:sqlite` 内置，零原生依赖
 - **Markdown 镜像**：按类型分文件（`preferences.md` / `projects.md` / `decisions.md` / `history.md` / `summary.md` / `patterns.md` / `pitfalls.md` / `constraints.md` / `rejected-solutions.md`，外加只读视图 `documents.md`），文件头是 YAML frontmatter（`type` / `generated.by` / `generated.at` / `covered` / `coverage` / `tags`）。人类可读，条目标题与正文可手工编辑（**人工修改优先**合并回库）；`documents.md` 例外：它只有 document 指针行（id、标题、摘要首句、文件路径），不含正文也不参与人工回填。文件头与条目元数据行由机器维护
-- **9 种记忆类型**：`preference` 偏好 / `project` 项目 / `decision` 决策 / `history` 历史 / `summary` 会话总览 / `pattern` 模式 + 编码记忆三型 `rejected_solution` 被否方案 / `pitfall` 踩坑 / `constraint` 约束（v0.7.13 起，`codingRetrospect` 默认关；v0.7.11 近重写已收窄删除 user/fact 两型）
+- **10 种记忆类型**：`preference` 偏好 / `project` 项目 / `decision` 决策 / `history` 历史 / `summary` 会话总览 / `pattern` 模式 + 编码记忆三型 `rejected_solution` 被否方案 / `pitfall` 踩坑 / `constraint` 约束（v0.7.13 起，`codingRetrospect` 默认关；v0.7.11 近重写已收窄删除 user/fact 两型）+ `document` 文档指针（#230，只存摘要与 `doc_path`，正文留在磁盘由 agent 自管）
 - **镜像同步状态机（v0.3.6+）**：mirror 与主库强一致，用 `generation`（期望轮次）/ `applied_generation`（已应用轮次）建模同步债务
   - 业务写操作在**自身事务内原子递增** desired generation——崩溃在 COMMIT 后、渲染前，重启也能凭 durable 债务恢复，绝不静默跳过（v0.3.8）
   - `generation` 用 SQLite 原子语句递增，多进程并发零丢失；带 `CHECK` 上界，负数/溢出拒绝
   - 逐 type 记录 `committed / failed / pending` 回执，健康端点区分 `ok / degraded / unknown`
   - 状态写失败不静默：同步失败落日志并留债务，重启自动收敛
 
-### 模型工具（9 个）
+### 模型工具（10 个）
 
 | 工具 | 功能 |
 |------|------|
@@ -61,8 +61,26 @@ dsh web
 | `memory_delete` | 删除记忆（按记忆 ID 精确删除） |
 | `memory_forget` | 抑制注入（降权不删除，可恢复） |
 | `memory_archive` | 归档/恢复记忆（v0.2.5；归档后隐藏于列表/搜索/注入/整理，`archived=false` 可恢复） |
+| `memory_register_document` | 登记 agent 产长文档的指针行（#230：摘要 + `doc_path` + evidence 落 `document` 类型；正文留在磁盘、由 agent 自管，注册口唯一，旁路写入被拒） |
 | `memory_runtime` | 本地推理运行时的状态 / 供给 / 校验（v0.7.32，自管运行时三档取件） |
 
+### 工作流（M.O. · 手法，v0.9 beta）
+
+记忆库答的是「这件事**为什么**这么办」，答不了「这件事**到底怎么跑**」。v0.9 把后者从记忆库里的一行文字变成项目里可提交、可 review、可被 CI 读的一份文件——一条工作流一个 JSON：
+
+```
+<项目>/.mneme/pipelines/<id>.json     ← 项目层（默认；跟着项目提交）
+<插件包>/pipelines/<id>.json          ← 全局层（兜底；今天包里没有这个目录，有意为空）
+```
+
+- **两层来源，顺序即优先级**：同 id 两处都有，项目层赢，被挡住的那份进 `shadowed` 报出来（不静默丢弃）；项目层的坏文件进 `unreadable` 而不拖死全局层——一层写坏不该让人连兜底那份也看不见
+- **校验很硬**：`id` / `name` / `project` / `version` / `status` / `done` 与每一步的 `phase` / `title` / `when` / `do` / `done` / `why` 缺一不可，`risk` 限 R0–R3、`needs` 必须指向存在的步骤、图里有环直接报错——任何一处不合规**整条读不出来**，不做「跳过坏文件继续」：半个工作流比没有更危险
+- **护栏，不是轨道**：绕行要留出口。自报 R0/R1 **且**不跨闸门 **且**兜底清单（`IRREVERSIBLE_PATTERNS`，机械匹配、不看自报）没命中 → 记账先走；其余 → 停下问人
+- **候选分层**：草稿住 `<memoryDir>/candidates/<项目键>/`，只在本地。升格要同时满足「走过两次（至少一次成功）」**且**「写得出反事实」；够格之后系统只**提议**，`promoteCandidate()` 只返回内容不写盘，提交与推送是人握着的那道门
+- **两个指标分开数**：跳过（这次不用这一步，≥3 次提议删**这一步**）与绕开（这条路整个不对，≥3 次提议重看**这条路径**）各自累加，混在一起两种提议都发不出来
+- **只读路由** `GET /api/dsh-mneme/pipeline[?id=&project=]`（`project` 非绝对路径回 400 `project-not-absolute`，不回退 `process.cwd()`）；答复契约 `mneme.pipeline/v1`，面板渲染与 agent 读的是同一份数据
+- 默认关（`actionPipelineEnabled`），设计取舍见 [docs/WORKFLOWS.md](docs/WORKFLOWS.md)
+
 ### 自动注入 + 会话摘要
 
 - **自动注入**：新会话开局注入记忆摘要（`summary` 优先 + 少量高重要性条目）
@@ -249,7 +267,13 @@ v0.3.0 起新增**记忆基因**层：从记忆里抽取**命名实体**、**带
 
 > 完整版本说明见 [CHANGELOG](CHANGELOG.md) 与各版本 [GitHub Release](https://github.com/slow-stack/mneme/releases)；当前特性以本 README 正文与[配置表](#-配置)为准。早期版本中的实验性功能（Wiki-Link、tag 系统等）已在 v0.7.11 移除，详见 CHANGELOG 对应条目。
 
-🧬 Gene → 🛡️ 审计加固 → 💤 Sleep Mode → 🕸️ 召回融合与图谱 → ✨ 面板体验 → 🌡️ 自进化记忆 → 🔐 作用域隔离 → 🌐 MCP 生态
+🧬 Gene → 🛡️ 审计加固 → 💤 Sleep Mode → 🕸️ 召回融合与图谱 → ✨ 面板体验 → 🌡️ 自进化记忆 → 🔐 作用域隔离 → 🌐 MCP 生态 → 🧭 M.O. 手法（项目级工作流，v0.9 beta）
+
+| 版本 | 主题 |
+|------|------|
+| **v0.9.0**（2026-10-17） | M.O.（Modus Operandi · 手法）beta：工作流本体住 `<项目>/.mneme/pipelines/`、候选分层与升格判据、面板清单与图同屏（`actionPipelineEnabled` 默认关）；设置面板折叠线挪到「新手之外」并按人话重写 22 个条目名（#427）；安全与供应链加固（39 条路由声明式鉴权、OSV 有漏洞即失败、发布带 provenance） |
+| **v0.9.1**（2026-10-18） | M.O. 从「看得见」跑到「跑得出账」：执行窗口由 `/mo-run start` / `/mo-run stop` 显式划开、运行账落 `<项目>/.mneme/pipelines/<id>.runs.jsonl`（账本坏了与从没跑过严格分开）、归属只出候选、观察旁挂与脱节检出、步骤 `assert` / `optional`、R1/R2 提议；沉淀链从真实会话日志挖 draft 工作流（判据恒 `null`，答案只能由人补）；人格定义页 v1 → v1.2（按 agent 寻址多卡，默认关）；面板、向量与检查更新的一圈修复（#448 / #450 / #460）；Release 正文改分层渲染 |
+| **v0.8.x** | 作用域隔离（agent / workspace 双维 + opt-in 硬过滤）、冲突队列人工裁决、生态化（stdio MCP server / 图召回轴 / 冷启动 / 注入截断） |
 
 ## 📦 安装
 
@@ -274,15 +298,44 @@ dsh web
 
 > 如需自定义配置（阈值、延迟等），可在 `~/.dsh/profiles/web/cordis.patch.yml` 中按 `id: dsh-mneme` 覆盖默认值（见下方配置表）。
 
-#### 方式二：从源码安装
+#### 方式二：从源码安装（本地目录）
 
 ```bash
 git clone https://github.com/slow-stack/mneme.git
-cd dsh-mneme
-dsh plugin --profile web add .
+cd mneme/dsh-mneme
+dsh plugin --profile web add "$(pwd)"
 dsh web
 ```
 
+> **路径必须绝对**：宿主对 `dsh plugin add` 的本地路径有一条硬校验（`parseInstallSpec` 里的 `a local path must be absolute`），相对路径（含 `.`、`..`）一律拒掉。上面用 `"$(pwd)"` 就地展开，就是为了不给它相对路径。
+
+#### 方式三：直接从 Git 仓库安装
+
+本仓库是**单仓多包**：仓库根那份 `package.json` 是**仓库壳**（`private`、不带 `dsh` 字段），插件本体在 `dsh-mneme/`。所以 Git 地址必须带 `#path:` 指到子目录：
+
+```bash
+dsh plugin --profile web add 'git+https://github.com/slow-stack/mneme.git#path:/dsh-mneme'
+dsh web
+```
+
+| 写法 | 结果 |
+|------|------|
+| `git+https://github.com/slow-stack/mneme.git#path:/dsh-mneme` | ✅ 装出 `@modusensus/dsh-mneme`（实测 0.9.0，38 个包） |
+| `https://github.com/slow-stack/mneme#path:/dsh-mneme` | ✅ 同上；lockfile 会归一成 `github:slow-stack/mneme#path:/dsh-mneme` |
+| `git+https://github.com/slow-stack/mneme.git` | ❌ 装到仓库根那份壳（`0.0.0`、无 `dsh` 字段），宿主不认它是插件 |
+
+`#path:` 是 pnpm 的 git 参数（`parseGitParams` 里按 `path:` 前缀解析），**不是**本仓库自定义的语法；pnpm 官方文档没写这一条，所以这里给出实测结果。
+
+#### 方式四：tarball
+
+```bash
+cd dsh-mneme
+npm pack                       # 产出 modusensus-dsh-mneme-<版本>.tgz
+dsh plugin --profile web add "C:/path/to/modusensus-dsh-mneme-0.9.0.tgz"
+```
+
+> 必须用 `npm pack`，别用 `pnpm pack`：`bin/cli.mjs` 在工作区里是 CRLF，pnpm 会以 `ERR_PNPM_BIN_CRLF` 直接失败。
+
 #### 自定义配置（可选）
 
 默认配置即可用。如需调整，在 `~/.dsh/profiles/web/cordis.patch.yml` 中覆盖：
@@ -443,7 +496,9 @@ dsh web
 | `conflictFreezeMaxPending` | `100` | 冲突冻结队列最大挂起数（1-1000）：超出后不再入队（防队列无限膨胀） |
 | `escapePromptVariables` | `true` | 注入文本花括号转义（v0.8.0 恢复，issue #162）：注入边界把 `{{...}}` 转义，防止 hot memory / 记忆原文里的 Go template / Vue 语法触发宿主 interpolate 抛错卡死会话（v0.7.4 曾修复、v0.7.11 误删） |
 
-> 🔐 **API 安全**：DSH 无内置鉴权且默认仅监听 `127.0.0.1`。插件 API 默认开放（便于 Web 面板即装即用）。如需防护（如局域网暴露），在配置中设置 `apiToken`：写操作（画像/规则/命令）与密钥端点（`vector-config`、`vector-reindex`）需携带 `Authorization: Bearer <token>`（前端设置面板可填入同一 token），只读的 `list` / `search` / `semantic` 保持开放。`/api/dsh-mneme/vector-config` 返回的 `apiKey` 已掩码（`sk-***…`），存储仍保留明文供调用；前端回传空或掩码值表示"不改 key"。
+> 🔐 **API 安全**：DSH 无内置鉴权且默认仅监听 `127.0.0.1`。插件 API 默认开放（便于 Web 面板即装即用）——**未配 `apiToken` 时读和写都开放**，真正的围栏是回环 + 宿主监听器的 Host/Origin 校验（它防 DNS rebinding 与跨站浏览器请求，但不建立身份）。如需防护（如局域网暴露），在配置中设置 `apiToken`：此时**写操作**（新增/更新/删除/导入/画像/规则/命令/开关/开关计费类）与**敏感读**（`/export`、`/external-api`、`/vector-config`、`/vector-reindex`、`/maintenance/*`、`/runtime/provision`）需携带 `Authorization: Bearer <token>`（前端设置面板填同一个 token）；只读的 `list` / `search` / `semantic` / `inject-preview` 等**仍然开放**，不要把它们当成被 token 保护的面。`/api/dsh-mneme/vector-config` 返回的 `apiKey` 已掩码（`sk-***…`），存储仍保留明文供调用；前端回传空或掩码值表示"不改 key"。
+>
+> 安全模型全表（哪些路由免鉴权、为什么）见 [SECURITY.md](../SECURITY.md#5-security-model-what-actually-protects-what)。
 
 
 > ⚠️ **已知边界：极简模式（minimal agent preset）下不注入**（宿主设计，非插件缺陷）：minimal 预设的组合文件显式 `complete: true` + `includeRuntimeContext: false`——整条系统提示词被 persona 钉死、全部 runtime context 快照被压制，**记忆注入 / 用户画像 / hot memory 在极简模式会话中一律不送达模型**（宿主内置 context 同样消失）。判断与解法：会话头部显示「极简模式」即为该形态；需要记忆注入请改用标准模式（会话级切换，或 `~/.dsh/settings.yaml` 设 `agent-presets.default: standard`——注意 `--dump-config` 显示的是 bundle 默认值，会被用户层覆盖，不能反映实际生效值）；极简模式下的过渡方案是把画像/规则写入 `AGENTS.md`（agent-instructions 走 section 路径，不受该压制影响）。
@@ -474,6 +529,7 @@ dsh web
 | `GET` | `/search?q&mode=keyword\|vector\|hybrid\|auto&topK&occurred_from&occurred_to&agent_scope&workspace_scope` | 搜索（关键词 / 向量 / hybrid=向量领位关键词补位 / 自动）。scope 两参声明调用方身份（不传 = 不解析，行为与旧版一致；任一给出则 strictScope 硬过滤与 A2 软加权随之生效） |
 | `GET` | `/context?q&topK&threshold&agent_scope&workspace_scope` | 注入候选一站式聚合（issue #370，#363 承诺）：宿主注入管线 `injectCandidates` 全语义（优先级分层 / 编码门控 / heat / scope 软加权 / hybrid 语义路 / pin 前置）+ 画像 + 规则，返回 `{profile, rules, items, pinnedCount}` 结构化条目，不含渲染文本。`threshold` 是 **importance 阈值**（默认 3，与 `/search` 的相似度阈值同名不同义）；`topK` 默认 5（对齐宿主 `maxInjectedItems`）；scope 语义与 `/search` 同口径；跨轮轮换 / 热记忆 / 时间前缀不含（调用方自管）；recall_runs 注入分账与宿主注入同口径（#217 `mode='inject'`） |
 | `POST` | `/bootstrap` | 冷启动（v0.8.4）：从仓库目录反向构建初始记忆，body `{dir}` 必填；幂等（(type,title,scope) 去重 + `_overwrite` 原地刷新），零 LLM、必有产出 |
+| `POST` | `/maintenance/reclaim` | 无损回收（#275 / #411，与面板同口径）：**只有 POST**（独立面没有 GET 预估分支）。字段只从 JSON body 读；`dryRun` 默认 `true`，只有 `dryRun:false` 且 `confirm:true` 才真删；`vacuum` 只允许显式指定 |
 
 ### curl 示例
 
@@ -584,7 +640,7 @@ Claude Code 挂载示例（项目根 `.mcp.json`；token 在面板「设置 →
 │  服务层：saveWithDedupe / injectCandidates        │
 │         / mergeHumanEdits / onWrite 钩子          │
 ├─────────────────────────────────────────────────┤
-│  模型接口：9 个工具 + 自动注入 + 会话摘要          │
+│  模型接口：10 个工具 + 自动注入 + 会话摘要         │
 ├─────────────────────────────────────────────────┤
 │  autoDream：阈值调度 → LLM 决策清单               │
 │            → 校验（fail-safe）→ 应用 → 摘要       │
@@ -602,7 +658,7 @@ src/
 ├── service.js        # 领域逻辑（去重合并、注入筛选、写入钩子、scope 加权/硬过滤、冲突队列）
 ├── scope.js          # 作用域解析（agentPreset + workspace registry 反查，issue #17）
 ├── config.js         # schemastery 配置 schema
-├── tools.js          # 9 个模型工具（defineTool）
+├── tools.js          # 10 个模型工具（defineTool）
 ├── inject.js         # systemPrompt.context 动态注入（含花括号转义）
 ├── summarize.js      # 会话结束 LLM 摘要
 ├── dream.js          # autoDream 调度 + runDream（LLM 决策 + 摘要）
@@ -617,8 +673,8 @@ src/
 ├── embedding.js      # OpenAI 兼容 embeddings 客户端 + 向量检索
 ├── api.js            # HTTP 路由（Web 面板数据通道，含 /conflicts 冲突队列）
 └── index.js          # 插件接线
-lib/                  # src 的同步分发产物（npm run sync；发布前由 root prepack 的 check-sync.js 校验一致性；唯一手写例外 lib/client.js——Web 面板 bundle，sync 不覆盖）
-test/                 # 1869 个 node:test 测试（审计与三轴线压测不变量；src↔lib 一致性由 scripts/check-sync.js 发布闸门校验）
+lib/                  # src 的同步分发产物（npm run sync，prepack 钩子在发布时自动跑；一致性由 scripts/check-sync.js 在 CI 与 release.yml 校验——它只查不同步；唯一手写例外 lib/client.js——Web 面板 bundle，sync 不覆盖）
+test/                 # 2173 个 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 运行时清单
 ```
 
@@ -627,7 +683,7 @@ scripts/              # e2e-dsh.js 端到端演示 · stress-dsh.js 三轴线压
 ```bash
 cd dsh-mneme
 npm install        # 安装 peer 依赖（以 devDependencies 形式，用于本地测试）
-npm test           # 运行 1869 个测试
+npm test           # 运行 2173 个测试
 npm run stress     # 三轴线压测：长会话检索 / 冲突仲裁 / 多 Agent 并发（离线 mock LLM）
 npm run sync       # 把 src/ 同步到 lib/（发布时由 prepack 钩子自动执行）
 ```
@@ -638,13 +694,19 @@ npm run sync       # 把 src/ 同步到 lib/（发布时由 prepack 钩子自动
 
 ## 📄 设计文档
 
-> 设计文档位于仓库根 `docs/`，链接以 `../docs/` 相对路径指向（GitHub 上从本目录打开可正常跳转）。
+> 设计文档在 `dsh-mneme/docs/`（本目录内，直接相对链接）；只有能力对比表在仓库根 `docs/`，用 `../docs/` 指过去。GitHub 上从本目录打开均可正常跳转。
 
 - [配置说明（全键参考）](docs/CONFIGURATION.md)
-- [蒸馏原文留存与记忆级溯源](docs/DISTILL.md)
+- [蒸馏原文留存与记忆级溯源](docs/DISTILL.md)（#399）
 - [实体结构化记忆设计](docs/ENTITIES.md)
 - [语义增强架构](docs/SEMANTIC.md)
 - [本地模型部署指南](docs/LOCAL_MODEL.md)
+- [工作流（M.O. · 手法）：本体住项目，证据住记忆库](docs/WORKFLOWS.md)
+- [连续性抢救（#249 N3）：触发器口径与事件契约](docs/CONTINUITY.md)
+- [Sleep Mode：空闲四阶段深度维护](docs/SLEEP.md)
+- [存储与回收：表结构、保留期、`dsh-mneme reclaim`](docs/STORAGE.md)
+- [独立服务 daemon（`dsh-mneme-serve`）](docs/DAEMON.md)
+- [与 Zep / Graphiti / Mem0 / Letta / Hindsight 的能力对比](../docs/COMPARISON.md)
 
 ## 🙏 致谢
 

package/bin/cli.mjs

@@ -19,8 +19,14 @@ const CLI_NAME = 'dsh-mneme';
 const DEFAULT_URL = 'http://127.0.0.1:8790';
 const CONFIG_DIR = path.join(os.homedir(), '.dsh-mneme');
 const CONFIG_PATH = path.join(CONFIG_DIR, 'cli.json');
-const MEMORY_TYPES = ['preference', 'project', 'decision', 'summary', 'history'];
-const SEARCH_MODES = ['keyword', 'vector', 'auto'];
+// 与 src/store.js 的 TYPES 对齐（CLI 是零依赖 HTTP 客户端，不 import 服务端
+// 模块，所以这里是手写字面量）。document 是唯一例外：它只能经
+// memory_register_document 铸造，saveWithDedupe 会拒绝旁路写入，所以不作为
+// --type 的选项——test/cli-enums.test.js 锁住「差值恰好是 document」。
+const MEMORY_TYPES = ['preference', 'project', 'decision', 'history', 'summary', 'pattern', 'rejected_solution', 'pitfall', 'constraint'];
+// hybrid：API 的 searchMemories 支持（向量先、关键词补位、双路命中做分数混合，
+// 见 src/api.js 的 mode 注释）。此前漏列，search --mode hybrid 会被客户端自己拒掉。
+const SEARCH_MODES = ['keyword', 'vector', 'auto', 'hybrid'];
 const REQUEST_TIMEOUT_MS = 10_000;
 
 function readPkgVersion() {

package/docs/CONFIGURATION.md

@@ -43,6 +43,7 @@
 |---|---|---|---|
 | `writeAdmission.enabled` | `false` | 跑第 1 级确定性判据：空白 / 纯噪声 + 密钥 / PII（判据来源是 #164 A2，经 `sensitiveScan` 注入） | 关 = 不判定、不拒绝，`evaluate` 返回与只计量阶段逐字段一致。命中 → 审计行带 `metadata.deny` |
 | `writeAdmission.enforce` | `false` | 命中时真的拒绝（`store.save` 之前返回） | 关 = 仅告警：判据照跑、审计照留、写入不拦（读审计时「`deny` 非空且 `decision=allow`」即这一档的指纹）。被拒写入不落库、不通知、不排嵌入，`memory_save` 返回 `action:"denied"` + `reason` |
+| `sensitiveScanEnabled` | `false` | A2 密钥 / PII 判据的来源（`sensitive-scan.js`）。开 = 判定结果可被写入准入消费；只覆盖带 sessionKey 的写入路径 | 关 = 扫描器不参与，`writeAdmission` 第 1 级只剩空白/噪声判据。**经 MCP / 8790 / `/import` 的写入不带 sessionKey，不进这道闸**（`write-admission.js` 的文件头注释点名了这条边界） |
 
 第 1 级的判据面刻意收窄：**去重键命中不进第 1 级**（归 write-update 放行——同步近重复门跑在异步矛盾检测之前会把本该被裁决的矛盾直接拒掉），G1/G2 阈值也只是计量。两个键都走 feature_flags 白名单（面板可启停）。
 
@@ -114,6 +115,8 @@
 | `hotMemoryRounds` | `5` | 热记忆覆盖最近几轮对话（≤50） | — |
 | `hotMemoryMaxTokens` | `2000` | 热记忆块 token 上限（200–32000） | — |
 | `escapePromptVariables` | `true` | 注入内容连续花括号转义（#162） | 关 = 原样透传（DSH interpolate 可能 throw） |
+| `injectTimePrefix` | `false` | 对话开始注入一次当前时间（#34，v0.7.11 误删后随 #333 恢复） | opt-in；格式与键名与 v0.7.2 一致，存量 feature_flags 恢复即生效 |
+| `personaEnabled` | `false` | 人格段：用户自写的一小段常驻注入文本 | opt-in；只是轻量常驻文本、不引入重型后台路径，故不进 `LIGHT_MODE_OFF` |
 
 ## 巩固（autoDream）
 
@@ -223,6 +226,21 @@
 | `rerankScoreThreshold` | `0.1` | 重排分数阈值 | — |
 | `rerankDtype` | `q8` | 量化档（#188） | 非法值由 transformers 抛出 → 重排降级告警 |
 
+## 图谱（graph，opt-in，#24）
+
+图谱四条链路都依赖实体抽取产出（`entityExtractionEnabled`），默认全关；lightMode 把前四个布尔键一并强制关。级联与预算键只是阈值，跟着开关走。
+
+| 键 | 默认 | 作用 | 开启后果 / 冲突 |
+|---|---|---|---|
+| `graphAnchoringEnabled` | `false` | 块1 图谱锚定：以查询命中的实体为种子沿关系表级联扩散（默认深度 2） | opt-in；关 = 与 #219 单跳轴逐字节一致；需 `entityRecallEnabled` 之上再开 |
+| `graphSeedCap` | `12` | 锚定种子集上限（1–30） | 只影响一次扩散的宽度 |
+| `graphCascadeDepth` | `2` | 级联深度（1–3） | 深度与召回面线性相关，3 容易把远邻拉进来 |
+| `graphWeightEnabled` | `false` | 块2 边权重演化：被寻回路径的边权重抬升（只加不减、封顶 1.0） | opt-in；关 = 边初值纯由建边来源决定 |
+| `graphWeightDelta` | `0.1` | 单次有效触达的抬升幅度（0–1） | 与其他 graph 开关无关的纯阈值 |
+| `graphPassiveConfirm` | `false` | 块4 被动确认：heat 触达（召回/注入）即给挂联关系边抬一格 | opt-in；关 = 零行为变化 |
+| `graphInjectHint` | `false` | 块3 关联提示标注：图召回候选在注入文本里以「[检索线索] …」标出 | 关 = 只参与排序、不改变注入块构成（保守档） |
+| `graphInjectBudget` | `1` | 图召回候选在注入块里的独立预算（0–5 条） | 不占 `maxInjectedItems` 名额；0 = 关闭 |
+
 ## 热度
 
 | 键 | 默认 | 作用 | 开启后果 / 冲突 |
@@ -242,6 +260,8 @@
 | `externalApiHost` | `127.0.0.1` | 绑定地址 | 改成非回环 = 把整个记忆库暴露给网络，自负其责 |
 | `disableMemorySearch` | `false` | 对模型隐藏 `memory_search` 工具（v0.8.5） | 慢/轻量模型的工具往返节流；隐藏即不可调 |
 | `disableMemoryArchive` | `false` | 对模型隐藏 `memory_archive` 工具 | 同上 |
+| `actionPipelineEnabled` | `false` | M.O.（手法）只读视图的门控：做法图谱 + 对话行结算卡 | opt-in beta；只是纯 UI 入口、不引入重型后台路径，故不进 `LIGHT_MODE_OFF`。写账另有独立的执行记账键（`/mo-run`），看图 ≠ 写账 |
+| `actionRunEnabled` | `false` | M.O. 执行记账：`/mo-run` 开一次执行窗口，窗口内命令执行才可能被记成一条 run | opt-in beta；挂在热路径（每个会话事件都过一次监听），故 `LIGHT_MODE_OFF` 里有它 |
 
 ## 运行时与本地模型
 
@@ -260,6 +280,9 @@
 | `runtimeDir` | `""` | 自管运行时目录（transformers + onnxruntime 闭包，#131） | 空 = `~/.dsh/mneme/runtime`；把重依赖挪出宿主 profile 的依赖图 |
 | `runtimeTarballDir` | `""` | 本地 `.tgz` 离线取件目录 | 有货优先于联网（弱网下装 onnxruntime-node 用） |
 | `runtimeMirror` | `""` | registry 镜像前缀（如 `https://npmmirror.com/mirrors/npm/`） | 空 = manifest 里的官方地址 |
+| `reindexMaxPerBoot` | `500` | 启动期向量回填的单次上限（原先硬编码 500） | `0` = 不限、本次跑完整个积压（4k 行积压靠重启九次才清空的旧行为就是被这个上限卡住的） |
+| `reindexBatchSize` | `10` | 回填批大小（1–64） | 越大单批 token/耗时越高 |
+| `reindexRateLimitMs` | `200` | 回填批间隔毫秒（限速） | 0 = 不限速 |
 
 ## lightMode 强制关闭清单（`LIGHT_MODE_OFF`）
 
@@ -269,6 +292,8 @@
 `entityExtractionEnabled` · `autoDream` · `sleepModeEnabled` · `rerankEnabled` ·
 `autoReindexOnBoot` · `hybridInject` · `injectGuidanceEnabled` · `searchSemanticDedup` ·
 `selectiveInjectEnabled` · `bm25SearchEnabled` · `entityRecallEnabled` ·
+`graphAnchoringEnabled` · `graphWeightEnabled` · `graphInjectHint` · `graphPassiveConfirm` ·
+`actionRunEnabled` ·
 `dreamNarrativeEnabled` · `documentMemoryEnabled` · `heatEnabled` · `continuityRescueEnabled` ·
 `preInjectGate.enabled`（#380） · `distillRecords.enabled`（#399）
 

package/docs/SEMANTIC.md

@@ -3,7 +3,7 @@
 - **日期**：2026-08-15
 - **状态**：✅ 已实现（本地 Embedding / Rerank / 聚类随 v0.2+ 落地；本文档转为历史设计存档，当前能力以 [README](../README.md) 正文为准）
 - **范围**：为 dsh-mneme 增加"完全离线的语义记忆引擎"，覆盖本地 Embedding、Rerank 精排、autoDream 向量聚类三个阶段
-- **相关文档**：[本地模型部署指南](LOCAL_MODEL.md) · [从 v0.1 升级说明](MIGRATION.md)
+- **相关文档**：[本地模型部署指南](LOCAL_MODEL.md) · [全键配置参考](CONFIGURATION.md)
 
 ## 1. 背景与目标
 
@@ -59,7 +59,7 @@ scripts/
 docs/
 ├── SEMANTIC.md         # 本文档
 ├── LOCAL_MODEL.md      # 本地模型部署指南
-└── MIGRATION.md        # 从 v0.1 升级说明
+└── CONFIGURATION.md    # 全键配置参考
 ```
 
 ## 3. 搜索流水线
@@ -207,7 +207,7 @@ LocalEmbedder(ONNX) ──失败──► OllamaEmbedder ──失败──► O
 
 ## 7. 配置新增项
 
-见 [MIGRATION.md](MIGRATION.md) 完整表格。核心：`embedProvider`（`local` / `ollama` / `openai`，默认 `openai` 保持 v0.1 行为）、`localEmbedModel`、`localEmbedDimension`、`localEmbedDevice`、`localEmbedBatchSize`、`ollamaBaseUrl`、`ollamaModel`、`embedModelCacheDir`、`rerankEnabled`、`rerankModel`。
+见 [CONFIGURATION.md](CONFIGURATION.md) 的检索与运行时键表。核心：`embedProvider`（`local` / `ollama` / `openai`，默认 `openai` 保持 v0.1 行为）、`localEmbedModel`、`localEmbedDimension`、`localEmbedDevice`、`localEmbedBatchSize`、`ollamaBaseUrl`、`ollamaModel`、`embedModelCacheDir`、`rerankEnabled`、`rerankModel`。
 
 ## 8. 测试与基准
 

package/lib/api-standalone.js

@@ -23,6 +23,12 @@ import { parseReclaimJson, readReclaimFields, reclaimReply, RECLAIM_UNAVAILABLE
 const DEFAULT_PORT = 8790;
 const DEFAULT_HOST = "127.0.0.1";
 const MAX_PORT_ATTEMPTS = 20;
+// 请求体与分页上界（防御，不是功能）：与宿主内 api.js 的 MAX_REQUEST_BODY_BYTES /
+// MAX_PAGE_LIMIT / MAX_SEARCH_TOP_K 同值同义——两张数据面的口径必须一致，否则
+// 「从哪张脸进来」会决定一次请求能吃掉多少内存。
+const MAX_REQUEST_BODY_BYTES = 4 * 1024 * 1024;
+const MAX_PAGE_LIMIT = 1000;
+const MAX_SEARCH_TOP_K = 200;
 
 /**
  * Listen with automatic EADDRINUSE recovery. Tries the configured port, then
@@ -86,13 +92,35 @@ function isAuthorized(req, apiToken) {
   return timingSafeEqual(Buffer.from(token), Buffer.from(apiToken));
 }
 
-/** Collect the request body as text (tolerant of transport errors). */
-function readBody(req) {
+/**
+ * Collect the request body as text, or null when it exceeds the cap.
+ *
+ * 超限时**必须回 null 而不是空串**：空串经 parseBody 变成 {}，而 /profile、
+ * /rules、/persona 的 PUT 会把「字段缺失」当成「用户要清空」——一个 5 MiB 的
+ * 请求就能把画像/规则/人格静默清掉。返回 null 让调用点在碰任何 store 之前
+ * 直接 413（2026-10 评审指出的数据损坏路径）。
+ * 连接不 destroy：调用方要能收到明确的 413，而不是被掐断。
+ */
+function readBody(req, res) {
   return new Promise((resolve) => {
     let body = "";
-    req.on("data", (chunk) => { body += chunk; });
-    req.on("end", () => resolve(body));
-    req.on("error", () => resolve(""));
+    let bytes = 0;
+    let overflow = false;
+    req.on("data", (chunk) => {
+      if (overflow) return;
+      bytes += chunk.length;
+      if (bytes > MAX_REQUEST_BODY_BYTES) {
+        overflow = true;
+        body = "";
+        sendJson(res, 413, { error: "payload-too-large", limit: MAX_REQUEST_BODY_BYTES });
+        return;
+      }
+      body += chunk;
+    });
+    req.on("end", () => resolve(overflow ? null : body));
+    // 超限后再来 transport error 也必须保留超限状态：否则调用点会拿着空串
+    // 继续往 store 写（PUT /persona 把 "" 解析成 {}，覆盖既有设置）。
+    req.on("error", () => resolve(overflow ? null : ""));
   });
 }
 
@@ -323,6 +351,38 @@ export function createStandaloneApi({ service, store, config = {}, logger, setti
         return;
       }
 
+      // --- GET /persona: agent persona（人格定义页，beta；v1.2 多卡形） --------
+      if (req.method === "GET" && pathname === "/persona") {
+        sendJson(res, 200, { persona: settings?.getPersona?.() ?? { default: {}, byAgent: {} } });
+        return;
+      }
+
+      // --- PUT /persona: write default (single-object form) or full multi-card
+      // 形状判定在 setPersona 内（settings.js 双形兼容：单对象=合并 default、
+      // 多卡=全量替换）；坏 JSON 回 400（与 /memories 写路径同口径）。
+      if (req.method === "PUT" && pathname === "/persona") {
+        void readBody(req, res).then((text) => {
+          if (text === null) return;
+          let body;
+          try {
+            body = JSON.parse(text || "{}");
+          } catch {
+            sendJson(res, 400, { error: "invalid-json" });
+            return;
+          }
+          const persona = body && typeof body === "object" && !Array.isArray(body) && body.persona && typeof body.persona === "object"
+            ? body.persona
+            : body;
+          try {
+            settings?.setPersona?.(persona && typeof persona === "object" ? persona : {});
+            sendJson(res, 200, { persona: settings?.getPersona?.() ?? { default: {}, byAgent: {} } });
+          } catch {
+            sendJson(res, 500, { error: "internal" });
+          }
+        });
+        return;
+      }
+
       // --- GET /rules: agent behavior rules -----------------------------------
       if (req.method === "GET" && pathname === "/rules") {
         sendJson(res, 200, { rules: settings?.getRules?.() ?? [] });
@@ -333,7 +393,8 @@ export function createStandaloneApi({ service, store, config = {}, logger, setti
       //     internal /api/dsh-mneme/list) ------------------------------------
       if (req.method === "GET" && pathname === "/memories") {
         const type = url.searchParams.get("type") ?? undefined;
-        const limit = Number(url.searchParams.get("limit") ?? 50);
+        // 上界是防御：limit 直接进 SQL LIMIT（见 MAX_PAGE_LIMIT 注释）。
+        const limit = Math.min(Number(url.searchParams.get("limit") ?? 50), MAX_PAGE_LIMIT);
         const offset = Number(url.searchParams.get("offset") ?? 0);
         const order = url.searchParams.get("order") ?? undefined;
         const minRaw = url.searchParams.get("minImportance");
@@ -384,7 +445,8 @@ export function createStandaloneApi({ service, store, config = {}, logger, setti
         // 整个异步回调套 try/catch：service 抛错不能变成未处理拒绝（Node 默认
         // 策略下会终止宿主进程）或悬着不回的请求（外层同步 try 捕不到这里）。
         if (req.method === "PUT") {
-          void readBody(req).then(async (text) => {
+          void readBody(req, res).then(async (text) => {
+            if (text === null) return;
             try {
               await handlePutBody(res, service, logger, id, text);
             } catch (error) {
@@ -400,7 +462,8 @@ export function createStandaloneApi({ service, store, config = {}, logger, setti
 
       // --- POST /memories: save with title-dedupe (safer than raw save) ------
       if (req.method === "POST" && pathname === "/memories") {
-        void readBody(req).then((text) => {
+        void readBody(req, res).then((text) => {
+          if (text === null) return;
           let body;
           try {
             body = JSON.parse(text || "{}");
@@ -488,7 +551,8 @@ export function createStandaloneApi({ service, store, config = {}, logger, setti
       // /api/dsh-mneme/maintenance/reclaim 共用 src/reclaim-http.js，两张皮只有鉴权
       // 与路径不同。这条曾经是整段复制的，于是面板侧修好之后这边还停在旧形态（#411）。
       if (req.method === "POST" && pathname === "/maintenance/reclaim") {
-        void readBody(req).then((text) => {
+        void readBody(req, res).then((text) => {
+          if (text === null) return;
           const parsed = parseReclaimJson(text);
           if (!parsed.ok) {
             sendJson(res, 400, { error: parsed.error });
@@ -521,7 +585,8 @@ export function createStandaloneApi({ service, store, config = {}, logger, setti
       // 显式收 dir（插件没有工作区根目录概念，不猜路径）；确定性解析零 LLM；
       // 幂等骑 saveWithDedupe 的 (type, title, scope) 去重 + _overwrite 刷新。
       if (req.method === "POST" && pathname === "/bootstrap") {
-        void readBody(req).then((text) => {
+        void readBody(req, res).then((text) => {
+          if (text === null) return;
           let body;
           try {
             body = JSON.parse(text || "{}");
@@ -554,7 +619,8 @@ export function createStandaloneApi({ service, store, config = {}, logger, setti
       // --- GET /search: unified recall pipeline (keyword + vector + BM25) ----
       if (req.method === "GET" && pathname === "/search") {
         const q = url.searchParams.get("q") ?? "";
-        const limit = Number(url.searchParams.get("topK") ?? url.searchParams.get("limit") ?? 20);
+        // 上界是防御：topK 直接进召回（见 MAX_SEARCH_TOP_K 注释）。
+        const limit = Math.min(Number(url.searchParams.get("topK") ?? url.searchParams.get("limit") ?? 20), MAX_SEARCH_TOP_K);
         const mode = url.searchParams.get("mode") ?? "auto";
         const rerank = url.searchParams.get("rerank") !== "false";
         const occurredFrom = url.searchParams.get("occurred_from") ?? null;
@@ -599,7 +665,7 @@ export function createStandaloneApi({ service, store, config = {}, logger, setti
       if (req.method === "GET" && pathname === "/context") {
         const q = (url.searchParams.get("q") ?? "").trim();
         const maxItemsRaw = Number(url.searchParams.get("topK") ?? url.searchParams.get("limit") ?? 5);
-        const maxItems = Number.isInteger(maxItemsRaw) && maxItemsRaw > 0 ? maxItemsRaw : 5;
+        const maxItems = Number.isInteger(maxItemsRaw) && maxItemsRaw > 0 ? Math.min(maxItemsRaw, MAX_SEARCH_TOP_K) : 5;
         // threshold 是 importance 阈值（injectCandidates 语义），与 /search 的
         // 相似度 threshold 同名不同义——文档已点名，勿混。
         const thresholdRaw = Number(url.searchParams.get("threshold") ?? 3);