企业官网建设流程全解析

1. 一次"氛围编码"翻车现场：代码能跑，但没人敢碰

这两年 AI 写代码的能力大家有目共睹，我也一度沉迷"氛围编码"（vibe coding）——需求丢给大模型，它噼里啪啦产出几百行代码，跑起来效果还不错，那种感觉确实爽。但爽完就出事：第三周开始，代码库像被谁用霰弹枪打过一样，到处是重复的逻辑、互相冲突的命名、只有 AI 自己"理解"的隐式状态。最夸张的一次，我让 AI 改一个订单状态流转的接口，它很听话地改了，但把另一个模块的定时任务判断条件也顺手改了，因为"我推断这个变量在这里是同一个意思"。结果就是生产环境凌晨三点报警，我爬起来回滚，然后对着 diff 一脸茫然——改动里有一半是它自作主张的"善意重构"。

这件事让我彻底明白：氛围编码最大的问题不是 AI 能力不够，恰恰是它太"自由"了。你给它一个模糊目标，它就拿最模糊的方式回你。真正的解法不是骂模型，而是给它一套工程化的约束和流程。我后来用的组合就是标题里写的这套思路：SDD（Specification-Driven Development，规范驱动开发）管"该做什么"，Harness 管"怎么被驾驭"。这篇文章就是把这套组合从概念落到实操的完整复盘，适合那些已经用 AI 写过不少代码、但开始对代码库失控感到焦虑的团队和个人开发者。如果你是第一次听说 SDD 或 Harness，也不用慌，下面每个环节我都会从原理讲到具体命令，保证能照着做。

1.1 氛围编码为什么诱人

先别急着否定氛围编码。它能火，是因为它真的把编程门槛拉低了一个量级。过去你写一个爬虫，要去找库、配置环境、处理编码、调反爬；现在对着模型说一句"帮我写个爬虫，要支持断点续抓"，十几秒就有代码。这种即时满足感是传统开发流程给不了的，尤其是做一些一次性脚本、原型验证、内部小工具的时候，氛围编码的效率就是碾压级的。

但问题也出在这——氛围编码把"写代码"变成了"聊天"，代码质量完全取决于提示词的质量和大模型当天的心情。你在对话里补一句"注意健壮性"，它可能真的给你加了 try-catch，但 try-catch 里吞掉了所有异常；你说"性能优化一下"，它可能给你套了三层无意义缓存。最可怕的是它不会主动告诉你"这里我不确定"，而是默默替你做了决定。而这些决定，恰恰是在代码评审和测试阶段最难被发现的。

1.2 失控的三种典型症状

我把自己和身边团队踩过的坑归纳成三类，你可以对照一下：

• 症状一：代码库熵增失控。同样的功能出现三套实现，每套风格都不一样，AI 每次改动都基于当前文件上下文，完全不记得项目里已经有过同类封装。结果就是改 A 调用逻辑时，B 和 C 的实现已经悄悄偏离。
• 症状二：隐性耦合没人说得清。AI 生成代码时经常会"顺手"依赖某个全局变量、某个魔法字符串，这些依赖不像显式接口那样能通过编译或 lint 发现，直到线上出问题才暴露。
• 症状三：回滚变成灾难。传统开发的回滚是一个明确的 tag 或 commit，但 AI 生成的代码改动经常是"逻辑改了，但因为格式变化产生大量无关 diff"，你根本看不清它到底改了什么，回滚就成了赌运气。

这三个症状的本质都是同一个：你在用聊天的自由度，去做需要承诺和约束的工程任务。而工程的核心恰恰是"约束下的确定性"。想通这点之后，我就开始研究怎么给 AI 加约束——于是有了后面的 SDD 和 Harness。

2. SDD 规范驱动：把"该做什么"钉死，再让 AI 动手

SDD 这名字听起来像新概念，但实际上它是软件工程里那套老智慧在新工具下的回归：先写规范，再写代码，规范先行，代码只是规范的实现。区别在于，以前写规范是为了给人看，现在写规范主要是为了给 AI 看。很多人觉得"规范文档"四个字就等于官僚、等于一堆没人读的 Word，这其实是没抓到重点——在 AI 原生开发里，规范不是文档，是契约。

2.1 规范不是文档，是契约

我说个极端一点的观点：如果你的规范写得足够好，AI 的实现工作应该是"无脑翻译"——把规范里的每一条行为描述翻译成对应代码。要达到这个效果，规范必须具备三个属性：

