761 lines
126 KiB
Markdown
761 lines
126 KiB
Markdown
# AI 获客助手整体方案
|
||
|
||
版本：v0.2
|
||
|
||
整理日期：2026 年 10 月 21 日
|
||
|
||
最近更新：2026 年 10 月 25 日，当前按功能模块逐层盘点小红书网页版入口；新增“平台路径”，33项初始模板中18项有可核对观察。搜索/正文/首层评论组合的既有探索保留；新导航已实测发布者主页通过，评论者主页最终复验在官方安全验证处暂停，尚未冻结导航候选。业务分类继续后置；全站、正式运行、双端和发布均未完成。
|
||
|
||
本轮补充：学习端使用独立验证记录库；平台账号由商家在官方页面自行登录，按账号复用本地浏览器资料并核验会话。
|
||
|
||
工程实施补充：`browser_use` 的桌面壳等仍按第 4.4 节评估；根据当前实施决定，学习后台以 `D:\qiekj\PenguinUniOS-Workspace\projects\learning` 的适用模块为基础裁剪，接入本项目独立的 PostgreSQL 与 Playwright 工作进程，见第 5.8 节。
|
||
|
||
状态：已完成本机学习与验证后台基础及有界平台候选的正式执行和过程复查，任务后账号反馈仍待人工核对。更多平台链路、商家桌面端、AI 与商业模块仍是后续工作，不能将阶段能力视为整个获客产品完成。已确认事项、实施建议和待验证选择在第 13 节分别记录。
|
||
|
||
当前实施重点：按功能模块逐层盘点当前账号可达的小红书网页版入口，把有效操作分别固化、轻量召回和变参执行。学习端沉淀操作知识与证据；未来运行端识别用户意图、装配参数，并按当前内容作业务判断。先以结构化任务验证召回与执行，不前置完整自然语言解析、业务分类评测或完整 A2A。
|
||
|
||
维护约定：实际开发、修复与工程验证追加到 [开发进度](开发进度.md)；已确定的优化、设计决定和优先级维护在本方案，近期实施顺序见第 14 节。普通解释和使用问答不记录；进度文档记录事实，不用规划替代完成证据。
|
||
|
||
交互图解：[方案图解](方案图解.html)，包含系统架构、获客流程、学习发布、任务与检索、AI 与额度、任务恢复、登录会话和实施阶段。设计调整时同步维护文字与图解。
|
||
|
||
## 1. 建议采用的整体路线
|
||
|
||
产品由三部分组成：**商家安装的桌面端、我们维护的学习与链路开发工具、云端 AI 与商业后台。**
|
||
|
||
桌面端负责账号登录、浏览器操作、任务运行和线索管理；学习工具负责把平台操作变成经过验证的能力包；云端负责模型调用、软件权益、订单和额度结算。
|
||
|
||
第一版明确同时适配 Windows 和 macOS，两端按同一业务范围开发、验证和发布。第一条学习链路已选定小红书「搜索笔记 → 详情 → 评论读取」；先验证本机演示页的基础链路，再由维护者在官方页面自行登录后进行实际适配。正式首发平台取决于验证结果，抖音、快手及手机执行端后续分别评估。
|
||
|
||
桌面框架采用 Electron，界面采用 React + TypeScript。浏览器侧已确定采用 Playwright 固定执行，学习与未来桌面复用同一版本协议、步骤及结果核对，围绕当前产品需要设计能力契约、定位、等待和状态核验，不另建 browser-use `Agent.run` 执行路径。当前已决定采用 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 或数据库上次记为已登录，都不能单独证明当前账号有效。身份不明、与任务预期账号不一致或仍需验证时，保持等待处理。具体判据按平台学习、验证和维护。
|
||
|
||
学习端当前已实现“先检测，再确认”：打开或刷新时根据可见导航、登录窗口和验证控件返回 `logged_in/logged_out/verification_required/unknown`，不读 Cookie、存储或表单值。已登录时提示无需重复扫码；身份仍以维护者授权为准。本地Codex协作时，维护者已明确授权持续使用固定学习账号后，后续同账号资料目录、同执行配置且可见页面检测已登录时，可沿用该授权完成维护会话ready，不再逐次询问；这不是新增平台身份自动核验功能。资料或绑定变更、登录失效、平台要求验证或会话异常时暂停处理，不把该授权用于任意账号。明确未登录/需验证会阻止执行并撤销旧确认，恢复后重新确认；未知只表示依据不足，不自动判定退出，也不撤销已有有效确认。当前检测适配仅覆盖小红书，其他平台可返回未知。
|
||
|
||
**登录后的窗口。** 首选在同一浏览器会话中从人工操作移交给执行器，登录完成后回到控制台；可最小化浏览器继续执行，提供重新显示和接管入口。最小化对视频加载、读取和任务推进的影响在 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` 的观察取证、候选校验、参数装配、验证记录及失败修订机制。本项目当前收敛为少量平台链路与内容判断，完整 A2A 供给、语义和召回设计后置，范围见第 5.10 节。模块职责可以借鉴，具体实现独立决定。参考工程的独立闭环仍有未完成项，不能将其设计或局部通过记录视为本项目实际能力。
|
||
|
||
首轮围绕搜索、主页和评论构建最小只读链路，记录完成情况、读取正确性、模型调用量、总耗时以及 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 通过学习工具观察页面、整理操作知识、编写参数化固定实现、提交候选，并根据程序校验与实际试跑修订。后台保存任务、证据、版本和验证真相。先打通这条开发者学习闭环，后台自主学习的模型调用、无人值守探索与调度按后续需要建设，不作为首条平台链路学习的前置；已保存内容的独立需求分析另按第 14.2 节实施。
|
||
|
||
能力验证通过后，由商家端按业务参数执行固定实现；内容相关性与采购意图等运行判断仍按产品方案使用可配置模型。本地 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 只解决存储与事务基础，不代表这些学习能力已接好。
|
||
|
||
原 A 的能力知识检索包含正向文档、embedding、索引代际和双路召回；这只是参考设计，不作为本项目每次学习后的必经流程。本项目先用固定能力清单和平台/任务类型路由，平台网页搜索与内容判断另行处理。已部署的 `pg_search` / `pgvector` 保留，数据或能力目录确有需要时再接入，当前不宣称业务召回已完成。
|
||
|
||
部署采用独立 Compose 项目、PG17、pg_search 0.26.1、pgvector 0.8.6，学习库、检索库和测试库分别命名。镜像及扩展版本以实际安装检查为准，配置与随机数据库密码保存在忽略的本机文件，原工程环境与数据库不参与迁移。
|
||
|
||
### 5.10 按社媒获客收敛学习与检索（2026-10-24）
|
||
|
||
本项目服务小红书、抖音等平台的内容发现、意向判断与后续互动。A2A 面向复杂业务系统的完整供给、语义和召回体系不作为首版模板。本节替代上一轮将完整学习/召回对接前移为首要任务的建议，先跑通少量明确链路。
|
||
|
||
#### 三类业务任务
|
||
|
||
1. **检索信息。** 用户给出问题或关键词、平台和范围，系统搜索图文/视频，按需要读取详情、主页及评论，返回带来源的信息与摘要。一次查询不一定形成客户线索。
|
||
2. **发现潜在客户。** 商品与客户条件 → 搜索或有限浏览 → 内容相关性判断 → 主页/角色与评论上下文 → 需求匹配 → 线索去重与依据保存。同行内容下的评论者和作者本人表达的需求分别处理。
|
||
3. **跟进互动。** 对已经明确的对象选择关注、私信、评论或回复指定评论/回复。动作绑定平台、账号、内容及评论层级，记录内容、结果与去重依据。正文生成、对象核对和动作执行分别处理，不能因一条评论相关就自动认定有采购意图。写操作仍须单独学习、限定验证和确认实际支持范围，当前只读执行器尚未支持。
|
||
|
||
#### 一个后台、一套浏览器执行与必要的 AI
|
||
|
||
当前保留已有学习后台、FastAPI/PostgreSQL 账本和浏览器工作进程。业务层只需任务配置/状态、平台链路清单、内容分析和线索/互动记录。任务控制正常步骤和分支；模型解析用户条件、判断内容与需求、按配置生成候选回复。无需为每次点击启动通用 Agent，也不按每个业务角色拆服务。
|
||
|
||
从 A2A 保留目标限定、观察证据、参数化、候选版本、验证记录、失败修订六项机制。当前功能入口与页面层级盘点按第14.0.1节推进；全站动态内容穷举、多工作者租约、完整三级语义生产、公共 AC 协议、独立供给平台、通用 Harness 和复杂任务规划后置。参考项目仍只读；本项目不以完全兼容其协议或全部字段为验收目标。
|
||
|
||
每条已学链路先保存：稳定标识与版本、平台/用途、真实支持的输入、结构化输出与来源、前置条件、步骤/结束条件、异常停止条件，以及证据和验证记录。样本参数与能力定义分开。笔记/评论输出记录必要的对象引用、父子关联和分页/截断状态；取不到的字段记缺口。可以先用类型定义加 JSON 清单，不以新建多层合同包、独立语义修订或索引代际系统为前置。Formily 仍为后续参数表单展示选项。
|
||
|
||
#### 先把“检索”分成三个实际用途
|
||
|
||
- **选用已学链路。** 能力少时，按平台和固定任务类型路由，缺条件再补问；自然语言可由模型解析成受限任务参数，程序核对已支持操作。无需每次先做 BM25/向量/Jev 选能力。
|
||
- **到平台检索内容。** 将用户条件映射为页面搜索、筛选和有限浏览，读取真实内容，模型进行相关性、需求和摘要分析。这是获客首期的主要检索路径，数据库向量检索不能替代网页取数。
|
||
- **查询已经保存的资料。** 对已有内容和线索先提供来源、关键词、对象及任务条件查询。数据和问法增多、简单方式效果不足时，再对明确对象接入 BM25/embedding，单独验证召回质量。
|
||
|
||
已准备的 `pg_search` 和 `pgvector` 保留；本轮不删除基础，也不要求立即接满 C V8。以后引入混合召回时，再落实同模型配置、范围过滤、版本对应、索引更新与评测，不把每个点击或原始学习日志都当作能力文档。
|
||
|
||
#### 页面操作与平台提醒的边界
|
||
|
||
本项目固定执行已确定为 Node.js Playwright，学习与未来 Electron 桌面复用同一 profile、动作合同及结果核对。`tools/learning/browser-worker.mjs` 使用 `launchPersistentContext`；没有接入 Python browser-use，也不另建 `Agent.run` 自主执行路径。A2A 或 `D:\qiekj\browser_use` 的框架与进程设计可作参考，不能将参考工程的能力或账号表现当作本项目已实现。
|
||
|
||
这里的操作要求是走正常可见页面路径、核对当前对象、等到页面状态就绪再进行下一动作；同一账号串行、限定本次读取范围和停止条件，尽量复用已取得内容，避免无意义刷新、重复搜索和失败连点。这些是减少错误与不必要交互的工程措施，不是平台不会识别或不会限制账号的承诺。DOM、视觉或 browser-use 均不能单凭技术名称推导账号安全；平台检测阈值和实际限制效果没有经过本项目验证。
|
||
|
||
学习与实际用户账号、浏览器资料及统计分别管理。学习先用隔离的维护者测试资料，人工示范和有限自动执行交替取证；后续执行复用固定链路，不重复整站探索。探索记录允许出现非真人提醒等中断，已经取得的有效知识仍可保留，不要求探索全程无提醒。受阻步骤保存依据，等待人工处理及重新检查正常状态；异常期间的部分结果不能充当用户正常运行模式的验收证据。
|
||
|
||
#### 固定执行合同：动作与页面原生通信分别约束
|
||
|
||
当前小红书新模式为 `execution_profile:"playwright-xhs-native-ui-v1"`，合同固定为 `execution_contract:{engine:"playwright",action_policy:"xhs-bounded-readonly-v1",network_policy:"xhs-page-native-v1"}`，三字段和值须完全一致，不接受自由框架名、自定义网络规则或无声降级。新建小红书任务默认该模式；明确选择旧实验模式时省略 profile，其他平台不使用本 profile。
|
||
|
||
功能路径盘点另选 `playwright-xhs-navigation-ui-v1`，精确合同为 `engine:playwright / action_policy:xhs-observed-navigation-readonly-v1 / network_policy:xhs-page-navigation-v1`，声明同站公开主页、通知及原搜索/笔记导航。它不修改旧模式或候选；非语义标签、菜单和消息窗口须补各自的控件检查与结果断言，不从任意CSS节点推导可点击权限。当前实际加载和取证状态见最新进度与第14.0.1节。
|
||
|
||
工具动作仅开放官网声明页面内已观察且当前唯一、可见可用的搜索输入/`Enter`，固定实际对象的同站标准笔记锚点，以及普通非交互、不可编辑、非敏感区域的有界读取、等待与滚动。搜索结果核对本次关键词，点击前后核对固定笔记编号，读取前后和每批核对完整页面来源、实际根、字段与截图。关注、私信、评论输入和发布不在此合同内，未来写能力仍须单独学习及验收。
|
||
|
||
页面原生通信不按接口名字推断业务写入。最长15秒的当前动作窗口内，当前主框架自然发起、无凭据URL且标准端口的第一方 HTTPS（`xiaohongshu.com` 及其子域）`xhr/fetch POST` 正常通信，包括安全通信；不再逐接口扩白名单。非第一方、子框架、非HTTPS、其他需策略授权的方法或资源类型、来源失配及到期继续拒绝；窗口不续签，动作结束即撤销。搜索仅接受转入本次关键词结果页，点击仅接受进入固定笔记，其他读取动作不接受完整地址漂移。GET/HEAD/OPTIONS 等既有被动通信语义保留，不能据此声称隔离了全部网络。
|
||
|
||
这是一套受限工具动作合同，不是网络沙箱，也不保证页面或第一方通信在服务端绝无副作用。只通过可见页面动作与实际结果验证，不直接调用平台接口、执行任意 JavaScript、读取请求头/正文或增加指纹/伪装措施；不承诺防检测或账号绝不受限。本地拒绝、平台可见提醒、动作结果及任务后反馈分别留证。
|
||
|
||
schema 10 为任务增加可空 `execution_profile`，旧任务保持空值、API 省略，不追溯补新模式。任务顶层只声明选定模式；`browser_readiness` 的 profile/contract 来自当前已核验会话，未打开不填。候选 `manifest` 保存冻结配置；浏览器验证 `environment` 保存执行器实际回显，初筛与阅读复制各自验证值，缺失显示未记录。静态检查配置不冒充实际执行，错配停止且撤销未证实会话。学习与未来桌面复用该协议，Windows/macOS 环境仍分别验收。
|
||
|
||
legacy 保留未声明新 profile 的四类旧实验策略及原边界：搜索、打开笔记、普通只读辅助和搜索整页定位。它们的精确请求白名单与旧失败原样保留，只用于原合同复现/对照，不能把新模式通信范围写回旧候选或把旧成功继承给新模式。当前加载及真实新模式状态见第14.2节和进度。
|
||
|
||
#### 学到了与可以交给用户运行分别验收
|
||
|
||
本项目的交付目标是：用户执行已发布链路时，在声明的使用范围内稳定完成任务，不出现非真人提醒或功能受限。发现按钮、读取数据或一次跑通只证明部分操作知识；即使探索账号可接受出现提醒，也不能将该探索过程直接交给用户执行。
|
||
|
||
每个版本保留两类记录即可：**学习探索记录**说明如何取得定位、步骤和异常知识；**正式运行模式验证记录**使用冻结的实现、实际拟交付的浏览器执行方式、正常起始会话、明确任务范围和参数，独立运行完整链路。后一类检查操作过程、任务结果、对象正确性、完整度以及当场与任务后是否出现平台提醒/功能限制，并记录浏览器、会话前置、样本与观察范围。平台也可能通过官方消息事后告知，不能以当场没有弹窗替代后续检查。更换关键词、目标对象及完整任务样本，而非只验证单次点击。
|
||
|
||
能力清单只开放已通过相应运行范围验收的版本；实验候选留在学习端。验证中出现提醒或状态不明时，不能凭部分结果晋级。已开放版本在实际运行中出现提醒，停止该任务并将该版本置为待复核，防止继续分配新的相同任务；保留依据、排查原因并重新验证后再恢复。学习有所得、验证通过与当前可用三种结论不混为一个“已学会”。这是一套轻量发布质量规则，无需复制 A2A 的完整供给系统。
|
||
|
||
有限样本未出现提醒，只能证明该版本在已测范围和时段的表现；不能保证任意账号、负载、平台更新后永不提醒，也不能仅从是否显示提醒量化账号权重变化。当前已有有界链路的正式执行及过程复查，任务后官方通知和功能复查尚未完成，不能宣称已经达到上述交付目标。
|
||
|
||
运行阶段需要异常暂停、人工接管和恢复核对；发送或回复结果不明时先核查，保留未知状态。当前只有人工会话确认与基础错误处理，尚未实现平台专属提醒识别、版本停用/恢复或真实账号权限验证。框架和表面上的动作形态不能代替正式运行模式验证。
|
||
|
||
框架事实参考：[browser-use 官方浏览器配置](https://docs.browser-use.com/open-source/customize/browser/all-parameters)和[真实浏览器连接说明](https://docs.browser-use.com/open-source/customize/browser/real-browser)。这些说明浏览器控制、配置与会话能力，不能据此推导小红书/抖音的检测结果或账号长期稳定性；后者须依据限定平台测试记录说明。
|
||
|
||
#### 当前阶段怎样验收
|
||
|
||
先验收小红书“搜索笔记 → 详情 → 评论读取”的正常路径、无结果、登录/平台提醒中断，以及输出和对象来源一致性；随后检验商品条件下的相关内容与需求判断，统计人工确认的误判、漏判、信息不足、耗时和费用。再分别学习和测试关注、私信、发布评论与回复指定评论；不能用只读链路通过替代写操作验证。
|
||
|
||
用户输入能否选择已有链路、参数能否正确传入、输出能否回答问题、线索是否有原文依据和动作是否重复，是首期闭环指标。框架、学习资料、内容判断、真实平台操作和账号状态分别报告。修订候选已有两组正式执行及过程复查，账号任务后反馈、模型判断和跟进功能仍未完成。
|
||
|
||
#### 参考核对保留的事实
|
||
|
||
参考 A 仍为 `main / db7b54a`，与此前核对相同；C V7/V8 是本机未提交设计资料，正式服务尚未初始化。A 的输出投影限制、持续资格桥和语义接入缺口仍存在，但不再要求本项目先补齐整套 A/C 体系。上轮核对过程保留于开发进度第 2026-10-24-02 条，当前实施按本节和第 14 节执行。
|
||
|
||
### 5.11 学习端实施方案与首条任务
|
||
|
||
本节落实第 5.10 节的轻量方案。通用工具与维护质量记录已实现，分批修订候选已完成静态校验、两组真实正式执行及过程复查，具体证据见开发进度。当前等待维护者复查账号后续反馈，并继续补平台真实空态、异常和回复层级样本。
|
||
|
||
#### 谁做什么、使用什么
|
||
|
||
- **维护者：** 在学习后台打开的专用浏览器中自行登录，确认用于学习的账号；必要时演示一遍日常使用路径，供操作质量对照。无需编写脚本，也不在后台提交手机号、密码或验证码。
|
||
- **本地 Codex：** 经学习后台/受限工具控制同一个浏览器会话，观察页面、整理状态和字段、编写参数化固定实现、提交候选，并依据校验和试跑结果修订。Codex 侧边浏览器与日常 Chrome 的登录态不作为该会话依据。
|
||
- **学习后台：** 保存任务、资料引用、步骤/输出、候选版本、两类验证及后续观察；维护候选是否处于实验、待观察、验收通过或待复核状态。界面在现有批次、候选和验证记录中补齐，不另建复杂调度系统。
|
||
|
||
继续使用 React/TypeScript 后台、FastAPI、PostgreSQL 和 Node.js Playwright 工作进程。浏览器采用可见的持久会话，同一会话一个驱动持有控制权。固定执行与桌面复用 Playwright 协议，不为“像人”另建 browser-use `Agent.run` 路径；视觉辅助仍须有明确用途并单独验证。先保留一个应用和现有数据库边界，暂不建设完整 A2A 或商家桌面。
|
||
|
||
#### 第一条学什么
|
||
|
||
目标固定为小红书网页端“关键词搜索笔记 → 打开指定结果详情 → 读取有限评论/回复 → 返回结构化结果与来源”。一次任务明确关键词、内容选择条件、本轮内容/评论范围、结束条件及读取不足时的返回状态；不承诺读完所有历史评论，不包含关注、私信或发布回复。
|
||
|
||
输入先只开放实际支持的参数；输出至少关联当前笔记/作者引用、正文来源、评论与父评论关系、本轮读取结果和完整/截断/未知状态。无法可靠获得的标识或字段保留缺口，不能猜测补值。正常结果、无搜索结果、空评论、加载结束、读取范围耗尽、登录失效、页面不支持及平台异常分别表达。
|
||
|
||
后续学习按需求增加主页/推荐流及互动能力；关注、私信、发评论、回复指定评论单独建立学习目标和测试用例，不能从只读流程直接开放。关键词、商品和选择对象作为参数变化，不为每个客户重新学习整条流程。
|
||
|
||
#### 一条链路怎样学成
|
||
|
||
1. **建任务并确认会话。** 新模式显式固定 profile 和读取范围，维护者登录并确认账号，核对实际会话合同，记录正常起始页面与可观察的功能状态；旧任务不原地切换模式。
|
||
2. **取得正常路径基线。** 观察日常页面操作，记录搜索、打开、滚动、评论展开等必要步骤；每步明确前置状态、当前对象、动作、完成反馈和退出条件。操作需与当前可见页面和实际反馈对应。
|
||
3. **有限探索与补证。** Codex 在相同会话中按目标补齐定位、字段和分支，保留前后证据。探索时出现提醒可记录有效知识和受阻范围；异常页面的返回不能替代正常路径依据。
|
||
4. **固化候选。** 编写有界、参数化固定实现，动态核对对象及作用域，按页面状态等待并返回结构化输出。最终实现来自已验证的操作知识，不照搬一段固定坐标或 DOM 序号录像。模型用于明确需要的理解，不逐次重新规划已知步骤。
|
||
5. **按拟交付方式独立验证。** 对冻结版本改变关键词和目标对象，运行完整任务；检查实际页面路径、状态等待、对象选择、输出正确性、重复/失败处理及当场平台反馈。由后台记录结果，Codex 自报成功不代替固定检查和实际读回。
|
||
6. **任务后观察并收口。** 核对官方通知和可观察的功能状态，完成下述观察记录后再评价该版本；缺口返回修订，新候选保留旧版本和旧结论。
|
||
|
||
这里“像正常用户操作”落实为可见、合理的页面路径及状态转换、当前对象核对、完成反馈与有界读取。截图或画面观感只是依据之一；不以人为添加鼠标轨迹、固定延迟或技术框架名称证明平台会判为真人。
|
||
|
||
#### 任务后的官方通知怎样进入验收
|
||
|
||
每次正式模式验证都绑定精确候选版本和任务起止时间，并保存执行前可核对的官方通知/功能状态基线。任务结束后立即复查；另外按该测试预先配置的观察窗口和复查时点记录后续反馈。第一阶段允许维护者在后台人工登记复查结果，无需先搭后台无人值守监控。观察窗口是报告范围，不是超过该时长便绝无风险的保证。
|
||
|
||
后续观察至少区分：未检查、等待复查、已检查且在该范围内未发现异常、发现相关通知/限制、关联不确定。保存可确认的通知标识或摘要、出现/查看时间、来源与关联依据；既有旧通知不误算成本次新事件，无法归因时不强行判为链路导致。渠道不可读、窗口未完成或通知关联不清时保留未知，不能记成“没有异常”。只记录与本次质量验证有关的官方反馈。
|
||
|
||
“运行结果正确”“操作过程符合定义”“后续观察完成”分别检查。当前没有观察证据的版本不能据当场跑通进入用户可用清单。后续才收到相关提醒时，补记到原版本，置为待复核并暂停新的相同版本分配；以前的通过记录保留。尚无桌面安装版时，只能标记维护环境中的验证范围；未来桌面执行方式、浏览器配置或系统改变，须在对应交付环境重新验收，不能沿用不相符的旧结果。
|
||
|
||
#### 通用工具的实现与平台学习的剩余准备
|
||
|
||
现有代码已具备建任务、持久浏览器会话、人工确认、观察截图、不可变候选及试跑记录。本次在这些基础上补齐通用操作和维护质量规则；状态如下，不据本机夹具推断真实平台链路已可用：
|
||
|
||
- **控制工具已实现：** `tools/learning/control.mjs` 为本地 Codex 提供只连接本机 API 的操作白名单，复用维护者鉴权、CSRF、任务与会话；不支持调用任意接口、脚本或命令。浏览器支持 `fill/press/click/read/scroll/wait/extract`；`press` 仅普通搜索框的 `Enter`，每个候选最多 30 步，单步滚动最多 10 次、每次最多 1600 像素，条件等待最长 15 秒。滚动可配置容器内相对 CSS 停止条件，任一完整目标出现即停止，边界或预算内未满足时明确失败；不能假定固定像素适用于不同正文。要求唯一的交互对象及精确目标零/多匹配停止，集合读取按范围与预算处理；精确目标支持任务参数，交互检查视口与遮挡。搜索控件以固定语义核对，轮换占位示例不单独作为控件变更；标签/意图真正改变或当前候选缺失仍停止，输入与按钮保留观察配额。明确点击产生的同源新页可接续控制；人工确认前同源新页可接续但不自动就绪。未知或出域弹窗暂停并显示真实阻断类型，保留最多 10 条脱敏页面事件。示例与用法见 [受限入口说明](../tools/learning/README.md)。
|
||
- **结构化读取已实现：** 新候选契约为 v2，旧 v1 保留兼容。观察器从实际 DOM 发现普通可见 id、语义标题/容器、纵向滚动根及核对过的 id 族/安全 class 集合；每个读根最多给出 12 个实际后代的相对字段提示，并保存定位依据。安全公共祖先扫描最多 12 层且止于 body 前，集合链接仍须精确筛选和执行前再次核对唯一目标。每次按最多 12 个字段、100 行映射文本、同源 HTTP 来源或允许的业务属性；返回 `items/count/truncated/source_url/coverage`，明确当前视口和预算范围。可选完整行模式只跳过字段存在但被视口/容器裁剪的行，报告 `skipped_incomplete_count` 并标记截断；真实缺字段、敏感或多匹配仍失败，空输出仍不能通过内容验证。旧步骤不自动取得新选项。未看到或超出预算的行不能声称读完，链接中的词不能代替正文断言。更多评论层级、跨任务及更大范围的聚合去重和平台结束分支仍须分别学习，不能由通用提取器猜测。
|
||
- **分批与空态合同已实现：** 可见等待可显式设置 `min_count`，在 1–100 个安全候选范围内等待指定可见数量；省略时保留唯一对象规则。录制/冻结继续校验集合来源，回放允许从未加载的零项等待出现，避免绑定首卡是否有标题。容器提取使用相对 `row_selector`，可配置 `batch`：先读首批，再在已观察的所属滚动根内读取最多 5 批、每次最多 1600 像素，批次时间预算 15 秒；强制完整行模式，按必填安全业务属性去重，同标识内容冲突即停止。逐批截图参与候选摘要，失败也保留已得证据；结束原因区分条数、边界、批数、时间预算，始终明确有限范围。评论父层与已展示回复须分别配置行定位，不能把平铺匹配都称为首层。另有与批次互斥的明确空态合同：普通唯一容器、零行、完整可见且精确匹配的空态文字、非忙碌和可用会话经再次核对后，才允许专用 `{"state":"empty"}` 预期通过；普通文本预期继续要求非空内容。通用工具测试与平台实际空态样本分别报告。
|
||
- **候选和人工质量记录已实现：** 冻结清单继续绑定前后及每批证据和摘要；正式模式试跑须记录运行前基线、起止时间和观察窗口，能力详情提供直达入口，保留探索默认入口。后续观察追加到原验证与精确候选版本，保留登记时间、可选发生时间、通知引用及关联依据，数据库禁止改写或删除事实记录。详情明确提示到期时间与官方消息/搜索/详情/评论功能待办，账号本人告知实际结果后可由 Codex 代登记；运行前“正常”不替代任务后检查。当前是维护者手工核对，尚无平台专属提醒识别或无人值守观察。
|
||
- **维护状态规则已实现：** 候选区分探索中、等待后续观察、维护范围内已验证、待复核。窗口到期本身不会通过；成功的正式模式、到期后的人工过程审核与无异常报告须同时成立。显式填写实际复查时间时，该时间也须在到期后，不能靠延后补录旧检查取得通过。晚到提醒或关联未知会影响同版本，旧试跑不能清除晚到异常，须在异常登记后开始新的正式验证并完成观察。发布预检仍 `published:false`，独立读回及未来双端交付条件保留；这里不产生商家正式可用清单。
|
||
- **平台适配仍在验证：** 显式新 profile 按第5.10节固定动作与原生通信合同执行；旧 legacy 模式保留四类互不借用的精确实验策略，分别为搜索七条、固定标准笔记链接打开八条、普通只读辅助两条、搜索整页目标定位三条。各自限定实际目标、官网当前主框架及最长15秒窗口，原请求/到期边界和历史失败不改。新模式不把未知第一方 POST 一律拦截或认定为业务写入；两种模式均不直接请求接口，通信允许不等于结果正确，仍核对实际搜索、笔记、正文、评论与来源，实验候选也不等于正式开放。
|
||
|
||
通用操作和状态规则先用隔离本机样本验证，再由维护者登录专用浏览器，与本地 Codex 协作完成首条有限真实学习。顺序为：确认会话并采集 → 观察正常搜索/详情/评论路径 → 明确必要请求及字段分支 → 记录参数化步骤 → 冻结校验 → 变参正式试跑及后续人工复查。首次观察发现现有工具不覆盖的行为时，先保留证据并补最小适配，不扩大为全站学习。
|
||
|
||
## 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、接口协议、密钥引用、支持的输入类型与结构化输出能力、思考模式、输出上限、超时重试、价格有效期、用途预算和有限的备用策略。提高模型规格的回退受用途与预算限制，不能在后台不设上限地升级。
|
||
|
||
当前维护端首轮采用服务端 `ASSISTANT_MODEL_*` 环境配置，先提供安全状态和独立分析入口，尚不建设可写密钥的管理页面。真实密钥只保存在本机忽略配置，前端仅得型号、主备槽位是否配置及调用限值；“已配置”不等于“已验证连通”。先以官方 `deepseek-flash`、关闭思考的短文本 JSON 分类建立质量与用量基线，型号保持可配。按 2026-10-24 核对的 [官方型号说明](https://api-docs.deepseek.com/quick_start/pricing/)，该别名对应 V4.1-Flash-1017，旧 V4 Flash 名称已转新版；版本号不能代替实际型号、质量和每任务成本对比。动态别名的后续变化以提供商为准，保存实际返回的型号元信息。
|
||
|
||
第一阶段的备用是同提供商、同型号的另一个 Key，相同 Key 去重；不自动升级型号或回放浏览器。仅鉴权、余额、限流、服务错误或连接超时等限定错误可转一次备用，格式或业务依据不符则保留失败。每次请求最多 30 秒，整个分析最多 60 秒，输出有上限；超时不代表提供商未计费。两个 Key 不等于两个独立账户，也不能保证突破共享额度或服务故障。首轮记录实际 Token、缓存用量及不可得项，不把 Token 数冒充实付金额；完整商家额度结算仍按后续商业网关方案建设。
|
||
|
||
新配置先做连通、结果结构、真实样本质量与成本验证，再发布配置版本。运行任务保存配置快照，切换默认模型不会让正在运行的同一批分析无记录地混用；供应商停用时暂停或使用已配置的兼容备用路径。若供应商只提供动态别名，记录可获得的实际版本或响应标识，不承诺可以继续调用已下线的旧模型。
|
||
|
||
更换已经适配的模型通常由后台配置完成；新增协议、视觉模型系列或客户端不支持的能力时，仍可能需要适配代码和客户端升级。
|
||
|
||
## 7. 线索与跟进
|
||
|
||
线索最少保存平台与对象标识、来源链接、发现时间、原始需求依据、判断结果和跟进状态。同一账号的多条相关评论可以归并，但保留各自来源。
|
||
|
||
优先采用稳定的平台对象标识；无法可靠确认身份时保留为待判断，不能仅凭相同昵称自动认定同一人。内容去重、客户去重和跟进动作去重分别处理。
|
||
|
||
关注、消息准备、消息发送、发布评论、回复指定评论/回复及结果读取分别实现。内容可来自商家模板或可选生成，保存实际使用的版本。评论互动固定所属图文/视频、目标评论及父子层级，执行前重新核对对象；自动跟进保留为业务目标，当前尚未实现。
|
||
|
||
跟进动作有 prepared、executing、confirmed、failed、uncertain 等状态。执行前记录目标和业务操作标识；程序崩溃、页面超时或网络中断后，先核对实际状态。
|
||
|
||
本地操作标识和记录可以减少重复执行，但第三方平台动作不能只靠本地去重就保证恰好执行一次。消息发送等结果不明时进入待核对，不能把未知结果直接当失败重试。
|
||
|
||
动作去重跨任务生效，至少结合平台、执行账号、可靠的目标标识、动作类型和业务跟进轮次。同一业务动作不能因为重建任务或更换模板就自动重做；新的跟进轮次需作为明确的业务设置。
|
||
|
||
## 8. 任务编排与恢复
|
||
|
||
任务包含商品条件版本、平台账号、入口与关键词、处理范围、能力包版本、模型配置版本与快照、分析预算和跟进设置。第一版一个账号内串行执行，后续再评估不同账号的并行。
|
||
|
||
任务状态包括待运行、运行中、暂停中、已暂停、等待登录、等待处理、等待额度、完成、失败和取消。
|
||
|
||
检查点保存已确认完成的对象、剩余队列、当前步骤和必要页面状态。恢复时重新打开或核验页面，不能直接沿用之前的第 N 条可见位置。任务范围以本轮实际发现的内容为准，不承诺无限滚动列表能被完整枚举。
|
||
|
||
暂停在可确认的步骤边界生效。紧急停止、断电或关闭程序可能留下结果不明的动作，恢复后仍按动作账目核对。人工接管后，运行端重新检查账号、页面和当前对象。
|
||
|
||
关闭主窗口与退出程序分别定义，Windows 托盘和 macOS 菜单栏、Dock 行为通过系统适配处理，界面明确显示任务是否仍在运行。退出程序会停止本地执行；本地任务不会在电脑休眠或关机后继续。两端分别验证恢复唤醒后的浏览器与账号核验。断网或云端不可用时停止开启新的分析和依赖分析的后续动作，保留检查点及未决请求，恢复后对账再继续。
|
||
|
||
任务固定使用创建时的能力包版本；运行中的任务不热切换脚本。发布记录至少包含版本、校验信息和兼容范围。客户端升级或回滚后，先确认其支持任务原有的能力包版本，再从支持的检查点继续；不兼容时明确暂停。需要采用不同能力版本时，按第 5.5 节建立关联的新任务并复用可兼容进度，保留跨任务动作去重。
|
||
|
||
## 9. 商业模式与额度
|
||
|
||
采用软件订阅、包内分析额度和超额加量包的组合。软件有效期和 AI 余额分别管理，不设置没有成本边界的模型无限使用承诺。
|
||
|
||
商家看到基础文本分析、深度分析和视觉分析等清楚的计量项；服务端记录实际供应商、模型、输入输出 Token、视觉用量、请求标识和费用。供应商成本与商家额度分账记录，任务和请求标识关联两者；商家消耗的分析额度不直接等同于供应商 Token。按分析量收费与按有效线索收费是不同模式，首版建议先验证分析额度模式。
|
||
|
||
一次请求按“预占额度、调用模型、保存结果与实际计量、结算或释放剩余预占”处理。客户端重试复用同一请求标识，已完成的请求返回已有结果，不重复扣费。
|
||
|
||
供应商请求超时可能已经产生费用，需保留处理中或待核对状态，不能立即视为免费失败，也不能盲目再发一次。具体对账方式按供应商能力实现，充值和扣费通过服务端账本事务管理。
|
||
|
||
初期定价沿用 v0.1 中的试售假设作为访谈材料，不在本轮把 199 元/月或三万条设成最终套餐。确定价格前测出实际消耗、维护工作量和商家持续付费意愿。
|
||
|
||
## 10. 推荐的开发顺序
|
||
|
||
### 阶段一：验证一个平台的基础能力
|
||
|
||
围绕搜索、视频、主页和评论定义最小能力契约，采用一条明确的执行路径完成验证。候选基础模块的提取验证与平台能力验证可以并行，不以完整旧工程迁移完成为前提。
|
||
|
||
从这一阶段就保留观察证据、字段与分支说明、未覆盖项、候选版本和验证用例，执行固定校验与变参试跑。先用简单文件及开发工具承载，避免前期只留下演示脚本，到后期才补无法追溯的学习依据。
|
||
|
||
当前直接复用已有学习后台、独立 PostgreSQL 与浏览器工作进程，先验证平台正常链路及异常停止。第 4.4 节桌面壳的候选提取放在恢复桌面工程时推进；不以启动原校园服务或迁移其运行数据为前提。
|
||
|
||
第一条学习链路采用小红书搜索笔记、详情和评论读取，先在当前维护环境验证登录、页面定位、字段、结束及平台提醒中断条件，再扩展抖音。先做单账号，不先做完整会员后台；未来桌面交付时 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 已确认的范围与原则
|
||
|
||
- 当前先完成少量平台链路、内容检索与需求判断；跟进动作分别验证，完整 A2A 体系和重型能力召回后置，见第 5.10 节。
|
||
- 首版同时适配 Windows 和 macOS，桌面框架采用 Electron。
|
||
- 保留搜索与推荐流入口，以及同行评论、作者本人有需求两条业务路径。
|
||
- 沿用先学习、固化链路、再重复执行的思路，控制运行时的模型调用。
|
||
- 学习与未来桌面共用 Playwright 固定执行协议，小红书新模式明确拆开动作合同与页面原生通信，旧 legacy 合同独立保留。
|
||
- 学习端独立保留验证记录，关联能力版本、用例、参数、环境、实际结果和证据；商家在平台官方页面自行完成登录。
|
||
- 模型由我们在运营后台按用途配置，不绑定某个厂商版本，也不要求默认使用最强模型。
|
||
- 学习后台以 A2A learning 的适用模块为基础裁剪适配，详见第 5.8 节；其他 A2A 与 browser-use Agent 资产按需参考，`browser_use` 桌面壳按第 4.4 节评估提取。
|
||
|
||
### 13.2 当前实施建议
|
||
|
||
已确定以 Playwright 固定执行并在学习/桌面复用同一协议，当前按第5.10节显式新 profile 验证，不另做 browser-use `Agent.run`。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.0 当前主线：学习、固化、召回与变参执行
|
||
|
||
当前唯一实施顺序：先完成可复用平台操作能力，再接运行时业务判断。近期对装修需求、咨询意向和人工核对投入过深，先暂停扩展这些功能，保留代码与历史。学习端不按每个行业重学网页，也不把某次内容判断固化成通用客户结论。
|
||
|
||
三层边界：学习端保存参数、页面节点/定位、动作、等待、输出、成功判据、异常和验证；轻量召回按平台与任务类型选定不可变候选及摘要；运行端将用户意图转成任务/参数，执行同一 Playwright 合同，并按实时内容决定业务分支。当前后台仅提供结构化参数的维护验证入口，不能称桌面端意图识别或桌面交付完成。
|
||
|
||
首条已验收探索范围为“小红书搜索 → 一篇详情 → 有界首层评论”。当前按维护者要求，扩大为当前账号网页版的功能入口与页面层级探索，以下已完成链路作为起点，不再将只读三段视为完整平台覆盖。轻量目录分为 search_notes 和 read_note_comments；首版仅组合同任务、同站、同执行模式的两个候选，复用现有学习会话。先召回预览并固定 ID/摘要，再以新关键词串行执行；多版本歧义要求显式选择，不按最新静默切换。搜索结果按真实编号、合法来源和唯一可定位标题衔接，不套装修词规则。详情候选目前仍从搜索前缀进入，组合验证会进行两次搜索，尚未学到可直接复用结果页的独立详情入口；此限制明确展示，不虚构已经拆成原子动作。
|
||
|
||
阶段验证沿用现有 exploration 浏览器试跑和 validations 证据；组合汇总另记 kind=route，保存召回快照、关键词、选中对象和两阶段验证引用，不创建新数据库表，不参与候选正式质量晋级或发布资格。目录查询、召回、执行均不调用业务分析模型；空结果未学会、标题歧义、会话未就绪、来源不符或预算耗尽时停止，保留已有阶段和部分正文，不能把读取不足判为平台无内容。
|
||
|
||
独立“链路复用”入口、轻量路由及汇总记录已实现，目录只显示最近静态状态，召回和执行前重新核验来源证据；可用输出与失败原始输出分开。组合占用同一任务，外部打开/确认/采集/动作/关闭/单候选试跑及第二组合请求在占用期拒绝，内部两阶段正常执行，结束或失败释放占用。隔离Edge在专用PG上已用两个非装修关键词完成换参、部分结果、无会话停止及重启留档。真实“装修顺序”首轮搜索通过，八步详情在滚动根定位缺失处停止，无请求阻止；旧失败保留。新七步候选 candidate_9d79ad9f21084c5097c039fd2002d3f3 静态通过后，使用同一新词重新验证，组合 validation_35d567240bca4416930f0098c7d79be5 为 completed；本次搜索取得3条，正文1条，首层评论6条，首层评论5批、去重1条、范围截断。新七步以实际补录的640px/最多5批评论步骤替代原3批范围，仍最多6条与15秒批次预算；原7步部分结果未改记通过。 当前随后按第14.0.1节扩大功能入口与层级覆盖；首条链路的更多样本、独立结果页入口和异常仍作为其中一组继续补齐，正式质量及业务层分别后置。工程通过不代替真实平台，单端探索不等于双端或正式发布。pg_search/embedding、通用 Agent、桌面工程和商业模块继续后置。
|
||
|
||
### 14.0.1 当前扩展：功能入口与页面层级图谱
|
||
|
||
维护者要求将作者/评论者主页、关注、私信及更多层级入口纳入学习。当前建立“平台路径”轻量清单，按首页与搜索、笔记与评论、他人主页与联系入口、通知与消息、我的主页与更多五组维护。初始33项只是已登记的功能模板，不是全站功能总数；发现新入口继续追加，不用固定分母或百分比宣称全站完成。
|
||
|
||
每项定义父功能、入口/页面/外站类别及所需页面证据。维护者与Codex按页面类型和转换边广度推进：当前页观察→识别实际可见入口→进入目标页→检查下级入口→记录返回/关闭路径→整理固定候选→变参和分支验证。页面功能与状态去重，层级按实际继续，不固定为一级/二级；本人/他人、图文/视频、公开/私密、空/非空、回复折叠/展开、消息可用/不可用分别列样本或缺口。菜单与标签需要专门记录实际控件，不因页面文字存在就称点击通过。非语义div、未入捕获范围或超过元素上限的入口标为未覆盖；下一步新增固定用途metadata、唯一实际对象核验和面板/选中态/回复父子关系等结果断言，再分别录制与验证，不临时放行任意div。
|
||
|
||
目录范围先列已知入口：发现/频道、点点AI、RED、直播、搜索笔记与用户、搜索筛选排序、笔记详情/作者、评论/回复/评论者主页、主页笔记/收藏/喜欢、关注状态/私信入口、通知分类、消息、我的主页、发布、更多/帮助/设置/创作者等。本站可见外站链接只记入口，外站目标另定义范围；当前用户账号没有的能力标“不适用/不可见待核”，不能补造存在或完成。当前只读导航合同不支持的控件明确待学，不改用任意脚本或强制点击绕过。
|
||
|
||
状态分开：入口已观察、已进入取证、步骤已记录、已固化、探索通过、正式范围通过。轻量页面先按已鉴权任务中的实际URL、可见元素和截图引用显示入口观察，组合链路记录另行核对；capture note只做归类，不能单独晋级。作者与评论者来源边分别登记。关注/取关、消息准备/发送、发布或回复等有状态变化的动作，入口观察与实际执行单独记账；本轮记录入口与下级形态，不向真实第三方发送内容或改变关系。
|
||
|
||
新增显式执行模式 playwright-xhs-navigation-ui-v1，三字段合同为 engine=playwright、action_policy=xhs-observed-navigation-readonly-v1、network_policy=xhs-page-navigation-v1。旧搜索profile、候选和验证不改；新模式单独取证，只允许已观察、实际唯一可用的同站读取锚点与固定目标核对。笔记标准路径别名按同编号核对；公开主页只允许实际省略原链接中各最多一个channel_type/parent_page_channel_type，必须确实省略至少一项，其余有序query、xsec、路径/对象/hash保持一致，无省略仍完整地址相同。明确opener的真实弹窗主框架仅接续原策略及原截止时间，不续签。已声明发现/搜索/笔记、公开主页及通知路径；关注/发送/任意按钮/未声明消息页不自动放行。单次原生通信窗口仍15秒，保留来源、对象、预算和失败证据；浏览器持久登录沿用维护者持续授权，不重复询问账号。
|
||
|
||
当前首轮已有18项可核对观察；发布者主页点击通过，评论者主页最终复验尚未通过。最新实际首页出现官方安全验证，ready已撤销；停止平台动作，由维护者在官方窗口手动完成后重新检测页面状态，不能据持久Cookie自动放行。当前实施顺序调整为：①验证处理后复验评论者来源边；②补安全关闭/返回、标签与菜单、回复展开、通知分类和消息窗口形态；③按模块将有效步骤参数化、冻结并独立变参验证；④补当前账号可见范围的空态/异常、正式基线和任务后反馈。客户意图及业务分类继续后置。工程、本机合成、真实观察、实际步骤、候选与发布结论分别报告。
|
||
|
||
### 14.1 首要：完成小红书只读链路与异常暂停
|
||
|
||
由维护者与本地 Codex 学习“搜索笔记 → 详情 → 评论读取”。先人工示范并观察正常页面，再固化参数、定位、等待、输出和结束条件；变更关键词及样本核对对象、原文和来源。按功能模块逐层盘点当前账号可达的网页版入口，直至已发现模块的下级入口有证据或明确缺口；动态笔记、账号、评论只取样，不将全量动态对象遍历作为“全站路径学习”。
|
||
|
||
真实观察已补齐首个有界样本，继续按以下范围推进，不扩为通用调度：
|
||
|
||
- 任务样本在录制前须能配置；当前没有参数编辑 API/UI，绑定空 `keyword` 会填空。补录前参数编辑须限制为尚无步骤/候选的任务，并保留身份、并发和参数校验；不得改写冻结候选。本次维护填入用户指定样本不代表编辑功能已经实现。
|
||
- 已补失败留证：失败仅追加真实前后及已得批次观察、阶段与安全代码，不插入成功步骤；先核对页面再决定下一步，不将 409 等同于“什么都没发生”。记录最多 30 条被动请求摘要及 12 类去重阻止摘要，阻止总数保留，不含 query/hash、正文、头或凭据，路径敏感段泛化；旧执行器请求不可追溯补出。回放另保存受限错误码。legacy 详情历史与普通读取辅助流量采用各自有限策略；新 profile 按第5.10节固定合同核验原生通信，历史失败不改记成功。
|
||
- 既有 legacy 修订样本输入为 `keyword` 和 `note_title`：正常首页搜索、等待至少 1 条可见标题、按标题唯一选笔记、等待详情、提取正文、首层评论分批去重，共 7 步。批次含首批最多 3 批、滚动每次 320 像素、去重输出最多 5 条，受 15 秒批次预算限制；逐批保存截图，时间/批数/条数/边界分别报告，不能据页面总数称为全部读完。旧 8 步在正式试跑发现首卡无标题导致等待超时，已转待复核；修订采用集合等待。准备阶段另发现平铺匹配会包含已展示回复，故根据实际父容器结构限定首层行。新候选静态及两组正式执行通过，实际得到 3/4 条首层评论，过程复查已登记，后续账号反馈仍等待维护者。字段缺失、目标不唯一、来源变化时停止；legacy 未匹配请求及新模式超出原生通信合同的请求分别停止，不把两种通信范围混同。
|
||
- 下一步收集窗口到期后的官方通知/功能实查反馈，再补真实搜索无结果、评论为空、目标缺失、登录失效/验证与更多读取范围；通用明确空态合同和合成测试不能代替这些平台样本。回复展开及父子关系单独学习，业务相关性和采购意图按第 14.2 节推进，不把当前精确标题选择当作已经自动选内容。
|
||
- 已补视口优先、离屏候选限额、隐藏正文排除与独立视口文字，以及搜索回车和明确点击产生的同源新页接续。图标和平台结构的覆盖仍须真实页面验证；提醒判断结合实际可见状态与画面，后续官方通知继续单独人工复查。已补可见页面登录检测，先检测持久会话，再决定是否需要登录或账号确认，见第 4.2 节。
|
||
|
||
探索时允许记录登录失效、非真人提醒、验证码、操作频繁和权限异常，保留有效知识和中断依据；无法识别或支持的状态列为缺口。随后对冻结版本独立验证完整任务、操作路径、对象和结果，并在任务后核对官方通知及功能反馈；观察未完成、出现提醒或状态未知的版本不进入用户可用清单。恢复和重新验证按第 5.10–5.11 节执行。
|
||
|
||
### 14.2 后置：保留的业务判断与自然语言验证
|
||
|
||
以下业务合同和已实现记录保留，当前暂停扩展；不再把咨询分类评测或人工标注作为学习链路复用的下一步前置。完成第14.0–14.1节后再按实际运行需要验证轻量业务层：商家自然语言 → 条件解析与人工确认 → 固定选择已学搜索/阅读 → 逐源内容判断 → 条件匹配与下一步建议。学习的是可复用平台能力，业务判断每次根据当前输入和实际内容重新运行；两者独立留档。后台先验证与未来 Electron 相同的业务合同，后续桌面接输入、会话及展示，不另写一套需求判断。普通信息问答、通用 Agent、重型能力召回与桌面工程继续后置。
|
||
|
||
首个业务样例已由维护者确认为“装修服务，寻找有装修需求的业主”；服务地区尚未提供，保留未设置，不自动补城市或全国范围。实施按以下顺序推进，各项当前状态分别说明：
|
||
|
||
0. **已实现，验证范围有限：商家需求工作台。** 在“内容初筛”顶部提供“商家需求”入口。模型从最多 2,000 字任务文字提取平台、服务、目标客户、1–3 个搜索词、服务地区及是否排除服务推销，逐字段引用原文；缺项、范围不支持与解析失败分别返回，不自动套用装修规则或全国地区。维护者查看原文后显式确认全部条件，追加不可变确认版本，注明 `maintainer_edit`，不把人工补充伪装成模型证据。地区可明确保留未知，但后续不能判定地域已匹配。
|
||
|
||
`business_briefs` 在学习账本以 schema 8 保存解析、确认、父版本摘要、来源、提示/结构版本、配置和实际用量。解析使用与内容分析相同的可配置模型客户端、受限主备和超时策略；有效同输入/配置/版本复用，失败不自动重试。模型 Key 与供应商私有参数不进入前端。确认无需再调用模型，不原地修改草稿或旧确认。
|
||
|
||
当前确认版本只固定路由到装修样例的已学搜索和单篇评论阅读；“用于本次初筛”仅使用第一个搜索词，其他候选词保留，不自动轮询。初筛创建接口只接受候选和条数，关键词/服务/客户/地区由服务端取已确认快照；新初筛与阅读传递确认编号和摘要。仍须选择已有候选并使用其已确认会话，不自动登录或切换账号。旧结构化初筛入口保留，不能冒称已确认自然语言任务。旧阅读可显式选择新条件进行独立分析，原阅读不重写。工程假页面闭环与真实已有阅读分析分别报告；尚未据此验证任意自然语言任务或商家桌面运行。
|
||
|
||
1. **首段已实现：结构化搜索、规则初筛与单篇阅读衔接。** 独立冻结四步搜索候选，读取当前有界结果的标题、作者和笔记来源；装修样例按透明规则保留最多 1–3 篇待读笔记，相关同行案例仍可作为评论来源。当前服务/客户条件限定为已支持的装修样例，其他业务不得沿用该规则冒充定制判断。按笔记 ID 归并，缺标题、重复/冲突标题、脱敏标题或非同站笔记来源不自动选择。后台“内容初筛”保存条件、规则模式、候选摘要、搜索验证、证据与全部理由，失败与历史追加留存；只保存地区条件，不作地域过滤。严格 `nonempty` 仅核对提取结构，不表示内容语义正确或已确认业主。
|
||
|
||
已补单篇阅读入口，兼容已学七步详情/首层评论链路，以及增加点击前有界目标滚动的八步修订合同：服务端只从当前初筛实际保留的笔记取得关键词、标题和编号，不接受另外传入标题或 URL。每请求一篇，绑定详情候选及其已确认会话；候选须同平台/站点，不自动切换登录。标题须唯一，滚动定位及点击前核对真实链接编号，点击后及后续读取/批次内持续核对页面编号；正文标题与来源再由后台比较。绑定输出来源去掉查询/片段，旧无绑定候选与历史不改。这里是当前浏览器内的对象核对，尚非独立身份的业务读回。
|
||
|
||
每次阅读追加 `reading_runs`，关联初筛、详情版本、实际验证、截图及错误。完整成功、正文已得但评论未完成、未完成分别保存；未学到评论空态时，零条或缺字段不能当作“平台没有评论”。评论继续按实际条数、批次、去重、结束原因和截断范围报告，不扩为全量抓取。后台可逐篇触发、查看阅读历史及直达详情，不自动重试或将实验候选发布给商家。工程、真实平台与交付状态分别以开发进度为准。
|
||
|
||
**结果重排后的定位采用独立修订合同。** 原七步第二篇因目标离开视口而停止的事实保留；新增八步在集合等待与点击之间明确加入一次 `until_target` 容器滚动。录制和静态校验绑定最新观察的唯一普通纵向容器、目标集合及已声明参数；运行时只在固定容器后代中精确匹配，与随后点击使用同一 CSS 和标题参数。目标完整可见且可操作时零滚动；否则按明确方向、距离、次数和时间移动容器。目标重复、编号不符、遮挡、来源/根变化、边界或预算耗尽时停止，不换对象或直跳来源。按步位保存实际次数、逐次位置/高度及停止原因，定位记录不代替来源核对。仅八步绑定回放在原 90 秒总预算上增加该滚动预算（最多 15 秒），单步仍限制最多 10 次、每次 1600 像素。
|
||
|
||
修订版须分别验证零滚动、搜索重排后的实际移动、目标消失和预算失败；合成测试与真实平台样本分别报告，不把新版本通过改记为旧版本成功。平台结构变化、更多结果范围与异常样本继续受候选版本约束，暂不扩大为全量读取或自动重试。
|
||
|
||
总预算还须覆盖单步执行与取证。首次八步回放暴露“只在步骤间检查”不能阻止单步越过预算，最终触发 120 秒工作进程超时、未返回完整验证。已补硬截止，并在总额内预留 2 秒关闭和返回：到期即停止本次执行并关闭其浏览器上下文，资料目录保留；只返回已完成的正文、步骤/批次证据和实际定位记录，不等待或补记迟到成功。确认关闭后后台撤销可执行状态，须重新打开并确认会话，不自动恢复。原超时阅读保留为无完整验证的失败，不据此断言页面没有发生动作。修复的工程与真实回放状态分别见开发进度；单步预算、对象绑定和旧历史继续保留，随后处理下项评论覆盖。
|
||
|
||
步骤耗时已能区分检查、读取与取证，真实媒体回放暴露逐步重复整页候选发现的成本。已将已观察定位的“当前检查”限定到该目标或滚动根，复用原元信息构造、定位语义、敏感判断、固定对象及来源核验；每步后与每批仍保留完整观察和真实截图。限定检查与原整页检查已做元信息等价及完整回归，同一冻结候选两篇追加探索通过，清单、原失败和预算未改。有限样例中当前检查成本明显下降，后置及批次取证仍占主要耗时；不能据两篇断言所有结果位置或账号都稳定，具体证据与环境见进度。
|
||
|
||
**媒体评论采用显式新内容合同。** 原文字必填遇纯图片的失败和已得批次证据保留，旧候选不改。新修订将正文声明为 `source:"content"`、`required:true`，配置已观察的普通内容根及其相对文字/媒体定位，最多保留 4 个媒体。输出区分 `text / media / mixed`，保存实际文字或 `null`、图像/视频类型、相对定位及截断事实，不返回原媒体 URL 或文件。只认实际加载、可见的正文媒体，排除头像；缺内容、加载失败、隐藏、敏感或歧义仍失败，裁剪和离屏沿用原范围语义。不能用作者或整行代正文，也不扩大完整行规则来忽略真实缺失。
|
||
|
||
媒体证据使用实际批次截图，统一标为内容未解释；存在媒体不能理解为无需求，当前不做 OCR。普通文字预期只比较原文字段，非空结构预期可确认媒体结构但不确认内容语义。新候选已覆盖真实纯文字和纯图片，混合、视频及异常分支的合成测试不能代替平台学习。实际覆盖以进度为准，未覆盖类型不冒称正式可用；模型首轮只解释实际可用文字，对媒体明确保留信息不足。
|
||
|
||
当前媒体修订样例已按实际图片位置录成独立八步：首层评论上限 6 条、每批滚动 480 像素、含首批最多 3 批，沿用 15 秒批次预算；搜索定位仍为每次 320 像素、最多 5 次、10 秒，整体绑定回放总额 100 秒。原文字样例的 5 条/320 像素及其失败均保留，各候选按自身冻结范围执行，实际条数与结束原因见进度。
|
||
|
||
新搜索页面的滚动方式须按真实观察另行修订。当前“装修公司案例”转入新的搜索页，旧容器定位未观察到，首篇在定位阶段失败且未打开笔记。新增显式 `scroll_scope:"viewport"`：定位仍绑定已观察、唯一、非敏感的普通容器，目标仅在该容器后代中匹配；实际按声明距离滚动页面，并固定核对当前文档滚动对象。页面、容器、文档滚动对象变化，目标歧义、编号不符、遮挡、不符合当前模式通信合同的请求或预算耗尽均停止。保留原次数、距离、时间及来源限制，不允许用 body/html 充当目标范围；缺省仍滚动原容器，不自动尝试另一种模式。旧候选与失败不改，整页模式的本机演示验证和真实平台复验分别报告。
|
||
|
||
**legacy 搜索分页保留独立动作阶段策略。** 实际整页移动 320 像素时，页面自然产生既有 `search_notes xhr` 请求，原通用只读策略拒绝，属于本地执行策略缺口，不据此认定平台提示或账号异常。新 `xhs-search-scroll-experimental-v1` 仅在官网精确 `/search_result` 或 `/search_result_ai` 页面、已观察唯一普通根及显式整页文字目标定位期间生效；私有绑定完整当前页面地址和签发时间，最长 15 秒、当前主框架、动作结束即撤销。只允许原 `collect xhr`、`apm_data fetch` 与精确 `search_notes xhr` 三条规则，不继承搜索历史、onebox、dqa 或笔记打开规则；不主动调用接口，不读取请求头或正文。页面/查询变化、不同发送类型、迟到或其他未知请求仍停止。后台只追加受限版本/规则标记，不保存原始请求信息。
|
||
|
||
既有 legacy 新八步为独立文字评论候选，未观察并声明的媒体类型不继承旧候选覆盖。录制时的零移动定位、正文及两条完整评论只证明各步实际来源；用于观察的额外滚动没有进入新组合，不能据此宣称完整重放已通过。首篇独立来源绑定阅读曾来源与正文通过、评论失败，保留 `partial / comments:null`；整页零移动不证明分页移动。实际批次取证约 20.4 秒，辅助 collect 请求在步骤开始约 22.5 秒后被阻止，与 15 秒边界交叉高度吻合，原日志未直接记录唯一拒因，旧失败不改。
|
||
|
||
**批次截止覆盖在途取证。** 已实现单次同步页面观察内的节点事实与原始文本遍历缓存，缓存不跨调用、页面或滚动；原筛选/排序、上限、敏感掩码、完整观察与逐批真实 PNG 保留。批次最多 15 秒，截止不晚于已签发策略到期，在上限内预留最多 2 秒关闭；到期撤销策略/ready并关闭当前上下文，`BATCH_BUDGET` 区分批次中断，只有实际关闭确认才清除后台会话。总预算先到仍为 `VERIFY_BUDGET`，不重新签发或延长授权。
|
||
|
||
每批行数据及去重计数先暂存，截图完成后，来源、固定根、登录及请求检查通过且未到期才提交。实际失败批次截图可以保留，但不能将其行数据当成完成输出。截止只保留已完整提交、逐批有证据的深复制前缀，继续标记截断与 `time_budget`，关联验证失败、阅读部分完成；未完成首批不返回评论。迟到结果不追加成功，来源漂移、内容冲突或不符合当前模式通信合同的请求，不能借部分输出绕过失败。工程回归与真实页面收益分别见进度。修复后一次真实复验的已完成后置取证约 0.25–0.30 秒，但在搜索集合等待阶段失败，不能据此宣称评论已通过或将整轮 8.141 秒与此前完整前缀 85.404 秒作同范围速度比较。
|
||
|
||
**已补加载过渡与 legacy 等待前置。** 本次搜索回车后的最新观察尚未包含结果集合；旧录制时结果已出现，不能假设未来每次如此。官网等待在进入自动化前须能按已观察定位、当前普通根和既有规则建立只读策略；否则明确 `READONLY_WAIT_NOT_READY`，不在无策略状态下继续等待再阻断页面辅助通信。敏感对象仍独立拒绝，非官网示例等待及原 body 例外不放宽。前置与下述范围等待已实现、隔离验证并加载，真实学习和回放状态见进度。
|
||
|
||
**加载过渡使用显式范围等待。** 新增可选 `wait_scope`，仅用于 `wait + visible + min_count`，须由维护者明确选取最新观察中唯一、可见、非敏感的普通读取根，不能选 body、html 或表单。目标集合可以暂为零项，但只在固定实际根内查询后代；范围外同名元素不计数，至少指定数量的可见、在视口且非忙碌对象出现才满足条件。根替换、页面完整地址或实际页面对象变化、敏感对象及超过 100 个候选均停止。后置仍做完整观察和真实截图，再核对同一根及条件；冻结引用实际根的证据，不补造缺失集合的观察。
|
||
|
||
legacy 范围等待沿用原两条只读辅助规则，按根及当前页面独立签发，不借用搜索权限；显式新 profile 仍核对相同普通根与集合条件，但按原生通信合同建立独立动作窗口，不套用这两条接口名单。`timeout_ms` 最长 15 秒，且不晚于当前策略到期，覆盖轮询、根/集合及登录检查，并在内部预留最多 2 秒关闭；到期撤销策略和 ready、关闭上下文，返回 `WAIT_TIMEOUT`，只凭实际关闭确认回传 `session_closed:true`。通用后置取证在撤销自动化与策略后执行，沿用原截图超时及整轮总预算，不把等待预算扩成整个动作预算；总截止先到仍为 `VERIFY_BUDGET`。旧步骤未声明范围时行为及证据保留，原七/八步阅读结构不变。
|
||
|
||
**legacy 实录和失败保留，当前转显式新模式验证。** 旧记录回车后集合为零、后续范围等待前已有20项，不能称真实轮询从零等到20项。旧独立回放虽建立只读策略，仍因安全状态及 APM xhr 被本地规则阻止，未得正文/评论；不能据摘要认定平台提醒或接口副作用。该失败不改写，新模式也不继承旧静态或执行结论。新增模式按第5.10节允许页面自身合约内自然通信，工具动作、来源、次数和预算仍固定；不靠延迟、改变自动化标志或换路径规避保护。
|
||
|
||
**请求拒因与失败诊断保留。** 同一纯决策函数同时服务匹配与固定拒因；legacy 四策略及其到期边界不变，新模式单独记录原生通信策略版本。拒因区分未建立/未生效、无效时间/到期、会话/页面/主框架/方法不符、地址变化或尚未开始、无效/出范围地址以及资源类型不符。只在实际阻止摘要中保存枚举原因、已签发版本及类型不符时的受限期望类型，不记录完整查询、请求头或正文。不能仅根据安全类路径判断副作用或平台是否已提示异常。
|
||
|
||
新 `failure_diagnostics` 绑定真实失败步位、动作、实际错误码和有界阶段/请求摘要，经服务端再次核验后追加到验证与其阅读；成功不带失败诊断，旧记录无字段不追溯补造。未知请求摘要最多12类，保留阻止总数及覆盖限制；总预算中断时同步快照，迟到回调不改结果。验证、阅读及动作失败共用显示，默认折叠细节，缺失原因显示未记录，不从 `WRITE_REQUEST_BLOCKED` 推断确有业务写入、平台封禁或等待超时。界面不新增放开规则或自动重试入口。失败诊断本身不改变 schema；新执行模式的可空任务字段见 schema 10。
|
||
|
||
**08–09阶段的新模式实录与历史记录（后续复用修订见14.0）。** 新任务 `learn_cbf78367730748b59da7cc0c2ec6f4f3` 共9条成功步骤；四步搜索候选 `candidate_6c67fdac11624f53b8ebb07451a5fe45` 和八步详情候选 `candidate_6c5f1066ff6d42e68c0a7e889e6061e4` 分别静态通过，详情摘要为 `e435f1973e6c6f828744e01b92dc446496b5fe6b959741d57ba0d780a30641e0`。录制定位实际整页移动0→320一次到目标；范围等待前后均18项，不称从零集合等到结果。录制评论为3批、1条完整，`truncated:true / stop_reason:batch_budget` 表示批次数上限，不是时间硬截止；这与随后回放的评论结果分别保留。
|
||
|
||
**首篇一次独立有界阅读探索通过。** `reading_d529b7e1a6db46b7801922acab373964` 关联 `validation_ff910a5ee1d74e8db51e103cdfb07d58`，模式为 `exploration`，搜索至正文/首层评论完整八步通过，来源绑定与实际新profile三字段合同一致；取得正文1条、完整首层评论2条、3批，范围截断，不代表平台全量评论。工作进程14.297秒（含入口4.488秒），服务端16.453秒，范围与计时口径分别记录；回放目标已可见、实际滚动0次，不冒称本轮验证了搜索分页。来源仍是既有 `discovery_40adbe10d64f4542b801562e4afb73bc` 的保留笔记；搜索四步候选尚未单独初筛回放，不能把详情链路搜索前缀通过当作新模式搜索初筛闭环已验收。旧来源、4条旧阅读、2个旧候选及14条旧成功步骤逐字读回不变。
|
||
|
||
**业务层历史进展与后置安排：咨询合同已有有限真实结果；当前实施顺序以第14.0节为准。** 维护者已确认两条短评论“有咨询意向，可保留为线索，实际装修需求待核实”；经同一受限入口由Codex代录的两条旧版 `corrected` 记录保留，备注注明对话确认及代录来源。旧纠错仅将表达由未知改为提问、业务相关性由不明改为相关，保持 `role:unknown / demand:insufficient / match:insufficient`，不补身份、地区或自身项目事实。正文仍未人工核对，原模型和旧五轴核对不迁移、不补新标签。
|
||
|
||
已实现有界、可追溯的笔记背景与独立 `consultation`（`yes / no / unclear`），与自身需求和业务匹配分离。服务端为同一来源绑定阅读生成 `note.context_refs=[]`、`comment_N.context_refs=["note"]`，正文只向模型提供一次，不复制到每条评论；来源仍最多21个、文字16,000字，不发空文字媒体源。每条咨询结果分别保存本源 `evidence` 和 `context_evidence:[{source_ref:"note",evidence:["笔记逐字依据"]}]`，最多一个背景来源、有依据时每类1–3条引用、单条最长1000字。yes/no须有本源依据，yes还须业务相关且有提问、求建议或自身需求表达；评论yes必须有其所关联笔记的背景依据，unclear可空。所有引用按对应来源逐字核对，其他评论、外部来源、未声明输出及动作字段均拒绝。服务正文可帮助理解联系方式短句的咨询对象和相关性，作者或其他评论者的需求、项目地区、预算和身份不能继承为本评论者自身事实。
|
||
|
||
新提示/结果为 `renovation-demand-v4 / demand-result-v3`，保存独立追加分析，复用要求版本、阅读、配置和商家条件均一致，旧分析不能被当作新版本完成。程序仅派生 `lead_disposition:retain_for_review / not_selected / insufficient` 和有限展示建议；业务相关、未按商家条件排除的咨询yes或自身需求可保留待核，不把咨询、相关性或“保留”升级为已确认需求、客户身份、地区及 `match`。咨询yes且原建议为跳过或补信息时，改为 `review_consultation`；模型不能直接输出动作计划。新字段保存在现有JSON分析/核对事实中，无数据库schema变更或线索表，也不引入完整A2A、自主Agent或联系动作。
|
||
|
||
代码、离线合同及已保存两条标注的合同验证已完成；离线检查没有模型、API或数据库调用，不是语义质量评测。服务已受控重启加载，只对同一已保存阅读创建独立新分析，没有重读平台。首轮真实模型输出未通过合同，失败原样保留；新增仅含固定检查枚举的无文本诊断后，后续独立调用完成，将两条评论判为咨询yes并保留待核实，同时自身需求、身份、地区和匹配继续不足。后续未重现首次失败，不能据此确定首次具体拒因或宣称修复了该原因。旧阅读、分析、两条人工核对及步骤逐字读回不变，新分析没有自动继承人工标签。后续恢复业务层验证时，再用固定评测集补服务推广、单纯赞美、询问他人进展等正反例及真实标注，分别核对咨询与自身需求，保留无效输出；有限同向样本不作整体准确率或稳定性验收。新四步搜索候选的独立验证、新来源衔接与正式基线已前移至第14.0–14.1节，先于业务分类扩展；不自动重读、扩第二篇或执行联系。浏览器已受控关闭且未重开，本轮分析不需要重新扫码或确认平台账号；平台链路、正式基线、账号后续反馈及Windows/macOS桌面交付仍分别验收，尚未发布。
|
||
|
||
新输出合同失败仅在实际新记录中可保存 `output_diagnostics:{check}`：枚举限定来源图、旧字段/覆盖/引文/角色/表达/自身需求/相关性/事实，以及咨询字段/值/依据/背景/组合，共16类。允许范围和 `MODEL_OUTPUT_INVALID` 不变，不保存原始模型输出、来源编号、URL或私有错误；缺失原因不追溯补造，成功不带失败诊断。它只定位固定检查，不证明语义正确，也不触发自动重试或切换模型。
|
||
|
||
修订候选可显式选择本任务已记录成功的真实步骤编号，1–30 个、不得重复、按声明顺序冻结，保存 `source_step_ids` 及完整动作前后/批次证据引用；不接受客户端另造步骤、修改原步骤或传入原始清单。未知、异任务、空或重复编号拒绝且不创建候选；缺省全步骤行为兼容保留。选步后的新版本仍须独立静态检查、合同核对和完整回放，不继承旧验证或质量结论；证据闭合不代表重新组合后的前置条件和时序已经跑通。
|
||
|
||
步骤耗时保存为受限 `step_timings`，含步位、动作、完成/失败/中断、实际毫秒数及独占阶段。当前检查、目标解析、执行、就绪等待、请求核验和前后/失败/批次截图分别记录；未发生阶段和旧记录不补零。`verify_timing` 保存总、入口与关闭耗时，未尝试关闭为 `null`。中断保留真实前缀和已得结果，返回数组值复制，迟到回调不补成功；不采集页面文字或参数作计时标签。按实际阶段成本优化，不靠扩大已有预算证明成功。本次已基于来源核对通过的有界文字进入第2项独立需求判断；模型只使用实际可用内容与明确缺失信息，运行通过不替代业务核对。
|
||
2. **已接入，当前验证业务质量：独立、可追溯的模型需求与咨询分析。** 当前代码提示为 `renovation-demand-v4`、结果为 `demand-result-v3`，咨询及背景合同见上文；旧 `renovation-demand-v3 / demand-result-v2` 分析保留。分别保存当前发言角色信号、可多选表达、自身需求、业务相关性及独立咨询意向；例如“我家准备装修，问大家顺序”同时属于自身明确需求、提问和求建议。“哪里”不足以确认服务方，服务方也可同时有自身需求，不能按账号角色一刀切排除。普通讨论、提供/推荐服务、已完工分享和单纯赞美不自动成为发言者自身需求。阶段、地区、预算只提取该发言者自身项目的原文事实，不把设计师所在地当作客户项目地。原版本结果保留，歧义仍待标注，不作账号身份或客户确认。
|
||
|
||
服务端根据当前确认条件及已校验判断固定派生初步匹配、保留待核、理由和建议；模型不输出可执行浏览器计划或跟进文案。地区未设置、缺项目地区或地名用词不同均保留待核，不擅自做行政区包含或判定异地不匹配；仅明确选择不限地区才跳过地域条件。排除服务推广只排除无自身需求的当前提供服务表达，不屏蔽服务方自身需求，也不丢弃同行笔记下面的潜在需求评论。建议区分核对作者、核对评论者、核对咨询意向、查看评论、补充信息和跳过，当前均为展示，关注/私信/评论不可执行。
|
||
|
||
分析只取来源核对通过、已有可用正文的完整或部分阅读，不重新操作平台，也不接受客户端另传文字、标题或来源。分析作为独立追加事实绑定阅读摘要、商家条件快照/摘要、模型配置、提示/结果版本与实际输入来源，复用键包括业务上下文；变更条件不会误用旧匹配结果。阅读已绑定确认条件时默认继承；旧 `POST {}` 沿用原初筛条件并明确来源，不冒称维护者确认。旧初筛、阅读及其“未调用模型”字段保留。模型只接收有限文字、临时来源引用和必要业务条件，不接收作者、真实对象 ID、链接、页面图像或凭据；页面文本按非可信资料处理，不能改变分析任务或触发工具。
|
||
|
||
服务端核对每项来源、结果覆盖、固定分类和逐字证据；阶段、地区和预算的值及依据均须来自对应原文。纯媒体由程序标为信息不足、内容未解释；缺失、裁剪及部分阅读范围明确保留，不能自动补完身份或将结论当作已确认客户。首轮最多 21 个来源、16,000 字，超限拒绝且不调用模型；不悄悄截断后声称完整覆盖。结构正确和引用真实只能证明结果可追溯，不能证明分类准确率。
|
||
|
||
安全状态、分析触发、逐条依据、主备尝试、Token、固定失败及历史已通过独立 API/UI 展示；不暴露密钥、接口私有参数或提供商原始错误。历史“查看分析”使用独立打开状态，每次点击直接展示详情侧栏，同条关闭后可重开；分类与原文依据优先，技术配置及用量折叠。打开和切换历史只改变界面，不调用模型或修改分析；人工核对另按下项显式保存，查看和预填不算已经核验。
|
||
|
||
隔离提供商与PostgreSQL回归、既有阅读的有限调用保留。旧 `analysis_aae778abf4c5410aae59a9089c016ec4` 采用v3提示/v2结果，主槽 `deepseek-flash` 一次完成，约2250毫秒、1822 Token，实付金额未知。正文服务推广的模型判断引导查看评论；两条联系方式短评论的原模型 `insufficient / role:unknown` 保留。维护者已确认咨询意向，两条旧人工纠错只调整提问表达及业务相关性，自身需求、角色、匹配和地区仍待核实；不据此修改默认型号或将人工意见一致性当作分类准确率。新上下文和独立咨询意向代码已实现，真实模型分析另存修订且不迁移该旧标注；后续型号对比仍用同一标注集分别评估漏判、误判、耗时和成本。
|
||
3. **已接入五/六轴人工核对，下一步积累真实样本。** 完成的v2分析使用原五轴，完成的v3分析增加独立咨询意向为六轴；详情提供醒目“人工核对”和每源入口，原文、笔记背景、原模型标签与人工结果分开显示。维护者显式选择“判断正确”“需要修正”“暂不能确定”或“当前文字不可核对”；首次预填原标签但不预选决策，也不自动保存。修正需实际改变当前版本至少一轴，并填写说明和1–3条本来源逐字引用。新版yes/no咨询须有本源依据，评论yes还需关联笔记逐字背景依据；不确定/无法核对须清空标签和背景依据并写原因。不能凭咨询意向补身份、需求或地区，不能将未知地区修成已匹配；纯媒体只有后两种未判定状态，不借文字核对冒充图像理解。
|
||
|
||
`analysis_reviews` 沿用schema 9追加表：v2分析继续保存 `analysis-review-v1` 五轴，v3分析保存 `analysis-review-v2` 六轴及独立 `context_evidence`。均保存原分析/来源摘要、原模型标签、维护者、决策、人工标签、依据、说明及前版引用；原分析、来源和旧核对均不修改，新合同无需schema变更。旧v2请求不接受新增咨询/背景字段，更早或失败结果只读，不补造维度或允许不完整结果晋级。每个来源修订追加版本，按原先读到的最新编号做事务核对；并发或旧表单409后刷新并要求重新核对，不自动重发。明确422校验拒绝显示安全原因并允许继续修改；成功、校验及冲突反馈自动滚入核对侧栏视野，避免长表单只看到禁用按钮。API与维护入口沿用鉴权、归属和CSRF，不调用模型或操作平台。
|
||
|
||
统计每个来源最新版本：已保存核对/待核对、已判定、正确/纠错、暂不能确定/文字不可核对分别计算，修订历史不重复计数。一致率只以“判断正确 + 需要修正”的已判定样本为分母，无样本为未知；另列各轴差异数。界面展示原模型结果，这是辅助核对一致性，不能称为独立评测准确率、精确率或召回率，更不能将暂不能确定、媒体、未核对项算作正确或错误。
|
||
|
||
首批核对范围为第一篇正文及两条有歧义评论。可在界面显式保存，或由用户在对话中确认已展示的具体来源和判断后，通过同一受限入口由 Codex 代录，备注注明对话确认和代录来源；不能根据一般业务讨论推定其他样本结论，也不能伪装成用户点击界面或独立盲标。首批三项已保存：正文确认、首条评论仅纠正表达类型，第二条评论由用户选择上下文不足并保留不确定；只有前两项计入已判定，角色、地域与需求缺失不强行补齐。这三项仅作有限质量对照，程序与 Codex 不代作余项真实人工判断。随后补地区、服务方兼具自身需求、同行内容下需求者等有限真实样本，形成独立标注集后再评估误判、漏判、费用和默认模型；不据这两项已判定样本直接修改默认模型或宣称准确率，业务样例的质量核对后置于平台链路复用验证，不能据此阻断行业无关的操作能力建设。线索归并、普通信息问答及新业务单独评估，关注、私信及回复仍按第 14.3 节单独学习。
|
||
|
||
“案例或服务展示内容→评论者自身需求”分支已取得新模式首篇服务推广正文及两条联系方式短评论，并完成旧版独立模型分析。两条旧版人工纠错已保存：`review_3edb0c3a1ca54a468e30870174150e86`（`comment_1`）、`review_ade9c9f4b0f649d6844019eb6a8d4e98`（`comment_2`），均注明维护者对话确认、Codex代录；可保留待核实咨询意向，不确认实际装修需求、身份或地区。该旧分析3个来源中已核对2个、待核对1个（正文），已判定2个；原模型完整读回不变。它的五轴备注不冒充新咨询状态，也不迁移成新版本人工标注；新合同代码和离线验证已实现，真实新分析及其业务质量另行验收。独立咨询展示不等于线索库，不将有咨询意向、正文服务推广或有限阅读通过当成本分支自身需求质量已经验收。
|
||
|
||
当前标题规则只用于验证发现与初筛流程。真实“装修案例”搜索中，部分相关内容标题并不含装修词，规则没有保留，不能据此断言平台没有合适内容或客户；后续需结合正文、评论与标注样本评估漏判。公开笔记编号与手机号须按字段语义处理：只对已核验官网的标准笔记来源路径保留公共编号，敏感查询、片段及普通文本继续脱敏，不改写历史记录。
|
||
|
||
### 14.3 再后：关注、私信及评论回复
|
||
|
||
先补写操作的范围、测试对象、对象/评论层级核验、独立结果核对及去重，再按已有授权执行限定测试。每种动作单独验收，分别处理已关注、已发送、评论层级不符、平台阻断和结果未知。正常步骤由固定链路控制，模型只在明确需要时处理内容；未知结果不自动重发。
|
||
|
||
### 14.4 按规模扩展检索与交付
|
||
|
||
能力目录扩大或简单路由出现可复现不足后，再按需要采用正向能力文档、BM25/向量融合和独立召回评测；历史内容/线索检索单独定义对象和范围。已有检索扩展保留，模型和索引配置届时按实际方案验证。
|
||
|
||
平台链路与业务质量稳定后，再恢复 Electron 商家端、双端安装/升级及商业网关。未来 Windows/macOS 仍须分别验证相同业务范围；当前后台验证不替代双端交付，也不要求现在建设完整桌面或 A2A 调度体系。
|
||
|
||
已确定的优化更新本节或其所属章节，说明问题、顺序和验收依据；进度记录引用当前规划。一般解释问答不新增计划。
|