add-ai-webapi

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

添加 AI Web API

注意

AI 摘要 API 是一项预览功能。预览功能并非供生产环境使用，且功能可能受限。这些功能会在正式发布前提供，以便客户提前体验并提供反馈。

在阶段 1 期间以及阶段 8 的总结中，向用户原样显示此注意事项 — 复制上方完整的 **Note** 块（包括“正式发布前提供，以便客户提前体验并提供反馈”的表述）。不要将其改写成自己的“预览功能注意事项：……”句子；此措辞与 Microsoft Learn 的预览免责声明一致，改写会失去这种忠实度。

将 Power Pages 生成式 AI 摘要 API 集成到 SPA 网站中。此技能聚焦于 AI 层（第 3 层）：摘要服务代码和 Summarization/* 站点设置。底层 Web API 前置条件 — Webapi/<table>/enabled、Webapi/<table>/fields、表权限和 Web 角色 — 委托给 /integrate-webapi 和 /create-webroles，以便每一层都有唯一的信息来源。

涵盖的两个 API

#	API	URL	请求体	响应
1	Search Summary	POST /_api/search/v1.0/summary	{ userQuery }	{ Summary, Citations }
2	Data Summarization	POST /_api/summarization/data/v1.0/<entitySet>(<id>)?$select=...&$expand=...	{ InstructionIdentifier } 或 { RecommendationConfig }	{ Summary, Recommendations }

示例：Microsoft 在支持案例页面提供的 Copilot 摘要。 Data Summarization 可通过任意实体集、列和提示词组合调用，但 Microsoft 为标准 incident 表记录并提供了一种特定配置： POST /_api/summarization/data/v1.0/incidents(<caseId>)?$select=description,title&$expand=incident_adx_portalcomments($select=description) 请求体为 { "InstructionIdentifier": "Summarization/prompt/case_summary" }。Microsoft Learn 有时将其称为“案例页面 Copilot 预设”。应将其视为一种可选的 Data Summarization 配方——当用户明确希望复现 Microsoft 示例时很有用——而不是自动建议。自定义的类案例表（cr363_servicerequest、 adx_case），或基于不同要素（优先级、所有者、SLA 计时器）生成摘要的标准 incident 表，都只是使用制作者定义的值进行常规 Data Summarization 调用。

参考资料：${PLUGIN_ROOT}/skills/add-ai-webapi/references/ai-api-reference.md — API 规范、必需标头、站点设置名称、错误代码，以及文档中记录的支持案例示例。请在工作流开始时阅读此资料；如果用户询问最新信息，请使用 mcp__plugin_power-pages_microsoft-learn__microsoft_docs_fetch 获取 Microsoft Learn 源页面。

管理员治理层级：两个 API 都受三级管理员层级控制——租户 PowerShell 设置（enableGenerativeAIFeaturesForSiteUsers）、Copilot Hub 环境/站点治理，以及站点级制作者开关（对于 Search Summary：设置 工作区 → Copilot → 站点搜索（预览）→ 启用站点搜索生成式 AI（预览））。 每一级都会覆盖其下一级的设置，因此“制作者开关已开启，但 API 仍提示已禁用”确实可能发生——管理员级治理具有更高优先级。

两个端点呈现禁用状态的方式有所不同：

• Search Summary → HTTP 200，但响应中包含 { Code: 400, Message: "Gen AI Search is disabled." }。生成的 fetchSearchSummary 会检测到这一情况并抛出 SearchSummaryApiError；UI 会显示补救卡片。
• Data Summarization → HTTP 400，其中 error.code = 90041001（管理员级禁用）或 90041003（每站点设置 Summarization/Data/Enable=false）。

完整的故障排除清单（租户 → 环境 → 站点，以及运行时版本、Bing 依赖和跨区域数据移动）位于 references/ai-api-reference.md §1“故障排除：AI 功能似乎已禁用（管理员层级）”中——出现任一禁用状态时，请引导用户查看该资料。在第 7 阶段之前，明确向用户说明这一治理层级；并在第 8 阶段的摘要中再次说明。

内置搜索控件与自定义代码路径：如果站点使用 Microsoft 提供的 Power Pages 搜索控件，且只希望在该页面显示 AI 摘要搜索结果，则无需使用此技能——只需开启 Copilot 工作区开关并设置 Search/Summary/Title 内容片段。此技能适用于自行构建搜索 UI 的站点，或需要从自定义代码调用 /_api/search/v1.0/summary 的情况。请在第 1 阶段确认用户采用的是哪种路径。

核心原则

• 仅处理第 3 层，其余工作委派出去。 Web API 网站设置、表权限和 Web 角色都属于 /integrate-webapi 和 /create-webroles。此技能只创建摘要服务代码和 Summarization/* 网站设置，不做其他工作。
• 按顺序启动 Agent。 根据 plugins/power-pages/AGENTS.md，针对每个目标按顺序启动 ai-webapi-integration Agent（绝不并行）。首次调用会建立共享的摘要服务文件和 CSRF 辅助程序；后续调用会对其进行扩展。所有代码集成完成后，再单独运行 ai-webapi-settings-architect。
• 使用原始 fetch + CSRF。 每个摘要请求都必须附带 __RequestVerificationToken（来自 /_layout/tokenhtml）和 X-Requested-With: XMLHttpRequest。绝不通过 OData 封装层转发。
• 不需要时跳过 /integrate-webapi。 如果所有已确认目标都是 Search Summary（它没有按表配置的 Web API 前置要求），或者所有第 1/2 层前置条件都已存在于磁盘上，技能将从第 3 阶段直接进入第 5 阶段。
• 使用 TaskCreate/TaskUpdate — 开始前创建包含所有阶段的待办列表。
• 维护网站完整性。 添加或调整 AI 界面前，先阅读 ${PLUGIN_ROOT}/references/site-modification-integrity.md；本地化需覆盖标签、加载、空状态、错误、引用、建议和补救状态，且 UI 必须支持双向布局并能安全扩展。

前置条件：

• 通过 /create-site 创建的现有 Power Pages SPA 网站
• 已通过 /setup-datamodel 或手动设置 Dataverse 数据模型（表 + 列）——适用于任何数据摘要目标
• 网站必须至少部署过一次（.powerpages-site 文件夹必须存在），设置阶段才能进行

初始请求： $ARGUMENTS

---

工作流

（工作流下方的阶段标题保留技术名称“第 1+2 层 / 第 3 层”，因为它们描述运行时分层，也是维护人员用于搜索的术语。此处的标题与面向用户的任务列表一致。）

1. 检查网站是否就绪 — 定位项目、检测框架、检查数据模型、部署状态和 Web 角色是否存在。
2. 确定 AI 摘要的适用场景 — 扫描代码，寻找搜索/数据摘要候选项。
3. 确认要添加的内容 — 查看清单，并选择要集成的 API/目标。
4. 为 AI 设置数据访问 — 如有需要，调用 /create-webroles，然后以仅限 AI 的读取模式为数据/案例目标调用 /integrate-webapi。仅搜索场景或前置条件已满足时，完全跳过此步骤。
5. 添加 AI 摘要代码 — 针对每个目标按顺序调用 ai-webapi-integration Agent。
6. 注册 AI 提示词 — 调用 ai-webapi-settings-architect Agent。
7. 验证所有内容 — 检查标头约定、搜索 $select、运行 npm run build 和验证脚本。
8. 审查并部署 — 记录技能使用情况、总结，并提供 /deploy-site 选项。

---

迭代模式（首次运行后）

此技能是一个一次性设置技能——用户首次请求集成摘要 API 时，才会端到端运行阶段 1–8。AI 界面一旦就绪（服务文件、框架封装、UI 调用位置和所有 Summarization/* 设置均已存在），后续调整已渲染 UI 的请求（颜色、间距、文案、移动按钮、更改空状态消息、在钩子中接入第二条推荐等）都不是重新进入此技能并再次运行所有阶段的理由。这样做会触发完整的 pac pages upload-code-site，并为每次调整生成一连串 git commit，而这正是上述阶段 5.5 / 6.4 提示要避免的繁琐节奏。

用户要求调整已集成的 AI 界面时：

• 编辑文件并在本地运行 npm run build，验证调整可以编译。这就是 UI 调整所需的全部验证流程。
• 不要自动运行 pac pages upload-code-site。 应在会话结束时、用户完成所有调整后再上传一次。
• 不要自动执行 git commit。 让用户将相关调整合并为一个提交。
• 用户表示已完成（或你已完成最后一项请求的调整）后，通过一个会话结束提示，批量进行部署和提交。

🚦 关卡（征得同意 · add-ai-webapi:iter.deploy-commit）： 迭代结束时，批量提示部署和提交——避免每次微调都上传和提交的繁琐节奏。

触发条件： 用户表示本次会话的 UI 调整已完成。 询问原因： 每次微小编辑后都自动部署或提交，会导致每次调整都执行一次 git commit 和一次 pac pages upload-code-site；批量处理能让历史记录更清晰，并避免重复部署。 取消后的结果： 无——源文件已编辑；未执行部署或提交。

使用 AskUserQuestion：

问题	标题	选项
所有 UI 调整看起来都不错。现在部署网站并提交更改吗？	部署并提交	是，部署并提交（推荐）；只提交——我稍后部署；只部署——我稍后提交；都不做——我会自行处理

仅当用户要添加一个新的 AI 界面（新页面、新表格或第二个 API）时，才重新运行完整技能流程。如果不确定某个请求是微调还是新增界面，请提问。

---

阶段 1：确认网站存在

目标：定位 Power Pages 项目根目录并确认前置条件。

1.0 检测迭代模式（先执行此步骤）

首先检测是否为重新进入，因为本技能其余部分都假定这是首次设置。 捕获有关项目状态的两个信号：

1. 服务信号：存在摘要服务 — src/services/aiSummaryService.*，或 src/ 下包含 /_api/search/v1.0/summary 或 /_api/summarization/data/v1.0/ 的任何源文件。存在此信号时，还要记录服务代码引用了哪些 API 接口 — 仅搜索、仅数据，或两者都有。此子分类对后续步骤很重要。
2. 设置项信号：至少存在一个第 3 层站点设置项，位于 .powerpages-site/site-settings/Summarization-*.sitesetting.yml。

然后根据组合情况继续：

• 两个信号都存在 → 重新进入。之前的 /add-ai-webapi 运行已端到端完成。显示下方的迭代模式提示。
• 存在服务信号，且现有服务代码仅支持搜索（引用了 /_api/search/v1.0/summary，但没有引用 /_api/summarization/data/v1.0/）→ 重新进入。仅支持搜索的站点可能没有 Summarization/* 设置项（搜索摘要使用工作区开关，而非逐次调用的设置项），因此缺少设置项信号属于正常状态，并不表示运行失败。显示下方的迭代模式提示。
• 存在服务信号，且现有服务代码包含数据摘要，但缺少设置项信号 → 首次运行进行中（之前的尝试在第 6 阶段完成前失败）。继续完整流程，无需提示。
• 两个信号都不存在 → 首次运行。继续执行第 1.1 阶段。

进入迭代模式分支时，询问：

问题	标题	选项
看起来此站点已接入 AI 摘要功能。此次请求是要调整现有功能，还是添加全新的功能入口（新页面、新表、第二个 API）？	模式	调整现有功能（推荐用于视觉或文案修改），添加新功能入口（再次运行完整技能），不确定 — 展示当前已接入的内容

• 调整现有功能：停止运行此技能。切换到上文迭代模式部分所述的工作流 — 编辑 + npm run build，不自动运行 upload-code-site，不自动提交，并在会话结束时集中询问是否部署和提交。
• 添加新功能入口：继续执行第 1.1 阶段（完整流程）。后续阶段会检测现有基础设施（CSRF 助手、摘要服务、设置项），并在其基础上扩展，而不是重复创建。
• 不确定 — 展示当前已接入的内容：列出现有服务文件、已接入的 UI 组件和 Summarization/* 设置项，然后再次询问同一问题。

1.1 创建待办列表

通过 TaskCreate 预先创建全部 8 个阶段的任务 — 参见进度跟踪。

1.2 定位项目

在当前目录或其直接子目录中查找 powerpages.config.json。

如果未找到：告知用户先通过 /create-site 创建站点。

1.3 检测框架

读取 package.json 并检测 React / Vue / Angular / Astro。参见 ${PLUGIN_ROOT}/references/framework-conventions.md。

1.4 检查数据模型

查找 .datamodel-manifest.json。如果找到，则读取 — 其中列出的表是数据摘要 API 的候选对象。标准的 incident 表与其他表一样都是候选对象；不要对其区别处理。

1.5 检查部署状态 — 硬性前提

查找 .powerpages-site。第 4 阶段（/integrate-webapi）和第 6 阶段（ai-webapi-settings-architect） 都要求此文件夹存在。将部署推迟到稍后并非可行的变通方案： 第 5 阶段写入 AI 调用服务代码后，如果尚未将第 1/2/3 层设置写入磁盘就部署网站，将会发布运行时故障代码（每次摘要调用都会返回 403/500，直到第二次部署完成）。最稳妥的顺序是在任何 AI 代码 生成之前，先部署干净的脚手架。

如果 .powerpages-site 不存在：

问题	标题	选项
未找到 .powerpages-site。AI 摘要技能需要先至少部署一次网站，才能配置权限和设置。现在部署干净的脚手架（尚无 AI 代码，可确保中间状态安全），还是停止并先自行运行 /deploy-site？	引导部署	是，现在部署脚手架（推荐），停止 — 我会先部署，然后重新运行 /add-ai-webapi

选择是：调用 Skill 工具执行 power-pages:deploy-site，并等待完成。然后 再次检查 .powerpages-site 是否存在。如果子技能返回后该文件夹仍不存在 （部署中途失败、用户取消，或上传已完成但未创建本地文件夹），请在此处停止并给出清晰的说明——原样呈现 deploy-site 的结果，方便用户排查，并告知他们重新运行 /deploy-site，然后再运行 /add-ai-webapi。请勿悄悄进入第 2 阶段；后续子技能需要此文件夹。

选择停止：结束此技能，并清楚说明下一步操作（“运行 /deploy-site，然后重新调用 /add-ai-webapi 以继续”）。请勿继续进入第 2 阶段——后续子技能无法运行。

1.6 检查 Web 角色

查找 .powerpages-site/web-roles/*.yml。记录是否存在任何角色——第 4 阶段的 委派要求至少有一个角色，/integrate-webapi 才能创建表权限。

输出：已确认的项目根目录、框架、数据模型可用性、部署状态、Web 角色清单。

阶段 2：探索 AI 集成点

目标：找出两个 API 的所有候选项，范围仅限 AI。

完整的 Explore Agent 提示词正文、清单格式和委派决策规则位于 ${PLUGIN_ROOT}/skills/add-ai-webapi/references/explore-prompt.md。请先阅读该文件， 然后调用 Explore Agent（通过 Task，设置 subagent_type: "Explore"， 详尽程度设为 medium），并逐字传递提示词正文。

Explore Agent 返回的内容（摘要——准确提示词请参阅参考文件）：

• 预留槽位标记（POWERPAGES:AI-SLOT kind=<pick>）——由 /create-site 放置的权威位置提示； 孤立标记会被标出，留待阶段 3 处理。
• 搜索摘要候选项，包括详情页上的相关记录发现目标 （“推荐的知识库文章”“相似案例”）。
• 数据摘要候选项，分类为 single-record / list / intent-mismatch， 每项包含现有 fetch 的 OData 查询和范围分类 （matches-existing-fetch / scope-extends-beyond-existing-fetch / needs-definition / intent-mismatch）。
• 现有基础设施——CSRF helper、powerPagesApi.ts、以往的 aiSummaryService.*。
• 每个数据摘要目标及每个 $expand 目标的 第 1/2 层状态—— ready / missing / n/a (search)。
• 字段列表范围提示——对于第 1/2 层状态为 ready、但现有 Webapi/<table>/fields 范围超出 AI 界面所需字段的行（包括主键、未被 @odata.bind 使用的关系导航属性、未使用的列），标记为 fields-broader-than-ai-mode，以便阶段 3 展示。
• 每个数据摘要目标的 第 3 层状态——Summarization/Data/Enable 以及代码将发送的特定 Summarization/prompt/<id>。

根据 Agent 的输出编制集成清单（每个候选项占一行，列为： #、API、Target file、Target kind、Entity Set、$select / $expand、Source、 Layer 1/2 status、Layer 3 status）——参考文件中包含一个完整示例。

委派决策（直接根据状态列计算）：

• 运行 /integrate-webapi？→ 如果任一行的第 1/2 层状态为 missing，则为 True。仅在 tables= 哨兵中传入状态为 missing 的行；不要重新审查已确认的表。
• 运行 ai-webapi-settings-architect？→ 如果任一行的第 3 层状态为 missing，则为 True。

输出：集成清单 + 委派决策 + 现有基础设施报告 + fields-broader-than-ai-mode 提示列表（如有）。

---

阶段 3：审查 AI 计划

目标：展示清单，并确认要集成哪些 API / 目标。

向用户展示：

1. 找到的 API 和目标列表。
2. 对于每一项：引用它的文件，以及服务将执行的操作。
3. 阶段 2 的两项委派决策（“将针对 [tables] 调用 /integrate-webapi”， “将为第 3 层调用 ai-webapi-settings-architect”）。
4. 现有基础设施说明（复用 CSRF helper、powerPagesApi.ts、之前的 aiSummaryService.*）。

审批节奏（提前说明预期）

在提出集成问题前，先简要告知用户还会有多少个决策点，这样“单次运行”就不会让人意外。从 关键决策点列表中计算，并减去本次运行不适用的决策点：

• 仅搜索的运行：跳过 /integrate-webapi 委派（阶段 4）和设置架构师（阶段 6）——此后还会暂停 4–5 次。
• 第 1/2 层已就绪：跳过阶段 4.3 的架构师审批。
• 没有列表／范围扩展／意图不匹配的行：跳过每个目标在阶段 3 的后续确认。
• 首次运行且所有分支都触发：此后还会暂停 7–10 次（Web 角色选择、逐个目标确认列表触发和范围、两份 integrate-webapi 架构师方案、AI 设置架构师方案、两次提交提示、最终部署）。

将其表达为事先告知，而非警告——例如：“在这次之后，我还会暂停约 6 次征求你的意见（Web 角色选择、两份架构师方案、两次提交提示、最终部署）。如果有列表目标需要决定触发条件或范围，可能还会多几次。”

集成问题

使用 AskUserQuestion，并根据阶段 2 清单动态构建选项列表——如果只有一个类别有候选项，就不要硬编码“搜索摘要和数据汇总”。根据找到的内容构建问题文本：

• 如果两个类别都有候选项：“我找到了搜索摘要和数据汇总的候选项。你想集成哪些？”
• 如果只有一个类别且只有一个目标：跳过“全部集成”——只需确认该目标（“要将搜索摘要接入 <page> 吗？”）。

默认选项列表中，仅在对应类别存在候选项时才显示相应行：

选项	包含条件
全部集成（推荐）	两个类别都存在
仅搜索摘要	存在搜索候选项 AND 存在数据汇总候选项
仅数据汇总	存在数据汇总候选项 AND 存在搜索候选项
让我选择具体项目	始终显示（多目标运行）
都不选——取消	始终显示

如果用户选择“让我选择具体项目”，则提出后续多选问题，列出集成清单中的每一行。如果阶段 2 将某个详情页候选项标记为相关记录发现目标，则应将其作为单独选项列出（即使同一页面也有数据汇总选项），让用户能有意识地选择基于 AI 的方案，而非手写 OData 匹配——例如：

• CaseDetail.tsx 上的搜索摘要（通过生成式 AI 查找相关知识库文章）
• ProductDetail.tsx 上的搜索摘要（通过生成式 AI 查找相关产品）

选项标签应注明页面名称和产生的结果，而不只是“搜索摘要”，让用户清楚地看到 AI 功能会出现在哪里。

按目标提出后续问题

用户确认目标后，仅在需要时针对每个目标提出后续问题：

• 列表触发方式——每个列表目标都要询问“打开时加载”还是“手动按钮”。
• 范围确认——仅当 Phase 2 将该行标记为 scope-extends-beyond-existing-fetch、 needs-definition 或 intent-mismatch 时才需要。先解决 intent-mismatch，因为 选定的目标类型决定接下来应询问哪种范围问题（LIST 或 SINGLE-RECORD）。

问题文本、选项列表以及范围分类到问题的映射位于 ${PLUGIN_ROOT}/skills/add-ai-webapi/references/scope-classification.md。任何目标需要后续问题时，都要读取该文件。

所选值将传入 Phase 5 的 Agent 调用提示词，作为 Scope for the summary call 区块（$filter、$orderby、Scope source、Target's existing list fetch）。目标组件上现有的 UI 获取逻辑保持不变——摘要 URL 是新增内容，绝不替代现有逻辑。

如果用户选择的范围会添加新的 $expand 目标（例如“包含其明细行”），请重新评估 Phase 2 的 Layer 1/2 委派决策——新增的扩展是一项新的前提条件（启用 Web API + 对子表的父范围权限）。

处理“None — cancel”

当用户选择 None — cancel 时：

1. 将剩余任务标记为 completed，并在 activeForm 中添加 (skipped — cancelled by user) 后缀， 让任务列表保持整洁，而不是让任务停留在 pending 状态。
2. 直接跳转到 Phase 8.1（使用 --skillName "AddAiWebapi" 记录技能使用情况，并将结果设为 cancelled）以及 Phase 8.2（提供一行摘要：“未进行任何更改——你在计划审查步骤取消了操作”）。
3. 完全跳过 Phases 4、5、6、7 和 8.3。不要调用 /integrate-webapi、 ai-webapi-integration、ai-webapi-settings-architect 或 /deploy-site。不要提交更改。

输出：用户确认的集成清单，或干净地取消操作。

---

Phase 4：委派 Layer 1 + Layer 2

目标：通过委派给 /create-webroles 和 /integrate-webapi（仅 AI 读取模式），而不是直接编写 Layer 1/2 文件，确保 AI 目标表的所有 Web API 前提条件均已满足。

4.1 跳过检查

符合以下任一条件时，跳过整个阶段：

• 所有已确认的目标都是 Search Summary（搜索没有按表设置的 Web API 前提条件）。
• Phase 2 的委派决策为“运行 /integrate-webapi？否”——此前的运行已将所有 Layer 1/2 前提条件写入磁盘。
• .powerpages-site 不存在（这两个子技能都需要该目录）。

若跳过，则继续 Phase 5，并在最终摘要中说明这一点。

4.2 创建缺失的 Web 角色（如有需要）

根据 Phase 1.6：如果 .powerpages-site/web-roles/ 中不存在 Web 角色，或者现有角色 与站点的身份验证模型不匹配，请询问用户：

问题	标题	选项
/integrate-webapi 至少需要一个 Web 角色来关联表权限。未找到匹配的角色。现在通过 /create-webroles 创建一个吗？	Web 角色	是，通过 /create-webroles 创建（推荐），跳过 — 我会单独处理角色

选择 是：使用提示词调用 Skill 工具，执行 power-pages:create-webroles，并在提示词中 包含调用方抑制哨兵，确保子技能不会发出自己的部署提示（由编排器统一决定是否在运行结束时部署）：

[CALLED-BY-PARENT-SKILL] caller=add-ai-webapi

为此 Power Pages SPA 站点创建 Web 角色。父技能 /add-ai-webapi 随后会将仅限 AI 读取模式的表权限 关联到你创建的角色。不要发出立即部署提示 — 编排器会在最后统一安排部署。

等待其完成。然后在继续 4.3 之前，重新检查 .powerpages-site/web-roles/。

选择 跳过：这会使本次运行进入已知会出错的路径 — 在用户手动创建 Web 角色和表权限之前，AI 端点在 运行时会返回 403。不要悄然继续。

🚦 关卡（同意 · add-ai-webapi:4.2.skip-webrole）： 在没有 Web 角色的情况下继续之前，必须获得明确确认 — 跳过会导致运行时的 Layer 1/2 无法正常工作。

触发条件： 用户在创建 Web 角色的选项中选择了“跳过”。 询问原因： 悄然继续会导致 AI API 端点在运行时返回 403；说明这一取舍，让用户能够在停止或继续之间做出知情选择。 取消后状态： 无任何变更 — 尚未写入代码。

通过第二个 AskUserQuestion 确认这一取舍：

问题	标题	选项
没有 Web 角色，我就无法设置表权限，因此在你自行配置之前，AI 端点在运行时会返回 403。要现在停止，以便先运行 /create-webroles，还是继续编写前端代码，并让我在最终摘要中标出这个缺口？	继续？	在此停止（推荐），继续 — 仅编写前端代码，并在摘要中标出缺口

选择 在此停止：干净地结束该技能。告知用户先运行 /create-webroles（也可以同时运行 /integrate-webapi），然后重新调用 /add-ai-webapi。

选择 继续：跳过 Phase 4 的其余部分（/integrate-webapi 委派需要 Web 角色来关联权限，因此运行 4.3 会失败），并跳转到 Phase 5。在 Phase 8 摘要中，明确标出 Layer 1/2 的缺口 — 列出用户仍需创建的确切文件 （Webapi/<table>/enabled、Webapi/<table>/fields，以及每个目标对应的表权限），以便最终消息清楚说明如何让运行时正常工作。

4.3 以仅限 AI 的只读模式调用 /integrate-webapi

根据 Phase 2 清单构建哨兵参数：

• primary=<primary table logical name>（正在汇总其记录 / 集合的表 — 例如，incident、cr4fc_product、cr363_workorder）
• tables=<primary plus every $expand target, comma-separated>
• expand-targets=<every $expand target, comma-separated; empty for pure data-summary targets with no $expand>
• caller=add-ai-webapi

使用单个提示词调用 power-pages:integrate-webapi 的 Skill 工具：

[AI-READ-ONLY] mode=ai-read-only primary=<primary> tables=<list> expand-targets=<list> caller=add-ai-webapi

为以下 Power Pages AI 汇总目标配置 Layer 1/2（Web API 站点设置 + 表权限）：

。这是只读集成 — /_api/summarization/data/v1.0/ 端点绝不会修改 Dataverse。请在所有 Web API 站点设置、表权限和共享的 powerPagesApi.ts 客户端都已写入磁盘后返回。

根据仅限 AI 的只读模式约定（你的 SKILL.md Phase 1.6）：

• 不要提交。 跳过 Phase 4.4 和 Phase 6.5 — 打印你原本会提交的文件列表，以便此编排器稍后暂存。父技能会批量提交。
• 不要部署。 跳过 Phase 6.1 部署询问、Phase 7.3 部署询问和 Phase 7.4 部署后说明。返回 Phase 7.2 摘要后停止。父技能负责在整个编排结束时统一部署。

/integrate-webapi 会检测 [AI-READ-ONLY] 哨兵（其 Phase 1.6），并通过强化后的提示词运行完整流程：只读表权限、最少字段列表（不含 PK，仅包含查找列的 _<col>_value）以及只读服务层。它仍会针对每位架构师向用户显示计划模式审批提示 — 此技能不会抑制这些提示。

等待 /integrate-webapi 完成。重新检查文件系统：

• src/shared/powerPagesApi.ts 存在
• 对于每个目标表：Webapi/<table>/enabled 存在，Webapi/<table>/fields 存在
• 对于每个目标表：至少存在一个 read: true 的表权限；每个 $expand 目标都存在 Parent 范围权限

如果仍缺少任何先决条件，请在继续之前告知用户 — 受委派的流程可能有某个环节未完成（例如，用户拒绝了架构师的计划）。不要在此处悄悄改为编写 Layer 1/2 文件。

输出：Layer 1/2 先决条件已写入磁盘；共享的 powerPagesApi.ts 和只读服务已存在；Web 角色已存在。

---

Phase 5：实现 Layer 3 代码

目标：创建 AI 汇总服务，并将其接入每个目标的 UI。

5.1 调用 ai-webapi-integration Agent — 第一个目标（顺序执行）

对于已确认清单中的第一个目标，通过 Task 调用 ${PLUGIN_ROOT}/agents/ai-webapi-integration.md 中的 Agent。完整提示词模板 — 包含 Agent 需要的每个字段，以及每个值由哪个编排阶段解析的说明 — 位于 ${PLUGIN_ROOT}/skills/add-ai-webapi/references/agent-invocation-prompt.md。读取该文件，复制模板，将每个 <…> 占位符替换为当前目标对应的具体值，然后通过 Task 传递。Agent 不会解析占位符；传入字面文本 <search | data> 会使其困惑。

首次调用需顺序执行，因为它会建立共享的汇总服务文件（src/services/aiSummaryService.*）以及后续目标会复用的 CSRF 辅助函数。Agent 会返回结构化的文件修改列表（见其“Return value”部分）；请记录该列表，以供 Phase 5.5 按文件提交。

5.2 验证服务 + CSRF 辅助函数是否存在

启动更多 Agent 之前，验证：

• 汇总服务文件存在（默认路径为 src/services/aiSummaryService.ts）。
• 代码库中只定义了一次 getCsrfToken（或从现有辅助函数导入）。

5.3 依次为剩余目标调用 Agent

根据 plugins/power-pages/AGENTS.md，启动 Agent 必须依次进行。对每个剩余目标调用一次 ai-webapi-integration，等待每次调用完成后再开始下一次。每个目标只会添加一个独立的导出函数、一个框架封装器（如尚不存在）并连接一个 UI 文件——不会发生合并冲突，但依次执行可以简化故障排查。

如果总共只有一个目标，请跳过 5.3。

5.4 替换占位 POST 请求

对于探索 Agent 在阶段 2 中标记的任何占位 InstructionIdentifier 请求体，子 Agent 应已将其替换。通过在受影响的文件中搜索 InstructionIdentifier 并确认每个已解析的调用都使用真实的实体集和 ID 来进行验证。

5.5 提出提交请求

不要自动提交——在迭代运行中，未经询问就执行 git commit 会为实际上属于同一组更改的内容生成一串冗余提交。

🚦 关卡（征求同意 · add-ai-webapi:5.5.commit）： 阶段 5 的摘要服务和 UI 连接全部完成后，明确询问是否提交。

触发条件： 所有阶段 5 目标均已完成连接（服务、框架封装器、UI 调用点）。 询问原因： 每次集成运行都自动提交会产生每次微调对应一个提交的冗余历史；让用户批量提交更安全。 取消后状态： 无——源文件已写入；未执行 git commit。

使用 AskUserQuestion：

问题	标题	选项
现在提交这些第 3 层集成更改吗？	提交	是，现在提交（推荐），跳过——我稍后提交

选择是时：仅暂存阶段 5 期间修改的文件——摘要服务、框架封装器、每个已连接的 UI 页面，以及 Agent 生成的任何安全 Markdown 渲染器组件。编排器已从每次 ai-webapi-integration 调用的文件修改报告中获得此列表。对每个文件使用显式的 git add <path>；不要使用 git add -A——否则 src/ 中无关的进行中工作也可能被纳入提交。将提交消息中的 <targets> 替换为简短易懂的列表（例如 CaseDetail and SearchResults，或目标较多时使用 3 pages）：

git add <each file modified by the Phase 5 agents>
git commit -m "Add AI summarization integration for <targets>"

选择跳过时：继续而不提交。用户将在最后自行批量提交。

输出：为每个已确认目标创建摘要服务、框架封装器和 UI 调用点。

---

阶段 6：配置第 3 层设置

目标：通过 ai-webapi-settings-architect Agent 注册 Summarization/* 站点设置。

6.1 跳过检查

同时满足以下条件时，跳过此阶段：

• 每个已确认目标都是搜索摘要（搜索没有针对每次调用的 Summarization/* 站点设置； 参见 ai-api-reference.md）。
• 阶段 3 中没有添加数据摘要目标。

如果仅涉及搜索，请提醒用户在部署后，在站点的 Copilot 工作区中启用带生成式 AI 的站点搜索（预览版），然后继续阶段 7。

6.2 确认部署前提仍然满足

阶段 1.5 已检查 .powerpages-site 是否存在。请在此处再次检查以作保障——如果该目录在阶段 1 之后消失（虽然罕见，但如果用户手动清理了该目录，就有可能发生），请停止并重新运行阶段 1.5 的 bootstrap-deploy 提示。不要在目录缺失时悄然继续调用架构师 Agent。

6.3 调用 ai-webapi-settings-architect

通过 Task 调用 Agent：${PLUGIN_ROOT}/agents/ai-webapi-settings-architect.md：

“分析此 Power Pages SPA 站点，并提出生成式 AI 摘要站点设置。 第 5 阶段已集成以下数据摘要目标：[列出每个目标及其实体集、每个目标的 InstructionIdentifier 值和目标类型（single-record 或 list）——架构师需要这些信息来决定 Summarization/Data/ContentSizeLimit 的设置值]。 如果任何目标的类型是 list，计划 MUST 包含 Summarization/Data/ContentSizeLimit=200000——服务器默认的 100k 会静默截断列表内容；这一点不可妥协。 检查是否已有 Summarization/* 设置。第 1 层（Webapi/<table>/*）和第 2 层（表权限）已在第 4 阶段通过 /integrate-webapi 以仅 AI 读取模式配置——请验证它们存在于磁盘上，并在计划的先决条件表中注明已满足。通过计划模式提出 AI 计划，并在获批后使用 create-site-setting.js 创建 YAML 文件。”

等待 Agent 完成。如果它报告缺少第 1 层或第 2 层先决条件，说明第 4 阶段未成功完成——读取文件系统，找出缺漏并告知用户，不要尝试在此处创建第 1 层或第 2 层文件。

6.4 提议提交

🚦 关卡（同意 · add-ai-webapi:6.4.commit）： 架构师创建 Summarization/* 站点设置后，明确询问是否提交。

触发条件： ai-webapi-settings-architect 已写入所有 Summarization/Data/Enable + Summarization/prompt/<id> YAML 文件。 询问原因： 自动提交可能会把已有的未提交 YAML 文件一并纳入提交；征求明确同意可确保提交范围仅包含架构师的输出。 取消后的状态： 不做任何更改——YAML 文件已写入磁盘；不会执行 git commit。

使用 AskUserQuestion：

问题	标题	选项
提交新的 Summarization/* 站点设置吗？	提交	是，现在提交（推荐），跳过——我稍后提交

选择是：仅暂存架构师刚创建的文件——使用 ai-webapi-settings-architect 返回的 filePath 列表（或每次调用 create-site-setting.js 时打印的单个文件路径），不要使用 glob。glob 可能会扫入因无关原因而处于未提交状态的既有 Summarization-* YAML 文件（例如之前运行未完成的文件，或由 maker 编辑过的提示词），导致它们被意外纳入提交。

对每个文件使用显式的 git add <path>：

git add <each Summarization-*.sitesetting.yml the architect just wrote>
git commit -m "Add AI summarization site settings"

选择跳过：继续操作，不提交。

输出：已创建 Summarization/Data/Enable、Summarization/prompt/<id> 设置。

---

第 7 阶段：验证

目标：确认所有预期文件都存在、所有 POST 请求都设置了两个必需标头，并且项目可以成功构建。

预览功能提醒。 构建成功并不意味着 API 在运行时会返回摘要——管理员级治理设置（租户 PowerShell、Copilot Hub）或站点级 Search Summary maker 开关仍可能阻止该功能。请参阅此技能顶部的预览功能说明，以及 references/ai-api-reference.md §1“故障排查：AI 功能似乎已禁用”中的管理员层级检查清单。现在就告知用户，避免部署后的测试结果令其意外。

7.1 文件清单

对于每个已确认的目标，请确认：

• 服务文件：src/services/aiSummaryService.ts（或符合项目惯例的等效文件）包含预期导出的函数（fetchSearchSummary 或 fetchDataSummary；如果用户选择了支持案例场景，Agent 也可以生成一个轻量包装函数，例如 fetchCaseSummary）。
• 框架包装器（非 Astro）：src/hooks/ 中的 React hook、src/composables/ 中的 Vue composable，或 src/app/services/ 中的 Angular 服务。
• UI 接线：至少有一个页面/组件导入该服务或包装器并调用它。
• 共享 API 客户端：只要范围内包含任何数据摘要目标，就应存在 src/shared/powerPagesApi.ts。
• Summarization/Data/ContentSizeLimit 站点设置：只要集成了任何列表摘要目标，就应设置此项。搜索源代码中的 fetchListSummary；如果有任何匹配项，请确认 .powerpages-site/site-settings/Summarization-Data-ContentSizeLimit.sitesetting.yml 存在，且其中包含 value: 200000（或更高值）。缺少此设置会静默地将列表摘要限制在服务器默认值 100k，并向用户提供截断的输入。如果缺少此项，请在完成第 7 阶段前向用户指出这一问题——重新运行架构设计器，或手动创建 YAML 文件。

7.2 请求头契约搜索

Grep: "_api/search/v1\\.0/summary|_api/summarization/data/v1\\.0/" in src/**/*.{ts,tsx,js,jsx,vue,astro}

