msw-find-diff

Files (4)

• SKILL.md
• msw-plan.config.example.json
• msw-plan.template.md
• project-layouts.md

SKILL.md (first lines)

# msw-find-diff

## Overview

接受 **Swagger / OpenAPI / Postman**，结合前端项目中的 MSW、API 模块、request 封装与测试，找出接口与**字段差异**，输出 **`msw-plan.md`**。执行前读取项目约定，并按 **Vue / React 目录速查** 加速定位（见 [project-layouts.md](./project-layouts.md)）。

包入口：**msw-api**。改代码用 **msw-update-code**，验收用 **msw-verify-plan**。

## When to Use

- 用户提供 Swagger / OpenAPI / Postman
- 需要生成或更新 `msw-plan.md`
- 契约升级、mock 与文档对齐

**When NOT to use**：已有完整 `msw-plan.md` 且只需改代码 → **msw-update-code**

## 项目约定（必读顺序）

### 1. `msw-plan.config.json`（项目根，可选）

若存在则 **优先于** 默认启发式；可复制 [msw-plan.config.example.json](./msw-plan.config.example.json) 到业务仓库根目录。

| 字段 | 作用 |
|------|------|
| `framework` | `vue` \| `react` — 选用 [project-layouts.md](./project-layouts.md) 对应表 |
| `projectRoot` | monorepo 子包路径，如 `apps/web` |
| `handlersAggregate` | **总文件**：命中后只在此文件内查字段 |
| `globs` | 按角色覆盖 mocks / api / request / unitTests / e2e |
| `searchOrder` | 搜索顺序，默认：handlers → mocks → api → request → types → unitTests → e2e |
| `pathPrefix` / `baseURLFromEnv` | 文档 path 与项目 URL 对齐 |
| `docAuthorityDefault` | 默认权威：`document`（见下方） |
| `scope.includeDocPaths` | 只对比部分 path（增量） |
| `verifyCommands` | 供 **msw-verify-plan** 使用 |

### 2. 无 config 时：框架对号入座

1. `package.json`：`vue` → [Vue 表](./project-layouts.md#vue-3vite-常见)；`react` → [React 表](./project-layouts.md#reactvite--cra)  
2. 按 **searchOrder** 角色搜，不要一上来 `grep` 全仓库  
3. 见 [路径 → 角色](./project-layouts.md#跨框架路径--角色快速对号入座)  

在 plan「搜索记录」写：`config: yes|no`、`framework`、`handlersAggregate`。

## 权威来源（写入 plan 必填）

| 值 | 含义 |
|----|------|
| `document` | 以接口文档为准改 mock/类型（默认） |
| `project` | 项目故意偏离文档，**不建议**自动改为文档值 |
| `user-confirmed` | 用户确认以哪侧为准 |

表格增加列 **权威**。`project` 项勿让 **msw-update-code** 强改文档方向。

## 寻找方式（必须遵守）

1. **文档索引**：`method` + `path` + schema 字段  
2. **总文件优先**：`handlersAggregate` → **仅在该文件**完成字段对比  
3. **按 searchOrder 扩散**  
4. **禁止**总文件已命中仍全仓库乱搜  

## 执行步骤

解析文档 → 映射到项目 → 对比字段 → 写入 `msw-plan.md`（格式见 [msw-plan.template.md](./msw-plan.template.md)）。

## 输出要求

- **不改代码**，只产出 plan  
- 汇报：匹配数、未匹配、plan 路径  

## 衔接

用户确认 plan → **msw-update-code** → 可选 **msw-verify-plan**

## Common Mistakes

| mistake | 修复 |
|---------|------|
| 忽略 config / layouts | 先读 `msw-plan.config.json` |
| 只写「字段不对」 | 必须 **从 / 变为** |

From eminoda/msw-api, MIT.

More from eminoda/msw-api