dsh-better-tips 0.12.1 → 0.13.0

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 本文件记录 dsh-better-tips 的显著变更。0.12.1 之前的条目是发布前内部迭代的摘要。
 
+## [0.13.0] - 2026-11-14
+
+### 新增与调整
+
+- 错误卡默认展示截获错误的短预览；「底层原始详情」与「DSH 原生报错」纵向同级展开，保留完整原文与独立复制入口。
+- 重试状态下直接展示底层报错及对应排查建议，移除重复记录标题和建议；无论报错是否连续，都只默认展示最后一条，更早报错在原位置折叠保留。
+- 每次复制排障报告重新读取已启用第三方插件名称与版本；排除 DSH 自带及官方插件，清单读取不全或不可用时明确标注，仅 owner 可访问环境接口。
+
+### 修复
+
+- 摘要请求在抛出异常前即建立请求身份，保留可关联的网络证据；摘要请求达到 token 上限不再被记为成功。
+- 手动压缩失败按命令及压缩事务读取持久化记录；仅恢复可识别的本地验证错误，未知自由文本不自动恢复，避免丢失 AUTH 类型后的凭据回显。
+- 保护包装异常及 AggregateError 中的 AUTH 原因；取消、会话切换和晚到响应不会覆盖新记录。
+- 自动压缩持久化错误同样应用安全恢复规则；未知正文在默认展示、报告及日志显示副本中隐藏，源事件不变。
+- 最终摘要尝试为 token 上限或不完整终态时，不再回捞前次失败充当当前错误；保留最终 finish 状态及折叠历史。
+- 修复原生插件经 bundle / preset 合并重新进入第三方清单，以及结构性、未激活条件条目导致的错误缺失标记。
+
+### 验证与边界
+
+- 221 项自动化测试通过；语法与发布内容检查通过。
+- 已通过本机模拟上游执行真实 `/compact`，确认 HTTP 400 原因及原生命令失败持久化；不将 SDK 进程证据视为桌面进程截获证据，也不宣称已完成生产聊天界面验收。
+- 重试预算、默认配置和声明的兼容范围不变；凭据过滤只覆盖常见形状，分享报告前仍需人工检查。
+
 ## [0.12.1] - 2026-11-13
 
 ### 修复

package/README.md

@@ -1,156 +1,88 @@
 # dsh-better-tips
 
-Concise error summaries with per-retry original messages, on-demand network evidence, exact log coordinates and bounded retries — a plugin for DeepSeek Harness (DSH).
+> 优雅的 DSH 错误诊断插件：提供深层报错解析、按需网络证据捕获、一键故障排查报告以及更智能的重试机制。
 
-当前版本 **0.12.1** · MIT License · 仓库 <https://github.com/HakureiMonika/dsh-better-tips>
+当前版本 **0.13.0**。npm 安装标识：`dsh-better-tips@0.13.0`。
 
-## 简介
+---
 
-dsh-better-tips 在 DSH 会话的错误行、重试行和上下文压缩失败行上：
+## 核心功能
 
-- 显示有界的错误摘要和一句排查方向，完整原文按记录折叠保留；
-- 按需展开失败请求在网络边界捕获的底层证据（cause 链、非 2xx 状态 / 响应头 / 响应体）；
-- 在官方重试预算之外提供有界的额外重试（普通请求与压缩请求各有独立预算）；
-- 一键复制可直接发给供应商或 AI 的纯文本排障报告；
-- 从错误精确定位会话日志中的原始事件。
+| 功能 | 说明 |
+| :--- | :--- |
+| **深层报错** | 在错误行显式展示 Host 捕获的底层错误摘要与建议。 |
+| **网络证据** | 按需展开失败请求的原始证据（Cause 链、状态码、响应体）。 |
+| **智能重试** | 针对普通请求与压缩请求提供独立的有界额外重试预算。 |
+| **一键报告** | 快速生成纯文本排障报告，便于发送给供应商或 AI 分析。 |
+| **精确定位** | 从错误界面直接跳转至会话日志中的精确事件位置。 |
 
-默认只展示重点：所有详情折叠，展开前不发起任何诊断请求。
+---
 
-## 安装
+## 安装指南
 
-**要求**
+### 兼容性要求
+- **DSH**: `>=0.2.2-rc.2 <0.3.0`
+- **Node.js**: `>=24.9.0`
 
