大模型项目开发经验

—— WinWork 文档中心开发经验分享

作者：罗林汉（lhluo4） 项目：WinWork 帮助中心 时间：2026-04-10（半天完成从 0 到上线） 工具：WinWork（AI 数字员工平台）

---

一、背景

我是运维/运营岗位，不是前端开发，也没有 VitePress 经验。 这次需要为集团的 WinWork AI 平台搭建一套帮助中心，从 0 到 Docker 上线部署，半天时间完成。

全程使用 WinWork 辅助，我主要负责：

• 提供需求描述和业务上下文
• 审阅和确认输出内容
• 处理公司内网环境适配问题

WinWork 负责：

• 搭建项目脚手架（VitePress + Mermaid + Docker）
• 撰写全部 70+ 个 Markdown 页面
• 编写 custom.css 定制全站样式
• 适配 Dockerfile、Nginx 配置、CI 流水线

---

二、项目概览

指标	数值
人工投入	半天（约 4 小时）
总提交数	10 次
总文件数	70+
总代码行数	13,000+ 行
技术栈	VitePress + Mermaid + Docker + Nginx
我的技术背景	非前端、无 VitePress 经验

---

三、半天时间线

第 1 小时（0:00 - 1:00）：从 0 到跑起来

目标：把需求变成能访问的网站。

过程：

1. 我告诉 WinWork：需要基于 VitePress 搭建一个帮助中心，覆盖产品介绍、数字员工、Agent 规范、Skill 规范、Memory Hub、平台架构、FAQ 等 6 大模块。
2. WinWork 一次性生成了 71 个文件：
   • 完整的目录结构和导航配置（.vitepress/config.mts）
   • 6 大模块的文档页面
   • 50+ 张 UI 截图的占位引用
   • package.json + 依赖安装

提交：feat: 初始化 WinWork 文档中心 — 71 files, 13,248 insertions

踩坑：README.md 里有大括号导致 VitePress 构建失败。报错贴给 WinWork，30 秒定位并修复。

成果：npm run dev 跑起来了，浏览器能看到帮助中心。

---

第 2 小时（1:00 - 2:00）：部署上线

目标：让文档在公司内部 Docker 环境中跑起来。

过程：

1. 我提需求："需要 build 成静态站点并用 Docker 部署"。WinWork 自动添加了 vitepress build 脚本、Dockerfile 和 Nginx 配置。
2. 公司内网拉不到公共 nginx 镜像，换了两次镜像源（内部仓库 → DockerHub 代理库），问题解决。
3. 还原 Dockerfile 为单阶段构建，适配公司 CI 流水线。

提交：

• fix: 添加 build 脚本、Dockerfile 和 nginx 配置
• fix: 使用内部镜像仓库 nginx，修正 COPY 路径为 dist/
• fix: 使用公司 DockerHub 代理库拉取 nginx 镜像
• fix: 还原 Dockerfile 为单阶段构建，适配 CI 流水线

成果：Docker build 成功，容器启动，内部可访问。

---

第 3 小时（2:00 - 3:00）：视觉升级

目标：首页要有品牌感，不能太素。

过程：

1. 首页从 38 行默认模板升级为完整入口页：下载卡片、登录说明、数字员工网格、角色引导、平台核心能力。
2. 新增 custom.css（567 行），定制品牌色、卡片布局、响应式适配。
3. 新增 8 个数字员工详情页（产品助手、质效助理、测试专家、资产管理、成本分析、SRE 助手、OA 助手、效能分析助手）。

提交：

• feat: 帮助中心优化 — 数字员工专区 + 视觉美化 — 14 files, 1,354 insertions
• feat: 首页布局优化 + 修复容器部署 — 3 files, 652 insertions

关键点：我只描述了想要的视觉效果（"卡片网格布局、hover 有阴影和上移、渐变边框"），WinWork 生成了完整的响应式 CSS，包含移动端适配。

---

第 4 小时（3:00 - 4:00）：规范补全 + 品牌定稿

目标：让开发者有章可循，品牌视觉定稿。

过程：

1. WinWork 从 stc_kc 下的 10 个代码仓库中读取 Agent/Skill 的实际代码和协议，生成了 Agent 接入规范（270 行）、数字人接入规范（258 行）、Skill 接入规范（290 行）。
2. 品牌色从紫色升级为暖橙色，整合宣传素材中的三支柱文案和六大场景。

提交：docs: 补充 Agent/Skill 接入规范并优化帮助中心结构 — 13 files, 1,115 insertions

成果：帮助中心内容完整，导航清晰，品牌视觉统一。

---

四、效率对比

阶段	纯手工预估	实际用时
学习 VitePress	1-2 天	0
搭建项目结构 + 71 个文件	2-3 天	30 分钟
定制 CSS 567 行	1-2 天	30 分钟
撰写 8 个数字员工页面	1 天	30 分钟
撰写 3 个规范文档（800+ 行）	2 天	30 分钟
Docker 部署适配	半天	30 分钟
合计	6.5-10.5 天	4 小时

---

五、我怎么和 WinWork 协作

我的角色是「产品经理 + 审核者」，不是「写代码的人」。

阶段	我做什么	WinWork 做什么
需求	描述目标、提供上下文和素材	理解意图，拆解任务
执行	审阅输出、指出问题	生成代码、修复问题
验证	在本地/服务器上看效果	分析报错日志、定位原因
迭代	提出优化方向	生成新版本

三个关键原则

1. 先给上下文，再生成

大模型不是猜谜，给它什么就还你什么。先把业务背景、模块结构、现有素材准备好，比直接说"帮我做个网站"有效得多。

2. 小步快跑，每步验证

不要一次性让 WinWork 生成整个项目。分阶段推进：先搭脚手架，确认能跑；再逐步加模块；每步 commit，出了问题能回滚。这次 10 次提交，每次都有明确的验证点。

3. 报错是朋友

遇到构建失败、页面卡加载、图片不显示，直接把错误日志贴给 WinWork。它分析日志的速度比我肉眼排查快得多。典型的循环是：贴报错 → AI 分析 → 试方案 → 验证 → 搞定。

---

六、大模型擅长和不擅长

擅长（交给 WinWork）	不擅长（需要人工）
脚手架搭建、配置生成	公司内网环境适配
CSS 样式、响应式布局	安全审查（token/密钥管理）
文档撰写、格式统一	跨部门协调和确认
报错分析、根因定位	业务决策（功能优先级）
跨仓库信息整合	合规审查

---

七、避坑指南

大括号问题：VitePress 的 Markdown 会用 做变量插值。文档内容里有 JSON 示例时，需要用 <pre> 包裹。

内网镜像：公司网络拉不到公共 nginx 镜像，用公司 DockerHub 代理库路径解决。

Docker 静态资源 404：VitePress build 后图片路径在容器中对不上，Nginx root 要指向 dist/ 目录。

CSS 变量冲突：自定义变量用独立前缀，再覆盖 --vp-*，不要直接改 VitePress 内置变量名。

---

八、给非研发同学的 6 条建议

1. 不要怕：你不需要会写代码，只需要会描述需求。
2. 给足上下文：业务背景、目标用户、现有素材，先准备好再开始。
3. 小步验证：每一步都确认效果，不要攒到最后才看。
4. 保留 git 历史：每次 commit 都是一次回滚点，大胆试。
5. 善用报错：把错误日志原样贴给大模型，它分析能力比你强。
6. 你是产品经理：你的核心价值在于判断"做得对不对"，而不是"代码怎么写"。

---

本文档基于 WinWork 文档中心的实际开发过程整理。项目仓库：WinWork Docs