infocard-metadata-provenance

name	infocard-metadata-provenance
description	信息卡元数据规范管理员。负责 meta.yaml 字段标准、来源追溯、描述语言一致性，防止 desc 字段出现英文、字段名错误、date 缺失等元数据腐化问题。
version	1.0.0
author	Hermes Agent
license	MIT
metadata	{"hermes":{"tags":["infocard","metadata","provenance","quality","desc","anti-pattern"],"related_skills":["infocard-style-man-skill","infocard-pub-publisher","any2card"]}}

infocard-metadata-provenance · 信息卡元数据规范

Overview

infocard-metadata-provenance 是信息卡元数据规范管理员，负责：

1. meta.yaml 字段标准（字段名、类型、语言）
2. 来源追溯（source URL、author）
3. 描述语言一致性（desc 必须为中文）
4. 防止腐化（desc 字段名错误、英文、date 缺失）

Provenance ownership and release-time semantics

The matching docs/**/*.meta.yaml sidecar is authoritative input; _index.yaml and homepage payloads are derived index artifacts. Generation/publish workflows own slug, path, category, title, date, updated, tags, and desc. Index rebuild scripts validate/read sidecars and must not be treated as a repair layer.

For this repository, date and updated are card release/issuance timestamps in Asia/Shanghai with seconds unless the user explicitly requests archival source-time preservation. Keep upstream publication time separately as source evidence. If a timestamp is wrong, inspect the sidecar and the publish timestamp gate before debugging the index. See references/source-time-and-release-time.md and references/date-source-provenance.md.

字段标准

必填字段

⚠️ date 必须带时分秒（2026-07-04）： 用 TZ=Asia/Shanghai date "+%Y-%m-%d %H:%M:%S" 取实际值。裸日期 YYYY-MM-DD 会被 rebuild_index.py 解释为上海 00:00 → UTC 08:00 → fmt_date UTC→SH 显示 12:00:00。批量修复脚本见 infocard-pub-publisher/scripts/fix-bare-dates.py。

字段	类型	说明
slug	string	URL slug，通常为 YYYYMMDD-title-slug
path	string	HTML 文件相对路径，如 docs/20260612-foo.html
category	string	分类，如 open-source、person、ai-agent ← 必填，缺失则 build 硬失败
title	string	卡片标题
date	string	发布日期，格式 YYYY-MM-DD HH:MM:SS（精确到秒）
updated	string	更新时间，格式同 date ← 必填，且必须与 date 等值
tags	list	标签列表 ← 必填，缺失则 build 硬失败
desc	string	中文描述摘要（必填，见下方语言规则）
style	string	主题名，如 darkblue、redswiss、hardblue ← 建议填写

release_audit（发布审计字段）

发布审计在公网验收完成后写入已有卡片的 .meta.yaml，在顶层与 note 同级。仅追加不覆盖，已有 release_audit 时只更新 published_commit 和追加 added_sections。

release_audit:
  schema: 1              # 固定值，协议版本
  published_commit: "bb14473"   # 内容 commit SHA（不是 audit commit）
  pages_url: "https://ccwq.github.io/infocard-pub/docs/20260723-unknowns-ai-guideline.html"
  verified_at: "2026-07-23T17:00:00"  # ISO 8601
  visual_status: "VISUAL_PENDING"      # PASS | VISUAL_PENDING
  added_sections: "07快捷键速查表,08场景化配置方式"  # 逗号分隔；新建卡留空
  content_delta: "+201 lines (shortcuts/config/keymap/plugins)"  # 简短变更说明

注意：published_commit 是内容 commit SHA（第一次 push 的 commit），不是 audit commit SHA。visual_status: VISUAL_PENDING 是截图工具异常时记录，不等于"视觉失败"。

taxonomy v2.0（条件必填）

当用户约束中明确指定 taxonomy 字段时（如 taxonomy v2.0: tech_stack / topics / primary_content_type 必填），所有命名字段均为阻塞性必填：

taxonomy:
  tech_stack:
    - Python
    - Claude Code
  topics:
    - academic research
    - llm pipeline
  primary_content_type: open-source toolkit

教训（2026-07-13）： Academic Research Skills 卡首次写 meta.yaml 时完全遗漏 taxonomy 字段，build 通过但卡片语义不完整。下次遇到用户明确要求 taxonomy 结构时，必须在第一版 meta.yaml 中写入全部命名字段，不得后补。

选填字段

| 字段 | 类型 | 说明 | |---|---| | source | string | 来源 URL | | author | string | 作者/来源平台 | | highlights | list | 亮点列表（用户约束明确要求时填写） | | taxonomy | object | 见上方条件必填规则 |

字段名规则（强制）

desc vs description

必须用 desc，禁止用 description 或其他名称。

# ✅ 正确
desc: 这是一段中文描述摘要

# ❌ 错误
description: This is English description
description: 这是一段描述摘要

症状：若 meta.yaml 写 description，build 后 _index.yaml 存 description；但首页渲染 JS 读取 desc，两边字段名不一致 → 首页列表中该卡描述为空。

