企业官网建设流程全解析

“AI 写代码一时爽，代码失控火葬场。”这句话是我这两年做 AI 辅助开发落地时最真实的感受。团队里每个人都想让 AI 多干点活，可一旦让模型放开手脚，它能在不知不觉中把你不想要的东西也写进项目里：自作主张的依赖、模棱两可的命名、脱离业务规则的边角逻辑。你会发现，真正难的不是让 AI 会写代码，而是让 AI 在一个可控的边界里写代码。也正因此，最近我一直在琢磨一个组合：SDD 规范驱动 + Harness 驾驭工程 AI，用来搭建一套真正的可控化 AI 辅助开发体系。

这套体系解决的是“AI 辅助开发如何从‘玩具’走向‘生产力’”的问题。单纯让 AI 写代码、做代码补全、生成测试用例，这些能力大家早就玩顺了，但一旦进入真实项目，你会发现 AI 经常在给你“埋雷”。而 SDD 的思路是：先定义好一个不可妥协的规范契约，再让 AI 在规范框架内执行；Harness 则负责把 AI 的能力封装成可编排、可复用、可观测的工程组件——它不替代模型，而是给模型套上“缰绳”。这套组合特别适合正在做 AI 工程化落地、想把 AI 嵌入到团队交付链路里的开发者和架构师。

1. 为什么“可控化”是 AI 辅助开发的生死线

1.1 AI 辅助开发的失控焦虑

过去这半年，我见过太多团队在引入 AI 编程工具之后经历“先兴奋、后崩溃”的过程。第一个星期，大家觉得 AI 无所不能，什么函数都能帮你写，什么测试都能帮你补；第二个星期开始发现代码开始出现莫名奇妙的重复逻辑、不存在的 API 调用、以及从某个开源项目里“缝合”过来的历史包袱；等到了第三四个星期，Code Review 已经无法看下去了，因为 AI 生成的代码占到了全量变更的 70%，而 Review 的时间反而翻了倍。

问题的根源并不在于模型能力不行，恰恰相反，模型能力越强，失控的破坏性就越大。一个没有约束条件的 Agent，在拿到“帮我优化一下订单模块”这种模糊指令时，它不会说“我不确定你的优化标准”，而是会直接动手，改掉你以为绝对不会动的核心封装，顺带重构了数据库索引。等你发现时，几千行 diff 已经躺在分支里了。这种失控感，是所有从“AI 写代码 Demo”迈向“AI 辅助开发落地”的团队都会撞上的墙。

另一个被很多人忽略的失控点是“不可复现性”。同一条指令，昨天跑和今天跑，结果可能完全不一样。这在大模型时代是常态，但在软件开发这个靠确定性吃饭的领域里是大忌。你没法保证 AI 每一次生成的代码都遵守同样的质量基线，除非在 prompt 之外还有一套程序化的校验机制兜底。

1.2 SDD 规范驱动：不是需求文档，而是验收契约

SDD，全称 Specification-Driven Development，中文我们可以叫它“规范驱动开发”。它和传统意义上的“需求文档”有本质区别。需求文档是写给人类看的，语气自由、目标宽泛，哪怕写得不够精确，人也能靠上下文脑补出意图。但 SDD 里的规范（Spec）是写给“模型 + 机器”双方看的契约，它要求每一个输入、输出、边界条件、性能指标、禁止事项都被明确写死。

我举个生活中的例子帮大家理解：你要装修房子，跟施工队说“我要一个温馨的客厅”，施工队可以自由发挥，结果大概率是你想骂人。但如果你把图纸画好、材料定好、灯位标高标好、验收标准写清楚，施工队只能按照图纸干，效果再差也有底线。SDD 就是把“温馨”翻译成“客厅东南角 3 米处设置 2700K 色温洗墙灯、沙发背景墙乳胶漆色号为 XXX、完工后照度不低于 300lx”这样的硬指标。

在 AI 辅助开发的语境里，SDD 的规范文件通常包括：目标描述、输入数据格式、输出产物格式、依赖约束、编码风格约束、异常处理要求、验收测试用例，以及“禁止事项”清单。这些内容不是用来“启发”模型的，而是用来“锁定”模型行为边界的。我在实际项目中把规范文件放在项目根目录的spec/文件夹里，每次让 AI 干活之前，必须先把对应的规范文件丢给它，再让它写代码——效果立竿见影。

