MikuMikuAR 文档

Appearance

ADR-154: 引入大模型交流能力 — 推荐路线（聊天面板打底） ​

  • 状态: 🗑️ 已被 ADR-196 取代（Superseded）—— 本路线的技术目标（Go LLM 客户端 + 流式管线 + 聊天面板）已由 ADR-196 提前达成，架构合并（聊天 = 诊断面板「闲聊」tab 子集），无独立落点存续
  • 日期: 2026-07-20（初版），2026-07-28（归档为被取代）
  • 相关: ADR-196（AI 诊断助手，实际实现本路线目标的传输底座）、ADR-155（NL 控场景，叠加于同一管线）、ADR-093（声明式菜单 Schema，NL 控场景上游）、ADR-153（无障碍，面板需 a11y）、app.contract（Go↔TS 绑定桥）

背景与问题 ​

项目当前 0 处大模型集成：package.json 无任何 AI 依赖；text-model/ 为 MMD 素材库（PMX/VMD/audio），非语言模型；ai-news-*、novel/ 为城邦外围 LLM 产出内容，未接入 app。

用户希望在 MikuMikuAR 中引入「大模型交流」能力，但有两个顾虑：(1) 市面编程器（Cursor / Claude Code 等）复杂度高，担心路线难走；(2) 范围不清导致 scope 膨胀。

本 ADR 与 ADR-155（激进）、ADR-156（创意）并列给出三条候选路线，本文为推荐路线。

⚠️ 归档说明（2026-07-28）：本 ADR 的核心目标已由 ADR-196 提前实现且架构更优——ADR-196 起草时即声明「以 ADR-154 聊天面板为传输底座……聊天闲聊为其子集」。规划的 4 个落点无一按原样创建（详见下方「第一步交付」表的落地对照），继续挂「规划中」会误导后来者照原落点表重复实现 ai-chat-panel.ts / llm-client.ts，与现有 core/ai/ 双适配器架构冲突。故归档为被取代，不再独立实施。

路线对照 ​

路线第一步交付后续扩展风险
推荐（本 ADR）聊天面板（客户端+流式+面板）叠 NL 控场景🟢 低
激进（ADR-155）直接 NL 控场景—🟡 中
创意（ADR-156）角色台词接 TTS/口型🟡→🔴

决策 ​

采用聊天面板打底作为第一步：先把 Go 侧 LLM 客户端 + 流式管线 + 一个 TS 面板跑通，后续在该管线之上叠加自然语言控场景。

核心原则 ​

  1. LLM 仅作「受限意图翻译器」：聊天场景输出自由文本；后续 NL 控场景输出固定 schema JSON，绝不开放「改文件 / 跑命令」类无限权力——这是复杂度可控的根本。
  2. 密钥服务端持有：API Key 落 Go 后端（设置或环境变量），WebView 前端不直连、不持有密钥。
  3. 纯增量、零侵入：新增独立模块，不改动 Babylon 渲染循环、不改动 ADR-093 菜单动作层的既有实现；NL 控场景仅「调用已有菜单 handler」，不新增动作逻辑。
  4. 复用现有桥与面板机制：走现成 Go↔TS Wails 绑定（116 函数契约）+ ADR-093 声明式面板，不从零造。

第一步交付（聊天面板）——落地对照（2026-07-28 核实） ​

下表左侧为本 ADR 原规划落点，右侧为 ADR-196 实际落地位置。无一按原样创建，全部合并或架构升级。

模块原规划落点实际落地（ADR-196）说明
Go LLM 客户端internal/app/llm/client.go✅ internal/app/llm/client.go（321 行）落点一致，已实现
Go 绑定internal/app/llm/binding.go✅ internal/app/ai_binding.go + internal/app/llm/tools.go落点名不同，能力已具
TS 客户端封装frontend/src/core/llm-client.ts✅ core/ai/{index,go-adapter,browser-adapter,sse}.ts架构升级：单 client → 双适配器（镜像 ADR-176）
TS 面板frontend/src/menus/ai-chat-panel.ts✅ menus/settings-diagnostic.ts 的「闲聊」tab合并：聊天面板从未独立创建，长进诊断面板

后续扩展（叠 NL 控场景） ​

在已跑通的客户端之上：新增「意图解析层」——LLM 走 function-calling 输出 {action, params}，映射到 ADR-093 已有菜单动作集（闭集）。无需重建动作逻辑，边际成本低。详见 ADR-155。

风险与回退 ​

风险等级缓解
API Key 泄露🟠仅 Go 后端持有；前端经 Wails 绑定间接调用，WebView 不可见
流式体感差（无 SSE）🟡强制走 SSE 流式，禁用整段等待
面板 a11y 缺失🟡复用 ADR-153 的 aria-live / focus 规范
范围蔓延🟢严格限定第一步仅聊天面板；NL 控场景单列 ADR-155，评审后再动

实施路径 ​

阶段范围验收
Step 1Go 客户端 + 绑定 + TS 面板，跑通基础对话面板可收发消息、流式渲染、tsc --noEmit 0 错、单测覆盖客户端解析
Step 2（后续，见 ADR-155）叠 NL 控场景意图层自然语言触发已有菜单动作

修订记录 ​

日期修订
2026-07-20初版，推荐路线定稿
2026-07-28归档为「已被 ADR-196 取代」：核心目标由 ADR-196 提前达成，架构合并（聊天 = 诊断面板闲聊 tab 子集），4 个规划落点全部合并/升级，无独立落点存续。补落地对照表，防后来者照原落点重复实现。