From bb25eb8bcb7f03b25d4c596f21037e584c9a271a Mon Sep 17 00:00:00 2001
From: williamfzc <178894043@qq.com>
Date: Tue, 31 Mar 2026 10:57:40 +0800
Subject: [PATCH 01/19] feat(ci): add PR size label pipeline

---
 .github/workflows/pr-labels.yml |  31 +++
 scripts/sync_pr_labels.js       | 470 ++++++++++++++++++++++++++++++++
 2 files changed, 501 insertions(+)
 create mode 100644 .github/workflows/pr-labels.yml
 create mode 100644 scripts/sync_pr_labels.js

diff --git a/.github/workflows/pr-labels.yml b/.github/workflows/pr-labels.yml
new file mode 100644
index 0000000000..2586c0c33c
--- /dev/null
+++ b/.github/workflows/pr-labels.yml
@@ -0,0 +1,31 @@
+name: PR Labels
+
+on:
+  pull_request_target:
+    types:
+      - opened
+      - reopened
+      - synchronize
+      - ready_for_review
+
+permissions:
+  contents: read
+  pull-requests: read
+  # PR labels are managed through the issues API.
+  issues: write
+
+jobs:
+  sync-pr-labels:
+    if: ${{ github.event.pull_request.state == 'open' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - uses: actions/setup-node@49933ea5288caeca8642e03cb748f7d9d40d8f46 # v4
+        with:
+          node-version: '20'
+
+      - name: Sync managed PR labels
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: node scripts/sync_pr_labels.js
diff --git a/scripts/sync_pr_labels.js b/scripts/sync_pr_labels.js
new file mode 100644
index 0000000000..968363f9ef
--- /dev/null
+++ b/scripts/sync_pr_labels.js
@@ -0,0 +1,470 @@
+#!/usr/bin/env node
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+const fs = require("node:fs/promises");
+const path = require("node:path");
+
+const API_BASE = "https://api.github.com";
+const SCRIPT_DIR = __dirname;
+const ROOT = path.join(SCRIPT_DIR, "..");
+
+const LABEL_DEFINITIONS = {
+  "size/S": { color: "77bb00", description: "Low-risk docs, CI, test, or chore only changes" },
+  "size/M": { color: "eebb00", description: "Single-domain feat or fix with limited business impact" },
+  "size/L": { color: "ff8800", description: "Large or sensitive change across domains or core paths" },
+  "size/XL": { color: "ee0000", description: "Architecture-level or global-impact change" },
+};
+
+const MANAGED_LABELS = new Set(Object.keys(LABEL_DEFINITIONS));
+
+const DOC_SUFFIXES = [".md", ".mdx", ".txt", ".rst"];
+const LOW_RISK_PREFIXES = [".github/", "docs/", ".changeset/", "testdata/", "tests/", "skill-template/"];
+const LOW_RISK_FILENAMES = new Set(["readme.md", "readme.zh.md", "changelog.md", "license", "cla.md"]);
+const LOW_RISK_TEST_SUFFIXES = ["_test.go", ".snap"];
+
+const CORE_PREFIXES = ["internal/auth/", "internal/engine/", "internal/config/", "cmd/"];
+const HEAD_BUSINESS_DOMAINS = new Set(["im", "contact", "ccm", "base", "docx"]);
+const LOW_RISK_TYPES = new Set(["docs", "ci", "test", "chore"]);
+
+const CLASS_STANDARDS = {
+  "size/S": {
+    channel: "Fast track (S)",
+    gates: [
+      "Code quality: AI code review passed",
+      "Dependency and configuration security checks passed",
+    ],
+  },
+  "size/M": {
+    channel: "Fast track (M)",
+    gates: [
+      "Code quality: AI code review passed",
+      "Dependency and configuration security checks passed",
+      "Skill format validation: added or modified Skills load successfully",
+      "CLI automation tests: all required business-line tests passed",
+    ],
+  },
+  "size/L": {
+    channel: "Standard track (L)",
+    gates: [
+      "Code quality: AI code review passed",
+      "Dependency and configuration security checks passed",
+      "Skill format validation: added or modified Skills load successfully",
+      "CLI automation tests: all required business-line tests passed",
+      "Domain evaluation passed: reported success rate is greater than 95%",
+    ],
+  },
+  "size/XL": {
+    channel: "Strict track (XL)",
+    gates: [
+      "Code quality: AI code review passed",
+      "Dependency and configuration security checks passed",
+      "Skill format validation: added or modified Skills load successfully",
+      "CLI automation tests: all required business-line tests passed",
+      "Domain evaluation passed: reported success rate is greater than 95%",
+      "Cross-domain release gate: all domains and full integration evaluations passed",
+    ],
+  },
+};
+
+function log(message) {
+  console.error(`sync-pr-labels: ${message}`);
+}
+
+function normalizePath(input) {
+  return String(input || "").trim().toLowerCase();
+}
+
+function envOrFail(name) {
+  const value = (process.env[name] || "").trim();
+  if (!value) {
+    throw new Error(`missing required environment variable: ${name}`);
+  }
+  return value;
+}
+
+function buildHeaders(token, hasBody = false) {
+  const headers = {
+    Accept: "application/vnd.github+json",
+    Authorization: `Bearer ${token}`,
+    "X-GitHub-Api-Version": "2022-11-28",
+  };
+  if (hasBody) {
+    headers["Content-Type"] = "application/json";
+  }
+  return headers;
+}
+
+async function githubRequest(url, token, options = {}) {
+  const { method = "GET", payload, allow404 = false } = options;
+  const hasBody = payload !== undefined;
+  const response = await fetch(url, {
+    method,
+    headers: buildHeaders(token, hasBody),
+    body: hasBody ? JSON.stringify(payload) : undefined,
+  });
+
+  if (allow404 && response.status === 404) {
+    return null;
+  }
+
+  if (!response.ok) {
+    const detail = await response.text();
+    throw new Error(`GitHub API ${method} ${url} failed: ${response.status} ${detail}`);
+  }
+
+  const text = await response.text();
+  return text ? JSON.parse(text) : null;
+}
+
+async function loadEventPayload(filePath) {
+  return JSON.parse(await fs.readFile(filePath, "utf8"));
+}
+
+async function listPrFiles(repo, prNumber, token) {
+  const files = [];
+  for (let page = 1; ; page += 1) {
+    const params = new URLSearchParams({ per_page: "100", page: String(page) });
+    const url = `${API_BASE}/repos/${repo}/pulls/${prNumber}/files?${params.toString()}`;
+    const batch = await githubRequest(url, token);
+    if (!batch || batch.length === 0) {
+      break;
+    }
+    files.push(...batch);
+    if (batch.length < 100) {
+      break;
+    }
+  }
+  return files;
+}
+
+async function listIssueLabels(repo, prNumber, token) {
+  const url = `${API_BASE}/repos/${repo}/issues/${prNumber}/labels`;
+  const labels = await githubRequest(url, token);
+  return new Set(labels.map((item) => item.name));
+}
+
+async function syncLabelDefinition(repo, token, name) {
+  const label = LABEL_DEFINITIONS[name];
+  const createUrl = `${API_BASE}/repos/${repo}/labels`;
+  const updateUrl = `${API_BASE}/repos/${repo}/labels/${encodeURIComponent(name)}`;
+
+  try {
+    await githubRequest(createUrl, token, {
+      method: "POST",
+      payload: {
+        name,
+        color: label.color,
+        description: label.description,
+      },
+    });
+    log(`created label ${name}`);
+  } catch (error) {
+    if (!String(error.message || error).includes(" 422 ")) {
+      throw error;
+    }
+    await githubRequest(updateUrl, token, {
+      method: "PATCH",
+      payload: {
+        new_name: name,
+        color: label.color,
+        description: label.description,
+      },
+    });
+    log(`updated label ${name}`);
+  }
+}
+
+async function addLabels(repo, prNumber, token, labels) {
+  if (labels.length === 0) {
+    return;
+  }
+  const url = `${API_BASE}/repos/${repo}/issues/${prNumber}/labels`;
+  await githubRequest(url, token, {
+    method: "POST",
+    payload: { labels },
+  });
+  log(`added labels: ${labels.join(", ")}`);
+}
+
+async function removeLabel(repo, prNumber, token, name) {
+  const url = `${API_BASE}/repos/${repo}/issues/${prNumber}/labels/${encodeURIComponent(name)}`;
+  await githubRequest(url, token, { method: "DELETE", allow404: true });
+  log(`removed label: ${name}`);
+}
+
+function parsePrType(title) {
+  const match = String(title || "").trim().match(/^([a-z]+)(?:\([^)]+\))?!?:/i);
+  return match ? match[1].toLowerCase() : "";
+}
+
+function isLowRiskPath(filePath) {
+  const normalized = normalizePath(filePath);
+  const basename = path.posix.basename(normalized);
+
+  if (DOC_SUFFIXES.some((suffix) => normalized.endsWith(suffix))) {
+    return true;
+  }
+  if (LOW_RISK_FILENAMES.has(basename)) {
+    return true;
+  }
+  if (LOW_RISK_PREFIXES.some((prefix) => normalized.startsWith(prefix))) {
+    return true;
+  }
+  if (LOW_RISK_TEST_SUFFIXES.some((suffix) => normalized.endsWith(suffix))) {
+    return true;
+  }
+  return normalized.includes("/testdata/");
+}
+
+function isBusinessSkillPath(filePath) {
+  const normalized = normalizePath(filePath);
+  return normalized.startsWith("shortcuts/") || normalized.startsWith("skills/lark-");
+}
+
+function shortcutDomainForPath(filePath) {
+  const parts = normalizePath(filePath).split("/");
+  return parts.length >= 2 && parts[0] === "shortcuts" ? parts[1] : "";
+}
+
+function skillDomainForPath(filePath) {
+  const parts = normalizePath(filePath).split("/");
+  return parts.length >= 2 && parts[0] === "skills" && parts[1].startsWith("lark-")
+    ? parts[1].slice("lark-".length)
+    : "";
+}
+
+async function detectNewShortcutDomain(files) {
+  for (const item of files) {
+    if (item.status !== "added") {
+      continue;
+    }
+    const domain = shortcutDomainForPath(item.filename);
+    if (!domain) {
+      continue;
+    }
+    try {
+      await fs.access(path.join(ROOT, "shortcuts", domain));
+    } catch {
+      return domain;
+    }
+  }
+  return "";
+}
+
+function collectCoreAreas(filenames) {
+  const areas = new Set();
+  for (const name of filenames) {
+    const normalized = normalizePath(name);
+    if (normalized.startsWith("cmd/")) {
+      areas.add("cmd");
+    } else if (normalized.startsWith("internal/auth/")) {
+      areas.add("internal/auth");
+    } else if (normalized.startsWith("internal/engine/")) {
+      areas.add("internal/engine");
+    } else if (normalized.startsWith("internal/config/")) {
+      areas.add("internal/config");
+    }
+  }
+  return areas;
+}
+
+function touchesSensitivePath(filenames) {
+  const pattern = /(^|\/)(auth|permission|permissions|security)(\/|_|\.|$)/;
+  return filenames.some((name) => pattern.test(normalizePath(name)));
+}
+
+async function classifyPr(payload, files) {
+  const pr = payload.pull_request;
+  const title = pr.title || "";
+  const prType = parsePrType(title);
+  const filenames = files.map((item) => item.filename || "");
+  // Filter out docs, tests, and other low-risk paths so the size label tracks business impact.
+  const effectiveChanges = files.reduce(
+    (sum, item) => sum + (isLowRiskPath(item.filename) ? 0 : (item.changes || 0)),
+    0,
+  );
+  const totalChanges = files.reduce((sum, item) => sum + (item.changes || 0), 0);
+  const domains = new Set();
+
+  for (const name of filenames) {
+    const shortcutDomain = shortcutDomainForPath(name);
+    if (shortcutDomain) {
+      domains.add(shortcutDomain);
+    }
+    const skillDomain = skillDomainForPath(name);
+    if (skillDomain) {
+      domains.add(skillDomain);
+    }
+  }
+
+  const coreAreas = collectCoreAreas(filenames);
+  const newShortcutDomain = await detectNewShortcutDomain(files);
+  const lowRiskOnly = filenames.length > 0 && filenames.every((name) => isLowRiskPath(name));
+  const singleDomain = domains.size <= 1;
+  const multiDomain = domains.size >= 2;
+  const headDomains = [...domains].filter((domain) => HEAD_BUSINESS_DOMAINS.has(domain));
+  const touchesCore = filenames.some((name) => CORE_PREFIXES.some((prefix) => normalizePath(name).startsWith(prefix)));
+  const sensitive = touchesCore || touchesSensitivePath(filenames);
+
+  const reasons = [];
+  let label;
+
+  if (lowRiskOnly && (LOW_RISK_TYPES.has(prType) || effectiveChanges === 0)) {
+    reasons.push("Only low-risk docs, CI, test, or chore paths were changed, with no effective business code or Skill changes");
+    label = "size/S";
+  } else {
+    // XL is reserved for architecture-level or global-impact changes.
+    const architectureLevel =
+      effectiveChanges > 1200
+      || (prType === "refactor" && sensitive && effectiveChanges >= 300)
+      || (coreAreas.size >= 2 && (multiDomain || effectiveChanges >= 300))
+      || (headDomains.length >= 2 && sensitive);
+
+    if (architectureLevel) {
+      if (effectiveChanges > 1200) {
+        reasons.push("Effective business code or Skill changes are far beyond the L threshold");
+      }
+      if (prType === "refactor" && sensitive && effectiveChanges >= 300) {
+        reasons.push("Refactor PR touches core or sensitive paths");
+      }
+      if (coreAreas.size >= 2) {
+        reasons.push("Touches multiple core areas at the same time");
+      }
+      if (headDomains.length >= 2) {
+        reasons.push("Impacts multiple major business domains");
+      }
+      label = "size/XL";
+    } else if (
+      prType === "refactor"
+      || effectiveChanges >= 300
+      || Boolean(newShortcutDomain)
+      || multiDomain
+      || sensitive
+    ) {
+      if (prType === "refactor") {
+        reasons.push("PR type is refactor");
+      }
+      if (effectiveChanges >= 300) {
+        reasons.push("Effective business code or Skill changes exceed 300 lines");
+      }
+      if (newShortcutDomain) {
+        reasons.push(`Introduces a new business domain directory: shortcuts/${newShortcutDomain}/`);
+      }
+      if (multiDomain) {
+        reasons.push("Touches multiple business domains");
+      }
+      if (sensitive) {
+        reasons.push("Touches core framework paths or security/auth-related sensitive paths");
+      }
+      label = "size/L";
+    } else {
+      if (filenames.some((name) => isBusinessSkillPath(name)) || effectiveChanges > 0) {
+        reasons.push("Regular feat, fix, or Skill change within a single business domain");
+      }
+      if (singleDomain && domains.size > 0) {
+        reasons.push(`Impact is limited to a single business domain: ${[...domains].sort().join(", ")}`);
+      }
+      if (effectiveChanges < 300) {
+        reasons.push("Effective business code or Skill changes are below 300 lines");
+      }
+      label = "size/M";
+    }
+  }
+
+  return {
+    label,
+    title,
+    prType: prType || "unknown",
+    totalChanges,
+    effectiveChanges,
+    domains: [...domains].sort(),
+    coreAreas: [...coreAreas].sort(),
+    newShortcutDomain,
+    reasons,
+    lowRiskOnly,
+    filenames,
+  };
+}
+
+async function writeStepSummary(prNumber, classification) {
+  const summaryPath = (process.env.GITHUB_STEP_SUMMARY || "").trim();
+  if (!summaryPath) {
+    return;
+  }
+
+  const standard = CLASS_STANDARDS[classification.label];
+  const domains = classification.domains.join(", ") || "-";
+  const coreAreas = classification.coreAreas.join(", ") || "-";
+  const reasons = classification.reasons.length > 0
+    ? classification.reasons
+    : ["No higher-severity rule matched, so the PR defaults to medium classification"];
+
+  const lines = [
+    "## PR Size Classification",
+    "",
+    `- PR: #${prNumber}`,
+    `- Label: \`${classification.label}\``,
+    `- PR Type: \`${classification.prType}\``,
+    `- Total Changes: \`${classification.totalChanges}\``,
+    `- Effective Business/SKILL Changes: \`${classification.effectiveChanges}\``,
+    `- Business Domains: \`${domains}\``,
+    `- Core Areas: \`${coreAreas}\``,
+    `- CI/CD Channel: \`${standard.channel}\``,
+    `- Low Risk Only: \`${classification.lowRiskOnly}\``,
+    "",
+    "### Reasons",
+    "",
+    ...reasons.map((reason) => `- ${reason}`),
+    "",
+    "### Pipeline Gates",
+    "",
+    ...standard.gates.map((gate) => `- ${gate}`),
+    "",
+  ];
+
+  await fs.appendFile(summaryPath, `${lines.join("\n")}\n`, "utf8");
+}
+
+async function main() {
+  const token = envOrFail("GITHUB_TOKEN");
+  const eventPath = envOrFail("GITHUB_EVENT_PATH");
+  const payload = await loadEventPayload(eventPath);
+
+  const repo = payload.repository.full_name;
+  const prNumber = payload.pull_request.number;
+
+  const files = await listPrFiles(repo, prNumber, token);
+  const classification = await classifyPr(payload, files);
+  const desired = new Set([classification.label]);
+  const current = await listIssueLabels(repo, prNumber, token);
+
+  const managedCurrent = [...current].filter((label) => MANAGED_LABELS.has(label));
+  const toAdd = [...desired].filter((label) => !current.has(label)).sort();
+  const toRemove = managedCurrent.filter((label) => !desired.has(label)).sort();
+
+  // Keep label metadata consistent even when labels already exist in the repository.
+  for (const label of Object.keys(LABEL_DEFINITIONS)) {
+    await syncLabelDefinition(repo, token, label);
+  }
+
+  await addLabels(repo, prNumber, token, toAdd);
+
+  for (const label of toRemove) {
+    await removeLabel(repo, prNumber, token, label);
+  }
+
+  await writeStepSummary(prNumber, classification);
+
+  log(
+    `pr #${prNumber} type=${classification.prType} total_changes=${classification.totalChanges} `
+      + `effective_changes=${classification.effectiveChanges} files=${files.length} `
+      + `desired=${[...desired].sort().join(",") || "-"} current_managed=${managedCurrent.sort().join(",") || "-"} `
+      + `reasons=${classification.reasons.join(" | ") || "-"}`,
+  );
+}
+
+main().catch((error) => {
+  log(error.message || String(error));
+  process.exit(1);
+});

From ebd65ed5d2f33677f42cf12f536333d2c623c3a6 Mon Sep 17 00:00:00 2001
From: williamfzc <178894043@qq.com>
Date: Tue, 31 Mar 2026 10:59:34 +0800
Subject: [PATCH 02/19] chore(ci): make PR label sync non-blocking

---
 .github/workflows/pr-labels.yml | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/.github/workflows/pr-labels.yml b/.github/workflows/pr-labels.yml
index 2586c0c33c..3d1596ed70 100644
--- a/.github/workflows/pr-labels.yml
+++ b/.github/workflows/pr-labels.yml
@@ -26,6 +26,8 @@ jobs:
           node-version: '20'
 
       - name: Sync managed PR labels
+        # Labeling is best-effort and must not block PR merges.
+        continue-on-error: true
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: node scripts/sync_pr_labels.js

From b1599d437149aa76503c061581ce3d1752daaf90 Mon Sep 17 00:00:00 2001
From: williamfzc <178894043@qq.com>
Date: Tue, 31 Mar 2026 11:11:52 +0800
Subject: [PATCH 03/19] feat(ci): add dry-run mode for PR label sync

---
 scripts/sync_pr_labels.js | 204 ++++++++++++++++++++++++++++++++++++--
 1 file changed, 193 insertions(+), 11 deletions(-)

diff --git a/scripts/sync_pr_labels.js b/scripts/sync_pr_labels.js
index 968363f9ef..37420200cf 100644
--- a/scripts/sync_pr_labels.js
+++ b/scripts/sync_pr_labels.js
@@ -67,6 +67,28 @@ const CLASS_STANDARDS = {
   },
 };
 
