From 07a218ce866291087eb6e6e21f5113e541b455b1 Mon Sep 17 00:00:00 2001
From: root
 <root@rjob-2fe3e7b54dafcbc9-f61eb500bddbbf61-0.chenxinquan.ailab-evobox.svc.pjlab.local>
Date: Thu, 22 Oct 2026 15:46:03 +0800
Subject: [PATCH] chore: fork-based PR workflow (push to origin, PR against
 upstream)

The upstream main branch is protected - direct pushes are rejected and
a PR needs one approving review. Development therefore moves to a fork
with a fixed remote layout:

  origin   = two-tiger/Tandem   (push target)
  upstream = AI45Lab/Tandem      (PR target)

scripts/pr.sh encodes that: it pushes the current branch to the fork
and opens the PR against upstream main, taking the title and body from
the latest commit when none are given. The head ref is spelled out as
<owner>:<branch> because cross-repository heads need the owner
namespace.

AGENTS.md documents the remote convention, the rebase-before-PR step
and the fact that upstream main must not be pushed to directly.
---
 AGENTS.md     |  7 ++++++-
 scripts/pr.sh | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 57 insertions(+), 1 deletion(-)
 create mode 100755 scripts/pr.sh

diff --git a/AGENTS.md b/AGENTS.md
index 401bf5a..95034bd 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -35,6 +35,11 @@
 改代码 → ruff check src tests → pytest →（若触碰协议）tandem check → PR（附单测 + smoke 链接）
 ```
 
+- **remote 约定**：`origin` = 自己的 fork（推送目标），`upstream` = 上游仓库（PR 目标）。
+  上游 `main` 受保护（需 review），**不能直接 push**，一律走 PR。
+- **提 PR**：`bash scripts/pr.sh` —— 把当前分支推到 fork，并向上游 `main` 开 PR
+  （标题/正文默认取最近一次提交信息）。提 PR 前先同步上游：
+  `git fetch upstream && git rebase upstream/main`。
 - `tandem check`：协议样例自检（CI 也跑）。
 - `tandem-eval rjob run …`：一站式提交（sync→spec→submit→watch→fetch→cleanup）。
   **收尾默认删 rjob**——成功/失败/超时/异常都删，不在集群上留残留；`--keep` 保留现场。
@@ -85,7 +90,7 @@ src/tandem_eval/         worker 侧 6 文件（entry/env/runner/recorder/scoring
 tests/                   protocol/ harness/ eval/ demo/ 四组
 infra/worker.sh          rjob worker 入口（mock 即跑；真实基准走共享 env.sh+docker）
 infra/config.json        唯一配置文件（含密钥 → gitignore；模板 config.example.json 提交）
-scripts/                 批量运行脚本（run_osw2_20x5.sh 等）
+scripts/                 批量运行脚本（run_osw2_20x5.sh 等）+ pr.sh（fork → 上游提 PR）
 tools/                   render_summary.py（demo 占位；完整 studio 后续平移）
 demo/                    轨迹回放与对比站点（adapter/metrics/frames/render + player/）
                          只读结果目录，不 import harness、不调模型、不碰 VM
diff --git a/scripts/pr.sh b/scripts/pr.sh
new file mode 100755
index 0000000..c7df6c8
--- /dev/null
+++ b/scripts/pr.sh
@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# 向开源上游提 PR：分支推到自己的 fork，PR 目标指向上游 main。
+#
+# remote 约定（见 docs/CLUSTER_RUNTIME.md 与本脚本头注释）：
+#   origin   = 自己的 fork     —— 推送目标
+#   upstream = 上游仓库        —— PR 目标（main 受保护，只能走 PR）
+#
+# 用法：
+#   bash scripts/pr.sh                        # 当前分支，按最近一次提交信息当标题
+#   bash scripts/pr.sh feature/foo "标题"      # 指定分支与标题
+#   bash scripts/pr.sh feature/foo "标题" "正文"
+#
+# 提交前应先同步上游：
+#   git fetch upstream && git rebase upstream/main
+set -euo pipefail
+
+UPSTREAM_REPO="${UPSTREAM_REPO:-AI45Lab/Tandem}"
+FORK_OWNER="${FORK_OWNER:-two-tiger}"
+FORK_REPO="${FORK_REPO:-$FORK_OWNER/Tandem}"
+
+BRANCH="${1:-$(git rev-parse --abbrev-ref HEAD)}"
+TITLE="${2:-}"
+BODY="${3:-}"
+
+if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
+  echo "不能从 $BRANCH 提 PR：上游 main 受保护，请先切特性分支" >&2
+  echo "  git switch -c feature/<名字>" >&2
+  exit 1
+fi
+
+if [ -z "$TITLE" ]; then
+  TITLE="$(git log -1 --format=%s)"
+fi
+if [ -z "$BODY" ]; then
+  # 非交互环境（CI / agent）下 gh 要求必须有 body：退回提交信息正文
+  BODY="$(git log -1 --format=%b)"
+fi
+if [ -z "$BODY" ]; then
+  BODY="$TITLE"
+fi
+
+echo "→ 推送分支到 fork：$FORK_REPO ($BRANCH)"
+git push -u origin "$BRANCH"
+
+args=(pr create --repo "$UPSTREAM_REPO" --head "$FORK_OWNER:$BRANCH" --base main --title "$TITLE")
+if [ -n "$BODY" ]; then
+  args+=(--body "$BODY")
+fi
+
+echo "→ 开 PR：$UPSTREAM_REPO:main ← $FORK_OWNER:$BRANCH"
+gh "${args[@]}"