版本边界采用三重失败关闭：metadata.yaml 使用 ==4.27.2；插件在导入 AstrBot Tool API 前读取当前进程的 astrbot.__version__，并校验实际依赖及 SSE 会话/运行绑定实现的 20 个核心源码文件摘要，即使管理员绕过 metadata 检查或只保留旧版本字符串也不会注册 ERP Tool；商用启动前还会在不发送 Key 的情况下读取同机 /api/v1/stats/versions，同时要求 AstrBot 运行时版本与磁盘代码版本都是 4.27.2。astrbot-contract.json 另行绑定官方仓库、v4.27.2 标签、提交 ad4fbfa90ca0c4ac2b30b3250e34dbf8fe7babbf、许可证摘要和上述核心文件摘要。

本地桥客户端只允许四个固定读取/计划方法及其精确 payload。发现文件拒绝链接、空文件、超大文件、重复/未知 JSON 字段，并绑定文件名、管道 PID 与 Windows 进程启动时间；建立连接后、写入请求前还会通过 GetNamedPipeServerProcessId 核对实际服务端 PID并再次核对启动时间，阻止同用户假管道伪造 ERP 响应。响应同时绑定协议版本、requestId、correlationId。context.get 还必须满足精确字段契约：活动模块必须包含安全的 moduleCode/navigationCode/moduleName，最多投影 50 个已打开模块，数量和截断标记必须自洽，名称不得包含控制字符；畸形上下文会在进入模型前失败关闭。capabilities.list 只接受最多 128 个不重复的完整命令描述符和受控、有界的 object/string/number/boolean/array Schema 子集；未知关键字、开放 additionalProperties、无效必填字段、超过 8 层/512 节点的 Schema，以及风险与确认/幂等标志不一致都会在进入模型前拒绝。商业启动会话严格采用 lserp-pet-p<PID>-s<启动Unix秒>-c<32位会话作用域令牌>-<32位随机数>；v3 令牌由当前数据库作用域指纹、用户、账套、子系统和管理员布尔值按版本化 UTF-8 长度前缀合同共同生成。Prompt 和三个 Tool 都要求完整后缀并把 PID、启动时间传给桥客户端；每个读取/计划 Tool 还会在业务调用前后重新读取严格上下文，同时比较数据库、用户 ID/姓名、账套、子系统、管理员身份，以及子系统名称、活动模块、打开模块数量/截断状态和有序模块投影。作用域初始不符时不发送业务请求，调用期间发生身份、权限或界面漂移时丢弃能力或计划结果，固定返回 erp_session_scope_mismatch/erp_session_scope_changed。ERP 退出后即使 PID 被复用也不能接管旧会话；缺 PID、缺启动时间/作用域令牌或仅匹配前缀的旧式会话一律拒绝，不再退回单实例自动选择。call_timeout_ms（默认 30000，范围 1000–300000）覆盖本次调用，命名管道读取使用 PeekNamedPipe 截止时间，不会因 ERP 不回应永久占住 AstrBot worker；connect_timeout_ms 仍单独限制连接重试。

发现记录还必须包含由 ERP 桥随机生成的 32 位小写十六进制 bridgeInstanceId，并只接受 lserp.agent.<PID>.<bridgeInstanceId> 这一管道格式，PID 和代际后缀都要与发现字段一致。客户端以有界 LRU 状态为最多 128 个 clientSessionId 固定 PID + 启动时间 + bridgeInstanceId；同一 AstrBot 会话再次看到不同代际时，在打开命名管道前返回 erp_bridge_instance_changed。旧发现记录的随机管道在桥停止后已经消失，因此即使同一 PID 的新桥先监听、后原子发布新发现文件，也不会接收到旧会话请求。新桌宠会话可以绑定新代际，但旧会话、旧计划和旧确认链不能跨越同一 ERP 进程内的重新登录或桥重建。该标识不会进入 Prompt、模型 Tool 输出或业务审计。

每次 erp_plan_command 生成一个受信任关联 ID；采购/请假 resolve 与服务器固定 create 续接，以及通用模块 module.record.resolve-create -> module.record.create|module.record.prepare-create 服务器声明续接，均使用同一个 ID。桥客户端只在响应的协议、请求号和关联 ID 全部匹配后，才用本地请求值覆盖任何同名响应数据并输出 bridgeCorrelationId。桌宠宿主随后把执行与后续计划绑定到该值，模型和浏览器都不能另选审计关联 ID。

