405 lines
9.1 KiB
Markdown
405 lines
9.1 KiB
Markdown
# 禁止 API 幻觉规则更新总结
|
||
|
||
## 📋 更新概览
|
||
|
||
为所有开发类 Agent 添加了**禁止 API 幻觉、强制使用 Context7 查询文档**的关键规则，防止使用过时或不存在的 API。
|
||
|
||
**更新时间**: 2026-02-14
|
||
**规则级别**: ⚠️ **CRITICAL（关键）**
|
||
**影响 Agent**: Frontend Expert, Umi Pro
|
||
|
||
---
|
||
|
||
## ✅ 已更新的配置文件
|
||
|
||
### OpenCode Agent 配置
|
||
|
||
| 文件 | 状态 | 更新内容 |
|
||
| --- | --- | --- |
|
||
| `.opencode/agents/frontend.md` | ✅ 已更新 | 添加"禁止 API 幻觉"强制规则 |
|
||
| `.opencode/agents/umi-pro.md` | ✅ 已更新 | 扩展 Context7 部分为强制查询规则 |
|
||
|
||
### Antigravity Agent 配置（建议同步）
|
||
|
||
| 文件 | 状态 | 建议操作 |
|
||
| ---------------------------------------- | ----------- | ------------------ |
|
||
| `.agent/frontend_expert_agent_prompt.md` | 🔄 建议更新 | 添加相同规则 |
|
||
| `.agent/umi_pro_agent_prompt.md` | 🔄 建议更新 | 扩展 Context7 规则 |
|
||
|
||
---
|
||
|
||
## 🎯 核心规则内容
|
||
|
||
### 禁止行为 ❌
|
||
|
||
**绝对禁止**凭记忆或猜测组件框架的 API/Props 定义
|
||
|
||
- ❌ 凭记忆假设某个 prop 存在
|
||
- ❌ 使用未经验证的 API
|
||
- ❌ 基于"我记得好像有这个 API"的实现
|
||
|
||
### 强制要求 ✅
|
||
|
||
- ✅ **必须使用 Context7** 查询官方文档
|
||
- ✅ 实现前先调用 `mcp_context7_query-docs`
|
||
- ✅ 根据查询结果使用**确切的** props 和方法
|
||
- ✅ 验证 API 的存在性和正确用法
|
||
|
||
---
|
||
|
||
## 📊 适用范围
|
||
|
||
### 组件库
|
||
|
||
- **ProComponents**: `ProTable`, `ProForm`, `QueryFilter`, `ModalForm` 等
|
||
- **Ant Design**: 所有 antd 组件
|
||
- **Custom Components**: 任何项目特定组件
|
||
|
||
### Framework API
|
||
|
||
- **UmiJS**: `useRequest`, `useModel`, `access`, `useIntl` 等
|
||
- **React**: Hooks, Context 等
|
||
- **第三方库**: 任何外部依赖
|
||
|
||
---
|
||
|
||
## 🔍 错误模式示例
|
||
|
||
### 示例 1: ProTable API 幻觉
|
||
|
||
```tsx
|
||
// ❌ 错误：凭记忆猜测 API
|
||
<ProTable
|
||
onLoad={() => {}} // 实际不存在，应该是 request
|
||
data={data} // 实际不存在，数据通过 request 获取
|
||
loading={loading} // request 自动处理 loading
|
||
/>
|
||
```
|
||
|
||
### 示例 2: QueryFilter Props 幻觉
|
||
|
||
```tsx
|
||
// ❌ 错误：猜测 props
|
||
<QueryFilter
|
||
onSearch={handleSearch} // 实际应该是 onFinish
|
||
fields={searchFields} // 不是通过 props 传递
|
||
resetable={true} // 拼写错误，应该是 resetButtonProps
|
||
/>
|
||
```
|
||
|
||
### 示例 3: useRequest Options 幻觉
|
||
|
||
```tsx
|
||
// ❌ 错误：猜测 options
|
||
const { data } = useRequest(fetchData, {
|
||
auto: true, // 实际应该是 ready
|
||
cache: true, // 不是这个 prop
|
||
onError: () => {}, // 正确
|
||
});
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ 正确模式示例
|
||
|
||
### 示例 1: ProTable 正确用法
|
||
|
||
```tsx
|
||
// ✅ 正确：查询 Context7 后使用
|
||
// Query: "ProTable API props request columns"
|
||
// Result: 使用 request prop，columns 定义列
|
||
|
||
<ProTable
|
||
columns={columns}
|
||
request={async (params) => {
|
||
const data = await fetchList(params);
|
||
return {
|
||
data: data.list,
|
||
success: true,
|
||
total: data.total,
|
||
};
|
||
}}
|
||
/>
|
||
```
|
||
|
||
### 示例 2: QueryFilter 正确用法
|
||
|
||
```tsx
|
||
// ✅ 正确：查询文档确认 API
|
||
// Query: "QueryFilter props onFinish layout"
|
||
// Result: 使用 onFinish 和 layout props
|
||
|
||
<QueryFilter
|
||
layout="vertical"
|
||
onFinish={(values) => {
|
||
console.log('Search values:', values);
|
||
}}
|
||
onReset={() => {
|
||
console.log('Reset');
|
||
}}
|
||
>
|
||
<ProFormText name="name" label="名称" />
|
||
<ProFormSelect name="status" label="状态" />
|
||
</QueryFilter>
|
||
```
|
||
|
||
### 示例 3: useRequest 正确用法
|
||
|
||
```tsx
|
||
// ✅ 正确：查询确认 options
|
||
// Query: "useRequest options manual ready onSuccess"
|
||
// Result: 确认可用的 options
|
||
|
||
const { data, loading, run } = useRequest(fetchData, {
|
||
manual: true, // 确认存在
|
||
ready: !!userId, // 确认存在 (不是 auto)
|
||
onSuccess: (data) => {
|
||
message.success('Success');
|
||
},
|
||
});
|
||
```
|
||
|
||
---
|
||
|
||
## 🔄 正确工作流程
|
||
|
||
### 步骤 1: 确定组件/API
|
||
|
||
```
|
||
需求：实现一个带搜索的商品列表页
|
||
组件：ProTable + QueryFilter
|
||
```
|
||
|
||
### 步骤 2: 查询 Context7
|
||
|
||
```typescript
|
||
// 查询 ProTable API
|
||
(await mcp_context7_query) -
|
||
docs({
|
||
libraryId: '/ant-design/pro-components',
|
||
query: 'ProTable props request columns pagination',
|
||
});
|
||
|
||
// 查询 QueryFilter API
|
||
(await mcp_context7_query) -
|
||
docs({
|
||
libraryId: '/ant-design/pro-components',
|
||
query: 'QueryFilter onFinish layout props',
|
||
});
|
||
```
|
||
|
||
### 步骤 3: 阅读查询结果
|
||
|
||
```
|
||
ProTable 文档结果：
|
||
- request: (params) => Promise<{data, success, total}>
|
||
- columns: ColumnsType[]
|
||
- pagination: 分页配置
|
||
|
||
QueryFilter 文档结果：
|
||
- onFinish: (values) => void
|
||
- layout: 'horizontal' | 'vertical' | 'inline'
|
||
- onReset: () => void
|
||
```
|
||
|
||
### 步骤 4: 使用确切 API 实现
|
||
|
||
```tsx
|
||
<QueryFilter
|
||
layout="vertical"
|
||
onFinish={(values) => setSearchParams(values)}
|
||
>
|
||
{/* 搜索字段 */}
|
||
</QueryFilter>
|
||
|
||
<ProTable
|
||
columns={columns}
|
||
request={async (params) => {
|
||
const res = await fetchProducts({...params, ...searchParams});
|
||
return {
|
||
data: res.list,
|
||
success: true,
|
||
total: res.total,
|
||
};
|
||
}}
|
||
/>
|
||
```
|
||
|
||
---
|
||
|
||
## 📝 Context7 查询技巧
|
||
|
||
### 查询模式
|
||
|
||
```typescript
|
||
// 模式 1: 查询特定组件 API
|
||
mcp_context7_query -
|
||
docs({
|
||
libraryId: '/ant-design/pro-components',
|
||
query: '[组件名] API props [关注的 prop]',
|
||
});
|
||
|
||
// 模式 2: 查询使用示例
|
||
mcp_context7_query -
|
||
docs({
|
||
libraryId: '/ant-design/pro-components',
|
||
query: '[组件名] example usage [场景]',
|
||
});
|
||
|
||
// 模式 3: 查询特定功能
|
||
mcp_context7_query -
|
||
docs({
|
||
libraryId: '/umijs/umi',
|
||
query: '[Hook/API 名] options configuration',
|
||
});
|
||
```
|
||
|
||
### 常用 Library ID
|
||
|
||
| 框架/库 | Library ID |
|
||
| ------------- | ---------------------------- |
|
||
| ProComponents | `/ant-design/pro-components` |
|
||
| Ant Design | `/ant-design/ant-design` |
|
||
| UmiJS | `/umijs/umi` |
|
||
| React | `/facebook/react` |
|
||
| Axios | `/axios/axios` |
|
||
|
||
---
|
||
|
||
## ⚠️ 常见陷阱
|
||
|
||
### 陷阱 1: 混淆相似 API
|
||
|
||
```tsx
|
||
// ❌ 容易混淆
|
||
<ProTable onLoad={...} /> // 不存在
|
||
<ProTable request={...} /> // ✅ 正确
|
||
|
||
<QueryFilter onSearch={...} /> // 不存在
|
||
<QueryFilter onFinish={...} /> // ✅ 正确
|
||
```
|
||
|
||
### 陷阱 2: TypeScript 类型推断错误
|
||
|
||
```tsx
|
||
// ❌ 假设类型
|
||
const { data } = useRequest<ProductList>(fetch); // 假设返回类型
|
||
|
||
// ✅ 查询文档确认
|
||
// 文档：useRequest 返回 {data, loading, error, run, ...}
|
||
const { data, loading, error } = useRequest(fetch);
|
||
```
|
||
|
||
### 陷阱 3: 版本差异
|
||
|
||
```tsx
|
||
// ❌ 使用旧版本 API（可能已废弃）
|
||
<Modal visible={show} /> // Ant Design 4
|
||
<Modal open={show} /> // ✅ Ant Design 5
|
||
|
||
// 必须通过 Context7 查询当前版本的 API
|
||
```
|
||
|
||
---
|
||
|
||
## 🎓 执行建议
|
||
|
||
### 对开发 Agent
|
||
|
||
1. **实施前必查**：任何组件使用前都查询文档
|
||
2. **不确定即查询**：即使"记得"API，也要验证
|
||
3. **记录查询结果**：在代码注释中说明 API 来源
|
||
|
||
### 对 Code Reviewer
|
||
|
||
1. **检查查询记录**：验证是否查询过文档
|
||
2. **验证 API 正确性**：对照文档检查 props
|
||
3. **标记可疑用法**：发现未经验证的 API 使用
|
||
|
||
### 对 QA Tester
|
||
|
||
1. **关注运行时错误**：props 不匹配会导致警告
|
||
2. **检查 Console**：查看 React/Ant Design 警告
|
||
3. **报告 API 问题**：发现后反馈给开发 Agent
|
||
|
||
---
|
||
|
||
## 📚 配置文件具体变更
|
||
|
||
### Frontend Expert (`frontend.md`)
|
||
|
||
**位置**: 核心指令 - 第 3 条
|
||
|
||
**添加内容**:
|
||
|
||
```markdown
|
||
### 3. ⚠️ 禁止 API 幻觉（强制规则）
|
||
|
||
**CRITICAL**: 使用组件框架时，**绝对禁止**凭记忆或猜测 API/Props 定义
|
||
|
||
#### 强制要求
|
||
|
||
- ✅ **必须使用 Context7** 查询官方文档
|
||
- ✅ 实现前先调用 `mcp_context7_query-docs` 查询组件 API
|
||
- ✅ 根据查询结果使用**确切的** props 和方法
|
||
- ❌ **绝对禁止**凭记忆假设某个 prop 存在
|
||
- ❌ **绝对禁止**使用未经验证的 API
|
||
```
|
||
|
||
### Umi Pro (`umi-pro.md`)
|
||
|
||
**位置**: 核心理念 - 第 7 条
|
||
|
||
**更新内容**:
|
||
|
||
```markdown
|
||
### 7. ⚠️ 禁止 API 幻觉 - Context7 强制查询（关键规则）
|
||
|
||
**CRITICAL**: 使用组件框架时，**绝对禁止**凭记忆或猜测 API/Props 定义
|
||
|
||
[包含完整的强制要求、适用范围、查询示例等]
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ 预期效果
|
||
|
||
### 减少的问题
|
||
|
||
1. ❌ Props 不匹配导致的 React 警告
|
||
2. ❌ 使用不存在的 API 导致的运行时错误
|
||
3. ❌ 因版本差异导致的功能失效
|
||
4. ❌ TypeScript 类型错误
|
||
|
||
### 提升的质量
|
||
|
||
1. ✅ 代码更符合官方最佳实践
|
||
2. ✅ API 使用正确且最新
|
||
3. ✅ 减少调试时间
|
||
4. ✅ 提高代码可维护性
|
||
|
||
---
|
||
|
||
## 📊 影响统计
|
||
|
||
### 适用场景覆盖率
|
||
|
||
- **ProComponents 使用**: 100%
|
||
- **Ant Design 组件**: 100%
|
||
- **UmiJS API**: 100%
|
||
- **React Hooks**: 100%
|
||
- **第三方库**: 100%
|
||
|
||
### 强制执行级别
|
||
|
||
- **Frontend Expert**: CRITICAL
|
||
- **Umi Pro**: CRITICAL
|
||
- **Planning**: 建议（规划阶段提醒）
|
||
- **Code Spec**: 必须检查（审查时验证）
|
||
|
||
---
|
||
|
||
**更新完成时间**: 2026-02-14
|
||
**规则重要性**: ⚠️ CRITICAL
|
||
**强制执行**: 是
|