# @agentproto/worktree 中文文档

规范地址：https://npmcn.com/package/%40agentproto/worktree/

版本：0\.21\.1
npm 元数据更新时间：2026-11-05T17:46:48.950Z
中文译文更新时间：2026-11-06T02:22:25.402Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40agentproto/worktree
原文对照：https://npmcn.com/package/%40agentproto/worktree/?lang=original
项目主页：https://agentproto.sh/
源码仓库：https://github.com/agentproto/ts

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.4 MB，33 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：7 个
- 首次发布：2026-07-08T14:51:27.842Z
- 最新版本发布：2026-11-05T17:46:48.517Z
- 近 30 天下载量：6480（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：38（近 12 个月 38 个）

## 中文简介

AIP-14 TOOL合同 + 内置于 AIP- 30 PROVIDER 中,用于提供、取出并清理一棵活树—— 原始的 AgentStep 绑定它 `cwd` 用于启动代理工作.

## 安装

```sh
npm install @agentproto/worktree
```

也可以使用：`pnpm add @agentproto/worktree`、`yarn add @agentproto/worktree`、`bun add @agentproto/worktree`

## README

# @ agentproto/ 工作树

AIP-14 TOOL合同+AIP-30内置的供货、取料、取料、取料、取料、取料、取料等合同, 清理一棵原始的活树 `@agentproto/workflow-runtime` `AgentStep` 约束其 `cwd` 以"在工作树上启动代理"的工作流程.

## 工具

-   **`worktree.provision`** —— 说 `git worktree add` 一个新的工作树 `repoRoot` 时间 `<repoRoot>/../_worktrees/<slug>` 树枝 `wt/<slug>`从 `base` (默认) `origin/main`) (中文(简体) ). 在此之前 `depsCmd` 运行 : `linkPaths` 彼此相连, `writeFiles` 被写,和 `cloneGlobs` (例如:. `node_modules`)被克隆 中——在文件系统支持的地方复制并写入,否则是一个简单的副本, 从来没有一个符号链接。 礛 `depsCmd` 运行,然后 `copyGlobs` (如: 本地机密)从 `repoRoot` 在同一棵树上 相对路径。 终于跑出树底 `agentproto.json` **设置** 钩子( 除非 `runSetup: false`) (中文(简体) ). 回返 `{ cwd, branch }`。 。 。 .
-   **`worktree.run-gate`** ——在目录内运行一个呼叫器提供的指令 并报告其退出代码的通过/失效.
-   **`worktree.cleanup`** ——停止工作树的监管服务,运行 树基 **拆开** 钩子(已上钩,从未被堵住),然后 `git worktree remove` (+ 可选) `git branch -D`) (中文(简体) ).
-   **`worktree.run-script`** 运行一个宣布 `scripts.<name>` 命令一次 在工作树上 `AGENTPROTO_*` 注射过.
-   **`worktree.start-service` 编号 : `worktree.stop-service` 编号 : `worktree.list-services`** - 开始/停止/列出申报 `type: "service"` 脚本受监督 拥有指定港口和 `*.localhost` 代理路线.

门/提供/清理 三重奏是不可知的:没有硬码的包管理器, env 版式,或出闸命令——一切都是一种输入.

## `agentproto.json` 按工作树木生命周期计算

丢出一个 `agentproto.json` 在 repo 根上声明新鲜的工作树是怎样的 建立、拆卸 和它所经营的事务:

```json
{
  "worktree": {
    "setup": ["pnpm install", "cp \"$AGENTPROTO_SOURCE_CHECKOUT_PATH/.env\" .env"],
    "teardown": "rm -rf .cache",
    "depsCmd": "pnpm install --prefer-offline",
    "linkPaths": ["node_modules"]
  },
  "scripts": {
    "test": { "command": "pnpm test" },
    "web":  { "command": "pnpm dev --port $AGENTPROTO_PORT", "type": "service", "port": 3000 },
    "api":  { "command": "pnpm api --port $AGENTPROTO_PORT", "type": "service" }
  }
}
```

