第四部分，Extensions 开发

自定义 Tools 与远程执行

注册带 TypeBox Schema 的工具，控制执行、流式更新、输出截断和远程工作目录。

高级 / 14 分钟 / 第 21 篇

工具定义

工具需要名称、标签、描述、TypeBox 参数和 execute 函数。描述决定模型何时调用，schema 负责参数形状，业务权限仍由 execute 检查。

工具结果包含 content 与 details。长输出必须截断或分页，否则会迅速占满上下文。

import { Type } from "typebox";

pi.registerTool({
  name: "project_status",
  label: "Project status",
  description: "Read the current project status without changing files",
  parameters: Type.Object({ verbose: Type.Optional(Type.Boolean()) }),
  execute: async (_id, params) => ({
    content: [{ type: "text", text: params.verbose ? "healthy" : "ok" }],
    details: {},
  }),
});

风险控制

工具内部重新验证路径、账号和资源所有权。
写入、发送和删除前设置确认。
远程执行使用受限账号和超时。
为可取消操作响应 AbortSignal。
工具错误返回可诊断信息但不泄露秘密。

官方资料

本页由 xueai 根据 Pi 官方资料用中文重新组织和讲解。Pi 更新频繁，命令、包名和接口以官方最新文档为准。

Pi Extensions Custom Tools