rbviz/dsh-plugin-jules

dsh-plugin-jules

CI
npm

将 Google Jules 作为 DeepSeek Harness 的一项能力。

Jules 是一个远程编码代理：你给它一个任务和一个仓库，它便在 Google 的云中异步地在其自己的克隆上工作——规划、编辑文件、运行命令，并打开一个拉取请求。本插件将该代理封装在十个 jules_ 工具之后，因此 harness 模型可以移交长时间运行的工作、跟踪它、批准其计划、回复它，并取回 diff。

它直接与文档化的 Jules v1alpha REST API 通信，并且没有运行时依赖。

它为你带来什么

- 超越单轮对话的委派。 jules_create 立即返回一个会话 id；无论是否有任何东西在监听，工作都会在云中继续进行。
- 通知而非轮询。 jules_watch 注册一个后台监视，harness 会投递完成通知，因此模型会结束其回合，而不是在状态检查上循环。
- 计划审查。 requirePlanApproval 真正地控制编辑，而 jules_approve_plan 在你阅读计划后放行它们。
- 可用的结果。 jules_patch 返回统一 diff——对于大型 diff 会分页，并附有所有被触及文件的列表——可直接用于 git apply。

要求

- DeepSeek Harness，带有基于 base 的 profile（base 包提供 tools、systemPrompt、jobs，以及本插件使用的存储栈）。
- Node 22 或更高版本。
- 一个 Jules 账户，且至少有一个仓库通过 Jules GitHub App 连接。
- 一个 Jules API 密钥：https://jules.google.com/settings。Jules 每个账户允许三个密钥，并且每个密钥只显示一次。

安装

该包声明了 dsh.bundle，因此它作为普通 profile 包安装。dsh plugin 将其参数转发给 profile 目录中的 pnpm，因此 add、update 和 remove 就是普通的动词。如果该 profile 尚不存在，第一条命令会创建它。

从 npm 安装

dsh plugin --profile  add dsh-plugin-jules

你的机器上不会编译任何东西：lib/ 以预构建形式发布，因此没有 prepare 脚本，也没有需要授予的 allowBuilds 权限。@deepseek-ai/ 对等依赖来自 harness 安装自身的模块回退，因此没有其他需要安装的东西——本插件不添加自己的运行时依赖。

重启 harness。 正在运行的进程会保持它启动时的包集合；add、update 或 remove 会在下次启动时被采用。然后确认该层已组合：

dsh --profile  --dump-config | grep -A 3 'id: jules'

升级和移除是相同的透传，各自后跟相同的重启：

sh
dsh plugin --profile  update dsh-plugin-jules
dsh plugin --profile  remove dsh-plugin-jules

从检出目录安装

要运行你自己从源码构建的版本：
sh
node scripts/link-dsh-deps.mjs   # 执行一次，并在更改 peerDependencies 之后再次执行
npm run build                    # 将 src/ 编译到 lib/

dsh plugin --profile  add /path/to/jules-plugin

路径规范以你调用命令时所在的目录为基准，因此从检出目录根执行 add . 即可。
重启，然后按上述方式确认。

从 GitHub 安装
sh
dsh plugin --profile  add github:rbviz/dsh-plugin-jules

pnpm 10 及更高版本会拒绝运行依赖项的 prepare 脚本，除非显式允许，因此
第一次尝试会失败，并打印出需要添加到该 profile 的 pnpm-workspace.yaml 中的确切键名：
yaml
allowBuilds:
dsh-plugin-jules: true

请将该许可视为允许此包在安装时于你的机器上执行代码，
这发生在 agent 所运行的任何沙箱之外——只允许你信任其源码的包，并固定到某个提交
（github:rbviz/dsh-plugin-jules#），这样后续的推送就无法悄悄改变实际运行的代码。

