dv-overview

技能：概览 — 使用什么以及何时使用

开始任何 Dataverse 工作时，先加载此技能 — 它包含每项任务都需要的通用背景信息：范围、工具能力参考、硬性规则和变更生命周期。它不负责路由；Agent 会根据各专业技能 frontmatter 中的 WHEN/DO NOT USE WHEN 触发条件自动选择技能。用户用日常语言描述需求；Agent 会自动串联技能，绝不会要求用户指定技能或命令。

---

此插件涵盖的内容

面向所有角色的 Dataverse / Power Platform 工作 — 包括构建者和 Agent 开发者、数据科学家、环境管理员和业务用户 — 由专业技能提供支持。Agent 会根据技能的 frontmatter 触发条件自动加载并路由到这些技能 — 你无需按名称调用它们。

领域	技能
连接、身份验证、配置 MCP、验证环境	dv-connect
架构 — 表、列、关系、表单、视图；检查现有架构	dv-metadata
数据写入 — 记录 CRUD、批量创建/更新/更新或插入、按 CSV/FK 顺序导入、示例数据	dv-data
数据读取与分析 — OData 查询、QueryBuilder、FetchXML（聚合 + N:N 联接）、DataFrame	dv-query
解决方案 ALM — 创建、导出、导入、打包/解包、导入后验证	dv-solution
Finance and Operations X++ — 编写、构建、部署、数据库同步、验证	erp-xpp
环境管理 — 批量删除、保留/存档、组织和 OrgDB 设置、回收站	dv-admin
安全与访问 — 角色、用户、应用程序用户、业务部门、自我提升权限（PAC CLI）	dv-security

**模型驱动应用：**构建模块（表、表单、视图）由 dv-metadata 涵盖；组合应用外壳本身 — 站点地图和导航 — 尚未作为一项一等技能提供。

不在范围内：

• Canvas 应用 — 属于不同的技术；请使用 pac canvas 或创作者门户
• Power Automate 流 — 请使用创作者门户或 Power Automate Management API
• Azure 基础设施，但服务主体设置所需的部分除外
• Business Central 或其他 Dynamics 产品

---

硬性规则

安全规则（初始化、身份验证、环境确认）不可妥协。工具选择（规则 1、2、4）基于能力。

0. 首先检查初始化状态

在编写任何代码或创建任何文件之前，主动搜索可调用工具，查找名称或描述中包含 dataverse 的工具（工具可能以特定环境名称注册，例如 mcp__dataverse_<orgid>__read_query，而不只是通用名称）。**如果找到任何 Dataverse MCP 工具，直接使用 — 跳过初始化检查和所有设置。**MCP 身份验证由宿主管理，不需要 .env 或 scripts/auth.py。切勿仅根据最初显示的工具列表就断定 MCP 不可用。

如果没有找到 MCP 工具，请检查是否存在 CLI 配置文件 — 这是执行数据操作最快的途径：

dataverse auth who

如果显示有活动配置文件且包含环境 URL，请直接使用 CLI 执行数据操作（参见 dv-query/dv-data 示例）— 无需 .env、auth.py 或工作区设置。对于明确提出的“连接”或“设置”请求，则无论如何都要运行 dv-connect — 它会配置 MCP、SDK 和 PAC。

如果不存在 CLI 配置文件，请检查工作区初始化状态：

ls .env scripts/auth.py 2>/dev/null

• 如果两者都存在：继续执行任务。
• 如果任一缺失：运行 python <plugin-scripts>/auth.py --ping。如果输出 REACHABLE（退出码为 0），则无需 pip 即可启动工作区 — 确认 URL 并继续。如果 --ping 失败，运行 dv-connect。

1. 使用 Python 编写脚本；CLI 和 MCP 均是一等工具

Python 用于编写自动化逻辑（转换、控制流、重试、CSV）。工具链（scripts/auth.py、SDK、技能示例）基于 Python。不过，MCP 工具、Dataverse CLI（dataverse）、Python SDK 和 PAC CLI（pac）都是一等工具调用——选择最适合的即可。Dataverse CLI 与 pac 地位相同；在整个解决方案和元数据技能中都可以自由调用 pac。

绝不：

