我们给 ERP 系统接了一个 LLM Agent：用户在系统侧边栏用自然语言问”今天 3 号炉的生产计划怎么样”，Agent 调后端工具查数据，再组织成一段业务回答。 现在每发一个版本，两段都要人工扛。发布是六步手工命令：本地 build 镜像、打包、传到服务器、导入、起容器、验证健康检查。验收更麻烦：发布后在侧边栏手敲指令，人肉看 Agent 调没调对工具、数据对不对、有没有泄露内部字段。 人肉

这次给 Java Runtime 接入仓管 Skill，我先重新梳理了 Pi 原生的 Skill 链路。 Pi 已经提供了四项可以直接组合的能力： Skill 自动发现 noSkills additionalSkillPaths Skill 元数据注入与正文按需加载 我们最终选择保留这套原生链路： 123noSkills + additionalSkillPaths + 自定义受限 rea

ERP 里接入数字员工后，普通问答偶尔会同时出现两条提示：一条是“本次业务处理未完成”，另一条是“连接已中断”。发生问题的会话通常已经开始调用 Tool，回答生成到一半就停止。 这次排查确认了两个问题。Spring MVC 的异步响应先超时，Pi 随后把下游断开解释成会话取消；前端又分别展示了 Tool 失败和连接失败，于是一次断流变成了两条错误提示。 现场证据先看服务端时间线。同一时段里，Jav

给 Management Console 加图片输入时，我先定了两个限制：一轮最多 5 张，原始单图不超过 10 MiB。随后看到 Runtime 给 Qwen 登记的上下文窗口是 1,000,000 Token，一个问题马上冒出来：一张 5 MB 图片发给模型，会不会直接吃掉几百万 Token，顺手把前面的系统指令挤出去？ 这两个数字属于不同阶段。5 MB 描述图片文件和 HTTP 传输；1M

管理台的语音输入最后没有做成“浏览器把音频交给 Pi，再让模型处理”。实际链路是：浏览器录音，Java 调用阿里云百炼转成文字，文字回填输入框；用户确认后，才按原有 SSE 对话链路交给 Pi。 这个拆分很重要：Pi 负责 Agent 会话、Tool 调用和模型回复；Java 负责 ERP Gateway 已有的鉴权、部署配置和外部 ASR 调用。音频不是 Pi 会话的一部分，也不会进入 LLM

我们准备把 Java MCP 接到 Pi Runtime 上。工具目录未来会按租户、用户和业务权限过滤，但过滤后的工具仍可能很多。把全部 Tool Schema 每轮发给模型，会增加 token 消耗，也会让相似工具之间的选择变得不稳定。 Pi 已经有渐进加载的底层机制：工具可以全部注册在 Registry 中，只把当前 Active Tools 发给模型。这套能力可以复用到 Java MCP，搜

这次要把 Pi Runtime 部署到一台已经安装 Docker 的 x86_64 Linux 主机上。代码还没有进入代码托管和构建流水线，因此第一版不接镜像仓库，也不做自动发布，只要求本地构建镜像、传到服务器、接入 Nginx，并把环境变量和运行数据放到镜像外面。 讨论到最后，真正需要理清的不是 Dockerfile 语法，而是三个边界：镜像负责什么，Compose 负责什么，环境变量和文件挂载

Pi 的 Skill 不是在启动时把所有 SKILL.md 正文塞进模型上下文。它采用渐进加载：启动或重载时发现 Skill 并保存元数据，构建 System Prompt 时只向模型展示目录，真正选中某个 Skill 后才读取正文。 理解这三层状态很重要：磁盘上的 Skill、运行时内存里的 Skill 元数据、模型上下文里的 Skill 正文不是同一件事。 三个加载时机完整链路可以压缩成三步：

Pi Java Runtime 目前把 Pi 的 AgentSession 写到本地 JSONL，再把原始 Entry 镜像到 Java 数据库。这个实现足以支持单机运行和管理台回放，但不适合作为云端部署后的会话恢复方案。 核心问题很直接：Runtime 续聊时仍从本机 sessions/*.jsonl 打开会话。如果实例重启、容器迁移或扩容到另一台机器，数据库虽然还保留管理台记录，Agent 却

一次物料出库的 AI Tool 调用失败，表面提示是“物料不存在或不属于当前工厂”。实际物料存在，问题发生在它作为 19 位 ID 穿过 JSON 与工具调用契约时。 第一次排查发现，工具调用收到的 ID 已经和查询结果不一致。随后将工具结果中的大整数序列化为字符串后，最新会话仍失败：返回值正确了，但工具参数 Schema 还是 integer，模型又把字符串 ID 当数字传回。这个问题需要同时修