@citeark/agent 0.3.20

package/src/deployment/supplement.mjs

@@ -0,0 +1,51 @@
+import { cp, mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { assembleCapDirectory, CAP_PROFILE } from '../cap/v2/core.mjs';
+import { canonicalJsonBytes } from '../cap/v2/canonical-json.mjs';
+import { capRecordId } from '../cap/v2/research-records.mjs';
+import { signCapArtifact, attachCapAttestation } from '../cap/v2/attestation.mjs';
+import { verifyCapDirectory } from '../cap/v2/verify.mjs';
+import { HANDOFF_ROLE, HANDOFF_SCHEMA, assertPortableHandoff, validateCodeFiles } from './handoff.mjs';
+import { sha256Value } from '../util.mjs';
+
+/** Add delivery metadata; all scientific Records and original Blobs stay identical. */
+export async function assembleHandoffSupplement({ sourceDirectory, directory, handoff, signingKeyPath }) {
+  const source = await verifyCapDirectory(sourceDirectory);
+  if (!source.valid) throw Error('Invalid source CAP');
+  if (handoff.schema !== HANDOFF_SCHEMA || handoff.delivery?.replayReady !== true) throw Error('Handoff is not ready');
+  assertPortableHandoff(handoff); validateCodeFiles(handoff.files);
+  if (handoff.policy) throw Error('Do not publish historical private verification policies');
+  const manifest = source.manifest;
+  if (manifest.blobs.some(b => b.roles.includes(HANDOFF_ROLE))) throw Error('Source already has a handoff; select its original execution CAP');
+  const records = await Promise.all(manifest.records.map(r => readFile(path.join(sourceDirectory, r.path), 'utf8').then(JSON.parse)));
+  const execution = records.find(r => r.role === 'execution');
+  if ((execution.citeark.sharedExecutionRunId ?? execution.citeark.runId) !== handoff.sourceRunId) throw Error('Handoff execution mismatch');
+  const blobs = await Promise.all(manifest.blobs.map(async b => ({ ...b,
+    ...(b.availability === 'embedded' ? { bytes: await readFile(path.join(sourceDirectory, b.path)) } : {}) })));
+  blobs.push({ id: capRecordId('blob', `handoff:${sha256Value(handoff)}`), roles: [HANDOFF_ROLE],
+    mediaType: 'application/json', bytes: canonicalJsonBytes(handoff),
+    rights: { statement: 'CiteArk execution handoff; retained implementation keeps its original source rights.' } });
+  const built = await assembleCapDirectory({ directory,
+    artifact: { id: capRecordId('artifact', `${source.artifactDigest}:handoff:${sha256Value(handoff)}`),
+      createdAt: handoff.delivery.generatedAt, createdBy: manifest.artifact.createdBy.ref },
+    profiles: manifest.profiles.filter(p => p !== CAP_PROFILE.core),
+    roots: manifest.roots.map(({role,ref}) => ({role,ref})), records, blobs,
+    relations: [...manifest.relations, { relationship: 'derivedFrom', artifactDigest: source.artifactDigest,
+      summary: 'Adds execution handoff only. No experiment rerun, scientific Record change or reassessment.' }] });
+  for (const name of ['projections', 'preview']) await cp(path.join(sourceDirectory, name), path.join(directory, name), { recursive: true }).catch(error => { if (error.code !== 'ENOENT') throw error; });
+  if (manifest.profiles.includes(CAP_PROFILE.publicBundle)) {
+    await mkdir(directory, { recursive: true });
+    await writeFile(path.join(directory, 'ro-crate-metadata.json'), canonicalJsonBytes({
+      '@context': 'https://w3id.org/ro/crate/1.3/context', '@graph': [
+        {'@id':'ro-crate-metadata.json','@type':'CreativeWork',about:{'@id':'./'}},
+        {'@id':'./','@type':'Dataset',identifier:built.artifactDigest,hasPart:built.manifest.records.map(r=>({'@id':r.path}))},
+      ],
+    }));
+  }
+  await attachCapAttestation({ directory, attestation: await signCapArtifact({ artifactDigest: built.artifactDigest,
+    actor: { ref: manifest.artifact.createdBy.ref }, signingKeyPath }) });
+  const verified = await verifyCapDirectory(directory);
+  if (!verified.valid) throw Error(verified.issues.join('\n'));
+  if (manifest.records.some(r => !verified.manifest.records.some(next => next.id === r.id && next.digest === r.digest))) throw Error('Scientific Records changed');
+  return { ...built, sourceArtifactDigest: source.artifactDigest, sourceRunId: execution.citeark.runId };
+}

package/src/deployment/terminal.mjs

@@ -0,0 +1,43 @@
+import { createInterface } from 'node:readline';
+import { Writable } from 'node:stream';
+
+export function cancelled() {
+  return Object.assign(Error('Operation cancelled.'), { exitCode: 130 });
+}
+
+export function createTerminalPrompter({ input = process.stdin, output = process.stdout } = {}) {
+  return {
+    async ask(label, { defaultValue = '', secret = false } = {}) {
+      if (!input.isTTY) throw Error('An interactive terminal is required. For automation, provide model options or use --dry-run.');
+      let muted = false;
+      const display = new Writable({ write(chunk, encoding, callback) {
+        if (!muted) output.write(chunk, encoding);
+        callback();
+      } });
+      display.isTTY = output.isTTY;
+      display.columns = output.columns;
+      const rl = createInterface({ input, output: display, terminal: true });
+      const prompt = `${label}${defaultValue ? ` [${defaultValue}]` : ''}: `;
+      return await new Promise((resolve, reject) => {
+        let settled = false;
+        const abort = () => {
+          if (settled) return;
+          settled = true; muted = false; output.write('\n'); rl.close(); reject(cancelled());
+        };
+        rl.on('SIGINT', abort);
+        rl.on('close', abort);
+        rl.question(prompt, value => {
+          settled = true;
+          muted = false;
+          if (secret) output.write('\n');
+          rl.close();
+          resolve(value.trim() || defaultValue);
+        });
+        muted = secret;
+      });
+    },
+    async confirm(label) {
+      return /^(?:y|yes)$/i.test(await this.ask(`${label} [y/N]`));
+    },
+  };
+}

package/src/diagnosis/renderer.mjs

@@ -0,0 +1,75 @@
+import { redactString } from "../cap/redaction.mjs";
+
+/**
+ * Turn the execution Agent's deliberately free-form analysis into a portable
+ * CAP preview. Scientific status remains canonical in the root Assessment
+ * Record; this file is an Agent interpretation intended for people.
+ */
+export function renderAgentDiagnosis({ contract, result, assessment, integrity }) {
+  const claimId = contract.research?.claimId ?? contract.research?.claimVersionId ?? "unknown claim";
+  const agentText = freeformDiagnosis(result);
+  const comparisons = Array.isArray(assessment.measurementAssessments)
+    ? assessment.measurementAssessments
+    : [];
+  const lines = [
+    "# Agent diagnosis",
+    "",
+    "> This is the execution Agent's interpretation of the recorded run. Canonical observations and the reproduction conclusion remain in the CAP Evidence and root Assessment Records.",
+    "",
+    "## Outcome",
+    "",
+    `- Claim: \`${claimId}\``,
+    `- Execution: \`${result.execution?.status ?? "unknown"}\``,
+    `- Integrity: \`${integrity.status ?? "unknown"}\``,
+    `- Verification: \`${assessment.verificationStatus ?? "inconclusive"}\``,
+  ];
+  for (const item of comparisons) {
+    const comparison = item.comparison ?? {};
+    lines.push(
+      `- ${comparison.metric ?? item.measurementId ?? "measurement"}: reported ${display(comparison.reportedValue)} ${comparison.unit ?? ""}; observed ${display(comparison.observedValue)}; status \`${item.verificationStatus ?? "inconclusive"}\``,
+    );
+  }
+  lines.push(
+    "",
+    "## Analysis",
+    "",
+    redactString(agentText),
+    "",
+  );
+  if (Array.isArray(result.limitations) && result.limitations.length) {
+    lines.push("## Remaining uncertainty", "");
+    for (const limitation of result.limitations) lines.push(`- ${redactString(String(limitation))}`);
+    lines.push("");
+  }
+  const markdown = `${lines.join("\n").trim()}\n`;
+  return {
+    markdown,
+    summary: diagnosisSummary(agentText),
+  };
+}
+
+function freeformDiagnosis(result) {
+  if (typeof result?.diagnosis === "string" && result.diagnosis.trim()) {
+    return result.diagnosis.trim();
+  }
+  if (typeof result?.execution?.failure?.reason === "string") {
+    return result.execution.failure.reason.trim();
+  }
+  if (typeof result?.execution?.summary === "string") {
+    return result.execution.summary.trim();
+  }
+  return "The execution Agent did not identify a more specific cause from the available evidence.";
+}
+
+function diagnosisSummary(value) {
+  const paragraph = String(value)
+    .replace(/^#+\s.*$/gm, "")
+    .split(/\n\s*\n/)
+    .map((item) => item.replaceAll(/\s+/g, " ").trim())
+    .find(Boolean) ?? "The Agent did not identify a more specific cause.";
+  return redactString(paragraph).slice(0, 1_000);
+}
+
+function display(value) {
+  return typeof value === "number" && Number.isFinite(value) ? String(value) : "unavailable";
+}

package/src/diagnosis/target-failure.mjs

@@ -0,0 +1,46 @@
+import { readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+
+import { redactString } from "../cap/redaction.mjs";
+
+/**
+ * Recover the best per-target explanation even when the wider pipeline exits
+ * before it can seal a CAP. Prefer the execution Agent's own result; otherwise
+ * retain a clearly labelled workflow error instead of silently leaving the
+ * claim in an unexplained pending state.
+ */
+export async function readTargetFailureDiagnosis(pipelineDirectory, error) {
+  for (const resultPath of await findNamedFiles(pipelineDirectory, "result.json")) {
+    try {
+      const result = JSON.parse(await readFile(resultPath, "utf8"));
+      const agentText = typeof result?.diagnosis === "string" && result.diagnosis.trim()
+        ? result.diagnosis.trim()
+        : typeof result?.execution?.failure?.reason === "string" && result.execution.failure.reason.trim()
+          ? result.execution.failure.reason.trim()
+          : null;
+      if (agentText) {
+        return { text: redactString(agentText).slice(0, 4_000), source: "execution-agent" };
+      }
+    } catch {
+      // A partial result from one attempt must not hide a valid diagnosis from
+      // another attempt for the same target.
+    }
+  }
+  return {
+    text: redactString(error instanceof Error ? error.message : String(error)).slice(0, 4_000),
+    source: "workflow",
+  };
+}
+
+async function findNamedFiles(root, filename) {
+  const matches = [];
+  async function visit(directory) {
+    for (const entry of await readdir(directory, { withFileTypes: true }).catch(() => [])) {
+      const target = path.join(directory, entry.name);
+      if (entry.isDirectory()) await visit(target);
+      else if (entry.isFile() && entry.name === filename) matches.push(target);
+    }
+  }
+  await visit(root);
+  return matches.sort();
+}

package/src/evidence/parser-registry.mjs

@@ -0,0 +1,54 @@
+import { CiteArkError, safeRelativePath } from "../util.mjs";
+import { fastTextClassificationParser } from "./parsers/fasttext-classification.mjs";
+import { jsonScalarParser } from "./parsers/json-scalar.mjs";
+import { simcseSentevalParser } from "./parsers/simcse-senteval.mjs";
+import { starSpaceClassificationParser } from "./parsers/starspace-classification.mjs";
+
+const PARSERS = new Map(
+  [jsonScalarParser, simcseSentevalParser, fastTextClassificationParser, starSpaceClassificationParser]
+    .map((parser) => [`${parser.id}@${parser.version}`, parser]),
+);
+
+/**
+ * Pure parser capability registry. It does not depend on execution contracts or
+ * research normalization, which keeps protocol validation acyclic.
+ */
+export function registerEvidenceParser(parser) {
+  if (!parser?.id || !parser?.version || typeof parser.parse !== "function") {
+    throw new CiteArkError("证据解析器接口无效");
+  }
+  PARSERS.set(parserKey(parser), parser);
+}
+
+export function listEvidenceParsers() {
+  return [...PARSERS.values()].map(
+    ({ id, version, description, configSchema }) => ({
+      id,
+      version,
+      description,
+      configSchema,
+    }),
+  );
+}
+
+export function getEvidenceParser(descriptor) {
+  return PARSERS.get(parserKey(descriptor));
+}
+
+export function validateEvidenceParserDescriptor(descriptor, measurement = {}) {
+  if (!descriptor || typeof descriptor !== "object") {
+    return ["parser 必须是对象"];
+  }
+  if (!safeRelativePath(descriptor.evidencePath)) {
+    return ["evidencePath 必须是 output 内的安全相对路径"];
+  }
+  const parser = getEvidenceParser(descriptor);
+  if (!parser) {
+    return [`没有注册证据解析器：${descriptor.id}@${descriptor.version}`];
+  }
+  return parser.validateConfig?.(descriptor.config ?? {}, measurement) ?? [];
+}
+
+function parserKey(parser) {
+  return `${parser?.id}@${parser?.version}`;
+}

package/src/evidence/parsers/fasttext-classification.mjs

@@ -0,0 +1,82 @@
+import { CiteArkError } from "../../util.mjs";
+
+export const fastTextClassificationParser = {
+  id: "fasttext.classification.test",
+  version: "1",
+  description: "从 fastText test 的原始 N、P@k、R@k 输出中确定性提取单标签分类准确率。",
+  configSchema: {
+    required: ["expectedExamples"],
+    properties: {
+      expectedExamples: "预期测试样本数，例如 AG News 为 7600",
+      k: "fastText 的 k；默认 1",
+      scale: "从 0-1 比例换算为目标单位的倍率；默认 100",
+    },
+    output: {
+      metric: "test_accuracy",
+      unit: "percentage_points",
+    },
+  },
+  validateConfig(config = {}, measurement = {}) {
+    const issues = [];
+    if (!Number.isInteger(config.expectedExamples) || config.expectedExamples <= 0) {
+      issues.push("config.expectedExamples 必须是正整数");
+    }
+    if (config.k !== undefined && (!Number.isInteger(config.k) || config.k <= 0)) {
+      issues.push("config.k 必须是正整数");
+    }
+    if (config.scale !== undefined && !Number.isFinite(config.scale)) {
+      issues.push("config.scale 必须是有限数值");
+    }
+    if (measurement.metric && measurement.metric !== "test_accuracy") {
+      issues.push("measurement.metric 必须是 test_accuracy");
+    }
+    if (measurement.unit && measurement.unit !== "percentage_points") {
+      issues.push("measurement.unit 必须是 percentage_points");
+    }
+    return issues;
+  },
+  parse(text, config = {}) {
+    const k = config.k ?? 1;
+    const scale = config.scale ?? 100;
+    const examples = integerLine(text, "N");
+    const precision = numericLine(text, `P@${k}`);
+    const recall = numericLine(text, `R@${k}`);
+    if (examples !== config.expectedExamples) {
+      throw new CiteArkError(`fastText 测试样本数不一致：observed=${examples}, expected=${config.expectedExamples}`);
+    }
+    if (precision < 0 || precision > 1 || recall < 0 || recall > 1) {
+      throw new CiteArkError("fastText P@k/R@k 必须位于 0 到 1 之间");
+    }
+    if (Math.abs(precision - recall) > 1e-12) {
+      throw new CiteArkError(`单标签 top-${k} 分类的 P@k 与 R@k 不一致：P=${precision}, R=${recall}`);
+    }
+    const accuracy = precision * scale;
+    return {
+      observations: [
+        { metric: "test_accuracy", value: accuracy, unit: "percentage_points" },
+        { metric: "test_examples", value: examples, unit: "count" },
+      ],
+      primary: { metric: "test_accuracy", value: accuracy, unit: "percentage_points" },
+      checks: [
+        { name: "expected_test_examples", status: "passed", observed: examples, expected: config.expectedExamples },
+        { name: "single_label_precision_recall_consistency", status: "passed", precision, recall, k },
+        { name: "proportion_to_percentage_points", status: "passed", scale, transformedValue: accuracy },
+      ],
+    };
+  },
+};
+
+function integerLine(text, label) {
+  const value = numericLine(text, label);
+  if (!Number.isInteger(value)) throw new CiteArkError(`fastText ${label} 不是整数`);
+  return value;
+}
+
+function numericLine(text, label) {
+  const escaped = label.replaceAll(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const matches = [...text.matchAll(new RegExp(`^\\s*${escaped}\\s+([0-9]+(?:\\.[0-9]+)?)\\s*$`, "gmi"))];
+  if (matches.length !== 1) throw new CiteArkError(`fastText 原始证据必须且只能包含一行 ${label}`);
+  const value = Number(matches[0][1]);
+  if (!Number.isFinite(value)) throw new CiteArkError(`fastText ${label} 不是有限数值`);
+  return value;
+}

package/src/evidence/parsers/json-scalar.mjs

@@ -0,0 +1,96 @@
+import { CiteArkError } from "../../util.mjs";
+
+export const jsonScalarParser = {
+  id: "json.scalar",
+  version: "1",
+  description:
+    "从 JSON Pointer 指向的数值读取原始标量，并可用公开的 scale/offset 做确定性单位换算。",
+  configSchema: {
+    required: ["metric", "unit"],
+    properties: {
+      pointer: "JSON Pointer；默认空字符串表示整个文档",
+      metric: "解析后主指标名称，必须与 experiment measurement.metric 一致",
+      unit: "解析后单位，必须与 experiment measurement.unit 一致",
+      scale: "可选有限数值；parsed = raw * scale + offset，默认 1",
+      offset: "可选有限数值；parsed = raw * scale + offset，默认 0",
+    },
+    example: {
+      pointer: "/accuracy",
+      metric: "accuracy",
+      unit: "percentage_points",
+      scale: 100,
+    },
+  },
+  validateConfig(config = {}, measurement = {}) {
+    const issues = [];
+    if (typeof config.metric !== "string" || !config.metric) {
+      issues.push("config.metric 必须是非空字符串");
+    }
+    if (typeof config.unit !== "string" || !config.unit) {
+      issues.push("config.unit 必须是非空字符串");
+    }
+    if (config.pointer !== undefined && typeof config.pointer !== "string") {
+      issues.push("config.pointer 必须是字符串");
+    }
+    if (config.scale !== undefined && !Number.isFinite(config.scale)) {
+      issues.push("config.scale 必须是有限数值");
+    }
+    if (config.offset !== undefined && !Number.isFinite(config.offset)) {
+      issues.push("config.offset 必须是有限数值");
+    }
+    if (measurement.metric && config.metric !== measurement.metric) {
+      issues.push("config.metric 必须与 measurement.metric 一致");
+    }
+    if (measurement.unit && config.unit !== measurement.unit) {
+      issues.push("config.unit 必须与 measurement.unit 一致");
+    }
+    return issues;
+  },
+  parse(text, config = {}) {
+    let value;
+    try {
+      const document = JSON.parse(text);
+      value = resolvePointer(document, config.pointer ?? "");
+    } catch (error) {
+      throw new CiteArkError(`JSON 标量证据解析失败：${error.message}`, { cause: error });
+    }
+    if (typeof value !== "number" || !Number.isFinite(value)) throw new CiteArkError("JSON 指针没有指向有限数值");
+    const metric = config.metric;
+    const unit = config.unit;
+    if (typeof metric !== "string" || !metric || typeof unit !== "string" || !unit) {
+      throw new CiteArkError("json.scalar parser 需要 config.metric 和 config.unit");
+    }
+    const scale = config.scale ?? 1;
+    const offset = config.offset ?? 0;
+    if (!Number.isFinite(scale) || !Number.isFinite(offset)) {
+      throw new CiteArkError("json.scalar parser 的 scale 和 offset 必须是有限数值");
+    }
+    const rawValue = value;
+    value = rawValue * scale + offset;
+    if (!Number.isFinite(value)) throw new CiteArkError("JSON 标量单位换算后不是有限数值");
+    return {
+      observations: [{ metric, value, unit }],
+      primary: { metric, value, unit },
+      checks: [
+        { name: "finite_scalar", status: "passed", rawValue },
+        {
+          name: "affine_unit_transform",
+          status: "passed",
+          scale,
+          offset,
+          transformedValue: value,
+        },
+      ],
+    };
+  },
+};
+
+function resolvePointer(document, pointer) {
+  if (pointer === "") return document;
+  if (!pointer.startsWith("/")) throw new Error("pointer 必须是 JSON Pointer");
+  return pointer
+    .slice(1)
+    .split("/")
+    .map((part) => part.replaceAll("~1", "/").replaceAll("~0", "~"))
+    .reduce((value, key) => value[key], document);
+}

package/src/evidence/parsers/simcse-senteval.mjs

@@ -0,0 +1,104 @@
+import { CiteArkError } from "../../util.mjs";
+
+export const simcseSentevalParser = {
+  id: "simcse.senteval.sts-table",
+  version: "1",
+  description:
+    "从 SimCSE SentEval 的七项 STS Markdown 汇总表提取分数，并独立复算算术平均值。",
+  configSchema: {
+    required: [],
+    properties: {
+      expectedTasks:
+        "可选任务名数组；默认 STS12-16、STSBenchmark、SICKRelatedness",
+    },
+    output: {
+      metric: "average_spearman",
+      unit: "percentage_points",
+    },
+  },
+  validateConfig(config = {}, measurement = {}) {
+    const issues = [];
+    if (
+      config.expectedTasks !== undefined &&
+      (!Array.isArray(config.expectedTasks) ||
+        config.expectedTasks.length === 0 ||
+        config.expectedTasks.some(
+          (task) => typeof task !== "string" || !task,
+        ))
+    ) {
+      issues.push("config.expectedTasks 必须是非空字符串数组");
+    }
+    if (measurement.metric && measurement.metric !== "average_spearman") {
+      issues.push("measurement.metric 必须是 average_spearman");
+    }
+    if (
+      measurement.unit &&
+      measurement.unit !== "percentage_points"
+    ) {
+      issues.push("measurement.unit 必须是 percentage_points");
+    }
+    return issues;
+  },
+  parse(text, config = {}) {
+    const expectedTasks = config.expectedTasks ?? [
+      "STS12",
+      "STS13",
+      "STS14",
+      "STS15",
+      "STS16",
+      "STSBenchmark",
+      "SICKRelatedness",
+    ];
+    const lines = text.split(/\r?\n/);
+    let headerIndex = -1;
+    let headers = [];
+    for (let index = 0; index < lines.length; index += 1) {
+      const cells = tableCells(lines[index]);
+      if (expectedTasks.every((task) => cells.includes(task)) && cells.some((cell) => /^Avg\.?$/i.test(cell))) {
+        headerIndex = index;
+        headers = cells;
+      }
+    }
+    if (headerIndex < 0) throw new CiteArkError("SimCSE 证据中没有找到七项 STS 汇总表头");
+    const valueLine = lines.slice(headerIndex + 1).find((line) => {
+      const cells = tableCells(line);
+      return cells.length === headers.length && cells.every((cell) => Number.isFinite(Number(cell)));
+    });
+    if (!valueLine) throw new CiteArkError("SimCSE 证据中没有找到 STS 汇总数值行");
+    const values = tableCells(valueLine).map(Number);
+    const byHeader = new Map(headers.map((header, index) => [header.replace(/\.$/, ""), values[index]]));
+    const taskValues = expectedTasks.map((task) => {
+      const value = byHeader.get(task);
+      if (!Number.isFinite(value)) throw new CiteArkError(`SimCSE 汇总表缺少 ${task}`);
+      return { metric: `spearman.${task}`, value, unit: "percentage_points", scope: task };
+    });
+    const printedAverage = byHeader.get("Avg");
+    if (!Number.isFinite(printedAverage)) throw new CiteArkError("SimCSE 汇总表缺少 Avg.");
+    const calculatedAverage = taskValues.reduce((sum, item) => sum + item.value, 0) / taskValues.length;
+    const roundingDifference = Math.abs(calculatedAverage - printedAverage);
+    if (roundingDifference > 0.011) {
+      throw new CiteArkError(`SimCSE Avg. 与七项算术平均不一致：printed=${printedAverage}, calculated=${calculatedAverage}`);
+    }
+    return {
+      observations: [
+        ...taskValues,
+        { metric: "average_spearman", value: printedAverage, unit: "percentage_points", scope: "seven_sts_tasks" },
+      ],
+      primary: { metric: "average_spearman", value: printedAverage, unit: "percentage_points" },
+      checks: [
+        { name: "expected_task_count", status: "passed", observed: taskValues.length, expected: expectedTasks.length },
+        { name: "arithmetic_mean", status: "passed", observed: calculatedAverage, printed: printedAverage, maximumRoundingDifference: 0.011 },
+      ],
+    };
+  },
+};
+
+function tableCells(line) {
+  if (!line.trim().startsWith("|")) return [];
+  return line
+    .trim()
+    .replace(/^\|/, "")
+    .replace(/\|$/, "")
+    .split("|")
+    .map((cell) => cell.trim());
+}

package/src/evidence/parsers/starspace-classification.mjs

@@ -0,0 +1,78 @@
+import { CiteArkError } from "../../util.mjs";
+
+export const starSpaceClassificationParser = {
+  id: "starspace.classification.test",
+  version: "1",
+  description: "从 StarSpace test 的原始 Evaluation Metrics 输出中确定性提取 hit@1 分类准确率。",
+  configSchema: {
+    required: ["expectedExamples"],
+    properties: {
+      expectedExamples: "预期测试样本数，例如 AG News 为 7600",
+      scale: "从 0-1 比例换算为目标单位的倍率；默认 100",
+    },
+    output: {
+      metric: "test_accuracy",
+      unit: "percentage_points",
+    },
+  },
+  validateConfig(config = {}, measurement = {}) {
+    const issues = [];
+    if (!Number.isInteger(config.expectedExamples) || config.expectedExamples <= 0) {
+      issues.push("config.expectedExamples 必须是正整数");
+    }
+    if (config.scale !== undefined && !Number.isFinite(config.scale)) {
+      issues.push("config.scale 必须是有限数值");
+    }
+    if (measurement.metric && measurement.metric !== "test_accuracy") {
+      issues.push("measurement.metric 必须是 test_accuracy");
+    }
+    if (measurement.unit && measurement.unit !== "percentage_points") {
+      issues.push("measurement.unit 必须是 percentage_points");
+    }
+    return issues;
+  },
+  parse(text, config = {}) {
+    const matches = [...text.matchAll(
+      /hit@1:\s*([0-9]+(?:\.[0-9]+)?)\s+hit@10:\s*([0-9]+(?:\.[0-9]+)?)\s+hit@20:\s*([0-9]+(?:\.[0-9]+)?)\s+hit@50:\s*([0-9]+(?:\.[0-9]+)?)\s+mean ranks\s*:\s*([0-9]+(?:\.[0-9]+)?)\s+Total examples\s*:\s*([0-9]+)/gi,
+    )];
+    if (matches.length !== 1) {
+      throw new CiteArkError("StarSpace 原始证据必须且只能包含一组 Evaluation Metrics");
+    }
+    const [, hit1Text, hit10Text, hit20Text, hit50Text, meanRankText, examplesText] = matches[0];
+    const hit1 = Number(hit1Text);
+    const hit10 = Number(hit10Text);
+    const hit20 = Number(hit20Text);
+    const hit50 = Number(hit50Text);
+    const meanRank = Number(meanRankText);
+    const examples = Number(examplesText);
+    const scale = config.scale ?? 100;
+    if (examples !== config.expectedExamples) {
+      throw new CiteArkError(`StarSpace 测试样本数不一致：observed=${examples}, expected=${config.expectedExamples}`);
+    }
+    for (const [name, value] of Object.entries({ hit1, hit10, hit20, hit50 })) {
+      if (!Number.isFinite(value) || value < 0 || value > 1) {
+        throw new CiteArkError(`StarSpace ${name} 必须位于 0 到 1 之间`);
+      }
+    }
+    if (!(hit1 <= hit10 && hit10 <= hit20 && hit20 <= hit50)) {
+      throw new CiteArkError("StarSpace hit@k 不满足随 k 单调不减");
+    }
+    if (!Number.isFinite(meanRank) || meanRank < 1) {
+      throw new CiteArkError("StarSpace mean ranks 必须是不小于 1 的有限数值");
+    }
+    const accuracy = hit1 * scale;
+    return {
+      observations: [
+        { metric: "test_accuracy", value: accuracy, unit: "percentage_points" },
+        { metric: "test_examples", value: examples, unit: "count" },
+        { metric: "mean_rank", value: meanRank, unit: "rank" },
+      ],
+      primary: { metric: "test_accuracy", value: accuracy, unit: "percentage_points" },
+      checks: [
+        { name: "expected_test_examples", status: "passed", observed: examples, expected: config.expectedExamples },
+        { name: "hit_at_k_monotonicity", status: "passed", hit1, hit10, hit20, hit50 },
+        { name: "proportion_to_percentage_points", status: "passed", scale, transformedValue: accuracy },
+      ],
+    };
+  },
+};