# Pi：Cursor Agent（`pi-cursor-sdk`）

> 本文件为 **@suwenguang/pi-kb 自有口径**。在 Pi 中使用 Cursor 模型/Agent 循环，依赖社区扩展 [`pi-cursor-sdk`](https://www.npmjs.com/package/pi-cursor-sdk)（底层 `@cursor/sdk`）。由 SKILL.md「Cursor Agent」一节引用。

## 1. 能力边界

| 项 | 说明 |
|----|------|
| 扩展 | `pi-cursor-sdk`（provider：`cursor/...`） |
| 用途 | 在 Pi TUI 里跑 Cursor Agent 循环（默认 local；可显式 cloud）；保留 Cursor 原生工具链 |
| 不替代 | 本包已 bundled 的 `pi-subagents` / `pi-mcp-adapter` / `pi-deepseek-search`；IDE 内 Composer 会话本身 |
| 鉴权 | **独立** Cursor SDK API Key（不复用 Desktop / Agent CLI 登录态） |
| 推荐模型 | `cursor/composer-2-5`（以 `/model` 或 `pi --list-models cursor` 为准） |

**为何不 bundled 进本包**

`@cursor/sdk` 带按平台的 optional binary（`linux-x64` / `darwin-arm64` 等）。若打进 `bundledDependencies`，发布机会把**打包机平台**的二进制打进 tarball，跨 OS 易坏。故 Cursor 扩展保持 **业务仓配套安装**，与 DeepSeek/MCP/subagents 的 bundled 策略刻意不同。

**与已有 Pi / Cursor 配置的关系**

| 配置面 | 位置 | 说明 |
|--------|------|------|
| Pi MCP | 业务仓 `.pi/mcp.json` 等 | 本包 bundled `pi-mcp-adapter` 消费 |
| Cursor MCP | `~/.cursor/mcp.json` / 项目 `.cursor/mcp.json` | Cursor Agent 侧；可用 `PI_CURSOR_SETTING_SOURCES` 控制是否加载 |
| Pi→Cursor 桥 | `pi-cursor-sdk` 本地 MCP bridge | 把 Pi 工具以 `pi__*` 暴露给 Cursor（默认 loopback） |

三套互不自动同步；需要哪边能力就配哪边。

## 2. 配置引导（业务仓做一次）

### 2.1 安装扩展（必需）

在**业务仓根**（已 `pi install` 本包的仓库）：

```bash
pi install npm:pi-cursor-sdk -l --approve
```

`-l` 写入项目 `.pi/settings.json`；`--approve` 便于项目级 `.pi/cursor-sdk.json` 读写（Pi 0.80.9+ 对 project-local 扩展的信任要求）。

环境：

- Node.js **22.19+**
- Pi **≥ 0.76.0**（推荐与 `pi-cursor-sdk` README 当前基线一致，如 0.80.9+）

### 2.2 凭证（必需）

任选其一（**禁止**把 Key 写进仓库）：

1. Pi 内 `/login` → Use an API key → **Cursor** → 粘贴 Key（存 `~/.pi/agent/auth.json`）  
2. `export CURSOR_API_KEY='cursor_...'`  
3. 一次性：`pi --api-key 'cursor_...' --model cursor/composer-2-5 ...`

申请：[Cursor Dashboard → Integrations](https://cursor.com/dashboard/integrations)（或团队 Service Account Key）。**Team Admin API Key 暂不支持**。

### 2.3 启动与校验

```bash
pi --approve --model cursor/composer-2-5
# 或会话内 /model 选 cursor/...
pi --list-models cursor
```

无 Key 时扩展仍可能注册 fallback 模型目录；真实跑通须有效 SDK Key。登录后可用 `/cursor-refresh-models` 刷新在线目录。

烟雾测试（可选）：

```bash
pi --model cursor/composer-2-5 --cursor-no-fast --no-session --mode json \
  -p "Reply exactly PI_CURSOR_MODEL_OK and nothing else."
```

### 2.4 常见失败

| 现象 | 处理 |
|------|------|
| 无 `cursor/` 模型 | 确认已 `pi install npm:pi-cursor-sdk -l` 且 `/reload`；Node ≥ 22.19 |
| 401 / 要求配置 Key | `/login` Cursor 或设 `CURSOR_API_KEY`；勿用 Desktop 登录态冒充 |
| 项目配置不生效 | 每次带 `--approve`，或确认项目信任已批准 |
| 想用 Composer 但走了别的 provider | `pi --model cursor/composer-2-5` 或 `/model` |
| Cloud 相关报错 | 默认 local；cloud 须显式 `--cursor-runtime cloud` + ack，见上游 README |

## 3. 与 KB 工作流的配合

1. **主路径不变**：KB 阶段门禁、CodeGraph、`pi-subagents` 工种仍按本包既有口径。  
2. **换模型跑 KB**：装好扩展后，用 `cursor/composer-2-5`（或其它 `cursor/*`）执行 `/kb-*` 即可；子 Agent 是否跟主会话模型取决于 `pi-subagents` / 派发时指定。  
3. **双向工具**：需要 Cursor 调用 Pi 的 `subagent`/`mcp` 等时，依赖 `pi-cursor-sdk` 的本地 bridge（工具名 `pi__*`）；详见上游 `/cursor-tools`。  
4. **不替代**：IDE 里正在开的 Composer 会话 ≠ SDK Agent；不能把当前 Cursor IDE 聊天当 REST 给 Pi 调。

### 3.1 Cursor SDK 子会话：工具面与超时（KB 编排必读）

| 项 | 说明 |
|----|------|
| 工具面差异 | Pi 宿主会话可见 `subagent` / `pi__subagent`；**Cursor SDK 子 Agent 会话**（含 `subagent(agent=kb-admin)` spawn 出的 kb-admin）可能**仅暴露 Cursor 原生工具**（read/shell/Task 等），**不保证**有 `pi__subagent` |
| 派发 fallback | kb-admin / 主 Agent 在 Cursor 子会话内派发工种时：直接用 **Cursor `Task`** + 本包 `agents/kb-*.md` 与对应 `prompts/kb-*.md`；**禁止**长时间探测 bridge 工具面 |
| 超时硬顶 | `subagent(..., timeoutMs=900000)` **未必传递**到 Cursor SDK 子进程；实测存在 **~5 分钟（300s）** 量级 SIGTERM（exit 143）。kb-admin **单轮须短平快**（读盘 + 首批派发即结束），全长 pipeline 由**多轮** kb-admin 接力 |
| 失败解读 | exit 143 + 短 duration → **Killed/timeout**；Pi harness stderr（如 `figma-mcp-oauth-sync`）**不是**业务失败根因 |

## 4. 斜杠入口

业务仓执行：`/kb-cursor-setup`（豁免 Bootstrap 门禁）。

上游细节以 [pi-cursor-sdk README](https://github.com/fitchmultz/pi-cursor-sdk) 为准（fast/mode/cloud/resume 等）。