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

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

版本：0\.92\.3
npm 元数据更新时间：2026-11-06T07:13:59.309Z
中文译文更新时间：2026-11-14T14:18:55.059Z
软件包许可：SEE LICENSE IN LICENSE

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

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

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

- 包体积（解压后）：1.3 MB，195 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22
- 运行依赖：1 个
- 首次发布：2026-09-30T08:11:38.723Z
- 最新版本发布：2026-11-06T07:13:59.162Z
- 近 30 天下载量：13898（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：165（近 12 个月 165 个）

## 中文简介

DSH 只读 Git/ SVN 代码审查

## 安装

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

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

## README

# DSH Code Review

在 **DeepSeek Harness（DSH）的 Agent 对话里**审查 Git / SVN 代码变更。插件先预览并核对审查范围，再在当前人类明确授权内，用当前 Agent 选择的模型生成中文问题报告；已明确要求审核且预览匹配时，不重复询问确认。

**只读：不修改代码，不自动修复，不提交、回滚或更新你的业务工作副本。**

## 快速开始：第一次怎么用

### 1\. 安装并启用插件

在 DSH 插件管理器中安装并启用本项目，或在终端执行：

```sh
dsh plugin add https://github.com/f-e-n-g-0531/dsh-code-review.git
```

需要 Node.js 22+，以及已安装的 Git 或 SVN 命令行工具。插件依赖 DSH，**不是独立命令行审查程序**，不能用 `npm test` 或直接运行源码来发起审查。

安装或升级后，确认当前 DSH 已加载插件。仓库发布新版本不会自动升级正在运行的插件；如当前会话仍未获得新工具，按 DSH 的插件加载提示重新加载或新建会话。

### 2\. 在目标代码仓库创建 Agent 会话

将会话的工作目录设为要审查的 **Git 仓库根目录或 SVN 工作副本根目录**，并在 DSH 中选好模型。不需要另给本插件配置 API Key。

例如，你的 SVN 工作副本是 `D:/work/my-project`，就以该目录作为会话工作目录。不要把网页地址或仓库远端 URL 当作本地工作目录。

如果会话工作区中有多个子仓库，见下方“多个仓库”示例。

### 3\. 把这段话发给 Agent

```text
使用 code_review_preview 预览当前仓库所有已跟踪文件的改动。
先告诉我：审查哪个仓库、哪些文件、额外读取哪些上下文、发送给哪个模型，以及哪些文件不能审查。
先不要调用 code_review_execute，等我确认。全程不要修改代码。
```

这是发在 **DSH 对话输入框**里的请求，不是终端命令。Git 默认比较 HEAD 与当前工作区的净变化；SVN 默认比较本地 BASE（工作副本记录的基础版本）与当前文件。

> 预览不调用审查模型，但 Agent 对话本身仍可能使用模型。工作副本模式默认不读 SVN 远端；SVN 历史模式会读取仓库版本，必须另行明确允许远端访问。

### 4\. 检查预览，再确认执行

检查 Agent 展示的：

-   **仓库和文件**是否选对，有没有遗漏或意外包含的文件。
-   **额外上下文**是什么；上下文是辅助理解的文件，也可能随执行发送给模型。
-   **模型提供方和模型名称**是否符合你的数据使用要求。
-   **阻断、排除和预算限制**；不能审查的文件不能当作已通过。

确认无误后，在同一会话回复：

```text
确认刚才展示的预览范围和模型，使用该 previewId 执行只读审查。
```

以上是“只预览，等我确认”的流程。若你已明确要求“审核 r7364”（SVN 远端访问仍须单独授权），Agent 应先内部预览，固定并核对范围、模型路由、预算与权限；预览符合当前明确授权时，直接执行，不再要求你重复确认。只要求预览或明确要求等待确认时不得执行；范围、模型或发送目的地超出授权，或授权边界不明确时，先询问。

插件使用预览返回的 ID 执行。默认预览有效期约 **5 分钟**，返回 `expiresAt` 与 `validForMs`；到期、文件、模型或会话目录变化后，需要新预览并重新核对当前授权，不能复用旧预览批准。`confirmed:true` 表示当前人类已明确授权且本次预览与授权一致，不是无授权绕过。计划最少调用只是初始下限，不是总调用数或耗时上限，后续取证、复核与综合会增加工作量。会话工具权限与宿主安全校验照旧，确认不能绕过限制。

### 后台执行如何等待

后台任务推荐调用 `code_review_wait({jobId, waitFor:"terminal"})`，一次最多等待 60 秒，中间检查点继续逐条保存但不会逐条唤醒等待方。任务仍在运行就继续等待；超时返回 `changed:false` 不代表结束。需要逐事件进度时使用 `waitFor:"progress"`，把返回的 `waitRevision` 原样作为下一次 `after`，不要自行加一，也不必每次再查 status。`code_review_status` 用于主动分页取完整结果或检查点。等待调用取消只停止等待，不取消后台审核。

### 5\. 查看结果

执行工具默认在对话中返回 **一份人可读的中文 Markdown 报告**，同时保留完整结构化 JSON。首屏先回答所选范围是否查完、记录了哪些候选和哪些结论尚不能下；问题卡按“本次新增（复核支持）”“当前源码问题（复核支持）”“待核实”“原有问题（复核支持）”“已反驳”分区，说明位置、触发条件、影响、依据及已有建议。分区仍遵循严格证据判定：仅 supported 或缺少有效旧新对照不能算本次新增，当前源码模式不作历史新增归因；**复核支持和引用校验不等于事实、运行复现或因果证明。**

