WeTV以领域契约和分层验证管理多端Harness

WeTV团队面对 Linux TV、V 站、M 站、Roku TV 的多平台产品矩阵，此前已沉淀 @tencent/wetv-kernel 核心逻辑包、上报/账号/播放器 SDK 与规范检测集、目录范式、单测范式，但在引入 AI 后发现单靠 memory 会「上下文腐化」——AI 生成代码经常忘记特殊规则、丢掉 Page/Module/API 开发范式、有现成 SDK 仍重写冗余逻辑，于是把规范从「人读的文档」转为「机器可读的契约」。 契约部分用四个 JSON 文件自上而下描述业务：pages.json 页面层由 ui-modules.json 组成、后者依赖 data-layer.json、数据取自 api-layer.json，配合统一业务语言的 glossary.json（如统一 vid 的命名、定义与 mzc00200xxx/n00xxxx 格式）。 Homepage 等通用概念通过 _DETECTION_HINTS 的关键词、常见路由与文件匹配模式，在 /project-init 时由 AI 扫描项目自动生成 domain-mapping.json（Web 端为 pages/index.tsx、Linux TV 端为 src/pages/Home.tsx 等），避免以往硬编码路径在项目重构后失效。 各端 props 差异用 _PLATFORM_PROP_VARIATIONS 表达（TV 端的 focusKey/onFocus/onBlur/onEnterPress 与 Web 端的 onMouseEnter/onMouseLeave），AI 生成代码时先读通用契约、再读平台映射、最后结合项目依赖库产出对应技术栈代码。 工作流以 Command 为入口、Skill 为专项工具、Agent 为带角色执行者：/project-init 五步完成环境准备、MCP 配置（可接 TAPD、企微）、项目类型探测、Page/API/UI Module 三层映射逐层人工确认、在 .codebuddy/ 下生成 domain-mapping.json、rules 与 patterns 等文件。 需求阶段经 TAPD MCP 拉需求并在 description 为空时回溯父需求、从 description 提取 Figma/蓝湖/Axure 链接、两级任务拆分与工时预估、调用 D2C 精简模式生成设计约束与 Token 映射、由 AI 自任红队从数据/交互/环境三个边界找遗漏场景并给出 P0/P1/P2 处理选项、再由三个维度推导验收用例。 开发阶段由 code-analyzer 做情报收集（领域模型分析、codebase_search 复用资产、惯用法识别、技术风险识别）、code-planner 产出 impl-plan 并作为第一道卡点等待人工审批、code-developer 严格按方案落盘并跑 web-local-quality-gate 质量门禁、code-reviewer 从 Plan 忠诚度、Idioms 合规、React/TS 反模式、CSR/SSR 兼容性四个维度审查并给出 PASS/PASS_WITH_NITS/NEEDS_REWORK 结论。 质量控制由本地门禁加 L0-L4 五个脚本组成：L0 validate-domain-model.sh 校验领域模型完整性、L1 validate-project-structure.sh 校验目录与模型对齐、L2 validate-api-contract.sh 校验 API 契约、L3 validate-cross-platform.sh 校验多端对等性、L4 generate-test-spec.js 跑 E2E，五层各占 20% 权重、评分 ≥70 才算通过，不通过打回重做。 通过后记录首次通过率、返工次数、任务完成数、红队发现问题数与变异测试安全评分生成效率报表。工程治理上自研 CLI 工具 @tencent/wpc-cli，用 wpc harness init 把源仓库 codebuddy-harness 的 commands/skills/agents/rules/scripts 同步到目标项目 .codebuddy/，用 wpc harness update 升级并检测孤儿文件（源仓库已删除而目标项目残留的旧命令会让 AI 调错），弃用 Git Submodule 的原因是要求独立子仓库、版本锁定在父 commit 且 CI/CD 中常缺 SSH key。 源仓库为唯一真相源，目标项目仅有 config/ 与 workflows/ 允许 AI 修改，AI 被要求修改通用流程前先确认路径以 codebuddy-harness/ 开头。团队还复盘了一个真实死锁坑：早期把「需求管理」也作为子 agent 启动，导致其确认框弹在子 agent 面板而主面板一直等待，修了两轮后定下「所有用户交互必须在主面板、子 agent 只执行不交互」的铁律。