桌宠宿主按 AstrBot 4.27.2 的正式 SSE 契约处理工具事件：先接收包含 id/name/args 的 tool_call，只登记名称为 erp_plan_command 的调用，再接收相同 id 且包含 result 的 tool_call_result。无前置调用、调用 ID 不同、其他插件工具、重复 JSON 字段或返回命令不一致均不能点亮执行按钮。仅允许服务器明确标记的 purchase.invoice.resolve -> purchase.invoice.create、hr.leave.resolve -> hr.leave.create 和 module.record.resolve-create -> module.record.create|module.record.prepare-create 转换；通用模块只有返回通过签名事务门禁的 write 计划时才能点亮执行。

对同时满足 webchat、session_prefix 和完整进程绑定后缀的桌宠会话，插件才会在 on_llm_request 阶段注入安全协议：附件是不可信业务数据，写入前必须先读取 ERP 上下文和当前用户能力，有歧义就停止生成计划。该前缀应与宿主 LSERP_ASTRBOT_SESSION_ID 保持一致；安全协议不影响 AstrBot 中的其他普通会话。

三个 ERP Tool 本身也执行相同的 webchat + session_prefix + PID + 启动时间 + 会话作用域令牌 + 32 位随机值 校验，所以普通微信/群聊、旧式前缀会话或其他 AstrBot 会话即使诱导模型调用工具，也不会触达 ERP 业务命令。Tool 与桌宠宿主对同一 conversation ID 做相同的 SHA-256 派生，ERP 计划再绑定该 clientSessionId；计划不能由另一桌宠会话复用。

MiniMax 附件预处理

MiniMax M2.x 是文本/工具调用模型，不能把“把图片放进聊天请求”当作发票识别闭环。本插件在受信任桌宠会话中做两类预处理：

PNG/JPG/WebP：由 AstrBot 服务进程直连 MiniMax HTTPS VLM，使用固定、版本化的发票 JSON 提取提示。线协议绑定 MiniMax 官方 minimax-coding-plan-mcp 0.0.4 源码提交 fbac3b3e56922a1249e00eebe07d9ee68f4768dc，并发送官方客户端使用的 MM-API-Source: Minimax-MCP；区域配置只接受 global 或 cn，分别固定到 https://api.minimax.io/v1/coding_plan/vlm 和 https://api.minimaxi.com/v1/coding_plan/vlm。禁止自定义 URL、系统代理和 HTTP 重定向。请求只读取服务进程的 MINIMAX_API_KEY，不启动 shell/Node 子进程，也不把 Key 放入命令行、URL、请求体或日志。发送前只读取一次有界图片快照，并要求其字节数和 SHA-256 与本次消息识别前的来源凭据完全一致；路径在校验后被替换、读取期间变化或恢复成原文件都不能让另一份图片进入 VLM。返回内容还会在本地拒绝非 JSON Content-Type、超大响应、重复字段、非零供应商状态、Markdown、未知字段、非有限数字、非法日期/金额/税率、控制字符、超量明细与不安全字段路径，并重新生成本地稳定行号，模型输出不能直接越过结构校验进入 ERP 计划。
PDF：父进程先绑定原文件名、大小和 SHA-256，再由 -I -B 启动的独立 PDFium worker 从同一份稳定字节快照完整渲染一至三页 RGB PNG；禁用表单绘制，限制页尺寸、像素、单页/总输出、CPU、内存、进程数和墙钟时间，并逐块复核 PNG 结构、CRC、解压大小和页面摘要。只有整份 PDF 全部页面均成功时才逐页调用同一受限 MiniMax HTTPS VLM，再按页序严格合并发票头与明细。原 PDF、每页 PNG、每页识别 JSON 和最终注入文本分别绑定摘要；加密文档、超过三页、部分渲染、来源替换、跨页重复/冲突、识别不确定或金额不守恒均失败关闭，不会降级为模型自由抄录。
XLSX/UTF-8 CSV：在独立 Python worker 中以只读方式和行/列/字符上限解析，不执行 Excel 公式、宏、外部链接或附件指令。只有匹配固定采购表头白名单时才会映射业务字段；数量、单价、税率、税额、金额和原始行顺序与精确提取包哈希绑定。未识别表头、重复字段、截断、跨工作表疑似重复或冲突会失败关闭。

