# @bitakit/cli 中文文档

规范地址：https://npmcn.com/package/%40bitakit/cli/

版本：0\.2\.11
npm 元数据更新时间：2026-11-02T10:56:22.626Z
中文译文更新时间：2026-11-08T05:16:07.526Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：345 kB，36 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=24
- 运行依赖：7 个
- 首次发布：2026-10-17T18:08:09.762Z
- 最新版本发布：2026-11-02T10:56:22.252Z
- 近 30 天下载量：1907（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 13 个）

## 中文简介

BitaKit 项目命令:添加插件和贡献,与医生检查一个项目.

## 安装

```sh
npm install @bitakit/cli
```

也可以使用：`pnpm add @bitakit/cli`、`yarn add @bitakit/cli`、`bun add @bitakit/cli`

## README

# @bitakit/cli (英语)

这个 `bitakit` 命令用于 BitaKit 工程: 电线一个已有的应用程序, 添加插件及其文件 从模板中生成接线 迁移一个0.1项目 检查一个常见问题的项目, 并构建插件包。 0.2中新增.

创建 Apps 时 `@bitakit/create-app` 0.2 已经把它列为依赖性。 其他地方:

```sh
npm install --save-dev @bitakit/cli
```

运行它 `npx bitakit <command>` 安装时,或 `npx @bitakit/cli@latest <command>` 以直接使用最新发布的CLI.

## 连接已有的应用程序

```sh
npx @bitakit/cli@latest init
```

