# @bud\.sh/app 中文文档

规范地址：https://npmcn.com/package/%40bud.sh/app/

版本：0\.8\.1
npm 元数据更新时间：2026-11-06T14:41:54.063Z
中文译文更新时间：2026-11-08T20:30:32.065Z
软件包许可：UNLICENSED

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

原始 npm 页面：https://www.npmjs.com/package/%40bud.sh/app
原文对照：https://npmcn.com/package/%40bud.sh/app/?lang=original

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

- 包体积（解压后）：81.1 MB，2148 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=26\.12\.0
- 运行依赖：3 个
- peer 依赖：vite \>=8\.3\.4
- 首次发布：2026-10-23T07:11:09.404Z
- 最新版本发布：2026-11-06T14:41:53.849Z
- 近 30 天下载量：2400（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 12 个）

## 中文简介

应用程序、其配置、屏幕和设计API

## 安装

```sh
npm install @bud.sh/app
```

也可以使用：`pnpm add @bud.sh/app`、`yarn add @bud.sh/app`、`bun add @bud.sh/app`

## README

# @bud.sh/app (英语)

Bud是审查一个网络项目的本地同伴:应用程序本身,它的配置,屏幕,设计和适配器API,以及一个主机启动的同伴服务器. 它的 Vite 插件, `@bud.sh/app/vite`在您的 Vite dev 服务器旁边主机, 以及软件包 `bud` CLI在没有Vite的情况下运行. 巴德浏览您的活页,在画布上同时显示您的路线,让你浏览,编辑和审查文件,并通过所选的存储适配器在页面,代码和任务上保持讨论. 界面使用Remix 3;您的项目可以使用任何运行于Vite上的框架.

## 特征

