# assistant 面向国内商家的 AI 获客助手，已开始建设本机学习与验证后台。 首版桌面端同时适配 Windows 和 macOS，两端按同一业务范围开发和验收。 产品设想是让商家配置商品与目标客户条件，由软件通过搜索或浏览视频发现相关账号，再结合主页和评论识别潜在需求，整理线索并执行后续跟进任务。 ## 当前文档 - [开发进度](docs/开发进度.md)：逐轮记录实际完成、验证、未完成项与提交状态；每轮结束前更新。 - [AI 获客助手方案图解](docs/方案图解.html)：独立离线 HTML，包含架构、获客、学习发布、AI 额度、任务恢复、登录会话与实施阶段；支持节点查看、路径演示、明暗主题及 SVG、PNG 导出。 - [AI 获客助手整体方案](docs/整体方案-v0.2.md)：设计决定、优化方向和实施顺序的当前依据，第 14 节维护近期规划；调整时同步现有方案与图解。 - [AI 获客助手初步讨论方案](docs/初步讨论方案-v0.1.md)：业务场景、学习固化链路、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 工程作为运行依赖。 学习后台的具体迁入范围见 [模块来源与边界](apps/admin/source-provenance.md)。原 A2A 项目保持只读；本项目未复制原运行数据或账号。 ## 本机启动 需要已启动的 Docker Desktop、Node.js 22.12+、pnpm 和 Python 3.12+。在项目根目录执行： ```powershell 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`，其余命令相同。 打开 [学习工作台](http://127.0.0.1:5179)，空数据库首次启动时自动初始化维护者账号 `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` 停止本项目容器并保留数据卷。普通重启不重建数据库。 ## 检查 ```powershell 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、召回率或完整混合检索已完成。 ## 远程仓库 [zwt-cmd/assistant](https://github.com/zwt-cmd/assistant)