pipeline-bidding/docs/DESIGN.md

投标产线（bidding_general）设计文档

对照开发产线（sdlc_general）设计，复用平台通用内核（项目/会话/任务链/人类任务/交付件/问答冒泡/技能分层）， 只增量定义投标产线自己的 阶段、角色、工具、技能、任务流转规则、交付件。

版本：v1.0.0　　创建：2026-08-26

---

一、业务流程（需求原文映射）

#	业务动作	承担者	落库
1	从 yumoqing@opencomputing.cn（阿里云企业邮）获取招标信息	agent.tender_scout	bid_tenders
2	对每条招标信息内容摘要：投标开始时间、项目周期、招标金额等	agent.tender_scout	bid_tenders.summary/bid_start_at/project_period/budget_amount
3	走审批流程	人（human task + 可选钉钉审批）	pipeline_human_tasks(task_type=tender_approval)
4	审批不通过 → 招标信息存档作废	机制	bid_tenders.status=archived
5	审批通过 → 创建项目	机制/主 agent	sd_projects(pipeline_id=bidding_general)
6	设定参与人员	主 agent / 人	bid_members
7	等待上传招标文件	人（阻塞门禁）	pipeline_human_tasks(tender_file_upload) + bid_tender_files
8	从招标文件抽取评分项及得分规则	agent.tender_analyst	bid_scoring_items
9	抽取所需资质	agent.tender_analyst	bid_qualifications
10	抽取投标文件要求（章节结构/格式/份数/密封）	agent.tender_analyst	bid_doc_requirements
11	从公司投标知识库获取所需资质文档	agent.bid_prep	bid_qualifications.kb_doc_id ← bid_kb_docs
12	发布人类应提供的文件清单	agent.bid_prep（阻塞门禁）	pipeline_human_tasks(human_docs_request)
13	按投标文件要求分章节编写投标文件	agent.bid_writer	bid_chapters
14	每章节完成后对照招标/投标文件要求评审，分数不够给改进意见重做	agent.bid_reviewer	bid_reviews(scope=chapter) → 章节循环
15	合成标书	agent.bid_compositor	bid_documents（docx）
16	对整个标书评审 + 按评分项和得分规则打分	agent.bid_scorer	bid_reviews(scope=whole) + bid_scores
17	不合适 → 改进意见 → 修改问题章节 → 评审 → …… 直到得分通过	机制（整书循环）	bid_scores.target_chapter_id → 章节回 rejected

---

二、阶段与角色（对照开发产线）

开发产线	投标产线	角色规范名	职责	next_role
requirement 需求分析	招标情报	agent.tender_scout	收邮件、去重入库、摘要与要素抽取、提交审批	agent.tender_analyst
—（新增门禁）	招标审批	人类任务	审批通过立项 / 不通过存档作废	—
design 设计	招标文件解析	agent.tender_analyst	抽取评分项+得分规则、所需资质、投标文件要求，产出章节骨架	agent.bid_prep
—（新增）	资料准备	agent.bid_prep	知识库资质匹配、缺失项发布人类文件清单	agent.bid_writer
develop 开发	章节编写	agent.bid_writer	按章节骨架逐章写作（一章一任务）	agent.bid_reviewer
test 测试	章节评审	agent.bid_reviewer	对照招标要求+得分规则逐章打分，不达标退回重写	agent.bid_compositor
—（新增）	标书合成	agent.bid_compositor	合成 docx（封面/目录/页码/偏离表），产出交付件	agent.bid_scorer
deploy 部署	全书评分	agent.bid_scorer	按评分项+得分规则给整书打分、生成改进意见并映射章节	""（终结→人类交付确认）
agent.pm	同名复用	agent.pm	任务审核/派发/验收	—
agent.qc	同名复用	agent.qc	交付件合规检查	—

角色命名遵守平台规范：agent 角色 = agent.{role}，人类角色 = RBAC {orgtype}.{role}。 同名角色跨产线隔离（按 pipeline_id 查 RoleSpec），agent.pm/agent.qc 在两产线各有自己的技能与提示词。

---

三、任务流转规则

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

[邮箱] --fetch_tenders--> bid_tenders(new)
    --summarize_tender--> summarized
    --submit_tender_approval--> pending_approval  ┌── reject ──> archived(作废) ✗终止
                                                  └── approve ──> approved
    --create_bid_project--> sd_projects + assign_members
    --request_tender_file--> [人类任务:上传招标文件] (阻塞)
        ↓ 上传完成
    agent.tender_analyst  → 评分项 / 资质 / 投标文件要求 / 章节骨架
        ↓ approved (PM)
    agent.bid_prep        → 知识库资质匹配 + [人类任务:应提供文件清单](阻塞)
        ↓ approved
    agent.bid_writer      → 逐章写作（每章一个任务，可并行受并发上限约束）
        ↓ 章节 written
    agent.bid_reviewer    → 章节评审打分
        ↓ 全部章节 approved
    agent.bid_compositor  → 合成标书 docx
        ↓
    agent.bid_scorer      → 整书评分
        ↓ 通过
    [人类任务:交付确认] → 项目 completed

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

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

3.3 循环二：整书评分回退

• 触发：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.4 阻塞门禁（人类任务）

task_type	语义	阻塞范围
tender_approval	招标信息审批	该 tender 不立项、不推进
tender_file_upload	等待上传招标文件	项目全部角色任务
human_docs_request	人类应提供的文件	项目全部角色任务
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 （与开发产线的既有任务创建约定一致，_create_next_task 同款）。 这是角色任务派发机制的约定，不是引擎通用规则 —— 引擎层 SQL 不得引用该等价关系， 引擎对投标产线零特判；投标的阻塞语义全部收敛在投标产线自己的代码（bid_flow）里。

