harveyz-skill 0.2.1 → 0.3.0

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` 的完整结构。

package/skills/harness/git-workflow-init/references/render_docs.py

@@ -0,0 +1,261 @@
+#!/usr/bin/env python3
+"""
+git-workflow-init Step 7 渲染器
+从 workflow-config.yml 动态生成 docs/reference/git-workflow.md
+"""
+import sys, re, os
+
+def load_config(path):
+    """简单 YAML 解析（只处理此 skill 使用的字段，无需完整 YAML 库）"""
+    content = open(path).read()
+
+    def extract_list_under(key, text):
+        """提取某个 key 下的列表项（- value 或 - "value"）"""
+        pattern = rf'{re.escape(key)}:\s*\n((?:[ \t]+- .+\n?)+)'
+        m = re.search(pattern, text)
+        if not m:
+            # 尝试行内列表 [a, b, c]
+            m2 = re.search(rf'{re.escape(key)}:\s*\[([^\]]+)\]', text)
+            if m2:
+                return [v.strip().strip('"') for v in m2.group(1).split(',')]
+            return []
+        return [re.sub(r'^[ \t]+- ', '', l).strip().strip('"')
+                for l in m.group(1).splitlines() if l.strip().startswith('- ')]
+
+    # 提取 branches.protected
+    protected = []
+    in_protected = False
+    current = None
+    for line in content.splitlines():
+        if re.match(r'\s+protected:', line):
+            in_protected = True
+            continue
+        if in_protected:
+            m = re.match(r'\s{4}- name:\s+(\S+)', line)
+            if m:
+                if current:
+                    protected.append(current)
+                current = {'name': m.group(1), 'allow_direct_commit': False, 'merge_from': []}
+            elif current and re.match(r'\s+allow_direct_commit:\s*(true|false)', line):
+                current['allow_direct_commit'] = 'true' in line
+            elif current and re.match(r'\s+merge_from:', line):
+                pass  # next lines are the list
+            elif current and re.match(r'\s{8}- ', line):
+                val = line.strip().lstrip('- ').strip('"')
+                current['merge_from'].append(val)
+            elif line.strip() and not line.startswith(' '):
+                in_protected = False
+    if current:
+        protected.append(current)
+
+    # branch_naming
+    naming_patterns = extract_list_under('allowed_patterns', content)
+    naming_exempt   = extract_list_under('exempt', content)
+
+    # commit_message
+    fmt_m = re.search(r'format:\s*(\S+)', content)
+    fmt = fmt_m.group(1) if fmt_m else 'none'
+    types = extract_list_under('types', content)
+    pattern_m = re.search(r'pattern:\s*"([^"]+)"', content)
+    regex_pattern = pattern_m.group(1) if pattern_m else ''
+    max_len_m = re.search(r'max_subject_length:\s*(\d+)', content)
+    max_len = int(max_len_m.group(1)) if max_len_m else 72
+
+    return {
+        'protected': protected,
+        'naming_patterns': naming_patterns,
+        'naming_exempt': naming_exempt,
+        'commit_format': fmt,
+        'commit_types': types,
+        'commit_regex': regex_pattern,
+        'max_subject_length': max_len,
+    }
+
+
+def branch_purpose(name):
+    mapping = {
+        'main': '生产就绪代码', 'master': '生产就绪代码',
+        'staging': '集成 / 预发布', 'develop': '开发集成',
+    }
+    if name in mapping:
+        return mapping[name]
+    if name.startswith('release'):
+        return '发版准备'
+    return '—'
+
+
+def pattern_to_prefix(p):
+    """^feature/.+ → feature/"""
+    m = re.match(r'^\^?([a-z]+)/', p)
+    return m.group(1) + '/' if m else p
+
+
+def pattern_purpose(prefix):
+    mapping = {
+        'feature/': ('新功能', 'feature/user-auth、feature/dark-mode'),
+        'fix/':     ('Bug 修复', 'fix/login-crash、fix/null-pointer'),
+        'chore/':   ('维护、依赖升级等', 'chore/upgrade-deps、chore/ci-timeout'),
+        'doc/':     ('文档更新', 'doc/api-reference、doc/onboarding'),
+        'docs/':    ('文档更新', 'docs/api-reference、docs/onboarding'),
+        'release/': ('发版切点', 'release/1.2.0'),
+        'hotfix/':  ('紧急热修复', 'hotfix/login-crash'),
+    }
+    return mapping.get(prefix, ('—', f'{prefix}example'))
+
+
+def render(config, template):
+    c = config
+    protected = c['protected']
+
+    # ── BRANCH_TOPOLOGY_ASCII ──────────────────────────────────────
+    # 找主分支（没有其他受保护分支 merge_from 到它的最顶层）
+    all_names = {b['name'] for b in protected}
+    merge_targets = set()
+    for b in protected:
+        for mf in b['merge_from']:
+            # mf 可能是 glob，提取固定前缀
+            base = mf.rstrip('/*')
+            if base in all_names:
+                merge_targets.add(base)
+
+    # 拓扑：逐级展开
+    def build_tree(root, depth=0):
+        b = next((x for x in protected if x['name'] == root), None)
+        if not b:
+            return ''
+        indent = '  ' * depth
+        lines = [indent + root]
+        for src in b['merge_from']:
+            src_base = src.rstrip('/*')
+            if src_base in all_names:
+                lines.append(build_tree(src_base, depth + 1))
+            else:
+                lines.append('  ' * (depth + 1) + f'<- {src}')
+        return '\n'.join(l for l in lines if l)
+
+    roots = [b['name'] for b in protected if b['name'] not in merge_targets]
+    ascii_lines = []
+    for r in roots:
+        for src in next(x for x in protected if x['name'] == r)['merge_from']:
+            src_base = src.rstrip('/*')
+            if src_base in all_names:
+                sub = next((x for x in protected if x['name'] == src_base), None)
+                ascii_lines.append(f'{r}')
+                ascii_lines.append(f'  <- {src_base}')
+                for subsrc in (sub['merge_from'] if sub else []):
+                    ascii_lines.append(f'        <- {subsrc}')
+            else:
+                ascii_lines.append(f'{r}')
+                ascii_lines.append(f'  <- {src}')
+    topology_ascii = '\n'.join(ascii_lines) if ascii_lines else ' <- '.join(b['name'] for b in protected)
+
+    # ── BRANCH_TABLE ───────────────────────────────────────────────
+    rows = ['| 分支 | 用途 | 合并目标 |', '|------|------|---------|']
+    for b in protected:
+        target = roots[0] if b['name'] != roots[0] else '—'
+        rows.append(f'| `{b["name"]}` | {branch_purpose(b["name"])} | `{target}` |')
+    for p in c['naming_patterns']:
+        prefix = pattern_to_prefix(p)
+        purpose, _ = pattern_purpose(prefix)
+        target_branch = next((b['name'] for b in protected if b['name'] not in roots), roots[0] if roots else '—')
+        rows.append(f'| `{prefix}<名称>` | {purpose} | `{target_branch}` |')
+    branch_table = '\n'.join(rows)
+
+    # ── PROTECTION_RULES ──────────────────────────────────────────
+    rule_lines = []
+    for b in protected:
+        sources = '、'.join(f'`{s}`' for s in b['merge_from'])
+        if b['allow_direct_commit']:
+            rule_lines.append(f'- **`{b["name"]}`** — 直接提交时发出警告（不阻断）。合并来源建议为 {sources}。')
+        else:
+            rule_lines.append(f'- **`{b["name"]}`** — 禁止直接提交。只接受来自 {sources} 的合并。')
+    protection_rules = '\n'.join(rule_lines)
+
+    # ── WORKFLOW EXAMPLES ─────────────────────────────────────────
+    integration = next((b['name'] for b in protected if b['name'] not in roots), roots[0] if roots else 'staging')
+    main_branch = roots[0] if roots else 'main'
+    checkout_ex = f'git checkout {integration}'
+    merge_ex     = f'git checkout {integration}\ngit merge feature/my-feature'
+    release_ex   = f'git checkout {main_branch}\ngit merge {integration}       # 或：git merge release/x.y.z\ngit push'
+
+    # ── NAMING_TABLE ──────────────────────────────────────────────
+    naming_rows = ['| 前缀 | 适用场景 | 示例 |', '|------|---------|------|']
+    for p in c['naming_patterns']:
+        prefix = pattern_to_prefix(p)
+        purpose, example = pattern_purpose(prefix)
+        naming_rows.append(f'| `{prefix}` | {purpose} | `{example}` |')
+    naming_table = '\n'.join(naming_rows)
+
+    # ── NAMING_EXEMPT ─────────────────────────────────────────────
+    naming_exempt = '、'.join(f'`{e}`' for e in c['naming_exempt']) or '无'
+
+    # ── COMMIT_FORMAT_SECTION ─────────────────────────────────────
+    if c['commit_format'] == 'conventional':
+        types_line = ' | '.join(f'`{t}`' for t in c['commit_types'])
+        commit_section = f"""遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范：
+
+```
+<类型>(<范围>): <简短描述>
+
+[可选正文]
+
+[可选 footer]
+```
+
+**类型：** {types_line}
+
+**首行长度限制：** {c['max_subject_length']} 个字符"""
+    elif c['commit_format'] == 'regex':
+        commit_section = f"""提交信息首行必须匹配正则：
+
+```
+{c['commit_regex']}
+```
+
+**首行长度限制：** {c['max_subject_length']} 个字符"""
+    else:
+        commit_section = '本项目无提交信息格式要求。'
+
+    # ── FAQ_SECTION ───────────────────────────────────────────────
+    faq = []
+    if integration != main_branch:
+        faq.append(f'**Q：在 {integration} 上提交被拒绝怎么办？**\n'
+                   f'A：你正在直接向 {integration} 提交。请新建分支，在新分支提交后再合并回 {integration}。')
+    release_p = [p for p in c['naming_patterns'] if 'release' in p]
+    if release_p:
+        faq.append(f'**Q：需要紧急热修复直接上 {main_branch} 怎么办？**\n'
+                   f'A：从 {main_branch} 切一个 `release/*` 分支，修复后合并到 {main_branch}，再反向合并到 {integration}。')
+    faq_section = '\n\n'.join(faq)
+
+    # ── 替换占位符 ─────────────────────────────────────────────────
+    result = template
+    result = result.replace('{{BRANCH_TOPOLOGY_ASCII}}',    topology_ascii)
+    result = result.replace('{{BRANCH_TABLE}}',             branch_table)
+    result = result.replace('{{PROTECTION_RULES}}',         protection_rules)
+    result = result.replace('{{WORKFLOW_CHECKOUT_EXAMPLE}}', checkout_ex)
+    result = result.replace('{{WORKFLOW_MERGE_EXAMPLE}}',   merge_ex)
+    result = result.replace('{{WORKFLOW_RELEASE_EXAMPLE}}', release_ex)
+    result = result.replace('{{NAMING_TABLE}}',             naming_table)
+    result = result.replace('{{NAMING_EXEMPT}}',            naming_exempt)
+    result = result.replace('{{COMMIT_FORMAT_SECTION}}',    commit_section)
+    result = result.replace('{{FAQ_SECTION}}',              faq_section + '\n\n' if faq_section else '')
+    return result
+
+
+if __name__ == '__main__':
+    config_path   = sys.argv[1]
+    template_path = sys.argv[2]
+    output_path   = sys.argv[3]
+
+    config   = load_config(config_path)
+    template = open(template_path).read()
+    rendered = render(config, template)
+
+    # 差量写入
+    existing = open(output_path).read() if os.path.exists(output_path) else None
+    if existing == rendered:
+        print('UNCHANGED')
+    else:
+        os.makedirs(os.path.dirname(output_path), exist_ok=True)
+        open(output_path, 'w').write(rendered)
+        print('UPDATED' if existing else 'NEW')