boss/docs/architecture/wechat_project_conversation_mapping_cn.md

微信式项目会话与聊天页规格

这份文档用于冻结“第一屏 = 微信式会话列表”的产品逻辑，避免后续开发时又回到“移动控制台首页”的方向。

视觉对标：

• 微信 iPhone 版会话列表页的核心结构
• 官方来源：微信 App Store 页面

适用范围：

• 手机 App 第一屏
• 设备页（对应微信通讯录位置）
• 我的页（对应微信“我”）
• 项目聊天页
• 主 Agent 置顶会话
• 项目会话列表
• 设备头像 / 协作群聊头像
• 手动置顶
• 项目目标
• 版本迭代记录
• 图片 / 视频 / 语音输入
• 消息转发

---

1. 首页定位

首页不是“主 Agent 聊天正文页”。

首页应该是：

• 一个微信式的会话列表页
• 列表中的每一条会话都代表一个“项目对话”
• 列表顶部固定一条 主 Agent 会话
• 用户点击任意一条会话，再进入该项目的具体对话页

一句话定义：

第一屏 = 主 Agent 总会话 + 各项目会话列表

底部导航要求：

• 第一项：会话
• 第二项：设备
• 第三项：我的
• 呈现方式：微信式扁平底栏，图标在上 / 文案在下 / 激活项使用微信绿

其中第二项 设备 对应微信中的“通讯录”位置。 第三项 我的 对应微信中的“我”。 项目入口不再占据底部一级导航，而是从 会话 首页进入。

---

2. 项目会话与设备项目文件夹的映射规则

每一个项目会话必须和设备端 GUI 界面里的项目文件夹一一对应。

映射规则如下：

1. 每台接入设备启动 worker-daemon 后，扫描并注册本机可见项目根目录。
2. 每个项目目录生成稳定的 project_folder_key。
3. 云端控制面把同名或同一仓库来源的文件夹，映射到同一个 project_id。
4. 主 Agent 不直接生成“虚拟项目名”，而是基于 project_id 做汇总。
5. 首页列表展示的项目会话标题，优先使用：
   • 项目显式别名
   • 仓库名 / 文件夹名
   • 最后回退到 project_id

必须满足：

• 一个项目会话能追溯到具体设备上的具体文件夹
• 进入项目详情时，能看到这个项目当前挂在哪些设备上

---

3. 会话列表项类型

首页列表至少包含 3 类会话项：

3.1 主 Agent 会话

规则：

• 永远固定在最上面
• 永远视为置顶
• 不允许取消置顶
• 头像使用独立主 Agent 头像
• 最新摘要由主 Agent 汇总生成

展示字段：

• 标题：主 Agent
• 摘要：项目汇总、风险提醒、待确认事项
• 时间：主 Agent 最后一次完成汇总的时间
• 标签：置顶

3.2 单设备项目会话

规则：

• 一个项目当前只由一台设备执行
• 列表头像使用该设备独立头像
• 摘要使用该设备最近一次返回给主控的有效摘要

展示字段：

• 标题：项目名
• 摘要：设备名 + 最新一句摘要
• 右侧第一行：若已置顶则显示 置顶，未置顶留白
• 右侧第二行：该设备对这个项目的最后回传时间
• 右侧第三行：背景信息窗口余量指示器（圆环进度标记 + 百分比）

3.3 多设备协作项目会话

规则：

• 一个项目已经进入多设备协作
• 列表头像使用“组合头像”
• 逻辑上等价于微信中的群聊

展示字段：

• 标题：项目名
• 摘要：设备A + 设备B + 最新一句协作摘要
• 右侧第一行：留白，除非用户手动置顶
• 右侧第二行：参与设备中最后一次回传时间的最大值
• 右侧第三行：不显示剩余使用量

---

4. 头像规则

4.1 单设备头像

每台设备必须有自己独立头像。

建议最小字段：

• device_id
• device_name
• device_type
• avatar_mode
• avatar_color
• avatar_label
• avatar_asset_url

优先级：

