# SourceDeck 体验与性能优化迭代提案

> 中文（默认） | [English](2026-10-19-experience-iteration-proposal.en.md)

日期：2026-10-19。状态：**用户已批准并要求“按方案执行落地”**。0.3.1 与 0.3.2 已实施；条件范围 0.4.0 未启动。依据：[同类工具调研与实测基线](../research/2026-10-19-comparable-tools-experience-review.md)，结果见[实施与验收记录](../implementation/2026-10-19-experience-optimization.md)。下文保留设计时的目标与预算，不能将目标当成已达成的实测。

## 用户目标与成功标准

用户明确要求继续深度调研，再制定优化版本迭代；限制是减少复杂度，从使用者角度改善体验和使用性能。沿用已确认场景：开发者在当前聊天中找开源实现、筛选比较，再引用给 Agent。

推荐成功标准：**用户更早看到可判断的候选，判断时不中断，选完随时带回对话；静置资料台不会持续做大量重复工作。** “六个候选中选两个”作为固定评估任务，属于本提案的验证假设，不是已收集的用户统计。

不新增顶层工作区、不改八表业务边界、不引入新依赖/凭据/后台服务。精确支持 DSH `0.2.1-rc.2` 与 Cordis `4.0.5`，继续使用官方受管研究子会话。不改上游、不升级基线。

## 三种路线与选择

| 路线 | 收益 | 代价 / 局限 | 建议 |
|---|---|---|---|
| A：仅压缩视觉 | 减少留白、按钮和说明 | 任务阶段仍混在一起，无变化读取、搜索作用域和解释不足仍在 | 只作为微调手段 |
| **B：按用户任务收敛，分批优化** | 每批改善一个可测问题；先减重复工作，再减阅读与操作负担 | 需要明确不同状态与返回行为，不能只改样式 | **采用** |
| C：扩展为综合研究平台 | 覆盖长期归档、报告与关系探索 | 信息、模型请求、状态与维护成本同时增加，偏离当前任务 | 暂不进入路线图 |

## 页面复杂度预算

这是验收约束，不是要求新增设置项。

- 顶层只保留“候选资料 / 收藏夹”两个目的地；“对比”改为有选项时出现的上下文动作，数量与四项上限可见。
- 结果阅读态不常驻新需求或补搜 textarea。新搜索通过已有文字按钮展开；补搜通过“补充查找”展开。空态保留一句需求与开始按钮。
- 底部默认保持一条选择摘要和一个主动作“引用到对话”；在 420px 面板中允许两行。补搜是次动作；直接摘要进入文字“更多”入口，最多一层，功能保留且说明其立即发送、集合只读的后果。
- 卡片保留图片/Logo、名称、短解释、stars、代码更新时间、关键许可证/语言与保留/排除；对比选择继续可发现，收藏保留明确可点目标。不能靠缩字或移除用户已确认的信息压缩页面。
- 原因仍可选；topics、通用项目介绍与查询详情可折叠。归档/关键限制不能被“详情”掩盖。未知事实明确写未知，不加相关性分数。
- 无独立视图密度、排序策略或高级筛选设置。若某个优化必须增加持久入口，先明确它替换哪个现有入口。
- 默认两列、容器宽度 <620px 单列的决定继续有效；不引入列表/网格切换器。对比面板只改变其内部呈现。

## 按任务变化的行为

| 场景 | 推荐呈现与动作 | 必须保住的行为 |
|---|---|---|
| 尚无研究 | 一个需求输入框、开始按钮与少量示例 | 不要求先配筛选条件；`/deck <需求>` 仍可直接开始 |
| 后台进行中 | 主题、真实轮次状态、停止；有候选就能阅读 | 左侧可继续；旧结果不消失；无虚假百分比或额外自动模型调用 |
| 有结果 | 紧凑主题摘要、现有四类筛选与一个本地搜索、卡片；新需求框收起 | 新搜索先展开编辑、确认开始才建主题；取消回原结果，保留草稿；更新不抢焦点或重置滚动 |
| 补充查找 | 点次动作后展开一处补充输入，当前主题已确定 | 保留/排除/原因自动沿用；取消展开不清草稿，不自动新建主题 |
| 对比 2–4 项 | 在原面板内进入聚焦比较区；返回时恢复列表位置 | 一项可显示“再选一项”；加入对比不等于保留；不同主题选择不串台 |
| 已有保留项 | “引用到对话（N 条）”随时可用，成功提示一次 | 插入而不发送；正文、附件、已有引用和不可变快照语义不变 |
| 筛选无匹配 | 明确写“当前条件下没有匹配资料”，就地清除筛选 | 不误称研究零结果、不暗中重搜、不自动清除筛选 |
| 失败/中断/只读 | 错误与下一步就地可见；只读态隐藏不可执行编辑器 | 到达资料保留，重试不扩大范围，旧摘要投递仍幂等 |

