MimirFW 静态分析：模块设计与工作原理

对象：Plumess/MimirFW（AGPL-3.0）· 方法：纯静态分析仓库状态：单次 Initial commit（6feb260，浅克隆 grafted），仅 9 个被跟踪文件，全部为文档/配置，零源代码

1. 总体架构

先给出「代码里实际存在的东西」，再给出 README 宣称的目标架构——两者目前是两条平行线。

实际存在的仓库结构（git ls-tree -r HEAD，共 9 个文件）：

mimirfw/
├── README.md           # 主文档（181 行，愿景/定位/规划）
├── LICENSE             # AGPL-3.0 全文（35182 字节）
├── .gitignore          # 透露预期技术栈（见 §3.5）
├── .dockerignore       # 同上
├── .gitattributes      # 仅 LF 归一化
├── api/README.md       # 5 行占位（"架构设计"标题，正文为空）
├── dev/README.md       # 83 行，描述不存在的脚本/工具
├── docker/README.md    # 54 行，描述不存在的部署文件
└── web/README.md       # 5 行占位（"交互设计"标题，正文为空）

README 宣称的目标架构（README.md:20-29 + 全部 🚧"规划中"）：

┌────────────────────────────────────────────────────┐
│  前端：网页/移动网页 · APP(🚧) · 小程序(🚧) · QQBot(优先) │
└───────────────────────┬────────────────────────────┘
                        ▼
               🎮 Mimir 核心引擎   ← （无任何代码）
                        ▼
        本地推理(vLLM/GPU集群) 或  云 API(多厂商聚合)  ← （无任何代码）
                        ▼
          RAG 私有知识库 / 游戏模板 / 插件系统  ← （全部 🚧）

结论先行：这是一个「README 已写好、代码未动工」的早期项目。所有架构图来自 README.md 的 mermaid 描述与 🚧 标记，没有一行实现代码可佐证。

2. 核心工作流

无可运行链路。 仓库不含任何 .py、.js/.ts、Dockerfile、docker-compose*.yaml、pyproject.toml、package.json、requirements.txt。README 的「快速开始」直接是占位符：

# 单节点 Docker 启动 ...    (README.md:163)
pass
# GPU 集群 Helm 启动 ...    (README.md:165)
pass

唯一「可执行」的东西是 dev/README.md:12-25 描述的命令（uv sync --dev、./start-api、./start-worker），但对应脚本 start-api、start-worker 均不存在于仓库——属于「计划中的工作流」，未实现。

3. 模块逐一分析

3.1 根目录 `README.md`（181 行）—— 唯一有实质内容的文件

职责	关键内容（文件:行号）
项目定位	「基于 LLM 的对话游戏搭建框架，支持 DND/狼人杀/文游」README.md:6
核心口号	「如同乐高积木般的智能体 NPC」（README.md:10）
能力诉求	人物预设/世界背景/进度回溯/插图生成 + 低代码 + 易部署多平台（README.md:14-16）
多用户身份	服务供应商/创作者/玩家三类（README.md:31-157）
技术方案	vLLM、K8s、RAG、多厂商 API 聚合、插件沙箱等——全部为规划（README.md:56-131）
快速开始	`pass` 占位（README.md:161-166）
许可	AGPLv3 + 盈利方式说明（README.md:168-178）

工作原理：纯文档，无代码逻辑。

3.2 `api/README.md`（5 行）

全文仅标题「MimirFW 后端 API —— 本文档描述了后端 API 的架构设计」，正文空。无 Flask 应用、无路由、无模型层代码。

3.3 `web/README.md`（5 行）

同上，仅「前端交互设计」占位。无 Next.js 组件、无页面代码。

3.4 `dev/README.md`（83 行）—— 描述的工具全部不存在

