DSH Code Review
在 DeepSeek Harness（DSH）的 Agent 对话里审查 Git / SVN 代码变更。插件会先列出审查范围，得到确认后，再用当前 Agent 选择的模型生成中文问题报告。
只读：不修改代码，不自动修复，不提交、回滚或更新你的业务工作副本。
快速开始：第一次怎么用
1. 安装并启用插件
在 DSH 插件管理器中安装并启用本项目，或在终端执行：
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
使用 code_review_preview 预览当前仓库所有已跟踪文件的改动。
先告诉我：审查哪个仓库、哪些文件、额外读取哪些上下文、发送给哪个模型，以及哪些文件不能审查。
先不要调用 code_review_execute，等我确认。全程不要修改代码。
这是发在 DSH 对话输入框里的请求，不是终端命令。Git 默认比较 HEAD 与当前工作区的净变化；SVN 默认比较本地 BASE（工作副本记录的基础版本）与当前文件。
预览不调用审查模型，但 Agent 对话本身仍可能使用模型。工作副本模式默认不读 SVN 远端；SVN 历史模式会读取仓库版本，必须另行明确允许远端访问。
4. 检查预览，再确认执行
检查 Agent 展示的：
- 仓库和文件是否选对，有没有遗漏或意外包含的文件。
- 额外上下文是什么；上下文是辅助理解的文件，也可能随执行发送给模型。
- 模型提供方和模型名称是否符合你的数据使用要求。
- 阻断、排除和预算限制；不能审查的文件不能当作已通过。
确认无误后，在同一会话回复：
确认刚才展示的预览范围和模型，使用该 previewId 执行只读审查。
插件使用预览返回的 ID 执行。默认预览有效期约 5 分钟；文件、模型或会话目录变化后，需要重新预览和确认。宿主权限不允许时，确认也不能绕过限制。
5. 查看结果
执行工具会在对话中返回 中文 Markdown 报告，同时返回结构化 JSON。先看“覆盖情况和限制”，再看问题列表，不要只看“发现了几个问题”。
如需保存报告，可以另行告诉 Agent：“将本次报告保存到我指定的位置”。插件本身不会自动在业务仓库创建报告文件。
按场景直接使用
下面的自然语言可以直接发给 Agent。每个场景都应先预览、展示范围，再确认执行。
只审查几个文件（Git / SVN 工作副本）
使用代码审查插件，只预览 src/api.ts 和 src/client.ts 的当前改动。
自动补充理解它们所需的依赖文件。先展示范围和模型，等我确认再执行，不修改代码。
对应 code_review_preview 参数（工具参数，不是 shell 命令）：
{"selectedPaths":["src/api.ts","src/client.ts"],"autoContext":true}
文件名要替换成仓库中实际存在的变更路径。未跟踪文件不会默认纳入，必须用 selectedPaths 显式选择。省略该参数时，范围是整个仓库的变更，不限于当前子目录。
审查 Git 单个提交
使用代码审查插件预览 Git 提交 abc1234，先展示范围，等我确认后再执行。
{"commit":"abc1234"}
将 abc1234 换成实际提交号。与该提交的唯一父提交比较；根提交与空旧版本比较。合并提交请改用两个版本比较，明确选择旧、新端点。
审查 Git 两个版本之间的变化
预览 Git 的 v1.0.0 到 v1.1.0 之间的代码变化，自动读取必要依赖。先展示范围，不直接执行。
{"baseRevision":"v1.0.0","targetRevision":"v1.1.0","autoContext":true}
比较两个版本的文件树，不自动计算合并基点，也不会把工作区中的未提交正文当作历史正文。commit 不能与这两个参数混用。
审查 SVN 单个 revision
例如审查 r7315 引入的净变化，即 r7314 → r7315：
使用代码审查插件预览 SVN r7315（与 r7314 比较）。
允许为这次预览读取当前工作副本对应的远端仓库固定版本。
先展示来源、范围和模型，不发送源码给审查模型，等我确认再执行。不要更新工作副本。
{"svnRevision":"7315","svnAllowNetwork":true}
必须在 SVN 工作副本根目录运行。插件从该工作副本对应的仓库 URL 读取固定版本，不要求先把工作副本更新到 r7315，也不会执行 update。远端认证不可用时会明确报错，不会改用本地文件冒充历史版本。
审查 SVN revision 区间
预览 SVN r7300 到 r7315 两个版本端点的净变化。
允许读取当前工作副本对应远端仓库的固定版本，自动补充同版本依赖。
先展示范围和来源，等我确认后执行，不修改或更新工作副本。
{"svnBaseRevision":"7300","svnTargetRevision":"7315","svnAllowNetwork":true,"autoContext":true}
这是两个版本端点的比较，不是逐一审查区间内的每个提交。revision 使用带引号的十进制数字，不写 r7315、HEAD 或日期；同一路径比较要求旧版本小于新版本；不同分支可使用相同 revision（见下一节）。svnRevision 与区间参数不能同时使用，也不能混用 Git 版本参数。
svnAllowNetwork:true 只允许读取本次工作副本对应仓库的固定版本，不授权更新、合并或任意远端 URL。本地 file: 仓库通常无需此参数。
比较 SVN 两个分支
跨分支、有效继承属性和独立基线替换从正式版 v0.80.1 提供。请先确认当前 DSH 加载的版本；仅更新仓库不会升级宿主插件。
{"svnBaseRevision":"7315","svnTargetRevision":"7315","svnBasePath":"branches/release","svnTargetPath":"trunk","svnAllowNetwork":true,"autoContext":true}
分支路径相对于当前SVN仓库根，不是本地目录或任意URL。旧、新两侧分别固定URL、peg与operative revision；同revision可以比较不同分支。只能在同仓库UUID内比较；嵌套重叠根和不明确来源拒绝，不能推断merge提交归属。
查看有效继承 mergeinfo
{"svnRevision":"7315","svnAllowNetwork":true,"svnEffectiveMergeinfo":true}
显式允许读取选中节点及最近祖先的合并属性，额外读取受共享预算限制；工作副本模式也可使用该开关并保持离线。空属性屏蔽继承，祖先证据不完整、混合BASE或不安全来源显示unknown；结果仅为属性导航，不证明相关revision已经审核。
审查未提交替换
{"selectedPaths":["src/module","src/module/old.cpp","src/module/new.cpp"],"svnReplacementBaseRevision":"7314","svnReplacementAllowNetwork":true}
替换比较的旧侧是你显式选择的目标URL固定历史节点，不是本地BASE，也不证明它就是被删除节点的原始revision。目录后代必须独立选入；只选父目录不能算后代均已批准。远端读取使用独立许可，默认不访问。没有可确认旧来源时明确拒绝，不读取复制源冒充旧节点。
加入业务要求、规则和调用方
只预览 src/api.ts 的改动；业务要求是“请求失败时必须释放连接”。
把 src/types.ts 作为辅助上下文，使用 review-rules.md 的项目规则，
并在 src/clients 目录中寻找引用该变更文件的代码。先展示读取范围，等我确认。
{
"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 两个仓库：
只预览工作区中 project-a 仓库的 src/api.ts 改动，不读取 project-b。先展示范围再等我确认。
{"repositoryPath":"project-a","selectedPaths":["src/api.ts"]}
repositoryPath 相对于会话工作目录，必须指向一个实际仓库根目录；其余文件路径再相对于该仓库。每个仓库分别预览和执行，不使用绝对路径、.. 或链接目录。
长任务：后台预览、审查与取回结果
全项目或慢仓库建议使用后台工具，不让一次外层调用等待整个项目。仍先预览，再由你确认外发；启动返回jobId不等于审核完成。
- 调用code_review_start，phase设为preview，previewArgs填原预览参数（例如reviewMode=project）。
- 用code_review_status和jobId查询；完成后读取resultSummary中的预览范围、模型和previewId。
- 展示预览，确认后调用code_review_start，phase设为execute，传previewId与confirmed=true。
- 持续调用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包含实际加载版本和模块位置，排查不同工作区时分别核对，不根据另一台机器推断。
大文件超出单次输入时按原行号分段。精确差异算不出时使用明确标注的包络，可能包含未变行，不声称精确归因。模型JSON错误会按当前阶段schema请求一次明确纠正，记录额外调用；检索请求非法时整批不执行并明确纠正，回填采用可追溯的滚动工作集、必要时延后重复窗口正文，不虚构证据。默认不按检索轮数中断；不会给错误输出补括号、猜字段或当成无缺陷。
多个会话同时审查
可以同时打开多个DSH Agent会话：会话A审项目A，会话B审项目B，也可以分别审查同一项目。各会话的预览、执行锁、模型路由、取消和预算独立；A正在执行不会让B收到全局busy。一个会话内部仍串行，不能拿另一个会话的previewId执行。宿主停用插件会结束全部服务，单次取消只影响当前请求。
审查整个项目当前代码
在项目仓库根目录创建会话，发送：
使用code_review_preview，全项目模式审查当前已跟踪代码，包括没有改动的文件。
先列出全部文件、排除项和分批范围，告诉我模型和预算；等我确认再执行。不要修改代码。
{"reviewMode":"project"}
这不是HEAD到工作区的差异：模型检查当前已有缺陷，不要求问题由最近提交引入。默认仍是 reviewMode:"changes" 的变更审查。
项目模式只接受reviewMode、repositoryPath和可选selectedPaths，不与历史revision、autoContext、规则或调用方参数混用。默认全部跟踪节点；不读取未跟踪/忽略文件、子模块、外部仓库及链接目标。目录只作清单记录，源码按批次审查；跨批次不宣称完整调用图或全程序语义分析。
清单上限10000节点，单次选择最多1000节点/16MiB，12节点一批，单文件256KiB；超限明确拒绝，缩小选择后必须重新预览。单次采集共享8MiB元数据内存保护，不按命令条数、插件秒表或模型调用次数中断；耗时受宿主/模型提供方限制，用户可随时取消。SVN为本地已观察清单，稀疏/外部/链接及不支持属性显示限制；不证明仓库远端完整覆盖。
对外只交付一份统一最终报告，给出总数、completed、excluded、blocked、pending、去重后的发现及未完成综合阶段；内部批次快照仅供证据追溯，不需要用户拼接报告。completed只表示所选捕获文件已处理，不代表代码正确；排除与阻断从不算完成。代码或清单变化会拒绝旧预览，运行后无法复核则标记outdated。
工具调用流程（给需要精确指定参数的人）
普通使用者只需上面的对话请求，不必手工构造 ID。需要精确控制时，让 Agent 按下列顺序调用：
- 调用
code_review_preview，参数可以是 {} 或上面的 JSON 示例。
- 展示返回的仓库、模型、文件与限制，保留返回的
previewId。此时还没有完成审查。
- 用户确认后，调用
code_review_execute：
{"previewId":"替换为本次预览真实返回的ID","confirmed":true}
不要把示例 ID 原样执行，也不要在 execute 中重新传文件和版本参数。要改范围，重新 preview。reviewRounds 可在预览时指定为 1～3（默认 1），表示独立审查次数，会增加模型调用量，不是模型的思考强度设置。
如何判断报告是否完成
| 状态 | 含义 | 你应该做什么 |
|---|
completed | 相应阶段完成，不表示代码绝对正确 | 阅读问题、复核结果和限制 |
partial | 只完成部分工作 | 检查未完成文件、证据不足或预算限制 |
failed | 执行失败，不是审核通过 | 根据诊断处理后重新预览 |
cancelled | 审查被取消 | 需要时重新发起 |
每个候选问题会保留位置、触发条件、影响和复核结果。复核可能支持、反驳、无法确定或未完成；引用原文匹配也不等于缺陷一定成立。没有发现问题不证明没有缺陷，读取过上下文也不等于审查了整个项目。
常见问题
| 遇到的问题 | 处理方法 |
|---|
| Agent 没有调用代码审查工具，只给了普通文字分析 | 明确要求调用 code_review_preview；若工具不可用，检查插件是否启用并已加载到当前会话 |
| 找不到仓库 / 选错仓库 | 检查会话工作目录；多仓库时用 repositoryPath 指定子仓库根目录 |
| 新文件没有出现 | 用 selectedPaths 显式选择未跟踪文件；路径相对于仓库 |
| 预览过期、文件已变化、模型已变化 | 重新预览，核对新范围后再确认，不复用旧 ID |
| SVN 历史提示需要网络许可 | 确认可以访问仓库后，预览参数增加 svnAllowNetwork:true |
| SVN 登录、权限或版本不存在 | 检查 SVN 本身的访问权限和版本号；不要把密码写进对话或仓库 URL |
| 文件被阻断或报告 partial | 阅读具体原因；缩小变更批次、补充允许的上下文，或处理真实冲突后重新预览。不能把排除文件视为通过 |
| 想审查 Git 暂存区，排除未暂存改动 | 当前没有单独 staged / unstaged 模式；默认是 HEAD 到工作区的净变化 |
支持范围与安全边界
- 执行会把批准范围内的代码、上下文、所选规则及业务要求发送给当前模型提供方；敏感项目请先检查预览和模型。常见凭据路径过滤不能保证源码没有秘密。
- 插件遵循 DSH 工具权限；确认预览不等于绕过宿主权限。不执行项目代码、构建脚本或模型生成的 shell 命令。
- Git 支持工作区、单提交、两版本比较。SVN 支持工作副本和固定历史端点；尚未完整支持所有 SVN 状态。
- SVN 根目录属性可预览；同仓库复制新增以空目标旧侧审查，复制来源只作信息；移动的新增/删除分别覆盖。目录后代须逐项纳入，选择父目录不自动批准所有后代。
- SVN 标准、固定宽度和受支持的复合关键字展开，以及工作副本变更/自动依赖/命中调用方、固定历史变更及上下文的换行元数据保留原文证据；不以规范化结果证明行为等价。自定义/固定宽度关键字、未提交替换、冲突、特殊节点、切换/外部工作副本及跨仓库比较等仍有限制。同仓库跨分支与独立基线替换需要下文列出的显式参数。已提交固定历史替换与未提交替换的支持不同，详见 SVN 支持矩阵。
- 二进制、不能解码的文件、普通源码路径中的链接和超限内容会明确阻断；已跟踪的 SVN 链接只审查
link 目标 记录，不读取目标正文，不静默截断后声称完成。文本导航不证明语义绑定、执行可达或完整调用覆盖。
规模限制
| 项目 | 默认上限 |
|---|
| 变更文件 | 200 个 |
| 单文件 | 256 KiB |
| 全部快照 | 4 MiB |
| 额外上下文 | 手动与自动来源共 20 个文件 |
| 单次模型输入 | 约 96 KiB |
| 内部时间／总调用次数 | 不设默认截止；遵循宿主与用户取消 |
大变更可按保留原行号的差异窗口分批分析；无法容纳的部分会明确标为未完成。建议先按功能或模块选择一小批文件。详细读取和时间预算见 开发与发布指南。
版本、许可与其他文档
最新安装包见 npm 和 GitHub Releases。发布或安装成功不代表真实模型的误报率、漏报率已得到证明。
许可：非商业源码公开许可证。公司内部商业项目、收费服务和商业交付需要另行取得书面授权。 详见 LICENSE。
