从一次模型调用，
搭出一个可靠的 Harness

先让 Pi 在你的电脑上启动

学习过程会从运行现成的 CLI 开始。完成这一步后，你可以直接检查项目行为，再往下拆解底层包。

1. 安装 Node.js 22.19 或更新版本；先用 node -v 确认当前版本。
2. 按官方 README 的 npm 安装方式安装 CLI（忽略依赖生命周期脚本）。
3. 进入一个专门的练习目录启动 pi；在 Pi 中用 /login 配置一个受支持的模型提供方。
4. 完成登录后，先让 Pi 回答一个简单问题；再退出并确认 pi --version 正常。

node -v
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
pi --version
mkdir pi-lab && cd pi-lab
pi

先看清：你究竟在组合哪几层？

把 harness 想成“让模型完成任务的运行系统”：它不仅发请求，还要管理消息、工具、运行状态和与使用者的交互。Pi 把这些职责拆成可复用的包。

让 pi-ai 做一件最简单的事

这一课先不做 Agent，也不执行工具。我们只注册一个 provider、找到模型、发一条 user message、读取完整回复。用这一层可以分辨：问题来自模型接入，还是之后的工具循环。

安装与最小例子

import { createModels } from "@earendil-works/pi-ai";
import { openaiProvider } from "@earendil-works/pi-ai/providers/openai";

const models = createModels();
models.setProvider(openaiProvider());

const model = models.getModel("openai", "gpt-4o-mini");
if (!model) throw new Error("Model not found in this provider catalog");

const response = await models.complete(model, {
  messages: [{
    role: "user",
    content: "用一句话解释什么是 agent harness。",
    timestamp: Date.now(),
  }],
});

for (const block of response.content) {
  if (block.type === "text") console.log(block.text);
}
console.log("tokens:", response.usage.input, response.usage.output);

在项目目录执行：npm init -y，再 npm install @earendil-works/pi-ai；把 package.json 设为 ESM（"type": "module"），然后用支持 TypeScript 的运行器或编译器运行示例。需要有效的提供方认证，依照官方 provider authentication 文档配置；不要把 API key 写进源码或网页。

读懂数据形状

Models 集合负责根据 provider + model 标识路由。这里使用完整 catalog 以便快速开始；产品只需一个 provider 时，可像示例一样导入 provider 子路径，减少不必要的模型目录和 SDK 包体。complete() 返回最终 AssistantMessage；若需要逐字增量和工具调用事件，再选择 stream() 并遍历事件。

用 Agent 接过消息和循环

核心差别不是“模型变聪明了”，而是应用开始持有可变状态，并定义模型调用、事件观察和工具执行怎样接起来。Pi 的 Agent 是有状态 wrapper：拥有当前 transcript、发出 lifecycle 事件并执行工具。

import { Agent } from "@earendil-works/pi-agent-core";
import { createModels } from "@earendil-works/pi-ai";
import { openaiProvider } from "@earendil-works/pi-ai/providers/openai";

const models = createModels();
models.setProvider(openaiProvider());
const model = models.getModel("openai", "gpt-4o-mini");
if (!model) throw new Error("Model not found");

const agent = new Agent({
  initialState: {
    systemPrompt: "你是一个简洁、准确的学习助手。",
    model,
  },
  streamFn: models.streamSimple.bind(models),
});

agent.subscribe((event) => {
  if (event.type === "message_update" &&
      event.assistantMessageEvent.type === "text_delta") {
    process.stdout.write(event.assistantMessageEvent.delta);
  }
});

await agent.prompt("用三点解释：模型 API 和 harness 有什么不同？");
console.log("\\n消息条数：", agent.state.messages.length);

这段与官方 agent-core Quick Start 使用同一结构：创建 provider / model，构造 Agent，把 models.streamSimple.bind(models) 传作 streamFn，订阅文本增量，然后 prompt()。绑定方法很重要：让调用时的 this 仍然是 Models 集合。

Harness 的最小组成

工具调用：模型提议，宿主程序执行

Agentic 循环会把工具声明发给模型。模型返回结构化的 tool call 后，Pi runtime 验证参数、运行本地 execute、把 tool result 写回 transcript，再决定是否继续模型请求。记住，真正拥有能力的是执行工具的宿主进程。

import type { AgentTool } from "@earendil-works/pi-agent-core";
import { Type } from "@earendil-works/pi-ai";

const addTool: AgentTool = {
  name: "add_numbers",
  label: "Add numbers",
  description: "Add two finite numbers and return the sum.",
  parameters: Type.Object({
    a: Type.Number({ description: "First number" }),
    b: Type.Number({ description: "Second number" }),
  }),
  execute: async (_toolCallId, params) => {
    const sum = params.a + params.b;
    return {
      content: [{ type: "text", text: String(sum) }],
      details: { sum },
    };
  },
};

agent.state.tools = [addTool];

