✨ feat(templates): add gitea ci example

README.md

@@ -39,6 +39,7 @@ Playbook：TSL（`.tsl`/`.tsf`）+ C++ + Python 工程规范与代理规则合
 - `docs/python/configuration.md`：Python 配置清单（落地时从 `templates/python/` 复制到项目根目录）。
 - `templates/cpp/`：C++ 落地模板（`.clang-format`、`conanfile.txt`、`CMakeUserPresets.json`、`CMakeLists.txt`）。
 - `templates/python/`：Python 落地模板（`pyproject.toml` 工具配置、`.flake8`、`.pylintrc`、`.pre-commit-config.yaml`、`.editorconfig`、`.vscode/settings.json`）。
+- `templates/ci/`：目标项目 CI 示例模板（如 Gitea Actions），用于自动化校验部分规范。
 
 ## .agents/（代理规则）
 
@@ -246,7 +247,7 @@ sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp
 
 脚本会：
 
-- 生成裁剪快照到 `docs/standards/playbook/`（包含 `docs/common/` + 选定语言目录 + 对应 `.agents/<lang>/` + `scripts/` + `.gitattributes` + 相关 `templates/<lang>/`）
+- 生成裁剪快照到 `docs/standards/playbook/`（包含 `docs/common/` + 选定语言目录 + 对应 `.agents/<lang>/` + `scripts/` + `.gitattributes` + 通用 `templates/ci/` + 相关 `templates/<lang>/`）
 - 自动执行 `docs/standards/playbook/scripts/sync_standards.*`，把 `.agents/<lang>/` 与 `.gitattributes` 落地到目标项目根目录
 - 生成 `docs/standards/playbook/SOURCE.md` 记录来源与版本信息
 

scripts/vendor_playbook.bat

@@ -80,6 +80,14 @@ copy /y "%SRC%\\.agents\\index.md" "%DEST_PREFIX%\\.agents\\index.md" >nul
 
 if not exist "%DEST_PREFIX%\\templates" mkdir "%DEST_PREFIX%\\templates"
 
