dv-connect

技能：连接

一步完成 Dataverse 连接，可重复执行且不会产生副作用。每个步骤都会检查是否已完成，若已完成则跳过。

环境优先规则 — 所有元数据和插件注册都通过 API／脚本在环境中创建，然后再拉取到代码库中。切勿手动编写解决方案 XML 来创建组件。

按顺序执行步骤；不要跳步。 **例外：**如果工作区已设置完成，步骤 0 可以直接结束整个流程。

主机入口测试（首先执行——在步骤 0 之前）。 本地 Windows／macOS 主机默认具备所需能力，无论由哪个 Agent 驱动——它可以运行 CLI、使用持久凭据并托管本地 MCP 服务；审批／沙盒限制不构成障碍，缺少 CLI 就安装。仅当运行时无法启动、身份验证无法持久保存，或主机明确属于 ChatGPT Work Mode／Codex 云端／CI／无密钥环的 Linux 时，才属于受限环境（判定表：headless-hosts.md）。受限 → 仅安装 Python 和 pip 依赖，配置 .env，运行 scripts/auth.py，验证 python scripts/auth.py --check，跳过 CLI／PAC／MCP。具备能力 → 按照以下正常流程操作。

---

步骤 0：检测现有设置（首先执行此步骤）

开始任何操作前，检查此工作区是否已连接到 Dataverse 环境。对已配置的工作区重复设置会覆盖 .env、重新注册 MCP，并浪费时间。

Gemini 仅支持 GA。如果请求使用 Preview，请先说明并停止，不要通过设置快捷跳过流程。

按顺序运行以下检查。如果四项全部通过，直接跳到步骤 7（最终验证），然后停止。

1. .env 存在且内容完整 — 工作区根目录下存在此文件，且 DATAVERSE_URL、TENANT_ID 和 MCP_CLIENT_ID 的值均非空
2. MCP 已注册 — 主机的 MCP 列表中有一项 dataverse-*，或 Gemini 中有其内置的 dataverse 项，且该项指向 DATAVERSE_URL
3. 两个身份验证端均与 .env 匹配 — dataverse auth who 显示的配置文件中，Environment Url 与 DATAVERSE_URL 一致；并且针对相同 URL 的 PAC 配置文件运行 pac org who 成功。（DV CLI 身份验证适用于 Connect／Data／Query／Metadata／MCP／Python；PAC 身份验证适用于 dv-solution 和 dv-admin。两者都在连接时预先完成，以免之后触发提示。）
4. Python SDK 可导入且为最新版本 — 运行 python -c "from PowerPlatform.Dataverse.client import DataverseClient; import pandas; from importlib.metadata import version; v=version('PowerPlatform-Dataverse-Client'); parts=tuple(int(p) for p in v.split('.')[:2]); assert parts>=(1,1), f'SDK {v} is outdated, need >=1.1.0'"，并以 0 退出

**如果全部通过：**首先确保 .env 中的归属信息有效——将 DATAVERSE_PLUGIN_VERSION 设为已加载清单中的 version，并在 DATAVERSE_PLUGIN_AGENT 缺失或为过期的 unknown／占位值时，添加该项（根据步骤 3 检测主机）。确认检测到的设置（URL、配置文件、MCP 服务），然后跳到步骤 7。除此之外，不要改写 .env、重新注册 MCP 或重新运行 pip install。

**如果任一项未通过：**按正常流程执行步骤 1–7，但仍需遵循每个步骤自身的跳过条件。部分配置的工作区无需从头重做——例如，如果只有 .env 和 MCP 缺失，但工具和身份验证均正常，则从步骤 2 或步骤 3 开始。

---

步骤 1：确保已安装工具

分别检查每个工具——一次性报告所有缺少的工具。安装命令请参阅 tools-setup.md。

工具	检查方式
Python 3	python --version
Git	git --version
Node.js	node --version
PAC CLI	pac（会打印版本横幅；pac --version 无效）（如果不在 PATH 中，请参阅 tools-setup.md）
Dataverse CLI	npm list -g @microsoft/dataverse
.NET SDK	dotnet --version
Azure CLI	az --version

