线程会话记忆 zhaoyuntao-wl/dsh-plugin-thread

dsh-thread

Thread 面向 DeepSeek Harness 的深度集成插件——带血缘的编码 Agent 会话记忆，全程使用底座原生通道。

功能

- 无损采集——订阅 session/event，完整事件流水落双 SQLite 库，稳定 origin 幂等去重。
- 三触发结构性送达——首轮锚定（项目身份 + 行为契约 + 状态卡）、每次压缩后重锚定、每回合边界的跨代理状态增量。无每轮状态卡噪音。设计沿确定性日志的记忆研究方向（如 arXiv:2605.21997《The Log is the Agent》）；压缩重锚定针对「Compaction Cliff」失效模式（arXiv:2608.22752）。
- 原生查询工具——query_session_memory 经 ctx.tools.register 注册进模型工具面，支持文件系统式导航 ls / cd / cat / grep；内嵌 MCP server 保留为回退通道。检索为无损流水上的确定性 BM25（中文 jieba 分词）+ 引用回拉——默认零 embedding 依赖；可在集成边界加 hybrid 层（以回归集对照 BM25 基线评估，不打包）。
- 行为契约技能——thread 技能注册进底座技能目录（"需要细节就调工具"）并在锚点注入，模型不必"记得自己有记忆"。
- 产出识别——write/edit 类工具写出的 markdown 文档在写时登记为产出并建血缘边；/thread-reg ast 覆盖显式登记。
- 决策与偏好的显式通道——决策经 /thread-reg dec（用户，--supersedes <id> 演化取代链）或模型的 record_decision 工具（行为契约指示模型：用户定案或自己落定决策时调用）记录；偏好/教训经 /thread-reg fdb 记录（"不要/别"句式自动分类为教训）。决策/偏好的自然语言判定已停用——文本启发式零误报；未显式记录的仍留在事件流水可回拉（目标判定与完成判定保留，带多行粘贴守卫）。
- 收尾沉淀 + 收件箱——收尾词把进行中目标沉淀为待办；/thread-cfm 是唯一待处理收件箱：待办（t#id）与候选（c#id）一个视图——do 完成/转正（候选可带修正文本）、cnl 丢弃、cnl all 双清。状态卡展示前几条候选，杜绝无声堆积。
- 行为边界（1.0，直说）——候选不会自动产出：决策/偏好的自然语言判定已停用，c# 条目只会显示存量遗留，直到发布后的抽取层上线；待办相反有活跃产出（收尾沉淀 + 目标完成自愈）。决策不会自行过期——时间性决策用 --supersedes 显式收口。目标完成判定偏保守（非 ASCII ≥4 连字符 / 纯 ASCII ≥8 连字符重叠；短英文目标宁漏勿误，用 /thread-rev gol 废弃）。完整清单见 Thread README 的「诚实边界」一节。
- 资源解除——/thread-rev <ast|dec|fdb|gol> <ids|all> 解除注册：决策/偏好/产出删除（事件流水保留原文）、目标走状态机废弃并同步自愈关联待办。每条结构化行在状态卡上带可见 #id，记忆全程可人工编辑。
- 会话隔离——/thread-iso / /thread-uniso；/thread-pub <ast|dec|fdb|gol> <ids|all> 把隔离期产生的行转共享。
- 可选主动压缩——THREAD_AUTO_COMPACT=1 时插件在回合边界监控 token 压力并静默触发 compactNow；无论哪种方式压缩，状态都会在压缩后重锚定。

支持的 dsh 版本

- 本地优先、零常驻——一切进程内运行：内嵌 SQLite 存储、无后台服务、无云端依赖。同机 web/headless profile 共享同一存储，离线会话行为一致。
- 已验证：dsh 0.2.0-rc.2（当前；CLI 与其 SDK 子包同版锁步发布）。0.1.x 不再声明支持——dsh 0.2.0 取消了共享的 plugin 消息来源，改为"每个生产者声明自己的 MessageSourceMap kind"，本插件已按新契约声明；0.1.x 用户请留在 dsh-thread@1.2.x。
- 插件钉 SDK peer ^0.2.0-rc.2（dsh-tools / dsh-agent / dsh-session / dsh-user-questions）；每次升级经隔离契约探针（对已发布 SDK 做类型编译 + 隔离 headless profile live 跑一遍）+ CI compat matrix（.github/workflows/ci.yml）验证后才更新此表。
- 除已验证版本外不做承诺；每个新 dsh 版本经评估并扩展 matrix 后才声明支持。

