migrate-webapi-selectall

插件检查：运行 node "${PLUGIN_ROOT}/scripts/check-version.js"——如果有消息输出，请在继续之前将其显示给用户。

迁移 Power Pages Web API 通配符

将每个已弃用的 Webapi/<table>/fields = * 值替换为经网站实际 Web API 行为证实的最小显式列集合。

由 LLM 负责发现源文件、推理调用链、确定字段、撰写报告和进行编辑。仅使用随附脚本检索权威 Dataverse 表架构；不得由该脚本决定代码需要哪些列。

支持以下两类网站：

• 非 SPA 网站，包含 HTML、JavaScript、Liquid、Web 模板和聚合 YAML；
• SPA 网站，包含 React、Vue、Angular、Astro、TypeScript、下载的部署 YAML 或混合自定义 JavaScript。

初始请求： $ARGUMENTS

不可妥协的规则

1. 审查所有已发现的源表 Web API 调用，包括共享封装、动态构建器和响应使用方。
2. 审查所有配置范围和部署配置文件副本。
3. 使用表架构将请求中的 EntitySetName 值映射到设置逻辑名称。绝不使用单数化、复数化或猜测。
4. 将 * 视为不支持读取、写入、聚合、FetchXML、文件和图像。
5. 在编辑任何内容之前，为每个通配符给出准确的拟议替代值。
6. 报告所有已有的显式 fields 设置，包括缺失的列和可能不必要的列。
7. 绝不执行不完整的通配符计划。先解决所有通配符和调用点行。
8. 报告中不得包含绝对本地路径、令牌、URL、数据值、筛选字面量、请求正文、响应正文和源代码片段；只能通过使用随附脚本渲染随附模板来生成报告。
9. 保留无关的 YAML 结构和值。
10. 使用全新的发现流程进行验证，不得依赖记忆中的清单。
11. 迁移输出目录中只能保留渲染后的报告及其图标。
12. 除非用户已明确确认环境、网站、网站类型、数据模型和部署配置文件，否则绝不下载或上传网站内容。两种传输都无法撤销。
13. 只有在获得明确批准后才能运行冒烟测试；绝不对已部署网站发起 POST、PATCH、PUT 或 DELETE Web API 调用。测试写入操作会破坏真实记录数据。

分析调用之前，请阅读 references/column-analysis.md。清点设置或撰写报告之前，请阅读 references/configuration-and-reporting.md。 进行任何下载或上传之前，请阅读 references/site-transfer.md。

阶段 1：准备

目标： 确认项目和网站，并保护现有工作。

1. 根据进度跟踪创建全部七项任务。
2. 从 $ARGUMENTS 或当前目录解析 PROJECT_ROOT。
3. 独立检测网站标记：
   • powerpages.config.json 表示这是 SPA 网站；
   • 根目录下的 website.yml、根目录下的 sitesetting.yml 或 .powerpages-site/ 表示这是已下载的非 SPA 资源；
   • 两者都出现时，扫描两种布局。
4. 如果存在 .solution-manifest.json，读取该文件。本次迁移会更改现有 设置；不要创建或选择其他解决方案。
5. 检查 git 状态。绝不丢弃、隐藏或纳入与本任务无关的用户更改。
6. 运行 node --version。
7. 确认可以读取 assets/migration-report-template.html 和 scripts/render-migration-report.js；如果任一文件缺失，则停止。
8. 阅读 references/site-transfer.md，然后 与用户确认环境、网站名称和 WebSiteId、网站类型、数据模型、部署配置文件和目标路径。逐一检查这些信息 是否与 pac auth who、pac env who 和 pac pages list 相符；有 任何不匹配时停止。绝不根据文件夹名称或当前活动的默认值进行推断。

分析错误的网站会导致自信地给出错误修复，因此在读取任何设置前，必须先确认网站身份。 只有在用户需要获取全新副本，或 PROJECT_ROOT 中没有网站内容时才下载；下载会替换本地文件，且无法撤销。

🚦 关卡（同意 · migrate-webapi-selectall:1.download-site）： 只有在显示已确认的环境、网站名称和 ID、网站类型、数据模型、目标路径及确切命令后，才能批准下载。取消后，本地内容保持不变，并继续使用现有副本。

使用 AskUserQuestion：下载已确认的网站 或 使用本地副本。 任何下载后都要重复步骤 3。

输出： 项目根目录、网站布局、解决方案上下文、git 状态、已确认的网站身份，以及获批后下载的副本。

阶段 2：构建完整清单

目标： 找出所有配置以及可能包含源 Web API 调用的位置，再开始分析列。

2.1 清点配置范围

使用 Glob、Grep 和 Read 检查：

