ru

RU - Repo Updater

用于同步数十或数百个 GitHub 仓库的综合 Bash CLI。除了基本同步功能，RU 还包含完整的 AI 辅助代码审查系统和 Agent 批量处理功能，可自动处理整个项目目录中未提交的更改。

为什么需要它

当你使用 47 个以上的仓库（个人项目、分支、依赖项）时，手动保持它们同步十分繁琐。但同步只是开始——RU 还可以协调 AI 编码 Agent，大规模审查问题、处理 PR，并提交未提交的工作。

它解决的问题：

• 需要为每个仓库手动执行 cd ~/project && git pull
• 错过更新，导致合并冲突不断累积
• 仓库存在未提交的更改，却一直得不到提交
• 问题和 PR 在各个仓库中不断堆积
• AI Agent 跨仓库工作时缺乏协调

关键概念

Git Plumbing，而非 Porcelain

RU 只使用 git plumbing 命令，绝不解析人类可读的输出：

# WRONG: Locale-dependent, version-fragile
git pull 2>&1 | grep "Already up to date"

# RIGHT: Machine-readable plumbing
git rev-list --left-right --count HEAD...@{u}
git status --porcelain
git rev-parse HEAD

流分离

人类可读的输出写入 stderr；数据写入 stdout：

ru sync --json 2>/dev/null | jq '.summary'
# Progress shows in terminal, JSON pipes to jq

不使用全局 cd

所有 git 操作都使用 git -C，不会更改工作目录。

常用命令

同步（主要用途）

# Sync all configured repos
ru sync

# Parallel sync (much faster)
ru sync -j8

# Dry run - see what would happen
ru sync --dry-run

# Resume interrupted sync
ru sync --resume

# JSON output for scripting
ru sync --json 2>/dev/null | jq '.summary'

状态（只读检查）

# Check all repos without modifying
ru status

# JSON output
ru status --json

仓库管理

# Initialize configuration
ru init

# Add repos to sync list
ru add owner/repo
ru add https://github.com/owner/repo
ru add owner/repo@branch as custom-name

# Remove from list
ru remove owner/repo

# List configured repos
ru list

# Detect orphaned repos (in projects dir but not in list)
ru prune           # Preview
ru prune --delete  # Actually remove
ru prune --archive # Move to archive directory

诊断

ru doctor      # System health check
ru self-update # Update ru itself

AI 辅助审查系统

RU 包含强大的审查协调系统，可管理各个仓库中的 AI 辅助代码审查。

两阶段审查工作流

阶段 1：发现（--plan）

• 在所有仓库中查询 GitHub 上未关闭的问题和 PR
• 使用标签分析和时间信息为条目评分，确定优先级
• 创建隔离的 git worktree，以安全地进行审查
• 在终端复用器中启动 Claude Code 会话

阶段 2：应用（--apply）

• 审查发现阶段提出的更改
• 运行质量门禁（ShellCheck、测试、lint）
• 可选择推送已批准的更改（--push）

# Discover and plan reviews
ru review --plan

# After reviewing AI suggestions
ru review --apply --push

优先级评分算法

因素	分值	逻辑
类型	0-20	PR：+20，问题：+10，草稿 PR：-15
标签	0-50	security/critical：+50，bug/urgent：+30
时长（错误）	0-50	>60 天：+50，>30 天：+30
近期活动	0-15	更新于 3 天内：+15，7 天内：+10
陈旧程度	-20	最近审查过：-20

优先级：CRITICAL（≥150）、HIGH（≥100）、NORMAL（≥50）、LOW（<50）

会话驱动程序

驱动程序	描述	最适用于
auto	自动检测最合适的可用选项	默认
ntm	集成 Named Tmux Manager	多 Agent 工作流
local	直接使用 tmux 会话	简单配置

ru review --mode=ntm --plan
ru review -j 4 --plan  # Parallel sessions

成本预算

ru review --max-repos=10 --plan
ru review --max-runtime=30 --plan  # Minutes
ru review --skip-days=14 --plan    # Skip recently reviewed
ru review --analytics              # View past review stats

Agent 批量处理（自动处理存在未提交更改的仓库）

ru agent-sweep 命令会协调 AI 编码 Agent，自动处理存在未提交更改的仓库。

