txy-ucas/dsh-workspace-snapshot

dsh-workspace-snapshot

CI
DSH compatibility
Release
License

一个面向 DeepSeek Harness 的、有界的、只读的 Git 工作区状态工具。它添加了一个面向模型的 workspace_snapshot 工具，以经过验证的结构化数据报告分支跟踪状态和相对于仓库的路径状态。

该插件从不暂存文件、切换分支、写入 Git 配置、创建提交或推送。

范围

该插件有意设计为状态探测工具，而非完整的 Git 工作流。它回答哪些路径处于已暂存、未暂存、冲突或未跟踪状态，而不暴露仓库变更操作或文件内容差异。当智能体必须检查更改的行、创建提交或管理分支时，请使用专门的审查或 Git 工作流插件。较窄的范围使该插件在只读部署中保持有用，并与更广泛的 Git 工具互补。

要求

- Node.js ^22.19.0 || >=24.0.0
- DeepSeek Harness 0.1.0-rc.6
- Harness 子进程提供程序的执行环境中可用 Git

该包固定了其测试所针对的确切 Cordis 和 DSH 对等 API 版本。不兼容的 Harness 升级会导致包解析失败，而不是静默加载未经验证的 API 组合。

安装

将预构建的 v0.1.0 版本安装到你使用的配置文件中：

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

该发布 tarball 无需包构建许可。也支持固定版本的源码安装：

dsh plugin --profile web add github:txy-ucas/dsh-workspace-snapshot#v0.1.0

Git 安装会运行该包的 prepare 构建。pnpm 10 或更新版本可能需要在配置文件的 pnpm-workspace.yaml 中添加以下条目，然后重复安装：

allowBuilds:
dsh-workspace-snapshot: true

对于本地开发，请从检出目录的父目录运行以下命令：

dsh plugin --profile web add ./dsh-workspace-snapshot

在不启动 UI 的情况下验证组合：

dsh --profile web --dump-config

输出必须包含 workspace-snapshot 行。

使用

向智能体提问：

Inspect the Git workspace before making changes.

模型可以调用 workspace_snapshot 并收到一个规范对象，例如：

{
"status": "ok",
"repositoryRoot": ".",json
"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": "." },
{ "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
}

每个路径在 entries 中只出现一次。changed 条目会分别给出 Git 索引区和工作区状态字符；rename 和 copy 条目还会带有 originalPath。conflict 条目带有一个经过验证的未合并状态，untracked 条目只带有其路径。

| 字段 | 含义 |
|---|---|
| repositoryRoot | 稳定的 "." 路径基准。每个条目路径和可选的 originalPath 都相对于仓库根目录，不会暴露其宿主机绝对路径。 |
| branch | 当前分支名称，若处于 detached 或未知 HEAD 状态则为 null。 |
| detached | Git 是否报告处于 detached HEAD 状态。 |
| upstream | 跟踪分支，若未配置则为 null。 |
| ahead / behind | 与已配置 upstream 的提交距离。当 Git 报告没有分支比较时，两者均为零。 |
| clean | Git 是否报告没有已跟踪的更改、冲突或未跟踪路径。该工具始终请求未跟踪路径。 |
| entries | 有界的路径记录，通过 kind: changed、conflict 或 untracked 区分。每个路径只出现一次。 |
| totalPaths | 从有界 stdout 中解析出的 Git 路径记录总数。 |
| conflictCount | 冲突路径总数，包括被省略的条目。 |
| stagedCount / unstagedCount | 根据非点号索引区/工作区状态得出的已更改路径总数。一个已更改路径可能同时增加这两个计数。 |
| untrackedCount | 未跟踪路径总数。 |
| omittedPaths | 因 maxPathRecords 或 maxResultBytes 而从 entries 中排除的路径记录数。 |
| truncated | entries 是否不完整。当此值为 true 时，计数字段仍然完整。 |

Native 和 Code Mode 消费者接收相同的规范对象。Native 渲染正是其 JSON 序列化；包含控制字符的路径会进行 JSON 转义。

错误

预期的外部失败会作为结构化值返回，而不是原始异常：
json
{
"status": "error",
"code": "NOT_A_REPOSITORY",
"message": "The session working directory is not inside a Git repository.",
"retryable": false
}

稳定的错误码有 NOT_A_REPOSITORY、GIT_UNAVAILABLE、TIMEOUT、CANCELLED、OUTPUT_LIMIT、INVALID_GIT_OUTPUT 和 GIT_FAILED。原始 stderr、抛出的值和堆栈跟踪永远不会返回给模型。

