# @factiii/runner 中文文档

规范地址：https://npmcn.com/package/%40factiii/runner/

版本：0\.43\.0
npm 元数据更新时间：2026-11-13T14:18:16.339Z
中文译文更新时间：2026-11-14T08:17:02.040Z
软件包许可：ISC

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

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

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

- 包体积（解压后）：3.7 MB，45 个文件
- TypeScript 类型：未声明
- Node.js 要求：\>=20 \<25
- 运行依赖：1 个
- 首次发布：2026-05-07T02:14:18.927Z
- 最新版本发布：2026-11-13T14:18:16.120Z
- 近 30 天下载量：4452（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：56（近 12 个月 56 个）

## 中文简介

Factiii Runner, 运行董事会AI特工 在你控制的机器上。 在WebRTC上与Factii网络/移动客户端对等.

## 安装

```sh
npm install @factiii/runner
```

也可以使用：`pnpm add @factiii/runner`、`yarn add @factiii/runner`、`bun add @factiii/runner`

## README

# @ factiii/ runner (英语)

一个在您控制的机器上运行 Factiii's board AI 代理(Claude-驱动编码会话)的无头守护进程. 安装在工作站,dev box,或具有稳定网络连接的VM上. 代理直接运行在那台机器上,所以它可以驱动任何机器所能驱动的东西:模拟器,本土建筑,平台工具链. 移动和网络 [事实三](https://factiii.com/) 然后客户端通过WebRTC连接到它并卸载AI工作.

## 所需资源

-   节点20+
-   在 PATH 上的 git 和 tmux( 当空间首次打开时为您安装); redis, OrbStack 和 Tailscale 是可选的额外
-   代理人CLIs: `claude` 财务报告和审定财务报表 `codex`
-   可选,按特点分列: `sops` 财务报告和审定财务报表 `age` (Secrets),带有模拟器的Xcode(模拟面板,macOS)
-   一个事实账户
-   Factiii API 服务器的外部网络访问

## 安装

```bash
curl -fsSL https://factiii.com/runner.sh | sh
```

