dsh-better-tips 0.0.0-stage → 0.13.0

package/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+本文件记录 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
+
+### 修复
+
+- 复制排障报告与详情面板区分「底层诊断已关闭 / 不可用」与真实的详情读取失败，不再把 capture 关闭或不可用误称为读取失败。
+- 多条失败记录同码同文、只能按时间邻近选中证据时，界面与报告都明确标注「关联未确认」，且不使用该捕获替代 DSH 原生排查建议。
+
+### 说明
+
+- 重试策略、默认配置与兼容范围不变，无新增配置项。
+- 185 项自动化测试全部通过（以 `npm test` 实际输出为准）。
+
+## [0.12.0] - 2026-11-13
+
+- 声明兼容范围：Node `>=24.9.0`、DSH `>=0.2.2-rc.2 <0.3.0`。
+- 每步内存证据上限由 6 增至 8，覆盖官方重试后的终态，仍为有界内存，不增加请求预算。
+- HTTP 状态只从明确的 400–599 格式推导，结构化 status 优先，不把正文中的任意三位数字当作状态码。
+- 重试延迟文案明确为「计划等待」；压缩 usage 明确为摘要请求用量。
+- 保留 `captureWindowMs` 兼容项；请求身份关联不再使用时间回退。
+
+## [0.11.0] - 2026-11-13
+
+- 渐进披露：默认零诊断请求，展开后才读取，完成结果缓存复用。
+- 混合错误链（A-B-A）不去重，每条失败记录独立展示、展开与日志定位。
+- 取消、晚到响应与会话身份隔离的回归覆盖。
+
+## [0.10.0] - 2026-11-13
+
+- 首个在隔离 DSH 环境中完整验证的版本：错误 / 重试 / 压缩失败展示、复制排障报告、日志精确定位、AUTH 与常见凭据保护、有界额外重试。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HakureiMonika
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,88 @@
-# Temporary Holding Version
+# dsh-better-tips
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> 优雅的 DSH 错误诊断插件：提供深层报错解析、按需网络证据捕获、一键故障排查报告以及更智能的重试机制。
+
+当前版本 **0.13.0**。npm 安装标识：`dsh-better-tips@0.13.0`。
+
+---
+
+## 核心功能
+
+| 功能 | 说明 |
+| :--- | :--- |
+| **深层报错** | 在错误行显式展示 Host 捕获的底层错误摘要与建议。 |
+| **网络证据** | 按需展开失败请求的原始证据（Cause 链、状态码、响应体）。 |
+| **智能重试** | 针对普通请求与压缩请求提供独立的有界额外重试预算。 |
+| **一键报告** | 快速生成纯文本排障报告，便于发送给供应商或 AI 分析。 |
+| **精确定位** | 从错误界面直接跳转至会话日志中的精确事件位置。 |
+
+---
+
+## 安装指南
+
+### 兼容性要求
+- **DSH**: `>=0.2.2-rc.2 <0.3.0`
+- **Node.js**: `>=24.9.0`
+
+### 安装方式
+
+| 方式 | 命令/操作 |
+| :--- | :--- |
+| **图形界面** | 打开 **Plugins** 页 -> **Add plugin** -> 输入仓库地址 |
+| **命令行** | `dsh plugin add https://github.com/HakureiMonika/dsh-better-tips` |
+| **开发环境** | 输入该插件的绝对本地路径 |
+
+---
+
+## 功能机制概览
+
+### 1. 错误显示
+当失败发生时，本插件会挂载一层补充诊断：
+- **插件捕获的底层报错**：优先显示短预览；「底层原始详情」保留完整证据，支持单独复制。
+- **DSH 原生报错**：与底层原始详情纵向同级折叠；无可用截获证据时保留原生提示，不冒充已捕获具体原因。
+- **错误收纳**：重试状态下紧接底层报错与对应排查建议；无论报错是否连续，都只默认展示最后一条，更早报错在原位置折叠保留，展开后可逐条查看。
+
+### 2. 重试逻辑
+- **独立预算**：普通请求与压缩摘要请求分别拥有独立的重试预算。
+- **智能策略**：基于指数退避加抖动，尊重 `Retry-After`，且永远避开硬拒绝代码（如 `AUTH`、`QUOTA` 等）。
+- **预算与费用**：普通请求每步、压缩摘要每次默认各额外重试 2 次；重试会产生真实请求费用，与其他重试插件同时启用可能叠加。相应预算设为 `0` 可关闭额外重试，不影响展示。
+- **读取时机**：失败行挂载后读取一次补充证据，以显示截获错误；无自动轮询。原始日志按点击读取，第三方插件清单在每次复制报告时重新读取。
+
+### 3. 安全与隐私
+- **有界内存证据**：插件新增的网络证据保留在 Host 有界内存中，进程结束后不可恢复；DSH 原生日志另有持久化机制，复制或导出的报告也可能被保存。
+- **常见凭据过滤**：自动过滤常见 API 凭据形状，但不保证清除任意秘密或个人信息；报错与响应可能回显输入，分享前仍需人工检查。
+- **采集边界**：只保留符合条件的失败请求证据，不更改上游请求内容；HTTP 200 内的协议错误、正常 EOF 等不一定产生网络捕获。
+
+---
+
+## 复制排查报告
+
+点击错误旁的“一键复制排障报告”，即可生成纯文本报告。报告会在每次点击时重新读取**已启用的第三方插件名称和版本**；DSH 自带及官方插件不列入，DSH 版本单独保留。仅导出名称和版本，不含配置、凭据、安装路径或来源地址；清单缺失或不完整会明确标注。
+
+```text
+记录于 2026/11/13 19:20:03：[SERVER] HTTP 503 ...
+DSH 原生报错: ...
+插件捕获的底层报错: ...
+request-id: ...
+API: api.example.com/...
+...
+```
+*(报告内容仅存在于你的剪贴板，不会自动上传到任何第三方平台)*
+
+---
+
+## 配置
+支持通过 `cordis.patch.yml` 进行灵活配置：
+- `extraRetries` / `compactionRetries`: 自定义重试预算。
+- `captureHosts`: 自定义捕获白名单。
+
+---
+
+## 开发与贡献
+
+```sh
+npm run check   # 语法检查
+npm test        # 自动化测试
+```
+
+MIT License · [问题反馈](https://github.com/HakureiMonika/dsh-better-tips/issues)