-- DSH `>=0.2.2-rc.2 <0.3.0`（`engines.dsh`；安装时会检查兼容性，不满足会被拒绝）
-- Node.js `>=24.9.0`（桌面版使用 DSH 自带运行时）
+### 安装方式
 
-**方式一：图形界面**。打开 DSH 侧栏 **Plugins** 页，点击 **Add plugin**（或其下拉菜单中的 **Install a third-party plugin**），输入本仓库地址：
+| 方式 | 命令/操作 |
+| :--- | :--- |
+| **图形界面** | 打开 **Plugins** 页 -> **Add plugin** -> 输入仓库地址 |
+| **命令行** | `dsh plugin add https://github.com/HakureiMonika/dsh-better-tips` |
+| **开发环境** | 输入该插件的绝对本地路径 |
 
-```text
-https://github.com/HakureiMonika/dsh-better-tips
-```
-
-对话框内可选择注册表（npm 官方源或 npmmirror 等镜像）。npm 安装标识：`dsh-better-tips`；指定版本：`dsh-better-tips@0.12.1`。
-
-**方式二：命令行**。`dsh plugin add <上述仓库地址或 dsh-better-tips@0.12.1>`。
-
-**方式三：本地目录**。**Add plugin** 也接受绝对本地路径，适合开发验证。
-
-安装后默认启用。界面未变化时刷新 DSH 页面；若提示需要重启，重启 DSH。关闭 `better-tips` 行只停用 Host 捕获与重试；停用整个 bundle 才恢复官方原生展示。
+---
 
-## 使用
+## 功能机制概览
 
-失败后，错误行默认显示有界摘要（首行最多 120 个 Unicode 码点，省略处明确标注）和一句排查方向；完整非敏感原文保存在展开区，复制始终取得完整原文。
+### 1. 错误显示
+当失败发生时，本插件会挂载一层补充诊断：
+- **插件捕获的底层报错**：优先显示短预览；「底层原始详情」保留完整证据，支持单独复制。
+- **DSH 原生报错**：与底层原始详情纵向同级折叠；无可用截获证据时保留原生提示，不冒充已捕获具体原因。
+- **错误收纳**：重试状态下紧接底层报错与对应排查建议；无论报错是否连续，都只默认展示最后一条，更早报错在原位置折叠保留，展开后可逐条查看。
 
-```text
-已重试 3/3 · 计划等待 500 ms
-类别概览 · SERVER / HTTP 503 · TRANSPORT · TRANSPORT
-排查：本组包含不同错误；展开后按每条记录分别排查。
-› 错误详情 · 重试记录 3 · 3 类错误
-  › 失败记录 2 · 已重试 2/3 · [TRANSPORT] Connection error.
-      原始报错 → 复制完整错误 → 本条排查 → 网络诊断 → 打开日志
-
-失败
-[SERVER] HTTP 503 上游暂时不可用。
-摘要 · 完整原文见详情
-排查：凭 request-id 核对服务端日志，稍后重试。
-› 错误详情 · 原始报错 → 网络诊断 → 日志定位
-```
-
-- **重试按记录分开**：保持发生顺序、每条的 seq 和各自原文 / 网络证据；不按 code/message 去重；混合错误链只作「类别概览」，不伪装成完整时间线或确认根因。
-- **按需读取**：错误 / 重试 / 压缩行全部收起且未点击复制报告时，不请求任何诊断 API；展开外层后才读取补充诊断；「重新读取」显式刷新，10 秒超时，无自动轮询。
-- **日志定位**：从错误详情打开内联的原始事件查看区，按精确 seq 高亮目标事件，并显示日志文件路径等只读元数据；无精确坐标时入口禁用，不用近似时间或文本相似度替代。个别已核验的报错可显示「源码匹配（非调用堆栈）」的生成函数位置，未知来源不伪造。
-- **排查建议**覆盖 DNS、连接、超时、TLS、HTTP 状态及原生错误类别；无证据时只使用事件已有信号。
+### 2. 重试逻辑
+- **独立预算**：普通请求与压缩摘要请求分别拥有独立的重试预算。
+- **智能策略**：基于指数退避加抖动，尊重 `Retry-After`，且永远避开硬拒绝代码（如 `AUTH`、`QUOTA` 等）。
+- **预算与费用**：普通请求每步、压缩摘要每次默认各额外重试 2 次；重试会产生真实请求费用，与其他重试插件同时启用可能叠加。相应预算设为 `0` 可关闭额外重试，不影响展示。
+- **读取时机**：失败行挂载后读取一次补充证据，以显示截获错误；无自动轮询。原始日志按点击读取，第三方插件清单在每次复制报告时重新读取。
 
