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/34] 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 000000000..2586c0c33
--- /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 000000000..968363f9e
--- /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/34] 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 2586c0c33..3d1596ed7 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/34] 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 968363f9e..37420200c 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/34] 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 37420200c..7cd13398a 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 000000000..cfe231035
--- /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/34] 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 cfe231035..98373b399 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/34] 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 7cd13398a..6ead27ebb 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/34] 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 3d1596ed7..bae29b032 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 000000000..404d4a6c6
--- /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/34] 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 bae29b032..41827524e 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 404d4a6c6..d667c654e 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 6ead27ebb..f73b15fe5 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/34] 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 000000000..97e2a161d
--- /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 000000000..f6a61c7bf
--- /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 c21bca742..b9de0b1a4 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 0bd7777e3..07000387d 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/34] 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 98373b399..fe525154c 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/34] 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 97e2a161d..7c8b8fc5f 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 000000000..23fe9fedd
--- /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 f6a61c7bf..540d75d1e 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/34] 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 23fe9fedd..dffb955dd 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 540d75d1e..d59a45f66 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 000000000..6749c4551
--- /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 000000000..5a7afa3e9
--- /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 000000000..189d62533
--- /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 000000000..d59074299
--- /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 000000000..0f7b51836
--- /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 000000000..ca3f481c2
--- /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 000000000..8c2e7b40f
--- /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/34] 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 d59a45f66..534b8a926 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 d59074299..465a05da2 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 b9de0b1a4..c21bca742 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 07000387d..0bd7777e3 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/34] 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 dffb955dd..f67f303c5 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 534b8a926..1dd5a38d4 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/34] 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 f73b15fe5..e160b793b
--- 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/34] 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 41827524e..7f0338dad 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 b9f28031b917acc88bdd48a8aac1ac52385b8ce7 Mon Sep 17 00:00:00 2001
From: williamfzc <178894043@qq.com>
Date: Tue, 31 Mar 2026 17:01:42 +0800
Subject: [PATCH 17/34] tmp

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

diff --git a/.github/workflows/pr-labels.yml b/.github/workflows/pr-labels.yml
index 7f0338dad..4f393f63f 100644
--- a/.github/workflows/pr-labels.yml
+++ b/.github/workflows/pr-labels.yml
@@ -10,7 +10,7 @@ on:
 
 permissions:
   contents: read
-  pull-requests: read
+  pull-requests: write
   # PR labels are managed through the issues API.
   issues: write
 

From 5e7f0d3b163452f427469c8a9c81cde7ee0ad3c7 Mon Sep 17 00:00:00 2001
From: williamfzc <178894043@qq.com>
Date: Tue, 31 Mar 2026 17:34:12 +0800
Subject: [PATCH 18/34] refactor(ci): replace generic area labels with
 business-specific ones

- Add PATH_TO_AREA_MAP to map shortcuts/skills paths to business areas (im, vc, ccm, base, mail, calendar, task, contact)

- Replace importantAreas with businessAreas throughout the codebase

- Remove area/shortcuts, area/skills, area/cmd generic labels

- Now generates specific labels like area/im, area/vc, area/ccm, etc.

- Update samples.json expected_areas to match new behavior

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 scripts/pr-labels/index.js     | 57 +++++++++++++++++++++++++---------
 scripts/pr-labels/samples.json | 14 ++++-----
 2 files changed, 49 insertions(+), 22 deletions(-)

diff --git a/scripts/pr-labels/index.js b/scripts/pr-labels/index.js
index e160b793b..10e12b198 100755
--- a/scripts/pr-labels/index.js
+++ b/scripts/pr-labels/index.js
@@ -35,6 +35,30 @@ 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"]);
 
