krisolo/boss
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
36a2cd8dfd691f86a228a2e183cf5543d9ec1f82
boss/docs/source-material/wechat_project_conversation_mapping_cn.md
kris 90cb6b7ff1 feat: ship native boss android console
2026-03-26 23:16:56 +08:00

19 KiB
Raw Blame History

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

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

视觉对标：

适用范围：

  • 手机 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