World's first open-source enterprise world model.
Rust agent-memorybitemporalgraphragknowledge-baseknowledge-graphllmontologypgvectorpostgresqlragrustself-hostedsemantic-searchtemporal-knowledge-graphworld-model
#!/usr/bin/env node
// 映射探索的测量台(#501):agent 从 schema 提议的口径,对不对、漏了多少。
//
// **打分不看名字,看数。** 治理那边的真值按两个名字键,因为它判的是二分类;
// 这里概念名是模型自己起的,「Revenue」与「已支付 GMV」按名字对不上任何一条。
// 所以真值一条是「一个业务口径 + 一条 gold SQL」,打分把提议真跑一遍,
// 跟 gold 的结果比数——数一样就是同一个口径,叫什么无所谓。
//
// 四栏,含义分开:
// covered 真值 N 条,被至少一条提议算出来的有几条(漏没漏)
// right 提议 K 条,跑得通且对上某条真值的有几条
// wrong **跑得通但一条都对不上**,附它算出的数与最接近的真值
// broken 跑不通(列不存在、语法错)
//
// wrong 是决定 #504 能不能默认开的那个数。跑不通的提议无害,它失败得很响;
// 跑得通而算错的才是全部风险——问数会拿它印出一个看起来完全正常的数字。
//
// 用法:
// node scripts/bench/mappings.mjs --fresh # 新库 → 挂源 → 探索 → 打分
// node scripts/bench/mappings.mjs --fresh --no-comments # 同上,但语料不带列注释
// node scripts/bench/mappings.mjs --kb <id> --score # 只打分,不动库
//
// 环境变量:BENCH_BASE(默认 http://127.0.0.1:8322)、BENCH_EMAIL / BENCH_PASSWORD、
// BENCH_PSQL(默认 docker exec … psql -d utopia -tAc)、
// BENCH_CORPUS_CONN(服务端用来连语料库的连接串)。
import fs from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";
// **判等与连库的那几样住在 lib.mjs,两个测量台共用。** 各写一份 `same()`
// 迟早漂移,而一旦漂移,「提议对了几条」与「答案对了几条」就不是同一把尺子
// 量出来的(#520)
import { api, login, psql, onDb, num, value, same, log, until, sleep, parseArgs } from "./lib.mjs";
const HERE = path.dirname(fileURLToPath(import.meta.url));
const args = parseArgs(process.argv);
const corpusName = args.corpus || "tpch";
const truth = JSON.parse(fs.readFileSync(path.join(HERE, "truth", `${corpusName}.mappings.json`), "utf8"));
const CORPUS_DB = process.env.BENCH_CORPUS_DB || `bench_${corpusName}`;
const CORPUS_CONN = process.env.BENCH_CORPUS_CONN || `postgres://utopia:utopia@localhost:5432/${CORPUS_DB}`;
const corpusPsql = (sql) => onDb(CORPUS_DB, `SET statement_timeout = '20s'; ${sql}`);
// ---------- 语料 ----------
//
// **每一组一个新库**(bench/README 的第一条规则),这里还多一层理由:
// `propose` 的 `ON CONFLICT … WHERE status = 'proposed'` 让第二轮探索
// 继承第一轮的行,同一个库上跑两次,第二次的分不是第二次的。
function loadCorpus() {
const db = CORPUS_DB;
const exists = onDb("postgres", `SELECT 1 FROM pg_database WHERE datname='${db}'`);
if (!exists) {
onDb("postgres", `CREATE DATABASE ${db}`);
log(`建库 ${db}`);
}
corpusPsql(fs.readFileSync(path.join(HERE, "schemas", `${corpusName}.sql`), "utf8"));
// 行可以单独一个文件:`wide` 的建表与造数各自都不短,放一起读不动
const data = path.join(HERE, "schemas", `${corpusName}.data.sql`);
if (fs.existsSync(data)) corpusPsql(fs.readFileSync(data, "utf8"));
log(`${corpusName} 表与行就位`);
// 注释是自变量:不加载就是一份同构但没有注释的语料,两轮之差即注释值多少分
if (!args["no-comments"]) {
corpusPsql(fs.readFileSync(path.join(HERE, "schemas", `${corpusName}.comments.sql`), "utf8"));
log("列注释已加载");
} else {
log("列注释**未**加载(--no-comments)");
}
}
// ---------- 新库 + 挂源 + 探索 ----------
async function fresh() {
loadCorpus();
const ws = (await api("GET", "/api/v1/workspaces"))[0].id;
const stamp = new Date().toISOString().slice(0, 16).replace(/[:T]/g, "-");
const label = args.label || (args["no-comments"] ? "no-comments" : "commented");
const kb = (await api("POST", `/api/v1/workspaces/${ws}/kbs`, { name: `mappings ${corpusName} ${label} ${stamp}` })).id;
await sleep(4000);
// **源名就叫语料名,各轮复用同一个源。**
//
// 第一轮给它起了 `tpch-2026-09-08-12-41`(想让各轮的源并存着比),结果是
// 零提议:`explore_mappings` 拿模型回的 `source` 去比挂载源的名字
// (`eq_ignore_ascii_case`),而模型看着 schema 回的是 `tpch`,对不上就
// 整条 `continue`,十二条一条不剩。任务照样 done,页面上只有一条
// 「没提出来」的告警。**源名是提议能不能落地的隐性依赖**,真实的库里
// 一样会踩——它该进 #503 的覆盖率报告,而不是靠人猜。
const dsName = corpusName;
const existing = (await api("GET", "/api/v1/admin/data-sources")).data_sources.find((d) => d.name === dsName);
const ds = existing?.id
?? (await api("POST", "/api/v1/admin/data-sources", { name: dsName, conn_string: CORPUS_CONN })).id;
await api("PUT", `/api/v1/admin/data-sources/${ds}/grants/${ws}`);
const mounted = await api("PUT", `/api/v1/kbs/${kb}/data-sources/${ds}`);
log(`kb ${kb},源 ${dsName} 已挂载,schema 文档 ${mounted.schema_tables ?? "?"} 张表`);
if (mounted.schema_error) log(` schema 同步报错:${mounted.schema_error}`);
// --also <corpus>:再挂一个源进同一个库(那份语料得已经建好)。两个源、四十多条
// 口径,才撑得爆提示词那个 30 的上限,检索才有得量(#574)
if (args.also && args.also !== true) {
const other = args.also;
const ex = (await api("GET", "/api/v1/admin/data-sources")).data_sources.find((d) => d.name === other);
const dsOther = ex?.id
?? (await api("POST", "/api/v1/admin/data-sources", {
name: other, conn_string: process.env.BENCH_ALSO_CONN || `postgres://utopia:utopia@localhost:5432/bench_${other}`,
})).id;
await api("PUT", `/api/v1/admin/data-sources/${dsOther}/grants/${ws}`);
const m2 = await api("PUT", `/api/v1/kbs/${kb}/data-sources/${dsOther}`);
log(`源 ${other} 也挂上了,schema 文档 ${m2.schema_tables ?? "?"} 张表`);
}
// --conventions:探索之前把真值文件里的约定写进库,它的提示词会读(#570)。
// 这是探索在 wide 上从 0/18 动起来的第一个机会:schema 里没有「测试单不算数」
if (args.conventions) {
if (!truth.conventions?.length) throw new Error(`${corpusName} 的真值里没有 conventions`);
await api("PATCH", `/api/v1/kbs/${kb}`, { data_conventions: truth.conventions.join("\n") });
log(`约定已写进库:${truth.conventions.length} 条`);
}
await api("POST", `/api/v1/kbs/${kb}/data-sources/explore`);
log("探索已入队,等提议落库");
let said = "";
await until(async () => {
const row = psql(`SELECT status || E'\\t' || attempts || E'\\t' || coalesce(left(last_error, 160), '')
FROM jobs WHERE kind='explore_mappings' AND payload->>'kb_id'='${kb}'
ORDER BY id DESC LIMIT 1`);
const [status, attempts, err] = (row || "queued\t0\t").split("\t");
// **任务重试期间就把错话说出来。** 头一轮等满十分钟拿到的是「没有任何进展」,
// 而真正该看见的是「模型密钥解不开」——它第一次失败时就已经写在 last_error 里了
if (err && err !== said) { said = err; log(` 第 ${attempts} 次失败:${err}`); }
if (status === "done" || status === "failed") return true;
return num(`SELECT count(*) FROM concept_mappings WHERE kb_id='${kb}'`);
}, 5000, 600000);
return kb;
}
// ---------- 打分 ----------
const qualify = (t) => (t && t.includes(".") ? t : `${truth.db_schema}.${t}`);
// 提议怎么变成一条能跑的 SQL:给了 sql 就用 sql,否则 expr + table 拼一条。
// 两者都没有就只有 table_name——那不是一个可执行的口径,算 broken。
function proposalSql(m) {
if (m.sql && m.sql.trim()) return m.sql.trim().replace(/;\s*$/, "");
if (m.expr && m.table_name) return `SELECT ${m.expr} FROM ${qualify(m.table_name)}`;
return null;
}
function score(kb) {
const rows = JSON.parse(psql(`SELECT coalesce(json_agg(x), '[]') FROM (
SELECT m.id, e.canonical_name AS concept, t.key AS kind, m.source, m.table_name,
m.expr, m.sql, m.unit, m.status
FROM concept_mappings m
JOIN entities e ON e.id = m.concept_id
JOIN entity_types t ON t.id = e.type_id
WHERE m.kb_id = '${kb}' ORDER BY e.canonical_name) x`));
const gold = truth.metrics.map((m) => ({ ...m, value: value(CORPUS_DB, m.gold).n }));
// 22 条查询没说、但读得懂这个 schema 的人不会反对的口径(退货率、客均余额)。
// **单独一栏,不算对也不算错**——头一轮把退货率记成 wrong,而它没有任何毛病,
// 错的是真值不全。govern.mjs 的 `unlabeled` 是同一件事
const plausible = (truth.plausible || []).map((m) => ({ ...m, value: value(CORPUS_DB, m.gold).n }));
const dimCols = new Set(truth.dimensions.map((d) => d.column.toLowerCase()));
// 列名不带表限定的那一份:同一个维度可能从事实表读,也可能从维表读
// (`shop_nm` 两边都有),而两种都对
const dimNames = new Set([...dimCols].map((c) => c.split(".").pop()));
// 陷阱分角色。**同一列在两个角色下不是同一件事**:`p_size` 当维度是对的
// (Q16 就按它分组),当指标求和才没有意义;`l_comment` 反过来。
// 第三轮上这条把一条正确的维度提议记成了踩陷阱
const trapFor = (role) =>
new Map(
truth.traps
.filter((t) => (t.as ?? "both") === "both" || t.as === role)
.map((t) => [t.column.toLowerCase(), t.why]),
);
const dimTraps = trapFor("dimension");
const trapCols = trapFor("metric");
const c = { right: 0, wrong: 0, broken: 0, traps: 0, plausible: 0, dim_right: 0, dim_wrong: 0 };
const hit = new Set(), wrong = [], broken = [], fair = [];
for (const m of rows) {
// 维度没有数可比:判它指的那一列在不在真值的 group-by 集合里,
// 以及有没有落到陷阱列上(把一个键或一段自由文本当成维度)
if (m.kind === "dimension") {
// **维度不一定是一个裸列名。** 模型给渠道的定义是
// `CASE chnl WHEN 1 THEN 'APP' … END`——把码翻译成人看的名字,这正是
// 一个维度该做的事。只认裸列名的话,三条正确的提议被判成错的(wide 第一轮)。
// 所以从表达式里把标识符抽出来,命中任一真值维度列即算数
const table = qualify(m.table_name).toLowerCase();
const ids = (m.expr || "").toLowerCase().match(/[a-z_][a-z0-9_]*/g) ?? [];
const col = ids.find((id) => dimCols.has(`${table}.${id}`) || dimNames.has(id))
?? `${table}.${(m.expr || "").replace(/[^\w.]/g, "")}`.toLowerCase();
if (dimCols.has(col) || dimNames.has(col.split(".").pop())) c.dim_right++;
else { c.dim_wrong++; wrong.push(`dim "${m.concept}" → ${col}${dimTraps.has(col) ? ` **trap: ${dimTraps.get(col)}**` : ""}`); }
if (dimTraps.has(col)) c.traps++;
continue;
}
const sql = proposalSql(m);
if (!sql) { c.broken++; broken.push(`"${m.concept}" 没有可执行的定义(只有 table_name=${m.table_name})`); continue; }
const got = value(CORPUS_DB, sql);
if (got.error) { c.broken++; broken.push(`"${m.concept}" → ${got.error}`); continue; }
if (got.empty) { c.broken++; broken.push(`"${m.concept}" 返回空`); continue; }
const matched = gold.filter((g) => same(g.value, got.n));
if (matched.length) { c.right++; matched.forEach((g) => hit.add(g.id)); continue; }
const plaus = plausible.find((g) => same(g.value, got.n));
if (plaus) { c.plausible++; fair.push(`"${m.concept}" = ${plaus.id} (${plaus.label})`); continue; }
c.wrong++;
// 最接近的真值:告诉人这条错在哪个方向,而不是只说它错了
const near = gold
.filter((g) => Number.isFinite(g.value))
.sort((a, b) => Math.abs(a.value - got.n) - Math.abs(b.value - got.n))[0];
const trap = [...trapCols.keys()].find((k) => (m.expr || "").toLowerCase().includes(k.split(".").pop()));
if (trap) c.traps++;
wrong.push(
`"${m.concept}" = ${sql}\n 算出 ${got.n},最近的真值 ${near?.id} = ${near?.value}` +
(trap ? `\n **trap: ${trapCols.get(trap)}**` : ""),
);
}
const pct = (a, b) => (b ? `${Math.round((a / b) * 100)}%` : "—");
const missed = gold.filter((g) => !hit.has(g.id));
// **那一轮带没带注释,问库名而不是问命令行参数。** `--score` 重打一次分时
// 命令行上没有 `--no-comments`,照参数写就把不带注释的那轮报成带注释的
const kbName = psql(`SELECT name FROM knowledge_bases WHERE id = '${kb}'`);
const out = {
kb, corpus: corpusName,
comments: !kbName.includes("no-comments"),
proposals: rows.length,
metrics: { right: c.right, plausible: c.plausible, wrong: c.wrong, broken: c.broken },
dimensions: { right: c.dim_right, wrong: c.dim_wrong },
covered: `${hit.size}/${gold.length} (${pct(hit.size, gold.length)})`,
traps_hit: c.traps,
};
console.log(JSON.stringify(out, null, 2));
if (fair.length) console.log("\nPLAUSIBLE — 22 条查询没说,但站得住的口径\n " + fair.join("\n "));
if (wrong.length) console.log("\nWRONG — 跑得通,算的不是任何一条真值\n " + wrong.join("\n "));
if (broken.length) console.log("\nBROKEN — 跑不通(无害,人一眼看得见)\n " + broken.join("\n "));
if (missed.length) console.log("\nMISSED — 真值里没人提的口径\n " + missed.map((g) => `${g.id} (${g.label})`).join("\n "));
}
// ---------- 主流程 ----------
const main = async () => {
await login();
const kb = args.kb && args.kb !== true ? args.kb : await fresh();
score(kb);
};
main().catch((e) => { console.error(e); process.exit(1); });