@yosai/cli 0.2.1-test.8 → 0.2.1-test.9

package/dist/skills/yos-doc-sheet/scripts/validate-runtime-sheet.mjs

@@ -0,0 +1,404 @@
+/**
+ * CLI 用纯 ESM 校验 SheetWorkbook（IWorkbookData 精简契约）。
+ * 供 ./yos-sheet.mjs 使用（同步自 @yos/sheet-editor@0.0.41）
+ */
+
+/** 与 @yos/sheet-editor MAX_SHEET_ROW_COUNT 对齐 */
+export const AGENT_MAX_ROW_COUNT = 10000;
+
+/** Excel 工作表名上限 */
+export const AGENT_MAX_SHEET_NAME_LENGTH = 31;
+
+/** CellValueType */
+export const AGENT_CELL_VALUE_TYPES = [1, 2, 3, 4];
+
+/** tier A 单元格允许字段 */
+export const AGENT_TIER_A_CELL_KEYS = ["v", "t", "f"];
+
+/** tier B 额外单元格字段 */
+export const AGENT_TIER_B_CELL_KEYS = ["s"];
+
+/** 永远禁止的单元格字段（富文本 / 内部公式 id 等） */
+export const AGENT_FORBIDDEN_CELL_KEYS = ["p", "si", "ref", "xf"];
+
+/**
+ * @param {"A"|"B"} tier
+ * @returns {Set<string>}
+ */
+export function allowedCellKeysForTier(tier) {
+  const keys = new Set(AGENT_TIER_A_CELL_KEYS);
+  if (tier === "B") {
+    for (const key of AGENT_TIER_B_CELL_KEYS) {
+      keys.add(key);
+    }
+  }
+  return keys;
+}
+
+/**
+ * @typedef {{ path: string, message: string }} SheetIssue
+ * @typedef {{ ok: boolean, issues: SheetIssue[] }} SheetValidateResult
+ */
+
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * @param {SheetIssue[]} issues
+ * @param {string} path
+ * @param {string} message
+ */
+function push(issues, path, message) {
+  issues.push({ path, message });
+}
+
+/**
+ * @param {unknown} key
+ * @returns {boolean}
+ */
+function isIndexKey(key) {
+  const n = Number(key);
+  return Number.isInteger(n) && n >= 0 && String(n) === String(key);
+}
+
+/**
+ * @param {SheetIssue[]} issues
+ * @param {string} path
+ * @param {unknown} cell
+ * @param {Set<string>} allowedKeys
+ * @param {"A"|"B"} tier
+ * @param {Set<string>} styleIds
+ */
+function validateCell(issues, path, cell, allowedKeys, tier, styleIds) {
+  if (cell === null || cell === undefined) {
+    return;
+  }
+  if (!isRecord(cell)) {
+    push(issues, path, "单元格必须是对象或 null");
+    return;
+  }
+
+  for (const key of Object.keys(cell)) {
+    if (AGENT_FORBIDDEN_CELL_KEYS.includes(key)) {
+      push(issues, `${path}.${key}`, `禁止字段 ${key}（Agent 勿生成）`);
+      continue;
+    }
+    if (!allowedKeys.has(key)) {
+      push(
+        issues,
+        `${path}.${key}`,
+        tier === "A"
+          ? `tier A 不允许字段 ${key}（样式请用 --tier B）`
+          : `未知单元格字段 ${key}`,
+      );
+    }
+  }
+
+  if ("v" in cell) {
+    const v = cell.v;
+    if (
+      v !== null &&
+      typeof v !== "string" &&
+      typeof v !== "number" &&
+      typeof v !== "boolean"
+    ) {
+      push(issues, `${path}.v`, "v 须为 string | number | boolean | null");
+    }
+  }
+
+  if ("t" in cell) {
+    if (!AGENT_CELL_VALUE_TYPES.includes(cell.t)) {
+      push(issues, `${path}.t`, "t 须为 1|2|3|4（STRING|NUMBER|BOOLEAN|FORCE_STRING）");
+    }
+  }
+
+  if ("f" in cell) {
+    const f = cell.f;
+    if (f !== null && typeof f !== "string") {
+      push(issues, `${path}.f`, "f 须为 string | null");
+    } else if (typeof f === "string") {
+      if (!f.trim()) {
+        push(issues, `${path}.f`, "公式不能为空字符串");
+      } else if (!f.trim().startsWith("=")) {
+        push(issues, `${path}.f`, "公式须含前导 =");
+      }
+    }
+  }
+
+  if (!("v" in cell) && !("f" in cell)) {
+    push(issues, path, "单元格至少需要 v 或 f");
+  }
+
+  if ("s" in cell && tier === "B") {
+    const s = cell.s;
+    if (s === null) {
+      // ok
+    } else if (typeof s === "string") {
+      if (s && styleIds.size > 0 && !styleIds.has(s)) {
+        push(issues, `${path}.s`, `样式 id "${s}" 未在根 styles 中定义`);
+      }
+    } else if (!isRecord(s)) {
+      push(issues, `${path}.s`, "s 须为样式 id 字符串、样式对象或 null");
+    }
+  }
+}
+
+/**
+ * @param {SheetIssue[]} issues
+ * @param {string} path
+ * @param {unknown} sheet
+ * @param {string} expectedId
+ * @param {"A"|"B"} tier
+ * @param {Set<string>} styleIds
+ */
+function validateSheet(issues, path, sheet, expectedId, tier, styleIds) {
+  if (!isRecord(sheet)) {
+    push(issues, path, "sheet 必须是对象");
+    return;
+  }
+
+  if (typeof sheet.id !== "string" || !sheet.id) {
+    push(issues, `${path}.id`, "id 必须是非空字符串");
+  } else if (sheet.id !== expectedId) {
+    push(issues, `${path}.id`, `建议与 sheets 的 key 一致（当前 key=${expectedId}）`);
+  }
+
+  if (typeof sheet.name !== "string" || !sheet.name.trim()) {
+    push(issues, `${path}.name`, "name 必须是非空字符串");
+  } else if (sheet.name.length > AGENT_MAX_SHEET_NAME_LENGTH) {
+    push(
+      issues,
+      `${path}.name`,
+      `name 长度不能超过 ${AGENT_MAX_SHEET_NAME_LENGTH}`,
+    );
+  }
+
+  if ("rowCount" in sheet) {
+    if (typeof sheet.rowCount !== "number" || !Number.isInteger(sheet.rowCount)) {
+      push(issues, `${path}.rowCount`, "rowCount 须为正整数");
+    } else if (sheet.rowCount < 1 || sheet.rowCount > AGENT_MAX_ROW_COUNT) {
+      push(
+        issues,
+        `${path}.rowCount`,
+        `rowCount 须在 1～${AGENT_MAX_ROW_COUNT}`,
+      );
+    }
+  }
+
+  if ("columnCount" in sheet) {
+    if (
+      typeof sheet.columnCount !== "number" ||
+      !Number.isInteger(sheet.columnCount) ||
+      sheet.columnCount < 1
+    ) {
+      push(issues, `${path}.columnCount`, "columnCount 须为正整数");
+    }
+  }
+
+  const tierBOnly = [
+    "styles",
+    "mergeData",
+    "freeze",
+    "rowData",
+    "columnData",
+    "tabColor",
+    "defaultStyle",
+  ];
+  if (tier === "A") {
+    for (const key of tierBOnly) {
+      if (key in sheet && sheet[key] !== undefined) {
+        const emptyArray =
+          key === "mergeData" &&
+          Array.isArray(sheet[key]) &&
+          sheet[key].length === 0;
+        const emptyObject =
+          (key === "rowData" || key === "columnData") &&
+          isRecord(sheet[key]) &&
+          Object.keys(sheet[key]).length === 0;
+        const emptyTab = key === "tabColor" && sheet[key] === "";
+        if (emptyArray || emptyObject || emptyTab) {
+          continue;
+        }
+        push(issues, `${path}.${key}`, `tier A 不允许 ${key}（请用 --tier B）`);
+      }
+    }
+  }
+
+  if ("mergeData" in sheet && sheet.mergeData !== undefined) {
+    if (!Array.isArray(sheet.mergeData)) {
+      push(issues, `${path}.mergeData`, "mergeData 须为数组");
+    } else if (tier === "B") {
+      sheet.mergeData.forEach((range, index) => {
+        const rPath = `${path}.mergeData[${index}]`;
+        if (!isRecord(range)) {
+          push(issues, rPath, "合并区须为对象");
+          return;
+        }
+        for (const key of [
+          "startRow",
+          "startColumn",
+          "endRow",
+          "endColumn",
+        ]) {
+          if (typeof range[key] !== "number" || !Number.isInteger(range[key])) {
+            push(issues, `${rPath}.${key}`, `${key} 须为整数`);
+          }
+        }
+      });
+    }
+  }
+
+  if ("freeze" in sheet && sheet.freeze !== undefined && tier === "B") {
+    if (!isRecord(sheet.freeze)) {
+      push(issues, `${path}.freeze`, "freeze 须为对象");
+    }
+  }
+
+  if (!("cellData" in sheet) || sheet.cellData === undefined) {
+    push(issues, `${path}.cellData`, "缺少 cellData");
+    return;
+  }
+  if (!isRecord(sheet.cellData)) {
+    push(issues, `${path}.cellData`, "cellData 须为对象（稀疏矩阵）");
+    return;
+  }
+
+  const allowedKeys = allowedCellKeysForTier(tier);
+  for (const [rowKey, row] of Object.entries(sheet.cellData)) {
+    if (!isIndexKey(rowKey)) {
+      push(issues, `${path}.cellData.${rowKey}`, "行 key 须为非负整数");
+      continue;
+    }
+    if (row === null || row === undefined) {
+      continue;
+    }
+    if (!isRecord(row)) {
+      push(issues, `${path}.cellData.${rowKey}`, "行须为对象");
+      continue;
+    }
+    for (const [colKey, cell] of Object.entries(row)) {
+      if (!isIndexKey(colKey)) {
+        push(
+          issues,
+          `${path}.cellData.${rowKey}.${colKey}`,
+          "列 key 须为非负整数",
+        );
+        continue;
+      }
+      validateCell(
+        issues,
+        `${path}.cellData.${rowKey}.${colKey}`,
+        cell,
+        allowedKeys,
+        tier,
+        styleIds,
+      );
+    }
+  }
+}
+
+/**
+ * 校验 Agent 生成的 SheetWorkbook 快照。
+ * @param {Record<string, unknown>} workbook
+ * @param {{ tier?: "A"|"B" }} [options]
+ * @returns {SheetValidateResult}
+ */
+export function validateSheetWorkbook(workbook, options = {}) {
+  const tier = options.tier === "B" ? "B" : "A";
+  /** @type {SheetIssue[]} */
+  const issues = [];
+
+  if (!isRecord(workbook)) {
+    return { ok: false, issues: [{ path: "", message: "根必须是对象" }] };
+  }
+
+  if (typeof workbook.id !== "string" || !workbook.id) {
+    push(issues, "id", "id 必须是非空字符串");
+  }
+  if (typeof workbook.name !== "string" || !workbook.name.trim()) {
+    push(issues, "name", "name 必须是非空字符串");
+  }
+
+  if ("resources" in workbook && workbook.resources !== undefined) {
+    if (!Array.isArray(workbook.resources)) {
+      push(issues, "resources", "resources 须为数组");
+    } else if (workbook.resources.length > 0) {
+      push(
+        issues,
+        "resources",
+        "禁止非空 resources（勿编造插件状态；请用 [] 或省略）",
+      );
+    }
+  }
+
+  /** @type {Set<string>} */
+  const styleIds = new Set();
+  if ("styles" in workbook && workbook.styles !== undefined) {
+    if (tier === "A") {
+      if (isRecord(workbook.styles) && Object.keys(workbook.styles).length === 0) {
+        // 空 styles 允许
+      } else {
+        push(issues, "styles", "tier A 不允许 styles（请用 --tier B）");
+      }
+    } else if (!isRecord(workbook.styles)) {
+      push(issues, "styles", "styles 须为对象");
+    } else {
+      for (const id of Object.keys(workbook.styles)) {
+        styleIds.add(id);
+        const style = workbook.styles[id];
+        if (style !== null && !isRecord(style)) {
+          push(issues, `styles.${id}`, "样式须为对象或 null");
+        }
+      }
+    }
+  }
+
+  if (!Array.isArray(workbook.sheetOrder) || workbook.sheetOrder.length === 0) {
+    push(issues, "sheetOrder", "sheetOrder 须为非空字符串数组");
+  } else {
+    workbook.sheetOrder.forEach((id, index) => {
+      if (typeof id !== "string" || !id) {
+        push(issues, `sheetOrder[${index}]`, "须为非空字符串");
+      }
+    });
+  }
+
+  if (!isRecord(workbook.sheets)) {
+    push(issues, "sheets", "sheets 须为对象");
+  } else {
+    const order = Array.isArray(workbook.sheetOrder) ? workbook.sheetOrder : [];
+    for (const id of order) {
+      if (typeof id !== "string") {
+        continue;
+      }
+      if (!(id in workbook.sheets)) {
+        push(issues, `sheets.${id}`, "sheetOrder 中的 id 在 sheets 中不存在");
+        continue;
+      }
+      validateSheet(
+        issues,
+        `sheets.${id}`,
+        workbook.sheets[id],
+        id,
+        tier,
+        styleIds,
+      );
+    }
+    for (const id of Object.keys(workbook.sheets)) {
+      if (!order.includes(id)) {
+        push(
+          issues,
+          `sheets.${id}`,
+          "存在于 sheets 但不在 sheetOrder 中（请加入 sheetOrder）",
+        );
+      }
+    }
+  }
+
+  return { ok: issues.length === 0, issues };
+}

