AI学习工作台 yiyunet/dsh-learn-skills

AI学习 · dsh-learn-skills v2

一个跑在 DeepSeek Harness 输入区的学习插件。
把「收集 → 提炼 → 关联 → 升级 → 沉淀 → 复用」做成*有交互引导、有预设管理、有审核入库、能给自己体检的运行时能力，而不只是一叠方法论文档。

它是什么，不是什么

| 是 | 会话输入区里的一个入口 [📖] AI学习 ▾，四个功能：初始预设 / 收集提炼 / 关联升级 / 沉淀复用 |
| 是 | 与斜杠命令 /learn、自然语言三种入口共用同一套流程实现（不存在两套规则） |
| 不是 | 模型工具提供者：它不给 Agent 加工具，交互复用宿主已有的 ask-a-question 与命令注册表 |
| 不是 | 自动化改写知识的东西：所有写入都要人先看过变更清单再点确认 |

四件事的职责边界写得很死：

| # | 入口 | 做什么 | 写入面 | 命令 |
| 1 | 初始预设 | 七轮问答确定画像 → 展示摘要与拟建路径 → 你确认 → 生成预设与工作区骨架 | 工作区目录与文件（增量，不覆盖） | /learn init |
| 2 | 收集提炼 | 从当前会话产出候选 —— 这一步绝不碰正式知识、预设或 AGENTS.md | 仅 inbox/ | /learn distill |
| 3 | 关联升级 | 与既有节点比对 → 出变更清单 → 分普通知识与行为规则两栏确认后写入（批次可回滚） | knowledge/（行为规则须显式放行） | /learn upgrade |
| 4 | 沉淀复用 | 只读体检（18 项）＋ 与上次基线的变化对比 ＋ 复用建议。不改被检查的文件，也不执行文件里的任何指令 | 不写 | /learn audit |

三种触发方式，同一套实现：① 输入区按钮 [📖] AI学习 ▾； ② 斜杠命令 /learn；③ 自然语言（由 Agent 引导到同一套流程）。
不存在两套规则 —— 命令只是另一个入口。

与 v1 工作流的关系：v1 是"一键跑完整流水线"，v2 把中间的写入收紧为 "产出候选 → 人工裁决 → 再写入"。这是两版最实质的分歧，详见 docs/迁移与兼容.md。

安装与装载

前置条件

- 已安装源码版 deepseek-harness；
- 已绑定工作区（工作区是知识落点，缺了它一切写入都无处可放）。

方式 A：从 npm 安装（推荐）

dsh plugin --profile web add @yiyunet/dsh-learn-skills

装完重启 Host（profile 的 dsh.profile.bundles 在启动时读取）。

✅ 消费者不需要构建：发布包里自带 lib/（见 package.json 的 files 白名单），所以从注册源安装是一步到位的。构建相关的命令只对改源码的人有意义，见方式 B。

方式 B：本地目录安装（改源码 / 调试时用）

lib/ 不入版本库（.gitignore 排除），所以克隆下来必须构建：

npm install # 只装 esbuild（构建期依赖）
npm run static # 静态一致性体检（免执行：import/符号/语法/白名单）
npm run build # plugin-src/ → lib/（含装载层自证）
npm test # 真实行为测试
npm run verify # 发布契约断言

把本机该目录装进 web profile（路径按你的实际位置替换）
dsh plugin --profile web add link:
或在 profile 目录里直接：
pnpm add link:

📌 npm install 结束时会自动构建一次（prepare 钩子，钩子名 scripts/postinstall.mjs）。
上面那句 npm run build 因此是幂等的复跑，不是必做步骤 —— 保留它是为了让"构建" 在流程里显式可见。

检查装载是否成功

- 输入区工具行出现 [📖] AI学习 ▾（在「工作区内修改」控件右侧）；
- 斜杠菜单里出现 /learn；
- /learn help 列出四个入口。

用法

按钮

点 AI学习 ▾ → 选一个入口。菜单顺序固定：初始预设 / 收集提炼 / 关联升级 / 沉淀复用。

- 执行中会显示状态；重复点击不会产生并发写入 —— 同一工作区同时只允许一个流程，第二次会被明确拒绝；
- 有「取消」按钮：取消后不再启动后续写入步骤，已完成的步骤如实汇报；
- 未绑定工作区时菜单里直接给出引导；
- 尚未初始化时，后三项会先识别已有知识库：识别到就直接用，识别不到才引导你先做「初始预设」。

