feishu-user-plugin 1.3.10 → 1.3.12

package/scripts/check-description-drift.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+'use strict';
+// Verifies every manifest description / long_description references only
+// the current package.json::version (or no version at all).
+//
+// Catches the "plugin.json description stuck at v1.3.8 for 3 releases"
+// class of bug: a CI gate would have flagged it on the v1.3.9 release PR.
+//
+// Rule: every `vX.Y.Z` token inside the listed description fields must
+// equal the current package.json::version. To keep a description across
+// releases without churn, drop the version reference entirely.
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+const VERSION = require(path.join(ROOT, 'package.json')).version;
+
+// Match `vX.Y.Z` only (must have leading `v`) — avoids false positives on
+// schema versions like "0.3" or random numbers.
+const VERSION_PATTERN = /v(\d+\.\d+\.\d+)/g;
+
+const SOURCES = [
+  { label: 'package.json::description',                   file: 'package.json',                          extract: (raw) => JSON.parse(raw).description },
+  { label: '.claude-plugin/plugin.json::description',     file: '.claude-plugin/plugin.json',            extract: (raw) => JSON.parse(raw).description },
+  { label: '.cursor-plugin/plugin.json::description',     file: '.cursor-plugin/plugin.json',            extract: (raw) => JSON.parse(raw).description },
+  { label: 'mcp-registry.json::description',              file: 'mcp-registry.json',                     extract: (raw) => JSON.parse(raw).description },
+  { label: '.mcpb/manifest.json::description',            file: '.mcpb/manifest.json',                   extract: (raw) => JSON.parse(raw).description },
+  { label: '.mcpb/manifest.json::long_description',       file: '.mcpb/manifest.json',                   extract: (raw) => JSON.parse(raw).long_description },
+  { label: 'skills/feishu-user-plugin/SKILL.md description', file: 'skills/feishu-user-plugin/SKILL.md', extract: extractSkillDescription },
+];
+
+function extractSkillDescription(raw) {
+  // SKILL.md frontmatter has  description: "..."  on a single line.
+  const m = raw.match(/^description:\s*"((?:[^"\\]|\\.)*)"/m);
+  return m ? m[1].replace(/\\"/g, '"') : null;
+}
+
+const failures = [];
+
+for (const src of SOURCES) {
+  const fullPath = path.join(ROOT, src.file);
+  if (!fs.existsSync(fullPath)) {
+    failures.push(`${src.label}: source file ${src.file} does not exist`);
+    continue;
+  }
+
+  let description;
+  try {
+    description = src.extract(fs.readFileSync(fullPath, 'utf8'));
+  } catch (e) {
+    failures.push(`${src.label}: parse error — ${e.message}`);
+    continue;
+  }
+
+  if (!description) continue; // Field absent — nothing to check.
+
+  for (const m of description.matchAll(VERSION_PATTERN)) {
+    const found = m[1];
+    if (found !== VERSION) {
+      failures.push(`${src.label}: references v${found}, but package.json is v${VERSION}`);
+    }
+  }
+}
+
+if (failures.length) {
+  console.error('description drift detected:');
+  for (const f of failures) console.error(`  ${f}`);
+  console.error(`\nFix: update each description to reference v${VERSION}, or remove the version reference entirely (e.g. drop "v1.3.8: feature X" → "feature X").`);
+  process.exit(1);
+}
+
+console.log(`OK: all manifest descriptions reference v${VERSION} (or no version reference)`);

package/scripts/check-docs-sync.js

@@ -1,14 +1,12 @@
 #!/usr/bin/env node
 'use strict';
-// Verifies CLAUDE.md is in sync with AGENTS.md (Codex) and
-// skills/feishu-user-plugin/references/CLAUDE.md (skill reference copy).
+// Verifies CLAUDE.md is in sync with AGENTS.md (Codex).
 //
-// Pre-commit hook (scripts/sync-claude-md.sh) already auto-regenerates these
+// Pre-commit hook (scripts/sync-claude-md.sh) already auto-regenerates AGENTS.md
 // from CLAUDE.md, but this script gives prepublishOnly + CI a hard gate.
 //
-// Match logic mirrors validate.yml's diff steps:
-//   AGENTS.md = "# feishu-user-plugin — Codex Instructions\n" + tail -n +2 CLAUDE.md
-//   skills/.../CLAUDE.md = identical to CLAUDE.md
+// Match logic mirrors validate.yml's diff step:
+//   AGENTS.md = "# feishu-user-plugin — Codex 指令\n" + tail -n +2 CLAUDE.md
 
 const fs = require('fs');
 const path = require('path');
