面向想参与 WeQ 开发的贡献者。
pnpm i
pnpm native:fetch # 取 nt_helper 原生产物（不入库，新克隆里没有）
pnpm dev仅使用根 package.json 的 packageManager 所锁定的 pnpm；环境与门禁按贡献指南。以下按主题查阅，不必先读全部专题。
本文按当前分支提供导航；带日期的专题保留当时方案和验证记录，不将待办或历史测试回执当成 当前发布状态。用户操作路径以使用手册和设置总览为准。
- 界面与工具设计约定：内容优先、选择草稿、任务身份和平台边界。
- 内容能力与缺口：区分已接入父级与尚未覆盖的子内容。
- 语音通话：私聊主动发起的三层协议（信令 / GCS / Opus）、编解码来源与能力边界。
- 视频通话：视频信令档位、H.265 媒体包格式、摄像头开关控制包与保活。
- 视频编码 t265：QQ 自带魔改 x265 的探测结果（参数结构体已逆出，图像结构体待 IDA）。
- 选择、搜索与导出契约：精确范围、确认冻结、保存策略与请求隔离。
- 保存位置逻辑简化：单文件另存、结果保留及全局偏好／菜单改造的阶段边界。
- 目录选择与本地备份导入：分层/递归扫描、独立位置记忆、三端账号目录、备份媒体与其他设备密钥复用。
- 联系人精确导出：好友/群多选交接、精确 UID、完整目录与任务快照。
- 生成内容精确导出：克隆与助手的持久身份、独立快照、原始结构及账号边界。
- 克隆会话复用普通页面：共用 ChatPane、数据身份与能力适配、原位设置和浮层层级。
- 空间精确导出：离散 tid、正文/互动/媒体范围、统一入口及历史隔离。
- 全局搜索新增来源：来源覆盖、账号缓存、频道全库与稳定条目跳转。
- 全局搜索优化：当前可见分类、会话来源范围、分类并行返回、匹配度排序与尚未实施的性能优化方向。
- 分析与报告：统计口径、历史身份、结果生命周期和恢复限制。
- 推荐回复上下文：时间与近期优先、成员和 @ 身份、自己发言后的接续模式。
- 窗口与浮层：页面、侧栏、浮窗、锚定窗格与模态层的职责。
- 设置重构执行方案：分阶段设计与验证记录；当前七组目录以设置总览和
settings/navigation.ts为准。 - 页面现场保留：活动性、隐藏页监听与内存状态边界。
- 原生 QQ 邮箱：账号级认证、邮件协议、附件、正文隔离与提醒生命周期。
- 手机连接与重连：局域网、已有/内嵌 TS、持久设备凭据和 iOS WebView 会话身份。
- Remote 手机壳独立仓库：手机源码、构建和协议测试的维护边界与电脑夹具入口。
- Web / Remote 功能对齐：浏览器文件发送、手机资料入口、内置 Web 报告捕获与独立 Node 部署限制。
- Web / Remote 体验优化：重连反馈、活动查询补查、手机导航与重型工作区按需加载。
- 会话分析时间轴 + 我的主场轮盘 — 默认最近一年、拖动重算、全历史绿墙与群聊卡片轮盘的翻页守卫
- 引用、提及与 +1：唯一身份剪贴板、当前账号名称解析与相同消息重发
- 多选修饰键与键盘契约：选择组、范围锚点、键盘隔离与业务限制。
- 合成工作区与归档：编辑记录、素材快照、独立媒体与账号绑定。
- SSO 历史路径统一 — 单窗读取、物理请求计数、旧任务及缓存兼容
- 批量漫游补缺：候选覆盖、持久预约与恢复。
- 漫游时间线：缓存混排与本地消息身份。
- 审计修复与权限边界：助手权限模式、隔离脚本、只读 MCP、权威数据保存及尚未完成的治理项。
- 审计第一批修复：导出 Bot 存储原件保护、私聊派生数据隔离与发布通知最小权限。
- 审计第二批修复：消息追加原子性、Bot 会话队列、停止收尾与非流式模型请求期限。
- 审计第三批修复：认证记录回收、链接预览内存预算与 Bot 默认日志隐私。
- 审计第四批修复：发布草稿至公开门禁、Web 冻结运行依赖与本地构建验证边界。
- 消息同步与性能修复方案及阶段实施记录：消息到达、QQ 已读消点、会话首屏与媒体的已实施范围，以及时间线虚拟化和真实性能验收待办。
- 消息性能修补：后续性能实现与针对性验证范围。
- 会话首屏请求与查询优化：消息请求分流、目录后台调度、旧窗口取消、漫游缓存合并查询与引用媒体后补。
- 页面回访与首包优化：数据结果缓存、收藏渐进显示、会话切换核算、模块拆分及导航意图预热。
- 首次进入会话优化：可见会话预取、在途接用与提级、分阶段正文交付及新增 UID 分区补查。
- 聊天图片预览缓存：解码内存预算、可见与离屏资源边界。
- 渲染资源生命周期、白屏定位、后台帧释放与自动恢复、原窗口现场恢复：资源释放、诊断与分阶段验证记录。
- 语音 worker 的 macOS 打包：子进程依赖与产物验证边界。
- 桌面包体积优化：生产依赖分层、原生架构裁剪、真实打包匹配器和产物冒烟。
- QQ 数据库布局：按文件设置保留页 — per-Pager pending byte、锁字节与布局自动识别
- nt_helper.node 接口文档 — 原生模块能力总览，写代码前先看，别重复造轮子
- 原生二进制与装扮资源的分发 —
pnpm native:fetch、发布链路、历史清洗记录 - 长期授权集成：权限助手协议、开发 / 正式通道、系统安装与 release 双产物校验。
- 大库密钥扫描修复：固定读取验证前缀、合成稀疏文件检查与本地产物边界。
- 测试约定 —
@weq/testkit - WeQ 存储管理：统计范围、嵌套目录去重、只读数据与缓存清理白名单。
- macOS QQ 进程探测：异步归属判断与子进程生命周期。
- Linux 窗口后端与 XWayland：为什么
ozone-platform必须走 Electron 启动参数，不能appendSwitch。 - 图文 Ark 卡片发送 — OIDB 0xdc2_34 的下发结果解析，以及 PC/Linux 端的已知实现缺口
- 推荐联系人 / 推荐群卡片 — 0x12b6_0 / 0x8b7_5 取卡 + PbSendMsg 直接发送（两步合一）
- AI 声聊 — 声线目录（OIDB 0x929d_0：分组 / 中文名 / 样音）与语音合成（0x929b_0），样音不入库
- 群报名 / 群收集表 — OIDB 0x921b_0 的字段布局、图片直链处理与已知缺口
- 发消息 —
MessageSvc.PbSendMsg+ 富媒体上传（NTV2/highway）+ 文件（群/私聊，老 OIDB + highway）、元素类型表、MCP 工具与已知缺口 - 本地文字识别模型：模型选型背景；当前识别与筛图配置见设置。
- 图片识别缓存原设计：历史方案，缓存已接入；当前实现查
packages/service/src/common/ocr_cache.ts及account/ocr_image.ts，不按旧“待实施”措辞重复开发。 - 词云 / 常用语的中文分词 — 接入 QQ 自带结巴词典与随包词典兜底，按词性过滤实词
- 主动操作类协议能力 — 群管理 / 群文件 / 群相册 / 群待办 / 收藏表情 / 请求处理 / 在线状态的命令、分层与签名判定
- 主动操作界面接入 — 原始候选与新增协议的入口、账号隔离、结果边界、通用加群及针对性验证。
- QQ 交互修复记录 — 免打扰未知态、画像雷达与在线状态 EOF 的字段证据和验证边界。
- 更新安装退出顺序 — 更新专用退出事件、窗口关闭偏好与安装错误恢复。
- macOS ad-hoc 更新安装：旧 cdhash 身份断点、官方资产校验、退出后替换与一次手动迁移。
- 外观优化进行中 — 主题可读色、公共控件与全应用验收矩阵；不代表整项已完成。
- Web 竖屏布局：手机主导航、整屏聊天、设置返回层级与可视视口适配。
- 群文件管理器 — 统一列表、来源绑定、拖拽、冲突检查与批次结果的实现边界。
- 页面自动更新 — 前台恢复、隐藏停轮询、读取重试与草稿保护。
- 群成员编辑入口 — 角色与目标身份、直接编辑及窗口边界。
- 失败发送占位移除 — 本机清理、确认状态保护、迟到回调与序号定位。
- 消息正确性与邮件导出修补：合成时间、逐条间隔、图文重编辑、设备未读、连续消息与图片资源生命周期。
- QQ 交互当前版本收尾：表情包、资料卡、独立修复窗、频道多选、自发缓存与混合消息操作的实现和验证边界。
- 数据库修复空间优化：中间件生命周期、分卷空间预算、独立缓存位置与备份保留。
- 模型温度参数回退：明确拒绝识别、JSON／SSE 重试边界、取消与物理用量记账。
- 备份与恢复：版本化格式、真实配置校验、冷启动事务、设置入口与按设备交接界面偏好。
- 消息选择与框选：临时预览、最终提交、稳定行尺寸、区间索引与长时间线定向性能回归。
- 群相册卡片导航：真实载荷关系、明确目标解析、来源绑定的相册／批次与评论视图。
- 贡献指南