Portfolio Flow

PortfolioFlow Skill

把一句话，变成设计师的完整作品集网站。

PortfolioFlow 是面向5 大设计领域（景观 / 平面 / 室内 / 工业 / UX）的作品集 建站 Skill。用户用一句中文或英文描述需求，本 Skill 自动生成：

• 完整作品集前台站（Hero + 作品网格 + 详情页 + 关于 + AI 助手对话框）
• 设计师管理后台（登录 + 作品 CRUD + AI 生成介绍 + 统计看板）
• 主题色自定义（5 套预设主题 + 用户传入 hex 自由组合）
• Edge Functions / KV / Middleware / JWT 鉴权全栈能力

最终通过 edgeone-pages-deploy 一键部署到 EdgeOne Pages。

---

触发后的执行流程（决策树）

收到符合本 Skill 触发条件的用户请求后，按以下顺序执行：

Step 1 — 收集必填信息

如果用户描述中缺少以下任意字段，向用户一次性追问（不要反复问）：

追问示例：

我需要确认几个关键信息：

1. 你的设计领域是什么？（景观/平面/室内/工业/UX）

2. 设计师姓名？

3. 主题方案？（暗夜森林/晨曦米色/深海蓝调/暖阳橙红/纯白极简，或者直接给一个 hex 颜色）

Step 2 — 决定项目结构

view 以下参考文件之一，根据用户领域加载对应的内容套路：

• 景观 / 室内 / 工业 → references/portfolio-knowledge.md 中的对应章节
• 平面 / UX → 同上

Step 3 — 生成项目骨架

在 /tmp/portfolio-{slug}/ 下创建以下文件（禁止使用 cd 进入路径包含特殊字符的目录，所有 路径都用绝对路径或 ~/Desktop/ 下的干净路径）：

portfolio-{slug}/
├── index.html              # 前台首页（用 templates/index.html 模板）
├── portfolio-detail.html   # 作品详情
├── admin.html              # 管理后台
├── login.html              # 登录页
├── assets/                 # 图片素材（用户上传或占位图）
├── functions/
│   ├── api/
│   │   ├── auth.js         # 登录鉴权 + JWT 签发（参考 references/auth-jwt.md）
│   │   ├── portfolios.js   # 作品 CRUD（参考 references/portfolio-crud.md）
│   │   ├── generate.js     # AI 生成介绍（参考 references/ai-generate.md）
│   │   └── stats.js        # 访问统计（参考 references/stats-kv.md）
│   └── _middleware.js      # JWT 校验 + CORS
└── README.md

Step 4 — 主题色注入

用户选定的主题方案需要同时注入到：

• index.html 的 <style> 中的 CSS 变量
• admin.html 的同位置
• login.html 的同位置

5 套预设主题的具体 CSS 变量值见 references/design-system.md。

如果用户传入 hex 颜色（如 #FF6B6B），按 references/design-system.md 中"hex 转完整主题"的算法生成配套色阶。

Step 5 — 调用部署 Skill

完成所有文件生成后，调用 edgeone-pages-deploy Skill 执行部署：

触发短语：deploy this portfolio to EdgeOne Pages
项目目录：~/Desktop/portfolio-{slug}/

部署成功后，必须：

1. 在 EdgeOne Pages 控制台引导用户绑定以下 KV 命名空间（手动一次性操作）：

• 变量名 PORTFOLIO_USERS ← 用户账号库
• 变量名 PORTFOLIO_WORKS ← 作品库
• 变量名 PORTFOLIO_STATS ← 访问统计
• 重要：变量名必须严格匹配，KV 绑定后在 Edge Function 中作为全局变量

访问，而非 env.PORTFOLIO_WORKS（这是 EdgeOne Pages 的特殊规范）。 2. 重新部署一次让 KV 绑定生效。 3. 返回访问 URL + 默认管理员账号密码（首次部署时自动写入 KV）。

---

路由表（references/ 按需加载）

下表帮助 AI 决定何时打开哪份 reference：

---

核心约束（必须遵守）

1. 绝不依赖外部 API Key——默认模式下所有功能（包括 AI 生成）必须零配置可跑。 references/ai-generate.md 描述了可选的 DeepSeek 增强模式，但不是默认行为。

2. 绝不写入用户路径含特殊字符的目录——优先使用 ~/Desktop/ 下不含 × ' " / 的干净路径。

3. 图片字段不做 `startsWith('http')` 兜底判断——直接信任传入的 img 字段， 本地 /assets/xxx.jpg 和远程 https://... 都要原样使用。

4. JWT secret 不硬编码在代码里——从 EdgeOne Pages 环境变量 JWT_SECRET 读取，部署后引导用户在控制台手动设置。

5. 首次部署完成后必须返回：

• 公开访问 URL
• 控制台链接
• 默认管理员账号（提示首次登录后立即修改密码）

---

可选增强（用户明确要求时启用）

---

反例：不应触发本 Skill 的请求

• "做一个景观项目展示站"（指特定项目站，不是设计师作品集） → 使用 landscapeflow Prompt
• "做一个落地页 / SaaS / 电商网站" → 不属于作品集场景
• "把我现有的简历改成网页" → 是简历不是作品集
• 单纯的"AI 生成一段作品介绍"（不建站） → 不需要建站 Skill

---

输出契约

执行完成后，向用户输出以下结构化结果：

✅ PortfolioFlow 作品集已就绪

🌐 访问 URL: https://portfolio-{slug}.edgeone.cool
🔐 管理后台: https://portfolio-{slug}.edgeone.cool/admin
   - 默认账号: admin@portfolio.local
   - 默认密码: PortfolioFlow_{随机6位}
   - ⚠️ 首次登录后请立即修改密码

📊 已部署能力:
   ✅ 前台作品集首页（{N} 个示例作品）
   ✅ 作品详情页
   ✅ 管理后台（登录 / CRUD / AI 生成）
   ✅ Edge Functions × 4
   ✅ KV Storage × 3
   ✅ JWT 鉴权 + CORS Middleware

🎨 当前主题: {主题名称}
📁 项目目录: {本地路径}

下一步建议:
1. 登录后台添加你的真实作品
2. 上传头像和封面图到 /assets/
3. 修改 footer 中的版权和联系方式

AI Generate — 作品介绍生成（双引擎）

何时加载本文件：用户的请求涉及 AI 生成作品介绍、自动写文案、智能填写描述、生成项目说明、AI 助手回答访客提问等。

>

核心设计：双引擎架构 —— 默认用"模板拼接 + 领域词库随机组合"，零依赖可跑；可选接 DeepSeek 真 LLM 作为增强模式。

---

一、双引擎架构

用户在 admin 后台点"AI 生成介绍"
  ↓
POST /api/generate { field, projectName, type, style, role, area, duration, goal }
  ↓
generate.js 路由：
  ├─ 检查 env DEEPSEEK_API_KEY 是否存在？
  │   ├─ 存在 → 尝试调用 DeepSeek（30 秒超时）
  │   │         ├─ 成功 → 返回 { source: 'ai', content: ... }
  │   │         └─ 失败 → 静默降级到模板引擎
  │   └─ 不存在 → 直接走模板引擎
  ↓
模板引擎：
  1. 加载对应领域的词库（portfolio-knowledge.md）
  2. pick() 随机抽取短语
  3. 拼接成结构化项目说明
  4. 返回 { source: 'template', content: ... }

---

二、完整代码

functions/api/generate.js

/**
 * Portfolio AI Generate API
 *
 * 路由：
 *   POST /api/generate
 *   {
 *     field: 'landscape' | 'graphic' | 'interior' | 'industrial' | 'ux',
 *     projectName: string,
 *     type: string,         // 项目类型，如 '社区公园'
 *     style?: string,       // 风格，如 '自然生态'
 *     role?: string,
 *     area?: string,
 *     duration?: string,
 *     goal?: string,
 *     mode?: 'template' | 'ai' | 'auto'   // 默认 auto
 *   }
 *
 *   返回：
 *   {
 *     ok: true,
 *     source: 'template' | 'ai',
 *     content: '生成的项目说明文本',
 *     warnings?: ['AI 调用失败，已降级到模板引擎']
 *   }
 */

// === 领域词库（5 个领域） ===

const KNOWLEDGE = {
  landscape: {
    intros: [
      '让设计回到土地与人居',
      '用最少的介入实现最丰富的体验',
      '在城市与自然之间编织新的对话',
      '为每一片土地写一封情书',
      '以场地的方式重新思考场地',
      '让风、水、光、植物，一起参与设计',
      '用景观回应城市的真实问题',
    ],
    styles: {
      '现代简约': ['极简几何线条', '强调功能与形式统一', '材料的克制运用', '尺度感的精准把握'],
      '自然生态': ['尊重场地原生肌理', '低介入设计哲学', '本土植物为骨架', '生境网络的细致编织'],
      '古典中式': ['移步换景的空间序列', '借景与框景的传统手法', '诗意栖居的当代诠释'],
      '工业复古': ['场地工业记忆的保留', '钢铁与植物的对话', '锈蚀美学的当代运用'],
      '北方风格': ['抵御冬季严寒的微气候策略', '常绿植物为骨架的全季视效', '雪景作为设计要素'],
      '南方风格': ['雨水管理与海绵理念', '亚热带植物的层次表达', '通风遮阳的气候适应'],
    },
    strategies: [
      '以人群行为为驱动重组功能分区，强化亲子、运动、静憩三类活动的边界与互动',
      '引入微气候调节策略，通过乔木阵列、水体降温、铺装透水提升场地全年舒适度',
      '植物配置遵循季相主题原则，确保四季皆有视觉焦点',
      '材料选型立足耐久性与本土性，重点回应当地气候对工艺的特殊要求',
      '强化无障碍系统，确保老人、儿童、残障人士都能平等使用',
      '引入雨水管理体系，将场地变为城市海绵基础设施的一部分',
    ],
    closes: [
      '让设计回到土地与人居',
      '用最少的介入实现最丰富的体验',
      '为这座城市留下一处可以呼吸的空间',
    ],
  },
  
  graphic: {
    intros: [
      '用视觉讲一个值得记住的故事',
      '设计是信息与情感的精准翻译',
      '让品牌成为可被识别的态度',
      '在二维空间里造一个有重量的世界',
      '字体、色彩、构图——每一寸都是表达',
    ],
    styles: {
      '极简主义': ['留白即设计', '字体的极致运用', '色彩的克制选择'],
      '复古印刷': ['网点、油墨与做旧', '老式排版的当代演绎', '手作质感的数字模拟'],
      '现代几何': ['模数化的网格系统', '色块与几何的构成游戏', '欧洲瑞士风格的当代延续'],
      '潮流插画': ['手绘的人格化表达', '渐变与噪点的当代审美', '社交媒体友好的视觉语言'],
      '日式美学': ['和风留白与季节感', '汉字与假名的层次美', '极简但充满情绪'],
    },
    strategies: [
      '从品牌核心价值出发反向定义视觉系统',
      '建立可延展的视觉语言库，确保品牌在不同载体上保持一致',
      '色彩与字体的双轴并行实验，找到最符合品牌气质的组合',
      '考虑印刷工艺与数字呈现的双向适配',
      '为品牌建立"声音"——视觉之外的语言风格统一',
    ],
    closes: [
      '让设计成为品牌最沉默也最有力的代言',
      '用克制的视觉表达最深的态度',
      '为不被看见的设计争取一秒注意力',
    ],
  },
  
  interior: {
    intros: [
      '空间是生活的容器，也是情绪的容器',
      '用材料、光线、尺度，雕刻日常',
      '让每个角落都值得驻足',
      '从生活方式出发，反向定义空间',
    ],
    styles: {
      '现代简约': ['白墙木地板的克制', '隐藏式收纳的极致', '少而精的家具陈设'],
      '日式侘寂': ['原木与亚麻的质感对话', '不完美中的完整', '光影作为材料的一部分'],
      '北欧风格': ['浅色木材与白墙的温暖', '功能主义家具', '自然光的充分利用'],
      '工业风': ['裸露的混凝土与钢架', '皮革与金属的搭配', '空间的开放感'],
      '新中式': ['传统纹样的当代转化', '深色硬木与素色软装', '禅意空间的现代演绎'],
      '法式优雅': ['线条与曲线的雕刻感', '香槟金与浅木色', '生活仪式感的强调'],
    },
    strategies: [
      '从居住者的真实生活动线出发重新组织空间序列',
      '以光线为隐藏的设计元素，避免任何区域出现死角',
      '材料选择优先考虑耐久与触感，远胜短期视觉效果',
      '家具与陈设遵循"减一件原则"——能拿走的都拿走',
      '收纳系统隐入墙体，让生活物品有归宿',
    ],
    closes: [
      '把好生活，安进具体的房间',
      '让空间为居住者讲一个温柔的故事',
      '相信空间会改变住在里面的人',
    ],
  },
  
  industrial: {
    intros: [
      '产品是问题的回答，不是形式的炫技',
      '好的设计让人忘记设计本身',
      '为日常物品争取一点诗意',
      '从功能出发，止于形式之美',
    ],
    styles: {
      'Dieter Rams 极简': ['Less, but better', '功能优先于装饰', '色彩与材料的诚实表达'],
      '日式人文': ['物哀美学的当代演绎', '触感与温度的考究', '使用习惯的细腻洞察'],
      '北欧温暖': ['天然材料的运用', '柔和的几何形态', '生活方式产品的定位'],
      '硬核工业': ['结构外显的诚实美学', '金属与机械感', '高性能产品定位'],
      '生活美学': ['日常物品的提升', '材料与工艺的讲究', '可持续设计理念'],
    },
    strategies: [
      '深入用户使用场景，找出当前产品中最反人性的细节',
      'CMF 在草图阶段就介入，确保最终成品的质感符合设计意图',
      '与工程团队同步迭代，保证设计可制造',
      '考虑全生命周期，包含包装、运输、回收',
      '用最少的零件实现最丰富的功能',
    ],
    closes: [
      '用毫米计的克制，做更人性的产品',
      '让产品成为生活里安静的好朋友',
      '相信形式追随用户的真实需求',
    ],
  },
  
  ux: {
    intros: [
      '为复杂的系统设计简单的入口',
      '让每一次点击都有理由',
      '好的体验是看不见的体验',
      '设计是与用户的一场长期对话',
    ],
    styles: {
      '极简清爽': ['白底大留白', '排版优先于装饰', '色彩仅作功能区分'],
      '玻璃拟态': ['毛玻璃与透明分层', '柔和的高光与阴影', '深色背景的科技感'],
      '新拟物': ['软阴影与凸起感', '现实物体的数字隐喻', '触感丰富'],
      '科技深色': ['深色底 + 高对比', '荧光色点缀', '数据可视化友好'],
      'Apple 风格': ['SF 字体与系统色彩', '极致的对齐与间距', '动效的克制运用'],
    },
    strategies: [
      '从用户研究出发建立清晰的人物画像和场景地图',
      '信息架构先于视觉，避免在错误的骨架上做漂亮的皮肤',
      '原型阶段做可用性测试，让真实用户走一遍',
      '建立设计系统，让所有页面共享同一套视觉语言',
      'A/B 实验驱动关键决策，数据与直觉并重',
    ],
    closes: [
      '让产品成为用户的延伸，而不是阻碍',
      '在数据与情感之间寻找平衡',
      '为每一个被服务的用户感到值得',
    ],
  },
};

