@fitchmultz: 使用 GPT-5.5 xhigh 作为规划者 + Composer 2.5 子代理作为实现者，比单独使用任一模型完成所有任务效果更好。在 pi (pi-…

GPT-5.5 xhigh 作为规划者 + Composer 2.5 子代理作为执行者，比任一模型单独完成所有任务更胜一筹。在 pi（pi-cursor-sdk）中，我的循环是：1. xhigh 研究并编写计划 2. xhigh 将实现委托给 Composer 2.5 子代理：工作树、分支、拉取请求 3. 每个都进行严格的 PR 审查（使用 Cursor 的“热核”模式：不留任何发现）。Composer 子代理修复直至通过 4. 我手动审查合并就绪的 PR 并交付。比 xhigh 单独更快。比 Composer 单独更彻底。你用什么：一个超级代理，还是规划者 + 执行者子代理？http://github.com/fitchmultz/pi-cursor-sdk… — # fitchmultz/pi-cursor-sdk 来源：https://github.com/fitchmultz/pi-cursor-sdk # pi-cursor-sdk 一个 pi 提供方扩展，允许 pi 通过本地 @cursor/sdk 代理运行时使用 Cursor 模型。如果你想在 pi 内使用 Cursor 的模型目录，同时保留 pi 原生的模型选择器、SDK 暴露的思考控制、会话恢复、上下文显示和默认页脚用户体验，请使用此扩展。 ## 快速入门 1. 安装包： bash pi install npm:pi-cursor-sdk 或从 GitHub 安装： bash pi install https://github.com/fitchmultz/pi-cursor-sdk 2. 使用 Cursor 模型启动 pi： bash pi --model cursor/composer-2.5 3. 在 pi 中，运行 /login，选择 使用 API 密钥，选择 Cursor，并粘贴你的 Cursor API 密钥。如果 pi 启动时没有密钥，请在 /login 后运行 /cursor-refresh-models 以刷新完整的实时 Cursor 模型目录，无需重启 pi。在 pi 中，使用 /model 选择另一个 Cursor 模型。 ## 要求 - Node.js 22.19+ - pi - 通过 /login 保存的 Cursor API 密钥，作为 CURSOR_API_KEY 可用，或通过 pi 的 --api-key 传递 无需全局安装 @cursor/sdk。此包依赖于 @cursor/sdk，因此正常安装包会带来此扩展构建和测试时使用的 SDK 版本。 ## 安装 ### 全局安装 bash pi install npm:pi-cursor-sdk 替代的 GitHub 安装： bash pi install https://github.com/fitchmultz/pi-cursor-sdk ### 项目本地安装 如果你希望包记录到当前项目的 .pi/settings.json 中，而不是全局 pi 设置，请使用 -l： bash pi install -l npm:pi-cursor-sdk ### 从本地检出尝试 从此仓库进行开发： bash npm install pi -e . --model cursor/composer-2.5 ## 配置你的 Cursor API 密钥 推荐设置： bash pi --model cursor/composer-2.5 然后，在 pi 内： 1. 运行 /login。 2. 选择 使用 API 密钥。 3. 选择 Cursor。 4. 粘贴你的 Cursor API 密钥。 5. 密钥保存在 pi 原生的 ~/.pi/agent/auth.json 中。 如果 pi 启动时没有密钥，备用 Cursor 模型仍然会注册，以便可以访问 /login。在 /login 后，备用模型运行可以使用已存储的密钥，并且 /cursor-refresh-models 会刷新从 Cursor SDK 发现到的完整实时 Cursor 模型目录，无需重启 pi。 环境设置： bash export CURSOR_API_KEY="your-key" pi --model cursor/composer-2.5 一次性设置： bash pi --api-key "your-key" --model cursor/composer-2.5 --cursor-no-fast -p "Say ok only." 发现过程使用 pi 原生的此扩展的解析顺序：--api-key、存储在 ~/.pi/agent/auth.json 中的 cursor 密钥，然后是 CURSOR_API_KEY。不要将 API 密钥存储在 ~/.pi/agent/cursor-sdk.json 中。该文件仅用于非秘密的扩展状态，例如 Cursor 快速默认设置。 PATH 仅用于可执行文件查找，不应包含 API 密钥。 ## 验证你的设置 列出 Cursor 模型： bash pi --list-models cursor 预期行为： - 使用有效密钥时，Cursor 模型显示在 cursor 提供方下 - 如果发现无法验证或访问 Cursor，pi 可能仍会显示备用 Cursor 模型；通过 /login 添加认证后，备用模型运行可以使用保存的密钥，并且 /cursor-refresh-models 会刷新实时目录 冒烟测试： bash pi --model cursor/composer-2.5 --cursor-no-fast -p "Reply with: ok" ## 选择模型 使用 /model 交互式选择 Cursor 模型，或在命令行传递模型： bash pi --model cursor/composer-2.5 pi --model cursor/gpt-5.5@1m pi --model cursor/gpt-5.5@272k pi --model cursor/claude-opus-4-7@300k 如何阅读模型 ID： - cursor/... 是此扩展注册的 Cursor 提供方 - @1m、@272k 和 @300k 是上下文窗口变体 - :medium、:high 和 :xhigh 是 pi 思考级别的后缀，用于 Cursor SDK 暴露了 pi 可控的思考参数的模型 - Cursor.models.list() 返回的明确最新风格的 Cursor 别名也会注册，当目标模型具有上下文变体时，使用相同的上下文后缀；被多个基础模型共享或与基础模型 ID 冲突的别名会被跳过，因为它们的 SDK 解析和显示的元数据可能不一致 带 pi 思考控制的示例： bash pi --model cursor/gpt-5.5@1m:medium pi --model cursor/gpt-5.5@272k:xhigh pi --model cursor/gpt-5.5@1m --thinking medium Cursor 专属参数不会编码到 pi 模型 ID 中。Cursor 的 context 成为 pi 可见的模型变体，因为它会改变 pi 原生的 contextWindow；Cursor 的 fast 是扩展状态，而不是模型身份。别名模型 ID 仍与其底层 Cursor 基础模型共享 Cursor 专属状态，例如快速默认设置。 ## 思考支持 所有 Cursor SDK 模型都应被视为具备思考能力的 Cursor 模型。pi --list-models 中的 thinking 列范围更窄：它仅表示 pi 可以控制该模型的一个 Cursor SDK 思考参数。对于 Cursor 暴露了 reasoning、effort 或布尔值 thinking 参数的模型，pi 原生的思考控制会映射到 Cursor SDK 参数： - reasoning=none|low|medium|high|extra-high - effort=low|medium|high|xhigh|max - thinking=false|true 适用于布尔值思考模型 对于同时具备 thinking 和 effort 的 Claude 模型，pi 思考 off 会发送 thinking=false 并省略 effort。 ### 为什么某些 Cursor 模型显示 thinking=no 在 pi --list-models 中，thinking=no 意味着 pi 无法使用 --thinking、最终 :medium 模型后缀或 shift+tab 来控制模型的思考级别。这并不意味着该 Cursor 模型不能思考。某些 Cursor SDK 模型没有暴露 reasoning、effort 或 thinking 参数供扩展设置。Cursor 的思考仍然被模型启用/支持，并且 Cursor 仍可能发出思考增量。当 SDK 发出这些增量时，扩展会通过 pi 原生的思考渲染来呈现它们。 ## 快速模式 使用 /cursor-fast 来持久切换所选 Cursor 模型的快速模式（如果该模型支持 Cursor 的 fast 参数）。快速偏好会按 Cursor 基础模型记住并存储： - 当前会话中，通过 pi.appendEntry() - 全局存储于 ~/.pi/agent/cursor-sdk.json 对于单次运行，强制开启或关闭快速模式而不更改保存的默认设置： bash pi --model cursor/gpt-5.5@1m --cursor-fast -p "Say ok only" pi --model cursor/composer-2.5 --cursor-no-fast -p "Say ok only" Composer 2 和 Composer 2.5 可以默认使用快速模式。使用 --cursor-no-fast 进行单次非快速 Composer 运行。在打印模式（-p）下，--cursor-no-fast 是静默的，不会写入 ~/.pi/agent/cursor-sdk.json。在交互模式下，页脚仅在快速模式启用时显示快速模式： text cursor fast 如果看不到 cursor fast，则快速模式已关闭。 ## 图片 最新用户消息中的图片会转发给 Cursor。历史图片不会包含在记录中，仅作为 [image omitted from transcript] 占位符出现，因此有关较早图片的后续问题应重新附加图片或包含文字描述。此扩展为 Cursor 模型声明了 text 和 image 输入，因为 Cursor 的 SDK 接受图片消息，并且 Cursor 模型预期支持它们。 ## Cursor 提供方工具契约 Cursor 运行使用本地的 Cursor SDK 代理，具有两个独立的工具界面： - Cursor 原生界面： Cursor 本地代理工具、Cursor 设置、插件和配置的 Cursor MCP 服务器。这些仍由 Cursor SDK 本地代理路径拥有。 - pi 桥接界面： pi-cursor-sdk 通过一个每运行本地的环回 MCP 桥接器公开可桥接的活跃 pi 工具（当桥接器启用且当前 pi 工具注册表公开了工具时）。桥接能力在每次 Cursor 运行时从 pi.getActiveTools() 和 pi.getAllTools() 快照获取。 当当前运行中暴露了这些工具时，Cursor 会看到活跃的可桥接 pi 工具，其 MCP 名称为碰撞安全的形式，例如 pi__sem_reindex。Pi 会话输出、工具卡片、确认、钩子、渲染器、历史和中止行为使用真实的 pi 工具名称，例如 sem_reindex。桥接器会排队 Cursor 的 MCP 调用，发出一个正常的 pi toolCall，等待匹配的 pi toolResult，然后将该结果解析回同一个活跃的 Cursor SDK 运行，而无需创建新的 Agent，除非该运行已被处置、中止或取消。桥接器不会直接调用 pi 工具的 execute() 处理程序。 重叠的内置 pi 工具（read、bash、write、edit、grep、find、ls）默认被隐藏，因为 Cursor 本地代理已经具有原生等效项。扩展/自定义工具以及 pi 活跃工具注册表中存在的非重叠活跃工具通常保持暴露。 当启用时，桥接器还会将 cursor_ask_question 作为 pi__cursor_ask_question 暴露，允许 Cursor 通过 pi 用户界面询问用户，而不是静默选择默认值。 Cursor 原生工具回放与桥接器是分开的。回放卡片是仅供显示的记录 Cursor SDK 活动。它们永远不会重新运行 Cursor 端命令、重新应用 Cursor 编辑、调用 MCP 服务器或改变 pi 状态。请参阅 Cursor 原生工具回放。 桥接器控制： bash # 仅回退到 Cursor SDK 工具/设置/MCP；不要通过桥接器暴露活跃的 pi 工具。 PI_CURSOR_PI_TOOL_BRIDGE=0 pi --model cursor/composer-2.5 # 选择加入，也通过桥接器暴露重叠的 pi 工具名称。 PI_CURSOR_EXPOSE_BUILTIN_TOOLS=1 pi --model cursor/composer-2.5 # 覆盖 Cursor SDK MCP 工具调用超时，包括桥接的 pi 工具和配置的 Cursor MCP 服务器。 PI_CURSOR_MCP_TOOL_TIMEOUT_SECONDS=7200 pi --model cursor/composer-2.5 PI_CURSOR_MCP_TOOL_TIMEOUT_MS=7200000 pi --model cursor/composer-2.5 # 将脱敏的桥接诊断信息作为 JSONL 输出到 stderr，前缀为 [pi-cursor-sdk:bridge]。 PI_CURSOR_PI_TOOL_BRIDGE_DEBUG=1 pi --model cursor/composer-2.5 PI_CURSOR_PI_TOOL_BRIDGE=0 是支持的回退标志，并完全禁用桥接器。桥接器也将 false、off、none、no 和 disabled 视为关闭；将 1、true、on、yes 和 enabled 视为开启。 PI_CURSOR_EXPOSE_BUILTIN_TOOLS=1 可选择加入暴露重叠的 pi 工具名称（Cursor 已有原生等效项）。 Cursor MCP 超时覆盖默认为 3600 秒，因为安装的 Cursor SDK 具有 60 秒的 MCP 请求默认值，对于某些本地 MCP 工具（包括桥接的 pi 工具和配置的 Cursor MCP 服务器）来说太短。 PI_CURSOR_PI_TOOL_BRIDGE_DEBUG=1 默认关闭，它会向 process.stderr 发出类型化、白名单化、脱敏的单行 JSONL 记录。这些记录是操作诊断信息，而不是匿名遥测：它们故意包含工具名称、安全关联 ID、桥接运行状态、公开的 pi↔MCP 名称对、排队的请求、结果解析、拒绝、取消和待处理计数。它们不得包含端点 URL、端点路径组件、端点令牌、原始参数/结果、stdout/stderr 负载、文件内容、Cursor 设置输出、API 密钥、承载令牌、cookie、会话凭据或秘密。如果工具名称本身是敏感的，请不要启用或分享桥接调试日志。 ### 维护者实时冒烟发布门禁 对于 Cursor 提供方/运行时的更改，请在发布前遵循手动 Cursor 实时冒烟检查清单。请参阅 Cursor 测试经验教训，了解 auth.json 种子化、隔离的 /tmp 测试框架布局、JSONL 回放错误扫描和其他回归陷阱。假设每个运行时表面都在范围内。该清单使用真实的 pi -e . --cursor-no-fast --model cursor/composer-2.5 运行，使用临时会话目录，并要求可见的 TUI/输出、脱敏的诊断信息和持久化的 JSONL 保持一致。如果存在可选、延迟、部分通过或未经观察的冒烟检查，不要将版本标记为就绪。 ### 维护者 Cursor SDK 事件捕获 使用 npm run debug:sdk-events 捕获一次直接 @cursor/sdk 运行时的时间戳 run.stream()、onDelta 和 onStep 时间线。使用 npm run debug:provider-events 捕获 通过 pi 的 Cursor 提供方（会话代理重用、桥接、原生回放、发送规划）的相同 onDelta/onStep 负载。工件默认位于 gitignored 的 .debug/cursor-sdk-events/ 目录下。交互式多轮 pi 会话将轮次分组在 .debug/cursor-sdk-events/sessions/<session-id>/turn-NNN-.../ 下，并附带一个 session.json 索引。你也可以在任何 pi 运行期间通过 PI_CURSOR_SDK_EVENT_DEBUG=1 选择加入；默认情况下捕获仅针对文件，因此 pi TUI 保持正常。请参阅 Cursor 测试经验教训 了解用法、工件布局和安全说明。 ## 备用模型 如果没有来自 /login、CURSOR_API_KEY 或 --api-key 的可用密钥，模型发现失败，或者发现未返回任何模型，此扩展会注册一个捆绑的备用快照，其中包含最新审查的 Cursor SDK 模型目录，并在可能时通知交互式用户。备用快照包括 Composer 2.5（composer-2.5 和 composer-2-5）、Composer 2、GPT、Claude、Gemini、Grok、Kimi 以及审查过的 Cursor.models.list() 输出暴露的其他模型 ID。确切的检入快照位于 src/cursor-fallback-models.generated.ts 中。 实际的 Cursor 运行仍需要来自 /login、CURSOR_API_KEY 或 --api-key 的密钥。如果在启动后添加了认证，请运行 /cursor-refresh-models 以刷新完整的实时 Cursor 模型目录，无需重启 pi。 ## 限制 - 仅限本地 Cursor SDK 代理。 此扩展不使用 Cursor 云代理。云 pi 工具桥接不在范围内，因为它需要单独的认证、传输、生命周期和远程信任设计。 - pi 工具桥接是本地且基于 MCP 的。 可桥接的活跃 pi 工具通过令牌化的 127.0.0.1 MCP 端点暴露给本地 Cursor 代理；内部 Cursor 回放活动名称被排除，重叠的内置 pi 工具默认被隐藏。设置 PI_CURSOR_PI_TOOL_BRIDGE=0 以禁用它，或设置 PI_CURSOR_EXPOSE_BUILTIN_TOOLS=1 以同时暴露重叠的内置工具。 - Cursor 原生工具回放仅供显示。 回放会渲染记录的 Cursor SDK 活动，永远不会重新运行 Cursor 端命令、重新应用 Cursor 编辑、调用 MCP 服务器或改变 pi 状态。工作流工具（例如 Cursor SwitchMode 和 Cursor 待办状态）不是 pi 工作流控制。请参阅 Cursor 原生工具回放 了解支持的回放卡片、排序、冲突处理和选择退出标志。 - Cursor 运行状态可以跨越工具使用轮次。 在 pi 会话中，此扩展在兼容的后续轮次中重用同一个 Cursor SDK 代理，并在上下文仍然匹配时发送增量提示。当上下文分歧时，在压缩或 /tree 导航后，API 密钥更改时，发送错误后，或会话关闭时，它会重新创建代理。对于桥接的 pi 工具，匹配的 pi toolResult 会解析回同一个活跃的 Cursor SDK 运行，而无需创建新的 Agent，除非该运行已被处置、中止或取消。回放也可以将一次活跃的 Cursor SDK 运行分割到多个 pi toolUse 轮次中进行显示。 - Cursor 设置源默认为全部。 此扩展默认传递 local.settingSources: ["all"]，以便配置的 Cursor MCP 服务器、插件工具、项目/用户设置以及相关的 Cursor 原生能力像在 Cursor 中一样可用。要缩小加载范围，请设置一个逗号分隔的