对于每个匹配的文件，请验证其周围的 fetch 包含：

• __RequestVerificationToken（CSRF 令牌，从 /_layout/tokenhtml 获取）——硬性规则
• X-Requested-With: XMLHttpRequest——建议项（验证器缺少此项时会发出警告，但不会阻止；它与 shell.ajaxSafePost 和其他所有 Power Pages POST 一致）

对于数据摘要调用，还需额外验证以下内容（均为硬性规则）：

• URL 包含 $select=（不使用通配符）
• 已设置 OData-MaxVersion: 4.0 和 OData-Version: 4.0 请求头

继续操作前，请修复所有缺失的硬性规则请求头。缺少 CSRF 令牌会导致 500 错误；缺少 $select 或 OData 请求头会导致 403/400 错误。缺少 X-Requested-With 只会产生验证器警告——为保持一致性，请添加此项，但它不会导致运行失败。

7.3 构建检查

cd "<PROJECT_ROOT>"
npm run build

修复所有类型或导入错误。常见问题：已接线的页面未导入摘要服务；DataSummaryResponse 与 UI 使用方之间存在类型不匹配；getCsrfToken 声明重复（如果第 5 阶段未复用现有 helper）。

7.4 展示验证结果

目标文件	API	服务函数	包装器	UI 调用位置	请求头 ✓	$select ✓
src/pages/SearchResults.tsx	搜索摘要	fetchSearchSummary	useSearchSummary	是	是	不适用
src/pages/CaseDetail.tsx	数据摘要	fetchDataSummary（可选包装为 fetchCaseSummary）	useCaseSummary	是	是	是
src/pages/ProductDetail.tsx	数据摘要	fetchDataSummary	useProductSummary	是	是	是

