1.0.0 关键特性概览#

1. 核心库彻底瘦身（Breaking Change）： pi-agent-core 删除了所有 Harness、Session 存储、Pico3、技能模板等重型模块，仅包含 Agent 状态机、执行循环以及 prepareRequest / finishTurn 最小生命周期钩子。会话存储与持久化全部划归 @earendil-works/pi-durable。
2. 多模态与分类模型三合一： 废除过往割裂的 ImagesModels API，将 chat、image、classifier 统一合并为 AnyModel 与单一的 Provider 抽象。原生集成以 Jev 为代表的分类器协议（支持 choice、score、bool）。
3. 全屏 TUI 与 OKHSL 色彩引擎： 终端交互默认升级为 Fullscreen TUI 模式；引入自适应算法，直接捕获终端 ANSI 调色板并通过 OKHSL 空间动态生成舒适的主题对比度。同时优化了渲染内存管理，单条消息内存占用降至原先的 20%。
4. 企业级鉴权与 MCP 安全加固： 严格落地 RFC 9207，校验 OAuth iss 参数防止授权码注入混淆；凭证按“URL + Server Name”两级隔离，支持同源多租户；原生集成 Radius 一步式配网以及无头环境的 Anthropic Copy Code 登录。

1. 传统 Tool Call 的三大痛点#

在传统的工具调用模型中，智能体与大模型的交互本质是一场低吞吐的串行“乒乓球赛”：

这种交互模式在面对复杂研发场景时存在三大弊端：

• 高延迟与多轮往返（Ping-Pong Overhead）：每执行一步动作，都必须等待模型生成完整的 JSON 参数、解析分发、返回结果，并重新发起下一轮 LLM 推理，数个工具串行下来往往消耗数分钟。
• 上下文污染与 Token 爆炸：大模型往往只需要海量数据中的一小部分信息（例如从 500 个文件中筛选某类导出接口），但传统模式必须把中间过程的巨量文本全部倒回上下文，极易触顶导致窗口截断，账单成本飙升。
• 缺乏代码级控制流：无法进行本地条件分支判断（if/else）、批量异步并发（Promise.all）、或在遇到错误时立刻就地捕获重试（try/catch）。

2. Codemode 的升维打法：代码即协议#

Codemode 彻底改变了范式：大模型不再输出机械的 JSON 结构，而是直接编写一段标准严谨的 JavaScript 异步函数体，交付给宿主沙箱即时编译执行。

3. 全方位技术维度对比矩阵#

1. Token 暴跌 40% 的三级精简架构#

在 1.0.0 以前，包含全量 MCP 工具定义的 Prompt 动辄突破 5,000+ Tokens。1.0.0 成功将标准 GPT-5.6 请求的系统开销从 5,300 骤降至 3,300 Tokens，核心依赖三项革新：

• 描述下沉与单行索引： 在 tool.ts 中，将过去洋洋洒洒的类库手册收拢为一行紧凑的指令，复杂 API 规则指引模型直接查阅外部文档引用：

  1
  // 简明扼要的引导，复杂规则下沉至本地文档
  2
  export const CODEMODE_DOCS_PATH = join(getDocsPath(), "codemode.md");
  3
  const DESCRIPTION_INTRO = `Run JavaScript that calls other tools. The input is raw JavaScript (not JSON, no code fence), run as an async function body in a QuickJS sandbox...`;

• 公平轮转预算裁剪算法（Fair-Queue Round-Robin）： 为了避免某一个庞大的 MCP 服务端（如包含数十个工具）把上下文全部挤占，selectCatalog() 实现了预算轮转调度算法：

  1
  function selectCatalog(groups: readonly CatalogGroup[], budget: number | undefined): Set<string> {
  2
      if (budget === undefined) return new Set(groups.flatMap((g) => g.entries.map((e) => e.name)));
  3
      const queues = groups.map((g) => [...g.entries].sort((a, b) => a.cost - b.cost));
  4
      const shown = new Set<string>();
  5
      let remaining = budget;
  6
      let active = queues.filter((q) => q.length > 0);
  7
      while (active.length > 0) {
  8
          active = active.filter((queue) => {
  9
              const next = queue[0];
  10
              if (next.cost > remaining) return false;
  11
              remaining -= next.cost;
  12
              shown.add(next.name);
  13
              queue.shift();
  14
              return queue.length > 0;
  15
          });
  16
      }
  17
      return shown;
  18
  }

  展开收起
  算法亮点：在 inlineBudget（默认 3,000 Tokens）限制内，以命名空间为单位，每个命名空间每轮只放行“代价最小”的一个工具。一旦某个命名空间超标即退出轮转，确保所有工具集均能平权露脸，超标工具自动转为 deferred。
• 基于 BM25 的本地运行时工具发现： 未塞进 Prompt 的工具，脚本可在运行时通过内建的全局函数自省发现：
  • searchTools(query, { limit, namespace })：在宿主端调用 BM25 算法毫秒级检索相关工具；
  • describeTool(name)：动态返回某工具的入参 Schema 与 TypeScript 声明；
  • describeNamespace(name)：查询某命名空间（如特定 MCP Server）的上下文指令。

