Appearance
AI 知识库路由表
本表把用户的自然语言意图映射到首张知识卡。AI 应先命中首选卡，再沿卡片的 source_files、API 和子系统关系继续追踪；不要直接扫描整个 frontend/src/。
由
scripts/gen-routes.mjs自动生成：首选卡按卡片use_when关键词命中，其次阅读为共享 ADR 的关联卡。
路由规则
| 用户意图或关键词 | 首选知识卡 | 其次阅读 |
|---|---|---|
| 动作注册、NL 控场、自然语言控制、动作执行器、工具 catalog、参数适配器、action registry | 统一动作注册表 — 菜单/NL/快捷键共享真相源 | NL 意图解析 — LLM 文本 → 动作执行、环境弹窗（编排 + barrel）、资源库操作 |
| AI 配置、loadAiConfig / saveAiConfig、Ollama 端点 | AI 配置持久化（IndexedDB） | 错误环形缓冲与全局捕获、场景运行时快照（AI 上下文）、内置 AI 诊断助手 — 双适配器服务层 |
| 错误缓冲、console.error 捕获、全局错误 | 错误环形缓冲与全局捕获 | AI 配置持久化（IndexedDB）、场景运行时快照（AI 上下文）、内置 AI 诊断助手 — 双适配器服务层 |
| 自然语言控场、NL 意图解析、LLM 动作解析、意图分发、intent dispatcher | NL 意图解析 — LLM 文本 → 动作执行 | 统一动作注册表 — 菜单/NL/快捷键共享真相源、环境弹窗（编排 + barrel）、资源库操作 |
| 场景快照、诊断上下文、FPS / 模型数 | 场景运行时快照（AI 上下文） | AI 配置持久化（IndexedDB）、错误环形缓冲与全局捕获、内置 AI 诊断助手 — 双适配器服务层 |
| AI 诊断助手、resolveAi、浏览器/Go 适配器、streamChat / testConnection | 内置 AI 诊断助手 — 双适配器服务层 | 应用启动引导、AI 配置持久化（IndexedDB）、错误环形缓冲与全局捕获 |
| 安卓 文件访问 SAF Storage Access Framework shared 模式 /sdcard 目录选择、网页 FSA 重选目录 授权引导 getFsaAuthState、SelectDir 在安卓弹 SAF 建树 ACTION_OPEN_DOCUMENT_TREE | 安卓文件访问（shared 模式） | 资源库初始化、风力物理注入（WASM Bullet） |
| 外部动画、Mixamo、VRM、GLB、FBX、动作重定向、骨骼映射、人形动画导入 | 外部动作重定向桥 | 场景序列化与自动保存 |
| AR 摄像头、视频透传、前后摄切换 | AR 摄像头视频透传 | AR 模式场景级协调 |
| AR 模式协调、接触阴影、AR 截图 | AR 模式场景级协调 | AR 摄像头视频透传 |
| 音频总线、音效、SFX、脚步声音量、音频上下文 | 音频总线 | 脚部落地检测降级、脚部地面跟随（MMD-native IK） |
| 骨骼覆盖存储、骨骼仲裁、感知层冲突 | 骨骼覆盖存储（多模块仲裁） | 虚拟裙骨物理控制器（ADR-084 Phase 2-3） |
| 骨骼覆盖、bone override、骨骼编辑、动作覆盖、欧拉角覆盖、混合权重、IK 保护、帧钩子注册、帧内时序（ADR-186） | 骨骼覆盖核心 API | 场景序列化与自动保存、动作模块基类、模型注册表与生命周期管理 |
| 相机状态、相机位置保存、scene/canvas 引用共享、freefly 输入状态 | 相机状态管理 + 运行时上下文 | 相机模式管理系统（MmdCamera）、环境状态写入入口（setEnvState + 中间件链）、环境重力控制 |
| 相机模式、轨道相机、自由飞行、相机控制、视角切换、ArcRotate、Freefly | 相机模式管理系统（MmdCamera） | 相机状态管理 + 运行时上下文、环境状态写入入口（setEnvState + 中间件链）、环境重力控制 |
| 后端适配、浏览器后端、Go 后端、IndexedDB、存储适配、后端测试、测试桩、mock | 后端适配层 | 内置 AI 诊断助手 — 双适配器服务层、环境状态防抖持久化、时间流转与太阳角系统 |
| DOM 契约、role 属性、aria 属性、选择器、e2e 断言、collapsible class | 渲染层 DOM 契约单源 | — |
| setEnvState、环境状态写入、中间件注册、预设动画状态 | 环境状态写入入口（setEnvState + 中间件链） | 相机状态管理 + 运行时上下文、相机模式管理系统（MmdCamera）、环境变更分发回调（破循环依赖） |
| 碰撞开关、身体碰撞、地面碰撞、WASM 物理碰撞 | 环境碰撞控制 | 环境重力控制 |
| 环境调度、破循环依赖、dispatch | 环境变更分发回调（破循环依赖） | 环境状态写入入口（setEnvState + 中间件链）、环境系统实现核心（barrel + observer + fog） |
| 重力控制、WASM 物理重力 | 环境重力控制 | 相机状态管理 + 运行时上下文、相机模式管理系统（MmdCamera）、环境状态写入入口（setEnvState + 中间件链） |
| 地面材质、GroundMaterialSpec、地面重建、地面材质单一来源、地面 typeKey、ADR-226 | 地面材质单一事实源（GroundMaterialSpec） | 地面系统 |
| 地面系统、程序化纹理、涟漪、地面高度查询 | 地面系统 | 地面材质单一事实源（GroundMaterialSpec） |
| 环境实现、observer、fog、barrel 重导出 | 环境系统实现核心（barrel + observer + fog） | 环境状态写入入口（setEnvState + 中间件链）、环境变更分发回调（破循环依赖）、环境状态防抖持久化 |
| 环境灯光、灯光包装、灯光与场景集成、时间预设、灯光派生 | 环境灯光包装 | EnvState 单一源 Schema、场景光照与阴影（barrel） |
| 环境弹窗、环境菜单、环境设置入口、env 菜单 | 环境弹窗（编排 + barrel） | 场景弹窗（编排 + 路由）、统一动作注册表 — 菜单/NL/快捷键共享真相源、NL 意图解析 — LLM 文本 → 动作执行 |
| 环境持久化、防抖保存、envState 持久化 | 环境状态防抖持久化 | 时间流转与太阳角系统、内置 AI 诊断助手 — 双适配器服务层、相机状态管理 + 运行时上下文 |
| EnvState 默认值 | EnvState 默认值派生 | — |
| EnvState、环境状态 schema、getEnvKeys、dispatch group | EnvState 单一源 Schema | 环境灯光包装、场景光照与阴影（barrel）、全局状态与场景运行时 Store |
| 时间流转、太阳角、预设动画、环境预设 | 时间流转与太阳角系统 | 环境状态防抖持久化、设置共享工具、内置 AI 诊断助手 — 双适配器服务层 |
| 水面、水池、水面反射 | 水面系统 | — |
| 环境系统、环境门面、env facade | 环境系统门面（Facade） | — |
| 全局事件、拖放导入、更新通知 | 事件处理与导航系统 | 应用启动引导、Go 更新检查与安装、渲染循环与 FPS 时钟 |
| 错误提示、信息提示、状态反馈、toast、status | 结构化反馈 API | — |
| 文件服务、文件 URL、文件编码、HTTP URL、文件服务器 | 统一文件服务层 | Go ZIP 解压与缓存管理、VMD 动作加载器 |
| 脚部落地检测 | 脚部落地检测降级 | 音频总线、脚部地面跟随（MMD-native IK） |
| Go 后端 生命周期 ServiceStartup ServiceShutdown、Go 配置系统 config.json GetConfig SetResourceRoot SetStorageMode、无障碍 GetSystemA11ySettings、后端日志环形缓冲 LogRing AiGetBackendLogs、COOP/COEP MPR coopCoepEnabled | Go 后端核心（App 生命周期 + 配置系统） | 应用启动引导、键盘导航工具 |
| Go 文件访问 FileAccessor ReadTextFile ReadFileBytes 平台抽象、安卓 shared 模式 路径管理 pathmgr、content:// URI ErrContentUriNotSupported | Go 文件与路径平台抽象 | 资源库操作、资源库核心 |
| Go 模型隔离 IsolateModelDir、安全路径 isSafePath 路径穿越、信任目录 trustedRoots | Go 模型隔离与安全 HTTP | — |
| Go 软件集成 Blender MMD 检测 打开、自定义软件 ScanSoftwareDir LaunchSoftware、OpenWithSoftware 外部软件打开模型 | Go 软件集成（Blender/MMD/自定义） | — |
| Go KTX2 纹理编码 toktx 转码、纹理压缩 ktx2Encode transcodeTexturesInDir、压缩模式 guessEncodeMode | Go KTX2 纹理编码 | — |
| Go 模型库扫描 ScanModelDir 资源分类、模型元数据 GetModelMeta GetModelMetaBatch、资源根目录 SelectDir、ZIP 内部条目展开 expandZipEntries | Go 模型库扫描 | GPU 压缩纹理能力探测、PMX 模型加载与缩略图捕获、场景渲染管线与后处理 |
| Go LLM 客户端 StreamChat 流式对话、AI 诊断助手 AiStreamChat AiCancelStream 后端实现、连接测试 AiTestLLMConnection AiFetchModels、工具调用 ToolSchema tool call | Go LLM 客户端与 AI 绑定 | — |
| Go 广场窗口 预热 导航 NavigatePlazaWindow 窗口控制、广场配置 FetchPlazaConfig SavePlazaConfig 缓存、plaza 直连模式 window.open 拦截 | Go 广场窗口与配置 | — |
| Go 预设 保存加载 环境预设 模型预设 动作预设 渲染预设 场景预设、标签系统 AddTag GetTagsByModel、库内预设模型 GetModelPresets SaveModelPresetToLibAuto | Go 预设持久化与标签 | 模型预设管理 UI、场景序列化与自动保存 |
| Go 模型广场代理 StartProxy StopProxy、SSRF 防护 私有 IP 拦截 isBlockedIP、广场下载 DownloadFromPlaza、WebSocket 代理 proxyWebSocket | Go 模型广场代理（SSRF 防护） | — |
| Go 场景保存加载 SaveSceneFile LoadSceneFile SaveLastScene、场景打包 BundleScene 场景 bundle、自动存档 SaveLastScene 韧性 | Go 场景序列化与打包 | — |
| Go 更新检查 CheckForUpdate GitHub Release、安装器 DownloadAndRunInstaller APK DownloadApk、版本比较 compareVersion isNewer | Go 更新检查与安装 | 事件处理与导航系统、应用启动引导 |
| Go 下载目录监听 fsnotify 下载自动导入、本地文件导入 ImportLocalFile、watch:newfile 事件、去抖 800ms watchPending | Go 下载目录监听与导入 | — |
| Go ZIP 解压 ExtractZip ImportZip 缓存、解压缓存清理 CleanOrphanCache ClearAllCaches GetCacheStats、Shift-JIS GBK 文件名解码 bestDecode decodeZipName、文件 HTTP 服务 StartFileServer StopFileServer、COOP COEP 中间件 | Go ZIP 解压与缓存管理 | 统一文件服务层、应用启动引导、运行模式检测 |
| GPU 能力、压缩纹理、KTX2、ASTC、BC7、ADR-189 | GPU 压缩纹理能力探测 | Go 模型库扫描、PMX 模型加载与缩略图捕获、场景渲染管线与后处理 |
| 启动引导、初始化、bootstrap | 应用启动引导 | 内置 AI 诊断助手 — 双适配器服务层、事件处理与导航系统、运行模式检测 |
| 资源库操作、导入模型、替换模型、替换动作、标签浏览、模型行点击 | 资源库操作 | 资源库核心、统一动作注册表 — 菜单/NL/快捷键共享真相源、NL 意图解析 — LLM 文本 → 动作执行 |
| 资源库核心、资源浏览层级、网格视图、缩略图流式加载、资源管理核心 | 资源库核心 | 资源库操作、环境状态防抖持久化、时间流转与太阳角系统 |
| 资源库初始化、资源库设置、资源库启动 | 资源库初始化 | 安卓文件访问（shared 模式） |
| 模型库、资源库、模型浏览、加载模型、library | 资源库入口与编排 | 统一资源加载队列 |
| 个人灯光、灯光跟随、跟随聚光灯 | 个人灯光跟随 | 灯光预设系统、场景光照与阴影（barrel）、模型生命周期操作 |
| 灯光预设、预设灯光、灯光配置 | 灯光预设系统 | 个人灯光跟随、场景光照与阴影（barrel）、模型生命周期操作 |
| 场景光照、方向光/半球光、灯光状态、灯光补间 | 场景光照与阴影（barrel） | 环境灯光包装、EnvState 单一源 Schema、个人灯光跟随 |
| 口型同步、lipsync、音频驱动口型 | 口型同步桥 | 程序化动作系统 |
| 模型加载、动作加载、道具加载、音频加载、加载排队、加载进度、loadId | 统一资源加载队列 | 资源库操作、资源库核心、资源库入口与编排 |
| 加载后刷新、库扫描完成、菜单刷新、注册表 | 模型加载/库扫描完成后菜单刷新注册表 | — |
| 语言切换、国际化、locale | 国际化语言状态 | 应用启动引导 |
| 材质系统、分类材质、材质参数调节、材质状态管理 | 分类材质系统 | — |
| 菜单 overlay、弹窗 wrapper、关闭所有浮层 | 菜单 Overlay 与 Wrapper 管理 | 菜单栈共享指针（stackRegistry）、基础行控件构建器 |
| 菜单声明、控件配置、状态绑定、菜单节点 | 声明式菜单 Schema | 菜单渲染引擎 |
| 菜单栈、modelStack、buildLevel、跨菜单导航 | 菜单栈共享指针（stackRegistry） | 菜单 Overlay 与 Wrapper 管理、基础行控件构建器 |
| 菜单引擎、SlideMenu、弹窗菜单 | 滑出式菜单引擎（SlideMenu） | 环境弹窗（编排 + barrel）、动作绑定 UI、动作模块注册表 |
| babylon-mmd、MmdRuntime、骨骼矩阵、动作切换、音频、ADR-192 | babylon-mmd 适配边界 | 场景光照与阴影（barrel）、动作菜单层级系统、感知层主控 |
| 模型加载、PMX 解析、缩略图捕获 | PMX 模型加载与缩略图捕获 | Go 模型库扫描、GPU 压缩纹理能力探测、资源库操作 |
| 模型注册表、模型生命周期、模型属性、物理分类 | 模型注册表与生命周期管理 | 场景序列化与自动保存、骨骼覆盖核心 API、模型生命周期操作 |
| 删除模型、聚焦模型、模型变换（位置/旋转/缩放）、VPD 姿态应用 | 模型生命周期操作 | 场景序列化与自动保存、场景核心编排器（纯组装器）、骨骼覆盖核心 API |
| 模型预设、动作预设、预设管理、预设面板 | 模型预设管理 UI | Go 预设持久化与标签、场景序列化与自动保存 |
| 动作绑定 UI、动作槽位管理、模块切换列表 | 动作绑定 UI | 滑出式菜单引擎（SlideMenu）、PMX 模型加载与缩略图捕获、模型生命周期操作 |
| 动作详情、图层管理、播放速度 | 动作详情 UI | PMX 模型加载与缩略图捕获、模型生命周期操作、动作绑定 UI |
| 脚部跟随、脚 IK、地面高度、脚部调整引擎 | 脚部地面跟随（MMD-native IK） | 音频总线、环境状态防抖持久化、时间流转与太阳角系统 |
| 动作历史、撤销、重做、动作记录 | 动作历史管理 | — |
| 动作意图、多主动作、动作库、动作广播、默认动作、场景动作 | 场景级动作意图库 | 场景序列化与自动保存、PMX 模型加载与缩略图捕获、模型生命周期操作 |
| 动作菜单、动作层级、感知面板、程序化动作面板 | 动作菜单层级系统 | babylon-mmd 适配边界、感知层主控、场景序列化与自动保存 |
| 动作模块基类、module base、模块骨架、模块创建、帧钩子管理 | 动作模块基类 | 骨骼覆盖核心 API、场景序列化与自动保存、模型注册表与生命周期管理 |
| 动作模块、模块注册、动作扩展、动作管线扩展 | 动作模块注册表 | 骨骼覆盖核心 API、滑出式菜单引擎（SlideMenu）、模型生命周期操作 |
| 动作管线、逐帧合成、骨骼写入顺序、PipelineStage / PipelineLayer | 动作管线（逐帧合成） | 骨骼覆盖核心 API、模型生命周期操作、动作模块基类 |
| 播放进度 UI、seek 拖动、自动循环播放、MMD runtime 回调、时间格式、播放控制栏 | 动作播放控制 | 时间流转与太阳角系统、设置共享工具 |
| 轨道相机键盘、WSAD 环绕控制、相机键位、orbit input | 轨道相机键盘输入状态叶子 | 模型注册表与生命周期管理、模型生命周期操作、场景序列化与自动保存 |
| 换装叠加层 | 换装叠加层 | 换装系统 |
| 换装加载/应用/重置 | 换装系统 | 换装叠加层 |
| 感知层、视线追踪、眨眼、呼吸、重心微动、感知上下文 | 感知层主控 | 场景序列化与自动保存、babylon-mmd 适配边界、动作菜单层级系统 |
| FPS 监控、自动降级、性能模式、RenderBridge | 性能监控与自动降级 | — |
| 物理桥、骨骼读取、每帧更新注册表 | 物理骨骼桥与每帧注册表 | 虚拟裙骨物理控制器（ADR-084 Phase 2-3） |
| 广场状态、Plaza 状态、广场关闭、广场站点、广场层级 | 广场状态管理 | — |
| 程序化动作、idle 动作、auto dance、节拍联动、动作生成、程序化 VMD | 程序化动作系统 | 口型同步桥、多 VMD 叠加系统 |
| 渲染循环、FPS 时钟、硬件缩放、渲染启停 | 渲染循环与 FPS 时钟 | 事件处理与导航系统、应用启动引导 |
| 菜单渲染、schema 渲染、控件渲染、数据绑定 | 菜单渲染引擎 | 声明式菜单 Schema |
| 渲染管线、后处理、tone mapping、SSR / SSAO | 场景渲染管线与后处理 | Go 模型库扫描、GPU 压缩纹理能力探测、PMX 模型加载与缩略图捕获 |
| 资源加载失败、纹理缺失、警告汇总、toast 提示 | 资源加载失败统一汇总 | — |
| runtime bridge、Wails events、跨平台事件、runtime-bridge | Runtime 隔离桥（Wails Events/Browser） | 应用启动引导 |
| 运行模式、桌面模式、浏览器模式、环境检测 | 运行模式检测 | 应用启动引导、内置 AI 诊断助手 — 双适配器服务层、后端适配层 |
| 场景弹窗、场景菜单、场景设置入口、场景路由 | 场景弹窗（编排 + 路由） | 环境弹窗（编排 + barrel）、统一动作注册表 — 菜单/NL/快捷键共享真相源、NL 意图解析 — LLM 文本 → 动作执行 |
| 场景序列化、场景保存、场景恢复、撤销/重做 | 场景序列化与自动保存 | 模型生命周期操作、场景核心编排器（纯组装器）、骨骼覆盖核心 API |
| 场景初始化、场景编排、场景生命周期 | 场景核心编排器（纯组装器） | 场景序列化与自动保存、应用启动引导、模型生命周期操作 |
| 设置共享、设置工具、UI 主题应用、字节格式化、设置默认值 | 设置共享工具 | 时间流转与太阳角系统、环境状态防抖持久化、资源库核心 |
| 设置页、设置路由、设置编排 | 设置页路由与编排 | 设置共享工具 |
| 快捷键、快捷键注册、键盘绑定 | 快捷键注册表 | — |
| 次表面散射材质 | SSS PBR 材质 | — |
| 全局状态、场景状态、播放控制状态、资源库状态、scene-state / playback-state / library-state | 全局状态与场景运行时 Store | EnvState 单一源 Schema |
| 变换适配、transform adapter、双模态、拖拽适配 | 变换适配器注册表（双模态去重） | 场景序列化与自动保存、骨骼覆盖核心 API、模型注册表与生命周期管理 |
| 变换模式、拖拽模式、位移旋转、transform mode | 拖拽变换模式开关 | — |
| 选中状态、选中物、变换选择、selection 状态 | 变换选中物状态源 | 场景核心编排器（纯组装器） |
| 键盘导航、列表导航、箭头键导航 | 键盘导航工具 | Go 后端核心（App 生命周期 + 配置系统）、应用启动引导 |
| 行控件、滑块行、开关行、模式行、骨骼选择行、危险操作行、信息卡 | 基础行控件构建器 | 时间流转与太阳角系统、菜单 Overlay 与 Wrapper 管理、菜单栈共享指针（stackRegistry） |
| 虚拟裙骨、物理裙摆、Bullet 弹簧链、skirt analyzer | 虚拟裙骨物理控制器（ADR-084 Phase 2-3） | 骨骼覆盖存储（多模块仲裁）、物理骨骼桥与每帧注册表 |
| 多层动作、动作叠加、VMD 混合、composite animation、动作图层、动作优先级 | 多 VMD 叠加系统 | 程序化动作系统、VMD 动作加载器 |
| VMD 加载、动作文件导入、伴音自动加载、动作时长、文件格式校验、动作播放开始 | VMD 动作加载器 | 环境状态防抖持久化、时间流转与太阳角系统、统一文件服务层 |
| 后端绑定、后端代理、resolveBackend、Wails bindings | 后端绑定聚合层（backend 代理化） | 内置 AI 诊断助手 — 双适配器服务层、后端适配层、环境状态防抖持久化 |
| 风力物理、风力注入、头发/裙子物理 | 风力物理注入（WASM Bullet） | 安卓文件访问（shared 模式）、场景光照与阴影（barrel）、babylon-mmd 适配边界 |
标准执行模板
text
先按 docs/knowledge/routes.md 判断首选知识卡。
读取 docs/knowledge/README.md 和首选卡片，再按 source_files 阅读源码。
grep docs/adr/ 查找相关决策和状态，检查 symbols、invariants、tests、use_when。
以源码为最终事实来源；如果卡片过时，先报告漂移，再决定是否同步更新。
修改后运行最小相关测试和 npm run check:docs。维护规则
- 本文件自动生成，请勿手改；重跑
npm run gen:routes重新生成。 - 新增/修改知识卡：更新 frontmatter 的
use_when（意图关键词）与adr（关联决策）后重跑即可自动入列。 use_when为空或不含关键词的卡不会出现在路由表（但仍可经索引/关联图抵达）。