prepare 会链接 peer 依赖并将 src/ 编译到 lib/，因为 git 安装获取的是源码，而 lib/ 有意不提交到仓库。从 registry 安装则完全跳过 prepare，直接提供预构建的 lib/。

不安装的方式

对于本地开发循环，你可以完全跳过该包，并从你的 profile 的 cordis.patch.yml 中按绝对路径插入构建后的入口点：
yaml
- insert:
- id: jules
name: '/path/to/jules-plugin/lib/index.js'
config:
apiKeyEnv: JULES_API_KEY

在 bundle 已安装时不要这样做。两个层都会插入行 id jules，组合会在启动时中止并报错 duplicate loader entry id: jules，而不是猜测哪一个生效。只使用其中一个所有者；要改变已安装 bundle 的行为，请按 id 覆盖其行。补丁会替换该行的整个配置，而不是合并进去，因此请重新声明你想要的每一个键。

身份验证

1. 在 https://jules.google.com/settings 创建一个密钥。
2. 将其以 apiKeyEnv 中的凭据名称暴露（默认为 JULES_API_KEY）。可以在启动 harness 之前导出它，
或者通过 harness 凭据存储来保存它，这样配置中引用的始终是密钥名称，而不是包含密钥本身。
sh
export JULES_API_KEY=...

密钥会在每次请求时解析——先使用字面量 apiKey，然后是 ctx.credentials，最后是启动
环境——因此轮换后的密钥会应用到下一次调用，无需重新加载。未配置密钥时，工具会以可操作的错误消息失败，而不是裸的 401。

快速开始
text
jules_sources                     # Jules 可以在哪些仓库中工作
jules_create                      # prompt + source + requirePlanApproval + autoCreatePr
jules_watch                       # 返回一个 job id；然后结束你的回合
... 完成通知到达 ...
job_output                        # 读取报告
jules_status                      # 读取计划，然后 jules_approve_plan
jules_patch                       # 审查或落地差异

工具

| 工具 | 用途 |
|---|---|
| jules_sources | 列出连接到 Jules 的仓库。仓库必须先出现在这里，jules_create 才能将其作为目标。 |
| jules_create | 启动会话并立即返回会话 id。接受 prompt，以及可选的 source、branch、title、requirePlanApproval、autoCreatePr。省略 source 可创建无仓库会话。 |
| jules_list | 列出最近的会话，最新的在前，附带状态和拉取请求链接。 |
| jules_status | 完整展示单个会话：状态、计划、审批、拉取请求、生成的文件、最新命令、最后一条代理消息。 |
| jules_activities | 事件日志：计划的生成与审批、消息、进度、完成、失败、产物。 |
| jules_approve_plan | 批准待处理的计划，以便代理可以编辑文件。 |
| jules_send_message | 回答问题、纠正计划或移交后续工作。 |
| jules_watch | 在后台监视；返回一个作业 id，并在有内容可读时通知你。 |
| jules_wait | 为同样的等待保持回合开启，适用于在此期间没有其他事情可以推进的情况。 |
| jules_patch | 最新的统一差异，列出所有涉及的文件，并提供 offset/nextOffset 分页。 |

每个 id 参数都接受 123、sessions/123 或 jules.google.com/session/123 URL，每个
source 参数都接受 owner/repo、github/owner/repo 或完整的资源名称。

配置

在加载器行的 config 块中设置。除凭据外，每个字段都有默认值。