安装

dsh plugin add dsh-thread
dsh plugin add dsh-thread@latest # 升级：同命令重装最新版（core 经 ^1.0.0 依赖自动跟随）

插件经 ^1.0.0 区间拉取内核（@thread-memory/core），新装与重装自动拿到最新 core；运行时启动日志报告解析到的 core 版本（[dsh-thread] thread core vX.Y.Z），内嵌 MCP server 亦在其握手中报告。

dsh 插件需在 profile 的 bundles 中引用才生效。在
~/.dsh/profiles/<your-profile>/package.json：

{
"name": "dsh-profile-my",
"private": true,
"dependencies": {},
"dsh": {
"profile": {
"bundles": [
"@deepseek-ai/dsh-base",
"@deepseek-ai/dsh-headless",
"dsh-thread"
]
}
}
}

除此之外零配置：@thread-memory/core 与 better-sqlite3 随依赖解析，插件激活即开始采集与注入。

注意（原生模块）：若插件启动报 "Could not locate the bindings file"，是 pnpm 10 在安装时跳过了 better-sqlite3 的构建脚本。在 profile 目录执行一条命令修复：

cd ~/.dsh/profiles/<your-profile>
pnpm rebuild better-sqlite3

这是 pnpm 10 的 onlyBuiltDependencies 策略，不是插件缺陷。

配置

| 配置 | 默认 | 含义 |
| budgetLines | 200 | 状态卡行数预算 |
| feedbackRows | 50 | 工具守卫查询的反馈行数 |
| busyRetries / busyRetryDelayMs | 20 / 100 | SQLITE_BUSY 重试策略 |
| compactPressureTokens | 0 | 主动压缩的 token 阈值（0 = 关；需 THREAD_AUTO_COMPACT=1 拉活压缩服务） |

命令

已注册为 dsh 真命令——命令面板可见、斜杠可补全、直接执行（不经模型一轮）。同样的文本在无命令 UI 的环境里按普通消息输入同样生效。

| 命令 | 作用 |
| /thread-reg <ast\|dec\|fdb\|gol> | 列出该资源行（rev/supersede 所需的 id 来源） |
| /thread-reg <ast\|dec\|fdb\|gol> <text> | 注册：ast = 路径（目录递归展开，上限 50）· dec = 决策（直接生效；--supersedes <id> 演化取代链）· fdb = 偏好/教训（"不要/别"句式自动分类）· gol = 目标 |
| /thread-rev <ast\|dec\|fdb\|gol> | 列出该资源行 |
| /thread-rev <ast\|dec\|fdb\|gol> <ids\|all> | 解除：dec/fdb/ast 删除（事件流水保留原文）· gol 废弃（状态机 + 关联待办自愈） |
| /thread-cfm | 待处理收件箱：待办（t#id）+ 候选（c#id） |
| /thread-cfm do <id> [text] | t# 完成待办 · c# 候选转正为生效决策（可带修正文本） |
| /thread-cfm cnl <id> / cnl all | 丢弃一条 / 清空收件箱 |
| /thread-iso / /thread-uniso | 隔离 / 解除会话 |
| /thread-pub | 列出隔离行（全部资源，id 来源） |
| /thread-pub <ast\|dec\|fdb\|gol> <ids\|all> | 隔离行转共享 |

MCP 回退

包内附带 MCP server（bin: dsh-thread），在原生工具注册不可用的底座/场景下提供同一 query_session_memory 契约。见 Thread 记忆协议。

仓库关系

本仓库承载 dsh 深度集成插件。底座无关内核（@thread-memory/core）与 Qoder 适配器在主仓库 Thread。

License

MIT