3.5 硬规则

• 审批不通过 = 终态（archived），不得再进入立项；需重新评估须人工 reopen_tender。
• 章节写作任务与章节一对一（params.chapter_id），禁止一个任务写多章（对照开发产线「单任务不要过大」）。
• 评审/评分只由 agent.bid_reviewer / agent.bid_scorer 执行，写作角色不得自评（源头杜绝越权：capability 按角色缩小）。
• 得分/改进意见必须落库（bid_reviews/bid_scores），不接受"文档里声称评审通过"。
• 案例与业绩一致性：技术方案引用的案例必须能对应到 bid_kb_docs(doc_type=case) 真实合同，禁止虚构客户/金额（写进 bid-doc-spec 技能，评审项硬检查）。

---

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

表	说明	关键字段
bid_mail_accounts	招标邮箱配置（凭据不写死代码）	protocol/host/port/username/password(AES)/folder/filter_keywords/last_uid/enabled
bid_tenders	招标信息	mail_uid/subject/received_at/raw_content/title/purchaser/tender_no/summary/bid_start_at/bid_deadline/project_period/budget_amount/deposit/qualification_req/status/project_id
bid_members	项目参与人员	project_id/user_id/member_role/duty
bid_tender_files	招标文件及附件	project_id/tender_id/file_name/file_path/file_type/extract_status
bid_scoring_items	评分项 + 得分规则	project_id/section/item_name/max_score/scoring_rule/is_veto/weight/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_chapters	标书章节	project_id/chapter_no/title/scoring_item_ids/status/version/content/file_path/review_score/review_comment/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

招标情报：fetch_tenders list_tenders tender_detail summarize_tender submit_tender_approval approve_tender reject_tender archive_tender reopen_tender

立项与人员：create_bid_project assign_members list_members request_tender_file list_tender_files

解析结果查看：list_scoring_items list_qualifications list_doc_requirements

知识库：search_bid_kb list_kb_docs add_kb_doc request_human_docs

章节与标书：create_chapter_outline list_chapters chapter_detail compose_bid list_bid_documents

评审评分：list_reviews bid_score_report

通用复用（引擎级，来自 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_tender_capability	fetch_tenders summarize_tender set_tender_fields submit_tender_approval archive_tender list_tenders	agent.tender_scout
bid_analysis_capability	add_scoring_item add_qualification add_doc_requirement create_chapter_outline list_scoring_items list_doc_requirements mark_file_extracted	agent.tender_analyst
bid_kb_capability	search_bid_kb match_qualification mark_qualification_missing request_human_docs list_qualifications	agent.bid_prep
bid_write_capability	list_chapters chapter_detail write_chapter submit_chapter list_scoring_items search_bid_kb	agent.bid_writer
bid_review_capability	review_chapter reject_chapter approve_chapter list_chapters list_scoring_items list_doc_requirements	agent.bid_reviewer
bid_compose_capability	compose_bid list_chapters list_doc_requirements	agent.bid_compositor
bid_score_capability	score_bid add_score_item_result request_chapter_revise list_scoring_items list_bid_documents	agent.bid_scorer

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

---

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

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

技能	内容
bid-workflow	产线总纲：阶段链、门禁、两级循环、回退语义、机制 vs LLM 分界
tender	招标信息状态机：new→summarized→pending_approval→approved/rejected→archived
bid-chapter	章节状态机 + 评审循环 + 重做上限 + 一章一任务
bid-review	评审与评分规范：对照评分项/得分规则打分、改进意见→章节映射、否决项处理
bid-qualification	资质匹配规范：知识库检索 → matched/missing/human_required → 人类文件清单
bid-doc-spec	投标文件编写规范：章节骨架来自评分标准原文、操作层内容、案例与业绩一一对应、禁虚构
team-communication	问答冒泡链（复用开发产线同名规范）

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

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

---

七、代码落位

内容	位置	理由
主 agent 能力包 bid_ability.py	pipeline-service	与 sdlc_ability 同构；ability 注册表在 core，任何模块可注册
角色能力工具 bid_*_capability.py	pipeline-service	exec_capability_tool 只 import pipeline_service.*
邮箱采集 bid_mail_fetcher.py	pipeline-service	被能力工具调用
通用任务 handler 汇总 shared_ability.py	pipeline-service	复用而非重写 SDLC 的通用任务/交付件/问答 handler
表 / CRUD / UI / dspy / RBAC	pipeline-bidding（新模块仓库）	产线业务资产独立仓库，宿主 load_pipeline_bidding() 装载
技能	pipeline-core/skills_library/pipelines/bidding_general	技能库统一目录，部署期同步到机构工作空间

---

八、验收口径

1. bid_* 12 张表建表成功，CRUD 页面可增删改查。
2. fetch_tenders 真连阿里云企业邮 IMAP 取到邮件并入库（凭据来自 bid_mail_accounts）。
3. summarize_tender 真调 LLM 产出摘要与 5 要素并落库。
4. 审批不通过 → tender 状态 archived；通过 → sd_projects 出现 pipeline_id=bidding_general 的项目。
5. 上传招标文件人类任务 pending 时，poller 不派发该项目 agent 任务（项目级门禁生效）。
6. 章节评审不达标 → 章节 rejected + 自动派生重写任务（DB 可查）。
7. 整书评分不达标 → bid_scores 有 improvement + target_chapter_id，命中章节回 rejected。
8. 全流程任务链在 pipeline_tasks 中可追溯（role 从 tender_scout 到 bid_scorer）。