文件拆分助手
05/1227 浏览开发心得
---
name: 文件拆分助手
updated: "2026-04-30 23:00:00"
version: "1.0"
description: |
文件拆分全流程助手。超标巡检→拆分建议→骨架生成→流程引导→验证→经验沉淀→经验吸收，
形成"发现→执行→沉淀→吸收"闭环。基于 16 次实战拆分经验（6fbf048→4c73008）。
MUST trigger when: (1) 拆分、split、模块拆分,
(2) 文件太大、太长、超800行、行数超标,
(3) 代码瘦身、文件瘦身,
(4) 巡检行数、检查行数,
(5) 用户问"哪些文件需要拆分"
---
# 文件拆分助手
> 发现→执行→沉淀→吸收 闭环。不只是文档，是可执行的工作流。
---
## 1. 触发条件
| 触发词 | 激活功能 |
|--------|---------|
| 拆分、split、模块拆分 | 完整拆分流程（§4） |
| 文件太大、太长、超800行、行数超标 | 超标巡检（§3） |
| 代码瘦身、文件瘦身 | 超标巡检 + 拆分建议（§3+§4） |
| 巡检行数、检查行数 | 仅超标巡检（§3） |
| 哪些文件需要拆分 | 超标巡检（§3） |
---
## 2. 经验吸收（拆分前自动执行）
**目的**：开始拆分前，自动加载历史经验，避免重蹈覆辙。
### 2.1 自动加载步骤
```
① 读取 docs/1知识库/技术总结/文件拆分经验总结.md（完整经验库）
② 读取复用手册 14.4（coordinator 模式 + 检查清单 + 陷阱表）
③ 读取 git log --oneline --grep="拆分" -10（最近 10 次拆分提交）
④ 从 ③ 中提取模式：哪些文件拆过、用了什么边界、行数结果
⑤ 检查 bug-guards/module-split-guard（防御规则）
```
### 2.2 经验摘要输出
加载后，向用户输出一段简要摘要：
```
【拆分经验加载完成】
- 历史拆分: N 个文件，成功率 100%
- 标准模式: coordinator + init(deps) 依赖注入
- 高频陷阱: G延迟绑定 / 循环依赖 / 输入双端同步 / 导出遗漏 / require不完整
- 防御规则: module-split-guard 已加载（10 条规则）
```
---
## 3. 超标巡检（自动发现）
**目的**：扫描所有文件，列出超标和接近超标的文件。
### 3.1 巡检命令
```bash
# 扫描 scripts/ 下所有 .lua 文件行数，排除数据文件
find /workspace/scripts -name "*.lua" \
! -name "er_seed_*" \
! -name "*_data.lua" \
! -path "*/data/*" \
-exec wc -l {} + | sort -rn | head -30
```
### 3.2 分级报告
| 级别 | 行数范围 | 标记 | 动作 |
|------|---------|------|------|
| 超标 | >800 | 🔴 | **必须拆分** |
| 预警 | 601-800 | 🟡 | 建议拆分 |
| 舒适 | ≤600 | 🟢 | 无需处理 |
### 3.3 排除规则
以下文件不计入巡检：
- `er_seed_*.lua`（自动生成的种子数据）
- `*_data.lua`（纯数据定义，拆分无意义）
- `scripts/data/` 目录下的文件
- 已知跳过的文件（如 panel_input_registrations.lua，需注释原因）
### 3.4 巡检结果模板
```
【行数巡检报告】
🔴 超标（必须拆分）:
- xxx.lua: 1234 行（超标 434 行）
🟡 预警（建议拆分）:
- yyy.lua: 750 行（距上限 50 行）
🟢 舒适区: 其余 N 个文件均 ≤600 行
上次巡检: YYYY-MM-DD
```
---
## 4. 拆分流程引导（核心流程）
### 4.1 阶段一：分析（必做）
```
① 读完整文件，统计总行数
② 列出所有函数及行数：
grep -n "^function\|^local function" scripts/xxx.lua
③ 识别拆分边界（按安全性选择）：
| 优先级 | 边界类型 | 安全性 | 子模块命名 |
|--------|---------|--------|-----------|
| 1 | 纯数据 | ★★★★★ | xxx_data.lua |
| 2 | 绘制层 | ★★★★☆ | xxx_draw.lua |
| 3 | 输入层 | ★★★☆☆ | xxx_input.lua |
| 4 | 逻辑子系统 | ★★★☆☆ | xxx_ai/events.lua |
| 5 | 混合依赖 | ★★☆☆☆ | 需 parentM 模式 |
④ 列出依赖清单：
- require 了哪些模块？
- 访问了哪些 G 表字段？
- init() 注入了哪些依赖？
- 哪些函数被外部调用？（grep 函数名）
⑤ 输出拆分方案给用户确认：
- 哪些函数留在 coordinator
- 哪些函数提取到子模块
- 预估拆分后行数
```
### 4.2 阶段二：骨架生成
**确认方案后，自动生成代码骨架：**
#### Coordinator 骨架
```lua
-- xxx.lua（coordinator）
local M = {}
-- 子模块
local SUB = require("xxx_sub")
-- coordinator 自有依赖（只留自己需要的）
local Config = require "Config"
-- 延迟绑定
local G
local function ensureDeps()
if not G then G = _G.G end
end
function M.init(deps)
G = deps.G
SUB.init({ parentM = M, G = G })
end
-- === 状态管理（留在 coordinator） ===
-- === 分派（调子模块） ===
function M.Draw(ctx, w, h)
ensureDeps()
SUB.init({ parentM = M, G = G }) -- 刷新 G 引用
SUB.draw(ctx, w, h)
end
-- === 对外接口（重新导出） ===
M.HitTest = SUB.HitTest
M.HandleAction = SUB.HandleAction
return M
```
#### 子模块骨架
```lua
-- xxx_sub.lua（子模块）
local M = {}
-- 自有依赖
local C = require "colors"
local FS = require "font_sizes"
local LS = require "layout_sizes"
local Logger = require "logger"
local log = Logger.new("XxxSub")
-- 注入依赖
local G, parentM
function M.init(deps)
if deps.G then G = deps.G end
if deps.parentM then parentM = deps.parentM end
end
-- === 从 coordinator 提取的函数 ===
-- （在此处粘贴，去掉下划线前缀）
return M
```
### 4.3 阶段三：执行拆分
```
① 将函数从 coordinator 剪切到子模块
② 函数重命名：M._drawXxx → M.drawXxx
③ coordinator 精简 require 列表
④ coordinator 添加子模块 require + init
⑤ coordinator 修改分派逻辑
⑥ 验证行数：两个文件都 ≤600
```
### 4.4 阶段四：验证（必做）
```bash
# 1. 被拆函数名检查（确认无遗漏调用）
grep -rn "被拆函数名" scripts/ --include="*.lua"
# 2. 行数验证
wc -l scripts/xxx.lua scripts/xxx_sub.lua
# 3. 构建验证
# → 调用 build 工具
# 4. 运行时日志检查
# → 查看 /opt/log/dev/user_script.log
```
### 4.5 阶段五：提交
```bash
git add scripts/xxx.lua scripts/xxx_sub.lua
git commit -m "拆分：xxx.lua（原行数→coordinator行数+子模块行数）"
```
---
## 5. 经验沉淀（拆分后自动执行）
**目的**：每次拆分完成后，自动将本次经验回填到知识库，形成持续积累。
### 5.1 沉淀触发条件
拆分提交成功后，**自动执行**以下步骤（不需要用户提醒）：
### 5.2 沉淀内容
#### ① 更新经验总结文档
在 `docs/1知识库/技术总结/文件拆分经验总结.md` 的统计数据表中更新数字：
```
总文件数 → +1
新增子模块 → +N
```
#### ② 如果发现新陷阱，追加到陷阱表
在经验总结的"四、关键陷阱与防范"章节追加新条目：
```markdown
### 4.X 新陷阱名称
**现象**：描述
**根因**：描述
**解决**：描述
```
#### ③ 如果发现新模式，回填到复用手册
在复用手册 14.4 章节追加新的子章节。
#### ④ 如果触发了 bug-guard，更新 module-split-guard
在 `~/.claude/skills/bug-guards/module-split-guard/SKILL.md` 追加新规则。
### 5.3 沉淀检查清单
```
□ 经验总结统计数据已更新
□ 新陷阱已追加（如有）
□ 新模式已回填复用手册（如有）
□ module-split-guard 已更新（如触发了新 bug）
□ 经验沉淀已单独 commit
```
### 5.4 沉淀提交格式
```bash
git commit -m "经验沉淀：拆分 xxx.lua 经验回填（新陷阱/新模式/统计更新）"
```
---
## 6. 批量拆分模式
**当多个文件需要拆分时，使用批次规划：**
### 6.1 批次规划原则
```
① 按风险排序：纯数据 → 绘制层 → 输入层 → 逻辑层
② 每批次内文件无依赖关系（可独立拆分）
③ 每批次完成后构建验证 + commit
④ 批次间如果发现新经验，立即沉淀（不等全部完成）
```
### 6.2 批量拆分方案模板
```markdown
## 批量拆分方案
### 超标文件清单（共 N 个）
| # | 文件 | 行数 | 超标量 | 拆分边界 | 难度 | 批次 |
|---|------|------|--------|---------|------|------|
| 1 | xxx.lua | 1234 | +434 | 绘制层 | 低 | 第一批 |
### 批次安排
| 批次 | 文件数 | 策略 | 预期风险 |
|------|--------|------|---------|
| 第一批 | N | 纯数据/绘制 | 低 |
### 拆分原则
1. coordinator 模式 + init(deps) 依赖注入
2. 外部调用者零改动
3. 每文件两个产物都 ≤600 行（G2 舒适线）
```
---
## 7. 定期巡检机制
**目的**：防止新代码悄悄膨胀超标。
### 7.1 巡检时机
| 时机 | 触发方式 |
|------|---------|
| 收工时 | 收工 skill 中加入行数快检 |
| 用户说"巡检" | P35 触发词匹配 |
| 大功能完成后 | 主动检查新增/修改文件行数 |
### 7.2 快检命令（收工时用）
```bash
# 快速检查是否有新超标文件（排除数据文件，只看 >700 行的）
find /workspace/scripts -name "*.lua" \
! -name "er_seed_*" ! -name "*_data.lua" ! -path "*/data/*" \
-exec wc -l {} + | awk '$1 > 700' | sort -rn
```
输出为空 = 无预警，可跳过。有输出 = 列出文件，提醒用户。
### 7.3 巡检结果记录
如果发现新超标文件，在巡检报告末尾追加：
```
⚠️ 新增预警: xxx.lua (750行)，建议下次迭代时拆分
```
---
## 8. 与其他 Skill 的联动
| Skill | 联动方式 |
|-------|---------|
| **module-split-guard** | 拆分执行时自动加载防御规则 |
| **行数守卫** | 巡检时检查是否有新超标文件 |
| **收工写记忆** | 收工时执行快检，发现超标文件记入 pipeline.json 的 likely_next_task |
| **代码复用守卫** | 拆分前检查是否有可复用的已拆模式 |
| **审查官** | 拆分完成后可选轻审验证质量 |
---
## 9. 完整工作流速览
```
触发（P35 匹配触发词）
↓
经验吸收（§2：读经验库 + git 历史 + bug-guard）
↓
超标巡检（§3：扫描文件 → 分级报告）
↓
拆分流程（§4：分析 → 骨架生成 → 执行 → 验证 → 提交）
↓
经验沉淀（§5：更新经验库 + 回填复用手册 + 更新 guard）
↓
闭环完成
```
**每一步都是自动的，不需要用户提醒。**