Add project workspace layout standard
This commit is contained in:
hotwa
@@ -16,6 +16,12 @@
|
||||
- mac-5 = brain（控制与编排）
|
||||
- mac-6 = hands（执行与算力）
|
||||
- mac-7 = eyes（浏览器与验收）
|
||||
- stable_project_workspace_rule:
|
||||
- 正式工程默认根目录：`~/project/workspace`
|
||||
- 项目容器结构：`~/project/workspace/<project-name>/repos|worktrees|shared|docs|scripts|tmp`
|
||||
- 多机并行协作默认采用：各机器本地副本 + git remote 同步
|
||||
- 不把活跃 `.git` / `git worktree` 元数据目录作为文件实时同步主方案
|
||||
- 最终集成与合并优先在 `mac-5` 完成
|
||||
- next_actions:
|
||||
- 验证 gateway 重启后新 provider / agent 是否全部生效
|
||||
- 实测 `local-mac5/local-mac6/local-mac7` 的 subagent 调度链路
|
||||
|
||||
@@ -32,3 +32,24 @@
|
||||
|
||||
- 这次更新针对的是 `opencode` 默认模型策略，不等于废弃原有 subagent / worker 的本地模型拓扑说明
|
||||
- 后续涉及 `opencode` 默认模型时，应优先引用本日规则，而不是旧的“每机默认本地 oMLX”说法
|
||||
|
||||
## 工程目录默认规则确定
|
||||
|
||||
- 已确定正式工程项目的默认根目录使用：`~/project/workspace`
|
||||
- 理由：
|
||||
- 与 `~/openclawd` 运行时目录分离
|
||||
- 与 `~/project/collective-memory-repo` 记忆系统分离
|
||||
- 便于 `mac-5` / `mac-6` / `mac-7` 统一使用相同路径语义
|
||||
- 便于 OpenClaw / ACP / OpenCode 默认按统一路径落盘与调度
|
||||
- 已确定每个正式项目使用项目容器结构：
|
||||
- `~/project/workspace/<project-name>/repos/`
|
||||
- `~/project/workspace/<project-name>/worktrees/`
|
||||
- `~/project/workspace/<project-name>/shared/`
|
||||
- `~/project/workspace/<project-name>/docs/`
|
||||
- `~/project/workspace/<project-name>/scripts/`
|
||||
- `~/project/workspace/<project-name>/tmp/`
|
||||
- 多机协作默认采用方案 A：
|
||||
- 三台机器各自保留本地项目副本
|
||||
- 代码同步以 git remote 为主
|
||||
- 不以文件级实时同步 `.git` / `worktree` 元数据作为主协作方式
|
||||
- 已新增长期决策文档：`shared/long-term/decisions/project-workspace-layout.md`
|
||||
|
||||
264
shared/long-term/decisions/project-workspace-layout.md
Normal file
264
shared/long-term/decisions/project-workspace-layout.md
Normal file
@@ -0,0 +1,264 @@
|
||||
# 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 创建或修改的工程任务
|
||||
- 多机并行开发和后续代码合并流程
|
||||
|
||||
若未来出现更高优先级的统一工程目录标准，应显式更新本文件并同步到相关记忆索引。
|
||||
Reference in New Issue
Block a user