企业官网建设流程全解析

今年大家聊 AI Coding，热度已经明显从“一次对话能生成多少行代码”转移到“这个项目到底能不能让人省心”上了。我观察到一个特别明显的变化：现在社区里高频出现的已经不是 prompt 技巧，而是一个听起来很有运维感的词——Harness。有人问 DeepSeek Harness 怎么装，有人问 Codex Harness 的 Skill 脚本怎么写，也有人自己搭了框架之后再回过头来琢磨“Harness 和 Agent 到底什么关系”。归根结底，大家都在做同一件事：给 AI Agent 套上一套可控的工程缰绳，让它能在真实仓库里按流程干活，而不是漫无目的地改代码。

这篇文章要分享的，就是我在企业级 AI Coding 落地中摸索出来的一套 Harness 工程实践：用 8 个 Skill 把需求理解、架构设计、编码执行、代码审查、测试生成、文档同步、发布联动、反馈复盘串成一条完整链路。适合正在做 AI Coding 平台建设，或者想把 Agent 写码真正接到团队工作流里的同学；如果你只是拿 AI 写点脚本，也能从这套设计里理解 Harness 的底层思路。

1. 先把概念对齐：Harness 工程到底是什么

1.1 Harness 与 Agent 的边界

Harness 英文原意是马具、挽具，放到工程语境里很形象。我们常说 Agent 是“大模型 + 记忆 + 工具调用循环”，负责思考、行动、观察，也就是“想做什么、怎么做”；而 Harness 是这个循环外面的那套控制系统，负责启动、暂停、回滚、记录，也就是“能不能做、做到哪一步停、出事怎么兜底”。

很多人第一次接触 Harness 会误以为它是又一个 Agent 框架，或者只是 IDE 插件的替身。实际上它更像一层“中间管理层”。Agent 本身可以很聪明，但聪明不意味着可靠；Harness 的作用恰恰是用工程手段去约束这种聪明。比如，Agent 在修改代码时可能觉得自己“已经理解了项目结构”，但 Harness 可以通过预置的文件访问白名单、命令执行沙箱、diff 行数上限，把风险提前卡住。

我对团队说的最多的一句话是：Agent 是驾驶员，Harness 是道路、红绿灯和刹车系统。没有 Harness 的 Agent 也能开车，但没人敢让它上企业级项目的路。

1.2 Skill：可复用的“业务能力单元”

有了 Harness 之后，还要解决另一个问题：Agent 得具备“干某一类具体活”的能力。这个能力包就是 Skill。

Skill 不是普通的提示词模板，它通常打包了四样东西：

• 触发器（Trigger）：什么时候被调用，比如新建 issue、PR 变更、定时任务。
• 使用说明（Instruction）：给模型的行为指引，包括步骤和约束。
• 工具声明（Tools）：这个 Skill 可以调用哪些外部工具，比如代码搜索、依赖分析、测试命令、Git 操作。
• 校验与输出（Validation & Output）：模型产出必须满足的格式和校验规则，一般用 JSON Schema 约束。

举个例子，团队里经常要写技术方案。如果每次都用一句“帮我设计一下”让模型临场发挥，输出格式五花八门，很难复用。但封装成“架构方案 Skill”后，模型必须按 ADR（架构决策记录）模板输出，必须调用依赖分析工具，必须返回结构化的 JSON。这样 Harness 才能把这个结果交给下一个 Skill 继续加工。

我一直跟研发强调：Skill 的颗粒度决定了 AI 流程的稳定度。颗粒度太粗，Skill 就退化成“带格式的 prompt”；颗粒度太细，编排成本又会失控。

1.3 企业级落地的三个硬约束

个人用 AI Coding 工具，跑飞了再重来也没事；企业级落地有三个绕不开的硬约束。

第一个是安全边界。AI 生成代码时可能会无意间读取敏感配置、执行危险命令、修改锁定文件。Harness 必须给每个 Skill 分配最小权限，比如“只能读 src 目录”“只能写 tests 目录”“不能执行 package 发布命令”。

