rafa-elricardo/bmpp

BMPP — 面向 DeepSeek Harness 的基础记忆策略插件

一个原生的 DeepSeek Harness（DSH）插件，它将智能体记忆策略中可机械检查的部分移入运行时，同时将所有语义决策留给模型。

状态：实验性 / alpha。 BMPP 可以正常工作，并有自动化测试套件覆盖，但其 API 和配置模型仍可能在不同版本之间发生变化。它并非经过生产加固的产品，也不隶属于 DeepSeek 项目，亦未获得其认可。

什么是 BMPP？

使用记忆系统的智能体会有一套针对它的策略：先搜索再写入、不要重复已有笔记、不要未经核对实时系统就信任召回的值。其中一些策略只能由模型来判断——某条记忆是否值得保留、某条笔记是否已经涵盖它、某个召回的事实是否仍然为真。BMPP 不触碰这一部分。 它把语义判断留在其应在之处，并且从不读取笔记内容或用户文本。

策略的其余部分是机械性的：在这次写入之前，记忆搜索是否确实完成了？ 那次搜索是否失败了？ 这是否是同一轮中的同一次写入重复出现？ 这些问题由运行时已经发出的事件来回答，因此 BMPP 以确定性的方式判定并强制执行它们。

BMPP 位于模型与 mcp__basic-memory__ 工具之间。当模型尝试更改记忆时，BMPP 会检查前置条件，要么放行该调用，要么阻止它并给出模型可以据此采取行动的解释。

范围： BMPP 仅管辖 mcp__basic-memory__ 命名空间。它不会阻止 bash、edit、write、文件系统或任何其他工具，也不是通用的智能体安全策略。

工作原理

每一轮都有一个分类，而 BMPP 的门控是它的函数。

| 分类 | 含义 | 对记忆写入的影响 | 对读取的影响 |
|---|---|---|---|
| unknown | 模型尚未声明任何内容 | 阻止 | 允许 |
| simple | 模型声明该轮为琐碎任务 | 允许，无需查找 | 允许 |
| complex | 模型声明该轮需要记忆 | 仅在同一轮中成功查找后才允许 | 允许 |

模型通过 BMPP 自己的控制工具 bmpp__classify 声明分类：

{"task": "complex"}

它可以在该轮中的任意时刻被调用——不必是第一个调用——而一轮中从未声明任何内容的会保持为 unknown，这允许读取并阻止写入。

召回。 对于 complex 轮次，BMPP 会监视记忆搜索工具（search_notes、search、build_context）。成功完成的搜索会满足召回前置条件；失败的搜索会让门控保持关闭，并告知模型重试。BMPP 不解析搜索结果——它读取运行时已经提供的结构化错误标志，
因此，一个诚实的空结果仍然算作一次完成的查找。

变更门控。 一次记忆写入会按顺序接受以下检查：

1. 分类（unknown → 被阻止）；
2. 是否完成了一次查找，以及它是否成功；
3. 一次查找和一次写入是否被打包进同一个并行批次；
4. 是否在未先读取的情况下覆盖一条现有笔记。

每个决定都带有一个稳定的原因代码（CLASSIFICATION_REQUIRED、
CREATE_REQUIRES_SEARCH、MEMORY_LOOKUP_REQUIRED、MEMORY_LOOKUP_FAILED、
MEMORY_LOOKUP_PENDING_IN_BATCH、OVERWRITE_REQUIRES_READ……），因此被阻止的调用会得到解释，而不是被吞掉。

轮次生命周期。 BMPP 的状态是按会话、按轮次维护的。当 Harness 轮次推进时，上一轮的分类和召回状态会被丢弃，因此在一轮中获得的授权绝不会在下一轮中被复用。BMPP 尚未评判过的会话完全不受影响。

模式

mode 决定裁决是被应用还是仅仅被记录。

| 模式 | 是否裁决 | 是否应用 | 能否拒绝或询问？ |
|---|---|---|---|
| off | 否 | 否 | 否——不注册任何内容 |
| audit | 是 | 否 | 从不——每次调用都会继续，而它想要的拒绝会被记录下来 |
| enforce | 是 | 是 | 是——唯一会阻止的模式 |

audit 从不阻止，无论 profile 怎么设置。 它是安全的第一步：你能获得 BMPP 本会做什么的完整证据，而行为不发生任何变化。

Profile

profile 决定策略有多严格。它从不改变 mode。

| Profile | 效果 |
|---|---|
| compat | 次级防护发出警告；破坏性操作走正常门控 |
| strict | 次级防护拒绝；破坏性操作请求批准，而不是直接拒绝 |

