file-tidy

name	file-tidy
description	文件系统整理师——结构感知归位，帮跑错地方的文件回到该去的子目录。支持干跑模式和自定义 YAML 辅助配置。独立使用或被 weaver-自我迭代 调用。

文件系统整理师 — File Tidy v2

不是"把所有 .py 塞进 scripts/"，而是学习项目已有的目录结构，把跑错地方的文件送回该去的地方。像一位细心的室友——先看家里怎么摆的，再帮你把跑偏的东西归位。

触发词

整理文件 / 整理目录 / 文件归类 / tidy / cleanup

何时使用

• 项目根目录散落文件，明显属于某个已存在的子目录
• 想把临时文件、备份文件找出来
• weaver 全局整理时自动调用

核心原则

1. 结构感知优先 — 先学习项目已有的目录结构，再判断归属
2. 高置信度才动 — 不确定的就放着，"不确定"比"猜错了"好一万倍
3. 不创造新目录 — 只归到已有目录，不新建
4. 不拆散项目 — 同一主题的文件保持在一起

工作流程

第一步：确定目标目录和模式

1. 用户指定目录 → 用指定目录；否则用当前工作目录
2. 默认干跑模式。用户说"执行"/"确认"/"动手"才进入执行模式
3. 检查目标目录下是否存在 .tidy-rules.yaml。存在则加载（辅助信息），不存在则纯靠结构感知

第二步：建地图 — 学习项目目录结构

使用 PowerShell 扫描目标目录下的直接子目录，为每个目录建立"指纹"。

构造 <safe_zone_pattern>：

• 如果存在 .tidy-rules.yaml 且含 safe_zones：将每个 zone 的 glob 转为 regex（* → .*，? → .，其余字符用 [regex]::Escape() 转义），用 | 拼接
• 如果没有 .tidy-rules.yaml 或 safe_zones 为空：使用默认安全模式 ^(\.|node_modules)

# 扫描一级子目录（排除安全区）
Get-ChildItem -Path <dir> -Directory -Depth 0 |
    Where-Object { $_.Name -notmatch '<safe_zone_pattern>' } |
    ForEach-Object {
        $dir = $_.FullName
        $files = Get-ChildItem -Path $dir -File -Depth 0 | Select-Object -First 20
        [PSCustomObject]@{
            Name       = $_.Name
            Path       = $dir
            SampleSize = @($files).Count  # 采样数量（最多 20），不是目录总文件数。如需总文件数做比例计算，单独 Get-ChildItem 计数
            Extensions = ($files | Group-Object Extension | Sort-Object Count -Desc | Select-Object -First 3).Name -join ','
            Prefixes   = ($files | ForEach-Object { ($_.BaseName -split '[-_]')[0] } | Group-Object | Sort-Object Count -Desc | Select-Object -First 3).Name -join ','
        }
    }

指纹字段含义：

• Name：目录名（提取中英文关键词作为语义标签）
• Extensions：目录内最常见的文件扩展名（如 .py,.csv,.md）
• Prefixes：目录内文件最常用的前缀/词根（如 movie,elm,weather）

同时读取 .tidy-rules.yaml（如果存在）获取：

• directories：目录别名（帮 AI 理解目录含义）
• safe_zones：绝对不碰的目录/文件模式（支持通配符 *）
• keep_at_root：必须留在根目录的文件
• junk：临时/垃圾文件清理规则

第三步：清理层 — 识别垃圾文件

用 .tidy-rules.yaml 的 junk 规则扫描目标目录，标记建议删除的文件。

注意：

• 清理层在归位层之前运行——垃圾文件先过滤掉，不参与归位判断
• 清理结果标记为"建议删除"，永远不自动执行删除
• 无 junk 配置时跳过此层

第四步：归位层 — 对游离文件逐项打分

对目标目录下的所有直接文件（不含子目录内的文件），逐一计算它属于每个已有子目录的分数。

评分维度

维度一：文件名 → 目录名匹配（权重 40%）

• 文件名和目录名共享相同关键词（子串双向匹配）：40 分 匹配粒度：去除分隔符（-、_、.、/）后的独立词段。如 movie_train 拆为 [movie, train]，outputs/movie/ 提取 [outputs, movie]。共享词段越多分越高：2+个共享词段 = 40 分，1 个 = 30 分，无共享 = 看别名
• 文件名包含目录名关键词或反之：30 分 （如 movie_train.py → 目录 outputs/movie/）
• 通过 .tidy-rules.yaml directories 别名匹配：25 分 （如文件名含"前端"关键词 → frontend-design/ 目录）
• 无关键词重合：0-10 分

维度二：同源文件聚类（权重 30%）

以下子项取最高分，不累加。即同时满足多个条件时，只取最高的一项得分。

• 目标目录内已有同前缀文件（前缀匹配）：30 分 （如 movie_report.md → 目录已有 movie_download.py）
• 文件扩展名在目标目录占主导（≥50%）：20 分
• 文件扩展名在目标目录常见（25-49%）：10 分
• 无明显同源关系：0 分

维度三：代码引用关系（权重 20%，仅代码文件）

• 文件内容中 import/require/reference 指向了目标目录内的模块：20 分
• 目标目录内文件的 import 指向了这个文件：15 分
• 非代码文件（.md, .csv, .json, .yaml 等）：跳过此维度，总分按 80 分制折算

