feat: ship native boss android console

docs/source-material/wechat_project_conversation_mapping_cn.md

@@ -0,0 +1,853 @@
+# 微信式项目会话与聊天页规格
+
+这份文档用于冻结“第一屏 = 微信式会话列表”的产品逻辑，避免后续开发时又回到“移动控制台首页”的方向。
+
+视觉对标：
+
+- 微信 iPhone 版会话列表页的核心结构
+- 官方来源：[微信 App Store 页面](https://apps.apple.com/cn/app/id414478124)
+
+适用范围：
+
+- 手机 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`