GHCP CLI SDK PR AUTOMATION

车队合规代理演示

演示GitHub Copilot CLI/SDK集成用于企业车队管理

此演示展示了一个基于Python的合规代理，该代理使用GitHub Copilot在一组微服务中自动执行组织策略 软件开发工具包 能力。

______________________________________________________________________

此演示实现了什么

此演示实现 全车队自动化合规执法 -一个AI代理，可以审计多个微服务，检测策略违规，应用修复程序，并使用证据创建Pull Request。

💡 生产模式与演示模式： 在生产场景中，此代理将运行 无头 --在没有任何用户界面的情况下，由时间表或事件触发，一个接一个地处理存储库。此示例提供 两种跑步方式: - React图形用户界面 (ui/)--一个用于观察代理行为的可视化仪表板。非常适合演示和了解SDK如何实时编排工具。 - 控制台模式 (agent/fleet_agent/agent_loop.py)--一个无头入口点，从中加载所有存储库 config/repos.json 并对其进行处理 在单个SDK会话中按顺序执行一个接一个。直接用 python -m fleet_agent.agent_loop 从 agent/ 目录。 在这两种模式中， 仍需要有人参与 --代理通过Pull Requests提出更改，人工审核和批准。 无需自然语言输入。 用户提供的唯一输入是中的存储库URL列表 config/repos.json发送到Copilot SDK的提示被烘焙到应用程序代码中——没有交互式提示或对话界面。

SDK和AI功能

展示合规性特征

______________________________________________________________________

🏗️ 建筑

Solution Architecture

┌──────────────────────────────────────────────────────────────────────────────┐
│                         FLEET COMPLIANCE AGENT                               │
├──────────────────────────────────────────────────────────────────────────────┤
│  ┌──────────────────────────────────────────────────────────────────────┐    │
│  │              🖥️ Visual UI (React + FastAPI)                          │    │
│  │  ┌─────────────────┐    WebSocket    ┌─────────────────┐             │    │
│  │  │  React Frontend │◄───────────────►│ FastAPI Backend │             │    │
│  │  │  localhost:3000 │   (streaming)   │  localhost:8000 │             │    │
│  │  └─────────────────┘                 └────────┬────────┘             │    │
│  └───────────────────────────────────────────────┼──────────────────────┘    │
│                                                  │ imports                   │
│                                                  ▼                           │
│  ┌────────────────────────────────────────────────────────────────────────┐  │
│  │              🧠 Agent Core (agent_loop.py)                             │  │
│  │  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐                 │  │
│  │  │   GitHub    │    │  Knowledge  │    │   Copilot   │                 │  │
│  │  │   Repos     │    │    Base     │    │    SDK      │                 │  │
│  │  │  (Target)   │    │   (RAG)     │    │ (Agent Brain)│                │  │
│  │  └──────┬──────┘    └──────┬──────┘    └──────┬──────┘                 │  │
│  │         │                  │                  │                        │  │
│  │         ▼                  ▼                  ▼                        │  │
│  │  ┌─────────────────────────────────────────────────────────────┐       │  │
│  │  │          13 CUSTOM TOOLS (Registered with SDK)              │       │  │
│  │  │  rag_search → clone → detect_drift → security_scan →        │       │  │
│  │  │  create_branch → apply_patches → get_approvals →            │       │  │
│  │  │  run_tests → read_file → fix_code → commit → push → PR      │       │  │
│  │  └───────────────────────────┬─────────────────────────────────┘       │  │
│  └──────────────────────────────┼─────────────────────────────────────────┘  │
│                                 │                                            │
│         ┌───────────────────────┼────────────────────┐                       │
│         ▼                       ▼                    ▼                       │
│  ┌─────────────┐          ┌─────────────┐      ┌─────────────┐               │
│  │ Change Mgmt │          │  Security   │      │   GitHub    │               │
│  │ MCP Server  │          │ MCP Server  │      │     CLI     │               │
│  │ (Approvals) │          │   (Scans)   │      │   (PRs)     │               │
│  └─────────────┘          └─────────────┘      └─────────────┘               │
│     :4101                    :4102                 gh                        │
└──────────────────────────────────────────────────────────────────────────────┘