斜杠命令

/learn help 列出四入口 /learn init 七轮问答（确认创建要在界面上点，见下） /learn distill 从当前会话产出候选 /learn upgrade [批次号] 出变更清单 / 写入 /learn audit 只读体检 /learn rollback 回滚某个变更批次

命令与按钮背后是同一个 flows 实现：命令只是另一个入口，不附带第二套规则。
需要"确认"的步骤（创建预设、写入变更）在命令侧用 --confirm 表达，但默认路径是界面上确认 —— 因为要让人先看清变更清单。

自然语言

插件不拥有模型工具，所以"自然语言入口"由工作区技能 learn- 承担：你直接说「帮我初始化学习体系」「把这次会话里的内容提炼成候选」，Agent 读技能后调用同一套流程。

七个问题问了什么前两题固定，第 3 题起由模型逐轮现场生成（每轮带上已采集的全部信息、剩余轮次与已问话题）；模型不可用时逐轮回退到硬编码题库，流程不中断。

| # | 主题 | 要点 |
| 1 | 名字 | 自由输入；空值/长度/保留名/非法字符都校验；重名请你换名，不覆盖也不替你改名 |
| 2 | 身份 · 面向 · 期望 | 三段式一条文本：职业 ｜ 面向什么（人群或事情）｜ 期望达到什么，带例子；回显第 1 题；只填一段就只当职业，其余保持未知；不索要单位/真名等无关信息 |
| 3 | 关注方向 | 模型按你的三参数出题与选项；降级时按「场景池 → 职业池 → 通用池」三级匹配给 7 个方向 +「其他，请输入」；支持多选与自定义 |
| 4 | 学习目标与典型任务 | 模型按上下文出题；降级时围绕固定主题给候选与自定义 |
| 5 | 当前基础与实际困难 | 同上 |
| 6 | 学习方式与输出偏好 | 同上 |
| 7 | 最想先解决的一件事 | 模型出题；降级时给"越快越好/先打基础/固定节奏"等候选 —— 这一项决定先做什么、后做什么 |

设计上刻意的三件事：

- 未填写 = 未知。跳过项在画像里是 null 并标注"未知 —— 未填写"，不编造画像。
- 推荐就是推荐。关注方向的措辞是"可能关注"，不伪称统计出来的"职业最高关注度"。
每题都能「返回修改」；改前置答案时，后续题每轮现取，天然重算。
- 模型只定题面，落库槽位固定。模型的自主性在"问什么、给哪些选项"；答案写进哪个画像字段由插件固定，避免模型报的维度绕过"未填写＝未知"的归一化而静默丢数据。

七题结束后展示：画像摘要 / 预设定位 / 知识框架草案 / 拟创建或修改的路径清单，然后你才能点「确认创建」。创建完会给出结构自证、安装指引，并提示：

请安装该 bundle（本插件不代为安装），然后新建会话，选择预设 。

⚠️ 预设在一个进程内按 standing scope 挂载一次（源码：packages/preset/agent-preset-registry 的 src/mount.ts roster/standing mount）。新预设不会在当前会话即时生效 —— 本插件不宣称热更新。

🔐 为什么"安装"这一步不代做：安装 bundle 会在 Host 进程执行新代码。官方入口 plugin_manager 工具为此强制弹 danger-full-access 审批（源码： packages/boot/plugin-manager/src/tools.ts:34-41），而服务方法 installBundle() 本身没有审批闸（同包 src/index.ts:417-447）—— 插件直接调它，等于替你越权。
所以本插件只生成、只出指引，点头的动作留给你：

① 终端一行（最省事）
dsh plugin --profile web add link:

② 或在「创造模式」会话里让 Agent 调 plugin_manager（会弹审批卡）
action=install_bundle, target=

复核：plugin_manager 的 list_plugins（找 preset- 行）或 GUI「设置 → Agent 预设」看它是否进名册撤销：dsh plugin --profile web remove @local/dsh-learn-preset-

🗑 要删掉一个预设（"干净删除"的完整四步）：见 docs/删除预设.md。
先记住三件事：① 新版没有"删除预设"按钮（设置页只能查看/选择/设为默认），能删的是它所在的那个 bundle；② 卸载之后还要删 /.dsh/preset-bundles// 目录，并且清掉 known.json 里的占用（否则同名重建会拿到 -2 后缀）；③ 同包多预设时不能卸整包。