PAC CLI 需要 .NET SDK，但 Dataverse CLI 不需要（npm 包已自带运行时）。Node.js 用于运行 Dataverse CLI npm 包（@microsoft/dataverse），该包用作 MCP 代理，并用于脚本化数据平面操作。PAC CLI 不可用时，Azure CLI 用作环境发现的后备方案（请参阅 mcp-configuration.md 步骤 3b）。连接时不需要 GitHub CLI——它之后用于 ALM/CI/CD 场景（请参阅 dv-solution）。

如果缺少任何工具，请安装（参阅 tools-setup.md），然后验证。如果 winget 安装了工具，但该工具不在 PATH 中，请让用户重启终端。

确认已安装 Python 后，先检查依赖项是否已存在，再进行安装：

python -c "from PowerPlatform.Dataverse.client import DataverseClient; import azure.identity, msal, msal_extensions, requests, pandas; print('OK')"

如果输出 OK，则跳过 pip。否则：

pip install --upgrade azure-identity requests PowerPlatform-Dataverse-Client pandas msal msal-extensions

msal + msal-extensions 可让 scripts/auth.py 重用 dataverse auth create 缓存——CLI、MCP 和 Python 只需登录一次。

确认已安装 Node.js 后，仅在 Dataverse CLI 缺失时安装（不要每次连接时都重新运行——在受管设备上，每次获取 @latest 都可能触发 npm 注册表安全提示；请参阅 tools-setup.md）：

npm install -g @microsoft/dataverse@latest

**跳过条件：**所有工具均已就绪、已安装 Python SDK，且可导入 pandas（python -c "import pandas"）。

---

步骤 2：发现并选择环境

向用户询问 URL 之前，先检查当前已有的可用环境。

**身份验证工具选择。**两个工具、两个 AAD 应用、两个缓存——连接时应预先完成这两项：

1. dataverse auth create（应用 0c412cc3-…）适用于 DV CLI + MCP + Python。
2. pac auth create（PAC 自有应用）适用于 dv-solution + dv-admin。

先检查是否已有 DV CLI 配置文件；如有需要，再使用 PAC 发现环境：

dataverse auth list
dataverse auth who
pac auth list   # PAC profiles are still useful for env discovery / pac org list

如果 dataverse auth who 显示存在配置文件，且其环境与用户的目标环境一致：

• 重用该配置文件。根据配置文件设置 DATAVERSE_URL 和 TENANT_ID。

如果不存在 DV CLI 配置文件（或配置文件指向错误的环境）：

• 询问：“您想连接到现有环境，还是创建新环境？”

**选择之前，检查租户/区域是否不匹配。**如果目标 URL 使用的区域与已验证账户的环境不同，请为正确的租户创建新的配置文件，而不是重用旧配置文件：

dataverse auth create --environment <url>          # interactive (WAM broker on Windows → no browser tab)
dataverse auth create --environment <url> --deviceCode   # headless / remote / SSH

如果用户遇到管理员同意错误，CLI 会输出正确的、限定了范围的同意 URL，供用户分享给租户管理员——不要自行编造。

要在现有 DV CLI 配置文件之间切换：

dataverse auth select --name <profile-name>

要创建新环境（需要管理员权限）：

pac admin create --name "<name>" --type "<type>" --region "<region>"

如果因权限错误而失败，请引导用户前往 Power Platform 管理中心创建环境，然后连接。

确认连接：

dataverse auth who
dataverse org who --context "app=dataverse-skills/<ver>;skill=dv-connect;agent=<agent>"

解析输出以提取 DATAVERSE_URL、TENANT_ID，以及 ERP 关联环境中的 ERP_URL（请参阅 erp-detection.md）。

如果两个命令都未显示租户 ID，则改用：

curl -sI https://<org>.crm.dynamics.com/api/data/v9.2/ \
  | grep -i "WWW-Authenticate" \
  | sed -n 's|.*login\.microsoftonline\.com/\([^/]*\).*|\1|p'

步骤 2b：预先为同一环境完成 PAC CLI 身份验证

PAC 使用自己的 AAD 应用，因此 dv-solution 和 dv-admin 需要单独登录——现在就完成。

pac auth list                                       # skip if a profile for $DATAVERSE_URL exists
pac auth create --name <orgid> --environment <DATAVERSE_URL>

