Pijul 版本控制 erkinalp/dsh-pijul

dsh-pijul

在 DeepSeek Harness 里使用 Pijul 分布式版本控制——不用离开聊天，就能查看、记录、切换频道、推送和拉取。

安装后有哪些变化

智能体多了十六个工具，通过 harness 的 shell 服务调用 pijul 命令行，受调用会话既有的沙箱策略和工作目录约束：

| 工具 | 作用 |
| pijul_status | 工作副本状态：当前频道、未记录的改动、未跟踪的文件 |
| pijul_log | 已记录的改动，最新的在前（limit、offset） |
| pijul_diff | 以 hunk 形式展示未记录的改动，可限定到指定路径 |
| pijul_init | 创建仓库 |
| pijul_clone | 从 URL、SSH 目标或本地路径克隆 |
| pijul_add | 开始跟踪路径（recursive 会包含目录内容） |
| pijul_record | 以非交互方式记录改动，附带提交信息 |
| pijul_change | 按哈希或无歧义前缀查看单个改动 |
| pijul_unrecord | 从当前频道丢弃改动——Pijul 的撤销 |
| pijul_reset | 丢弃工作副本中未记录的改动 |
| pijul_push | 推送到远程（默认 --all） |
| pijul_pull | 从远程拉取（默认 --all） |
| pijul_remote | 列出远程、设置默认远程、删除远程 |
| pijul_channel | 列出、创建、切换、删除或分叉频道 |
| pijul_apply | 把已记录的改动应用到当前频道 |
| pijul_identity | 列出 pijul 已知的签名身份 |

每个工具都返回 { ok, exitCode, timedOut, aborted, stdout, stderr }，并渲染成紧凑的 [tool] ok/failed 块。repo 默认取会话工作目录，所以在仓库聊天里可以省略。

环境要求

- PATH 上有 Pijul 1.0.0-beta.x（已针对 1.0.0-beta.21 测试），例如 cargo install pijul --version 1.0.0-beta.21。也可以通过插件的 binary 配置键固定绝对路径。
- 一个持有签名密钥的 SSH agent，外加一个 pijul 身份。 pijul 1.0-beta 会用 agent 里的密钥给每次记录的改动签名。一次性设置：

ssh-agent -a ~/.ssh/agent.sock # persistent agent; the plugin defaults SSH_AUTH_SOCK here
ssh-add ~/.ssh/id_ed25519 # your signing key
pijul identity list # an identity already exists? done.
pijul identity new default --no-link --display-name "You" --email you@example.com

每条命令都在 SSH_AUTH_SOCK="${SSH_AUTH_SOCK:-$HOME/.ssh/agent.sock}" 下运行，所以只要该 socket 上有常驻 agent，记录功能在 harness 重启后依然可用。出问题时用 pijul_identity 排查。

安装

从 GitHub 安装——仓库是纯 ESM，没有构建步骤，所以用 git 安装不需要 prepare 脚本，也不需要构建许可：

dsh plugin --profile web add github:erkinalp/dsh-pijul

想让你审计过的代码就是实际运行的代码，就锁定 commit：

dsh plugin --profile web add github:erkinalp/dsh-pijul#<commit-sha>

从本地检出或打包好的 tarball 安装：

dsh plugin --profile web add ./dsh-pijul

之后重启 dsh web（或该配置档的进程）。用 dsh --profile web --dump-config 确认这一层已加载——它会显示一个 # == dsh-pijul 块。

示例

[user] put these three files under pijul, commit, and show me the change
[agent] pijul_init {path: "notebook"} → ok
pijul_add {repo: "notebook", paths: ["."], recursive: true} → ok
pijul_record{repo: "notebook", message: "initial import",
author: "You <you@example.com>"} → ok
[pijul_log] Change XXKRZNVTIP3J637PCAZXHI32FAFNIZUKJKBQFCJQUP6NBTVA763AC
Author: You <you@example.com> Date: 2026-08-20 21:47:59 (+03)
initial import

非交互

pijul 命令一旦打开编辑器，就不只是让智能体失败——它会卡住工具，直到 shell 超时。插件在设计上杜绝了这种情况，而它必须防住的两个场景，是探测 1.0.0-beta.21 时发现的：

