马库斯AI框架

[center][size=6][color=#55C7FF][b]MARCUS AI 框架[/b][/color][/size]
[size=4][color=#DDE8FF][b]面向《霸主》子 Mod 的受治理 AI 基础框架[/b][/color][/size]

[color=#9FB2D0]公共扩展 API | 安全游戏数据查询 | 受治理命令 | AI / RAG / 存储 / 媒体[/color]

[size=4][color=#43D39E][b]一句话概括[/b][/color][/size]
[b]一个共享基础设施层，让独立编译的《霸主》Mod 能够添加受治理的 AI 功能，而无需从头重建权限、游戏数据访问、提供商连接、存储、RAG、媒体和诊断系统。[/b]

[color=#55C7FF][b]《霸主》v1.4.8[/b][/color] | [color=#A77BFF][b]《霸主》v1.3.15[/b][/color] | [color=#43D39E][b]英语 + 简体中文[/b][/color] | [color=#FFCC66][b]预览版 0.1.0[/b][/color][/center]

[line]

[size=5][color=#55C7FF][b]此框架是什么[/b][/color][/size]

Marcus AI 框架是面向[b]独立编译的 AI 功能子 Mod[/b]的基础设施。它在子 Mod、《霸主》游戏进程以及内置的本地 Companion 服务之间提供稳定的公共契约。

[color=#FFCC66][b]重要提示：[/b][/color]此框架本身[b]不是[/b]一个 NPC 外交、关系、对话或剧情 Mod。它不会自行改变你的战役。面向玩家的 AI 行为仅在已安装的子 Mod 请求框架能力时才会出现。

[quote][b]子 Mod[/b] 请求受治理的能力 -> [b]核心宿主[/b] 检查身份、权限、会话和风险 -> [b]内置 Companion[/b] 可选地执行提供商、数据库、RAG 或媒体工作 -> 框架返回类型化的、有界的结果。[/quote]
[size=5][color=#A77BFF][b]核心功能[/b][/color][/size]

[list]
[][b]独立扩展注册[/b] - 子 Mod 通过稳定的公共 API 进行注册，无需复制框架内部实现。[/]
[][b]版本化能力代理[/b] - 跨 Mod 调用使用能力 URI 和类型化错误，而非反射技巧。[/]
[][b]PlayerKnown 数据查询[/b] - 扩展接收有界的只读 DTO，而非实时的 TaleWorlds 对象。[/]
[][b]权限治理[/b] - 声明不等于授权；敏感路由在玩家许可之前保持默认拒绝。[/]
[][b]受治理命令[/b] - R1/R2 操作会经过检查并重新验证；R3 需要玩家一次性批准。[/]
[][b]AI 网关[/b] - 逻辑路由、提供商回退、模型固定、幂等性、结构化输出和云导出门控。[/]
[][b]提供商支持[/b] - OpenAI 兼容、Anthropic、Ollama、Player2、ComfyUI 和 Managed GGUF 适配器。[/]
[][b]提示词与工具契约[/b] - 有界上下文提供程序、提示词注册表、结构化输出和工具候选验证。[/]
[][b]存储与时间线服务[/b] - 隔离的 KV/SQL 视图、战役/时间线边界、导出/导入和协调。[/]
[][b]SQLite FTS5 RAG[/b] - 作用域集合、语料指纹和有界检索结果。[/]
[][b]资产与媒体服务[/b] - 不透明的内容寻址句柄、图像/TTS 契约和引用安全清理。[/]
[][b]诊断与安全控制[/b] - 扩展状态、权限、任务、命令、资产、错误和紧急停止。[/]
[][b]单一模块，两种语言[/b] - 英语和简体中文一同发布并跟随游戏语言。[/]
[/list]
[size=5][color=#43D39E][b]自动 COMPANION + 游戏内配置[/b][/color][/size]

[quote][color=#43D39E][b]无需单独下载 Companion。无需安装脚本。无需保持控制台窗口打开。[/b][/color]

Companion 已包含在 [b]MarcusAIFramework/Companion/[/b] 下。主 Mod 会静默启动它，通过当前用户的私有命名管道连接，并复用现有的兼容实例而非启动重复实例。由游戏启动的 Companion 会监视《霸主》进程并在游戏关闭后退出。宿主关闭不会重启配置会话。[/quote]
[list]
[]HTTP、SQLite、模型、RAG、图像和 TTS 工作均在《霸主》进程之外进行。[/]
[]如果 Companion 启动失败，框架会安全降级而非阻止游戏加载。[/]
[]配置文件在游戏重启后持久保留，因此常规设置无需每次会话重新输入。[/]
[]高级的 [b]setup[/b]、[b]manage[/b] 和配置文件命令仅保留为开发者/恢复工具。[/]
[/list]
[size=5][color=#55C7FF][b]玩家快速设置[/b][/color][/size]

[color=#55C7FF][size=4][b]1. 安装正确的完整框架包[/b][/size][/color]
[list]
[]选择与你确切的《霸主》API 匹配的包：[b]v1.4.8[/b] 或 [b]v1.3.15[/b]。[/]
[]将 [b]Modules/MarcusAIFramework[/b] 解压到《霸主》游戏文件夹中。[/]
[][color=#FF6B7A][b]切勿混用两个游戏版本包中的文件。[/b][/color][/]
[]在启动器中启用所需依赖项和 Marcus AI 框架，然后正常启动游戏。[/]
[/list]
[color=#A77BFF][size=4][b]2. 在 MCM 中配置你的 LLM[/b][/size][/color]
[list=1]
[]打开 [b]MCM -> Marcus AI 框架 -> 01 Companion[/b]。[/]
[]选择 Ollama、OpenAI、Anthropic 或 OpenAI 兼容。[/]
[]输入确切的 API Base URL 和模型 ID。Ollama 可将 URL 留空以使用 [b]http://127.0.0.1:11434[/b]，且无需 API 密钥。[/]
[]从每个已安装子 Mod 的文档中复制确切的 [b]Route ID[/b]。多个 Route ID 之间用英文逗号分隔。[/]
[]对于需要身份验证的服务，选择 [b]Set / replace key[/b]，在游戏内掩码询问框中输入密钥，然后选择 [b]Save to Companion[/b]。[/]
[]云提供商还需要 [b]global cloud export[/b] 以及匹配的子 Mod 路由权限。[/]
[/list]
[color=#FFCC66][b]Route ID 不是模型名称。[/b][/color]不要猜测它。请使用子 Mod 作者发布的确切 ID。

[size=5][color=#43D39E][b]下载指南 - 各文件的作用[/b][/color][/size]

[color=#55C7FF][size=4][b]1. MarcusAIFramework v1.4.8 受保护 ZIP - v1.4.8 必需[/b][/size][/color]
[list]
[]仅与《霸主》v1.4.8 配合使用。[/]
[]包含受保护的核心宿主、公共 API、双语资源、诊断界面以及带运行时依赖的内置 Companion。[/]
[]SHA-256：[b]E089F15657D7A4A5F2B9D25ABA280535E4BBB0D70C4A615C6535386DF4873EFA[/b][/]
[/list]
[color=#A77BFF][size=4][b]2. MarcusAIFramework v1.3.15 受保护 ZIP - v1.3.15 必需[/b][/size][/color]
[list]
[]仅与《霸主》v1.3.15 配合使用。[/]
[]包含受保护的核心宿主、公共 API、双语资源、诊断界面以及相同的版本中立内置 Companion。[/]
[]SHA-256：[b]9F481ECBD9DB999EF3F67A879B280FEE80BBFDF3E9A1E30E70F0C3C5DD8500C5[/b][/]
[/list]
[color=#43D39E][size=4][b]3. MarcusAIFramework 开发者工具包 - 面向子 MOD 作者[/b][/size][/color]
[list]
[][b]SDK/ref[/b] 下的双版本编译时引用 DLL。[/]
[]公共 XML 文档、API 清单、JSON 架构、双语扩展示例模板、FakeHost、断言和警告级 linter。[/]
[]框架开发者文档、兼容性说明、设计蓝图以及 [b]marcus-ai-framework-extension-developer[/b] Codex 技能。[/]
[]普通玩家不需要此下载。[/]
[/list]
[color=#FFCC66][size=4][b]4. ReferenceExtension 和 CapabilityFixtureExtension - 可选验证 MOD[/b][/size][/color]
[list]
[]ReferenceExtension 演示公共框架 API。[/]
[]CapabilityFixtureExtension 验证最小化的跨 Mod 能力流程。[/]
[]它们是开发者示例和验收夹具，而非必需的玩家内容。[/]
[/list]
[size=5][color=#A77BFF][b]API 密钥与隐私[/b][/color][/size]

[list]
[]API 密钥[b]不[/b]存储在 MCM JSON、《霸主》存档或 platform.db 中。[/]
[]内置 Companion 使用 DPAPI 在 [b]credentials.dpapi[/b] 中为当前 Windows 用户保护凭据。[/]
[]密钥绝不会通过框架 UI 或管理响应回显。[/]
[]本地连接必须使用明确的回环地址，且重定向被禁用。[/]
[]云流量保持默认拒绝，直到全局门控、路由策略和连接分类全部允许。[/]
[]切勿将你的 API 密钥发送给 Mod 作者，或粘贴到导出的配置文件或诊断报告中。[/]
[/list]
[size=5][color=#FFCC66][b]安全模型[/b][/color][/size]

[list]
[][b]R0[/b] - 只读查询。[/]
[][b]R1[/b] - 低风险准备和通知。[/]
[][b]R2[/b] - 有界的游戏玩法变更，需权限和执行的重新验证。[/]
[][b]R3[/b] - 需要玩家一次性批准的战略性或不可逆操作。[/]
[]紧急暂停会拒绝新的 AI/媒体任务，但不会禁用只读查询。[/]
[]诊断信息省略 API 密钥、Authorization 头、完整提示词/响应、数据库主体和文件系统路径。[/]
[/list]
[size=5][color=#55C7FF][b]系统需求[/b][/color][/size]

[list]
[]《骑马与砍杀 II：霸主》[b]v1.4.8[/b] 或 [b]v1.3.15[/b]，使用匹配的包。[/]
[]Harmony。[/]
[]ButterLib。[/]
[]UIExtenderEx。[/]
[]Mod Configuration Menu v5。[/]
[]需要消费 Marcus AI 框架的子 Mod 才能实现面向玩家的 AI 行为。[/]
[/list]
[size=5][color=#43D39E][b]当前验证状态[/b][/color][/size]

[list]
[]核心 v1.4.8 和 v1.3.15 严格 Release 构建：[color=#43D39E][b]通过，0 警告，0 错误[/b][/color]。[/]
[]Companion Release 与协议回归测试套件：[color=#43D39E][b]通过[/b][/color]，包括 MCM 配置 IPC、DPAPI 凭据保存/清除、无密钥回显、提供商默认值、持久化和现有实例检测。[/]
[]两个受保护核心 DLL 均保留了全部 116 个公共 API 类型和成员以及 SubModule、MCM、Gauntlet、存档行为和扩展入口契约。[/]
[]两个集成 ZIP 包含 54 个运行时文件，并通过了允许列表、XML、本地化、正斜杠 ZIP 路径、重复条目和提取文件 SHA-256 验证。[/]
[]英语和简体中文本地化各包含 97 个键，无缺失、重复、空值或占位符不匹配的条目。[/]
[/list]
[color=#FFCC66][b]证据边界：[/b][/color]这些是静态、构建、保护、协议和包契约的结果。当前版本在本次验证运行中[b]尚未[/b]部署或启动游戏，实际提供商及游戏内英语/中文冒烟测试仍有待执行。

[line]

[center][size=4][color=#55C7FF][b]构建 AI 功能。保持权限受治理。[/b][/color][/size]
[color=#9FB2D0]Marcus AI 框架 | 预览版 0.1.0 | 《霸主》v1.4.8 / v1.3.15[/color][/center]