pi 源码模式缺少模型数据清单 (pi Source Mode Missing Model Data Manifest)

2026-09-18 暂无评论

出现条件

从 git clone 的 pi 仓库直接用 tsx 跑源码（pi-test.sh / pi-test.ps1），且该仓库从未执行过模型数据生成步骤。npm install 本身不会补上它。

症状

Error [ERR_MODULE_NOT_FOUND]: Cannot find module
  '.../packages/ai/src/providers/data/.manifest.json'
  imported from '.../packages/ai/src/providers/all.ts'
  code: 'ERR_MODULE_NOT_FOUND'

进程在启动瞬间就崩，连 --version 都跑不出来，容易误判成"依赖没装好"。

根因

packages/ai/src/providers/data/ 是生成目录，不入版本库，clone 后为空。它由 packages/ai/scripts/generate-models.ts 从仓库内已有的 src/providers/*.models.ts 派生，产出每个 provider 的 JSON 加一份 .manifest.json（含 schemaVersion / generatedAt / structureHash / files 校验信息）。

而 providers/all.ts 用静态 JSON 导入引用清单：

import modelDataManifest from "./data/.manifest.json" with { type: "json" };

静态导入在模块解析阶段就必须存在文件，所以缺失即致命错误，不是运行期可降级的告警。

解决

npm install --ignore-scripts
npm run hydrate:model-data        # = packages/ai: generate-models.ts --strict --data-only

hydrate:model-data 只生成数据目录，不触碰 models.generated.ts。对比 npm run generate:models 会连带重新生成 models.generated.ts（该文件按仓库规范禁止手改，只能重新生成）。

边界与前提

走过一次 npm run build 的仓库不会遇到：packages/ai 的 build 脚本第一步就是 generate-models。
生成过程需要网络：脚本会 fetch openrouter、nvidia、vercel ai-gateway 等上游模型列表。网络受限时先配置代理（本机约定 7890，见 AGENTS.md）。
生成耗时约 5 秒，输出会列出每个 provider 的模型数量，可用它确认成功。