-## DSH 原生报错与插件底层证据的区别
+### 3. 安全与隐私
+- **有界内存证据**：插件新增的网络证据保留在 Host 有界内存中，进程结束后不可恢复；DSH 原生日志另有持久化机制，复制或导出的报告也可能被保存。
+- **常见凭据过滤**：自动过滤常见 API 凭据形状，但不保证清除任意秘密或个人信息；报错与响应可能回显输入，分享前仍需人工检查。
+- **采集边界**：只保留符合条件的失败请求证据，不更改上游请求内容；HTTP 200 内的协议错误、正常 EOF 等不一定产生网络捕获。
 
-| | DSH 原生报错 | 插件底层证据 |
-| --- | --- | --- |
-| 来源 | 会话日志中的持久事件（`llm/retry`、`turn/end`、压缩事件等），逐字读取 | Host 进程内对失败 fetch 请求的捕获（undici cause 链、非 2xx 状态 / 响应头 / 响应体） |
-| 性质 | 会话持久记录（可能含插件追加的重试事件），展示与复制的基准 | 补充层，按请求身份或时间关联到失败记录 |
-| 生存期 | 随会话持久保存 | 仅在 Host 进程内存，重启或重载后不可恢复 |
-| 边界 | 适配层已把 cause 链展平进 message | 抓不到的错误码不推断、不生成 |
-
-- 请求身份严格匹配时证据可用；仅按时间邻近选中的候选明确标注「关联未确认」，只出现在所属详情内，不替代 DSH 原生排查建议。
-- 底层捕获已关闭或不可用时，界面与报告如实标注「已关闭 / 不可用」，不误称读取失败（0.12.1 修复）。
-- 没有内存捕获不代表没有发生错误。
+---
 
 ## 复制排查报告
 
-错误简报旁的**复制排障报告**无需先展开；点击后生成纯文本并复制到剪贴板，不会自动发送给任何第三方：
+点击错误旁的“一键复制排障报告”，即可生成纯文本报告。报告会在每次点击时重新读取**已启用的第三方插件名称和版本**；DSH 自带及官方插件不列入，DSH 版本单独保留。仅导出名称和版本，不含配置、凭据、安装路径或来源地址；清单缺失或不完整会明确标注。
 
 ```text
-记录于2026/11/13 19:20:03 (Asia/Shanghai)：使用“deepseek”渠道的“deepseek-chat”模型时遇到[SERVER] HTTP 503 上游暂时不可用。
-截止生成本报告时: DSH 0.2.2-rc.2 · Better Tips 0.12.1
-
-DSH 原生报错: [SERVER] HTTP 503 …（最多 600 个 Unicode 码点）
-插件捕获的底层报错: HTTP 503 Service Unavailable
-request-id: …
-API: api.example.com/v1/chat/completions
-响应摘要: Service temporarily unavailable …（最多 300 个 Unicode 码点）
-请求耗时 4 ms；计划等待（非实测） 500 ms；重试记录 1/2
-
-请协助排查；以上是已保留的错误证据，并非已确认根因。
+记录于 2026/11/13 19:20:03：[SERVER] HTTP 503 ...
+DSH 原生报错: ...
+插件捕获的底层报错: ...
+request-id: ...
+API: api.example.com/...
+...
 ```
+*(报告内容仅存在于你的剪贴板，不会自动上传到任何第三方平台)*
 
