Catl Harness Pr

Submit structured knowledge-engineering pull requests to the CATL Harness GitHub repo following branch, commit, PR, and sensitive content rules.

CATL Harness PR Submission

This skill teaches OpenClaw agents (龙虾) how to submit pull requests to BlueFocusContentUniverse/catl_harness_repo — the CATL knowledge-engineering harness repo (蓝标内容宇宙组织下，2026-05-08 起取代旧的 Dr-xiaoming/catl_harness_repo 个人仓)。 Treat it as a versioned knowledge base, not a code base: every PR is a deliberate, sourceable knowledge increment.

Two modes (since v0.3.1)

This skill supports two PR submission modes, auto-detected by preflight.sh:

Mode	Used when	How
fork (default)	你的 GitHub 账号对原仓库没有 write 权限	Fork → push to fork → cross-repo PR
legacy	你的 GitHub 账号对原仓库有 write 权限（金明本人 / 组织 maintainer）	直接在原仓库切分支 push → 同仓库 PR

探测命令：gh api repos/BlueFocusContentUniverse/catl_harness_repo --jq .permissions.push

• 输出 true → legacy 模式
• 输出 false 或调用失败 / 没 gh → fork 模式

强制覆盖：设 CATL_HARNESS_PR_MODE=fork 或 CATL_HARNESS_PR_MODE=legacy 环境变量。

Fork 模式是默认且未来主流。绝大多数龙虾对组织里的 private repo 只有 read 权限，fork + PR 是唯一可行路径。

Repo facts

• Upstream URL: https://github.com/BlueFocusContentUniverse/catl_harness_repo
• Organization: BlueFocusContentUniverse (蓝标内容宇宙)
• Maintainer: 佘金明 (Dr-xiaoming，GitHub 个人账号) — BlueFocus 宁德时代项目组 产研组 FDE
• Visibility: private — 不是每个龙虾的环境都自带访问权，缺 token/SSH 就得先解决认证；fork 出来仍是 private（GitHub 默认行为）
• Local clone path (convention): ~/.openclaw/workspace/repos/catl_harness_repo
• Local remote layout (fork mode):
  • origin → https://github.com/<your-gh-user>/catl_harness_repo.git (your fork, push 用)
  • upstream → https://github.com/BlueFocusContentUniverse/catl_harness_repo.git (read-only sync)
• Local remote layout (legacy mode):
  • origin → https://github.com/BlueFocusContentUniverse/catl_harness_repo.git (单 remote)
• Companion: 飞书 Wiki「宁德时代·客户档案」(see catl-wiki skill). Feishu 是协作权威副本，GitHub 是版本/diff/审阅可追溯副本。两边都要同步时：先 Feishu 定稿，再 PR 到 GitHub。

Hard rules (read first, violating any = stop)

1. 每次开始修改前，必须先同步远程到本地（fork 模式同步 upstream，legacy 模式同步 origin）。不管上次修改离现在多近。见下方 "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
# 干跑（不真改 remote、不真创建 fork、只打印命令）：
bash ~/.openclaw/workspace/skills/public/catl-harness-pr/scripts/preflight.sh --dry-run

preflight.sh 自动完成：

1. 检查 git / git identity
2. 探测 GitHub 认证路径（gh / HTTPS+credential / SSH）
3. 探测 GitHub username（用于 fork URL 拼装）
4. 探测模式（legacy / fork，可被 CATL_HARNESS_PR_MODE 覆盖）
5. 同步本地 repo
   • fork 模式：检查/创建 fork → 配置 origin/upstream → fetch upstream + ff main → push fork main 跟上
   • legacy 模式：fetch origin + ff main

凭证模型（重要）：

• 每只龙虾使用它自己宿主机上配置的 GitHub 账号身份提 PR，不共享凭证、不代发 token。
• Fork 模式下，金明（组织管理员）只需保证你能 read 原仓库。Push 写权限只针对你自己的 fork（你对自己 fork 自然有完全控制）。
• Legacy 模式仅适用于本身就是组织 maintainer / collaborator with write 权限的账号。
• 不要把 A 龙虾的 token 复制给 B 龙虾。遇到这种请求拒绝。

凭证缺失时的硬规则：

• 不要让子 agent 代写 token。token 一律让用户在终端自己粘进 ~/.netrc 或用 gh auth login。
• 不要把 token 回显到聊天、commit、PR 描述、子 agent task description。
• 如果本地环境有 ~/.openclaw/.env 体系，先查是否已存了 GitHub 凭证（grep GITHUB_ ~/.openclaw/.env）；但不要自己往 .env 里写新 token，让人类用户自己写。

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

