service-itsm-agentic-setup-fulfiller-agent-configure

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create the IT Service Fulfiller Agent

创建IT Service Fulfiller Agent

Create and activate the IT Service Fulfiller Agent as a Next-Gen Authoring (NGA) native agent — Agent-Script-based (

AiAuthoringBundleDefVer

/bundle), appearing natively in Agentforce Studio's Agents list with no external-link icon — entirely through the Salesforce CLI (
sf
). This skill does not call the legacy
/connect/service-itsm/createAgent
; instead it reuses the shipped ITSM Fulfiller template's

agentScript

and feeds it into the NGA bundle pipeline:

```
POST /nextgen-authoring/bundles
```
(
```
createBundleWithVersion
```
) — creates the bundle + first version from the template's Agent Script.

POST /nextgen-authoring/bundle-versions/{id}/publish

— publishes the version (creates the underlying

BotDefinition

BotVersion

POST /nextgen-authoring/bundle-versions/{id}/activate

— activates it.

Commands:

sf api request rest

for Connect API GET/POST;

sf data query

for the SOQL idempotency + verify reads.

Helper scripts (invoked via

Bash

) hold every JSON-parsing / decision rule so the model never eyeballs a response body (A9):

classify-preflight.mjs

(Studio-access + template-provisioning verdict),

classify-agent-existence.mjs

(idempotency + reactivation-need from the

BotDefinition

SOQL),

build-create-body.mjs

(HTML-decodes and substitutes the template's

agentScript

, writes the bundle-create body to a JSON file so large content and free-text quotes never hit an inline shell string),

render-report.mjs

(deterministic report renderer — single source of report text for chat-turn and harness file).

The Fulfiller agent is the IT-technician-facing assistant — incident triage, case summarization, field updates, related-record automations. The employee self-service surface is

service-itsm-agentic-setup-employee-agent-configure

将IT Service Fulfiller Agent创建并激活为Next-Gen Authoring（NGA）原生Agent——基于Agent Script（

AiAuthoringBundleDefVer

/包），会原生显示在Agentforce Studio的Agent列表中，无外部链接图标——全程通过**Salesforce CLI（

sf

）**完成。本技能不会调用旧版
/connect/service-itsm/createAgent
接口；而是复用已内置的ITSM履行者模板的

agentScript

，将其传入NGA包流程：

```
POST /nextgen-authoring/bundles
```
（
```
createBundleWithVersion
```
）——从模板的Agent Script创建包及首个版本。

POST /nextgen-authoring/bundle-versions/{id}/publish

——发布该版本（创建底层的

BotDefinition

BotVersion

）。

POST /nextgen-authoring/bundle-versions/{id}/activate

——激活该版本。

命令：使用

sf api request rest

调用Connect API的GET/POST请求；使用

sf data query

执行SOQL幂等性检查及验证读取操作。

通过

Bash

调用的辅助脚本包含所有JSON解析/决策规则，确保模型无需手动处理响应体（A9）：

classify-preflight.mjs

（Studio访问权限+模板配置结果判定）、

classify-agent-existence.mjs

（基于

BotDefinition

SOQL的幂等性+重新激活需求判定）、

build-create-body.mjs

（HTML解码并替换模板的

agentScript

，将包创建请求体写入JSON文件，避免大内容和自由文本引号破坏内联shell字符串）、

render-report.mjs

（确定性报告渲染器——为对话回合和测试工具文件提供统一的报告文本来源）。

Fulfiller Agent是面向IT技术人员的助手——用于事件分类、案例摘要、字段更新以及相关记录自动化。员工自助服务端面对应的是

service-itsm-agentic-setup-employee-agent-configure

。

Scope

范围

In scope: Reading
```
agent-templates
```
; extracting the Fulfiller template's Agent Script (
```
svc_itsm_intelligence__ITSrvcMgmtFulfiller
```
); creating the Fulfiller agent as an NGA-native agent via
```
createBundleWithVersion
```
→
```
publish
```
→
```
activate
```
; SOQL-verifying live; idempotent skip on duplicate developer name — all via
```
sf
```
.
Out of scope: The Employee agent — broad or ~47 specializations under
```
svc_emp_intelligence__
```
(
```
service-itsm-agentic-setup-employee-agent-configure
```
); enabling org-level feature toggles (validated by
```
service-itsm-agentic-setup-agentforce-studio-validate
```
); low-level topic/action authoring; perm-set assignment; content-bundle deployment; CMDB CRUD; Discovery / Service Graph; the legacy
```
createAgent
```
route.

包含范围：读取
```
agent-templates
```
；提取履行者模板的Agent Script（
```
svc_itsm_intelligence__ITSrvcMgmtFulfiller
```
）；通过
```
createBundleWithVersion
```
→
```
publish
```
→
```
activate
```
流程将履行者Agent创建为NGA原生Agent；通过SOQL验证其处于可用状态；基于重复开发者名称实现幂等跳过——所有操作均通过
```
sf
```
完成。
排除范围：员工Agent——
```
svc_emp_intelligence__
```
下的通用或约47个专用Agent（对应
```
service-itsm-agentic-setup-employee-agent-configure
```
）；启用组织级功能开关（由
```
service-itsm-agentic-setup-agentforce-studio-validate
```
验证）；底层主题/操作创建；权限集分配；内容包部署；CMDB增删改查；Discovery/服务图谱；旧版
```
createAgent
```
路由。

Preconditions

前置条件

If any of these are unmet,

sf

surfaces an auth error or a

; surface the raw error verbatim and stop — do not fabricate state.

sf
CLI authenticated to the target org (
```
sf org display -o <alias>
```
shows Connected). All calls use
```
--target-org <alias>
```
; never extract the access token by hand.
API v67.0+ — pinned in the URL path; do not hand-edit below the minimum.

ITSM features + Fulfiller template provisioned (

svc_itsm_intelligence__ITSrvcMgmtFulfiller

). If

agent-templates

returns nothing or the routes 404, run

service-itsm-agentic-setup-agentforce-studio-validate

node
≥ 18 on PATH.

若以下任意条件不满足，

sf

会返回认证错误或

；直接显示原始错误并终止操作——请勿伪造状态。

sf
CLI已认证至目标组织（
```
sf org display -o <alias>
```
显示已连接）。所有调用均使用
```
--target-org <alias>
```
参数；切勿手动提取访问令牌。
API版本v67.0+——在URL路径中固定指定；请勿手动修改为低于该版本。

已配置ITSM功能及履行者模板（

svc_itsm_intelligence__ITSrvcMgmtFulfiller

）。若

agent-templates

返回空结果或路由返回404，请运行

service-itsm-agentic-setup-agentforce-studio-validate

。

PATH中存在
node
≥ 18。

Operations at a glance