1.3 Harness 在体系中的位置：调度、插件与技能包

有了一纸规范，还需要一个能严格遵守规范的“执行者”。大模型本身只是一个会说话的脑子，它没法自己打开文件、跑测试、调用内部系统接口。Harness 解决的就是这个问题：它是一个工程化的 AI 执行框架，负责把模型连接到真实世界的工具链上。

用驾驶来类比，模型是发动机，Harness 是方向盘、仪表盘和传动系统。Harness 不改变发动机的排量，但决定了这辆车以什么路线行驶、在什么条件下刹车、怎么把动力传输到轮子上。它能加载插件来扩展模型的能力边界——比如文件读写插件、命令行执行插件、局域网服务调用插件；它能定义 skill（技能包），让模型在特定场景下遵守一套标准作业程序；它还能编排工作流，把多个步骤串成一条自动化的流水线。

这里要澄清一下 Harness 和普通 Agent 的区别。普通的 AI Agent 更像是一个“实习生”，你给个目标，它自己摸索路径，过程不可见、不可控；而 Harness 里的工作流更像是一台“自动售货机”，每一步动作、每一次工具调用、每一个判断节点都是提前定义好的，模型的角色只是在每个节点上执行“自然语言计算”。你可以随时看到它正在做什么、在哪一步停了、为什么停。这个区别在工程落地时极其关键，因为它意味着诊断、回滚、审计成为可能。

2. SDD 规范驱动的核心环节与实战写法

2.1 三段式开发闭环：写规范、生成、校验回环

SDD 不是让你放弃和 AI 对话，而是让你把对话收敛到一个闭环里。我在团队里推广的标准流程是三步：首先，把需求翻译成规范文档；然后，基于规范生成代码或配置；最后，用自动化测试和静态检查做校验，校验不通过就回到第一步修订规范或让 AI 根据报错信息迭代。这个闭环跑通后，AI 生成的内容不再是“一次性运气”，而是可持续维护的资产。

这个闭环中最容易被人忽视的是第三层“校验回环”。很多团队用完 prompt 拿到代码就算完事，这恰恰是失控的开端。AI 生成代码后，我们必须用 lint 工具、单元测试、端到端测试去验证规范中的每一条约束是否被满足。更强一点的团队会把规范中的验收指标写成脚本化的断言，比如“查询接口 P95 延迟必须低于 200ms”“所有对外 API 必须包含 rate limit 注解”，然后把这一类断言接到 CI 里。

我这里要强调一个观念转变：SDD 里的规范，实际上是在把“人给 AI 提要求”这件事，从“对话式”升级成“配置式”。对话是临时性的，文档和断言是持久性的。同一个 AI 工具，今天用可能给你生成 A 风格的代码，明天用可能生成 B 风格；但只要规范文档和校验脚本还躺在仓库里，任何风格都必须过同一道关卡。

2.2 规范文档的关键要素有哪些

很多同学第一次写规范时容易走两个极端：要么写得像一篇作文，通篇废话；要么只给一句话，管不住 AI。我自己打磨过很多版后，认为一份能真正约束 AI 的规范，至少要有下面这些要素：

• 目标与范围：这个任务要交付什么，明确“不做什么”往往比“做什么”更重要。
• 输入与输出：数据从哪来、格式长什么样、产出去哪；给出示例片段。
• 约束条件：必须遵守的框架版本、命名规范、目录结构、依赖白名单。
• 验收标准：可量化的指标，比如测试覆盖率、响应时间、日志格式要求。
• 禁止事项：明确写出 AI 不许动哪些文件、不许引入哪些库、不许修改哪些配置。
• 示例产物：给一个符合要求的样例，模型会疯狂模仿样例格式。

把禁止事项写清楚，是我从血泪里学到的。最开始我写规范只写“应该”怎么做，AI 经常自作主张去改无关文件；后来我把禁止事项放在规范靠前的位置，比如“禁止修改src/main/resources/application.yml”“禁止删除migrations/下任何历史脚本”，失控比例明显下降。因为模型对“不要做什么”的遵循，其实比对“应该做什么”的遵循更精准。

2.3 一份可落地的规范文件示例

下面我直接放一份我在内部项目里用过的规范模板，大家根据自己的场景改一改就能用：

