proposa-ai

Proposa AI

AI 驱动的投标书生成服务：解析招标文件、采购需求、澄清公告、公司资料和历史参考投书， 经 Step1-6 工作流生成最终 DOCX 投标书。HTTP API 是主要对接入口，后台直接执行与人工 验证相同的 scripts/test_step1.py 至 scripts/test_step6.py。

处理流程

1. Step 1：文档解析及表/函/表格提取。
2. Step 2：招标需求、评分项、废标项及响应项分析。
3. Step 3：结合模板、评分项和参考投书生成大纲。
4. Step 4：生成章节内容及章节 DOCX 中间产物。
5. Step 5：覆盖性、废标风险和内容完整性审核与修复。
6. Step 6：按模板装配 DOCX，生成最终投标文件。

项目结构

proposa-ai/
├── src/                         # 正式功能代码
│   ├── config.py                # .env 与全局配置
│   ├── models.py                # 数据模型
│   ├── chapter_policy.py        # 章节结构策略
│   ├── doc_reader/              # PDF/DOCX/Markdown 读取
│   ├── llm_client/              # LLM 调用与缓存
│   ├── pdf_table_to_docx/       # PDF 表格提取
│   ├── step1_parsing/ ... step6_exporting/
│   └── templates/               # 正式 DOCX 模板资源
├── scripts/                     # 阶段脚本与快速回归
│   ├── test_step1.py ... test_step6.py
│   └── tests/
├── data/                        # 项目输入数据
├── test_data/                   # 手工测试数据
├── output/                      # 生成产物与缓存
├── models/                      # 可选本地 NLP 模型资源
├── deploy.sh                    # Linux 部署脚本
├── .env                         # 本地配置，Git 忽略
├── .env.example                 # 环境变量示例
└── pyproject.toml               # uv 依赖与安装配置

环境配置

uv sync

项目已在 pyproject.toml 的 [tool.uv] 中配置清华 PyPI 镜像 （https://pypi.tuna.tsinghua.edu.cn/simple）加速依赖下载；需要更换镜像时， 设置环境变量 UV_INDEX_URL 覆盖即可。

复制 .env.example 为 .env：

Copy-Item .env.example .env

至少填写：

DEEPSEEK_API_KEY=你的密钥

操作系统环境变量的优先级高于 .env。

环境变量说明

参数	必填	默认值	说明
DEEPSEEK_API_KEY	是	无	DeepSeek API 密钥。仅保存在本地 .env，不得提交到 Git。
DEEPSEEK_BASE_URL	否	https://api.deepseek.com	DeepSeek 兼容 API 的基础地址。
DEEPSEEK_MODEL	否	deepseek-v4-flash	分析、生成和审核使用的模型名称。
BID_OUTPUT_DIR	否	output	工作流默认输出目录；相对路径以仓库根目录为基准。
BID_WRITER_CONCURRENCY	否	5	Step4 并发撰写章节的最大线程数。
BID_ANALYZER_CONCURRENCY	否	5	Step2 并发分析文档分块的最大线程数。
BID_HEADING_CONCURRENCY	否	5	Step6 标题层级分析的最大 LLM 并发数。
PROPOSA_API_HOST	否	0.0.0.0	HTTP API 监听地址；默认监听所有网卡。
PROPOSA_API_PORT	否	8000	HTTP API 监听端口。
PROPOSA_WORK_DIR	否	output/api_jobs	HTTP API 和 test_step1-6 默认工作目录；每个请求的内容放在 PROPOSA_WORK_DIR/<request_id>/ 下，中间文件在 work/，最终 DOCX 在请求目录根。
REFERENCE_DIR	否	/data/shenqin/	JSON 模式下参考投标文件相对路径的首选目录。
REFERENCE_DIR1	否	/data/dms/dms_upload	JSON 模式下参考投标文件相对路径的第二候选目录。
TPC_DIR	否	无	JSON 模式下招标文件、采购需求和澄清公告相对路径的拼接前缀。
PROPOSA_API_MAX_UPLOAD_MB	否	512	单个上传文件的大小上限，单位 MB。
PROPOSA_API_TIMEOUT_SECONDS	否	28800	Step1-6 后台子进程超时秒数，默认 8 小时。
PROPOSA_API_CONCURRENCY	否	1	同时执行的后台生成任务数；大型 DOCX 场景建议保持 1。
PROPOSA_CALLBACK_TIMEOUT_SECONDS	否	30	单次回调 HTTP 请求的超时秒数。
PROPOSA_CALLBACK_MAX_RETRIES	否	3	回调失败时的最大尝试次数，包含首次请求。

