# @halcyonlabs/app 中文文档

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

版本：0\.47\.0-halcyon\.405
npm 元数据更新时间：2026-11-16T00:23:32.207Z
中文译文更新时间：2026-11-17T06:38:53.799Z
软件包许可：SEE LICENSE IN LICENSE

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

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

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

- 包体积（解压后）：104 MB，2781 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^22\.19\.0 \|\| ^24\.0\.0 \|\| ^26\.0\.0
- 运行依赖：11 个
- 首次发布：2026-10-24T18:31:23.770Z
- 最新版本发布：2026-11-16T00:23:31.983Z
- 近 30 天下载量：43510（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：212（近 12 个月 212 个）

## 中文简介

npx 的 bb 应用程序发射器

## 安装

```sh
npm install @halcyonlabs/app
```

也可以使用：`pnpm add @halcyonlabs/app`、`yarn add @halcyonlabs/app`、`bun add @halcyonlabs/app`

## README

![Moonlet](https://github.com/user-attachments/assets/4d9d02fb-c179-449b-a38a-041955143232)

# 月球

[![npm version](https://img.shields.io/npm/v/bb-app.svg)](https://www.npmjs.com/package/bb-app)

Moonlet是一种能自建的代理IDE. 它可以控制、定制和自动化 给自己的软件厂打下基础.

这个软件包提供了 `npx -y -p @halcyonlabs/app bb-app` 捆绑发射器 `bb` CLI 条目,以及 节点SDK导出. 每个表面——网络应用,CLI,和HTTP API——都是个 头等舱驾驶月球。 工作在线条中运行,你可以跟随现场,方向 任何一点,或向另一个特工交接.

> 注:月球正积极开发. 工作流量和表面仍在演变.

## 快速启动

Moonlet来自npm和管弦乐编码代理器 你已经安装.

### 先决条件

-   节点.js 22.19, 24,或 26.
-   盖特 Git.
-   至少有一个受支持的代理提供者: [克劳德代码](https://docs.anthropic.com/en/docs/claude-code), (中文(简体) ), [代码](https://developers.openai.com/codex/cli)通过非加太公司的诅咒, [Pi](https://github.com/earendil-works/pi/tree/main/packages/coding-agent),或另一个与非加太公司兼容的代理人.

如果你已经使用其中之一的提供者,月亮会取回您的现有 证书。 如果使用多个提供者,可以混合和匹配每个任务.

### 支持的主机环境

-   马科斯
-   链接

通过 WSL2 上的 Ubuntu 窗口

全部运行 `bb` 命令在 WSL2 内安装节点.js, Git, 以及您的提供商 CLIs 在WSL2 distro内部,并使用 Linux 风格的路径,例如 `/home/me/repo` 或者说 `/mnt/c/Users/me/repo`。 。 。 .

WSL2内部,使用Linux路径而不是驱动字母或UNC路径. 还原 建议在WSL文件系统内; `/mnt/c/...` 被故意支持,以便您能够保留现有的 Windows 退出, 但对于文件的查看来说, 它比较慢, 也不太可靠 .

### 安装和运行

```bash
npx -y -p @halcyonlabs/app@latest bb-app
```

然后打开 : `http://localhost:38886`

选择进入自动夜间频道:

```bash
npx -y -p @halcyonlabs/app@nightly bb-app
```

夜间版本从 `main` 可能不稳定 这个 `nightly` 离马厩不相干地运动 `latest` 标签.

npm 12 并随后被块依赖默认安装脚本. 月球需要这些 用于构建本地添加的脚本( e)`better-sqlite3`, (中文(简体) ), `node-pty`, (中文(简体) ), `@parcel/watcher`) (中文(简体) ). 没有他们,月亮就停了 `Could not locate the bindings file`。如果您的 npm 版本是 12 或晚于 12,则允许 安装的脚本 :

```bash
npx --allow-scripts=better-sqlite3,node-pty,@parcel/watcher -y -p @halcyonlabs/app@latest bb-app
```

或为所有全球安装设定一次政策:

```bash
npm config set allow-scripts=better-sqlite3,node-pty,@parcel/watcher --location=user
```

`npx -y -p @halcyonlabs/app@latest bb-app` 下载已发布的 `@halcyonlabs/app` 软件包,启动服务器并 本地主机守护进程, 并为网络应用程序服务 。 它存储月球管理状态 `~/.bb/` 默认。 如果任一管理的孩子进程出乎意料地退出,则 发射装置重新启动了那个孩子 而不阻止另一个孩子 新闻 `Ctrl+C` 内 以状态停止进程和退出的终端 `0`。 。 。 .

如果另一个活的月球拥有同一数据目录和a的运行时记录 在配置的本地地址上健康服务器答案, 启动退出 状态 `1` 不启动两个孩子的过程。 现有实例保留 运行中。 没有健康服务器的运行时间记录并不能阻止启动.

应用程序日志旋转到 `logs/server.N.log` 财务报告和审定财务报表 `logs/host-daemon.N.log` 在数据目录下,每个服务保存五个最新文件. 输出 绕过日志,例如启动错误和崩溃,直接转到 `logs/server-stdio.log` 财务报告和审定财务报表 `logs/host-daemon-stdio.log`。这些文件附加 整个重启;当一个超过 10 MB 的服务启动时,它被重新命名为 `-stdio.1.log`,替换前一个。 发射器打印状态和日志 位置没有将服务输出转发到终端,因此停滞 终端无法屏蔽服务记录 。 用默认跟随一切 数据目录 :

```bash
tail -F ~/.bb/logs/*.log
```

当stdout被重定向时,包括CI中,启动器状态输出是平坦的. 设定 `FORCE_COLOR=1` 请求颜色或 `NO_COLOR=1` 将其禁用; `NO_COLOR` 以优先为准。 在位进度更新需要一个 stdout TTY.

相同的产出捕捉适用于 `bb-server` 财务报告和审定财务报表 `bb-host-daemon`。 。 。 .

为了阻止在另一个终端或背景中运行的月球安装:

```bash
npx -y -p @halcyonlabs/app bb-app stop
```

`stop` 读取 `bb-app-runtime.json` 从数据目录中确认 录音过程其实是发射装置,然后停止。 过 `--data-dir` 何时 要停止的月球安装不使用默认 `~/.bb/`。 。 。 .

### 这个 `bb` 命令

从外出控制月球,打开 **设置 通用 命令行** 财务报告和审定财务报表 选择 **安装** 旁边 **月球类CLI**。月球上的线索已经 `bb`; 这个 用于您自己的终端、脚本和代理商在月球之外运行,例如 Claude Code 或 Codex (英语). 月球链接一个发射器从 `~/.bb/bin/bb` 输入文件夹 路径`~/.local/bin` 关于 Linux ; `/opt/homebrew/bin`, (中文(简体) ), `/usr/local/bin`,或 `~/.local/bin` (原始内容存档于2018-09-28). on macOS. 它在视窗上添加 `~/.bb/bin` 给用户的路径; 之后打开一个新的终端. **删除** 再来一次 月球离开任何 其他项目 `bb` 你已经有了位置.

从一个终端,之前 `bb` 是在你的路径:

```bash
npx -y -p @halcyonlabs/app bb settings cli-command install
```

### 从应用程序更新

当 Moonlet 有更新时, 设置 → 更新显示 **更新** 按钮(或运行) `bb updates app apply`) (中文(简体) ). Moonlet 将新版本下载到 `~/.bb/app-versions/`,然后重新连接页面。 月球没有 向后滚动: 如果新版本无法启动, 请运行新版本 (单位:千美元)`npx -y -p @halcyonlabs/app@latest bb-app`)或修因缘. 再见 `npx -y -p @halcyonlabs/app bb-app` 运行使用更新 已安装版本; 通过 `--bundled` 运行已下载的 npx 副本. 启动月球 `--no-in-app-updates` 以关闭应用程序更新.

服务器移动到另一台机器后,旧数据目录会保存 `server-moved.json`。 。 。 . `bb-app` 没有启动服务器: 它运行此计算机 主机守护进程对应于新服务器地址 `config.json`时重新启动 并回答旧服务器端口。 API 请求获取 `410 server_moved` 与新地址; 浏览器页面重定向到它以直接地址或链接 到它月球连接。 在搬回这台电脑的过程中 (单位:千美元)`server-import.json`),它为即将到来的服务器释放了端口. 何时 `server-moved.json` 离开,在移动完成或 `bb server unlock`, (中文(简体) ), 它再次启动服务器并在同一位置守护进程 . `bb-server` 有状态的退出 `3` 而不是开始,但返回移动的服务器除外.

