setup-app-insights

插件检查：运行 node "${PLUGIN_ROOT}/scripts/check-version.js"——如果输出消息，请先向用户展示，再继续。

共享说明：shared-instructions.md——请先阅读。

设置 Application Insights

通过 app.json → expo.extra.appInsightsConfig 配置生成的应用可选的、由客户自行拥有的 Application Insights 遥测功能。这是主机／运行时配置，不属于连接器或计划部分——绝不会触及数据模型、原生功能矩阵、连接器列表或屏幕。

Application Insights 默认关闭。调用此技能（或批准其变更）即表示明确选择启用；绝不会根据应用描述推断用户已同意。

适用情况

• /setup-app-insights — 在现有应用中启用、更改或禁用 Application Insights。
• 当请求仅涉及更改 Application Insights 时，由 /edit-app 调用（其 Step 0.5 快速路径会委托给此技能）。
• 示例：“为此应用启用 Application Insights”、“更改此应用使用的 Application Insights 资源”、“为此应用禁用 Application Insights”。

不适用情况

• 在应用屏幕中添加或更改自定义事件 → 先在此处配置 Application Insights，然后继续通过 /edit-app 更改这些源文件。
• 数据模型／连接器／原生功能／设计／屏幕变更 → 使用相应的 /add-*、/setup-*、/edit-app 或 /design-system 技能。
• 配置新的 Azure Application Insights 资源 → 不在此技能的范围内；此技能会查找或接受现有资源。

输入

• working_dir — 项目根目录的绝对路径（从 cwd 自动检测，或由编排器传入）。
• --action <enable|change-resource|disable> — 可选；省略时，根据当前状态和一个问题推断。

Step 1 — 检测调用模式

遥测检查点：resolve_app_insights_mode

1. Check MOBILE_APP_ORCHESTRATING=1 AND explicit edit-app caller context
   → Mode A (invoked by /edit-app). Use the passed --working-dir. Return a status block.

2. Else resolve working_dir from cwd (must contain app.json with an expo object)
   → Mode B (standalone). Return a human summary.

使用 app-edit-routing.md 中的调用作用域上下文， 不要使用过时的 shell 值。两种模式下，配置审批均由 Step 3 负责。

Step 2 — 检查并确定操作

遥测检查点：determine_app_insights_action

如有以下文件，请读取：

• <working_dir>/app.json
• <working_dir>/app/_layout.tsx
• <working_dir>/package.json
• <working_dir>/memory-bank.md

如果缺少 app.json、文件格式错误或没有 expo 对象，则停止操作，不进行变更（Mode A 下为 BLOCKED）。如果未提交的工作涉及 app.json 或 app/_layout.tsx，请遵循 shared-instructions.md 中关于变更文件重叠的审批规则。

确定操作：

• enable — appInsightsConfig.enabled 不存在或为 false，且用户希望启用。
• change-resource — 已经是 enabled: true，且用户希望更改目标。
• disable — 用户希望关闭 Application Insights。
• 如果意图不明确，使用当前 enabled 状态作为初始选项，通过一次 AskUserQuestion 提出以上三个选项。

Step 3 — 变更预览 + 审批

遥测检查点：review_app_insights_change

展示一份简明的变更预览，并仅在获得批准后继续：

─── Application Insights ────────────────────────────
Action        <enable | change resource | disable>
Current       enabled: <true|false>
Configuration app.json → expo.extra.appInsightsConfig
Provider      app/_layout.tsx → PowerAppsProvider appConfig
Sensitive     connection string is never printed or stored in memory-bank.md

询问：Apply this Application Insights change?

Step 4 — 发送选择遥测

确认操作后，通过 Mobile Apps 使用情况遥测记录所选操作（启用／更改资源时为 enabled，禁用时为 disabled）：

node "${PLUGIN_ROOT}/hooks/run-telemetry.js" \
  app-insights-selection \
  "<enabled-or-disabled>" \
  "<prompt-or-pretool>" \
  '<working_dir>'

传入调用来源，以便事件中的 invocationSource 与技能的调用方式一致：Mode A 中为 pretool（由另一个技能通过 Skill 工具委托调用，例如 /edit-app），Mode B 中为 prompt（用户直接运行了 /setup-app-insights）。

此事件遵循现有 Mobile Apps 遥测控制，不包含 Application Insights 资源详情或连接字符串。遥测失败时会放行，绝不会阻止技能继续执行。

步骤 5a — 启用 / 更改资源

遥测检查点：configure_app_insights_resource

发现当前 Azure CLI 身份可见的 Application Insights 资源：

