stepfun-cli

v0.2.4

Published

11 days ago

[Unofficial / personal project] CLI for the StepFun AI platform — full-platform agent toolkit (chat, multimodal, TTS/ASR, image, files, vector stores, MCP search). Not affiliated with StepFun.

stepfun-cli

███████╗████████╗███████╗██████╗ ███████╗██╗   ██╗███╗   ██╗
██╔════╝╚══██╔══╝██╔════╝██╔══██╗██╔════╝██║   ██║████╗  ██║
███████╗   ██║   █████╗  ██████╔╝█████╗  ██║   ██║██╔██╗ ██║
╚════██║   ██║   ██╔══╝  ██╔═══╝ ██╔══╝  ██║   ██║██║╚██╗██║
███████║   ██║   ███████╗██║     ██║     ╚██████╔╝██║ ╚████║
╚══════╝   ╚═╝   ╚══════╝╚═╝     ╚═╝      ╚═════╝ ╚═╝  ╚═══╝

⚠️ 个人开发项目,非 StepFun 官方出品。本项目由 @HXACA 个人维护,与 StepFun(阶跃星辰)公司无任何官方关系,仅是基于公开 API 封装的第三方 CLI。所有功能在出 bug、API 变更、服务不稳定等情况下,请通过 GitHub issue 反馈,不要打扰 StepFun 官方支持。 Personal project. Not an official StepFun product. Use at your own discretion.

功能特性

文本对话 — OpenAI 兼容的 chat completion + Anthropic 兼容的 /messages,支持流式、reasoning、tool 调用
多模态 — 一行加 --image / --image-url / --video-url,自动切到 vision 模型
TTS — 36 个系统音色 + 自定义克隆音色,sync + SSE 流式
ASR — SSE 实时(/audio/asr/sse)+ Whisper 兼容多文件(--async)
图像 — 文生图(generate)、图生图编辑(edit)、风格变体(variations)
文件 + 知识库 — 上传 / 列表 / 下载 / 删除文件;创建 / 管理 vector store(RAG 知识库)
联网搜索 — 通过 StepFun MCP 的 web_search + web_fetch,以及非 MCP 的 simple search
多通道路由 — 一个 CLI 同时覆盖 StepPlan 订阅通道和公开 /v1,根据 is_stepplan_user 自动选择
Agent 友好 — --non-interactive / --dry-run / --yes / 全量 tool schema 导出 / 全字段 JSON 输出 / 全路径 token 脱敏

安装

# AI Agent 使用(Claude Code、Cursor、OpenClaw 等 50+ Agent):添加 Skill 到你的 Agent
npx skills add HXACA/stepfun-cli -y -g

# 或全局安装 CLI 在终端中使用
npm install -g stepfun-cli

需要 Node.js 22+ 或 Bun 1.0+ 与 StepFun API key。

两条路径互补、可同时用:

npx skills add ... 走 vercel-labs/skills,自动识别本机装好的 55 个 Agent 并把 SKILL.md 挂到对应目录 — 这一步只装 Agent skill,不装 CLI 本体
npm install -g stepfun-cli 装出 stepfun 命令本体(终端可直接调用);装完还可 stepfun skill install --target all 一行挂 15 个常见 Agent skill(不依赖第三方工具的备选路径)

stepfun skill install 支持的 Agent(路径对齐 vercel-labs/skills 官方):

| Agent | --target 名 | 全局 skill 目录 | |---|---|---| | Claude Code | claude-code | ~/.claude/skills/ | | Cursor | cursor | ~/.cursor/skills/ | | Cline / Dexto / Warp | cline | ~/.agents/skills/ | | OpenCode | opencode | ~/.config/opencode/skills/ | | OpenClaw | openclaw | ~/.openclaw/skills/ | | Codex | codex | ~/.codex/skills/ | | Gemini CLI | gemini-cli | ~/.gemini/skills/ | | GitHub Copilot | github-copilot | ~/.copilot/skills/ | | iFlow CLI | iflow-cli | ~/.iflow/skills/ | | Qwen Code | qwen-code | ~/.qwen/skills/ | | Kiro CLI | kiro-cli | ~/.kiro/skills/ | | Windsurf | windsurf | ~/.codeium/windsurf/skills/ | | Trae / Trae CN | trae / trae-cn | ~/.trae/skills/ | | Roo Code | roo | ~/.roo/skills/ |

stepfun skill install 默认是软链(指向 npm 包内 SKILL.md),stepfun-cli 升级时 skill 跟着更新。要独立副本用 --mode copy。卸载: stepfun skill uninstall [--target all]。

快速开始

