# @feng0531/dsh-vcs 中文文档

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

版本：0\.8\.4
npm 元数据更新时间：2026-11-14T11:24:06.562Z
中文译文更新时间：2026-11-14T14:18:56.006Z
软件包许可：SEE LICENSE IN LICENSE

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

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

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

- 包体积（解压后）：4.1 MB，85 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22\.0\.0
- 运行依赖：1 个
- peer 依赖：@deepseek-ai/dsh 0\.1\.7-rc\.2 \|\| 0\.2\.0-rc\.2 \|\| 0\.2\.1-rc\.2 \|\| 0\.2\.1-rc\.5 \|\| 0\.2\.2-rc\.1 \|\| 0\.2\.2-rc\.3
- 首次发布：2026-09-28T13:03:36.448Z
- 最新版本发布：2026-11-14T11:24:06.398Z
- 近 30 天下载量：4848（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：82（近 12 个月 82 个）

## 中文简介

Git 和 SVN 更改预览, 确认安全的本地 Git 分支切换用于 DSH

## 安装

```sh
npm install @feng0531/dsh-vcs
```

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

## README

# DSH VCS

在 DeepSeek Harness（DSH）Web 中查看 Git / SVN 文件变更和提交历史，**默认只读预览**。

你可以查看差异、浏览历史、追溯文件。已有确认式本地 Git 分支切换会改变 HEAD、暂存区和工作文件。当前冻结源码在 0.7.3 基础上累积了受限整文件／变更块／逐行暂存与取消暂存、commit／amend、从当前 HEAD 创建分支及两类标签、图片叠加／滑动比较和只读分支删除评估，已以 **0.8.0** 收口，不再扩展功能。写操作必须先预览再明确确认，正文比较仍只读；不提供 fetch／pull／push、stash、merge 或冲突解决。

