dsh-annals

dsh plugin --profile web add dsh-annals

dsh-annals


给 AI 一份跨会话的记忆：每天一个日志文件、一份可检索的索引、一个独立的 git 仓库。

DSH（DeepSeek Harness）插件 | 版本 0.7.0 | Releases

为什么装它

问题是记忆，不是日志

AI 的每次会话都开在一张白纸上。上一轮敲定的方案、踩过的坑、否掉的路线，下一轮全都不在了 —— 于是你反复解释同一件事，它反复推荐你早就排除掉的办法。

真正的代价不是多花的那几分钟，是你开始不再信任它的判断：你知道它说的每句话都没查过前情，只能自己盯。

你需要的是一份它能自己查到的记录

写日志这件事，人靠自律，AI 靠规矩。而这个插件补的是规矩能被执行的那一环。

日志系统自己搭，通常死在三个地方：

1. 技能被遗漏加载 —— 模型「想到要记」才会去加载技能，而「想到要记」正是失效的那一环。

2. 规矩漂移 —— 只在 AGENTS.md 里写，模型偶尔漏读、读成片段、被别的指令挤掉。

3. 装好了但没初始化 —— 目录、生成器、git init，一样不落全得手动来。

这个插件把三件事装进一个包，并补上第四件：一次初始化。

装完你会得到什么

变化 · 具体表现

不用重复解释 · 干了三个月的事，AI 用 annals_query 一次调用查得到当时为什么这么定

坑只踩一次 · 失败记录留在日志里，下次撞上同一处，它先查到再动手

决定有据可查 · 三个月后你自己也忘了当初为什么排除方案 A —— 日志里有

能交接 · 换个 AI、换个人，读日志就能接上，不用口述前情

它不是「帮你写周报」的工具。它解决的是你和 AI 之间没有共享上下文这件事。

安装

从 Releases 下载最新的 dsh-annals-<版本>.tgz，然后：

dsh plugin --profile web add C:\path\to\dsh-annals-0.7.0.tgz

装完重启 DSH 生效。

开发时可以从源码目录链进去（依赖不会自动装，需自备 @deepseek-ai/schemastery）：

dsh plugin --profile web add link:C:/path/to/dsh-annals

两个装完才知道的坑

1. 本地 tgz 是按绝对路径记的，不是解包副本。dsh plugin add 会在 profile 的 package.json 里写下 "dsh-annals": "file:D:/path/to/xxx.tgz" —— tgz 一删，这个 profile 就装不上了。想长期用，把它放到不会被清理的位置。

2. 从 tgz 装会自动装依赖（@deepseek-ai/schemastery），从 link: 装不会。这是 pnpm 的行为，不是插件选的。

装完会发生什么

第一次进新工作区：它会主动问你

不用你记着要启用。插件注入一条提示，让模型问你一次：

要不要在本工作区启用日志系统？它会建 日志\ 目录、索引生成器和一个独立的 git 仓库，我每次干完活会把事情记进去。

• 你说要 → 它调用 annals_init(enabled=true)，一次建好全部文件
• 你说不要 → 写一条拒绝记录，之后完全静默：不询问、不提醒、零副作用

反悔了随时能开：让模型调用 annals_init(enabled=true)，或者删掉 .dsh\log-system.json 让它重新问。

启用后：初始化建了什么

annals_init(enabled=true) 一次完成，已存在的文件全部跳过，不覆盖你的数据：

1. 日志\.gitattributes —— .md 用 CRLF、.mjs 用 LF

2. 日志\build-index.mjs —— 索引生成器，零依赖

3. 日志\log-parse.mjs —— 生成器用的解析模块

4. 日志\YYYY-MM-DD.md —— 今天的日志骨架

5. 在 日志\ 里 git init

6. .dsh\log-system.json —— 状态文件

只碰 日志\ 和 .dsh\，不在工作区根创建任何文件。

顺带一个坑：插件跑的是裸 git init，全局没设 init.defaultBranch 时新仓叫 master。想要 main 就自己 git branch -m main。

干活的时候：三条提醒

提醒不显示在 GUI 对话流里 —— 它通过 agent.steer() 注入给模型，你在界面上看不到，只会发现 AI 突然回头补了日志。

什么时候 · 提醒什么

这一轮改了文件，但没写今天的日志 · 催它判断该不该记、该记就写

这一轮装了/卸了插件、改了 DSH 配置，但没写日志 · 这类写入在工作区外，「改了文件」那条看不见，单独催一次

日志写了，但 _日志索引.md 没更新 · 催它跑生成器、提交

它只提醒，不代劳。该不该记、记什么、什么时候跑生成器，仍然由模型判断和执行。插件不替模型写文件 —— 好处是「谁写的」永远可追溯。

工作区的三种状态

状态记在 <工作区>\.dsh\log-system.json：

状态 · 怎么进入 · 之后的行为

未决定（无状态文件） · 默认 · 新会话时注入提示，让模型问你一次；不催写日志

已启用（state: "enabled"） · 你同意，或已有 日志\build-index.mjs · 正常提醒

已拒绝（state: "declined"） · 你拒绝 · 完全静默

兼容老工作区：没有状态文件、但已经有 日志\build-index.mjs 的，直接视为已启用，不重复询问。

我该说什么话

大部分时候你什么都不用说 —— 它会自己问、自己提醒。下面这些是说出来有明确效果的：

你说 · 会发生什么

「好」/「启用吧」（在它问的时候） · 初始化整个日志系统

「不用了」 · 写拒绝记录，之后不再问、不再提醒