# 认证(写入 ~/.stepfun/config.yaml,权限 0600)
stepfun auth login --api-key sk-xxxxxxxx                       # 交互模式:询问是否 StepPlan 订阅用户
stepfun auth login --api-key sk-xxxxxxxx --stepplan            # 显式标记为 StepPlan 用户
stepfun auth login --api-key sk-xxxxxxxx --no-stepplan         # 显式标记为 /v1 用户(默认)

stepfun auth status                                            # 查看 key 来源、StepPlan 标记、解析后的 base URL

# 文本对话(chat completion 与流式 + 多模态)
stepfun text chat --message "StepFun 是什么?" --max-tokens 1000
stepfun text chat --message "解释 SSE 协议" --stream
stepfun text chat --message "图里是什么?" --image ./photo.jpg
stepfun text chat --message "描述这段视频" --video-url https://example.com/clip.mp4

# Anthropic 兼容 /messages(含 thinking + text 块)
stepfun text messages --max-tokens 1000 --message "你好" --stream

# TTS(同步 + SSE 流式)
stepfun speech synthesize --text "你好世界" --voice cixingnansheng --out hello.mp3
stepfun speech voices list                                     # 看本账户的克隆音色
stepfun speech voices catalog                                  # 内置 36 个系统音色清单
stepfun speech voices preview --voice cixingnansheng --out preview.mp3

# ASR
stepfun audio transcribe --file recording.mp3                  # 默认 SSE 流式
stepfun audio transcribe --file recording.mp3 --async          # Whisper 兼容,适合大文件

# 图像(文生图 / 图生图 / 风格变体)
stepfun image generate --prompt "一只穿宇航服的猫" --out cat.png
stepfun image edit --input cat.png --prompt "改成夜晚" --out night.png
stepfun image variations --input cat.png --prompt "油画风格" --out cat-oil.png

# 文件(用于 RAG 灌料 / 文件传输)
stepfun files upload --file report.pdf --purpose retrieval-text
stepfun files list --limit 20
stepfun files content --file-id file-abc --out local.pdf       # 仅 file-extract purpose 支持
stepfun files delete --file-id file-abc

# Vector Stores(知识库)
stepfun vector-stores create --name my_kb
stepfun vector-stores add-file --vector-store-id <vs> --file-id <fid> --description "Q3 文档"
stepfun vector-stores list-files --vector-store-id <vs>

# 模型 / token
stepfun models list
stepfun models get --model step-3.5-flash
stepfun tokens count --text "你好,世界"

# 搜索(MCP web_search + 免费 fetch + 非 MCP simple)
stepfun search "StepFun 最新动态"
stepfun search fetch https://stepfun.com
stepfun search simple "ai" --n 5

# Anthropic Claude Code / Cursor / Cline / OpenCode 集成片段
stepfun mcp config --target claude-code

命令参考

完整命令树详见 stepfun --help,设计细节见 docs/cli-design.md。

`stepfun text`

stepfun text chat --message "写一首诗"
stepfun text chat --model step-3 --message "解释 BFS" --stream
stepfun text chat --system "你是编程助手" --message "用 Go 写 Fizzbuzz"
stepfun text chat --message "user:你好" --message "assistant:嗨!" --message "你叫什么名字?"
cat messages.json | stepfun text chat --messages-file - --output json

# Anthropic /messages 协议(thinking + text content blocks)
stepfun text messages --max-tokens 1000 --message "Hi" --stream

`stepfun image`

stepfun image generate --prompt "穿宇航服的猫" --out cat.png
stepfun image generate --prompt "Logo 概念" --n 4 --out-dir ./out/ --size 512x512
stepfun image edit --input cat.png --prompt "改成夜晚" --out night.png
stepfun image variations --input cat.png --prompt "油画" --out cat-oil.png

`stepfun speech`

stepfun speech synthesize --text "你好世界" --voice cixingnansheng --out hello.mp3
stepfun speech synthesize --text "流式输出" --voice cixingnansheng --stream --out streaming.mp3
echo "头条新闻" | stepfun speech synthesize --text-file - --voice yuanqishaonv --out news.mp3
stepfun speech voices list
stepfun speech voices catalog --full --gender female --model step-tts-mini
stepfun speech voices preview --voice cixingnansheng --out preview.mp3

`stepfun audio`

stepfun audio transcribe --file recording.mp3                  # SSE 流式,实时 delta
stepfun audio transcribe --file recording.mp3 --async          # Whisper 兼容多文件
stepfun audio transcribe --file recording.mp3 --output json    # NDJSON
stepfun audio transcribe --file pcm.raw --rate 16000 --channel 1

`stepfun search`

