Aller au contenu principal

Spark Blueprint AI CLI 从零使用指南

Traduction en coursCe guide est actuellement disponible en chinois simplifié. Une version traduite sera ajoutée ultérieurement.

本篇面向第一次使用 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。

Dernière mise à jour le