@@ -16,9 +14,9 @@ const path = require('path');
 const ROOT = path.join(__dirname, '..');
 const claude = fs.readFileSync(path.join(ROOT, 'CLAUDE.md'), 'utf8');
 
-// AGENTS.md: header replaced with "# feishu-user-plugin — Codex Instructions"
+// AGENTS.md: header replaced with "# feishu-user-plugin — Codex 指令"
 const claudeBody = claude.split('\n').slice(1).join('\n'); // drop first line
-const expectedAgents = '# feishu-user-plugin — Codex Instructions\n' + claudeBody;
+const expectedAgents = '# feishu-user-plugin — Codex 指令\n' + claudeBody;
 const actualAgents = fs.readFileSync(path.join(ROOT, 'AGENTS.md'), 'utf8');
 
 const failures = [];
@@ -27,15 +25,8 @@ if (actualAgents !== expectedAgents) {
   failures.push('Fix: bash scripts/sync-claude-md.sh (or edit CLAUDE.md and re-stage)');
 }
 
-const skillRef = path.join(ROOT, 'skills', 'feishu-user-plugin', 'references', 'CLAUDE.md');
-const actualSkillRef = fs.readFileSync(skillRef, 'utf8');
-if (actualSkillRef !== claude) {
-  failures.push('skills/feishu-user-plugin/references/CLAUDE.md is out of sync with CLAUDE.md');
-  failures.push('Fix: bash scripts/sync-claude-md.sh (or edit CLAUDE.md and re-stage)');
-}
-
 if (failures.length) {
   for (const f of failures) console.error(f);
   process.exit(1);
 }
-console.log('OK: CLAUDE.md / AGENTS.md / skill reference all in sync');
+console.log('OK: CLAUDE.md / AGENTS.md in sync');

package/scripts/check-mcp-registry-version.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+'use strict';
+// Verifies mcp-registry.json::version + packages[0].version == package.json::version.
+// Wired into:
+//   - .github/workflows/publish.yml — pre-publish gate so CI never publishes to the
+//     official MCP Registry with a stale version string.
+//   - .github/workflows/validate.yml — PR-time gate so any version bump on
+//     package.json without a matching bump on mcp-registry.json fails before merge.
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+
+const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
+const pkgVersion = pkg.version;
+
+const registryPath = path.join(ROOT, 'mcp-registry.json');
+const registry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+const registryVersion = registry.version;
+
+if (!Array.isArray(registry.packages) || registry.packages.length === 0) {
+  console.error('ERROR: mcp-registry.json has no packages[] entries');
+  process.exit(1);
+}
+const pkgEntryVersion = registry.packages[0].version;
+
+const sources = [
+  { label: 'package.json', version: pkgVersion, path: 'package.json' },
+  { label: 'mcp-registry.json::version', version: registryVersion, path: 'mcp-registry.json' },
+  { label: 'mcp-registry.json::packages[0].version', version: pkgEntryVersion, path: 'mcp-registry.json' },
+];
+
+const allEqual = sources.every((s) => s.version === sources[0].version);
+
+if (!allEqual) {
+  console.error('ERROR: mcp-registry.json version mismatch with package.json!');
+  sources.forEach((s) => console.error(`  ${s.label}: ${s.version}`));
+  console.error('Fix: bump mcp-registry.json::version AND mcp-registry.json::packages[0].version');
+  console.error(`     to match package.json (${pkgVersion}).`);
+  process.exit(1);
+}
+
+console.log(`OK: mcp-registry.json version ${pkgVersion}`);

package/scripts/check-mcpb-version.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+'use strict';
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+
+// Source 1: package.json
+const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
+const pkgVersion = pkg.version;
+
+// Source 2: .mcpb/manifest.json
+const manifestPath = path.join(ROOT, '.mcpb', 'manifest.json');
+if (!fs.existsSync(manifestPath)) {
+  console.error('ERROR: .mcpb/manifest.json not found');
+  process.exit(1);
+}
+const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+const manifestVersion = manifest.version;
+
+if (!manifestVersion) {
+  console.error('ERROR: .mcpb/manifest.json is missing the `version` field');
+  process.exit(1);
+}
+
+if (pkgVersion !== manifestVersion) {
+  console.error('ERROR: .mcpb manifest version mismatch!');
+  console.error(`  package.json:        ${pkgVersion}`);
+  console.error(`  .mcpb/manifest.json: ${manifestVersion}`);
+  process.exit(1);
+}
+
+console.log(`OK: .mcpb manifest version ${pkgVersion}`);

