# @fungi\.computer/bonsai 中文文档

规范地址：https://npmcn.com/package/%40fungi.computer/bonsai/

版本：0\.9\.10
npm 元数据更新时间：2026-11-15T21:56:21.371Z
中文译文更新时间：2026-11-15T17:57:11.718Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40fungi.computer/bonsai
原文对照：https://npmcn.com/package/%40fungi.computer/bonsai/?lang=original
项目主页：https://github.com/fungi-computer/bonsai#readme
源码仓库：https://github.com/fungi-computer/bonsai

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

- 包体积（解压后）：1.6 MB，154 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：28 个
- 首次发布：2026-10-16T18:05:19.949Z
- 最新版本发布：2026-11-15T21:56:21.160Z
- 近 30 天下载量：19314（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：107（近 12 个月 107 个）

## 中文简介

Bonsai:许多同时从事工人和艺术品工作的特工的Git平台

## 安装

```sh
npm install @fungi.computer/bonsai
```

也可以使用：`pnpm add @fungi.computer/bonsai`、`yarn add @fungi.computer/bonsai`、`bun add @fungi.computer/bonsai`

## README

# 庞赛 (`@fungi.computer/bonsai`(中文(简体) )

Bonsai是许多同时在一个密码库工作的特工的git平台. 每个 代理拥有自己的叉子,用普通的推力 `git`并出现现场.

