Jujutsu 版本控制 viztor/dsh-jujutsu

dsh-jujutsu
Jujutsu for DeepSeek Harness让 harness 变成 jj 原生 —— 智能体改用 jj，不再用 Git，而且知道为什么。

在 Jujutsu 工作区里，智能体不再伸手去用 Git，改用 jj —— 而且会被告知原因，不只是被拦住。

- 在会误导的地方拒绝 Git。 在 colocated 仓库里，git status 报出的状态和 jj status 不一样。守卫会拦住这种情况，并回给你该跑的命令。
- 十一个 jj 工具，模型不用开 shell、不用解析输出，就能读写历史。
- 教会模型 jj 是什么：没有暂存区，@ 永远是一个提交，change ID 在改写后依然保留。
- 一个设置面板，就在插件自己的页面上。

在 Jujutsu 工作区之外，插件是隐形的，除非你打开 _Force Jujutsu_（这时它会拒绝 jj，并告诉你该跑哪条 init 命令）。在普通 Git 仓库里，它什么都不做。

安装

从 harness 的 Plugins 页面安装，或者：

dsh plugin install dsh-jujutsu

然后打开 Plugins → Jujutsu 配置。开箱即用，默认值都按安全来选。

要求

| jj | 必需。 0.46.0 或更新版本。brew install jj |
| jj-hunk | 可选。增加 hunk 级别的 split/squash。不装它，这两个工具会报告不可用，而不是直接失败。cargo install --git https://github.com/laulauland/jj-hunk --tag v0.5.1 jj-hunk |
| Node | 24 或更新版本 |

它做什么

拒绝 Git，并告诉你该跑什么

拒绝是翻译出来的，不是套模板：守卫会解析你实际输入的命令，返回它对应的确切 jj 命令。

| 你运行 | 会发生什么 |
| git log --oneline -6 | Refused: git log --oneline -6. Run: jj log -r ::@ --limit 6 --no-graph |
| git diff HEAD~1 | Refused: git diff HEAD~1. Run: jj diff --from @- |
| git push origin main | Refused: git push origin main. Run: jj git push --remote origin --bookmark main |
| git status | Refused: git status. Run: jj status |
| git add src/a.ts | 拒绝，并给出原因而不是命令：没有暂存区可供添加 |
| git status --porcelain | 用目录里的措辞——改变命令的 flag 绝不会被悄悄丢掉 |
| git rebase -i | 拒绝——它需要终端。建议改用 jj rebase、jj squash、jj absorb |
| rm -rf .git | 拒绝，并说明 jj 的提交对象就存在那里 |
| jj status、jj log、… | 正常运行 |
| echo "git commit" | 运行——它根本没碰 Git |

三条规则让翻译结果可以放心粘贴：Git 版本号会改写成 revset（HEAD~2 → @--，因为 HEAD 不是 jj 的 revset）；任何无法精确映射的内容都回退到目录里的措辞，而不是给出半翻译的命令；每个参数都做 shell 引号处理。

读和写分开配置。愿意让模型用 Git 去看的用户，并不因此就同意让它去写。

十一个 jj 工具

| 工具 | 它做什么 |
| jj_status | 工作副本，包括它是否处于冲突状态 |
| jj_log、jj_diff、jj_op_log | 历史、变更和操作日志 |
| jj_new、jj_describe、jj_squash | 开始、描述和折叠变更 |
| jj_bookmark、jj_op_restore | 命名修订；撤销任何操作 |
| jj_hunk_list、jj_hunk_apply | 挑选并应用单个 hunk |

这些工具全部返回结构化 JSON，绝不返回散文。修订用变更 ID 寻址，重写之后它依然有效——提交 ID 做不到这一点。

教会模型

系统提示词会告诉模型：这里的版本控制是 Jujutsu，以及这意味着什么。规则在会失真之处不予下发：纯 Git 仓库里不下发，完全没有仓库的目录里也不下发。

目录里没有版本控制时，插件会说明这一点——这样智能体就能主动提议初始化一个，建议用 jj git init（colocated 模式，Git 工具照常可用）。