• 可验证性：每条规范都有明确的"通过/不通过"判断标准，而不是模糊的"性能要好"。
• 单一来源：一个行为逻辑在规范里只出现一次，避免 AI 在多个地方看到同一需求的不同描述后产生混淆。
• 变更闭环：业务逻辑变更先改规范，再让 AI 改代码，而不是直接跟 AI 说"你把这个变量改成这样"。

举个例子，"用户登录需要校验验证码"这句话就不是规范；规范版本应该是："当请求头 x-captcha-token 缺失，或 Token 与当前 session 绑定值不一致时，接口返回 401，错误码为 CAPTCHA_INVALID，且不得触发任何短信发送逻辑。" 你能明显感觉到，第二种写法 AI 根本不需要"发挥"，照做就行。

2.2 一套我能直接用的规范模板拆解

我自己在项目里沉淀了一套规范模板，结构很固定，你也可以直接抄走。它能用 Markdown 或 YAML 写，重点是字段固定：

## 功能: 用户登录 ### 行为定义 - 输入: 用户名, 密码, 验证码 token - 输出: JWT Token, 登录成功时间 ### 规则约束 - R1: 密码连续错误 5 次，锁定账号 30 分钟 - R2: 验证码校验失败时禁止触发短信发送 ### 验收标准 - AC1: 正确凭证 + 有效验证码 => 200 + Token - AC2: 错误密码 => 401, 错误码 PWD_INVALID - AC3: 验证码失效 => 401, 错误码 CAPTCHA_EXPIRED - AC4: 锁定期间 => 403, 错误码 ACCOUNT_LOCKED ### 影响范围 - 模块: auth-service - 禁止改动: 订单模块, 优惠券模块

这里最关键的是"影响范围"这一节。以前 AI 乱改代码，就是因为没有显式声明"你哪些地方不能碰"。我最初也以为模型不会认这个，实测下来只要你写明确，配合后面要讲的 Harness 钩子，AI 就越界率会低很多。原理其实很简单：大模型遵循指令的能力远比我们想象中强，问题在于你以前根本没给它这个指令。

2.3 规范拆解粒度：多大算合适

有朋友问过我：规范写太细，不等于自己把代码写完了吗？这确实是个需要拿捏的问题。我的经验是：规范管"行为结果"，不管"实现路径"。你只要告诉 AI "登录失败后该返回什么状态码、该记录什么日志"，不用管它是用 Service 层还是 Repository 层实现。粒度大致控制在"一个接口 / 一个后台任务 / 一个页面行为"为最小单位，太大 AI 消化不了，太小维护成本吃不消。

另外，规范文件要跟着代码一起做版本管理。我通常放在仓库根目录的specs/文件夹下，文件名和模块名对应。每次业务需求变更，先改规范文件的 diff，再让 AI 改代码——这相当于把"需求变更记录"变成了 Git 提交的一部分，后期追责和复盘都清楚得多。

3. Harness 与裸 Agent 的区别：AI 之外的那层"驾驭装置"

手上有规范之后，我需要一个机制来保证 AI 真的按规范执行，而不是又跑到另一条路上去。Harness 就是用来干这个的。我最早看到 "DeepSeek Harness" 这个名字时，以为是个单独的 AI 模型或 IDE 插件，研究之后发现它更像一个"可供你配置和扩展的 Agent 驾驭框架"——尤其适合 DeepSeek 这类开源模型与 Claude Code 这类 Agent 工具的配合场景。你可以把它理解成：裸 Agent 是一台高性能跑车，Harness 是方向盘、刹车、路面护栏和领航员的整合体。

3.1 裸 Agent 和 Harness 的本质差异

很多人分不清 Agent 和 Harness 的区别，我用一个场景说明：你让裸 Agent "写一个登录接口"，它会自己决定文件放哪、依赖用什么、函数怎么命名，然后一口气给你生成一堆新文件。而加了 Harness 之后，同一个请求会被拆解成几个阶段：先调用规范读取 Hook，把specs/auth.md内容注入到上下文；再根据规范确定"只允许修改 auth 模块"；最后等 Agent 写完，还触发一次差异检查，看看它有没有碰不该碰的文件。

这里面的差异可以归纳成一张表：

