Skip to content

01-产品定义与边界.md

Latest commit

 

History

History
150 lines (110 loc) · 11.4 KB

01-产品定义与边界.md

File metadata and controls

150 lines (110 loc) · 11.4 KB
Raw
doc-id 01-product-boundary
title 产品定义与边界
status active
version 1.9.0
last-updated 2026-09-09
source-range 规格书 §1、§1.1–§1.3；v1.1 新增可选 AI Agent 产品边界；v1.2 多目标与双语产品化边界；v1.3 Cursor/VS Code 源码导航与开源入口；v1.4 编辑器工作区归属；Next.js 公共预览与正式支持边界；上下文问答实现与成熟度边界
参考文献/依赖
02-architecture-stack
03-public-api-models
09-local-protocol-security
10-ui-diagnostics
12-testing-acceptance
15-risks-adr
16-ai-agent-execution
17-model-provider-credentials
next-00-index
next-01-research-compatibility
context-qa-00-index

产品定义与边界

Astro 公共集成补充（2026-09-06）

平级 @spotpatch/astro 已作为 npm 公共集成发布，且仅在 astro dev 工作；原生模板不要求 React，React 岛屿使用公共 JSX 编译链路。除定位、DOM/CSS、编辑器和 Prompt 外，现已接入公共 AI 审阅/应用/回滚、dataFlow、只读 contextualAsk、externalAgent 和 Astro 专用 trustedFastMode 检查。服务端执行仍不由浏览器证明，动态 DOM/其他岛框架不保证内部 exact。正式验证矩阵为 Node >=22.12 与 Astro 5.18.2、6.4.8、7.2.8，并覆盖 Linux、macOS、Windows；当前范围与验收以 Astro 功能对齐规范为准。发布状态不扩大外部 Agent、SSR adapter、第三方 UI 框架或其他版本的现有成熟度承诺。

产品定义

SpotPatch 是一个本地优先、仅在开发期运行的页面上下文与修改工作台。当前有 Vite、Astro 和 Next.js 三个平级入口，分别保留正式支持、文档矩阵和公共预览边界。用户选择页面元素并逐项描述要求，工具关联授权源码、DOM/CSS 与适用的组件语义，支持编辑器导航、结构化 Prompt、显式只读 Ask 和可选修改流程。下文 v1/v1.1 等段落保留历史阶段合同，不应单独当作全部当前能力清单。

一句话定位：

像在 Figma 里评论网页，但每个标注都直接连接真实源码，并能转化为 AI 可执行的开发上下文。

v1 必须交付

  • 鼠标悬浮高亮页面元素。
  • 点击选中元素，不触发业务点击行为。
  • 显示 React 组件名称和精简组件栈。
  • 定位业务源码文件、行号、列号。
  • 显示定位来源和置信度。
  • 添加一条文字标注。
  • 提取经过清洗的 DOM。
  • 提取命中 CSS 规则和关键计算样式。
  • 提取源码附近片段。
  • 预览并一键复制结构化 AI Prompt。
  • 一键在自动识别的 Cursor 或 VS Code 中打开精确文件位置，也可显式固定编辑器。
  • 仅在 Vite 开发服务器中工作。
  • 生产构建零代码、零属性、零接口残留。

上述能力的模块实现分别由架构文档和子模块规范定义 (见 doc-id:02-architecture-stack)，最终验收口径由测试与验收规范定义 (见 doc-id:12-testing-acceptance)。

v1 明确不做

  • 不调用任何 AI API。
  • 不自动修改业务代码。
  • 不读取或上传整个项目。
  • 不做账号、团队、云同步和分享链接。
  • 不创建 GitHub、Linear 或 Jira 任务。
  • 不录制完整用户操作过程。
  • 不支持生产环境。
  • 不正式支持 Vue、Svelte、Angular、Next.js、Webpack。
  • 不承诺精确还原第三方 CSS-in-JS 的原始源码行号。
  • 不读取跨域 iframe 和跨域 stylesheet。

