在 awesome-copilot 中用 Octopus Deploy MCP 定制 GitHub Copilot Agent 自动生成发布说明

导读

本文以社区仓库 awesome-copilot 中收录的 Octopus Deploy 发布说明 Agent（agents/octopus-deploy-release-notes-mcp.agent.md）为分析对象，讲解如何通过一条 .agent.md 文件把 GitHub Copilot 变身为一名称职的“发布说明技术作者”：借助 @octopusdeploy/mcp-server 提供的 Octopus Deploy API 工具，自动获取指定项目、环境与空间上的最新部署 Release，拉取该 Release 对应的 Git 提交（message、author、date），并整理成 Markdown 格式的完整发布说明。读完本文，你将掌握该 Agent 的 YAML Frontmatter 配置（MCP 服务启动方式、密钥注入、26 个可用工具的白名单机制）、提示词主体设计思路，以及如何在 VS Code 中安装启用并为自己的发布流程复刻这套配置。

一、Agent 定位：Octopus 部署管线里的“发布说明写手”

Octopus Deploy 是面向开发团队的部署自动化平台，一条典型的发布流程是：代码提交 → CI 构建产出 Release → Octopus 将 Release 部署到开发/预发/生产等不同环境。部署完成后，团队往往还需要一份“这次发版到底包含什么变更”的说明，供测试、产品与客户查阅。

在 awesome-copilot 中收录的这个 Agent（名为 octopus-release-notes-with-mcp）正是为这一场景设计的。它的目标极其聚焦：

• 作为一位资深技术写作者，为软件应用生成发布说明；
• 数据来源是 Octopus Deploy 中某次部署的高层发布信息，以及该 Release 关联的一批 Git 提交（每条包含 message、author、date）；
• 输出是 Markdown 列表格式的完整发布说明；
• 输出应保留重要细节，但对与发布说明无关的提交允许跳过。

从仓库组织方式看，该 Agent 由 GitHub 合作伙伴（partners）贡献，同时被注册进两处索引：

• Agent 目录索引 docs/README.agents.md：列出 Agent 名称、描述及一键安装入口；
• Partners 插件清单 plugins/partners/plugin.json：在 extensions.com.github.awesome-copilot.agents 中引用该文件，使其可随 partners@awesome-copilot 插件整体安装（见 plugins/partners/README.md 中的收录说明）。

二、Frontmatter 拆解：MCP 服务声明与最小权限工具集

Agent 的定义完全通过 Markdown 文件顶部的 YAML Frontmatter 声明，这也是本仓库所有 Agent 的统一规范（可参考 CONTRIBUTING.md 中“Adding an Agent”一节约定的元数据格式）。该文件的 Frontmatter 包含四块核心配置：

---
name: octopus-release-notes-with-mcp
description: Generate release notes for a release in Octopus Deploy. The tools for this MCP server provide access to the Octopus Deploy APIs.
mcp-servers:
  octopus:
    type: 'local'
    command: 'npx'
    args:
    - '-y'
    - '@octopusdeploy/mcp-server'
    env:
      OCTOPUS_API_KEY: ${{ secrets.OCTOPUS_API_KEY }}
      OCTOPUS_SERVER_URL: ${{ secrets.OCTOPUS_SERVER_URL }}
    tools:
    - 'get_account'
    - 'get_branches'
    - 'get_certificate'
    - 'get_current_user'
    - 'get_deployment_process'
    - 'get_deployment_target'
    - 'get_kubernetes_live_status'
    - 'get_missing_tenant_variables'
    - 'get_release_by_id'
    - 'get_task_by_id'
    - 'get_task_details'
    - 'get_task_raw'
    - 'get_tenant_by_id'
    - 'get_tenant_variables'
    - 'get_variables'
    - 'list_accounts'
    - 'list_certificates'
    - 'list_deployments'
    - 'list_deployment_targets'
    - 'list_environments'
    - 'list_projects'
    - 'list_releases'
    - 'list_releases_for_project'
    - 'list_spaces'
    - 'list_tenants'
---

1. name 与 description

• name：Agent 的唯一标识，即 octopus-release-notes-with-mcp；
• description：用于让 GitHub Copilot 判断“何时该启用该 Agent”，这里明确描述了功能边界——为 Octopus Deploy 中某个 Release 生成发布说明，工具经由 Octopus Deploy API 提供访问。因此描述应尽量具体、可检索，便于 Copilot 在收到“给某次 Octopus 发版写发布说明”类请求时自动命中该 Agent。

2. mcp-servers：本地启动的 MCP 服务

该 Agent 声明了一个名为 octopus 的本地 MCP 服务：

字段	值	说明
type	local	在本地以子进程方式启动的 MCP 服务
command	npx	通过 npx 直接拉起 npm 包，无需预先全局安装
args	-y、@octopusdeploy/mcp-server	-y 自动确认安装依赖，包名指向官方 Octopus Deploy MCP 服务器
env	OCTOPUS_API_KEY、OCTOPUS_SERVER_URL	注入 Octopus 实例访问所需的身份与地址