它安装了最新发布的 [github.com/事实三/运行者](https://github.com/factiii/runner/releases) 检查后 `.sha256`,在机器没有(或20至24外的一个)时带来自己的节点,然后运行 `factiii-runner setup`。再运行一次更新。 Npm在0.27.0之后 封锁了每个发布,所以 `npm install -g @factiii/runner` 安装旧版本,直到 npm 解锁软件包.

没有剧本 :

```bash
npm install -g https://github.com/factiii/runner/releases/download/v0.39.0/factiii-runner-0.39.0.tgz
factiii-runner setup
```

## 使用量

```bash
factiii-runner setup       # install and pair the connector, then list the parts
factiii-runner connect     # re-pair with a different account
factiii-runner start       # run the daemon (keep this process alive)
factiii-runner status      # show current config + credential storage state
factiii-runner parts list | add | remove | start | stop <part>   # pick what this runner does
factiii-runner doctor      # check what this machine needs, and fix what the runner may fix
factiii-runner service install | status | remove   # start at login, restart after a crash
factiii-runner password    # enter an old connection password once, to remove it (see Security notes)
```

`setup` 通过浏览器对等流将您带入, 并安装其它任何设备: 跑者从一个开始 **连接器** (支付加加密链接到你的设备). 完成之后, `factiii-runner start` 运行守护进程 。 其他的都是你加的部分(以下). 董事会自己的工具链(git,tmux,节点,Claude CLI,以及当它是Codex时的董事会提供商CLI)也安装在您在董事会上首次打开一个空间时,并在那里显示进度; `factiii-runner setup --tools` 从终端运行同样的安装.

### 部件

每个部分都说它做了什么,是否安装了它,以及它花费了多少磁盘和内存. 同样的列表在跑者状态下的应用程序中 > 特性,其中一个按钮会添加,去除,开始或停止一个部件,并安装在后台运行.

| 编 | 需求 |
| --- | --- |
| `terminals` | git, tmux, 脚本 |
| `claude` 编号 : `codex` | 节点和代理CLI |
| `secrets` | 索普斯和年龄 |
| `simulator` (macOS) (英语) | Xcode 和一个 iOS 模拟器 |
| `local-ai` | Ollama( 开始并停止运行) `ollama serve`(中文(简体) ) |
| `vault` | 它的数据库 PGlite( 安装到运行文件夹; 删除保存您文件的部分) |

-   `add` 运行 `doctor` 只满足这部分的需求。 有什么需要吗 `sudo` 或设置窗格被打印,永远不要运行.
-   `remove` 仅卸载什么 `add` 安装( 隐藏在 `parts.json` ,从不使用节点,git或脚本,也从不使用另一个已安装部分的工具.
-   机器上已经读取的部分是安装的,所以更新一个已存在的跑道不会改变什么.

`doctor` 当董事会报告“Couldn't初始化环境”时, 它打印了跑者需要的每个工具的解析位置,以及它所搜索的PATH,它将一个真正不存在的工具与跑者无法看见的地方安装的工具分开.

### 清单`doctor`(中文(简体) )

`doctor` 随时打印机器的核对表。 每个项目都说明哪个特性需要它,是否需要它,所以没有人为从未显示模拟器的跑者安装了Xcode. 只需要连接器的项目;每个工具都是可选的,由需要的部分命名. 一个未完成的项目有两件事:

-   **帮我弄好** 当不需要管理员时:一个工具Homebrew或npm安装(tmux, sops, 年龄,代理CLIs),或跑取器自己的文件夹. 跑者安装了工具,没有其他的.
-   **要复制的命令** 需要的时候 `sudo` 或者你的决定是:在 Linux (apt, dnf, paceman) 上制作软件包, 睡眠和电源设置, 自动登录, 被滞留 。 跑步者打印出它,从不运行.

此清单的工具( git, tmux, 脚本, 节点, claude, codex, redis, sops, 年龄, OrbStack, Tailscale) 也在应用程序中逐项显示, 在跑者状态下 > 特性下. 初始化安装了基础(git,tmux,脚本,节点,claude);每个附加(codex, redis用于终端,sops和年龄的活代理状态,OrbStack用于容器,Tailscale用于远程访问)都有自己的安装按钮,而Connect Codex则安装了代码. Tailscale's Instruction 也开始作为系统服务(你的密码,一次)进行尾缩放,让你成为它的操作员,然后运行 `tailscale up`: 打开它显示的“ 签名到尾图” 按钮, 或设置 `TAILSCALE_AUTH_KEY` (一个认证密钥,或者 OAuth 客户端的密钥 `?preauthorized=true` 和它的标记),在跑者的环境里加入,没有签入. 屏幕 分享后工作于 `vnc://<its tailnet IP>`甚至当Factiii倒下的时候.

`doctor` 当所需项目未得到满足时,出口1,否则为0。 没有终点站,或者 `--no-fix`,它只报告:它不要求任何东西,也不改变任何东西. `--json` 为脚本打印同一报表.

对Debian、Ubuntu或Fedora没有包装;有 `doctor` 在发布页上而不是提供安装.

### 永远`service`(中文(简体) )

```bash
factiii-runner service install   # start at login, restart after a crash
factiii-runner service status    # installed? running? what it runs, where it logs
factiii-runner service remove    # stop it and delete what install wrote
```

`setup` 在结尾提供此选项( “ 重新启动后继续运行 ” ) 。 它使用操作系统自己的服务管理器,用于当前用户,而不使用 `sudo`数字 :

|  | 安装了什么 | 何处 |
| --- | --- | --- |
| 马科斯 | a 发射代理 | `~/Library/LaunchAgents/com.factiii.runner.plist` |
| 链接 | 系统化用户服务 | `~/.config/systemd/user/factiii-runner.service` |
| 窗口 | 登录时的计划任务 | 任务 `FactiiiRunner`,文件输入 `~/.factiii-runner/service/` |

-   服务运行 `factiii-runner start` 和运行时安装的节点和跑道 `service install`还有那个终端的路口 如果你移动到另一个节点版本 或重新安装跑者在别的地方,运行 `service install` 重写文件并重新启动服务 .
-   它会在坠机后重新启动跑者,而不是在停机后:一个从设置中的账户中断开的跑者会一直被关闭 .
-   从应用程序工作上核准的更新,在无所事事的情况下(默认情况下),运行者也会自我更新; `factiii-runner update auto off`) (中文(简体) ). 它重新启动了自己;服务没有涉及。 未启动的新版本将回滚至以前的版本(`factiii-runner update status`) (中文(简体) ).
-   输出到 `~/.factiii-runner/logs/runner.log`。当它通过10 MB时,跑者复制到 `runner.log.1` (取代上一个)并空出它,在开始和一小时一次,所以这两个文件是它一直保存的.
-   如果在安装服务时(由手启动,或在另一个进程管理器下),一个跑者已经在运行,则该服务被写入而未启动,因此从没有两个. 拦住那个老家伙跑 `service install` 再来一次.
-   `install` 拒绝覆盖它没有写的同名文件 `remove` 只删除什么 `install` 写作.
-   一个跑者设置与 `FACTIII_RUNNER_DIR` 获得自己的服务名称和日志.

**和机器里没人一起重启之后.** 服务在用户登录时开始,打开跑者配置的密钥是在该用户的密钥链上,该密钥被锁定到那时. 所以无人看管的机器还需要一件事 由你来决定 跑者解释它,从来不做它:

-   **马可斯:** 自动登录( 系统设置 > 用户组 > 自动登录为) 。 这是一个安全交易:任何能够到达Mac的人都会得到登录的会话,而macOS在FileVault开机时不会提供.
-   **林纳:** `sudo loginctl enable-linger <user>` 在启动时启动用户服务。 登录密钥环仍需要解锁,以便跑者读取其配置.
-   **窗口 :** 自动登录( n)`netplwiz`和MacOS一样.
-   **睡眠和力量:** `service install` 财务报告和审定财务报表 `doctor` 打印命令( e)`pmset` 在macOS上,包括"在动力故障后自动启动". 他们从来没有运行过.

**重启后保密 .** 棋盘密码从未被存储 。 跑者自己回来,但每个板子的秘密都锁上,直到有人从应用程序中解锁.

### 今天每个平台都有什么用

-   **马可斯:** 以上一切诸相. 启动代理还没有被我们运行在真正的Mac上;其文件已被检查过 `plutil` 并且其命令被测试 假发射.
-   **林纳:** 运行者、核对表和服务文件已执行。 libsecret 键链路径和系统单元在真机(β)上未经测试.
-   **窗口 :** 一个主机板需要WSL2的跑道,因为tmux和redis没有Windows构建;在WSL2内部安装跑道并是一个Linux跑道. 在窗口本身 `doctor` 表示WSL2已缺失, 计划任务已执行但未经测试( β) .

## 安全说明

跑者自己储存的证书 `~/.factiii-runner/` - 每一个董事会的GitHub PAT(`<board>/.creds/`)和配对JWT(`config.json`(-是) **休息时加密** 在权限下使用 AES-256-GCM `0600`在同一个机键链键下 已存在的平文本文件在第一个读取时自动迁移;没有再铺平 。 董事会 `onedrive.json`,由自取消的跑取者 OneDrive 索引所留下,在第一个读取时被删除:无用. Claude/Codex的签名不在这份列表中:见下文提供商的签名.

**没有简单的背书.** 没有可用的密钥链的主机( 无 libsecret 的无头 Linux, CI 容器, 锁定的登录密钥环) 完全没有存储 : `setup` 拒绝, 而运行中的守护进程会连接, 但失败了每个证书读写 。 它告诉你缺少哪个工具以及如何安装,无论是在控制台上还是在跑步器设置中 ~ 秘密. 修复键盘,重启,它会拾起它留下的地方.

### 机器密钥, 和已丢失的连接密码

1.  **机器钥匙(总是).** OS键链中的32字节键——macOS键链,Linux上的libsecret,Windows上的DPAPI. 连接到登录的OS用户,因此守护进程工作无人关注. 跑者碰碰一个键链项`factiii-runner` 编号 : `config-encryption-key`),并且从不删除任何内容;如果该项存在但无法被读取,它会报告问题,而不是在顶端刻出一个替换.
2.  **连接密码( 已删除) .** 旧版本允许您在机器密钥上加个密码. 它将GitHub的连接(以及自退去的跑者OneDrive指数中的OneDrive)封入了数据密钥下(OneDrive Index)`vault-key.json`)),因此每次重启(包括自动更新)后,一个受密码保护的跑者会被锁起,无法克隆,部署,甚至无法显示GitHub用户的哪个被连接,直到有人输入. 密码无法再设置或更改 。 连接单独被密封在机器密钥下,就像配对配置,跑者在开始的时候会读取. 必须在密码后留下的值属于部署机密(以下).

