@code2rich/jpage 1.5.0

package/routes/users.js

@@ -0,0 +1,120 @@
+// 用户管理路由（仅 admin）。从 server.js 提取，行为保持不变。
+// 挂载点：/api/users
+
+const express = require('express');
+const bcrypt = require('bcryptjs');
+const { dbAll, dbGet, dbRun } = require('../lib/db');
+const { requireAuth, requireAdmin } = require('../lib/middleware/auth');
+const { clientIp } = require('../lib/util');
+const logger = require('../logger');
+
+const router = express.Router();
+
+router.get('/', requireAuth, requireAdmin, async (req, res) => {
+  try {
+    const users = await dbAll('SELECT id, username, email, email_verified, role, created_at FROM users ORDER BY id ASC');
+    res.json({ users: users.map(u => ({ ...u, emailVerified: !!u.email_verified })) });
+  } catch (e) {
+    res.status(500).json({ error: '获取用户列表失败' });
+  }
+});
+
+router.post('/', requireAuth, requireAdmin, async (req, res) => {
+  const { username, password, role, email } = req.body || {};
+  if (!username || !password) return res.status(400).json({ error: '用户名和密码不能为空' });
+  if (username.length > 30 || username.length < 2 || !/^[a-zA-Z0-9_]+$/.test(username)) {
+    return res.status(400).json({ error: '用户名 2-30 位，只能包含字母、数字和下划线' });
+  }
+  if (password.length < 8) return res.status(400).json({ error: '密码至少 8 位' });
+  if (!['admin', 'user'].includes(role || 'user')) return res.status(400).json({ error: '无效角色' });
+  if (email) {
+    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+    if (!emailRegex.test(email)) return res.status(400).json({ error: '邮箱格式不正确' });
+  }
+  try {
+    // 唯一性检查
+    if (email) {
+      const emailConflict = await dbGet('SELECT id FROM users WHERE email = ? OR username = ?', [email, email]);
+      if (emailConflict) return res.status(409).json({ error: '该邮箱已被使用' });
+    }
+    const nameConflict = await dbGet('SELECT id FROM users WHERE username = ?', [username]);
+    if (nameConflict) return res.status(409).json({ error: '用户名已存在' });
+
+    const hash = await bcrypt.hash(password, 10);
+    const result = await dbRun(
+      'INSERT INTO users (username, email, email_verified, password_hash, role) VALUES (?, ?, ?, ?, ?)',
+      [username, email || null, email ? 1 : 0, hash, role || 'user']
+    );
+    logger.audit('user.create', { userId: result.lastID, username, email, role: role || 'user', createdBy: req.userId, ip: clientIp(req) });
+    res.json({ id: result.lastID, username, email: email || null, role: role || 'user' });
+  } catch (e) {
+    if (e.message && e.message.includes('UNIQUE')) return res.status(400).json({ error: '用户名或邮箱已存在' });
+    res.status(500).json({ error: '创建用户失败' });
+  }
+});
+
+router.put('/:id', requireAuth, requireAdmin, async (req, res) => {
+  const targetId = parseInt(req.params.id);
+  if (isNaN(targetId)) return res.status(400).json({ error: '无效用户 ID' });
+  const { role, password, username, email } = req.body || {};
+  if (!role && !password && !username && email === undefined) return res.status(400).json({ error: '无更新字段' });
+  try {
+    const user = await dbGet('SELECT * FROM users WHERE id = ?', [targetId]);
+    if (!user) return res.status(404).json({ error: '用户不存在' });
+    if (username) {
+      if (username.length > 30 || username.length < 2 || !/^[a-zA-Z0-9_]+$/.test(username)) {
+        return res.status(400).json({ error: '用户名 2-30 位，只能包含字母、数字和下划线' });
+      }
+      const conflict = await dbGet('SELECT id FROM users WHERE username = ? AND id != ?', [username, targetId]);
+      if (conflict) return res.status(409).json({ error: '用户名已存在' });
+      await dbRun('UPDATE users SET username = ? WHERE id = ?', [username, targetId]);
+    }
+    if (email !== undefined) {
+      if (email) {
+        const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+        if (!emailRegex.test(email)) return res.status(400).json({ error: '邮箱格式不正确' });
+        const conflict = await dbGet('SELECT id FROM users WHERE (email = ? OR username = ?) AND id != ?', [email, email, targetId]);
+        if (conflict) return res.status(409).json({ error: '该邮箱已被使用' });
+        await dbRun('UPDATE users SET email = ?, email_verified = ? WHERE id = ?', [email, 1, targetId]);
+      } else {
+        await dbRun('UPDATE users SET email = NULL, email_verified = 0 WHERE id = ?', [targetId]);
+      }
+    }
+    if (role) {
+      if (!['admin', 'user'].includes(role)) return res.status(400).json({ error: '无效角色' });
+      await dbRun('UPDATE users SET role = ? WHERE id = ?', [role, targetId]);
+    }
+    if (password) {
+      if (password.length < 8) return res.status(400).json({ error: '密码至少 8 位' });
+      const hash = await bcrypt.hash(password, 10);
+      await dbRun('UPDATE users SET password_hash = ? WHERE id = ?', [hash, targetId]);
+    }
+    logger.audit('user.update', { targetUserId: targetId, changes: { role, username, email, password: !!password }, updatedBy: req.userId, ip: clientIp(req) });
+    res.json({ success: true });
+  } catch (e) {
+    res.status(500).json({ error: '更新用户失败' });
+  }
+});
+
+router.delete('/:id', requireAuth, requireAdmin, async (req, res) => {
+  const targetId = parseInt(req.params.id);
+  if (isNaN(targetId)) return res.status(400).json({ error: '无效用户 ID' });
+  if (targetId === req.userId) return res.status(400).json({ error: '不能删除自己' });
+  try {
+    const user = await dbGet('SELECT * FROM users WHERE id = ?', [targetId]);
+    if (!user) return res.status(404).json({ error: '用户不存在' });
+    // 将该用户的文件转交给第一个 admin
+    const admin = await dbGet("SELECT id FROM users WHERE role = 'admin' AND id != ? ORDER BY id ASC LIMIT 1", [targetId]);
+    if (admin) {
+      await dbRun('UPDATE files SET uploaded_by = ? WHERE uploaded_by = ?', [admin.id, targetId]);
+    }
+    // 删除用户（ON DELETE CASCADE 会清理 tokens）
+    await dbRun('DELETE FROM users WHERE id = ?', [targetId]);
+    logger.audit('user.delete', { targetUserId: targetId, username: user.username, deletedBy: req.userId, ip: clientIp(req) });
+    res.json({ success: true });
+  } catch (e) {
+    res.status(500).json({ error: '删除用户失败' });
+  }
+});
+
+module.exports = router;