组件

______________________________________________________________________

🎬 观看演示


*点击上图在YouTube上观看完整的演示视频*

______________________________________________________________________

💡 为什么选择GitHub Copilot SDK？

GitHub Copilot 命令行工具 通常用于交互式自然语言对话——开发人员键入问题并获得回复。但如果你能利用同样的人工智能能力呢 以编程方式?

这 GitHub Copilot SDK 完全解锁了这个。通过Python SDK公开Copilot CLI，它从对话工具转换为 可编程智能体大脑.

工作原理： Python SDK在中生成了Copilot CLI 服务器模式 并通过以下方式进行通信 JSON-RPC。您的代码注册工具、发送提示和接收事件，而CLI处理身份验证、模型通信和令牌管理。

Your Application
       ↓
   SDK Client
       ↓ JSON-RPC
Copilot CLI (server mode)
       ↓
  GitHub Copilot API

# The SDK starts the CLI in server mode and manages the session
client = CopilotClient()
await client.start()  # Spawns copilot CLI as background process

session = await client.create_session(
    system_message={"mode": "replace", "content": SYSTEM_PROMPT},
    tools=[clone_tool, detect_drift_tool, apply_patches_tool, ...],
    available_tools=["clone_repository", "detect_compliance_drift", ...],
    on_permission_request=lambda req, inv: PermissionRequestResult(kind="approved"),
)
await session.send("Enforce compliance on contoso-payments-api")
# SDK autonomously calls tools, reasons over results, and completes the workflow

关键见解： 代替人工打字提示， 代码驱动对话 -向SDK发送结构化提示，注册自定义工具，并让SDK自主决定执行路径。

此模式允许 企业自动化场景 仅使用交互式CLI是不可能的。

🔑 交互式与嵌入式： 开发人员通常在VS代码中使用GitHub Copilot CLI或代理模式 交互式地 -实时提问、获取建议和迭代。在这个例子中，我们采取了一种根本不同的方法： 我们将GitHub Copilot SDK直接嵌入到自主代理中SDK成为全自动工作流的推理引擎，而不是交互式助手。

⚠️ SDK预览通知： GitHub Copilot SDK目前位于 预览。此演示引脚版本 github-copilot-sdk==0.2.2 （协议v3）。看 升级Copilot SDK 了解详情。

______________________________________________________________________

🔄 代理人如何工作

代理在中执行合规工作流 三个阶段:

第一阶段：发现和分析（在任何代码更改之前）

第2阶段：代码修改（进行更改）

第3阶段：验证和批准（代码更改后）

视觉时间轴

ORIGINAL CODE                              MODIFIED CODE
     │                                          │
     ▼                                          ▼
┌──────────────────────────────────────────────────────────────────────────┐
│  clone → detect_drift → security_scan    │   apply_patches → run_tests   │
│         (analyze original)               │   → fix_code (if needed)      │
│                                          │   (modify & validate)         │
│  ◄────── BEFORE changes ──────►          │  ◄────── AFTER changes ─────► │
└──────────────────────────────────────────────────────────────────────────┘
                                       ▲
                                 Branch created here

______________________________________________________________________

⚡ 入门指南

平台： 这些说明适用于 视窗 使用PowerShell。为其他平台调整路径。

先决条件

Azure AI搜索知识库（FoundryIQ）要求

此项目使用 Azure AI搜索知识库 （FoundryIQ）用于RAG，而不是Azure OpenAI矢量存储。

FoundryIQ设置管道