两个 profile 之间只有三个选项不同。其他一切——包括 unknown 何时阻止写入，以及创建何时需要搜索——在两者中完全相同。

默认值：mode: audit + profile: compat。

支持的 DSH 版本

BMPP 0.1.0  →  DSH >= 0.1.5-rc.2 =0.1.5-rc.2 "

该覆盖层是本机专用的，并被 gitignore。examples/ 中存放可分发配置片段。

安装到 profile

from a local checkout or a packed tarball
pnpm run build && pnpm pack
dsh plugin --profile  add ./dsh-bmpp-0.1.0.tgz

dsh plugin add 会在 profile 内运行 pnpm，链接该包并将 bundle 追加到 profile 的有序 bundle 列表中。BMPP 尚未发布到包注册表，因此目前只能通过本地路径或 tarball 来安装。

机制、替代方案以及选择 bundle 形式背后的理由：
docs/DISTRIBUTION.md。

配置

两个相互独立的维度，在一行中配置。没有 strict 布尔值，也没有第二种方式来设置同一件事。

- insert:
- id: bmpp
name: 'dsh-bmpp'
config:
mode: audit        # off | audit | enforce
profile: compat    # compat | strict

schema 会在加载时拒绝未知键和无效值，因此拼写错误会导致启动失败，而不是静默地禁用某个防护。

examples/ 中为每种组合都包含一个现成片段：config.off.yml、config.audit.yml、config.enforce.yml、config.strict.yml。

示例

一个从不进行分类的回合 → 写入被阻止，读取不受影响。

model:  mcp__basic-memory__read_note   { identifier: "some-note" }
→ allowed            (reads are never blocked)

model:  mcp__basic-memory__write_note  { title: "New note", … }
→ denied             CLASSIFICATION_REQUIRED
→ "this turn has not been classified … call bmpp__classify first"

一个 simple 回合 → 无需查找即可允许写入。

model:  bmpp__classify                 { task: "simple" }
→ allowed            ALLOW_CONTROL

model:  mcp__basic-memory__write_note  { title: "New note", … }
→ allowed            ALLOW_SIMPLE

一个 complex 回合在未搜索的情况下写入 → 被阻止。

model:  bmpp__classify                 { task: "complex" }
→ allowed            ALLOW_CONTROL

model:  mcp__basic-memory__write_note  { title: "New note", … }
→ denied             CREATE_REQUIRES_SEARCH
→ "creating a note requires searching for the subject first … Search, then retry."

一个 complex 回合先搜索 → 写入被允许。

model:  bmpp__classify                  { task: "complex" }
→ allowed            ALLOW_CONTROL
model:  mcp__basic-memory__search_notes { query: "…" }
→ allowed            ALLOW_READ_ONLY
→ recall settled: succeeded

model:  mcp__basic-memory__write_note   { title: "New note", … }
→ allowed            ALLOW_RECALL_OK

在 mode: audit 下，上述每一行“denied”都会被记录为一次拒绝，并且仍然被允许。真正的阻断需要 mode: enforce。

架构

BMPP 是一个 Cordis 插件，通过 Harness 的公共插件 API 注册。它将 Harness 作为依赖使用，从不分叉它。

| 组件 | 角色 |
|---|---|
| src/state.ts | 纯策略状态机：decide() 返回裁决、原因和决策事件。mode 和 profile 被有意排除在其输入之外，因此该状态机不会受到执行设置的影响。 |
| src/gate.ts | 集成层：订阅 tools/pre-execute 和 tools/result，解析当前轮次，在裁决之后应用 mode/profile，并注册 bmpp__classify 控制工具。 |
| src/config.ts | 经过验证的 mode × profile 模型以及工具类别列表。 |
| src/version.ts | BMPP 自身的版本行以及 Harness 兼容性包络、检测与分类。 |
| src/audit-sink.ts、src/audit-store.ts | 审计记录模式以及持久化 sidecar 存储。 |
| src/index.ts | Cordis 入口点：配置验证、加载时表面探测、兼容性决策以及挂载。 |

工具拦截。 BMPP 根据它已经接收到的工具名称对调用进行分类。内存命名空间之外的调用被原样委托；读取被允许；写入和破坏性操作被门控。它仅在守卫所需的范围内检查工具参数（目标路径和 overwrite 标志），从不检查笔记内容。

轮次生命周期。 当宿主提供 sessionProjections 服务时，当前 Harness 轮次从该服务读取，否则从内部计数器读取。推进轮次会丢弃上一轮次的分类和召回状态。

