agentforce-bot-upgrade

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Einstein Bot Upgrade Orchestrator

Einstein Bot升级协调器

Purpose

目标

Run a multi-bot upgrade-and-handoff cycle:
  1. Parse and validate bot/version pairs from
    --bots
  2. Follow Generate Agent Spec Reference per bot-version pair (parallelizable)
  3. Aggregation step that requires all generated Agent Specs
  4. /agentforce-generate
    per Agent Spec (parallelizable)
  5. Post-conversion enhancement pass per generated Agent Script (parallelizable)
执行多机器人升级与交接周期:
  1. 解析并验证
    --bots
    中的机器人/版本对
  2. 针对每个机器人-版本对遵循Generate Agent Spec Reference(支持并行执行)
  3. 聚合步骤:需收集所有生成的Agent Spec
  4. 针对每个Agent Spec执行
    /agentforce-generate
    (支持并行执行)
  5. 针对每个生成的Agent Script执行转换后增强步骤(支持并行执行)

Inputs

输入参数

Inputs:
  • --mode <online|offline>
    is optional; default is
    online
    when omitted.
  • If
    mode=online
    , required:
    • --org-alias <org-alias>
    • --bots <bot1:v1,bot2:v2,...>
  • If
    mode=offline
    , required:
    • --offline-dir <offline-dir>
  • --interactive <true|false>
    is optional; default is
    true
    when omitted.
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
controls whether the skill pauses for user input during execution:
  • --interactive true
    (default): resolve ambiguities, open questions, and approval gates by asking the user, as described in this skill and its references.
  • --interactive false
    : 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 (
    --org-alias
    /
    --bots
    for online,
    --offline-dir
    for offline), no bots discovered, or the same bot given multiple versions. In those cases, report the issue and halt without prompting.
Propagate the effective
--interactive
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 true
    (默认):通过询问用户解决歧义、未决问题和审批节点,具体流程见本技能及其参考文档。
  • --interactive false
    :自主运行。在任何决策点均不提示用户。对于所有未决问题、歧义或审批节点,应用文档中推荐的默认方案/解决办法,并将自动应用的决策记录在运行产物(Agent Spec、未决问题、提取摘要)中。仅当出现缺失输入或矛盾且无安全推荐默认值时才允许强制停止——比如缺失必填启动输入(在线模式下的
    --org-alias
    /
    --bots
    ,离线模式下的
    --offline-dir
    )、未发现任何机器人、或同一机器人被指定多个版本。这些情况下,报告问题并停止运行,不进行提示。
将生效的
--interactive
值传递给每个机器人的Generate Agent Spec工作流(步骤2)、规划器工作流(步骤3)和转换后增强步骤(步骤5)。

Missing Input Handling

缺失输入处理

Resolve missing required launch inputs before Step 1:
  1. Online mode —
    --org-alias
    not provided.
    Resolve this before attempting to list bots (listing requires a target org).
    • 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
      --org-alias
      input (do not prompt or list).
  2. Online mode — bot name and version (
    --bots
    ) not available.
    • Interactive: using
      --org-alias
      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
      BotDefinition
      and
      BotVersion
      query patterns in SF CLI Bot Reference — omit the name/version filters to enumerate all bots and versions — present the results, and build the
      --bots
      workload from the user's selection.
    • Non-interactive: halt with an explicit error naming the missing
      --bots
      input (do not prompt or list).
  3. Offline mode —
    --offline-dir
    not available.
    • Interactive: ask the user to provide the
      --offline-dir
      path, then continue.
    • Non-interactive: fail with an explicit error naming the missing
      --offline-dir
      input (do not prompt).
在步骤1之前解决缺失的必填启动输入:
  1. 在线模式——未提供
    --org-alias
    。在尝试列出机器人之前解决此问题(列出机器人需要目标组织)。
    • 交互模式:列出已登录组织的可用别名,让用户选择目标组织。使用SF CLI Bot Reference中的SF CLI模式。
    • 非交互模式:停止运行并明确报错,指出缺失
      --org-alias
      输入(不提示或列出别名)。
  2. 在线模式——机器人名称和版本(
    --bots
    )不可用
    • 交互模式:以
      --org-alias
      为目标组织,列出该组织中的所有机器人及其版本,然后让用户选择要转换为Agent的机器人/版本条目。使用SF CLI Bot Reference中的
      BotDefinition
      BotVersion
      查询模式——省略名称/版本过滤器以枚举所有机器人和版本——展示结果,并根据用户选择构建
      --bots
      任务列表。
    • 非交互模式:停止运行并明确报错,指出缺失
      --bots
      输入(不提示或列出机器人)。
  3. 离线模式——未提供
    --offline-dir
    • 交互模式:让用户提供
      --offline-dir
      路径,然后继续运行。
    • 非交互模式:运行失败并明确报错,指出缺失
      --offline-dir
      输入(不提示)。

