任务记忆卡 xjhao-heim/dsh-task-memory

dsh-task-memory

DeepSeek Harness 插件：工作区级任务记忆。

解决的问题：相似的活会反复出现，而每次会话都从零重新分析一遍。这个插件把「做过的任务」存成一人一张的记忆卡，并且让卡片以两段式被检索——先看索引，命中后才读那一张的正文，所以记忆再长也不需要每次全读。

两段式检索

| 阶段 | 机制 | 成本 |
| 索引 | 一张有界的卡片摘要清单，注入到会话（一行一卡：名字 + 描述 + 触发词） | 常驻，且按使用频率排序、有硬上限 |
| 正文 | 命中后用 task_memory_load 取那一张卡的正文 | 一次调用，只读一张 |

索引不进对话历史，也不按轮次重复；其余卡片用 task_memory_index / task_memory_search 发现。记忆再长也不需要每次全读。

上架过的卡片（见下）会额外出现在 Harness 的技能目录里，可以用内置 skill 工具加载——但那是可选的，不是索引机制本身。

数据布局

所有工作区共用一个 SQLite 数据库：$DSH_HOME/task-memory/memory.db（默认 ~/.dsh/task-memory/memory.db）。表内用 workspace 列隔离各工作区。

meta (key, value) ← schema 版本等
cards (workspace, name, description, when_to_use, triggers, tags,
status, published, revision, created, updated, body, hits, last_used)
assets (workspace, card, path, bytes) ← 外键级联，随卡片一起删除

用 node:sqlite（Node 内置）实现，零第三方依赖、无需编译。本机 dsh-memento 已在用同一机制，所以 Electron 宿主也支持。

数据库相对文件存储买到的三个性质：

| 性质 | 说明 |
| 原子性 | 卡片与附件在同一事务里写入，崩溃不会留下「有附件没卡片」 |
| 唯一身份 | 卡名是主键列，「一件事只留一张卡」是 schema 保证，不是靠代码反复检查 |
| 计数不漂移 | hits/last_used 是卡片行上的列，不可能与卡片失联 |

索引仍然永远从行数据现算，不存索引表；## 变更记录 段落承担版本历史，所以也不需要 journal。

工具

| 工具 | 作用 |
| task_memory_index | 完整索引，可按 query / status / tag / tier 过滤。索引被上限截断时兜底 |
| task_memory_load | 按名字取一张卡的正文、元数据与附件清单 |
| task_memory_asset | 读取某张卡的某个附件（代码片段、补丁等，存于数据库） |
| task_memory_save | 落卡。默认 auto 模式会拒绝为已记录的任务再建一张卡，并返回候选卡 |
| task_memory_search | 跨卡片正文全文检索（带片段），触发词都没命中时兜底 |

新鲜度分档

记忆库有两种「旧」：内容过时（status: verified/draft/stale，人工判断）和久未使用（档位，自动按时间算）。两者正交——一张卡可以既「已确认」又「遗忘」（内容正确但一年没用了）。合成一个字段就再也说不清用户指的是哪种。

五档（天数可配置）

| 档位 | 默认距离 | 在注入索引里的呈现 |
| 近期 | ≤ 7 天 | 名字 + 描述 + 触发词 + 年龄 + 使用次数 |
| 之前 | 8–30 天 | 同上 |
| 很久之前 | 31–90 天 | 名字 + 描述（去掉触发词）+ 年龄 |
| 远古 | 91–365 天 | 只有名字，合并成一行 |
| 遗忘 | > 365 天 | 不列出，只报一行数量 |

这就是「检索频率不同」：越旧的卡越不容易出现在模型眼前，但一次也没丢。

时间基准：max(updated, lastUsed)

- 刚改写过的卡 = 知识新鲜 → 算活跃
- 刚被检索过的卡 = 仍被需要 → 算活跃

取较新者。只用 updated 会让「写完再没碰过」的卡一直假装新鲜；只用 lastUsed 会把刚创建、还没被检索过的卡判成遗忘。两者都是 cards 表上的列，所以不可能与卡片失联。

遗忘 ≠ 删除

遗忘档只做三件事：不注入、面板可见并标记、工具仍能检索到。行数据一个字段都不动——一个会自己删记忆的记忆插件比一个拥挤的更糟。

想清理时用面板上的「清理遗忘」按钮：它先列出所有遗忘档卡片让你确认，再删除指定名字的那些。没有自动清理。

