DeepSeek Harness 发布后我拿它做的第一件实事是给内部演示项目 BitFun 生成一个官网。整个过程没有停留在“让 AI 帮我写一段页面代码”的层面而是把安装、配置、任务拆解、内容生成、构建验证和排错完整走了一遍。真正跑通之后会发现这类工具的价值不只是自动补全或聊天生成而是把“建一个项目并让它跑起来”这件事拆成一条可观察、可干预、可回滚的执行链。下面这篇实录以 BitFun 官网为主线从 DeepSeek Harness 到底是什么开始讲清楚它在什么场景下值得用然后再演示从零安装、配置模型、下发任务、生成代码到本地部署的完整过程。文中的项目名 BitFun 是一个示例站点名你可以直接替换成自己的品牌、产品页或团队内部工具展示站。代码和配置都是示例结构落地时请以你实际使用的仓库、模型和包管理器版本为准。1. DeepSeek Harness 是做什么的一次官网生成背后的执行链1.1 普通人看到的是“AI 写页面”Harness 看到的是“任务被执行”如果直接在聊天框里让模型生成一个官网它会输出一堆 HTML、CSS 和 JavaScript 片段。你可以复制到本地再手动保存成文件、安装依赖、启动项目。页面多的时候这种工作方式会很快失控文件保存错目录、依赖版本对不上、导航跳转路径错误、图片资源没下载下来每一条都要人工兜底。DeepSeek Harness 这类工具的定位是把“生成代码”扩展成“执行任务”。它不只是生成一段代码而是一步一步地做以下事情读取项目目录和已有文件理解你提出的网站目标规划需要的文件结构和实现步骤创建或修改文件执行安装依赖、启动开发服务器、运行构建等命令观察命令输出发现问题后再修正直到任务完成或达到预设次数才停下来。换句话说它不是“替你想代码”而是“替你执行一个需要写代码的任务”。官网只是其中一个典型场景。它认为最终交付物不是一个回答片段而是一个可运行的项目目录。1.2 DeepSeek Harness 与普通 Chat 的差异理解这个差异是后面所有操作的前提。用表格可以看得更清楚对比维度普通聊天窗口DeepSeek Harness 这类 Agent Harness交付结果文本片段文件改动、命令执行结果是否自动操作文件否是是否自动执行命令否是工作记忆单轮或多轮对话结合工作区文件上下文失败处理用户手动复制修正可以按规则重试或停止等待介入适合场景问思路、写题、改作文案建站、改造项目、补测试、批量修改代码需要强调的是Harness 并不一定比普通聊天更“聪明”。它更像是一套约束模型行为的控制循环模型每次只决策下一步动作工具负责执行动作并返回结果。这样做的意义在于复杂任务可以被拆成若干小步骤每一个步骤都有日志、有文件 diff、有可回滚点。1.3 三种常见入口CLI、Web 面板、编辑器插件从安装和使用习惯上看DeepSeek Harness 这类工具通常围绕三种形态展开。第一种是命令行入口。适合在某些自动化脚本或 CI 场景里直接调用可以把任务写成参数传入也可以读取项目下的 Markdown 任务文件。第二种是 Web 面板。启动后通常会在浏览器里打开一个本地服务页面用来选择工作区、查看任务状态、观察执行日志。热词里出现的dsh web在很多执行框架中对应的就是这个“启动 Web 工作台”的入口。第三种是编辑器插件方式。把 Harness 接入 VSCode 后可以在编辑器右侧看到任务面板也可以把选中代码发给模型做定向修改。在学习阶段建议优先使用 Web 面板因为整个生成和排错过程都有可视化日志比命令行更容易理解。2. 开工之前模型 API、运行环境与官网需求要对齐2.1 本地环境清单给 BitFun 做官网之前先确认本地是否满足运行 DeepSeek Harness 的基本条件。项目建议要求说明Node.js20 LTS 或更高具体以仓库要求为准版本过低会导致 pnpm 或构建工具运行异常pnpm通过 Corepack 启用或独立安装常见安装脚本使用 pnpm 管理依赖Git已安装并配置用户信息用于拉取仓库和保留版本历史模型 API Key已申请且余额或配额可用Harness 需要调用远程模型能力浏览器Chrome / Edge 等现代浏览器用于访问 Harness Web 面板端口未被占用的本地端口启动时关注日志输出的端口号如果本地已经安装了 nvm 或 Volta建议先把 Node 切到项目要求的 LTS 版本再执行安装命令。很多启动失败的问题并不是代码问题而是 Node 版本与 pnpm 版本不匹配。2.2 模型接入方式要先确认DeepSeek Harness 需要连接一个可用的模型服务。常见接入方式是你的模型平台提供 OpenAI 兼容接口Harness 在本地保存 endpoint、API Key 和模型名。在开始前把以下信息写进环境配置文件或通过启动命令前的环境变量传入# 以 .env 文件为例实际字段名请以项目的 .env.example 为准 LLM_API_KEYsk-这里填你的密钥 LLM_BASE_URLhttps://api.deepseek.com LLM_MODEL填写你申请到的模型名环境变量环节最容易犯的错误是照抄别人的字段名。不同版本的 Harness 可能使用DEEPSEEK_API_KEY、OPENAI_API_KEY、MODEL_PROVIDER等不同名称。所以第一步应该是打开项目根目录下的.env.example或README看清楚它真正读取的是哪个变量。确认模型是否能被远程调用也可以用下面这条最小请求验证curl https://api.deepseek.com/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $LLM_API_KEY \ -d { model: 你的模型名, messages: [{role: user, content: ping}] }能返回 JSON再进入下一步如果这一步就失败后面所有任务都会卡在模型调用上。2.3 用一份需求卡片约束官网范围让 AI 生成官网最怕的不是 AI 不会写而是任务描述太宽泛。直接说“帮我做个官网”模型可能只会输出一个没有业务含义的通用模板。给 BitFun 建站前我先写了一份需求卡片标题、一句话说明、目标用户、包含页面、视觉风格、技术约束全部列清楚# BitFun 官网需求卡片 - 站点定位BitFun 是一个面向开发者的创意工具合集站 - 本次目标生成一个可部署的响应式官网展示产品价值和功能入口 - 页面范围首页、功能列表、关于页面 - 视觉倾向浅色背景强调清晰排版避免大面积动态特效 - 技术方案Vite React 静态站点 - 验证标准npm install 和 npm run build 成功 - 内容要求所有示例数据必须带有明显的示例标记不能伪造用户评价这份卡片后来成为 Harness 任务的输入。它的作用不是限制模型“发挥创意”而是把验收范围固定下来让模型知道哪些是一步到位的硬性约束哪些是可以自由调整的视觉空间。3. 安装和启动 DeepSeek Harness先解决 pnpm 这一关3.1 从仓库到本地的基本安装路径安装过程的第一步是拉取 Harness 项目代码然后安装依赖。以 pnpm 为主要包管理器时命令通常是这样的git clone your-repository-url deepseek-harness cd deepseek-harness pnpm install如果你在安装时遇到网络问题或者仓库体积较大依赖下载时间会很长。学习环境里可以先配置镜像源但不建议在生产服务器上盲目修改全局 registry更稳妥的做法是只在当前项目里配置。也可以先执行pnpm approve-builds或阅读根目录的package.json确认哪些依赖包需要执行 postinstall 脚本。某些包在安装后还需要原生编译缺少 Python、C 编译环境时会报错。3.2 启动 Web 工作台的三种方式安装完成后启动入口通常写在package.json的 scripts 里。网上经常出现的pnpm dsh web就是这种命令的典型写法pnpm dsh web如果项目没有dsh子命令可以回退到以下方式pnpm dev # 或者 pnpm start启动后终端会输出一个本地访问地址一般是http://localhost:端口号或http://127.0.0.1:端口号。不要修改配置端口后仍然使用旧端口访问那样页面会一直打不开。3.3 启动后的基础检查Web 面板启动不等于 Harness 已经全部可用还需要做三类基础检查。第一类是模型配置检查。在面板设置里能看见模型供应商、模型名和 API Key 是否加载成功。第二类是工作区检查。Harness 默认不允许操作任意目录需要把 BitFun 项目所在的文件夹授权给工具。第三类是任务日志检查。随便发一个“读取当前目录结构”的简单任务观察它是否能正确返回文件树。# 如果通过命令行查看工作区可能会有类似命令 pnpm dsh ls这里要特别提醒不同项目暴露的命令可能完全不同。当命令不存在时不要反复换说法硬跑应该先查看package.json的scripts字段和文档。3.4 pnpm 卡住与依赖安装失败先按这个顺序查安装过程中最容易出现的就是pnpm install长时间不结束或者pnpm dsh web启动后看上去像卡住。遇到这类问题按以下顺序排查看网络。依赖源不通时会长时间重试表现为进度条不动看终端输出。如果输出了下载进度但速度很慢可能是镜像问题看命令入口。确认当前命令确实存在于package.json而不是凭记忆输入看缓存。偶发损坏的缓存会导致安装后运行缺模块。清掉旧依赖重新安装。常见操作如下pnpm store prune rm -rf node_modules pnpm install如果项目根目录有.npmrc可以检查其中是否配置了自定义源、严格 peer 依赖等行为。不要为了“网络加速”就在配置里写入不明来源地址优先使用可信任的公共镜像。4. 用 DeepSeek Harness 给 BitFun 生成官网全程实录4.1 给 Agent 的第一份任务说明环境跑通后我把 BitFun 的需求卡片整理成了一个任务文件并放入一个独立工作区。任务文件的好处是即使 Harness 中途断了重新发起任务时仍可以引用同一份文件避免每次重写需求。mkdir -p bitfun-website cd bitfun-website然后创建TASK.md# 任务生成 BitFun 官网 工作目录下是一个空项目。请按以下步骤完成 1. 初始化一个 Vite React 项目推荐使用 JavaScript 版本 2. 创建 index.html 和 src/main.jsx 3. 实现顶部导航、首屏宣传区、功能卡片、底部导航 4. 使用响应式布局在手机宽度下导航堆叠显示 5. 所有图片和文案使用占位内容示例数据必须标注“示例” 6. 完成后执行 npm install 和 npm run build修复构建错误。 页面文案可以参考 BitFun一个面向开发者的创意工具合集站。这里把“验证标准”直接写在任务里是为了让 Agent 在执行完后主动运行构建命令而不是生成完代码就宣布成功。4.2 任务执行过程中的日志与目录变化在 Web 面板或命令行里运行任务后Harness 输出的日志大致会呈现这样的过程- 读取 TASK.md - 规划执行步骤 - 初始化 Vite 项目 - 写入 src/main.jsx - 写入 src/App.jsx - 写入 src/index.css - 安装 npm 依赖 - 执行 npm run build这个过程中不要只盯最后一步。关注它是否在合适目录下执行命令是否跳过了某个步骤。如果 Agent 使用了 Vite 的自动初始化命令例如npm create vitelatest它可能需要在交互式提示中选择框架和语言。这时有些 Harness 会直接注入非交互参数有些则可能卡住。完成后工作区应该会生成类似这样的文件结构bitfun-website/ ├── index.html ├── package.json ├── vite.config.js └── src/ ├── main.jsx ├── App.jsx ├── index.css └── components/ ├── Header.jsx ├── Hero.jsx ├── FeatureList.jsx └── Footer.jsx4.3 检查生成出的核心代码而不是直接信任Agent 生成完项目后我会先打开src/components/Header.jsx看它是否采用可维护的数据流。下面是一个常见的合理生成形态// src/components/Header.jsx export default function Header({ navItems }) { return ( header classNamesite-header a classNamebrand href/BitFun/a nav {navItems.map((item) ( a key{item.href} href{item.href}{item.label}/a ))} /nav /header ); }这段代码的关键点是导航数据通过navItems传入而不是在组件内部写死。这样后续如果要增加页面只需要在App.jsx的数据数组中加一项。再打开src/main.jsx确认挂载入口正确import React from react; import ReactDOM from react-dom/client; import App from ./App.jsx; import ./index.css; ReactDOM.createRoot(document.getElementById(root)).render( React.StrictMode App / /React.StrictMode );如果页面包含路由跳转还需要检查index.html和部署配置是否对单页路由做了回退。示例项目暂时没有多路由所以vite build后直接托管静态文件即可。4.4 样式文件与响应式布局的验收官网很容易出现桌面端正常、移动端错位的问题。生成样例中的src/index.css至少应包含 CSS 变量、基础 reset 和断点布局:root { --color-bg: #f8fafc; --color-text: #0f172a; --color-accent: #2563eb; } * { box-sizing: border-box; } body { margin: 0; font-family: system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif; background: var(--color-bg); color: var(--color-text); line-height: 1.6; } .site-header { display: flex; justify-content: space-between; align-items: center; padding: 16px 24px; border-bottom: 1px solid #e2e8f0; } media (max-width: 768px) { .site-header { flex-direction: column; align-items: flex-start; gap: 12px; } }Agent 可能生成类似代码但类名和颜色不一定完全一样。你需要关心的是结构是否清晰、是否有基础变量、断点是否覆盖移动端。不要因为页面好看就跳过样式审查。4.5 本地运行和生产构建在 BitFun 官网目录里依次执行npm install npm run dev浏览器打开终端提示的本地地址能看到页面即可。然后执行npm run build构建成功后目录中会生成dist/文件夹。这一步是判断 Harness 是否真正完成任务的关键指标生成页面只是第一步能构建通过才说明依赖、路径和代码语法没有把它卡在静态生成之外。如果build过程报错把报错信息贴回 Harness让它继续修改。不要重新新建项目尽量让它基于当前文件修复这样可以保留已经生成的业务结构。5. 生成类项目的验收方式不要只等一个“成功”5.1 Harness 说“完成”不代表页面一定能上线DeepSeek Harness 判断任务完成的依据是自己的执行循环它认为“构建通过”就算完成。但从真实上线角度看距离可发布还有一段路。手工写代码时开发者会下意识检查导航跳转、图片路径、版权年份、空状态等琐碎细节而 AI 生成项目时这些内容很可能看起来合理但实际不可用。我建议把验收拆成三层能跑、能点、能发布。5.2 三层验收清单下面是 BitFun 官网的具体验收清单可以作为以后任何 AI 生成站点的参考模板验收层检查项通过标准能跑本地npm run dev浏览器正常打开首页能跑npm run build生成 dist 目录且无报错能点导航链接每个链接能跳转到对应区块或页面能点按钮点击CTA 按钮有实际跳转动作或目标事件能点页面缩放375px 宽度下无横向滚动能发布静态资源路径JS、CSS、图片均能加载没有 404能发布示例内容标记占位文案能明显看出是示例不会误导访客能发布标题和描述index.html中的title、description不是默认值其中“没有横向滚动”是响应式网站最容易漏掉的检查。把浏览器窗口拖到手机宽度如果出现横向滚动条通常是因为某张图片固定宽度或某个容器设置了过宽的min-width。5.3 AI 生成站点必须做内容幻觉核查模型生成页面时很可能编造出不存在的功能、伪造的用户评价、错误的联系地址甚至虚构“已经上线”的第三方产品名称。BitFun 本身是示例项目所以影响不大但如果你给真实产品生成官网这部分会成为最大的发布风险。处理方式是在需求卡片里明确要求所有无法核实的数据、评价、客户 Logo 一律不得出现只能使用待替换的示例占位符。不要依赖模型的自我判断它不会知道自己刚刚编造了一个联系人电话。5.4 如何把验收结果交回给 Agent 修复验收发现的问题不要直接在部署环境里手工改完就结束。更合理的方式是记录一条修复指令继续交给同一个工作区执行请修复以下问题 1. index.html 中 title 仍是 Vite React请改为 BitFun 官网 2. Hero 区域按钮单击后没有跳转目标地址应改为 #features 3. 375px 宽度下出现横向滚动请检查溢出的容器 4. Footer 中的邮箱 hellobitfun.example 是占位内容请明确标注为示例。这种“生成 - 验收 - 修补”循环是使用 Harness 最有效的工作方式。它把 AI 当成一个可以反复修改工程问题的协作者而不是一次性答案生成器。6. 高频报错排查reasoning_content、400、pnpm 启动问题6.1 现象pnpm 安装或启动像卡住一样前面安装章节已经提过基础清理方式。补充一个判断方法当执行pnpm install时如果长时间停留在某一个依赖包不动可以观察到终端是否还有网络传输。没有传输变化时先按CtrlC取消不要一直等。处理建议问题现象常见原因处理方式pnpm install 慢网络到默认源不稳定临时使用镜像源重试pnpm dsh web 启动后无输出命令入口不存在或启动脚本崩了查看 package.json 的 scripts启动后端口无法访问端口被占用或服务绑定在 127.0.0.1查看日志输出地址和可用端口删除 node_modules 后安装失败锁文件与 registry 不匹配确认 lockfile 后重新安装6.2 现象thinking 模式下返回 400提示 reasoning_content 必须回传在使用 DeepSeek 模型做多轮或 Agent 任务时日志里可能出现类似这样的错误upstream_status: http 400 cause: the reasoning_content in the thinking mode must be passed back to the api.这类报错的本质是模型开启了思考模式第一次返回除了content外还会返回用于继续推理的reasoning_content。当 Harness 把上下文继续发给模型时如果只保留对话内容而丢掉推理内容服务端会认为多轮上下文不完整于是返回 400。排查路径查看当前任务是否开启了 thinking mode查看实现的日志里是否保存并回传了reasoning_content查看多轮 messages 字段中该条消息是否同时包含content和reasoning_content如果只要最终答案而不需要思维链先尝试关闭思考模式如果必须使用思考模式则需要在客户端请求逻辑中保留该字段并在下一轮传回。这个报错通常不是网络问题也不是 API Key 问题而是上下文处理逻辑与模型要求不匹配。修改后再次发起同一任务即可。6.3 现象网关转发请求返回 400但不是模型名称写错在 DeepSeek Harness 接入自定义转发服务或使用 OpenAI 兼容接口时400 报错也经常出现。先不要怀疑模型名称按以下顺序确认请求地址是否填写正确/chat/completions是否存在Authorization头中的 Key 是否包含多余空格消息格式是否为messages: [{ role: user, content: ... }]是否传入了模型不支持的参数是否在 thinking mode 下忘传reasoning_content。可以使用最小请求反复测试curl https://api.example.com/chat/completions \ -H Authorization: Bearer $API_KEY \ -H Content-Type: application/json \ -d {model: 模型名, messages: [{role: user, content: ping}]}逐一修改参数看哪一步导致状态码变化。最小化复现比直接翻 Harness 源码更高效。6.4 现象页面能启动但图片和链接 404这种错误大多不是 Harness 运行逻辑问题而是生成时的路径策略不统一。Agent 可能在一个组件里写了绝对路径/images/logo.png但图片实际放在src/assets/构建后没有复制到根目录。检查方式打开浏览器开发者工具的 Network 面板找到 404 的资源地址查看项目文件树确认资源实际路径如果是 React 项目建议使用import logo from ./assets/logo.png方式让打包器接管路径如果是写死路径则要确保部署时资源在对应位置。修复指令可以是所有图片均使用 import 方式引用不要使用字符串路径。 检查 src 目录下是否有未被引用的图片资源并把它们清理掉。这个坑几乎每种 AI 生成前端项目都会遇到验收时值得专门查一遍。7. DeepSeek Harness 生成官网的最佳实践与扩展方向7.1 用一份可复用的 Prompt 模板减少返工文档开头我写的那份需求卡片可以沉淀成模板以后每次做官网时直接复制修改。模板应包含七个固定部分站点定位、目标用户、页面范围、必备功能、视觉风格、技术约束、验证标准。参考模板# 站点名称官网生成任务 - 站点定位 - 目标用户 - 页面范围 - 必备功能 - 视觉风格 - 技术约束 - 验证标准不要省略“验证标准”。它告诉 Harness 怎样才算真正完成。没有这一步它很可能生成一个看起来完整但无法构建的项目。7.2 每次让 Agent 改动前先形成一个可回滚点AI 执行任务时修改文件是批量操作万一连续几次修坏了找回原状会非常痛苦。使用时建议按“提交一个干净版本 - 让 Agent 修改 - 检查 diff - 提交新版本”的节奏推进。git add . git commit -m feat: generate BitFun official website # Agent 执行下一次调整后查看差异 git diff如果 Agent 改了不该改的文件可以快速放弃修改git checkout -- src/这个习惯既适合学习环境也是生产项目使用任何 Agent 工具时都必要的基本保护。7.3 生产环境发布前还要补上这些内容学习环境里能在本地跑通就算结束。生产环境发布前需要额外关注项目生产环境建议代码仓库确认没有把.env和 API Key 提交进仓库页面信息index.html的 title、description、favicon 必须替换静态资源使用构建产物dist/不要直接用源码目录做静态站点HTTPS生产域名必须配置 HTTPS 证书缓存给带 hash 的静态资源配置长缓存回滚保留上一个构建版本部署失败时能快速回退内容校对由真实业务人员检查所有文案和数据生成官网只是第一步真正上线之前仍然需要把 AI 生成的内容当作外包初稿来审而不是当成成品直接发布。7.4 下一步可以做的四件事跑通这次 BitFun 官网实录后可以顺着同一条任务链路继续扩展。第一把生成官网的流程复制到文档站点。用同样的 Harness 机制生成一个技术文档或 API 手册练习如何让 Agent 根据目录批量生成页面。第二让 Harness 补测试。官网源码已经有了再让它基于组件写冒烟测试观察它是否理解渲染逻辑。第三接入风格指南。如果公司已有设计规范可以把颜色、间距、字体规则写入任务卡片看 Agent 能否严格遵守。第四做一次老项目改造。挑一个结构混乱的页面让 Harness 在保留原功能的前提下拆组件这比从零建站更能检验它的边界控制能力。DeepSeek Harness 真正有价值的用法是让任务、代码、验证形成一个持续修正的循环。给 BitFun 做官网只是一个入口后面要处理的问题越多你越能感受到工具和人工检查之间平衡的重要性。