使用与步骤 2 相同的账户。如果未安装 PAC CLI，则跳过，并注明之后使用 dv-solution / dv-admin 时需要安装。

---

第 3 步：创建 .env

展示身份验证选项：

你希望如何通过 Dataverse 进行身份验证？

1. 交互式登录（推荐） — 通过浏览器登录。无需注册应用。令牌会缓存在会话之间。
2. CI/CD 服务主体 — 使用 CLIENT_SECRET 或 CLIENT_CERTIFICATE_PATH。

直接写入 .env — 不要指示用户创建它：

根据检测到的一个 tool_type 同时推导 MCP_CLIENT_ID 和规范归属信息。根据已加载的清单设置 PLUGIN_VERSION；Antigravity 使用 .claude-plugin/plugin.json，因为原生 plugin.json 中没有此项。

tool_type = "<copilot | claude | cursor | codex | gemini | antigravity | unknown>"
plugin_version = "<plugin manifest version, e.g. 1.5.0>"
mcp_client_id = "aebc6443-996d-45c2-90f0-388ff96faa56" if tool_type == "copilot" else "0c412cc3-0dd6-449b-987f-05b053db9457"
agent_host = {
    "copilot": "copilot", "claude": "claude-code", "cursor": "cursor",
    "codex": "codex", "gemini": "gemini-cli",
    "antigravity": "antigravity-cli",
}.get(tool_type, "unknown")

with open(".env", "w") as f:
    f.write(f"DATAVERSE_URL={dataverse_url}\n")
    f.write(f"TENANT_ID={tenant_id}\n")
    f.write(f"MCP_CLIENT_ID={mcp_client_id}\n")
    f.write(f"DATAVERSE_PLUGIN_VERSION={plugin_version}\n")
    f.write(f"DATAVERSE_PLUGIN_AGENT={agent_host}\n")
    f.write(f"SOLUTION_NAME={solution_name}\n")
    f.write(f"PUBLISHER_PREFIX=\n")  # filled in when solution is created
    f.write(f"PAC_AUTH_PROFILE=nonprod\n")
    if client_id:
        f.write(f"CLIENT_ID={client_id}\n")
    if client_secret:
        f.write(f"CLIENT_SECRET={client_secret}\n")

确保 .env 已加入 .gitignore：

import os

GITIGNORE_ENTRIES = [
    ".env", ".vscode/settings.json", ".claude/mcp_settings.json",
    ".token_cache.bin", ".dataverse/", "*.snk", "__pycache__/", "*.pyc",
    "solutions/*.zip", "plugins/**/bin/", "plugins/**/obj/",
]
gitignore = open(".gitignore").read() if os.path.exists(".gitignore") else ""
missing = [e for e in GITIGNORE_ENTRIES if e not in gitignore]
if missing:
    with open(".gitignore", "a") as f:
        f.write("\n" + "\n".join(missing) + "\n")

跳过条件： .env 已存在且包含所有必需值。

---

第 4 步：设置项目结构（仅限新项目）

如果这是一个新项目（没有 scripts/ 目录）：

mkdir -p solutions plugins scripts

确保 scripts/auth.py 和 scripts/enable-mcp-client.py 存在——参见 references/helper-scripts.md。

如果仓库根目录中不存在 templates/CLAUDE.md，请将其复制到根目录。将占位符（{{DATAVERSE_URL}}、{{SOLUTION_NAME}}、{{PUBLISHER_PREFIX}}）替换为 .env 中的值。

---

第 5 步：验证连接

dataverse auth who
pac org who
python scripts/auth.py --check

--check 会执行真实的数据平面调用（而不只是获取令牌）——这是证明组织确实可访问的唯一方式；即使组织域名被拦截，仍可能成功创建令牌。所有检查都必须解析到同一用户/环境，以证明 DV CLI 缓存、PAC 配置文件（第 2b 步）以及 Python 对共享缓存的复用均已正确配置。

如果任一检查失败：