宣称存在的脚本（dev/README.md:30-48）：start-api（Flask 热重载）、start-worker（Celery）、reformat（Ruff）、mypy-check、update-uv/sync-uv、pytest/*.sh（含 pytest_model_runtime.sh、pytest_workflow.sh、pytest_vdb.sh）。经 git ls-tree 与目录列举核实，上述脚本均未提交。这是唯一能推断后端技术栈的文件：Python + Flask + Celery + uv + Ruff + MyPy + pytest + testcontainers + Weaviate（向量库）。

3.5 `docker/README.md`（54 行）+ `.gitignore`/`.dockerignore` —— 推断的部署形态

docker/README.md:31-34 描述 .env.example、docker-compose-template.yaml、docker-compose.middleware.yaml、generate_docker_compose——均不存在。其中提到 --profile weaviate（docker/README.md:23），确认计划用 Weaviate 做向量数据库。
.gitignore 暴露完整预期栈：Python 生态（__pycache__/*.py[cod]/.ruff_cache/.mypy_cache，行 17-33）、Next.js 前端（.next//out/，行 38-39）、SQLite/Redis（*.sqlite*/*.rdb/*.aof，行 49-51）、本地模型权重（*.gguf/*.ggml/*.safetensors/*.onnx，行 59-64）。

4. 数据模型

未实现/未读到。 无 ORM 模型、无 SQL 建表语句、无 JSON Schema、无配置文件。可依据文档推断的「计划数据实体」仅有 README 里的概念（人物预设、世界背景设定、游戏模板、NPC），无任何字段级定义。

5. 与 Z.R.I.C 功能对照表

判定口径：以代码是否真实存在为准，README 文字宣称一律视为「未实现」。

Z.R.I.C 功能	MimirFW 状态	依据
剧本解析	❌ 未实现	无剧本格式/解析代码
推演分支	❌ 未实现	仅「进度回溯」愿景（README.md:14）
自动判定	❌ 未实现	无任何判定逻辑代码
世界状态	❌ 未实现	无状态存储代码
NPC 情绪记忆	❌ 未实现	仅「智能化 NPC/智能体 NPC」口号（README.md:6,10）
地图	❌ 未实现	未读到任何地图概念
触发器	❌ 未实现	未读到
时间线	❌ 未实现	「进度回溯」仅口号，无实现
记忆系统	❌ 未实现	仅提 RAG（README.md:77），无代码
本地模型	⚠️ 仅规划	README 提 vLLM/本地推理（README.md:57,106）；`.gitignore` 预留 gguf/onnx 等权重忽略规则
许可	✅ 已落实	`LICENSE` 为 AGPL-3.0 全文，README.md:168-178 补充盈利条款

对照结论：11 项中 10 项「未实现」，1 项「仅规划」，仅「许可」1 项落实。MimirFW 在 Z.R.I.C 能力维度上目前是空集。

6. 三个重点问题的答案

游戏类型如何「配置化」（DND/狼人杀/文游的抽象层）：不存在。 README 仅承诺「预设多套游戏模板和前端皮肤模板（🚧规划中）」（README.md:79）与「低代码设计游戏」（README.md:144），无任何抽象层、配置格式、模板文件或插件接口代码。
NPC 智能体构建：不存在。 「乐高积木般的智能体 NPC」（README.md:10）是宣传语，无 agent 类、无 persona/情绪/记忆实现。
LLM 调用方式：不存在可读代码。 唯一技术线索：README 规划「本地推理（vLLM）/ 云 API（多厂商聚合、智能路由）」（README.md:56-63）与「RAG 管理私有知识库」（README.md:77）；.gitignore 预留模型权重文件类型。无任何 LLM 客户端、协议、降级策略代码。

7. 设计评价

优点（架构思路层面，非代码层面）

定位清晰、需求分层合理：把「服务供应商 / 创作者 / 玩家」三类用户的需求分别用 mermaid 决策图拆解（README.md:31-157），这是很多同类项目缺失的产品思考。
明确的「确定性/生成性」意图：口号「开发者提供基础模块，用户自由拼装游戏」指向模块化、可配置方向，与 loreweaver、Z.R.I.C 的「结构化生成」路线同向（但停留在口号）。
许可策略诚实：AGPLv3 且 README 主动说明「云服务商须开源、可通过 API 计费/闭源插件盈利」（README.md:172-177）——比无许可或含糊许可规范。
工程栈选择合理（若落地）：Flask+Celery+uv+Ruff+MyPy+pytest+Weaviate+Next.js 是成熟组合，.gitignore 对模型权重/向量库/测试的忽略规则写得规范。

缺陷（代码依据明确）

零实现：git ls-tree 仅 9 个文件，全部文档/配置，无一行产品代码——与 README 宣称的「MVP 开发中」存在巨大落差（README badge 自标 Status: MVP_Development，README.md:4）。
文档相互引用不存在之物：dev/README.md 描述 start-api 等脚本、docker/README.md 描述 docker-compose-template.yaml 等文件，实际均未提交，读者照文档操作会直接失败。
占位符裸露：README 快速开始直接 pass（README.md:163,165），无任何可运行路径。
「MVP 开发中」与实际不符：按 README badge，项目应已进入 MVP 阶段，但仓库仅有文档骨架，MVP 代码未公开或尚未开始。

差距总结

README 宣称的「框架、低代码、多平台、RAG、vLLM、插件生态」与其代码现状（空仓库）之间是100% 的宣称-实现鸿沟。若将其当作「架构设计书」阅读有参考价值；若当作「可运行框架」则完全不成立。

8. 结论

它是什么：一份愿景完整、实现为空的文档仓库——本质是「项目白皮书 + 目录占位」，其价值在于产品定位（对话类游戏的多角色身份拆解）与预期技术栈（Flask/Celery/Next.js/Weaviate/vLLM/RAG），而非任何可运行能力。
它不是什么：不是框架、不是 MVP、不是可运行系统——没有引擎、没有 NPC 智能体、没有 LLM 调用、没有配置化游戏抽象，Z.R.I.C 能力对照表除「许可」外全为空。
对后续分析的提示：建议在清单中标记为「文档占位仓库（无实现代码）」，其可借鉴内容仅为 README 的产品与架构设想，不构成任何代码级参考。