跳至主要内容

Spark Blueprint AI CLI 从零使用指南

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

本篇面向第一次使用 Spark Blueprint AI CLI 的用户。按本文完成后，你可以在本机通过命令行、Codex 或 Claude Code 操作 Spark 的业务蓝图、业务域、调研中心和 AI 抽取候选。

:::tip 统一的 Spark CLI 手册 通用安装、认证和 AI 助手集成已经维护在独立的 Spark CLI 手册 中。本篇重点介绍 Blueprint 模块；首次使用时建议先完成 安装与认证。 :::

当前已完成的命令范围：

  • 蓝图：创建、查看、切换当前蓝图、更新基础信息、创建快照、删除临时蓝图。
  • 业务域：查看矩阵、创建概念域 / 列域 / 行域 / 业务域 / 子域、更新、移动、删除、导入模板。
  • 调研中心：查看证据、创建访谈、上传材料、追加附件、标记状态、发起 AI 抽取、查看抽取批次。
  • AI 候选：查看、忽略、恢复、确认入库。
  • 报告：overview、domains、discovery。

为什么 FDE 需要 Spark Blueprint AI CLI / MCP​

FDE 的工作通常不是单纯录入数据，而是在客户访谈、行业参考模型、现有系统信息和目标业务蓝图之间持续做判断。传统方式下，FDE 需要在浏览器、文档、聊天窗口和命令行之间来回切换：先整理访谈材料，再查找 eTOM、APQC 或客户侧术语，再回到系统里筛选证据、发起 AI 抽取、评审候选项、补充蓝图资产。这个过程容易丢上下文，也不容易复用。

Spark Blueprint AI CLI 和 MCP 的目标，是把 Spark 的蓝图能力变成 AI Agent 可以稳定调用的工作台操作层。FDE 可以继续使用自然语言描述任务，例如“把当前未 AI 分解的调研事项进行筛选提取，提取时参考 eTOM Assurance 和 Resource Trouble Management”，由 Codex 或 Claude Code 先整理外部参考，再通过 Spark MCP 把证据范围、蓝图上下文和抽取要求一起传给 Spark。这样 AI 不只是回答问题，而是带着上下文推动蓝图工作向前走。

对客户来说，这带来的价值主要有四点：

  • 更快形成可评审的蓝图资产。访谈、材料和现场问题可以快速转成候选业务域、能力、流程、业务对象和痛点，缩短从 Discovery 到 Blueprint Review 的周期。
  • 更容易解释 AI 结果。每个候选项都应保留来源证据、抽取批次、置信度和建议归属，客户可以看到“为什么这样判断”，而不是只看到一段不可追溯的 AI 总结。
  • 更好复用行业方法。eTOM、APQC、ITIL、客户内部术语表等参考材料可以作为分类和归属提示进入抽取过程，但事实来源仍然受 Discovery evidence 约束，避免 AI 编造未被访谈支持的内容。
  • 更适合治理和交付沉淀。候选项可以先进入 review 状态，再由 FDE 或客户代表确认、忽略、恢复或重新抽取，关键动作都可以保留在 Spark 中。

对 FDE 来说，它不是一组需要死记硬背的命令，而是一个可自动化的工作方式：

  • 可以在一个 AI 会话里完成列蓝图、切换当前蓝图、查看调研证据、触发 AI 抽取、查看候选项和生成报告。
  • 可以让 AI 在调用 Spark 前先做必要的行业资料整理，并把整理结果明确写入 instruction，确保后端抽取请求真正收到这些参考信息。
  • 可以把常见交付动作固化为 Agent Flow，例如 Start、Evidence Select、Blueprint Context Load、Reference Guidance Merge、AI Extract、Validate、Normalize、Save Candidates。
  • 可以做批处理和自动巡检，例如查找未抽取证据、重跑失败批次、筛选低置信度候选项、生成周报或月报。

