Harness Skills

使命

把 OpenAI "Harness Engineering" 七层模型里最关键的"意图层 + 约束层 + 反馈层"实装到一个真实 git 仓库，让团队用最短命令得到完整工作流：

TAPD 故事 → start-feature 一键拉分支 → 写代码 → commit（强制关联 TAPD）
         → push feature 分支（阻止直推 main）→ CNB 建 PR
         → cnbcool/ai-review 自动在 PR 评论里评审
         → 人类批准 → 合入 main → TAPD 故事"代码"Tab 自动回写

受众默认什么都没有：没 TAPD API 账号、没 CNB PAT、没 CNB 组织。skill 的职责是引导和装配。

快速决策树

用户说"把这个仓库接入 TAPD 和 CNB" / "装一下 harness": → 走完整装配流程 § 完整装配

用户说"我只想把 commit 关联 TAPD 故事": → 最小装配（仅 commit-msg hook）§ 最小装配

用户说"从 TAPD 故事拉分支开始做": → scripts/start-feature.sh <story_id> § 日常工作流

用户说"推送之后看不到 commit 在 TAPD 里": → 诊断章节 → 参考 references/troubleshooting.md

用户说"AI 代码评审能在 PR 里评论吗": → 确认 .cnb.yml 的 pull_request: 有 cnbcool/ai-review:latest stage

完整装配（最常用）

前置

必备工具：git, jq, curl, python3, bash。

需要用户获取的东西（skill 会引导但不能代做）：

1. TAPD workspace_id（项目 ID，10 位数字）：在 TAPD 登录后任意项目页 URL 里找。
2. TAPD API 账号：TAPD 公司管理 → API 账号管理，URL https://www.tapd.cn/<公司ID>/open_platform/config。创建时务必勾选目标 workspace 的授权，否则后续 403。
3. CNB 个人访问令牌：https://cnb.cool → 个人设置 → 访问令牌 (Access Tokens)。scope 勾 repo。
4. CNB 组织（group）path：用户在 CNB 至少要有一个 group（登录后左上角切换）。用户可能只有 cnb.<hash> 这种默认个人 group，最好建一个命名 group。

装配三步

🌟 推荐：交互式向导（零态用户首选）

SKILL=~/.workbuddy/skills/harness-skills        # 或通过 SkillHub 安装后的路径

# 一条命令进入向导，按提示一步步输入（会自动帮你打开 TAPD/CNB 获取凭据的页面）
bash $SKILL/scripts/install-harness.sh wizard /path/to/repo

向导会问你：

1. TAPD 公司ID → workspace_id → API User/Password → alias
2. CNB PAT → alias → 从你的 group 列表选一个 → CNB 仓库名
3. 是否 mirror 本地仓库、是否装自动推 TAPD 钩子

任意一步卡住都会给出获取指引，不会让你"卡在不知道填什么"。

或者：手工三步（适合脚本化/CI 用）

# 1. 绑 TAPD 凭据（workspace_id 需要你从 TAPD 页面 URL 里找）
TAPD_API_USER=<你的 API 账号> \
TAPD_API_PASSWORD=<你的 API 密钥> \
  bash $SKILL/scripts/install-harness.sh connect-tapd <alias> <你的 workspace_id>

# 2. 绑 CNB 凭据（PAT 从 cnb.cool 个人设置里生成）
CNB_TOKEN=<你的 CNB PAT> \
  bash $SKILL/scripts/install-harness.sh connect-cnb <alias>

# 3. 装配到仓库
bash $SKILL/scripts/install-harness.sh setup /path/to/repo \
  --auto-init \
  --tapd-alias=<上面的 alias> --workspace-id=<你的 workspace_id> \
  --cnb-alias=<上面的 alias> --cnb-org=<你的 CNB 组织> --cnb-repo=<仓库名> \
  --mirror     # 可选：同时把本地全量 mirror push 到新 CNB 仓

装完后：

• .codebuddy/connections.yml：记录 TAPD/CNB 绑定元数据（可 commit，无凭据）
• .cnb.yml：包含 main: push: 构建流水线 + main: pull_request: AI review + 常规 CI
• .tapd.yml：TAPD workspace 元数据，commit-msg hook 读它拼 URL
• .gitmessage：commit 模板，提示写 --story=<id> 格式
• .github/PULL_REQUEST_TEMPLATE.md：TAPD 关联段（追加，不覆盖上游）
• .git/hooks/commit-msg：校验 commit message 必须关联 TAPD 故事/缺陷/任务
• .git/hooks/pre-push：protect-main 拒绝直推受保护分支；可选 auto-push 到 TAPD
• .gitignore 追加 .codebuddy/secrets/ 和 .harness-bypass

日常工作流

A. 从 TAPD 故事开始做需求

bash $SKILL/scripts/start-feature.sh <STORY_ID>

这个命令会：

1. 调 TAPD API 查故事标题
2. 标题 slug 化（小写/去特殊字符/限 40 字符）
3. 新建分支 feature/<短ID>-<slug>
4. （如果能联网到 TAPD）把 TAPD 官方"源码提交关键字"塞进剪贴板