| 字段 | 默认值 | 含义 |
|---|---|---|
| apiKey | — | 字面密钥。优先使用 apiKeyEnv，以免机密进入配置文件。 |
| apiKeyEnv | JULES_API_KEY | 保存密钥的凭据引用。 |
| baseURL | https://jules.googleapis.com/v1alpha | API 根地址。 |
| defaultSource | — | 当调用省略时，jules_create 所指向的仓库。设置它会使无仓库会话不可用。 |
| requestTimeoutMs | 30000 | 每个请求的截止时间。 |
| defaultPageSize | 30 | 未选择分页大小的列表调用的分页大小。 |
| maxPageSize | 100 | 调用方可以请求的最大分页大小。 |
| maxPatchBytes | 200000 | jules_patch 返回的最大差异片段。 |
| pollIntervalMs | 5000 | jules_wait 内状态轮询之间的延迟。 |
| waitDefaultMs | 120000 | 当调用方未设置时，jules_wait 使用的等待预算。 |
| waitMaxMs | 300000 | 调用方可以请求的最大等待预算。 |
| maxActivityPages | 10 | 一次读取可以遍历的活动页数。 |
| enableWatch | true | 暴露 jules_watch。 |
| watchPollIntervalMs | 15000 | jules_watch 内轮询之间的延迟。 |
| watchDefaultMs | 1800000 | 当调用方未设置时，jules_watch 使用的监视预算。 |
| watchMaxMs | 7200000 | 调用方可请求的最大监视预算。 |
| watchSettleOnMessage | true | 当代理发布消息时结束监视，而不仅仅是在状态变化时。 |
| retryMaxAttempts | 4 | 每个请求的尝试次数，包括第一次。 |
| retryBaseDelayMs | 1000 | 第一个退避步骤；每次尝试翻倍。 |
| retryMaxDelayMs | 30000 | 单个退避步骤的上限。 |

跨字段错误会在加载时以具名错误失败，而不是在第一次调用时：defaultPageSize
高于 maxPageSize、waitDefaultMs 高于 waitMaxMs、watchDefaultMs 高于 watchMaxMs、
retryBaseDelayMs 高于 retryMaxDelayMs，以及 baseURL 不是绝对 URL。

等待：监视，不要轮询

一个 Jules 会话会运行数分钟到数小时。工具的设计使得模型永远不必轮询，并在三处
说明了这一点，因为轮询是代价最高、收益最低的失败模式：

- 模型指南以它开头——创建、监视、结束你的回合；
- 每个与等待相关的工具描述都说明它用于什么，而不是它做什么，因此
jules_status 读起来像是一个确认步骤，而不是一个邀请；
- jules_status 在被询问两次时会说明这一点。它会按调用方和
会话记住上次报告的内容，当没有任何变化时，它会呈现：

注意：自你上次检查 45 秒前以来没有任何变化。不要继续轮询——jules_watch
通知才是告诉你发生了某些事情的东西。

规范值携带 unchangedForMs，因此这一事实是数据而非散文，并且该提示是
附加性的：完整报告仍然在那里。

重启结束的是监视，而不是工作

后台作业是进程本地的：harness 将它们保存在内存中，并在关闭时拆除它们。
因此，重启会静默地结束每一个监视——而 Jules 会话本身仍在
Google 的云中继续运行，因为它们从一开始就不属于我们。

作业无法被恢复。作业需要一个活着的拥有代理来接收完成通知，而在
插件加载时没有代理；任何声称在启动时恢复监视的东西都会是在轮询，却没有人可以告知。

幸存下来的是事实。jules_watch 将会话记录在一个持久的 jules_watches 域中，
而一个自行得出结论的监视会将其移除。条目会随其记录的预算过期，
因此不会有任何累积。重启后，模型指南会增加一段文字，列出仍然
处于待命状态的内容：

注意：后台监视无法在 harness 重启后存活，并且在此 harness 上次停止时仍有 2 个监视处于待命状态：
123、456。Jules 会话本身仍在云中继续运行。用 jules_watch 重新武装你仍然关心的那些；
一个此后已经完成的会话只需要一次
jules_status。

该部分文本按每次组装进行评估，因此该注释会在插件加载后立即出现，并随着监视被重新武装而清除。
一个被故意终止的监视会保留其条目，直到其预算过期——
区分“用户停止了此操作”和“测试框架正在关闭”并不是现有信号能够可靠做到的事情，而猜错恰恰会丢弃这个机制存在所要保留的记录。

