pi-farm 0.2.1 → 0.2.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +44 -1
- package/bin/pp.js +5 -0
- package/completions/_pp +6 -0
- package/completions/pp.bash +13 -4
- package/docs/architecture.md +151 -0
- package/docs/autostart.md +166 -0
- package/docs/cli.md +207 -0
- package/docs/configuration.md +160 -0
- package/docs/development.md +129 -0
- package/docs/troubleshooting.md +204 -0
- package/package.json +2 -1
- package/src/autostart.js +7 -1
- package/src/commands.js +297 -0
- package/src/help.js +42 -0
- package/src/mesh.js +224 -0
package/README.md
CHANGED
|
@@ -27,6 +27,7 @@ pi-plus.yml ──► tmux new-session -d -s backend -c ~/code/backend -- pi --n
|
|
|
27
27
|
- **零依赖**:单文件 Node CLI,自带 YAML 子集解析器,不装 `js-yaml`、不需要 Python。
|
|
28
28
|
- **可脚本化**:`--json`、`--dry-run`、`--quiet`,退出码可用(`up` 有失败即 1)。
|
|
29
29
|
- **安全默认**:不经过 shell 拼接命令;tmux 名做白名单校验;重建前先 `check`。
|
|
30
|
+
- **直接跟别的 agent 说话**:`pp mesh ls/send` 直连 remote-pi 的本地 broker,按会话名或跨机地址发消息、拿 ACK、等回复。
|
|
30
31
|
|
|
31
32
|
## 安装
|
|
32
33
|
|
|
@@ -45,6 +46,9 @@ cd pi-plus && ./install.sh
|
|
|
45
46
|
|
|
46
47
|
依赖:Node.js ≥ 18、tmux、pi(非 pi 的 agent 也可以,见 `agent` 字段)。
|
|
47
48
|
|
|
49
|
+
> 若你的 `npm config get registry` 指向内网镜像(例如 Nexus),装不到这个包时显式指定公共源:
|
|
50
|
+
> `npm i -g pi-farm --registry https://registry.npmjs.org/`
|
|
51
|
+
|
|
48
52
|
Shell 补全(可选):
|
|
49
53
|
|
|
50
54
|
```bash
|
|
@@ -94,8 +98,40 @@ pp n api --save # 同时写进配置文件,重启后自动拉起
|
|
|
94
98
|
- 常用选项:`-C/--dir`、`--agent`、`--log`、`--save`、`-a/--attach`、`--no-remote-pi`、`--force`、`--dry-run`
|
|
95
99
|
- `pp new` 不依赖任何配置文件;`--save` 会在**没有配置时新建** `~/.pi/plus.yml`(或 `-c` / `$PI_PLUS_CONFIG` 指向的路径)并追加这一条
|
|
96
100
|
|
|
97
|
-
##
|
|
101
|
+
## 跟别的会话说话(mesh)
|
|
102
|
+
|
|
103
|
+
`pp` 直连 remote-pi 的本地 broker(`~/.pi/remote/sessions/local/broker.sock`),
|
|
104
|
+
不需要 pi 进程、不需要配对,本机和其它电脑上的 agent 都能发:
|
|
105
|
+
|
|
106
|
+
```bash
|
|
107
|
+
pp mesh ls # 谁在线(只读探测,不会让别人看到上下线)
|
|
108
|
+
pp mesh resolve backend # 配置里的会话 → mesh 地址 + 在线状态
|
|
109
|
+
pp mesh send backend "构建绿了,可以发版" # 会话名/序号都行
|
|
110
|
+
pp mesh send 1 macbook:/Users/me/code/api@api "ping" # 跨机直接写地址
|
|
111
|
+
pp mesh send all "5 分钟后重启机器" # 广播
|
|
112
|
+
pp mesh send backend "跑一下测试" --reply 60000 # 等它回话,收到就返回
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
- 单个目标 = 单播并等 broker 的 ACK:`delivered to …`(收到)、`busy`(对方正在跑,
|
|
116
|
+
消息被丢弃,稍后重试)、`denied`、超时;多个目标或 `all` = 组播,不等 ACK
|
|
117
|
+
- 加 `--reply <ms>` 会在 ACK 之后继续监听,把对方的回复打印出来(单播收到第一条就返回)
|
|
118
|
+
- 跨机地址形如 `macbook:/Users/me/code/api@api`;本机注册名默认 `pp-mesh`,用 `--as` 改
|
|
119
|
+
- 与 `pp send` 的区别:`pp send` 是往 tmux pane 里打字(对方当成"用户输入"),
|
|
120
|
+
`pp mesh send` 是走 agent 之间的消息通道(对方收到 `[agent-network] message from …` 信封)
|
|
121
|
+
- broker 没起来时会明确报 `no mesh broker at …`;`pp mesh ls/resolve` 可离线用来看地址
|
|
98
122
|
|
|
123
|
+
## 文档
|
|
124
|
+
|
|
125
|
+
| 文档 | 内容 |
|
|
126
|
+
| --- | --- |
|
|
127
|
+
| [docs/configuration.md](docs/configuration.md) | 配置参考:**全部字段**、restart 策略矩阵、remote-pi 三种模式、完整示例、校验规则 |
|
|
128
|
+
| [docs/cli.md](docs/cli.md) | 命令行参考:全局选项、退出码、每个命令的用法/JSON/env |
|
|
129
|
+
| [docs/autostart.md](docs/autostart.md) | 开机自启:systemd 单元为什么必须有 `KillMode=none`、linger、timer、launchd、WSL 两侧配置、冷启动验证 |
|
|
130
|
+
| [docs/architecture.md](docs/architecture.md) | 内部实现:模块职责、`up` 数据流、名字解析、restart 状态机、tmux 目标规则 |
|
|
131
|
+
| [docs/troubleshooting.md](docs/troubleshooting.md) | 排障手册:按报错原文查(起不来、`can't find pane`、名字不对、自启没生效、attach 乱码…) |
|
|
132
|
+
| [docs/development.md](docs/development.md) | 开发指南:跑测试、改代码的规矩、测试分层、发布流程(含 npm staged publishing 的坑) |
|
|
133
|
+
|
|
134
|
+
## 配置参考
|
|
99
135
|
```yaml
|
|
100
136
|
version: 1
|
|
101
137
|
|
|
@@ -242,6 +278,7 @@ pp status [name|#...] 状态表,第一列是 # 序号(--json 机器可
|
|
|
242
278
|
pp attach <name|#> 进入;不存在则先启动
|
|
243
279
|
pp logs <name|#> [-n 200] 打印滚动输出
|
|
244
280
|
pp send <name|#> "文本" 往 pane 里打字并回车(--no-enter 不回车)
|
|
281
|
+
pp mesh ls|resolve|send 直连 remote-pi broker:看谁在线 / 查地址 / 发消息(--reply 等回复)
|
|
245
282
|
pp check 校验配置
|
|
246
283
|
pp doctor 环境诊断(含自启状态、WSL 提示)
|
|
247
284
|
pp init 写示例配置
|
|
@@ -266,6 +303,8 @@ pp version 打印版本
|
|
|
266
303
|
|
|
267
304
|
## 开机自启
|
|
268
305
|
|
|
306
|
+
完整说明(`KillMode=none` 的原因、linger、timer、launchd、WSL 两侧、冷启动验证)见 [docs/autostart.md](docs/autostart.md)。
|
|
307
|
+
|
|
269
308
|
```bash
|
|
270
309
|
pp install # 开机/登录时按 restart 策略 up 一次
|
|
271
310
|
pp install --watch 300 # 另外每 5 分钟巡检,挂了自动补
|
|
@@ -330,6 +369,8 @@ sessions:
|
|
|
330
369
|
|
|
331
370
|
## 排障
|
|
332
371
|
|
|
372
|
+
完整版见 [docs/troubleshooting.md](docs/troubleshooting.md),这里是最常见的几行:
|
|
373
|
+
|
|
333
374
|
| 现象 | 处理 |
|
|
334
375
|
| --- | --- |
|
|
335
376
|
| `session "x" exited immediately` | `-v` 看实际命令;先用 `check` 确认 cwd/agent;临时加 `remain_on_exit: true` 看报错 |
|
|
@@ -340,6 +381,8 @@ sessions:
|
|
|
340
381
|
|
|
341
382
|
## 开发
|
|
342
383
|
|
|
384
|
+
详见 [docs/development.md](docs/development.md)。
|
|
385
|
+
|
|
343
386
|
```bash
|
|
344
387
|
npm test # node --test,纯单元测试,不需要 tmux
|
|
345
388
|
./test/e2e.sh # 端到端冒烟测试(需 tmux/pi,约 3 分钟,会临时装一个 systemd unit 再删掉)
|
package/bin/pp.js
CHANGED
|
@@ -64,6 +64,11 @@ function parseArgs(argv) {
|
|
|
64
64
|
case "--save": options.save = true; break;
|
|
65
65
|
case "--attach": options.attach = true; break;
|
|
66
66
|
case "--no-remote-pi": options.noRemotePi = true; break;
|
|
67
|
+
case "--as": options.as = takeValue(flag, inline); break;
|
|
68
|
+
case "--wait": options.wait = Number(takeValue(flag, inline)) || 5000; break;
|
|
69
|
+
case "--no-wait": options.noWait = true; break;
|
|
70
|
+
case "--body-json": options.bodyJson = takeValue(flag, inline); break;
|
|
71
|
+
case "--reply": options.reply = Number(takeValue(flag, inline)) || 0; break;
|
|
67
72
|
case "--local": options.local = true; break;
|
|
68
73
|
case "--path": options.path = takeValue(flag, inline); break;
|
|
69
74
|
case "--help": process.exit(showHelp(command));
|
package/completions/_pp
CHANGED
|
@@ -16,6 +16,7 @@ _pp() {
|
|
|
16
16
|
'attach:attach to a session (starts it if needed)'
|
|
17
17
|
'logs:print pane output'
|
|
18
18
|
'send:type text into a pane'
|
|
19
|
+
'mesh:remote-pi mesh (ls/send/resolve)'
|
|
19
20
|
'check:validate the config'
|
|
20
21
|
'doctor:environment diagnostics'
|
|
21
22
|
'init:write an example config'
|
|
@@ -45,6 +46,11 @@ _pp() {
|
|
|
45
46
|
'--no-remote-pi[do not set a remote-pi name for pp new]' \
|
|
46
47
|
'(-n --lines)'{-n,--lines}'[scrollback lines]:lines:' \
|
|
47
48
|
'--no-enter[do not press Enter after send]' \
|
|
49
|
+
'--as[mesh name to register as]:name:' \
|
|
50
|
+
'--wait[mesh ACK timeout]:ms:' \
|
|
51
|
+
'--reply[wait for a reply after the ACK]:ms:' \
|
|
52
|
+
'--no-wait[do not wait for the mesh ACK]' \
|
|
53
|
+
'--body-json[mesh body as JSON]:json:' \
|
|
48
54
|
'--watch[reconcile interval for install]:seconds:' \
|
|
49
55
|
'--print[print autostart unit and exit]' \
|
|
50
56
|
'1:command:->command' \
|
package/completions/pp.bash
CHANGED
|
@@ -4,7 +4,7 @@ _pp() {
|
|
|
4
4
|
COMPREPLY=()
|
|
5
5
|
cur="${COMP_WORDS[COMP_CWORD]}"
|
|
6
6
|
prev="${COMP_WORDS[COMP_CWORD-1]}"
|
|
7
|
-
local commands="new n create up start down stop restart status ls list attach a logs log send check validate doctor init install autostart uninstall version help"
|
|
7
|
+
local commands="new n create up start down stop restart status ls list attach a logs log send mesh check validate doctor init install autostart uninstall version help"
|
|
8
8
|
|
|
9
9
|
case "$prev" in
|
|
10
10
|
-c|--config)
|
|
@@ -14,22 +14,31 @@ _pp() {
|
|
|
14
14
|
--socket|--lines|-n|--agent|-C|--dir)
|
|
15
15
|
return 0
|
|
16
16
|
;;
|
|
17
|
+
mesh)
|
|
18
|
+
COMPREPLY=( $(compgen -W "ls list resolve send" -- "$cur") )
|
|
19
|
+
return 0
|
|
20
|
+
;;
|
|
17
21
|
attach|a|logs|log|send|down|stop|restart|up|start)
|
|
18
|
-
local cfg="" i
|
|
22
|
+
local cfg="" i names=""
|
|
19
23
|
for ((i = 1; i < COMP_CWORD; i++)); do
|
|
20
24
|
if [[ "${COMP_WORDS[i]}" == "-c" || "${COMP_WORDS[i]}" == "--config" ]]; then
|
|
21
25
|
cfg="${COMP_WORDS[i+1]}"
|
|
22
26
|
fi
|
|
23
27
|
done
|
|
24
28
|
if [[ -n "$cfg" && -r "$cfg" ]]; then
|
|
25
|
-
|
|
29
|
+
names=$(sed -n 's/^[[:space:]-]*name:[[:space:]]*\([^[:space:]#]*\).*/\1/p' "$cfg")
|
|
30
|
+
fi
|
|
31
|
+
if [[ "$prev" == "send" ]]; then
|
|
32
|
+
COMPREPLY=( $(compgen -W "all broadcast $names" -- "$cur") )
|
|
33
|
+
else
|
|
34
|
+
COMPREPLY=( $(compgen -W "$names" -- "$cur") )
|
|
26
35
|
fi
|
|
27
36
|
return 0
|
|
28
37
|
;;
|
|
29
38
|
esac
|
|
30
39
|
|
|
31
40
|
if [[ "$cur" == -* ]]; then
|
|
32
|
-
COMPREPLY=( $(compgen -W "--config --socket --json --dry-run --force --reconcile --quiet --verbose --lines --watch --print --path --no-enter --attach --log --save --no-remote-pi --dir --agent --help --version" -- "$cur") )
|
|
41
|
+
COMPREPLY=( $(compgen -W "--config --socket --json --dry-run --force --reconcile --quiet --verbose --lines --watch --print --path --no-enter --attach --log --save --no-remote-pi --dir --agent --as --wait --reply --no-wait --body-json --help --version" -- "$cur") )
|
|
33
42
|
return 0
|
|
34
43
|
fi
|
|
35
44
|
if [[ $COMP_CWORD -eq 2 && "${COMP_WORDS[1]}" == "help" ]]; then
|
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
# 架构与实现
|
|
2
|
+
|
|
3
|
+
本文讲 `pp`(npm 包 `pi-farm`)内部怎么跑起来:模块划分、一份 YAML 到「一个跑着 pi 的 tmux session」的完整链路、状态文件、restart 策略的状态机,以及几个不显然的实现决定。
|
|
4
|
+
|
|
5
|
+
## 设计目标
|
|
6
|
+
|
|
7
|
+
1. **一个名字贯穿三处**:tmux session 名、pi session 显示名(`--name`)、remote-pi mesh 里的 agent 名,默认都取 YAML 里的 `name`。
|
|
8
|
+
2. **声明式**:`pp up` 幂等;`pp ls` 一眼看清配置与现实的差距;重启后由 systemd/launchd 再跑一次同一份配置。
|
|
9
|
+
3. **零运行时依赖**:只用 Node 内置模块,`npm i -g pi-farm` 就是一次性安装,不需要编译、不需要 postinstall。
|
|
10
|
+
4. **不碰用户进程**:所有 agent 都跑在 tmux 里,`pp` 自己不常驻、不做守护进程(除了 systemd 的 oneshot 跑一次)。
|
|
11
|
+
|
|
12
|
+
## 模块
|
|
13
|
+
|
|
14
|
+
```
|
|
15
|
+
bin/pp.js 参数解析、命令分发、顶层错误 → 退出码
|
|
16
|
+
src/config.js YAML -> 规范化的 session 对象;路径发现;argv 构造;序号解析
|
|
17
|
+
src/yaml.js 零依赖 YAML 子集解析器(parseYaml / YamlError)
|
|
18
|
+
src/tmux.js tmux CLI 的薄封装(Tmux 类)+ paneTarget + resolveExecutable
|
|
19
|
+
src/remote-pi.js 读写 <cwd>/.pi/remote-pi/config.json,构造 REMOTE_PI_DIRECT_CONFIG
|
|
20
|
+
src/state.js 手动停止记录(XDG state),给 restart 策略用
|
|
21
|
+
src/mesh.js remote-pi broker 的零依赖客户端(探测 / 注册 / 发送 / ACK)
|
|
22
|
+
src/autostart.js systemd / launchd 单元渲染与安装/卸载/状态查询
|
|
23
|
+
src/commands.js 各子命令实现(up/down/restart/status/attach/logs/send/mesh/check/doctor/init/install/new)
|
|
24
|
+
src/help.js COMMANDS 单一数据源 + 总览/单命令页/拼写建议
|
|
25
|
+
src/example.js `pp init` 写入的示例配置
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
`src/help.js` 的 `COMMANDS` 是命令表的唯一来源:总览、单命令帮助、别名解析和拼写建议都由它生成,测试会断言「每个规范命令都有完整帮助页」,所以加命令时不会出现文档漂移。
|
|
29
|
+
|
|
30
|
+
## mesh 客户端(`pp mesh`)
|
|
31
|
+
|
|
32
|
+
`src/mesh.js` 直接说 broker 的换行分隔 JSON 协议(UNIX socket),不依赖 remote-pi 的代码,也不启动 pi:
|
|
33
|
+
|
|
34
|
+
```
|
|
35
|
+
pp mesh ls → {"type":"list_peers"} → body.peers 里的地址数组(只读,不注册)
|
|
36
|
+
pp mesh send → {"type":"register",name,cwd} → register_ack.address_assigned
|
|
37
|
+
→ {from,to,id,re:null,body} → {re:<id>, body:{type:"ack",status:"received|busy|denied"}}
|
|
38
|
+
← 对方回信 {re:<id>, from, body} ← --reply 期间打印并提前返回
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
几个要点:
|
|
42
|
+
|
|
43
|
+
- **为什么 `ls` 要"只读探测"**:broker 收到注册就会广播 `peer_joined`,别人的 UI 会闪一条通知;纯查询用 `list_peers` 不会改变任何人的 peer 列表。
|
|
44
|
+
- **会话名 → 地址**:`sessionMeshAddress()` 按 `<cwd>@<remote_pi_name>` 拼,`remote_pi_mode: off` 或没有名字时返回 `null`;broker 对同 `(cwd,name)` 的第二次注册会加 `#2` 后缀,`livePeersFor()` 把 `base` 和 `base#N` 都算作同一会话。
|
|
45
|
+
- **ACK 语义**:单播等 ACK,`busy` 意味着对方正在跑一轮、消息被丢弃(不是排队),所以 `pp` 直接报错让你重试;组播/广播没有逐条 ACK。
|
|
46
|
+
- **临时身份**:注册名默认 `pp-mesh`,`--as` 可改;进程退出即注销,别人看到的只是一条上下线。
|
|
47
|
+
- **回复**:`--reply <ms>` 在同一连接上继续等 `re === 本次 id` 的信封;单播拿到第一条就提前返回,组播/广播会一直收到窗口结束。
|
|
48
|
+
- **跨机**:地址前缀 `<pc>:` 由 broker leader 的 relay 桥完成,发送端无需配对;`pp mesh ls` 会显示 `PC` 列。
|
|
49
|
+
|
|
50
|
+
## 启动链路(`pp up`)
|
|
51
|
+
|
|
52
|
+
```
|
|
53
|
+
findConfigPath() -c / $PI_PLUS_CONFIG / ./*.yml / ~/.pi/plus.yml / $XDG_CONFIG_HOME/pi-plus
|
|
54
|
+
↓ loadConfigFile()
|
|
55
|
+
parseYaml() → normalizeConfig()
|
|
56
|
+
↓ 每条 session 变成
|
|
57
|
+
{ name, tmuxName, cwd, agent[], pi, piSession, piSessionDir, piSessionName,
|
|
58
|
+
remotePiName, remotePiMode, env{}, args[], log, remainOnExit, restart }
|
|
59
|
+
↓ selectSessions() 按名字/序号挑;裸 up 跳过 restart:no 与会话被手动停止的(--reconcile 时)
|
|
60
|
+
↓ prepareSession() mkdir 日志目录;remote_pi_mode: config 时写 <cwd>/.pi/remote-pi/config.json
|
|
61
|
+
↓ launchSpec() remote_pi_mode: env 时注入 REMOTE_PI_DIRECT_CONFIG=<合并后的 JSON>
|
|
62
|
+
↓ tmux.create() tmux new-session -d -s <tmuxName> -c <cwd> -- env K=V ... <argv>
|
|
63
|
+
↓ pipe-pane / remain-on-exit (配置了 log 才挂日志;restart:no 自动 -w remain-on-exit)
|
|
64
|
+
↓ verifyStartup() 等 600ms,检查 session 是否还在、pane 是否 dead,失败时回放 pane 内容
|
|
65
|
+
↓ clearStopped() 清掉「手动停止」记录
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
`buildSessionArgv()` 决定 pi 的参数顺序,这是唯一给 pi 加参数的地方:
|
|
69
|
+
|
|
70
|
+
```
|
|
71
|
+
<agent...> [--name <pi_session_name>] [--session-dir <dir>]
|
|
72
|
+
[--session <path> | --session-id <id>] <args...>
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
只有 `pi`(即 `basename(agent[0]) === "pi"`,或显式 `pi: true`)才会加这些参数;`agent: bash` 之类的会话原样执行。
|
|
76
|
+
|
|
77
|
+
## 名字解析(三处名字 + 序号)
|
|
78
|
+
|
|
79
|
+
| 目标 | 字段 | 默认 |
|
|
80
|
+
|---|---|---|
|
|
81
|
+
| tmux session | `tmux_name` | `name` |
|
|
82
|
+
| pi session 显示名 | `pi_session_name` | `name`(`null` 表示不加 `--name`) |
|
|
83
|
+
| remote-pi agent | `remote_pi_name` | `name`(`false` 表示不设置) |
|
|
84
|
+
|
|
85
|
+
pi 的 **session id**(`pi_session`)是另一回事:它是「续接哪段对话」,和显示名无关。给 id 用 `--session-id`,给 `.jsonl` 路径用 `--session`,由 `isSessionPath()` 判断。
|
|
86
|
+
|
|
87
|
+
CLI 里凡是收 `<name>` 的地方都支持序号:`resolveSessionRef()` 先按 `name`/`tmuxName` 精确匹配,再按配置顺序把纯数字当成 1-based 下标(就是 `pp ls` 第一列的 `#`)。名字优先于序号,所以真有会话叫 `3` 时不会被序号抢走。
|
|
88
|
+
|
|
89
|
+
## restart 策略的状态机
|
|
90
|
+
|
|
91
|
+
`restart` 决定「谁在什么情况下把会话拉起来」,语义对齐 docker compose:
|
|
92
|
+
|
|
93
|
+
| 策略 | 裸 `up` | `up --reconcile`(自启/watch) | `up <name>`(手动点名) | pane 崩溃后 |
|
|
94
|
+
|---|---|---|---|---|
|
|
95
|
+
| `no` | 不参与 | 不参与 | 重建 | 保留 dead pane(自动 `remain-on-exit`),`pp logs` 仍可看 |
|
|
96
|
+
| `always` | 启动 | 启动 | 重建 | 下次 `up`/巡检重启 |
|
|
97
|
+
| `on-failure` | 启动 | 手动 `down` 过的跳过 | 重建 | 下次 `up`/巡检重启 |
|
|
98
|
+
| `unless-stopped` | 启动 | 手动 `down` 过的跳过 | 重建 | 下次 `up`/巡检重启 |
|
|
99
|
+
|
|
100
|
+
「手动 `down` 过」这件事记在状态文件里(见下节),`clearStopped()` 会在成功启动后清除;这正是 compose 里 `unless-stopped` 与 `always` 的区别。
|
|
101
|
+
|
|
102
|
+
判断一个会话「要不要重建」靠一次 `tmux list-panes -a` 快照:session 不存在 → 创建;存在但所有 pane 都 dead → 重建;存在且活着 → 跳过(`--force` 例外)。
|
|
103
|
+
|
|
104
|
+
## 状态文件
|
|
105
|
+
|
|
106
|
+
```
|
|
107
|
+
$XDG_STATE_HOME/pi-plus/state.json (默认 ~/.local/state/pi-plus/state.json)
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
结构是以**配置文件的绝对路径**为 key 的桶:
|
|
111
|
+
|
|
112
|
+
```json
|
|
113
|
+
{
|
|
114
|
+
"/home/user/.pi/plus.yml": {
|
|
115
|
+
"backend": { "stopped": true, "at": "2026-11-18T09:12:03.114Z", "reason": "down" }
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
- 用配置路径做 key,所以同一个会话放在两份配置里互不影响
|
|
121
|
+
- 读取对损坏的 JSON 容错(返回 `{}`),不会因为半个字节把 `pp ls` 弄挂
|
|
122
|
+
- 只在 `down` 且策略为 `unless-stopped`/`on-failure` 时写
|
|
123
|
+
|
|
124
|
+
## tmux 交互细节
|
|
125
|
+
|
|
126
|
+
- **pane 目标必须带冒号**:`send-keys`/`capture-pane`/`pipe-pane`/`set-option -w` 用 `=name:`(`paneTarget()`),而 `has-session`/`kill-session` 用 `=name`。混用会得到 `can't find pane: =xxx`。
|
|
127
|
+
- **幂等检查用只读模式**:`Tmux.run(..., { readOnly: true })` 在 `--dry-run` 下依然真实执行,否则 dry-run 时 `sessionExists()` 会因为「命令没跑」而谎报会话不存在。
|
|
128
|
+
- **日志**:`log:` 用 `pipe-pane -o -t =name: "cat >> '<path>'"`,`prepareSession()` 提前 `mkdir -p` 日志目录,否则首次开机写入会静默失败。
|
|
129
|
+
- **socket 隔离**:`tmux.socket` / `--socket X` 等价于 `tmux -L X`,端到端测试靠它完全隔离,不碰默认 socket 上的生产会话。
|
|
130
|
+
|
|
131
|
+
## systemd / cgroup 的坑(`KillMode=none`)
|
|
132
|
+
|
|
133
|
+
单元是 `Type=oneshot`,`ExecStart=... pp up --config <cfg> --reconcile`。默认 `KillMode=control-group` 意味着**单元结束时 systemd 会把它 cgroup 里的所有进程杀干净**——而 tmux server 正是这个单元的孙进程。结果就是:日志显示 `Result=success`,会话却一个都不剩。
|
|
134
|
+
|
|
135
|
+
所以渲染出的单元里固定带 `KillMode=none`,让 tmux 与 agent 逃出这次清理。用真实单元的副本做过冷启动验证:加 `KillMode=none` 前「成功但零会话」,加之后会话存在、单元退出后仍在、崩溃后 `--reconcile` 能复活。
|
|
136
|
+
|
|
137
|
+
`--reconcile` 就是给这种「非用户交互」场景用的:跳过被手动 `down` 掉的 `unless-stopped`/`on-failure`,其余按策略启动/重建。
|
|
138
|
+
|
|
139
|
+
## remote-pi 名称的两种注入方式
|
|
140
|
+
|
|
141
|
+
remote-pi 的 agent 身份是 `<cwd>@<name>`,name 存在**每个目录**下的 `.pi/remote-pi/config.json`(字段 `agent_name`),`/remote-pi rename` 改的也是这个文件。
|
|
142
|
+
|
|
143
|
+
- `remote_pi_mode: config`(默认):`pp` 在启动前把 `agent_name` 写进那个文件,和 `/remote-pi rename` 的效果一致,重启后仍在。**同一目录只能有一个名字**,所以两个会话共用 cwd 且名字不同时 `normalizeConfig()` 会警告,并建议改用 env。
|
|
144
|
+
- `remote_pi_mode: env`:不写文件,用 `REMOTE_PI_DIRECT_CONFIG`(内联 JSON,remote-pi 优先读它)把「文件里的其它选项 + 我们的 agent_name」传给 pi。适合共享目录、临时会话(`pp new` 默认用它)。
|
|
145
|
+
- `remote_pi_mode: off` / `remote_pi_name: false`:完全不设置。
|
|
146
|
+
|
|
147
|
+
## 测试与可观测性
|
|
148
|
+
|
|
149
|
+
- `--dry-run` 打印真正会执行的命令(`tmux new-session ...`、`tmux send-keys ...`),CI 与人工排查都用它。
|
|
150
|
+
- `--json` 给机器读:`up` → `{started,skipped,failures}`,`ls` → 行数组,`check` → `{ok,problems,notes,config}`,`doctor` → `{checks,warnings}`。
|
|
151
|
+
- 单元测试覆盖 YAML 解析、配置归一化、restart 策略、状态文件、单元渲染、帮助页与 `pp new`;端到端脚本 `test/e2e.sh` 用独立 socket 跑 86 项真实交互。
|
|
@@ -0,0 +1,166 @@
|
|
|
1
|
+
# 开机自启
|
|
2
|
+
|
|
3
|
+
目标:机器(或 WSL 发行版)启动后,`~/.pi/plus.yml` 里的会话自动跑起来;崩溃的会话按 `restart` 策略复活。
|
|
4
|
+
|
|
5
|
+
`pp install` 装的是一个 **oneshot** 单元/任务:开机跑一次 `pp up --config <cfg> --reconcile --quiet`,跑完就退出,agent 留在 tmux 里。`pp` 本身不常驻。
|
|
6
|
+
|
|
7
|
+
## Linux:systemd user unit
|
|
8
|
+
|
|
9
|
+
安装 `~/.config/systemd/user/pi-plus.service`:
|
|
10
|
+
|
|
11
|
+
```ini
|
|
12
|
+
[Unit]
|
|
13
|
+
Description=pi-plus: start pi agents in tmux
|
|
14
|
+
Documentation=https://github.com/HardyDou/pi-plus
|
|
15
|
+
After=default.target
|
|
16
|
+
|
|
17
|
+
[Service]
|
|
18
|
+
Type=oneshot
|
|
19
|
+
RemainAfterExit=yes
|
|
20
|
+
# tmux must outlive this unit: systemd would otherwise kill the sessions
|
|
21
|
+
# in this unit's cgroup as soon as the oneshot run finishes.
|
|
22
|
+
KillMode=none
|
|
23
|
+
WorkingDirectory=%h
|
|
24
|
+
Environment=PATH=<node 目录>:<项目 bin>:~/.local/bin:/usr/local/bin:/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin:/usr/bin:/bin
|
|
25
|
+
ExecStart=/usr/bin/env node "<pp.js 绝对路径>" "up" "--config" "<配置文件>" "--reconcile" "--quiet"
|
|
26
|
+
TimeoutStartSec=300
|
|
27
|
+
Nice=5
|
|
28
|
+
|
|
29
|
+
[Install]
|
|
30
|
+
WantedBy=default.target
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
几个关键点:
|
|
34
|
+
|
|
35
|
+
- **`KillMode=none` 必须有**。默认 `KillMode=control-group` 会在单元结束时清空其 cgroup,而 tmux server 是它的子进程——现象是 `Result=success` 但会话一个不剩。改之前/之后都用真实单元做过冷启动验证。
|
|
36
|
+
- **`RemainAfterExit=yes`**:让单元停在 `active (exited)`,`systemctl --user status` 能看到「跑过且成功」。
|
|
37
|
+
- **PATH 要写死**:systemd 不读你的 shell 配置,`pi`/`node` 在 nvm 里时必须显式给出目录。`pp` 会自动把「当前 node 所在目录」和「项目自己的 `node_modules/.bin`」拼进去。
|
|
38
|
+
- **不要依赖 `--socket`**:单元里不会传命令行 `--socket`,会话的 socket 由配置文件里的 `tmux.socket` 决定。用 `--socket` 临时调试的会话,自启时会在默认 socket 上重建。
|
|
39
|
+
|
|
40
|
+
安装/操作:
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
pp install # 写单元 + enable + start
|
|
44
|
+
pp install --print # 只看内容,不落盘
|
|
45
|
+
pp install --watch 120 # 再装一个每 120 秒巡检的 timer
|
|
46
|
+
systemctl --user status pi-plus.service
|
|
47
|
+
systemctl --user list-timers | grep pi-plus
|
|
48
|
+
journalctl --user -u pi-plus.service -n 50
|
|
49
|
+
pp uninstall # 停用 + 删除
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
### 没登录也想跑:linger
|
|
53
|
+
|
|
54
|
+
systemd user unit 默认随「用户登录」启动。服务器上希望开机就跑(不等 SSH 登录):
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
sudo loginctl enable-linger "$USER"
|
|
58
|
+
loginctl show-user "$USER" -p Linger # Linger=yes
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
`pp doctor` 会显示 `autostart systemd, enabled, last run ok`;`pp install` 在没开 linger 时会提示这条命令。
|
|
62
|
+
|
|
63
|
+
### 定时巡检:`--watch`
|
|
64
|
+
|
|
65
|
+
装 `pi-plus.timer`:
|
|
66
|
+
|
|
67
|
+
```ini
|
|
68
|
+
[Unit]
|
|
69
|
+
Description=pi-plus: reconcile tmux sessions
|
|
70
|
+
|
|
71
|
+
[Timer]
|
|
72
|
+
OnBootSec=45s
|
|
73
|
+
OnUnitActiveSec=300s
|
|
74
|
+
AccuracySec=30s
|
|
75
|
+
Persistent=true
|
|
76
|
+
Unit=pi-plus.service
|
|
77
|
+
|
|
78
|
+
[Install]
|
|
79
|
+
WantedBy=timers.target
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
`pp up --reconcile` 每次都会跳过被手动 `down` 过的 `unless-stopped`/`on-failure` 会话,所以巡检不会违背你的手动操作。
|
|
83
|
+
|
|
84
|
+
## macOS:LaunchAgent
|
|
85
|
+
|
|
86
|
+
安装 `~/Library/LaunchAgents/com.pi-plus.plist`:
|
|
87
|
+
|
|
88
|
+
```xml
|
|
89
|
+
<key>Label</key><string>com.pi-plus</string>
|
|
90
|
+
<key>ProgramArguments</key>
|
|
91
|
+
<array>
|
|
92
|
+
<string>/usr/bin/env</string><string>node</string>
|
|
93
|
+
<string>/usr/local/lib/node_modules/pi-farm/bin/pp.js</string>
|
|
94
|
+
<string>up</string><string>--config</string><string>/Users/you/.pi/plus.yml</string>
|
|
95
|
+
<string>--reconcile</string><string>--quiet</string>
|
|
96
|
+
</array>
|
|
97
|
+
<key>EnvironmentVariables</key><dict><key>PATH</key><string>…</string></dict>
|
|
98
|
+
<key>RunAtLoad</key><true/>
|
|
99
|
+
<key>ProcessType</key><string>Background</string>
|
|
100
|
+
<key>ThrottleInterval</key><integer>30</integer>
|
|
101
|
+
<key>StandardOutPath</key><string>~/Library/Logs/pi-plus.log</string>
|
|
102
|
+
<key>StandardErrorPath</key><string>~/Library/Logs/pi-plus.log</string>
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
`pp install` 用 `launchctl bootstrap gui/$UID`(失败回落 `launchctl load -w`)。`--watch N` 只会加 `StartInterval`,因为 launchd 没有独立的 timer 概念。
|
|
106
|
+
|
|
107
|
+
日志:`tail -f ~/Library/Logs/pi-plus.log`。
|
|
108
|
+
|
|
109
|
+
## WSL2:只有里面装是不够的
|
|
110
|
+
|
|
111
|
+
WSL2 的发行版**不会**在 Windows 重启后自己启动——它由某个 `wsl.exe` 调用拉起来。所以「重启后自动恢复」需要两边:
|
|
112
|
+
|
|
113
|
+
**WSL 内部(`pp install` 负责)**
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
# /etc/wsl.conf 里有
|
|
117
|
+
[boot]
|
|
118
|
+
systemd=true
|
|
119
|
+
|
|
120
|
+
[user]
|
|
121
|
+
default=youruser
|
|
122
|
+
|
|
123
|
+
pp install
|
|
124
|
+
sudo loginctl enable-linger "$USER"
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
**Windows 侧(需要你手动做一次)**
|
|
128
|
+
|
|
129
|
+
登录时触发一次 `wsl.exe`,启动项里放一个 `.vbs`:
|
|
130
|
+
|
|
131
|
+
```vbscript
|
|
132
|
+
'" %APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\pi-plus.vbs
|
|
133
|
+
Set s = CreateObject("WScript.Shell")
|
|
134
|
+
s.Run "wsl.exe -d Ubuntu-24.04 -u youruser -e /bin/true", 0, False
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
或用任务计划程序:触发器「登录时」,操作 `wsl.exe`,参数 `-d <发行版> -u <用户> -e /bin/true`,勾「不管用户是否登录都运行」(配合 linger)。
|
|
138
|
+
|
|
139
|
+
`pp install` 在检测到 WSL(`WSL_DISTRO_NAME` / `WSL_INTEROP` 或内核名含 `microsoft`)时会直接打印这段提示,`pp doctor` 也会给出 `wsl` 一行提醒。
|
|
140
|
+
|
|
141
|
+
验证顺序:`wsl --shutdown`(Windows 侧)→ 重新打开 WSL → `pp ls` 应该 7/7 在跑;若没有,先看 `systemctl --user status pi-plus` 与 `journalctl --user -u pi-plus`。
|
|
142
|
+
|
|
143
|
+
## 验证自己的自启是否真的有效
|
|
144
|
+
|
|
145
|
+
不要只看 `systemctl is-enabled`,它只说明「会被执行」。真正的检验是**冷启动**:
|
|
146
|
+
|
|
147
|
+
```bash
|
|
148
|
+
# 把真实单元复制一份、换成临时配置和临时 socket,模拟"没有会话"的开机状态
|
|
149
|
+
sed 's#/home/you/.pi/plus.yml#/tmp/boot/plus.yml#' \
|
|
150
|
+
~/.config/systemd/user/pi-plus.service > ~/.config/systemd/user/pp-boottest.service
|
|
151
|
+
tmux -L boottest kill-server 2>/dev/null
|
|
152
|
+
systemctl --user daemon-reload && systemctl --user start pp-boottest.service
|
|
153
|
+
sleep 3 && tmux -L boottest list-sessions # 会话应该在
|
|
154
|
+
systemctl --user stop pp-boottest.service
|
|
155
|
+
tmux -L boottest list-sessions # 停止单元后仍然在(KillMode=none 生效)
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
## 卸载
|
|
159
|
+
|
|
160
|
+
```bash
|
|
161
|
+
pp uninstall # 停用并删除单元/定时器(不杀正在跑的会话)
|
|
162
|
+
systemctl --user disable --now pi-plus.timer # 如果装过 --watch
|
|
163
|
+
rm -f ~/.config/systemd/user/pi-plus.* # 残留
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
WSL 里关掉 linger:`sudo loginctl disable-linger "$USER"`。
|