+if exist "%SRC%\\templates\\ci" (
+  xcopy "%SRC%\\templates\\ci\\*" "%DEST_PREFIX%\\templates\\ci\\" /e /i /y >nul
+  if errorlevel 1 (
+    echo ERROR: failed to copy templates\\ci
+    exit /b 1
+  )
+)
+
 set "LANGS_CSV="
 for %%L in (%LANGS%) do (
   echo %%~L| findstr /r "[\\/]" >nul && (

scripts/vendor_playbook.ps1

@@ -81,6 +81,11 @@ Copy-Item (Join-Path $Src ".agents/index.md") (Join-Path $AgentsDir "index.md")
 $TemplatesDir = Join-Path $DestPrefix "templates"
 New-Item -ItemType Directory -Path $TemplatesDir -Force | Out-Null
 
+$ciTplSrc = Join-Path (Join-Path $Src "templates") "ci"
+if (Test-Path $ciTplSrc) {
+  Copy-Item $ciTplSrc $TemplatesDir -Recurse -Force
+}
+
 foreach ($lang in $Langs) {
   $docsSrc = Join-Path (Join-Path $Src "docs") $lang
   if (-not (Test-Path $docsSrc)) { throw "Docs not found for lang=$lang ($docsSrc)" }

scripts/vendor_playbook.sh

@@ -81,6 +81,9 @@ mkdir -p "$DEST_PREFIX/.agents"
 cp "$SRC/.agents/index.md" "$DEST_PREFIX/.agents/index.md"
 
 mkdir -p "$DEST_PREFIX/templates"
+if [ -d "$SRC/templates/ci" ]; then
+  cp -R "$SRC/templates/ci" "$DEST_PREFIX/templates/"
+fi
 
 old_ifs="${IFS}"
 IFS=', '

templates/ci/README.md

@@ -0,0 +1,34 @@
+# CI 模板（templates/ci）
+
+本目录提供“目标项目可复制启用”的 CI 模板示例，用于在 CI 中自动化校验部分 Playbook 规范。
+
+当前提供：
+
+- `gitea/`：Gitea Actions（GitHub Actions 语法）
+
+## 使用（Gitea Actions）
+
+前提：目标项目已经 vendoring Playbook（例如 `docs/standards/playbook/`）。
+
+复制到目标项目根目录：
+
+```sh
+cp -R docs/standards/playbook/templates/ci/gitea/.gitea ./
+```
+
+提交：
+
+```sh
+git add .gitea
+git commit -m ":memo: docs(ci): add standards check workflow"
+```
+
+## commit message 校验
+
+工作流会运行 `.gitea/ci/commit_message_lint.py`：
+
+- 规范来源（自动探测其一）：
+  - `docs/common/commit_message.md`
+  - `docs/standards/playbook/docs/common/commit_message.md`
+- 默认要求 emoji；如需允许无 emoji：在 workflow 中设置 `COMMIT_LINT_REQUIRE_EMOJI=0`。
+

templates/ci/gitea/.gitea/ci/commit_message_lint.py

@@ -0,0 +1,210 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import json
+import os
+import pathlib
+import re
+import subprocess
+import sys
+from typing import Dict, List, Optional, Tuple
+
+
+def _eprint(*args: object) -> None:
+    print(*args, file=sys.stderr)
+
+
+def _git(*args: str) -> str:
+    return subprocess.check_output(["git", *args], text=True).strip()
+
+
+def _repo_root() -> pathlib.Path:
+    return pathlib.Path(_git("rev-parse", "--show-toplevel"))
+
+
+def _find_commit_spec(root: pathlib.Path) -> pathlib.Path:
+    candidates = [
+        root / "docs" / "common" / "commit_message.md",
+        root / "docs" / "standards" / "playbook" / "docs" / "common" / "commit_message.md",
+    ]
+    for path in candidates:
+        if path.is_file():
+            return path
+    raise FileNotFoundError(
+        "commit_message.md not found; expected one of:\n"
+        + "\n".join(f"- {p}" for p in candidates)
+    )
+
+
+def _parse_type_emoji_mapping(md_text: str) -> Dict[str, str]:
+    mapping: Dict[str, str] = {}
+    for raw_line in md_text.splitlines():
+        line = raw_line.strip()
+        if not (line.startswith("|") and line.endswith("|")):
+            continue
+        if "type" in line and "emoji" in line:
+            continue
+        if re.fullmatch(r"\|\s*-+\s*(\|\s*-+\s*)+\|", line):
+            continue
+
+        cols = [c.strip() for c in line.strip("|").split("|")]
+        if len(cols) < 2:
+            continue
+
+        m_type = re.search(r"`([^`]+)`", cols[0])
+        m_emoji = re.search(r"`(:[^`]+:)`", cols[1])
+        if not m_type or not m_emoji:
+            continue
+
+        type_name = m_type.group(1).strip()
+        emoji_code = m_emoji.group(1).strip()
+        mapping[type_name] = emoji_code
+
+    if not mapping:
+        raise ValueError("failed to parse type/emoji mapping from commit_message.md")
+    return mapping
+
+
+def _validate_subject_line(
+    line: str,
+    mapping: Dict[str, str],
+    *,
+    require_emoji: bool,
+) -> Optional[str]:
+    subject = line.strip()
+    if not subject:
+        return "empty subject"
+
+    m = re.match(
+        r"^(?:(?P<emoji>:[a-z0-9_+-]+:)\s+)?"
+        r"(?P<type>[a-z]+)"
+        r"(?P<scope>\([a-z0-9_]+\))?"
+        r":\s+(?P<text>.+)$",
+        subject,
+    )
+    if not m:
+        return "does not match ':emoji: type(scope): subject' or 'type(scope): subject'"
+
+    emoji = m.group("emoji")
+    type_name = m.group("type")
+    text = (m.group("text") or "").rstrip()
+
+    if type_name not in mapping:
+        return f"unknown type: {type_name}"
+
+    if emoji:
+        expected = mapping[type_name]
+        if emoji != expected:
+            return f"emoji/type mismatch: got {emoji} {type_name}, expected {expected} for type {type_name}"
+    elif require_emoji:
+        return "missing emoji (set COMMIT_LINT_REQUIRE_EMOJI=0 to allow)"
+
+    if text.endswith((".", "。")):
+        return "subject should not end with a period"
+
+    return None
+
+
+def _load_event_payload() -> Tuple[str, Optional[dict]]:
+    event_name = os.getenv("GITHUB_EVENT_NAME") or os.getenv("GITEA_EVENT_NAME") or ""
+    event_path = os.getenv("GITHUB_EVENT_PATH") or os.getenv("GITEA_EVENT_PATH") or ""
+    if not event_path:
+        return event_name, None
+
+    path = pathlib.Path(event_path)
+    if not path.is_file():
+        return event_name, None
+
+    try:
+        return event_name, json.loads(path.read_text(encoding="utf-8"))
+    except Exception as exc:
+        _eprint(f"WARN: failed to parse event payload: {path} ({exc})")
+        return event_name, None
+
+
+def _gather_subjects(event_name: str, payload: Optional[dict]) -> List[Tuple[str, str]]:
+    subjects: List[Tuple[str, str]] = []
+
+    if isinstance(payload, dict):
+        if event_name.startswith("pull_request"):
+            pr = payload.get("pull_request")
+            if isinstance(pr, dict):
+                title = (pr.get("title") or "").strip()
+                if title:
+                    subjects.append(("pull_request.title", title.splitlines()[0].strip()))
+
+        if event_name == "push":
+            commits = payload.get("commits")
+            if isinstance(commits, list):
+                for commit in commits:
+                    if not isinstance(commit, dict):
+                        continue
+                    msg = (commit.get("message") or "").strip()
+                    if not msg:
+                        continue
+                    subject = msg.splitlines()[0].strip()
+                    sha = commit.get("id") or commit.get("sha") or ""
+                    label = f"push.commit {sha[:7]}" if sha else "push.commit"
+                    subjects.append((label, subject))
+
+    if subjects:
+        return subjects
+
+    try:
+        subjects.append(("HEAD", _git("log", "-1", "--format=%s", "HEAD")))
+    except Exception:
+        pass
+    return subjects
+
+
+def main() -> int:
+    try:
+        root = _repo_root()
+    except Exception as exc:
+        _eprint(f"ERROR: not a git repository: {exc}")
+        return 2
+
+    os.chdir(root)
+
+    require_emoji = os.getenv("COMMIT_LINT_REQUIRE_EMOJI", "1") not in ("0", "false", "False")
+
+    try:
+        spec_path = _find_commit_spec(root)
+    except FileNotFoundError as exc:
+        _eprint(f"ERROR: {exc}")
+        return 2
+
+    try:
+        mapping = _parse_type_emoji_mapping(spec_path.read_text(encoding="utf-8"))
+    except Exception as exc:
+        _eprint(f"ERROR: failed to read/parse {spec_path}: {exc}")
+        return 2
+
+    event_name, payload = _load_event_payload()
+    subjects = _gather_subjects(event_name, payload)
+
+    print(f"commit spec: {spec_path}")
+    if event_name:
+        print(f"event: {event_name}")
+    print(f"require emoji: {require_emoji}")
+    print(f"checks: {len(subjects)} subject(s)")
+
+    errors: List[str] = []
+    for label, subject in subjects:
+        err = _validate_subject_line(subject, mapping, require_emoji=require_emoji)
+        if err:
+            errors.append(f"- {label}: {err}\n  subject: {subject}")
+
+    if errors:
+        _eprint("ERROR: commit message lint failed:")
+        for item in errors:
+            _eprint(item)
+        return 1
+
+    print("OK")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+

templates/ci/gitea/.gitea/workflows/standards-check.yml

@@ -0,0 +1,19 @@
+name: Standards Check
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  commit-message:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Lint commit message / PR title
+        env:
+          COMMIT_LINT_REQUIRE_EMOJI: "1"
+        run: |
+          python3 .gitea/ci/commit_message_lint.py
+