dsh-better-tips 0.0.0-stage → 0.12.1

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+本文件记录 dsh-better-tips 的显著变更。0.12.1 之前的条目是发布前内部迭代的摘要。
+
+## [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,156 @@
-# 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.
+Concise error summaries with per-retry original messages, on-demand network evidence, exact log coordinates and bounded retries — a plugin for DeepSeek Harness (DSH).
+
+当前版本 **0.12.1** · MIT License · 仓库 <https://github.com/HakureiMonika/dsh-better-tips>
+
+## 简介
+
+dsh-better-tips 在 DSH 会话的错误行、重试行和上下文压缩失败行上：
+
+- 显示有界的错误摘要和一句排查方向，完整原文按记录折叠保留；
+- 按需展开失败请求在网络边界捕获的底层证据（cause 链、非 2xx 状态 / 响应头 / 响应体）；
+- 在官方重试预算之外提供有界的额外重试（普通请求与压缩请求各有独立预算）；
+- 一键复制可直接发给供应商或 AI 的纯文本排障报告；
+- 从错误精确定位会话日志中的原始事件。
+
+默认只展示重点：所有详情折叠，展开前不发起任何诊断请求。
+
+## 安装
+
+**要求**
+
+- 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**），输入本仓库地址：
+
+```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 码点，省略处明确标注）和一句排查方向；完整非敏感原文保存在展开区，复制始终取得完整原文。
+
+```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 状态及原生错误类别；无证据时只使用事件已有信号。
+
+## DSH 原生报错与插件底层证据的区别
+
+| | DSH 原生报错 | 插件底层证据 |
+| --- | --- | --- |
+| 来源 | 会话日志中的持久事件（`llm/retry`、`turn/end`、压缩事件等），逐字读取 | Host 进程内对失败 fetch 请求的捕获（undici cause 链、非 2xx 状态 / 响应头 / 响应体） |
+| 性质 | 会话持久记录（可能含插件追加的重试事件），展示与复制的基准 | 补充层，按请求身份或时间关联到失败记录 |
+| 生存期 | 随会话持久保存 | 仅在 Host 进程内存，重启或重载后不可恢复 |
+| 边界 | 适配层已把 cause 链展平进 message | 抓不到的错误码不推断、不生成 |
+
+- 请求身份严格匹配时证据可用；仅按时间邻近选中的候选明确标注「关联未确认」，只出现在所属详情内，不替代 DSH 原生排查建议。
+- 底层捕获已关闭或不可用时，界面与报告如实标注「已关闭 / 不可用」，不误称读取失败（0.12.1 修复）。
+- 没有内存捕获不代表没有发生错误。
+
+## 复制排查报告
+
+错误简报旁的**复制排障报告**无需先展开；点击后生成纯文本并复制到剪贴板，不会自动发送给任何第三方：
+
+```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
+
+请协助排查；以上是已保留的错误证据，并非已确认根因。
+```
+
+- 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 次」只是本插件自身的预算；同时启用其他重试类插件可能叠加，请另行核对总预算。
+- **压缩失败展示**：原生失败原文与摘要请求尝试分区，每次尝试绑定各自的网络证据；压缩事件与摘要记录按时间关联，界面保留「关联未确认」，不把对应建议当成确定根因。
+
+## 配置
+
+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