# bidscope **Repository Path**: suijiyingdui/bidscope ## Basic Information - **Project Name**: bidscope - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-05-18 - **Last Updated**: 2026-05-18 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # BidScope 招投标信息聚合工具 BidScope 是一个基于 **Pi Agent Framework + React + Express + SQLite** 的招投标信息聚合系统，支持自然语言查询、多源抓取、登录态站点演示、内容清洗去重、风险预警、AI 汇总整理、Word 报告导出、定时增量推送和 Web UI 交互。 > 当前项目已在 Windows + Node.js 22 环境验证通过。 --- ## 1. 功能概览 - **自然语言意图解析**：识别关键词、区域、时间范围、定时频率。 - **多源信息抓取**：集成千里马真实搜索接口，并保留多站点抓取框架。 - **登录态站点演示**：内置剑鱼标讯登录态抓取流程演示，用于满足鉴权站点要求。 - **内容清洗与去重**：清洗导航/广告/模板噪声，使用 SimHash 去重。 - **AI 富化整理**：调用当前配置的大模型提取采购单位、预算、招标范围、资质要求、项目洞察。 - **风险预警**：根据投标截止时间判断临近截止/已截止风险。 - **Word 报告导出**：生成包含 AI 执行摘要、结构化表格、可访问复核链接、附件链接的 `.docx` 文件。 - **定时与增量推送**：识别“每天9:00”等频率，定时执行并仅输出新增内容。 - **现代 Web UI**：豆包风格主页、会话历史、模型配置、定时任务页面。 --- ## 2. 目录结构 ```text bidscope/ ├─ bidscope-backend/ # 后端：Express + Pi Agent + SQLite + Word导出 │ ├─ src/ │ │ ├─ agent/ # Pi Agent 创建、系统提示词、工具定义 │ │ ├─ api/ # REST API 路由 │ │ ├─ db/ # SQLite 连接、迁移、Repository │ │ ├─ scrapers/ # 千里马与多站点爬虫 │ │ ├─ services/ # AI富化、去重、风险分析、Word导出等 │ │ ├─ tools/ # Agent 工具：意图解析、抓取、聚合导出 │ │ └─ server.ts # 后端入口 │ ├─ data/ # SQLite 数据库运行时目录（自动生成） │ └─ output/ # Word 运行时输出目录（自动生成） ├─ bidscope-frontend/ # 前端：React + Vite + Tailwind │ └─ src/ ├─ 操作文档.md # 操作与验证说明 ├─ 详设文档.md # 详细设计文档 ├─ package.json # npm workspace 脚本入口 ├─ package-lock.json # 锁定依赖版本 └─ README.md ``` --- ## 3. 从零构建环境 ### 3.1 安装基础软件 需要安装： - **Node.js 22+** - **npm 10+** - Windows PowerShell（推荐） 验证版本： ```powershell node -v npm -v ``` 期望示例： ```text v22.x.x 10.x.x ``` 如果机器上已有项目内置 Node： ```powershell $nodeDir=(Resolve-Path '.tools/node-v22.16.0-win-x64').Path; $env:Path="$nodeDir;$env:Path" ``` > 新开 PowerShell 后需要重新执行上述 PATH 注入命令。若从压缩包零构建，通常不包含 `.tools`，请直接安装 Node.js 22+。 ### 3.2 解压项目 将压缩包解压到任意目录，例如： ```text D:\match\bidscope ``` 进入项目根目录： ```powershell cd D:\match\bidscope ``` --- ## 4. 配置大模型 后端读取 `bidscope-backend/.env` 中的模型配置。首次运行请新建该文件： ```powershell New-Item -ItemType File bidscope-backend/.env -Force ``` 写入以下内容，并替换为自己的模型网关和 Key： ```env BIDSCOPE_MODEL_PROVIDER=openai-compatible BIDSCOPE_MODEL_API_BASE=http://218.28.9.108:50053/v1 BIDSCOPE_MODEL_NAME=qwen3.6-max-preview BIDSCOPE_MODEL_API_KEY=your_api_key_here ``` 说明： - `BIDSCOPE_MODEL_PROVIDER`：OpenAI 兼容接口固定可填 `openai-compatible`。 - `BIDSCOPE_MODEL_API_BASE`：模型网关地址，必须包含 `/v1`。 - `BIDSCOPE_MODEL_NAME`：模型名称。 - `BIDSCOPE_MODEL_API_KEY`：模型访问密钥。 - `.env`、数据库、运行时输出文件不建议提交到仓库或公开压缩包。 也可以启动前端后，在“模型设置”页面保存和切换多个模型配置。 --- ## 5. 安装依赖 在项目根目录执行： ```powershell npm install ``` 说明： - 项目使用 npm workspace 管理前后端依赖。 - 不需要手动进入子项目分别安装。 - `node_modules` 不应放入提交压缩包，解压后执行 `npm install` 即可恢复。 --- ## 6. 启动开发环境 ### 6.1 启动后端 打开第一个 PowerShell，在项目根目录执行： ```powershell npm run dev:backend ``` 后端默认地址： ```text http://localhost:3001 ``` 健康检查： ```text http://localhost:3001/health ``` ### 6.2 启动前端 打开第二个 PowerShell，在项目根目录执行： ```powershell npm run dev:frontend ``` 前端默认地址： ```text http://localhost:5173 ``` 启动后在浏览器打开 `http://localhost:5173`。 --- ## 7. 生产构建与运行 ### 7.1 全量构建 ```powershell npm run build ``` 构建产物： - 后端：`bidscope-backend/dist` - 前端：`bidscope-frontend/dist` ### 7.2 运行构建后的后端 ```powershell npm run start -w bidscope-backend ``` ### 7.3 预览构建后的前端 ```powershell npm run preview -w bidscope-frontend ``` 注意：Vite `preview` 主要用于静态资源预览。正式部署时需使用 Nginx、网关或同源代理把 `/api` 和 `/ws` 转发到后端 `http://localhost:3001`。 本地演示推荐使用第 6 节的开发启动方式，因为 Vite 开发服务已内置 `/api` 和 `/ws` 代理。 --- ## 8. 验证步骤 ### 8.1 单元测试 ```powershell npm run test -w bidscope-backend ``` 通过标志： ```text Test Files 1 passed Tests 3 passed ``` ### 8.2 端到端冒烟测试 ```powershell npm run smoke -w bidscope-backend ``` 冒烟测试会执行： 1. 测试模型连通性。 2. 创建招投标查询任务。 3. 调用 Pi Agent 工具流水线。 4. 抓取多站点结果。 5. 清洗、去重、风险分析。 6. 调用 AI 富化并生成 Word 报告。 7. 校验数据库、登录态站点结果和 Word 文件。 通过标志： ```text SMOKE_OK ``` ### 8.3 Web UI 验证 1. 打开 `http://localhost:5173`。 2. 输入或点击示例： ```text 最近3个月上海区域内的充电桩招标信息都有哪些，请汇总后每天9:00发送给我 ``` 3. 验证页面显示： - Agent 执行进度 - 查询结果卡片 - Word 下载按钮 - 左侧会话历史 - 定时任务记录 4. 下载 Word，检查是否包含： - AI执行摘要 - 市场/项目观察 - 结构化关键信息表格 - AI分析、跟进建议、风险说明 - Bing/百度复核链接、原始公告链接、附件链接 --- ## 9. 常用脚本 | 命令 | 说明 | |---|---| | `npm install` | 安装全部 workspace 依赖 | | `npm run dev:backend` | 启动后端开发服务 | | `npm run dev:frontend` | 启动前端开发服务 | | `npm run build` | 构建前后端 | | `npm run test -w bidscope-backend` | 运行后端单元测试 | | `npm run smoke -w bidscope-backend` | 运行端到端冒烟测试 | | `npm run start -w bidscope-backend` | 运行构建后的后端 | | `npm run preview -w bidscope-frontend` | 预览构建后的前端 | --- ## 10. 运行时文件说明 以下文件或目录会在运行时生成，不建议放入源码压缩包： ```text node_modules/ bidscope-backend/dist/ bidscope-frontend/dist/ bidscope-backend/data/*.db* bidscope-backend/output/*.docx bidscope-backend/.env bidscope-backend/credentials/*.key *.log ``` 数据库和输出目录会自动创建： - SQLite 数据库：`bidscope-backend/data/bidscope.db` - Word 输出：`bidscope-backend/output/*.docx` --- ## 11. 打包压缩建议 提交源码包时建议包含： - `bidscope-backend/src` - `bidscope-frontend/src` - `package.json` - `package-lock.json` - `README.md` - `操作文档.md` - `详设文档.md` - 赛题说明文件 建议排除： - `node_modules` - `.tools` - `dist` - `.env` - 数据库文件 - 运行时 Word 输出 - 日志文件 - 凭证密钥文件 这样压缩包体积更小，也避免泄露本地密钥或历史数据。评审或新机器解压后，按照第 3～8 节即可从零构建和验证。 --- ## 12. 常见问题 ### 12.1 端口被占用 现象：后端提示 `EADDRINUSE`，或 Vite 自动切换到其他端口。 处理： - 关闭已有的后端/前端进程后重启。 - 或访问终端输出的新端口。 ### 12.2 Node 版本过低 现象：`npm install`、`vite build` 或 `vitest` 报 engine/version 相关错误。 处理： - 安装 Node.js 22+。 - 或使用项目内置 Node 后重新执行 PATH 注入命令。 ### 12.3 模型调用失败 现象：模型连通性测试失败或 smoke 阶段提示模型错误。 处理： - 检查 `bidscope-backend/.env` 中 `BIDSCOPE_MODEL_API_BASE` 是否包含 `/v1`。 - 检查 `BIDSCOPE_MODEL_API_KEY` 是否有效。 - 检查当前网络是否能访问模型网关。 - 也可以在前端“模型设置”页面重新保存并测试连接。 ### 12.4 千里马链接或附件打不开 部分聚合平台详情页或附件需要登录。Word 报告会额外提供 Bing/百度复核检索链接和原始公告链接，优先使用这些链接定位可访问的公开原文。 --- ## 13. 参考文档 - `操作文档.md`：完整操作与验证步骤 - `详设文档.md`：系统详细设计与创新点说明 - Pi Agent Framework：https://github.com/earendil-works/pi