第二个是可追溯性。整个过程要能审计：谁在什么时候触发了哪个 Skill，模型生成了什么，谁做了人工审批，哪一步失败了。没有审计，AI Coding 就没办法在合规要求严格的团队中推广。

第三个是降级和人工接管。AI 链路不能是“单点赌命”。某个 Skill 连错三次，Harness 必须能自动降级，把任务转给人工处理，或者回滚到上一个稳定检查点。

我在项目里给这三个约束分别对应了三个机制：RBAC 权限模型、全量操作日志、任务状态机。这样即使某个 Skill 跑坏了，损失也是可控的。

2. 8 个 Skill 串起的全链路：从需求到复盘的闭环

2.1 为什么是 8 个，而不是 3 个或 20 个

企业软件研发流程如果高度概括，是“想清楚、写出来、验明白、发出去”四个阶段。但真正落地，每个阶段还要再拆出关键动作。我把 AI Coding 全链路裁剪成了 8 个 Skill：

1. 需求解析 Skill
2. 架构方案 Skill
3. 编码执行 Skill
4. 代码审查 Skill
5. 测试资产 Skill
6. 文档同步 Skill
7. 发布联动 Skill
8. 反馈复盘 Skill

这 8 个不是拍脑袋定的，而是按“端到端闭环 + 每段可人工介入”的原则裁剪出来的。少于 8 个，意味着某些环节只能靠人肉补位；多于 8 个，编排成本和触发冲突会明显上升。比如需求解析和架构方案看似可以合并，但如果你让一个 Skill 同时干“理解需求”和“设计技术方案”，它很容易在需求还没确认时就开始写代码，这是大忌。

每个 Skill 对应一个“门禁”环节。前一个 Skill 的输出没有通过校验，后一个 Skill 就不会启动。这种门禁式设计让 AI 流程具备解释性——任何一步出问题，你能立刻定位到是哪个环节。

2.2 全链路状态流：每个 Skill 输入输出怎么衔接

下面这张表是我们在 Harness 编排层定义的核心流转关系，也直接映射到任务状态机里：

实际运行中，Harness 会在每个输出节点做两件事：格式校验和语义校验。格式校验用的是 JSON Schema，语义校验会调用一次轻量模型枚举输出中的风险点。例如需求任务书里必须有可验证的验收标准，不能只写“优化性能”这种不可测的话；技术方案里如果涉及数据库变更，必须包含回滚方案。这一层校验极大地减少了下游 Skill 被脏数据污染的概率。

2.3 关键设计取舍：为什么不做“一把梭大 Agent”

现在很多产品宣传是“你把任务丢给 AI，它自己搞定一切”。这种“一把梭大 Agent”在企业级场景里并不好用，原因很现实。

第一是上下文爆炸。一个 Agent 如果把需求、代码库、测试结果、历史决策全部塞进上下文，很快会超过模型窗口，然后开始“失忆”。拆成 8 个 Skill 后，每个 Skill 只接收上一个环节的结构化输出，上下文可控得多。

第二是失败定位困难。大 Agent 跑偏时，你很难判断是需求理解错了、方案设计有问题、还是工具调用出了岔子。拆开后，哪个 Skill 失败一目了然，可以单独重试或降级。

第三是权限没法精细控制。一个全知全能的 Agent 要么给太多权限，有安全风险；要么给太少权限，干什么都要打断你。拆成 Skill 后，可以给“编码执行 Skill”开放写权限，给“架构方案 Skill”只开放读权限，权限被最小化。

这个取舍的本质是“复杂任务拆成简单流水线”。它牺牲了一点端到端的“智能感”，换来了稳定性和可维护性。在企业里，稳定性永远排在炫技前面。

3. 逐个拆解：8 个 Skill 的落地方式与调试要点