package/scripts/check-scopes.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+'use strict';
+
+// Validates src/oauth.js::SCOPES against:
+//  1) BANLIST — scope names we've confirmed do NOT exist in Feishu's catalog
+//     (caused OAuth 422 / runtime 20043). Add new ones here when discovered.
+//  2) docs/AUTH-SETUP.md mentions — every scope in SCOPES must appear at least
+//     once in AUTH-SETUP.md, so the doc never drifts behind the code.
+//
+// Why this gate exists: Feishu's OAuth server SILENTLY accepted some malformed
+// scope names pre-2026-05 (they were ignored, UAT just lacked the scope); from
+// May 2026 it started rejecting the whole authorize request with 422 +
+// "scope <name> 有误". A single bad name in SCOPES locks every user out of
+// `npx oauth`. This script catches it in CI before merge.
+
+const path = require('path');
+const fs = require('fs');
+
+const repoRoot = path.join(__dirname, '..');
+
+// --- Step 1: extract SCOPES constant from src/oauth.js ---
+const oauthSrc = fs.readFileSync(path.join(repoRoot, 'src', 'oauth.js'), 'utf8');
+const m = oauthSrc.match(/const\s+SCOPES\s*=\s*'([^']+)'/);
+if (!m) {
+  console.error('check-scopes: could not find `const SCOPES = \'...\'` in src/oauth.js');
+  process.exit(1);
+}
+const scopes = m[1].split(/\s+/).filter(Boolean);
+
+// --- Step 1b: ADDITIONAL_APP_SCOPES — tenant-side scopes that the plugin requires
+// but that don't live in SCOPES (because they can't be granted via OAuth — only
+// in the Feishu app console "应用身份" tab). Validated against AUTH-SETUP.md only.
+const ADDITIONAL_APP_SCOPES = [
+  // Used by LarkOfficialClient.getAppName() to resolve self-app display label.
+  // Without it, `senderType=app` messages fall back to "[Bot] (cli_xxx)".
+  // Feishu marks this scope as 免审权限 (no admin review needed).
+  'application:application:self_manage',
+];
+
+// --- Step 2: BANLIST of known-bad scope names ---
+//
+// Each entry: { bad: '<name>', reason: '<why>', replacement: '<correct names>' }
+// Append-only — never remove an entry (it's a regression guard).
+const BANLIST = [
+  {
+    bad: 'calendar:calendar.event:write',
+    reason: 'Feishu catalog has no such scope. The catalog splits write into 4 verbs.',
+    replacement: 'calendar:calendar.event:create + calendar:calendar.event:update + calendar:calendar.event:delete + calendar:calendar.event:reply',
+  },
+  {
+    bad: 'okr:okr.content:write',
+    reason: 'Feishu catalog uses :writeonly (one word) not :write.',
+    replacement: 'okr:okr.content:writeonly',
+  },
+];
+
+// --- Step 3: validate ---
+const failures = [];
+
+for (const entry of BANLIST) {
+  if (scopes.includes(entry.bad)) {
+    failures.push(
+      `BANLIST hit: SCOPES contains \`${entry.bad}\`.\n` +
+      `  Reason: ${entry.reason}\n` +
+      `  Replace with: ${entry.replacement}`
+    );
+  }
+}
+
+// docs/AUTH-SETUP.md must mention every scope. Catches silent additions
+// to SCOPES that never made it into the OAuth setup docs.
+const authSetupPath = path.join(repoRoot, 'docs', 'AUTH-SETUP.md');
+const authSetup = fs.readFileSync(authSetupPath, 'utf8');
+const missingFromDocs = scopes.filter(s => s !== 'offline_access' && !authSetup.includes(s));
+if (missingFromDocs.length) {
+  failures.push(
+    `${missingFromDocs.length} scope(s) in SCOPES not mentioned in docs/AUTH-SETUP.md:\n` +
+    missingFromDocs.map(s => `  - ${s}`).join('\n') +
+    `\n  Add them to the scope table around line 117 (\`## OAuth Scopes\` section).`
+  );
+}
+
+// Same enforcement for tenant-only scopes.
+const missingAppScopes = ADDITIONAL_APP_SCOPES.filter(s => !authSetup.includes(s));
+if (missingAppScopes.length) {
+  failures.push(
+    `${missingAppScopes.length} tenant-side scope(s) not in docs/AUTH-SETUP.md:\n` +
+    missingAppScopes.map(s => `  - ${s}`).join('\n') +
+    `\n  Add them to the "应用身份额外 scope" section.`
+  );
+}
+
+if (failures.length) {
+  console.error('check-scopes: FAIL\n');
+  for (const f of failures) console.error(f + '\n');
+  process.exit(1);
+}
+
+console.log(`check-scopes: OK (${scopes.length} OAuth + ${ADDITIONAL_APP_SCOPES.length} tenant-only scopes, ${BANLIST.length} banned names guarded)`);

