lingyuzeng/collective-memory-repo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f635fff3e6a5996663ae51aab8712652ec6e87ea
collective-memory-repo/shared/long-term/decisions/project-workspace-layout.md
hotwa f635fff3e6 Record Pixi-first project environment rule
2026-03-18 00:34:12 +08:00

9.2 KiB
Raw Blame History

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：记忆系统
  • 其他目录（若后续存在）再按用途单独划分

标准目录结构

每个项目使用如下结构：

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

各目录职责

repos/

用于存放真正的 git 仓库主目录。

示例：

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

worktrees/

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

示例：

~/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 中包含：

.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/ 下

推荐：

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

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

~/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 View Git Blame Copy Permalink