Harness 的价值不在"让 AI 更聪明"，而在"让 AI 的行为可以预期"。你可以把"规范"喂给它，把"不许动哪些文件"喂给它，把"每次改动必须先跑测试"喂给它。换句话说，Harness 把 AI 从"自由职业者"变成了"有工牌和规章制度约束的正式员工"。

3.2 Harness 的三个核心构件：Hook、Skill、Plugin

我研究和使用 Harness 类工具时，发现大部分框架都围绕三个核心构件：Hook、Skill、Plugin。理解这三个概念，就理解了 Harness 的工作原理。

Hook 是拦截点，在 AI 工作流的特定时机触发，比如对话开始前、文件修改后、命令执行时。我依赖最多的是"文件修改后"的 Hook，用来做守卫——一旦检测到 Agent 修改了specs/目录或生产下发的配置文件，立即中断并回退。它就像 git 的 hook 包了一层 AI 上下文。

Skill 是能力包，本质是一组提示词+脚本+配置文件的打包。比如"前端规范 Skill"会告诉 AI 项目用 Vue3、TypeScript、定制的代码风格，并提供对应模板；"数据库迁移 Skill"则禁止 AI 手改旧 SQL，必须走 migration 目录生成新文件。Skill 的存在让 AI 的领域行为是"可插拔"的，换团队或换项目时，启用对应 Skill 即可，不用重复调教。

Plugin 是功能扩展，更多是运行时代码层面的能力，比如让 Harness 支持某种辅助语言、集成某个审查工具的输出等。实际用起来，Plugin 的效果有点像给 Harness 加"外挂模块"，让整个流程和团队已有的 CI/CD 体系衔接起来。

我不建议把这几个概念想得太复杂——你就记住，Hook 管流程时机，Skill 管领域知识，Plugin 管外部能力。搞明白后，接下来才是真正的实操环节。

4. 把 SDD + Harness 落到真实项目：内网部署与权限问题完整排查

理论讲完了，得拿点真实的东西出来。我所在公司因为合规要求，代码数据不能出内网，所以"DeepSeek Harness 怎么部署到内网服务器"这个问题，我是真刀真枪踩出来的。这里先声明一句：离线部署和私有化部署是完全正常的企业工程需求，跟各类网络边界工具没有任何关系，纯粹是为了数据合规和稳定性。

4.1 为什么要坚持内网/离线环境

原因无非两点。一是代码本身就是最敏感的数据资产，AI 编码工具如果默认把代码片段发到外部服务，法务第一个不答应。二是离线环境下模型服务其实更好管控——可以做权限收敛、资源隔离、按需扩容，而且不依赖外网链路，网络抖动不会打断生成任务。对需要长期在同一个代码库上迭代的团队来说，"AI 生成过程可重复、流量可审计"比"模型最新最强"重要得多。

如果你要用 Harness 部署离线环境，第一步先把需要的 Skill、插件、模型权重文件全部下载打包好，在内网做一次全量校验。实操时我碰到最多的问题，就是大家直接在外网跑通了 demo，回头在内网一部署就各种缺包、路径错误。所以我的建议是准备一个"离线物料清单"，列清楚每个组件的版本和校验哈希，而不是靠 feel。

4.2 离线部署 Skill 到内网服务器的过程

我们以"把附带 Skill 部署到内网 Linux 服务器"为例走一遍流程。假设你已经通过内部软件仓库拿到了 Harness 框架的压缩包群（包括主程序、默认 Skill 包、模型服务配置）。

第一步，创建目录骨架。我采用的标准布局如下：

/opt/ai-harness/ ├── bin/ ├── config/ ├── skills/ │ ├── sdd-check/ │ ├── code-review/ │ └── db-migration/ ├── plugins/ └── logs/

第二步，把 Skill 解压到skills/目录，然后修改config/harness.yaml，把 Skill 注册进去。下面是个最小可用的配置示例：

skills: enabled: - sdd-check - db-migration hooks: pre_task: - name: inject_spec path: /opt/ai-harness/skills/sdd-check/scripts/inject_spec.sh post_modify: - name: boundary_guard path: /opt/ai-harness/plugins/boundary-guard/index.js models: backend: "internal" endpoint: "http://10.20.30.40:8080/v1"

第三步，启动前先跑一次自检：

/opt/ai-harness/bin/harness doctor

