CATL Harness PR Submission

This skill teaches OpenClaw agents (龙虾) how to submit pull requests to Dr-xiaoming/catl_harness_repo — the CATL knowledge-engineering harness repo. Treat it as a versioned knowledge base, not a code base: every PR is a deliberate, sourceable knowledge increment.

Repo facts

• URL: https://github.com/Dr-xiaoming/catl_harness_repo
• Owner: 佘金明 (Dr-xiaoming) — BlueFocus 宁德时代项目组 产研组 FDE
• Visibility: private — 不是每个龙虾的环境都自带访问权，缺 token/SSH 就得先解决认证
• Local clone path (convention): ~/.openclaw/workspace/repos/catl_harness_repo
• Companion: 飞书 Wiki「宁德时代·客户档案」(see catl-wiki skill). Feishu 是协作权威副本，GitHub 是版本/diff/审阅可追溯副本。两边都要同步时：先 Feishu 定稿，再 PR 到 GitHub。

Hard rules (read first, violating any = stop)

1. 每次开始修改前，必须先同步远程 main 到本地。不管上次修改离现在多近。见下方 "Phase B: sync"。
2. 永不直推 main。所有改动走 feature branch + PR，即使是 typo。
3. PR 必须有来源。每个知识增量必须能回溯到一次会议、一份纪要、一次客户沟通、一份外部资料、或一份内部讨论。
4. 不泄露甲方未公开内容。即使 repo 是私有的，PR 描述/commit/diff 也不要直接复述甲方原话。遇到敏感资料写成"源自客户访谈纪要 (内部，2026-XX-XX)"即可。
5. 不把蓝标判断写进客户的嘴里。蓝标内部分析放 internal-analysis/ 或 frontmatter tags: [bluefocus-pov]，不要混入 layer1-client-cognition/。
6. 大改动先开 issue。新增 layer、调目录结构、删节点 → 先开 issue @Dr-xiaoming 确认方向。

Execution phases (do them in order, do not skip)

Phase A — Environment preflight (每个新环境只需跑一次，但每次对话开头要验证)

龙虾接到"向 harness 仓库提 PR"任务时，第一个动作是跑这个门禁。任一项失败，停下来向用户报告缺什么，不要硬往下走。

bash ~/.openclaw/workspace/skills/public/catl-harness-pr/scripts/preflight.sh

或手动版：

# A1. git 是否存在
command -v git >/dev/null || { echo "❌ git 未安装，请先 brew install git 或 apt install git"; exit 1; }
git --version

# A2. git identity 是否设过
name=$(git config --global user.name)
email=$(git config --global user.email)
[ -n "$name" ] && [ -n "$email" ] || {
  echo "❌ git identity 未设，请先:"
  echo "   git config --global user.name \"Your Name\""
  echo "   git config --global user.email \"[email protected]\""
  exit 1
}
echo "✓ git identity: $name \x3C$email>"

# A3. GitHub 认证 — 三条路径按优先级探测
if command -v gh >/dev/null && gh auth status >/dev/null 2>&1; then
  AUTH_ROUTE="gh"
elif git ls-remote https://github.com/Dr-xiaoming/catl_harness_repo.git HEAD >/dev/null 2>&1; then
  AUTH_ROUTE="https+credential"   # ~/.netrc 或 credential helper 已配
elif ssh -T [email protected] 2>&1 | grep -q "successfully authenticated"; then
  AUTH_ROUTE="ssh"
else
  AUTH_ROUTE="none"
fi
echo "auth route: $AUTH_ROUTE"
[ "$AUTH_ROUTE" = "none" ] && {
  echo "❌ 没有可用的 GitHub 认证。见 references/auth-setup.md。"
  echo "   告诉用户选一条："
  echo "   (1) 装 gh 并 gh auth login"
  echo "   (2) 生成 PAT (repo 权限) 写入 ~/.netrc"
  echo "   (3) 配 SSH key 并加到 GitHub 账号"
  exit 1
}

凭证缺失时的硬规则：

• 不要让子 agent 代写 token。token 一律让用户在终端自己粘进 ~/.netrc 或用 gh auth login。
• 不要把 token 回显到聊天、commit、PR 描述、子 agent task description。
• 如果用户环境是 ~/.openclaw/.env 体系（金明的机器），可以告诉他检查 grep GITHUB_ ~/.openclaw/.env；但不要自己往 .env 里写新 token。

Phase B — Repo sync (每次修改前都要跑，不是只跑一次)

这一步就是"每次修改前同步远程"的硬性要求。

REPO=~/.openclaw/workspace/repos/catl_harness_repo

# B1. Clone if missing — 容错：如果目录存在但不是 git repo，报错不覆盖
if [ ! -d "$REPO/.git" ]; then
  if [ -d "$REPO" ] && [ -n "$(ls -A "$REPO")" ]; then
    echo "❌ $REPO 已存在但不是 git repo，不敢覆盖。人工确认后再处理。"
    exit 1
  fi
  mkdir -p "$(dirname "$REPO")"
  git clone https://github.com/Dr-xiaoming/catl_harness_repo.git "$REPO"
fi
cd "$REPO"

# B2. 检查本地残留 — 未提交改动、unpushed 分支都要先处理
if ! git diff --quiet || ! git diff --cached --quiet; then
  echo "⚠️  本地有未提交改动:"
  git status --short
  echo "决策树："
  echo " - 是本次任务的延续 → git stash 暂存，干完再 pop"
  echo " - 是上次任务忘提交的 → 停下来，先确认这些改动该不该提 / 该去哪个分支"
  echo " - 是废弃草稿 → git restore . 丢弃（确认再做）"
  exit 1
fi

current=$(git branch --show-current)
if [ "$current" != "main" ]; then
  echo "ℹ️  当前在分支 $current，不是 main"
  # 检查是否有 unpushed commits
  if [ -n "$(git log @{u}.. 2>/dev/null)" ]; then
    echo "⚠️  $current 有未推送的 commit，先评估是否要推送或丢弃，再继续。"
    git log --oneline @{u}..
    exit 1
  fi
fi

# B3. 强制从远程同步 main —— 这一步就是「每次修改前同步远程」
git fetch origin --prune
git checkout main
git pull --ff-only origin main || {
  echo "❌ main 不能 fast-forward，可能本地有 diverged 状态，人工处理。"
  exit 1
}
echo "✓ main 已同步到 $(git rev-parse --short HEAD)"

关键理解：Phase B 不是 Phase A 的延续，而是每次开工前都跑一遍的独立门禁。即使 10 分钟前刚跑过，也要重跑——别的协作者可能刚刚合了 PR。

Phase C — Make changes on a feature branch

# C1. 从最新的 main 切新分支（分支名见 references/branch-naming.md）
git checkout -b layer1/client-cognition-update-20260507

# C2. 进行实际修改 —— 只改 markdown，除非明确要求
# (edit files here)

# C3. 本地 review
git status
git diff --stat
git diff | head -200      # 眼过一遍实际内容

# C4. 如果看到 .DS_Store / IDE 文件 / 个人笔记 / 原始 chat 记录 — 立刻清
# git restore --staged \x3Cfile>  或  把它加进 .gitignore

Phase D — Commit

git add \x3Cspecific-files>   # 不要 git add .，容易带脏文件

git commit -m "layer1(client-cognition): 补充 Q2 神行品牌叙事差异化要点

- 来源: 2026-05-06 虞旸定稿 draft-v2 + 5/3 客户访谈
- 影响范围: layer1/客户认知底座.md 第 3 节
- 审阅人: @Dr-xiaoming"

Commit message 规则完整版见 references/commit-style.md。必须带「来源 / 影响范围 / 审阅人」三段。

Phase E — Push & open PR

# E1. 推送前再 fetch 一次，确认 main 没变化（很快，几乎零成本）
git fetch origin main
behind=$(git rev-list --count HEAD..origin/main)
if [ "$behind" -gt 0 ]; then
  echo "⚠️  main 在我干活期间前进了 $behind 个 commit，考虑 rebase："
  echo "   git rebase origin/main"
fi

# E2. Push 新分支
git push -u origin "$(git branch --show-current)"

# E3. 写 PR body 到 /tmp/pr-body.md（模板见下节）

# E4. 开 PR
if command -v gh >/dev/null; then
  gh pr create \
    --title "layer1(client-cognition): 补充 Q2 神行品牌叙事差异化" \
    --body-file /tmp/pr-body.md \
    --base main \
    --reviewer Dr-xiaoming
else
  # 没 gh → 把 compare URL 给用户，让他浏览器开 PR
  branch=$(git branch --show-current)
  echo "请在浏览器打开："
  echo "https://github.com/Dr-xiaoming/catl_harness_repo/compare/main...${branch}?expand=1"
  echo "把 /tmp/pr-body.md 的内容粘进 description。"
fi

PR description template

写到 /tmp/pr-body.md，是每个 harness PR 的合同：

## What
\x3C!-- 一句话说明这次 PR 改了什么。不要写「更新文档」这种废话。 -->

## Why / Source
\x3C!-- 必填。这次知识增量从哪里来？ -->
- 来源类型: [ ] 会议纪要 / [ ] 客户访谈 / [ ] 外部资料 / [ ] 内部讨论 / [ ] 二次提炼 / [ ] 我的判断
- 时间: 2026-XX-XX
- 关联资料: (Feishu 链接 / 文件路径 / 会议名)

## Scope of impact
- 影响 Layer: [ ] L1 客户认知 / [ ] L2 行业认知 / [ ] L3 项目方法论 / [ ] SOP / [ ] 其他
- 下游引用: (列出会用到这份知识的 agent / skill / 任务)

## Sensitive content check
- [ ] 没有甲方原话 / 内部敏感措辞
- [ ] 没有把蓝标主观判断写成「客户立场」
- [ ] 客户/竞品名字处理符合 Layer 1 红线

## Reviewers
- [ ] @Dr-xiaoming (默认必审)
- [ ] (可选) 业务侧第二审阅人

Default reviewer 永远是 @Dr-xiaoming。第二审阅人仅在跨业务域时加。

After the PR is opened

1. 立刻把 PR URL 回传给用户。
2. 不要自动 merge，即使有权限。等人工（金明）review。
3. 收到 review 意见：在同一分支上追加 commit；不要 force-push，除非明确要求 rebase 清历史。
4. merge 之后：如果这份内容同时在飞书 Wiki 存在，确认 Wiki 版本已先于 GitHub 更新——否则 GitHub 就成了单向漂移。

When this skill does NOT apply

• 其他 GitHub 项目的 PR — 用通用 git/gh 知识，不要套用这里的知识工程模板。
• 直接编辑飞书 Wiki / 飞书云文档 — 用 catl-wiki 或 feishu-doc skill。
• 本地 Obsidian 笔记同步 — 用 obsidian-openclaw-sync skill。

Bundled resources

• scripts/preflight.sh — 一键跑 Phase A + Phase B 门禁
• references/branch-naming.md — 分支命名规则表
• references/commit-style.md — commit message 风格与反模式
• references/auth-setup.md — gh / HTTPS+PAT / SSH 三种认证路径详解
• references/repo-layout.md — 仓库目录结构与知识归类速查