SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场dx-org-analyze

dx-org-analyze

部署与运维

查看项目

更新于 10-15 10:12

技能介绍

用途

dx-org-analyze 用于两类任务：一是将两个 Salesforce org 并排对比，生成包含漂移分数（drift score）的对比报告；二是对单个 org 进行盘点分析（introspect），生成覆盖元数据、org 设置、org 限制、已安装包、许可证、系统权限和深层数据记录的清单报告。该技能为只读，仅做对比与分析，绝不部署或修改任一 org。

主要能力

对比模式会生成漂移分数——加权总分（60% 元数据、30% 权限、10% 配置文件），并给出严重级别（LOW/MODERATE/HIGH/CRITICAL）。报告结构包括：

  • 汇总统计：按元数据类型统计数量，含来自深层数据的 Identical/Different 列
  • 按类型划分的元数据组件：仅源端、仅目标端、共享
  • 配置文件（Profiles）：共享、仅源端、仅目标端
  • 已安装包：版本对比、仅源端、仅目标端
  • 包组件：按命名空间分组的带命名空间组件
  • Org 权限：按类别列出布尔启用/禁用差异及值差异
  • 系统权限：PermissionSet 上的 PermissionsXxx 字段，按权限集列出差异
  • Org 值与限制：按 Identity、Storage、API、Feature Limits 分组
  • 许可证：用户、权限集、包许可证数量差异
  • 深层数据：Apex、Flow、验证规则、自定义字段等的内容级差异

单 org 盘点模式覆盖：元数据清单、org 设置、org 限制、已安装包、许可证、系统权限和深层数据记录。

使用方式

该技能仅使用 Bash 工具执行所有 sf CLI 命令和 Python 脚本，sf 命令必须带 --json，不使用 mcp__salesforce_dx__* 工具。数据访问优先级为：优先 SF CLI 命令（如 sf org list metadata-types、sf org list metadata、sf org display、sf data query、sf limits api display 等），仅在 SF CLI 无法提供数据时才使用直接 REST/Tooling API 调用。

认证规则：所有认证必须通过 SF CLI（sf org login web、sf org login jwt、sf org login access-token），绝不接受用户直接提供的原始凭据、会话 ID 或访问令牌。采集脚本仅通过 sf org display --json 获取访问令牌。

对比工作流：

  1. 列出已认证 org：运行 sf org list --json --skip-connection-status，从所有桶（devHubs、nonScratchOrgs、scratchOrgs、sandboxes、other）收集 org，以表格展示（别名、用户名、实例 URL、Org ID、类型）。若已认证 org 少于 2 个但至少有 1 个，提供单 org 盘点模式；若无已认证 org，则停止并提示运行 sf org login web --alias <name>。
  2. 用户选择两个 org：两者都必须显式命名，不允许隐式/默认 org。需指定哪个是源（参考/期望状态）、哪个是目标。接受别名、用户名或列表编号，解析为具体用户名。若 org 无别名，提示用户分配。
  3. 验证连通性：对每个 org 运行 sf data query --target-org <alias-or-username> --query "SELECT Id FROM Organization LIMIT 1" --json。若失败并报 INVALID_SESSION_ID 或认证错误，运行 sf org login web --alias <alias>。
  4. 采集数据（每个 org）：生成唯一 run ID，运行采集脚本：
RUN_ID=$(date +%Y%m%d-%H%M%S)
python3 ./scripts/collect_org_data.py \
  --org-alias "$SOURCE_ORG" \
  --output /tmp/dx-org-comparison-${RUN_ID}-source
python3 ./scripts/collect_org_data.py \
  --org-alias "$TARGET_ORG" \
  --output /tmp/dx-org-comparison-${RUN_ID}-target

退出码：0 = 成功，1 = 致命错误（向用户报告 stderr），2 = 会话过期（重新认证后重试）。

  1. 计算差异并生成报告：
