fix(portal): 藏書地圖看得到自己的知識——租戶字串改從「寫入端」來，不再拿環境變數預設值（Arcrun#108）

leo 2026-08-12 實撞：藏書地圖回 0 個庫，同一分鐘 KBDB 裡有 1854 條三元組， `arcrun_whoami` 顯示 admin／全部知識庫、`kbdb_search` 也查得到——只有地圖那格是空的。病根（不是資料掉了，是讀寫兩端各拿一個來源）：寫入端 owner_id ＝ `~/.arcrun/config.yaml` 的 `api_key`（CLI push／小幫手上傳／MCP， leo ＝ `bfezv28v`）讀取端過濾＝ `portalTenant(env) = env.CONSOLE_TENANT || "leo"` ——repo toml 帶的**官方 prod 值**，而 `acr` 從來不注入 CONSOLE_TENANT ⇒ 那個 `"leo"` 不是理論邊角，是每台 self-hosted 實例的實際行為，1854 條全被濾掉。與 #105（`env.MCP_OWNER_NAMESPACE || "leo"`）同一句話，換一個檔案。租戶字串該從哪裡來（本票的核心判斷）： **從「寫入這批知識的那一方」來，不是從一份手抄的環境變數預設值來。** 不是「掛到每個帳號上」——portal 帳號共用同一台實例的知識庫（design D-2），帳號之間的差別是 libraries 權限不是 owner_id；複製一份到帳號上只是多一個會過期的副本。 #105 真正的教訓是：過濾用的租戶字串要有單一權威來源、解析不到要誠實失敗、且要能機械驗證。修法： 1. 唯一產地 `cypher-executor/src/lib/tenant.ts` - `knowledgeOwner(env)` → branded `TenantId`：`ARCRUN_NAMESPACE` → `CONSOLE_TENANT` → 丟 `TenantUnresolvedError`。**沒有字面預設值**——`|| 'leo'` 正是把「這台機器沒設定」偽裝成「你沒有資料」的元凶。 - `accountTenant(env)` → 普通 `string`（帳號子 namespace `{tenant}::portal` 與 cypher 自己寫的設定用它）。**回 string 是刻意的**：型別上就不可能流進知識資料面。 - 資料面過濾一律經 `ownerQuery()` / `ownerField()`，只吃 `TenantId`。 2. 值的正解由 CLI 從真相源導出：`acr update` 把 config 的 `api_key` 注入成 `ARCRUN_NAMESPACE`，但**先驗再寫**（`GET /kbdb/map?owner_id=<api_key>` 查得到庫才寫；查不到／問不到就一個字都不動）。無條件覆蓋會把「知識本來就在 CONSOLE_TENANT 底下」的一鍵安裝實例指向空的那一格 ——那是 #97/#106 那類「更新一次把人家的東西弄不見」，比原本的 bug 更糟。未注入時回退 CONSOLE_TENANT ⇒ 對官方 prod 與未更新的實例，這次改動是惰性的。 3. 空地圖分四態（沿 #100「讀不到就說讀不到」）：no_library_grant／filtered_out／ scope_mismatch／confirmed_empty。scope_mismatch 以前不存在，所以設定錯誤被畫成「你沒有資料」。回應仍不含租戶字串（design §3.3 紅線）。 4. 同族一起修（同一道閘一次抓到）：console-dashboard 4 處、console-auth 1 處 ——console 首頁的規模數字與藏書地圖對 leo 也一直是空的。留下的閘（規則存在但沒機制驗證＝會再犯第三次）： · 型別閘：TenantId 只能由 tenant.ts 產出 → 拿隨手一個 string 去過濾，tsc 當場不給過。 · 出貨閘：scripts/build-worker-artifacts.mjs 編 tier2 成品前先掃，違規 → 編不出成品。 · 閘自己可測：規則是純函式（tenant-source-rules.mjs），tests/tenant-gate.test.ts 逐條驗「5 種壞例子會擋」＋「11 種合法寫法零誤攔」；掃描範圍只有 src/，擋不到自己。規範寫入 .claude/rules/02-forbidden.md 第六類、system-dev/wiki/mistakes.md #26。沒動：庫權限過濾（一字未改，回歸測試釘住）、帳號資料落點、任何金鑰、租戶字串仍不下發前端。驗證： cypher vitest 441 綠 / 14 紅，14 紅與 base commit e05518a 逐字相同（既有） tsc 5 個既有錯誤，零新增 cli node:test 60/60 綠（含本次新增 12 條）；tsc 零錯誤閘壞例子實跑 exit 1；build 實跑「建置中止」；乾淨時實跑通過端到端 ◐ 未驗：需部署到 leo21c，那道閘要 leo 親手解（見 PR ③） Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-13 00:15:58 +08:00
parent e05518a2b4
commit b223a69884
19 changed files with 1290 additions and 55 deletions
@@ -23,7 +23,10 @@
 import { Hono } from 'hono';
 import type { Context } from 'hono';
 import type { Bindings } from '../types';