纯 Git 仓库可以被有意收编。 打开 _Use Jujutsu in Git repos_，在还没有 .jj 的 Git 仓库里，第一个会话会执行 jj git init --colocate：历史被导入，智能体拿到 jj，而 Git 工具照常工作，因为 .git 没被动过。对于 jj 无法表示的仓库，直接拒绝——LFS（jj 会把原始字节提交上去，覆盖指针）、稀疏检出、浅克隆、链接工作树，以及正在进行的 Git 操作。子模块不构成阻碍：jj 记录 gitlink，把子模块留给 Git，所以你可以在父项目里继续用 jj。见 docs/37。

深度是延后加载的，不是预先付费的。规则和工作区状态随系统提示词一起下发，因为它们必须在模型发出第一条 Git 命令之前就生效；手册——工作副本模型、Git→jj 动词对照表、十一个工具各自返回什么——注册为 jujutsu 运行时技能，所以在模型真正需要之前，它的成本只有一行目录条目。用 _Offer the jj manual_ 关掉它。为什么在这里切分，以及为什么手册不做成 MCP 服务器，见 docs/36。

配置

打开 Plugins → Jujutsu。大部分设置都在这个页面：

| 设置 | 默认值 | 改变什么 |
| Guard | 开 | 关掉后守卫仍然挂载但不起作用——适合看看它_本来会_拦住什么 |
| Read-only Git | ask | 对 git status、git log 等怎么处理 |
| Writing Git | ask | 对 git commit、git push 等怎么处理 |
| Remember approvals | 开 | 本会话内不再重复询问你已经批准过的动词 |
| Mention missing version control | 开 | 目录没有仓库时告诉模型 |
| 优先使用 Jujutsu | 开 | 建议用 jj git init，而不是 git init |
| 在提示词中解释 Jujutsu | 开 | 关闭后，守卫仍会拒绝 Git，但不告诉模型原因 |
| 提供 jj 手册 | 开 | 把 jj 手册作为按需技能提供 |
| 在 Git 仓库中使用 Jujutsu | 关 | 接管普通 Git 仓库，在 .git 旁创建 .jj |
| 强制使用 Jujutsu | 关 | 在工作区之外拒绝 jj，并提示 jj git init --colocate |

进阶：二进制文件从哪里查找

有三项设置不在页面上，因为只有非常规安装才需要它们，展示出来会让其他所有人被迫为它们做决定。改为在配置档的配置里设置——它们就是普通的 Config 字段：

| 设置 | 默认值 | 改变什么 |
| jjPath | jj | 当 jj 不在 PATH 上时设置，或用来固定某个特定构建 |
| jjHunkPath | jj-hunk | 同上，针对 jj-hunk |
| hunkInstall | ask | jj-hunk 缺失时怎么做：ask、never 或 auto |

为单个项目关闭

在项目根目录放一个 .dsh-jujutsu.json：

{ "enabled": false }

从工作目录向上查找，最近的标记生效，所以你可以禁用一个 monorepo，再用 {"enabled": true} 重新启用其中某个 vendored 的 jj 仓库。同一个文件还按项目接受两个选择性开启项——接管用 {"adopt": true} / {"adopt": false}，强制 Jujutsu 用 {"forceJj": true} / {"forceJj": false}——而 {"enabled": false} 会否决这两者。

文件放哪里由你决定——如果这个开关应当只在本地生效，就把它加进 .gitignore；如果想和团队共享这一行为，就提交它。格式错误的标记会被忽略，而不是照办，所以一个笔误不会悄悄禁用守卫。

故障排查

我想要 Git 时却提示「Refused」。 这说明插件在正常工作。把 _Read-only Git_ 或 _Writing Git_ 设为 allow，或者为该项目添加一个 .dsh-jujutsu.json，内容为 {"enabled": false}。

完全没有反应。 插件只在 Jujutsu 工作区内生效——也就是含有 .jj 目录的目录，或它的任意父目录。用 jj status 检查；如果它提示 _"There is no jj repo in '.'"_，说明插件正确地处于未激活状态。jj git init 会创建一个（默认 colocated）。如果你仍想让插件接管这样的目录，打开 _Force Jujutsu_：此后 jj 命令会被拒绝，并给出初始化命令，而不是自行失败。

