文件夹索引整理 hero-jianghaojie/folder-index

folder-index

给任意文件夹做「分类整理 + 可重建索引」的智能体技能 —— 让其他 AI 和代码随时能查到东西在哪，而不是靠翻目录。

核心主张：整理 ≠ 搬迁。当一个工作区有几十万文件、且工程文件里写死了大量绝对路径时，物理移动风险高、收益低；你真正需要的是「找得到」+「别人不会忘位置」。所以本技能先做可重建索引，物理移动只在引用闸门零命中、且用户确认后、带 undo manifest 才进行。

它解决什么问题

- 工作区越滚越大（下载、实验草稿、克隆的仓库、缓存……），自己都记不住哪个目录是干什么的；
- 换了模型/新开会话，AI 一进来就"失忆"：不知道入口在哪、不知道哪些能动；
- 想"整理一下"，又怕移错文件把工程弄坏（工程脚本、IDE 配置、虚拟环境、项目记忆文件里全是绝对路径）。

30 秒上手

1) 首次：扫描顶层条目，生成注解层模板（不改动任何文件）
python scripts/index_gen.py --root /path/to/workspace --init

2) 打开 _index.meta.json，给每个条目补 category / purpose / move_policy （工作区根下的点目录会自动标成「配置 / 不要移动」）

3) 生成索引（人读 md + 机器读 json + 扁平 tsv）
python scripts/index_gen.py --root /path/to/workspace

4) 日常三招
python scripts/index_gen.py --root <ws> --find ADS # 搜索引
python scripts/index_gen.py --root <ws> --refs autoADS # 移动前的引用闸门
python scripts/index_gen.py --root <ws> --fast # 秒级刷新结构

产出

| 文件 | 读者 | 内容 |
| _INDEX.md | 人 | 怎么用 → 🚨安全铁律 → 按用途分组的条目表 → 活跃入口 → 归档候选 |
| _index.json | 机器（AI/脚本） | 每条含 category / purpose / move_policy / refs / keywords / size / files / mtime |
| _index.tsv | grep / awk | 扁平表，一行一条 |
| _index.meta.json | 人维护 | 注解层：类别、用途、移动策略、引用者、关键词 |

生成物随目录变化重跑即可；人工判断只写在 _index.meta.json 里，不会被覆盖。

分类与移动策略

category：project_active 活跃工程 · project_idle 项目（较旧） · knowledge 知识/资料 · assets 素材/第三方仓库 · environment 环境（可重建） · tooling 工具 · scratch 草稿/临时/缓存 · misc 杂项 · config 配置目录（勿动） · entry 顶层入口文件

move_policy：keep 🛑 不要移动 · ask ⚠️ 移动前先查引用 · archive-ok 📦 可归档

设计要点（都是踩出来的）

1. 引用判定必须按绝对路径变体搜，不能按子串：pa / review / skill / tests 这类常见词会假命中几百次。
2. 必须排除索引文件自身：索引天然包含所有条目名，否则 100% 假命中。
3. 闸门要覆盖非代码位置：DSH/代理配置、技能目录、项目记忆文件 —— 真引用常藏在那里。
4. 点目录默认「配置 / 不要移动」：工作区根下的 .xxx 基本都是各工具配置，不该出现在"待整理"里。
5. 只读扫描：生成器只写自己的三份产物，绝不移动/删除用户文件。

安装

任选其一：

A. 作为技能放到你的 agent 技能目录（Claude Code / DSH 等）
cp -r folder-index ~/.agents/skills/folder-index

B. 只在某个工作区里用脚本
cp scripts/index_gen.py /path/to/workspace/

技能入口是 SKILL.md；模型看到"整理文件夹 / 做个索引 / 目录太乱"之类的请求时会按里面的 5 步流程执行。

实测

一次真实部署：54 个顶层条目 / 613,865 个文件 / 17.66 GB

| 动作 | 耗时 |
| 全量重建 | 141 s |
| --fast 结构刷新 | < 1 s |
| --refs（扫 1177 个参考文件） | ~3 s |

folder-index is an agent skill that organizes a folder by building a regenerable index instead of moving files. Scan → annotate (_index.meta.json) → generate (_INDEX.md human-readable, _index.json machine-readable, _index.tsv flat) → gate any move with --refs (absolute-path-aware reference scan) → move only with an undo manifest, after user confirmation. See SKILL.md for the workflow, the four iron rules and the anti-patterns.

License

MIT —— 见 LICENSE。