StepFun 中国区 Step Plan Provider Extension

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

代码基线：官方 pi-providers src/providers/stepfun-ai.ts，仅替换中国区配置项。

安装

从 npm 安装 Beta 版本：

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

临时体验而不安装：

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

认证方法

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

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

# 在 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）

# 设置 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：

# 替换 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。

卸载方法

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 的映射需要实测验证是否生效。