agentforce-bot-upgrade
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseEinstein Bot Upgrade Orchestrator
Einstein Bot升级协调器
Purpose
目标
Run a multi-bot upgrade-and-handoff cycle:
- Parse and validate bot/version pairs from
--bots - Follow Generate Agent Spec Reference per bot-version pair (parallelizable)
- Aggregation step that requires all generated Agent Specs
- per Agent Spec (parallelizable)
/agentforce-generate - Post-conversion enhancement pass per generated Agent Script (parallelizable)
执行多机器人升级与交接周期:
- 解析并验证中的机器人/版本对
--bots - 针对每个机器人-版本对遵循Generate Agent Spec Reference(支持并行执行)
- 聚合步骤:需收集所有生成的Agent Spec
- 针对每个Agent Spec执行(支持并行执行)
/agentforce-generate - 针对每个生成的Agent Script执行转换后增强步骤(支持并行执行)
Inputs
输入参数
Inputs:
- is optional; default is
--mode <online|offline>when omitted.online - If , required:
mode=online--org-alias <org-alias>--bots <bot1:v1,bot2:v2,...>
- If , required:
mode=offline--offline-dir <offline-dir>
- is optional; default is
--interactive <true|false>when omitted.true
If required inputs are missing, handle per the Missing Input Handling and Interactive Mode rules below.
输入参数:
- 为可选参数;若省略,默认值为
--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 Mode
交互模式
--interactive- (default): resolve ambiguities, open questions, and approval gates by asking the user, as described in this skill and its references.
--interactive true - : run autonomously. Do NOT prompt the user at any decision point. For every open question, ambiguity, or approval gate, apply the documented recommended default/solution and record the auto-applied decision in the run artifacts (Agent Spec, open questions, extraction summary). The only hard stops permitted without prompting are inputs that are missing or contradictory with no safe recommended default — a missing mandatory launch input (
--interactive false/--org-aliasfor online,--botsfor offline), no bots discovered, or the same bot given multiple versions. In those cases, report the issue and halt without prompting.--offline-dir
Propagate the effective value to the per-bot Generate Agent Spec workflow (Step 2), the planner workflow (Step 3), and the post-conversion enhancement pass (Step 5).
--interactive--interactive- (默认):通过询问用户解决歧义、未决问题和审批节点,具体流程见本技能及其参考文档。
--interactive true - :自主运行。在任何决策点均不提示用户。对于所有未决问题、歧义或审批节点,应用文档中推荐的默认方案/解决办法,并将自动应用的决策记录在运行产物(Agent Spec、未决问题、提取摘要)中。仅当出现缺失输入或矛盾且无安全推荐默认值时才允许强制停止——比如缺失必填启动输入(在线模式下的
--interactive false/--org-alias,离线模式下的--bots)、未发现任何机器人、或同一机器人被指定多个版本。这些情况下,报告问题并停止运行,不进行提示。--offline-dir
将生效的值传递给每个机器人的Generate Agent Spec工作流(步骤2)、规划器工作流(步骤3)和转换后增强步骤(步骤5)。
--interactiveMissing Input Handling
缺失输入处理
Resolve missing required launch inputs before Step 1:
- Online mode — not provided. Resolve this before attempting to list bots (listing requires a target org).
--org-alias- Interactive: list the available aliases of logged-in orgs and ask the user to select the target org. Use the SF CLI patterns in SF CLI Bot Reference.
- Non-interactive: halt with an explicit error naming the missing input (do not prompt or list).
--org-alias
- Online mode — bot name and version () not available.
--bots- Interactive: using as the target org, list every bot and its versions in the org, then ask the user to select the bot/version entries they want to convert to agents. Use the
--org-aliasandBotDefinitionquery patterns in SF CLI Bot Reference — omit the name/version filters to enumerate all bots and versions — present the results, and build theBotVersionworkload from the user's selection.--bots - Non-interactive: halt with an explicit error naming the missing input (do not prompt or list).
--bots
- Interactive: using
- Offline mode — not available.
--offline-dir- Interactive: ask the user to provide the path, then continue.
--offline-dir - Non-interactive: fail with an explicit error naming the missing input (do not prompt).
--offline-dir
- Interactive: ask the user to provide the
在步骤1之前解决缺失的必填启动输入:
- 在线模式——未提供。在尝试列出机器人之前解决此问题(列出机器人需要目标组织)。
--org-alias- 交互模式:列出已登录组织的可用别名,让用户选择目标组织。使用SF CLI Bot Reference中的SF CLI模式。
- 非交互模式:停止运行并明确报错,指出缺失输入(不提示或列出别名)。
--org-alias
- 在线模式——机器人名称和版本()不可用。
--bots- 交互模式:以为目标组织,列出该组织中的所有机器人及其版本,然后让用户选择要转换为Agent的机器人/版本条目。使用SF CLI Bot Reference中的
--org-alias和BotDefinition查询模式——省略名称/版本过滤器以枚举所有机器人和版本——展示结果,并根据用户选择构建BotVersion任务列表。--bots - 非交互模式:停止运行并明确报错,指出缺失输入(不提示或列出机器人)。
--bots
- 交互模式:以
- 离线模式——未提供。
--offline-dir- 交互模式:让用户提供路径,然后继续运行。
--offline-dir - 非交互模式:运行失败并明确报错,指出缺失输入(不提示)。
--offline-dir
- 交互模式:让用户提供
References
参考文档
Use these reference files during execution:
- SF CLI Bot Reference
- Generate Agent Spec Reference
- Planner Workflow Reference
- Post-Conversion Enhancements Reference
- Extraction Blueprint
- Input Contract
- Mapping Rules
- Handoff Output Format
- Quality Checklist
执行过程中使用以下参考文件:
- SF CLI Bot Reference
- Generate Agent Spec Reference
- Planner Workflow Reference
- Post-Conversion Enhancements Reference
- Extraction Blueprint
- Input Contract
- Mapping Rules
- Handoff Output Format
- Quality Checklist
Execution Contract
执行约定
Step 1: Parse and Validate --bots
--bots步骤1:解析并验证--bots
--botsExecute Step 1 in this order:
- Resolve mode:
- If omitted, use
--mode.online
- If
- Start fresh for this invocation:
- do not discover, inspect, or reuse outputs from previously existing runs
- treat this invocation as a clean execution context
- only use artifacts produced during the current invocation flow
- Build initial workload list:
- : read
mode=onlineand split by comma.--bots - : scan
mode=offlineand collect immediate sub-directories as bot workload roots.<offline-dir>
- Validate input shape:
- : each
mode=onlinetoken must match--bots.<bot-name>:<version> - : ensure at least one bot sub-directory exists; otherwise STOP (in interactive mode ask the user to clarify; in non-interactive mode halt with an explicit error per the Interactive Mode rule).
mode=offline
- Normalize workload entries:
- : build
mode=onlineentries.{bot_name, bot_version} - : build
mode=offlineentries (Annotate inferred bot name and version when derivable from the sub-directory structure; if not derivable, leave the entry unnamed and continue).{offline_bot_dir}
- Enforce one-version-per-bot rule (online mode):
- If the same appears with multiple versions, STOP (in interactive mode ask the user to clarify; in non-interactive mode halt with an explicit error per the Interactive Mode rule).
bot_name
- If the same
- Apply offline bot filter:
- If and
mode=offlineis provided, use--botsonly as a filter over discovered sub-directories; do not treat it as required offline input.--bots
- If
- Persist Step 1 output:
- Save and carry forward a validated workload list for Step 2 parallel execution.
按以下顺序执行步骤1:
- 确定运行模式:
- 若省略,使用
--mode模式。online
- 若省略
- 本次调用从头开始:
- 不发现、检查或重用之前运行的输出结果
- 将本次调用视为全新的执行上下文
- 仅使用本次调用流程中生成的产物
- 构建初始任务列表:
- :读取
mode=online并按逗号拆分。--bots - :扫描
mode=offline并收集直接子目录作为机器人任务根目录。<offline-dir>
- 验证输入格式:
- :每个
mode=online令牌必须匹配--bots格式。<bot-name>:<version> - :确保至少存在一个机器人子目录;否则停止运行(交互模式下询问用户澄清;非交互模式下按交互模式规则停止运行并明确报错)。
mode=offline
- 标准化任务条目:
- :构建
mode=online条目。{bot_name, bot_version} - :构建
mode=offline条目(若可从子目录结构推导机器人名称和版本则添加注释;若无法推导则保留条目未命名并继续)。{offline_bot_dir}
- 强制执行「每个机器人对应一个版本」规则(在线模式):
- 若同一对应多个版本,停止运行(交互模式下询问用户澄清;非交互模式下按交互模式规则停止运行并明确报错)。
bot_name
- 若同一
- 应用离线机器人过滤器:
- 若且提供了
mode=offline,仅将--bots用作已发现子目录的过滤器;不将其视为必填离线输入。--bots
- 若
- 保存步骤1输出:
- 保存并传递验证后的任务列表,用于步骤2的并行执行。
Step 2: Run Einstein Bot Upgrade (Per Bot-Version)
步骤2:执行Einstein Bot升级(按机器人-版本)
Execute the agent spec generation workflow from Generate Agent Spec Reference per bot-version combination:
- (default
--mode <online|offline>if omitted)online - mode-specific required inputs:
- online -> ,
--org-alias,--bot--bot-version - offline ->
--offline-dir
- online ->
- (pass through the effective orchestrator value; default
--interactive <true|false>)true
Parallelization rule:
- In , execute invocations in parallel because each bot-version pair is independent.
mode=online - In , execute the Generate Agent Spec Reference workflow in parallel over every bot sub-directory discovered in Step 1.
mode=offline- Pass and
--mode offlineper invocation. Ensure each invocation (online/offline) uses isolated working directories to avoid cross-run file collisions.--offline-dir <bot-subdirectory-path>
- Pass
Hard rules:
- Do not skip this step.
针对每个机器人-版本组合,执行Generate Agent Spec Reference中的Agent Spec生成工作流:
- (若省略则默认
--mode <online|offline>)online - 模式特定必填输入:
- 在线模式 -> ,
--org-alias,--bot--bot-version - 离线模式 ->
--offline-dir
- 在线模式 ->
- (传递协调器的生效值;默认
--interactive <true|false>)true
并行化规则:
- 在模式下,并行执行调用,因为每个机器人-版本对相互独立。
mode=online - 在模式下,对步骤1中发现的每个机器人子目录并行执行Generate Agent Spec Reference工作流。
mode=offline- 每次调用传递和
--mode offline。 确保每次调用(在线/离线)使用独立的工作目录,避免跨运行文件冲突。--offline-dir <bot-subdirectory-path>
- 每次调用传递
硬性规则:
- 不得跳过此步骤。
Step 3: Aggregation + Planner Step (Conditional)
步骤3:聚合 + 规划器步骤(条件执行)
After all upgrade invocations complete:
- Always build a consolidated list of .
{bot_name, bot_version, run_project_dir, agent_spec_path} - Always build list of failed/incomplete upgrade runs (if any).
- Always build an initial ready-for-authoring list containing only valid Agent Spec entries.
- Each entry must include: .
{bot_name, bot_version, run_project_dir, agent_spec_path, handoff_json_path, open_questions_path}
- Each entry must include:
- If total bot workload count is greater than 1:
- Execute planner workflow from Planner Workflow Reference using:
- all ready-for-authoring values as
agent_spec_pathspec_paths - orchestrator working directory as
working_dir - the associated per-spec artifacts from each ready-for-authoring entry: (handoff JSON) and
handoff_json_path(open questions)open_questions_path
- all ready-for-authoring
- Require output file at .
<orchestrator working directory>/bot-upgrade-planner-output.json - Read and apply:
bot-upgrade-planner-output.json- if : replace ready-for-authoring entries using planner fields (
specs_changed=true,updated_spec_path,run_project_dir,handoff_json_path)open_questions_path - if : keep original ready-for-authoring list unchanged
specs_changed=false
- if
- Execute planner workflow from Planner Workflow Reference using:
- If total bot workload count is 1:
- Skip planner workflow entirely.
- Keep original ready-for-authoring list unchanged.
Planner output expectations:
- boolean
specs_changed - array with entries:
updated_specsoriginal_spec_pathupdated_spec_pathrun_project_dirhandoff_json_pathopen_questions_path
- must be empty when
updated_specsspecs_changed=false
所有升级调用完成后:
- 始终构建合并后的列表。
{bot_name, bot_version, run_project_dir, agent_spec_path} - 始终构建失败/未完成的升级运行列表(若有)。
- 始终构建初始可创作列表,仅包含有效的Agent Spec条目。
- 每个条目必须包含:。
{bot_name, bot_version, run_project_dir, agent_spec_path, handoff_json_path, open_questions_path}
- 每个条目必须包含:
- 若机器人任务总数大于1:
- 使用以下参数执行Planner Workflow Reference中的规划器工作流:
- 所有可创作的值作为
agent_spec_pathspec_paths - 协调器工作目录作为
working_dir - 每个可创作条目中的关联产物:(交接JSON)和
handoff_json_path(未决问题)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
- 若
- 使用以下参数执行Planner Workflow Reference中的规划器工作流:
- 若机器人任务总数为1:
- 完全跳过规划器工作流。
- 保留原始可创作列表不变。
规划器输出预期:
- 布尔值
specs_changed - 数组,包含以下条目:
updated_specsoriginal_spec_pathupdated_spec_pathrun_project_dirhandoff_json_pathopen_questions_path
- 当时,
specs_changed=false必须为空updated_specs
Step 4: Invoke Agentforce-Generate (Per Agent Spec)
步骤4:调用Agentforce-Generate(按Agent Spec)
For each entry in final ready-for-authoring list (post Step 3 planner reconciliation):
- Add this recommendation to the generated invocation context before calling :
/agentforce-generate- Do not activate Agent Script versions in this orchestrated run.
- Draft iteration is required: generating , validating, deploying, and preview testing are allowed.
.agent - Activate should be deferred unless the user explicitly asks for release.
- Resolve effective from the final ready-for-authoring entry.
run_project_dir - Read fully.
<run_project_dir>/agentforce-generate-invocation-prompt.md - If Step 3 produced planner-updated spec paths/artifacts, apply path substitutions in the invocation context so spec/handoff/open-questions references point to updated files.
- If planner also changed , use that updated
run_project_dirfor resolving prompt/output-contract paths.run_project_dir
- If planner also changed
- Keep all non-path instructions unchanged from the original generated prompt.
- Invoke with this resolved invocation context.
/agentforce-generate - Read and capture outputs exactly as specified.
<run_project_dir>/agentforce-generate-output-contract.md
Parallelization rule:
- Invoke in parallel across Agent Specs because each run is independent.
/agentforce-generate
Output-contract capture rules:
- Treat the output contract as authoritative for required fields/artifacts.
- If any contract field is missing, mark status as partial and list missing fields explicitly.
- Return captured outputs with deterministic keys matching the contract names.
- Preserve output file paths and status of each required artifact.
- If expected prompt/contract files are missing for an entry, mark that entry , record missing paths, and continue processing other entries.
partial
针对步骤3规划器协调后的最终可创作列表中的每个条目:
- 在调用之前,向生成的调用上下文添加以下建议:
/agentforce-generate- 在此协调运行中不要激活Agent Script版本。
- 需要草稿迭代:允许生成、验证、部署和预览测试。
.agent - 除非用户明确要求发布,否则应推迟激活操作。
- 从最终可创作条目中解析生效的。
run_project_dir - 完整读取。
<run_project_dir>/agentforce-generate-invocation-prompt.md - 若步骤3生成了规划器更新后的Spec路径/产物,在调用上下文中应用路径替换,使Spec/交接/未决问题的引用指向更新后的文件。
- 若规划器也更改了,使用更新后的
run_project_dir解析提示/输出约定路径。run_project_dir
- 若规划器也更改了
- 保留原始生成提示中的所有非路径指令不变。
- 使用解析后的调用上下文调用。
/agentforce-generate - 读取并严格按指定捕获输出。
<run_project_dir>/agentforce-generate-output-contract.md
并行化规则:
- 针对多个Agent Spec并行调用,因为每次运行相互独立。
/agentforce-generate
输出约定捕获规则:
- 将输出约定视为必填字段/产物的权威来源。
- 若任何约定字段缺失,将状态标记为部分完成并明确列出缺失字段。
- 返回捕获的输出,使用与约定名称匹配的确定性键。
- 保留每个必填产物的输出文件路径和状态。
- 若某个条目对应的预期提示/约定文件缺失,将该条目标记为,记录缺失路径,并继续处理其他条目。
partial
Step 5: Post-Conversion Agent Script Enhancements (Per Generated Agent Script)
步骤5:转换后Agent Script增强(按生成的Agent Script)
After Step 4 completes, for each generated artifact:
.agent- Resolve the generated file path from captured
.agentoutputs./agentforce-generate - Execute post-conversion enhancement workflow from Post-Conversion Enhancements Reference with:
agentscript_file=<generated-agent-file-path>- (the effective orchestrator run mode resolved in Step 1)
mode=<online|offline> - online mode only: (required so the enhanced Agent Script can be redeployed)
org_alias=<org-alias>
- Require in-place enhancement:
- optimized/enhanced output must be written to the same file location.
.agent
- optimized/enhanced output must be written to the same
- Capture per-file enhancement status and any partial failures.
Parallelization rule:
- Execute post-conversion enhancement workflow in parallel across generated files because each file enhancement is independent.
.agent
步骤4完成后,针对每个生成的产物:
.agent- 从捕获的输出中解析生成的
/agentforce-generate文件路径。.agent - 使用以下参数执行Post-Conversion Enhancements Reference中的转换后增强工作流:
agentscript_file=<generated-agent-file-path>- (步骤1中确定的协调器生效运行模式)
mode=<online|offline> - 仅在线模式:(必填,以便重新部署增强后的Agent Script)
org_alias=<org-alias>
- 要求原地增强:
- 优化/增强后的输出必须写入同一文件位置。
.agent
- 优化/增强后的输出必须写入同一
- 捕获每个文件的增强状态及任何部分失败情况。
并行化规则:
- 针对多个生成的文件并行执行转换后增强工作流,因为每个文件的增强相互独立。
.agent
Step 6: Consolidate Run Report and Conclude
步骤6:合并运行报告并结束
After Step 5 completes for every bot in the workload:
- Write a single consolidated, human-readable run report as a non-empty Markdown file in the orchestrator working directory. Per bot, the report must state: the effective run mode, whether the planner ran (or
executed), the generated Agent Spec path and generatedskippedpath, the action inventory (including any.agentitems), and — whenNEEDS_STUB— the auto-applied decisions.--interactive=false - Treat the run report as the FINAL artifact: write it only after all other artifacts (Agent Spec(s), handoff JSON, open questions, any planner output, and generated file(s)) are already written.
.agent
步骤5针对任务中的所有机器人完成后:
- 在协调器工作目录中写入一份合并的、人类可读的Markdown格式运行报告(不能为空)。针对每个机器人,报告必须说明:生效运行模式、规划器是否运行(或
executed)、生成的Agent Spec路径和生成的skipped路径、操作清单(包括任何.agent项),以及当NEEDS_STUB时自动应用的决策。--interactive=false - 将运行报告视为最终产物:仅在所有其他产物(Agent Spec、交接JSON、未决问题、任何规划器输出、生成的文件)已写入后再编写报告。
.agent
Deliverable
交付物
Return:
- parsed bot/version list
- per-bot upgrade execution status
- aggregation output (full Agent Spec list + final ready-for-authoring subset)
- planner workflow status (or
executed) andskippedpath when executedbot-upgrade-planner-output.json - per-spec execution status
/agentforce-generate - generated handoff artifact paths per bot/spec (including planner-updated artifacts when applicable)
- captured outputs per output contract
/agentforce-generate - per-agent post-conversion enhancement status (including enhanced file paths)
.agent - path to the consolidated run report written in Step 6
返回:
- 解析后的机器人/版本列表
- 每个机器人的升级执行状态
- 聚合输出(完整Agent Spec列表 + 最终可创作子集)
- 规划器工作流状态(或
executed),以及执行时的skipped路径bot-upgrade-planner-output.json - 每个Spec的执行状态
/agentforce-generate - 每个机器人/Spec的生成交接产物路径(若适用,包括规划器更新后的产物)
- 按输出约定捕获的输出
/agentforce-generate - 每个Agent的转换后增强状态(包括增强后的文件路径)
.agent - 步骤6中编写的合并运行报告路径