3.1 Skill 1 需求解析：把模糊想法变成任务书

几乎所有 AI Coding 翻车，根源都在“需求没有说清楚”。需求解析 Skill 的目标，是逼着模型在动手前先输出一份结构化的需求任务书。

我用一个简化版的 Skill 配置来说明：

name: requirement-parser version: 1.3.0 description: 将原始需求转换为结构化任务书 triggers: - event: issue.state_changed condition: new_status == "triage" - event: command.manual command: /parse-requirement tools: - repo.code_search - docs.read - issue.read_comments steps: - extract: fields: - goal - scope - users - acceptance_criteria - constraints - risks - verify: required: - acceptance_criteria - scope - estimate: method: llm_analysis input: repo.code_search_result - output: format: json schema: task_schema_v3.json checkpoints: - "缺失验收标准时，必须列出澄清问题并转人工" - "影响模块清单来自代码搜索，不得凭空填写"

这里的关键设计是checkpoints。第一项要求“缺失验收标准时，必须列出澄清问题并转人工”，是为了禁止模型自行脑补需求。第二项要求“影响模块清单来自代码搜索”，是为了防止模型编造项目结构。实测下来，这个 Skill 是整套链路里回报率最高的，因为它把后续所有 Skill 的地基打牢了。

调试这个 Skill 时最常踩的坑是：模型把“输出 JSON”理解成“只有 JSON”，导致给用户的解释性内容全丢了。后来我在校验器里加了summary字段，要求同时输出给用户看的自然语言摘要和给下游用的结构化数据，两边都不耽误。

3.2 Skill 2 架构方案：先写设计，再碰代码

架构方案 Skill 存在的价值是“延迟编码”。很多 AI 写代码翻车，就是因为拿到需求立刻开写，跳过设计。这个 Skill 的输出是一份技术方案，包含：

• 技术选型说明
• 变更涉及的前后端模块清单
• 依赖与数据模型的影响面
• 风险与回滚策略
• 测试策略建议

我给这个 Skill 配置了一个“影响面阈值”机制。如果模型估算的变更文件超过 15 个，或者涉及数据库表结构变更，方案会自动进入“待人工审批”状态，不会继续往编码环节走。这个机制帮我们挡住了好几次“AI 迷之自信的大重构”。

架构方案 Skill 还可以调用绘图工具生成架构图。我们试过让模型输出 Mermaid 然后转成图片，但效果一般；后来直接接了一个内部架构图渲染服务，模型只输出节点和连线关系，由服务端出图。企业环境里更容易落地，因为图片资源是可控的。

3.3 Skill 3 编码执行：安全写码与“主动停下来”

编码执行 Skill 是核心，也是风险最高的一环。它的任务不是“尽可能多地写代码”，而是“在约束下正确完成变更”。我给它定义了四条铁律：

• 不碰白名单之外的文件
• 不执行危险命令（强制数据库迁移、发布、删除分支等）
• 不在没有测试的情况下提交大段代码
• 遇到三类情况必须停下：现有逻辑与任务书冲突、需要新增外部依赖、涉及跨模块大规模重构

为什么强调“主动停下来”？因为 AI 并不知道企业内部系统的隐藏约束。有一次模型为了实现某个功能，想直接改一个公共库的内部方法，影响面波及六个业务模块。如果没有停下来机制，这种改动进到 MR 里，Review 成本极高。

在 Harness 层，我给这个 Skill 挂了文件锁和 diff 量监控。多个 Skill 并行时，文件锁防止同时写同一个文件；diff 量超过阈值时，系统自动拆分成多个变更批次。实际操作中，一个 500 行以内的变更，模型完成度最高；超过 1000 行，错误率显著上升，所以宁可拆成多个小批次。

3.4 Skill 4 代码审查：让 AI 黑起自己来

审查 Skill 最容易做成摆设，因为模型给自己写的代码做 Review，容易“自我感觉良好”。我的解决方法是给这个 Skill 加“对抗性角色”。审查时必须同时扮演三类人：安全评审、性能工程师、维护者。它要回答三个问题：

