快速上手

安装

@spark/cli的 npm 发布尚未落地（v1.0.0 已打 tag，发布步卡在 CI 凭证），当前只能从源码跑。装一次依赖、出一条 server bundle，之后的up与全局安装后的spark up走的是同一条代码路径：

git clone https://github.com/Wanfeng1028/Spark && cd Spark
pnpm install                    # Node ≥ 24 · pnpm 9
pnpm --filter @spark/cli build  # 出 server 的 esbuild 单文件 bundle

发布落地后这一段回到npm i -g @spark/cli（pnpm 为pnpm add -g @spark/cli）。

启动

进入目标项目目录，运行spark up启动本地 Agent 工作台：

cd your-project
node <Spark 仓库路径>/apps/cli/dist/main.js up   # 源码态；npm 发布后即 spark up

server 缺省绑定127.0.0.1:4318（端口取SPARK_PORT，否则落~/.spark/spark.json的server.port），仅本机可访问。

spark up轮询/api/healthz就绪后把终端交给 Ink TUI，不会替你打开浏览器。想用 Web 工作台自行访问同一地址即可——server 静态托管apps/web/dist，未知路由回 index.html。TUI 退出连带回收本命令拉起的 server 子进程，不留残留。

已有 server 在跑时，spark up探测命中直接复用，不重复拉起；自定义基址用spark up --api <url>或环境变量SPARK_API。

配置模型

引擎内置 8 家供应商目录（openai / anthropic / deepseek / openrouter / groq / together / xai / mistral），也可用 baseUrl 指向任何 OpenAI 兼容端点。首回合前在~/.spark/models.json声明一次即可，defaultModel 必填：

{
  "providers": {
    "deepseek": {
      "apiKeyEnv": "DEEPSEEK_API_KEY",
      "baseUrl": "https://api.deepseek.com/v1"
    }
  },
  "defaultModel": {
    "provider": "deepseek",
    "model": "deepseek-chat",
    "contextWindow": 128000
  }
}

API key 只从环境变量读取，不落盘、不入日志：

export DEEPSEEK_API_KEY=sk-...

共三个配置文件，均在~/.spark/下：spark.json（server 绑定与引擎行为，可缺省）、models.json（供应商与模型路由，必填）、permissions.json（审批规则表，缺省为空 = 全部落默认 ask）。加载即 zod 校验，失败报E_CONFIG启动即败，不带病运行。

开始对话

在 TUI 直接输入自然语言即可开聊；Web 工作台访问http://127.0.0.1:4318。每次工具调用的输入、输出、耗时都以事件形式实时投影到界面，写类工具与 bash 会弹审批卡（1 允许一次 / 2 总是允许 / 4 本项目总是允许 / 3 拒绝并给建议），超时未响应一律拒绝。

下一步

相关文档：