agent/.agent/NO_API_HALLUCINATION_UPDATE.md

# 禁止 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  
**强制执行**: 是