跳到主要内容

集成 Codex

Spark CLI 可以生成 Codex plugin，将 Spark skills 和 MCP server 一次性安装到本机。安装后，Codex 可以先理解用户意图，再选择对应的 Spark MCP 工具或 CLI 命令。

1. 安装前检查​

spark version
spark auth status
codex --version

必须先完成 Spark CLI 安装与认证。Codex 与 Spark CLI 使用同一份 ~/.spark profile，不需要再次复制 Access Secret。

2. 安装 Spark Codex Plugin​

spark integrations install codex

安装命令会：

  • 创建本机 Spark plugin，默认目录为 ~/plugins/spark。
  • 生成 skills/*/SKILL.md。
  • 写入 plugin 的 .mcp.json，MCP server 通过 spark mcp start 启动。
  • 更新个人 marketplace：~/.agents/plugins/marketplace.json。
  • 尝试执行 codex plugin add spark@personal。

检查结果：

spark integrations doctor
codex plugin list | grep spark

如果自动添加失败：

codex plugin add spark@personal

安装后关闭当前 Codex 会话并重新打开，让 skills 和 MCP 配置重新加载。

3. 如何在 Codex 中调用​

新会话中输入 /skills 查看 Spark skills。不确定使用哪个入口时，先调用：

$spark-guide

任务相关常用入口：

Skill用途
$spark-task-designer选择 App、版本并查看任务设计器上下文
$spark-task-assets管理任务类型、字段、表单、步骤、工作流和权限
$spark-task-i18n查看、导入和导出任务设计器翻译
$spark-task-check执行任务设计器 readiness 和兼容性检查
$spark-task-package导出、校验、diff 或应用任务设计器包
$spark-worklist查询我的待办、我创建的、我处理的和 TQL
$spark-sla查看任务 SLA 运行信息

Codex plugin skills 使用 $spark-* 语法，不是 /spark-* slash command。

4. 示例：让 Codex 检查工作流​

可以直接用自然语言：

调用 Spark，进入 spark-sample App 的任务设计器，列出工作流。
选择 Purchase Approval，展示节点、连线以及第 2 条连线上的规则。
先只读取，不要修改。

也可以明确指定 skills：

$spark-task-designer 切换到 spark-sample，并显示当前设计版本。
$spark-task-assets 选择 Purchase Approval 工作流，列出节点和连线规则。

Codex 最终会调用类似命令：

spark-designer task app use spark-sample
spark-designer task workflow use "Purchase Approval"
spark-designer task workflow describe --lang zh-CN
spark-designer task workflow rules 2

5. 示例：让 Codex 修改工作流​

$spark-task-assets 在当前 Purchase Approval 工作流中增加 Manager Review 节点，
绑定同名 Step，并从 Start 连接到 Manager Review。
执行前展示目标 App、版本、工作流和具体变更，等我确认后再写入。

对于写操作，Codex 应先展示变更，再在用户确认后调用带 --yes 的语义化命令。不要要求 Codex 直接生成整份 workflow JSON。

6. 示例：查询任务运行期​

$spark-worklist 查询 spark-sample 在 DEV 环境中我的待办，只显示 key、title、status、assignee。
$spark-worklist 用 TQL 查询当前由我处理且状态为 OPEN 的任务。

对应 CLI：

spark worklist my-pending \
  --app spark-sample \
  --env dev \
  --columns key,title,status,assignee

spark worklist search 'assignee = currentUser() AND status = OPEN' \
  --app spark-sample \
  --env dev

7. 更新 Plugin​

Spark CLI 增加新的 commands、skills 或 MCP tools 后，重新执行：

spark integrations install codex

然后重新打开 Codex 会话。只更新仓库而不重新安装 plugin，已经生成到 ~/plugins/spark 的 skill 内容不会自动刷新。

8. 排查​

spark integrations doctor
spark mcp inspect --json
codex plugin list
  • /skills 中没有 Spark：重新安装 plugin，并开启新会话。
  • $spark-* 不存在：确认 codex plugin list 中已经出现 Spark。
  • MCP 调用失败：先在终端执行 spark auth status，再检查 plugin .mcp.json 中的 CLI 路径。
  • 写操作未执行：多数高影响命令需要用户确认和 --yes，这是预期保护。
最后于 更新