pipeline-bidding/docs/DESIGN.md

投标产线（bidding_general）设计文档

对照开发产线（sdlc_general）设计，复用平台通用内核（项目/会话/任务链/人类任务/交付件/问答冒泡/技能分层）， 只增量定义投标产线自己的 阶段、角色、工具、技能、任务流转规则、交付件。 版本：v1.1.0　　创建：2026-08-26　　修订：2026-08-31（产线起点改为上传招标文件；解析产出加 QC 契合度审核门禁）

---

零、产线边界（v1.1 修订）

• 招标信息的采集、摘要、审批归商机产线。投标产线从「上传招标文件」开始： 用户/驾驶舱直接创建投标项目 → 上传招标文件 → 进入解析。
• bid_tenders 表保留，但只承载招标文件解析抽取的商务要素（项目名称/招标人/编号/ 截止时间/周期/预算/保证金/资质要求，source=tender_doc），不再有邮件采集与审批状态机。
• 已删除：邮箱采集（bid_mail.py、bid_mail_accounts 表/页面）、招标审批（tender_approval 人类任务）、 摘要/审批/存档工具（fetch_tenders/summarize_tender/submit_tender_approval/approve_tender 等）、 招标信息状态机（new→summarized→pending_approval→…）。

---

一、业务流程

#	业务动作	承担者	落库
1	创建投标项目 + 设定参与人员	驾驶舱 / 人	sd_projects(pipeline_id=bidding_general) + bid_members
2	等待上传招标文件	人（阻塞门禁，上传后自动完成）	pipeline_human_tasks(tender_file_upload) + bid_tender_files
3	抽取评分项及得分规则	agent.tender_analyst	bid_scoring_items
4	抽取所需资质	agent.tender_analyst	bid_qualifications
5	抽取投标文件要求（章节结构/格式/份数/密封）+ 商务要素	agent.tender_analyst	bid_doc_requirements + bid_tenders(source=tender_doc)
6	生成章节骨架（评分项挂载）	agent.tender_analyst	bid_chapters
7	解析产出 QC 契合度审核（四类逐类，10 分制 >9.5 放行，否则改进意见退回重做）	agent.qc	bid_qc_reviews
8	从公司投标知识库获取所需资质文档	agent.bid_prep	bid_qualifications.kb_doc_id ← bid_kb_docs
9	发布人类应提供的文件清单	agent.bid_prep（阻塞门禁）	pipeline_human_tasks(human_docs_request)
10	按投标文件要求分章节编写投标文件	agent.bid_writer	bid_chapters
11	每章节完成后对照招标/投标文件要求评审，分数不够给改进意见重做	agent.bid_reviewer	bid_reviews(scope=chapter) → 章节循环
12	合成标书	agent.bid_compositor	bid_documents（docx）
13	对整个标书评审 + 按评分项和得分规则打分	agent.bid_scorer	bid_reviews(scope=whole) + bid_scores
14	不合适 → 改进意见 → 修改问题章节 → 评审 → …… 直到得分通过	机制（整书循环）	bid_scores.target_chapter_id → 章节回 rejected
15	交付确认	人	pipeline_human_tasks(bid_delivery_confirm) → 项目 completed

---

二、阶段与角色

阶段	角色规范名	职责
立项与上传	驾驶舱 + 人	建项目、配人、上传招标文件
招标文件解析	agent.tender_analyst	抽取评分项+得分规则、所需资质、投标文件要求、商务要素，产出章节骨架
解析产出 QC	agent.qc	四类产出对照招标文件原文按 10 分制审核契合度，>9.5 放行，否则改进意见退回
资料准备	agent.bid_prep	知识库资质匹配、缺失项发布人类文件清单
章节编写	agent.bid_writer	按章节骨架逐章写作（一章一任务）
章节评审	agent.bid_reviewer	对照招标要求+得分规则逐章打分，不达标退回重写
标书合成	agent.bid_compositor	合成 docx（封面/目录/页码），产出交付件
全书评分	agent.bid_scorer	按评分项+得分规则给整书打分、生成改进意见并映射章节
任务验收	agent.pm	任务审核/验收
合规检查	agent.qc（复用）	解析产出契合度审核（本产线 QC 的主职责）

角色命名遵守平台规范：agent 角色 = agent.{role}，人类角色 = RBAC {orgtype}.{role}。 RoleSpec.next_role 全部留空：投标是「一章一任务 + 多级回退循环」扇出结构， 流转一律由 bid_flow 状态对账器（每 15s）决定，它是角色任务唯一创建者。

