先聊聊背景。人工智能技术的发展速度确实令人惊叹。从前，AI只能协助补全下一行代码，而如今，从需求创建到性能优化，几乎每个开发环节都能看到AI的身影。但随之而来的问题是：这些零散的AI能力就像一盘散沙，需要开发者自行挑选组合。有人仍停留在传统编码模式，有人则尝试多种不同的AI工具——从需求到提测的整个链路，缺乏一个统一的工具来串联，更谈不上标准化的流程来驱动团队高效运用AI。

这引出了两个非常现实的问题：

• 对于简单的任务，能否让AI独立完成全流程？
• 对于复杂任务，能否设计一套标准化流程，让开发者在关键节点借助AI加速交付？

基于这一思路，我们在传统prompt工程的基础上向前迈进了一步，构建了一套更加系统化的“Harness Engineering”。其核心产出是一系列覆盖整个研发生命周期的智能开发工作流，让AI真正有能力执行长周期任务。

工作流总览

[图片]

整体架构

[图片]

详细设计

智能知识库

为什么需要项目知识库？

你可能会有疑问：AI不是能理解代码吗？为什么还需要专门构建知识库？答案很简单：AI能够理解代码，但恰恰缺少那种“全局感”。

1. 缺乏项目全貌：AI每次对话都是“全新”的，不清楚项目采用的技术栈、目录结构、代码风格。
2. 无法复用经验：之前的分析结果无法持久化，每次都要从头分析，效率低下且容易产生不一致。
3. 上下文受限：项目文件众多，AI无法一次性读取所有内容来建立完整认知。
4. 规范不一致：AI生成的代码很可能与项目现有风格不匹配，需要人工修正。

.workflow 知识库正是为解决这些问题而生。它是一套结构化的项目元信息文档，让AI能够：

• 快速了解项目的技术栈和架构
• 严格遵循现有的编码规范和命名约定
• 复用已有的组件和工具函数
• 按照项目惯例调用API

.workflow 知识库架构

目录结构

[图片]

知识库与开发流程的协作

.workflow 知识库是整个AI辅助开发流程的基础设施，并非孤立存在，而是与其他命令形成一条完整的协作链路。

[图片]

协作流程详解

[图片]

具体协作方式

1. prd-preprocess 如何使用知识库

[图片]

2. dev-workflow-plan 如何使用知识库

[图片]

3. archive 如何使用知识库

[图片]

命令介绍

1. workflow-init：知识库初始化

作用： 深度分析项目，一次性生成完整的 .workflow/ 知识库。

使用方式：

# 基本用法
mcp__bgent__bili-fe-workflow-init
# 强制覆盖已有知识库
mcp__bgent__bili-fe-workflow-init forceOverwrite=true

执行流程： [图片]

支持的项目类型：

• 单项目：标准的单页应用
• 多项目：Monorepo、Vue 多页应用

2. knowledge-update：知识库更新

作用： 项目代码变更后，增量更新指定知识库文件，无需每次全量重建。

使用方式：

# 更新 API 文档
mcp__bgent__bfw-knowledge-update knowledgeFile=".workflow/knowledge/api.md"
# 更新组件文档
mcp__bgent__bfw-knowledge-update knowledgeFile=".workflow/knowledge/components.md"
# 更新全部知识库
mcp__bgent__bfw-knowledge-update knowledgeFile=".workflow/knowledge/index.md"

执行流程： [图片]

更新策略：

• 内置知识库：使用特定分析指令，保证分析质量一致。
• 自定义知识库：走通用更新流程，根据文档内容确定分析范围。

差异对比示例：

## 差异对比报告
### 新增内容 (New)
- [API] 新增接口: `GET /api/v2/user/profile`
- [组件] 新增业务组件: `UserA vatarUploader.vue`
### 修改内容 (Modified)
- [API] 修改响应结构: `getUserList` 返回数据路径从 `response.data` 改为 `response.result`
### 删除内容 (Removed)
- [API] 废弃接口: `GET /api/v1/user/old-list`
### 保持不变 (Unchanged)
- [API] 基础架构: Service Layer 模式保持不变

需求文档澄清

为什么需要预处理？

仅仅一份PRD，距离真正开始开发还有相当距离。原因很现实：

1. PRD是产品视角的需求描述，无法直接映射到代码模块。
2. PRD需要经过需求评审来澄清和补充，口头讨论的内容常常不会落入文档。
3. 若需求涉及多个项目（前端PC、H5、后端），需先提取当前项目需要修改的部分。
4. 前端开发还需要交互稿和视觉稿。
5. 前端开发需要后端的技术方案。
6. 还有诸多其他问题。

因此，仅凭一份PRD远远不够，还需进行二次处理。人工整理虽然可行，但耗时较长。相比之下，AI具备独特优势：