因此，Spark Blueprint AI CLI / MCP 的定位不是替代 Spark Console 页面，也不是让用户记住更多命令。它更适合作为 FDE 的 AI 工作入口：页面负责可视化评审和治理，CLI / MCP 负责让 AI Agent 安全、可追溯、可重复地调用 Spark 能力。

1. 准备条件​

你需要先准备：

  • Node.js 18 或更高版本。
  • 可以访问 Spark 的账号。
  • 在 Spark Console 系统设置中由你自己生成的 Access Key 和 Access Secret。
  • Spark 服务地址，例如：
https://spark.hiforce.ai

Access Key 和 Access Secret 不是 CLI 分配的。CLI 只负责把你在 Spark 系统里生成的凭据保存到本机配置文件中。

2. 安装 Spark CLI​

如果已经发布到 npm，使用：

npm install -g @hiforce/spark
spark version

如果你是从源码仓库安装，进入 spark-cli 目录：

cd /home/code/spark/spark-all/spark-cli
npm link
spark version

如果不想全局 link，也可以直接用源码运行：

node /home/code/spark/spark-all/spark-cli/src/spark.js version

下面示例都用 spark。如果你没有全局安装，把 spark 替换成：

node /home/code/spark/spark-all/spark-cli/src/spark.js

3. 初始化 Spark Access Key​

把你自己生成的 Access Key 写入本机：

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

也支持 key=value 写法，方便 AI command 使用：

spark auth set \
  profile=spark-deploy \
  baseUrl=https://spark.hiforce.ai \
  accessKey=<你的 Access Key> \
  accessSecret=<你的 Access Secret>

验证连接：

spark auth status

查看本机 profile：

spark auth list

切换 profile：

spark auth use spark-deploy

4. 设置当前工作蓝图​

先列出可访问的蓝图：

spark blueprint list

切换当前工作蓝图：

spark blueprint use bp-1780146277372

查看当前工作蓝图：

spark blueprint current

设置当前工作蓝图后，大多数蓝图子命令都可以省略 <blueprint> 参数。例如：

spark blueprint show
spark discovery list --status NOT_EXTRACTED
spark domains matrix --level L0

如果你还没有蓝图，可以创建并直接切换：

spark blueprint create \
  --customer "ACME Telecom" \
  --engagement "OSS/BSS Discovery" \
  --use

5. 常用 CLI 命令​

查看命令指南：

spark guide
spark guide blueprint
spark guide blueprint discovery
spark guide blueprint domains
spark guide blueprint candidates

spark guide 的 Markdown 输出是两列表格：Command 展示可执行命令，Description 说明该命令用途。需要给 AI 或脚本读取时，可以追加 --format json，JSON 中会同时保留原始 usage 和带说明的 entries。

业务域：

spark domains matrix --level L0
spark blueprint domains show <domain-code-or-id>
spark blueprint domains create-concept --name "Operations" --colspan 1 --yes
spark blueprint domains create-domain --name "Problem Handling" --columns <column-id> --row <row-id> --yes

调研中心：

spark discovery list --status NOT_EXTRACTED
spark blueprint discovery show DC-001
spark blueprint discovery create-interview --subject "Fault Order Interview" --interviewee "Operations Lead"
spark blueprint discovery upload --path ./materials --note "现场补充材料" --yes
spark blueprint discovery extract --codes DC-001,DC-002 --instruction "重点识别故障工单相关能力" --wait

--instruction 不只是“关注点”文本。Codex / Claude 如果在抽取前查询了 eTOM、行业参考模型或客户侧术语映射，必须把相关结论摘要放进 --instruction，否则 Spark 后端 AI 抽取只会收到 Blueprint context 与 Discovery evidence，不会知道前面查询过的外部参考。外部参考只能作为分类和归属提示，候选事实和 sourceQuote 仍必须来自证据本身。

AI 候选：

spark candidates list --status SUGGESTED
spark blueprint candidates show AC-001
spark blueprint candidates ignore AC-001 --reason "重复候选"
spark blueprint candidates accept AC-001 --target-type domain --domain <domain-id-or-code> --yes

