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) 开源。