agentforce-d360-analyze

agentforce-d360-analyze — Data Cloud 360° 会话视图

从 Data Cloud STDM + GenAI DMO 重建单个 Agentforce 会话的层级结构。分为三个阶段——获取 → 组装 → 渲染。典型墙钟时间：约 15 轮会话需要约 10–30 秒。

该流水线仅使用 DC：它读取 Data Cloud 已物化的运行时审计行。它不是运行时可用性工具——有关此技能无法回答的问题，请参阅下文“仅使用 DC 的盲区”。

如果用户提供的信息不足以继续

调用时如果既没有会话 ID，也没有发现条件，请原样输出此代码块——不要改述，也不要预先运行任何脚本。触发条件：输入为空，或既不包含会话 ID 格式（UUID 或 0Mw… Messaging ID），也不包含发现表达式（没有时间短语 / --agent / --channel / --outcome / --grep / “查找”/“列出”等动词）。

我应该从哪个 org 的 Data Cloud 中提取哪个会话？

我需要：

• 会话 ID — Agent Session UUID（019db7f6-…）或 MessagingSession ID（0Mw…，15/18 个字符）。
  • 没有会话 ID？ — 告诉我你还记得什么，我来查找：时间有多近（例如“最近 2 小时”“今天”、某个日期）、哪个 Agent、哪个渠道（Messaging / Builder / Voice）、会话如何结束（已升级、用户结束、已转接、超时），或对话中的某个短语。我会以编号列表显示匹配的会话——你选一个，我来提取。
• Org 别名 — 用于 sf CLI 身份验证的别名（你通过 sf org login 配置的别名）。

生成的文件位于 ~/.vibe/data/agentforce-d360-analyze/<org_id15>/<agent>__<ver>/<session_id>/（可通过每个脚本的 --data-dir <path> 覆盖）。

会话 ID 格式——UUID 或 MessagingSession ID

--session 接受这两种格式：

格式	示例	解析方式
Agent Session UUID	019dface-0000-7000-8000-000000000002	直接传递
MessagingSession ID（0Mw 前缀）	0MwTESTMSG12345AAA	通过 resolve_session.py 解析——首次获取时实时查询 DC，之后优先从磁盘读取

多匹配情况确实存在。 一个 MessagingSession ID 可能对应多个 Agent Session UUID。出现多匹配时，解析器会打印所有候选项并以非零状态退出；用户需要使用特定 UUID 重新调用。

生成的文件始终位于 ~/.vibe/data/agentforce-d360-analyze/<org_id15>/<agent>__<ver>/<session_id>/（默认路径；可通过每个脚本的 --data-dir <path> 覆盖）——Messaging ID 仅用作查找键，不会用作目录名。占主导地位的 Agent（sorted(agents_observed) 中的第一个）用于命名 <agent>__<ver>/ 路径段。

解析脚本前缀

<SKILL_DIR> = 此技能自身目录的绝对路径（即包含此文件的文件夹 SKILL.md）；请根据上下文中的技能路径解析，并在下方替换。运行环境 安装技能的位置各不相同（~/.claude/skills/、~/.vibe/skills/、插件缓存、 项目的 .claude/skills/），因此此代码块也会在运行时探测已知的安装根目录，并 使用第一个实际包含此技能脚本的目录。若已导出 SKILL_ROOT，则优先使用它。

_skill=agentforce-d360-analyze
for _c in "${SKILL_ROOT:-}" "<SKILL_DIR>" \
          "${CLAUDE_PLUGIN_ROOT:+$CLAUDE_PLUGIN_ROOT/skills/$_skill}" \
          "${VIBES_SKILLS_DIR:+$VIBES_SKILLS_DIR/$_skill}" \
          "$HOME/.claude/skills/$_skill" "$PWD/.claude/skills/$_skill" \
          "${PLUGIN_ROOT:-$HOME/.vibe/skills}/$_skill"; do
  [ -n "$_c" ] || continue
  # Some stagers (ADK eval) nest the bundled files under <skill>/artifacts/.
  for _r in "$_c" "$_c/artifacts"; do
    [ -f "$_r/scripts/fetch_dc.py" ] && { SKILL_ROOT="$_r"; break 2; }
  done
done
[ -f "${SKILL_ROOT:-}/scripts/fetch_dc.py" ] || { echo "$_skill: scripts not found — set SKILL_ROOT to this skill's directory" >&2; exit 1; }
prefix="$SKILL_ROOT/scripts"

本文档后续所有调用均使用 "$prefix/..."。

