Codemode:组合工具与非聊天模型
Codemode 是一个模型可调用的工具:模型编写 JavaScript,脚本再调用 Pi 的其他工具、组合或筛选结果。模型通常只看到脚本返回的结果,而不是每次调用的完整输出。
它从 Pi 0.99.0 起内置;1.0 加入图片生成,1.4 改进 worker 排队,1.5 改进大工具调用的流式处理和工具搜索。这里介绍的是 1.5 中的用法,不是说所有能力都在 1.5 新增。
什么时候有用
- 并行读取多个文件或调用多个只读工具,再把摘要返回给模型。
- 从大量 MCP 工具中搜索需要的能力,按需查看参数。
- 使用分类器对结构化数据回答布尔、选择或评分问题。
- 使用图片模型生成或编辑图片,然后把图片交给模型查看。
如果只是读取一个文件或执行一条简单命令,直接调用普通工具通常更容易检查。Codemode 不保证节省成本:脚本、工具结果、模型请求和图片生成都可能产生开销。
如何启用
单次启动时,在默认工具之外增加 Codemode:
pi --tools +codemode要为以后的会话启用,把下面的字段合并到 ~/.pi/agent/settings.json:
{ "defaultTools": ["+codemode"]}+codemode 保留其他默认工具。已连接的 MCP 服务器如果使用 codemode exposure,也可能自动启用它。--no-extensions 会禁用内置 Codemode 扩展;如确实需要只加载它,参考 -e builtin:codemode 与官方资源选项。
进入 Pi 后,可以请求:“用 Codemode 读取 README 和包清单,只输出各文件的前 300 个字符。”实际是否选择该工具由模型决定;请检查工具调用和结果。
脚本长什么样
以下代码是 Codemode 工具的脚本输入,不是 shell 命令,也不是让你粘到普通 Pi 输入框运行的命令。工具接收原始 JavaScript,不带 Markdown 代码围栏:
const paths = ["README.md", "package.json"];const results = await Promise.allSettled( paths.map((path) => tools.read({ path })));return results.map((result, index) => ({ path: paths[index], preview: result.status === "fulfilled" ? String(result.value).slice(0, 300) : `读取失败: ${result.reason}`,}));脚本运行在异步函数体内,因此可以顶层 await 和 return。Promise.allSettled() 保留成功和失败结果;工具调用失败、被拦截或参数非法时会拒绝 Promise。
常用能力:
| 脚本入口 | 用途 |
|---|---|
tools.<name>({ ... }) | 调用当前可达的工具 |
text(value) / return value | 向模型返回文本或 JSON 值 |
image(block) | 返回图片块,并保存临时文件供后续步骤使用 |
searchTools(query) | 搜索可调用工具,默认最多 8 项 |
describeTool(name) | 查看工具说明和 TypeScript 声明 |
describeNamespace(name) | 查看 MCP 服务器说明和工具名称 |
store(key, value) / load(key) | 在会话分支中保存和读取小型 JSON 状态 |
models | 查询和调用分类器、图片模型 |
工具的返回值因工具而异。例如 read 读取文本时返回文本,bash 返回带 output、exit_code 和截断信息的结构,MCP 工具返回 MCP 结果;不要一律假设有相同的 content 字段。
发现和组合 MCP 工具
MCP 默认 codemode exposure 的工具不会全部塞进 Codemode 描述。脚本可以按需发现:
const matches = await searchTools("搜索文档", { namespace: "docs", limit: 5 });return matches;docs 只是示例服务器名称。找到了工具,再通过 describeTool() 看参数和结果类型,按实际声明调用。Pi 1.5 修复了中文等非 ASCII 查询无法匹配的问题;搜索结果仍需人工检查是否是正确服务。
tool_search 是另一种机制:它找到尚未声明的工具,并把匹配项声明给后续模型调用。两者都可能让间接暴露的工具变得可用,详见 MCP 工具暴露。
分类器与图片模型
分类器和图片模型不是聊天模型,不出现在普通 /model 聊天选择器中。它们能通过 Codemode 的 models 对象调用,也可由 Extension 的 ctx.modelRegistry 调用。
分类器
先选择当前凭据可用的分类器,再判断返回状态:
const [model] = await models.getAvailableOfType("classifier");if (!model) throw new Error("没有可用的分类器");const result = await models.classify(model, { state: { message: "这个修改解决了我的问题,谢谢。" }, questions: { approved: { type: "bool", instructions: "用户是否认可结果?", criteria: { true: "认可", false: "没有认可" }, }, },});if (result.stopReason !== "stop") throw new Error(result.errorMessage ?? "分类失败");return result.answers;返回的是模型判断和概率,不是事实证明或权限决策。1.4 起部分分类器支持图片,但必须查看具体模型的 input 和服务限制;不是所有分类器都接受图片。具体可用性与费用取决于供应商及凭据。
图片生成
const [model] = await models.getAvailableOfType("image");if (!model) throw new Error("没有可用的图片模型");const result = await models.generateImages(model, { input: [{ type: "text", text: "A red fox in the snow, watercolor" }],});if (result.stopReason !== "stop") throw new Error(result.errorMessage ?? "图片生成失败");for (const block of result.output) { if (block.type === "image") image(block); else text(block.text);}真实生成会调用外部服务并可能计费。image() 会显示图片并写入临时文件;需要长期保存时,检查结果中的路径并按需求复制到目标位置。不要把 base64 图片作为文本输出。
状态、限制与失败语义
- 脚本在 QuickJS 中运行,没有直接的 Node API、文件系统、网络或定时器;外部能力经由
tools和models。 - 一次脚本的 VM 内存上限为 256 MB。一个 Pi 进程默认最多两个存活 worker;1.4 起满载时排队,最多等 60 秒或直到脚本自己的 deadline。
PI_CODEMODE_MAX_WORKERS可调整并发,也会增加资源需求。 - 脚本首行可写
// @options: {"max_output_tokens": 2000, "timeout_ms": 60000}。超时包括等待 worker 的时间;图片生成可能需要几分钟,不要机械套用短超时。 store()保存小型 JSON 值,成功脚本的状态跟随会话树和分支;失败脚本的写入不保存。不要存储图片或凭据。- 已执行的工具调用不会在脚本失败时回滚。例如先写文件再抛错,文件仍可能已被修改。脚本结束时尚在运行的调用会被取消,但这不保证外部服务撤销已接受的操作。
- QuickJS 限制脚本直接访问系统,不限制被调用的
bash、写工具或 MCP 服务器的权限。处理不可信工作仍需容器、VM 或其他真正的隔离。
更多 API、输出与上限见 Pi Codemode 官方文档。扩展自身进程和工具参数变化见 Pi 1.5 新功能与升级。