# 规范：库存报表生成任务（Spec 1.0） - 目标：根据 `/data/inventory/raw.csv` 生成日报表 `/data/inventory/report.md` - 输入格式：CSV，字段顺序为 sku_id, warehouse_code, quantity, updated_at - 输出格式：Markdown 表格，表头为 SKU ID、仓库代码、当前库存、更新时间 - 聚合规则：同 sku_id 在多个仓库的记录汇总为一行，数量求和 - 数据清洗：quantity 为空白或非数字的行直接丢弃，并在文件末尾追加统计信息 - 性能约束：脚本必须在 5 秒内完成处理，不得使用外部 API - 质量校验：执行 `pytest test_inventory_report.py` 必须全部通过 - 禁止事项： - 禁止修改 `/data/inventory/raw.csv` - 禁止引入 pandas 以外的任何数据处理依赖 - 禁止删除输入文件中未在报告中出现的字段 - 示例产物： | SKU ID | 仓库代码 | 当前库存 | 更新时间 | |--------|----------|----------|----------| | A1001 | WH-01 | 231 | 2025-01-15 10:00 |

这份规范丢给任何支持文件读写的大模型，配合 Harness 的插件，它都能严格按要求产出报表。你可能会觉得“写规范比写代码还费劲”，但别忘了，这份规范是可以复用的。下个月报表需求改成按周汇总，你只需要改聚合规则和输出文件名，AI 立刻又能在新约束下干活，比重新调一次 prompt 稳定得多。

2.4 为什么 SDD 能压制 Agent 的“自由发挥”倾向

底层逻辑其实很简单：大模型在做生成时，遵循的是一个“最大化概率”的原则，遇到模糊不清的地方，它会去补全它认为最合理的细节。如果你不告诉它金额字段必须保留两位小数，它可能输出 3 位；如果你不告诉它不能碰历史迁移脚本，它可能为了“保持风格一致”把旧脚本也顺手改了。这不是模型蠢，而是人的指令没给够信息量。

SDD 从两个层面解决这个问题。第一层，它把隐性知识显性化：团队里那些只可意会不可言传的约定，比如“幂等接口必须校验 requestId”“错误信息必须包含 traceId”，统统写进规范文档，模型第一次就能看到。第二层，它把自由度压缩到可以校验的区间：哪怕模型真的在某处自由发挥，校验回环也会立刻把它揪出来，而不是等代码合并后由人肉背锅。所以我会说，SDD 不只是给 AI 看的文档，更是给整个工程团队看的“安全护栏”。

3. Harness 安装与工程化配置实操

3.1 安装前的环境准备

要说 Harness 的安装踩坑，我先给还没用过的朋友们提个醒：在那之前，先把基础环境理清楚，能省两个小时。Harness 通常依赖 Node.js 运行时，我建议直接使用 Node.js 18 以上的长期支持版本，老版本在插件加载时容易出现兼容问题。

其次是模型服务的准备。Harness 本身不内置大模型，它需要对接一个可调用的模型服务。本地开发时你可以对接 OpenAI 兼容的本地推理服务或者云端 API；企业内网环境则建议提前把模型权重部署好，通过内网地址暴露成标准接口。跑通之前的判断标准很简单：打开内网机器的终端，直接 curl 一下模型服务的地址，如果能在几秒内得到回复，Harness 后续就稳了。

还需要注意的是网络与下载渠道。插件市场里的插件需要从离线包或者镜像仓库获取，我踩过的坑是在某些有网络隔离要求的环境里直接敲安装命令，结果等了半天，日志显示卡在下载阶段。正确的做法是提前在有网环境下把安装包和所需插件包下载好，拷到内网机器上再执行本地安装。

3.2 Windows、Linux 与内网服务器的安装步骤

我分别说下常见场景的操作要点。开发机上如果只是体验，最简单的是用全局包管理工具安装 Harness 的命令行入口：

npm install -g harness harness --version

这里我给的是通用命令形式，不同发行渠道的包名可能带有后缀或组织前缀，以你所用版本的官方文档为准。装好后执行版本命令，能打印版本号说明安装成功。Windows 用户需要注意，如果是在 PowerShell 里执行全局命令遇到权限报错，多半是脚本执行策略限制，用管理员身份打开终端再执行一次即可。