在已有的 Next.js 或 TanStack Start app 中, `init` 写入 `bitakit.config.ts`包装 `next.config` 与 `withBitaKit` (或添加) `bitakit()` 到 Vite 插件,挂载 `<BitaKitProvider>` 周围 `{children}` ,添加使 `<PluginPage />`,忽略 `src/bitakit.gen.*`,将代理规则附加到 `AGENTS.md` 并创造 `CLAUDE.md` 导入( 已有) `CLAUDE.md` 仅获得 `@AGENTS.md` 线条)。 还能提供 `bitakit-app-development` 用于 Codex 和 Claude 代码的本地项目文件夹中的技能; 已有 保存任一路径的技能(参见 [保持代理文件的时速](https://npmcn.com/package/%40bitakit/cli/#readme-keep-agent-files-current)) (中文(简体) ). 它印出它写的东西`+` 新建文件, `~` 更改文件)和什么 它跳过了。 已经携带了线条的文件从未被触动过,所以 安全运行; 无法编辑的形状( 例如普通JS) `next.config.js`)为 随行跳过以手相加. 未安装软件包 : `init` 列出缺失的 (单位:千美元)`@bitakit/core`, (中文(简体) ), `@bitakit/discovery`, (中文(简体) ), `@bitakit/ui` 和框架适配器,加 `@bitakit/cli` 以作为对 `bitakit` 页:1 然后运行 `generate` 财务报告和审定财务报表 `doctor`。 。 。 . `create-bitakit-app` 从同一模板为新应用程序写出相同的线条.

技能(`SKILL.md` 联 合 国 `references/` 将食谱复制到 `.agents/skills/` 用于编码和编码 大多数其他特工和 `.claude/skills/` 克劳德代码. `create-app` 0.2.2并随后列入 在新的应用程序中; `npx @bitakit/create-app .` 在只持有的文件夹中创建应用程序 `.git` 财务报告和审定财务报表 代理文件,所以技能着陆 一个开放的代理会话工作。 见 [技能读取](https://npmcn.com/package/%40bitakit/cli/skills/bitakit-app-development/README.md) 为了如何使用它 并请求尝试.

## 更新 BitaKit

保留每个 `@bitakit/*` 包在一个放行上(0.2.x,后为0.3.x). 只有那些 运出的内容被更改后得到补丁放出,因此补丁版本在一行内可能有所不同; `doctor` 接受并报告不同行的软件包是一个错误.

在一行之内, `npm update` 安装护理范围允许的最新补丁。 名称 `@bitakit/*` 软件包 `package.json` 列表(平面 `npm update` 更新每个依赖 :

```sh
npm update @bitakit/core @bitakit/ui @bitakit/next @bitakit/cli @bitakit/discovery
```

`package.json` 保持其范围; `package-lock.json` 记录新版本.

一条新线不在那些范围内。 全部安装 `@bitakit/*` 软件包在一个命令中, 这里 0.3; 各保持其位置在 `dependencies` 或者说 `devDependencies`数字 :

```sh
npm install @bitakit/core@0.3 @bitakit/ui@0.3 @bitakit/next@0.3 @bitakit/cli@0.3 @bitakit/discovery@0.3
```

不单独移动一个软件包( 例如) `npm install --save-dev @bitakit/cli@latest`: 一经 新线已出,将应用程序分出两行. 遵守新线路的升级指南 它有一个,然后刷新代理文件并检查工程:

```sh
npx bitakit init --update-agent-files
npx bitakit doctor
```

### 保持代理文件的时速

安装 `SKILL.md` 记录 CLI 版本和文件的校验和 前题 `metadata`。在更新 BitaKit 软件包后,运行:

```sh
npx bitakit init --update-agent-files
```

它安装了缺失的技能拷贝,用这个版本的技巧来替换一个没有编辑过的拷贝,并且 替换 BitaKit 块 `AGENTS.md` (在其 `bitakit-agent-rules` 标记) 当前的规则; 将自己的规则保留在该块之上或下方。 你编辑的手抄本是 保存并报告;删除其文件夹并再次运行命令取取出新版本. `doctor` 当副本缺失或大于已安装的 CLI 时, 当两个副本不同时, 或者当 页:1 `AGENTS.md` 块与现行规则不同.

## 添加一个特性

```sh
npx bitakit add plugin notes
```

这创造了 `src/plugins/notes/` 有页 `/notes` 和它的航行 动作;发现连接它,所以没有什么可以注册的. `--example` 写入完整 特性(服务) `notes.list`,事件,行动,页; `--minimal` 只有服务,它的 事件和一项行动.

所有三种模式也都自写插件 `AGENTS.md` 及其启动目的, 实际文件, 公共身份证和检查,加a `CLAUDE.md` 包含 `@AGENTS.md`。保持该本地指南当前 随着特性的发展;它没有被 `init --update-agent-files`。 。 。 .

将单个文件添加到已有插件( 插件包内, 只给出名称) :

```sh
npx bitakit add action notes/archive        # actions/archive.ts        → notes.archive
npx bitakit add service notes/search        # services/search.ts       → services.notes.search
npx bitakit add page notes/archive          # ui/pages/archive.tsx      → /notes/archive
npx bitakit add interceptor notes/audit     # interceptors/audit.ts
npx bitakit add config notes/limits         # configs/limits.ts         → app.config.notes.limits
npx bitakit add events notes                # events.ts
npx bitakit add layout auth/split           # src/layouts/auth/split.tsx → a candidate for layout.auth
npx bitakit add layout auth --plugin brand  # src/plugins/brand/ui/layouts/auth.tsx
```

文件路径决定 ID; 嵌入式名称, 如 `notes/team/invite` 创建 `actions/team/invite.ts` 带身份证 `notes.team.invite`。现有文件永远不会被覆盖.

在应用程序中,为已有插件添加无头测试 :

```sh
npx bitakit add test notes                  # tests/notes.test.ts at the app root
```

测试挂起 `src/plugins/notes` 与 `mountPlugin` 从 `@bitakit/core/testing`检查 插件启动, 然后停止; 当插件放置动作时包含 Shell 的站入 内 `shell.*` 插槽 。 命令打印应用程序的设置仍然缺少作为命令( 缺少 dev 依附关系, `"type": "module"`页:1 `test` 脚本),从不编辑 `package.json`。 。 。 .

## 生成和迁移

```sh
npx bitakit generate            # write src/bitakit.gen.* from the plugin folders and installed packages
npx bitakit generate --watch    # keep regenerating while files change
npx bitakit migrate --dry-run   # list the changes from a 0.1 layout
npx bitakit migrate             # apply them: bitakit.config.ts, folder-only files, ui/, generated imports,
                                # setup({ scope }), placement slot, slots.attach({ slot }), Foundation* →
                                # BitaKit* names and Core names moved from @bitakit/ui to @bitakit/core
```

框架适配器在 `dev` 财务报告和审定财务报表 `build`· ; `generate` 用于 脚本和类型检查。 移民后,审查diff,然后运行 `generate` 财务报告和审定财务报表 `doctor`。 。 。 . 移民 `bitakit.config.ts` 进口 `defineBitaKit` 从 `@bitakit/discovery`; 安装为 a 如果项目尚未列出, 则依赖 dev .

## 检查一个工程

```sh
npx bitakit doctor          # human-readable report, exit code 1 on problems
npx bitakit doctor --json   # for CI
npx bitakit info [--json]   # the plugins, services, actions, events and pages discovery finds
npx bitakit slots [--json]  # every slot you can fill: owner, accepts and this app's contributions
```

### 明确更新检查

```sh
npx bitakit doctor --check-updates  # read-only registry lookup
npx bitakit doctor --update         # authorized BitaKit updates and agent-file refresh
```

两个都接受 `--json`;两旗不能合并. 平面 `doctor` 地方卫生报告 和可用更新而无需安装任何东西. `--check-updates` 只注重更新. 登记失败使当地诊断及其退出状态保持不变 `updateStatus: "unavailable"`。每次检查都有限定的超时,没有重复. 检查报告运行中的 CLI, 项目宣布 `@bitakit/*` 软件包、已安装的版本、登记册 `latest`,范围/被过滤者, 和两个技能拷贝. `latest` 可以属于另一个释放线。 候选人是顾问: `npm-check-updates` 过滤器宣布范围和对等约束, 而软件包管理器 和项目测试验证已安装的图表。 无法获取的结果保持不变 `unknown`,带有 非零退出状态 `--check-updates`。注册/自动设置仍与检测到的npm、pnpm、Yarn或Bun一起 配置; 证书没有被打印 。 同行检查还可以读取其他依赖性.

`--update` 执行一次新检查, 然后使用项目的软件包管理器只升级 符合条件的 BitaKit 依赖在其限制范围内。 它拒绝允许 本地范围更新无法执行。 土著 解决可能更新必要的过渡依赖。 然后运行项目 - 本地CLI's 现有 `init --update-agent-files`,保留编辑技能和外部管理的用户文本 代理块。 安装失败在刷新前停止; 检查工程 diff 之前 重试中. 结果包括: `installedAfter` 无需再进行登记查询。 运行项目 检查后。 报告外部/全球的CLI,但从未沉默地取而代之;没有 项目本地CLI,代理文件得到保存,报告解释了如何刷新. 工作空间/目录/文件/URL依赖性规格报告为无依据而非 重写. 未知的软件包管理器或不完整的注册检查防止了突变.

用于替换(`single`插槽, `slots` 还有候选人从应用程序中打印出来的指纹 文档和 `choose` 内 `bitakit.config.ts` (单位:千美元)`renders app:split`,或 `renders the default: choose one of ...`(三); `--json` 添加 `selection: { candidates, renders, reason, choice }`组合文件 候选人数 `layout.<family>`。软件包可以在运行时添加候选人.

医生检查包版本,复制副本 `@bitakit/core`,配置包装器和 提供者线程,仍然强制Webpack的脚本或 `foundation-generate`,忽略生成 文件、插件页面和链接未到达路由、服务名称相撞, `requires` 条目 无名称、 插件依赖周期、 缺少软件包样式、 已贬值布局、 可替换 部分没有决定(应用程序文档中的若干候选人,或 `choose` 未知条目 或非单一槽)和代理文件不同步,并打印每个问题的固定.

这个 `requires` 检查读取字符串文字 `requires` 服务、行动、拦截器 内 `export const requires` 用于提供文件。 名字必须是一个服务身份,一个 `exposeAs` 或合同 `provides` 按钮或本地插件。 内有点名 本地插件的命名空间( n)`notes.list`) 被精确检查,包括对照转换的插件 关入 `plugins.overrides`合同等其他名称 `auth`,可以来自安装 来自主机的插件包 `services` 或来自其他文件中声明的密钥,医生不能 列表,因此只有在不存在这些列表时才对其进行检查。 图表检查报告周期 `dependencies` 联 合 国 `plugin.config.ts` 作为错误并启用了依赖已禁用插件作为警告的插件.

## 在无头浏览器中检查一页

插件页和插槽只在浏览器中渲染出,所以一个HTTP 200证明什么也没有. 与德夫尔 服务器运行, `check-page` 在无头铬中打开一页,并报告:

```sh
npx bitakit check-page /todos         # against --base-url, default http://localhost:3000
npx bitakit check-page /todos --json  # { "version": 1, ... } for agents and CI
npx bitakit check-page http://localhost:3230/todos --screenshot todos.png --timeout 60000
```

它等待网络闲置,等待BitaKit运行时间结束 (单位:千美元)`<html data-bitakit-runtime>`,设置 `@bitakit/ui`),然后报告最终URL,HTTP状态, 标题,h1-h3标题,摘要 `<main>`,运行时状态, BitaKit 错误( `[bitakit]` 控制台出错:启动失败, 如开发中关闭的插件, 以及 其他运行时间错误),控制台 错误和警告、页错误和失败的同源请求。 它一看见就带着一号离开 任何错误(警告不计数)和0. `--timeout` (默认为 3,000 ms) 装载 开始 JSON报告 `url`, (中文(简体) ), `finalUrl`, (中文(简体) ), `status`, (中文(简体) ), `title`, (中文(简体) ), `headings`, (中文(简体) ), `text`, (中文(简体) ), `textSource`, (中文(简体) ), `runtime` (单位:千美元)`ready`, (中文(简体) ), `starting`, (中文(简体) ), `failed`,或 `null` 没有BitaKit供应商, `networkIdle`, (中文(简体) ), `loadError`, (中文(简体) ), `bitakitErrors`, (中文(简体) ), `consoleErrors`, (中文(简体) ), `consoleWarnings`, (中文(简体) ), `pageErrors`, (中文(简体) ), `failedRequests`, (中文(简体) ), `screenshot`, (中文(简体) ), `errors` 财务报告和审定财务报表 `ok`。 。 。 .

囊括所有路由的答案是未知的路由,有状态200和"Page没有找到"状态,所以 读取标题和退出代码.

`check-page` 使用项目本身的 Playwright (`playwright` 或者说 `@playwright/test`永远不会 安装任何东西。 没有它,它就带着2号离开,并打印要运行的命令:

```sh
npm install --save-dev playwright
npx playwright install chromium
```

Linux( 容器, CI) 上安装 Chromium 及其系统库 : `npx playwright install --with-deps chromium`。无法启动的浏览器同时退出 2 .

## 构建插件包

在创建软件包中 `npx @bitakit/create-app my-plugin --plugin`数字 :

```sh
npx bitakit build          # types, compiled sources and dist/plugin.js
npx bitakit build --check  # type-check only
```

包裹 `package.json` 声明 `bitakit: { plugin: './plugin' }`; 安装 已建软件包自动发现插件.

### 槽声明或用户界面贡献

```sh
bitakit add slot-definition notes/header/tools  # slots/header/tools.ts, owned by notes
bitakit add slot notes/app-bar/end              # ui/slots/app-bar/end.tsx, contributes UI
```

在插件包中,略去插件前缀. `bitakit build` 汇编定义和扩充 `SlotMap`; 生成 `dist/plugin.slots.json` 是医生的静态清单. 随所出品入所出. 医生报告重复合同、组成部分/合同 不执行插件源, 不匹配和未解决的计算记录 。 这不能证明 安装了 UI 输出, 或者插件已经准备好 .

`bitakit build` 保留 `settings.ts` 财务报告和审定财务报表 `ui/settings/page.tsx` 在包装厂和 发送设置映射增强值 。 自定义/外页描述符、 已命名的页边框和 插槽 `when` 出口通过用于本地应用发现的同一种正常化产品.

## 检查和明确的安置移徙

`bitakit info` 财务报告和审定财务报表 `bitakit info --json` 使用共享目录计划:

```json
{ "version": 1, "static": { "plugins": [] }, "live": null }
```

这取代了以前的原始发现JSON. 保留文件 `resolution: "file"` 无法使用 ID 解决前; 已安装的软件包入口点 `pluginId`编号 :`declarations: null`。 。 。 . CLI 不执行插件来发明活性准备. 配置和设置值被省略 .

`bitakit slots` 回答"我能放在哪里?" 它列出了应用程序的档期合同,它的 启用插件和已安装的软件包(来自 `*.slots.json`),加上来自软件包的名称提示 清单和 `bitakit.config.ts`:同一套医生数. 人类的产物将它们分类 拥有者,每个插槽一行,包含其所接受的及其贡献计数. `--json` 指纹 :

```json
{
  "version": 1,
  "slots": [
    {
      "id": "todos.footer",
      "owner": "todos",
      "plugin": "todos",
      "contract": true,
      "accepts": "component",
      "policy": "list",
      "payload": false,
      "payloadKeys": [],
      "source": "src/plugins/todos/slots/footer.ts",
      "contributions": [
        {
          "kind": "component",
          "id": null,
          "plugin": "activity",
          "source": "src/plugins/activity/ui/slots/todos.footer.tsx"
        }
      ]
    }
  ],
  "unresolved": [],
  "unknownTargets": []
}
```

`owner` 是本地槽的插件 ID 或已安装的包名; 名称提示 有过 `contract: false`。 。 。 . `payloadKeys` 从字面上读取 `z.object({ ... })` (或另一个) `.object({ ... })` 计划。 贡献来自应用程序自己的文件: `ui/slots` 组件和组件 其字面意义 `slots` 列表槽名称; 软件包和 `setup()` 在运行时附加他们的. 没有被执行。 文件字面上不声明的值是 `null` (包装有效载荷,用于 无法读取的文件列表于 `unresolved`。 。 。 . `unknownTargets` 列表 向无人申报的空档提供捐款(`{ slot, kind, id, plugin, source }`),例如拼错 名称;它们无处可见。 人类输出在槽后列出两者.

```sh
bitakit add slot-definition notes/toolbar
bitakit add settings-page notes
bitakit migrate --navigation-slot shell.navigation --dry-run
# Review the diff before running the same explicit migration without --dry-run.
bitakit doctor
```

医生警告你 `groups: ['navigation']` 未经明确安排的行动 壳已安放. 选入迁移添加所选 `slots` 目标并保留逻辑 组合。 它跳过基于扩散的模糊对象;进口/计算申报需要人工操作 检讨. 没有群名会自动被重新解释为槽. 迁移扫描应用程序源 root; 外部包含的插件目录需要自己的审查 。 对于遗产0.1布局, 在预览位置变化之前完成/审查布局迁移.

`settings-page` 写入 `ui/settings/page.tsx` 并使用现有的 `renderField` 回调; `@bitakit/app-preferences` 必须安装。 它既不建立价值商店,也不建立导航 行动 模板从不覆盖已有文件 .

## 常见问题

### @bitakit/cli 是什么？

BitaKit 项目命令:添加插件和贡献,与医生检查一个项目\.

### 如何安装 @bitakit/cli？

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

### @bitakit/cli 支持 TypeScript 吗？

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

### @bitakit/cli 支持 ESM 还是 CommonJS？

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

### @bitakit/cli 需要什么版本的 Node\.js？

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

### @bitakit/cli 可以商用吗？

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

### @bitakit/cli 的下载量有多少？

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

### @bitakit/cli 还在维护吗？

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