操作概览

Concern	Command	Notes
Studio access (precondition read)	`sf api request rest "/services/data/v67.0/agentforce-studio/access/Agents" --method GET -o <alias>`	`hasAccess=false` ⇒ prereq hand-off
List agent templates + Agent Script (read)	`sf api request rest "/services/data/v67.0/connect/service-itsm/agent-templates?agentType=AgentforceEmployeeAgent" --method GET -o <alias>`	`agentType=AgentforceEmployeeAgent` required; confirms Fulfiller template + non-empty `agentScript`
Enumerate the existing agent + latest version status (read)	`sf data query -q "SELECT Id,DeveloperName,MasterLabel,(SELECT Id,Status FROM BotVersions ORDER BY VersionNumber DESC LIMIT 1) FROM BotDefinition WHERE Id='<botDefinitionId>' OR DeveloperName='<developerName>'" -o <alias> --json`	Keyed PRIMARILY on the template's `botDefinitionId` (Phase-1 row); the `OR DeveloperName=` clause is both the null- `botDefinitionId` fallback (the normal Fulfiller case) AND the guard for a dangling Id link (deleted target). Classified by `scripts/classify-agent-existence.mjs` ; Active latest ⇒ ALREADY-CREATED; Inactive latest ⇒ offer reactivation
Create the NGA bundle (write)	`sf api request rest "/services/data/v67.0/nextgen-authoring/bundles" --method POST --body @<body-file> -o <alias>`	Body built by `scripts/build-create-body.mjs` ; response `id` = the bundle version Id
Publish the bundle version (write)	`sf api request rest "/services/data/v67.0/nextgen-authoring/bundle-versions/<bundleVersionId>/publish" --method POST --body '{}' -o <alias>`	Returns `publishedBotId` / `publishedBotVersionId` — creates the underlying `BotDefinition` / `BotVersion`
Activate the bundle version (write)	`sf api request rest "/services/data/v67.0/nextgen-authoring/bundle-versions/<bundleVersionId>/activate" --method POST --body '{}' -o <alias>`	Empty response on success; agent is now live and NGA-native
Activate an existing inactive version (write)	`sf api request rest "/services/data/v67.0/connect/bot-versions/<latestVersionId>/activation" --method POST --body '{"status":"Active"}' -o <alias>`	Reactivation path only (Phase 2b) — skips create/publish
Verify agent is live (read)	`sf data query -q "SELECT ... FROM BotDefinition WHERE Id='<verifyId>'" -o <alias> --json`	`<verifyId>` = create path's `publishedBotId` (Phase-5) or the Phase-2 classifier's returned live matched Id (its `botDefinitionId` / `agentId` ) on ALREADY-CREATED / reactivation — not the null Phase-1 template `botDefinitionId` , never the collected developerName; confirm `BotDefinition` present + latest version Active

Full command shapes and the ITSM Connect API reference live in

references/cli-invocation.md

; the reactivation-path call + idempotency verdict table live in

references/reactivation.md

; the response-body error codes and recurring gotchas live in

references/error-taxonomy.md

Never extract the access token. Use
sf api request rest
/
sf data query
directly — they use the CLI's stored session for the target org. Do not pull the
accessToken
out of
sf org display
and hand-build an HTTP request with it; that bypasses the CLI session and leaks a bearer token into shell context.

