changan-su/forsion/amadeus-note-format

<!-- a c1 -->
这张卡/这一列的内容
 
<!-- /a c1 -->

# ❌ 有画布没 schema → 文件被判成 v3 → 打开时被拽进补号管线原地改写 = 毁档
amadeus_canvas: {"v":1,...}
 
# ❌ 有 schema 没结构 → 半吊子文件
amadeus_schema: amadeus.page/4
 
# ✅
amadeus_schema: amadeus.page/4
amadeus_canvas: {"v":1,...}

amadeus_schema: amadeus.page/4
amadeus_layout: {"v":4,"rows":[{"columns":[{"refs":["cg7qn"],"width":1},{"refs":["cu671"],"width":1}],"tail":"cybwa"}]}

amadeus_schema: amadeus.page/4
amadeus_canvas: {"v":1,"mode":"canvas","main":{"x":6,"y":-25,"w":515},"cards":[{"ref":"cubeh","x":597,"y":1,"w":400}],"tree":{"cubeh":"m:"},"elements":[]}

主卡的自然流正文照旧写……
 
<!-- a cubeh -->
 
这张卡片的内容
 
<!-- /a cubeh -->

import { readFileSync } from 'node:fs';
const raw = readFileSync(process.argv[2], 'utf8'); const errs = [], warns = [];
const done = (line) => { console.log(line);
  warns.forEach((w) => console.log(`⚠️  ${w}`)); errs.forEach((e) => console.log(`❌ ${e}`));
  console.log(errs.length ? `\n不通过:${errs.length} 个问题` : '\n通过'); process.exit(errs.length ? 1 : 0); };
