yuezengwu/dsh-explain

English | 简体中文

dsh-explain — DSH 学习模式插件

✅ 状态：M6 已完全在 Explain 内实现并通过 DSH 0.1.0-rc.6 验收；无需修改或依赖其他插件。 产品需求见 docs/PRD.md；技术方案见 docs/ARCHITECTURE.md。

一句话定位：把多个 DSH 工作会话中值得学习的内容汇入用户唯一的全局学习线程，为每个来源会话保留至多一个活跃讲解，并用全局学习上下文持续适配用户的知识水平和讲解偏好。

核心形态

• 一个 $DSH_HOME 只有一条本地学习线程；工作会话、恢复和 fork 不复制学习状态。
• 每个顶层来源会话可以有一个等待反馈的讲解，也可以没有；同一来源未反馈时不再生成第二条，其他来源仍可继续。
• 用户可在任意已建立或空白工作 Session 的 composer 输入 /explain <学习请求>，主动要求 explain agent 生成一条讲解；管理命令 /explain on|off|status 保持不变。
• 用户可选中可见文字后使用 composer 工具行中的 Explain 快捷入口，也可在任意已完成 assistant 回答上选择「学习这个回答」；两者只创建可编辑草稿，绝不自动提交。
• 主动讲解、自主讲解、重讲和压缩共享全局调度器，任何时刻最多一个辅助模型请求；主动请求优先于后台工作，但不打断已在途的主动请求或重讲。
• 自主判断默认最多发送 50 次/滚动 24 小时；占额跨重启保留，失败和重试计数，用户触发的主动讲解、重讲与压缩豁免。
• explain 维护私有的全局 ExplainContext，汇总对话偏好、知识概况和学习进展；它只进入辅助模型，不注入主 Agent。
• 有新的结构化观察或已关闭讲解且用户连续 30 分钟未操作 explain，或预计辅助请求占所选模型上下文 50% 以上时，自动压缩辅助模型历史；用户可见原始记录不删除。
• 主模型不知道 explain 存在；explain 不写主 Session 日志、不注入主模型上下文、不阻塞主 turn。
• 学习历史、来源活跃状态、压缩检查点和 ExplainContext 持久化到 $DSH_HOME/dsh-explain/v1/thread.sqlite；开关与模型设置走 $DSH_HOME/settings.yaml。
• 首个讲解 entry 保存最多 2,000 字符的受限来源摘要供后续重讲；来源 Session 删除不影响重讲，摘要不向学习视图返回。
• 学习线程使用 DSH 第一方 conversation.view 槽位中的「学习」Tab；普通配置与运行诊断使用第一方 settings.section，不引入外部 UI 宿主。
• 「学习」是 Session-scoped 视图入口，但业务数据来自同一个全局 client store 和 typed Remote；不同工作 Session 看到同一条学习线程。
• 设置页和学习视图复用同一个 browser store；用户可在设置中选择辅助模型、启用学习模式、调整滚动 24 小时自主额度，并查看路由、额度恢复、上下文压力和最近压缩。
• 讲解来源仍在当前 Session inventory 时可直接打开；来源被删除后历史保持可读并显示不可用。
• P0 不自动切换视图。空白 Session 的 Hero 阶段不显示视图 Tab；进入学习视图后，当前工作 Session 的 composer 仍然保留。
• P0 没有外部 UI 依赖，不携带或要求安装 better-sidebar。

动机

• DSH 能完成复杂工作，但用户通常只看到结果，不一定理解过程中用到的概念、取舍和常见误区。
• 学习模式把工作会话变成学习素材来源，不要求用户先知道应该问什么。
• 用户的学习事实和进度需要跨工作会话保持一致，因此所有内容进入一条全局线程；按来源保留的活跃讲解让用户回到相关工作时继续反馈。

当前进展

• 需求查重：产品目标无直接重复，相关插件可提供局部实现参考。
• PRD P0 定稿：单一学习线程、按来源活跃讲解、自主调用预算、双触发压缩、全局 ExplainContext 和可自动验证的验收标准。
• 技术架构 v11：两个快捷适配器都由 Explain 通过 DSH 第一方槽位拥有；可选插件保持不变且不被观察。
• UI 路径核验：沿用第一方 ui-trajectory 的 ctx.slots.inject('conversation.view', ...) 注册方式，无外部 UI 依赖。
• M1 基础设施：独立插件构建、本地 SQLite schema、实体级 CAS、分页/长轮询和自动生成的 typed Remote。
• M2 主实现：来源观察、辅助模型单飞调度、持久预算、重讲、双触发压缩、ExplainContext 与 conversation.view 学习界面。
• M2 真实 DSH Web/模型流程验收与 GIF。
• M3 发布门禁：P0 验收矩阵、无密钥 assembled Web snapshot、安装与组合 smoke。
• M4 内测可控性：无 YAML 设置页、并发设置收敛、来源跳转/缺失降级、共享诊断 store 和扩展 assembled Web snapshot。
• M5 主动学习命令：composer 中的 /explain <学习请求>、显式请求调度、来源标识、持久重讲摘要和稳定失败结果。
• M6.1 Explain Host 协议：--selection / --answer <turn> 来源定位、origin 持久化、重讲传播、旧 --suggested 输入兼容和稳定失败。
• M6 P1 实现：选中文字、精确 assistant 回答和用户显式选中的 Advisor 可见建议，经 Explain 自有可编辑草稿进入同一学习闭环。

