integrate-backend

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

后端集成

分析用户的业务问题，并推荐合适的后端集成方案——Web API、AI Web API、服务器逻辑、Cloud Flows，或组合使用——然后转到相应的技能来实现解决方案。

核心原则

• 先理解问题：切勿仓促选择技术。推荐之前，应分析用户意图、数据流、安全需求和性能要求。
• 推荐能解决问题的最简单方案：对于简单的 Dataverse CRUD，使用 Web API；对于生成式摘要或基于现有数据的搜索，使用 AI Web API；需要服务器端处理时，使用服务器逻辑；需要异步后台处理时，使用 Cloud Flows。避免过度设计。
• 安全操作应在服务器上执行：如果写入操作依赖必须防篡改的业务规则（状态转换、审批工作流、计算值），服务器逻辑必须验证并执行写入——不能只做验证，然后把写入留给客户端的 Web API 调用。请参阅决策框架中的安全操作原则。
• AI Web API 基于 Web API 构建：数据摘要和案例预设终结点通过与常规 Web API 相同的 _api 层读取数据，因此沿用相同的表权限、列权限和 Webapi/<table>/* 站点设置。如果计划中同一张表同时包含 Web API 项和 AI Web API 项，AI 项依赖于 Web API 项（因此应安排在更晚的阶段）。搜索摘要没有按表设置的前置条件，可以独立使用。
• 组合方案很常见：许多实际场景需要不止一种方案。理由充分时，应推荐组合方案，并说明每一部分的必要性。
• 负责路由，不负责实现：此技能会推荐并调用合适的技能，但不会自行创建后端文件。

初始请求：$ARGUMENTS

---

工作流

1. 确认站点存在 — 找到 Power Pages 项目并检查前置条件
2. 了解业务问题 — 分析用户的需求及其原因
3. 推荐集成方案 — 说明推荐方案及理由
4. 转到相应技能 — 调用合适的后端技能进行实现

---

阶段 1：确认站点存在

目标：找到 Power Pages 项目根目录并确认前置条件

操作：

1. 创建包含全部 4 个阶段的待办列表（参见进度跟踪表）

1.1 定位项目

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

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

1.2 检查当前状态

使用 Explore agent 快速扫描站点中现有的后端集成：

“分析此 Power Pages SPA 站点中现有的后端集成：

1. 检查 .powerpages-site/server-logic/ — 列出所有现有的服务器逻辑终结点
2. 检查 .powerpages-site/cloud-flow-consumer/ — 列出所有已注册的云流
3. 搜索前端代码（src/**/*.{ts,tsx,js,jsx,vue,astro}）中对 /_api/（Web API）、/_api/serverlogics/（服务器逻辑）和 /_api/cloudflow/（Cloud Flows）的调用
4. 检查 src/services/、src/shared/ 或类似目录中是否有现有的服务层或 API 工具
5. 列出 .powerpages-site/web-roles/*.webrole.yml 中可用的 Web 角色 报告现有的后端集成，以便我们在此基础上继续构建。”

1.3 发现 Dataverse 自定义操作

检查用户的 Dataverse 环境中是否存在可用于集成的现有自定义操作：

node "${PLUGIN_ROOT}/scripts/list-custom-actions.js" "<ENV_URL>"

脚本会返回自定义 API（现代）和自定义流程操作（旧版），以及它们的名称、说明、绑定类型和参数。如果发现自定义操作，请记下它们；这些信息将在第 3 阶段纳入建议。

输出：确认项目根目录、识别现有后端集成、发现 Dataverse 自定义操作

---

第 2 阶段：了解业务问题

目标：分析用户的请求，了解其背后的业务问题，而不仅仅是技术需求

操作：

2.1 分析请求

根据用户的请求和网站现有状态，确定：

• 用户想要实现什么？（业务成果，而非技术）
• 涉及哪些数据？（Dataverse 表、外部系统、用户输入）
• 谁会触发此操作？（用户操作、表单提交、页面加载、定时任务）
• 用户是否需要即时响应？（实时 UI 更新，还是后台处理）
• 是否涉及外部服务？（支付网关、电子邮件、Graph、SharePoint、第三方 API）
• 是否涉及凭据或机密？（API 密钥、客户端机密、令牌）
• 逻辑是否必须对浏览器隐藏？（定价规则、验证算法、业务规则）
• 这是简单的数据操作，还是复杂的业务逻辑？（CRUD 与多步处理）
• 是否有写入操作依赖于必须防篡改的业务规则？（状态转换、审批条件、计算值）——如果是，服务器逻辑必须验证并执行写入，而不能只做验证
• UI 是否需要 AI 生成的摘要、有依据的 AI 搜索，或相关记录发现功能？（例如，“总结此案例”“总结未结订单”“在案例页面推荐 KB 文章”“AI 驱动的搜索”）——如果是，AI Web API 是合适的选择。留意这些措辞信号：总结、摘要、Copilot、相关 / 相似 / 推荐的 <实体>、AI 搜索、语义搜索。
• **现有 Dataverse 自定义操作能否处理部分需求？**如果在第 1.3 阶段发现了自定义操作，请检查其中是否有符合用户需求的操作——服务器逻辑可以通过 InvokeCustomApi 调用现有自定义操作，而不必从头构建等效逻辑

2.2 歧义时进行澄清

如果请求可能对应多种方案，且无法明确选择哪种方案，请使用 AskUserQuestion 进行澄清：

问题	询问时机
用户需要立即看到结果，还是可以在后台完成？	当请求涉及可同步或异步处理的任务时
是否涉及外部 API 或服务（例如 Stripe、SendGrid、SharePoint）？	当请求提到“集成”但未说明具体内容时
是否涉及不应放在浏览器中的敏感凭据？	当提到外部服务集成时
这是一次性操作，还是多步工作流？	当请求可能是简单调用，也可能是流程编排时

输出：清楚了解业务问题和技术要求

---

第 3 阶段：推荐集成方案

目标：给出理由明确的建议

操作：

3.1 应用决策框架

参考：${PLUGIN_ROOT}/skills/integrate-backend/references/decision-framework.md

使用参考文档中的决策矩阵、意图映射和 Secure Action Principle（安全操作原则） 来确定合适的方案。请考虑：

1. 仅使用 Web API 能否处理？ 如果只是简单的 Dataverse CRUD，不涉及外部调用、机密、服务器端逻辑，也没有管理写入的业务规则——建议使用 Web API。这是最简单的方案。

2. 是否需要 AI Web API？ 如果符合以下任一情况，AI Web API 就是合适的选择：

   • UI 希望在记录的详情页上显示 AI 生成的摘要（例如，“总结此案例”、“Copilot 摘要”）
   • UI 希望获取列表或集合的 AI 摘要（例如，“总结未结订单”、“指出本周案例中的趋势”）
   • 详情页需要发现相关记录（例如，“为此案例推荐 KB 文章”、“类似产品”、“类似案例”）——与手动编写 OData 关键字匹配相比，Search Summary 的基于检索内容的摘要更合适
   • 网站需要带有引用来源的 AI 增强搜索，以取代或补充仅基于关键字的搜索

   AI Web API 仅支持读取，因此 Secure Action Principle 不适用。如果某个 AI 项目涉及的 Dataverse 表也由 Web API 项目处理，请将该 AI 项目安排在后续阶段（它依赖于 Web API Layer 1/2 前置条件）。Search Summary 项目没有逐表前置条件，可以独立实施。

3. 是否需要 Server Logic？ 如果符合以下任一情况，则需要 Server Logic：

   • 调用外部 API（HttpClient）
   • 凭据或机密必须保留在服务器上
   • 业务逻辑必须对浏览器隐藏
   • 应将多个 Dataverse 查询合并到一个端点
   • 需要无法绕过的服务器端验证
   • 为门户使用封装 Dataverse Custom API/Action——如果在 Phase 1.3 中发现了自定义操作，请在建议从头构建之前，检查是否有操作符合需求
   • 写入依赖于必须防篡改的业务规则（状态转换、审批条件、计算值）——服务器逻辑必须验证并执行写入

4. 是否需要 Cloud Flows？ 如果符合以下任一情况，则 Cloud Flows 是合适的选择：

   • 操作是异步的——用户不需要立即获得结果
   • 后台处理：发送电子邮件、通知、处理订单
   • 使用 Power Automate 连接器跨系统执行多步骤工作流
   • 长时间运行的流程超过 Server Logic 120 秒的超时时间
   • 非开发人员应能够修改工作流

5. 是否需要组合使用？ 常见组合：

   • Web API + AI Web API：UI 显示原始 Dataverse 记录及同一数据的 AI 摘要（最常见的 AI 模式——仪表板、案例或订单详情页）
   • Web API + Cloud Flow：UI 读取/写入非敏感的 Dataverse 字段，某些操作会触发后台流程
   • Server Logic + Cloud Flow：实时端点验证并执行操作，异步流程执行后续任务（例如，Server Logic 转换状态，Cloud Flow 发送通知）
   • Web API + Server Logic：Web API 用于安全的直接读取/写入，Server Logic 用于需要执行业务规则的操作（对于这些操作，Server Logic 会验证并写入）
   • Web API + AI Web API + Cloud Flow：支持门户提供可浏览的案例、Copilot 摘要与 KB 发现，以及异步通知

3.1.1 安全审查 — 应用安全操作原则

在确定计划之前，审查分配给 Web API 的每一项，并询问：“如果用户跳过之前的任何服务端逻辑验证，直接调用此 Web API 端点，是否可能违反业务规则？”

如果答案是是，那么该写入操作就不应归入 Web API 项。将写入操作移至负责验证它的服务端逻辑项中。服务端逻辑应使用 Server.Connector.Dataverse 验证并执行写入操作。

以下常见模式必须使用验证并执行的服务端逻辑（而非 Web API）：

模式	必须在服务端执行的原因
状态转换（草稿 → 已提交 → 已批准）	客户端可通过直接发送 PATCH 跳转到任意状态
条件写入（仅允许在截止日期前或特定角色执行）	客户端可能在截止日期后写入，或在错误的角色上下文中写入
计算字段写入（服务端计算分数、价格或派生值）	如果客户端直接写入该字段，就可以提交任意值
多表原子操作（授予投标 + 拒绝其他投标 + 更新活动）	客户端执行不完整可能导致数据不一致
依赖其他记录当前状态的写入	客户端持有的过时数据视图可能导致无效写入

状态转换的正确计划结构：

Phase 1: Server Logic — "transition-order" endpoint
  - POST: accepts { entityId, targetStatus }
  - Reads current record, validates transition is allowed, writes new status
  - Returns { success, previousStatus, newStatus }

Phase 2: Web API — Order table CRUD
  - Read: list/filter orders (safe for Web API)
  - Create: new orders in Draft status (safe — initial state, no rule to enforce)
  - Update: description, notes, dates (safe — no business rules on these fields)
  - NOTE: Status changes are NOT here — they go through the server logic endpoint

错误的计划结构（反模式）：

❌ Phase 1: Server Logic — "validate-transition" endpoint
  - POST: accepts { entityId, targetStatus }
  - Reads current record, validates transition
  - Returns { valid: true/false }   ← only validates, doesn't write

❌ Phase 2: Web API — Order table CRUD
  - Update: includes status field  ← client writes status after "validation"
  - PROBLEM: client can skip Phase 1 and write any status directly

3.2 渲染 HTML 计划

在征求批准前，构建计划数据并渲染 HTML 计划。该计划会直观展示：

• 关键概念 — Web API、Server Logic 和 Cloud Flows 的教育性概览（在模板中硬编码）
• 概览 — 各方案的统计数据、方案标签、设计理由
• 数据流 — 展示每项用户操作的数据流向的可视化流程图，步骤按方案着色
• 实施顺序 — 按阶段分组的项目，包含依赖项、复杂度徽章和实施命令
• 集成项目 — 每个项目都包含其方案、理由和实施详情

准备一个包含以下键的 JSON 对象：

键	说明
SITE_NAME	来自 powerpages.config.json 的站点名称
PLAN_TITLE	简短标题（例如，“后端集成计划”）
SUMMARY	对集成策略的 1-3 句总结
ITEMS_DATA	集成项目数组（见下方格式）
DATA_FLOWS_DATA	数据流图数组（见下方格式）
RATIONALE_DATA	设计理由条目数组（包含 icon、title、desc）

ITEMS_DATA 格式：

{
  "name": "Create PayPal Order",
  "approach": "webapi|aiwebapi|serverlogic|cloudflow",
  "description": "What this item does",
  "reasoning": "Why this approach was chosen",
  "phase": 1,
  "status": "new|existing|extends",
  "complexity": "low|medium|high",
  "depends": "Name of item this depends on (if any)",
  "details": [
    { "label": "Endpoint", "value": "/_api/serverlogics/create-paypal-order" },
    { "label": "Secrets", "value": "PAYPAL_CLIENT_ID, PAYPAL_CLIENT_SECRET" }
  ],
  "docs": [
    { "label": "Server Logic Overview", "url": "https://learn.microsoft.com/..." }
  ]
}

阶段分配规则 — 根据依赖关系为每个项目分配一个 phase 编号：

1. 没有依赖项的项目应放在符合其方案的最早阶段
2. 依赖于其他项目的项目应放在其依赖项之后的阶段
3. 同一阶段的项目之间不能相互依赖，并且可以并行构建
4. 建议的默认顺序：首先是 Server Logic 基础功能（用于状态转换的验证并执行端点、批量查询），然后是针对非敏感字段的 Web API CRUD（读取、使用安全默认值创建、更新不受业务规则约束的字段），接着是高级 Server Logic（多表事务），然后是 AI Web API（基于 Web API 已设置的表进行摘要/依据检索），最后是 Cloud Flows（异步后续处理）
5. 安全约束：Web API 项目绝不能写入其值受 Server Logic 项目强制执行的业务规则约束的字段。如果某个字段需要验证，则 Server Logic 项目应直接写入该字段，Web API 项目则应将该字段排除在范围之外
6. AI 分层约束：针对某个 Dataverse 表的 AI Web API 项目，如果该表也由 Web API 项目负责，则 AI Web API 项目必须位于 Web API 项目之后的阶段 — AI Web API 的数据摘要端点会复用 Web API 的 Layer 1/2 前置条件（表权限、Webapi/<table>/* 站点设置）。搜索摘要项目没有单表前置条件，可以放在任意阶段。

DATA_FLOWS_DATA 格式（每个步骤的 approach 是 webapi、aiwebapi、serverlogic 或 cloudflow 之一）：

{
  "trigger": "User registers and pays",
  "description": "User fills the form, pays via PayPal, receives confirmation",
  "steps": [
    { "approach": "serverlogic", "name": "Validate Seats", "detail": "Check availability" },
    { "approach": "serverlogic", "name": "Create Order", "detail": "Server calls PayPal" },
    { "approach": "cloudflow", "name": "Send Email", "detail": "Async confirmation" }
  ]
}

重要：在数据流图中，当 Server Logic 步骤验证业务规则时，下一步不应再由 Web API 写入同一字段。Server Logic 步骤应负责验证并执行。例如：

// ✅ Correct — server logic validates and writes status
{ "approach": "serverlogic", "name": "Submit Order", "detail": "Validates Draft→Submitted, writes new status" }

// ❌ Incorrect — split across server logic validation and Web API write
{ "approach": "serverlogic", "name": "Validate Transition", "detail": "Checks Draft→Submitted" },
{ "approach": "webapi", "name": "Update Status", "detail": "PATCH status to Submitted" }

将计划写入 <PROJECT_ROOT>/docs/backend-plan.html（如有需要，创建 docs/）。使用渲染脚本：

node "${PLUGIN_ROOT}/scripts/render-backend-plan.js" --output "<OUTPUT_PATH>" --data "<DATA_JSON_PATH>"

渲染脚本拒绝覆盖已有文件。如果默认路径已存在，请选择新的描述性文件名（例如，backend-plan-payments.html）。

渲染完成后，在用户的默认浏览器中打开 HTML 计划：

open "<OUTPUT_PATH>"  # macOS
# start "<OUTPUT_PATH>"  # Windows
# xdg-open "<OUTPUT_PATH>"  # Linux

3.3 呈现计划摘要

不要在 CLI 中重述完整计划。HTML 文件是唯一的详细计划文档。

在 CLI 中仅提供简短摘要：

• 项目总数以及各方案的项目数量
• 计划使用单一方案还是组合方案
• 实际输出路径
• 提示浏览器中打开的 HTML 包含所有详细信息，包括数据流图

3.4 与用户确认

🚦 关卡（plan · integrate-backend:3.4.plan-approval）： 在调用相应的子技能（integrate-webapi / add-server-logic / add-cloud-flow）之前，先批准集成计划。无论选择如何，计划 HTML 都会保留在磁盘上——取消只会停止分发。

触发条件： 阶段 3.3 已生成 HTML 计划，并显示了简短的 CLI 摘要。 询问原因： 分发了错误的子技能——为 Web API 任务调用 add-server-logic 会浪费几分钟；为 Web API 任务调用 add-cloud-flow 则会生成孤立的流程 YAML。 取消后的结果： 无——不会调用任何子技能，HTML 计划仍保留在保存路径中。

使用 AskUserQuestion：

问题	选项
以下是集成计划。HTML 计划已在浏览器中打开，其中包含数据流图和逐项说明。这个方案看起来合适吗？	是，继续（推荐），更改方案，取消

如果选择“更改方案”：询问用户更倾向于什么方案以及原因，更新计划，然后再次呈现。

如果选择“取消”：停止工作流。

输出：用户批准的集成方案

---

阶段 4：分派到技能

目标：调用相应的技能来实现已批准的方案，遵循阶段顺序，并在每个阶段内并行执行

操作：

4.1 制定阶段执行计划

根据计划中的 phase 编号，将已批准的项目分组。每个阶段都是一批相互独立的项目——同一阶段内的项目彼此没有依赖关系，可以并行构建。

方案	要调用的技能	要传递的内容
Web API	/integrate-webapi	用户的请求 + 此阶段的表格 + 现有模式
AI Web API	/add-ai-webapi	用户的请求 + 此阶段的目标页面/表格 + 要使用的两个 API 之一（Search Summary 或 Data Summarization）+ 任何触发偏好（列表摘要是在挂载时自动生成还是通过手动按钮触发）。如果目标表格的 Web API 前置条件已在较早阶段配置，请说明这一点，以便 AI 技能跳过其第 1/2 层委派。
服务端逻辑	/add-server-logic	用户的请求 + 此阶段的端点 + 所需的 SDK 功能 + 已识别的机密 + 阶段 1.3 中匹配的 Dataverse 自定义操作
云流程	/add-cloud-flow	用户的请求 + 此阶段的异步操作

4.2 按阶段执行

按顺序处理各阶段（先阶段 1，再阶段 2，依此类推）。完成一个阶段中的所有事项后，再进入下一阶段——后续阶段依赖前面的阶段。

在每个阶段内，尽可能提高并行度：

• 阶段中只有一种实现方式：将该阶段的所有事项一次性提交给技能。告诉技能：“这 N 个事项彼此独立——请尽可能并行实现。”
• 同一阶段中有多种实现方式：针对各自的事项分别调用每项技能。由于同一阶段中的事项没有相互依赖关系，因此在该阶段内调用技能的顺序无关紧要。调用第二项技能时，传入第一项技能的上下文，以便它遵循相同的前端模式（例如命名约定、文件组织方式）。

示例——一个包含 4 个阶段的计划：

阶段	事项	技能	并行方式
1	验证转换（serverlogic）、仪表板指标（serverlogic）	/add-server-logic	将两个事项一起提交——技能并行构建
2	供应商更新（webapi）、投标 CRUD（webapi）、PR 创建（webapi）	/integrate-webapi	将 3 个事项一起提交——技能并行构建
3	授予投标（serverlogic）	/add-server-logic	单个事项——顺序执行
4	审批通知（cloudflow）、到期提醒（cloudflow）	/add-cloud-flow	将两个事项一起提交——技能并行构建

调用每项技能时，请包含：

1. 要实现的事项——列出该阶段计划中的具体事项名称
2. 并行指导——“这些事项属于同一阶段，彼此没有依赖关系。请尽可能并行实现。”
3. 前序阶段的上下文——说明目前已创建的内容（文件、模式、服务），以便技能在此基础上构建

4.3 总结

所有阶段完成后，简要总结已创建的内容：

阶段	实现方式	创建内容
1	服务器逻辑	[创建的端点、使用的 SDK 功能]
2	Web API	[创建的文件、集成的表]
3	服务器逻辑	[创建的端点]
4	云端工作流	[注册的工作流、连接的触发器]

如果用户尚未部署，请提醒他们使用 /deploy-site 进行部署。

4.4 记录技能使用情况

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

按照参考文档中的技能跟踪说明记录此技能的使用情况。使用 --skillName "IntegrateBackend"。

输出：实现所有建议的后端集成

---

重要说明

不应使用此技能的情况

如果用户的请求明确且无歧义地对应单一实现方式，请跳过此技能，直接使用实现技能：

• “为……创建服务器逻辑端点” → /add-server-logic
• “为 contacts 表集成 Web API” → /integrate-webapi
• “添加用于发送电子邮件的云端工作流” → /add-cloud-flow
• “在案例详情页中添加 AI 摘要”／“总结未结案例”／“在此页面上推荐知识库文章” → /add-ai-webapi

此技能适用于用户描述业务问题、需要帮助选择合适实现方式的模糊请求。

示例：路由方式示例

示例 1：简单的 Dataverse CRUD → Web API

User: I need to show a list of products on the homepage and let users
      filter by category.

Recommendation: Web API
Reason: This is straightforward Dataverse read operations with filtering.
        No external APIs, no secrets, no server-side logic needed.
Skill: /integrate-webapi

示例 2：使用凭据的外部 API → 服务端逻辑

User: Add payment processing through Stripe. The API key must stay
      on the server.

Recommendation: Server Logic
Reason: Calls an external API (Stripe) with credentials that must be
        protected. Server logic hides the code and credentials from
        the browser.
Skill: /add-server-logic

示例 3：后台邮件 → Cloud Flow

User: When a user submits the contact form, send them a confirmation
      email and notify the support team on Teams.

Recommendation: Cloud Flow
Reason: Email and Teams notifications are async — the user doesn't
        need to wait for them. Cloud Flows have built-in connectors
        for Outlook and Teams.
Skill: /add-cloud-flow

示例 4：服务端验证 → 服务端逻辑（验证并执行）

User: Add validation that rejects orders when quantity exceeds
      inventory. Check the actual Dataverse data, not just the form.

Recommendation: Server Logic (validate-and-execute)
Reason: Server-side validation that can't be bypassed from the browser.
        The server logic checks inventory AND creates/updates the order
        in a single call — the client doesn't write the order via Web API
        because quantity validation would be bypassable.
Skill: /add-server-logic

示例 5：仪表板性能 → 服务端逻辑

User: The dashboard makes 3 separate API calls to load contacts,
      orders, and products. It's slow.

Recommendation: Server Logic
Reason: Batching multiple Dataverse queries into a single server
        endpoint reduces round-trips and improves load time.
Skill: /add-server-logic

示例 6：CRUD + 后台处理 → Web API + Cloud Flow

User: Let users submit support tickets from the portal. After
      submission, assign it to the right team and send an email.

Recommendation: Web API + Cloud Flow
Reason: The ticket creation is a Dataverse write (Web API). The
        assignment and email happen in the background after the
        user submits (Cloud Flow).
Phases: Phase 1 → /integrate-webapi (ticket CRUD)
        Phase 2 → /add-cloud-flow (assignment + email, depends on ticket creation)

示例 7：验证 + 处理 + 通知 → 服务端逻辑 + Cloud Flow

User: When a user places an order, validate inventory, process the
      payment through Stripe, and send a confirmation email.

Recommendation: Server Logic + Cloud Flow
Reason: Inventory validation and Stripe payment need real-time
        server-side processing with credentials (Server Logic).
        The confirmation email is async (Cloud Flow).
Phases: Phase 1 → /add-server-logic (validate inventory + process payment — parallel)
        Phase 2 → /add-cloud-flow (confirmation email, depends on payment)

示例 8：状态转换 + CRUD → 服务端逻辑（验证并执行）+ Web API

User: Build a procurement workflow with status transitions
      (Draft → Submitted → Approved) and let users edit request details.

Recommendation: Server Logic + Web API
Reason: Status transitions must be tamper-proof — server logic validates
        the transition AND writes the new status to Dataverse in one call
        (the Secure Action Principle). Editing non-sensitive fields like
        description or notes is safe via Web API since no business rule
        governs those writes.
Phases: Phase 1 → /add-server-logic (transition-request endpoint that
          validates AND writes status changes)
        Phase 2 → /integrate-webapi (read/list requests, edit description
          and notes — but NOT status, which goes through server logic)

NOTE: The Web API item must NOT include the status field in its Update
      operations. Status writes go exclusively through the server logic
      endpoint.

示例 9：详情页上的 AI 摘要 → AI Web API（数据摘要，支持案例方案）

User: Add an AI-generated summary card to the case detail page that
      includes the comments customers have posted.

Recommendation: AI Web API — Data Summarization
Reason: Microsoft Learn documents a ready-made Data Summarization
        configuration for this scenario on the standard incident table —
        POST to /_api/summarization/data/v1.0/incidents(<id>) with
        InstructionIdentifier "Summarization/prompt/case_summary" and
        $expand=incident_adx_portalcomments($select=description). The
        user can adopt this verbatim or tweak the columns / prompt for
        their own case-handling UX.
Skill: /add-ai-webapi

示例 10：详情页上的相关知识库文章 → AI Web API（搜索摘要）

User: On the case detail page, show relevant KB articles to help
      agents find answers faster.

Recommendation: AI Web API (Search Summary for related-record discovery)
Reason: Search Summary's grounded retrieval returns AI-ranked citations
        from the site's knowledge index — a much better fit than a
        hand-rolled OData keyword match on the knowledge article table.
        The citations rewrite into SPA routes for clean deep-linking.
Skill: /add-ai-webapi

示例 11：列表摘要 + 可浏览的记录 → Web API + AI Web API

User: On the dashboard, show the list of open cases from Dataverse
      and an AI summary highlighting the most common issue themes.

Recommendation: Web API + AI Web API
Reason: The list is direct Dataverse reads — Web API handles pagination,
        filtering, and status badges. The summary is a list-form Data
        Summarization call with $filter=statecode eq 0 using the tabular-
        insight prompt pattern. Web API item goes in Phase 1 because AI
        Web API reuses its Layer 1/2 prereqs (table permissions, Webapi
        site settings for the incident table).
Phases: Phase 1 → /integrate-webapi (incident list CRUD for the dashboard)
        Phase 2 → /add-ai-webapi (list summary for open cases, reuses
          Phase 1's Layer 1/2 — the AI skill detects this and skips its
          Web API delegation)

进度跟踪

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

任务主题	activeForm	描述
验证站点是否存在	正在验证站点前置条件	定位项目根目录，扫描现有后端集成
了解业务问题	正在分析需求	确定用户需求，澄清歧义
推荐集成方案	正在评估方案	应用决策框架，提出建议
路由至实现技能	正在实现后端集成	调用获批的技能并总结结果

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

---

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