agentforce-bot-upgrade

Einstein Bot 升级编排器

目的

运行多机器人升级与交接周期：

1. 从 --bots 解析并验证机器人／版本对
2. 针对每个机器人版本对执行生成 Agent 规范参考（可并行）
3. 执行汇总步骤，该步骤要求所有生成的 Agent 规范均已就绪
4. 针对每个 Agent 规范执行 /agentforce-generate（可并行）
5. 针对每个生成的 Agent Script 执行后转换增强流程（可并行）

范围 — 此技能仅转换 Einstein Bot（BotDefinition/BotVersion 聊天机器人），将其转换为新的 Agentforce Agent。它不会将现有 Agentforce Agent 从旧版 GenAiPlannerBundle 迁移到 NGA aiAuthoringBundle — 如需进行此类迁移，请使用 agentforce-generate 技能中的“将旧版 Agent 迁移到 Agent Script”流程。

输入

输入：

• --mode <online|offline> 为可选参数；省略时默认为 online。
• 如果 mode=online，则必需：
  • --org-alias <org-alias>
  • --bots <bot1:v1,bot2:v2,...>
• 如果 mode=offline，则必需：
  • --offline-dir <offline-dir>
• --interactive <true|false> 为可选参数；省略时默认为 true。

如果缺少必需输入，请按照下文的“缺少输入处理”和“交互模式”规则处理。

交互模式

--interactive 用于控制技能在执行期间是否暂停并等待用户输入：

• --interactive true（默认值）：按照此技能及其参考文档中的说明，通过询问用户来解决歧义、开放问题和审批关卡。
• --interactive false：自主运行。在任何决策点都不得提示用户。对于每个开放问题、歧义或审批关卡，应用文档中推荐的默认值／解决方案，并在运行产物（Agent 规范、开放问题、提取摘要）中记录自动应用的决定。唯一允许在不提示的情况下直接停止的情况，是缺少输入或存在矛盾且没有安全的推荐默认值 — 缺少强制启动输入（在线模式下的 --org-alias/--bots，离线模式下的 --offline-dir）、未发现机器人，或同一机器人指定了多个版本。在这些情况下，报告问题并停止，不提示用户。

将生效的 --interactive 值传递给按机器人执行的“生成 Agent 规范”工作流（步骤 2）、规划器工作流（步骤 3）以及后转换增强流程（步骤 5）。

缺少输入处理

在步骤 1 之前，先补齐缺少的必需启动输入：

1. 在线模式 — 未提供 --org-alias。 必须先确定此项，再尝试列出机器人（列出机器人需要指定目标组织）。
   • 交互模式：列出已登录组织的可用别名，并询问用户选择目标组织。使用 SF CLI 机器人参考中的 SF CLI 模式。
   • 非交互模式：以明确错误指出缺少 --org-alias 输入，然后停止（不得提示或列出）。
2. 在线模式 — 未提供机器人名称和版本（--bots）。
   • 交互模式：使用 --org-alias 作为目标组织，列出该组织中的所有机器人及其版本，然后询问用户选择要转换为 Agent 的机器人／版本条目。使用 SF CLI 机器人参考中的 BotDefinition 和 BotVersion 查询模式 — 省略名称／版本筛选条件以枚举所有机器人和版本 — 展示结果，并根据用户的选择构建 --bots 工作负载。
   • 非交互模式：以明确错误指出缺少 --bots 输入，然后停止（不得提示或列出）。
3. 离线模式 — 未提供 --offline-dir。
   • 交互模式：询问用户提供 --offline-dir 路径，然后继续。
   • 非交互模式：以明确错误指出缺少 --offline-dir 输入，然后失败（不得提示）。

参考资料

执行期间请使用以下参考文件：

1. SF CLI Bot 参考
2. 生成 Agent 规范参考
3. 规划器工作流参考
4. 转换后增强参考
5. 提取蓝图
6. 输入约定
7. 映射规则
8. 交接输出格式
9. 质量检查清单

执行约定

第 1 步：解析并验证 --bots

按以下顺序执行第 1 步：

1. 确定模式：
   • 如果未提供 --mode，则使用 online。
