sqliang Markdown Frontmatter Engine
深度分析指定 Markdown 文件的内容，结合 schema/ 目录下预设的动态字段定义，为其提取并更新符合规范的 Frontmatter 元数据。
字段来源
schema/ 目录下的 .md 文件对应 frontmatter 字段，文件名即字段名，数字前缀控制输出优先级。
工作流
前置准备
步骤 0 — 扫描确认：
python3 ./scripts/batch_ops.py scan "笔记目录" --json
向用户确认处理范围（有多少文件、多少已有 frontmatter），避免范围不符预期。
步骤 1 — 读取格式规范：
读取 FORMAT.md，掌握输出格式要求（字段间空一行、2 空格缩进）。
步骤 2 — 确定字段范围（优先级：对话指定 > .env 配置 > 全量）：
先用 --list 快速枚举 schema 中有哪些可用字段：
python3 ./scripts/batch_ops.py schema "./schema" --list
然后按以下顺序决定本次处理的字段范围：
- 对话指定（最高优先）：用户在对话中明确说"只要 title 和 tags"，用对话指定的字段
- .env 配置（对话未指定时）：读取 skill 根目录的
.env，若有SCHEMA_FIELDS=xxx配置则使用：
此步骤不可跳过。即使后续python3 ./scripts/batch_ops.py env-fields "./" # 输出字段名: title,tags,domain # 或输出 (全量) 表示无配置write/write-multi命令会自动读取.env，此步骤的作用是在写入前让 AI 明确知道本次处理的字段范围，避免分析多余的字段。 - 全量：对话未指定且
.env无配置时，读取 schema 目录下所有.md文件
若对话指定或 .env 中的字段在 schema 里找不到，输出警告并只处理已知字段：
# 若含未知字段，输出: 警告: 以下字段不在 schema 目录中: unknown_field
步骤 3 — 加载选定字段的规则（一次性，缓存）： 根据步骤 2 的结果决定加载范围：
- 全量：读取 schema 目录下所有
.md文件 - 部分字段：只读取用户选定字段对应的 schema 文件
# 全量模式（步骤 2 未指定字段时）
python3 ./scripts/batch_ops.py schema "./schema"
# -> 返回: [1] title, [2] aliases, [3] tags, [4] source, [5] domain
# 部分字段模式（步骤 2 已指定字段时，直接读取对应文件即可）
# 不需要额外命令，缓存 --fields 过滤后的文件列表，按需读取
步骤 4 — 确定操作范围：
- 单个文件：
python3 ./scripts/batch_ops.py read "文件路径" - 目录：扫描结果即范围
- 文件列表：直接处理
批量处理（对操作范围内的每个 .md 文件）
a. 读取解析：读取文件内容，解析已有 frontmatter，只保留不在本次更新范围内的历史字段。
b. 语义提取（只处理选定的字段）：直接使用步骤 3 缓存的 schema 规则（不再读文件），仅对用户指定或全量模式下的字段进行提取，未选字段保持原样不动。
c. 格式化：按 FORMAT.md 规范组装 frontmatter（字段顺序由 schema 文件名数字前缀决定）。
收尾写入（一次性批量写入，不逐文件操作）
所有文件分析完毕后，将结果构造为 JSON 数组，用 write-multi 一次性写入：
python3 ./scripts/batch_ops.py write-multi "笔记目录" updates.json --schema-dir "./schema"
JSON 格式：
[
{"path": "file1.md", "title": "...", "tags": ["tutorial", "python"], "aliases": [], "source": "blog", "domain": "Technology"},
{"path": "file2.md", "title": "...", "tags": ["thought"], "aliases": [], "source": "note", "domain": "Personal"}
]
如需单独写入单个文件，使用多字段模式：
python3 ./scripts/batch_ops.py write "note.md" --json '{"title": "...", "domain": "Technology"}'
异常处理
b 步（读规则）：若 schema 文件解析失败，记录并跳过该字段，继续处理其他字段。
c 步（语义提取）：若根据 Schema 规则无法从正文中推断出明确值，保持该字段为空或使用 Schema 中指定的默认值，禁止随意编造。
d 步（写入）：若写入失败，在报告中标记该文件并说明原因，继续处理其他文件，最后汇总报告。
收尾报告
向用户输出执行报告：成功更新的文件数、跳过的文件数、失败文件及原因。
脚本工具说明
python3 ./scripts/batch_ops.py scan <dir> [--json]：扫描目录下的 .md 文件，--json输出机器可读格式python3 ./scripts/batch_ops.py read <file_path>：读取文件内容和已有 frontmatterpython3 ./scripts/batch_ops.py write <file_path> [--json <json>] [field value]：写入字段，--json接受多字段 JSONpython3 ./scripts/batch_ops.py write-multi <dir> <json_path> [--schema-dir <path>]：批量写入，--schema-dir提供字段顺序python3 ./scripts/batch_ops.py schema <schema_dir>：扫描字段定义，支持两个轻量枚举选项：--list：只列字段名和优先级（不读文件），用于快速了解有哪些可用字段--fields X,Y：只返回指定字段的条目（不读文件），用于字段选择时验证和过滤；未知字段会输出警告
python3 ./scripts/batch_ops.py env-fields <skill_root>：读取 skill 根目录的.env中的SCHEMA_FIELDS配置，输出字段名逗号分隔字符串；无配置时输出(全量)
规模化处理
处理超过 50 个文件时，建议分批处理并向用户实时报告进度（如"已处理 25/100 个"），避免单次操作超时。