From 23db05a99d6a1e88cf9f2dec92df7e4c0d53418e Mon Sep 17 00:00:00 2001 From: Manus AI Date: Sun, 26 Jul 2026 16:13:49 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=94=B6=E5=8F=A3SOUL=E4=B8=BA?= =?UTF-8?q?=E5=94=AF=E4=B8=80=E9=9C=80=E6=B1=82=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- 开发文档/00、简洁入口/01、产品与需求.md | 2 +- .../SOUL派对本机材料与APP能力调研_20260726.md | 42 ---------- 开发文档/1、需求/README.md | 6 +- ...成员运营模块_需求文档_20260726.md => SOUL需求文档.md} | 76 ++++++++++++++++++- 开发文档/1、需求/索引.md | 5 +- 开发文档/功能迭代记录.md | 15 ++++ 6 files changed, 97 insertions(+), 49 deletions(-) delete mode 100644 开发文档/1、需求/03-调研/SOUL派对本机材料与APP能力调研_20260726.md rename 开发文档/1、需求/{02-业务/SOUL派对成员运营模块_需求文档_20260726.md => SOUL需求文档.md} (68%) diff --git a/开发文档/00、简洁入口/01、产品与需求.md b/开发文档/00、简洁入口/01、产品与需求.md index 4d2a0a8f74..fa75a9bc70 100644 --- a/开发文档/00、简洁入口/01、产品与需求.md +++ b/开发文档/00、简洁入口/01、产品与需求.md @@ -7,7 +7,7 @@ | P0 | [当前需求真源](../1、需求/修改/工作手机_进行中_20260613.md) | 唯一进行中需求与完成判定 | | P0 | [产品总方案](../3、原型/工作手机全产品设计_20260722/产品总方案.md) | 产品定位、范围、版本和研发拆分 | | P0 | [可点击原型](../3、原型/工作手机全产品设计_20260722/可浏览高保真原型.html) | 页面评审 | -| P0 | [SOUL派对成员运营模块需求](../1、需求/02-业务/SOUL派对成员运营模块_需求文档_20260726.md) | 成员登记、欢迎内容、统计与房主关系；主责火炬 | +| P0 | [SOUL需求文档](../1、需求/SOUL需求文档.md) | 成员登记、欢迎内容、统计与房主关系；主责火炬 | | P1 | [业务需求](../1、需求/02-业务/业务需求.md) | 业务背景和完整能力范围 | ## 产品设计附件 diff --git a/开发文档/1、需求/03-调研/SOUL派对本机材料与APP能力调研_20260726.md b/开发文档/1、需求/03-调研/SOUL派对本机材料与APP能力调研_20260726.md deleted file mode 100644 index e71193747a..0000000000 --- a/开发文档/1、需求/03-调研/SOUL派对本机材料与APP能力调研_20260726.md +++ /dev/null @@ -1,42 +0,0 @@ -# SOUL派对本机材料与APP能力调研 - -- 调研日期：2026-07-26 -- 归属模块：工作手机 → **SOUL派对成员运营模块**（与微信模块独立） -- 产品负责人：水泉 -- 开发主责：火炬 -- 结论状态：用于需求设计；涉及实际连接、消息投递、成员资料读取的能力均需在真实账号与真实房间逐项验收。 - -## 一、已盘点材料 - -| 材料组 | 已确认内容 | 对本模块的价值 | -|---|---|---| -| 派对转写 | 本机存在多场派对转写、团队会议及内容分发记录 | 可用于定义房间、进房、发言、重复进入等事件口径 | -| 成员画像材料 | `卡若_人物与属性_soul文件夹.md` | 证明“基于可见行为+公开资料形成标签”的画像方式可落地 | -| 语料统计 | 历史统计覆盖289份文件、约993万字符 | 可作为AI标签、话题、意图识别的离线训练与评测样本 | -| 运营方法论 | 派对房文章强调问题分轨、承诺兑现、回访和转化指标 | 用于设计成员分层、欢迎内容和转化漏斗 | -| 卡若AI派对工作流 | 已有派对运营、内容、素材、报表及三端开发分流 | 本模块只新增“进房成员运营”，不替换既有运营流水线 | - -## 二、APP本机安装与功能线索 - -| 项目 | 调研结果 | 需求映射 | -|---|---|---| -| 桌面安装 | `/Applications/SOUL.app` 为PlayCover包装，实际包为 `Wrapper/Soul_New.app` | 真机/桌面端验收均需记录运行环境 | -| 派对能力 | 包内存在 `ClubParty.bundle`、`ChatRoom.bundle` | 以“房间、成员、进房事件、发言事件”为领域对象 | -| 私信能力 | 包内存在 `PrivateChat.bundle` | 以“欢迎内容任务、投递回执、回复事件”为领域对象 | -| 内容能力 | 包内存在 `Publish.bundle`、`AIGC.bundle` | 欢迎素材可引用文字、图片或活动卡片 | -| 账号与消息 | 存在推送扩展、分享扩展、群容器目录 | 账号切换、通知和授权状态需纳入验收 | - -## 三、能力分级 - -| 等级 | 能力 | 当前状态 | -|---|---|---| -| A：已确认领域存在 | 派对房、成员、私信、内容/图片、通知、分享 | 由本机安装包模块和历史派对材料共同确认 | -| B：需真实环境验收 | 成员进房实时事件、成员资料字段、私信发送/送达/回复、重复进房统计 | 列为火炬P0技术验证 | -| C：暂不纳入 | 微信联系人、微信消息、微信朋友圈、微信二维码 | 明确归微信模块，SOUL模块不得复用或写入 | - -## 四、调研结论 - -1. 本模块适合采用“事件采集 → 成员登记 → AI标签 → 欢迎内容任务 → 回执统计 → 房主关系图谱”的独立闭环。 -2. 先做成员登记和统计，再接欢迎内容；任何写动作须有任务、回执、频次和失败原因。 -3. 人员画像只保留业务相关、可解释的标签和来源，不把推断当作事实。 -4. 单个成员、多次进房、多个房主之间必须以统一成员主键和关系表去重，才能支撑月1～2万人规模。 diff --git a/开发文档/1、需求/README.md b/开发文档/1、需求/README.md index 572736acb3..fb75d845ee 100644 --- a/开发文档/1、需求/README.md +++ b/开发文档/1、需求/README.md @@ -2,7 +2,10 @@ # 1、需求 -**规则**：`modify/` **仅 1 篇**进行中真源；**总纲** → [全项目 §〇](../../../cunkebao_v3/开发文档/1、需求/修改/全项目_进行中_20260613.md)（四端互通 · 每轮必读 · 需求互传） +> **SOUL唯一需求入口**：[SOUL需求文档](SOUL需求文档.md)（后续SOUL功能统一追加此处） + + +**规则**：`modify/` **仅 1 篇**进行中真源；**总纲** → [工作手机当前需求](./修改/工作手机_进行中_20260613.md)（四端互通 · 每轮必读 · 需求互传） --- @@ -22,6 +25,7 @@ 1、需求/ ├── 索引.md ├── README.md +├── SOUL需求文档.md ← SOUL功能唯一需求真源 ├── 01-概述/ 项目概述（背景） ├── 02-业务/ 业务需求（MVP + 对话沉淀归档） ├── 03-调研/ diff --git a/开发文档/1、需求/02-业务/SOUL派对成员运营模块_需求文档_20260726.md b/开发文档/1、需求/SOUL需求文档.md similarity index 68% rename from 开发文档/1、需求/02-业务/SOUL派对成员运营模块_需求文档_20260726.md rename to 开发文档/1、需求/SOUL需求文档.md index 93b6bf736c..900a0af61e 100644 --- a/开发文档/1、需求/02-业务/SOUL派对成员运营模块_需求文档_20260726.md +++ b/开发文档/1、需求/SOUL需求文档.md @@ -1,6 +1,67 @@ -# SOUL派对成员运营模块｜需求文档 +# SOUL需求文档 + +> **唯一需求真源**：所有SOUL功能、调研结论、开发计划、接口验收和后续迭代统一追加到本文件；不在子目录新建SOUL需求文档。 +> +> **模块边界**：SOUL功能独立于微信功能。SOUL数据、接口、任务和统计独立管理，不写入微信功能链路。 +> +> **开发主责**：火炬。 + +## 文档使用规则 + +1. 新功能按“需求背景 → 功能规则 → 数据字段 → 验收标准 → 变更记录”追加到本文。 +2. 调研材料只提炼结论与来源；原始材料继续留在本机资料库。 +3. 每个功能用状态标记：`待验证`、`待开发`、`开发中`、`已验收`。 +4. 真实环境字段、消息回执和统计数据以火炬验收记录为准。 + +## 一、调研基础与已确认线索 + + +- 调研日期：2026-07-26 +- 归属：工作手机 → **SOUL派对成员运营功能**（与微信功能独立） +- 产品负责人：水泉 +- 开发主责：火炬 +- 结论状态：用于需求设计；涉及实际连接、消息投递、成员资料读取的能力均需在真实账号与真实房间逐项验收。 + +### 1.1 已盘点材料 + +| 材料组 | 已确认内容 | 对本模块的价值 | +|---|---|---| +| 派对转写 | 本机存在多场派对转写、团队会议及内容分发记录 | 可用于定义房间、进房、发言、重复进入等事件口径 | +| 成员画像材料 | `卡若_人物与属性_soul文件夹.md` | 证明“基于可见行为+公开资料形成标签”的画像方式可落地 | +| 语料统计 | 历史统计覆盖289份文件、约993万字符 | 可作为AI标签、话题、意图识别的离线训练与评测样本 | +| 运营方法论 | 派对房文章强调问题分轨、承诺兑现、回访和转化指标 | 用于设计成员分层、欢迎内容和转化漏斗 | +| 卡若AI派对工作流 | 已有派对运营、内容、素材、报表及三端开发分流 | 本模块只新增“进房成员运营”，不替换既有运营流水线 | + +### 1.2 APP本机安装与功能线索 + +| 项目 | 调研结果 | 需求映射 | +|---|---|---| +| 桌面安装 | `/Applications/SOUL.app` 为PlayCover包装，实际包为 `Wrapper/Soul_New.app` | 真机/桌面端验收均需记录运行环境 | +| 派对能力 | 包内存在 `ClubParty.bundle`、`ChatRoom.bundle` | 以“房间、成员、进房事件、发言事件”为领域对象 | +| 私信能力 | 包内存在 `PrivateChat.bundle` | 以“欢迎内容任务、投递回执、回复事件”为领域对象 | +| 内容能力 | 包内存在 `Publish.bundle`、`AIGC.bundle` | 欢迎素材可引用文字、图片或活动卡片 | +| 账号与消息 | 存在推送扩展、分享扩展、群容器目录 | 账号切换、通知和授权状态需纳入验收 | + +### 1.3 能力分级 + +| 等级 | 能力 | 当前状态 | +|---|---|---| +| A：已确认领域存在 | 派对房、成员、私信、内容/图片、通知、分享 | 由本机安装包模块和历史派对材料共同确认 | +| B：需真实环境验收 | 成员进房实时事件、成员资料字段、私信发送/送达/回复、重复进房统计 | 列为火炬P0技术验证 | +| C：暂不纳入 | 微信联系人、微信消息、微信朋友圈、微信二维码 | 明确归微信模块，SOUL模块不得复用或写入 | + +### 1.4 调研结论 + +1. 本模块适合采用“事件采集 → 成员登记 → AI标签 → 欢迎内容任务 → 回执统计 → 房主关系图谱”的独立闭环。 +2. 先做成员登记和统计，再接欢迎内容；任何写动作须有任务、回执、频次和失败原因。 +3. 人员画像只保留业务相关、可解释的标签和来源，不把推断当作事实。 +4. 单个成员、多次进房、多个房主之间必须以统一成员主键和关系表去重，才能支撑月1～2万人规模。 + + +--- + +## 二、产品需求 -> **模块边界**：本模块属于工作手机项目，但独立于微信模块；只处理SOUL派对房的成员登记、欢迎内容任务、互动回执、数据统计和房主关系。微信账号、微信联系人、微信消息、微信朋友圈均不在本需求范围。 | 项目 | 内容 | |---|---| @@ -173,3 +234,14 @@ AI只基于可见资料和房间行为生成**可解释标签**，每条标签 - 不替代现有SOUL内容生产、视频切片、素材分发和文章发布工作流。 - 不将成员资料同步到微信模块。 - 不以未经验证的推断替代成员事实。 + + +--- + +## 三、后续功能追加区 + +> 后续任何SOUL需求在本节新增，保留日期、负责人、状态和验收标准，不另建SOUL需求文件。 + +| 日期 | 功能 | 主责 | 状态 | 验收证据 | +|---|---|---|---|---| +| 2026-07-26 | 派对成员登记、欢迎内容、统计与关系图谱 | 火炬 | 待开发 | S0真实字段验证待补 | diff --git a/开发文档/1、需求/索引.md b/开发文档/1、需求/索引.md index f9a02c7b74..9454ab380d 100644 --- a/开发文档/1、需求/索引.md +++ b/开发文档/1、需求/索引.md @@ -14,12 +14,11 @@ --- -## 新模块（20260726） +## SOUL需求（唯一入口） | 文档 | 说明 | 主责 | |---|---|---| -| [SOUL派对成员运营模块需求](./02-业务/SOUL派对成员运营模块_需求文档_20260726.md) | 成员登记、欢迎内容、数据统计、房主关系图谱；与微信模块隔离 | 火炬 | -| [SOUL本机材料与APP能力调研](./03-调研/SOUL派对本机材料与APP能力调研_20260726.md) | 本机资料、APP模块线索、能力分级和验收边界 | 水泉/火炬 | +| [SOUL需求文档](./SOUL需求文档.md) | 派对成员登记、欢迎内容、数据统计、房主关系、调研结论与后续功能统一追加 | 火炬 | ## 已完成归档 diff --git a/开发文档/功能迭代记录.md b/开发文档/功能迭代记录.md index bc8ee7497a..d85dddde4f 100644 --- a/开发文档/功能迭代记录.md +++ b/开发文档/功能迭代记录.md @@ -1331,3 +1331,18 @@ flowchart LR - SOUL模块与微信模块的数据、接口、任务队列明确隔离。 - 本机调研覆盖派对转写、成员画像、运营材料和SOUL桌面端安装包模块线索。 - 火炬负责S0字段验证、S1登记台、S2内容任务、S3看板、S4策略治理开发。 + +## 2026-07-26｜设备控制页 Hook 状态漂移与无线 Agent 别名修复 + +- **现象**：设备详情页显示 `Hook / Frida` 未注入，但 `/api/v3/devices/{device_id}/modules` 已返回 `supports_hook=true`、Frida `16.5.6`、Root 就绪，微信两个模块均为 `loaded`。 +- **根因**：设备列表使用 ADB serial `xgfe65eimrrofyws`，无线 Agent 注册使用另一逻辑 ID；连接优先级只按字符串精确匹配，并且仅看 Agent 基础 capabilities，忽略了已确认的模块探测回执。 +- **修复**：`sdk/app/services/connection_priority.py` 增加逻辑 ID/ADB serial/唯一设备型号三层匹配；Hook 状态在 Agent 未带 `hook` 字段时读取同一设备最新模块探测回执，避免状态漂移。 +- **验收**：本地 Docker `workphone-sdk` 重启后 `/health` 返回 `devices_online=1`；`/api/v3/connection/modes/xgfe65eimrrofyws?refresh=true` 返回首选 `Hook / Frida`、`Agent WebSocket` 在线；模块接口返回 Frida `16.5.6`、Root `true`、2 个微信模块 `loaded`；`hub.html` JavaScript 语法检查通过。 +- **控制链路**：实时画面与触控入口继续使用 `screen/remote.ws`，按钮动作沿用 Agent WS 优先路由；本轮未改业务按钮和动作协议。 +- **待补**：UI 树接口已返回 HTTP 200，但当前回执节点字段为空，需按 Agent 实际回执结构补齐前端节点计数与展示。 + +## 2026-07-26｜SOUL需求单文档收口 + +- 原“成员运营需求”和“本机材料调研”合并为`开发文档/1、需求/SOUL需求文档.md`。 +- SOUL后续功能、调研、验收和火炬开发任务只在该文档持续追加。 +- 删除两个子目录SOUL需求副本，避免功能分散和多真源。