文件存放分包（按用途落盘）

制作物落盘

先读 .harness/surfaces.json（正式面 ↔ 隔离根）。没有则从 ~/.cursor/harness/surfaces.default.json 拷一份再改路径。表/代码/引擎/资产都走同一套对照，不要另开杂目录。

改某份正式物时，在它所在目录只建一个工作夹，不把草稿丢到业务根或 .harness/artifacts：

<所在目录>/
  <正式名>.xlsx                                      # 稳定名，当前正式
  沙箱/
    <正式名>.sandbox-YYYYMMDD-HHMMSS.xlsx            # 本轮副本，也是快照
    <正式名>.sandbox-YYYYMMDD-HHMMSS.xlsx.changes.json

表写入走 xlsx_sandbox_clone，默认就是正式表同级 沙箱/。不要再旁开版本夹。沙箱/ 不进 git：仓根必须有 **/沙箱/，见 write-isolation。

业务根顶层只留业务大类。便携工具链、引擎试验和对照摘录都按 .harness/surfaces.json 的隔离根放，不进业务根杂目录。

何时用

• 工作区里找不到文件，或目录分层与用途对不上
• 导入/导出后资源散落在根目录或桌面
• 开新工作区、新模块、新活动包，需要先定目录再动手
• 整理存量乱盘：要搬家清单，不能静默乱移导致断引用

不替代：export-naming-gate / naming-consistency-check（管名字与改名联动）；本技能管放哪一层目录、怎么分包。

公开惯例（对照用，落盘时改成项目词）

综合引擎官方与成熟样式指南的共识（按用途/功能分包，而不是顶层按「网格/贴图/材质」堆类型夹）：

1. 项目命名空间顶层：自研内容进一个项目根夹（如引擎内容根下的 ProjectName/），与第三方包、商店包分开，方便升级与迁移。
2. 优先按用途/功能/对象分包：角色、武器、场景区块、UI、关卡等同对象相关文件放一起；类型夹（Meshes/Textures）只作最底层或干脆用过滤，不作高层主轴。
3. 共享地基单独夹：全局 UI、母材质库、通用音频等进 Core / Shared / MaterialLibrary 一类，避免复制粘贴分叉。
4. 草稿与个人沙盒隔离：_Dev / Developers/<名> 类目录，不进正式构建/发包集合。
5. 文件夹名：PascalCase 或项目统一大小写；无空格、无奇怪符号；空目录及时删。
6. 多仓业务根（客户端 / 服务端 / 配置表）：根上只留业务大类 + 运行时标记；架构薄脚本不进业务仓；表、代码、美术源、导出物分区，原始源与导出产物勿混同一叶目录。

写法上不绑死某一家引擎目录名；定档时按业务根真实路径映射下列模板。

怎么做

1. 锁定根与范围

1. 确认任务根（含 .harness 的业务根）与要整理的子树（客户端内容根、表仓、工具仓等）。
2. 读现有约定：先对齐 .harness/surfaces.json，再看 docs 或布局备忘，不另起炉灶。
3. 问清本轮范围：只规划新树 / 只扫违规 / 要执行搬家。缺「不可动路径」先问用户。
4. 对照物：业务根路径列表、.harness/state.json、现有顶层目录截图或 dir 列表。
5. 不合格：根都没定就开搬家 → 停。
6. 本步产物：范围卡（根、子树、是否允许改引用）。

2. 选定分包主轴并画出目标树

1. 主轴默认 用途/功能（角色、系统、关卡、活动期号）；仅在叶子需要时再按类型细分。
2. 画出目标树（3～5 层内）：ProjectNs/、Core|Shared/、各功能夹、ThirdParty|Plugins/、_Dev|Scratch/。
3. 多仓时分别画：表仓键目录、客户端内容根、服务端代码根；跨仓只写「指针」不写复制全文。
4. 每条边写「放什么 / 不放什么」一句，避免又变成杂物抽屉。
5. 不合格：顶层全是 Meshes/Textures/Materials 且无功能夹 → 改主轴。
6. 本步产物：目标树 markdown（可进 .harness/artifacts/<工作项>/file-layout-target.md）。

3. 扫描现状 → 差异表

1. 列出当前顶层与二级目录；标：合规 / 错位 / 第三方混入自研 / 草稿进生产 / 空目录。
2. 对错位文件给「建议目标路径」；同名冲突单独标红。
3. 预估断引用面：场景/预制/表键/代码路径字符串（只列类型，细改名交命名技能）。
4. 对照物：差异表（源路径 → 目标路径 → 风险）。
5. 不合格：差异表无目标路径或无风险列 → 补全。
6. 本步产物：file-layout-diff.md 或表。

4. 执行搬家（获准后）

1. 用户批准差异表后再动；先干跑清单（只打印将发生的移动）。
2. 小步搬：先第三方隔离与草稿迁出，再功能分包；每步可回滚（版本库提交或打包备份）。
3. 搬完跑引用修复：能自动则自动，否则列「待修引用」交对应职种；命名违规挂 export-naming-gate / naming-consistency-check。
4. 更新布局备忘（短文，路径表即可），登记产物。
5. 不合格：未获准就批量移动，或搬完无引用检查 → 回本步或回滚。
6. 本步产物：实际移动日志 + 布局备忘路径。

5. 固化模板（可选）

1. 把本仓目标树收成「新模块脚手架」说明或脚本（只建目录，不灌业务文件）。
2. 在定档菜单可点名本技能；大整理进里程碑时挂制作人视野。
3. 不合格：模板与真实树不一致 → 改模板。
4. 本步产物：脚手架说明路径。

完成检查

• 目标树按用途主轴，且自研 / 第三方 / 草稿分离
• 差异表含源→目标→风险；搬家经批准
• 搬后有引用检查或待修清单；布局备忘已落盘可打开
• 开放问题已列给用户或已关闭

失败回哪一步

工具锚点

目录列表 / 资源浏览器过滤 · 版本库 diff 与移动检测 · 表键与代码路径检索 · .harness/artifacts/<工作项>/ 布局备忘 · 干跑搬家清单

示例目标树（映射时替换项目名）

<业务根>/
  .harness/state.json
  .harness/
  <ClientContentNs>/          # 引擎内容根下的项目命名空间
    Core/                     # 共享地基
    Characters/
    Environment/
    UI/
    Maps/                     # 或 Levels
  ThirdParty/                 # 或 Plugins：只升不改
  _Dev/                       # 个人草稿，不进发包
  data_tables/                # 若表在同根：源表与导出分区
  server/                     # 若同根：代码与本地数据分离

叶子是否再分 Meshes 等：仅当集合极大或管线强制；否则优先前缀命名 + 过滤器。

工具锚

1. 包体落 ${HARNESS_APPS} 或工作区约定目录。
2. 大文件检索：everything-search。
3. 完成信号：目录树与清单一致。