记录不携带所有者，因此一旦重启使一切变为非活跃状态，该笔记就会列出由共享同一测试框架主目录的任意会话所武装的监视。在单会话设置中这是不可见的；在有多个会话时，这是噪声而非错误操作，因为重新武装是无害的。

没有存储域的合成只会丢失该笔记；工具族不受影响。

Jules API 不允许的事项

这些是服务限制，而非插件中的缺口。在围绕它们进行规划之前值得了解：

- 没有取消、暂停或恢复。 :cancelPlan、:pause 和 :resume 全部返回 404。会话会运行至完成或失败，卡住的命令无法被中断。唯一的杠杆是一条消息。
- 没有单独的“拒绝计划”操作。 :approvePlan 存在；没有 :rejectPlan。发送带有修正内容的消息是更改计划的唯一方式。
- 后续消息从会话自身的快照恢复。 :sendMessage 只接受一个提示——没有基础或分支控制。将后续消息视为在该会话的分支上迭代。
- PR 基础跟随起始分支。 创建时没有 prBase，因此在 jules_create 上设置 branch 来控制它。
- 没有成本、令牌或运行时核算，也没有办法要求代理在 N 分钟后回报。

部分信号

- progressUpdated 经常携带空摘要。 因此 jules_status 会呈现 latestCommand，取自最新的 bashOutput 产物，这样至少可以将停滞的会话追溯到某条命令。
- generatedFiles 在实践中为空。 jules_patch——它读取 changeSet 产物——是权威的变更列表，其 files 字段列出每个被触及的路径。
- requirePlanApproval 和 autoCreatePr 是服务不会回显的输入。 它们被报告为 yes/no/unknown，由证据决定（存在 PR、计划已获批准），在没有证据时为 unknown，而不是伪造的 false。
- 批准由其事件确认，而不是由它返回时所处的阶段确认。 jules_approve_plan 在批准后短暂轮询 planApproved 活动，因为服务对其自身操作是最终一致的：阶段可能仍显示 AWAITING_PLAN_APPROVAL——或更靠后的某个阶段——而 planApproved 可能仍显示为 false，但对于一个实际上已落地并开始工作的批准而言。回复会说明两者中发生了哪一种（approvalConfirmed），当无法及时确认时，它会如实说明，而不是暗示批准失败。如果你需要确定性，请自行读取 planApproved 事件，或等待代理的第一个进度事件。
- Session.state 仅供参考。 会话可以发布其最终答案，而让 state 仍显示
IN_PROGRESS 无限期持续——Jules 网页界面也显示同样的卡死状态。插件读取活动日志，而不是信任该字段。
- 活动游标是过滤器，不是参数。 API 参考文档记录了 ?createTime=，但服务会拒绝它（“Cannot bind query parameter. Field 'createTime' could not be found”）。插件发送官方 SDK 使用的 AIP-160 表达式，并将拒绝视为带宽问题而非失败。

设计说明

规范值，而非散文。 每个工具都声明输出 schema 并返回与之匹配的值；render 单独生成模型读取的文本。可选标量投影为 ''，缺失列表投影为 []，因此值始终是形状固定的无损 JSON。

等待只有一种实现。 jules_wait 和 jules_watch 共享 runWatch，因此它们不可能在会话何时完成或报告什么上产生分歧。watch 基于新证据得出结论：终态、它进入的状态，或启动后到达的活动。它启动时读取的日志是基线——用于报告，绝不作为触发条件——因此观察一个会话，其最后活动就是你刚刚回答的问题时，它会等待真正的回复。