它会检查每个 Skill 的配置完整性、依赖脚本是否可执行、模型服务是否连通。这一步能拦住 80% 的部署坑。我们团队第一次部署时跳过自检，结果某个 Skill 的 Python 脚本在打包过程中丢了依赖，白白排查了一下午——所以这个命令真的不是摆设。

4.3 Windows 下 Skill 读文件权限报错的根因与修复

在内网跑通 Linux 之后，我试着在本地 Windows 开发机上跑同样的 Harness，结果遇到一个很经典的问题：Skill 读取文件时报错，提示setnamedsecurityinfow failed (win32)。第一次看到这个错误我以为是 Harness 的 bug，搜了一圈才发现这其实是 Windows 文件安全描述符的操作权限问题。

根因是这样的：Harness 在初始化 Skill 环境时，会对目标目录做一次安全属性校验，尝试设置目录的 ACL（访问控制列表）。如果你的账号对某个父级目录没有WRITE_DAC权限（修改安全描述符的权限），Windows 就会返回这个底层接口错误，Harness 那个包装层没有做特别友好的处理，直接把底层错误抛了出来。

排查链路我建议按这个顺序走：

1. 用icacls检查目标目录当前权限，看当前用户是否有 Write 权限。
2. 确认目录所有者是谁，很多内网机器管理员给的目录所有者是SYSTEM而不是你的域账号。
3. 用管理员 PowerShell 重新授予当前用户完全控制权：

icacls "D:\work\ai-harness\skills" /grant "$env:USERNAME:(OI)(CI)F" /T

4. 改完之后把 Harness 的缓存目录删掉（很多人漏了这步，权限修好了但 EhCache 还存着旧的失败状态）：

Remove-Item -Recurse -Force "$env:USERPROFILE\.harness\cache"

5. 重新启动 Harness 加载 Skill。

处理完这个之后，Windows 本地环境基本就顺了。这里多说一句：内网部署不要只看 Linux 服务器端，开发者的 Windows 本机往往才是最先暴露问题的地方。权限、路径大小写、换行符，这类"本地小差异"会在 Harness 这种带缓存、带目录扫描的框架里被放大成很难看的报错。

5. 实用插件与提示词优化：从"写得出来"到"写得可控"

Harness 的价值在于把 AI 行为收敛到可控范围，但真正让效率有质变的，是选择合适的插件和写好约束性提示词。我最初装了一堆插件，后来一个个删掉，最终留下的都是跟"可控性"强相关的。这轮复盘也顺便回答很多人问的"DeepSeek Harness 用于 coding 最应该装哪些插件"。

5.1 我目前留在生产环境的插件清单

这几个插件之间是分工协作的：spec-injector保证 AI 干活前看到规范，boundary-guard保证它不越界，diff-summary方便你审查，rollback-safe让你敢放手让它做。四者缺一不可——少一个，另外三个的效果都会打折扣。

5.2 提示词优化的两个关键动作

很多人在 Harness 里还是拿着裸提示词去用，这是典型的"骑着马找马"。在 Harness 场景下，提示词优化不是让它写得更华丽，而是让它"更老实"。我总结，最有效的两个动作是：

动作一：任务指令里显式声明"约束优先级"。要在提示词开头写清楚：本项目以specs/目录下规范为准，如果我对需求的描述与规范冲突，以规范为准；且禁止修改核心库文件，除非得到明确授权。这句话的作用是绝杀——因为大模型对冲突信息的处理遵循"后写优先"原则，你先把规范声明为最高优先级，它才会在纠结时偏向规范。

动作二：任务结束后强制走反思清单。在提示词尾部要求 AI 完成代码后必须自答四个问题：动过哪些文件？与规范是否有偏差？是否引入了新的依赖？是否运行过测试命令？这个"强制输出"的设计很巧妙，因为它迫使 Agent 重新检查自己的产物，很多遗漏和越界行为会在这一步被它自己发现并修正。

5.3 代码回退：AI 改坏了怎么办

热搜词里有"deepseek harness 代码回退"，这说明大家真的很担心 AI 把代码库搞坏。我的经验是，靠人力 review 永远防不住所有问题，必须把回退做成一个低成本动作。我在 Harness 里绑定了三层回退：

