前言¶
在 Harness 里让智能体改代码、跑命令时，版本历史往往仍要切到终端：看未记录变更、写 change、推远程。Pijul 用 patch 模型做分布式版本控制，和 Git 的工作流不完全相同；若只在对话里用内置 shell 拼 pijul 子命令，还要自己处理非交互、沙箱路径和 beta 版 CLI 的坑。下面介绍社区插件 dsh-pijul（维护者 erkinalp），它在会话沙箱策略下注册十六个工具，封装常见 pijul 操作，返回值统一，便于 agent 串联 status、record、push 等步骤。
这是什么¶
dsh-pijul 是 DeepSeek Harness（DSH）的工作流类插件：通过 harness 的 shell 服务调用本机 pijul CLI，在调用会话的沙箱策略与工作目录内读写仓库。插件自身不发起网络请求；pijul clone、push、pull 仅在你显式调用对应工具时才会连网。
- 仓库：github.com/erkinalp/dsh-pijul
- 社区目录：skillhub.cn/plugins/erkinalp/dsh-pijul
- 许可证：MIT（见仓库
LICENSE） - 当前 package 版本：0.2.0；兼容 DSH
@deepseek-ai/dsh-base>=0.2.0 <0.3.0，Node >=20
实现为纯 ESM 单文件 index.mjs，无构建步骤、零 npm 依赖，符合 DSH 插件规范中的 inject / apply 注入方式。
核心功能：十六个工具¶
安装后，agent 多出下表所列工具（名称与 README 一致）。每个工具返回 { ok, exitCode, timedOut, aborted, stdout, stderr }，界面以紧凑的 [tool] ok/failed 块展示。参数 repo 默认等于会话工作目录，在已有仓库的对话里通常可省略。
| 工具 | 作用 |
|---|---|
pijul_status |
工作副本：当前 channel、未 record 的变更、未跟踪文件 |
pijul_log |
已 record 的变更，新到旧（支持 limit、offset） |
pijul_diff |
未 record 变更的 hunk，可按路径限定 |
pijul_init |
初始化仓库 |
pijul_clone |
从 URL、SSH 目标或本地路径克隆 |
pijul_add |
开始跟踪路径（recursive 可包含目录内容） |
pijul_record |
非交互 record，带提交说明 |
pijul_change |
按 hash 或唯一前缀查看单个 change |
pijul_unrecord |
从当前 channel 撤销 change（Pijul 的 undo） |
pijul_reset |
丢弃工作副本中未 record 的修改 |
pijul_push |
推送到 remote（默认 --all） |
pijul_pull |
从 remote 拉取（默认 --all） |
pijul_remote |
列出、设置默认或删除 remote |
pijul_channel |
列出、创建、切换、删除或 fork channel |
pijul_apply |
将已 record 的 change 应用到当前 channel |
pijul_identity |
列出 pijul 已知的签名 identity |
插件针对 Pijul 1.0.0-beta.x（README 写明在 1.0.0-beta.21 上测过）做了非交互防护：例如 record 即使用 -m 仍可能打开编辑器时，通过把 EDITOR/VISUAL 设为 shell 内置 true 避免挂起；push/pull 默认 all: true；pijul_unrecord 要求至少传入一个 hash；pijul_add 暴露 recursive，避免「只 add 目录本身、不含内容」的默认行为与常见预期不符。
可选配置：若 PATH 上没有 pijul，可在插件配置里用 binary 键指定绝对路径。
环境与前置条件¶
- 安装 pijul 1.0.0-beta.x 并放在 PATH，例如：
cargo install pijul --version 1.0.0-beta.21
- SSH agent 与 pijul identity：pijul 1.0-beta 会对每次 record 签名。README 建议持久化 agent 并加载密钥，插件默认把
SSH_AUTH_SOCK指向~/.ssh/agent.sock：
ssh-agent -a ~/.ssh/agent.sock
ssh-add ~/.ssh/id_ed25519
pijul identity list
pijul identity new default --no-link --display-name "You" --email you@example.com
record 若报 SSH 或 identity 错误，可用 pijul_identity 工具对照排查。
- HTTPS remote：支持 clone 与 pull，不支持 push；推送需 SSH 或本地路径。
安装与启用¶
从 GitHub 安装（纯 ESM，无需 prepare 或 build allowance）：
dsh plugin --profile web add github:erkinalp/dsh-pijul
若希望固定已审计的提交：
dsh plugin --profile web add github:erkinalp/dsh-pijul#<commit-sha>
本地目录或 tarball：
dsh plugin --profile web add ./dsh-pijul
安装后重启 dsh web（或该 profile 对应进程）。用下面命令确认配置层已加载，应能看到 # == dsh-pijul 块：
dsh --profile web --dump-config
安装前建议自行阅读仓库源码与 MIT 许可证；插件命令与内置 bash 工具一样，在当前会话的沙箱策略下执行，对仓库路径的读写受 workspace 范围约束。
典型用法¶
README 中的对话示例（路径与作者信息可按你的环境替换）：
[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
经过上面的步骤，agent 在沙箱内完成 init、递归 add、非交互 record，再用 log 展示最新 change。
权限、兼容与排错¶
权限：命令经 harness shell 服务执行，与内置 bash 工具同一套沙箱；SSH agent 仅用于签名 record，插件不额外连外网。
离线：纯本地仓库时可完全离线使用上述只读/本地写操作；同步 remote 时才依赖网络。
常见现象（摘自 README Troubleshooting）：
| 现象 | 处理方向 |
|---|---|
pijul binary not found on PATH |
安装 pijul 或设置 config.binary |
pijul_record SSH/identity 失败 |
检查 agent、ssh-add、pijul_identity |
Already in a Pijul repository |
目录已是仓库时勿重复 pijul_init |
Refusing to reset, as there are unrecorded changes |
先 pijul_reset 或 record，再切 channel |
sandbox: file access denied |
扩大 workspace 或将仓库移到沙箱允许路径内 |
部分发行版/snap 包在容器内因 XDG_RUNTIME_DIR 只读可能无法运行；README 建议用 cargo install 或 release 二进制。
结尾¶
dsh-pijul 把 Pijul 的日常操作收成十六个 Harness 工具，在会话沙箱内非交互驱动 CLI，适合已在用或评估 Pijul patch 模型、又希望 agent 在对话里完成 record 与同步的开发者。DSH 生态强调「一切皆插件」；SkillHub 目录页 为社区索引，与 DeepSeek / 幻方无官方从属关系。细节与变更以仓库为准：https://github.com/erkinalp/dsh-pijul。