部署（Linux 服务器）

仓库提供一键部署脚本 deploy.sh，按顺序完成：

1. 检测到服务器未安装 uv 时自动安装（默认开启，AUTO_INSTALL_UV=0 可关闭）；
2. 使用 ModelScope 将 gpt2-chinese-cluecorpussmall-onnx 下载到 models/ 目录（模型文件已存在时跳过）；
3. 使用 uv sync --frozen 安装锁定依赖；
4. 后台启动 proposa-api，写入 PID/日志文件并做 /health 健康检查。

部署前准备

cp .env.example .env

编辑 .env 填写真实配置，至少设置 DEEPSEEK_API_KEY；PROPOSA_API_PORT、 PROPOSA_WORK_DIR、REFERENCE_DIR、REFERENCE_DIR1 等可按需调整。

执行部署

sh deploy.sh            # 完整部署并后台启动（可重复执行）
sh deploy.sh status     # 查看运行状态与健康检查
sh deploy.sh stop       # 停止后台服务
sh deploy.sh restart    # 停止后重新后台启动

日志位于 output/api.log，PID 位于 output/api.pid。

请求审计日志位于 output/requests.log，UTF-8 JSONL 格式，每行一条事件，追加写入。 记录原始 JSON 请求体、接口响应状态码及 JSON 正文，以及每次回调的地址、载荷、 HTTP 状态码、响应正文或异常；通过 request_id 关联，成功创建任务时它也是任务 ID。 校验失败的请求也记录。multipart 记录表单字段和文件名/大小/类型，不记录文件二进制。

processing_request 在校验完成、提交后台任务之前记录最终处理参数：body 中为复制到 任务目录后的实际文件绝对路径、规范化回调地址、txbId 和生效的清理开关；两个路径模式 标记均为 true，表示这些最终路径已经是绝对路径。JSON 模式额外通过 source_paths 记录删除 static、目录拼接后的源文件绝对路径，便于对照原始请求。CLA_FILE 仅保存， 不参与生成，日志通过 clarification_used_in_pipeline=false 明确标注。

下载响应仅记录状态码，不记录 DOCX 内容。日志不随任务中间文件清理，重启后仍保留。 回调 HTTP 200 的业务错误正文会原样记录，原有按 HTTP 状态判断投递成功的规则不变。 日志包含请求中的路径和回调信息，仅保存在服务器，按运维要求限制访问并定期归档。

tail -f output/requests.log

可用环境变量：MODEL_REPO（默认 Maiteka/gpt2-chinese-cluecorpussmall-onnx）、MODEL_DIR（默认 models/gpt2-chinese-cluecorpussmall-onnx）、UV_CACHE_DIR（默认 <仓库根>/.uv-cache）、UV_INDEX_URL（默认清华 PyPI 镜像 https://pypi.tuna.tsinghua.edu.cn/simple）、PROPOSA_API_PORT（默认读取 .env，缺省 8000）、 RESTART=1（服务已运行时强制重启）、AUTO_INSTALL_UV=0（uv 缺失时只提示、 不自动安装）。

HTTP API（对接主文档）

启动服务

uv run proposa-api

接口总览

接口	方法	说明
/health	GET	健康检查。
/api/v1/files/validate	POST	上传单个文件，同步检测 DOCX / 文字型 PDF，供入库前校验。
/api/v1/final-review	POST	提交生成任务，返回 HTTP 202。
/api/v1/jobs/{request_id}	GET	查询任务状态。
/api/v1/jobs/{request_id}/progress	GET	查询 Step1-6 进度。
/api/v1/jobs/{request_id}/file	GET	下载最终 DOCX。