档位边界写进配置（tierDays），随时可改；改完不需要迁移任何数据，因为档位永远是算出来的，不存进文件。

筛选

面板顶部有两个筛选器：

| 控件 | 作用 |
| 档位下拉 | 默认（按配置，通常只看近期）/ 全部档位 / 仅近期 / 仅之前 / 仅很久之前 / 仅远古 / 仅遗忘 |
| 起止日期 | 按最后活动日期过滤；范围默认取真实数据的最早~最晚，可改 |
| 日期条 | 每个「有卡片的日期」一个可点标签（显示月-日与张数），点一下就把范围收到那一天 |

日期条是必需的补充：原生 的日历弹层同样由 Chromium 绘制、CSS 碰不到，而用日期选择器排错时最关键的信息是「哪天有记忆」。所以那个信息放在选择器旁边，而不是指望日历里能标出来。

档位筛选在宿主侧执行（不是浏览器里过滤）：列表本身有上限，本地过滤会把本该被查询捞出来的卡藏掉。

工具 task_memory_index 也接受 tier 参数，含义与面板一致。

设置页

「设置 → 任务记忆」区块，改完保存立即生效（不需要重启）：

| 设置 | 说明 |
| 面板默认显示哪些档位 | 打开面板时默认勾选的档位；默认只看近期 |
| 档位边界（天） | 四个边界，改完立刻影响分档 |
| 注入索引的卡片上限 | 索引里最多列多少张 |
| 单张卡正文上限 | 超出截断并给出数据库位置 |
| 回合结束自动落卡 | 关掉后只能由你明确要求才记录 |

设置存在哪里：$DSH_HOME/task-memory/settings.json（默认 ~/.dsh/task-memory/settings.json）。

优先顺序是 设置文件 > cordis.patch.yml 里的 config > 内置默认。设置文件赢，因为它代表你最后一次在界面上做的选择；loader config 仍然是新安装的种子值。

打开设置页会补齐缺失的参数。 页面上每个参数都显示它的有效值，而一个「没有记录」的参数是无法在界面里改的——所以读取设置时会把本地文件缺的字段按当前生效的值写进去（不是写死默认值：通过 loader config 设过 maxCatalogCards: 99 的部署，文件里也该是 99，否则文件与运行中的插件说的不是一回事）。已经写过的值永远不会被覆盖。

为什么不用宿主自己的设置服务：dsh-settings 只渲染插件用 schemastery 声明了 .volatile() 字段的表单，而本插件零依赖、没有 schema。手写 YAML 去改 profile 的 patch 文件则有损坏整个 profile 启动配置的风险——为了一个设置面板不值得。所以设置写进自己的 JSON 文件，原子写（临时文件 + rename），坏文件退化成「没有覆盖」而不是启动失败。

兼容旧版记忆

早期版本把记忆存成 <工作区>/.dsh/task-memory/notes/<卡名>/SKILL.md 加一个 stats.json。那些文件里的知识仍然有效，所以面板上有一个「兼容旧版记忆」按钮，按当前选择的工作区把它搬进数据库。

点击后是三步，每步都有确认：

1. 预演（不写任何东西）—— 告诉你将导入多少张、其中多少是新建、多少与库里已有卡片同名、多少附件、多少张无法解析。
2. 导入 —— 已存在的同名卡片不会被覆盖（导入永远不破坏库里更新的版本），然后报告实际写入了什么。
3. 删除旧文件 —— 这一步单独确认，且在导入成功之后才提出。

导入用 importCard 原样写回：原始日期、revision、hits、last_used 都保留，而不是当作新卡重新推导。删除只动 notes/ 与 stats.json 两项，同目录下别的插件数据不会被碰。

自动落卡

默认不需要你开口。 每个回合结束时，如果这一轮确实做了实事（工具调用 ≥ 3 次）而且还没有存过卡，插件会自动追问模型一次：

任务记忆自动检查：本轮工作已结束。回顾本轮，判断是否产生了值得留存的东西……

模型据此判断本轮是否有非显然结论/踩坑/可复用流程：有就调 task_memory_save，没有就回一句「本轮无需记录」。

为什么要这么做：一段提示词只能「请求」模型记录，而刚干完活的模型不会可靠地执行又一条指令。之前的实测就是——你不主动说「记住这个」，卡片永远是零。所以这里用的是真实触发点而不是请求：宿主在关闭回合前会 await agent/turn-stopping，监听器调 agent.steer(...) 就能让机器多跑一步。