---

三、任务流转规则

3.1 主链（机制驱动，非 LLM 驱动）

[立项] create_bid_project → sd_projects + 「上传招标文件」人类任务(阻塞)
    ↓ 上传完成（对账器自动关闭上传任务）
agent.tender_analyst  → 评分项 / 资质 / 投标文件要求 / 商务要素 / 章节骨架
    ↓
agent.qc（A2 QC 门禁）→ 四类产出逐类契合度审核（10 分制）
    │   得分 > 9.5 → 该类放行
    │   不通过 → 改进意见 → 清空该类产出 → 解析重做（携带意见）→ 重审
    │   轮次超限（默认 3）→ 抛人工（qc_escalation 阻塞，逃逸阀：人工修/强制放行）
    ↓ 全部放行
agent.bid_prep        → 知识库资质匹配 + [人类任务:应提供文件清单](阻塞)
    ↓
agent.bid_writer      → 逐章写作（每章一个任务，可并行）
    ↓ 章节 written
agent.bid_reviewer    → 章节评审打分
    ↓ 全部章节 approved
agent.bid_compositor  → 合成标书 docx
    ↓
agent.bid_scorer      → 整书评分
    ↓ 通过
[人类任务:交付确认] → 项目 completed

3.2 QC 门禁：解析产出契合度审核（v1.1 新增）

• 审核对象（四类，逐类审核）：

  qc_type	落库表
  scoring_items 评分项+得分规则	bid_scoring_items
  qualifications 所需资质	bid_qualifications
  doc_requirements 投标文件要求	bid_doc_requirements
  chapter_outline 章节骨架	bid_chapters

• 判定：agent.qc 对照招标文件原文逐项核对，按 10 分制打契合度分； 得分高于通过分（bid_qc_pass_score，默认 9.5）才放行（严格大于）。
• 不通过：改进意见必填（缺什么/错在哪/对照原文哪一处）→ 系统清空该类产出物 → 对账器重派解析任务（params.qc_redo=1 + qc_improvements 携带意见）→ 重抽 → 重审。
• 轮次上限：单类审核超 bid_qc_max_round（默认 3）→ 抛 qc_escalation 阻塞人工任务。 逃逸阀：人工在产出物管理页修正后重新提交，或在审核记录页把该记录 passed 改 1 强制放行。
• 重做轮次上限：解析重做任务完成数超 bid_qc_max_round 且产出仍缺 → 同样抛人工，防无限循环。
• 首跑解析重试上限（MAX_ANALYST_ATTEMPT=2）只计首跑任务，QC 退回的重做不计入。
• 记录落 bid_qc_reviews（qc_type/round/fit_score/pass_score/passed/improvement）。

3.3 循环一：章节级评审回退

• 触发：review_chapter 判定 score / max_score < chapter_pass_ratio（默认 0.8）
• 动作：章节 status=rejected + review_comment 落库 + revise_count += 1
• 机制：存在 rejected 章节且无在办编写任务 → 对账器自动派生 agent.bid_writer 重写任务（params 带 chapter_id）
• 上限：revise_count > bid_max_revise（默认 3）→ 抛人类介入，不无限重做

3.4 循环二：整书评分回退

• 触发：score_bid 总分率 < bid_pass_ratio（默认 0.85），或存在否决项（is_veto）未响应
• 动作：bid_scores 逐评分项落分 + improvement + target_chapter_id
• 机制：把 target_chapter_id 命中的章节置 rejected → 派生 bid_writer 任务 → 重写 → 章节评审 → 全部通过 → 重新合成 → 重新评分
• 轮次记录 bid_reviews.round，上限 bid_max_round（默认 3）→ 抛人类介入
• 改进意见未映射到章节 → 抛人工指定（不静默丢失）

3.5 阻塞门禁（人类任务）

task_type	语义	阻塞范围
tender_file_upload	等待上传招标文件（上传后自动完成）	项目全部角色任务
human_docs_request	人类应提供的文件	项目全部角色任务
qc_escalation	解析产出 QC 连续不达标	项目全部角色任务
bid_delivery_confirm	最终标书交付确认	项目收尾（不阻塞派发）

门禁的守门位置：投标产线的角色任务唯一创建者是 bid_flow 对账器（每 15 秒状态对账）。 对账器在创建任务前就检查 pipeline_human_tasks.project_id = <项目id> AND status='pending'， 有阻塞任务直接不派 —— 门禁在创建源头，不在引擎派发层。

