[RFC] 支持通过 repos 地址自动 clone/pull 作为 session work_dir

orion commented

2026-06-24 22:09:56 +08:00

Owner

动机

目前 bixiu-mcp 的 work_dir 优先级链为：

X-Work-Dir Header > clientInfo.cwd > 环境变量 > 当前目录

客户端需要提前知道代码在服务器上的绝对路径，或者依赖环境变量全局设置。在多项目场景下不够灵活。

提议

允许客户端在 initialize 阶段通过 header / clientInfo 传入 repos 地址，bixiu-mcp 自动 clone/pull 到本地缓存目录，并将该目录设为 session 的 work_dir。

工作流

客户端传 repos 地址（如 git.bx.wedata.club/bixiu/bixiweave）
                │
                ▼
bixiu-mcp 自动 clone/pull 到缓存目录（如 ~/.bixiu-mcp/repos/bixiu/bixiweave/）
                │
                ▼
session.work_dir = 该目录
                │
                ▼
所有文件操作、git 操作、终端命令都在 repos 内执行

需要讨论的问题

1. 传参方式

新增 Header X-Repos-Url（类似 X-Work-Dir）
或在 clientInfo 中新增 repos 字段
优先级应与 X-Work-Dir 互斥？还是 repos 优先？

2. 鉴权

私有仓库需要 token
可复用现有的 Authorization Header 或 API Token
或支持 X-Repos-Token 独立传

3. 目录生命周期

缓存策略：clone 后复用，每次连接自动 git pull
清理策略：LRU 淘汰？固定磁盘配额？
是否需要手动刷新机制（?refresh=true）？

4. 分支/标签选择

是否需要支持 X-Repos-Ref header 来指定分支/tag/commit？
不传时默认用仓库的 default_branch

5. 首次 clone 性能

大仓库首次 clone 可能耗时较长
是否可以异步：先返回 session，后台 clone 完成后通知客户端？
或简单地在 initialize 阶段同步等待 + 超时报错？

6. 与现有 work_dir 的关系

repos_url 存在 ──► 优先用 repos（clone/pull 到缓存目录）
repos_url 不存在 ──► 走现有 work_dir 优先级链

关联

bixiweave 已有 servers/forgejo_server.py 封装 Forgejo API
bixiu-mcp 刚支持了 X-Work-Dir header（25a2d84）
可与 bixiweave 的自举流程配合：Issue 触发后自动 clone 对应 repos 进行分析

## 动机目前 bixiu-mcp 的 work_dir 优先级链为： ``` X-Work-Dir Header > clientInfo.cwd > 环境变量 > 当前目录 ``` 客户端需要提前知道代码在服务器上的绝对路径，或者依赖环境变量全局设置。在多项目场景下不够灵活。 ## 提议允许客户端在 `initialize` 阶段通过 header / clientInfo 传入 **repos 地址**，bixiu-mcp 自动 clone/pull 到本地缓存目录，并将该目录设为 session 的 work_dir。 ## 工作流 ``` 客户端传 repos 地址（如 git.bx.wedata.club/bixiu/bixiweave） │ ▼ bixiu-mcp 自动 clone/pull 到缓存目录（如 ~/.bixiu-mcp/repos/bixiu/bixiweave/） │ ▼ session.work_dir = 该目录 │ ▼ 所有文件操作、git 操作、终端命令都在 repos 内执行 ``` ## 需要讨论的问题 ### 1. 传参方式 - 新增 Header `X-Repos-Url`（类似 `X-Work-Dir`） - 或在 `clientInfo` 中新增 `repos` 字段 - 优先级应与 `X-Work-Dir` 互斥？还是 repos 优先？ ### 2. 鉴权 - 私有仓库需要 token - 可复用现有的 `Authorization` Header 或 API Token - 或支持 `X-Repos-Token` 独立传 ### 3. 目录生命周期 - 缓存策略：clone 后复用，每次连接自动 `git pull` - 清理策略：LRU 淘汰？固定磁盘配额？ - 是否需要手动刷新机制（`?refresh=true`）？ ### 4. 分支/标签选择 - 是否需要支持 `X-Repos-Ref` header 来指定分支/tag/commit？ - 不传时默认用仓库的 default_branch ### 5. 首次 clone 性能 - 大仓库首次 clone 可能耗时较长 - 是否可以异步：先返回 session，后台 clone 完成后通知客户端？ - 或简单地在 initialize 阶段同步等待 + 超时报错？ ### 6. 与现有 work_dir 的关系 ``` repos_url 存在 ──► 优先用 repos（clone/pull 到缓存目录） repos_url 不存在 ──► 走现有 work_dir 优先级链 ``` ## 关联 - bixiweave 已有 `servers/forgejo_server.py` 封装 Forgejo API - bixiu-mcp 刚支持了 `X-Work-Dir` header（25a2d84） - 可与 bixiweave 的自举流程配合：Issue 触发后自动 clone 对应 repos 进行分析

