# remote-filesearch-cli

**Repository Path**: davidfantasy/remote-filesearch-cli

## Basic Information

- **Project Name**: remote-filesearch-cli
- **Description**: 为 AI Coding Agent 设计的远程 Git 仓库文件浏览与搜索服务。自动同步仓库，通过 HTTP API 提供带截断分页的文件内容、ripgrep加速的全文搜索和图片 base64 查看；配套 CLI 客户端专为保护 Agent 上下文窗口而设计。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-12
- **Last Updated**: 2026-07-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# remote-filesearch-cli

> 为 AI Coding Agent 设计的远程 Git 仓库文件浏览与搜索服务。

让 AI coding agent 安全、省 token 地访问远程 Git 仓库，而不必将整个仓库塞进上下文窗口。服务端定时同步指定 Git 仓库，通过 HTTP API 提供文件浏览、内容搜索和图片查看；配套 CLI 客户端专为保护 agent 上下文窗口而设计——所有返回都带截断分页，避免撑爆上下文。

## 使用场景

- **AI agent 读远程仓库**：agent 无需 clone 整个仓库，按需取单个文件、搜代码、看目录结构，且每次返回都自动截断。
- **文档/知识库查询**：把文档仓库挂上去，agent 通过搜索定位知识点，按行分页读取长文档。
- **多模态查看**：仓库里的截图、架构图以 base64 返回，多模态模型可直接消费。
- **代码搜索**：ripgrep 加速的全文搜索，适合 agent 在大型仓库里定位符号、调用点。

## 特性

- **上下文窗口保护**：文件内容按 200 行 / 8000 字符截断并支持 `offset` 分页；搜索结果限 20 条、每条 snippet 限 200 字符；图片超过 5 MiB 直接拒绝，避免返回超大 base64 撑爆上下文。
- **ripgrep 加速**：搜索优先走 ripgrep（`rg --json`），未安装时自动回退 Go regexp，零额外依赖即可运行。
- **自动同步**：定时 poll 同步指定 Git 分支（默认 5 分钟），`git fetch --depth 1` 浅克隆，同步失败时保留旧缓存并标记 `degraded` 状态。
- **只读安全**：纯只读服务，无写入 / 编辑能力，不修改源仓库。
- **文件类型自动识别**：文本 / 图片 / 二进制三分类——文本缓存全文可搜，图片按需 base64，二进制拒绝返回。
- **统一 JSON envelope**：所有接口返回 `{ok, data, warning, error}`，关闭 HTML 转义，便于程序消费。
- **零运行时依赖**：编译为单二进制，仅需目标机器有 git（服务端）和可选的 ripgrep。

## 快速开始

### 构建

```bash
make build
# 产物：dist/remote-filesearch-server、dist/remote-filesearch-cli
```