需要特别说明的是环境变量的取值语法 ${{ secrets.OCTOPUS_API_KEY }}：在 GitHub Copilot 的 VS Code / CCA 环境中，这类占位符会被替换为存储在仓库 Secret（或用户/组织安全配置）中的真实值。API Key 与 Server URL 属于敏感凭据，不应以明文写入 .agent.md；拷贝到仓库时应将其保存在安全的 Secret 存储中。这与仓库中“Custom Agents”的统一使用方法一致（详见 docs/README.agents.md 的 MCP Server Setup 说明：每个 Agent 可能依赖一个或多个 MCP 服务器，需要先配置好对应服务器再使用）。

3. tools：按需开放的 26 个 API 工具

与常见“把所有工具全部暴露给 Agent”的做法不同，该 Frontmatter 通过 tools 字段做了一次工具白名单裁剪——只把与查询部署与 Release 信息相关的 26 个工具暴露给 Copilot。按用途可大致归类为：

列表类（查询多个资源）

• list_spaces：列出 Octopus 中所有 Space（空间），用于定位用户指定空间；
• list_projects、list_releases、list_releases_for_project：枚举项目与 Release，其中 list_releases_for_project 是“按项目拿历史 Release”的关键入口；
• list_environments：列出环境，配合确定“最后部署到某环境”的 Release；
• list_deployments：列出部署记录，是判断“某 Release 是否已部署到目标环境、何时部署”的依据；
• list_deployment_targets、list_accounts、list_certificates、list_tenants：查询部署目标、账户、证书、租户等周边资源。

详情类（按 ID 取单个资源）

• get_release_by_id、get_deployment_process：获取 Release 与部署流程详情；
• get_task_by_id、get_task_details、get_task_raw：查询部署任务及其原始输出，可用于核对部署结果；
• get_deployment_target、get_current_user、get_tenant_by_id、get_tenant_variables、get_missing_tenant_variables、get_variables、get_branches、get_account、get_certificate、get_kubernetes_live_status：读取分支、变量、租户、Kubernetes 实时状态等元数据。

从该 Agent 的工作流（后文第四节）看，真正形成主链路的工具是：list_spaces → list_projects → list_releases_for_project / list_deployments / list_environments（定位“最新一次已部署 Release”）→ get_release_by_id / get_task_details（获取构建信息与提交列表）。而 get_account、get_certificate、get_kubernetes_live_status 等工具更多承担上下文补充角色，说明作者有意保留了更宽的查询面，以便 Agent 在信息不足时能自行探查。

三、提示词主体：从“人设”到“执行步骤”的三层设计

Frontmatter 之后是正文提示词，它完成了“Agent 该怎么工作”的完整定义，可以拆成三个层次来理解：

第一层：角色人设

# Release Notes for Octopus Deploy

You are an expert technical writer who generates release notes for software applications.

这里明确把 Agent 定位成“软件应用发布说明的资深技术作者”，让模型在后续生成中自然采用技术写作者的措辞与详略判断，而不是工程师口吻。

第二层：输入与输出契约

You are provided the details of a deployment from Octopus deploy including high level release nots with a list of commits, including their message, author, and date.
You will generate a complete list of release notes based on deployment release and the commits in markdown list format.
You must include the important details, but you can skip a commit that is irrelevant to the release notes.

三条约束分别锁定了：

• 输入：一次 Octopus 部署的详情，含高层发布说明，以及提交列表（每条含 message、author、date）；
• 输出格式：基于 Release 与提交整理成 Markdown 列表形式的完整发布说明；
• 取舍规则：必须保留重要细节，但允许跳过与发布说明无关的提交——这赋予 Agent 编辑裁量权，避免把 “chore/format” 之类噪音提交一股脑塞进面向读者的文档。

第三层：执行步骤（操作序列）

In Octopus, get the last release deployed to the project, environment, and space specified by the user.
For each Git commit in the Octopus release build information, get the Git commit message, author, date, and diff from GitHub.
Create the release notes in markdown format, summarising the git commits.

这是整个提示词中“可执行性”最强的部分，规定了三步走的调用链：

1. 定位 Release：依据用户给出的 project（项目）、environment（环境）与 space（空间），在 Octopus 中取得“最后一次成功部署到该环境的 Release”；
2. 补全提交细节：对 Octopus Release 构建信息中的每个 Git 提交，从 GitHub 获取 commit message、author、date 以及 diff；
3. 汇总成文：以 Markdown 格式创建发布说明，对 Git 提交做摘要式归纳。

值得注意的细节是：Octopus 的 Release 构建信息本身会携带提交列表，但 diff 细节需要回到 GitHub（即代码托管端）补齐，因此 Agent 通常还需要具备访问 GitHub 仓库/提交的能力，才能完成“根据 diff 判断某次提交到底改了什么、是否值得写进发布说明”这一步骤。

四、Agent 工作流推演：一次完整的“发版说明生成”会话

把 Frontmatter 中授权的工具与提示词中的执行步骤拼接起来，可以推演出 Agent 一次典型会话的处理过程：

