erp-xpp

技能：财务与运营 X++ 开发

关键安全规则——请先阅读

1. 仅限 Windows。 pac tool xpp install 和 pac package compile --package-type erp 需要 Windows。不要虚构 Linux/macOS 或基于 SDK 的替代方案。
2. 在任何部署或 DB 同步之前确认目标。 显示 Dataverse 环境 URL，取得明确确认，然后运行 pac org who --environment <url>，并核对 Dataverse URL 以及关联的 ERP URL/版本。
3. 切勿假设使用 Full DB 同步。 虽然独立运行的 pac package db-sync 默认使用 Full，但当请求含糊时，必须让用户选择 Full、Module 或 Incremental。
4. 在 PAC 到达成功终态之前，切勿声称部署成功。 如果失败，请保留并报告异步操作 ID。
5. 不要覆盖现有模型或源文件。 在搭建脚手架或编辑之前，检查 .erp/xpp.json、描述符和目标元数据路径。
6. 在 ERP 验证之前固定每个运行时端点。 PAC 和 Dataverse CLI 有各自独立的活动配置文件。在进行任何 dataverse ... --target erp 检查之前，要求运行 dataverse auth who 和 dataverse org who --json，并确认结果与已确认的 Dataverse 和关联 ERP URL 一致。根据传输方式验证 ERP MCP：直接 HTTP 必须指向 <erp-url>/mcp；stdio 代理必须接收基础 <erp-url>，并将请求有效路由到 /mcp。选择配置文件不会重新指定现有 MCP 连接的目标。
7. 将运行时验证视为可能会修改数据的操作。 用户单独选择部署后验证后，检查 X++ 实现，说明确切的测试输入和预期变更，并就这些输入和影响取得确认。不要对非幂等操作套用通用测试矩阵。
8. ERP X++ 包部署后的所有额外验证都必须由用户选择。 在 pac package deploy --package-type erp 之后，记录 PAC 的终态结果，然后询问用户是否需要进一步验证，以及要运行哪些检查。除非用户选择，否则不要查询异步操作、执行 X++ 构件、查询其 ERP 实体或测试其安全性。进行运行时验证时，确认确切输入、成功标准和失败标准；切勿虚构值或执行未经批准的失败路径。此规则适用于 ERP X++ 包部署，不适用于 Dataverse 解决方案 ALM。

PAC CLI 是 X++ 生命周期的托管操作界面。不要用原始 Dataverse API、直接调用 ERP sidecar、LCS 上传自动化或手写编译器调用来替代这些命令。

对于仅限规划的 X++ 请求，可以加载技能并阅读本地参考资料；不要调用环境或写入本地文件。

意图路由

用户意图	操作
创建 ERP 包/模型	pac package init --package-type erp
为环境安装编译器元数据	pac tool xpp install
检查/移除本地 SDK	pac tool xpp list / pac tool xpp uninstall
编译或生成 X++	pac package compile --package-type erp
部署一个预构建 ZIP	pac package deploy --package-type erp --package <zip>
部署仓库中的所有模型	pac package deploy --package-type erp --solution-root <root>
仅运行 DB 同步	pac package db-sync
创建 ERP 自定义服务	编写其 X++ 类/契约以及 AxService 和 AxServiceGroup 元数据，然后编译并部署
创建 ERP ICustomAPI 操作	编写 ICustomAPI 类、操作菜单项以及特权/职责/角色安全配置，然后编译、部署；必要时执行 DB 同步，并通过 ERP MCP 验证
编写、编译、部署并验证	按照端到端工作流执行

不存在 pac package build 或顶层 pac xpp 命令。 对于 ERP，pac package compile --package-type erp 会编译标签和 X++、运行最佳实践检查，并生成可部署的托管 ZIP。

技能边界

需求	请改用
连接/身份验证、安装或更新 PAC CLI	dv-connect
读取或分析 ERP 业务数据	dv-query
创建/更新/删除 ERP 业务记录或导入 DMF 数据	dv-data
列出/取消 ERP 批处理作业	dv-admin
Dataverse 解决方案 ALM	dv-solution
ERP UI 个性化设置、工作流编辑或环境生命周期管理	Finance and Operations UI / Power Platform 管理工具；不在涵盖范围内

预检

1. 确认使用的是 Windows。
2. 运行 pac 并检查其横幅；pac --version 无效。这些命令要求 PAC CLI .NET 工具版本为 2.11.1 或更高。
3. 运行 pac package help 和 pac tool xpp help。如果缺少 compile、db-sync 或 tool xpp，请加载 dv-connect，并先更新到最新的 .NET 工具安装版本，再继续。
4. 执行环境操作前，运行：

pac auth list
pac org who --environment <dataverse-url>

