@yolk_vat-y/dsh-project-memory

dsh plugin --profile web add @yolk_vat-y/dsh-project-memory

dsh-project-memory

如果这个插件帮你省下 1 小时 Debug 时间，请点个 Star。

[English](README.md) | [简体中文](README.zh-CN.md)

     

为 DeepSeek Harness（dsh）agent 提供持久化的 项目开发记忆。专门针对项目开发，原生融合 dsh 任务系统，会话内任务清单与读过的文件自动沉淀为跨会话任务记录，任务↔文件自动关联——开发工作流可切换、可续接，无需重复梳理整个项目，解决上下文失效。底层是一套混合索引：文档块、代码符号、经验笔记与洞察各占一层，召回时分层打分再合并排序。文档（PDF/Markdown/txt）与代码符号写入工作区独立存储，文档自动交叉链接至所提及的代码符号；经验笔记（问题 → 方案）自动去重，避免重复踩坑。数据跨会话压缩与交接保留，召回附带 路径:行号 可回源核实。

插件在磁盘上维护一份精简的项目记忆，每条记录指向具体的文件与行号；agent 需要快速了解项目时先查记忆，无需重读整个项目。

特性

• TaskBridge：跨会话开发任务 — 会话内的任务清单与触碰过的文件持久化为项目任务实体，工作流可以随时切走再续接，不必重新界定项目范围。关联文件按最近活跃排序（读取永远不越过写过的文件），续接时一眼看到该先看哪些。新会话通过 list_tasks → select_task 续接。委派给子代理的工作不会建档。宿主不提供会话事件时，任务工具仍可作为普通记录列表使用。
• 任务面板与编辑 — 卡片可拖拽，展示任务步骤与涉及文件，可折叠为迷你条或彻底隐藏；标题、步骤与状态支持行内编辑，与模型更新走同一条写回路径；四档外观风格只改材质、几何、字型与密度，颜色跟随宿主。面板默认隐藏，仅在显式唤起后出现；会话切换只后台同步，刷新页面不会自行打开；渲染错误有边界兜底，面板崩溃不会拖垮宿主。
• 文档记忆 — PDF、Markdown 与纯文本按块切分并生成摘要，索引期不调用模型。每条保留一段简短摘要供注入、一个有界的检索词集合，以及回源引用。
• 代码符号记忆 — 零依赖扫描器提取函数、类、方法、接口与类型别名及其签名，覆盖 JavaScript/TypeScript、Python、Go、Rust、C/C++/C#、Java 与 shell。项目装了 typescript 时，可选第二层补推导返回类型、泛型与接口，后台执行、不阻塞索引。
• 读到即记忆、变更即刷新 — 默认开启懒索引：文件在模型实际读取的瞬间被记忆，记忆是正常工作的副产品，而不是额外的一次全量扫描。index_repo 或监听根目录可以覆盖其余文件；后台轮询只重记变更过的文件。
• 文档 ↔ 代码交叉链接 — 文档提及的符号，在查询该符号时一并带出。链接按当前符号表解算，不会过期。
• 混合召回 — 对文档、符号、经验笔记与 insight 排序召回，可选 LLM 查询扩展。leanvec 是 optionalDependency：默认装上并按余弦重排经验/洞察两层，没装或 vectorDir: 'off' 则退回纯词法。针对 CJK 增强：短语加分、同义词表，以及文档↔符号链接的词边界处理。俄语（西里尔）同样支持：切词 + 虚词表 + Snowball 词干，俄文查询能命中俄文条目，也参与去重。
• 经验笔记 — 记录问题 → 方案；相似问题覆盖而不重复，数量随项目规模有界，与教训走同一条注入通道：检索与自动注入都能带出。
• 分层 insight 记忆（教训 / 决策 / 流程） — 同一实体贯穿任务、项目、全局三级。近重复合并或强化；提升是更换归属而非复制。被使用会记账，因此衰减与容量按活跃度排序，而不是只按时间。面板提供分级的记忆视图用于审核与编辑；列表按新→旧排列并增量加载——每页 30 条，滚到底前就预取下一页，离屏行不参与渲染，记忆变多也不卡。
• 触发式注入 — insight 可携带 authored trigger：只有 when 能触发，guard 只能收窄，prevents 记下没有它会坏在哪。语料正文永远不能触发注入；统计通道另有独立门槛，默认沉默。证据来源分级：只有宿主事实（结构化工具调用、fs/todo 事件）与真人消息里的不可逆外部动作（提交 / 发布 / 发版 / 推送 / 部署 / 公开）能触发全文注入；散文里的"删除 / 清理 / 渲染 / 基准"只进提示通道，子代理提示词与通知类消息不参与动作判定。
• 用法也是一个 skill — 向宿主 skills 注册 project-memory（目录 bundle，含 scripts/pm-digest.mjs，resourceBase 指向包内目录）。模型按需加载查询 / 写入流程，不占常驻提示；没有 skills 服务的宿主静默跳过。

安装

插件只依赖通过 peerDependencies 声明的稳定公共 API。

cd dsh-project-memory && dsh plugin --profile web add . -w