package/scripts/check-tool-count.js

@@ -6,11 +6,12 @@ const { TOOLS } = require(path.join(__dirname, '..', 'src', 'server'));
 
 const failures = [];
 
-// Source 1: README.md "N tools" badge
+// Source 1: README.md tool count — accepts "N tools" (English) or "N 工具" (Chinese)
+// since README.md is Chinese-primary while README.en.md mirrors in English.
 const readme = fs.readFileSync(path.join(__dirname, '..', 'README.md'), 'utf8');
-const readmeMatch = readme.match(/(\d+)\s+tools/);
+const readmeMatch = readme.match(/(\d+)\s*(?:tools|工具)/);
 if (!readmeMatch) {
-  failures.push('No "N tools" badge in README.md');
+  failures.push('No "N tools" / "N 工具" marker in README.md');
 } else if (parseInt(readmeMatch[1], 10) !== TOOLS.length) {
   failures.push(`README.md claims ${readmeMatch[1]} tools, src/server.js has ${TOOLS.length}`);
 }

package/scripts/check-version.js

@@ -22,10 +22,15 @@ if (!skillMatch) {
 }
 const skillVersion = skillMatch[1];
 
+// Source 4: .cursor-plugin/plugin.json
+const cursorPlugin = JSON.parse(fs.readFileSync(path.join(ROOT, '.cursor-plugin', 'plugin.json'), 'utf8'));
+const cursorVersion = cursorPlugin.version;
+
 const sources = [
   { label: 'package.json', version: pkgVersion, path: 'package.json' },
   { label: '.claude-plugin/plugin.json', version: pluginVersion, path: '.claude-plugin/plugin.json' },
   { label: 'skills/feishu-user-plugin/SKILL.md', version: skillVersion, path: 'skills/feishu-user-plugin/SKILL.md' },
+  { label: '.cursor-plugin/plugin.json', version: cursorVersion, path: '.cursor-plugin/plugin.json' },
 ];
 
 const versions = sources.map((s) => s.version);

package/scripts/sync-claude-md.sh

@@ -4,9 +4,8 @@ ROOT="$(git rev-parse --show-toplevel)"
 cd "$ROOT"
 if git diff --cached --name-only | grep -qx "CLAUDE.md"; then
   tail -n +2 CLAUDE.md > /tmp/feishu-claude-body.$$
-  { echo "# feishu-user-plugin — Codex Instructions"; cat /tmp/feishu-claude-body.$$; } > AGENTS.md
+  { echo "# feishu-user-plugin — Codex 指令"; cat /tmp/feishu-claude-body.$$; } > AGENTS.md
   rm -f /tmp/feishu-claude-body.$$
-  cp CLAUDE.md skills/feishu-user-plugin/references/CLAUDE.md
-  git add AGENTS.md skills/feishu-user-plugin/references/CLAUDE.md
-  echo "[hook] CLAUDE.md → AGENTS.md + skill reference synced"
+  git add AGENTS.md
+  echo "[hook] CLAUDE.md → AGENTS.md synced"
 fi

package/scripts/sync-team-skills.sh

@@ -1,28 +1,30 @@
 #!/usr/bin/env bash
 # scripts/sync-team-skills.sh — post-merge hook on main.
 #
-# What this does (zero manual steps, no degradation):
-#   1. Copy skills/ + .claude-plugin/plugin.json into team-skills repo
-#   2. Run team-skills' generate-catalog.py (forced manual-yaml path for byte
-#      parity with CI)
-#   3. Run our scripts/generate-release-artifacts.js to produce
-#      changelog + readme-row from CHANGELOG.md
-#   4. Inject the changelog block into team-skills child README before the
-#      previous version's heading
-#   5. Replace the team-skills root README catalog row matching feishu-user-plugin
-#   6. Commit + push branch + open PR
-#   7. Auto-merge: --admin --squash (we have admin on team-skills repo;
-#      org-level setting blocks repo PATCH for allow_auto_merge so we use
-#      --admin to bypass review wait. CI is non-blocking via "Check catalog"
-#      drift never happening since step 2 produced byte-identical output.)
+# Idempotent + conflict-resilient sync from feishu-user-plugin's main into
+# zhuzhen-team/team-skills. Designed so retries always converge:
 #