⚠️ 那个 bundle 目录在工作区内（/.dsh/preset-bundles//），它是活的：宿主重启时按预设 id 在当前配置里解析，定义缺失的会话会被拒绝恢复。
所以不要删也不要移动它；要撤掉请先用上面的 remove 摘掉 bundle （完整步骤与"删错了怎么救"：docs/删除预设.md）。

工作区结构

AGENTS.md 工作区原则与知识入口（精炼、稳定） index/ 外部原始材料（保留来源与原文） inbox/ 标准化材料、待审核候选、提炼批次 knowledge/ framework.md 正式知识体系的唯一总索引 nodes/ 正式知识节点 data/ 待分析数据（不默认转为知识或长期记忆） task/ 学习任务、执行状态与待办 reports/ 体检报告、复盘与变化记录 .dsh/ skills/ 工作区技能 learn-skills/ 本插件状态：批次账 / 体检基线 / 变更日志 / 断点 preset-bundles/ 本插件生成的预设 bundle（★2.1.0 起落在这里；删它会连带废掉对应预设）

关于 skills/：默认不与 .dsh/skills/ 重复存技能。宿主的 skill-filesystem 只扫 /.dsh/skills（rank 100），根目录下的 skills/ 不会被加载；如果确有需要独立分发的技能，请用 .agents/skills（rank 200）并在文档里写明用途。

增量迁移既有工作区

初始化是增量的，绝不清空：

- 目录：不存在才建，已存在无操作；
- 文件：内容相同 → 跳过；内容不同 → 标为 conflict 并一个字都不写，在结果里明确告诉你哪个文件被挡下了、为什么；
- 重复运行幂等：不会重复创建，也不会覆盖你后来的修改。

迁移与 v1

本版（v2）是完全重写：四个入口是运行时能力，不再以"一叠方法论技能"的形态分发。
- 不提供 v1 技能的迁移路径 —— v1 的 skills/learn- 技能包已从本仓移除；
- 需要 v1 方法论文本的作者，请见本仓的历史版本（若已归档）；
- v2 的功能不依赖任何 v1 技能：装好插件即可用四个入口与 /learn 命令。

数据与状态

全部状态都在工作区内的 .dsh/learn-skills/，不写宿主配置：

| 文件 | 内容 | 寿命 |
| session.json | 单次流程的断点（可取消、可续办） | 流程结束即清 |
| batches.json | 已处理批次账 + 内容指纹 → 批次（“不重复创建候选”的判据） | 长期 |
| audit.json | 上次成功保存的体检基线 | 长期（只增） |
| known.json | 已分配过的节点 id 与预设占用 | 长期（不回收） |
| changes/.json | 变更日志（回滚依据；含写入前内容） | 长期 |

预设本体是一个可安装的 bundle，落在 /.dsh/preset-bundles// （恰好两件：package.json + cordis.patch.yml）。目录名可用 config.presetDir 改，整个根也可用 config.presetRoot（绝对路径）覆盖。

🗑 删掉一个预设：见 docs/删除预设.md ——独立成包的走四步法（关行确认 → 卸包 → 删目录 → 清 known.json 占用）；与别人共用一个组合包时不能卸包（会带走同包所有预设），只能改那份 patch 的声明段；以及删错了的黄金窗口（重启之前补回声明＝零损失）。

⚠️ DSH 0.1.7-alpha.1 起预设改为声明式（提交 feat(preset): declare Agent compositions in profile YAML）：旧的 /.agent-presets// 目录已无人读取，预设必须是 @deepseek-ai/dsh-agent-preset 的一个 Loader 条目。
只写盘不算预设存在 —— 必须安装该 bundle 才会进名册；安装由你经 plugin_manager（强制审批）或一行 CLI 完成，本插件不代做（见上文“为什么”）。
0.1.6-alpha.2 及更早生成的旧式目录预设不会自动迁移，需手动转成 bundle （见 docs/迁移与兼容.md）。

🧭 身份判据来自宿主名册：init 会先读 ctx.agentPresets.list()（注册表 roster）再判重 —— 因为新架构里预设身份＝声明行里的 config.id，而注册表不扫描目录（一份组合包可以声明很多个预设：本机 dsh-migrated-presets 一个文件里就有 12 个）。
名册读不到时直接拒绝创建（ROSTER_UNAVAILABLE，一个文件都不写）——宁可不出件，也不出一个与既有预设重复的 config.id （官方原话：「重复的 preset ID 会导致声明加载失败」）。

回滚

/learn rollback