• 每个 sitesetting.yml；
• 每个 *.sitesetting.yml；
• .powerpages-site/site-settings/；
• 部署配置文件和特定环境的副本。

记录每个 Webapi/<table>/fields 和 Webapi/<table>/enabled 条目，包括其相对文件、行号、范围、键样式和当前值。将 fields 设置分类为：

• wildcard；
• explicit；
• 对已启用表而言为 missing；
• 仅在同一配置范围内才算 duplicate。

不要将不同部署配置文件中的相同设置视为重复项。记录每个配置文件名称及其覆盖的设置。绝不假设 default 配置文件就是预期的部署配置文件。

每个唯一的表只查询一次 Dataverse，绝不针对每个配置文件分别查询。

2.2 清查源代码调用

仅分析权威且可编辑的源文件。切勿检查已编译或生成的代码。

对于 SPA 网站：

1. 在搜索调用之前，先阅读 powerpages.config.json、package.json 以及现有的框架或打包工具配置。
2. 将 compiledPath 和所有已配置的构建输出目录视为硬性排除项。
3. 排除 .powerpages-site/web-files/、node_modules/、覆盖率和缓存目录、源映射、压缩后的捆绑文件、框架输出目录，以及符合 <entry-name>-<content-hash>.<extension> 格式的内容哈希资源。
4. .powerpages-site/site-settings/ 仅用于配置清查，绝不可用于源代码分析。
5. 搜索可编辑的根目录，例如已配置的源代码目录和框架应用目录。

对于非 SPA 网站，搜索可编辑的 JavaScript、Liquid、Web 模板、Web 文件和其他编写的源代码。不要仅仅因为编写的非 SPA Web 文件会作为 Web 文件部署，就将其排除。

搜索以下源代码扩展名：.js、.jsx、.ts、.tsx、.vue、.html、.htm、.liquid、.aspx、.ascx、.cshtml 和 XML Web 模板。如果调用仅存在于已编译、压缩、生成或内容哈希输出中，请记录 missing-source 阻断项并停止迁移。不要根据这些输出推断列。

搜索以下内容：

• /_api/、编码变体、拆分的 URL 片段和 API 基础地址常量；
• fetch、Axios、XMLHttpRequest、jQuery AJAX、webapi.safeAjax、shell.ajaxSafePost 和自定义请求封装；
• 实体集常量、查询构造器、FetchXML 构造器和请求体构造器；
• 从其他文件导入的调用方和使用方。

对于每个源代码候选项，记录相对路径、行号、方法、端点表达式和封装链。注释、示例或非表端点也需要明确说明处置方式。绝不记录已排除的构建输出。

将设置清单写入 docs/webapi-selectall-migration/migration-report.json，并按照 references/configuration-and-reporting.md 中的说明生成报告草稿。 暂不提出字段。

如果任何范围内的源文件或配置文件无法读取，请停止。

🚦 关卡（计划 · migrate-webapi-selectall:2.confirm-scope）： 在检索架构之前，确认项目、配置范围和配置文件、通配符数量、显式设置数量以及源代码清单。取消后仅保留只读报告草稿。

使用 AskUserQuestion 确认或取消。如果用户指出其他源代码或部署范围，请扩展清单并重复此阶段。

Phase 3：检索架构并解析列

目标： 使用权威名称，同时让大模型判断实际用法。

3.1 仅检索相关表架构

构建初始去重列表，其中包含：

• 所有 Web API 设置中的逻辑表名称；
• 所有候选表调用中的实体集名称；
• 绑定目标或相关表调用中直接出现的实体集名称。

不要将导航属性名称视为表标识符。只有在关系元数据解析出其目标逻辑名称后，该名称才具有权威性。

从已确认的项目上下文或 pac env who 获取环境 URL。 如果无法获取，请将 URL 作为数据收集项进行询问；切勿索取或接受访问令牌。

将每个去重后的标识符各写一行，保存到 docs/webapi-selectall-migration/table-identifiers.txt。运行：

node "${PLUGIN_ROOT}/skills/migrate-webapi-selectall/scripts/query-table-schema.js" --project-root "<PROJECT_ROOT>" --environment-url "<ENVIRONMENT_URL>" --tables-file "<PROJECT_ROOT>/docs/webapi-selectall-migration/table-identifiers.txt" --output "<PROJECT_ROOT>/docs/webapi-selectall-migration/table-schema.json"

如果某个标识符无法解析，请追踪代码或获取正确的契约；不要猜测。

完成初始快照后：

1. 将每个使用到的 $expand 导航属性与其源表返回的关系元数据进行匹配。
2. 仅收集所有现有快照中尚未出现的目标逻辑名称。
3. 将这些名称写入 table-identifiers-pass-<N>.txt，并查询到 table-schema.pass-<N>.json。
4. 对嵌套扩展路径重复上述步骤，直到每个使用到的导航段都已解析。