-# Failure modes are now narrow:
+# Flow:
+#   1. Generate release artifacts in feishu repo (changelog block + readme row).
+#   2. cd team-skills repo, fetch origin main.
+#   3. Close any stale OPEN sync PRs whose branch is for an older version
+#      (so v1.3.10 sync doesn't pile up behind a never-merged v1.3.9 sync).
+#   4. Delete any local stale sync/feishu-v$VERSION branch and recreate from
+#      origin/main — always starts fresh, never carries leftover commits.
+#   5. Copy plugin tree + inject changelog + replace catalog row + regen catalog.
+#   6. If nothing changed → exit 0 (already in sync for v$VERSION).
+#   7. Commit + push --force-with-lease (safe: only this script writes to sync/* branches).
+#   8. Open PR if not exists; merge --admin --squash.
+#
+# Failure modes:
 #   - team-skills repo not cloned at expected path → clean skip
-#   - branch already exists from previous attempt → clean skip
-#   - generate-release-artifacts.js fails → exit non-zero (visible to user
-#     via post-merge stderr; user fixes CHANGELOG and re-pushes)
+#   - generate-release-artifacts.js fails → exit non-zero (visible in stderr)
+#   - PR merge fails (rare; should be impossible after force-recreate from origin/main)
+#     → exit non-zero, post-merge wrapper labels as "non-fatal" but user sees stderr
 set -e
-TEAM_SKILLS="/Users/abble/team-skills/plugins/feishu-user-plugin"
+
+TEAM_SKILLS_REPO="/Users/abble/team-skills"
+TEAM_SKILLS="$TEAM_SKILLS_REPO/plugins/feishu-user-plugin"
 if [ ! -d "$TEAM_SKILLS" ]; then echo "[hook] team-skills not present, skip"; exit 0; fi
 
 ROOT="$(git rev-parse --show-toplevel)"
@@ -30,25 +32,43 @@ cd "$ROOT"
 
 VERSION=$(node -e "console.log(require('./package.json').version)")
 ARTIFACTS="/tmp/feishu-release/v${VERSION}"
+BRANCH="sync/feishu-v$VERSION"
 
-# Generate release artifacts FIRST so we can inject them into team-skills.
-# This reads CHANGELOG.md for the v$VERSION section and emits team-skills
-# changelog markdown + root readme row + announcement card JSON.
+# 1. Generate release artifacts FIRST so we can inject them into team-skills.
 node scripts/generate-release-artifacts.js "$VERSION" >/dev/null
 
-# Copy plugin tree.
-cp -r skills/. "$TEAM_SKILLS/skills/"
-cp .claude-plugin/plugin.json "$TEAM_SKILLS/.claude-plugin/"
+# 2. cd team-skills, fetch origin main.
+cd "$TEAM_SKILLS_REPO"
+git fetch origin main --quiet
+
+# 3. Close any stale OPEN sync PRs (different version branch). Idempotent —
+#    any matching PR for this same $VERSION is preserved (we'll force-update
+#    its branch in step 7 instead).
+STALE_PRS=$(gh pr list --state open --search "Sync feishu-user-plugin in:title" \
+  --json number,headRefName --jq ".[] | select(.headRefName != \"$BRANCH\") | .number")
+if [ -n "$STALE_PRS" ]; then
+  for stale_num in $STALE_PRS; do
+    gh pr close "$stale_num" \
+      --comment "Superseded by sync/feishu-v$VERSION (auto-closed by sync-team-skills.sh)" \
+      --delete-branch 2>&1 | tail -1 || true
+    echo "[hook] closed stale sync PR #$stale_num"
+  done
+fi
+
+# 4. Delete any local stale sync branch + recreate from origin/main.
+#    `git checkout -B` is "create or reset". We always start from latest main
+#    so there are no inherited commits from older sync attempts.
+git checkout -B "$BRANCH" origin/main
+
+# 5. Copy plugin tree from feishu repo, inject changelog, regen catalog.
+cp -r "$ROOT/skills/." "$TEAM_SKILLS/skills/"
+cp "$ROOT/.claude-plugin/plugin.json" "$TEAM_SKILLS/.claude-plugin/"
 