1. 设备自定义头像
2. 系统生成头像
3. 文本缩写头像

建议默认缩写：

• Mac Studio -> M
• Windows GPU -> W
• Cloud Worker -> C

4.2 群聊式组合头像

当项目由多台设备协作时：

• 使用组合头像
• MVP 阶段支持 2 设备叠放头像
• 后续可扩展到 3~4 设备拼接头像

组合规则：

• 2 设备：左右叠放
• 3 设备：主头像 + 右上 / 右下
• 超过 3 台时：显示 2~3 个头像 + +N

排序规则：

• 优先主执行设备
• 再按最近活跃度排序

---

5. 列表排序规则

首页排序不能只是项目创建时间排序。

排序必须按以下优先级：

1. 主 Agent 会话，永远第一
2. 用户手动置顶的项目会话
3. 未置顶项目，按 latest_reply_at DESC

其中：

• latest_reply_at = 该项目参与设备最后一次有效回传时间的最大值
• “有效回传”包括：
  • 线程摘要
  • 审计结论
  • 运维修复结果
  • 关键错误 / 告警事件

不应计入：

• 心跳包
• 纯监控噪声日志
• 无内容变化的重复状态刷新

---

6. 手动置顶规则

首页必须支持长按会话条置顶。

交互规则：

• 长按普通项目会话 -> 弹出操作菜单
• 菜单包含：
  • 置顶
  • 取消置顶
  • 标记已读
  • 查看项目详情

排序规则：

• 主 Agent 永远第一
• 用户置顶项目在主 Agent 之后
• 多个置顶项目按最近消息时间排序

注意：

• 主 Agent 不允许取消置顶
• 系统需要记录 manual_pinned = true/false

---

7. 首页列表项最小展示字段

每一条项目会话至少要有：

• conversation_id
• conversation_type
• project_id
• project_title
• avatar_render_model
• latest_summary
• latest_reply_at
• manual_pinned
• context_budget_remaining_pct
• context_budget_indicator_style
• context_budget_level
• compaction_expected_at
• unread_count
• risk_level
• active_device_count

可选增强字段：

• device_names_preview
• audit_pending_count
• ops_alert_count
• compaction_risk
• must_finish_before_compaction

---

8. 建议新增的数据对象

在现有 projects / threads / thread_events 之上，建议增加：

• project_conversations
• project_conversation_items
• project_conversation_participants
• device_avatars
• conversation_pin_state

8.1 project_conversations

核心字段：

• conversation_id
• project_id
• conversation_type (master / single_device / multi_device)
• title
• latest_summary
• latest_reply_at
• manual_pinned
• sort_bucket

8.2 project_conversation_participants

核心字段：

• conversation_id
• device_id
• role
• is_primary
• last_reply_at

8.3 conversation_pin_state

核心字段：

• conversation_id
• pin_type (system / manual)
• pinned_by
• pinned_at

---

9. 首页 UI 结构

建议结构：

1. 状态栏
2. 页面标题：会话
3. 搜索 / 说明条
4. 会话列表
5. 底部导航

会话列表项布局：

• 左侧：头像
• 中间：标题 + 最近摘要
• 右侧：三层信息轨

右侧三层信息轨规则：

• 第一层：置顶 标签；若未置顶则保留空白高度
• 第二层：最后一次有效会话时间
• 第三层：背景信息窗口余量指示器
• 群聊型项目会话不展示第三层额度信息

背景信息窗口余量指示器规则：

• 使用统一的小圆环进度标记 + 百分比数字
• 样式和设备端线程页保持一致，不允许手机端自行推导一套不同视觉
• 数据来源于设备端 worker-daemon 上报的线程上下文预算，而不是前端本地估算
• 指示器表达的是“当前线程在发生背景信息压缩前，还剩多少可安全使用空间”
• 该值越低，越需要主 Agent 在压缩前完成关键收尾、证据固化和线程交接

视觉要求：