（行顺序和示例文件路径与第 2 阶段清单示例相同，便于同时阅读两张表的维护者从上到下追踪每一行。第 2 行对应 Microsoft 提供的支持案例方案——对 incidents 配置的数据摘要调用，使用 case_summary 提示词标识符。）

**构建状态：**通过 / 失败（附详情）。

7.5 最终站点完整性检查

完成所有 AI 集成源代码更改和构建验证后，运行：

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

在展示完成情况或询问是否部署之前，请修复所有阻塞性错误。检查并报告两个方向的审查发现，并展开内容。之后如果又有源代码更改，请重新运行此检查。

输出：已验证所有集成文件；项目构建成功。

---

第 8 阶段：审查与部署

目标：记录技能使用情况、展示摘要并提供部署选项。

8.1 记录技能使用情况

参考：${PLUGIN_ROOT}/references/skill-tracking-reference.md

使用 --skillName "AddAiWebapi"。

8.2 呈现摘要

步骤	状态	详情
Web 角色	通过 /create-webroles 创建 / 复用现有角色 / 跳过	角色名称
第 1/2 层（Web API 设置 + 权限）	通过 /integrate-webapi 创建 / 复用现有设置 / 跳过（仅搜索）	写入的文件列表
摘要服务	已创建 / 已扩展	导出的函数、文件路径
框架封装	已创建 / 已扩展	hook/composable/service 路径
UI 调用点	已接入	文件列表
第 3 层（Summarization/* 设置）	已创建 / 已存在 / 已跳过	Summarization/Data/Enable，每个提示词对应一项

8.3 询问是否部署

问题	标题	选项
一切准备就绪。要部署网站以启用摘要 API 吗？	部署	是，现在部署（推荐），否，我稍后部署

是：调用 /deploy-site。 否：确认收到。提醒用户，只有网站部署并应用新的设置和权限后，API 调用才会生效。

8.4 部署后说明

在运行结束时向用户说明以下内容：

• Search Summary 开关 — 对于任何 Search Summary 集成，提醒用户开启 Set up workspace → Copilot → Site search (preview) → "Enable Site search with generative AI (preview)"。如果不开启，端点会返回已禁用状态的响应，UI 将显示问题修复卡片，而不是摘要。
• 测试步骤 — 对于 Data Summarization，打开记录详情页或列表页，触发摘要，确认返回 200 且文本已呈现，然后点击一个推荐标签，确认后续请求会发送 RecommendationConfig。对于 Search Summary，执行搜索并确认摘要显示在关键词结果上方，且引用锚点指向 SPA 路由（而非 /page-not-found/）。对于刚创建且没有评论的记录，Microsoft 提供的支持案例方案通常会触发 90041005“无可摘要内容”分支，这是正常情况——请使用在每个已选 / 展开的列中都有实质内容的记录进行测试。
• 出现已禁用状态卡片或 90041001 时 — 按照 references/ai-api-reference.md §1“故障排查：AI 功能显示为已禁用（管理员层级）”中的管理员层级检查清单逐项排查。重试没有帮助；管理员或制作者必须更改治理设置 / 开启网站开关。
• 任何摘要调用出现 403，始终是第 1/2 层问题（Webapi/<table>/fields 中的列名大小写错误，或缺少 read: true 表权限）——请以仅限 AI 的只读模式重新运行 /integrate-webapi，不要手动编辑 YAML。
• 完整错误代码参考（90041001 … 90041006）位于 references/ai-api-reference.md §2“错误代码”。用户报告 400 错误时请打开此文档。
• 列权限配置文件可能会悄悄隐藏内容。 如果摘要明显遗漏内容，请先检查 Web 角色上的 Dataverse 列权限配置文件，再怀疑提示词或字段列表。

输出：已呈现摘要，已完成部署或延后部署，并已提供部署后指导。

---

重要说明

所有阶段都必须遵守

• 使用 TaskCreate/TaskUpdate 跟踪每个阶段的进度。
• 在关键决策点征求用户确认（见下方列表）。
• 按顺序启动 Agent——遵循 plugins/power-pages/AGENTS.md 中的“Agent spawning”规则。绝不要并行地在多个目标上启动 ai-webapi-integration（每个目标都会扩展同一个 aiSummaryService.* 文件，因此并行运行会发生冲突）。
• 在里程碑处提交更改——实现完成后（第 5 阶段）提交一次，设置创建完成后（第 6 阶段）再提交一次。
• 摘要请求绝不使用 OData 封装器——只能使用原始 fetch。
• 绝不直接编写第 1/2 层文件——始终委托给 /integrate-webapi / /create-webroles。此技能属于第 3 层。

关键决策点（等待用户确认）

以下列表是保守估计的上限——许多运行中触发的提示词更少，因为跳过检查（仅搜索运行、第 1/2 层已就绪、没有列表/意图不匹配目标）会省去整个分支。对于首次运行且涉及多个目标的情况，实际最坏约为 10 个提示词；重新进入后进行简单调整，只需 1 个提示词（Phase 1.0 的模式问题）。

1. 在 Phase 1.0（重新进入检测）：调整现有界面、添加新界面，或检查已接入的内容。只有先前的 /add-ai-webapi 运行在磁盘上留下了服务文件或 Summarization/* 设置时，才会触发。
2. 在 Phase 1.5：启动部署或停止（如果缺少 .powerpages-site）。
3. 在 Phase 3 之后（主要阶段）：确认要集成哪些 API / 目标。
4. Phase 3 中针对每个目标的后续问题（数量不定）：列表触发器选择（每个列表目标一次），以及范围确认（针对每个 scope-extends-beyond-existing-fetch、needs-definition 或 intent-mismatch 行）。问题文本和选项列表位于 references/scope-classification.md。
5. 在 Phase 4.2：通过 /create-webroles 创建缺失的 Web 角色（如有需要）。调用此子技能时会传入 caller-suppress 哨兵，因此不会触发它自己的部署提示词。
6. 在 Phase 4.2（仅限跳过路径）：确认即使已知存在运行时故障风险，仍要继续。
7. 在 Phase 4.3 的 /integrate-webapi 委派中：批准其 table-permissions-architect 计划和 webapi-settings-architect 计划（每位架构师各自负责其计划模式提示词；该子技能处于 AI 只读模式，因此会抑制其提交和部署提示词）。
8. 在 Phase 5.5：现在提交集成更改，还是稍后提交。
9. 在 Phase 6.3 的 ai-webapi-settings-architect 调用中：批准其计划。
10. 在 Phase 6.4：现在提交新的设置，还是稍后提交。
11. 在 Phase 8.3：现在部署，还是稍后部署。

列表摘要用例指南

当目标是记录列表（而不是单条记录）时，单记录 Copilot 卡片的默认设置并不适用——集合端点、表格洞察提示词、ContentSizeLimit=200000、normalizeSummaryString + 安全 Markdown 渲染器等。

完整的 10 条指南（集合端点、范围镜像、提示词大小、导航属性大小写、必需的 ContentSizeLimit）位于 ${PLUGIN_ROOT}/skills/add-ai-webapi/references/ai-api-reference.md §2“列表摘要指南”。在任何列表摘要目标进入 Phase 5 之前，请先阅读该部分——Phase 5 Agent 和 Phase 6 设置架构师都会参考同一份指南。

进度跟踪

开始第 1 阶段之前，使用 TaskCreate 创建包含所有阶段的任务列表：

任务主题	activeForm	描述
检查站点是否就绪	正在检查站点前置条件	定位项目根目录、检测框架、检查数据模型、部署状态和 Web 角色清单
查找 AI 摘要的适用位置	正在扫描代码中的 AI 摘要机会	使用 Explore Agent 查找搜索、数据和案例候选项、现有基础设施及委派决策
确认要添加的内容	正在确认 AI 摘要计划	提供清单，并确认要集成的 API 和目标
为 AI 设置数据访问	正在设置 Web API 访问权限	如有需要，调用 /create-webroles，然后以仅 AI 读取模式调用 /integrate-webapi（仅搜索时则跳过）
添加 AI 摘要代码	正在向页面添加 AI 摘要代码	按顺序调用 ai-webapi-integration：第一个目标创建共享服务和 CSRF 辅助程序，其余目标在此基础上扩展
注册 AI 提示词	正在注册 AI 提示词设置	调用 ai-webapi-settings-architect，创建 Summarization/* 设置
验证所有内容	正在验证文件清单、标头和构建	确认服务文件、包装器、UI 接线和标头约定，并运行项目构建
审查并部署	正在审查摘要并部署	记录技能使用情况、提供摘要、提供 /deploy-site 选项，并给出部署后指导

开始每项任务时，通过 TaskUpdate 将状态标记为 in_progress；完成时标记为 completed。

---

从第 1 阶段开始：验证站点是否存在