package/server.js

@@ -0,0 +1,372 @@
+// 即页 jpage 服务端入口。
+// 仅负责：app 创建、中间件装配、路由挂载、MCP/静态/catch-all、全局错误处理、启动编排与关闭钩子。
+// 业务逻辑分布在 lib/（共享层）与 routes/（按域拆分的 Router）。
+
+const express = require('express');
+const path = require('path');
+const fs = require('fs');
+const crypto = require('crypto');
+const multer = require('multer');
+const session = require('express-session');
+const SQLiteStore = require('connect-sqlite3')(session);
+const bcrypt = require('bcryptjs');
+const helmet = require('helmet');
+const sqlite3 = require('sqlite3').verbose();
+const morgan = require('morgan');
+const cron = require('node-cron');
+
+const { runMigrations } = require('./migrations');
+const { setDb, dbGet, dbRun, configureDatabase } = require('./lib/db');
+const { DATA_DIR, UPLOAD_DIR } = require('./lib/paths');
+const { generateReadablePassword, currentUserId } = require('./lib/util');
+const { loadTemplates, loadTemplateNameMap } = require('./lib/templates');
+const { reloadCategoryNameCache } = require('./lib/categories');
+const { backfillFtsIndex } = require('./lib/fts');
+const { scheduleViewCountFlush, flushViewCounts, recordVisit } = require('./lib/view-counts');
+const { setAdminUserId } = require('./lib/auth-state');
+const { renderFile } = require('./lib/render');
+const { initMailer } = require('./mailer');
+const { mountMcpServer, closeMcpTransports } = require('./mcp-server');
+const logger = require('./logger');
+
+// 路由域
+const authRouter = require('./routes/auth');
+const usersRouter = require('./routes/users');
+const tokensRouter = require('./routes/tokens');
+const filesRouter = require('./routes/files');
+const tagsRouter = require('./routes/tags');
+const categoriesRouter = require('./routes/categories');
+const contentTemplatesRouter = require('./routes/content-templates');
+const adminRouter = require('./routes/admin');
+const skillsRouter = require('./routes/skills');
+
+const PORT = process.env.PORT || 8858;
+const NODE_ENV = process.env.NODE_ENV || 'development';
+const ALLOW_REGISTRATION = process.env.ALLOW_REGISTRATION === 'true';
+
+if (!fs.existsSync(DATA_DIR)) fs.mkdirSync(DATA_DIR, { recursive: true });
+if (!fs.existsSync(UPLOAD_DIR)) fs.mkdirSync(UPLOAD_DIR, { recursive: true });
+
+// 创建并注入数据库实例（lib/* 通过 require('./lib/db') 取同一实例）
+const db = new sqlite3.Database(path.join(DATA_DIR, 'database.sqlite'));
+setDb(db);
+
+// --- 会话密钥 ---
+let sessionSecret = process.env.SESSION_SECRET;
+let sessionSecretWarning = false;
+if (!sessionSecret) {
+  if (NODE_ENV === 'production') {
+    logger.error({ type: 'app', message: '生产模式下必须设置 SESSION_SECRET' });
+    process.exit(1);
+  }
+  sessionSecret = crypto.randomBytes(32).toString('hex');
+  sessionSecretWarning = true;
+}
+
+const app = express();
+app.set('trust proxy', 1);
+
+// helmet：关闭内置 CSP（由下方手写中间件 + render.js 分级下发），
+// 显式 frameguard=deny 与 CSP frame-ancestors 'none' 对齐，消除头冲突。
+// crossOriginEmbedderPolicy 关闭：渲染端点会加载用户内容（可能含未带 CORP 的子资源）。
+app.use(helmet({
+  contentSecurityPolicy: false,
+  crossOriginEmbedderPolicy: false,
+  frameguard: { action: 'deny' },
+}));
+
+// CSP 中间件：管理界面下发严格 APP_CSP；渲染端点（render/asset/短链）跳过，
+// 由 lib/render.js 的 renderFile 按内容类型分级下发 Markdown/HTML 策略。
+const { APP_CSP, isRenderPath } = require('./lib/csp');
+app.use((req, res, next) => {
+  if (isRenderPath(req.path)) return next();
+  res.setHeader('Content-Security-Policy', APP_CSP);
+  next();
+});
+
+// 全局 JSON 解析限制为 1MB；大 body（upload-json / upload-zip-base64）由端点级中间件放宽。
+app.use(express.json({ limit: '1mb' }));
+app.use(express.urlencoded({ extended: true, limit: '1mb' }));
+
+app.use((req, res, next) => {
+  res.header('Access-Control-Allow-Origin', req.headers.origin || '*');
+  res.header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
+  res.header('Access-Control-Allow-Headers', 'Origin, X-Requested-With, Content-Type, Accept');
+  if (req.method === 'OPTIONS') return res.sendStatus(200);
+  next();
+});
+
+app.use(session({
+  store: new SQLiteStore({ db: 'sessions.sqlite', dir: DATA_DIR }),
+  secret: sessionSecret,
+  resave: false,
+  saveUninitialized: false,
+  name: 'jpage.sid',
+  cookie: {
+    httpOnly: true,
+    sameSite: 'lax',
+    // HTTPS 部署应开启 secure，避免会话 cookie 被中间人嗅探。
+    // 显式通过 COOKIE_SECURE=true 开启；未设时保持 false 以兼容 HTTP 部署。
+    secure: process.env.COOKIE_SECURE === 'true',
+    maxAge: 7 * 24 * 60 * 60 * 1000
+  }
+}));
+
+// --- 结构化 HTTP 请求日志 ---
+morgan.token('user-id', (req) => req.userId || req.session?.userId || '-');
+morgan.token('ts', () => new Date().toISOString());
+app.use(morgan((tokens, req, res) => {
+  return JSON.stringify({
+    level: 'info',
+    type: 'http',
+    method: tokens.method(req, res),
+    url: tokens.url(req, res),
+    status: parseInt(tokens.status(req, res), 10),
+    contentLength: tokens.res(req, res, 'content-length') || 0,
+    responseTime: tokens['response-time'](req, res) + ' ms',
+    remoteAddr: tokens['remote-addr'](req, res),
+    userAgent: tokens['user-agent'](req, res),
+    referrer: tokens.referrer(req, res) || '',
+    userId: tokens['user-id'](req, res),
+    timestamp: tokens.ts(req, res),
+  });
+}, {
+  skip: (req) => req.path.startsWith('/vendor/') || /\.(css|js|map|png|ico|woff2?)$/i.test(req.path),
+}));
+
+const { version: PACKAGE_VERSION } = require('./package.json');
+
+// --- 健康检查 ---
+app.get('/health', async (req, res) => {
+  let dbOk = false;
+  let diskOk = false;
+  try { await dbGet('SELECT 1'); dbOk = true; } catch {}
+  try { diskOk = fs.existsSync(UPLOAD_DIR); } catch {}
+  const ok = dbOk && diskOk;
+  res.status(ok ? 200 : 503).json({
+    status: ok ? 'ok' : 'degraded',
+    db: dbOk,
+    disk: diskOk,
+    uptime: process.uptime(),
+    version: PACKAGE_VERSION
+  });
+});
+
+// --- 路由挂载 ---
+app.use('/api/auth', authRouter);
+app.use('/api/users', usersRouter);
+app.use('/api/tokens', tokensRouter);
+app.use('/api/files', filesRouter);
+app.use('/api/tags', tagsRouter);
+app.use('/api', categoriesRouter);       // /api/categories、/api/templates
+app.use('/api/content-templates', contentTemplatesRouter);
+app.use('/api/admin', adminRouter);
+app.use('/api', skillsRouter);            // /api/skills、/api/mcp/config
+
+// --- 短链（根路径，公开热点）---
+app.get('/s/:key', async (req, res) => {
+  try {
+    const file = await dbGet('SELECT * FROM files WHERE share_key = ?', [req.params.key]);
+    if (!file) return res.status(404).send('<!DOCTYPE html><html><head><meta charset="UTF-8"></head><body style="font-family:sans-serif;text-align:center;padding:4em"><h1>404</h1><p>页面不存在</p><a href="/">返回首页</a></body></html>');
+    if (!file.is_public && !currentUserId(req)) return res.redirect('/');
+    recordVisit(file, req).catch(() => {});
+    await renderFile(res, file);
+  } catch (e) {
+    res.status(500).json({ error: '渲染失败' });
+  }
+});
+
+// --- MCP 端点 ---
+async function authenticateMcpToken(tokenValue) {
+  // 旧 MCP_TOKEN
+  if (process.env.MCP_TOKEN && tokenValue === process.env.MCP_TOKEN) return true;
+  // 用户级 Token
+  const hash = crypto.createHash('sha256').update(tokenValue).digest('hex');
+  const row = await dbGet('SELECT id FROM tokens WHERE token_hash = ?', [hash]);
+  return !!row;
+}
+
+mountMcpServer(app, {
+  port: PORT,
+  mcpToken: process.env.MCP_TOKEN,
+  mcpIp: process.env.MCP_IP || 'localhost',
+  protocol: process.env.MCP_PROTOCOL || 'http',
+  authenticateRequest: authenticateMcpToken,
+});
+
+// --- 静态资源 ---
+const NODE_MODULES = path.join(__dirname, 'node_modules');
+// 静态资源长缓存：版本化路径（vendor 内容随包固定，public 资源带 ?v= 查询参数）
+// 30 天 + immutable，命中后浏览器零往返；首次加载仍走 ETag。
+const STATIC_OPTS = { maxAge: '30d', immutable: true, etag: true, lastModified: true };
+app.use('/vendor/katex', express.static(path.join(NODE_MODULES, 'katex', 'dist'), STATIC_OPTS));
+app.use('/vendor/highlight.js', express.static(path.join(NODE_MODULES, 'highlight.js'), STATIC_OPTS));
+app.use('/vendor/mermaid', express.static(path.join(NODE_MODULES, 'mermaid', 'dist'), STATIC_OPTS));
+
+// index:false —— 不让 static 自动把 / 映射到 index.html（由下方 catch-all 注入哈希资源路径后返回）
+app.use(express.static(path.join(__dirname, 'public'), { ...STATIC_OPTS, index: false }));
+
+// --- SPA 兜底：返回 index.html，注入打包后的带哈希资源路径（若已 build）---
+const INDEX_HTML_PATH = path.join(__dirname, 'public', 'index.html');
+const DIST_MANIFEST_PATH = path.join(__dirname, 'public', 'dist', 'manifest.json');
+let _indexHtmlCache = { html: null, manifestMtime: 0, manifest: null };
+function getIndexHtml() {
+  let manifest = null, manifestMtime = 0;
+  try {
+    const st = fs.statSync(DIST_MANIFEST_PATH);
+    manifestMtime = st.mtimeMs;
+    if (_indexHtmlCache.html && _indexHtmlCache.manifestMtime === manifestMtime) {
+      return _indexHtmlCache.html; // manifest 未变，用缓存
+    }
+    manifest = JSON.parse(fs.readFileSync(DIST_MANIFEST_PATH, 'utf8'));
+  } catch {
+    // 无构建产物 → 返回源 index.html（引用源文件 /css、/js）
+    if (_indexHtmlCache.html && !_indexHtmlCache.manifest) return _indexHtmlCache.html;
+    const html = fs.readFileSync(INDEX_HTML_PATH, 'utf8');
+    _indexHtmlCache = { html, manifestMtime: 0, manifest: null };
+    return html;
+  }
+  // 注入哈希路径
+  let html = fs.readFileSync(INDEX_HTML_PATH, 'utf8');
+  if (manifest['style.css']) {
+    html = html.replace(/\/css\/style\.css\?v=[\d.]+/g, '/dist/' + manifest['style.css']);
+  }
+  if (manifest['app.js']) {
+    html = html.replace(/\/js\/app\.js\?v=[\d.]+/g, '/dist/' + manifest['app.js']);
+  }
+  _indexHtmlCache = { html, manifestMtime, manifest };
+  return html;
+}
+
+app.get('*', (req, res) => {
+  res.setHeader('Content-Type', 'text/html; charset=utf-8');
+  res.send(getIndexHtml());
+});
+
+// --- 全局错误处理 ---
+app.use((err, req, res, next) => {
+  logger.error({ type: 'app', message: err.message, stack: err.stack });
+  if (err instanceof multer.MulterError) {
+    if (err.code === 'LIMIT_FILE_SIZE') return res.status(400).json({ error: '文件大小超过50MB限制' });
+    return res.status(400).json({ error: err.message });
+  }
+  res.status(500).json({ error: err.message || '服务器内部错误' });
+});
+
+// --- 初始管理员引导 ---
+async function bootstrapAdmin() {
+  let adminUser = process.env.ADMIN_USER;
+  const explicitPass = process.env.ADMIN_PASSWORD;
+  try {
+    const row = await dbGet('SELECT COUNT(*) AS c FROM users');
+    if (row.c > 0) return;
+
+    if (!adminUser) adminUser = 'admin';
+
+    let adminPass;
+    if (explicitPass) {
+      if (explicitPass.length < 8) {
+        logger.warn({ type: 'app', message: 'ADMIN_PASSWORD 长度不足 8 位，跳过自动创建' });
+        logger.warn({ type: 'app', message: '解决方式：设置为 ≥8 位的强密码，或留空以自动生成' });
+        return;
+      }
+      adminPass = explicitPass;
+    } else {
+      adminPass = generateReadablePassword(16);
+    }
+
+    const hash = await bcrypt.hash(adminPass, 10);
+    await dbRun('INSERT INTO users (username, password_hash, role) VALUES (?, ?, ?)', [adminUser, hash, 'admin']);
+    logger.info({ type: 'app', message: '已创建初始管理员', username: adminUser });
+    if (!explicitPass) {
+      logger.info({ type: 'app', message: '初始密码', password: adminPass, sensitive: true });
+      logger.info({ type: 'app', message: '首次登录后请立即修改密码' });
+    }
+  } catch (e) {
+    logger.error({ type: 'app', message: '初始化管理员失败', error: e.message });
+  }
+}
+
+// --- 启动 ---
+// 初始化数据库与缓存（启动和测试都需要）；listen 仅在直接运行时执行。
+async function initApp() {
+  await configureDatabase();
+  await runMigrations(db);
+  initMailer();
+  loadTemplates();
+  await loadTemplateNameMap();
+  await reloadCategoryNameCache();
+  await backfillFtsIndex();
+  await bootstrapAdmin();
+  let adminUserId = null;
+  try {
+    const row = await dbGet('SELECT id FROM users ORDER BY id ASC LIMIT 1');
+    if (row) adminUserId = row.id;
+  } catch (e) {
+    logger.error({ type: 'app', message: '解析 admin user id 失败', error: e.message });
+  }
+  setAdminUserId(adminUserId);
+  scheduleViewCountFlush();
+  return adminUserId;
+}
+
+if (require.main === module) {
+  app.listen(PORT, async () => {
+    const mcpIp = process.env.MCP_IP || 'localhost';
+    const adminUserId = await initApp();
+    logger.info({ type: 'app', message: '服务已启动', url: `http://${mcpIp}:${PORT}`, registration: ALLOW_REGISTRATION ? 'open' : 'closed' });
+    if (sessionSecretWarning) logger.warn({ type: 'app', message: 'SESSION_SECRET 未设置，已生成临时密钥（重启后会话会失效）' });
+
+    // 自动定时备份
+    const backupCron = process.env.BACKUP_CRON;
+    if (backupCron) {
+      const { createBackupArchive } = adminRouter;
+      const backupDir = process.env.BACKUP_DIR || path.join(DATA_DIR, 'backups');
+      if (!fs.existsSync(backupDir)) fs.mkdirSync(backupDir, { recursive: true });
+      if (cron.validate(backupCron)) {
+        cron.schedule(backupCron, () => {
+          try {
+            const ts = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+            const fname = `jpage-backup-${ts}.zip`;
+            const fpath = path.join(backupDir, fname);
+            const output = fs.createWriteStream(fpath);
+            const archive = createBackupArchive();
+            output.on('close', () => {
+              logger.info({ type: 'app', message: '自动备份完成', file: fpath });
+              const backups = fs.readdirSync(backupDir)
+                .filter(f => f.startsWith('jpage-backup-') && f.endsWith('.zip'))
+                .sort();
+              while (backups.length > 7) {
+                fs.unlinkSync(path.join(backupDir, backups.shift()));
+              }
+            });
+            archive.pipe(output);
+            archive.finalize();
+          } catch (e) {
+            logger.error({ type: 'app', message: '自动备份失败', error: e.message });
+          }
+        });
+        logger.info({ type: 'app', message: '自动备份已启用', cron: backupCron, dir: backupDir });
+      } else {
+        logger.warn({ type: 'app', message: 'BACKUP_CRON 格式无效', cron: backupCron });
+      }
+    }
+    if (process.env.MCP_TOKEN && !adminUserId) {
+      logger.warn({ type: 'app', message: 'MCP_TOKEN 已设置但 users 表为空，MCP 端点将禁用' });
+    } else if (process.env.MCP_TOKEN && adminUserId) {
+      logger.info({ type: 'app', message: 'MCP 端点已启用', url: `http://${mcpIp}:${PORT}/mcp` });
+    }
+  });
+
+  for (const sig of ['SIGINT', 'SIGTERM']) {
+    process.on(sig, async () => {
+      logger.info({ type: 'app', message: `收到 ${sig}，正在关闭 MCP transport` });
+      await flushViewCounts(); // 关闭前回写缓冲的 view_count，避免丢失
+      await closeMcpTransports();
+      process.exit(0);
+    });
+  }
+}
+
+// 导出供集成测试使用（require 时不 listen）
+module.exports = { app, db, initApp };