stepfun search "StepFun 最新发布"                              # MCP web_search,¥0.04/次
stepfun search fetch https://stepfun.com                       # MCP web_fetch,免费
stepfun search simple "ai" --n 5                               # 非 MCP /v1/search

`stepfun files` · `stepfun vector-stores`

# Files
ID=$(stepfun files upload --file report.pdf --purpose retrieval-text)
stepfun files list --purpose retrieval-text
stepfun files get --file-id "$ID"
stepfun files content --file-id <file-extract-id> --out report.pdf
stepfun files delete --file-id "$ID"

# Vector Stores
VS=$(stepfun vector-stores create --name my_kb)
stepfun vector-stores list
stepfun vector-stores add-file --vector-store-id "$VS" --file-id "$ID" --description "Q3 文档"
stepfun vector-stores list-files --vector-store-id "$VS"
stepfun vector-stores delete --vector-store-id "$VS"

`stepfun models` · `stepfun tokens`

stepfun models list                                            # 当前 key 可用模型(按类别分组)
stepfun models get --model step-3.5-flash
stepfun tokens count --text "你好"
stepfun tokens count --file paragraph.txt

`stepfun auth` · `stepfun config` · `stepfun update`

stepfun auth login --api-key sk-xxxxx --stepplan               # 写 api_key + is_stepplan_user
stepfun auth status                                            # 显示 key 来源、StepPlan 标记、路由
stepfun auth logout                                            # 仅清除 api_key 字段

stepfun config show
stepfun config set --key default_text_model --value step-3.5-flash
stepfun config set --key is_stepplan_user --value true
stepfun config export-schema                                   # 配置文件 JSON Schema
stepfun config export-schema --tools                           # 全部 verb 的 OpenAI/Anthropic 工具 schema
stepfun config export-schema --command "text chat"             # 单个 verb 的工具 schema

stepfun update                                                 # 检查 npm 是否有新版本

Anthropic SDK 指向 StepFun

如果你在用 Anthropic 官方 SDK,可以让它直接打到 StepFun 的 /v1/messages 端点:

# StepPlan 通道:
export ANTHROPIC_BASE_URL="https://api.stepfun.com/step_plan"   # 不带 /v1 后缀
# 普通 /v1 通道(SDK 会自动追加 /v1):
export ANTHROPIC_BASE_URL="https://api.stepfun.com"
export ANTHROPIC_API_KEY="$STEPFUN_API_KEY"

也可以直接用本 CLI 的 text messages 命令(等价协议),不需要再装 SDK。

给 Agent 用

stepfun-cli 把"被 Agent 使用"当作一等场景。两条接入路径:

1. 注册为 Skill(推荐) — 装好 CLI 后一行命令:

stepfun skill install                 # 装到 Claude Code(默认)
stepfun skill install --target all    # 装到 Claude Code / Cursor / Cline / OpenCode
# 重启对应 Agent,即可被中英触发关键词匹配

2. 注册为 Anthropic/OpenAI 工具 — 直接拿生成的 tool schema:

stepfun config export-schema --tools > tools.json   # 29 个工具
# 你的 Agent 框架里:
# tools = JSON.parse(fs.readFileSync('tools.json')).tools
# 当模型调用 stepfun_text_chat,你 spawn `stepfun text chat --message ...`

Agent 调用时建议:

总是带 --non-interactive --quiet --output json
大命令前加 --dry-run 看一眼 envelope,不烧 quota
用 --config <path> 隔离每个 session 的 config

开发与构建

bun install                  # 装依赖(只用 zod / yaml / @clack/prompts)
bun run dev <command>        # 直接从源码跑
bun run typecheck            # tsc --noEmit
bun run lint                 # eslint
bun test                     # bun:test,~199 个用例
bun run build                # 产出 dist/stepfun.mjs(单文件,~300KB)
bash test/e2e/smoke.sh       # 端到端 70 项验收(需要真 API key)
bash test/acceptance/run-all.sh   # 完整功能验收 + 保留可听可看的 artifact

许可证

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

stepfun-cli

功能特性

安装

快速开始

命令参考

stepfun text

stepfun image

stepfun speech

stepfun audio

stepfun search

stepfun files · stepfun vector-stores

stepfun models · stepfun tokens

stepfun auth · stepfun config · stepfun update

Anthropic SDK 指向 StepFun

给 Agent 用

开发与构建

许可证

`stepfun text`

`stepfun image`

`stepfun speech`

`stepfun audio`

`stepfun search`

`stepfun files` · `stepfun vector-stores`

`stepfun models` · `stepfun tokens`

`stepfun auth` · `stepfun config` · `stepfun update`