• 使用 JavaScript/TypeScript/Node.js 编写自动化逻辑（npm、yarn、pnpm、package.json、node_modules/）
• 使用 @azure/msal-node、@azure/identity 或任何 Node.js Azure SDK
• 自行实现 MSAL / 设备代码流——身份验证使用 scripts/auth.py、pac auth 和 Dataverse CLI

始终：

• 使用 pip install 和 Python SDK（PowerPlatform-Dataverse-Client）处理数据和架构逻辑
• 使用 scripts/auth.py 获取令牌/凭据；使用 azure-identity（Python）处理 Azure 凭据流
• 将 Dataverse CLI（dataverse）和 pac 视为允许使用的一方 CLI

2. 选择合适的接口——了解能力，而非遵循固定顺序

没有强制的工具顺序。每种接口都有自己的能力特征；根据任务和当前所用接口选择合适的工具——这些只是灵活的默认建议，并非必须遵循的步骤。完整矩阵见下方的工具能力；原则如下：

• 优先使用托管接口（MCP、Dataverse CLI 或 SDK），而非手动编写原始 OData——托管接口已处理身份验证、分页、重试和地理路由，而原始 HTTP 需要自行实现。当 MCP 无法处理时（批量操作超过 25 条记录、大量读取、高级架构，如表单/视图/N:N 关系/全局选项集/备用键、多步骤工作流、分析，或 MCP 不可用），默认使用 Python SDK。
• 原始 Web API 是没有托管途径时的最后手段（例如未绑定操作 PublishXml、全局选项集，以及没有一等 SDK/CLI 命令的任何功能）——即使如此，也优先使用 dataverse api（托管身份验证、退出代码），而不是手动编写 urllib/get_token。表单/视图并非只能使用原始接口（可通过 SDK 在 systemform/savedquery 上调用 records.create/update；只有 PublishXml 需要 dataverse api）。聚合/N:N 联接也并非只能使用原始接口：可以使用 client.query.fetchxml()（聚合 + link-entity），也可以使用 CLI 的 data associate 执行 N:N 写入。
• 如果 SDK 方法失败，或 PAC 命令似乎缺失，请先查看相关技能，再手动编写原始 HTTP。

字段大小写：$select/$filter 使用小写逻辑名称（new_name）。$expand 和 @odata.bind 使用区分大小写的导航属性名称，且必须与 $metadata 相符（例如 new_AccountId）。大小写错误会导致 400 错误。**SDK 记录负载：**在 @odata.bind 键上使用正确的 SchemaName 大小写（例如 [email protected]）；SDK 不会自动纠正错误的大小写。原始 Web API 调用（表单、视图、元数据）：大小写完全由你手动处理——小写的 [email protected] 会导致 400 错误。

**发布者前缀：**绝不要硬编码前缀（尤其是 new）；应查询现有发布者并询问用户。前缀是永久的。请参阅解决方案技能中的发布者发现流程。

3. 使用文档记录的身份验证模式

三个入口，共用一种登录方式：

• dataverse auth create（Dataverse CLI）会写入共享的 MSAL 令牌缓存。此登录方式可供 CLI、MCP 代理以及通过 msal-extensions 使用缓存的 scripts/auth.py 使用。
• scripts/auth.py — Python/SDK 身份验证（服务主体 → 共享 CLI 缓存 → 设备代码）。优先使用 get_client(skill)（SDK）；get_plugin_headers(skill, get_token()) 是 SDK 功能缺失时的回退方案——两者都会附加归属信息。
• pac auth create（PAC CLI）用于对 pac 进行身份验证，供 dv-solution、dv-admin 和 erp-xpp 使用。

**遥测归属信息（保持确定性）：**每个请求都携带封闭架构的 app=dataverse-skills/<ver>;skill=<skill>;agent=<agent> 上下文，以便服务器识别哪个技能路由了每次 OData 调用。该上下文已内置——get_client(skill) 和 get_plugin_headers(skill, ...) 会在 SDK 和原始 HTTP 路径上附加该上下文；Dataverse CLI 会自动附加 DataverseCli/<ver> 和命令，你需要通过 --context "app=dataverse-skills/<ver>;skill=<skill>;agent=<agent>" 添加技能信息（CLI 会自行加上括号——请勿预先添加）。切勿修改、省略或随意填写此上下文——它采用封闭架构（技能和 Agent 均须在允许列表中，不含 PII）。

绝对不要：

