From f635fff3e6a5996663ae51aab8712652ec6e87ea Mon Sep 17 00:00:00 2001
From: hotwa <ze.ga@qq.com>
Date: Wed, 18 Mar 2026 00:34:12 +0800
Subject: [PATCH] Record Pixi-first project environment rule

---
 agents/openclaw-main/current.md               |  3 +
 daily/2026-03-18.md                           |  6 ++
 .../decisions/project-workspace-layout.md     | 74 +++++++++++++++++++
 3 files changed, 83 insertions(+)

diff --git a/agents/openclaw-main/current.md b/agents/openclaw-main/current.md
index 8cca182..4658213 100644
--- a/agents/openclaw-main/current.md
+++ b/agents/openclaw-main/current.md
@@ -19,6 +19,9 @@
 - stable_project_workspace_rule:
   - 正式工程默认根目录：`~/project/workspace`
   - 项目容器结构：`~/project/workspace/<project-name>/repos|worktrees|shared|docs|scripts|tmp`
+  - 项目环境默认优先使用 Pixi；每个项目应有 `pixi.toml`
+  - `.pixi/` 属于本地环境产物，不应纳入 git 跟踪
+  - 若 Pixi 失效或不适用，可使用 UV 作为后备环境管理方案
   - 多机并行协作默认采用：各机器本地副本 + git remote 同步
   - 不把活跃 `.git` / `git worktree` 元数据目录作为文件实时同步主方案
   - 最终集成与合并优先在 `mac-5` 完成
diff --git a/daily/2026-03-18.md b/daily/2026-03-18.md
index 9a98318..5e7d68e 100644
--- a/daily/2026-03-18.md
+++ b/daily/2026-03-18.md
@@ -52,4 +52,10 @@
   - 三台机器各自保留本地项目副本
   - 代码同步以 git remote 为主
   - 不以文件级实时同步 `.git` / `worktree` 元数据作为主协作方式
+- 项目环境管理规则已补充：
+  - 每个正式项目默认优先使用 Pixi 管理环境
+  - 每个项目应有 `pixi.toml`
+  - `.pixi/` 不纳入 git 跟踪
+  - 若 Pixi 失效或不适用，可使用 UV 作为后备方案
+  - 默认应把 Pixi 作为首选项目环境管理器
 - 已新增长期决策文档：`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
index 6d27004..41cc55a 100644
--- a/shared/long-term/decisions/project-workspace-layout.md
+++ b/shared/long-term/decisions/project-workspace-layout.md
@@ -116,6 +116,80 @@ OpenClaw 体系下，正式工程项目的默认根目录统一设为：
 
 ---
 
+## 项目环境管理规范
+
+### 默认环境管理器
+
+每个正式项目默认优先使用 **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 替代
+
+---
+
 ## 多机并行开发规范
 
 ### 路径统一规则