@clize/clize 0.35.5 → 0.36.0

package/dist/core/seo.js

@@ -1,10 +1,12 @@
 import { ClizeError } from "../lib/errors.js";
 import { sha256hex } from "../lib/crypto.js";
 import { DataForSeo, KEYWORDS_PER_CALL, normalizeHost, } from "../providers/seo/dataforseo.js";
-import { classifySerp } from "./seo-classify.js";
+import { classifySerp, clusterCells, ITEM_TYPES } from "./seo-classify.js";
 import { Gsc, toGscProperty } from "../providers/seo/gsc.js";
 import { readTraffic } from "./seo-traffic.js";
-import { INSPECT_MAX, IMPRESSIONS_MOVE_MIN, isImpressionsMove, probeStatus, readSitemap, selectPages, } from "./seo-pages.js";
+import { INSPECT_MAX, IMPRESSIONS_MOVE_MIN, fetchPageHeads, isImpressionsMove, normalizePageUrl, probeStatus, readSitemap, selectPages, } from "./seo-pages.js";
+import { deriveCells, derivePageFamilies, familyKeyOf, localeOfUrl, normalizeLocaleTag, parsePageHead, } from "./seo-cells.js";
+import { isIndexablePage, pageUrlPath } from "./site-manifest.js";
 /** 对客加价:成本 × (1 + 4) = ×5。刻意不复用 platform.billing.markupPct(0.2)——
  *  那是给域名 / 媒体等大额供给定的,套在美分级数据上会让定价失真(一次 serp 收 8 厘)。 */
 export const SEO_MARKUP_PCT = 4;
@@ -383,7 +385,7 @@ export async function keywords(ctx, db, opts) {
             keywords: cached.value,
             charged,
             cap,
-            notes: withCapNote(thisCallNote(charged, shape, chargedForSeo(cached.costUsd)), cap),
+            notes: withCapNote(thisCallNote(charged, shape, chargedForSeo(cached.costUsd)), cap, ...keywordsHandoffNotes(cached.value, tag)),
         };
     }
     await assertSeoCap(ctx, db, { estimateUsd: estimateSeoCost(op, { keywords: seeds.length }) });
@@ -418,9 +420,21 @@ export async function keywords(ctx, db, opts) {
         keywords: rows,
         charged,
         cap,
-        notes: withCapNote(thisCallNote(charged, shape), cap),
+        notes: withCapNote(thisCallNote(charged, shape), cap, ...keywordsHandoffNotes(rows, tag)),
     };
 }