**升级一个有密码集的跑者:一个解锁,然后永远不再.** 更改前编写的连接文件仍在旧信封中 。 没有密码集,它们会在第一次启动时转换。 有了密码,跑者需要它 **最后一次 最后一次**:它开始,连接,并报告这些文件为被锁定的文件(主机,和"跑者"设置 ~"秘密"),而不是"没有寄存器". 一次输入密码——在应用程序中,在终端提示中 `start` 显示,或与 `factiii-runner password` 在一个既无也无的主机上——每张棋盘的文件都是在机键下一起重写. 一个文件只有在解密后才能被重写,通过临时文件和重命名,所以一个失败的转换会留下旧文件原样. **来自应用程序的更新 永远不会等待在终端.** 自我更新后重启跳过终端提示,即使跑者是在终端启动的——没有人坐在那里——因此跑者与那些被锁定的连接连接起来,打印出问题和解锁方式,应用程序在任何一页都向它的主人询问提供更新的同一条旗上的密码. 一个被解锁的跑者 `factiii-runner password` 当它在几秒钟内运行通知,并告诉连接的客户.

**等保险库的文件走了.** 只要旧信封里没有留下任何文件——在开始的时候,或者在解锁之后—— `vault-key.json` 改为 `vault-key.retired.json` 而密码停止存在:以后不再重启请求。 一个拥有密码集但下面没有被封存的跑者在开始时会丢失密码而不被询问. 如果一个文件即使打开了金库也不会解密,它就留在原地并命名在控制台上,金库会一直停留到那个板被重新连接(它取代了文件).