为什么是「追问」而不是「直接写」：只有模型分得清「可复用的根因」和「一次性的查询结果」。缺的不是判断力，而是提醒自己去判断这件事。

三个防呆：

| 条件 | 行为 |
| 本轮工具调用 < 3 次 | 不提醒（查询、闲聊、小改动） |
| 本轮已经存过卡 | 不提醒（记忆已是最新） |
| 本轮本身就是提醒引发的复查 | 不提醒（防死循环的关键） |

模型说「不值得存」时不会硬写。关闭方式：把 autoCapture 设为 false。

上架与不上架

卡片默认只留在本工作区的任务记忆里，不进技能目录。 需要时用 publish: true 单独上架。

为什么默认不上架：本插件的卡片注册成 runtime 技能后，会出现在 Harness 的技能目录里，而技能中心（Skill Center）页面列的就是同一份目录。技能中心是给人挑通用技能的地方，不该被某个工作区的排查记录塞满。而且技能中心虽然能编辑技能，却无法操作 runtime 条目（它列出的 runtime 技能没有文件路径），所以这些卡片在那里只是一排点了没反应的噪声。

| 状态 | 出现在任务记忆索引 | 出现在技能目录/技能中心 | 加载方式 |
| 未上架（默认） | ✅ | ❌ | task_memory_load / task_memory_search |
| 已上架（publish: true） | ✅ | ✅ | 上面两种，外加内置 skill 工具 |

上架与否不影响可检索性：未上架的卡一样会被注入索引、一样能被工具检索和加载，只是不会污染面向人的技能列表。上架状态是粘性的——一次 update 不会把它悄悄取消，只有显式传 publish: false 才撤下。

判断标准：跨任务复用的通用方法论才值得上架；某个项目的排查记录、一次性结论留在工作区即可。

上架后立即生效，不用等

技能的收集结果在注册表里是按 revision 缓存的，所以「改了卡片」本身不会让目录刷新。本插件在每次写入后主动调 control.invalidate() —— 它把 revision 加一、清掉缓存并通知观察者，于是下一次收集必然重新读取。

关键在于宿主侧的消费方式：@deepseek-ai/dsh-tool-skill 在每一步（agent/pre-step）都会 snapshot() 一次并比对摘要，摘要变了才推送新目录。所以 invalidate 之后的下一个步骤就会看到新卡片。

这对模型侧的技能列表是立即的。技能中心页面是浏览器里的列表，点一下刷新即可看到；它读的是同一份已失效的缓存，不会再拿到旧数据。

只记一份

task_memory_save 的三种模式：

- auto（默认）：先用本地相似度（字符 trigram + 触发词重合 + 标签重合）比对已有卡片。判定为同一件事时不创建，直接返回那张卡的 name 与匹配理由，让模型改用 update。
- update：合并进指定卡。合并按 ## 段落进行——模型这次写到的段落被替换，没提到的段落原样保留，因此后一次保存不会悄悄抹掉先前的结论。revision 递增，triggers / tags 取并集。
- force-create：确实是一个不同任务时才用。

索引有硬上限（默认 50 张，按加载次数→更新时间排序）。被截断的卡仍然可以通过 task_memory_index / task_memory_search 找到——这是「记忆可以很长，但每次不必全读」的落地方式。

记忆面板（P3）

Harness 侧边栏里的「任务记忆」入口，中间列打开面板。左侧是卡片列表、右侧是详情/编辑区，两列各自滚动——详情不会因为你记忆变多而被推得越来越远。

| 操作 | 说明 |
| 浏览 | 顶部选工作区（带卡片数），左栏列表：名字、状态、描述、更新时间、revision、加载次数、触发词 |
| 查看 | 点左栏卡片，右栏显示正文与元数据 |
| 新建 | 点右上角「新建卡片」，在右栏填写；勾选「作为技能上架」（默认不勾） |
| 编辑 | 右栏直接改字段与正文后保存；上架开关也在这里 |
| 删除 | 二次确认，删掉卡片及其全部附件（外键级联） |
| 检索 | 按正文全文过滤左栏列表 |

状态显示中文：「已确认 / 草稿 / 可能过时」。存储里仍然是 verified / draft / stale 标识符 —— 面板只翻译显示，因为那三个词是工具 schema 和数据库列使用的值，就地改写会破坏与模型的契约。

