docs: add initial acquisition assistant proposal

.gitignore

@@ -0,0 +1,30 @@
+# 本机配置与凭据
+.env
+.env.*
+!.env.example
+!.env.*.example
+
+# 本地浏览器状态、运行记录和临时产物
+.runtime/
+runtime/
+profiles/
+logs/
+*.log
+tmp/
+.tmp/
+
+# 常见依赖与构建产物
+node_modules/
+.venv/
+venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+dist/
+build/
+coverage/
+
+# 系统文件
+.DS_Store
+Thumbs.db
+Desktop.ini

README.md

@@ -0,0 +1,19 @@
+# assistant
+
+面向国内商家的 AI 获客助手，当前处于产品与技术方案讨论阶段。
+
+产品设想是让商家配置商品与目标客户条件，由软件通过搜索或浏览视频发现相关账号，再结合主页和评论识别潜在需求，整理线索并执行后续跟进任务。
+
+## 当前文档
+
+- [AI 获客助手初步讨论方案](docs/初步讨论方案-v0.1.md)：业务场景、学习固化链路、AI 分工、端形态、收费思路及首版验证范围。
+
+## 项目状态
+
+当前仓库仅包含初步方案，尚未实现获客平台功能。文档中的建议选型、套餐价格、分析额度和成本示例都不是最终产品承诺。
+
+本项目使用现有 `assistant` 目录维护，不另建同名项目，也不直接引入完整 A2A 工程作为运行依赖。
+
+## 远程仓库
+
+[zwt-cmd/assistant](https://github.com/zwt-cmd/assistant)

docs/初步讨论方案-v0.1.md

@@ -0,0 +1,258 @@
+# AI 获客助手初步讨论方案
+
+版本：v0.1
+
+整理日期：2026 年 10 月 20 日
+
+阶段：初步讨论，尚未进入功能实现。
+
+## 1. 产品目标
+
+为国内商家提供一款可以持续发现潜在客户、判断需求并管理跟进的 AI 获客工具。首批讨论对象是抖音、小红书、快手等内容平台，暂不扩展跨境电商。
+
+商家配置“卖什么、希望找什么人”，软件通过视频、账号主页和评论理解需求，形成候选客户，再进入关注、私信和后续结果记录流程。
+
+以建材商家为例，软件既可以从同行发布的商品视频评论中寻找询价、求推荐和采购需求，也可以直接发现正在装修、选择材料或寻找供应商的用户。
+
+产品核心价值是减少人工搜索、看主页、翻评论和整理线索的重复劳动，同时让客户筛选过程和跟进结果可追溯。
+
+## 2. 当前共识与待定事项
+
+### 2.1 用户已经明确的目标
+
+- 产品以主动发现潜客为主，内容创作可以辅助，但不作为唯一获客方式。
+- 支持关键词搜索和浏览推荐视频两种候选来源，也可以先搜索再继续浏览。
+- 判断视频与商家商品的相关性，必要时进入作者主页继续判断账号角色。
+- 发现同行商家后，进入相关商品视频的评论区寻找有需求的人。
+- 发现作者本人就是潜在采购方时，可以直接进入客户筛选和跟进流程。
+- 自动关注、私信是目标功能，需要拆成可单独验证的操作链路。
+- 复用“先学习页面操作，再固化链路”的思路，运行时避免每一步重新让 AI 探索。
+- 需要能够收费，并控制持续使用带来的模型成本。
+
+### 2.2 本轮讨论形成的建议
+
+- 第一版采用少量固定链路、明确的分支规则和局部 AI 判断，不照搬完整 A2A 架构。
+- 首个平台只选一个，优先验证搜索入口，再增加推荐流浏览入口。
+- 电脑本地执行器与网页管理后台组合是候选方案，手机后续可承接查看线索、提醒和任务控制。
+- 收费优先考虑软件订阅、包内分析额度和超额加量包的组合。
+
+### 2.3 尚未最终确定
+
+首个平台、手机或电脑执行端、浏览器控制方式、具体技术栈、首版自动跟进范围、套餐价格与额度，都需要经过验证后确定。
+
+这些建议不代表已完成选型；当前仓库也没有实现上述平台功能。
+
+## 3. 两条主要业务路径
+
+### 3.1 从同行视频评论中寻找客户
+
+1. 按关键词搜索视频，或者浏览候选视频。
+2. 判断内容是否与商家的商品、使用场景或目标客户相关。
+3. 查看作者主页，结合简介、作品和视频上下文判断账号角色。
+4. 如果属于同品类商家，读取其相关商品视频的评论和回复。
+5. 识别询价、求推荐、采购规格、使用场景和采购时间等需求信号。
+6. 对候选客户去重，保存来源和判断依据。
+7. 进入关注、私信和后续跟进任务。
+
+### 3.2 直接发现有采购需求的用户
+
+1. 搜索或浏览视频，发现作者本人在表达需求。
+2. 结合视频与主页判断其是否为目标采购方。
+3. 核对需求是否与商家的产品、服务范围等条件匹配。
+4. 整理为候选客户，再进入跟进流程。
+
+例如，“装修选什么瓷砖”“求门窗供应商”“准备采购一批材料”等表达可作为待判断信号。不能仅因出现产品词，就直接认定有采购意图。
+
+### 3.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. 学习端先固化哪些链路
+
+学习端的职责是理解平台页面和操作方法，产出有输入、输出、等待、完成判据和失败状态的执行链路。链路通过验证后，运行端按精确版本复用。
+
+首批候选链路可以拆成六类：
+
+1. **搜索与列表读取。** 输入关键词和读取范围，输出候选视频及来源位置。
+2. **视频读取与候选切换。** 打开视频，读取标题、作者、链接和可取得的内容信息，并能继续处理下一候选。
+3. **主页与作品读取。** 进入作者主页，读取简介及相关作品，返回所需上下文。
+4. **评论与回复读取。** 展开评论、回复和后续内容，保留其所属视频、父子关系及读取进度。
+5. **关注操作。** 对指定账号读取当前状态、执行动作并确认结果。
+6. **私信操作。** 打开指定会话、装配消息内容、执行发送并记录可观察结果；准备与发送可分别控制。
+
+关键词、账号链接、读取范围和消息内容应作为参数，不写死在链路中。跟进动作结果不确定时先核实状态，避免直接重发。
+
+各平台分别学习和验证。同平台、同页面版本下的共性操作可以复用，不必为每个商家重新学习完整平台。页面变化后更新对应链路版本。
+
+已有 A2A 学习端的能力包生产、参数化、动作定位、等待和结果核验机制可作为参考。此前查看到的真实验证以分类、校区等业务操作为主，不能据此认定已有抖音、小红书或快手链路。
+
+## 5. 固定链路与 AI 的分工
+
+### 5.1 固定程序负责执行
+
+固定程序负责运行链路、传递参数、遍历候选、保存进度、去重、控制预算和记录执行结果。已经明确的正常步骤不需要模型逐次规划。
+
+在这个场景下，学习端产出少量平台能力，运行端按业务规则选择和串联即可；第一版不要求建设完整的实体目录、通用能力召回和复杂多 Agent 协作体系。
+
+### 5.2 AI 负责三类判断
+
+- **内容相关性：** 视频是否涉及商家的产品、场景或目标需求。
+- **账号角色：** 作者是同行、采购方、普通创作者，还是无法确定。
+- **采购意图：** 作者或评论者是在实际寻购、询价、比较产品，还是讨论、分享或推广。
+
+内容相似、账号身份和采购意图必须分开判断。相似内容不等于潜在客户，同行账号也不等于其所有评论者都有购买需求。
+
+判断输入优先使用标题、简介、评论正文、父评论及必要上下文。已有文字不足时，再按需要增加 OCR、语音转写或视频理解。
+
+每个候选结果应能回溯到原始内容，区分明确事实与模型推断。匹配标准需用真实样本校准，暂不预设一个通用分数作为准确率保证。
+
+### 5.3 生成能力按需增加
+
+AI 可以辅助把商家的描述转换为筛选条件，生成与上下文匹配的消息草稿，以及整理回复摘要。是否纳入首版，按需求与成本验证后决定。
+
+## 6. 端形态与轻量架构
+
+### 6.1 端形态仍在比较
+
+目前候选为手机 App、电脑端执行器，以及电脑执行器配网页后台。建议先验证电脑端方案，因为便于调试、维护链路、查看执行记录和管理任务。
+
+管理界面可以做成网页；控制商家本机已登录的浏览器，通常还需要浏览器扩展或本地执行程序配合。
+
+如果关键功能只能在手机端完成，再评估 Android 执行端。手机查看线索、接收提醒和控制任务，可以与手机直接操作其他 App 分开建设。
+
+### 6.2 建议的首版模块
+
+- **本地执行器：** 商家任务界面、浏览器会话、链路执行、进度保存及异常接管。
+- **链路资产：** 各平台已学习和验证的动作、参数、输入输出及版本。
+- **AI 分析服务：** 相关性、角色、意图判断，以及可选的生成能力。
+- **轻量服务端：** 产品账号、软件权益、分析额度、订单和用量结算。
+- **线索与任务记录：** 来源、判断依据、去重关系、跟进状态及实际结果。
+
+浏览器会话留在本机；云端接口按业务需要接收分析内容。软件供应商的模型密钥由服务端管理，不放进客户端安装包。
+
+### 6.3 浏览器执行方式待实验决定
+
+browser-use 可作为浏览器 Agent 组件参考，WorkBuddy 可用来快速试验流程，自研执行器则便于形成统一产品体验。
+
+现阶段应比较结构化读取、视觉识别和混合方式的准确率、耗时、成本、异常恢复及维护工作量，尚不锁定某一种实现。对于几条已明确的链路，优先验证固定执行，复杂例外再评估 Agent 参与。
+
+## 7. 软件期限与 AI 额度的收费思路
+
+### 7.1 用户提出的两种方向
+
+一是用户向平台充值 Token，再按用量使用；二是按月、按年购买软件，到期续费。第二种需要防止持续模型消耗超过收入。
+
+讨论建议将两者组合：**软件订阅费包含一定分析额度，超额购买加量包；自带 API Key 可作为后续选项。**
+
+对商家展示分析条数或分析额度，内部按实际输入、输出 Token 和模型价格记成本。软件有效期与 AI 余额分别管理，不能将年费直接解释为无限模型使用。
+
+### 7.2 初期试售假设
+
+可以先用一个简单套餐验证，例如：199 元/月、一台设备、包含三万条基础短文本意图分析，超额另购分析包。
+
+该价格和额度仅是讨论示例，不是最终报价。需要结合识别质量、维护、客服、服务器、支付和自身获客成本调整。年付方案可在月度用量分布稳定后再设计。
+
+基础文本分类、深度分析、图片或视频理解、浏览器 Agent 任务应有明确的计量区别。评论分析条数也要与识别出的潜客数量区分，避免把模型判断数量直接当作客户交付量。
+
+### 7.3 同行收费结构参考
+
+- **获客星：** 软件独立订阅、统一星币管理；软件有单独套餐与有效期，套餐可赠送积分，积分用于模型调用、识别和生成等功能。
+- **WorkBuddy：** 软件订阅包含积分，额外需求购买加量包。公开定价中的标准版普通月付为 99 元，基础积分为每月 2,000；另有 50 元购买 1,000 积分、有效期一个月的加量包，限时赠送另计。
+- **Deeke：** 官方价格页检索信息显示 499 元/年的软件服务模式，含升级与支持；未明确披露 AI 用量，不能据此推断包含无限模型调用。
+
+这些信息仅用于比较收费结构，不证明产品效果、真实交付能力或本项目应采用相同定价。公开信息核对日期为 2026 年 10 月 20 日。
+
+## 8. AI 成本控制与量级估算
+
+### 8.1 成本控制思路
+
+固定浏览器动作尽量由代码执行，AI 只接收判断所需的文字和上下文。先去重并排除明确无关内容，再批量调用文本模型；只有需要额外判断的样本进入更强模型或多模态处理。
+
+控制单次输入输出、任务总预算、重试次数和执行时长，按用户记录实际调用成本。同一内容是否复用已有结果，应同时考虑筛选条件和模型规则版本，避免错误沿用。
+
+### 8.2 短文本分类算量示例
+
+阿里云官方文档在核对日列出的 qwen-flash 华北2（北京）、单次输入不超过 128K 的基础价格为：输入每百万 Token 0.15 元，输出每百万 Token 1.5 元。
+
+假设一万条评论平均每条摊销提示词后使用 200 个输入 Token、50 个输出 Token，则总计 200 万输入和 50 万输出，费用为：
+
+`2 × 0.15 + 0.5 × 1.5 = 1.05 元`
+
+这是非思考、短输出的理论算量，不是实测账单，也不表示已经获得一万个潜客。未计入更长上下文、重试、强模型复核、截图与视频分析、浏览器运行以及平台运营维护成本。
+
+模型是否适合建材采购意图识别，要通过样本测试确定；不能只依据低单价选型。
+
+## 9. 第一版验证顺序
+
+### 阶段一：确定一个平台和一个行业
+
+优先考虑用户最近描述的抖音建材场景，但正式首发平台仍需核对网页版所需功能后确定。明确目标客户、相关需求、排除条件和线索判定标准。
+
+### 阶段二：验证搜索到线索的主流程
+
+使用一个账号，先完成搜索、视频读取、主页判断、评论分析、去重和线索展示。自由浏览推荐流作为后续候选入口。
+
+同时记录三类 AI 判断各自的误判、漏判、耗时和费用，避免只看到最终候选数量。
+
+### 阶段三：学习并验证跟进链路
+
+关注和私信分别验证，记录执行前状态、目标对象、动作结果及后续回复。准备消息、执行发送和结果核对分开处理，未知结果先核实。
+
+自动跟进是产品目标，首版开放到哪一步仍需确认；异常接管和可选复核不应被描述为已经实现的能力。
+
+### 阶段四：接入权益与计量
+
+完成产品账号、设备与订阅权益、额度预占与结算、用量记录和加量包，验证额度耗尽、任务失败及重试时的账目一致性。
+
+### 阶段五：扩展复用
+
+在单平台流程稳定后，再增加推荐流、多账号和其他平台。链路学习与运行消费保持版本对应。
+
+## 10. 首轮需要取得的验证结果
+
+- 搜索、主页、评论和跟进链路分别能否完成，失败发生在哪里。
+- 三类 AI 判断的误判和漏判情况，而非只有模型自评分。
+- 每千条评论、每批任务和每条被确认线索的实际成本。
+- 线索来源及判断依据能否回看，同一对象是否会重复进入任务。
+- 中断后能否恢复进度，关注与消息状态是否会重复或无法确认。
+- 商家是否认为结果有用，是否愿意持续使用和付费。
+
+样本验证可先准备约一千条带上下文的评论，并人工标注其中一部分，对比不同模型和筛选条件。样本规模、计量单位和验收标准均属于待细化项。
+
+## 11. 下一轮待定事项
+
+1. 首发平台是否确定为抖音，建材是否作为首个行业。
+2. 电脑本地执行器、扩展与网页后台怎样组合。
+3. 六类链路各自的参数、输出、完成判据及可恢复边界。
+4. 首版是否完成自动关注与消息发送，哪些情况进入待判断或人工接管。
+5. 采用什么模型、哪些判断需要多模态，以及如何定义有效线索。
+6. 软件按设备、账号或团队计费，包内额度与加量包怎样设计。
+7. 现有学习端与 browser_use 项目可复用到什么程度。
+
+## 12. 参考链接
+
+- [获客星官方产品与收费结构](https://www.huokexing.com/)
+- [WorkBuddy 官方定价](https://www.workbuddy.cn/docs/workbuddy/Pricing)
+- [WorkBuddy 浏览器扩展说明](https://chromewebstore.google.com/detail/workbuddy/ajnnogdfpilbhkeggdjlcokgglijmdde)
+- [Deeke 官方价格页](https://deeke.cn/pricing)
+- [qwen-flash 官方模型与价格说明](https://help.aliyun.com/zh/model-studio/qwen-flash)
+- [browser-use 项目](https://github.com/browser-use/browser-use)
+
+外部资料用于产品形态、收费结构和成本量级参考。实际套餐和模型单价可能调整，实施前应再次核对。