investigating-agentforce-d360

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

根据 Data Cloud STDM + GenAI DMO，分层重建单个 Agentforce 会话。分为三个阶段：抓取 → 组装 → 渲染。典型耗时：约 15 轮会话需 10–30 秒。

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

如果用户未提供足够信息，无法继续

在没有会话 ID 且没有发现条件时调用此工具，应逐字打印此代码块——不要改述，也不要预先运行任何脚本。触发条件：输入为空，或不包含会话 ID 格式（既不是 UUID，也不是 0Mw… messaging ID），且不包含发现表达式（没有时间短语 / --agent / --channel / --outcome / --grep / “find” / “list” 之类的动词）。

我应该从哪个 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/investigating-agentforce-d360/<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/investigating-agentforce-d360/<org_id15>/<agent>__<ver>/<session_id>/（默认路径；可通过 --data-dir <path> 按脚本覆盖）——messaging ID 仅用作查询键，绝不会用作目录名。占主导地位的 Agent（sorted(agents_observed) 中的第一个）决定 <agent>__<ver>/ 路径段的名称。

解析脚本前缀

默认安装会将此技能放在运行时的插件根目录下。如果此技能克隆到了其他位置（例如，直接从 forcedotcom/sf-skills 仓库克隆到自定义路径），请将 PLUGIN_ROOT 设置为指向运行时的技能目录。

prefix="${SKILL_ROOT:-${PLUGIN_ROOT:-$HOME/.vibe/skills}/investigating-agentforce-d360}/scripts"

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

会话发现（尚无 ID）

用户没有会话 ID 时，针对 STDM 会话 DMO 运行 discover_sessions.py。该脚本会输出带编号的选择列表；用户选定一项后，使用相应 UUID 继续。

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

筛选条件（除 --org 外均为可选）：--since <expr>（默认最近 24 小时；接受“最近 2 小时”“今天”、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>

标志：使用 --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}/investigating-agentforce-d360/ 根目录；如果宿主运行环境需要将产物放在不同的分发目录结构下，请传入这两个参数。

输出产物

所有内容都写入 ~/.vibe/data/investigating-agentforce-d360/<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 擅长的方面

• 运行了什么——按顺序记录每个步骤、每次大模型调用、每个网关请求及响应，并附有时间戳和持续时间。适合回答“带我了解整个会话”。
• 用户看到了什么——完整的消息记录（用户 + Agent），按顺序排列。
• 大模型生成了什么——生成内容、令牌数量、信任度评分（来自 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>
目标组织已启用 Data Cloud	是——必须已为该会话生成 STDM + GenAI DMO
Python 3.10+	是——流水线脚本

常见提示词——对应操作

用户说	技能执行的操作
“跟踪 my-org 中的会话 <uuid>”	fetch_dc.py --session <uuid> --org my-org → 组装 → 渲染
“总结 0Mw… 中发生了什么”	将 0Mw… 解析为 UUID，然后运行完整的 DC 流水线
“查找 my-org 中今天通过 Messaging 升级的会话”	运行 discover_sessions.py --since today --outcome ESCALATED --channel Messaging，打印选择列表，由用户选择，然后运行 DC 流水线
“带我了解这个会话”	与跟踪操作相同——从上到下阅读渲染后的摘要

用户最终看到的内容

管道完成后，渲染出的 dc._session_summary.md 包含以下顶层章节：

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

如需深入分析，请打开 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。请等待一两分钟后重新运行。