2. 本次调用从头开始：
   • 不要发现、检查或复用先前已有运行的输出
   • 将本次调用视为全新的执行上下文
   • 仅使用当前调用流程中生成的工件
3. 构建初始工作负载列表：
   • mode=online：读取 --bots 并按逗号拆分。
   • mode=offline：扫描 <offline-dir> 并收集其直接子目录，作为 Bot 工作负载根目录。
4. 验证输入格式：
   • mode=online：每个 --bots 词条必须符合 <bot-name>:<version> 格式。
   • mode=offline：确保至少存在一个 Bot 子目录；否则停止（交互模式下询问用户以澄清；非交互模式下按照交互模式规则以明确的错误信息终止）。
5. 规范化工作负载条目：
   • mode=online：构建 {bot_name, bot_version} 条目。
   • mode=offline：构建 {offline_bot_dir} 条目（如果能从子目录结构推断 Bot 名称和版本，则予以标注；如果无法推断，则不为条目命名并继续）。
6. 执行每个 Bot 仅允许一个版本的规则（仅限在线模式）：
   • 如果同一个 bot_name 出现多个版本，则停止（交互模式下询问用户以澄清；非交互模式下按照交互模式规则以明确的错误信息终止）。
7. 应用离线 Bot 筛选条件：
   • 如果 mode=offline 且已提供 --bots，则仅将 --bots 用作已发现子目录的筛选条件；不要将其视为必需的离线输入。
8. 保存第 1 步输出：
   • 保存经过验证的工作负载列表，并将其传递给第 2 步并行执行。

第 2 步：运行 Einstein Bot 升级（针对每个 Bot 版本）

针对每个 Bot 版本组合，执行生成 Agent 规范参考中的 Agent 规范生成工作流：

• --mode <online|offline>（如果省略，默认为 online）
• 特定模式所需的输入：
  • 在线 -> --org-alias、--bot、--bot-version
  • 离线 -> --offline-dir
• --interactive <true|false>（传递编排器的有效值；默认为 true）

并行规则：

• 在 mode=online 下，由于每个 Bot 版本组合相互独立，因此并行执行调用。
• 在 mode=offline 下，对第 1 步发现的每个 Bot 子目录并行执行生成 Agent 规范参考中的工作流。
  • 每次调用传递 --mode offline 和 --offline-dir <bot-subdirectory-path>。 确保每次调用（在线/离线）都使用相互隔离的工作目录，以避免运行之间的文件冲突。

硬性规则：

• 不要跳过此步骤。

步骤 3：聚合 + 规划器步骤（条件执行）

所有升级调用完成后：

1. 始终构建一个整合列表，包含 {bot_name, bot_version, run_project_dir, agent_spec_path}。
2. 始终构建失败/未完成的升级运行列表（如有）。
3. 始终构建初始的可编写内容列表，其中仅包含有效的 Agent Spec 条目。
   • 每个条目必须包含：{bot_name, bot_version, run_project_dir, agent_spec_path, handoff_json_path, open_questions_path}。
4. 如果机器人工作负载总数大于 1：
   • 使用以下参数，执行 规划器工作流参考 中的规划器工作流：
     • 将所有可编写内容条目的 agent_spec_path 值作为 spec_paths
     • 将编排器工作目录作为 working_dir
     • 使用每个可编写内容条目关联的各项规范工件：handoff_json_path（交接 JSON）和 open_questions_path（待解决问题）
   • 要求在 <orchestrator working directory>/bot-upgrade-planner-output.json 生成输出文件。
   • 读取 bot-upgrade-planner-output.json 并按以下方式处理：
     • 如果 specs_changed=true：使用规划器字段（updated_spec_path、run_project_dir、handoff_json_path、open_questions_path）替换可编写内容条目
     • 如果 specs_changed=false：保持原始可编写内容列表不变
5. 如果机器人工作负载总数为 1：
   • 完全跳过规划器工作流。
   • 保持原始可编写内容列表不变。

规划器输出要求：

1. 布尔值 specs_changed
2. updated_specs 数组，包含以下条目：
   • original_spec_path
   • updated_spec_path
   • run_project_dir
   • handoff_json_path
   • open_questions_path
