From b60da88e37e1228720ea523ca88415c5bcc1b3b2 Mon Sep 17 00:00:00 2001
From: kris <krisoso.com@gmail.com>
Date: Sun, 5 Apr 2026 12:40:16 +0800
Subject: [PATCH] docs: add conversation folder drawer design

---
 ...04-05-conversation-folder-drawer-design.md | 351 ++++++++++++++++++
 1 file changed, 351 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-04-05-conversation-folder-drawer-design.md

diff --git a/docs/superpowers/specs/2026-04-05-conversation-folder-drawer-design.md b/docs/superpowers/specs/2026-04-05-conversation-folder-drawer-design.md
new file mode 100644
index 0000000..6c2fb7e
--- /dev/null
+++ b/docs/superpowers/specs/2026-04-05-conversation-folder-drawer-design.md
@@ -0,0 +1,351 @@
+# 会话首页项目文件夹与抽屉模式设计
+
+日期：`2026-04-05`
+
+## 1. 背景
+
+当前 Boss 的会话首页已经具备：
+
+- 微信式 `会话 / 设备 / 我的` 顶层结构
+- `主 Agent`、单线程会话、群聊、系统会话的基础展示
+- 线程级搜索、项目文件夹页、线程详情页
+- 线程上下文环、活动状态、置顶分组、最新回复时间与预览
+
+但当前首页仍有一个结构性问题：
+
+1. **同一个项目下多个线程会直接或间接摊在首页。**
+   - 项目内线程一多，首页会很快变长
+   - 会话心智更像“线程管理器”，不像微信式会话列表
+   - 用户很难第一眼理解“这是一个项目，里面有多个线程”
+
+2. **文件夹能力已经存在，但前台还停在半状态。**
+   - 投影层已有 `folder_archive`、`folderKey`
+   - Android 也有文件夹页
+   - 但首页还没有完全收成“项目文件夹会话”心智
+
+3. **用户已经明确要求首页采用“文件夹 / 抽屉”模式。**
+   - 单线程项目仍直接显示线程
+   - 2 个及以上线程的项目在首页显示为一个项目文件夹
+   - 点进去后再看该项目下全部线程
+
+本设计的目标，就是把这条链正式收成稳定结构。
+
+## 2. 目标与非目标
+
+### 2.1 目标
+
+1. 会话首页只保留微信式聊天列表，不再让多线程项目把首页摊平。
+2. 单线程项目继续直接显示线程会话。
+3. 多线程项目在首页显示为一个项目文件夹会话。
+4. 文件夹项聚合展示：
+   - 最新回复时间
+   - 最新回复预览
+   - 最需要关注的上下文环
+   - 最近活跃线程提示
+5. 搜索仍然保留线程可达性，但不破坏文件夹心智。
+6. 线程数量变化时，首页能自动在“单线程直显”和“项目文件夹”之间切换。
+
+### 2.2 非目标
+
+1. 本轮不重做聊天详情页。
+2. 本轮不改变群聊、主 Agent、系统会话的核心模型。
+3. 本轮不新增新的数据存储层。
+4. 本轮不把首页改成项目管理器或复杂树状导航。
+5. 本轮不做项目文件夹内的拖拽排序或自定义手工分组。
+
+## 3. 用户体验结论
+
+采用用户已确认的 `1 + 2` 方案：
+
+1. **首页结构**
+   - `1 个线程` 的项目：直接显示线程会话
+   - `2 个及以上线程` 的项目：显示一个项目文件夹会话
+
+2. **文件夹会话聚合**
+   - 时间取项目内最新活跃线程
+   - 预览取项目内最新回复
+   - 上下文环取项目内最需要关注的线程
+   - 副标题包含：
+     - `N 个线程`
+     - `最近：某线程名`
+
+3. **导航层级**
+   - 首页负责项目级入口
+   - 项目文件夹页负责该项目下全部线程入口
+   - 点线程后进入现有线程聊天详情页
+
+这保证首页仍然像微信聊天列表，同时建立清晰的“项目文件夹”心智。
+
+## 4. 首页结构设计
+
+### 4.1 首页会话类型
+
+首页允许出现的会话项：
+
+- `主 Agent`
+- 群聊
+- 系统会话
+- 单线程项目会话
+- 多线程项目文件夹会话
+
+首页不再直接平铺多线程项目中的各个线程。
+
+### 4.2 单线程项目
+
+当一个项目只包含 1 个线程时：
+
+- 首页直接显示该线程会话
+- 展示逻辑维持现状：
+  - 标题：线程名
+  - 副标题：文件夹名/设备信息
+  - 时间：该线程最新回复时间
+  - 预览：该线程最新回复
+  - 上下文环：该线程自己的上下文状态
+
+### 4.3 多线程项目文件夹
+
+当一个项目包含 2 个及以上线程时：
+
+- 首页只显示一个项目文件夹会话
+- 文件夹会话展示字段：
+  - `title`: 项目名
+  - `subtitle`: `N 个线程 · 最近：某线程名`
+  - `latestReplyAt`: 项目内最新活跃线程的时间
+  - `preview`: 项目内最新活跃线程的最后回复
+  - `contextBudgetIndicator`: 项目内最需要关注的线程
+  - `activityIconCount`: 只在项目内真实有活动线程时显示
+
+文件夹会话在首页的外观仍应保持微信式会话行，不做卡片化管理面板。
+
+## 5. 聚合规则
+
+### 5.1 时间聚合
+
+文件夹会话的 `latestReplyAt` 取项目内最新活跃线程的真实时间。
+
+优先时间来源：
+
+1. 线程最新活跃时间
+2. 线程账本最新消息时间
+3. 项目最近同步时间
+
+### 5.2 预览聚合
+
+文件夹会话的 `preview` 取项目内最新活跃线程的最后回复预览。
+
+如果最新活跃线程没有可用预览，则向下回退到项目内下一个最近活跃线程。
+
+### 5.3 上下文环聚合
+
+文件夹会话的上下文环不取“最新活跃线程”，而取“最需要关注的线程”。
+
+优先级规则：
+
+1. `mustFinishBeforeCompaction = true`
+2. 更高的上下文风险级别
+3. 更近的活跃时间
+
+这保证首页能优先暴露“最需要被注意”的线程，而不是只是“最后说话的线程”。
+
+### 5.4 活动状态聚合
+
+文件夹会话的活动点只在项目内确实存在活动线程时显示。
+
+空闲项目文件夹不得因为聚合兜底而持续闪烁。
+
+### 5.5 副标题规则
+
+文件夹副标题统一格式：
+
+- `N 个线程 · 最近：某线程名`
+
+限制：
+
+- 最近线程名需要裁剪，避免副标题过长
+- 如果线程名缺失，则只显示 `N 个线程`
+
+## 6. 搜索设计
+
+### 6.1 搜索范围
+
+搜索仍然命中：
+
+- 项目名
+- 文件夹名
+- 线程名
+- 最近消息预览
+
+### 6.2 搜索结果呈现
+
+搜索结果不破坏首页文件夹心智。
+
+规则：
+
+- 命中单线程项目：直接显示线程会话结果
+- 命中多线程项目中的线程：显示 `项目名 / 线程名`
+
+### 6.3 搜索结果点击行为
+
+点击规则：
+
+- 单线程项目结果：直接进入线程聊天页
+- 多线程项目中的线程结果：
+  - 先进入该项目文件夹页
+  - 再定位或高亮目标线程
+
+这样既保留线程可达性，又不让首页结构回退到“全线程铺开”。
+
+## 7. 项目文件夹页
+
+项目文件夹页继续复用现有线程列表页，但语义需要收平：
+
+- 页面标题：项目名
+- 副标题：`N 个线程`
+- 列表项：该项目下全部线程
+- 每个线程项展示：
+  - 线程名
+  - 最新预览
+  - 最新时间
+  - 上下文环
+  - 活动状态
+
+点线程后，进入现有线程聊天详情页。
+
+## 8. 置顶与排序
+
+### 8.1 置顶
+
+置顶继续作用在首页会话项层级：
+
+- 单线程项目可置顶
+- 多线程项目文件夹也可置顶
+
+不在首页单独透出项目内部某个线程的置顶。
+
+### 8.2 排序
+
+排序规则改为基于首页会话项：
+
+- 单线程项目按自身最新回复时间排序
+- 多线程项目文件夹按聚合后的 `latestReplyAt` 排序
+
+### 8.3 置顶分组
+
+置顶会话分组仍保留，且可收起/展开。
+
+项目文件夹进入置顶组后，也按一个会话项处理，不在置顶组内再展开线程。
+
+## 9. 动态升降级规则
+
+### 9.1 1 线程 -> 2 线程
+
+当项目线程数从 1 增加到 2 或以上时：
+
+- 首页要自动从“单线程直显”升级为“项目文件夹会话”
+- 不要求用户手工刷新结构认知
+
+### 9.2 2 线程 -> 1 线程
+
+当项目线程数从 2 或以上降到 1 时：
+
+- 首页要自动从“项目文件夹会话”降回“单线程直显”
+
+### 9.3 缺少可归档标识
+
+如果线程没有可稳定归属的 `folderName / codexFolderRef`：
+
+- 不强行归档到项目文件夹
+- 继续按单线程处理
+
+宁可少聚合，也不要错误聚合。
+
+## 10. 数据模型与投影调整
+
+### 10.1 投影层
+
+会话首页投影需要明确支持两类项目型项：
+
+- `single_device`
+- `folder_archive`
+
+`folder_archive` 需要补齐或稳定这些字段：
+
+- `folderKey`
+- `threadCount`
+- `threadTitle`
+- `latestReplyAt`
+- `preview`
+- `contextBudgetIndicator`
+- `activityIconCount`
+
+### 10.2 Android 首页渲染
+
+Android 首页渲染应按投影类型分流：
+
+- `single_device`：走线程会话行
+- `folder_archive`：走项目文件夹会话行
+
+文件夹会话行和线程会话行应共享大部分微信式会话行样式，只在文案语义上区分。
+
+## 11. 回归要求
+
+必须覆盖这些场景：
+
+1. 单线程项目：首页直接显示线程
+2. 多线程项目：首页显示项目文件夹
+3. 文件夹项的时间取内部最新线程
+4. 文件夹项的预览取内部最新回复
+5. 文件夹项的上下文环取最需要关注线程
+6. 项目线程数从 1 变 2，首页自动升级为文件夹
+7. 项目线程数从 2 变 1，首页自动降回单线程
+8. 搜索命中多线程项目里的线程，点击后可进入文件夹并定位线程
+9. 置顶分组和项目文件夹共存正常
+10. 空闲项目文件夹不持续闪活动点
+
+## 12. 实现范围
+
+本轮一次完成：
+
+1. 服务端投影层：多线程项目聚合为项目文件夹会话
+2. Android 会话首页：按新投影渲染
+3. Android 搜索：保留线程可达性，但保持文件夹心智
+4. 项目文件夹页：继续复用现有线程列表页并收平语义
+5. 回归测试：覆盖聚合、搜索、升降级、置顶与活动状态
+
+## 13. 不采用的方案
+
+### 13.1 首页直接展开/收起项目内线程
+
+不采用原因：
+
+- 首页会很长
+- 层级更重
+- 微信感会被削弱
+
+### 13.2 顶部项目抽屉，下方只显示当前项目线程
+
+不采用原因：
+
+- 更像项目管理器而不是会话列表
+- 会削弱“聊天首页”的直觉
+
+### 13.3 让项目内部某个线程长期透出到首页
+
+不采用原因：
+
+- 会破坏项目文件夹心智
+- 首页结构会重新变乱
+
+## 14. 最终结论
+
+首页最终采用：
+
+- 单线程项目：直接显示线程
+- 多线程项目：显示项目文件夹会话
+- 文件夹会话：
+  - 时间取最新线程
+  - 预览取最新回复
+  - 上下文环取最需关注线程
+  - 副标题带 `N 个线程 · 最近：某线程`
+
+这套方案最符合“微信式首页 + 项目文件夹心智”的目标，也能在不重做聊天详情页的前提下，把多线程项目的结构真正收清楚。