// === 工具函数 ===

function pick(arr) {
  if (!Array.isArray(arr) || arr.length === 0) return '';
  return arr[Math.floor(Math.random() * arr.length)];
}

function pickN(arr, n) {
  if (!Array.isArray(arr) || arr.length === 0) return [];
  const shuffled = [...arr].sort(() => Math.random() - 0.5);
  return shuffled.slice(0, Math.min(n, arr.length));
}

// === 模板引擎 ===

function generateFromTemplate({ field, projectName, type, style, role, area, duration, goal }) {
  const lib = KNOWLEDGE[field] || KNOWLEDGE.landscape;  // 兜底用景观
  
  const intro = pick(lib.intros);
  const styleDescs = lib.styles[style] || lib.styles[Object.keys(lib.styles)[0]];
  const styleDesc = pickN(styleDescs, 2).join('，');
  const strategies = pickN(lib.strategies, 4);
  const close = pick(lib.closes);
  
  const areaPart = area ? `，规划/服务规模约 ${area}` : '';
  const rolePart = role ? `，我担任 ${role}` : '';
  const durationPart = duration ? `，历时 ${duration}` : '';
  const goalPart = goal || '在功能、美学、可持续性三个维度找到平衡';
  
  return `【项目概况】
${projectName} 是一个 ${type} 项目${areaPart}${rolePart}${durationPart}。

【设计立意】
${intro}。本项目采用 ${style || '当代'} 的设计语言，注重${styleDesc}。

【设计目标】
本项目的核心目标是：${goalPart}。围绕这一目标，方案在多个维度展开系统性思考。

【设计策略】
${strategies.map((s, i) => `${['其一', '其二', '其三', '其四'][i]}，${s}。`).join('\n')}

【设计立意延展】
${close}。

— 由 PortfolioFlow 生成`;
}

// === DeepSeek 引擎（可选）===

async function generateFromDeepSeek(data, apiKey) {
  const { field, projectName, type, style, role, area, duration, goal } = data;
  
  const fieldNameMap = {
    landscape: '景观设计',
    graphic: '平面设计',
    interior: '室内设计',
    industrial: '工业设计',
    ux: 'UX/UI 设计',
  };
  
  const prompt = `你是一位资深的${fieldNameMap[field] || '设计'}从业者，请为下面这个作品写一段约 300 字的专业项目说明。

要求：
- 分为【项目概况】【设计立意】【设计目标】【设计策略】【创新点】五个段落
- 语言专业但有人味，避免空洞的大词
- 不要使用 emoji
- 末尾不要加签名

作品信息：
- 项目名称：${projectName}
- 项目类型：${type}
- 设计风格：${style || '未指定'}
- 我的角色：${role || '未指定'}
- 项目规模：${area || '未指定'}
- 项目时长：${duration || '未指定'}
- 核心目标：${goal || '未指定'}

请直接输出项目说明文本，不要任何前后说明。`;
  
  const response = await fetch('https://api.deepseek.com/chat/completions', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${apiKey}`,
    },
    body: JSON.stringify({
      model: 'deepseek-chat',
      messages: [{ role: 'user', content: prompt }],
      max_tokens: 800,
      temperature: 0.7,
    }),
    signal: AbortSignal.timeout(30000),  // 30 秒超时
  });
  
  if (!response.ok) {
    throw new Error(`DeepSeek API returned ${response.status}`);
  }
  
  const data2 = await response.json();
  const content = data2.choices?.[0]?.message?.content;
  if (!content) throw new Error('Empty response from DeepSeek');
  
  return content.trim() + '\n\n— 由 PortfolioFlow + DeepSeek 协作生成';
}

// === 主路由 ===

export async function onRequest({ request }) {
  if (request.method !== 'POST') {
    return jsonResponse({ error: 'Method not allowed' }, 405);
  }
  
  let body;
  try { body = await request.json(); } catch {
    return jsonResponse({ error: 'Invalid JSON' }, 400);
  }
  
  // 校验
  if (!body.field || !body.projectName || !body.type) {
    return jsonResponse({ error: 'field, projectName, type are required' }, 400);
  }
  
  const mode = body.mode || 'auto';
  const apiKey = typeof DEEPSEEK_API_KEY !== 'undefined' ? DEEPSEEK_API_KEY : null;
  const warnings = [];
  
  // 用户明确要求模板
  if (mode === 'template') {
    return jsonResponse({
      ok: true,
      source: 'template',
      content: generateFromTemplate(body),
    });
  }
  
  // 用户明确要求 AI 但没配 key
  if (mode === 'ai' && !apiKey) {
    return jsonResponse({
      error: 'DeepSeek API key not configured. Add DEEPSEEK_API_KEY in EdgeOne Pages environment variables.',
      hint: 'Or use mode=template to use the built-in template engine.',
    }, 400);
  }
  
  // auto 模式：有 key 优先 AI，失败降级
  if (apiKey) {
    try {
      const aiContent = await generateFromDeepSeek(body, apiKey);
      return jsonResponse({
        ok: true,
        source: 'ai',
        content: aiContent,
      });
    } catch (err) {
      warnings.push(`AI generation failed: ${err.message}. Falling back to template engine.`);
    }
  }
  
  // 降级到模板
  return jsonResponse({
    ok: true,
    source: 'template',
    content: generateFromTemplate(body),
    warnings: warnings.length ? warnings : undefined,
  });
}

function jsonResponse(data, status = 200) {
  return new Response(JSON.stringify(data), {
    status,
    headers: { 'Content-Type': 'application/json; charset=utf-8' },
  });
}

---

三、前端调用（admin.html）

// 在作品编辑表单里，点"AI 生成介绍"按钮触发
async function generateDescription() {
  const form = document.getElementById('work-form');
  const btn = document.getElementById('btn-ai-generate');
  const targetField = document.getElementById('description');
  
  btn.disabled = true;
  btn.textContent = '✨ 生成中...';
  
  try {
    const res = await fetch('/api/generate', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      credentials: 'same-origin',
      body: JSON.stringify({
        field: form.field.value,
        projectName: form.title.value,
        type: form.type.value,
        style: form.style.value,
        role: form.role.value,
        area: form.area.value,
        duration: form.duration.value,
        goal: form.goal.value,
      }),
    });
    const data = await res.json();
    
    if (!res.ok) {
      alert('生成失败：' + data.error);
      return;
    }
    
    // 打字机效果展示
    targetField.value = '';
    let i = 0;
    const text = data.content;
    const timer = setInterval(() => {
      if (i >= text.length) {
        clearInterval(timer);
        btn.disabled = false;
        btn.textContent = '✨ AI 生成介绍';
        // 显示来源
        const badge = document.getElementById('ai-source-badge');
        badge.textContent = data.source === 'ai' ? '🤖 由 DeepSeek 生成' : '✍️ 由模板引擎生成';
        badge.style.display = 'inline-block';
        return;
      }
      targetField.value += text[i];
      i++;
    }, 20);
  } catch (err) {
    alert('网络错误：' + err.message);
    btn.disabled = false;
    btn.textContent = '✨ AI 生成介绍';
  }
}

---

四、可选：访客 AI 助手对话框

前台首页右下角浮动一个"问问关于这个设计师"对话框，提升网站互动感。

functions/api/assistant.js（独立 Edge Function）

// 简化版：根据当前作品集数据，回答访客的简单问题
export async function onRequest({ request }) {
  if (request.method !== 'POST') {
    return new Response(JSON.stringify({ error: 'Method not allowed' }), { status: 405 });
  }
  
  const { question } = await request.json();
  if (!question) {
    return new Response(JSON.stringify({ error: 'question required' }), { status: 400 });
  }
  
  // 取当前所有公开作品作为上下文
  const indexRaw = (typeof PORTFOLIO_WORKS !== 'undefined')
    ? await PORTFOLIO_WORKS.get('index:all', 'json')
    : [];
  const slugs = (indexRaw || []).slice(0, 20);
  const works = await Promise.all(slugs.map(s => 
    PORTFOLIO_WORKS.get(`work:${s}`, 'json')
  ));
  const validWorks = works.filter(Boolean);
  
  const apiKey = typeof DEEPSEEK_API_KEY !== 'undefined' ? DEEPSEEK_API_KEY : null;
  
  if (apiKey) {
    // 真 LLM
    return await answerWithAI(question, validWorks, apiKey);
  }
  
  // 规则引擎兜底
  return answerWithRules(question, validWorks);
}

function answerWithRules(question, works) {
  const q = question.toLowerCase();
  
  let answer;
  if (q.includes('多少') || q.includes('几个') || q.includes('total')) {
    answer = `我目前发布了 ${works.length} 个作品。`;
  } else if (q.includes('擅长') || q.includes('好') || q.includes('best')) {
    const types = [...new Set(works.map(w => w.type))];
    answer = `从作品看，我主要在 ${types.slice(0, 3).join('、')} 等领域有较多实践。`;
  } else if (q.includes('最新') || q.includes('latest')) {
    const latest = works[0];
    answer = latest ? `最新作品是「${latest.title}」（${latest.year}）。` : '暂无作品。';
  } else if (q.includes('联系') || q.includes('contact')) {
    answer = '欢迎通过页面底部的联系方式与我沟通。';
  } else {
    answer = `感谢提问。这个问题可能需要更具体的描述，建议直接查看作品集了解我的设计风格，或通过联系方式深入交流。`;
  }
  
  return new Response(JSON.stringify({ ok: true, source: 'rules', answer }), {
    headers: { 'Content-Type': 'application/json; charset=utf-8' },
  });
}

async function answerWithAI(question, works, apiKey) {
  const context = works.slice(0, 10).map(w => 
    `- ${w.title}（${w.type}, ${w.year}）：${w.summary}`
  ).join('\n');
  
  const prompt = `你是一位设计师本人，正在自己的作品集网站上回答访客的提问。

我的作品列表：
${context}

访客的问题：${question}

请用第一人称简洁友好地回答（2-3 句话），如果问题与作品无关，礼貌引导对方查看作品集。`;
  
  try {
    const response = await fetch('https://api.deepseek.com/chat/completions', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiKey}` },
      body: JSON.stringify({
        model: 'deepseek-chat',
        messages: [{ role: 'user', content: prompt }],
        max_tokens: 300,
        temperature: 0.6,
      }),
      signal: AbortSignal.timeout(20000),
    });
    const data = await response.json();
    const answer = data.choices?.[0]?.message?.content || '抱歉，我现在不太方便回答这个问题。';
    return new Response(JSON.stringify({ ok: true, source: 'ai', answer }), {
      headers: { 'Content-Type': 'application/json; charset=utf-8' },
    });
  } catch (err) {
    return answerWithRules(question, works);
  }
}

---

五、AI 执行清单

生成 generate.js 时按顺序确认：

• [ ] 包含 5 个领域的完整词库（intros / styles / strategies / closes）
• [ ] pick() 和 pickN() 工具函数实现随机选择
• [ ] 模板引擎为默认行为（零依赖即可跑）
• [ ] DeepSeek 接入是可选增强（环境变量 DEEPSEEK_API_KEY）
• [ ] DeepSeek 调用失败时静默降级到模板引擎，附带 warnings 字段
• [ ] DeepSeek 设置 30 秒 timeout
• [ ] 响应里的 source 字段如实标注来源（'ai' 或 'template'）
• [ ] 前端打字机效果加 20ms/字符的延迟，增强 AI 感

---

六、关键技术亮点（评委视角）

---

七、反例

❌ 错误：所有领域共用一套词库 ✅ 正确：每个领域独立词库，专业术语隔离

❌ 错误：调用 DeepSeek 失败时直接报错 500 ✅ 正确：静默降级到模板引擎，warnings 字段透明告知

❌ 错误：每次生成结果一模一样（用 join 拼死内容） ✅ 正确：pick() 随机抽取，让 100 次生成有 100 种结果

❌ 错误：把 DEEPSEEK_API_KEY 硬编码在代码里 ✅ 正确：从环境变量读取，README 中引导用户配置

Auth & JWT — 邮箱密码登录与 JWT 鉴权完整方案

何时加载本文件：用户的请求涉及登录、注册、鉴权、密码、token、JWT、Session、保护管理后台、限制访问等。

>

核心原则：本方案只用 Edge Functions 原生能力 + KV Storage，零 npm 依赖——这是 EdgeOne Pages Edge Functions 运行时的硬约束（V8 隔离环境，不支持 Node.js 模块）。

---

一、整体架构

用户访问 /admin
  ↓
_middleware.js 拦截 → 检查 Cookie 里的 portfolio_token
  ↓
有 token + 验证通过 → 放行
没 token / 验证失败 → 重定向到 /login.html
  ↓
用户在 /login 提交邮箱密码
  ↓
POST /api/auth (action: 'login')
  ↓
auth.js 验证：
  1. 查 PORTFOLIO_USERS KV 拿 user record
  2. 用 Web Crypto API 比对密码 hash
  3. 用 Web Crypto API 签发 JWT
  4. Set-Cookie: portfolio_token=xxx; HttpOnly; SameSite=Strict
  ↓
前端跳转 /admin.html

---

二、KV 数据结构

PORTFOLIO_USERS 命名空间

key: user:{email}              # 例如 user:admin@portfolio.local
value: {
  "email": "admin@portfolio.local",
  "passwordHash": "base64(SHA-256(password + salt))",
  "salt": "base64(16 bytes random)",
  "role": "admin",
  "createdAt": 1730000000000,
  "lastLoginAt": 1730000000000
}

