@halcyonlabs/app

中文文档
0.47.0-halcyon.405发布于 2026/11/16SEE LICENSE IN LICENSETypeScriptES Module近 30 天下载 4.4万

npx 的 bb 应用程序发射器

中文使用文档
文档目录11 节
  1. 快速启动
  2. 先决条件
  3. 支持的主机环境
  4. 安装和运行
  5. 这个 bb 命令
  6. 从应用程序更新
  7. 国 际
  8. 使用 SDK 脚本
  9. 证书
  10. 配置
  11. 进一步阅读

Moonlet

月球

npm version

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

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

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

快速启动

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

先决条件

  • 节点.js 22.19, 24,或 26.
  • 盖特 Git.
  • 至少有一个受支持的代理提供者: 克劳德代码, (中文(简体) ), 代码通过非加太公司的诅咒, Pi,或另一个与非加太公司兼容的代理人.

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

支持的主机环境

  • 马科斯
  • 链接
通过 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 退出, 但对于文件的查看来说, 它比较慢, 也不太可靠 .

安装和运行

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

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

选择进入自动夜间频道:

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,则允许 安装的脚本 :

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

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

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,替换前一个。 发射器打印状态和日志 位置没有将服务输出转发到终端,因此停滞 终端无法屏蔽服务记录 。 用默认跟随一切 数据目录 :

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

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

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

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

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 是在你的路径:

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 :

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

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

使用 SDK 脚本

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

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运行 codex login 或按 Codex 文件配置证书.
claude-code安装 克劳德代码 并按其文件认证.
cursor安装 光标的代理CLI (单位:千美元)cursor-agent)并认证每个光标的文档.
pi安装 Pi 与 npm install -g @earendil-works/pi-coding-agent (0.84.0或更新)并按其文件进行认证;月球可以从设置运行安装.
opencode安装 打开代码 并按其文件认证.
grok安装 Grok 构建 认证 grok login 或者说 XAI_API_KEY。 。 。 .
hermes-agent安装 赫尔墨斯探员,以 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数字 :

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数字 :

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数字 :

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 行为,看 配置文件。 。 。 .

进一步阅读

版本与发布记录

@halcyonlabs/app 共发布 212 个版本,首次发布于 2026/10/25;过去 12 个月发布了 212 个版本。

版本发布日期距今
0.47.0-halcyon.405latest2026/11/161 天前
0.47.0-halcyon.4042026/11/161 天前
0.47.0-halcyon.4032026/11/161 天前
0.47.0-halcyon.4022026/11/161 天前
0.47.0-halcyon.4012026/11/151 天前
0.47.0-halcyon.3992026/11/151 天前

关于 @halcyonlabs/app 的常见问题

@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 和提交记录判断。