• 读取或解析原始令牌缓存文件（例如 tokencache_msalv3.dat）——只能通过 scripts/auth.py / msal-extensions 复用缓存
• 自行实现 MSAL 设备代码流程
• 在脚本中硬编码令牌或凭据
• 发明新的身份验证机制

如果身份验证已过期或缺失，请重新运行 dataverse auth create（或 pac auth create），或检查 .env。请参阅 dv-connect 技能。

4. 坦诚说明缺口——不要编造

每项技能都记录了经过测试的调用顺序——适用时请按此操作。技能文档是受支持且未弃用 API 的事实来源。如果调用因 AttributeError 失败，可能是已安装的 SDK 版本不支持该功能——请查看技能中的版本说明，并使用文档记录的替代方案。

**诚实守则：**如果遇到技能文档未涵盖的缺口，请如实说明并提出变通方案。不要编造不受支持的调用路径——不要发明未记录的方法、参数或端点。如不确定，请如实说明。

**连通性不等于身份验证。**即使 login.microsoftonline.com 令牌获取成功，组织的数据平面域名仍可能无法访问（例如 ChatGPT Work Mode 等出口受限的主机）。切勿报告并非来自真实返回调用的计数或结果——请通过 python scripts/auth.py --check 验证；若失败，请说明“无法访问”，绝不要捏造数字。在受限主机上，优先使用 SDK，而不是 CLI/MCP。请参阅 dv-connect/references/headless-hosts.md。

---

工具能力——不同任务该用哪个工具

了解每种工具的实际限制，可以避免编造调用路径。这是单项技能都不包含的唯一一部分上下文。

工具	适用场景	不支持的功能
MCP Server	数据 CRUD（创建/读取/更新/删除记录，每次调用最多批量处理 25 条记录）、创建/更新/删除表 + 添加列（包括本地选项/多选 + 查找/客户列）、通过 describe 检查架构 + 记录、搜索元数据（search）、搜索数据 + 文件内容（启用 Dataverse 搜索时使用 search_data）、上传/下载文件	表单、视图、全局选项集、N:N关系、备用键、解决方案（通过 create_table/update_table 支持查找 + 本地选项/多选列）。**注意：**创建表可能超时，但仍可能成功——重试前务必先运行 describe（例如 describe('tables/{name}')）。按顺序运行查询（并行调用会超时）。带空格的列名会规范化为下划线（例如 "Specialty Area" → cr9ac_specialty_area）。**SQL（read_query）：**支持 JOIN、GROUP BY（COUNT/SUM/AVG/MIN/MAX）、TOP、WHERE、ORDER BY；不支持 DISTINCT、HAVING、子查询、OFFSET、UNION、CASE/IF、CAST/CONVERT、CTE 或日期函数。对于这些功能，请使用 client.query.sql()（也支持 DISTINCT，少于 5K 行）、$apply，或使用构建器生成 DataFrame，再通过 pandas 处理——参见 dv-query。**批量操作：**MCP create_record/update_record/delete_record 每次调用最多批量处理 25 条记录；更大规模的批量操作请使用 SDK CreateMultiple——参见 dv-data。
Python SDK（dv-data）	脚本化数据写入，尤其适用于大量数据。记录 CRUD、upsert（备用键）、批量创建/更新/upsert（CreateMultiple/UpdateMultiple/UpsertMultiple）、解析查找项的 CSV 导入、文件列上传（大于 128MB 时分块）	全局选项集、记录关联（$ref）、$apply聚合、表/列/关系创建（使用 dv-metadata）、调用自定义操作
Python SDK（dv-query）	批量读取和分析。多页记录迭代、OData 查询（select/filter/expand/orderby）、QueryBuilder 流式 API、无需 GUID 的显示（格式化值）、通过 $expand 解析查找项、通过 client.query.fetchxml() 聚合和连接 N:N（聚合 FetchXML + link-entity）、移交 pandas DataFrame（client.query.builder(...).execute().to_dataframe()）以便导出、Jupyter notebook 代码片段	QueryBuilder 路径上的 OData $apply 和 N:N $expand——N:N 请使用 records.list(expand=...)，聚合请使用 fetchxml()（不要使用原始 urllib）
Dataverse CLI（dataverse）	无头数据平面：data CRUD、associate/disassociate（N:N + $ref）、data upload；api request/invoke（Web API 备用入口）；api list/describe（发现自定义 API）	元数据/架构（使用 SDK——dv-metadata）、解决方案 ALM（使用 PAC）、表单/视图；ChatGPT web / Codex cloud 中不可用（没有 .NET 运行时）——请使用 SDK
PAC CLI	解决方案导出/导入/打包/解包、ERP X++ SDK 安装 + 包架构搭建/编译/部署/数据库同步、创建/列出/删除/重置环境、身份验证配置文件管理、插件更新（pac plugin push——首次注册需要 Web API）、用户/角色分配（pac admin assign-user）、添加解决方案组件（pac solution add-solution-component）	数据 CRUD、创建 Dataverse 元数据（表/列/表单）、列出解决方案组件（没有 list-components——通过 SDK/CLI 查询 solutioncomponent）；X++ SDK 安装/编译需要 Windows
Azure CLI	应用注册、服务主体、凭据管理	Dataverse 专属操作
GitHub CLI	仓库管理、GitHub 密钥、Actions 工作流状态	Dataverse 专属操作
原始 Web API（最后手段）	仅当没有托管接口提供该操作时使用——即无法通过 MCP、Python SDK、Dataverse CLI 或 dataverse api 备用入口实现时。确实适用的情况：未绑定操作（如 PublishXml）、全局选项集及类似边缘情况（不包括表单/视图——这些可通过对 systemform/savedquery 执行 SDK 记录 CRUD 实现）。即使如此，也应优先使用 dataverse api（托管身份验证 + 技能归属），而不是手写 urllib。	功能上没有限制（完整的 OData/MetadataService）——但原始 urllib 会绕过托管身份验证、分页、重试和技能归属，因此应将其视为最后手段
**路由：**该表展示了各个界面的用途；如何选择原则（软性默认，而非固定顺序）是硬性规则 2。列表中没有 MCP 工具？加载 dv-connect。

