dsh-learn

dsh-learn — DSH 的持久学习回路

Persistent learning for DeepSeek Harness. A Cordis plugin that turns a session's corrections, failures and fixes into ordinary DSH skills — so the next session starts already knowing them. Zero extra model calls. Keeps the system prompt stable; recall travels through the host's runtime-context channel.

从会话里学东西，把学到的东西写成普通的 DSH 技能，并且在写之前先过一遍内容卫生与门槛检查。

---

它是什么

dsh-learn 挂在会话事件流上，把每个回合里出现的纠正、失败与修法蒸成类级技能，写进技能库，让下一个会话能用 learn_skills 找到、能被模型当技能加载。它自己不做判断：确定性路径（正则 + 门槛）只产出候选，写盘必须由模型显式决定。技能落在一个专属技能根里，状态、账本、候选与归档落在 <DSH_HOME>/learn/data/。整个过程零额外模型调用；纪律是字节稳定的系统提示段，队列与规则摘录走宿主专门的 runtime context，不改写持久会话历史，也不让系统提示在会话中途变化。

它不发明新的文件格式，也不维护第二套目录：学到的技能就是普通的 DSH 技能——宿主的技能提供者扫得到，/名字 能加载，别的工具也读得懂。插件只是往那个目录里写，并记住自己写过什么。

---

设计取舍

自动学习这件事，难的不是「把东西存下来」，是**「存什么」和「谁说了算」**。这个插件在每一处都选了更保守的那一边：

一个回合走完的路径：

1. session/event 进来 → curator.touch() 记一次活动。
2. capture 把用户/助手/工具事件脱敏、压缩、按信号分类，塞进当前会话的内存窗口。来源纪律在这一层强制：用户文本只允许产出 REMEMBER_REQUEST / USER_CORRECTION / USER_PREFERENCE / DURABLE_FACT，助手文本只允许 TECHNIQUE / SKILL_WRONG / RECOVERED_FAILURE，工具结果只允许 RECOVERED_FAILURE / TECHNIQUE / TOOL_FAILURE_OPEN（text.js 的 SOURCE_KINDS）。
3. agent/turn-stopping → 防抖 4 秒后跑一次 runReview(session, {dryRun:false})。它只写候选到 pending.json，并且只在窗口观测数 ≥ review.triggerObservations（默认 3）时才跑。回合边界只负责调度，绝不 await——自我改进不能拖慢用户的回合。
4. 模型看 learn action=pending，自己决定要不要写：learn_skill_manage create（新技能）或 learn action=note（往四把伞里加一条规则）。两条路都过同一套门槛与同一套内容卫生。
5. 命中 tokenSimilarity ≥ 0.6 的既有规则会被强化（记一次命中、进 lessons）而不是复制一条。
6. curator 自带定时器（每 10 分钟问一次是否到期，那一次检查只读一个状态字段），只在空闲且距上次维护够久时把 staleAfterDays（14 天）以上的受管技能转成 stale、archiveAfterDays（30 天）以上的移进归档目录。被加载过 3 次以上的技能只标 stale、不自动归档——「有人还在用」比文件时间更可信。

把一整天的真实会话（一万多个事件）喂回插件：8 条看着像教训的东西，一条都没留下——每条都给出了自己的理由。这是一次真实的运行结果，不是挑出来的漂亮样本。

而真的踩过坑之后，它是这么记的：规则带具体命令、带出处、能脱开那次事故独立成立。上面这三条来自写这个插件时的真事——Tee-Object 的截断、robocopy 对单文件的退出码、以及「grep 搜不到不等于不存在」。

---

中央设计规则：确定性路径只提议，不判决

确定性路径只产出候选（零模型调用的候选队列）；写一个技能文件必须由模型自己的决定触发 —— learn_skill_manage create，或者 learn action=note。

这不是洁癖，是 v0.1.0 的一次事故换来的。

v0.1.0 的 REMEMBER_RE 里挂着裸的 \bremember\b|\balways\b|\bnever\b。它当时坐在裁判席上：命中就算「用户偏好」，直接落盘。于是这个插件存下的第一条「用户长期偏好」，是它自己调试正则表达式时写下的英文独白——一段关于 pattern、regex 和 edge case 的推理散文，被它自己的正则读成了「用户要求以后一直这么做」。

三处结构性修正：