人工编辑与模型写入的语义不同：模型 update 是按 ## 段落合并，而面板保存是逐字替换——你在编辑器里写的就是最终内容，删掉的段落和触发词不会自己回来。

实现要点：Host 侧用 ctx.webServer.register 挂 /api/task-memory/ 六条路由，客户端用 fetch 调用，两个 slot（sidebar.panellist + main）提供入口和页面。样式只用主题 token，明暗主题都跟随宿主。

界面里的下拉框是自绘的，不是原生 ：后者的展开弹层由 Chromium/OS 绘制、CSS 碰不到，在暗色主题下会是白底黑字，与其余控件格格不入。自绘版直接采用宿主菜单的配方（--dsw-menu-surface-fill + --dsw-menu-backdrop-filter + --dsw-elevation-prominent），并保留原生控件的全部键盘与无障碍行为（方向键、Home/End、Enter/Space、Escape、点外部关闭、焦点回到触发器）。

安装

本插件不使用 npm 安装、没有 node_modules、不依赖任何 @deepseek-ai/ 包——link: 安装的插件是从真实路径加载的，Node 的解析走不到 profile 的 node_modules，所以裸包名会失败。lib/schema.js 因此自己实现了注册契约。

1. 加依赖（link: 指向本目录）：
"dependencies": { "dsh-task-memory": "link:D:/AI/dsh-task-memory" }

2. 加进 bundles：
"bundles": [ ..., "dsh-task-memory" ]

3. 建 junction，让 Node 能解析到它： New-Item -ItemType Junction -Path "$env:USERPROFILE\.dsh\profiles\<profile>\node_modules\dsh-task-memory" -Target "D:\AI\dsh-task-memory"

配置

- id: dsh-task-memory
name: dsh-task-memory
config:
maxCatalogCards: 50 # 注入索引的卡片上限 maxBodyChars: 24000 # 单张卡正文的读取上限，超出截断并给出数据库位置 includeSystemPrompt: true autoCapture: true # 回合结束自动追问是否落卡；设 false 关闭
defaultTiers: [recent] # 面板默认显示哪些档位
tierDays: # 新鲜度档位的天数边界，必须递增 past: 7 # ≤7 天算「近期」 old: 30 # ≤30 天算「之前」 ancient: 90 # ≤90 天算「很久之前」 forgotten: 365 # ≤365 天算「远古」，超过则「遗忘」

这些都可以在「设置 → 任务记忆」里改，改完立即生效并存进设置文件（优先于这里的 loader config）。

测试

node test/all.test.js

node --test 会为每个文件 spawn 子进程（在受限沙箱下会被拒），test/all.test.js 把十组用例导入同一进程执行，断言完全相同。

test/setup.js 在任何测试运行前把 DSH_HOME 指向临时目录，所以跑测试绝不会创建或改动你真实的 ~/.dsh/task-memory/。每个用例还各自开 :memory: 库，互不干扰。每个测试文件都单独引入它，这样一个套件被单独运行时同样安全。

另有一个真实 Cordis 运行时的集成测试（test/integration.cordis.mjs：装配、通过真实注册表读写、上架语义、写入触发目录重扫、面板路由、回合结束追问及其防循环、卸载清理）。它必须在 profile 目录下运行——插件是 junction 安装的，从 D:\AI\dsh-task-memory 里跑会解析不到 @deepseek-ai/*。运行方式见该文件头部注释。

限制

- 卡片按会话工作目录隔离（数据库里是 workspace 列），不跨工作区共享。面板顶部的选择器可以在工作区间切换查看。
- 去重是启发式：它宁可拒绝新建也不轻易产生第二张卡，但最终判断在模型；工具会给出匹配理由，模型可以据此改用 force-create。
- 删除卡片不提供模型工具——模型能自行删除的记忆就是会消失的记忆。删除只在面板里由人操作。
- 自动落卡是追问而非直接写入：模型判断不值得存就不会存。这保住了判断质量，代价是它偶尔会漏存——想确保记下来时，直接说「记住这个」。
- 改用数据库后，卡片不再能直接用 read/edit 工具改；附件也用 task_memory_asset 读，而不是给一个文件路径。
- 改动插件的 JS 代码后需要重启 Harness 才会加载（patchReload: live 只覆盖新增插件与配置改动）。