const fm = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(raw);
const head = fm ? fm[1] : '', body = fm ? raw.slice(fm[0].length) : raw;
// 键名容忍 YAML 单/双引号写法('amadeus_schema': …),与宿主 AMADEUS_FM_KEY 同口径 —— 只认双引号
// 会把带单引号的结构化文件当成素文件放行,后面所有检查一条都不跑。
const keys = [...head.matchAll(/^['"]?(amadeus_[A-Za-z0-9_-]+)['"]?\s*:/gm)].map((m) => m[1]);
const major = (/^['"]?amadeus_schema['"]?\s*:\s*['"]?amadeus\.page\/(\d+)['"]?\s*$/m.exec(head) || [])[1];
const v4 = major === '4';
if (major && +major > 4) { errs.push(`amadeus_schema 主版本 ${major} 比 v4 新 → 宿主整篇当单块只读、编译器拒写。别改它`); done('未来格式文件'); }
// v4-only 结构键出现在非 v4 文件里 = 毁档形态(v3 自己的 amadeus_layout 是另一套形状,合法)。
const layoutV4 = /^['"]?amadeus_layout['"]?\s*:\s*['"]?\{\s*"v"\s*:\s*4/m.test(head);
if ((keys.includes('amadeus_canvas') || layoutV4) && !v4)
  errs.push('有 amadeus_canvas / v4 分栏却缺 amadeus_schema: amadeus.page/4 → 被判成 v3,打开即补号改写(毁档)');
if (!keys.length) done('素文件(纯 markdown)—— v4 常态,无结构可校验');
if (!v4) done(`v3 文件(键: ${keys.join(', ')})—— 保留 frontmatter 与标记原样,别手工迁 v4`);
if (!keys.includes('amadeus_layout') && !keys.includes('amadeus_canvas'))
  errs.push('有 amadeus_schema 却没有 amadeus_layout / amadeus_canvas → 违反发射不变式');
// ⚠️ 只警告,**不是错误**:v4 文件里的未知 amadeus_* 键是新版客户端的不透明扩展,宿主承诺原样保管。
// 报成错误会诱使人「清理」掉它 = 老端一次保存吞掉新端的数据。别删,也别自己新造。
const extra = keys.filter((k) => !['amadeus_schema', 'amadeus_layout', 'amadeus_canvas'].includes(k));
if (extra.length) warns.push(`不认识的 amadeus_ 键: ${extra.join(', ')} —— 若非你写的,原样留着别删(新端扩展);也别自己新造`);
const OPEN = /^<!--\s*a\s+([A-Za-z0-9_-]+)\s*-->\s*$/, CLOSE = /^<!--\s*\/a\s+([A-Za-z0-9_-]+)\s*-->\s*$/;
const order = [], seen = new Set(); let cur = null;
body.split('\n').forEach((line, i) => {
  const o = OPEN.exec(line);
  if (o) { if (seen.has(o[1])) errs.push(`锚 id 重复: ${o[1]}`); seen.add(o[1]); order.push(o[1]); cur = o[1]; return; }
  const c = CLOSE.exec(line);
  if (c) { if (c[1] === cur) cur = null;
    else warns.push(`第 ${i + 1} 行 <!-- /a ${c[1]} --> 与当前锚(${cur ?? '无'})不匹配 → 不收束,按正文字面留着`); }
});
const jsonOf = (k) => { const m = new RegExp(`^['"]?${k}['"]?\\s*:\\s*(.*)$`, 'm').exec(head); if (!m) return null;
  let s = m[1].trim(); if (/^['"]/.test(s)) s = s.slice(1, -1);
  try { return JSON.parse(s); } catch (e) { errs.push(`${k} 不是合法 JSON: ${e.message}`); return null; } };
const layout = jsonOf('amadeus_layout'), canvas = jsonOf('amadeus_canvas'), lrefs = new Set();
if (layout) { if (layout.v !== 4) errs.push(`amadeus_layout 的 v 必须是 4(当前 ${layout.v})`);
  for (const r of layout.rows || []) {
    for (const col of r.columns || []) for (const ref of col.refs || []) {
      if (!seen.has(ref)) errs.push(`amadeus_layout 引用了不存在的锚 "${ref}"`); lrefs.add(ref); }
    if (r.tail) { if (!seen.has(r.tail)) errs.push(`分栏行 tail 锚 "${r.tail}" 不存在`); lrefs.add(r.tail); }
    const pos = (r.columns || []).flatMap((c) => c.refs || []).map((x) => order.indexOf(x));
    if (pos.some((p, i) => i && p !== pos[i - 1] + 1)) warns.push('分栏行的 refs 在源文里不连续 → 读侧把整行拆回自然流');
  } }
// 画布键是 **fail-closed 整键作废**:下面任何一条不满足,宿主 parseCanvasJson 直接丢掉整个
// amadeus_canvas —— 用户的卡片坐标、连线、白板元素一次全没。所以这些都是错误,不是风格问题。
const num = (v) => typeof v === 'number' && Number.isFinite(v); // 字符串 "900" 不算数
if (canvas) {
  if (canvas.v !== 1) errs.push(`amadeus_canvas 的 v 必须是数字 1(当前 ${JSON.stringify(canvas.v)})→ 整键作废`);
  if (canvas.mode != null && canvas.mode !== 'doc' && canvas.mode !== 'canvas')
    errs.push(`mode 只能是 "doc" 或 "canvas"(当前 ${JSON.stringify(canvas.mode)})→ 整键作废`);
  if (canvas.main != null && (!num(canvas.main.x) || !num(canvas.main.y) || !num(canvas.main.w) || canvas.main.w <= 0))
    errs.push('main 的 x/y 必须是有限数、w 必须 > 0 → 整键作废');
  if (canvas.cards != null && !Array.isArray(canvas.cards)) errs.push('cards 必须是数组 → 整键作废');
  if (canvas.elements != null && !Array.isArray(canvas.elements)) errs.push('elements 必须是数组 → 整键作废');
  const rs = (Array.isArray(canvas.cards) ? canvas.cards : []).map((c) => c?.ref);
  if (new Set(rs).size !== rs.length) errs.push('cards 里同一个 ref 出现两次 → 歧义,整键作废');
}
for (const c of (Array.isArray(canvas?.cards) ? canvas.cards : [])) {
  if (typeof c?.ref !== 'string' || !/^[A-Za-z0-9_-]+$/.test(c.ref)) { errs.push(`卡片 ref 非法: ${JSON.stringify(c?.ref)} → 整键作废`); continue; }
  if (!seen.has(c.ref)) errs.push(`amadeus_canvas 引用了不存在的卡锚 "${c.ref}"`);
  if (lrefs.has(c.ref)) errs.push(`锚 "${c.ref}" 同时被分栏与画布引用 → 违反互斥不变式`);
  if (!num(c.x) || !num(c.y) || !num(c.w) || c.w <= 0) errs.push(`卡片 "${c.ref}" 的 x/y 必须是有限数、w 必须 > 0(w 必写)→ 整键作废`);
  if (c.h != null && (!num(c.h) || c.h < 0)) errs.push(`卡片 "${c.ref}" 的 h 若写就必须是 ≥ 0 的有限数 → 整键作废`); }
for (const [k, v] of Object.entries(canvas?.tree || {}))
  if (v !== 'm:' && !seen.has(v)) errs.push(`tree 里 "${k}" 的父 "${v}" 既不是主卡哨兵 m: 也不是已有锚`);
done(`v4 结构化:锚 ${order.length} 枚,分栏行 ${layout?.rows?.length ?? 0},卡片 ${canvas?.cards?.length ?? 0}`);