主文聚合未完成原因并给出下一步；完整证据与判定、逐项覆盖、风险计划、执行诊断及聚合限制保留在**单独的技术报告**；后台任务可用 `code_review_status({jobId,detail:"technical"})` 读取，不需要拼接批报告。通俗主文只是已有结果的呈现，不代做源码复审、不隐藏限制、不放宽证据门槛，也不会为改写报告额外调用模型或改变取证算法。执行诊断列出实际加载的插件版本、阶段调用和墙钟统计；累计调用耗时可能并发重叠，不代表纯提供方耗时或可相加的总耗时。

如需保存报告，可以另行告诉 Agent：“将本次报告保存到我指定的位置”。插件本身不会自动在业务仓库创建报告文件。

## 按场景直接使用

下面的自然语言可以直接发给 Agent。其中只要求预览或明确要求等待确认的示例，不得直接执行；若直接明确要求审核，则按上面的授权规则内部核对预览后执行，不重复询问。

### 只审查几个文件（Git / SVN 工作副本）

```text
使用代码审查插件，只预览 src/api.ts 和 src/client.ts 的当前改动。
自动补充理解它们所需的依赖文件。先展示范围和模型，等我确认再执行，不修改代码。
```

对应 `code_review_preview` 参数（**工具参数，不是 shell 命令**）：

```json
{"selectedPaths":["src/api.ts","src/client.ts"],"autoContext":true}
```

文件名要替换成仓库中实际存在的变更路径。未跟踪文件不会默认纳入，必须用 `selectedPaths` 显式选择。省略该参数时，范围是整个仓库的变更，不限于当前子目录。

### 审查 Git 单个提交

```text
使用代码审查插件预览 Git 提交 abc1234，先展示范围，等我确认后再执行。
```

```json
{"commit":"abc1234"}
```

将 `abc1234` 换成实际提交号。与该提交的唯一父提交比较；根提交与空旧版本比较。**合并提交请改用两个版本比较**，明确选择旧、新端点。

### 审查 Git 两个版本之间的变化

```text
预览 Git 的 v1.0.0 到 v1.1.0 之间的代码变化，自动读取必要依赖。先展示范围，不直接执行。
```

```json
{"baseRevision":"v1.0.0","targetRevision":"v1.1.0","autoContext":true}
```

比较两个版本的文件树，不自动计算合并基点，也不会把工作区中的未提交正文当作历史正文。`commit` 不能与这两个参数混用。

### 只审查 Git 暂存区或未暂存改动

提交前只看已暂存内容，或只想确认工作区里还没暂存的修改：

```json
{"changeScope":"staged"}
```

`staged` 比较 HEAD 与索引（相当于 `git diff --cached`）：右侧是已暂存内容，工作区里尚未 `git add` 的修改不作为变更内容，也不会作为变更正文发送给模型。把值换成 `"unstaged"` 则比较索引与工作区（相当于 `git diff`）：左侧是已暂存内容，仅作为旧侧基线，右侧是工作区文件。省略 `changeScope` 时默认仍是 HEAD 到工作区的净变化。

这两个范围只用于 Git 工作副本，不能与 `commit`、`baseRevision`、`targetRevision`、SVN 参数或 `reviewMode:"project"` 同时使用。未跟踪文件仍默认排除；`worktree` / `unstaged` 下用 `selectedPaths` 显式选择后才会纳入。预览和报告都会标明实际比较的是哪两个内容。

`staged` 下显式上下文、自动依赖、调用方候选和规则文件仍按工作区当前内容读取，可能包含尚未暂存的修改；预览会列出这些文件。

### 审查 SVN 单个 revision

例如审查 r7315 引入的净变化，即 **r7314 → r7315**：

```text
使用代码审查插件预览 SVN r7315（与 r7314 比较）。
允许为这次预览读取当前工作副本对应的远端仓库固定版本。
先展示来源、范围和模型，不发送源码给审查模型，等我确认再执行。不要更新工作副本。
```

```json
{"svnRevision":"7315","svnAllowNetwork":true}
```

必须在 SVN 工作副本根目录运行。插件从该工作副本对应的仓库 URL 读取固定版本，不要求先把工作副本更新到 r7315，也不会执行 update。远端认证不可用时会明确报错，不会改用本地文件冒充历史版本。

### 审查 SVN revision 区间

```text
预览 SVN r7300 到 r7315 两个版本端点的净变化。
允许读取当前工作副本对应远端仓库的固定版本，自动补充同版本依赖。
先展示范围和来源，等我确认后执行，不修改或更新工作副本。
```

```json
{"svnBaseRevision":"7300","svnTargetRevision":"7315","svnAllowNetwork":true,"autoContext":true}
```

这是两个版本端点的比较，**不是逐一审查区间内的每个提交**。revision 使用带引号的十进制数字，不写 `r7315`、`HEAD` 或日期；同一路径比较要求旧版本小于新版本；不同分支可使用相同 revision（见下一节）。`svnRevision` 与区间参数不能同时使用，也不能混用 Git 版本参数。

`svnAllowNetwork:true` 只允许读取本次工作副本对应仓库的固定版本，不授权更新、合并或任意远端 URL。本地 `file:` 仓库通常无需此参数。

### 比较 SVN 两个分支

跨分支、有效继承属性和独立基线替换从正式版 v0.80.1 提供。请先确认当前 DSH 加载的版本；仅更新仓库不会升级宿主插件。

```json
{"svnBaseRevision":"7315","svnTargetRevision":"7315","svnBasePath":"branches/release","svnTargetPath":"trunk","svnAllowNetwork":true,"autoContext":true}
```

分支路径相对于当前SVN仓库根，不是本地目录或任意URL。旧、新两侧分别固定URL、peg与operative revision；同revision可以比较不同分支。只能在同仓库UUID内比较；嵌套重叠根和不明确来源拒绝，不能推断merge提交归属。

