---
date: 2026-05-10
type: pattern
scope: agent-pool / dev-environment
related: PR feature/pool-pin-codeworkspace
---

# agent pool 固化 + VSCode multi-root + Remote-SSH 叠加

## 背景

之前 `ap_pool_parent` 用"`git worktree list` 第一个非主 entry"探测池父目录——
顺序依赖脆弱，首位条目偶发是嵌套或不预期的 worktree 时，下次 `pool-init` 会
建到错误位置。同时多 agent 并行场景缺一个"单 IDE 看全部 slot 改动"的入口。

## 关键发现

### 1. 单 IDE 同时挂 main + N slot 的最轻方案：VSCode multi-root + Remote-SSH

不需要把池移进项目内部 `.worktree/`（曾考虑过，但要对抗 IDE / tsc / next / eslint
的全局扫描默认行为）。两个特性正交、可叠加：

- Remote-SSH：vscode-server 跑在远端，文件操作和终端全在远端
- multi-root workspace：`.code-workspace` 文件列 N 个 folder，IDE 文件树并排显示

只需一个 `<repo-parent>/<repo-name>.code-workspace` 文件，绝对路径全用远端路径，
本地 VSCode 通过 Remote-SSH 打开此文件，server 加载所有 folder。**N folder 必须
全在同一台远端**——multi-root 不支持跨主机混挂。

### 2. multi-root 配置作用域不会串

每个 root（slot）独立激活扩展实例：
- `slot-1/src/foo.ts` → ESLint 用 `slot-1/node_modules/eslint` + `slot-1/.eslintrc`
- `slot-2/src/foo.ts` → 完全另一份
- TypeScript server / Git SCM / 终端 CWD 同样按 root 隔离

担心的"配置串味"不会发生，每个 slot 是完全独立项目环境。

### 3. bash 生成 JSON 的"安全门"是 python heredoc 子进程

```bash
ap_write_code_workspace() {
  AP_VAR1="$value1" \
  AP_VAR2="$value2" \
  python3 - <<'PYEOF' || return 0
  # 引用 os.environ['AP_VAR1']，原子写入 + os.replace
  PYEOF
}
```

用 env 变量传值给 python 子进程，避开 bash 转义噩梦（路径含空格 / 引号 / unicode）。
原子写入用 `tmp + os.replace` 保证半写状态不会被 IDE 看到。`python3` 缺失时函数
静默 return 0——这类"锦上添花"的功能不该阻塞主流程。

### 4. 路径迁移用"检测优先级"做软兼容，不强制迁移

```bash
ap_pool_root() {
  # 1) 显式覆盖
  # 2) 新规则路径已存在 → 用它
  # 3) legacy 路径已存在 → 用它（向后兼容）
  # 4) 都不存在 → 默认按新规则建
}
```

新协作者落到新路径，老用户继续用现有目录，无需手工 migrate 或 mv。比"硬切换 +
公告迁移指南"友好得多。

## 触发条件

- 用 `git worktree list` 输出顺序做路径推断的脚本——基本一定有脆弱性，固化优先
- 多 agent / 多 worktree 并行场景，需要"单视野看全部"——multi-root 不要急着拒绝
- 用 bash 生成结构化文件（JSON / YAML）——心里默认走 python/jq 子进程，别 hand-craft

## 反例

- ❌ 把 pool 放主仓库内部 `.worktree/` 来"自包含"：要打 IDE / tsc / next / eslint
  / git clean 全套工具链，得不偿失
- ❌ 静默切换默认路径不留 fallback：现网用户的池突然"找不到"
- ❌ 用 bash 拼 JSON 字符串：路径含特殊字符就炸