• 更接近微信会话列表
• 不要做成项目管理后台
• 不要把大量设备、审计字段直接塞进首页列表
• 首页只保留最适合“扫一眼决定先点谁”的信息
• 对单设备项目允许展示轻量额度信息，但群聊型项目不显示额度
• 首页中的圆环指示器展示的是“线程上下文预算”，不是账号 5h / 7d 额度，两者不能混用

---

10.1 主 Agent 的上下文预算协作逻辑

这部分是整个系统里多线程协作的核心调度信号。

主 Agent 必须持续读取每个线程的：

• context_budget_remaining_pct
• context_budget_level
• compaction_expected_at
• must_finish_before_compaction

主 Agent 的默认策略：

• safe：>= 60%
  • 允许继续正常推进任务
• watch：40% ~ 59%
  • 不再给该线程追加大块背景信息
  • 要求该线程开始产出阶段摘要
• urgent：25% ~ 39%
  • 主 Agent 应优先让该线程完成当前原子子任务
  • 同时预创建下一条接力线程和 handoff 摘要
• critical：< 25%
  • 禁止继续扩张上下文
  • 主 Agent 必须优先触发“压缩前收尾”
  • 包括：补齐关键结论、未提交 patch、命令记录、测试结论、证据引用、未决问题

压缩前收尾的优先顺序：

1. 当前正在修改但尚未固化的代码和补丁
2. 解释问题所必需的命令、日志、文件路径和测试结果
3. 与下一线程交接有关的关键决策和未决问题
4. 硬件测试 / 多模态审计所需的证据引用

设计原则：

• 不要等发生 compaction 之后再补救
• 主 Agent 必须尽量在 compaction 之前完成关键任务或完成线程交接
• 首页会话列表里的圆环标记，必须能帮助用户和主 Agent 同时感知哪些项目最接近上下文风险边缘

---

10. 和整体系统设计的关系

这套首页设计不会改变整体架构，只改变第一屏的信息组织方式。

对应关系如下：

• projects 提供项目真相
• threads 提供线程真相
• thread_events 提供最近事件
• worker_account_bindings / gptpluscontrol 提供设备与账号状态
• project_conversations 负责把这些底层状态重组为“会话列表”

所以：

• 底层仍是多机多线程系统
• 首页表现层收敛成微信式会话列表
• 主 Agent 仍然是总入口
• 项目会话只是“主 Agent 汇总后暴露出来的二级会话壳”

---

11. 项目聊天页结构

点击首页任意项目会话后，进入“微信式聊天页”。

聊天页结构固定为：

1. 状态栏
2. 聊天页头部
3. 顶部能力入口
4. 消息流
5. 媒体 / 转发入口
6. 语音 / 文本输入区

页面要求：

• 尽量接近微信聊天详情页的层级和节奏
• 不显示底部 tab bar
• 重点是聊天，而不是后台字段

---

12. 顶部两个固定按钮

项目名称下面必须增加两个并列按钮。

布局要求：

• 同一行
• 横向总宽度 100%
• 两个按钮各占一半宽度

按钮定义：

• 项目目标
• 版本迭代记录

---

13. 项目目标规则

项目目标 的生成和维护规则：

• 初始目标由用户和主 Agent 沟通后创建
• 主 Agent 负责整理成结构化目标
• 用户允许手动编辑
• UI 以“圆形单选式完成标记”展示每一条目标
• 用户或主 Agent 将目标标记完成后，目标正文自动加删除线
• 主 Agent 根据项目目标做任务拆解、督促和规划
• 各线程都要以项目目标为约束执行开发和测试

建议数据对象：

• project_goals
• project_goal_revisions
• project_goal_items
• project_goal_completion_logs

核心字段：

• project_id
• goal_title
• goal_body
• goal_order
• display_style (radio_checklist)
• completion_state (pending / completed)
• completed_by
• completed_at
• source (human / master_agent)
• is_active
• edited_by
• edited_at

权限规则：

• 用户可编辑
• 用户可标记目标已完成
• 主 Agent 可整理和建议修改
• 主 Agent 可复核目标完成状态并修正排序
• 普通 worker 线程不能直接改项目目标

13.1 项目目标页交互