### 查看有效继承 mergeinfo

```json
{"svnRevision":"7315","svnAllowNetwork":true,"svnEffectiveMergeinfo":true}
```

显式允许读取选中节点及最近祖先的合并属性，额外读取受共享预算限制；工作副本模式也可使用该开关并保持离线。空属性屏蔽继承，祖先证据不完整、混合BASE或不安全来源显示unknown；结果仅为属性导航，不证明相关revision已经审核。

### 审查未提交替换

```json
{"selectedPaths":["src/module","src/module/old.cpp","src/module/new.cpp"],"svnReplacementBaseRevision":"7314","svnReplacementAllowNetwork":true}
```

替换比较的旧侧是你显式选择的目标URL固定历史节点，不是本地BASE，也不证明它就是被删除节点的原始revision。目录后代必须独立选入；只选父目录不能算后代均已批准。远端读取使用独立许可，默认不访问。没有可确认旧来源时明确拒绝，不读取复制源冒充旧节点。

### 加入业务要求、规则和调用方

```text
只预览 src/api.ts 的改动；业务要求是“请求失败时必须释放连接”。
把 src/types.ts 作为辅助上下文，使用 review-rules.md 的项目规则，
并在 src/clients 目录中寻找引用该变更文件的代码。先展示读取范围，等我确认。
```

```json
{
  "selectedPaths": ["src/api.ts"],
  "contextPaths": ["src/types.ts"],
  "rulePaths": ["review-rules.md"],
  "callerScopePaths": ["src/clients"],
  "businessRequirement": "请求失败时必须释放连接"
}
```

这些文件和目录需要实际存在，路径相对于所选仓库：

-   `contextPaths`：手动加入辅助文件，不代表该文件本身完成了主审。SVN工作副本的未变更文件须通过离线正常节点/属性及来源检查；标准、固定宽度及受支持的复合自定义关键字经过 BASE 核验后可用于上下文；关键字名可由空格、制表符或换行分隔，格式内空格使用 `%_`。引号配置、未知格式及特殊或不可确认来源仍明确拒绝，已选择的可审查变更复用快照。
-   `autoContext:true`：自动补充最多三层文本依赖，不是全仓扫描或编译器分析。
-   `callerScopePaths`：在明确指定的非根目录中寻找字面引用。预览可能扫描该目录内不匹配的候选正文；只有捕获的匹配上下文随执行发送模型。SVN受支持的关键字候选经 BASE 核验后支持，扫描及核验正文共同计费；不支持配置明确失败，不保证找到全部调用方。
-   `rulePaths`：最多四个 UTF-8 Markdown 或文本规则文件，不能同时列为上下文。
-   `businessRequirement`：帮助确定审查目标，本身不是缺陷证据。

Git / SVN 历史审查也能使用这些参数；依赖和调用方按对应版本读取，不回退到当前工作区。只想提供旧版辅助文件时，用 `oldContextPaths`，例如 `{"svnRevision":"7315","svnAllowNetwork":true,"oldContextPaths":["src/old-helper.ts"]}`。它不能用于工作副本模式。

### 一个工作区中有多个仓库

假设会话工作目录下有 `project-a`、`project-b` 两个仓库：

```text
只预览工作区中 project-a 仓库的 src/api.ts 改动，不读取 project-b。先展示范围再等我确认。
```

```json
{"repositoryPath":"project-a","selectedPaths":["src/api.ts"]}
```

`repositoryPath` 相对于会话工作目录，必须指向一个实际仓库根目录；其余文件路径再相对于该仓库。每个仓库分别预览和执行，不使用绝对路径、`..` 或链接目录。

## 长任务：后台预览、审查与取回结果

全项目或慢仓库建议使用后台工具，不让一次外层调用等待整个项目。仍先预览并核对当前明确授权，匹配时直接执行；仅要求预览则停在预览，超授权则询问。启动返回jobId不等于审核完成。

1.  调用code\_review\_start，phase设为preview，previewArgs填原预览参数（例如reviewMode=project）。
2.  用code\_review\_status和jobId查询；完成后读取resultSummary中的预览范围、模型和previewId。
3.  内部检查预览的范围、模型、发送目的地、预算和权限；当前人类已明确要求匹配的审核时，不重复询问，调用code\_review\_start，phase设为execute，传previewId与confirmed=true。仅要求预览或等待确认时先展示并等待；超授权时先询问。
4.  持续调用code\_review\_wait等待进度变化或终态，不因启动返回任务ID就结束用户请求。可展示阶段与“处理数/总数”，不分批汇报问题；抓取阶段分母未知则不显示虚假百分比。等待返回仍running就继续等待，不重新启动。任务结束后取回并统一交付一份最终报告。查询审查任务；offset/limit分页取回检查点、文件状态和发现；单个检查点内的大清单用checkpointIndex指定其零基索引，再用offset/limit取回内部全部条目。可调用code\_review\_cancel取消。

报告保存在宿主profile的data/dsh-code-review/jobs目录；没有profile环境时使用用户主目录.dsh下的数据目录，不写入业务仓库。内容可能含源码片段，应按源码敏感级别保护。本次启动调用结束不自动取消后台任务；明确取消、停用插件或宿主退出会停止它。

重启后可按原jobId读回保存记录，原运行标记interrupted，不自动继续外发。recovery给出已观察文件/窗口与未完成路径；它不是完整分母或新授权；宿主重启及自动恢复本身不授权外发，补审必须有当前明确授权并重新预览核对。新预览的runtime包含实际加载版本和模块位置，排查不同工作区时分别核对，不根据另一台机器推断。