⚠️ 概念区分（重要）：tenant_id 是引擎的通用租户键（宿主可提供为 org_id / user_id 等）。 只有角色任务（pipeline_id='role_task'）这个具体场景约定 tenant_id = project_id。 这是角色任务派发机制的约定，不是引擎通用规则 —— 引擎层 SQL 不得引用该等价关系， 引擎对投标产线零特判；投标的阻塞语义全部收敛在投标产线自己的代码（bid_flow）里。

3.6 硬规则

• 章节写作任务与章节一对一（params.chapter_id），禁止一个任务写多章。
• 评审/评分只由 agent.bid_reviewer / agent.bid_scorer 执行，写作角色不得自评； 解析产出契合度审核只由 agent.qc 执行（capability 按角色缩小，源头杜绝越权）。
• 得分/改进意见必须落库（bid_reviews/bid_scores/bid_qc_reviews），不接受"文档里声称评审通过"。
• 案例与业绩一致性：技术方案引用的案例必须能对应到 bid_kb_docs(doc_type=case) 真实合同， 禁止虚构客户/金额（写进 bid-doc-spec 技能，评审项硬检查）。

---

四、数据表（bid_ 前缀，与 sd_/pipeline_ 表共库 pipeline）

表	说明	关键字段
bid_tenders	招标商务要素（解析抽取）	project_id/source/title/purchaser/tender_no/summary/bid_start_at/bid_deadline/project_period/budget_amount/deposit_amount/qualification_req
bid_members	项目参与人员	project_id/user_id/member_role/duty
bid_tender_files	招标文件及附件	project_id/tender_id/file_name/file_path/file_type/extract_status/content_text
bid_scoring_items	评分项 + 得分规则	project_id/section/item_name/max_score/scoring_rule/is_veto/target_chapter_no/source_ref
bid_qualifications	所需资质	project_id/qual_name/requirement/is_mandatory/kb_doc_id/match_status/owner
bid_doc_requirements	投标文件要求	project_id/req_type/chapter_no/chapter_title/requirement/page_limit
bid_qc_reviews	解析产出 QC 审核记录	project_id/qc_type/round/fit_score/pass_score/passed/improvement/task_id
bid_chapters	标书章节	project_id/chapter_no/title/scoring_item_ids/status/version/content/review_score/revise_count/assignee_role
bid_reviews	评审记录（章节级/整书级）	project_id/scope/chapter_id/round/reviewer/score/max_score/passed/comments
bid_scores	评分明细（按评分项）	project_id/review_id/scoring_item_id/score/max_score/reason/improvement/target_chapter_id
bid_kb_docs	公司投标知识库	org_id/doc_type/doc_name/tags/file_path/content_text/valid_until/status
bid_documents	合成标书	project_id/version/file_path/page_count/total_score/status

复用平台表：sd_projects（项目，pipeline_id=bidding_general）、pipeline_tasks（角色任务链）、 pipeline_human_tasks（人类任务）、pipeline_deliverables（交付件）、pipeline_agent_questions（问答冒泡）。

---

五、工具

5.1 主 agent（驾驶舱）工具 —— PipelineAbility.tools

立项与人员：create_bid_project assign_members list_members request_tender_file list_tender_files

解析结果与 QC：list_scoring_items list_doc_requirements list_qualifications qc_report

知识库：search_bid_kb list_kb_docs add_kb_doc request_human_docs

章节与标书：list_chapters chapter_detail list_bid_documents list_reviews bid_score_report

诊断推进：diagnose_bid advance_bid

通用复用（引擎级，来自 shared_ability）：create_task list_tasks task_detail approve_task complete_task cancel_task reset_task_retry start_agents diagnose_project list_deliverables view_deliverable list_questions answer_question escalate_question list_projects start_project complete_project archive_project pause_project resume_project list_role_models set_role_model submit_deliverable approve_deliverable reject_deliverable

5.2 角色 agent 能力工具（capability → TOOL_SCHEMAS）

