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
|
@@ -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
|
|
@@ -0,0 +1,204 @@
|
|
|
1
|
+
# 排障手册
|
|
2
|
+
|
|
3
|
+
按「你看到的原文」查。每条都附上验证命令。
|
|
4
|
+
|
|
5
|
+
## 启动类
|
|
6
|
+
|
|
7
|
+
### `session "backend" exited immediately`
|
|
8
|
+
|
|
9
|
+
```
|
|
10
|
+
error: session "backend" exited immediately
|
|
11
|
+
[backend] ...(pane 最后几行输出)
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
`pp up` 在创建会话 600ms 后会检查 pane 是否还活着,死了就把截到的输出打出来。常见原因依次排查:
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
pp up backend -v --dry-run # ① 打印真实 argv,确认 agent/参数/目录
|
|
18
|
+
pp check backend # ② cwd 是否存在、agent 是否在 PATH
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
- **agent 不在 PATH 上**:systemd/非交互 shell 的 PATH 很短。用绝对路径:`agent: /home/you/.nvm/versions/node/v26.13.1/bin/pi`
|
|
22
|
+
- **pi 参数不合法**:例如 `pi_session` 里有大写以外非法字符,或 `pi_session_dir` 指向不可写的目录。pi 会直接退出
|
|
23
|
+
- **cwd 不存在**:`cwd does not exist: /path`
|
|
24
|
+
- 想看到完整报错:临时加 `remain_on_exit: true`,然后 `pp logs backend -n 200`
|
|
25
|
+
|
|
26
|
+
### `cwd does not exist: /home/you/code/backend`
|
|
27
|
+
|
|
28
|
+
配置文件里的目录在这台机器上不存在(典型:`pp init` 生成的模板)。改 `cwd` 或先 `mkdir -p`。
|
|
29
|
+
|
|
30
|
+
### `directory does not exist: /tmp/x`(`pp new -C`)
|
|
31
|
+
|
|
32
|
+
`-C` 只接受已存在的目录,不会替你创建。
|
|
33
|
+
|
|
34
|
+
### `error: unknown session "9" (7 session(s) configured; see pp ls)`
|
|
35
|
+
|
|
36
|
+
序号从 1 开始,且只按**配置文件里的顺序**,不是 `pp ls` 筛过之后的顺序(筛过时请用名字)。
|
|
37
|
+
|
|
38
|
+
### `tmux session "api" already exists (--force to recreate, or pick another name)`
|
|
39
|
+
|
|
40
|
+
`pp new api` 撞名。`--force` 重建,或换个名字。
|
|
41
|
+
|
|
42
|
+
## tmux 类
|
|
43
|
+
|
|
44
|
+
### `tmux ... can't find pane: =backend`
|
|
45
|
+
|
|
46
|
+
0.2 之前的 bug:`send-keys` / `capture-pane` 的目标必须是 `=name:`(带冒号),而 `has-session` / `kill-session` 用 `=name`。升级即可。自查:
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
tmux list-panes -a -F '#{session_name}:#{pane_id}' | head
|
|
50
|
+
tmux send-keys -t '=backend:' 'echo ok' Enter # 冒号不能少
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
### `no server running on /tmp/tmux-1000/pi-plus`
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
pp ls # 空表 = 确实没有会话
|
|
57
|
+
pp doctor # tmux server 那行会写 not running (starts on demand)
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
用了 `--socket pi-plus` 时,你的 shell 里 `tmux ls` 看不到这些会话——需要 `tmux -L pi-plus ls`。
|
|
61
|
+
|
|
62
|
+
### 会话在 `tmux ls` 里有,但 `pp ls` 显示 `off`
|
|
63
|
+
|
|
64
|
+
两边看的不是同一个 socket。检查配置里的 `tmux.socket` 和你 `tmux ls` 用的 socket 是否一致;另外自启单元不会带命令行 `--socket`(只认配置文件里的 `tmux.socket`)。
|
|
65
|
+
|
|
66
|
+
### `STATE=dead`
|
|
67
|
+
|
|
68
|
+
pane 里的进程退出了,`remain-on-exit` 把 pane 留在那儿。看怎么回事:
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
pp logs backend -n 200
|
|
72
|
+
pp up backend # 重建(restart: no 的会话必须点名)
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
## 名字 / remote-pi 类
|
|
76
|
+
|
|
77
|
+
### mesh 里看到的不是我配的名字
|
|
78
|
+
|
|
79
|
+
1. `cat <cwd>/.pi/remote-pi/config.json` 看 `agent_name`
|
|
80
|
+
2. 同一目录两个会话要求不同名字 → 必须 `remote_pi_mode: env`(文件只有一个 `agent_name`,`config` 模式最后一次写赢)
|
|
81
|
+
3. broker 侧同名冲突会临时显示 `name#2`,不会写回配置
|
|
82
|
+
|
|
83
|
+
```bash
|
|
84
|
+
pp check # 共享 cwd + config 模式会给出警告
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
### 想彻底不进 mesh
|
|
88
|
+
|
|
89
|
+
```yaml
|
|
90
|
+
remote_pi_mode: off
|
|
91
|
+
# 或
|
|
92
|
+
remote_pi_name: false
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
`pp new` 加 `--no-remote-pi`。
|
|
96
|
+
|
|
97
|
+
### pi 里 `/session` 看到的名字不是我想的
|
|
98
|
+
|
|
99
|
+
那是 `pi_session_name`(`--name`),不是 tmux 名,也不是 remote-pi 名。看 [configuration.md](configuration.md#名字映射速查)。
|
|
100
|
+
|
|
101
|
+
## 自启类
|
|
102
|
+
|
|
103
|
+
### 重启后一个会话都没有,但 `systemctl --user is-enabled pi-plus` 说 enabled
|
|
104
|
+
|
|
105
|
+
三种可能,按概率:
|
|
106
|
+
|
|
107
|
+
1. **没开 linger**(服务器/无图形登录):`sudo loginctl enable-linger "$USER"`
|
|
108
|
+
2. **WSL2**:发行版要有人调 `wsl.exe` 才会起来的,Windows 侧必须配触发(见 [autostart.md](autostart.md#wsl2只有里面装是不够的))
|
|
109
|
+
3. **单元里没有 `KillMode=none`**:现象是 `Result=success` 但 tmux server 被 systemd 连坐杀掉了。老版本升级后请重装单元:`pp uninstall && pp install`
|
|
110
|
+
|
|
111
|
+
验证是不是第 3 种:
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
systemctl --user show pi-plus -p Result -p ExecMainStatus # success
|
|
115
|
+
tmux ls # 空的 → 就是它
|
|
116
|
+
grep KillMode ~/.config/systemd/user/pi-plus.service # 应该 =none
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
### 会话起来但立刻又被杀
|
|
120
|
+
|
|
121
|
+
`pp install` 之后又手动 `systemctl --user restart pi-plus.service`:oneshot 每次执行都会跑 `up --reconcile`,如果配置文件里某会话已 dead 且 `restart: always`,会被重建——这是预期行为,不是杀。
|
|
122
|
+
|
|
123
|
+
### 手动 `down` 的会话,巡检又起来了
|
|
124
|
+
|
|
125
|
+
只有 `always` 会。`unless-stopped` / `on-failure` 的手动停止记录在 `~/.local/state/pi-plus/state.json`:
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
cat ~/.local/state/pi-plus/state.json
|
|
129
|
+
pp up backend # 点名启动会清掉这条记录,重新纳入巡检
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
## attach 类
|
|
133
|
+
|
|
134
|
+
### 从脚本 / agent 里 `pp attach` 输出乱码或卡住
|
|
135
|
+
|
|
136
|
+
`attach` 需要真正的终端(pty + termios)。非 TTY 直接拒绝,用 `script`、`expect`、管道都不行——你会得到 cooked mode,方向键变成 `ESC [ A` 之类的字面量。
|
|
137
|
+
|
|
138
|
+
- 本机:在真终端里跑 `pp attach backend`
|
|
139
|
+
- 远程:`ssh -t host 'pp attach backend'`(`-t` 必须有)
|
|
140
|
+
- 只想看输出:`pp logs backend -n 500` 或 `tail -f ~/.pi/plus/logs/backend.log`
|
|
141
|
+
|
|
142
|
+
## 发布 / 安装类
|
|
143
|
+
|
|
144
|
+
### `npm i -g pi-farm` 装到的是别的东西或 404
|
|
145
|
+
|
|
146
|
+
内网镜像 `npm config get registry` 指向 Nexus 时拿不到公网包:
|
|
147
|
+
|
|
148
|
+
```bash
|
|
149
|
+
npm i -g pi-farm --registry https://registry.npmjs.org/
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
### `pp: command not found`
|
|
153
|
+
|
|
154
|
+
```bash
|
|
155
|
+
npm bin -g 2>/dev/null || echo "$(npm root -g)/../bin"
|
|
156
|
+
echo "$PATH" | tr ':' '\n' | grep -i node
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
nvm 的全局 bin 通常在 `~/.nvm/versions/node/vX/bin`,装完要重开 shell 或 `hash -r`。
|
|
160
|
+
|
|
161
|
+
### `pp -V` 的版本和 GitHub 上不一致
|
|
162
|
+
|
|
163
|
+
```bash
|
|
164
|
+
which -a pp # 可能还有旧的 ~/.local/bin/pp 符号链接
|
|
165
|
+
npm ls -g --depth=0 | grep pi-farm
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
## 配置类
|
|
169
|
+
|
|
170
|
+
### `unknown key "pi_sesion" (ignored)` 之类的警告
|
|
171
|
+
|
|
172
|
+
拼写错误被忽略而不是报错(故意这么设计,免得升级时新增字段导致旧配置无法解析)。`pp check` 会列出所有警告。
|
|
173
|
+
|
|
174
|
+
### `config file not found`
|
|
175
|
+
|
|
176
|
+
```bash
|
|
177
|
+
pp check # 会打印实际搜索过的路径
|
|
178
|
+
PI_PLUS_CONFIG=/path/to/plus.yml pp ls
|
|
179
|
+
pp init # 写一份模板到 ~/.pi/plus.yml
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
### 想确认某个字段到底被解析成了什么
|
|
183
|
+
|
|
184
|
+
```bash
|
|
185
|
+
pp check --json | jq '.sessions[]? // .' # 或
|
|
186
|
+
pp up backend --dry-run -v # 打印最终 argv + env
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
`--dry-run` 会显示形如:
|
|
190
|
+
|
|
191
|
+
```
|
|
192
|
+
[backend] cwd=/home/you/code/backend tmux=backend pi-session=backend remote-pi=backend(mode=config)
|
|
193
|
+
[dry-run] tmux new-session -d -s backend -c /home/you/code/backend -- env ... pi --name backend
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
## 还是不行
|
|
197
|
+
|
|
198
|
+
```bash
|
|
199
|
+
pp doctor --json | jq
|
|
200
|
+
pp check --json | jq
|
|
201
|
+
pp up <name> -v --dry-run
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
把这四条的输出贴到 issue(记得先脱敏路径)。
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-farm",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.3",
|
|
4
4
|
"description": "Declarative tmux sessions for pi coding agents (CLI: pp). One YAML drives the tmux session, pi session id/name and remote-pi mesh name, and survives reboots.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -11,6 +11,7 @@
|
|
|
11
11
|
"src",
|
|
12
12
|
"examples",
|
|
13
13
|
"completions",
|
|
14
|
+
"docs",
|
|
14
15
|
"README.md",
|
|
15
16
|
"LICENSE"
|
|
16
17
|
],
|
package/src/autostart.js
CHANGED
|
@@ -229,7 +229,13 @@ export function installAutostart({ scriptPath, configPath, watch = false, print
|
|
|
229
229
|
if (timer) {
|
|
230
230
|
run("systemctl", ["--user", "enable", "--now", `${SERVICE_NAME}.timer`], { allowFailure: true });
|
|
231
231
|
} else {
|
|
232
|
-
|
|
232
|
+
// `restart` (not `start`): the oneshot stays "active (exited)" after a
|
|
233
|
+
// run, so `start` would be a no-op when installing over an old unit —
|
|
234
|
+
// which is exactly the "I ran `pp down`, then `pp install`" case.
|
|
235
|
+
const restarted = run("systemctl", ["--user", "restart", `${SERVICE_NAME}.service`], { allowFailure: true });
|
|
236
|
+
if (restarted.status !== 0) {
|
|
237
|
+
run("systemctl", ["--user", "start", `${SERVICE_NAME}.service`], { allowFailure: true });
|
|
238
|
+
}
|
|
233
239
|
}
|
|
234
240
|
run("loginctl", ["enable-linger", process.env.USER || ""], { allowFailure: true });
|
|
235
241
|
}
|