以上是 v1 核心交付的历史边界，继续有效。v1.1 通过新的、默认关闭的扩展能力增加 AI 执行链路，不把该能力反向改写成 v1 的必需项；ADR-006 的适用范围及后续演进见架构决策 (见 doc-id:15-risks-adr)。

v1.1 可选 AI Agent 扩展

当且仅当用户在 Vite Node 可信配置中显式启用 AI，并配置 provider URL、环境变量 Key 和允许模型后，SpotPatch 可以提供以下开发期能力：

  • 把当前不可变的 SpotAnnotation 作为任务起点，而不是让模型从截图猜测位置。
  • 通过经过能力探测的模型协议执行结构化工具调用。
  • 在隔离 Git worktree 中按需搜索、读取和修改允许的本地源码。
  • 对变更执行路径、规模、补丁和项目检查门禁。
  • 默认先展示完整 Diff 和检查结果，由用户确认后应用到业务工作区。
  • 在严格门禁全部通过且配置显式允许时，支持受限的自动应用。
  • 应用后在文件未发生后续变化时，支持撤销本次 Agent 变更。

本地工具、Git 隔离、审阅和撤销规则只有一个事实来源 (见 doc-id:16-ai-agent-execution)；URL、凭据、模型、协议和远程数据边界只有一个事实来源 (见 doc-id:17-model-provider-credentials)；配置字段和默认关闭行为见公共 API (见 doc-id:03-public-api-models)。

v1.1 AI 扩展明确不做：

  • 不在生产构建、vite preview 或非开发服务器中启用。
  • 不要求 Codex CLI，也不把任意 CLI 作为隐式后门。
  • 不自动执行 git commit、git push、创建 PR、发布或部署。
  • 不向模型开放任意 shell、任意网络请求或依赖安装。
  • 不在首版自动 stash、覆盖或合并脏工作区。
  • 不承诺任意“OpenAI 兼容”中转站都支持可靠工具调用；必须以真实能力探测为准。
  • 不把 URL、Key 和模型名本身视为授权；本地执行权限始终由 SpotPatch 服务端策略决定。

未启用 AI、凭据缺失或模型能力不满足时，v1 的选择、定位、Prompt 预览、复制和打开编辑器能力必须继续正常工作。

v1.2 产品化工作台

v1.2 在不改变“仅本地开发期”和“AI 默认关闭”边界的前提下，把单目标标注扩展为可持续使用的多目标修改工作台：

  • 一次任务可选择配置允许数量的元素；每个目标必须拥有独立修改说明、源码上下文和编号高亮。
  • 不提供含糊的全局说明覆盖逻辑；Prompt 与可选 Agent 必须逐项保持不同说明，并把整组变更作为一个可审阅、可撤销的原子任务。
  • 内置中文、英文和标准语言自动解析，工作台内可即时切换且不丢失草稿、同意状态或 Job。
  • 使用 SpotPatch 品牌标识和统一设计令牌，形成专业开发工具层级；响应式、键盘、焦点、错误与字符预算反馈进入正式验收，不再作为演示性质 UI。
  • 单项说明、整组说明和目标数量均有公共硬上限；任何空项、超限或上下文未就绪都不能静默执行。

这些能力同时适用于本地 Prompt 和可选 AI 路径；未启用 AI 时仍完整保留多目标编辑、预览、复制和打开源码。数据值域 (见 doc-id:03-public-api-models)，交互与视觉 (见 doc-id:10-ui-diagnostics)，架构取舍 (见 doc-id:15-risks-adr)。

已实现：上下文问答（成熟度仍受专题 Gate 约束）

当前代码已实现由选择目标约束的 Contextual Ask，不能继续描述为“代码未实现”。至少选择一个元素后，用户显式切换 Ask，提交单次问题；Configured Key 或通过独立兼容 Gate 的 Managed Codex 返回带有服务端校验源码引用的只读答案。Vite、Next 和 Astro 已接入共享能力；手动配置默认关闭，初始化器是否启用以各自实现为准。

