Smart Workspace Organizer 📁 / 智能项目文件组织助手#

Lightweight project file management skill. / 轻量化的项目文件管理技能。

---

First-Time Setup / 首次安装（自动初始化）#

EN: On first load, auto-scan existing folders and generate PROJECT-HISTORY.md! CN: 首次加载此技能时，自动扫描 workspace 现有文件夹，生成 PROJECT-HISTORY.md！

Auto-Scan Logic / 自动扫描逻辑#

text

EN:
Scan workspace/ root directory
    ↓
Find ./articles/, ./data-science/, etc.
    ↓
Filter system folders: .git, .openclaw, memory, skills, .learnings
    ↓
Create PROJECT-HISTORY.md entry for each real project folder
    ↓
Continue to normal workflow

CN:
扫描 workspace/ 根目录
    ↓
发现 ./articles/、./data-science/ 等文件夹
    ↓
过滤系统文件夹：.git、.openclaw、memory、skills、.learnings 等
    ↓
为每个真实项目文件夹创建 PROJECT-HISTORY.md 条目
    ↓
继续执行主流程

text

IF ./PROJECT-HISTORY.md does not exist:
    1. Scan all folders in workspace root directory
    2. Filter out system folders (.git, .openclaw, memory, skills, .learnings, etc.)
    3. For each real project folder, create an entry in PROJECT-HISTORY.md
    4. Set created = today, last_used = today
    5. Continue to Step 2
ELSE:
    Skip initialization, continue to Step 2

---

Core Features / 核心功能#

#English中文1Project History Search - Match keywords in PROJECT-HISTORY.md项目历史搜索 - 在 PROJECT-HISTORY.md 中匹配关键词2Smart Folder Direct Use - Directly use matched folder, auto update last_used智能文件夹推荐 - 直接使用匹配到的文件夹，自动更新 last_used3New Project Creation - Create new folders and record automatically新项目创建 - 自动创建新项目文件夹并记录4History Updates - Keep project history current历史记录更新 - 保持项目历史最新

---

Project History File / 项目历史文件#

Location / 位置: workspace/PROJECT-HISTORY.md

Format / 格式#

markdown

# Project History / 项目历史

## project-key
- name: Project Name / 项目名称
- path: ./project-folder/
- desc: Project description / 项目描述
- created: YYYY-MM-DD
- last_used: YYYY-MM-DD

Format Fields / 格式字段#

Field / 字段Description / 说明Example / 示例## keyUnique project identifier (level-2 heading) / 项目唯一标识footballnameProject name / 项目名称足球预测pathPath relative to workspace / 相对于workspace的路径./data_analyzer/descProject description (for keyword matching) / 项目描述足球数据分析createdCreation date / 创建时间2026-03-01last_usedLast used date / 最后使用时间2026-04-18

Path Resolution / 路径解析#

text

EN:
Current workspace: ~/.openclaw/workspace-[agentname]/
Project history: ~/.openclaw/workspace-[agentname]/PROJECT-HISTORY.md
New project folder: ~/.openclaw/workspace-[agentname]/[projectname]/

CN:
当前 workspace: ~/.openclaw/workspace-[agentname]/
项目历史文件: ~/.openclaw/workspace-[agentname]/PROJECT-HISTORY.md
新项目文件夹: ~/.openclaw/workspace-[agentname]/[projectname]/

---

Chinese Keyword Mapping / 中文关键词映射#

Chinese / 中文Matches / 匹配key足球 / footballfootball电池 / batterybattery射击 / shootingshooting预测 / predictionfootball验证 / verificationverify

---

Execution Flow / 执行流程（全自动）#

Step 1: Initialize (First Time Only) / 初始化（仅首次）#

text

EN:
IF ./PROJECT-HISTORY.md does not exist:
    1. Scan workspace root directory for all folders
    2. Filter system folders (.git, .openclaw, memory, skills, .learnings, etc.)
    3. Create initial entries for each real project
    4. Continue to Step 2
ELSE:
    Skip, continue to Step 2

CN:
如果 ./PROJECT-HISTORY.md 不存在：
    1. 扫描 workspace 根目录所有文件夹
    2. 过滤系统文件夹（.git、.openclaw、memory、skills、.learnings 等）
    3. 为每个真实项目创建初始条目
    4. 继续 Step 2
