Skip to main content
Glama
Gemini Coding Harness MCP

Gemini Coding Harness MCP

README.md
# Gemini Coding Harness MCP

面向 **Gemini 桌面端(Mac `Gemini.app` Task 任务模式 / 对话)** 与 **Gemini CLI** 的受控本地编程 Harness MCP 服务。

项目借鉴 **DeepSeek Harness(`dsh`)** 的「`Agent = Model + Harness`」与 **三角色解耦** 思想,把工程纪律与安全护栏下沉为 MCP 服务端硬规则,而不是只靠 Prompt 约束模型。直接暴露裸 `fs / bash` 容易导致盲改覆盖、输出撑爆上下文或误操作宿主机;本项目通过高内聚工具与强约束策略,让通用桌面客户端具备可靠、可校验、可回滚的本地代码工程能力。

---

## 核心设计理念

1. **三角色解耦(Interfaces ↔ Policy ↔ Provider)**
   - MCP 协议层(`src/mcp/`)与底层执行引擎(`src/providers/`)通过 `HarnessProvider` 接口解耦,后续可平滑替换为 Docker 沙箱或外部编码子代理,无需改动任何工具契约。
2. **把“束缚”写进代码护栏**
   - **白名单与只读锁**:仅访问显式启用的注册仓库,支持单仓库切换 `readOnly` 只读锁定;拦截 `..`、绝对路径、符号链接逃逸、`.git/` 内部元数据,以及 `.env`、`*.pem`、`*.key`、SSH 私钥、`credentials.json` 等敏感文件。
   - **写前必读锁(Read-before-Edit)**:记录每个已读文件的 `sha256`;未在当前会话读取或磁盘内容已变更的文件拒绝改/覆写/删,`file_edit` 失配时自动返回最接近代码行与行号辅助自纠。
   - **命令、环境脱敏与 TTL**:剥离宿主机 `*_KEY`/`*_TOKEN`/`*_SECRET` 等环境变量;支持高危黑名单(`standard`)与 **命令前缀白名单(`allowlist`)** 双模式;所有后台命令受 `maxCmdRuntimeSec` 硬超时约束。
   - **上下文输出预算(Context Budgeting)**:代码读取按完整行预算切分并输出 `nextStartLine` 精准续读;超长命令/diff 日志自动落盘至 `runtime/logs/`(7 天/100 份自动清理),支持 `log_read(logId)` 分页回看。
   - **磁盘持久化 Checkpoint**:首次修改或删除任意文件前自动持久化原始快照到 `runtime/checkpoints/`,跨会话保留,随时通过 MCP 或控制台一键回滚。
3. **控制面与执行面分离**
   - 内置零依赖 **本地可视化配置控制台**(`--ui`,仅监听 `127.0.0.1:18788`),强制校验 `Host`、`Origin` 与随机 `X-Harness-CSRF`;LLM 永远无法通过 MCP 给自己扩容白名单或放宽安全限制。

---

## 架构总览

```text
┌──────────────────────────────────────────────────────────┐
│  Gemini Desktop (Mac 本地 MCP stdio / Task 模式) 或 CLI   │
└────────────────────────────┬─────────────────────────────┘
                             │ JSON-RPC (stdio / Streamable HTTP)
                             ▼
┌──────────────────────────────────────────────────────────┐
│  [1] MCP Adapter 层 (src/mcp/create-server.ts)           │
│      14 个高内聚工具 + 工程纪律 Instructions + 审计记录   │
└────────────────────────────┬─────────────────────────────┘
                             │
                             ▼
┌──────────────────────────────────────────────────────────┐
│  [2] Harness Policy & State 层                           │
│   ├── Path & Env Guard:白名单/只读、禁敏感文件与环境变量 │
│   ├── Command Guard:黑名单 / allowlist 白名单模式 + TTL  │
│   ├── Output Budget:按行读取分页 + log_read + 自动清理   │
│   └── Session Store:sha256 锁 + 持久化 Checkpoint + 进程组│
└────────────────────────────┬─────────────────────────────┘
                             │
                             ▼
┌──────────────────────────────────────────────────────────┐
│  [3] Service Provider 层 (src/providers/)                │
│      fs-ops / cmd-ops / git-ops(iOS/Swift/Node/Go/Rust) │
└──────────────────────────────────────────────────────────┘

        ▲ 仅本机浏览器操作(完全隔离于 LLM)
┌───────┴──────────────────────────────────────────────────┐
│  本地可视化配置控制台 (127.0.0.1:18788, --ui)             │
│  Finder 选目录 · 父目录扫描 · 只读锁 · 一键回滚 · 审计    │
└──────────────────────────────────────────────────────────┘
```

---

## 14 个高内聚工具一览

针对桌面客户端工具往返特征优化,将高频探查、受控变更与校验流程合并为 14 个高语义工具:

