契约化多端架构：基于领域模型的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，但体量一大就会"腐化"：
规范冲突：AI 生成的代码，经常忘记我们的特殊规则
开发范式丢失：聊着聊着，AI 就忘了"Page / Module / API"这些开发范式
复用场景不识别：明明有现成 SDK，AI 还是给你重新写冗余逻辑
这时候我们才意识到：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，建立统一的业务语言理解。
