1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | component-flattening-analysis-tech-leads-club-agent-skills |
| 作者/维护者 | Tech Leads Club |
| 来源链接 | https://github.com/tech-leads-club/agent-skills/tree/main/packages/skills-catalog/skills/(architecture)/component-flattening-analysis |
| 许可证 | MIT（仓库根 LICENSE 文件，GitHub API） |
| GitHub Stars | 5,024（GitHub API；为整个技能市场共享，非本技能独有） |
| Forks | 460（GitHub API） |
| 最新版本 | skills-catalog-v0.17.3（2026-08-05，GitHub Releases） |
| 安装方式 | npx @tech-leads-club/agent-skills 交互式安装，或 CLI 指定安装 |
2. 功能介绍与亮点
component-flattening-analysis 检查代码库的组件命名空间结构，找出“该属于某个组件却停留在根命名空间”的孤儿类，并给出具体的重构方案。核心流程分三个阶段：
- 结构映射——遍历命名空间树，标记哪些节点是叶子节点（组件）、哪些是被下级扩展过的根命名空间（子域）；
- 孤儿类检测——扫描每个根命名空间下的源文件，按“业务代码”“共享代码”“混合”分类，并评估它们被哪些组件依赖；
- 扁平化方案分析——对每个问题命名空间给出三种可选策略：下沉合并（把叶子节点代码并入根命名空间）、上移拆分（把根命名空间代码拆成新的叶子组件）、提取共享（把公共代码单独抽成
.shared组件），并说明各自的适用条件。
亮点：明确给出“组件应该只存在于叶子节点”这条架构规则，把常见的“根目录下散落几个类不知道该不该动”问题变成结构化判定；每种扁平化策略都配有前后对比的目录树示例，输出可直接落地的重构步骤而不是空泛建议；技能作者在 description 中显式声明了它与同仓库 coupling-analysis、domain-identification-grouping 的分工边界，避免用户混用；内容为纯 Markdown 方法论，无脚本、无外部依赖。
3. 适用场景
所属分类：工程效率与代码质量
- 单体应用或大型模块拆分前，需要先定位哪些类“放错了位置”、该归属到具体子组件而不是留在顶层命名空间
- 代码评审中发现某个目录顶层堆了不少零散文件，需要判断是该合并进现有子组件、拆出新组件，还是抽成共享代码
- 为后续的耦合分析或领域分组做前置清理，先让组件结构本身干净、无孤儿类
- 受益人群：负责单体重构或模块化改造的技术负责人、架构师，以及日常处理代码评审中“这个类该放哪儿”争议的高级工程师
4. 跨 Agent 兼容性
- Claude Code：✅ 原生支持。所属市场官方支持列表 Tier 1 明确列出，安装方式与市场其余技能一致，正文不依赖 Claude 专属交互工具。
- Codex：⚠️ 需适配。官方支持列表 Tier 2 列出 OpenAI Codex，但未见针对该技能的专项适配说明。
- OpenClaw：❓ 未验证，抓取到的材料中未提及该平台。
- Hermes Agent：❓ 未验证，抓取到的材料中未提及该平台。
5. 推荐理由
“这个类到底该放在哪个组件里”是重构中最容易靠直觉拍板、也最容易吵起来的问题——留在原地会让根命名空间越堆越乱，随手挪走又可能破坏依赖关系。这个技能把判断过程拆成命名空间建模、孤儿类分类、扁平化策略选择三步，每步都有可视化的目录树示例，产出可以直接执行的重构步骤而非“建议整理一下”这种空话。它是一个可以单独安装使用的原子工具，不需要为了这一项分析去装下游更大的拆分流水线。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 5 | 所属技能市场整体 5,024★，为 88 个技能共享的合集热度，不代表本技能自身；检索未发现针对该子技能的独立第三方讨论 |
| 可用性 | 8 | npx 一条命令即可交互安装，免费无付费依赖；SKILL.md + README + QUICK-REFERENCE 共约 38,550 字节，开箱即可用；所属目录最近一次内容更新为 2026-02-26，距今约 5.5 个月，技能市场仓库本身在 2026-08-06 仍有新提交 |
| 安全性 | 9 | 全部内容为纯 Markdown 方法论与目录树示例，逐份通读三个文件未见可疑指令、混淆代码或隐蔽外发；无本地命令执行、无自身网络外发、无凭据索取；License（MIT）明确；所属市场对目录内全部技能发布前统一执行 Snyk Agent Scan 静态扫描，本技能历史扫描记录仅有一条“隐藏 Unicode 字符”中等提示，逐字节核对后确认为目录树示例中的常规制表符号（├└│等），非隐藏指令 |
| 综合分 | 7.33 | 三项均值 |
安全检查清单：①无 shell 命令执行，纯文本指令 ②无自身外联通道 ③无需 API Key 或凭据 ④通读 SKILL.md、README、QUICK-REFERENCE 三份文件未见可疑指令；市场历史静态扫描曾标记本技能含“隐藏 Unicode 字符”（中等），逐字节核实后确认为目录树绘图用的常规制表符号，非隐藏指令或混淆内容 ⑤市场统一静态扫描 + 作者具名维护 ⑥License 清晰（MIT） ⑦所属目录最近内容更新 2026-02-26，约 5.5 个月前
7. 跟同类 Skills 相比的优势
| 项目 | 定位 | 与本技能的差异 |
|---|---|---|
| component-flattening-analysis（本技能） | 找出错放在根命名空间、该归属某组件的孤儿类，给出三种扁平化重构方案 | 原子工具，只装这一项能力即可使用 |
| component-common-domain-detection | 检测跨多个组件重复出现的业务逻辑，判断是否该整合 | 处理的是“逻辑重复”问题，不涉及单个类的归属位置 |
| coupling-analysis | 用强度/距离/波动性三维模型衡量模块间耦合程度 | 只回答“耦合是否过重”，不判断某个类该放在命名空间树的哪个位置 |
| domain-identification-grouping | 把已经理清的组件按业务边界聚合成领域分组 | 处理组件到领域的分组问题，前提是组件结构本身已经扁平、无孤儿类 |
| modular-decomposition | 组件盘点→重复检测→扁平化→耦合分析→领域分组五步流水线 | 内嵌了本技能对应阶段的方法论作为流水线第三步，适合一次性跑完整条拆分分析链、不介意多装其余四步的场景 |
8. 用户评价
该技能目前在第三方平台尚无具名用户评价。
9. 其他补充
所属技能市场官方支持 Claude Code、Cursor、GitHub Copilot 等在内的十余个 AI 编码 agent；技能内容以英文撰写；市场对外宣称对所有技能执行统一的静态安全扫描（Snyk Agent Scan）与内容审校流程。
10. 安装使用方式
- 交互式安装：
npx @tech-leads-club/agent-skills，选择 “Install skills” 后搜索component-flattening-analysis并选择目标 agent - 指定安装：
npx @tech-leads-club/agent-skills install -s component-flattening-analysis -a claude-code - 安装后无需重启，在对话中提出“找出根命名空间里的孤儿类”“帮我把这个模块的结构扁平化”等请求即可触发
11. 注意事项
- 产出的是命名空间结构图与扁平化建议，不是可直接执行的重构补丁，实际挪动文件后仍需人工更新引用并跑测试验证
- 该技能只判断“类的位置是否合理”，不检测跨组件的业务逻辑重复，此类需求应改用 component-common-domain-detection
- 技能内容为英文，中文项目团队使用时依赖 agent 自身的翻译理解能力