assistant/docs/AI拓客助手优化方案-v0.1.md

# AI 拓客助手优化方案 v0.1

状态：用户已要求开始实现。日期：2026 年 10 月 28 日。项目：`browser_use/school-assistant/`，首个平台为小红书。下文保留审核时的设计基线，当前实现及待验收项目见 [DESIGN](DESIGN.md) 和 [PROGRESS](PROGRESS.md)。

建议把产品主线调整为：**用户用自然语言交代目标，助手通过真实页面完成分阶段任务，保留需求证据和执行进度，将验证过的方法沉淀为可复用链路。** UI 围绕对话组织，线索、浏览器、任务进度和评价围绕对话展开。

本次审核决定产品方向、交互和实施顺序。通过后再修改程序；本方案不授权实际关注、私信或其他对外触达。同级 `assistant/` 继续独立。

## 1 已讨论的方向和本次新增建议

| 范围 | 已讨论的方向 | 本版提出的具体机制 |
| --- | --- | --- |
| 任务入口 | 输入一段话，识别意图，必要时再追问 | 可编辑的目标理解卡，显示已知条件、推断和待确认项 |
| 执行范围 | 不强制填写篇数、评论数，不设置软件余额 | 内部分段执行和自动接续；阶段汇报列出已覆盖与未覆盖范围 |
| 评论阅读 | 评论以及展开后的回复都可能有需求 | 保存讨论层级、发言人、回复对象和各自原话，按人判断 |
| 业务链路 | 查找、核实、导出、关注和私信属于不同阶段 | 操作能力、阶段模板、本次计划三层组合，按条件选择分支 |
| 页面操作 | 沿实际页面操作，过程可见 | 每次动作核对页面变化，保留中断恢复点和动作记录 |
| 平台受限 | 停下来告诉用户，提供合适的替代路线 | 暂停受限阶段，保留已完成结果，展示替代路线及切换影响 |
| 经验与评价 | 边做边沉淀，任务结束可点赞或点踩 | 独立复盘形成经验草稿；反馈关联任务、证据和链路版本 |

表格右栏是待审核的落地设计，尚未实现。

## 2 当前问题和改造目标

当前程序已有内嵌浏览器、暂停接管、页面截图、来源保存、文字分析和经验数据结构，但入口仍要求填写业务条件及阅读数量。阅读以首层评论为主，展开回复、主页身份核实、名单导出、关注与私信尚未形成完整链路。

最近分析的实际任务保存了 4 篇笔记和 20 条首层评论，只覆盖了 3 个关键词中的第一个。模型在累计 51/60 步时主动结束，文字却称“预算耗尽”。这说明需要同时修正执行策略和停止原因，不能只改提示文案。本轮经验草稿和复用回执均为 0，现有数据结构也不能代表学习闭环已跑通。详细依据保留在 [D24 日志分析](PROGRESS.md)。

改造后的验收应回答三个问题：能否按用户真实目标完成合适的阶段；每条线索是否有可核实的来源和正确归属；下一次遇到相似任务时，能否可靠复用上次验证的方法。客户是否回复、是否成交另行记录。

## 3 对话入口和桌面布局

### 目标理解

用户可以说“我做杭州装修，帮我找最近准备装修的人”，也可以直接给一篇笔记、一个账号，要求分析、整理名单或继续已有任务。系统先判断本次属于需求研究、发现候选、核对对象、整理导出还是跟进，再生成计划。

一张简短的理解卡显示“要做什么、按什么标准、准备走哪些阶段”。助手自动生成搜索词，并允许用户修改；地区、产品、客户类型不统一设为必填。如果用户只想整理现有账号，就不再追问产品。如果用户要求筛选“适合我的客户”，又没有任何业务背景，才需要补问会影响匹配的条件。

例如，用户说“我是杭州的装修公司，找最近在装修的人，整理名单”，可直接开始搜索和核实。用户说“把这批人私信一下”时，先使用对话中已经明确的名单和话术，只有名单有歧义或消息内容缺失时才追问。追问不应把旧表单拆成多轮必答题。