hunk 工具提示不可用。 jj-hunk 没有安装，或者不在 PATH 上。把 _jj-hunk executable_ 设为绝对路径，或者安装它：

bash
cargo install --git https://github.com/laulauland/jj-hunk --tag v0.5.1 jj-hunk

不要运行 cargo install jj-hunk。 发布到 crates.io 的 crate 是同一个项目，但落后两个小版本，命令行也不一样——它不接受这些工具使用的查询接口。从 crates.io 安装得到的 jj-hunk，每次调用都会报 unexpected argument '--query' found 而失败，用这种方式踩坑实在让人摸不着头脑。插件测试针对的是上面这条锁定 git 版本的安装命令。

jj new 或 jj commit 会被拒绝。 当 jj 没有配置身份时，插件会拒绝创建提交的命令，因为 jj 会创建一个作者为空的提交，而这样的提交无法推送： bash jj config set --user user.name "Your Name" jj config set --user user.email "you@example.com"

会_保留_作者的命令——jj describe、jj squash——不受影响。

面向开发者

本文件其余部分讲的是如何构建和验证插件本身。

构建与测试 bash
pnpm run build # tsc -> lib/ then vp pack -> lib/client.js
pnpm run ci # vp check, build, suite, package checks — the whole gate
pnpm run package-check # just the tarball and release-wiring checks

lib/ 不是可选项，也不提交到仓库。 发布入口是编译产出的 JavaScript，因为 Node 拒绝为 node_modules 下的文件剥离类型（ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING）。这就是为什么插件用 link: 安装能工作，用 tarball 安装却不行：link 解析到工作区，那里允许剥离类型。

两个产物，两种构建方式，因为它们的加载方式不同：

| lib/index.js | 宿主侧。tsc -p tsconfig.build.json，ESM，启用 rewriteRelativeImportExtensions，把源码里的 ./foo.ts 说明符改写成 ./foo.js |
| lib/client.js | 浏览器侧。由 src/client/panel.ts 经 vp pack 打包，CommonJS，包在 window.__ModuleLoader__.load 里 |

客户端侧不能直接用 tsc 输出：Web 客户端不 import 打包产物，而是把它当脚本执行，并把 require 交给工厂函数。这层包装就是 vite.config.ts 里的 banner/footer。路由提供 ${package}/client.js，只接受 /^client\..*\.js$/，所以 scripts/name-client-bundle.ts 会把 vp pack 产出的 client.cjs 改名。

发布不走本地 pnpm publish。registry 条目由 CI 通过 npm 的 OIDC 可信发布创建，因此不需要持有 token，来源证明也自动生成；手动发布的版本会是唯一一个没有来源校验，也没有标签检查。三种触发方式，以及各自需要的一次性设置，都在 CONTRIBUTING.md 里。
bash
npm publish --dry-run # what a publish would upload, from the working tree

目录结构

| src/ | 宿主侧——守卫、工具、提示词、检测。见 src/README.md。 |
| src/client/ | 面板，由 vp pack 构建到 lib/client.js。只用 Harness 原语。 |
| locale/ | 显示名称和一句话简介，按语言分。 |
| SPEC.md | 构建规范。 |
| docs/ | 37 份文档：已验证的契约、测量结果、决策。 |
| research/digest.md | 催生这套设计的对话的长期记录。 |

验证了什么，怎么验证的

关于 Harness 的每条结论都读自 0.2.0-rc.2 源码，并附行号引用（docs/11）；关于 jj 的每条结论都对照已安装的 0.46.0 实测（docs/13）。两份文档都记录了这轮排查没有发现什么，以及还有哪些问题悬而未决。

守卫、十一个工具、提示词注入和面板，都已在真实会话中观察到正常工作。349 个测试，pnpm run ci 通过。

这套东西的来历

设计对话发生在一个 Google AI Mode 会话里，以公开链接分享，再经反爬代理抓取。对话记录没有逐字保留——它带着个人分享链接和一段私人对话。内容被提炼进 research/digest.md，原始抓取已删除。摘要可以公开，那个会话不行。

许可证

MIT——见 LICENSE。