基于Harness工程的AI Coding流水线：8个Skill串联企业级交付全链路

先说个感受如果你只是拿DeepSeek的对话窗口写点脚本可能很难体会“企业级AI Coding”和“个人用AI写代码”之间的鸿沟有多大。我在公司牵头搞了一套基于Harness工程的AI Coding方案简单说就是把一条从需求到上线的完整链路交给AI去执行——但每个环节都套上一个叫Skill的标准化组件最终用8个Skill把链路串了起来。这套体系跑通之后我最大的感触是AI Coding能不能在企业里真正落地关键不在模型有多强而在于你能不能把过程变成一条可编排、可审计、可回滚的流水线。这篇文章就把我搭这套体系的完整思路过一遍8个Skill怎么设计、每个Skill内部怎么实现、Skill之间怎么通信、踩过哪些坑、怎么压测验证。内容偏工程实践适合正在做企业AI编程平台、或者在团队里推AI Coding效能改造的同学参考。1. Harness工程到底在解决什么问题1.1 企业级AI Coding的三个隐性成本个人用AI写代码关注的是“帮我写完这个函数”。但在企业环境里事情远没那么简单。我总结下来企业级AI Coding有三大隐性成本是个人场景完全不会遇到的。第一是输出不确定性。同样的prompt模型今天给A方案明天给B方案哪怕最终都能跑代码风格、依赖选择、异常处理方式都可能是漂移的。个人能容忍这种漂移企业不能——你没法让一个团队维护一个“每天都在变”的代码库。第二是上下文失控。一个成熟项目的代码仓库少说也有几十万行直接全塞给模型不现实context窗口有限而且相关性低的代码会严重稀释生成质量。第三是质量与合规无法沉淀。个人写完代码自己跑一下就算完事企业却要求每一个改动都有评审记录、安全扫描结果、测试覆盖率报告否则过不了审计。这三个成本叠加起来结论很明确企业需要的不是一个“更聪明的对话机器人”而是一条带护栏的流水线。这就是Harness工程要做的事。1.2 Skill、Agent与Harness的关系这里先把三个概念理清楚因为我在跟同事讨论时发现很多人把Skill和Agent混为一谈。用一句话概括Agent是决策者Skill是执行者Harness是承载两者的运行环境。Agent可以理解为一个“能自己决定下一步干什么”的智能体它有大目标会根据情况拆解任务、选择工具。而Skill是一个参数化、可复用的能力单元它不负责“思考大的”只负责把一件具体的事做扎实——比如“解析需求”“审查代码”“生成测试用例”。Harness则是这些能力单元的运行框架负责加载Skill、管理上下文、传递数据、控制流程、记录审计日志。把它们放到真实场景里Agent接到“帮我修复登录模块的验证码Bug”这个任务后会决定先调req-parser解析问题描述再调arch-designer分析改动方案然后调code-forger生成修复代码。而Harness在这个过程里负责把上一个Skill的输出规整成结构化数据喂给下一个Skill同时把每一次调用、每一次返回都记录下来。我见过不少团队连Skill和Agent都没分清就急着上AI Coding平台结果做出来的东西既不是灵活的Agent也不是稳定可复用的Skill两头不靠。想清楚这三者的边界是整个体系设计的第一步。1.3 为什么基于Harness框架做二次开发而不是自己造轮子聊到这里很多人会问这些东西我们自己写不就行了为什么要用Harness框架我一开始也这么想直到自己写了两个Skill之后发现一个完整的Harness框架需要解决的事情太多了上下文窗口的动态管理、模型调用的容错与重试、Skill的注册发现、输入输出的Schema校验、全流程的审计追踪、并发执行的资源控制……这些如果全从零开始至少要多花两三个月而且自己写的方案大概率没有社区踩过坑的框架稳。我当时对比了几条技术路线一是直接用DeepSeek Harness这类开源框架它的好处是天然适配DeepSeek模型插件体系比较成熟社区里有大量现成Skill可以直接改二是基于Codex Harness思路把Skill做成独立的CLI工具通过标准输入输出协议接入编排层这样语言无关、跨模型迁移更灵活三是自己从零写编排器自由度最高但成本也最高。最终我们选择了“DeepSeek Harness 自定义编排层”的混合方案底层的模型调用、上下文管理、插件加载用Harness框架的能力上层自己写了一个轻量Pipeline用来管理8个Skill之间的流转顺序、数据传递和人工审批节点。整体跑下来稳定性和灵活性都达到了预期。2. 8个Skill的全链路设计2.1 八个Skill一览从需求到上线的完整拆解在动手写代码之前我先做了一件事把一条软件交付链路从头到尾画出来看看哪些环节AI能介入、哪些环节必须人工兜底。经过几轮调整最终定下来8个Skill基本覆盖了从需求到运维的完整生命周期。这8个Skill分别是req-parser需求解析负责把自然语言需求转成结构化PRD、验收标准和任务清单。arch-designer架构设计负责基于PRD和仓库现状输出技术方案、改动点清单、依赖分析。code-forger代码生成负责按架构方案生成具体代码只输出diff格式的改动。code-reviewer代码评审负责对生成的代码做多维度评审输出问题清单和修复建议。test-master测试生成与执行负责生成单元测试和集成测试并真正执行、输出覆盖率报告。sec-scanner安全扫描负责扫描依赖漏洞、硬编码密钥、注入风险等安全问题。deploy-pilot部署编排负责生成部署清单、回滚方案与发布Checklist。doc-scribe文档沉淀负责生成变更日志、接口文档和架构决策记录回灌到知识库。这8个Skill串起来的完整链路是需求进入req-parser→arch-designer→code-forger→code-reviewer→test-master→sec-scanner→deploy-pilot→doc-scribe后面几个环节之间有反馈回路评审或测试不通过会打回给code-forger重新生成而不是一路往下走。2.2 为什么是8个多一个与少一个会怎样设计Skill划分时团队内部争论过好多次要不要把日志监控也做成一个Skill要不要把数据库变更单独拆出来后来我们定下了一条划分原则每个Skill必须产出一种独立的、可验收的交付物。也就是说一个Skill做出来结果必须是可检查、可评判的而不是“做了一部分还得靠下一个环节来兜底”。基于这个原则8个Skill其实是压到最精简的数量了。比如把code-reviewer和sec-scanner合并行不行理论上行但实际操作中代码评审关注的是逻辑正确性、代码风格、可维护性安全扫描关注的是漏洞、密钥、依赖风险两者判断标准完全不同合并会让单个Skill的职责过重提示词也会互相干扰最终输出质量反而下降。反过来如果把部署监控也做成Skill又会发现监控是持续运行的长任务跟一次性交付的Skill性质不同硬塞进流水线里只会拖慢节奏。所以最终就锁定了这8个后面所有开发、压测、迭代都围绕这8个展开。2.3 数据协议先行Skill之间靠Schema通信这8个Skill能否顺畅串联最关键的设计不是每个Skill本身有多强而是它们之间的数据协议。我们做了一个很关键的决策8个Skill之间不传递自然语言只传递结构化JSON。也就是说req-parser输出的不是一段“我理解的需求是……”的文字而是一个符合预定Schema的JSON对象里面有requirements[]、acceptance_criteria[]、task_list[]这些字段。下一个Skillarch-designer读到的不是散文而是可以直接处理的数据结构。这么做的好处非常明显。一是稳定自然语言传递容易出现信息损耗和歧义上一轮AI输出“需求较紧急”这种模糊描述下一轮AI根本没法判断紧急程度是P0还是P2结构化之后字段就是字段数值就是数值。二是可校验每个Skill收到输入后先做Schema校验字段缺失、类型不对直接报错不会带着脏数据跑完整条链路。三是可审计每一条数据从哪来、经过哪些转换都有迹可循。具体实现上我们用JSON Schema定义了每个Skill的输入输出结构放在一个独立的schemas/目录里统一管理。版本变更走Git评审流程谁改Schema都得说明原因防止接口悄悄变化导致下游Skill崩溃。3. 前半程Skill拆解需求、架构、编码3.1 req-parser把一句话变成可验收的任务包第一个Skill承担的是“把模糊变清晰”的脏活累活。团队里经常有人提的需求就是一句话“那个登录页有点问题你帮我优化一下。”这种描述直接丢给AI写代码结果大概率不是你想要的东西。req-parser的核心逻辑是拆三层背景层、约束层、验收层。背景层负责把需求放进业务上下文比如这个登录页是给内部运营用的还是给外部用户用的涉及哪些现有模块约束层负责收集硬性条件包括技术栈、兼容性要求、性能指标、合规要求验收层则是把“优化一下”变成可验证的条目比如“登录失败时错误提示必须在1秒内展示”“密码连续错误5次后锁定账号30分钟”。为了让模型不乱猜我们在req-parser里内置了一套需求模板并做了两轮交互式追问。第一轮问清业务背景和用户范围第二轮针对缺失的验收条件做定向补问。这个Skill的输出是固定Schema包含requirements数组每条需求带优先级、acceptance_criteria数组每条标准带验证方式和risks数组潜在风险。有了这个结构化任务包后面所有环节才有了源头依据。3.2 arch-designer先画图纸再动工把错误前置很多人觉得AI写代码不是一个命令就直接生成吗还要单独设计架构这个想法在企业项目里行不通。直接让AI生成一个大型模块的代码它不知道现有项目的分层结构、命名约定、公共组件生成出来的东西要么跟现有代码风格完全不搭要么重复造轮子。arch-designer做的事情就是让AI先画图纸再动工。它的输入是req-parser输出的结构化任务包加上一份预扫描的“仓库地图”repo-map。仓库地图不是全量代码而是项目的目录结构、关键模块职责、已有公共组件清单、核心服务之间的依赖关系。这份地图由一个后台服务在每次代码更新后自动生成存在向量数据库里arch-designer只取与任务相关的片段。arch-designer的输出包含四块技术方案怎么做、分几步、改动点清单具体到文件级别标注新增/修改/删除、依赖影响分析改了A会不会影响B、测试策略建议。这个设计最直接的效果是很多问题在真正写代码之前就暴露出来了。比如方案设计阶段发现需求涉及一个已经废弃的服务模型会直接打回给req-parser而不是硬着头皮生成一堆跑不起来的代码。3.3 code-forger带约束地生成diff不是自由发挥code-forger是整个链路里最“显眼”的Skill但也是最容易失控的一个。我们设计它时定了三条铁律。第一条铁律按改动点清单生成不允许自由发挥。arch-designer输出的改动点清单里明确写了要加哪个文件、改哪个函数code-forger只能在这个范围内工作。如果模型觉得需要额外的改动必须输出“补充建议”字段然后回到arch-designer重新评估而不是自己顺手就改了。这样做的原因是自由发挥一次两次可能没问题但长期来看会让diff变得不可控评审成本急剧上升。第二条铁律只输出diff不输出全量文件。diff格式是最容易评审的代码评审人看diff就能快速理解改了什么、为什么改。我们给code-forger设计了一个包含diff、commit_message、tests_added、note等字段的输出Schema生成结果直接以标准diff展现。第三条铁律上下文只给相关文件不喂全库。模型在生成代码时我们通过repo-map精确筛选出与改动点相关的文件片段连同该文件的函数签名、依赖导入、相关注释一起放进上下文。这样既节省token又避免无关代码干扰生成质量。实测下来上下文裁剪后生成的代码接口匹配率比“全量塞入”高了接近一倍。4. 后半程Skill拆解评审、测试、安全4.1 code-reviewer用规则库给AI写的代码挑刺代码到了code-reviewer这里核心目标只有一个找出问题。但AI写代码的“自信感”很强你要让它自己审自己它往往会觉得“我写的代码没问题”。所以我们没有只依赖大模型的能力而是给code-reviewer挂了一个分层规则库。规则库分三层。第一层是静态规则直接用Semgrep、ESLint这类工具检查语法错误、未使用变量、明显坏味道第二层是安全规则针对SQL注入、反序列化漏洞、硬编码凭据等高危模式做专项扫描第三层是业务规则这是团队自己沉淀的比如“所有外部接口入参必须做长度校验”“金额计算必须用十进制类型”等。code-reviewer的执行过程是先把diff拆成多个chunk对每个chunk并行跑三层规则库再把规则库的结果喂给模型让模型结合上下文生成“严重级-问题描述-修复建议-涉及文件行号”四要素齐全的评审意见。最后只保留严重级别为“必须修复”和“建议修复”的问题输出包含blocking_issues和non_blocking_suggestions两部分的JSON。这个流程设计上有个小心思规则库负责“确定性检查”模型负责“语义理解”两者互补。纯规则检查会漏掉很多需要语义理解的问题纯模型评审又不够稳定合在一起才能既快又准。4.2 test-master生成测试并真的跑起来很多团队的AI Coding方案里测试生成只是为了“看起来有覆盖率”。但我们做test-master时坚持一条原则生成的测试必须真实跑通跑不通就是Skill失败。test-master的输入是code-forger生成的diff和arch-designer生成的测试策略建议。它会先分析diff涉及哪些函数、哪些分支、哪些边界条件然后生成单元测试和集成测试。生成完之后不是完事而是自动执行并把测试结果、失败日志、覆盖率报告全部汇总输出。这里最核心的工程环节是测试数据自动构造。模型生成的测试用例经常因为依赖外部服务跑不通比如要连数据库、调存储服务、访问外部API。我们的做法是给test-master接了一个mock服务注册中心它可以根据被测代码的依赖声明自动生成对应的mock客户端并注入测试环境。这样测试用例可以快速、稳定地跑起来而不需要真实依赖环境。测试跑完之后test-master会做一个关键判断如果测试失败它不会简单地把错误报告往后传而是先把失败日志发回给code-forger让它尝试修复代码后重新生成diff再重新走评审和测试。这个“反馈回路”是整个链路能否真正自治的关键。我们设了最多循环3次超过3次还没通过就转人工。4.3 sec-scanner把安全卡在进CI之前安全扫描放在测试之后、部署之前目的很清楚不能在代码进入发布流程之后才发现安全问题。sec-scanner主要做四类检查。一是依赖漏洞扫描工程文件里的第三方依赖版本跟公共漏洞库比对发现有已知漏洞直接标红二是密钥泄露用正则和语义模型双重检查代码里有没有硬编码的API Key、密码、Token三是注入风险重点看SQL拼接、命令拼接、模板注入这几类高危模式四是权限配置扫描服务配置文件检查是否开放了过大的权限范围。这一环的难点在于误报控制。一开始sec-scanner报警报得特别勤很多其实是测试代码里的假数据或者内部工具类里的占位符。后来我们加了一个白名单机制经过人工确认为安全的模式可以加入白名单并附上审批人信息后续扫描自动跳过。白名单本身也要走审计流程不能随便加这样既降误报又不牺牲安全。sec-scanner是最后一个质量门禁节点。它的输出里有一个强制字段security_clearance只有为true时流水线才允许进入部署环节。这个字段同时会写进审计日志方便安全团队事后追溯。5. 收尾Skill拆解部署、文档5.1 deploy-pilot让交付也有标准动作代码通过所有质量门禁之后就轮到deploy-pilot。这个Skill不直接操作生产环境而是生成一份可执行的部署方案。deploy-pilot的输入包括code-forger的diff、测试报告、安全扫描结果以及当前生产环境的部署拓扑信息。它输出三类东西部署清单本次要发哪些服务、按什么顺序发、回滚方案每个服务出问题时的回滚步骤、发布Checklist包括检查项、验证步骤、责任人建议。这里最容易被忽略的是发布顺序。一个需求往往涉及多个服务的改动先发哪个后发哪个是有讲究的。比如订单服务和库存服务都改了正常情况下应该先发被依赖方再发依赖方否则可能出现接口不兼容。deploy-pilot通过分析服务依赖图来排顺序把这个容易出错的环节也标准化了。在deploy-pilot和真正的生产发布之间我们插了一个人工审批节点。AI可以生成完美的部署方案但它不能为线上事故负责所以这一步必须有人拍板。审批通过后部署方案会推送给现有的CI/CD平台执行执行结果再回传给流水线。5.2 doc-scribe把过程变成知识资产最后一个Skill是doc-scribe它的价值一开始被严重低估后来成了整个团队最离不开的一个。doc-scribe做的三件事变更日志、接口文档、架构决策记录。变更日志整理本次发布涉及的所有功能点、修复问题和已知限制接口文档根据实际代码变化生成或更新接口说明架构决策记录ADR则是在有技术选型或架构调整时把背景、方案、权衡过程记录下来。真正让它发挥价值的是后面的知识回灌环节。doc-scribe生成的文档不是扔到一个没人看的破wiki里而是经过清洗和向量化后写入项目知识库。后续再有新需求进入req-parser时它会先从知识库里检索相关的历史决策和历史实现作为参考上下文。这就形成了一个飞轮做得越多后面的任务完成质量就越高。我举一个实际例子。有一回团队讨论一个支付模块的改造arch-designer在生成方案时自动检索到了三个月前一次类似的改造记录里面明确写了当时的方案被否掉的原因——因为某个中间件的版本不支持事务回滚。这个信息直接让团队避开了同一个坑。如果没有doc-scribe的知识回灌这段历史大概率就被遗忘了。6. Skill开发与编排的工程实操6.1 一个Skill的最小实现长什么样讲了这么多设计落到底层还是要写代码。一个Skill在Harness框架里的最小实现包括三个部分配置文件、入口脚本、Schema定义。配置文件是一个YAML声明了Skill的名称、描述、版本、输入输出、使用的模型参数。我们项目的code-reviewer配置大概是这样的name: code-reviewer description: 对代码diff执行多维度评审输出问题清单 version: 1.2.0 input: schema: schemas/review_input.schema.json source: previous_step.output output: schema: schemas/review_output.schema.json prompt: template: templates/reviewer.prompt.md model: deepseek-v3.2 temperature: 0.2 max_tokens: 4000 tools: - git.diff - scanner.semgrep - llm.classifier retry: max_attempts: 3 backoff: exponential入口脚本则是一个标准的Python函数接收SkillContext返回SkillOutput。框架负责把上一个Skill的输出反序列化、做Schema校验然后注入到SkillContext里Skill执行完把结果包装成结构化输出框架再做一层校验并记录审计日志。整个流程对Skill开发者来说很简洁只需要关注核心逻辑不需要关心传输、校验、日志这些基础设施。公共提示词模板放在独立的templates/目录下和代码分开管理。这样业务人员可以只改提示词调优效果不需要动代码重新部署。6.2 编排器上的容错、重试与人工审批8个Skill本身写好了还要有一个“指挥中枢”把它们串起来。我们自研的编排器核心逻辑很短但控制点非常多。最基本的流程控制代码大概是这样的pipeline Pipeline(delivery) pipeline.add(req-parser) pipeline.add(arch-designer, requirereq-parser) pipeline.add(code-forger, requirearch-designer) pipeline.add(code-reviewer, requirecode-forger) pipeline.add(test-master, requirecode-reviewer) pipeline.add(sec-scanner, requiretest-master) pipeline.add(deploy-pilot, requiresec-scanner, gatehuman_approval) pipeline.add(doc-scribe, requiredeploy-pilot) pipeline.on_feedback(test-master, code-forger, max_loops3) pipeline.run(initial_inputdemand)这段代码体现了三个关键设计。第一是显式依赖每个Skill声明require哪个上游不能乱序执行。第二是反馈回路test-master可以打回给code-forger重做且限制最多3轮防止死循环。第三是人工审批门deploy-pilot后面挂了人工节点这个门是硬性的AI不能自己跨过去。容错和重试也是必不可少的。模型调用经常因为超时或者临时不可用而失败我们在框架层做了统一的指数退避重试最多尝试3次。如果3次都失败流水线会停在这个节点的failed状态并发送告警给值班工程师而不是静默跳过或者把错误数据往后传。6.3 全链路压测怎么验证这套体系真的可用体系搭完之后紧接着的问题是你怎么知道这套东西是真的能用而不是演示的时候一切正常、真上需求就崩我们做了一轮全链路压测方法很朴素从过去半年的真实需求里随机抽了30个涵盖新功能开发、Bug修复、性能优化、技术重构四类分别跑完整条流水线统计关键指标。压测的核心指标有四个需求理解通过率需求能否被req-parser正确解析成可执行任务、改动一次通过率测试和安全扫描一次通过不需要打回重试、人工干预次数整个流程中人工介入的次数、端到端平均耗时从需求进入流水线到产出部署方案的时间。实测数据出来后有几个发现。第一code-forger的新功能开发场景一次通过率明显低于Bug修复场景主要原因是新功能涉及多个文件的协调改动模型容易漏改。第二test-master生成的测试用例覆盖率整体不错但在边界条件处理上比较薄弱比如空指针、超大输入、并发场景。第三整个流水线端到端的平均耗时在15分钟左右其中测试执行占了大头这提醒我们测试并行化是后续优化重点。压测不只是看数据更重要的是暴露问题。30个需求跑下来我们发现了十几个流程缺陷比如某些情况下arch-designer会忽略仓库地图中已有组件的复用导致code-forger重复造轮子又比如sec-scanner对内部工具类误报率偏高。这些问题都在压测阶段被修复了没有等到真实业务上线才暴露。7. 企业落地踩坑实录与常见问题7.1 四个真实踩坑现场第一个坑是上下文膨胀导致输出质量断崖式下跌。早期code-forger为了保险起见把改动点涉及的服务全部代码片段都塞进上下文结果一个改动常常要喂两三万token。模型输出看起来信息量很大但真正可用的核心代码比例很低很多内容是在“围绕着无关代码兜圈子”。后来做了上下文裁剪只保留与目标函数直接相关的调用链和依赖签名质量问题立刻缓解。第二个坑是Skill之间的数据协议不兼容。有一次改动arch-designer的Schema把一个字段从related_files改名成files_to_change结果没有同步更新code-forger整个流水线跑了一天才被发现全是白跑。之后我们加了Schema版本校验下游Skill发现输入Schema版本不匹配时直接报错并提示让开发人员检查兼容性。第三个坑是模型选型一刀切。一开始所有Skill都用同一个模型结果req-parser这种偏结构化提取的任务大模型杀鸡用牛刀慢且贵code-forger这种强推理任务却因为模型能力不足频繁出错。后来拆开结构提取类Skill用中小模型推理生成类Skill用最强模型成本和效果都改善了不少。第四个坑是审计日志不够细。最初只记录了“某个Skill调用了几次、耗时多久”但合规团队要求知道“某段代码是谁让AI生成的、基于什么规则修改的、谁审批放行的”。我们后来在Harness框架里补了全量快照日志把每次调用的输入、输出、命中规则、审批记录都存储下来才算满足审计要求。7.2 常见问题速查表我把这几个月被团队问得最多的几个问题整理成一个速查表方便大家排查现象可能原因解决方案生成的代码跟现有风格不搭上下文里缺少项目规范说明在code-forger提示词里注入docs/coding_style.md测试用例跑得慢mock不完善测试连了真实依赖检查mock服务注册中心确保依赖被正确替换安全扫描误报多白名单机制没启用建立白名单审批流程人工确认后加入白名单某个Skill经常超时输入数据量过大或模型max_tokens不足增加上下文裁剪逻辑或者调大输出上限评审意见太泛泛规则库覆盖不足结合代码评审历史持续补充业务规则流水线打回循环过多需求或设计阶段信息不充分优先检查req-parser和arch-designer输出质量这几个问题都不是一次性修完就完了随着业务越用越深规则库、提示词、白名单都在持续迭代。这也是为什么我始终觉得Harness工程不是搭完就结束的项目而是一个需要长期运营的体系。这套8个Skill串起全链路的方案跑了几个月我最深的体会有两点。第一真正难的从来不是让模型写代码而是把“让模型写代码”这个过程变成企业可以信任、可以审计、可以回溯的流水线。第二Skill体系最大的价值不是单个Skill多聪明而是它能把团队积累的最佳实践固化成标准动作让每一次交付都用上全团队沉淀下来的经验。如果一个Skill跑了三个月没有更新过提示词那大概率说明这个环节还没被真正用起来。