将 table-schema.json 和所有编号快照视为一个架构包。 切勿重新查询该包中已有的逻辑表，也不要并发启动架构查询。

标识符列表和架构快照是工作文件。保留这些文件直至验证完成，然后在第 7 阶段删除。

3.2 分析每个调用及其使用方

对于源清单中的每一行：

1. 阅读完整的外层函数或模板块。
2. 追踪导入的包装器、URL 变量、查询构建器、请求体构建器、响应映射器、类型、组件、模板和每个调用方。
3. 跟踪条件分支、展开运算符、动态数组和运行时配置。
4. 使用架构包将实体集映射到逻辑表。
5. 应用 references/column-analysis.md 中的每条规则。
6. 按所属逻辑表记录所需内容，而非仅按请求记录。
7. 将该行归类为 mapped、non-table 或 not-a-call。
8. 如果任何运行时分支或使用方仍不明确，则将该行标记为未解决。

一个逻辑表通常会在多个位置被访问。提出字段前，应收集该表的所有调用点，包括重复或相互竞争的包装器、每页脚本、不同的查询形态，以及同一文件中的重复调用。已分析过的表，后续调用点仍可能增加列，因此切勿在遇到第一个调用点后就停止。

对于没有 $select 的普通记录 GET 请求，应根据所有使用方推导输出字段，并提出源代码修改建议，添加最精简的显式投影。筛选、排序和其他查询字段仍属于字段设置，即使不应将其加入输出投影。

将响应投影和字段设置允许列表分开维护。除非响应使用方也会读取某一列，否则切勿将仅用于筛选、排序、分组或写入的列添加到现有 $select 中。

3.3 构建配置提案

对于每项通配符设置：

1. 汇总适用站点行为中所有调用点到达该逻辑表时已证实的要求。

2. 根据架构包验证每个提议的名称。

3. 将每个提议的列关联到源文件路径和行号，或用户确认的外部契约。

4. 生成精确的替换内容：

   Webapi/<table>/fields = <column-name-1>,<column-name-2>,<column-name-3>
   

5. 如果提案为空或任何证据不完整，则将提案标记为未解决。

对于每项已明确配置的设置：

• 将已配置的列与已证实的必需列进行比较；
• 将其分类为精确、缺少必需列、可能范围过宽或有外部依据；
• 为每处差异提供精确的修复方案；
• 不得默默修改。

更新报告。继续之前，解决所有通配符和调用点对应的行。

输出： 证据完整的报告，其中包含精确的通配符替换内容和所有已明确配置的设置。

第 4 阶段：审查完整计划

目标： 在修改前展示完整的暴露面缩减计划。

展示：

• 发现的通配符问题及每项对应的精确替换内容；
• 每个提议列的证据；
• 需要添加 $select 的源 GET 请求；
• 已明确配置的设置，以及缺少或多余的列；
• 清查中发现的缺失或重复设置；
• 未解决的调用点为零。

🚦 关卡（同意 · migrate-webapi-selectall:4.apply-plan）： 批准所有通配符替换、必需的源投影、可选的明确设置强化以及本地编辑。取消将仅保留报告。

使用 AskUserQuestion，并提供以下选项：

• Apply all wildcard fixes and approved explicit fixes；
• Apply all wildcard fixes only；
• Cancel。

绝不提供只应用部分通配符修复的选项。

第 5 阶段：应用已批准的编辑

目标： 更新源投影和所有通配符设置。

1. 使用 Edit 添加已批准的 $select 投影。保留方法、筛选器、排序、展开、分页、编码、Liquid 表达式和错误处理。
2. 使用 Edit 替换每个范围和配置文件中的所有通配符值。保留标识符、键名、引号、缩进、注释和无关值。
3. 仅在所选批准方案中包含已明确配置设置的更改时，才应用这些更改。
4. 立即重新读取每个已更改的代码块，并更新报告状态。

如果任何编辑失败，或文件在审查后发生变化，请停止。不要继续应用不完整的配置集，也不要对用户的工作执行大范围回滚。

输出： 所有已批准的本地编辑和更新后的报告。

第 6 阶段：独立验证

目标： 不依赖先前的记录，证明迁移已完成。

1. 从头开始重复第 2 阶段的清查。
2. 确认每个配置范围中都不包含 Webapi/<table>/fields 通配符值。
3. 将每个迁移后的值与其已批准的精确替换内容进行比较。
4. 重新打开每个调用点并重新执行覆盖分析：
   • 映射的表和方法仍然正确；
   • 必需的设置列均已包含；
   • 普通记录 GET 请求使用明确的 $select；
   • 展开、查找、写入、FetchXML、文件和图像列仍然得到覆盖。
