LocalAI Assistant MCP 安全规则全解读：prompts/10_safety.md 的五条护栏如何守护服务器
LocalAI Assistant MCP 安全规则全解读prompts/10_safety.md 的五条护栏如何守护服务器【免费下载链接】LocalAILocalAI is the open-source AI engine. Run any model - LLMs, vision, voice, image, video - on any hardware. No GPU required.项目地址: https://gitcode.com/GitHub_Trending/lo/LocalAI本文围绕仓库中 pkg/mcp/localaitools/prompts/10_safety.md 这份Safety rules系统提示文档展开。它服务于 LocalAI 的 MCP 管理助手LocalAI Assistant——一个运行在 LocalAI 实例内部、可通过自然语言安装/删除模型、管理后端、修改模型配置的管理 Agent。该文档定义了 Agent 的五条不可协商的安全规则变更前确认、变更前消歧、错误逐字转述、绝不虚构标识符、有界轮询是理解整个 MCP 管理面安全设计的第一手资料。读完本文你将掌握这套规则的每一条细节、它们在源码与测试中的落实方式以及在实际对话中正确使用 LocalAI Assistant 的交互范式。背景LocalAI Assistant 与其 MCP 管理面LocalAI Assistant 是一个以 Model Context ProtocolMCP形式暴露 LocalAI 管理能力的助手。从 pkg/mcp/localaitools/doc.go 的包注释可以确认其两种接入方式进程内in-process由聊天处理器接入当管理员将会话切换为 LocalAI Assistant 模态时MCP 服务器通过成对的进程内内存传输net.Pipe()接入会话LocalAIClient由inproc子包实现直接调用 LocalAI 内部服务进程外out-of-process通过独立的local-ai mcp-server子命令运行基于 stdio 使用 MCP 协议httpapi子包负责通过 HTTP 访问远程 LocalAI 实例。关键在于 pkg/mcp/localaitools/prompts/00_role.md 中的一句定位You are runninginsidethe very LocalAI instance you administer. Tool calls take effect on this server immediately.也就是说Agent 与它管理的服务器运行在同一个实例中每一次工具调用都会立即对该服务器产生实际作用。这正是安全规则文档存在的前提用户管理员信任 Agent 在不造成意外变更的前提下操作服务器因此必须给 Agent 加上严格的行动边界。同文档还要求 Agent 保持简洁、多用要点列表、在罗列选项时用数字编号方便用户按序号选择——这与 10_safety.md 中消歧时给出编号列表的要求是呼应的。安全文档在系统提示中的装配机制10_safety.md并不是一份孤立的散落文档而是 LocalAI Assistant 每轮对话都会看到的系统提示组成部分。pkg/mcp/localaitools/prompts.go 通过//go:embed prompts/*.md prompts/skills/*.md将prompts/目录下全部 Markdown 文件编译进二进制SystemPrompt()函数按字典序遍历嵌入式文件系统为每个文件生成形如以下的片段!-- file: prompts/10_safety.md -- # section: 10_safety # Safety rules These rules are non-negotiable. ...其中!-- file: ... --头用于追踪溯源模型引用的是哪份 skill# section: basename标题让模型能区分不同来源的指令。整个提示按00_role→10_safety→20_tools的顺序排列紧跟在角色定义之后的正是本安全规则。pkg/mcp/localaitools/prompts_test.go 中名为 contains the safety anchors that the LLM relies on 的测试断言系统提示必须包含LocalAI Assistant、Confirm before mutating、Surface tool errors verbatim、install_model、delete_model等关键锚点目的就是防止安全规则被意外删除。因此10_safety.md中的每条规则都相当于随每次模型调用内置进上下文的硬约束。工具目录只读与变更mutating的分类要理解安全规则先要理解规则约束的对象。10_safety.md开头即声明这些规则不可协商non-negotiable并把需要确认的工具全部点名列出。完整的工具编目见 pkg/mcp/localaitools/prompts/20_tools.md它把工具分为两大类只读工具Read-onlygallery_search、list_installed_models、list_galleries、list_backends、list_known_backends、get_job_status、get_model_config、vram_estimate、system_info、list_nodes、list_scheduling、get_scheduling、list_voice_profiles、get_branding、get_usage_stats、get_pii_events、get_middleware_status、get_router_decisions、get_router_corpus_stats、list_aliases等。它们只读取状态可随时调用变更工具Mutating会改变服务器状态受安全规则 1 的确认约束。这一分类在源码中同样可见。pkg/mcp/localaitools/tools.go 用常量集中定义了所有工具名pkg/mcp/localaitools/tools.go 中的mutatingToolNames切片即确认规则必须覆盖的变更工具全集并注明注册仍按功能分组由prompts_test.go机械地保证每个会改变状态的工具都出现在确认规则中。五条安全规则逐条精解以下内容完整继承自 pkg/mcp/localaitools/prompts/10_safety.md并结合源码展开。规则 1变更前必须确认Confirm before mutating规则原文要求在调用任何变更工具之前先以通俗语言说明即将做什么哪个工具、哪个目标、哪些参数并在下一轮等待用户明确确认。只有Yes、do it、go ahead、proceed这类表述才计为确认其他任何说法都不算。需要确认的 19 个工具完整清单如下领域工具模型 / Galleryinstall_model、import_model_uri、delete_model、edit_model_config、reload_models、load_model后端install_backend、upgrade_backend模型状态toggle_model_state、toggle_model_pinned品牌 / 别名set_branding、set_alias路由语料库seed_router_corpus、clear_router_corpus声音克隆档案create_voice_profile、delete_voice_profile分布式调度set_node_vram_budget、set_scheduling、delete_scheduling这条规则的技术意义可以结合工具语义理解。例如load_model预加载模型入内存消除首次请求的冷启动延迟与toggle_model_state/toggle_model_pinned启用/禁用、固定/取消固定模型直接影响当前运行态create_voice_profile会保存一份已确认同意克隆的 PCM-WAV 参考音频与精确转写文本属于敏感数据写入set_node_vram_budget、set_scheduling、delete_scheduling则改变分布式节点的资源分配与调度策略。任何一个误触都可能造成服务不可用或数据被覆盖因此一律要求先确认再执行。测试层面的兜底见 pkg/mcp/localaitools/prompts_test.gonames every mutating tool in the confirmation safety rule逐一比对mutatingToolNames与10_safety.md原文确保提示文档里的名单与代码里的常量名单不会因重构而失同步。规则 2变更前先消歧Disambiguate before mutating当用户请求存在歧义时例如多个 gallery 条目都能匹配、同一模型名存在多个已安装版本、后端存在多种变体Agent不得直接调用变更工具而应将候选以编号列表呈现请用户选择后再执行。从 pkg/mcp/localaitools/dto.go 可以看到一个典型的歧义场景import_model_uri的响应结构包含AmbiguousBackend bool与BackendCandidates []string——当 URI 同时可被多个后端解析时工具会返回ambiguous_backendtrue此时 Agent 必须把候选呈现给用户并在用户指定后以BackendPreference字段如llama-cpp二次调用。另一个场景是install_model的variant参数pkg/mcp/localaitools/dto.go 的 jsonschema 说明指出默认应留空以让 LocalAI 依据本机引擎与内存自动选择可运行的构建只有用户明确点名某个量化版本如 the Q8 one时才传入且名称必须与条目变体列表完全一致。这与 pkg/mcp/localaitools/prompts/skills/install_chat_model.md 中的第 25 步形成一致流程先gallery_search→ 以名称、gallery、简介、许可证的编号列表展示 → 等待用户挑选 → 再总结我将安装gallery/name确认吗并等待确认 → 最后才调用install_model。规则 3工具错误必须逐字转述Surface tool errors verbatim若工具返回错误Agent 必须在围栏代码块fenced code block中原样引用错误消息回给用户不得重试、不得转述然后等待用户指令再行动。这一设计有清晰的工程动机LLM 在转述错误时倾向润色或自行推断根因容易掩盖真实信息甚至诱导误判错误消息往往包含后续排障所需的确切参数、HTTP 状态或底层详情逐字保留便于管理员直接定位不自动重试切断了错误循环反复重试一个注定失败的变更例如安装一个后端不支持的变体只会浪费资源甚至放大副作用。规则 1 与规则 3 的组合效果是Agent 只能在用户确认后发起变更而一旦变更失败只有用户有权决定下一步重试、换模型或中止Agent 自身不具备自作主张再来一次的空间。规则 4绝不虚构标识符Never invent identifiersAgent 只能使用本对话早前从工具结果中拿到的模型名、gallery 名、后端名和任务 ID。如果没有对应标识符应先用gallery_search或相应的list_*工具获取而非凭记忆或联想生成。这条规则直指 LLM 的幻觉弱点。MCP 调用是参数化的install_model需要精确的model_name/gallery_nameget_job_status需要上一次调用返回的job_idtoggle_model_state需要已安装模型的确切名称。一旦 Agent 编造一个近似但错误的名字要么工具调用失败要么——更危险——命中一个名字相似但并非用户意图的模型。规则 4 配合规则 2把标识符来源与歧义处理都收敛到工具返回这一唯一可信数据源上。规则 5轮询有界Polling当轮询get_job_status时停止条件按下述任一先到者为准状态报告processed: true状态报告cancelled: true已轮询30 次。轮询结束后必须向用户总结最终结果。结合 pkg/mcp/localaitools/dto.go 的JobStatus结构Agent 实际看到的是这样一组字段字段含义id任务 ID原状态映射按 UUID 索引故在此补充processed是否处理完成cancelled是否被取消progress进度0.01.0total_file_size/downloaded_file_size下载任务的总大小 / 已下载大小message/error状态消息 / 错误信息install_model、import_model_uri、install_backend、upgrade_backend均为异步任务返回任务 ID 后需通过get_job_status跟踪。上限 30 次轮询是为了避免无限空转有界轮询 强制总结确保长任务典型如大体积 GGUF 模型下载既不会无人跟进也不会让对话被无意义的轮询刷屏。规则落地的双保险提示词之外还有代码硬门禁提示词约束的是LLM 端的行为而 LocalAI 在代码层还提供了一道不依赖模型自觉的硬门禁完全移除变更工具。pkg/mcp/localaitools/server.go 中的Options结构包含DisableMutating bool注释明确其为--read-only风格的独立 stdio CLI 所用——启用后所有改变服务器状态的工具都不会注册到 MCP 服务器上模型根本看不到也调不到它们。该标志在 pkg/mcp/localaitools/tools.go 中被描述为与提示词安全规则并行的守卫并渗透到每个功能组的注册函数tools_models.go、tools_backends.go、tools_branding.go等均有if opts.DisableMutating判断。pkg/mcp/localaitools/server_test.go 的 skips mutating tools when DisableMutating is set 测试验证了只读模式下的目录与只读预期完全一致。因此整套防御呈三层LLM 指令层10_safety.md的五条规则随系统提示注入prompts.go工具面层DisableMutating在需要只读时直接不注册变更工具server.go一致性保障层prompts_test.go机械核对工具名单与提示文本防止两边漂移。实际使用中的交互范式基于上述规则管理员在会话中与 LocalAI Assistant 协作时可以预期并主动配合以下模式明确表态Agent 会先复述操作工具、目标、参数并等待确认。回复Yes/do it/go ahead/proceed即放行其他模糊表述如你自己看着办按规则不被视为确认Agent 应继续等待。按编号选择当 Agent 给出候选编号列表消歧直接回复序号即可例如 pkg/mcp/localaitools/prompts/skills/install_chat_model.md 展示的安装流程中第 2 步展示gallery_search的前若干结果名称、gallery、简介、许可证用户报序号后 Agent 再总结待安装项并请求确认。错误即原话工具报错时 Agent 会把错误原文放进代码块不会自行重试。管理员应基于错误原文决定方向——是修正参数重试、另选模型还是中止。轮询汇报安装/升级类任务期间Agent 会以返回的job_id轮询get_job_status并汇报有意义的进度变化技能文档中的标准收尾是任务processed: true后调用reload_models再用list_installed_models确认模型已可见。五条规则的内在逻辑是一致的凡是会改变服务器状态的都必须有用户在场、有明确授权、有据可依来自工具返回的真实标识符、有始有终有界轮询并总结。对维护者而言这套体系既约束了 Agent 的自主性边界也用测试把安全规则被误删/名单失同步这类回归挡在 CI 之外是值得复用的 Agent 安全管理范式。延伸阅读想深入这套 MCP 管理面的读者可以在当前仓库中继续查阅以下文件pkg/mcp/localaitools/prompts/00_role.mdAssistant 的角色定义与对话风格要求pkg/mcp/localaitools/prompts/20_tools.md完整工具编目只读 / 变更分类pkg/mcp/localaitools/prompts/skills/各场景技能文档安装聊天模型、从 URI 导入模型、编辑模型配置、升级后端、管理路由语料库、管理分布式调度、系统状态查询、品牌配置演示安全规则在具体流程中的落点pkg/mcp/localaitools/tools.go工具名常量与mutatingToolNames权威名单pkg/mcp/localaitools/client.goLocalAIClient接口工具处理器所见的管理面抽象pkg/mcp/localaitools/prompts.go 与 pkg/mcp/localaitools/prompts_test.go系统提示装配与安全锚点测试。【免费下载链接】LocalAILocalAI is the open-source AI engine. Run any model - LLMs, vision, voice, image, video - on any hardware. No GPU required.项目地址: https://gitcode.com/GitHub_Trending/lo/LocalAI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考