失败是分类型的，部分失败会被点名。 传输失败、超时、404、认证拒绝、速率限制，以及非 JSON 的 2xx 响应体，各自抛出自己的错误类，因此调用方可以区分它们，而不是阅读散文。重试恰好覆盖 429 和 5xx，并且是有界的。在部分失败可存活的情况下，结果会说明这一点，而不是填补空白：如果会话读取成功但其活动日志读取失败，投影会携带 logRead: false，报告以警告开头，因为“没有待处理的计划”和“我们无法查看”需要采取相反的行动。jules_approve_plan 区分三种结果——已确认、尚不可见和无法验证——因此不可读的日志永远不会被解读为批准失败。

日志写入永不拒绝。 日志失败只会损失重启说明，绝不会损失 watch，因此它绝不能拖垮正在做实际工作的任务——但它会被记录，因为静默吞掉它正是日志损坏在一个发布周期内未被发现的原因。

与服务匹配的重试。 Jules 记录了 429 和 5xx，但没有公布限制，而且它自己的 SDK 报告高并发会静默失败并给出误导性错误。客户端对这些状态进行指数退避重试，遵守 Retry-After，并以类型化错误放弃。尚不可查询的会话——Jules 在资源存在之前就生成了 id——会被重试，而不是被报告。

模块解析。 profile 使用 pnpm 的 link: 协议安装树外包，这不会在真实包旁边创建 node_modules，而 Node 会将符号链接的包解析到其 realpath。因此，插件自身的 import '@deepseek-ai/dsh-tools' 会失败，即使 harness
刚加载完文件。scripts/link-dsh-deps.mjs 会把每个声明的 peer 链接到当前运行安装已经使用的那份副本上，这样两边就共享同一个模块实例。

开发

node scripts/link-dsh-deps.mjs   # 执行一次，或在更改 peerDependencies 之后执行
npm run build                    # tsc，使用 harness 已经自带的 TypeScript
npm test                         # 先构建，然后运行完整测试套件
node scripts/link-dsh-deps.mjs --check   # 报告缺失的 peer，不做任何更改

scripts/build.mjs 会依次从 $DSH_TSC、链接的 node_modules、$DSH_HOME 解析 TypeScript，因此该插件不需要自己的工具链，也永远不会运行 pnpm install。

测试分两层运行。单元测试针对打桩的传输层覆盖规范化、请求构造、重试与错误分类、投影以及渲染。真实组合测试则通过 Cordis 加载器把构建好的插件与真实的 harness 服务一起挂载，并通过真实的执行管线驱动工具——包括存储栈，因此持久化的 watch 日志是被实际执行的，而不是假设的。

源码导览

| 文件 | 作用 |
|---|---|
| src/index.ts | 插件入口：名称、注入、Config schema、凭据解析、注册、模型指引。 |
| src/client.ts | 基于 fetch 的 v1alpha 客户端、错误类以及重试策略。 |
| src/types.ts | 传输类型以及工具在调用前应用的引用规范化。 |
| src/views.ts | 到规范值的投影，以及每个投影渲染出的文本。 |
| src/tools.ts | defineTool 声明。 |
| src/watch.ts | runWatch——jules_wait 与 jules_watch 共享的稳定规则——以及 job 适配器。 |
| src/journal.ts | 持久化的 watch 日志以及重启说明。 |
| src/async.ts | 两条等待路径共用的可取消 sleep。 |
| cordis.patch.yml | profile 应用的 bundle 层。 |

许可证

MIT——见 LICENSE。按设计即为宽松许可：商业使用、修改和再分发都没问题，唯一的义务是保留版权声明。这里没有任何 copyleft，因此将其构建进商业产品无需对本仓库进行法律审查。

该插件不捆绑任何第三方代码。它的全部十个导入——@deepseek-ai/ 包和 zod——都是 harness 提供的 peer 依赖，而且它们每一个都是 MIT，DeepSeek Harness 本身也是。

有两件事独立于本许可证，在发布前值得了解：使用该插件需要一个 Jules 账户，并受 Google 服务条款约束；而 Jules* 是 Google 的商标，此处为描述性使用——本项目与 Google 没有任何关联，也未获得其认可。