输出必须标明已确认的 Dataverse 环境，并包含关联的 ERP URL/版本。请勿将 ERP URL 替代 --environment；PAC 接受 Dataverse URL 并解析其 ERP 关联信息。

5. 通过 Dataverse CLI 或 ERP MCP 进行运行时验证前，运行：

dataverse auth who
dataverse org who --json \
  --context "app=dataverse-skills/<ver>;skill=erp-xpp;agent=<agent>"

要求所选 CLI 配置文件的环境 URL 与返回的 erpUrl 均与上文确认的 PAC 目标一致。如果不一致，请运行 dataverse auth select --name <profile-name>，然后重新执行两项检查。在支持该选项的命令中传入 --environment <dataverse-url>，但绝不能将此选项视为选择正确配置文件的替代方案；某些 ERP 数据命令没有环境覆盖选项。

对于 ERP MCP 验证，请检查活动服务器配置。直接使用 HTTP 时，要求其指向已确认的 <erp-url>/mcp；使用 dataverse mcp 等 stdio 代理时，要求其接收已确认的基础 <erp-url>，并使用其有效的 /mcp 端点。如果不一致，请停止操作，并在发现或调用之前重新连接或重新初始化匹配的 ERP MCP 服务。

每次 MCP 运行时调用前，都要建立新的、特定于传输方式的会话，并通过 MCP 发起的身份/当前会话检查验证调用方。dataverse auth who 只能证明 CLI 身份。如果 MCP 无法证明其调用方身份，请勿通过该会话调用。对于安全验收，已验证的调用方必须是预期的非管理员测试用户。

6. 首次安装 SDK 前，请说明它会下载约 4 GB 的内容，并在 %LOCALAPPDATA%\Microsoft\Dynamics365\<version>\PackagesLocalDirectory 下展开至约 16 GB。

命令速查

# Scaffold one or more models
pac package init --outputDirectory <root> --package-type erp \
  --model <ModelA,ModelB> --publisher <publisher> --layer ISV

# SDK lifecycle
pac tool xpp install --environment <dataverse-url>
pac tool xpp list
pac tool xpp uninstall --version <four-part-version>

# Compile/build all configured models
pac package compile --solution-root <root> --package-type erp \
  --app-version <four-part-version> --language en-US

# Compile one model during the edit loop
pac package compile --solution-root <root> --package-type erp \
  --model <ModelName> --app-version <four-part-version> \
  --language en-US --incremental

# Deploy one compiled package, without DB sync
pac package deploy --environment <dataverse-url> --package-type erp \
  --package <root>/bin/<Model>_<version>_managed.zip \
  --build-type Full --release-type Dev --db-sync None \
  --logConsole --logFile <deployment-log-path>

# Deploy every model in .erp/xpp.json in dependency order
pac package deploy --environment <dataverse-url> --package-type erp \
  --solution-root <root> --build-type Full --release-type Dev \
  --db-sync None --logConsole --logFile <deployment-log-path>

自动化时请使用明确的值，不要依赖默认值。完整的参数表和 DB-sync 规则见 references/commands.md。

编写 X++ 源代码

仓库根目录包含 .erp/xpp.json；源代码默认位于 src/。每个模型都有描述符和元数据，位于：

<root>/
  .erp/xpp.json
  src/<Model>/Descriptor/<Model>.xml
  src/<Model>/<Model>/AxClass/<Class>.xml

请运行 pac package init，不要手动编写描述符/配置。检查现有路径后，再有针对性地添加元数据文件。PAC 会编译并打包编写的元数据；它不会搭建自定义服务、ICustomAPI 操作或数据实体。关于可运行类、标签、自定义服务、ICustomAPI 操作、公共 OData 数据实体和针对特定构件的验证，请参阅 references/authoring.md。

编译/构建规则

• 正常编译会依次执行标签编译 -> X++ 编译 -> 最佳实践检查 -> 生成可部署 ZIP。
• 仅在编辑迭代中使用 --incremental。最终部署前运行一次非增量编译。
• 除非用户明确要求且了解验证减少的影响，否则不要使用 --skip-bp。
• 如果安装了多个 SDK，请传入 --app-version；否则 PAC 可能会因选择不明确而拒绝执行。
• 即使 ZIP 已在之前的运行中生成，只要出现 Compile summary: ... failed 或任何非零退出码，都应视为失败。
• 确认输出 ZIP 是本次运行在 <root>/bin/ 下生成的。
• 如果标签编译报告 XPPLC2010，且 PAC 在 LabelC 以退出码 0 完成后仍失败，请添加有效的标签资源；不要删除日志或绕过该阶段。

部署和数据库同步规则