Linux 服务器上安装时，我建议加上用户级目录配置，避免污染系统环境。设置一个专门的工作目录，以后所有的 harness 配置、插件、skill 数据都存在这里：

mkdir -p ~/harness-workspace cd ~/harness-workspace npm install -g harness export HARNESS_HOME=~/harness-workspace

真正要落地到内网时，麻烦主要在“离线”两个字。我的做法是：在有网的一台机器上执行harness plugin download --all，把插件离线包和核心二进制打包成一个harness-offline-bundle.tar.gz，再拷贝进内网。内网机器上解压后，设置离线模式环境变量并指向本地仓库：

tar -xzf harness-offline-bundle.tar.gz -C ~/harness-workspace export HARNESS_OFFLINE=1 export HARNESS_PLUGIN_SOURCE=local

设置完成后启动 Harness，它会优先从本地仓库加载插件，不再试图访问外部网络。这一步做完，内网部署的基础就通了。有同学问“装到 D 盘行不行”，Windows 下当然可以，但要注意一个细节：配置目录和插件目录如果带有中文或空格路径，某些插件脚本在解析路径时可能出错，我建议安装路径一律用纯英文无空格。

3.3 插件系统：给 AI 接上“手”和“眼”

没有插件的 Harness，就像一个只有大脑没有四肢的人，它能想但做不了。插件系统的价值在于把模型能力与真实工具链打通。最常用的几个插件类型包括：文件系统插件（读写项目文件）、命令执行插件（跑 shell 命令、pytest、eslint）、HTTP 请求插件（调用内部 API）、浏览器自动化插件（操作页面，这也是 RPA 场景的基础）。

插件管理的命令行通常长这样：

harness plugin list harness plugin install fs-toolbox harness plugin install command-runner harness plugin uninstall browser-automation

我强烈建议不要一股脑装一堆插件。插件越多，加载越慢，prompt 上下文被插件说明占掉的空间越大，模型反而会“选择困难”。我个人的标准是：一个任务只装必要的 3 到 5 个插件。比如做代码生成，就装文件读写、命令行、代码搜索这 3 个；做 RPA 采集，就装 HTTP 请求、浏览器自动化、数据清洗这 3 个。剩下的一律按需再装。

3.4 Skill 机制：把领域知识封装成可复用的技能包

如果说插件是给 AI 的工具，skill 就是给 AI 的“操作手册 + 考试大纲”。一个 skill 通常由三部分构成：一份说明文档（写清楚在什么场景下启用、任务怎么拆解、质量标准是什么）、一组参考示例（给模型看“规范产出长什么样”）、以及一些脚本或模板资源。

我自己在工程里维护 skill 的标准目录结构如下：

skills/ inventory-report/ SKILL.md examples/ report-sample.md scripts/ validate.sh templates/ spec-template.md

部署 skill 很简单，把它放进 Harness 的skills目录，重启后就会自动加载。内网部署和本地部署逻辑一致，只要把整个skills文件夹一起拷进内网环境即可。不过这里有个坑：有些 skill 会在首次加载时尝试从网络拉取依赖，在内网环境会失败。对策是写 skill 时就把运行所需的资源文件放到 skill 自己的目录下，脚本里用相对路径引用。

Harness 和具体的 Agent 框架还有一个重要差异：在 Agent 模式里，模型自己决定“我该调用什么工具、按什么顺序调用”；而在 skill 模式下，skill 文档本身就是一套标准作业程序，模型更多是照着执行。所以 skill 写得好不好，直接决定执行质量。我写 SKILL.md 时会刻意遵循“场景 — 步骤 — 校验 — 异常处理”四段式，把每个环节该调用的插件名也写进去，这样模型在流程走到某一步时不会犹豫。

4. 完整案例：从规范到 Harness 工作流落地

4.1 场景选择：企业内部库存日报生成

理论讲再多，不如跑一个完整案例。我选了一个我们内部已稳定运行两个月的场景：库存日报生成。业务方每天上午需要一份 Markdown 格式的库存日报表，数据来源是仓库系统导出的一份 CSV。这个任务重复、琐碎、格式要求严格，非常适合做成 SDD + Harness 的标准流水线，而且它还带了一点 RPA 的影子——如果数据不是通过导出 CSV，而是需要去内部系统页面点击下载，那就要用到浏览器自动化插件。

