pi-farm 0.2.2 → 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 +24 -0
- 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
|
|
|
@@ -97,6 +98,28 @@ pp n api --save # 同时写进配置文件,重启后自动拉起
|
|
|
97
98
|
- 常用选项:`-C/--dir`、`--agent`、`--log`、`--save`、`-a/--attach`、`--no-remote-pi`、`--force`、`--dry-run`
|
|
98
99
|
- `pp new` 不依赖任何配置文件;`--save` 会在**没有配置时新建** `~/.pi/plus.yml`(或 `-c` / `$PI_PLUS_CONFIG` 指向的路径)并追加这一条
|
|
99
100
|
|
|
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` 可离线用来看地址
|
|
122
|
+
|
|
100
123
|
## 文档
|
|
101
124
|
|
|
102
125
|
| 文档 | 内容 |
|
|
@@ -255,6 +278,7 @@ pp status [name|#...] 状态表,第一列是 # 序号(--json 机器可
|
|
|
255
278
|
pp attach <name|#> 进入;不存在则先启动
|
|
256
279
|
pp logs <name|#> [-n 200] 打印滚动输出
|
|
257
280
|
pp send <name|#> "文本" 往 pane 里打字并回车(--no-enter 不回车)
|
|
281
|
+
pp mesh ls|resolve|send 直连 remote-pi broker:看谁在线 / 查地址 / 发消息(--reply 等回复)
|
|
258
282
|
pp check 校验配置
|
|
259
283
|
pp doctor 环境诊断(含自启状态、WSL 提示)
|
|
260
284
|
pp init 写示例配置
|
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"`。
|
package/docs/cli.md
ADDED
|
@@ -0,0 +1,207 @@
|
|
|
1
|
+
# 命令行参考
|
|
2
|
+
|
|
3
|
+
`pp` 是唯一入口(包名 `pi-farm`,可执行文件只有 `pp`)。不带参数打印总览与命令列表,想直接看状态用 `pp ls`。
|
|
4
|
+
|
|
5
|
+
```
|
|
6
|
+
pp <command> [names...] [options]
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
## 全局选项
|
|
10
|
+
|
|
11
|
+
| 选项 | 说明 |
|
|
12
|
+
|---|---|
|
|
13
|
+
| `-c, --config <path>` | 指定配置文件(覆盖自动发现) |
|
|
14
|
+
| `--socket <name>` | 用 `tmux -L <name>` 的独立 socket,等价于配置里的 `tmux.socket` |
|
|
15
|
+
| `--json` | 机器可读输出(同时抑制人读文本) |
|
|
16
|
+
| `--dry-run` | 只打印会执行的 tmux 命令,不动真实状态 |
|
|
17
|
+
| `--force` | 已在运行时也强制重建(`up`)/强制覆盖(`init`) |
|
|
18
|
+
| `--reconcile` | 自启/巡检模式:跳过被手动 `down` 过的 `unless-stopped`/`on-failure` |
|
|
19
|
+
| `-q, --quiet` | 静默(只输出错误) |
|
|
20
|
+
| `-v, --verbose` | 打印每条 tmux 命令 |
|
|
21
|
+
| `-n, --lines <N>` | `logs` 显示行数,默认 200 |
|
|
22
|
+
| `--no-enter` | `send` 只打字不回车 |
|
|
23
|
+
| `-C, --dir <path>` | `new` 的目标目录(默认当前目录) |
|
|
24
|
+
| `--agent <cmd>` | `new` 的启动命令(默认 `pi`) |
|
|
25
|
+
| `--log` | `new` 时把输出写到 `~/.pi/plus/logs/<name>.log` |
|
|
26
|
+
| `--save` | `new` 时把会话追加进配置文件 |
|
|
27
|
+
| `-a, --attach` | `new` 建完直接进入 |
|
|
28
|
+
| `--no-remote-pi` | `new` 时不给 remote-pi 名字 |
|
|
29
|
+
| `--as <name>` | `mesh send` 注册用的名字,默认 `pp-mesh` |
|
|
30
|
+
| `--wait <ms>` | `mesh send` 等 ACK 的超时,默认 5000 |
|
|
31
|
+
| `--reply <ms>` | `mesh send` 收到 ACK 后继续监听回复的时长(单播收到第一条即返回) |
|
|
32
|
+
| `--no-wait` | `mesh send` 只发不等 ACK |
|
|
33
|
+
| `--body-json <json>` | `mesh send` 发结构化 JSON(默认发纯文本) |
|
|
34
|
+
| `--print` | `install` 只打印单元文件 |
|
|
35
|
+
| `--watch [secs]` | `install` 额外装一个定时器,每 N 秒(默认 300)巡检一次 |
|
|
36
|
+
| `-h, --help` | 帮助(`pp help`、`pp <cmd> --help` 等价) |
|
|
37
|
+
| `-V, --version` | 打印版本 |
|
|
38
|
+
|
|
39
|
+
## 退出码
|
|
40
|
+
|
|
41
|
+
| 码 | 含义 |
|
|
42
|
+
|---|---|
|
|
43
|
+
| `0` | 成功 |
|
|
44
|
+
| `1` | 运行时失败:某个会话起不来、`check` 发现问题、`doctor` 有失败项 |
|
|
45
|
+
| `2` | 用法/配置错误:未知命令、未知选项、找不到配置文件、名字不存在、参数非法 |
|
|
46
|
+
|
|
47
|
+
`--json` 模式下错误仍然是 stderr 纯文本,JSON 只出现在 stdout。
|
|
48
|
+
|
|
49
|
+
## 命令
|
|
50
|
+
|
|
51
|
+
### `pp up [name|#...]`
|
|
52
|
+
|
|
53
|
+
后台创建/启动(别名 `start`)。不带名字 = 所有 `restart != no` 的会话。
|
|
54
|
+
|
|
55
|
+
- 已在运行 → 跳过(`--force` 则重建)
|
|
56
|
+
- pane 已 dead → 按策略重建(`restart: no` 且没点名 → 跳过并提示)
|
|
57
|
+
- 统计:`N started, M already running[, K failed]`
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
pp up
|
|
61
|
+
pp up backend
|
|
62
|
+
pp up 2 5 --force
|
|
63
|
+
pp up --reconcile # 自启/巡检用
|
|
64
|
+
pp up --dry-run -v
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
JSON:`{ "started": 2, "skipped": 1, "failures": [] }`
|
|
68
|
+
|
|
69
|
+
### `pp down [name|#...]`
|
|
70
|
+
|
|
71
|
+
停止(别名 `stop`)。不带名字 = 全部停掉(包括 `restart: no` 的)。
|
|
72
|
+
|
|
73
|
+
会为 `unless-stopped` / `on-failure` 记录「手动停止」,以免下次巡检把它拉回来。
|
|
74
|
+
|
|
75
|
+
JSON:`{ "killed": [...], "missing": [...] }`
|
|
76
|
+
|
|
77
|
+
### `pp restart [name|#...]`
|
|
78
|
+
|
|
79
|
+
先 `down` 再 `up`,遵守 `restart` 策略:`restart: no` 的会话不参与裸 `restart`。
|
|
80
|
+
|
|
81
|
+
### `pp status [name|#...]`
|
|
82
|
+
|
|
83
|
+
状态表(别名 `ls`、`list`)。列:`#`、`NAME`、`STATE`、`RESTART`、`PID`、`AGENT`、`CWD`、`PI SESSION`、`REMOTE-PI`。
|
|
84
|
+
|
|
85
|
+
`STATE` 取值:`running`、`attached`(有人正在看)、`dead`(pane 退出但被 `remain-on-exit` 保留)、`off`(配置了但没跑 / `restart: no` / 手动停过)。
|
|
86
|
+
|
|
87
|
+
JSON:行对象数组。
|
|
88
|
+
|
|
89
|
+
### `pp attach <name|#>`
|
|
90
|
+
|
|
91
|
+
进入会话(别名 `a`)。会话没跑会先启动。需要真终端(非 TTY 时 tmux 会报错)。`--dry-run` 打印 `tmux attach-session -t =<name>`。
|
|
92
|
+
|
|
93
|
+
### `pp logs <name|#> [-n N]`
|
|
94
|
+
|
|
95
|
+
打印 pane 最近 N 行(别名 `log`)。配了 `log:` 的会话也可以用 `tail -f` 看文件。
|
|
96
|
+
|
|
97
|
+
### `pp send <name|#> "文本"`
|
|
98
|
+
|
|
99
|
+
往 pane 里打字并回车(`--no-enter` 只打字)。本质是 `tmux send-keys`,适合给跑着的 agent 推提示词、回 `y/n`。**不返回 agent 的输出**,要看结果用 `pp logs`。
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
pp send backend "跑一下 npm test,失败就把报错贴出来"
|
|
103
|
+
pp send 3 --no-enter "git status" # 先不执行
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
### `pp mesh <ls|resolve|send>`
|
|
107
|
+
|
|
108
|
+
直连 remote-pi 的本地 broker(`~/.pi/remote/sessions/local/broker.sock`,可用 `$REMOTE_PI_HOME` 改根目录):
|
|
109
|
+
不启动 pi、不注册常驻 peer,一条命令说完就走。
|
|
110
|
+
|
|
111
|
+
| 子命令 | 作用 |
|
|
112
|
+
|---|---|
|
|
113
|
+
| `ls` | 列出在线 peer。**只读探测**(`{"type":"list_peers"}`),不会让别人的 peer 列表出现上下线抖动 |
|
|
114
|
+
| `resolve [name\|#...]` | 配置里的会话 → mesh 地址(`<cwd>@<remote_pi_name>`)+ 在线状态;broker 不在也能用 |
|
|
115
|
+
| `send <target...> "文本"` | 以临时身份(默认 `pp-mesh`)注册、投递、等 ACK |
|
|
116
|
+
|
|
117
|
+
```bash
|
|
118
|
+
pp mesh ls # # ADDRESS PC SESSION
|
|
119
|
+
pp mesh resolve backend risk-01 # backend → /srv/api@backend online x1
|
|
120
|
+
pp mesh send backend "跑一下 npm test" # delivered / busy / denied / timeout
|
|
121
|
+
pp mesh send 1 3 "10 分钟后重启" # 多个目标 = 组播,不等 ACK
|
|
122
|
+
pp mesh send all "standup in 5" # 广播
|
|
123
|
+
pp mesh send macbook:/Users/me/code/api@api "ping" --wait 2000
|
|
124
|
+
pp mesh send backend "报一下进度" --reply 60000 # 收到回复立刻打印并返回
|
|
125
|
+
pp mesh send api --body-json '{"task":"test","id":42}' # 结构化消息
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
- 目标可以是会话名、`#` 序号、完整 mesh 地址(`<cwd>@<name>` 或 `macbook:/path@name`)、`all`/`broadcast`
|
|
129
|
+
- 单播会等 broker 的 ACK:`received` 成功;`busy` 表示对方正在跑一轮,**消息被丢弃**(用 `--no-wait` 或稍后重试);`denied`;超时(消息可能仍会送达)
|
|
130
|
+
- `--reply <ms>`:ACK 之后继续监听 `re=<本次 id>` 的回信;单播拿到第一条就提前返回,组播/广播会一直收到窗口结束
|
|
131
|
+
- 发送内容默认是字符串(对方看到的就是这句话);`--body-json` 发送任意 JSON,对方收到的是序列化后的 JSON 文本
|
|
132
|
+
- 地址后缀 `#N` 是 broker 对同 `(cwd, name)` 重复身份的自动去重,`livePeersFor` 会把它一并算作同一个会话
|
|
133
|
+
- 跨机投递走 broker leader 的 relay 桥,发送端不需要做任何配对
|
|
134
|
+
|
|
135
|
+
### `pp check [name|#...]`
|
|
136
|
+
|
|
137
|
+
只校验配置,不碰 tmux。失败项进 stderr 并退出 1;`notes` 是提示(`restart: no`、手动停过、共享目录写同名等)。JSON:`{ "ok": true, "problems": [], "notes": [], "config": "..." }`。
|
|
138
|
+
|
|
139
|
+
### `pp doctor`
|
|
140
|
+
|
|
141
|
+
环境体检:node / tmux / tmux server / pi / 配置文件 / 自启状态 / WSL 提示。任何一项失败 → 退出 1。JSON:`{ "checks": [{name, ok, detail}], "warnings": [] }`。
|
|
142
|
+
|
|
143
|
+
### `pp init`
|
|
144
|
+
|
|
145
|
+
写示例配置到 `~/.pi/plus.yml`;`--local` 写 `./pi-plus.yml`;`--path <p>` 指定路径;已存在时报错(`--force` 覆盖)。
|
|
146
|
+
|
|
147
|
+
### `pp install [--watch N] [--print]`
|
|
148
|
+
|
|
149
|
+
装开机自启(别名 `autostart`):Linux 用 systemd user unit,macOS 用 LaunchAgent。细节见 [autostart.md](autostart.md)。
|
|
150
|
+
|
|
151
|
+
- `--print` / `--dry-run`:只打印单元文件,不落盘
|
|
152
|
+
- `--watch [N]`:额外装一个 systemd timer(macOS 上是 `StartInterval`),每 N 秒跑一次 `up --reconcile`
|
|
153
|
+
|
|
154
|
+
### `pp uninstall`
|
|
155
|
+
|
|
156
|
+
停用并删除自启单元(不杀正在跑的会话)。
|
|
157
|
+
|
|
158
|
+
### `pp new [name]`
|
|
159
|
+
|
|
160
|
+
在当前目录(或 `-C <path>`)临时开一个会话,**不需要配置文件**。名字默认取目录名并规整成 tmux 安全字符,重名自动 `-2`、`-3`;显式给的名字重名则报错(`--force` 重建)。默认 `agent: pi`、`remote_pi_mode: env`。
|
|
161
|
+
|
|
162
|
+
```bash
|
|
163
|
+
pp new # 名字 = 目录名
|
|
164
|
+
pp n api -C ~/code/api --attach # 别名 n / create
|
|
165
|
+
pp new scratch --agent bash --log --save # 顺便写进配置
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
### `pp help [command]`
|
|
169
|
+
|
|
170
|
+
不带参数是总览;`pp help up` 与 `pp up --help` 等价;拼错会给出建议(`did you mean 'pp up'?`)。
|
|
171
|
+
|
|
172
|
+
### `pp version`
|
|
173
|
+
|
|
174
|
+
打印版本(等价 `-V`)。
|
|
175
|
+
|
|
176
|
+
## 环境变量
|
|
177
|
+
|
|
178
|
+
| 变量 | 作用 |
|
|
179
|
+
|---|---|
|
|
180
|
+
| `PI_PLUS_CONFIG` | 配置文件路径,优先级仅次于 `-c` |
|
|
181
|
+
| `TMUX_TMPDIR` | tmux socket 所在目录(`tmux -L` 时用) |
|
|
182
|
+
| `XDG_STATE_HOME` | 手动停止记录的位置(默认 `~/.local/state`) |
|
|
183
|
+
| `XDG_CONFIG_HOME` | 配置搜索路径之一(默认 `~/.config`) |
|
|
184
|
+
| `REMOTE_PI_DIRECT_CONFIG` | 由 `pp` 在 `remote_pi_mode: env` 时注入,不用手动设 |
|
|
185
|
+
| `REMOTE_PI_HOME` | remote-pi 的状态根目录(默认 `~/.pi`),`pp mesh` 用它定位 broker socket |
|
|
186
|
+
|
|
187
|
+
## 常见组合
|
|
188
|
+
|
|
189
|
+
```bash
|
|
190
|
+
# 每天看一眼
|
|
191
|
+
pp doctor && pp check && pp ls
|
|
192
|
+
|
|
193
|
+
# 只重启崩溃的那几个
|
|
194
|
+
pp ls --json | jq -r '.[] | select(.state=="dead") | .name' | xargs -r pp up
|
|
195
|
+
|
|
196
|
+
# 给某个 agent 推任务
|
|
197
|
+
pp send risk "把这周的日志异常整理成表格"
|
|
198
|
+
|
|
199
|
+
# 临时开一个实验目录,跑完删
|
|
200
|
+
d=$(mktemp -d) && pp new trial -C "$d" -a && pp down trial
|
|
201
|
+
|
|
202
|
+
# 让 risk-01 汇报,并把回复收进文件(最多等 2 分钟)
|
|
203
|
+
pp mesh send risk-01 "把今天的异常日志总结成 5 条" --reply 120000 > risk-report.txt
|
|
204
|
+
|
|
205
|
+
# 全体通知
|
|
206
|
+
pp mesh send all "我要重启这台机器,5 分钟后回来"
|
|
207
|
+
```
|