-# Inject changelog block into team-skills/plugins/feishu-user-plugin/README.md.
-# Insert just before the existing first "### vX.Y.Z" heading, OR after
-# "## 更新日志" if no prior version exists.
+# 5a. Inject changelog block into team-skills child README (idempotent).
 README="$TEAM_SKILLS/README.md"
 if grep -q "^### v${VERSION} " "$README"; then
   echo "[hook] team-skills child README already has v${VERSION} section, skipping inject"
 else
-  # awk: print everything; when we hit the FIRST `### vX.Y.Z (date)` heading,
-  # insert the new block before it.
   awk -v block_file="$ARTIFACTS/team-skills-changelog.md" '
     BEGIN { inserted = 0 }
     /^### v[0-9]+\.[0-9]+\.[0-9]+ \(/ && !inserted {
@@ -61,14 +81,12 @@ else
   echo "[hook] injected v${VERSION} changelog block into child README"
 fi
 
-# Replace the team-skills root README catalog row matching feishu-user-plugin.
-ROOT_README="$TEAM_SKILLS/../../README.md"
+# 5b. Replace root README catalog row matching feishu-user-plugin.
+ROOT_README="$TEAM_SKILLS_REPO/README.md"
 NEW_ROW=$(cat "$ARTIFACTS/team-skills-readme-row.md")
 if grep -q "^| \\*\\*feishu-user-plugin\\*\\* |" "$ROOT_README"; then
-  # Replace the line in-place. Use Python (sed regex with table chars + |
-  # quotes is brittle across BSD/GNU).
   python3 -c "
-import sys, re
+import re
 p = '$ROOT_README'
 new_row = '''$NEW_ROW'''.strip()
 text = open(p, 'r', encoding='utf-8').read()
@@ -78,47 +96,44 @@ open(p, 'w', encoding='utf-8').write(text)
   echo "[hook] updated root README catalog row to v${VERSION}"
 fi
 
-# Switch into team-skills repo root (two parents up from $TEAM_SKILLS).
-cd "$TEAM_SKILLS/../.."
-
-BRANCH="sync/feishu-v$VERSION"
-if git rev-parse --verify "$BRANCH" >/dev/null 2>&1; then
-  echo "[hook] branch $BRANCH already exists locally, skipping"; exit 0
-fi
-git checkout -b "$BRANCH"
-
-# team-skills CI runs generate-catalog.py without PyYAML; force the same path
-# locally for byte-identical output. Verified in PR #36.
+# 5c. Regenerate catalog.yaml (force PyYAML-less path for byte parity with CI).
 if [ -f "scripts/generate-catalog.py" ]; then
   python3 -c "import sys, runpy; sys.modules['yaml']=None; runpy.run_path('scripts/generate-catalog.py', run_name='__main__')" >/dev/null 2>&1
 fi
 
-# Stage every file the hook might have touched. Each `git add` is idempotent
-# on already-clean files, so unchanged ones stage as no-op. Files that don't
-# exist (e.g., catalog.yaml when team-skills repo doesn't have the generator)
-# would fail under `set -e`, so guard explicitly.
+# 6. Stage everything the hook touched.
 git add "plugins/feishu-user-plugin/"
 [ -f "README.md" ]    && git add README.md
 [ -f "catalog.yaml" ] && git add catalog.yaml
 
-# If nothing actually changed, exit 0 — the v$VERSION sync was already done.
 if git diff --cached --quiet; then
   echo "[hook] nothing to sync (working tree clean for v$VERSION)"; exit 0
 fi
 
 git commit -m "chore: sync feishu-user-plugin v$VERSION (skills + plugin.json + README changelog + catalog)"
-git push -u origin "$BRANCH"
 
-gh pr create --title "Sync feishu-user-plugin v$VERSION" --body "Auto-sync from feishu-user-plugin main. Includes:
+# 7. Push (force-with-lease since this branch is exclusively written by this
+#    script — safe even if a previous run pushed something we just rebuilt).
+git push --force-with-lease -u origin "$BRANCH"
+
+# 8. Open PR if not exists, then merge.
+PR_NUM=$(gh pr list --head "$BRANCH" --state open --json number --jq ".[0].number // empty")
+if [ -z "$PR_NUM" ]; then
+  gh pr create --title "Sync feishu-user-plugin v$VERSION" --body "Auto-sync from feishu-user-plugin main. Includes:
 - plugins/feishu-user-plugin/.claude-plugin/plugin.json bumped to v$VERSION
 - plugins/feishu-user-plugin/skills/ regenerated
 - plugins/feishu-user-plugin/README.md: v$VERSION changelog section auto-generated from feishu-user-plugin's CHANGELOG.md
 - README.md (root): catalog row updated
 - catalog.yaml regenerated"
