文件拆分助手

05/1228 浏览开发交流

---

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）

↓

闭环完成

```

**每一步都是自动的，不需要用户提醒。**

TapTap 制造应用

9.8

前往论坛