将 Work IQ Dev 工具集成到 智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶® 插件 CI/CD

使用 Work IQ Dev Tools (WIQD) ,向 智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶® 插件项目添加持续集成和持续交付 (CI/CD) 检查。 本文将廉价的拉取请求检查与经过身份验证的候选测试和批准的版本提交分开。

本指南适用于将 WIQD 集成到现有 CI/CD 系统的开发人员。 它记录了要求和命令序列,而不是如何设置完整的 CI/CD 环境。 您需要配置系统的作业、触发器、运行器、密钥、批准和工件处理,并将这些示例集成到该系统中。 在开始之前,请准备好先 决条件中列出的运行器、环境和凭证。

发布目标是租户的组织应用目录,管理员在其中批准提交的插件,然后用户才能发现它们。 直接共享是一种单独的分发方法。 此工作流不自动审批管理员。 公共合作伙伴中心提交使用单独 wiqd publish pc 的工作流。

先决条件

若要在现有管道或工作流中运行 WIQD 命令,请确保你有:

  • 源托管的 WIQD 插件项目及其生命周期文件、组件测试和非机密环境配置。 请参阅 使用 Work IQ Dev Tools 构建插件。
  • 具有源签出、运行器、受保护密钥和发布审批控制的现有 CI/CD 系统。 您知道如何在该系统中配置作业、触发器和工件处理。
  • Node.js 24.15.0 或更高版本,以及运行程序上精确批准的 WIQD 版本。 按照 WIQD 安装说明进行操作,并使用 wiqd --version记录安装的版本。
  • PowerShell 7 来使用本文中的命令示例。
  • 为租户支持的命令配置的 WIQD 环境。 按照 WIQD 环境配置 准备环境文件。 单独的测试环境和生产环境或 Microsoft 365 租户是可选的,不是先决条件。 dev、 staging和 prod 是常规名称,不能保证租户或部署范围。
  • 获得所选预配、包验证和发布操作授权的 Microsoft 365 标识,并获得所需的委派许可。 仅授予这些操作所需的权限,如 WIQD 许可和资源限制中所列。
  • 对于声明性代理评估,预配的目标、已审阅的提示文件、批准的质量阈值以及单独配置的评估身份验证和 EULA 接受。 请按照 WIQD 代理评估指南 了解详细设置和要求。 没有代理的插件不需要代理评估,例如仅技能插件或仅工具插件;保留其适用的组件和目标体验测试。

请按照 CI/CD 提供商的文档进行平台设置和工作流创作。 例如,请参阅创建第一个 Azure 管道或实现 GitHub Actions。

选择管道方案

配置单独的作业,以便不受信任的更改无法访问部署凭据或提交版本。

方案 何时运行 WIQD 操作 Gate
拉取请求验证 打开拉取请求时以及每次更新其建议的更改后 脱机源验证;可选脱机发布准备 源检查通过,并记录其覆盖范围限制
候选生成和测试 已批准的受信任分支上的更改或授权的手动运行 在所选环境中预配插件,生成和验证包,测试和评估适用的代理 通过包装、组件、体验和质量检查
版本提交 已批准的候选项和发布授权 确认发布配置和已验证的包,然后发布到组织应用目录 提交成功,然后进行管理员批准和推出验证

保留项目的组件生成和测试。 WIQD 不会为每个插件提供通用编译命令,也不会更新插件引用的远程服务。

如果要使 WIQD 管道设置指南 适应插件项目,请使用本文的 wiqd plugin 命令序列。 本指南的 wiqd agent 生命周期示例面向代理项目,而不是独立插件项目。

添加廉价的拉取请求检查

在没有 Microsoft 365 凭据的情况下运行脱机验证。 这些检查不会预配资源、调用代理或将任何内容提交到注册表。

要向现有作业添加源检查,请执行以下操作:

  1. 查看建议的源并安装已批准的 WIQD 版本。
  2. 运行项目的适用组件测试。
  3. 运行以下 WIQD 步骤,替换 .\plugins\contoso 为项目路径和 dev 预期的环境上下文。
  4. 需要本机退出成功和 JSON 成功信封才能通过作业。