每份实际参与本次消息的附件都会生成 kind/filename/sizeBytes/sha256/extractionSha256 来源凭据：前一个摘要绑定原文件，后一个摘要绑定实际注入 Agent 的精确 UTF-8 预处理包。采购解析 Tool 会忽略模型提供的 sourceDocuments，重新从当前消息的一次性状态中注入，随后由 ERP 的短期解析凭证、命令输入指纹、固定 XML 写入合同和客户业务审计共同绑定。一到三张同类图片的规范化识别 JSON 也会与各自提取摘要做二次校验：Tool 按附件顺序和页内顺序重新投影供应商、发票号、日期、币种、物料原文和全局唯一行 ID，并用十进制语义核对发票头与每行的金额、数量、单价、税率、税额和总行数。识别不确定、必填字段不全、多来源单歧义、文档类型/发票头冲突、跨页疑似重复明细、合并后超过 200 行或数字不等时不会调用 ERP。Tool 调用时会重新哈希源文件；超过三份附件、文件在识别后被替换、状态过期或已消费、预处理被关闭、扩展名/大小不合法或无法重新读取时，采购计划在到达 ERP 前即失败。模型不能伪造、删除、替换提取版本或把旧附件来源复用到新请求。

不再安装或分发 mmx-cli，客户运行环境也不再依赖 Node.js。MiniMax Key 应由 AstrBot 专用服务账号的秘密管理器注入 MINIMAX_API_KEY，不得出现在插件配置、桌宠、命令行或日志；minimax_api_region 必须与 Key 购买区域一致。启用图片识别但缺少/格式错误的 Key 或区域时，插件在加载阶段直接失败；图片请求失败时只把稳定错误代码交给 Agent，Agent 必须停止生成写入计划。商用 ERP 附件计划要求可审计预处理；关闭 minimax_vision_enabled 或 document_extract_enabled 后，含对应附件的采购计划会以 attachment_preprocess_required 失败关闭，不会降级为无法绑定提取版本的模型原生视觉。

上线前应在 AstrBot 专用服务账号环境中使用轮换后的 Key 执行 python verify_minimax_vlm_contract.py --region <global|cn> --output <新文件.json>。探针只生成并发送内置的无客户数据 64×64 PNG，复用生产代码验证 TLS、区域、认证、官方来源头、供应商状态和严格业务 JSON，再以 CreateNew 写入只含合同版本、哈希与计数的脱敏报告；它不接受客户图片路径，也不会输出 Key 或原始模型文本。已有输出不会覆盖。探针通过只证明当时的 MiniMax 在线线协议可用，不能代替服务条款、数据处理或真实发票识别验收。

文档与 PDF 渲染 worker 使用当前 AstrBot Python 虚拟环境的原始可执行路径（不解析 venv 符号链接），以 -I -B 启动，通过有界 JSON stdin/stdout 交换，不使用 shell。父进程把识别前的来源 SHA-256 和字节数作为严格请求合同传入；worker 只读取一次稳定快照，先验证精确匹配，再从同一份内存字节解析 CSV/XLSX 或渲染 PDF，绝不在验签后按路径二次打开附件。子进程环境只保留 Python/Windows 启动所需白名单变量，不继承 MiniMax Key 或代理凭据；Python audit hook 拒绝网络、再启动子进程和文件写入。Linux 使用 RLIMIT_CPU/RLIMIT_AS，Windows 使用 Job Object 限制 CPU、内存和活动进程数，超时或超大输出会回收整个进程树。

相关限制可通过 document_timeout_seconds、document_cpu_seconds 和 document_memory_mb 配置；配置无效时插件启动直接失败，不会降级到主进程解析。

图片、PDF、XLSX、CSV 源附件统一硬上限为 12 MB，图片在调用 MiniMax VLM 前即拒绝超限文件；官方桌宠 Host 的 LSERP_ATTACHMENT_MAX_FILE_MB 也固定约束为 1-12。任一入口或可信传递层放宽都必须视为契约变更并重跑商用回归。

商用上线仍应在 AstrBot 上传目录前置杀毒/文件隔离，并使用专用低权限 Windows 服务账号或 AppContainer。Python audit hook 是防御加固，不能替代操作系统级网络隔离和恶意文档扫描。