配置
可安装的 bundle 会以默认值插入该插件。需要时，在 profile 后续的 cordis.patch.yml 层中覆盖完整的行配置：
yaml
- id: workspace-snapshot
config:
timeoutMs: 5000
maxGitStdoutBytes: 262144
maxPathRecords: 500
maxResultBytes: 131072

| 字段 | 默认值 | 约定 |
|---|---:|---|
| timeoutMs | 5000 | 可执行文件查找与状态的共享截止时间，范围为 100 到 120000 毫秒。 |
| maxGitStdoutBytes | 262144 | 保留的 Git stdout 上限，范围为 1024 到 4000000。超出时返回 OUTPUT_LIMIT；部分输出永远不会被解析。 |
| maxPathRecords | 500 | 初始保留在 entries 中的最大路径记录数，范围为 1 到 10000。有界 stdout 中的所有记录仍会计入完整计数。 |
| maxResultBytes | 131072 | 完整规范 JSON 结果的 UTF-8 字节上限，范围为 1024 到 4000000。条目会被整体移除，直到结果能够容纳；JSON 永远不会被截断。 |

配置有意保持扁平。无效的限制值会导致插件加载失败。

安全性与生命周期

- 该插件声明 inject = ['tools', 'subprocess']；Cordis 仅在两个服务都可用时才会激活它。
- 工具注册由 ctx.effect() 管理，并会在 HMR、卸载或卸载安装时消失。
- 每次调用都运行一个固定的只读 argv：git --no-pager --no-optional-locks -c core.fsmonitor=false -c core.untrackedCache=false -c status.relativePaths=false status --porcelain=v2 --branch -z --untracked-files=all。
- Git 通过 ctx.subprocess 运行，绝不使用 node:child_process，因此所选的执行环境 provider 及其进程树清理仍具有权威性。
- 子进程环境会移除所有继承的 GIT_* 值，然后仅设置 GIT_CONFIG_COUNT=0、GIT_OPTIONAL_LOCKS=0 和 LC_ALL=C。环境中的仓库、索引、对象存储和配置注入都无法重定向该查询。
- 可选锁、仓库 FSMonitor 钩子、未跟踪缓存以及相对于 cwd 的状态路径均被显式禁用。任何模型或用户控制的字符串都不会进入 argv。
- NUL 分隔的解析器可处理空格、换行、Unicode 路径以及重命名/复制源路径，无需 shell 引用。
- 解析器要求完整的分支头，并在接受输出前验证记录标签、子模块状态、文件模式、对象 ID、重命名/复制评分和状态枚举。
- 调用方的中止信号和配置的超时会限制可执行文件查找、Git 进程以及完整进程树退出。当后代进程仍存活时，不会接受捕获的 stdout。计时器和信号监听器的所有权在工具 settle 之前结束。
- Git stdout、保留的路径记录和规范结果字节分别受到独立限制。该插件不保留任何缓存、watcher、socket、interval 或跨会话可变状态。
- UI 呈现是一个纯粹的通用读取卡片。面向模型的结果仅从经过验证的规范值派生。

范围与限制

- 不会返回被忽略的路径。
- 子模块状态通过 Git 的 porcelain 状态字段呈现，但不会递归展开。
- Git 可能会读取仓库元数据和工作树路径。该插件禁用了已知的状态时钩子和写入优化；它并不声称 Git 本身不执行任何操作系统读取。
- 快照是时间点信息。在 Git 退出后，另一个进程可能会立即修改仓库。
- 此工具不能替代 git diff、审查工具、权限策略或提交工具。
- DeepSeek Harness 处于开发者预览阶段。确切的对等版本会有意拒绝未经验证的 Harness API；计划兼容性工作流会在 @deepseek-ai/dsh@latest 需要插件更新时进行报告。

卸载
sh
dsh plugin --profile web remove dsh-workspace-snapshot

开发
sh
corepack enable
pnpm install
pnpm run check
node tests/install.e2e.mjs
DSH_VERSION=latest node tests/install.e2e.mjs

该测试套件涵盖严格的 porcelain 头部和记录元数据、路径分类和完整计数、结果字节截断、固定 argv、继承的 Git 环境隔离、真实的 FSMonitor 钩子哨兵、残留进程树超时和取消、结构化外部失败、规范化渲染、Cordis fiber 释放、包构建，以及安装到隔离的 Harness 配置文件中。

许可证

MIT