此 GitHub Actions 步骤检查独立插件项目中的声明性代理源图面:

- name: Validate plugin source
  shell: pwsh
  run: |
    $ErrorActionPreference = 'Stop'
    $PSNativeCommandUseErrorActionPreference = $false
    $text = wiqd plugin validate --path .\plugins\contoso --env dev --mode source --json
    if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
    $result = ($text -join "`n") | ConvertFrom-Json
    if ($result.status -cne 'success') { throw 'Plugin source validation failed.' }

相同的 PowerShell 正文可以在 Azure Pipelines pwsh: 步骤中运行。 请勿将生命周期或评估凭据注入任一提供程序不受信任的拉取请求作业。

源验证检查保存的声明式代理源,并需要可读的插件项目 JSON 文件。 它不完全验证顶级应用清单架构、独立技能、根连接器或引用的 API 和 OpenAPI 内容。 仅限技能或仅限连接器的插件可以报告没有声明性代理源覆盖范围,并不是说每个组件都有效。 查看返回的已检查文件列表和结果。

显式指定 --mode source 离线作业。 裸机 wiqd plugin validate 默认为 package,将上传已生成的 ZIP,并且可能要求登录。 请参阅 WIQD 验证命令参考。

有关其他脱机发布就绪情况检查,请运行以下命令并应用相同的退出代码和 JSON 检查:

wiqd plugin publish --path .\plugins\contoso --env dev --dry-run --no-runtime --no-network --json

此检查不会提交插件。 将禁用运行时和网络检查,并且当没有代理时,将跳过声明性代理阶段。 脱机检查都不能代替生成包的验证或目标 Microsoft 365 体验中的测试。

为受信任作业配置身份验证

预配、程序包验证和发布需要拉取请求作业没有的凭据。 与租户管理员一起查看记录的身份验证模式,确认所选 WIQD 版本中的支持,然后仅将凭据注入受信任的步骤。

警告

请勿使用用户名/密码身份验证。 确认所选 WIQD 版本中的支持后,请使用刷新令牌模式。 仅当组织的安全策略明确允许时才使用密码模式。 不要为了使管道成功而削弱 MFA 或条件访问要求。 刷新令牌也是敏感凭据,需要受保护的存储和受限的访问。

重要

WIQD 管道身份验证指南将刷新令牌身份验证标记为尚未发布或完全验证。 刷新令牌示例是集成指南,而不是确认的生产就绪身份验证路径。 在使用这些示例之前,请确认所选的确切 WIQD 版本的发布可用性、安全批准、实时同意和操作检查。

Mode 必需的进程输入 要删除的输入
刷新令牌 CI_ENABLED=true,中的 M365_TENANT_ID租户 GUID,并且受保护 M365_REFRESH_TOKEN 同时删除 和 M365_ACCOUNT_PASSWORD,甚至为M365_ACCOUNT_NAME空定义
用户名和密码 CI_ENABLED=true、受保护 M365_ACCOUNT_NAME和受保护 M365_ACCOUNT_PASSWORD 删除 M365_REFRESH_TOKEN; M365_TENANT_ID 在此模式下是可选的

对于刷新令牌身份验证:

  1. 遵循 WIQD 管道身份验证中的专用本地启动过程。
  2. 将生成的令牌直接放入已批准的管道机密存储中。 请勿提交它,将其作为命令参数传递,或将其包含在日志或项目中。
  3. 将租户和令牌映射到受信任的命令进程。
  4. 在启用版本提交之前,请在受控运行中验证所选 WIQD 版本、标识、运行程序和所需操作。

对于受信任的 GitHub Actions 步骤,请使用以下环境绑定:

env:
  CI_ENABLED: 'true'
  M365_TENANT_ID: ${{ vars.M365_TENANT_ID }}
  M365_REFRESH_TOKEN: ${{ secrets.M365_REFRESH_TOKEN }}