| pijul 行为 | 插件如何处理 |
| pijul record <paths> -m <msg> 即使给了 -m 也会打开提交信息编辑器（任何参数顺序都如此） | 命令前导把 EDITOR/VISUAL 导出为 shell 内建命令 true，即空操作。pijul 于是接受它已经写好的模板——也就是 -m 的信息——不再等待编辑器。 |
| pijul push / pijul pull 不带 --all 会打开编辑器挑选变更 | --all 是默认值，同一个空操作编辑器让显式 all: false 这条逃生通道安全，而不是挂起。 |
| pijul unrecord 不带 hash 会显示交互式选择 | pijul_unrecord 要求至少一个 hash。 |
| pijul add . 只记录目录本身，不记录其内容 | pijul_add 暴露 recursive（对应 pijul --recursive）；工具描述里写明了这点，因为「全部添加」才是常见意图。 |

插件从不弹出提示，也从不留下附着在终端上的进程。

权限与兼容性

- 权限：命令通过 harness 的 shell 服务运行，遵循调用会话当前的沙箱策略——与内置 bash 工具同样的隔离。仓库在会话工作区内读写；SSH agent 只用于给已记录的变更签名。插件自身不发起网络调用：只有你调用 pijul clone/push/pull 时才会联网。
- 外部服务：无。本地仓库完全离线。
- 兼容性：基于 @deepseek-ai/dsh-base 构建的 DeepSeek Harness 配置档（DSH >=0.2.0 <0.3.0）。它使用 tools、shell 和 systemPrompt，并在配置档提供时读取 sandboxPolicy、shellEnv 和 workingDirectory。pijul 1.0.0-beta.x。
- HTTPS 远程支持 clone 和 pull，不支持 push；要 push 请用 SSH 或本地路径。

故障排查

| 现象 | 原因与修复 |
| pijul binary not found on PATH | 安装 pijul，或在 pijul 行把 config.binary 设为绝对路径。 |
| pijul_record 报 SSH 或身份错误 | 记录操作需要签名。运行 pijul_identity；在 ~/.ssh/agent.sock 启动 agent，并用 ssh-add 添加你的密钥（见环境要求）。 |
| Error: Already in a Pijul repository | 对已经存有仓库的目录执行 pijul_init。这是 pijul 报错，退出码 1，不是空操作。 |
| Refusing to reset, as there are unrecorded changes | 切换通道前先执行 pijul_reset，或先把改动记录下来。 |
| 工具报 sandbox: file access denied | 会话的沙箱策略管辖仓库路径；扩大工作区，或把仓库移到工作区内。 |

在某些系统上，发行版/snap 的 pijul 包无法在容器内运行，因为它把 XDG_RUNTIME_DIR 硬编码在只读的 /run 下；用普通二进制（cargo install 或发布版 tarball）更可靠。

开发

纯 ESM，无构建步骤，零依赖：index.mjs 没有任何 import，按 DeepSeek Harness 插件规范导出 name、inject 和 apply(ctx, config)。工具定义是普通对象，JSON Schema 手工转换，所以 ctx.tools.register 无需 @deepseek-ai/dsh-tools 也能接受它们。

这是有意为之。pnpm 链接的 bundle 里，裸 import 会从 checkout 的真实路径解析，而不是配置档的 node_modules，还可能被后续的 dsh plugin add 清理掉；零依赖插件则永远不会 import 失败。

npm test # unit + integration (node:test, no install step)
npm run test:unit # 34 tests, no pijul required
npm run test:integration # drives the real pijul CLI; self-skips when absent

单元测试用一个桩构建插件，桩模拟真实服务的形状——ctx.tools.register、ctx.systemPrompt.section、ctx.shell.resolve → ctx.shell.execute → result()，以及用于可选服务的 ctx.get——所以 shell 接缝处的回归会在这里失败，而不是在聊天里。集成测试在真实 bash 中、对真实仓库运行插件生成的原样命令字符串。

bundle 清单在 package.json（dsh.bundle → cordis.patch.yml），它把 pijul 行插入配置档组合。binary 配置键从行配置中按普通值读取：

- id: pijul
name: dsh-pijul
config:
binary: /usr/local/bin/pijul

发布历史见 CHANGELOG.md。

许可证

MIT © Erkin Alp Güney