项目目标页必须明确体现以下交互：

• 每条目标左侧使用圆形单选式完成标记
• 标记完成后，当前目标正文自动加删除线
• 已完成目标显示 已完成 状态和完成时间
• 未完成目标显示 进行中 或 待处理
• 顶部仍保留 编辑目标 入口
• 编辑目标 只允许用户和主 Agent 修改目标内容
• 普通 worker 线程只能读取，不可直接改写

---

14. 版本迭代记录规则

版本迭代记录 的生成和维护规则：

• 由主 Agent 监督各项目进程
• 定期自动汇报每一个版本号更新的内容
• 主 Agent 负责校验各线程提交上来的版本更新记录是否准确
• 版本迭代记录是只读记录
• 用户不能直接编辑版本记录正文

建议数据对象：

• version_iteration_reports
• version_iteration_sources
• version_iteration_reviews

核心字段：

• project_id
• version_name
• change_summary
• source_thread_ids
• generated_by
• verified_by_master
• published_at

权限规则：

• 主 Agent 可生成 / 复核 / 发布
• 用户可查看
• 用户不可直接改正文
• worker 线程只能提交候选更新，不可直接发布

---

15. 聊天能力范围

项目聊天页必须支持：

• 文本输入
• 语音输入
• 图片发送
• 视频发送
• 图片 / 视频 / 文本转发到其他聊天窗口

建议最小对象：

• conversation_messages
• message_attachments
• message_forwards

其中：

• message_attachments 支持 image / video / file / voice
• message_forwards 必须记录：
  • source_conversation_id
  • target_conversation_id
  • message_id
  • forwarded_by
  • forwarded_at

---

16. 设备页规格

设备页对应底部第二个导航项，位置等价于微信的“通讯录”。

功能目标：

• 展示当前已接入设备
• 展示各设备登录账号
• 展示各设备当前运行项目
• 展示各设备剩余额度
• 支持新增设备
• 支持设备管理

16.1 页面结构

设备页结构固定为：

1. 状态栏
2. 页面标题：设备
3. 右上角 + 添加
4. 长按操作提示
5. 设备列表
6. 底部导航

16.2 列表项最小字段

每一台设备至少展示：

• device_name
• device_avatar
• account_display_name
• running_projects_summary
• quota_5h_remaining
• quota_7d_remaining
• device_status

16.3 设备状态颜色

状态必须显式展示为圆点或小标记：

• 绿色：设备在线
• 红色：设备异常
• 灰色：设备掉线

建议枚举：

• online
• abnormal
• offline

16.4 新增设备

交互要求：

• 右上角点击 + 添加
• 打开新增设备流程
• 可进入：
  • 新设备绑定
  • 登录引导
  • token / pairing code 绑定

16.5 长按设备

长按任意设备条目，弹出操作菜单：

• 编辑设备名称
• 编辑设备头像
• 解绑设备

16.6 建议新增数据对象

建议增加：

• device_profiles
• device_status_snapshots
• device_project_bindings

核心字段建议：

• device_id
• device_name
• device_avatar_url
• device_type
• status
• account_id
• quota_5h_remaining
• quota_7d_remaining
• last_seen_at

---

17. 我的页规格

我的页对应底部第三个导航项，位置等价于微信的“我”。

功能目标：

• 展示用户头像
• 展示账号名称
• 展示账号唯一二维码入口
• 展示账号与安全
• 展示设置
• 展示 运维与修复 入口
• 展示关于 / 版本号 / OTA 更新

17.1 页面结构

我的页结构固定为：

1. 状态栏
2. 用户信息头部
3. 功能列表
4. 关于 及 OTA 红点
5. OTA 更新内容区
6. 底部导航

17.2 头部信息

头部至少展示：

• 用户头像
• 用户昵称 / 显示名
• 当前账号类型
• 右侧 唯一二维码 入口

二维码入口呈现规则：

• 放在头部信息卡的最右侧
• 以微信式小二维码图标呈现
• 与头像、昵称、账号类型处于同一个头部单元中
• 不再单独占一行文字说明

