Workspace Guardian — 文件组织铁律

这条规则凌驾于你的默认行为之上。 除非用户明确指定了完整路径，否则你必须按本规则决定文件存放位置和命名方式。 违反此规则 = 用户找不到文件 = 浪费 Token 反复搜索 = 信任崩塌。

---

§1 根基原则：一个项目 = 一个目录

绝不在以下位置散落文件：

• 用户主目录 ~/
• 桌面、下载、文档等系统目录
• WorkBuddy 根目录（除非是 Claw/ 下的指定项目目录）
• 任意时间戳目录（如 20260407141708/）

所有文件必须归属于一个项目目录。没有项目目录？先创建。

---

§2 项目目录结构规范

2.1 已有项目的文件去向

项目	根目录	产出物去向
芬琳漆监控	~/WorkBuddy/Claw/	直接放在根目录（已有约定：芬琳漆价格监控报告_*.xlsx、create_report_v*.py）
木铭建材网站	~/openclaw-projects/mumingbuild-new/	放在项目目录内
ERP 系统	~/openclaw-projects/erp-admin/ 或 erp-backend/	放在对应项目目录内
Hermes Agent	~/.hermes/	放在 Hermes 配置目录内
OpenClaw 配置	~/.openclaw/	放在 OpenClaw 配置目录内

2.2 新项目的目录结构

当创建新项目时，在 ~/WorkBuddy/ 或 ~/openclaw-projects/ 下建立项目目录：

~/WorkBuddy/{project-name}/
├── output/              ← 所有最终产出物（报告、图片、HTML 等）
│   ├── 2026-04-14_报告.xlsx
│   └── 2026-04-14_截图.png
├── scripts/             ← 脚本工具（Python、Shell 等）
│   └── generate_report.py
├── data/                ← 数据文件（JSON、CSV、数据库等）
│   └── products_db.xlsx
├── docs/                ← 文档（MD、指南等）
│   └── setup-guide.md
├── temp/                ← 临时文件（处理完即删）
└── README.md            ← 项目说明（必填，含项目用途和文件索引）

---

§3 文件命名规则

3.1 通用命名格式

{日期}_{描述}.{ext}

• 日期格式：YYYY-MM-DD（如 2026-04-14）
• 描述：简短中文或英文，用连字符分隔
• 示例：2026-04-14_芬琳漆价格报告.xlsx

3.2 脚本命名

• 功能性脚本：{动词}_{对象}.py（如 generate_report.py、upload_cover.py）
• 版本迭代：{动词}_{对象}_v{N}.py（如 create_report_v5.py）
• 禁止：test.py、temp.py、fix.py、new.py 等无意义命名

3.3 报告产出物命名

{项目名}_{类型}_YYYY-MM-DD.{ext}

示例：芬琳漆价格监控报告_2026-04-14.xlsx

---

§4 禁止行为清单

#	禁止行为	原因	正确做法
1	在 ~/ 根目录创建文件	污染用户主目录，无法定位	放入对应项目目录
2	创建纯时间戳目录 20260407141708/	无语义，无法回忆内容	用项目名+日期命名
3	创建空目录后不放入文件	空壳目录浪费搜索	先有文件再建目录
4	同一功能创建多个版本文件散落	fix.py、fix2.py、fix_cat.py 混乱	统一版本号：fix_cat_v2.py，旧版移入 archive/
5	在非项目目录创建临时文件	用后遗忘，占空间	使用 temp/ 目录，任务完成后清理
6	文件名含空格或特殊字符	跨平台兼容性问题	使用下划线 _ 或连字符 -

---

§5 文件创建前的三问检查

在创建任何文件或目录之前，问自己：

1. 这个文件属于哪个项目？ → 找到对应项目目录
2. 用户能在3秒内找到它吗？ → 如果不能，命名或位置有问题
3. 一周后我自己能找到它吗？ → 如果不能，加日期前缀或更明确的描述

三问中有任何一个答"否"，就重新规划位置或命名。

---

§6 特殊情况

6.1 用户明确指定路径

如果用户说"保存到 D:/reports/"或"放在桌面上"，按用户指定的路径执行，本规则让步。

6.2 自动化任务的产出物

自动化任务（如每日新闻、Token 报告）的产出物：

