Commit 624ee95e authored by 王蔡翾's avatar 王蔡翾
Browse files

bug修复

parent 6e1d9234
# 只有 API Key 使用环境变量;数据库、管理员及其余参数在 src/main/resources/application.yaml 中配置。
# 可以直接在启动终端或 IDE 中设置,无需创建 .env;若使用 .env,仍需手动导出。
# API Key 仅后端使用,禁止放入 VITE_*。
ZLBX_API_KEY=
DEEPSEEK_API_KEY=
......@@ -31,3 +31,11 @@ build/
### VS Code ###
.vscode/
# 部署凭证只保存在本机,允许提交不含密钥的示例。
.env
.env.*
!.env.example
# 可选的外部覆盖配置可能含凭证,禁止纳入 Git;如需使用须通过启动参数显式加载。
/application-local.yaml
var/
# 如昼商机助手后端
Java 21 / Spring Boot 4.1.2 / MySQL 8。前端位于相邻的 `rz-GB-web`。
D1–D4 代码已实现:会话登录、公司档案、分页检索与获客、平台市场聚合、匹配度及摘要快照、检索方案、八状态关注与标签、任务/SSE、实际调用和证据账本。新增单/双企业情报、项目快速/完整研判、投标文件解析与视觉、主体确认和预算恢复。D4 已补充持久化会话、单项目/整批快照问答、清理与恢复验收。2026-10-29 已接入本地指定的 MySQL 8.0.27,验证 V1–V7 迁移、健康检查、管理员登录及档案读取;104 项本地测试通过。供应商凭证及真实业务联调仍待补充,数据库重启持久化未在本次验证。
## 配置与启动
1. 创建空的 MySQL 8 数据库 `rz_gb`,字符集 `utf8mb4`。应用账号需具备该库的建表、索引和读写权限;Flyway 会按版本迁移,不需要手动逐个执行 SQL。
2. 数据库和管理员初始信息直接维护在 `src/main/resources/application.yaml` 的 `spring.datasource` 与 `rz.admin-password` 中,打包后随 JAR 加载。部署前核对数据库地址和账号;初始密码不限制最小长度,但不能为空,UTF-8 不超过 BCrypt 的 72 字节上限;`admin` 已存在时重启不会重置密码。
3. 其余参数直接修改 `src/main/resources/application.yaml`。只有 `ZLBX_API_KEY`、`DEEPSEEK_API_KEY` 使用终端或 IDE 的环境变量;可以暂不设置,先运行登录和档案功能。
4. 从后端项目根目录启动,无需加载 `.env`:
```sh
export JAVA_HOME=$(/usr/libexec/java_home -v 21)
mvn spring-boot:run
```
运行 JAR 不再依赖工作目录中的 `application-local.yaml`,修改主 YAML 后需要重新打包部署。源码主 YAML 和 JAR 均包含数据库及管理员初始化凭证,应限制访问。若需外部覆盖,可按 `application-local.example.yaml` 填写文件,再通过 `--spring.config.additional-location=file:/绝对路径/application-local.yaml` 显式加载。旧 `.env` 的数据库及其他参数不再由本项目读取。
服务默认 `http://localhost:8240`;`GET /actuator/health` 用于就绪检查。生产同源 HTTPS 部署时将主 YAML 中 `server.servlet.session.cookie.secure` 改为 `true`,反向代理 `/api` 到后端,并关闭 SSE 缓冲、设置足够的读超时。会话保存在当前实例内存,后端重启后需要重新登录;档案、任务、关注保存在数据库中。
## 前端
```sh
cd ../rz-GB-web
npm ci
npm run dev
```
默认 `http://localhost:3000`,Vite 已代理 `/api` 到 `8240`。先登录后填写公司档案,进入“服务验证”逐项测试。对话调研已接入四个真实任务入口、主体选择与预算暂停;未配置真实供应商时明确等待,不生成演示结果。
## 测试
```sh
export JAVA_HOME=$(/usr/libexec/java_home -v 21)
mvn -Djava.awt.headless=true verify
```
自动测试仅使用 test 作用域 H2 和本地 HTTP 模拟服务,不使用真实密钥,不产生外部费用。生产不包含 H2,不会自动降级到内存库。MySQL 重启持久化和真实服务验证需补充连接/凭证后执行,参见 `docs/D1实施与验收.md`。
D3 工作流、文件矩阵与验收见 [D3 实施与验收](docs/D3实施与验收.md)。D2 接口、快照、预算及验收见 [D2 实施与验收](docs/D2实施与验收.md);基础会话、事件与配置见 [D1 实施与验收](docs/D1实施与验收.md)。需求与四天计划保持在 [docs](docs/README.md)。
D4 结果、102 项本地测试、格式/异常矩阵和真实验收待办见 [D4 实施与验收](docs/D4实施与验收.md);构建、V1–V7 初始化、部署和新增接口见 [接口契约与运行交付](docs/接口契约与运行交付.md)。
# 可选的外部覆盖示例;默认数据库与管理员配置已在 src/main/resources/application.yaml 中维护。
# 如需覆盖,复制为 application-local.yaml,填写后通过以下启动参数显式加载,无需激活 profile:
# --spring.config.additional-location=file:/绝对路径/application-local.yaml
# 本示例不含凭证,根目录的实际 application-local.yaml 仍由 Git 忽略。
spring:
datasource:
# JDBC 库名不加反引号;UTC 会话与本项目的数据库时间戳约定一致。
url: "jdbc:mysql://localhost:3306/rz_gb?useUnicode=true&characterEncoding=UTF-8&connectionTimeZone=UTC&forceConnectionTimeZoneToSession=true"
username: ""
password: ""
rz:
# 首次初始化使用;已有 admin 时不会重置密码。使用引号,避免 YAML 把数字密码解析为数值。
admin-password: ""
# D1 实施与验收记录
日期:2026-10-26(Asia/Shanghai)。本次按用户要求先完成代码,数据库和 API Key 随后补充。**D1 代码实现不等于真实服务验收通过。**
## 已实现范围
- 三组 Flyway 迁移:账号/档案/公告/关注与历史/标签;检索方案/批次/有序快照/会话消息;任务/幂等命令/事件/实际调用/证据/临时文件元数据。D2–D3 所需表提前建立,不代表这些业务接口均已实现。
- Spring Security 会话认证,BCrypt 初始 admin,CSRF 覆盖登录、退出和所有写接口。账号由环境初始化,不提供注册或默认弱密码。未登录的任务、档案、文件、关注均被拦截;不存在的文件接口也不绕过登录。
- 八组手填档案,后端计算版本、时间和完善状态;最低企业名称+主营业务;四维权重固定名称,非负且不能全零。版本冲突返回 409,避免多页面覆盖。
- 关注增删、读取及初始历史原子保存,重复关注只保留一条。只能关注已从真实检索取得的公共公告;取消关注清理其历史与标签绑定,不删除公告或独立任务。
- 单实例有界执行器(2 线程、16 排队),D1 单任务执行一个白名单验证动作。三个工作流锁定版本并正确发送 `X-Client`,没有“一次 HTTP 请求执行完整 Skill”的虚构接口。
- 有序持久化事件、SSE 重放、创建/继续幂等、等待输入/主体/预算、取消、重启中断处理。HTTP 传输不自动重试。
- 实际调用账本保存状态、HTTP 状态、耗时、`meta.cost_units`、返回的实际模型与 usage。未知成本为 null,不能当成零。文本响应不保存或向前端发送 `reasoning_content`。
- 前端同源客户端、会话恢复、真实登录与退出、档案读取保存、移除档案 AI 导入、清除旧演示档案自动加载、任务验证页与真实事件组件;不自动上传浏览器旧演示数据。
## 需要补充的环境变量
| 变量 | 用途 | 必须时间 |
| --- | --- | --- |
| `DB_URL` | MySQL JDBC URL,含数据库名及 UTC 连接时区 | 后端启动前 |
| `DB_USERNAME` / `DB_PASSWORD` | 数据库用户名与密码 | 后端启动前 |
| `ADMIN_INITIAL_PASSWORD` | 首次初始化 admin,不限制最小长度;不能为空,UTF-8 最多 72 字节(BCrypt 上限) | 首次启动前 |
| `ZLBX_API_KEY` | 知了标讯数据与账户查询 | 知了真实验证前 |
| `DEEPSEEK_API_KEY` | 文本、结构化、流式、联网 Search/Fetch、视觉 | 模型真实验证前 |
完整占位符见根目录 `.env.example`。不需要 Redis、Milvus、向量模型、OSS、千问、智谱或发布渠道密钥。后端启动时读取环境,补充或变更后重启;随后可显式继续原先等待配置的任务。
## 已开放接口
统一 `/api`,除 CSRF 引导与登录外均需要服务端会话 Cookie;写请求要带 CSRF header。错误响应 `{"code":"...","message":"..."}`,不返回 SQL 或供应商原始认证错误。
| 方法与路径 | 请求 / 行为 |
| --- | --- |
| `GET /auth/csrf` | 返回 `{token,headerName}`,含登录前引导;原样回传 token |
| `POST /auth/login` | `application/x-www-form-urlencoded`:`username=admin&password=...`,成功后重新获取 CSRF |
| `GET /auth/me` | 恢复真实登录会话 |
| `POST /auth/logout` | 会话失效,删除 Cookie;写请求必须有 CSRF |
| `GET/PUT /company-profile` | 与前端八组字段一致;PUT 含当前 version,返回服务端权威版本与完善状态 |
| `GET /watch` | 当前账号的关注记录及历史 |
| `POST/DELETE /watch/{projectId}` | 关注或取消,公告 ID 例如 `zlbx-8240`;不接受演示项目 |
| `GET /watch/{projectId}/history` | 只读自己的关注历史 |
| `POST /agent/tasks` | 创建单动作验证任务,必须 `Idempotency-Key` |
| `GET /agent/tasks` | 最近 50 个当前账号任务 ID |
| `GET /agent/tasks/{id}` | 状态、原始参数快照、结果、真实调用账本和证据 |
| `POST /agent/tasks/{id}/continue` | 仅等待状态允许;补充同类任务参数,必须独立 `Idempotency-Key` |
| `POST /agent/tasks/{id}/cancel` | 停止未发出的动作;已发出的请求继续计费和记账 |
| `GET /agent/tasks/{id}/events` | SSE;支持 `Last-Event-ID` 或 `?after=数字` |
| `GET /agent/tasks/{id}/event-history` | JSON 事件分页,每次最多 100,after 为上次事件 ID |
| `GET /agent/tasks/{id}/report` | D1 与任务详情相同,返回单项验证结果,不生成完整业务报告 |
| `GET /system/limits` | 可公开的调用、积分、分页及未来文件保护值,不返回密钥 |
任务示例(先登录获取会话与 CSRF):
```json
{
"operation": "BID_SEARCH",
"workflow": "TENDER_SEARCH",
"input": "智慧水务,水质监测",
"entityConfirmed": false,
"maxCalls": 1,
"maxCostUnits": 1
}
```
`workflow` 为 `TENDER_SEARCH` / `COMPANY_INTEL` / `BID_DECISION`;对应 `zlbx-bidding/2.3.0` / `company-intel/1.0.2` / `bid-decision/1.0.4`。`operation` 白名单:`ZLBX_BALANCE`、`BID_SEARCH`、`BID_DETAIL`、`COMPANY_SEARCH`、`COMPANY_PROFILE`、`MODEL_TEXT`、`MODEL_JSON`、`MODEL_STREAM`、`WEB_SEARCH`、`WEB_FETCH`、`VISION`。客户端不能指定任意工具 URL 或认证头。
`BID_SEARCH` 是 D1 小样本探针:关键词用中英文逗号分隔,最多 10 个,组内 OR;全国近 90 天,阶段 `[1,2,4,7,8]`,只读第 1 页、最多 3 条,不宣称全量召回。`BID_DETAIL` 只接受数字公告 ID。企业画像需要显式确认主体;不根据第一条自动选择或合并集团。视觉仅发送后端生成的“D1 8240”样图,不接收文件上传。
幂等键 8–128 字符,按账号隔离;同键同请求返回同任务,同键不同请求 409。继续操作按任务和独立命令键防重。SSE ID 全局递增,同任务有序;只读事件重连不会重复收费。终态或等待状态发送 `idle` 后关闭;补充参数后重新订阅。事件包括 `RECEIVED`、`STATE`、`TOOL_START`、`TOOL_COMPLETE`、`TOOL_FAILED`、`REPORT_FRAGMENT`。不会展示私有推理链。
## 保护值与边界
- 默认每任务最多 5 次实际请求、10 知了积分;每个 D1 探针只执行一步。预算不足时暂停继续,必须用户显式操作。**未核实工具价格时,积分预算无法保证首个请求一定不超额**;返回 cost 后如实展示,不把未知费用当作 0。暂停后的继续累计调用次数,不清零账本。
- D2 检索保护值先配置每页 50、最多 5 页;D1 探针仅最多 3 条,不占用全批预算。检索结果单位由供应商原样保留,D2 前不在列表中假装已完成金额标准化和排序。
- HTTP 连接超时 10 秒,请求/读取默认 90 秒,最多 4 MiB 响应,不跟随供应商重定向;所有超时和不确定结果不自动重试。
- 未来文件保护值预先配置:20 MiB、PDF 50 页、视觉最多 20 页/张、原件 24 小时、审计元数据 180 天。D1 尚未开放上传,也尚未运行文件清理,不能把这些配置当作文件能力已交付。
- 临时文件处理选用 Apache Tika 负责 Office/文本/HTML 类型检测与文字提取,PDFBox 负责逐页 PDF/扫描页渲染;D3 再加入经核实兼容版本和代表性样例,D1 不引入尚未使用的解析库。
- 服务重启把排队/计划/运行任务标记为 `PARTIAL`,进行中的调用标记 `UNKNOWN`,不自动重放。会话需重新登录。
## 测试与真实验收
本地验收结果(2026-10-26):
- 后端 `mvn test`:**15 项通过,0 失败,0 错误,0 跳过**。覆盖会话/CSRF/退出、密码哈希、三组迁移、档案版本/权重、并发幂等、等待主体/输入、继续防重、业务失败/额度不足/空结果/限流、真实协议流片段与 usage、事件重放、归属鉴权、关注唯一与历史清理、内网 URL 拒绝、缺凭证预检、重启中断恢复,以及各 D1 供应商动作的本地协议契约。
- 前端 `npm run build`:通过。新增 API 客户端、任务事件 Hook、服务验证页,以及本次登录/档案/App/Topbar 的定向 ESLint:通过。
- 对旧 `store.tsx` / `DiscoverPage.tsx` 的定向 lint 仍有 8 项预存错误;已用 Git HEAD 原文件复验,分别是混合导出 Fast Refresh 规则、渲染时 Date.now 和 effect 内同步状态更新。本次不扩大范围整改旧原型。Vite 的单包体积 >500 kB 提醒仍保留,构建成功。
- 浏览器端(临时 H2 文件库,供应商 Key 清空):错误密码被拒绝;正确登录;初次档案为空、无 AI 导入;手填公司名/主营业务后保存 v1;刷新后仍可读;关闭并重新启动 Java 进程、重新登录后内容与 v1 仍在;历史验证任务仍在;缺 Key 显示 WAITING_INPUT,实际调用列表为空;退出回到登录页。测试服务已关闭,测试数据未写入真实库。
- 测试使用 H2 MySQL 模式和本地 HTTP 协议样例,不证明真实 MySQL/供应商可用。H2 由 Spring Boot 管理为 2.4.240,Flyway 提示其已验证版本为 2.3.232;当前 3 组迁移与测试均通过,仍需真实 MySQL 验收。
![D1 缺凭证时的真实等待状态与零实际调用](./d1-service-check.png)
| 依赖验收 | 当前状态 | 补充后执行 |
| --- | --- | --- |
| MySQL 迁移、刷新与后端重启后档案仍可读 | 待补数据库,未验证 | 启动、保存、刷新、重启、登录回查版本 |
| 知了余额与权限 | 待补 `ZLBX_API_KEY`,未验证 | 余额单项任务 |
| 知了检索/详情/主体/画像字段与费用 | 未发真实请求 | 小样本任务,记录字段、耗时、HTTP、cost,脱敏后锁定差异 |
| DeepSeek 文本/JSON/流式 | 待补 `DEEPSEEK_API_KEY`,未验证 | 分别创建三项任务,记录实际 model 与 usage |
| DeepSeek Search / Fetch | 未发真实请求 | 独立两项任务;不能由文本成功推定联网通过 |
| DeepSeek 视觉 | 未发真实请求 | 样图识别应读出 D1 8240,人工核对内容与 usage |
真实验证请使用页面逐项显式发起,不要一次批量跑完整深度报告。任务详情保存实际返回数据供契约核对,文档中只登记脱敏字段与调用 ID,禁止复制 Key、原始认证头和带签名参数的完整 URL。
官方协议核对(2026-10-26):[DeepSeek 模型与调用](https://api-docs.deepseek.com/quick_start/agent_integrations/)、[Search & Fetch](https://api-docs.deepseek.com/guides/search/)、[视觉](https://api-docs.deepseek.com/guides/vision/)、[Spring Security CSRF](https://docs.spring.io/spring-security/reference/servlet/exploits/csrf.html)。模型默认 `deepseek-flash`,实际标识以每次响应为准;不能把参考项目的旧模型别名当作实测版本。
# D2 实施与验收记录
日期:2026-10-27(北京时间)。范围对应《四天开发计划》4.1–4.3。
**D2 前后端代码与本地联调已完成,真实 MySQL / 知了接口验收尚未通过。** 当前执行环境未配置数据库、admin 初始密码、知了及 DeepSeek 凭证,本轮未向真实供应商发送请求,未产生外部查询费用。
## 交付范围
- 发现商机提供普通检索、获客报告、区域市场三个模式。默认全国、近 90 天;今天、三天、一周、一个月、半年、一年与自定义日期均可使用。日期在创建时固定,使用北京时间。
- 关键词使用逗号分隔,最多十个。OR 对接 `search_bids`;AND 对接 `query_bids_advanced` 的组间 AND。金额在本系统使用万元,适配接口时转换为元,并区分 `min_amount` 与 `min_money`。
- 普通检索的省份/金额是显式硬条件,按发布时间降序展示。获客省份/金额仅用于偏好排序,不排除其他省份或未知预算候选。可用同批临时偏好视图调整顺序,不请求新页、不改变原快照。
- 每页读取均记录真实请求开始、状态、耗时及实际费用;同一批次按公告 ID 去重,记录平台命中、已取数、去重数、展示数、页数和停止原因。预算等待后从下一页继续,不重新读取成功页。
- 同名标题不合并项目。有明确 `project_code`、采购方、地区和标段时建立阶段关联链,保留各阶段公告及证据;字段不足则保持独立公告。当前计数明确按公告,避免将无法核实的项目数冒充真实归并结果。
- 列表摘要逐页执行原文规则摘录,保留建设内容、地区、节奏、资质业绩片段、信息缺口及证据定位。未取得正文时不补造资质或工期,不自动逐项获取详情、调用企业情报或投标决策。
- 四维匹配由后端计算并冻结档案版本、权重、维度依据与完整性。档案未完善时不提供综合分;已完善时未知维度用中性 50 分并标待核验。按权重归一化,最终一次四舍五入取整;匹配分不是资格认证或中标概率。
- 方案支持保存、编辑、删除和手动执行。方案执行与版本登记同一事务提交后才派发任务。执行保存固定日期、条件、档案和公告事实/分析;编辑或删除方案不改变旧结果。历史 Tab 只回读,不触发收费请求。
- 关注八状态可人工自由跳转、从暂不考虑恢复、单独修改备注。状态/备注/历史一次事务提交,版本检查防覆盖,命令幂等防重复留痕;未变化的同值保存不新增历史。
- 标签支持创建、全局删除解绑、项目多选与筛选,账号隔离。标签绑定和删除会更新关注版本。取消关注沿用确认弹窗,只清理个人关注、历史与标签绑定,不删除公告或独立报告。
- 前端“了解采购方”“深入研判”保留显式入口,目前明确提示由 D3 接入,没有伪造深查调用。
## 区域市场的两种统计口径
区域市场明确指定的省份是硬条件,留空为全国;未填业务词时实际使用并公开展示:`智慧水务、供水、污水处理、水质监测、管网漏损`。
工作流先调用 `get_top_purchasers`、`get_top_suppliers`、`aggregate_bids_advanced(group_by=month)`,再读预算允许的公告页。三个聚合步骤共享任务预算、调用账本及哈希证据;预算暂停恢复时跳过成功步骤。
平台 Top 与趋势按其工具实际口径展示,公告勾选的阶段只约束公告样本。采购方工具统计采购、供应商工具统计中标、月度工具使用支持的公告口径,不能把这些数字与样本公告数混算成市场份额。只有样本统计时明确标“已读去重公告样本”;聚合失败或预算不足不以样本冒充平台统计。
由于 Top 工具的锁定契约未提供 AND 分组,区域市场当前只接受 OR;需要 AND 时使用普通检索/获客,不能悄悄改成 OR。公告初始保护值最多 5 页 × 50 条;市场的三次聚合也占请求预算,所以默认 5 次上限下通常只剩两页公告额度。达到部署保护值不能无限继续。
## 新增及扩展接口
所有接口在 `/api` 下,需要服务端会话;写请求必须带 CSRF。
| 方法与路径 | 行为 |
| --- | --- |
| `POST /searches` | `{conditions,maxCalls,maxCostUnits}`,必须带 `Idempotency-Key`;返回统一任务 |
| `GET /searches` | 最近 50 次执行,含方案名称/版本及时间;不产生外部调用 |
| `GET /searches/{id}` | 任务状态、已验证报告、实际调用与证据 |
| `GET /searches/{id}/items?page=1&size=20` | 从固定批次分页,每页 1–50;不读取上游新页 |
| `POST /searches/{id}/continue` | 原条件加新累计预算,独立幂等键;仅等待状态可继续 |
| `POST /searches/{id}/view` | `{preference,regions,minWan,maxWan}`;临时重排原候选集,无外部请求 |
| `GET /projects/{id}` | 当前账号已取得或关注的公告快照 |
| `GET/POST /search-schemes` | 列举/保存方案;保存不执行检索 |
| `PUT/DELETE /search-schemes/{id}` | 编辑需当前 version,删除保留独立执行记录 |
| `GET/POST /search-schemes/{id}/runs` | 历史任务 ID / 手动执行;POST 需幂等键,预算用部署上限;发现商机传 `strictFilters=true`,将旧 LEADS 方案的地区与金额转为新任务硬条件,原方案和历史任务不变 |
| `GET /watch?group=跟进中&tag=重点` | 可选按三个分组和标签筛选,含版本、公告、标签与历史 |
| `POST /watch/{id}/changes` | `{status?,note?,version}`,必须带幂等键;status 留空可单改备注 |
| `GET /watch/{id}/history` | 按关注版本排序的个人状态/备注历史 |
| `GET/POST /tags`、`DELETE /tags/{id}` | 标签列举、创建、全局解绑删除 |
| `PUT /watch/{id}/tags` | `{tags:[标签名称],version}`,必须带幂等键,标签必须属于本人 |
`conditions` 字段:`keywords`、`keywordMode: ANY/ALL`、`mode: SEARCH/LEADS/MARKET`、`beginDate/endDate`、`stages`;偏好 `preference: COMPREHENSIVE/REGION/BUSINESS/AMOUNT`、`preferredRegions`、`budgetMinWan/budgetMaxWan`;显式硬条件 `hardRegions`、`hardMinWan/hardMaxWan`。后端拒绝向 LEADS 偷渡硬筛选。所有金额非负、上下限有序、日期不晚于今天且跨度不超过一年。
数据库新增 **V5**:任务档案快照、列表分析快照与哈希、方案执行版本登记、关注幂等命令、历史版本、市场聚合证据关联。保留 V1–V4,不改写已发布迁移。生产仍必须使用 MySQL,H2 仅在测试作用域。
## 验证结果
| 验证 | 结果与证明范围 |
| --- | --- |
| Java 21 `mvn -o test` | **39 项通过,0 失败、0 错误、0 跳过**;H2 MySQL 模式+本机 HTTP 模拟供应商 |
| 前端 `npm run build` | TypeScript 与 Vite 构建通过,保留 >500 kB 包体提醒 |
| 本次新增/替换页面及契约、事件 Hook、App 定向 ESLint | 通过;未把旧 UI 组件全库 lint 作为已通过 |
| 本机浏览器获客/关注 | 登录、档案保存、方案保存、读取两页返回 4 条/去重 3 条、未知金额保留、完整测试样本 100 分、偏好视图、关注、状态备注事务、标签、历史、刷新回读均验证 |
| 本机浏览器区域市场 | 3 次平台聚合+2 页公告,共 5 次本机请求;聚合 800 与样本 3 分开展示;空档案综合分显示 `—` |
| 真实 MySQL / 供应商 | **未验证**,缺环境配置;不以模拟测试代替真实验收 |
自动测试还覆盖:OR/AND 参数和万元转换、原检索发布时间排序、评分精确权重及高分上限、缺正文/缺预算、证据篡改拒绝、同标题不同阶段保留、可靠编号关联、方案编辑/删除不改快照、旧档案不重算、关注重复命令与旧版本拒绝、标签权限/解绑、市场聚合预算恢复不重跑,以及原 D1 会话/CSRF/供应商失败边界。
下图为明确标注“测试”的本机夹具,不是真实采购项目:
![关注状态、备注、标签与历史测试](./d2-watch-fixture.png)
![平台聚合与公告样本范围测试](./d2-market-fixture.png)
## 开源架构参考与本次采纳
本次查阅六个仓库说明,并补读可访问的监控脚本、Fire Enrich 编排器、中文 DOCX 解析器和 DeepResearch 控制器。没有复制第三方源码或引入其运行依赖;历史调研中的提交与许可记录仍在 [GitHub 相似项目调研](./GitHub相似项目调研.md)。
| 项目与本次访问来源 | 可借鉴之处 | 本轮处理 |
| --- | --- | --- |
| [BidMaster-Pro](https://github.com/guangshu100/BidMaster-Pro) | 招标解读、Skill 与商机入口的功能组织 | 作为功能对照;本轮原始 fetchers 路径未成功访问,不追加未经核实的实现断言 |
| [全国机会监控脚本](https://raw.githubusercontent.com/FightingThrones/guiyang-tender-monitor-skill/main/guiyang-tender-monitor/scripts/tender_monitor.py) | 结构化来源、评分理由与日报字段 | 不复制分数阈值筛掉候选的做法,偏好变化保留原集合 |
| [中文 DOCX 解析器](https://raw.githubusercontent.com/sanwudazhiyuan/-bid-analysis/main/src/parser/docx_parser.py) | 段落/表格保留顺序、格式与证据定位 | 原文摘录保留定位;完整文件链路属于 D3,未提前声称完成 |
| [TenderGraph](https://github.com/Amawta-labs/tendergraph) | 后端在模型之外校验证据与来源版本,明确合成数据范围 | 公告证据、列表分析哈希、范围校验及冻结报告;不采用其合成商机作生产数据 |
| [Fire Enrich 编排器](https://raw.githubusercontent.com/firecrawl/fire-enrich/main/lib/agent-architecture/orchestrator.ts) | 按所需字段选择阶段、共享已取得上下文 | 列表摘要复用本批原始事实,不附带触发企业深查 |
| [DeepResearch 控制器](https://raw.githubusercontent.com/spring-ai-alibaba/deepresearch/main/src/main/java/com/alibaba/cloud/ai/example/deepresearch/controller/ChatController.java) | 有限执行、SSE、停止及人工继续入口 | 复用现有持久化任务/有序事件和预算等待;不整体迁入 Graph/RAG 平台 |
这些是针对本项目的工程判断,不是第三方部署、抽取准确率或供应商覆盖率的实测结论。
## 真实环境后续验收
按根目录环境示例配置 MySQL、admin 密码、知了 Key 后启动。先小样本确认 OR/AND、金额单位、公告正文及项目编号字段,再运行全国近 90 天获客。核对调用 ID、平台总数、分页、积分、来源;选浙江偏好检查安徽等候选及未知预算仍保留。独立验证市场三个工具的字段与口径,再验证服务重启后方案、报告与关注仍可读取。
D3 企业情报/项目深挖、文件解析及 D4 全范围恢复/历史会话等继续按原计划实施。当前摘要是可追溯规则摘录,不是模型完成的深度招标解读;不得以列表分数承诺资格通过或中标。
# D3 实施与验收
日期:2026-10-28(北京时间)。本次继续现有 D1/D2 未提交代码,没有重置或覆盖已有成果。
**状态:前后端代码、本地自动测试和浏览器联调已完成;真实 MySQL、知了、DeepSeek 账号联调未验证,因此不能把 D3 的真实服务验收门槛标为通过。** 本地 HTTP 模拟请求只用于可重复测试,不是实际供应商数据或计费凭证。
## 1. 已实现范围
### 企业情报与双公司对比
- `COMPANY_RESEARCH` 固定使用 company-intel 1.0.2。先查询企业候选;完整返回范围中仅有一个且全称精确匹配时可以自动确认。多主体、简称或模糊匹配均等待选择,不按记录量选择第一条。
- 双公司必须全部完成主体确认后才启动后续画像;两个主体不能相同。确认值与本任务候选比对,确认后锁定,预算继续不能把旧事实拼到新公司上。
- 基础画像、业务词、客户、供应商、中标明细、年度聚合和真实投标重叠竞对分别实际请求。历史明细与伙伴只覆盖返回页/Top20,不声称已取全量。单企业 Top3 竞对仅查基础画像,不递归展开。
- 双公司共同客户为两家客户样本的企业全称交集;交锋事实展示竞对工具原始 `co_bid_count` 等字段。没有交锋数据时不把行业头部当直接竞对。
- 公开资料通过后端 DeepSeek Search 查询,最多三条;首个安全来源再通过 Fetch 获取正文。每条网页来源单独登记证据;未检出风险不等于无风险。
- 已完成企业任务可选择画像、伙伴、业绩、竞对或公开资料局部追问。子任务复用经过校验的确认主体缓存,账本明确显示 `LOCAL / ENTITY_CACHE`,只补查选定部分,不重复执行整份工作流。
### 项目研判
- `BID_RESEARCH` 固定使用 bid-decision 1.0.4。支持完整标题、知了公告链接、其他公开公告链接及投标文件。普通公开链接先 Fetch,再使用公开标题站内定位;知了链接走详情工具原生 `bid_url` 参数,不自行删改签名。
- 公告或采购方有歧义时等待候选选择。快速模式取得项目正文、采购方基础画像与证据建议;完整模式增加采购方历史供应商/采购史、潜在竞争者、公开资料,并在明确有品牌及型号时查询历史单价。
- 服务项目或无型号时不查询品牌价格;不混算项目总价、设备单价或不同规格,不产生利润承诺和精确胜率。
- 创建项目任务时冻结我方档案;档案完善且取得公开项目正文时复用既有四维规则输出我方适配、完整性、依据与档案版本。评分不是资格认定或胜率。
- 文件没有完整公开标题时可先创建任务,再等待补充;不会把文件全文送到公开搜索。无站内结果时保留文件/公开网页事实并明确未核实。文件与公告是否完全一致、是否最新版,仍需人工核对。
- 获客结果的“了解采购方”“深入研判”先展示对应输入,用户显式发起后才创建父子任务。后端检查账号、批次及所选对象,每批最多五个、串行执行;结果链接显示在原对象下。初始获客报告不隐式深查。
### 文件与真实轨迹
- 上传只接受 `BID_PROJECT`,取当前会话账号为归属;沿用 CSRF。首次绑定后不能转移至另一个任务,公司档案导入不开放。
- 使用 Apache POI 5.5.1、PDFBox 3.0.8、jsoup 1.21.2 与 TwelveMonkeys WebP 解码。正文按段落/工作表与行/幻灯片/PDF 页保留定位;不伪造 Office 页码。依赖依据:[POI 提取文档](https://poi.apache.org/text-extraction.html)、[PDFBox 3 迁移文档](https://pdfbox.apache.org/3.0/migration.html)。
- 文字 PDF 本地提取,扫描页渲染后逐页视觉;同页存在文字页眉和大幅扫描图时仍走视觉。图片按帧解码,GIF 不只读取第一帧。Office 宏、HTML 脚本和外链不执行。
- 默认最大原件 20 MiB、PDF 50 页、视觉 20 页、提取全文 200,000 字符;工作表/幻灯片数复用 50 上限;临时解析图片总量最多为原件大小保护值的两倍(默认 40 MiB),按段检查。压缩包保留 POI 的压缩比防护,并限制单项解压大小。超限明确要求拆分,不静默截断。
- 原件、提取全文、临时页图都保存在数据库,24 小时到期或手动删除时统一清空,写入删除审计。任务报告必要摘录与调用账本保留,界面明确提示这一范围。
- 四个入口共享真实后端 SSE 和事件游标;移除 `runSkillTrace` 及原调研模板回答。收费步骤先落 STARTED,再发 HTTP;报告只展示持久化事件与已保存结果,不展示私有推理。
## 2. 预算、恢复与证据规则
- 部署默认外部请求保护值提高为 25、积分保护值为 100;可通过 `TASK_MAX_CALLS` / `TASK_MAX_COST_UNITS` 降低。单企业最多 18 次,双企业和项目最多 25 次,每个任务拥有独立调用及积分预算;实际执行还受部署保护值限制。
- 知了积分、DeepSeek token、联网请求次数分别记录,合计由后端权威计算、前端只展示,不相加为同一费用。缺失费用保持未知;不会用零或预估值冒充实际扣费。
- 达到调用/积分预算时暂停;知了响应缺积分时也暂停。继续时显式确认已发生的请求与未知费用,或增加预算。未知单价的首个请求可能超出积分保护值,不能承诺事前精确控制。
- 每个成功步骤保留唯一快照,继续或幂等重试跳过成功步骤。取消与发请求使用同一任务锁;取消后不再发送后续请求,在途请求照实保存结果和费用。
- 失败/未知结果不自动重试;服务重启仍使用已有的 PARTIAL 恢复规则,避免重放收费请求。
- 事实绑定证据 ID、完整来源 URL、定位和原始快照哈希。报告重建校验所有事实;并发读取时先取步骤,再取来源,避免把刚提交的步骤误判为缺失。
- 模型生成稿属于服务端草稿,不作为事实来源展示。模型建议只允许引用本任务已登记来源;关键数字必须原样存在于引用依据。未通过校验的建议隐藏,任务标为部分完成,保留可核查事实与费用。
## 3. 新增接口与请求示例
沿用 `/api/agent/tasks`、`/{id}/continue`、`/{id}/cancel`、`/{id}/events`、`/{id}/report`,写请求仍需会话、CSRF 和 `Idempotency-Key`。创建/继续幂等键各自作用于原有任务账本,刷新报告只读,不二次收费。
```json
{
"operation": "COMPANY_RESEARCH",
"workflow": "COMPANY_INTEL",
"input": "",
"entityConfirmed": false,
"maxCalls": 18,
"maxCostUnits": 10,
"research": {
"companies": ["待研究企业名称"],
"selections": {},
"mode": "FULL",
"fileId": null,
"parentId": null,
"targetProjectId": null,
"focus": null,
"acknowledgedCalls": 0
}
}
```
- 项目改用 `BID_RESEARCH / BID_DECISION`、`companies: []`,`input` 为完整标题/公开链接;上传文件时填写 `fileId`。`mode` 为 `QUICK` 或 `FULL`。
- `research.selections` 的键与候选 `choices[].key` 一致,值必须是本任务返回候选 ID。不能用 `entityConfirmed: true` 绕过候选校验;新建任务不能预先提交选择或费用确认。
- 继续沿用完整原请求,只修改合法选择、预算,以及已经发生的请求数 `acknowledgedCalls`。定位后的项目、公司、文件、模式、父任务和追问范围不能改变。
- 局部企业追问使用已完成企业任务 `parentId` 和 `focus`:`profile / partners / performance / competitors / public`。
- 文件:`POST /api/files`,multipart 字段 `purpose=BID_PROJECT`、`file`;`GET /api/files/{id}` 读取本人元数据与提取预览;`DELETE /api/files/{id}` 清理本人原件、全文与临时图片。浏览器不手设 multipart Content-Type,以保留 boundary。报告页在任务结束或取消后提供明确范围的原件删除操作。
- 新增迁移 `V6__research_files.sql`:研究步骤、锁定主体、原件/派生文件字段、删除审计。保留 D1–D2 表和请求指纹兼容,不修改已发布迁移内容。
## 4. 已执行验证
### 自动化
- 后端 `JAVA_HOME=$(/usr/libexec/java_home -v 21) mvn -q verify`:**79 项测试通过,0 失败、0 错误**。包括原有 39 项、D3 工作流 17 项、文件解析 23 项。
- 前端 `npm run build`:通过。
- 对本次修改涉及的 TS/TSX 执行 ESLint:通过。包括调研页、统一任务组件、事件订阅、API 客户端、发现商机入口、App、Topbar 及移除演示代码涉及文件。
- 两个仓库 `git diff --check`:通过。
工作流测试覆盖:同名等待前无深查、双公司都确认、唯一精确匹配、非法/锁定选择、单/双企业、快速/完整研判、标题/知了链接/公开链接/文件路径、X-Client 路由、预算恢复幂等、未知积分确认、暂停取消与在途取消计费、局部追问缓存、父子任务五对象及串行约束、篡改证据拒绝、模型引用失败隐藏、视觉实际 HTTP 与隐私字段隔离、文件归属/用途/CSRF/过期/删除。
### 格式矩阵
| 格式 | 本地代表性样本结果 | 定位/边界 |
| --- | --- | --- |
| TXT、MD、CSV、HTML | 通过 | UTF-8 中文、GB18030;HTML 不执行脚本;CSV 保留原始行 |
| DOC | 通过 | Apache POI 官方开源样本;段落定位,来源及许可证见测试资源目录 |
| DOCX | 通过 | 中文段落和表格,明确没有可靠分页 |
| XLS、XLSX | 通过 | 中文工作表、行号、数值;伪装后缀拒绝 |
| PPT、PPTX | 通过 | 中文文字、幻灯片编号 |
| 文字 PDF | 通过 | 本地提取,不额外视觉 |
| 扫描 PDF | 通过 | 按页生成视觉输入 |
| 混合 PDF | 通过 | 文字页/扫描页分别处理;文字页眉加扫描正文也识别为需视觉 |
| JPG、PNG、GIF、WebP | 通过 | 解码后转逐帧视觉输入;WebP 使用实际解码器 |
| 损坏、伪装、加密、超页/超全文 | 通过 | 明确失败或提示拆分,没有静默截断 |
这些是代表性合成/开源样本,并非全量真实标书。中文复杂 PDF、低清扫描、GIF 动画合成、Office 嵌入图片/复杂图表、超大表格和复杂布局在 D4 继续扩大样本验收。
### 浏览器(H2 + 本地 HTTP 模拟服务)
已实际登录测试账号并操作:四入口展示;同名企业只有一次主体查询即暂停;选择分公司后完成工作流;一次调用预算暂停及确认恢复;区域市场入口返回聚合/公告报告;从获客结果创建采购方子任务;multipart 上传非敏感 TXT 并完成文件项目快速研判。检查了真实事件、源链接、消耗、文件定位与缺口文案。
- [企业画像截图](images/D3-企业画像-本地模拟.png)
- [文件研判截图](images/D3-文件研判-本地模拟.png)
截图和界面测试资料均明确使用“界面测试”样本,不能当作知了或 DeepSeek 真实业务验收证据。测试服务使用内存数据库,验收后停止,不更改生产数据。
## 5. 尚未通过的真实验收与 D4 边界
1. 本地没有提供真实数据库连接、知了/DeepSeek 凭证,真实 MySQL 迁移/重启持久化、供应商字段/积分、模型、Search/Fetch 和视觉均**未验证**。需配置后按 D1/D2/D3 文档逐项实测,尤其核对各企业/项目工具的实际字段。
2. 模型事实名字、文件与公告一致性、历史价格可比规格仍需人工核验;服务端引用/数字校验不等于尽调结论真实或来源网站真实。
3. 明细与伙伴限返回首批,公开资料最多三条;共享客户是样本交集,不能称全量共同客户。未返回的事实显示缺口。
4. 多扫描页加完整研判可能达到累计 25 次保护上限,需要拆分资料或在创建时选择快速模式;不能无限增加预算绕过部署保护。
5. 前端构建有主 JS 包超过 500 kB 的体积提醒,构建成功;本次没有扩大到无关依赖清理或全站代码拆包。
6. D4 的完整历史会话 CRUD、整批问答、断线/服务重启场景扩大、全范围真实资料格式/异常验收和部署交付仍按四天计划继续。本次没有把这些项目提前标为完成。
# D4 实施与验收
日期:2026-10-28(北京时间)。继续 D1–D3 已有未提交成果,未重置两个仓库。
**交付状态:D4 前后端实现、本地回归、代表性格式测试、浏览器联调与运行文档已完成;真实 MySQL、知了和 DeepSeek 联调未验证。不能据此宣称四天计划全部真实验收通过。**
当前进程未设置 DB_URL、DB_USERNAME、DB_PASSWORD、ADMIN_INITIAL_PASSWORD、ZLBX_API_KEY、DEEPSEEK_API_KEY;后端没有 `.env`。未读取或输出其他项目的凭证,未使用模拟数据替代真实服务证据。
## 1. 本次实现
### 历史会话与真实问答
- 新增会话新建、按标题及用户问题搜索、分页、自动标题、带版本的重命名、删除与历史消息读取。首次问题自动生成标题,人工命名后不再覆盖;同一任务重复关联不重复写消息。
- 调研四入口创建的任务关联到持久化会话。较早 D1–D3 的独立任务仍可从最近任务回查;没有静默为旧任务批量生成会话。
- “发现商机”提供整批结果及单项目 AI 提问,“重点关注”提供单项目入口。打开入口不调用模型,明确提交问题才发起一个 `SNAPSHOT_QA` 任务。
- 整批从数据库读取该快照的全部 `search_item`,不取当前分页的 20 条,不使用前端临时偏好排序作为事实。单项目仅包含所选项目。候选、条件、日期、已读取数、平台总命中数、来源在提交时冻结并计算完整性哈希。
- 问答只调用一次后端模型,不重新执行招投标检索、企业情报或项目深查。报告标为建议与推断;逐条核验来源、关键数字及链接。无效回答隐藏,任务部分完成,实际模型与 token 仍保留。
- 每个候选保留全部标准化字段;每条正文最多提供前 1000 字,明确标记摘录。完整上下文超过 600,000 字符时拒绝并建议单项目提问,不静默省略候选,也不宣称读过完整标书。
- 后续问题默认沿用最近一次快照问答范围,每次按当时批次冻结;每次模型请求独立记账。当前不把历史模型回复当新事实来源;依赖省略指代的问题应补全对象名称。
- 删除会话只删除会话及消息。独立任务、实际费用、关注、原件按各自生命周期保留;桌面与窄屏均有明确删除范围和确认交互。
- 移除原未接入后端的 AI 面板、本地模板回答、模拟逐字流及内存会话存储,当前页面不会将这些内容作为真实结果展示。
### 文件生命周期与格式边界
- 到期文件在 GET 时立即清理,定时任务尚未运行也不能返回全文。定时清理每次最多 100 条,按到期顺序处理;重复清理/手动删除只保留一次删除审计。
- 文件绑定、证据记录同事务;发出新的依赖文件请求前再次检查删除、归属和过期。已经登记并发出的请求属于在途请求,删除不能撤回已发送内容和实际费用。
- 原件、提取全文与派生图片保存在有期限的临时表,删除统一置空。长期文件证据只保留每段最多 2000 字的必要摘录和定位,不再复制整份长文件全文;这部分摘录与费用账本不会随原件删除。
- 补充 DOC/DOCX、XLS/XLSX、PPT/PPTX 的内嵌图片提取;位图走相同视觉预算。无法可靠定位的图片只标资源编号及“位置需人工核对”,不伪造页码。不能解码的矢量图明确提示转换后补充。
- 既有 20 MiB、50 页、20 视觉页、200,000 字、临时图片总量保护值继续生效。Office 图片消耗同一视觉页预算,超限明确拆分。
- 公司档案导入仍关闭;文件只允许 `BID_PROJECT`。
### 恢复、费用与错误
- SSE 保留事件游标、去重及重连;网络不可达时按退避延迟只读重试,最多 15 秒间隔,恢复后追完最终事件。401/403/404 停止重连,登录失效回登录页。
- 创建与继续任务仍通过持久化幂等键及请求指纹防重;浏览器重复点击、网络结果未知后手动重试保留当前请求键。页面刷新、历史读取、来源展开、用量读取均不创建新收费任务。
- 重启把正在执行的任务标为 PARTIAL,在途 STARTED 调用标 UNKNOWN / RESTART_INTERRUPTED,不自动重放。生产会话保存在实例内存,重启后需要重新登录。
- 失败、部分完成、预算暂停均保留已有来源、调用与费用,并提供补充资料、调整条件或返回入口的下一步。取消后可手动刷新结果与用量,核对仍在途的请求。
- 新增 `/api/usage`,只汇总本账号持久化调用;知了积分、模型 token、未知用量分别列示,不能把本地账本当平台余额。服务验证页可显式读取,不隐式发起余额查询。
## 2. 已执行验证
运行环境:Java 21.0.12.1、Maven 3.9.16、Node 23.11.1、npm 10.9.2。Maven 启动命令明确指定 Java 21,避免主机默认 Java 8。
| 验证 | 实际结果 |
| --- | --- |
| `JAVA_HOME=$(/usr/libexec/java_home -v 21) mvn -q -Djava.awt.headless=true verify` | 102 项测试,0 失败、0 错误、0 跳过;生成后端 JAR |
| `npm run build` | TypeScript 和 Vite 构建通过,生成 `rz-GB-web/dist` |
| 本次修改涉及的 TS/TSX、Vite 配置 ESLint | 通过 |
| 两仓库 `git diff --check` | 通过 |
| 中文文字 PDF 额外样本 | 本机系统中文字体生成非敏感样本;中文、预算、行内报价文本完整提取,保留第 1 页定位,不调用视觉 |
| 实际进程强制中断/重启 | 临时文件 H2 + 本机模拟 HTTP;重新登录后 PARTIAL,原调用 UNKNOWN,报告/事件可读;模拟请求始终一次,无自动重放 |
| 浏览器 | 测试账号登录 → 模拟检索 → 整批问答 → 来源/费用 → 会话改名 → 刷新恢复 → 桌面侧栏搜索;同时检查窄屏会话操作 |
测试共六组:原基础业务 29 项、排序 5 项、摘要匹配 5 项、研究工作流 17 项、文件解析 30 项、D4 集成 16 项。D4 集成覆盖 25 个候选跨两页的末条问答、冻结范围、单项目范围、并发幂等、自动标题/搜索/版本冲突/删除、账号隔离、坏引用/坏数字、供应商认证/限流/超时/不可达、即时过期清理、长期摘录范围和只读用量。
测试最初在受限沙箱中因禁止本机 HTTP 端口失败,改为允许本机端口的测试进程后通过;文件解析以 `java.awt.headless=true` 运行。没有把环境启动失败记为业务测试通过。
![D4 历史会话与快照问答(本地模拟)](images/D4-历史会话与快照问答-本地模拟.png)
截图里的 `d4-ui-fixture-only` 和“界面测试”均为本地模拟资料,不代表真实 DeepSeek 模型、知了数据或真实扣费证据。
### 格式矩阵
| 格式/边界 | 本地结果 | 验证口径 |
| --- | --- | --- |
| TXT、MD、CSV、HTML | 通过 | UTF-8 中文、GB18030、CSV 原始行、HTML 脚本不执行 |
| DOC | 通过 | POI 开源段落样本;真实中文老 DOC 复杂排版未验证 |
| DOCX | 通过 | 中文段落/表格、内嵌位图;不伪造页码 |
| XLS、XLSX | 通过 | 中文表格/行号、内嵌图片、公式读取缓存值,不更新外链 |
| PPT、PPTX | 通过 | 中文幻灯片、内嵌位图,图像资源位置需人工核对 |
| 文字 PDF | 通过 | 常规英文样本及额外中文样本;不触发视觉 |
| 扫描/混合 PDF | 通过 | 逐页渲染、文字页与扫描页分流、文字页眉加扫描正文 |
| JPG、PNG、WebP、GIF | 通过 | 实际解码;GIF 增加两帧样本与逐帧定位 |
| 损坏/后缀伪装/加密/超限 | 通过 | 拒绝或要求拆分,不静默截断 |
| 低清真实标书、复杂图表/矢量/动画合成语义 | 未验证 | 无真实标书和真实视觉凭证;不承诺完整版面还原或 OCR 准确率 |
扫描件测试验证了本地渲染、视觉请求结构、位置和成本记录,未证明真实模型识别质量。
### 异常矩阵
| 场景 | 已验证行为 |
| --- | --- |
| 无结果、未知预算/地区、部分页成功 | 保留已读范围与缺口,未知金额不当零、不删除候选 |
| 401/403、业务失败、余额不足 | 区分认证、业务与预算原因;等待或失败,不当作无结果 |
| 429、网络超时、HTTP 503、网页域名不可达 | 明确原因及下一步;超时结果 UNKNOWN,不自动重试 |
| 模型引用或数字不可验证 | 隐藏生成结论,保留事实与实际用量 |
| 重复提交/同键不同内容 | 同键同内容复用;不同内容或会话冲突返回 409 |
| SSE 事件重放、取消、服务重启 | 事件有序、重放不创建收费调用;取消停止后续;重启保留未知费用 |
| 文件过期/删除/跨账号/跨任务 | 全文及派生物清理;拒绝非法复用,审计不重复 |
| 冻结上下文过大 | 明确提示单项目提问,不删除候选凑入模型上下文 |
## 3. A01–A20 验收账
“本地通过”仅指合成样例、测试数据库和模拟 HTTP。真实验收列不能由本地结果自动推导。
| 编号 | 本地判定与证据 | 真实验收 |
| --- | --- | --- |
| A01 鉴权退出 | 通过;真实安全过滤链、CSRF、登录/退出测试及浏览器登录 | 待指定环境 |
| A02 持久化 | 通过;数据库读取及临时文件 H2 进程重启 | MySQL 未验证 |
| A03 四入口 | 通过;既有 D3 浏览器记录及工作流测试 | 未验证 |
| A04 招投标实际请求 | 通过;本机 HTTP 调用与报告对应 | 知了未验证 |
| A05 初始不深挖 | 通过;工具白名单与调用断言 | 待真实账本核对 |
| A06 偏好不变候选 | 通过;候选集合、未知预算测试 | 待真实数据复核 |
| A07 两种排序 | 通过;冻结排序及匹配测试 | 待真实数据复核 |
| A08 召回范围 | 通过;分页、去重、平台总数、停止原因 | 供应商字段未验证 |
| A09 主体确认 | 通过;确认前无深查、范围冲突测试 | 同名真实主体未验证 |
| A10 双公司/项目 | 通过;单/双主体和快/完整工作流测试 | 未验证 |
| A11 真实轨迹 | 通过;本机请求账本与事件、移除模拟流 | 真实模型流未验证 |
| A12 来源与推断 | 通过;证据哈希、引用/数字拒绝、来源页面 | 来源事实仍需人工核验 |
| A13 预算费用 | 通过;暂停恢复、未知费用、token 分账 | 真实积分/账单未验证 |
| A14 八状态 | 通过;事务、版本、幂等、标签与历史测试 | 待指定环境演示 |
| A15 全格式 | 通过;代表性格式矩阵 | 真实资料/真实 OCR 未验证 |
| A16 清理删除 | 通过;归属、到期、手动清理、必要摘录审计 | 待指定环境定时任务核对 |
| A17 无结果/失败 | 通过;异常矩阵与可执行提示 | 真实错误字段未验证 |
| A18 幂等恢复 | 通过;SSE 测试及实际进程重启,无重复请求 | MySQL/反向代理断线未验证 |
| A19 会话快照 | 通过;CRUD、浏览器刷新、跨两页整批 QA | 指定环境未验证 |
| A20 评分 | 通过;非法权重、精确舍入、档案版本及高分样本 | 真实样本不硬造高分 |
## 4. 交付与尚未完成项
- 实现位于后端 `rz-GB` 与相邻前端 `rz-GB-web`;新增 Flyway V7,未修改 V1–V6 的已发布结构。代码按要求补充中文业务注释。
- 构建、部署、接口、事件/幂等/金额/日期单位和确认流程见 [接口契约与运行交付](接口契约与运行交付.md)。三个 Skill 锁定版本及本地工具映射也在该文档。
- 前端构建仍有主 JS 超过 500 kB 的提示,构建成功;本轮未扩展到全站拆包。
- 单实例任务执行器与内存会话沿用现有设计;多实例调度、自动通知、注册、标书生成和生产高可用不在本期。
- 仍需提供指定测试环境 MySQL 连接、admin 初始密码、知了和 DeepSeek 凭证/余额及代表性真实标书,再按四天计划 6.2 演示脚本和 D1–D3 的真实服务清单执行。届时记录实际模型 ID、工具字段、积分、token、Search/Fetch、扫描件识别及数据库重启结果。
- 未做生产部署,也没有提交、推送、创建 PR 或改动真实业务数据。真实凭证不足属于未验证条件,不等于已通过的交付承诺。
# 如昼商机助手:GitHub 相似项目调研
调研日期:2026-10-26(北京时间)。
## 1. 结论
有相似项目,但本轮检索尚未发现同时覆盖“水行业商机召回、三个专用 Skill、企业情报、具体项目研判、人工跟进八状态”的现成完整替代品。已有仓库分别覆盖招标解读、机会监控、企业信息补全、证据校验和 Agent 编排。
建议继续现有 Java/React 项目,按模块借鉴。优先阅读 Spring AI Alibaba DeepResearch、TenderGraph 和中文招标文件解析系统;BidMaster-Pro 适合作功能对照,但不宜仅凭 README 就整体引入。
这是一份公开资料与定向源码调研,不是部署验收、安全审计或许可证法律意见。本文中的“值得参考”“不宜直接引入”是结合本项目范围作出的工程判断。
## 2. 检索与核实方法
- 以 GitHub 为主,补充检索 Gitee;查询招投标 Agent、商机监控、采购情报、企业调研、销售线索与 Java 研究 Agent。
- 下表八个项目均查看仓库页面/README,并通过 GitHub 公共 API 获取许可证识别、Star、归档状态和默认分支最新提交。
- 定向读取九个实现/依赖文件:各项目一个关键文件,DeepResearch 另读 `pom.xml`。未安装、执行第三方代码,未进行真实模型和数据源调用。
- Star 是调研当时的快照;最近提交日期取默认分支最新提交的 committer 时间,转换为北京时间。不是搜索引擎抓取日期,也不是仓库 `updated_at` 或其他分支 push 时间。
- 下表八个仓库在查询时均未归档,但“不归档”“有测试目录”“Star 多”均不能证明生产可用。
## 3. 候选项目对比
“关联度”指与本项目某个模块的接近程度,不是完整覆盖率。
| 项目 | 关联度与方向 | 技术形态 | Star | 默认分支最新提交(北京时间) | 许可核实 |
| --- | --- | --- | ---: | --- | --- |
| [BidMaster-Pro](https://github.com/guangshu100/BidMaster-Pro) | 高:中文招投标 Agent、解读、Skill、商机监控 | Python/FastAPI;React/Electron 客户端 | 409 | [2026-09-03](https://github.com/guangshu100/BidMaster-Pro/commit/cc89d9093651e3410f68384f926ceef672b76534) | LICENSE 为 AGPL-3.0;README 却写 MIT,存在冲突 |
| [guiyang-tender-monitor-skill](https://github.com/FightingThrones/guiyang-tender-monitor-skill) | 高:中小企业商机发现、适合度、日报 | Python 脚本+Skill+来源目录 | 2 | [2026-07-16](https://github.com/FightingThrones/guiyang-tender-monitor-skill/commit/072d054b509fc67a726bd2c8fe14fcd367f7b70a) | CC BY-NC 4.0;README 明示商业用途需另行授权 |
| [招标文件智能解析系统](https://github.com/sanwudazhiyuan/-bid-analysis) | 高:中文资格、评分、风险、原文定位 | Python 解析/服务+Web 前端 | 35 | [2026-04-23](https://github.com/sanwudazhiyuan/-bid-analysis/commit/08dc9366e408d335dca7d9e46974e46fe8d60f65) | Apache-2.0 |
| [TenderGraph](https://github.com/Amawta-labs/tendergraph) | 高:投标工作台、证据、人工确认 | TypeScript/Next.js,Codex 相关运行链路 | 0 | [2026-07-21](https://github.com/Amawta-labs/tendergraph/commit/771537b070004f91b20b26c34e460655c9dd03f4) | 代码 Apache-2.0;仓库声明合成基准数据另用 CC BY 4.0 |
| [TenderAI](https://github.com/teja05-45/TenderAI) | 中高:公告文件提取、OCR、引用问答 | FastAPI、LangGraph、ChromaDB、Streamlit | 0 | [2026-07-23](https://github.com/teja05-45/TenderAI/commit/e82b0969d90df3e87fe4aa0f267e9b0ede5620a7) | MIT |
| [Fire Enrich](https://github.com/firecrawl/fire-enrich) | 中高:企业情报、资料补全、来源展示 | TypeScript/Next.js;Firecrawl+OpenAI | 1,293 | [2025-10-08](https://github.com/firecrawl/fire-enrich/commit/94e061dc5bab94e5838cceb8b3d5e6af329d2d50) | MIT;不代表其外部服务和全部依赖同许可 |
| [Spring AI Alibaba DeepResearch](https://github.com/spring-ai-alibaba/deepresearch) | 业务中、技术高:规划、工具、流式、人工反馈 | Java/Spring AI Alibaba Graph;Vue3 | 373 | [2026-03-02](https://github.com/spring-ai-alibaba/deepresearch/commit/7f009adf56fadacdc78a02c4967aebe784918b11) | Apache-2.0 |
| [mtender-mcp-server](https://github.com/nalyk/mtender-mcp-server) | 中:采购搜索、买方/供应商统计、阶段与文档 | TypeScript/Node.js/MCP | 0 | [2026-05-06](https://github.com/nalyk/mtender-mcp-server/commit/9512496f85fdcb69733770f2423a4bea7079a8ff) | ISC |
许可证列结合仓库页面、README、GitHub API 与实际文件核对。其中监控 Skill 的 API 识别结果为 `NOASSERTION`,其 README/LICENSE 明确使用 CC BY-NC 4.0,不能把未自动识别当作无约束许可。
## 4. 逐项可借鉴内容与限制
### 4.1 BidMaster-Pro:功能覆盖较广,但不能直接当完整底座
README 描述招标解读、标书生成、检查、OCR、公司知识库和商机资讯。与我们的单项目分析和 Skill 组织形式接近,但其重心还包括本期不做的标书生成与排版。[仓库说明](https://github.com/guangshu100/BidMaster-Pro)
抽查发现 `services/news/fetchers.py` 实现 RSS 等获取路径,但其中 HTML 适配器交由其他流程,浏览器适配器是空实现;这不证明整个项目没有其他抓取能力,但不足以据此认为已具备通用浏览器采集。[抽查文件](https://github.com/guangshu100/BidMaster-Pro/blob/cc89d9093651e3410f68384f926ceef672b76534/services/news/fetchers.py#L250)
README 的 MIT 描述与实际 AGPL-3.0 LICENSE 不一致。建议作为功能/界面对照,代码复用前先明确具体版本和授权,不能按 README 的 MIT 一句直接采用。[实际 LICENSE](https://github.com/guangshu100/BidMaster-Pro/blob/cc89d9093651e3410f68384f926ceef672b76534/LICENSE)
### 4.2 全国招投标机会监控 Skill:最贴近“每天找几个值得跟的项目”
它面向中小软件和集成企业,提供来源池、机会评分、摘要与日报;值得参考报告字段与来源管理。本项目仍以知了 API 为主,不需要因此回到自建全网爬虫。[仓库说明](https://github.com/FightingThrones/guiyang-tender-monitor-skill)
源码中存在 `score >= 8` 才保留候选的逻辑;若照搬会与我们“偏好仅用于排序”的规则冲突。其软件行业关键词与判断规则也不能直接当水行业评分。[筛选实现](https://github.com/FightingThrones/guiyang-tender-monitor-skill/blob/072d054b509fc67a726bd2c8fe14fcd367f7b70a/guiyang-tender-monitor/scripts/tender_monitor.py#L560)
作者明确商业用途需要另行授权,因此先作为产品参考,不纳入默认代码复用清单。[许可说明](https://github.com/FightingThrones/guiyang-tender-monitor-skill#许可证)
### 4.3 中文招标文件智能解析系统:最值得参考文档提取
README 覆盖 DOC/DOCX/PDF 解读、资格和评分条件、风险提示与原文定位。源码 `parse_docx` 按 XML body 的出现顺序交错读取段落和表格,适合借鉴到我们对招标文件条件、金额和上下文的提取中。[解析实现](https://github.com/sanwudazhiyuan/-bid-analysis/blob/08dc9366e408d335dca7d9e46974e46fe8d60f65/src/parser/docx_parser.py#L325)
它偏标书解读与审查,不能替代商机召回、企业情报和人工跟进。README 的速度与准确性宣传未由本轮复现;许可为 Apache-2.0,仍需对拟复用文件及依赖逐项检查。[仓库与许可](https://github.com/sanwudazhiyuan/-bid-analysis)
### 4.4 TenderGraph:最值得参考“结论必须有证据”
提供投标工作台、来源版本、要求变更和人工审批;README 明确机会收件箱使用合成数据,不宣称通用实时商机发现,所以不能当真实公告数据服务。[项目说明与范围](https://github.com/Amawta-labs/tendergraph)
`gates.ts` 在模型之外校验结构、claim/evidence ID、来源范围、可用状态和快照哈希。适合借鉴“后端拒绝没有证据的结论”的方法,不需要整体搬入其审批体系或模型运行方式。[校验实现](https://github.com/Amawta-labs/tendergraph/blob/771537b070004f91b20b26c34e460655c9dd03f4/src/lib/harness/gates.ts#L23)
该仓库是 Build Week 版本,Star 和使用样本较少;本轮未验证部署、运行成本及生产稳定性。
### 4.5 TenderAI:适合参考文件处理状态与引用问答
README 描述 PDF/OCR、结构化元数据、RAG 问答、项目对比和报告。实际 LangGraph 文件有解析、OCR、元数据、embedding、finalize 节点,并在失败时转到收尾节点,能参考其处理链路。[工作流源码](https://github.com/teja05-45/TenderAI/blob/e82b0969d90df3e87fe4aa0f267e9b0ede5620a7/app/agents/graph.py#L33)
仓库页面仅有 3 次提交,且采用 Python/Streamlit,未见与我们相同的获客与跟进产品闭环。适合作流程参考,不能据此承诺中文全部文件格式或现有 React/Java 能直接复用。[仓库](https://github.com/teja05-45/TenderAI)
### 4.6 Fire Enrich:适合参考企业情报按需补全
从邮箱/域名推导企业,再补全企业画像等字段,带来源上下文。源码按所需字段选择阶段,并把已发现数据传给后续阶段,可借鉴为“只补查用户需要的信息”。[编排实现](https://github.com/firecrawl/fire-enrich/blob/94e061dc5bab94e5838cceb8b3d5e6af329d2d50/lib/agent-architecture/orchestrator.ts#L19)
它不是中国企业同名确认、历史中标关系或真实竞对数据服务;其接口依赖 Firecrawl/OpenAI,迁到知了/DeepSeek 需要适配。默认分支一年多未有新提交,不能仅因 1,293 Star 就判定持续活跃。[仓库](https://github.com/firecrawl/fire-enrich)
### 4.7 Spring AI Alibaba DeepResearch:与当前后端最接近
支持研究计划、在线搜索、人工反馈和流式输出。实际 `ChatController` 存在 `/stream`、`/stop`、`/resume` 路径,适合参考任务执行和用户确认交互。[控制器](https://github.com/spring-ai-alibaba/deepresearch/blob/7f009adf56fadacdc78a02c4967aebe784918b11/src/main/java/com/alibaba/cloud/ai/example/deepresearch/controller/ChatController.java#L105)
但核对到其依赖为 Java 17、Spring Boot 3.4.8、Spring AI Alibaba 1.0.0.4;我们当前为 Java 21、Boot 4.1.2,前端也为 React 而不是 Vue。不能把“同为 Spring”当成复制即可运行的兼容保证。[依赖文件](https://github.com/spring-ai-alibaba/deepresearch/blob/7f009adf56fadacdc78a02c4967aebe784918b11/pom.xml#L12)
建议借鉴有限步骤、人工反馈与 SSE 接口形态,不整套引入其多 Agent、代码执行和混合 RAG 基础设施。
### 4.8 mtender-mcp-server:数据工具边界参考
面向摩尔多瓦公开采购,README 提供搜索、采购方/供应商聚合、公告阶段、文档获取和 OCR 回退等工具。源码将搜索注册成独立 MCP 工具,可参考查询参数、分页与资源链接的边界。[搜索工具](https://github.com/nalyk/mtender-mcp-server/blob/9512496f85fdcb69733770f2423a4bea7079a8ff/src/tools/search.ts)
它不提供中国水行业公告或知了数据,国家数据模型也不同。只作工具接口和采购生命周期设计参考,不新增为第四个业务 Skill。[仓库](https://github.com/nalyk/mtender-mcp-server)
## 5. 与本项目的对应关系
下表为本轮工程判断;“参考”不表示已接入、适配或测得性能收益。
| 本项目需求 | 优先参考 | 采纳尺度 |
| --- | --- | --- |
| 主 Agent 路由、计划、补问 | DeepResearch | 参考人工中断/继续的接口思路,保留三个受控工作流 |
| 真实调用轨迹与 SSE | DeepResearch | 业务事件与模型报告分开;仍需自行实现持久化事件、幂等和收费去重 |
| 水行业商机召回 | 已提供的 tender-search+知了 API | 本轮仓库不能替代已确认数据源;监控 Skill 仅借鉴来源与报告设计 |
| 偏好不漏候选 | 本项目自行实现 | 不复制监控脚本的分数硬过滤或软件行业规则 |
| 中文招标文件提取 | 中文招标文件解析系统、TenderAI | 参考段落/表格顺序、失败收尾和证据定位,不为此整体改成 Python |
| 企业情报按需查询 | Fire Enrich | 参考阶段化和共享上下文,主体确认/中标客户关系仍使用既定 Skill |
| 事实/推断、引用校验 | TenderGraph | 先实现证据 ID 存在性、来源范围、必要数字校验;不扩展完整审批系统 |
| 八状态、标签、档案和检索快照 | 现有前后端继续实现 | 本轮没有找到可直接替换该业务闭环的模块 |
| 费用审计与预算暂停 | 本项目自行实现 | 不能把流式输出或 Agent 日志等同于真实积分/token 账本 |
## 6. 对四天计划的影响
本轮没有证据支持“换成某仓库可以立即缩短到一天上线”。引入不同语言后端、不同前端、向量库和多 Agent 平台,会增加迁移与运维工作。
建议保持原四天计划,只补充以下设计参考:
1. **D1:**参考 DeepResearch 的执行/人工反馈接口形态,仍以现有统一任务对象和白名单工具客户端为准;单独验证 Boot 版本兼容,不直接导入旧依赖。
2. **D2:**把“偏好变化候选集不变”作为必须自动验证的规则;引入第三方评分前先检查是否存在阈值删除。
3. **D3:**参考中文文档解析的结构顺序与 TenderGraph 的证据准入;企业情报只执行被请求的步骤。
4. **D4:**增加引用不存在、失效证据、阶段重复公告、文件表格错配及重复收费的验收,而不是根据开源项目宣传免验收。
代码复用若发生,应固定具体提交、记录来源和许可,先抽取最小模块验证。此调研没有复制任何第三方代码进业务项目,也没有修改原开发计划或业务代码。
## 7. 补充线索与未验证部分
检索还发现 [DuoLa-BidAgent](https://github.com/duolaAmengweb3/DuoLa-BidAgent)(本地企业资料/公开招投标/项目工作区)、[bid-agent](https://github.com/yellowfacehc/bid-agent)(招标信息获取)和 [ai-lead-radar](https://github.com/ck830820/ai-lead-radar)(招采线索监测)。本轮只阅读搜索返回的项目说明,未核实其完整源码、许可和维护数据,不纳入上述优先复用建议。
Gitee 检索返回的候选多为采购管理、监管评标或二次转载,未进一步验证为与本项目相同的销售侧商机 Agent。本轮结论是有限范围检索结果,不是对 GitHub/Gitee 全站项目的穷尽证明。
尚未验证:第三方完整部署、真实中国公告召回率、中文抽取准确率、模型实际消耗、依赖安全性、商用授权适用性。上述指标不能从 README、Star 或少量代码抽查直接推断。
# 如昼商机助手开发文档
更新时间:2026-10-28(北京时间)。
本目录记录结合现有前后端和三个专用 Skill 制定的需求与四天开发计划。已完成 D1–D4 代码实现与本地测试,真实 MySQL、知了与 DeepSeek 的验收待补充环境配置;具体结果见 D1–D4 记录。
## 阅读顺序
1. [需求分析与 Skill 集成方案](./需求分析与Skill集成方案.md):已确认范围、现状差距、Skill 能力与冲突、场景路由、召回排序、任务事件、证据成本、文件与数据设计。
2. [四天开发计划](./四天开发计划.md):开工依赖、D1–D4 交付与验收、接口草案、二十项验收矩阵、测试和风险处理。
3. [D1 实施与验收](./D1实施与验收.md):当前代码范围、接口、环境变量、保护值、测试结果与真实依赖待验证项。
4. [D2 实施与验收](./D2实施与验收.md):检索获客、市场聚合、方案快照、关注事务、架构参考和 39 项自动测试记录。
5. [D3 实施与验收](./D3实施与验收.md):企业/项目工作流、文件、主体选择与预算恢复。
6. [D4 实施与验收](./D4实施与验收.md):历史会话与快照问答、清理、102 项测试、格式/异常矩阵及逐项真实验收状态。
7. [接口契约与运行交付](./接口契约与运行交付.md):V1–V7、构建部署、事件/幂等、金额日期单位及工具映射。
## 本轮确认
D3 详细结果见 [D3 实施与验收](./D3实施与验收.md):企业/项目工作流、文件格式矩阵、候选与预算恢复、79 项测试和浏览器本地联调记录。
- 后端为 `rz-GB`,前端为相邻的 `rz-GB-web`;后续由 AI 实现并完成联调。
- 知了标讯 API 是本期主要数据源;飞书清单待补,不自建全网站爬虫。
- 一个主 Agent 编排 tender-search 2.3.0、company-intel 1.0.2、bid-decision 1.0.4;只承诺这三个 Skill 的能力。
- 真实 DeepSeek 模型与公开资料检索;后端配置凭证,admin 预设账号。
- 保留原有检索、匹配度、方案、跟进、档案、会话,新增调研四入口与获客流程。
- 原检索按发布时间排列;获客报告按相关度/偏好排序,地域和金额偏好不默认过滤候选。
- 获客初始报告只真实调用招投标检索;用户明确选择后才做企业情报或投标决策深挖。
- 文件只用于投标项目解析;公司档案手填,关闭原 AI 文件导入。
- 格式覆盖文本、PDF(含扫描件)、Word、Excel/CSV、PowerPoint、HTML 与指定图片格式;详细清单和限制见需求文档。
- 来源、数据缺口、实际调用与成本可审计;状态由人手动修改。
## 更新原则
产品需求和用户最新确认优先于 Skill 目录内的通用引导。Skill 说明不代表已完成注册、付费查询、联网验证或部署;接口草案也不代表后端已有接口。
实施过程中每日更新完成情况与实际验收记录。外部依赖未验证、工具失败或仅用模拟样例的部分必须如实标记,不能用演示动画替代真实执行证据。
# 如昼商机助手:四天开发计划
编制日期:2026-10-26(北京时间)
适用范围:[需求分析与 Skill 集成方案](./需求分析与Skill集成方案.md)中的已确认需求。
执行方式:由 AI 完成两个项目的代码、必要测试与联调;D1–D4 指开工后的四个开发日,不假定已确定具体开工日期。
## 1. 交付目标与排期前提
第四天交付一个可在指定测试环境运行的版本:预设 admin 登录;发现商机与检索方案;带真实招投标检索调用的获客报告;四类调研入口;企业情报与双公司对比;具体项目投标研判;指定格式投标文件解析;重点关注八状态;手填公司档案;历史会话;可回查的来源与实际消耗。
本次改版的主链路是:
`输入/场景卡 → 意图与参数确认 → 受控 Skill 工作流 → 真实数据 → 标准化与证据 → 结论/报告 → 用户选择深挖或跟进`
本计划按单条 AI 实施主线估算,每天约 8–10 小时的集中开发与验证,约 32–40 小时;这是排期估计,不是对外部服务可用性或固定工时完成全部需求的保证。用户无需承担开发工作,但真实服务的凭证、余额和部署环境必须可用。
| 前置条件 | 最晚验证点 | 不满足时的处理 |
| --- | --- | --- |
| MySQL 可连接、Java 21、Maven、Node/npm 可运行 | D1 前段 | 先修复环境;数据库未真实连接不能算持久化完成 |
| 知了数据 API 凭证、余额、应用使用权限可用 | D1 中段 | 保留适配开发与契约测试;暂停真实数据验收并记录阻塞,不替换为演示数据通过 |
| DeepSeek 文本、视觉和 Search/Fetch 可用 | D1 中段 | 分别记录可用项;联网和扫描件不能因文本模型可用而自动视为通过 |
| 指定格式的可解析测试样例 | D1 准备,D3–D4 验收 | 可创建无敏感信息的自测样例;真实资料不足时明确样本局限 |
| 三个 Skill 版本及关键工具参数锁定 | D1 | 使用提供的版本;实测字段差异记录在适配层,不在线悄悄升级工作流 |
本期不增加全网站爬虫、第四个 Skill、定时通知、注册、多租户、自动报名/投标、标书生成、报价自动执行、报告对外分享服务。公司档案文件导入按最新确认关闭。
## 2. 四天里程碑总览
| 日期 | 主目标 | 后端交付 | 前端交付 | 当日可演示结果 |
| --- | --- | --- | --- | --- |
| D1 | 工程与真实服务打通 | 数据迁移、admin 会话、档案/关注基础接口、统一任务骨架、数据与模型小样本验证 | API 客户端、登录、手填档案、任务状态基础组件 | 正确密码登录;档案落库;发起一条真实数据/模型任务并回查记录 |
| D2 | 招投标检索与获客闭环 | 召回分页、去重、方案快照、排序、摘要与匹配度、关注事务 | 发现商机、获客表单/报告、方案 Tab、关注八状态与标签 | 全国近 90 天真实获客;偏好不漏掉其他候选;关注后可查看变更历史 |
| D3 | 企业情报与项目研判闭环 | 同名确认、单/双企业工作流、投标快/完整模式、文件解析、公开资料补充、预算暂停 | 四个调研入口、主体选择、项目文件、真实流式轨迹、显式深挖按钮 | 从获客结果选择采购方背调,再对具体项目研判;无自动深挖 |
| D4 | 全范围验收与交付 | 格式补齐、清理/删除、恢复/错误处理、审计核对、集成验证 | 历史会话、整批提问、断线/失败/预算提示、来源和覆盖范围完善 | 完整业务演示+格式矩阵+异常用例+真实服务证据+运行说明 |
前后端每天联调,不把界面接入集中到第四天。D4 主要用于补齐和验收,不应到 D4 才首次尝试联网、视觉或文件解析。
## 3. D1:基础工程、账号与服务验证
### 3.1 前段:本地运行与数据边界
1. 检查项目实际 JDK、Maven、Node/npm 及 MySQL。当前静态检查显示后端目标 Java 21,主机另有其他 JDK,开发命令需明确使用兼容版本。
2. 补齐后端数据库访问、迁移、输入校验、安全配置及统一错误返回;明确前端代理 `/api`,不要把外部密钥放进 `VITE_*`。
3. 建立用户、公司档案、公告/批次、关注与历史、方案、会话、任务/事件、工具调用、证据、临时文件等必要表;按可独立验证的模块拆分迁移。
4. 实现预设 admin 初始化、密码哈希、登录/当前用户/退出、会话和 CSRF;初始密码从部署环境提供,配置示例只保留占位符。
5. 实现公司档案读取/保存、版本与完善状态;前端接入登录和八组表单,关闭原 AI 导入入口,停止自动加载演示公司。
### 3.2 后段:先验证真实依赖,再展开业务
1. 封装知了白名单工具客户端,正确设置各工作流的 `X-Client`;区分传输失败、业务失败、余额不足和无结果。
2. 在可用凭证下进行少量真实请求:余额、公告检索/详情、企业主体搜索及代表性画像响应;记录脱敏后的字段契约、返回时间、状态和计费字段。不要跑全量深度报告来验证一个字段。
3. 验证 DeepSeek 最新模型的真实文本请求、结构化输出、流式响应;分别验证 Search/Fetch 和一张非敏感样例图的视觉解析。记录实际返回模型标识与 token usage。
4. 实现统一任务的创建、状态查询、幂等、必要补问、实际工具调用记录、有序事件与基础 SSE。明确“计划调用”与“实际调用”不同。
5. 实现关注基础增删与关联权限;为 D2 的状态事务和标签联调准备稳定接口。
6. 前端建立统一请求和错误处理、任务事件订阅基础组件,清除对“本地 authed 即已登录”的依赖。
### 3.3 D1 验收门槛
- 错误密码不能登录,未登录不能读取档案/任务/文件;退出后会话失效。
- 保存档案后刷新页面、重启后端仍可读取;完善状态与版本由后端决定。
- 有一份脱敏的真实依赖验证记录,分别注明知了、DeepSeek 文本、联网、视觉是否通过,不能只写“API 已打通”。
- 同一幂等键重复创建不多扣一次费用;一次实际工具请求对应一条可追溯调用记录。
- 明确首版分页/调用/积分及文件保护值,写入配置与接口说明。
## 4. D2:发现商机、获客与人工跟进
### 4.1 招投标检索工作流
1. 实现统一条件对象,把基础硬条件与偏好拆开。对话默认全国/近 90 天;提供今天、近三天、近一周、近一个月、近半年、近一年和自定义范围。
2. 明确 UI 关键词组合方式,适配上游 OR/AND;地区和金额单位集中转换,校验金额非负、上下限和日期范围。
3. 拉取预算允许的分页,再对已拉取集合去重和排序;记录平台总命中数、已取数、去重数、展示数、截断原因。继续检索追加同一范围的新页,不重跑已成功页。
4. 标准化采购方、预算、公告阶段、原始来源和缺失字段;可靠编号归并公告阶段,不因标题相似而错误合并项目。
5. 区域市场复用检索和聚合工具,输出买方、供应商和时间趋势;关键词缺失时显示实际水行业关键词集合。样本统计与全库聚合明确区分。
### 4.2 获客、列表分析与检索方案
1. 新增获客输入:关键词、时效、四种推荐方式,地域/金额作为可选偏好。初始报告只执行招投标检索工作流。
2. 原检索保持发布时间顺序;获客使用版本化相关度与偏好排序,附排序原因。未知金额/地区不丢弃,换偏好不得改变基础候选集合。
3. 有正文时生成建设内容、地区、节奏、资质业绩等结构化结论;无正文时显示信息缺口。批次较大时摘要分批执行并显示进度,不能为列摘要自动执行完整投标决策。
4. 四维匹配分与权重落到后端,保留依据、完整性及档案版本;修复默认规则不能产生 90 分以上样例的问题。评分、模型失败不影响检索列表正常显示。
5. 保存/编辑/删除方案和手动执行;执行记录绑定固定条件、项目版本/必要字段及有序结果。切换 Tab 读取历史快照,不按最新条件临时重算。
6. 前端联调发现商机表格、摘要、来源、获客报告和方案 Tab;为企业情报、项目研判提供明确的深挖按钮,按钮点击前不发起深查。
### 4.3 重点关注闭环
1. 关注与取消关注、标签管理及筛选;关注唯一约束避免重复。
2. 状态/备注/历史在同一事务写入,支持八状态人工跳转、暂不考虑后恢复、备注单独编辑留痕;采用版本检查避免两次保存互相覆盖。
3. 跟进中、已有结果、暂不考虑三个页面分组统计正确;截止或 AI 结论变化不自动改状态。
4. 前端接入取消关注的既有确认交互;明确它删除关注历史但不删除公告和独立报告。
### 4.4 D2 验收门槛
- 不提供地域偏好时全国召回;选择浙江偏好后,非浙江高相关项目仍保留;金额未知项目也保留。
- 获客初始报告有实际招投标工具请求,企业情报与投标决策调用数为零。
- 普通检索的顺序不随档案/权重变更而改变;获客排序原因可解释。
- 页面能区分“平台命中 800 条、本批读取 250 条、去重 210 个”,不会宣称全量排名。
- 用标为测试的数据验证精确权重计算与高分呈现;真实结果不为验收硬造高分。
- 页面完成检索→关注→准备投标→已报名→提交→结果,并可恢复、编辑备注和回查历史;重复提交不重复记历史。
## 5. D3:企业情报、投标研判与文件
### 5.1 企业情报与双公司对比
1. 实现主体定位与候选选择;多候选停在等待确认,不因第一条记录量大就自动认定,也不自动将集团分支混入统计。
2. 实现基础画像、业务关键词、客户供应商、中标表现、竞对及公开资料补充;Top 竞对仅轻查,不递归展开。
3. 双公司对比只比较两家已经确认的主体;共同客户和交锋事实来自真实数据,行业头部不能冒充直接竞对。
4. 单/双企业分别设置调用与积分预算;追问只补查相关部分,不重新跑整份深度工作流。
5. 接入 DeepSeek Search/Fetch 补充官网、公开新闻及风险信息;每个事实保留来源。未查到公开风险不能转成“无风险”。
### 5.2 具体项目与投标决策
1. 支持知了公告链接、其他公开公告链接、完整标题或投标文件;定位歧义时让用户选项目。
2. 实现项目画像、采购方历史、潜在竞争者、历史价格参照、可选我方适配;“快速判断”与“完整研判”有明确步骤和预算差异。
3. 服务类或无品牌型号时不伪造品牌价;不同规格、总价与单价不能混合计算。没有成本和可比样本时输出缺口,不生成利润承诺或精确胜率。
4. 在获客结果中显式选择企业/项目后创建父子任务,把深度结果追加在对应对象下;首批建议 3 个、最多 5 个对象,逐个执行。
5. 报告绑定事实/推断、证据 ID、样本范围和实际调用;生成后校验引用和关键数字。
### 5.3 文件链路与真实轨迹
1. 建立仅供投标项目的上传、类型检测、权限、解析、过期及删除流程;文件先归属当前用户,绑定指定项目任务后不能串用到其他用途。
2. 接入成熟库提取文本、Office、表格、幻灯片和文字 PDF;按页/工作表/幻灯片保留证据定位。首日选型,D3 先跑完全部格式的代表性样例,D4 修复边界。
3. 扫描页渲染后使用 DeepSeek 视觉解析;混合 PDF 按页决定路径。限制大小、页数和视觉页数,超限提示拆分而不是静默截断。
4. 前端新增第四个“评估投标项目”入口,四入口均复用统一任务组件;展示必要补问、主体选择、预算暂停、工具动作与报告片段。
5. 删除 `runSkillTrace` 的伪造执行用途;后台未实际发请求时不能出现“已调用”。可展示加载动画,但文案必须对应真实状态。
### 5.4 D3 验收门槛
- 输入同名企业时可以选主体;未选之前没有发生后续企业深查扣费。
- 单公司、双公司、区域市场、项目评估四个入口均有真实完整链路;正常输入两步内能发起任务。
- “了解采购方”仅执行企业情报工作流;“深入研判”仅执行项目决策工作流,内部工具调用照实计入,不冒充另一 Skill 被调用。
- 至少完成标题、公开链接、投标文件三条项目输入路径;站内未核实时如实说明资料来自用户文件。
- 一次预算暂停可确认继续,取消后不再发出后续工具请求;已发生的费用不因取消而清零。
- 页面流式事件与后台调用记录可逐条核对,报告不展示私有推理链。
## 6. D4:完整验收、异常恢复与交付
### 6.1 功能补齐与边界验证
1. 完成会话新建、搜索、自动标题、重命名、删除,以及原单项目/整批 AI 提问;整批始终绑定检索快照,不只读当前页。
2. 补齐格式矩阵的全部代表性样例、扫描/混合页、中文文本、表格以及错误文件。原公司档案导入入口不得残留可用路径。
3. 实现原件/临时图片/提取全文过期清理、手动删除及必要删除审计;删除原件与报告摘录的范围分别提示。
4. 联调 SSE 断线重连、幂等、重复点击、取消、服务重启后的中断状态;重连不能重新触发收费调用。
5. 核对任务报告中的筛选条件、日期、范围、来源、事实/推断、工具调用、积分和模型 token。缓存读取不得显示为新一次调用。
6. 覆盖无结果、字段缺失、认证失败、余额不足、限流、超时、部分成功、外部网页不可达;每种情况提供调整条件、补充信息、重试或查看已有结果的下一步。
### 6.2 联调演示脚本
1. 使用 admin 登录,手动填写公司档案,调整四维权重并刷新验证。
2. 选择智慧水务关键词,使用全国/近 90 天生成获客报告,查看真实调用、条件、覆盖范围、来源和成本。
3. 切换地域/业务/金额偏好,对比同一候选集的顺序,检查未知预算保留。
4. 保存并执行检索方案;切换历史 Tab,验证固定条件和结果快照。
5. 选择一个采购方做企业情报,遇到多候选则确认;再发起双公司对比。
6. 对一个项目分别使用快速判断和完整研判;切换标题/链接/文件三种输入方式,检查证据定位。
7. 加入重点关注、打标签、经历八状态中的代表路径,查看备注与历史;AI 不改变状态。
8. 断线恢复和重复提交,证明不会重复发起同一收费请求;模拟额度不足、无结果和服务失败。
9. 新建、重命名、搜索、删除历史会话;删除投标原文件,验证清理与审计,不混淆报告摘录。
真实业务演示与可重复异常测试分开记录。固定测试样例可验证边界,但不能代替真实数据与模型联调。
### 6.3 交付物
- 两个仓库中的实现代码、数据库迁移和必要测试;按用户要求补充详细中文业务注释。
- 后端运行文档、前端运行文档、环境变量示例;示例不得包含真实密钥和固定弱密码。
- 接口契约说明,明确分页、事件、幂等、错误、金额/日期单位与任务确认流程。
- 三个 Skill 版本、实际工具映射、真实 API 差异与预算设置记录。
- 格式验收矩阵、异常用例结果、真实接口联调记录和未完成项清单。
- 前端构建产物或明确构建方式、数据库初始化方式及测试环境启动步骤;不把原免构建 HTML 演示页视为后端交付。
## 7. 计划中的接口契约
以下接口是待实现设计,不代表当前后端已经存在。统一前缀 `/api`,所有业务资源按当前账号鉴权,状态改变请求需匹配会话和 CSRF 策略。
| 模块 | 接口建议 | 关键行为 |
| --- | --- | --- |
| 登录 | `POST /auth/login`、`GET /auth/me`、`POST /auth/logout` | admin 验证、恢复会话、会话失效 |
| 档案 | `GET/PUT /company-profile` | 八组字段、完整性、版本、四维权重;不提供文件导入 |
| 公告检索 | `POST /searches`、`GET /searches/{id}`、`GET /searches/{id}/items` | 真实执行、查询快照、稳定分页,区分总命中与读取范围 |
| 继续召回 | `POST /searches/{id}/continue` | 在预算与相同基础条件下追加新页,幂等,不盲目重复已成功页 |
| 公告 | `GET /projects/{id}` | 返回来源、阶段和已取得的结构化内容 |
| 手动项目 | `POST /projects/import` | URL 或已上传投标文件二选一,解析预览;用户确认后关注 |
| 检索方案 | `GET/POST /search-schemes`、`PUT/DELETE /search-schemes/{id}`、`POST /search-schemes/{id}/runs` | CRUD 和手动执行,执行结果绑定批次 |
| 关注 | `GET /watch`、`POST/DELETE /watch/{projectId}` | 分组与筛选;取消关注沿用确认语义 |
| 状态历史 | `POST /watch/{projectId}/changes`、`GET /watch/{projectId}/history` | 状态/备注/版本/幂等键,原子写入 |
| 标签 | `GET/POST /tags`、`DELETE /tags/{id}`、`PUT /watch/{projectId}/tags` | 标签唯一、删除解绑、按账号隔离 |
| 会话 | `GET/POST /conversations`、`PATCH/DELETE /conversations/{id}`、`GET /conversations/{id}/messages` | 搜索、标题、消息与任务历史 |
| Agent 任务 | `POST /agent/tasks`、`GET /agent/tasks/{id}` | 场景卡/自然语言统一创建,含意图、硬条件、偏好和父任务 |
| 确认/取消 | `POST /agent/tasks/{id}/continue`、`POST /agent/tasks/{id}/cancel` | 主体/参数/预算确认,显式选择、幂等、合法状态校验 |
| 轨迹/报告 | `GET /agent/tasks/{id}/events`、`GET /agent/tasks/{id}/report` | SSE/重放、结构化结果、Markdown、证据与实际费用 |
| 文件 | `POST /files`、`GET/DELETE /files/{id}` | 仅投标用途,类型/大小/归属/过期,删除覆盖临时派生物 |
| 用量 | `GET /usage` | 本地任务账本和平台余额分别标注,明确统计范围与未知费用 |
任务状态、事件和核心对象在 D1 先出最小契约,前端按此接入;D2–D3 的新增字段向后兼容。前端不得直接调用知了或 DeepSeek,也不在前端重新计算权威分数和成本。
## 8. 验收矩阵
所有行均属于本期目标;“未验证”或“失败”不可在交付时改写为“通过”。
| 编号 | 验收项 | 判定证据 |
| --- | --- | --- |
| A01 | 预设 admin 的真实鉴权与退出 | 正误密码、未登录资源访问、退出后失效记录 |
| A02 | 原功能保留与持久化 | 页面刷新/服务重启后档案、关注、方案、会话仍在 |
| A03 | 四调研入口两步发起 | 客户、竞对、区域、项目的界面操作记录;歧义按规则补问 |
| A04 | 获客必调招投标检索 | 新任务存在真实外部请求、响应记录和对应报告 |
| A05 | 初始报告不隐式深挖 | 企业情报/投标决策工作流启动次数为零 |
| A06 | 偏好不误作过滤 | 固定候选数据下地域/金额偏好变化前后集合一致,未知字段仍在 |
| A07 | 两场景排序分开 | 原检索时间倒序;获客排序有依据;匹配分不重排原列表 |
| A08 | 分页与“找全”边界 | 总命中/已读取/去重/截断提示准确,统一排序覆盖已读全部分页 |
| A09 | 主体确认与上下文冲突 | 同名候选可选,确认前无深查;新旧条件冲突可选择 |
| A10 | 双企业对比与项目研判 | 真实来源数据、对比口径、项目结论/风险/缺口与事实对应 |
| A11 | 轨迹真实且不泄露私有推理 | 每条实际动作对应后台记录;无预设假调用、密钥或私有推理链 |
| A12 | 来源与事实/推断分层 | 引用能定位工具记录/文件页;模型未知链接被拒绝或标缺口 |
| A13 | 成本与预算 | 次数/积分/token 分账,实际扣费字段保留,超预算能暂停继续 |
| A14 | 八状态与历史 | 状态/备注同事务、人工跳转/恢复、重复提交和冲突保存用例 |
| A15 | 全格式与损坏文件 | TXT、MD、CSV、HTML、DOC、DOCX、XLS、XLSX、PPT、PPTX、文字/扫描/混合 PDF、JPG、PNG、WebP、GIF 各有样例与结果 |
| A16 | 文件用途、清理与删除 | 档案导入关闭;文件不能跨任务使用;到期、手动删除及派生文件清理记录 |
| A17 | 无结果/缺数/失败 | 页面有数据边界、已有结果和可执行下一步,无空白或虚构回答 |
| A18 | 幂等、重连、取消与重启 | 重放不二次收费,取消停止后续步骤,重启中断任务不显示成功 |
| A19 | 会话与检索快照 | 搜索/重命名/删除、旧条件回查、整批问答覆盖实际批次 |
| A20 | 匹配分正确性 | 非法权重拒绝、只舍入一次、档案版本可查、高分测试样例明确标为测试 |
## 9. 验证命令与测试分层
后端先执行与当前修改相关的单元/集成测试,再完成 Maven 的 `test`/`verify`;前端完成 `npm run build`,并检查本次改动相关的 lint。实际命令与版本在实施时记录,不把命令列在文档里等同于已运行。
重点自动化覆盖:条件与偏好分离、关键词映射、金额转换、日期边界、分页去重与阶段归并、权重计算、同名等待、幂等计费、状态/备注事务、引用校验、权限和文件清理。外部接口使用记录过的脱敏样例做契约测试,另用受控的真实请求验证集成。
界面验收从浏览器执行完整业务链路,至少检查加载、空态、错误、暂停、取消和报告引用。只通过编译不能证明 Agent 路由、真实数据、视觉解析或跟进闭环已经正确。
## 10. 风险、缓冲与变更规则
| 风险 | 对排期的影响 | 处理方式 |
| --- | --- | --- |
| 第三方接口字段/价格与 Skill 文档不一致 | 适配和成本计算返工 | D1 小样本锁定契约;预计成本标来源版本,实际成本读响应 |
| 全国近 90 天命中很多 | 召回耗时、额度和排序覆盖扩大 | 有界分页、继续检索、明确本批覆盖;不能靠静默漏页“优化” |
| Office 老格式、混合 PDF、扫描件质量差 | 文件集成与验收工时增加 | D1 验证视觉,D3 跑全部格式代表样例;D4 只修边界,无法识别明确失败 |
| 同步深查多个企业/项目 | 额度和执行时间快速增长 | 初始报告不深查;用户选择后串行,建议 3 个、最多 5 个 |
| 全范围功能集中四天 | 稳定性缓冲较少 | 每日门槛必须真实通过;D4 留出回归,不新增第四个 Skill 或生产运维范围 |
| 凭证/余额/网络不可用 | 无法完成真实联调验收 | 记录阻塞与恢复条件;独立开发继续,不用模拟成功掩盖未完成 |
若 D1–D3 门槛未通过,先修复主链路,再按实际剩余工时重排。不能擅自把已确认的文件格式、八状态、双公司对比或真实调用删除;需要缩小范围时提交具体未完成项、原因及替代排期,由用户决定。四天结束时逐项报告“通过/失败/未验证”,真实服务验收未通过则不宣称全部交付。
# 四天计划完成度核查
核查日期:2026-10-29(北京时间)。范围:`rz-GB`、相邻 `rz-GB-web`、四天开发计划、需求分析和 D1–D4 验收记录。本轮只新增核查报告,未修改业务代码、配置或数据库,未使用真实供应商密钥。
## 结论
四天计划的主要业务已有实现,本地自动测试和构建通过;**不能判定四天计划全部验收完成,也不能判定现在能直接运行完整真实业务**。当前最先需要解决的是数据库及首次管理员配置,再完成知了、DeepSeek 和指定环境的真实联调。另有若干功能与原计划存在差距,不能统一归因为“只差 API Key”。
“已实现”表示代码和本地测试证据存在;“真实待验收”表示尚未证明真实数据库、供应商响应、模型质量及实际部署满足要求。没有用文档中的完成声明替代本次代码检查和测试。
## 四天逐项核对
| 计划 | 本轮确认存在的实现 | 尚未完成的验收或功能 |
| --- | --- | --- |
| D1:基础工程和真实依赖 | Java 21 工程、Flyway V1–V7、admin 初始化、会话/CSRF、手填档案及版本、统一任务、幂等、事件/SSE、工具白名单和调用账本 | MySQL 初始化与重启持久化;真实知了余额/检索/详情/企业字段;真实模型文本/JSON/流、Search/Fetch、视觉及实际计费记录 |
| D2:检索、获客和跟进 | 分页与去重、硬条件/偏好分离、普通检索与获客两种排序、范围统计、规则摘录与四维匹配、方案快照、关注八状态、标签/备注/历史事务及版本 | 真实数据字段、金额单位、分页总数、召回效果及积分核对;真实网页从检索到跟进的完整演示 |
| D3:企业、项目和文件 | 四入口、主体选择、单/双企业、采购方历史、项目快/完整模式、来源与引用检查、局部补查、文件解析/视觉调用、预算暂停、父子任务 | 同名真实企业和双公司报告核验;真实标题/链接/文件三路研判;真实扫描件/复杂标书质量;自然语言任务路由尚缺 |
| D4:恢复和交付 | 历史会话 CRUD、固定快照单项目/整批问答、到期/手动文件清理、删除审计、取消/重启中断、SSE 重放、用量读取、代表性格式和异常测试、运行文档 | 指定环境 MySQL/SSE 代理与重启验收;供应商真实账单;真实文件矩阵;超大问答分段汇总、审计保留期执行和文档一致性仍有差距 |
列表摘要目前是已有正文的规则摘录,并非逐公告模型总结;代码和界面已说明这一口径。无正文会提示缺口。这不应被宣传为读完标书后的完整 AI 研判。
## 直接影响启动和真实业务的缺项
### 1. 数据库和首次管理员配置
本轮检查时,后端目录只有 `.env.example`,没有 `.env`;当前工具进程未设置 `DB_URL`、`DB_USERNAME`、`DB_PASSWORD`、`ADMIN_INITIAL_PASSWORD`、`ZLBX_API_KEY`、`DEEPSEEK_API_KEY`。未读取其他项目的凭证,也没有据此断言用户的其他主机或 IDE 不存在配置。
本机 3306、8240、3000 未观察到监听进程;这只描述本轮检查时的本机状态,不排除远端数据库或非默认端口。
要先运行登录、档案和本地业务接口,需要:
1. 可连接的 MySQL 8 数据库,建议空库 `rz_gb`、字符集 `utf8mb4`。
2. 应用账号具有该库迁移建表、索引和读写权限。
3. 配置数据库三项变量;首次设置管理员密码,至少 12 字符、UTF-8 最多 72 字节。
4. 显式导出环境变量再启动;Spring Boot 不会自动读取 `.env`。
5. 实际执行 Flyway V1–V7,登录并保存档案,重启后再次读取,证明 MySQL 持久化有效。
证据:[application.yaml](../src/main/resources/application.yaml:14)、[SecurityConfig.java](../src/main/java/com/example/rzgb/auth/SecurityConfig.java:34)、[运行说明](../README.md)。本机已具备 Java 21、Maven、Node/npm,不需要把这些再次列为未安装的软件。
### 2. 知了与 DeepSeek 真实服务
完整检索、获客、企业情报、联网研究、模型问答和扫描件解析,还需要后端 `ZLBX_API_KEY`、`DEEPSEEK_API_KEY`,并确认账户余额、接口使用权限和部署主机网络可达。
不能只补密钥就宣布完成。必须用少量请求核对真实响应与当前适配契约:`data.items`、企业/聚合字段、`meta.cost_units`、实际模型标识、token usage;然后再跑完整工作流。如果字段不同,需要修改适配与对应测试。
本轮查阅的知了官方 API 概述与 DeepSeek Search/Fetch、视觉文档支持代码采用的基础路径、认证方式及能力方向,未发现足以直接判定这些能力不存在的依据;但这不能证明当前账号权限、具体工具参数或真实效果已经通过。
- [知了官方 API 概述](https://ai.zhiliaobiaoxun.com/docs/api)
- [DeepSeek Search](https://api-docs.deepseek.com/api/search/)
- [DeepSeek Fetch](https://api-docs.deepseek.com/api/fetch/)
- [DeepSeek Vision](https://api-docs.deepseek.com/guides/vision/)
### 3. 指定环境的启动和代理
本地开发需实际启动后端 8240 和前端 3000。部署构建产物时需配置静态站点、路由回退及同源 `/api` 反向代理;SSE 关闭代理缓冲并允许长连接。HTTPS 部署启用安全会话 Cookie。
当前按单实例设计运行,内存登录会话在重启后失效,需要重新登录;这与业务数据是否持久化是两回事。多实例调度和生产高可用不在本期,不是本地单实例启动的前置条件。
操作见 [接口契约与运行交付](接口契约与运行交付.md)。
## 除环境以外,确认存在的计划差距
| 项目 | 原计划/需求 | 当前实现与影响 | 建议 |
| --- | --- | --- | --- |
| 自然语言统一任务入口 | 自然语言与场景表单统一进入意图、参数确认和工作流 | 前端根据所选场景直接指定 operation/workflow;后端接收显式类型,没有自然语言意图解析及条件提取。输入完整企业名/标题可用,但一句“找浙江近三个月的水务项目”不会自动转成对应查询 | 若保留原需求,补意图路由、结构化参数预览/确认和歧义补问;在此之前明确只支持场景表单 |
| 超大整批问答 | 超上下文时分段汇总并展示覆盖范围 | 已冻结全部候选,但超过 600,000 字符时返回 `QA_CONTEXT_LIMIT`,要求改单项目;没有分段汇总。普通大小批次仍可用 | 增加分段与最终汇总,保留各段覆盖对象、引用及费用;或明确收窄需求 |
| 手动导入项目后关注 | 计划草案含 URL/投标文件解析预览,确认后关注 | 已有标题/URL/文件研判入口,但没有独立 `/projects/import` 及手动导入后进入关注的完整链路;关注依赖已经存在的 project。交付文档承认未提供该接口 | API 名称可以调整,但若保留该业务需求,需补解析预览、确认落库及关注闭环 |
| 审计数据保留期 | 需求建议审计元数据 180 天,可配置 | `auditRetentionDays` 可配置且对外显示,但代码未消费该值执行归档/删除;原件/全文/派生图片清理已实现。不能把“配置为 180 天”理解为届时自动清理 | 明确保留范围和引用关系后补归档/清理,或说明目前长期保留 |
| 文档及检查收尾 | 交付说明应与最终功能一致 | 前端 README 开头仍说 D3 是原型、按钮不发深查,末尾又描述 D3/D4 已接入;全量 lint 也未通过 | 更新过期说明,处理遗留 lint;不阻塞已通过的构建,但不能称全部工程检查通过 |
定位:[ResearchPage.tsx](/Users/ruzhoukeji/rz-GB-web/src/pages/ResearchPage.tsx:70)、[TaskRequest.java](../src/main/java/com/example/rzgb/task/TaskRequest.java:10)、[SnapshotQa.java](../src/main/java/com/example/rzgb/conversation/SnapshotQa.java:58)、[文件清理](../src/main/java/com/example/rzgb/files/BidFileService.java:76)、[AppProperties.java](../src/main/java/com/example/rzgb/config/AppProperties.java:18)。
已额外确认:深挖串行控制不是缺项。`TaskService.validateParent` 已在父任务锁内检查同批最多五个子任务、已有未结束子任务则拒绝新建。前端当前逐个进入对象,没有批量勾选界面;本轮不把批量界面当作串行能力缺失。
## 本轮实际执行的检查
| 检查 | 2026-10-29 本轮结果 |
| --- | --- |
| Java 21,`mvn -o -q -Djava.awt.headless=true verify` | 通过;102 项,0 失败、0 错误、0 跳过;后端 JAR 存在 |
| 后端测试范围 | 基础 29、排序 5、摘录匹配 5、研究工作流 17、文件解析 30、D4 集成 16 |
| `npm run build` | TypeScript 与 Vite 通过,生成 dist;主 JS 554.06 kB,存在大于 500 kB 的体积提示 |
| `npm run lint` | 未通过,8 个错误,集中在既有 UI 组件导出规则及 sidebar 渲染期间 Math.random |
| 两仓库 `git diff --check` | 通过;没有因此修改或清理已有未提交代码 |
| 当前配置与默认端口 | 当前进程缺上述数据库和供应商变量;后端无 .env;默认端口未见监听 |
| MySQL、真实供应商、真实标书和部署代理 | 未执行,不记为通过 |
| 浏览器完整业务演示 | 本轮未重跑;D3/D4 文档保留的是此前 H2 + 本机模拟 HTTP 的浏览器记录 |
首次后端测试因沙箱不允许监听本机临时 HTTP 端口而失败;允许测试在沙箱外使用本机端口后,同一命令全部通过。测试使用 H2 和本地模拟服务,没有外部收费请求。日志:`/tmp/rzgb-review-maven-approved.log`、`/tmp/rzgb-review-web-build.log`、`/tmp/rzgb-review-web-lint.log`。
## 建议执行顺序与通过标准
1. **先让基础服务启动**:配置 MySQL/管理员、运行迁移,验证健康检查、登录、档案读写及重启持久化。
2. **再验证真实依赖**:少量核对余额、公告检索/详情、企业搜索/画像、文本/JSON/流、Search/Fetch、视觉;对照响应修正适配。
3. **跑完整业务闭环**:检索→获客→关注状态/标签→企业及双公司→项目快/完整研判→标题/URL/真实文件→会话与整批提问,核对来源和账单。
4. **补齐保留的计划差距**:自然语言、超大问答分段、手动项目关注、审计保留期;更新交付文档和 lint。
5. **指定环境验收**:代理下 SSE 断线恢复、重复提交、预算暂停/取消、进程重启、原件过期/删除与复杂真实文件。每项有脱敏证据后再更新 A01–A20 的真实验收列。
当前可以确认“核心代码和本地回归具备”,不能确认“真实业务已经正常运行”或“四天计划 100% 完成”。
# 接口契约与运行交付
适用版本:D1–D4;更新时间 2026-10-28(北京时间)。实际本地结果见 [D4 实施与验收](D4实施与验收.md)。
## 1. 测试环境启动
后端 Java 21、Maven 3.9+、MySQL 8;前端使用带锁文件的 npm 安装。本轮验证 Node 23.11.1 / npm 10.9.2,部署可使用满足 Vite 引擎约束的团队 Node 版本。
1. 新建空的 `rz_gb` MySQL 数据库,字符集 utf8mb4。账号需具备本库迁移与业务读写权限;不要复用其他项目数据库。Flyway 首次自动执行 V1–V7,升级环境只执行未运行的版本。
2. 数据库和 `rz.admin-password` 直接配置在 `src/main/resources/application.yaml`,构建后随 JAR 加载,不再自动读取根目录的 `application-local.yaml`。切换部署环境前核对数据库地址和账号,修改后重新打包。初始密码不限制最小长度,但不能为空,UTF-8 不超过 BCrypt 的 72 字节上限。既有 admin 不会因重启被重置。
3. 除 `ZLBX_API_KEY`、`DEEPSEEK_API_KEY` 外,参数均直接在 YAML 中维护。API Key 在启动终端或 IDE 环境变量中设置。从后端根目录运行,无需加载 `.env`:
```sh
export JAVA_HOME=$(/usr/libexec/java_home -v 21)
mvn spring-boot:run
```
默认后端端口 8240;`GET /actuator/health` 检查就绪。主机默认 Java 8 时必须先指定 Java 21。本轮用已安装 Maven;Wrapper 的独立 Maven 发行包需要可下载且可写缓存。
```sh
cd ../rz-GB-web
npm ci
npm run dev
```
前端默认 3000,通过同源 `/api` 代理到 8240。开发时可用 `API_PROXY_TARGET=http://127.0.0.1:8244 npm run dev -- --port 3004` 指向独立本地后端;此变量仅被 Vite 服务端读取,不是浏览器密钥配置。
真实供应商未配置时,任务等待配置或输入,不返回演示数据。不向前端 `VITE_*` 放 API Key。
## 2. 构建、初始化与代理
```sh
# 后端目录
export JAVA_HOME=$(/usr/libexec/java_home -v 21)
mvn -Djava.awt.headless=true verify
java -Djava.awt.headless=true -jar target/rz-GB-0.0.1-SNAPSHOT.jar
# 前端目录
npm ci
npm run build
```
后端运行 JAR 时,直接使用包内的数据库和管理员初始化配置,并通过进程环境提供两个 API Key。主 YAML 和 JAR 均包含凭证,应限制访问;生产 JAR 不包含 H2、测试口令或模拟服务。若需覆盖包内配置,可填写 `application-local.example.yaml` 并通过 `--spring.config.additional-location=file:/绝对路径/application-local.yaml` 显式加载。前端交付目录是 `dist/`,部署到静态服务,路由回退到 `index.html`;不能用旧 HTML 原型代替后端。
通过同一域名提供前端和 `/api`,HTTPS 下将主 YAML 的 `server.servlet.session.cookie.secure` 改为 `true`。反向代理需关闭 SSE 响应缓冲并允许长连接,例如:
```nginx
location /api/ {
proxy_pass http://127.0.0.1:8240;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_buffering off;
proxy_read_timeout 180s;
}
```
本期任务执行和会话是单实例;重启需重新登录。数据库中的任务、会话、文件和业务数据保留。重启恢复只标记中断,不重发收费请求;不要把多个实例同时连到同库当作已支持的并行调度。
## 3. 通用请求契约
- 前缀 `/api`。除登录与 CSRF 引导外均需真实会话;Cookie 为 HttpOnly。所有改变状态的请求必须带 `/auth/csrf` 返回的 headerName/token;登录后 CSRF 轮换,客户端重新读取。
- 任务创建、继续、方案执行、关注变更使用 `Idempotency-Key`。8–128 位,允许字母、数字及 `._:-`。相同作用域同键同内容回查;同键不同内容 409。创建键按账号隔离;继续键按任务隔离;客户端不自动重试写请求。
- 通用错误 JSON:`{"code":"稳定错误码","message":"脱敏中文说明"}`。401 重新登录;403 刷新 CSRF 后由用户重试;409 刷新版本/检查范围;413 拆分;429 稍后显式重试;502/503/504 查看已有结果与未知费用。原始 SQL、请求密钥和私有模型推理不会返回浏览器。
- 检索日期为北京时间自然日的 `YYYY-MM-DD`,首尾包含;持久化创建时间 API 返回时间戳/ISO 时间,前端按北京时间展示。检索条件不得偷偷替换成当前日期。
- 浏览器金额字段统一为万元(`*Wan`),上游元/万元适配在后端集中转换。未知金额保持 null;负数、上下限倒置及非法权重拒绝。
- 原检索按发布时间排序;获客偏好只改顺序。返回平台总命中/已读/去重/展示/停止原因,均不等于全库保证。
## 4. 现有业务接口
| 模块 | 接口及关键行为 |
| --- | --- |
| 登录 | GET `/auth/csrf`,POST `/auth/login`(表单 username/password),GET `/auth/me`,POST `/auth/logout` |
| 公司档案 | GET/PUT `/company-profile`;版本检查、八组表单、四维权重;没有档案导入接口 |
| 检索 | POST/GET `/searches`,GET `/searches/{id}`、`/{id}/items?page=1&size=20`;size 1–50,只读固定快照 |
| 继续/偏好 | POST `/searches/{id}/continue` 继续未成功页,POST `/{id}/view` 只重排原候选,普通检索拒绝偏好改序 |
| 方案 | GET/POST `/search-schemes`,PUT/DELETE `/{id}`,POST/GET `/{id}/runs`;编辑需版本,手动执行锁定条件及方案版本 |
| 公告 | GET `/projects/{id}`,只允许当前账号曾取得或关注的公告 |
| 关注 | GET `/watch`,POST/DELETE `/watch/{projectId}`,POST `/watch/{projectId}/changes`,GET `/watch/{projectId}/history` |
| 标签 | GET/POST `/tags`,DELETE `/tags/{id}`,PUT `/watch/{projectId}/tags`;按账号隔离、版本和幂等事务 |
| 任务 | POST/GET `/agent/tasks`,GET `/{id}` 或 `/{id}/report`,POST `/{id}/continue`、`/{id}/cancel` |
| 文件 | POST `/files`(multipart purpose=BID_PROJECT、file),GET/DELETE `/files/{id}`;只读本人文件、首次绑定不可转移 |
| 用量 | GET `/usage` 汇总本地账本;GET `/system/limits` 读取保护值;均不主动调用外部余额接口 |
各业务完整请求例子沿用 [D1](D1实施与验收.md)、[D2](D2实施与验收.md)、[D3](D3实施与验收.md)。旧 `/projects/import` 是计划草案,当前项目研判入口通过任务标题/URL/文件输入实现,没有单独的手动公告导入接口。
### 事件和恢复
`GET /agent/tasks/{id}/events?after=0` 返回 SSE;`Last-Event-ID` 优先于 after。游标必须为非负整数,ID 全局递增,同任务按 ID 有序;事件不是连续自然数。`event-history?after=...` 每次最多读 100 条,按最后 ID 继续。
SSE 发送 `task-event`(id/type/payload)及 `idle`(终态/等待);终态刚好与读取并发时继续追完最后事件。浏览器只展示已保存的动作,不公开私有推理。重连、GET 报告和历史均不创建任务。
状态包括 RECEIVED、PLANNING、RUNNING、WAITING_INPUT、WAITING_ENTITY、WAITING_BUDGET、SUCCEEDED、PARTIAL、FAILED、CANCELLED。只有 WAITING_* 可继续。已定位的公司、文件、项目、模式、父任务和范围不可变;问答问题也不可换。失败/重启中断需核对账单后显式新建,不自动恢复收费动作。
### 历史会话与问答
| 接口 | 请求/响应重点 |
| --- | --- |
| POST `/conversations` | `{"title":""}` 新建;空标题由首个问题自动生成 |
| GET `/conversations?q=&offset=0` | 按标题/用户问题字面搜索,每次最多 50 条,offset 继续;不解释 `%`、`_` 为通配符 |
| GET `/conversations/{id}` | 标题、version、创建/更新时间 |
| PATCH `/conversations/{id}` | `{"title":"新标题","version":2}`;冲突返回 409 |
| DELETE `/conversations/{id}` | 清除目录与消息;保留独立报告/费用/原件,响应说明范围 |
| GET `/conversations/{id}/messages` | 用户问题和 task_id;助手内容保存在独立任务报告,不复制成第二份可漂移答案 |
| POST `/conversations/{id}/tasks` | `{"taskId":"已有本人任务ID"}`,只关联已有任务,不收费;重复关联同会话无副作用 |
| POST `/conversations/{id}/messages` | 问题及 scope,带 Idempotency-Key;原子写消息、标题、任务后才调度模型 |
```json
{
"question": "这批项目哪些信息尚未披露?",
"scope": { "batchId": "检索任务ID", "projectId": null }
}
```
整批只填 batchId;单项目可以同时填 batchId/projectId,或只填 projectId 使用本人最近取得该项目的快照。所有范围均在服务端鉴权。执行中的检索拒绝冻结,需等待完成或暂停;无候选、跨账号或无证据拒绝并提供下一步。
问答任务 operation=`SNAPSHOT_QA`,workflow=`TENDER_SEARCH`,保留该工作流版本来源,**不代表重新调用了 tender-search**。调用账本明确为一次 DeepSeek 模型请求;请求只使用已读数据,零知了深查。模型选择由后端配置,客户端不能指定工具地址或系统提示词。
单次问答正文摘录 1000 字/公告、全部上下文 600,000 字符;长期文件证据摘录 2000 字/段。超过上下文限制拒绝,不只分析当前页。模型回答校验并不证明来源事实真实,也不保证自然语言语义完全正确,需根据原始来源人工复核。
## 5. 三个 Skill 版本与实际工具映射
| 工作流 | 锁定版本 / X-Client | 实际白名单工具 |
| --- | --- | --- |
| tender-search | 2.3.0 / zlbx-bidding/2.3.0 | search_bids、query_bids_advanced;区域聚合 get_top_purchasers、get_top_suppliers、aggregate_bids_advanced |
| company-intel | 1.0.2 / company-intel/1.0.2 | search_company、get_company_profile、get_company_business_keywords、get_company_partners、query_bids_advanced、aggregate_bids_advanced、find_competitors |
| bid-decision | 1.0.4 / bid-decision/1.0.4 | search_bids、get_bid_detail、search_company、get_company_profile、get_company_partners、find_potential_bidders、get_price_trends、query_bids_advanced |
公开资料由后端固定的 DeepSeek Search/Fetch 端点补充;模型、视觉与问答共用后端模型配置。版本代表已锁定的本地编排映射,不是三个外部 Skill 服务。只在实际 HTTP 开始时记外部调用;LOCAL / ENTITY_CACHE、FILE_PARSE 单列,不记外部扣费。
本轮未取得真实供应商字段差异与计费合同,仍按现有适配契约使用 data.items、企业/聚合字段、meta.cost_units、模型 usage。真实响应不符合时失败并报告契约错误,不能把测试样例当实测差异记录。实际模型 ID 从响应保存,配置名不冒充实际模型标识。
预算默认外部调用最多 25、知了积分 100;单企业最多 18。未知费用不得视为零,后续暂停确认;未知单价首个请求可能超过保护值。DeepSeek token 与知了积分不相加。默认文件 24 小时到期,每分钟清理;审计保留策略的自动归档/删除尚未实现,不会自动清除收费证据。
## 6. 真实验收接续
提供专用测试数据库与供应商凭证、余额和代表性真实标书后,按四天计划 6.2 逐步演示。先少量验证余额、检索、详情、文本、JSON、真实流、Search/Fetch 和视觉,再跑完整企业/项目路径;记录脱敏请求/响应状态、实际模型、调用 ID、日期范围、来源、积分和 token。
在这些证据齐备前,[D4 验收账](D4实施与验收.md)中的“真实未验证”保留原状态。当前不包含生产部署、生产多实例验证或全量复杂标书识别承诺。
# 如昼商机助手:需求分析与 Skill 集成方案
编制日期:2026-10-26(北京时间)
文档状态:基于本轮已确认范围的开发基线;尚未实现或通过真实接口验收。
配套排期:[四天开发计划](./四天开发计划.md)。
## 1. 已确认的产品与交付范围
产品面向水行业销售、BD、商务及售前人员,以一个主 Agent 编排三个专用 Skill,完成商机发现、企业调研、项目研判和人工跟进。它提供带证据的辅助判断,最终参与、报价、合作及合规决策由用户作出。
| 项目 | 已确认口径 |
| --- | --- |
| 交付 | 由 AI 编写后端与前端代码,完成联调;本次任务先交付需求与四天计划 |
| 项目 | `rz-GB` 为后端;相邻的 `rz-GB-web` 为前端 |
| 数据源 | 本期以三个 Skill 共用的知了标讯 API 为主,不自建各公告网站的全网爬虫 |
| 飞书来源清单 | 用户稍后补充,作为后续扩展资料;不作为本期主链路的前置条件 |
| 模型 | 接入 DeepSeek 当前最新可用模型;模型名、地址及凭证通过后端配置管理 |
| 调研 | 查询真实招中标数据,并按 Skill 工作流补充公开互联网资料 |
| 账号 | 预设一个 `admin` 账号,不做注册、组织成员和多租户管理 |
| 原有功能 | 保留发现商机、检索方案、列表匹配度、标签、重点关注八状态、公司档案、历史会话 |
| 新增功能 | 四个“我要调研”入口;“我要获客”四种推荐方式;统一任务、真实调用轨迹、证据与成本审计 |
| 两种排序 | 原检索列表按发布时间顺序展示,匹配度不参与重排;获客报告允许相关度与偏好排序 |
| 文件用途 | 最新确认:本期仅允许投标项目文件,公司档案手动填写;原公司档案 AI 导入入口移除或隐藏 |
| 文件类型 | TXT/MD、PDF(含扫描件)、DOC/DOCX、XLS/XLSX/CSV、PPT/PPTX、HTML、JPG/PNG/WebP/GIF |
“全网”描述数据平台的检索来源,不构成对全部公开公告、全部地区或实时完整性的承诺。“未查到”必须写明查询范围,不能写成“没有”。
## 2. 现有项目与需求差距
以下为静态代码核对结果,不代表运行测试结果。
| 位置 | 当前实现 | 本期需要补齐 |
| --- | --- | --- |
| 后端 `pom.xml`、`src/main` | Java 21、Spring Boot 4.1.2、Web MVC、MySQL 驱动;仅启动类和应用名配置 | 持久化、鉴权、业务接口、Skill 工作流、模型与联网调用、任务执行、文件解析 |
| 前端 `src/App.tsx`、`LoginPage.tsx` | 任意非空账号密码,本地布尔登录态 | 服务端验证 admin、会话恢复和退出 |
| `src/lib/store.tsx` | 项目检索、关注、档案、方案、会话均使用内置数据和 localStorage | 改为后端权威数据;浏览器仅保存必要界面偏好,不自动上传旧演示数据 |
| `DiscoverPage.tsx` | 默认近 30 天;档案完善后按匹配度排序;本地每页 8 条 | 原检索移除匹配度重排;增加独立获客入口,默认全国、近 90 天;后端分页 |
| `ResearchPage.tsx` | 客户、竞对、区域三个入口;模板回答 | 增加项目评估入口;自然语言与表单统一任务,真实调用三个工作流 |
| `useStreaming.ts` | 定时逐字显示文本;定时展示预设 Skill 名称 | 使用后端真实事件与模型流;不能把定时动画当作执行证据 |
| `WatchPage.tsx` | 八状态、标签、备注、历史;文件仅保存名称 | 数据落库;状态与备注在同一事务写入历史;项目文件实际解析 |
| `ProfilePage.tsx` | 八组表单;文本文件启发式导入 | 保留八组表单与版本,后端判定完善状态;按最新确认关闭文件导入 |
| `AiPanel.tsx`、`src/lib/ai.ts` | 单项目和整批模板分析;规则分数 | 绑定实际项目/检索快照,提供有来源的摘要与追问;深度投标决策显式触发 |
原匹配度规则的四维上限分别为 95、90、85、75;默认权重 40/20/20/20 下综合最高 88 分。因此不能原样迁移后声称已满足“90 分以上项目可识别”。需要调整评分标尺并用明确的测试样例验证,不能为制造高分而篡改真实数据。
## 3. 三个 Skill 的能力与集成方式
### 3.1 实际交付内容
| Skill | 读取来源 | 实际形态 | 业务职责 |
| --- | --- | --- | --- |
| tender-search 2.3.0 | `/Users/ruzhoukeji/tender-search-2.3.0/` | SKILL.md 与搜索、企业、市场、账户 API 参数文档 | 搜公告、项目召回、区域市场、采购方/供应商统计 |
| company-intel 1.0.2 | `/Users/ruzhoukeji/zlbx-company-intel-1.0.2/` | 工作流、API 速查、报告模板、Python HTML 渲染脚本 | 单企业调研、双企业对比、历史客户供应商与竞对 |
| bid-decision 1.0.4 | `/Users/ruzhoukeji/zlbx-bid-decision-1.0.4/` | 工作流、API 速查、报告模板、Python HTML 渲染脚本 | 具体项目参与建议、竞争信号、历史价格参照与风险 |
三个目录不是三个独立 HTTP 服务,也不存在已实现的“一次调用完整 Skill 报告”接口。后端需把其工作流转为受控执行步骤,调用已列出的数据工具,再由 DeepSeek 解释与生成报告。不能只把 Skill 名称放入提示词,就标记为“真实调用”。
主 Agent 是应用内的编排模块,不等于另外部署多个自主 Agent。本期使用明确的工具白名单、输入校验和有限工作流,不引入通用多 Agent 平台。
### 3.2 数据工具适配
共同数据地址为 `https://mcp-server.zhiliaobiaoxun.com/api_v2/`。数据工具使用 POST,账户余额为 `GET /account/balance`。请求头使用 `X-API-Key`,并按实际工作流保留版本标识:
| 工作流 | X-Client |
| --- | --- |
| 招投标检索 | `zlbx-bidding/2.3.0` |
| 企业情报 | `company-intel/1.0.2` |
| 投标决策 | `bid-decision/1.0.4` |
重点适配约束:
- `search_bids` 的金额条件为 `min_amount/max_amount`;`query_bids_advanced` 为 `min_money/max_money`;聚合接口放在 `filters.min_money/max_money`。上游均以元为单位,前端万元转换必须集中处理。
- 基础关键词数组在上游为 OR;`keyword_groups` 表示组间 AND、组内 OR。不能直接沿用原前端“空格分词全部命中”的规则而不说明。
- 公告阶段与用户跟进状态分开:上游 1/2/4/7/8 等为采购意向、预招标、招标、中标、合同等事实阶段,不自动推进“已报名”等个人跟进状态。
- 搜索分页 `page_size` 最大 50;企业搜索最大 20。API 总命中数、实际拉取公告数、去重项目数、展示数分别记录。
- `find_competitors` 使用已确认企业全称,不能沿用其他工具可传公司 ID 的方式。
- API 返回的公告/企业 URL 原样保留,包括签名参数;日志不记录签名值。原公告网址只有在上游确实提供时展示,不能将平台详情页冒充原发布网站。
- 某些参考文件对竞对字段写法不一致,如 `name/product/caller/province`。首日用真实小样本确认响应,适配层兼容已核实变体,缺字段明确报缺口。
- 业务成功同时检查 HTTP 状态与响应 `success/error`;不得将 HTTP 200 中的额度错误当作无结果。
### 3.3 产品规则与 Skill 文档的冲突处理
用户在本轮明确的产品要求优先;目录内说明是实现参考,不是自动执行注册、收费查询或扩展产品范围的授权。
| 文档差异 | 本产品处理 |
| --- | --- |
| tender-search 企业接口说明允许自动合并总部和分支;产品要求同名主体确认 | 多候选进入主体选择,未确认不启动企业深查;未经确认不汇总集团口径 |
| 检索说明允许无结果自动放宽时间/关键词 | 原条件结果始终保留;优先提供“一键扩大范围”。如执行补充检索,独立记录新条件,不替换原结果或悄悄改变任务 |
| Skill 引导安装 opportunity-radar、标书生成工具或配置持续监控 | 本期只承诺三个已提供 Skill,不安装或转调第四个 Skill,不做自动写标书与监控通知 |
| 两个 Skill 默认额外生成 HTML 报告 | 本期核心交付为结构化数据与 Markdown 报告;HTML 属于现成可复用资源,不自动扩大为分享、导出产品功能 |
| Skill 含自动注册、设备特征采集流程 | 本产品使用后端预配置凭证;不自动注册、不采集设备标识、不自动充值 |
| Skill 的调用次数与积分预算存在不同口径 | 两项分别限额;价格参考仅用于预计值,以响应 `meta.cost_units` 记录实际扣费,未知不记为零 |
| 投标工作流包含报价带和竞争结论 | 有可比样本才给历史价格参考;缺少自身成本不能声称利润底线,历史成交特征不能证明违法或确定中标概率 |
## 4. 场景、路由与对话规则
| 入口/意图 | 必要输入 | 主工作流 | 初始交付 |
| --- | --- | --- | --- |
| 查目标客户 | 一个可确认的企业主体 | 企业情报 | 主营、采购/中标表现、客户供应商、竞对、数据缺口 |
| 查竞争对手 | 一个或两个企业主体;我方可选 | 企业情报 | 单企业画像或双企业对比;共同客户与投标重叠证据 |
| 查区域市场 | 地区;水务业务词可选 | 招投标检索 | 采购热度、Top 买方/供应商、时间趋势和统计范围 |
| 评估投标项目 | 公告链接、完整标题、投标文件三选一 | 投标决策 | 参与建议、竞争信号、历史报价参考、风险及缺口 |
| 我要获客 | 至少一个水务关键词;时效默认近 90 天 | 招投标检索,必须真实执行 | 带来源的初始商机报告;不自动调用另外两个工作流 |
| 普通公告查询 | 明确关键词与显式筛选条件 | 招投标检索 | 符合条件的公告列表,发布时间倒序 |
具体项目且提问“是否值得投/如何报价”优先项目研判;明确企业的背调/对比优先企业情报;地区、行业、产品与“找项目/看市场”走招投标检索。混合多个业务目标时先让用户选本轮目标,不并行发起多个深度任务。
区域市场未提供业务词时,使用公开展示的水行业基础关键词集合,并写入实际检索条件。API 需要关键词,不能传空数组后假装做过全行业查询。地区未明确时可使用全国默认值,但需在执行前摘要与结果中显示。
每次补问最多 1–2 项,仅询问执行必需的信息。会话继承已经确认的关键词、地区、主体和项目;与新输入冲突时生成选择项,不静默覆盖。已经执行的任务保留条件快照,新确认产生后续任务。
四个调研入口的“两步”验收指正常输入情况下“选择入口 → 提交必要输入”;企业同名确认等必要澄清不通过猜测来省略。
## 5. 获客的召回、排序与深挖
### 5.1 硬条件与偏好分离
统一任务必须分别保存 `hardFilters` 与 `preferences`。获客基础召回使用关键词、时效及公告阶段;默认全国、近 90 天,初始阶段按 Skill 默认 `[1,2,4,7,8]` 展示并允许明确选择。
| 获客方式 | 召回行为 | 排序行为 |
| --- | --- | --- |
| 综合推荐 | 使用相同基础召回 | 关键词相关度为主 |
| 地域推荐 | 不把重点省市传为排除其他地区的条件 | 重点省市命中加分;周边范围先用用户确认城市,不虚构实际距离 |
| 业务推荐 | 使用用户选择的关键词与可解释同义词集合 | 按标题、标的物、已取得正文的相关性排序 |
| 金额推荐 | 不把偏好预算区间传为金额硬过滤 | 已披露预算与目标区间的接近程度加分;未披露预算保留并标“待核验” |
用户明确说“仅限浙江”“必须 100–500 万元”时才升级为硬条件,并在执行摘要说明;不能把档案偏好自动变成硬条件。原普通检索表单的地区与预算仍为用户显式硬条件,保持该场景语义。
实现采用版本化、可解释的相关度与偏好加分,不让模型自由删改候选集。字段缺失不是零金额、不匹配地区或不具备资质;缺失字段不能被判定为负面事实。排序分与公司匹配分为不同字段,不混用。
### 5.2 “先找全”的可验收边界
先遍历允许的分页,再对已取得候选集统一排序;不能只拉第一页就声称给出了全量 Top 项目。单次调用/积分预算、最大页数与外部接口上限均需记录。
建议开发默认每批最多拉取 5 页、每页 50 条,作为可配置的成本保护值,而不是已承诺的全量规模。若总数超出本批覆盖,结果必须显示“平台命中 N 条,本批已读取 M 条,去重后 K 个项目,排序仅覆盖本批”,提供继续检索动作,不写“全部已找全”。实际页数上限以首日额度验证后锁定。
优先以公告 ID/唯一键去重;跨公告用项目编号、采购方、标段等可靠字段归并,保留意向、变更、候选、中标、合同的阶段链。仅标题相似时标记可能关联,不将两个项目强行合并。归并不得丢失阶段和来源。
市场总量优先使用上游聚合接口。仅有前几页时不得把样本计数或金额累计标成全市场统计;中标结果与合同可能对应同一交易,无法归并时注明按公告统计。
### 5.3 深挖与原有评分
初始获客报告仅调用招投标检索工作流。用户点击“了解采购方/竞对”后才新建企业情报任务;点击“深入研判”后才新建投标决策任务。每批建议只选择前 3 个,最多 5 个重点对象,串行执行并在预算不足时等待选择,不自动把 Top5 全部深查。
公司档案完善后可计算原列表的四维匹配分:业务贴合、服务地区、金额匹配、业绩与资质;维度名称固定,默认权重 40/20/20/20,可调权重。建议维度得分统一使用 0–100,综合分由后端按未提前舍入的归一化权重计算,最终一次取整;全零或负权重拒绝保存。证据缺失的维度标“待核验”,完整性与得分分开展示。分数不表示已满足硬资质或中标概率。
档案未完善时不给综合匹配分。沿用原型最低要求“企业名称+主营业务”,其他字段缺失仍应逐项提示。档案/权重版本变化使新计算使用新版本,历史报告保留当时版本与分数。
## 6. 统一任务、运行状态与可审计事件
统一任务至少保存:任务 ID、用户/会话 ID、入口、原始问题、意图、已确认主体/项目、硬条件、偏好、输入文件 ID、继承上下文版本、Skill 名称与版本、调用和积分预算、幂等键、父任务、实际范围及结果。
推荐状态:`RECEIVED → PLANNING → RUNNING → SUCCEEDED/PARTIAL/FAILED/CANCELLED`。缺信息、同名企业、预算不足分别进入 `WAITING_INPUT`、`WAITING_ENTITY`、`WAITING_BUDGET`,确认后继续;不阻塞请求线程等待用户。
前端只展示可审计的“计划 → 行动 → 结果 → 下一步”:
| 事件 | 内容与真实性要求 |
| --- | --- |
| 计划摘要 | 业务目标、实际筛选条件、预计 Skill 和预算;标注“计划调用”,不能提前记成已调用 |
| 工具开始 | 实际发出调用后产生;包含产品化工具名和任务步骤 |
| 工具完成/失败 | 对应一次真实请求;记录返回条数、耗时、错误类别和成本是否已知 |
| 等待输入/主体/预算 | 展示候选项或必要问题;不继续昂贵调用 |
| 报告片段 | 模型实际生成的报告内容,引用已登记证据 |
| 结束 | 最终状态、实际范围、实际调用及费用摘要;部分成功不能显示全部完成 |
不传输或展示原始私有推理链、系统提示词、密钥、原始认证头。原前端的预设调用动画必须撤换。
后端先持久化有序事件,再通过 SSE 推送。事件含递增 ID,断线可按最后 ID 重放;重连只读事件,不重新发起收费工具。任务创建和继续操作使用幂等键,用户连点不重复执行。取消后停止未发出的步骤,已发出的调用可能继续计费,真实记录该事实。
本期单实例、有限工作线程和有界队列即可。服务重启时将未完成任务标记为中断/部分结果,提供明确重试入口,不自动重放无法确认是否扣费的请求。
## 7. 事实、引用、费用与文件
### 7.1 报告结构与来源
报告统一包含:一句话结论;实际条件和数据时间范围;结果表;事实;Agent 推断及依据;数据缺口和置信说明;数据来源与分析范围;实际 Skill/工具调用和成本;一个最相关的下一步。
每条事实绑定证据 ID,证据记录工具调用 ID、记录标识、完整来源 URL、发布时间/抓取时间及必要摘录。模型只能引用已登记证据,不得生成“看起来正确”的链接。用户文件事实标注文件名、页码/工作表/幻灯片定位,不能写成已获公开公告核实。
模型生成的数字与企业名称须能回溯到工具结果或用户提供资料;统计计算由后端完成。缺少关键证据时返回数据缺口,不让模型补齐。一般项目问答限于已取得上下文;需要新外部资料时记录真实补查。
### 7.2 成本控制
- 分开保存工具调用次数、知了积分、联网检索/抓取次数、DeepSeek 输入/输出 token。不同单位不能相加为一个“总次数”。
- Skill 文档的参考预告为企业单查约 10–18 积分、双查约 20–28 积分;投标完整模式约 12–25 次调用、快速模式约 5–8 次。它们是文档估计,不是本项目已验证价格。
- 企业单查调用上限参考 18、双查 25,投标决策参考 25;另外设独立积分预算。具体价格、余额、免费主体查询以真实账号验证,不能认定“一个工具永远扣一分”。
- 执行前展示预计范围;下一步可能超预算时暂停,用户增加额度后再继续。联系人默认不查,只有明确请求时执行。
- 实际积分读取响应 `meta.cost_units`;缺失时标“待核对”,不能以余额差推断并发任务的准确费用。模型未返回 usage 也标未知。
- 缓存命中与真实外部调用分别展示。每次新建获客报告至少真实调用一次招投标检索工具;重复打开历史报告不重复扣费。
- 超时不能盲目自动重试可能已扣费的调用;优先使用供应商支持的幂等能力,未明确支持时记录结果未知并提供用户可理解的重试动作。
### 7.3 投标文件处理
本轮最终确认覆盖前述所有格式,但仅用于对应投标项目任务。不得用于训练、自动建立其他客户档案或无关调研;公司档案本期手动填写,不接受文件导入。
| 格式 | 处理路径 | 验收边界 |
| --- | --- | --- |
| TXT/MD/CSV/HTML | 检测类型与编码,提取文本/表格单元格 | 不执行 HTML 脚本,不把文档中的指令当系统指令 |
| DOC/DOCX、XLS/XLSX、PPT/PPTX | 使用成熟解析库提取文字及定位信息 | 不执行宏;复杂表格可失去排版,但不得虚构单元格关系 |
| 文字 PDF | 提取逐页文本 | 保留页码和原始证据定位 |
| 扫描/混合 PDF | 识别无文本页,逐页渲染后使用模型视觉能力解析 | 有页数、大小与成本限额;超过限额提示拆分,不能静默漏页 |
| JPG/PNG/WebP/GIF | 模型视觉理解并提取内容 | 动画 GIF 按首帧处理并提示;低清、缺页或不可辨认内容提示核验 |
建议首版保护值:单文件 20 MB、PDF 最多 50 页、视觉处理每任务最多 20 页/张;工作簿/幻灯片/提取文本也设置大小和条数上限。它们是可配置的实施默认值,应在上传界面事先显示,不冒充“任意大小均支持”。加密、损坏、未知类型或内容不符的文件必须给出具体错误与下一步。
原文件及解析临时内容建议上传后最多保留 24 小时,用户可提前删除。清理包括临时图片、提取全文、模型供应商文件引用(如使用)和失败任务残留;报告仅保留已引用的必要摘录与来源定位。删除文件不等于删除已有报告摘录,界面说明区别,并提供删除报告/会话入口。供应商侧留存政策不能承诺由本系统控制。
仅允许在当前账号/任务权限内下载或删除文件。审计保留文件类型、哈希、上传/删除时间等必要元数据,避免保留正文。审计元数据建议保留 180 天,可配置;原文件期限与审计期限分别管理。
### 7.4 网址与资料出入边界
知了详情链接优先通过详情工具读取。其他公开公告链接走受控网页正文获取,再按标题/采购方与标讯交叉核实;登录、验证码、付费或无法访问时提示上传文件或完整标题,不声称已抓取正文。
本地文件可按既定 DeepSeek 模型方案发送必要文字/图片用于当次解析;上传界面明确该用途。知了数据查询仅发送项目/企业名等查询参数,不上传本地文件全文。联网补充仅使用必要公开实体查询,不能将文件全文或内部商务内容送入搜索引擎。
URL 获取需防止访问本机/内网地址、重定向绕过及超大响应。所有外部内容均视为待分析数据,不能借公告内容改变系统工具、预算、权限或执行命令。Markdown 与外链渲染需做协议校验和内容清理。
## 8. 原有业务闭环
| 模块 | 保留与修正要求 |
| --- | --- |
| 公司档案 | 八组表单、保存、版本、完善状态、四维权重;关闭文件导入;不自动填入虚构演示公司 |
| 检索方案 | 保存/修改/删除/手动执行;执行条件、项目集与顺序冻结为快照,Tab 不按当前条件悄悄重算 |
| 重点关注 | 已关注、准备投标、已报名、已提交投标文件、已中标、未中标、已流标、暂不考虑 |
| 状态规则 | 允许人工跳转和恢复;结果页与暂不考虑分组保留;不会因截止时间、公告更新或 AI 建议自动变更 |
| 历史与备注 | 一次提交原子保存状态、备注快照、操作人与时间;仅改备注也留痕;重复提交不产生重复历史 |
| 标签 | 自定义、增删、关注绑定与筛选;删除标签同步解绑;关注唯一约束避免重复 |
| 取消关注 | 沿用原页面确认后删除该关注的状态/备注/历史;不删除公共公告、来源与已生成报告;暂缓项目建议用“暂不考虑” |
| 会话 | 新建、标题搜索、重命名、删除、任务历史;删除进行中会话时先阻止后续步骤并处理文件引用 |
| 单项目/整批提问 | 项目使用项目快照,整批使用实际检索批次而非当前分页;超上下文时分段汇总并显示覆盖范围 |
## 9. 技术与持久化设计建议
沿用 Java 21、Spring Boot MVC、MySQL、React/TypeScript/Vite。采用业务模块内的 Controller/Service/Repository,三个受控工作流复用数据客户端;不新增向量数据库、消息中间件或独立 Agent 微服务。
后端使用成熟安全组件处理预设 admin、密码哈希和服务端会话。密码由部署环境提供,不提交默认弱口令。前端同源代理 `/api`,会话 Cookie 配合 CSRF 防护;鉴权覆盖任务、会话、文件、报告与跟进数据。
| 数据组 | 必要记录 |
| --- | --- |
| 用户与档案 | 用户、公司档案、档案/权重版本 |
| 公告与检索 | 公告、公告阶段来源关系、检索方案、执行批次及有序公告快照 |
| 人工跟进 | 关注记录、历史、标签及绑定 |
| 会话与任务 | 会话、消息、任务、确认参数、父子任务、结果与报告版本 |
| 轨迹与证据 | 有序任务事件、实际工具调用、耗时/状态/费用、事实证据引用 |
| 临时文件 | 账号/任务归属、类型、位置、过期/删除时间、解析状态 |
金额以精确十进制和明确单位保存;时刻返回带时区的 ISO 8601,业务日期按 Asia/Shanghai 解释;报名/投标截止只有日期时标明精度,不臆造具体时分。需要用户人工确认的事实不能被模型输出直接覆盖。
注释要求:后续代码按用户要求补充详细中文注释,重点解释硬条件/偏好边界、主体确认、金额转换、计费预算、幂等、状态事务、引用校验、文件清理和降级原因,避免只注释语法表面。
## 10. 开工依赖与当前验证边界
1. 后端环境需要配置可用的 `ZLBX_API_KEY`、`DEEPSEEK_API_KEY`、数据库连接与 admin 初始密码。只通过本地环境配置,不在聊天、提交记录或前端包中保存密钥。
2. 知了账号需有足够额度且允许部署应用访问;使用条款、返回链接有效性与接口字段需在首日实测。本轮未发起收费查询或注册。
3. DeepSeek 模型、联网 Search/Fetch、视觉能力及账号权限需做真实验证。公开文档显示 `deepseek-flash` 当前对应 V4.1-Flash-1017;配置可变,发布时再次核实,不能把网页聊天能力当作 API 已可用。
4. 未核实凭证不等于没有凭证;本轮没有读取或打印密钥。没有真实服务调用证据时只能标记开发/模拟验证,不能标“真实联调通过”。
5. 本期交付以本地或指定测试环境可运行、前后端联调通过为界;生产域名、TLS、服务器与上线运维不因四天计划而自动视为已交付。
## 11. 资料依据
- 产品需求:本次会话中的原型说明、Agent 方案及后续确认;冲突以最新确认优先。
- 本地三个 Skill 的 `SKILL.md`、`references`、两个报告渲染脚本;版本按第 3 节固定,文档内容尚未全部经过在线 API 验证。
- [DeepSeek 更新记录](https://api-docs.deepseek.com/updates/)与[模型调用说明](https://api-docs.deepseek.com/quick_start/agent_integrations/):核对日期 2026-10-26。
- [DeepSeek Search & Fetch](https://api-docs.deepseek.com/guides/search/)与[视觉输入说明](https://api-docs.deepseek.com/guides/vision/):联网与图片能力需独立接入并验证,不默认随模型回答自动发生。
- [Apache Tika](https://tika.apache.org/)与[PDFBox 文档](https://pdfbox.apache.org/3.0/migration.html):用于多格式提取、PDF 处理的候选实现;开发时选择兼容且维护中的依赖版本,不把支持格式说明等同于实际解析通过。
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment