xmwork/.claude/commands/sync-upstream.md at b39fbddd8451cc38d56c983d42143c45db865c13

Files

T

gongzhiyong b39fbddd84 feat: add 5 more team assets (upstream sync, migration review, pre-commit hook)

Commands:
- /sync-upstream [--dry-run]   — casdoor-internal upstream sync with commit classification
- /check-migrations [repo|all] — Alembic/Prisma/Drizzle consistency checker (focuses on xiaoshou pending migrations)

Specialist agents:
- migration-reviewer — Critical/High/Low severity review for DB schema changes across
  all 6 repos (Alembic, Prisma, Drizzle, xorm Sync2, raw SQL)

Playbooks:
- playbooks/casdoor-upstream-rebase.md — quarterly upstream rebase flow
  with commit classification, batched merging, cross-repo JWT compat check, rollback criteria

Hooks (active by default via settings.json):
- .claude/hooks/pre-commit-check.sh — PreToolUse on Bash:
  * blocks inline secrets in command strings (10+ patterns: sk-ant-, ghp_, AKIA, PEM, etc.)
  * on git commit, scans staged diff for same patterns
  * blocks diffs > 5000 lines (override with [huge-diff-ok] in commit msg)
- settings.json: wire PreToolUse hook

2026-04-23 23:57:41 +08:00

4.4 KiB

Raw Blame History

description, argument-hint

description

argument-hint

把 casdoor-internal 同步上游 casdoor/casdoor 的最新改动，冲突自动分析但不暴力解决

--dry-run

把 /workspace/casdoor-internal 和上游 https://github.com/casdoor/casdoor 同步。若传 --dry-run，只出报告不动代码。

前置检查

cd /workspace/casdoor-internal
git fetch upstream main 2>&1 || {
  echo "没配 upstream remote，先加："
  echo "  git remote add upstream https://github.com/casdoor/casdoor.git"
  exit 1
}

如果 .github/workflows/sync.yml 最近跑过，优先读它的日志看它做到哪一步。

第一阶段：侦察（永远执行）

git log --oneline ^HEAD upstream/main

对每个上游 commit 打标签：

标签	判断规则	处理
🟢 safe	纯 bugfix、只动测试、改注释/文档	可直接 cherry-pick
🟡 careful	碰了 `controllers/`、`object/`、`routers/`、`authz/`	手动 merge，hunk 级审查
🔴 dangerous	改了 `conf/app.conf`、`build.sh`、`docker-compose.yml`（我们的 skip-worktree 文件）	手动决策，绝不粗暴 merge
🔵 feature	新文件、新 API 端点	直接吸收，但要跑测试
⚫ breaking	go.mod 主版本升级、数据库 schema 变更、删 API	标记到报告，等人类决策

第二阶段：如果 `--dry-run`

生成 /workspace/ai-ops/reports/casdoor-sync-$(date +%Y-%m-%d).md：

# Casdoor 上游同步计划 YYYY-MM-DD

## 上游新增 commits: N 个
| Hash | 类别 | 描述 | 建议动作 |
|---|---|---|---|
...

## 高风险项
- ⚫ commit xxx 升级了 Beego v2 → v3（我们的 Makefile 锁死在 v2.3.8，拒绝）
- 🔴 commit yyy 改了 conf/app.conf（我们 skip-worktree，需要人工评估）

## 建议 merge 顺序
1. 先 cherry-pick 所有 🟢
2. 再按文件分组处理 🟡
3. 🔴/⚫ 单独列 PR 等人类决策

## 影响评估
- 是否破坏 ACA 部署？<是/否 + 理由>
- 是否影响 chat-gw/xiaoshou/gongdan/lobechat 的 JWT 解析？<评估>

到此结束，dry-run 不动代码。

第三阶段：真干（没传 --dry-run 才执行）

只处理 🟢 + 🟡 + 🔵。🔴 和 ⚫ 永远不动。

3.1 拉分支

git checkout -b chore/sync-upstream-$(date +%Y-%m-%d)

3.2 分批 merge（不要一次性 merge upstream/main）

批次 A：纯 bugfix（🟢）

for hash in <🟢 列表>; do
  git cherry-pick $hash || {
    echo "冲突于 $hash，跳过，记录到报告"
    git cherry-pick --abort
  }
done
make fmt && make vet && make ut

批次 B：feature（🔵） cherry-pick，每个都跑 make ut，失败就 revert。

批次 C：careful（🟡） 逐个 commit，逐个 hunk 审查：

上游改了我们动过的代码 → 保留我们的，手动吸收上游新逻辑
上游重命名 → 在本地也重命名
上游删除 → 只在确认本地没引用后才删

3.3 前端改动

如果有 web/* 冲突：

cd web
yarn && yarn build   # 必须通过
cd ..

3.4 Docker 构建验证

sh ./build.sh
make docker-build

第四阶段：产出 PR

git push -u origin chore/sync-upstream-$(date +%Y-%m-%d)
gh pr create --title "chore: sync with upstream casdoor $(git rev-parse --short upstream/main)" --body-file /tmp/sync-pr-body.md

PR body 必须包含：

## 同步范围
- 上游 commit 区间：<start-hash>..<end-hash>
- 吸收 X 个 safe、Y 个 feature、Z 个 careful
- **拒绝/挂起** N 个 dangerous + breaking（见下方"需人工决策"）

## 本地验证
- [x] `make fmt`
- [x] `make vet`
- [x] `make ut`
- [x] `yarn build`
- [x] `make docker-build`

## 风险评估
- JWT claim 字段：<是否变化>
- ACA 部署配置：<是否需要改 build-and-deploy.yml>
- 对下游仓库（chat-gw/xiaoshou/gongdan/lobechat）的影响：<无/需同步改动>

## 需人工决策
- commit xxx（Beego 升级）：已挂起
- conf/app.conf 上游改动：已挂起，等确认 Azure PG 连接逻辑是否受影响

红线

❌ 禁止 git merge -X theirs upstream/main
❌ 禁止 git merge -X ours upstream/main
❌ 禁止修改 conf/app.conf 或其他 skip-worktree 文件
❌ 禁止升级 go.mod 里 beego、xorm 主版本
❌ 禁止在冲突无法判断时"猜一个"，应挂起到 PR 的"需人工决策"段落
✅ 任何 🔴/⚫ 改动一律转化为"PR 描述里的决策项"，绝不自动执行

4.4 KiB Raw Blame History Unescape Escape