Skip to content

00-索引与决策摘要.md

Latest commit

 

History

History
94 lines (76 loc) · 8.88 KB

00-索引与决策摘要.md

File metadata and controls

94 lines (76 loc) · 8.88 KB
Raw
doc-id context-qa-00-index
title 上下文问答：索引与决策摘要
status proposed
version 1.4.0
last-updated 2026-09-02
implementation-status q0-q6-complete; q7-implementation-complete-remote-gate-pending; product-internal
source-range 选中元素后的单次只读问答、Key 与 Managed Codex、答案来源、转修改草稿及后续会话演进
参考文献/依赖
01-product-boundary
03-public-api-models
05-runtime-lifecycle
09-local-protocol-security
10-ui-diagnostics
15-risks-adr
16-ai-agent-execution
17-model-provider-credentials
external-agent-00-index
data-flow-09-ai-assistance
22-persistent-shell-motion-system

上下文问答：索引与决策摘要

本专题定义 SpotPatch 的“上下文问答（Contextual Ask）”目标规范。它解决当前产品只能把选中上下文送入修改流程、不能在 SpotPatch 内回答“这是什么组件”“为什么这里这样渲染”等问题的结构性缺口。

截至 2026-09-02，Q1–Q6 已通过；Q7 的 npm tarball 黑盒、Vite/Next 版本笛卡尔矩阵、Ubuntu/Windows/macOS 与 Node 20/22 CI、Windows npm Codex 原生可执行文件解析和发布前门禁均已落地。默认关闭的 contextualAsk flag 可在 Vite/Next 条件装配同一独立 Runtime extension：用户在持续 Planner 中显式切换 Ask/Change，以双草稿完成单轮只读提问、结构化答案、源码跳转、取消/重新开始和本地转修改草稿；Ask transport/UI 不进入未启用或 production 的 Runtime。**本机 macOS 的 Node 20/22 与 Vite 5/6/7、Next 15/16 代表组合已通过，但本工作区改动尚未进入远端 GitHub runner，Ubuntu/Windows 结果没有发生，故仍不能标记 beta 或进行跨平台宣传。**精确矩阵和放行规则见 (见 doc-id:context-qa-11-cross-platform-beta)。

2026-09-09 文档复核补充

当前 Vite、Next 与 Astro 已装配共享 Ask，packages/runtime/src/contextual-ask-panel-entry.ts、packages/dev-server/src/contextual-ask/ 和各适配器初始化/配置入口可核验其存在。上文 2026-09-02 的远端 Gate 描述是当时证据快照，不应解释为之后绝无 CI 运行；本次审计未收集满足本专题全部放行条件的新 run/矩阵证据，因此保持原有 internal 状态，不提升为 Beta。初始化器与手动默认值也需区分：Astro init 当前启用 Ask，Vite/Next 需按配置启用。

首阶段交付边界

首阶段必须同时满足：

  • 用户至少选择一个元素后才能提问；
  • 一次提交只有一个问题，一次执行只产生一个终态答案；
  • 支持已配置 Key 的 openai-compatible Provider，以及通过独立兼容 Gate 的 Managed Codex；
  • 答案回到 SpotPatch 当前工作台，并携带可点击、可校验的源码引用；
  • 可一键把当前选择、问题、答案摘要和引用转为可编辑修改草稿；
  • Ask 没有文件写工具、worktree、Diff、checks、Apply 或 Revert；
  • 不保留长期聊天历史，不提供全仓库无目标聊天；
  • 不通过自然语言猜测 Ask/Change，也不在一次 Ask 内隐式升级为修改。

首阶段明确不做：

  • 连续追问；
  • Claude Code 答案回传；
  • Cursor Inbox/CLI 答案回传；
  • 跨页面问答会话恢复；
  • 长期会话列表、搜索、云同步或知识库；
  • 无选中元素的通用仓库聊天。

这些后续能力的兼容方向见 (见 doc-id:context-qa-10-evolution)，不得提前污染首阶段协议和 UI。