5. 对 SPA 站点运行现有项目构建。对于非 SPA 站点，检查已编辑的 JavaScript 和 Liquid 语法，并在有现成站点测试时运行这些测试。
6. 最终确定报告状态和每个条目的状态，然后删除先前的 migration-report.html，并根据更新后的数据文件重新生成该报告。

如果明确配置的设置仍存在差异，不得声称已完成全面强化。适用时，使用报告契约中定义的部分完成状态。

输出： 最终报告和经过验证的本地迁移。

最终站点完整性关卡

完成所有已批准的源代码编辑、独立验证和 SPA 构建后，运行：

node "${PLUGIN_ROOT}/scripts/validate-site-integrity.js" --projectRoot "<PROJECT_ROOT>"

在声称迁移已完成或提供部署之前，修复所有阻塞性错误。双向检查并报告审查结果，包括展开的内容。之后若有任何源代码变更，请重新运行此关卡。

阶段 7：部署并总结

目标： 仅发布已验证的更改。

在上传前立即与用户重新确认 references/site-transfer.md 中的每项身份详情，并显示确切的命令。选择用户审阅过的部署配置文件；只有用户明确指定时，才使用 default。更改环境、网站、数据模型或配置文件，都需要单独的部署审批。

🚦 Gate（最终 · migrate-webapi-selectall:7.deploy）： 批准针对所显示环境、网站、网站类型、数据模型和部署配置文件执行已验证的迁移。取消将保留本地编辑和最终报告，且不会更改线上网站。

使用 AskUserQuestion：Deploy now 或 Keep local only。

• 重新运行 pac auth who 和 pac env who，如有任何不匹配，立即停止。 pac pages upload-code-site 不接受 --environment，而是会上传到当前活动身份验证配置文件所报告的目标。
• 对于 SPA 网站，确认 .powerpages-site 包含已批准的配置编辑，运行现有的生产构建，然后运行 pac pages upload-code-site --rootPath "<PROJECT_ROOT>" --siteName "<SITE_NAME>"。
• 对于非 SPA 网站，运行 pac pages upload --path "<PROJECT_ROOT>" --environment "<ENVIRONMENT>" --modelVersion "<Standard|Enhanced>" --deploymentProfile "<PROFILE>"。

绝不能用一个上传命令替代另一个。每个命令都会破坏另一种网站类型，且无法撤销损坏。

部署后，列出冒烟测试会覆盖的读取路径：GET 调用、$select 投影、$expand、FetchXML 和聚合。绝不能未经提示就运行测试。

🚦 Gate（进度 · migrate-webapi-selectall:7.smoke-test）： 批准针对已部署网站执行所列的读取路径冒烟测试。取消将跳过测试，并报告该已部署迁移尚未验证。

使用 AskUserQuestion：Run the read-path smoke test 或 Skip verification。

绝不发起写入、文件或图像请求。请用户针对一次性记录自行测试这些路径。

将 HTTP 403 响应视为需要调查的证据，绝不能恢复 *。不得在先前审批下添加列。返回阶段 3，更新确切的计划和报告，重复阶段 4 的审批，在阶段 6 独立验证，并取得新的阶段 7 部署审批。

删除迁移过程中创建的所有工作文件，仅保留 docs/webapi-selectall-migration/migration-report.html 和渲染器放在其旁边的 power-pages-icon.png：

• table-identifiers.txt 和 table-identifiers-pass-<N>.txt；
• table-schema.json 和 table-schema.pass-<N>.json；
• migration-report.json。

仅删除本次迁移创建的文件，并确认目录中只有报告及其图标。返回较早阶段时跳过清理，并在该轮完成后删除重新生成的文件。

按照 ${PLUGIN_ROOT}/references/skill-tracking-reference.md 中的说明，使用 --skillName "MigrateWebapiSelectall" 记录使用情况。

总结通配符计数、明确审阅、源文件编辑、报告路径、验证、部署，以及每条未验证的路径。

进度跟踪

在第 1 阶段之前创建以下任务：

任务主题	进行中形式	描述
准备迁移项目	正在准备迁移项目	确认站点，然后解决布局和 git 状态
清点 Web API 用法	正在清点 Web API 用法	找出每个配置和源代码调用
确认实际列	正在确认实际列	获取架构并追踪每个使用方
审查迁移计划	正在审查迁移计划	提出准确的修复方案和证据
应用已批准的迁移	正在应用已批准的迁移	编辑投影和配置
验证迁移结果	正在验证迁移结果	重复发现、构建并完成报告
部署并总结	正在部署并总结	获得批准后发布并报告结果

开始任务时将其标记为 in_progress，完成时将其标记为 completed。

---

从第 1 阶段开始：准备。