az resource list \
  --resource-type Microsoft.Insights/components \
  --query "[].{name:name,id:id,resourceGroup:resourceGroup,location:location}" \
  -o json

根据结果分支处理：

• 返回了一个或多个资源： 使用 AskUserQuestion 让用户选择一个。配置前，确认选定的组件是基于工作区的——az resource list 会返回所有 Microsoft.Insights/components，包括不符合此技能约定的经典组件。读取所选资源的 properties.WorkspaceResourceId：

  WORKSPACE_RESOURCE_ID=$(
    az resource show \
      --ids "<selected-resource-id>" \
      --api-version 2020-02-02 \
      --query properties.WorkspaceResourceId \
      -o tsv
  )
  

  如果 WORKSPACE_RESOURCE_ID 为空，则该资源是经典（非基于工作区的）组件：不要配置它。说明仅支持基于工作区的 Application Insights 资源，并让用户选择其他资源，或使用下方的管理员交接方式。否则，在不打印连接字符串的情况下获取它：

  APP_INSIGHTS_CONNECTION_STRING=$(
    az resource show \
      --ids "<selected-resource-id>" \
      --api-version 2020-02-02 \
      --query properties.ConnectionString \
      -o tsv
  )
  

• 未登录： 告知用户运行 az login，然后重试一次资源发现。

• 没有订阅 / 资源访问权限或授权失败： 说明 Application Insights Azure RBAC 与 Power Platform 和 Entra 应用注册权限彼此独立。提供管理员交接方式：管理员可以创建 / 选择一个基于工作区的 Application Insights 资源，并向用户提供其连接字符串。

• 未返回资源： 询问用户是否想粘贴管理员提供的连接字符串，或保持遥测禁用。不要要求用户创建 Azure 资源。

接受粘贴的连接字符串时，使用 AskUserQuestion 自由输入，并且绝不要在聊天或命令输出中重复答案。仅验证其是否包含 InstrumentationKey=，以及是否包含 IngestionEndpoint=，或是否可以使用标准公共云默认值。不要将连接字符串存储在 memory-bank.md 中。

更新 <working_dir>/app.json，使 expo.extra.appInsightsConfig 包含：

{
  "expo": {
    "extra": {
      "appInsightsConfig": {
        "enabled": true,
        "connectionString": "<selected-or-pasted-connection-string>",
        "appId": "<appId>",
        "environment": "development",
        "includeUserId": false
      }
    }
  }
}

字段规则：

• appId — 保留现有的非空值；否则依次使用 expo.slug、package.json 中的 name。
• environment / includeUserId — 保留现有值；默认分别为 "development" 和 false。绝不要隐式启用用户身份收集。
• 设置 enabled: true，并且只替换连接字符串。若缺少 appInsightsConfig 对象，则创建该对象，并保留 app.json 中的所有其他字段。

绝不要打印连接字符串、将其传递给其他 Agent、写入 native-app-plan.md 或 memory-bank.md，或将其包含在摘要中。

运行时说明（适用于后续的屏幕工作）

此应用使用带有 React Native 手动设备插件的 @microsoft/applicationinsights-web。第一个运行时事件是 PowerAppsNative.ApplicationStarted，用于在 Dev Player 中加载应用后进行确定性的摄取检查。运行时提供了两个用途有意区分的记录器：

import {
  getAppLogger,
  getCustomEventsLogger,
} from '@microsoft/power-apps-native-host';

• getAppLogger() 是宿主 / 运行时记录器；其事件会继续发送到 Microsoft OneDS，同时也会转发到已配置的 Application Insights 资源。
• getCustomEventsLogger() 用于应用的自定义事件；事件只会发送到已配置的 Application Insights 资源，并且在禁用自定义事件时不执行任何操作。
• 仅当用户明确请求这些事件，或已批准的屏幕规范中包含 Custom events 条目时，才生成自定义事件调用。绝不要将 getAppLogger() 用于自定义事件。
• 遥测属性必须是已批准的标量值（结果代码、持续时间、计数、屏幕标识符、操作名称）。绝不要包含表单值、自由文本、记录标题、姓名、电子邮件、电话号码、令牌、精确坐标、嵌套对象或完整 URL。

将以下内容持久化到 memory-bank.md（绝不包含连接字符串）：

- Custom events: enabled
- Custom events app ID: <appId>
- Custom events resource ID: <selected-resource-id or admin-provided>
- Custom events destination: one customer-owned workspace-based Application Insights resource

步骤 5b — 禁用

遥测检查点：disable_app_insights

