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.
@@ -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.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
- run("systemctl", ["--user", "start", `${SERVICE_NAME}.service`], { allowFailure: true });
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
  }