pi-ultracode

为 Pi 提供确定性的多代理工作流。

English · 简体中文

pi-ultracode 为 Pi 增加可选的语义化分析深度模式。它既可以自动判断任务需要的深度，也可以固定使用 focused、standard 或 deep 策略。当委派确有价值时，主代理可以运行有边界的 JavaScript 工作流，使用并行子代理、隔离 worktree、结构化输出、持久恢复和实时进度。

项目结合了 Claude Code 的终端 Agentic 体验，以及 Grok Build 的显式工作流和结构控制思路，同时继续使用 Pi 作为运行时。

安装

pi install npm:pi-ultracode

然后重新加载 Pi，并用主命令开启自适应 Ultracode：

/reload
/ultracode

也可以在启动时直接进入 auto 模式：

pi --ultracode

pi-ultracode 会注册名为 workflow 的工具。如果已安装 pi-dynamic-workflows，请先运行 pi remove npm:pi-dynamic-workflows。

需要 Pi 0.86.0 或更高版本。模式提示词通过独立分区更新，不再替换整段系统提示词。

核心特性

• 自适应语义深度：可选择 auto、focused、standard 或 deep；auto 使用证据充分的最小深度，父代理 effort 始终由用户控制。
• 显式工作流：通过 agent()、parallel()、pipeline() 和嵌套 workflow() 组合任务。
• 独立子代理：每个代理拥有独立的 Pi 会话、上下文、工具、模型选择和可选角色。
• 并行 worktree 隔离：写入型代理可在临时 git worktree 中工作，再集成补丁。
• 结构化输出：使用有边界的 JSON Schema 子集校验代理结果。
• 持久恢复：按照稳定的结构身份复用已完成调用，不重复执行成功任务。
• 实时可观测性：在 TUI 中查看状态、模型、思考强度、turn、工具、token、重试和 transcript。
• 有界执行：限制累计代理数、并发、JSON 大小、Worker 运行和取消清理时间。

快速开始

用主命令开启自适应 Ultracode，然后描述任务：

/ultracode

Review the current branch in parallel, verify every finding,
fix the justified issues, and run the relevant tests.

Pi 会自行判断工作流是否有帮助。小任务仍可继续使用普通的单代理循环。

常用命令：

命令	作用
/ultracode	关闭时开启 auto；任一模式已开启时关闭
/ultracode auto	配置 Jev 时由其选择初始深度，否则由父代理判断
/ultracode focused	固定处理方法已知、范围明确且能局部直接验证的工作
/ultracode standard	固定调查独立维度或竞争假设，并做针对性验证
/ultracode deep	固定检查相互作用的约束或关键不变量，要求独立证据和反例检验
/ultracode off	关闭且不改变父代理 effort
/ultracode status	查看配置模式及其适用条件、验证要求
/ultracode default on	全局默认开启，并立即开启当前会话；已开启时保留当前深度
/ultracode default off	取消默认开启
/ultracode default	查看全局启动默认值
/workflows 或 F6	打开工作流浏览器
/workflows <runId>	打开指定运行
/workflows abort	中止活动运行

/ultracode default on 保存全局启动默认值，并立即将关闭的当前会话切换为 auto；当前已开启时保留所选深度。/ultracode default off 只取消默认开启，不关闭当前会话；关闭当前会话请用 /ultracode off。这些操作均不改变 effort。设置保存在 ~/.pi/agent/ultracode.json（遵循 PI_CODING_AGENT_DIR），跨项目和重启生效；未设置时默认关闭。启动时，只有当前分支没有保存 Ultracode 模式才应用默认值，已有的 off 或深度选择在 reload、resume、fork 后继续保留。显式 pi --ultracode 仍可启用 auto。

按 Esc 可取消正在运行的工作流。在 Pi 的 fullscreen TUI 中，请在工作流详情内使用 Ctrl+PageUp、Ctrl+PageDown 和 Ctrl+End。

分析深度

深度决定要调查和验证什么，不是模型 effort，也不是代理数量或调查轮数配额：