首次部署时自动创建默认管理员

部署完成后第一次访问 /api/auth?init=true，如果 KV 里没有任何 user 记录，则：

1. 生成随机 12 位密码（包含字母 + 数字） 2. 哈希后写入 PORTFOLIO_USERS 3. 在响应里仅一次性返回明文密码给用户 4. 后续访问该端点直接返回 { error: 'already initialized' }

---

三、完整代码

functions/api/auth.js

/**
 * Portfolio Auth API
 * 路由：
 *   POST /api/auth { action: 'login', email, password }      → 登录
 *   POST /api/auth { action: 'changePassword', oldPw, newPw } → 改密码（需登录）
 *   GET  /api/auth?init=true                                  → 首次部署初始化
 *   GET  /api/auth?action=me                                  → 检查当前登录状态
 *   POST /api/auth { action: 'logout' }                       → 登出
 */

// === 工具函数 ===

const enc = new TextEncoder();
const dec = new TextDecoder();

// SHA-256 哈希 → base64
async function sha256base64(text) {
  const buf = await crypto.subtle.digest('SHA-256', enc.encode(text));
  return btoa(String.fromCharCode(...new Uint8Array(buf)));
}

// 生成随机字节 → base64
function randomBase64(byteLen) {
  const arr = new Uint8Array(byteLen);
  crypto.getRandomValues(arr);
  return btoa(String.fromCharCode(...arr));
}

// 生成随机密码（12 位字母+数字）
function generatePassword() {
  const chars = 'ABCDEFGHJKMNPQRSTUVWXYZabcdefghijkmnpqrstuvwxyz23456789';
  const arr = new Uint8Array(12);
  crypto.getRandomValues(arr);
  return Array.from(arr).map(b => chars[b % chars.length]).join('');
}

// 密码哈希（password + salt → hash）
async function hashPassword(password, salt) {
  return await sha256base64(password + ':' + salt);
}

// === JWT 实现（HS256，无依赖）===

// base64url 编码
function b64urlEncode(input) {
  let s = typeof input === 'string'
    ? btoa(input)
    : btoa(String.fromCharCode(...new Uint8Array(input)));
  return s.replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_');
}

function b64urlDecode(s) {
  s = s.replace(/-/g, '+').replace(/_/g, '/');
  while (s.length % 4) s += '=';
  return atob(s);
}

// HMAC-SHA256 签名
async function hmacSign(data, secret) {
  const key = await crypto.subtle.importKey(
    'raw',
    enc.encode(secret),
    { name: 'HMAC', hash: 'SHA-256' },
    false,
    ['sign']
  );
  const sig = await crypto.subtle.sign('HMAC', key, enc.encode(data));
  return b64urlEncode(sig);
}

async function signJWT(payload, secret) {
  const header = { alg: 'HS256', typ: 'JWT' };
  const headerB64 = b64urlEncode(JSON.stringify(header));
  const payloadB64 = b64urlEncode(JSON.stringify(payload));
  const sig = await hmacSign(`${headerB64}.${payloadB64}`, secret);
  return `${headerB64}.${payloadB64}.${sig}`;
}

async function verifyJWT(token, secret) {
  try {
    const [headerB64, payloadB64, sigGiven] = token.split('.');
    if (!headerB64 || !payloadB64 || !sigGiven) return null;
    
    const expectedSig = await hmacSign(`${headerB64}.${payloadB64}`, secret);
    if (sigGiven !== expectedSig) return null;
    
    const payload = JSON.parse(b64urlDecode(payloadB64));
    if (payload.exp && Date.now() / 1000 > payload.exp) return null;  // 过期
    return payload;
  } catch (e) {
    return null;
  }
}

// === Cookie 工具 ===

function getCookie(request, name) {
  const cookieHeader = request.headers.get('Cookie') || '';
  const match = cookieHeader.match(new RegExp(`(^|; )${name}=([^;]+)`));
  return match ? decodeURIComponent(match[2]) : null;
}

function setCookie(name, value, options = {}) {
  const parts = [`${name}=${encodeURIComponent(value)}`];
  if (options.maxAge) parts.push(`Max-Age=${options.maxAge}`);
  if (options.path) parts.push(`Path=${options.path}`);
  if (options.httpOnly) parts.push('HttpOnly');
  if (options.secure) parts.push('Secure');
  if (options.sameSite) parts.push(`SameSite=${options.sameSite}`);
  return parts.join('; ');
}

// === 主路由 ===

export async function onRequest({ request }) {
  const url = new URL(request.url);
  const SECRET = (typeof JWT_SECRET !== 'undefined' && JWT_SECRET)
    || 'portfolio-flow-default-secret-please-change-me';
  
  // 首次初始化
  if (request.method === 'GET' && url.searchParams.get('init') === 'true') {
    return await handleInit();
  }
  
  // 检查当前登录状态
  if (request.method === 'GET' && url.searchParams.get('action') === 'me') {
    return await handleMe(request, SECRET);
  }
  
  if (request.method !== 'POST') {
    return jsonResponse({ error: 'Method not allowed' }, 405);
  }
  
  let body;
  try { body = await request.json(); } catch { 
    return jsonResponse({ error: 'Invalid JSON' }, 400);
  }
  
  switch (body.action) {
    case 'login':          return await handleLogin(body, SECRET);
    case 'logout':         return handleLogout();
    case 'changePassword': return await handleChangePassword(body, request, SECRET);
    default:               return jsonResponse({ error: 'Unknown action' }, 400);
  }
}

// === 各路由实现 ===

async function handleInit() {
  if (typeof PORTFOLIO_USERS === 'undefined') {
    return jsonResponse({ error: 'KV namespace PORTFOLIO_USERS not bound' }, 500);
  }
  
  // 检查是否已初始化
  const existing = await PORTFOLIO_USERS.get('user:admin@portfolio.local');
  if (existing) {
    return jsonResponse({ error: 'Already initialized', hint: 'Login at /login' }, 400);
  }
  
  const password = generatePassword();
  const salt = randomBase64(16);
  const passwordHash = await hashPassword(password, salt);
  
  const user = {
    email: 'admin@portfolio.local',
    passwordHash,
    salt,
    role: 'admin',
    createdAt: Date.now(),
    lastLoginAt: null,
  };
  
  await PORTFOLIO_USERS.put('user:admin@portfolio.local', JSON.stringify(user));
  
  return jsonResponse({
    ok: true,
    message: '🎉 PortfolioFlow initialized successfully!',
    credentials: {
      email: 'admin@portfolio.local',
      password,  // 仅一次性返回
    },
    warning: '⚠️ Save this password NOW. It will not be shown again. Change it immediately after first login.',
  });
}

async function handleLogin(body, secret) {
  const { email, password } = body;
  if (!email || !password) {
    return jsonResponse({ error: 'Email and password required' }, 400);
  }
  
  if (typeof PORTFOLIO_USERS === 'undefined') {
    return jsonResponse({ error: 'KV not bound' }, 500);
  }
  
  const userRaw = await PORTFOLIO_USERS.get(`user:${email}`);
  if (!userRaw) {
    // 故意延迟，防止时序攻击
    await new Promise(r => setTimeout(r, 200));
    return jsonResponse({ error: 'Invalid credentials' }, 401);
  }
  
  const user = JSON.parse(userRaw);
  const inputHash = await hashPassword(password, user.salt);
  
  if (inputHash !== user.passwordHash) {
    return jsonResponse({ error: 'Invalid credentials' }, 401);
  }
  
  // 更新 lastLoginAt
  user.lastLoginAt = Date.now();
  await PORTFOLIO_USERS.put(`user:${email}`, JSON.stringify(user));
  
  // 签发 JWT（7 天过期）
  const payload = {
    sub: email,
    role: user.role,
    iat: Math.floor(Date.now() / 1000),
    exp: Math.floor(Date.now() / 1000) + 60 * 60 * 24 * 7,
  };
  const token = await signJWT(payload, secret);
  
  const cookie = setCookie('portfolio_token', token, {
    maxAge: 60 * 60 * 24 * 7,
    path: '/',
    httpOnly: true,
    secure: true,
    sameSite: 'Strict',
  });
  
  return new Response(JSON.stringify({
    ok: true,
    user: { email: user.email, role: user.role },
  }), {
    status: 200,
    headers: {
      'Content-Type': 'application/json',
      'Set-Cookie': cookie,
    },
  });
}

function handleLogout() {
  const cookie = setCookie('portfolio_token', '', {
    maxAge: 0,
    path: '/',
    httpOnly: true,
    secure: true,
    sameSite: 'Strict',
  });
  return new Response(JSON.stringify({ ok: true }), {
    status: 200,
    headers: {
      'Content-Type': 'application/json',
      'Set-Cookie': cookie,
    },
  });
}

async function handleMe(request, secret) {
  const token = getCookie(request, 'portfolio_token');
  if (!token) return jsonResponse({ authenticated: false }, 200);
  
  const payload = await verifyJWT(token, secret);
  if (!payload) return jsonResponse({ authenticated: false }, 200);
  
  return jsonResponse({
    authenticated: true,
    user: { email: payload.sub, role: payload.role },
    expiresAt: payload.exp * 1000,
  });
}

async function handleChangePassword(body, request, secret) {
  const token = getCookie(request, 'portfolio_token');
  if (!token) return jsonResponse({ error: 'Unauthorized' }, 401);
  
  const payload = await verifyJWT(token, secret);
  if (!payload) return jsonResponse({ error: 'Invalid token' }, 401);
  
  const { oldPassword, newPassword } = body;
  if (!oldPassword || !newPassword) {
    return jsonResponse({ error: 'Both old and new password required' }, 400);
  }
  if (newPassword.length < 8) {
    return jsonResponse({ error: 'New password must be at least 8 characters' }, 400);
  }
  
  const userRaw = await PORTFOLIO_USERS.get(`user:${payload.sub}`);
  if (!userRaw) return jsonResponse({ error: 'User not found' }, 404);
  
  const user = JSON.parse(userRaw);
  const oldHash = await hashPassword(oldPassword, user.salt);
  if (oldHash !== user.passwordHash) {
    return jsonResponse({ error: 'Old password incorrect' }, 401);
  }
  
  // 更新密码（重新生成 salt）
  user.salt = randomBase64(16);
  user.passwordHash = await hashPassword(newPassword, user.salt);
  await PORTFOLIO_USERS.put(`user:${payload.sub}`, JSON.stringify(user));
  
  return jsonResponse({ ok: true, message: 'Password changed successfully' });
}

// === 公共工具：JSON 响应 ===
function jsonResponse(data, status = 200) {
  return new Response(JSON.stringify(data), {
    status,
    headers: { 'Content-Type': 'application/json' },
  });
}

---

四、Middleware：保护 /admin 路由

functions/_middleware.js

const PROTECTED_PATHS = ['/admin', '/admin.html'];
const PROTECTED_API = ['/api/portfolios', '/api/stats'];  // 这些 API 需要登录

const enc = new TextEncoder();

// （复用 auth.js 的 verifyJWT，但 middleware 是独立文件，所以这里要复制一份核心逻辑）
function b64urlEncode(input) {
  let s = typeof input === 'string'
    ? btoa(input)
    : btoa(String.fromCharCode(...new Uint8Array(input)));
  return s.replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_');
}
function b64urlDecode(s) {
  s = s.replace(/-/g, '+').replace(/_/g, '/');
  while (s.length % 4) s += '=';
  return atob(s);
}
async function hmacSign(data, secret) {
  const key = await crypto.subtle.importKey('raw', enc.encode(secret),
    { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
  const sig = await crypto.subtle.sign('HMAC', key, enc.encode(data));
  return b64urlEncode(sig);
}
async function verifyJWT(token, secret) {
  try {
    const [h, p, s] = token.split('.');
    if (!h || !p || !s) return null;
    const expected = await hmacSign(`${h}.${p}`, secret);
    if (s !== expected) return null;
    const payload = JSON.parse(b64urlDecode(p));
    if (payload.exp && Date.now() / 1000 > payload.exp) return null;
    return payload;
  } catch { return null; }
}
function getCookie(request, name) {
  const cookieHeader = request.headers.get('Cookie') || '';
  const match = cookieHeader.match(new RegExp(`(^|; )${name}=([^;]+)`));
  return match ? decodeURIComponent(match[2]) : null;
}

export async function onRequest({ request, next }) {
  const url = new URL(request.url);
  const SECRET = (typeof JWT_SECRET !== 'undefined' && JWT_SECRET)
    || 'portfolio-flow-default-secret-please-change-me';
  
  // 1. CORS 预检
  if (request.method === 'OPTIONS') {
    return new Response(null, {
      headers: {
        'Access-Control-Allow-Origin': '*',
        'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
        'Access-Control-Allow-Headers': 'Content-Type',
      },
    });
  }
  
  // 2. 检查是否是受保护路径
  const isProtectedPage = PROTECTED_PATHS.some(p => url.pathname.startsWith(p));
  const isProtectedApi = PROTECTED_API.some(p => url.pathname.startsWith(p));
  
  if (isProtectedPage || isProtectedApi) {
    const token = getCookie(request, 'portfolio_token');
    const payload = token ? await verifyJWT(token, SECRET) : null;
    
    if (!payload) {
      if (isProtectedApi) {
        return new Response(JSON.stringify({ error: 'Unauthorized' }), {
          status: 401,
          headers: { 'Content-Type': 'application/json' },
        });
      }
      // 页面 → 重定向到登录
      return Response.redirect(`${url.origin}/login.html?from=${encodeURIComponent(url.pathname)}`, 302);
    }
    
    // 把用户信息透传给后端 API（通过 header）
    const newRequest = new Request(request);
    newRequest.headers.set('X-Auth-Email', payload.sub);
    newRequest.headers.set('X-Auth-Role', payload.role);
  }
  
  // 3. 调用下游
  const response = await next();
  
  // 4. 给所有 /api 响应加 CORS 和品牌头
  if (url.pathname.startsWith('/api')) {
    response.headers.set('Access-Control-Allow-Origin', '*');
    response.headers.set('X-Powered-By', 'PortfolioFlow');
  }
  
  return response;
}

---

五、前端登录页（login.html 关键 JS 片段）

const form = document.getElementById('login-form');
form.addEventListener('submit', async (e) => {
  e.preventDefault();
  const email = form.email.value.trim();
  const password = form.password.value;
  const errorEl = document.getElementById('error-msg');
  errorEl.textContent = '';
  
  try {
    const res = await fetch('/api/auth', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ action: 'login', email, password }),
      credentials: 'same-origin',  // 关键：让 Cookie 被存储
    });
    const data = await res.json();
    
    if (!res.ok) {
      errorEl.textContent = data.error || '登录失败';
      return;
    }
    
    // 登录成功，跳转
    const from = new URLSearchParams(location.search).get('from') || '/admin.html';
    location.href = from;
  } catch (err) {
    errorEl.textContent = '网络错误：' + err.message;
  }
});