2. QuickJS 沙箱隔离与双向管道#

宿主通过 Execution 为每次脚本执行创建独立的 Worker 线程：

• 彻底切断宿主句柄：虚拟机内部不提供 fs、net、child_process，甚至没有异步 setTimeout。脚本与外部通信的唯一渠道是宿主注入的 bridge 函数。
• 硬件级无阻塞中断： 在构造 Worker 时共享一段 4 字节的 SharedArrayBuffer。当触发超时或用户发送取消信号时，宿主直接写入中断标记位，QuickJS 的底层解释循环在下一次 Opcode 步进时立即硬中断，彻底解决恶意死循环耗尽 CPU 的隐患。

3. 基于 Proxy 的智能容错与参数防呆#

大模型手写代码经常出现大小写错位或别名幻觉（例如把 tools.bash 写成 tools.Bash 或 tools.executeBash）。

在 prelude-source.ts 中，Pi 使用 ES Proxy 进行了属性拦截守卫：

1
function guard(target, label, names, hint) {
2
    return new Proxy(target, {
3
        get(object, property, receiver) {
4
            if (typeof property !== "string" || property in object || property in Object.prototype) {
5
                return Reflect.get(object, property, receiver);
6
            }
7
            const wanted = comparable(property);
8
            const close = names.filter((name) => comparable(name) === wanted || comparable(name).includes(wanted));
9
            let message = label + "." + property + " does not exist.";
10
            if (close.length > 0) message += " Did you mean " + close.slice(0, 5).map((n) => label + "." + n).join(", ") + "?";
11
            if (hint) message += " " + hint;
12
            throw new TypeError(message);
13
        },
14
    });
15
}

当访问错误属性时，沙箱立刻报错并附带最具可能性的候选建议（“Did you mean tools.bash?”），引导大模型在下一轮以极低代价精准纠错。

4. 跨轮状态存储与原生多模态生成#

• 会话分支绑定的持久化存储： 沙箱提供了 store(key, value) 和 load(key)。当且仅当脚本执行成功，所有的 key-value 写入才会持久化为会话树的 codemode-store 自定义节点。无论用户在 TUI 中如何通过 /tree 回退、切换分支，各分支都能读取到属于自己历史路径上的精确状态快照。
• 多模态图文无缝流转： 1.0.0 原生开放 models.generateImages(model, context)。大模型脚本可在沙箱中并发调用文生图模型，并通过 image(block) 挂载为多模态响应。如果模型生成了图像却忘记挂载，执行器还会自动注入提醒注记，防止资产静默丢失。

1. 核心架构：Selection（选择）与 Dispatch（调度）彻底解耦#

虚拟模型在外观上是一个普通模型选项（如 jev/auto），用户在 /model 菜单或 CLI 中对其选定并配置虚拟思考深度。但在真实的请求分发链路中，它只是一个路由仲裁层：

2. 状态驱动的路由上下文：ModelRouteRequest#

在 virtual-models.ts 中，每一次向 Provider 派发请求前，路由函数都会接收到完备的决策上下文：

1
export interface ModelRouteRequest<TState = unknown> {
2
    model: Model<Api>;                     // 当前选中的虚拟模型
3
    thinkingLevel: ModelThinkingLevel;     // 当前选中的思考等级
4
    reason: ModelRouteReason;              // 触发本次路由的业务原因
5
    previous?: { model: Model<Api>; thinkingLevel?: ModelThinkingLevel }; // 上一次成功的物理模型
6
    failed?: { model: Model<Api>; message: AssistantMessage };            // 失败重试时的错误信息
7
    state?: TState;                        // 挂载在当前会话分支上的路由私有状态
8
    messages: readonly Message[];          // 完整对话历史
9
    signal?: AbortSignal;
10
}

3. 实战范式剖析：jev-router.ts 双阶段流水线#

官方给出的 jev-router.ts 是一个非常经典的智能流水线范例：

1. 意图定性：通过 Jev 分类器读取用户输入，复杂度评分超过 0.5 调度至顶尖的 gpt-5.6-sol，常规任务选择性价比极佳的 gpt-5.6-terra。
2. 首发修改分水岭：规划模型充分阅读代码、排查架构，一旦成功做出第一次文件变更（成功调用 edit 或 write 工具），路由状态机将 phase 从 "planning" 切换为 "implementation"。
3. 低成本收尾：实现阶段全面切至廉价且极速的 gpt-5.6-luna 进行后续编译、修复与打磨。
4. 收益：整场复杂交互仅付出一次微小的 Prompt Cache Miss 成本，却兼备了顶级架构师的缜密思维与初级工程师的低廉吞吐。

4. 严苛的工程防御体系#

• 前置上下文压缩判定： 在 agent-session.ts 中，当虚拟模型把请求分发给小模型时，如果小模型的 Context Window 小于当前会话长度，Pi 会在派发前自动触发上下文压缩（Auto-Compaction），确保不会因小模型窗口过小而直接炸库。
• 物理模型安全回退： 若会话恢复时原先注册的虚拟模型已卸载，Pi 会自动解析会话分支中最后一次成功应答的真实物理模型，平滑接管，避免出现会话死锁。