• Markdown 报告：直接输出在回复中，不创建文件（除非用户要求）
• Excel/PDF 等文件：放在 ~/WorkBuddy/Claw/output/ 下
• 临时中间文件：放在 ~/WorkBuddy/Claw/temp/，任务完成后删除

6.3 WorkBuddy/Claw 项目的特例

~/WorkBuddy/Claw/ 是芬琳漆监控的主项目目录，以下文件允许直接放在根目录：

• 芬琳漆价格监控报告_*.xlsx（历史约定）
• create_report_v*.py（报告生成脚本）
• 芬琳漆产品数据库.xlsx（核心数据）
• cad_area_calculator.py（CAD 工具）

其他所有新文件应遵循子目录结构。

6.4 Agent 工作区

OpenClaw 各 Agent 的工作区文件（如 ~/.openclaw/workspace-*/）由 Agent 自行管理，本规则不干预。但 Agent 在非工作区创建的文件仍需遵守本规则。

---

§7 自动清理机制

核心原则：不留垃圾，不养尸体。 生成物不被认可就删，脚本失败就清，临时文件用完即弃。

7.1 生成物即时清理

当用户明确不认可某个生成物（图片、报告、文档等）时，立即删除，不等不拖：

用户表达	判断	动作
"不好看" "不行" "不对" "重做"	不认可	删除该生成物 + 回复 🗑️ 已删除：{文件名}
"这张不要" "删掉"	明确要求删除	立即删除 + 回复确认
"再生成一个"	暗示上一个不要	删除上一个 + 生成新的
"留着吧" "还行"	认可	保留文件

执行规则：

• 图片生成：新图满意后，如果不满意的不在同一轮对话已删，立即清理
• 报告/文档：用户说"重新生成"时，旧版移入 archive/ 或直接删除（视用户语气）
• 代码文件：替换版本时，旧版移入 archive/ 并标注日期

7.2 失败脚本即时清理

脚本测试失败的处置流程：

脚本运行失败
  ├─ 致命错误（语法错误、依赖缺失、逻辑完全错误）→ 直接删除，不保留
  ├─ 部分成功（逻辑对但结果不准）→ 移入 archive/ 或修复后覆盖
  └─ 环境问题（权限、网络、超时）→ 保留，标注原因，稍后重试

判断标准：

失败类型	示例	处置
语法错误	SyntaxError、ModuleNotFoundError	修复覆盖或删除
逻辑完全错误	输出全部错误、空结果	删除重写
部分正确	格式有小错、少数字段缺失	修复覆盖
环境限制	连接超时、权限不足	保留 + 注释说明

执行后回复格式：

🗑️ 已清理失败脚本：{文件名}（原因：{简要原因}）

7.3 temp/ 目录定时清扫

temp/ 是临时文件区，用完即清：

• 每次任务完成后，检查 temp/ 中本任务产生的文件
• 已被最终产出物引用或合并的临时文件 → 立即删除
• 暂时不确定是否还需要 → 保留，但最迟 24 小时后清理
• 清理时回复：🧹 已清扫临时文件：{文件名}

7.4 archive/ 目录管理

archive/ 不是垃圾场，只放有参考价值的旧版本：

• 保留最近 3 个版本，更早的删除
• 每次归档时在文件名中标注日期：create_report_v4_2026-04-09.py
• archive/ 总大小超过 50MB 时，提醒用户清理

7.5 空目录清扫

创建目录后如果未放入任何文件，在任务结束时：

• 删除空目录
• 回复：🧹 已清理空目录：{目录名}

---

§8 执行自检

每次创建文件后，在回复中简述：

📁 已保存：{项目目录}/{子目录}/{文件名}

让用户确认文件位置可预期。

---

§9 现有混乱清理建议（仅供参考，不自动执行）

当前 ~/ 根目录散落大量脚本（约80+个 .py 文件），建议用户择机整理：

• SSH 相关脚本 → ~/scripts/ssh/
• 微信上传脚本 → ~/scripts/wechat/
• ERP 相关脚本 → ~/openclaw-projects/erp-admin/scripts/
• 芬琳漆脚本 → ~/WorkBuddy/Claw/scripts/
• 临时/一次性脚本 → 确认无用后删除

此清理需用户确认后执行，不自动进行。