游戏叙事与剧情 / 系统课时
让脚本检查进入提交流程
让脚本检查进入提交流程
多人维护 Ink 脚本时,最浪费时间的不是复杂运行时故障,而是语法错误、临时文本和关键节点缺失进入评审后才被发现。本节把这些低成本检查收敛成一条可重复执行的门禁:本地提交前尽早失败,远端流水线再执行同一套规则。
学习目标
- 把 Ink 编译、内容规则和关键节点检查串成一个可重复执行的命令
- 用 Git 提交钩子在提交前阻止明显有问题的剧情脚本
- 明确本地钩子与远端 CI 的职责边界,避免检查只在某台机器生效
把检查变成一条门禁链
提交阶段适合拦截“确定有问题且检查成本低”的错误。推荐顺序是先编译,再做团队内容规则检查,最后验证约定的关键剧情入口是否仍然存在;任一环节失败就停止提交。

这里的“关键路径检查”不是完整剧情自动游玩,而是提交阶段的轻量契约:例如主入口、存档恢复点、主要结局 knot 不应被误删或改名。真正需要选择序列、变量状态和结局内容断言时,应放到独立的运行时测试中。
建立统一检查脚本
下面假设主入口是 story/main.ink,团队要求保留 intro、checkpoint、ending_good 三个 knot,并禁止把 TODO_REVIEW、FIXME_STORY、TEMP_TEXT 这类临时标记提交进仓库。把规则集中到 tools/check_ink.py,团队成员和 CI 都执行同一个文件。
from pathlib import Path
import re
import subprocess
import sys
ROOT = Path(__file__).resolve().parents[1]
STORY_DIR = ROOT / "story"
ENTRY = STORY_DIR / "main.ink"
OUTPUT = ROOT / "build" / "story.json"
OUTPUT.parent.mkdir(parents=True, exist_ok=True)
try:
result = subprocess.run(
["inklecate", "-o", str(OUTPUT), str(ENTRY)],
cwd=ROOT,
text=True,
capture_output=True,
check=False,
)
except FileNotFoundError:
print("inklecate not found")
sys.exit(1)
if result.returncode != 0:
print(result.stdout, end="")
print(result.stderr, end="", file=sys.stderr)
sys.exit(result.returncode)
print("[1/3] compile: OK")
ink_files = list(STORY_DIR.rglob("*.ink"))
blocked = re.compile(r"\b(?:TODO_REVIEW|FIXME_STORY|TEMP_TEXT)\b")
bad_files = []
for path in ink_files:
if blocked.search(path.read_text(encoding="utf-8")):
bad_files.append(path.relative_to(ROOT))
if bad_files:
print("blocked markers found in:")
for path in bad_files:
print(f" {path}")
sys.exit(1)
print("[2/3] content: OK")
knot_pattern = re.compile(
r"^\s*===\s*([A-Za-z_][A-Za-z0-9_]*)\s*===\s*$",
re.MULTILINE,
)
declared = set()
for path in ink_files:
declared.update(
knot_pattern.findall(path.read_text(encoding="utf-8"))
)
required = {"intro", "checkpoint", "ending_good"}
missing = sorted(required - declared)
if missing:
print("missing required knots:")
for knot in missing:
print(f" {knot}")
sys.exit(1)
print("[3/3] key knots: OK")
print("INK_CHECK_OK")预期输出
[1/3] compile: OK
[2/3] content: OK
[3/3] key knots: OK
INK_CHECK_OK三个关键 knot 和禁止标记都属于项目约定,应由团队按实际剧情调整。脚本先调用编译器,因此普通语法错误、无效引用等编译问题会比内容规则更早失败,不会被后续检查掩盖。
接入 Git 提交前检查
不要把脚本逻辑直接写死在某个成员的 .git/hooks 目录。下面把钩子保存到仓库的 .githooks/pre-commit,再让当前克隆使用这个版本化目录;钩子本身只调用统一检查脚本。
mkdir -p .githooks
cat > .githooks/pre-commit <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
python3 tools/check_ink.py
EOF
chmod +x .githooks/pre-commit
git config core.hooksPath .githooks
git config --get core.hooksPath预期输出
.githooks之后执行 git commit 时,只要检查脚本返回非零状态,提交就会被阻止。core.hooksPath 是每个克隆仓库的本地配置,因此新成员仍需要完成一次初始化;可以把这一步放进项目的开发环境初始化脚本。
让远端流水线复用同一条命令
本地 hook 只能提高反馈速度,不能作为唯一门禁,因为成员可以未配置 hook,也可以主动跳过。远端 CI 应再次执行同一个检查入口,而不是复制另一份规则。
python3 tools/check_ink.py预期输出
[1/3] compile: OK
[2/3] content: OK
[3/3] key knots: OK
INK_CHECK_OK这样规则只维护一份:本地提交前负责“尽快告诉作者哪里错了”,远端流水线负责“保证进入主分支的内容一定跑过检查”。当团队以后增加禁用标签、命名规范或真正的剧情路径测试时,也应继续从这个统一入口扩展。