# G4 内部模块接入机制

当前门户包含梅花易数、塔罗、小六壬、雷诺曼和六爻纳甲五个模块。公共部分统一模块身份、导航、模型目录、共享背景、生成互斥、私人生成、追问及精确 RPC 路由；各体系保留自己的本地规则与结果结构。梅花和塔罗继续使用原有服务和页面，三个新增模块使用 `MethodService`、`MethodController`、`MethodPage`。没有宣称五个模块已经继承同一个类，也没有提供面向外部插件的运行时模块市场。

## 模块身份与注册

`src/shared/modules.ts` 的 `MODULES` 是门户卡片、顶部导航、Host 注册和共享记忆来源使用的同一份目录。每项含稳定的 `id`、名称、简介、序号、传统标签和类型。`ModuleId` 与 `NewMethodId` 由目录推导，后者排除现有梅花、塔罗。

Host 每次插件注册只创建一份 `MemoryService` 和一份 `GenerationGate`，再将它们传给所有五个模块。口令、解锁状态、文档、版本队列与失效 epoch 因此不会按模块重复创建；任意模块的解读和追问都使用同一个生成互斥位。背景提炼占用该位时仍允许本地起课、投币和抽牌，新的 AI 首解等待提炼结束后冻结背景。

| 模块 | Host 服务 | 客户端控制器 / 页面 | 独立本地核心 |
|---|---|---|---|
| 梅花易数 | `MeihuaService` | `MeihuaController` / `Page` | `src/core/` |
| 塔罗 | `TarotService` | `TarotController` / `TarotPage` | `src/tarot/` |
| 小六壬 | `MethodService('xiaoliu')` | `MethodController` / `MethodPage` | `src/xiaoliu/` |
| 雷诺曼 | `MethodService('lenormand')` | `MethodController` / `MethodPage` | `src/lenormand/` |
| 六爻纳甲 | `MethodService('liuyao')` | `MethodController` / `MethodPage` | `src/liuyao/` |

三个新增核心各自有类型和算法版本。小六壬返回月宫、日宫、时宫和计数过程；雷诺曼返回固定牌序、中心、相邻组合与五张对照；六爻返回独立本卦/变卦、多动爻、八宫、纳甲、世应、六亲、六神和月建日辰旬空。公共 UI 按模块选择对应结果呈现，不把它们强制压成梅花结果或塔罗结果。

## RPC 契约

`registerModuleTransport` 逐条注册 `/api/<module>/<endpoint>` 的 POST 精确路由。请求必须是 `application/json` 且通过宿主 Connection 的 `client-request` 信封校验，`method` 必须与路由完全匹配；响应保留同一个 `rpcId`。认证和跨源入站策略由宿主 `/api` 承载。进程内信封测试不会被当作真实 HTTP 认证验收。

五模块共用 `catalog`、`current`、`interpret`、`followup`、`cancel`、`checkpoint`、`preferences` 的生命周期名称；本地操作保留体系差异：

| 模块 | 本地操作 | 开始后到 ready 的流程 |
|---|---|---|
| 梅花 | `cast` | 固定起卦规则与环境，返回本地卦象 |
| 塔罗 | `start`、`select`、`reveal` | 洗牌 → 选背牌 → 按既有牌阵揭示 |
| 小六壬 | `start` | 固定当地时间，直接计算三次顺数结果 |
| 雷诺曼 | `start`、`select`、`reveal` | 36 张洗牌 → 选齐 3/5 槽位 → 整组揭示冻结结果 |
| 六爻 | `start`、`toss`、`record` | 自下而上记录六条 6/7/8/9 爻值 → 独立装卦 |

所有 mutation 携带从 `/api/memory/status` 取得的 `epoch`。清空、锁定或重启后旧页面不能依靠旧 id 重新提交。新增抽牌和投币还携带 `expectedCount`，分别对照 Host 的已选槽位数或已记爻数；追问携带 `expectedTurnCount`，取消追问携带当前 `turnId`。这样可以拒绝双窗口、重复动作和旧页面晚到操作。

`catalog/current` 仅恢复当前状态，不触发提炼或调用模型生成。读取模型目录本身可能与宿主供应商目录服务交互，它和生成解读是不同动作。`preferences` 只允许在首次 AI 解读冻结之前修改所选模型、共享背景引用与替他人设置，冻结后不能悄悄改写本轮。

梅花与塔罗既有路由名、公共核心导出和独立结果结构保留。此次接入仍执行 0.4 引入的 mutation epoch 约束，不向未带 epoch 的 0.3 直接 RPC 调用者宣称完全兼容。旧客户端须更新请求协议；详见 README 的接口兼容说明。

## 公共生成与私人背景

`module-framework.ts` 提供背景选项、模型路由解析、可用模型校验及目录读取。`generatePrivate` 负责首解与追问的流式正文、终态、超时、取消、加密私人审计和普通 Session 元信息。完整私人请求不通过 `GenerateOptions.sessionId` 写入供应商 Session 贡献器；这只是已经核对的调用链边界，不是对所有宿主插件的隔离保证。

首次 `interpret` 按当前共享记忆成功版本冻结 `MemorySnapshot`。正文作为用户资料块传给模型；系统解读规则单独按模块规定本地结果的含义。浏览器读取的 `MemoryUsage` 只有使用状态、版本和 epoch，结果 RPC 不携带解密文档正文。追问使用同一个背景快照和完整角色顺序对话，不因用户随后编辑文档改变旧轮。

点击结束、成功离开当前模块或在 Host 另起一轮时，检查点只收集用户原始问题与新增追问。替他人问关闭本人背景引用和自动写入；仅停用背景引用不会自动停用本人信息写入。后台提炼的来源校验、并发写入、失败保留和撤回去重仍由唯一 `MemoryService` 处理。