package/dist/skills/yos-doc-sheet/scripts/yos-doc.mjs

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+/**
+ * yos-doc — DocDraft schema / validate CLI（Node ≥ 18）
+ * 实现：./validate-runtime-doc.mjs（同步自 @yos/doc-editor@0.0.41）
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  AGENT_ALLOWED_MARKS,
+  AGENT_FORBIDDEN_MARKS,
+  AGENT_FORBIDDEN_NODES,
+  AGENT_TIER_A_NODES,
+  AGENT_TIER_B_NODES,
+  validateDocDraft,
+} from "./validate-runtime-doc.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REFERENCES_DIR = resolve(__dirname, "..", "references");
+
+function printHelp() {
+  process.stdout.write(`yos-doc — YOS DocDraft 工具（Agent / CI）
+
+用法:
+  yos-doc schema [--tier A|B]
+  yos-doc validate <draft.json> [--tier A|B]
+  yos-doc paths
+
+命令:
+  schema    打印当前档位白名单（JSON）
+  validate  校验 DocDraft JSON 文件；通过 exit 0，失败 exit 1
+  paths     打印 AGENT_SCHEMA / few-shot / 全量文档路径
+
+选项:
+  --tier A|B   默认 A；B 额外允许 columnBlock / column / image
+  -h, --help   帮助
+`);
+}
+
+function parseTier(argv) {
+  const index = argv.indexOf("--tier");
+  if (index === -1) {
+    return "A";
+  }
+  const value = argv[index + 1];
+  if (value === "A" || value === "B") {
+    return value;
+  }
+  process.stderr.write(`无效 --tier: ${String(value)}（仅 A|B）\n`);
+  process.exit(2);
+}
+
+function cmdSchema(tier) {
+  const payload = {
+    tier,
+    root: {
+      title: "string",
+      content: { type: "doc", content: [] },
+      attachments: [],
+    },
+    nodes: {
+      A: [...AGENT_TIER_A_NODES],
+      B: tier === "B" ? [...AGENT_TIER_B_NODES] : [],
+      forbidden: [...AGENT_FORBIDDEN_NODES],
+    },
+    marks: {
+      allowed: [...AGENT_ALLOWED_MARKS],
+      forbidden: [...AGENT_FORBIDDEN_MARKS],
+    },
+    docs: {
+      agentSchema: "references/AGENT_SCHEMA.doc.md",
+      fewShot: "references/few-shot.draft.json",
+      fullApi: "references/DOC_DATA_API.md",
+    },
+  };
+  process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+}
+
+function cmdPaths() {
+  const paths = {
+    agentSchema: join(REFERENCES_DIR, "AGENT_SCHEMA.doc.md"),
+    fewShot: join(REFERENCES_DIR, "few-shot.draft.json"),
+    fullApi: join(REFERENCES_DIR, "DOC_DATA_API.md"),
+    template: join(REFERENCES_DIR, "doc-draft.template.json"),
+  };
+  process.stdout.write(`${JSON.stringify(paths, null, 2)}\n`);
+}
+
+function cmdValidate(fileArg, tier) {
+  if (!fileArg) {
+    process.stderr.write("validate 需要 <draft.json> 路径\n");
+    process.exit(2);
+  }
+  const filePath = resolve(process.cwd(), fileArg);
+  let raw;
+  try {
+    raw = readFileSync(filePath, "utf8");
+  } catch (error) {
+    process.stderr.write(`无法读取: ${filePath}\n${String(error)}\n`);
+    process.exit(2);
+  }
+  let draft;
+  try {
+    draft = JSON.parse(raw);
+  } catch (error) {
+    process.stderr.write(`JSON 解析失败: ${String(error)}\n`);
+    process.exit(1);
+  }
+  if (typeof draft !== "object" || draft === null || Array.isArray(draft)) {
+    process.stderr.write("根必须是对象（DocDraft）\n");
+    process.exit(1);
+  }
+  const result = validateDocDraft(draft, { tier });
+  if (result.ok) {
+    process.stdout.write(`OK (${filePath}) tier=${tier}\n`);
+    process.exit(0);
+  }
+  process.stderr.write(
+    `FAIL (${filePath}) tier=${tier} — ${result.issues.length} issue(s)\n`,
+  );
+  for (const issue of result.issues) {
+    process.stderr.write(`  - ${issue.path}: ${issue.message}\n`);
+  }
+  process.exit(1);
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  if (argv.length === 0 || argv.includes("-h") || argv.includes("--help")) {
+    printHelp();
+    process.exit(argv.length === 0 ? 2 : 0);
+  }
+  const command = argv[0];
+  const tier = parseTier(argv);
+  if (command === "schema") {
+    cmdSchema(tier);
+    return;
+  }
+  if (command === "paths") {
+    cmdPaths();
+    return;
+  }
+  if (command === "validate") {
+    const fileArg = argv.find(
+      (item, index) =>
+        index > 0 && !item.startsWith("-") && argv[index - 1] !== "--tier",
+    );
+    cmdValidate(fileArg, tier);
+    return;
+  }
+  process.stderr.write(`未知命令: ${String(command)}\n`);
+  printHelp();
+  process.exit(2);
+}
+
+main();

package/dist/skills/yos-doc-sheet/scripts/yos-sheet.mjs

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+/**
+ * yos-sheet — SheetWorkbook schema / validate CLI（Node ≥ 18）
+ * 实现：./validate-runtime-sheet.mjs（同步自 @yos/sheet-editor@0.0.41）
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  AGENT_FORBIDDEN_CELL_KEYS,
+  AGENT_MAX_ROW_COUNT,
+  AGENT_TIER_A_CELL_KEYS,
+  AGENT_TIER_B_CELL_KEYS,
+  validateSheetWorkbook,
+} from "./validate-runtime-sheet.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REFERENCES_DIR = resolve(__dirname, "..", "references");
+
+function printHelp() {
+  process.stdout.write(`yos-sheet — YOS SheetWorkbook 工具（Agent / CI）
+
+用法:
+  yos-sheet schema [--tier A|B]
+  yos-sheet validate <workbook.json> [--tier A|B]
+  yos-sheet paths
+
+命令:
+  schema    打印当前档位白名单（JSON）
+  validate  校验工作簿 JSON；通过 exit 0，失败 exit 1
+  paths     打印 AGENT_SCHEMA / few-shot / 全量文档路径
+
+选项:
+  --tier A|B   默认 A；B 额外允许 styles / merge / freeze / 行列宽
+  -h, --help   帮助
+`);
+}
+
+function parseTier(argv) {
+  const index = argv.indexOf("--tier");
+  if (index === -1) {
+    return "A";
+  }
+  const value = argv[index + 1];
+  if (value === "A" || value === "B") {
+    return value;
+  }
+  process.stderr.write(`无效 --tier: ${String(value)}（仅 A|B）\n`);
+  process.exit(2);
+}
+
+function cmdSchema(tier) {
+  const payload = {
+    tier,
+    root: {
+      id: "string",
+      name: "string",
+      sheetOrder: ["sheet-1"],
+      sheets: {},
+      resources: [],
+    },
+    cells: {
+      A: [...AGENT_TIER_A_CELL_KEYS],
+      B: tier === "B" ? [...AGENT_TIER_B_CELL_KEYS] : [],
+      forbidden: [...AGENT_FORBIDDEN_CELL_KEYS],
+    },
+    limits: {
+      maxRowCount: AGENT_MAX_ROW_COUNT,
+    },
+    docs: {
+      agentSchema: "references/AGENT_SCHEMA.sheet.md",
+      fewShot: "references/few-shot.workbook.json",
+      fullApi: "references/SHEET_DATA_API.md",
+    },
+  };
+  process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+}
+
+function cmdPaths() {
+  const paths = {
+    agentSchema: join(REFERENCES_DIR, "AGENT_SCHEMA.sheet.md"),
+    fewShot: join(REFERENCES_DIR, "few-shot.workbook.json"),
+    fullApi: join(REFERENCES_DIR, "SHEET_DATA_API.md"),
+    template: join(REFERENCES_DIR, "sheet-workbook.template.json"),
+  };
+  process.stdout.write(`${JSON.stringify(paths, null, 2)}\n`);
+}
+
+function cmdValidate(fileArg, tier) {
+  if (!fileArg) {
+    process.stderr.write("validate 需要 <workbook.json> 路径\n");
+    process.exit(2);
+  }
+  const filePath = resolve(process.cwd(), fileArg);
+  let raw;
+  try {
+    raw = readFileSync(filePath, "utf8");
+  } catch (error) {
+    process.stderr.write(`无法读取: ${filePath}\n${String(error)}\n`);
+    process.exit(2);
+  }
+  let workbook;
+  try {
+    workbook = JSON.parse(raw);
+  } catch (error) {
+    process.stderr.write(`JSON 解析失败: ${String(error)}\n`);
+    process.exit(1);
+  }
+  if (typeof workbook !== "object" || workbook === null || Array.isArray(workbook)) {
+    process.stderr.write("根必须是对象（SheetWorkbook）\n");
+    process.exit(1);
+  }
+  const result = validateSheetWorkbook(workbook, { tier });
+  if (result.ok) {
+    process.stdout.write(`OK (${filePath}) tier=${tier}\n`);
+    process.exit(0);
+  }
+  process.stderr.write(
+    `FAIL (${filePath}) tier=${tier} — ${result.issues.length} issue(s)\n`,
+  );
+  for (const issue of result.issues) {
+    process.stderr.write(`  - ${issue.path}: ${issue.message}\n`);
+  }
+  process.exit(1);
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  if (argv.length === 0 || argv.includes("-h") || argv.includes("--help")) {
+    printHelp();
+    process.exit(argv.length === 0 ? 2 : 0);
+  }
+  const command = argv[0];
+  const tier = parseTier(argv);
+  if (command === "schema") {
+    cmdSchema(tier);
+    return;
+  }
+  if (command === "paths") {
+    cmdPaths();
+    return;
+  }
+  if (command === "validate") {
+    const fileArg = argv.find(
+      (item, index) =>
+        index > 0 && !item.startsWith("-") && argv[index - 1] !== "--tier",
+    );
+    cmdValidate(fileArg, tier);
+    return;
+  }
+  process.stderr.write(`未知命令: ${String(command)}\n`);
+  printHelp();
+  process.exit(2);
+}
+
+main();