6.7 KiB
assistant
面向国内商家的 AI 获客助手，已开始建设本机学习与验证后台。
首版桌面端同时适配 Windows 和 macOS，两端按同一业务范围开发和验收。
产品设想是让商家配置商品与目标客户条件，由软件通过搜索或浏览视频发现相关账号，再结合主页和评论识别潜在需求，整理线索并执行后续跟进任务。
当前文档
- 开发进度：逐轮记录实际完成、验证、未完成项与提交状态；每轮结束前更新。
- AI 获客助手方案图解：独立离线 HTML，包含架构、获客、学习发布、AI 额度、任务恢复、登录会话与实施阶段；支持节点查看、路径演示、明暗主题及 SVG、PNG 导出。
- AI 获客助手整体方案：设计决定、优化方向和实施顺序的当前依据，第 14 节维护近期规划；调整时同步现有方案与图解。
- AI 获客助手初步讨论方案：业务场景、学习固化链路、AI 分工、端形态、收费思路及首版验证范围。
当前路线
- 使用 Electron 开发 Windows、macOS 双平台桌面端。
- 以 Playwright 固定执行为主线，Midscene 作为可选辅助；学习后台以 A2A learning 的适用模块为基础裁剪适配，桌面壳另行提取验证。
- 学习端围绕少量平台操作完成观察取证、结构化整理、候选生成、固定校验、变参试跑和版本发布，运行异常回流维护端修订。
- 首期由开发者与本地 Codex 协作学习：维护者在平台页面登录，Codex 观察、编写参数化实现、提交候选并依据校验和试跑结果修订；后台管理证据与版本。后台内置自主学习 Agent 后续按需求建设。
- 学习后台使用独立 PostgreSQL，检索库准备
pg_search与pgvector；商家桌面端仍按 SQLite 规划。平台账号在官方页面自行登录，每个账号复用专用浏览器资料目录。 browser_use测试工程的 Electron 桌面壳、产品认证和管理后台作为候选复用基础；云端可沿用其 FastAPI 骨架，本地 SQLite、获客执行与商业模块按当前方案适配或新增，范围见整体方案第 4.4 节。- 模型由我们在运营后台按文本判断、复杂复核、视觉操作等用途配置，不绑定具体型号。
- 第一条学习链路选定小红书「搜索笔记 → 详情 → 评论读取」，先用本机演示页跑通学习与验证，再在维护者自行登录的平台页面上适配。
项目状态
当前包含方案文档、学习后台前后端和独立的 Playwright 浏览器工作进程。可以建立维护者账号、创建学习任务、打开浏览器人工登录、观察取证、录制参数化步骤、生成不可变候选以及保存校验和实际试跑记录。第一版操作为搜索、详情和读取，尚未接入 AI 自动探索或完成真实小红书链路验证。
当前服务是本机维护工具；Electron 商家端、macOS 实机验收、能力正式发布、AI 网关和商业计量尚未完成。文档中的价格、额度和成本示例不是最终产品承诺。
本项目使用现有 assistant 目录维护，不另建同名项目，也不直接引入完整 A2A 工程作为运行依赖。
学习后台的具体迁入范围见 模块来源与边界。原 A2A 项目保持只读；本项目未复制原运行数据或账号。
本机启动
需要已启动的 Docker Desktop、Node.js 22.12+、pnpm 和 Python 3.12+。在项目根目录执行：
pnpm install
python -m venv .venv
.venv\Scripts\python.exe -m pip install -r apps/server/requirements.txt
pnpm db:up
pnpm exec playwright install chromium
pnpm dev
macOS 创建虚拟环境使用 python3 -m venv .venv，安装依赖使用 .venv/bin/python -m pip install -r apps/server/requirements.txt，其余命令相同。
打开 学习工作台，空数据库首次启动时自动初始化维护者账号 admin，初始密码 123456。已有账号时跳过初始化，后续重启不会覆盖账号或密码。密码以 scrypt 摘要保存。API 默认端口为 8810。可将 .env.example 复制为 .env 调整本机配置；使用已安装的 Edge 时设置 ASSISTANT_BROWSER_CHANNEL=msedge。
平台登录在工作台打开的浏览器中直接完成。首次需要人工确认当前身份，固定账号资料目录用于后续复用；目前没有自动核验平台身份的适配器。学习账本保存到 PostgreSQL，浏览器资料与证据文件保存在 .runtime/learning/，均不提交 Git。
学习数据库
pnpm db:up 创建本项目的独立容器、数据卷和本机连接配置，端口默认为 127.0.0.1:55432。使用固定版本的 paradedb/paradedb:0.26.1-pg17，包含 PostgreSQL 17、pg_search 0.26.1 与 pgvector 0.8.6。随机数据库密码和连接串仅写入被 Git 忽略的 .env，与后台登录密码分别管理。
assistant_learning：维护者、任务、观察、候选和验证记录；默认 schema 为assistant_learning。assistant_retrieval：独立能力知识检索底座，业务索引与模型 embedding 尚未接入。assistant_learning_test：隔离工程测试，每轮使用新建的随机 schema。
已有 SQLite 原型数据时，先停止本项目后台，执行 pnpm db:migrate-sqlite，再启动后台。迁移只向空 PostgreSQL 命名空间复制，同一事务核对行数；原 .runtime/learning/learning.sqlite 及一致备份均保留，不覆盖已存在的 PostgreSQL 数据。未配置 ASSISTANT_DATABASE_URL 时仍可用 SQLite 做离线开发；它不是当前 Docker 学习环境的存储方式。
pnpm db:status 查看容器，pnpm db:stop 停止本项目容器并保留数据卷。普通重启不重建数据库。
检查
pnpm check
pnpm build
pnpm test:server
pnpm test:learning
pnpm db:check
node tools/learning/test-browser-worker.mjs
test:learning 使用隔离的测试库/随机 schema、真实浏览器与本机演示页，覆盖参数化步骤、结果断言、证据回看及重启持久化，不访问真实平台账号。未配置测试 DSN 时回退到临时 SQLite，绝不借用开发库。Windows 默认使用本机 Edge，其他系统默认使用已安装的 Playwright Chromium；可用 ASSISTANT_TEST_BROWSER_CHANNEL 覆盖。单端通过不会被记作 Windows/macOS 均通过。
db:check 实际验证中文 BM25、平台过滤、搜索索引计划与固定样本向量排序，测试数据在专用测试库中创建后清理。样本向量不能代表模型 embedding、召回率或完整混合检索已完成。