跳至主要内容

安装与认证

翻譯正在進行中本指南目前僅提供簡體中文版本，其他語言版本將在後續補充。

1. 准备条件​

安装前需要：

  • Node.js 18 或更高版本。
  • 能访问 Spark 服务的网络环境。
  • 一个可访问 Spark Console 的账号。
  • 在 Spark Console 系统设置 → Access Keys 中创建的 Access Key 和 Access Secret。
  • 如从源码安装，需要取得 spark-all 仓库。

:::warning 当前发布状态 当前 @hiforce/spark 尚未发布到项目配置的 npm registry。现阶段请使用源码 npm link 或从本地目录全局安装。发布完成后，本页会补充 registry 安装命令。 :::

2. 从源码安装​

进入仓库中的 spark-cli 模块：

cd <spark-all>/spark-cli
npm link
spark version
spark-designer version

npm link 会把全局 spark 和 spark-designer 两个命令链接到当前源码目录。spark 负责认证、Blueprint 和运行期能力；spark-designer 负责 Task、Page、Data、SLA 等设计器。后续 git pull 获取新版本后，一般不需要重新 link。

不希望使用 link 时，可以从本地目录安装：

cd <spark-all>
npm install -g ./spark-cli
spark version
spark-designer version

这种方式复制当前版本。仓库更新后，需要再次执行 npm install -g ./spark-cli。

如果没有全局安装权限，可以直接运行源码：

node <spark-all>/spark-cli/src/spark.js version
node <spark-all>/spark-cli/src/spark.js guide --format markdown
node <spark-all>/spark-cli/src/spark-designer.js guide --format markdown

下文分别使用 spark 和 spark-designer。直接运行源码时，分别替换为 node <spark-all>/spark-cli/src/spark.js 和 node <spark-all>/spark-cli/src/spark-designer.js。

3. 创建 Access Key​

在 Spark Console 中进入 系统设置 → Access Keys，创建一组用于自动化访问的凭据。Access Secret 应在创建时妥善保存，不要写入文档、聊天记录或 Git 仓库。

CLI 不签发 Access Key，也不使用浏览器 Cookie。它只把用户提供的凭据保存到本机，并在调用 Spark API 时携带认证头。

4. 创建认证 Profile​

spark auth set \
  --profile spark-dev \
  --base-url https://spark.hiforce.ai \
  --access-key <Access Key> \
  --access-secret <Access Secret>

验证连接：

spark auth status

管理多个 profile：

spark auth list
spark auth use spark-dev
spark auth remove old-profile

本地文件默认位于：

~/.spark/config.json
~/.spark/credentials.json

不要把 ~/.spark/credentials.json 提交到版本库，也不要在 CI 日志中打印 Access Secret。

5. 单次命令覆盖配置​

临时选择另一个 profile：

SPARK_PROFILE=spark-test spark auth status

CI 或临时 shell 也可以直接提供环境变量：

SPARK_BASE_URL=https://spark.hiforce.ai \
SPARK_ACCESS_KEY=<Access Key> \
SPARK_ACCESS_SECRET=<Access Secret> \
spark auth status --json

环境变量只应用于当前命令，不会自动写入本地 credentials 文件。

6. 完成安装检查​

spark version
spark-designer version
spark auth status
spark guide --format markdown
spark-designer guide --format markdown
spark integrations list
spark integrations doctor

spark integrations doctor 会显示 Node.js 版本、Spark 配置位置、Claude command 目录和 Codex plugin 目录，但不会打印 Access Secret。

7. 更新与卸载​

源码 link 安装：

cd <spark-all>
git pull --ff-only
spark version

本地复制安装：

cd <spark-all>
git pull --ff-only
npm install -g ./spark-cli

卸载全局命令：

npm uninstall -g @hiforce/spark

卸载 CLI 不会自动删除 ~/.spark 中的 profile。需要彻底清理时，应先确认没有其他 Spark 自动化任务使用这些凭据，再手工删除对应文件。

8. 常见问题​

spark: command not found​

确认 npm 全局 bin 目录已经加入 PATH，或直接用源码命令验证：

npm prefix -g
node <spark-all>/spark-cli/src/spark.js version

Spark CLI is not configured​

执行 spark auth set，然后用 spark auth status 验证当前 profile。

当前 profile 不正确​

spark auth list
spark auth use <profile>
spark auth status

下一步：集成 Codex 或 集成 Claude Code。

最後於 更新