146 lines
19 KiB
Markdown
146 lines
19 KiB
Markdown
# assistant
|
||
|
||
面向国内商家的 AI 获客助手，当前优先完成平台链路学习与复用，并按功能模块逐层扩展当前账号网页版可见入口。后台新增“学习 → 链路复用”：选择已学搜索/详情版本，召回锁定摘要，换新关键词执行并核对正文、有限评论和来源，全程不调用业务分析模型。
|
||
|
||
真实小红书以新词“装修顺序”完成独立搜索到详情/首层评论的组合探索：搜索3条、正文1条、评论6条，5批、去重1条、范围截断。旧八步定位失败与首个七步部分结果保留；补录长正文评论范围后冻结新的七步候选，完整复验通过。这是当前可见结果范围内的单样本探索，正式基线、任务后反馈、双端和发布仍待验收。
|
||
|
||
装修初筛、商家条件、需求/咨询意向和人工核对已有实现与历史保留，当前暂停扩展，后置到操作复用闭环之后；后台业务验证不代表桌面端已经完成。当前状态与证据见开发进度，唯一后续顺序见整体方案第14节。
|
||
|
||
首版桌面端同时适配 Windows 和 macOS，两端按同一业务范围开发和验收。
|
||
|
||
产品设想是让商家配置商品与目标客户条件，由软件搜索或浏览图文/视频，结合主页和评论识别需求，整理线索，并按配置关注、私信、评论或回复指定评论；也可按用户问题检索信息并返回来源。
|
||
|
||
后台“学习 → 平台路径”（/#/platform-paths）维护功能层级与证据状态；初始33个模板不等于全站总量，当前18项有可核对观察。发布者主页导航通过，评论者主页最终复验在官方安全验证处暂停；菜单/标签/回复与消息窗口仍待补学。入口可见不等于动作或固化通过，动态内容取样，业务分类继续后置。
|
||
|
||
## 当前文档
|
||
|
||
- [开发进度](docs/开发进度.md)：记录实际开发、修复、工程验证及提交状态；普通解释与使用问答不记录。
|
||
- [AI 获客助手方案图解](docs/方案图解.html)：独立离线 HTML，包含架构、获客、学习发布、任务与检索、AI 额度、任务恢复、登录会话与实施阶段；支持节点查看、路径演示、明暗主题及 SVG、PNG 导出。
|
||
- [AI 获客助手整体方案](docs/整体方案-v0.2.md)：设计决定、优化方向和实施顺序的当前依据，第 14 节维护近期规划；调整时同步现有方案与图解。
|
||
- [学习端实施方案](docs/整体方案-v0.2.md#511-学习端实施方案与首条任务)：首条小红书范围、分工、六步学习、任务后官方消息观察和开始学习前的待补项。
|
||
- [本机协作学习入口](tools/learning/README.md)：Codex 受限控制操作、浏览器工具、登录检测与人工质量记录。
|
||
- [AI 获客助手初步讨论方案](docs/初步讨论方案-v0.1.md)：业务场景、学习固化链路、AI 分工、端形态、收费思路及首版验证范围。
|
||
|
||
当前研发主线已收回“链路学习 → 固化 → 轻量召回 → 变参执行”。装修初筛、咨询判断和人工核对保留为后置业务验证，不再继续扩展。维护后台的业务验证不代表桌面端已经完成；本阶段不依赖业务模型识别每篇内容。
|
||
|
||
## 当前路线
|
||
|
||
- 当前按功能模块逐层盘点小红书网页版入口，把可复用操作分别固化，再按平台/任务类型路由；桌面阶段采用 Electron，同时面向 Windows 和 macOS。
|
||
- 已确定学习与桌面共用 Playwright 固定执行、同一版本合同及结果核对，不另建 browser-use `Agent.run` 路径；Midscene 仍是后续可选辅助。学习后台以 A2A learning 的适用模块为基础裁剪适配，桌面壳另行提取验证。
|
||
- 学习端按页面类型和入口来源记录层级、下级控件及返回路径，分别完成观察取证、候选生成、固定校验和变参试跑；运行异常回流维护端修订。
|
||
- 首期由开发者与本地 Codex 协作学习：维护者在平台页面登录，Codex 观察、编写参数化实现、提交候选并依据校验和试跑结果修订；后台管理证据与版本。后台内置自主学习 Agent 后续按需求建设。
|
||
- 学习后台使用独立 PostgreSQL，检索库准备 `pg_search` 与 `pgvector`；商家桌面端仍按 SQLite 规划。平台账号在官方页面自行登录，每个账号复用专用浏览器资料目录。
|
||
- `browser_use` 测试工程的 Electron 桌面壳、产品认证和管理后台作为候选复用基础；云端可沿用其 FastAPI 骨架，本地 SQLite、获客执行与商业模块按当前方案适配或新增，范围见整体方案第 4.4 节。
|
||
- 模型由我们在运营后台按文本判断、复杂复核、视觉操作等用途配置，不绑定具体型号。
|
||
- 第一条学习链路选定小红书「搜索笔记 → 详情 → 评论读取」，先用本机演示页跑通学习与验证，再在维护者自行登录的平台页面上适配。
|
||
- 新小红书任务默认“有界网页操作（原生通信）”，也可明确选旧模式作对照。新模式只允许已观察唯一搜索输入/回车、固定官网标准笔记链接和普通区域有界读取；15 秒动作窗口内，当前主框架发起的第一方 HTTPS `xhr/fetch POST` 自然通信（包括安全通信）可正常进行。它不是网络沙箱，也不承诺服务端绝无副作用；不直接请求接口、运行任意 JavaScript 或添加指纹伪装。旧模式（legacy）的四类精确请求策略原样保留。
|
||
- 当前浏览器执行为 Playwright，尚未接入 browser-use。平台提醒的识别、暂停与人工恢复需按真实页面补齐；任何浏览器框架都不作为不会被识别或限制账号的保证。
|
||
- 学习探索记录与正式运行模式验证分开：已实现运行前基线、观察窗口、人工追加反馈和候选质量状态；晚到异常保留原记录并将同版本置为待复核。当前只评价维护环境，平台自动提醒识别、真实平台表现与商家发布仍待验证。
|
||
|
||
## 项目状态
|
||
|
||
当前包含方案文档、学习后台前后端和独立的 Playwright 浏览器工作进程。支持可见页面登录检测、人工确认、七类有界动作、动态目标匹配、有界容器目标定位、集合等待、有界分批读取与业务 ID 去重、显式文字/媒体内容、步骤阶段耗时、明确空态合同及不可变候选；逐批截图绑定摘要，失败保留实际证据。小红书图文及有限首层评论已通过两组正式模式执行；真实平台空态、登录失效、回复层级及更多范围仍待补样本。已有任务后人工观察机制及明确复查待办，尚未接入后台 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`。
|
||
|
||
[内容初筛](http://127.0.0.1:5179/#/discovery) 使用已学习的四步搜索读取候选和已确认会话，按装修规则初筛，最多保留 3 篇。当前只保存地区条件，未作地域过滤；保留相关同行案例作为评论来源，不据标题确认业主身份或采购意图。
|
||
|
||
打开一条有保留笔记的初筛记录，选择同站的七步详情候选或有界定位八步修订候选，可逐篇点击“读取正文与评论”。使用详情学习任务已确认的会话，未就绪时前往该学习会话处理；当前不自动打开或切换浏览器。八步候选还会显示目标进入视口时的滚动次数、逐次位移与停止原因，目标已可操作时可为零次。每篇独立保存正文、首层评论、来源核对、验证与截图；正文已读但评论失败时保留部分结果，不把未读到评论等同于确认无评论。旧文字候选仍要求文字；新内容候选明确区分文字、媒体和混合内容，媒体保留实际批次截图并标记未解释，不做 OCR。新回放另保存步骤与阶段耗时，旧记录缺失不补零。总预算到期会关闭本次浏览器并保留已完成证据，重新运行前须重开并确认会话。
|
||
|
||
整页滚动页面可另学显式 viewport 模式，目标仍限定在已观察的普通容器内，预算、对象和来源核对保持不变。维护入口可按本任务真实步骤编号冻结修订版本，不修改旧步骤或候选；新组合须独立检查和回放，不能继承旧成功。字段和边界见 [本机学习入口](tools/learning/README.md)。真实平台适配进展见进度文档。
|
||
|
||
最新文字/图片评论八步候选在两篇真实装修笔记上探索通过，各取得正文和 6 条首层评论，其中一篇包含纯图片评论。当前检查复用原核验语义并限定到已观察目标，每步后的完整取证保留；本机工作进程耗时约 46/49 秒。该版本仍为维护实验候选，未正式发布，模型和需求质量尚未验收；历史失败、样本范围及分阶段测试见 [开发进度](docs/开发进度.md)。
|
||
|
||
平台登录在工作台打开的浏览器中直接完成。打开/刷新时先检测可见页面的登录状态：已登录时无需重复扫码，未登录或需验证时由维护者在官方窗口处理；状态不确定时允许人工核对。当前账号身份仍需确认，页面检测不代替身份认证。固定资料目录用于后续复用。学习账本保存到 PostgreSQL，浏览器资料与证据文件保存在 `.runtime/learning/`，均不提交 Git。
|
||
|
||
## 装修需求分析
|
||
|
||
在[内容初筛](http://127.0.0.1:5179/#/discovery)顶部打开“商家需求”，输入任务文字，核对逐字段原文依据和缺项后确认条件，再点击“用于本次初筛”。本轮只支持小红书装修服务寻找业主，使用第一个搜索词；服务地区可保留未知，不默认全国。确认版本单独追加保存，初筛和阅读继承条件引用，仍需已有候选及已确认会话。
|
||
|
||
在已取得可用正文并通过来源核对的阅读详情中，点击“分析本次已读内容”。这会分析该条已保存的文字，不重新打开或操作平台。正文与每条首层评论分别给出明确需求、疑似需求、普通讨论或信息不足，并保留逐字依据、来源、缺失信息、模型配置和请求记录。纯图片/视频标为信息不足、内容未解释；需求信号不等于已确认客户。失败阅读不能分析，有正文的有效部分阅读会保留范围说明。
|
||
|
||
新版另列当前角色信号、多选表达、业务相关性及根据商家条件派生的初步匹配和建议。“自身要装修”可同时“提问、求建议”；服务方也可有自身需求，短句“哪里”不确认角色。阅读默认沿用关联条件，旧阅读可选择已确认条件追加新分析；条件摘要参与结果复用，旧分析仍可查看。地区或上下文不足会提示补充信息。建议未执行。
|
||
|
||
新分析合同为 `renovation-demand-v4 / demand-result-v3`。评论通过服务端生成的 `context_refs:["note"]` 引用同次阅读的笔记，笔记没有背景引用，正文只向模型提供一次；总范围仍为21个来源、16,000字。新增独立 `consultation`（有／无／信息不足），本条逐字依据与笔记背景依据分开保存，不能引用其他评论或继承作者的身份、需求、项目地区和预算。程序派生“保留待核实”等展示结果，不据咨询意向提升业务匹配或触发联系；这也不是独立线索库。新旧提示和结果版本隔离复用，不重写旧分析。
|
||
|
||
人工核对：打开一条完成的分析，在“人工核对”区域按“核对此条”，对照原文选择判断正确、需要修正、暂不能确定或当前文字不可核对。`demand-result-v3` 使用六轴 `analysis-review-v2`，增加独立咨询意向和笔记背景依据；`demand-result-v2` 仍按原五轴 `analysis-review-v1` 保存，更早结构只读。修正时填写标签、说明和本条原文依据；评论确认有咨询意向时另附所关联笔记的逐字背景依据，再显式保存。无法确定时直接写原因，不必猜身份。每次修订另存，旧模型与人工版本保留，未保存的预填不算核对；纯媒体不作文字判断。一致率仅统计已判定样本的最新版本，不是模型真实准确率或召回率；核对不调用模型、重新读取平台或触发联系动作。
|
||
|
||
查看已有结果时，在分析历史中点击“查看分析”，会直接打开“分析详情”侧栏，首先显示分类、原文和依据；关闭后可再次打开同一条记录。模型配置、用量与请求记录在侧栏下方折叠区中。查看历史只打开已有结果，不调用模型；人工核对与纠错另行显式追加保存，原模型结果保留。
|
||
|
||
服务端模型使用 [.env.example](.env.example) 的 `ASSISTANT_MODEL_*` 配置：供应商、接口、型号、主/备用 Key、思考模式、超时和输出上限。真实 Key 只填被忽略的 `.env`，不使用 `VITE_` 前缀或提交仓库，修改后重启本机服务。当前以 `deepseek-flash`、关闭思考为基线；型号可换，主备只切 Key，不自动升级模型。每请求最多 30 秒、合计最多 60 秒；最多 21 个来源和 16,000 字，超限拒绝，不自动截断。
|
||
|
||
前端只显示安全配置状态，“已配置”不等于已验证连通。相同阅读、配置和分析版本复用已完成结果，失败不会自动重试；新失败记录单独保留。Token 仅汇总已返回用量，失败/超时的未知消耗不计入汇总，费用显示未知，尚未接商家扣费。调用、工程回归与真实内容试用的具体状态见 [开发进度](docs/开发进度.md)。
|
||
|
||
## 学习数据库
|
||
|
||
`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 学习环境的存储方式。
|
||
|
||
schema 10 为学习任务增加可空 `execution_profile`；旧任务保留空值且 API 省略字段，不追溯补成新模式。候选清单保存声明合同，实际会话、验证、初筛和阅读各自保存已核验回显；缺字段显示未记录，不用任务选项替代实际执行证据。
|
||
|
||
`pnpm db:status` 查看容器，`pnpm db:stop` 停止本项目容器并保留数据卷。普通重启不重建数据库。
|
||
|
||
## 检查
|
||
|
||
```powershell
|
||
pnpm check
|
||
pnpm build
|
||
pnpm test:server
|
||
pnpm test:learning
|
||
pnpm test:discovery
|
||
pnpm test:reading
|
||
pnpm test:reading-seek
|
||
pnpm test:reading-media
|
||
pnpm test:demand-analysis
|
||
pnpm test:business-workbench
|
||
pnpm test:analysis-review
|
||
pnpm test:control
|
||
pnpm test:session
|
||
pnpm test:platform-policy
|
||
pnpm db:check
|
||
node tools/learning/test-browser-worker.mjs
|
||
node scripts/test-migrate-learning.mjs
|
||
```
|
||
|
||
`test:learning` 使用隔离的测试库/随机 schema、真实浏览器与本机演示页，覆盖参数化对象、结构化读取、试跑/质量界面、晚到异常、证据回看及重启持久化，不访问真实平台账号。未配置测试 DSN 时回退到临时 SQLite，绝不借用开发库。Windows 默认使用本机 Edge，其他系统默认使用已安装的 Playwright Chromium；可用 `ASSISTANT_TEST_BROWSER_CHANNEL` 覆盖。单端通过不会被记作 Windows/macOS 均通过。
|
||
|
||
`db:check` 实际验证中文 BM25、平台过滤、搜索索引计划与固定样本向量排序，测试数据在专用测试库中创建后清理。样本向量不能代表模型 embedding、召回率或完整混合检索已完成。
|
||
|
||
`test:discovery` 使用独立服务、随机测试 schema 与合成页面，验证装修规则、来源/标题不足时不选、界面理由、历史、失败记录及重启保存。`test:reading` 在独立页面验证初筛到单篇阅读、对象绑定、部分结果、历史及重启；`test:reading-seek` 独立验证八步候选录制、结果重排后的滚动定位及有界失败；`test:reading-media` 验证显式文字/媒体/混合内容、媒体截断、原文字合同、步骤耗时、截图及历史。以上脚本均不访问真实账号。`test-migrate-learning.mjs` 仅使用测试 DSN 和随机 schema 验证迁移，包括旧 SQLite 没有质量观察/内容初筛/阅读表的兼容、新记录复制及失败整体回滚；不会向开发库导入测试数据。
|
||
|
||
`test:demand-analysis` 使用随机测试 schema、合成浏览器页面和本机 HTTP 假模型，覆盖需求依据、主备切换、双失败、错误依据拒绝、已完成结果复用、历史/重启及密钥不暴露；显式覆盖所有模型环境变量，不使用真实模型 Key 或真实平台账号。迁移脚本也兼容旧库缺分析表，按阅读后的依赖顺序复制分析事实。
|
||
|
||
`test:business-workbench` 在独立 PostgreSQL、Edge 和本机假模型验证需求解析、显式确认、已学初筛/阅读、多轴分析、历史与复用。schema 8 增加不可变商家需求版本；迁移兼容旧库缺该表，并在同一事务内核对父版本关系和失败回滚。各脚本的实际执行结果与未覆盖项见开发进度，不能以脚本存在代替通过。
|
||
|
||
`test:analysis-review` 使用独立 PostgreSQL、Edge 和本机假模型准备合成阅读/分析，验证四种核对、修正依据、并发旧版本拒绝、最新版本统计及重启；真实业务结论仍需维护者核对。schema 9 增加不可变核对链，迁移兼容旧库缺表、保留修订顺序并拒绝坏父引用。
|
||
|
||
## 远程仓库
|
||
|
||
[zwt-cmd/assistant](https://github.com/zwt-cmd/assistant)
|