| 类别 | 工具名 | 核心能力与内置护栏 |
|---|---|---|
| **工作区** | `workspace_list` | 列出当前已启用的白名单仓库、只读状态与已同步的客户端 MCP Roots |
| | `workspace_explore` | 单次返回目录聚簇摘要、文件骨架(支持 `subdir`)、Git 状态、规则文档与 `scripts` |
| **只读** | `code_search` | 基于 `ripgrep` 的代码检索(自动排除 `.git`、`node_modules` 及敏感文件) |
| | `file_read_batch` | 单次批量读取 1–8 个文件(按完整行预算切分,带 `nextStartLine` 与 `sha256` 读锁) |
| | `git_diff_summary` | 查看 `git status`、`diff --stat` 与预算裁剪后的统一 diff |
| | `log_read` | 按 `logId` 分页读取被预算裁剪落盘到 `runtime/logs/` 的完整命令/diff 输出 |
| **编辑** | `file_edit` | 多 hunk 精确唯一替换(需先读;失配时返回最近似行号片段),自动快照并返回 diff |
| | `file_create` | 新建文件(自动建父目录与快照;覆盖已存在文件需显式 `overwrite=true` 且已读) |
| | `file_delete` | 受写前必读锁与持久化 Checkpoint 保护的文件删除(可一键回滚恢复) |
| **执行** | `cmd_run` | 策略校验与环境脱敏后执行命令;12 秒内同步返回,超时自动转后台并受 TTL 约束 |
| | `cmd_poll` | 查询后台命令状态,支持 `waitSeconds`(0–10 秒)长轮询 |
| | `cmd_stop` | 按进程组(`-pid`)安全终止运行中的后台命令 |
| | `verify_run` | 运行校验命令;默认 25 秒内同步完成,大项目超时自动转后台 `jobId` 供轮询 |
| **回滚** | `checkpoint_manage` | `create` / `list` / `revert` 跨会话持久化文件快照 |

---

## 环境要求

- **操作系统**:macOS(核心 MCP 服务亦可在 Linux 运行;`Finder` 选目录弹窗依赖 macOS `osascript`)
- **Node.js**:20+(推荐 22 LTS)
- **依赖工具**:`git`、`ripgrep`(`rg`,建议通过 `brew install ripgrep` 安装;缺失时目录探索自动回退原生遍历)

---

## 快速开始(推荐:Mac `Gemini.app` 本地 `stdio` 模式)

### 1. 克隆并构建

```bash
git clone https://github.com/tihonovaaybeniz-code/gemini-coding-harness.git
cd gemini-coding-harness
npm install
npm run typecheck
npm run build
```

### 2. 打开可视化配置控制台添加仓库

```bash
npm run ui
# 或在 Finder 中直接双击项目根目录下的 Open-Config-UI.command
```

浏览器打开 `http://127.0.0.1:18788` 后,可零手写配置完成管理:
- **工作区白名单**:点击 **「+ Finder 选择文件夹」** 选择仓库,自动识别 Git 分支、技术栈与推荐 `verifyCommands`;支持随时点击开关启用/停用(改完热重载立即生效,无需重启 `Gemini.app`)。
- **父目录自动发现**:在 **「父目录自动发现」** 添加常用开发目录(如 `~/Projects`),自动扫描候选仓库(自动跳过 Harness 自身目录),默认不放行,手动勾选开关才正式写入白名单。
- **MCP Roots 与安全策略**:实时查看客户端是否在 `--stdio` 握手中支持 `roots/list`(自动过滤 `/`、`$HOME` 与 Harness 自身目录),并调整输出字节上限、同步超时与读取行数预算。
- **调用审计 & 接入命令**:查看 `runtime/audit.jsonl` 最近工具调用元数据,并一键复制客户端启动命令与技能文案。

> 手动配置方式:参考 [harness.config.example.json](harness.config.example.json) 复制为 `harness.config.json`(已被 `.gitignore` 忽略;首次运行也会自动生成空配置)。

### 3. 接入 Mac `Gemini.app`(本地 MCP)

1. 打开 Mac `Gemini.app` → **自定义 → 关联应用 → 添加自定义关联应用**,选择 **本地 MCP**。
2. **服务器名称**:`Gemini Coding Harness`
3. **命令**:填入控制台「调用审计 & 接入命令」里生成好的完整绝对路径命令(桌面应用通常不继承 `nvm` 的 `PATH`,务必使用 `node` 绝对路径):
   ```text
   /path/to/node /path/to/gemini-coding-harness/dist/index.js --stdio
   ```
4. **沙盒设置**:
   - 推荐选 **完整访问权限**(安全边界由 Harness 服务端白名单、路径/命令护栏与 Checkpoint 保障,后续在控制台增减仓库无需反复改系统沙盒);
   - 或选 **自定义沙盒** 并显式放行 `gemini-coding-harness`、目标仓库目录及 Node / Homebrew 路径。
5. **(推荐)配置「技能」**:将 [GEMINI_SKILL.md](GEMINI_SKILL.md) 内容粘入 Mac `Gemini.app` 顶部的 **「技能」** 面板,让模型在 Task 模式下稳定遵循先探查、写前必读、改完必验的工程流程。