---

六、关键安全约束（必须遵守）

1. JWT_SECRET 不能硬编码——通过 EdgeOne Pages 环境变量配置：

   控制台 → 项目 → 环境变量 → 新增
   Key: JWT_SECRET
   Value: 任意 32 字符以上的随机字符串

2. Cookie 必须 `HttpOnly + Secure + SameSite=Strict`——防止 XSS 偷 token 3. 密码必须加盐哈希——salt 每个用户独立，永不复用 4. 失败响应人为延迟 200ms——防止时序攻击枚举邮箱 5. JWT 过期时间设为 7 天——长期 session 但有时效

---

七、AI 执行清单

生成 auth.js、_middleware.js、login.html 时按顺序确认：

• [ ] auth.js 包含 5 个 action：login / logout / me / init / changePassword
• [ ] _middleware.js 保护 /admin* 和 /api/portfolios /api/stats 路径
• [ ] JWT 使用 HMAC-SHA256，通过 Web Crypto API 实现，不引入任何 npm 包
• [ ] 默认 JWT_SECRET 兜底字符串，但 README 提示用户在控制台改
• [ ] 部署完成后自动调用 /api/auth?init=true 一次，把默认管理员账号密码返回给用户
• [ ] login 失败时延迟 200ms 回应
• [ ] 密码哈希使用 SHA-256 + per-user salt
• [ ] Cookie 设置 HttpOnly + Secure + SameSite=Strict + Max-Age 7 天

---

八、KV 绑定提醒（部署后必做）

部署完成后引导用户在 EdgeOne 控制台手动绑定：

项目 → KV 存储 → 绑定命名空间

变量名: PORTFOLIO_USERS
命名空间: 新建（名字随意，如 portfolio-users）

重要：绑定后必须重新部署一次，否则 PORTFOLIO_USERS 全局变量仍是 undefined。

绑定生效后，首次访问 /api/auth?init=true 自动创建管理员账号。

---

九、反例：常见错误

❌ 错误：在 Edge Function 中 import bcrypt from 'bcrypt' ✅ 正确：用 Web Crypto API 的 SHA-256（V8 隔离环境不支持 npm 模块）

❌ 错误：用 env.PORTFOLIO_USERS.get(...) ✅ 正确：用全局 PORTFOLIO_USERS.get(...)（EdgeOne 规范）

❌ 错误：把 JWT secret 写死在代码里 ✅ 正确：从全局 JWT_SECRET 读，配合控制台环境变量

❌ 错误：登录失败立即返回 401 ✅ 正确：人为延迟 200ms 后再返回，避免时序攻击

❌ 错误：Cookie 不设 HttpOnly ✅ 正确：HttpOnly + Secure + SameSite=Strict 三件套

Deploy Workflow — 部署流程（调用 edgeone-pages-deploy）

何时加载本文件：用户请求涉及部署、上线、发布、EdgeOne Pages、KV 绑定、环境变量、域名设置等。

>

核心原则：本 Skill 自身不直接执行部署，而是调用 `edgeone-pages-deploy` Skill 完成。我们的职责是把项目生成好，并引导用户完成部署后的 KV 绑定等手动配置。

---

一、整体流程

1. 生成本地项目目录       ← 本 Skill 负责
2. 调用 edgeone-pages-deploy 部署
3. 引导用户在控制台绑定 KV
4. 引导用户在控制台设置环境变量
5. 重新部署一次让绑定生效
6. 首次访问 /api/auth?init=true 获取默认管理员密码
7. 返回完整访问信息给用户

---

二、Step 1: 生成本地项目目录

路径选择

必须避免包含特殊字符（× ' " / 等）和长串空格的路径。优先选择：

~/Desktop/portfolio-{slug}/           ← 推荐
~/portfolio-flow/                     ← 备选
/tmp/portfolio-{slug}/                ← 临时

绝不写入到：

• 包含 × 字符的目录（曾经踩过的坑）
• 中文路径深度超过 3 层的目录
• 含特殊符号 '"!? 的目录

目录结构

portfolio-{slug}/
├── index.html
├── portfolio-detail.html
├── admin.html
├── login.html
├── assets/
│   └── works/
├── functions/
│   ├── api/
│   │   ├── auth.js
│   │   ├── portfolios.js
│   │   ├── generate.js
│   │   ├── stats.js
│   │   └── assistant.js
│   └── _middleware.js
└── README.md

---

三、Step 2: 调用 edgeone-pages-deploy

本 Skill 完成项目生成后，主动调用 EdgeOne Pages 官方部署 Skill。

触发方式

向用户的 AI 编程工具发出明确的部署请求：

Deploy this PortfolioFlow project to EdgeOne Pages.
Project directory: ~/Desktop/portfolio-{slug}/
Project name: portfolio-{slug}

edgeone-pages-deploy 会自动： 1. 检查 / 安装 EdgeOne CLI 2. 验证登录状态（已登录则跳过） 3. 上传项目文件到 EdgeOne COS 4. 创建生产环境部署 5. 返回访问 URL 与控制台链接

部署成功后的输出

EDGEONE_DEPLOY_URL=https://portfolio-{slug}.edgeone.cool?eo_token=xxx&eo_time=xxx
EDGEONE_PROJECT_ID=pages-xxxxxx

记录下 EDGEONE_PROJECT_ID，后续控制台操作需要它。

---

四、Step 3: 引导用户绑定 3 个 KV 命名空间

部署成功后，立即引导用户在控制台完成 KV 绑定。

向用户输出以下指引（截图最佳，文字也可）：

## 🔧 部署完成！但还差一步关键配置

PortfolioFlow 需要 3 个 KV 命名空间才能运行：

### 操作步骤（约 2 分钟）

1. 打开控制台：
   https://console.cloud.tencent.com/edgeone/pages/project/pages-{你的项目ID}
2. 左侧菜单点 **「KV 存储」**
3. 点击 **「绑定命名空间」** 按钮，分别绑定以下 3 个：

   | 变量名 | 命名空间 |
   |---|---|
   | `PORTFOLIO_USERS` | 新建（名字随意） |
   | `PORTFOLIO_WORKS` | 新建（名字随意） |
   | `PORTFOLIO_STATS` | 新建（名字随意） |

⚠️ **变量名必须一字不差**——它们在代码中作为**全局变量**访问。

为什么是全局变量？

EdgeOne Pages 的 KV 绑定规范：绑定的变量名直接在 Edge Function 中作为全局变量使用，而不是 env.VARIABLE_NAME 的方式。

// ❌ 错误
await env.PORTFOLIO_USERS.get(...);

// ✅ 正确
await PORTFOLIO_USERS.get(...);

这是 LandscapeFlow AI 实战踩出来的关键经验，必须在生成的代码里就遵守。

---

五、Step 4: 引导用户配置环境变量

PortfolioFlow 用到 2 个环境变量：

配置步骤

1. 控制台 → 项目设置 → 环境变量 → 新增
2. 添加 JWT_SECRET：
   Key: JWT_SECRET
   Value: 任意 32+ 字符的随机字符串
   
   生成方法（终端运行）：
   openssl rand -base64 32
   
3. （可选）添加 DEEPSEEK_API_KEY：
   Key: DEEPSEEK_API_KEY
   Value: 你的 DeepSeek API Key

4. 保存后回到顶部，点 **「构建部署」** → **「新建部署」** 重新部署一次

---

六、Step 5: 重新部署让绑定生效

⚠️ 关键步骤，绝不能跳过——KV 绑定和环境变量都需要重新部署一次才会注入到运行时。

cd ~/Desktop/portfolio-{slug}
edgeone pages deploy .

或者在控制台点"重新部署"按钮。

---

七、Step 6: 首次初始化获取默认管理员

第二次部署完成后，自动访问初始化端点：

curl "https://portfolio-{slug}.edgeone.cool/api/auth?init=true&eo_token=xxx&eo_time=xxx"

期望响应：

{
  "ok": true,
  "message": "🎉 PortfolioFlow initialized successfully!",
  "credentials": {
    "email": "admin@portfolio.local",
    "password": "随机12位密码"
  },
  "warning": "⚠️ Save this password NOW. It will not be shown again."
}

重要：

• 这个密码只显示一次，后续调用同一端点返回 Already initialized
• 必须立即告知用户保存密码，并提醒首次登录后改密码

---

八、Step 7: 返回完整结果给用户

部署链路全部完成后，按以下格式向用户输出结构化结果：

✅ PortfolioFlow 作品集已就绪

## 🌐 访问地址

- **前台首页**：https://portfolio-{slug}.edgeone.cool
- **管理后台**：https://portfolio-{slug}.edgeone.cool/login
- **控制台**：https://console.cloud.tencent.com/edgeone/pages/project/pages-{id}

## 🔐 默认管理员

- 邮箱：`admin@portfolio.local`
- 密码：`{12位随机密码}`
- ⚠️ 首次登录后请立即修改密码

## 📊 已部署能力

| 模块 | 状态 |
|---|---|
| 前台首页 | ✅ |
| 作品详情页 | ✅ |
| 管理后台（登录/CRUD/AI生成/看板）| ✅ |
| Edge Functions × 5 | ✅ |
| KV Storage × 3 | ✅ |
| JWT 鉴权 + CORS Middleware | ✅ |
| 访问统计 + 数据看板 | ✅ |

## 🎨 当前主题

{用户选定的主题名}

## 📁 本地项目目录

~/Desktop/portfolio-{slug}/

## 💡 下一步建议

1. 登录后台修改默认密码
2. 添加你的真实作品（覆盖 3 个示例作品）
3. 上传作品图到 /assets/works/，重新部署
4. （可选）添加 DEEPSEEK_API_KEY 启用真 AI 模式
5. （可选）绑定自定义域名解除 3 小时 token 限制

---

九、域名问题（必告知用户）

EdgeOne Pages 默认域名 xxx.edgeone.cool 的特殊机制：

⚠️ 默认域名限制
- 链接形如 https://xxx.edgeone.cool?eo_token=xxx&eo_time=xxx
- token 默认 3 小时过期
- 不带 token 直接访问会 401

要解除限制，必须绑定自定义域名：
1. 控制台 → 域名管理 → 添加自定义域名
2. 配置 CNAME 解析到 EdgeOne 给的地址
3. 等待 HTTPS 证书签发（约 5 分钟）
4. 此后 https://your-domain.com 可永久公开访问

对参赛作品来说：评委如果要复现，会用临时 token 链接看 3 小时内的版本，不一定需要自定义域名。但用户长期使用必须配域名。

---

十、常见部署错误与排查

---

十一、AI 执行清单

完整的部署流程检查：

• [ ] 已生成完整项目目录
• [ ] 项目路径不含 × 等特殊字符
• [ ] 调用 edgeone-pages-deploy 完成第一次部署
• [ ] 引导用户绑定 3 个 KV 命名空间
• [ ] 引导用户配置 JWT_SECRET 环境变量
• [ ] 触发第二次部署让绑定生效
• [ ] 访问 /api/auth?init=true 获取默认账号
• [ ] 输出完整的部署结果给用户（含访问 URL、控制台、默认账号、本地路径）
• [ ] 提醒用户首次登录后修改密码
• [ ] 提醒用户域名 3 小时限制（如未绑定自定义域名）

---

十二、反例

❌ 错误：部署成功就告诉用户"完成了"，不引导 KV 绑定 ✅ 正确：必须把 KV 绑定、环境变量、二次部署整套流程跑完

❌ 错误：默认域名 token 链接当作最终交付物 ✅ 正确：明确告知用户域名有 3 小时限制，引导绑定自定义域名

❌ 错误：把 admin@portfolio.local 默认密码写死 ✅ 正确：首次部署随机生成，仅一次性返回

❌ 错误：跳过二次部署，KV 绑定不生效 ✅ 正确：KV 绑定/环境变量配置后必须重新部署

Design System — 视觉规范与主题色

何时加载本文件：用户的请求涉及主题色、配色方案、视觉风格、hex 自定义、CSS 变量、深浅模式等。

>

何时不加载：用户只是建一个默认作品集站、没有提到任何视觉相关字眼时。

---

一、共享设计基础（5 套主题都遵守）

字体系统

通过 Google Fonts 引入两套字体，所有主题不变：

<link href="https://fonts.googleapis.com/css2?family=Playfair+Display:ital,wght@0,400;0,500;0,600;0,700;1,400&family=DM+Sans:ital,opsz,wght@0,9..40,300;0,9..40,400;0,9..40,500;0,9..40,600&display=swap" rel="stylesheet" />

CSS 变量：

--font-serif: 'Playfair Display', Georgia, serif;   /* 标题、英文 eyebrow */
--font-sans: 'DM Sans', system-ui, sans-serif;       /* 正文、UI */

共享尺寸

--radius-sm: 6px;
--radius-md: 12px;
--radius-lg: 18px;
--radius-pill: 999px;

--shadow-card: 0 4px 20px rgba(0,0,0,0.06);
--shadow-card-hover: 0 12px 36px rgba(0,0,0,0.12);

--container-max: 1280px;
--container-padding: clamp(20px, 4vw, 60px);

---

二、5 套预设主题（用户选 1 套）

每个主题都通过一组完整的 CSS 变量定义，注入到 index.html / admin.html / login.html 的 <style> 标签里。

主题 1：暗夜森林（dark-forest）— 默认主题

氛围：黑底 + 景观绿 + 衬线大字。深夜美术馆感，克制中带生命力。

适合：景观设计师、室内设计师、工业设计师、所有偏专业沉稳的设计师。

来源：LandscapeFlow AI 同款配色，已经过真实部署验证。

