把 Copilot 嵌进 Java 工具链：从终端 CLI 到 SDK 与插件

#

GitHub Copilot 早已不只是 IDE 里的补全。对 Java 团队而言，更现实的问题是：Issue 能否在云端自动变成可 review 的 PR？CI 里能否跑「只打标签、不写代码」的推理步骤？JMeter、Office 或自研桌面产品能否内嵌同一套 agent，而不是让用户在外部 Chat 与工具之间来回粘贴？本文围绕 Copilot CLI、Copilot cloud agent、Agentic Workflows（gh aw） 与 Copilot SDK for Java 四条主线，说明机制、约束与可落地的最小配置；演示仓库细节（如 brunoborges/todo-app）仅作行为示例，不当作产品契约。

多入口 agent：同一仓库，不同触发面

#

为什么

#

Java 工作流分散在 GitHub Issue、IntelliJ/Eclipse、终端脚本和 Slack/Teams/Jira 等协作面。若每个入口各自维护一套 prompt，很快会出现「云端 agent 与本地 CLI 行为不一致」的漂移。官方文档将 Copilot cloud agent 描述为在 GitHub Actions 驱动的临时开发环境 中探索代码、修改并提 PR 的 agent；入口则覆盖 Issue 指派、IDE、gh、Mobile、MCP，以及 Jira、Slack、Teams、Azure Boards、Linear 等集成（见 启动 cloud agent 会话）。演讲者观点：「prompt once, agents everywhere」是对这一矩阵的概括，并非文档固定标语。

机制与约束

#

• 将 Issue 指派给 Copilot 会触发后台 coding 会话，完成后 raise pull request 并请求人工 review。
• 无模型选择器的入口默认使用 Auto 模型（可用性与限流下的路由选型）。
• Cloud agent 默认 MCP 含 GitHub MCP（仓库只读，可扩权限）与 Playwright MCP（读页、交互、截图；默认仅 localhost / 127.0.0.1）——见 MCP 与 cloud agent。

怎么做

#

gh issue edit 1 --repo org/todo-app --add-assignee "@copilot"
# 或创建时指派
gh issue create --repo org/todo-app \
  --title "Show timestamps on todo items" \
  --body "Add createdAt/completedAt to UI." \
  --assignee "@copilot"

常见误区

#

• 把「指派 Issue」等同于「本地 IDE 里开 Copilot Chat」——前者在 云端 Actions 环境 跑完整仓库任务，后者不自动提 PR。
• 假设 Playwright 每次都会在 PR 里贴截图——官方只保证能力存在，是否贴图取决于任务与 agent 决策。

Copilot CLI：终端 agent、权限与 slash 命令

#

为什么

#

探索期任务（脚手架、一次性脚本、本地多文件重构）需要 低摩擦的 REPL：一句话启动、可读目录、可恢复会话。若每次都走 GUI，很难与 cron、gh 脚本或 SSH 会话结合。

机制与约束

#

CLI 命令参考 中与现场 demo 对齐的符号包括：

官方明确建议：自动批准模式应在 VM、容器或专用系统 上运行（配置 CLI 权限）。演讲者观点：将 Docker Sandboxes 与 YOLO 并列是隔离宿主机风险的产品组合建议；「Docker Sandbox」不是 Copilot CLI 文档中的内置子命令——Docker 侧见 Sandboxes 中的 Copilot。

怎么做

#

# 非 YOLO：适合日常
copilot -p "Explain this Maven multi-module layout"

# 高风险：仅隔离环境
copilot --yolo -p "Refactor package structure and run ./mvnw test"

REPL 内：/plan 先规划；/context 查窗口；!git status 直接跑 git。

常见误区

#

• 在生产笔记本上长期开 /yolo——官方风险提示与现场演示一致：agent 可能直接执行 rm 等操作。
• 把 docker run … ghcr.io/github/copilot-cli 当作唯一安装路径——copilot-cli README 推荐 copilot-install、brew、npm -g @github/copilot 等。

云端 Coding Agent：Issue → PR 与 Playwright

#

为什么

#

「实现 + 跑测试 + UI 自检 + 给 reviewer 证据」若拆成人工多步，延迟和上下文切换成本很高。Cloud agent 把实现与验证尽量收进 一次后台任务，人主要做 review-only。