否则：
    跳过初始化，继续 Step 2

Step 2: Understand Task / 理解任务#

text

EN: Analyze user's task, extract 2-3 keywords, determine project type
CN: 分析用户任务，提取2-3个关键词，判断属于哪类项目

Step 3: Search & Match / 搜索匹配#

text

EN:
Read PROJECT-HISTORY.md
    ↓
Match rules (priority order):
    1. key exact match → Direct use
    2. name/desc contains keyword → Direct use
    3. Chinese keyword mapping hit → Direct use
    4. No match → Auto-create new project
    5. Multiple matches → Use first one, notify user

CN:
读取 PROJECT-HISTORY.md
    ↓
匹配规则（优先级顺序）：
    1. key 完全匹配 → 直接使用
    2. name/desc 包含关键词 → 直接使用
    3. 中文关键词映射命中 → 直接使用
    4. 无匹配 → 自动创建新项目
    5. 多个匹配 → 使用第一个，并向用户说明

Step 4: Execute & Record / 执行与记录#

text

EN:
【Existing Project】
    1. Create ./[project]/ folder (if not exists)
    2. Update PROJECT-HISTORY.md: last_used = today
    3. Reply: "Task organized to [project] (last_used: today)"

【New Project】
    1. Create ./[project-name]/ folder
       - If folder exists, auto-add suffix _1, _2, etc.
    2. Append new entry to PROJECT-HISTORY.md
    3. Reply: "Created new project [project-name], files will be organized here"

CN:
【已有项目】
    1. 创建 ./[project]/ 文件夹（如不存在）
    2. 更新 PROJECT-HISTORY.md：last_used = 今天日期
    3. 回复："已将此任务整理到 [项目名]（last_used: 今天）"

【新项目】
    1. 创建 ./[project-name]/ 文件夹
       - 如文件夹已存在，自动追加 _1, _2 后缀
    2. 在 PROJECT-HISTORY.md 追加新条目
    3. 回复："已创建新项目 [项目名]，文件将整理到此目录"

---

Decision Rules / 决策规则#

Project vs One-time Task / 项目 vs 一次性任务#

Type / 类型Example / 示例Handling / 处理方式Ongoing project / 持续项目足球预测系统 / Football predictionCreate independent folder / 创建独立文件夹Daily analysis / 日常分析每日预测、周报 / Daily predictionPut in related project folder / 放入相关项目文件夹One-time task / 一次性任务临时数据整理 / Temp data整理Put in project folder or tmp / 放入项目文件夹或tmp

Folder Naming / 文件夹命名规范#

text

EN:
- Use concise English/pinyin names
- Avoid Chinese folder names
- Example: myproject/, recommender/, dataprocessor/

CN:
- 使用简洁的英文/拼音名称
- 避免中文文件夹名
- 示例: myproject/, recommender/, dataprocessor/

---

Example Dialogues / 示例对话#

Case 1: Match Found → Direct Use / 匹配成功 → 直接使用#

User / 用户: "帮我分析今天足球数据" / "Analyze today's football data"

Agent / 智能体:

text

EN:
[Scan] ./PROJECT-HISTORY.md (init if not exists)
[Extract keyword] "足球" → football
[Match result] football -> ./data_analyzer/
  created: 2026-03-01, last_used: 2026-04-18

"Task organized to data_analyzer/ (last_used: today)"

CN:
[扫描] ./PROJECT-HISTORY.md（如不存在则初始化）
[提取关键词] "足球" → football
[匹配结果] football -> ./data_analyzer/
  created: 2026-03-01, last_used: 2026-04-18

"已将此任务整理到 data_analyzer/（last_used: 今天）"

Case 2: No Match → Auto Create / 无匹配 → 自动创建#

User / 用户: "我要开发一个新的推荐算法" / "I want to develop a new recommendation algorithm"

Agent / 智能体:

text

EN:
[Extract keyword] "推荐"
[Match result] No match

1. Create ./recommender/ folder
2. Append new entry to PROJECT-HISTORY.md
3. Reply: "Created new project recommender, files will be organized here"

CN:
[提取关键词] "推荐"
[匹配结果] 无匹配