17.3 账号与安全

账号与安全页项的职责：

• 修改账号密码
• 设备安全管理
• 身份校验

MVP 要求：

• 当前先只冻结入口和字段
• 后续二级页再开发

17.4 设置

设置在当前版本只保留一级入口。

规则：

• 先展示
• 暂不开发二级页

17.5 关于与 OTA

关于项必须展示：

• 当前版本号
• 若有新 OTA，右侧显示红色 OTA 提示

点击后行为：

• 展示 OTA 更新内容
• 可触发 立即 OTA

17.6 OTA 更新内容区

更新内容区必须包含：

• 目标版本号
• 更新点摘要
• 立即 OTA 按钮

建议新增数据对象：

• user_profiles
• app_versions
• ota_updates
• ota_update_logs

建议字段：

• current_version
• target_ota_version
• has_ota_update
• ota_update_summary
• ota_update_status
• ota_triggered_at

17.7 账号认证页

移动端必须补齐 3 个账号认证页面：

• 登录页
• 注册页
• 忘记密码页

认证页规则：

• 登录页 必须支持账号、密码、登录验证码
• 注册页 必须支持账号、登录验证码、密码、确认密码
• 忘记密码页 必须支持账号、登录验证码、新密码、确认新密码
• 3 个页面都要提供 发送验证码
• 登录验证码和找回验证码都必须进入后端校验链路
• 登录成功后才允许继续设备绑定与项目同步
• 重置密码成功后，旧设备登录态允许被系统要求重新校验

---

18. 已冻结的二级页面

为了避免开发时只做一级页壳子，下面这些二级页也已经纳入 UI 范围：

• 项目目标页
• 版本迭代记录页
• 转发到项目页
• 添加设备页
• 设备长按操作菜单
• 账号与安全页
• 关于 / OTA 页
• 登录页
• 注册页
• 忘记密码页

这些页面的目标是：

• 保持微信式的导航和扁平视觉
• 不把复杂系统状态直接做成后台面板
• 每个子页面都能对应明确的数据对象和入口来源
• 其中 运维与修复 必须作为 我的 页里的二级入口，不再作为底部一级导航
• 运维与修复 内部再分为 运维对话 和 审计对话 两个子页

---

18. UI 上不直接暴露的后台逻辑

虽然聊天页外观接近微信，但底层仍然是多线程系统。

所以：

• 首页看到的是项目会话
• 聊天页看到的是主 Agent 汇总后的项目聊天流
• 底层真实 worker 线程、审计线程、运维线程仍继续工作
• 主 Agent 把底层线程状态整理成适合聊天页展示的消息

换句话说：

UI 上是聊天，系统里仍然是多线程编排

---

19. 当前 UI 原型对应

当前原型已按这套规则重绘整套核心页面：

• 主 Agent 置顶
• 单设备头像
• 双设备协作头像
• 手动置顶示例
• 会话按最近消息排序
• 项目聊天页双按钮
• 项目目标页圆形完成标记 + 自动划线
• 版本迭代记录只读展示
• 图片 / 视频 / 转发入口
• 语音输入入口
• 设备页第二导航位
• 设备在线 / 异常 / 掉线三种状态
• 右上角添加设备
• 长按设备管理提示
• 我的页第三导航位
• 账号与安全入口
• 设置入口
• 关于 + OTA 红点
• OTA 更新内容卡片
• 登录页 / 注册页 / 忘记密码页
• 登录验证码发送入口

对应文件：

• /Users/kris/code/UI/.runtime/pencil/threads/ui-codex-ops-mobile/outputs/codex-ops-mobile-v1.pen
• /Users/kris/code/Talking/output/ui-codex-ops-mobile-v13/d5gpt.png
• /Users/kris/code/Talking/output/ui-codex-ops-mobile-v13/g8Qpr.png
• /Users/kris/code/Talking/output/ui-codex-ops-mobile-v13/CwqbE.png
• /Users/kris/code/Talking/output/ui-codex-ops-mobile-v13/i7IZ1.png