+  PR_NUM=$(gh pr view "$BRANCH" --json number --jq .number)
+  echo "[hook] opened sync PR #$PR_NUM"
+else
+  echo "[hook] reusing existing sync PR #$PR_NUM (branch force-updated)"
+fi
 
-PR_NUM=$(gh pr view --json number --jq .number)
-# Use --admin --squash: we have admin permissions on team-skills (verified) and
-# the team-skills org has auto-merge disabled at org level. --admin merges
-# without waiting for required reviews. CI is informational only here.
+# Use --admin --squash: we have admin permissions on team-skills (verified).
+# After step 4's force-recreate from origin/main, this PR is always cleanly
+# mergeable (no carried conflicts). --admin bypasses required reviews; CI
+# is informational since step 5c produced byte-identical catalog output.
 gh pr merge "$PR_NUM" --admin --squash
 echo "[hook] team-skills sync PR #$PR_NUM merged"

package/scripts/verify-app-name.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+// scripts/verify-app-name.js — diagnostic: does the current app have the
+// tenant-side `application:application:self_manage` scope?
+//
+// Hits Feishu's app-info endpoint with the current credentials' APP_ID/SECRET
+// and prints either the resolved app name (scope is granted) or the error
+// code (with remediation pointing at docs/AUTH-SETUP.md).
+//
+// Usage:
+//   node scripts/verify-app-name.js
+//
+// Exit codes:
+//   0  scope works, displayLabel will say "[Bot] AppName"
+//   1  99991672 — scope missing, displayLabel will fall back to "[Bot] (cli_xxx)"
+//   2  other auth failure (wrong APP_ID/SECRET, network, etc.)
+
+'use strict';
+
+const { readCredentials } = require('../src/auth/credentials');
+
+async function main() {
+  const creds = readCredentials() || {};
+  const appId = creds.LARK_APP_ID;
+  const appSecret = creds.LARK_APP_SECRET;
+  if (!appId || !appSecret) {
+    console.error('No LARK_APP_ID/SECRET in credentials. Run `npx feishu-user-plugin setup` first.');
+    process.exit(2);
+  }
+  console.error(`Probing app info for APP_ID=${appId}…`);
+
+  const tokenRes = await fetch('https://open.feishu.cn/open-apis/auth/v3/app_access_token/internal', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ app_id: appId, app_secret: appSecret }),
+  });
+  const tokenData = await tokenRes.json();
+  if (!tokenData.app_access_token) {
+    console.error(`app_access_token request failed: ${JSON.stringify(tokenData)}`);
+    process.exit(2);
+  }
+
+  const infoRes = await fetch(`https://open.feishu.cn/open-apis/application/v6/applications/${appId}?lang=zh_cn`, {
+    headers: { 'Authorization': `Bearer ${tokenData.app_access_token}` },
+  });
+  const info = await infoRes.json();
+
+  if (info.code === 0 && info.data?.app?.app_name) {
+    console.error(`OK — app name resolves to "${info.data.app.app_name}". displayLabel will read "[Bot] ${info.data.app.app_name}".`);
+    process.exit(0);
+  }
+  if (info.code === 99991672) {
+    console.error('FAIL — code 99991672. The tenant-side scope `application:application:self_manage` is not granted.');
+    console.error('Fix:');
+    console.error('  1. Open https://open.feishu.cn/app/<appId>/safe — "应用身份" tab');
+    console.error('  2. Add scope `application:application:self_manage` (marked 免审权限 — no admin review needed)');
+    console.error('  3. Save; no re-publish required');
+    console.error('  4. Re-run this script to confirm');
+    process.exit(1);
+  }
+  console.error(`FAIL — unexpected response: code=${info.code} msg=${info.msg || JSON.stringify(info)}`);
+  process.exit(2);
+}
+
+main().catch((e) => { console.error(`Threw: ${e.message}`); process.exit(2); });