「记一下」/「先记一下」 · 让模型现在就把当前进展写进日志

「简单记」/「详细记」 · 决定这条写多细（A 档 / C 档）；不说默认 B 档

「这个不用记」/「别碰日志」 · 本会话不再催写日志

「以前那个 X 是怎么弄的？」 · 触发 annals_query，按内容捞历史

「这个文件以前哪些条目碰过？」 · 触发 annals_links，按关系反查

判断记不记由模型来做，它加载 annals 技能后按一份正反清单判断。拿不准会问你一句，日常小事不问也不写。

能力一览

能力 · 是什么 · 什么时候用得上

annals 技能 · 写日志的完整规矩（该不该写、写多细、怎么排版、写完做什么） · 模型要写日志时自动加载

常驻规矩 · 一段精简版日志规矩，每轮都在系统提示里 · 防止「模型没加载技能就忘了要记」

小鲸鱼人设 · 标准版/精简版/自定义三种语气提示，默认关闭，设置页可开 · 想让每轮对话多一点趣味时

轮次提醒 · 轮次收尾时判断这一轮改了文件却没写日志 · 提醒本身不占你注意力，只在它漏记时出现

环境变更提醒 · 判断这一轮装/卸了插件、改了 DSH 配置却没写日志 · 这类写入在工作区外，普通「改了文件」提醒覆盖不到

索引新鲜度提醒 · 判断日志写了但索引没重新生成 · 防「写了日志就以为完事」—— 索引不跑，检索永远停在旧快照

annals_init · 一次初始化整个日志系统 · 首次启用；或反悔后重新启用

annals_query · 按内容找：忘了一件事在哪，用关键词捞 · 动手做一件「感觉做过」的事之前

annals_links · 按关系找：知道是哪一条，看它引了谁、谁引了它 · 改文件前想知道以前哪些条目碰过它

annals_ignore · 把「别的插件在自动写」的目录加进工作区忽略清单 · 某个目录总被误报成「你改过工作区」时

annals_query 与 annals_links 不重叠：前者用在「我记得做过但忘了在哪」，后者用在「我知道是哪条，想看它牵到谁」。

忽略某个目录

有些目录是别的插件在自动写（比如 .dsh-meow 记忆库），不是这一轮的活。把目录加入工作区的忽略清单后，它下面的所有改动不再算「工作区改过」，轮尾不会再为它催日志。

直接跟 AI 说「忽略 .dsh-meow」即可，它会调用 annals_ignore 写进 .dsh\annals.json。也可以手动调：

• annals_ignore({ action: "scan" }) —— 列一级目录，看哪个像插件自动写的
• annals_ignore({ action: "add", dirs: [".dsh-meow"] }) —— 加入清单（目录里有源码/文档会先警告，但允许保存）
• annals_ignore({ action: "list" }) / { action: "remove", dirs: [...] } / { action: "dismiss", dirs: [...] }

清单每个工作区一份，存在 .dsh\annals.json，不随插件升级丢失。dismiss 用于「用户说了不要」：该目录 7 天内不再提示。忽略只影响「改没改」的判定，不阻止任何插件继续写那个目录。

都没有自动触发。插件不会在每轮替你检索再塞进上下文 —— 那会把 prompt 缓存命中率打到 0%，而且意图分类判错等于静默不检索。只有两处被动入口：常驻系统提示里的一句规矩、annals 技能的触发词。是否调用由模型自己决定。

配置

插件带一个 GUI 设置页：设置面板 → annals设置，页内分两个 tab：日志设置、人设。

两个 tab 都读写 Host 的 annals 设置命名空间；保存后写进 profile 的 cordis.patch.yml config 段，热重载条目，下一次请求生效，不需要重启。

插件页卡片（「插件」→ dsh-annals）不渲染配置表单 —— 那是 DSH 的既有行为：插件页只显示包信息与运行状态，配置表单由功能包自己注册设置页。

十三个字段，五个在 GUI 里

字段 · 默认 · 含义 · GUI

enabled · true · 总开关 · ✅

probe · false · 检索记录：把每次 AI 调用插件检索工具记到 日志\annals-probe.jsonl，默认关闭 · ✅

persona · false · 小鲸鱼人设总开关；关闭时任何预设都不注入（默认关闭） · ✅

personaPreset · standard · 人设预设：standard / simple / custom:<id>；persona: true 时生效 · ✅

personaCustoms · [] · 自定义人设数组，每项 { id, name, text }；text 最多 2000 字符，列表可放多张 · ✅

skill · true · 注册 annals 技能 · ❌ 只能改 YAML

section · true · 注入常驻日志规矩 · ❌ 只能改 YAML

reminder · true · 轮次收尾提醒（含索引新鲜度提醒） · ❌ 只能改 YAML

envReminder · true · 环境变更提醒（装/卸插件、改 DSH 配置但没写日志） · ❌ 只能改 YAML

initTool · true · 注册 annals_init 工具 · ❌ 只能改 YAML

skipSubagents · true · 子代理会话不提醒 · ❌ 只能改 YAML

queryTool · true · 注册 annals_query 工具 · ❌ 只能改 YAML

linksTool · true · 注册 annals_links 工具 · ❌ 只能改 YAML

人设页

人设页把标准版（438 字符）、精简版（165 字符）和任意多张自定义人设做成卡片。卡片显示名称、1–2 行描述和约 token；每张卡都有「复制」按钮，点击会基于该卡原文新建一张自定义卡，方便改出自己的版本；标准版/精简

…(truncated)