PDFium/XLSX worker 依赖不仅锁定版本，还在 requirements.txt 中固定 wheel SHA-256；正式环境必须用 python -m pip install --require-hashes -r requirements.txt 安装。商用打包分别下载构建机测试 wheel 与 win_amd64 客户 wheel，在隔离 venv 中离线复装并执行 pip check；现场预检还会核对 pypdfium2 5.12.1 Windows wheel 的精确名称、SHA-256、原生 pdfium.dll 和随包许可证，任何 worker 测试跳过都会终止构建。

建议对桌宠配置路由关闭 AstrBot 自带的 Moonshot 文件提取，避免同一文档被重复解析和发送。

erp_get_capabilities 返回的是按当前 ERP 登录权限过滤后的命令及输入 JSON Schema；模型必须先发现能力，再按 Schema 生成计划。采购附件先计划 purchase.invoice.resolve，发票日期在 resolve/create 1.4 契约中是严格 YYYY-MM-DD，不允许时间或时区。可信预处理层根据精确载荷与来源回执自动生成图片/PDF/CSV/XLSX 的 preprocessContract，模型提供的同名字段会被丢弃，缺失、错后缀或被调换的合同不能进入 ERP。唯一解析时 Tool 在本地把服务器 resolvedInput 原样续接 purchase.invoice.create，不会让模型重建或输出短期 HMAC resolutionProof。自然语言请假同理先计划 hr.leave.resolve 1.4；dateExpression 必须保持用户原文，“本周五”“下周一到下周三”“8月15号”等表达只依据 ERP 返回的当前本地时间解析，模型不得提前换算日期，裸“周一/星期一”必须追问；多日表达必须保留两端明确的上午/下午/全天，不能由模型补时间。只有返回完整符合 lrp1.<到期 ticks>.<nonce>.<输入指纹>.<签名> 受限形状的服务器短期凭证时才原样续接 hr.leave.create；采购 rp1 同样校验完整形状，最终真实性与有效期仍由 ERP 创建命令复核。禁止自行生成或修改员工、假别、流程、时段、工时及凭证。零候选、多候选、缺少/伪造凭证、无效解析计划或不受信任的 follow-up 都不会自动续接。本插件已按 AstrBot 4.27.2 官方源码事件结构完成工具契约核对，并完成 CSV/XLSX/PDF 独立 worker、自动续接 Tool 和宿主 SSE 字节流测试；升级 AstrBot 的任何版本前都必须重新审查上游差异、更新锁定提交并运行真实框架契约测试，不能直接扩大版本范围。

AstrBot 宿主要求首个 SSE 事件精确回显本次 session_id，工具调用、工具结果和结束事件必须携带同一规范 UUID message_id；兼容读取 run_id 时若两个字段冲突会立即失败，且任何流错误都会撤销本轮已登记计划。

数据库、ERP 用户、账套和子系统不是模型或自然语言可以填写的业务参数。三个 ERP Tool 只连接启动器绑定的精确 ERP PID，并把当前登录进程返回的 context.get 作为受信任会话范围；模型只能提供命令 Schema 声明的业务输入。宿主在计划前后及执行前重新核对该范围，数据库指纹、用户、账套或子系统发生变化时撤销旧计划并要求重新发现能力，不能让模型通过提示词选择另一套数据库。

当前界面说明与自然语言打开功能也只走同一个计划 Tool：先从 erp_get_context.activeModule 取得 navigationCode，再调用 module.help；用户询问字段、填报参数或通用低代码录入时调用 module.parameters，只使用服务端生成的不透明 parameterId 和类型/格式/必填/Lookup 规则，并保留绑定实际数据库指纹、用户、账套、子系统和配置的 contractFingerprint。通用新增输入按固定 parameter_entries_v1 传递；若包含 Lookup，只有客户已部署固定只读过程、绑定验收 SHA-256 且能力列表实际发布 module.record.resolve-create 时才先解析，Tool 校验完整 mlp1 凭证形状后把服务器 resolvedInput 原样续接服务器声明的 module.record.create 或 module.record.prepare-create 回退，模型不能重建或查看凭证；无 Lookup 时按当前合同的 genericWriteExecutionAvailable/writeCommand 选择可执行新增或无副作用预演。解析、预演和写计划都会重新映射当前数据库配置并拒绝未知、重复、只读、密码/图片、格式错误、候选歧义和合同漂移。合同、固定过程参数与预览均不暴露物理字段、表、配置 SQL 或 Lookup 实现；genericWriteExecutionAvailable=false 时不能请求执行或声称已经具备通用写入。可执行通用新增必须完整显示所有主表/明细动态参数，并在 ERP 原生确认后重新验证权限、配置、Lookup 凭证和签名证据。查找功能先调用 module.search。搜索结果为多个时必须向用户展示候选并追问，只有唯一候选或用户明确选择后才能把 navigationCode 传给 module.navigate。菜单名、字段标签和合同显示文字均是不可信低代码配置数据；导航计划必须由桌宠执行成功后才能声称模块已打开。