锁定、清空通过 `memory.onInvalidate` 向五服务广播取消并清理当前结果、背景快照和暗牌等 Host 缓存。客户端 `MemoryController` 检测解锁状态/epoch 变化后调用各控制器的 `resetPrivate`，取消旧请求、推进客户端 revision，并清理草稿与结果。晚到快照或 mutation 回复不能复活旧私人问题。

## 导航、恢复和页面状态

`HubController` 管理门户、五个模块视图、转场、减少动态效果与深浅主题。解读或追问正在进行时禁止切换模块，当前页面保留取消入口。注册客户端或 Connection 重置时，控制器重新读取 Host 当前结果；若发现尚在生成的轮次，门户自动恢复到对应模块。

模块页面由同一次客户端插件注册的控制器维护，普通切换、暂时隐藏与目录刷新不会重新起课或抽牌。背景面板打开时其余视图进入 inert，隐私 epoch 改变后页面重建。这里的恢复指同一个仍运行的 Host 的当前结果；Host 重启后的背景密文可以解锁恢复，但没有实现从加密审计重新装载完整占卜历史列表。

三个新增模块的 `MethodController` 使用同一请求 revision、快照请求序号、AbortController 和轮询流程。`load` 恢复 Host 的问题、排列和背景选项；`act` 在旧请求晚到时拒绝覆盖新状态；`poll` 直到首解和追问终态；`cancel` 在追问时找到当前 `turnId`；`dispose/resetPrivate` 结束旧私有请求。各模块保留自己的本地动作参数和 UI。

复制导出包含冻结问题、环境、模型、背景使用版本、已记录投币、已选槽位、本地结果、首解及追问终态，部分投币阶段 `result:null` 也不能丢掉已记录动作。没有复制 Host 暗牌集合或解密背景正文。模型生成的 HTML 样式文字用 React 文本节点显示，不能成为可执行 DOM。

## 新模块的实际接入步骤

1. 在独立目录创建纯本地核心、输入/结果类型、规则版本与可核对的对照样例；算法不依赖模型。
2. 在共享 `MODULES` 增加稳定模块 id 与门户文案，并评估公共 union、记忆来源和普通日志模块标识是否需要扩展。
3. 按新体系实现 Host 生命周期。如果它符合现有三模块模式，扩展 `MethodService` 的本地分派、输入校验和结果冻结；若流程不同，保留独立服务，并复用目录、背景、生成、追问和 transport 辅助函数。
4. 从 Host 注册处注入既有 `MemoryService/GenerationGate`，注册实际支持的精确 endpoints 及 dispose。不要新建第二份背景、第二个生成位或明文持久化路径。
5. 客户端增加控制器注册、恢复/隐私重置/Connection 重置处理和导航离开检查点；新增模块不能只加门户卡片而没有这些生命周期接入。
6. 增加对应结果渲染与本地动作。洗牌集合只保留 Host，浏览器先收槽位；AI 解读前结果冻结，追问不能换牌/换爻/换规则。
7. 在构建入口与 package exports 中暴露所需纯核心，保留独立规则说明、素材许可和第三方依赖来源。新素材不依赖远程网络加载。
8. 运行核心对照、Host/RPC/加密记忆、客户端状态和 DOM 检查，再完成包完整性、隔离 HTTP、Web/原生验证。真实模型质量独立记录。

目前 `MethodService` 仍显式分派三个新 id，因此没有“只改目录就能自动接入任意体系”的承诺。上述流程是源码内部扩展路径；规则差异和新的本地动作需要实现并验收。

## 验证范围与证据分层

`tests/method-client.test.tsx` 九组回归通过真实 `MethodController`、完整 Connection 信封、`MethodService/MemoryService` 和临时 JSON 密文后端，只模拟供应商输出，验证：

- 三模块完整本地结果呈现；小六壬三宫与步骤、雷诺曼五张四相邻两镜像及离线原创牌图、六爻六行纳甲/六亲/六神/世应/旬空与交节。
- 未解锁不能点击解读，查看或展开本地依据没有生成调用；雷诺曼背牌阶段没有图像或提前结果。
- 六爻手录和模拟投币的自下而上顺序、`expectedCount`、部分记录复制。
- Host 当前结果和背景选项恢复，`resetPrivate` 后晚到快照和动作回复被拒绝。
- 三模块首解和追问的轮询、取消前缀保留、正确 `turnId`、完整后续回答，以及首条冻结用户记录和背景块逐字一致。
- 完整复制保留结果与追问终态，生成文字作为安全文本显示。

这些检查不覆盖真实供应商语义质量、实际桌面视觉、系统剪贴板或跨机器安装，也不会代替最终全仓构建与安装包逐项核对。最终交付证据以对应版本验收文件和实际测试日志为准。

附加恢复回归覆盖三个模块的非首项模型与指定时间、结束检查点路由、六爻超范围日期的开始拒绝，以及另一窗口新轮完成后旧追问草稿清理。

最终 0.6.0 已完成 169/169 全仓测试、类型检查、构建、安装包 40 文件逐字节回读，以及隔离 Web/原生验收。实际界面验证包括三新模块本地结果与模拟解读、跨模块背景更新与冻结、取消保留前缀、复制、旧模块导航、主题、窄窗及锁定后的本地运行。合成信息的存储/日志/原生浏览器缓存扫描和普通 Session 解压回读结果见 [总验收记录](v6-goal-completion-audit.md)。真实供应商语义质量和正式安装独立记为未执行。