• 这段代码有没有安全漏洞？
• 有没有明显的性能瓶颈？
• 三个月后其他人来维护，能看懂这段代码吗？

关键实现是审查 Skill 不能只看 diff，还要结合上下文。只看 diff 的审查往往漏掉跨函数影响，所以我会把涉及的核心函数调用链一起喂给模型，并让它输出“建议阻塞”和“建议优化”两类问题。如果出现“建议阻塞”级别问题，Harness 会跳过提交，直接把 diff 打回“编码执行 Skill”重做。

这里要提一个细节：审查 Skill 的 temperature 必须调低，我一般设在 0.1 以下。Review 是确定性任务，不需要创意发散。温度高了，模型会给出很多似是而非的风格建议，反而淹没了真正的问题。

3.5 Skill 5 测试资产：跑通比生成更多重要

测试资产 Skill 很容易被误解为“生成单测用例”，但真正难的是让测试跑起来。我们遇到过模型生成了 80% 代码行数的测试，结果有一半因为环境依赖问题执行不了。所以这个 Skill 我设计了三个步骤：

1. 读取变更代码，分析测试计划
2. 生成单测和必要集成测试
3. 在容器中真实执行测试，收集报告

为了稳定执行，所有测试统一跑在预置 Docker 容器里，避免“在我电脑上是好的”这种问题。容器里预装了依赖、Mock 服务和 SQLite 数据库，不给测试访问生产数据库的机会。这个约束同时保证了安全性和复现性。

覆盖率阈值我通常设在 60% 到 70%，对核心函数还可以单独提高。如果测试后覆盖率不达标，Skill 会继续生成测试直到达标或达到最大尝试次数。实测这个机制让流水线中的 AI 代码评审问题数下降不少，因为很多逻辑错误都是写测试时才暴露出来的。

3.6 Skill 6 文档同步：AI 写代码的“售后”

几乎每个 AI Coding 项目都会忽略文档。代码合进去了，文档还是旧的，这在企业里是很重的技术债。文档同步 Skill 做的事，是在代码变更通过测试后，自动更新 README、接口文档和 CHANGELOG。

这个 Skill 要控制“动什么文档”。我给模型配了一份文档白名单，只允许改与当前变更直接相关的文件。比如一个 API 的入参变了，就更新对应的接口文档，但不允许它顺手重写整个 README。乱改文档比不更新更糟，Review 的人会崩溃。

还有个实际细节：文档同步 Skill 的 prompt 里要明确“使用与代码变更一致的词汇风格”，否则模型容易把文档改成它自己的表述习惯，和团队风格冲突。文档生成后又通过脚本比对，只保留 diff 中实际变化的段落，防止大段无意义重写。

3.7 Skill 7 发布联动：接到流水线才叫闭环

编码、测试、文档都完成之后，发布联动 Skill 负责把成果推向工程化流水线。它的核心动作是：创建 MR/PR、触发 CI、跟踪流水线、反馈部署状态。这个 Skill 的难点不在模型，而在外部系统的对接。

我先调用 Git 平台 API 创建 MR，提交信息由编码执行 Skill 生成，但会经过模板化处理。接着触发 CI 流水线，并轮询状态。如果流水线失败，Skill 会把失败日志摘录下来，读取关键错误信息，然后决定是转给人处理，还是自动回到编码执行环节做一次修复。

对外部系统调用要做三个防御处理：幂等、超时、人工接管。比如“创建 MR”重复调用时不能创建多个；“轮询流水线”不能无限等；连续失败三次必须发通知给人。这些逻辑对输出内容的“智能性”没要求，但对系统稳定性帮助巨大。

3.8 Skill 8 反馈复盘：让每个失败都变成经验