:root[data-theme="dark-forest"] {
  --bg: #0A0A0A;
  --bg-elevated: rgba(255,255,255,0.06);
  --bg-overlay: rgba(10,10,10,0.86);
  
  --primary: #22C55E;
  --primary-dim: rgba(34,197,94,0.15);
  --primary-glow: rgba(34,197,94,0.4);
  
  --text: #FFFFFF;
  --text-muted: rgba(255,255,255,0.60);
  --text-faint: rgba(255,255,255,0.30);
  
  --border: rgba(255,255,255,0.10);
  --divider: rgba(255,255,255,0.08);
  
  --hero-gradient: linear-gradient(
    rgba(10,10,10,0.64) 0%,
    rgba(10,10,10,0.28) 32%,
    rgba(10,10,10,0.30) 58%,
    rgba(10,10,10,0.86) 100%
  );
  
  --btn-cta-bg: linear-gradient(135deg, #22C55E 0%, #16A34A 100%);
  --btn-cta-text: #FFFFFF;
  --btn-cta-shadow: 0 0 30px rgba(34,197,94,0.4);
}

主题 2：晨曦米色（dawn-beige）

氛围：温暖米白底 + 深咖文字 + 燕麦色点缀。手作感、温柔克制。

适合：室内设计师、平面设计师、手工艺术家、生活方式品牌。

:root[data-theme="dawn-beige"] {
  --bg: #F5F0E8;
  --bg-elevated: #FFFFFF;
  --bg-overlay: rgba(245,240,232,0.92);
  
  --primary: #8B6F47;
  --primary-dim: rgba(139,111,71,0.10);
  --primary-glow: rgba(139,111,71,0.20);
  
  --text: #2C2418;
  --text-muted: rgba(44,36,24,0.65);
  --text-faint: rgba(44,36,24,0.35);
  
  --border: rgba(44,36,24,0.10);
  --divider: rgba(44,36,24,0.06);
  
  --hero-gradient: linear-gradient(
    rgba(245,240,232,0.10) 0%,
    rgba(245,240,232,0.30) 60%,
    rgba(245,240,232,0.92) 100%
  );
  
  --btn-cta-bg: linear-gradient(135deg, #8B6F47 0%, #6B5435 100%);
  --btn-cta-text: #F5F0E8;
  --btn-cta-shadow: 0 6px 24px rgba(139,111,71,0.30);
}

主题 3：深海蓝调（deep-ocean）

氛围：靛蓝底 + 冷霜白 + 海蓝高亮。科技感、冷静理性。

适合：UX/UI 设计师、产品设计师、数据可视化设计师。

:root[data-theme="deep-ocean"] {
  --bg: #0F1B2E;
  --bg-elevated: rgba(255,255,255,0.05);
  --bg-overlay: rgba(15,27,46,0.86);
  
  --primary: #38BDF8;
  --primary-dim: rgba(56,189,248,0.15);
  --primary-glow: rgba(56,189,248,0.4);
  
  --text: #F8FAFC;
  --text-muted: rgba(248,250,252,0.65);
  --text-faint: rgba(248,250,252,0.35);
  
  --border: rgba(248,250,252,0.10);
  --divider: rgba(248,250,252,0.06);
  
  --hero-gradient: linear-gradient(
    rgba(15,27,46,0.60) 0%,
    rgba(15,27,46,0.28) 32%,
    rgba(15,27,46,0.30) 58%,
    rgba(15,27,46,0.88) 100%
  );
  
  --btn-cta-bg: linear-gradient(135deg, #38BDF8 0%, #0EA5E9 100%);
  --btn-cta-text: #0F1B2E;
  --btn-cta-shadow: 0 0 30px rgba(56,189,248,0.4);
}

主题 4：暖阳橙红(sunset-coral)

氛围：奶白底 + 珊瑚橙 + 暖灰文字。明亮愉悦、活力四射。

适合：平面设计师、插画师、品牌设计师、儿童 / 教育领域设计师。

:root[data-theme="sunset-coral"] {
  --bg: #FFFBF5;
  --bg-elevated: #FFFFFF;
  --bg-overlay: rgba(255,251,245,0.92);
  
  --primary: #FB7185;
  --primary-dim: rgba(251,113,133,0.10);
  --primary-glow: rgba(251,113,133,0.25);
  
  --text: #2D1B14;
  --text-muted: rgba(45,27,20,0.65);
  --text-faint: rgba(45,27,20,0.35);
  
  --border: rgba(45,27,20,0.10);
  --divider: rgba(45,27,20,0.06);
  
  --hero-gradient: linear-gradient(
    rgba(255,251,245,0.10) 0%,
    rgba(255,251,245,0.30) 60%,
    rgba(255,251,245,0.92) 100%
  );
  
  --btn-cta-bg: linear-gradient(135deg, #FB7185 0%, #F43F5E 100%);
  --btn-cta-text: #FFFFFF;
  --btn-cta-shadow: 0 6px 24px rgba(251,113,133,0.35);
}

主题 5：纯白极简(pure-minimal)

氛围：纯白底 + 纯黑字 + 极少装饰。瑞士风格、性冷淡极致。

适合：工业设计师、建筑设计师、字体设计师、追求极致简约的所有领域。

:root[data-theme="pure-minimal"] {
  --bg: #FFFFFF;
  --bg-elevated: #FAFAFA;
  --bg-overlay: rgba(255,255,255,0.95);
  
  --primary: #000000;
  --primary-dim: rgba(0,0,0,0.06);
  --primary-glow: rgba(0,0,0,0.10);
  
  --text: #000000;
  --text-muted: rgba(0,0,0,0.55);
  --text-faint: rgba(0,0,0,0.30);
  
  --border: rgba(0,0,0,0.08);
  --divider: rgba(0,0,0,0.04);
  
  --hero-gradient: linear-gradient(
    rgba(255,255,255,0.10) 0%,
    rgba(255,255,255,0.30) 60%,
    rgba(255,255,255,0.92) 100%
  );
  
  --btn-cta-bg: #000000;
  --btn-cta-text: #FFFFFF;
  --btn-cta-shadow: 0 4px 16px rgba(0,0,0,0.15);
}

---

三、用户传 hex 颜色 → 自动生成完整主题的算法

当用户传入 hex 颜色（如 #FF6B6B），按以下规则生成配套的完整 CSS 变量集。

Step 1: 判断是浅色调还是深色调

function isLightColor(hex) {
  // 移除 # 号
  const h = hex.replace('#', '');
  const r = parseInt(h.substring(0, 2), 16);
  const g = parseInt(h.substring(2, 4), 16);
  const b = parseInt(h.substring(4, 6), 16);
  // 相对亮度计算（YIQ 公式）
  const yiq = (r * 299 + g * 587 + b * 114) / 1000;
  return yiq >= 128;
}

Step 2: 根据色调选择基础主题模板

function buildThemeFromHex(hex) {
  const isLight = isLightColor(hex);
  
  if (isLight) {
    // 浅色主调 → 使用"晨曦米色"或"暖阳橙红"为骨架
    return {
      bg: '#FFFBF5',
      bgElevated: '#FFFFFF',
      bgOverlay: 'rgba(255,251,245,0.92)',
      primary: hex,
      primaryDim: hexToRgba(hex, 0.10),
      primaryGlow: hexToRgba(hex, 0.25),
      text: '#1A1A1A',
      textMuted: 'rgba(26,26,26,0.65)',
      textFaint: 'rgba(26,26,26,0.35)',
      border: 'rgba(26,26,26,0.10)',
      divider: 'rgba(26,26,26,0.06)',
      btnCtaBg: `linear-gradient(135deg, ${hex} 0%, ${darken(hex, 0.15)} 100%)`,
      btnCtaText: '#FFFFFF',
      btnCtaShadow: `0 6px 24px ${hexToRgba(hex, 0.35)}`,
    };
  } else {
    // 深色主调 → 使用"暗夜森林"或"深海蓝调"为骨架
    return {
      bg: '#0A0A0A',
      bgElevated: 'rgba(255,255,255,0.06)',
      bgOverlay: 'rgba(10,10,10,0.86)',
      primary: hex,
      primaryDim: hexToRgba(hex, 0.15),
      primaryGlow: hexToRgba(hex, 0.4),
      text: '#FFFFFF',
      textMuted: 'rgba(255,255,255,0.60)',
      textFaint: 'rgba(255,255,255,0.30)',
      border: 'rgba(255,255,255,0.10)',
      divider: 'rgba(255,255,255,0.08)',
      btnCtaBg: `linear-gradient(135deg, ${hex} 0%, ${darken(hex, 0.15)} 100%)`,
      btnCtaText: contrastText(hex),  // 自动选黑或白
      btnCtaShadow: `0 0 30px ${hexToRgba(hex, 0.4)}`,
    };
  }
}

Step 3: 辅助函数

// hex 转 rgba
function hexToRgba(hex, alpha) {
  const h = hex.replace('#', '');
  const r = parseInt(h.substring(0, 2), 16);
  const g = parseInt(h.substring(2, 4), 16);
  const b = parseInt(h.substring(4, 6), 16);
  return `rgba(${r},${g},${b},${alpha})`;
}

// 颜色加深（用于按钮渐变的第二个颜色）
function darken(hex, amount) {
  const h = hex.replace('#', '');
  const r = Math.max(0, Math.floor(parseInt(h.substring(0, 2), 16) * (1 - amount)));
  const g = Math.max(0, Math.floor(parseInt(h.substring(2, 4), 16) * (1 - amount)));
  const b = Math.max(0, Math.floor(parseInt(h.substring(4, 6), 16) * (1 - amount)));
  return `#${r.toString(16).padStart(2,'0')}${g.toString(16).padStart(2,'0')}${b.toString(16).padStart(2,'0')}`;
}

// 自动选黑白文字以保证按钮对比度
function contrastText(hex) {
  return isLightColor(hex) ? '#000000' : '#FFFFFF';
}

---

四、主题切换的实现方式

主题信息存在 <html> 标签的 data-theme 属性上，CSS 用属性选择器命中。

HTML 结构

<html lang="zh-CN" data-theme="dark-forest">
  <head>
    <style>
      /* 5 套主题的 CSS 变量定义（全部内嵌，避免外链） */
      :root[data-theme="dark-forest"] { ... }
      :root[data-theme="dawn-beige"] { ... }
      :root[data-theme="deep-ocean"] { ... }
      :root[data-theme="sunset-coral"] { ... }
      :root[data-theme="pure-minimal"] { ... }
      
      /* 通用样式使用 var() */
      body {
        background: var(--bg);
        color: var(--text);
        font-family: var(--font-sans);
      }
    </style>
  </head>
</html>

用户传入 hex 的情况

如果用户传入 hex，直接在 <head> 内追加一个 :root[data-theme="custom"] { ... } 样式块（值来自上面的 buildThemeFromHex(hex) 输出），并把 <html data-theme="custom">。

---

五、视觉风格关键词约束（所有主题共享）

无论选哪套主题，生成的网站必须遵守以下视觉纪律：

1. 高级、克制、有呼吸感 —— 永远比"塞满"少 30% 2. Hero 区必有一张主图 —— 16:9 或全屏，加 --hero-gradient 蒙版 3. 标题用衬线 Playfair Display —— italic 强调用 --primary 色 4. eyebrow 用 DM Sans 全大写 —— letter-spacing 0.18em，颜色 --primary 5. 卡片 hover 上浮 4px + 加 `--primary-glow` 阴影 6. 按钮主 CTA 用 `--btn-cta-bg` 渐变胶囊 7. 绝不滥用阴影、绝不使用 emoji 作为视觉重点

---

六、生成网站时 AI 的执行清单

收到用户请求并确定主题后，AI 必须：

• [ ] 在 index.html 的 <head> 注入完整的 5 套主题 CSS 变量（即使用户只选 1 套，5 套都写进去，方便后续切换）
• [ ] 在 <html> 标签设置 data-theme="{用户选的主题}"
• [ ] 如果用户传入 hex，按算法生成 custom 主题块并追加到 5 套之后
• [ ] admin.html 和 login.html 同步注入相同的主题块
• [ ] 检查所有颜色都使用 var(--xxx)，不能硬编码任何颜色值

---

七、给评委的提示信息（写在生成的 README.md 中）

## 🎨 主题系统

本作品集支持 5 套预设主题：
- 🌲 暗夜森林（默认，黑底+景观绿）
- 🌅 晨曦米色（米白底+深咖文字）
- 🌊 深海蓝调（靛蓝底+海蓝高亮）
- 🌇 暖阳橙红（奶白底+珊瑚橙）
- ⚪ 纯白极简（纯白底+纯黑字）

也支持传入任意 hex 颜色自动生成完整主题。

修改方式：在 `<html>` 标签上改 `data-theme` 属性即可，无需重新部署。

Portfolio CRUD — 作品管理完整实现

何时加载本文件：用户的请求涉及作品的添加/编辑/删除/列表/详情、作品管理、增删改查、KV 数据存储、图片上传、分页等。

---

一、数据模型

PORTFOLIO_WORKS 命名空间

每个作品一条 KV 记录：

key:   work:{slug}                # 例：work:landscape-park-2024
value: {
  "slug": "landscape-park-2024",
  "title": "北方滨海生态公园",
  "type": "滨海景观",
  "year": 2024,
  "area": "120 公顷",
  "role": "项目总负责人",
  "duration": "8 个月",
  "tags": ["生态修复", "滨海景观", "微气候设计"],
  "cover": "/assets/works/landscape-park-2024-cover.jpg",
  "gallery": [
    "/assets/works/landscape-park-2024-01.jpg",
    "/assets/works/landscape-park-2024-02.jpg"
  ],
  "summary": "120 公顷北方滨海公园方案设计，回应北方冬季旅游淡季问题",
  "description": "完整的 Markdown 项目说明...",
  "isFeatured": true,
  "isPublished": true,
  "createdAt": 1730000000000,
  "updatedAt": 1730000000000
}

索引 key

为了支持快速列表查询，额外维护索引：

key:   index:all
value: ["landscape-park-2024", "graphic-vi-2023", ...]   # 按 createdAt 倒序排列的 slug 数组

key:   index:featured
value: ["landscape-park-2024", "landscape-wetland-2022"]  # 精选作品 slug 数组

key:   index:by-type:{type}
value: ["slug1", "slug2", ...]                            # 按类型分组

为什么用索引？——KV 不支持列表/扫描操作，必须自己维护索引。每次 CRUD 都同步更新索引。

---

二、完整代码

functions/api/portfolios.js

/**
 * Portfolio CRUD API
 * 路由：
 *   GET    /api/portfolios                       → 列表（公开，支持分页/筛选）
 *   GET    /api/portfolios?slug=xxx              → 详情（公开）
 *   POST   /api/portfolios                       → 创建（需登录）
 *   PUT    /api/portfolios?slug=xxx              → 更新（需登录）
 *   DELETE /api/portfolios?slug=xxx              → 删除（需登录）
 *
 * 注：写操作的鉴权由 _middleware.js 完成，本文件假设到达这里的写请求都已通过验证
 */

export async function onRequest({ request }) {
  if (typeof PORTFOLIO_WORKS === 'undefined') {
    return jsonResponse({ error: 'KV namespace PORTFOLIO_WORKS not bound' }, 500);
  }
  
  const url = new URL(request.url);
  const slug = url.searchParams.get('slug');
  
  switch (request.method) {
    case 'GET':
      return slug ? await getOne(slug) : await getList(url.searchParams);
    case 'POST':
      return await createWork(await request.json());
    case 'PUT':
      if (!slug) return jsonResponse({ error: 'slug required' }, 400);
      return await updateWork(slug, await request.json());
    case 'DELETE':
      if (!slug) return jsonResponse({ error: 'slug required' }, 400);
      return await deleteWork(slug);
    default:
      return jsonResponse({ error: 'Method not allowed' }, 405);
  }
}

// === 列表查询（支持分页 + 筛选） ===

async function getList(params) {
  const page = parseInt(params.get('page') || '1', 10);
  const pageSize = Math.min(parseInt(params.get('pageSize') || '12', 10), 50);
  const type = params.get('type');
  const featured = params.get('featured') === 'true';
  
  // 从索引拿到 slug 列表
  let indexKey = 'index:all';
  if (featured) indexKey = 'index:featured';
  else if (type) indexKey = `index:by-type:${type}`;
  
  const indexRaw = await PORTFOLIO_WORKS.get(indexKey, 'json');
  const allSlugs = Array.isArray(indexRaw) ? indexRaw : [];
  
  // 分页切片
  const total = allSlugs.length;
  const start = (page - 1) * pageSize;
  const slugs = allSlugs.slice(start, start + pageSize);
  
  // 并行读取每条作品记录
  const works = await Promise.all(
    slugs.map(async (s) => {
      const raw = await PORTFOLIO_WORKS.get(`work:${s}`, 'json');
      return raw;
    })
  );
  
  // 过滤掉 null（数据损坏的情况）
  const validWorks = works.filter(Boolean);
  
  // 只对已发布的作品返回（公开访问时）
  const published = validWorks.filter(w => w.isPublished !== false);
  
  return jsonResponse({
    ok: true,
    works: published,
    pagination: {
      page,
      pageSize,
      total,
      totalPages: Math.ceil(total / pageSize),
    },
  });
}

// === 单条详情 ===

async function getOne(slug) {
  const raw = await PORTFOLIO_WORKS.get(`work:${slug}`, 'json');
  if (!raw) return jsonResponse({ error: 'Not found' }, 404);
  
  return jsonResponse({ ok: true, work: raw });
}

// === 创建 ===

async function createWork(data) {
  // 校验必填字段
  const required = ['title', 'type', 'year'];
  for (const f of required) {
    if (!data[f]) return jsonResponse({ error: `Field "${f}" is required` }, 400);
  }
  
  // 生成 slug（如果用户没提供）
  const slug = data.slug || slugify(data.title);
  
  // 检查 slug 是否已存在
  const existing = await PORTFOLIO_WORKS.get(`work:${slug}`);
  if (existing) {
    return jsonResponse({ error: `Slug "${slug}" already exists, please choose another` }, 409);
  }
  
  const now = Date.now();
  const work = {
    slug,
    title: data.title,
    type: data.type,
    year: parseInt(data.year, 10),
    area: data.area || null,
    role: data.role || null,
    duration: data.duration || null,
    tags: Array.isArray(data.tags) ? data.tags : [],
    cover: data.cover || null,
    gallery: Array.isArray(data.gallery) ? data.gallery : [],
    summary: data.summary || '',
    description: data.description || '',
    isFeatured: !!data.isFeatured,
    isPublished: data.isPublished !== false,
    createdAt: now,
    updatedAt: now,
  };
  
  await PORTFOLIO_WORKS.put(`work:${slug}`, JSON.stringify(work));
  await updateIndexes(slug, work, 'add');
  
  return jsonResponse({ ok: true, work }, 201);
}

// === 更新 ===

async function updateWork(slug, data) {
  const raw = await PORTFOLIO_WORKS.get(`work:${slug}`, 'json');
  if (!raw) return jsonResponse({ error: 'Not found' }, 404);
  
  const oldFeatured = !!raw.isFeatured;
  const oldType = raw.type;
  
  const updated = {
    ...raw,
    ...data,
    slug,  // slug 不允许通过 PUT 修改
    updatedAt: Date.now(),
  };
  
  // 类型强转
  if (data.year) updated.year = parseInt(data.year, 10);
  
  await PORTFOLIO_WORKS.put(`work:${slug}`, JSON.stringify(updated));
  
  // 索引同步：如果 featured 或 type 变化了，更新索引
  if (oldFeatured !== !!updated.isFeatured || oldType !== updated.type) {
    await updateIndexes(slug, { ...raw, isFeatured: oldFeatured, type: oldType }, 'remove');
    await updateIndexes(slug, updated, 'add');
  }
  
  return jsonResponse({ ok: true, work: updated });
}

// === 删除 ===

async function deleteWork(slug) {
  const raw = await PORTFOLIO_WORKS.get(`work:${slug}`, 'json');
  if (!raw) return jsonResponse({ error: 'Not found' }, 404);
  
  await PORTFOLIO_WORKS.delete(`work:${slug}`);
  await updateIndexes(slug, raw, 'remove');
  
  return jsonResponse({ ok: true, message: `Work "${slug}" deleted` });
}

// === 索引维护 ===

async function updateIndexes(slug, work, action) {
  // 操作：'add' 或 'remove'
  
  const indexKeys = ['index:all'];
  if (work.isFeatured) indexKeys.push('index:featured');
  if (work.type) indexKeys.push(`index:by-type:${work.type}`);
  
  for (const key of indexKeys) {
    const current = (await PORTFOLIO_WORKS.get(key, 'json')) || [];
    let updated;
    
    if (action === 'add') {
      // 加到最前（最新的在前）
      updated = [slug, ...current.filter(s => s !== slug)];
    } else {
      updated = current.filter(s => s !== slug);
    }
    
    await PORTFOLIO_WORKS.put(key, JSON.stringify(updated));
  }
}

// === 工具函数 ===

function slugify(text) {
  // 中文转拼音过于复杂，简化处理：保留字母数字 + 时间戳
  const ascii = text.replace(/[^a-zA-Z0-9\s-]/g, '').trim().toLowerCase();
  if (ascii.length > 2) {
    return ascii.replace(/\s+/g, '-').substring(0, 40) + '-' + Date.now().toString(36);
  }
  // 全中文 → 使用时间戳作为 slug
  return 'work-' + Date.now().toString(36);
}

function jsonResponse(data, status = 200) {
  return new Response(JSON.stringify(data), {
    status,
    headers: { 'Content-Type': 'application/json; charset=utf-8' },
  });
}

---

三、前端管理后台（admin.html 关键 JS）

// 加载作品列表
async function loadWorks() {
  const res = await fetch('/api/portfolios?page=1&pageSize=50', {
    credentials: 'same-origin',
  });
  const data = await res.json();
  if (!res.ok) {
    alert('加载失败：' + (data.error || '未知错误'));
    return;
  }
  renderWorksList(data.works);
}

// 创建作品
async function createWork(formData) {
  const res = await fetch('/api/portfolios', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    credentials: 'same-origin',
    body: JSON.stringify(formData),
  });
  const data = await res.json();
  if (!res.ok) {
    alert('创建失败：' + data.error);
    return null;
  }
  return data.work;
}

// 更新作品
async function updateWork(slug, formData) {
  const res = await fetch(`/api/portfolios?slug=${encodeURIComponent(slug)}`, {
    method: 'PUT',
    headers: { 'Content-Type': 'application/json' },
    credentials: 'same-origin',
    body: JSON.stringify(formData),
  });
  return await res.json();
}

// 删除作品
async function deleteWork(slug) {
  if (!confirm(`确定删除作品 "${slug}"？此操作不可撤销。`)) return;
  
  const res = await fetch(`/api/portfolios?slug=${encodeURIComponent(slug)}`, {
    method: 'DELETE',
    credentials: 'same-origin',
  });
  const data = await res.json();
  if (data.ok) {
    alert('删除成功');
    loadWorks();
  } else {
    alert('删除失败：' + data.error);
  }
}

// 切换发布状态
async function togglePublish(slug, currentState) {
  await updateWork(slug, { isPublished: !currentState });
  loadWorks();
}

// 切换精选状态
async function toggleFeatured(slug, currentState) {
  await updateWork(slug, { isFeatured: !currentState });
  loadWorks();
}

---

四、前台首页加载作品（index.html 关键 JS）

async function loadFeaturedWorks() {
  const grid = document.getElementById('works-grid');
  if (!grid) return;
  
  try {
    const res = await fetch('/api/portfolios?featured=true&pageSize=6');
    const data = await res.json();
    
    if (!data.ok || !data.works || data.works.length === 0) {
      grid.innerHTML = '<p class="works-empty">暂无作品</p>';
      return;
    }
    
    grid.innerHTML = data.works.map(w => `
      <a class="work-card" href="/portfolio-detail.html?slug=${encodeURIComponent(w.slug)}">
        ${w.cover ? `<div class="work-cover" style="background-image: url('${w.cover}')"></div>` : '<div class="work-cover-empty"></div>'}
        <div class="work-body">
          <div class="work-meta">${w.type} · ${w.year}${w.area ? ' · ' + w.area : ''}</div>
          <h3 class="work-title">${escapeHtml(w.title)}</h3>
          <p class="work-summary">${escapeHtml(w.summary || '')}</p>
        </div>
      </a>
    `).join('');
  } catch (err) {
    grid.innerHTML = `<p class="works-error">加载失败：${escapeHtml(err.message)}</p>`;
  }
}

function escapeHtml(s) {
  if (typeof s !== 'string') return '';
  return s.replace(/[&<>"']/g, c => ({
    '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;'
  }[c]));
}

loadFeaturedWorks();

---

五、图片上传策略

Edge Function 不支持直接接收 multipart 文件上传（V8 隔离环境限制）。 两个可行方案：

方案 A（推荐）：让用户把图片直接放到 assets/works/ 后部署

后台编辑表单提供"图片 URL"字段，用户事先把图片放到项目的 /assets/works/ 目录，然后填路径 /assets/works/xxx.jpg。

优点：

• 零复杂度
• 图片走 EdgeOne CDN，加载快
• 适合作品集这种"图不频繁变"的场景

缺点：

• 每次新增图片需要重新部署一次

方案 B（进阶）：base64 内联存到 KV

后台支持拖拽上传，前端 FileReader 读为 base64，POST 到 /api/portfolios 时塞到 cover 字段，存到 KV。

// admin.html 上传逻辑
fileInput.addEventListener('change', async (e) => {
  const file = e.target.files[0];
  if (file.size > 500 * 1024) {  // 500KB 上限
    alert('图片不能超过 500KB');
    return;
  }
  const reader = new FileReader();
  reader.onload = (ev) => {
    document.getElementById('cover-preview').src = ev.target.result;
    document.getElementById('cover-data').value = ev.target.result;
  };
  reader.readAsDataURL(file);
});

优点：

• 上传体验好
• 无需重新部署

缺点：

• KV 单条 value 上限 25KB → 图片要严格控制大小
• 大量作品时 KV 存储费用较高

默认采用方案 A，但 README 中告知用户两种方式。

---

六、KV 绑定提醒

部署完成后在 EdgeOne 控制台手动绑定：

项目 → KV 存储 → 绑定命名空间

变量名: PORTFOLIO_WORKS
命名空间: 新建（如 portfolio-works）

绑定后必须重新部署一次，否则 PORTFOLIO_WORKS 全局变量为 undefined。

---

七、首次部署的示例作品种子

部署完成、KV 绑定生效后，自动创建 3 个示例作品作为占位（按用户选定的设计领域）。

示例代码（在某个初始化 API 中调用，例如 /api/portfolios?init=true）：

const SEED_WORKS = {
  landscape: [
    { title: '北方滨海生态公园', type: '滨海景观', year: 2024, area: '120 公顷', isFeatured: true, isPublished: true, summary: '120 公顷北方滨海公园方案设计，回应北方冬季旅游淡季问题' },
    { title: '社区口袋花园改造', type: '城市口袋公园', year: 2023, area: '2,800 ㎡', isFeatured: true, isPublished: true, summary: '老城区废弃绿地激活，让边缘空间重新成为社区中心' },
    { title: '城市湿地修复项目', type: '生态修复', year: 2022, area: '46 公顷', isFeatured: false, isPublished: true, summary: '退耕还湿，重建城市边缘的生物栖息廊道' },
  ],
  graphic: [
    { title: '独立咖啡品牌 VI', type: '品牌设计', year: 2024, isFeatured: true, isPublished: true, summary: '为一家独立咖啡品牌从 Logo 到包装的全套视觉体系' },
    { title: '城市文化季主视觉', type: '活动视觉', year: 2023, isFeatured: true, isPublished: true, summary: '某城市年度文化季的主视觉与衍生物料设计' },
    { title: '独立诗集装帧', type: '书籍装帧', year: 2023, isFeatured: false, isPublished: true, summary: '为青年诗人首部诗集所做的封面与内页设计' },
  ],
  // 其他三个领域（interior / industrial / ux）类似
};

async function seedWorks(field) {
  for (const w of SEED_WORKS[field] || []) {
    await createWork(w);  // 复用上面的 createWork 函数
  }
}

---

八、AI 执行清单

生成 portfolios.js 和管理后台时按顺序确认：

• [ ] 五个方法齐全：GET list / GET one / POST / PUT / DELETE
• [ ] 每个写操作（POST/PUT/DELETE）都同步更新索引（index:all、index:featured、index:by-type:{type}）
• [ ] 公开访问 GET list 时过滤掉 `isPublished: false` 的作品
• [ ] 创建时自动生成 slug，并检查重复
• [ ] 删除时确认对话框（前端）
• [ ] cover/gallery 字段保留 /assets/... 路径，不做 startsWith('http') 兜底判断
• [ ] 首次部署后调用 seed 方法插入 3 个示例作品

---

九、反例：常见错误

❌ 错误：每次列表查询遍历所有 KV key ✅ 正确：维护 index:all 等索引数组

❌ 错误：cover 字段做 startsWith('http') 判断（这是 LandscapeFlow V8 踩过的坑） ✅ 正确：直接信任传入的路径，本地 /assets/... 与远程 URL 一视同仁

❌ 错误：更新 isFeatured 时只改记录、不动 index:featured ✅ 正确：所有可能影响索引的字段变化都同步索引

❌ 错误：DELETE 没有 confirm 确认 ✅ 正确：前端必须二次确认

Portfolio Knowledge — 5 大设计领域的内容套路

何时加载本文件：用户的请求涉及具体设计领域（景观/平面/室内/工业/UX），或需要生成符合行业规范的作品介绍、项目分类、技能标签时。

>

核心价值：本文件是 PortfolioFlow 的"行业大脑"——让生成的作品集像设计师自己写的，不是通用模板套词。所有话术来自 20 年景观行业总工的真实表达 + 跨界设计领域的常识总结。

---

通用结构（5 个领域共用）

每个领域作品集都包含以下信息维度：

{
  "field": "领域名（如：景观）",
  "intro_keywords": ["定位短语词库"],
  "style_descriptors": ["风格描述词库"],
  "deliverable_types": ["典型交付物类型"],
  "skill_tags": ["技能标签词库"],
  "project_types": ["典型项目类型"],
  "career_milestones": ["典型简历里程碑"],
  "ai_prompt_template": "AI 生成项目说明的模板字符串"
}

---

一、景观设计（landscape）

定位短语词库（用于 Hero 副标题）

const LANDSCAPE_INTROS = [
  "让设计回到土地与人居",
  "用最少的介入实现最丰富的体验",
  "在城市与自然之间编织新的对话",
  "为每一片土地写一封情书",
  "以场地的方式重新思考场地",
  "让风、水、光、植物，一起参与设计",
  "用景观回应城市的真实问题"
];

风格描述词库

const LANDSCAPE_STYLES = {
  '现代简约': ['极简几何线条', '强调功能与形式统一', '材料的克制运用', '尺度感的精准把握'],
  '自然生态': ['尊重场地原生肌理', '低介入设计哲学', '本土植物为骨架', '生境网络的细致编织'],
  '古典中式': ['移步换景的空间序列', '借景与框景的传统手法', '诗意栖居的当代诠释', '园林空间的现代转译'],
  '工业复古': ['场地工业记忆的保留', '钢铁与植物的对话', '锈蚀美学的当代运用', '废弃空间的活化'],
  '北方风格': ['抵御冬季严寒的微气候策略', '常绿植物为骨架的全季视效', '雪景作为设计要素'],
  '南方风格': ['雨水管理与海绵理念', '亚热带植物的层次表达', '通风遮阳的气候适应']
};

典型项目类型

社区公园 / 城市口袋公园 / 滨海景观 / 商业街区景观 / 居住区景观 /
生态湿地修复 / 校园景观 / 屋顶花园 / 历史街区改造 / 工业遗址再生 /
儿童友好乐园 / 康养景观 / 道路景观

技能标签词库

总平面设计 · 竖向设计 · 雨水管理 · 植物配置 · 微气候设计 ·
施工图绘制 · 方案汇报 · 投标方案 · 概念深化 · 节点详图 ·
工程造价估算 · 现场配合 · 设计审图 · GB 51192 规范 · LEED 认证

简历里程碑示例

2024 · 主持完成 100 公顷北方滨海公园方案设计，获省级方案竞赛一等奖
2022 · 担任华北某新城景观总规专项负责人，覆盖 12 个子项目
2018 · 一级注册建筑师 / 注册城乡规划师
2015 · 加入 XX 设计院景观所，从设计师晋升至所长助理

AI 生成项目说明模板

【项目概况】
{projectName}定位为{pick(LANDSCAPE_INTROS)}的{type}项目，规划用地约 {area} ㎡。

【设计语言】
方案以"{style}"为核心美学逻辑，注重{pick(styles[style])}。{pick(styles[style])}贯穿全场地，确保设计意图能在不同尺度上一致呈现。

【设计目标】
本项目的核心目标是：{goal}。围绕这一目标，方案在功能策划、空间序列、植物配置、材料选型四个维度展开系统性设计。

【设计策略】
其一，以人群行为为驱动重组功能分区，强化亲子、运动、静憩三类活动的边界与互动。
其二，引入微气候调节策略，通过乔木阵列、水体降温、铺装透水提升场地全年舒适度。
其三，植物配置遵循季相主题原则，确保四季皆有视觉焦点。
其四，材料选型立足耐久性与本土性，重点回应当地气候对工艺的特殊要求。

【创新点】
本方案在传统{type}设计逻辑基础上，叠加全流程数字化辅助决策机制，将设计师精力从制图与排版中释放出来，回归对土地与人居的本质思考。

---

二、平面设计（graphic）

定位短语词库

const GRAPHIC_INTROS = [
  "用视觉讲一个值得记住的故事",
  "设计是信息与情感的精准翻译",
  "让品牌成为可被识别的态度",
  "在二维空间里造一个有重量的世界",
  "字体、色彩、构图——每一寸都是表达",
  "为不被看见的设计，争取一秒注意力"
];

风格描述词库

const GRAPHIC_STYLES = {
  '极简主义': ['留白即设计', '字体的极致运用', '色彩的克制选择', '信息层级的精准把控'],
  '复古印刷': ['网点、油墨与做旧', '老式排版的当代演绎', '手作质感的数字模拟'],
  '现代几何': ['模数化的网格系统', '色块与几何的构成游戏', '欧洲瑞士风格的当代延续'],
  '潮流插画': ['手绘的人格化表达', '渐变与噪点的当代审美', '社交媒体友好的视觉语言'],
  '日式美学': ['和风留白与季节感', '汉字与假名的层次美', '极简但充满情绪']
};

典型项目类型

品牌 VI / Logo 设计 / 海报系列 / 书籍装帧 / 包装设计 /
画册设计 / 字体设计 / 插画作品 / 展览视觉 / 产品包装 /
活动主视觉 / 报纸广告 / 邮票设计

技能标签词库

品牌战略 · Logo 设计 · 字体设计 · 版式设计 · 印刷工艺 ·
Adobe 全家桶 · Figma · Procreate · 包装结构 · 印前流程 ·
色彩理论 · 视觉系统 · 信息可视化 · 摄影统筹 · 插画

---

三、室内设计（interior）

定位短语词库

const INTERIOR_INTROS = [
  "空间是生活的容器，也是情绪的容器",
  "用材料、光线、尺度，雕刻日常",
  "让每个角落都值得驻足",
  "从生活方式出发，反向定义空间",
  "设计是把好生活，安进具体的房间",
  "我相信空间会改变住在里面的人"
];

风格描述词库

const INTERIOR_STYLES = {
  '现代简约': ['白墙木地板的克制', '隐藏式收纳的极致', '少而精的家具陈设'],
  '日式侘寂': ['原木与亚麻的质感对话', '不完美中的完整', '光影作为材料的一部分'],
  '北欧风格': ['浅色木材与白墙的温暖', '功能主义家具', '自然光的充分利用'],
  '工业风': ['裸露的混凝土与钢架', '皮革与金属的搭配', '空间的开放感'],
  '新中式': ['传统纹样的当代转化', '深色硬木与素色软装', '禅意空间的现代演绎'],
  '法式优雅': ['线条与曲线的雕刻感', '香槟金与浅木色', '生活仪式感的强调']
};

典型项目类型

住宅设计 / 公寓改造 / 别墅设计 / 民宿设计 / 咖啡馆 /
餐厅 / 办公空间 / 联合办公 / 零售门店 / 美容空间 /
展厅设计 / 会所空间 / 健身房 / 培训机构

技能标签词库

平面规划 · 软装搭配 · 材料应用 · 灯光设计 · 家具选型 ·
施工图绘制 · 3D 效果图 · SketchUp · V-Ray · AutoCAD ·
现场施工 · 风水堪舆 · 收纳系统 · 预算控制 · 智能家居

---

四、工业设计（industrial）

定位短语词库

const INDUSTRIAL_INTROS = [
  "产品是问题的回答，不是形式的炫技",
  "好的设计让人忘记设计本身",
  "为日常物品争取一点诗意",
  "从功能出发，止于形式之美",
  "我相信形式追随用户的真实需求",
  "用毫米计的克制，做更人性的产品"
];

风格描述词库

const INDUSTRIAL_STYLES = {
  'Dieter Rams 极简': ['Less, but better', '功能优先于装饰', '色彩与材料的诚实表达'],
  '日式人文': ['物哀美学的当代演绎', '触感与温度的考究', '使用习惯的细腻洞察'],
  '北欧温暖': ['天然材料的运用', '柔和的几何形态', '生活方式产品的定位'],
  '硬核工业': ['结构外显的诚实美学', '金属与机械感', '高性能产品定位'],
  '生活美学': ['日常物品的提升', '材料与工艺的讲究', '可持续设计理念']
};

典型项目类型

3C 数码产品 / 家电产品 / 家居用品 / 厨房用具 / 文具设计 /
医疗器械 / 智能硬件 / 玩具设计 / 运动器材 / 出行工具 /
公共设施 / 灯具设计 / 卫浴产品 / 概念产品

技能标签词库

草图绘制 · Rhino · KeyShot · SolidWorks · 结构设计 ·
材料工艺 · 用户研究 · 原型制作 · 3D 打印 · CMF 设计 ·
人机工程学 · 可制造性分析 · 产品摄影 · 设计专利

---

五、UX/UI 设计（ux）

定位短语词库

const UX_INTROS = [
  "为复杂的系统设计简单的入口",
  "让每一次点击都有理由",
  "好的体验是看不见的体验",
  "设计是与用户的一场长期对话",
  "从问题出发，止于优雅的解决",
  "在数据与直觉之间寻找平衡"
];

风格描述词库

const UX_STYLES = {
  '极简清爽': ['白底大留白', '排版优先于装饰', '色彩仅作功能区分'],
  '玻璃拟态': ['毛玻璃与透明分层', '柔和的高光与阴影', '深色背景的科技感'],
  '新拟物': ['软阴影与凸起感', '现实物体的数字隐喻', '触感丰富'],
  '科技深色': ['深色底 + 高对比', '荧光色点缀', '数据可视化友好'],
  '游戏化': ['色彩鲜艳与动效丰富', '插画与图标统一', '正反馈强化'],
  'Apple 风格': ['SF 字体与系统色彩', '极致的对齐与间距', '动效的克制运用']
};

典型项目类型

SaaS 后台 / 移动 App / 小程序 / 官网 / 落地页 /
设计系统 / 数据看板 / 智能硬件交互 / 车载 HMI / 智能电视 ·
增长实验 / A/B 测试 / 用户研究 / 信息架构 / 可访问性设计

技能标签词库

用户研究 · 信息架构 · 交互设计 · 视觉设计 · 原型设计 ·
Figma · Sketch · Principle · Framer · 设计系统 ·
A/B 测试 · 数据分析 · 可用性测试 · 服务设计 · 可访问性

---

AI 生成项目说明的通用模板（5 个领域统一调用）

function generateProjectBrief(field, data) {
  const { projectName, projectType, style, area, role, duration, highlights } = data;
  
  const lib = KNOWLEDGE_BASE[field];
  const intro = pick(lib.intros);
  const styleDesc = pick(lib.styles[style] || lib.styles[Object.keys(lib.styles)[0]]);
  
  // 5 个领域共用的模板骨架
  return `
【项目背景】
${projectName} 是一个 ${projectType} 项目${area ? `，规模为 ${area}` : ''}${role ? `，我担任 ${role}` : ''}${duration ? `，历时 ${duration}` : ''}。

【设计语言】
${intro}。本项目采用 ${style} 风格，注重${styleDesc}。

【设计过程】
${highlights || `从用户研究出发，经历概念发散、方案选择、细节打磨三个阶段。每一个决策都经过${pick(['用户测试', '专家评审', '数据验证', '场地核验'])}的检验。`}

【设计成果】
${pick([
  '最终方案在功能与美学之间找到了恰当的平衡，',
  '设计成果获得了客户与最终用户的高度认可，',
  '方案在多轮迭代中逐渐清晰，',
])}成为我设计生涯中一次珍贵的实践。

— 由 PortfolioFlow 生成
  `.trim();
}

---

6 个示例作品（每个领域用于演示）

如果用户没有提供作品数据，自动生成以下 3 个示例作品作为占位（按用户选定的领域）：

景观示例

[
  { title: '北方滨海生态公园', type: '滨海景观', year: 2024, area: '120 公顷' },
  { title: '社区口袋花园改造', type: '城市口袋公园', year: 2023, area: '2,800 ㎡' },
  { title: '城市湿地修复项目', type: '生态修复', year: 2022, area: '46 公顷' }
]

平面示例

[
  { title: '某独立咖啡品牌 VI', type: '品牌设计', year: 2024 },
  { title: '城市文化季主视觉', type: '活动视觉', year: 2023 },
  { title: '独立诗集装帧设计', type: '书籍装帧', year: 2023 }
]

室内示例

[
  { title: '90 ㎡ 极简两居改造', type: '住宅设计', year: 2024, area: '90 ㎡' },
  { title: '城市边缘的山居民宿', type: '民宿设计', year: 2023, area: '420 ㎡' },
  { title: '联合办公空间设计', type: '商业空间', year: 2022, area: '1,200 ㎡' }
]

工业示例

[
  { title: '便携咖啡器具系列', type: '生活产品', year: 2024 },
  { title: '智能家居控制中枢', type: '智能硬件', year: 2023 },
  { title: '老年人友好医疗设备', type: '医疗产品', year: 2022 }
]

UX 示例

[
  { title: '某 SaaS 数据看板重设计', type: 'SaaS 后台', year: 2024 },
  { title: '健身 App 新用户引导优化', type: '移动 App', year: 2023 },
  { title: '车载 HMI 系统设计', type: '车载交互', year: 2023 }
]

---

AI 执行检查清单

收到生成请求后，AI 必须按顺序确认：

• [ ] 已识别用户的设计领域（5 个之一）
• [ ] 已加载对应的 INTROS / STYLES / TYPES / TAGS 词库
• [ ] Hero 副标题从 INTROS 中随机选 1 条（每次生成结果应不同）
• [ ] 风格描述从对应 STYLES[style] 中随机抽 2-3 条短语组合
• [ ] 技能标签从 TAGS 中选 8-12 条
• [ ] 如果用户未提供作品，使用预设 3 个示例作品
• [ ] 生成的所有文案都使用对应领域的专业术语，不要使用其他领域的话术

---

反例：不要这么做

❌ 错误：用景观领域的"植物配置"描述 UX 项目 ❌ 错误：把"用户研究"作为景观项目的核心环节 ❌ 错误：所有领域都用同一个 Hero 副标题"用设计改变世界" ❌ 错误：把所有项目都套用同一个项目说明模板

✅ 正确：每个领域有独立词库，词库内部再随机组合，让 100 个用户生成出 100 份不同的作品集

Stats & KV — 访问统计与数据看板

何时加载本文件：用户的请求涉及访问量、PV、UV、热门作品、统计看板、数据可视化、访客分析等。

---

一、统计能力总览

PortfolioFlow 在 PORTFOLIO_STATS KV 命名空间下维护以下数据：

total:pv             → 总浏览量（数字）
total:uv             → 总独立访客数（数字，按 IP+UA hash 去重）
total:contacts       → "联系我"按钮被点击次数

work:{slug}:pv       → 单个作品的浏览量
work:{slug}:uv       → 单个作品的独立访客数

daily:{YYYY-MM-DD}   → 当日 PV
daily-uv:{YYYY-MM-DD} → 当日 UV (Set 形式存 visitor hash)

ranking:top10         → Top 10 热门作品 slug 数组（每小时聚合更新）
referrer:{domain}     → 各来源域名带来的访问数

---

二、完整代码

functions/api/stats.js

/**
 * Portfolio Stats API
 *
 * 路由：
 *   POST /api/stats { event: 'page_view', slug?, referrer? }  → 记录访问（公开）
 *   POST /api/stats { event: 'contact_click' }                → 记录联系点击
 *   GET  /api/stats?action=summary                            → 看板汇总（需登录）
 *   GET  /api/stats?action=daily&days=30                      → 最近 N 天日 PV（需登录）
 *   GET  /api/stats?action=top&n=10                           → Top 作品（需登录）
 *
 * 注：GET 类查询的鉴权由 _middleware.js 完成
 */

const enc = new TextEncoder();

export async function onRequest({ request }) {
  if (typeof PORTFOLIO_STATS === 'undefined') {
    return jsonResponse({ error: 'KV namespace PORTFOLIO_STATS not bound' }, 500);
  }
  
  const url = new URL(request.url);
  
  if (request.method === 'POST') {
    const body = await request.json().catch(() => ({}));
    return await handleEvent(body, request);
  }
  
  if (request.method === 'GET') {
    const action = url.searchParams.get('action') || 'summary';
    switch (action) {
      case 'summary': return await getSummary();
      case 'daily':   return await getDailyTrend(parseInt(url.searchParams.get('days') || '30', 10));
      case 'top':     return await getTopWorks(parseInt(url.searchParams.get('n') || '10', 10));
      default:        return jsonResponse({ error: 'Unknown action' }, 400);
    }
  }
  
  return jsonResponse({ error: 'Method not allowed' }, 405);
}

// === 事件记录 ===

async function handleEvent(body, request) {
  const { event, slug, referrer } = body;
  if (!event) return jsonResponse({ error: 'event required' }, 400);
  
  const today = formatDate(new Date());
  const visitorHash = await getVisitorHash(request);
  
  switch (event) {
    case 'page_view':
      await incr('total:pv');
      await incr(`daily:${today}`);
      
      // UV：检查访客 hash 是否当天已记录
      const uvKey = `daily-uv:${today}`;
      const uvList = (await PORTFOLIO_STATS.get(uvKey, 'json')) || [];
      if (!uvList.includes(visitorHash)) {
        uvList.push(visitorHash);
        // 限制每天 UV 集合最多 10000，防止 value 超出 KV 上限
        if (uvList.length > 10000) uvList.shift();
        await PORTFOLIO_STATS.put(uvKey, JSON.stringify(uvList));
        await incr('total:uv');
      }
      
      // 单作品 PV
      if (slug) {
        await incr(`work:${slug}:pv`);
        const workUvKey = `work:${slug}:uv-list`;
        const workUvList = (await PORTFOLIO_STATS.get(workUvKey, 'json')) || [];
        if (!workUvList.includes(visitorHash)) {
          workUvList.push(visitorHash);
          if (workUvList.length > 5000) workUvList.shift();
          await PORTFOLIO_STATS.put(workUvKey, JSON.stringify(workUvList));
          await incr(`work:${slug}:uv`);
        }
      }
      
      // 来源统计
      if (referrer) {
        try {
          const domain = new URL(referrer).hostname;
          if (domain && !domain.endsWith(new URL(request.url).hostname)) {
            await incr(`referrer:${domain}`);
          }
        } catch { /* invalid referrer URL */ }
      }
      
      return jsonResponse({ ok: true });
    
    case 'contact_click':
      await incr('total:contacts');
      return jsonResponse({ ok: true });
    
    default:
      return jsonResponse({ error: 'Unknown event' }, 400);
  }
}

// === 看板查询 ===

async function getSummary() {
  const pv = parseInt((await PORTFOLIO_STATS.get('total:pv')) || '0', 10);
  const uv = parseInt((await PORTFOLIO_STATS.get('total:uv')) || '0', 10);
  const contacts = parseInt((await PORTFOLIO_STATS.get('total:contacts')) || '0', 10);
  
  // 今日数据
  const today = formatDate(new Date());
  const todayPv = parseInt((await PORTFOLIO_STATS.get(`daily:${today}`)) || '0', 10);
  const todayUvList = (await PORTFOLIO_STATS.get(`daily-uv:${today}`, 'json')) || [];
  
  return jsonResponse({
    ok: true,
    summary: {
      totalPV: pv,
      totalUV: uv,
      totalContactClicks: contacts,
      todayPV: todayPv,
      todayUV: todayUvList.length,
      contactConversion: pv > 0 ? `${((contacts / pv) * 100).toFixed(2)}%` : '0%',
    },
  });
}

async function getDailyTrend(days) {
  days = Math.min(Math.max(days, 1), 90);  // 限制 1-90 天
  
  const result = [];
  const today = new Date();
  
  for (let i = days - 1; i >= 0; i--) {
    const d = new Date(today);
    d.setDate(d.getDate() - i);
    const dateStr = formatDate(d);
    
    const pv = parseInt((await PORTFOLIO_STATS.get(`daily:${dateStr}`)) || '0', 10);
    const uvList = (await PORTFOLIO_STATS.get(`daily-uv:${dateStr}`, 'json')) || [];
    
    result.push({
      date: dateStr,
      pv,
      uv: uvList.length,
    });
  }
  
  return jsonResponse({ ok: true, daily: result });
}

async function getTopWorks(n) {
  n = Math.min(Math.max(n, 1), 50);
  
  // 取所有作品 slug
  if (typeof PORTFOLIO_WORKS === 'undefined') {
    return jsonResponse({ error: 'PORTFOLIO_WORKS KV not bound, cannot determine work list' }, 500);
  }
  
  const allSlugs = (await PORTFOLIO_WORKS.get('index:all', 'json')) || [];
  
  // 取每个作品的 PV
  const stats = await Promise.all(allSlugs.map(async (slug) => {
    const pv = parseInt((await PORTFOLIO_STATS.get(`work:${slug}:pv`)) || '0', 10);
    const uv = parseInt((await PORTFOLIO_STATS.get(`work:${slug}:uv`)) || '0', 10);
    const workData = await PORTFOLIO_WORKS.get(`work:${slug}`, 'json');
    return { slug, title: workData?.title || slug, pv, uv };
  }));
  
  // 按 PV 倒序排
  stats.sort((a, b) => b.pv - a.pv);
  
  return jsonResponse({ ok: true, top: stats.slice(0, n) });
}

// === 工具 ===

async function incr(key) {
  const current = parseInt((await PORTFOLIO_STATS.get(key)) || '0', 10);
  await PORTFOLIO_STATS.put(key, String(current + 1));
}

async function getVisitorHash(request) {
  // 用 IP + User-Agent 简单生成访客指纹
  const ip = request.headers.get('CF-Connecting-IP')
    || request.headers.get('X-Forwarded-For')
    || request.headers.get('X-Real-IP')
    || '0.0.0.0';
  const ua = request.headers.get('User-Agent') || '';
  const fingerprint = `${ip}::${ua}`;
  
  const buf = await crypto.subtle.digest('SHA-256', enc.encode(fingerprint));
  return btoa(String.fromCharCode(...new Uint8Array(buf))).substring(0, 12);
}

function formatDate(d) {
  const y = d.getFullYear();
  const m = String(d.getMonth() + 1).padStart(2, '0');
  const day = String(d.getDate()).padStart(2, '0');
  return `${y}-${m}-${day}`;
}

function jsonResponse(data, status = 200) {
  return new Response(JSON.stringify(data), {
    status,
    headers: { 'Content-Type': 'application/json; charset=utf-8' },
  });
}

---

三、前端埋点（index.html / portfolio-detail.html）

// 页面加载时埋点（首页或作品详情页都用同一套）
(async function trackPageView() {
  try {
    const slug = new URLSearchParams(location.search).get('slug') || null;
    await fetch('/api/stats', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        event: 'page_view',
        slug,
        referrer: document.referrer || null,
      }),
      // 注意：不要 await 阻塞渲染，用 keepalive 后台发送
      keepalive: true,
    });
  } catch (e) { /* 静默失败，不影响用户体验 */ }
})();