package/skills/jpage-content-template/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: jpage-content-template
+description: 当用户要生成 HTML/Markdown 内容时，先从模板市场查找风格样例，参照样例的风格生成新内容。适用于用户要求生成页面、报告、仪表板等，且希望有特定风格参考的场景。
+---
+
+# 核心规则
+
+当用户要求生成 HTML 或 Markdown 内容时，先判断是否需要风格参考。如果用户指定了风格或类型（如「仪表板」「报告」「深色风格」），先查询模板市场获取样例。
+
+# 触发场景
+
+- 用户说「参照模板生成…」「用模板风格生成…」
+- 用户要求生成特定类型的内容（仪表板、报告、简历等）
+- 用户提到具体风格关键词（深色、极简、科技感等）
+- 用户说「从模板市场找一个…」
+- 用户要求生成美观的页面但未指定具体样式
+
+# 工作流
+
+## 场景一：用户指定模板或风格
+
+用户明确要求参照某个模板或某种风格。
+
+```
+1. 调 list_content_templates 查询模板市场
+   - 如果用户指定了场景类型（如「仪表板」），设置 scene 参数
+   - 如果用户指定了风格关键词，设置 keyword 参数
+2. 向用户展示匹配的模板列表（标题、场景、描述）
+3. 用户选择一个模板后，调 get_content_template(id=选择的模板id) 获取完整样例
+4. 学习样例的以下特征：
+   - 整体布局结构（header/main/footer/sidebar 等区域划分）
+   - 色彩方案（主色、辅色、背景色、文字色）
+   - 排版风格（字体大小、间距、对齐方式）
+   - 交互元素（按钮样式、卡片样式、表格样式）
+   - 使用的 CSS 技术（Grid/Flexbox/absolute 等）
+   - 特殊效果（渐变、阴影、动画等）
+5. 根据用户的具体内容需求，生成风格一致但内容全新的 HTML/Markdown
+6. 调 upload_file 上传到即页，返回预览链接
+```
+
+## 场景二：自动推荐模板
+
+用户没有指定模板，但要求生成特定类型的内容。
+
+```
+1. 根据用户需求判断可能的场景类型
+2. 调 list_content_templates(scene=场景类型, sort="use_count", limit=3)
+3. 如果有匹配模板，向用户推荐：
+   「我找到了几个相关模板，是否参照某个模板的风格？还是直接生成？」
+4. 用户选择后，按场景一的流程继续
+5. 如果用户选择直接生成，则不使用模板，正常生成
+```
+
+## 场景三：上传样例到模板市场
+
+用户有一段好看的 HTML/Markdown，想保存为模板供以后参考。
+
+```
+1. 调 POST /api/content-templates 上传模板
+   - title: 模板名称
+   - content: 完整的 HTML/Markdown 内容
+   - scene: 使用场景（dashboard/report/resume/landing/note/other）
+   - description: 风格描述
+   - styleTags: 风格标签（逗号分隔）
+   - fileType: html 或 markdown
+2. 告知用户模板已上传到市场
+```
+
+# 场景与关键词对照
+
+| 用户可能说的 | scene 参数 |
+|---|---|
+| 仪表板、数据看板、Dashboard、监控面板 | dashboard |
+| 报告、周报、月报、分析报告 | report |
+| 简历、CV、名片、个人主页 | resume |
+| 落地页、Landing Page、产品页、活动页 | landing |
+| 笔记、文档、会议纪要、技术文档 | note |
+| 卡片、海报、Banner、封面 | card |
+| 演示、PPT、幻灯片 | presentation |
+| 邮件、Email、Newsletter | email |
+| 其他未分类 | other |
+
+# 风格学习原则
+
+AI 拿到样例后应学习的维度（按优先级）：
+
+1. **布局结构** — 区域划分、内容组织方式
+2. **色彩方案** — 主色调、配色关系
+3. **字体排版** — 字号层级、行间距、字重
+4. **组件样式** — 卡片、按钮、表格、图表容器
+5. **视觉装饰** — 圆角、阴影、渐变、边框
+
+**重要**：学习风格，不复制内容。生成的必须是全新的原创内容，仅保持视觉风格一致。
+
+# MCP 工具
+
+- `list_content_templates` — 查询模板列表（支持 scene/keyword/fileType 筛选）
+- `get_content_template` — 获取模板完整内容（自动记录使用次数）