# @feng0531/dsh-code-report 中文文档

规范地址：https://npmcn.com/package/%40feng0531/dsh-code-report/

版本：1\.1\.1
npm 元数据更新时间：2026-11-10T12:39:21.001Z
中文译文更新时间：2026-11-14T14:18:49.476Z
软件包许可：SEE LICENSE IN LICENSE

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40feng0531/dsh-code-report
原文对照：https://npmcn.com/package/%40feng0531/dsh-code-report/?lang=original
项目主页：https://github.com/f-e-n-g-0531/dsh-code-report#readme
源码仓库：https://github.com/f-e-n-g-0531/dsh-code-report

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：394 kB，38 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22
- 运行依赖：1 个
- 首次发布：2026-10-15T06:14:47.845Z
- 最新版本发布：2026-11-10T12:39:20.761Z
- 近 30 天下载量：6758（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：50（近 12 个月 50 个）

## 中文简介

比较多个 Git/SVN 项目的版本差异，生成改动、接口影响与 QA 测试范围报告。

## 安装

```sh
npm install @feng0531/dsh-code-report
```

也可以使用：`pnpm add @feng0531/dsh-code-report`、`yarn add @feng0531/dsh-code-report`、`bun add @feng0531/dsh-code-report`

## README

# DSH Code Report · 多项目发布报告

比较多个 Git / SVN 项目的两个版本，导出中文 Markdown 报告。可以只导出本地差异证据，也可以在确认发送后，让 DSH 中配置的模型整理改动、对外接口变更、影响范围和 QA 测试建议。

**这是 DeepSeek Harness（DSH）的插件，不是独立应用。** 模型建议需要人工复核，不代表测试通过或发布批准。

## 适合什么场景

-   **多项目一起发版**：一次选择最多 12 个项目，统一核对 Git / SVN 的 A/B 固定版本与变更路径。
-   **给研发和 QA 整理交接材料**：让模型基于已发送的差异证据，整理改动、对外接口、影响范围与测试建议；不能确认的内容保留为待确认。
-   **先核对证据，再决定是否使用 AI**：采集和下载证据不调用模型；确认发送范围后才生成分析，可能产生模型费用。

### 能得到什么

| 产出 | 用途 |
| --- | --- |
| 本地证据清单 | 核对比较端点、文件清单、来源与哈希；未调用模型，不是发布结论 |
| 插件内模型报告 | 阅读分析正文，并展开技术附录核对已发送证据及覆盖限制 |
| 下载的正式 Markdown | 仅保留“本次比较范围、改动内容、对外接口变更、影响范围、QA 测试范围”五节，便于交接；不包含证据附录，不是完整差异归档 |

**使用前先判断边界**：它比较已提交／已保存的两个版本，不包含未提交变化；AI 默认只分析预算内摘要和有限片段，不是全仓代码审查、完整调用图或自动化测试。报告与证据需及时下载，不能依赖内存缓存归档。