References

参考文档

Use these reference files during execution:
  1. SF CLI Bot Reference
  2. Generate Agent Spec Reference
  3. Planner Workflow Reference
  4. Post-Conversion Enhancements Reference
  5. Extraction Blueprint
  6. Input Contract
  7. Mapping Rules
  8. Handoff Output Format
  9. Quality Checklist
执行过程中使用以下参考文件:
  1. SF CLI Bot Reference
  2. Generate Agent Spec Reference
  3. Planner Workflow Reference
  4. Post-Conversion Enhancements Reference
  5. Extraction Blueprint
  6. Input Contract
  7. Mapping Rules
  8. Handoff Output Format
  9. Quality Checklist

Execution Contract

执行约定

Step 1: Parse and Validate
--bots

步骤1:解析并验证
--bots

Execute Step 1 in this order:
  1. Resolve mode:
    • If
      --mode
      omitted, use
      online
      .
  2. 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
  3. Build initial workload list:
    • mode=online
      : read
      --bots
      and split by comma.
    • mode=offline
      : scan
      <offline-dir>
      and collect immediate sub-directories as bot workload roots.
  4. Validate input shape:
    • mode=online
      : each
      --bots
      token must match
      <bot-name>:<version>
      .
    • mode=offline
      : 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).
  5. Normalize workload entries:
    • mode=online
      : build
      {bot_name, bot_version}
      entries.
    • mode=offline
      : build
      {offline_bot_dir}
      entries (Annotate inferred bot name and version when derivable from the sub-directory structure; if not derivable, leave the entry unnamed and continue).
  6. Enforce one-version-per-bot rule (online mode):
    • If the same
      bot_name
      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).
  7. Apply offline bot filter:
    • If
      mode=offline
      and
      --bots
      is provided, use
      --bots
      only as a filter over discovered sub-directories; do not treat it as required offline input.
  8. Persist Step 1 output:
    • Save and carry forward a validated workload list for Step 2 parallel execution.
按以下顺序执行步骤1:
  1. 确定运行模式:
    • 若省略
      --mode
      ,使用
      online
      模式。
  2. 本次调用从头开始:
    • 不发现、检查或重用之前运行的输出结果
    • 将本次调用视为全新的执行上下文
    • 仅使用本次调用流程中生成的产物
  3. 构建初始任务列表:
    • mode=online
      :读取
      --bots
      并按逗号拆分。
    • mode=offline
      :扫描
      <offline-dir>
      并收集直接子目录作为机器人任务根目录。
  4. 验证输入格式:
    • mode=online
      :每个
      --bots
      令牌必须匹配
      <bot-name>:<version>
      格式。
    • mode=offline
      :确保至少存在一个机器人子目录;否则停止运行(交互模式下询问用户澄清;非交互模式下按交互模式规则停止运行并明确报错)。
  5. 标准化任务条目:
    • mode=online
      :构建
      {bot_name, bot_version}
      条目。
    • mode=offline
      :构建
      {offline_bot_dir}
      条目(若可从子目录结构推导机器人名称和版本则添加注释;若无法推导则保留条目未命名并继续)。
  6. 强制执行「每个机器人对应一个版本」规则(在线模式):
    • 若同一
      bot_name
      对应多个版本,停止运行(交互模式下询问用户澄清;非交互模式下按交互模式规则停止运行并明确报错)。
  7. 应用离线机器人过滤器:
    • mode=offline
      且提供了
      --bots
      ,仅将
      --bots
      用作已发现子目录的过滤器;不将其视为必填离线输入。
  8. 保存步骤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:
  • --mode <online|offline>
    (default
    online
    if omitted)
  • mode-specific required inputs:
    • online ->
      --org-alias
      ,
      --bot
      ,
      --bot-version
    • offline ->
      --offline-dir
  • --interactive <true|false>
    (pass through the effective orchestrator value; default
    true
    )
Parallelization rule:
  • In
    mode=online
    , execute invocations in parallel because each bot-version pair is independent.
  • In
    mode=offline
    , execute the Generate Agent Spec Reference workflow in parallel over every bot sub-directory discovered in Step 1.
    • Pass
      --mode offline
      and
      --offline-dir <bot-subdirectory-path>
      per invocation. Ensure each invocation (online/offline) uses isolated working directories to avoid cross-run file collisions.
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
    模式下,并行执行调用,因为每个机器人-版本对相互独立。
  • mode=offline
    模式下,对步骤1中发现的每个机器人子目录并行执行Generate Agent Spec Reference工作流。
    • 每次调用传递
      --mode offline
      --offline-dir <bot-subdirectory-path>
      。 确保每次调用(在线/离线)使用独立的工作目录,避免跨运行文件冲突。
