---
date: 2026-05-10
tags: [agent-pool, vscode, code-workspace]
---

# `.code-workspace` 双文件陷阱：旧手工文件 vs 新自动维护文件

## 场景

PR #285 引入 `.code-workspace` 自动维护机制后，本机有两个 workspace 文件：

| 文件 | 维护方 | 路径 |
|---|---|---|
| `workspace.code-workspace` | `pool-init` / `pool-resize` / `agent-claim` / `agent-release` 自动维护 | `<repo-parent>/<repo>.code-workspace` |
| `ffoa.code-workspace` | 上个时代手工维护的遗留 | 同目录 |

VSCode multi-root 默认打开旧的 `ffoa.code-workspace`（recent workspaces 记忆），用户看到的状态是几周前手编时的快照（slot-2/3 永远显示 `(free)`、`slot-4` 根本没列）。

## 根因

`ap_codeworkspace_file()` （`agent-pool-lib.sh:185`）路径解析：

```bash
echo "$(dirname "${main_dir}")/$(basename "${main_dir}").code-workspace"
```

主仓库目录 `workspace` → 自动维护 `workspace.code-workspace`。**不扫描兄弟 `*.code-workspace` 文件**，旧文件无人管。

## 处理

- 优先：删旧文件，让 VSCode 用 File → Open Workspace from File 重新选 `workspace.code-workspace`
- 次选：把旧文件 symlink 到新文件，零侧改动但易混淆
- 不推荐：改脚本同时维护多文件（增加复杂度，没必要为历史包袱让代码扛）

`FFOA_CODEWORKSPACE_FILE` env var 可覆盖（单值），需要别名时单独 export。

## 给未来 AI 的判断

用户报告"VSCode 侧边栏显示不对 / slot 状态错位"先做：

```bash
ls -la <repo-parent>/*.code-workspace
```

只有一个 = 不是这个陷阱；多于一个 = 用户大概率打开了旧的，先确认他 VSCode 当前打开哪个文件。