@lark-apaas/coding-miaoda-sandbox-skills 0.1.0-dev.6f4e4bc → 0.1.0-dev.72ac425

package/miaoda/lark-design-prototype/scripts/icon-query.mjs

@@ -0,0 +1,272 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+
+const SVG_BASE = 'https://cdn-tos-cn.bytedance.net/obj/archi/ee/es-design-base/svgs';
+const REMOTE_CATALOG =
+  'https://lf3-static.bytednsdoc.com/obj/eden-cn/pshi/lark-design-prototype/1.0.4/db71a6cd-33f97519-0d446cd5/icons.catalog.json';
+const REMOTE_CATALOG_SHA256 = 'db71a6cd6ac90c77629e8ce0fc0905ca1488a6601800ff7533385490b10eac9d';
+
+function usage() {
+  return `Usage:
+  node icon-query.mjs [--catalog <remote|catalog.json|url>] --query "<keywords>" [--family outlined] [--style v2-outlined|source-outlined|source-filled|source-colorful] [--shape normal|round] [--prefer-v2] [--require-v2] [--limit 5]
+
+Returns a compact JSON array with name, hash, family, version, shape, score, description, and final svgUrl.
+Never print the raw icon catalog during page generation.`;
+}
+
+function argValue(name, fallback = '') {
+  const index = process.argv.indexOf(name);
+  return index === -1 ? fallback : process.argv[index + 1] || fallback;
+}
+
+function argFlag(name) {
+  return process.argv.includes(name);
+}
+
+function tokenize(text) {
+  const rawTokens = String(text || '')
+    .toLowerCase()
+    .split(/[\s,，、:：;；/|()（）\[\]{}'"`<>.!?？。_-]+/)
+    .map((item) => item.trim())
+    .filter(Boolean);
+  const aliases = {
+    搜索: ['search'],
+    查找: ['search'],
+    通知: ['notification', 'bell'],
+    提醒: ['reminder', 'bell'],
+    主页: ['home'],
+    首页: ['home'],
+    模板: ['template'],
+    文档: ['doc', 'document', 'file'],
+    document: ['doc'],
+    文件: ['file'],
+    文件夹: ['folder'],
+    表格: ['sheet', 'table', 'bitable'],
+    spreadsheet: ['sheet'],
+    table: ['sheet'],
+    图表: ['chart'],
+    看板: ['dashboard', 'chart'],
+    帮助: ['help', 'faq'],
+    指南: ['guide', 'info'],
+    飞书: ['feishu', 'lark', 'logo', 'logotype'],
+    品牌: ['brand', 'logo', 'logotype'],
+    标识: ['logo', 'logotype'],
+    logo: ['brand', 'logotype'],
+  };
+  const expanded = new Set(rawTokens);
+  for (const token of rawTokens) {
+    for (const alias of aliases[token] || []) {
+      expanded.add(alias);
+    }
+  }
+  return [...expanded];
+}
+
+async function readJsonFile(filePath) {
+  const text = await fs.readFile(filePath, 'utf8');
+  return JSON.parse(text);
+}
+
+async function readCatalog(source) {
+  const resolved = !source || source === 'remote' ? REMOTE_CATALOG : source;
+  if (/^https?:\/\//.test(resolved)) {
+    const response = await fetch(resolved);
+    if (!response.ok) {
+      throw new Error(`Catalog request failed with HTTP ${response.status}`);
+    }
+    const text = await response.text();
+    if (resolved === REMOTE_CATALOG) {
+      const actualHash = createHash('sha256').update(text).digest('hex');
+      if (actualHash !== REMOTE_CATALOG_SHA256) {
+        throw new Error(
+          `Catalog integrity check failed: expected ${REMOTE_CATALOG_SHA256}, got ${actualHash}`,
+        );
+      }
+    }
+    return { catalog: JSON.parse(text), catalogSource: resolved };
+  }
+  const filePath = path.resolve(resolved);
+  return { catalog: await readJsonFile(filePath), catalogSource: filePath };
+}
+
+function detectVersion(name) {
+  return /(?:^|[-_])v2(?:[-_]|$)/i.test(name) ? 'v2' : 'non-v2';
+}
+
+function detectShape(icon) {
+  const name = icon.name.toLowerCase();
+  if (name.includes('file-round-') || name.includes('wiki-round-')) return 'round';
+  if (icon.family === 'colorful' && /(?:icon_|wiki-)?file[-_]/.test(name)) return 'normal';
+  return 'none';
+}
+
+function detectStyleType(icon) {
+  const version = detectVersion(icon.name);
+  const shape = detectShape(icon);
+  if (icon.family === 'outlined') {
+    return version === 'v2' ? 'v2-outlined' : 'non-v2-outlined';
+  }
+  if (icon.family === 'filled') {
+    return 'source-filled';
+  }
+  if (icon.family === 'colorful' && /(?:feishu|lark).*logo|logotype|logo/i.test(icon.name)) {
+    return 'brand-colorful';
+  }
+  if (icon.family === 'colorful' && version === 'v2' && shape === 'round') {
+    return 'file-v2-colorful-round';
+  }
+  if (icon.family === 'colorful' && version === 'v2' && shape === 'normal') {
+    return 'file-v2-colorful-normal';
+  }
+  return icon.family;
+}
+
+function normalizeOptions() {
+  const style = argValue('--style');
+  const options = {
+    family: argValue('--family', 'outlined'),
+    style,
+    shape: argValue('--shape'),
+    preferV2: argFlag('--prefer-v2'),
+    requireV2: argFlag('--require-v2'),
+    requireNonV2: argFlag('--require-non-v2'),
+    include: argValue('--name-include'),
+    exclude: argValue('--name-exclude'),
+  };
+
+  if (style === 'v2-outlined') {
+    options.family = 'outlined';
+    options.requireV2 = true;
+  } else if (style === 'non-v2-outlined') {
+    options.family = 'outlined';
+    options.requireNonV2 = true;
+  } else if (style === 'file-v2-colorful-normal') {
+    options.family = 'colorful';
+    options.requireV2 = true;
+    options.shape = 'normal';
+    options.include ||= 'file';
+  } else if (style === 'file-v2-colorful-round') {
+    options.family = 'colorful';
+    options.requireV2 = true;
+    options.shape = 'round';
+    options.include ||= 'file-round';
+  } else if (style === 'source-outlined') {
+    options.family = 'outlined';
+    options.preferV2 = true;
+  } else if (style === 'source-filled') {
+    options.family = 'filled';
+  } else if (style === 'brand-colorful' || style === 'source-colorful') {
+    options.family = 'colorful';
+    if (style === 'source-colorful') {
+      options.preferV2 = true;
+    }
+  }
+  return options;
+}
+
+function flattenCatalog(catalog, options) {
+  const rows = [];
+  for (const category of catalog) {
+    for (const [family, icons] of Object.entries(category.icons || {})) {
+      if (options.family && family !== options.family) {
+        continue;
+      }
+      for (const icon of icons || []) {
+        const row = {
+          category: category.id || '',
+          family,
+          name: icon.name,
+          hash: icon.hash,
+          darkHash: icon.darkHash,
+          description: icon.description || '',
+        };
+        row.version = detectVersion(row.name);
+        row.shape = detectShape(row);
+        row.styleType = detectStyleType(row);
+        rows.push(row);
+      }
+    }
+  }
+  return rows;
+}
+
+function passesFilters(icon, options) {
+  const name = icon.name.toLowerCase();
+  if (options.requireV2 && icon.version !== 'v2') return false;
+  if (options.requireNonV2 && icon.version !== 'non-v2') return false;
+  if (options.shape && icon.shape !== options.shape) return false;
+  if (options.include && !name.includes(options.include.toLowerCase())) return false;
+  if (options.exclude && name.includes(options.exclude.toLowerCase())) return false;
+  const sourceStyles = new Set(['source-outlined', 'source-filled', 'source-colorful']);
+  if (options.style && !sourceStyles.has(options.style) && icon.styleType !== options.style)
+    return false;
+  return true;
+}
+
+function scoreIcon(icon, queryTokens, options) {
+  const name = icon.name.toLowerCase();
+  const description = icon.description.toLowerCase();
+  let score = 0;
+  for (const token of queryTokens) {
+    if (name.includes(token)) score += 5;
+    if (description.includes(token)) score += 3;
+    if (name === `icon_${token}_outlined`) score += 8;
+    if (name === `icon_${token}-v2_outlined`) score += 8;
+    if (name === `icon_${token}_filled`) score += 8;
+    if (name === `icon_file-${token}-v2_colorful`) score += 8;
+  }
+  if (score === 0) return 0;
+  if (icon.family === 'outlined') score += 1;
+  if ((options.preferV2 || options.style?.includes('v2')) && icon.version === 'v2') score += 4;
+  if (
+    options.style === 'brand-colorful' &&
+    /feishu|lark|logotype|logo/i.test(`${name} ${description}`)
+  )
+    score += 10;
+
+  const objectTokens = ['doc', 'document', 'file', 'card', 'sheet', 'bitable', 'ai'];
+  const queryHasObject = objectTokens.some((token) => queryTokens.includes(token));
+  if (
+    !queryHasObject &&
+    objectTokens.some((token) => name.includes(`_${token}`) || name.includes(`-${token}`))
+  ) {
+    score -= 3;
+  }
+  return score;
+}
+
+const catalogSource = argValue('--catalog', 'remote');
+const query = argValue('--query');
+const limit = Math.max(1, Number.parseInt(argValue('--limit', '5'), 10) || 5);
+
+if (!query) {
+  console.error(usage());
+  process.exit(2);
+}
+
+const options = normalizeOptions();
+const queryTokens = tokenize(query);
+const { catalog, catalogSource: usedCatalogSource } = await readCatalog(catalogSource);
+const matches = flattenCatalog(catalog, options)
+  .filter((icon) => passesFilters(icon, options))
+  .map((icon) => ({ ...icon, score: scoreIcon(icon, queryTokens, options) }))
+  .filter((icon) => icon.score > 0)
+  .sort((a, b) => b.score - a.score || a.name.localeCompare(b.name))
+  .slice(0, limit)
+  .map((icon) => ({
+    name: icon.name,
+    hash: icon.hash,
+    darkHash: icon.darkHash || undefined,
+    family: icon.family,
+    version: icon.version,
+    shape: icon.shape,
+    styleType: icon.styleType,
+    score: icon.score,
+    description: icon.description.slice(0, 180),
+    svgUrl: `${SVG_BASE}/${icon.name}.${icon.hash}.svg`,
+    catalogSource: usedCatalogSource,
+  }));
+
+console.log(JSON.stringify(matches, null, 2));

package/miaoda/lark-design-prototype/scripts/token-query.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+import { createHash } from 'node:crypto';
+
+const SOURCES = {
+  semantic: {
+    url: 'https://lf3-static.bytednsdoc.com/obj/eden-cn/pshi/lark-design-prototype/1.0.4/db71a6cd-33f97519-0d446cd5/semantic.json',
+    sha256: '33f975193bcd0b5b12df9003e6f8586bf4662336e0bd5cf73ea1f362cfa4eb50',
+  },
+  keys: {
+    url: 'https://lf3-static.bytednsdoc.com/obj/eden-cn/pshi/lark-design-prototype/1.0.4/db71a6cd-33f97519-0d446cd5/keys.json',
+    sha256: '0d446cd57b0beaaaa9ba485009b31a73be77d5f87a8481ec032c54f33b3bb471',
+  },
+};
+
+function usage() {
+  return `Usage:
+  node token-query.mjs --query "<token name or intent>" [--source semantic|keys] [--limit 5]
+
+Fetches the versioned public token resource, verifies SHA-256, and returns compact matches.`;
+}
+
+function argValue(name, fallback = '') {
+  const index = process.argv.indexOf(name);
+  return index === -1 ? fallback : process.argv[index + 1] || fallback;
+}
+
+function tokenize(value) {
+  return String(value || '')
+    .toLowerCase()
+    .split(/[\s,，、:：;；/|()（）\[\]{}'"`<>.!?？。_-]+/)
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function scoreEntry([key, value], query, queryTokens) {
+  const normalizedKey = key.toLowerCase();
+  const searchText = `${key} ${value?.$description || ''} ${value?.$extensions?.id || ''} ${
+    value?.$extensions?.name || ''
+  }`.toLowerCase();
+  let score = normalizedKey === query ? 100 : normalizedKey.includes(query) ? 40 : 0;
+  for (const token of queryTokens) {
+    if (normalizedKey.includes(token)) score += 10;
+    if (searchText.includes(token)) score += 3;
+  }
+  return score;
+}
+
+const sourceName = argValue('--source', 'semantic');
+const source = SOURCES[sourceName];
+const query = argValue('--query').trim().toLowerCase();
+const limit = Math.max(1, Number.parseInt(argValue('--limit', '5'), 10) || 5);
+
+if (!source || !query) {
+  console.error(usage());
+  process.exit(2);
+}
+
+const response = await fetch(source.url);
+if (!response.ok) {
+  throw new Error(`Token request failed with HTTP ${response.status}`);
+}
+const text = await response.text();
+const actualHash = createHash('sha256').update(text).digest('hex');
+if (actualHash !== source.sha256) {
+  throw new Error(`Token integrity check failed: expected ${source.sha256}, got ${actualHash}`);
+}
+
+const queryTokens = tokenize(query);
+const matches = Object.entries(JSON.parse(text))
+  .map((entry) => ({ entry, score: scoreEntry(entry, query, queryTokens) }))
+  .filter(({ score }) => score > 0)
+  .sort((a, b) => b.score - a.score || a.entry[0].localeCompare(b.entry[0]))
+  .slice(0, limit)
+  .map(({ entry: [key, value] }) => ({ key, ...value, source: source.url }));
+
+console.log(JSON.stringify(matches, null, 2));

package/miaoda/lark-design-prototype/scripts/verify-static-html.mjs

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+function usage() {
+  return `Usage:
+  node verify-static-html.mjs <file.html> [--sidebar]
+
+Runs token-light pre-browser checks for Lark-style static HTML deliverables.
+Use --sidebar only when the page contains a navigation sidebar. Shadow declarations are reported for contextual review.`;
+}
+
+const htmlPath = process.argv[2];
+if (!htmlPath) {
+  console.error(usage());
+  process.exit(2);
+}
+
+const absoluteHtmlPath = path.resolve(htmlPath);
+const html = await fs.readFile(absoluteHtmlPath, 'utf8');
+
+const hardFailures = [];
+const warnings = [];
+const passed = [];
+
+function pass(name, ok, failMessage, warn = false) {
+  if (ok) {
+    passed.push(name);
+  } else if (warn) {
+    warnings.push(failMessage);
+  } else {
+    hardFailures.push(failMessage);
+  }
+}
+
+pass(
+  'no gradients',
+  !/(linear-gradient|radial-gradient|conic-gradient)/i.test(html),
+  'Page UI contains gradients.',
+);
+const shadows = [...html.matchAll(/box-shadow\s*:\s*([^;}"'<>]+)/gi)]
+  .map((match) => match[1].trim())
+  .filter((value) => !/^none(?:\s*!important)?$/i.test(value));
+pass(
+  'no shadows requiring contextual review',
+  shadows.length === 0,
+  'Shadow declarations found; verify they belong to permitted floating layers, not ordinary cards.',
+  true,
+);
+if (process.argv.includes('--sidebar')) {
+  pass(
+    'fixed sidebar background',
+    html.includes('#f9f9f9'),
+    'Sidebar background #f9f9f9 is missing.',
+  );
+  pass(
+    'fixed selected sidebar state',
+    html.includes('#1f23290d'),
+    'Selected sidebar state #1f23290d is missing.',
+  );
+}
+pass('has table', /<table[\s>]/i.test(html), 'No table found.', true);
+pass('has search input', /type=["']search["']/i.test(html), 'No search input found.', true);
+pass(
+  'has local responsive CSS',
+  /@media\s*\(/i.test(html),
+  'No responsive media query found.',
+  true,
+);
+
+const imageRefs = [...html.matchAll(/<img\b[^>]*\bsrc=["']([^"']+)["']/gi)].map(
+  (match) => match[1],
+);
+const localImageRefs = imageRefs.filter(
+  (src) => !/^(https?:)?\/\//.test(src) && !src.startsWith('data:'),
+);
+const missingImages = [];
+for (const src of localImageRefs) {
+  try {
+    await fs.access(new URL(src, pathToFileURL(absoluteHtmlPath)));
+  } catch {
+    missingImages.push(src);
+  }
+}
+
+pass(
+  'all local images exist',
+  missingImages.length === 0,
+  `Missing local image assets: ${missingImages.join(', ')}`,
+);
+
+const tableHeaders = [...html.matchAll(/<th\b[^>]*>([\s\S]*?)<\/th>/gi)]
+  .map((match) => match[1].replace(/<[^>]+>/g, '').trim())
+  .filter(Boolean);
+
+console.log(
+  JSON.stringify(
+    {
+      file: absoluteHtmlPath,
+      passed,
+      warnings,
+      hardFailures,
+      stats: {
+        images: imageRefs.length,
+        localImages: localImageRefs.length,
+        tableHeaders,
+      },
+    },
+    null,
+    2,
+  ),
+);
+
+if (hardFailures.length > 0) {
+  process.exit(1);
+}

package/miaoda/performance-review/SKILL.md

@@ -59,11 +59,11 @@ const userMap = new Map(users.map(u => [u.id, u]));
 - N+1 queries: per-item DB calls inside loops — use batch or JOIN
 - List endpoints without pagination — will break as data grows
 - OFFSET pagination on large datasets — use cursor pagination (WHERE id > cursor)
-- Multiple independent DB queries running serially — use Promise.all
+- Multiple independent DB queries running serially — use Promise.all. The platform connection pool caps real concurrency at **7**; beyond that queries queue. It only pays off for IO-bound queries — CPU-heavy ones (large aggregations, big `generate_series`) still take the same total time, so for those the only fix is fewer/cheaper queries
 - External API calls without timeout
-- WHERE/ORDER BY columns missing indexes — **cross-check with schema definition: for every ORDER BY or WHERE column in service queries, verify a matching index exists in schema.ts**
+- WHERE/ORDER BY columns missing indexes — **cross-check against the live DDL: for every ORDER BY or WHERE column in service queries, verify a matching index exists via `npx -y @lark-apaas/miaoda-data-cli db schema <table>`. Do NOT use `schema.ts` for this — it is a generated mirror that silently drops partial-index `WHERE` clauses and CHECK constraints, so an existing partial index reads as missing (and a partial unique index reads as full-table unique)**
 - Aggregation done in JS instead of SQL layer — fetch all rows then compute in app is a common anti-pattern
-- **Sorting fields used in list/ranking endpoints must have database indexes — read schema.ts and verify**
+- **Sorting fields used in list/ranking endpoints must have database indexes — verify with `db schema <table>` (the live DDL), not `schema.ts`**
 - **Date-range loop expansion in JS (CRITICAL)**: code shaped like `for (let d = new Date(start); d <= end; d.setDate(d.getDate()+1)) for (item of items) ...` is O(N×days). For 1000 records over 90 days = 90,000 ops per request. Must be pushed to SQL using `generate_series(start, end, '1 day') + unnest(array_field) + GROUP BY ... HAVING COUNT(*) > N` — let the database do the date×row cross product
 - **Multiple endpoints sharing the same base data should be merged**: e.g. Dashboard frontend calling 4 separate stats endpoints, each internally re-querying the full teacher table to build a lookup map. Merge into a single overview endpoint that runs the 4 stats in parallel internally and shares one base-data query.
 - **Stats / Dashboard endpoints must have a default time window**: any query that scans the entire fact table for aggregation (`select ... from coursePlan` with no `where`) will degrade as data grows. Add a default `where startDate >= now() - interval '90 day'` (or business-appropriate window) so it can hit `idx_*_start_date`. Without a time window, even with indexes the planner may still seq-scan. If "all history" is required, use a materialized view or pre-aggregated table refreshed on schedule, never a live full-table scan.

package/miaoda/semantic-search/SKILL.md

@@ -57,6 +57,8 @@ SELECT rds_ai.ai_embed('你好')::vector;
 -- → vector(1024)
 ```
 
+⚠️ **模型可用性由租户管理后台管控。** embedding 仅此一个模型、无备选，管理员将其下架或停用后 `rds_ai.ai_embed` 即不可用，调用报 `model_unavailable`（处置见「关键注意事项」）。
+
 ## 实现步骤
 
 以下 SQL 使用 `products` / `embedding` 作为示例。Agent 生成实际方案时，必须替换成用户应用里的真实表名、字段名、主键、返回列和索引名。
@@ -281,14 +283,15 @@ LIMIT 10;
 
 ## 关键注意事项
 
-### ⚠️ ai_embed 报错优先看状态码：422 (额度不足) / 429 (限流)
+### ⚠️ ai_embed 报错优先看状态码：422 (额度不足) / 429 (限流) / 500 (无可用模型)
 
-`rds_ai.ai_embed` 抛错时，PG 错误信息里通常会带 HTTP 状态码或 `quota_exceeded` / `rate_limit_exceeded` 关键字。识别后给用户的提示要分开：
+`rds_ai.ai_embed` 抛错时，PG 错误信息里通常会带 HTTP 状态码或 `quota_exceeded` / `rate_limit_exceeded` / `model_unavailable` 关键字。识别后给用户的提示要分开：
 
 - **422 / quota_exceeded** — 当前应用的 AI 调用额度已用完。提示用户：「AI 调用额度已耗尽，请联系应用 Owner 在控制台续费或升级套餐后再试」。**不要重试**，重试只会继续报错。
 - **429 / rate_limit_exceeded** — 调用过于密集触发限流。提示用户：「AI 调用过于频繁触发了限流，稍后再试，或调小回填批次 / 降低并发即可恢复」。**可重试**，建议指数退避。
+- **500 / model_unavailable** — 租户预置的 embedding 模型已被管理员下架或停用，且无备选模型。提示用户：「当前租户无可用 AI 模型，请联系租户管理员恢复后再试」。**不要重试**，模型恢复后重跑存量回填即可。
 
-trigger 已经用 `EXCEPTION WHEN OTHERS THEN NEW.embedding := NULL` 兜住单条失败，业务写入不会回滚；后续走存量回填补齐。批量回填（步骤 7）建议捕获错误码：遇到 422 立刻停止整批并提示续费，遇到 429 退避后续跑。
+trigger 已经用 `EXCEPTION WHEN OTHERS THEN NEW.embedding := NULL` 兜住单条失败，业务写入不会回滚；后续走存量回填补齐。批量回填（步骤 7）建议捕获错误码：遇到 422 立刻停止整批并提示续费，遇到 429 退避后续跑，遇到 500 停整批并提示联系租户管理员。
 
 ### ⚠️ 同步 trigger 调 rds_ai.ai_embed 必须 BEGIN/EXCEPTION 兜底