DDDFXYqiming/dsh-ocr1-memory

简体中文 | English

@dsh-external/dsh-ocr1-memory

一个 DSH 光学记忆插件，思路来自 DeepSeek-OCR 论文（Contexts Optical Compression，OCR1）。文本记忆按段落渲染成带 SoM 编号的图像，旧记忆按年龄降低分辨率。检索默认依据文本与 OCR 证据，配置了光学定位器的话，可以再由模型挑出相关段，最后确定性地返回原始 verbatim 文本。

把记忆渲染成图像，用的是论文里对长上下文做光学压缩的思路，这一步到底省了多少，ocr1_mem_metrics 会给出文本 token、视觉 token 和压缩比的实测数字，省不省一目了然。

能力

| 工具 | 作用 |
|---|---|
| ocr1_mem_status | 查看存储、渲染与 OCR 配置状态 |
| ocr1_mem_store | 分段、渲染并保存记忆 |
| ocr1_mem_update | 更新记忆并重置为最新层级 |
| ocr1_mem_retrieve | 检索、OCR 读回、active recall |
| ocr1_mem_list | 列出记忆条目与命中次数 |
| ocr1_mem_metrics | 查看文本/视觉 token 与压缩比 |
| ocr1_mem_calibrate | 校准文本 token 基线 |
| ocr1_mem_forget | 删除记忆及其光学产物 |
| ocr1_mem_render_test | 渲染管线自测 |
| ocr1_mem_embed_test | 视觉 embedding 自测 |
| memory_read / memory_retrieve | 读取 L1/L2/L3，并优先走 OCR1 光学召回 |
| memory_write / memory_update | 带 evidence 的治理写入，自动同步 OCR1 SoM |
| memory_search / memory_promote | 全文检索与跨 namespace 提升 |
| memory_pending / memory_accept | 审阅自动蒸馏候选并确认入库 |
| memory_maintain / memory_stats | 去重、L1 压缩、统计与光学状态 |
| memory_index / memory_archive / memory_rollback | 重建索引、归档与历史恢复 |
| memory_expand / memory_activate | 展开 DSH 溯源事件、激活记忆治理 |

工作方式

1. 文本按空行和长度切成段落，再渲染为 SoM 图像。
2. 记忆图像的分辨率随年龄在 vivid → normal → fuzzy 三级之间衰减。哪次检索命中了低清记忆，active recall 会先把它恢复成高清。
3. 配置光学定位器后，由模型输出 K 位 0/1 标签，插件按阈值和 Top-K 规则选出段落。
4. Fetch 阶段只从持久化原文取回选中的段，返回的就是原文本身，没有替代文本。
5. 视觉 embedding 和命中热度衰减是可选能力。每轮 context 注入默认开启，index 模式注入 L1 与光学元数据，要保留正文快照就选 contextMode: snapshot。
6. 治理工具和 OCR1 store 用的是同一个插件实例。每轮默认只注入 L1 与光学元数据，详细正文按需 Fetch，历史 context 快照靠 contextMode: snapshot 保留。
7. tools/result 里先失败后成功的序列会在 turn/end 生成 pending。到了维护周期或阈值就自动维护并提醒，正式记忆仍由带 evidence 的治理写入确认。

配置

在 profile 的 cordis.patch.yml 里覆盖需要的选项。

- id: dsh-ocr1-memory
config:
storeDir: ''
memoryDir: '~/.dsh/memory'
maxIndexLines: 30
autoNamespace: true
autoPending: true
maintainEveryTurns: 20
maintenanceBatchSize: 8 # 每次维护最多处理的光学条目数
reflectPendingThreshold: 5
reflectSopsThreshold: 40

OCR / llama-server
ocrBaseUrl: ''
ocrApiKey: ''
ocrModel: 'deepseek-ai/DeepSeek-OCR'
requireOcr: false # true = OCR 不可用时失败，不静默走文本降级
autoStartOcrServer: false
ocrServerPath: '' # 也可使用 OCR_SERVER_PATH 或 PATH 中的 llama-server
ocrModelDir: ''
ocrServerPort: 18080