• dataverse auth who 失败 → 重新运行第 2 步。
• pac org who 失败 → 重新运行第 2b 步。
• python scripts/auth.py --check 显示设备代码 URL → 浏览器/WAM 缓存中没有可供 Python 复用的令牌。自动修复： 重新运行 dataverse auth create --environment <url> --deviceCode，然后重试。如果仍然提示，请检查 pip show msal msal-extensions。无头主机（ChatGPT / Codex cloud / CI）：dataverse auth create 无法在此持久化令牌——不要反复重试（参见 headless-hosts.md）。
• python scripts/auth.py --check 显示 NOT REACHABLE 并附带连接/超时错误 → 组织域名被网络出口策略拦截，而非身份验证问题。不要报告成功或数量——参见 headless-hosts.md 中的修复方法。
• 其他 Python 错误 → 检查 SDK 安装和 .env。

开始处理元数据前，还要确认账户拥有 prvCreateEntity 自定义特权——参见 tools-setup.md。

---

步骤 6：配置 MCP 服务

仅在当前宿主指向所选环境时，才跳过此步骤：

• Gemini：gemini mcp list 将捆绑服务 dataverse 解析为所选 URL
• Antigravity：agy mcp list 包含所选环境
• 其他宿主：其 MCP 列表或配置中包含指向所选 URL 的 Dataverse 服务

如果尚未配置 MCP，请按照 mcp-configuration.md 操作：

1. 根据上下文检测用户正在运行哪个工具（Copilot、Claude、Cursor、Codex、Gemini 或 Antigravity）
2. 根据工具选择设置 MCP_CLIENT_ID
3. 从 .env 获取环境 URL
4. 默认使用 GA 端点（/api/mcp）
5. 根据宿主注册 MCP 服务（参见下方各宿主对应的区块）
6. 处理 Dataverse 管理员许可和允许列表——优先使用 dataverse mcp allow <MCP_CLIENT_ID>，而不是门户（每个租户/环境仅需执行一次）
7. 如果存在 ERP_URL，请单独将其加入允许列表并进行验证

**MCP 插件归属信息：**此插件使用 stdio 代理传输（npx @microsoft/dataverse mcp <url>）。注册时，请在 env 区块中加入 DATAVERSE_OPERATION_CONTEXT，以便 CLI 在向 /api/mcp 发送请求时将其附加到 User-Agent。根据 .env 构建其值：

DATAVERSE_OPERATION_CONTEXT=app=dataverse-skills/{DATAVERSE_PLUGIN_VERSION};skill=mcp-direct;agent={DATAVERSE_PLUGIN_AGENT}

对于 Claude Code（claude mcp add -t stdio），通过 -e DATAVERSE_OPERATION_CONTEXT=... 传递。对于 JSON/TOML 宿主，将其添加到服务的环境区块中。

**重要提示：**配置 MCP 后，必须重启编辑器/CLI。

**对于 Copilot：**写入 JSON 配置，然后：

✅ 已配置 Dataverse MCP 服务。重启编辑器使更改生效。

**对于 Claude：**运行 claude mcp add 命令，然后提醒用户，下次启动时会出现身份验证弹窗：

✅ 已注册 Dataverse MCP 服务。重启 Claude Code 以启用 MCP 工具。 请记得使用 claude --continue 恢复会话，以保留上下文。

重启时，可能会打开浏览器窗口，让你登录 Dataverse 环境（MCP 代理会代你进行身份验证）。详情请参阅 mcp-configuration.md。

**对于 Cursor：**写入 JSON 配置，然后：

✅ 已在 ~/.cursor/mcp.json 中配置 Dataverse MCP 服务 dataverse-{orgid}。重新加载 Cursor 窗口（Ctrl+Shift+P →“Developer: Reload Window”），以便在“Settings → Tools & MCPs”下显示新的 MCP 服务。

首次使用时，npx @microsoft/dataverse 代理会通过浏览器设备代码登录，之后会静默复用共享缓存。详情请参阅 mcp-configuration.md。

**对于 Codex：**将 TOML 配置写入 ~/.codex/config.toml。Codex 仅在启动时加载 MCP 工具，因此在用户重启前，不要声称这些工具可以调用。告知用户：

✅ 已在 ~/.codex/config.toml 中配置 Dataverse MCP 服务 dataverse-{orgid}。重启 Codex（CLI），或重新加载 Codex IDE，以加载 MCP 工具。

---

步骤 7：最终验证

编辑器/CLI 重启后，必须成功通过以下两项检查，才能宣布设置完成：

