harveyz-skill 0.2.1 → 0.4.0

package/skills/harness/git-workflow-init/evals/evals.json

@@ -0,0 +1,104 @@
+{
+  "skill_name": "git-workflow-init",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "我刚在 /tmp/gwi-test-basic 创建了一个新的 Python 项目目录，已经 git init 了。目录里有一个 workflow-config.yml，内容是默认的 gitflow 配置（branches.protected 包含 main 和 staging，commit_message.enforce: true，tags.enforce: true，push_rules.enforce: true）。请帮我完整运行 git 工作流初始化，不需要更新 AI 配置文件。",
+      "expected_output": "skill 读取 workflow-config.yml，审核通过，在 /tmp/gwi-test-basic 中生成 .githooks/pre-commit、.githooks/commit-msg、.githooks/pre-push，设置 core.hooksPath，并生成 docs/reference/git-workflow.md",
+      "files": [],
+      "expectations": [
+        "skill 读取了项目根目录的 workflow-config.yml",
+        "审核步骤执行且通过，打印审核通过信息",
+        "pre-commit hook 内容包含对 main 和 staging 的保护逻辑，且基于配置动态生成",
+        "commit-msg hook 内容包含 Conventional Commits 检查和 max_subject_length 检查",
+        "pre-push hook 内容包含 tag 命名校验（refs/tags/* 分支）和 force push 阻断（refs/heads/* 分支）",
+        "所有 hook 安装在 .githooks/ 目录，core.hooksPath 已设置为 .githooks",
+        "docs/reference/git-workflow.md 已创建且内容反映配置中的实际规则"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "我的项目在 /tmp/gwi-test-custom，已 git init，根目录有 workflow-config.yml，其中 branch_naming.enforce: true，commit_message.format: regex，commit_message.pattern: '^(JIRA-\\d+|NOJIRA): .{1,80}'，tags.enforce: false，push_rules.enforce: false。请运行 git 工作流初始化。",
+      "expected_output": "skill 安装 pre-commit、commit-msg、post-checkout hook，不安装 pre-push hook；commit-msg hook 使用自定义 regex 而非 Conventional Commits",
+      "files": [],
+      "expectations": [
+        "commit-msg hook 使用配置中的 pattern 字段进行校验，不使用 Conventional Commits 类型列表",
+        "post-checkout hook 已安装，包含分支命名检查逻辑",
+        "pre-push hook 未创建（tags.enforce 和 push_rules.enforce 均为 false）",
+        "core.hooksPath 已设置为 .githooks"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "我的项目在 /tmp/gwi-test-claudemd，已 git init，目录里有默认 workflow-config.yml 和一个内容为 '# My Project\\n\\n这是一个 Node.js 项目。' 的 CLAUDE.md。请完整运行初始化并在 CLAUDE.md 中追加对 git 文档的索引引用。",
+      "expected_output": "hooks 已安装，docs/reference/git-workflow.md 已创建，CLAUDE.md 末尾追加了 Git Workflow 引用段落（只是索引链接，非完整内容）",
+      "files": [],
+      "expectations": [
+        "所有 hooks 已安装在 .githooks/ 目录",
+        "core.hooksPath 已设置为 .githooks",
+        "docs/reference/git-workflow.md 已创建",
+        "CLAUDE.md 中追加了对 docs/reference/git-workflow.md 的链接引用",
+        "CLAUDE.md 的引用只是索引链接，没有把完整 git 规范内容写进去"
+      ]
+    },
+    {
+      "id": 4,
+      "prompt": "帮我配置 git 分支管理规范。我当前目录是 /tmp/gwi-test-nogit（目录存在但没有 git init 过）。",
+      "expected_output": "skill 检测到不在 git 仓库中，向用户说明情况并询问是否先执行 git init，而不是直接报错退出或静默跳过",
+      "files": [],
+      "expectations": [
+        "skill 执行了 git rev-parse --show-toplevel 或等效命令来检测 git 仓库",
+        "skill 检测到非 git 仓库后，没有静默跳过，也没有直接崩溃报错",
+        "skill 向用户询问是否先执行 git init（而不是自动执行）",
+        "用户拒绝后 skill 优雅停止，没有留下半完成的状态"
+      ]
+    },
+    {
+      "id": 5,
+      "prompt": "我的项目在 /tmp/gwi-test-badconfig，已 git init，根目录有一个 workflow-config.yml，内容存在以下问题：1) main 的 merge_from 包含 'main' 自身；2) branch_naming.allowed_patterns 里有一个非法正则 '[unclosed'；3) commit_message.format 设为 'regex' 但没有 pattern 字段。请运行初始化。",
+      "expected_output": "skill 在审核阶段发现三个问题并一次性列出，停止执行，不部署任何 hook 文件",
+      "files": [],
+      "expectations": [
+        "skill 执行了配置审核步骤",
+        "审核报告一次性列出所有三个问题：循环依赖、非法正则、缺少 pattern 字段",
+        "审核失败后 skill 停止，没有创建任何 .githooks/ 文件",
+        "skill 提示用户修复配置后重新运行"
+      ]
+    },
+    {
+      "id": 6,
+      "prompt": "帮我配置 git 分支管理规范。我的项目在 /tmp/gwi-test-noconfig，已 git init，但目录里没有 workflow-config.yml。",
+      "expected_output": "skill 提示找不到配置文件，询问用户是否使用默认配置（从 references/workflow-config.yml 复制），用户同意后继续执行完整流程",
+      "files": [],
+      "expectations": [
+        "skill 检测到项目根目录和 .claude/ 目录均无 workflow-config.yml",
+        "skill 询问用户是否使用默认配置，未自动复制",
+        "用户同意后，skill 将 references/workflow-config.yml 复制到项目根目录",
+        "随后继续完整的审核和部署流程"
+      ]
+    }
+  ],
+  "v4_evals": [
+    {
+      "id": 7,
+      "name": "hash-check",
+      "prompt": "这个项目的 git hooks 已经安装过（有 MANAGED 块和 hash 标记），但我手动修改了 pre-commit 里 main 分支 MANAGED 块的错误提示文字，没有更新 hash。现在重新运行 git-workflow-init，处理这个变更。",
+      "expected_output": "skill 重算 MANAGED 块 hash，发现与标记不符，报告 type C 冲突（手改冲突），展示 diff，询问用户保留修改还是用新配置覆盖，按用户决策处理。",
+      "assertions": []
+    },
+    {
+      "id": 8,
+      "name": "lock-diff-add-branch",
+      "prompt": "我在 workflow-config.yml 里新增了 develop 分支保护规则（merge_from: feature/*）。上次安装时的 lock 文件里没有 develop。现在重新运行 git-workflow-init，同步变更。",
+      "expected_output": "skill 对比 lock 文件与当前配置，检测到 develop 是新增分支，在 pre-commit 插入对应 MANAGED 块，更新 lock 文件，报告 pre-commit 状态为 UPDATED。",
+      "assertions": []
+    },
+    {
+      "id": 9,
+      "name": "conflict-scanner",
+      "prompt": "我在 pre-commit 的 MANAGED 块外手写了 develop 分支的保护逻辑。现在 workflow-config.yml 也把 develop 加入了 branches.protected。重新运行 git-workflow-init。",
+      "expected_output": "skill 扫描 MANAGED 块外的用户代码，发现 develop 分支在用户代码和新配置中都有处理，报告 type A 冲突（条件重叠），提供三个选项让用户决策后再写入。",
+      "assertions": []
+    }
+  ]
+}

package/skills/harness/git-workflow-init/references/git-workflow-template.md

@@ -0,0 +1,94 @@
+# Git 工作流规范
+
+本文档定义此项目的分支管理规则与开发协作约定。
+
+> 本文档由 `git-workflow-init` 根据 `workflow-config.yml` 自动生成，请勿手动编辑。
+> 如需修改规则，请更新 `workflow-config.yml` 后重新运行 `/git-workflow-init`。
+
+---
+
+## 分支模型
+
+```
+{{BRANCH_TOPOLOGY_ASCII}}
+```
+
+{{BRANCH_TABLE}}
+
+---
+
+## 分支保护规则
+
+以下规则由 `.githooks/pre-commit` 自动强制执行：
+
+{{PROTECTION_RULES}}
+
+提交被拒绝时，请检查当前所在分支，改用正确的合并流程操作。
+
+---
+
+## 标准开发流程
+
+### 开始新工作
+
+```bash
+# 始终从集成分支拉取
+{{WORKFLOW_CHECKOUT_EXAMPLE}}
+git pull
+git checkout -b feature/my-feature
+```
+
+### 合并到集成分支
+
+```bash
+{{WORKFLOW_MERGE_EXAMPLE}}
+git push
+```
+
+### 发布到主分支
+
+```bash
+{{WORKFLOW_RELEASE_EXAMPLE}}
+```
+
+---
+
+## 分支命名规范
+
+{{NAMING_TABLE}}
+
+使用 kebab-case，名称简短且有描述性。豁免分支（{{NAMING_EXEMPT}}）不受命名规范约束。
+
+---
+
+## 提交信息格式
+
+{{COMMIT_FORMAT_SECTION}}
+
+---
+
+## Hooks 安装说明
+
+git hooks 通过 `.githooks/` 目录管理（已纳入版本控制），并设置 `core.hooksPath = .githooks`。
+
+新克隆仓库后需手动激活：
+
+```bash
+git config core.hooksPath .githooks
+git config merge.ff false   # 禁止 fast-forward，确保 merge commit 可被钩子审查
+```
+
+或通过 Claude Code 重新运行安装 skill：
+
+```
+/git-workflow-init
+```
+
+---
+
+## 常见问题
+
+{{FAQ_SECTION}}
+
+**Q：能绕过 hooks 吗？**
+A：可以用 `git commit --no-verify`，但请记录原因并告知团队。hooks 存在有其意义，请谨慎绕过。

package/skills/harness/git-workflow-init/references/hook-templates.md

@@ -0,0 +1,232 @@
+# Hook 代码模板
+
+Step 6 生成 hooks 时参考此文件。
+
+---
+
+## 通用结构
+
+每个 hook 文件由三部分组成：
+
+```
+固定头部（非 MANAGED，每次重新生成时原样保留）
+│
+├── # --- BEGIN MANAGED: <block-id> (hash:<8hex>) ---
+│   <配置驱动的生成内容>
+│   # --- END MANAGED: <block-id> ---
+│
+│   （可有多个 MANAGED 块）
+│
+用户自定义区（MANAGED 块之外，永不覆盖）
+│
+固定尾部：exit 0
+```
+
+### MANAGED 块 ID 规范
+
+| hook 文件 | 块 ID |
+|-----------|-------|
+| pre-commit | `branches.protected/<branch-name>` |
+| commit-msg | `commit-msg/format`、`commit-msg/length` |
+| pre-push | `pre-push/tags`、`pre-push/force-push` |
+| post-checkout | `post-checkout/branch-naming` |
+
+---
+
+## pre-commit
+
+触发条件：`branches.protected` 存在时生成。
+
+**固定头部：**
+```sh
+#!/bin/sh
+# Generated by git-workflow-init v4.0.0
+# Manual edits outside MANAGED blocks are preserved across runs.
+BRANCH=$(git symbolic-ref --short HEAD 2>/dev/null)
+[ -z "$BRANCH" ] && exit 0
+IS_MERGE=0
+[ -f "$(git rev-parse --git-dir)/MERGE_HEAD" ] && IS_MERGE=1
+
+merge_source_branch() {
+    msg_file="$(git rev-parse --git-dir)/MERGE_MSG"
+    [ -f "$msg_file" ] || { printf ''; return; }
+    head -1 "$msg_file" | sed "s/Merge branch '//;s/'.*//"
+}
+```
+
+**每个保护分支生成一个 MANAGED 块**（以 main 为例，merge_from: staging, release/*）：
+```sh
+# --- BEGIN MANAGED: branches.protected/main (hash:<hash>) ---
+if [ "$BRANCH" = "main" ]; then
+    if [ "$IS_MERGE" -eq 0 ]; then
+        echo "❌ 禁止直接在 main 上提交。请在 staging 或 release/* 分支开发后合并。"
+        exit 1
+    fi
+    SRC=$(merge_source_branch)
+    case "$SRC" in
+        staging|release/*) exit 0 ;;
+        *) echo "❌ main 只接受来自 staging 或 release/* 的合并，当前来源：'${SRC:-unknown}'"; exit 1 ;;
+    esac
+fi
+# --- END MANAGED: branches.protected/main ---
+```
+
+`case` 模式从配置的 `merge_from` 列表动态生成，`|` 分隔。
+`allow_direct_commit: true` 时将 `exit 1` 改为 `echo "⚠️ 警告"`（不阻断）。
+
+**固定尾部：**`exit 0`
+
+---
+
+## commit-msg
+
+触发条件：`commit_message.enforce: true` 时生成。
+
+**固定头部：**
+```sh
+#!/bin/sh
+# Generated by git-workflow-init v4.0.0
+MSG=$(cat "$1")
+SUBJECT=$(printf '%s\n' "$MSG" | head -1)
+SUBJECT=$(printf '%s\n' "$SUBJECT" | sed '/^#/d' | sed 's/^[[:space:]]*//')
+[ -z "$SUBJECT" ] && exit 0
+```
+
+**格式检查 MANAGED 块（`commit-msg/format`）：**
+- `format: conventional`：将 `types` 列表拼接为正则 `^(feat|fix|...)(\(.+\))?: .+`；`require_scope: false` 时 scope 部分为可选 `(\(.+\))?`
+- `format: regex`：使用配置的 `pattern` 字段直接作为 grep 表达式
+
+**长度检查 MANAGED 块（`commit-msg/length`）：**
+```sh
+# --- BEGIN MANAGED: commit-msg/length (hash:<hash>) ---
+LEN=$(printf '%s' "$SUBJECT" | wc -c | tr -d ' ')
+if [ "$LEN" -gt <max_subject_length> ]; then
+    echo "❌ 提交信息首行超过 <max_subject_length> 个字符（当前 ${LEN} 个字符）"
+    exit 1
+fi
+# --- END MANAGED: commit-msg/length ---
+```
+
+**固定尾部：**`exit 0`
+
+---
+
+## pre-push
+
+触发条件：`tags.enforce: true` 或 `push_rules.enforce: true` 时生成。
+
+**固定头部：**
+```sh
+#!/bin/sh
+# Generated by git-workflow-init v4.0.0
+while IFS=' ' read -r local_ref local_sha remote_ref remote_sha; do
+    case "$remote_ref" in
+```
+
+**tag 检查 MANAGED 块（`pre-push/tags`，仅当 `tags.enforce: true`）：**
+```sh
+# --- BEGIN MANAGED: pre-push/tags (hash:<hash>) ---
+        refs/tags/*)
+            TAG=$(printf '%s' "$remote_ref" | sed 's|refs/tags/||')
+            MATCHED=0
+            for PATTERN in <allowed_patterns>; do
+                printf '%s\n' "$TAG" | grep -qE "$PATTERN" && MATCHED=1 && break
+            done
+            if [ "$MATCHED" -eq 0 ]; then
+                echo "❌ Tag 命名不符合规范：$TAG"
+                exit 1
+            fi
+            ;;
+# --- END MANAGED: pre-push/tags ---
+```
+
+**force push 检查 MANAGED 块（`pre-push/force-push`，仅当 `push_rules.enforce: true`）：**
+```sh
+# --- BEGIN MANAGED: pre-push/force-push (hash:<hash>) ---
+        refs/heads/main|refs/heads/staging)
+            if [ "$local_sha" = "0000000000000000000000000000000000000000" ]; then
+                echo "❌ 禁止 force push 到受保护分支：$remote_ref"
+                exit 1
+            fi
+            ;;
+# --- END MANAGED: pre-push/force-push ---
+```
+
+`refs/heads/main|refs/heads/staging` 从 `push_rules.block_force_push` 列表动态生成。
+
+**固定尾部：**
+```sh
+    esac
+done
+exit 0
+```
+
+---
+
+## post-checkout
+
+触发条件：`branch_naming.enforce: true` 时生成。
+
+**固定头部：**
+```sh
+#!/bin/sh
+# Generated by git-workflow-init v4.0.0
+[ "$3" = "1" ] || exit 0
+BRANCH=$(git symbolic-ref --short HEAD 2>/dev/null)
+[ -z "$BRANCH" ] && exit 0
+```
+
+**命名检查 MANAGED 块（`post-checkout/branch-naming`）：**
+```sh
+# --- BEGIN MANAGED: post-checkout/branch-naming (hash:<hash>) ---
+case "$BRANCH" in
+    <exempt-branch-1>|<exempt-branch-2>) exit 0 ;;
+esac
+MATCHED=0
+for PATTERN in <allowed_patterns>; do
+    printf '%s\n' "$BRANCH" | grep -qE "$PATTERN" && MATCHED=1 && break
+done
+if [ "$MATCHED" -eq 0 ]; then
+    echo "⚠️ 分支命名不符合规范：$BRANCH"
+    echo "   允许的格式：<allowed_patterns 列表>"
+fi
+# --- END MANAGED: post-checkout/branch-naming ---
+```
+
+`exempt` 列表生成 case 模式（`|` 分隔）；`allowed_patterns` 逐条 grep。post-checkout 仅警告不阻断（`exit 0`，不 `exit 1`）。
+
+**固定尾部：**`exit 0`
+
+---
+
+## MANAGED 块 hash 计算
+
+```bash
+actual_hash=$(printf '%s' "<block_content>" | git hash-object --stdin | cut -c1-8)
+```
+
+`<block_content>` = BEGIN/END 标记之间的内容，去首尾空白。
+
+## 多行内容写入方式
+
+禁止用 `awk -v` 传多行 shell 脚本（含换行符时 awk 报错）。正确方式：
+
+```bash
+TMPBLOCK=$(mktemp)
+cat > "$TMPBLOCK" << 'BLOCKEOF'
+# --- BEGIN MANAGED: branches.protected/develop (hash:PLACEHOLDER) ---
+if [ "$BRANCH" = "develop" ]; then
+    ...
+fi
+# --- END MANAGED: branches.protected/develop ---
+BLOCKEOF
+
+python3 - "$HOOKFILE" "$TMPBLOCK" << 'PYEOF'
+import sys
+hook = open(sys.argv[1]).read()
+block = open(sys.argv[2]).read()
+hook = hook.replace('\nexit 0\n', '\n' + block + '\nexit 0\n', 1)
+open(sys.argv[1], 'w').write(hook)
+PYEOF
+rm "$TMPBLOCK"
+```

package/skills/harness/git-workflow-init/references/lock-file-format.md

@@ -0,0 +1,34 @@
+# Lock 文件格式
+
+路径：`.githooks/.workflow-config.lock.yml`
+
+每次运行 git-workflow-init 成功后写入，记录本次生效的配置快照，供下次运行做 diff。
+
+```yaml
+# Generated by git-workflow-init, do not edit manually
+generated_at: "<ISO 8601 timestamp>"
+skill_version: "4.0.0"
+branches_protected:
+  - name: main
+    allow_direct_commit: false
+    merge_from: [staging, "release/*"]
+  - name: staging
+    allow_direct_commit: false
+    merge_from: ["feature/*", "fix/*", "chore/*", "doc/*"]
+commit_message:
+  format: conventional
+  types: [feat, fix, chore, docs, refactor, test, style, perf]
+  max_subject_length: 80
+branch_naming:
+  allowed_patterns: ["^feature/.+", "^fix/.+", "^chore/.+", "^doc/.+", "^release/.+"]
+  exempt: [main, staging]
+tags:
+  enforce: true
+  allowed_patterns: ["^v[0-9]+\\.[0-9]+\\.[0-9]+$"]
+  require_annotated: true
+push_rules:
+  enforce: true
+  block_force_push: [main, staging]
+```
+
+只记录影响 hook 生成的字段，不需要照搬 `workflow-config.yml` 的完整结构。