维度四：语义兜底（权重 10%，仅当前三项总分 < 30 时触发）

仅对文本类文件（.py, .md, .txt, .js, .ts, .java, .json, .yaml, .xml, .csv, .html, .css 等）触发语义兜底。二进制文件（.pdf, .png, .zip, .exe, .dll 等）直接跳过此维度。

• 读取文件内容摘要（前 30 行）
• 与各目录名 + directories 别名做语义匹配
• 有明确语义关联：10 分；模糊关联：5 分；无关联：0 分
• 重要：如果超过 2 个文件需要语义兜底，直接停止此维度，标记这些文件为"无法判断"。熔断后第 3 个及之后的非代码文件直接按"无法判断"处理，归入"未归类"。

综合评分公式

• 代码文件：维度一(0-40) + 维度二(0-30) + 维度三(0-20) + 维度四(0-10) = 总分(0-100)
• 非代码文件：维度一(0-40) + 维度二(0-30) + 维度四(0-10)，按 (总分 / 80) * 100 折算

安全过滤（打分后应用）

以下条件任一满足，则不加入移动建议：

• 文件在 keep_at_root 列表中
• 文件是隐藏文件（. 开头）
• 文件名/路径匹配 safe_zones 模式
• 目标路径已存在同名文件（冲突）

多目录等分时的仲裁策略

同分平局：当文件对多个目标目录得分相同且均为最高时，选择文件数更少的目录（避免把零散文件塞进已经很大的目录）。如果文件数也相同，选目录名与文件名关键词匹配度更高的。

第五步：展示计划

按四档输出：

整理计划 — <目标目录绝对路径>

▌ 建议删除（N 项）
  <文件>                    → [删除] <reason>

▌ 建议移动 — 高置信度（N 项）
  <源文件路径>              → <目标路径>  (XX分)

▌ 建议移动 — 请确认（N 项）
  <源文件路径>              → <目标路径>  (XX分  ⚠ <低分原因>)

▌ 未归类（N 项）
  <文件>                    (<原因>)

已扫描 XX 个文件，建议删除 X 项，建议移动 X 项（其中 X 项需确认），未归类 X 项。

执行：整理文件 --confirm（执行全部建议移动 + 建议删除） 只看高置信度：整理文件 --safe（只执行高置信度移动 + 建议删除）

格式规则：

• 每个文件必须标注归属于哪个子目录
• "请确认"项必须说明低分原因（如"可能与 scripts/ 或 outputs/movie/ 均有关"）
• 未归类项必须说明不动它的原因
• 建议删除不自动执行，需用户确认
• 如果所有文件都在合适的位置，输出"目录已整洁，无需整理"

置信度阈值

总分	动作
≥ 70	高置信度 — 直接建议移动
40-69	中置信度 — 建议移动，标注"请确认"
< 40	不处理，列入"未归类"

第六步：用户确认

展示计划后询问：

"执行整理（全部移动+删除）/ 安全模式（只动高置信度项）/ 只看归类（只移动高置信度，不删）/ 取消？"

• 执行整理：执行所有建议移动 + 所有建议删除
• 安全模式：只执行高置信度移动 + 只执行建议删除，中置信度不动
• 只看归类：只执行高置信度移动，删除项不动
• 取消：不执行任何操作

第七步：执行

# 检查目标目录是否存在（不存在则跳过，绝不创建新目录）
if (-not (Test-Path "<target>")) {
    Write-Output "ERROR 目标目录 <target> 不存在，跳过"
    continue
}

# 移动文件（不覆盖已存在的同名文件）
if (-not (Test-Path "<target>/<filename>")) {
    Move-Item -Path "<source>" -Destination "<target>/<filename>"
    Write-Output "OK  <source>  →  <target>/<filename>"
} else {
    Write-Output "SKIP  <source>  →  <target>/<filename>  已存在"
}

执行完成后输出摘要：

整理完成 — 移动 X 项，跳过 Y 项（冲突），删除 Z 项，未处理 W 项

被 weaver 调用时

weaver 在全局整理时调用 file-tidy：

1. weaver 以干跑模式启动 file-tidy
2. 结果嵌入 weaver 变更摘要的"文件系统整理"段落
3. 用户在 weaver 摘要中确认后，weaver 再次调用 file-tidy 执行

命令选项

选项	行为
（默认，无参数）	干跑模式，只展示计划
--confirm	执行全部建议移动 + 建议删除
--safe	只执行高置信度移动 + 建议删除
--classify	只移动高置信度，不执行删除（对应"只看归类"模式）
--dry-run	只出报告不动手

安全规则

• 绝不自动删除文件 — 删除标记需用户二次确认
• 绝不覆盖已有文件 — 目标已有同名文件时跳过并报告
• 绝不创建新目录 — 只使用项目已有的子目录
• 绝不碰隐藏文件 — . 开头默认跳过
• 不碰安全区目录 — 根据 safe_zones 配置排除
• 不确定就放着 — 低置信度文件不动，不猜测

注意事项

• 本 skill 执行时，必须实际运行 PowerShell 命令扫描目录，不能凭空猜测文件位置
• 评分必须对每个文件、每个目标目录逐项计算，不能跳步
• 目录指纹中的"前缀"独立于扩展名——movie_train.py 和 movie_report.md 共享前缀 movie_
• .tidy-rules.yaml 是辅助而非驱动——没有它也应该能完成归位判断