• 谁写的文本，决定能声明什么。text.js 的 SOURCE_KINDS 按来源限定可声明的信号类型；助手的叙述不可能再被读成用户偏好，而它如果要推动落盘，只能以「有效做法 / 技能有错 / 失败后修复」的身份。
• 没有一条模式匹配裸副词。REMEMBER_RE 要求祈使句或习惯性框架（例如行首的 ^(?:always|never)\s+[a-z]），单独一个 always 什么都不是。
• 判别权交回模型。正则只给候选打分、排序、写进 pending.json；remember() 是唯一会碰技能文件的路径，而它只能由模型给出 statement 才会被调用。skillfile.js 里的常驻技能把这条分工写在第一段：「正则只负责回忆和打分，不负责判断。」

---

专属技能目录

用户要求「学到的技能收进自己的文件夹」。实现方式是单独一个技能根，不是共享根下的子目录。

为什么子目录做不到

宿主 provider @deepseek-ai/dsh-skill-filesystem 对一个技能根只扫一层：

// dsh-skill-filesystem/lib/index.js
function isPotentialSkillPath(root, path) {
  const segments = ...;
  if (segments.length === 0 || segments.length > 2) return false;
  // 1 段 → 根下的 *.md；2 段 → <name>/SKILL.md
}

<skills>/learned/<name>/SKILL.md 是 3 段，直接出局；chokidar watcher 也用 depth: 1。也就是说：把技能塞进 <skills>/learned/ 子目录，文件还在，但宿主的技能目录里看不见它们，/技能名 也加载不到。

为什么单独一个根可以，而且不需要动宿主配置

技能目录是一层提供者（@deepseek-ai/dsh-skill 的 SkillRegistry）的合并结果：每个提供者按 rank 从小到大参与合并，同名取 rank 小的。所以只要有人覆盖这个根就行。

“有人”很容易搞砸。最自然的做法是往 profile 的 cordis.patch.yml 里给宿主那个 skill-filesystem loader 条目加一条 customSkillDirs——这条路是死的，而且死得没有声音：

# <profileDir>/cordis.patch.yml
- id: skill-filesystem
  name: "@deepseek-ai/dsh-skill-filesystem"
  config:
    customSkillDirs: ["<DSH_HOME>\\skills\\learned"]

• 这条补丁会合成进最终配置树，--dump-config 里看得到 customSkillDirs 确实在了；
• 但它落在的是 host plane 那一行，而 @deepseek-ai/dsh-web-app 早把这一行 disabled: true 了（它把每个 agent 的行挪到了 agent preset 后面，skill 注册表本身留在 host plane）；
• 顶层 id 补丁只覆盖它重新声明的键，disabled: true 原样留着。于是配置看着对，provider 从来没挂载过。

所以插件不再向宿主申请，而是自己当这个提供者：lib/provider.js 通过 ctx.inject(['skills'], …) 调用 ctx.skills.registerProvider()，把这个根读进技能目录。不需要改 profile、不需要重启，rank 取 330——排在 custom 根（300）之后、默认 user-dsh 根（400）之前，项目根（100/200）仍然优先。

代价是必须守宿主的提供者契约，而它很严：validateCandidate 对一行不合法就直接 throw，一次 throw 会让整轮 collect 失败，所有根的技能一起消失。所以 list() 只发射已经满足宿主语法的行，其它一律跳过，并且不向外抛错：

• 目录名不匹配 ^[a-z0-9]+(?:-[a-z0-9]+)*$ → 跳过；
• 没有 SKILL.md（或根本读不出来）→ 跳过；
• description 缺失或只有空白 → 跳过（宿主要求非空）。

根不存在时 list() 返回 { candidates: [], complete: true }——空贡献，不是错误。

真实技能根就是：

<DSH_HOME>/skills/learned/

lib/config.js 的 skillsRoot 是 <DSH_HOME>/skills，lib/skills.js 只加一层 LEARNED_SUBDIR，并且这一步是幂等的（根已经以 learned 结尾就不再追加）。organize 提供出去的、以及 doctor 检查的，都是 skills.learnedDir 这一个值。

安全线：没被证明能看见，就不搬

learned 这个根在技能目录里真的出现之前，写进去的技能等于消失。所以插件不假设注册成功，而是问宿主的目录自己：

1. 往 skills.learnedDir 写一个一次性探针技能 learn-root-probe/SKILL.md；
2. 先调用自己那个 provider 的 invalidate() 丢掉宿主的 collect 缓存（缓存按 cwd + scope 链 + revision 存，不丢的话刚写进去的文件会被旧的快照一直盖住），再调宿主的技能目录服务（ctx.skills，退路 ctx.get('skills')），最多轮询 4 次、每次间隔 150ms，看这个名字回不回来；
3. 无论成败都在 finally 里删掉探针目录。

只有探针通过（skills.isLive() === true）之后：

• 新技能才写进专属根；在那之前一律写共享根，照常可用；
• migrateOwnSkills() 才肯搬东西，并且只搬本插件拥有的技能（managed.json 里有记录，或属于三个内置伞）；
• 共享根里同时存在旧副本时，删掉旧副本——否则旧的会盖住新的。

