docs: 迭代17 策略会话（R-019）设计文档 + 开盘啦 API 参考材料

2026-09-09 08:58:49 +08:00
parent 6a578cc598
commit 9382ace3a0
6 changed files with 3394 additions and 0 deletions
@@ -0,0 +1,23 @@
+# 计划：策略会话——会话以策略当前数据为依据做讨论（阶段航点）
+
+> 来源：R-019（**已定稿**，2026-09-08）｜ 状态：执行中（设计阶段先行）｜ 所属迭代：17-策略会话
+> 粒度：阶段航点（覆盖设计 → 宿主调研 → 实现 → 验收全过程，随进展拆分小任务）
+
+## 目标
+
+让 AI 会话可以"以策略为 Workspace"（数据依据版）：**对话开始前选「讨论策略」→ 服务端生成该策略当前数据摘要 → 预注入会话上下文 → 以该策略当前数据为依据进行复盘/分析讨论**；只读、会话中可换/刷新、产物不落盘。
+
+## 范围与分阶段
+
+1. **设计阶段（当前，老师指令：先做产品逻辑 + UI 交互逻辑）**：产出《产品逻辑设计》《UI交互设计》，D 系列问题老师拍板后定稿；
+2. **宿主注入通道调研**：确认把外部摘要注入会话上下文的可行通道/形态（决定"折叠数据依据条"还是"文本消息形态"呈现；影响客户端渲染方案与注入动作实现）；
+3. **技术实现方案**（技术约束核对、服务端摘要服务 + 客户端选择 UI + 注入动作 + 回归）；
+4. **实现 + 验收**。
+
+## 验收指向
+
+见 `docs/04-迭代记录/17-策略会话/验收标准.md`（实现阶段补充细化）。
+
+## 边界
+
+见 R-019 定稿边界：不用宿主工作区；不开放账本写；不做按需取数工具；复盘产物不落盘；本期不做通用视图（全部持仓/交易记录）作依据。
@@ -0,0 +1,76 @@
+# 迭代 17 UI 交互设计：策略会话（讨论依据控件）
+
+> 依据：R-019（已定稿）+ 产品逻辑设计（同迭代）｜ 日期：2026-09-08 ｜ 状态：**设计稿（D 问题待拍板）**
+> 视觉基线：UI约束-004（--dsw-* token）/ UI约束-001（头部 chip 形态）/ 现有 QmtConnectionChip 交互模式；复用 Toast、外点关闭、RPC(useRpc) 机制。
+
+## 1. 交互总览（一句话）
+
+对话视图输入区上方有一枚**「讨论依据」chip**（仿 DSH workspace chip：未选=「讨论依据：请选择 ▾」；已选=「依据：做T ▾」+刷新）；选择策略 → 服务端生成数据摘要 → 注入并在对话流顶部出现一条**数据依据条目**，之后即可基于该策略数据讨论。
+
+## 2. 控件布局（示意）
+
+```
+┌─ 对话视图 ──────────────────────────────┐
+│ …对话消息流…                             │
+│   [数据依据条 ▾ 做T · 快照 14:32 · 3仓/42笔]  ← 选后注入显示（可展开全文）
+│ ─────────────────────────────────────── │
+│ [依据：做T ▾] [↻]                    │ ← accessory 行（输入框上方左侧）
+│ ┌ 输入框（composer）────────────────┐  │
+│ └────────────────────────────────────┘  │
+└─────────────────────────────────────────┘
+```
+
+## 3. chip 状态机
+
+| 状态 | 外观 | 交互 |
+|---|---|---|
+| 未加载 | 不显示（静默，与 QMT chip 一致） | — |
+| 未选择 | `讨论依据：请选择 ▾`（tertiary 色） | 点开 → 策略下拉（空态见 §5） |
+| 生成中 | `依据：做T …`（opacity .6，右侧小 spinner/省略） | 不可再点（防抖） |
+| 已选择 | `依据：做T ▾` + 右侧「↻ 刷新」小钮 | 点 chip 换策略；点 ↻ 刷新注入 |
+| 策略已删除 | `依据：做T（已删除）▾`（warning 色） | 下拉选其它/清除 |
+| 错误 | toast 错误 + chip 保留原态 | 可重试 |
+
+## 4. 交互细节
+
+1. **选择策略（F1 主流程）**
+   - 点击 chip → 下拉菜单（与 QmtConnectionChip 同一套 Menu 视觉）：
+     - 标题区「以哪个策略讨论？」；
+     - 策略项：每项 = 策略名 + 副行「当前 N 只持仓 · 最近交易 …」；
+     - 底部「清除依据」（仅已选时出现）；当前依据项前打 ✓；
+   - 点击某策略 → chip 进入生成中 → 服务端取摘要 → 注入会话 + 对话流顶部出现依据条目 → toast.success(`已载入「做T」数据依据：3 持仓 / 42 笔交易（快照 14:32:05）`)。
+2. **注入条目（D-1 建议形态）**
+   - 视觉：淡色卡片/引用样式（bg-layer 弱化 + 左侧竖条 accent），标题行「⛭ 神之一手数据依据」+ `做T · 快照 2026-09-08 14:32:05`，行 2 摘要「当前持仓 3 只 / 历史交易 42 笔（含已清仓）」；
+   - 默认折叠，点击展开全文（markdown 摘要内容）；
+   - 多依据/多刷新并存时按时间堆叠，最近一次在消息流最新处；不伪装用户/助手消息（若通道仅支持文本消息，则呈现为最顶部一段普通消息文本——实现以调研为准）。
+3. **换策略**：chip 下拉选另一策略 → 同"生成中→注入"流程；chip 文案与已注入条目更新。
+4. **刷新依据**：点 chip 右侧 ↻ → 生成新快照并注入新条目（含新快照时间）；toast「已更新依据（快照 14:35:10）」。不会删除旧条目。
+5. **清除依据**：下拉「清除依据」→ chip 复位「请选择」；不清除历史注入条目。
+6. **键盘/可及**：Esc 或外点关闭下拉；chip 提供 title 提示「以某个策略的数据为依据开始讨论（只读）」。
+7. **只读表达**：选择器下拉仅含策略与其状态信息，无任何写/操作入口；文案提示"会话只读，不执行交易操作"（依赖尾注与依据条目样式即可，不打断输入）。
+
+## 5. 空态与边界 UI
+
+| 场景 | UI |
+|---|---|
+| 无策略可配置 | 下拉空态：「暂无策略，请到 设置 → 神之一手 → 策略分组 添加」+「去设置」快捷键位 |
+| 策略持仓为空 | 摘要条目持仓区显示「当前无持仓」；交易摘要照常 |
+| 行情缺失 | 摘要中现价列显示 —，条目副行提示「部分行情缺失（--）」，不阻塞 |
+| 生成失败/服务不可用 | toast.error(原因)；chip 回原态可重试 |
+| 已在数据 tab（.odl-root）| 不显示该控件（现状 CSS 隐藏 composer 的区域一致，仅聊天视图展示） |
+
+## 6. 组件落点（初拟，技术方案细化）
+
+- 客户端新组件 `StrategyBasisChip.jsx`（chip + 下拉 + 刷新），复刻 QmtConnectionChip 的结构（rootRef/外点关闭/useRpc/useToast）；
+- 注入条目组件 `DataBasisCard.jsx`（折叠/展开 markdown 展示）；
+- 服务端新只读端点（`one-divine-lot/strategies/basis-summary`）生成摘要（产品逻辑 §4 规格）；
+- 挂载位置：D-4（对话 accessory vs 会话头部）拍板后确定 slot 与可见性策略。
+
+## 7. D 问题（AI 建议项，与产品逻辑设计共享，待老师拍板）
+
+| # | 问题 | AI 建议 |
+|---|---|---|
+| D-1 | 注入条目呈现形态 | 折叠「数据依据」卡片，点开全文（见 §4.2） |
+| D-2 | 交易摘要聚合粒度 | 按持仓聚合 + 已清仓标注；如需近期逐笔再加近 N 笔 |
+| D-3 | 依据跨刷新持久化 | 会话级不持久化（重开重选） |
+| D-4 | chip 位置 | 对话视图输入框上方 accessory 行左侧（仿 workspace chip 位置）；备选=会话头部与 QMT chip 并排 |
@@ -0,0 +1,91 @@
+# 迭代 17 产品逻辑设计：策略会话
+
+> 依据：R-019（已定稿）｜ 日期：2026-09-08 ｜ 状态：**设计稿（D 问题待老师拍板后定稿）**
+
+## 0. 一句话逻辑
+
+> 会话 = 用户选定「讨论策略」→ 系统把该策略**当前数据**（当前持仓 + 全历史关联交易摘要）作为会话依据注入 → 之后人机围绕该数据复盘/分析；依据可随时更换/刷新；只读。
+
+## 1. 概念与数据域
+
+| 概念 | 定义 | 数据来源 |
+|---|---|---|
+| 策略 | settings 中的策略定义（id/name，做T、网格超市…） | settings.strategies（现有） |
+| 策略当前持仓（活动行） | 该策略账本中未清仓的 holding（shares>0 活动） | SqliteStore strategy_holdings（R-018 数据域：账本为唯一权威） |
+| 行情现价/涨跌 | holding code 的实时价格 | QuoteHub 内存快照（读穿透；不可得=—） |
+| 关联交易记录 | 归属该策略/持仓的委托（含已清仓历史，trade_orders 归属列 + 历史库） | SqliteStore trade_orders/trade_fills（R-009/R-018） |
+| 数据依据（basis） | 一次注入到会话的"策略当前数据摘要快照" | 服务端按需生成（本设计） |
+
+**关键语义（沿用 R-018 数据域分界）**：持仓展示 = 账本（活动行）；交易 = 归属账本（历史全量）；行情 = 内存快照。摘要生成**只读**这些域，不写账本。
+
+## 2. 会话级状态
+
+策略会话不需要跨会话持久存储（设计建议，见 D-3）；会话内 UI 状态：
+
+- `basis: none | { strategyId, strategyName, injectedAt }`
+- `basisState: idle | generating | done | error`
+- 注入后的摘要内容随会话消息流存在（可折叠"数据依据"条目），不单独存储。
+
+## 3. 核心流程
+
+### 3.1 选择策略 → 注入依据（主流程）
+1. 对话视图（聊天）中，用户在「讨论依据」控件里选一个策略；
+2. 客户端调服务端 `strategies/:id/basis-summary`（只读）生成摘要文本（规格见 §4）；
+3. 摘要通过**宿主注入通道**进入当前会话上下文（技术通道调研待定，见 §6）；同屏在对话流顶部呈现「数据依据」条目；
+4. toast 反馈：`已载入「做T」数据依据（3 持仓 / 42 笔交易，快照 14:32:05）`；
+5. 用户开始提问复盘/分析；模型以摘要（及会话中后续补充）为依据回答。
+
+### 3.2 换策略
+- 重开选择器选另一策略 → 再次执行 3.1（新摘要作为新的依据条目追加；chip 切换为新策略）。旧依据条目保留在历史中（模型自然以最近/明确引用的为准）。
+
+### 3.3 刷新依据
+- 已选状态下 chip 提供「刷新」：重新生成**当前时刻**摘要并注入（盘中数据变化后想拿最新）。
+- 语义：每次刷新=新快照依据条目（含新快照时间），不覆盖旧条目。
+
+### 3.4 清除依据
+- 选择器提供「清除依据」：回到无依据普通会话（chip 复位为「讨论依据：未选择」）；已注入的历史条目仍在消息流中，后续对话不再视为策略依据会话。
+
+### 3.5 边界
+| 场景 | 行为 |
+|---|---|
+| 无可选策略（未配置） | 选择器显示空态「暂无策略，请到 设置→神之一手→策略分组 添加」 |
+| 会话进行中该策略被删除/改名 | chip 下次加载策略列表时按 id 对齐：找不到=显示「策略已删除」+ 可清除；改名后按 id 正常（显示新名）；历史依据条目保留 |
+| 策略当前持仓为空 / 无行情 | 摘要照常生成：持仓区显示"当前无持仓"；现价列显示 —；交易摘要照常（历史） |
+| 账本只读 | 摘要生成与注入路径无任何写操作；UI 无操作按钮（区别于数据 tab 的手动操作） |
+| 未选策略的普通聊天 | 与现状完全一致，不受影响（策略会话是可选增强，不锁定会话） |
+
+## 4. 摘要规格（服务端 `basis-summary` 输出，markdown 文本）
+
+结构（自上而下）：
+1. **快照头**：`【神之一手数据依据】策略：做T ｜ 快照：2026-09-08 14:32:05 ｜ 数据为只读快照，非实时`
+2. **当前持仓**（活动行，逐行）：code 名称｜份额｜可用｜成本价｜现价（— 缺失）｜市值｜浮动盈亏｜持仓天数；尾部合计（N 只 / 总市值 / 总盈亏）。现价/市值缺行情时给—，不阻塞。
+3. **交易摘要（该策略全历史关联委托，聚合）**：总笔数/买入累计/卖出累计（按归属 holding 聚合）：
+   - 每 holding 一段：code 名称｜状态（持有中/已清仓 清仓日）｜买卖笔数｜累计买入(量/额)｜累计卖出(量/额)｜当前份额；
+   - 已清仓 holding 标注清仓日期与最后动作摘要；
+   - 排序：持有中在前（按成本日/名称），已清仓在后（按清仓日倒序）；
+   - **规模上限**：holding 超过 20 行时按最新清仓倒序截断并注明「更多历史见 交易记录 tab」。
+4. **尾注**：只读提示「以上为策略数据快照；本会话只读，不执行任何交易/账本操作」。
+
+字段精确取数与空值规则在技术实现方案细化。
+
+## 5. 非目标（本期明确不做）
+
+- 宿主工作区/目录注册（R-019 R3）；
+- 账本写/交易执行、任何操作按钮；
+- 按需取数工具（AI 自行调用业务接口）；
+- 复盘产物落盘 / 复盘管理（含 DB）——未来 T-002 方向；
+- 通用视图（全部持仓/交易记录）作依据；
+- 关注列表作为依据源。
+
+## 6. 技术通道（设计假设，待调研确认）
+
+注入的可行通道候选：① 宿主 injected-context/上下文节点（可折叠条目、非用户消息）→ 首选；② 会话 send（文本消息形态进会话）→ 兜底（呈现为一条前置依据消息）。**渲染与动作方案以调研结果为准**（本期设计保留两种形态的表达，UI 交互设计按"数据依据条目"统一描述）。
+
+## 7. D 问题（AI 建议项，待老师拍板）
+
+| # | 问题 | AI 建议 |
+|---|---|---|
+| D-1 | 注入条目的呈现形态 | 对话流顶部「数据依据」条目：默认折叠为一行（图标+策略+快照时间+行数摘要），点开看全文；不伪装成用户消息 |
+| D-2 | 交易摘要聚合粒度 | 按持仓聚合（每持仓一段汇总 + 已清仓标注），不逐笔铺开（避免注入过长）；如老师要"近期逐笔"可加近 N 笔小表 |
+| D-3 | 依据选择是否跨刷新持久化 | 本期**会话级不持久化**（刷新需重选；历史注入条目仍在消息流），与 R-016 会话级偏好一致、不加存储；复盘管理未来再考虑 |
+| D-4 | 选择控件挂载位置 | 对话视图输入框上方 accessory 行左侧（仿 DSH workspace chip 位置），仅聊天视图可见；替代方案=会话头部（与 QMT chip 并排）待老师定 |
@@ -0,0 +1,39 @@
+# 迭代 17：策略会话（以策略当前数据为依据的会话讨论）
+
+## 目标（一句话）
+
+让 AI 会话可"以策略为 Workspace"：对话开始前选「讨论策略」，预注入该策略**当前数据摘要**作为会话依据，AI 与老师围绕该策略持仓/交易做复盘与分析讨论；只读、会话中可换/刷新依据。
+
+## 目标描述
+
+- 老师原始诉求「新需求，让 AI 会话可以以策略为 Workspace」经四轮讨论定稿（R-019，2026-09-08）：
+  - **改造现有 DSH 对话窗口**，不引入宿主工作区/目录；
+  - 会话的数据 = ①开始前/过程中注入的策略当前数据摘要 + ②会话过程本身产生的对话；复盘管理（可能带 DB 沉淀）为神之一手未来模块，本期不做；
+  - 注入口径：当前持仓明细 + 该策略全历史关联交易聚合摘要（含已清仓）；
+  - 只读（Q4=A）；预注入不挂工具（R2-Q1=A）；产物不落盘（R2-Q4）。
+- **本迭代分阶段推进**：先设计（产品逻辑 + UI 交互逻辑，老师 2026-09-08 指令）→ 宿主注入通道调研 → 技术实现方案 → 实现与验收。
+
+## 讨论过程
+
+| 日期 | 轮次 | 要点 |
+|---|---|---|
+| 2026-09-08 | 需求讨论 Q1-Q4 | 语义收敛：非物理目录；数据为依据；会话内只读 |
+| 2026-09-08 | 需求讨论 R2 | 预注入；范围 R2-Q3=A；产物暂不落 |
+| 2026-09-08 | 需求讨论 R3 | 参考 DSH 工作区模式的"开始前选策略"体验，但**不用宿主工作区** |
+| 2026-09-08 | 需求定稿 F1/F2 | 首条消息前「讨论策略」选择 + 会话中可换/刷新；注入口径维持 R2-Q3=A |
+| 2026-09-08 | 老师指令 | 立项迭代：先做产品逻辑、UI 交互逻辑设计 |
+
+## 本期（设计阶段）交付
+
+- `产品逻辑设计.md`（数据与行为逻辑、摘要规格、状态与边界）
+- `UI交互设计.md`（交互流程、控件、视觉与文案、状态机）
+- D 系列设计问题（AI 建议项）→ 老师拍板 → 设计定稿
+
+## 后续阶段（设计定稿后）
+
+- 宿主注入通道技术调研 → 技术实现方案.md → 实现 → 验收标准.md + 验收（是否拆分独立迭代由老师定）。
+
+## 对老师配合的请求
+
+1. 拍板 D1-D4（产品/UI 设计中的 AI 建议项，见设计文档末）；
+2. 实现验收需真实会话环境人工目视。
@@ -0,0 +1,74 @@
+# 需求：R-019 策略会话（会话以策略当前数据为依据做讨论）· 已定稿
+
+> 登记：2026-09-08 ｜ 来源：老师指令（新需求）｜ 状态：**已定稿（2026-09-08，F1/F2 老师确认）**
+> 归属：迭代 17（待立项）｜ 计划：待出（PLAN-017）｜ 实现状态：未开始
+
+## 需求描述（老师原始诉求，原话）
+
+> **新需求，让 AI 会话可以以策略为 Workspace。**
+> 三轮讨论后收敛为：**让 AI 会话以某个策略的当前数据为讨论依据**（复盘 / 分析），改造现有对话窗口，会话开始前确认用哪个策略。
+
+## 讨论记录（2026-09-08）
+
+### 第一轮（Q1-Q4，老师拍板）——语义收敛
+
+| # | 问题 | 结论 |
+|---|---|---|
+| Q1 | 需求对象与形态 | 改造现有 DSH 对话窗口：会话以某个策略的持仓、交易记录为依据做复盘/分析 |
+| Q2 | 「以策略为 Workspace」含义 | **不是物理工作目录/文件为主要依据**；是让策略数据作为会话的聊天依据 |
+| Q3 | 入口与触发 | 在现有会话窗口（非独立新页面） |
+| Q4 | 会话内能力边界 | **A 只读**：读该策略业务数据，不开放账本写 |
+
+### 第二轮（R2-Q1..Q4，老师拍板）——机制与范围
+
+| # | 问题 | 结论 |
+|---|---|---|
+| R2-Q1 | 聊天依据如何生效 | **A 预注入**：选定策略即开始聊，把该策略数据依据注入会话上下文（不挂按需取数工具） |
+| R2-Q2 | 选择粒度 | C 单选策略/通用视图混选——后被 R3 收敛（本期仅策略） |
+| R2-Q3 | 时间覆盖 | **A**：当前持仓 + 该策略全部历史交易（含已清仓） |
+| R2-Q4 | 复盘产物 | **暂不落盘**（留会话历史）；保存沉淀属 T-002/未来复盘管理 |
+
+### 第三轮（R3，老师定调）——不用 DSH 原生工作区
+
+**老师原话（2026-09-08）**：目前不需要 dsh web 原本定义的工作区。会话的数据 = ① 会话注入的数据 + ② 会话过程中产生的数据；以后神之一手会加「复盘管理」，可能用数据库存沉淀；**目前会话只是以策略当前数据来做会话讨论**。
+
+- 不做 DSH 宿主工作区（不注册目录 / 不动工作区分组与侧栏）；
+- 「会话开始前选策略」= 仿工作区"先选再开始"的体验，但只做会话级策略依据选择；
+- 会话过程中产生的数据 = 会话历史本身；复盘管理（可能带 DB）为未来模块，本期不做。
+
+### 第四轮（F1-F2，2026-09-08 老师确认）——定稿收口
+
+| # | 问题 | 结论（老师拍板） |
+|---|---|---|
+| F1 | 入口形态（无宿主工作区下"会话开始前选策略"） | **采纳 AI 建议**：对话视图首条消息前显示「讨论策略」选择区（仿 DSH workspace chip Choose 体验：显示「依据：做T ▾」），选策略即注入数据摘要开始聊；会话中可点 chip 换策略 / 点「刷新」注入最新数据 |
+| F2 | 「策略当前数据」口径 | **采纳 AI 建议（R2-Q3=A 维持）**：注入 = 当前持仓明细 + 该策略全历史关联交易**聚合摘要**（按持仓/时间汇总买卖与结果，含已清仓；明细过长不进注入） |
+
+## 定稿语义
+
+- **对象**：现有 DSH 对话窗口（挂神之一手 tab 的会话），对话视图首条消息前出现「讨论策略」选择；
+- **机制**：选策略 → 服务端取该策略当前数据 → 预注入会话上下文（摘要形态，含快照时间）→ 开始聊；换策略 / 点刷新 = 再次注入该策略最新摘要（模型以最近一次注入为依据）；
+- **数据范围**：当前持仓明细 + 全历史关联交易聚合摘要（含已清仓），只读；
+- **能力**：会话内 AI 只读（无账本写 / 交易执行入口）；产物不落盘。
+
+## 定稿边界
+
+**做**：对话开始前的策略选择 UI（F1 形态）；策略当前数据摘要的生成与注入；会话中换策略/刷新的再注入。
+
+**不做**：DSH 宿主工作区/目录（R3 明确不需要）；账本写与交易执行（Q4=A）；按需取数工具（R2-Q1=A）；复盘产物落盘与复盘管理/DB（R2-Q4，未来 T-002/复盘管理另立）；通用数据视图（全部持仓/交易记录）作为依据（R2-Q2 收敛，本期仅策略）。
+
+## 计划阶段待办（定稿后第一件事：技术可行性调研）
+
+1. **宿主注入通道调研**：DSH 会话如何把外部数据作为上下文注入给模型（injected-context 节点 / 会话 send / 其他公开通道），确认可行通道与形态（决定"摘要以消息形态进会话"还是"上下文节点形态"）；
+2. 入口 UI 落点核实：对话视图首条消息前的输入区 accessory / workspace chip 同构位置可由插件挂载的 slot（及 composer 可见性管理，与现有"神之一手 tab 隐藏 composer" CSS 的交互）；
+3. settings 是否需记录策略-会话选择偏好（会话级，不持久化 or 持久化待定）；
+4. 数据摘要服务：服务端生成"策略当前数据摘要"的组成与规模边界（当前持仓字段集 / 交易聚合规则 / 上限裁剪）。
+
+## 关联
+
+- 终极目标：目标-002（策略）/ 目标-006（交易复盘）/ 目标-007（人机合一·只读）；目标-001（复用宿主会话能力）
+- 需求池：T-002 复盘记录工具（起草）——复盘管理/落库的未来归属
+- 设计约束影响（计划阶段核对）：技术约束-009（会话头部 slot 机制参照）/ 技术约束-014、产品约束-009（会话结构语义）、UI约束-001（chip 形态参照）；如需新约束条目于计划阶段补充
+
+## 验收
+
+**（计划/迭代立项后写入迭代验收标准.md）**