整理一下文档站轻量维护和健康巡检流程

这次主要补充创游世界资料库的日常轻量维护能力，把仓库健康巡检、链接检查、同步临时文件清理、VS Code 扫描优化和维护流程文档整理到一起，减少后续小改时反复完整构建、误扫缓存目录、同步冲突文件混入仓库等问题。

主要调整：

- 新增仓库健康巡检脚本，用于生成轻量巡检报告
- 新增文档链接轻量检查脚本，用于检查旧域名和疑似失效本地链接
- 新增同步临时文件清理脚本，支持 dry-run 预览
- 补充 docs:check:light、docs:health:audit、docs:sync:clean 等维护命令
- 新增轻量检查与维护流程文档，明确日常小改优先使用轻量检查
- 增加 VS Code 工作区排除规则，减少 node_modules、构建产物和同步缓存带来的扫描压力
- 保持日常小改不强制完整构建，只在发布、部署或结构性改动前做完整检查

Author: Azek431

docs/维护与报告/轻量检查与维护流程.md

@@ -0,0 +1,76 @@
+---
+title: 轻量检查与维护流程
+description: 说明创游世界资料库日常维护时优先使用的轻量检查命令，避免每次小改都触发大范围日期更新或完整构建。
+created: 2026-06-08
+updated: 2026-06-08
+search: false
+---
+
+# 轻量检查与维护流程
+
+这份文档用于记录创游世界资料库的日常轻量维护方式。
+
+它的目标不是替代完整构建，而是让日常小改、UI 微调、链接检查、同步文件清理、仓库健康巡检变得更稳定、更省时间。
+
+## 日常小改优先使用
+
+日常小改、文案调整、少量样式优化时，优先运行：
+
+    pnpm run quality:check
+    git diff --check
+    git status -sb
+    git diff --stat
+
+如果这次改动主要集中在文档内容，也可以运行：
+
+    pnpm run docs:check:light
+    git diff --check
+    git status -sb
+    git diff --stat
+
+## 同步文件清理
+
+清理前先预览：
+
+    pnpm run docs:sync:clean:dry
+
+确认没有误删风险后再清理：
+
+    pnpm run docs:sync:clean
+
+这个命令只用于清理 Syncthing 冲突文件、临时下载文件、系统缩略图文件和回收站目录，不应该碰源码、Git、node_modules 或构建产物。
+
+## 仓库健康巡检
+
+需要生成轻量巡检报告时运行：
+
+    pnpm run docs:health:audit
+
+报告会写入：
+
+    docs/维护与报告/仓库健康巡检报告.md
+
+报告里的中低风险问题不一定都要立刻处理，但高风险问题需要优先检查。
+
+## 什么时候再完整构建
+
+日常小改不需要每次都完整构建。
+
+以下情况再运行完整构建或更重的检查：
+
+- 发布发行版前
+- 大范围改动目录结构前后
+- 修改 VitePress 配置、构建配置或依赖后
+- 修改侧边栏、路由、主题入口、CI 配置后
+- 部署前做最终确认时
+
+## 提交前建议
+
+提交前至少确认：
+
+    pnpm run quality:check
+    git diff --check
+    git status -sb
+    git diff --stat
+
+如果输出没有明显错误，再使用 VS Code 或其他 Git 工具提交。

package.json

@@ -33,7 +33,12 @@
     "docs:domain:check": "node scripts/check-site-domain.mjs",
     "docs:css:check": "node scripts/check-css-health.mjs",
     "quality:check": "node scripts/run-light-checks.mjs",
-    "ci": "node scripts/run-ci-checks.mjs"
+    "ci": "node scripts/run-ci-checks.mjs",
+    "docs:health:audit": "node scripts/audit-repo-health.mjs",
+    "docs:sync:clean": "node scripts/clean-sync-temp.mjs",
+    "docs:sync:clean:dry": "node scripts/clean-sync-temp.mjs --dry-run",
+    "docs:links:check:light": "node scripts/check-doc-links-light.mjs",
+    "docs:check:light": "pnpm run docs:ui:check && pnpm run docs:links:check:light && pnpm run docs:health:audit"
   },
   "name": "cysj-data",
   "version": "0.1.0",