-w（workspace-root）标志是必需的：profile 目录是 pnpm 工作区根目录，不带该标志 pnpm 会拒绝 add。其他目录下用同样的命令加上绝对路径即可。

插件同时发布在 npm 上（scoped 包）：

dsh plugin --profile web add @yolk_vat-y/dsh-project-memory -w

每个被索引的项目在 <root>/.dsh-project-memory/ 下有独立存储；它默认就把自己排除在 git 之外，.gitignore 无需任何添加。global 级条目单独存放于 ~/.config/dsh-project-memory/global.json；可用 insight.globalFile 改到别处。

用法

以下工具由 agent 自动调用，无需用户手动输入。在对话中直接说自然语言即可——例如「给这个项目建个索引」或「auth 模块是干嘛的」，或者正常开发即可——agent 会自动调用对应工具。默认开启「读到即索引」：模型读哪个文件，就顺便索引哪个文件，记忆在你干活的过程中自然积累。watch_repo 让显式监听的根目录在后台保持新鲜；index_repo 强制对项目做一次全量回填（未变更文件自动跳过）。

在 git 工作树里，语料就是 git ls-files --cached --others --exclude-standard 的清单——已跟踪文件，加上未被忽略的未跟踪文件——因此 .gitignore（含嵌套规则）决定什么会被记忆。隐藏路径（任一段以 . 开头）与内置忽略名单（node_modules、dist …）在两种模式下都跳过；不是 git 工作树的目录退回普通遍历，套用同一套过滤。「读到即索引」只在文件首次入库时套用同一判据；已入库的条目后续只刷新内容、不再问 git——等 .gitignore 开始排除它时，由 index_repo / watch_repo 的扫描清理摘掉。显式 index_doc 不受 .gitignore 与隐藏路径过滤限制，但仍服从 roots.exclude、可读性与体积上限，且只要文件还在，它的条目就能活过后续扫描清理。

工具 · 用途

index_doc file_path · 索引单个文档（PDF/MD/txt）：分块、确定性摘要，带 路径:行号 入库。未变更文件自动跳过。

index_repo root · 索引整个项目：文档生成确定性摘要，代码文件生成零 token 符号表。增量更新，store 跟随文件清单：已删除、被忽略或移走的文件会被清理（显式 index_doc 的条目只要文件还在就保留）；文档与符号交叉链接。根目录不存在或在排除名单上时，会在写入任何内容前拒绝。

watch_repo root · 启用自动刷新：后台轮询检测新增/变更文件，仅重抽这些文件。监听根会记在该项目的 store 里，在该项目下启动 dsh 时恢复监听；不存在或在排除名单上的根目录会被拒绝，已消失的根目录会被丢弃而不是被重新创建。

memory_stats root · 查看记忆库内容：总量、最近索引时间，以及按时间排序的逐文件清单。后台索引失败（watch / 懒索引，按根记账、最多 50 条）也会一并报出，让「文件一直没进语料」可见。

query_memory query · 对文档、符号、经验与 insight 执行排序检索，可选 LLM 查询扩展。type 选择层（all / doc / symbol / experience / insight / task）。返回带相对分数、引用或 insight id、以及文档→符号链接的结果。

list_tasks · 列出本项目任务记录（含归档，带标记）。新会话/续接前先调用。

select_task · 将会话绑定到某任务（此后 todo 清单与读文件同步进该任务）。按 taskId 精确绑定，或按 title 完全匹配（多个同名返回候选；无则新建）。带 title 可改名；自动解归档。

archive_task · 归档任务（隐藏默认视图、不占容量、停止同步、清掉选中它的会话绑定；归档任务也不再参与注入与召回）。select_task 可恢复。

show_task_panel · 在 UI 中打开任务面板。用户要求查看任务列表或你想展示面板时调用。

/tasks（用户输入，不经模型） · 唯一的用户命令：展示任务栈并驱动工作流卡片。其余动作是它的子动词，由卡片按钮调用：switch / archive / unbind / rename / todos … / step / step-move / step-text 为任务动作，insight list [scope] [offset] [limit] / confirm / promote / demote / archive / restore / delete / save / edit 为记忆动作。

remember problem solution · 保存经验笔记。它就是 kind: 'experience' 的 insight——与教训 / 决策 / 流程同库、同去重、同删除入口。相似问题合并或覆盖而非重复。

forget id_or_query · 删除记忆——教训 / 决策 / 流程与经验笔记一视同仁，task / project / global 全层一次搞定，不必先知道它在哪一层。精确 id 删那一条；关键词按查询侧覆盖率匹配（命中词 ÷ 查询词数）。真删、无撤销；关键词命中超过上限（默认 10）时一条都不删，只列出候选。最近删除的 5 条会以完整条目留在该层 store 同目录的 deleted.json（项目层 <root>/.dsh-project-memory/deleted.json，global 层在 global 文件旁），删除回报里给出真实路径——删错时读它、重新保存一次即可找回。

save_lesson · 在 task/project/global 任一作用域保存教训 / 决策 / 流程；带 id 就是就地覆盖既有条目（只改本次显式传的字段，旧值留在 prev，用同一个 id 再写一

…(truncated)