机制与约束

#

演示仓库 brunoborges/todo-app 中，Issue 要求为 todo 项展示创建/完成时间；agent 在实体已有 createdAt/completedAt 的前提下补 Thymeleaf 展示（演示内容，非官方样例）。

怎么做

#

gh pr checkout 2 --repo brunoborges/todo-app
./mvnw spring-boot:run

模板片段（与 PR OCR 一致）：

<span class="todo-timestamp" th:if="${todo.createdAt != null}"
  th:text="${'Created: ' + #temporals.format(todo.createdAt,'MMM d, yyyy HH:mm')}"></span>
<span class="todo-timestamp" th:if="${todo.completedAt != null}"
  th:text="${'Completed: ' + #temporals.format(todo.completedAt,'MMM d, yyyy HH:mm')}"></span>

常见误区

#

• 认为 cloud agent 只在 main 分支上工作——实际在 临时 Actions 环境 checkout 并改代码；本地需 gh pr checkout 验证。
• 忽略 Playwright 的 localhost 限制——测远程 staging 需在 自定义环境 中显式配置。

给云端 agent 配 JDK：copilot-setup-steps.yml

#

为什么

#

GitHub-hosted Ubuntu 24.04 镜像默认 JDK 17（见 runner 软件表）。若 pom.xml 使用 <release>25</release>，agent 内 mvn test 会报 release version 25 not supported，PR 可能在 CI 阶段集体失败——这与「agent 已写完代码」无关，而是 启动前环境未对齐。

机制与约束

#

• 路径：.github/workflows/copilot-setup-steps.yml
• 必须包含名为 copilot-setup-steps 的 job；在 agent 开始工作之前 执行。
• 文件须在 默认分支 上才会被拾取（可用 workflow_dispatch 自测）。
• 文档：配置 cloud agent 开发环境

怎么做

#

# .github/workflows/copilot-setup-steps.yml
name: Copilot Coding Agent · Setup Steps
on: workflow_dispatch
jobs:
  copilot-setup-steps:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: "25"
      - run: java -version && ./mvnw -q -v

gh aw init 也会生成同名文件（Agentic Workflows 与 cloud agent 共用钩子）。

常见误区

#

• 只在 feature 分支添加 setup 文件——未合并到 default branch 时 agent 看不到。
• 只改 GitHub Actions CI workflow，不改 copilot-setup-steps——两者执行时机不同。

Code Review Agent：写—评—改闭环

#

为什么

#

主 coding agent 的 diff 常有可预测的 nit：Thymeleaf 空值、CSS 布局、测试遗漏。若全部依赖人工 comment，reviewer 时间耗在格式层而非业务风险。

机制与约束

#

• 显式 PR review：在 Reviewers 中选择 Copilot（使用 Copilot code review）。
• Cloud agent 内置二次审查：文档记载 agent 生成代码时会做安全扫描，并 gets a second opinion on its code with Copilot code review（配置 agent 设置）——与 PR 上的独立 review UI 相关但不完全等同。
• 以下 Thymeleaf/CSS 级评论来自现场 OCR，非官方模板：

怎么做

#

在 PR 界面触发「Review with Copilot」，或在流程中依赖 cloud agent 内置 review。修复示例：

.todo-timestamp {
  display: block;
  font-size: 0.75rem;
  opacity: 0.6;
}

常见误区

#

• 把「内置 second opinion」当成「一定会在 PR Conversation 里出现与 OCR 相同的逐行评论」。
• 期望 Copilot 给出 Approve——文档明确其 review 类型为 Comment，不构成 approve/request changes。

Agentic Workflows：Markdown prompt 与 safe-outputs

#

为什么

#

CI 里嵌入 LLM 时，最大风险是 agent 获得 contents: write 后误改仓库、推分支或删资源。Agentic Workflows 把「推理」与「写操作」拆开：主 job 只读，写操作仅能走编译期校验的 safe-outputs 白名单。

机制与约束

#

仓库以 github/gh-aw 为准（安装：curl -sL …/install-gh-aw.sh | bash，见 install.md）：