## 拟议 0.3.1：减少重复工作，保持行为稳定

这批不增加可见功能，优先解决容易验证、风险较低的成本。

**范围**：

1. 面板完整读取改为串行调度，操作引起的 refresh 合并。候选页活动研究保持约 2 秒的刷新能力；终态静置改为 30 秒周期。收藏模式、已确认不可见/卸载时暂停全量读取，返回候选、恢复可见、切主题、操作确认后立即失效刷新。活动观察器继续运行。可见性要根据固定 RC 的实际挂载行为验证，不能用 `document.hidden` 代替所有面板可见性。
2. 保留命令/自然语言打开所需的活动观察器，单独统计它的轻量请求；不得把 `openRevision` 当作内容 revision。第一批不依赖尚未验证的推送订阅，也不引入内容版本协议。
3. 复用按 locale 的 Intl formatter；对比每来源生成一次事实，按维度复用。每轮只做一次分组；收藏用查找集合避免卡片重复遍历。只在 profiler 证明有用的位置稳定 props / memo。
4. 避免无变化时替换展示数据、避免相同错误反复打断。相等判定先计量成本，不能用更昂贵的全量深比较替代重复渲染。原因输入在本地保持及时，持久化调度如有改变须在 blur/切主题前 flush。

**一致性代价**：跨窗口/其他客户端的写入在静置退避期间，可能最多约 30 秒才在当前面板显示；当前窗口操作确认、恢复可见和手动刷新走立即更新。后台结果不能因退避漏掉；进入 running 后恢复活动节奏。若这一延迟在任务测试中不可接受，再单独评审内容失效通知，不静默放宽一致性。

**验收与退出**：在固定 RC 真实 Host 上，静置 60 秒全量集合读取不多于 2 次（排除初始化与显式操作），running 时同一面板至多一个全量读取在途；全链路至少记录 full-load 与 activity 请求的独立计数。200 项压力样本测格式化调用数与 profiler；普通 6/24 项的写入、引用、换主题、重启、取消隔离无退化。达不到就继续这一批，不用新增功能掩盖问题。

**不做**：持久索引、新表、虚拟列表、全局状态库、后台 GitHub 抓取。内存扫描的当前 p95 不足 1ms，尚无优先重做存储层的依据。

## 拟议 0.3.2：收拢结果页，连续筛选不中断

依赖 0.3.1 的测量与基本交互回归稳定。这批每个变更都应减少现有摩擦。

1. 落实阶段化输入、紧凑 footer 与上下文对比入口；保留资料/收藏两个目的地。减少品牌重复与常驻操作提示，空态才讲启动方式，结果页优先展示本轮需求。
2. 候选与收藏分别记忆查询；当前主题搜索覆盖已有标题、URL、说明和原因，仍为本地筛选。筛选空、真正零新增、完成和失败使用不同文案；分组显示匹配数，不为每个被隐藏轮次重复显示空提示。
3. 决策给出逐卡保存反馈；失败保留草稿和最近确认状态。维持同卡写入顺序，避免按钮连点堆积但不能丢掉用户最后一次明确选择。先不增加乐观更新/撤销队列；已有重复点击撤销仍可用。
4. 待处理筛选中操作导致卡片离开时，焦点落到相邻项或筛选结果说明；轮询和结果追加不抢焦点。折叠详情、补搜及更多操作支持 Tab/Enter/Escape 和焦点恢复，真实 IME 不被快捷键截获。

**验收与退出**：以相同 fixture、相同面板和模型结果做 0.3.0 / 新版任务对照，先做 3–5 人形成性观察；属于小样本问题发现，不宣称统计显著。主要流程无需展开高级菜单即可完成：筛两项→引用→续写；补搜和直接摘要可发现。以完成时间、误判、回头找入口次数检验，若更难找就恢复文字入口，不能只以按钮减少为成功。

**不做**：新批量动作、单字母全局快捷键、自动全选/自动排除、强制写原因、结果热度排序、第二套状态或新的卡片外观切换。

## 条件性下一批：判断依据与窄栏对比

暂称 **0.4.0 候选范围**，不是必须全部实施的功能清单。只有前两批观察确认“候选看懂慢/比较不出结论”仍是主要瓶颈，才进入设计。

