项目文件自动收纳

skill 名：project-fold 版本：v0.2.0-candidate 中文名：项目文件自动收纳 定位：给 Vibe Builder 的项目文件归位与升级判断 skill

第一性原理：升级。

默认用最小可用结构；只有当现有结构装不下真实复杂度时，才升级目录形态。目录服务做成，不服务洁癖。

目录语言与中英映射

开始扫描前先确定本次项目根使用 zh 还是 en：

1. 作为 mishu 子 Skill 使用时，先按 MISHUHOME（若已设置）或 ~/.mishu 解析 store 根，再读取 SELF.md 的 folderlanguage。
2. 独立使用且语言未知时，先问用户用中文目录还是英文目录；中文目录和双语映射通常会多消耗一点 token。
3. 同一个 Projects 根只用一套实际目录名，不能中英混建。正文里的英文目录名是稳定的 schema ID；真正执行时按所选语言映射。
4. 中文模式或语言迁移时，执行任何创建、改名或移动之前，必须读取并遵守 [references/folder-names.md](references/folder-names.md)：先写完整映射文件，再把本轮映射快照写进搬运日志。
5. 机器契约文件 NOW.md、HANDOFF.md、SKILL.md 不翻译，避免跨 Agent 发现失败。

根目录规则

当 project-fold 由 mishu 调用时，defaultprojectsroot 只是新项目和未归属资料的默认落点。已有项目即使位于其他位置，也先在原地只读盘点；不得因为设置了默认根目录就搬迁。只有用户确认集中整理，并看过 move plan 后，才执行可逆移动。

Projects 第一层只允许三类：

Projects/
  <Project>/
  _Project-Inbox/
  _Archive/

<Project> 是一个可持续推进、复盘、归档的开发目标。不要让散文件、下载名、临时 demo、单个构建包、过程文档或旧仓库副本占据第一层。

归档语义只有两层，名称不重复：Projects 根的 Archive/ 只接收整个退役项目容器；项目内部旧版本、旧 demo 和历史副本只进入 90History/。

非开发目标不要留在 Projects 第一层。素材、参考图、字体、截图等去全局 Assets 或项目 30Assets/ / 70References/；不确定就进 _Project-Inbox/。

升级阶梯

L0 Inbox

未判断归属的 AI 生成文件或用户手动导入文件先进入：

_Project-Inbox/

不要让用户先想分类。Agent 后续二次分类。

Inbox 边界：

_Project-Inbox/      = 不知道属于哪个项目
<Project>/_Inbox/    = 知道属于这个项目，但不知道放哪个意图目录
<ProjectFamily>/_Inbox/ = 知道属于这个项目族，但不知道属于共享级还是子项目级

L1 普通项目

默认形态。一个目标，一个主要开发对象。

最小结构：

<Project>/
  00_Context/
  10_Source/
  20_Docs/
  90_History/

按需生长（不预建全套，按“文件意图判断表”长出真实需要的目录）：

30_Assets/
40_Builds/
50_Data/
60_Run-Release/
70_References/

清理任务才加：

99_Delete-Review/

当同一项目内出现多份源码、多类素材、构建产物、数据、运行/发布流程时，不新建项目、不升级层级，只补对应目录。这仍是 L1，只是长胖了。

L2 项目族

当一个目标下面出现 2 个以上会独立演化的输出形态，才升级为项目族。

项目族比普通项目多两个核心判断点：

<ProjectFamily>/
  00_Context/
  10_Shared/
  20_Subprojects/
  _Inbox/
  90_History/

注意编号语义变了：项目族用 10Shared/20Subprojects 替代 L1 的 10Source/20Docs，同一层不并存。子项目内部才重新回到 L1 的 10Source/20Docs 逻辑。

按需增加普通项目目录，如 30Assets/、40Builds/、50Data/、60Run-Release/。

铁律：