-   **`worktree.setup` 编号 : `worktree.teardown`** 单(多线)外壳 字符串或一系列命令,以 cwd 的形式按顺序运行 . 失败的设置命令 **未提供** (a) 其记录输出 失败的拆卸命令会被记录下来, 但永远不要挡住清理 。 钩子跑 没有TTY,所以它们的巢显然不互动: `CI=true` 财务报告和审定财务报表 `npm_config_confirm_modules_purge=false` 除非环境 已经定义了它们(如此) `pnpm`编号 :`npm` 在确认时从未中止 快速).
-   **`worktree.depsCmd` 编号 : `worktree.linkPaths`** ——申报性缺省 `worktree.provision`属于自己的 `depsCmd`编号 :`linkPaths` 投入(见上文):a 要求提供一种工作树,而不明确传递这些投入 譬如说. `agentproto worktree new`或产卵时工作树木 `agent_start.worktree` 仍在申请,从这里找到的 一个 明确的工具输入总是胜过这一默认。 一样 `runSetup` 门, 与 `setup`编号 :`teardown` - 见下文安保部分.
-   **`scripts.<name>`** —— 说 `{ command, type?: "service", port? }`普通脚本 运行一次( e)`worktree.run-script`(三); `type: "service"` 脚本受到监督 长期进程(`worktree.start-service`) (中文(简体) ).

### 安全性: 配置从承诺的基础树读取

`agentproto.json` 实值 **永远** 读取通过 `git show <base>:agentproto.json` —— 说 基准参考的已执行树( 默认) `origin/main`从来没有工作树 工作树。 工作树内的特性分支或代理编辑文件 因此 **无法注入** 运行的设置/ 隐藏钩或服务命令 在主机上;只有审查员合并到基分支中的内容才能执行.

## `<repoRoot>/.agentproto/worktree.json` 当地每台机器工作树默认值

`agentproto.json` 被所有复制雷波的人所承诺和分享 它不能持有任何特定主机—— pnpm 存储路径, 是否克隆 `node_modules` 一点也不. `.agentproto/worktree.json` 填补了这一空白:一个LOCAL, gitignored, 主机拥有的文件( 和 `.agentproto/allowed-commands.json`(中文(简体) ) 一台机器可以放下来宣布它自己的工作树默认,没有 承诺:

```json
{
  "cloneGlobs": ["node_modules"],
  "linkPaths": ["../sibling-repo"],
  "copyGlobs": ["envs/**/.env.local"],
  "writeFiles": [
    { "path": "pnpm-workspace.yaml", "content": "\nvirtualStoreDir: /abs/path/.pnpm-vstores/{slug}\n", "mode": "append" }
  ],
  "depsCmd": "pnpm install --prefer-offline"
}
```

-   **`cloneGlobs`** 平面图案(相对于 `repoRoot`) gi 在工作树上克隆的 Dirs/ 文件 `depsCmd` 运行。 复制并写入 文件系统支持它的地方( MacOS APFS) `cp -c`/ clonefile, Linux 文档 `cp --reflink=auto`),倒倒回了平庸的抄本——从没有韵母,所以 `depsCmd` 可以使克隆人变异(例如. `pnpm install` 修理)没有 触摸源检出。 目录匹配被克隆为一个整体单位 (例如:. `node_modules` 费用一 `readdir`里面的一切都没有 (b) 与《公约》有关的其他事项; `**` 不支持 – 明确命名每个路径段.
-   **`writeFiles`' `path`编号 :`content`** 可能使用文字 `{slug}` 占地者, 取而代之的是工作树本身的一发子弹,例如指向pnpm's `virtualStoreDir` 每个工作树都有一个单独的无相撞目录 (模仿这批货物的真正用途) `agentik-studio`是因为 `infra/cli/src/commands/wt.ts` `defaultWriteFiles`) (中文(简体) ).
-   **`copyGlobs` 编号 : `linkPaths` 编号 : `depsCmd`** - 形状和语义与 匹配 `worktree.provision` 输入/ `agentproto.json` 字段.

**优先发言** (最胜的胜负)是明白的 `worktree.provision` 工具输入 > 此本地文件 > `agentproto.json`承诺 `worktree.depsCmd`编号 : `worktree.linkPaths` (单位:千美元)`copyGlobs`编号 :`cloneGlobs`编号 :`writeFiles` 没有承诺 等同,所以对于这些链 停止在这个文件。 一样 `runSetup` 门 成为坚定的信念.