报告：

spark blueprint report --scope overview --format markdown
spark blueprint report --scope domains --format markdown
spark blueprint report --scope discovery --format markdown

6. 在 Codex 中安装 Spark Plugin​

安装 Codex 集成：

spark integrations install codex

这个命令会完成几件事：

  • 创建本机 Codex plugin：~/plugins/spark
  • 生成 Codex skills：~/plugins/spark/skills/*/SKILL.md
  • 写入 Spark MCP server：~/plugins/spark/.mcp.json
  • 写入个人 marketplace：~/.agents/plugins/marketplace.json
  • 执行 codex plugin add spark@personal

验证：

codex plugin list | grep spark

安装成功后，命令行输出里会包含：

  • start：推荐第一入口，通常是 $spark-guide。
  • discover：在 Codex 中查看 skills 的入口，通常是 /skills。
  • skills：当前 Spark plugin 提供的 $spark-* skill 清单。

如果安装命令提示 codex plugin add 失败，可以手工执行：

codex plugin add spark@personal

安装后需要开启一个新的 Codex 会话。重新进入后，可以通过 /skills 查看 Spark skills，或直接在输入中显式引用：

$spark-guide
$spark-set-access-key
$spark-blueprints
$spark-blueprint
$spark-domains
$spark-discovery
$spark-candidates
$spark-report

注意：当前 Codex CLI 不会把插件目录里的 commands/*.md 自动注册成 /spark-* slash command。如果输入 /spark-blueprints 看到 Unrecognized command，说明你在找旧入口；请改用 $spark-blueprints、/skills 或自然语言。

6.1 如何知道有哪些 Codex 入口​

推荐顺序：

  1. 安装完成后先看 spark integrations install codex 的输出，其中 skills 字段会列出所有可用入口。
  2. 新开 Codex 会话后输入 /skills，在 skills 列表中查看 Spark。
  3. 不确定用哪个入口时，先输入 $spark-guide。
  4. 也可以直接用自然语言，例如“调用 Spark 列出我可以访问的业务蓝图”。

当前 Spark Codex skills：

$spark-guide
$spark-set-access-key
$spark-blueprints
$spark-blueprint
$spark-domains
$spark-discovery
$spark-candidates
$spark-report

如果 Codex 里没有 Spark plugin：

  1. 确认插件已安装：
codex plugin list | grep spark
  1. 重新安装：
spark integrations install codex
codex plugin add spark@personal
  1. 关闭当前 Codex 会话，重新打开一个新会话。

6.2 Codex 初始化示例​

在 Codex 中输入：

$spark-set-access-key baseUrl=https://spark.hiforce.ai accessKey=<你的 Access Key> accessSecret=<你的 Access Secret>

然后输入：

$spark-blueprints use bp-1780146277372

再输入：

$spark-discovery list --status NOT_EXTRACTED

Discovery 列表展示后，Codex 会继续给出 Next Actions。生成到 Codex skill 里的 prompt 默认使用英文动作标签，例如：

  • Add interview/material
  • Extract all pending evidence
  • Extract specific evidence
  • Review extraction results/candidates

每个 Next Actions 都应带上可以复制的命令或可以直接发送给 Codex 的自然语言。如果证据已经是 EXTRACTED，但你想换一个关注点重新抽取，可以这样说：

Re-extract DC-001 with a focus on alarm delay, auto-close rules, and field dispatch routing.

CLI 形式：

spark blueprint discovery extract \
  --codes DC-001 \
  --instruction "Focus on alarm delay, auto-close rules, and field dispatch routing." \
  --force \
  --wait

如果你要求 Codex 先查询 eTOM 或其他规范，再做抽取，确认它最终调用 extraction 时把查询结论写进 instruction。例如：

spark blueprint discovery extract \
  --codes DC-001 \
  --instruction "Focus on alarm delay, auto-close rules, and field dispatch routing. eTOM reference: classify assurance fault handling under Service Problem Management or Resource Trouble Management when the evidence supports it." \
  --force \
  --wait

你也可以直接用自然语言：

Show the current Blueprint domain matrix.
Extract DC-001 and DC-002 with a focus on Problem Handling domains and business objects.
Create an interview evidence item for a regional environment-alarm handling case, and ask for confirmation before saving it.

Codex plugin 内置了 Spark MCP server，读操作会优先走 MCP tools；需要上传本地文件或修改数据时，Codex 应先展示影响范围并让你确认。

7. 在 Claude Code 中安装 Spark Commands​

安装 Claude Code slash commands：

spark integrations install claude

默认会写入：

~/.claude/commands/

如果你想指定目录：

spark integrations install claude --dir ~/.claude/commands

重新打开 Claude Code 后，可以输入：

/spark-guide
/spark-discovery
/spark-domains
/spark-candidates

Claude Code command 里的 prompt 也默认使用英文，并且后续操作必须使用 Claude 语境下的 /spark-* slash command 或 spark ... CLI 命令。例如 /spark-discovery 列表后查看候选，应提示：

/spark-candidates list --status SUGGESTED

已抽取证据需要换关注点重抽时，应提示：

spark blueprint discovery extract \
  --codes DC-001 \
  --instruction "Focus on alarm delay, auto-close rules, and field dispatch routing." \
  --force \
  --wait

如果 slash command / MCP agent 在前置步骤中查询了 eTOM 等参考资料，必须把摘要放入 --instruction 或 MCP instruction 参数；不要只在聊天回复里说明“已查询”，否则后端 AI 抽取请求不会包含这些参考信息。

初始化示例：

/spark-set-access-key baseUrl=https://spark.hiforce.ai accessKey=<你的 Access Key> accessSecret=<你的 Access Secret>
/spark-blueprints use bp-1780146277372
/spark-discovery list --status NOT_EXTRACTED

8. 本地配置文件位置​

Spark CLI 会把配置和凭据分别保存：

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

Codex plugin 文件：

~/plugins/spark/
~/.agents/plugins/marketplace.json
~/plugins/spark/skills/spark-blueprints/SKILL.md
~/plugins/spark/.mcp.json

Claude Code command 文件：

~/.claude/commands/spark-guide.md
~/.claude/commands/spark-discovery.md

Access Secret 只保存在本机 credentials 文件中，不应提交到 Git。

9. 常见问题​

9.1 Codex 里输入 /spark-blueprints 提示 Unrecognized command​

这是正常现象。当前 Codex CLI 不会把 Spark plugin 内的文件注册成 /spark-* slash command。请使用：

$spark-blueprints

或者直接用自然语言：

调用 Spark 列出我可以访问的业务蓝图。

如果 $spark-blueprints 也没有触发，先确认插件是否安装：

codex plugin list | grep spark

如果没有：

spark integrations install codex
codex plugin add spark@personal

然后重新打开 Codex 新会话，再用 /skills 或 $spark-blueprints 验证。

9.2 提示 Spark profile incomplete​

说明没有设置 Access Key，或者当前 profile 不对。重新执行：

spark auth set --profile spark-deploy --base-url https://spark.hiforce.ai --access-key <key> --access-secret <secret>
spark auth use spark-deploy
spark auth status

9.3 省略蓝图参数时报 No current blueprint​

先设置当前蓝图：

spark blueprint list
spark blueprint use <blueprint-code>

9.4 AI 上传本地材料前为什么要确认​

上传本地材料会把文件保存为 Spark Discovery 证据，属于写操作。AI 工具必须先展示路径、文件数量和影响范围，用户确认后才追加 --yes 执行。

9.5 哪些模块暂时还没有正式 CLI​

当前先完成蓝图、业务域、调研中心和候选评审。能力地图、价值流、痛点、应用拆解、应用覆盖、路线图、治理等模块会等界面操作稳定后再补 CLI。

最後於 更新