crm-archaeology

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CRM Archaeology — study a live Dynamics 365 org, end to end

CRM考古法——全面研究实时Dynamics 365组织

A live CRM org is unreadable in the browser, but almost everything in it can be pulled to disk as plain text. So the method is three stages:

EXTRACT (steps 1–7: org → files + fragments)  →  STUDY (steps 8–9: connect the
layers into business processes)  →  DOCUMENT (step 10: one ARCHITECTURE.md)

Every command and query this skill relies on is in this skill's

references/extraction-queries.md

(verified against Microsoft Learn, June 2026). Read the relevant section of that file when you reach each step — do not improvise queries from memory; Dataverse metadata endpoints have non-obvious casing, casting, and join-key rules that the reference encodes.

实时CRM组织在浏览器中无法直接读取，但其中几乎所有内容都可以拉取到本地磁盘保存为纯文本。因此该方法分为三个阶段：

提取（步骤1–7：组织 → 文件+片段）→ 研究（步骤8–9：将各层关联为业务流程）→ 文档化（步骤10：生成一份ARCHITECTURE.md）

本技能依赖的所有命令和查询都位于本技能的

references/extraction-queries.md

文件中（已根据Microsoft Learn验证，2026年6月）。执行到每个步骤时，请阅读该文件的对应章节——不要凭记忆即兴编写查询；Dataverse元数据端点有非直观的大小写、类型转换和连接键规则，这些规则已在参考文件中编码。

Hard rules

硬性规则

Read-only. This skill exports, GETs, and reads. It never creates, updates, or deletes anything in the org via the API, a script, or
```
pac
```
. The single sanctioned exception is the step-9 lifecycle walk-through, where a test record may be created through the app UI — by the user, or by you only with their explicit consent, and only in a sandbox. If the study reveals something worth fixing, file it as a finding — do not fix it inline.
Confirm the environment before the first call. Show the user the environment URL and ask them to confirm (
```
pac org who
```
to verify). Prefer a SANDBOX. Never assume the active
```
pac
```
auth profile is the right target.
Fragments, not one giant pass. Each step writes its output into the study workspace as it finishes. The study must be resumable — stopping after step 4 today and continuing tomorrow is a normal way to run it.
No speculation in the output. Document only what the extracted files and queries show. Unclear behavior is recorded as unclear.

只读模式。本技能仅执行导出、GET和读取操作。绝不会通过API、脚本或
```
pac
```
在组织中创建、更新或删除任何内容。唯一被允许的例外是步骤9的生命周期演练，此时可通过应用UI创建测试记录——由用户创建，或经用户明确同意后由你创建，且仅在沙箱环境中进行。如果研究发现需要修复的问题，请将其记录为发现项——不要直接在流程中修复。
首次调用前确认环境。向用户展示环境URL并请求确认（使用
```
pac org who
```
验证）。优先选择沙箱环境。切勿假设当前
```
pac
```
认证配置文件是正确的目标环境。
片段式处理，而非一次性批量处理。每个步骤完成后，将其输出写入研究工作区。研究必须可恢复——今天执行到步骤4后停止，明天继续是正常的运行方式。
输出中不得包含推测内容。仅记录提取的文件和查询所显示的内容。不明确的行为需记录为“不明确”。

Step 0 — Scope gate (always first)

步骤0——范围确认（始终首先执行）

Ask the user (one message, not an interview):

Environment — which org URL? Confirm it; prefer sandbox.
Depth — quick pass (steps 1–4 + a reduced doc: entity map + automation inventory — enough to understand the business shape, ~hours) or full study (all steps, may span days)?
Workspace — where to put the study folder (default:
```
./crm-study/
```
).

Then verify tooling:

pac

installed and authenticated (

pac org who

). If the

dataverse

plugin is installed, its

dv-connect

skill owns setup/auth — hand off to it rather than improvising. Web API calls need a bearer token; reuse the project's existing auth helper if one exists.

Create the workspace and

git init

it:

crm-study/
  src/            # unpacked solution(s) — the extracted "codebase"
  src-yaml/       # pac solution clone output (only if cloud flows / Power Fx commands exist)
  fragments/      # one file per step: 02-entities.md, 04-automation.md, ...
  ARCHITECTURE.md # assembled at the end

Git matters beyond hygiene: re-running step 1 later and reading

git diff

is the cheap "what changed in the org since the last study?" drift check.

向用户询问（一条消息，而非访谈）：