**许可提醒**：个人非商业学习、教学或研究可按许可证条件使用；公司内部商业项目的开发、测试、维护等商业用途需先取得书面授权，不能因源码公开或包可下载就视为免费商用。详见[许可证](https://github.com/f-e-n-g-0531/dsh-code-report/blob/main/LICENSE)。

[安装与准备](https://npmcn.com/package/%40feng0531/dsh-code-report/#readme-%E5%AE%89%E8%A3%85%E4%B8%8E%E5%87%86%E5%A4%87) · [快速上手](https://npmcn.com/package/%40feng0531/dsh-code-report/#readme-%E5%BF%AB%E9%80%9F%E4%B8%8A%E6%89%8B) · [完整使用说明](https://npmcn.com/package/%40feng0531/dsh-code-report/#readme-%E5%AE%8C%E6%95%B4%E4%BD%BF%E7%94%A8%E8%AF%B4%E6%98%8E) · [故障排查](https://npmcn.com/package/%40feng0531/dsh-code-report/#readme-%E6%95%85%E9%9A%9C%E6%8E%92%E6%9F%A5) · [开发、发布与许可](https://npmcn.com/package/%40feng0531/dsh-code-report/#readme-%E5%BC%80%E5%8F%91%E5%8F%91%E5%B8%83%E4%B8%8E%E8%AE%B8%E5%8F%AF)

> 本文对应 v1.1.1。版本变化见[发布说明](https://github.com/f-e-n-g-0531/dsh-code-report/blob/main/RELEASE-NOTES.md)；发布不自动安装或重启当前 DSH。

## 安装与准备

-   使用可运行的 DSH；插件要求 Node.js 22 或更新的运行时。桌面版是否另需安装 Node.js，以宿主安装方式为准。
-   运行 DSH 的环境需能调用 Git；使用 SVN 项目还需能调用 svn。普通使用不需要 svnadmin。
-   AI 分析需要提前在 DSH 配置模型服务。插件不提供模型服务，也不要求在本页面填写 API Key。

优先使用 DSH 自带的“插件”页面安装 npm 包，填写以下包名与版本：

```text
@feng0531/dsh-code-report@1.1.1
```

也可使用已配置好的 DSH 命令行。确认当前 profile 名称后再执行；profile 是插件安装环境，不是会话名或工作区路径。例如，只有确认使用 desktop 环境时才运行：

```sh
dsh plugin --profile desktop add @feng0531/dsh-code-report@1.1.1
```

安装会修改对应环境，先备份配置。命令行安装还需满足 DSH 自身的包管理器要求。安装后保存工作，手动完全退出并重新启动 DSH，再刷新原页面。**只刷新页面不会重载旧后台。** 发布新版本不会自动升级或重启你的环境。

[GitHub 正式发布页](https://github.com/f-e-n-g-0531/dsh-code-report/releases)提供安装包和校验文件；下载 tgz 本身不等于已安装。普通用户无需下载源码或自行构建。

## 快速上手

1.  **打开工作区**：在带工作目录的 DSH 会话中打开侧栏“发布报告”。待后台验证和自动发现完成；项目需位于会话工作目录内，嵌套项目可手动添加。
2.  **填写比较范围**：勾选项目并展开卡片，填写 A 基线与 B 目标。Git 默认使用远端 `origin`，会联网；需要离线时先切换“本地离线”。可填写该来源中已有的两个标签或 SHA；版本留空则必须填写对应分支。SVN 两侧填写仓库分支路径，并勾选历史读取授权。
3.  **先采集，不发模型**：点击“开始执行 · 采集差异”，核对固定端点、变更路径、源码来源和限制。只需证据时，到这里即可下载证据清单，不必生成 AI 报告。
4.  **按需生成分析**：核对 DSH 默认模型或指定已配置的模型，检查预算内发送范围和敏感内容，勾选本次发送授权，再点击“开始执行 · 生成报告”。默认单次摘要不等于全部差异全文分析；预览创建满 10 分钟后需重新采集。
5.  **人工复核并下载**：检查改动、接口影响和 QA 建议，必要时展开附录核对证据，再点“下载 .md 文件”。正式下载不含技术附录；刷新、更新或重启前先保存所需结果。

例如：Git 远端名为 `origin`，A 分支 `main`、B 分支 `develop`，两侧版本留空，即比较采集时远端两个分支的最新提交。若是同一分支发版，请指定不同标签／SHA；同一分支两侧版本都留空不会自动比较上一版。

## 完整使用说明

展开配置、源码、发送确认与导出的详细规则

## 从配置到报告

### 1\. 打开“发布报告”

打开带工作目录的 DSH 会话，点击侧栏“发布报告”。页面以发布工作台呈现“配置发布范围 → 核对差异证据 → 生成与导出”流程条；项目卡片将 A · 比较基线与 B · 发布目标分开标注，帮助说明可折叠。深浅主题与窄屏采用对应布局，实际可读性和操作范围以验收记录为准。流程条是状态提示，不代替采集或模型发送确认。多个项目应位于会话工作目录内；项目位于目录外时不能直接读取。

页面先验证后台身份、版本及协议，一致后自动发现一次：**仅检查工作区根目录及一级子文件夹，不递归进入项目内部。** 点前缀隐藏、常见缓存及链接目录跳过（不按 Windows Hidden 属性筛选）。嵌套项目可手动添加。

自动发现不获取远端 Git 分支，也不扫描源码调用关系。失败后可点击“扫描 / 重新发现”重试；重新验证或更新失败解锁不会自动重扫。扫描保留已填写的项目与版本、现有预览和报告，新发现项目默认不选中。

### 2\. 勾选项目，填写 A/B 分支，版本可留空

项目卡片默认各自折叠，摘要栏仍显示路径、Git/SVN 类型、选择状态及错误标记。点击对应项目的展开按钮，或聚焦后按 Enter／Space，查看和编辑配置；勾选项目不会自动展开。折叠不清空路径、远端、A/B 或版本值，搜索及批量填版本仍按原规则执行。“定位首个错误项目”会清除显示筛选、展开该项并聚焦配置输入。忙碌时已有禁用限制仍保留；单纯展开／折叠不查询引用或调用模型。

| 输入 | 填写方式 |
| --- | --- |
| 项目路径 | 相对于会话工作目录；根目录填 "."，例如 client 或 server |
| Git 读取方式 / 远端名 | 默认“远端实时读取”，远端配置名默认 origin（不是 URL）；显式选“本地离线”才仅用本地对象 |
| SSH 私钥文件或目录（可选） | Git 远端模式专用，可直接填 `D:/keys/fork_ssh_key` 私钥文件，或 `D:/keys/.ssh` 目录；支持 `~` 和相对于源仓库根目录的路径，留空沿用现有认证设置 |
| Git 分支 A/B | 版本留空时必填；远端模式使用远端已有分支，如 main、develop 或 origin/develop，无需在本地创建对应分支 |
| Git 版本 A/B（可选） | 留空取所选来源中对应分支最新提交；显式版本优先，可填标签、SHA 或 HEAD~1 等历史表达式，所需对象须在该来源可读 |
| SVN 分支 A/B | 相对于 SVN 仓库根目录，例如 trunk、branches/release；"." 表示当前工作副本的仓库路径 |
| SVN r 版本 A/B（可选） | 留空取对应分支最新一次提交；指定历史版本支持 r1200 或 1200，不接受手填 HEAD、日期或版本范围 |

Git 默认可点击“读取远端分支/标签”，查询该配置远端当时的引用；采集时会重新获取，列表不保证与后续采集相同。选择“远端实时读取”即允许访问该配置远端，不另设网络勾选；查询和采集会联网，并可能需要现有的非交互认证。远端名填写 origin 等配置名称，不填写 URL、密码或令牌。认证沿用源仓库有效的 credential/http、core.sshCommand 与 ssh.variant 配置，以及明确设置的 GIT\_SSH\_COMMAND、GIT\_SSH、GIT\_SSH\_VARIANT；源仓库 local 认证设置也在范围内。仓库和用户已配置且信任的 credential helper / SSH 程序可能执行，插件不是 OS 沙箱。相对 -i 路径不会自动改写，仍相对临时目录解析；建议使用绝对路径或已配置的 SSH 身份，不要将密钥路径、私钥或令牌粘贴到报告字段。逐行错误会标出缺失内容，重复项目须先移除。

指定 SSH 私钥文件或目录后，本次远端查询和抓取使用 OpenSSH，覆盖现有 `core.sshCommand`、`GIT_SSH_COMMAND` / `GIT_SSH` 和 SSH variant，但不改写这些配置。文件模式通过 `-i` 指定该私钥并设置 `IdentitiesOnly=yes`，保留 OpenSSH 默认 `config` / `known_hosts`；不要填写 `.pub` 公钥。目录模式读取该目录的 `config`（若存在）、`known_hosts` 及存在的常见 `id_*` 私钥；自定义私钥可直接填文件路径，无需改名或复制，也可在 `config` 中用绝对 `IdentityFile` 路径指定。`~`、相对 IdentityFile / Include 等仍按 OpenSSH 自身规则解释，不自动相对新目录重定位。仅保存所填路径，不读取私钥内容到报告或发送给模型；SSH 配置属于受信任配置，可能启动 ProxyCommand 等程序。不会关闭主机指纹校验；未信任的主机需先在插件外核验，密码或私钥口令不会交互询问（可预先使用 ssh-agent）。本地离线和 SVN 不使用此设置。

Git 示例：远端名 origin，A 分支 main、B 分支 develop，两侧版本留空，比较远端这两个分支的最新提交。origin/develop、refs/remotes/origin/develop 会按所选远端归一化为远端分支；标签可填 refs/tags/v1.0.0，历史版本可填已抓取历史中的 SHA、HEAD~1。HEAD 指远端 HEAD，不替换为本地当前分支。

远端采集会在独立临时裸仓库完整抓取分支、标签及可达历史，再固定 A/B SHA 并读取差异与固定版本源码；不 checkout、pull 或 merge，不修改业务仓库的 objects、refs 或工作区，结束后清理临时目录。取消会停止本地自有传输进程树并清理临时目录；不保证远端服务器撤销请求。失败不会回退本地。完整历史可能消耗较多网络、临时磁盘和时间；没有固定规模上限不等于无限资源。远端 HEAD 在查询与抓取间变化可能使采集失败，应重新采集。观察时间是抓取完成后的本次观察值，不是跨项目原子快照，也不会自动更新已有预览。

需要离线时显式选择“本地离线”，再点击“读取本地分支/标签”。本地模式只读已有引用和对象，不自动 fetch 或补取 partial clone 缺失对象；缺对象时直接失败，先在插件外补齐后重采。远端跟踪引用可能滞后服务器。

SVN 示例：A 分支 trunk、版本 r1200；B 分支 branches/release、版本 r1250。两侧必须属于同一仓库。即使使用本地 SVN 仓库，也要勾选历史读取授权；远程仓库可能产生网络访问。

一次最多选择 **12 个项目**。路径、分支和版本逐行核对后再采集。只留空一侧时，该侧使用对应分支最新提交；A/B 是同一分支且两侧版本均留空时没有差异，不会自动改成“上一版对最新版”。采集先解析并固定 Git SHA / SVN revision，报告展示固定端点；SVN 最新提交按分支历史解析，不是直接使用全仓最新 revision。

### 3\. 减少重复填写

-   搜索项目路径或勾选“仅看已选”，只改变显示，不取消隐藏项目的选择。
-   展开“批量填版本”，应用于**所有已勾选的同类型项目**，不受搜索筛选限制。默认只填空白；取消该选项才覆盖已有值。批量栏留空的字段保持原值。
-   点击“保存配置”，保存项目、选择状态、Git 读取方式与远端配置名、A/B 版本、标题、源码路径、提供方 ID 和模型 ID。下次同一浏览器、同一工作区打开时恢复。修改后需再次保存；“恢复已保存”会替换当前输入，使当前预览失效；旧报告保留并标为旧配置结果。

配置保存在浏览器本地存储，不写入项目、不跨浏览器同步。旧配置缺少 Git 读取方式或远端名时，恢复为 remote / origin；**升级后如需离线，务必先显式改为“本地离线”再查询或采集**。修改读取方式或远端名会清除引用列表、预览和发送确认，保留已填 A/B。清理浏览器数据可能丢失配置。保存时包含此工作区的 SVN 历史访问勾选状态，恢复后会明确提示，可能允许后续 SVN 采集联网。旧版配置未保存该字段时默认关闭。不保存密码、API Key、源码正文、预览、报告或模型发送确认；**不要在输入字段中粘贴凭据**。模型发送仍需每次确认。

### 4\. 按需附带源码文件或文件夹

展开“附带项目源码（可选）”，每行输入一个工作区内的文件或文件夹路径，例如：

```text
client/src/api.ts
client/src/components
client/CI/Env
```

支持直接填写目录，根目录可填 `.`。**目录源码筛选**：递归展开按扩展名或常见文件名白名单选取源码、脚本、文本配置及文档，例如 `.cpp`、`.h`、`.tcc`、`.def`、`.cs`、`.ets`、`.lua`、`.json`、`.md`、`.vcxproj`、Makefile；不是读取每一个普通文件。IDE 数据库（如 `.sdf`）、图片等资源、编译库及其他未支持格式在正文读取前按元数据排除，限制说明显示排除数量、扩展名统计及最多 5 个示例；这些文件不计为源码覆盖。未知文本格式可显式填写文件路径，但仍须通过严格二进制和编码校验；与目录输入重叠时只计入一次，显式选择优先，排除统计同步扣除。

只展开明确填写的路径，不自动附带其他项目或扫描调用链；路径可来自工作区内另一个项目。目录内点前缀隐藏、敏感、依赖、构建和缓存路径、链接及非普通文件仍会跳过，预览的限制说明列出排除计数；隐藏判断基于点前缀，不读取 Windows Hidden 属性。显式填写敏感路径仍拒绝，不因目录支持而允许凭据文件。

普通路径补充源码取自**当前磁盘内容**，不一定属于 A 或 B，报告会单独标记。需要历史契约时，在“固定版本源码”中每行填写 `仓库路径|A或B|仓库相对路径`，例如 `client|A|src/api.ts` 和 `client|B|src/api.ts`。仓库必须已经选中；固定版本源码仍仅支持文件，不支持目录。两侧分别读取本次固定的 Git 提交或 SVN revision，不存在、符号链接、解码后含 NUL 或无法按支持的编码解码时会失败，不会改读磁盘。工作区与固定版本源码的路径条目和实际文件数量不设固定规模上限。

源码按完整文件解码，工作区文件、目录展开文件和固定 A/B 源码使用同一规则。**源码编码兼容**：有明确 BOM 的 UTF-16LE／BE 先按对应编码严格解码，保留 BOM 和换行；非 BOM 文件仍先尝试 UTF-8、再 GB18030，二者失败后，仅对完全由 ASCII 与单字节 `0xA9` 组成且至少有一个 `0xA9` 的文件，将该字节解释为 ©。此窄回退标为 `windows-1252-copyright` 并展示 `encodingWarning`，说明编码归属存在歧义，**不代表支持通用 Windows-1252**。

没有 UTF-16 BOM 的 NUL 字节仍拒绝；BOM UTF-16 奇数字节、未配对代理项或解码后 NUL 字符仍拒绝。其他不符合支持条件的编码及读取失败使整次采集失败，不制造替换字符或静默截断；不修改源码、原始字节及其哈希。目录筛选不等于放宽正文校验：显式选择二进制 `.sdf` 仍失败，伪装为 `.cpp` 的二进制也会使整次失败。单文件大小、证据总量、源码目录展开的条目数、目录数和深度不设固定规模上限，仍受可用内存、操作系统与工具限制；大范围采集和报告展示可能明显增加耗时及内存。源码目录展开不同于项目自动发现，后者仍保持有限的浅层扫描范围。

Git/SVN 差异按原始 LF 字节边界逐行执行 UTF-8 优先、失败后 GB18030 的规则，兼容 UTF-8 路径头与 GBK 正文分别占行的差异。这不是完整编码检测器：同一行混合编码、同时可按 UTF-8 与 GBK 解码的歧义字节不保证识别；不会修复已有乱码或已存在的 U+FFFD，也不修改源文件。路径名单、SVN XML 等元数据仍严格要求 UTF-8。差异解码规则不变，不继承源码的 BOM UTF-16 或窄 © 回退。

常见敏感路径会被拦截，但这不是完整密钥扫描；发送前仍需检查密码、令牌与私人信息。

### 5\. 采集并检查证据

按钮不可用时，旁边会提示后台验证状态、正在进行的任务、超出 12 项、具体项目缺失的路径或 A/B 分支；包含 SVN 项目时还需勾选历史读取授权。窄窗口下 A/B 输入栏在项目下方纵向显示，无需横向寻找。

版本差异中的 `.git` / `.svn` 内部路径在读取正文前自动排除，并在报告列出路径及覆盖限制；不是先读取再删文本。其他敏感路径（如 `.env`、密钥文件）仍阻断整个采集并提示项目和路径。附带源码不允许指定内部路径。

点击“开始执行 · 采集差异”。这一步**不调用模型**；Git 默认远端模式和 SVN 历史读取可能访问仓库服务器。生成分析使用已固定的证据，不重新读取 Git 远端；模型发送仍需单独确认。

完成后检查项目、固定版本、变更路径数、目录展开后的实际源码文件清单、来源及排除计数等限制说明，核对后才授权发送模型。报告显示源码 `encoding` 及原始字节 SHA-256（`hash`/`rawHash`），差异显示 `diffEncoding`、原始字节 `rawDiffHash` 与解码后 UTF-8 文本 `diffHash`；文本哈希不等于原字节哈希，不能用它证明未转码。此时显示“采集证据（尚未生成发布报告）”，醒目标明仅采集完成、未调用模型，尚无改动解释、接口影响分析或测试建议。可点“下载证据清单 .md”保存为 `captured-evidence-YYYY-MM-DD.md`，它不是发布报告；单次摘要主报告不嵌入全部 diff，也不是原始证据归档。

采集通过一次 `preview-start` 登记任务，随后用短 RPC 只读查询 `result／progress`；轮询不重复启动采集，也不调用模型。取消通过独立 `preview-cancel` 针对该任务，结果仍须核对；任务及句柄仅在内存中，不提供后台重启后续跑。页面采用统一外层滚动，避免项目列表与正文嵌套滚动。

预览在后台内存中保存，创建满 **10 分钟**后不能再开始分析；页面显示剩余有效期，到期可重新采集。后台重启、主动释放或缓存淘汰也可能使其提前失效。修改比较输入或恢复配置会使旧预览失效，但保留上一份报告并标记为旧配置结果，仍可下载。重新采集失败或取消不会删除旧报告；成功采集展示新的本地证据，同时单独保留最近一份成功模型报告，可用“查看上一份模型报告”切换并下载。

### 6\. 确认发送，让模型整理报告

“确认分析范围”默认勾选**使用 DSH 默认模型**，自动读取宿主默认配置，展示本次提供方和模型，无需填写 ID。模型在采集时固定；宿主配置之后变化不会悄悄换模型，需要改用新默认值时重新采集。这不是自动跟随会话临时切换的聊天模型；仅继承提供方和模型 ID，推理强度等参数沿用插件／适配器既有默认，不复制聊天会话参数。

需要其他模型时，取消默认选项，再填写 DSH 已配置的**提供方 ID**和**模型 ID**，不修改宿主配置。旧保存配置未指定选择方式时也默认使用宿主默认模型，原手填值保留供切换使用。宿主未提供默认模型服务或默认配置无效时，明确提示配置后重采集或手动指定，不自动猜测或回退到其他模型。

确认固定版本、源码来源及分析计划，勾选发送授权，再点击“开始执行 · 生成报告”。模型将收到本次预算内摘要、被选中的路径元数据及原文片段，而非全部差异或全部所选源码，可能产生费用。每次点击都消耗本次确认，失败、取消或更改模型后必须重新勾选。

宿主/UI 默认使用 **single-request 单次摘要**：每次明确确认最多派发一次插件模型请求，不自动拆分或重试。默认预算 64000 字节，可在 4000–64000 字节间调整；它包含提示与 JSON 包装的保守估算，**不是 token 数，也不能保证适配所有模型**。修改预算后先“更新分析计划”，不会自动调用模型。预算不足以容纳必要项目统计时拒绝规划，不静默遗漏项目。完整本地清单不等于模型全文覆盖：路径与扩展名启发式选择元数据和有限片段，生成物正文不发送，未发送内容不能推断没有变化。库级 full 分批策略仍可用，不设固定片数上限，但不是当前 UI 默认。计数仅描述所发送摘要证据，不代表耗时百分比或代码理解覆盖率。详见[单次摘要边界](https://github.com/f-e-n-g-0531/dsh-code-report/blob/main/docs/SINGLE-REQUEST.md)。

可以取消任务。模型派发前已取消时不会启动模型入口；**已发送的请求不能保证撤回，是否停止及是否计费由模型服务决定**。离开面板或切换会话不会自动取消付费分析；结果仍归原会话。失败或取消后先只读核对后台状态，不能凭错误提示判定未执行或未计费；只有已确认停止且允许重试、预览仍有效时，才再次确认重试；单次摘要失败不会在同一次生成中追加第二次请求，显式重试可能再次计费。库级 full 策略才涉及同证据、同计划和同路由已校验分片的复用；更改模型或更新计划会清除相应缓存，不自动重试付费请求。模型已完成但响应丢失时，可用“恢复已完成报告”按原任务 ID 只读查询，不重新派发；缓存有 10 分钟和容量限制，不保证永久留存。结果尚未知时应先恢复或核查，不能把断线当作未计费。

### 报告中的对外接口变更

AI 报告要求独立列出 HTTP/RPC、公开函数/类/SDK、消息与协议契约的新增、删除、签名、参数、返回值、错误码和行为变化，给出 A/B 对比、兼容性、调用方迁移及接口测试建议，并引用文件/差异证据。内部函数不自动视为对外接口；对外性或旧契约未知时标为待确认。

模型必须返回规定的改动、接口、影响、QA、未知项五组结构化数据，结论引用本片真实证据 ID；程序检查格式与引用，再生成 Markdown。无效引用、自由 Markdown、截断输出或工具请求都会失败，不作为完整 AI 报告导出。报告附已发送摘要证据索引、实际发送正文片段及来源哈希/UTF-16 偏移、本地完整路径清单与排除项，方便人工复核；本地列出某文件不等于模型收到该文件全文。SVN 属性或目录变化即使没有文本 diff，也会以范围证据列出；无法精确匹配到变更路径的块不按文件顺序猜测。范围证据不等于已读文件正文，也不能据此判断接口没有变化。

这是基于已提供证据的模型分析，不是完整 API 扫描或兼容性证明。**引用有效不等于结论正确，分片完成不等于每条证据被正确理解**；未发现变化不保证没有变化。历史接口分析可附带 A/B 固定版本的声明或协议文件，当前磁盘源码不能当作历史版本。未调用模型时接口章节明确标为尚未分析。

### 影响与测试建议怎么看

影响范围要求先说明受影响的功能场景、使用者及可能观察到的现象，而不是只列类名或线程术语。QA 测试范围中的建议按执行角色分组：

-   **QA 可执行测试**：先写“测试哪个系统／对象的什么功能”，再用“测试功能、正常使用、重点观察、回归边界”简短说明。按已有正常流程测功能，不强制凑详细步骤，也不让 QA 调材质／内部参数、切宏、制作特殊资源、清内部缓存、改配置或插桩；这些准备工作交研发。正常产品界面已有、且有证据支持的用户设置仍可按正常使用覆盖。
-   **研发专项验证**：编译链接、二进制兼容、线程交接、指针或缓冲区等需代码／调试工具的检查，不作为普通手工 QA 用例。
-   **测试前待补充**：连功能对应关系或判断依据都不明确时，由研发／产品确认，不得编造对象、菜单和玩法。若已能确认功能，只缺入口或样例，仍保留功能回归方向及重点观察项，注明研发需提供可直接使用的测试包／场景／资源，不把技术准备转交 QA。
-   **未分类测试建议**：旧模型文本未明确分类时保留原文，需人工确认执行角色与入口，不自动认定可执行。

这些是生成要求和展示分组，不是业务语义正确性认证；格式校验无法证明测试步骤真实存在。模型只收到少量片段时，应明确哪些测试无法制定，不用一串技术术语冒充完整回归单。更新规则不会自动重写旧报告，也不会自动重新调用模型。

### 7\. 下载并保留结果

只有确认本次模型、核对发送范围并明确勾选确认后，点击“开始执行 · 生成报告”，成功结果才显示“Markdown 报告”，可点“下载 .md 文件”保存为 `release-report-YYYY-MM-DD.md`。采集、下载证据或展开帮助都不会自动调用模型；仅有本地证据时流程条不会显示报告已完成。重新采集仍保留上一份成功模型报告，可单独查看与下载，但它未必属于新范围。页面默认用安全 React 阅读视图显示标题、列表和表格，固定技术附录默认折叠，原始 Markdown 单独折叠。普通文本的数字实体解码后仍作为 React 文本，源码围栏保持原样；任意 HTML、外链和图片不执行或加载，仅允许受限的站内引用。导出时对标题、路径、限制说明及模型文本等不可信字段做 Markdown 转义，库级 full 报告中的差异放在围栏内，单次摘要正文用短数字引用，不逐条插入“分片 1”与原始证据 ID，完整清单、已发送正文、哈希与定位保留在插件内的两份折叠附录，不嵌入全部差异；正式报告下载会移除技术附录、采集附录及正文中指向这些附录的数字引用，仅保留“本次比较范围、改动内容、对外接口变更、影响范围、QA 测试范围”五节，不含额外章节或统计说明，并清理已识别的源码引用；HTTP(S) URL 和根相对端点优先保留，根相对路径与本地绝对路径仅凭文本无法可靠区分，这不是完整路径脱敏；条目中的待确认信息仍保留，不据此伪造确定结论。下载上一份模型报告也使用相同规则；本地证据清单的独立下载不变。此处理不重新调用模型，不删除插件内原始结果；外部阅读器与插件行为仍需分别核验，不把安全阅读视图当作下载文件在任意阅读器中的安全证明。

报告不会自动写入项目，也不会随“保存配置”持久化。完整 snapshot 仅在宿主内存中按预览 TTL 保留，生成成功还会释放预览；下载摘要主报告不能还原全部差异。若需完整证据归档，必须在释放或过期前由操作者另行显式保存原始快照／差异；当前 UI 没有自动保存完整快照的功能。内存状态仅限当前插件实例，不提供跨刷新、宿主重启恢复或多个标签页之间的全局互斥。当前插件实例在内存中按会话和工作区保留最近结果；切回会话可查看旧报告，但不恢复快照或模型发送确认。当前展示和最近一份成功模型报告共同占用缓存。结果未知时的恢复任务 ID 也仅按会话保留在插件内存中，切回可继续查询；刷新或插件重载会丢失，恢复前会阻断新分析和更新。报告正文按最多 16 个会话保留，可能按会话数量淘汰，不设固定正文总字节上限；大报告更耗内存。未确认的任务身份不会因正文淘汰就视为已结束。明确“放弃恢复”只标记放弃，不解除结果未知的任务屏障；仍需后台明确停止或报告完成才能恢复新业务及安装。它不证明远端请求停止或未计费；**刷新、插件重载或更新前仍须下载**，不能把内存保留当作可靠归档。可显式清除当前结果：“清除证据结果”只清当前本地证据，仍保留上一份成功模型报告供查看和下载；查看模型报告后点击“清除报告”才删除该模型副本。

## 更新插件

展开页首“插件版本与更新”，先下载报告、保存配置，等待当前任务结束，再检查更新。检查只请求 npm 元数据，不安装，不发送项目源码。

前后台一致且有更新版本时，勾选确认后才安装。安装使用 DSH 原生插件管理器，不自动重启，也不绕过兼容性或安全策略。

-   **需要重启**：保存工作，手动完全退出并重新打开 DSH，再刷新页面。
-   **已应用**：按宿主提示加载新版界面；若前后台仍不一致，手动重启。
-   **结果未知**：安装可能仍在进行，到 DSH“插件”页面核查，不重复安装。
-   **明确失败/取消**：按错误检查；业务操作可恢复，已有报告不会因解锁自动重扫而清空。

报告业务与安装在同一插件实例内互斥：活动任务或结果未知时先核对，不能切换会话来绕过；只读恢复和报告下载仍可用。更新期间和需重载/未知终态会锁住业务操作。控制器在当前插件实例内保留状态，切换会话不解除；刷新或插件重载不保证保留安装状态。此时仍应先核查宿主，不把锁消失当成安装完成。

## 限制与数据边界

| 项目 | 当前行为 |
| --- | --- |
| 自动发现 | 根目录和一级子文件夹；最多 500 项目、100000 目录，约 120 秒扫描预算；未覆盖会提示 |
| 单次比较 | 1–12 个项目，比较两个已保存版本的端点，不含未提交变化 |
| 补充源码 | 工作区支持文件或递归目录，固定版本仅文件；路径条目、文件数量和单文件大小不设固定规模上限；严格正文校验，BOM UTF-16 与窄 © 回退见编码说明 |
| 源码目录展开 | 按格式筛选：按源码／脚本／文本配置／文档扩展名或文件名白名单，不把所有普通文件当源码；其他格式元数据排除并显示数量、扩展名及最多 5 个示例，不计入覆盖。原有敏感／隐藏／构建／链接排除不变；不设固定目录规模上限 |
| 总证据 | 不设固定总量、单命令证据输出（stdout）或分析片数上限；不等于无限资源，仍受可用内存、操作系统及工具限制 |
| 模型输入 | UI 默认单次摘要，预算 4000–64000 字节、默认 64000，非 token；本地全量统计不等于模型全文分析；full 分批仅库级可用 |
| 读取失败 | 待附带文件无法读取、二进制或非法编码使整次采集失败，不静默截断；项目自动发现预算中断仍返回部分发现及提示 |
| 编码 | 源码整文件、差异原始 LF 行均保留 UTF-8／GB18030 优先规则；源码兼容仅增加明确 BOM 的严格 UTF-16LE／BE 与带警告的 ASCII＋0xA9 窄 © 回退，差异不继承；元数据仍严格 UTF-8，不保证歧义或同行混合编码 |
| Git 读取 | 默认远端联网、隔离临时完整抓取；显式本地模式严格离线、缺对象即失败。远端错误不回退本地 |
| Git 子模块 | 仅记录指针变化，不分析内部差异；LFS 引用不等于实际大文件内容 |
| 影响分析 | 不生成完整调用图，不自动执行测试，不保证识别跨项目关系 |

## 故障排查

| 现象 | 先检查什么 / 怎么处理 |
| --- | --- |
| 无“发布报告”入口 | 插件是否装在当前 profile、是否启用；保存工作后手动重启并刷新 |
| 界面新版，后台旧版 | 不要重复安装。保存配置、下载报告后完全退出并重开 DSH；刷新不能替代后台重载 |
| 后台连接失败、HTTP 404/405 | 先确认启用和版本；旧版路由故障可从 DSH 原生插件页升级，再手动重启。404/405 不是单一根因证明 |
| 未发现项目 | 确认工作区、项目是否处于一级目录、是否有 .git/.svn；嵌套或跳过目录手动添加 |
| 还出现“6 层 / 1500 目录”提示 | 这是旧后台行为，不是当前扫描限制；核对后台版本，重启后重新扫描 |
| 采集按钮不可用 | 后台验证需通过；选中 1–12 项并填写路径；Git 版本留空时需对应分支，SVN 需两侧分支及历史读取授权 |
| 版本或对象不存在 / 远端认证失败 | 核对读取方式、远端配置名、分支/标签及 DSH 运行用户的非交互认证。分类提示用于排查，不证明用户凭据错误；远端失败不回退本地。本地模式缺对象时先在插件外补齐 |
| SSH 密钥 / 公钥认证 / 主机密钥提示 | 核对仓库 core.sshCommand、密钥可读性与服务器授权；相对 -i 建议改用绝对路径。主机指纹须自行核验，不自动跳过 known\_hosts 校验 |
| DNS / 连接超时 / 代理 / TLS / HTTP 认证提示 | 按分类检查网络、VPN、代理、受信任证书及读取权限；不会自动关闭 TLS 校验。原始错误不回显 URL、凭据或密钥路径，不把分类当作根因证明 |
| SVN 访问失败 | 核对分支、固定版本、历史读取授权、网络及读取权限 |
| 预览已过期或不可用 | 重新采集；10 分钟、缓存淘汰、后台重启或预览已消费均可能导致不可用 |
| 目录包含 `.sdf` 等非源码文件 | 目录筛选会在自动展开时排除 IDE 数据库、资源和编译库，并记录限制；显式选择二进制 `.sdf` 仍失败。需加载 v0.10.2 或更新版本的前后台才具备此筛选行为 |
| 编码拒绝或正文乱码 | 先区分源码、差异与路径/XML 元数据。源码兼容仅识别 BOM UTF-16 和带警告的 ASCII＋0xA9 窄回退，不是任意西文编码检测；无 BOM 的 NUL、损坏 UTF-16 或其他非法编码仍拒绝，差异规则不变。已有乱码不修复；核对编码标签、警告和原字节哈希，不直接修改业务历史来消除错误 |
| 敏感路径或系统资源不足 | 核对被拒路径或调整采集范围；当前不支持逐个排除某条变更路径，不要删除真实凭据来绕过检查 |
| 只有差异，没有 QA 建议 | 当前是本地证据报告；确认模型及发送授权后执行生成 |
| 更新被新包冷却期拒绝 | 遵守宿主/包管理器策略，等待或由管理员评估；插件不会自动降低安全策略 |
| 页面退出或白屏 | 不反复点击更新；记录前后台版本、发生时间、操作步骤和原始错误。此前反馈的直接原因尚未确定 |

反馈问题时附上插件与 DSH 版本、系统、阶段（扫描/采集/生成/更新）和脱敏错误。**不要上传完整源码、密钥或含凭据的日志。**

## 开发、发布与许可

-   [开发指南](https://github.com/f-e-n-g-0531/dsh-code-report/blob/main/docs/DEVELOPMENT.md)
-   [发布与恢复指南](https://github.com/f-e-n-g-0531/dsh-code-report/blob/main/docs/RELEASING.md)
-   [本版说明](https://github.com/f-e-n-g-0531/dsh-code-report/releases)

本项目采用[非商业源码公开许可证](https://github.com/f-e-n-g-0531/dsh-code-report/blob/main/LICENSE)，**不是 OSI 认可的开源许可**。商业用途（包括公司内部商业项目的开发、测试、维护）需另行书面授权。第三方材料适用各自许可证，见[第三方声明](https://github.com/f-e-n-g-0531/dsh-code-report/blob/main/THIRD_PARTY_NOTICES.md)。

## 常见问题

### @feng0531/dsh-code-report 是什么？

比较多个 Git/SVN 项目的版本差异，生成改动、接口影响与 QA 测试范围报告。

### 如何安装 @feng0531/dsh-code-report？

在项目目录运行 npm install @feng0531/dsh-code-report，或使用 pnpm add / yarn add / bun add。

### @feng0531/dsh-code-report 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/feng0531\_\_dsh-code-report 是否存在。

### @feng0531/dsh-code-report 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @feng0531/dsh-code-report 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @feng0531/dsh-code-report 可以商用吗？

@feng0531/dsh-code-report 使用 SEE LICENSE IN LICENSE 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

### @feng0531/dsh-code-report 的下载量有多少？

根据 npm 官方下载统计，@feng0531/dsh-code-report 在 2026/10/15 – 2026/11/13 这 30 天内被下载 6,758 次，日均约 225 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @feng0531/dsh-code-report 还在维护吗？

最新版本 1\.1\.1 发布于 2026/11/10（4 天前）；至今共发布 50 个版本，其中过去 12 个月发布了 50 个；首次发布于 2026/10/15。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。