# PRPilot MCP Agent

PRPilot 是一个面向开源新手的 PR 状态分析助手。用户给出 GitHub PR 链接和可选的本地仓库路径后，Agent 会通过 MCP 工具查询 PR 基本状态、CI / Checks、评论与 Review、本地 Git 状态，并生成中文下一步建议。

## 安装步骤

建议使用 Python 3.11+：

```bash
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
```

如果 MCP SDK API 后续变化，优先检查：

```bash
python -c "from mcp.server.fastmcp import FastMCP; from mcp import ClientSession, StdioServerParameters; from mcp.client.stdio import stdio_client; print('ok')"
```

## .env 配置

复制 `.env.example` 为 `.env`：

```text
OPENAI_API_KEY=你的 OpenAI-compatible API Key
OPENAI_BASE_URL=可选，兼容服务地址；为空时使用 OpenAI SDK 默认地址
OPENAI_MODEL=gpt-4o-mini
GITHUB_TOKEN=可选，建议填写以提高 GitHub API 限额
```

说明：

- `OPENAI_API_KEY` 或 `OPENAI_BASE_URL` 至少应配置一种可用 LLM 连接方式。
- `GITHUB_TOKEN` 不配置时，公开仓库通常仍可匿名访问，但更容易限流，部分 Checks 也可能权限不足。

DeepSeek 配置示例：

```text
OPENAI_API_KEY=你的 DeepSeek API Key
OPENAI_BASE_URL=https://api.deepseek.com
OPENAI_MODEL=deepseek-v4-flash
GITHUB_TOKEN=可选
```

GUI 的 `API 配置` 弹窗里也有 `DeepSeek 预设` 按钮，会自动填入 Base URL 和模型名。

## 如何运行

图形界面：

```bat
start_gui.bat
```

打开窗口后，先点击左侧 `API 配置`。如果使用 DeepSeek，点击 `DeepSeek 预设`，填写 API Key 后保存；其他 OpenAI-compatible 服务则手动填写 `OPENAI_API_KEY`、`OPENAI_BASE_URL` 和 `OPENAI_MODEL`。

GUI 的最终回复区使用 `markdown-it-py` + `tkinterweb` 渲染 Markdown，会按 HTML/CSS 显示标题、表格、列表、代码块和引用。

一键启动：

```bat
start.bat
```

一键运行 demo：

```bat
start.bat --demo
```

交互模式：

```bash
python agent_client.py
```

直接传入问题：

```bash
python agent_client.py "分析 https://github.com/OWNER/REPO/pull/123，本地仓库路径是 D:\path\repo"
```

demo 模式：

```bash
python agent_client.py --demo
```

demo 会读取 `data/sample_input.txt`，但仍然真实调用 MCP 工具，不会伪造结果。

## 安全限制

- GitHub API 只做只读 GET 请求。
- 本地仓库只执行固定白名单 git 命令。
- `subprocess.run` 使用 list 参数，`shell=False`。
- 不会自动 `push`、`merge`、`comment`、`checkout`、`rebase`、`reset` 或 `clean`。

如果本地仓库检查返回 `dubious ownership`，说明 Git 发现当前运行用户和仓库所有者不一致。确认该目录是你的仓库后，可以在普通终端运行工具提示的命令，例如：

```bash
git config --global --add safe.directory D:/Coding/MAAdev/MaaAssistantArknights
```

`inspect_local_repo` 允许的命令只有：

```text
git status --short
git status -sb
git branch --show-current
git remote -v
git rev-parse HEAD
git diff --stat
git log --oneline -5
```