dsh-workspace-snapshot：DeepSeek Harness 的只读 Git 工作区探针

在 DeepSeek Harness (DSH) 的开发实践中，让 AI Agent 在修改代码前检查当前 Git 状态是一个常见需求。现有的 Git 工具往往功能过于复杂，或者不仅限于“检查”功能，容易导致 Agent 误执行提交或切换分支等破坏性操作。dsh-workspace-snapshot 提供了一个受控的、只读的解决方案。

功能定位¶

dsh-workspace-snapshot 是 DeepSeek Harness 的一个客户端插件，由 txy-ucas 维护。它通过向模型暴露一个 workspace_snapshot 工具，将 Git 工作区的状态（如分支、跟踪状态、文件变更分类）报告为经过验证的结构化数据。这是一个“探针”而非完整的工作流，其核心价值在于安全地读取状态。

核心能力¶

该插件主要提供以下能力：

只读状态报告：通过 ctx.subprocess 运行 Git 命令，报告当前分支、跟踪分支、ahead/behind 数量、detached HEAD 状态以及工作区是否干净。
路径分类：明确区分路径的类型，包括：
- changed：有变更的文件，细分为 indexStatus（暂存区状态）和 worktreeStatus（工作区状态）。
- conflict：存在合并冲突的文件。
- untracked：未被跟踪的新文件。
严格的操作限制：插件声明了只读权限，实际上：
- 永远不会暂存文件。
- 永远不会切换分支。
- 永远不会写入 Git 配置。
- 永远不会创建提交或推送。
- 默认禁用了 Git 的锁、FSMonitor 和 untracked cache，以确保查询结果不受环境干扰。
结构化输出：返回的 JSON 对象包含完整的统计信息（stagedCount, unstagedCount, untrackedCount 等）以及路径条目，且路径均为相对于仓库根目录的，不暴露绝对路径。

安装与启用¶

安装前请确保环境满足依赖要求：Node.js ^22.19.0 || >=24.0.0 和 DeepSeek Harness 0.1.0-rc.6。

使用官方预构建包安装：

dsh plugin --profile web add https://github.com/txy-ucas/dsh-workspace-snapshot/releases/download/v0.1.0/dsh-workspace-snapshot-0.1.0.tgz

安装后，可以通过以下命令验证插件是否正确加载：

dsh --profile web --dump-config

输出中应包含 workspace-snapshot 配置行。

典型用法¶

Agent 在收到指令后，可以调用 workspace_snapshot 工具。例如，Agent 收到的指令如下：

Inspect the Git workspace before making changes.

工具返回的 canonical 对象示例如下：

{
  "status": "ok",
  "repositoryRoot": ".",
  "branch": "feature/status-tool",
  "detached": false,
  "upstream": "origin/feature/status-tool",
  "ahead": 2,
  "behind": 0,
  "clean": false,
  "entries": [
    {
      "kind": "changed",
      "path": "src/index.ts",
      "indexStatus": "M",
      "worktreeStatus": "M"
    },
    {
      "kind": "changed",
      "path": "README.md",
      "indexStatus": ".",
      "worktreeStatus": "M"
    },
    {
      "kind": "untracked",
      "path": "notes.txt"
    }
  ],
  "totalPaths": 3,
  "conflictCount": 0,
  "stagedCount": 1,
  "unstagedCount": 1,
  "untrackedCount": 1,
  "omittedPaths": 0,
  "truncated": false
}

配置项¶

插件安装后使用默认配置。如果需要调整，可以在 --profile web 的配置文件中覆盖：

- id: workspace-snapshot
  config:
    timeoutMs: 5000
    maxGitStdoutBytes: 262144
    maxPathRecords: 500
    maxResultBytes: 131072

配置项说明如下：

字段	默认值	说明
`timeoutMs`	`5000`	Git 命令执行的超时时间，范围 100 - 120000 ms。
`maxGitStdoutBytes`	`262144`	Git 输出字节上限，范围 1024 - 4000000。超出会返回 `OUTPUT_LIMIT`。
`maxPathRecords`	`500`	内存中保留的路径记录上限，范围 1 - 10000。
`maxResultBytes`	`131072`	最终返回的 JSON 结果字节上限，范围 1024 - 4000000。

注意：配置是扁平的，且如果设置无效的限制，插件将无法加载。

适用场景与注意事项¶

适用场景：适合需要 Agent 评估当前代码库状态（如是否有冲突、未提交更改）的场景，特别是在只读部署环境中。
使用限制：这是一个探针工具，不是完整的工作流。如果 Agent 需要检查具体变更的行内容、创建提交或管理分支，应使用专门的 Git 工作流或审查插件。
安全性：插件通过 inject = ['tools', 'subprocess'] 声明依赖，仅当 Cordis 的这两个服务同时可用时才会激活。子进程环境清除了所有 GIT_* 环境变量，确保查询结果不受用户或模型控制的环境变量影响。
来源核查：安装前建议查看源码与许可证。该插件使用 MIT 许可证，并在 GitHub 上提供维护。

dsh-workspace-snapshot 提供了一种安全、受控的方式来让 Agent 获取 Git 工作区的只读快照，是构建健壮智能体工作流的有力补充。