• 操作级回退：rollback-safe插件会在每次 AI 提交前自动生成 diff 快照。如果 AI 在单次任务中跑偏，我直接用快照还原该次改动，不用碰之前的正常提交。
• 任务级回退：每次任务开始时自动切新分支，任务失败直接丢弃分支，干净利落。这比在同一个分支上反复修改、反复 revert 要好得多。
• 规范级回退：如果 AI 改了规范本身的语义，仓库里保留规范文件的每次 diff，我可以随时把规范恢复到上一个"已认可版本"，再基于它重新生成代码。

这套三层回退本质上是给 AI 的每次操作一个"后悔药"，而且后悔药要够廉价，你才敢让 AI 大胆尝试。不敢回退的团队，才是真正被 AI 绑架的团队。

6. 从"氛围"到"工程"：我踩过的坑和现在的固定打法

最后这部分聊聊我实际用下来的整体感受，包括那些还没在上面展开的坑，以及我现在固定的工作流程。热搜词里那几条关于"插件无法安装""加载失败"的问题，我在实际排查中也处理过，这里一并分享。

6.1 插件加载失败这类问题怎么快速定位

有朋友遇到failed to load plugins web boot: 1 entry did not activate这种报错。这类"入口未激活"的问题，本质是插件入口文件抛了异常，或者入口函数名跟框架预期不一致。我的排查思路很简单：

第一步，看logs/plugin-loader.log里有没有更底层的异常栈，往往是某个依赖函数未定义，或者 Node/Python 版本不匹配。第二步，确认插件的入口声明，通常在harness.yaml的插件配置里写的是main: index.js，但实际文件可能叫main.ts，框架在 web boot 阶段找不到入口就报 "did not activate"。第三步，单独验证插件能否脱离框架运行，直接执行一遍入口文件的导出函数，看到底是哪一行炸的。

这个排查链路适用于大部分 Harness 类框架的插件问题。核心原则是：先看日志，再查入口，最后单测插件。不要一上来就重装整个 Harness，浪费时间。

另外一个很多人都提过的点：DeepSeek Harness 能不能不登录、接其他模型。我的使用体验是，Harness 设计上确实是模型无关的，它只关心"规范注入+越界拦截+结果校验"这层编排逻辑，后端接什么模型取决于你config/harness.yaml里写的 endpoint。所以在内网环境接一个通过内部 API 网关暴露的模型服务，完全可行。但这里我不建议走任何非正规渠道接非授权的模型接口，既不稳定也有合规隐患，企业场景下宁可本地起内网模型。

6.2 现在的固定流程：规范先行，Harness 兜底

经过这几个月的调整，我现在做项目的固定流程已经稳定下来，分享给你参考：

1. 写规范：先打开specs/目录，把本次需求的行为定义、规则约束、验收标准、影响范围写清楚。这一步花的时间大概占开发总时长的 30%~40%，刚开始会觉得慢，但后面省下的返工时间远超这个成本。
2. 喂给 Harness：启动带sdd-checkSkill 的任务，spec-injector 会自动把规范文件塞进上下文，并用提示词模板要求 Agent"只实现规范里描述的行为，不主动扩展需求"。
3. 跑边界守卫：AI 每完成一次文件修改，boundary-guard Hook 都做一次路径白名单校验，一旦碰了名单外的目录，直接拦截并给出警告。
4. 人工审查：我只看 diff-summary 生成的三类摘要——规范内变更、规范外新增、风险变更。通常我只抽查第二类和第三类的具体 diff。
5. 验收与回退：跑完测试确认无误，让 AI 自己更新规范状态为"已实现"，然后提交。如果验收失败，直接走任务级分支回退，重新来一遍。

这套流程跑下来，我最大的感受是：AI 编程真正有意义的升级，不是让它写得更快，而是让它变得可预期。氛围编码时代，你期待的是惊喜；SDD + Harness 这套玩法，你期待的是稳定。两者并不矛盾——你想探索新功能雏形时，偶尔氛围一把没问题；但要朝着生产环境长期迭代，就必须从"让 AI 自由发挥"切换到"让 AI 按规范施工"。

我现在打开 IDE 准备动手之前，已经养成了条件反射：先问自己一句，"这个特性的规范写好了吗？"如果没有，绝不直接开对话窗口让 AI 猜。这个习惯，就是我从氛围编码的坑里爬出来后，收获的最大一笔财富。如果你正处在"AI 很好用但代码库越来越乱"的阶段，建议你从下一周开始，专挑一个小模块把规范写出来，然后套上一套最轻量的 Harness 约束跑一跑，也许也会回不去了。