dsh-cognition-engine
给 DeepSeek Harness 装一层可追溯的记忆、会自我改组的图式和三段式反思。
一个纯 TypeScript、零运行时依赖的 DSH 插件。所有状态都存在内存 + 本地 JSON，不接数据库、不发外部请求（除非你主动打开真模型）。
本项目是 DeepSeek V4.1-Flash（1017）许愿式编程 的产物：需求由人提出，代码、测试、评测与文档由模型在会话中逐轮生成、验证并修正。
认知引擎 记忆 3 · 图式 2 · 待办 1 · 跨会话摘要 ▸
点一下这条状态条，展开五个页签：状态 / 待办 / 记忆 / 图式 / 设置。
为什么做
普通 Agent 的记忆是一个检索管道：切块 → 向量化 → 取最近的。它解决不了四件事：
- 现在为真 vs 曾经为真——你说"用 Python"，后来改"用 TypeScript"，两句话都在，它不知道该信哪句。
- 新信息该挂在哪——第 20 条偏好和第 3 条是同一个话题，还是该新开一簇？
- 它对这事什么态度——被连续否定之后，它还是用同样的语气回答。
- 决定是怎么来的——只给结论，不给推理过程。
认知引擎用五个模块分别对应这四条，外加一个长程任务台账兜底"跨会话不忘事"。
特性
- 双时态记忆：
validFrom/validTo（世界时间）+ recordedAt/supersededAt（事务时间）。取代不删除，旧版本仍可历史召回。
- 图式网络：新观察能同化就并入，不能就新建图式并连边；否定陈述会触发冲突而不是硬塞。
- 图式扩展召回：召回时可按图式把同簇的其他记忆一并带出（
expand）。
- 三段式反思：THESIS → ANTITHESIS（CONTRADICTION/EVIDENCE）→ SYNTHESIS，严格串行；可对已有草稿直接审（
draft），可把结论写回记忆（save）。
- 长程任务台账：
tasks.json 原子落盘，重启恢复，超时任务自动催办。
- 持久化：记忆写入
cognition-state.json，重启自动恢复；页面一键清空。
- 反思引擎：可在「本地模拟」与「真实模型」之间切换；真实模型走宿主
llm 服务。
- 记忆读取锁：给读取记忆正文的接口加访问口令，防止本机其他进程偷看。
安装
需要 DeepSeek Harness，Node.js ≥ 22。
# 从本地目录安装（推荐先用这个）
dsh plugin --profile desktop add /path/to/cognition-engine
或让 Agent 直接调 plugin_manager 的 install_bundle 指向该目录。
安装后重启一次 DSH。页面输入框下方会出现状态条。
npm 包名当前是 @local/cognition-engine，发布前请改成你自己的作用域或 dsh-cognition-engine，并同步修改 cordis.patch.yml 里的 name。
七个工具
| 工具 | 作用 |
|---|
cognition_context | 新会话先调它：读取跨会话核心记忆（≤400 字摘要） |
cognition_remember | 写入记忆；supersedes 取代旧事实，source 标记来源，scope 选 global / workspace / session |
cognition_recall | 按 strict / historical / belief 召回；render 走 Inline&Spill，expand 按图式扩展，scope 过滤作用域 |
cognition_forget | 删除记忆：按 id、按来源（如 test、reflection）、按主题 |
cognition_reflect | 三段式反思；draft 审草稿，save 把结论存成记忆 |
cognition_state | 记忆/图式/任务统计与跨会话摘要 |
manage_long_task | 长程任务：create / update / list / due / delete |
配置
cordis.patch.yml：
- insert:
- id: cognition-engine
name: '@local/cognition-engine'
config:
decayHalfLifeHours: 168 # 记忆衰减半衰期
assimilateThreshold: 0.55 # 同化阈值
overlapThreshold: 0.42 # 重叠聚类阈值
communityThreshold: 0.3 # 社区连边阈值
maxClusterSize: 8 # 单簇上限
tasksFile: D:/path/tasks.json
stateFile: D:/path/cognition-state.json
heartbeatHours: 6 # 多久没更新算超时
patrolIntervalHours: 3 # 后台巡视间隔
recordOnly: true # 主动发言只记录不发送
# lockToken: 你的固定口令
# llmProvider: deepseek
# llmModel: deepseek-chat
页面
状态条固定在输入框下方，五个页签：
- 状态：记忆 / 图式 / 待办计数与跨会话摘要
- 待办：任务描述、状态、线索、超时标记
- 记忆：正文、来源徽章、当前/已取代、标签
- 图式：成员数、邻接数、极性
- 设置：清空记忆、反思引擎（本地模拟 / 真实模型）、记忆读取锁与访问口令
页面上所有数据走 HTTP，不进入模型上下文，不消耗 token。
数据与隐私
| 项 | 说明 |
|---|
| 落盘 | cognition-state.json（记忆）、tasks.json（任务） |
| HTTP | GET /cognition-engine/state（仅计数）、GET /cognition-engine/detail（含正文）、POST /cognition-engine/{clear,model,lock} |
| 记忆读取锁 | 开启后 detail 与三个 POST 要求 x-cognition-token；state 始终公开（只有计数） |
| 外部请求 | 默认零外部请求；只有打开真模型时才会调用宿主配置的模型服务 |
⚠️ 不设 lockToken 且未上锁时，本机任意进程都能读取记忆正文。多人或多程序共用一台机器时请先上锁。
卸载
插件运行时注册的东西（7 个工具、4 条 HTTP 路由、后台巡视定时器、页面状态条）会在卸载时自动撤销。
但有四样东西不会自动消失，需要显式清理：
| 残留 | 说明 |
|---|
cognition-state.json | 记忆的落盘 |
tasks.json | 长程任务台账 |
AGENTS.md 第九节 | 会继续指示模型调用已不存在的 cognition_context |
浏览器 localStorage['cognition-token'] | 上锁口令 |
清理脚本：
powershell -NoProfile -ExecutionPolicy Bypass -File D:\dshgz\cognition-engine\scripts\uninstall-cleanup.ps1 -Workspace D:\dshgz
然后移除插件本体：
plugin_manager remove_bundle target=@local/cognition-engine
最后在页面控制台执行 localStorage.removeItem("cognition-token")，刷新页面。
为什么不在 dispose 里自动删数据：dispose 在 HMR 热重载和插件重启时也会触发，自动删会把记忆每改一次代码就清空一次。运行时资源自动撤、磁盘数据交给显式脚本，是刻意的分工。
架构
| 模块 | 职责 | 设计来源 |
|---|
memory.ts | 双时态存储、三种召回、冲突检测、Inline&Spill | LongMemory |
graph.ts | 图式网络、同化/顺应、重叠聚类、图式扩展 | CAM（NeurIPS 2025） |
reflection.ts | 三段式反思、Worker 队列 | Hegelion |
proactive.ts | 默认不做的发言闸门 | dsh-superagent-prototype |
task_manager.ts | 长程任务台账、原子落盘 | 自研 |
persist.ts | 记忆快照存储 | 自研 |
views.ts | 页面只读视图 | 自研 |
index.ts | 插件装配：工具、路由、巡视 | — |
client.js | 输入框下方的状态条与面板 | — |
反思闭环参考了 Generative Agents 的「记忆 → 反思 → 回写记忆」；图式扩展参考了 GraphRAG 的社区扩展思路。
开发
npm install
npm run build # tsc → lib/
npm test # 33 项单元测试
npm run eval # 20 条评测 + token 预算门禁
npm run eval -- --update 在确认变好之后重写基线。
质量门禁
- 单元测试 33 / 33
- 评测用例 20 / 20，判分器自检、打包自检 5 项
- 工具 schema 固定开销 1086 tokens（预算 1400）
- 单次调用输出上限 344 tokens（预算 600）
兼容性
设计原则：只做特性探测，不做版本判断；任何宿主能力缺失都降级而不是报错。
| 场景 | 行为 |
|---|
| 与其他插件工具重名 | 跳过该工具并记警告，其余 6 个照常注册 |
| HTTP 路由被占用 | 跳过该路由，插件继续加载 |
宿主没有 webServer / events / effect | 对应功能静默关闭，不抛错 |
agent/pre-step 的 next 缺失 | 返回 undefined，不阻断模型步骤 |
| 宿主更新导致工具 schema 不被接受 | 该工具注册失败，但不影响其他工具 |
刻意不做的事（避免和其他插件打架）：不修改全局 patch、不覆写系统提示、不接管 tools/post-execute、不声明 peerDependencies（避免 pnpm 的 ERESOLVE）。
已验证环境：DSH 0.1.x（desktop profile）+ Node 22。每次 npm run eval 都会回归「兼容性」三项。
已知限制
- 记忆是进程内 + 单文件，没有并发多实例保护；两个 DSH 同时写会互相覆盖。
- 反思默认用离线确定性推理器，不是真思考；打开真模型后才由模型生成。
- 上锁是共享口令，不是账号体系；口令泄露即失效。
- 真模型输出可能很长（一次反思可达数千 token），请自行控制使用频率。
参考与致谢
本项目的机制设计来自以下开源工作。只借鉴思想，未复制任何代码——所有实现均为重新编写。
记忆与图式
反思
插件机制
评测方法
特别说明
- 本项目由 DeepSeek V4.1-Flash（1017） 在「许愿式编程」模式下完成：人提需求，模型负责设计、实现、自测、修复与文档。
- 所有参考项目仅用于理解机制；代码、测试与文档均为原创实现，未包含上述项目的源码片段。
- 若你是上述项目的作者并认为某处借鉴过度，请开 issue，我会调整或移除。
License
MIT
English
dsh-cognition-engine is a zero-dependency DeepSeek Harness plugin that adds bitemporal memory, a constructivist schema graph, a mood state machine, dialectical reflection, and a long-horizon task ledger. Six tools, one status dock, everything stored locally.