硬性规则:
  • 不得跳过此步骤。

Step 3: Aggregation + Planner Step (Conditional)

步骤3:聚合 + 规划器步骤(条件执行)

After all upgrade invocations complete:
  1. Always build a consolidated list of
    {bot_name, bot_version, run_project_dir, agent_spec_path}
    .
  2. Always build list of failed/incomplete upgrade runs (if any).
  3. 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}
      .
  4. If total bot workload count is greater than 1:
    • Execute planner workflow from Planner Workflow Reference using:
      • all ready-for-authoring
        agent_spec_path
        values as
        spec_paths
      • orchestrator working directory as
        working_dir
      • the associated per-spec artifacts from each ready-for-authoring entry:
        handoff_json_path
        (handoff JSON) and
        open_questions_path
        (open questions)
    • Require output file at
      <orchestrator working directory>/bot-upgrade-planner-output.json
      .
    • Read
      bot-upgrade-planner-output.json
      and apply:
      • if
        specs_changed=true
        : replace ready-for-authoring entries using planner fields (
        updated_spec_path
        ,
        run_project_dir
        ,
        handoff_json_path
        ,
        open_questions_path
        )
      • if
        specs_changed=false
        : keep original ready-for-authoring list unchanged
  5. If total bot workload count is 1:
    • Skip planner workflow entirely.
    • Keep original ready-for-authoring list unchanged.
Planner output expectations:
  1. boolean
    specs_changed
  2. updated_specs
    array with entries:
    • original_spec_path
    • updated_spec_path
    • run_project_dir
    • handoff_json_path
    • open_questions_path
  3. updated_specs
    must be empty when
    specs_changed=false
所有升级调用完成后:
  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:
    • 使用以下参数执行Planner Workflow Reference中的规划器工作流:
      • 所有可创作的
        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
    必须为空

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):
  1. 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
      .agent
      , validating, deploying, and preview testing are allowed.
    • Activate should be deferred unless the user explicitly asks for release.
  2. Resolve effective
    run_project_dir
    from the final ready-for-authoring entry.
  3. Read
    <run_project_dir>/agentforce-generate-invocation-prompt.md
    fully.
  4. 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
      run_project_dir
      , use that updated
      run_project_dir
      for resolving prompt/output-contract paths.
  5. Keep all non-path instructions unchanged from the original generated prompt.
  6. Invoke
    /agentforce-generate
    with this resolved invocation context.
  7. Read
    <run_project_dir>/agentforce-generate-output-contract.md
    and capture outputs exactly as specified.
Parallelization rule:
  • Invoke
    /agentforce-generate
    in parallel across Agent Specs because each run is independent.
Output-contract capture rules:
  1. Treat the output contract as authoritative for required fields/artifacts.
  2. If any contract field is missing, mark status as partial and list missing fields explicitly.
  3. Return captured outputs with deterministic keys matching the contract names.
  4. Preserve output file paths and status of each required artifact.
  5. If expected prompt/contract files are missing for an entry, mark that entry
    partial
    , record missing paths, and continue processing other entries.
针对步骤3规划器协调后的最终可创作列表中的每个条目:
  1. 在调用
    /agentforce-generate
    之前,向生成的调用上下文添加以下建议:
    • 在此协调运行中不要激活Agent Script版本。
    • 需要草稿迭代:允许生成
      .agent
      、验证、部署和预览测试。
    • 除非用户明确要求发布,否则应推迟激活操作。
  2. 从最终可创作条目中解析生效的
    run_project_dir
  3. 完整读取
    <run_project_dir>/agentforce-generate-invocation-prompt.md
  4. 若步骤3生成了规划器更新后的Spec路径/产物,在调用上下文中应用路径替换,使Spec/交接/未决问题的引用指向更新后的文件。
    • 若规划器也更改了
      run_project_dir
      ,使用更新后的
      run_project_dir
      解析提示/输出约定路径。
  5. 保留原始生成提示中的所有非路径指令不变。
  6. 使用解析后的调用上下文调用
    /agentforce-generate
  7. 读取
    <run_project_dir>/agentforce-generate-output-contract.md
    并严格按指定捕获输出。
并行化规则:
  • 针对多个Agent Spec并行调用
    /agentforce-generate
    ,因为每次运行相互独立。