深度	适用条件	验证要求
Focused	范围明确、方法已知、结果可局部验证；例如添加指定校验规则	直接检查修改行为或关键结论，通常使用父代理循环。默认不做广泛调查或对抗评审，但不能省略验证。
Standard	多个独立维度或未解决的竞争假设会实质影响答案；例如故障存在多个合理根因	调查相关维度或比较根因，再针对冲突、证据薄弱的结论验证。仅仅步骤多且方法已知，不足以要求 standard。
Deep	紧密相互作用的硬约束或关键不变量，需要独立证据与反例检验；例如取消与持久提交发生竞争	追踪相互影响，检查边界及失败路径，用不同测试、复现、证明或来源挑战关键结论。第二个代理既非必要条件，也不保证证据独立。
Auto	选择足以处理当前任务的最小深度	遵守所选深度的证据要求；仅在实质新证据或未解决冲突要求时升级。

风险决定哪些结论需要验证。安全、并发、数据丢失等关键词、文件数量或“做一次 review”本身不能自动触发 deep；信息不足也不证明存在隐藏复杂度。Deep 不自动意味着必须使用工作流、增加代理或反复调查。显式 focused / standard / deep 保持固定：若不足以确认结论，应说明不确定性并建议更深模式，不能悄悄越界。

当关键结论已有直接证据、没有实质冲突或未解决的高风险问题，且下一轮只会重复已知证据时停止。墙钟时间、deadline 和 duration limit 不得用于选择或停止分析深度。maxAgents 与 reserveAgents 继续作为结构性准入限制。父会话 effort 由用户控制，子代理 effort 仍按具体子任务单独判断。

Auto 下可选的 Jev 初始深度选择

设置非空白 TYPESAFE_API_KEY 后，每次 auto 的 before_agent_start 通过已有 TypeSafe SDK 向 https://api.typesafe.ai 的 jev-1.13.0 发起一次选择请求。只在 focused、standard、deep 中选择，与父代理提示词共用 src/depth.ts 的标准。不创建路由代理，也不增加父模型分类请求。成功结果作为初始深度注入，不会把 auto 改成固定模式；父代理可根据 Jev 未见的相关会话或仓库证据立即升级。

• 请求只发送当前展开后的用户提示词和附图数量，不读取仓库，不发送会话历史、系统提示词或图片内容。启用前请确认这些提示词可以发送给 TypeSafe。简短追问、依赖图片的任务可能缺少准确选择初始深度所需的上下文；父代理仍拥有正常上下文，并按证据升级。文本为空时跳过选择。
• 缺少/空白密钥、网络或服务错误、响应格式错误、不受支持的选择，以及 10 秒传输超时，均保留父代理在正常 turn 内的语义路由。不重试，不增加回退分类请求。超时仅限制传输，不限制分析深度。
• 固定模式及 off 不请求 Jev 深度选择。模式切换、模型切换、分支恢复、会话关闭或新的提示词会使待完成请求失效并中止；过期结果不会应用。
• Pi 提供 ctx.signal 时会透传取消。但 before_agent_start 阶段可能没有操作信号，因此不能保证用户立即取消这次前置请求；生命周期取消及 10 秒超时仍然生效。
• SDK 日志关闭，不记录密钥、原始响应或服务错误正文。选择请求用量不计入 Pi 执行用量。/ultracode status 与页脚描述的是配置模式，不是父代理随证据变化的实时深度。

同一个密钥也会启用下述既有子代理 effort 选择，包括固定深度模式；其行为不变。

子代理 effort

Ultracode 不会修改父会话的 effort；以下父代理选择作为默认和 Jev 失败时的回退。父代理按分配给每个子代理的具体任务通过模型后缀选择最合适的受支持档位，不固定默认 medium 或 high，也不盲目追求最低或最高档。