信息足够的搜索、阅读和整理可以开始，计划卡随进度更新。用户中途修正标准时，保存目标版本和修改点，说明哪些结果需要重新分析。只有新增页面工作需要继续执行，已有来源不重复采集；已有关注或消息记录不会因修改目标而清空。

### 布局

| 区域 | 内容 |
| --- | --- |
| 左侧 | 会话与任务历史，支持回到中断位置、查看既有成果 |
| 中间 | 对话、理解卡、简短进度、线索卡、导出结果、任务评价 |
| 右侧 | 执行中的真实浏览器，可接管；结束后显示带实际时间的只读截图与停止原因 |

默认保持对话清爽。搜索词、筛选依据、经验详情和执行日志按需展开。结果卡可使用“复制、导出、👍、👎、更多”操作，评价入口紧贴它所评价的结果。

## 4 执行范围和停止规则

### 取消人为业务配额

取消默认的“本轮最多阅读”“每篇最多评论”和固定 60 步业务上限，也不引入自建余额或积分。用户主动指定“先看 10 篇”或“只整理这 5 个账号”时，尊重这次明确范围。

页面读取、单次模型请求仍可分批并设置超时。这些属于执行机制，每批结束保存位置、已读集合和待办项，沿同一任务继续，不能把一个批次结束显示为整个目标完成。真实服务的欠费、限流或不可用要准确提示；取消软件配额不表示上游调用免费。

实施时同时核对表单、接口校验、编排、执行器和框架提示中的总量限制，将单次超时与整个任务的终止分开。不能只隐藏输入框，后台仍以旧步数或固定总时长自动收尾。

### 建议的默认收尾方式

开放式“帮我找客户”没有全站读完的终点。建议按当前目标生成检索路线，持续处理可访问的新候选并分段汇报。**关键词尚未覆盖、回复尚未展开、任务仍可推进时，不以固定步数或模型一句总结提前宣告完成。**

当前路线已无新增候选、可访问内容已处理，或持续重复操作没有进展时，给出阶段结果，说明已覆盖范围、未读部分和继续方式。新的行业方向、地区扩展或触达动作会改变目标时，再由用户决定。这里的“阶段收尾”不等于已经穷尽平台或已经找到客户，也不自动安排后台定时运行。

| 状态 | 用户看到的含义 | 后续处理 |
| --- | --- | --- |
| 执行中 | 当前阶段正在推进，有可核实的新进展 | 保存检查点并继续 |
| 阶段结果 | 当前路线处理到一个明确节点，仍可继续或调整 | 展示覆盖情况和后续选项 |
| 已完成 | 用户明确交代的范围和产物已完成 | 提交结果并进入复盘 |
| 等待用户 | 必要信息、登录或验证需要用户处理 | 保存位置，补齐后继续 |
| 平台或服务受限 | 页面限制、真实限流或服务错误阻断相应动作 | 停止受限阶段，说明依据和可选路线 |
| 用户停止或异常中断 | 用户主动停止，或程序未能继续 | 保留已完成结果与待恢复动作 |

停止原因由程序根据实际事件记录，模型只负责解释。模型主动结束、页面无新增、请求超时、平台上限和用户停止必须区分。历史任务的 51/60、59/60 和失败记录继续保留；新策略生效后续跑旧任务，需要记录策略版本和接续位置，旧配额不能继续作为隐藏阻断。

## 5 分阶段链路和证据

主线为：**理解目标 → 搜索发现 → 阅读笔记与讨论 → 判断需求 → 核对主页 → 整理交付或获授权的跟进 → 复盘。** 实际任务可以从任意合适阶段进入，也可以只执行其中一段。

| 阶段 | 核心动作 | 成功依据 |
| --- | --- | --- |
| 搜索发现 | 生成或调整关键词，使用实际搜索入口，点击真实结果 | 记录检索路线和已访问内容，避免只看第一个词 |
| 阅读讨论 | 阅读正文、首层评论，展开相关回复并继续阅读 | 保存实际加载的原话、层级和发言人，核对新增内容 |
| 判断需求 | 按当前用户目标判断每个发言人自己的需求 | 理由能回指本人原话，模糊信息保留为待核 |
| 核对主页 | 点击对应头像，查看主页及页面可见账号信息 | 候选人、评论和主页能对应，未知信息保持未知 |
| 整理导出 | 去重并整理用户要求的字段 | 清晰区分昵称、小红书号、主页链接和笔记标识 |
| 关注或私信 | 关注需明确对象范围和动作，私信还需明确消息内容 | 核对关注状态或实际发送结果，保留动作记录 |
| 复盘 | 汇总结果、阻断、未完成项和可复用操作 | 形成结果卡及有页面依据的经验草稿 |

### 评论与展开回复

正文、首层评论、子回复分别保存，关联所属笔记、父评论、讨论根和回复对象。页面无法确认的身份或关系留空，不能猜补。父评论作者说“我家在杭州”，不能让其下每位回复者都变成杭州客户；回复中引用别人的需求也不能自动归给自己。

展开后先判断是否出现新内容，再采集和去重。遇到入口失效、登录限制或多次没有新增，记录原因并换合适路径。“没有评论”“尚未展开”“只读取了一部分”“当前无法访问”分别表达，不反复点击同一入口，也不把未读内容当成没有需求。

### 需求判断和名单

建议把“正在装修”和“明确寻找装修服务”作为两个独立维度。前者可能符合广泛寻找装修人群的目标，后者才能支持更强的服务意向判断。模型不能擅自把宽目标改成窄目标，也不能把一般交流升级成购买意愿。

例如“我给你 8 万来我家装成这样”可保留为待核信号，同时说明可能是认真委托，也可能是调侃。主页信息、后续上下文和用户纠正可以补充判断，不能抹掉原始出处。

导出建议包括：昵称、页面可见的小红书号、主页链接、需求原话、来源、观察时间、判断理由、待核事项和跟进状态。IP 属地单独保存，不能直接填成项目所在地。未知字段留空并说明；已核对的账号可归并多条证据，未确认同一身份时不强行合并。首版导出建议提供 CSV，后续按使用习惯增加 Excel。

## 6 页面操作和跟进受限

### 自然页面路径

优先沿搜索、结果、详情、评论、头像和主页等实际可见入口操作。点击后确认页面或控件状态变化，阅读过程中保留可接管的浏览器。用户提供的有效分享链接可以正常打开；不手工拼接临时签名链接，也不把固定坐标轨迹沉淀为通用能力。