Azure Pipelines 需要显式env映射机密变量。 在调用 WIQD 之前,请使用这些绑定并拒绝未解析的 $(NAME) 宏:

env:
  CI_ENABLED: 'true'
  M365_TENANT_ID: $(M365_TENANT_ID)
  M365_REFRESH_TOKEN: $(M365_REFRESH_TOKEN)

这些是环境绑定,而不是完整的管道定义。 对于身份验证模式和特定于提供程序的检查,请遵循 WIQD 管道示例。

CI_ENABLED 必须完全小写 true;泛型 CI=true 是不够的。 直接调用生命周期命令,而不是 wiqd auth login 在 CI 中调用。 这些是委派的凭据,不是仅限应用的标识,并且不会绕过 MFA、条件访问、同意或权限。

WIQD 不会轮换管道机密存储。 当身份验证需要人工登录或同意时,请解决策略或同意问题,并通过记录的本地过程替换机密。 不要自动切换到其他标识。

生成和验证候选项

在版本提交之前,在所选的 WIQD 环境中生成并测试候选项。 测试可以使用与发布相同的租户、环境配置和授权的 Microsoft 365 标识;单独的测试环境是可选的。 将相关命令保留在同一项目和环境状态上。

警告

如果候选插件和已发布插件使用相同的插件资源标识,则预配可以在目录提交或管理员批准之前更新现有用户使用的资源。 仅当候选更改获得授权并控制访问时,才将该标识用于候选更新。 单独的候选标识是可选的,但可将候选更改与已发布的插件隔离开来。

准备候选人:

  1. 选择已批准的源修订版和插件包版本。
  2. 如果已预配所选环境,请通过批准的安全持久性机制使其已建立的环境状态可用。 保留所有生命周期所需的值,而不仅仅是应用 ID。 请勿通过下载项目存档或身份验证缓存来还原凭据。
  3. 运行组件生成、测试和脱机源代码验证。
  4. 如果需要,请为此候选环境预配或更新所选环境。
  5. 如果预配更改了源验证涵盖的输入,请重新验证受影响的源。
  6. 打包项目。
  7. 使用包模式验证生成的确切 ZIP。
  8. 使用候选记录保留 ZIP、验证结果、源修订版本、程序包版本、WIQD 版本和环境标识。

以下 PowerShell 示例涵盖了一个需要预配或更新其租户资源的候选项。 配置身份验证后,在受信任的作业中运行它。 如果所选环境已绑定标识,并且不需要预配更新,请省略 provision 命令。 仅当源验证的输入已更改时才重复源验证。 将项目路径和 dev 环境替换为候选配置。 如果出现本机错误、JSON 格式错误或信封失败,帮助程序就会停止。

该示例将完整的验证 JSON 写入为 .artifacts\validation.json 中间证据。 在保留或共享之前,限制访问并审查租户信息、标识符、URL 和敏感内容的有效负载。 上传前对证据进行清理;不要自动上传项目目录。

$ErrorActionPreference = 'Stop'
$PSNativeCommandUseErrorActionPreference = $false

function Invoke-WiqdJson([string[]]$Arguments) {
    $text = & wiqd @Arguments
    if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
    $result = ($text -join "`n") | ConvertFrom-Json
    if ($result.status -cne 'success') { throw 'WIQD operation failed.' }
    return $result
}

$project = (Resolve-Path .\plugins\contoso).Path
$environment = 'dev'
$artifactDirectory = Join-Path $PWD '.artifacts'
New-Item -ItemType Directory -Path $artifactDirectory -Force | Out-Null
$package = Join-Path $artifactDirectory 'plugin-dev.zip'
$common = @('--path', $project, '--env', $environment, '--json')

