27万星囤件，编目格式闸交货——第8轮设计模式提炼：给编目立一份格式合同

flowchart TD
    A["第一拍 09-27<br/>文字件 九条套路"] --> B["第二拍 09-29<br/>流程件 六套路"]
    B --> C["第三拍 09-30早<br/>带脚件 六接缝套路"]
    C --> D["第四拍 09-30晚<br/>验件 七道闸"]
    D --> E["第五拍 本期<br/>数据格式件 五套路"]

name: catalog-schema
description: Validate a skill catalog file against the four-column v1
  schema. Use when the user asks to check, validate, lint, or audit a
  catalog file, or reports that skill-dispatcher misreads catalog rows.
  Format-only by contract - it judges whether rows match the schema,
  never whether the catalog content is any good. Read-only by contract -
  it issues row reports and never edits files. To draft or refresh a
  catalog use catalog-drafter instead. To validate a SKILL.md file use
  skill-lint instead. Not a replacement for skill-dispatcher.
# Catalog Schema — 编目格式闸

编目的合同科：验一行四列是不是 v1 的样子。
只出验收单，不动一个字，不判内容好坏。

## v1 格式合同
- 版本头（可选，向后兼容）：`# catalog-schema: v1`，逐字一致
- 数据行：`域别名 | 件名 | 一句话触发词 | 召唤口令`，竖线分隔恰四列
- 正例（规范样本，照这行长）：
  `telecom | pcap-analyzer | 分析抓包文件 | 用 pcap-analyzer 分析这个包`
- 反例（会挂）：`telecom | pcap-analyzer | 分析抓包文件`——三列，缺召唤口令
- `#` 开头是注释行，空行忽略；一域超过八件转 remind 建议收编目
- 本合同认领的是编目工具链既有的竖线四列写法，不改一列

## 工作流程
1. 跑 scripts/validate_catalog.py <编目文件> --registry ~/.claude/skills
2. 退出码 2：文件读不了，如实报告并停
3. fail 行逐条抄单：行号、条款名、改法，一条不许漏
4. remind 项原样转呈（缺版本头、一域超八、幽灵件名），留用户裁决
5. 呈完整验收单，写盘数为零

## 不要做
- 不要替用户改一个字——闸只出单，不动刀
- 不要判内容——域起得好不好、口令顺不顺口，神归读者，形归本闸
- 不要为缺版本头挂科——从宽条款，remind 不 fail
- 不要展开读取编目里各件的正文——格式闸只认行，不认件

## 完成定义
- 每一数据行恰有一个结论（过、挂、remind 三选一）
- 每个 fail 行附行号、条款名与改法
- 本次写盘数为零

#!/usr/bin/env python3
"""validate_catalog.py - 只读验收编目文件是否合 v1 格式（TSV 体检单）。
契约：永不写盘；同一输入两次运行输出逐字节一致。
只判形不判神：列数、空列、件名正则、一域上限、版本头、幽灵件名。
行格式：行号 | pass/fail/remind | 条款名 | 明细与改法（行号 0 为全卷级）
退出码：0 无挂项，1 有挂项，2 文件读不了。
"""
import argparse, os, re, sys

NAME_RE = re.compile(r"^[a-z0-9][a-z0-9-]*$")
VERSION_LINE = "# catalog-schema: v1"
MAX_PER_DOMAIN = 8      # 09-30 早班卷口径
COLUMNS = 4

