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 会引导但不能代做）：
- TAPD workspace_id（项目 ID，10 位数字）：在 TAPD 登录后任意项目页 URL 里找。
- TAPD API 账号：TAPD 公司管理 → API 账号管理，URL
https://www.tapd.cn/<公司ID>/open_platform/config。创建时务必勾选目标 workspace 的授权，否则后续 403。 - CNB 个人访问令牌：
https://cnb.cool→ 个人设置 → 访问令牌 (Access Tokens)。scope 勾repo。 - 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>
这个命令会：
- 调 TAPD API 查故事标题
- 标题 slug 化（小写/去特殊字符/限 40 字符）
- 新建分支
feature/<短ID>-<slug> - （如果能联网到 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？
两种原因，按顺序排查：
- CNB 和 TAPD 的集成没开：去 TAPD 项目 → 项目设置 → DevOps → 启用「云原生构建源码」→ 关联 CNB 仓库。这是最标准路径。
- 集成开了但不想依赖 Web webhook（例如私有化 / 离线审计）：
- 在setup时加--with-auto-push，装本地 pre-push 钩子，push 时自动调 TAPD Open APIPOST /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:latestassets/git-hooks/*.sh：commit-msg 校验、pre-push 调度器、protect-main、可选的 TAPD 推送钩子assets/git/*：.gitmessage、.tapd.yml、PR 模板