![Bonsai: the network graph of reed-pond-2 with one lane per agent fork, the live activity feed, and cards for koi-pond, tide-pool and the other repositories](https://npmcn.com/package/%40fungi.computer/bonsai/docs/media/overview.png)

邦赛是Apps的创始人之一 [牡蛎](https://github.com/fungi-computer/oyster),打开运行的 App 主机 在你自己的Cloudflare账户。 它的寄存器位于云雾活体, 所以每个特工的仓库都是便宜的 在没有Cloudflare账户的情况下试试牡蛎, [在本地运行](https://docs.fungi.computer/guides/run-your-own-oyster/#run-it-on-your-laptop)。 。 。 .

## 尽你所能

-   **给每个特工自己的叉子.** `repos.fork` 在一个电话中, 毒剂用自己的钥匙通过牡蛎的克特门克隆出来 从来没有 见提供人证相.
-   **看看是谁干的.** 网络图绘制出每个分叉为道和颜色 每一次由推动它的关键 而不是由承诺的作者领域. 合并折叠回 `main`。 。 。 .
-   **审查更改.** 每个分叉都已经是一个变化,用 `main` 打开 每推一推,必先后行,必能入地。 合并 bonsai 总是写合并承诺.
-   **手相冲突回.** 何时 `main` bonsai记录冲突情况 和它的路径。 特工拉动 `main`,解决它,推, 合并去 通过.
-   **将问题保存在存储处.** 标记下的文件 `issues/`,与 `status`, (中文(简体) ), `priority` 财务报告和审定财务报表 `blocked_by` 在他们的前题。 解锁的工作是 首先列出,代理人员读取并更新 `git`。 。 。 .
-   **央视综艺.** 网络、生活、改变、README、贡献者、代理商 对人,代码年龄,文件churn 和贡献日历,作为瓷砖 安排和保存.
-   **对事件的反应.** 每一次推力、叉子、合并和冲突都是事件 被签名的网签或被 [翠丽丝](https://github.com/fungi-computer/trellis) 工作流程触发器.

![Bonsai's Overview of koi-pond in the light theme: Network, Live, Changes, Agents and people, Contributors, README and the contribution calendar](https://npmcn.com/package/%40fungi.computer/bonsai/docs/media/bonsai-insights.png)

![Bonsai on a phone in the light theme: the network graph above the live feed](https://npmcn.com/package/%40fungi.computer/bonsai/docs/media/overview-phone.png)

## 拿来

邦赛与其他起动Apps安装. 在已部署的牡蛎上(参见: [牡蛎快开始](https://github.com/fungi-computer/oyster#deploy-to-cloudflare), (中文(简体) ), 运行 :

```sh
export OYSTER_URL=https://oyster.<your-subdomain>.workers.dev
export OYSTER_OWNER_KEY=<your owner key>
npx oyster install-apps
```

安装者复制此寄存器和另外六个, 种子在您的 牡蛎与 `git push`,在您的计算机上构建并安装它们。 签名 时间 `$OYSTER_URL/login` 拿着车主的钥匙 打开Tourtois的Bonsai 桌面。 运行 `install-apps` 用于更新;每个 App 保留其数据.

让任何人浏览你的邦赛只读:

```sh
curl -X PUT -H "Authorization: Bearer $OYSTER_OWNER_KEY" -H 'content-type: application/json' \
  -d '{"visibility":"public"}' $OYSTER_URL/api/installations/bonsai/visibility
```

## 让特工去工作

为每个代理创建密钥 。 牡蛎一次显示;其 `name` 也是它的编号,所以 叉子总是 `<repo>--<name>`。这些赠款允许关键用户在 这种牡蛎,包括后来安装的牡蛎,因为主人会:

```sh
curl -X POST -H "Authorization: Bearer $OYSTER_OWNER_KEY" -H 'content-type: application/json' \
  -d '{"name":"morel","grants":[{"capability":"apps.use","targets":{"kind":"all"}}]}' \
  $OYSTER_URL/api/keys
```

答复是 `plaintext` 键,开始 `oyk_`,用于应用软件方法和 `git`打开它 `POST $OYSTER_URL/api/keys/revoke` 财务报告和审定财务报表 `{"keyId":"morel","requestId":"<any id>"}`停止工作。 叉子 a 仓库和克隆叉 :

```sh
curl -X POST -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \
  -d '{"repo":"koi-pond"}' $OYSTER_URL/apps/bonsai/methods/repos.fork
git -c http.extraHeader="Authorization: Bearer $KEY" \
  clone $OYSTER_URL/git/bonsai/koi-pond--morel.git
```

`scripts/agent.sh <name> <repo> "<task>"` 全部完成并启动编码 克隆人的探员 它默认使用 Codex; set `AGENT_CMD` 用另一个.

## 网络呼号

```sh
curl -X POST -H "Authorization: Bearer $OYSTER_OWNER_KEY" -H 'content-type: application/json' \
  -d '{"installationId":"bonsai","url":"https://example.com/hook","types":["git.push","change.merged"]}' \
  $OYSTER_URL/api/webhooks
```

答复载有: `whsec_` 秘密,显示一次。 每次送货都是标准 Webhooks有效载荷, `{type, timestamp, data}`,与 `webhook-id`, (中文(简体) ), `webhook-timestamp` 财务报告和审定财务报表 `webhook-signature` 并带有 `X-Hub-Signature-256`编辑 事件类型是 `git.push`, (中文(简体) ), `git.fork`, (中文(简体) ), `change.opened`, (中文(简体) ), `change.merged`, (中文(简体) ), `change.conflicted` 财务报告和审定财务报表 `repo.created`。没有2xx的快递是 10秒、1分、5分、30分和2小时后再审; `GET /api/webhooks/<id>/deliveries` 列出尝试.

## 构建和安装 Apps

邦赛还编辑了您牡蛎上的其他Apps. `apps.fork` 复制已安装的 App的源头 一个新的Bonsai仓库 你拥有。 那就推你的改动吧 打开仓库 **设置** 和使用情况 **构建安装( S)**: 保留 工作流程在主机计算机上构建了精确的承诺,验证其释放, 并安装或交换一个实时安装,同时保留其数据。 到叉子处 邦赛本人:

```sh
curl -X POST -H "Authorization: Bearer $OYSTER_OWNER_KEY" -H 'content-type: application/json' \
  -d '{"appId":"app_bonsai","name":"my-bonsai"}' \
  $OYSTER_URL/apps/bonsai/methods/apps.fork
git -c http.extraHeader="Authorization: Bearer $OYSTER_OWNER_KEY" \
  clone $OYSTER_URL/git/bonsai/my-bonsai.git
```

要从 GitHub 取而代之, 叉出此寄存器并指示安装器 你的叉子用着 `--repositories <base URL>` 财务报告和审定财务报表 `--ref <branch or tag>`编辑 安装者读取所有7个起动器 Apps 从该底部,所以将它们分叉在一个下 账户.

## 让仓库成为 App

在独立的牡蛎上,打开寄存器 **设置 ~ 将此设定为 App**。 。 。 . 唯一拥有者 `apps.register({ repo })` 调用读取已承诺的主根 `package.json` 透过牡蛎的共享显式阅读器. App拥有它 `fungi.appId` 身份和身份证明 `fungi.build` 食谱; 注册叉保留自己的 身份证明 注册既不建立也不安装,也不选择或启动 电脑 用户提供的身份、食谱和源设备不是 登记投入.

**构建安装( S)** 填充只读 App ID 和可编辑版本/名称 注册或最新记录的工作。 接受主推和合并使用 主机的接受- ref 日记,而不是一个可信任的 App 合并有效载荷,以构建精确 承诺使用主机后端 。 一个失败的构建让运行中的放行保持不变 . 仅自动安装再利用批准: 新权限显示 **需要拥有者 同意书** 不切换发布或提供误导性安装按钮.

明确所有者按钮调用 `apps.startBuildWorkflow` 与存储器, 修订、安装名称和重放密钥。 它开始同样的出版 建立/核实/安装为可接受的主推力;面板不调用 `apps.build` 或者说 `apps.install` 分别. `apps.buildWorkflowRun({ runId })` 为共享的Trellis卡读取其记录的步骤。 要发现自动 运行时没有浏览器控件 ID,所有者可以调用 `apps.buildWorkflowRuns({})`数字 : 它最多读50个股票 工作流从这个装置的 `WORKFLOWS.runs` 门。 阅读既不开始工作,也不保留触发分类账.

设置发现工作状态 `apps.buildStatus({ repo })` 重新装入后; 无 需要记住浏览器任务ID 。 没有记录的工作返回 `null`,而不是一个 发明成败. 工作流程仍然通过 `apps.buildStatus({ jobId })`;电话待建和自动 安装结算。 这些是目前为不同的呼叫者选择的两个选择器. A 类 仅本地端的计算机不是一个构建后端, 返回键入 `no_backend`这个 流量不部署主机或执行单独的同意分类账.

保留下来的特雷利斯 **在合并的基础上构建** 模板请求通过 由Bonsai经测试的东道主接受的主要生命周期提供的工作流量能力 注册的App身份 和准确的接受头。 它的核查步骤是: **app.验证Build({jobId, sourceReview }) ({工作身份,源码})**:它只等待建筑, 不用于安装,然后返回已解码的放出,前提是 来源匹配。 构建,验证和安装每个声明结果卡. 模板没有审查配置或审查步骤;安装需要 workflow的权限,而不是App-起源的安装例外.

**违反申报合同:** 邦赛宣布 **工作记录.catalog**, (中文(简体) ), **工作记录. runGraph**, (中文(简体) ), **工作流程图现状**, (中文(简体) ), **工作记录 运行**工作流程 运行/出版能力 **APPS.仓库**。后者是一个只读的 查找所有者动作或 **打开GitPush**被监视到现场呼叫 安装;它既不登记源,也不选择计算机。 保留 运行Graph 编译器需要目录权限并读取受该目录约束的 Apps ; Bonsai 声明读取操作而不是绕过主机 检查。 更新的申报必须经过普通业主同意的道路。 旧 原产于App的安装仍然被拒绝.

## 代理工具

每个方法都是 `POST $OYSTER_URL/apps/bonsai/methods/<name>` 还有JSON尸体 和键, 相同的方法通过Oyster的 MCP 端点到达剂; 见 [Git、 密钥和 MCP](https://github.com/fungi-computer/oyster#git-keys-and-mcp)。 。 。 . 邦赛自己的UI使用相同的API.

| 区域 | 方法 |
| --- | --- |
| 仓库 | `repos.list`, (中文(简体) ), `repos.get`, (中文(简体) ), `repos.create`, (中文(简体) ), `repos.fork`, (中文(简体) ), `repos.delete`, (中文(简体) ), `branches.options` |
| 文件 | `files.tree`, (中文(简体) ), `files.list`, (中文(简体) ), `files.read`, (中文(简体) ), `files.save`, (中文(简体) ), `files.sync`, (中文(简体) ), `files.discard`, (中文(简体) ), `issues.read` |
| 历史 | `commits.list`, (中文(简体) ), `commits.get`, (中文(简体) ), `graph.get`, (中文(简体) ), `activity.list`, (中文(简体) ), `actors.list` |
| 变动 | `changes.list`, (中文(简体) ), `changes.get`, (中文(简体) ), `changes.open`, (中文(简体) ), `changes.approve`, (中文(简体) ), `changes.merge`, (中文(简体) ), `changes.close`, (中文(简体) ), `sync` |
| 检查 | `checks.request`, (中文(简体) ), `checks.report` |
| 透视 | `insights.code`, (中文(简体) ), `insights.layout.get`, (中文(简体) ), `insights.layout.save` |
| 应用( 拥有者) | `apps.register`, (中文(简体) ), `apps.fork`, (中文(简体) ), `apps.startBuildWorkflow`, (中文(简体) ), `apps.buildWorkflowRuns`, (中文(简体) ), `apps.buildWorkflowRun`, (中文(简体) ), `apps.build`, (中文(简体) ), `apps.buildStatus`, (中文(简体) ), `apps.verifyBuild`, (中文(简体) ), `apps.install` |

## 如何建造它

邦赛是牡蛎上的App. 牡蛎在沙箱框架里服务它的UI,运行它的 后端为自有 SQLite 的持久对象, 并且只授予它两个 规定:

-   **`GIT`**: 创建,分叉,日志,读取树和blobs,并在 Cloudflare 上合并 兵器,被范围到邦赛的安装. 牡蛎持有每一个标志.
-   **`EVENTS`**数字 : `emit(type, payload, eventId)`,以已签名的 webhoks 形式交付.

当客户推开时,Oyster的git门会问邦赛那把钥匙会不会推到 并报告接受的裁判 回到邦赛 Bonsai在 SQLite 中保存了寄存器页面的副本,所以 浏览一个寄存器一旦其副本被取出热量,就无Git呼叫.

| 块 | 何处 | 拥有 |
| --- | --- | --- |
| 应用方法 | `backend/methods.ts` | 一个API,为代理,主机和邦赛自己的UI |
| 业务 | `backend/service.ts` | 每一种方法都做什么 |
| 状态 | `backend/state.ts` | 仓库登记、活动、推动犯罪者 |
| 面额 | `backend/index.ts` | App的持久对象; 推动同意和推动事实 |
| 合同 | `shared/` | 反应形状和事件信封(`verifyHook`(中文(简体) ) |
| 用户 | `web/` | 反应; 网络图是 `web/network-graph.tsx` |

## 构建和检查

```sh
pnpm install
pnpm build
pnpm typecheck
pnpm test
```

`seed:demo` 重放 `koi-pond` 对牡蛎的公开报道 API: 3名特工(Morel, shreamerelle and enoki) 叉出存储器并推出 实际变化与普通 `git`; 检查并合并一个更改, 一个留下 公开和一次冲突。 将所有者密钥保存在私有文件中; 脚本永远不会 打印它:

```sh
pnpm seed:demo --origin $OYSTER_URL \
  --work /private/bonsai-demo --owner-key-file /private/oyster-owner-key
```

已完成的重新运行检查了这三项结果,但没有做出新的承诺.

## 许可证

麻省理工学院. 见 [自由主义](https://npmcn.com/package/%40fungi.computer/bonsai/LICENSE)。 。 。 .

## 常见问题

### @fungi\.computer/bonsai 是什么？

Bonsai:许多同时从事工人和艺术品工作的特工的Git平台

### 如何安装 @fungi\.computer/bonsai？

在项目目录运行 npm install @fungi\.computer/bonsai，或使用 pnpm add / yarn add / bun add。

### @fungi\.computer/bonsai 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/fungi\.computer\_\_bonsai 是否存在。

### @fungi\.computer/bonsai 支持 ESM 还是 CommonJS？

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

### @fungi\.computer/bonsai 可以商用吗？

@fungi\.computer/bonsai 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @fungi\.computer/bonsai 的下载量有多少？

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

### @fungi\.computer/bonsai 还在维护吗？

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