核心决策

  1. Ask 与 Change 是显式任务种类，也是权限边界。 UI 必须由用户选择模式；服务端只相信 task.kind，不做意图分类和自动升级。
  2. 选择上下文与任务意图分离。 新建 SpotSelectionContext v1 与 SpotTaskEnvelope v1；现有 SpotAnnotation v3 在迁移期继续作为 Change 兼容载荷，不强行一次性重写全部链路。
  3. Ask 是独立只读执行器。 它可复用 Provider 会话、取消、清洗、源码授权和只读工具原语，但不得调用 executeAgentChange 或 managed-apply-v1。
  4. 答案是严格结构化结果。 模型只能引用服务端签发的 source handle；服务端解析、校验并投影为可打开的源码引用。Markdown 文本、任意 HTML 和模型自报绝对路径都不是引用协议。
  5. “转为修改”只创建草稿。 转换不会调用模型、创建写任务或申请写权限；每个目标仍必须拥有自己的修改说明，Ask 答案只作为来源证据，不复活已废止的全局修改 note。
  6. Provider 与 Managed Codex 共享领域结果，不共享执行实现。 Key 使用 @spotpatch/agent 的只读工具循环；Managed Codex 使用 @spotpatch/bridge 的独立只读 App Server adapter 和临时只读源码投影。
  7. 同一持续 Shell 承载 Ask。 不创建第二个浮层、第二套选择器或第二套动画状态机；Ask 状态通过既有 Runtime 视觉投影进入 Planner/Execution Island。
  8. 状态与版本声明以证据为准。 Managed Codex 必须证明 item/completed 的 agentMessage、outputSchema、read-only sandbox 和清理行为；Claude/Cursor 必须各自通过回传合同测试后才能启用。

文档地图

文档 doc-id 单一职责
00-索引与决策摘要.md context-qa-00-index 状态、范围、核心决策与规范优先级
01-需求与产品语义.md context-qa-01-requirements 用户目标、用例、Ask/Change 语义和范围外
02-实仓审计与能力矩阵.md context-qa-02-audit-compatibility 当前代码事实、根因和官方能力证据
03-总体架构与包边界.md context-qa-03-architecture 分层、依赖方向、复用边界和代码组织
04-领域模型与本地协议.md context-qa-04-model-protocol 任务、答案、引用、Job、endpoint、限制和错误
05-Key只读执行器.md context-qa-05-key-executor Provider 工具循环、Prompt、只读授权和结果提交
06-ManagedCodex只读适配器.md context-qa-06-managed-codex App Server、read-only profile、事件、结果与清理
07-UI状态机与交互规范.md context-qa-07-ui-state 模式、输入、答案卡、引用、动效、无障碍和状态矩阵
08-安全隐私性能与可观测性.md context-qa-08-security-performance 威胁模型、数据边界、保留、预算、日志和失败策略
09-测试验收与实施计划.md context-qa-09-testing-delivery Gate、测试矩阵、阶段顺序、迁移和完成定义
10-后续会话与外部回流演进.md context-qa-10-evolution 追问、Claude、Cursor、跨页面会话的兼容演进
11-跨平台Beta发布门禁.md context-qa-11-cross-platform-beta OS/Node/npm/Vite/Next 矩阵、Windows 约束、证据与 beta 放行

规范所有权

  • 本专题拥有通用 Contextual Ask 的产品、领域、协议和交互语义。
  • Provider Key、Base URL、凭据和协议认证仍由 (见 doc-id:17-model-provider-credentials) 拥有。
  • Change 的 worktree、写工具、checks、Apply/Revert 仍由 (见 doc-id:16-ai-agent-execution) 拥有。
  • 外部 Agent 的 Inbox、连接和 managed 写模式仍由 (见 doc-id:external-agent-00-index) 拥有。
  • 数据链路 Explain/Assist Find 的事实分类和 evidence 资格仍由 (见 doc-id:data-flow-09-ai-assistance) 拥有；它未来可复用 Ask 执行原语，但不是本专题的同义功能。
  • Shell 几何、Scene 动效和包体基线仍由 (见 doc-id:22-persistent-shell-motion-system) 拥有。

若发生冲突，权限和安全规范优先于交互便利；专题内优先级为：04 协议 > 05/06 执行 > 08 安全 > 07 UI > 01 产品 > 00 摘要。实现状态只在本页和 (见 doc-id:context-qa-09-testing-delivery) 更新，其他页面不得自行宣称 released。