59 lines
4.2 KiB
Markdown
59 lines
4.2 KiB
Markdown
# 橘子拓客
|
||
|
||
基于 Electron、FastAPI 和 browser-use 的桌面拓客 Agent。首个平台为小红书：自然语言描述目标 → 必要追问和计划 → 笔记、评论及回复取证 → 需求判断与主页核对 → 名单导出或明确授权的跟进 → 独立复盘和评价。
|
||
|
||
项目目录暂保留 `school-assistant/`；已从学校办事业务转向 AI 拓客。原查课、谈话、角色准入、填报和审批链路不再挂载到当前应用。原设计与说明见 `docs/archive/`。同级 `assistant/` 独立维护。
|
||
|
||
## 安装与启动
|
||
|
||
需要 Node.js 20.19+、uv 和 Docker Desktop。Windows 和 macOS 使用同一组命令，在本项目目录执行：
|
||
|
||
```sh
|
||
npm ci
|
||
npm run backend:setup
|
||
npm run db:up
|
||
npm start
|
||
```
|
||
|
||
Python 环境使用 3.12，依赖锁为跨平台解析；Electron 自带浏览器，无需另外安装 Playwright Chromium。
|
||
|
||
默认 API 端口 8788、Electron CDP 9333、控制端口 8797、PostgreSQL 15433。启动前请确保这些端口未被其他应用占用。源码模式下配置和任务证据在本项目，打包模式在应用 userData。
|
||
|
||
## 配置模型
|
||
|
||
首次可复制 `.env.example` 为 `.env`，也可运行后在右上角“模型设置”填写 Key 并测试。API 不返回已保存 Key；Key 不进入版本库。
|
||
|
||
默认 `deepseek-flash`，官方当前对应 DeepSeek-V4.1-Flash-1017，支持图像输入；可选 `deepseek-v4-pro` 做文本判断，此型号当前不支持图像输入。已为 browser-use 0.13.10 补齐新模型名的 thinking/结构化输出适配，不依赖旧型号别名。
|
||
|
||
没有 Key 时应用仍可启动、描述目标并保存任务，但会明确停在“配置模型”，不会把演示数据当成真实采集结果。
|
||
|
||
## 第一次使用
|
||
|
||
1. 输入一段话说明任务，也可提供实际笔记或账号链接。助手生成可展开的理解卡，只追问必要缺项。
|
||
2. 发现候选先确认交付人数；已给人数、指定页面/篇数或明确一轮范围则直接沿用，不反复追问。按可区分身份的人去重，身份未知来源单列，不凑人数。无默认笔记数、评论数或60步业务上限。
|
||
3. 需要登录或验证码时，任务暂停，在右侧浏览器中处理后继续。
|
||
4. 查看原话、来源及待核结果，导出CSV；作者、评论者和回复者分别判断。结果下可点赞、点踩或纠正单条线索。
|
||
5. 同一对话可以补充条件、修订标准或继续任务。来源与动作历史保留，经验草稿仍需跨任务验证。
|
||
|
||
默认发现整理不实施触达。关注/私信先核对账号与对象，用户选择具体批次；私信另需确定内容。红色失败标记或未知结果会暂停当前账号后续私信，不能自动重发。跟进控件目前经过本地合同和页面夹具验证，真实平台链路尚待单独授权验收。没有读到的内容保留为未知，摘录不代表已确认客户身份。
|
||
|
||
## DeepSeek Search / Fetch
|
||
|
||
可选公开网页资料工具已提供：`POST /api/research/search` 与 `POST /api/research/fetch`。输入区“补充公开网页资料”默认关闭，开启后可补充公开资料。Fetch 可供独立公开资料读取，不使用小红书登录态，不保证能抓取登录后笔记或评论。
|
||
|
||
它们与模型使用同一 DeepSeek Key，独立按请求计费；真实可用性须通过实际账号验证。
|
||
|
||
## 验证与文档
|
||
|
||
```sh
|
||
npm run check
|
||
npm run build
|
||
npm test
|
||
```
|
||
|
||
测试中的夹具和 mock 不代表真实平台或真实模型已验证。当前设计见 [DESIGN](docs/DESIGN.md)，实际完成与限制见 [PROGRESS](docs/PROGRESS.md)。
|
||
|
||
核心模块：`backend/prospecting/` 新业务编排与来源分析、`backend/browser/` 浏览器执行与取证、`backend/research.py` 公开检索、`renderer/` 拓客工作台。当前兼容数据层保留 `school_id/student_id` 内部字段作为工作区/操作者标识，新作用域 `prospecting_workspace` 与旧学校任务和经验隔离。
|
||
|
||
品牌图标成品位于 `resources/brand/`，常规构建自动复制并接入，无需重新生成。维护图标时可通过已有 `sharp` 运行 `scripts/generate-app-icons.mjs`；未在项目安装时，用 `ICON_SHARP_MODULE` 指向现有模块的绝对路径。改名保持原npm包名、appId及用户数据目录，已有Key、登录态与历史继续沿用。
|