从应用程序中添加或打开工程、启动线索并选择提供者 你想用那个线程.

## 国 际

包裹也暴露了 `bb` 已经运行的月球服务器的 CLI :

```bash
npx -y -p @halcyonlabs/app bb --help
```

CLI也一样 `BB_SERVER_URL` 和月球配置分辨率作为 SDK. 何时 未设置, 它针对的是默认本地软件包服务器 `http://127.0.0.1:38886`。 。 。 .

## 使用 SDK 脚本

软件包还显示驱动已运行的脚本的节点 SDK 月球服务器 :

```ts
import { BBSdk } from "bb-app";

const bb = new BBSdk();
const thread = await bb.threads.spawn({
  projectId: "proj_personal",
  environment: { type: "host", workspace: { type: "personal" } },
  prompt: "Summarize my active bb work.",
});
await bb.threads.wait({ threadId: String(thread.id), status: "idle" });
console.log(await bb.threads.output({ threadId: String(thread.id) }));
```

`new BBSdk()` 使用同样的 `BB_SERVER_URL` 月球配置分辨率为 CLI(英语:CLI). 过 `new BBSdk({ baseUrl: "http://host:38886" })` 用于远程或测试 (见下文远程访问说明)。 Moonlet推出的脚本已经收到 `BB_SERVER_URL` 财务报告和审定财务报表 `BB_THREAD_ID` 在他们的环境中.