会话发现（尚无 ID）

当用户没有会话 ID 时，针对 STDM 会话 DMO 运行 discover_sessions.py。脚本会打印一个带编号的选择列表；用户选择一项后，使用所选 UUID 继续。

python3 "$prefix/discover_sessions.py" [--org <alias>] [filters...]

--org 为可选项。“我的组织”“我们的组织”或完全没有指定别名，都表示使用 sf CLI 的默认目标组织——省略 --org，脚本会使用 sf config get target-org。只有当用户指定别名时，才传入 --org <alias>。如果未设置默认值，脚本会以“no --org given and no default target org set”退出；转告用户脚本给出的 sf config set target-org <alias> 提示，并请用户提供别名。

筛选条件（均为可选）：--since <expr>（默认为过去 24 小时；接受“last 2 hours”、“today”和 ISO 日期）、--agent <api-name>、--channel <Messaging|Builder|Voice>、--outcome <USER_ENDED|ESCALATED|TRANSFERRED|TIMEOUT|NOT_SET>、--grep <substring>（对话文本）、--tz <IANA>、--limit <N>（默认为 20）。

输出：包含 #、UUID、Start (UTC)、Agent、Channel、Duration、Outcome 的 Markdown 表格。用户回复一个编号后，使用对应的 UUID 继续。

管道 — 三个阶段

fetch_dc.py     →  24 dc.<name>.json + dc._session_manifest.json     (DC Query REST waterfall, 5 waves)
assemble_dc.py  →  dc._session_tree.json                             (pure in-memory hierarchical join)
render_dc.py    →  dc._session_summary.md                            (human summary, multi-section)

每个阶段都可独立运行。fetch_dc.py --session <sid> [--org <alias>] 默认会依次运行全部三个阶段。

调用方式

python3 "$prefix/fetch_dc.py" --session <session-id-or-messaging-id> [--org <alias>]

这里的 --org 也是可选项：不传入该选项（用户说“我的组织”或未指定别名）时，将使用 CLI 的默认目标组织。如果未设置默认值，fetch_dc.py 会以原因 no_org 报告 DC_ACCESS_DENIED（在无头模式下退出码为 10）——请用户提供别名，并使用 --org <alias> 重新运行。

标志：使用 --verbose 查看每个 DMO 的行数；使用 --no-assemble / --no-render 提前停止。所有入口脚本（fetch_dc.py、assemble_dc.py、render_dc.py、resolve_session.py、discover_sessions.py）都支持 --data-dir <path> 和 --cache-dir <path>，用于覆盖默认的 ~/.vibe/{data,cache}/agentforce-d360-analyze/ 根目录——如果宿主运行时需要将制品存放在不同的分发目录布局下，请传入这些选项。

输出制品

所有内容都写入 ~/.vibe/data/agentforce-d360-analyze/<org_id15>/<agent>__<ver>/<session_id>/（默认为此路径；可使用 --data-dir <path> 覆盖）：

dc.sessions.json              dc.steps.json                dc.gateway_requests.json
dc.interactions.json          dc.messages.json             dc.gateway_responses.json
dc.participants.json          dc.generations.json          dc.gateway_request_llm.json
dc.content_quality.json       dc.content_category.json     dc.gateway_request_metadata.json
dc.tags.json                  dc.tag_definitions.json      dc.gateway_request_tags.json
dc.tag_associations.json      dc.tag_definition_associations.json
dc.feedback.json              dc.feedback_details.json     dc.gateway_records.json
dc.moments.json               dc.moment_interactions.json
dc.telemetry_spans.json       dc.app_generation.json

dc._session_manifest.json     (per-DMO row counts + empties)
dc._session_tree.json         (hierarchical join — session → interactions → steps → messages → generations → gateway)
dc._session_summary.md        (rendered human summary)

零行查询会在清单中记录为 status: empty；不会写入文件。assemble_dc 可以处理文件缺失的情况。完整读取顺序请参阅 references/artifacts.md。

仅凭 DC 分析的盲点——确定根本原因前请先阅读

仅凭 DC 可以回答发生了什么——运行过哪些步骤、触发了哪些生成、记录了哪些网关请求。但它无法回答本来可能发生但没有发生什么：

• 在某一轮中，分类器有哪些可用主题（这些信息位于运行时规划器遥测中，而不在 DC 中）。
• 某个主题上声明了哪些操作，以及其中哪些通过了规则表达式筛选并实际提供给了大模型。
• 大模型为何选择某个主题或操作，而不是其他选项（完整的提示词和响应文本只存在于规划器运行时遥测中）。