• 共享的放 10_Shared/
• 独立演化的放 20_Subprojects/
• 不确定的放 _Inbox/
• 子项目内部继续按普通项目逻辑整理

示例：一个 vibe builder 用户的同一目标下同时出现 Web App、Browser Extension、Landing Site、Skill Pack，才升级为项目族。只有一个 Web demo 时保持普通项目。

文件意图判断表

先按层级选对 schema：L1 普通项目用 10Source/20Docs；L2 项目族根用 10Shared/20Subprojects。两套不并存。下表「层级」列标明各目录适用哪一层。

备份与版本泛滥处理

一堆同源文件（版本号、日期、"备份/backup/副本/copy/bak/old"、"xxx前备份"）是整理里最占地方、最不敢删的东西。规则：识别一族 → 留最新 → 旧的收进待删除区 → 永不自动删 → 用户复核。

识别「同源族」：主名相同、只差版本或备注后缀。例：

CAM需求清单_v2.7.xlsx
CAM需求清单_v2.7_修改前备份.xlsx
CAM需求清单_v2.7_版本号统一前备份.xlsx
CAM需求清单_v2.8.xlsx
CAM需求清单_v2.9.xlsx      <- 最新，留在正常目录

处理：

• 保留活口：版本号最高 / 时间最新的一份留在正常目录；无法判断谁最新时，全族留 Inbox 并说明。
• 旧版收待删除区：其余进 99Delete-Review/<族名>/（或用户项目已有的备份目录，如 09备份/——沿用用户现有约定，不新造）。
• 只归置不删除：待删除区是「候选」，删不删由用户在复核后决定；skill 自己绝不删。
• 运行期垃圾单列：.sqlite-wal/-shm、pycache/、-recovery-backups/、Thumbs.db、.DSStore 等是工具运行残留，不是资料，进 99Delete-Review/_runtime/ 或列为待删除复核候选；不要当项目文件归档，Skill 自己不删除。
• 待删除区的每一次归置照样写进搬运日志，能还原。

AI 生成与手动导入的二次分类

不要只按文件后缀分类。先判断归属层级，再判断文件意图。

顺序：

1. 先剥离备份/版本族（见「备份与版本泛滥处理」）：留最新，旧的入待删除区，再对剩下的判归属。
2. 属于哪个项目或项目族？
3. 是项目级、共享级，还是子项目级？
4. 是 Context、Source、Docs、Assets、Builds、Data、Run-Release、References、History、Delete-Review 哪一种？
5. 置信度够不够？
6. 不够就留 Inbox，不硬搬。

置信度：

High   -> 可建议直接移动
Medium -> 列入 move plan，等用户确认
Low    -> 留在 Inbox，并说明缺什么信息

示例：

index.html

可能是 10Source/、40Builds/、90History/ 或 Project-Inbox/；看相邻文件、引用关系、文件名和用户意图再定。

logo.png

可能是项目 30Assets/、项目族 30Assets/、子项目 30Assets/ 或 70References/；不要只因后缀是 png 就移动。

Mini case：

导入文件：
  landing.html
  app-demo.mp4
  logo.png
  prompt.md
  old-v1.zip

判断：
  landing.html -> 10_Source 或 40_Builds，看是否还会继续编辑
  app-demo.mp4 -> 30_Assets
  logo.png     -> 30_Assets
  prompt.md    -> 00_Context 或 20_Docs，看是否定义项目行为
  old-v1.zip   -> 90_History

两种模式

起手先判断走哪种模式，别默认闷头整理。

• 方案模式（默认）：首次整理、或用户第一次接触这套框架时。先理解现状再写方案——只读扫描完、看懂文件之间的归属关系后，再落笔。方案要极简：只列真正要动的文件（移哪个→到哪、置信度、一句为什么），不堆砌不解释显而易见的项，让用户几眼扫完就能确认。确认后才执行。宁可多问一句，不要擅自搬动。
• 直接模式：满足以下任一条件才启用，跳过方案直接执行——

