AI 平台品牌可见性测试工具

本地网页工具，用于测试豆包、通义千问、百度文心在业务关键词下是否会自然提到目标公司。未命中时，工具会根据上一轮回答生成自然追问，并保存原始问答、截图、评分和报告。

环境要求

• Git。
• Node.js 24 或更新版本。项目使用 Node 内置 SQLite 能力，旧版 Node 可能无法启动。
• npm 11 或更新版本，通常会随 Node.js 一起安装。
• Google Chrome。自动化测试真实平台时会调用本机 Chrome，Mac 和 Windows 都需要提前安装。
• 可访问目标 AI 平台网站的本地网络环境。

npm run setup:browsers 会准备 Playwright 浏览器依赖，但不能代替 Google Chrome；真实平台测试仍需要本机已安装 Chrome。

仓库不包含种子数据。下载安装到本地后，数据库会在首次启动时自动创建；用户需要在网页里自行填写模型设置、公司画像和关键词，填写完整后即可正常使用。

Mac 本地安装

适用于 macOS 的“终端”或 iTerm，默认 shell 通常是 zsh：

git clone https://github.com/LeiThreeStone/ai-brand-visibility.git
cd ai-brand-visibility
npm ci
npm run setup:browsers
npm run dev

打开本地地址：

http://127.0.0.1:5173

如果要把数据库和截图保存到固定目录，可在启动前设置数据目录：

export BRAND_VISIBILITY_DATA_DIR="$HOME/brand-visibility-data"
npm run dev

Windows 本地安装

适用于 Windows PowerShell：

git clone https://github.com/LeiThreeStone/ai-brand-visibility.git
cd ai-brand-visibility
npm ci
npm run setup:browsers
npm run dev

打开本地地址：

http://127.0.0.1:5173

如果要把数据库和截图保存到固定目录，可在启动前设置数据目录：

$env:BRAND_VISIBILITY_DATA_DIR="D:\brand-visibility-data"
npm run dev

启动后，后端 API 默认运行在：

http://127.0.0.1:4188

首次使用

1. 打开“设置”，填写 OpenAI 兼容接口地址、API Key 和模型名称。
2. 填写公司画像，包括公司名、简称、品牌、产品、业务范围和别名。
3. 在关键词库中新建或编辑要测试的关键词。
4. 进入“手动”发起一次测试，或进入“自动”创建定时任务。
5. 在“报告”里查看命中率、原始问答、截图证据和 CSV 导出。

API Key 只保存在本机 SQLite 数据库里，不会写入源码文件。仓库默认不会提交 data/ 目录。

常用命令

Mac 和 Windows 都一样：

npm run dev
npm run test
npm run build
npm run lint
npm run share

命令说明：

• npm run dev：同时启动本地 API 和网页。
• npm run test：运行项目测试。
• npm run build：检查 TypeScript 并生成前端构建文件。
• npm run lint：运行代码检查。
• npm run share：通过临时 tunnelmole 地址把本机网页发给别人访问。

临时分享

在运行项目的电脑上执行：

npm run share

等窗口里出现 https://...tunnelmole.net 这样的地址后，把这个地址发给对方即可。对方看到的是这台电脑正在运行的网页、任务进度、结果和截图。

注意事项：

• 这台电脑和命令窗口必须一直开着。
• 电脑关机、睡眠、断网，或者关闭命令窗口后，对方就不能访问。
• 临时地址没有账号校验，只适合发给明确的单个人短期使用。
• 自动化浏览器默认在后台运行，不弹到桌面前台。

数据位置

默认数据都在本地 data/ 目录：

• SQLite：data/brand_visibility.sqlite
• 证据截图：data/evidence/
• CSV 导出：网页右上角“导出 CSV”

可用环境变量修改数据目录：

macOS：

export BRAND_VISIBILITY_DATA_DIR="$HOME/brand-visibility-data"
npm run dev

Windows PowerShell：

$env:BRAND_VISIBILITY_DATA_DIR="D:\brand-visibility-data"
npm run dev

可选环境变量

• PORT：后端 API 端口，默认 4188。
• BRAND_VISIBILITY_DATA_DIR：本地数据库和截图目录，默认项目下的 data/。
• BRAND_VISIBILITY_RUN_TIMEOUT_MS：单次任务超时时间，默认 8 分钟。

排障

• 如果提示找不到 node:sqlite，请升级到 Node.js 24 或更新版本。
• 如果自动化浏览器启动失败，先确认本机已经安装 Google Chrome，再重新运行 npm run setup:browsers。
• 如果 5173 或 4188 端口被占用，先关闭已有本地服务，或设置 PORT 后重新启动。
• 如果首次打开没有公司和关键词，这是正常状态；先在“设置”里录入公司画像和关键词。

边界

• 不登录任何平台。
• 不绕过验证码、风控或登录限制。
• 如果平台弹出登录窗口，工具会尝试关闭；无法继续时记录为“登录墙阻断”。
• 每个真实平台测试都会创建一次性浏览器环境，任务完成后删除。
• 代理地址只是配置位；未填写时报告标记为“未换独立 IP”。