• 源文件：Markdown + YAML front matter；变更后须 gh aw compile 生成 .lock.yml（勿手改）。
• engine: copilot（亦支持 claude、codex、gemini 等）。
• 生产建议 strict: true；主 job 禁止 直接 issues: write / pull-requests: write / contents: write。
• Job summary 中的 MCP Gateway、Agent Workflow Firewall (AWF)、Firewall Activity 与 安全架构 一致。

怎么做

#

---
on:
  issues:
    types: [opened]
safe-outputs:
  add-labels:
    allowed: [effort:small, effort:medium, effort:large]
  add-comment:
    max: 1
engine: copilot
strict: true
---
Read the issue; apply exactly one effort:* label and one brief comment.

gh aw compile
git add .github/workflows
git commit -m "feat: agentic effort labeler"

常见误区

#

• 手改 .lock.yml——下次 compile 会覆盖，且可能绕过校验。
• 使用已弃用的 githubnext/gh-aw 安装路径——以 github/gh-aw 文档为准。

自定义 LabelOps：/effort 与 Effort Labeler

#

为什么

#

并非每个 Issue 都需要 coding agent 写代码。体量估算、实现提示、标签分类适合 只读推理 + 受限写入（标签/评论），供排期或后续再 assign coding agent。

机制与约束

#

• /effort 是演示仓库自定义 slash，非 GitHub 全局内置命令；官方仅提供 on.slash_command 范式（triggers、safe-outputs）。
• 历史 issue #154 上可见 effort: medium 与实现要点（BufferedImage、bbox 等）——演示 OCR。
• 演讲者观点：现场 demo 曾遇「Effort Labeler is disabled」；workflow 列表可作旁证，无官方「必成功」保证。

怎么做

#

在 Issue 评论输入 /effort（仓库已配置对应 agentic workflow 时）。等效事件载荷概念：

{ "comment": { "body": "/effort" }, "issue": { "number": 164 } }

常见误区

#

• 把 Effort Labeler 当成开箱即用的 GitHub 产品功能。
• workflow 被 disable 后仍指望评论触发——需先检查 Actions 启用状态与 default branch 上的 lock 文件。

/fleet：CLI 内并行 sub-agent

#

为什么

#

单线程 LLM 处理多语言翻译、多模块脚手架时墙钟时间过长。/fleet 由主 agent 拆分子任务，sub-agent 并行执行（fleet 概念）。

机制与约束

#

• 主 agent 作 orchestrator，负责依赖与合并。
• 并行放大 prompt 漂移（例如对 <code> 块误加 RTL CSS）——需在 AGENTS.md / copilot-instructions.md 写明禁止项。
• UI 上并行任务列表 不一定对应当前 demo 仓库（演讲者已提示读图核对）。

怎么做

#

copilot --yolo -p "/fleet translate the UI to Portuguese and Spanish"

主 agent 典型分解（演讲者演示归纳）：i18n 配置 → messages.properties → Thymeleaf → 语言切换 CSS → ./mvnw test。

常见误区

#

• 忘记把 --yolo 传给需要自动执行子任务的会话——子 agent 可能停在确认步骤。
• 未在指令中约束并行子 agent 的目录边界，导致多子任务改同一文件冲突。

Copilot SDK for Java：协议握手与 JMeter 插件

#

为什么

#

当 agent 需要嵌进 已有 Java 桌面/服务器产品（JMeter GUI、Office 插件、浏览器扩展）时，解析 CLI stdout 不可靠：需要稳定会话、权限回调与 协议版本握手。官方 copilot-sdk-java 通过子进程启动 Copilot CLI 作 server；社区仓库 copilot-community-sdk/copilot-sdk-java 已 archived 并指向官方库。

机制与约束

#

• Maven 坐标（README）：com.github:copilot-sdk-java；要求 Copilot CLI 1.0.17+、Java 17+（推荐 JDK 25 以使用 virtual threads）。
• 源码 CopilotClient.verifyProtocolVersion：MIN_PROTOCOL_VERSION = 2，经 connect / ping RPC 交换 protocolVersion；不匹配则 fail fast（与现场堆栈一致）。
• 官方 README「Projects Using This SDK」列出 brunoborges/jmeter-copilot-plugin——集成模式存在；57.2/sec 等指标仅来自演示 OCR。