+function printHelp() {
+  const lines = [
+    "Usage:",
+    "  node scripts/sync_pr_labels.js",
+    "  node scripts/sync_pr_labels.js --dry-run --pr-url <github-pr-url> [--token <token>] [--json]",
+    "  node scripts/sync_pr_labels.js --dry-run --repo <owner/name> --pr-number <number> [--token <token>] [--json]",
+    "",
+    "Modes:",
+    "  default    Read the GitHub Actions event payload and apply labels",
+    "  --dry-run  Fetch the PR, compute the managed label, and print the result without writing labels",
+    "",
+    "Options:",
+    "  --pr-url <url>       GitHub pull request URL, for example https://github.com/larksuite/cli/pull/123",
+    "  --repo <owner/name>  Repository name, used with --pr-number",
+    "  --pr-number <n>      Pull request number, used with --repo",
+    "  --token <token>      GitHub token override; falls back to GITHUB_TOKEN",
+    "  --json               Print dry-run output as JSON",
+    "  --help               Show this message",
+  ];
+  console.log(lines.join("\n"));
+}
+
 function log(message) {
   console.error(`sync-pr-labels: ${message}`);
 }
@@ -75,8 +97,12 @@ function normalizePath(input) {
   return String(input || "").trim().toLowerCase();
 }
 