1. AI分析文档和代码的速度远超人类。
2. 粗略统计，AI撰写的文档长度是人写的7倍以上，更适合用作prompt。
3. AI能发现一些人类容易忽视的模块。

我们模仿自身开发需求的流程：产品输出TAPD → 需求评审对齐 → 技术方案对齐 → 编写代码。其中需求评审是关键环节，通过评审明确不确定点、拉齐产品与技术理解。但问题在于，评审讨论的内容常常停留在口头上，未落实成文档。为了让AI也能获取这些信息，我们设计了 prd-preprocess 命令。

命令介绍

命令的大致流程是：

[图片]

收集需求文档、设计稿、接口文档 → 匹配涉及的代码模块 → 对比代码现状与需求 → 澄清 → 落地文档。这实质上是对“产品出TAPD → 需求评审对齐”这一步骤的AI化模仿——通过拆解更细的步骤，让AI模拟真实开发流程。

核心作用

/prd-preprocess 是一个需求文档预处理工具，帮助开发者将原始的产品需求文档（PRD、设计稿、技术方案）转换为结构化、可执行的开发PRD文档。

1. 减少需求理解偏差
2. 自动分析涉及的代码模块
3. 提前发现需求中的问题和歧义
4. 生成标准化的开发文档

使用示例

# 基本用法
/prd-preprocess
# 指定需求目录
/prd-preprocess prd/20251217-new-feature/
# 通过 @ 选择文件（自动识别父目录）
/prd-preprocess @prd/20251217-new-feature/original-prd.md

执行后生成的文件结构：[图片]

prd-preprocess 命令使用介绍

前置条件： 先安装 mcp tool @bilibili-business/mcp-server-sdk，或安装 Claude Code 插件 Fugue。

在 Claude Code 中输入 /prd-preprocess 会出现命令选项，下图中有三个：

1. 当前项目下自己创建的命令：.claude/commands/prd-preprocess.md
2. 发布在 Claude Code 插件 Fugue 上的 command
3. 发布在 mcp 工具的 prompt

目前三个效果相近，我们也在对比 mcp 和 plugin 哪个更优。当前推荐使用 mcp 版本。如果你看到的前缀与我的 mcp-router:workflow 不同，不必担心，因为我本地使用了 mcp-router 托管。

[图片]

阶段一：prd、技术方案、设计稿的资源获取

[图片]

不带参数直接执行，工作流未收到需求文档时，会询问需求存放在哪个目录。该目录将被用作工作流执行时存放prd、技术方案和最终输出文档的位置。默认在项目 /prd/20251217-xxx/ 目录下进行。

[图片]

工作流会询问是否有设计稿链接、技术方案文档：

[图片]

将准备好的技术方案粘贴过去（此处没有figma设计稿），工作流便进入下一步。

[图片]

阶段二：分析需求和代码

[图片]

提取需求

工作流首先提取需求中与前端相关的功能点并进行整理。提取时按照四个方向进行：

1. 界面改动：新增页面、修改现有页面、删除页面
2. 功能改动：新增功能、修改功能、删除功能
3. 交互改动：用户操作流程、状态变化、动画效果
4. 数据改动：新增接口、修改接口参数、数据格式变化

这四个方向正是我们自己在开发时，从前端角度考虑的关键要点。这符合工作流的两条原则：模仿和拆解。

[图片]

分析涉及代码

分析从两个方向入手：

1. 使用 mcp tool rag-knowledge-search 查询知识库。如果之前有相同模块的需求改动，并通过工作流生成过相关的 prdtecharchive 文档，则rag search能快速定位到涉及的模块。工作流与知识库可以相互补充完善。
2. 借助 Explore、Glob、Grep 等工具直接筛查代码。

最终生成模块时，也会拆分成不同方向，基本涵盖了一个前端需求所需的所有代码：

1. 主页面
2. 相关组件
3. 路由配置
4. API 接口
5. 工具和类型定义

[图片]

阶段三：需求澄清

[图片]

这一步，工作流会对比PRD与项目代码现状，分别从三个角度进行需求澄清：完整性、一致性、明确性。这一步非常关键。我们可以将需求评审时口头讨论的内容明确告知AI，从而消除模糊性，减少AI的幻觉。反之，AI也能发现一些之前评审时未讨论到的问题，通过澄清来补全。

说实话，站在前端角度，很多交互细节产品不会在PRD中写明。往往是开发者辛苦完成，产品验收发现不符，又需返工。通过AI澄清明确性，能更早地将问题暴露出来。比如下面列举的，基本都是PRD未明确的细节：

• 选择“自定义”后输入X天，X的取值范围是多少？有无最小值/最大值限制？
• 当用户从“等于”切换到“匹配”或“为空”时，已选择的枚举值如何处理？保留还是清空？

[图片]

阶段四：需求拆解

[图片]