Ask 不创建 worktree、不写代码、不运行 checks，也不产生 Diff/Apply/Revert。“转为修改”只建立可编辑草稿，必须再次提交才进入写入任务。不提供连续追问、长期历史、无目标全仓聊天或 Claude/Cursor 答案回流。

2026-09-09 源码复核确认实现存在，但问答专题仍为 product-internal / remote gate pending，本次文档审计没有取得满足全部 Beta 放行条件的逐矩阵证据，不自行提升为跨平台 Beta。具体成熟度只由 问答专题状态 和 跨平台放行门禁 维护。

已实现：浮动工作台与灵动岛

入口、Planner 与执行岛共用持续 Shell，支持拖拽、吸附、视口约束和当前 Session 的位置恢复。视觉 Scene 来自真实 Runtime/Agent/Handoff 事件；待审阅不等于已应用，动画不能决定业务完成。独立 motion bundle 使用 GSAP 做有界、可中断过渡。该实现与专项浏览器视觉/性能验收完成是两件事，剩余门禁以 21、22 为准。

v1.3 源码导航与开源入口

  • 每个具备源码坐标的目标都提供独立快捷入口，底部操作继续打开活动目标；二者必须指向同一服务端授权坐标。
  • 默认识别启动 Vite 的 Cursor 或 VS Code 集成终端，并把绝对源码坐标交给该编辑器按工作区归属路由；无法识别时才使用有界后备探测。无法启动时给出可见、双语且可操作的反馈，不能以“请求已发送”冒充打开成功。
  • Apply 完成后保留已授权源码坐标供审阅导航，但释放旧 DOM 引用，避免把过期页面节点继续当作可修改目标。
  • 打开源码属于只读导航，不因 Agent 正在运行或结果进入审阅态而被编辑操作锁一并禁用。
  • 工作台提供唯一、可识别的官方 GitHub 仓库入口，用于文档发现、Issue 与项目传播；不得加入追踪参数、第三方推广脚本或侵入主任务的弹窗。

编辑器值域与默认值由公共 API 定义 (见 doc-id:03-public-api-models)，服务端确认语义与安全边界 (见 doc-id:09-local-protocol-security)，视觉、反馈和外链规则 (见 doc-id:10-ui-diagnostics)。

v1 支持矩阵

项目 v1 支持范围 说明
React 18.2–18.3 当前目标项目为 React 18.3.1
Vite 5、6、7 依赖公开 Plugin API；CI 分版本验证
TypeScript 5.5+ 工具自身启用最严格配置
JSX .jsx、.tsx 不解析 .js 中的 JSX
浏览器 Chromium 最新两个主版本 v1 自动化验收基线
编辑器 Cursor、VS Code 默认自动识别；可显式固定其中一个，其他编辑器后续通过 adapter 扩展
操作系统 macOS、Windows、Linux 受控 CLI 负责 Cursor/VS Code 工作区路由，未知环境由后备适配器探测
启动方式 vite / vite dev vite build、vite preview 禁用

React 19 先进入实验兼容矩阵，不进入 v1 正式承诺。原因不是 DOM/AST 方案不支持，而是组件栈增强依赖 React 私有 Fiber 信息；Bippy 文档也明确指出 React 19 的源码定位需要不同的 JSX runtime 配置。

Next.js 公共预览边界

@spotpatch/next 按 0.x 公共预览分发，但尚未进入正式支持矩阵。@spotpatch/vite 不能作为 Next.js 适配器使用；在阻断式 POC、完整兼容矩阵、生产零残留和 Registry 冷安装验收全部通过前，README、包描述和 UI 必须标注“公共预览”，不得声称“正式支持 Next.js”或“支持生产使用”。

候选 Next.js、Node、React、Router 与构建器范围只在兼容性规范中定义 (见 doc-id:next-01-research-compatibility)。专题文档状态、仓库决策和阅读入口 (见 doc-id:next-00-index)。公共预览不改变本文件的 v1 历史边界，也不降低现有 Vite 适配器的质量门禁。

产品边界如需改变，必须形成或更新架构决策 (见 doc-id:15-risks-adr)。