pi-farm 0.2.2 → 0.3.0
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 +42 -0
- package/bin/pp.js +6 -0
- package/completions/_pp +9 -0
- package/completions/pp.bash +17 -4
- package/docs/architecture.md +152 -0
- package/docs/autostart.md +166 -0
- package/docs/cli.md +225 -0
- package/docs/configuration.md +160 -0
- package/docs/development.md +129 -0
- package/docs/troubleshooting.md +226 -0
- package/package.json +5 -2
- package/src/aliases.js +204 -0
- package/src/autostart.js +7 -1
- package/src/commands.js +489 -2
- package/src/help.js +71 -0
- package/src/mesh.js +239 -0
package/docs/cli.md
ADDED
|
@@ -0,0 +1,225 @@
|
|
|
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
|
+
| `--bin-dir <dir>` | `alias` 的软链目录,默认 `~/.local/bin` 或 `$PP_BIN_DIR` |
|
|
35
|
+
| `--print` | `install` 只打印单元文件 |
|
|
36
|
+
| `--watch [secs]` | `install` 额外装一个定时器,每 N 秒(默认 300)巡检一次 |
|
|
37
|
+
| `-h, --help` | 帮助(`pp help`、`pp <cmd> --help` 等价) |
|
|
38
|
+
| `-V, --version` | 打印版本 |
|
|
39
|
+
|
|
40
|
+
## 退出码
|
|
41
|
+
|
|
42
|
+
| 码 | 含义 |
|
|
43
|
+
|---|---|
|
|
44
|
+
| `0` | 成功 |
|
|
45
|
+
| `1` | 运行时失败:某个会话起不来、`check` 发现问题、`doctor` 有失败项 |
|
|
46
|
+
| `2` | 用法/配置错误:未知命令、未知选项、找不到配置文件、名字不存在、参数非法 |
|
|
47
|
+
|
|
48
|
+
`--json` 模式下错误仍然是 stderr 纯文本,JSON 只出现在 stdout。
|
|
49
|
+
|
|
50
|
+
## 命令
|
|
51
|
+
|
|
52
|
+
### `pp up [name|#...]`
|
|
53
|
+
|
|
54
|
+
后台创建/启动(别名 `start`)。不带名字 = 所有 `restart != no` 的会话。
|
|
55
|
+
|
|
56
|
+
- 已在运行 → 跳过(`--force` 则重建)
|
|
57
|
+
- pane 已 dead → 按策略重建(`restart: no` 且没点名 → 跳过并提示)
|
|
58
|
+
- 统计:`N started, M already running[, K failed]`
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
pp up
|
|
62
|
+
pp up backend
|
|
63
|
+
pp up 2 5 --force
|
|
64
|
+
pp up --reconcile # 自启/巡检用
|
|
65
|
+
pp up --dry-run -v
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
JSON:`{ "started": 2, "skipped": 1, "failures": [] }`
|
|
69
|
+
|
|
70
|
+
### `pp down [name|#...]`
|
|
71
|
+
|
|
72
|
+
停止(别名 `stop`)。不带名字 = 全部停掉(包括 `restart: no` 的)。
|
|
73
|
+
|
|
74
|
+
会为 `unless-stopped` / `on-failure` 记录「手动停止」,以免下次巡检把它拉回来。
|
|
75
|
+
|
|
76
|
+
JSON:`{ "killed": [...], "missing": [...] }`
|
|
77
|
+
|
|
78
|
+
### `pp restart [name|#...]`
|
|
79
|
+
|
|
80
|
+
先 `down` 再 `up`,遵守 `restart` 策略:`restart: no` 的会话不参与裸 `restart`。
|
|
81
|
+
|
|
82
|
+
### `pp status [name|#...]`
|
|
83
|
+
|
|
84
|
+
状态表(别名 `ls`、`list`)。列:`#`、`NAME`、`STATE`、`RESTART`、`PID`、`AGENT`、`CWD`、`PI SESSION`、`REMOTE-PI`。
|
|
85
|
+
|
|
86
|
+
`STATE` 取值:`running`、`attached`(有人正在看)、`dead`(pane 退出但被 `remain-on-exit` 保留)、`off`(配置了但没跑 / `restart: no` / 手动停过)。
|
|
87
|
+
|
|
88
|
+
JSON:行对象数组。
|
|
89
|
+
|
|
90
|
+
### `pp attach <name|#>`
|
|
91
|
+
|
|
92
|
+
进入会话(别名 `a`)。会话没跑会先启动。需要真终端(非 TTY 时 tmux 会报错)。`--dry-run` 打印 `tmux attach-session -t =<name>`。
|
|
93
|
+
|
|
94
|
+
### `pp logs <name|#> [-n N]`
|
|
95
|
+
|
|
96
|
+
打印 pane 最近 N 行(别名 `log`)。配了 `log:` 的会话也可以用 `tail -f` 看文件。
|
|
97
|
+
|
|
98
|
+
### `pp send <name|#> "文本"`
|
|
99
|
+
|
|
100
|
+
往 pane 里打字并回车(`--no-enter` 只打字)。本质是 `tmux send-keys`,适合给跑着的 agent 推提示词、回 `y/n`。**不返回 agent 的输出**,要看结果用 `pp logs`。
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
pp send backend "跑一下 npm test,失败就把报错贴出来"
|
|
104
|
+
pp send 3 --no-enter "git status" # 先不执行
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
### `pp mesh <ls|resolve|send>`
|
|
108
|
+
|
|
109
|
+
直连 remote-pi 的本地 broker(`~/.pi/remote/sessions/local/broker.sock`,可用 `$REMOTE_PI_HOME` 改根目录):
|
|
110
|
+
不启动 pi、不注册常驻 peer,一条命令说完就走。
|
|
111
|
+
|
|
112
|
+
| 子命令 | 作用 |
|
|
113
|
+
|---|---|
|
|
114
|
+
| `ls` | 列出在线 peer。**只读探测**(`{"type":"list_peers"}`),不会让别人的 peer 列表出现上下线抖动 |
|
|
115
|
+
| `resolve [name\|#...]` | 配置里的会话 → mesh 地址(`<cwd>@<remote_pi_name>`)+ 在线状态;broker 不在也能用 |
|
|
116
|
+
| `send <target...> "文本"` | 以临时身份(默认 `pp-mesh`)注册、投递、等 ACK |
|
|
117
|
+
|
|
118
|
+
```bash
|
|
119
|
+
pp mesh ls # # ADDRESS PC SESSION
|
|
120
|
+
pp mesh resolve backend risk-01 # backend → /srv/api@backend online x1
|
|
121
|
+
pp mesh send backend "跑一下 npm test" # delivered / busy / denied / timeout
|
|
122
|
+
pp mesh send 1 3 "10 分钟后重启" # 多个目标 = 组播,不等 ACK
|
|
123
|
+
pp mesh send all "standup in 5" # 广播
|
|
124
|
+
pp mesh send macbook:/Users/me/code/api@api "ping" --wait 2000
|
|
125
|
+
pp mesh send backend "报一下进度" --reply 60000 # 收到回复立刻打印并返回
|
|
126
|
+
pp mesh send api --body-json '{"task":"test","id":42}' # 结构化消息
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
- 目标可以是会话名、`#` 序号、完整 mesh 地址(`<cwd>@<name>` 或 `macbook:/path@name`)、`all`/`broadcast`
|
|
130
|
+
- 单播会等 broker 的 ACK:`received` 成功;`busy` 表示对方正在跑一轮,**消息被丢弃**(用 `--no-wait` 或稍后重试);`denied`;超时(消息可能仍会送达)
|
|
131
|
+
- `--reply <ms>`:ACK 之后继续监听 `re=<本次 id>` 的回信;单播拿到第一条就提前返回,组播/广播会一直收到窗口结束
|
|
132
|
+
- 发送内容默认是字符串(对方看到的就是这句话);`--body-json` 发送任意 JSON,对方收到的是序列化后的 JSON 文本
|
|
133
|
+
- 地址后缀 `#N` 是 broker 对同 `(cwd, name)` 重复身份的自动去重,`livePeersFor` 会把它一并算作同一个会话
|
|
134
|
+
- 跨机投递走 broker leader 的 relay 桥,发送端不需要做任何配对
|
|
135
|
+
|
|
136
|
+
### `pp alias [ls|add|rm]`
|
|
137
|
+
|
|
138
|
+
管理备用命令名。macOS 自带 `/usr/bin/pp`(ASN.1 工具),所以包内自带 `pifarm`、`pi-plus` 两个名字;`alias` 再加任意短名。
|
|
139
|
+
|
|
140
|
+
```bash
|
|
141
|
+
pp alias ls # 列出指向本 CLI 的软链 + 目录是否在 PATH
|
|
142
|
+
pp alias add pif # ~/.local/bin/pif → 本 CLI
|
|
143
|
+
pp alias add p --bin-dir /usr/local/bin
|
|
144
|
+
pp alias rm pif
|
|
145
|
+
pp alias ls --json
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
- 默认目录 `~/.local/bin`,可用 `$PP_BIN_DIR` 或 `--bin-dir` 覆盖;不在 PATH 时会提示怎么加
|
|
149
|
+
- 软链指向脚本本身,`npm i -g` 升级后别名自动跟随
|
|
150
|
+
- `add` 遇到同名**非软链**文件会拒绝(`--force` 才替换);`rm` 遇到指向别的程序的软链也会拒绝
|
|
151
|
+
- `pp doctor` 的 `command name` 行会写明哪个名字是我们的、哪个是别人的,以及装在 PATH 上那份的版本
|
|
152
|
+
|
|
153
|
+
### `pp check [name|#...]`
|
|
154
|
+
|
|
155
|
+
只校验配置,不碰 tmux。失败项进 stderr 并退出 1;`notes` 是提示(`restart: no`、手动停过、共享目录写同名等)。JSON:`{ "ok": true, "problems": [], "notes": [], "config": "..." }`。
|
|
156
|
+
|
|
157
|
+
### `pp doctor`
|
|
158
|
+
|
|
159
|
+
环境体检:node / tmux / tmux server / pi / 配置文件 / 自启状态 / WSL 提示。任何一项失败 → 退出 1。JSON:`{ "checks": [{name, ok, detail}], "warnings": [] }`。
|
|
160
|
+
|
|
161
|
+
### `pp init`
|
|
162
|
+
|
|
163
|
+
写示例配置到 `~/.pi/plus.yml`;`--local` 写 `./pi-plus.yml`;`--path <p>` 指定路径;已存在时报错(`--force` 覆盖)。
|
|
164
|
+
|
|
165
|
+
### `pp install [--watch N] [--print]`
|
|
166
|
+
|
|
167
|
+
装开机自启(别名 `autostart`):Linux 用 systemd user unit,macOS 用 LaunchAgent。细节见 [autostart.md](autostart.md)。
|
|
168
|
+
|
|
169
|
+
- `--print` / `--dry-run`:只打印单元文件,不落盘
|
|
170
|
+
- `--watch [N]`:额外装一个 systemd timer(macOS 上是 `StartInterval`),每 N 秒跑一次 `up --reconcile`
|
|
171
|
+
|
|
172
|
+
### `pp uninstall`
|
|
173
|
+
|
|
174
|
+
停用并删除自启单元(不杀正在跑的会话)。
|
|
175
|
+
|
|
176
|
+
### `pp new [name]`
|
|
177
|
+
|
|
178
|
+
在当前目录(或 `-C <path>`)临时开一个会话,**不需要配置文件**。名字默认取目录名并规整成 tmux 安全字符,重名自动 `-2`、`-3`;显式给的名字重名则报错(`--force` 重建)。默认 `agent: pi`、`remote_pi_mode: env`。
|
|
179
|
+
|
|
180
|
+
```bash
|
|
181
|
+
pp new # 名字 = 目录名
|
|
182
|
+
pp n api -C ~/code/api --attach # 别名 n / create
|
|
183
|
+
pp new scratch --agent bash --log --save # 顺便写进配置
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
### `pp help [command]`
|
|
187
|
+
|
|
188
|
+
不带参数是总览;`pp help up` 与 `pp up --help` 等价;拼错会给出建议(`did you mean 'pp up'?`)。
|
|
189
|
+
|
|
190
|
+
### `pp version`
|
|
191
|
+
|
|
192
|
+
打印版本(等价 `-V`)。
|
|
193
|
+
|
|
194
|
+
## 环境变量
|
|
195
|
+
|
|
196
|
+
| 变量 | 作用 |
|
|
197
|
+
|---|---|
|
|
198
|
+
| `PI_PLUS_CONFIG` | 配置文件路径,优先级仅次于 `-c` |
|
|
199
|
+
| `TMUX_TMPDIR` | tmux socket 所在目录(`tmux -L` 时用) |
|
|
200
|
+
| `XDG_STATE_HOME` | 手动停止记录的位置(默认 `~/.local/state`) |
|
|
201
|
+
| `XDG_CONFIG_HOME` | 配置搜索路径之一(默认 `~/.config`) |
|
|
202
|
+
| `REMOTE_PI_DIRECT_CONFIG` | 由 `pp` 在 `remote_pi_mode: env` 时注入,不用手动设 |
|
|
203
|
+
| `REMOTE_PI_HOME` | remote-pi 的状态根目录(默认 `~/.pi`),`pp mesh` 用它定位 broker socket |
|
|
204
|
+
|
|
205
|
+
## 常见组合
|
|
206
|
+
|
|
207
|
+
```bash
|
|
208
|
+
# 每天看一眼
|
|
209
|
+
pp doctor && pp check && pp ls
|
|
210
|
+
|
|
211
|
+
# 只重启崩溃的那几个
|
|
212
|
+
pp ls --json | jq -r '.[] | select(.state=="dead") | .name' | xargs -r pp up
|
|
213
|
+
|
|
214
|
+
# 给某个 agent 推任务
|
|
215
|
+
pp send risk "把这周的日志异常整理成表格"
|
|
216
|
+
|
|
217
|
+
# 临时开一个实验目录,跑完删
|
|
218
|
+
d=$(mktemp -d) && pp new trial -C "$d" -a && pp down trial
|
|
219
|
+
|
|
220
|
+
# 让 risk-01 汇报,并把回复收进文件(最多等 2 分钟)
|
|
221
|
+
pp mesh send risk-01 "把今天的异常日志总结成 5 条" --reply 120000 > risk-report.txt
|
|
222
|
+
|
|
223
|
+
# 全体通知
|
|
224
|
+
pp mesh send all "我要重启这台机器,5 分钟后回来"
|
|
225
|
+
```
|
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
# 配置参考
|
|
2
|
+
|
|
3
|
+
一份 YAML 描述「要跑哪些 agent、在哪里跑、叫什么名字、崩了怎么办」。默认位置 `~/.pi/plus.yml`,`pp check` 会把解析结果和警告全打出来。
|
|
4
|
+
|
|
5
|
+
## 配置文件在哪
|
|
6
|
+
|
|
7
|
+
按优先级找:
|
|
8
|
+
|
|
9
|
+
| 顺序 | 位置 |
|
|
10
|
+
|---|---|
|
|
11
|
+
| 1 | `-c` / `--config <path>` |
|
|
12
|
+
| 2 | 环境变量 `$PI_PLUS_CONFIG`(支持 `~` 和 `$VAR`) |
|
|
13
|
+
| 3 | 当前目录 `pi-plus.yml` / `pi-plus.yaml` / `plus.yml` / `plus.yaml` |
|
|
14
|
+
| 4 | `~/.pi/plus.yml` / `~/.pi/plus.yaml` |
|
|
15
|
+
| 5 | `$XDG_CONFIG_HOME/pi-plus/config.yml`(默认 `~/.config/pi-plus/config.yml`) |
|
|
16
|
+
|
|
17
|
+
`pp init` 写 `~/.pi/plus.yml`(`--local` 写 `./pi-plus.yml`,`--path <p>` 指定路径)。配置文件不存在时,除了 `init` / `new` 之外的命令都会以退出码 2 报 `config file not found`。
|
|
18
|
+
|
|
19
|
+
## 结构
|
|
20
|
+
|
|
21
|
+
```yaml
|
|
22
|
+
version: 1 # 可选,目前不参与逻辑
|
|
23
|
+
|
|
24
|
+
tmux: # 可选
|
|
25
|
+
socket: pi-plus # 等价于每条命令都加 --socket pi-plus
|
|
26
|
+
|
|
27
|
+
defaults: # 可选:所有 session 的默认值(键同 session,name/cwd 除外)
|
|
28
|
+
agent: pi
|
|
29
|
+
restart: always
|
|
30
|
+
env:
|
|
31
|
+
TZ: Asia/Shanghai
|
|
32
|
+
|
|
33
|
+
sessions: # 必填,非空列表
|
|
34
|
+
- name: backend
|
|
35
|
+
cwd: ~/code/backend
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
## session 字段
|
|
39
|
+
|
|
40
|
+
| 字段 | 类型 | 默认 | 说明 |
|
|
41
|
+
|---|---|---|---|
|
|
42
|
+
| `name` | string | **必填** | 会话名,也是另外两个名字的默认值。只能用字母、数字、`-`、`_`;`tmux_name` 全局唯一 |
|
|
43
|
+
| `cwd` | string | 当前目录 | 工作目录。支持 `~` 和 `$VAR`,必须是存在的目录(`pp check` 会验证) |
|
|
44
|
+
| `agent` | string 或列表 | `pi` | 启动命令。字符串按 shell 规则切分(支持引号),列表原样使用。`basename` 是 `pi` 时会自动加 pi 的参数 |
|
|
45
|
+
| `pi` | bool | 按 `agent` 推断 | 强制/禁止加 pi 参数(`--name` / `--session-id` 等) |
|
|
46
|
+
| `pi_session` | string | 无 | 续接哪段对话:`.jsonl` 路径(`/`、`~/`、`./`、`../`、`*.jsonl`)走 `--session`,否则当 session id 走 `--session-id`。id 规则:首字符是字母或数字,末字符也是字母或数字,中间允许字母、数字、`.`、`_`、`-` |
|
|
47
|
+
| `pi_session_name` | string / null | `name` | pi 的显示名(`--name`)。`null` 表示不加 |
|
|
48
|
+
| `pi_session_dir` | string | 无 | `--session-dir`,pi 存会话文件的目录 |
|
|
49
|
+
| `remote_pi_name` | string / false | `name` | remote-pi mesh 里的 agent 名。`false` 表示不设置。会被规整:`/ : @ # 空白` → `-`,禁止 `broadcast` / `broker` |
|
|
50
|
+
| `remote_pi_mode` | `config` / `env` / `off` | `config` | 见下文「remote-pi 名称的三种模式」 |
|
|
51
|
+
| `remote_pi` | map | 无 | 上面两个字段的嵌套写法:`remote_pi: {name: x, mode: env}` |
|
|
52
|
+
| `env` | map | `{}` | 追加的环境变量(值为 null 的键忽略)。与 `defaults.env` **合并**,同名覆盖 |
|
|
53
|
+
| `args` | string 或列表 | `[]` | 追加到 agent 命令末尾的参数(整体替换 `defaults.args`,不合并) |
|
|
54
|
+
| `log` | string / true | 无 | 用 `pipe-pane` 把输出落到文件;`true` 表示 `<cwd>/.pi-plus.log`。目录会自动创建 |
|
|
55
|
+
| `remain_on_exit` | bool | `false` | tmux 的 `remain-on-exit`(退出后保留 pane 以便看日志)。`restart: no` 自动开启 |
|
|
56
|
+
| `restart` | `no`/`always`/`on-failure`/`unless-stopped` | `always` | 拉起策略,见下节 |
|
|
57
|
+
|
|
58
|
+
未知键不会让命令失败,但会作为警告出现(`unknown key "xxx" (ignored)`),方便发现拼写错误。
|
|
59
|
+
|
|
60
|
+
## `restart` 策略
|
|
61
|
+
|
|
62
|
+
语义对齐 docker compose:
|
|
63
|
+
|
|
64
|
+
| 策略 | 裸 `pp up` | 自启 / `--watch`(`--reconcile`) | `pp up <name>` | 崩溃后 |
|
|
65
|
+
|---|---|---|---|---|
|
|
66
|
+
| `no` | 跳过 | 跳过 | 重建 | 保留 dead pane(可 `pp logs`),只有点名才重建 |
|
|
67
|
+
| `always` | 启动 | 启动 | 重建 | 下次 `up`/巡检复活 |
|
|
68
|
+
| `on-failure` | 启动 | 手动 `down` 过的跳过 | 重建 | 下次 `up`/巡检复活 |
|
|
69
|
+
| `unless-stopped` | 启动 | 手动 `down` 过的跳过 | 重建 | 下次 `up`/巡检复活 |
|
|
70
|
+
|
|
71
|
+
- 「手动 `down`」记录在 `$XDG_STATE_HOME/pi-plus/state.json`(默认 `~/.local/state/pi-plus/state.json`),以配置文件路径为 key
|
|
72
|
+
- `pp up <name>`(点名启动)会清掉这条记录,把这个会话重新纳入巡检
|
|
73
|
+
- `restart: true` / `false` 是 `always` / `no` 的别名
|
|
74
|
+
|
|
75
|
+
## remote-pi 名称的三种模式
|
|
76
|
+
|
|
77
|
+
remote-pi 的身份是 `<cwd>@<名字>`,名字存在**每个目录**的 `<cwd>/.pi/remote-pi/config.json`(`agent_name` 字段),`/remote-pi rename` 改的就是它。
|
|
78
|
+
|
|
79
|
+
| 模式 | 行为 | 适用 |
|
|
80
|
+
|---|---|---|
|
|
81
|
+
| `config`(默认) | `pp` 启动前把 `agent_name` 写进该文件,保留其它键 | 一个目录一个会话,希望名字持久 |
|
|
82
|
+
| `env` | 不写文件,注入 `REMOTE_PI_DIRECT_CONFIG=<JSON>`(remote-pi 优先级高于文件) | 同一目录多个会话、临时会话(`pp new` 默认) |
|
|
83
|
+
| `off` | 什么都不做 | 不想进 mesh |
|
|
84
|
+
|
|
85
|
+
`config` 模式下,同一 `cwd` 的两个会话如果要求不同名字,`pp check` 会警告「last write wins」并建议改 `env`——因为文件只有一个 `agent_name`。
|
|
86
|
+
|
|
87
|
+
## 完整示例
|
|
88
|
+
|
|
89
|
+
```yaml
|
|
90
|
+
version: 1
|
|
91
|
+
|
|
92
|
+
tmux:
|
|
93
|
+
socket: pi-plus
|
|
94
|
+
|
|
95
|
+
defaults:
|
|
96
|
+
agent: pi
|
|
97
|
+
restart: always
|
|
98
|
+
env:
|
|
99
|
+
TZ: Asia/Shanghai
|
|
100
|
+
|
|
101
|
+
sessions:
|
|
102
|
+
# ① 最简:只想后台跑一个 pi,名字/目录都用默认规则
|
|
103
|
+
- name: backend
|
|
104
|
+
cwd: ~/code/backend
|
|
105
|
+
|
|
106
|
+
# ② 续接一段已有的 pi 对话,并把显示名固定下来
|
|
107
|
+
- name: risk
|
|
108
|
+
cwd: ~/code/risk
|
|
109
|
+
pi_session: 3f9a1c2e # 走 --session-id
|
|
110
|
+
pi_session_name: risk-01
|
|
111
|
+
|
|
112
|
+
# ③ 同一目录两个 agent,各自独立的 mesh 名字
|
|
113
|
+
- name: bh-01
|
|
114
|
+
cwd: ~/code/baohan
|
|
115
|
+
remote_pi_name: bh-system-01
|
|
116
|
+
remote_pi_mode: env
|
|
117
|
+
- name: bh-02
|
|
118
|
+
cwd: ~/code/baohan
|
|
119
|
+
remote_pi_name: bh-system-02
|
|
120
|
+
remote_pi_mode: env
|
|
121
|
+
|
|
122
|
+
# ④ 不是 pi 的 agent,带一个常驻日志
|
|
123
|
+
- name: shell
|
|
124
|
+
cwd: /srv/tools
|
|
125
|
+
agent: bash
|
|
126
|
+
restart: no
|
|
127
|
+
log: ~/.pi/plus/logs/shell.log
|
|
128
|
+
|
|
129
|
+
# ⑤ 带参数的 pi,按需扩写
|
|
130
|
+
- name: reviewer
|
|
131
|
+
cwd: ~/code/review
|
|
132
|
+
agent: pi --model opencode-go/deepseek-v4.1-flash
|
|
133
|
+
args: [--approve]
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
## 名字映射速查
|
|
137
|
+
|
|
138
|
+
```
|
|
139
|
+
name: backend
|
|
140
|
+
├─ tmux session tmux_name = backend (pp attach backend / tmux attach -t backend)
|
|
141
|
+
├─ pi 显示名 pi_session_name = backend (pi 里 /session 看到的名字)
|
|
142
|
+
└─ remote-pi agent remote_pi_name = backend (<cwd>@backend)
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
三者都能单独覆盖;pi 的 **session id** 不是名字,是 `pi_session`。
|
|
146
|
+
|
|
147
|
+
## 校验规则汇总
|
|
148
|
+
|
|
149
|
+
`pp check` 会报出(并且 `pp up` 会拒绝启动)的情况:
|
|
150
|
+
|
|
151
|
+
- `name` 为空、含 `.`/`:`/空格等非 tmux 安全字符
|
|
152
|
+
- `tmux_name` 重复
|
|
153
|
+
- `cwd` 不存在或不是目录
|
|
154
|
+
- `pi_session` 不符合 session id 规则(且不是路径)
|
|
155
|
+
- `remote_pi_mode` 不是 `config`/`env`/`off`
|
|
156
|
+
- `restart` 不是四个策略之一
|
|
157
|
+
- `env` 不是映射、`args` 不是字符串/列表
|
|
158
|
+
- `sessions` 不是列表、根节点不是映射
|
|
159
|
+
|
|
160
|
+
仅作为「提示」(不影响退出码语义,但会打印):`restart: no` 不参与裸 `up`、被手动 `down` 过、`config` 模式下共享目录写同一个名字、agent 不在 PATH 上。
|
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
# 开发指南
|
|
2
|
+
|
|
3
|
+
零运行时依赖,纯 ESM,Node ≥ 18。改完跑 `npm test`,端到端再跑一次 `./test/e2e.sh`。
|
|
4
|
+
|
|
5
|
+
## 目录
|
|
6
|
+
|
|
7
|
+
```
|
|
8
|
+
bin/pp.js CLI 入口:参数解析、命令分派、退出码
|
|
9
|
+
src/commands.js 各子命令实现(up/down/restart/status/attach/logs/send/
|
|
10
|
+
check/doctor/init/install/uninstall/new)
|
|
11
|
+
src/config.js YAML → 归一化配置、argv 构建、名字解析、序号解析
|
|
12
|
+
src/yaml.js 零依赖 YAML 子集解析器
|
|
13
|
+
src/tmux.js tmux 封装(run/create/kill/list/capture/send/pipeLog/attach)
|
|
14
|
+
src/remote-pi.js <cwd>/.pi/remote-pi/config.json 读写
|
|
15
|
+
src/state.js 手动停止记录(XDG state)
|
|
16
|
+
src/autostart.js systemd / launchd 模板与安装
|
|
17
|
+
src/help.js 命令表(help 文本与补全的唯一来源)
|
|
18
|
+
src/example.js init 的模板配置
|
|
19
|
+
test/ 单元测试 + e2e.sh
|
|
20
|
+
docs/ 技术文档
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## 跑起来
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
git clone https://github.com/HardyDou/pi-plus && cd pi-plus
|
|
27
|
+
npm test # 41 个单测,不需要 tmux
|
|
28
|
+
./test/e2e.sh # 86 项端到端,需要 tmux + pi,约 2–3 分钟
|
|
29
|
+
node bin/pp.js --help
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
`e2e.sh` 会在隔离环境里跑,不会碰你的真实会话:独立 socket(`pfe2e`)、独立配置(`/tmp/e2e-pifarm/plus.yml`)、独立 state 目录,退出时 `trap` 清理。它会真的装一个 `pi-plus.service` 再删掉,所以需要 systemd(或至少 `systemctl --user` 能跑)。
|
|
33
|
+
|
|
34
|
+
想手动试:
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
S=/tmp/scratch && mkdir -p $S/demo && cat > $S/plus.yml <<'YAML'
|
|
38
|
+
version: 1
|
|
39
|
+
tmux:
|
|
40
|
+
socket: pdev
|
|
41
|
+
defaults:
|
|
42
|
+
agent: bash
|
|
43
|
+
sessions:
|
|
44
|
+
- name: demo
|
|
45
|
+
cwd: /tmp/scratch/demo
|
|
46
|
+
YAML
|
|
47
|
+
PI_PLUS_CONFIG=$S/plus.yml node bin/pp.js up
|
|
48
|
+
PI_PLUS_CONFIG=$S/plus.yml node bin/pp.js logs demo
|
|
49
|
+
tmux -L pdev kill-server
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## 改代码时的规矩
|
|
53
|
+
|
|
54
|
+
- **tmux 目标**:`has-session` / `kill-session` 用 `=name`;`send-keys` / `capture-pane` / `pipe-pane` / `set-option` 必须用 `paneTarget(name)`(`=name:`,带冒号)。写错不会报错,只会「什么都没发生」——历史上 `log:` 不写文件就是这个原因。
|
|
55
|
+
- **只读查询要传 `readOnly: true`**:否则 `--dry-run` 时 tmux 命令被短路成 `true`,`sessionExists()` 会把所有会话报成「在跑」。
|
|
56
|
+
- **所有面向用户的文本**走 `ui`(`makeUi({quiet, json, color})`),否则 `--json` / `-q` 会漏。
|
|
57
|
+
- **help 文本不要手写两份**:命令、选项、示例都写进 `src/help.js` 的 `COMMANDS`,`renderOverview` / `renderCommandHelp` 自动生成,`test/help.test.js` 会检查覆盖是否完整。
|
|
58
|
+
- **新增配置字段**:加进 `SESSION_KEYS`(否则出现 `unknown key` 警告)、在 `normalizeSession` 里解析、更新 `docs/configuration.md` 的字段表、补一条 `test/config.test.js`。
|
|
59
|
+
- **改行为要改文档**:README 的生命周期表、`docs/` 对应章节、`src/help.js` 的备注,三处一致。
|
|
60
|
+
- 配置解析一定要「宽进严出」:未知键警告但不失败,非法值报错并指出字段名。
|
|
61
|
+
|
|
62
|
+
## 测试策略
|
|
63
|
+
|
|
64
|
+
| 层 | 位置 | 覆盖什么 |
|
|
65
|
+
|---|---|---|
|
|
66
|
+
| 解析器 | `test/yaml.test.js` | 嵌套、流式、引号、注释、块标量、tab 缩进报错 |
|
|
67
|
+
| 配置归一化 | `test/config.test.js` | 默认值、名字规整、argv 顺序、restart 策略、共享 cwd 警告、序号解析 |
|
|
68
|
+
| 模板 | `test/autostart.test.js` | systemd 单元(`KillMode=none`、PATH 去重、`--reconcile`)、timer、launchd plist |
|
|
69
|
+
| 帮助 | `test/help.test.js` | 每个命令都有完整帮助页、别名解析、拼写建议 |
|
|
70
|
+
| 新会话 | `test/new.test.js` | 名字规整、`--save` 往返、拒绝无 `sessions:` 的文件 |
|
|
71
|
+
| 状态 | `test/state.test.js` | 标记/清除、按配置隔离、坏 JSON 容错 |
|
|
72
|
+
| 端到端 | `test/e2e.sh` | 真 tmux + 真 pi + 真 systemd unit 装/卸 |
|
|
73
|
+
|
|
74
|
+
单元测试一律用 `node:test` + `node:assert/strict`,不引测试框架,也不 mock 文件系统之外的东西(`mkdtemp` 就够)。
|
|
75
|
+
|
|
76
|
+
## CI
|
|
77
|
+
|
|
78
|
+
`.github/workflows/ci.yml`:ubuntu + macos × node 18/20/22,跑 `npm test`、`node bin/pp.js --version`、对模板配置跑一次 `check`(允许失败)。e2e 不进 CI(需要 tmux/pi,且会装单元)。
|
|
79
|
+
|
|
80
|
+
本地提交前:
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
npm test && node bin/pp.js --help >/dev/null && git diff --check
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
## 发布
|
|
87
|
+
|
|
88
|
+
包名 `pi-farm`,可执行文件 `pp`,版本在 `package.json` 和 `bin/pp.js` 共用前者。
|
|
89
|
+
|
|
90
|
+
npm 对开启 2FA 的账号用**分阶段发布(staged publishing)**:`npm publish` 只上传,要再执行一次 `npm publish` 才转正,否则会看到
|
|
91
|
+
|
|
92
|
+
```
|
|
93
|
+
npm error code E409 ... Cannot publish over previously staged version "0.2.0"
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
流程:
|
|
97
|
+
|
|
98
|
+
```bash
|
|
99
|
+
# 1. 改版本
|
|
100
|
+
npm version patch # 生成 tag
|
|
101
|
+
# 2. 全绿
|
|
102
|
+
npm test && ./test/e2e.sh
|
|
103
|
+
# 3. 发布(注意 registry、注意要 !bypass 2FA 的 granular token)
|
|
104
|
+
npm publish --registry https://registry.npmjs.org/
|
|
105
|
+
npm publish --registry https://registry.npmjs.org/ # 第二次 = 转正 staged 版本
|
|
106
|
+
# 4. 校验
|
|
107
|
+
npm view pi-farm version dist.tarball bin
|
|
108
|
+
npm i -g --prefix /tmp/pp-verify pi-farm --registry https://registry.npmjs.org/
|
|
109
|
+
/tmp/pp-verify/bin/pp -V
|
|
110
|
+
# 5. GitHub release
|
|
111
|
+
git push --follow-tags
|
|
112
|
+
gh release create v$(node -p "require('./package.json').version") --generate-notes
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
注意:
|
|
116
|
+
|
|
117
|
+
- token 需要 `Read and write` + **`bypass 2fa`**,否则 `E403 Two-factor authentication or granular access token with bypass 2fa enabled is required`
|
|
118
|
+
- 带 `bypass_2fa` 的 token **不能** `npm unpublish`(403),发布前测干净
|
|
119
|
+
- `0.0.0-stage` 这类占位版本是 npm 的 staged publishing 产物,正常现象
|
|
120
|
+
|
|
121
|
+
发布只改了名字/描述时,GitHub 上的 release notes 记得改成给用户看的话,别留默认 commit 列表。
|
|
122
|
+
|
|
123
|
+
## 常见坑(代码层面)
|
|
124
|
+
|
|
125
|
+
- `execFile` 的 `env` 是**替换**不是合并,必须显式带上 `PATH`(`Tmux.run` 里已经处理)
|
|
126
|
+
- `tmux -L <socket>` 与默认 socket 完全隔离,测试里别混用
|
|
127
|
+
- `systemd` oneshot 结束会清 cgroup,tmux 会被连坐杀死 → 单元必须 `KillMode=none`
|
|
128
|
+
- macOS 上 `launchctl bootstrap` 失败时回落 `load -w`,两条路都要留日志
|
|
129
|
+
- 网络路径(`/mnt/c/...`)上的 `cwd` 会让 pi 很慢,不属于 bug
|