### 供应商登录

Claude/Codex OAuth文件由这些CLI写入每个板的状态目录(`<board>/claude`, (中文(简体) ), `<board>/codex`)或OS键链,由CLI拥有. **跑者不加密他们.** 这个部分的一个更早的版本说,它们是在会话之间被封存的;没有代码这样做,文件与CLI留下的文件完全一样.

> **在Linux和Windows上的Beta. 互联网档案馆的存檔,存档日期2013-12-21.** 只有 macOS 键链路径被测试为结束 。 自由秘诀`secret-tool`并且Windows DPAPI路径被执行但未经验证——我们还没有机器来锻炼它们. 他们现在失败了关闭而不是有辱人格,因此预期的失败模式是"跑者说它不能存储证书",而不是沉默的平话. 如果打中了请报告.

这保护的是 **离线** 访问没有登录密钥链的文件:同步文件夹、备份、在另一台机器上读取的磁盘。 没错 **没有** 防范某人作为跑者OS用户签名,或失密跑者主机——守护进程总是可以读取它能使用的东西. 在你信任的机器上运行一个跑者 并且只有你拥有的账户.

部署 **秘诀** 面板是一个单独的商店,具有不同的模型: sops/age,在每次操作提供的密码下,从不缓存. 这两个密码是故意独立的——部署秘密从来不需要读取无人看管的,连接符号确实如此,这就是连接符号不再坐在任何密码后的原因. 见 `.specs/runner-secrets-store.md`。 。 。 .

## 常见问题

### @factiii/runner 是什么？

Factiii Runner, 运行董事会AI特工 在你控制的机器上。 在WebRTC上与Factii网络/移动客户端对等\.

### 如何安装 @factiii/runner？

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

### @factiii/runner 支持 TypeScript 吗？

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

### @factiii/runner 需要什么版本的 Node\.js？

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

### @factiii/runner 可以商用吗？

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

### @factiii/runner 的下载量有多少？

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

### @factiii/runner 还在维护吗？

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