---

## 对话提示词示例

在 Mac `Gemini.app`(普通对话或 Task 模式)中可直接发送:

**连通性与工作区检查**
```text
请调用本地 MCP `Gemini Coding Harness` 的 `workspace_list`,列出当前可用工作区和 source 来源,不要修改任何文件。
```

**受控开发任务模板**
```text
请使用本地 MCP `Gemini Coding Harness` 在工作区 `<仓库别名>` 中完成以下任务:
1. 先调用 `workspace_explore`、`code_search` 和 `file_read_batch` 阅读相关代码;
2. 动手前调用 `checkpoint_manage(action="create")` 建立回滚点,再使用 `file_edit` 小步修改;
3. 改完后必须运行 `verify_run` 和 `git_diff_summary`;
4. 仅依据真实工具结果汇报改动清单、核心 diff 与检查退出码。
```

---

## 其他接入方式

### Gemini CLI(本地 `stdio`)

在 `~/.gemini/settings.json` 中添加:

```json
{
  "mcpServers": {
    "gemini-coding-harness": {
      "command": "/path/to/node",
      "args": ["/path/to/gemini-coding-harness/dist/index.js", "--stdio"]
    }
  }
}
```

### Streamable HTTP 模式(可选,用于云端/Web 调试)

```bash
npm start
# 默认监听 http://127.0.0.1:18787/p/<64-hex-token>/mcp
# token 自动生成于 runtime/token.txt
```

如需配合需要公网 HTTPS 回调的客户端,可另起本地隧道(仅建议临时调试,或配合固定域名与强鉴权):

```bash
cloudflared tunnel --url http://127.0.0.1:18787 --no-autoupdate
```

---

## 项目结构

```text
gemini-coding-harness/
├── .github/workflows/ci.yml      # GitHub Actions 自动 typecheck、build 与集成测试
├── src/
│   ├── index.ts                  # CLI 入口(--stdio / --http / --ui)与 MCP Roots 探测
│   ├── config.ts                 # 热重载配置、原子保存、动态 Roots 注册表
│   ├── errors.ts                 # 结构化可执行纠错异常(HarnessError)
│   ├── workspace-scanner.ts      # 多技术栈探测、verifyCommands 推荐、父目录扫描
│   ├── mcp/create-server.ts      # 14 个高内聚 MCP 工具注册与调用审计
│   ├── policy/
│   │   ├── path-guard.ts         # 路径越界、符号链接逃逸与敏感凭证拦截
│   │   ├── command-guard.ts      # 黑名单 / allowlist 前缀白名单命令护栏
│   │   ├── env-guard.ts          # 子进程敏感环境变量脱敏
│   │   ├── output-budget.ts      # 输出预算裁剪与报错行提取
│   │   └── runtime-cleanup.ts    # 日志自动清理与 JSONL 大小轮转
│   ├── state/session-store.ts    # Read-before-Edit sha256 锁、持久化 Checkpoint、TTL 进程组
│   ├── providers/
│   │   ├── types.ts              # HarnessProvider 抽象接口
│   │   ├── exec-utils.ts         # 原子写、只读锁检查与脱敏命令执行封装
│   │   ├── fs-ops.ts             # 目录探索、批量按行读取、模糊定位编辑与删文件/读日志
│   │   ├── cmd-ops.ts            # 同步/异步命令执行与异步化 verify_run
│   │   ├── git-ops.ts            # Git Diff 摘要与 Checkpoint 管理
│   │   └── local-provider.ts     # 本地 Provider 门面
│   └── ui/
│       ├── server.ts             # 本地控制面 HTTP API(Host/Origin/CSRF 保护)
│       └── page.ts               # 单页可视化控制台前端
├── scripts/
│   ├── e2e-verify.mjs            # Streamable HTTP 全链路与护栏验证
│   └── verify-ui-and-roots.mjs   # stdio MCP Roots、护栏全覆盖与 Web UI API 验证
├── harness.config.example.json   # 配置文件示例
├── GEMINI_SKILL.md               # Gemini 客户端配套技能文案
├── Open-Config-UI.command        # macOS Finder 双击启动控制台脚本
└── LICENSE                       # MIT License
```

---

## 本地开发与验证

```bash
npm run typecheck
npm run build
npm test
```

---

## 安全说明

- `harness.config.json`(含本地仓库绝对路径)与 `runtime/`(含 `token.txt`、`audit.jsonl`、`requests.jsonl`、`client-probe.json`、`logs/`)默认被 `.gitignore` 忽略,**所有运行态数据与日志均不写入目标业务仓库**。
- 可视化控制台仅绑定 `127.0.0.1`,所有变更接口均强制校验 `Host`、`Origin` 与每进程随机 `X-Harness-CSRF`。

## 开源协议

本项目基于 [MIT License](LICENSE) 开源。