**用量指南：**一次性命令使用 CLI dataverse data create/query/count；每次调用约 25 条记录以内或使用简单筛选时使用 MCP；大量批量写入使用 SDK 的 CreateMultiple（大批量数据从约 1,000 条开始分块——参见 dv-data），批量读取使用 dv-query；聚合使用 SDK 的 fetchxml()。

SDK 方法速查表（用于防止幻觉，不是偏好信号）：SDK 方法名称最难发现，因此 Agent 常会凭空编造。本表将常见操作映射到准确调用。根据硬性规则 2，每项操作也都可以通过 MCP/CLI 完成；完整模式请参见注明的技能。

操作	SDK 调用	技能
创建 / 更新 / 删除记录	client.records.create() / .update() / .delete()（批量操作时传入列表）	dv-data
使用备用键进行 Upsert	client.records.upsert()	dv-data
查询 / 筛选记录	client.records.list(...)（扁平结果）或 .list_pages(...)（流式处理）	dv-query
按 GUID 获取单条记录	client.records.retrieve(table, guid)（缺失时返回 None）	dv-query
聚合 / 服务端联接	client.query.fetchxml(xml)（聚合 + link-entity）	dv-query
流畅式查询构建（可链式调用）	client.query.builder(Table).where(...).execute()	dv-query
有限 SQL 读取	client.query.sql("SELECT ...")	dv-query
加载到 pandas	client.query.builder(table).select(...).execute().to_dataframe()	dv-query
上传到文件列	client.files.upload(...)	dv-data
创建表 / 列 / 查找列 / N:N 关系	client.tables.create() / .add_columns() / .create_lookup_field() / .create_many_to_many_relationship()	dv-metadata
创建备用键（启用 upsert）	client.tables.create_alternate_key(...)	dv-metadata
检查现有架构	client.tables.list_columns(table) / .list_table_relationships(table)	dv-metadata
创建发布者 / 解决方案	client.records.create("publisher" / "solution", {...})	dv-solution

MCP 可用性检查

如果用户的请求涉及 MCP（无论明确还是隐含），请在可调用工具中搜索名称或描述包含 dataverse 的工具（与硬性规则 0 中的搜索相同）。

如果 MCP 不可用，且用户明确要求使用 MCP（“使用 MCP 查询”）：

1. 不要默默改用 Python SDK 或 Web API
2. 告知用户：“此会话尚未配置 Dataverse MCP 工具。”
3. 加载 dv-connect 以设置 MCP 服务
4. 配置好 MCP 后，停止——必须重启会话，MCP 工具才会出现。不要继续使用 SDK。