共享根里用户手写的技能永远不动（organize 会把它们列在「不动这些」里）。

怎么用

# 先看会改什么（只探测，不搬）
learn action=organize dryRun=true
# 真收拢
learn action=organize dryRun=false

organize 会：

1. 报告技能提供者是否注册上（已注册 —— 这个根由本插件自己提供，不需要改宿主配置）；
2. 跑上面那条探测安全线：探针不通过就到此为止，一个技能都不搬；通过了才收拢，并逐个 claim + 写账本 skill.organize；
3. 不碰 <profileDir>/cordis.patch.yml——这条写入路径已经删掉了，插件不该为了自己的功能去改用户的应用配置。

learn action=doctor 的 host-root 检查比对的是「插件真实技能根」与「已注册的根」，并注明是不是由本插件自注册提供的。

---

v0.1.0 的缺陷与 v0.2.0 的修法

审计出来的每一条，以及它是怎么修的：

审计之后、在自测里又抓出来的（这些是 v0.2.0 自己的 bug，不是 v0.1.0 的）：

v0.2.1：把插件放到真实对话里跑，它又露了一次原形

上面 20 条是读代码和单元测试发现的。把跑了一整天的真实会话喂回去重放之后，又抓出 6 条—— 它们有同一个共同点：测试夹具是我照着 schema 编的，而真实事件流不长那样。

真实会话重放的结果（6,223 事件 / 31 用户 / 992 助手 / 1,050 工具）：dry run observations: 78， 真跑 filed: 2，两条都是真的工具恢复教训（edit: Error: old_string was not found in … 和 edit: Error: old_string matched 2 times …; provide a more specific old_string or set replace_all to true）， 其余全部带着具名理由被拒。修 callId 之前，同样一次重放产出的是匿名的 ": Error: …"。

v0.2.2：专属根不再求宿主，改成自己提供

两个症状（learned_root_live: false、durable-preferences 一直显示 external 没被收编）其实是同一个病： 插件一直在请求宿主把 <DSH_HOME>/skills/learned 登记成技能根——往 <profileDir>/cordis.patch.yml 里加一条 customSkillDirs。那条补丁能被 loader 合并，却什么都不会发生：它落在宿主平面那一行 skill-filesystem （@deepseek-ai/dsh-web-app 把它设成 disabled: true），而顶层 id 补丁只覆盖它自己重述的键。

改法是插件自己提供那个根：lib/provider.js 用 ctx.inject(['skills'], …) 拿到 skills 服务， 再 registerProvider() 注册一个只扫专属目录的提供者，rank: 330——夹在 custom(300) 与 user-dsh(400) 之间，所以学到的技能压得住共享根里的旧副本，而项目根（100/200）仍然优先。 这条路的形状决定了模块的写法：@deepseek-ai/dsh-skill 的 validateCandidate 在遇到畸形行时是 throw， 一次 throw 会打断整个 collect，所有根里的所有技能一起消失——所以 list() 必须自己把宿主会拒的行全部过滤掉 （名字不合 /^[a-z0-9]+(?:-[a-z0-9]+)*$/、没有 SKILL.md、描述为空……），而不是指望宿主容忍。

v0.2.3：三处「输出比实际乐观」的谎

代码改对了，但工具说的话还停留在旧设计上。三条都是看着真实输出抓出来的：

v0.3.0：把整条回路接上，以及第一次有东西可看

v0.2.3 之后有人把 16 个模块重读了一遍、自己跑了自测、在临时 home 里做了两个探针，然后把盘上真实数据和 README 的每条声明对了一遍。它的总结论是：这条回路能捕获、能打分、能排队，但它从来没有变成学习——队列里有候选躺了一整天，三把伞技能里 0 条规则，usage.json 不存在，curator_runs: 0。六条都是同一个病的不同部位：没有人在正确的时刻被叫来。

同一个版本里还删掉了一批够不着的死代码：lib/blocks.js 从九个导出缩到一个（其余八个描述的是另一套系统：用户侧/环境侧的记忆分流、hub、external_dirs、读写前置守卫），lib/storage.js 的 writeReport/patchReport/moveToArchive/listArchived 和 reports/、staging/ 两个每次启动都建、从来没有写过的目录，lib/skills.js 的 stage。判据写在 blocks.js 的头部注释里：没有任何代码路径能走到的字符串不是文档，是第二份真相，而它只会漂移。

v0.3.1：把规则放进提示词，把后门关上