package/skills/feishu-user-plugin/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: feishu-user-plugin
-version: "1.3.10"
-description: "All-in-one Feishu plugin — send messages as yourself (incl. batch_send), read group/P2P chats (auto-expands merge_forward), manage docs/tables/wiki (full CRUD)/drive, OKR (with progress writes), calendar (read+write), Tasks v2, multi-profile auto-switch, real-time WS events. v1.3.8: multi-profile auto-switch on read errors (B), WebSocket realtime im.message events via get_new_events (C), credential pointer-only mode (E), CI gates (F), auth/uat.js + auth/cookie.js extracts (D)."
-allowed-tools: send_to_user, send_to_group, send_as_user, send_image_as_user, send_file_as_user, send_post_as_user, batch_send, send_card_as_user, search_contacts, create_p2p_chat, get_chat_info, get_user_info, get_login_status, list_profiles, switch_profile, manage_profile_hints, read_p2p_messages, list_user_chats, list_chats, read_messages, send_message_as_bot, reply_message, forward_message, delete_message, update_message, add_reaction, delete_reaction, pin_message, create_group, update_group, list_members, manage_members, search_docs, read_doc, get_doc_blocks, create_doc, manage_doc_block, read_doc_markdown, manage_bitable_app, manage_bitable_table, manage_bitable_field, manage_bitable_view, manage_bitable_record, upload_bitable_attachment, list_wiki_spaces, search_wiki, list_wiki_nodes, get_wiki_node, create_wiki_node, update_wiki_node, move_wiki_node, copy_wiki_node, delete_wiki_node, list_files, create_folder, upload_drive_file, manage_drive_file, upload_image, upload_file, download_message_resource, download_doc_image, list_user_okrs, get_okrs, list_okr_periods, create_okr_progress_record, list_okr_progress_records, delete_okr_progress_record, list_calendars, list_calendar_events, get_calendar_event, create_calendar_event, update_calendar_event, delete_calendar_event, respond_calendar_event, get_freebusy, list_tasks, get_task, create_task, update_task, complete_task, delete_task, manage_task_members, get_new_events, manage_ws_status
+version: "1.3.12"
+description: "All-in-one Feishu MCP server + CLI tool — send messages as yourself (incl. batch_send), read group/P2P chats (auto-expands merge_forward), manage docs/tables/wiki (full CRUD)/drive, OKR (with progress writes), calendar (read+write), Tasks v2, multi-profile auto-switch, real-time WS events. v1.3.12: search_messages tool (Protobuf phase 2 B.5, UAT-only), CLI tool mode (`tool list` / `tool help <name>` / `tool <name> '<json>'`), IdentityState state machine + credentials hot-reload (no-restart UAT reload), displayLabel + sender semantics pack for LLM consumption, WS owner PID liveness check, gitleaks secret scan."
+allowed-tools: send_to_user, send_to_group, send_as_user, send_image_as_user, send_file_as_user, send_post_as_user, batch_send, send_card_as_user, search_contacts, create_p2p_chat, get_chat_info, get_user_info, get_login_status, list_profiles, switch_profile, manage_profile_hints, read_p2p_messages, list_user_chats, list_chats, read_messages, search_messages, send_message_as_bot, reply_message, forward_message, delete_message, update_message, add_reaction, delete_reaction, pin_message, create_group, update_group, list_members, manage_members, search_docs, read_doc, get_doc_blocks, create_doc, manage_doc_block, read_doc_markdown, manage_bitable_app, manage_bitable_table, manage_bitable_field, manage_bitable_view, manage_bitable_record, upload_bitable_attachment, list_wiki_spaces, search_wiki, list_wiki_nodes, get_wiki_node, create_wiki_node, update_wiki_node, move_wiki_node, copy_wiki_node, delete_wiki_node, list_files, create_folder, upload_drive_file, manage_drive_file, upload_image, upload_file, download_message_resource, download_doc_image, list_user_okrs, get_okrs, list_okr_periods, create_okr_progress_record, list_okr_progress_records, delete_okr_progress_record, list_calendars, list_calendar_events, get_calendar_event, create_calendar_event, update_calendar_event, delete_calendar_event, respond_calendar_event, get_freebusy, list_tasks, get_task, create_task, update_task, complete_task, delete_task, manage_task_members, get_new_events, manage_ws_status
 user_invocable: true
 ---
 

package/skills/feishu-user-plugin/references/search.md

@@ -15,8 +15,8 @@
    - `/digest 群名` 整理聊天摘要
 
 ## 通过邮箱或手机号查找
-如果用户提供了邮箱或手机号，改用 `find_user`：
+邮箱、手机号、姓名都可以作为 `query` 直接传给 `search_contacts`，不需要单独的工具：
 ```
-find_user({ email: "xxx@xxx.com" })
-find_user({ mobile: "+86xxx" })
+search_contacts({ query: "xxx@xxx.com" })
+search_contacts({ query: "+86xxx" })
 ```