265 lines
7.2 KiB
Markdown
265 lines
7.2 KiB
Markdown
# 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/`
|
||
用于临时输出，不应作为长期事实或主源码归档位置。
|
||
|
||
---
|
||
|
||
## 多机并行开发规范
|
||
|
||
### 路径统一规则
|
||
|
||
`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 创建或修改的工程任务
|
||
- 多机并行开发和后续代码合并流程
|
||
|
||
若未来出现更高优先级的统一工程目录标准，应显式更新本文件并同步到相关记忆索引。
|