From f934693a604c4811835e17dad27a6308ebd252ce Mon Sep 17 00:00:00 2001 From: hotwa Date: Wed, 18 Mar 2026 00:23:46 +0800 Subject: [PATCH] Add project workspace layout standard --- agents/openclaw-main/current.md | 6 + daily/2026-03-18.md | 21 ++ .../decisions/project-workspace-layout.md | 264 ++++++++++++++++++ 3 files changed, 291 insertions(+) create mode 100644 shared/long-term/decisions/project-workspace-layout.md diff --git a/agents/openclaw-main/current.md b/agents/openclaw-main/current.md index 406382f..8cca182 100644 --- a/agents/openclaw-main/current.md +++ b/agents/openclaw-main/current.md @@ -16,6 +16,12 @@ - mac-5 = brain（控制与编排） - mac-6 = hands（执行与算力） - mac-7 = eyes（浏览器与验收） +- stable_project_workspace_rule: + - 正式工程默认根目录：`~/project/workspace` + - 项目容器结构：`~/project/workspace//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 调度链路 diff --git a/daily/2026-03-18.md b/daily/2026-03-18.md index 3394937..9a98318 100644 --- a/daily/2026-03-18.md +++ b/daily/2026-03-18.md @@ -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//repos/` + - `~/project/workspace//worktrees/` + - `~/project/workspace//shared/` + - `~/project/workspace//docs/` + - `~/project/workspace//scripts/` + - `~/project/workspace//tmp/` +- 多机协作默认采用方案 A： + - 三台机器各自保留本地项目副本 + - 代码同步以 git remote 为主 + - 不以文件级实时同步 `.git` / `worktree` 元数据作为主协作方式 +- 已新增长期决策文档：`shared/long-term/decisions/project-workspace-layout.md` diff --git a/shared/long-term/decisions/project-workspace-layout.md b/shared/long-term/decisions/project-workspace-layout.md new file mode 100644 index 0000000..6d27004 --- /dev/null +++ b/shared/long-term/decisions/project-workspace-layout.md @@ -0,0 +1,264 @@ +# Project Workspace Layout + +**Created:** 2026-03-18 +**Topic:** 多机并行开发时的工程目录、命名结构与 worktree 规范 + +--- + +## 决策结论 + +OpenClaw 体系下，正式工程项目的默认根目录统一设为： + +`~/project/workspace` + +每个正式项目使用一个独立的“项目容器目录”： + +`~/project/workspace/` + +该容器目录用于承载： + +- 多个子仓库（multi-repo） +- 每个子仓库的并行 `git worktree` +- 项目级共享资料、文档、脚本与临时文件 + +这条规则面向以下机器统一生效： + +- `mac-5 = brain` +- `mac-6 = hands` +- `mac-7 = eyes` + +目标是让三台机器在**相同路径语义**下工作，便于 ACP / OpenCode / OpenClaw 调度、脚本复用、并行开发、分支合并与后续备份管理。 + +--- + +## 为什么不用直接把所有仓库平铺在 `~/project` + +虽然 `~/project/` 的平铺方式可以工作，但在当前体系下不够稳定，原因有： + +1. `~/project` 已经承载长期资产，不仅有工程代码，也有记忆仓库等长期资料 +2. 后续项目数量增多时，平铺结构会让“正式工程 / 临时实验 / 记忆系统 / 参考仓库”混在一起 +3. 多机并行时，需要一个更清晰的默认工程根路径，便于 ACP 调度时直接假设落盘位置 + +因此推荐额外收敛一层： + +- `~/project/workspace`：正式工程区 +- `~/project/collective-memory-repo`：记忆系统 +- 其他目录（若后续存在）再按用途单独划分 + +--- + +## 标准目录结构 + +每个项目使用如下结构： + +```text +~/project/workspace// +├── 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//worktrees// +``` + +不推荐把 worktree 塞进 repo 内部隐藏目录，例如： + +```text +~/project/workspace//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//repos/...` +- 新建 worktree → 放到 `~/project/workspace//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 创建或修改的工程任务 +- 多机并行开发和后续代码合并流程 + +若未来出现更高优先级的统一工程目录标准，应显式更新本文件并同步到相关记忆索引。