+// CODEOWNERS-based path to area label mapping
+// Maps shortcuts and skills paths to business area labels
+const PATH_TO_AREA_MAP = {
+  // shortcuts
+  "shortcuts/im/": "im",
+  "shortcuts/vc/": "vc",
+  "shortcuts/calendar/": "calendar",
+  "shortcuts/doc/": "ccm",
+  "shortcuts/sheets/": "ccm",
+  "shortcuts/drive/": "ccm",
+  "shortcuts/base/": "base",
+  "shortcuts/mail/": "mail",
+  "shortcuts/task/": "task",
+  "shortcuts/contact/": "contact",
+  // skills
+  "skills/lark-im/": "im",
+  "skills/lark-vc/": "vc",
+  "skills/lark-doc/": "ccm",
+  "skills/lark-base/": "base",
+  "skills/lark-mail/": "mail",
+  "skills/lark-calendar/": "calendar",
+  "skills/lark-contact/": "contact",
+};
+
 const SENSITIVE_PATTERN = /(^|\/)(auth|permission|permissions|security)(\/|_|\.|$)/;
 
 const CLASS_STANDARDS = {
@@ -253,11 +277,14 @@ function skillDomainForPath(filePath) {
     : "";
 }
 
-function getImportantArea(filePath) {
+// Get business area label based on CODEOWNERS path mapping
+function getBusinessArea(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";
+  for (const [prefix, area] of Object.entries(PATH_TO_AREA_MAP)) {
+    if (normalized.startsWith(prefix)) {
+      return area;
+    }
+  }
   return "";
 }
 
@@ -380,17 +407,17 @@ async function classifyPr(payload, files) {
   const totalChanges = files.reduce((sum, item) => sum + (item.changes || 0), 0);
   
   const domains = new Set();
-  const importantAreas = new Set();
+  const businessAreas = 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 area = getImportantArea(name);
-    if (area) importantAreas.add(area);
+
+    const businessArea = getBusinessArea(name);
+    if (businessArea) businessAreas.add(businessArea);
   }
 
   const coreAreas = collectCoreAreas(filenames);
@@ -420,7 +447,7 @@ async function classifyPr(payload, files) {
     totalChanges,
     effectiveChanges,
     domains: [...domains].sort(),
-    importantAreas: [...importantAreas].sort(),
+    businessAreas: [...businessAreas].sort(),
     coreAreas: [...coreAreas].sort(),
     coreSignals,
     sensitiveKeywords,
@@ -441,7 +468,7 @@ async function writeStepSummary(prNumber, classification) {
 
   const standard = CLASS_STANDARDS[classification.label];
   const domains = classification.domains.join(", ") || "-";
-  const areas = classification.importantAreas.join(", ") || "-";
+  const areas = classification.businessAreas.join(", ") || "-";
   const coreAreas = classification.coreAreas.join(", ") || "-";
   const reasons = classification.reasons.length > 0
     ? classification.reasons
@@ -485,7 +512,7 @@ function formatDryRunResult(repo, prNumber, classification) {
     effectiveChanges: classification.effectiveChanges,
     lowRiskOnly: classification.lowRiskOnly,
     domains: classification.domains,
-    importantAreas: classification.importantAreas,
+    businessAreas: classification.businessAreas,
     coreAreas: classification.coreAreas,
     coreSignals: classification.coreSignals,
     sensitiveKeywords: classification.sensitiveKeywords,
@@ -505,7 +532,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(",")}`] : []),
+    ...(result.businessAreas.length > 0 ? [`areas:${result.businessAreas.join(",")}`] : []),
   ];
   const reasonParts = result.reasons.length > 0
     ? result.reasons
@@ -645,7 +672,7 @@ async function main() {
   }
 
   const desired = new Set([classification.label]);
-  for (const area of classification.importantAreas) {
+  for (const area of classification.businessAreas) {
     desired.add(`area/${area}`);
   }
 
@@ -654,7 +681,7 @@ async function main() {
   const toAdd = [...desired].filter((label) => !current.has(label)).sort();
   const toRemove = managedCurrent.filter((label) => !desired.has(label)).sort();
 
-  for (const area of classification.importantAreas) {
+  for (const area of classification.businessAreas) {
     const labelName = `area/${area}`;
     if (!LABEL_DEFINITIONS[labelName]) {
       LABEL_DEFINITIONS[labelName] = { color: "1d76db", description: `PR touches the ${area} area` };
diff --git a/scripts/pr-labels/samples.json b/scripts/pr-labels/samples.json
index fe525154c..dac736ed3 100644
--- a/scripts/pr-labels/samples.json
+++ b/scripts/pr-labels/samples.json
@@ -51,7 +51,7 @@
     "status": "merged",
     "merged_at": "2026-03-30T11:40:18Z",
     "expected_label": "size/M",
-    "expected_areas": ["area/shortcuts"],
+    "expected_areas": ["area/base"],
     "review_note": "Small fix sample. Verify the lower edge of the M bucket within a single domain."
   },
   {
@@ -62,7 +62,7 @@
     "status": "merged",
     "merged_at": "2026-03-30T10:19:11Z",
     "expected_label": "size/M",
-    "expected_areas": ["area/shortcuts", "area/skills"],
+    "expected_areas": ["area/mail"],
     "review_note": "Security-like wording in the title but stays in one business domain (mail)."
   },
   {
@@ -84,7 +84,7 @@
     "status": "merged",
     "merged_at": "2026-03-30T15:00:41Z",
     "expected_label": "size/M",
-    "expected_areas": ["area/shortcuts", "area/skills"],
+    "expected_areas": ["area/im"],
     "review_note": "Single-domain feature with larger diff but effective changes stay in M."
   },
   {
@@ -95,7 +95,7 @@
     "status": "merged",
     "merged_at": "2026-03-30T09:19:24Z",
     "expected_label": "size/L",
-    "expected_areas": ["area/cmd"],
+    "expected_areas": [],
     "review_note": "Touches core area (cmd), bumping the size to L."
   },
   {
@@ -106,7 +106,7 @@
     "status": "merged",
     "merged_at": "2026-03-28T16:00:52Z",
     "expected_label": "size/L",
-    "expected_areas": ["area/shortcuts", "area/skills"],
+    "expected_areas": ["area/base", "area/ccm"],
     "review_note": "Docs change but touches multiple business domains, making it L."
   },
   {
@@ -117,7 +117,7 @@
     "status": "closed",
     "merged_at": null,
     "expected_label": "size/L",
-    "expected_areas": ["area/shortcuts"],
+    "expected_areas": ["area/ccm"],
     "review_note": "Closed PR but useful as an L sample for effective lines exceeding 300."
   },
   {
@@ -128,7 +128,7 @@
     "status": "closed",
     "merged_at": null,
     "expected_label": "size/L",
-    "expected_areas": ["area/cmd", "area/skills"],
+    "expected_areas": [],
     "review_note": "Closed PR touching core area (cmd)."
   }
 ]
\ No newline at end of file

From 5c5942c2402f14f0bb6d0fb88c1f5da110bc589c Mon Sep 17 00:00:00 2001
From: williamfzc <178894043@qq.com>
Date: Tue, 31 Mar 2026 19:42:51 +0800
Subject: [PATCH 19/34] fix(ci): address PR review feedback for label scripts
 and workflows

- Add `edited` event to PR labels workflow to trigger on title changes
- Add security warning comment in pr-labels.yml workflow
- Update pr-labels README with latest business area labels
- Exclude `skills/lark-*` paths from low risk doc classification
- Handle renamed files properly in PR path classification
- Fix YAML frontmatter extraction to handle CRLF line endings
- Use precise regex for YAML key validation instead of substring match
- Fix exit code checking logic in skill-format-check test script
- Translate Chinese comments in skill-format-check to English
---
 .github/workflows/pr-labels.yml     |  6 ++++--
 scripts/pr-labels/README.md         | 13 +++++++++----
 scripts/pr-labels/index.js          | 28 ++++++++++++++++++++--------
 scripts/skill-format-check/index.js | 19 +++++++++++--------
 scripts/skill-format-check/test.sh  |  3 ++-
 5 files changed, 46 insertions(+), 23 deletions(-)

diff --git a/.github/workflows/pr-labels.yml b/.github/workflows/pr-labels.yml
index 4f393f63f..5f38d9449 100644
--- a/.github/workflows/pr-labels.yml
+++ b/.github/workflows/pr-labels.yml
@@ -2,8 +2,12 @@ name: PR Labels
 
 on:
   pull_request_target:
+    # NOTE: This event runs with base-branch code and write permissions.
+    # Do NOT add `ref: github.event.pull_request.head.sha` to the checkout step,
+    # as that would execute untrusted PR code with elevated access.
     types:
       - opened
+      - edited
       - reopened
       - synchronize
       - ready_for_review
@@ -11,8 +15,6 @@ on:
 permissions:
   contents: read
   pull-requests: write
-  # PR labels are managed through the issues API.
-  issues: write
 
 jobs:
   sync-pr-labels:
diff --git a/scripts/pr-labels/README.md b/scripts/pr-labels/README.md
index d667c654e..963d208f4 100644
--- a/scripts/pr-labels/README.md
+++ b/scripts/pr-labels/README.md
@@ -17,10 +17,15 @@ The script evaluates the "effective" lines of code changed (ignoring tests, docs
 - **`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`
+The script also identifies which business areas a PR touches to give reviewers an immediate sense of the impact scope. Currently tracked areas include:
+- `area/im`
+- `area/vc`
+- `area/ccm`
+- `area/base`
+- `area/mail`
+- `area/calendar`
+- `area/task`
+- `area/contact`
 
 Minor modules like docs and tests are omitted to keep PR tags clean and focused on structural changes.
 
diff --git a/scripts/pr-labels/index.js b/scripts/pr-labels/index.js
index 10e12b198..a10e4667f 100755
--- a/scripts/pr-labels/index.js
+++ b/scripts/pr-labels/index.js
@@ -253,6 +253,7 @@ function isLowRiskPath(filePath) {
   const normalized = normalizePath(filePath);
   const basename = path.posix.basename(normalized);
 
+  if (normalized.startsWith("skills/lark-")) return false;
   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;
@@ -398,6 +399,13 @@ async function classifyPr(payload, files) {
   const title = pr.title || "";
   const prType = parsePrType(title);
   const filenames = files.map((item) => item.filename || "");
+  const impactedPaths = files.flatMap((item) => {
+    const paths = [item.filename || ""];
+    if (item.status === "renamed" && item.previous_filename) {
+      paths.push(item.previous_filename);
+    }
+    return paths.filter(Boolean);
+  });
   
   // Filter out docs, tests, and other low-risk paths so the size label tracks business impact.
   const effectiveChanges = files.reduce(
@@ -409,33 +417,37 @@ async function classifyPr(payload, files) {
   const domains = new Set();
   const businessAreas = new Set();
 
-  for (const name of filenames) {
+  for (const name of impactedPaths) {
+    const businessArea = getBusinessArea(name);
+    if (businessArea) {
+      businessAreas.add(businessArea);
+      domains.add(businessArea);
+      continue;
+    }
+
     const shortcutDomain = shortcutDomainForPath(name);
     if (shortcutDomain) domains.add(shortcutDomain);
 
     const skillDomain = skillDomainForPath(name);
     if (skillDomain) domains.add(skillDomain);
-
-    const businessArea = getBusinessArea(name);
-    if (businessArea) businessAreas.add(businessArea);
   }
 
-  const coreAreas = collectCoreAreas(filenames);
+  const coreAreas = collectCoreAreas(impactedPaths);
   const newShortcutDomain = await detectNewShortcutDomain(files);
   
-  const lowRiskOnly = filenames.length > 0 && filenames.every(isLowRiskPath);
+  const lowRiskOnly = impactedPaths.length > 0 && impactedPaths.every(isLowRiskPath);
   const singleDomain = domains.size <= 1;
   const multiDomain = domains.size >= 2;
   const headDomains = [...domains].filter((domain) => HEAD_BUSINESS_DOMAINS.has(domain));
   const coreSignals = [...coreAreas].sort();
-  const sensitiveKeywords = collectSensitiveKeywords(filenames);
+  const sensitiveKeywords = collectSensitiveKeywords(impactedPaths);
   const sensitive = coreSignals.length > 0 || sensitiveKeywords.length > 0;
 
   const context = {
     prType, effectiveChanges, lowRiskOnly,
     domains, headDomains, coreAreas, coreSignals,
     sensitiveKeywords, sensitive, newShortcutDomain,
-    singleDomain, multiDomain, filenames
+    singleDomain, multiDomain, filenames: impactedPaths
   };
 
   const { label, reasons } = evaluateRules(context);
diff --git a/scripts/skill-format-check/index.js b/scripts/skill-format-check/index.js
index 1dd5a38d4..f056045e6 100644
--- a/scripts/skill-format-check/index.js
+++ b/scripts/skill-format-check/index.js
@@ -37,27 +37,30 @@ function checkSkillFormat() {
 
     const content = fs.readFileSync(skillFile, 'utf-8');
 
-    // 检查 YAML Frontmatter
-    if (!content.startsWith('---\n') && !content.startsWith('---\r\n')) {
+    // Normalize line endings to simplify parsing
+    const normalizedContent = content.replace(/\r\n/g, '\n');
+
+    // Check YAML Frontmatter
+    if (!normalizedContent.startsWith('---\n')) {
        console.error(`❌ [${skill}] SKILL.md must start with YAML frontmatter (---)`);
        hasErrors = true;
     } else {
-        // 兼容不同的换行符
-        let endOfFrontmatter = content.indexOf('\n---', 3);
+        // Handle different newline combinations
+        let endOfFrontmatter = normalizedContent.indexOf('\n---', 4);
         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:')) {
+            const frontmatter = normalizedContent.substring(4, endOfFrontmatter);
+            if (!/^name:/m.test(frontmatter)) {
                 console.error(`❌ [${skill}] YAML frontmatter missing 'name'`);
                 hasErrors = true;
             }
-            if (!frontmatter.includes('description:')) {
+            if (!/^description:/m.test(frontmatter)) {
                 console.error(`❌ [${skill}] YAML frontmatter missing 'description'`);
                 hasErrors = true;
             }
-            if (!frontmatter.includes('metadata:')) {
+            if (!/^metadata:/m.test(frontmatter)) {
                 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/test.sh b/scripts/skill-format-check/test.sh
index 6749c4551..7e74901ff 100755
--- a/scripts/skill-format-check/test.sh
+++ b/scripts/skill-format-check/test.sh
@@ -38,8 +38,9 @@ run_negative_test() {
     
     # 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
+    local exit_code=$?
     
-    if [ $? -eq 1 ]; then
+    if [ $exit_code -ne 0 ]; then
         echo "✅ Passed! (Correctly rejected $test_name)"
         rm -rf "$DIR/tests/temp_test_dir"
         return 0

From d272d4d3c3fd8a7e754d74e47847fd416b15affa Mon Sep 17 00:00:00 2001
From: williamfzc <178894043@qq.com>
Date: Tue, 31 Mar 2026 20:01:32 +0800
Subject: [PATCH 20/34] fix(skill-format-check): address CodeRabbit review
 feedback

- Fix frontmatter closing delimiter detection to strictly match '---' using regex, preventing invalid closing tags like '----' from passing.
- Improve test fixture reliability by failing tests immediately if fixture preparation fails, avoiding false positives.
---
 scripts/skill-format-check/index.js |  9 ++++----
 scripts/skill-format-check/test.sh  | 33 ++++++++++++++++++++---------
 2 files changed, 27 insertions(+), 15 deletions(-)

diff --git a/scripts/skill-format-check/index.js b/scripts/skill-format-check/index.js
index f056045e6..e6289df08 100644
--- a/scripts/skill-format-check/index.js
+++ b/scripts/skill-format-check/index.js
@@ -45,13 +45,12 @@ function checkSkillFormat() {
        console.error(`❌ [${skill}] SKILL.md must start with YAML frontmatter (---)`);
        hasErrors = true;
     } else {
-        // Handle different newline combinations
-        let endOfFrontmatter = normalizedContent.indexOf('\n---', 4);
-        if (endOfFrontmatter === -1) {
-             console.error(`❌ [${skill}] SKILL.md has unclosed YAML frontmatter`);
+        const frontmatterMatch = normalizedContent.match(/^---\n([\s\S]*?)\n---(?:\n|$)/);
+        if (!frontmatterMatch) {
+             console.error(`❌ [${skill}] SKILL.md has unclosed or invalid YAML frontmatter`);
              hasErrors = true;
         } else {
-            const frontmatter = normalizedContent.substring(4, endOfFrontmatter);
+            const frontmatter = frontmatterMatch[1];
             if (!/^name:/m.test(frontmatter)) {
                 console.error(`❌ [${skill}] YAML frontmatter missing 'name'`);
                 hasErrors = true;
diff --git a/scripts/skill-format-check/test.sh b/scripts/skill-format-check/test.sh
index 7e74901ff..efa2e4a89 100755
--- a/scripts/skill-format-check/test.sh
+++ b/scripts/skill-format-check/test.sh
@@ -3,27 +3,41 @@
 # Get the directory of this script
 DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
 INDEX_JS="$DIR/index.js"
+TEMP_DIR="$DIR/tests/temp_test_dir"
 
 echo "=== Running tests for skill-format-check ==="
 echo "Index script: $INDEX_JS"
 
+prepare_fixture() {
+    local test_name=$1
+    rm -rf "$TEMP_DIR"
+    mkdir -p "$TEMP_DIR"
+    if [ ! -d "$DIR/tests/$test_name" ]; then
+        echo "❌ Missing fixture directory: $DIR/tests/$test_name"
+        exit 1
+    fi
+    cp -r "$DIR/tests/$test_name" "$TEMP_DIR/" || {
+        echo "❌ Failed to copy fixture: $test_name"
+        exit 1
+    }
+}
+
 # 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/"
+    prepare_fixture "$test_name"
     
-    node "$INDEX_JS" "$DIR/tests/temp_test_dir"
+    node "$INDEX_JS" "$TEMP_DIR"
     
     if [ $? -eq 0 ]; then
         echo "✅ Passed! (Correctly validated $test_name)"
-        rm -rf "$DIR/tests/temp_test_dir"
+        rm -rf "$TEMP_DIR"
         return 0
     else
         echo "❌ Failed! Expected $test_name to pass but it failed."
-        rm -rf "$DIR/tests/temp_test_dir"
+        rm -rf "$TEMP_DIR"
         exit 1
     fi
 }
@@ -33,20 +47,19 @@ 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/"
+    prepare_fixture "$test_name"
     
     # 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
+    node "$INDEX_JS" "$TEMP_DIR" > /dev/null 2>&1
     local exit_code=$?
     
     if [ $exit_code -ne 0 ]; then
         echo "✅ Passed! (Correctly rejected $test_name)"
-        rm -rf "$DIR/tests/temp_test_dir"
+        rm -rf "$TEMP_DIR"
         return 0
     else
         echo "❌ Failed! Expected $test_name to fail but it passed."
-        rm -rf "$DIR/tests/temp_test_dir"
+        rm -rf "$TEMP_DIR"
         exit 1
     fi
 }

From 35d8aea500d4010994f5b671cdd7e3bcd758d9dc Mon Sep 17 00:00:00 2001
From: williamfzc <178894043@qq.com>
Date: Tue, 31 Mar 2026 20:21:37 +0800
Subject: [PATCH 21/34] fix: address review comments from PR 148

- ci: warn when PR label sync fails in job summary
- test(skill-format-check): capture validator output for negative tests
- fix(skill-format-check): catch errors when reading SKILL.md to avoid hard crashes
---
 .github/workflows/pr-labels.yml     | 7 +++++++
 scripts/skill-format-check/index.js | 9 ++++++++-
 scripts/skill-format-check/test.sh  | 9 +++++++--
 3 files changed, 22 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/pr-labels.yml b/.github/workflows/pr-labels.yml
index 5f38d9449..c5234287a 100644
--- a/.github/workflows/pr-labels.yml
+++ b/.github/workflows/pr-labels.yml
@@ -28,8 +28,15 @@ jobs:
           node-version: '20'
 
       - name: Sync managed PR labels
+        id: sync_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/pr-labels/index.js
+
+      - name: Warn when label sync fails
+        if: ${{ always() && steps.sync_pr_labels.outcome == 'failure' }}
+        run: |
+          echo "::warning::PR label sync failed; labels may be stale."
+          echo "⚠️ PR label sync failed; labels may be stale." >> "$GITHUB_STEP_SUMMARY"
diff --git a/scripts/skill-format-check/index.js b/scripts/skill-format-check/index.js
index e6289df08..f354da143 100644
--- a/scripts/skill-format-check/index.js
+++ b/scripts/skill-format-check/index.js
@@ -35,7 +35,14 @@ function checkSkillFormat() {
       return;
     }
 
-    const content = fs.readFileSync(skillFile, 'utf-8');
+    let content;
+    try {
+      content = fs.readFileSync(skillFile, 'utf-8');
+    } catch (err) {
+      console.error(`❌ [${skill}] Failed to read SKILL.md: ${err.message}`);
+      hasErrors = true;
+      return;
+    }
 
     // Normalize line endings to simplify parsing
     const normalizedContent = content.replace(/\r\n/g, '\n');
diff --git a/scripts/skill-format-check/test.sh b/scripts/skill-format-check/test.sh
index efa2e4a89..1a5faf82c 100755
--- a/scripts/skill-format-check/test.sh
+++ b/scripts/skill-format-check/test.sh
@@ -49,8 +49,9 @@ run_negative_test() {
     
     prepare_fixture "$test_name"
     
-    # Run the script and suppress error output since we expect it to fail
-    node "$INDEX_JS" "$TEMP_DIR" > /dev/null 2>&1
+    # Capture output for diagnostics while still treating non-zero as expected
+    local log_file="$TEMP_DIR/.validator.log"
+    node "$INDEX_JS" "$TEMP_DIR" > "$log_file" 2>&1
     local exit_code=$?
     
     if [ $exit_code -ne 0 ]; then
@@ -59,6 +60,10 @@ run_negative_test() {
         return 0
     else
         echo "❌ Failed! Expected $test_name to fail but it passed."
+        if [ -s "$log_file" ]; then
+            echo "--- Validator output ---"
+            cat "$log_file"
+        fi
         rm -rf "$TEMP_DIR"
         exit 1
     fi

From ad6a354917b5c5e39a66301e49463f3a9252ddfd Mon Sep 17 00:00:00 2001
From: williamfzc <178894043@qq.com>
Date: Tue, 31 Mar 2026 20:31:16 +0800
Subject: [PATCH 22/34] fix: add error handling for directory enumeration in
 skill-format-check

- refactor: use `fs.readdirSync` with `{ withFileTypes: true }` to avoid extra stat calls
- fix: catch and report errors gracefully during skills directory enumeration instead of crashing
---
 scripts/skill-format-check/index.js | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/scripts/skill-format-check/index.js b/scripts/skill-format-check/index.js
index f354da143..e96b7651f 100644
--- a/scripts/skill-format-check/index.js
+++ b/scripts/skill-format-check/index.js
@@ -13,9 +13,16 @@ function checkSkillFormat() {
     process.exit(1);
   }
 
-  const skills = fs.readdirSync(SKILLS_DIR).filter(file => {
-    return fs.statSync(path.join(SKILLS_DIR, file)).isDirectory();
-  });
+  let skills;
+  try {
+    skills = fs
+      .readdirSync(SKILLS_DIR, { withFileTypes: true })
+      .filter(entry => entry.isDirectory())
+      .map(entry => entry.name);
+  } catch (err) {
+    console.error(`Failed to enumerate skills directory: ${err.message}`);
+    process.exit(1);
+  }
 
   let hasErrors = false;
 

From eb835032129479ef29897d9bb9d1af62111b5349 Mon Sep 17 00:00:00 2001
From: williamfzc <178894043@qq.com>
Date: Tue, 31 Mar 2026 20:43:52 +0800
Subject: [PATCH 23/34] docs(skill-format-check): clarify `metadata`
 requirement in README

test(pr-labels): add edge case samples for skills paths, CCM multi-paths, and renames
---
 scripts/pr-labels/samples.json       | 33 ++++++++++++++++++++++++++++
 scripts/skill-format-check/README.md |  6 ++---
 2 files changed, 36 insertions(+), 3 deletions(-)

diff --git a/scripts/pr-labels/samples.json b/scripts/pr-labels/samples.json
index dac736ed3..5c910e25e 100644
--- a/scripts/pr-labels/samples.json
+++ b/scripts/pr-labels/samples.json
@@ -130,5 +130,38 @@
     "expected_label": "size/L",
     "expected_areas": [],
     "review_note": "Closed PR touching core area (cmd)."
+  },
+  {
+    "name": "size-s-skill-docs-only",
+    "number": 140,
+    "title": "docs(skills): update lark-im skill frontmatter",
+    "pr_url": "https://github.com/larksuite/cli/pull/140",
+    "status": "merged",
+    "merged_at": "2026-03-31T09:00:00Z",
+    "expected_label": "size/S",
+    "expected_areas": ["area/im"],
+    "review_note": "A change purely to a SKILL.md file inside skills/**. This should be size/S because skill markdown files are documentation."
+  },
+  {
+    "name": "size-m-ccm-multi-path",
+    "number": 141,
+    "title": "feat(ccm): update drive and docs handlers",
+    "pr_url": "https://github.com/larksuite/cli/pull/141",
+    "status": "merged",
+    "merged_at": "2026-03-31T09:30:00Z",
+    "expected_label": "size/M",
+    "expected_areas": ["area/ccm"],
+    "review_note": "A change touching multiple CCM sub-paths (doc, drive). Should stay M as it represents a single domain (CCM), not bumping to L as multiDomain."
+  },
+  {
+    "name": "size-m-domain-rename",
+    "number": 142,
+    "title": "refactor: rename base shortcuts to bitable",
+    "pr_url": "https://github.com/larksuite/cli/pull/142",
+    "status": "merged",
+    "merged_at": "2026-03-31T10:00:00Z",
+    "expected_label": "size/M",
+    "expected_areas": ["area/base"],
+    "review_note": "A rename across paths. Since we track previous_filename to evaluate domains, this should properly capture the base domain."
   }
 ]
\ No newline at end of file
diff --git a/scripts/skill-format-check/README.md b/scripts/skill-format-check/README.md
index f67f303c5..04a00b4e8 100644
--- a/scripts/skill-format-check/README.md
+++ b/scripts/skill-format-check/README.md
@@ -4,9 +4,9 @@ This directory contains a script to validate the format of `SKILL.md` files loca
 
 ## 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`
-- `description`
+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 fields:
+- `name` (required)
+- `description` (required)
 - `metadata` (outputs a warning if missing, does not fail the build)
 
 > **Note:** The `lark-shared` skill is explicitly excluded from these format checks.

From 445cf0c81641a9dc6c66909378cb9107d4ebfeb2 Mon Sep 17 00:00:00 2001
From: williamfzc <178894043@qq.com>
Date: Tue, 31 Mar 2026 20:50:32 +0800
Subject: [PATCH 24/34] test(pr-labels): add real PR edge case samples

- use PR #134 to test skill path behaviors
- use PR #57 to test multi-path CCM resolution
- use PR #11 to test track renames cross domains
---
 scripts/pr-labels/samples.json | 44 +++++++++++++++++-----------------
 1 file changed, 22 insertions(+), 22 deletions(-)

diff --git a/scripts/pr-labels/samples.json b/scripts/pr-labels/samples.json
index 5c910e25e..8049c2173 100644
--- a/scripts/pr-labels/samples.json
+++ b/scripts/pr-labels/samples.json
@@ -132,36 +132,36 @@
     "review_note": "Closed PR touching core area (cmd)."
   },
   {
-    "name": "size-s-skill-docs-only",
-    "number": 140,
-    "title": "docs(skills): update lark-im skill frontmatter",
-    "pr_url": "https://github.com/larksuite/cli/pull/140",
-    "status": "merged",
-    "merged_at": "2026-03-31T09:00:00Z",
-    "expected_label": "size/S",
-    "expected_areas": ["area/im"],
-    "review_note": "A change purely to a SKILL.md file inside skills/**. This should be size/S because skill markdown files are documentation."
+    "name": "size-l-skill-format-check",
+    "number": 134,
+    "title": "feat(ci): add skill format check workflow to ensure SKILL.md compliance",
+    "pr_url": "https://github.com/larksuite/cli/pull/134",
+    "status": "closed",
+    "merged_at": null,
+    "expected_label": "size/L",
+    "expected_areas": [],
+    "review_note": "Includes updates to tests/bad-skill/SKILL.md inside skills-like paths, testing how skill mock files and test scripts are handled."
   },
   {
     "name": "size-m-ccm-multi-path",
-    "number": 141,
-    "title": "feat(ccm): update drive and docs handlers",
-    "pr_url": "https://github.com/larksuite/cli/pull/141",
-    "status": "merged",
-    "merged_at": "2026-03-31T09:30:00Z",
-    "expected_label": "size/M",
+    "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",
     "expected_areas": ["area/ccm"],
-    "review_note": "A change touching multiple CCM sub-paths (doc, drive). Should stay M as it represents a single domain (CCM), not bumping to L as multiDomain."
+    "review_note": "Touches docs_create_images.go and table_auto_width.go, representing multiple CCM sub-paths but resolving to a single ccm domain."
   },
   {
     "name": "size-m-domain-rename",
-    "number": 142,
-    "title": "refactor: rename base shortcuts to bitable",
-    "pr_url": "https://github.com/larksuite/cli/pull/142",
+    "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-31T10:00:00Z",
-    "expected_label": "size/M",
-    "expected_areas": ["area/base"],
+    "merged_at": "2026-03-28T16:00:52Z",
+    "expected_label": "size/L",
+    "expected_areas": ["area/base", "area/ccm"],
     "review_note": "A rename across paths. Since we track previous_filename to evaluate domains, this should properly capture the base domain."
   }
 ]
\ No newline at end of file

From b2027b4491e6750c50161d4dfe7e969745fda6c2 Mon Sep 17 00:00:00 2001
From: williamfzc <178894043@qq.com>
Date: Tue, 31 Mar 2026 22:26:07 +0800
Subject: [PATCH 25/34] refactor(ci): migrate pr labels from area to domain
 prefix

- Replaced `area/` prefix with `domain/` for PR labeling to align with existing GitHub labels
- Renamed internal constants and variables from `area` to `domain` (e.g. `PATH_TO_AREA_MAP` to `PATH_TO_DOMAIN_MAP`)
- Updated `samples.json` test data to use new `domain/` format and `expected_domains` key
- Added `scripts/pr-labels/test.js` runner script for continuous validation of labeling logic against PR samples
- Corrected expected size label for PR #134 test sample
---
 scripts/pr-labels/index.js     | 46 +++++++++++++++++-----------------
 scripts/pr-labels/samples.json | 32 +++++++++++------------
 scripts/pr-labels/test.js      | 42 +++++++++++++++++++++++++++++++
 3 files changed, 81 insertions(+), 39 deletions(-)
 create mode 100644 scripts/pr-labels/test.js

diff --git a/scripts/pr-labels/index.js b/scripts/pr-labels/index.js
index a10e4667f..39e4eaf1f 100755
--- a/scripts/pr-labels/index.js
+++ b/scripts/pr-labels/index.js
@@ -35,9 +35,9 @@ 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"]);
 
-// CODEOWNERS-based path to area label mapping
-// Maps shortcuts and skills paths to business area labels
-const PATH_TO_AREA_MAP = {
+// CODEOWNERS-based path to domain label mapping
+// Maps shortcuts and skills paths to business domain labels
+const PATH_TO_DOMAIN_MAP = {
   // shortcuts
   "shortcuts/im/": "im",
   "shortcuts/vc/": "vc",
@@ -278,12 +278,12 @@ function skillDomainForPath(filePath) {
     : "";
 }
 
-// Get business area label based on CODEOWNERS path mapping
-function getBusinessArea(filePath) {
+// Get business domain label based on CODEOWNERS path mapping
+function getBusinessDomain(filePath) {
   const normalized = normalizePath(filePath);
-  for (const [prefix, area] of Object.entries(PATH_TO_AREA_MAP)) {
+  for (const [prefix, domain] of Object.entries(PATH_TO_DOMAIN_MAP)) {
     if (normalized.startsWith(prefix)) {
-      return area;
+      return domain;
     }
   }
   return "";
@@ -415,13 +415,13 @@ async function classifyPr(payload, files) {
   const totalChanges = files.reduce((sum, item) => sum + (item.changes || 0), 0);
   
   const domains = new Set();
-  const businessAreas = new Set();
+  const businessDomains = new Set();
 
   for (const name of impactedPaths) {
-    const businessArea = getBusinessArea(name);
-    if (businessArea) {
-      businessAreas.add(businessArea);
-      domains.add(businessArea);
+    const businessDomain = getBusinessDomain(name);
+    if (businessDomain) {
+      businessDomains.add(businessDomain);
+      domains.add(businessDomain);
       continue;
     }
 
@@ -459,7 +459,7 @@ async function classifyPr(payload, files) {
     totalChanges,
     effectiveChanges,
     domains: [...domains].sort(),
-    businessAreas: [...businessAreas].sort(),
+    businessDomains: [...businessDomains].sort(),
     coreAreas: [...coreAreas].sort(),
     coreSignals,
     sensitiveKeywords,
@@ -480,7 +480,7 @@ async function writeStepSummary(prNumber, classification) {
 
   const standard = CLASS_STANDARDS[classification.label];
   const domains = classification.domains.join(", ") || "-";
-  const areas = classification.businessAreas.join(", ") || "-";
+  const bDomains = classification.businessDomains.join(", ") || "-";
   const coreAreas = classification.coreAreas.join(", ") || "-";
   const reasons = classification.reasons.length > 0
     ? classification.reasons
@@ -495,7 +495,7 @@ async function writeStepSummary(prNumber, classification) {
     `- Total Changes: \`${classification.totalChanges}\``,
     `- Effective Business/SKILL Changes: \`${classification.effectiveChanges}\``,
     `- Business Domains: \`${domains}\``,
-    `- Impacted Areas: \`${areas}\``,
+    `- Impacted Domains: \`${bDomains}\``,
     `- Core Areas: \`${coreAreas}\``,
     `- CI/CD Channel: \`${standard.channel}\``,
     `- Low Risk Only: \`${classification.lowRiskOnly}\``,
@@ -524,7 +524,7 @@ function formatDryRunResult(repo, prNumber, classification) {
     effectiveChanges: classification.effectiveChanges,
     lowRiskOnly: classification.lowRiskOnly,
     domains: classification.domains,
-    businessAreas: classification.businessAreas,
+    businessDomains: classification.businessDomains,
     coreAreas: classification.coreAreas,
     coreSignals: classification.coreSignals,
     sensitiveKeywords: classification.sensitiveKeywords,
@@ -544,7 +544,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.businessAreas.length > 0 ? [`areas:${result.businessAreas.join(",")}`] : []),
+    ...(result.businessDomains.length > 0 ? [`domains:${result.businessDomains.join(",")}`] : []),
   ];
   const reasonParts = result.reasons.length > 0
     ? result.reasons
@@ -684,19 +684,19 @@ async function main() {
   }
 
   const desired = new Set([classification.label]);
-  for (const area of classification.businessAreas) {
-    desired.add(`area/${area}`);
+  for (const domain of classification.businessDomains) {
+    desired.add(`domain/${domain}`);
   }
 
   const current = await client.listIssueLabels();
-  const managedCurrent = [...current].filter((label) => MANAGED_LABELS.has(label) || label.startsWith("area/"));
+  const managedCurrent = [...current].filter((label) => MANAGED_LABELS.has(label) || label.startsWith("domain/"));
   const toAdd = [...desired].filter((label) => !current.has(label)).sort();
   const toRemove = managedCurrent.filter((label) => !desired.has(label)).sort();
 
-  for (const area of classification.businessAreas) {
-    const labelName = `area/${area}`;
+  for (const domain of classification.businessDomains) {
+    const labelName = `domain/${domain}`;
     if (!LABEL_DEFINITIONS[labelName]) {
-      LABEL_DEFINITIONS[labelName] = { color: "1d76db", description: `PR touches the ${area} area` };
+      LABEL_DEFINITIONS[labelName] = { color: "1d76db", description: `PR touches the ${domain} domain` };
     }
   }
 
diff --git a/scripts/pr-labels/samples.json b/scripts/pr-labels/samples.json
index 8049c2173..29e51eb7c 100644
--- a/scripts/pr-labels/samples.json
+++ b/scripts/pr-labels/samples.json
@@ -7,7 +7,7 @@
     "status": "merged",
     "merged_at": "2026-03-30T12:15:45Z",
     "expected_label": "size/S",
-    "expected_areas": [],
+    "expected_domains": [],
     "review_note": "Pure docs sample. Useful to confirm low-risk paths stay in S even when total changed lines are not tiny."
   },
   {
@@ -18,7 +18,7 @@
     "status": "merged",
     "merged_at": "2026-03-28T09:33:24Z",
     "expected_label": "size/S",
-    "expected_areas": [],
+    "expected_domains": [],
     "review_note": "Docs sample, verifying docs changes remain in S."
   },
   {
@@ -29,7 +29,7 @@
     "status": "merged",
     "merged_at": "2026-03-28T16:00:15Z",
     "expected_label": "size/S",
-    "expected_areas": [],
+    "expected_domains": [],
     "review_note": "Docs sample, no effective business code changes."
   },
   {
@@ -40,7 +40,7 @@
     "status": "merged",
     "merged_at": "2026-03-28T03:43:44Z",
     "expected_label": "size/S",
-    "expected_areas": [],
+    "expected_domains": [],
     "review_note": "Docs sample, pure documentation clarification."
   },
   {
@@ -51,7 +51,7 @@
     "status": "merged",
     "merged_at": "2026-03-30T11:40:18Z",
     "expected_label": "size/M",
-    "expected_areas": ["area/base"],
+    "expected_domains": ["domain/base"],
     "review_note": "Small fix sample. Verify the lower edge of the M bucket within a single domain."
   },
   {
@@ -62,7 +62,7 @@
     "status": "merged",
     "merged_at": "2026-03-30T10:19:11Z",
     "expected_label": "size/M",
-    "expected_areas": ["area/mail"],
+    "expected_domains": ["domain/mail"],
     "review_note": "Security-like wording in the title but stays in one business domain (mail)."
   },
   {
@@ -73,7 +73,7 @@
     "status": "merged",
     "merged_at": "2026-03-30T03:09:31Z",
     "expected_label": "size/M",
-    "expected_areas": [],
+    "expected_domains": [],
     "review_note": "CI workflow change that goes beyond S threshold."
   },
   {
@@ -84,7 +84,7 @@
     "status": "merged",
     "merged_at": "2026-03-30T15:00:41Z",
     "expected_label": "size/M",
-    "expected_areas": ["area/im"],
+    "expected_domains": ["domain/im"],
     "review_note": "Single-domain feature with larger diff but effective changes stay in M."
   },
   {
@@ -95,7 +95,7 @@
     "status": "merged",
     "merged_at": "2026-03-30T09:19:24Z",
     "expected_label": "size/L",
-    "expected_areas": [],
+    "expected_domains": [],
     "review_note": "Touches core area (cmd), bumping the size to L."
   },
   {
@@ -106,7 +106,7 @@
     "status": "merged",
     "merged_at": "2026-03-28T16:00:52Z",
     "expected_label": "size/L",
-    "expected_areas": ["area/base", "area/ccm"],
+    "expected_domains": ["domain/base", "domain/ccm"],
     "review_note": "Docs change but touches multiple business domains, making it L."
   },
   {
@@ -117,7 +117,7 @@
     "status": "closed",
     "merged_at": null,
     "expected_label": "size/L",
-    "expected_areas": ["area/ccm"],
+    "expected_domains": ["domain/ccm"],
     "review_note": "Closed PR but useful as an L sample for effective lines exceeding 300."
   },
   {
@@ -128,7 +128,7 @@
     "status": "closed",
     "merged_at": null,
     "expected_label": "size/L",
-    "expected_areas": [],
+    "expected_domains": [],
     "review_note": "Closed PR touching core area (cmd)."
   },
   {
@@ -138,8 +138,8 @@
     "pr_url": "https://github.com/larksuite/cli/pull/134",
     "status": "closed",
     "merged_at": null,
-    "expected_label": "size/L",
-    "expected_areas": [],
+    "expected_label": "size/M",
+    "expected_domains": [],
     "review_note": "Includes updates to tests/bad-skill/SKILL.md inside skills-like paths, testing how skill mock files and test scripts are handled."
   },
   {
@@ -150,7 +150,7 @@
     "status": "closed",
     "merged_at": null,
     "expected_label": "size/L",
-    "expected_areas": ["area/ccm"],
+    "expected_domains": ["domain/ccm"],
     "review_note": "Touches docs_create_images.go and table_auto_width.go, representing multiple CCM sub-paths but resolving to a single ccm domain."
   },
   {
@@ -161,7 +161,7 @@
     "status": "merged",
     "merged_at": "2026-03-28T16:00:52Z",
     "expected_label": "size/L",
-    "expected_areas": ["area/base", "area/ccm"],
+    "expected_domains": ["domain/base", "domain/ccm"],
     "review_note": "A rename across paths. Since we track previous_filename to evaluate domains, this should properly capture the base domain."
   }
 ]
\ No newline at end of file
diff --git a/scripts/pr-labels/test.js b/scripts/pr-labels/test.js
new file mode 100644
index 000000000..720b752f4
--- /dev/null
+++ b/scripts/pr-labels/test.js
@@ -0,0 +1,42 @@
+const fs = require('fs');
+const { execSync } = require('child_process');
+const path = require('path');
+
+const samplesPath = path.join(__dirname, 'samples.json');
+const indexPath = path.join(__dirname, 'index.js');
+const samples = JSON.parse(fs.readFileSync(samplesPath, 'utf8'));
+
+let passed = 0;
+let failed = 0;
+
+for (const sample of samples) {
+  try {
+    const output = execSync(`node ${indexPath} --dry-run --json --pr-url ${sample.pr_url}`, { encoding: 'utf8', env: process.env });
+    const result = JSON.parse(output);
+
+    const matchLabel = result.label === sample.expected_label;
+    
+    // Sort before comparing to ignore order
+    const actualDomains = (result.businessDomains || []).sort();
+    const expectedDomains = (sample.expected_domains || []).map(d => d.replace('domain/', '')).sort();
+    
+    const matchDomains = JSON.stringify(actualDomains) === JSON.stringify(expectedDomains);
+
+    if (matchLabel && matchDomains) {
+      console.log(`✅ Passed: ${sample.name}`);
+      passed++;
+    } else {
+      console.log(`❌ Failed: ${sample.name}`);
+      console.log(`   Label expected: ${sample.expected_label}, got: ${result.label}`);
+      console.log(`   Domains expected: ${expectedDomains}, got: ${actualDomains}`);
+      failed++;
+    }
+  } catch (e) {
+    console.log(`❌ Failed: ${sample.name} (Execution error)`);
+    console.error(e.message);
+    failed++;
+  }
+}
+
+console.log(`\nTest Summary: ${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);

From 18f74ff73d485bce342e776e80798875cb0f5226 Mon Sep 17 00:00:00 2001
From: williamfzc <178894043@qq.com>
Date: Tue, 31 Mar 2026 22:41:24 +0800
Subject: [PATCH 26/34] test: use execFileSync instead of execSync in pr-labels
 test script

---
 scripts/pr-labels/test.js | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/scripts/pr-labels/test.js b/scripts/pr-labels/test.js
index 720b752f4..b24c09fe3 100644
--- a/scripts/pr-labels/test.js
+++ b/scripts/pr-labels/test.js
@@ -1,5 +1,5 @@
 const fs = require('fs');
-const { execSync } = require('child_process');
+const { execFileSync } = require('child_process');
 const path = require('path');
 
 const samplesPath = path.join(__dirname, 'samples.json');
@@ -11,7 +11,11 @@ let failed = 0;
 
 for (const sample of samples) {
   try {
-    const output = execSync(`node ${indexPath} --dry-run --json --pr-url ${sample.pr_url}`, { encoding: 'utf8', env: process.env });
+    const output = execFileSync(
+      process.execPath,
+      [indexPath, '--dry-run', '--json', '--pr-url', sample.pr_url],
+      { encoding: 'utf8', env: process.env }
+    );
     const result = JSON.parse(output);
 
     const matchLabel = result.label === sample.expected_label;

From 26072bb20aba40c50669dde4b9cf9145be47b36c Mon Sep 17 00:00:00 2001
From: williamfzc <178894043@qq.com>
Date: Tue, 31 Mar 2026 22:56:30 +0800
Subject: [PATCH 27/34] fix: resolve target path against process.cwd() instead
 of __dirname in skill-format-check

---
 scripts/skill-format-check/index.js | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/scripts/skill-format-check/index.js b/scripts/skill-format-check/index.js
index e96b7651f..71b14f00a 100644
--- a/scripts/skill-format-check/index.js
+++ b/scripts/skill-format-check/index.js
@@ -1,9 +1,13 @@
 const fs = require('fs');
 const path = require('path');
 
-// 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);
+// Allow passing a target directory as the first argument.
+// If provided, resolve against process.cwd() so it behaves as the user expects.
+// If not provided, default to '../../skills' relative to this script's directory.
+const targetDirArg = process.argv[2];
+const SKILLS_DIR = targetDirArg
+  ? path.resolve(process.cwd(), targetDirArg)
+  : path.resolve(__dirname, '../../skills');
 
 function checkSkillFormat() {
   console.log(`Checking skill format in ${SKILLS_DIR}...`);

From 405ef1521dd134dc3049a7d7dee24d3c2dfe2bf6 Mon Sep 17 00:00:00 2001
From: williamfzc <178894043@qq.com>
Date: Tue, 31 Mar 2026 23:22:14 +0800
Subject: [PATCH 28/34] docs: correct label prefix in PR label workflow README

- Updated README.md to reflect the new `domain/` label prefix instead of `area/`
---
 scripts/pr-labels/README.md | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/scripts/pr-labels/README.md b/scripts/pr-labels/README.md
index 963d208f4..99ca287cf 100644
--- a/scripts/pr-labels/README.md
+++ b/scripts/pr-labels/README.md
@@ -4,7 +4,7 @@ This directory contains scripts and sample data for automatically classifying an
 
 ## 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.
+- `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 `domain/*` 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
@@ -16,16 +16,16 @@ The script evaluates the "effective" lines of code changed (ignoring tests, docs
 - **`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 business areas a PR touches to give reviewers an immediate sense of the impact scope. Currently tracked areas include:
-- `area/im`
-- `area/vc`
-- `area/ccm`
-- `area/base`
-- `area/mail`
-- `area/calendar`
-- `area/task`
-- `area/contact`
+### Domain Tags (`domain/*`)
+The script also identifies which business domains a PR touches to give reviewers an immediate sense of the impact scope. Currently tracked domains include:
+- `domain/im`
+- `domain/vc`
+- `domain/ccm`
+- `domain/base`
+- `domain/mail`
+- `domain/calendar`
+- `domain/task`
+- `domain/contact`
 
 Minor modules like docs and tests are omitted to keep PR tags clean and focused on structural changes.
 

From 13b1c49751febcb75e29ea2d729a802049240bf9 Mon Sep 17 00:00:00 2001
From: williamfzc <178894043@qq.com>
Date: Tue, 31 Mar 2026 23:43:39 +0800
Subject: [PATCH 29/34] fix(ci): fix dry-run console output formatting and
 enforce auth in tests

- Removed duplicate domain array interpolation in printDryRunResult
- Added process.env.GITHUB_TOKEN guard in test.js to prevent ambiguous failures from API rate limits
---
 scripts/pr-labels/index.js | 1 -
 scripts/pr-labels/test.js  | 6 ++++++
 2 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/scripts/pr-labels/index.js b/scripts/pr-labels/index.js
index 39e4eaf1f..b7c410d5c 100755
--- a/scripts/pr-labels/index.js
+++ b/scripts/pr-labels/index.js
@@ -544,7 +544,6 @@ 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.businessDomains.length > 0 ? [`domains:${result.businessDomains.join(",")}`] : []),
   ];
   const reasonParts = result.reasons.length > 0
     ? result.reasons
diff --git a/scripts/pr-labels/test.js b/scripts/pr-labels/test.js
index b24c09fe3..db08ddc10 100644
--- a/scripts/pr-labels/test.js
+++ b/scripts/pr-labels/test.js
@@ -6,6 +6,12 @@ const samplesPath = path.join(__dirname, 'samples.json');
 const indexPath = path.join(__dirname, 'index.js');
 const samples = JSON.parse(fs.readFileSync(samplesPath, 'utf8'));
 
+if (!process.env.GITHUB_TOKEN) {
+  console.error("❌ Error: GITHUB_TOKEN environment variable is required to run tests without hitting API rate limits.");
+  console.error("Please run: GITHUB_TOKEN=$(gh auth token) node scripts/pr-labels/test.js");
+  process.exit(1);
+}
+
 let passed = 0;
 let failed = 0;
 

From eca66bd69a98a52348356428b4f51daa95e2ac17 Mon Sep 17 00:00:00 2001
From: williamfzc <178894043@qq.com>
Date: Wed, 1 Apr 2026 00:00:35 +0800
Subject: [PATCH 30/34] fix(ci): ensure PR labels can be applied reliably

- Added `issues: write` permission to pr-labels workflow, which is strictly required by the GitHub REST API to modify labels on pull requests
- Reordered script execution in `index.js` to apply/remove labels on the PR *before* attempting to sync repository-level label definitions (colors/descriptions). The definition sync is now a trailing best-effort step with error catching so transient repo-level API failures don't abort the critical path.
---
 .github/workflows/pr-labels.yml |  1 +
 scripts/pr-labels/index.js      | 15 ++++++++++-----
 2 files changed, 11 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/pr-labels.yml b/.github/workflows/pr-labels.yml
index c5234287a..096b41256 100644
--- a/.github/workflows/pr-labels.yml
+++ b/.github/workflows/pr-labels.yml
@@ -15,6 +15,7 @@ on:
 permissions:
   contents: read
   pull-requests: write
+  issues: write
 
 jobs:
   sync-pr-labels:
diff --git a/scripts/pr-labels/index.js b/scripts/pr-labels/index.js
index b7c410d5c..cdfe4d3af 100755
--- a/scripts/pr-labels/index.js
+++ b/scripts/pr-labels/index.js
@@ -699,17 +699,22 @@ async function main() {
     }
   }
 
-  // Keep label metadata consistent even when labels already exist in the repository.
-  for (const label of Object.keys(LABEL_DEFINITIONS)) {
-    await client.syncLabelDefinition(label);
-  }
-
   await client.addLabels(toAdd);
 
   for (const label of toRemove) {
     await client.removeLabel(label);
   }
 
+  // Keep label metadata consistent even when labels already exist in the repository.
+  // This is best-effort trailing work done after the critical path of applying the labels.
+  for (const label of Object.keys(LABEL_DEFINITIONS)) {
+    try {
+      await client.syncLabelDefinition(label);
+    } catch (e) {
+      log(`Warning: Failed to sync label definition for ${label}: ${e.message}`);
+    }
+  }
+
   await writeStepSummary(prNumber, classification);
 
   log(

From 798c039c0cb5d418cd957e7932c6fe64ca273715 Mon Sep 17 00:00:00 2001
From: williamfzc <178894043@qq.com>
Date: Wed, 1 Apr 2026 00:22:10 +0800
Subject: [PATCH 31/34] fix(ci): fix edge cases in pr-label index script

- Added missing `skills/lark-task/` to `PATH_TO_DOMAIN_MAP` to properly detect task domain modifications
- Updated GitHub REST API error checking in `syncLabelDefinition` to reliably match `error.status === 422` rather than loosely checking substring
- Moved token presence check in `main()` to happen before `resolveContext` to avoid triggering unauthenticated 401 API limits when GITHUB_TOKEN is omitted locally
---
 scripts/pr-labels/index.js | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/scripts/pr-labels/index.js b/scripts/pr-labels/index.js
index cdfe4d3af..c3163c3e3 100755
--- a/scripts/pr-labels/index.js
+++ b/scripts/pr-labels/index.js
@@ -56,6 +56,7 @@ const PATH_TO_DOMAIN_MAP = {
   "skills/lark-base/": "base",
   "skills/lark-mail/": "mail",
   "skills/lark-calendar/": "calendar",
+  "skills/lark-task/": "task",
   "skills/lark-contact/": "contact",
 };
 
@@ -167,7 +168,9 @@ class GitHubClient {
 
     if (!response.ok) {
       const detail = await response.text();
-      throw new Error(`GitHub API ${method} ${url} failed: ${response.status} ${detail}`);
+      const error = new Error(`GitHub API ${method} ${url} failed: ${response.status} ${detail}`);
+      error.status = response.status;
+      throw error;
     }
 
     const text = await response.text();
@@ -211,7 +214,7 @@ class GitHubClient {
       });
       log(`created label ${name}`);
     } catch (error) {
-      if (!String(error.message || error).includes(" 422 ")) {
+      if (error.status !== 422) {
         throw error;
       }
       await this.request(updateUrl, {
@@ -668,12 +671,13 @@ async function main() {
   }
 
   options.token = options.token || envValue("GITHUB_TOKEN");
-  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 { repo, prNumber, payload, client } = await resolveContext(options);
+
   const files = await client.listPrFiles();
   const classification = await classifyPr(payload, files);
 

From d4cd27c791c7d6d8340021a5b39cfdc37951cb79 Mon Sep 17 00:00:00 2001
From: williamfzc <178894043@qq.com>
Date: Wed, 1 Apr 2026 00:35:54 +0800
Subject: [PATCH 32/34] test(ci): clean up PR label test samples

- Removed duplicate PR entries (#11 and #57) to reduce redundant API calls during testing
- Renamed sample test cases to correctly reflect their expected labels (e.g. `size-l-skill-format-check` -> `size-m-skill-format-check`)
---
 scripts/pr-labels/samples.json | 28 +++-------------------------
 1 file changed, 3 insertions(+), 25 deletions(-)

diff --git a/scripts/pr-labels/samples.json b/scripts/pr-labels/samples.json
index 29e51eb7c..76dd7291b 100644
--- a/scripts/pr-labels/samples.json
+++ b/scripts/pr-labels/samples.json
@@ -98,28 +98,6 @@
     "expected_domains": [],
     "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",
-    "expected_domains": ["domain/base", "domain/ccm"],
-    "review_note": "Docs change but touches multiple business domains, making it 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",
-    "expected_domains": ["domain/ccm"],
-    "review_note": "Closed PR but useful as an L sample for effective lines exceeding 300."
-  },
   {
     "name": "size-l-fix-cli",
     "number": 91,
@@ -132,7 +110,7 @@
     "review_note": "Closed PR touching core area (cmd)."
   },
   {
-    "name": "size-l-skill-format-check",
+    "name": "size-m-skill-format-check",
     "number": 134,
     "title": "feat(ci): add skill format check workflow to ensure SKILL.md compliance",
     "pr_url": "https://github.com/larksuite/cli/pull/134",
@@ -143,7 +121,7 @@
     "review_note": "Includes updates to tests/bad-skill/SKILL.md inside skills-like paths, testing how skill mock files and test scripts are handled."
   },
   {
-    "name": "size-m-ccm-multi-path",
+    "name": "size-l-ccm-multi-path",
     "number": 57,
     "title": "feat(docs): support local image upload in docs +create",
     "pr_url": "https://github.com/larksuite/cli/pull/57",
@@ -154,7 +132,7 @@
     "review_note": "Touches docs_create_images.go and table_auto_width.go, representing multiple CCM sub-paths but resolving to a single ccm domain."
   },
   {
-    "name": "size-m-domain-rename",
+    "name": "size-l-domain-rename",
     "number": 11,
     "title": "docs: rename user-facing Bitable references to Base",
     "pr_url": "https://github.com/larksuite/cli/pull/11",

From 3c2224857262fd91d515aebf60270af31cb637c4 Mon Sep 17 00:00:00 2001
From: williamfzc <178894043@qq.com>
Date: Wed, 1 Apr 2026 00:51:44 +0800
Subject: [PATCH 33/34] fix(ci): bootstrap new labels before applying to PRs

- Prior changes correctly made full label sync best-effort, but broke the flow for brand new domains
- GitHub API returns a 422 error if you attempt to attach a label to an Issue/PR that does not exist in the repository
- Added a targeted bootstrap loop to create/sync specifically the labels in `toAdd` before attempting `client.addLabels()`
- Left the remaining global label synchronization as a best-effort trailing action
---
 scripts/pr-labels/index.js | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

diff --git a/scripts/pr-labels/index.js b/scripts/pr-labels/index.js
index c3163c3e3..5897d0c25 100755
--- a/scripts/pr-labels/index.js
+++ b/scripts/pr-labels/index.js
@@ -703,15 +703,27 @@ async function main() {
     }
   }
 
+  // Ensure labels to be added actually exist in the repository first
+  // If the label doesn't exist, GitHub API will return 422 Unprocessable Entity when trying to add it to a PR.
+  for (const label of toAdd) {
+    if (LABEL_DEFINITIONS[label]) {
+      try {
+        await client.syncLabelDefinition(label);
+      } catch (e) {
+        log(`Warning: Failed to bootstrap new label ${label}: ${e.message}`);
+      }
+    }
+  }
+
   await client.addLabels(toAdd);
 
   for (const label of toRemove) {
     await client.removeLabel(label);
   }
 
-  // Keep label metadata consistent even when labels already exist in the repository.
-  // This is best-effort trailing work done after the critical path of applying the labels.
+  // Keep other label metadata consistent. This is best-effort trailing work.
   for (const label of Object.keys(LABEL_DEFINITIONS)) {
+    if (toAdd.includes(label)) continue; // Already synced above
     try {
       await client.syncLabelDefinition(label);
     } catch (e) {

From fc3985b4ab4322b4c1752eb36a5dddb2d5e8265e Mon Sep 17 00:00:00 2001
From: williamfzc <178894043@qq.com>
Date: Wed, 1 Apr 2026 01:01:13 +0800
Subject: [PATCH 34/34] test(ci): automate PR label regression testing

- Added a dedicated GitHub Actions workflow (`pr-labels-test.yml`) to automatically run `test.js` against `samples.json` whenever the labeling logic is updated
- Documented local testing instructions in `scripts/pr-labels/README.md`
---
 .github/workflows/pr-labels-test.yml | 31 ++++++++++++++++++++++++++++
 scripts/pr-labels/README.md          | 12 ++++++++---
 2 files changed, 40 insertions(+), 3 deletions(-)
 create mode 100644 .github/workflows/pr-labels-test.yml

diff --git a/.github/workflows/pr-labels-test.yml b/.github/workflows/pr-labels-test.yml
new file mode 100644
index 000000000..df8dd8918
--- /dev/null
+++ b/.github/workflows/pr-labels-test.yml
@@ -0,0 +1,31 @@
+name: Test PR Label Logic
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "scripts/pr-labels/**"
+      - ".github/workflows/pr-labels-test.yml"
+  pull_request:
+    branches: [main]
+    paths:
+      - "scripts/pr-labels/**"
+      - ".github/workflows/pr-labels-test.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  test-pr-labels:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Run PR label regression tests
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: node scripts/pr-labels/test.js
diff --git a/scripts/pr-labels/README.md b/scripts/pr-labels/README.md
index 99ca287cf..a996c8c23 100644
--- a/scripts/pr-labels/README.md
+++ b/scripts/pr-labels/README.md
@@ -46,7 +46,13 @@ You can test the labeling logic against an existing GitHub PR without actually a
 node scripts/pr-labels/index.js --dry-run --repo larksuite/cli --pr-number 123
 ```
 
-To see the raw JSON output for programmatic use:
+## Testing
+
+A regression test suite is available in `test.js` which verifies the output of the classification logic against historical PRs configured in `samples.json`.
+
 ```bash
-node scripts/pr-labels/index.js --dry-run --repo larksuite/cli --pr-number 123 --json
-```
\ No newline at end of file
+# Requires GITHUB_TOKEN environment variable to avoid rate limits
+GITHUB_TOKEN=$(gh auth token) node scripts/pr-labels/test.js
+```
+
+This test suite also runs automatically in CI via `.github/workflows/pr-labels-test.yml` when changes are made to this directory.
\ No newline at end of file