-import { kbdbFetch, run, requirePortalUser, parseLibraries, portalTenant, hasGraphAccess, workflowsVisible, uploadEnabled, buildDiagnostics } from './portal';
+import { kbdbFetch, run, requirePortalUser, parseLibraries, hasGraphAccess, workflowsVisible, uploadEnabled, buildDiagnostics } from './portal';
+// Arcrun#108：知識資料面的租戶字串只有一個產地（lib/tenant.ts）。這裡刻意**不再** import
+// portalTenant——它是帳號層的值（回 string 不是 TenantId），拿來過濾知識就是本票的病。
+import { knowledgeOwner, ownerField, ownerQuery, isOwnedBy, censusQueryAllTenants, type TenantId } from '../lib/tenant';
 import { graphBase, graphHeaders } from './kbdb-proxy';
 import { executeWebhookGraph } from '../actions/webhook-handlers';

@@ -40,7 +43,9 @@ export const portalDataRouter = new Hono<{ Bindings: Bindings }>();

 /** 讀 tenant 的 named workflow graph（`{tenant}:wf:{name}`）。不存在/壞 record → null。 */
 async function getTenantWorkflowGraph(env: Bindings, name: string): Promise<Record<string, unknown> | null> {
-  const raw = await env.WEBHOOKS.get(`${portalTenant(env)}:wf:${name}`, 'text');
+  // #108：workflow 是 CLI `acr push` 用實例 namespace 寫進來的（`{ns}:wf:*`），
+  // 所以讀的時候也要用同一個 namespace，不是帳號層那個字串。
+  const raw = await env.WEBHOOKS.get(`${knowledgeOwner(env)}:wf:${name}`, 'text');
  if (!raw) return null;
  try {
    const rec = JSON.parse(raw) as { graph?: Record<string, unknown> };
@@ -190,9 +195,11 @@ export function findBestNodeMatch(searchTerm: string, nodeNames: string[]): stri
 * 三元組條數（KBDB `/records/triplet-stats` 真 SQL COUNT）。owner 傳 '' ＝不限租戶（KBDB 端
 * `?1 = '' OR e.owner_id = ?1`）。null＝讀不到——caller 據此不敢宣稱 0。
 */
-async function tripletCount(env: Bindings, owner: string): Promise<number | null> {
+async function tripletCount(env: Bindings, owner: TenantId | null): Promise<number | null> {
  try {
-    const res = await kbdbFetch(env, `/records/triplet-stats?owner_id=${encodeURIComponent(owner)}`);
+    // owner=null ＝ 普查全庫（#100 用來分辨「查不到」與「沒有」）。這是唯一一個
+    // 刻意不帶租戶範圍的查詢，因此走一支名字就在喊「我沒有租戶範圍」的專用 helper。
+    const res = await kbdbFetch(env, `/records/triplet-stats?${owner === null ? censusQueryAllTenants() : ownerQuery(owner)}`);
    if (!res.ok) return null;
    const body = (await res.json().catch(() => null)) as { stats?: { triplet_count?: unknown }[] } | null;
    if (!body || !Array.isArray(body.stats)) return null;
@@ -219,16 +226,16 @@ async function tripletCount(env: Bindings, owner: string): Promise<number | null
 *   owned=0 但 any>0       → owner_id / 範圍對不上，不是空庫 → 畫面說讀不到
 *   owned=null             → 讀不到 → 畫面說讀不到
 */
-async function tripletCensus(env: Bindings, tenant: string): Promise<{ owned: number | null; any: number | null }> {
+async function tripletCensus(env: Bindings, tenant: TenantId): Promise<{ owned: number | null; any: number | null }> {
  const owned = await tripletCount(env, tenant);
  if (owned !== 0) return { owned, any: null }; // 非 0（含 null）不必多問一次
-  return { owned, any: await tripletCount(env, '') };
+  return { owned, any: await tripletCount(env, null) };
 }

 /** 從 KBDB triplet records 找最佳比對節點名（t96 plugin fuzzy fallback 用）。 */
-async function fuzzyFindNode(env: Bindings, tenant: string, searchTerm: string): Promise<string | null> {
+async function fuzzyFindNode(env: Bindings, tenant: TenantId, searchTerm: string): Promise<string | null> {
  try {
-    const res = await kbdbFetch(env, `/records/by-template/triplet?owner_id=${encodeURIComponent(tenant)}`);
+    const res = await kbdbFetch(env, `/records/by-template/triplet?${ownerQuery(tenant)}`);
    if (!res.ok) return null;
    const body = (await res.json().catch(() => null)) as { records?: { values?: Record<string, unknown> }[] } | null;
    if (!body || !Array.isArray(body.records)) return null;
@@ -263,7 +270,7 @@ portalDataRouter.get('/portal/data/search', (c) =>
      return c.json({ success: true, entries: [], count: 0, mode: 'keyword', note: '此帳號尚未被授權任何知識庫，請聯絡管理員。' });
    }

-    const params = new URLSearchParams({ q, owner_id: portalTenant(c.env) });
+    const params = new URLSearchParams({ q, owner_id: ownerField(knowledgeOwner(c.env)) });
    if (!libraries.includes('*')) params.set('library', libraries.join(','));
    // 透傳的只有「在權限範圍內再收窄」的 filter；owner_id/library 上面已由 server 定死，
    // caller 傳什麼都不看（URLSearchParams 是新建的，蓋不掉）。
@@ -334,7 +341,7 @@ portalDataRouter.get('/portal/data/entries/:id', (c) =>
    const body = (await res.json()) as { entry?: { owner_id?: string | null; metadata_json?: string | null } };
    const entry = body.entry;
    if (!entry) return notFound(c);
-    if ((entry.owner_id ?? '') !== portalTenant(c.env)) return notFound(c);
+    if (!isOwnedBy(entry.owner_id, knowledgeOwner(c.env))) return notFound(c);
    if (!canReadLibrary(libraries, entryLibrary(entry))) return notFound(c);
    return c.json({ success: true, entry });
  }),
@@ -359,7 +366,7 @@ portalDataRouter.get('/portal/data/graph/neighbors/:name', (c) =>
    const nodeName = normalizeCjkQuery(c.req.param('name'));

    // ① tenant workflow 路徑（存在才走；input：node=path、depth=query 預設 2、namespace/owner=tenant）
-    const tenant = portalTenant(c.env);
+    const tenant = knowledgeOwner(c.env);
    const wfGraph = await getTenantWorkflowGraph(c.env, 'graph_neighbors');
    if (wfGraph) {
      const depthRaw = c.req.query('depth') ?? '';
@@ -420,9 +427,9 @@ portalDataRouter.get('/portal/data/graph/overview', (c) =>
    if (!(await hasGraphAccess(c.env, libraries))) {
      return c.json({ error: '無知識圖譜檢視權限' }, 403);
    }
-    const tenant = portalTenant(c.env);
+    const tenant = knowledgeOwner(c.env);
    const [res, census] = await Promise.all([
-      kbdbFetch(c.env, `/records/by-template/triplet?owner_id=${encodeURIComponent(tenant)}&limit=500`),
+      kbdbFetch(c.env, `/records/by-template/triplet?${ownerQuery(tenant)}&limit=500`),
      tripletCensus(c.env, tenant),
    ]);
    const tripletsTotal = census.owned;
@@ -505,7 +512,7 @@ portalDataRouter.get('/portal/data/chat', (c) =>
      wfGraph,
      { question },
      'rag_chat',
-      portalTenant(c.env),
+      knowledgeOwner(c.env),
      c.executionCtx,
    );
    if (!result.success) {
@@ -611,7 +618,7 @@ portalDataRouter.get('/portal/data/workflows', (c) =>
    // 資料源與 /webhooks/named ＋ /workflows/:name/executions 同一份（WEBHOOKS/ANALYTICS KV）。
    // 不經 HTTP 打自己（global_fetch_strictly_public 下 fetch 自己 hostname 會 self-loop），
    // 直讀同 worker 的 KV binding；欄位收斂成唯讀展示需要的最小集合。
-    const tenant = portalTenant(c.env);
+    const tenant = knowledgeOwner(c.env);
    const prefix = `${tenant}:wf:`;
    const list = await c.env.WEBHOOKS.list({ prefix });
    const workflows = await Promise.all(
@@ -637,7 +644,7 @@ portalDataRouter.get('/portal/data/workflows', (c) =>
        let last_execution: { timestamp: string; verdict?: string } | null = null;
        const execRes = await kbdbFetch(
          c.env,
-          `/execution-log/latest?${new URLSearchParams({ workflow_id: name, owner_id: tenant }).toString()}`,
+          `/execution-log/latest?${new URLSearchParams({ workflow_id: name, owner_id: ownerField(tenant) }).toString()}`,
        );
        const execBody = await execRes.json().catch(() => null) as {
          success?: boolean;
@@ -691,25 +698,42 @@ function recordLibrary(values: Record<string, unknown> | undefined): string | nu
 /** record 可讀？租戶要對；有標 library 的還要在用戶庫集合內。 */
 function canReadRecord(
  rec: { values?: Record<string, unknown>; owner_id?: string | null },
-  tenant: string,
+  tenant: TenantId,
  libraries: string[],
 ): boolean {
-  if ((rec.owner_id ?? '') !== tenant) return false;
+  if (!isOwnedBy(rec.owner_id, tenant)) return false;
  const lib = recordLibrary(rec.values);
  return lib === null || canReadLibrary(libraries, lib);
 }

 // GET /portal/data/map — 藏書地圖全館視圖，**只回這個帳號有權限的庫**。
 // KBDB 的 /map 對權限無知（它回全館），過濾在這裡做——MCP 不得比 portal 同一個帳號看得更多。
+//
+// 🔴 Arcrun#108：一張空地圖有四種成因，**判準留在 server，不留給前端猜**
+//    （沿 #100 總圖那條「讀不到就說讀不到」，同一套 census 機制）：
+//      no_library_grant ：這個帳號一個庫都沒被授權 → 是權限問題，不是資料問題
+//      filtered_out     ：實例有庫，但都不在這個帳號的權限內 → 正常且正確的隔離
+//      confirmed_empty  ：實例真的一條三元組都沒有 → **只有此時**才准說「還沒有知識」
+//      scope_mismatch   ：實例有三元組，但本命名空間一條都撈不到 → **命名空間對不上**
+//                        （就是本票：1854 條在 bfezv28v，卻拿 "leo" 去過濾）
+//    scope_mismatch 這一格以前不存在，所以設定錯誤被畫成「你沒有資料」——leo 看到的空地圖。
+//
+// ⚠️ 回應**絕不含租戶字串**（design §3.3 紅線：前端拿到租戶字串就能繞過庫過濾直打 /kbdb/*）。
+//    只回代碼與數字，文字說明講「請通知管理員」，命名空間本身不下發。
 portalDataRouter.get('/portal/data/map', (c) =>
  run(c, async () => {
    const auth = await requirePortalUser(c);
    if (!auth.ok) return auth.res;
    const libraries = parseLibraries(auth.user.values.libraries);
    if (libraries.length === 0) {
-      return c.json({ success: true, libraries: [], count: 0, note: '此帳號尚未被授權任何知識庫，請聯絡管理員。' });
+      return c.json({
+        success: true, libraries: [], count: 0,
+        empty_confirmed: true, empty_reason: 'no_library_grant',
+        note: '此帳號尚未被授權任何知識庫，請聯絡管理員。',
+      });
    }
-    const res = await kbdbFetch(c.env, `/map?owner_id=${encodeURIComponent(portalTenant(c.env))}`);
+    const tenant = knowledgeOwner(c.env);
+    const res = await kbdbFetch(c.env, `/map?${ownerQuery(tenant)}`);
    if (!res.ok) {
      return new Response(res.body, { status: res.status, headers: { 'Content-Type': 'application/json' } });
    }
@@ -720,7 +744,42 @@ portalDataRouter.get('/portal/data/map', (c) =>
    const allowed = body.libraries.filter(
      (l) => typeof l?.library === 'string' && canReadLibrary(libraries, l.library),
    );
-    return c.json({ success: true, libraries: allowed, count: allowed.length });
+    if (allowed.length > 0) {
+      return c.json({ success: true, libraries: allowed, count: allowed.length, empty_confirmed: false, empty_reason: null });
+    }
+    // 以下都是「回空」的路徑——多花一次查詢換一個**有根據**的理由，不猜。
+    if (body.libraries.length > 0) {
+      // 命名空間對得上（撈得到庫），只是這個帳號沒有那些庫的權限＝隔離正常運作。
+      return c.json({
+        success: true, libraries: [], count: 0,
+        empty_confirmed: true, empty_reason: 'filtered_out',
+        note: '這個帳號目前沒有任何知識庫的檢視權限，請聯絡管理員開通。',
+      });
+    }
+    const census = await tripletCensus(c.env, tenant);
+    if (census.owned === null || (census.owned === 0 && census.any === null)) {
+      return c.json({
+        success: true, libraries: [], count: 0,
+        empty_confirmed: false, empty_reason: 'unreadable',
+        note: '讀不到知識庫的統計，無法確認庫裡有沒有東西——這不是「還沒有知識」，是這次讀取失敗。請稍後重整或通知管理員。',
+      });
+    }
+    if (census.owned === 0 && (census.any ?? 0) > 0) {
+      return c.json({
+        success: true, libraries: [], count: 0,
+        empty_confirmed: false, empty_reason: 'scope_mismatch',
+        instance_triplet_count: census.any,
+        note:
+          `讀不到你這個帳號範圍內的藏書——但這台實例裡有 ${census.any} 條知識關聯。` +
+          '這不是「還沒有知識」，不用去重新上傳；比較像知識的歸屬命名空間對不上。' +
+          '請通知管理員跑一次 `acr update`（會把你安裝時的命名空間同步給雲端），或檢查 ARCRUN_NAMESPACE 設定。',
+      });
+    }
+    return c.json({
+      success: true, libraries: [], count: 0,
+      empty_confirmed: true, empty_reason: 'confirmed_empty',
+      note: '知識庫還沒有任何內容——上傳文件後就會出現在這裡。',
+    });
  }),
 );

@@ -734,7 +793,7 @@ portalDataRouter.get('/portal/data/map/:library', (c) =>
    if (!canReadLibrary(libraries, library)) return notFound(c);
    const res = await kbdbFetch(
      c.env,
-      `/map/${encodeURIComponent(library)}?owner_id=${encodeURIComponent(portalTenant(c.env))}`,
+      `/map/${encodeURIComponent(library)}?${ownerQuery(knowledgeOwner(c.env))}`,
    );
    if (res.status === 404) return notFound(c);
    if (!res.ok) return c.json({ error: `KBDB 回錯（HTTP ${res.status}）` }, 502);
@@ -775,7 +834,7 @@ portalDataRouter.post('/portal/data/templates', (c) =>
        name: body.name,
        slots: body.slots,
        description: typeof body.description === 'string' ? body.description : undefined,
-        created_by: portalTenant(c.env),
+        created_by: knowledgeOwner(c.env),
      }),
    });
    return new Response(res.body, { status: res.status, headers: { 'Content-Type': 'application/json' } });
@@ -790,10 +849,10 @@ portalDataRouter.get('/portal/data/records/by-template/:template', (c) =>
    if (!auth.ok) return auth.res;
    const libraries = parseLibraries(auth.user.values.libraries);
    if (libraries.length === 0) return c.json({ success: true, records: [], count: 0 });
-    const tenant = portalTenant(c.env);
+    const tenant = knowledgeOwner(c.env);
    const res = await kbdbFetch(
      c.env,
-      `/records/by-template/${encodeURIComponent(c.req.param('template'))}?owner_id=${encodeURIComponent(tenant)}`,
+      `/records/by-template/${encodeURIComponent(c.req.param('template'))}?${ownerQuery(tenant)}`,
    );
    if (!res.ok) return c.json({ error: `KBDB 回錯（HTTP ${res.status}）` }, 502);
    const body = (await res.json().catch(() => null)) as
@@ -824,7 +883,7 @@ portalDataRouter.get('/portal/data/records/:recordId', (c) =>
      | null;
    const record = body?.record;
    if (!record) return notFound(c);
-    if (!canReadRecord(record, portalTenant(c.env), libraries)) return notFound(c);
+    if (!canReadRecord(record, knowledgeOwner(c.env), libraries)) return notFound(c);
    return c.json({ success: true, record });
  }),
 );
@@ -856,7 +915,7 @@ portalDataRouter.post('/portal/data/records', (c) =>
    const res = await kbdbFetch(c.env, '/records', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ template: body.template, values, owner_id: portalTenant(c.env) }),
+      body: JSON.stringify({ template: body.template, values, owner_id: ownerField(knowledgeOwner(c.env)) }),
    });
    return new Response(res.body, { status: res.status, headers: { 'Content-Type': 'application/json' } });
  }),
@@ -884,7 +943,7 @@ portalDataRouter.get('/portal/data/diagnostics', (c) =>
  run(c, async () => {
    const auth = await requirePortalUser(c);
    if (!auth.ok) return auth.res;
-    const tenant = portalTenant(c.env);
+    const tenant = knowledgeOwner(c.env);
    const core = await buildDiagnostics(c.env, tenant);
    return c.json({
      generated_at: new Date().toISOString(),