@clize/clize 0.28.1 → 0.29.1

package/dist/core/seo.js

@@ -7,8 +7,9 @@ import { readTraffic } from "./seo-traffic.js";
 /** 对客加价:成本 × (1 + 4) = ×5。刻意不复用 platform.billing.markupPct(0.2)——
  *  那是给域名 / 媒体等大额供给定的,套在美分级数据上会让定价失真(一次 serp 收 8 厘)。 */
 export const SEO_MARKUP_PCT = 4;
-/** 无 domain 归属的查询(keywords/competitors/serp)按租户走的月度兜底。
- *  有 domain 的路径(PR2 的 check)用 seo_domains.budget_monthly_usd,同一个默认值。 */
+/** 租户月度上限的**出厂值**($5)。它是防意外累计的兜底,不是产品的定价上界 ——
+ *  用户随时可用任一条 seo 命令的 `--cap <usd>` 自助上调(`tenants.seo_budget_monthly_usd`)。
+ *  单域配额(seo_domains.budget_monthly_usd)沿用同一个出厂值,两堵墙各管各的。 */
 export const SEO_BUDGET_DEFAULT_USD = 5;
 /** 缓存 TTL:词/竞品指标月更口径 30 天;结果页时效短,7 天。 */
 const TTL_DAYS = { keywords: 30, competitors: 30, serp: 7 };