- 用户明示「现在马上整理 / 直接执行 / 不用给我看方案」； - 目标目录已经是这套结构（目录名可为映射表中的中文或英文；第一层只有项目容器、Inbox、Archive），说明用户在用这套框架，只是日常归位。 - 即便直接模式，High 置信度才真移动；Medium/Low 仍留 Inbox 并在日志里说明。

判断不了走哪种，就默认方案模式。

工作流程

1. 判断模式（见「两种模式」）：不确定或首次 → 方案模式。
2. 先与用户确认 Projects 根路径，记为 $PROJECTS_ROOT；不假设、不硬猜。
3. 只读扫描 $PROJECTS_ROOT 第一层和 Inbox。
4. 让用户确认项目名；不从仓库名硬推项目名。
5. 移动 Git 仓库前先跑 git status --short；有未提交内容时只按身份包裹，不合并、不删除。
6. 默认建普通项目（L1）容器。
7. 只有出现多个独立演化输出时，升级为项目族（L2）。
8. 散文件按“归属层级 + 文件意图 + 置信度”生成 move plan。
9. 执行移动：方案模式必须先给用户看 plan、确认后才移；直接模式跳过确认，但只移 High 置信度，Medium/Low 一律留 Inbox。
10. 项目内部历史副本进所选语言对应的 90History / 90历史；只有整个项目退役时，项目容器才进入 Projects 根的 Archive / 归档。不要删除。
11. 所有移动写入搬运日志（复原兜底）：每条记录 原路径 -> 新路径、时间、置信度，确保能逐条反向还原。没有用户指定输出目录时，英文模式放 $PROJECTSROOT/Project-Inbox/cleanup-log.md，中文模式放 $PROJECTSROOT/项目收件箱/搬运日志.md。格式示例：

## 2026-07-07 14:30 整理
- ./landing.html -> ./Tuck/10_Source/landing.html  [High]
- ./old-v1.zip   -> ./Tuck/90_History/old-v1.zip    [High]
- ./mystery.dat  留 _Project-Inbox（Low：无法判断归属）

1. 完成后验证：

find "$PROJECTS_ROOT" -maxdepth 1 -type f -not -name '.DS_Store' -not -name '.localized' -print
find "$PROJECTS_ROOT" -maxdepth 1 -mindepth 1 -not -name '.DS_Store' -not -name '.localized' -print

第一条应为空；第二条应只显示项目容器以及所选语言对应的 Inbox、Archive。

真实文件系统坑

• macOS 默认大小写不敏感：tuck 和 Tuck 视为同一路径。遇到只改大小写或同名容器包裹时，必须用临时名中转：tuck -> __tmptucksource -> Tuck/10_Source/local-workspace。
• .DS_Store 和 .localized 是系统噪音；验证时忽略，只提示用户可清理或列入待删除复核，Skill 自己不删除。
• 普通目录不能因为名字像编号就留在 Projects 第一层；它必须是用户确认的开发目标，否则进 Archive/、Project-Inbox/ 或项目内 70_References/。
• 移动同名项目容器时，先把旧内容包进 90_History/<old-name>/，再建立新结构。

安全边界

• 每次整理必写搬运日志（原路径 -> 新路径），这是复原兜底；没有日志的移动等于不可逆，不允许。
• 中文模式或语言迁移时，映射文件与日志中的映射快照都写好之后才能移动；映射不完整就停手。
• 不删除。
• 不自动清 node_modules、.next、.build、模型、venv。
• 不移动系统目录、隐藏配置目录、bin。
• 不合并 Git 仓库；多个仓库先用 local-worktree/、github-repo/、public-repo/ 标身份。
• 不把证书、token、.env、私钥放进项目仓库；放敏感复核区。
• 不把应用本体塞进 /Applications，除非它是明确的 .app 安装包且用户要求。