smart-workspace（智能工作空间）

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 / 自动扫描逻辑

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 条目
    ↓
继续执行主流程

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 / 核心功能

Project History File / 项目历史文件

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

Format / 格式

# Project History / 项目历史

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

Format Fields / 格式字段

Path Resolution / 路径解析

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 / 中文关键词映射

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

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

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 / 理解任务

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

Step 3: Search & Match / 搜索匹配

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 / 执行与记录

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 一次性任务

Folder Naming / 文件夹命名规范

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 / 智能体:

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 / 智能体:

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 / 智能体:

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 / 匹配已有项目

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 / 自动创建新项目

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

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

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

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兼容性

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 / 权限说明

Notes / 注意事项