sha256: 8d5df3c1ba6acf8ecbbb41c484604b3d4618d244d8d59dd2b9a52781fb16fe35 --- title: 应用宝活动平台 Harness 工程实践——从对话式 AI Coding 到工程化系统 source: wechat url: https://mp.weixin.qq.com/s/UE-RZH9hnbBd06CVapFGrA mp_name: 应用宝活动平台 publish_date: 2026-07-03 --- # 应用宝活动平台 Harness 工程实践 **来源**: 应用宝活动平台 **发布日期**: 2026-07-03 **原文链接**: https://mp.weixin.qq.com/s/UE-RZH9hnbBd06CVapFGrA --- 作者：zimingxing、kinglongli 、yifhao 应用宝活动平台系统支撑应用宝内包括 app、pc、手助等产品的所有日常/节假日活动，在今年上半年，我们针对整套系统进行了一次完整的重构。正值这个时间点，Harness Engineering 的概念被提出，我们团队也在重构的过程中，针对新的活动平台系统引入 Harness Engineering 的工程实践，初步搭建了一套 AI 端到端的开发流程。 这篇文章主要记录了团队在践行 Harness 工程化过程中遇到的一些问题以及实践经验，抛砖引玉，欢迎其他团队同学一起探讨。 ## 一、为什么要实践 Harness Engineering 在最初的开发阶段，我们主要采用对话式 AI coding 的方式进行开发，通过 CodeBuddy + Plan Mode、Rules + Prompt、AI 辅助编码、人工 Review 这样的协作方式让项目跑起来。 这种开发方式在实现一些一次性任务、或者小需求的时候会非常快，但随着项目复杂度的提升，逐渐暴露出了几个明显问题： ### 1.1 单窗口上下文快速膨胀 为了让 AI 能清晰的知道我们的业务背景、代码规范、项目结构等等，往往我们每次都需要在给 AI 的 prompt 中输入这些信息。 为了避免每次重复输入这些信息，我们会将团队的一些背景知识、代码规范、生成规则等沉淀为文档或 rules，在每次对话中塞到上下文带给 AI。 随着项目迭代，知识背景、规则会越来越多，每次启动上下文窗口，还没输入需求就已经塞了很大一部分内容。 另外，如果在单一窗口下让 AI 实现需求，往往多轮交互下来，上下文会快速膨胀，出现有损压缩导致遗忘、不按规则生成等等情况。 ### 1.2 缺乏完整的业务知识 每次需求开发都依赖人在 Prompt 中讲清楚需求背景、涉及业务的知识等等信息，而一个需求往往可能涉及多个业务、多个服务，这些服务之间如何合作、如何实现串联，都需要人来捋清楚后喂给 AI，一个完整的上下文构造非常耗费精力。 ### 1.3 缺乏工程上的自动化闭环 对话式 AI coding 的方式仅仅只能在 coding 环节由 AI 实现，但一个需求的完整交付，还包括了需求分析拆解、测试环境部署、接口验证、测试等等环节，这些环节依旧需要依赖人来执行和验证。 ### 1.4 单窗口无法并行 在一个窗口内对话，一次只能执行一个任务，当需求涉及多个独立的开发任务（例如开发三个独立接口），要么只能一个一个让 AI 开发，要么就只能同时开三个窗口，分别跟 AI 对话让其执行。 总的来说，当任务越是完整、越是规模化、越是可抽象成稳定流程，其仅仅采用对话式 AI coding 来完成的弊端就越明显，采用 Harness 工程实践的价值也就越高。 ## 二、整体架构：知识库工程 ✖️ 端到端开发工程 应用宝活动平台的 Harness 工程，主要包含了两部分工程能力：知识库工程和基于知识库之上构建的端到端开发工程。 知识库工程负责将散落在代码、文档、可观测系统中的工程知识，按照一定结构进行沉淀和更新，并提供给上层端到端开发工程消费。 整个端到端开发工程以"状态文件"为驱动，实现了将一个需求由 AI 按照需求拆解->需求澄清->任务拆解->并行开发->单测校验->代码审查->测试环境部署->用例请求构造->接口验证->提交代码全流程执行，人在其中只负责核心关键阶段的决策和信息补全。 当前，我们的整套体系包含 800+ 结构化文档，知识范围涵盖后台 90+ 个微服务，端到端流程沉淀了 12 个专家 Agent、30+ 业务相关 Skill 以及 10+ 个固定流程脚本。 ## 三、Knowledge Engineering——让 AI 真正懂业务 在复杂业务系统中，AI 最大的问题并不是"不会写代码"，而是缺乏真实、准确、持续更新的业务知识作为背景上下文。 知识库是整个 Harness 工程体系的基石——它决定了 AI 在需求拆解、技术方案、代码生成、接口验证等每一个环节中，能否拿到正确、充分的上下文。知识库建设的关键难点： 1. 冷启涉及的知识数据规模大 2. 大量知识背景下如何精确提取知识 3. 知识更新迭代速度快，已有知识容易过期 借鉴 LLM Wiki 和 Obsidian-Wiki 的方法论和实践，团队搭建了一套结构化的知识库，由两部分协同构成：自动生成部分（Skill 体系让 AI 自动读代码、自动生成结构化文档、自动维护新鲜度）和手工沉淀部分（人在 custom.md 和 common/ 中沉淀业务背景、架构决策、使用规范等）。 ### 3.1 整体目录结构 ``` llm-knowledge/ ├── backend/ │ ├── overview.md # 全局总览 │ ├── business/ │ │ ├── private_domain/ # 商城会员域 │ │ ├── activity/ # 活动平台域 │ │ ├── yybgame/ # 福利平台域 │ │ │ ├── meta.yaml # 服务索引 │ │ │ ├── custom/ # 域级手工文档 │ │ │ └── service_name/ │ │ │ ├── overview.md # 等8类自动生成 │ │ │ └── custom/ # 服务级手工文档 │ │ └── ... │ └── common/ # 公共知识库 │ ├── conventions/ # 开发规范 │ ├── lib_usage/ # 常用库指南 │ └── tech/ # 技术专题 └── .codebuddy/skills/ ``` 三层结构：总览层、域层（meta.yaml + custom/）、服务层（8类自动生成文档 + custom/） 8类自动生成的文档：overview.md、interfaces.md、architecture.md、dependencies.md、storage.md、config.md、pitfalls.md、log.md（历史保护，不可覆盖） ### 3.2 知识生成：从代码到结构化文档的自动化流水线 定义了两个 skill：gen-project-docs（单服务）和 batch-doc-generator（批量多服务）。 以服务入口文件为起点，import 追踪找到接口注册点，go.mod 定位 proto 包提取接口定义。增量融合保留人工补充的业务注释，只更新代码事实性信息。 以"接口调用量"判断接口是否活跃并在文档中标注。meta.yaml 作为注册中心记录文档状态和 git hash，skill 根据 git hash 变更判断是否需要重新生成。 支持仓库导入模式：直接从 Git URL 导入尚未纳入知识库的仓库，自动完成 clone、生成、分析归属、更新 meta.yaml。 ### 3.3 知识检索：渐进式加载 采用层次化加载 + grep 替代传统 RAG 检索： - 第一层：全局概述加载，通过关键词匹配缩小到 1-2 个业务域 - 第二层：grep 在 meta.yaml 里精确筛选 - 第三层：根据查询模式只加载必要的文档类型 四种查询模式：产品需求拆解（A）、技术方案拆解（B）、接口搜索（C）、知识库问答（D） ### 3.4 文档新鲜度检测 比较两个 git hash：meta.yaml 中记录的 git_hash（上次生成时的版本）和仓库当前 HEAD 的 hash。差异超阈值时标记过期，以增量模式更新生成文档。 增量模式特性：最小改动原则 + 人工批注保留。log.md 历史保护确保可审计性（每次生成追加一条记录，严禁覆盖）。 目前覆盖 4 个业务领域（活动、福利、商城、增长），90+ 微服务，800+ 份结构化文档。 ## 四、端到端开发工程建设——从"写代码"到"交需求" 核心设计思想： 1. 拆分上下文替代单窗口累计 2. 以状态文件替代容易被压缩的对话历史 3. 用确定性编排替代概率性发挥 4. DAG + 多 Agent 并行替代单线程串行执行 5. 打通从开发到提交的全流程 ### 4.1 状态文件驱动 两类结构化 JSON 文件： - product-state.json：用于产品需求拆解后的多 Story 并行开发流程 - e2e-state.json：用于单 Story 的端到端开发流程 状态文件落盘，实现流程可中断、可恢复、可观测。 Hook 机制（Stop、SessionStart、SessionEnd）确保流程不会被"偷懒式"提前停止，跨会话可自动恢复，结束后清理残留状态。 ### 4.2 专家 Agent 体系：每个专家只做一件事 设计原则：单一职责、上下文隔离、工具最小权限、确定性的输入输出、模型可插拔 12个专家 Agent： - 规划类：product-analyst、requirement-analyst、task-planner - 执行类：proto-engineer、backend-developer、code-fixer - 验证类：unit-tester、interface-verifier、test-case-designer - 审查类：code-reviewer - 集成类：publisher、git-committer 三个收益：行为更稳定、减少调度器负担和抖动、便于独立维护迭代 ### 4.3 DAG 编排 + Fork-Join **Worktree 隔离**：task-planner 按 DAG 编排任务，同一层并发执行，不同 worktree 隔离，统一 merge 收口。 **Fork-Join**：R 阶段需求拆解 → Fork 段多子需求并行开发 Phase 1-4（任务拆解→开发→单测→CR） → Join 段串行收口（合并→发布→验证→提交）。 **冲突治理四策略**： - Merge Conflict：事前文件级隔离，不绕过 - Shared file：收口阶段串行处理 - Proto 协议修改：前置串行，统一生成桩代码 - DB/配置变更：一次性前置确认 ### 4.4 脚本化执行 "AI 负责认知，脚本负责执行"——前后沉淀接近 15 个脚本（e2e-dev.py 状态机、worktree.sh 工作流、build-and-publish.sh 编译发布、kb-init.sh 知识库初始化等）。 ### 4.5 DevOps 集成 tRPC-Gateway（让本地 AI 调通内网接口）、Codar CR 流水线（AI 写的代码让 AI 来审）、TAPD/Rick/123/七彩石/伽利略等多平台读写集成。 ## 五、复盘、规划与思考 ### 5.1 核心工程原则 关键经验： 1. 调度架构演进：从 Agent 驱动转向强类型代码编排（弃用主子 Agent 模式，弃用 Shell 脚本，驱动层重构为 Go 代码） 2. 严格禁用项目级 Memory 以保障状态隔离 3. 引入 Mock 机制，分离调度逻辑与生成耗时 4. 应对异构服务拓扑，构建目录解析抽象层 七条核心原则： 1. AI 负责认知，脚本负责执行 2. 长链路必须状态化 3. 知识库必须结构化 4. Agent 必须职责隔离 5. 执行步骤必须脚本化 6. Workflow 比 Prompt 更重要 7. 把 AI 当作工程系统来设计 ### 5.2 下一步方向 从"能跑"到"跑得好"——自进化能力、评估体系、工具解耦。 ### 5.3 开放性思考 **TDD 在 AI 时代**：TDD 落地不在代码层面，而是集中在接口测试用例上，在一开始的需求方案设计环节便生成需求级测试用例。 **AI 工程的架构分层**：当前缺的不是好 Agent，而是好架构——Agent/Skill 的分层与插拔式组合是后续要重点优化的方向。 **代码还重要吗？**——"从代码为王到架构为王"：核心在线业务系统仍需要人守住架构这条线（AI 代码腐化速度快、高质量的代码和架构反哺 AI、人对代码失去掌控后线上出问题只能靠 AI 排查）；但结果导向、容错率高的系统（如运营看板）适合 vibe coding 黑盒化。