契约化多端架构：基于领域模型的Harness实践（上）

契约化多端架构：基于领域模型的Harness实践（上）

本文为《契约化多端架构：基于领域模型的Harness实践》系列第 1 篇（共 3 篇），分为（上）（中）（下）三篇，建议连续阅读。

作为一名老登前端开发，这两年深刻感受到大模型时代 AI 对软件工程带来的冲击——也被近年来 AI 各种范式大潮冲击了一遍又一遍。一路从提示词工程，再到上下文工程、Vibe Coding，再到本篇要介绍的 Harness 工程化，一路在思考：什么样的 AI 工程化方案，才是符合 WeTV（腾讯视频海外平台）当下 Web 项目的？这里抛砖引玉，和大家一起来探讨。 【为了将每个细节讲到味，篇幅较长，文章有问题的地方欢迎指出，大佬们不吝点赞+收藏！】

01 我们是怎么开始"吃 AI"的

说实话，2025 年初那会儿，AI 热潮铺天盖地——朋友圈、技术社区、各种大会，全是"不用 AI 就被淘汰"的论调。作为老登，说实话有点焦虑。

正好那段时间，我们接连有两个从 0 到 1 的项目：Linux TV 改版、Roku TV 立项。按以往经验，这种新项目意味着大量重复劳动——搭建项目框架、写基础组件、对接 API、写测试用例… 总得有个起点吧？

当时就想：要不拿 AI 试试？

1.1 AI 辅助编程的那点历史

回过头看，这事儿其实折腾了很久。图灵 1950 年的那篇论文，其实不是在讨论"AI 写代码"，而是提了个判据：如果机器能通过对话骗过人类，就算有智能——这个设想埋下了后来"用自然语言编程"的种子。70 年代有人研究自动编程（Automatic Programming），试图从形式化规约推导程序，当然没成。80 年代专家系统火过一阵，用 IF-THEN 规则做代码审查，但规则维护成本太高，最后也没落地。

2000 年代统计机器学习入场，但还是没改变开发者的日常。真正的转折是 2017 年的 Transformer（就是那篇 Attention is All You Need），然后 2021 年 Copilot 上线，AI 辅助编程才算真正进入主流。

但"进入主流"和"真正好用"之间，还有很大的距离——这就是为什么我们从提示词工程，一路走到 Harness 工程化。

1.2 没有 AI 之前：我们其实已经做了很多"工程化"

面对 Web 侧这种多平台产品矩阵——Linux TV、V 站、M 站、Roku TV——我们为了提升研效，早就开始"工程化"了：

• @tencent/wetv-kernel：核心逻辑包，平台无关

• 上报/账号/播放器 SDK：基础能力收敛

• 规范检测集、目录范式、单测范式：多年踩坑沉淀

没有 AI 之前，我们靠"人肉传承"——有了 AI 之后，第一反应是：怎么让 AI 也"懂这些范式"？

1.2.1 上下文腐化：memory 不是万能的

刚开始用 AI，每次写提示词都想：能不能把这些范式和复用场景直接给到 AI？

但很快发现——上下文工程虽然有 memory，但体量一大就会"腐化"：

这时候我们才意识到：memory 不是万能的。

1.2.2 从"人肉传承"到"契约化规范"

意识到 memory 不行之后，我们开始想：既然 AI 的上下文会腐化，那就把规范"外置"——不让 AI 靠记忆，而是靠"查契约"。

具体来说，就是把我们之前沉淀的那些东西——规范检测集、目录范式、单测范式、开发范式模型——从"人读的文档"变成"机器可读的契约"。

这一步，其实就是从上下文工程走向Harness 工程化的关键转折点。

02 我们需要什么样的Harness

2.1 用"契约"代替"猜"

以前让 AI 写代码，它得先把项目扒一遍，然后靠"猜"来理解你的意图。项目一大，该读的没读到，不该读的干扰一堆——这就是"上下文腐化"。

Harness 的做法是提前定义好领域模型——用 JSON 把业务概念写清楚：页面有哪些、组件有哪些、接口有哪些、数据结构是什么。AI 直接读这个就行，不用去扒源码。

关键是这份领域模型跟平台没关系，各端共用同一份。

运行 /project:init 的时候，AI 会根据 _DETECTION_HINTS 自动扫描当前项目，生成 domain-mapping.json 映射文件，把"通用契约"映射到"各端具体实现"：

