前言¶
在 DSH 环境下，智能体常需操作多个 Git 仓库。如果当前工作区与预期的分支不一致，或者与远程存在分歧，后续的提交和推送会导致数据丢失或覆盖。dsh-checkout-guard 是一个 DSH 插件，用于在编辑、提交或推送之前进行预检。它确认当前工作区是否符合预期，防止在错误的状态下进行写入。
插件简介¶
名称：lesliewylie/dsh-checkout-guard
维护者：LeslieWylie
类别：admin-security
许可证：MIT
核心定位：这是一个只读、默认离线的 DSH 插件。它读取 Git 工作区，检查分支身份、与远程的分歧情况、下一个提交将携带的身份、索引中的工作内容，以及同一机器上是否存在其他导致冲突的重复克隆。
安装与启用¶
通过 npm 安装该插件，并在 DSH 的配置文件中启用。
- 安装
npm install dsh-checkout-guard
- 启用
在cordis.yml中添加以下条目：
- id: checkout-guard
name: 'dsh-checkout-guard'
核心功能¶
该插件提供以下检查项，默认为只读模式：
- 分支身份与远程分歧：检查当前分支是否与预期的分支匹配，并计算相对于远程的差异（ahead/behind）。
- 下一个提交身份：验证下一次提交将使用的作者信息（需配合
expectIdentity参数使用）。 - 工作区索引检查：检查索引中是否已存在待提交的工作。
- 重复克隆检测：在同一机器上检测是否有其他仓库克隆了相同的远程，并判断它们是否领先于当前工作区。
- 写入防护：如果上述检查失败，插件会阻止写入操作。
工具使用¶
插件提供了两个主要工具，分别用于单仓库检查和批量扫描。
checkout_guard：检查单个工作区¶
用于检查单个仓库路径的状态。
参数：
* path (必需)：工作区的绝对路径。
* expectBranch：期望所在的分支，不匹配会触发阻断。
* fetch：是否先执行 git fetch 以获取最新的远程状态（默认 false，这是唯一涉及网络操作的功能）。
* expectIdentity：期望的作者邮箱，用于验证提交身份。
返回值：
检查结果包含 safeToWrite 字段。只有当该字段为 true 时才允许写入。其他字段如 blockers 会列出阻止写入的原因，warnings 则提供非阻断性的状态提示。
checkout_guard_scan：批量扫描根目录¶
用于扫描根目录下所有的工作区，并返回概览。
参数：
* roots：要扫描的根目录列表。
* maxDepth：扫描深度。
输出：
返回每个工作区的分支、上游、ahead/behind、未提交数量、fetch 时间等信息，并标记出 needsAttention（需要关注）的仓库和 duplicateRemotes（重复远程）。
安全与注意事项¶
了解插件的边界有助于正确使用。
- 不判断身份：插件本身不会判断你的身份是否正确，除非你显式指定了
expectIdentity。它只会报告作者信息来自哪里。 - 不修复任何问题：插件不会自动拉取、变基或暂存。它只负责报错和阻断。如果发现状态异常，需要手动处理。
- 无写入操作：插件不会向任何仓库写入数据。即使在
fetch: true模式下，也仅执行git fetch --dry-run，不会修改索引或锁文件。 - 避免锁冲突：插件使用
GIT_OPTIONAL_LOCKS=0运行，避免与其他智能体或进程争夺.git/index.lock。 - 不检测远程归档：插件无法通过 API 告知远程仓库是否已被归档。
配置¶
在 cordis.yml 中可以配置插件的作用范围。
- id: checkout-guard
name: 'dsh-checkout-guard'
config:
roots:
- /path/to/projects
roots 参数限定了插件会扫描的目录范围。如果不设置，默认为用户的主目录。
结尾¶
dsh-checkout-guard 作为一个预检工具，通过阻断错误的写入操作，降低了智能体在多仓库环境中因状态误判导致的数据风险。它不承诺解决冲突，但能确保在状态不明时停止操作。