**安保模式**: 与 `agentproto.json`,此文件直接读取 磁盘( 从未 `git show`从 `repoRoot` - UNURCE的检查,从来没有 刚创建的工作树, 它开始没有副本( 目录是 {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}这太夸张了 这里没有什么是献身的 保证针对: 分支不能将文件偷运进去,因为它 绝对不能犯法 信任模式只是"谁拥有这个 机器的文件系统”——与 `allowed-commands.json`。 。 。 .

径向警卫:a `cloneGlobs` 可解决外部问题的模式 `repoRoot` (单位:千美元) `/`,或任何 `..` 部分)在任何 文件系统访问.

### 环境

每个钩子、脚本和服务都收到:

| 变量 | 含义 |
| --- | --- |
| `AGENTPROTO_SOURCE_CHECKOUT_PATH` | 原始复选的绝对路径 |
| `AGENTPROTO_WORKTREE_PATH` | 工作树目录的绝对路径 |
| `AGENTPROTO_BRANCH_NAME` | 工作树的分支名称 |

每个 **服务** 还收到自己的 `AGENTPROTO_PORT` 财务报告和审定财务报表 `AGENTPROTO_URL` (它的代理 URL),加上每个兄弟的同行发现 vars 在同一工作树上提供服务: `AGENTPROTO_SERVICE_<NAME>_PORT` 财务报告和审定财务报表 `AGENTPROTO_SERVICE_<NAME>_URL` (名称为大写,非缩写) `_`) (中文(简体) ).

### 服务、港口和倒置代理

-   **端口分配** - 服务使用其申报的 `port` 当自由,否则 OS指定麻黄口. 每个申报的港口都保留在前面 服务到此结束 .
-   **反转代理** —— 说 `ProxyTable` + 键 `createProxyServer`编号 :`startProxy` 路径 `http://<script>--<branch-slug>--<repo-slug>.localhost:<proxy-port>` 改为 服务的地方端口,有WebSocket升级通过. 在回购 默认分支 : `http://<script>--<repo-slug>.localhost:<proxy-port>`轻小写, 将非图形映射到 `-`,倒塌重复,和修剪. `*.localhost` 决定: `127.0.0.1` 因此不需要DNS设置.

### `agentproto worktree` 国 际

```
agentproto worktree ls      [--repo <dir>] [--json]
agentproto worktree archive <path> [--base <ref>] [--keep-branch] [--json]
```

`ls` 列出 repo 的 git 工作树; `archive` 停止工作树的服务, 运行被撕裂的钩子,并删除它(删除分支,除非 `--keep-branch`) (中文(简体) ).

## 提供货币( 全守护进程队列)

`worktree.provision` 运行其重相(`cloneGlobs`, (中文(简体) ), `depsCmd`, (中文(简体) ), `copyGlobs`, (中文(简体) ), `setup` 钩子)通过 `provisionScheduler`,一个全流程FIFO 有上限的队列( 默认 2; ) ; `0` = 无限). 一个插槽覆盖整个重物 单个产卵从不与自己相接触. `git worktree add` 和廉价准备`linkPaths`, (中文(简体) ), `writeFiles`运行之前 排队,而永不节奏.

```ts
import { provisionScheduler, parseProvisionLimits, runWithProvisionContext } from "@agentproto/worktree"

provisionScheduler.configure(parseProvisionLimits(config.worktrees))

await runWithProvisionContext(
  { callerKey: parentSessionId, signal, onProgress: p => log(p) },
  () => runTool({ tool: provisionWorktreeTool, candidates, input }),
)
```