这三个任务接口的路径 ID 均可传 request_id 或提交时的 txbId 值，无需增加查询参数。 系统优先精确匹配 request_id，找不到时按 txbId 查询最近提交的任务。 同一个 txbId 多次提交会生成不同 request_id，旧任务仍可通过其 request_id 查询。 新任务无论排队、处理中、失败还是完成，均不会自动回退旧成功任务；校验或后台提交失败 不替换已有映射。映射按提交顺序更新，不随完成顺序改变。

GET /api/v1/jobs/TEST-TXB-001
GET /api/v1/jobs/TEST-TXB-001/progress
GET /api/v1/jobs/TEST-TXB-001/file

任务查询响应中的 request_id 和返回的 URL 仍使用实际任务 ID。需要保证多次查询及下载 属于同一次生成时，先用 txbId 查询状态，取响应 request_id 后固定使用它。 映射和任务记录均为进程内存状态，服务重启后不保留；多实例需访问持有任务的实例。 完整示例见 API 进度查询接口对接文档。

入库前文件检测

完整字段、路径规则和错误示例见 文件检测接口对接文档。

POST /api/v1/files/validate 支持 JSON 服务端路径和 multipart 文件上传。 每次只检测一个文件，不需要 txbId、回调地址或本地模板，不创建任务、不调用 LLM。

JSON 请求包含三个必填字段：

{
  "file_path": "static/file/参考投书.docx",
  "file_role": "REFERENCE_BID",
  "is_absolute": false
}

字段	说明
file_path	非空字符串，服务端文件路径，不是 HTTP 下载地址。
file_role	TENDER_FILE 招标文件、PROCUREMENT_FILE 采购需求、CLA_FILE 澄清公告、REFERENCE_BID 参考投书。
is_absolute	必填布尔值；true 直接读取清理后的路径，false 按业务用途拼接目录。

路径规则与原生成接口共用：先清理独立 static 目录段；相对模式下，前三类拼接 TPC_DIR，参考投书依次在 REFERENCE_DIR、REFERENCE_DIR1 下查找，首个存在文件优先。 成功响应额外包含 file_role 和 resolved_path（实际完整源文件路径）。业务用途决定 路径规则；本检测接口允许各用途的有效 DOCX 或文字 PDF，生成接口的业务字段格式限制仍保留。

失败仍返回非 2xx HTTP 状态，包含顶层 valid=false、message、兼容字段 detail、 resolved_path 和 candidate_paths。文件不存在、损坏、无文字、超限或无法读取时， message 包含解析后的完整源路径，不返回检测临时副本路径。例如：

{
  "valid": false,
  "message": "REFERENCE_BID 不是有效的 DOCX 文件；完整文件路径：/data/shenqin/file/参考投书.docx",
  "detail": "REFERENCE_BID 不是有效的 DOCX 文件；完整文件路径：/data/shenqin/file/参考投书.docx",
  "resolved_path": "/data/shenqin/file/参考投书.docx",
  "candidate_paths": ["/data/shenqin/file/参考投书.docx"]
}

参考投书所有配置目录均未找到文件时，message 和 candidate_paths 列出所有完整候选路径， 多个候选时 resolved_path=null。参数无效或目录未配置、无法确定完整路径时，明确返回原因， 不虚构完整路径（resolved_path=null、candidate_paths=[]）。

multipart 模式仍使用小写 file 上传；该模式无服务端源路径，失败不返回临时路径：

curl.exe -X POST "http://127.0.0.1:8000/api/v1/files/validate" -F "file=@待上传文件.pdf"

检测通过返回 HTTP 200：

{
  "valid": true,
  "file_type": "pdf",
  "is_text_pdf": true,
  "filename": "待上传文件.pdf",
  "size": 12345,
  "sha256": "文件内容的64位SHA-256摘要",
  "message": "文件检测通过"
}

• file_type 为 pdf 或 docx；DOCX 的 is_text_pdf 为 null。size 单位为字节。
• 校验后缀和实际内容，不信任上传 MIME；后缀不区分大小写。不自动修正错误后缀。
• DOCX 检查 ZIP、主文档内容类型、包关系及正文 XML；不要求 DOCX 有文字。
• PDF 必须未加密、可逐页解析，且至少一页有可提取文字；无文字或纯扫描 PDF 拒绝。 混合 PDF、有 OCR 文字层的 PDF 可能通过；不保证每页都有文字，不验证 OCR 或业务内容准确性。
• 沿用 PROPOSA_API_MAX_UPLOAD_MB（默认 512 MB）；检测副本在响应前自动删除。 PDF 检测会将文件读入内存，请按服务容量配置大小上限。
• 后端仅在 HTTP 200 且 valid=true 时继续入库，并确保入库内容与检测内容一致（可比对哈希）。 生成接口仍会再次校验文件和对应业务字段要求。