每次父会话运行前，扩展都会提供本地 Pi 能力快照：当前默认子模型（ctx.model）和已注册且可用的覆盖模型，以及 Pi 能力 API 返回的各模型支持档位。切换模型或更新注册信息后，下次运行会使用新快照。裸后缀（如 :low）使用默认子模型的能力；显式模型或 agent 角色指定的模型使用各自能力，建议用完整 provider/model 标识。仅支持 low/medium/high 的模型只提供这三个选项，不会先提供七档再依赖 clamp。未知能力明确保留为未知，父代理应省略自动 effort 后缀，而不是猜测。此过程不增加模型请求。

快照来自本地注册信息，不会在线探测提供商，且运行期间可能过时；执行端仍用 clamp 保护显式请求或过时信息。SDK 单独使用 createWorkflowTool() 而不加载扩展时，不会注入此区块，宿主需自行提供能力上下文才能让父代理据此自动选择后缀。快照存在与否，都不会改写用户显式选择的 effort 或无后缀默认行为。

后缀	适用条件与排除条件	例子
:off	完全指定的机械操作；不涉及寻找修改位置、判断含义或隐藏影响	在指定位置按给定内容修正错字
:minimal	单一范围内的一次明确局部判断；不涉及跨文件追踪或多步骤实现	解释一个自包含短表达式
:low	目标清楚、方法已知、验证直接的小实现或问题；不包含根因未知的故障	给已有函数添加指定校验规则及测试
:medium	协调多个已知约束的有界多步骤实现或调查；不包含相互影响的未解决假设	在既有架构中贯通配置加载、使用和测试
:high	检验多个合理假设、追踪跨模块影响，或推理关键正确性约束；不能只凭安全或架构关键词升级	比较竞争根因，诊断跨模块状态不同步
:xhigh	多个困难问题相互作用，需要比较方案、验证跨模块不变量；文件多或笼统声称复杂不够	排查生命周期、缓存、取消相互影响的偶发故障
:max	极难的综合推理，需要严密论证及反例检验，或已有低档推理不足的具体证据；风险关键词本身不够	证明并修复涉及并发、内存安全和底层语义的全系统不变量

写代码、审查、文本长度、文件数量、风险关键词及 depth 模式都不能单独决定高档；信息不足不自动意味着 medium/high，也不能臆造复杂度。选择 high/xhigh/max 时须简述具体推理难点。最高档不要求先经历低档失败，也不要求模型支持中间档。风险决定需要验证什么，不等于所有参与代理都要高 effort。

这些分档是任务选择标准，不是跨提供商统一的能力刻度。Workflow UI 展示实际生效的 effort；未指定后缀且 Jev 未覆盖时，子会话使用正常的用户/模型配置。系统提示词、workflow 指南和 Jev 共用 src/effort-policy.ts 的分档标准，均不改变父会话 effort。skeptic 和独立 synthesis agent 都不是默认步骤。

可选 Jev 自动选择

在启动 Pi 的环境中设置非空白的 TYPESAFE_API_KEY 即启用；未设置或仅含空白时，完全保留现有父代理后缀及用户/模型默认行为。

• 每个子任务在子会话创建后、执行前，通过 @typesafe-ai/sdk 请求 jev-1.13.0，仅从实际子模型支持的 effort 中选择；成功后覆盖父代理为该子任务选择的 effort，不更换执行模型，也不修改父会话或全局默认值。
• 选择标准复用 src/effort-policy.ts。请求发送至 https://api.typesafe.ai，包含该子任务提示词（角色、额外指令、标签及输出要求）、子模型标识和支持档位；不会额外读取仓库或发送完整父会话历史。启用前请确认这些任务内容可以发送给 TypeSafe。
• 请求超时为 10 秒，不重试。网络、服务、响应格式错误或返回不受支持的档位时，保留已经解析好的父代理选择/默认 effort；回退不会额外请求模型重新判断。
• 用户取消会中止选择并终止子任务，不会执行回退任务。模型仅支持一个档位时无需请求 Jev；无法确定实际模型时保留原行为。
• UI 展示实际生效的 effort。Jev SDK 日志关闭，不记录密钥、原始响应或服务错误正文；Jev 的选择请求用量不计入子代理执行用量。