环境——哪个组织URL？请确认；优先选择沙箱环境。
深度——快速扫描（步骤1–4 + 简化文档：实体映射+自动化清单——足以了解业务架构，约数小时）还是全面研究（所有步骤，可能耗时数天）？
工作区——研究文件夹的存放位置（默认：
```
./crm-study/
```
）。

然后验证工具：确认

pac

已安装并完成认证（

pac org who

）。如果已安装

dataverse

插件，其

dv-connect

技能负责设置/认证——请移交至该技能，不要自行操作。Web API调用需要Bearer令牌；如果项目已有认证助手，请复用。

创建工作区并执行

git init

：

crm-study/
  src/            # 解压的解决方案——提取的“代码库”
  src-yaml/       # pac solution clone输出（仅当存在云流/Power Fx命令时）
  fragments/      # 每个步骤对应一个文件：02-entities.md, 04-automation.md, ...
  ARCHITECTURE.md # 最终组装的文档

Git的作用不止于代码规范：后续重新运行步骤1并查看

git diff

是一种低成本的“自上次研究以来组织发生了哪些变化？”漂移检查方式。

Steps 1–7 — Extract

步骤1–7——提取

Work through these in order the first time; after step 1 lands, steps 2–7 are independent of each other and can run as parallel subagents (give each its reference section and the workspace path; each writes only its own fragment).