HTTP 400 表示文件/路径无效、目录未配置、空文件、不支持的后缀、结构无效、加密或无文字 PDF， 也用于无效 JSON；413 表示超限；415 表示请求不是 multipart 或 JSON；422 表示 JSON 必填参数 缺失/类型错误/用途无效，或上传缺少 file、字段不是文件、上传了多个文件。可在 /docs 查看并试用。

请求格式

接口同时支持 multipart/form-data 文件上传和 application/json 服务端本地路径。

multipart/form-data

curl.exe -X POST "http://127.0.0.1:8000/api/v1/final-review" `
  -F "CALLBACK_URL=http://121.43.55.7:10026/shenqin/tender/callback" `
  -F "txbId=投续表的DMS-ID" `
  -F "TENDER_FILE=@招标文件.pdf" `
  -F "PROCUREMENT_FILE=@采购需求.docx" `
  -F "REFERENCE_BID=@参考投标文件.docx" `
  -F "CLA_FILE=@澄清公告.docx" `
  -F "CLEAN_INTERMEDIATE=false" `
  -F "REFERENCE_IS_ABSOLUTE=false"

application/json

curl.exe -X POST "http://127.0.0.1:8000/api/v1/final-review" `
  -H "Content-Type: application/json" `
  --data '{
    "CALLBACK_URL": "http://121.43.55.7:10026/shenqin/tender/callback",
    "txbId": "投续表的DMS-ID",
    "TENDER_FILE": "E:/CODE/proposa-ai/test_data/171-上海群众艺术馆/上海市群众艺术馆物业管理服务采购项目招标文件.pdf",
    "PROCUREMENT_FILE": "E:/CODE/proposa-ai/test_data/171-上海群众艺术馆/采购需求.docx",
    "TPC_IS_ABSOLUTE": true,
    "REFERENCE_BID": "E:/CODE/proposa-ai/test_data/171-上海群众艺术馆/参考投标文件/物业管理费项目投标文件.docx",
    "REFERENCE_IS_ABSOLUTE": true,
    "CLA_FILE": "",
    "CLEAN_INTERMEDIATE": false
  }'

请求参数

参数	必填	说明
CALLBACK_URL	是	处理成功或失败后接收 JSON 的回调地址。
txbId	是	投续表的 DMS ID，回调时原样返回。
TENDER_FILE	是	招标文件；multipart 上传 PDF，JSON 传服务端本地路径。
PROCUREMENT_FILE	是	采购需求；multipart 上传 DOCX，JSON 传服务端本地路径。
REFERENCE_BID	是	参考投标文件；multipart 上传 DOCX，JSON 传服务端本地路径。
CLA_FILE	否	澄清公告文件；当前仅接收并记录，不参与生成。
TPC_IS_ABSOLUTE	JSON 是	仅 JSON 路径模式生效，必须传布尔值；false 时 TENDER_FILE、PROCUREMENT_FILE、非空 CLA_FILE 与 TPC_DIR 拼接，true 时原样读取。接口不会根据路径文本自行判断。
CLEAN_INTERMEDIATE	否	默认 true；设为 false 时保留中间文件并返回 intermediateDir。
REFERENCE_IS_ABSOLUTE	JSON 是	仅 JSON 路径模式生效，必须传布尔值；false 时依次在 REFERENCE_DIR、REFERENCE_DIR1 下查找 REFERENCE_BID，true 时原样读取。接口不会根据路径文本自行判断。

REFERENCE_BID 路径处理

JSON 模式的 TENDER_FILE、PROCUREMENT_FILE、REFERENCE_BID、CLA_FILE 在路径 拼接或绝对读取之前，统一删除独立的 static/（或 static\）目录段。例如 static/file/example.docx 变成 file/example.docx。保留其他目录、文件名和绝对路径根； 不修改配置目录本身，mystatic/、static.docx 不受影响。multipart 上传不做路径清理。