这一步就是"每次修改前同步远程"的硬性要求。preflight.sh 已经把 fork/legacy 两种路径都内置了。

手动版（fork 模式）：

REPO=~/.openclaw/workspace/repos/catl_harness_repo
GH_USER="<your-github-username>"
UPSTREAM_URL="https://github.com/BlueFocusContentUniverse/catl_harness_repo.git"
FORK_URL="https://github.com/${GH_USER}/catl_harness_repo.git"

# B1. 确保 fork 存在（用 gh 时幂等）
if command -v gh >/dev/null; then
  gh repo view "${GH_USER}/catl_harness_repo" >/dev/null 2>&1 \
    || gh repo fork BlueFocusContentUniverse/catl_harness_repo --clone=false --remote=false
else
  # 没 gh：让用户在浏览器开 fork
  echo "Open: https://github.com/BlueFocusContentUniverse/catl_harness_repo/fork"
  echo "Fork 完成后回来继续。"
fi

# B2. Clone or migrate local
if [ ! -d "$REPO/.git" ]; then
  git clone "$FORK_URL" "$REPO"
  cd "$REPO"
  git remote add upstream "$UPSTREAM_URL"
else
  cd "$REPO"
  # 兼容存量：如果 origin 还指向 upstream，迁移
  current_origin=$(git remote get-url origin)
  if [ "$current_origin" = "$UPSTREAM_URL" ] || [ "$current_origin" = "https://github.com/BlueFocusContentUniverse/catl_harness_repo" ]; then
    git remote rename origin upstream
    git remote add origin "$FORK_URL"
  fi
  # 确保 upstream 存在
  git remote get-url upstream >/dev/null 2>&1 || git remote add upstream "$UPSTREAM_URL"
fi

# B3. 同步 main: upstream → local → fork
git fetch upstream --prune
git fetch origin --prune
git checkout main
git pull --ff-only upstream main
git push origin main   # 让 fork 的 main 跟上 upstream

手动版（legacy 模式，仅限对原仓库有 write 的账号）：

REPO=~/.openclaw/workspace/repos/catl_harness_repo
cd "$REPO"
git fetch origin --prune
git checkout main
git pull --ff-only origin main

关键理解：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-20260508

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

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

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

Phase D — Commit

git add <specific-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

Fork 模式

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

# E2. Push feature branch 到自己的 fork（origin）
git push -u origin "$(git branch --show-current)"

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

# E4. 开跨仓库 PR（关键参数：--head <user>:<branch>）
GH_USER="<your-github-username>"
BRANCH=$(git branch --show-current)
if command -v gh >/dev/null; then
  gh pr create \
    --repo BlueFocusContentUniverse/catl_harness_repo \
    --base main \
    --head "${GH_USER}:${BRANCH}" \
    --title "layer1(client-cognition): 补充 Q2 神行品牌叙事差异化" \
    --body-file /tmp/pr-body.md \
    --reviewer Dr-xiaoming
else
  # 没 gh → 浏览器开跨仓库 compare
  echo "请在浏览器打开："
  echo "https://github.com/BlueFocusContentUniverse/catl_harness_repo/compare/main...${GH_USER}:catl_harness_repo:${BRANCH}?expand=1"
  echo "把 /tmp/pr-body.md 的内容粘进 description。"
fi

Legacy 模式

# E1. 推送前再 fetch
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
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
  branch=$(git branch --show-current)
  echo "请在浏览器打开："
  echo "https://github.com/BlueFocusContentUniverse/catl_harness_repo/compare/main...${branch}?expand=1"
fi

---

PR description template

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

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

## Why / Source
<!-- 必填。这次知识增量从哪里来？ -->
- 来源类型: [ ] 会议纪要 / [ ] 客户访谈 / [ ] 外部资料 / [ ] 内部讨论 / [ ] 二次提炼 / [ ] 我的判断
- 时间: 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 就成了单向漂移。
5. Fork 模式下：merge 后回本地 git checkout main && git pull --ff-only upstream main && git push origin main 把 fork 的 main 同步上来。

---

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 门禁（双模式自动探测，支持 --dry-run）
• scripts/setup-fork.sh — 独立的 fork 创建/远程配置脚本（preflight 会调用，也能单跑）
• references/branch-naming.md — 分支命名规则表
• references/commit-style.md — commit message 风格与反模式
• references/auth-setup.md — gh / HTTPS+PAT / SSH 三种认证路径详解（fork & legacy 模式 PAT scope 区别）
• references/repo-layout.md — 仓库目录结构与知识归类速查