orion commented

2026-06-24 22:17:15 +08:00

Author

Owner

方案收敛

经过讨论，简化后的方案如下：

bixiu-mcp 的职责边界

只做：
  repos 地址 → git clone（缓存不存在时）→ 设置 work_dir

不做：
  ✗ git pull / git checkout → 交给 MCP git 工具
  ✗ 分支管理 → 交给 MCP git 工具
  ✗ 缓存淘汰 → 暂不处理

传参方式

clientInfo 新增字段：

{
  "clientInfo": {
    "repos": "git.bx.wedata.club/bixiu/bixiweave",
    "repos_mode": "clone"    // "clone"（默认）| "worktree"
  }
}

也支持 X-Repos-Url Header 覆盖。

clone 模式

clone（默认）— 完整独立 clone 到 ~/.bixiu-mcp/repos/<owner>/<repo>/
worktree — 创建 bare repo + worktree，适合同 repo 多分支场景

鉴权

复用 API Token。如 clone 私有仓库失败，返回友好提示。

与现有 work_dir 的关系

互斥，repos 优先：

repos 存在 ──► 忽略 X-Work-Dir
repos 不存在 ──► 走现有 work_dir 优先级链

后续

目录清理、缓存淘汰等功能作为独立 Issue 跟进
实现时在 initialize 阶段同步 clone，60s 超时

## 方案收敛经过讨论，简化后的方案如下： ### bixiu-mcp 的职责边界 ``` 只做： repos 地址 → git clone（缓存不存在时）→ 设置 work_dir 不做： ✗ git pull / git checkout → 交给 MCP git 工具 ✗ 分支管理 → 交给 MCP git 工具 ✗ 缓存淘汰 → 暂不处理 ``` ### 传参方式 `clientInfo` 新增字段： ```json { "clientInfo": { "repos": "git.bx.wedata.club/bixiu/bixiweave", "repos_mode": "clone" // "clone"（默认）| "worktree" } } ``` 也支持 `X-Repos-Url` Header 覆盖。 ### clone 模式 - `clone`（默认）— 完整独立 clone 到 `~/.bixiu-mcp/repos/<owner>/<repo>/` - `worktree` — 创建 bare repo + worktree，适合同 repo 多分支场景 ### 鉴权复用 API Token。如 clone 私有仓库失败，返回友好提示。 ### 与现有 work_dir 的关系互斥，repos 优先： ``` repos 存在 ──► 忽略 X-Work-Dir repos 不存在 ──► 走现有 work_dir 优先级链 ``` ### 后续 - 目录清理、缓存淘汰等功能作为独立 Issue 跟进 - 实现时在 `initialize` 阶段同步 clone，60s 超时

orion commented

2026-06-24 22:33:26 +08:00

Author

Owner

已实现并推送

基础功能已在 ipc_terminal_server.py 中实现（commit 141098c）：

新增功能

clientInfo.repos / X-Repos-Url Header → 自动 clone 到 ~/.bixiu-mcp/repos/<owner>/<repo>/
支持三种 URL 格式：裸路径、https://、git@
缓存命中直接复用，不做 git pull
私有仓库复用 API Token 鉴权
60s clone 超时，友好错误提示

使用方式

{
  "clientInfo": {
    "repos": "git.bx.wedata.club/bixiu/bixiweave"
  }
}

或 Header: X-Repos-Url: git.bx.wedata.club/bixiu/bixiweave

后续

目录清理/缓存淘汰作为独立 Issue 跟进

## 已实现并推送基础功能已在 `ipc_terminal_server.py` 中实现（commit `141098c`）： ### 新增功能 - `clientInfo.repos` / `X-Repos-Url` Header → 自动 clone 到 `~/.bixiu-mcp/repos/<owner>/<repo>/` - 支持三种 URL 格式：裸路径、`https://`、`git@` - 缓存命中直接复用，不做 `git pull` - 私有仓库复用 API Token 鉴权 - 60s clone 超时，友好错误提示 ### 使用方式 ```json { "clientInfo": { "repos": "git.bx.wedata.club/bixiu/bixiweave" } } ``` 或 Header: `X-Repos-Url: git.bx.wedata.club/bixiu/bixiweave` ### 后续 - 目录清理/缓存淘汰作为独立 Issue 跟进

Rows
Columns

[RFC] 支持通过 repos 地址自动 clone/pull 作为 session work_dir #5

动机

提议

工作流

需要讨论的问题

1. 传参方式

2. 鉴权

3. 目录生命周期

4. 分支/标签选择

5. 首次 clone 性能

6. 与现有 work_dir 的关系

关联

方案收敛

bixiu-mcp 的职责边界

传参方式

clone 模式

鉴权

与现有 work_dir 的关系

后续

已实现并推送

新增功能

使用方式

后续