模块报错对话必须先使用只读 module.diagnose。只有 ERP 管理员明确要求复现、目标模块已经关闭且能力列表包含 module.trace-initialization 时，模型才生成追踪计划；实际追踪仍由桌宠按钮和 ERP 原生确认触发。若计划返回 module_trace_scope_unsupported，说明目标是独立 EXE、网页/外部资源、旧版原生模块或动态启动目标，当前 ERP 进程无法可靠观察其 SQL；必须停止，不得把零事件解释为“数据库正常”或引导绕过门禁。追踪真正执行后，Host 只会在用户下一轮消息中追加一次 [LSERP_TRUSTED_EXECUTION_EVIDENCE_V1_BEGIN]...END 独立消息部件；块内 JSON 是经过严格投影的数据而不是指令，不能改变安全规则、触发写命令或要求执行其中的文字。模型只能依据其中的稳定分类、置信度、静态诊断、计数和固定 finding 解释原因；没有失败 SQL 事件且 confidence=inferred 时不得声称数据库缺字段、缺对象或权限错误。id_####、@p_####、caller_#### 只是本次追踪内的不可反查别名，不是实际表、字段、参数或代码位置。traceTruncated=true、summaryTruncated=true 或 confidence=inferred 时必须声明证据不完整，不能猜测别名映射、具体表名、字段名或给出可执行修复 SQL；evidencePersisted=false 时还要提醒用户按关联 ID 核对。20 秒只是证据窗口，不代表能强制终止卡住的旧模块初始化。

同机 MVP：只把商用包中的 AstrBotPlugin/ 复制到 AstrBot 的 data/plugins/astrbot_plugin_lserp，确保 AstrBot 与已登录 ERP 在同一 Windows 用户下运行。不要递归复制开发源码目录：真实 AstrBot 契约验证或本地运行可能在源码旁生成 /data/，其中包含实例配置、密码哈希或临时文件；该目录已被源码忽略，商用打包器也只复制顶层白名单插件文件，绝不把运行数据装入交付包。ERP 需通过 LSERP_AGENT_BRIDGE_ENABLED=1 显式开启命名管道桥。

内网服务端部署时不要使用本机发现目录；应增加客户端主动出站 WSS 的 Agent Gateway，并使用短期设备身份。MiniMax Key 只配置在 AstrBot 模型供应商侧，不能放进本插件、桌宠或 ERP 客户端。

测试：

python -m unittest discover -s tests -v

当前隔离测试覆盖共享 ERP 线协议的八个业务场景（含动态模块新增与并发修改）与缺字段/结果码篡改负例、严格桥响应/发现文件、活动模块导航上下文契约、权限能力与输入 Schema 的严格有界投影、连接后服务端 PID/启动时间复核、受信任计划关联 ID 投影、多 ERP 实例拒绝与精确 PID 绑定、可信会话派生、硬超时、未授权会话零桥调用、采购/请假/动态 Lookup 固定续接、采购附件来源与精确提取摘要自动覆盖、一次性交接、变更/过期/未预处理失败关闭、只读诊断不续接，以及附件沙箱、识别字节与来源摘要绑定、PDFium 真渲染/超页/换源/CRC/跨页冲突负例、MiniMax 固定区域直连 HTTPS 边界、官方 MCP 0.0.4 请求来源头与源码契约绑定、视觉结果严格结构校验和版本守卫正负例。商用打包还必须用 verify_astrbot_contract.py 在依赖已由企业制品库复核的 AstrBot Python 环境中加载官方干净源码，实际实例化插件、三个 FunctionTool、ProviderRequest 和附件 API；本地 stub 测试不能替代这一步。

准备发布 AstrBot 插件市场前，必须为 metadata.yaml 填写真实公开 GitHub repo，并完成 Windows 命名管道集成测试。

README.md Unescape Escape

astrbot_plugin_lserp

MiniMax 附件预处理

README.md