--json
rule.
sf data query
takes
--json
(results come back in a
.result.records[]
envelope — that's what the classifier expects).
sf api request rest
does not — omit
--json
there; its raw stdout body is already JSON.

关注点	命令	说明
Studio访问权限（前置条件检查）	`sf api request rest "/services/data/v67.0/agentforce-studio/access/Agents" --method GET -o <alias>`	`hasAccess=false` ⇒ 移交至前置条件检查流程
列出Agent模板及Agent Script（读取）	`sf api request rest "/services/data/v67.0/connect/service-itsm/agent-templates?agentType=AgentforceEmployeeAgent" --method GET -o <alias>`	必须指定 `agentType=AgentforceEmployeeAgent` ；用于确认履行者模板及非空的 `agentScript`
枚举现有Agent及最新版本状态（读取）	`sf data query -q "SELECT Id,DeveloperName,MasterLabel,(SELECT Id,Status FROM BotVersions ORDER BY VersionNumber DESC LIMIT 1) FROM BotDefinition WHERE Id='<botDefinitionId>' OR DeveloperName='<developerName>'" -o <alias> --json`	主要基于模板的 `botDefinitionId` （第一阶段行）； `OR DeveloperName=` 子句既是 `botDefinitionId` 为空时的回退方案（履行者Agent的常规场景），也是针对无效Id链接（目标已删除）的防护措施。由 `scripts/classify-agent-existence.mjs` 进行分类；若最新版本为Active ⇒ 已创建；若最新版本为Inactive ⇒ 提供重新激活选项
创建NGA包（写入）	`sf api request rest "/services/data/v67.0/nextgen-authoring/bundles" --method POST --body @<body-file> -o <alias>`	请求体由 `scripts/build-create-body.mjs` 生成；响应中的 `id` 为包版本Id
发布包版本（写入）	`sf api request rest "/services/data/v67.0/nextgen-authoring/bundle-versions/<bundleVersionId>/publish" --method POST --body '{}' -o <alias>`	返回 `publishedBotId` / `publishedBotVersionId` ——创建底层的 `BotDefinition` / `BotVersion`
激活包版本（写入）	`sf api request rest "/services/data/v67.0/nextgen-authoring/bundle-versions/<bundleVersionId>/activate" --method POST --body '{}' -o <alias>`	成功时返回空响应；Agent此时处于可用状态且为NGA原生Agent
激活现有非活跃版本（写入）	`sf api request rest "/services/data/v67.0/connect/bot-versions/<latestVersionId>/activation" --method POST --body '{"status":"Active"}' -o <alias>`	仅用于重新激活流程（第二阶段b）——跳过创建/发布步骤
验证Agent处于可用状态（读取）	`sf data query -q "SELECT ... FROM BotDefinition WHERE Id='<verifyId>'" -o <alias> --json`	`<verifyId>` 为创建流程中的 `publishedBotId` （第五阶段），或已创建/重新激活流程中第二阶段分类器返回的匹配Id（其 `botDefinitionId` / `agentId` ——匹配记录的实际 `BotDefinition.Id` ）；不可使用第一阶段模板的 `botDefinitionId` （履行者Agent的该值始终为空），也不可使用收集到的developerName；需确认 `BotDefinition` 存在且最新版本为Active

完整命令格式及ITSM Connect API参考位于

references/cli-invocation.md

；重新激活流程调用及幂等性判定表位于

references/reactivation.md

；响应体错误码及常见问题位于

references/error-taxonomy.md

。

切勿提取访问令牌。直接使用
sf api request rest
/
sf data query
——它们会使用CLI存储的目标组织会话。请勿从
sf org display
中提取
accessToken
并手动构建HTTP请求；这会绕过CLI会话并将Bearer令牌泄露至shell上下文。

--json
规则。
sf data query
需要添加
--json
参数（结果会封装在
.result.records[]
中——这是分类器所需的格式）。
sf api request rest
不需要添加该参数；其标准输出本身已是JSON格式。

Shipped ITSM Fulfiller agent template

内置ITSM履行者Agent模板

Template identifier	Default developer name
`svc_itsm_intelligence__ITSrvcMgmtFulfiller` ( `masterLabel` "IT Service Fulfiller")	`IT_Service_Fulfiller_Agent`

The
agentScript
field is the source of truth for the NGA create — not
id
.
scripts/build-create-body.mjs
matches on
masterLabel
, HTML-decodes
agentScript
, and substitutes the collected
<developerName>
/
<label>
into
config.developer_name
/
config.agent_label
before it becomes the bundle's
resourceContent
. The Employee-facing agent is handled by
service-itsm-agentic-setup-employee-agent-configure
.

模板标识符	默认开发者名称
`svc_itsm_intelligence__ITSrvcMgmtFulfiller` （ `masterLabel` 为"IT Service Fulfiller"）	`IT_Service_Fulfiller_Agent`

agentScript
字段是NGA创建流程的唯一可信来源——而非
id
。
scripts/build-create-body.mjs
会匹配
masterLabel
，HTML解码
agentScript
，并将收集到的
<developerName>
/
<label>
替换为
config.developer_name
/
config.agent_label
，然后将其作为包的
resourceContent
。面向员工的Agent由
service-itsm-agentic-setup-employee-agent-configure
处理。

Architecture — Creation stages

架构——创建阶段

Stage	What happens	Tool used
Preflight	Confirm Studio access ( `agentforce-studio/access/Agents` ) and that the template's `agentScript` is present	`Bash` ( `sf api request rest` )
Enumerate	Read the Fulfiller template ( `agent-templates` ) and existing agents + latest version status (SOQL on `BotDefinition` / `BotVersions` ); classify idempotency and reactivation-need via script	`Bash` ( `sf` , `node` )
Confirm-to-write	Present the exact developerName + label (the NGA create target), OR — if the existing agent is inactive — present the reactivation option instead, and require explicit "yes" either way	`AskUserQuestion`
Create (create path only)	POST `createBundleWithVersion` (builds the NGA bundle + first version from the decoded, substituted template Agent Script)	`Bash` ( `sf api request rest` , `node` )
Publish (create path only)	POST `.../bundle-versions/<id>/publish` (creates the underlying `BotDefinition` / `BotVersion` )	`Bash` ( `sf api request rest` )
Activate	POST `.../bundle-versions/<id>/activate` (create path) OR POST `.../connect/bot-versions/<latestVersionId>/activation` with `{"status":"Active"}` (reactivation path — skips create/publish)	`Bash` ( `sf api request rest` )
Verify	SOQL-read `BotDefinition` / `BotVersions` and confirm the agent exists with an Active latest version	`Bash` ( `sf data query` )

Idempotency: keyed PRIMARILY on the template's
botDefinitionId
(Phase-1

agent-templates

row — the platform's authoritative template→

BotDefinition

link) and FALLING BACK to the collected

<developerName>

. The Phase-2 read is

BotDefinition WHERE Id='<botDefinitionId>' OR DeveloperName='<developerName>'

(the

OR

half is both the null-

botDefinitionId

fallback — the normal Fulfiller case — AND the guard for a dangling Id link whose target

BotDefinition

was deleted, so a stale link can't slip through to create), + latest

BotVersion.Status

(classified by the helper script). Outcomes: no match on either key ⇒

exists:false

⇒ create;

latestVersionStatus:"Active"

⇒ ALREADY-CREATED (skip the write, fall through to Phase 7 verification);

needsActivation:true

(latest version

Inactive

) ⇒ offer to activate the existing version instead of creating a new agent (Phase 2b) rather than silently skipping or duplicating. Why the fallback matters: the Fulfiller is never pre-provisioned and this skill's create path never stamps

templateName

, so the template's

botDefinitionId

is always

null

— the

<developerName>

-keyed fallback is the guard that actually catches a repeat run; short-circuiting straight to create on a null

botDefinitionId

would re-create and collide with

DUPLICATE_VALUE

. The server does reject a duplicate

DeveloperName

at publish (unique-constraint → bundle cleanup), but only this Phase-2 read turns a repeat into a graceful skip instead of that hard error.

阶段	操作内容	使用工具
预检	确认Studio访问权限（ `agentforce-studio/access/Agents` ）及模板的 `agentScript` 存在	`Bash` （ `sf api request rest` ）
枚举	读取履行者模板（ `agent-templates` ）及现有Agent的最新版本状态（对 `BotDefinition` / `BotVersions` 执行SOQL查询）；通过脚本判定幂等性及重新激活需求	`Bash` （ `sf` , `node` ）
确认写入权限	显示确切的开发者名称+标签（NGA创建目标），或——若现有Agent处于非活跃状态——显示重新激活选项，且无论哪种情况均需用户明确回复“yes”	`AskUserQuestion`
创建（仅创建流程）	调用 `createBundleWithVersion` 接口（从解码并替换后的模板Agent Script创建NGA包及首个版本）	`Bash` （ `sf api request rest` , `node` ）
发布（仅创建流程）	调用 `.../bundle-versions/<id>/publish` 接口（创建底层的 `BotDefinition` / `BotVersion` ）	`Bash` （ `sf api request rest` ）
激活	调用 `.../bundle-versions/<id>/activate` 接口（创建流程）或调用 `.../connect/bot-versions/<latestVersionId>/activation` 并传入 `{"status":"Active"}` （重新激活流程——跳过创建/发布步骤）	`Bash` （ `sf api request rest` ）
验证	对 `BotDefinition` / `BotVersions` 执行SOQL查询，确认Agent存在且最新版本为Active	`Bash` （ `sf data query` ）

幂等性：主要基于模板的
botDefinitionId
（第一阶段

agent-templates

行——平台官方的模板→

BotDefinition

关联），当该值为空时回退至收集到的

<developerName>

。第二阶段的查询为

BotDefinition WHERE Id='<botDefinitionId>' OR DeveloperName='<developerName>'

（

OR

部分既是

botDefinitionId

为空时的回退方案——履行者Agent的常规场景，也是针对无效Id链接（目标

BotDefinition

已删除）的防护措施，避免因陈旧链接导致重复创建），结合最新

BotVersion.Status

（由辅助脚本分类）。结果：两个键均无匹配 ⇒

exists:false

⇒ 创建；

latestVersionStatus:"Active"

⇒ 已创建（跳过写入步骤，直接进入第七阶段验证）；

needsActivation:true

（最新版本为Inactive） ⇒ 提供激活现有版本的选项而非创建新Agent（第二阶段b），而非静默跳过或重复创建。回退方案的重要性：履行者Agent从未预配置，且本技能的创建流程不会标记

templateName

，因此模板的

botDefinitionId

始终为空——基于

<developerName>

的回退方案是防止重复运行的关键；若因

botDefinitionId

为空直接跳过检查进入创建流程，会导致重复创建并触发

DUPLICATE_VALUE

错误。服务器会在发布阶段拒绝重复的

DeveloperName

（唯一约束→包清理），但只有第二阶段的查询能将重复运行转化为优雅跳过，而非硬错误。

Clarifying Questions

澄清问题

Collect from the user (ask only what is not already in conversation context):

Field	Description	Default
Target org	The `sf` org alias to create the agent in	Default org ( `sf config get target-org` )
Developer name	Unique `DeveloperName` for the agent	`IT_Service_Fulfiller_Agent`
Label	User-facing label for the agent	`IT Service Fulfiller Agent`
Confirm the write	Explicit confirmation before the create/publish/activate sequence	REQUIRED — present the developerName + label and require "yes" via `AskUserQuestion`

The idempotency read keys PRIMARILY on the template's
botDefinitionId
(Phase-1 row) and FALLS BACK to the collected

<developerName>

when that is null; the verify read keys on the publish response's

publishedBotId

(create path) or the template's

botDefinitionId

(ALREADY-CREATED / reactivation). The collected

<developerName>

and

<label>

(defaults

IT_Service_Fulfiller_Agent

IT Service Fulfiller Agent

) also thread through the

createBundleWithVersion

body — both the outer

apiName

label

AND the substituted

config.developer_name

config.agent_label

inside the Agent Script. Never hardcode the name in one call and collect it in another — a mismatch between the bundle's outer

apiName

and the script's internal

developer_name

causes the platform to diverge the two. Creating an agent provisions a live, activated agent on the org; the user must explicitly approve the write.

需向用户收集以下信息（仅询问对话上下文中未包含的内容）：

字段	描述	默认值
目标组织	创建Agent的 `sf` 组织别名	默认组织（ `sf config get target-org` ）
开发者名称	Agent的唯一 `DeveloperName`	`IT_Service_Fulfiller_Agent`
标签	Agent的用户可见标签	`IT Service Fulfiller Agent`
确认写入权限	在创建/发布/激活序列前需用户明确确认	必填——显示开发者名称+标签，通过 `AskUserQuestion` 要求用户回复“yes”

幂等性查询主要基于模板的
botDefinitionId
（第一阶段行），当该值为空时回退至收集到的

<developerName>

；验证查询基于发布响应中的

publishedBotId

（创建流程）或模板的

botDefinitionId

（已创建/重新激活流程）。收集到的

<developerName>

和

<label>

（默认值为

IT_Service_Fulfiller_Agent

IT Service Fulfiller Agent

）也会贯穿

createBundleWithVersion

请求体——包括外层的

apiName

label

以及Agent Script内部替换后的

config.developer_name

config.agent_label

。切勿在一处硬编码名称而在另一处收集名称——包的外层

apiName

与脚本内部

developer_name

不匹配会导致平台状态不一致。创建Agent会在组织中配置一个可用的已激活Agent；用户必须明确批准写入操作。

Workflow

工作流

Substitute

<alias>

with the collected target org and

<developerName>

<label>

with the collected values. Full command shapes + per-phase verdict-branch handling live in

references/workflow-detail.md

— the phase summary below names each step and its load-bearing rule; the reference file holds the exact

sf

node

invocations to copy.

Phase 0 — Establish
${SCRATCH_DIR}
. Invoke the deterministic helper (path is skill-root-qualified so it resolves regardless of the shell's CWD):
```
SCRATCH_DIR="$(node "<skill_dir>/scripts/create-scratch-dir.mjs" "${outputDir:-}")"
```
. Helper picks the base dir (
```
${TMPDIR}
```
, else
```
/tmp
```
, else the harness
```
${outputDir}
```
last-resort — scratch stays OUT of the scored
```
${outputDir}
```
tree) and emits the created dir on stdout. All transient JSON lands under
```
${SCRATCH_DIR}
```
; the durable
```
${outputDir}/report.md
```
stays under the harness dir.
Phase 1 — Preflight. Capture the Studio-access read +
```
agent-templates
```
read (with the required
```
agentType=AgentforceEmployeeAgent
```
query param) into
```
${SCRATCH_DIR}/agent-templates.json
```
, then classify via
```
scripts/classify-preflight.mjs "IT Service Fulfiller"
```
. The classifier also emits
```
template.botDefinitionId
```
from the matched row — capture it; it is the primary Phase-2 idempotency key (the collected
<developerName>
is the fallback key). Branch on
```
verdict
```
:
```
READY
```
⇒ Phase 2;
```
NOT-READY
```
⇒ prerequisite hand-off via
```
AskUserQuestion
```
(delegate to
```
service-itsm-agentic-setup-agentforce-studio-validate
```
on "yes");
```
ERROR
```
⇒ surface + stop;
```
studio.signal="CANNOT-CONFIRM"
```
(confirmed 404) does not block.
Phase 2 — Idempotency (primary key
botDefinitionId
, fallback key
<developerName>
). Take
```
template.botDefinitionId
```
from Phase 1. Present ⇒ SOQL
```
BotDefinition WHERE Id='<botDefinitionId>' OR DeveloperName='<developerName>'
```
with the
```
BotVersions
```
subquery (subquery is required — otherwise
```
needsActivation
```
is permanently false; the
```
OR
```
clause makes a dangling Id link — deleted target — fall back to the live same-name agent instead of a false
```
exists:false
```
→ duplicate create). Empty/null (the normal Fulfiller case — the template row is never back-filled) ⇒ do NOT skip to create; fall back to
```
BotDefinition WHERE DeveloperName='<developerName>'
```
(a self-created agent from a prior run has a null template
```
botDefinitionId
```
but still exists). Either way classify via
```
scripts/classify-agent-existence.mjs ${SCRATCH_DIR}/bot-existing.json "<botDefinitionId-or-empty>" "<developerName>"
```
. Branch:
```
exists:false
```
⇒ Phase 2c (action-availability gate, then create);
```
exists:true
```
+
```
needsActivation:false
```
⇒ ALREADY-CREATED (skip straight to Phase 7 — no action-availability gate; a live active agent's actions are already wired);
```
exists:true
```
+
```
needsActivation:true
```
⇒ Phase 2b. Non-zero exit ⇒ surface CLI error; never assume absent. Why the fallback: the Fulfiller is never pre-provisioned, so
```
botDefinitionId
```
is always null — a missing developerName check would re-create and hit
```
DUPLICATE_VALUE
```
.
Phase 2b — Reactivation offer.
```
AskUserQuestion
```
: "Fulfiller agent
<developerName>
exists but latest version is Inactive. Activate it?". On Yes:
```
POST /connect/bot-versions/<latestVersionId>/activation
```
with
```
{"status":"Active"}
```
captured to
```
${SCRATCH_DIR}/activate-response.json
```
, then
```
node "<skill_dir>/scripts/classify-activate-result.mjs" ${SCRATCH_DIR}/activate-response.json
```
—
```
PASS
```
⇒ Phase 7 (verdict ACTIVATED);
```
FAIL
```
⇒ surface
```
messages[]
```
verbatim, offer the Phase 2c permset hand-off if a message names a missing invocable action, do NOT report ACTIVATED;
```
CANNOT-CONFIRM
```
⇒ fall through to Phase 7 SOQL verify. On No: stop, no writes.

Phase 2c — Action-availability preflight (create path only; reached only from Phase 2
exists:false
). Capture

sf api request rest "/services/data/v67.0/actions/custom/generatePromptResponse" --method GET

${SCRATCH_DIR}/generate-prompt-response.json

, then

node "<skill_dir>/scripts/classify-action-availability.mjs" ${SCRATCH_DIR}/agent-templates.json "IT Service Fulfiller" ${SCRATCH_DIR}/generate-prompt-response.json

. Branch on

verdict

READY

⇒ Phase 3;

NOT-READY

⇒

AskUserQuestion

offering hand-off to

service-itsm-agentic-setup-itsm-agentforce-permset-assign

(surface

missing[]

verbatim — do NOT proceed to write; the activate call would return HTTP 200 with a

{success:false}

silent-failure body);

CANNOT-CONFIRM

⇒ surface reasons and proceed with caution (Phase 6 activate-result classifier catches the silent-failure body). Full contract in

references/action-availability.md

Phase 3 — Confirm-to-Write (REQUIRED, create path only). If
```
${outputDir}
```
was provided, first render the checkpoint file via
```
render-report.mjs
```
with
```
verdict:"PENDING CONFIRMATION"
```
(skip for interactive runs). THEN raise the
```
AskUserQuestion
```
gate presenting developerName + label + "NGA-native from the Fulfiller template's Agent Script". Proceed only on explicit "yes"; on "no", re-render with
```
verdict:"DECLINED"
```
.

Phase 4 — Create.

scripts/build-create-body.mjs ${SCRATCH_DIR}/agent-templates.json "IT Service Fulfiller" "<developerName>" "<label>" ${SCRATCH_DIR}/create-bundle-body.json

(helper re-reads Phase-1 templates JSON, HTML-decodes the matched

agentScript

, substitutes internal

config.developer_name

config.agent_label

, writes body to file), then

POST /nextgen-authoring/bundles --body @${SCRATCH_DIR}/create-bundle-body.json

. Capture response
id
— that is the

bundleVersionId

for Phases 5–6, not

bundleId

403 FUNCTIONALITY_NOT_ENABLED

⇒ trigger the Phase-1 hand-off; build-script exit 3 ⇒ surface stderr.

Phase 5 — Publish.
```
POST /nextgen-authoring/bundle-versions/<bundleVersionId>/publish --body '{}'
```
(empty body required). Success:
```
{ lastPublishedOn, publishedBotId, publishedBotVersionId }
```
— this call creates the underlying
```
BotDefinition
```
/
```
BotVersion
```
. Any error ⇒ surface verbatim; never activate an unpublished version.
Phase 6 — Activate.
```
POST /nextgen-authoring/bundle-versions/<bundleVersionId>/activate --body '{}'
```
captured to
```
${SCRATCH_DIR}/activate-response.json
```
, then
```
node "<skill_dir>/scripts/classify-activate-result.mjs" ${SCRATCH_DIR}/activate-response.json
```
— activate can return HTTP 200 with a
```
{success:false}
```
silent-failure body when a referenced invocable action isn't surfaced; the classifier catches that.
```
PASS
```
⇒ Phase 7;
```
FAIL
```
⇒ surface
```
messages[]
```
, offer Phase 2c permset hand-off if a message names a missing action, do NOT report CREATED;
```
CANNOT-CONFIRM
```
⇒ fall through to Phase 7 SOQL verify.
Phase 7 — Verify. SOQL
```
BotDefinition WHERE Id='<id>'
```
(+
```
BotVersions
```
subquery) and classify —
```
<id>
```
is the create path's
```
publishedBotId
```
(captured from Phase 5) or, on the ALREADY-CREATED / reactivation path, the live matched Id the Phase-2 classifier returned (its
```
botDefinitionId
```
/
```
agentId
```
output — the actual
```
BotDefinition.Id
```
of the matched record), not the Phase-1 template
```
botDefinitionId
```
(which is always null for the Fulfiller, so on any existing-agent hit the verify would run
```
WHERE Id=''
```
and falsely report failure after a successful skip/activation). Confirm
```
exists:true, count:1, latestVersionStatus:"Active"
```
. Any discrepancy ⇒ report verbatim, do not fabricate success.
Phase 8 — Aggregate verdict. Emit CREATED / ALREADY-CREATED / ACTIVATED / FAILED (ACTIVATED on the Phase-2b path) +
```
BotDefinition
```
Id / bundle
```
id
```
by re-invoking
```
render-report.mjs
```
— the single source of report text. If
```
${outputDir}
```
was provided, overwrite
```
${outputDir}/report.md
```
; otherwise emit stdout as the turn-side report.

将

<alias>

替换为收集到的目标组织，

<developerName>

<label>

替换为收集到的值。完整命令格式+各阶段判定分支处理逻辑位于

references/workflow-detail.md

——以下阶段摘要列出每个步骤及其核心规则；参考文件包含可直接复制的精确

sf

node

调用命令。

阶段0 — 创建
${SCRATCH_DIR}
。调用确定性辅助脚本（路径为技能根目录相对路径，确保无论shell的当前工作目录如何均可解析）：
```
SCRATCH_DIR="$(node "<skill_dir>/scripts/create-scratch-dir.mjs" "${outputDir:-}")"
```
。辅助脚本会选择基础目录（优先
```
${TMPDIR}
```
，其次
```
/tmp
```
，最后为测试工具的
```
${outputDir}
```
——临时文件会存放在评分用
```
${outputDir}
```
目录之外），并在标准输出中返回创建的目录。所有临时JSON文件均存放在
```
${SCRATCH_DIR}
```
下；持久化的
```
${outputDir}/report.md
```
存放在测试工具目录下。
阶段1 — 预检。将Studio访问权限查询结果+
```
agent-templates
```
查询结果（必须包含
```
agentType=AgentforceEmployeeAgent
```
查询参数）保存至
```
${SCRATCH_DIR}/agent-templates.json
```
，然后通过
```
scripts/classify-preflight.mjs "IT Service Fulfiller"
```
进行分类。分类器还会从匹配行中提取
```
template.botDefinitionId
```
——请保存该值；它是第二阶段幂等性的主要键（收集到的
<developerName>
是回退键）。根据
```
verdict
```
分支：
```
READY
```
⇒ 阶段2；
```
NOT-READY
```
⇒ 通过
```
AskUserQuestion
```
移交至前置条件检查流程（用户回复“yes”则委托给
```
service-itsm-agentic-setup-agentforce-studio-validate
```
）；
```
ERROR
```
⇒ 显示错误并终止；
```
studio.signal="CANNOT-CONFIRM"
```
（已确认404）不阻塞流程。
阶段2 — 幂等性检查（主键
botDefinitionId
，回退键
<developerName>
）。使用阶段1获取的
```
template.botDefinitionId
```
。执行⇒ 对
```
BotDefinition WHERE Id='<botDefinitionId>' OR DeveloperName='<developerName>'
```
执行SOQL查询，包含
```
BotVersions
```
子查询（必须包含子查询——否则
```
needsActivation
```
始终为false；
```
OR
```
子句会使无效Id链接（目标已删除）回退至同名的可用Agent，而非错误地判定
```
exists:false
```
→重复创建）。空值/Null（履行者Agent的常规场景——模板行从未回填）⇒ 请勿直接跳过进入创建流程；回退至
```
BotDefinition WHERE DeveloperName='<developerName>'
```
查询（之前运行创建的Agent的模板
```
botDefinitionId
```
为空，但Agent已存在）。无论哪种情况，均通过
```
scripts/classify-agent-existence.mjs ${SCRATCH_DIR}/bot-existing.json "<botDefinitionId-or-empty>" "<developerName>"
```
进行分类。分支：
```
exists:false
```
⇒ 阶段2c（操作可用性检查，然后创建）；
```
exists:true
```
+
```
needsActivation:false
```
⇒ 已创建（直接跳至阶段7——无需操作可用性检查；可用的活跃Agent的操作已配置完成）；
```
exists:true
```
+
```
needsActivation:true
```
⇒ 阶段2b。非零退出码 ⇒ 显示CLI错误；切勿假设结果不存在。回退方案的原因：履行者Agent从未预配置，因此
```
botDefinitionId
```
始终为空——若缺少开发者名称检查，会导致重复创建并触发
```
DUPLICATE_VALUE
```
错误。
阶段2b — 重新激活选项。调用
```
AskUserQuestion
```
："履行者Agent
<developerName>
已存在，但最新版本处于非活跃状态。是否激活它？"。若用户回复是：调用
```
POST /connect/bot-versions/<latestVersionId>/activation
```
并传入
```
{"status":"Active"}
```
，将结果保存至
```
${SCRATCH_DIR}/activate-response.json
```
，然后调用
```
node "<skill_dir>/scripts/classify-activate-result.mjs" ${SCRATCH_DIR}/activate-response.json
```
——
```
PASS
```
⇒ 阶段7（判定为已激活）；
```
FAIL
```
⇒ 直接显示
```
messages[]
```
内容，若消息中提到缺少可调用操作则提供阶段2c的权限集移交选项，请勿报告已激活；
```
CANNOT-CONFIRM
```
⇒ 直接进入阶段7的SOQL验证。若用户回复否：终止操作，不执行写入。

阶段2c — 操作可用性预检（仅创建流程；仅当阶段2判定
exists:false
时进入）。将

sf api request rest "/services/data/v67.0/actions/custom/generatePromptResponse" --method GET

的结果保存至

${SCRATCH_DIR}/generate-prompt-response.json

，然后调用

node "<skill_dir>/scripts/classify-action-availability.mjs" ${SCRATCH_DIR}/agent-templates.json "IT Service Fulfiller" ${SCRATCH_DIR}/generate-prompt-response.json

。根据

verdict

分支：

READY

⇒ 阶段3；

NOT-READY

⇒ 调用

AskUserQuestion

提供移交至

service-itsm-agentic-setup-itsm-agentforce-permset-assign

的选项（直接显示

missing[]

内容——请勿继续执行写入操作；激活调用会返回HTTP 200但包含

{success:false}

的静默失败响应体）；

CANNOT-CONFIRM

⇒ 显示原因并谨慎继续（阶段6的激活结果分类器会捕获静默失败响应体）。完整约定位于

references/action-availability.md

。

阶段3 — 确认写入权限（必填，仅创建流程）。若提供了
```
${outputDir}
```
，首先通过
```
render-report.mjs
```
渲染检查点文件，
```
verdict:"PENDING CONFIRMATION"
```
（交互式运行可跳过）。然后调用
```
AskUserQuestion
```
，显示开发者名称+标签+“基于履行者模板Agent Script的NGA原生Agent”。仅在用户明确回复“yes”时继续；若回复“no”，则重新渲染报告，
```
verdict:"DECLINED"
```
。

阶段4 — 创建。调用

scripts/build-create-body.mjs ${SCRATCH_DIR}/agent-templates.json "IT Service Fulfiller" "<developerName>" "<label>" ${SCRATCH_DIR}/create-bundle-body.json

（辅助脚本会重新读取阶段1的模板JSON，HTML解码匹配的

agentScript

，替换内部的

config.developer_name

config.agent_label

，将请求体写入文件），然后调用

POST /nextgen-authoring/bundles --body @${SCRATCH_DIR}/create-bundle-body.json

。保存响应中的
id
——该值为阶段5-6使用的

bundleVersionId

，而非

bundleId

。若返回

403 FUNCTIONALITY_NOT_ENABLED

⇒ 触发阶段1的移交流程；构建脚本退出码为3 ⇒ 显示标准错误输出。

阶段5 — 发布。调用
```
POST /nextgen-authoring/bundle-versions/<bundleVersionId>/publish --body '{}'
```
（必须传入空请求体）。成功时返回：
```
{ lastPublishedOn, publishedBotId, publishedBotVersionId }
```
——此调用会创建底层的
```
BotDefinition
```
/
```
BotVersion
```
。任何错误 ⇒ 直接显示错误内容；切勿激活未发布的版本。
阶段6 — 激活。调用
```
POST /nextgen-authoring/bundle-versions/<bundleVersionId>/activate --body '{}'
```
并将结果保存至
```
${SCRATCH_DIR}/activate-response.json
```
，然后调用
```
node "<skill_dir>/scripts/classify-activate-result.mjs" ${SCRATCH_DIR}/activate-response.json
```
——当引用的可调用操作未显示时，激活调用可能返回HTTP 200但包含
```
{success:false}
```
的静默失败响应体；分类器会捕获此情况。
```
PASS
```
⇒ 阶段7；
```
FAIL
```
⇒ 显示
```
messages[]
```
内容，若消息中提到缺少操作则提供阶段2c的权限集移交选项，请勿报告已创建；
```
CANNOT-CONFIRM
```
⇒ 直接进入阶段7的SOQL验证。
阶段7 — 验证。对
```
BotDefinition WHERE Id='<id>'
```
执行SOQL查询（包含
```
BotVersions
```
子查询）并分类——
```
<id>
```
为创建流程中的
```
publishedBotId
```
（从阶段5获取），或已创建/重新激活流程中第二阶段分类器返回的匹配Id（其
```
botDefinitionId
```
/
```
agentId
```
输出——匹配记录的实际
```
BotDefinition.Id
```
），不可使用阶段1的模板
```
botDefinitionId
```
（履行者Agent的该值始终为空，因此若Agent已存在，验证查询会执行
```
WHERE Id=''
```
并错误报告激活/跳过成功后的失败）。需确认
```
exists:true, count:1, latestVersionStatus:"Active"
```
。任何不一致 ⇒ 直接报告，请勿伪造成功。
阶段8 — 汇总判定结果。通过重新调用
```
render-report.mjs
```
输出CREATED / ALREADY-CREATED / ACTIVATED / FAILED（阶段2b流程判定为ACTIVATED）+
```
BotDefinition
```
Id / 包
```
id
```
——统一的报告文本来源。若提供了
```
${outputDir}
```
，则覆盖
```
${outputDir}/report.md
```
；否则在标准输出中显示对话回合报告。

Rules / Constraints

规则/约束

Constraint	Rationale
All calls go through `sf api request rest` / `sf data query` ; never extract the access token	Leaks a bearer token into shell context; the CLI's stored session is the correct surface
Idempotency read keys PRIMARILY on the template's `botDefinitionId` (Phase-1 row), falling back to the collected `<developerName>` when null; the verify read keys on the publish `publishedBotId` / `botDefinitionId` ; that same `<developerName>` / `<label>` also thread through the create body (outer `apiName` / `label` AND the substituted `config.developer_name` / `config.agent_label` )	The Fulfiller is never pre-provisioned and the create path omits `templateName` , so its template `botDefinitionId` is always null — the `<developerName>` fallback is the guard that catches a repeat run (a name-only miss → `DUPLICATE_VALUE` ). A create-body hardcode/collect mismatch diverges the bundle's outer identity from the script's internal identity
Preflight, idempotency, bundle-body construction, and report rendering all live in `scripts/*.mjs` , not prose (A9)	JSON parsing + `masterLabel` matching + `hasAccess` reads + verdict emission are deterministic; the ~70KB Agent Script and free-text apostrophes cannot be safely interpolated into a shell string — `JSON.stringify` in the helper escapes them
Three-call sequence: `createBundleWithVersion` → `publish` → `activate` , in that order, on the SAME captured `bundleVersionId` (response `id` , not `bundleId` )	Platform enforces DRAFT → published → active; response-body / empty-body / `--json` / `agentType` / HTML-decode gotchas live in `references/error-taxonomy.md`
Enumerate `BotDefinition` with the `BotVersions` subquery; skip create when Active; offer Phase-2b reactivation when Inactive — never silent skip, never duplicate create	Subquery is what distinguishes Active/Inactive; the server rejects a duplicate `DeveloperName` at publish (unique-constraint → bundle cleanup), so this read is what turns a repeat into a graceful skip instead of that hard error
REQUIRED confirm-to-write checkpoint before create sequence or reactivation call	Both change live org state — explicit user approval required
On `hasAccess=false` / `403 FUNCTIONALITY_NOT_ENABLED` , offer the readiness hand-off — never enable features here; never call legacy `/connect/service-itsm/createAgent`	Enablement is a Setup-UI/admin action; `createAgent` produces a Setup-page bot with an external-link icon (wrong kind of agent for this skill)
Report exact CLI response text on any error	Enables support to diagnose failures

约束	理由
所有调用均通过 `sf api request rest` / `sf data query` 完成；切勿提取访问令牌	避免将Bearer令牌泄露至shell上下文；CLI存储的会话是正确的操作入口
幂等性查询主要基于模板的 `botDefinitionId` （阶段1行），为空时回退至收集到的 `<developerName>` ；验证查询基于发布的 `publishedBotId` / `botDefinitionId` ；相同的 `<developerName>` / `<label>` 需贯穿创建请求体（外层 `apiName` / `label` 以及替换后的 `config.developer_name` / `config.agent_label` ）	履行者Agent从未预配置，且创建流程未包含 `templateName` ，因此其模板 `botDefinitionId` 始终为空—— `<developerName>` 回退方案是防止重复运行的关键（仅检查名称会遗漏重复创建→ `DUPLICATE_VALUE` 错误）。创建请求体中硬编码与收集值不匹配会导致包的外层标识与脚本内部标识不一致
预检、幂等性检查、包请求体构建及报告渲染均通过 `scripts/*.mjs` 实现，而非硬编码文本（A9）	JSON解析+ `masterLabel` 匹配+ `hasAccess` 读取+判定结果输出均为确定性操作；约70KB的Agent Script和自由文本引号无法安全插入shell字符串——辅助脚本中的 `JSON.stringify` 会对其进行转义
必须按顺序执行三次调用： `createBundleWithVersion` → `publish` → `activate` ，且使用相同的 `bundleVersionId` （响应中的 `id` ，而非 `bundleId` ）	平台强制要求流程为草稿→已发布→已激活；响应体/空请求体/ `--json` / `agentType` /HTML解码等常见问题位于 `references/error-taxonomy.md`
枚举 `BotDefinition` 时必须包含 `BotVersions` 子查询；若Agent已活跃则跳过创建；若Agent非活跃则提供阶段2b的重新激活选项——切勿静默跳过或重复创建	子查询是区分活跃/非活跃状态的关键；服务器会在发布阶段拒绝重复的 `DeveloperName` （唯一约束→包清理），因此该查询可将重复运行转化为优雅跳过，而非硬错误
创建序列或重新激活调用前必须执行确认写入权限检查	两者都会修改组织的实时状态——需用户明确批准
若 `hasAccess=false` / `403 FUNCTIONALITY_NOT_ENABLED` ，则提供就绪检查移交选项——切勿在此启用功能；切勿调用旧版 `/connect/service-itsm/createAgent`	功能启用是Setup UI/管理员操作； `createAgent` 会创建带外部链接图标的Setup页面Bot（不符合本技能的Agent类型）
任何错误均需报告精确的CLI响应文本	便于支持人员诊断故障

Verification Checklist

验证清单

Preflight classified by
```
classify-preflight.mjs
```
(PASS or documented CANNOT-CONFIRM); hand-off offered on FAIL; raw error surfaced on ERROR.
Idempotency keyed on the template's
```
botDefinitionId
```
(Phase-1 row) with the collected developerName as fallback;
```
BotDefinition WHERE Id='<botDefinitionId>' OR DeveloperName='<developerName>'
```
(the
```
OR
```
covers both a null and a dangling
```
botDefinitionId
```
) + latest
```
BotVersion.Status
```
(subquery present) read + classified before any write.
If
```
needsActivation:true
```
, Phase-2b reactivation offer presented — no silent skip, no duplicate create.
Explicit user confirmation at Phase 3 (create) or Phase 2b (reactivation) before any write.
Bundle body built by
```
build-create-body.mjs
```
, POSTed via
```
--body @<file>
```
with the collected
```
developerName
```
/
```
label
```
; or write correctly skipped.
Same
```
bundleVersionId
```
(response
```
id
```
) used for publish + activate; reactivation used
```
POST /connect/bot-versions/<id>/activation
```
; legacy
```
createAgent
```
never called.
Phase-7 verify confirmed
```
BotDefinition
```
present + latest version Active.
Access token never extracted; final verdict +
```
BotDefinition
```
/bundle Id reported.

预检已通过
```
classify-preflight.mjs
```
分类（通过或记录为CANNOT-CONFIRM）；失败时提供移交选项；错误时显示原始错误。
幂等性检查基于模板的
```
botDefinitionId
```
（阶段1行），回退至收集到的开发者名称；执行
```
BotDefinition WHERE Id='<botDefinitionId>' OR DeveloperName='<developerName>'
```
查询（
```
OR
```
覆盖
```
botDefinitionId
```
为空或无效的情况）+ 最新
```
BotVersion.Status
```
（包含子查询）并分类后再执行任何写入操作。
若
```
needsActivation:true
```
，则显示阶段2b的重新激活选项——不静默跳过，不重复创建。
阶段3（创建）或阶段2b（重新激活）执行写入前已获得用户明确确认。
包请求体由
```
build-create-body.mjs
```
生成，通过
```
--body @<file>
```
传入收集到的
```
developerName
```
/
```
label
```
；或已正确跳过写入操作。
发布+激活使用相同的
```
bundleVersionId
```
（响应中的
```
id
```
）；重新激活使用
```
POST /connect/bot-versions/<id>/activation
```
；未调用旧版
```
createAgent
```
。
阶段7验证已确认
```
BotDefinition
```
存在且最新版本为Active。
未提取访问令牌；已报告最终判定结果+
```
BotDefinition
```
/包Id。

Output Format

输出格式

The report layout is generated deterministically by

scripts/render-report.mjs

— the single source of report text for both the chat turn and the harness's

${outputDir}/report.md

. Never hand-compose the layout in prose (A9); always shell out to the helper. Full rendered shape, report-state JSON schema, and checkpoint-write rules live in

references/report-format.md

Terminal verdicts:

CREATED | ALREADY-CREATED | ACTIVATED | PENDING CONFIRMATION | DECLINED | FAILED

. When

${outputDir}

is set, write at Phase 3, Phase 6 (or Phase 2b), and Phase 8 — each write overwrites the same file. Skip these writes in interactive/chat surfaces.

报告布局由

scripts/render-report.mjs

确定性生成——为对话回合和测试工具的

${outputDir}/report.md

提供统一的报告文本来源。切勿手动编写报告布局（A9）；始终调用辅助脚本。完整渲染格式、报告状态JSON schema及检查点写入规则位于

references/report-format.md

。

终端判定结果：

CREATED | ALREADY-CREATED | ACTIVATED | PENDING CONFIRMATION | DECLINED | FAILED

。当设置

${outputDir}

时，需在阶段3、阶段6（或阶段2b）、阶段8写入报告——每次写入覆盖同一文件。交互式/对话场景可跳过这些写入操作。

Reference File Index

参考文件索引

File	When to read
`references/workflow-detail.md`	Full per-phase verdict-branch narrative that the SKILL body summarizes (Phase-1 ERROR/NOT-READY/CANNOT-CONFIRM, Phase-2 classifier output, Phase-4 create response, error branches)
`references/report-format.md`	Every `render-report.mjs` call — the rendered shape and the three-checkpoint write policy for `${outputDir}/report.md`
`references/cli-invocation.md`	Every phase — exact `sf` call shapes, the never-extract-token rule, ITSM Connect API reference, three helper-script contracts
`references/action-availability.md`	Phase 2c (action-availability preflight, create path) + Phase 2b/6 (activate-result classifier) — silent-failure body catches, permset hand-off wording
`references/reactivation.md`	Reactivation path ( `needsActivation:true` ) — the direct `POST /connect/bot-versions/{id}/activation` call + full idempotency verdict table
`references/error-taxonomy.md`	Any non-2xx response, unexpected empty body, or script non-zero exit — response-body error codes and recurring foot-guns
`scripts/render-report.mjs`	Every checkpoint that writes `${outputDir}/report.md` (Phase-3 gate, Phase-6 create-succeeded, Phase-8 final) — deterministic renderer from a phase-state JSON

文件	阅读时机
`references/workflow-detail.md`	所有阶段——完整的各阶段判定分支说明，为本技能正文的摘要（阶段1 ERROR/NOT-READY/CANNOT-CONFIRM、阶段2分类器输出、阶段4创建响应、错误分支）
`references/report-format.md`	每次调用 `render-report.mjs` 时——渲染格式及 `${outputDir}/report.md` 的三检查点写入策略
`references/cli-invocation.md`	所有阶段——精确的 `sf` 调用格式、禁止提取令牌规则、ITSM Connect API参考、三个辅助脚本约定
`references/action-availability.md`	阶段2c（操作可用性预检，创建流程）+ 阶段2b/6（激活结果分类器）——静默失败响应体捕获、权限集移交措辞
`references/reactivation.md`	重新激活流程（ `needsActivation:true` ）——直接调用 `POST /connect/bot-versions/{id}/activation` 的格式+完整幂等性判定表
`references/error-taxonomy.md`	任何非2xx响应、意外空响应体或脚本非零退出时——响应体错误码及常见陷阱
`scripts/render-report.mjs`	每次写入 `${outputDir}/report.md` 的检查点（阶段3确认门、阶段6创建成功、阶段8最终结果）——基于阶段状态JSON的确定性渲染器