这个场景的核心难点有三个：一是输入数据经常会多出末行合计、空行和损坏编码；二是业务方对报表的格式变化零容忍，少一列、多一列都会引起投诉；三是执行环境必须稳定，不能依赖某个同事每天早上手动跑。这些痛点刚好是 SDD 和 Harness 擅长处理的。

4.2 第一步：编写 SDD 规范

我直接贴出当时定义的规范文件关键部分：

# 规范：每日库存报表生成（Spec 2.0） - 数据源：`/data/inventory/daily_export.csv` - 输出路径：`/data/inventory/report_YYYY-MM-DD.md` - 表头要求：SKU ID、仓库代码、当前库存、更新时间 - 汇总规则：按 SKU ID + 仓库代码分组，同一组的多行记录取更新时间最新的一行 - 异常处理： - sku_id 为空或缺失 -> 丢弃并计入 error_count - quantity 无法解析为数字 -> 置为 0 并计入 error_count - 质量门禁： - 报告末尾必须包含 `采集时间`, `数据行数`, `错误行数` - 报告不得出现空表 - 禁止事项： - 禁止修改原始 CSV 数据 - 禁止使用非白名单依赖（只允许 csv 标准库和 strftime 类格式化函数）

这份规范写完后，我没有急着让 AI 干活，而是先把它交给团队同学做一次“猜提示词演习”：如果一个人只有这份规范、没有任何其他上下文，能不能准确说出现在要生成一份什么样的报表？能说出来，说明规范信息足够。说不出来，说明规范还有缺口，需要补。这个演习是我推荐的验证技巧，比直接审查 markdown 文档有效得多。

4.3 第二步：定义 Harness Skill 与插件封装

规范写好后，接下来要把它变成 Harness 能执行的技能。我先安装了两个插件：文件系统读写插件和命令行执行插件。然后写了一个inventory-reportskill，SKILL.md 内容要点如下：

# SKILL: inventory-report ## 启用场景 当用户请求生成每日库存日报时启用。输入参数为日期，格式 YYYY-MM-DD。 ## 执行步骤 1. 调用 file-reader 插件读取 `/data/inventory/daily_export.csv` 2. 调用 command-runner 插件执行 `python scripts/normalizer.py` 3. 校验生成报告的完整性： - 检查表头是否符合 spec 2.0 - 检查末尾是否包含统计信息 4. 输出报告路径给用户 ## 参考规范 规范文件位置：`/spec/inventory_report_spec.md` 在生成报告前，必须重新读取该规范，确保理解最新约束。 ## 异常处理 - 输入文件不存在：终止任务并提示“未找到昨日导出文件” - 报告校验失败：重新执行步骤 2，最多重试一次

把这份 SKILL.md 连同normalizer.py脚本和示例输出文件放入skills/inventory-report/，重启 Harness，这个技能就被自动注册了。之后执行任务时，只需要对 Harness 说一句“生成 2025-01-15 的库存日报”，它就会严格走上面的流程，而不是自己发明一套新做法。

4.4 第三步：运行工作流并校验结果

实际运行时，我会用 Harness 提供的命令行模式直接触发任务：

harness run skill:inventory-report --date 2025-01-15

运行日志会显示每一步插件的调用情况。由于输出路径固定，我还要加一层保险：在 CI 里放一个断言脚本，检查生成的 Markdown 文件是否包含规范要求的表头和统计信息。这样即便 Harness 在夜间运行，第二天业务方打开报表前，门禁已经替我们把过关了。

有一次凌晨执行时，HVAC 系统出现瞬时故障导致服务器重启，任务日志里显示模型在第三步“校验报告完整性”后自动重试了一次，最终成功生成报表。这就是可观测性和自动重试机制的价值。如果换成裸调 Agent，模型可能会在重启后从此忘掉任务，又或者生成一个缺了统计信息的半成品。

5. 常见问题与排查技巧实录

5.1 failed to load plugins 的三种诱因

很多新手一开始就栽在“插件加载失败”这个槛上。我归纳了三种最常见的诱因。第一种是插件目录权限不对，Harness 插件需要写入缓存文件夹，如果目录权限不足就会加载失败；第二种是插件与主程序版本不匹配，比如主程序已经升级到新协议，而插件还是旧版本；第三种是内网环境下插件依赖缺失，安装插件时有依赖包没有进入离线包，运行时自然加载不了。