反馈复盘 Skill 是 8 个里最容易被砍掉，但长期价值最大的一个。它定期收集三类信息：线上问题、失败测试用例、代码评审意见。然后进行两个动作：

第一，聚类分析，找出问题发生的共性原因。比如“接口超时”反复出现，可能指向某个架构决策有问题；“测试失败”集中在一个模块，可能说明那个模块需要补重构。

第二，更新知识库和 Skill 的 few-shot 示例。如果发现模型在新增类型时反复犯同样的错误，就把这个 case 提炼成经验示例，注入到后续编码 Skill 的上下文中。这就形成了链路自学习的闭环。

让我印象最深的一个案例：反馈复盘 Skill 发现新代码中 70% 的问题集中在“异步处理没做好”上。于是我们把这个 case 沉淀为反模式示例，并在编码执行 Skill 里增加了一条强制检查：“凡是涉及异步调用，必须在代码中显式说明错误处理和超时策略”。一个月后，相关问题数量明显下降。

这个 Skill 让整套链路不是“一次性消耗品”，而是可以越用越懂业务、越用越稳的基础设施。

4. 实战避坑：Skill 编排里的那些坑

4.1 两种最容易翻车的 Skill 编排反模式

第一种反模式是把 Skill 做成“超级提示词”。有同事为了省事，把需求解析、架构方案、编码执行全塞进一个 Skill，以为模型自己会拆。实际结果就是上下文膨胀，模型经常遗忘最初的需求约束，而且出问题时完全无法定位。

第二种反模式是“有 Skill 无状态流”。Skill 虽然定义了，但 Harness 没有做严格的输入输出校验，每个 Skill 跑完就完事，下一个 Skill 拿到的数据可能已经是脏的。这样链条越长，错误越积越深。我建议强制校验节点必须有，并且每个 Skill 的输出格式要版本化，避免上游改动悄悄破坏下游。

4.2 上下文预算与状态管理

一个很现实的问题：模型上下文窗口有限，但项目信息无限。Harness 的核心工作之一就是上下文预算管理。我通常给单次 Skill 执行设置上下文上限，比如 32k tokens，超出部分要分层压缩：最优先保留当前任务相关的代码和结构化数据，中间层用摘要替代，最底层的历史信息直接丢弃。

状态管理也很重要。任务状态机至少要包含created、running、awaiting_review、succeeded、failed、manual_handoff六种状态。这样 Skill 之间的依赖关系才能在 Harness 中被正确追踪。常见错误是状态只有成功和失败两种，导致“需要人工确认”的中间态只能靠人肉记录，非常容易被漏。

4.3 Skill 全生命周期的版本、权限与审计

Skill 本身是代码，也需要做好版本管理。我见过一个团队，某个 Skill 改了 prompt 后没人通知，结果下游解析直接崩了。所以 Skill 的 manifest 必须带版本号，并且每次调整都要走 MR 评审。

权限方面遵循最小化。需求解析和架构方案 Skill 只给读权限，编码执行 Skill 给受限写权限，发布联动 Skill 只能调用 CI 接口。权限配置在 Harness 的 RBAC 层统一管理，不要在 Skill 内部零散设置，否则很容易漏。

审计日志记录三件关键信息：谁触发了什么 Skill、模型产出的核心关键字、是否有异常路径。这些日志不仅是问题排查的依据，也是后续优化 Skill 的数据来源。

4.4 高频问题速查表

如果只让我留一个建议，那就是：别急着把 8 个 Skill 一次全上。先投入产出比最高的三件套——需求解析、编码执行、代码审查——跑通一条最窄的链路。这条链路稳定运行一两周后，你会发现模型在真实项目里的行为模式已经比较可预测了，再逐步叠加测试、文档、发布和复盘。我见过太多团队一上来就想要“全家桶”，结果被编排复杂度劝退。AI Coding 的落地，本质不是模型更聪明，而是工程外壳足够结实。Harness 工程的价值，恰恰是让聪明变得可用、可控、可追溯。