跳转到内容

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 新功能与升级。