1. 项目概述一个由AI驱动的技术官网是如何诞生的最近在折腾一个挺有意思的项目叫DollhouseMCP。简单来说它是一个专注于AI角色Persona管理和智能体Agent编排的平台。而我手头的任务就是为这个平台搭建一个对外的官方网站。你可能觉得一个官网嘛不就是写写HTML、CSS搞点静态页面但这次我想分享的远不止这些。整个项目从设计、开发到内容创作几乎全程由AI辅助完成我自己则更像一个“导演”负责设定目标、审核结果和把控方向。这背后涉及到的工具链和工作流对于任何想用AI提升开发效率的开发者来说都有不少值得借鉴的地方。这个网站dollhousemcp.com的核心目标很明确第一作为产品门面清晰传达DollhouseMCP是什么、能做什么第二作为一个技术博客分享我们在开发MCP服务器、移动端工作流、CI/CD调试等过程中踩过的坑和解决方案第三它本身就是一个“元开发”案例用来验证和展示DollhouseMCP平台在自动化构建与内容生成方面的能力。如果你对AI辅助开发、现代前端架构或者如何高效管理一个技术内容站点感兴趣那接下来的内容应该能给你带来一些实实在在的启发。2. 核心思路与技术选型为什么是“静态站点AI生成”2.1 摒弃传统CMS拥抱Git-Based工作流在项目启动前我首先思考的是内容管理方式。传统的WordPress或Headless CMS固然强大但对于一个以技术文档和博客为核心、且需要高度定制化和版本控制的站点来说它们显得有些笨重。我们最终选择了基于Git的静态站点生成思路。所有内容包括博客文章、文档甚至页面原型都以Markdown或HTML文件的形式存放在代码仓库里。这样做有几个显著优势版本控制与协作透明化每一次内容更新、样式修改都对应一次Git提交谁在什么时候改了什么都一清二楚。这对于技术团队的内容协作来说是天生的友好。回滚到任何一个历史版本也只需要一条git checkout命令。极致的性能与安全性生成的最终产物是纯粹的HTML、CSS和JavaScript文件可以直接部署到任何静态托管服务如Vercel, Netlify, GitHub Pages。没有数据库查询没有后端逻辑页面加载速度极快也几乎不存在SQL注入之类的安全漏洞。与开发流程无缝集成内容更新可以像代码更新一样走完整的Pull Request审查流程。我们可以设置CI/CD在内容合并后自动构建并部署站点确保了发布流程的严谨性。注意这种模式的关键在于需要从一开始就设计好清晰的内容目录结构和文件命名规范。我们采用了类似许多静态站点生成器如Hugo, Jekyll的约定将博客文章放在_blog_posts/目录下并使用YAML Frontmatter来管理文章的元数据如标题、日期、摘要、标签。这为未来可能的自动化工具迁移预留了接口。2.2 工具链Claude Cursor 如何重塑开发体验技术选型的另一个核心是开发工具。这个项目几乎是我使用“AI结对编程”密度最高的一次主要依赖两样东西Anthropic的Claude模型和Cursor编辑器。Claude作为“首席架构师”与“内容写手”Claude特别是Claude 3系列模型在理解复杂技术需求、进行系统设计以及生成高质量文本方面表现惊人。我的工作流程通常是先用自然语言向Claude描述我需要一个什么功能或组件比如“设计一个深色主题切换按钮要求符合WCAG可访问性标准”它会给出包含HTML结构、CSS样式甚至JavaScript交互逻辑的完整方案。对于博客内容我可以给出主题和大纲Claude能快速生成结构清晰、技术细节准确的初稿我只需在此基础上进行润色和事实校正。Cursor编辑器作为“超级执行终端”Cursor不仅仅是VSCode的一个分支它深度集成了AI能力。我大量使用了它的“Chat”和“Edit”功能。例如在浏览一个复杂的CSS文件时我可以直接选中一段代码问Cursor“解释一下这段Grid布局的逻辑”或者“如何优化这段选择器的性能”。更强大的是“Edit”指令我可以输入“将这个组件的padding改用设计令牌中的变量”Cursor能精准地定位并修改代码大大减少了机械性查找替换的工作。DollhouseMCP自身作为“质量检验员”这是最有趣的一环。我们利用DollhouseMCP平台创建了一个专门用于“代码审查”和“内容质量检查”的AI角色。在提交代码或文章前我会让这个角色通读一遍它能够以另一个“AI开发者”的视角指出可能存在的样式不一致、语义化标签使用不当、甚至是文章中的逻辑断层。这种“AI自我审查”的机制有效避免了单一AI生成内容可能带来的盲点。2.3 设计系统先行建立可复用的视觉语言很多个人或小团队项目容易犯的错误是“边做边设计”导致后期样式混乱维护成本陡增。我们在写第一行页面代码之前花了相当精力在构建一个完整的设计系统上。这体现在项目结构中的styles/目录和style-guide.html文件。以“设计令牌Design Tokens”为核心所有颜色、字体、间距、边框半径等视觉属性都被抽象为CSS自定义属性变量定义在tokens.css中。例如:root { --color-primary: #7c3aed; --color-surface: #ffffff; --color-surface-dark: #1a1a1a; --spacing-unit: 0.25rem; /* 4px */ --spacing-4: calc(var(--spacing-unit) * 4); /* 16px */ }这样做的好处是当需要调整品牌色或整体间距时只需修改令牌文件所有引用这些令牌的组件都会自动更新保证了绝对的视觉一致性。组件化CSS架构我们的CSS文件组织严格遵循了从抽象到具体的层次tokens.css设计令牌一切样式的基础。base.css重置样式reset和默认元素样式如body,h1-h6,a。components.css可复用的UI组件如按钮、卡片、导航栏、表单等。每个组件都只使用设计令牌来定义样式与具体页面解耦。utilities.css工具类如.text-center,.mt-4margin-top: var(--spacing-4)。用于快速微调但提倡优先使用组件。pages/目录存放页面特有的样式覆盖尽量保持精简。深色模式的优雅实现深色模式不是简单的颜色反转。我们在tokens.css中利用CSS媒体查询media (prefers-color-scheme: dark)和自定义属性为所有颜色令牌定义了亮色和深色两套值。组件样式只引用如--color-surface这样的令牌而令牌的实际值会根据系统主题自动切换。这比在每个组件里写媒体查询要高效和可靠得多。3. 核心开发流程与实操要点3.1 从设计稿到可交互原型的快速迭代我们并没有使用Figma或Sketch从头绘制高保真设计稿。相反流程更加敏捷和“代码优先”概念碰撞与内容提纲我会和Claude进行对话明确某个页面如首页、博客列表页需要展示哪些信息模块它们的优先级如何。生成HTML/CSS原型基于讨论结果我直接让Claude或Cursor生成一个基础的HTML文件并引用我们已有的设计系统styles/下的CSS。这个原型文件会放在mockups/目录下例如Dollhouse-Sprite-Sheet.html就是一个用于测试图标系统的原型。实时浏览器预览与调整使用python -m http.server启动一个本地服务器在浏览器中实时查看原型。结合浏览器开发者工具直接调整CSS变量或样式效果立竿见影。提炼与抽象当某个原型中的组件比如一个特性展示卡片被验证可行后我会将其HTML结构和CSS样式从原型文件中剥离重构并正式添加到components.css和style-guide.html中成为设计系统的一部分。这种做法的最大好处是设计决策能立刻用代码验证避免了设计稿与最终实现效果之间的落差。style-guide.html文件就是这个过程的产物它不是一个静态的PDF规范而是一个随时可运行、可交互的组件库文档。3.2 博客引擎的轻量级实现作为一个技术博客文章管理系统是核心。我们没有引入复杂的静态站点生成器而是采用了一种极简但完全够用的方案文件结构所有博客文章都是_blog_posts/目录下的Markdown文件。文件名遵循YYYY-MM-DD-slug.md的格式便于按日期排序和管理。Frontmatter元数据每篇文章开头用YAML格式定义元数据这像是文章的“身份证”。--- title: 调试MCP服务器常见错误与解决思路 date: 2024-05-15 summary: 本文记录了在开发和部署Model Context Protocol服务器过程中遇到的典型连接、认证和资源加载问题并提供了一套实用的排查清单。 tags: [mcp, debugging, ai-tools] ---这些元数据未来可以很容易地被一个简单的JavaScript脚本读取用来生成博客首页的文章列表、标签云或RSS订阅源。内容撰写与AI辅助技术博客要求内容准确、逻辑清晰。我的典型流程是确定主题与大纲我自己构思或与Claude讨论后确定文章的核心论点和结构。生成初稿将大纲和关键要点比如具体的错误日志、代码片段提供给Claude让它生成文章初稿。AI在组织语言、确保技术描述连贯性上非常高效。深度编辑与“注入灵魂”这是最关键的一步。AI初稿往往正确但平淡。我会通读全文做以下几件事加入个人经验在描述某个错误时补充我当时的第一反应、走过的弯路以及最终如何灵光一现找到解决方案的“顿悟时刻”。强化实操细节AI可能会说“需要检查配置文件”我会把它改成“打开你项目根目录下的server.py找到第42行附近的host参数确保它不是127.0.0.1而是0.0.0.0。”添加注意事项与坑点在步骤旁边加入警告框提示读者可能忽略的细微之处。优化可读性拆分过长的段落增加小标题将复杂的解释用类比说清楚比如把MCP协议比作“AI模型的外接硬盘盒”。SEO与可访问性基础在AI生成HTML结构时我会特别提示它注意语义化标签多用article,section,header少用无意义的div和图片的alt属性。文章开头的summary不仅用于页面摘要也作为搜索引擎的description。合理的h1到h6标题层级对于SEO和屏幕阅读器用户都至关重要。3.3 “元开发”案例的实践用AI构建AI工具的官网项目文档中提到的“Meta-Development Case Study”是这个项目最独特的价值点。它记录了我们如何利用尚在开发中的DollhouseMCP平台来加速这个官网本身的建设。这不是一个空洞的概念而是有具体数据和方法的时间节省分析我们粗略估计在网站基础框架搭建、组件开发、初始内容填充这几个阶段AI辅助带来了85-90%的效率提升。例如一个符合设计规范的“博客卡片”组件从描述需求到得到可用的代码传统手动编码可能需要30分钟到1小时包括思考、编写、调试。而通过向Claude描述需求“一个包含图片、标题、摘要、日期和标签的卡片悬停有效果在移动端堆叠排列”我能在5分钟内获得一个90分可用的版本剩下的10分钟用于微调样式和测试响应式。具体任务分解代码生成如前所述的组件、页面结构、工具函数。内容创作技术博客初稿、文档字符串、配置说明。代码重构与优化将重复的CSS模式抽象成工具类优化选择器性能。问题排查将浏览器控制台报错信息丢给AI它能快速给出可能的原因和修复建议。验证平台能力这个过程本身就是一个对DollhouseMCP平台的“吃狗粮”测试。我们在构建官网时遇到的挑战、对AI助手提出的需求都反向驱动了平台功能的改进。例如我们发现需要一种更结构化的方式来管理多轮对话中产生的设计决策这促使我们改进了平台中“项目上下文记忆”的机制。实操心得不要指望AI一次性能给出完美答案。最有效的工作模式是“快速迭代”。先让它生成一个基础版本然后在浏览器中测试发现问题后将问题最好附带截图或错误信息反馈给AI让它进行修正。经过2-3轮这样的交互你通常能得到一个非常健壮的解决方案。这比你自己从头调试要快得多。4. 部署、维护与未来规划4.1 极简部署策略由于是纯静态站点部署变得异常简单。我们目前采用的方式是将代码仓库推送到GitHub。使用Vercel或Netlify等平台进行关联。这些平台能监听指定分支如main的推送。每次推送后平台会自动运行构建命令我们目前没有构建步骤直接部署源文件并将产物发布到CDN上生成一个唯一的预览URL或更新生产域名。整个过程完全自动化从代码提交到线上更新通常在1分钟内完成。这为内容的快速迭代提供了基础设施保障。4.2 内容维护与团队协作即使是一个人的项目我们也模拟了团队协作的规范分支策略任何新功能如添加一个页面或新文章都在新的特性分支feat/xxx上开发。提交信息使用约定式提交Conventional Commits如feat: add dark mode toggle component或docs: publish post about mcp debugging。这便于以后生成更新日志。Pull Request完成开发后发起PR描述更改内容。虽然目前没有其他 reviewer但这个流程迫使我自己在合并前重新审视一遍代码和内容的改动相当于一次自我代码审查。对于博客内容我们计划引入一个轻量级的编辑工作流。非技术编辑可以在GitHub上直接修改Markdown文件GitHub的Web编辑器对Markdown很友好通过PR提交修改由技术负责人合并。这比操作任何CMS的后台都更清晰、可追溯。4.3 阶段性路线图与扩展思考根据项目文档中的规划网站的发展分为几个阶段Phase 1: 静态文档站点当前核心目标是跑通从内容创作到部署的完整流程验证设计系统并发布首批高质量的技术博客。目前这一阶段已基本完成。Phase 2: 交互式演示与Playground这是提升网站吸引力和实用性的关键。我们计划集成代码沙盒在博客中嵌入可交互的代码示例让读者可以直接在浏览器里运行和修改关于MCP服务器配置的代码片段。构建“角色”配置模拟器一个可视化工具让访客可以简单拖拽配置模拟DollhouseMCP中AI角色的创建过程并生成对应的配置文件。这能极大地降低理解门槛。Phase 3: 平台深度集成让网站不再是孤立的产品介绍页而成为DollhouseMCP平台的一个前端入口。例如用户仪表板登录的用户可以在这里管理自己的AI角色和智能体流程。实时状态监控展示平台服务的健康状态、API使用情况等。市场/模板库用户可以浏览和下载由社区共享的优质角色模板或工作流模板。长期可能性基于AI的站内搜索超越关键词匹配实现语义搜索。例如用户搜索“如何让AI角色记住对话历史”即使文章中没有完全相同的字句也能找到讲解上下文窗口和记忆机制的相关文章。个性化内容推荐根据用户阅读的文章标签和行为在侧边栏或文末推荐相关的技术博客。自动化内容更新对于某些涉及版本号如Claude API更新的教程类文章可以设置AI Agent定期检查原文并在发现过时时自动提交更新PR。5. 常见问题与避坑指南在实际开发中我们遇到了一些典型问题以下是排查思路和解决方案问题现象可能原因排查步骤与解决方案本地样式正常部署后样式错乱1. 资源路径错误相对路径/绝对路径问题。2. 浏览器缓存了旧的CSS文件。3. CDN缓存未刷新。1. 检查浏览器开发者工具“网络”标签页确认CSS/字体文件是否成功加载状态码200。红色表示失败。2. 确保HTML中引用CSS的路径正确。如果站点部署在子路径如example.com/blog/需使用绝对路径以/开头或配置构建工具的基础路径。3. 对部署后的页面进行强制刷新CtrlShiftR / CmdShiftR。4. 在构建命令或部署平台设置中为静态资源文件名添加哈希后缀如style.abcd1234.css以破坏缓存。深色模式切换不生效或闪烁1. CSS变量定义在错误的媒体查询内或选择器优先级不够。2. JavaScript切换逻辑与CSS媒体查询冲突。3. 发生了“无样式内容闪烁”FOUT。1. 确认:root选择器内的变量和media (prefers-color-scheme: dark)内的变量定义正确。使用浏览器开发者工具“元素”面板检查:root上计算后的CSS变量值是否随系统主题变化。2. 如果使用JS切换确保在html标签上设置>AI生成的代码结构冗余或性能不佳AI倾向于生成通用、健壮但有时冗长的代码。1.审查CSS选择器避免过度嵌套如.card .title .icon尽量使用扁平的类名选择器提升渲染性能。2.合并重复样式AI可能会为相似组件生成几乎相同的样式块手动将其合并为共享的类或混合宏如果使用Sass/Less。3.检查JavaScript事件监听如果AI生成了多个相似元素的交互代码考虑使用事件委托将监听器绑定在父元素上减少内存占用。4.始终进行手动优化将AI代码视为高级“草稿”性能优化和极致精简仍需开发者把关。博客文章列表页生成逻辑复杂手动维护一个包含所有文章链接和元数据的HTML文件非常低效且易出错。1.采用极简的构建脚本写一个Node.js或Python脚本在本地开发时运行。该脚本读取_blog_posts/目录下所有Markdown文件的Frontmatter生成一个包含文章列表数据的JSON文件如posts.json或一段静态的HTML片段。2.前端动态获取在博客列表页的HTML中引入一段JavaScript通过fetch获取生成的posts.json然后动态渲染列表。这样每次新增文章只需运行一次脚本无需手动修改HTML。3.考虑引入轻量级SSG如果需求变得更复杂如分页、标签页可以考虑使用像11ty这样的极简静态站点生成器它学习成本低且能完美处理Markdown和模板。图标系统管理混乱多个页面使用图标有的用SVG内联有的用图片样式不统一。1.建立统一的图标库我们创建了house-icons.css文件使用CSS Sprite或字体图标如IcoMoon技术将所有图标整合到一个资源文件中。2.定义使用类为每个图标定义对应的CSS类如.icon-home通过background-position或::before伪元素来显示。3.保持SVG源码文件在icons/目录下保留所有图标的原始SVG文件方便未来修改和添加。使用构建工具如svgo优化SVG代码再生成图标字体或Sprite图。最后的几点心得AI是杠杆不是替代品它极大地放大了我的产出能力但项目的核心架构、产品逻辑和最终的质量把控必须由人来负责。我的角色从“码农”转变为了“产品经理架构师技术编辑”。文档即代码代码即文档style-guide.html和清晰的目录结构是最好的文档。保持它们的更新比维护一份独立的Word文档有效得多。从小处着手快速验证不要一开始就想着做一个大而全的系统。我们先做出了一个包含设计令牌、几个核心组件和一篇博客的“最小可行网站”部署上线。获得正反馈后再按计划逐步添加功能。这种节奏让人更有成就感也更容易调整方向。拥抱迭代无论是设计、代码还是内容几乎没有什么是“最终版”。AI辅助让快速迭代的成本变得极低。不要追求第一次就完美先做出一个可用的版本然后基于反馈和使用体验持续地优化它。这个官网本身就是这一理念的活生生的例子。