基本用法

# Process all repos with uncommitted changes
ru agent-sweep

# Dry run - preview what would be processed
ru agent-sweep --dry-run

# Process 4 repos in parallel
ru agent-sweep -j4

# Filter to specific repos
ru agent-sweep --repos="myproject*"

# Include release step after commit
ru agent-sweep --with-release

# Resume interrupted sweep
ru agent-sweep --resume

# Start fresh
ru agent-sweep --restart

Agent 三阶段工作流

阶段 1：规划（--phase1-timeout，默认 300s）

• Claude Code 分析未提交的更改
• 确定应暂存哪些文件（遵循拒绝列表）
• 生成结构化提交消息

阶段 2：提交（--phase2-timeout，默认 600s）

• 验证计划（文件是否存在、是否符合拒绝列表要求）
• 暂存已批准的文件并创建提交
• 运行质量门禁
• 可选择推送到远程仓库

阶段 3：发布（--phase3-timeout，默认 300s，需指定 --with-release）

• 分析自上一个标签以来的提交历史
• 确定版本升级类型（patch/minor/major）
• 创建 git 标签，并可选择创建 GitHub 发布

执行模式

--execution-mode=agent  # Full AI-driven workflow (default)
--execution-mode=plan   # Phase 1 only: generate plan, stop
--execution-mode=apply  # Phase 2+3: execute existing plan

预检

启动 Agent 前会验证每个仓库：

检查项	跳过原因
是否为 git 仓库	not_a_git_repo
是否已配置 Git 邮箱	git_email_not_configured
是否不是浅克隆	shallow_clone
是否没有正在进行的变基	rebase_in_progress
是否没有正在进行的合并	merge_in_progress
是否不是分离 HEAD	detached_HEAD
是否有上游分支	no_upstream_branch
是否未发生分歧	diverged_from_upstream

安全防护

文件拒绝列表 - 无论 Agent 输出什么，都不会提交：

类别	模式
密钥	.env、*.pem、*.key、id_rsa*、credentials.json
构建产物	node_modules、__pycache__、dist、build、target
日志/临时文件	*.log、*.tmp、*.swp、.DS_Store
IDE 文件	.idea、.vscode、*.iml

密钥扫描：

--secret-scan=none   # Disable
--secret-scan=warn   # Warn but continue (default)
--secret-scan=block  # Block push on detection

退出代码

代码	含义
0	所有仓库均已成功处理
1	部分仓库失败（Agent 出错、超时）
2	质量门禁失败（密钥、测试）
3	系统错误（缺少 ntm、tmux）
4	参数无效
5	已中断（使用 --resume）

配置

符合 XDG 规范的目录结构

~/.config/ru/
├── config               # Main config file
└── repos.d/
    ├── public.list      # Public repos (one per line)
    └── private.list     # Private repos (gitignored)

~/.local/state/ru/
├── logs/
│   └── YYYY-MM-DD/
├── agent-sweep/
│   ├── state.json
│   └── results.ndjson
└── review/
    ├── digests/
    └── results/

仓库列表格式

# ~/.config/ru/repos.d/public.list
owner/repo
another-owner/another-repo@develop
private-org/repo@main as local-name
https://github.com/owner/repo.git

布局模式

布局	示例路径
flat	/data/projects/repo
owner-repo	/data/projects/owner_repo
full	/data/projects/github.com/owner/repo

ru config --set LAYOUT=owner-repo

单仓库配置

# ~/.../your-repo/.ru-agent.yml
agent_sweep:
  enabled: true
  max_file_size: 5242880  # 5MB
  extra_context: "This is a Python project using FastAPI"
  pre_hook: "make lint"
  post_hook: "make test"
  denylist_extra:
    - "*.backup"
    - "internal/*"

ntm 集成

当 ntm（Named Tmux Manager）可用时，RU 会使用其机器人模式 API：

函数	用途
ntm --robot-spawn	在新的 tmux 窗格中创建 Claude Code 会话
ntm --robot-send	发送提示词，并对长消息进行分块
ntm --robot-wait	阻塞等待会话完成，直至超时
ntm --robot-activity	查询会话实时状态
ntm --robot-status	获取所有托管会话的状态
ntm --robot-interrupt	发送 Ctrl+C 以中断长时间运行的操作