怎么做

#

import com.github.copilot.sdk.CopilotClient;
import com.github.copilot.sdk.json.*;

try (var client = new CopilotClient()) {
    client.start().get();
    var session = client.createSession(
        new SessionConfig()
            .setModel("auto")
            .setOnPermissionRequest(PermissionHandler.APPROVE_ALL))
        .get();
    var result = session.sendAndWait(
        new MessageOptions().setPrompt(
            "Emit JMeter .jmx: 50 users, 5 min, GET http://localhost:8080/"))
        .get();
    // SaveService.loadTree(...) → 挂到 JMeter 测试树
}

排错（可复现日志）：对齐 SDK 与本地 copilot CLI 版本。

SDK protocol version mismatch: SDK expects version 2, but server reports version 3
Please update your SDK or server to ensure compatibility.

常见误区

#

• 继续使用已归档社区坐标或旧包名 com.github.copilot.sdk（以官方 README 为准）。
• 升级 CLI 却不升级 SDK（或反之）——协议号变化会直接导致启动失败，而非「模型回答变差」。

CLI 还是 SDK：选型与仓库级契约

#

为什么

#

全 CLI 难以嵌入产品 UI；全 SDK 又浪费在一次性脚本上。更稳妥的是：探索与自动化脚本用 CLI；需要进程内会话、权限 UI、协议错误回流用 SDK。官方分别定位终端交互与 程序化控制 Copilot CLI，无单一「决策矩阵」页——下表为工程归纳。

机制与约束

#

• .github/copilot-instructions.md：仓库级自定义指令，cloud agent 与 code review 可消费（可用 frontmatter excludeAgent 排除）。
• AGENTS.md：CLI 从仓库根或 COPILOT_CUSTOM_INSTRUCTIONS_DIRS 读取；GitHub 仓库亦可多处放置，路径最近者优先（CLI 自定义指令）。不宜夸大为「IDE/CLI/云端 100% 同文件同语义」——IDE 另有独立配置路径。
• MCP：cloud agent 文档警告第三方 MCP 可能影响 performance and quality，建议 tools allowlist。演讲者转述：keynote 中「200+ 工具反而增错率」未能在官方文档中找到同等表述。

# AGENTS.md（示例片段）
- Java release: 25 (see pom.xml).
- Build: ./mvnw test
- Never apply RTL to <pre>/<code> (i18n).
- UI changes: prefer Playwright MCP on localhost; attach screenshot in PR when applicable.

常见误区

#

• 堆叠过多 MCP 服务器却不配 allowlist——工具发现噪声上升，延迟增加。
• 只写 copilot-instructions.md 却忽略 CLI 侧的 AGENTS.md（或相反），导致本地与云端行为分裂。

演示失败同样是边界样本

#

两场「失败」反而标出了工程边界：

1. Effort Labeler 未跑通——自定义 workflow 的生命周期与 Actions 启用状态相关，不是模型能力问题。
2. JMeter 插件 SDK v2 / CLI v3 不匹配——说明集成点是 版本化的 RPC 协议，而非聊天 API 字符串。

把这两类错误纳入 runbook（对齐 copilot-setup-steps、对齐 SDK/CLI、检查 workflow disable），比只看 happy path 更能指导生产落地。

参考与延伸阅读

#

• Copilot cloud agent 概念
• 启动 cloud agent 会话（含指派 Issue）
• Cloud agent 的 MCP 默认能力（含 Playwright）
• 自定义 cloud agent 环境（copilot-setup-steps）
• Ubuntu 24.04 runner 软件列表（Java 版本）
• 使用 Copilot code review
• 配置 cloud agent 校验与二次审查
• Copilot CLI 命令参考（slash 表）
• Copilot CLI 权限与 YOLO
• /fleet 并行 sub-agent 概念
• github/gh-aw 仓库
• Agentic Workflows 安全架构（AWF / MCP Gateway）
• 官方 Copilot SDK for Java
• CopilotClient 源码（协议握手）
• 仓库 copilot-instructions.md
• Awesome Copilot 社区合集