{

通用契约定义"是什么"，映射文件定义"在哪、怎么实现"。

2.2 多端差异用映射解决

业务逻辑是通的，但各端实现方式不一样——TV 用焦点驱动，Web 用鼠标，移动端用触摸。

Harness 用 _PLATFORM_SPECIFIC 标注各端差异。AI 生成代码时先读通用契约，再读映射文件，最后结合项目依赖库生成符合该端技术栈的代码。

2.3 把整个流程串起来

完整工作流：

/project:init → 需求分析 → 红队验证 → 验收标准 → 方案设计 → 需求开发 → 测试验证 → 观测回收

• 初始化：AI 探测项目结构，生成映射文件和配置

• 需求分析：AI 读需求，拆成任务清单让你确认——避免理解偏差

• 红队验证：AI 自己当"对手"，找漏洞——没网络怎么办？数据为空怎么展示？

• 验收标准：生成 TDD 契约文件，开发完了对着验收

• 需求开发：AI 创建 Team 分工——reader 读代码、planner 做方案、executor 写代码、reviewer 做 Review

• L0-L4 验证：五层质量门禁，自动拦截不合格代码

• 观测回收：记录 Token 消耗、首次通过率、返工次数

2.4 用建房子理论类比图

03 我们的 harness 如何编排设计

早期我们让 AI 一口气干完"读需求 → 拆任务 → 写代码 → 跑测试"，结果是上下文一多就乱，改一处漏一片。

后来想通了：把开发流程拆成角色，每个人干自己的活，上下文隔离，互不干扰。

Command、Skill、Agent 到底啥区别？

刚接触的人容易搞混，其实很简单：

• Command 是"你跑的那个命令"。比如 /web-agent-new，它就是个入口，负责解析参数、拉 TAPD、串步骤。它不干活，它是"调度员"，类似我们以前开发脚手架 Cli的命令入口。

• Skill 是"专项工具"。比如 requirement-breakdown 专门拆需求，d2c 专门把 Figma 转代码。它被 command 调用，只做一件事，做完就返回。好处是复用方便，换个项目不用改。

• Agent 是"带角色的执行者"。比如 code-analyzer 是代码阅读者，code-planner 是方案设计者。它有角色设定，会在独立上下文里自主决策。

一句话区分：Command 是"入口"，Skill 是"工具"，Agent 是"角色"。

跟业界比，我们做了哪些优化？

工具

怎么干活的

多角色？

懂业务？

Copilot / Cursor

一个模型聊到底

✗

✗

Devin

一个 agent 自己干

✗

✗

OpenHands

多 agent 协作

✓（得自己配）

✗

我们的Harness

Command + Skill + Agent Team

✓（流程里固化了）

✓（领域模型注入）

最大的区别：Copilot / Cursor 你得把需求说清楚，它自己去扒代码猜意图。Harness 提前把业务概念结构化（领域模型），AI 直接读，不用猜。

一个真实踩的坑

最早设计的时候，我们让主面板把"需求管理"也当子 agent 启动——结果卡死了。

原因是：子 agent 弹的确认框出现在"子 agent 面板"，主面板看不到，就一直等，死锁。

后来定了一条铁律：所有用户交互必须在主面板，子 agent 只执行不交互。

这个坑修了两轮才彻底闭合。现在的流程里，每个检查点都是主面板直接弹 ask_followup_question，子 agent 返回结果后主面板再决定下一步。

有了上面的 harness顶层设定，接下来我将核心内容拆开讲，把这套东西的设计细节摊开说。主要分三块：

• 先是领域模型。 这是整套 Harness 的核心——把业务概念结构化，让 AI 能读懂。四个模型文件（pages、ui-modules、api-layer、data-layer）分别管什么、怎么配合，_DETECTION_HINTS 和 _PLATFORM_SPECIFIC 这两个关键设计是怎么工作的，都会说清楚。

• 然后是完整工作流。 从你跑 /project:init  command命令开始，到需求分析、需求开发、L0-L4 验证，再到最后的观测回收，每一步具体做什么、产出什么、怎么保证质量，都会拆开讲。

• 最后是管理机制。 这套东西做好了，得让团队真正用起来。各端项目怎么接入、怎么升级、文件怎么管理、版本怎么迭代，这些是落地时要解决的。

04 领域模型设计

前面说了，领域模型是一份"业务说明书"——用 JSON 写清楚业务里有哪些页面、哪些组件、哪些接口、哪些数据。AI 读这份说明书就能理解业务，不用去扒源码。

4.1 四层架构

四层从上到下是依赖关系：

页面层（pages.json）

实际跑起来是这样：用户访问首页 → AI 识别 HomePage（pages.json）→ 分解出需要 HeaderModule + PosterListModule（ui-modules.json）→ 识别数据依赖 ChannelListData（data-layer.json）→ 生成调用 ChannelListAPI（api-layer.json）的代码 → 输出各端实现。

4.2 _DETECTION_HINTS：让 AI 自己找文件

领域模型是通用业务概念，但各端具体实现文件路径不一样。首页在 Web 端是 pages/index.tsx，Linux TV 端是 pages/home.tsx，Roku 端是 components/HomeScene.brs。

以前的做法是在领域模型里硬编码各端路径，但项目重构后路径变了，模型就错了。

现在的做法是用 _DETECTION_HINTS 给 AI 提供探测提示，让 AI 在 /project-init 时自动扫描项目，生成 domain-mapping.json 映射文件。

看实际例子：

{

跑 /project-init 时 AI 会扫描项目目录，生成：

{

4.3 _PLATFORM_SPECIFIC：处理各端差异

文件在哪解决了，还有个问题：各端的 props 不一样。

PosterCard 组件，通用定义里只说"这是一个可点击的海报卡片"，但 TV 端需要 focusKey、onFocus（焦点驱动），Web 端需要 onMouseEnter（鼠标悬停）。

做法是在通用定义里用 _PLATFORM_PROP_VARIATIONS 标注各端差异：

{

AI 生成代码时，先读通用契约，再读 domain-mapping.json 里的平台映射，最后结合项目依赖库生成符合该端技术栈的代码。

4.4 glossary.json：统一业务语言

业务里有很多专有名词，不同人叫法不一样。比如"视频 ID"，有人叫 vid，有人叫 videoId，有人叫 contentId。AI 读代码的时候就会混乱。

用 glossary.json 统一业务语言：

{

AI 读领域模型之前先读 glossary.json，建立统一的业务语言理解。