Step	What it captures	Fragment
1. Solution export	Everything to disk: web resources, PCF controls, FormXml, RibbonDiffXml, workflows-as-XAML, plugin DLLs. YAML clone too if cloud flows / Power Fx commands exist. Checkpoint: show the user what landed before going deeper.	`01-inventory.md`
2. Entity universe	Every table the business uses — union of four sources: app components, sitemap (also keep the Area/Group names: they are the business taxonomy and the doc's chapter list), standard tables with custom columns, record counts/usage. Then expand outward via lookups to catch child entities never shown in navigation.	`02-entities.md`
3. Data model	ERD edges, data dictionary, every option-set value with label — the labels ARE the business vocabulary.	`03-data-model.md`
4. Server automation	`workflow` table by category (classic / business rule / action / BPF / cloud flow) + plugin steps + webhooks. Every item: trigger → behavior → why the business needs it.	`04-automation.md`
5. Client-side logic	Form → event → `library.function` map from FormXml; web resource inventory; PCF vs HTML-hosted React; minified-bundle grep for the tables each React app touches.	`05-client-side.md`
6. Command bar	BOTH generations: classic RibbonDiffXml (including the easy-to-miss Application Ribbons component) and modern `appaction` commands (Power Fx lives in the command component library `.msapp` , not in the row).	`06-commands.md`
7. Security	Roles (≈ personas), BU tree, field security, which roles can use which app.	`07-security.md`

For each step, the exact commands, queries, parsing targets, and the gotchas that silently produce wrong results (join keys, label languages, type casts, 24-hour-stale counts) are in the matching section of

extraction-queries.md

Conditional step 7b — embedded Power BI. Detect deterministically, not by clicking around: dashboards are

systemform

rows with

type eq 0

— scan their

formxml

for Power BI markers (see the reference's step 7b). When found, the analytics logic lives in a Power BI semantic model outside the solution export: record which reports are embedded and which Dataverse tables feed them into

fragments/07b-analytics.md

; if the

pbi-cli

skills are available,

power-bi-docs

can document the model itself.

首次运行时请按顺序执行这些步骤；步骤1完成后，步骤2–7相互独立，可作为并行子代理运行（为每个子代理提供参考章节和工作区路径；每个子代理仅写入自己的片段）。

步骤	捕获内容	片段文件
1. 解决方案导出	将所有内容保存到磁盘：Web资源、PCF控件、FormXml、RibbonDiffXml、XAML格式的工作流、插件DLL。如果存在云流/Power Fx命令，还需导出YAML克隆版本。检查点：深入之前向用户展示已导出的内容。	`01-inventory.md`
2. 实体全域	业务使用的所有表——四个来源的并集：应用组件、站点地图（同时保留区域/组名称：它们是业务分类法和文档的章节列表）、带有自定义列的标准表、记录数量/使用情况。然后通过查找扩展到导航中从未显示的子实体。	`02-entities.md`
3. 数据模型	ERD关系、数据字典、每个选项集的带标签值——标签就是业务词汇。	`03-data-model.md`
4. 服务器端自动化	按类别（经典/业务规则/操作/BPF/云流）划分的 `workflow` 表 + 插件步骤 + Webhook。每个条目：触发器→行为→业务需求原因。	`04-automation.md`
5. 客户端逻辑	从FormXml生成的表单→事件→ `library.function` 映射；Web资源清单；PCF与HTML托管的React对比；通过搜索压缩包找出每个React应用涉及的表。	`05-client-side.md`
6. 命令栏	两代命令栏：经典RibbonDiffXml（包括容易遗漏的Application Ribbons组件）和现代 `appaction` 命令（Power Fx位于命令组件库 `.msapp` 中，而非行内）。	`06-commands.md`
7. 安全	角色（≈角色 persona）、业务单元（BU）树、字段安全、哪些角色可以使用哪些应用。	`07-security.md`

每个步骤的具体命令、查询、解析目标以及可能导致错误结果的陷阱（连接键、标签语言、类型转换、24小时过期计数）都在

extraction-queries.md

的对应章节中。

条件步骤7b——嵌入式Power BI。通过确定性检测，而非手动点击：仪表板是

type eq 0

的

systemform

行——扫描其

formxml

中的Power BI标记（请参考步骤7b的参考内容）。如果检测到，分析逻辑位于解决方案导出之外的Power BI语义模型中：记录哪些报表是嵌入式的，以及哪些Dataverse表为其提供数据，并写入

fragments/07b-analytics.md

；如果

pbi-cli

技能可用，

power-bi-docs

可以记录该模型本身。

Steps 8–9 — Study (this is the actual learning)

步骤8–9——研究（这是真正的学习阶段）

8. Verify the static maps against the running app. The extracted files say what is registered; the app says what runs. Two built-in tools close the gap: Monitor → FormEvents (catches JS handlers registered dynamically in code, which FormXml never shows) and Command Checker (

&ribbondebug=true

on the app URL — the authority on the merged classic+modern command bar). Reconcile differences into the fragments.

9. Trace business processes end to end. For each key entity (start from the sitemap's main work areas, not the master-data ones), connect the layers into a lifecycle:

who creates it (role, step 7) → which form + JS validates and cascades (step 5) → which buttons act on it (step 6) → which automation fires on save (step 4) → which status transitions exist (statuscode labels, step 3) → what downstream records appear.

Walk the app to confirm each lifecycle — a test record makes the cascades and automations visible (watch what auto-populates, check audit history). Per hard rule 1, the test record is created through the app UI, by the user or by you only with their explicit consent, and only in a sandbox — never via the API or

pac

. Write each lifecycle as a user story with a mermaid

sequenceDiagram

into

fragments/09-processes.md

. This step is sequential by nature — it needs all the fragments.

8. 验证静态映射与运行中应用的一致性。提取的文件显示的是已注册的内容；而应用显示的是实际运行的内容。有两个内置工具可以填补这一差距：Monitor → FormEvents（捕获通过代码动态注册的JS处理程序，这些内容从未在FormXml中显示）和Command Checker（在应用URL中添加

&ribbondebug=true

——这是合并后的经典+现代命令栏的权威工具）。将差异协调到片段文件中。

9. 端到端追踪业务流程。对于每个关键实体（从站点地图的主要工作区域开始，而非主数据区域），将各层关联为一个生命周期：

谁创建它（角色，步骤7）→ 哪个表单+JS进行验证和级联（步骤5）→ 哪些按钮对其执行操作（步骤6）→ 保存时触发哪些自动化（步骤4）→ 存在哪些状态转换（状态码标签，步骤3）→ 会生成哪些下游记录。

通过操作应用来确认每个生命周期——测试记录可以使级联和自动化可见（观察自动填充的内容，检查审计历史）。根据硬性规则1，测试记录需通过应用UI创建，由用户创建或经用户明确同意后由你创建，且仅在沙箱环境中进行——绝不能通过API或

pac

创建。将每个生命周期编写为用户故事，并使用mermaid

sequenceDiagram

写入

fragments/09-processes.md

。此步骤本质上是顺序执行的——需要所有片段文件。

Step 10 — Assemble the document

步骤10——组装文档

Build

ARCHITECTURE.md

from the fragments following this skill's

references/architecture-template.md

. The template implements the marketplace diagram convention (

${CLAUDE_PLUGIN_ROOT}/references/diagram-convention.md

). The template's reading order puts user stories first (they answer "why does this org exist") and enforces the one rule that makes the doc useful: every automation, API, and command entry carries a Why row — what breaks without it. Show the user the assembled doc; offer the drift-check habit (re-run step 1 periodically,

git diff

, feed changes to

management-talk

for reporting).

根据本技能的

references/architecture-template.md

模板，从片段文件构建

ARCHITECTURE.md

。该模板遵循市场图表约定(

${CLAUDE_PLUGIN_ROOT}/references/diagram-convention.md

)。模板的阅读顺序将用户故事放在首位（它们回答“这个组织存在的目的是什么”），并强制执行一条使文档有用的规则：每个自动化、API和命令条目都需包含“Why”行——没有它会发生什么问题。向用户展示组装好的文档；建议养成漂移检查习惯（定期重新运行步骤1，执行

git diff

，将变更提交给

management-talk

进行报告）。

Common mistakes

常见错误

Mistake	Fix
Filtering entities by `IsCustomEntity eq true` only	Most of the business lives in customized standard tables. Use the four-source union of step 2.
Reading only per-entity RibbonDiffXml	Global buttons live in the Application Ribbons component (must be added to a solution to export); modern buttons live in `appaction` rows. All three or the map is wrong.
Trusting FormXml as the complete JS map	Handlers added via `addOnLoad` / `addOnChange` in code never appear there. Cross-check with Monitor → FormEvents (step 8).
Treating the XML unpack as complete	Cloud flows and Power Fx command logic only decompose in the YAML clone ( `pac solution clone` ).
Skipping the Why on automation entries	A trigger list without business purpose is an inventory, not documentation. Every entry: what breaks without it?
Writing to the org "just to test something"	Never via API/script/ `pac` . The only sanctioned write is the step-9 UI test record — user-consented, sandbox-only. Read-only is the contract that makes this skill safe to run against any environment.

错误	修复方法
仅通过 `IsCustomEntity eq true` 过滤实体	大多数业务逻辑存在于自定义的标准表中。使用步骤2中的四来源并集。
仅读取每个实体的RibbonDiffXml	全局按钮位于Application Ribbons组件中（必须添加到解决方案才能导出）；现代按钮位于 `appaction` 行中。需包含这三者，否则映射会出错。
认为FormXml是完整的JS映射	通过代码中的 `addOnLoad` / `addOnChange` 添加的处理程序永远不会出现在FormXml中。需使用Monitor → FormEvents（步骤8）进行交叉检查。
认为XML解压是完整的	云流和Power Fx命令逻辑仅在YAML克隆中解析（ `pac solution clone` ）。
跳过自动化条目的Why说明	仅列出触发器的清单只是库存，而非文档。每个条目都需说明：没有它会发生什么问题？
向组织写入内容“只是为了测试”	绝不能通过API/脚本/ `pac` 写入。唯一被允许的写入是步骤9中的UI测试记录——需经用户同意且仅在沙箱环境中进行。只读模式是本技能可安全运行于任何环境的契约。

Sibling skills

关联技能

```
drive-to-legacy
```
— same discipline for a plain source repo; if step 5 turns up the React app's original source repository, switch to it for that part.
```
dataverse:dv-connect
```
/
```
dv-query
```
— auth/setup and ad-hoc data reads if the dataverse plugin is installed.
```
power-bi-docs
```
(pbi-cli) — documents embedded Power BI models (step 7b).
```
fit-gap-analysis
```
— consumes the fragments as the ready-made "as-is" side.
```
debug-mantra
```
— uses
```
04-automation.md
```
+
```
05-client-side.md
```
as the layer map when tracing a CRM bug.
```
seed-dataverse-data
```
— its duplicate-row guardrail scan is answered by
```
04-automation.md
```
.

```
drive-to-legacy
```
——针对纯源代码仓库的相同流程；如果步骤5发现React应用的原始源代码仓库，请切换到该技能处理这部分内容。
```
dataverse:dv-connect
```
/
```
dv-query
```
——如果已安装dataverse插件，负责认证/设置和临时数据读取。
```
power-bi-docs
```
（pbi-cli）——记录嵌入式Power BI模型（步骤7b）。
```
fit-gap-analysis
```
——将片段文件作为现成的“现状”输入。
```
debug-mantra
```
——使用
```
04-automation.md
```
+
```
05-client-side.md
```
作为层映射来追踪CRM错误。
```
seed-dataverse-data
```
——其重复行防护扫描可通过
```
04-automation.md
```
得到答案。