输出约定捕获规则:
  1. 将输出约定视为必填字段/产物的权威来源。
  2. 若任何约定字段缺失,将状态标记为部分完成并明确列出缺失字段。
  3. 返回捕获的输出,使用与约定名称匹配的确定性键。
  4. 保留每个必填产物的输出文件路径和状态。
  5. 若某个条目对应的预期提示/约定文件缺失,将该条目标记为
    partial
    ,记录缺失路径,并继续处理其他条目。

Step 5: Post-Conversion Agent Script Enhancements (Per Generated Agent Script)

步骤5:转换后Agent Script增强(按生成的Agent Script)

After Step 4 completes, for each generated
.agent
artifact:
  1. Resolve the generated
    .agent
    file path from captured
    /agentforce-generate
    outputs.
  2. Execute post-conversion enhancement workflow from Post-Conversion Enhancements Reference with:
    • agentscript_file=<generated-agent-file-path>
    • mode=<online|offline>
      (the effective orchestrator run mode resolved in Step 1)
    • online mode only:
      org_alias=<org-alias>
      (required so the enhanced Agent Script can be redeployed)
  3. Require in-place enhancement:
    • optimized/enhanced output must be written to the same
      .agent
      file location.
  4. Capture per-file enhancement status and any partial failures.
Parallelization rule:
  • Execute post-conversion enhancement workflow in parallel across generated
    .agent
    files because each file enhancement is independent.
步骤4完成后,针对每个生成的
.agent
产物:
  1. 从捕获的
    /agentforce-generate
    输出中解析生成的
    .agent
    文件路径。
  2. 使用以下参数执行Post-Conversion Enhancements Reference中的转换后增强工作流:
    • agentscript_file=<generated-agent-file-path>
    • mode=<online|offline>
      (步骤1中确定的协调器生效运行模式)
    • 仅在线模式:
      org_alias=<org-alias>
      (必填,以便重新部署增强后的Agent Script)
  3. 要求原地增强:
    • 优化/增强后的输出必须写入同一
      .agent
      文件位置。
  4. 捕获每个文件的增强状态及任何部分失败情况。
并行化规则:
  • 针对多个生成的
    .agent
    文件并行执行转换后增强工作流,因为每个文件的增强相互独立。

Step 6: Consolidate Run Report and Conclude

步骤6:合并运行报告并结束

After Step 5 completes for every bot in the workload:
  1. 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 (
    executed
    or
    skipped
    ), the generated Agent Spec path and generated
    .agent
    path, the action inventory (including any
    NEEDS_STUB
    items), and — when
    --interactive=false
    — the auto-applied decisions.
  2. 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
    .agent
    file(s)) are already written.
步骤5针对任务中的所有机器人完成后:
  1. 在协调器工作目录中写入一份合并的、人类可读的Markdown格式运行报告(不能为空)。针对每个机器人,报告必须说明:生效运行模式、规划器是否运行(
    executed
    skipped
    )、生成的Agent Spec路径和生成的
    .agent
    路径、操作清单(包括任何
    NEEDS_STUB
    项),以及当
    --interactive=false
    时自动应用的决策。
  2. 将运行报告视为最终产物:仅在所有其他产物(Agent Spec、交接JSON、未决问题、任何规划器输出、生成的
    .agent
    文件)已写入后再编写报告。

Deliverable

交付物

Return:
  1. parsed bot/version list
  2. per-bot upgrade execution status
  3. aggregation output (full Agent Spec list + final ready-for-authoring subset)
  4. planner workflow status (
    executed
    or
    skipped
    ) and
    bot-upgrade-planner-output.json
    path when executed
  5. per-spec
    /agentforce-generate
    execution status
  6. generated handoff artifact paths per bot/spec (including planner-updated artifacts when applicable)
  7. captured
    /agentforce-generate
    outputs per output contract
  8. per-agent post-conversion enhancement status (including enhanced
    .agent
    file paths)
  9. path to the consolidated run report written in Step 6
返回:
  1. 解析后的机器人/版本列表
  2. 每个机器人的升级执行状态
  3. 聚合输出(完整Agent Spec列表 + 最终可创作子集)
  4. 规划器工作流状态(
    executed
    skipped
    ),以及执行时的
    bot-upgrade-planner-output.json
    路径
  5. 每个Spec的
    /agentforce-generate
    执行状态
  6. 每个机器人/Spec的生成交接产物路径(若适用,包括规划器更新后的产物)
  7. 按输出约定捕获的
    /agentforce-generate
    输出
  8. 每个Agent的转换后增强状态(包括增强后的
    .agent
    文件路径)
  9. 步骤6中编写的合并运行报告路径