整理澄清内容，生成 clarification.md 文档，然后拆分子需求。正如我们自身开发时，不会一次性完成整个需求，而是分块逐步实现。对AI而言同理，受限于上下文，它也无法一口气完成整个需求。将大需求拆分为若干小需求，有助于AI更准确地生成。这依然是模仿+拆解的思路。

[图片]

当然，我们可以手动调整拆解范围。例如，你认为“维度条件配置”和“指标条件配置”可以合并实现，便可手动合并。

[图片]

最终生成多份PRD文档，并整理各模块的依赖关系，给出后续开发建议。

智能开发工作流

上一步将原始PRD拆分为多个子需求PRD，接下来进入开发阶段。

常规开发流程是：PRD → 技术方案选型 → 技术方案设计 → 编写代码。但很多时候，作为项目负责人，我们对项目细节非常熟悉，往往不将“技术方案选型 → 技术方案设计”落实为文档，而是头脑风暴后直接开始编码。按照模仿+拆解的思路，我们将这一流程拆解为AI可执行的步骤，编排成智能开发工作流。

智能开发工作流主要是一个顶层调度器，负责分析需求文档中的Figma解析策略，然后分三条路径执行，如下图所示：

[图片]

两大Skill的定位非常清晰，并通过 d2c-logic-hints-generator 衔接：

• D2C = 视觉驱动，设计稿 → UI代码 → 逻辑补全提示
• Dev = 逻辑驱动，需求 → 完整可运行代码

整体调用的Skill列表如下：

[图片]

D2C

核心理念

“设计驱动代码”——从Figma设计稿自动生成高还原度的UI代码，将视觉还原工作自动化。

传统工作流分析

[图片]

技能组成（6个Skill）

对传统工作流进行拆解，实现设计稿分析和UI还原。

[图片]

七步流水线

[图片]

本阶段的产出包括：可运行的UI代码和一份 logic-hints.md。UI已还原，但按钮点击事件为空、接口调用为mock、表单校验尚未实现——这些都被精确标记在 logic-hints.md 中。

关键设计点

1. 并行MCP调用： 所有Figma API调用在单条消息中并行发起，大幅缩短耗时。
2. 单Task批处理： 组件识别和图标匹配各用一个Task（子袋）完成全部项目，避免逐个启动子袋的开销。
3. 预计算样式映射： figma-design-analyzer 在提取阶段生成 tw-to-css.json，code-generator 直接查表，省去重复解析Tailwind。
4. 渐进式数据持久化。
5. 子袋上下文隔离： D2C在独立子袋中运行，完成后上下文自动释放，不污染主袋的上下文窗口。

Dev

核心理念

“需求驱动，动态编排”——分析PRD复杂度和特征，自动规划最优的Skill执行序列。

技能组成（7个Skill）

[图片]

动态规划

Dev的核心设计是Step 0的动态计划生成：分析需求特征和其他输入 → 选择Skill → 用户确认。具体SKill动态选择规则如下：

[图片]

技术要点提取→学习→方案 的三级流水线

这是Dev最核心的设计——三个Skill形成递进式知识构建：

[图片]

设计精髓：

• 需求驱动过滤： 只提取与当前需求相关的技术点，不过度学习。
• 三级优先级（??⚪） 从提取阶段贯穿到学习阶段，控制学习深度。
• 覆盖度校验： tech-architect 验证方案中所有使用的技术是否都已被学习，发现缺口就补学。

3大执行策略

在full模式的执行策略下，两大子系统的协作关系如下：

[图片]

D2C Phase 1 生成的 logic-hints.md 内容如下：

logic-hints.md 内容:
├── 已生成文件列表
├── 已完成项（UI骨架/组件配置/样式）
├── 待补全清单（API调用/事件处理/数据源/路由）
├── 已使用组件列表
└── 补全建议

Dev根据 logic-hints.md 进入逻辑补全模式，各个Skill的行为调整如下：

[图片]

layout-only / none 策略下，直接进入Dev标准模式，动态规划Skill执行序列。

自动化测试

使用流程概览

[图片]

实现方案

完整工作流设计

Step1：调用测试工作流

调用测试工作流有多种方式（输入/找到 /bili-fe-test-workflow），自然语言输入，可按需调整。根据用户输入生成规范且详细的测试计划，包括frontmatter基本信息、执行要求、每个测试用例的基本信息（ones caseid如果有的话）、初始URL、前置条件（包含3A造数信息）、测试步骤（越详细越好，小学生也能按步骤点点点）、预期结果等。常见用法举例：

• 商业部门需求，直接贴ones链接或onesid，如：[图片]
• 或者直接说：“onesid:16751”
• 可额外添加 @xxx-prd.md、tech.md 等文件
• 随意加自定义要求，简单需求也可以直接复制tapd/企微内容贴给工作流
• 第一次生成后，可以按需调整修改，人工Review一遍，避免AI开始测试时跑偏或找不到内容，省得浪费大量时间和Token