宿主版本检测。 Harness 在其上下文中不暴露版本服务，因此 BMPP 从承载它的进程的应用程序清单——即正在运行的入口点自身的 package.json——读取版本，并回退到从该入口点解析出的 Harness 标识包。以入口点为锚点很重要：从 BMPP 自身的模块解析会读取 BMPP 自身固定的依赖，并将开发依赖报告为宿主版本。

不从 Harness 导入值。 生成代码中的每个 @deepseek-ai/ 导入都是类型导入，并在编译时被擦除；运行时访问通过注入的上下文进行。有一项测试针对构建输出断言这一点，这正是使 BMPP 真正独立而非 Harness monorepo 的一个片段的原因。

审计

BMPP 记录每一个决策——裁决、其原因代码、工具类别、策略状态、
执行结果、轮次和分类。它只记录元数据：没有工具参数、没有笔记内容、没有用户文本。

审计不会写入 DSH 会话事件日志。 它存放在一个存储 sidecar 中：一个由插件拥有的域（bmpp_audit，版本 1，按记录布局），通过 Harness 的公共 storageDomain 服务打开，该服务将其存储在 $DSH_HOME/storages/bmpp_audit/ 下。

这一点有具体的理由。Harness 不认识的会话事件类型是读取时必需的：读取器遇到无法识别的事件时必须拒绝重建会话，而不是静默跳过它，而公共的 Session.append API 没有为插件提供任何方式来将自己的事件类型标记为可安全省略。因此，将插件自创的类型写入会话日志会使每个被审计的会话变得不可观测且无法恢复。将审计保留在其自己的域中，可使会话日志能被任何 Harness 构建版本解释，并保持审计的持久性和可查询性。

存储是一个可选依赖。如果某个组合没有挂载存储服务，BMPP 仍会执行每条规则，并报告它无法持久化的记录；日志故障永远不会变成策略故障，审计失败也永远不会将允许变为拒绝。

限制

诚实的、当前状态的限制：

- 实验性。 配置模型和原因码词汇表仍可能发生变化。
- 仅限 Basic Memory。 该门控仅管辖 mcp__basic-memory__，别无其他。
- 读取永远不会被阻止。 BMPP 没有禁止读取的概念。
- 召回结果为 ok 或 failed。 Basic Memory 没有为其搜索工具声明输出 schema，因此空但成功的搜索与有结果的搜索无法区分。BMPP 拒绝解析结果文本来猜测；RECALL_EMPTY 仍被建模但不可达。
- 次级防护是部分的。 未读取即覆盖的防护已实现。秘密模式和测试夹具防护已建模且可配置，但尚未强制执行。
- 独立的 Python 回归层已过时。 tools/emit-policy-stream.mts 和 tools/bmpp_verify.py 是针对早期设计编写的，当时审计是一个 bmpp/policy 会话事件。由于审计已移至存储 sidecar，该层不读取任何事件，也不验证任何内容。TypeScript 测试套件是当今权威的验证手段。
- 不是沙箱，也不是安全边界。 BMPP 执行的是记忆策略；它并不限制 agent。

开发
sh
pnpm install
pnpm run typecheck
pnpm test
pnpm run build    # emits lib/, which is never committed

需要 Node.js ^22.19.0 || >=24.0.0 和 pnpm。pnpm test 也会构建项目，因为有一个测试套件会检查生成的 JavaScript，以证明该插件没有导入任何 Harness 值。

有关如何提出更改，请参阅 CONTRIBUTING.md。

AI 辅助开发
BMPP 采用 AI 辅助工作流开发，包括 LLM 辅助的实现、测试、调试和文档编写，以迭代式（“氛围编程”）风格进行。之所以直白说明这一点，是因为这是事实，也因为它与你应如何评估该项目相关。

这并非作为任何方向上的质量保证。项目所依赖的，反而是可验证的行为：一套针对真实工具注册表进行测试的测试套件、一个会大声失败而非静默错误执行的兼容性边界，以及上文记录的局限性。请把测试——而非文字描述——当作主张的依据。

安全

关于如何报告漏洞，请参阅 SECURITY.md。请不要为安全问题公开提交 issue。

贡献

请参阅 CONTRIBUTING.md。欢迎贡献，包括针对你认为策略处理有误的行为提交 issue。

许可证

MIT —— 请参阅 LICENSE。

BMPP 是一个独立的第三方插件。它不属于 DeepSeek Harness 仓库，也未与 DeepSeek 项目关联或获得其认可。

Português

本 README 的葡萄牙语版本位于 README.pt-BR.md。