# Project Workspace Layout

**Created:** 2026-03-18  
**Topic:** 多机并行开发时的工程目录、命名结构与 worktree 规范

---

## 决策结论

OpenClaw 体系下，正式工程项目的默认根目录统一设为：

`~/project/workspace`

每个正式项目使用一个独立的“项目容器目录”：

`~/project/workspace/<project-name>`

该容器目录用于承载：

- 多个子仓库（multi-repo）
- 每个子仓库的并行 `git worktree`
- 项目级共享资料、文档、脚本与临时文件

这条规则面向以下机器统一生效：

- `mac-5 = brain`
- `mac-6 = hands`
- `mac-7 = eyes`

目标是让三台机器在**相同路径语义**下工作，便于 ACP / OpenCode / OpenClaw 调度、脚本复用、并行开发、分支合并与后续备份管理。

---

## 为什么不用直接把所有仓库平铺在 `~/project`

虽然 `~/project/<repo>` 的平铺方式可以工作，但在当前体系下不够稳定，原因有：

1. `~/project` 已经承载长期资产，不仅有工程代码，也有记忆仓库等长期资料
2. 后续项目数量增多时，平铺结构会让“正式工程 / 临时实验 / 记忆系统 / 参考仓库”混在一起
3. 多机并行时，需要一个更清晰的默认工程根路径，便于 ACP 调度时直接假设落盘位置

因此推荐额外收敛一层：

- `~/project/workspace`：正式工程区
- `~/project/collective-memory-repo`：记忆系统
- 其他目录（若后续存在）再按用途单独划分

---

## 标准目录结构

每个项目使用如下结构：

```text
~/project/workspace/<project-name>/
├── repos/        # 真正的 git 仓库
├── worktrees/    # 各 repo 的并行工作树
├── shared/       # 项目级共享资料（样例数据、草稿、协议表等）
├── docs/         # 架构文档、设计说明、任务拆分
├── scripts/      # 项目级自动化脚本
└── tmp/          # 临时文件、构建产物、实验输出
```

### 各目录职责

#### `repos/`
用于存放真正的 git 仓库主目录。

示例：

```text
~/project/workspace/acme-platform/repos/backend
~/project/workspace/acme-platform/repos/frontend
~/project/workspace/acme-platform/repos/admin-panel
```

#### `worktrees/`
用于存放每个仓库派生出来的并行 `git worktree`。

示例：

```text
~/project/workspace/acme-platform/worktrees/backend/feat-auth
~/project/workspace/acme-platform/worktrees/backend/feat-payment
~/project/workspace/acme-platform/worktrees/frontend/feat-dashboard
```

#### `shared/`
用于放不适合直接塞进某个 repo 的共享资料，例如：

- 需求草稿
- 原型截图
- 样例数据
- 外部接口对照表
- 跨仓库共享的项目说明

#### `docs/`
用于项目级文档，例如：

- 系统架构
- 任务拆分
- 分支策略
- 合并策略
- 节点分工约定

#### `scripts/`
用于项目级自动化脚本，例如：

- 初始化仓库脚本
- 批量创建 worktree 脚本
- 多仓状态检查脚本
- 集成构建脚本

#### `tmp/`
用于临时输出，不应作为长期事实或主源码归档位置。

---

## 项目环境管理规范

### 默认环境管理器

每个正式项目默认优先使用 **Pixi** 管理开发环境。

也就是说，在项目根目录中应优先存在：

- `pixi.toml`

若项目需要锁定依赖解析结果，可同时存在：

- `pixi.lock`

### 默认原则

1. **优先 Pixi，后备 UV**
   - 能用 Pixi 时，优先用 Pixi
   - 只有在 Pixi 明显失效、无法满足项目要求、或兼容性阻塞时，才退回使用 UV
2. **每个项目应有自己的环境定义**
   - 项目级环境配置应跟随项目保存，而不是完全依赖机器全局环境
3. **环境管理配置应可被版本控制**
   - `pixi.toml` 应纳入版本控制
   - `pixi.lock` 若项目需要可复现构建，也应纳入版本控制
4. **环境产物不纳入版本控制**
   - `.pixi/` 不应被 git 跟踪
   - UV 产生的本地环境目录（若使用）也不应被 git 跟踪

### `.pixi` 跟踪规则

Pixi 的本地环境与缓存目录通常位于项目内的隐藏目录：

- `.pixi/`

该目录属于**本地生成的环境产物**，不应被提交到仓库。

因此每个使用 Pixi 的项目都应确保 `.gitignore` 中包含：

```gitignore
.pixi/
```

### UV 作为后备方案

若 Pixi 失效，可使用 **UV** 作为后备环境管理器。

适用场景包括但不限于：

- 某项目在 Pixi 下无法稳定解析或构建
- 某些 Python 工作流临时更适合 UV
- 上游工具链对 UV 支持更直接，而 Pixi 暂时不兼容

但长期默认规则仍然是：

- **先尝试 Pixi**
- **必要时再切 UV**

### 为什么优先 Pixi