Invoke-WiqdJson (@('plugin', 'validate', '--mode', 'source') + $common) | Out-Null
Invoke-WiqdJson (@('plugin', 'provision') + $common) | Out-Null
Invoke-WiqdJson (@('plugin', 'validate', '--mode', 'source') + $common) | Out-Null
Invoke-WiqdJson (@('plugin', 'package', '--output', $package) + $common) | Out-Null
if (-not (Test-Path -LiteralPath $package -PathType Leaf)) { throw 'Package output is missing.' }
$validation = Invoke-WiqdJson (@('plugin', 'validate', '--mode', 'package', '--package-file', $package) + $common)
$validation | ConvertTo-Json -Depth 100 | Set-Content -LiteralPath (Join-Path $artifactDirectory 'validation.json')

包模式会将已生成的 ZIP 提交到平台的包验证服务并报告其发现。 它不生成 ZIP 或自动登录,也不会建立运行时行为、连接就绪情况、远程服务运行状况或合作伙伴中心接受度。 它需要经过身份验证的服务访问权限,而不是脱机拉取请求检查。 缺少身份验证、服务故障或程序包被拒绝会阻止候选。

预配通常先于打包,因为它写入所选环境文件以及该打包消耗的内容 TEAMS_APP_ID 。 如果环境已绑定标识,并且不需要预配更新,请省略针对该现有状态的预配命令和包。 重新预配使用该标识,但全新签出不会自动保留该标识。 在两次运行之间安全地保留稳定 ID;请勿将环境文件、用户密钥文件、身份验证缓存或整个工作区作为项目发布。

不要在超时后自动重试预配或发布。 在授权重新运行之前,请检查现有操作和资源。

测试和评估已部署的候选项

在每个目标体验中测试候选人,包括其所需的连接、权限、技能和远程服务。 包验证不会确定每种功能在运行时都正常工作。

对于包含声明式代理的插件,请添加质量关口:

  1. 标识部署的声明性代理组件的游戏 ID。 不要替换独立插件的目录标题 ID。
  2. 为代表性任务准备已审阅的提示文件和接受阈值。 将候选项与基线进行比较时,保持套件不变。
  3. 在预期运行程序上配置评估 CLI 的 Microsoft 365 代理连接身份验证和所需的租户批准。 单独配置所选评委的凭据,并在 CI 之外完成评估 CLI 所需的 EULA 同意。
  4. 针对已部署的组件运行 wiqd agent eval ,并将结果与候选项一起保留。
  5. 如果评估失败、未达到阈值或运行程序无法进行身份验证,则阻止发布。

此示例评估工作区中 evals\contoso 已部署的代理。 将已审阅的提示文件置于 evals\contoso\evals\prompts.json,相对于签出根目录。 输出路径将相对于该工作区进行解析。 替换 <deployed-agent-title-id> 为候选组件的游戏 ID。 阈值 0.85 是一个示例;选择方案所需的质量栏。

$ErrorActionPreference = 'Stop'
$PSNativeCommandUseErrorActionPreference = $false
$agentId = '<deployed-agent-title-id>'
$text = wiqd agent eval --path .\evals\contoso --agent-id $agentId --env dev --threshold 0.85 --output .evals\results.json --json
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
$result = ($text -join "`n") | ConvertFrom-Json
if ($result.status -cne 'success') { throw 'Agent evaluation failed.' }

WIQD Eval 命令参考文档仅提示工作区和显式代理 ID。 评估工作流文档阈值处理:阈值未命中和上游失败都返回非零退出,JSON 中的错误代码不同。

生命周期刷新令牌不对评估进行身份验证。 评估 CLI 使用自己的 Microsoft 365 身份验证,而法官使用单独的 GitHub Copilot 或 Azure 凭据。 WIQD 源不为任意托管运行程序提供完整的无人参与评估凭据启动。 在使其成为自动门之前,先对您的跑步者进行设置;如果它不能在无人值守的情况下运行,则需要授权评估及其证据,而不是将跳过运行视为成功。

wiqd agent eval 不是全插件评估器,也不评估独立技能、根连接器或自定义引擎代理。 对于这些功能,请保留验证 和测试插件所需的组件和目标体验测试。

如果测试人员需要直接访问,请明确授权受众并遵循 WIQD 插件共享。 共享需要 AGENT_SCOPE=shared 在所选环境文件和相应的共享部署中;为环境 dev 命名不会建立该范围。 不要重新标记个人部署或复制其 ID 来绕过共享要求。