JSON 模式下：

• REFERENCE_BID 为绝对路径时直接使用。
• REFERENCE_BID 为相对路径时，设置 "REFERENCE_IS_ABSOLUTE": false，接口依次按 REFERENCE_DIR + REFERENCE_BID、REFERENCE_DIR1 + REFERENCE_BID 拼接并检查文件； 首选实际存在的文件，再复制到隔离任务目录。两处都存在时优先使用 REFERENCE_DIR。
• 两个候选目录均未配置，或配置后均不存在目标文件时，接口在启动 worker 前返回 400。
• 接口只按 REFERENCE_IS_ABSOLUTE 的布尔值处理，不根据路径是否以 / 开头自行判断； 相对模式下会先去掉文件值开头的路径分隔符再与配置目录拼接。

multipart 模式下 REFERENCE_BID 是上传文件本身，REFERENCE_IS_ABSOLUTE 仅兼容接收， 不参与路径拼接。

上传校验规则

• TENDER_FILE 必填且不能为空，只接受能正常打开并提取到文字的 PDF；纯扫描或损坏的 PDF 会返回 HTTP 400。
• PROCUREMENT_FILE 和 REFERENCE_BID 只接受 DOCX；服务验证 ZIP 容器、必需 OOXML 部件和正文 XML。
• CLA_FILE 可选；当前仅保存并在回调中记录原始文件信息，不参与生成或校验。
• JSON 模式路径不存在或扩展名不符合要求时，会在启动 worker 前返回 400。
• Windows 路径建议使用正斜杠，或正确转义反斜杠。

处理流程与文件路径

提交成功后，后台按顺序执行 test_step1.py 至 test_step6.py。

每个请求的内容都放在：

PROPOSA_WORK_DIR/<request_id>/
├── work/                          # Step1-6 中间文件与缓存
└── <招标文件名>.docx              # 最终 DOCX

最终文件名规则：招标 PDF 原文件名去掉 .pdf 后追加 .docx。

CLEAN_INTERMEDIATE=true（默认）时，处理结束后只清理 work/，最终 DOCX 保留； false 时 work/ 也保留。

提交响应（HTTP 202）

{
  "request_id": "501c42526b5b4bb6ad68f0d736ef5884",
  "txbId": "1",
  "status": "processing",
  "message": "三份文件校验通过，已开始处理",
  "resultPath": "E:/CODE/proposa-ai/api_output_v1/501c42526b5b4bb6ad68f0d736ef5884/招标文件.docx",
  "output_path": "E:/CODE/proposa-ai/api_output_v1/501c42526b5b4bb6ad68f0d736ef5884/招标文件.docx",
  "progress_url": "http://127.0.0.1:8000/api/v1/jobs/501c42526b5b4bb6ad68f0d736ef5884/progress"
}

字段	说明
request_id	任务唯一 ID，用于查询进度、状态和下载最终文件。
txbId	请求传入的投续表 DMS ID，原样回传。
status	当前任务状态；202 响应中为 processing。
message	处理提示信息。
resultPath	最终 DOCX 的绝对路径，位于 PROPOSA_WORK_DIR/<request_id>/ 下。
output_path	与 resultPath 相同的兼容字段。
progress_url	轮询步骤进度的 URL。
intermediate_dir	可选；仅当 CLEAN_INTERMEDIATE=false 时返回，指向 work/ 目录。

status 任务状态

状态值	含义
queued	任务已创建，等待后台 worker 开始处理。
processing	正在执行 Step1-6，可通过 progress_url 查看当前步骤。
completed	处理成功，resultPath 指向最终 DOCX，可下载。
failed	处理失败，resultPath 为 error: 具体错误信息。

进度查询

curl.exe "http://127.0.0.1:8000/api/v1/jobs/任务ID/progress"

{
  "updated_at": "2026-08-26T14:29:00+00:00",
  "current_step": 3,
  "total_steps": 6,
  "current_step_name": "Step 3 投书大纲生成",
  "status": "running",
  "message": "Step 3 投书大纲生成 正在处理",
  "completed_steps": [1, 2]
}