- 新建的节点被删除，更新过的被还原；
- 写入之后被你改过的文件一律不动，并列入“跳过”如实上报 —— 回滚不会变成第二次覆盖；
- 日志在 .dsh/learn-skills/changes/.json。

配置

cordis.patch.yml 里的全部字段都有中文注释。默认值的关键两条：

allowWrite: true # 总闸。关掉后四项功能变纯只读（初始预设只出预览） allowBehaviorRules: false # 行为规则（预设提示词 / AGENTS.md / 技能）默认不放行

第二条是刻意的：一条知识被认可，不会自动变成长期指令。会影响 Agent 行为的那类变更，必须由人显式打开这个开关，才会在「关联升级」的确认里被执行。

语义增强（方案 B-1：双轨并存 + 冲突标记）

默认关闭，开关与预算都在 cordis.patch.yml：

allowModelSemantics: false # 打开后：提炼会把会话原文发给模型做语义判定 semanticBatchSize: 8 # 一次调用判多少条（越大越省，延迟越高） semanticBudgetMs: 60000 # 总预算；用尽即停，剩余候选走基线轨

为什么默认关：打开后会话原文会发给模型。会话里可能有客户信息、平台账号线索、内部报价 —— 这是数据出站，属合规红线，故默认不启用。

它做什么：给「收集提炼」加一条语义轨——模型判定每条候选的类型、以及它与已有节点的关系（new/supplement/correction/conflict/duplicate/supersede/unverified），并给出 why（依据哪几个字得出的）。

为什么不覆盖基线（这是设计地基）：模型输出不可复现——同一份内容两次提炼可能给不同判定。若覆盖基线，就会出现“同一知识两次入库分类不同 → 版本号无故 +1 → 索引抖动”，留痕与可回溯性当场失效。所以采用双轨并存：

| 轨 | 谁产生 | 可复现 | 落盘字段 |
| 基线轨 | 关键词正则 + 词面重合 | ✅ | type / relations（confidence: 'heuristic'） |
| 语义轨 | 模型 | ❌ | typeSemantic / relationsSemantic（confidence: 'model'）+ why |

两轨一致时不产生额外字段；不一致时并排显示并标 typeDivergence / relationsDivergence，审核面板会把模型建议明确标注为「模型」——最终判定仍由你裁决。

降级纪律：没有模型 / 超时 / 输出不是合法 JSON / 超预算 ⇒ 静默回退基线轨，候选照常产出，提炼流程一秒不停（与「初始预设」的“模型优先、硬编码兜底”同构）。
⚠️ 两个如实标注：① 语义增强部分生效时（达到预算或某批失败），界面与批次文件都会标明“未跑完”，不会假装全部完成；② 批次文件里的 semantic 摘要记录了几次调用、几处分歧，便于事后回溯。模型输出一律严格校验、绝不修补——编造的候选 id、非法 type/relation 一律丢弃。

开发

npm run static # 免执行静态体检（import/符号/语法/白名单）
npm run build # 构建（宿主半侧复制 + 客户端 esbuild 打包 + 装载层自证）
npm test # node --test：真实行为测试（真跑文件系统）
npm run verify # 10 组发布契约断言
npm run check # ★ 上面四步一次跑完：static → build → test → verify
npm run inspect # 产物体检

架构约定（与生态基准件 @yiyunet/dsh-dingtalk-connector 对位）：

- plugin-src/ 是唯一真源，lib/ 是产物，改产物会被下次构建覆盖；
- 宿主半侧只用 Node 内置模块与宿主运行时提供的包，不得把 @deepseek-ai/dsh- 写进依赖节（运行包用模块局部 Symbol 做 key，装第二份物理副本会破坏 Host 查找）；
- 客户端半侧只能引 react 系（平台冻结模块表），第三方依赖一律不许进；
- 客户端产物必须由 wrapper 把 bundle 嵌进 __ModuleLoader__.load 的 factory 内部 ——放在外面会在脚本顶层执行到 require("react")，整个 /plugins 拼接 bundle 会全灭。

排错

按症状查。每条都给出“为什么”和“下一步”。

装完看不到 [📖] AI学习 ▾

| 检查 | 说明 |
| 重启 Host 了吗 | ★ 最常见的原因。dsh.profile.bundles 在启动时读取，改完 profile 必须重启才生效 |
| 装对 profile 了吗 | 必须是 --profile web（客户端半侧只在 web profile 注册） |
| 包真的在吗 | dsh plugin --profile web list，或直接看 profile 的 bundles 列表 |