`staged` 变更审查的独立文件链默认最多 2 条并行；配置 `changesConcurrency` 为 1～4（1 回退串行），启用阶段续审时先扫描全体文件主审，再调度跨窗口／跨文件综合；恢复队列按真实依赖就绪情况排队，保留其他阶段的读取最低份额。配置 `maxRetrievalRounds` 为 0～50，默认为 3，限制主审／综合的检索请求回合数（不是成功读取次数；非法请求也会消耗回合）（0 只允许最终答复）。配置不是 preview 参数，不改变模型或来源授权；并发仍共享同一份读取/调用预算，额度不足时完成顺序可能影响哪些任务未完成，不能保证与串行逐项结果相同。提供方限流时应降低并发。复核可预取批准快照中候选锚点附近的同侧原文，仍允许追加反证读取并逐字校验；不复用主审结论或其他会话凭据。完整变更计划可容纳时仅生成一次再分发到窗口，否则保留原分窗口计划并在预览估算中体现。

大文件超出单次输入时按原行号分段。精确差异算不出时使用明确标注的包络，可能包含未变行，不声称精确归因。完整结束但 JSON 语法无效时会按当前阶段 schema 最多请求两次明确纠正，记录额外调用；检索请求非法时整批不执行并明确纠正，回填采用可追溯的滚动工作集、必要时延后重复初始源码正文，保留精确编辑、风险／调用线索和已读证据回执，不虚构证据。主审默认最多 3 轮检索，复核及独立反证默认最多 6 轮；独立配置及取值规则见下文“可选模型关系比较与复核取证轮数”。恰好用完允许轮数后可自然返回最终答复；实际请求额外检索被拒时才记录相应限制，不把用完轮数当作审核通过。不会给错误输出补括号、猜字段或当成无缺陷。

### 显式续审与私有模型工件

需要补审时，在**新预览**中传入 `resumeFromJobId`，例如 `{"resumeFromJobId":"原执行任务的真实jobId"}`；仍须核对新范围与当前明确续审授权并通过当前宿主权限；不能复用旧批准，明确要求匹配的补审时无需再重复询问。只复用同一会话、工作目录、模型路由／思考设置下，完整快照、配置和运行时身份均匹配的已完成且符合复用条件的文件链；项目模式还绑定对应批次。来源或配置变化不做猜测复用。旧发现标记 `priorRun`，不伪造本轮读取凭据、模型调用或覆盖。变更模式开启阶段续审时，schema2 检查点还可保存已接受但所在文件链未完成的 primary 生成；它只省去匹配的主审生成，综合、交互和复核在新安全边界执行，复核重新取得独立回执。预览分别显示可复用文件、生成及仍需的新鲜复核；不能把保存了正文或候选当作阶段完成。

后台审查会在上述宿主任务目录的 `artifacts` 子目录留存有界模型工件，包括失败／取消时已捕获的文本或工具参数；不含 reasoning。它们可能含源码，应按源码保护，不会自动加入提示词、当作已确认发现或在普通状态报告公开。默认单工件 1 MiB、每任务原文总量 8 MiB、最多 4096 条记录；截断由工件标记，存储超限明确返回遗漏标记和无源码诊断。读取绑定原会话、目录、提供方、模型和思考设置。需要查看时，Agent 必须先提示“可能把源码／模型原文带入当前对话”，取得你的明确同意，再调用 `code_review_artifacts({jobId,confirmed:true})`；可用 `offset`／`limit` 分页，默认一次 1 条、最多 100 条。返回内容标为 `sourceBearing:true`、`untrusted:true`，不是批准证据；普通 `status` 不返回工件原文。目录／文件使用 0700／0600 权限模式及原子写入；Windows 模式位不等于额外 ACL 保证。

## 多个会话同时审查

可以同时打开多个DSH Agent会话：会话A审项目A，会话B审项目B，也可以分别审查同一项目。各会话的预览、执行锁、模型路由、取消和预算独立；A正在执行不会让B收到全局busy。一个会话不能同时启动两个独立审查任务，但任务内部可按配置并行；不能拿另一个会话的previewId执行。宿主停用插件会结束全部服务，单次取消只影响当前请求。

## 审查整个项目当前代码

在项目仓库根目录创建会话，发送：

```text
使用code_review_preview，全项目模式审查当前已跟踪代码，包括没有改动的文件。
先列出全部文件、排除项和分批范围，告诉我模型和预算；等我确认再执行。不要修改代码。
```

```json
{"reviewMode":"project"}
```

这不是HEAD到工作区的差异：模型检查当前已有缺陷，不要求问题由最近提交引入。默认仍是 `reviewMode:"changes"` 的变更审查。

项目模式接受reviewMode、repositoryPath、可选selectedPaths、reviewEffort和显式续审参数resumeFromJobId，不与历史revision、autoContext、规则或调用方参数混用。默认全部跟踪节点；不读取未跟踪/忽略文件、子模块、外部仓库及链接目标。目录只作清单记录，源码按批次审查；跨批次不宣称完整调用图或全程序语义分析。

未指定选择时，清单上限 10000 节点，Git 索引输出上限 2 MiB。Git 显式 `selectedPaths` 只查询所选精确文件，不先枚举全仓，因此大仓库可用小范围预览；空数组不枚举索引，目录与通配符不会展开。此时 `inventoryScope:"selected"`、`inventoryComplete:false`、`selectionComplete:false`，`totalTrackedNodes:null` 表示全仓总数未知，`inventoryNodes` 仅为所选清单数；只绑定所选索引及正文，未选文件的变化不使该局部快照失效。单次选择运行时最多 1000 节点（公开工具参数显式列表最多 200 项）/16 MiB，12 节点一批，单文件 256 KiB；超限必须重新预览。SVN 仍枚举本地已观察清单，显式选择不绕过清单上限，稀疏/外部/链接及不支持属性显示限制，不证明远端完整覆盖。SVN 单次采集共享 8 MiB 元数据保护；Git 所选索引单次查询最多 64 KiB、合计 2 MiB。不按命令条数、插件秒表或模型调用次数中断；耗时受宿主/模型提供方限制，用户可随时取消。