-   **页 次** - 您在现场浏览器旁边配置的路由, 每个工作空间标签有标签和历史, 以及对您选择的元素的评论
-   **帆布** - 每一个被配置的路由 总是以光和暗的时空截图, 有评论,其指针跟随其元素
-   **分支** - 截图 `main` 和工作树旁边的每一个激活的分支, 每一个从它的最新承诺中建起, 在您的退票之外
-   **拾取器** - 评论记录该元素、其块并附有 `bud:react-grab`, (中文(简体) ), `bud:remix` 或您自己的拾取器,其组件和源行
-   **文件** - 文件树、编辑器、diffs、历史、中转和解决冲突
-   **代码注释** - 讨论经过编辑的选定行,过时时可读
-   **任务** - 评论成为人民和代理人改变生活的董事会的任务 [圆珠](https://github.com/gastownhall/beads) 作为默认存储;任务设计可以添加优先权或受让人等字段
-   **探员** - 评论成为编码代理人的任务([打开代码](https://opencode.ai/)在沙盒、当地工作树木或 [{\\fn华文楷体\\fs16\\1che0e0e0}船](https://boat.dev/),单独 `dev/` 分支:代理视图显示代理端口和聊天旁的直播预览,代理屏幕列出每次会话,任何内容都会被推到某人批准时
-   **托管** - Cloudflare上的整个团队的画布、网页、任务和代理人,一个GitHub仓库
-   **自定义屏幕** - 你自己的 Remix 屏幕旁边的内置,任何你可以关闭
-   **存储适配器** - Beads 默认存储任务和讨论;自定义适配器和相容的 Git 注释存储是明确的选择

## 安装

一个软件包持有应用程序、其Vite插件和 `bud` CLI: 爱丽丝

```sh
npm install -D @bud.sh/app
```

要尝试此寄存器的版本, 构建并包装它 :

```sh
pnpm --filter @bud.sh/app build
pnpm --filter @bud.sh/app pack --out /tmp/bud-app.tgz
# In your project
npm install -D /tmp/bud-app.tgz
```

节点需要26.12或更新.

## 使用量

添加 Vite 插件 :

```ts
// vite.config.ts
import { bud } from '@bud.sh/app/vite'

export default {
  plugins: [bud()],
}
```

完全添加一个配置文件 :

```ts
// bud.config.ts (or bud.config.js)
import { defineConfig } from '@bud.sh/app'

export default defineConfig({
  name: 'My project',
  routes: ['/', { id: 'product', path: '/products/123', title: 'Product' }],
  // port: 4000,                     // Bud's own port; omit to pick a free one
  // target: { port: 3000 },         // detected from Vite by default
  // comments: { remote: 'origin' },
  // plugins: [reactGrab()],         // from @bud.sh/app/plugins; Bud's DOM picker by default
})
```

运行您通常的 Vite dev 命令并打开打印 **巴德** URL (中文(简体) ). 插件只在开发中运行, 而配置更改会重新启动它 。 它在Vite开始收听时启动Bud的同伴,找到你的dev服务器地址,在热量更新上刷新预览,并加入小dev桥页用于跟随你的活页;桥在Bud框外无所事事.

### 插件、存储和设计

仓库、拾取器、任务设计、额外屏幕和工厂的沙盒和代理商都来了 从插件, 哪个 `@bud.sh/app/plugins` 输出 : `beads()`, (中文(简体) ), `gitComments()`, (中文(简体) ), `memory()`, (中文(简体) ), `reactGrab()`, (中文(简体) ), `react()`, (中文(简体) ), `remix()`, (中文(简体) ), `picker()`, (中文(简体) ), `taskDesign()`, (中文(简体) ), `local()`, (中文(简体) ), `boat()`, (中文(简体) ), `opencode()` 财务报告和审定财务报表 `definePlugin` 为了你自己 任务和讨论是Beads的,除非插件提供; `storage: { work: false }` 或者说 `{ threads: false }` 关一关. `designs.pages` 如何设定 页面边栏名称页面: `path` (默认)或 `title` 与路径旁边.

```ts
import { defineConfig } from '@bud.sh/app'
import { definePlugin, gitComments, taskDesign } from '@bud.sh/app/plugins'
import { tracker } from './bud/tracker.server.ts'

export default defineConfig({
  routes: ['/'],
  plugins: [
    definePlugin({ name: 'tracker', label: 'Tracker', work: tracker }),
    gitComments(),
    taskDesign('./bud/tasks.tsx'),
  ],
})
```

一个插件的存储是一个完全提供的效果层,使用 `WorkAdapter` 或者说 `ThreadAdapter` 服务从 `@bud.sh/app/server`,或为 `{ project }`· ; `memoryAdapterLayer({ schema })` 两者都用于固定装置。 共享的地层一旦获得, 和它的财产,与伴侣是密不可分的。 任务设计是结束于 `.ts`, (中文(简体) ), `.tsx`, (中文(简体) ), `.js` 或者说 `.jsx` 项目内部,外部 `node_modules`; 巴德检查他们的路径 在监听和打开时输出之前。 只有每个商店的公众身份和 连接状态到达屏幕通过 `project.storage`; 插件和服务器配置 保持隐私.

任务设计默认导出 `defineTaskDesign` 从 `@bud.sh/app/design`。其可选性 `card`, (中文(简体) ), `page`, (中文(简体) ), `properties`, (中文(简体) ), `actions`, (中文(简体) ), `sections` 财务报告和审定财务报表 `column` 槽是Remix组件. 外接槽保留其内置部件,将其导出作为组件 `TaskCardDefault`, (中文(简体) ), `TaskPageDefault`, (中文(简体) ), `SectionsDefault` 财务报告和审定财务报表 `ColumnDefault`· ; `properties` 财务报告和审定财务报表 `actions` 空到设计填满为止。 槽接收经验证的工作数据、场渲染、导航和 明确操作。 项目上下文仅包含其显示 `id` 财务报告和审定财务报表 `name`。 。 。 .

见 [任务设计指南](https://bud.sh/docs/app/guides/task-designs) 用于导出道具 和紧凑的卡片示例. 相同的浏览器-模块注册和共享的Remix导入地图服务于屏幕和设计.

### 屏幕

`screens` 按顺序设置巴德的导航 将其留给Pages, Canvas, Tasks, Agents and File(工厂成立后代理). 留下内置来禁用它, 将其扩展以更改其标签或图标, 并添加自己的屏幕作为 Remix 组件模块 :

```ts
// bud.config.ts
import { canvas, defineConfig, files, pages } from '@bud.sh/app'

export default defineConfig({
  routes: ['/'],
  screens: [
    pages(),
    canvas(),
    { ...files(), label: 'Code' },
    { id: 'metrics', label: 'Metrics', icon: 'chart', module: './bud/metrics.tsx' },
  ],
})
```

```tsx
// bud/metrics.tsx
import { Text, defineScreen } from '@bud.sh/app/screen'

export default defineScreen({
  load: async ({ project, signal }) => {
    let response = await fetch(new URL('/metrics.json', project.targetOrigin), { signal })
    return (await response.json()) as { visits: number }
  },
  render: (metrics) => <Text as="p">{metrics.visits} visits this week</Text>,
})
```

一个自定义屏幕 `path` 默认为 `/<id>` 联 合 国 `icon` 改为 `layers`。巴德显示其装载器,直到 `load` 和解和复试卡如果失败。 屏幕只在浏览器中运行,在Bud的页面中运行,并用Bud的请求能力获得项目,所以把它们像配置一样对待. `@bud.sh/app/screen` 还出口巴德的 `Button`, (中文(简体) ), `Text`, (中文(简体) ), `Loader`, (中文(简体) ), `Spinner` 还有野外卡片 屏幕尚不能导入 CSS; Bud 在您第一次访问时和编辑后, 用您的项目的 Vite 捆绑每个 .

屏幕可以拥有巢穴地. 将路由图保存在一个浏览器安全模块中,然后通过与 `routes` 在配置屏幕和 `defineScreen`数字 :

```ts
// bud/metrics-routes.ts
import { get, route } from 'remix/routes'

export const metricsRoutes = route('/metrics', {
  index: get('/'),
  report: get('/reports/:id'),
})

metricsRoutes.report.href({ id: 'weekly' }) // /metrics/reports/weekly
```

```tsx
import { Text, defineScreen } from '@bud.sh/app/screen'
import { metricsRoutes } from './metrics-routes.ts'

export default defineScreen({
  routes: metricsRoutes,
  render: (_data, context) => (
    <Text>{context.route === 'report' ? context.params.id : 'All reports'}</Text>
  ),
})
```

配置元数据允许启动验证而不在服务器上运行屏幕模块. 每一条路线必须停留在屏幕的路径下. `context.route` 缩进 `context.params`· ; `context.url` 带有完整的当前位置。 在屏幕内导航可以保存其组件状态和已装入的数据. 当组件上下文变化时从该组件中获取特定路由的更新; `load` 仅在屏幕首次打开时运行.

被打开的屏幕在隐藏时也会被挂起 . `context.active` 当屏幕可见并拥有浏览器位置时告诉屏幕。 背景调节可以更新其数据,但应当将URL修改推迟到再次激活.

### 没有维特

```sh
npx bud [project-directory]                 # standalone, needs target.origin or target.port
npx bud doctor [project-directory]          # what's set up, and what the rest needs
npx bud comments migrate [project-directory] [--to bud:beads] [--dry-run]
```

这个 `bud` 命令随之而来 `@bud.sh/app` 需求 `target.origin` 或者说 `target.port` 在配置服务。 预览打开了这种方式不能被评论;为此使用Vite插件. Bud只显示项目设置的内容; `bud doctor` 说这是什么,其他需要什么. `bud capture` 是一个主机巴德的建造者运行.

### 任务链接

董事会住在这里 `/tasks`; 每个任务都有打字符 `/tasks/:id` URL (中文(简体) ). 打开任务保存了棋盘的过滤和滚动位置,后退返回到同一块棋盘. 复制链接和修改后点击使用相同的路由. 老年人 `?issue=` 链接在ID验证后永久重定向。 分级ID中的点由路由构建器编码.

### 评论

注释使用选中的线程适配器, 它默认为 Beads 。 初始化项目 Beads 工作空间在写作前明确; Bud 从不创建一个或选择隐藏倒置. 作者来自您的 Git 名和服务器上的电子邮件 。 一个讨论可以与多个 任务而不重复其信件。 打开讨论会载入其信件; 计数和 当后端返回有限制的视图时, 截线会保持清晰 .

写作使用您最后读取的讨论版本 。 冲突保留草案供审查 不确定的写作需要在重试前检查存储的讨论 . **同步** 明确 ,并使用所选适配器的现有远程配置.

与 `gitComments()`,讨论使用兼容性 `bud/comments` 树枝。 写入保存您的源分支,索引和工作文件 。 同步验证和 合并取来的记录,然后不强制地推出准确有效的执行 。 没有其他 应用程序存储选择会写入此注释 .

单位 **文件**,选择行并按 Ctrl/QQAlt+M 进行注释。 先省一编稿.

### 文件和审查链接

文件链接直接命名此地. 屏幕和链接帮助者共享的路由图 `@bud.sh/ui/routes`。 。 。 .

| 地点 | 網址 |
| --- | --- |
| 文件或目录 | `/files/src/app.ts` |
| 工作或分阶段审查 | `/files/review/working/src/app.ts` |
| 所有已更改的文件 | `/files/review/working` |
| 提交比较 | `/files/compare/HEAD...<full-object-id>/src/app.ts` |
| 选中源行 | `/files/src/app.ts#L12-L20` |
| 选中的 diff 线条 | `/files/review/working/src/app.ts#L12-R14` |

在diffs语中, `L` 是旧的一面和 `R` 新的一面。 复制的选中项打开其一个文件, 包括从所有文件审查中复制的文件 。 其可选 `at` 查询值是一个SHA-256内容摘要,用于检测已改变的源;它不是一个可地址的Git blob. 比较端点接受 `HEAD`,完整对象标识和完整 `refs/...` 名称。 被输入的构建器安全地编码了它们.

第一段的文件 `review`, (中文(简体) ), `compare`, (中文(简体) ), `blob` 或者说 `path` 使用情况 `/files/path/<actual-path>` 以避免路线相撞。 现有查询链接在项目和坐标验证后重新定向. 外国的遗产联系仍然被拒绝.

新链接属于伴侣的起源,请求仍然需要其会话能力. 如果一个不同的项目后来重新使用该来源,则书签不主张项目身份。 项目身份证继续覆盖当地偏好范围.

讨论使用情况 `/comments/:id`。巴德读取所选线程适配器并打开自有 画布、文件或任务屏幕,包括其保存的位置和谈话。 复制链接控制 使用此地址; 较旧 `?thread=` 链接在验证后永久重定向。 URL 载 只有线程ID,预览从未收到API能力.

### 移动 Git 注释

```sh
bud comments migrate --to bud:beads --dry-run
bud comments migrate --to bud:beads
```

命令加载工程的配置并使用其选定的线程适配器,除非 `--to` 超过它。 先初始化目标商店. 迁移不需要预览服务器或 `target.origin`,它永远不会改变配置或源 Git 注释.

扫描和代码抓取、状态、消息顺序、原始作者、时间戳和回复 祖相被还. 完整历史可以超过浏览器信件显示限制; 2; 源和目标仍然执行它们所配置的字节限制。 现有来源身份 被跳过,所以重运行命令可恢复部分迁移而不重复线程. 不确定的写入会停止运行, 并且永远不会自动重试 。 保留来源 Git 历史直到您审查过 输入的讨论.

## 警卫

巴德绑住回回转。 请求需要一个从未发送到预览页面的会场能力. Canvas在自己的无头浏览器中捕获页面. 页面以沙盒框显示它们,在项目本身的发源地上,它与巴德不同,只通过德夫桥来跟踪它们 `postMessage` 协议`@bud.sh/app/bridge`),一个从巴德自己的发源地服务的网站从未被陷害.

## 发展

```sh
pnpm dev       # Bud and the marketing site with HMR
pnpm verify    # all checks, including an installed-tarball browser test
```

见 [一般事务人员(其他职等)](https://npmcn.com/package/%40bud.sh/app/AGENTS.md) 为应用程序的结构.

## 相关软件包

-   [`@bud.sh/project`](https://npmcn.com/package/%40bud.sh/project/README.md) - 配置合同和装载
-   [`@bud.sh/ui`](https://npmcn.com/package/%40bud.sh/ui/README.md) - 组件
-   [`@bud.sh/comments`](https://npmcn.com/package/%40bud.sh/comments/README.md), (中文(简体) ), [`@bud.sh/files`](https://npmcn.com/package/%40bud.sh/files/README.md), (中文(简体) ), [`@bud.sh/beads`](https://npmcn.com/package/%40bud.sh/beads/README.md) - 域服务

## 常见问题

### @bud\.sh/app 是什么？

应用程序、其配置、屏幕和设计API

### 如何安装 @bud\.sh/app？

在项目目录运行 npm install @bud\.sh/app，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 bud，可以用 npx bud 直接运行。

### @bud\.sh/app 支持 TypeScript 吗？

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

### @bud\.sh/app 支持 ESM 还是 CommonJS？

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

### @bud\.sh/app 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=26\.12\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @bud\.sh/app 可以商用吗？

@bud\.sh/app 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @bud\.sh/app 的下载量有多少？

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

### @bud\.sh/app 还在维护吗？

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