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 幻觉

// ❌ 错误：凭记忆猜测 API
<ProTable
  onLoad={() => {}} // 实际不存在，应该是 request
  data={data} // 实际不存在，数据通过 request 获取
  loading={loading} // request 自动处理 loading
/>

示例 2: QueryFilter Props 幻觉

// ❌ 错误：猜测 props
<QueryFilter
  onSearch={handleSearch} // 实际应该是 onFinish
  fields={searchFields} // 不是通过 props 传递
  resetable={true} // 拼写错误，应该是 resetButtonProps
/>

示例 3: useRequest Options 幻觉

// ❌ 错误：猜测 options
const { data } = useRequest(fetchData, {
  auto: true, // 实际应该是 ready
  cache: true, // 不是这个 prop
  onError: () => {}, // 正确
});

---

✅ 正确模式示例

示例 1: ProTable 正确用法

// ✅ 正确：查询 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 正确用法

// ✅ 正确：查询文档确认 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 正确用法

// ✅ 正确：查询确认 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

// 查询 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 实现

<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 查询技巧

查询模式

// 模式 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

// ❌ 容易混淆
<ProTable onLoad={...} />        // 不存在
<ProTable request={...} />       // ✅ 正确

<QueryFilter onSearch={...} />   // 不存在
<QueryFilter onFinish={...} />   // ✅ 正确

陷阱 2: TypeScript 类型推断错误

// ❌ 假设类型
const { data } = useRequest<ProductList>(fetch); // 假设返回类型

// ✅ 查询文档确认
// 文档：useRequest 返回 {data, loading, error, run, ...}
const { data, loading, error } = useRequest(fetch);

陷阱 3: 版本差异

// ❌ 使用旧版本 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 条

添加内容:

### 3. ⚠️ 禁止 API 幻觉（强制规则）

**CRITICAL**: 使用组件框架时，**绝对禁止**凭记忆或猜测 API/Props 定义

#### 强制要求

- ✅ **必须使用 Context7** 查询官方文档
- ✅ 实现前先调用 `mcp_context7_query-docs` 查询组件 API
- ✅ 根据查询结果使用**确切的** props 和方法
- ❌ **绝对禁止**凭记忆假设某个 prop 存在
- ❌ **绝对禁止**使用未经验证的 API

Umi Pro (umi-pro.md)

位置: 核心理念 - 第 7 条

更新内容:

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