- 优先用现有 `note` 表达“与本次需求的关系及关键待确认点”，卡片把它放在通用 description 之前；以“研究判断”清楚标注，详情保留事实介绍。修改研究提示要求短、可追溯且允许未知，不另加模型调用。无需先扩字段，确需结构化 fit / limitations 时另行评审。
- 已有 license / archived 字段可在取得时显示；补齐提示中对它们的要求，有关键事实缺失则写待核验，不为了显示完整多跑研究。证据链接与查询时间放进现有详情，不做未经核验的“已认证”徽章。
- 对比只解决同维度阅读：>=620px 表格，窄栏按维度纵向、每项带名称；返回恢复筛选、焦点和滚动。没有用户需要可不增加“只看差异”、自定义列或 AI 排名。
- 研究结果质量以人工核对 URL、任务相关性、明确不确定性及补搜重复率来评估；不以候选数越多、摘要越长为好。没有时长/token 数据时不承诺“更深入且更便宜”。

若实际主要瓶颈是模型提供方慢、搜索工具不可用或信息缺失，单独记录到对应链路，不通过复杂 UI 遮掩。

## 性能与可用性预算

以下全部是**拟议验收目标，尚未实测达成**。先跑原版基线，若目标在目标机器上明显失真，记录原因并评审调整，不能把变更目标当作达标。

| 观测项 | 目标 / 方法 |
|---|---|
| 点击/输入到首次可见反馈 | 6/24/200 候选，典型动作各采 30 次，p95 ≤100ms；不等模型/网络确认才显示本地操作状态 |
| 本地操作到确认展示 | 单独记录 Host 确认耗时与随后绘制；超 300ms 显示局部保存状态，不以本地响应替代保存成功 |
| 面板加载到首批可操作候选 | 已有 24 项、暖启动目标 p95 ≤500ms，30 次；冷启动单列报告；排除模型研究时间与远程图片完成时间 |
| 静置成本 | 全量读取 ≤2 次/分钟；activity 观察器单列；不可见期间符合生命周期条件则无持续全量扫描；不声称 0 总请求 |
| 格式化/刷新 | 四项对比每渲染每项最多生成一份事实；未变化 tick 不触发全卡业务渲染；200 项只作压力样本 |
| 视口稳定 | 图像加载/失败不改变画框；用户阅读中的更新不跳到顶部；新结果不抢编辑焦点 |
| 空间利用 | 420×800 CSS px 的结果态，未展开输入时 header+nav+footer 目标 ≤35% 高度；截图/DOM 实测，同时维持正文≥14px、主操作≥32px；不以小字体硬达标 |
| 大列表升级触发 | 200 项仍 p95 >200ms 的交互、连续出现明显长任务或记录的 DOM/内存瓶颈时，先定位再评审按轮展开/虚拟化；不只因条目数触发 |
| 兼容与人工验收 | 320/420/640/900 宽、深浅、长中英、100%/125%；原生 IME/附件/缩放仍需真实验收，旧未验收项不可抹去 |

测试矩阵同时控制当前集合大小与历史总量：当前 6/24/200 项 × profile 1/100/1,000 主题。常见任务重点为 6/24，1,000 主题为压力规模；记录硬件、RC、插件 commit、插件启用清单及运行方式。不新增生产遥测或上传用户资料。

## 实现前必须明确的边界

- 简单退避不需新平台 API；可见生命周期和聚焦比较区返回行为需在固定 RC 验证。若后续考虑事件失效，先找该 RC 公共订阅证据，不能拿 master/alpha 示例代替。
- 候选决定、研究终态、引用、直接摘要的写入和失效必须仍按 session/set/round 归属。缓存如果加入，要覆盖 clear、source metadata 共享更新、其他窗口操作与重启；没有完整失效方案先不用缓存。
- 新搜索、关闭、返回不会丢未提交原因/需求/补搜输入。底部收起只改变展示，不改变草稿保存和引用校验。
- 本轮已有独立授权：用户在看到提案后明确要求“按方案执行落地”。授权覆盖前两批；条件批次仍须观察证据支持，不自动扩展。

## 发布与停止条件

每批独立回归、构建、沙箱安装和真实 Host 验收，检查后提交推送并核对 HEAD/远端；失败记录 pending。产品版本按实际批准范围再变更。生产安装仍需用户明确指示。

出现任一项即暂缓发布：引用/附件/正文丢失，迟到结果串主题，轮询退避漏掉完成状态，取消影响主会话，旧数据不可读，输入法冲突，次要动作隐藏后无法找回。若前两批已解决主任务，不继续追加 0.4.0 的内容。