scripts/audit-repo-health.mjs

@@ -0,0 +1,260 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const root = process.cwd();
+const reportPath = path.join(root, "docs/维护与报告/仓库健康巡检报告.md");
+
+const skipDirs = new Set([
+  ".git",
+  "node_modules",
+  "dist",
+  ".vite",
+  ".cache",
+  ".astro",
+]);
+
+const guardFiles = new Set([
+  "scripts/check-site-domain.mjs",
+  "scripts/check-doc-links-light.mjs",
+  "scripts/audit-repo-health.mjs",
+  "docs/维护与报告/仓库健康巡检报告.md",
+]);
+
+const textExts = new Set([
+  ".md",
+  ".mdx",
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".mts",
+  ".vue",
+  ".css",
+  ".json",
+  ".yml",
+  ".yaml",
+  ".txt",
+  ".html",
+]);
+
+const suspiciousPatterns = [
+  {
+    name: "绝对本地路径",
+    pattern: /[A-Z]:\\|\/storage\/emulated\/0|\/home\/|\/mnt\//i,
+  },
+  {
+    name: "旧域名",
+    pattern: /cysjdocs\.dpdns\.org|cysjdocs\.pages\.dev/i,
+  },
+  {
+    name: "疑似临时标记",
+    pattern: /TODO|FIXME|待处理|临时|占位|随便写|测试内容/i,
+  },
+  {
+    name: "冲突文件痕迹",
+    pattern: /sync-conflict|<<<<<<<|=======|>>>>>>>/i,
+  },
+];
+
+function rel(file) {
+  return path.relative(root, file).replaceAll("\\", "/");
+}
+
+function walk(dir, output = []) {
+  if (!fs.existsSync(dir)) return output;
+
+  for (const item of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, item.name);
+    const relative = rel(full);
+
+    if (item.isDirectory()) {
+      if (skipDirs.has(item.name)) continue;
+      if (relative.startsWith("docs/.vitepress/dist")) continue;
+
+      walk(full, output);
+      continue;
+    }
+
+    if (guardFiles.has(relative)) continue;
+
+    if (textExts.has(path.extname(item.name).toLowerCase())) {
+      output.push(full);
+    }
+  }
+
+  return output;
+}
+
+function read(file) {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+function getTitle(text) {
+  const frontmatterTitle = text.match(/^---[\s\S]*?\ntitle:\s*["']?(.+?)["']?\s*\n[\s\S]*?---/);
+  if (frontmatterTitle) return frontmatterTitle[1].trim();
+
+  const h1 = text.match(/^#\s+(.+)$/m);
+  if (h1) return h1[1].trim();
+
+  return "";
+}
+
+const files = walk(root);
+const mdFiles = files.filter((file) => path.extname(file).toLowerCase() === ".md");
+
+const stats = {
+  totalTextFiles: files.length,
+  totalMdFiles: mdFiles.length,
+  totalDocsFiles: mdFiles.filter((file) => rel(file).startsWith("docs/")).length,
+};
+
+const findings = [];
+const titleMap = new Map();
+const bigFiles = [];
+
+for (const file of files) {
+  const relative = rel(file);
+  const text = read(file);
+  const size = Buffer.byteLength(text, "utf8");
+
+  if (size > 80 * 1024) {
+    bigFiles.push({ file: relative, size });
+  }
+
+  for (const item of suspiciousPatterns) {
+    if (item.pattern.test(text)) {
+      findings.push({
+        level: item.name === "旧域名" || item.name === "冲突文件痕迹" ? "高" : "中",
+        file: relative,
+        issue: item.name,
+      });
+    }
+  }
+
+  if (relative.endsWith(".md") && relative.startsWith("docs/")) {
+    const title = getTitle(text);
+
+    if (!title) {
+      findings.push({
+        level: "中",
+        file: relative,
+        issue: "缺少可识别标题",
+      });
+    } else {
+      if (!titleMap.has(title)) titleMap.set(title, []);
+      titleMap.get(title).push(relative);
+    }
+
+    const h1Count = (text.match(/^#\s+/gm) || []).length;
+    if (h1Count > 1) {
+      findings.push({
+        level: "低",
+        file: relative,
+        issue: `存在 ${h1Count} 个一级标题`,
+      });
+    }
+
+    if (!/^---[\s\S]*?---/.test(text)) {
+      findings.push({
+        level: "中",
+        file: relative,
+        issue: "缺少 frontmatter",
+      });
+    }
+  }
+}
+
+for (const [title, list] of titleMap.entries()) {
+  if (list.length > 1) {
+    for (const file of list) {
+      findings.push({
+        level: "低",
+        file,
+        issue: `标题重复：${title}`,
+      });
+    }
+  }
+}
+
+bigFiles
+  .sort((a, b) => b.size - a.size)
+  .slice(0, 20)
+  .forEach((item) => {
+    findings.push({
+      level: item.size > 180 * 1024 ? "中" : "低",
+      file: item.file,
+      issue: `文件偏大：${Math.round(item.size / 1024)}KB`,
+    });
+  });
+
+const grouped = {
+  高: findings.filter((item) => item.level === "高"),
+  中: findings.filter((item) => item.level === "中"),
+  低: findings.filter((item) => item.level === "低"),
+};
+
+const now = new Date().toISOString();
+
+const lines = [
+  "---",
+  "title: 仓库健康巡检报告",
+  "description: 记录创游世界资料库的轻量巡检结果，用于发现旧域名、冲突文件、缺失标题、重复标题、过大文件和潜在维护问题。",
+  "created: 2026-06-08",
+  `updated: ${now.slice(0, 10)}`,
+  "search: false",
+  "---",
+  "",
+  "# 仓库健康巡检报告",
+  "",
+  `> 生成时间：${now}`,
+  "",
+  "## 巡检摘要",
+  "",
+  `- 文本文件数量：${stats.totalTextFiles}`,
+  `- Markdown 文件数量：${stats.totalMdFiles}`,
+  `- docs 文档数量：${stats.totalDocsFiles}`,
+  `- 高风险问题：${grouped["高"].length}`,
+  `- 中风险问题：${grouped["中"].length}`,
+  `- 低风险问题：${grouped["低"].length}`,
+  "",
+  "## 高风险问题",
+  "",
+  grouped["高"].length
+    ? grouped["高"].map((item) => `- \`${item.file}\`：${item.issue}`).join("\n")
+    : "- 暂无高风险问题。",
+  "",
+  "## 中风险问题",
+  "",
+  grouped["中"].length
+    ? grouped["中"].slice(0, 80).map((item) => `- \`${item.file}\`：${item.issue}`).join("\n")
+    : "- 暂无中风险问题。",
+  "",
+  "## 低风险问题",
+  "",
+  grouped["低"].length
+    ? grouped["低"].slice(0, 120).map((item) => `- \`${item.file}\`：${item.issue}`).join("\n")
+    : "- 暂无低风险问题。",
+  "",
+  "## 后续建议",
+  "",
+  "- 优先处理旧域名、冲突文件痕迹、缺少 frontmatter、缺少标题的问题。",
+  "- 重复标题不一定是错误，但建议检查是否存在内容重复或导航命名不清晰。",
+  "- 文件偏大不一定需要立刻拆分，但如果阅读体验下降，可以拆为专题页、索引页和细分页。",
+  "- 本报告只做轻量巡检，不会替代完整构建检查。",
+  "",
+];
+
+fs.mkdirSync(path.dirname(reportPath), { recursive: true });
+fs.writeFileSync(reportPath, lines.join("\n") + "\n", "utf8");
+
+console.log(`Repository health report generated: ${path.relative(root, reportPath)}`);
+
+if (grouped["高"].length > 0) {
+  console.error(`Found ${grouped["高"].length} high-risk issue(s).`);
+  process.exit(1);
+}