# 升级记录

按版本记录用户能感知的新增功能、改进、修复和升级操作，最新版本在前。技术变更清单见 [CHANGELOG](../CHANGELOG.md)，接入参数见 [嵌入协议](EMBED.md)。记录日期不等于 npm 发布日期；是否已发布以实际 npm/GitHub Release 状态为准。

| 版本 | 记录日期 | 本次主要变化 |
| --- | --- | --- |
| [未发布](#unreleased) | 2026-08-31 | 移除 `@` 文件补全，让位 DSH 原生提及菜单 |
| [0.2.1](#v021) | 2026-08-30 | 草稿写回与发送保护、工作区隔离、诊断降噪、安装兼容性收尾；待发布 |
| [0.2.0](#v020) | 2026-08-29 | 五维诊断、流式增强、知识区、文件补全、模板变量与极简模式 |
| [0.1.0](#v010) | 2026-08-26 | 方法工坊、快捷增强器与可嵌入的初始工具包；依据已有变更日志整理 |

<a id="unreleased"></a>
## 未发布：移除 `@` 文件补全，让位 DSH 原生提及

记录日期：2026-08-31。尚未收口为正式版本。

### 移除

- 快捷增强器不再在宿主输入框上提供 `@` 文件引用补全菜单；同步移除了 `Embed` 接入参数 `searchFiles` 与 Node 半区的 `/dsh-promptkit/workspace-files` 检索路由。草稿中已写好的 `@path` 引用不受影响：增强时仍受「保留 @ 文件引用」保护，发送后由 DSH 原生机制读取文件。

### 为什么移除

- 与原生功能完全重复。经拆解 DSH `0.1.2-alpha.2` 的 `dsh-file-reference` 与 `dsh-client-ui-reference` 确认：原生 `@` 提及与插件补全是同一件事（输入 `@path` token 触发候选、选中后插入规范 mention 文本、选中本身不读文件），且原生是严格超集——额外提供会话候选、目录逐层下钻（Tab/尾斜杠）、含空格路径的引号语法与原子行内引用。该功能最初是为尚无原生 `@` 的旧 Web profile 补位，原生覆盖后已无独立价值。
- 重叠产生实际冲突，不只是难看：两个菜单同时弹出互相遮挡（zIndex 20004 的插件菜单压在原生菜单上方）；插件在 window 捕获阶段吞掉 ↑↓/Enter/Esc，导致原生菜单无法用键盘操作；插件插入时整段重写草稿尾段，会破坏原生的原子行内引用。
- 修复方式比较后选择了删除而非共存。`/pk` 式命名空间共存适用于宿主没有的功能；对宿主已覆盖的能力，重复实现即是负价值，嗅探宿主 DOM 让位则跨版本脆弱。删除后键权完全归还宿主。

### 升级注意

- 自定义宿主若此前注入了 `searchFiles`，可直接移除注入；保留不报错，但不再有任何效果。Embed Protocol v1 其余接口不变。
- 旧版 DSH（`0.1.0-rc`）若无原生 `@` 提及，安装本版后将没有文件引用补全；如仍需该能力，请留在 0.2.1 或依赖宿主自身升级。

### 验证范围

- `npm run build && npm test` 102/102 通过，含新增负向回归：向 QuickEnhancer 传入 `searchFiles` 并写入 `@sr`，断言不出现补全菜单且草稿原样。
- ui/client.js、ui/client-lite.js、ui/embed.js 三份产物已重建，grep 确认无补全代码残留。
- 未做真机验证；按惯例待下次真机清单执行时一并确认原生菜单独占、无双重弹出。

<a id="v021"></a>
## 0.2.1：增强结果更可靠，升级安装更明确

状态：版本收口与本地验收，尚未执行推送、打标签或 npm 发布。

### 新增与改进

- 2026-08-31 复查修复：新版 `InputZone.session` 仅为会话状态，历史文本改从 `useChat` 的消息投影获取；测试不再使用含虚构消息节点的会话状态。
- 语义增强收到错误、取消、长度截断或缺失结束标记时拒绝返回成功结果，保留原草稿。
- alpha 烟测升级为实际打包安装、带 Cookie 的 HTTP 探测及正常退出验证；启动成功不等于浏览器交互或真实模型调用全部通过。

- 增加 `dsh-promptkit/browser` 浏览器入口，区分浏览器组件与 Node 插件注册逻辑。
- 诊断允许返回部分有效维度，并提供缺项/格式状态；界面不会把诊断协议标记当成草稿正文。
- 文件补全按当前会话工作区建立异步索引，缓存 5 秒，并限制扫描数量、深度和耗时。目录较大或不可读时明确提示结果不完整。
- 知识区区分检查通过与真实缺口，新记录使用完整草稿去重，避免长草稿前缀相同而误合并。内置方法仍为 21 个，本版未新增方法卡。

### 修复

- 取消、切换会话或继续编辑后，迟到的增强、模板和方法库改造结果不再覆盖新草稿。
- 只增强选区时保留前后文，预览与执行都使用选中片段；快捷键使用最新草稿、档位和选择的方法。
- 自动发送的增强失败可回退原文一次，发送回执失败不再触发第二次发送；其他输入框的 Enter 不会被误拦截。
- 技能引用在应用结果时自动补回，提示仅供确认，关闭提示不会再次改写草稿。
- “成功增强三次自动展开”不再依赖默认关闭的详细统计；失败与取消不推进进度。
- 修复 React 列表警告、窄屏边距，以及灵感库被宿主顶栏遮挡的问题。

### 从 0.2.0 升级

1. 升级前可在灵感库导出 JSON 备份。保留同一浏览器来源与 `storagePrefix`，无需主动清空 localStorage；已有资产与旧诊断暂存记录保留。旧截断草稿无法恢复全文，因此不与新的完整草稿强行合并。
2. 当前版本尚未发布，可在本仓库执行下方命令安装本地包。npm 安装命令只获取已发布版本，不保证等于本记录版本。

   ```bash
   npm ci
   npm run build
   npm pack
   dsh plugin --profile web add ./dsh-promptkit-0.2.1.tgz
   ```

3. 安装后刷新浏览器。若宿主仍缓存旧 Node 模块，需要通过宿主重载或重启 DSH，使会话工作区解析等后端修复生效；只刷新页面不一定足够。
4. 自定义宿主若启用 `onSubmitDraft`，必须实现 `composer.isInputTarget(target)`；`TextareaComposer` 已实现。需要选区预览实时更新时，实现 `onSelectionChange(callback)`。
5. 自定义流式 adapter 仅在确实不支持流式时抛出 `fallback=true`；已输出、超时或模型错误不应标记为可降级。文件路由请求须带 `session_id`，不能再依赖启动目录兜底。（2026-08-31 更正：该文件路由及 `searchFiles` 参数已随 `@` 补全一并移除，见[未发布](#unreleased)；此条仅对 0.2.1 及更早版本有效。）

### 验证范围

- 自动化回归覆盖源码、构建产物、真实本地 HTTP、流结束协议与异常交互；HTTP 测试使用模型桩，不调用外部模型。
- 安装消费验证覆盖 Node 18.20.8 / 26.7.0 与 React 17.0.2 / 19.2.8 的四种组合。Node 24.15.0 用于锁文件安装、构建和测试，产物可复现。
- DSH `0.1.2-alpha.2` 已完成空 profile 安装本地 bundle 后的 Web 启动验证；CI 在 alpha 通道执行同一烟测。旧 `0.1.0-rc` 只有模拟槽位契约覆盖，不宣称所有旧版已完成真机验证。
- 源码开发与测试建议 Node 24.15+；DSH 插件运行包要求 Node `>=22.6`，上述 Node 18 安装记录属于提高下限前的历史验证，不能用于声明当前支持范围。

<a id="v020"></a>
## 0.2.0：从快捷改写扩展到诊断与知识闭环

### 新增功能

- 五维诊断与方法感知检查，诊断发现可暂存知识区，由用户选择存为待验证假设卡或忽略。
- SSE 流式增强、取消、低/中/高强度，以及按所选对话、项目记忆、思考卡辅助改写。
- `@` 文件补全、`/pk` 灵感插入、模板变量、技能引用保留，以及自定义宿主可接入的发送前自动增强。
- 灵感库支持收藏、项目分组、派生对比、思考卡、关系视图和 JSON 备份；方法库扩展为 21 个方法。
- 极简/完整界面与多实例存储隔离，并适配 DSH `0.1.2-alpha` 输入槽位。

### 升级注意

增强本身只写回消息框，不直接发送。项目记忆、模型调用等可选能力需要宿主注入。此版本发送回退、文件检索作用域和首次体验计数的边界已在 0.2.1 修正，升级时应阅读上一节的 adapter 注意事项。

<a id="v010"></a>
## 0.1.0：初始工具包

### 新增功能

- 方法工坊用于填写问题、事实和约束，生成可编辑的 Prompt 预览。
- 快捷增强器提供本地轻量增强与可注入的语义增强能力。
- 初始 12 个 Markdown 思考方法，以及方法源、输入框、模型调用等可替换接口。
- Embed Protocol v1 将工具包封装为独立 `PromptKit` 命名空间，供 React/DSH 宿主组合使用。

历史日期与功能范围依据仓库已有 CHANGELOG 整理，不表示补建了对应 Git 标签或 npm 发布记录。

## 后续每次更新如何记录

每个版本在本文顶部新增一节，并更新索引表；不要覆盖旧版本历史。固定记录：版本和日期、状态、新增功能、改进/修复、从上一版升级的操作、数据与 adapter 兼容性、实际验证范围。没有新增功能时明确写“本版无新增功能”。

尚未完成的功能或验证不得写成已交付；本地提交、Git 标签、npm 发布是不同状态，发布完成后再更新状态。维护要求见 [贡献指南](../CONTRIBUTING.md#版本更新与升级记录)。