3. 当 specs_changed=false 时，updated_specs 必须为空

步骤 4：调用 Agentforce-Generate（针对每个 Agent Spec）

针对最终可编写内容列表中的每个条目（步骤 3 规划器协调后）：

0. 在调用 /agentforce-generate 之前，将以下建议添加到生成的调用上下文中：
   • 在此次编排运行中不要激活 Agent Script 版本。
   • 必须进行草稿迭代：允许生成 .agent、验证、部署和预览测试。
   • 除非用户明确要求发布，否则应推迟激活。
1. 从最终可编写内容条目中解析有效的 run_project_dir。
2. 完整读取 <run_project_dir>/agentforce-generate-invocation-prompt.md。
3. 如果步骤 3 生成了规划器更新后的规范路径/工件，请在调用上下文中替换路径，使规范/交接/待解决问题引用指向更新后的文件。
   • 如果规划器还更改了 run_project_dir，请使用更新后的 run_project_dir 解析提示词/输出契约路径。
4. 保持原始生成提示词中的所有非路径指令不变。
5. 使用解析后的调用上下文调用 /agentforce-generate。
6. 读取 <run_project_dir>/agentforce-generate-output-contract.md，并严格按照指定内容捕获输出。

并行化规则：

• 在各个 Agent Spec 之间并行调用 /agentforce-generate，因为每次运行彼此独立。

输出契约捕获规则：

1. 将输出契约视为必需字段/工件的权威来源。
2. 如果缺少任何契约字段，则将状态标记为 partial，并明确列出缺失字段。
3. 使用与契约名称匹配的确定性键返回捕获的输出。
4. 保留输出文件路径以及每个必需工件的状态。
5. 如果某个条目的预期提示词/契约文件缺失，则将该条目标记为 partial，记录缺失路径，并继续处理其他条目。

第 5 步：转换后增强 Agent 脚本（针对每个生成的 Agent 脚本）

第 4 步完成后，对每个生成的 .agent 工件：

1. 根据捕获的 /agentforce-generate 输出，确定生成的 .agent 文件路径。
2. 按照转换后增强参考执行转换后增强工作流，并提供：
   • agentscript_file=<generated-agent-file-path>
   • mode=<online|offline>（第 1 步中确定的有效编排器运行模式）
   • 仅限在线模式：org_alias=<org-alias>（必填，以便重新部署增强后的 Agent Script）
3. 要求原位增强：
   • 优化后／增强后的输出必须写入同一个 .agent 文件位置。
4. 记录每个文件的增强状态和任何部分失败。

并行化规则：

• 对生成的 .agent 文件并行执行转换后增强工作流，因为每个文件的增强彼此独立。

第 6 步：汇总运行报告并结束

第 5 步完成工作负载中的每个 bot 后：

1. 在编排器工作目录中，将一份可读的汇总运行报告写入非空 Markdown 文件。报告必须逐个 bot 说明：有效运行模式、规划器是否运行（executed 或 skipped）、生成的 Agent Spec 路径和生成的 .agent 路径、操作清单（包括任何 NEEDS_STUB 项），以及在 --interactive=false 时自动应用的决策。
2. 将运行报告视为最终工件：只有在所有其他工件（Agent Spec、交接 JSON、未解答问题、任何规划器输出和生成的 .agent 文件）均已写入后，才能写入该报告。

交付内容

返回：

1. 解析出的 bot／版本列表
2. 每个 bot 的升级执行状态
3. 汇总输出（完整的 Agent Spec 列表 + 最终可供编写的子集）
4. 规划器工作流状态（executed 或 skipped）；若已执行，则提供 bot-upgrade-planner-output.json 路径
5. 每个 Spec 的 /agentforce-generate 执行状态
6. 每个 bot／Spec 的生成交接工件路径（包括适用时由规划器更新的工件）
7. 按输出契约捕获的 /agentforce-generate 输出
8. 每个 Agent 的转换后增强状态（包括增强后的 .agent 文件路径）
9. 第 6 步写入的汇总运行报告路径