如果用户的问题是为什么使用或没有使用某个特定主题或操作，仅凭 DC 几乎总是不够的。告知用户：“可用性问题需要该轮的运行时规划器跟踪信息——这不在此技能的 Data Cloud 范围内。请查看反映规划器已记录决策的平台遥测。”不要依据仅有的运行时证据臆造根本原因。

DC 擅长做什么

• 运行了什么 — 按顺序记录每个步骤、每次 LLM 调用、每次网关请求及响应，并附带时间戳和耗时。适合回答“带我逐步回顾这次会话”。
• 用户看到了什么 — 完整的消息记录（用户 + Agent），按顺序排列。
• LLM 生成了什么 — 生成内容、Token 数量、信任评分（毒性、指令遵循度，以及来自 content_quality + content_category 的内容类别细分）。
• 工具调用 — 操作调用、输入、输出和错误（来自 gateway_request_metadata + gateway_records）。
• 反馈 + 标记 — 用户反馈、升级标记、会话结束类型。
• 审计完整性 — 检查 GatewayRequest 和 GatewayResponse 之间的 1:1 不变量；如有偏差，会在 counts.audit_chain_1to1_ok 中标记。

先决条件

工具	必需
sf CLI（已通过身份验证并连接到目标组织）	是 — sf org login web --alias <alias>，且 CLI 必须提供 sf org auth show-access-token（启动前检查会强制执行此要求）
目标组织已启用 Data Cloud	是 — 会话对应的 STDM + GenAI DMO 必须已完成物化
Python 3.10+	是 — 用于流水线脚本

典型提示词 — 对应的操作

用户说	技能执行
"Trace session <uuid> in my-org"	fetch_dc.py --session <uuid> --org my-org → 组装 → 渲染
"Summarize what happened in 0Mw…"	将 0Mw… 解析为 UUID，然后运行完整的 DC 流水线
"Find escalated sessions today in my-org on Messaging"	运行 discover_sessions.py --since today --outcome ESCALATED --channel Messaging，显示选择器，用户选定后运行 DC 流水线
"Walk me through this session"	与追踪会话相同 — 从上到下阅读渲染后的摘要

返回给用户的内容

流水线完成后，渲染后的 dc._session_summary.md 包含以下顶层章节：

1. 会话身份 — UUID、开始/结束时间、时长、Agent、渠道、结束类型、参与者数量
2. 会话初始化 — 渠道模式 + 初始化变量（identity.mode、identity.bootstrap_variables）
3. ID 参考 — 层级追踪中所有被截断 ID 的完整 UUID
4. 对话记录 — 每次 TURN 交互中 USER ↔ AGENT 的叙述
5. 完整层级追踪 — Interaction → Step → Generation → GatewayRequest，并提供 +start + duration = +end 计算
6. 每轮摘要 — 每次交互一行
7. Planner LLM 调用（完整提示词 + 响应） — 通过 --show-prompts 选择启用；默认不显示
8. 可视化分析 — 甘特图 + LLM 调用叠加图
9. 会话计数 — 面向工程师的清单计数表
10. 空数据诊断 — 每个 rows == 0 且已填写 _unavailable_reason 的 DMO 各占一行
11. 目录（按会话筛选） — TagDefinitions / TagDefinitionAssociations / Tags，仅包含会话中观察到的 Agent

如需深入分析，请打开 dc._session_tree.json — 它是渲染摘要所依据的唯一事实来源。完整的流水线契约请参阅 references/dc_pipeline_contract.md；各 DMO 的字段参考请参阅 references/dc_dmo_fields.md。

注意事项

• gateway_requests_dropped_by_stdm — 当 DC 报告 gateway_requests 行数为零，但运行时遥测显示确实发起了 LLM 调用时，此技能无法明确区分“STDM 导出器丢弃了写入”与“源头确实禁用了日志记录”。会话将报告为 planner_ran_no_gateway_logs；操作人员可检查平台遥测以进一步判断。请参阅 references/dc_pipeline_contract.md §2.8。
• 延迟 — Generation 和 GatewayRequest 只带有单次写入的时间戳，而非开始/结束时间对。渲染器不会计算它们之间的“延迟” — 该时间差反映的是 DC 的序列化顺序，而非 LLM 调用耗时。
• Data Cloud 物化延迟 — 对于较新的会话，如果 STDM 尚未同步完成，可能会显示 interactions_not_materialized_yet。请在一两分钟后重新运行。