用途：为使用 GraphQL 与 Apollo Client 的项目提供查询、变更与类型生成的统一开发规范，减少内联写法与手写 hooks 带来的类型和错误处理问题。
主要能力与规则：不内联 gql 字面量，改为创建 .gql 文件；创建或修改 .gql 后必须运行代码生成；所有变更必须添加 onError 处理；查询与变更一律使用生成的 hooks，不写原始 Apollo hooks。文件按组件或 graphql/mutations、graphql/fragments 目录组织，生成文件不可手改。
使用方式：新建 .gql 定义查询或变更，运行 npm run gql:typegen 生成类型，再导入如 useGetItemsQuery、useCreateItemMutation 等生成 hook 使用；下载 schema 并生成类型用 npm run sync-types。变更触发控件需在提交期间禁用、显示加载状态、具备 onError 与成功反馈；查询可配置 fetchPolicy（cache-first、cache-and-network、network-only、no-cache）等选项。
适用场景：React 与 Apollo Client 项目中新增查询、变更、可复用字段选择片段，以及需要即时反馈的乐观更新。
限制：乐观更新不适用于可能校验失败、含服务端生成值、删除等破坏性操作或影响其他用户的操作。分页、认证、错误上报等细节暂未提供。