+function envValue(name) {
+  return (process.env[name] || "").trim();
+}
+
 function envOrFail(name) {
-  const value = (process.env[name] || "").trim();
+  const value = envValue(name);
   if (!value) {
     throw new Error(`missing required environment variable: ${name}`);
   }
@@ -86,15 +112,75 @@ function envOrFail(name) {
 function buildHeaders(token, hasBody = false) {
   const headers = {
     Accept: "application/vnd.github+json",
-    Authorization: `Bearer ${token}`,
     "X-GitHub-Api-Version": "2022-11-28",
   };
+  if (token) {
+    headers.Authorization = `Bearer ${token}`;
+  }
   if (hasBody) {
     headers["Content-Type"] = "application/json";
   }
   return headers;
 }
 
+function parseArgs(argv) {
+  const options = {
+    dryRun: false,
+    json: false,
+    help: false,
+    prUrl: "",
+    repo: "",
+    prNumber: "",
+    token: "",
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--dry-run") {
+      options.dryRun = true;
+    } else if (arg === "--json") {
+      options.json = true;
+    } else if (arg === "--help" || arg === "-h") {
+      options.help = true;
+    } else if (arg === "--pr-url") {
+      options.prUrl = argv[i + 1] || "";
+      i += 1;
+    } else if (arg === "--repo") {
+      options.repo = argv[i + 1] || "";
+      i += 1;
+    } else if (arg === "--pr-number") {
+      options.prNumber = argv[i + 1] || "";
+      i += 1;
+    } else if (arg === "--token") {
+      options.token = argv[i + 1] || "";
+      i += 1;
+    } else {
+      throw new Error(`unknown argument: ${arg}`);
+    }
+  }
+
+  return options;
+}
+
+function parsePrUrl(prUrl) {
+  let parsed;
+  try {
+    parsed = new URL(prUrl);
+  } catch {
+    throw new Error(`invalid PR URL: ${prUrl}`);
+  }
+
+  const match = parsed.pathname.match(/^\/([^/]+)\/([^/]+)\/pull\/(\d+)\/?$/);
+  if (!match) {
+    throw new Error(`unsupported PR URL format: ${prUrl}`);
+  }
+
+  return {
+    repo: `${match[1]}/${match[2]}`,
+    prNumber: Number(match[3]),
+  };
+}
+
 async function githubRequest(url, token, options = {}) {
   const { method = "GET", payload, allow404 = false } = options;
   const hasBody = payload !== undefined;
@@ -121,6 +207,11 @@ async function loadEventPayload(filePath) {
   return JSON.parse(await fs.readFile(filePath, "utf8"));
 }
 
+async function getPullRequest(repo, prNumber, token) {
+  const url = `${API_BASE}/repos/${repo}/pulls/${prNumber}`;
+  return githubRequest(url, token);
+}
+
 async function listPrFiles(repo, prNumber, token) {
   const files = [];
   for (let page = 1; ; page += 1) {
@@ -426,18 +517,109 @@ async function writeStepSummary(prNumber, classification) {
   await fs.appendFile(summaryPath, `${lines.join("\n")}\n`, "utf8");
 }
 
-async function main() {
-  const token = envOrFail("GITHUB_TOKEN");
+function formatDryRunResult(repo, prNumber, classification) {
+  const standard = CLASS_STANDARDS[classification.label];
+  return {
+    repo,
+    prNumber,
+    label: classification.label,
+    prType: classification.prType,
+    totalChanges: classification.totalChanges,
+    effectiveChanges: classification.effectiveChanges,
+    lowRiskOnly: classification.lowRiskOnly,
+    domains: classification.domains,
+    coreAreas: classification.coreAreas,
+    reasons: classification.reasons,
+    channel: standard.channel,
+    gates: standard.gates,
+  };
+}
+
+function printDryRunResult(result, asJson) {
+  if (asJson) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  const lines = [
+    `Repo: ${result.repo}`,
+    `PR: #${result.prNumber}`,
+    `Label: ${result.label}`,
+    `PR Type: ${result.prType}`,
+    `Total Changes: ${result.totalChanges}`,
+    `Effective Business/SKILL Changes: ${result.effectiveChanges}`,
+    `Low Risk Only: ${result.lowRiskOnly}`,
+    `Business Domains: ${result.domains.join(", ") || "-"}`,
+    `Core Areas: ${result.coreAreas.join(", ") || "-"}`,
+    `CI/CD Channel: ${result.channel}`,
+    "",
+    "Reasons:",
+    ...(result.reasons.length > 0 ? result.reasons : ["No higher-severity rule matched, so the PR defaults to medium classification"]).map((reason) => `- ${reason}`),
+    "",
+    "Pipeline Gates:",
+    ...result.gates.map((gate) => `- ${gate}`),
+  ];
+  console.log(lines.join("\n"));
+}
+
+async function resolveContext(options) {
+  if (options.prUrl) {
+    const { repo, prNumber } = parsePrUrl(options.prUrl);
+    const payload = {
+      repository: { full_name: repo },
+      pull_request: await getPullRequest(repo, prNumber, options.token),
+    };
+    return { repo, prNumber, payload };
+  }
+
+  if (options.repo || options.prNumber) {
+    if (!options.repo || !options.prNumber) {
+      throw new Error("--repo and --pr-number must be provided together");
+    }
+    const prNumber = Number(options.prNumber);
+    if (!Number.isInteger(prNumber) || prNumber <= 0) {
+      throw new Error(`invalid PR number: ${options.prNumber}`);
+    }
+    const payload = {
+      repository: { full_name: options.repo },
+      pull_request: await getPullRequest(options.repo, prNumber, options.token),
+    };
+    return { repo: options.repo, prNumber, payload };
+  }
+
   const eventPath = envOrFail("GITHUB_EVENT_PATH");
   const payload = await loadEventPayload(eventPath);
+  return {
+    repo: payload.repository.full_name,
+    prNumber: payload.pull_request.number,
+    payload,
+  };
+}
 
-  const repo = payload.repository.full_name;
-  const prNumber = payload.pull_request.number;
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  if (options.help) {
+    printHelp();
+    return;
+  }
 
-  const files = await listPrFiles(repo, prNumber, token);
+  options.token = options.token || envValue("GITHUB_TOKEN");
+  const { repo, prNumber, payload } = await resolveContext(options);
+
+  if (!options.dryRun && !options.token) {
+    throw new Error("missing required GitHub token; set GITHUB_TOKEN or pass --token");
+  }
+
+  const files = await listPrFiles(repo, prNumber, options.token);
   const classification = await classifyPr(payload, files);
+
+  if (options.dryRun) {
+    printDryRunResult(formatDryRunResult(repo, prNumber, classification), options.json);
+    return;
+  }
+
   const desired = new Set([classification.label]);
-  const current = await listIssueLabels(repo, prNumber, token);
+  const current = await listIssueLabels(repo, prNumber, options.token);
 
   const managedCurrent = [...current].filter((label) => MANAGED_LABELS.has(label));
   const toAdd = [...desired].filter((label) => !current.has(label)).sort();
@@ -445,13 +627,13 @@ async function main() {
 
   // Keep label metadata consistent even when labels already exist in the repository.
   for (const label of Object.keys(LABEL_DEFINITIONS)) {
-    await syncLabelDefinition(repo, token, label);
+    await syncLabelDefinition(repo, options.token, label);
   }
 
-  await addLabels(repo, prNumber, token, toAdd);
+  await addLabels(repo, prNumber, options.token, toAdd);
 
   for (const label of toRemove) {
-    await removeLabel(repo, prNumber, token, label);
+    await removeLabel(repo, prNumber, options.token, label);
   }
 
   await writeStepSummary(prNumber, classification);

From 04351c7b5106b9e3cda5d57af9411249bcc3e9b5 Mon Sep 17 00:00:00 2001
From: williamfzc <178894043@qq.com>
Date: Tue, 31 Mar 2026 11:44:43 +0800
Subject: [PATCH 04/19] feat(ci): add PR label dry-run samples

---
 scripts/sync_pr_labels.js           | 71 +++++++++++++++++------------
 scripts/sync_pr_labels.samples.json | 22 +++++++++
 2 files changed, 65 insertions(+), 28 deletions(-)
 create mode 100644 scripts/sync_pr_labels.samples.json

diff --git a/scripts/sync_pr_labels.js b/scripts/sync_pr_labels.js
index 37420200cf..7cd13398a2 100644
--- a/scripts/sync_pr_labels.js
+++ b/scripts/sync_pr_labels.js
@@ -83,7 +83,7 @@ function printHelp() {
     "  --repo <owner/name>  Repository name, used with --pr-number",
     "  --pr-number <n>      Pull request number, used with --repo",
     "  --token <token>      GitHub token override; falls back to GITHUB_TOKEN",
-    "  --json               Print dry-run output as JSON",
+    "  --json               Print dry-run output as JSON instead of the default one-line summary",
     "  --help               Show this message",
   ];
   console.log(lines.join("\n"));
@@ -360,9 +360,17 @@ function collectCoreAreas(filenames) {
   return areas;
 }
 
-function touchesSensitivePath(filenames) {
+function collectSensitiveKeywords(filenames) {
   const pattern = /(^|\/)(auth|permission|permissions|security)(\/|_|\.|$)/;
-  return filenames.some((name) => pattern.test(normalizePath(name)));
+  const hits = new Set();
+  for (const name of filenames) {
+    const normalized = normalizePath(name);
+    const match = normalized.match(pattern);
+    if (match && match[2]) {
+      hits.add(match[2]);
+    }
+  }
+  return [...hits].sort();
 }
 
 async function classifyPr(payload, files) {
@@ -395,8 +403,9 @@ async function classifyPr(payload, files) {
   const singleDomain = domains.size <= 1;
   const multiDomain = domains.size >= 2;
   const headDomains = [...domains].filter((domain) => HEAD_BUSINESS_DOMAINS.has(domain));
-  const touchesCore = filenames.some((name) => CORE_PREFIXES.some((prefix) => normalizePath(name).startsWith(prefix)));
-  const sensitive = touchesCore || touchesSensitivePath(filenames);
+  const coreSignals = [...coreAreas].sort();
+  const sensitiveKeywords = collectSensitiveKeywords(filenames);
+  const sensitive = coreSignals.length > 0 || sensitiveKeywords.length > 0;
 
   const reasons = [];
   let label;
@@ -425,6 +434,12 @@ async function classifyPr(payload, files) {
       if (headDomains.length >= 2) {
         reasons.push("Impacts multiple major business domains");
       }
+      for (const signal of coreSignals) {
+        reasons.push(`Core area hit: ${signal}`);
+      }
+      for (const keyword of sensitiveKeywords) {
+        reasons.push(`Sensitive keyword hit: ${keyword}`);
+      }
       label = "size/XL";
     } else if (
       prType === "refactor"
@@ -445,8 +460,11 @@ async function classifyPr(payload, files) {
       if (multiDomain) {
         reasons.push("Touches multiple business domains");
       }
-      if (sensitive) {
-        reasons.push("Touches core framework paths or security/auth-related sensitive paths");
+      for (const signal of coreSignals) {
+        reasons.push(`Core area hit: ${signal}`);
+      }
+      for (const keyword of sensitiveKeywords) {
+        reasons.push(`Sensitive keyword hit: ${keyword}`);
       }
       label = "size/L";
     } else {
@@ -471,6 +489,8 @@ async function classifyPr(payload, files) {
     effectiveChanges,
     domains: [...domains].sort(),
     coreAreas: [...coreAreas].sort(),
+    coreSignals,
+    sensitiveKeywords,
     newShortcutDomain,
     reasons,
     lowRiskOnly,
@@ -529,37 +549,32 @@ function formatDryRunResult(repo, prNumber, classification) {
     lowRiskOnly: classification.lowRiskOnly,
     domains: classification.domains,
     coreAreas: classification.coreAreas,
+    coreSignals: classification.coreSignals,
+    sensitiveKeywords: classification.sensitiveKeywords,
     reasons: classification.reasons,
     channel: standard.channel,
     gates: standard.gates,
   };
 }
 
-function printDryRunResult(result, asJson) {
-  if (asJson) {
+function printDryRunResult(result, options) {
+  if (options.json) {
     console.log(JSON.stringify(result, null, 2));
     return;
   }
 
-  const lines = [
-    `Repo: ${result.repo}`,
-    `PR: #${result.prNumber}`,
-    `Label: ${result.label}`,
-    `PR Type: ${result.prType}`,
-    `Total Changes: ${result.totalChanges}`,
-    `Effective Business/SKILL Changes: ${result.effectiveChanges}`,
-    `Low Risk Only: ${result.lowRiskOnly}`,
-    `Business Domains: ${result.domains.join(", ") || "-"}`,
-    `Core Areas: ${result.coreAreas.join(", ") || "-"}`,
-    `CI/CD Channel: ${result.channel}`,
-    "",
-    "Reasons:",
-    ...(result.reasons.length > 0 ? result.reasons : ["No higher-severity rule matched, so the PR defaults to medium classification"]).map((reason) => `- ${reason}`),
-    "",
-    "Pipeline Gates:",
-    ...result.gates.map((gate) => `- ${gate}`),
+  const signalParts = [
+    ...result.coreSignals.map((signal) => `core:${signal}`),
+    ...result.sensitiveKeywords.map((keyword) => `keyword:${keyword}`),
+    ...(result.domains.length > 0 ? [`domains:${result.domains.join(",")}`] : []),
   ];
-  console.log(lines.join("\n"));
+  const reasonParts = result.reasons.length > 0
+    ? result.reasons
+    : ["No higher-severity rule matched, so the PR defaults to medium classification"];
+  console.log(
+    `${result.label} | #${result.prNumber} | type:${result.prType} | eff:${result.effectiveChanges} | `
+      + `sig:${signalParts.join(";") || "-"} | reason:${reasonParts.join("; ")}`,
+  );
 }
 
 async function resolveContext(options) {
@@ -614,7 +629,7 @@ async function main() {
   const classification = await classifyPr(payload, files);
 
   if (options.dryRun) {
-    printDryRunResult(formatDryRunResult(repo, prNumber, classification), options.json);
+    printDryRunResult(formatDryRunResult(repo, prNumber, classification), options);
     return;
   }
 
diff --git a/scripts/sync_pr_labels.samples.json b/scripts/sync_pr_labels.samples.json
new file mode 100644
index 0000000000..cfe2310352
--- /dev/null
+++ b/scripts/sync_pr_labels.samples.json
@@ -0,0 +1,22 @@
+[
+  {
+    "name": "docs-only",
+    "pr_url": "https://github.com/larksuite/cli/pull/27",
+    "expected_label": "size/S"
+  },
+  {
+    "name": "single-domain-im",
+    "pr_url": "https://github.com/larksuite/cli/pull/30",
+    "expected_label": "size/M"
+  },
+  {
+    "name": "core-cmd",
+    "pr_url": "https://github.com/larksuite/cli/pull/20",
+    "expected_label": "size/L"
+  },
+  {
+    "name": "core-cmd-shared",
+    "pr_url": "https://github.com/larksuite/cli/pull/86",
+    "expected_label": "size/L"
+  }
+]

From 05c50a76b4952a1e138aed4f5940dd3f7a2becf1 Mon Sep 17 00:00:00 2001
From: williamfzc <178894043@qq.com>
Date: Tue, 31 Mar 2026 12:55:31 +0800
Subject: [PATCH 05/19] test(ci): update PR label samples with real historical
 merged PRs

Replaced synthetic or open PR samples with actual merged/closed PRs from the
repository to provide a more accurate reflection of the size label categorization.
Added 4 samples each for sizes S, M, and L covering docs, fixes, ci, and features.
---
 scripts/sync_pr_labels.samples.json | 124 +++++++++++++++++++++++++---
 1 file changed, 112 insertions(+), 12 deletions(-)

diff --git a/scripts/sync_pr_labels.samples.json b/scripts/sync_pr_labels.samples.json
index cfe2310352..98373b399f 100644
--- a/scripts/sync_pr_labels.samples.json
+++ b/scripts/sync_pr_labels.samples.json
@@ -1,22 +1,122 @@
 [
   {
-    "name": "docs-only",
-    "pr_url": "https://github.com/larksuite/cli/pull/27",
-    "expected_label": "size/S"
+    "name": "size-s-docs-badge",
+    "number": 103,
+    "title": "docs: add official badge to distinguish from third-party Lark CLI tools",
+    "pr_url": "https://github.com/larksuite/cli/pull/103",
+    "status": "merged",
+    "merged_at": "2026-03-30T12:15:45Z",
+    "expected_label": "size/S",
+    "review_note": "Pure docs sample. Useful to confirm low-risk paths stay in S even when total changed lines are not tiny."
   },
   {
-    "name": "single-domain-im",
+    "name": "size-s-docs-simplify",
+    "number": 26,
+    "title": "docs: simplify installation steps by merging CLI and Skills into one …",
+    "pr_url": "https://github.com/larksuite/cli/pull/26",
+    "status": "merged",
+    "merged_at": "2026-03-28T09:33:24Z",
+    "expected_label": "size/S",
+    "review_note": "Docs sample, verifying docs changes remain in S."
+  },
+  {
+    "name": "size-s-docs-star-history",
+    "number": 12,
+    "title": "docs: add Star History chart to readmes",
+    "pr_url": "https://github.com/larksuite/cli/pull/12",
+    "status": "merged",
+    "merged_at": "2026-03-28T16:00:15Z",
+    "expected_label": "size/S",
+    "review_note": "Docs sample, no effective business code changes."
+  },
+  {
+    "name": "size-s-docs-clarify-install",
+    "number": 3,
+    "title": "docs: clarify install methods and add source build steps",
+    "pr_url": "https://github.com/larksuite/cli/pull/3",
+    "status": "merged",
+    "merged_at": "2026-03-28T03:43:44Z",
+    "expected_label": "size/S",
+    "review_note": "Docs sample, pure documentation clarification."
+  },
+  {
+    "name": "size-m-fix-base-scope",
+    "number": 96,
+    "title": "fix(base): correct scope for record history list shortcut",
+    "pr_url": "https://github.com/larksuite/cli/pull/96",
+    "status": "merged",
+    "merged_at": "2026-03-30T11:40:18Z",
+    "expected_label": "size/M",
+    "review_note": "Small fix sample. Verify the lower edge of the M bucket within a single domain."
+  },
+  {
+    "name": "size-m-fix-mail-sensitive",
+    "number": 92,
+    "title": "fix: remove sensitive send scope from reply and forward shortcuts",
+    "pr_url": "https://github.com/larksuite/cli/pull/92",
+    "status": "merged",
+    "merged_at": "2026-03-30T10:19:11Z",
+    "expected_label": "size/M",
+    "review_note": "Security-like wording in the title but stays in one business domain (mail)."
+  },
+  {
+    "name": "size-m-ci-improve",
+    "number": 71,
+    "title": "ci: improve CI workflows and add golangci-lint config",
+    "pr_url": "https://github.com/larksuite/cli/pull/71",
+    "status": "merged",
+    "merged_at": "2026-03-30T03:09:31Z",
+    "expected_label": "size/M",
+    "review_note": "CI workflow change that goes beyond S threshold."
+  },
+  {
+    "name": "size-m-feat-im-pagination",
+    "number": 30,
+    "title": "feat: add auto-pagination to messages search and update lark-im docs",
     "pr_url": "https://github.com/larksuite/cli/pull/30",
-    "expected_label": "size/M"
+    "status": "merged",
+    "merged_at": "2026-03-30T15:00:41Z",
+    "expected_label": "size/M",
+    "review_note": "Single-domain feature with larger diff but effective changes stay in M."
+  },
+  {
+    "name": "size-l-fix-api-silent",
+    "number": 85,
+    "title": "fix: resolve silent failure in `lark-cli api` error output (#39)",
+    "pr_url": "https://github.com/larksuite/cli/pull/85",
+    "status": "merged",
+    "merged_at": "2026-03-30T09:19:24Z",
+    "expected_label": "size/L",
+    "review_note": "Touches core area (cmd), bumping the size to L."
+  },
+  {
+    "name": "size-l-docs-rename-base",
+    "number": 11,
+    "title": "docs: rename user-facing Bitable references to Base",
+    "pr_url": "https://github.com/larksuite/cli/pull/11",
+    "status": "merged",
+    "merged_at": "2026-03-28T16:00:52Z",
+    "expected_label": "size/L",
+    "review_note": "Docs change but touches multiple business domains, making it L."
   },
   {
-    "name": "core-cmd",
-    "pr_url": "https://github.com/larksuite/cli/pull/20",
-    "expected_label": "size/L"
+    "name": "size-l-feat-local-image",
+    "number": 57,
+    "title": "feat(docs): support local image upload in docs +create",
+    "pr_url": "https://github.com/larksuite/cli/pull/57",
+    "status": "closed",
+    "merged_at": null,
+    "expected_label": "size/L",
+    "review_note": "Closed PR but useful as an L sample for effective lines exceeding 300."
   },
   {
-    "name": "core-cmd-shared",
-    "pr_url": "https://github.com/larksuite/cli/pull/86",
-    "expected_label": "size/L"
+    "name": "size-l-fix-cli",
+    "number": 91,
+    "title": "fix: correct CLI examples in root help and READMEs (closes #48)",
+    "pr_url": "https://github.com/larksuite/cli/pull/91",
+    "status": "closed",
+    "merged_at": null,
+    "expected_label": "size/L",
+    "review_note": "Closed PR touching core area (cmd)."
   }
-]
+]
\ No newline at end of file

From 91ce441125a9f4bd6cd89abcce79d3dc0bb28582 Mon Sep 17 00:00:00 2001
From: williamfzc <178894043@qq.com>
Date: Tue, 31 Mar 2026 13:23:06 +0800
Subject: [PATCH 06/19] feat(ci): add high-level area tags for PRs

Based on user feedback, fine-grained domain labels (like `domain/base`) are too detailed for the early stages.
This change adds support for applying `area/*` tags to indicate which important top-level modules a PR touches.

Currently tracked areas:
- `area/shortcuts`
- `area/skills`
- `area/cmd`

Minor modules like docs, ci, and tests are intentionally excluded to keep tags focused on critical architectural components.
---
 scripts/sync_pr_labels.js | 35 ++++++++++++++++++++++++++++++++++-
 1 file changed, 34 insertions(+), 1 deletion(-)

diff --git a/scripts/sync_pr_labels.js b/scripts/sync_pr_labels.js
index 7cd13398a2..6ead27ebb9 100644
--- a/scripts/sync_pr_labels.js
+++ b/scripts/sync_pr_labels.js
@@ -325,6 +325,14 @@ function skillDomainForPath(filePath) {
     : "";
 }
 
+function getImportantArea(filePath) {
+  const normalized = normalizePath(filePath);
+  if (normalized.startsWith("shortcuts/")) return "shortcuts";
+  if (normalized.startsWith("skills/") || normalized.startsWith("skill-template/")) return "skills";
+  if (normalized.startsWith("cmd/")) return "cmd";
+  return "";
+}
+
 async function detectNewShortcutDomain(files) {
   for (const item of files) {
     if (item.status !== "added") {
@@ -385,6 +393,7 @@ async function classifyPr(payload, files) {
   );
   const totalChanges = files.reduce((sum, item) => sum + (item.changes || 0), 0);
   const domains = new Set();
+  const importantAreas = new Set();
 
   for (const name of filenames) {
     const shortcutDomain = shortcutDomainForPath(name);
@@ -395,6 +404,11 @@ async function classifyPr(payload, files) {
     if (skillDomain) {
       domains.add(skillDomain);
     }
+    
+    const area = getImportantArea(name);
+    if (area) {
+      importantAreas.add(area);
+    }
   }
 
   const coreAreas = collectCoreAreas(filenames);
@@ -488,6 +502,7 @@ async function classifyPr(payload, files) {
     totalChanges,
     effectiveChanges,
     domains: [...domains].sort(),
+    importantAreas: [...importantAreas].sort(),
     coreAreas: [...coreAreas].sort(),
     coreSignals,
     sensitiveKeywords,
@@ -506,6 +521,7 @@ async function writeStepSummary(prNumber, classification) {
 
   const standard = CLASS_STANDARDS[classification.label];
   const domains = classification.domains.join(", ") || "-";
+  const areas = classification.importantAreas.join(", ") || "-";
   const coreAreas = classification.coreAreas.join(", ") || "-";
   const reasons = classification.reasons.length > 0
     ? classification.reasons
@@ -520,6 +536,7 @@ async function writeStepSummary(prNumber, classification) {
     `- Total Changes: \`${classification.totalChanges}\``,
     `- Effective Business/SKILL Changes: \`${classification.effectiveChanges}\``,
     `- Business Domains: \`${domains}\``,
+    `- Impacted Areas: \`${areas}\``,
     `- Core Areas: \`${coreAreas}\``,
     `- CI/CD Channel: \`${standard.channel}\``,
     `- Low Risk Only: \`${classification.lowRiskOnly}\``,
@@ -548,6 +565,7 @@ function formatDryRunResult(repo, prNumber, classification) {
     effectiveChanges: classification.effectiveChanges,
     lowRiskOnly: classification.lowRiskOnly,
     domains: classification.domains,
+    importantAreas: classification.importantAreas,
     coreAreas: classification.coreAreas,
     coreSignals: classification.coreSignals,
     sensitiveKeywords: classification.sensitiveKeywords,
@@ -567,6 +585,7 @@ function printDryRunResult(result, options) {
     ...result.coreSignals.map((signal) => `core:${signal}`),
     ...result.sensitiveKeywords.map((keyword) => `keyword:${keyword}`),
     ...(result.domains.length > 0 ? [`domains:${result.domains.join(",")}`] : []),
+    ...(result.importantAreas.length > 0 ? [`areas:${result.importantAreas.join(",")}`] : []),
   ];
   const reasonParts = result.reasons.length > 0
     ? result.reasons
@@ -634,12 +653,26 @@ async function main() {
   }
 
   const desired = new Set([classification.label]);
+  for (const area of classification.importantAreas) {
+    desired.add(`area/${area}`);
+  }
+
   const current = await listIssueLabels(repo, prNumber, options.token);
 
-  const managedCurrent = [...current].filter((label) => MANAGED_LABELS.has(label));
+  const managedCurrent = [...current].filter((label) => MANAGED_LABELS.has(label) || label.startsWith("area/"));
   const toAdd = [...desired].filter((label) => !current.has(label)).sort();
   const toRemove = managedCurrent.filter((label) => !desired.has(label)).sort();
 
+  for (const area of classification.importantAreas) {
+    const labelName = `area/${area}`;
+    if (!LABEL_DEFINITIONS[labelName]) {
+      LABEL_DEFINITIONS[labelName] = {
+        color: "1d76db",
+        description: `PR touches the ${area} area`,
+      };
+    }
+  }
+
   // Keep label metadata consistent even when labels already exist in the repository.
   for (const label of Object.keys(LABEL_DEFINITIONS)) {
     await syncLabelDefinition(repo, options.token, label);

From 5a841dc142815346846ed9362e0b6004199342a0 Mon Sep 17 00:00:00 2001
From: williamfzc <178894043@qq.com>
Date: Tue, 31 Mar 2026 13:26:27 +0800
Subject: [PATCH 07/19] refactor(ci): extract pr-label-sync logic to a
 dedicated directory

To avoid polluting the root `scripts/` directory, moved `sync_pr_labels.js` and
`sync_pr_labels.samples.json` into a new `scripts/sync-pr-labels/` folder.
Added a dedicated README to document its usage and behavior.
Updated `.github/workflows/pr-labels.yml` to reflect the new path.
---
 .github/workflows/pr-labels.yml               |  2 +-
 scripts/sync-pr-labels/README.md              | 47 +++++++++++++++++++
 .../index.js}                                 |  0
 .../samples.json}                             |  0
 4 files changed, 48 insertions(+), 1 deletion(-)
 create mode 100644 scripts/sync-pr-labels/README.md
 rename scripts/{sync_pr_labels.js => sync-pr-labels/index.js} (100%)
 rename scripts/{sync_pr_labels.samples.json => sync-pr-labels/samples.json} (100%)

diff --git a/.github/workflows/pr-labels.yml b/.github/workflows/pr-labels.yml
index 3d1596ed70..bae29b0325 100644
--- a/.github/workflows/pr-labels.yml
+++ b/.github/workflows/pr-labels.yml
@@ -30,4 +30,4 @@ jobs:
         continue-on-error: true
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: node scripts/sync_pr_labels.js
+        run: node scripts/sync-pr-labels/index.js
diff --git a/scripts/sync-pr-labels/README.md b/scripts/sync-pr-labels/README.md
new file mode 100644
index 0000000000..404d4a6c62
--- /dev/null
+++ b/scripts/sync-pr-labels/README.md
@@ -0,0 +1,47 @@
+# PR Label Sync
+
+This directory contains scripts and sample data for automatically classifying and labeling GitHub Pull Requests based on the files they modify.
+
+## Files
+
+- `index.js`: The main Node.js script. It fetches PR files, evaluates their risk level, calculates business impact, and uses GitHub APIs to add appropriate `size/*` and `area/*` labels.
+- `samples.json`: A collection of historical PRs used as test cases to verify the labeling logic (especially for regression testing the S/M/L thresholds).
+
+## Features
+
+### Size Labels (`size/*`)
+The script evaluates the "effective" lines of code changed (ignoring tests, docs, and ci files) to classify the PR:
+- **`size/S`**: Low-risk changes involving only docs, tests, CI workflows, or chores.
+- **`size/M`**: Small-to-medium changes affecting a single business domain, with effective lines under 300.
+- **`size/L`**: Large features (>= 300 lines), cross-domain changes, or any changes touching core architecture paths (like `cmd/`).
+- **`size/XL`**: Architectural overhauls, extremely large PRs (>1200 lines), or sensitive refactors.
+
+### Area Tags (`area/*`)
+The script also identifies which high-level architectural modules a PR touches to give reviewers an immediate sense of the impact scope. Currently tracked important areas include:
+- `area/cmd`
+- `area/shortcuts`
+- `area/skills`
+
+Minor modules like docs and tests are omitted to keep PR tags clean and focused on structural changes.
+
+## Usage
+
+### In GitHub Actions
+This script is designed to run in CI workflows. It automatically reads the `GITHUB_EVENT_PATH` payload to get the PR context.
+
+```bash
+node scripts/sync-pr-labels/index.js
+```
+
+### Local Dry Run
+You can test the labeling logic against an existing GitHub PR without actually applying labels by using the `--dry-run` flag.
+
+```bash
+# Requires GITHUB_TOKEN environment variable or passing --token
+node scripts/sync-pr-labels/index.js --dry-run --repo larksuite/cli --pr-number 123
+```
+
+To see the raw JSON output for programmatic use:
+```bash
+node scripts/sync-pr-labels/index.js --dry-run --repo larksuite/cli --pr-number 123 --json
+```
\ No newline at end of file
diff --git a/scripts/sync_pr_labels.js b/scripts/sync-pr-labels/index.js
similarity index 100%
rename from scripts/sync_pr_labels.js
rename to scripts/sync-pr-labels/index.js
diff --git a/scripts/sync_pr_labels.samples.json b/scripts/sync-pr-labels/samples.json
similarity index 100%
rename from scripts/sync_pr_labels.samples.json
rename to scripts/sync-pr-labels/samples.json

From 8e0c997ff1e00d9dddaf327e4c5799c2692d384d Mon Sep 17 00:00:00 2001
From: williamfzc <178894043@qq.com>
Date: Tue, 31 Mar 2026 13:28:21 +0800
Subject: [PATCH 08/19] refactor(ci): rename pr label script directory for
 simplicity

Renamed `scripts/sync-pr-labels/` to `scripts/pr-labels/` to keep directory
names concise. Updated internal references and GitHub workflow files to point
to the new path.
---
 .github/workflows/pr-labels.yml                    | 2 +-
 scripts/{sync-pr-labels => pr-labels}/README.md    | 6 +++---
 scripts/{sync-pr-labels => pr-labels}/index.js     | 6 +++---
 scripts/{sync-pr-labels => pr-labels}/samples.json | 0
 4 files changed, 7 insertions(+), 7 deletions(-)
 rename scripts/{sync-pr-labels => pr-labels}/README.md (90%)
 rename scripts/{sync-pr-labels => pr-labels}/index.js (98%)
 rename scripts/{sync-pr-labels => pr-labels}/samples.json (100%)

diff --git a/.github/workflows/pr-labels.yml b/.github/workflows/pr-labels.yml
index bae29b0325..41827524e5 100644
--- a/.github/workflows/pr-labels.yml
+++ b/.github/workflows/pr-labels.yml
@@ -30,4 +30,4 @@ jobs:
         continue-on-error: true
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: node scripts/sync-pr-labels/index.js
+        run: node scripts/pr-labels/index.js
diff --git a/scripts/sync-pr-labels/README.md b/scripts/pr-labels/README.md
similarity index 90%
rename from scripts/sync-pr-labels/README.md
rename to scripts/pr-labels/README.md
index 404d4a6c62..d667c654ea 100644
--- a/scripts/sync-pr-labels/README.md
+++ b/scripts/pr-labels/README.md
@@ -30,7 +30,7 @@ Minor modules like docs and tests are omitted to keep PR tags clean and focused
 This script is designed to run in CI workflows. It automatically reads the `GITHUB_EVENT_PATH` payload to get the PR context.
 
 ```bash
-node scripts/sync-pr-labels/index.js
+node scripts/pr-labels/index.js
 ```
 
 ### Local Dry Run
@@ -38,10 +38,10 @@ You can test the labeling logic against an existing GitHub PR without actually a
 
 ```bash
 # Requires GITHUB_TOKEN environment variable or passing --token
-node scripts/sync-pr-labels/index.js --dry-run --repo larksuite/cli --pr-number 123
+node scripts/pr-labels/index.js --dry-run --repo larksuite/cli --pr-number 123
 ```
 
 To see the raw JSON output for programmatic use:
 ```bash
-node scripts/sync-pr-labels/index.js --dry-run --repo larksuite/cli --pr-number 123 --json
+node scripts/pr-labels/index.js --dry-run --repo larksuite/cli --pr-number 123 --json
 ```
\ No newline at end of file
diff --git a/scripts/sync-pr-labels/index.js b/scripts/pr-labels/index.js
similarity index 98%
rename from scripts/sync-pr-labels/index.js
rename to scripts/pr-labels/index.js
index 6ead27ebb9..f73b15fe52 100644
--- a/scripts/sync-pr-labels/index.js
+++ b/scripts/pr-labels/index.js
@@ -70,9 +70,9 @@ const CLASS_STANDARDS = {
 function printHelp() {
   const lines = [
     "Usage:",
-    "  node scripts/sync_pr_labels.js",
-    "  node scripts/sync_pr_labels.js --dry-run --pr-url <github-pr-url> [--token <token>] [--json]",
-    "  node scripts/sync_pr_labels.js --dry-run --repo <owner/name> --pr-number <number> [--token <token>] [--json]",
+    "  node scripts/pr-labels/index.js",
+    "  node scripts/pr-labels/index.js --dry-run --pr-url <github-pr-url> [--token <token>] [--json]",
+    "  node scripts/pr-labels/index.js --dry-run --repo <owner/name> --pr-number <number> [--token <token>] [--json]",
     "",
     "Modes:",
     "  default    Read the GitHub Actions event payload and apply labels",
diff --git a/scripts/sync-pr-labels/samples.json b/scripts/pr-labels/samples.json
similarity index 100%
rename from scripts/sync-pr-labels/samples.json
rename to scripts/pr-labels/samples.json

From de656ee1d35be9dce3bd6d27a274945263061bd1 Mon Sep 17 00:00:00 2001
From: williamfzc <178894043@qq.com>
Date: Tue, 31 Mar 2026 13:20:48 +0800
Subject: [PATCH 09/19] ci: add GitHub Actions workflow to check skill format

---
 .github/workflows/skill-format-check.yml | 32 +++++++++++
 scripts/check_skill_format.js            | 72 ++++++++++++++++++++++++
 skills/lark-shared/SKILL.md              |  3 +
 skills/lark-whiteboard/SKILL.md          |  1 +
 4 files changed, 108 insertions(+)
 create mode 100644 .github/workflows/skill-format-check.yml
 create mode 100644 scripts/check_skill_format.js

diff --git a/.github/workflows/skill-format-check.yml b/.github/workflows/skill-format-check.yml
new file mode 100644
index 0000000000..97e2a161db
--- /dev/null
+++ b/.github/workflows/skill-format-check.yml
@@ -0,0 +1,32 @@
+name: Skill Format Check
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "skills/**"
+      - "scripts/check_skill_format.js"
+      - ".github/workflows/skill-format-check.yml"
+  pull_request:
+    branches: [main]
+    paths:
+      - "skills/**"
+      - "scripts/check_skill_format.js"
+      - ".github/workflows/skill-format-check.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  check-format:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Run Skill Format Check
+        run: node scripts/check_skill_format.js
diff --git a/scripts/check_skill_format.js b/scripts/check_skill_format.js
new file mode 100644
index 0000000000..f6a61c7bf5
--- /dev/null
+++ b/scripts/check_skill_format.js
@@ -0,0 +1,72 @@
+const fs = require('fs');
+const path = require('path');
+
+const SKILLS_DIR = path.join(__dirname, '../skills');
+
+function checkSkillFormat() {
+  console.log('Checking skill format...');
+
+  if (!fs.existsSync(SKILLS_DIR)) {
+    console.error('Skills directory not found:', SKILLS_DIR);
+    process.exit(1);
+  }
+
+  const skills = fs.readdirSync(SKILLS_DIR).filter(file => {
+    return fs.statSync(path.join(SKILLS_DIR, file)).isDirectory();
+  });
+
+  let hasErrors = false;
+
+  skills.forEach(skill => {
+    const skillPath = path.join(SKILLS_DIR, skill);
+    const skillFile = path.join(skillPath, 'SKILL.md');
+
+    if (!fs.existsSync(skillFile)) {
+      console.error(`❌ [${skill}] Missing SKILL.md`);
+      hasErrors = true;
+      return;
+    }
+
+    const content = fs.readFileSync(skillFile, 'utf-8');
+
+    // 检查 YAML Frontmatter
+    if (!content.startsWith('---\n') && !content.startsWith('---\r\n')) {
+       console.error(`❌ [${skill}] SKILL.md must start with YAML frontmatter (---)`);
+       hasErrors = true;
+    } else {
+        // 兼容不同的换行符
+        let endOfFrontmatter = content.indexOf('\n---', 3);
+        if (endOfFrontmatter === -1) {
+             console.error(`❌ [${skill}] SKILL.md has unclosed YAML frontmatter`);
+             hasErrors = true;
+        } else {
+            const frontmatter = content.substring(3, endOfFrontmatter);
+            if (!frontmatter.includes('name:')) {
+                console.error(`❌ [${skill}] YAML frontmatter missing 'name'`);
+                hasErrors = true;
+            }
+            if (!frontmatter.includes('version:')) {
+                console.error(`❌ [${skill}] YAML frontmatter missing 'version'`);
+                hasErrors = true;
+            }
+            if (!frontmatter.includes('description:')) {
+                console.error(`❌ [${skill}] YAML frontmatter missing 'description'`);
+                hasErrors = true;
+            }
+            if (!frontmatter.includes('metadata:')) {
+                console.error(`❌ [${skill}] YAML frontmatter missing 'metadata'`);
+                hasErrors = true;
+            }
+        }
+    }
+  });
+
+  if (hasErrors) {
+    console.error('\n❌ Skill format check failed. Please fix the errors above.');
+    process.exit(1);
+  } else {
+    console.log('\n✅ Skill format check passed!');
+  }
+}
+
+checkSkillFormat();
diff --git a/skills/lark-shared/SKILL.md b/skills/lark-shared/SKILL.md
index c21bca7429..b9de0b1a45 100644
--- a/skills/lark-shared/SKILL.md
+++ b/skills/lark-shared/SKILL.md
@@ -2,6 +2,9 @@
 name: lark-shared
 version: 1.0.0
 description: "飞书/Lark CLI 共享基础：应用配置初始化、认证登录（auth login）、身份切换（--as user/bot）、权限与 scope 管理、Permission denied 错误处理、安全规则。当用户需要第一次配置(`lark-cli config init`)、使用登录授权(`lark-cli auth login`)、遇到权限不足、切换 user/bot 身份、配置 scope、或首次使用 lark-cli 时触发。"
+metadata:
+  requires:
+    bins: ["lark-cli"]
 ---
 
 # lark-cli 共享规则
diff --git a/skills/lark-whiteboard/SKILL.md b/skills/lark-whiteboard/SKILL.md
index 0bd7777e34..07000387d1 100644
--- a/skills/lark-whiteboard/SKILL.md
+++ b/skills/lark-whiteboard/SKILL.md
@@ -1,5 +1,6 @@
 ---
 name: lark-whiteboard
+version: 1.0.0
 description: >
   当用户要求在飞书云文档中绘制图表，或使用飞书画板绘制架构图、流程图、思维导图、时序图或其他可视化图表时使用此 skill。
 compatibility: Requires Node.js 18+

From 7b4657e476305e037b2c85e134cb1224b49fe5b0 Mon Sep 17 00:00:00 2001
From: williamfzc <178894043@qq.com>
Date: Tue, 31 Mar 2026 13:47:06 +0800
Subject: [PATCH 10/19] test(ci): update sample json to include expected_areas

Added `expected_areas` lists to each sample in `samples.json` to reflect
the newly added `area/*` high-level module tagging logic. Allows testing
to accurately check both `size/*` and `area/*` outputs.
---
 scripts/pr-labels/samples.json | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/scripts/pr-labels/samples.json b/scripts/pr-labels/samples.json
index 98373b399f..fe525154c3 100644
--- a/scripts/pr-labels/samples.json
+++ b/scripts/pr-labels/samples.json
@@ -7,6 +7,7 @@
     "status": "merged",
     "merged_at": "2026-03-30T12:15:45Z",
     "expected_label": "size/S",
+    "expected_areas": [],
     "review_note": "Pure docs sample. Useful to confirm low-risk paths stay in S even when total changed lines are not tiny."
   },
   {
@@ -17,6 +18,7 @@
     "status": "merged",
     "merged_at": "2026-03-28T09:33:24Z",
     "expected_label": "size/S",
+    "expected_areas": [],
     "review_note": "Docs sample, verifying docs changes remain in S."
   },
   {
@@ -27,6 +29,7 @@
     "status": "merged",
     "merged_at": "2026-03-28T16:00:15Z",
     "expected_label": "size/S",
+    "expected_areas": [],
     "review_note": "Docs sample, no effective business code changes."
   },
   {
@@ -37,6 +40,7 @@
     "status": "merged",
     "merged_at": "2026-03-28T03:43:44Z",
     "expected_label": "size/S",
+    "expected_areas": [],
     "review_note": "Docs sample, pure documentation clarification."
   },
   {
@@ -47,6 +51,7 @@
     "status": "merged",
     "merged_at": "2026-03-30T11:40:18Z",
     "expected_label": "size/M",
+    "expected_areas": ["area/shortcuts"],
     "review_note": "Small fix sample. Verify the lower edge of the M bucket within a single domain."
   },
   {
@@ -57,6 +62,7 @@
     "status": "merged",
     "merged_at": "2026-03-30T10:19:11Z",
     "expected_label": "size/M",
+    "expected_areas": ["area/shortcuts", "area/skills"],
     "review_note": "Security-like wording in the title but stays in one business domain (mail)."
   },
   {
@@ -67,6 +73,7 @@
     "status": "merged",
     "merged_at": "2026-03-30T03:09:31Z",
     "expected_label": "size/M",
+    "expected_areas": [],
     "review_note": "CI workflow change that goes beyond S threshold."
   },
   {
@@ -77,6 +84,7 @@
     "status": "merged",
     "merged_at": "2026-03-30T15:00:41Z",
     "expected_label": "size/M",
+    "expected_areas": ["area/shortcuts", "area/skills"],
     "review_note": "Single-domain feature with larger diff but effective changes stay in M."
   },
   {
@@ -87,6 +95,7 @@
     "status": "merged",
     "merged_at": "2026-03-30T09:19:24Z",
     "expected_label": "size/L",
+    "expected_areas": ["area/cmd"],
     "review_note": "Touches core area (cmd), bumping the size to L."
   },
   {
@@ -97,6 +106,7 @@
     "status": "merged",
     "merged_at": "2026-03-28T16:00:52Z",
     "expected_label": "size/L",
+    "expected_areas": ["area/shortcuts", "area/skills"],
     "review_note": "Docs change but touches multiple business domains, making it L."
   },
   {
@@ -107,6 +117,7 @@
     "status": "closed",
     "merged_at": null,
     "expected_label": "size/L",
+    "expected_areas": ["area/shortcuts"],
     "review_note": "Closed PR but useful as an L sample for effective lines exceeding 300."
   },
   {
@@ -117,6 +128,7 @@
     "status": "closed",
     "merged_at": null,
     "expected_label": "size/L",
+    "expected_areas": ["area/cmd", "area/skills"],
     "review_note": "Closed PR touching core area (cmd)."
   }
 ]
\ No newline at end of file

From c781307bd687ba6e08bbb85f3fcd6b46c976e63a Mon Sep 17 00:00:00 2001
From: williamfzc <178894043@qq.com>
Date: Tue, 31 Mar 2026 13:52:53 +0800
Subject: [PATCH 11/19] refactor(scripts): move skill format check to isolated
 directory and add README

---
 .github/workflows/skill-format-check.yml      |  6 +++---
 scripts/skill-format-check/README.md          | 21 +++++++++++++++++++
 .../index.js}                                 |  2 +-
 3 files changed, 25 insertions(+), 4 deletions(-)
 create mode 100644 scripts/skill-format-check/README.md
 rename scripts/{check_skill_format.js => skill-format-check/index.js} (97%)

diff --git a/.github/workflows/skill-format-check.yml b/.github/workflows/skill-format-check.yml
index 97e2a161db..7c8b8fc5f7 100644
--- a/.github/workflows/skill-format-check.yml
+++ b/.github/workflows/skill-format-check.yml
@@ -5,13 +5,13 @@ on:
     branches: [main]
     paths:
       - "skills/**"
-      - "scripts/check_skill_format.js"
+      - "scripts/skill-format-check/**"
       - ".github/workflows/skill-format-check.yml"
   pull_request:
     branches: [main]
     paths:
       - "skills/**"
-      - "scripts/check_skill_format.js"
+      - "scripts/skill-format-check/**"
       - ".github/workflows/skill-format-check.yml"
 
 permissions:
@@ -29,4 +29,4 @@ jobs:
           node-version: '20'
 
       - name: Run Skill Format Check
-        run: node scripts/check_skill_format.js
+        run: node scripts/skill-format-check/index.js
diff --git a/scripts/skill-format-check/README.md b/scripts/skill-format-check/README.md
new file mode 100644
index 0000000000..23fe9feddc
--- /dev/null
+++ b/scripts/skill-format-check/README.md
@@ -0,0 +1,21 @@
+# Skill Format Check
+
+This directory contains a script to validate the format of `SKILL.md` files located in the `../../skills` directory.
+
+## Purpose
+
+The `index.js` script ensures that all `SKILL.md` files conform to the standard template defined in `skill-template/skill-template.md`. Specifically, it checks that the YAML frontmatter includes the following required fields:
+- `name`
+- `version`
+- `description`
+- `metadata`
+
+## Usage
+
+This script is executed automatically via GitHub Actions (`.github/workflows/skill-format-check.yml`) on pull requests and pushes that modify the `skills/` directory.
+
+To run the check manually from the root of the repository, execute:
+
+```bash
+node scripts/skill-format-check/index.js
+```
diff --git a/scripts/check_skill_format.js b/scripts/skill-format-check/index.js
similarity index 97%
rename from scripts/check_skill_format.js
rename to scripts/skill-format-check/index.js
index f6a61c7bf5..540d75d1ef 100644
--- a/scripts/check_skill_format.js
+++ b/scripts/skill-format-check/index.js
@@ -1,7 +1,7 @@
 const fs = require('fs');
 const path = require('path');
 
-const SKILLS_DIR = path.join(__dirname, '../skills');
+const SKILLS_DIR = path.join(__dirname, '../../skills');
 
 function checkSkillFormat() {
   console.log('Checking skill format...');

From 117cb8e6bb6de3aff8aaa7d9deb87b3cbacd5820 Mon Sep 17 00:00:00 2001
From: williamfzc <178894043@qq.com>
Date: Tue, 31 Mar 2026 14:15:33 +0800
Subject: [PATCH 12/19] test(scripts): add positive and negative tests for
 skill format check

---
 scripts/skill-format-check/README.md          | 14 +++++
 scripts/skill-format-check/index.js           |  6 +-
 scripts/skill-format-check/test.sh            | 63 +++++++++++++++++++
 .../tests/bad-skill-no-frontmatter/SKILL.md   |  3 +
 .../bad-skill-unclosed-frontmatter/SKILL.md   |  9 +++
 .../tests/bad-skill/SKILL.md                  |  8 +++
 .../tests/good-skill-complex/SKILL.md         | 17 +++++
 .../tests/good-skill-minimal/SKILL.md         | 10 +++
 .../tests/good-skill/SKILL.md                 | 12 ++++
 9 files changed, 140 insertions(+), 2 deletions(-)
 create mode 100755 scripts/skill-format-check/test.sh
 create mode 100644 scripts/skill-format-check/tests/bad-skill-no-frontmatter/SKILL.md
 create mode 100644 scripts/skill-format-check/tests/bad-skill-unclosed-frontmatter/SKILL.md
 create mode 100644 scripts/skill-format-check/tests/bad-skill/SKILL.md
 create mode 100644 scripts/skill-format-check/tests/good-skill-complex/SKILL.md
 create mode 100644 scripts/skill-format-check/tests/good-skill-minimal/SKILL.md
 create mode 100644 scripts/skill-format-check/tests/good-skill/SKILL.md

diff --git a/scripts/skill-format-check/README.md b/scripts/skill-format-check/README.md
index 23fe9feddc..dffb955dda 100644
--- a/scripts/skill-format-check/README.md
+++ b/scripts/skill-format-check/README.md
@@ -19,3 +19,17 @@ To run the check manually from the root of the repository, execute:
 ```bash
 node scripts/skill-format-check/index.js
 ```
+
+You can also specify a custom target directory as the first argument:
+
+```bash
+node scripts/skill-format-check/index.js ./path/to/my/skills
+```
+
+## Testing
+
+This tool comes with a quick validation script to ensure it correctly identifies good and bad skill formats. To run the tests, execute:
+
+```bash
+./scripts/skill-format-check/test.sh
+```
diff --git a/scripts/skill-format-check/index.js b/scripts/skill-format-check/index.js
index 540d75d1ef..d59a45f66d 100644
--- a/scripts/skill-format-check/index.js
+++ b/scripts/skill-format-check/index.js
@@ -1,10 +1,12 @@
 const fs = require('fs');
 const path = require('path');
 
-const SKILLS_DIR = path.join(__dirname, '../../skills');
+// Allow passing a target directory as the first argument, default to '../../skills'
+const targetDirArg = process.argv[2] || '../../skills';
+const SKILLS_DIR = path.resolve(__dirname, targetDirArg);
 
 function checkSkillFormat() {
-  console.log('Checking skill format...');
+  console.log(`Checking skill format in ${SKILLS_DIR}...`);
 
   if (!fs.existsSync(SKILLS_DIR)) {
     console.error('Skills directory not found:', SKILLS_DIR);
diff --git a/scripts/skill-format-check/test.sh b/scripts/skill-format-check/test.sh
new file mode 100755
index 0000000000..6749c4551a
--- /dev/null
+++ b/scripts/skill-format-check/test.sh
@@ -0,0 +1,63 @@
+#!/bin/bash
+
+# Get the directory of this script
+DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
+INDEX_JS="$DIR/index.js"
+
+echo "=== Running tests for skill-format-check ==="
+echo "Index script: $INDEX_JS"
+
+# Function to run a positive test
+run_positive_test() {
+    local test_name=$1
+    echo -e "\n--- [Positive] $test_name ---"
+    
+    mkdir -p "$DIR/tests/temp_test_dir"
+    cp -r "$DIR/tests/$test_name" "$DIR/tests/temp_test_dir/"
+    
+    node "$INDEX_JS" "$DIR/tests/temp_test_dir"
+    
+    if [ $? -eq 0 ]; then
+        echo "✅ Passed! (Correctly validated $test_name)"
+        rm -rf "$DIR/tests/temp_test_dir"
+        return 0
+    else
+        echo "❌ Failed! Expected $test_name to pass but it failed."
+        rm -rf "$DIR/tests/temp_test_dir"
+        exit 1
+    fi
+}
+
+# Function to run a negative test
+run_negative_test() {
+    local test_name=$1
+    echo -e "\n--- [Negative] $test_name ---"
+    
+    mkdir -p "$DIR/tests/temp_test_dir"
+    cp -r "$DIR/tests/$test_name" "$DIR/tests/temp_test_dir/"
+    
+    # Run the script and suppress error output since we expect it to fail
+    node "$INDEX_JS" "$DIR/tests/temp_test_dir" > /dev/null 2>&1
+    
+    if [ $? -eq 1 ]; then
+        echo "✅ Passed! (Correctly rejected $test_name)"
+        rm -rf "$DIR/tests/temp_test_dir"
+        return 0
+    else
+        echo "❌ Failed! Expected $test_name to fail but it passed."
+        rm -rf "$DIR/tests/temp_test_dir"
+        exit 1
+    fi
+}
+
+# Run positive tests
+run_positive_test "good-skill"
+run_positive_test "good-skill-minimal"
+run_positive_test "good-skill-complex"
+
+# Run negative tests
+run_negative_test "bad-skill"
+run_negative_test "bad-skill-no-frontmatter"
+run_negative_test "bad-skill-unclosed-frontmatter"
+
+echo -e "\n🎉 All tests passed successfully!"
diff --git a/scripts/skill-format-check/tests/bad-skill-no-frontmatter/SKILL.md b/scripts/skill-format-check/tests/bad-skill-no-frontmatter/SKILL.md
new file mode 100644
index 0000000000..5a7afa3e9c
--- /dev/null
+++ b/scripts/skill-format-check/tests/bad-skill-no-frontmatter/SKILL.md
@@ -0,0 +1,3 @@
+# No Frontmatter Skill
+
+This skill completely lacks a YAML frontmatter.
diff --git a/scripts/skill-format-check/tests/bad-skill-unclosed-frontmatter/SKILL.md b/scripts/skill-format-check/tests/bad-skill-unclosed-frontmatter/SKILL.md
new file mode 100644
index 0000000000..189d625330
--- /dev/null
+++ b/scripts/skill-format-check/tests/bad-skill-unclosed-frontmatter/SKILL.md
@@ -0,0 +1,9 @@
+---
+name: bad-skill-unclosed
+version: 1.0.0
+description: "This skill has an unclosed frontmatter block."
+metadata: {}
+
+# Unclosed Frontmatter Skill
+
+This frontmatter does not have a closing `---` block.
\ No newline at end of file
diff --git a/scripts/skill-format-check/tests/bad-skill/SKILL.md b/scripts/skill-format-check/tests/bad-skill/SKILL.md
new file mode 100644
index 0000000000..d590742997
--- /dev/null
+++ b/scripts/skill-format-check/tests/bad-skill/SKILL.md
@@ -0,0 +1,8 @@
+---
+name: bad-skill
+description: "This skill is missing version and metadata."
+---
+
+# Bad Skill
+
+This skill is missing required fields.
diff --git a/scripts/skill-format-check/tests/good-skill-complex/SKILL.md b/scripts/skill-format-check/tests/good-skill-complex/SKILL.md
new file mode 100644
index 0000000000..0f7b51836b
--- /dev/null
+++ b/scripts/skill-format-check/tests/good-skill-complex/SKILL.md
@@ -0,0 +1,17 @@
+---
+name: good-skill-complex
+version: 2.5.1-beta
+description: >
+  A very complex description
+  that spans multiple lines
+  and contains weird chars: !@#$%^&*()
+metadata:
+  requires:
+    bins: ["lark-cli", "node"]
+  cliHelp: "lark-cli something --help"
+  customField: "customValue"
+---
+
+# Complex Skill
+
+This skill has a complex frontmatter block.
diff --git a/scripts/skill-format-check/tests/good-skill-minimal/SKILL.md b/scripts/skill-format-check/tests/good-skill-minimal/SKILL.md
new file mode 100644
index 0000000000..ca3f481c27
--- /dev/null
+++ b/scripts/skill-format-check/tests/good-skill-minimal/SKILL.md
@@ -0,0 +1,10 @@
+---
+name: good-skill-minimal
+version: 0.1.0
+description: Minimal valid description
+metadata: {}
+---
+
+# Minimal Skill
+
+This has the bare minimum required fields.
diff --git a/scripts/skill-format-check/tests/good-skill/SKILL.md b/scripts/skill-format-check/tests/good-skill/SKILL.md
new file mode 100644
index 0000000000..8c2e7b40fc
--- /dev/null
+++ b/scripts/skill-format-check/tests/good-skill/SKILL.md
@@ -0,0 +1,12 @@
+---
+name: good-skill
+version: 1.0.0
+description: "This is a properly formatted skill."
+metadata:
+  requires:
+    bins: ["lark-cli"]
+---
+
+# Good Skill
+
+This skill follows all the formatting rules.

From 701160cca30f3de227eb16e605c45b9d4afe96e5 Mon Sep 17 00:00:00 2001
From: williamfzc <178894043@qq.com>
Date: Tue, 31 Mar 2026 14:26:00 +0800
Subject: [PATCH 13/19] fix(scripts): revert skill changes and downgrade
 version/metadata checks to warnings

---
 scripts/skill-format-check/index.js                 | 8 ++++----
 scripts/skill-format-check/tests/bad-skill/SKILL.md | 6 +++---
 skills/lark-shared/SKILL.md                         | 3 ---
 skills/lark-whiteboard/SKILL.md                     | 1 -
 4 files changed, 7 insertions(+), 11 deletions(-)

diff --git a/scripts/skill-format-check/index.js b/scripts/skill-format-check/index.js
index d59a45f66d..534b8a926f 100644
--- a/scripts/skill-format-check/index.js
+++ b/scripts/skill-format-check/index.js
@@ -48,16 +48,16 @@ function checkSkillFormat() {
                 hasErrors = true;
             }
             if (!frontmatter.includes('version:')) {
-                console.error(`❌ [${skill}] YAML frontmatter missing 'version'`);
-                hasErrors = true;
+                console.warn(`⚠️  [${skill}] YAML frontmatter missing 'version' (Warning only)`);
+                // hasErrors = true;
             }
             if (!frontmatter.includes('description:')) {
                 console.error(`❌ [${skill}] YAML frontmatter missing 'description'`);
                 hasErrors = true;
             }
             if (!frontmatter.includes('metadata:')) {
-                console.error(`❌ [${skill}] YAML frontmatter missing 'metadata'`);
-                hasErrors = true;
+                console.warn(`⚠️  [${skill}] YAML frontmatter missing 'metadata' (Warning only)`);
+                // hasErrors = true; // Downgrade to warning to not fail on existing skills
             }
         }
     }
diff --git a/scripts/skill-format-check/tests/bad-skill/SKILL.md b/scripts/skill-format-check/tests/bad-skill/SKILL.md
index d590742997..465a05da2e 100644
--- a/scripts/skill-format-check/tests/bad-skill/SKILL.md
+++ b/scripts/skill-format-check/tests/bad-skill/SKILL.md
@@ -1,8 +1,8 @@
 ---
-name: bad-skill
-description: "This skill is missing version and metadata."
+version: 1.0.0
+metadata: {}
 ---
 
 # Bad Skill
 
-This skill is missing required fields.
+This skill is missing required fields like name and description.
diff --git a/skills/lark-shared/SKILL.md b/skills/lark-shared/SKILL.md
index b9de0b1a45..c21bca7429 100644
--- a/skills/lark-shared/SKILL.md
+++ b/skills/lark-shared/SKILL.md
@@ -2,9 +2,6 @@
 name: lark-shared
 version: 1.0.0
 description: "飞书/Lark CLI 共享基础：应用配置初始化、认证登录（auth login）、身份切换（--as user/bot）、权限与 scope 管理、Permission denied 错误处理、安全规则。当用户需要第一次配置(`lark-cli config init`)、使用登录授权(`lark-cli auth login`)、遇到权限不足、切换 user/bot 身份、配置 scope、或首次使用 lark-cli 时触发。"
-metadata:
-  requires:
-    bins: ["lark-cli"]
 ---
 
 # lark-cli 共享规则
diff --git a/skills/lark-whiteboard/SKILL.md b/skills/lark-whiteboard/SKILL.md
index 07000387d1..0bd7777e34 100644
--- a/skills/lark-whiteboard/SKILL.md
+++ b/skills/lark-whiteboard/SKILL.md
@@ -1,6 +1,5 @@
 ---
 name: lark-whiteboard
-version: 1.0.0
 description: >
   当用户要求在飞书云文档中绘制图表，或使用飞书画板绘制架构图、流程图、思维导图、时序图或其他可视化图表时使用此 skill。
 compatibility: Requires Node.js 18+

From cc58e06de1433103e14ebe0ed2f634d8bae4770f Mon Sep 17 00:00:00 2001
From: williamfzc <178894043@qq.com>
Date: Tue, 31 Mar 2026 14:53:10 +0800
Subject: [PATCH 14/19] fix(scripts): completely remove version check and skip
 lark-shared

---
 scripts/skill-format-check/README.md |  5 +++--
 scripts/skill-format-check/index.js  | 10 ++++++----
 2 files changed, 9 insertions(+), 6 deletions(-)

diff --git a/scripts/skill-format-check/README.md b/scripts/skill-format-check/README.md
index dffb955dda..f67f303c55 100644
--- a/scripts/skill-format-check/README.md
+++ b/scripts/skill-format-check/README.md
@@ -6,9 +6,10 @@ This directory contains a script to validate the format of `SKILL.md` files loca
 
 The `index.js` script ensures that all `SKILL.md` files conform to the standard template defined in `skill-template/skill-template.md`. Specifically, it checks that the YAML frontmatter includes the following required fields:
 - `name`
-- `version`
 - `description`
-- `metadata`
+- `metadata` (outputs a warning if missing, does not fail the build)
+
+> **Note:** The `lark-shared` skill is explicitly excluded from these format checks.
 
 ## Usage
 
diff --git a/scripts/skill-format-check/index.js b/scripts/skill-format-check/index.js
index 534b8a926f..1dd5a38d4e 100644
--- a/scripts/skill-format-check/index.js
+++ b/scripts/skill-format-check/index.js
@@ -20,6 +20,12 @@ function checkSkillFormat() {
   let hasErrors = false;
 
   skills.forEach(skill => {
+    // Skip lark-shared skill completely
+    if (skill === 'lark-shared') {
+        console.log(`⏭️  Skipping check for ${skill}`);
+        return;
+    }
+
     const skillPath = path.join(SKILLS_DIR, skill);
     const skillFile = path.join(skillPath, 'SKILL.md');
 
@@ -47,10 +53,6 @@ function checkSkillFormat() {
                 console.error(`❌ [${skill}] YAML frontmatter missing 'name'`);
                 hasErrors = true;
             }
-            if (!frontmatter.includes('version:')) {
-                console.warn(`⚠️  [${skill}] YAML frontmatter missing 'version' (Warning only)`);
-                // hasErrors = true;
-            }
             if (!frontmatter.includes('description:')) {
                 console.error(`❌ [${skill}] YAML frontmatter missing 'description'`);
                 hasErrors = true;

From 4df331f19e7f678b6a9f193e3a727c88cd943070 Mon Sep 17 00:00:00 2001
From: williamfzc <178894043@qq.com>
Date: Tue, 31 Mar 2026 14:59:59 +0800
Subject: [PATCH 15/19] refactor(ci): improve pr-labels script readability and
 maintainability

- Reorganized code into logical sections with clear comments
- Encapsulated GitHub API interactions into a reusable `GitHubClient` class
- Extracted and centralized classification logic into a pure `evaluateRules` function
- Replaced magic numbers with named constants (`THRESHOLD_L`, `THRESHOLD_XL`)
- Fixed `ROOT` path resolution logic
- Simplified conditional statements and control flow
---
 scripts/pr-labels/index.js | 608 ++++++++++++++++++-------------------
 1 file changed, 298 insertions(+), 310 deletions(-)
 mode change 100644 => 100755 scripts/pr-labels/index.js

diff --git a/scripts/pr-labels/index.js b/scripts/pr-labels/index.js
old mode 100644
new mode 100755
index f73b15fe52..e160b793b3
--- a/scripts/pr-labels/index.js
+++ b/scripts/pr-labels/index.js
@@ -5,9 +5,16 @@
 const fs = require("node:fs/promises");
 const path = require("node:path");
 
+// ============================================================================
+// Constants & Configuration
+// ============================================================================
+
 const API_BASE = "https://api.github.com";
 const SCRIPT_DIR = __dirname;
-const ROOT = path.join(SCRIPT_DIR, "..");
+const ROOT = path.join(SCRIPT_DIR, "..", "..");
+
+const THRESHOLD_L = 300;
+const THRESHOLD_XL = 1200;
 
 const LABEL_DEFINITIONS = {
   "size/S": { color: "77bb00", description: "Low-risk docs, CI, test, or chore only changes" },
@@ -18,6 +25,7 @@ const LABEL_DEFINITIONS = {
 
 const MANAGED_LABELS = new Set(Object.keys(LABEL_DEFINITIONS));
 
+// File path matching configurations
 const DOC_SUFFIXES = [".md", ".mdx", ".txt", ".rst"];
 const LOW_RISK_PREFIXES = [".github/", "docs/", ".changeset/", "testdata/", "tests/", "skill-template/"];
 const LOW_RISK_FILENAMES = new Set(["readme.md", "readme.zh.md", "changelog.md", "license", "cla.md"]);
@@ -27,6 +35,8 @@ const CORE_PREFIXES = ["internal/auth/", "internal/engine/", "internal/config/",
 const HEAD_BUSINESS_DOMAINS = new Set(["im", "contact", "ccm", "base", "docx"]);
 const LOW_RISK_TYPES = new Set(["docs", "ci", "test", "chore"]);
 
+const SENSITIVE_PATTERN = /(^|\/)(auth|permission|permissions|security)(\/|_|\.|$)/;
+
 const CLASS_STANDARDS = {
   "size/S": {
     channel: "Fast track (S)",
@@ -67,27 +77,9 @@ const CLASS_STANDARDS = {
   },
 };
 
-function printHelp() {
-  const lines = [
-    "Usage:",
-    "  node scripts/pr-labels/index.js",
-    "  node scripts/pr-labels/index.js --dry-run --pr-url <github-pr-url> [--token <token>] [--json]",
-    "  node scripts/pr-labels/index.js --dry-run --repo <owner/name> --pr-number <number> [--token <token>] [--json]",
-    "",
-    "Modes:",
-    "  default    Read the GitHub Actions event payload and apply labels",
-    "  --dry-run  Fetch the PR, compute the managed label, and print the result without writing labels",
-    "",
-    "Options:",
-    "  --pr-url <url>       GitHub pull request URL, for example https://github.com/larksuite/cli/pull/123",
-    "  --repo <owner/name>  Repository name, used with --pr-number",
-    "  --pr-number <n>      Pull request number, used with --repo",
-    "  --token <token>      GitHub token override; falls back to GITHUB_TOKEN",
-    "  --json               Print dry-run output as JSON instead of the default one-line summary",
-    "  --help               Show this message",
-  ];
-  console.log(lines.join("\n"));
-}
+// ============================================================================
+// Utilities
+// ============================================================================
 
 function log(message) {
   console.error(`sync-pr-labels: ${message}`);
@@ -109,180 +101,124 @@ function envOrFail(name) {
   return value;
 }
 
-function buildHeaders(token, hasBody = false) {
-  const headers = {
-    Accept: "application/vnd.github+json",
-    "X-GitHub-Api-Version": "2022-11-28",
-  };
-  if (token) {
-    headers.Authorization = `Bearer ${token}`;
+// ============================================================================
+// GitHub API Client
+// ============================================================================
+
+class GitHubClient {
+  constructor(token, repo, prNumber) {
+    this.token = token;
+    this.repo = repo;
+    this.prNumber = prNumber;
   }
-  if (hasBody) {
-    headers["Content-Type"] = "application/json";
+
+  buildHeaders(hasBody = false) {
+    const headers = {
+      Accept: "application/vnd.github+json",
+      "X-GitHub-Api-Version": "2022-11-28",
+    };
+    if (this.token) {
+      headers.Authorization = `Bearer ${this.token}`;
+    }
+    if (hasBody) {
+      headers["Content-Type"] = "application/json";
+    }
+    return headers;
   }
-  return headers;
-}
 
-function parseArgs(argv) {
-  const options = {
-    dryRun: false,
-    json: false,
-    help: false,
-    prUrl: "",
-    repo: "",
-    prNumber: "",
-    token: "",
-  };
+  async request(endpoint, options = {}) {
+    const { method = "GET", payload, allow404 = false } = options;
+    const hasBody = payload !== undefined;
+    const url = endpoint.startsWith("http") ? endpoint : `${API_BASE}${endpoint}`;
+    
+    const response = await fetch(url, {
+      method,
+      headers: this.buildHeaders(hasBody),
+      body: hasBody ? JSON.stringify(payload) : undefined,
+    });
 
-  for (let i = 0; i < argv.length; i += 1) {
-    const arg = argv[i];
-    if (arg === "--dry-run") {
-      options.dryRun = true;
-    } else if (arg === "--json") {
-      options.json = true;
-    } else if (arg === "--help" || arg === "-h") {
-      options.help = true;
-    } else if (arg === "--pr-url") {
-      options.prUrl = argv[i + 1] || "";
-      i += 1;
-    } else if (arg === "--repo") {
-      options.repo = argv[i + 1] || "";
-      i += 1;
-    } else if (arg === "--pr-number") {
-      options.prNumber = argv[i + 1] || "";
-      i += 1;
-    } else if (arg === "--token") {
-      options.token = argv[i + 1] || "";
-      i += 1;
-    } else {
-      throw new Error(`unknown argument: ${arg}`);
+    if (allow404 && response.status === 404) {
+      return null;
     }
-  }
 
-  return options;
-}
+    if (!response.ok) {
+      const detail = await response.text();
+      throw new Error(`GitHub API ${method} ${url} failed: ${response.status} ${detail}`);
+    }
 
-function parsePrUrl(prUrl) {
-  let parsed;
-  try {
-    parsed = new URL(prUrl);
-  } catch {
-    throw new Error(`invalid PR URL: ${prUrl}`);
+    const text = await response.text();
+    return text ? JSON.parse(text) : null;
   }
 
-  const match = parsed.pathname.match(/^\/([^/]+)\/([^/]+)\/pull\/(\d+)\/?$/);
-  if (!match) {
-    throw new Error(`unsupported PR URL format: ${prUrl}`);
+  async getPullRequest() {
+    return this.request(`/repos/${this.repo}/pulls/${this.prNumber}`);
   }
 
-  return {
-    repo: `${match[1]}/${match[2]}`,
-    prNumber: Number(match[3]),
-  };
-}
-
-async function githubRequest(url, token, options = {}) {
-  const { method = "GET", payload, allow404 = false } = options;
-  const hasBody = payload !== undefined;
-  const response = await fetch(url, {
-    method,
-    headers: buildHeaders(token, hasBody),
-    body: hasBody ? JSON.stringify(payload) : undefined,
-  });
-
-  if (allow404 && response.status === 404) {
-    return null;
+  async listPrFiles() {
+    const files = [];
+    for (let page = 1; ; page += 1) {
+      const params = new URLSearchParams({ per_page: "100", page: String(page) });
+      const batch = await this.request(`/repos/${this.repo}/pulls/${this.prNumber}/files?${params}`);
+      if (!batch || batch.length === 0) {
+        break;
+      }
+      files.push(...batch);
+      if (batch.length < 100) {
+        break;
+      }
+    }
+    return files;
   }
 
-  if (!response.ok) {
-    const detail = await response.text();
-    throw new Error(`GitHub API ${method} ${url} failed: ${response.status} ${detail}`);
+  async listIssueLabels() {
+    const labels = await this.request(`/repos/${this.repo}/issues/${this.prNumber}/labels`);
+    return new Set(labels.map((item) => item.name));
   }
 
-  const text = await response.text();
-  return text ? JSON.parse(text) : null;
-}
-
-async function loadEventPayload(filePath) {
-  return JSON.parse(await fs.readFile(filePath, "utf8"));
-}
+  async syncLabelDefinition(name) {
+    const label = LABEL_DEFINITIONS[name];
+    const createUrl = `/repos/${this.repo}/labels`;
+    const updateUrl = `/repos/${this.repo}/labels/${encodeURIComponent(name)}`;
 
-async function getPullRequest(repo, prNumber, token) {
-  const url = `${API_BASE}/repos/${repo}/pulls/${prNumber}`;
-  return githubRequest(url, token);
-}
-
-async function listPrFiles(repo, prNumber, token) {
-  const files = [];
-  for (let page = 1; ; page += 1) {
-    const params = new URLSearchParams({ per_page: "100", page: String(page) });
-    const url = `${API_BASE}/repos/${repo}/pulls/${prNumber}/files?${params.toString()}`;
-    const batch = await githubRequest(url, token);
-    if (!batch || batch.length === 0) {
-      break;
-    }
-    files.push(...batch);
-    if (batch.length < 100) {
-      break;
+    try {
+      await this.request(createUrl, {
+        method: "POST",
+        payload: { name, color: label.color, description: label.description },
+      });
+      log(`created label ${name}`);
+    } catch (error) {
+      if (!String(error.message || error).includes(" 422 ")) {
+        throw error;
+      }
+      await this.request(updateUrl, {
+        method: "PATCH",
+        payload: { new_name: name, color: label.color, description: label.description },
+      });
+      log(`updated label ${name}`);
     }
   }
-  return files;
-}
-
-async function listIssueLabels(repo, prNumber, token) {
-  const url = `${API_BASE}/repos/${repo}/issues/${prNumber}/labels`;
-  const labels = await githubRequest(url, token);
-  return new Set(labels.map((item) => item.name));
-}
-
-async function syncLabelDefinition(repo, token, name) {
-  const label = LABEL_DEFINITIONS[name];
-  const createUrl = `${API_BASE}/repos/${repo}/labels`;
-  const updateUrl = `${API_BASE}/repos/${repo}/labels/${encodeURIComponent(name)}`;
 
-  try {
-    await githubRequest(createUrl, token, {
+  async addLabels(labels) {
+    if (labels.length === 0) return;
+    await this.request(`/repos/${this.repo}/issues/${this.prNumber}/labels`, {
       method: "POST",
-      payload: {
-        name,
-        color: label.color,
-        description: label.description,
-      },
+      payload: { labels },
     });
-    log(`created label ${name}`);
-  } catch (error) {
-    if (!String(error.message || error).includes(" 422 ")) {
-      throw error;
-    }
-    await githubRequest(updateUrl, token, {
-      method: "PATCH",
-      payload: {
-        new_name: name,
-        color: label.color,
-        description: label.description,
-      },
-    });
-    log(`updated label ${name}`);
+    log(`added labels: ${labels.join(", ")}`);
   }
-}
 
-async function addLabels(repo, prNumber, token, labels) {
-  if (labels.length === 0) {
-    return;
+  async removeLabel(name) {
+    await this.request(`/repos/${this.repo}/issues/${this.prNumber}/labels/${encodeURIComponent(name)}`, {
+      method: "DELETE",
+      allow404: true,
+    });
+    log(`removed label: ${name}`);
   }
-  const url = `${API_BASE}/repos/${repo}/issues/${prNumber}/labels`;
-  await githubRequest(url, token, {
-    method: "POST",
-    payload: { labels },
-  });
-  log(`added labels: ${labels.join(", ")}`);
 }
 
-async function removeLabel(repo, prNumber, token, name) {
-  const url = `${API_BASE}/repos/${repo}/issues/${prNumber}/labels/${encodeURIComponent(name)}`;
-  await githubRequest(url, token, { method: "DELETE", allow404: true });
-  log(`removed label: ${name}`);
-}
+// ============================================================================
+// Path & Domain Heuristics
+// ============================================================================
 
 function parsePrType(title) {
   const match = String(title || "").trim().match(/^([a-z]+)(?:\([^)]+\))?!?:/i);
@@ -293,18 +229,10 @@ function isLowRiskPath(filePath) {
   const normalized = normalizePath(filePath);
   const basename = path.posix.basename(normalized);
 
-  if (DOC_SUFFIXES.some((suffix) => normalized.endsWith(suffix))) {
-    return true;
-  }
-  if (LOW_RISK_FILENAMES.has(basename)) {
-    return true;
-  }
-  if (LOW_RISK_PREFIXES.some((prefix) => normalized.startsWith(prefix))) {
-    return true;
-  }
-  if (LOW_RISK_TEST_SUFFIXES.some((suffix) => normalized.endsWith(suffix))) {
-    return true;
-  }
+  if (DOC_SUFFIXES.some((suffix) => normalized.endsWith(suffix))) return true;
+  if (LOW_RISK_FILENAMES.has(basename)) return true;
+  if (LOW_RISK_PREFIXES.some((prefix) => normalized.startsWith(prefix))) return true;
+  if (LOW_RISK_TEST_SUFFIXES.some((suffix) => normalized.endsWith(suffix))) return true;
   return normalized.includes("/testdata/");
 }
 
@@ -335,13 +263,9 @@ function getImportantArea(filePath) {
 
 async function detectNewShortcutDomain(files) {
   for (const item of files) {
-    if (item.status !== "added") {
-      continue;
-    }
+    if (item.status !== "added") continue;
     const domain = shortcutDomainForPath(item.filename);
-    if (!domain) {
-      continue;
-    }
+    if (!domain) continue;
     try {
       await fs.access(path.join(ROOT, "shortcuts", domain));
     } catch {
@@ -355,25 +279,20 @@ function collectCoreAreas(filenames) {
   const areas = new Set();
   for (const name of filenames) {
     const normalized = normalizePath(name);
-    if (normalized.startsWith("cmd/")) {
-      areas.add("cmd");
-    } else if (normalized.startsWith("internal/auth/")) {
-      areas.add("internal/auth");
-    } else if (normalized.startsWith("internal/engine/")) {
-      areas.add("internal/engine");
-    } else if (normalized.startsWith("internal/config/")) {
-      areas.add("internal/config");
+    for (const prefix of CORE_PREFIXES) {
+      if (normalized.startsWith(prefix)) {
+        // remove trailing slash for area name
+        areas.add(prefix.slice(0, -1));
+      }
     }
   }
   return areas;
 }
 
 function collectSensitiveKeywords(filenames) {
-  const pattern = /(^|\/)(auth|permission|permissions|security)(\/|_|\.|$)/;
   const hits = new Set();
   for (const name of filenames) {
-    const normalized = normalizePath(name);
-    const match = normalized.match(pattern);
+    const match = normalizePath(name).match(SENSITIVE_PATTERN);
     if (match && match[2]) {
       hits.add(match[2]);
     }
@@ -381,39 +300,103 @@ function collectSensitiveKeywords(filenames) {
   return [...hits].sort();
 }
 
+// ============================================================================
+// Classification Logic
+// ============================================================================
+
+function evaluateRules(context) {
+  const {
+    prType, effectiveChanges, lowRiskOnly,
+    domains, headDomains, coreAreas, coreSignals,
+    sensitiveKeywords, sensitive, newShortcutDomain,
+    singleDomain, multiDomain, filenames
+  } = context;
+
+  const reasons = [];
+  let label;
+
+  if (lowRiskOnly && (LOW_RISK_TYPES.has(prType) || effectiveChanges === 0)) {
+    reasons.push("Only low-risk docs, CI, test, or chore paths were changed, with no effective business code or Skill changes");
+    label = "size/S";
+    return { label, reasons };
+  }
+
+  // XL is reserved for architecture-level or global-impact changes.
+  const isXL =
+    effectiveChanges > THRESHOLD_XL ||
+    (prType === "refactor" && sensitive && effectiveChanges >= THRESHOLD_L) ||
+    (coreAreas.size >= 2 && (multiDomain || effectiveChanges >= THRESHOLD_L)) ||
+    (headDomains.length >= 2 && sensitive);
+
+  if (isXL) {
+    if (effectiveChanges > THRESHOLD_XL) reasons.push("Effective business code or Skill changes are far beyond the L threshold");
+    if (prType === "refactor" && sensitive && effectiveChanges >= THRESHOLD_L) reasons.push("Refactor PR touches core or sensitive paths");
+    if (coreAreas.size >= 2) reasons.push("Touches multiple core areas at the same time");
+    if (headDomains.length >= 2) reasons.push("Impacts multiple major business domains");
+    coreSignals.forEach((signal) => reasons.push(`Core area hit: ${signal}`));
+    sensitiveKeywords.forEach((keyword) => reasons.push(`Sensitive keyword hit: ${keyword}`));
+    label = "size/XL";
+  } else if (
+    prType === "refactor" ||
+    effectiveChanges >= THRESHOLD_L ||
+    Boolean(newShortcutDomain) ||
+    multiDomain ||
+    sensitive
+  ) {
+    if (prType === "refactor") reasons.push("PR type is refactor");
+    if (effectiveChanges >= THRESHOLD_L) reasons.push(`Effective business code or Skill changes exceed ${THRESHOLD_L} lines`);
+    if (newShortcutDomain) reasons.push(`Introduces a new business domain directory: shortcuts/${newShortcutDomain}/`);
+    if (multiDomain) reasons.push("Touches multiple business domains");
+    coreSignals.forEach((signal) => reasons.push(`Core area hit: ${signal}`));
+    sensitiveKeywords.forEach((keyword) => reasons.push(`Sensitive keyword hit: ${keyword}`));
+    label = "size/L";
+  } else {
+    if (filenames.some(isBusinessSkillPath) || effectiveChanges > 0) {
+      reasons.push("Regular feat, fix, or Skill change within a single business domain");
+    }
+    if (singleDomain && domains.size > 0) {
+      reasons.push(`Impact is limited to a single business domain: ${[...domains].sort().join(", ")}`);
+    }
+    if (effectiveChanges < THRESHOLD_L) {
+      reasons.push(`Effective business code or Skill changes are below ${THRESHOLD_L} lines`);
+    }
+    label = "size/M";
+  }
+
+  return { label, reasons };
+}
+
 async function classifyPr(payload, files) {
   const pr = payload.pull_request;
   const title = pr.title || "";
   const prType = parsePrType(title);
   const filenames = files.map((item) => item.filename || "");
+  
   // Filter out docs, tests, and other low-risk paths so the size label tracks business impact.
   const effectiveChanges = files.reduce(
     (sum, item) => sum + (isLowRiskPath(item.filename) ? 0 : (item.changes || 0)),
     0,
   );
   const totalChanges = files.reduce((sum, item) => sum + (item.changes || 0), 0);
+  
   const domains = new Set();
   const importantAreas = new Set();
 
   for (const name of filenames) {
     const shortcutDomain = shortcutDomainForPath(name);
-    if (shortcutDomain) {
-      domains.add(shortcutDomain);
-    }
+    if (shortcutDomain) domains.add(shortcutDomain);
+    
     const skillDomain = skillDomainForPath(name);
-    if (skillDomain) {
-      domains.add(skillDomain);
-    }
+    if (skillDomain) domains.add(skillDomain);
     
     const area = getImportantArea(name);
-    if (area) {
-      importantAreas.add(area);
-    }
+    if (area) importantAreas.add(area);
   }
 
   const coreAreas = collectCoreAreas(filenames);
   const newShortcutDomain = await detectNewShortcutDomain(files);
-  const lowRiskOnly = filenames.length > 0 && filenames.every((name) => isLowRiskPath(name));
+  
+  const lowRiskOnly = filenames.length > 0 && filenames.every(isLowRiskPath);
   const singleDomain = domains.size <= 1;
   const multiDomain = domains.size >= 2;
   const headDomains = [...domains].filter((domain) => HEAD_BUSINESS_DOMAINS.has(domain));
@@ -421,79 +404,14 @@ async function classifyPr(payload, files) {
   const sensitiveKeywords = collectSensitiveKeywords(filenames);
   const sensitive = coreSignals.length > 0 || sensitiveKeywords.length > 0;
 
-  const reasons = [];
-  let label;
+  const context = {
+    prType, effectiveChanges, lowRiskOnly,
+    domains, headDomains, coreAreas, coreSignals,
+    sensitiveKeywords, sensitive, newShortcutDomain,
+    singleDomain, multiDomain, filenames
+  };
 
-  if (lowRiskOnly && (LOW_RISK_TYPES.has(prType) || effectiveChanges === 0)) {
-    reasons.push("Only low-risk docs, CI, test, or chore paths were changed, with no effective business code or Skill changes");
-    label = "size/S";
-  } else {
-    // XL is reserved for architecture-level or global-impact changes.
-    const architectureLevel =
-      effectiveChanges > 1200
-      || (prType === "refactor" && sensitive && effectiveChanges >= 300)
-      || (coreAreas.size >= 2 && (multiDomain || effectiveChanges >= 300))
-      || (headDomains.length >= 2 && sensitive);
-
-    if (architectureLevel) {
-      if (effectiveChanges > 1200) {
-        reasons.push("Effective business code or Skill changes are far beyond the L threshold");
-      }
-      if (prType === "refactor" && sensitive && effectiveChanges >= 300) {
-        reasons.push("Refactor PR touches core or sensitive paths");
-      }
-      if (coreAreas.size >= 2) {
-        reasons.push("Touches multiple core areas at the same time");
-      }
-      if (headDomains.length >= 2) {
-        reasons.push("Impacts multiple major business domains");
-      }
-      for (const signal of coreSignals) {
-        reasons.push(`Core area hit: ${signal}`);
-      }
-      for (const keyword of sensitiveKeywords) {
-        reasons.push(`Sensitive keyword hit: ${keyword}`);
-      }
-      label = "size/XL";
-    } else if (
-      prType === "refactor"
-      || effectiveChanges >= 300
-      || Boolean(newShortcutDomain)
-      || multiDomain
-      || sensitive
-    ) {
-      if (prType === "refactor") {
-        reasons.push("PR type is refactor");
-      }
-      if (effectiveChanges >= 300) {
-        reasons.push("Effective business code or Skill changes exceed 300 lines");
-      }
-      if (newShortcutDomain) {
-        reasons.push(`Introduces a new business domain directory: shortcuts/${newShortcutDomain}/`);
-      }
-      if (multiDomain) {
-        reasons.push("Touches multiple business domains");
-      }
-      for (const signal of coreSignals) {
-        reasons.push(`Core area hit: ${signal}`);
-      }
-      for (const keyword of sensitiveKeywords) {
-        reasons.push(`Sensitive keyword hit: ${keyword}`);
-      }
-      label = "size/L";
-    } else {
-      if (filenames.some((name) => isBusinessSkillPath(name)) || effectiveChanges > 0) {
-        reasons.push("Regular feat, fix, or Skill change within a single business domain");
-      }
-      if (singleDomain && domains.size > 0) {
-        reasons.push(`Impact is limited to a single business domain: ${[...domains].sort().join(", ")}`);
-      }
-      if (effectiveChanges < 300) {
-        reasons.push("Effective business code or Skill changes are below 300 lines");
-      }
-      label = "size/M";
-    }
-  }
+  const { label, reasons } = evaluateRules(context);
 
   return {
     label,
@@ -513,11 +431,13 @@ async function classifyPr(payload, files) {
   };
 }
 
+// ============================================================================
+// Output & Formatting
+// ============================================================================
+
 async function writeStepSummary(prNumber, classification) {
   const summaryPath = (process.env.GITHUB_STEP_SUMMARY || "").trim();
-  if (!summaryPath) {
-    return;
-  }
+  if (!summaryPath) return;
 
   const standard = CLASS_STANDARDS[classification.label];
   const domains = classification.domains.join(", ") || "-";
@@ -590,46 +510,118 @@ function printDryRunResult(result, options) {
   const reasonParts = result.reasons.length > 0
     ? result.reasons
     : ["No higher-severity rule matched, so the PR defaults to medium classification"];
+  
   console.log(
     `${result.label} | #${result.prNumber} | type:${result.prType} | eff:${result.effectiveChanges} | `
       + `sig:${signalParts.join(";") || "-"} | reason:${reasonParts.join("; ")}`,
   );
 }
 
+function printHelp() {
+  const lines = [
+    "Usage:",
+    "  node scripts/pr-labels/index.js",
+    "  node scripts/pr-labels/index.js --dry-run --pr-url <github-pr-url> [--token <token>] [--json]",
+    "  node scripts/pr-labels/index.js --dry-run --repo <owner/name> --pr-number <number> [--token <token>] [--json]",
+    "",
+    "Modes:",
+    "  default    Read the GitHub Actions event payload and apply labels",
+    "  --dry-run  Fetch the PR, compute the managed label, and print the result without writing labels",
+    "",
+    "Options:",
+    "  --pr-url <url>       GitHub pull request URL, for example https://github.com/larksuite/cli/pull/123",
+    "  --repo <owner/name>  Repository name, used with --pr-number",
+    "  --pr-number <n>      Pull request number, used with --repo",
+    "  --token <token>      GitHub token override; falls back to GITHUB_TOKEN",
+    "  --json               Print dry-run output as JSON instead of the default one-line summary",
+    "  --help               Show this message",
+  ];
+  console.log(lines.join("\n"));
+}
+
+function parseArgs(argv) {
+  const options = {
+    dryRun: false,
+    json: false,
+    help: false,
+    prUrl: "",
+    repo: "",
+    prNumber: "",
+    token: "",
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--dry-run") options.dryRun = true;
+    else if (arg === "--json") options.json = true;
+    else if (arg === "--help" || arg === "-h") options.help = true;
+    else if (arg === "--pr-url") options.prUrl = argv[++i] || "";
+    else if (arg === "--repo") options.repo = argv[++i] || "";
+    else if (arg === "--pr-number") options.prNumber = argv[++i] || "";
+    else if (arg === "--token") options.token = argv[++i] || "";
+    else throw new Error(`unknown argument: ${arg}`);
+  }
+
+  return options;
+}
+
+function parsePrUrl(prUrl) {
+  let parsed;
+  try {
+    parsed = new URL(prUrl);
+  } catch {
+    throw new Error(`invalid PR URL: ${prUrl}`);
+  }
+
+  const match = parsed.pathname.match(/^\/([^/]+)\/([^/]+)\/pull\/(\d+)\/?$/);
+  if (!match) throw new Error(`unsupported PR URL format: ${prUrl}`);
+
+  return { repo: `${match[1]}/${match[2]}`, prNumber: Number(match[3]) };
+}
+
+async function loadEventPayload(filePath) {
+  return JSON.parse(await fs.readFile(filePath, "utf8"));
+}
+
 async function resolveContext(options) {
+  const token = options.token;
+
   if (options.prUrl) {
     const { repo, prNumber } = parsePrUrl(options.prUrl);
+    const client = new GitHubClient(token, repo, prNumber);
     const payload = {
       repository: { full_name: repo },
-      pull_request: await getPullRequest(repo, prNumber, options.token),
+      pull_request: await client.getPullRequest(),
     };
-    return { repo, prNumber, payload };
+    return { repo, prNumber, payload, client };
   }
 
   if (options.repo || options.prNumber) {
-    if (!options.repo || !options.prNumber) {
-      throw new Error("--repo and --pr-number must be provided together");
-    }
+    if (!options.repo || !options.prNumber) throw new Error("--repo and --pr-number must be provided together");
     const prNumber = Number(options.prNumber);
-    if (!Number.isInteger(prNumber) || prNumber <= 0) {
-      throw new Error(`invalid PR number: ${options.prNumber}`);
-    }
+    if (!Number.isInteger(prNumber) || prNumber <= 0) throw new Error(`invalid PR number: ${options.prNumber}`);
+    
+    const client = new GitHubClient(token, options.repo, prNumber);
     const payload = {
       repository: { full_name: options.repo },
-      pull_request: await getPullRequest(options.repo, prNumber, options.token),
+      pull_request: await client.getPullRequest(),
     };
-    return { repo: options.repo, prNumber, payload };
+    return { repo: options.repo, prNumber, payload, client };
   }
 
   const eventPath = envOrFail("GITHUB_EVENT_PATH");
   const payload = await loadEventPayload(eventPath);
-  return {
-    repo: payload.repository.full_name,
-    prNumber: payload.pull_request.number,
-    payload,
-  };
+  const repo = payload.repository.full_name;
+  const prNumber = payload.pull_request.number;
+  const client = new GitHubClient(token, repo, prNumber);
+
+  return { repo, prNumber, payload, client };
 }
 
+// ============================================================================
+// Main Execution
+// ============================================================================
+
 async function main() {
   const options = parseArgs(process.argv.slice(2));
   if (options.help) {
@@ -638,13 +630,13 @@ async function main() {
   }
 
   options.token = options.token || envValue("GITHUB_TOKEN");
-  const { repo, prNumber, payload } = await resolveContext(options);
+  const { repo, prNumber, payload, client } = await resolveContext(options);
 
   if (!options.dryRun && !options.token) {
     throw new Error("missing required GitHub token; set GITHUB_TOKEN or pass --token");
   }
 
-  const files = await listPrFiles(repo, prNumber, options.token);
+  const files = await client.listPrFiles();
   const classification = await classifyPr(payload, files);
 
   if (options.dryRun) {
@@ -657,8 +649,7 @@ async function main() {
     desired.add(`area/${area}`);
   }
 
-  const current = await listIssueLabels(repo, prNumber, options.token);
-
+  const current = await client.listIssueLabels();
   const managedCurrent = [...current].filter((label) => MANAGED_LABELS.has(label) || label.startsWith("area/"));
   const toAdd = [...desired].filter((label) => !current.has(label)).sort();
   const toRemove = managedCurrent.filter((label) => !desired.has(label)).sort();
@@ -666,22 +657,19 @@ async function main() {
   for (const area of classification.importantAreas) {
     const labelName = `area/${area}`;
     if (!LABEL_DEFINITIONS[labelName]) {
-      LABEL_DEFINITIONS[labelName] = {
-        color: "1d76db",
-        description: `PR touches the ${area} area`,
-      };
+      LABEL_DEFINITIONS[labelName] = { color: "1d76db", description: `PR touches the ${area} area` };
     }
   }
 
   // Keep label metadata consistent even when labels already exist in the repository.
   for (const label of Object.keys(LABEL_DEFINITIONS)) {
-    await syncLabelDefinition(repo, options.token, label);
+    await client.syncLabelDefinition(label);
   }
 
-  await addLabels(repo, prNumber, options.token, toAdd);
+  await client.addLabels(toAdd);
 
   for (const label of toRemove) {
-    await removeLabel(repo, prNumber, options.token, label);
+    await client.removeLabel(label);
   }
 
   await writeStepSummary(prNumber, classification);

From c9de60f7f0e13a34afb075e5a8bbcdbe1347691a Mon Sep 17 00:00:00 2001
From: williamfzc <178894043@qq.com>
Date: Tue, 31 Mar 2026 15:37:18 +0800
Subject: [PATCH 16/19] ci: fix setup-node version in pr-labels workflow

---
 .github/workflows/pr-labels.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/pr-labels.yml b/.github/workflows/pr-labels.yml
index 41827524e5..7f0338dad0 100644
--- a/.github/workflows/pr-labels.yml
+++ b/.github/workflows/pr-labels.yml
@@ -19,9 +19,9 @@ jobs:
     if: ${{ github.event.pull_request.state == 'open' }}
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/checkout@v4
 
-      - uses: actions/setup-node@49933ea5288caeca8642e03cb748f7d9d40d8f46 # v4
+      - uses: actions/setup-node@v4
         with:
           node-version: '20'
 

From d8c7a07012e83b6c8e6251f30f7c383f7e9644ea Mon Sep 17 00:00:00 2001
From: williamfzc <178894043@qq.com>
Date: Tue, 31 Mar 2026 16:19:53 +0800
Subject: [PATCH 17/19] docs: add dummy comment to test CI pipeline

---
 README.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/README.md b/README.md
index aacf745c0d..b27cdf6e2c 100644
--- a/README.md
+++ b/README.md
@@ -285,3 +285,4 @@ When running, it calls Lark/Feishu Open Platform APIs. To use these APIs, you mu
 - [Feishu Open Platform App Service Provider Security Management Specifications](https://open.feishu.cn/document/uAjLw4CM/uMzNwEjLzcDMx4yM3ATM/management-practice/app-service-provider-security-management-specifications)
 - [Lark User Terms of Service](https://www.larksuite.com/user-terms-of-service)
 - [Lark Privacy Policy](https://www.larksuite.com/privacy-policy)
+\n<!-- dummy change to test pr labels trigger -->

From 0374f08df4e468648e1b55f03feb4c1acb7d5552 Mon Sep 17 00:00:00 2001
From: williamfzc <178894043@qq.com>
Date: Tue, 31 Mar 2026 17:49:15 +0800
Subject: [PATCH 18/19] docs: add dummy change in base shortcut to trigger CI

---
 shortcuts/base/shortcuts.go | 1 +
 1 file changed, 1 insertion(+)

diff --git a/shortcuts/base/shortcuts.go b/shortcuts/base/shortcuts.go
index fea4ebd7e4..25b68dd26e 100644
--- a/shortcuts/base/shortcuts.go
+++ b/shortcuts/base/shortcuts.go
@@ -78,3 +78,4 @@ func Shortcuts() []common.Shortcut {
 		BaseDashboardBlockDelete,
 	}
 }
+// trigger CI

From b409aa4cff94c398ddd5e291f9c0c0eceeacb8a4 Mon Sep 17 00:00:00 2001
From: williamfzc <178894043@qq.com>
Date: Tue, 31 Mar 2026 18:03:27 +0800
Subject: [PATCH 19/19] chore: test Skill Format Check action

---
 skills/lark-base/SKILL.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/skills/lark-base/SKILL.md b/skills/lark-base/SKILL.md
index fc71084288..d13c88f956 100644
--- a/skills/lark-base/SKILL.md
+++ b/skills/lark-base/SKILL.md
@@ -307,3 +307,4 @@ https://{domain}/base/{base-token}?table={table-id}&view={view-id}
 | [`workflow commands`](references/lark-base-workflow.md) | `+workflow-list / +workflow-get / +workflow-create / +workflow-update / +workflow-enable / +workflow-disable` |
 | [`dashboard commands`](references/lark-base-dashboard.md) | `+dashboard-list / +dashboard-get / +dashboard-create / +dashboard-update / +dashboard-delete` |
 | [`dashboard block commands`](references/lark-base-dashboard-block.md) | `+dashboard-block-list / +dashboard-block-get / +dashboard-block-create / +dashboard-block-update / +dashboard-block-delete` |
+