// "联系我"按钮点击埋点
document.querySelectorAll('[data-event="contact-click"]').forEach(btn => {
  btn.addEventListener('click', () => {
    fetch('/api/stats', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ event: 'contact_click' }),
      keepalive: true,
    }).catch(() => {});
  });
});

---

四、管理后台看板（admin.html）

async function loadDashboard() {
  try {
    // 并行加载三类数据
    const [summaryRes, dailyRes, topRes] = await Promise.all([
      fetch('/api/stats?action=summary', { credentials: 'same-origin' }),
      fetch('/api/stats?action=daily&days=30', { credentials: 'same-origin' }),
      fetch('/api/stats?action=top&n=10', { credentials: 'same-origin' }),
    ]);
    
    const summary = (await summaryRes.json()).summary;
    const daily = (await dailyRes.json()).daily;
    const top = (await topRes.json()).top;
    
    // 渲染汇总卡片
    document.getElementById('stat-total-pv').textContent = summary.totalPV.toLocaleString();
    document.getElementById('stat-total-uv').textContent = summary.totalUV.toLocaleString();
    document.getElementById('stat-today-pv').textContent = summary.todayPV.toLocaleString();
    document.getElementById('stat-today-uv').textContent = summary.todayUV.toLocaleString();
    document.getElementById('stat-contacts').textContent = summary.totalContactClicks.toLocaleString();
    document.getElementById('stat-conversion').textContent = summary.contactConversion;
    
    // 渲染近 30 天趋势（用 SVG 简单画一条折线）
    renderDailyChart(daily);
    
    // 渲染 Top 10 作品列表
    const topList = document.getElementById('top-works-list');
    topList.innerHTML = top.map((w, i) => `
      <li>
        <span class="rank">#${i + 1}</span>
        <a href="/portfolio-detail.html?slug=${encodeURIComponent(w.slug)}">${w.title}</a>
        <span class="metric">PV ${w.pv} · UV ${w.uv}</span>
      </li>
    `).join('');
  } catch (err) {
    console.error('Dashboard load failed:', err);
  }
}

