# @appforge-ci/agent 中文文档

规范地址：https://npmcn.com/package/%40appforge-ci/agent/

版本：0\.3\.29
npm 元数据更新时间：2026-10-24T09:15:27.207Z
中文译文更新时间：2026-11-06T18:02:30.825Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40appforge-ci/agent
原文对照：https://npmcn.com/package/%40appforge-ci/agent/?lang=original

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

- 包体积（解压后）：3.3 MB，443 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：7 个
- 首次发布：2026-09-23T07:59:49.944Z
- 最新版本发布：2026-10-24T09:15:26.988Z
- 近 30 天下载量：2519（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：36（近 12 个月 36 个）

## 中文简介

将Mac迷你变成舰队成员的建设者守护进程. 它会:

## 安装

```sh
npm install @appforge-ci/agent
```

也可以使用：`pnpm add @appforge-ci/agent`、`yarn add @appforge-ci/agent`、`bun add @appforge-ci/agent`

## README

# @appforge-ci/代理服务器

将Mac迷你变成舰队成员的建设者守护进程. 它会:

-   一次性在控制平面上注册 **入学人数 符号** 由仪表板(Fleet- 添加Mac迷你)生成.
-   每15秒发送一个心跳(CPU/mem/disk,当前构建, Tailscale) 如果安装了主机名) 并抓取任何待办事宜 **远程管理 命令** (排水、恢复、重启、重新启动、运行命名维护) 脚本),在同一反应中.
-   长波 `POST /agents/lease-job` - 从来没有入境港口 在麦克迷你机上打开了.
-   一次运行一个或多个构建( N)`resolveMaxConcurrentBuilds()` 内 `src/lib/config.ts` —— 说 `APPFORGE_MAX_CONCURRENT_BUILDS`编号 : `AgentConfig.maxConcurrentBuilds`,或从 CPU 自动检测出默认值 核心计数,上限为 4),每个计数器都在自己的任务范围目录中:克隆 复出,读取 `appforge.yaml`,运行工作流程 `scripts` 顺序 通过 `bash -lc`,溪流逐行记录,上传匹配 文物通过预先签名的 URL 直通 Cloudflare R2 然后报告 成功/失败。 见 `docs/fleet-management.md`'同时期建筑' 用于全景。 受管制的VPN建筑(承载 `sandbox`)是例外:它单独运行,而代理本身拒绝 与它共享 Mac (`src/lib/exclusive-builds.ts`, (中文(简体) ), `docs/vpn.md`, (中文(简体) ), "规范模式".

## 在Mac迷你电脑上设置

如果这回波已经克隆在机器上(对于你自己的笔记本电脑来说, 或任何迷你的东西 `git clone`d直接,有一个命令路径——看 `docs/self-hosting.md`'""添加一款Mac迷你"一节:

```bash
appforge-admin login --api-url <url> --admin-api-url <url>   # once
appforge-admin agents add-mac --name "mac-mini-1"
```

这要求入学证 读这台机器自己的信息, 注册并安装一个 `launchd` 服务( 无) `sudo`在一个步骤。 然后结束 登录它需要的(在服务器上撤销了符号并删除文件); `--keep-login` 保留它:登录是一个长寿的 表示房客们能用这个Mac来读 `cli-credentials-off-build-mac` 在那里检查失败; `docs/security.md`,"一个CLI登录 永远不要留在一个建Mac"。 下方的从擦出路径不需要登录 Mac .

对于一个完全没有这种再现克隆的从碎纸盒——没有 `git clone`,没有 `pnpm install` 实际安装两个CLI 需要从 npm 改为:

```bash
# 1. Prerequisites (once per machine) — see infra/mac-mini-setup/bootstrap.sh
#    for the full list (Homebrew, Xcode CLT, Node, CocoaPods, fastlane,
#    Android SDK/adb if you also build Android/Flutter/RN apps), or run
#    `appforge-admin agents bootstrap` once it's installed below (skips
#    the sudo/system-setting parts unless you pass --full).

npm install -g @appforge-ci/admin-cli @appforge-ci/agent
# ^ needs a version actually published first (tag-triggered
#   .github/workflows/publish.yml, gated on an NPM_TOKEN secret that
#   isn't set up on this instance yet) — 404s until then. See
#   packages/admin-cli/README.md's "Install" section for the
#   `npm link`-from-a-checkout path that works today.

# 2. Enroll — get a token with `appforge-admin agents enroll`:
appforge-agent enroll \
  --api-url https://your-admin-api-instance.example \
  --token afe_xxx \
  --name "mac-mini-1"
# Already enrolled? `enroll` refuses unless you pass --force. The control
# plane dedupes on this Mac's hardware UUID, so a re-enroll rotates the
# agent token and keeps the same fleet record — it can't make a duplicate.

# 3. Run it directly to sanity-check...
appforge-agent run

# 4. ...then Ctrl-C and install as a launchd service so it survives
#    reboots/logouts — no sudo, no copying files, points straight at
#    wherever npm just installed this binary:
appforge-agent install-service

# If another account is this Mac's auto-login account (a Mac that also hosts a
# GitHub Actions runner, say), a LaunchAgent would wait for a manual login after
# every reboot. Install the agent as a boot-time LaunchDaemon instead (asks for
# sudo; runs as your account; `--dry-run` previews every step):
appforge-agent install-service --daemon
```

`install-service` 旗帜 : `--daemon` (启动时间启动守护进程,见上文), `--dry-run` (与 `--daemon`数字 : 打印步骤和列表,不更改任何内容), `--force` (尽管运行的代理报告) 活动构建; 重新启动取消它们), `--drop-env` (让新的 plist drop 操作员按键, 如 `APPFORGE_SANDBOX_MONITOR` 列表被替换的套件和此 shell 不导出; 没有它,则 守护进程安装拒绝). 没有重新运行 `--daemon` 保留已安装的窗体. 细节、回滚和限制: `docs/fleet-management.md`,"代理服务表".

## 这个Mac会自己回来吗? `appforge-agent doctor`

只读检查,运行于Mac本身作为运行代理的用户. 它会回答什么 `docs/datacenter-readiness.md` 结束(拉起电源,代理机在 在不拉动电源的情况下:

```bash
appforge-agent doctor            # human-readable; exit 1 if anything fails
appforge-agent doctor --json     # the same, machine-readable, with a `rebootRecovery` roll-up
appforge-agent doctor --strict   # exit 1 on warnings too
```

| 组 | 检查 |
| --- | --- |
| 重新启动恢复 | FileVault 关闭; 代理服务器的服务启动时没有登录( 启动守护进程, 或启动代理服务器) **自动登录** gitHub跑腿的服务也一样; `autorestart` 开始 |
| 服务 | 每个安装 `com.appforge.*` 启动的任务是装入而不是冲洗;每个已建的应用程序( )`packages/agent`, (中文(简体) ), `apps/*`)可以解决其依赖性;服务不给一个版本贴上标签 `node`; 代理设备被安装为一个启动的任务( 不是一次启动守护进程和一个启动代理设备) ; 在服务配置(# 902) 中无法读取控制- 飞机密钥 ; 没有 CLI 登录令牌 `~/.appforge-admin` 或者说 `~/.appforge` (单位:千美元)`cli-credentials-off-build-mac`, # 904: 租户的建置像这个用户一样运行并且可以读取; 跳过没有代理的机器, 如操作员的笔记本电脑; 运行代理的心跳是新鲜的 |
| 东道主 | 从不睡在AC电源上;稳定的主机名(macOS) `HostName` 设置; 如果使用, 缩放为守护进程; 远程登录; 无密码 `shutdown -r now` 页:1 `REBOOT_HOST`; 免费磁盘 |
| 网络 | 默认的路由不是Wi-Fi; Wi-Fi 不与有线链接相接(一个Mac上的两个局域网地址); 当Wi-Fi _实值_ 链接,它最多损失了20平方英尺的2%到网关(a) `tart pull` (不恢复) 相机迷你机没有Wi-Fi,所以悄悄依赖它的迷你机在移动中无法幸存;跳过笔记本电脑,当VPN是默认路线时 |

一台笔记本电脑(battery present)跳过仅对无人看管的Mac重要的检查. `install-service` 财务报告和审定财务报表 `appforge-admin agents add-mac` 完成后打印重新启动恢复判决.

## 沙盒自试( 规范建筑)

当工作要求时,代理商可以在macOS Seatbelt sandbox 下运行一个建筑的脚本 (还没有问) 要检查这个 Mac:

```bash
appforge-agent sandbox-selftest                 # the matrix, against this Mac's real home; exit 0 pass / 1 fail / 2 inconclusive
appforge-agent sandbox-run --proxy-port 18888 -- /bin/bash -lc 'flutter pub get'   # one command under the same profile
```

代理在每次规范构建之前运行相同的矩阵,并且只有在操作员选择 显示器与 `APPFORGE_SANDBOX_MONITOR=1` (默认关闭;金丝雀 Mac 第一位),开始和每10次 还有几分钟 报告 `enforcementLevel: sandbox` 只有当它通过。 这是绕行的回归套件 上面列出的是课堂,而不是监禁的证据. `APPFORGE_SANDBOX_DISABLED=1` 是操作员杀死 切换: 设置在您运行的外壳中 `appforge-agent install-service` 从(被烤入) 启动列表 `APPFORGE_MAX_CONCURRENT_BUILDS`; 下一张列表的手编辑被删除 (原始内容存档于2018-10-21). Snock. 矩阵的无框控件简短地写到 `/opt/homebrew/bin` 财务报告和审定财务报表 `~/Library/LaunchAgents`一个丢弃的首选项域, 并提交一个启动的工作, 在每次运行。 程序和说明: `docs/manual-sandbox-validation.md`。 。 。 .

## 如何是建筑克隆人

每个 https 创建克隆(并获取其 `commitSha`) 带有 hermetic git : 没有系统或 global git 配置, 是空的 `$HOME`,没有 麻烦你,不急,不急,不急 `GIT_*`编号 :`SSH_*` 变量。 私人 GitHub 寄存器获得 GitHub App 的 1 小时代号 只在这种环境下; 所有其他的克隆都是匿名的, 所以Mac自己的登录(`gh`钥匙链, `~/.netrc`从来没有什么 克隆租户的仓库(appforge-ci#893). 一个ssh遥控器没有改变。 一个自负者,他的Mac服务 一个值得信赖的Ong和谁 使用该登录的克隆私有寄存器可选择返回 `APPFORGE_AMBIENT_GIT_CREDENTIALS=1` 运行在外壳中 `install-service` (像上面的把手一样被压入名单); 从来没有在运行其他兽人建筑的Mac上. `docs/github-app.md`。 。 。 .

## 远程管理,为什么它是一个许可列表

仪表盘只能发出八种命令之一 (单位:千美元)`DRAIN`, (中文(简体) ), `RESUME`, (中文(简体) ), `REBOOT_HOST`, (中文(简体) ), `RESTART_AGENT`, (中文(简体) ), `RUN_MAINTENANCE_SCRIPT`, (中文(简体) ), `UPDATE_AGENT`, (中文(简体) ), `CANCEL_BUILD`, (中文(简体) ), `TEST_TUNNEL`) -- -- 有: 故意没有"运行任意的外壳命令"终点. `UPDATE_AGENT` 排出毒剂,等待 每一个在飞行中,然后自我更新和 重新执行; `CANCEL_BUILD` 杀死一个完全命名的建筑进程组 在这个代理的并行槽中 见 `docs/fleet-management.md`是因为 命令表格. `RUN_MAINTENANCE_SCRIPT` 进一步 要求脚本名称已经存在于此机器的本地 `~/.appforge-agent/config.json` 下级 `maintenanceScripts`,例如:

```json
{
  "...": "... (written by `enroll`)",
  "maintenanceScripts": {
    "clear-derived-data": "rm -rf ~/Library/Developer/Xcode/DerivedData/*",
    "update-cocoapods": "sudo gem install cocoapods",
    "prune-simulators": "xcrun simctl delete unavailable"
  }
}
```

`REBOOT_HOST` 弹壳向外 `sudo /sbin/shutdown -r now`; 给代理人的 使用精确范围为该命令的顺从者条目(见 `infra/mac-mini-setup/bootstrap.sh`),不是被子苏道.

对于此许可列表以外的任何内容——交互式调试,安装一个 新 Xcode 版本, 监视一个被卡住的建筑的屏幕—— 使用真正的远程 桌面工具( Tailscale SSH, 苹果远程桌面, 或 `tailscale funnel`(原始内容存档于2019-09-25). /VNC. AppForge故意不重新执行远程外壳或 屏幕共享 _主机_; 见Docs/fleet-management.md. (本节) 浏览器中的“测试浏览器”特性不同: _模拟/模拟屏幕_ 用于制造的应用程序,而不是Mac迷你机自己的 桌面 — 见应用程序/设备流/README.md.)

## 常见问题

### @appforge-ci/agent 是什么？

将Mac迷你变成舰队成员的建设者守护进程\. 它会:

### 如何安装 @appforge-ci/agent？

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

### @appforge-ci/agent 支持 TypeScript 吗？

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

### @appforge-ci/agent 支持 ESM 还是 CommonJS？

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

### @appforge-ci/agent 可以商用吗？

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

### @appforge-ci/agent 的下载量有多少？

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

### @appforge-ci/agent 还在维护吗？

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