draftgo-cli 3.0.1 → 3.0.29

package/src/projectMap.js

@@ -2,6 +2,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const parse5 = require('parse5');
 
 function exists(p) {
   try { fs.accessSync(p); return true; } catch { return false; }
@@ -60,20 +61,52 @@ function itemFile(projectDir, section, item) {
 function extractRoutes(html) {
   const routes = new Set();
   if (!html) return routes;
-  const patterns = [
-    /\bdata-page-route\s*=\s*["']([^"']+)["']/gi,
-    /\bhref\s*=\s*["']([^"']+)["']/gi,
-  ];
-  for (const re of patterns) {
-    let m;
-    while ((m = re.exec(html))) {
-      const route = normalizeRoute(m[1]);
-      if (route) routes.add(route);
-    }
+  let document;
+  try {
+    document = parse5.parse(html);
+  } catch {
+    return routes;
   }
+  const visit = (node) => {
+    for (const attr of node.attrs || []) {
+      if (attr.name === 'href' || attr.name === 'data-page-route') {
+        const route = normalizeRoute(attr.value);
+        if (route) routes.add(route);
+      }
+      if (attr.name.startsWith('on')) {
+        const re = /\b(?:App\.)?(?:navigate|go|openPage)\s*\(\s*["']([^"']+)["']/g;
+        let match;
+        while ((match = re.exec(attr.value))) {
+          const route = normalizeRoute(match[1]);
+          if (route) routes.add(route);
+        }
+      }
+    }
+    for (const child of node.childNodes || []) visit(child);
+  };
+  visit(document);
   return routes;
 }
 
+function extractScriptBindings(code) {
+  const bindings = { routes: [], events: [], schedules: [] };
+  if (!code) return bindings;
+  let match;
+  const routeRe = /@route\(\s*["']([A-Za-z]+)\s+([^"']+)["']\s*\)/g;
+  while ((match = routeRe.exec(code))) bindings.routes.push(`${match[1].toUpperCase()} ${match[2]}`);
+  const eventRe = /@on\(\s*["']([^"']+)["']\s*\)/g;
+  while ((match = eventRe.exec(code))) bindings.events.push(match[1]);
+  const scheduledRe = /@scheduled\(\s*["']([^"']+)["']\s*\)/g;
+  while ((match = scheduledRe.exec(code))) bindings.schedules.push(match[1]);
+  const goRouteRe = /\.Route\(\s*["']([A-Za-z]+)["']\s*,\s*["']([^"']+)["']/g;
+  while ((match = goRouteRe.exec(code))) bindings.routes.push(`${match[1].toUpperCase()} ${match[2]}`);
+  const goEventRe = /\.On\(\s*["']([^"']+)["']/g;
+  while ((match = goEventRe.exec(code))) bindings.events.push(match[1]);
+  const goScheduleRe = /\.Schedule\(\s*["']([^"']+)["']/g;
+  while ((match = goScheduleRe.exec(code))) bindings.schedules.push(match[1]);
+  return bindings;
+}
+
 function pageKey(page) {
   if (page && page.id != null) return `page:${page.id}`;
   return `page:${normalizeRoute(page && page.route) || page && page.title || 'new'}`;
@@ -86,6 +119,42 @@ function addRouteRefs(refs, route, source) {
   refs.get(clean).add(source);
 }
 
+function classifyPageArea(item) {
+  const route = normalizeRoute(item && item.route);
+  const title = String((item && item.title) || '');
+  const tag = String((item && item.tag) || '');
+  const text = `${route} ${title} ${tag}`;
+
+  if (!route) return 'unknown';
+  if (route === '/' || /(^|[\s/])(home|index|首页|主页)([\s/]|$)/i.test(text)) return 'home';
+  if (/^\/(login|setup|install|register)(\/|$)/i.test(route) || /(系统|内置|平台配置|基础配置)/.test(text)) return 'system';
+  if (/^\/admin(\/|$)/i.test(route) || /(管理|后台|运营|审核|权限|控制台|配置)/.test(text)) return 'admin';
+  if (/(业务|内容|案例|产品|新闻|订单|客户|会员|课程|活动|资料|下载|预约|表单|详情|列表|列表页|工作台|中心|门户|商城|服务)/.test(text)) return 'business';
+  return 'unknown';
+}
+
+function normalizeHtmlSkeleton(html) {
+  if (!html) return '';
+  let out = html;
+  out = out.replace(/<!--([\s\S]*?)-->/g, '');
+  out = out.replace(/<script\b[\s\S]*?<\/script>/gi, '<script></script>');
+  out = out.replace(/<style\b[\s\S]*?<\/style>/gi, '<style></style>');
+  out = out.replace(/\b(data-page-route|href|id|for|aria-label|aria-labelledby|aria-describedby|title|value|name|placeholder)\s*=\s*("[^"]*"|'[^']*')/gi, '$1=""');
+  out = out.replace(/\b(class|style)\s*=\s*("[^"]*"|'[^']*')/gi, '$1=""');
+  out = out.replace(/>[^<]*</g, '><');
+  out = out.replace(/\s+/g, ' ');
+  return out.trim();
+}
+
+function collectPageGroups(pages) {
+  const groups = { home: [], admin: [], business: [], system: [], unknown: [] };
+  for (const page of pages) {
+    const key = groups[page.area] ? page.area : 'unknown';
+    groups[key].push(page);
+  }
+  return groups;
+}
+
 function summarizePage(projectDir, item) {
   const file = itemFile(projectDir, 'pages', item);
   return {
@@ -95,6 +164,7 @@ function summarizePage(projectDir, item) {
     permission: item.permission || null,
     tag: item.tag || '',
     html_file: file,
+    area: classifyPageArea(item),
   };
 }
 
@@ -198,19 +268,6 @@ function summarizeAIHub(item) {
   return base;
 }
 
-function summarizeExternalAPI(item) {
-  return {
-    id: item.id,
-    code: item.code || '',
-    name: item.name || '',
-    method: item.method || 'GET',
-    path: item.path || '',
-    base_url: item.base_url || '',
-    status: item.status,
-    tags: Array.isArray(item.tags) ? item.tags : [],
-  };
-}
-
 function summarizeDoc(item) {
   return {
     id: item.id,
@@ -250,7 +307,6 @@ function buildProjectMap(projectDir) {
     db_meta: readJsonSafe(projectDir, '.draftgo/db_meta/index.json'),
     custom_scripts: readJsonSafe(projectDir, '.draftgo/custom_scripts/index.json'),
     aihub: readJsonSafe(projectDir, '.draftgo/aihub/index.json'),
-    external_apis: readJsonSafe(projectDir, '.draftgo/external_apis/index.json'),
     docs: readJsonSafe(projectDir, '.draftgo/docs/articles/index.json'),
     doc_categories: readJsonSafe(projectDir, '.draftgo/doc_categories/index.json'),
     system_config: readJsonSafe(projectDir, '.draftgo/system_config/index.json'),
@@ -261,6 +317,7 @@ function buildProjectMap(projectDir) {
   const pages = indexes.pages.items.map((p) => summarizePage(projectDir, p));
   const navigations = indexes.navigations.items.map((n) => summarizeNav(projectDir, n));
   const routeRefs = new Map();
+  const pageGroups = collectPageGroups(pages);
 
   for (const nav of navigations) {
     const html = nav.html_file ? readTextSafe(relToAbs(projectDir, nav.html_file)) : '';
@@ -283,25 +340,135 @@ function buildProjectMap(projectDir) {
       label: m.label || '',
       fields: m.schema && m.schema.properties ? Object.keys(m.schema.properties) : [],
     })),
-    custom_scripts: indexes.custom_scripts.items.map((s) => ({
-      id: s.id,
-      name: s.name || '',
-      slug: s.slug || '',
-      mode: s.mode || '',
-      status: s.status,
-      code_file: itemFile(projectDir, 'custom_scripts', s),
-    })),
+    custom_scripts: indexes.custom_scripts.items.map((s) => {
+      const codeFile = itemFile(projectDir, 'custom_scripts', s);
+      const bindings = extractScriptBindings(codeFile ? readTextSafe(relToAbs(projectDir, codeFile)) : '');
+      return {
+        id: s.id,
+        name: s.name || '',
+        slug: s.slug || '',
+        mode: s.mode || '',
+        status: s.status,
+        code_file: codeFile,
+        routes: bindings.routes,
+        events: bindings.events,
+        schedules: bindings.schedules,
+      };
+    }),
     aihub: indexes.aihub.items.map(summarizeAIHub),
-    external_apis: indexes.external_apis.items.map(summarizeExternalAPI),
     docs: indexes.docs.items.map(summarizeDoc),
     doc_categories: indexes.doc_categories.items.map(summarizeDocCategory),
     system_config: indexes.system_config.items.map(summarizeSystemConfig),
     roles: indexes.roles.items.map((r) => ({ id: r.id, code: r.code || '', name: r.name || '', status: r.status })),
     users_count: indexes.users.items.length,
+    pageGroups,
     routeRefs: Object.fromEntries([...routeRefs.entries()].map(([route, sources]) => [route, [...sources]])),
   };
 }
 
+function htmlParseErrors(html) {
+  const errors = [];
+  const ignored = new Set(['missing-doctype']);
+  try {
+    parse5.parse(html, {
+      onParseError(error) {
+        if (ignored.has(error.code)) return;
+        errors.push({
+          code: error.code || 'html-parse-error',
+          line: error.startLine || null,
+          column: error.startCol || null,
+        });
+      },
+    });
+  } catch (error) {
+    errors.push({ code: error.message || 'html-parse-error', line: null, column: null });
+  }
+  return errors;
+}
+
+function extractStyleText(html) {
+  const parts = [];
+  if (!html) return '';
+
+  const styleAttr = /\bstyle\s*=\s*(["'])([\s\S]*?)\1/gi;
+  let m;
+  while ((m = styleAttr.exec(html))) parts.push(m[2]);
+
+  const styleBlock = /<style\b[^>]*>([\s\S]*?)<\/style>/gi;
+  while ((m = styleBlock.exec(html))) parts.push(m[1]);
+
+  return parts.join('\n');
+}
+
+function maskDgVarFunctions(css) {
+  let out = '';
+  for (let i = 0; i < css.length; i += 1) {
+    const rest = css.slice(i).toLowerCase();
+    const fnStart = rest.startsWith('var(') ? 'var(' : rest.startsWith('color-mix(') ? 'color-mix(' : null;
+    if (!fnStart) {
+      out += css[i];
+      continue;
+    }
+
+    let j = i + fnStart.length;
+    let depth = 1;
+    while (j < css.length && depth > 0) {
+      if (css[j] === '(') depth += 1;
+      else if (css[j] === ')') depth -= 1;
+      j += 1;
+    }
+
+    const fn = css.slice(i, j);
+    if (/^var\(\s*--dg-/i.test(fn) || /^color-mix\([\s\S]*var\(\s*--dg-/i.test(fn)) {
+      out += ' '.repeat(fn.length);
+    }
+    else out += fn;
+    i = j - 1;
+  }
+  return out;
+}
+
+function hasHardcodedColor(css) {
+  const masked = maskDgVarFunctions(css);
+  return /#[0-9a-f]{3,8}\b/i.test(masked)
+    || /\b(?:rgb|rgba|hsl|hsla|color-mix)\s*\(/i.test(masked);
+}
+
+function hasDarkThemeCoverage(html) {
+  return /\[data-theme\s*=\s*["']dark["']\]/i.test(html)
+    || /\[data-theme\s*~=\s*["']dark["']\]/i.test(html)
+    || /\bdata-theme\s*=\s*["']dark["']/i.test(html);
+}
+
+function reportColorThemeRisk(label, html, addWarning) {
+  const css = extractStyleText(html);
+  if (!css || !hasHardcodedColor(css)) return;
+  if (hasDarkThemeCoverage(html)) return;
+  addWarning('DG-COLOR-001', 'low', `${label} 发现硬编码配色且未看到深色主题覆盖；优先使用系统 var(--dg-*) token，自主配色需兼容浅色与深色。`);
+}
+
+function collectOrphanFiles(projectDir, relDir, indexRel, fileField, prefix, exts) {
+  const dir = path.join(projectDir, relDir);
+  if (!exists(dir)) return [];
+  const index = readJsonSafe(projectDir, indexRel);
+  const indexed = new Set(index.items.map((it) => String(it[fileField] || '').replace(/\\/g, '/')));
+  return fs.readdirSync(dir)
+    .filter((name) => name.startsWith(`${prefix}_`) && exts.includes(path.extname(name)))
+    .map((name) => path.join(relDir, name).replace(/\\/g, '/'))
+    .filter((rel) => !indexed.has(rel));
+}
+
+function reportPaginationHack(label, html, addWarning) {
+  if (/\bApp\.get\s*\(\s*['"]db\/[^'"]+['"]\s*,\s*\{[\s\S]{0,240}\bpage_size\s*:\s*9999\b/i.test(html)) {
+    addWarning('DG-DATA-001', 'high', `${label} 使用 page_size: 9999 拉取 DB 数据；DraftGo 规范是不传 page/page_size 即返回全量。`);
+  }
+}
+
+function needsAdminCompanion(page) {
+  const text = `${page.route || ''} ${page.title || ''} ${page.tag || ''}`;
+  return /(案例|产品|新闻|订单|客户|会员|课程|活动|资料|下载|预约|表单|内容|招聘|发布|审核|上下架|商城)/.test(text);
+}
+
 function isProbablySystemPage(page) {
   const tag = String(page.tag || '');
   const title = String(page.title || '');
@@ -313,7 +480,13 @@ function analyzeProject(projectDir) {
   const map = buildProjectMap(projectDir);
   const errors = [];
   const warnings = [];
+  const warningDetails = [];
+  const addWarning = (code, confidence, message) => {
+    warnings.push(message);
+    warningDetails.push({ code, confidence, message });
+  };
   const routeSeen = new Map();
+  const signatureSeen = new Map();
 
   if (!exists(path.join(projectDir, '.draftgo'))) {
     errors.push('未找到 .draftgo/，请先运行 draftgo init 或 draftgo connect。');
@@ -322,7 +495,7 @@ function analyzeProject(projectDir) {
   for (const page of map.pages) {
     const label = `${page.title || '未命名页面'}${page.id != null ? `#${page.id}` : ''}`;
     if (!page.route) errors.push(`${label} 缺少 route。`);
-    if (!page.title) warnings.push(`${label} 缺少 title。`);
+    if (!page.title) addWarning('DG-PAGE-001', 'high', `${label} 缺少 title。`);
     if (!page.html_file) errors.push(`${label} 找不到 html_file 或 page_${page.id}_*.html。`);
 
     if (page.route) {
@@ -337,7 +510,7 @@ function analyzeProject(projectDir) {
         const own = pageKey(page);
         const externalRefs = refs.filter((s) => s !== own);
         if (externalRefs.length === 0) {
-          warnings.push(`${label} (${page.route}) 未在导航、首页或其他页面入口中发现绑定引用。`);
+          addWarning('DG-ROUTE-001', 'medium', `${label} (${page.route}) 未在导航、首页或其他页面入口中发现绑定引用。`);
         }
       }
     }
@@ -345,19 +518,80 @@ function analyzeProject(projectDir) {
     if (page.html_file) {
       const html = readTextSafe(relToAbs(projectDir, page.html_file));
       if (/\b(mockData|demoData|fakeData|sampleData|staticData)\b/i.test(html)) {
-        warnings.push(`${label} 疑似包含 mock/demo/fake/staticData，确认是否为用户明确要求的静态/demo。`);
+        addWarning('DG-MOCK-001', 'medium', `${label} 疑似包含 mock/demo/fake/staticData，确认是否为用户明确要求的静态/demo。`);
       }
       if (/\b(onclick|addEventListener)\b[\s\S]{0,120}\b(toast|alert)\b/i.test(html) && !/\b(App\.(post|put|delete|get)|fetch\s*\()/i.test(html)) {
-        warnings.push(`${label} 疑似只有反馈提示、缺少真实数据读写或 API 调用。`);
+        addWarning('DG-CLOSURE-001', 'medium', `${label} 疑似只有反馈提示、缺少真实数据读写或 API 调用。`);
+      }
+      reportPaginationHack(label, html, addWarning);
+      reportColorThemeRisk(label, html, addWarning);
+      const signature = normalizeHtmlSkeleton(html);
+      if (signature) {
+        if (!signatureSeen.has(signature)) signatureSeen.set(signature, []);
+        signatureSeen.get(signature).push({ label, area: page.area });
+      }
+      const parseErrors = htmlParseErrors(html);
+      for (const parseError of parseErrors.slice(0, 5)) {
+        const at = parseError.line ? `（行 ${parseError.line}${parseError.column ? `:${parseError.column}` : ''}）` : '';
+        addWarning('DG-HTML-001', 'high', `${label} HTML 解析提醒：${parseError.code}${at}。`);
       }
     }
   }
 
+  const adminCount = map.pageGroups.admin.length;
+  const maintainableBusinessPages = map.pageGroups.business.filter(needsAdminCompanion);
+  if (maintainableBusinessPages.length > 0 && adminCount === 0) {
+    addWarning(
+      'DG-ADMIN-001',
+      'medium',
+      `检测到 ${maintainableBusinessPages.length} 个具有可维护内容信号的业务页面，但未发现管理端页面；若内容需要运营维护，建议补管理端页面或明确说明不需要。`,
+    );
+  }
+
+  for (const labels of signatureSeen.values()) {
+    const nonSystem = labels.filter((item) => item.area !== 'system');
+    if (nonSystem.length < 3) continue;
+    addWarning(
+      'DG-DUPLICATE-001',
+      'low',
+      `发现 ${nonSystem.length} 个结构几乎一致的页面，疑似工作台副本：${nonSystem.map((item) => item.label).join('、')}。建议复刻内置导航/侧栏后按业务差异拆分，不要整页复制。`,
+    );
+    break;
+  }
+
+  for (const nav of map.navigations) {
+    if (!nav.html_file) continue;
+    const navLabel = `导航${nav.name || nav.code || nav.id || ''}`;
+    const html = readTextSafe(relToAbs(projectDir, nav.html_file));
+    reportColorThemeRisk(navLabel, html, addWarning);
+  }
+
+  const orphanGroups = [
+    ['页面', '.draftgo/pages', '.draftgo/pages/index.json', 'html_file', 'page', ['.html']],
+    ['导航', '.draftgo/navigations', '.draftgo/navigations/index.json', 'html_file', 'nav', ['.html']],
+    ['文档', '.draftgo/docs/articles', '.draftgo/docs/articles/index.json', 'content_file', 'article', ['.html', '.md']],
+    ['自定义脚本', '.draftgo/custom_scripts', '.draftgo/custom_scripts/index.json', 'code_file', 'script', ['.py', '.js', '.ts', '.sh', '.go', '.txt']],
+  ];
+  for (const [label, relDir, indexRel, fileField, prefix, exts] of orphanGroups) {
+    const orphans = collectOrphanFiles(projectDir, relDir, indexRel, fileField, prefix, exts);
+    if (orphans.length) {
+      addWarning('DG-ORPHAN-001', 'high', `${label}目录存在 ${orphans.length} 个未登记到 index.json 的文件：${orphans.slice(0, 5).join('、')}。push 不会上传这些文件。`);
+    }
+  }
+
+  for (const script of map.custom_scripts) {
+    if (String(script.mode || '').toLowerCase() !== 'route' || !script.code_file) continue;
+    const code = readTextSafe(relToAbs(projectDir, script.code_file));
+    if (/\bdef\s+handle\s*\(/.test(code) && !/@route\s*\(/.test(code)) {
+      errors.push(`自定义脚本${script.name || script.slug || script.id}#${script.id} 是 route 模式但只有 handle()，缺少 @route("METHOD /path") 注册，HTTP 端点不会命中。`);
+    }
+  }
+
   if (map.pages.length === 0 && exists(path.join(projectDir, '.draftgo'))) {
-    warnings.push('未发现 pages/index.json 页面缓存；开发前建议先拉取页面。');
+    addWarning('DG-CACHE-001', 'low', '未发现 pages/index.json 页面缓存；开发前建议先拉取页面。');
   }
 
-  return { map, errors, warnings };
+  return { map, errors, warnings, warningDetails };
 }
 
 module.exports = {
@@ -365,4 +599,5 @@ module.exports = {
   analyzeProject,
   normalizeRoute,
   extractRoutes,
+  extractScriptBindings,
 };

package/src/skill.js

@@ -2,14 +2,14 @@
 
 // Per-platform skill renderer.
 //
-// For every AI-tool target (see src/platforms.js) we render a self-contained
-// copy of the skill body into that tool's own directory. No more shared
-// .draftgo/skill/ indirection — each AI tool can read the real content
-// natively, which dramatically improves command compliance.
+// For every AI-tool target (see src/platforms.js) we render the complete
+// instruction body into that tool's own directory. The large OpenAPI snapshot
+// is shared once under .draftgo/skill-shared to avoid redundant copies.
 //
 // Templating in .md files:
 //   {{SKILL_DIR}}     → platform's project-relative skill dir (forward slashes)
 //   {{SKILL_SCRIPTS}} → {{SKILL_DIR}}/scripts
+//   {{SKILL_SHARED}}  → .draftgo/skill-shared
 
 const path = require('path');
 const fs = require('fs');
@@ -21,6 +21,8 @@ const {
 } = require('./fsx');
 
 const SKILL_SOURCE_DIR = path.join(RESOURCES_DIR, 'skill');
+const SHARED_RESOURCE_DIR = path.join('.draftgo', 'skill-shared');
+const SHARED_FILES = new Set(['quickref/api.json']);
 
 function getPackageVersion() {
   try {
@@ -54,12 +56,32 @@ function renderFrontmatter(fm) {
   return lines.join('\n');
 }
 
+function splitFrontmatter(text) {
+  const normalized = String(text || '').replace(/\r\n/g, '\n');
+  if (!normalized.startsWith('---\n')) return { frontmatter: {}, body: normalized };
+  const end = normalized.indexOf('\n---\n', 4);
+  if (end < 0) return { frontmatter: {}, body: normalized };
+  const frontmatter = {};
+  for (const line of normalized.slice(4, end).split('\n')) {
+    const colon = line.indexOf(':');
+    if (colon <= 0) continue;
+    const key = line.slice(0, colon).trim();
+    let value = line.slice(colon + 1).trim();
+    if (value.startsWith('"') && value.endsWith('"')) {
+      value = value.slice(1, -1).replace(/\\"/g, '"');
+    }
+    frontmatter[key] = value;
+  }
+  return { frontmatter, body: normalized.slice(end + 5) };
+}
+
 function substitute(text, platform) {
   const skillDir = platform.skillDir;
   const scriptsDir = `${skillDir}/scripts`;
   return text
     .replace(/\{\{SKILL_DIR\}\}/g, skillDir)
-    .replace(/\{\{SKILL_SCRIPTS\}\}/g, scriptsDir);
+    .replace(/\{\{SKILL_SCRIPTS\}\}/g, scriptsDir)
+    .replace(/\{\{SKILL_SHARED\}\}/g, SHARED_RESOURCE_DIR.replace(/\\/g, '/'));
 }
 
 function walk(root, onFile) {
@@ -76,27 +98,51 @@ function renderInto(destDir, platform) {
   const srcRoot = SKILL_SOURCE_DIR;
   walk(srcRoot, (absSrc) => {
     const rel = path.relative(srcRoot, absSrc);
+    if (SHARED_FILES.has(rel.replace(/\\/g, '/'))) return;
     const absDst = path.join(destDir, rel);
     ensureDir(path.dirname(absDst));
     if (absSrc.endsWith('.md')) {
       let body = readText(absSrc);
-      body = substitute(body, platform);
       if (rel === 'SKILL.md') {
-        body = renderFrontmatter(platform.frontmatter) + body;
+        const parsed = splitFrontmatter(body);
+        body = renderFrontmatter({ ...(platform.frontmatter || {}), ...parsed.frontmatter }) + parsed.body;
       }
+      body = substitute(body, platform);
       writeText(absDst, body);
     } else {
       copyFile(absSrc, absDst);
     }
   });
 
-  // Some platforms expect the entry file at a different path/name than
-  // SKILL.md (e.g. copilot's .github/prompts/draftgo.prompt.md, cursor's
-  // .cursor/commands/draftgo.md). For those, mirror the rendered SKILL.md
-  // to the platform's mainFile if it differs.
-  const projectMain = path.join(path.dirname(destDir), '..'); // not used
-  // We render into <project>/<assetDir>; mainFile lives at <project>/<mainFile>.
-  // The renderer caller (installPlatform) handles cross-file copy.
+}
+
+function ensureSharedResources(projectDir) {
+  const sharedRoot = path.join(projectDir, SHARED_RESOURCE_DIR);
+  for (const rel of SHARED_FILES) {
+    const src = path.join(SKILL_SOURCE_DIR, rel);
+    const dest = path.join(sharedRoot, rel);
+    if (exists(dest)) {
+      const sourceStat = fs.statSync(src);
+      const destStat = fs.statSync(dest);
+      if (sourceStat.size === destStat.size && destStat.mtimeMs >= sourceStat.mtimeMs) continue;
+    }
+    copyFile(src, dest);
+  }
+  return sharedRoot;
+}
+
+function validateRenderedSkill(assetDir) {
+  const main = path.join(assetDir, 'SKILL.md');
+  if (!exists(main)) throw new Error('渲染结果缺少 SKILL.md');
+  const text = readText(main);
+  const firstEnd = text.indexOf('\n---\n', 4);
+  const body = firstEnd >= 0 ? text.slice(firstEnd + 5) : '';
+  if (!text.startsWith('---\n') || firstEnd < 0 || body.startsWith('---\n')) {
+    throw new Error('SKILL.md frontmatter 必须且只能有一个');
+  }
+  if (/\{\{(?:SKILL_DIR|SKILL_SCRIPTS|SKILL_SHARED)\}\}/.test(text)) {
+    throw new Error('SKILL.md 仍包含未替换占位符');
+  }
 }
 
 function ensureRuntime(projectDir) {
@@ -111,9 +157,10 @@ function ensureRuntime(projectDir) {
   }
   appendGitignoreLine(projectDir, '.draftgo/config.json');
   appendGitignoreLine(projectDir, '.draftgo/token');
+  ensureSharedResources(projectDir);
 }
 
-function installPlatform(projectDir, platform /*, { force } */) {
+function installPlatform(projectDir, platform, opts = {}) {
   if (!exists(SKILL_SOURCE_DIR)) {
     throw new Error(
       `Skill source missing: ${SKILL_SOURCE_DIR}. The CLI package may be broken.`
@@ -121,24 +168,59 @@ function installPlatform(projectDir, platform /*, { force } */) {
   }
   const destAsset = path.join(projectDir, platform.assetDir);
   const destMain  = path.join(projectDir, platform.mainFile);
-
-  // Clean install so removed sub-skills/scripts don't linger.
-  if (exists(destAsset)) removePath(destAsset);
-  // If mainFile lives outside assetDir, clean it too.
-  if (path.relative(destAsset, destMain).startsWith('..')) {
-    if (exists(destMain)) removePath(destMain);
+  const mainOutsideAsset = path.relative(destAsset, destMain).startsWith('..');
+  if ((exists(destAsset) || exists(destMain)) && !opts.force) {
+    return { path: platform.mainFile, skipped: true };
   }
 
-  renderInto(destAsset, platform);
+  ensureSharedResources(projectDir);
+  const token = `${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+  const stageAsset = `${destAsset}.tmp-${token}`;
+  const backupAsset = `${destAsset}.bak-${token}`;
+  const stageMain = mainOutsideAsset ? `${destMain}.tmp-${token}` : null;
+  const backupMain = mainOutsideAsset ? `${destMain}.bak-${token}` : null;
+  let assetBackedUp = false;
+  let mainBackedUp = false;
+  let assetInstalled = false;
+  let mainInstalled = false;
+
+  try {
+    renderInto(stageAsset, platform);
+    validateRenderedSkill(stageAsset);
+    if (mainOutsideAsset) copyFile(path.join(stageAsset, 'SKILL.md'), stageMain);
 
-  // If mainFile is not at <assetDir>/SKILL.md, mirror the rendered SKILL.md
-  // to the platform's mainFile path (e.g. copilot prompt file, cursor cmd md).
-  const renderedMain = path.join(destAsset, 'SKILL.md');
-  if (path.resolve(renderedMain) !== path.resolve(destMain)) {
-    ensureDir(path.dirname(destMain));
-    copyFile(renderedMain, destMain);
+    ensureDir(path.dirname(destAsset));
+    if (exists(destAsset)) {
+      fs.renameSync(destAsset, backupAsset);
+      assetBackedUp = true;
+    }
+    if (mainOutsideAsset && exists(destMain)) {
+      ensureDir(path.dirname(destMain));
+      fs.renameSync(destMain, backupMain);
+      mainBackedUp = true;
+    }
+
+    fs.renameSync(stageAsset, destAsset);
+    assetInstalled = true;
+    if (mainOutsideAsset) {
+      fs.renameSync(stageMain, destMain);
+      mainInstalled = true;
+    }
+  } catch (err) {
+    if (mainInstalled && exists(destMain)) removePath(destMain);
+    if (assetInstalled && exists(destAsset)) removePath(destAsset);
+    if (mainBackedUp && exists(backupMain)) fs.renameSync(backupMain, destMain);
+    if (assetBackedUp && exists(backupAsset)) fs.renameSync(backupAsset, destAsset);
+    throw err;
+  } finally {
+    if (exists(stageAsset)) removePath(stageAsset);
+    if (stageMain && exists(stageMain)) removePath(stageMain);
   }
 
+  if (exists(backupAsset)) removePath(backupAsset);
+  if (backupMain && exists(backupMain)) removePath(backupMain);
+  if (!exists(destMain)) throw new Error(`安装后缺少入口文件：${platform.mainFile}`);
+
   return { path: platform.mainFile };
 }
 
@@ -163,7 +245,7 @@ function installAll(projectDir, platforms, opts = {}) {
   for (const p of platforms) {
     results.push({ platform: p, result: installPlatform(projectDir, p, opts) });
   }
-  writeInstalledVersion(projectDir);
+  if (results.every((item) => !item.result.skipped)) writeInstalledVersion(projectDir);
   return results;
 }
 
@@ -177,4 +259,6 @@ module.exports = {
   statusPlatform,
   installAll,
   ensureRuntime,
+  ensureSharedResources,
+  splitFrontmatter,
 };