// 用纯 SVG 画 30 天趋势折线图（不依赖任何图表库）
function renderDailyChart(daily) {
  const svg = document.getElementById('chart-daily');
  if (!svg || !daily.length) return;
  
  const W = 800, H = 200, PAD = 30;
  const maxPV = Math.max(...daily.map(d => d.pv), 1);
  const stepX = (W - 2 * PAD) / (daily.length - 1 || 1);
  
  const points = daily.map((d, i) => {
    const x = PAD + i * stepX;
    const y = H - PAD - (d.pv / maxPV) * (H - 2 * PAD);
    return `${x},${y}`;
  }).join(' ');
  
  svg.setAttribute('viewBox', `0 0 ${W} ${H}`);
  svg.innerHTML = `
    <polyline points="${points}"
      fill="none" stroke="var(--primary)" stroke-width="2"/>
    ${daily.map((d, i) => {
      const x = PAD + i * stepX;
      const y = H - PAD - (d.pv / maxPV) * (H - 2 * PAD);
      return `<circle cx="${x}" cy="${y}" r="3" fill="var(--primary)"/>`;
    }).join('')}
    <text x="${PAD}" y="${H - 5}" font-size="10" fill="var(--text-faint)">${daily[0].date}</text>
    <text x="${W - PAD - 60}" y="${H - 5}" font-size="10" fill="var(--text-faint)">${daily[daily.length - 1].date}</text>
  `;
}