将已批准的更新提交到组织应用目录

使用受保护的发布作业将更新提交到组织应用目录。 候选测试不授权生产变化或管理员批准。

发布更新:

  1. 批准候选源版本、程序包版本、验证结果、适用的评估证据以及预期的生产受众。
  2. 使发布目标的已建立环境状态可用于作业。 保留其现有插件标识以进行更新,而不是在每次运行时创建新的应用注册。
  3. 如果版本使用与测试候选项不同的环境配置或插件资源标识,请对该目标重复受影响的预配、打包、验证和测试。
  4. 如果只有经过身份验证的 Microsoft 365 标识更改,请验证其租户、委派的许可、权限和对所需操作的访问权限。 仅身份验证标识更改不需要重新生成包。
  5. 确认发布目标的包和部署通过适用的测试。 如果有效配置、包和部署状态未更改,请重用候选证据,而无需重复目标验证。
  6. 通过 WIQD 提交发布目标的预配项目并记录结果。
  7. 将提交交给管理员批准,然后验证更新的应用目录条目、包版本、可用性和用户体验。

验证发布目标并授权提交后,此命令会将所选项目的插件发布到组织应用目录。 prod 是一个示例环境名称;使用您配置的发布环境,该环境可以与用于候选测试的环境相同。

$ErrorActionPreference = 'Stop'
$PSNativeCommandUseErrorActionPreference = $false
$text = wiqd plugin publish --path .\plugins\contoso --env prod --json
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
$result = ($text -join "`n") | ConvertFrom-Json
if ($result.status -cne 'success') { throw 'Plugin submission failed.' }

将发布结果与发布记录一起保留。

wiqd plugin publish 通过 接受项目和环境,而不是之前生成的 ZIP --package-file。 验证捕获的 ZIP 并不能证明发布提交了这些确切的字节。 保持已批准的源和环境状态固定,限定固定 WIQD 版本的发布行为,并验证生成的提交版本。 不要将此描述为不可变的 ZIP 提升工作流。

WIQD 为以下分发路由提供单独的命令:

运算 结果 剩余操作
wiqd plugin publish 提交到租户组织应用目录 管理员批准后,用户才能发现插件
wiqd plugin share 指定用户或租户的直接访问 验证授权受众、安装和连接
wiqd publish pc 对于插件包 合作伙伴中心产品/服务准备、上传、授权提交和状态跟踪 Microsoft 控制认证和实时发布

对于公开提交,请按照 使用 WIQD 发布到合作伙伴中心。 市场身份验证独立于本文中使用的核心管道凭据。 无人参与提交需要显式授权和受信任的持久性运行器(具有先前建立的交互式卖家会话)和对其受保护的操作系统凭据存储的访问权限。 市场发布不支持干净运行程序、服务主体和工作负载标识身份验证;如果不满足这些运行器要求,请使用经过身份验证的运算符。

WIQD 不记录插件注册表插槽提升或回滚命令。 在发布之前建立受支持的替换或恢复过程,并且不要假定程序包更新还原单独操作的服务或权限。 关注 改进和更新插件 以进行推出验证和恢复计划。

保留证据并清理候选项

保留跟踪已批准更新所需的证据,而不会将租户凭据或评估数据暴露给未经授权的读取者。

  1. 保留已批准的源修订版本、WIQD 版本、程序包标识和版本、净化验证和评估结果以及发布状态。
  2. 限制评估结果访问,因为提示和响应可能包含组织数据。
  3. 在删除候选部署之前验证生产更新。
  4. 如果临时候选具有单独的资源标识并且不再需要,请显式授权其删除。 仅对候选环境和标识使用记录的 WIQD 插件删除命令 。

不要将破坏性清理作为无条件的管道阶段,也不要删除已发布插件的标识作为候选清理的一部分。 如果测试和发布使用相同的标识,请不要将其作为临时候选标识删除。