## 证书

Moonlet 使用您配置的任何提供者 。 常见提供者 :

| 提供者 | 设置 |
| --- | --- |
| `codex` | 安装 [代码 CLI](https://developers.openai.com/codex/cli)运行 `codex login` 或按 Codex 文件配置证书. |
| `claude-code` | 安装 [克劳德代码](https://docs.anthropic.com/en/docs/claude-code) 并按其文件认证. |
| `cursor` | 安装 [光标的代理CLI](https://cursor.com/cli) (单位:千美元)`cursor-agent`)并认证每个光标的文档. |
| `pi` | 安装 [Pi](https://github.com/earendil-works/pi/tree/main/packages/coding-agent) 与 `npm install -g @earendil-works/pi-coding-agent` (0.84.0或更新)并按其文件进行认证;月球可以从设置运行安装. |
| `opencode` | 安装 [打开代码](https://opencode.ai/) 并按其文件认证. |
| `grok` | 安装 [Grok 构建](https://docs.x.ai/build/overview) 认证 `grok login` 或者说 `XAI_API_KEY`。 。 。 . |
| `hermes-agent` | 安装 [赫尔墨斯探员](https://hermes-agent.nousresearch.com/docs/getting-started/installation),以 `hermes model`,然后用 `hermes acp --check`。 。 。 . |

Moonlet为Codex, Claude Code, Pi, 索引了记录的本地技能根, Cursor, OpenCode, omp, Grok Build, 以及赫尔墨斯特工. 它包括用户根, 项目根和兼容根,例如 `.agents/skills`这些技能 在选中的提供者中显示 `/` 命令菜单。 技能页面和 `bb skill list` 显示 Claude Code、 Codex 和 Cursor 的本地技能。 月球还 读取配置的 Pi、 omp、 Grok 和 Hermes 技能目录, 并启用 提供者插件技能.

月光读取 Pi 全球 `~/.pi/agent` 文件和每个工作空间 `.pi` 文档. 这包括设置、证书、模型、包、扩展、技能、, 提示、主题和上下文文件。 Pi扩展可以添加模型和工具. Moonlet 只有在 Pi 保存或全球信任政策批准后才加载项目资源 工作空间。 未解决 `ask` 因为月亮没有皮,所以不能相信 信任即时. 你还可以使用 Pi CLI 和 `/login` 创建此配置.

自定义的非加太代理通过非加太供应商插件配置 `customAgents` 设置 : `bb plugin config provider-acp set customAgents '[...]'`选项的配置文件 `modelCli` 财务报告和审定财务报表 `reasoningCli` 或者说 `nativeReasoning` 推理设置。 可选 `nativeSkillRoots` 字段为作曲者添加提供者-本地技能。 内容 `user` 从目标主机主目录解析路径。 内容 `project` 路径 从选定的工作空间解析. 顶级 `sharedSkillRoots` 使用同样的 `user` 财务报告和审定财务报表 `project` 路径格式. Moonlet将这些来源列为只读技能. 月球把它们注入了Codex,克洛德, Pi,还有ACP线. 这允许为月球收集一件体能技能 独立供应商CLI.

## 配置

使用 `bb-app config` 用于持续的非机密包设置 `~/.bb/config.json`数字 :

```bash
npx -y -p @halcyonlabs/app bb-app config set BB_APP_URL https://<machine>.<tailnet>.ts.net
npx -y -p @halcyonlabs/app bb-app config list
npx -y -p @halcyonlabs/app bb-app config refresh
```

对于远程访问,请使用 Moonlet 连接或发布默认的回路监听器 (原始内容存档于2018-03-21). Tailscale Service. 直接尾网或局域网访问端口 `38886` 要求 明确、安全敏感 `--server-bind-host 0.0.0.0` 兼容选项; 见多分仪向导.

使用 `bb-app client ssh-target` 以配置本地编辑器打开远程 月球服务器下方 `~/.bb/client.json`。目标就是在 `ssh`,例如 `devbox` 或者说 `user@devbox`数字 :

```bash
npx -y -p @halcyonlabs/app bb-app client ssh-target set https://bb.example.test devbox --host-id host_abc
npx -y -p @halcyonlabs/app bb-app client ssh-target list
```

使用 `bb-app env` 提供商证书 `~/.bb/env.json`数字 :

```bash
npx -y -p @halcyonlabs/app bb-app env set OPENAI_API_KEY <key>
npx -y -p @halcyonlabs/app bb-app env list
npx -y -p @halcyonlabs/app bb-app env unset OPENAI_API_KEY
```

`env list` 编辑所有值。 配置和嵌入 询问正在运行的本地月球 服务器以重新装入; 如果月球停止, 数值在下次启动时适用.

用于所有配置密钥、 优先级、 启动旗和源码开发 `.env` 行为,看 [配置文件](https://github.com/get-bb/bb/blob/main/docs/configuration.md)。 。 。 .

## 进一步阅读

-   [主要读取](https://github.com/get-bb/bb#readme)
-   [平台支持](https://github.com/get-bb/bb/blob/main/docs/platform-support.md)
-   [配置](https://github.com/get-bb/bb/blob/main/docs/configuration.md)
-   [在多个设备上使用月球](https://github.com/get-bb/bb/blob/main/docs/multiple-devices.md)
-   [工作树设置和撕毁脚本](https://github.com/get-bb/bb/blob/main/docs/worktrees.md)

## 常见问题

### @halcyonlabs/app 是什么？

npx 的 bb 应用程序发射器

### 如何安装 @halcyonlabs/app？

在项目目录运行 npm install @halcyonlabs/app，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 bb、bb-app、bb-server、bb-host-daemon，可以用 npx bb 直接运行。

### @halcyonlabs/app 支持 TypeScript 吗？

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

### @halcyonlabs/app 支持 ESM 还是 CommonJS？

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

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

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

### @halcyonlabs/app 可以商用吗？

@halcyonlabs/app 使用 SEE LICENSE IN LICENSE 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

### @halcyonlabs/app 的下载量有多少？

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

### @halcyonlabs/app 还在维护吗？

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