-- DSH 原生报错与插件捕获的底层报错分行标注；超长节明确标注省略，完整原文仍可在界面查看并单独复制。
-- 缺少捕获、版本读取失败或诊断关闭 / 不可用时，仍可复制原生部分并明确缺项；复制失败会在原位置展开可选中的报告文本。
-- 时间使用本地时区并附 IANA 区名；「计划等待」不冒充实测耗时。
-- 错误原文与响应体可能回显你的输入内容；仅过滤常见凭据形状，分享前请自行检查。
-
-## 重试和压缩失败
-
-展示与重试相互独立：把重试次数设为 0 不影响展示，停用 bundle 后两者一起恢复官方行为。
-
-- **普通请求**：只接手官方执行器放弃的失败，默认每步额外 2 次。
-- **压缩（compaction）摘要请求**：独立预算，默认额外 2 次；每次尝试通过新的 `llm.stream` 完整分发，不拼接部分摘要文本；取消信号合并，卸载等待在途任务结束。
-- **硬拒绝码从不重试**：`AUTH`、`QUOTA`、`CONTEXT_WINDOW_EXCEEDED`、`INVALID_MODEL`、`ABORTED` 等（完整列表见 [lib/policy.js](lib/policy.js)）；默认白名单为 `PI_AI_ERROR / TRANSPORT / TIMEOUT / SERVER / EMPTY_RESPONSE / RATE_LIMIT`。
-- **退避**：有上限的指数曲线加对称抖动，尊重提供方 Retry-After（受上限约束）；官方已执行过退避时接续其曲线而不是重新开始。
-- **费用**：重试产生真实请求费用。「额外 2 次」只是本插件自身的预算；同时启用其他重试类插件可能叠加，请另行核对总预算。
-- **压缩失败展示**：原生失败原文与摘要请求尝试分区，每次尝试绑定各自的网络证据；压缩事件与摘要记录按时间关联，界面保留「关联未确认」，不把对应建议当成确定根因。
+---
 
 ## 配置
+支持通过 `cordis.patch.yml` 进行灵活配置：
+- `extraRetries` / `compactionRetries`: 自定义重试预算。
+- `captureHosts`: 自定义捕获白名单。
 
-bundle 的 [cordis.patch.yml](cordis.patch.yml) 中 `better-tips` 行的 `config`：
-
-| 键 | 默认 | 含义 |
-| --- | --- | --- |
-| `enabled` | `true` | Host 捕获与重试总开关；Client 展示独立 |
-| `extraRetries` | `2` | 每步额外重试次数，`0` 表示不介入 |
-| `compactionRetries` | `2` | 每个压缩摘要请求的额外重试次数 |
-| `initialDelayMs` | `1000` | 起步等待 |
-| `maxDelayMs` | `20000` | 单次等待上限 |
-| `jitterRatio` | `0.2` | 抖动比例 |
-| `retryableCodes` | 见上 | 愿意重试的错误码白名单；硬拒绝集合优先 |
-| `captureDetails` | `true` | 启用底层捕获 |
-| `captureWindowMs` | `10000` | 旧配置兼容项；请求身份关联不再使用时间回退 |
-| `captureHosts` | `[]` | 捕获主机白名单；空数组不限制 |
-
-非法取值回退到文档默认值，不会静默变成 0。
-
-## 安全限制
+---
 
-- 只捕获失败请求（抛出的错误或非 2xx 响应）；绝不记录请求体、请求头、`Authorization`、查询字符串、Cookie 和成功响应的正文。
-- 响应只保留状态码、诊断头白名单（`request-id`、`retry-after`、`cf-ray` 等）和至多 4096 字符的正文；截断、读取中、不可读等状态明确标注。
-- `AUTH` 错误正文始终隐藏；常见凭据形状（Bearer / `sk-` / api key 等）会脱敏。这是常见凭据过滤，**不是**任意秘密或个人信息的完整清洗；展开的诊断应视为敏感数据。
-- 捕获仅存于 Host 进程内存且有界（失败请求环形记录 100 条、每步证据 8 条、每会话压缩记录 12 条）；重启或重载 Host 后不可恢复。
-- 不修改任何已持久化的会话事件；日志元数据接口仅限已认证 owner，不接受浏览器传入的文件路径或报错文本。
-- 复制与报告生成都是手动操作，无自动上传、无后台采集提示词或完整会话。
-
-## 兼容版本
-
-- DSH `>=0.2.2-rc.2 <0.3.0`（`engines.dsh`，安装时检查）；Node.js `>=24.9.0`。
-- 实际集成验证基于 **DSH 0.2.2-rc.2**（隔离环境与真实页面验证）；不保证该范围内未来版本的全部私有契约不变。
-- Client 侧使用 `conversation.chat.node` 的 5 个 keyed renderers（优先级 -100），保留原生优先级 0；停用 bundle 后恢复官方展示。不修改核心包、不注入提示词、不重写既有会话事件。
-
-## 开发与测试
+## 开发与贡献
 
 ```sh
 npm run check   # 语法检查
 npm test        # 自动化测试
 ```
 
-0.12.1 的 185 项自动化测试全部通过。自动化测试通过不代表插件已在你的生产环境中加载；请在 **Plugins** 页面确认安装与启用状态，并实际触发一次错误来验证展示。
-
-## License
-
-MIT
+MIT License · [问题反馈](https://github.com/HakureiMonika/dsh-better-tips/issues)