509 lines
56 KiB
Markdown
509 lines
56 KiB
Markdown
# AI 获客助手整体方案
|
||
|
||
版本：v0.2
|
||
|
||
整理日期：2026 年 10 月 21 日
|
||
|
||
最近更新：2026 年 10 月 22 日，参考 A2A 学习端，将已有的参数化、验证和版本管理细化为有界学习闭环。
|
||
|
||
本轮补充：学习端使用独立验证记录库；平台账号由商家在官方页面自行登录，按账号复用本地浏览器资料并核验会话。
|
||
|
||
工程实施补充：`browser_use` 的桌面壳等仍按第 4.4 节评估；根据当前实施决定，学习后台以 `D:\qiekj\PenguinUniOS-Workspace\projects\learning` 的适用模块为基础裁剪，接入本项目独立的 PostgreSQL 与 Playwright 工作进程，见第 5.8 节。
|
||
|
||
状态：已进入本机学习与验证后台基建。方案中的商家桌面端、真实平台适配、AI 与商业模块仍是后续工作，不能将后台基础功能视为整个获客产品完成。已确认事项、实施建议和待验证选择在第 13 节分别记录。
|
||
|
||
维护约定：每轮实际进展与验证结果追加到 [开发进度](开发进度.md)；优化、设计决定和优先级维护在本方案，近期实施顺序见第 14 节。进度文档记录事实，不用规划替代完成证据。
|
||
|
||
交互图解：[方案图解](方案图解.html)，包含系统架构、获客流程、学习发布、AI 与额度、任务恢复、登录会话和实施阶段。设计调整时同步维护文字与图解。
|
||
|
||
## 1. 建议采用的整体路线
|
||
|
||
产品由三部分组成：**商家安装的桌面端、我们维护的学习与链路开发工具、云端 AI 与商业后台。**
|
||
|
||
桌面端负责账号登录、浏览器操作、任务运行和线索管理；学习工具负责把平台操作变成经过验证的能力包；云端负责模型调用、软件权益、订单和额度结算。
|
||
|
||
第一版明确同时适配 Windows 和 macOS，两端按同一业务范围开发、验证和发布。第一条学习链路已选定小红书「搜索笔记 → 详情 → 评论读取」；先验证本机演示页的基础链路，再由维护者在官方页面自行登录后进行实际适配。正式首发平台取决于验证结果，抖音、快手及手机执行端后续分别评估。
|
||
|
||
桌面框架采用 Electron，界面采用 React + TypeScript。浏览器侧以 Playwright 固定执行为主线，围绕当前产品需要设计能力契约、定位、等待和状态核验。当前已决定采用 A2A 学习后台的适用模块；其他 A2A 与 browser_use 资产仍按需选择。Midscene 是可选辅助组件，在出现明确定位或视觉需求后再对比引入，不作为首版必选依赖。
|
||
|
||
本地存储建议采用 SQLite，新增执行器建议采用 Node.js/TypeScript，云端数据库建议采用 PostgreSQL。云端可采用现有测试工程的 FastAPI 认证与管理骨架，再新增本项目的 AI、权益与计量模块；这项选择在基础模块提取验证后确定，不再将服务端统一使用 TypeScript 作为建议前提。实现选择以当前需求、验证效果和双端分发维护成本为依据；具体依赖版本在原型通过后固定。
|
||
|
||
模型由我们在运营后台按用途配置，客户端不绑定具体厂商或版本。基础分析优先验证较低成本模型，复杂复核和视觉操作分别配置，均有独立预算。
|
||
|
||
这是一套围绕获客业务组织的产品。正常运行的链路、参数和分支由程序控制，模型负责内容理解和少量需要重新理解页面的步骤。
|
||
|
||
## 2. 商家使用过程
|
||
|
||
1. 安装软件，登录我们平台的产品账号。
|
||
2. 添加平台账号，在软件打开的独立浏览器中自行扫码，或在平台官方页面输入手机号和验证码完成登录。软件核验登录状态和账号后保存本地账号映射；再次运行先检查原会话，失效时再请商家登录。
|
||
3. 创建商品档案：商品、使用场景、服务地区、客户类型和排除条件；未设置的地区等条件不自动补齐。
|
||
4. 配置搜索关键词或推荐流入口、任务范围、预算及跟进方式。
|
||
5. 启动任务，查看候选视频、主页判断、评论线索和筛选依据。
|
||
6. 对匹配对象执行配置的关注、私信及后续跟进任务，记录结果。
|
||
7. 查看任务报告、已用分析额度和后续回复。
|
||
|
||
第一版建议提供账号、商品档案、任务、线索、跟进、用量六个主要页面。链路开发和模型调试放在维护工具中，商家主要配置业务条件。
|
||
|
||
自动关注和私信继续保留为产品目标。研发顺序先验证发现与筛选，再验证跟进动作；首版正式开放范围依据验证结果确定。
|
||
|
||
## 3. 业务主流程
|
||
|
||
保留关键词搜索和推荐流浏览两个入口，首轮先完成搜索入口。内容判断后分成同行商家和采购方两条路径。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[商品与目标客户条件] --> B[搜索或浏览视频]
|
||
B --> C[内容相关性判断]
|
||
C -->|不相关| B
|
||
C -->|相关或需要上下文| D[读取主页与相关作品]
|
||
D --> E{账号角色与需求}
|
||
E -->|同行商家| F[读取相关视频评论及回复]
|
||
F --> G[评论采购意图判断]
|
||
E -->|作者有采购需求| H[核对需求与商品条件]
|
||
E -->|信息不足| I[待判断]
|
||
G --> J[线索去重与依据保存]
|
||
H --> J
|
||
J --> K[关注与私信任务]
|
||
K --> L[核对结果并记录后续回复]
|
||
```
|
||
|
||
内容相关不代表有采购意图。同行身份也不排除采购需求，例如面向经销商销售的商品。一个账号可以有多个角色标签，业务分支按当前需求决定。
|
||
|
||
## 4. 系统如何分工
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
subgraph DEV[维护者环境]
|
||
LEARN[限定目标并观察取证] --> KNOW[字段、状态、分支与缺口]
|
||
KNOW --> CANDIDATE[候选能力与验证用例]
|
||
CANDIDATE --> CHECK[固定规则校验]
|
||
CHECK --> VERIFY[变参试跑与结果核对]
|
||
VERIFY --> PKG[发布不可变能力版本]
|
||
VERIFY -. 验证失败后修订 .-> CANDIDATE
|
||
end
|
||
subgraph LOCAL[商家电脑]
|
||
UI[Electron 商家界面] --> RUN[任务与链路执行器]
|
||
RUN --> ADAPTER[平台适配器]
|
||
ADAPTER --> PW[Playwright 浏览器驱动]
|
||
PW --> BROWSER[按账号隔离的浏览器]
|
||
RUN --> DB[SQLite 任务与线索记录]
|
||
RUN -. 按需评估 .-> MS[可选 Midscene 辅助]
|
||
MS -.-> PW
|
||
end
|
||
subgraph CLOUD[云端服务]
|
||
API[账号与权益 API] --> LEDGER[订单与额度账本]
|
||
CONFIG[运营后台模型配置] --> AI
|
||
AI[AI 网关] --> MODEL[文本与视觉模型]
|
||
AI --> LEDGER
|
||
RELEASE[能力包与客户端版本发布]
|
||
end
|
||
PKG --> RELEASE
|
||
RELEASE --> RUN
|
||
RUN -. 失败证据回流维护端 .-> LEARN
|
||
UI --> API
|
||
RUN --> AI
|
||
MS --> AI
|
||
```
|
||
|
||
这张图表达职责，不表示首版需要拆成许多独立服务。云端可以先用一个应用和一个 PostgreSQL 实例；本地用一个桌面程序配独立执行进程。
|
||
|
||
### 4.1 桌面端
|
||
|
||
桌面采用 Electron，界面建议使用 React + TypeScript，Windows 和 macOS 共享界面、任务、平台链路及 AI 客户端代码；应用目录、系统凭据存储、进程管理、菜单快捷键、安装与升级通过小范围系统适配处理。界面用于配置、查看和接管；浏览器任务放到独立执行进程，避免耗时操作阻塞界面。新增执行代码建议采用 Node.js/TypeScript，界面通过受限 IPC 调用任务能力。只有某个外部组件有明确价值并通过验证时，才按需增加其他运行时和进程适配。
|
||
|
||
第一版建议控制独立、可见、可最大化的浏览器窗口。商家登录时像使用普通浏览器一样操作，登录完成后回到软件控制台。Electron 的界面窗口和被自动化控制的平台浏览器是两部分；后续若要将平台画面嵌入软件内容区，需要另行验证会话和执行器接入。
|
||
|
||
现有测试工程已实现 WebContentsView 宿主、面板布局和人工接管，因此将内嵌浏览器列为首版可验证的替代方案。先验证它与本项目固定执行器的接入、官方页面人工登录、账号会话复用、收起及截图行为，再决定是否采用；验证前保留独立窗口作为当前主线。采用其桌面壳不要求同时采用内嵌宿主、Python 本地后端或 browser-use Agent。
|
||
|
||
该进程划分参考 [Electron 官方进程模型](https://www.electronjs.org/docs/latest/tutorial/process-model)。打包、进程退出和浏览器生命周期都需要在 Windows 与 macOS 安装包中分别验证。
|
||
|
||
构建目标建议覆盖 Windows x64、macOS Apple Silicon（arm64）和 Intel（x64）。最低系统版本在锁定 Electron、Playwright 和浏览器版本后明确，以各依赖支持范围的交集为准，不直接承诺所有历史 Windows/macOS 版本。参考 [Electron 支持平台](https://github.com/electron/electron#platform-support)与 [Playwright 系统要求](https://playwright.dev/docs/intro#system-requirements)。
|
||
|
||
安装包按目标平台及架构产出，例如 Windows 安装程序和 macOS DMG。各端构建、签名与 macOS 公证、升级和回滚分别建立流水线；SQLite 等原生依赖和配套浏览器也按平台、架构准备。共享业务代码不意味着一份二进制安装包直接用于所有系统。分发方式参考 [Electron 官方打包说明](https://www.electronjs.org/docs/latest/tutorial/application-distribution)。
|
||
|
||
### 4.2 浏览器与账号
|
||
|
||
固定执行层负责打开页面、点击、输入、滚动、等待和读取，首选 Playwright，按本项目的能力契约封装与验证。一个运行会话明确由一个驱动持有。每个平台账号绑定独立的浏览器数据目录，保留其登录状态。产品账号、平台账号和浏览器目录分别建模。
|
||
|
||
**登录交互。** 商家在软件管理的浏览器中打开平台官方页面，自行扫码或输入手机号、验证码等登录信息。我们的产品账号界面不索取这些平台登录信息，也不代收验证码。登录阶段业务执行器暂停动作，商家持有操作权；登录判定只读取必要的已登录页面标志及账号标识。手机号、验证码和密码不进入业务数据库、日志、学习证据或模型输入。
|
||
|
||
**登录成功的判据。** 等待平台完成登录跳转，并检查可用的已登录页面标志和可靠账号标识，绑定到本地账号记录。二维码消失、登录弹窗关闭、已有 Cookie 或数据库上次记为已登录，都不能单独证明当前账号有效。身份不明、与任务预期账号不一致或仍需验证时，保持等待处理。具体判据按平台学习、验证和维护。
|
||
|
||
**登录后的窗口。** 首选在同一浏览器会话中从人工操作移交给执行器，登录完成后回到控制台；可最小化浏览器继续执行，提供重新显示和接管入口。最小化对视频加载、读取和任务推进的影响在 Windows/macOS 分别验证；未验证前保留可见执行方式。关闭整个浏览器会结束当前执行会话，运行端应暂停任务并保存检查点，不能把关闭窗口视为浏览器仍在执行。首版不将可见登录后自动切换无头运行作为默认流程。
|
||
|
||
**下次如何复用。** 每个账号分配固定的专用资料目录，使用 Playwright 的持久化上下文打开同一目录，保存浏览器支持持久化的 Cookie 和本地存储等资料。目录位于应用本地数据区，与安装目录分开；正常重启、任务结束和客户端升级保留目录。SQLite 保存账号标识、目录引用、会话状态和最后核验时间，平台登录资料由浏览器管理。
|
||
|
||
如采用内嵌浏览器，由 Electron 的稳定 `persist:` 会话分区保存资料，执行器连接该宿主的实际页面目标；上层仍按本地平台账号映射会话引用。独立浏览器目录和 Electron 分区是两种存储实现，不把登录页放在一个会话、执行页另建到空白会话，也不依赖复制两种实现的 Cookie 来切换。现有测试工程在新建会话时追加随机标识，需改为稳定的账号作用域，并保留身份核验、控制权与账号互斥规则。
|
||
|
||
新任务先复用已有浏览器会话；需要重开时先正常关闭并释放原会话，再用同一目录启动，打开页面核验账号和登录有效性。资料保留且平台会话有效时可直接执行，不需要每次重新扫码。平台会话到期、退出登录、资料清理或平台要求重新验证时，进入等待登录；不承诺永久免登录，也不设未经实测的有效天数。不同设备及 Windows/macOS 各自建立和验证会话，不将资料目录直接复制作为登录迁移方案。
|
||
|
||
一个平台账号同一时间由一个执行任务持有，暂停接管时移交控制权，避免人和执行器同时操作。同一数据目录不得被多个浏览器实例同时占用。
|
||
|
||
首版可先运行一个平台账号，但数据结构从开始就保留账号标识。登录失效进入等待登录状态，完成登录并核验身份后再继续。
|
||
|
||
浏览器通道与版本、视口和页面条件尽量保持可比较，优先复用两端相同的网页链路。字体、快捷键、缩放及平台页面差异仍需分别验证；存在必要差异时由适配层处理。首版浏览器控制不依赖全屏鼠标坐标或系统级桌面点击。
|
||
|
||
持久化目录与连接能力以 [Playwright 官方 BrowserType 文档](https://playwright.dev/docs/api/class-browsertype#browser-type-launch-persistent-context)为依据。首版使用专用目录，不依赖复制商家日常浏览器的整份资料。
|
||
|
||
登录资料复用仍需按真实平台验证；可复用状态与失效处理参考 [Playwright 身份状态文档](https://playwright.dev/docs/auth)。保存目录不保证所有内存或临时会话状态在重启后可用，重新打开后的有效性检查始终保留。
|
||
|
||
### 4.3 本地与云端的数据边界
|
||
|
||
商家端独立的业务 SQLite 保存平台账号映射、任务、检查点、候选内容、线索、证据及动作结果。账号映射包含浏览器目录或会话分区引用和最后核验状态；平台登录资料保留在对应本地浏览器资料中。维护者学习端使用独立 PostgreSQL 学习库和检索库，两端分别管理生命周期和数据，不共享商家登录资料。
|
||
|
||
云端 PostgreSQL 保存产品账号、设备权益、订单、额度账本、模型请求计量以及版本清单。模型分析按任务提交所需文本或图片。
|
||
|
||
第一版以本地线索为主，不默认建设全量线索同步。网页后台先服务产品管理、订单、用量和发布；如果后续要在手机上查看线索，再增加明确的线索同步功能。
|
||
|
||
学习维护所需的失败回流，首版通过诊断导出与维护端导入实现，内容限定为相关能力版本、必要输入、失败位置及对应页面证据片段。诊断资料和业务线索同步分别设计，浏览器登录资料仍保留在本地账号目录。
|
||
|
||
供应商模型密钥保存在服务端。客户端通过我们自己的 AI 网关调用模型，网关负责身份、模型路由、额度和请求预算。模型配置发布后有明确版本；客户端按业务用途调用，服务端记录实际使用的配置与模型。若引入 Midscene 或 browser_use 的模型调用，也接入这层网关，分别验证协议及模型适配兼容性。
|
||
|
||
### 4.4 测试工程可以采用哪些基础
|
||
|
||
2026 年 10 月 22 日只读核对 `D:\qiekj\browser_use` 当前工作区的源码、路由、数据结构、打包脚本与历史验证记录。该工程已有大量未提交修改，本次结论针对当前工作区；源码存在和历史通过记录不代表本轮重新验收通过。未修改源工程，未启动其服务、任务、数据库或平台账号。
|
||
|
||
**候选采用范围。**
|
||
|
||
- 桌面壳：`electron/` 的窗口、应用协议、preload 与 IPC、就绪检查、产品账号登录及刷新生命周期；`renderer/` 的布局、任务状态、历史、接管和通用展示组件。原后端进程管理接口可参考，启动对象改为本项目执行进程。
|
||
- 管理界面：`console/` 的布局、主题、登录页、菜单权限、用户管理、审计、筛选与通用表格组件。商品、线索、用量和商业管理页面按本项目新增。
|
||
- 云端骨架：`server/` 的 FastAPI 应用、产品用户与会话、权限和审计，以及配置草稿、修订与发布机制。可保留 FastAPI/PostgreSQL；学校业务 JSON 需要替换为本项目配置与能力清单契约。
|
||
- 浏览器宿主：WebContentsView、人工接管、输入隔离及目标检查作为独立候选组件，按第 4.1、4.2 节验证，避免把浏览器展示层与原 Agent 编排整套绑定。
|
||
|
||
**必须适配的边界。**
|
||
|
||
1. 学校、学生、业务系统与成员关系贯穿原表结构、接口和 UI，需要映射为商家、产品用户、内容平台及本地平台账号模型；不能仅替换文案。原同一用户、同一系统唯一绑定也需要适配同平台多账号。
|
||
2. 原业务登录依赖用户名、加密密码、角色绑定和受控凭据证据。采用产品账号认证时，将第三方平台登录单独改为官方页面人工登录、本地持久化会话和账号身份核验，不携带原密码代配与凭据租约链。
|
||
3. 原 runner 在新建内嵌分区及独立浏览器目录时加入随机标识，不能直接提供本项目按账号跨任务复用登录态。采用宿主后需稳定账号映射；同一活跃会话保活与重开后复用分别验收。
|
||
4. 原 `backend/` 本地服务与中心 `server/` 均使用 PostgreSQL。桌面业务存储仍按本项目 SQLite 设计，学习端仍使用独立验证库；提取基础时切开本地 PG/Docker 和校园编排依赖。
|
||
5. 原本地模型设置、供应商密钥与兜底调用，不等同于本项目云端按用途配置、预算和计费网关。客户端模型配置界面需替换；设备登录标识也不等同于商业设备权益。
|
||
6. 原打包入口只配置 Windows 免安装目录，已有非 Windows 路径分支不能视为 macOS 发布验证。本项目仍需完成目标系统与架构验证、安装包、签名、macOS 公证和升级回滚。
|
||
|
||
**继续新增的产品能力。** 获客业务页面与平台链路、商家业务和学习验证存储、独立能力包契约与门禁、订阅套餐、订单与续费、设备权益、AI 网关、模型配置版本、额度预占结算及对账仍需建设。本次未在原中心路由和表结构中发现完整商业模块实现。
|
||
|
||
**建议提取顺序。** 先在本项目建立独立应用标识、数据目录、端口与构建入口，提取桌面壳和后台布局，再适配产品认证与商家模型，接入 SQLite 与固定执行器，随后增加 AI 与商业模块。内嵌浏览器只作限定范围验证后决定采用。原工程含端口探测及关闭旧本地服务逻辑，新应用须校验进程归属，不能沿用旧项目端口或关闭其运行实例。提取范围限选定源码、必要资源、依赖声明和相应测试；不复制原环境配置、账号资料、运行数据、依赖目录、构建产物或 Git 元数据。
|
||
|
||
## 5. 学习端怎样落地
|
||
|
||
### 5.1 谁负责学习
|
||
|
||
首版由我们在维护者环境中学习、调试和验证平台链路，然后发布给商家使用。同一版本的共性平台操作可以复用；商家的关键词、商品和客户条件作为运行参数。
|
||
|
||
学习端从开发工具做起，采用“限定范围、观察取证、整理操作知识、生成候选、固定校验、变参试跑、发布版本”的闭环。维护者可以手写、借助模型生成或修订实现；各类实现经过相同的校验和验证。首版不要求自动学习任意网站，也不要求每个学习步骤都由模型完成。
|
||
|
||
每次学习先明确平台、能力目标、页面入口、账号角色、输入输出、需要覆盖的正常与异常分支，以及时间、步骤和模型调用预算。一次学习未覆盖的情况记录为缺口，不能把“见过页面”“理解操作”和“执行验证通过”合并成一个成功状态。
|
||
|
||
### 5.2 从页面证据到可执行能力
|
||
|
||
1. **观察并留存依据。** 记录页面和当前对象、操作前后状态、动作、读取值、定位候选及匹配数量、等待条件、结果和观察时间。截图或页面快照作为可回看的依据，具体保存范围受本次学习预算限制。
|
||
2. **整理结构化操作知识。** 明确输入字段的类型、必填条件和值来源，记录页面状态、步骤先后、分支条件、预期效果及未理解项。例如搜索的有结果、无结果、需要登录，评论的继续加载、展开回复和读取结束分别描述。
|
||
3. **形成候选能力及用例。** 将确定的步骤变成参数化实现，附输入输出契约、结果核对方式、验证用例和证据引用。模型的文字说明、点击录像或 Midscene 缓存都不能直接作为已发布能力。
|
||
4. **固定规则校验。** 由程序检查结构与类型、参数绑定、动作范围、定位与等待定义、输出映射、用例覆盖和证据引用。校验拒绝先返回候选修订；这一步不能代替真实浏览器验证，也不由模型自行宣告通过。
|
||
5. **变参试跑并核对结果。** 在维护环境安装候选版本，改变关键词、视频或账号对象、列表长度和页面状态，核对实际对象、字段、来源、分支及结束条件。存在多个匹配元素时明确作用域并核验目标，不能默认点击第一个。内容本身会变化，不要求两次返回完全相同的视频列表。
|
||
6. **发布经过验证的版本。** 只有满足该版本覆盖范围和双端验收要求的候选才进入发布清单；范围外情况保留缺口或明确不支持。更新生成新版本，旧版本及其验证记录保留。
|
||
|
||
“校验通过”表示产物结构符合约定；“试跑通过”表示指定环境与样本中实际执行并核对成功；“已发布”表示进入商家可用清单。这些状态分别记录。学习资料另记已观察范围、理解情况和剩余缺口，避免用单一进度百分比代替覆盖情况。
|
||
|
||
### 5.3 学习产物与最小存储
|
||
|
||
每条能力包至少包括：能力名称、内容平台、版本与内容校验值、输入输出定义、前置状态、参数化动作实现、定位与等待规则、完成判据、错误与未知结果状态、恢复规则、证据引用、验证用例、操作系统与浏览器兼容范围。发布清单关联验证结果，记录 Windows 与 macOS 各自的状态，不能把单端通过视为双端通过。
|
||
|
||
首版可以采用显式 TypeScript 实现加 JSON 清单，不先建设通用流程语言或工作流平台。学习记录与能力包分开：学习记录解释如何得到实现、还有哪些缺口，商家执行包只携带运行所需的契约、实现和兼容信息。
|
||
|
||
维护端保存学习任务、观察证据、操作知识与缺口、候选版本、校验与试跑记录、发布清单。学习后台采用独立 PostgreSQL 学习库，截图、快照等大文件保存为文件并由记录引用。检索库与学习账本分库，准备 pg_search 与 pgvector；商家桌面业务库仍采用 SQLite。SQLite 学习原型保留作离线开发及隔离测试，原库迁移后保留。首版不要求先建设多机调度或全站探索队列。
|
||
|
||
每次验证单独追加一条记录，至少包含学习任务、能力版本及内容校验值、用例和参数快照、平台与测试账号引用、操作系统与浏览器版本、执行器及必要模型配置版本、开始结束时间、前置与结束状态、预期效果、实际读回、校验或执行结论、失败原因、耗时和模型消耗，以及证据引用。未使用模型时可记录零调用；未取得实际计量时标记未知，不能用零替代。
|
||
|
||
固定校验、浏览器试跑、结果核对与双端验收分别记录并关联同一候选版本。重跑、修订回归产生新记录，保留历史结论；验证界面可按能力、版本、用例和系统筛选，查看预期与实际结果及关联证据。发布清单引用具体通过记录，同时保留未覆盖项；记录库中不保存平台手机号、验证码、密码或原始登录凭据。
|
||
|
||
例如，搜索能力输入关键词和读取范围，输出候选视频标识、标题、作者、来源及本轮读取状态；评论能力输入视频标识和进度，输出本轮评论、父子关系、来源及下一读取状态。验证时既检查数据结构，也检查读出的字段是否属于当前视频和评论对象。
|
||
|
||
固化的是“如何找到并处理当前对象”，不是把一次录制中的第几个按钮或屏幕坐标照搬到所有任务中。动态评论列表需要每次重新识别当前内容；DOM 句柄不能作为跨运行的长期身份。
|
||
|
||
### 5.4 学习范围与运行判断的分工
|
||
|
||
首批沿用六类链路：搜索、视频读取与切换、主页与作品读取、评论与回复读取、关注、私信。先完成前四类的只读流程，关注、私信按跟进阶段验证。跟进链路把准备、动作和结果核对分开，试跑使用明确的测试账号和测试对象。
|
||
|
||
学习单元是可复用的平台操作及其必要分支。一条视频、一条评论和一个潜在客户是运行时处理的业务对象，不为每个对象新建一条需要学习的能力，也不遍历整个平台后才开始运行。
|
||
|
||
运行端按业务规则调用已发布能力；内容相关性、账号角色和采购意图仍结合当前商品及上下文在运行时判断。可以固定读取与调用步骤，不能把一次学习中的客户判断冻结到所有商家和所有新内容上。
|
||
|
||
### 5.5 失败怎样回到学习端
|
||
|
||
区分候选校验拒绝、试跑失败、商家运行异常和动作结果未知。登录失效、额度耗尽等由既定运行状态处理；页面结构变化或未覆盖分支则回流维护端，携带能力版本、输入、相关证据和失败位置。
|
||
|
||
维护端在限定预算内定位原因，修订候选，并重新执行固定校验、受影响用例及必要回归，形成新版本。运行任务固定旧版本，不能让诊断模型在商家任务中边探索边替换生产脚本。发布后，新任务使用新版本；旧任务可恢复时仍使用原版本。原版本无法继续而需要新版本时，先检查检查点兼容性，再建立关联原任务的新任务，并继承已完成对象和动作账目，避免重新跟进。
|
||
|
||
关注或私信等操作结果未知时，先核对实际效果，再决定后续处理。不能为了生成失败样本或验证修复而重复发送；候选校验拒绝也不能记成浏览器执行失败。某次试跑通过不代表完整的自然失败、修订、回归闭环已被验证，验收记录分别说明覆盖情况。
|
||
|
||
### 5.6 现有项目与开源项目的角色
|
||
|
||
- **browser_use 测试工程的桌面与后台：** 本轮已检查其工程基础，按第 4.4 节作为候选提取源；这与采用 browser-use Python Agent 框架分别决定。优先减少窗口、产品认证和管理界面的重复建设，业务执行和存储按本项目契约重接。
|
||
- **A2A 学习端：** 当前决定以其现有学习后台的适用页面和工作流为基础裁剪，迁移与差异见第 5.8 节。能力包、参数化、定位、等待、会话和结果核验按本项目边界适配；原项目的业务验证不能等同于获客平台适配完成。browser_use Agent 的采用仍按需决定。
|
||
- **Midscene：** 作为可选的探索页面、局部定位、视觉读取和诊断组件，出现明确需求后，验证其效果、成本与集成价值。其规划与定位缓存可以减少调用，但查询和断言仍可能调用模型，不能直接当作免模型的已发布能力包。参见 [缓存机制](https://midscenejs.com/caching)和 [Playwright 集成](https://midscenejs.com/integrate-with-playwright)。
|
||
- **OpenAdapt Flow：** 重点研究录制、编译、参数化和执行后检查。当前开发位于 [OpenAdapt 主仓库的 flow 包](https://github.com/OpenAdaptAI/OpenAdapt/tree/main/packages/flow)。首版先参考产物设计，验证通过后再决定是否接入 Python 运行时。
|
||
- **Riot、Browser Use Desktop、Workflow Use：** 保留为实现参考与对照原型，暂不作为首版同时引入的运行依赖。
|
||
|
||
第一版普通流程优先用显式代码执行。页面不匹配时可以调用有预算的只读诊断；发现新的操作方法后，在维护环境验证并发布新版本。已发布任务不直接把临时探索结果当作新能力包。
|
||
|
||
### 5.7 参考项目与本项目的边界
|
||
|
||
选型以当前业务需要和执行方式为准。browser-use 的 Agent 可以探索页面，也提供直接动作与无 LLM 的初始动作；不能把它等同于所有步骤都必须调用大模型。参见 [官方 Agent 配置](https://docs.browser-use.com/open-source/customize/agent/all-parameters)。这些能力可供参考，不构成必须采用它的理由。
|
||
|
||
本项目重复运行少量已知流程，首选 Playwright 固定执行、普通程序等待和结果核对，模型主要处理内容判断。降低调用量来自链路固化和职责划分，不能仅归因于更换框架。只有需要在具体实现之间做选择时，才使用相同流程和模型条件比较，不把旧项目对照测试设为开发前置。
|
||
|
||
A2A 与 browser_use 提供设计和实现经验，本项目独立定义需要的功能、数据结构和执行边界。可以借鉴思路、按需采用合适组件，也可以直接实现；不为了复用而增加旧项目耦合、额外运行时或迁移工作。学习与运行端通过能力契约隔离底层驱动，不把框架对象写入业务数据格式。
|
||
|
||
此前对本机代码的只读核对显示，A2A 学习工程已有 Playwright 参数化动作、定位和等待实现，旧 browser_use 工程也有固定流程与会话管理实现。这些是可参考的实现案例，不是本项目的依赖或现成获客链路；测试宿主也不能直接视为商家生产执行器。
|
||
|
||
本轮进一步参考 `D:\qiekj\PenguinUniOS-Workspace\projects\learning` 的观察取证、操作知识、候选校验、参数装配、试跑读回及失败修订设计，补齐本项目学习闭环。其全站分层探索、多工作者领取与租约、跨端能力供给及知识检索体系暂不引入；模块职责可以借鉴，具体存储、协议和实现独立决定。参考工程的独立闭环验收仍有未完成项，不能将其设计或局部通过记录视为整套能力已验证。
|
||
|
||
首轮围绕搜索、主页和评论构建最小只读链路，记录完成情况、读取正确性、模型调用量、总耗时以及 Windows/macOS 分发维护工作量。第 4.4 节中现有测试工程的桌面与后台候选模块单独提取验证，不将其中的校园编排作为本项目执行前提。只有出现明确的探索、视觉或定位问题时，再针对该步骤评估 Midscene 等辅助方案。正常流程不能同时由两个驱动无协调地控制同一浏览器会话。
|
||
|
||
### 5.8 学习后台的实际迁入边界（2026-10-22）
|
||
|
||
本轮按当前决定，以 `PenguinUniOS-Workspace/projects/learning` 的学习后台为来源，直接裁剪适用的 React/Ant Design 组件、页面结构和交互流程。原工程保持只读，不复制账号、环境配置、数据库、浏览器资料、依赖目录或构建产物；新工程拥有独立认证、数据目录、端口和进程。
|
||
|
||
学习进度、学习批次、候选能力、参数与操作链详情、脚本测试、验证历史和证据回看接本项目接口。原后台的多机监控、租约派发、消费者回执、语义检索、系统账号管理不作为本机学习端的前置；未接入的模块不放置可点击的空壳。
|
||
|
||
后端使用 FastAPI + 独立 PostgreSQL，浏览器由 Node.js Playwright 工作进程执行。采用 PostgreSQL 可保留原事务、行锁与队列设计，但原 ConsoleRepository/FrontierRepository 还绑定 A2A 业务合同，部分证据文件与运行器依赖 POSIX/macOS，不能整包导入后宣称兼容 Windows。本轮适配不可变候选、动作证据引用和测试历史机制，保留后续扩展接口。
|
||
|
||
本机学习后台的空数据库首次启动时初始化 `admin / 123456`，以 scrypt 摘要保存密码。已有账号时跳过初始化，重启不重置密码；该账号属于本机维护工具，与后续云端商业后台和平台账号分别管理。云端商业数据库仍按 PostgreSQL 规划。
|
||
|
||
第一版可人工选择页面元素，记录参数化填写、点击与读取，生成固定候选；校验与试跑各自追加记录。实际读取结果交由后台固定规则对照预期，此项不等同于原项目的完整独立身份读回、失败恢复和发布供给体系。尚未接入模型自动理解与规划。
|
||
|
||
用本机演示页面先验证「搜索 → 详情 → 评论」、不同关键词试跑、错误预期失败、证据留存和重启持久化。Windows 记录不能代替 macOS 实机记录，发布预检保留双端要求；本轮不提供正式能力发布按钮。小红书模板仅预填目标和入口，实际平台登录、定位、只读请求范围与结束条件仍需逐步验证。
|
||
|
||
迁入清单与来源见 [后台模块说明](../apps/admin/source-provenance.md)。启动及验证命令见项目 README。
|
||
|
||
### 5.9 自主学习核心与检索底座的职责
|
||
|
||
本项目首期明确采用本地 Codex 协作学习：维护者给出限定目标并在平台页面自行登录，Codex 通过学习工具观察页面、整理操作知识、编写参数化固定实现、提交候选，并根据程序校验与实际试跑修订。后台保存任务、证据、版本和验证真相。先打通这条开发者学习闭环，后台内置模型调用、无人值守学习与调度按后续需要建设，不作为首条平台链路学习的前置。
|
||
|
||
能力验证通过后，由商家端按业务参数执行固定实现；内容相关性与采购意图等运行判断仍按产品方案使用可配置模型。本地 Codex 的开发学习过程与商家执行时的模型调用分别计量，不要求商家运行 Codex。
|
||
|
||
原学习端的真实模型入口为 `independent_learning_runner.py`，冻结 orchestrator、frontier、author、diagnose、repair 五份 Skill，交由原生模型 CLI 执行受限工具循环；`agent_dispatch.py` 的传输主要服务失败诊断与修订。后台提供持久状态、预算和固定门禁，模型返回成功不等于链路已学会。
|
||
|
||
学习链路为：读取目标与队列 → 原子领取限定节点 → 浏览器观察及补证 → 形成字段、分支和操作链知识 → 作者提交候选 → 固定校验反馈 → 新 attempt 修订 → 接收精确版本 → 自动首测及独立读回。全站 frontier 使用 PG 行锁、租约与最浅层优先；本项目先适配单条已选链路，不需要首先开放全站遍历。
|
||
|
||
当前后台已迁入适用的管理页面和录制/候选/验证适配器，尚未迁入模型自主学习、完整操作知识合同、自动作者修订循环与独立身份读回。原 runner 的 `sandbox-exec`、证据文件的 `fcntl/getuid/dir_fd` 和仅 macOS 支持的原子提交需要跨平台替换。增加 PostgreSQL 只解决存储与事务基础，不代表这些学习能力已接好。
|
||
|
||
`pg_search` 与 `pgvector` 用于学习后的能力知识检索：正向文档 → embedding → 不可变索引代际 → 激活 → BM25/向量召回。它们不负责观察页面或决定下一步点击。原工程检索模块还有真实模型效果、生产资格桥和正式消费边界；本项目本轮只部署与验证检索扩展，未宣称业务索引或自动检索学习已完成。
|
||
|
||
部署采用独立 Compose 项目、PG17、pg_search 0.26.1、pgvector 0.8.6，学习库、检索库和测试库分别命名。镜像及扩展版本以实际安装检查为准，配置与随机数据库密码保存在忽略的本机文件，原工程环境与数据库不参与迁移。
|
||
|
||
## 6. AI 判断与调用成本
|
||
|
||
### 6.1 三个判断分别记录
|
||
|
||
内容相关性、账号角色、采购意图分开定义输入和结果，也分别评估误判与漏判。实现时可把有共同上下文的判断合并到一次模型请求中，仍保留三个独立字段。
|
||
|
||
结果包括对象标识、分类、需求信号、原文依据、缺失信息、模型和规则版本；信息不足时返回待判断。模型自评分仅用于排序实验，不能直接当作识别准确率。
|
||
|
||
评论分析保留所属视频、父评论和必要回复，区分作者、评论者和商家。新评论或变化后的上下文需要重新判断。
|
||
|
||
### 6.2 文字优先，视觉按需
|
||
|
||
能用标题、简介和评论判断的，优先使用文本。视频信息不足时，才评估截图、OCR、语音转写或视频理解；它们有独立预算。
|
||
|
||
“相关性”不仅是词面或向量相似度，“购买意图”也不能由相似度直接替代。是否使用向量检索取决于样本规模，首版不必先建设向量数据库。
|
||
|
||
轻量文本模型、较强复核模型和视觉模型通过适配层接入，具体型号在同一批样本上比较后确定。每次结果应能关联输入内容和规则版本。业务分析结果的复用键包含内容与上下文、商品条件、提示规则、模型及结果结构版本，并设置适合内容时效的有效期。
|
||
|
||
### 6.3 两类成本分开
|
||
|
||
我们维护平台时的学习、探索、链路修复，属于产品研发与维护成本。商家运行中的文本分析、视觉分析和可选页面诊断属于实际运行用量。
|
||
|
||
普通 Playwright 代码不产生 LLM Token 费用；使用 Midscene 的 AI 操作、查询、断言或异常分析，仍可能产生费用。不能把“有缓存”解释为整条获客流程零模型成本。
|
||
|
||
程序先去重、复用有效结果，并做明确规则筛选；模糊样本不因缺少关键词就直接全部排除。批量分析按对象标识返回结果，验证结构后才进入线索状态。
|
||
|
||
### 6.4 模型由我们在后台配置
|
||
|
||
模型供应商、具体型号和路由策略由产品运营方在管理后台维护。客户端调用稳定的业务分析接口，不硬编码某个 DeepSeek 或其他厂商的版本。商家按产品权益使用相应分析能力，默认无需自行选择模型或填写供应商密钥。
|
||
|
||
后台分别配置基础文本判断、复杂文本复核、页面视觉定位与理解、维护者学习探索四类用途。它们可以使用不同模型；不要求采用最新或最强型号。较低成本模型满足样本质量要求时，可以作为默认，但不能仅凭版本较旧就推定价格低或任务效果足够。
|
||
|
||
文本意图识别与 GUI 视觉操作分别校验能力。只支持文字的模型可以用于评论分析，但不能直接替代 Midscene 所需的视觉模型。Midscene 的模型系列适配配置也需要匹配，不能仅修改模型名称就假定可用。依据 [Midscene 模型选择](https://midscenejs.com/model-selection)和 [模型配置](https://midscenejs.com/model-common-config)。
|
||
|
||
配置至少包括供应商与实际 model ID、接口协议、密钥引用、支持的输入类型与结构化输出能力、思考模式、输出上限、超时重试、价格有效期、用途预算和有限的备用策略。提高模型规格的回退受用途与预算限制，不能在后台不设上限地升级。
|
||
|
||
新配置先做连通、结果结构、真实样本质量与成本验证，再发布配置版本。运行任务保存配置快照，切换默认模型不会让正在运行的同一批分析无记录地混用；供应商停用时暂停或使用已配置的兼容备用路径。若供应商只提供动态别名，记录可获得的实际版本或响应标识，不承诺可以继续调用已下线的旧模型。
|
||
|
||
更换已经适配的模型通常由后台配置完成；新增协议、视觉模型系列或客户端不支持的能力时，仍可能需要适配代码和客户端升级。
|
||
|
||
## 7. 线索与跟进
|
||
|
||
线索最少保存平台与对象标识、来源链接、发现时间、原始需求依据、判断结果和跟进状态。同一账号的多条相关评论可以归并，但保留各自来源。
|
||
|
||
优先采用稳定的平台对象标识；无法可靠确认身份时保留为待判断，不能仅凭相同昵称自动认定同一人。内容去重、客户去重和跟进动作去重分别处理。
|
||
|
||
关注、消息准备、消息发送、结果核对和回复读取分别实现。消息内容可来自商家模板或可选生成，保存实际使用的版本。自动跟进保留为最终业务链路的一部分。
|
||
|
||
跟进动作有 prepared、executing、confirmed、failed、uncertain 等状态。执行前记录目标和业务操作标识；程序崩溃、页面超时或网络中断后，先核对实际状态。
|
||
|
||
本地操作标识和记录可以减少重复执行，但第三方平台动作不能只靠本地去重就保证恰好执行一次。消息发送等结果不明时进入待核对，不能把未知结果直接当失败重试。
|
||
|
||
动作去重跨任务生效，至少结合平台、执行账号、可靠的目标标识、动作类型和业务跟进轮次。同一业务动作不能因为重建任务或更换模板就自动重做；新的跟进轮次需作为明确的业务设置。
|
||
|
||
## 8. 任务编排与恢复
|
||
|
||
任务包含商品条件版本、平台账号、入口与关键词、处理范围、能力包版本、模型配置版本与快照、分析预算和跟进设置。第一版一个账号内串行执行，后续再评估不同账号的并行。
|
||
|
||
任务状态包括待运行、运行中、暂停中、已暂停、等待登录、等待处理、等待额度、完成、失败和取消。
|
||
|
||
检查点保存已确认完成的对象、剩余队列、当前步骤和必要页面状态。恢复时重新打开或核验页面，不能直接沿用之前的第 N 条可见位置。任务范围以本轮实际发现的内容为准，不承诺无限滚动列表能被完整枚举。
|
||
|
||
暂停在可确认的步骤边界生效。紧急停止、断电或关闭程序可能留下结果不明的动作，恢复后仍按动作账目核对。人工接管后，运行端重新检查账号、页面和当前对象。
|
||
|
||
关闭主窗口与退出程序分别定义，Windows 托盘和 macOS 菜单栏、Dock 行为通过系统适配处理，界面明确显示任务是否仍在运行。退出程序会停止本地执行；本地任务不会在电脑休眠或关机后继续。两端分别验证恢复唤醒后的浏览器与账号核验。断网或云端不可用时停止开启新的分析和依赖分析的后续动作，保留检查点及未决请求，恢复后对账再继续。
|
||
|
||
任务固定使用创建时的能力包版本；运行中的任务不热切换脚本。发布记录至少包含版本、校验信息和兼容范围。客户端升级或回滚后，先确认其支持任务原有的能力包版本，再从支持的检查点继续；不兼容时明确暂停。需要采用不同能力版本时，按第 5.5 节建立关联的新任务并复用可兼容进度，保留跨任务动作去重。
|
||
|
||
## 9. 商业模式与额度
|
||
|
||
采用软件订阅、包内分析额度和超额加量包的组合。软件有效期和 AI 余额分别管理，不设置没有成本边界的模型无限使用承诺。
|
||
|
||
商家看到基础文本分析、深度分析和视觉分析等清楚的计量项；服务端记录实际供应商、模型、输入输出 Token、视觉用量、请求标识和费用。供应商成本与商家额度分账记录，任务和请求标识关联两者；商家消耗的分析额度不直接等同于供应商 Token。按分析量收费与按有效线索收费是不同模式，首版建议先验证分析额度模式。
|
||
|
||
一次请求按“预占额度、调用模型、保存结果与实际计量、结算或释放剩余预占”处理。客户端重试复用同一请求标识，已完成的请求返回已有结果，不重复扣费。
|
||
|
||
供应商请求超时可能已经产生费用，需保留处理中或待核对状态，不能立即视为免费失败，也不能盲目再发一次。具体对账方式按供应商能力实现，充值和扣费通过服务端账本事务管理。
|
||
|
||
初期定价沿用 v0.1 中的试售假设作为访谈材料，不在本轮把 199 元/月或三万条设成最终套餐。确定价格前测出实际消耗、维护工作量和商家持续付费意愿。
|
||
|
||
## 10. 推荐的开发顺序
|
||
|
||
### 阶段一：验证一个平台的基础能力
|
||
|
||
围绕搜索、视频、主页和评论定义最小能力契约，采用一条明确的执行路径完成验证。候选基础模块的提取验证与平台能力验证可以并行，不以完整旧工程迁移完成为前提。
|
||
|
||
从这一阶段就保留观察证据、字段与分支说明、未覆盖项、候选版本和验证用例，执行固定校验与变参试跑。先用简单文件及开发工具承载，避免前期只留下演示脚本，到后期才补无法追溯的学习依据。
|
||
|
||
工程基础从第 4.4 节的候选模块提取验证开始：先完成独立桌面启动、后台布局与产品登录的最小链路，并核对新应用数据、端口和进程归属。云端可以采用原 FastAPI 骨架；本地存储与执行按新契约接入。提取不以启动原校园服务或迁移其运行数据为前提。
|
||
|
||
第一条学习链路采用小红书搜索笔记、详情和评论读取，在 Windows 与 macOS 上分别验证浏览器登录、页面定位、字段与结束条件；再验证抖音等平台。先做单账号，不先做完整会员后台。双端使用同一验收清单。
|
||
|
||
阶段产物是可重复执行的链路、结构化学习记录、独立验证记录库、真实样本、变参结果和失败记录。验证首次人工登录、同目录重开、软件重启和会话失效后的行为。若关键网页版功能不足，先调整执行方式或首发平台，再投入完整产品建设。
|
||
|
||
### 阶段二：完成发现与筛选
|
||
|
||
实现商品档案、任务、三类判断、去重、来源回看和本地线索页面。准备带上下文的标注样本，对照人工结果，统计误判、漏判、耗时和费用。样本量和可接受标准在首轮样本后细化。
|
||
|
||
### 阶段三：完成学习资产与恢复
|
||
|
||
将前期学习资料与候选整理为统一能力包，完善校验、试跑记录、版本发布和回滚工具。验证重启、登录失效、页面变化、人工接管、列表变化和预算耗尽后的行为，并覆盖失败证据回流、候选修订及回归；明确哪些属于人为构造场景、哪些已有实际运行证据。
|
||
|
||
### 阶段四：接入跟进闭环
|
||
|
||
分别验证关注、会话准备、消息发送、结果核对和回复记录。覆盖已关注、重复候选、发送前中断和发送结果不明等情况，再确定首版开放范围。
|
||
|
||
### 阶段五：形成可收费的安装版
|
||
|
||
完善双平台安装包、任务进程退出、客户端升级、产品登录、设备权益、订单、后台模型配置、额度网关和账本。模型配置逻辑在前面的分析验证中先以开发配置使用，此阶段补齐管理界面、验证发布和回退。分别在已确认的 Windows 与 macOS 系统版本、架构目标环境验证，按同一业务范围发布。用一批有限任务核对供应商用量、服务端扣费和客户端展示是否一致。
|
||
|
||
### 阶段六：扩展覆盖
|
||
|
||
单平台流程和商业用量稳定后，依次增加推荐流、多账号并行、抖音与快手、可选线索同步和手机查看。每增加一个平台都新增适配与验证，不把它描述为自动通用。
|
||
|
||
## 11. 首轮验收要回答的问题
|
||
|
||
- 一条能力从页面证据、字段与分支说明到实现和用例是否可追溯，尚未覆盖哪些状态。
|
||
- 固定校验、变参试跑和版本发布是否分别有记录；更换关键词、对象和列表状态后，输出与实际页面是否仍对应。
|
||
- 学习端能否按能力版本、参数、用例、系统和浏览器回看独立验证记录，修订与重跑是否保留原结论。
|
||
- 每类页面是否真的能完成操作和读取，读出的对象、文本与来源是否对应。
|
||
- 同行评论和需求作者两条业务路径能否分别形成可回看的线索。
|
||
- 内容、角色和意图判断各自有哪些误判、漏判和信息不足的样本。
|
||
- 每千条分析、每批任务和每条人工确认线索的模型费用与总耗时是多少。
|
||
- 登录失效、页面变化、崩溃、额度耗尽和人工接管后，是否能继续或明确停止。
|
||
- 平台登录能否完全由商家在官方页面完成，登录信息是否排除在日志、证据和模型输入之外；同目录重开、软件重启和升级后是否复用并重新核验会话。
|
||
- 登录后同会话移交、浏览器最小化、手动关闭及重新显示的行为在两端是否符合定义，当前账号身份是否始终与任务对应。
|
||
- 出现未覆盖分支或链路失效后，能否保留证据、修订候选并完成回归；是否避免在旧任务中直接替换未验证实现。
|
||
- 跟进结果能否核对，重复对象和不确定结果会怎样处理。
|
||
- 客户端、服务端和供应商用量是否能对账，重试是否导致重复扣费。
|
||
- 安装到已确认的 Windows 与 macOS 系统版本、架构的干净目标环境后，浏览器、原生依赖、执行进程、升级和数据保留是否正常。
|
||
- 相同功能在 Windows 与 macOS 是否均通过，窗口关闭、完整退出、快捷键和休眠恢复是否符合各端定义。
|
||
- 候选基础模块提取后是否具备独立标识、目录与进程生命周期，是否仍意外依赖原校园数据、旧工程数据库或客户端供应商密钥。
|
||
|
||
这些是产品验收方向。本机学习基础、PG 存储和隔离示例已有工程验证，结果与边界见开发进度文档；真实平台准确率、日处理量、双端业务效果和交付周期尚未确定。
|
||
|
||
## 12. 建议的后续工程结构
|
||
|
||
当前已建立 `apps/admin/` 学习工作台、`apps/server/` 本机维护 API 和 `tools/learning/` 浏览器工作进程。后续随业务扩展拆分，建议结构如下；未建立的包不代表已有实现：
|
||
|
||
```text
|
||
apps/desktop/ 商家桌面界面与主进程
|
||
apps/server/ 已有本机学习 API；云端产品 API 后续独立部署
|
||
apps/admin/ 已有维护者学习后台；商业运营模块后续补充
|
||
tools/learning/ 维护者的学习、调试和验证入口
|
||
packages/contracts/ 任务、能力包、线索、错误和模型结果定义
|
||
packages/runner/ 编排、检查点、动作记录和预算
|
||
packages/browser/ 浏览器生命周期与账号会话
|
||
packages/platforms/ 各平台的链路实现
|
||
packages/ai/ 文本与视觉分析客户端
|
||
packages/storage/ 本地数据访问与迁移
|
||
capabilities/ 已验证能力包的清单与版本资产
|
||
docs/ 方案与运行说明
|
||
```
|
||
|
||
初期保留较少实际包，先明确边界再按代码规模拆分。当前先完成维护者学习后台及执行器，再接商家桌面端；商业后台在商业闭环阶段完善。
|
||
|
||
## 13. 本轮建议与仍需验证的选择
|
||
|
||
### 13.1 已确认的范围与原则
|
||
|
||
- 首版同时适配 Windows 和 macOS，桌面框架采用 Electron。
|
||
- 保留搜索与推荐流入口，以及同行评论、作者本人有需求两条业务路径。
|
||
- 沿用先学习、固化链路、再重复执行的思路，控制运行时的模型调用。
|
||
- 学习端独立保留验证记录，关联能力版本、用例、参数、环境、实际结果和证据；商家在平台官方页面自行完成登录。
|
||
- 模型由我们在运营后台按用途配置，不绑定某个厂商版本，也不要求默认使用最强模型。
|
||
- 学习后台以 A2A learning 的适用模块为基础裁剪适配，详见第 5.8 节；其他 A2A 与 browser-use Agent 资产按需参考，`browser_use` 桌面壳按第 4.4 节评估提取。
|
||
|
||
### 13.2 当前实施建议
|
||
|
||
以 Playwright 固定执行为主线，围绕当前产品设计轻量执行器；Midscene 保持可选，按实际步骤需求比较。维护者负责能力包学习、验证和发布，云端负责模型网关与用量计量。A2A 与 browser_use 的设计和实现可按需参考。
|
||
|
||
学习端采用有界闭环：限定目标与预算，观察取证，整理字段、状态、分支和缺口，生成候选及用例，固定校验，变参试跑与结果核对，发布不可变版本；失败通过维护端修订和回归。先服务六类获客操作，不建设完整通用学习平台。
|
||
|
||
React + TypeScript、SQLite、Node.js/TypeScript 执行器与 PostgreSQL 是推荐组合；云端优先验证可采用的 FastAPI 认证与管理骨架，再新增本项目模块。桌面壳与后台可从已检查的测试工程中提取适用基础，具体组件依据功能适配、运行表现和双平台分发维护成本决定。
|
||
|
||
### 13.3 仍需验证的选择
|
||
|
||
首发内容平台、具体 model ID 与预算、完整跟进范围、套餐、并行规模、Midscene 是否引入，以及是否采用其他外部组件，仍由实验结果决定。Windows/macOS 最低系统版本和架构覆盖在依赖与打包验证后明确。实现应优先回答当前业务能否闭环，再扩展通用能力。
|
||
|
||
外部框架选型资料核对于 2026 年 10 月 21 日，浏览器持久化及登录状态文档于 10 月 22 日补充核对。本文中的整体组合和模块边界是本项目的设计建议，不是外部项目已经提供的整套获客产品。
|
||
|
||
## 14. 当前优化与近期实施规划
|
||
|
||
本节维护当前实施顺序；实际完成情况、具体测试及遗留问题以开发进度文档为准。以下事项尚未因写入规划而完成，不承诺固定日期。
|
||
|
||
### 14.1 首要：打通本地 Codex 的小红书学习闭环
|
||
|
||
首期由维护者与当前本地 Codex 协作，后台内置自主学习 Agent 后置。限定目标为「搜索笔记 → 详情 → 评论读取」，先完成单账号、有限样本和明确结束条件。
|
||
|
||
1. **建立可确认的实际会话。** 在学习后台创建小红书批次，使用固定本地账号引用；由维护者在后台打开的专用浏览器中登录并确认当前账号。日常 Chrome 或 Codex 右侧窗口的 Cookie 不作为该会话的登录证明。
|
||
2. **整理 Codex 可调用的工具与上下文。** 复用现有 API/浏览器工作进程，提供目标、参数、观察、动作、证据、候选与验证反馈。按实际需要补轻量操作入口，不把另建通用 Agent 平台或必须使用 MCP 作为前置。
|
||
3. **依据真实页面完善站点适配。** Codex 观察搜索、详情、弹窗、评论展开与分页，核对定位和请求事实。当前通用只读请求限制与定位规则是否适合真实小红书需实测；失败时保存依据并修订明确的站点规则。
|
||
4. **固化最小操作知识与版本。** 记录输入输出、字段来源、定位、等待、分支、结束条件、未覆盖项与证据；生成参数化固定实现和候选，不把一次手动点击或模型声明视为学会。
|
||
5. **完成变参回归。** 更换关键词和笔记样本，核对输出确实对应当前笔记及评论；验证正常路径、无结果和中断状态，保存成功与失败记录。未覆盖分支明确列出。
|
||
|
||
本阶段验收：同一候选能够在维护者实际登录的小红书会话中重放限定路径，改变参数后读取对象与输出仍正确，观察、候选摘要和验证记录可追溯。当前本机演示页的通过记录不能代替此项。
|
||
|
||
### 14.2 随后：补齐可交付的能力门禁
|
||
|
||
- 根据实际读取目标定义独立来源读回，逐步补当前 `not_configured` 的核验缺口；程序对执行输出的固定断言继续单独记录。
|
||
- 在 Windows 与 macOS 目标环境分别验证相同能力范围、资料复用、关闭与重开行为；原工程仅 macOS 的 runner/原子落盘机制按需替换，不作为双端已验证代码直接引入。
|
||
- 完成能力清单、版本兼容与发布/回退接口，并将真实验证记录关联发布条件。当前只有预检，不提前宣称商家可用分发已完成。
|
||
|
||
### 14.3 知识增多后：接入能力检索
|
||
|
||
- 从操作知识和合格候选/发布状态生成正向检索文档，将限制与 Gap 保留为结构化条件。
|
||
- 接入真实 embedding 配置、模型版本与维度，建立可追溯索引代际；复用已准备的中文 BM25 与向量查询基础。
|
||
- 将平台、适用范围及版本/质量过滤接入召回，验证真实样本效果。扩展烟测与固定样本向量排序不等于业务召回质量完成。
|
||
|
||
### 14.4 后续产品化与持续优化
|
||
|
||
按第 10 节推进 Electron 商家端、固定能力消费、线索与内容判断、云端模型网关及权益/计量。模型用途、预算与链路执行分别管理，首期本地 Codex 学习不要求商家安装 Codex。
|
||
|
||
每轮新增优化先更新本节或其所属章节，说明解决的问题、实施顺序和验收依据；相应进度记录引用当前规划。产品目标变化时修订现有条目，避免叠加多个互相冲突的计划文件。
|