在当前工程体系下，Pixi 的优势在于：

- 可以统一管理多语言开发环境
- 可以覆盖 Conda / Python / Node.js 等常见工程依赖场景
- 项目级定义更清晰，便于多机复现
- 对后续 OpenClaw / ACP / OpenCode 在统一工程目录下执行任务更友好

因此，后续如果没有特殊说明：

- 新项目默认按 Pixi 项目处理
- 环境初始化优先考虑 `pixi.toml`
- 只有在 Pixi 不适用时才考虑 UV 替代

---

## 多机并行开发规范

### 路径统一规则

`mac-5` / `mac-6` / `mac-7` 都应尽量使用相同的默认工程路径：

`~/project/workspace`

这样带来的好处：

- ACP 任务默认落盘路径统一
- OpenCode / OpenClaw / 脚本不必按机器写不同路径适配
- 文档、自动化、约定都更稳定
- 便于把“项目位置”作为长期记忆规则直接复用

### 推荐同步方式

正式代码同步**以 git remote 为主**，而不是以文件系统实时同步为主。

也就是说：

- 三台机器都各自保留一份本地 clone / 本地项目容器目录
- 通过 `commit / push / fetch / merge` 协作
- 不把活跃 `.git` / `worktree` 元数据作为实时文件同步对象

### 不推荐的主同步方式

不推荐把带 `.git` 与 `git worktree` 元数据的活跃工程目录直接通过 iCloud / Dropbox / Syncthing 一类文件同步工具作为主协作方式，因为这容易导致：

- `.git` 元数据不一致
- `worktree` 注册状态冲突
- merge / rebase 中间态被污染
- 不同机器删除/修改 worktree 后状态漂移

结论：

- **代码主协作：git remote**
- **文件级同步：仅限非关键共享资料，且谨慎使用**

---

## `git worktree` 规范

### worktree 应放在项目容器的 `worktrees/` 下

推荐：

```text
~/project/workspace/<project-name>/worktrees/<repo-name>/<task-or-branch-name>
```

不推荐把 worktree 塞进 repo 内部隐藏目录，例如：

```text
~/project/workspace/<project-name>/repos/backend/.worktrees/feat-auth
```

原因：

- repo 主体与 worktree 混在一起，不利于观察
- 清理、归档、排错都更麻烦
- 对 ACP / 自动化调度不够直观

### worktree 命名建议

优先使用可读、可映射任务意图的名字：

- `feat-auth`
- `feat-dashboard`
- `fix-logging`
- `refactor-api-client`
- `integration-merge`

若任务较多，可加前缀或编号：

- `task-001-auth`
- `task-002-billing`
- `exp-ui-variant-a`

原则：

- 人能看懂
- 一眼知道用途
- 尽量避免纯随机命名

---

## ACP / OpenCode 调度约定

当需要让 OpenClaw / ACP / OpenCode 去拉取项目、创建项目、修改项目时，默认应优先把项目放到：

`~/project/workspace`

即：

- clone 新项目 → 放到 `~/project/workspace/<project-name>/repos/...`
- 新建 worktree → 放到 `~/project/workspace/<project-name>/worktrees/...`
- 项目级说明 / 草稿 / 协作文档 → 放到对应项目下的 `docs/` 或 `shared/`

这意味着：

1. 后续如果 hotwa 说“把这个项目拉下来改一下”，默认工程根路径应优先理解为 `~/project/workspace`
2. 如果没有更具体要求，应默认遵循本文件定义的项目容器结构
3. 若某次任务出于兼容原因必须使用其他路径，应在任务内显式说明，不覆盖该长期默认规则

---

## 节点分工建议

在当前集群中，推荐分工如下：

- `mac-5 = brain`：主控、任务拆分、审查、最终集成与合并
- `mac-6 = hands`：执行、编码、构建、脚本与通用实现任务
- `mac-7 = eyes`：浏览器相关实现、页面验证、截图与验收

典型并行方式：

- 各节点在自己的本地项目副本上工作
- 各自切 feature branch 或使用各自 worktree
- 完成后提交到远端
- 最终在 `mac-5` 做集成合并与主线收敛

---

## 默认操作原则

1. 正式工程优先落在 `~/project/workspace`
2. 一个大项目优先使用一个项目容器目录
3. 多子目录若本质是独立仓库，应放到 `repos/`
4. 并行开发优先使用 `worktrees/`，而不是直接多点改同一个 checkout
5. 多机协作优先使用 git 分支与远端合并，不依赖活跃仓库的文件级同步
6. 最终集成与合并优先在 `mac-5` 完成
7. 临时实验文件不要污染 `repos/` 与 `worktrees/` 的主结构

---

## 适用范围

这是一条**长期默认工程组织规则**，适用于：

- 后续新建项目
- 拉取外部项目进行二次开发
- 由 OpenClaw / ACP / OpenCode 创建或修改的工程任务
- 多机并行开发和后续代码合并流程

若未来出现更高优先级的统一工程目录标准，应显式更新本文件并同步到相关记忆索引。