def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("catalog")
    ap.add_argument("--registry", help="注册表根目录，供幽灵件名核对")
    args = ap.parse_args()
    try:
        with open(args.catalog, encoding="utf-8") as f:
            lines = f.read().splitlines()
    except OSError as e:
        print(f"读不了 {args.catalog}: {e}", file=sys.stderr)
        sys.exit(2)

    rows, names, domains = [], {}, {}
    version_seen = False
    for no, raw in enumerate(lines, 1):
        line = raw.strip()
        if not line:
            continue
        if line.startswith("#"):
            if line == VERSION_LINE:
                version_seen = True
            elif line.startswith("# catalog-schema"):
                rows.append((no, "fail", "版本头条款",
                             f"版本头拼错；改法：逐字改为「{VERSION_LINE}」"))
            continue
        cells = [c.strip() for c in line.split("|")]
        if len(cells) != COLUMNS:
            rows.append((no, "fail", "列数条款",
                         f"{len(cells)} 列，v1 要求 {COLUMNS} 列；改法："
                         f"按「域 | 件名 | 触发词 | 口令」用竖线补齐"))
            continue
        dom, name, trig, call = cells
        for label, val in (("域别名", dom), ("件名", name),
                           ("触发词", trig), ("召唤口令", call)):
            if not val:
                rows.append((no, "fail", "空列条款",
                             f"{label} 为空；改法：补上，无内容删行不留壳"))
        if name:
            if not NAME_RE.match(name):
                rows.append((no, "fail", "件名条款",
                             f"「{name}」不合小写连字符正则；改法："
                             f"全小写，只留数字与连字符"))
            if name in names:
                rows.append((no, "fail", "同卷撞名条款",
                             f"与第 {names[name]} 行撞名「{name}」；"
                             f"改法：一行一件，重复行删除"))
            else:
                names[name] = no
            domains[dom] = domains.get(dom, 0) + 1

    if not version_seen:
        rows.insert(0, (0, "remind", "版本头条款",
                       "未见版本头；从宽不挂，建议补在文件首行，"
                       "v2 迁移那天全靠它"))
    for dom, n in sorted(domains.items()):
        if n > MAX_PER_DOMAIN:
            rows.append((0, "remind", "一域八件条款",
                         f"域「{dom}」{n} 件超上限；改法：拆域或收编目"))
    if args.registry and os.path.isdir(args.registry):
        installed = set(os.listdir(args.registry))
        for name in sorted(names):
            if name not in installed:
                rows.append((0, "remind", "幽灵件名条款",
                             f"「{name}」不在注册表；改法：确认是待装件"
                             f"还是手滑行，待装件请加注释行说明"))

    for no, verdict, clause, detail in rows:
        print(f"{no}\t{verdict}\t{clause}\t{detail}")
    hard = sum(1 for r in rows if r[1] == "fail")
    soft = sum(1 for r in rows if r[1] == "remind")
    print(f"# fail {hard} remind {soft}", file=sys.stderr)
    sys.exit(1 if hard else 0)

if __name__ == "__main__":
    main()

flowchart TD
    A["用户请求验编目"] --> B["点亮 catalog-schema"]
    B --> C["跑 validate_catalog.py"]
    C --> D{"退出码"}
    D -->|退出码2 文件读不了| E["如实报告并停"]
    D -->|退出码1 有挂行| F["逐行抄单<br/>行号条款改法"]
    D -->|退出码0| G["remind 项转呈"]
    F --> H{"remind 项在场"}
    H -->|有| I["原样列出<br/>用户裁决"]
    H -->|无| J["呈完整验收单"]
    I --> J
    G --> J
    J --> K["写盘数为零"]

# 两件套：正文、脚本
mkdir -p ~/.claude/skills/catalog-schema/scripts
# 将上文 SKILL.md 存为 ~/.claude/skills/catalog-schema/SKILL.md
# 将上文脚本   存为 ~/.claude/skills/catalog-schema/scripts/validate_catalog.py

# 出厂自测第一式：最小正例喂它，退出码应为 0
printf 'telecom | pcap-analyzer | 分析抓包文件 | 用 pcap-analyzer 分析这个包\n' > /tmp/catalog-fixture.md
python3 ~/.claude/skills/catalog-schema/scripts/validate_catalog.py /tmp/catalog-fixture.md
# 预期：一条 remind（缺版本头，行号 0），stderr 报 fail 0 remind 1

# 自测第二式：故意喂一行三列的坏行，确认「行号、条款、改法」三件套齐全
printf 'telecom | pcap-analyzer | 分析抓包文件\n' >> /tmp/catalog-fixture.md
python3 ~/.claude/skills/catalog-schema/scripts/validate_catalog.py /tmp/catalog-fixture.md --registry ~/.claude/skills
# 预期：退出码 1，第 2 行挂「列数条款」并给出补列改法

# 点火三句（应被唤起）：「帮我验一下这份编目」「dispatcher 好像读不了我的编目」
#   「这份编目格式对不对」
# 灭火三句（不应唤起）：「帮我给编目起个草」归 catalog-drafter；
#   「帮我验一件 SKILL.md」归 skill-lint；「把编目里这三件删掉」是动资产，不归闸

# 市场撞名复查（本通道今日未开，命令备上架日用）
npx skills find catalog-schema