Step2：运行测试计划

觉得测试计划修改得足够详细和完善后，就可以让AI开始正式测试了：

[图片]

Step3：生成测试报告

AI测完后，可以让它生成详细的测试报告，方便校验和追溯。

Step4：生成Playwright测试脚本

基于之前的测试上下文，生成playwright测试脚本。项目的playwright初始化，可以用我们的MCP里的 /bili-fe-test-workflow-setup 来快速搞定。

Step5：测试脚本修复

生成脚本后，先在本地跑一下，AI调试或人工调试，跑通后就能提交git了。

Step6：UI自动化平台重复跑测试

代码提交后，在UI自动化平台上跑跑看能不能通过。后续的需求、回归用例就可以定时重复跑了。

Step7：CI流水线配置

UI自动化平台接入成功后，就可以配置CI流水线。这样在release前发MR时，就能自动进行回归测试，提升上线稳定性。

[图片]

完整AI交互流程

[图片]

可选工作流程

以上是走完一个完整测试工作流的过程。实际中也可以根据情况跳过某些步骤。不同情况的适用场景（AI生成测试计划后，下一步之前会提示用哪种模式）：

• 完整流程（传统）：适合用例在15个以内的场景，基本能在可接受时间内执行完。
• 渐进式：AI测完一个用例，立即生成测试脚本，并验证可运行性；然后循环进入下一个用例。一定程度上减少第一种方式的上下文丢失。
• 代码优先（适合vibe coding者）：基于plan直接生成完整的测试脚本代码，然后一个个运行并修复。
• 对于50+用例的场景：建议先跑一部分测试，生成脚本，调通后再让AI依葫芦画瓢。

[图片]

复杂用例场景处理

1. 登录态解决
   • a. 本地
   • b. 平台
2. 用例前置数据准备
   • a. 已支付订单相关行为测试（3A造数）

后续迭代方向

• 基于上面的Plugin & Skill，探索分发测试工作流的各部分。
• 减少AI测试的等待时间，提升生成测试脚本的准确性，并减少过程中的token消耗。

AI Mock工作流

实现方案

[图片]

核心优势

• AI帮你完成配置：调用 /bili-fe-mock-workflow-setup 即可。
• 无需额外袋里软件配置，集成在你的前端项目里，且不影响业务代码。
• 与你本地的AI Agent无缝集成，任意Mock逻辑（mock本身即代码）。
• 3种模式任选：AI通过MCP动态添加（不改本地文件）、AI修改本地custom-handlers（gitignored）、基于Swagger。

使用场景

• 开发过程中没有实际接口时Mock。
• 已有接口，但需要调整不同数据返回来测试不同UI场景。
• 本地UI测试时，临时Mock一下。
• 减少AI操作浏览器消耗的token。
• 剩下的，就靠你的想象力了。

使用方式

• 调用 /bili-fe-mock-workflow-setup 初始化。
• mcp_server_sdk 配置 --enable-mock 参数，以及额外可选选项（刷新页面保留添加参数：--mock-persist-handlers）。
• 首次可以调用 /bili-fe-mock-workflow 你的mock需求，不明确时AI会引导你用哪种mock方式：

[图片]

• 前2个直接开始mock。选择swagger时，会引导你使用定制的 /bili-fe-swagger-mock-workflow 来完成swagger mock。
• 后续的mock，或者你已经很清楚要怎么mock，直接告诉AI要求就行，不必每次都调工作流。

总结思考

过去一年的实践，已经验证了这套方法论的有效性。但这仅仅是个开始。AI时代的前端开发，正在经历根本性的范式变革。过去我们依赖个人经验来推动需求落地，未来则会更多依赖规范化的工作流、可复用的上下文资产，以及人与AI的协同生产机制。

Harness Engineering的意义，不只是提供一套更高效的开发流程，更在于在团队内部建立一种新的工程共识：先定义清楚问题，再约束生成过程，最后通过标准化验证确保结果可交付、可维护、可复用。

这意味着，前端工程师的价值正在从“单点编码产出”转向“问题抽象、方案设计、规则沉淀与质量把控”。谁能更好地组织需求、编排上下文、制定约束、验证结果，谁就能更有效地放大AI的能力。工作流的价值也不仅体现在单次提效上，而在于它能否沉淀为团队能力，帮助更多同学以更低门槛、更稳定质量完成复杂交付。

因此，这份文档的目标不是给出一个固定答案，而是提供一个可实践、可迭代的起点。希望大家在使用过程中，持续补充案例、沉淀模板、优化规则，将零散的个人经验逐步升级为团队共享的智能开发体系。这套体系一旦建立，提效就不再是偶发结果，而会成为组织层面的稳定能力。