• 仅部署指 --db-sync None。
• --build-type 控制服务器如何应用包：Full、Incremental 或 Delete；它不是本地构建命令。
• --release-type Dev 是常规的测试/开发选项。请求数据库同步时，Release 会强制在服务器端执行完整数据库同步。
• Delete 会忽略数据库同步设置。
• 单包部署使用 --package <zip>。解决方案模式部署不传入 --package，而是读取 .erp/xpp.json，按拓扑顺序排列模型并进行部署，然后运行一次所请求的数据库同步。
• PAC 会在部署时将 fnomoduledefinition.json 注入 ZIP。如果必须保留不可变的校验和，请先复制构件。
• 独立数据库同步和带同步的部署是分别支持的工作流；切勿仅为了满足仅数据库同步的请求而重新部署。

有关仅编译、仅部署、仅数据库同步、多模型和完整生命周期的流程，请参阅 references/workflows.md。每次编译、部署、数据库同步和运行时验证时，都应遵循 references/validation.md 中的成功判定条件、诊断流程和错误映射。

端到端工作流

对于“进行此 X++ 更改并部署”：

1. 检查仓库并保留现有工作。
2. 在搭建新模型前，确认模型/类名称、发布者和层。
3. 仅当模型不存在时，运行 pac package init --package-type erp。
4. 添加或编辑请求的 X++ 元数据，例如类、契约、自定义服务、服务组、ICustomAPI 操作及其安全设置、公共数据实体，以及所需标签。
5. 确认/验证目标环境，并核实 ERP 关联/版本。
6. 安装或重复使用匹配的 SDK。
7. 进行非增量编译，并要求编译错误为零。除非用户接受，否则应处理最佳实践警告。
8. 使用明确的构建/发布/数据库同步模式进行部署。
9. 将 PAC 的退出代码、异步操作 ID、终止状态和数据库同步结果作为部署命令的一部分记录。不要自动运行其他验证。
10. 询问用户是否需要部署后验证，以及授权哪些检查：重新查询异步操作、API/操作发现、运行时行为、数据实体查询、多用例测试和/或安全验收。此前对部署的批准以及选择某项检查，不代表授权其他检查。
11. 如果用户拒绝所有验证，则报告 PAC 部署结果，并说明未执行其他验证。如果选择了运行时验证，则仅检查已部署的自定义构件及其契约，然后询问每项所需输入以及预期的成功和失败标准。重复提示中已有的确切值或标准以供确认；绝不虚构或扩大范围。
12. 对于已选择的运行时检查，将 Dataverse CLI 配置文件和特定传输方式的 ERP MCP 目标固定为已确认的环境，然后仅验证获批的构件：

• 可运行类：打开 https://<erp-host>/?mi=SysClassRunner&cls=<ClassName>。
• 自定义服务：在调用 erp:<ServiceGroup>/<Service>/<Operation> 前，检查 X++ 实现是否存在副作用；调用时使用 dataverse api invoke --target erp --context "app=dataverse-skills/<ver>;skill=erp-xpp;agent=<agent>"；仅使用 list/describe 进行发现。
• ICustomAPI 操作：如果选择了发现，则使用 ERP MCP api_find_actions 验证其操作菜单项和契约。如果选择了执行，则仅使用已确认源契约或获批的发现结果中的获批输入进行调用，然后将每个返回属性和预期变更与观察到的结果进行比较。
• 公共 OData 数据实体：如果选择了发现，则使用 dataverse data describe --target erp 检查。如果选择了查询执行，则使用 dataverse data query --target erp 查询已确认的实体集。为每条运行的命令添加 --context "app=dataverse-skills/<ver>;skill=erp-xpp;agent=<agent>"。
• 安全验收：仅当同时选择了运行时执行和安全验收时，才以分配了预期自定义角色的非管理员测试用户身份调用获批用例。管理员身份执行仅用于诊断，不能验证权限/职责/角色链。

13. 报告包路径、环境、异步操作 ID、终止状态、数据库同步模式、接受或拒绝的验证检查，以及仅针对实际执行的检查给出结果。

常见错误 — 请勿使用

错误	正确
pac xpp install	pac tool xpp install
pac xpp compile	pac package compile --package-type erp
pac package build	pac package compile --package-type erp
pac package deploy --package-type xpp	--package-type erp
将 ERP URL 传给 --environment	传入已关联的 Dataverse URL
单个 ZIP 未指定 --package	添加 --package <zip>
为整个仓库的部署添加 --package	省略它并使用 --solution-root
pac package db-sync --db-sync None	None 仅用于部署；独立模式为 Full、Module、Incremental
模块同步未指定 --modules	添加 --modules ModelA,ModelB
增量同步未指定 --argument-file	添加有效的 IncrementalSyncParameters JSON 文件