排查方法是分步骤看日志。先harness plugin list，看插件列表里有没有正常标记；再手动调用一次插件看报错信息；最后检查插件目录里的 manifest 文件，确认依赖版本。不要一上来就重装，重装往往治标不治本。

5.2 web boot: 1 entry did not activate 的错误指向

报错信息里带着web boot，意味着问题出在 Harness 的桌面端或 Web 界面入口，而不是命令行核心。我遇到过几次，现象是桌面端启动后白屏或提示入口未激活。绝大多数情况是插件市场入口的静态资源加载失败，或者是本地 Web 服务端口被占用。

我建议先回退到命令行模式，把harness serve --headless启动的服务停掉，再启动桌面端。如果还是不行，看日志中 web 入口模块在等什么资源，把离线包里的 web 静态资源重新解压一遍。曾经有个同事的机器上装了安全软件，把 Harness 的 Web 服务拦了，导致入口始终激活不了，加白名单后就正常了。

5.3 Skill 读取文件失败：Windows 权限问题 setnamedsecurityinfow

Windows 环境下跑 Skill 时，如果脚本读取文件报setnamedsecurityinfow failed (win32)，这不是 Harness 本身坏了，而是操作系统文件 ACL 层返回了失败。常见原因是文件被其他进程占用、文件上设置了拒绝读的 ACE、或者杀毒软件实时扫描拦截了句柄操作。

我的处理顺序是：先确认文件没有被 Excel 或编辑器等进程独占打开；然后用系统管理员权限启动 Harness；最后如果问题依旧存在，到文件属性的安全标签页里加一条当前用户的完全控制权限。注意，改了 ACL 以后需要重启 Harness 会话才能生效。有些自动化执行策略会要求机器在凌晨锁屏状态运行任务，Windows 锁屏状态下某些权限相关的 API 会异常，这种情况可以把任务注册为系统服务，而不是依赖桌面会话。

5.4 安装失败与卸载清理的实操建议

不少同学反馈“Harness 无法安装”，多半是历史版本的残留配置、全局目录权限、或者包管理器缓存冲突。我建议先清理 npm 的全局缓存，再确认配置目录存在，再重新执行安装。

npm cache clean --force rm -rf ~/.harness npm install -g harness

这里要特别提醒一点：不要为了卸载而手动删除乱七八糟的文件，否则下次安装必出问题。标准卸载流程是先用harness plugin list把所有插件禁掉，再停掉所有相关进程，最后删除配置目录。我见过有人绕过卸载直接删安装目录，导致路径配置写死在用户级配置文件里，新版本装完还在用旧配置，最后各种诡异报错。

5.5 内网环境的限制与实践建议

内网部署最大的敌人是“下意识觉得离线等于安全”。离线确实能缓解供应链安全问题，但也会带来模型版本锁定、skill 更新滞后等运维负担。我建议在内网建立一条“外网镜像同步 — 补丁包导入 — 定期版本验证”的流程，至少每两个月同步一次，否则模型和插件落后太多，SDD 规范的编写也会变得别扭。

另外一个细节：内网环境里如果有多个团队共用同一个 Harness 集群，一定要把 skill 和插件的版本发到集中配置中心管理，避免某个人在本地改了一个 skill，其他人运行时行为不一致。可控化 AI 辅助开发体系，说到底就是让 AI 的每一次输出都能被追踪、被重复、被审计。而内网环境恰恰是最容易暴露这类管理短板的地方，值得多花一点心思。

我个人在实际操作中的体会是：SDD 规范和 Harness 这类工程框架，本质上是在帮我们转换心态——不再指望 AI“聪明到能猜对我们想要什么”，而是逼我们把需求想清楚、写明白、可度量。这个过程一开始会有点笨拙，甚至会让你怀疑“写规范比写代码还慢”，但一旦跑通一两个真实场景，把规范模板和 skill 沉淀下来，后续的效率提升是指数级的。工具会快速迭代，今天叫 Harness，明天可能有别的框架，但“先定义验收标准，再让 AI 在约束里创造”这个原则，我相信在未来很多年内都会是工程 AI 的底层逻辑。