improve-codebase-architecture

name	improve-codebase-architecture
description	发现 DGame 代码库中的加深机会，依据 dgame-dev skill 的分层规范与 CLAUDE.md 编码红线，参考 docs/adr/ 中的决策。当用户想改善架构、寻找重构机会、合并紧耦合模块、把散落逻辑收口，或让代码库更易测试、更易被 AI 导航时使用。

Improve Codebase Architecture

暴露 DGame 架构摩擦并提出加深机会——把浅模块变为深模块。DGame 是热更手游工程，没有普遍的单元测试文化，所以加深的主要收益是：分层局部性（变更、bug、知识集中在一处）、AI 可导航性（少跳转即可理解一个概念）、以及 DGame 特有的收口（资源、配置、事件、模块访问、纯逻辑）。可测试性作为收益仅在逻辑能下沉到 GameBattle 纯逻辑域时才成立。

术语表

在每个建议中精确使用这些术语。一致的语言是关键——不要滑向"component"、"service"、"API"或"boundary"。完整定义见 LANGUAGE.md。

• Module（模块） — 任何具有接口和实现的东西（函数、类、程序集、模块门面项）。
• Interface（接口） — 调用者使用模块所需知道的一切：类型、不变量、错误模式、顺序、配置。不仅仅是类型签名。
• Implementation（实现） — 内部的代码。
• Depth（深度） — 接口处的杠杆：少量接口背后的大量行为。Deep（深） = 高杠杆。Shallow（浅） = 接口几乎与实现一样复杂。
• Seam（接缝） — 接口所在的位置；一个可以在不原地编辑的情况下改变行为的地方。（用这个词，不是"boundary"。）
• Adapter（适配器） — 在接缝处满足接口的具体实现。
• Leverage（杠杆） — 调用者从深度中获得的收益。
• Locality（局部性） — 维护者从深度中获得的收益：变更、bug、知识集中在一个地方。

关键原则（完整列表见 LANGUAGE.md）：

• 删除测试（思想实验，非真删代码）：想象删除该模块。如果复杂性消失了，它就是传递模块。如果复杂性重新出现在 N 个调用者身上，它就在发挥价值。
• 接口就是收口面。 在 DGame，一个好接缝是资源/配置/事件/模块访问被收口的那一点。
• 一个适配器 = 假设的接缝。两个适配器 = 真正的接缝。

本技能依据 DGame 的分层规范与编码红线，不重新争论它们。dgame-dev skill 的 references 为好接缝命名并界定落位；CLAUDE.md 的核心原则是不可违背的红线；ADR 记录已定的决策。

流程

1. 探索

先加载 DGame 的分层约束与红线——这是本技能与项目对齐的关键，不可跳过：

• 触发 dgame-dev skill 获取相关主题（分层落位 → project-map.md；四层单向依赖、程序集边界、启动链路、GameModule 门面、ConfigMgr 封装 → client-architecture-claude.md / client-modules-claude.md；再按涉及主题拉取 UI、事件、资源、红点、Luban 等 reference）。这些是命名接缝、判断分层归属、识别 GameModule.XXX 访问约定的权威来源。
• 阅读 CLAUDE.md 的核心原则（编码红线）：分层落位、优先复用 TEngine 二次封装、GameModule 访问、异步优先（UniTask）、资源必须成对释放、事件解耦（GameEventDriver/EEventGroup）。违背这些红线的浅性，是最高优先的加深目标。
• 阅读你将涉及区域中的任何 ADR（docs/adr/，若存在）。

然后用 Agent 工具配合 subagent_type=Explore 遍历代码库。有机地探索，记录你感受到摩擦的地方。DGame 中特别值得留意的浅模块形态：

• GameModule 门面里只做一次静态转发、几乎无逻辑的入口——它是杠杆点，也是浅性容易堆积的地方。
• ConfigMgr 封装里只透传 TbXXX / ConfigSystem.Instance.Tables 的方法，或反过来：本该收口到 ConfigMgr 的配置访问却散落在多个 UI/模块里（配置跨接缝泄漏）。
• UI 层：UIWindow/UIWidget/子页面只做透传的薄壳；或 UI 直接读配置表、直接加载资源，把本该在下层的知识拉进窗口脚本。
• 资源加载/卸载散落：加载与释放不成对、分散在多处，没有一个模块持有资源生命周期（无局部性）。
• 事件封装单调用点：IEvent 里只有一个发送者一个接收者的封装，删除它复杂性并不集中。
• 可下沉的纯逻辑：混在 GameLogic（依赖 Unity/UI/资源）里的纯计算，本可下沉到 GameBattle 成为进程内可测深模块，却因和表现层缠绕而无法测试。
• 红点树：节点定义、聚合与业务判断散落，未收口到 RedDotModule 现有入口。