@@ -40,7 +41,9 @@ export function chargedForSeo(upstreamCostUsd) {
     return Number((upstreamCostUsd * (1 + SEO_MARKUP_PCT)).toFixed(4));
 }
 export function keywordBand(sv, kd) {
-    if (sv === null || sv === 0)
+    if (sv === null)
+        return "no_data";
+    if (sv === 0)
         return "no_volume";
     if (kd === null)
         return "stretch"; // 有量但上游没给 KD:落中档,不假装知道
@@ -50,8 +53,14 @@ export function keywordBand(sv, kd) {
         return "stretch";
     return "wall";
 }
-/** 行动优先级排序:能打的在前(低 KD 优先,同档大量优先),无量的沉底。 */
-const BAND_ORDER = { attackable: 0, stretch: 1, wall: 2, no_volume: 3 };
+/** 行动优先级排序:能打的在前(低 KD 优先,同档大量优先),无量的沉底,一无所知的最底。 */
+const BAND_ORDER = {
+    attackable: 0,
+    stretch: 1,
+    wall: 2,
+    no_volume: 3,
+    no_data: 4,
+};
 // ---------------- 计费与预算 ----------------
 /** 本月该租户(可选:限定 domain)的 seo 支出,口径 = 用户实付额。 */
 export async function seoSpentThisMonth(db, tenantId, domain) {
@@ -65,26 +74,104 @@ export async function seoSpentThisMonth(db, tenantId, domain) {
         .first();
     return row?.s ?? 0;
 }
-/** 预算闸:超了给 429 + 解法(免逐次 confirm 的对价是花钱透明 + 有上限兜底)。 */
-export async function assertSeoBudget(ctx, db, opts = {}) {
-    const domain = opts.domain;
-    let cap = SEO_BUDGET_DEFAULT_USD;
-    if (domain) {
-        const row = await db
-            .prepare("SELECT budget_monthly_usd FROM seo_domains WHERE domain=? AND tenant_id=?")
-            .bind(domain, ctx.tenantId)
-            .first();
-        if (row?.budget_monthly_usd != null)
-            cap = Number(row.budget_monthly_usd);
+// ── 预算体系(0.29.0 重做;三处旧行为都被 2026-08-31 的 kunavo dogfood 打脸)
+//
+//  ① **墙可以自助推**。旧的租户墙是代码常量 + 报错指路 "contact support" —— 一条死路,
+//     而这是个自助产品。改成 `tenants.seo_budget_monthly_usd`,任何一条 seo 命令带
+//     `--cap <usd>` 即改(**带这个 flag 本身就是知情同意**,不再多一道 confirm)。
+//     刻意**不**新开 `seo budget` 命令:它在被砍清单里(产品文档 §2.2),而"改一个上限"
+//     不值得一条顶级命令 —— 挂在花钱的命令上,恰好也是撞墙时手边就有的那条路。
+//  ② **两堵墙都真的生效,配高的那个不架空另一个**。租户墙(所有 seo 花费)与单域配额
+//     (seo_domains.budget_monthly_usd,只管该域的 check)是两回事。旧实现里
+//     `--budget 15` 配在租户 $5 之下,读起来像 $15 可花,实际 $5 就被拦 —— 撒谎的配置。
+//     现在两个数都返回给调用方,单域配额超过租户墙时明说「你会先撞租户墙」。
+//  ③ **闸前置到"这次要花的钱"上**。旧闸是 `spent < cap` 即放行:$4.99 时放进一次
+//     $1.20 的调用 → 实测 $6.17/$5.00,超额 23% 才拦。现在按 op 估一个上限,
+//     `spent + 估算 > cap` 就拒 —— **估算只用于闸,计费仍按响应里的真实 cost**。
+/** 一次调用的**上游成本估算上限**(美元)。数字来自 2026-08-30 sandbox 实测
+ *  (design/seo-geo-impl.md §9:keyword_overview 10 词 $0.01296 · ai_keyword_data 10 词
+ *  $0.0110 · ranked_keywords limit=20 $0.0144 · bulk_traffic 3 域 $0.01236 ·
+ *  serp depth=20 $0.0040 / depth=100 $0.020),各项取略高于实测的线性模型。
+ *  **只用于前置闸**:估高一点会早拦一次,估低会让墙漏一点点 —— 前者可自助推墙,后者是旧 bug。 */
+export function estimateSeoCost(op, n = {}) {
+    const kw = n.keywords ?? 0;
+    switch (op) {
+        case "keywords":
+            return 0.011 + 0.0002 * kw;
+        case "keywords+ai":
+            return 0.011 + 0.0002 * kw + (0.01 + 0.0001 * kw);
+        case "competitors": {
+            const d = n.domains ?? 1;
+            return 0.011 + 0.0005 * d + d * (0.011 + 0.0002 * (n.limit ?? RANKED_KEYWORDS_LIMIT));
+        }
+        case "serp":
+            return 0.0002 * (n.depth ?? SERP_DEPTH);
     }
-    const spent = await seoSpentThisMonth(db, ctx.tenantId, domain);
-    if (spent < cap)
+}
+/** 读租户墙:tenants 列有值用它,没有(或没这行)用默认 $5。 */
+export async function tenantSeoCap(db, tenantId) {
+    const row = await db
+        .prepare("SELECT seo_budget_monthly_usd AS cap FROM tenants WHERE id=?")
+        .bind(tenantId)
+        .first();
+    return row?.cap == null ? SEO_BUDGET_DEFAULT_USD : Number(row.cap);
+}
+/** 自助上调/下调租户墙。带 `--cap` 走到这里 —— 动作本身即知情同意,不再多一道闸。 */
+export async function setTenantSeoCap(db, tenantId, usd) {
+    if (!Number.isFinite(usd) || usd < 0)
+        throw new ClizeError(`--cap must be a non-negative number of dollars, got "${usd}"`, 400);
+    const cap = Number(usd.toFixed(2));
+    // 租户行由注册流程建;这里只更新,不 upsert(没有行 = 没有这个租户,不该被一个 flag 造出来)。
+    // 改不到就报错,**绝不静默无视** —— 一个说了不算的 --cap 正是这次要修掉的那类撒谎配置。
+    const r = (await db
+        .prepare("UPDATE tenants SET seo_budget_monthly_usd=?, updated_at=? WHERE id=?")
+        .bind(cap, new Date().toISOString(), tenantId)
+        .run());
+    if (r?.meta?.changes === 0)
+        throw new ClizeError(`cannot set seo cap: no such tenant ${tenantId}`, 404);
+    return cap;
+}
+export async function seoBudgetState(db, tenantId) {
+    const capUsd = await tenantSeoCap(db, tenantId);
+    const spentThisMonth = Number((await seoSpentThisMonth(db, tenantId)).toFixed(4));
+    return {
+        capUsd,
+        spentThisMonth,
+        remainingUsd: Number(Math.max(0, capUsd - spentThisMonth).toFixed(4)),
+    };
+}
+/** 撞墙时给的自助路径 —— 具体到可以直接跑的一行,不是 "contact support"。 */
+function raiseHint(cap, needMore) {
+    const suggest = Math.max(Math.ceil(cap * 2), Math.ceil(cap + needMore + 1));
+    return `raise it yourself and re-run: add \`--cap ${suggest}\` to any \`clize seo\` command (passing --cap is the consent; it sets this tenant's monthly seo cap)`;
+}
+/** 预算闸(**前置**):这次要花的钱放不进剩余额度就拒,不等超支了才拦。
+ *
+ *  两层依次过:先租户墙(所有花费),再单域配额(有 domain 的路径)。
+ *  `estimateUsd` = 本次上游成本估算(未加价);闸按对客价算 —— 用户看到的墙是对客金额。 */
+export async function assertSeoBudget(ctx, db, opts = {}) {
+    const need = chargedForSeo(opts.estimateUsd ?? 0);
+    const cap = await tenantSeoCap(db, ctx.tenantId);
+    const spent = await seoSpentThisMonth(db, ctx.tenantId);
+    // 两个条件都要:已经吃满就拒(哪怕这次估算是 0),以及"这次要花的放不进剩余额度"就拒。
+    if (spent >= cap || spent + need > cap)
+        throw new ClizeError(`monthly seo cap reached: $${spent.toFixed(2)} spent of $${cap.toFixed(2)}` +
+            (need > 0 ? `, and this call needs about $${need.toFixed(2)}` : "") +
+            `. ${raiseHint(cap, need)}`, 429);
+    if (!opts.domain)
         return;
-    const scope = domain ? `for ${domain}` : "this month";
-    const raise = domain
-        ? `clize seo check --domain ${domain} --budget ${Math.ceil(cap * 2)}`
-        : "top up the cap by contacting support (per-domain budgets are set by `clize seo check --budget`)";
-    throw new ClizeError(`monthly seo budget reached ${scope}: $${spent.toFixed(2)} of $${cap.toFixed(2)}. raise: ${raise}`, 429);
+    const row = await db
+        .prepare("SELECT budget_monthly_usd FROM seo_domains WHERE domain=? AND tenant_id=?")
+        .bind(opts.domain, ctx.tenantId)
+        .first();
+    if (row?.budget_monthly_usd == null)
+        return;
+    const dCap = Number(row.budget_monthly_usd);
+    const dSpent = await seoSpentThisMonth(db, ctx.tenantId, opts.domain);
+    if (dSpent >= dCap || dSpent + need > dCap)
+        throw new ClizeError(`monthly seo budget reached for ${opts.domain}: $${dSpent.toFixed(2)} of $${dCap.toFixed(2)}` +
+            (need > 0 ? `, and this call needs about $${need.toFixed(2)}` : "") +
+            `. raise it with \`clize seo check --domain ${opts.domain} --budget ${Math.ceil(dCap * 2)}\``, 429);
 }
 /** 扣费 + 入账(缓存命中不扣、不入账,ledger 里就不会出现一条 $0 噪音行)。 */
 async function chargeSeo(ctx, op, upstreamCostUsd, detail = {}) {
@@ -138,12 +225,19 @@ export async function keywords(ctx, db, opts) {
     if (seeds.length > KEYWORDS_PER_CALL)
         throw new ClizeError(`too many keywords (${seeds.length}); max ${KEYWORDS_PER_CALL} per call`, 400);
     const { tag, codes } = resolveLocale(opts.locale);
+    if (opts.capUsd !== undefined)
+        await setTenantSeoCap(db, ctx.tenantId, opts.capUsd);
     const op = opts.ai ? "keywords+ai" : "keywords";
     const key = await cacheKey(op, seeds.slice().sort().join("|"), tag);
     const cached = await readCache(db, ctx.tenantId, key, TTL_DAYS.keywords);
     if (cached)
-        return { locale: tag, keywords: cached, charged: { usd: 0, cacheHit: true } };
-    await assertSeoBudget(ctx, db);
+        return {
+            locale: tag,
+            keywords: cached,
+            charged: { usd: 0, cacheHit: true },
+            budget: await seoBudgetState(db, ctx.tenantId),
+        };
+    await assertSeoBudget(ctx, db, { estimateUsd: estimateSeoCost(op, { keywords: seeds.length }) });
     const api = client(ctx);
     const base = await api.keywordOverview(seeds, codes);
     let cost = base.costUsd;
@@ -169,9 +263,10 @@ export async function keywords(ctx, db, opts) {
         (b.sv ?? 0) - (a.sv ?? 0));
     await writeCache(db, ctx.tenantId, key, rows, cost);
     const charged = await chargeSeo(ctx, op, cost, { keywords: seeds.length, locale: tag });
-    return { locale: tag, keywords: rows, charged };
+    return { locale: tag, keywords: rows, charged, budget: await seoBudgetState(db, ctx.tenantId) };
 }
-/** 竞品反查:一次问多个域的流量画像 + 每个域靠什么词活。 */
+/** 竞品反查:一次问多个域的流量画像 + 每个域靠什么词活。
+ *  **这是命令面里唯一的词源命令**(反查出来的 topKeywords 就是候选种子);判读见 skill §6。 */
 export async function competitors(ctx, db, opts) {
     const domains = [...new Set(opts.domains.map(normalizeHost).filter(Boolean))];
     if (!domains.length)
@@ -180,11 +275,20 @@ export async function competitors(ctx, db, opts) {
         throw new ClizeError(`too many domains (${domains.length}); max 10`, 400);
     const { tag, codes } = resolveLocale(opts.locale);
     const limit = Math.min(Math.max(opts.limit ?? RANKED_KEYWORDS_LIMIT, 1), 100);
+    if (opts.capUsd !== undefined)
+        await setTenantSeoCap(db, ctx.tenantId, opts.capUsd);
     const key = await cacheKey(`competitors:${limit}`, domains.slice().sort().join("|"), tag);
     const cached = await readCache(db, ctx.tenantId, key, TTL_DAYS.competitors);
     if (cached)
-        return { locale: tag, competitors: cached, charged: { usd: 0, cacheHit: true } };
-    await assertSeoBudget(ctx, db);
+        return {
+            locale: tag,
+            competitors: cached,
+            charged: { usd: 0, cacheHit: true },
+            budget: await seoBudgetState(db, ctx.tenantId),
+        };
+    await assertSeoBudget(ctx, db, {
+        estimateUsd: estimateSeoCost("competitors", { domains: domains.length, limit }),
+    });
     const api = client(ctx);
     const traffic = await api.bulkTraffic(domains, codes);
     let cost = traffic.costUsd;
@@ -211,7 +315,7 @@ export async function competitors(ctx, db, opts) {
     rows.sort((a, b) => (b.etv ?? 0) - (a.etv ?? 0));
     await writeCache(db, ctx.tenantId, key, rows, cost);
     const charged = await chargeSeo(ctx, "competitors", cost, { domains: domains.length, locale: tag });
-    return { locale: tag, competitors: rows, charged };
+    return { locale: tag, competitors: rows, charged, budget: await seoBudgetState(db, ctx.tenantId) };
 }
 /** 结果页真相:自然结果 + 占位判定 + 寄生目标。 */
 export async function serp(ctx, db, opts) {
@@ -220,11 +324,17 @@ export async function serp(ctx, db, opts) {
         throw new ClizeError("no keyword given", 400);
     const { tag, codes } = resolveLocale(opts.locale);
     const depth = Math.min(Math.max(opts.depth ?? SERP_DEPTH, 10), 100);
+    if (opts.capUsd !== undefined)
+        await setTenantSeoCap(db, ctx.tenantId, opts.capUsd);
     const key = await cacheKey(`serp:${depth}`, keyword, tag);
     const cached = await readCache(db, ctx.tenantId, key, TTL_DAYS.serp);
     if (cached)
-        return { ...cached, charged: { usd: 0, cacheHit: true } };
-    await assertSeoBudget(ctx, db);
+        return {
+            ...cached,
+            charged: { usd: 0, cacheHit: true },
+            budget: await seoBudgetState(db, ctx.tenantId),
+        };
+    await assertSeoBudget(ctx, db, { estimateUsd: estimateSeoCost("serp", { depth }) });
     const { result: page, costUsd } = await client(ctx).serpLiveAdvanced(keyword, codes, depth);
     const classified = classifySerp(keyword, page.items);
     const payload = {
@@ -246,7 +356,32 @@ export async function serp(ctx, db, opts) {
     };
     await writeCache(db, ctx.tenantId, key, payload, costUsd);
     const charged = await chargeSeo(ctx, "serp", costUsd, { keyword, locale: tag });
-    return { ...payload, charged };
+    return { ...payload, charged, budget: await seoBudgetState(db, ctx.tenantId) };
+}
+/** `pre_emergence` 要求的最低曝光:低于此量与噪声不可分(同 GSC 新词回填的阈值口径)。 */
+const SIGNAL_MIN_IMPRESSIONS = 10;
+/** `authority_limited` 要求的曝光量级 —— 少量曝光 + 零点击只是没人搜,不是授权度问题。 */
+const AUTHORITY_LIMITED_MIN_IMPRESSIONS = 50;
+/** `authority_limited` 的位次下界(GSC 均位次)。50+ 基本落在第 5 页之后,点击天然趋零。 */
+const AUTHORITY_LIMITED_MIN_POSITION = 50;
+/** `demand_no_surface` 要求的最低搜索量:量表报个位数的词本来就可能整月零曝光。 */
+const DEMAND_NO_SURFACE_MIN_SV = 50;
+/** `signals` 里最多留几条 `demand_no_surface`。**这条形态在冷启动站上是常态不是意外**
+ *  ——0.29.0 发布日对 clize.ai 实测:18 条 signals 里 17 条是它,一份"每行都说同一句话"
+ *  的清单不是压缩,是把词表又抄了一遍。另两个形态是真稀有,不设上限。
+ *  被截掉的词不会消失:它们本来就全在 `rank.unseen` 里,notes 说明还有多少条。 */
+const DEMAND_NO_SURFACE_MAX = 5;
+/** 形态判定:纯函数、纯阈值,给定同样三个数字永远给同样的答案(agent 可自行复核)。 */
+export function signalForm(a) {
+    if (a.position === null)
+        return a.sv !== null && a.sv >= DEMAND_NO_SURFACE_MIN_SV ? "demand_no_surface" : null;
+    if (a.sv === 0 && a.impressions >= SIGNAL_MIN_IMPRESSIONS)
+        return "pre_emergence";
+    if (a.clicks === 0 &&
+        a.impressions >= AUTHORITY_LIMITED_MIN_IMPRESSIONS &&
+        a.position >= AUTHORITY_LIMITED_MIN_POSITION)
+        return "authority_limited";
+    return null;
 }
 /** GSC 窗口重拉的天数:Google 会事后修正近日数据,固定重拉最近 N 天并替换。 */
 const GSC_WINDOW_DAYS = 30;
@@ -305,11 +440,84 @@ async function upsertDomain(ctx, db, domain, cfg) {
 }
 async function readKeywords(db, domain) {
     const { results } = await db
-        .prepare("SELECT keyword, sv, kd, source FROM seo_keywords WHERE domain=? ORDER BY id")
+        .prepare("SELECT keyword, locale, sv, kd, ai_sv, cpc, source, last_refreshed_at FROM seo_keywords WHERE domain=? ORDER BY id")
         .bind(domain)
         .all();
     return results;
 }
+/** 词表指标多久算过期(与 keywords 命令的缓存 TTL 同口径:SV/KD 是月更的量)。 */
+const METRICS_TTL_DAYS = TTL_DAYS.keywords;
+/** 一轮 check 最多给多少个词补指标。上限存在只为拦住"回填炸了词表"这种意外
+ *  ——正常一轮是几十个词、几美分;真要更大的词表就分几轮,或先跑 `seo keywords`。 */
+const METRICS_PER_CHECK = 200;
+/** `sv/kd/ai_sv/cpc/last_refreshed_at` 五列此前是死列(没有任何写入点),于是
+ *  `byBand` 对任何词表都恒为 `{no_volume: N}` —— 恒真且误导(2026-08-31 线上首轮 check 暴露)。
+ *  出路选了产品文档 §12.2 的①:**check 顺带把缺指标的词批量取一次并写回**。
+ *
+ *  这让 check 从"恒免费"变成"有时花几美分",换来的是 byBand 有真实分布、
+ *  以及交叉层(§signals)有 sv 这一源可比 —— 没有它,check 只有 GSC 一个源,
+ *  "三源并排"少一条腿。计费口径**沿用既有规则,不新造**:
+ *   · 词表自己就是缓存 —— `last_refreshed_at` 在 30 天内的词不重取、不重复计费;
+ *   · 未命中的按 `keywords` 端点如实入账(op="keywords",detail 带 domain)。
+ *  预算不够时**不中断 check**:跳过补指标、记 note —— GSC/流量两段是免费的,
+ *  不该被一次几美分的可选动作拖垮。 */
+async function refreshKeywordMetrics(ctx, db, domain, rows, notes, now) {
+    const cutoff = now - METRICS_TTL_DAYS * DAY_MS;
+    const stale = rows.filter((r) => {
+        const t = r.last_refreshed_at ? Date.parse(r.last_refreshed_at) : NaN;
+        return !Number.isFinite(t) || t < cutoff;
+    });
+    if (!stale.length)
+        return { usd: 0, cacheHit: true };
+    if (stale.length > METRICS_PER_CHECK)
+        notes.push(`keywords: ${stale.length} words need metrics — pricing the first ${METRICS_PER_CHECK} this round, the rest on the next check`);
+    const todo = stale.slice(0, METRICS_PER_CHECK);
+    // 按 locale 分组:上游按 (location, language) 问量,混着问会给错市场的数字。
+    const byLocale = new Map();
+    for (const r of todo) {
+        const tag = r.locale || DEFAULT_LOCALE;
+        byLocale.set(tag, [...(byLocale.get(tag) ?? []), r.keyword]);
+    }
+    let cost = 0;
+    let priced = 0;
+    const stamp = new Date(now).toISOString();
+    for (const [tag, words] of byLocale) {
+        let codes;
+        try {
+            codes = resolveLocale(tag).codes;
+        }
+        catch {
+            notes.push(`keywords: skipped ${words.length} word(s) in unsupported locale "${tag}"`);
+            continue;
+        }
+        for (let i = 0; i < words.length; i += KEYWORDS_PER_CALL) {
+            const batch = words.slice(i, i + KEYWORDS_PER_CALL);
+            try {
+                await assertSeoBudget(ctx, db, {
+                    domain,
+                    estimateUsd: estimateSeoCost("keywords", { keywords: batch.length }),
+                });
+                const { result, costUsd } = await client(ctx).keywordOverview(batch, codes);
+                cost += costUsd;
+                await writeAll(db, result.map((m) => db
+                    .prepare("UPDATE seo_keywords SET sv=?, kd=?, cpc=?, last_refreshed_at=? WHERE domain=? AND keyword=? AND locale=?")
+                    .bind(m.sv, m.kd, m.cpc, stamp, domain, m.keyword, tag)));
+                priced += batch.length;
+            }
+            catch (e) {
+                // 预算不够 / 上游抽风 / 没配凭证 —— 都只让这一段降级,不毁掉整轮免费测量。
+                notes.push(`keywords: metrics not refreshed (${e instanceof Error ? e.message : String(e)})`);
+                break; // 同一 locale 的后续批次没必要再撞同一堵墙
+            }
+        }
+    }
+    // cost=0 但走到这里 = 试过而没成(预算/上游/凭证),不是"缓存命中"——别把失败报成免费命中。
+    if (!cost)
+        return { usd: 0, cacheHit: false };
+    const charged = await chargeSeo(ctx, "keywords", cost, { domain, keywords: priced, via: "check" });
+    notes.push(`keywords: priced ${priced} word(s) this round ($${charged.usd.toFixed(4)}); metrics are reused for ${METRICS_TTL_DAYS} days, so a re-run costs nothing`);
+    return charged;
+}
 /** 词表:--keywords 是**全量替换**(保留已有行的指标),不带则读已存的。 */
 async function syncKeywords(db, domain, keywords, now) {
     if (keywords) {
@@ -336,7 +544,10 @@ export async function checkOne(ctx, db, domain0, cfg = {}, now = Date.now()) {
     const domain = normalizeHost(domain0.replace(/^https?:\/\//, "").split("/")[0] ?? "");
     if (!domain)
         throw new ClizeError("no domain: pass --domain or run inside a clize project", 400);
-    // 预算闸刻意不在这里:check 不打上游数据源,没有可花的钱。花钱的是查询三条。
+    // 预算闸不拦整轮 check:测量两段是免费的,不该被一次几美分的可选动作拖垮。
+    // 闸在 refreshKeywordMetrics 里前置到那一次上游调用上(超了就跳过补指标 + 记 note)。
+    if (cfg.capUsd !== undefined)
+        await setTenantSeoCap(db, ctx.tenantId, cfg.capUsd);
     const ranAt = new Date(now).toISOString();
     const win = measureWindow(now);
     const conf = await upsertDomain(ctx, db, domain, cfg);
@@ -364,8 +575,10 @@ export async function checkOne(ctx, db, domain0, cfg = {}, now = Date.now()) {
             .run();
     // ── GSC(唯一的搜索面)。拿不到不中断整轮 —— 给 null + hint。
     const gsc = await gscSection(ctx, db, domain, conf, kwRows, notes, win, now);
-    // ── 位次:词表 join 刚落库的 GSC 明细。零上游调用、零成本。
-    //    回填可能刚往词表里加了词,所以重新读一次 —— 否则 total 会漏掉本轮的新发现。
+    // ── 补指标:回填可能刚往词表里加了词,所以先重读一次(否则 total 会漏掉本轮的新发现),
+    //    再把缺指标 / 指标过期的词批量取一次写回。**这是 check 唯一可能花钱的一步**,
+    //    30 天内重跑不重复取、不重复计费;预算不够就跳过并记 note,不毁掉免费的两段。
+    const charged = await refreshKeywordMetrics(ctx, db, domain, await readKeywords(db, domain), notes, now);
     const kwAll = await readKeywords(db, domain);
     const tracked = kwAll.filter((k) => k.source !== "gsc_backfill");
     let rank = null;
@@ -374,13 +587,14 @@ export async function checkOne(ctx, db, domain0, cfg = {}, now = Date.now()) {
     else if (!tracked.length)
         notes.push("no keyword list yet — pass --keywords a,b,c to start tracking positions");
     else
-        rank = await rankSection(db, domain, tracked, win);
-    // byBand 只统计**取过指标**的词:sv 为空是「没问过量」,不是「没有量」——
-    // 把它算进 no_volume 会让分桶恒真且误导(2026-08-31 线上首轮 check 暴露)。
+        rank = await rankSection(db, domain, tracked, win, notes);
+    // byBand 只统计**问过量**的词(`last_refreshed_at` 非空)。没问过 ≠ 没有量:
+    // 把没问过的算进 no_volume 会让分桶恒真且误导(2026-08-31 线上首轮 check 暴露)。
+    // 问过而上游没给行的词落 `no_data` —— 那是如实的"查无此词",与 `no_volume`(量确实是 0)分开。
     const byBand = {};
     let unpriced = 0;
     for (const k of kwAll) {
-        if (k.sv === null) {
+        if (!k.last_refreshed_at && k.sv === null) {
             unpriced++;
             continue;
         }
@@ -388,21 +602,26 @@ export async function checkOne(ctx, db, domain0, cfg = {}, now = Date.now()) {
         byBand[b] = (byBand[b] ?? 0) + 1;
     }
     if (unpriced)
-        notes.push(`keywords: no metrics on file for ${unpriced} of ${kwAll.length} — byBand counts only priced keywords (the saved list stores words, not metrics)`);
-    const spent = await seoSpentThisMonth(db, ctx.tenantId);
+        notes.push(`keywords: no metrics on file for ${unpriced} of ${kwAll.length} — byBand counts only priced keywords (see the note above for why they were skipped)`);
+    const cap = await tenantSeoCap(db, ctx.tenantId);
+    const spent = Number((await seoSpentThisMonth(db, ctx.tenantId)).toFixed(4));
+    const remaining = Number(Math.max(0, cap - spent).toFixed(4));
+    // 单域配额配得比租户墙高 = 会先撞租户墙。旧版只报单域数字,读起来像那个数可花 —— 撒谎的配置。
+    if (conf.budget_monthly_usd > cap)
+        notes.push(`budget: this domain's cap is $${conf.budget_monthly_usd.toFixed(2)}, but the tenant-wide monthly seo cap is $${cap.toFixed(2)} ($${remaining.toFixed(2)} left) — you will hit the tenant cap first. Raise it with \`--cap <usd>\` on any \`clize seo\` command.`);
     return {
         domain,
         brand: conf.brand,
         competitors,
         ranAt,
-        budget: { monthlyUsd: conf.budget_monthly_usd, spentThisMonth: Number(spent.toFixed(4)) },
+        budget: { monthlyUsd: conf.budget_monthly_usd, spentThisMonth: spent, capUsd: cap, remainingUsd: remaining },
         keywords: { total: kwAll.length, byBand, tracked: tracked.length },
         rank,
         traffic,
         gsc,
         notes,
-        // check 免费:两个数据源都是自有的(GSC service account + 自家 CF RUM)。
-        charged: { usd: 0, cacheHit: false },
+        // 测量本身是免费的(GSC service account + 自家 CF RUM);花的只可能是补词指标那一步。
+        charged,
     };
 }
 /** 按 query 聚合一段窗口的 GSC 明细。位次 = **曝光加权均值**(GSC 自己的 average position 口径)。 */
@@ -426,21 +645,27 @@ async function aggregateGsc(db, domain, from, to) {
     return out;
 }
 /** 位次段:词表 join GSC 明细。纯 D1 读,零上游调用。 */
-async function rankSection(db, domain, tracked, win) {
+async function rankSection(db, domain, tracked, win, notes) {
     const cur = await aggregateGsc(db, domain, win.from, win.to);
     const prev = await aggregateGsc(db, domain, win.prevFrom, win.prevTo);
     const wanted = new Set(tracked.map((k) => k.keyword));
     const series = await weeklySeries(db, domain, wanted, win.to);
     const latest = [];
     const unseen = [];
+    const signals = [];
     for (const k of tracked) {
         const a = cur.get(k.keyword);
         if (!a) {
             // GSC 本窗口没见过这个词。**只列名,零成本** —— 对它做深抓只会一遍遍确认「仍未见」。
             unseen.push(k.keyword);
+            // 但"量表说有需求 × Google 一次曝光都没给"本身是个形态,不该只当空行。
+            const form = signalForm({ sv: k.sv, position: null, impressions: 0, clicks: 0 });
+            if (form)
+                signals.push({ keyword: k.keyword, form, sv: k.sv, kd: k.kd, position: null, impressions: 0, clicks: 0 });
             continue;
         }
         const p = prev.get(k.keyword);
+        const form = signalForm({ sv: k.sv, position: a.position, impressions: a.impressions, clicks: a.clicks });
         latest.push({
             keyword: k.keyword,
             position: a.position,
@@ -449,12 +674,41 @@ async function rankSection(db, domain, tracked, win) {
             // 位次变小 = 前进,所以 delta = 旧 - 新(正数是好消息)。上一窗口没数据 → null。
             delta: p ? Number((p.position - a.position).toFixed(1)) : null,
             series: series.get(k.keyword) ?? [],
+            sv: k.sv,
+            kd: k.kd,
+            form,
         });
+        if (form)
+            signals.push({
+                keyword: k.keyword,
+                form,
+                sv: k.sv,
+                kd: k.kd,
+                position: a.position,
+                impressions: a.impressions,
+                clicks: a.clicks,
+            });
     }
     latest.sort((x, y) => x.position - y.position);
     const movers = latest
         .filter((r) => r.delta != null && Math.abs(r.delta) >= RANK_MOVER_MIN)
         .sort((x, y) => Math.abs(y.delta ?? 0) - Math.abs(x.delta ?? 0));
+    // 形态排序 = 值得先看的在前:能立刻动手的 pre_emergence,再是要换打法的 authority_limited。
+    const FORM_ORDER = {
+        pre_emergence: 0,
+        authority_limited: 1,
+        demand_no_surface: 2,
+    };
+    signals.sort((x, y) => FORM_ORDER[x.form] - FORM_ORDER[y.form] || y.impressions - x.impressions || (y.sv ?? 0) - (x.sv ?? 0));
+    // demand_no_surface 在冷启动站上是常态,留全量会把两条真稀有的形态淹掉。截断要说出来。
+    const noSurface = signals.filter((x) => x.form === "demand_no_surface");
+    if (noSurface.length > DEMAND_NO_SURFACE_MAX) {
+        const drop = new Set(noSurface.slice(DEMAND_NO_SURFACE_MAX).map((x) => x.keyword));
+        for (let i = signals.length - 1; i >= 0; i--)
+            if (drop.has(signals[i].keyword))
+                signals.splice(i, 1);
+        notes.push(`signals: ${noSurface.length} keywords have demand but no impressions this window — listing the ${DEMAND_NO_SURFACE_MAX} with the most volume; the rest are in rank.unseen`);
+    }
     return {
         source: "gsc",
         window: { from: win.from, to: win.to },
@@ -462,6 +716,7 @@ async function rankSection(db, domain, tracked, win) {
         latest,
         movers,
         unseen,
+        signals,
     };
 }
 /** 周口径时序:从窗口末端往回按 7 天分桶(不用自然周,免得口径受星期几影响)。 */