全项目审查默认最多 **8 个独立批次并行**，每批内主审、检索、复核仍按依赖顺序执行；预览和报告的 `execution.batchConcurrency` 显示实际配置。插件配置 `projectConcurrency` 可设为 1～8，设 1 回退串行；遇到模型提供方并发限制或 429，应降低并发。该设置不是 preview 参数，不扩大来源或共享模型调用预算，也不减少模型调用量或承诺 token 成本下降。仅一个批次时不会获得批间加速；实际提速受提供方吞吐、批次均衡及检查点写入影响。

对外只交付一份统一最终报告，给出总数、completed、excluded、blocked、pending、去重后的发现及未完成综合阶段；内部批次快照仅供证据追溯，不需要用户拼接报告。completed只表示所选捕获文件已处理，不代表代码正确；排除与阻断从不算完成。所绑定的代码或清单变化会拒绝旧预览，运行后无法复核则标记outdated。

## 自动选择整体审查与子智能体

生产默认 `executionStrategy:"auto"`：fresh、单轮changes且完整文件全部适配输入时，选择整体审查；多个批次自动使用真实子智能体，单批直接主审。preview返回 `dispatch.requested/effectiveStrategy/reason/childMode/plannedChildCount`，明确计划方式及原因；实际报告另记录真正启动的child身份，不把文件并发数当子智能体数。可在preview显式选择auto/staged/whole-scope。已有显式staged配置不暗改；auto遇超大完整文件回到staged并披露原因，project/resume/多轮保持兼容路径。显式whole-scope仍严格拒绝不支持场景。能装下时，一次主审同时检查全部成员；超限才分批，不按四个文件强切，不再额外调用逐文件风险规划、业务分组及旧专门综合。候选集中独立复核，缺少上下文时仍可能增加检索调用，因此不承诺总调用仅一次。

实际超限分为多组时，整体路径使用宿主真实 `spawn` 子智能体有界并行，`wholeScopeConcurrency` 可设1～4（默认2）；只有一组时不创建子智能体。正常补读沿用每组独立会话和持续上下文；宿主确认输入容量受限时可在清理父会话后，按成员有界拆分并新建子会话补审，保留父尝试和候选，不重跑已完成兄弟，也不增加原预算。全部主审收尾后集中复核。宿主须具备受限预设、结构化子会话和活动父Agent；能力缺失或变化明确拒绝，不暗中退回串行。子智能体共用唯一批准快照读取账本与模型生成尝试总账，取消须等待所有子会话清理。跨组关系未核查仍partial，并行不提高完成标准。

内部 `review_snapshot` 工具可能在父会话目录可见，但只有本次注册且身份绑定的审查子会话可执行；父会话和其他子会话读取前拒绝。子会话作为宿主管理的独立Session按宿主规则记录，可能含批准源码和工具响应，不等同于插件私有模型工件留存。

`maxInputBytes` 是插件显式输入保护，不是模型上下文容量探测；生产默认改为 524288 字节（512KiB），低层API保留原98304默认，允许配置为 1～4194304 的整数。主审计划计入完整新旧正文、JSON转义、规则、检索目录、指令与原生结果工具；持续子会话发送前另外检查包含历史消息和工具的逻辑LLM envelope，不是提供方最终HTTP字节。宿主系统提示与历史开销可能使已规划组在发送前受限，届时保留未完成而不截断源码。预览的 `plan.maxInputBytes` 与执行使用同一值。提高前应核实当前模型容量、费用及提供方限制，插件不会自动猜测容量或因失败不断加大输入重试。

当前仅支持 fresh 单轮 changes；多轮、旧任务恢复及 project 明确拒绝，预览显示 `resumeSupported:false`。超大完整文件显示 blocked，不截断或把差异窗口冒充全文；多批跨边界未核查保持 partial。身份、原文定位、归因、独立复核回执及来源新鲜度校验不变。默认auto不代表模型容量保证；整体路径尚无真实业务同条件质量与耗时验收，不宜把单测调用减少当作业务问题已解决。配置由宿主插件管理方式加载，发布不会自动安装或重启宿主。

## 风险投入、发现台账与复审

`reviewEffort` 可选 `auto`（默认）、`quick`、`standard`、`deep`，在preview中明确。它是对批准变更的有界确定性检查，不额外调用模型规划；quick也不跳过原文、归因和独立复核。高风险线索只改变检查方向，不证明缺陷。深度模式下仅已获首轮支持的high/critical候选增加一次独立反证复核，使用新的读取回执；不把首轮结论传给第二位验证者。两次结论分歧、证据不足或反证未完成均保守处理，不按多数票升级。插件配置 `enableCounterVerification:false` 可关闭额外反证；开启状态在preview绑定。它可能增加调用和耗时，不承诺普遍提速。

变更审查可在新后台preview传 `rereviewFromJobId` 接续本会话、相同仓库/模型/规则/需求政策的终态且未标记outdated的报告。每轮仍重新捕获、预览和授权；旧回执及结论不进入本轮证据。关联修复链第三轮提示重新考虑方案，第四轮拒绝；不是跨任务全局次数锁。可用 `findingOutcomes` 记录已知发现的 `fixed/refuted/intentional/deferred` 与原因，人工标记是处置声明，不证明修复。相同精确定位与缺陷主张保持台账身份，不因行号移动重复建项；未再次观察不自动关闭。

