pawin-brain-deepseek-harness

---

[!NOTE] 这是 Pawin 项目出品的独立社区插件 —— 不是 DeepSeek 官方产品。

类脑的理念

Pawin Brain 不是记忆插件——它是一个类脑的 agent 运行时，围绕一条闭环：

记住 ──► 自己纠错 ──► 学习
  ▲                      │
  └──────────────────────┘

• 记住——记不住过去的 agent，不可能从过去里学。
• 自己纠错——把矛盾、反复失败、证据缺失摆到台面上，而不是糊弄过去。
• 学习——一条教训只有让"之后的、不同的会话真的改变了行为"才算数，光给自己写个笔记不算。

v0.1 交付的是「记住」这一环——海马体。它刻意排在最先：后面每一环读的，都是这一环写下的东西。

v0.1 交付了什么

面向 DeepSeek Harness 的、经过完整测试的第一块：

1. 每轮注入——最近几天的日记在每轮开始时进入模型上下文。
2. brain_note——把值得记住的事追加进当天日记。
3. brain_recall——多关键词 AND 检索历史日记。

记忆就是目录里的纯 Markdown 文件。没有数据库、没有网络、没有外部服务。删掉目录，记忆就清空。

路线图

闭环的后两环——自己纠错（冲突监控、反复失败检测）与学习（行为差分证明）——正在积极开发，会以后续版本发布。记忆先发，是因为其余每一环都依赖它。

<memoryRoot>/
└── diary/
    ├── 2026-08-13.md   # 只追加，每行一条 [HH:MM] 条目
    └── 2026-08-12.md

快速开始

在 DeepSeek Harness 源码检出目录里运行：

pnpm dsh web --patch examples/demo.cordis.yml

打开 http://127.0.0.1:3080 说：

记一下，我最喜欢的茶是乌龙茶。

然后开一个新会话（不需要重启服务）：

我最喜欢什么茶？用 brain_recall 查一下记忆。

agent 会从磁盘上的日记里把它捞回来。

工作原理

flowchart LR
    U[用户消息] --> P[agent/pre-step]
    P -->|注入今日日记| M[模型请求]
    M -->|调用| N[brain_note]
    M -->|调用| R[brain_recall]
    N --> D[(diary/YYYY-MM-DD.md)]
    R --> D
    D -->|下一轮| P

• 注入挂在 agent/pre-step（瀑布式事件）上，每轮只追加一条带来源的消息——同一轮不重复注入，日记为空时零 token。
• 工具走常规 ctx.tools 注册表：运行时参数校验、沙箱策略、审批、卸载回收都和官方工具一个待遇。
• 存储只追加（O_APPEND），并发追加不会互相覆盖。

安全边界

dsh-brain 把日记当不可信输入、把文件系统当敌对环境：

边界	行为
日期	严格 YYYY-MM-DD 加日历往返校验；2026-02-30 直接拒绝
路径穿越	日期参数层拒绝；路径拼接层还留一道防御检查
符号链接	三层全拒：记忆根目录、diary/ 目录、每个日记文件
内容	NUL 字节、超长行、超预算追加全部大声拒绝
读取	按字节预算截断并保留最新尾部；单文件 64 MB 硬上限
写入	O_APPEND 原子追加；并发写不会串行错乱
配置	非法配置在插件加载时即失败——从不装死

配置

字段	默认值	含义
memoryRoot	~/.dsh-brain-memory	记忆库根目录（绝对路径或 ~ 开头）
injectDiaryDays	2	每轮注入最近几天日记（含今天），1–7
injectMaxBytes	8192	注入总字节预算
noteMaxBytes	8192	brain_note 单次追加字节预算
recallMaxResults	20	brain_recall 最多返回条数，1–500
recallSnippetChars	240	每条命中展示字符数，1–4000
recallScanDays	30	brain_recall 扫描窗口（日历天），1–365

挂载示例（examples/demo.cordis.yml）：

- insert:
    - id: dsh-brain
      name: '/absolute/path/to/dsh-brain/src/index.ts'
      config:
        memoryRoot: '~/.dsh-brain-memory'

开发与测试

插件以独立目录形式放在 DeepSeek Harness 源码检出内开发（@deepseek-ai/* 依赖经 harness 工作区解析）。

# 单元测试 + 真实组装测试；每文件 100% 覆盖率门槛
./node_modules/.bin/vitest run --config vitest.config.ts --coverage

# 类型检查（paths 把每个 @deepseek-ai/* 包映射到构建产物 lib/types）
./node_modules/.bin/tsc --noEmit -p tsconfig.json

# lint（harness 的 .oxlintrc.json）
./node_modules/.bin/oxlint -c .oxlintrc.json src tests

当前状态：84 个测试全绿，覆盖率四维（语句/分支/函数/行）100%，类型检查与 lint 零问题。

真实组装测试用 harness 自己的 Loader 启动 headless 组装：确定性 mock LLM 真实调用 brain_note 与 brain_recall，并断言第二轮注入能看到第一轮写入的记忆。

许可证

MIT © Pawin

与 DeepSeek 无隶属或背书关系。