Optical locator
opticalLocatorEnabled: false
opticalLocatorBaseUrl: ''
opticalLocatorModel: 'deepseek-ocr-memory'
opticalLocatorThreshold: 0.4
opticalLocatorTopK: 5
opticalLocatorStrict: true
opticalLocatorAutoStart: false
opticalLocatorServerPath: ''
opticalLocatorModelDir: ''
opticalLocatorServerPort: 18081
opticalLocatorModelFile: 'deepseek-ocr-locator-q8_0.gguf'
opticalLocatorMmprojFile: 'mmproj-locator-q8_0.gguf'

Context / retrieval
dynamicDecayEnabled: false
autoInjectContext: true
contextMode: 'index' # snapshot 可保留正文快照
contextMaxEntries: 5
contextMaxChars: 4000
sharedStore: false
embeddingRetrieval: false
ocrMaxEntriesPerRetrieve: 5

想让插件自己管一个真实的 CPU llama-server，把 autoStartOcrServer 设为 true，同时提供 ocrServerPath 和 ocrModelDir。ocrBaseUrl 里写了显式端口的话，健康检查和启动都以它为准。Embedding 默认不参与主检索，复用同一个服务时把 ocrEmbeddingBaseUrl 留空即可。训练后的 Locator 可以通过 opticalLocatorAutoStart 在独立 endpoint 自动启动，模型目录也可以交给 OPTICAL_LOCATOR_MODEL_DIR 提供。

环境变量回退（仅在对应 Config 字段留空时生效，Config 永远优先；面向源码直跑/脚本场景，profile 部署建议全部走 cordis.yml）：OCR_SERVER_PATH（ocr/embedding/locator 的 serverPath 默认）、OCR_MODEL_DIR / OCR_EMBEDDING_MODEL_DIR（模型目录）、OPTICAL_LOCATOR_MODEL_DIR（locator 模型目录）、PYTHON（渲染器直调时的 python 可执行文件）。

高级选项见 docs/IMPLEMENTATION.md。

安装

dsh plugin --profile web add github:DDDFXYqiming/dsh-ocr1-memory

OCR 后端

插件通过 OpenAI 兼容接口与后端通信（llama.cpp 官方文档列出了 /v1/chat/completions、/v1/embeddings 和多模态输入能力）。

- /v1/chat/completions 负责 OCR 读回和光学定位。
- /v1/embeddings 提供可选的多模态视觉 embedding。

配好 ocrBaseUrl 就能用上 OCR。requireOcr: false 时后端不可用会保留文本检索路径，requireOcr: true 时则直接报告 OCR 错误。autoStartOcrServer 开启后，插件按 endpoint 去重启动 llama-server，只清理自己启动的进程。后端启动、CPU-only 配置、模型格式和平台注意事项见 docs/DEPLOYMENT.md。

文档

| 文档 | 内容 |
|---|---|
| WORKFLOW | 工作流程图 |
| IMPLEMENTATION | 架构与实现说明 |
| DEPLOYMENT | 后端部署与验证 |
| STATUS | 当前实现状态 |
| BENCHMARK | 与 dsh-memory 的隔离对比 |
| EXPLORATION | 研究与实测记录 |
| TEST_SPEC / TEST_REPORT | 测试说明与报告 |
| PAPER_MAPPING | 论文原生机制与插件工程扩展的逐项边界 |

当前 npm test 为 88/88 通过（无后端时真实后端用例会跳过）。

本地工具路径

迁移脚本默认使用当前用户主目录下的 .dsh/memory 与 .dsh/ocr1-memory，可通过 OLD_MEMORY_ROOT 和 OCR1_STORE_DIR 覆盖。精选迁移还支持 OLD_MEMORY_NAMESPACE，默认使用当前系统用户名。渲染脚本位置从迁移脚本自身目录解析，与启动命令时的工作目录无关。

scripts/build.sh 默认只检查构建。只有显式提供 DSH_PROFILE_NODE_MODULES 时，才尝试修复对应 profile 的插件链接。

参考资料

- DeepSeek-OCR · 论文
- OCR-Memory
- AgentOCR