AgentTool 的 schema 描述要传给模型的参数；execute 是本地业务逻辑，返回 text content（也可有 details 给 host 使用）。Pi 官方示例还支持 onUpdate 发进度、AbortSignal 中断以及每工具的执行顺序配置。失败应 throw error，让 runtime 把工具错误交给模型，不要伪装成成功文本。

先做可控的前置拦截

const agent = new Agent({
  initialState: { systemPrompt, model, tools: [addTool] },
  streamFn: models.streamSimple.bind(models),
  beforeToolCall: async ({ toolCall, args, context }) => {
    if (toolCall.name === "delete_file") {
      return {
        block: true,
        reason: "delete_file is disabled in this lesson",
        terminate: true,
      };
    }
  },
});

这只是运行时策略的一个挂点。实际应用还应由 host 检查经 schema 验证后的参数、用户身份与授权、路径归属、额度和副作用级别；对写文件、发邮件、交易等高影响动作，增加合适的确认或隔离流程。不能仅凭模型自述、提示词或者项目 trust 决定是否允许。

何时用 CLI，何时嵌 SDK？

如果你想使用 Pi 的现成会话、工具、设置和资源发现，不一定要自己重新拼装 agent-core。pi-coding-agent 提供交互 CLI，以及 Node.js / Bun 中的 TypeScript SDK。先根据进程边界和控制需求选入口。

# 人交互
pi

# 一次调用，只取最终文本
pi --print "总结这个仓库的目录结构"

# 一次调用，订阅 JSONL 事件
pi --mode json "检查测试失败的原因" > events.jsonl

# 长驻 RPC 进程；命令通过 stdin 每行发送 JSON
pi --mode rpc --no-session

注意：JSON mode 输出的是一串换行分隔的事件，不是单个 JSON 响应；RPC 的 prompt 命令被接受，不代表 run 已经结束，完成时应持续读事件直至 agent_settled。执行行为和权限仍沿用运行 Pi 的进程，模式不等于沙箱。

最小 TypeScript SDK

import { createAgentSession } from "@earendil-works/pi-coding-agent";

const { session } = await createAgentSession();
try {
  await session.prompt("当前目录里有哪些文件？");
  console.log(session.getLastAssistantText());
} finally {
  session.dispose();
}

此工厂默认使用当前工作目录、已发现资源、存储设置和配置凭证；会话默认持久化。若宿主明确不想写 session 文件，官方 SDK 提供 SessionManager.inMemory()。不再用时调用 dispose()，它会中止活动工作并清理 extension context 和事件监听器。

把“能跑”变成“能恢复、能检查”

健壮性不是一层万能包装，而是明确管理失败、状态、安全与可观察性。下面按实施顺序增量加固，不必一次上齐所有 package。

建议的加固顺序

1. 输入与输出契约：校验用户输入和工具参数；对外返回可预期的状态，而不是只看 Assistant 的最终文字。
2. 取消与超时：从请求路径传播 AbortSignal；需要中断时调用 agent.abort()，需要等待清理完成时再 waitForIdle()。
3. 工具幂等：写入型工具考虑幂等键、去重、明确超时与副作用回滚边界；返回错误要保持错误态。
4. 会话与上下文：先说清谁是 transcript 的权威来源。pi-agent-core 管当前 Agent state；coding-agent SDK 的 SessionManager 管持久 session 与 active branch；pi-durable 为独立的持久化 runtime / storage 能力，不要未经设计把它们混为一个存储契约。
5. 事件与日志：分别记录状态转换、工具输入输出摘要、provider 请求和错误；敏感文本 / token 不应原样写到遥测。pi-telemetry 是显式 contract，要由应用接到选用的后端。
6. 模型与成本：设置预算、最大步骤、重试上限及可解释的失败策略。不要把无限重试当恢复机制；对可重试的 provider 错误和不可重试的工具 / 权限错误分别处理。
7. 安全隔离：将 Pi 或自有工具部署在最小权限用户 / 容器等隔离边界；生产凭证只注入运行环境，并尽量限制权限范围。
8. 回归测试：为工具 schema、正常路径、空结果、拒绝权限、异常、取消、重复调用和上下文变长建立测试；固定期望行为，而不是只比较生成文案。

做一个只读“仓库讲解助手”

目标不是复制整个 coding-agent，而是做出一个权限有边界、能观测执行过程、出现故障时能说明白的最小产品原型。

1. 基线：先完成一条 pi-ai 调用，保证 provider 和环境凭证可用。
2. 升级：用 pi-agent-core 构造 Agent，只加入两个只读工具：列出预设目录下的文件、读取目录内的一个文本文件。
3. 限制：工具实现中校验解析后的路径始终落在练习仓库目录；不开放任意命令或文件写入。
4. 界面：先用 Node CLI 输出 Agent 文本和工具事件；需要直接使用 Pi 的完整会话能力时，再对照 SDK 重新实现。
5. 验证：增加成功、文件不存在、目录穿越尝试、工具异常、取消等测试案例，写出你期望的退出码 / 错误呈现。
6. 复盘：画出模型调用、工具执行、事件、会话状态、策略检查之间的边界；标注此实现还缺哪些生产保障。