┌──────────────────┐     upload      ┌──────────────────────┐
│  knowledge/*.md  │ ──────────────► │  Azure Blob Storage  │
│  (policy docs)   │                 │  (container)         │
└──────────────────┘                 └──────────┬───────────┘
                                                │
                                                │ points to
                                                ▼
┌───────────────────────────────────────────────────────────────┐
│               Azure AI Search (FoundryIQ)                     │
│  ┌─────────────────────────────────────────────────────┐      │
│  │  Knowledge Source                                   │      │
│  │  • Data source: Azure Blob Storage container        │      │
│  │  • Auto-indexes documents on creation               │      │
│  │  • Creates a local index in FoundryIQ               │      │
│  └──────────────────────┬──────────────────────────────┘      │
│                         │ consumed by                         │
│                         ▼                                     │
│  ┌─────────────────────────────────────────────────────┐      │
│  │  Knowledge Base                                     │      │
│  │  • Powered by LLM (gpt-4o)                          │      │
│  │  • Output mode: Extractive data                     │      │
│  │  • Reasoning effort: low                            │      │
│  │  • Custom instructions for retrieval                │      │
│  └─────────────────────────────────────────────────────┘      │
└───────────────────────────────────────────────────────────────┘

RBAC： 用户必须通过以下方式访问Azure AI搜索知识库 DefaultAzureCredential （托管身份、Azure CLI等）。

注： 使用Azure OpenAI 仅 通过内部知识库进行重新排名——代理代码不会直接调用Azure OpenAI。所有LLM推理都来自GitHub Copilot SDK。

______________________________________________________________________

设置步骤

1.克隆此存储库

git clone https://github.com/MSFT-Innovation-Hub-India/GHCP-CLI-SDK-PR-AUTOMATION.git
cd ghcp-cli-sdk-sample1

2.创建目标存储库

该代理在外部GitHub存储库上运行。推送示例仓库：

# For each API in sample-repos/:
cd sample-repos\contoso-orders-api
git init && git add . && git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/YOUR_USERNAME/contoso-orders-api.git
git push -u origin main
cd ..\..
# Repeat for contoso-payments-api and contoso-catalog-api

更新 agent/config/repos.json:

{
  "repos": [
    "https://github.com/YOUR_USERNAME/contoso-orders-api.git",
    "https://github.com/YOUR_USERNAME/contoso-payments-api.git",
    "https://github.com/YOUR_USERNAME/contoso-catalog-api.git"
  ]
}

3.身份验证

az login
az account set --subscription "YOUR_SUBSCRIPTION_NAME"
gh auth login

4.配置环境

cd agent
copy .env.example .env

编辑 agent/.env:

# Azure AI Search Knowledge Base (FoundryIQ)
AZURE_AI_SEARCH_ENDPOINT=https://YOUR_SEARCH_SERVICE.search.windows.net
AZURE_AI_KB_NAME=your-knowledge-base-name
AZURE_AI_KB_REASONING_EFFORT=low

# Copilot SDK
COPILOT_CLI_PATH=C:\Users\YOUR_USERNAME\AppData\Roaming\npm\copilot.cmd

# MCP Servers
CHANGE_MGMT_URL=http://localhost:4101
SECURITY_URL=http://localhost:4102

查找Copilot CLI路径： 跑 where.exe copilot 或检查 %APPDATA%\npm\copilot.cmd 知识库设置： 创建Azure AI搜索知识库，知识源指向中的策略文档 knowledge/。在Azure门户中配置具有提取输出模式的知识库。

5.创建虚拟环境

# MCP servers
cd mcp\change_mgmt
python -m venv .venv && .venv\Scripts\Activate.ps1 && pip install -r requirements.txt && deactivate
cd ..\security
python -m venv .venv && .venv\Scripts\Activate.ps1 && pip install -r requirements.txt && deactivate
cd ..\..\agent
python -m venv .venv && .venv\Scripts\Activate.ps1 && pip install -r requirements.txt && deactivate
cd ..

6.配置Azure AI搜索知识库

1. 创建Azure存储帐户 --创建blob容器并从以下位置上传策略markdown文件 knowledge/ 喜欢
2. 创建Azure AI搜索 Azure门户中的资源
3. 创建知识源 在FoundryIQ中，将其指向Azure Blob存储容器。FoundryIQ会自动对文档进行索引，并创建 本地索引
4. 创建知识库 --选择上面创建的知识源。配置：

- 型号： 选择Azure OpenAI部署（例如。， gpt-4o) - 输出模式： 提取数据（返回逐字文本，而不是合成答案） - 推理努力： 低（可通过配置 AZURE_AI_KB_REASONING_EFFORT 任何人） - 说明： 添加检索说明，以帮助知识库将查询映射到正确的策略文档

1. 设置环境变量 在 agent/.env:

- AZURE_AI_SEARCH_ENDPOINT --Azure AI搜索服务端点URL - AZURE_AI_KB_NAME --知识库名称

注： 这 scripts/deploy-vector-store.py 该脚本用于传统的Azure OpenAI矢量存储方法，不再需要。

7.安装前端

cd ui\frontend
npm install
cd ..\..

______________________________________________________________________

运行演示

打开 4个独立的终端:

打开： http://localhost:3000

______________________________________________________________________

📁 项目结构

ghcp-cli-sdk-sample1/
├── agent/                      # Fleet compliance agent
│   ├── config/repos.json       # Target repositories
│   ├── fleet_agent/
│   │   ├── agent_loop.py       # Main agentic entry point (SDK-driven)
│   │   ├── github_ops.py       # Git/GitHub operations
│   │   ├── mcp_clients.py      # MCP server clients
│   │   ├── patcher_fastapi.py  # Code patching logic
│   │   └── rag.py              # Knowledge base search (Azure AI Search KB / FoundryIQ)
│   ├── test_sdk_response.py    # SDK response parsing tests
│   ├── requirements.txt
│   └── .env.example
│
├── knowledge/                  # Policy documents (RAG source)
│   ├── CM-7-approval-matrix.md
│   ├── OBS-1.1-structured-logging.md
│   ├── OBS-3.2-trace-propagation.md
│   ├── OPS-2.1-health-readiness.md
│   ├── REL-1.0-pr-gates.md
│   └── SEC-2.4-dependency-vulnerability-response.md
│
├── mcp/                        # MCP servers
│   ├── change_mgmt/server.py   # Approval matrix evaluation
│   └── security/server.py      # Vulnerability scanning
│
├── sample-repos/               # Demo target repos
│   ├── contoso-catalog-api/
│   ├── contoso-orders-api/
│   └── contoso-payments-api/
│
├── scripts/
│   ├── deploy-vector-store.py  # Legacy: Deploy Azure OpenAI vector store (not used)
│   └── push-sample-repos.ps1   # Push samples to GitHub
│
├── images/
│   └── solution-architecture.png  # Architecture diagram
│
├── ui/
│   ├── frontend/               # React app (Vite + Tailwind)
│   └── backend/main.py         # FastAPI WebSocket server
│
├── docs/ARCHITECTURE_FLOW.md
├── DEMO_CHECKLIST.md
└── README.md

策略ID命名约定

______________________________________________________________________

🖥️ 可视化用户界面

UI提供代理活动的实时流式传输 三面板布局:

主要特点

• 单一回购选择器：下拉菜单一次选择一个存储库
• 实时流媒体：事件发生时立即显示
• PR URL显示：创建的PR的可点击链接
• 根据回购清单：逐步跟踪进度

WebSocket事件

⚠️ 单用户应用程序： 此UI仅用于本地单用户执行。它使用本地用户的GitHub和Azure凭据。

______________________________________________________________________

🔧 定制

MCP服务器API

变更管理（端口4101）：

curl -X POST http://localhost:4101/approval \
  -H "Content-Type: application/json" \
  -d '{"service": "contoso-payments-api", "touched_paths": ["app/auth.py"]}'

# Response: {"required_approvals": ["SRE-Prod", "Security"], "risk_level": "high"}

安全扫描（端口4102）：

curl -X POST http://localhost:4102/scan \
  -H "Content-Type: application/json" \
  -d '{"requirements": "requests==2.19.0"}'

# Response: {"findings": [{"name": "requests", "cve": "CVE-2018-18074", "severity": "HIGH"}]}

______________________________________________________________________

📋 示例目标存储库

该演示包括三个故意不兼容的FastAPI服务：

这 支付 服务触发CM-7.2（高影响服务），需要SRE Prod批准。

______________________________________________________________________

⬆️ 升级Copilot SDK

这 github-copilot-sdk 版本是 钉住 在 agent/requirements.txt 以防止无声的破裂。Copilot CLI（Node.js）和Python SDK的版本是独立的——如果CLI自动更新到较新的协议版本，则固定的SDK可能会停止使用 协议版本不匹配 错误：

SDK expects version 3, but server reports version 4

何时升级

• 你看到一个 协议版本不匹配 运行时出错
• Copilot CLI已更新（通过 npm update -g)现在使用较新的协议

如何升级

cd agent
.venv\Scripts\Activate.ps1

# Check current version
pip show github-copilot-sdk

# Upgrade to latest
pip install --upgrade github-copilot-sdk

# Check new version
pip show github-copilot-sdk

升级后， 检查是否破坏API更改 -SDK处于预览中，并且API表面可能在版本之间变化。需验证的关键领域：

一旦验证， 固定新版本 在 agent/requirements.txt:

github-copilot-sdk==X.Y.Z

版本历史

______________________________________________________________________

🏢 从POC到生产

此演示实现了适用于企业环境的模式。这 “自动化提出，人类认可” 这种方法是一种既定的GitOps模式。

当前限制：

• 单用户、单机执行
• 运行之间没有持久状态
• 无身份验证/授权
• 无作业排队或调度

相关行业格局

______________________________________________________________________

�️ 负责任的人工智能考虑因素

此解决方案作为 无头自主代理 --代理和最终用户之间没有会话交换。代理接收来自配置的硬编码提示(repos.json，政策文件 knowledge/)，执行确定性工作流，并生成代码补丁和Pull Requests。人类仅在PR审查阶段重新进入循环。

鉴于这种设计，许多适用于交互式人工智能系统（聊天机器人、内容生成器、面向用户的助手）的传统负责任人工智能问题是 不适用 在这里：

考虑了什么

尽管风险较低，但有以下保障措施：

1. 人性化设计 --代理通过Pull Requests提出更改；它从不自动合并。CM-7审批矩阵根据服务层和修改的文件将PR发送给特定的人工审阅者（SRE、安全、服务所有者）。每次代码更改在进入生产环境之前都需要明确的人工批准。

1. 代码正确性验证 --所有生成的补丁都经过验证 ast.parse() 在编写之前确保语法正确。测试已运行(pytest)在打开PR之前，根据修补后的代码。如果测试失败，代理将尝试基于SDK的代码修复（最多重试3次），测试结果将报告在PR中，以供审阅者注意。

1. 接地输出（RAG） --PR描述引用了从Azure AI搜索知识库（FoundryIQ）检索到的组织自己的政策文档中的证据。知识库使用提取检索，从政策文档中返回逐字文本，而不是合成答案，进一步降低了政策引用中的幻觉风险。

1. 有界代理行为 --Copilot SDK会话仅限于通过以下方式明确注册的13个自定义工具 available_tools 白名单。SDK不能使用内置的文件写入或终端工具。所有文件写入都受到路径遍历保护和仅限工作区的边界检查的进一步约束。

1. 无保留状态或学习 --每次运行都是干净的——工作区是短暂的，状态文件被清除，SDK会话没有先前运行的内存。代理不能在执行过程中累积或泄漏上下文。

1. 单用户执行上下文 --该代理在运营商自己的GitHub和Azure凭据下运行。没有多租户访问，没有共享执行上下文，也没有凭据委派。操作员看到的正是代理看到的。

何时重游

如果解决方案演变为：

• 接受 用户提供的提示 （例如，“扫描此回购中的X”）-将引入即时注入风险
• 过程 外部/不受信任的存储库 --源代码的注释或文件名中可能包含对抗性内容
• 以a的身份奔跑 多租户服务 --需要凭证隔离和访问控制
• 生成 面向用户的内容 超出PR描述——需要内容安全过滤器

______________________________________________________________________

�🐛 故障排除

______________________________________________________________________

🔗 相关资源

• MCP（模型上下文协议）规范
• Azure人工智能搜索知识库（FoundryIQ）
• FastAPI文档

______________________________________________________________________

📄 许可证

此演示用于教育目的。有关详细信息，请参阅许可证。