输出模式

JSON 模式（--json）

ru sync --json 2>/dev/null

{
  "version": "1.2.0",
  "timestamp": "2025-01-03T14:30:00Z",
  "summary": {
    "total": 47,
    "cloned": 8,
    "updated": 34,
    "current": 3,
    "conflicts": 2
  },
  "repos": [...]
}

NDJSON 结果日志

{"repo":"mcp_agent_mail","action":"pull","status":"updated","duration":2}
{"repo":"beads_viewer","action":"clone","status":"cloned","duration":5}

jq 示例

# Get paths of all cloned repos
ru sync --json 2>/dev/null | jq -r '.repos[] | select(.action=="clone") | .path'

# Count by status
cat ~/.local/state/ru/logs/latest/results.ndjson | jq -s 'group_by(.status) | map({status: .[0].status, count: length})'

更新策略

ru sync                        # Default: ff-only (safest)
ru sync --rebase               # Rebase local commits
ru sync --autostash            # Auto-stash before pull
ru sync --force                # Force update (use with caution)

策略	行为
ff-only	仅快进；发生分歧时失败
rebase	将本地提交变基到远程提交之上
merge	必要时创建合并提交

质量门禁

应用更改前，RU 会运行自动化质量门禁：

按项目类型自动检测：

项目类型	测试命令	Lint 命令
npm/yarn	npm test	npm run lint
Cargo（Rust）	cargo test	cargo clippy
Go	go test ./...	golangci-lint run
Python	pytest	ruff check
Makefile	make test	make lint
Shell 脚本	（无）	shellcheck *.sh

速率限制

RU 包含一个自适应并行度控制器：

条件	操作
GitHub 剩余配额 < 100	将并行度降至 1
GitHub 剩余配额 < 500	将并行度降低 50%
检测到模型返回 429	暂停启动新会话 60 秒
错误率 > 50%	打开熔断器

退出代码（同步）

代码	含义
0	成功 - 所有仓库均已同步或已是最新
1	部分失败 - 部分仓库失败
2	存在冲突
3	依赖错误（缺少 gh、认证失败）
4	参数无效
5	已中断（使用 --resume）

环境变量

变量	描述	默认值
RU_PROJECTS_DIR	仓库根目录	/data/projects
RU_LAYOUT	路径布局	flat
RU_PARALLEL	并行工作线程数	1
RU_TIMEOUT	网络超时（秒）	30
RU_UPDATE_STRATEGY	拉取策略	ff-only
GH_TOKEN	GitHub 令牌	（来自 gh CLI）

故障排除

常见问题

问题	解决方法
gh: command not found	brew install gh && gh auth login
gh: auth required	gh auth login 或设置 GH_TOKEN
Cannot fast-forward	使用 --rebase 或先推送
dirty working tree	提交更改或使用 --autostash
diverged_from_upstream	git fetch && git rebase origin/main

调试模式

# View latest run log
cat ~/.local/state/ru/logs/latest/run.log

# View specific repo log
cat ~/.local/state/ru/logs/latest/repos/mcp_agent_mail.log

# Run with verbose output
ru agent-sweep --verbose --debug

预检失败调试

# View why repos were skipped
ru agent-sweep --json 2>/dev/null | jq '.repos[] | select(.status == "skipped")'

安装

# One-liner
curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/repo_updater/main/install.sh | bash

# Verify
ru doctor

架构说明

• 约 17,700 行 Bash 代码，纯 Bash，除 git、curl、gh 外无外部依赖
• 工作窃取队列，用于并行同步，支持原子出队
• 使用 mkdir 实现可移植锁定（适用于所有 POSIX 系统）
• 路径安全验证可防止路径遍历攻击
• 网络操作采用指数退避重试

与 Flywheel 集成

工具	集成方式
Agent Mail	在仓库更新时通知 Agent；协调评审
BV	将仓库同步作为周期性 beads 进行跟踪
CASS	搜索过往同步会话和 Agent 扫描日志
NTM	用于会话编排的机器人模式 API
DCG	RU 在 DCG 沙箱保护下运行