-   **公平无边.** FIFO, 呼叫者拥有最少的运行槽 首先,一个管弦乐团的爆裂 不能饿死另一个呼叫者.
-   **撤销.** 中止 `signal` 丢弃已队列的条目, 或杀死运行 相相的整个进程组( SIGTERM, 然后是相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相 与 `ProvisionCancelledError`。取消的备料将删除 半作活树和分枝;一出平地的倒闭使活树得以保持.
-   **进步.** `onProgress` 接收 `queued` (与 `position`, (中文(简体) ), `started`, (中文(简体) ), `phase` 财务报告和审定财务报表 `done` (单位:千美元)`ok`, (中文(简体) ), `failed` 或者说 `cancelled`) (中文(简体) ).
-   **结.** `worktrees.provisionConcurrency`, (中文(简体) ), `worktrees.provisionConcurrencyByRepo`, (中文(简体) ), `worktrees.provisionLoadFactor` 内 `~/.agentproto/config.json`; 内 `AGENTPROTO_WORKTREES_PROVISION_CONCURRENCY` 赢了 完整的表格见CLI文件.
-   **范围.** 队列为每个进程. 守护进程拥有共享的; `agentproto worktree new` 有自己的例子.

## `worktreeAgentWorkflow`

此套件还导出 `RuntimeWorkflow` 连锁这三人 上方工具环绕 `AgentStep`: 规定 − 代理人(`cwd` 约束 提供的工作树) ——大门 ——通过,人类批准 ——清理. 在门上 工作树被留在那里检查.

## `worktree-agent` 国 际

A 类 `bin` 运行该工作流程的端到端对一个真正的代理程序守护进程(即 编码代理是真实的,可监督的 `agent_start` 届会——不空 子进程 :

```
worktree-agent run \
  --repo <abs repo root> --slug <id> --task "<prompt>" --gate "<check cmd>" \
  [--base origin/main] [--adapter claude-code] [--deps-cmd "pnpm install --prefer-offline"] \
  [--copy-glob <glob>]... [--no-cleanup] [--yes]
```

它连接到守护进程 MCP 的端点 (`http://127.0.0.1:18790/mcp`,或 `AGENTPROTO_MCP_URL`)并大声地失败,如果它不能达到一个. 核准 步骤读取从 `/dev/tty`· ; `--yes` 自动核准,和 a 非交互运行( 无 TTY) 默认不批准 —— 工作树为左 而不是静静地清理.

## `worktree-gc` 常规(AIP-41,选入)

`routines/worktree-gc/ROUTINE.md` 是一个参考 AIP-41 常规收获 合并工作树的时间安排,所以长期工作空间不会积累 暂停 `_worktrees/*` 树木和死亡 `wt/*` 树枝。 它发射 `worktree_gc` 工具(守护进程 MCP/HTTP 表面显示) `planGc` 编号 : `applyGc` 内 `src/gc.ts`(中文(简体) ) 与 `apply: true`, (中文(简体) ), `salvageDirty: false`, (中文(简体) ), `wait: true` 日薪工资(`0 4 * * *`, UTC) (中文(简体) ). `wait: true` 使圆圈为真正的结果跑出块;没有它就是一个大块 repo 超过该工具的 25 默认值 `waitMs`,运行记录一个赤裸的工作 作为成功,失败的应用程序从未到达 `on_failure`。 。 。 .

**船舶残废`enabled: false`(中文(简体) )** 它会登记,但不会起火直到 你打开它。 要在工作空间激活它 :

1.  复制 `routines/worktree-gc/` 到工作空间的常规库 `<workspace>/.routines/worktree-gc/ROUTINE.md` (路径) `@agentproto/routine`是因为 `routineSpec.pathOf` (预计).
2.  设定 `enabled: true` 在前题。 插入 `repoRoot: <abs path>` 或者说 `workspaceSlug: <slug>` 改为 `target.inputs`· ; 否则守护进程会解决从 **活动工作空间**。 。 。 .
3.  重新装入例行程序后, 守护进程会记录时间表 .

安全变量由发动机执行,不能被发动机削弱 例行程序: 可回收为 **合并** (融合 {已出现,新 }) **财务报告和审定财务报表** 页:1 树是干净的) **除外** 狭义去除泵豁免:干净 `unpushed` 工作树木,其种植物都是机械依赖物`chore(deps)` 编号 : `fix(deps)` 主题和只碰锁文件的 diff `package.json`)为 晋升至 `reclaim`。一个 **打开** 公关或现场工作树总是 **举行**,则a **脏** 综合工作树仅存存档——从未 弃用——只有在 `salvageDirty` 实值 `true`。 。 。 .

## 常见问题

### @agentproto/worktree 是什么？

AIP-14 TOOL合同 \+ 内置于 AIP- 30 PROVIDER 中,用于提供、取出并清理一棵活树—— 原始的 AgentStep 绑定它 cwd 用于启动代理工作\.

### 如何安装 @agentproto/worktree？

在项目目录运行 npm install @agentproto/worktree，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 worktree-agent，可以用 npx worktree-agent 直接运行。

### @agentproto/worktree 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @agentproto/worktree 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @agentproto/worktree 可以商用吗？

@agentproto/worktree 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @agentproto/worktree 的下载量有多少？

根据 npm 官方下载统计，@agentproto/worktree 在 2026/10/05 – 2026/11/03 这 30 天内被下载 6,480 次，日均约 216 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @agentproto/worktree 还在维护吗？

最新版本 0\.21\.1 发布于 2026/11/06（今天）；至今共发布 38 个版本，其中过去 12 个月发布了 38 个；首次发布于 2026/07/08。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。