+/** 定价回执的交接行(design/seo-cell-funnel.md §3.2 F)。漏斗死在这一步:量表对非英语工具词六成给
+ *  `no_data`,agent 把空值当没需求扔掉(2026-09-02 119 格 82 格未买一次 SERP;09-03 上午 zh-TW 22 词 1 页)。
+ *  规则「no_data 不是没需求」在 skill 里写了三次失效三次 —— 放在回执上,命令现成、路径分好,agent 不做决定。 */
+function keywordsHandoffNotes(rows, tag) {
+    const empty = rows.filter((r) => r.band === "no_data" || r.band === "no_volume");
+    if (!empty.length)
+        return [];
+    const loc = tag === DEFAULT_LOCALE ? "" : `@${tag}`;
+    return [
+        `${empty.length} of ${rows.length} keyword(s) have no volume row — missing data, not missing demand; volume only orders cells, it never drops one. Siblings of a verified family: enroll and build — \`clize seo check --add-keywords "<word>${loc}#<family>"\`; a new family: \`clize seo serp "${empty[0]?.keyword ?? "<word>"}${loc}"\` first ($0.02)`,
+    ];
+}
 /** 竞品反查:一次问多个域的流量画像 + 每个域靠什么词活。
  *  **这是命令面里唯一的词源命令**(反查出来的 topKeywords 就是候选种子);判读见 skill §6。 */
 export async function competitors(ctx, db, opts) {
@@ -493,7 +507,9 @@ const SERP_RELAY_NOTE = "when the survivor list is final, set the baseline: `cli
  *  (四道闸之一:没跑过 serp 不许建页),所以这里是指向页型规格包的黄金位置。**只发给可
  *  进入的 SERP**(listicle_window / open)——对 official_wall / definition_wall 提示建页
  *  就是误导;条件取自已算出的 verdict,同 signals 一样是按事实选择流程指引,不是建议。 */
-const SERP_BUILD_NOTE = "building a page for this keyword? page-type skeletons + on-page spec: `clize build site start`; after deploy, add the keyword to `clize seo check --keywords` (`<keyword>@<locale>` for a non-English cell); a locale sibling is gated by its own SERP — `clize seo serp <keyword> --locale <l>`, not by the English page";
+const SERP_BUILD_NOTE = "building a page for this keyword? page-type skeletons + on-page spec: `clize build site start`; after deploy, enroll the cell with `clize seo check --add-keywords \"<keyword>@<locale>#<family>\"` — once a family earns or holds an enterable verdict, its locale siblings need no SERP of their own: enroll them the same way and build";
+/** tool_window 专属(v2):占位者是工具,角度是它们缺什么 —— 读前三名的页,不是标题。 */
+const SERP_TOOL_TAIL = "; the gap is what the tools on this page do not do — read the top 3 pages, then write the angle";
 /** listicle_window 专属追加(0.30.1):放置→外部是四条缝里唯一没有回执配合的一段,两轮
  *  实测(subagent 二测 vs tabledi 真实使用)执行方差全集中在放置环 —— 失守的规矩只活在
  *  prose 里,接力链此前终止于"入表",agent 写交付物时手边没有这一行。 */
@@ -501,10 +517,32 @@ const SERP_PITCH_TAIL = "; then pitch the parasite targets above — inclusion b
 function serpTailNotes(verdict) {
     if (verdict === "listicle_window")
         return [SERP_BUILD_NOTE + SERP_PITCH_TAIL, SERP_RELAY_NOTE];
+    if (verdict === "tool_window")
+        return [SERP_BUILD_NOTE + SERP_TOOL_TAIL, SERP_RELAY_NOTE];
     if (verdict === "open")
         return [SERP_BUILD_NOTE, SERP_RELAY_NOTE];
     return [SERP_RELAY_NOTE];
 }
+const emptyComposition = () => {
+    const c = {};
+    for (const t of ITEM_TYPES)
+        c[t] = 0;
+    return c;
+};
+/** serp 跑完把 verdict 回写到这个租户词表里同名同市场的条目(design/seo-cell-funnel.md §3.2 E):
+ *  族的验证态从此是事实不是记忆。serp 本身无 domain,所以按租户名下所有域写;写不到就是没这条,不是错。 */
+async function rememberVerdict(db, tenantId, keyword, tag, verdict) {
+    try {
+        await db
+            .prepare("UPDATE seo_keywords SET serp_verdict=?, serp_at=? WHERE keyword=? AND locale=?" +
+            " AND domain IN (SELECT domain FROM seo_domains WHERE tenant_id=?)")
+            .bind(verdict, new Date().toISOString(), keyword.toLowerCase(), tag, tenantId)
+            .run();
+    }
+    catch {
+        /* 回写是增强层,不拦查询 */
+    }
+}
 /** 结果页真相:自然结果 + 占位判定 + 寄生目标。 */
 export async function serp(ctx, db, opts) {
     const keyword = opts.keyword.trim();
@@ -520,8 +558,10 @@ export async function serp(ctx, db, opts) {
     if (cached) {
         const charged = { usd: 0, cacheHit: true };
         const cap = await seoCapState(db, ctx.tenantId);
+        await rememberVerdict(db, ctx.tenantId, keyword, tag, cached.value.verdict);
         return {
             ...cached.value,
+            composition: cached.value.composition ?? emptyComposition(), // 7 天缓存里可能还有 v2 之前的条目
             charged,
             cap,
             notes: withCapNote(thisCallNote(charged, shape, chargedForSeo(cached.costUsd)), cap, ...serpTailNotes(cached.value.verdict)),
@@ -537,6 +577,7 @@ export async function serp(ctx, db, opts) {
         aiOverview: page.aiOverview,
         itemTypes: page.itemTypes,
         counts: classified.counts,
+        composition: classified.composition,
         items: classified.items.map((i) => ({
             pos: i.pos,
             host: i.host,
@@ -550,6 +591,7 @@ 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 });
     const cap = await seoCapState(db, ctx.tenantId);
+    await rememberVerdict(db, ctx.tenantId, keyword, tag, payload.verdict);
     return {
         ...payload,
         charged,
@@ -557,6 +599,119 @@ export async function serp(ctx, db, opts) {
         notes: withCapNote(thisCallNote(charged, shape), cap, ...serpTailNotes(payload.verdict)),
     };
 }
+/** 一批最多多少格(整站矩阵 100–150 格要一次装下;再大就分两次)。 */
+const SERP_BATCH_MAX = 200;
+/** 上游并发(每格一次 live 抓取,实测 ~2.7s;Workers 出站连接上限 6)。 */
+const SERP_BATCH_CONCURRENCY = 6;
+/** 一批格子的结果页真相:每格一次 serp(缓存前置、各自入账),再在批内算簇、内联定价排序、汇总回执。
+ *  它是 B 档的闸与简报原料、A+ 档的放置目标来源 —— 不是兄弟格的前置(兄弟格直接建,§7.2)。 */
+export async function serpBatch(ctx, db, opts) {
+    const seen = new Set();
+    const entries = [];
+    for (const raw of opts.entries) {
+        const e = parseKeywordEntry(raw);
+        if (!e.keyword)
+            continue;
+        const k = `${e.keyword}\u0000${e.locale}`;
+        if (seen.has(k))
+            continue;
+        seen.add(k);
+        entries.push(e);
+    }
+    if (!entries.length)
+        throw new ClizeError("no keyword given", 400);
+    if (entries.length > SERP_BATCH_MAX)
+        throw new ClizeError(`too many cells (${entries.length}); max ${SERP_BATCH_MAX} per call — split the list`, 400);
+    if (opts.capUsd !== undefined)
+        await setTenantSeoCap(db, ctx.tenantId, opts.capUsd);
+    // 每格一次 serp:各自查缓存、各自过闸、各自入账(账本逐笔仍是真值);并发受出站连接上限约束。
+    const results = new Array(entries.length);
+    const queue = entries.map((e, i) => i);
+    const worker = async () => {
+        for (let i = queue.shift(); i !== undefined; i = queue.shift()) {
+            const e = entries[i];
+            try {
+                results[i] = await serp(ctx, db, { keyword: e.keyword, locale: e.locale, depth: opts.depth });
+            }
+            catch (err) {
+                results[i] = err instanceof Error ? err : new Error(String(err));
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(SERP_BATCH_CONCURRENCY, entries.length) }, worker));
+    const notes = [];
+    let usd = 0;
+    let cached = 0;
+    const ok = [];
+    for (let i = 0; i < entries.length; i++) {
+        const r = results[i];
+        const e = entries[i];
+        if (r instanceof Error || r === undefined) {
+            notes.push(`"${e.keyword}"@${e.locale}: ${r instanceof Error ? r.message : "no result"}`);
+            continue;
+        }
+        usd += r.charged.usd;
+        if (r.charged.cacheHit)
+            cached++;
+        ok.push({ e, r });
+    }
+    // 内联定价:只排序,从不淘汰。按市场分组走 keywords(30 天缓存;预算不够就跳过并说明)。
+    const metrics = new Map();
+    let priced = 0;
+    if (opts.price !== false && ok.length) {
+        const byLocale = new Map();
+        for (const { e } of ok)
+            byLocale.set(e.locale, [...(byLocale.get(e.locale) ?? []), e.keyword]);
+        for (const [locale, seeds] of byLocale) {
+            try {
+                const kr = await keywords(ctx, db, { seeds, locale });
+                usd += kr.charged.usd;
+                for (const row of kr.keywords) {
+                    metrics.set(`${row.keyword.toLowerCase()}\u0000${locale}`, { sv: row.sv, kd: row.kd, band: row.band });
+                    priced++;
+                }
+            }
+            catch (err) {
+                notes.push(`pricing skipped for ${locale} (${err instanceof Error ? err.message : String(err)}) — cells are unordered, not dropped`);
+            }
+        }
+    }
+    const { clusterOf, clusters } = clusterCells(ok.map(({ e, r }) => ({ key: `${e.keyword}@${e.locale}`, locale: e.locale, urls: r.items.slice(0, 10).map((i) => i.url) })));
+    const cells = ok.map(({ e, r }) => {
+        const m = metrics.get(`${e.keyword}\u0000${e.locale}`);
+        return {
+            keyword: e.keyword,
+            locale: e.locale,
+            verdict: r.verdict,
+            composition: r.composition,
+            aiOverview: r.aiOverview,
+            top: r.items.slice(0, 10),
+            parasiteTargets: r.parasiteTargets,
+            cluster: clusterOf.get(`${e.keyword}@${e.locale}`) ?? null,
+            sv: m?.sv ?? null,
+            kd: m?.kd ?? null,
+            band: m?.band ?? null,
+            cached: r.charged.cacheHit,
+        };
+    });
+    const byVerdict = {};
+    for (const c of cells)
+        byVerdict[c.verdict] = (byVerdict[c.verdict] ?? 0) + 1;
+    const enterable = cells.filter((c) => c.verdict === "tool_window" || c.verdict === "listicle_window" || c.verdict === "open").length;
+    const walls = cells.length - enterable;
+    const cap = await seoCapState(db, ctx.tenantId);
+    const money = `this call: $${usd.toFixed(4)} (serp batch, ${cells.length} cell${cells.length === 1 ? "" : "s"}, ${cached} cache hit${cached === 1 ? "" : "s"}${opts.price === false ? ", not priced" : `, ${priced} priced`})`;
+    const tally = `${cells.length} cells: ${enterable} enterable (${byVerdict.tool_window ?? 0} tool_window · ${byVerdict.listicle_window ?? 0} listicle_window · ${byVerdict.open ?? 0} open) · ${walls} wall${walls === 1 ? "" : "s"} · ${clusters.length} cluster${clusters.length === 1 ? "" : "s"} of ≥2 (same page in the occupants' eyes: shared ≥5 of the top 10)`;
+    const handoff = "enterable cells: brief + build (§7.1), then `clize seo check --add-keywords \"<word>@<locale>#<family>\"`; once a family is verified its siblings need no SERP; walls: skip rows with the reason";
+    return {
+        cells,
+        clusters,
+        summary: { cells: cells.length, enterable, walls, byVerdict, clusters: clusters.length, priced, cached },
+        charged: { usd: Number(usd.toFixed(4)), cacheHit: cells.length > 0 && cached === cells.length && priced === 0 },
+        cap,
+        notes: withCapNote(money, cap, tally, handoff, SERP_RELAY_NOTE, ...notes),
+    };
+}
 /** `pre_emergence` 要求的最低曝光:低于此量与噪声不可分(同 GSC 新词回填的阈值口径)。 */
 const SIGNAL_MIN_IMPRESSIONS = 10;
 /** `pre_emergence` 的第二条件:窗口曝光 ≥ 月量 × 此倍数 = 量表明显没跟上需求。
@@ -623,7 +778,7 @@ function measureWindow(now) {
 /** 配置 upsert:带参则更新,不带则沿用已存的(首次给出后记住)。 */
 async function upsertDomain(ctx, db, domain, cfg) {
     const existing = await db
-        .prepare("SELECT domain, brand, competitors, gsc_property FROM seo_domains WHERE domain=? AND tenant_id=?")
+        .prepare("SELECT domain, brand, competitors, gsc_property, locales FROM seo_domains WHERE domain=? AND tenant_id=?")
         .bind(domain, ctx.tenantId)
         .first();
     const row = {
@@ -635,20 +790,22 @@ async function upsertDomain(ctx, db, domain, cfg) {
         // "none" 存成哨兵而不是清空:清空等于「还没探测过」,下轮又会去问一遍 —— 那句
         // 「pass --gsc none to stop asking」就成了空头支票。
         gsc_property: cfg.gsc === GSC_OFF ? GSC_OFF : (cfg.gsc ?? existing?.gsc_property ?? null),
+        locales: cfg.locales ? JSON.stringify(cfg.locales.map((l) => resolveLocaleLoose(l))) : (existing?.locales ?? null),
     };
     // budget_monthly_usd 不再写也不再读(0.29.2 砍掉单域配额):列留在表里(有 DEFAULT,
     // INSERT 省略它即可),但它不再影响任何行为 —— 唯一的墙是租户级 `--cap`。
     await db
-        .prepare("INSERT INTO seo_domains (domain, tenant_id, brand, competitors, gsc_property, created_at) VALUES (?,?,?,?,?,?)" +
+        .prepare("INSERT INTO seo_domains (domain, tenant_id, brand, competitors, gsc_property, locales, created_at) VALUES (?,?,?,?,?,?,?)" +
         " ON CONFLICT(domain) DO UPDATE SET brand=excluded.brand, competitors=excluded.competitors," +
-        " gsc_property=excluded.gsc_property")
-        .bind(domain, ctx.tenantId, row.brand, row.competitors, row.gsc_property, new Date().toISOString())
+        " gsc_property=excluded.gsc_property, locales=excluded.locales")
+        .bind(domain, ctx.tenantId, row.brand, row.competitors, row.gsc_property, row.locales, new Date().toISOString())
         .run();
     return row;
 }
 async function readKeywords(db, domain) {
     const { results } = await db
-        .prepare("SELECT keyword, locale, sv, kd, ai_sv, cpc, source, saved_at, last_refreshed_at FROM seo_keywords WHERE domain=? ORDER BY id")
+        .prepare("SELECT keyword, locale, sv, kd, ai_sv, cpc, source, saved_at, last_refreshed_at, family, page_url, serp_verdict, serp_at" +
+        " FROM seo_keywords WHERE domain=? ORDER BY id")
         .bind(domain)
         .all();
     return results;
@@ -725,31 +882,45 @@ async function refreshKeywordMetrics(ctx, db, domain, rows, notes, now) {
     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;
 }
-/** 词表条目(0.35.0):`word` 或 `word@ja-JP` —— `@` 后是定价市场,缺省 en-US,白名单外 400。
- *  此前非英语词一律按 en-US 定价、全部 no_data;语言页按 skill §7「上线即入表」的契约就成了没有
- *  记分牌的孤儿页(tabledi 全球台账 §6 把非英语量价整个留在文件里,进不了 check)。 */
+/** 词表条目(0.35.0 `word@ja-JP`;v2 加 `#family` / `=url`,design/seo-cell-funnel.md §3.2 B):
+ *  `csv 分割@ja-JP#split-csv`、`listen vergleichen online@de-DE=/de/tools/listen-vergleichen/`。
+ *  族与页二选一,给页的由清单反查族。`#` / `=` 只在条目末尾按这个形状识别(`c# tutorial` 里的 # 不算)。
+ *  此前非英语词一律按 en-US 定价、全部 no_data;语言页按 skill §7「上线即入表」的契约就成了没有记分牌的孤儿页。 */
 export function parseKeywordEntry(raw) {
-    const s = raw.trim();
-    const at = s.lastIndexOf("@");
-    if (at > 0 && at < s.length - 1) {
-        const { tag } = resolveLocale(s.slice(at + 1).trim());
-        return { keyword: s.slice(0, at).trim().toLowerCase(), locale: tag };
-    }
-    return { keyword: s.toLowerCase(), locale: DEFAULT_LOCALE };
+    const m = /^(.+?)(?:@([A-Za-z]{2}(?:-[A-Za-z]{2})?))?(?:=((?:\/|https?:\/\/)[^#\s]*))?(?:#([A-Za-z0-9._-]+))?$/.exec(raw.trim());
+    const kw = (m?.[1] ?? raw).trim().toLowerCase();
+    const locale = m?.[2] ? resolveLocale(m[2]).tag : DEFAULT_LOCALE;
+    const pageUrl = m?.[3] ? m[3].trim() : null;
+    const family = m?.[4] ? m[4].toLowerCase() : null;
+    return { keyword: kw, locale, family, pageUrl };
 }
 /** 输出侧的条目写法:与输入同形,en-US 不带后缀。 */
 function keywordLabel(k) {
     return !k.locale || k.locale === DEFAULT_LOCALE ? k.keyword : `${k.keyword}@${k.locale}`;
 }
-/** 词表:--keywords 是**全量替换**(保留已有行的指标),不带则读已存的。同一词可按不同市场各占一行。 */
-async function syncKeywords(db, domain, keywords, now) {
-    if (keywords) {
-        const wanted = new Map();
-        for (const raw of keywords) {
+/** 词表:--keywords 是**全量替换**(保留已有行的指标),--add-keywords 是追加;都不带则读已存的。
+ *  同一词可按不同市场各占一行。族 / 承载页只在条目给了时覆盖(COALESCE),不给不动。 */
+async function syncKeywords(db, domain, keywords, addKeywords, now) {
+    const parse = (raws) => {
+        const out = new Map();
+        for (const raw of raws) {
             const e = parseKeywordEntry(raw);
             if (e.keyword)
-                wanted.set(`${e.keyword}\u0000${e.locale}`, e);
+                out.set(`${e.keyword}\u0000${e.locale}`, e);
         }
+        return out;
+    };
+    const upsert = async (entries) => {
+        for (const e of entries)
+            await db
+                .prepare("INSERT INTO seo_keywords (domain, keyword, locale, source, saved_at, family, page_url) VALUES (?,?,?,?,?,?,?)" +
+                " ON CONFLICT(domain, keyword, locale) DO UPDATE SET source='check'," +
+                " family=COALESCE(excluded.family, seo_keywords.family), page_url=COALESCE(excluded.page_url, seo_keywords.page_url)")
+                .bind(domain, e.keyword, e.locale, "check", now, e.family, e.pageUrl)
+                .run();
+    };
+    if (keywords) {
+        const wanted = parse(keywords);
         // 全量替换语义:不在新表里的(词, 市场)删掉(含之前 gsc_backfill 进来的)。
         const { results: existing } = await db
             .prepare("SELECT keyword, locale FROM seo_keywords WHERE domain=?")
@@ -761,15 +932,24 @@ async function syncKeywords(db, domain, keywords, now) {
                     .prepare("DELETE FROM seo_keywords WHERE domain=? AND keyword=? AND locale=?")
                     .bind(domain, e.keyword, e.locale)
                     .run();
-        for (const e of wanted.values())
-            await db
-                .prepare("INSERT INTO seo_keywords (domain, keyword, locale, source, saved_at) VALUES (?,?,?,?,?)" +
-                " ON CONFLICT(domain, keyword, locale) DO UPDATE SET source='check'")
-                .bind(domain, e.keyword, e.locale, "check", now)
-                .run();
+        await upsert(wanted.values());
     }
+    if (addKeywords)
+        await upsert(parse(addKeywords).values());
     return readKeywords(db, domain);
 }
+/** `--locales` 的条目:白名单内按白名单写法,白名单外保留规范形(it / nl):这些语区照样能算格子,只是不能定价。 */
+function resolveLocaleLoose(raw) {
+    try {
+        return resolveLocale(raw).tag;
+    }
+    catch {
+        const m = /^([a-z]{2})(?:[-_]([a-z]{2}))?$/i.exec(raw.trim());
+        if (!m)
+            throw new ClizeError(`unknown locale "${raw}"`, 400);
+        return m[2] ? `${m[1].toLowerCase()}-${m[2].toUpperCase()}` : m[1].toLowerCase();
+    }
+}
 /** 测一轮。cron 若将来复活,定期跑的就是这个函数(同一条代码路径)。 */
 export async function checkOne(ctx, db, domain0, cfg = {}, now = Date.now()) {
     const domain = normalizeHost(domain0.replace(/^https?:\/\//, "").split("/")[0] ?? "");
@@ -783,7 +963,7 @@ export async function checkOne(ctx, db, domain0, cfg = {}, now = Date.now()) {
     const win = measureWindow(now);
     const conf = await upsertDomain(ctx, db, domain, cfg);
     const competitors = conf.competitors ? JSON.parse(conf.competitors) : [];
-    const kwRows = await syncKeywords(db, domain, cfg.keywords, ranAt);
+    const kwRows = await syncKeywords(db, domain, cfg.keywords, cfg.addKeywords, ranAt);
     const notes = [];
     // ── 流量分源(自有基建,不花数据钱)。AI 来源单列;全零也返回,零就是信息。
     let traffic = null;
@@ -804,8 +984,21 @@ export async function checkOne(ctx, db, domain0, cfg = {}, now = Date.now()) {
             " referrers=excluded.referrers, ai_sources=excluded.ai_sources")
             .bind(domain, traffic.from.slice(0, 10), traffic.to.slice(0, 10), traffic.pv, JSON.stringify(Object.fromEntries(traffic.topReferrers.map((r) => [r.host, r.pv]))), JSON.stringify(traffic.ai.byEngine))
             .run();
+    // ── 页面清单(资产,产品自记;design/seo-cell-funnel.md v2 §3.2 A):sitemap → seo_pages,
+    //    新页 / lastmod 变了的页抓一次页首(hreflang / lang / noindex / title),按 hreflang 互链分族。
+    //    自己的站,零上游费用;任何失败只降级成 note。托管站的清单由 deploy 直接写,这里只补 sitemap 没有的。
+    const sitemap = await readSitemap(domain);
+    if (!sitemap.urls.length)
+        notes.push("pages: no sitemap found (/sitemap.xml or a Sitemap: line in robots.txt) — pages Google was never shown cannot be listed; publish one to get index status for pages without impressions");
+    const firstSeen = await rememberPages(db, domain, sitemap.urls, now);
+    try {
+        await refreshPageHeads(db, domain, notes, now);
+    }
+    catch (e) {
+        notes.push(`pages: inventory not refreshed this round (${e instanceof Error ? e.message : String(e)})`);
+    }
     // ── GSC(唯一的搜索面)。拿不到不中断整轮 —— 给 null + hint。
-    const gsc = await gscSection(ctx, db, domain, conf, kwRows, notes, win, now);
+    const gsc = await gscSection(ctx, db, domain, conf, kwRows, notes, win, now, sitemap, firstSeen);
     // ── 补指标:回填可能刚往词表里加了词,所以先重读一次(否则 total 会漏掉本轮的新发现),
     //    再把缺指标 / 指标过期的词批量取一次写回。**这是 check 唯一可能花钱的一步**,
     //    30 天内重跑不重复取、不重复计费;预算不够就跳过并记 note,不毁掉免费的两段。
@@ -836,6 +1029,14 @@ export async function checkOne(ctx, db, domain0, cfg = {}, now = Date.now()) {
     }
     if (unpriced)
         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)`);
+    // ── 格子面:页面清单 × 词表意图。全部免费源;失败只降级。
+    let cells = null;
+    try {
+        cells = await cellsSection(db, domain, kwAll, conf, win, rank, notes);
+    }
+    catch (e) {
+        notes.push(`cells: unavailable this round (${e instanceof Error ? e.message : String(e)})`);
+    }
     // ── 可用性分层如实回显(seo-geo-product.md §2.4):check 的三源(词表指标/流量/GSC)
     //    不是对所有站都成立 —— 托管站有流量没 GSC,外部站加了 SA 才有 GSC,裸外部站只剩
     //    词表一源。对一源站假装三源测量是口径事故;缺哪源、去哪解锁,一行说清。
@@ -863,6 +1064,7 @@ export async function checkOne(ctx, db, domain0, cfg = {}, now = Date.now()) {
         rank,
         traffic,
         gsc,
+        cells,
         notes,
         // 测量本身是免费的(GSC service account + 自家 CF RUM);花的只可能是补词指标那一步。
         charged,
@@ -940,13 +1142,9 @@ async function aggregateGscByPage(db, domain, from, to) {
 /** 页面面(0.34.0):每页两窗口曝光 × 实况状态 × 收录态。GSC 段成功后才有(数据都在明细表里)。
  *  探测与 inspection 的任何失败只降级成 note,不中断 check;收录态按预算分配:
  *  塌方的 movers 先(「页丢了还是掉了」)→ sitemap 里零曝光的新页(「Google 收了没」)→ 头部页。 */
-async function pagesSection(db, domain, gscClient, property, win, notes, now) {
+async function pagesSection(db, domain, gscClient, property, win, notes, now, sitemap, firstSeen) {
     const cur = await aggregateGscByPage(db, domain, win.from, win.to);
     const prev = await aggregateGscByPage(db, domain, win.prevFrom, win.prevTo);
-    const sitemap = await readSitemap(domain);
-    if (!sitemap.urls.length)
-        notes.push("pages: no sitemap found (/sitemap.xml or a Sitemap: line in robots.txt) — pages Google was never shown cannot be listed; publish one to get index status for pages without impressions");
-    const firstSeen = await rememberSitemap(db, domain, sitemap.urls, now);
     const face = selectPages(cur, prev, sitemap.urls, firstSeen);
     if (face.unseenTotal > face.unseen.length)
         notes.push(`pages: unseen lists ${face.unseen.length} of ${face.unseenTotal} zero-impression sitemap URLs (newest first seen first)`);
@@ -989,36 +1187,217 @@ async function pagesSection(db, domain, gscClient, property, win, notes, now) {
         notes.push(`pages: index status unavailable — ${stop}`);
     else if (candidates)
         notes.push(`pages: index status checked for ${done} of ${order.length} candidate page(s) — collapsed movers first, then the most recently first-seen sitemap URLs without impressions, then top pages (${INSPECT_MAX} per check)`);
+    // 实况状态与收录态回写清单(页面是资产:退役规则要看「已收录 + 零曝光」,不能只活在一轮的返回里)。
+    const stamp = new Date(now).toISOString();
+    await writeAll(db, [...face.latest, ...face.movers, ...face.unseen]
+        .filter((r) => r.status !== null || r.index)
+        .map((r) => db
+        .prepare("UPDATE seo_pages SET status=COALESCE(?, status), index_state=COALESCE(?, index_state)," +
+        " index_verdict=COALESCE(?, index_verdict), index_at=COALESCE(?, index_at) WHERE domain=? AND url=?")
+        .bind(r.status, r.index?.state ?? null, r.index?.verdict ?? null, r.index ? stamp : null, domain, r.page)));
     return { ...face, sitemap: { source: sitemap.source, urls: sitemap.urls.length } };
 }
-/** sitemap 首见表(0.35.0):每次 check 把 sitemap 里的 URL upsert 一遍,首见日期只写一次。
+/** 页面清单(v2,原 0.35.0 sitemap 首见表):每次 check 把 sitemap 里的 URL upsert 进 seo_pages,首见日期只写一次。
  *  「这批页是刚上线的还是上一批的」lastmod 分不出来 —— 一次全站改版(2026-09-02 主站 124 条全同日)
  *  就把新页挤出 unseen 的检查配额;首见是机器自己记得住的事实,与站的生成器无关。首轮入库时
- *  用 lastmod 兜底(没有就当天),之后只更新 last_seen。 */
-async function rememberSitemap(db, domain, urls, now) {
+ *  用 lastmod 兜底(没有就当天),之后只更新 last_seen / lastmod。托管站 deploy 写进来的行(source=deploy)不动 source。 */
+async function rememberPages(db, domain, urls, now) {
     const out = new Map();
-    if (!urls.length)
-        return out;
     const today = new Date(now).toISOString().slice(0, 10);
-    // 只在这个站第一次入库时拿 lastmod 兜底(一次性回填);之后没见过的 URL 就是新页,首见 = 今天 ——
-    // 否则一张带旧 lastmod 的新页会被当成老页,排序又退回 lastmod。
-    const { results: any } = await db
-        .prepare("SELECT 1 AS one FROM seo_sitemap_urls WHERE domain=? LIMIT 1")
-        .bind(domain)
-        .all();
-    const bootstrap = !any.length;
-    await writeAll(db, urls.map((u) => db
-        .prepare("INSERT INTO seo_sitemap_urls (domain, url, first_seen_at, last_seen_at) VALUES (?,?,?,?)" +
-        " ON CONFLICT(domain, url) DO UPDATE SET last_seen_at=excluded.last_seen_at")
-        .bind(domain, u.loc, bootstrap && u.lastmod && u.lastmod < today ? u.lastmod : today, today)));
+    if (urls.length) {
+        const { results: any } = await db
+            .prepare("SELECT 1 AS one FROM seo_pages WHERE domain=? LIMIT 1")
+            .bind(domain)
+            .all();
+        const bootstrap = !any.length;
+        await writeAll(db, urls.map((u) => db
+            .prepare("INSERT INTO seo_pages (domain, url, first_seen_at, last_seen_at, source, lastmod) VALUES (?,?,?,?,'sitemap',?)" +
+            " ON CONFLICT(domain, url) DO UPDATE SET last_seen_at=excluded.last_seen_at, lastmod=excluded.lastmod")
+            .bind(domain, u.loc, bootstrap && u.lastmod && u.lastmod < today ? u.lastmod : today, today, u.lastmod)));
+    }
     const { results } = await db
-        .prepare("SELECT url, first_seen_at FROM seo_sitemap_urls WHERE domain=?")
+        .prepare("SELECT url, first_seen_at FROM seo_pages WHERE domain=?")
         .bind(domain)
         .all();
     for (const r of results)
         out.set(r.url, r.first_seen_at);
     return out;
 }
+/** 一轮 check 最多抓多少页的页首(自己的站,不花数据钱,只花时间;新页与 lastmod 变了的页优先)。 */
+const HEADS_PER_CHECK = 300;
+async function readPages(db, domain) {
+    const { results } = await db
+        .prepare("SELECT url, locale, family, first_seen_at, lastmod, head_at, alternates, noindex, index_state, index_verdict, source" +
+        " FROM seo_pages WHERE domain=? ORDER BY first_seen_at DESC, url")
+        .bind(domain)
+        .all();
+    return results;
+}
+const parseAlternates = (json) => {
+    if (!json)
+        return {};
+    try {
+        const v = JSON.parse(json);
+        return v && typeof v === "object" ? v : {};
+    }
+    catch {
+        return {};
+    }
+};
+/** 页首抓取 + 分族(design/seo-cell-funnel.md §3.2 A):没抓过 / lastmod 变了的页抓一次页首,然后对全站
+ *  按 hreflang 互链重算族与语区。**agent 不声明任何页面字段** —— 语言、族、标题、noindex 全从站上读。
+ *  托管站(source=deploy)的行由 deploy 写清单,这里不抓。 */
+async function refreshPageHeads(db, domain, notes, now) {
+    const rows = await readPages(db, domain);
+    if (!rows.length)
+        return;
+    const stale = rows.filter((r) => r.source !== "deploy" && (!r.head_at || (r.lastmod !== null && r.lastmod > r.head_at.slice(0, 10))));
+    const todo = stale.slice(0, HEADS_PER_CHECK);
+    const langThisRound = new Map();
+    if (todo.length) {
+        const heads = await fetchPageHeads(todo.map((r) => r.url));
+        const stamp = new Date(now).toISOString();
+        const stmts = [];
+        for (const r of todo) {
+            const h = heads.get(r.url);
+            if (!h || h.status === null)
+                continue; // 探不到:下轮再试,不记 head_at
+            const head = h.html ? parsePageHead(h.html, r.url) : null;
+            if (head) {
+                r.alternates = JSON.stringify(head.alternates);
+                r.noindex = head.noindex ? 1 : 0;
+                langThisRound.set(r.url, head.lang);
+            }
+            stmts.push(db
+                .prepare("UPDATE seo_pages SET status=?, head_at=?, alternates=COALESCE(?, alternates), title=COALESCE(?, title), noindex=?" +
+                " WHERE domain=? AND url=?")
+                .bind(h.status, stamp, head ? JSON.stringify(head.alternates) : null, head?.title ?? null, head?.noindex ? 1 : 0, domain, r.url));
+        }
+        await writeAll(db, stmts);
+        if (stale.length > todo.length)
+            notes.push(`pages: read the head of ${todo.length} of ${stale.length} new or changed page(s) this round (${HEADS_PER_CHECK} per check)`);
+    }
+    // 分族:全站一起算(簇是全局关系;缓存的 alternates 与本轮新抓的一起进并查集)。
+    const fam = derivePageFamilies(rows.map((r) => ({ url: r.url, lang: langThisRound.get(r.url) ?? null, alternates: parseAlternates(r.alternates) })), DEFAULT_LOCALE);
+    const updates = [];
+    for (const r of rows) {
+        const f = fam.get(normalizePageUrl(r.url));
+        if (!f)
+            continue;
+        // 语区:本轮抓过或还没有的页按派生值;已有值且本轮没抓的页不动(别让一次抓失败把已知语区抹掉)。
+        const locale = langThisRound.has(r.url) || !r.locale ? f.locale : r.locale;
+        if (f.family !== r.family || locale !== r.locale)
+            updates.push(db.prepare("UPDATE seo_pages SET family=?, locale=? WHERE domain=? AND url=?").bind(f.family, locale, domain, r.url));
+    }
+    await writeAll(db, updates);
+}
+/** 同词落多页的展开(rank.latest.pages > 1 的那些 query):本窗口有曝光的页,按曝光降序,最多 5 页。 */
+async function pagesOfQueries(db, domain, queries, from, to) {
+    const out = new Map();
+    if (!queries.length)
+        return out;
+    const wanted = new Set(queries);
+    const { results } = await db
+        .prepare("SELECT query, page, SUM(impressions) AS impressions FROM seo_gsc_daily" +
+        " WHERE domain=? AND date>=? AND date<=? GROUP BY query, page")
+        .bind(domain, from, to)
+        .all();
+    const acc = new Map();
+    for (const r of results) {
+        if (!wanted.has(r.query) || !r.page || !r.impressions)
+            continue;
+        acc.set(r.query, [...(acc.get(r.query) ?? []), { page: r.page, impressions: r.impressions }]);
+    }
+    for (const [q, pages] of acc)
+        out.set(q, pages
+            .sort((a, b) => b.impressions - a.impressions || (a.page < b.page ? -1 : 1))
+            .slice(0, 5)
+            .map((p) => p.page));
+    return out;
+}
+/** 格子面:页面清单 × 词表意图。绑定(族 + 语区 → 页)在这里做并写回词表;派生全在 seo-cells.ts 的纯函数里。 */
+async function cellsSection(db, domain, kwAll, conf, win, rank, notes) {
+    const pageRows = await readPages(db, domain);
+    const cur = await aggregateGscByPage(db, domain, win.from, win.to);
+    const prev = await aggregateGscByPage(db, domain, win.prevFrom, win.prevTo);
+    const norm = (m) => {
+        const out = new Map();
+        for (const [p, a] of m)
+            out.set(normalizePageUrl(p), (out.get(normalizePageUrl(p)) ?? 0) + a.impressions);
+        return out;
+    };
+    const curN = norm(cur);
+    const prevN = norm(prev);
+    const pages = pageRows.map((r) => ({
+        url: r.url,
+        locale: r.locale,
+        family: r.family,
+        firstSeen: r.first_seen_at,
+        noindex: !!r.noindex,
+        indexState: r.index_state,
+        indexVerdict: r.index_verdict,
+        impressions: curN.get(normalizePageUrl(r.url)) ?? 0,
+        prevImpressions: prev.size ? (prevN.get(normalizePageUrl(r.url)) ?? 0) : null,
+        alternates: parseAlternates(r.alternates),
+    }));
+    // 绑定:族 + 语区 → 清单里的页;给了页没给族的 → 从页反查族。写回词表(下一轮就是事实)。
+    const byUrl = new Map();
+    for (const r of pageRows)
+        byUrl.set(normalizePageUrl(r.url), r);
+    const byFamLoc = new Map();
+    for (const r of pageRows)
+        if (r.family && r.locale && !byFamLoc.has(`${r.family}\u0000${r.locale}`))
+            byFamLoc.set(`${r.family}\u0000${r.locale}`, r.url);
+    const updates = [];
+    const keywords = [];
+    // 条目里的 `=/path/` 是站内相对路径:按域补全成绝对 URL 再比对 / 存回
+    const absolute = (u) => (u.startsWith("/") ? `https://${domain}${u}` : u);
+    for (const k of kwAll) {
+        if (k.source === "gsc_backfill")
+            continue;
+        let family = k.family;
+        let pageUrl = k.page_url ? absolute(k.page_url) : null;
+        if (!family && pageUrl)
+            family = byUrl.get(normalizePageUrl(pageUrl))?.family ?? familyKeyOf(pageUrl);
+        if (family && (!pageUrl || !byUrl.has(normalizePageUrl(pageUrl)))) {
+            const bound = byFamLoc.get(`${family}\u0000${k.locale}`);
+            if (bound)
+                pageUrl = bound;
+        }
+        if (family !== k.family || pageUrl !== k.page_url)
+            updates.push(db
+                .prepare("UPDATE seo_keywords SET family=?, page_url=? WHERE domain=? AND keyword=? AND locale=?")
+                .bind(family, pageUrl, domain, k.keyword, k.locale));
+        keywords.push({
+            keyword: k.keyword,
+            locale: k.locale,
+            family,
+            pageUrl,
+            serpVerdict: k.serp_verdict,
+            sv: k.sv,
+            band: keywordBand(k.sv, k.kd),
+        });
+    }
+    await writeAll(db, updates);
+    // 同词落多页:rank 已经算出 pages > 1 的词,这里只展开页清单。
+    const split = (rank?.latest ?? []).filter((r) => r.pages > 1);
+    const pagesOf = await pagesOfQueries(db, domain, split.map((r) => r.keyword), win.from, win.to);
+    const cannibal = split
+        .map((r) => ({ query: r.keyword, locale: r.locale, pages: pagesOf.get(r.keyword) ?? [] }))
+        .filter((c) => c.pages.length > 1);
+    let locales;
+    if (conf.locales)
+        try {
+            locales = JSON.parse(conf.locales);
+        }
+        catch {
+            locales = undefined;
+        }
+    const face = deriveCells(pages, keywords, { locales, windowTo: win.to, cannibal, priceable: new Set(Object.keys(LOCALES)) });
+    const d = face.defects.noAlternates.length + face.defects.oneWay.length + face.defects.sameLocaleInCluster.length;
+    notes.push(`cells: ${face.byStatus.missing} missing · ${face.byStatus.queued} queued (${face.byStatus.family_unverified} families unverified → serp their first keyword) · ${face.byStatus.built} built · ${face.byStatus.retire} to retire · ${face.cannibal.length} cannibal · ${d} defects`);
+    return face;
+}
 /** 位次段:词表 join GSC 明细。纯 D1 读,零上游调用。 */
 async function rankSection(db, domain, tracked, win, notes) {
     const cur = await aggregateGsc(db, domain, win.from, win.to);
@@ -1194,7 +1573,7 @@ async function writeAll(db, stmts) {
         await db.batch(stmts.slice(i, i + D1_BATCH));
 }
 /** GSC 段:窗口重拉替换 + 新词回填。任何失败都降级成 note,不中断 check。 */
-async function gscSection(ctx, db, domain, conf, kwRows, notes, win, now) {
+async function gscSection(ctx, db, domain, conf, kwRows, notes, win, now, sitemap, firstSeen) {
     if (conf.gsc_property === GSC_OFF) {
         notes.push("gsc: switched off for this domain (--gsc none) — pass --gsc <property> to turn it back on");
         return null;
@@ -1308,7 +1687,7 @@ async function gscSection(ctx, db, domain, conf, kwRows, notes, win, now) {
     // 自己失败只降级(pages: null + note),不毁掉上面已经算好的 GSC 段。
     let pages = null;
     try {
-        pages = await pagesSection(db, domain, gscClient, property, win, notes, now);
+        pages = await pagesSection(db, domain, gscClient, property, win, notes, now, sitemap, firstSeen);
     }
     catch (e) {
         notes.push(`pages: unavailable this round (${e instanceof Error ? e.message : String(e)})`);
@@ -1323,4 +1702,47 @@ async function gscSection(ctx, db, domain, conf, kwRows, notes, win, now) {
         pages,
     };
 }
+/** 托管站(design/seo-cell-funnel.md §3.2 A):deploy plan 时把清单里的页直接写进 seo_pages(source=deploy),
+ *  族 / 语区 = deploy GEO-ready 按目录派生的 hreflang 族 —— 页面是资产、产品自记,托管站连 sitemap 都不用读。
+ *  best-effort:任何失败都不该拦 deploy(调用方吞掉);首见日期用清单里的 mtime 兜底(同 sitemap 首见表的做法)。 */
+export async function recordDeployedPages(db, host, m, now = Date.now()) {
+    const domain = normalizeHost(host);
+    const today = new Date(now).toISOString().slice(0, 10);
+    const abs = (p) => `https://${domain}${p.startsWith("/") ? p : "/" + p}`;
+    // 反查:URL 形路径 → 族键 + 语区 + 全族 alternates
+    const byPath = new Map();
+    for (const [stem, fam] of Object.entries(m.families)) {
+        const family = familyKeyOf(abs(stem));
+        const alternates = {};
+        for (const [tag, p] of Object.entries(fam))
+            alternates[tag] = abs(p);
+        for (const [tag, p] of Object.entries(fam)) {
+            if (tag.toLowerCase() === "x-default")
+                continue;
+            const prev = byPath.get(p);
+            byPath.set(p, { family, locale: normalizeLocaleTag(tag) ?? prev?.locale ?? null, alternates });
+        }
+    }
+    const stmts = [];
+    let n = 0;
+    for (const [path, f] of Object.entries(m.files)) {
+        if (!isIndexablePage(path))
+            continue;
+        const up = pageUrlPath(path);
+        const url = abs(up);
+        const fam = byPath.get(up);
+        const family = fam?.family ?? familyKeyOf(url);
+        const locale = fam?.locale ?? localeOfUrl(url) ?? DEFAULT_LOCALE;
+        const firstSeen = f.mtime && f.mtime.slice(0, 10) < today ? f.mtime.slice(0, 10) : today;
+        stmts.push(db
+            .prepare("INSERT INTO seo_pages (domain, url, first_seen_at, last_seen_at, source, locale, family, alternates, head_at)" +
+            " VALUES (?,?,?,?,'deploy',?,?,?,?)" +
+            " ON CONFLICT(domain, url) DO UPDATE SET last_seen_at=excluded.last_seen_at, source='deploy'," +
+            " locale=excluded.locale, family=excluded.family, alternates=excluded.alternates, head_at=excluded.head_at")
+            .bind(domain, url, firstSeen, today, locale, family, JSON.stringify(fam?.alternates ?? {}), new Date(now).toISOString()));
+        n++;
+    }
+    await writeAll(db, stmts);
+    return n;
+}
 //# sourceMappingURL=seo.js.map