默认 `rereviewScope:"full"`，未知完整依赖图时保持全新主审。明确选择 `rereviewScope:"diff-only"` 才将新旧两侧、属性和来源指纹都未变的主文件保留为未重审；本轮完整批准来源仍可检索。预览列出primary与unreviewed路径，实际省略未变主文件时报告强制partial，不能当作跨文件影响已排除或全范围通过。取消/失败终态不被partial覆盖。上述修复链和差异复审仅changes支持；project支持风险投入但不接受历史修复链参数。

默认execute与wait交付短简报，先给最终复核决策、位置与下一步，不展开数千行附录；完整记录仍保存。需要原始候选、全部限制和诊断时，显式调用 `code_review_status({jobId,detail:"technical"})`，只读取所属任务已保存报告，不重新调用模型，也不是私有模型响应读取。短简报省略处明确标识，不从模型长段落推断新结论。报告首屏先给复核支持数量和优先候选编号，分开已复核不确定与复核未完成，显示未查范围。正文按类别与严重程度展示，附录保留原候选顺序与完整证据。真实事件评测见[仓库评测说明](https://github.com/f-e-n-g-0531/dsh-code-review/blob/main/evaluation/README.md)；没有专家确认和完整实际结果时不输出命中率。

## 工具调用流程（给需要精确指定参数的人）

普通使用者只需上面的对话请求，不必手工构造 ID。需要精确控制时，让 Agent 按下列顺序调用：

1.  调用 `code_review_preview`，参数可以是 `{}` 或上面的 JSON 示例。
2.  内部核对返回的仓库、模型路由、发送目的地、文件、预算与权限，保留返回的 `previewId`；只预览或需确认时向用户展示。**此时还没有完成审查。**
3.  当前人类已明确要求审核且预览与授权一致时，直接调用 `code_review_execute`，不重复询问；只预览、等待确认或超授权时不得直接执行：

```json
{"previewId":"替换为本次预览真实返回的ID","confirmed":true}
```

不要把示例 ID 原样执行，也不要在 execute 中重新传文件和版本参数。要改范围，重新 preview。`reviewRounds` 可在预览时指定为 1～3（默认 1），表示独立审查次数，会增加模型调用量，不是模型的思考强度设置。

## 如何判断报告是否完成

| 状态 | 含义 | 你应该做什么 |
| --- | --- | --- |
| `completed` | 相应阶段完成，不表示代码绝对正确 | 阅读问题、复核结果和限制 |
| `partial` | 只完成部分工作 | 检查未完成文件、证据不足或预算限制 |
| `failed` | 执行失败，不是审核通过 | 根据诊断处理后重新预览 |
| `cancelled` | 审查被取消 | 需要时重新发起 |

每个候选问题会保留位置、触发条件、影响和复核结果。复核可能支持、反驳、无法确定或未完成；引用原文匹配也不等于缺陷一定成立。**没有发现问题不证明没有缺陷，读取过上下文也不等于审查了整个项目。**

### 模型结果传输与读取预算恢复

生产入口启用原生结果工具 `submit_review_result`，只接收结构化结果，不执行模型工具产生的文件操作；同次调用仍兼容文本结果。底层适配器的原生模式默认关闭，由生产服务显式启用。只有原生模式允许提取开头完整、平衡且字节不变的 JSON 后面的明确自然语言尾注；多 JSON、含糊尾部、损坏 JSON 仍拒绝，不补字段或猜身份。原生模式的预览与发送前校验使用同一 UTF-8 测量：输入、阶段契约、格式指引和序列化工具 schema 均纳入，不把字节估算当 token 或费用保证。

已启用的模型桥接对完整结束但 JSON 无效的响应最多请求两次明确纠正（共最多三次调用），不会修补损坏 JSON；取消、提供方错误、不完整结束或输出超限不作此类重试。主审响应中的文件身份、严重性、必填字段或行证据校验失败时，最多请求一次完整响应纠正，仍按原快照、输入及调用预算严格验证。每次额外调用和纠正事件都会计数记录，恢复失败仍标为失败，不代表发现了缺陷。

全项目模式可将行号错位的证据重新定位到同文件当前侧的唯一精确文本；不跨文件、跨版本或模糊匹配，原候选保留供审计，窗口范围仍须通过校验。模型会收到共享检索预算余量；预算耗尽或请求超过余量时仅给一次不再检索的最终答复机会，不扩大读取权限。预算受限的文件仍列为未完成，已有有效候选保留，不会因返回空 findings 就算审查通过。

## 常见问题

| 遇到的问题 | 处理方法 |
| --- | --- |
| Agent 没有调用代码审查工具，只给了普通文字分析 | 明确要求调用 `code_review_preview`；若工具不可用，检查插件是否启用并已加载到当前会话 |
| 找不到仓库 / 选错仓库 | 检查会话工作目录；多仓库时用 `repositoryPath` 指定子仓库根目录 |
| 新文件没有出现 | 用 `selectedPaths` 显式选择未跟踪文件；路径相对于仓库 |
| 预览过期、文件已变化、模型已变化 | 新预览并重新核对当前授权，不复用旧 ID 或旧批准；超出授权时询问 |
| SVN 历史提示需要网络许可 | 确认可以访问仓库后，预览参数增加 `svnAllowNetwork:true` |
| SVN 登录、权限或版本不存在 | 检查 SVN 本身的访问权限和版本号；不要把密码写进对话或仓库 URL |
| 文件被阻断或报告 partial | 阅读具体原因；缩小变更批次、补充允许的上下文，或处理真实冲突后重新预览。不能把排除文件视为通过 |
| 想只审查 Git 暂存区或只审查未暂存改动 | 预览参数设置 `changeScope:"staged"`（HEAD → 索引）或 `changeScope:"unstaged"`（索引 → 工作区）；默认仍是 HEAD 到工作区的净变化 |

## 支持范围与安全边界

-   执行会把批准范围内的代码、上下文、所选规则及业务要求发送给当前模型提供方；敏感项目请先检查预览和模型。常见凭据路径过滤不能保证源码没有秘密。
-   插件遵循 DSH 工具权限；确认预览不等于绕过宿主权限。不执行项目代码、构建脚本或模型生成的 shell 命令。
-   Git 支持工作区净变化、暂存区/未暂存范围、单提交、两版本比较。SVN 支持工作副本和固定历史端点；**尚未完整支持所有 SVN 状态**。
-   SVN 根目录属性可预览；同仓库复制新增以空目标旧侧审查，复制来源只作信息；移动的新增/删除分别覆盖。目录后代须逐项纳入，选择父目录不自动批准所有后代。
-   SVN 标准、固定宽度和受支持的复合关键字展开，以及工作副本变更/自动依赖/命中调用方、固定历史变更及上下文的换行元数据保留原文证据；不以规范化结果证明行为等价。自定义/固定宽度关键字、未提交替换、冲突、特殊节点、切换/外部工作副本及跨仓库比较等仍有限制。同仓库跨分支与独立基线替换需要下文列出的显式参数。已提交固定历史替换与未提交替换的支持不同，详见 [SVN 支持矩阵](https://npmcn.com/package/%40feng0531/dsh-code-review/SVN-SUPPORT-MATRIX.md)。
-   源码可混用 UTF-8（含 BOM）与 GBK/CP936；无 BOM 时优先严格 UTF-8，失败才尝试完整合法 GBK 字节序列，原有带 BOM 的 UTF-16 仍支持。BOM 声明损坏不回退；不支持 GB18030 四字节扩展或单文件混杂编码。两种编码都合法的无 BOM 字节优先按 UTF-8 解释，自动识别不保证还原原作者意图；不转码写回，原始字节哈希、换行与证据行号保留，规则文件仍限 UTF-8。
-   二进制、不能解码的文件、普通源码路径中的链接和超限内容会明确阻断；已跟踪的 SVN 链接只审查 `link 目标` 记录，不读取目标正文，不静默截断后声称完成。文本导航不证明语义绑定、执行可达或完整调用覆盖。

## 调用效率与预算

以下业务分组、窗口及专门综合策略用于 `staged` 路径。业务分组在文件链启动前独立完成，不以先跑完第一个文件作引导。适合的 2～4 个文件可合并为一次组主审：必须是精确变更、完整正文且可容纳的非项目模式成员，响应逐个返回原文件身份并通过各自校验。窗口化、超预算或不适合的组在发送前回退单文件。开启组交互通道后，仅当前生成的真实读取覆盖全部成员编辑且交互引用校验通过，才替代完全匹配的专门交互生成；缺失或非法通道保留合法主审并回退，候选仍独立复核。预览显示条件性节省及回退成本，组主审不等于跨文件缺陷已证明。可合并的风险假设是可选信息，缺失／无效会记录限制，不为它单独追加调用。

变更模式默认优先保留主文件全文，仅附带有导入／调用等关系的完整上下文对象（序列化合计最多16KiB或输入上限四分之一，取较小值）；其余批准来源保留版本目录按需读取，不表示不存在或已核查。完整正文，或经过精确新旧编辑、坐标和原文核对且覆盖全部编辑的单批窗口，可将风险问题合入首轮主审。多批窗口、包络差异和项目审查仍保留独立规划；保留独立候选复核和跨窗口／跨文件综合，不以丢弃窗口换取速度。报告中的合并问题不是独立风险规划或已验证条件。

模型搜索的精确命中可同轮附带批准来源原文，每阶段最多2次额外读取尝试、每次最多24行；占用原共享额度并预留4次操作／16KiB输出，不猜测另侧坐标，不增加检索轮数。配置 `focusPrimaryContext:false`、`enableSearchSeeds:false` 可分别关闭上下文聚焦和搜索命中附读；无检索能力时不会隐藏正文。

共享读取预算按本次可审文件数有界缩放，预览的 `execution.readerBudget` 显示具体值；所有阶段共用、不逐文件刷新。生产编排在根上限内按主审规模及综合／复核单元权重预留最低额度，未用份额释放；最低份额取整可能为零，不保证每个阶段都有新读额度。同一批准快照的相同操作结果可复用，`calls` 计实际结果生成、缓存命中另计；每次交付仍计序列化字节，复核回执重新签发，跨快照不复用。必要证据不足仍保留未完成范围，不以提前返回当作完成。配置 `riskPlanningMode:"separate"`、`readerBudgetPolicy:"fixed"` 可回退原规划和固定读取额度，这些是插件配置，不是preview参数。更多额度不保证更快或完整覆盖；不建议用提高并发掩盖冗余调用。

诊断显示实际加载版本、阶段及调用目的计数、读取余量，并区分单阶段检索轮数和共享读取额度。新增无源码的JSON纠正原因、协议／审查格式纠正计数及未合并规划原因；纠正计数以实际纠正调用为准；这些诊断不含原响应、源码片段或提供方错误文本，与下面说明的私有模型工件分开。`primary-initial` 是检索链初始调用，不只包含主审阶段。累计调用耗时可能并发重叠，不能当作总耗时或纯提供方耗时。离线调用数减少不代表实际审核必然同比提速，不能用更快返回partial冒充审核完成。

### 0.87.0 的连续取证与策略开关

同次变更审查会按目标来源选择此前实际交付过的有限片段，经当前阶段 reader 重新读取并放入当前模型输入；未发送、超预算或取消的片段不计为本阶段证据，缓存命中仍扣投递字节，不继承历史回执。精确适配的交互单元可把可选风险问题内联到结果中；缺失或非法风险如实保留限制，不抹合法发现、不补发规划。

迁移契约把明确的旧入口、新入口和调用方组织为有界导航，旧新路径分别解析并保留跨组联系；不是同名／相似度推断的语义证明。既有严格迁移分支只接受宿主契约限定的来源、编辑和本次独立复核证据，缺少一侧仍未决。另有默认关闭的 `enableModelComparison` 分支：宿主核对批准原文、新回执、完整文本角色范围和候选真实编辑，跨文件关系仍由模型判断、因果未证明，报告单列支持结果，不并入旧严格新增统计；项目模式不启用。C++ 类／成员线索仅覆盖字面 include、唯一声明／类外定义和明确接收者；重载、继承、虚分派、宏等不猜测绑定。

| 插件配置（不是 preview 参数） | 变更模式用途 |
| --- | --- |
| `enableEvidenceContext` | 当前阶段有限正文重新投递 |
| `inlineInteractionRisks` | 适配的交互风险内联 |
| `enableMigrationContracts` | 旧入口→新入口→调用方契约导航 |
| `enableMigrationRegression` | 受宿主契约约束的跨文件旧新复核 |
| `enableGroupInteractions` | 通过真实读取验收后替代匹配交互生成 |
| `enableStageContinuation` | 有界让出／继续及 primary 生成检查点 |

上述六项在正式插件变更入口默认 true，可逐项设 false 回退；底层及直接创建的 service 默认 false。项目模式不启用后四项，仍采用自己的批次、预算和续审协议。额度让出只等待其他阶段释放后有限继续，不抢占活动阶段、不提高根预算、不重置截止或调用账；无进展、取消或超时保留真实 pending／partial。

### 可选模型关系比较与复核取证轮数

`enableModelComparison` 是宿主插件配置，默认 `false`；不能用 preview／execute 参数开启。启用状态绑定预览和续审身份，并在预览及报告披露。角色导航不是源码证据，也不证明接口身份或控制流；缺少关键宏、契约或实现时仍应返回不确定，不为对齐旧报告强制支持。

`maxRetrievalRounds` 默认3。`maxVerificationRetrievalRounds` 可显式设为0至50；未设置时，主审为0则复核也为0，否则复核为 `max(maxRetrievalRounds, 6)`。复核与独立反证复核使用各自有界轮次，但共用原读取调用、输出字节、模型调用及截止预算，不因多阶段重置额度。

整批变更审查的请求验证遥测区分非法格式、未授权来源和越界范围。只有各执行路径均具备观测能力且没有未验证的策略拒绝请求时，才声明完整；缺少自定义子会话观测或取消时保留未知。它不证明模型JSON、缺陷语义或源码无错误，也不回填旧报告计数。

## 规模限制

| 项目 | 默认上限 |
| --- | --- |
| 变更文件 | 200 个 |
| 单文件 | 256 KiB |
| 全部快照 | 4 MiB |
| 额外上下文 | 手动与自动来源共 20 个文件 |
| 单次模型输入 | 生产插件 512 KiB；低层 API 默认 96 KiB |
| 内部时间／总调用次数 | 不设默认截止；遵循宿主与用户取消 |

大变更可按保留原行号的差异窗口分批分析；无法容纳的部分会明确标为未完成。建议先按功能或模块选择一小批文件。详细读取和时间预算见 [开发与发布指南](https://npmcn.com/package/%40feng0531/dsh-code-review/DEVELOPMENT.md)。

## 版本、许可与其他文档

最新安装包见 [npm](https://www.npmjs.com/package/@feng0531/dsh-code-review) 和 [GitHub Releases](https://github.com/f-e-n-g-0531/dsh-code-review/releases)。发布或安装成功不代表真实模型的误报率、漏报率已得到证明。

**许可：非商业源码公开许可证。公司内部商业项目、收费服务和商业交付需要另行取得书面授权。** 详见 [LICENSE](https://npmcn.com/package/%40feng0531/dsh-code-review/LICENSE)。

-   [版本变化](https://npmcn.com/package/%40feng0531/dsh-code-review/CHANGELOG.md)：各版本带来的变化。
-   [本次发布说明](https://npmcn.com/package/%40feng0531/dsh-code-review/RELEASE-NOTES.md)：本版功能与限制。
-   [SVN 支持矩阵](https://npmcn.com/package/%40feng0531/dsh-code-review/SVN-SUPPORT-MATRIX.md)：SVN 具体状态、限制和验证证据。
-   [开发与发布指南](https://npmcn.com/package/%40feng0531/dsh-code-review/DEVELOPMENT.md)：维护者使用的测试、打包与发布流程。
-   [核心能力对照](https://npmcn.com/package/%40feng0531/dsh-code-review/CORE-ALIGNMENT-TASKS.md) / [参考源码对照](https://npmcn.com/package/%40feng0531/dsh-code-review/CORE-SOURCE-INVENTORY.md)：维护计划与参考来源。
-   [评测说明](https://npmcn.com/package/%40feng0531/dsh-code-review/evaluation/README.md)：样本、试跑观察及其限制。

## 常见问题

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

DSH 只读 Git/ SVN 代码审查

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

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

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

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

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

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

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

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

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

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

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

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

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

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