进度接口中的 status：

状态值	含义
running	当前步骤正在执行。
completed	当前步骤已完成；当 current_step 为 6 且状态为 completed 时，表示全部步骤完成。

任务状态查询与下载

curl.exe "http://127.0.0.1:8000/api/v1/jobs/任务ID"
curl.exe "http://127.0.0.1:8000/api/v1/jobs/任务ID/file" --output 投标文件.docx

GET /api/v1/jobs/{request_id}/file 仅在任务 completed 且文件存在时返回 DOCX。

回调

回调只在任务成功或失败后发送，不在提交时发送。

成功回调：

{
  "request_id": "任务ID",
  "txbId": "投续表的DMS-ID",
  "status": "completed",
  "resultPath": "output/api_jobs/<request_id>/招标文件.docx",
  "files": {
    "TENDER_FILE": {"filename": "招标文件.pdf", "size": 123, "sha256": "..."},
    "PROCUREMENT_FILE": {"filename": "采购需求.docx", "size": 456, "sha256": "..."},
    "REFERENCE_BID": {"filename": "参考投书.docx", "size": 789, "sha256": "..."}
  },
  "final_review_url": "http://API地址/api/v1/jobs/任务ID/file"
}

失败回调：

{
  "request_id": "任务ID",
  "txbId": "投续表的DMS-ID",
  "status": "failed",
  "resultPath": "error: Step1-6 处理进程异常退出（退出码 7）",
  "error": "Step1-6 处理进程异常退出（退出码 7）"
}

回调说明：

• 使用 POST JSON，不发送 token。
• 默认最多重试 3 次；重试仍失败时，任务状态记录 callback_delivered=false 和 callback_error。
• 请求中上传了 CLA_FILE 时，files.CLA_FILE 会包含 filename/size/sha256。
• CLEAN_INTERMEDIATE=false 时，成功和失败回调都会额外返回 intermediateDir。

常见 HTTP 状态码

状态码	含义
202	校验通过，任务已异步开始。
400	文件、路径、参数或回调地址校验失败。
413	上传文件超过大小限制。
415	不支持的 Content-Type。
422	缺少必填字段。
500	后台任务提交失败。

测试与局部验证

# 快速回归
uv run python -m unittest discover -s scripts/tests -v

# 按阶段手工测试（会使用 test_data 并可能调用 LLM）
uv run python scripts/test_step3.py
uv run python scripts/test_step6.py

生成结构保护规则

• 一级章节原则上以模板为准；只有评分项大类无法匹配任何模板标题时，才允许在“项目经理” 一级章之前新增一级章，并统一重排编号。
• Step4 使用 LLM 从 Step3 最终完整大纲识别重难点分析及应对类章节，结合父标题路径和 写作要求判断，不限制章号、所属章名或层级。业态、概况、分析和措施可分散在同级小节或不同章， 按职责原位协同重写，全部落点合计约 1 万字（正文 9,000～11,000 字），允许在命中节点下 增加不超过四级的子标题。原有标题、评分绑定、原生表格、图片及说明保持；其他小节按原规则处理。
• Step4 manifest 保存扩展后的最终标题映射；Step5 优先读取该映射，并审核重难点节点的完整 子树正文。Step6 保留新标题并同步目录和书签。无匹配章节时不新增专项章节。
• 评分项按“评分大类 → 具体小评分项 → 响应正文”组织；复用时必须能识别小评分项核心主题， 禁止重复创建同名/近义标题；新增标题不带分值，不使用 SC-xx 等内部编号。
• 废标项统一归入第一章要求承诺函，不散落、不重复。
• 最终真实一级章统一使用 第{中文序号}章 和 Heading 1，并映射到最终大纲。
• 模板中显式 Heading 1-4 只用于标题层级语义，不复制其视觉格式。
• Step5 补充正文必须写入 Step3 绑定的最深层评分标题节点。
• 开标一览表服务内容/服务要求/服务期限按表内填写说明统一填“响应”。
• 只有 %%表名%% 占位符允许创建或整表替换；Markdown 表格不能绕过授权生成 DOCX 表格。
• 表格、图片、图注、前后说明、签名照片/签署人/日期等原生内容块必须保持完整。