对任何你怀疑是浅模块的东西应用删除测试：删除它会让复杂性集中，还是仅仅移动它？"集中了"就是加深信号。

分层与红线优先：候选必须尊重四层单向依赖（HotFix → Main → DGame → 基础设施）与热更程序集边界（GameLogic → GameProto/GameBattle，GameBattle 不得依赖 GameLogic 且只写纯逻辑）。加深不得引入反向依赖、不得让 Runtime/AOT 编译期引用 HotFix 业务类型、不得绕过 TEngine 二次封装层。凡是与这些冲突的"加深"，不是候选。

2. 以 HTML 报告呈现候选

将一个自包含 HTML 文件写入操作系统临时目录，不在仓库留痕。从 $TMPDIR 解析临时目录，回退到 %TEMP%（Windows），写入 <tmpdir>/architecture-review-<timestamp>.html，每次运行得到新文件。用 start <path>（Windows）为用户打开，并告知绝对路径。

报告用 Tailwind via CDN 布局，Mermaid via CDN 画图状关系（调用图、依赖、四层依赖流、时序），手工 div/SVG 画更偏编辑性质的视觉（质量图、剖面图）。每个候选一个 before/after 可视化。要视觉化。

每个候选渲染为卡片：

• 文件 — 涉及哪些文件/类/程序集（用真实路径，如 Scripts/HotFix/GameLogic/ConfigMgr/...）
• 问题 — 当前架构为什么造成摩擦（点名是哪种浅性：门面转发 / 配置泄漏 / 资源不收口 / 纯逻辑无法下沉…）
• 方案 — 会改变什么的通俗描述，并给出加深后模块的落位程序集
• 收益 — 用局部性、杠杆、收口解释；仅当能下沉到 GameBattle 时才谈可测试性
• Before / After 图 — 并排，展示浅性和加深
• 建议强度 — Strong / Worth exploring / Speculative，渲染为徽章
• 跨层影响 — 若跨 Runtime/Main/HotFix/配置层，明确标出

报告末尾以 顶部建议 章节结束：先处理哪个候选、为什么。

领域用 dgame-dev references 的真实名称，架构用 LANGUAGE.md 的词汇。 说"ConfigMgr 的配置读取接口"、"GameModule.ResourceModule 加载生命周期"、"RedDotModule 节点入口"——不要杜撰"FooBarHandler"或含糊的"某个 service"。

ADR 冲突：只有当摩擦足够真实、值得重新审视某条 ADR 时才提出该候选，并在卡片中用琥珀色标注（例如 "与 ADR-0007 矛盾——但值得重新开启，因为……"）。不要罗列 ADR 已禁止的每一个理论重构。

完整 HTML 脚手架、图表模式和样式指导见 HTML-REPORT.md。

先不要提接口。文件写好后，问用户："你想探索其中哪一个？"

3. 追问循环

用户选定候选后，进入追问对话。与他们一起走设计树——约束、依赖、加深模块的形状、接缝后面是什么、哪些逻辑能下沉到 GameBattle 变得可测。同时核对 DGame 落位：加深后的模块归属哪个程序集、是否仍通过 GameModule.XXX 访问、资源加载/卸载是否成对收口、配置是否收口到 ConfigMgr、事件是否走 GameEventDriver。

随着决策成型，副作用在线发生：

• 用 references 里没有的概念命名加深模块？ 将术语加入 CONTEXT.md——与 /grill-with-docs 相同纪律（见 CONTEXT-FORMAT.md），文件不存在则惰性创建。若该概念属于框架级规范，同时提议补进对应的 dgame-dev reference（依据 CLAUDE.md 的自我优化机制）。
• 在对话中锐化了一个模糊术语？ 就地更新 CONTEXT.md。
• 用户以一个承重理由拒绝候选？ 提供 ADR："要不要把这个记录为 ADR，这样未来架构审查不会再建议它？" 只在理由确实会被未来探索者需要时才提供，跳过临时理由和显而易见的理由。见 ADR-FORMAT.md。
• 想探索加深模块的替代接口？ 见 INTERFACE-DESIGN.md。
• 发现 references 描述与实际代码 API 不符？ 按 CLAUDE.md 自我优化机制记录到 .claude/memory/problem_YYYY-MM-DD.md。