防止：meta.yaml 一律写 desc，build 脚本有 normalize 兜底（description → desc），但源文件仍应统一。

语言规则（强制）

desc 必须为中文

所有 meta.yaml 的 desc 字段必须使用简体中文，不得使用纯英文或混合语言。

# ✅ 正确：中文描述摘要
desc: 把 Claude Code、Codex CLI、OpenCode 装进图形界面——文件树、Git 面板、用量统计全透明

# ❌ 错误：纯英文
desc: A curated awesome list of public autoresearch use cases

# ❌ 错误：前半中后半英
desc: Awesome Autoresearch 公开使用案例精选列表 — A curated awesome list of public autoresearch use cases

允许的情况：

• 产品名称、工具名、GitHub slug 等专有名词保留英文：Claude Code、Codex、draw.io
• 代码片段保留原文：npm install --save-dev

检测方法（发布前必做）：

python3 - <<'PY'
import yaml, pathlib, re

docs = pathlib.Path('docs')
for m in docs.glob('*.meta.yaml'):
    data = yaml.safe_load(m.read_text())
    desc = data.get('desc','') or data.get('description','') or ''
    if not desc: continue
    # Check: desc must start with Chinese char
    chinese_start = bool(re.search(r'^[\u4e00-\u9fff]', desc))
    if not chinese_start:
        print(f'NON-CHINESE START: {m.name}: {desc[:60]}')
PY

历史教训（2026-06-12）：5 张卡的 desc 全为英文（awesome-autoresearch、drawio-skill、openskynet、plannotator、trinity），已在 commit 1590b3d 中统一翻译为中文。

日期规则

date 必须精确到秒

# ✅ 正确
date: 2026-06-12 20:20:00
updated: 2026-06-12 20:20:00

# ❌ 错误：只到日期
date: 2026-06-12

症状：若只写日期，首页显示粒度不足，排序精度下降。

规范：所有卡必须使用 YYYY-MM-DD HH:MM:SS 格式（24 小时制，东八区时间）。

来源追溯规则

source 和 author

来源明确的卡应同时填写：

source: https://github.com/user/repo
author: github-username

若来源是 Wikipedia / 公开文档：

source: https://zh.wikipedia.org/wiki/...
author: Wikipedia

无外部来源时可不填 source。

Anti-patterns

1. 字段名错误：description 而非 desc → 首页描述为空
2. 英文 desc：纯英文或前半中后半英 → 发布到中文平台不专业
3. date 粒度不足：只写 YYYY-MM-DD → 排序精度不足
4. date 缺失：无 date 字段 → build 脚本报错或回退到 mtime
5. slug 与 path 不一致：slug: foo 但 path: docs/bar.html → 索引错乱
6. path 指向不存在文件：build 时报错
7. 中文 YAML key 缩进不足（高发陷阱）：list item 子键使用中文标识符（可信度、备注 等）时，若缩进少 1 空格，YAML 解析报 expected <block end>, but found '<block mapping start>'

中文 YAML key 缩进陷阱（Anti-pattern #7 详解）

触发场景：在 meta.yaml 的 list（如 sources:、data_accuracy_notes:）下，用中文作为子键名。

错误写法：

sources:
  - title: "GitHub 官方仓库"
    url: https://github.com/opendatalab/MinerU
   可信度: 高        # ← 少 1 空格！视觉对齐但 YAML 解析失败
    备注: "Stars 66.9k"

正确写法：

sources:
  - title: "GitHub 官方仓库"
    url: https://github.com/opendatalab/MinerU
    可信度: 高       # ← 4 空格，与 url/title 对齐
    备注: "Stars 66.9k"

根因：中文字符视觉宽度与等宽 ASCII 不同，写入时容易"看起来对齐"但实际少 1 空格。

验证命令：

python3 -c "import yaml; yaml.safe_load(open('meta.yaml')); print('YAML OK')"

防呆建议：

• 避免在 list item 子键中使用无引号中文字符串，改用英文 key（credibility / note）
• 或确保所有 key 统一加英文双引号 "可信度":（YAML 解析器对引号键更严格，会拒绝缩进错误）

发布前检查清单

每次发布 meta.yaml 前必须确认：

• 字段名是 desc 而非 description
• desc 首字符是中文（[\u4e00-\u9fff]）
• desc 无前半中后半英的混合结构
• date 精确到秒（YYYY-MM-DD HH:MM:SS）
• slug 与文件名一致
• path 指向真实存在的 HTML 文件
• 发布前可用 references/check_desc_required.py 扫描缺失摘要的 sidecar

Redundancy Policy

本技能不负责：

• 视觉风格（归 infocard-style-man-skill）
• 发布流程 / build / git（归 infocard-pub-publisher）
• 内容抽取 / 网页转卡（归 any2card）

Verification Checklist

• 所有 meta.yaml 使用 desc 而非 description
• 所有 desc 首字符为中文
• 所有 desc 无混合语言结构
• 所有 date 精确到秒
• 所有 path 指向真实文件
• slug 与文件名一致