“像人一样操作”落实为路径合理、状态可见、动作有反馈和失败能停下，不承诺因此不会触发检测。随机抖动鼠标或伪装身份不作为产品目标。遇到验证码交给用户处理。Browser Use 官方也明确说明，浏览器配置不能保证避开或解决所有验证码，见 [Browser Use README](https://github.com/browser-use/browser-use/blob/main/README.md)。

### 关注与私信的授权范围

“帮我找客户”只启动与发现和整理有关的阶段。关注需明确对象范围和动作；私信还需明确消息内容，可复用对话中已确定的话术。信息充分后可以按范围连续执行，无需逐人重复确认；缺少必要内容或范围发生实质变化时再澄清。关注是否是私信前置条件，以当前页面能力为准。

对已关注的对象跳过重复关注；发送超时或结果不确定时，先核对会话记录，不能直接重发。每次动作保留准备、执行中、成功、失败或结果未知状态，应用重启也不能把成功动作当作新动作重放。动作前再次检查用户授权范围和当前账号状态，避免沿用过时计划。

### 红色感叹号和平台上限

将用户描述的红色感叹号作为**立即暂停当前账号私信阶段的信号**：停止继续发送，保存页面提示和截图，区分已发送、失败、结果未知及未发送名单。

只有页面明确提示每日上限，才告知“今日私信达到平台上限”。单独出现红色感叹号时，表述为“发送失败，原因待确认”，不能将图标统一等同于每日上限。未核实前不重试，也不自动给名单下一位发送；不假定次日一定恢复。

暂停后提供可行的独立分支，例如整理导出当前名单、核实已有候选或查看当前成果。先说明每条路线的产物和切换影响，由用户选择；不通过换账号或换入口继续同一种受限发送。小红书社区公约要求尊重他人停止交流的意愿，避免不受欢迎的广告打扰；链路还应记录明确拒绝并跳过后续触达，见 [小红书社区公约 2.0](https://pgy.xiaohongshu.com/help/detail?id=1eda0a065dd894063c2e029a49e8f6a1&userType=4)。

## 7 边做边沉淀的复用机制

### 三层复用

| 层次 | 保存什么 | 示例 |
| --- | --- | --- |
| 操作能力 | 适用页面、参数、前置条件、页面定位方法、成功依据、失败恢复和版本 | 展开一组回复；读取主页可见小红书号 |
| 阶段模板 | 能力组合、顺序、分支、阶段产物及中断恢复方式 | 阅读讨论并核对候选；整理名单；核实后私信 |
| 本次任务计划 | 用户目标、筛选标准、对象、关键词、内容版本、授权范围和进度 | 杭州装修候选名单，先核实再导出 |

行业、客户标准和消息内容属于本次任务，不写死在通用操作经验中。通用经验也不保存个人昵称、评论原话和用户账号；这些留在任务证据和名单内。

### 经验的形成和验证

每个阶段结束或异常中断后，由独立复盘步骤整理执行轨迹，抽取有证据的方法，形成经验草稿。复盘不占用最后几个采集步骤，也不依赖模型记得调用保存工具。

草稿记录来源任务、页面证据、适用条件和已知失败。后续在不同对象或参数下试用，动作的成功依据相符后才能升级为可复用版本。失败则记录不适用条件；页面或关键控件变化时降级或停用相应版本，再验证替代方法。模型总结、一次点击和用户点赞都不能单独把经验升级为“已验证”。

复用时先检查当前条件，成功后继续下一阶段，失败则回到页面观察或明确中断。页面能力、任务事实和业务判断分开保存，避免“复用上次链路”变成重复上次客户名单、搜索词和话术。

## 8 评价和链路推荐

### 任务评价

任务结果下提供 👍 和 👎。点赞一键完成；点踩后可选原因，例如“人群不对”“没有真实需求”“任务没完成”“过程太慢”，也允许自由说明。原因均可跳过，不要求长问卷。

同时支持单条线索纠正，例如“这人已经装完了”“这是玩笑”“这是有效咨询”。反馈关联当时的目标、任务、证据快照、模型配置和链路版本，保留原判断及更正记录。必要时重新分析已有证据，避免为一次纠正重跑整条浏览器链路。

| 评价维度 | 记录内容 | 用途 |
| --- | --- | --- |
| 执行质量 | 阶段是否走通、是否重复、为何中断 | 改进页面能力和恢复策略 |
| 用户认可 | 任务点赞点踩、线索纠正 | 调整筛选和呈现方式 |
| 业务效果 | 是否回复、是否确认需求、是否合作 | 在相近场景中比较链路效果 |

业务效果标明来自用户反馈还是实际页面观察。任务点赞不等于所有线索有效，已发送不等于已回复，已回复也不等于成交。

### 替代路线和效果积累

早期按目标适配度、账号当前能力和已有证据推荐路线，展示“为什么适合、会产出什么、有哪些前置条件”。样本不足时标记为待验证，不先宣称哪条最容易获客。

积累后，在相近业务、目标、地区和执行阶段中比较有效需求、回复、合作及失败原因，并显示样本量和观察范围。避免只按线索数量或点赞数排名；用户否定的候选和未回复结果也应进入评估，防止只记录成功案例。反馈先用于规则、经验和链路排序，不默认等同于训练模型。

## 9 模型和 Search Fetch 的使用

保留当前 DeepSeek 接入，让页面执行使用具备图像理解及结构化动作能力的模型，文字复核使用适合文本分析的配置。模型名称、版本和调用错误在任务记录中可追溯，实施时再核对官方可用版本，不靠升级整个 browser-use 框架解决业务问题。

截图中的 Search/Fetch 可以用于公开网页资料补充，例如行业背景、公开需求表达和链接正文。它们不共享小红书登录态，不能代替登录后评论或回复的实际阅读，也不能把搜索摘要当作已经核实的客户证据。具体能力以 [DeepSeek Search/Fetch 文档](https://api-docs.deepseek.com/zh-cn/guides/search/) 为准。

建议保留显式开启公开检索的设置；开启后助手在相关任务中按需使用，结果标明来源。缺 Key、调用权限或真实服务余额时，清楚提示需要处理的配置，不伪装成“本轮阅读额度用完”。Key 继续仅由本项目设置管理。

## 10 实施顺序和验收

沿用现有 Electron、React、FastAPI、browser-use 和数据库结构，在当前拓客模块逐步调整。先把任务和页面事实表达准确，再完善回复、导出和跟进，最后用真实跨任务验证经验复用。不另建一套总框架，也不恢复学校业务链路。

| 阶段 | 交付 | 主要验收 |
| --- | --- | --- |
| 第一阶段 对话与执行状态 | 对话入口、理解卡、必要追问、取消默认业务配额、准确停止原因、分段接续 | 信息足够直接开始；必要缺项才追问；持续推进不被固定60步截断；部分结果和未覆盖范围准确，暂停重启可恢复 |
| 第二阶段 阅读与名单 | 展开回复、讨论关系、来源元数据、主页核对、账号去重、CSV导出 | 父子发言不混淆；无新增不反复展开；作者信息不再阻断正文；未知ID不猜补；导出可追溯到证据 |
| 第三阶段 跟进与受限分支 | 授权范围、关注与私信动作、动作账本、失败暂停、替代路线 | 未授权不发送；已关注不重复；发送结果未知不重发；红色感叹号立即停后续私信；恢复不会重放已成功动作 |
| 第四阶段 经验与反馈 | 独立复盘、经验版本、跨任务验证、👍👎及线索纠正、路线推荐 | 新对象或参数能复用；页面变化能降级；评价可归因；推荐显示依据，业务效果不冒充技术成功 |

独立复盘和版本记录在前期先具备基础能力，第四阶段验收完整复用闭环。每阶段先做必要的本地验证，再区分真实模型、真实平台和业务结果。第三阶段真实触达验证，仍需用户另行给出明确对象范围和内容；方案审核本身不触发对外操作。

每次交付都报告：**问题出在哪、实际做了什么及验证结果、下一步做什么。** 没有修复或尚未验收的项目继续列出，不能用测试通过代替真实业务完成。

## 11 本轮审核重点

建议按以下默认方案审核，可直接按条修改：

1. **入口与布局**：采用左侧历史、中间对话和结果、右侧浏览器，业务表单退出默认入口，理解卡允许编辑。
2. **收尾方式**：取消默认篇数、评论数和固定步数业务上限；按可观察进展分段继续，无新增或受阻时给阶段结果与未覆盖说明。
3. **跟进边界**：查找整理不自动进入关注私信；关注需明确对象范围和动作，私信另需明确内容，信息充分后按范围执行。红色感叹号暂停整个当前账号私信阶段。
4. **首版交付**：按四阶段推进，名单先支持 CSV；复盘独立运行，经验经不同任务验证后升级。
5. **后期效果积累**：采用任务评价加单条线索纠正，分别统计执行质量、用户认可和业务效果，再逐步改进链路推荐。

通过后将本方案中获批部分同步为正式设计和阶段任务；未获批部分继续保留为建议，不进入运行逻辑。