如果 MCP 不可用，且用户提出的是数据问题（“有多少个账户？”）：

1. 使用 CLI（如果已有配置文件）或 SDK 作答。不要让用户无法继续。
2. 作答后，主动询问：“MCP 可以通过对话方式处理这个问题——需要我帮你设置吗？”

两者的区别很重要：明确要求使用 MCP → 暂停操作并设置 MCP；隐含的数据问题 → 使用 SDK 作答，并提供 MCP 设置选项。

如果 MCP 工具可用，简单读取 / 查询 / 小规模 CRUD 操作优先使用 MCP。仅在需要编写脚本时使用 SDK。

---

变更生命周期 — 安全操作

对于任何实际变更，请按顺序完成以下三个步骤：确认位置，确认容器，然后持久化结果。

步骤 1 — 确认环境（必须）

Dataverse 工作通常涉及多个环境（dev、test、staging、prod）和多组凭据。切勿假设当前 PAC 身份验证配置文件、.env 中的值，或记忆及之前会话中的任何信息，反映了当前任务的正确目标环境。

在首次执行会触及特定环境的操作之前——创建表、部署插件、推送解决方案、插入数据——你必须：

1. 向用户显示你打算使用的环境 URL
2. 请用户确认该 URL 是否正确
3. 运行 pac org who，验证当前活动连接是否匹配

“我即将对 <URL> 进行更改。这是正确的目标环境吗？”

在用户明确确认之前，不得继续操作。 这是此插件中最重要的安全检查。跳过此步骤可能导致在错误的环境中进行不可逆更改。在同一会话中，用户确认环境后，针对同一环境的后续操作无需再次确认。

步骤 2 — 确认解决方案（更改任何元数据之前）

创建表、列或其他元数据之前，请确保存在一个用于容纳这些工作的解决方案：

1. 询问用户：“这些组件应该放入哪个解决方案？”
2. 如果 .env 中有解决方案名称（SOLUTION_NAME），请向用户确认
3. 如果尚无解决方案，加载 dv-solution 技能，并遵循其发布者发现和解决方案创建流程。使用 SDK——绝不要使用原始 Web API——创建发布者和解决方案记录：

# Quick reference — full pattern with publisher discovery is in dv-solution
publisher_id = client.records.create("publisher", {
    "uniquename": "<name>", "friendlyname": "<display>",
    "customizationprefix": "<prefix>", "description": "<desc>",
})
solution_id = client.records.create("solution", {
    "uniquename": "<Name>", "friendlyname": "<Display>",
    "version": "1.0.0.0",
    "[email protected]": f"/publishers({publisher_id})",
})

4. 在所有 SDK 调用中传入 solution="<UniqueName>"，或在原始 Web API 元数据调用中包含 "MSCRM.SolutionName": "<UniqueName>" 标头。

不使用解决方案创建的元数据只会存在于默认解决方案中，无法妥善导出或部署。始终先创建解决方案。

步骤 3 — 拉取到仓库（必须）

每次更改元数据（通过 MCP、Web API 或 maker portal）后，都必须在会话结束时执行拉取：

pac solution export --name <SOLUTION_NAME> --path ./solutions/<SOLUTION_NAME>.zip --managed false
pac solution unpack --zipfile ./solutions/<SOLUTION_NAME>.zip --folder ./solutions/<SOLUTION_NAME>
rm ./solutions/<SOLUTION_NAME>.zip
git add ./solutions/<SOLUTION_NAME>
git commit -m "feat: <description>"
git push

仓库始终是事实来源。

---

脚本

该插件附带 scripts/auth.py（用于获取 Azure Identity 令牌/凭据，供所有其他脚本和 SDK 使用）。除一次性查询外，任何 Web API 调用都应编写为 Python 脚本并提交到 /scripts/，使用 scripts/auth.py 获取令牌。写入操作请参阅 dv-data；查询和分析请参阅 dv-query；导入后验证请参阅 dv-solution。

---

Windows 脚本

特定平台的 shell 规则（.py 中使用 ASCII、禁止多行 python -c、PAC PowerShell 封装、后台输出不缓冲）位于 references/windows-scripting.md。在 Windows 上运行时请阅读。