python3 ./scripts/compute_diff.py \
  --org-a /tmp/dx-org-comparison-${RUN_ID}-source \
  --org-b /tmp/dx-org-comparison-${RUN_ID}-target \
  --output /tmp/dx-org-comparison-${RUN_ID} \
  --format both \
  --org-a-label "Source" \
  --org-b-label "Target"

若用户希望详细列出共享组件，使用 --show-shared。

  1. 呈现结果：读取 /tmp/dx-org-comparison-${RUN_ID}.md 呈现给用户；后续问题可用 .json 查询。然后解析输出目录并复制两个文件：
OUTPUT_DIR=""
if [ -n "$USER_OUTPUT_PATH" ]; then
  OUTPUT_DIR="$USER_OUTPUT_PATH"
elif [ -d "force-app/main/adk-eval-output" ]; then
  OUTPUT_DIR="force-app/main/adk-eval-output"
fi
if [ -n "$OUTPUT_DIR" ]; then
  cp /tmp/dx-org-comparison-${RUN_ID}.json "$OUTPUT_DIR/dx-org-analyze-result.json"
  cp /tmp/dx-org-comparison-${RUN_ID}.md "$OUTPUT_DIR/dx-org-analyze-result.md"
fi

单 org 盘点工作流：

  1. 验证连通性（同上查询）。
  2. 采集数据：
RUN_ID=$(date +%Y%m%d-%H%M%S)
python3 ./scripts/collect_org_data.py \
  --org-alias "$ORG" \
  --output /tmp/dx-org-analysis-${RUN_ID}
  1. 生成报告：
python3 ./scripts/introspect_org.py \
  --org /tmp/dx-org-analysis-${RUN_ID} \
  --output /tmp/dx-org-analysis-${RUN_ID} \
  --format both \
  --label "OrgName"
  1. 呈现结果：读取 /tmp/dx-org-analysis-${RUN_ID}.md 呈现给用户，然后按同样逻辑解析输出目录并复制文件为 dx-org-analyze-result.json 与 dx-org-analyze-result.md。

适用场景

  • 对比两个 org 的配置差异，评估配置漂移程度
  • 盘点单个 org 的元数据、权限、包、许可证与限制
  • 在部署前后核对源与目标 org 的期望状态
  • 排查 org 间权限、配置文件、已安装包版本差异

限制与约束

  • 始终对 sf 命令使用 --json，以获得可靠解析的结构化输出
  • 将 org 解析为用户名而非别名（别名可能歧义，用户名唯一）
  • 跳过已过期和已断开的 org
  • 只读——绝不部署或修改，仅对比，绝不改变任一 org
  • 仅通过 SF CLI 认证，所有认证走 SF CLI 凭据存储
  • 两个 org 必须显式指定，绝不对比未命名或隐式/默认 org
  • 采集脚本退出码 2 表示会话过期，需重新认证后重试
  • 元数据列表时若遇 API 限制错误，可用 --skip-deep-data 进行更快、细节更少的扫描
  • 版本差异（DE vs EE）中许多差异是版本固有的，而非配置漂移
  • 大型 org 的深层数据可能超时，可用 --skip-deep-data 标志，再针对后续问题运行完整深层数据

故障排查

  • "No org found for <alias>"：org 未认证，运行 sf org login web --alias <name>
  • 已认证 org 少于 2 个：对比前先认证更多 org
  • "INVALID_SESSION_ID" 或认证错误：会话过期，重新运行 sf org login web --alias <name>
  • 采集脚本退出码 2：会话过期，重新认证并重试

跨技能集成

  • 从 org 检索特定元数据：platform-metadata-retrieve
  • 将元数据部署到 org：platform-metadata-deploy
  • 创建用于对比的 scratch org：dx-org-manage
  • 对比后切换默认 org：dx-org-switch

参考文件索引

  • references/collection-details.md：采集脚本收集内容与方式的细节
  • references/report-format.md：漂移分数公式与报告章节细节
  • scripts/collect_org_data.py：数据采集脚本（每个 org）
  • scripts/compute_diff.py：差异计算与报告生成脚本
  • scripts/introspect_org.py：单 org 盘点报告脚本