又一次独立审查——这次它读完了 16 个模块、跑了自测、在沙箱里复现了一个数据丢失 bug，还把宿主自己的插件开发指南从 app.asar 里挖了出来。那份指南正好给出了三个弱项的官方补法，于是这个版本一半是修 bug，一半是接上宿主本来就有、而这里一个都没用的扩展点。

这一版真正新增的能力：一个 lib/host.js，只走宿主指南里最弱的两级，并且每一级都是可选的（ctx.get(name) 拿不到就退化成「插件照常工作，只是少一层网」）：

• ctx.systemPrompt.section() —— 把判断标准放回模型眼前。一段字节稳定的纪律段落（order: 90），外加一段只在队列非空时才产出文字的队列提醒（order: 91）。字节稳定是硬要求：一段每回合都变的提示词会让前缀缓存每次失效。
• ctx.tools.guard() —— 关掉后门。技能库里的文件不再能被 write / edit 直接改：专属根整个是插件的，共享根按技能名判（共享根里还有别人的技能，一个拒绝 <dshHome>/skills 下一切路径的守卫，是在禁止别人改自己的文件）。路径比较是词法归一化的，所以 …/learned/x/../../learned/x/SKILL.md 这种爬出去再爬回来的写法照样拦得住。守卫在探测之后才挂——它要拿 learnedDir 做比较，而插件在那之前还不知道哪个根算数。
• 队列提醒为什么不用 agent.inject()：inject 把消息放进收件箱但不唤醒智能体，所以它无法让模型在触发它的那个回合里动手；而它可以在队列被读取的那一刻再次触发——一个等着发生的循环。提示词段落每次都在同一个位置说同一件事，不会循环。

自检现在 23 节 856 条断言（浏览器半边 454 条）：新增 host 一节（守卫该拦的拦、不该拦的放行、isInside 的六条边界、队列为空时不产生一个字的提醒、钩子一个都挂不上时报出原因），ledger 一节（真实 hits 序列 1,2,3,4,5、轮转、有界读、propose 行确实变小），以及医生新增的 host-hooks 检查——只有 tools.guard 挂了才算故障：两段提示词是建议，而守卫是「技能只能经 learn_skill_manage 修改」这句话的凭据；没有它，那句话只是提示词里的说法。

v0.3.2：变异测试没抓住的那几个守卫

第三次独立审查换了一个方法：往代码里注入 22 个缺陷，看测试能不能发现。它抓住 14 个——写/编辑守卫、提供者的候选过滤、规则缩水拒绝、账本落盘、数据倾倒拒收，全都在。剩下 8 个不但没抓住，两套测试还照样打印 all green。一个没有任何测试能看见它失效的守卫，离变成装饰只有一次重构的距离。

这一节里最该留下的一句：这 8 个漏网的缺陷不是在读代码时发现的，是先假设「如果我把它改坏，测试会不会红」再一个一个试出来的。新增的 safety 一节（21 节里的最后一节）就是这么来的：每一条断言都对应一个「改了它、测试却还是绿的」的具体变异。查 N-C1（不带 confirm 的删除必须归档）那条尤其说明问题——原来唯一调用 delete 的测试在上一行的权限检查就退出了，那个分支从来没有被任何测试执行过。

v0.3.3：第二次，拒绝理由本身是那个 bug

v0.3.2 发完之后，作者按自己的纪律用这个插件记一条事实——被自己的门槛拒了，而拒绝理由是：

缺少可迁移的做法或具体对象……把命令名、参数、路径、文件名用反引号括起来。

那句话里有六个反引号括起来的路径。照着提示做只会再加反引号，永远进不去。真正的原因在 lib/text.js 的 isActionable 里：hasConcreteDetail(source) && source.length <= 200——具体对象是有的，超了 200 字。这个阈值是写死的字面量，文档里没有，拒绝理由里也没有。

两个反引号、两个数字，都不是靠读代码发现的，是靠用发现的：第一次是 v0.3.0 用这个工具记东西被拒（理由没说补救办法），第二次就是这条（理由说错了补救办法）。同一个 bug 在同一个函数里出现了两次，都是「拒绝理由是假的」——所以这一节的教训不是「阈值要调」，是拒绝理由和判定条件必须是同一个来源。

v0.3.4：同一行里「记住」和「没能记下」

回执是给正在用的人看的，所以它的措辞就是功能本身。v0.3.3 的回执行长这样：

学习 · 记住一条环境事实 · 做法没能记下 · 环境事实没能记下 · 记住一条做法

两个成功了、两个被拒了，但读起来像自相矛盾——因为成功那一半是祈使句，失败那一半是陈述句。英文两份词条一直是对的（saved a technique / could not save the technique：同一个动词、同一个宾语，只有结果词不同），只有中文在写的时候跑偏了。