SpotPatch
把 React 页面中被点选的元素连接到精确源码和受边界约束的开发上下文。先判断用户需要的是了解产品、接入项目、使用工作流还是排查问题，再执行对应流程。
工作原则
- 只根据实际项目和官方文档作结论，不把 peer dependency 范围写成已经验证的支持矩阵。
- 用户只要求解释、评估或排查时，仅检查并报告，不安装依赖、不改文件。
- 用户要求接入时，先识别框架、React 版本、Node.js 版本、包管理器、配置文件和现有工作区变更。
- 修改前保留用户已有改动；修改后展示变更并执行项目中已有的相关检查。
- SpotPatch 只用于开发环境。不要把 Runtime、源码标记、本地协议端点或凭据引入生产路径。
- AI 修改默认使用 Review。不要自动 commit、push、发布或部署用户项目。
需要精确兼容范围、安全边界、命令和能力限制时，读取 references/product-reference.md。
触发示例
- “帮我把 SpotPatch 接入这个 Vite + React 项目。”
- “我点选了页面上的按钮，怎么跳到它对应的 TSX？”
- “用 SpotPatch 整理这个 UI 修改需求，但先不要让 AI 改代码。”
- “检查 SpotPatch 为什么没有显示 Select element。”
- “我想看这个组件真正消费了哪些接口字段。”
- “在 Next.js 项目里试用 SpotPatch，并告诉我预览版有哪些限制。”
选择流程
用户想了解 SpotPatch
- 用一句话说明：SpotPatch 让开发者直接点选 React 页面元素，定位对应 JSX/TSX，并把可信上下文交给编辑器、任意编码助手或可选的审阅式 AI Agent。
- 强调无需 AI 也能使用源码定位、上下文检查和结构化 Prompt。
- 提供官网、GitHub 与 npm 链接；避免空泛的“万能”“完全自动”等宣传词。
用户想在 Vite + React 中接入
- 读取
package.json、锁文件和vite.config.*，确认：
- Node.js>=20.19.0；
- Vite>=5 <8；
- React 18.2–18.3；
- 项目使用 npm 或 pnpm。 - 如果不满足正式支持范围，说明具体差异并停止宣称“正式支持”；只有用户明确接受实验性验证后才继续。
- 在项目根目录执行推荐初始化：
bash
npx --yes @spotpatch/vite@latest setup
- 检查生成结果。
spotPatch(...)必须位于 React 插件之前；有歧义的动态 Vite 配置应让初始化器安全失败，再人工审阅接入。 - 使用项目原有开发命令启动页面。点击右下角 Select element / 选择元素，或按
Mod+Shift+S。 - 展示依赖与配置 Diff，并运行可发现的类型检查或构建检查。不要替用户提交代码。
如果用户要求手动接入 npm 项目，可使用：
npm install --save-dev @spotpatch/vite@latest
npx spotpatch-vite init
用户想在 Next.js 中接入
先明确告知：@spotpatch/next 是 0.x Public Preview，不在正式支持矩阵内；组件 Data Flow Beta 也不支持 Next.js。只有用户接受预览风险后继续。
- 检查 Node.js
>=20.19.0，并把 Next.js>=15.3 <17、React 18/19 仅解释为候选 peer 范围。 - 优先遵循仓库当前的 Next.js 预览文档；pnpm 项目使用：
bash
pnpm add --save-dev @spotpatch/next
pnpm exec spotpatch-next init
pnpm exec spotpatch-next check
pnpm dev
- 确认开发脚本通过
spotpatch-next dev启动，并检查next.config.*与instrumentation-client.*的生成结果。 - 遇到复杂 CommonJS 配置、混合 root/
srcRouter、冲突 Loader 或 rewrite 时安全停止，说明需要人工接入。
用户已经安装，想完成一次页面修改
- 启动项目原有开发服务器，不替换宿主应用的启动方式；Next.js 预览必须使用初始化后生成的脚本。
- 让用户点选一个或多个目标，并为每个目标写独立、可验证的修改要求。
- 在 SpotPatch 中核对组件名、文件路径、行列、React 栈和置信度；上下文不足或有歧义时先补证据。
- 根据用户意图选择：
- 在 Cursor 或 VS Code 打开精确源码；
- 预览并复制结构化 Prompt；
- 使用已明确配置的 AI Provider 在隔离 Git worktree 中准备修改。 - AI 路径默认选择 Review：查看项目检查、完整 Diff，再 Apply 或 Discard。
- 只有用户明确理解风险并主动选择时才使用 Trusted direct。该模式跳过宿主项目检查，不保证类型检查、lint、测试或构建通过。
用户想看组件数据链路
- 仅在 Vite + React 18 的开发环境使用 Data Flow Beta。
- 只报告有稳定组件、源码、调用点和调用实例证据的关系。
- 可以展示 HTTP 方法与路径、参数键位置、源码实际消费的响应字段，以及 React state、Zustand、storage 或 callback 去向。
- 不读取或复制响应体，不保留 query 值；模糊流量标记为 partial、unknown 或 unassigned。
- 不把时间或 URL 相似性当作组件归属证明，也不要声称 Next.js 已支持该功能。
故障排查
按以下顺序检查，避免直接重装：
- Node、React、Vite/Next.js 是否在相应范围内。
- 包管理器与锁文件是否一致，依赖树是否安装了同一套 SpotPatch 版本。
- Vite 中 SpotPatch 是否位于 React 插件之前；Next.js 是否通过
spotpatch-next dev启动。 - 页面是否处于开发模式，是否出现唯一的
spotpatch-root。 - 源文件是否位于默认
src/**/*.jsx或src/**/*.tsx范围，或被自定义 include/exclude 排除。 - 编辑器无法打开时，明确配置
editor: "cursor"或editor: "vscode"。 - LAN 访问、动态配置、rewrite/Loader 冲突等边界必须按文档安全失败，不要绕过认证或生产隔离。
报告问题时给出最小复现信息：框架与版本、React 与 Node 版本、包管理器、配置片段、启动命令、可复现步骤和完整错误文本；发送前移除密钥、Cookie、Token、响应体及业务隐私数据。
完成标准
- 项目范围与支持状态表述准确。
- 变更可见、可审阅，且未覆盖用户已有工作。
- 开发流程可以启动并完成元素选择或诊断。
- 生产路径没有被启用 SpotPatch。
- 未泄露凭据，未自动 commit、push、发布或部署。
- 最终回复附上下一步操作和必要链接。
官方链接
- 官网：https://spotpatch.dev
- GitHub：https://github.com/huanglvjing/spotpatch
- Vite npm：https://www.npmjs.com/package/@spotpatch/vite
- Next.js 预览 npm：https://www.npmjs.com/package/@spotpatch/next
