# StepFun 中国区 Step Plan Provider Extension

为官方 Pi Coding Agent 注册一个名为 `stepfun-cn` 的自定义 Provider，使 Pi 可以使用中国区 Step Plan 订阅套餐。

代码基线：官方 [pi-providers](https://github.com/pi-vault/pi-providers) `src/providers/stepfun-ai.ts`，仅替换中国区配置项。

## 安装

从 npm 安装 Beta 版本：

```bash
pi install "npm:@ayuanaa/pi-provider-stepfun-cn@beta"
```

临时体验而不安装：

```bash
pi -e "npm:@ayuanaa/pi-provider-stepfun-cn@beta"
```

## 认证方法

### 方法一：环境变量（推荐）

此 Provider 通过环境变量 `STEPFUN_API_KEY` 读取 API Key，**不在源码中写入或读取真实 Key**。

```bash
# 在 Pi 启动前导出（推荐）
export STEPFUN_API_KEY="<your-stepfun-api-key>"

# 或在 Pi 命令行中直接设置
STEPFUN_API_KEY="<your-stepfun-api-key>" pi -e "npm:@ayuanaa/pi-provider-stepfun-cn@beta"
```

如果你的 shell 配置文件（如 `~/.zshrc`、`~/.bashrc`）中已设置该变量，直接启动 Pi 即可。

### 方法二：/login 交互式登录

在 Pi 中运行 `/login stepfun-cn`，按提示输入中国区 Step Plan API Key。登录凭据将保存到 `auth.json`，后续启动 Pi 自动使用，无需重复输入。

认证优先级：**auth.json 登录凭据优先，环境变量 `STEPFUN_API_KEY` 作为后备**。

## 临时测试（pi -e）

```bash
# 设置 API Key
export STEPFUN_API_KEY="your-key"

# 启动 Pi 并加载 npm Package
pi -e "npm:@ayuanaa/pi-provider-stepfun-cn@beta"

# 进入 Pi 后，查看所有可用模型
# 输入 /model，确认能看到 stepfun-cn 下的模型列表
```

## /model 使用方法

**切换模型**

```
# 查看所有可用模型
/model

# 选择指定模型（示例）
/model stepfun-cn/step-3.7-flash

# 循环切换模型
Ctrl+P
```

## curl 连通性测试

在终端中直接测试 Step Plan API：

```bash
# 替换 YOUR_API_KEY 为真实 Key
curl -sS -X POST "https://api.stepfun.com/step_plan/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $STEPFUN_API_KEY" \
  -d '{
    "model": "step-3.7-flash",
    "messages": [{"role": "user", "content": "回复 OK"}],
    "max_tokens": 256,
    "reasoning_effort": "low"
  }' | jq .
```

预期返回包含 `"content": "OK"` 或类似简短回复的 JSON。

## 卸载方法

```bash
pi remove "npm:@ayuanaa/pi-provider-stepfun-cn"
```

## 安全说明

1. **API Key 管理**
   - API Key 仅通过环境变量 `STEPFUN_API_KEY` 或 `/login` 交互式输入读取
   - 源码中不写入、不硬编码任何真实 Key
   - 不输出、不记录、不验证展示完整 API Key
   - 不要将包含 Key 的 `.env` 文件提交到代码仓库
   - 建议将 `.env` 加入 `.gitignore`

2. **扩展权限**
   - Pi 扩展运行在 Pi 的上下文中，具有与 Pi 相同的系统权限
   - 此扩展仅注册一个自定义 Provider，不涉及文件读写、网络代理或系统命令执行

3. **API 请求**
   - 所有 API 请求通过 Pi 内置的 OpenAI Chat Completions 兼容层发出
   - 请求发送到 `https://api.stepfun.com/step_plan/v1`，使用标准 Bearer Token 认证
   - 不在扩展层做任何请求篡改或代理

4. **模型注册范围**
   - 仅注册 4 个对话/推理模型
   - 语音、TTS、ASR、图像生成/编辑等模型不在此扩展中注册

## 模型元数据说明

| 模型 ID | 能力 | 上下文窗口 | maxTokens | 推理强度 |
|---|---|---|---|---|
| step-3.7-flash | text, image | 256,000 | 256,000 | low / medium / high |
| step-3.5-flash-2603 | text | 256,000 | 256,000 | low / high |
| step-3.5-flash | text | 256,000 | 256,000 | high only |
| step-router-v1 | text | 384,000 | 384,000 | low / medium / high |

### step-router-v1 说明

**调用端点：** step-router-v1 **只能通过** `https://api.stepfun.com/step_plan/v1` 调用。

**自动路由：** 该模型会在 `deepseek-v4-pro` 与 `step-3.7-flash` 之间自动路由，用户无需手动选择后端模型。

**输入限制：** 只支持文字输入，**不支持图片和文档输入**。

**工具调用：** 支持普通 function tool calls，**但不支持** StepFun 内置的 `web_search` 工具类型。

**上下文窗口：** 官方明确说明 `max_tokens` 上限为 384K。`contextWindow=384000` 是当前 Pi Provider 元数据工作值，官方页面没有单独明确 Router 的 `contextWindow`，需要通过真实长上下文使用继续验证。

### 关于 cost 的说明

Step Plan 是订阅制套餐产品，不是按 token 计费。此处将 `cost` 全部设为 `0` 是一种展示策略，意味着 Pi 内部费用统计显示为 0。这**不代表模型免费**——用户已为 Step Plan 订阅套餐付费，每次 API 调用消耗的是套餐额度而非额外 token 费用。

### 需要人工确认的元数据

1. **maxTokens** — `step-router-v1` 的 `contextWindow=384000` 需要通过真实长上下文使用继续验证，官方页面未单独明确 Router 的 contextWindow。
2. **thinkingLevelMap 映射** — Pi 的 thinking levels 到 StepFun 的 reasoning_effort 的映射需要实测验证是否生效。