**0.8.2 已正式发布至 npm 与 GitHub。** 修正工作区操作表单挤占差异区；同标签四矩阵完整测试 **3354/3354**、浏览器及五精确宿主合同均通过，公开包字节一致。未更新或重启日常 DSH。最终工件与验证边界见[发布回执](https://github.com/f-e-n-g-0531/dsh-vcs/blob/main/docs/releases/0.8.2-RECEIPT.md)、[本版说明](https://github.com/f-e-n-g-0531/dsh-vcs/blob/main/docs/releases/0.8.2.md)及[当前能力](https://github.com/f-e-n-g-0531/dsh-vcs/blob/main/docs/CURRENT-CAPABILITIES.md)。

-   npm 包：`@feng0531/dsh-vcs`
-   [下载正式版本](https://github.com/f-e-n-g-0531/dsh-vcs/releases/latest) · [查看更新](https://github.com/f-e-n-g-0531/dsh-vcs/blob/main/CHANGELOG.md)
-   采用[非商业许可证](https://npmcn.com/package/%40feng0531/dsh-vcs/LICENSE)，商业用途须另行书面授权。

## 能做什么

| 场景 | 功能 |
| --- | --- |
| 查看工作区变更 | Git 全部、已暂存、未暂存文件；SVN 本地基线与工作副本、属性差异 |
| 阅读代码差异 | 默认 Monaco 只读 Diff，支持并排／行内、换行、忽略行尾空白、上一处／下一处差异 |
| 浏览 Git 历史 | 搜索提交说明、作者、路径与提交时间范围（since/until，含边界，按 committer date）；查看本地分支、提交图、提交详情与目录 |
| 比较历史版本 | 比较提交与选定父提交，或选择两个本地提交进行 A/B 比较 |
| 追溯代码来源 | 文件历史、唯一来源重命名追踪（含改名同时修改）、Blame（逐行查看最后修改者和提交） |
| 搜索与定位 | 在固定提交中分页搜索内容，点击结果定位命中行；高级、基础与分段阅读支持目标行，返回保留结果与阅读设置 |
| 查看其他内容 | 支持部分静态图片并排／叠加／滑动比较与双侧同步缩放；较大历史 UTF-8 文件可分段阅读 |
| 查看 HEAD 移动记录 | Reflog 只读查看最近200项，点击固定提交查看详情；不提供恢复、reset或checkout |
| 浏览 SVN 历史 | 明确同意连接后，查看 HTTPS 仓库日志、修订差异和文件历史 |
| 切换本地 Git 分支（0.6.0 起） | 独立入口预览当前／目标分支与提交，明确确认后执行；不是历史引用导航 |

提供中英文界面。编辑器加载失败时会显示基础文本比较；它不是完整的 Monaco 替代品。

## 安装

需要：

-   Node.js **22 或更新版本**；DSH `0.2.2-rc.3` 本身要求 **24.9.0+**，须同时满足宿主要求。
-   DSH Web：声明兼容 **0.1.7-rc.2、0.2.0-rc.2、0.2.1-rc.2、0.2.1-rc.5、0.2.2-rc.1 或 0.2.2-rc.3**。
-   系统 PATH 中有 Git 或 SVN；只使用 Git 时无需安装 SVN。

profile是DSH的配置和插件环境，不是Session。下面的web是示例，请先确认运行中的DSH使用哪个profile；若不同，替换命令中的web。宿主插件命令通过pnpm执行，需确保该工具可用。

在终端执行：

```
dsh plugin --profile web add "@feng0531/dsh-vcs@<已确认发布到 npm 的版本>"
```

GitHub 与 npm 的可用版本可能不同；例如 0.4.11 仅发布 GitHub。安装前核对目标渠道，候选源码版本不等于已发布版本。

安装后由你自行重启 DSH，再刷新原来的 Web 页面。安装会改变所选 profile；升级前请备份配置。**本项目的发布不会自动升级或重启你的 DSH。**

也可以从 [GitHub Release](https://github.com/f-e-n-g-0531/dsh-vcs/releases/latest) 下载 tgz 和校验文件，核对 SHA-256 后安装：

```
dsh plugin --profile web add "<tgz 的绝对路径>"
```

升级、旧包迁移和回滚见[安装指南](https://github.com/f-e-n-g-0531/dsh-vcs/blob/main/docs/INSTALL.md)。

## 更新与免重启加载

VCS 顶部“更新插件”提供更新检查、宿主插件管理器与最新发布链接。明确勾选确认后，更新按钮会委托宿主安装指定正式版本，修改当前插件环境；不会自动重启，缺少宿主更新接口时改用插件管理器。安装新版后点击“检查并加载已安装更新”：后端指纹一致才重新挂载前端，否则提示自行重启 DSH。第一次引入此功能需要重启一次。后端、依赖锁、加载器、字典或编辑器资源变化均需重启。加载失败保留旧版或显示恢复操作，不自动重启。

## 开始使用

1.  在 DSH 中选择一个 Session，确认它的工作目录在项目内。
2.  打开 VCS 页面，发现仓库，再从顶部下拉框选择仓库。
3.  点击文件查看差异，或进入历史视图浏览提交。
4.  SVN远程历史需先审阅并明确同意。复制成员可主动查看范围内的固定来源历史，不自动跨复制追溯。
5.  外部工具修改了项目后，手动刷新；可见窗口重新获得焦点时也会刷新。没有定时轮询。

默认发现当前目录、一级子目录以及包含当前目录的上级仓库。项目更深时，输入相对 Session 目录的子目录，例如 `packages/example`；不接受任意绝对路径或越界路径。

**注意：Session 位于仓库子目录时，发现后的查看范围可以覆盖整个仓库。**

### 左右两侧比较的是什么

| 模式 | 左侧 | 右侧 |
| --- | --- | --- |
| Git 全部 | 最近提交（HEAD） | 当前工作区 |
| Git 已暂存 | 最近提交（HEAD） | 暂存区（Index） |
| Git 未暂存 | 暂存区（Index） | 当前工作区 |
| SVN 本地变更 | 本地基线（BASE） | 当前工作副本 |

新增文件可能使用空白左侧。冲突文件只供查看，不提供三方合并或冲突解决。

### 确认式本地 Git 分支切换

历史页的分支下拉只改变阅读起点，**不会切换工作区**。实际切换使用独立的“切换本地分支”入口：先读取已有本地分支，选择目标并预览当前／目标完整引用及提交，再明确确认。预览约 60 秒失效，确认仅能使用一次；取消预览不执行切换，切换过程中不能重复提交。

仅支持已有的本地 `refs/heads` 分支和干净、普通的 Git 工作副本。已暂存、未暂存、未跟踪以及**被忽略的文件**都会阻止操作；不会自动保存、stash、强制覆盖、创建分支或连接远端。配置了过滤器或命令 hooks、存在 Git attributes、稀疏／部分克隆、assume-unchanged／skip-worktree、符号链接／子模块、未完成的合并／变基等操作或锁时也会保守拒绝。Git 元数据或工作路径硬链接（含本地克隆共享的对象文件）、元数据符号链接／alternates、linked worktree、分离／符号链接的 Git 元数据目录、`core.worktree`、detached／未创建首个提交的 HEAD，以及与目标分支同名的 tag 均不支持；目标被其他 worktree 占用时不绕过 Git 的拒绝。

确认前重新检查仓库和分支状态，但不保证与其他 Git 工具之间的原子隔离。写入已开始后取消、超时或失败可能表示**结果未知**，不能当作已回滚；先手动刷新并核对当前分支、暂存区和工作文件，不要盲目重试。成功后界面重新发现并刷新仓库。

### SVN 历史需要单独同意

本地 SVN 变更比较不连接服务器。打开远程历史前，需要审阅服务器与路径范围并勾选同意；授权约 5 分钟后过期，须重新手动同意。

目前仅支持系统信任、**无需额外认证的 HTTPS SVN 服务**。不提供用户名／密码、自定义证书或其他协议。历史范围固定在本地工作副本的修订，不自动获取服务器最新版本。

## 候选：确认式单文件取消暂存

在Git“已暂存”模式选中普通修改文件后，使用“取消暂存”预览，核对路径、固定HEAD、原Index与目标OID／模式，再勾选确认。它只恢复该文件的Index条目，不改工作文件或其他暂存内容；不是逐行取消暂存，不执行reset。

只支持工作字节仍等于Index的既有普通文件，拒绝选中MM、增删改名、冲突、unborn／detached、linked worktree、特殊Index、attributes／filters／hooks及扫描到的链接／硬链接。工作区含ignored／untracked也会扫描，每文件2MiB、总正文16MiB、最多2万节点，超限拒绝。过期或状态变化须重新预览；确认失败／取消可能结果未知，先点击恢复入口刷新核对，不自动重试或回滚。源码与隔离测试不等于正式发布或当前GUI已更新。

## 候选：确认式单文件暂存

Git“未暂存”模式选择普通修改文件后，预览原Index与捕获字节对应的目标OID，勾选并确认。仅支持Index仍等于固定HEAD的既有文件，不支持所选MM／增删改名／冲突和内容转换；工作树扫描与取消暂存同样受限。浏览器不发送正文或路径，确认仅用一次性token。

Stage先追加已确认原始字节的blob，再CAS发布Index。取消／失败可能留下不可达blob，即使Index未改变也不能保证整个仓库毫无副作用；不会删除对象或GC回滚。结果未知时stage和unstage共用该仓库恢复门禁，显式刷新核对后再操作。

## 候选：按完整变更块暂存

Git“未暂存”模式选中支持的普通文件后，读取精确块计划，勾选完整变更块，先生成候选预览，再核对并明确确认。计划和选择预览都只读；选择后重新修改勾选须重新获取计划。每侧最多256KiB、4000原始行及20万精确LCS格，显示真实换行标记，无近似写入。

此入口按原子块选择，块内逐行使用下方独立入口；支持MM文件连续选择剩余块（按当前Index→Work，不重放HEAD差异）；整文件stage／unstage仍拒绝MM。二进制／非UTF8、新增／删除／改名／冲突仍不支持；候选部分unstage见下文。工作文件保留所有修改，Index仅选中块；确认后取消的append-only副作用及恢复门禁与单文件stage一致。

## 候选：按恢复块部分取消暂存

Git“已暂存”模式选中支持的M-space／MM文件后，读取Index→HEAD恢复计划。只撤回勾选的暂存块，其余暂存与全部工作修改保持。选择预览后核对候选OID，再独立确认；不是丢弃工作修改，不运行reset／checkout。

每端256KiB／4000原始行／20万精确格，UTF8保留原始换行，原子块不可拆成任意逐行。计划／预览只读，确认可追加合成blob，取消后不保证对象不存在，不GC回滚。与其他Index操作共用pending／unknown门禁。

## 候选：块内逐行选择

精确逐行暂存（Index→Work）与逐行取消暂存（Index→HEAD）为每条删除／插入分别提供选择。未选旧行保留，选中目标行按目标序位于块内保留行之后；删除与插入不自动配对。先生成只读候选OID预览，再独立确认；工作文件不改。

每输入及候选256KiB／4000行、精确LCS20万格、最多8000行操作。会合并原始行边界的EOF／CR-LF组合拒绝，不补换行。其余受限MM／仓库guard／append-only孤立对象及恢复门禁不变，不代表支持所有Git文件类型或配置。

## 候选：显式提交预览与确认

Git已暂存模式可显式填写author／committer姓名邮箱、秒级时间／时区与消息，读取只读预览，核对父HEAD／分支、新tree／commit OID和原文，再独立确认一次token。内容仅来自完整Index，不自动暂存、不amend、不push，工作文件保留。

初期仅支持已出生loose本地分支及既有reflog、普通stage0 Index、严格配置子集。initial／signed／hooks／packedrefs／shared-worktree／属性转换等拒绝，非一般Git提交兼容。提交作者与固定machine reflog审计身份不同；外部Git竞争不提供跨Index／ref全局原子性。确认中断需核对HEAD和Index，可能留下仅追加对象，不自动重试或回滚。

## 候选：最近提交消息复用

提交编辑器可显式读取最近HEAD的身份和原始消息。读取不会改草稿，点击复用才仅复制消息原文，不自动替换作者／提交者。复用立即作废旧预览，必须重新核对并确认；不是amend。CRLF／BOM／EOF状态保留，不支持的写入消息明确拒绝而不自动转换。

## 候选：Amend历史替换

独立amend编辑器显式填写提交者与消息，预览旧HEAD／旧tree、保留原作者和父列表，以及新tree／commitOID，再单独确认历史替换。支持受限same-tree消息修改，不自动stage、push或force。签名／hooks／packedrefs等当前严格拒绝，外部Git竞争不保证跨Index／ref全局原子。

## 候选：从当前HEAD创建分支

创建编辑器仅填写安全短名，预览服务器固定的HEAD起点／完整ref／当前分支后明确确认。创建不覆盖已有目标，不自动checkout、stage、commit或push；修改名称使旧预览失效，结果未知先核对refs和HEAD，不自动重试或删分支。当前严格Git子集和外部竞争限制保持。

## 候选：删除分支只读评估

输入短名可只读核对当前／目标tip和已合并祖先证明，明确不执行删除。无删除确认按钮、token或force入口；未合并／不完整历史／超限明确拒绝。评估不是未来删除授权，实际删除仍未开放。

## 候选：当前HEAD的annotated tag

显式填写短tag名、tagger和消息，先核对服务器固定HEAD、完整refs/tags和tag对象OID，再勾选单次确认。不覆盖已有标签，不签名、push或checkout；未知结果先核对引用和对象，不自动重试或删除。此入口仅支持严格 unsigned annotated 子集，不含任意起点；lightweight tag 使用下方独立入口。

## 候选：当前HEAD的lightweight tag

仅填写短tag名，核对固定HEAD和完整refs/tags后单次确认，引用直接指向commit，不生成annotated对象、不需要tagger或消息。与附注标签分开展示与授权；不覆盖、签名、push或checkout。未知结果先核对refs和HEAD，不自动重试或删除。

## 目前的限制

-   **不是完整的 Fork 客户端**：上述写入口均限严格 Git 子集，逐行选择仅限精确模型与受支持文件；分支删除仅只读评估，不执行删除。仍缺少远端 fetch／pull／push、stash、merge／rebase 与冲突解决，不提供 force。历史图和列表都有容量限制；历史分支导航可使用本地分支、标签及本地缓存的远程跟踪引用，不连接远端。
-   普通文本比较每侧最多 **2MiB**。Git提交／A-B／工作区三个模式比较超限时可手动加载完整文本（UTF-8／GBK／带BOM的UTF-16），每侧最多 **8MiB、10万行**，单行最多65536字符；计算超时会明确提示结果不完整。工作区读取期间发生变化会拒绝结果，但不是系统级原子快照；SVN大文件仍不支持。
-   内容搜索每页最多100条匹配，扫描最多64个文件／16MiB正文，匹配列表最多1MiB；固定提交树上限10万项／16MiB。超过16MiB的文件跳过并提示结果不完整，二进制排除；无匹配的扫描页仍可能有下一页。长命中行仅显示开头片段，打开文件可继续阅读。
-   历史 UTF-8 正文分段最多 **16MiB**，每片64KiB；按全局行号定位，行片段有明确提示；基础单版本阅读每窗口最多500行。分段阅读不是完整 Diff。正文按固定对象缓存，最多 32MiB／8 项／60 秒，缓存命中仍重新验证请求授权。历史目录按需分页，每页最多 100 项，单目录仍有 10 万项和 16MiB 命令输出上限。
-   重命名追溯仅沿第一父链，至少50%相似且确认唯一删除源／新增目标；合并、复制、歧义或累计32次确认后停止。
-   子模块变更只显示 Index 记录的提交指针与本地检出状态（已检出／未初始化／目录缺失／不可读）；不进入子模块、不读取其 HEAD，也不更新或同步。
-   树浏览和来源行预览可手动查看该历史路径的文件历史，并可选跟随重命名；路径必须存在于所选提交，跟随规则与路径历史一致（第一父链、≥50%相似、唯一确认、32次上限）。
-   冲突文件可额外手动查看 Git Index 阶段1／2／3，任意两阶段可只读比较。缺失阶段显示为空、不推断原内容；阶段编号不声称合并／变基归属。每阶段仍为 2MiB 预览；不读取工作文件、不解决冲突，子模块只显示提交引用，链接只显示目标文本。
-   图片支持 PNG、基线/渐进 JPEG 和简单静态 VP8／无损VP8L WebP；动画、扩展 WebP、算术编码/CMYK JPEG 等不支持。
-   支持 UTF-8、GBK、带 BOM 的 UTF-16；不是通用编码检测器。
-   本地读取整次请求默认最多 15 秒，子命令共享剩余预算；取消或超时会终止子进程树并等待清理，不保证立即完成。操作系统拒绝终止时仍可能延迟。

## 常见问题

-   **找不到仓库**：检查 Session 工作目录和 Git／SVN 的 PATH；更深项目使用相对子目录发现。
-   **提示重新发现**：目录变了或发现授权过期，手动重新发现即可。
-   **高级编辑器加载失败**：确认安装了完整正式包并重新加载宿主；失败时仍可使用基础比较。
-   **SVN 历史连接失败**：先确认是受信任 HTTPS 服务，且不要求本插件未支持的额外认证。

正式发布要求通过同标签自动测试、Windows／Linux 检查、隔离浏览器和精确宿主合同等门禁。**0.8.2 已通过全部门禁并核验公开包；0.8.1 未通过完整浏览器门禁、未发布且标签保留。** 发布不证明当前 DSH 页面已加载新版，本次不安装、升级或重启日常 GUI／profile。

## 开发与更多资料

[文档导航](https://github.com/f-e-n-g-0531/dsh-vcs/blob/main/docs/README.md) · [贡献指南](https://github.com/f-e-n-g-0531/dsh-vcs/blob/main/CONTRIBUTING.md) · [安全说明](https://github.com/f-e-n-g-0531/dsh-vcs/blob/main/SECURITY.md) · [维护者发布流程](https://npmcn.com/package/%40feng0531/dsh-vcs/docs/RELEASING.md)

界面设计参考 [Fork](https://fork.dev/)，不代表与 Fork 官方有关联或获得背书。

## 常见问题

### @feng0531/dsh-vcs 是什么？

Git 和 SVN 更改预览, 确认安全的本地 Git 分支切换用于 DSH

### 如何安装 @feng0531/dsh-vcs？

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

### @feng0531/dsh-vcs 支持 TypeScript 吗？

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

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

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

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

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

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

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

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

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

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

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