> 需要 Go 1.25+。可选安装 [ripgrep](https://github.com/BurntSushi/ripgrep) 以获得更快搜索体验。

### 启动服务端

```bash
export GIT_REPO_URL=https://github.com/your-org/your-repo.git
./dist/remote-filesearch-server
# ==> listening on :8080
```

服务端会先 clone 仓库、构建内存缓存，然后启动 HTTP 服务并开始后台定时同步。

### 使用 CLI

```bash
# 查看服务器状态
./dist/remote-filesearch-cli ...   # 见下方命令说明

# 默认连接 http://localhost:8080，可通过环境变量指向其他地址
export FILESEARCH_SERVER_URL=http://your-host:8080
```

## 配置

### 服务端环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `GIT_REPO_URL` | （必填） | 要同步的 git 仓库地址 |
| `GIT_BRANCH` | `main` | 跟踪分支 |
| `SYNC_INTERVAL` | `5m` | poll 同步间隔（支持 `30s`、`10m` 等 duration 或纯数字秒） |
| `LISTEN_ADDR` | `:8080` | HTTP 监听地址 |
| `DATA_DIR` | `./data` | 本地 clone 路径 |

### 客户端配置

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `FILESEARCH_SERVER_URL` | `http://localhost:8080` | 客户端连接的服务器地址 |

也可在编译时通过 `-ldflags "-X main.serverURL=..."` 注入默认地址。

## API 文档

所有接口返回统一 JSON envelope：

```json
// 成功
{ "ok": true, "data": { ... }, "warning": null, "error": null }
// 失败
{ "ok": false, "data": null, "warning": null,
  "error": { "code": "file_not_found", "message": "文件不存在: foo.md", "details": {} } }
```

### `GET /api/health`

服务器状态、最后同步时间、同步错误、缓存文件数。`status` 为 `ok` 或 `degraded`（同步失败但服务可用）。

### `GET /api/files/{path}`

按文件类型自动返回：文本文件返回截断内容 + 分页元信息；图片返回 base64 + MIME 类型；二进制文件返回 `unsupported_file_type`。

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `offset` | `0` | 起始行号（0-based），仅文本 |
| `limit` | `200` | 返回行数上限，仅文本 |

### `GET /api/tree/{path}`

递归列出目录内容，支持 glob 和类型过滤。

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `glob` | （无） | glob 模式，支持 `**` 递归通配（如 `**/*.md`） |
| `type` | （无） | 条目类型过滤：`file` 或 `dir` |

### `GET /api/search`

全文搜索文件内容。优先使用 ripgrep，不可用时回退 Go regexp。

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `q` | （必填） | 搜索词 |
| `path` | （无） | 路径前缀过滤（如 `docs/`） |
| `regex` | `false` | 是否将 `q` 作为正则表达式 |
| `type` | （无） | 文件类型过滤（如 `md`、`yaml`、`go`） |
| `glob` | （无） | 文件名 glob 模式（如 `**/*.md`） |

## CLI 命令

```
remote-filesearch-cli
├── file
│   ├── get <path> [--offset N] [--limit M]    # 读取文件（文本/图片自动识别）
│   └── list <path> [--glob "**/*.md"] [--type file|dir]
└── search <query> [--path prefix] [--regex] [--type md] [--glob "**/*.md"]
```

输出为 JSON envelope，失败时退出码为 1。示例：

```bash
# 读取文件（自动分页）
./dist/remote-filesearch-cli file get docs/readme.md

# 翻页读取
./dist/remote-filesearch-cli file get docs/readme.md --offset 200 --limit 100

# 列出目录，只看 .md 文件
./dist/remote-filesearch-cli file list docs --glob "**/*.md" --type file

# 搜索
./dist/remote-filesearch-cli search "退款流程" --path changes/
./dist/remote-filesearch-cli search "Rule-\d+" --regex --type md
```

## 截断与限制

| 场景 | 限制 | 说明 |
|------|------|------|
| 文件内容 | 200 行或 8000 字符（先到为准） | 文本文件，支持 `offset` 分页 |
| 搜索结果 | 20 条匹配 | 每条 snippet 200 字符 |
| 搜索 snippet | 200 字符 | 匹配行 ±2 行 |
| 图片 | 5 MiB | 超限返回 `image_too_large` 错误 |
| 目录列表 | 无限制 | 可用 `--glob` / `--type` 收窄 |

## 架构

```text
┌─────────────────────────────────────────────────────┐
│               remote-filesearch-server              │
│                                                     │
│  ┌──────────┐   ┌───────────┐   ┌────────────────┐  │
│  │ git sync │──▶│ 内存缓存  │   │  HTTP handlers │  │
│  │ (poll)   │   │ (text+img)│◀─▶│  (chi router)  │  │
│  └──────────┘   └───────────┘   └────────────────┘  │
│                       │                  │           │
│                       ▼                  ▼           │
│                 ripgrep (可选)      os.ReadFile       │
└─────────────────────────────────────────────────────┘
                          ▲
                          │ HTTP (JSON envelope)
                          │
┌─────────────────────────────────────────────────────┐
│               remote-filesearch-cli                  │
│  cobra 命令树 ──▶ HTTP client ──▶ JSON 输出 (stdout)   │
└─────────────────────────────────────────────────────┘
```

## 开发

```bash
make format   # gofmt
make build    # 编译 server + cli 到 dist/
make test     # go test ./...
make dev      # 本地运行 server（需 GIT_REPO_URL）
make clean    # 清理 dist/
```

## 许可

MIT