菜单能弹，但点了报 HTTP 404

报错形如 transport failure for /api/dsh-learn-skills: HTTP 404。

根因：HTTP RPC 端点没注册上。connection 服务属于 Web 运行时那一层，在插件 apply() 那一刻可能尚未就绪 ⇒ 注册机会被错过。

为什么本插件不该出这个问题：它不把 connection 写进静态 inject（那会让插件在无 Web 运行时的部署里整体 inactive），而是挂到它就绪之后再注册。
npm run verify 的 ⑤-b 组断言专门钉住这一点。

⇒ 若你确实看到这个 404：把 ~/.dsh/ 下的宿主日志里 learn-skills 相关行发出来。

点「初始预设」立刻报“无法读取宿主预设名册（agentPresets）”

这是刻意设计，不是 bug。 拿不到名册就无法保证不生成重复的 config.id （官方明写“重复的 preset ID 会导致声明加载失败”）⇒ 宁可不落盘。

⇒ 此时其余三个入口不受影响，手工加预设照旧。

点「确认创建」后提示“尚未安装”

这也是刻意的（2.1.0 起不代装）：安装 bundle 会在 Host 进程执行新代码，官方入口 plugin_manager 为此强制弹 danger-full-access 审批，而服务方法
installBundle() 本身没有审批闸 ⇒ 插件直接调它等于替你越权。

⇒ 照提示跑那行 dsh plugin --profile web add link:，或按 README 「七个问题问了什么」末尾的说明操作。

「收集提炼」产出为空或候选很少

| 原因 | 判据 |
| 本次会话内容被判为噪声 | 寒暄、空内容不计入（isNoise，宁可漏判） |
| 这段消息已被处理过 | 会标 alreadyProcessed，不重复创建 |
| 会话历史不完整 | 报告里会标“部分范围”；historyComplete: false 说明发生过 replace 压缩 |
| 上限截断 | stats 里如实反映，不静默丢失 |

语义增强（allowModelSemantics）没生效

默认就是关的（打开会把会话原文发给模型，属数据出站，须显式开启）。

打开后仍不生效时，按降级纪律逐条查 —— 以下任一都会静默回退基线轨（不抛错）：无模型 / 超时 / 输出不是合法 JSON / 超预算。批次文件里的 semantic 摘要会记 “几次调用、几处分歧”，以及是否跑完（部分生效会明确标“未跑完”，不假装完成）。

想确认“模型到底有没有在工作”

判据只有一条 —— 宿主日志：

第 N 题未由模型生成，已回退到通用候选：

看到它就说明那一轮是降级跑的。别用“问题看起来够具体”当判据 —— 硬编码兜底候选里也有具体选项，没有区分力。

npm run check 报“缺少必需文件”或断言失败

先看它具体报哪一组。10 组断言每组对应一个真实失败模式， scripts/verify-package.mjs 里每条都有注释说明“为什么钉这一条”。
最常见的一类是 lib/ 与 plugin-src/ 不同步 —— 改完源码没重建：

npm run build && npm run verify

卸载

第一步：摘掉插件

dsh plugin --profile web remove @yiyunet/dsh-learn-skills

或走 GUI：设置 → 插件，找到它移除。改完重启 Host。
⚠️ 卸载只是“不再装载”，不会删你的数据。

第二步（可选）：清掉插件留下的状态

都在工作区内，插件不写宿主配置：

| 路径 | 内容 | 删掉的后果 |
| /.dsh/learn-skills/ | 批次账 / 体检基线 / 变更日志 / 断点 / known.json | 丢“上次基线”与回滚依据；知识节点本身不受影响 |
| /.dsh/preset-bundles// | 本插件生成的预设本体 | ⚠️ 会连带废掉对应预设（宿主重启时解析不到定义，该预设的会话会被拒绝恢复） |

🗑 要删预设，请走四步法，不要直接删目录 ——见 docs/删除预设.md：关行确认 → 卸包 → 删目录 → 清 known.json 占用。同包多预设时不能卸整包（会带走同包里所有预设）。

第三步：你的知识库不会被删

AGENTS.md / index/ / inbox/ / knowledge/ / data/ / task/ / reports/
都是你的资产，插件从不删它们。卸载后它们原样保留，可用任何工具继续使用。

回滚写入而非整个卸载？用 /learn rollback —— 它只还原本插件写过的，且写入之后被你改过的文件一律不动。

许可

MIT。见 LICENSE。