检查 1：宿主的 MCP 列表显示 Dataverse 服务已连接

• Claude：claude mcp list
• Gemini：gemini extensions list，然后运行 gemini mcp list
• Antigravity：agy mcp list；重启后运行 /mcp 这可以证明 MCP 服务已启动，但不能证明数据操作可用。

检查 2：Agent 成功通过 describe/search 列出表并返回数据

“列出我的 Dataverse 环境中的表。”

这可以证明端到端连接均正常：身份验证、租户许可、环境允许列表和终结点可访问性都没有问题。如果 Agent 回退到 PAC CLI 或 Web API，请参阅 mcp-configuration.md 中的故障排除说明。

只有两项检查都通过，才能确认设置已验证。

解读失败情况：

• 如果检查 1 失败（服务未显示为 ✓ Connected）：MCP 服务本身无法启动。重新运行步骤 6，并检查是否已安装 npx/Node.js，以及 MCP 注册是否成功。
• 如果检查 1 通过，但检查 2 失败（服务已启动，但 describe/search 报错）：服务可以使用 MCP 通信，但无法访问或读取 Dataverse。运行下方的 --validate 进行诊断。

诊断 — --validate（仅用于故障排查）：

npx @microsoft/dataverse mcp {DATAVERSE_URL} --validate

此命令会通过全新的身份验证握手测试两个 Dataverse MCP 终结点，并报告详细错误（身份验证、允许列表、许可、终结点可访问性）：

• GA / Production 终结点 — {DATAVERSE_URL}/api/mcp。这是插件在运行时实际使用的终结点。
• Preview 终结点 — {DATAVERSE_URL}/api/mcp_preview。需为每个环境单独选择启用；插件不会使用此终结点。

首次设置时，不要将 --validate 用作成功判定条件。 在刚配置好的工作区中，令牌缓存尚未预热，因此 --validate 可能会报 MsalClientException 或 403，但 MCP 在后续实际调用中可能运行正常。只有在检查 1 或检查 2 已确认失败时，才使用 --validate 进行诊断。

如何解读 --validate 输出：

• 先查看 GA / Production 终结点（/api/mcp）的结果。 如果此项通过，正常使用插件时 MCP 就能正常工作，无论 Preview 终结点的结果如何。
• 大多数环境的 Preview 终结点（/api/mcp_preview）预期会返回 403 Forbidden。 Preview 需为每个环境单独选择启用；如果你的环境未启用，Preview 检查就会始终失败。这不表示设置有问题。
• 在这种情况下，请忽略总体退出代码和 ⚠ Partial success 警告。 除非 /api/mcp 和 /api/mcp_preview 都通过，否则验证器会返回退出代码 1（失败）。由于大多数环境都未启用 Preview 终结点，即使 MCP 通过 GA 终结点完全正常运行，--validate 也会以 1 退出。请关注各终结点的结果，而不是汇总状态。
• 如果 GA 终结点（/api/mcp）失败： 这才是真正需要调查的信号 — 检查身份验证、租户许可、环境允许列表或终结点可访问性。

MCP 服务功能

关于 MCP 能做和不能做的事情（数据 CRUD + 最多 25 条的批量操作、创建表/列（包括 choice/lookup）、search/describe、上传/下载文件），以及 SDK / Web API 的相关信息，请参阅 overview 技能中的 Tool Capabilities 矩阵。

验证 MCP 正常运行后，告诉用户：

✅ 已连接到 {DATAVERSE_URL} 上的 Dataverse。工具已安装并完成身份验证，MCP 已就绪。

你现在可以：

• 创建表、列和关系（dv-metadata）
• 写入和导入数据（dv-data）
• 查询和分析数据（dv-query）
• 导出和升级解决方案（dv-solution）

要创建你的第一个解决方案，请参阅 dv-solution 技能。 要加载示例数据（客户、联系人、商机），请询问：“将演示数据加载到我的 Dataverse 环境中。”

---

支持的 Agent

安装为插件后，此插件的技能会由 GitHub Copilot CLI、Claude Code CLI、Gemini CLI 和 Antigravity CLI 原生加载。无需手动加载上下文。

PAC CLI 命令、Python 脚本和 XML 模板在各个宿主中均可正常使用。