B. commit 格式

推荐（TAPD 官方完整格式）：

feat(scope): subject line ≤50 chars

说明改动原因。

--story=<SHORT_ID>@tapd-<WORKSPACE_ID> --user=<API_USER> [标题] https://www.tapd.cn/<WORKSPACE_ID>/s/<SHORT_LINK_ID>

最简（也被 hook 接受）：

--story=<id>   或   --bug=<id>   或   --task=<id>

获取官方完整格式的方法：

• TAPD 故事详情页右上角「复制源码提交关键字」
• 或（若 AI agent 装了 mcp-server-tapd）：调 get_commit_msg(workspace_id, options={object_id, type})
• 或 bash $SKILL/scripts/tapd-commit-tag.sh <alias> <story_id>

C. push + PR

git push cnb feature/<SHORT_ID>-xxx     # protect-main hook 放行 feature/*
# CNB 返回: Create PR at https://cnb.cool/<org>/<repo>/-/compare/main...feature/...

在 CNB 网页端创建 PR 后：

• cnbcool/ai-review:latest 插件自动跑，在 PR 评论里发代码评审意见
• 常规 CI（go test / bun lint 等）并行跑
• 人类 reviewer 批准 → 合入 main
• CNB → TAPD webhook（若 TAPD 项目 settings/devops 已启用云原生构建源码集成）自动在故事详情页「代码」Tab 添加 commit

D. commit 没出现在 TAPD？

两种原因，按顺序排查：

1. CNB 和 TAPD 的集成没开：去 TAPD 项目 → 项目设置 → DevOps → 启用「云原生构建源码」→ 关联 CNB 仓库。这是最标准路径。
2. 集成开了但不想依赖 Web webhook（例如私有化 / 离线审计）：
   • 在 setup 时加 --with-auto-push，装本地 pre-push 钩子，push 时自动调 TAPD Open API POST /code_commit_infos 推送 commit
   • 或事后用 bash $SKILL/scripts/push-commit-to-tapd.sh <alias> <repo> <sha> 手动补推

最小装配

只装 commit-msg hook（不接 CNB，不改 .cnb.yml）：

bash $SKILL/scripts/lib/install-commit-hook.sh install /path/to/repo

仅强制 commit 必须带 --story=<id> / --bug=<id> / --task=<id>。适合已经有自己的 CI 系统、只想加约束层的团队。

常见问题的快速答案

| 问题 | 答案 | |---|---| | API 账号 testauth 通过但 list workspace 403 | API 账号创建时没勾选 workspace 授权。去 /<公司ID>/open_platform/config 编辑授权 | | POST /orgs/<org>/repos 返回 404 | CNB 不是 GitHub 风格。正确是 POST /<org>/-/repos，字段 visibility_level: "Private" | | GET /user/orgs 返回 [] | CNB 叫 groups 不叫 orgs。用 GET /user/groups | | pull_request 里 AI review 没自动跑 | 检查 .cnb.yml 有没有 cnbcool/ai-review:latest stage；确认推的不是 main 而是 feature 分支；PR 要开到 main | | 直推 main 被 hook 拦截了 | 这是预期行为。走 PR 流程，或临时 HARNESS_ALLOW_MAIN_PUSH=1 git push ...（慎用）|

详见 references/troubleshooting.md。

深入主题

深度内容按需加载，避免 SKILL.md 膨胀：

• 完整工作流 + 给客户演示的剧本：references/workflow.md
• TAPD × CNB 集成的所有已知事实和踩坑：references/tapd-cnb-integration.md
• 故障排查清单（所有实测过的错误码 + 修复）：references/troubleshooting.md

卸载

bash $SKILL/scripts/uninstall-harness.sh /path/to/repo

默认保留：凭据文件、CNB 远端仓库、PR 模板里的 TAPD 段（需要手工删）。

脚本总览

| 脚本 | 用途 | 用户直接调 | |---|---|---| | scripts/install-harness.sh wizard | 交互式装配向导（零态首选） | ✅ | | scripts/install-harness.sh connect-tapd / connect-cnb / setup / status | 主入口的各子命令（手工/脚本化用） | ✅ | | scripts/start-feature.sh | 从 TAPD 故事拉 feature 分支 | ✅ | | scripts/tapd-commit-tag.sh | 取 TAPD 源码提交关键字 | ✅ | | scripts/push-commit-to-tapd.sh | 手动/CI 把 commit 推给 TAPD | ✅ | | scripts/verify-harness.sh | 仓库装配体检 | ✅ | | scripts/uninstall-harness.sh | 反向卸载 | ✅ | | scripts/lib/* | 内部工具（secrets-store / create-cnb-repo / mirror-to-cnb 等） | 一般不直接调 |

资产总览

• assets/cnb-templates/*.cnb.yml：5 种栈模板（go / node / python / terraform / mixed-go-node），main: pull_request: 段都带 cnbcool/ai-review:latest
• assets/git-hooks/*.sh：commit-msg 校验、pre-push 调度器、protect-main、可选的 TAPD 推送钩子
• assets/git/*：.gitmessage、.tapd.yml、PR 模板