设置 enabled: false，清空 connectionString，并在存在时保留 appId 和 environment。除非必须保留现有的明确批准值，否则将 includeUserId: false 保持不变。无需 Azure 登录或发现资源。

{
  "expo": {
    "extra": {
      "appInsightsConfig": {
        "enabled": false,
        "connectionString": "",
        "appId": "<appId>",
        "environment": "development",
        "includeUserId": false
      }
    }
  }
}

在 memory-bank.md 中记录 Custom events: disabled 和应用 ID；移除过时的资源 ID／目标行。

步骤 6 — 验证提供程序接线

遥测检查点：verify_app_insights_provider

确认 app/_layout.tsx 导入根目录下的 app.json，并将完整对象传递给 PowerAppsProvider：

import appConfig from '../app.json';

<PowerAppsProvider appConfig={appConfig}>

如果缺少任一部分，只修补导入和 appConfig 属性；保留所有其他提供程序属性和布局行为。仅当 app/_layout.tsx 有更改时，运行 npx --no-install tsc --noEmit。

修改后，使用 Node 解析 app.json 并断言：

• enable / change-resource：enabled === true 且 connectionString 非空。
• disable：enabled === false 且 connectionString === ""。

步骤 6.5 — 提供操作埋点（仅限 enable / change-resource）

遥测检查点：offer_operation_instrumentation

此技能仅接入遥测管道；绝不编辑屏幕或生成的服务。启用 Application Insights 会自动发出应用加载、未处理错误和导航等主机级信号，但 todo_created 或 order_deleted 等领域事件属于自定义事件，需要修改源代码。这些修改应由 /edit-app → screen-planner → screen-builder 负责，通过现有的仅标量、无 PII 允许列表，使用 getCustomEventsLogger 发出具名事件。在此处提供后续操作选项；切勿通过此技能为操作添加埋点。

仅在 enable 或 change-resource 成功后运行此步骤。disable 时完全跳过。

• 模式 B（独立运行）： 使用一次 AskUserQuestion 询问，默认选择 No（埋点为选择加入，与默认关闭的 Application Insights 一致）：

  Application Insights 已启用。要我为应用的主要操作添加自定义事件吗（创建／更新／删除）？

  • Yes → 使用限定范围的埋点说明调用 /edit-app，并让其按常规编辑流程发现实体、屏幕和操作边界（此技能不会读取数据模型或屏幕）：

    Invoke skill: /edit-app
    
    Arguments:
      Add custom events at each successful create, update, and
      delete boundary for the app's main entities. Emit named events through
      getCustomEventsLogger with approved scalar properties only — no
      operation results, response payloads, form values, free text, record
      titles, personal identifiers, tokens, precise coordinates, nested
      objects, or complete URLs. Use trackScenario() for any duration.
    

  • No → 按照常规模式 B 摘要结束。

• 模式 A（由 /edit-app 调用）： 不要在此处询问用户，也不要再次调用 /edit-app——这会回到编排器形成循环。应在返回块中标记可提供后续操作（instrumentation_offer: available），以便 /edit-app 在快速流程完成后提供该选项。

支持范围

此技能会发现或接受现有的 Application Insights 资源；不会预配 Azure 资源。如果用户没有 Azure 访问权限，也没有管理员提供的连接字符串，则保持遥测禁用且不阻塞流程——关闭自定义事件后，应用仍可正常运行。

返回

模式 A（通过 /edit-app 调用）——状态块，第一行是状态码：

DONE
action: <enable|change-resource|disable>
enabled: <true|false>
app_id: <appId>
layout_patched: <yes|no>
instrumentation_offer: <available|none>

只有在成功执行 enable/change-resource 后（参见步骤 6.5），instrumentation_offer 才是 available；对于 disable 或未启用遥测的情况，请使用 none。如果已应用但有注意事项（例如，无法验证管理员提供的字符串），请使用 DONE_WITH_CONCERNS: <list>；如果缺少必需输入，请使用 NEEDS_CONTEXT: <missing>；如果无法使用 app.json，请使用 BLOCKED: <reason>。

模式 B（独立运行）——面向用户的摘要：

此应用的 Application Insights 已<启用|更新|禁用>。 配置：app.json → expo.extra.appInsightsConfig 若要更改资源或稍后关闭，请再次运行 /setup-app-insights。

在执行 enable/change-resource 后，如果用户接受了步骤 6.5 中的提议，请注明操作插桩已交由 /edit-app 处理；如果用户拒绝，请说明他们之后可以运行 /edit-app 来添加自定义操作事件。