capability	工具	授予角色
bid_analysis_capability	read_tender_file list_tender_files extract_from_file add_scoring_item add_qualification add_doc_requirement create_chapter_outline list_scoring_items list_doc_requirements mark_file_extracted	agent.tender_analyst
bid_qc_capability	start_qc finish_qc list_qc qc_report（+ 只读工具）	agent.qc
bid_kb_capability	search_bid_kb kb_doc_detail list_qualifications match_qualification mark_qualification_missing auto_match_qualifications request_human_docs	agent.bid_prep
bid_write_capability	list_chapters chapter_detail write_chapter submit_chapter search_bid_kb kb_doc_detail list_scoring_items	agent.bid_writer
bid_review_capability	review_chapter approve_chapter reject_chapter list_reviews list_chapters list_scoring_items list_doc_requirements	agent.bid_reviewer
bid_compose_capability	compose_bid list_chapters list_bid_documents read_bid_document list_doc_requirements	agent.bid_compositor
bid_score_capability	start_bid_score add_score_item_result finalize_bid_score request_chapter_revise read_bid_document list_scoring_items list_bid_documents bid_score_report	agent.bid_scorer

capability 按角色职责缩小 —— 写作角色拿不到 review_chapter/score_bid，评审角色拿不到 write_chapter， 解析角色拿不到 finish_qc，QC 拿不到 extract_from_file。越权在源头杜绝，不靠事后 RBAC 校验。

---

六、技能（skills_library/pipelines/bidding_general/）

common/（产线通用规范，状态机 + 门禁）

技能	内容
bid-workflow	产线总纲：阶段链、QC 门禁、两级循环、阻塞门禁、机制 vs LLM 分界
bid-qc	解析产出 QC 契合度审核规范：四类审核清单、10 分制打分口径、退回重做流程（capability 声明）
bid-chapter	章节状态机 + 评审循环 + 重做上限 + 一章一任务
bid-review	评审与评分规范：对照评分项/得分规则打分、改进意见→章节映射、否决项处理
bid-qualification	资质匹配规范：知识库检索 → matched/missing/human_required → 人类文件清单
bid-doc-spec	投标文件编写规范：章节骨架来自评分标准原文、操作层内容、案例与业绩一一对应、禁虚构
team-communication	问答冒泡链（复用开发产线同名规范）

roles/（角色定义，frontmatter 声明 capability）

agent.tender_analyst agent.bid_prep agent.bid_writer agent.bid_reviewer agent.bid_compositor agent.bid_scorer agent.qc agent.pm

---

七、代码落位

内容	位置	理由
能力模块（bid_*_capability / bid_flow / bid_common）	pipeline-bidding 仓库	产线能力包住自己仓库，宿主不装零接触
主 agent 能力包 bid_ability.py	pipeline-bidding 仓库	与能力模块同仓；ability 注册表在 core，任何模块可注册
表 / CRUD / UI / dspy / RBAC	pipeline-bidding 仓库	产线业务资产独立仓库，宿主 load_pipeline_bidding() 装载
技能	pipeline-core/skills_library/pipelines/bidding_general	技能库统一目录，部署期同步到机构工作空间
引擎改动	仅 exec_capability_tool 支持全路径 module（8 行）	引擎零投标特判

---

八、门限参数（appbase params 表 + DEFAULT_PARAMS 兜底）

参数	默认	含义
bid_chapter_pass_ratio	0.8	章节评审通过门限（得分率）
bid_pass_ratio	0.85	整书评分通过门限（得分率）
bid_max_revise	3	单章节最大重做次数
bid_max_round	3	整书最大评分轮次
bid_qc_pass_score	9.5	解析产出 QC 契合度通过分（10 分制，严格大于才放行）
bid_qc_max_round	3	单类产出 QC 最大审核轮次 / 解析重做轮次上限

---

九、验收口径

1. bid_* 12 张表建表成功，CRUD 页面可增删改查（含 bid_qc_reviews）。
2. 上传招标文件人类任务 pending 时，对账器不派发该项目任何角色任务（门禁生效）；上传后任务自动关闭。
3. 解析任务产出评分项/资质/投标文件要求/章节骨架后，对账器自动派 agent.qc 审核任务。
4. QC 审核得分 >9.5 → 该类放行进入下一阶段；≤9.5 → 该类产出被清空 + 解析重做任务携带改进意见（DB 可查）。
5. QC 轮次超限 → qc_escalation 阻塞人工任务创建，项目暂停派发。
6. 章节评审不达标 → 章节 rejected + 自动派生重写任务（DB 可查）。
7. 整书评分不达标 → bid_scores 有 improvement + target_chapter_id，命中章节回 rejected。
8. 全流程任务链在 pipeline_tasks 中可追溯（role 从 tender_analyst 到 bid_scorer，含 agent.qc）。