1. 为什么我要拆 pi-mono 的 Monorepo 架构第一次看到 pi-mono 的仓库结构时我盯着packages/目录看了很久。一个 AI 编程助手项目居然拆出了 7 个核心子包从底层 LLM API 抽象一路铺到终端 TUI、Web 界面、Slack 机器人甚至还有 GPU Pod 管理 CLI。这种系统级的工程化组织方式和大多数把代码堆在src/里的项目完全不是一个思路。pi-mono 是一个用 TypeScript 编写的 AI 编程助手 Monorepo采用 npm workspaces 管理多包协作构建工具是 tsgoTypeScript 编译器 vite包管理用 npm版本号 0.67.68总源文件约 600 个.ts/.tsx。它的核心价值在于把LLM 调用 → Agent 循环 → 工具执行 → 多端渲染这条链路拆成了可独立演进、可单独测试、可被不同前端复用的分层结构。这篇文章适合谁如果你正在做以下任何一件事pi-mono 的架构都值得参考想把一个 AI 应用从单文件脚本演进成多端产品想用 npm workspaces 管理一个包含 Agent 核心、UI 层、CLI 工具的中大型 TypeScript 项目或者你单纯想搞清楚一个 Agent 系统到底该怎么分层。我会给出可复制的 workspaces 配置骨架、包依赖拓扑以及构建验证命令让你能在自己的项目里复现同类架构。2. 前置准备TaoToken 与本地环境在动手复现架构之前得先解决Agent 到底调用谁的问题。pi-mono 的pi-ai层抽象了 22 个 Provider但如果你只是想跑通自己的 Agent 循环没必要一开始就接那么多。我建议先用一个兼容 OpenAI 协议的统一入口把链路打通TaoToken 就是这样一个选择——它提供统一的 API 端点模型对话、Coding Plan、API Keys 管理都有对应的控制台入口。具体来说你需要准备三样东西第一一个可用的 API Key。登录 TaoToken 控制台后在 API Keys 页面创建一个密钥格式通常是sk-开头的一串字符。这个 Key 会作为环境变量注入到你的 Agent 配置里。第二确认你的 Node.js 版本。pi-mono 用的是 ESM 模块体系建议 Node 18 以上npm 9 以上因为 npm workspaces 的--workspace参数在旧版本上行为不一致。第三一个空目录作为 Monorepo 根。不要在一个已有package.json的项目里直接套 workspaces依赖提升hoisting会和你原有的node_modules打架。注意TaoToken 的 API 端点是https://taotoken.net/api不要在后面拼/v1之类的路径具体路径由你调用的 SDK 决定。模型对话入口在控制台里可以直接测试接入文档里有各语言的示例。环境变量建议这样组织放在根目录的.env.local记得加进.gitignore# .env.local TAOTOKEN_API_KEYsk-your-key-here TAOTOKEN_BASE_URLhttps://taotoken.net/api然后在代码里通过process.env.TAOTOKEN_API_KEY读取。pi-mono 的AuthStorage模块做的就是类似的事——把密钥从环境变量或文件里读出来统一注入到 Provider 层业务代码不直接碰密钥。3. 可复制的 npm workspaces 配置骨架pi-mono 的包依赖拓扑是这样的自底向上pi-tui ─────────────┐ pi-web-ui ──────────┤ pi-mom ─────────────┼──→ pi-coding-agent ──→ pi-agent-core ──→ pi-ai pi-pods ────────────┘pi-ai是最底层不依赖任何内部包pi-agent-core只依赖pi-aipi-coding-agent依赖前三者UI 层tui/web-ui/mom/pods各自依赖pi-coding-agent或pi-agent-core。这个拓扑的关键约束是依赖只能向上不能向下也不能横向。pi-ai绝对不能 importpi-agent-core的任何东西否则整个分层就塌了。根目录package.json的 workspaces 配置骨架{ name: my-agent-monorepo, version: 0.1.0, private: true, type: module, workspaces: [ packages/ai, packages/agent-core, packages/coding-agent, packages/tui, packages/web-ui ], scripts: { build: npm run build --workspaces --if-present, build:ai: npm run build --workspacepackages/ai, typecheck: tsc --build --dry, clean: rm -rf packages/*/dist packages/*/node_modules node_modules }, devDependencies: { typescript: ^5.6.0, tsgo: ^0.1.0 } }每个子包的package.json要显式声明内部依赖用workspace:*协议npm 9 支持{ name: my/agent-core, version: 0.1.0, type: module, main: ./dist/index.js, types: ./dist/index.d.ts, exports: { .: { types: ./dist/index.d.ts, import: ./dist/index.js } }, dependencies: { my/ai: workspace:* }, scripts: { build: tsgo -p tsconfig.json } }这里有几个我踩过的坑。第一exports字段必须同时给types和import否则 TypeScript 在 ESM 下解析不到类型声明编辑器里全是红波浪线。第二main指向dist而不是src因为 workspace 之间是通过构建产物互相引用的不是直接读源码——这一点和某些用 tsconfig paths 直接映射源码的方案不同pi-mono 走的是先构建、再引用的路线好处是每个包可以独立发布坏处是改了下层包必须重新 build 才能被上层看到。根tsconfig.json用 project references 组织{ compilerOptions: { target: ES2022, module: ESNext, moduleResolution: Bundler, strict: true, declaration: true, composite: true, skipLibCheck: true }, references: [ { path: packages/ai }, { path: packages/agent-core }, { path: packages/coding-agent } ] }composite: true是 project references 的硬性要求它会让 tsc 生成.tsbuildinfo文件增量构建时只重编改动的包。moduleResolution: Bundler是为了配合 ESM 的exports字段解析。4. Agent 模块的组织方式与核心循环pi-mono 把 Agent 拆成两层pi-agent-core提供纯粹的 Agent 循环不绑定任何具体工具pi-coding-agent在它之上实现编码场景的会话管理、工具集和扩展机制。这个拆法的好处是如果你要做一个非编码类的 Agent比如客服机器人可以直接复用pi-agent-core不用拖上整个 coding-agent。pi-agent-core的核心是agentLoop()它的执行流程是这样的// packages/agent-core/src/agent-loop.ts简化示意 export async function agentLoop( agent: Agent, prompts: AgentMessage[], streamFn: StreamFn ): PromiseAgentMessage[] { const messages agent.convertToLlm(prompts); let stopReason: string toolUse; while (stopReason toolUse) { const stream await streamFn(agent.model, { messages }); const assistantMsg await collectStream(stream); messages.push(assistantMsg); const toolCalls extractToolCalls(assistantMsg); if (toolCalls.length 0) { stopReason stop; break; } for (const call of toolCalls) { await agent.hooks.beforeToolCall?.(call); const result await agent.executeTool(call); await agent.hooks.afterToolCall?.(call, result); messages.push(toToolResultMessage(call, result)); } } return messages; }这个循环的关键设计点有三个。第一streamFn是注入的不是硬编码的所以你可以换成任何实现了stream(model, context, options)签名的函数——pi-mono 的pi-ai提供的就是这个签名。第二工具执行有beforeToolCall和afterToolCall钩子扩展系统就是挂在这两个点上。第三循环终止条件是stopReason ! toolUse而不是简单的没有工具调用这样能兼容某些 Provider 返回的中间状态。工具执行模式支持sequential和parallel两种。parallel模式下多个工具调用并发执行但结果按原始顺序收集回上下文——这个细节很重要因为 LLM 期望 toolResult 的顺序和 toolCall 的顺序一致乱序会导致后续推理出错。pi-coding-agent在 Agent 之上包了一层AgentSession负责会话持久化和上下文压缩。会话用 JSONL 格式存储每个会话一个目录包含context.jsonl结构化 API 消息和log.jsonl人类可读日志。当对话超过模型上下文窗口时shouldCompact()检测触发findCutPoint()找到合适的截断点compact()把旧消息替换成摘要。这套机制让长对话不会因为 token 溢出而崩掉。5. 验证请求与构建结果配置写完后先验证 workspace 链接是否正确npm install npm ls --workspaces --depth0你应该看到所有子包被列出来且内部依赖显示为- ./packages/xxx的符号链接形式。如果某个包显示missing说明 workspaces 数组里的路径写错了。接着构建底层包验证 TypeScript 编译链路npm run build:ai ls packages/ai/dist/正常输出应该包含index.js、index.d.ts和若干.tsbuildinfo。如果报Cannot find module my/ai八成是上层包的package.json里没写workspace:*依赖或者exports字段的路径和实际产物对不上。然后写一个最小验证脚本确认 Agent 循环能跑通// packages/coding-agent/scripts/smoke.ts import { createAgentSession } from my/coding-agent; const session await createAgentSession({ apiKey: process.env.TAOTOKEN_API_KEY!, baseUrl: process.env.TAOTOKEN_BASE_URL!, model: gpt-4o-mini, }); const result await session.prompt(用一句话解释什么是 Monorepo); console.log(result.content);用tsx或node --loader ts-node/esm跑这个脚本。如果返回了模型输出说明从pi-ai的 Provider 层到pi-agent-core的循环层再到pi-coding-agent的会话层整条链路是通的。如果卡在streamFn报 401检查 API Key 是否从环境变量正确读取如果报fetch failed检查baseUrl是否写成了https://taotoken.net/api而不是带/v1的路径。构建全部包并做类型检查npm run build npm run typechecktypecheck用的是tsc --build --dry它不会真正输出文件只检查 project references 的依赖顺序和类型一致性。如果某个包的类型声明没生成这个命令会直接报错比等到运行时才发现问题要早得多。6. 本篇常见错误排查错误一npm ERR! workspace not found原因通常是workspaces数组里的 glob 路径和实际目录不匹配。pi-mono 用的是显式列出每个包路径的写法而不是packages/*通配。显式列出的好处是构建顺序可控坏处是新增包容易忘。如果你用通配符确保packages/下没有非包的目录比如docs/否则 npm 会尝试把它当 workspace 处理。错误二ESM 下Cannot use import statement outside a module这是package.json里漏了type: module。每个子包都要加不只是根目录。另外如果你的构建产物是.js但源码是.ts确保tsconfig.json的module设为ESNext或NodeNext不要用CommonJS。错误三类型声明找不到编辑器报Could not find a declaration file检查子包的exports字段。TypeScript 在moduleResolution: Bundler下会优先读exports.types如果只写了main和types而没写exports某些版本的 TS 会解析失败。最稳妥的写法是exports里同时给types和import两个条件。错误四改了底层包上层包没更新这是先构建再引用模式的固有代价。解决方案有两个一是用npm run build --workspaces全量重建二是开发期用tsc --watch在每个包上跑增量编译。pi-mono 的tsgo本身就支持 watch 模式比原生 tsc 快不少。如果你实在受不了这个延迟可以临时在根 tsconfig 里加paths映射到源码但发布前一定要切回产物引用。错误五Agent 循环卡死不退出检查stopReason的判断逻辑。有些 Provider 在工具调用后会返回stopReason: toolUse但实际没有 toolCall导致循环空转。在extractToolCalls后加一个判断如果toolCalls.length 0强制把stopReason设为stop。另外给循环加一个最大迭代次数比如 20 次防止无限循环烧 token。7. 从架构复现到实际接入把 Monorepo 骨架搭起来只是第一步真正让 Agent 跑起来还需要一个稳定的模型入口。我建议的接入顺序是先用模型对话页面验证你的 API Key 和 baseUrl 能正常返回再把同样的配置注入到pi-ai的 Provider 层。如果你打算长期在这个架构上做编码类 AgentCoding Plan 提供了更适合高频调用的配额方案比按次计费更划算。接入文档里有各语言的完整示例包括流式和非流式两种调用方式。对于 pi-mono 这种基于EventStream的架构你需要的是流式接口——stream(model, context, options)返回一个异步迭代器逐块吐出AssistantMessage的增量内容。把pi-ai的streamSimple()替换成你自己的实现只要签名一致上层agentLoop()完全不用改。最后提醒一点Monorepo 的包边界一旦定下来就不要轻易让上层包反向依赖下层包。我见过太多项目一开始分层清晰后来为了图方便在pi-ai里 import 了pi-agent-core的类型结果整个依赖图变成一团乱麻构建顺序再也理不清。pi-mono 的拓扑之所以能保持干净就是因为每个包的职责边界卡得很死——pi-ai只管 Provider 抽象pi-agent-core只管循环pi-coding-agent只管编码场景。你的项目也应该这样。