M1 建立持久层和 Host/Client RPC 基础；M2 完成学习闭环；M3 建立 P0 发布门禁；M4 让内测用户无需编辑 YAML 即可配置和诊断，并能从讲解返回仍存在的来源会话；M5 允许用户从工作 composer 主动发起一次学习；M6 增加 Explain 自有快捷入口，不修改可选插件。自动化证据见 验收矩阵。

当前迭代

M6 由 Explain 在 conversation.input.left 注册选区动作，并在 conversation.chat.assistant-actions 注册精确回答动作。两者只使用公开的 Session input facade，点击时重新校验 composer，只写可编辑草稿；dsh-selection-chat、dsh-suggested-replies 与 dsh-advisor 均无需修改、安装或暴露私有状态。完整范围与证据见 迭代记录。

安装

Explain 当前适配 DSH 0.1.0-rc.6。DSH 仍处于开发者预览阶段，本插件不支持更早的私有预览包版本线。

npx @deepseek-ai/dsh@0.1.0-rc.6 plugin --profile web add github:yuezengwu/dsh-explain
npx @deepseek-ai/dsh@0.1.0-rc.6 web

Git 仓库插件会在安装时构建。如果 pnpm 要求批准构建，请按错误信息把 dsh-explain 加入该 profile 的 pnpm-workspace.yaml，然后重新运行安装命令。

本地开发

默认构建使用公开的 DSH 0.1.0-rc.6 API 包。assembled Web 验收仍需要已构建的 DSH 源码 checkout；安装依赖后显式建立本地链接：

pnpm install
DSH_SOURCE_DIR=/absolute/path/to/dsh pnpm run dsh:link
DSH_SOURCE_DIR=/absolute/path/to/dsh pnpm run dsh:link:check
pnpm run test
DSH_SOURCE_DIR=/absolute/path/to/dsh pnpm run test:web
DSH_SOURCE_DIR=/absolute/path/to/dsh pnpm run test:m6
pnpm run typecheck
pnpm run build

源码 checkout 必须匹配 0.1.0-rc.6 的公开 API；插件不保留更早私有预览版本线的兼容层。

test:web 使用全新临时 $DSH_HOME、持久 Session fixture 和预置 Explain SQLite 运行无密钥的真实 DSH Web 组合，并比对学习视图与设置页 ARIA golden；它还验证 native settings revision 写入、可用来源跳转和缺失来源降级。更新有意的界面输出时运行 DSH_SOURCE_DIR=/absolute/path/to/dsh pnpm run test:web:refresh 并审查 snapshot diff。

test:m6 只把 Explain 安装到全新 profile，验证消费方插件均不存在、两个快捷入口都只生成精确可编辑草稿，以及卸载并重新安装后完整层只恢复一次。

开发验收使用本地目录安装，不经过 npm：

dsh plugin --profile web add /absolute/path/to/dsh-explain
dsh --profile web --dump-config
dsh --profile web

查重结论（2026-08-12）

产品目标无直接重复；以下项目只作为局部先例，不作为本项目的数据模型。

仓库	可复用部分	明确不复用的部分
dsh-auto-blame	回合结束后的后台模型调用、客户端反馈形态	外部自定义 Session 事件与 projection 不能作为本项目持久化方案
dsh-advisor	转录增量、模型调用隔离、发射保护和配置 gateway	advisor 向主 agent 注入建议；explain 永不注入主模型
dsh-memory	仓库命名覆盖长期记忆方向	当前只有占位 README，没有可复用服务或协议
dsh-memory-evolve	跨会话分层记忆、低频快照与用户可见管理经验	未公开 Cordis memory service，且快照进入主 Agent；explain 不依赖或读取其私有文件
DSH compact-basic / token-meter / LLM model info	容量阈值策略、固定 token 估算和精确路由 contextWindow	原生 compact 只修改单个 Session surface；explain 需要自有全局 SQLite compactor
DSH 第三方 memory MCP 示例	跨会话持久记忆的可选互操作参考	模型主动工具调用和外部 provider 不适合作为 P0 自动 ExplainContext
DSH ui-trajectory	conversation.view 视图注册、Session 头部 Tab 和 active-only 渲染先例	trajectory 的 Session 事件视图模型；学习事实仍使用插件自有 SQLite 与 Remote
DSH-better-sidebar	侧边工作台交互参考	P0 不需要边工作边查看，因此不引入其服务、源码副本或依赖树
official-plugins-port 的 claude/learning-output-style 与 claude/explanatory-output-style	学习与解释类提示词参考	纯 system prompt 无法提供独立调度、持久历史和反馈闭环
dsh-edu	后续知识沉淀格式	P0 不做课程、测验、卡片或复习系统

许可证

本项目使用 MIT License。