Step 1｜确定作用域 用户给出“空间 Space、项目 Project、环境 Environment”。Agent 依次调用 list_spaces、list_projects、list_environments，把自然语言中的名称解析为 Octopus 中的真实标识。

Step 2｜找到“最后部署”的 Release 调用 list_releases_for_project（或 list_releases）拿到 Release 列表，再用 list_deployments 核对各 Release 在目标环境的部署记录，锁定最后一次成功部署的 Release；随后用 get_release_by_id 取回该 Release 的详细构建信息（其中包含 Git 提交清单）。如有必要，还可通过 get_task_details / get_task_raw 检查部署任务结果，确认确实部署成功。

Step 3｜从 GitHub 补齐每个提交的细节 对构建信息中的每个提交，获取其 message、author、date 与 diff。这一步是提示词显式要求的“提交级取证”，确保发布说明写的是真实变更而非模型臆测。

Step 4｜撰写 Markdown 发布说明 技术写作者人设开始工作：按提交逐一归纳，用 Markdown 列表输出，保留重要变更（新功能、修复、破坏性变更等），过滤无关提交，最终呈现可直接粘贴到 Release Notes 页面的成品。

整个过程无需人工整理提交日志，正好补上“Octopus 部署完成 ≠ 变更已对外传达”这一环节的空白。

五、安装与启用：三条途径任选

方式一：在 docs 索引页一键安装

该 Agent 已被登记进 docs/README.agents.md 的 Agent 表格，条目后附有 VS Code / VS Code Insiders 的一键安装徽章，点击即可把该 .agent.md 安装到编辑器。仓库代理类目下（octopus 的 MCP 配置也可从同表内的 Install MCP 徽章直接写入 VS Code）。

方式二：通过 partners 插件安装

由于该 Agent 是 GitHub 合作伙伴贡献内容，也属于 partners 插件的一员（见 plugins/partners/plugin.json 与 plugins/partners/README.md）。安装整个插件即可连同其 MCP 依赖一起获得：

copilot plugin install partners@awesome-copilot

方式三：手动下载并放入仓库

参考 docs/README.agents.md 的使用说明：

1. 下载 agents/octopus-deploy-release-notes-mcp.agent.md 文件并添加到你的仓库；
2. 按 Frontmatter 要求配置 octopus MCP 服务器（npx 启动 @octopusdeploy/mcp-server），并确保 OCTOPUS_API_KEY、OCTOPUS_SERVER_URL 两个 Secret 在环境中可用；
3. 在 VS Code Chat 界面、CCA（Copilot coding agent）或 Copilot CLI 中选用该 Agent。

启用前置条件

安装完成后还不能直接使用，需要满足三项运行时前提：

• Node.js/npx 可用：MCP 服务器以 type: local + npx 启动，运行环境必须能联网拉取 @octopusdeploy/mcp-server；
• Octopus 凭据就绪：OCTOPUS_API_KEY（API Key）与 OCTOPUS_SERVER_URL（形如 https://yourinstance.octopus.app）必须指向有权限读取对应 Space/项目/环境数据的账户；
• Git 提交可访问：生成发布说明需要读取 GitHub 上的提交 message、author、date 与 diff，因此仓库需对 Octopus 构建信息中引用的提交具备读取权限。

六、复用与定制建议

在理解了该 Agent 的组成之后，你可以低成本地为自己的团队定制同类 Agent：

• 调整工具白名单：如果团队不使用租户（Tenant）或多账户体系，可以去掉 list_tenants、get_tenant_by_id、get_tenant_variables、get_missing_tenant_variables、list_accounts 等工具，进一步收窄权限面；
• 定制输出规范：在第三层“执行步骤”后追加格式要求，例如要求按 ### 新特性 / ### 缺陷修复 / ### 其他变更 分组、标注是否含破坏性变更、附上 PR 编号，或要求输出对应英文/中文双语版本；
• 切换过滤策略：原提示词允许“跳过无关提交”，若你希望更严格的审计口径（如无一行遗漏），可以改为“对每个提交给出保留或忽略的理由”；
• 接入发布流程：可将会话入口固化进团队约定，例如约定提问模板“为 {project} 部署到 {environment}（Space: {space}）的最新 Release 生成发布说明”，让 Agent 直接按模板触发。

需要留意的是：Agent 的 MCP 配置与 Secret 引用方式会随 GitHub Copilot 产品能力迭代而变化，本仓库文件为当前收录形态；在复用时应以你所使用的 Copilot 版本所支持的安全配置语法为准，并始终避免在纯文本 Agent 文件中写入明文凭据。

总结

Octopus Deploy 发布说明 Agent 是一个“小而完整”的 Copilot Agent 范本：它用 YAML Frontmatter 声明了本地 MCP 服务的启动方式、注入密钥所需的环境变量，以及经过裁剪的 26 个 Octopus API 工具白名单；再用简短提示词定义了“技术作者人设 → 输入输出契约 → 三步执行序列”。对开发团队而言，把这条 agents/octopus-deploy-release-notes-mcp.agent.md 接入日常发版流程，即可让“部署完成”与“发布说明就绪”之间的时间差趋近于零。