1. 创建 ./recommender/ 文件夹
2. 在 PROJECT-HISTORY.md 追加新条目
3. 回复："已创建新项目 recommender，文件将整理到此目录"

Case 3: Multiple Matches → Use First / 多个匹配 → 使用第一个#

User / 用户: "做一下射击项目的数据分析" / "Do data analysis for the shooting project"

Agent / 智能体:

text

EN:
[Extract keyword] "射击" → shooting
[Match result] Multiple matches: ./shooting/, ./shooting_v2/
[Decision] Use first one: ./shooting/

"Multiple matches found, using ./shooting/ (last_used: today)"

CN:
[提取关键词] "射击" → shooting
[匹配结果] 多个匹配：./shooting/, ./shooting_v2/
[决策] 使用第一个：./shooting/

"发现多个匹配项目，已使用 ./shooting/（last_used: 今天）"

---

Test Cases / 测试案例#

✅ Test 1: Match Existing / 匹配已有项目#

text

EN:
Input: "分析今天足球数据" / "Analyze today's football data"
Expected: Match football → Use ./data_analyzer/, update last_used

CN:
输入: "分析今天足球数据"
预期: 匹配 football → 使用 ./data_analyzer/，更新 last_used

✅ Test 2: Auto Create New / 自动创建新项目#

text

EN:
Input: "开发一个天气预测系统" / "Develop a weather prediction system"
Expected: No match → Auto-create ./weather-prediction/ folder

CN:
输入: "开发一个天气预测系统"
预期: 无匹配 → 自动创建 ./weather-prediction/ 文件夹

✅ Test 3: First-Time Auto-Scan / 首次自动扫描#

text

EN:
Scenario: Workspace has ./articles/, ./data-science/, memory/, .git/
Expected:
  - Filter .git, memory, skills (system folders)
  - Create entries for articles, data-science in PROJECT-HISTORY.md
  - created = today, last_used = today

CN:
场景: Workspace 有 ./articles/, ./data-science/, memory/, .git/
预期:
  - 过滤 .git, memory, skills 等系统文件夹
  - 为 articles, data-science 创建 PROJECT-HISTORY.md 条目
  - created = 今天日期，last_used = 今天日期

---

Cross-Agent Compatibility / 跨Agent兼容性#

text

EN:
Agent A workspace:
  ~/.openclaw/workspace-data_analyzer/
  ├── PROJECT-HISTORY.md
  └── data_analyzer/

Agent B workspace:
  ~/.openclaw/workspace-mlbots/
  ├── PROJECT-HISTORY.md
  └── baseball_project/

Path ./PROJECT-HISTORY.md automatically resolves to the corresponding workspace.

CN:
Agent A workspace:
  ~/.openclaw/workspace-data_analyzer/
  ├── PROJECT-HISTORY.md
  └── data_analyzer/

Agent B workspace:
  ~/.openclaw/workspace-mlbots/
  ├── PROJECT-HISTORY.md
  └── baseball_project/

路径 ./PROJECT-HISTORY.md 自动解析到对应的 workspace。

---

Permission Notes / 权限说明#

Permission / 权限Scope / 范围Read / 读取PROJECT-HISTORY.md in current workspaceWrite / 写入Create new folders, update history in current workspaceNo access / 不访问System files, credentials, other agents' files

---

Notes / 注意事项#

#English中文1Be direct: If match found, use it directly and notify user直接处理: 如匹配到项目，直接使用并告知用户2Auto-create: If no match, create new folder without asking自动创建: 无匹配时直接创建新文件夹，无需询问3Update always: Always update last_used when using existing project始终更新: 使用已有项目时必须更新 last_used4Record all: Must update PROJECT-HISTORY.md for new projects记录新项目: 创建新项目时必须更新 PROJECT-HISTORY.md5Bilingual: Support both Chinese and English keyword matching双语兼容: 同时支持中文关键词和英文key直接匹配6Workspace isolation: Different agents have independent historiesworkspace隔离: 不同Agent的项目历史互相独立7System folders: Skip .git, .openclaw, memory, skills, .learnings, .env, .DS_Store系统文件夹: 跳过 .git, .openclaw, memory, skills 等8Monthly archive: Mark projects with last_used > 3 months as archived定期归档: 每月检查，将 last_used > 3个月的项目标记为归档