loadDashboard();

---

五、KV 绑定提醒

部署完成后在 EdgeOne 控制台手动绑定：

项目 → KV 存储 → 绑定命名空间

变量名: PORTFOLIO_STATS
命名空间: 新建（如 portfolio-stats）

绑定后必须重新部署一次让 PORTFOLIO_STATS 全局变量生效。

---

六、AI 执行清单

生成 stats.js、前端埋点、看板时按顺序确认：

• [ ] 包含 6 个 action：page_view / contact_click + summary / daily / top
• [ ] PV 埋点使用 keepalive: true 后台发送，不阻塞页面渲染
• [ ] UV 通过 IP+UA 哈希去重，每日重置集合
• [ ] UV 集合上限保护（10000/5000），防止 KV value 超限
• [ ] 看板看板用纯 SVG 画图，不引入任何图表库
• [ ] Top 作品依赖 PORTFOLIO_WORKS KV 已绑定
• [ ] 看板路由通过 middleware 鉴权（需登录）

---

七、反例

❌ 错误：每个 PV 都同步等待响应再渲染页面 ✅ 正确：keepalive: true 后台静默发送

❌ 错误：UV 集合无上限，最终超过 KV value 25KB 限制 ✅ 正确：超过上限时 shift() 移除最老条目

❌ 错误：用 echarts/chart.js 等图表库（增加包体积） ✅ 正确：原生 SVG 画折线图，简洁专业

❌ 错误：referrer 不做来源域名过滤（自家域名也算外部来源） ✅ 正确：过滤掉与当前 host 相同的 referrer