Workspace Tidy — AI skill for Claude Code

workspace-tidy · AI 编程工作区自动整理技能

把"项目工作区每周整理"沉淀成一个 **AI Agent 技能**：散落文件自动归位、临时垃圾清理、 目录联接校验，以及在 [ZCode](https://zcode.ai) 中把侧边栏未分组任务自动归组——让工作区 和任务列表始终保持"一眼能找到"的状态。

**跨工具兼容**：不依赖任何专有 API。ZCode、Codex、Claude Code 等**任何能读文件、 执行命令的 AI 编程工具**都可以执行本技能；在非 ZCode 环境里，任务分组模块会自动跳过， 文件整理功能完全一致。

它解决什么问题

AI 编程工具用久了，工作区常见两类混乱：

• 文件层面：根目录堆满临时脚本、截图、备份，找不到哪个文件属于哪个项目；
• 会话层面（ZCode）：侧边栏几十个历史会话平铺，新会话不知道该归到哪个项目。

本技能用一份 `tidy.config.json` 描述你的分类体系（目录 + 关键词 + 白名单 + 联接 + 分组）， Agent 每周按配置巡检一次，配合自动化调度即可完全无人值守。

快速开始

方式一：作为 ZCode / Claude Code 技能安装

# ZCode
git clone https://github.com/<你的用户名>/workspace-tidy.git
mkdir -p ~/.zcode/skills && cp -r workspace-tidy ~/.zcode/skills/workspace-tidy

# Claude Code 同理
mkdir -p ~/.claude/skills && cp -r workspace-tidy ~/.claude/skills/workspace-tidy

然后对 Agent 说："按 workspace-tidy 技能整理当前工作区"。

方式二：Codex / 其他 Agent 直接使用

把本仓库放入工作区，对 Agent 说：

读 workspace-tidy/SKILL.md，按它的流程和铁律整理当前工作区。

（仓库内的 [AGENTS.md](AGENTS.md) 是等价入口，Codex 会自动读取。）

配置你的分类体系

cp config/tidy.config.example.json tidy.config.json   # 放到你的工作区根目录

编辑 `tidy.config.json`：

字段	说明
categories	分类目录 + 关键词（大小写不敏感，匹配文件名/会话文本），命中即归位
junk_patterns	垃圾文件通配模式（默认含 nul、*$*.png、*.tmp 等）
protected	白名单文件，永不移动
min_age_hours	最近 N 小时内修改的文件不动（默认 72，保护进行中的工作）
archive_dir	无规则匹配/拿不准的文件的归档目录
junctions	需要保持存活的目录联接（junction/symlink），失效时打印重建命令
zcode.groups	ZCode 侧边栏分组：id / 中文标题 / 颜色 / 关键词，overrides 按任务 id 前缀强制归组

脚本用法

python scripts/tidy_core.py --config tidy.config.json --dry-run   # 默认，只打印计划
python scripts/tidy_core.py --config tidy.config.json --apply     # 实际执行（写操作清单到 logs/）
python scripts/zcode_task_groups.py --config tidy.config.json --dry-run   # ZCode 任务归组
python scripts/zcode_task_groups.py --config tidy.config.json --apply

两个脚本只用 Python 3 标准库，Windows / macOS / Linux 通用。

配合定时自动化（以 ZCode 为例）

创建一条每周定时自动化（如"每周五 21:00"），提示词模板：

对当前工作区执行每周整理巡检：按 workspace