工作流示例

通常由主代理自动编写工作流。需要复用时，可以保存到 .pi/ultracode/workflows/*.workflow.js 或 ~/.pi/ultracode/workflows/*.workflow.js。只有 Pi 将项目标记为可信后，才会发现项目级工作流；用户级工作流在未信任项目中仍可使用。

export const meta = {
  name: "parallel_review",
  description: "Review correctness and tests in parallel",
};

const findings = await parallel([
  () => agent(
    "Review the current branch for correctness and lifecycle bugs.",
    { label: "correctness review" },
  ),
  () => agent(
    "Review the current branch for missing or weak regression tests.",
    { label: "test review" },
  ),
]);

return findings.filter(Boolean);

如需编辑器类型提示，请添加：

/// <reference types="pi-ultracode/workflow" />

完整工作流接口见 types/workflow.d.ts，更多示例见 examples/workflows。

角色、模型与 worktree

自定义代理角色放在：

.pi/ultracode/agents/*.md
.pi/agents/*.md
~/.pi/ultracode/agents/*.md
~/.pi/agent/agents/*.md

每次调用都可以选择角色、模型、思考强度或 worktree 隔离：

await agent("Implement and test the fix.", {
  label: "implement fix",
  agentType: "general-purpose",
  model: "anthropic/claude-sonnet-4:high",
  isolation: "worktree",
});

Worktree 隔离只能在至少有一个 commit 的 Git 仓库中使用；隔离树创建失败时会直接失败，不会回退到共享工作目录。每次调用都会获得唯一的 detached worktree。补丁集成不修改用户 index；byte-exact patch 会先在 object format 匹配的私有 Git index 中完成 cached check，再绕开仓库 attributes、filter 与 EOL 转换直接 materialize 原始 blob；冲突补丁会保存供人工恢复，不使用可能破坏 index 的三方合并回退。成功交付的补丁会保留，用于 resume 时校验共享树效果仍然存在。隔离树不会链接共享仓库的可写 node_modules；需要时请在隔离树中安装依赖，或在集成后执行最终测试。为保证补丁集成可预测，建议保持工作区干净。

执行边界

工作流默认使用 maxAgents: 128，最多并发运行 16 个代理，并只允许一层嵌套工作流。嵌套 workflow() 只接受经过 trust-aware discovery 的已保存工作流名称，不接受显式路径。累计代理上限会跨 resume 保留，缓存回放不会再次占用额度。

Workflow 子代理会保留项目上下文和普通 skills，但不会初始化环境中的 Pi 扩展，也不会暴露父级编排工具与 skill（workflow、subagent、subagent_wait 或 pi-subagents）。这样可把编排限制在父会话边界，同时允许 pi-ultracode 与 pi-subagents 在主会话中共存。项目级代理和设置遵循 Pi 的项目信任结果；内置 Explore 与 Plan 角色使用封闭的只读工具列表，不包含 shell 或写入工具。

Resume 刻意保持不可变：规范化脚本、参数、规范仓库及仓内相对 cwd、项目信任上下文、代理定义、实际模型和调用结构都必须匹配。Worktree 交付会在修改共享仓库前先写入持久恢复意图；中断或冲突的交付会阻止自动回放，并报告恢复补丁。工作内容发生变化时，应启动新的 run。

Token 和成本只用于可观测性，不作为执行预算。Worker 与 VM 限制用于确定性和存活性保护，不是安全沙箱，也不参与分析深度判断。

设计参考

• Claude Code：自然语言驱动、终端优先的 Agentic 编码体验和任务委派。
• Grok Build：显式工作流、持久 journal、有界 admission 和结构执行控制。
• Pi：模型运行时、会话、工具、扩展 API 和 TUI 都继续使用 Pi 原生能力。

pi-ultracode 是独立的 Pi 扩展，与 Anthropic 或 xAI 没有关联。

开发

npm ci
npm run typecheck
npm test
npm pack --dry-run

许可证

MIT