# 禁止 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 {}} // 实际不存在，应该是 request data={data} // 实际不存在，数据通过 request 获取 loading={loading} // request 自动处理 loading /> ``` ### 示例 2: QueryFilter Props 幻觉 ```tsx // ❌ 错误：猜测 props ``` ### 示例 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 定义列 { 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 { console.log('Search values:', values); }} onReset={() => { console.log('Reset'); }} > ``` ### 示例 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 setSearchParams(values)} > {/* 搜索字段 */} { 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 // ❌ 容易混淆 // 不存在 // ✅ 正确 // 不存在 // ✅ 正确 ``` ### 陷阱 2: TypeScript 类型推断错误 ```tsx // ❌ 假设类型 const { data } = useRequest(fetch); // 假设返回类型 // ✅ 查询文档确认 // 文档：useRequest 返回 {data, loading, error, run, ...} const { data, loading, error } = useRequest(fetch); ``` ### 陷阱 3: 版本差异 ```tsx // ❌ 使用旧版本 API（可能已废弃） // Ant Design 4 // ✅ 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 **强制执行**: 是