# 投标产线（bidding_general）设计文档

> 对照开发产线（`sdlc_general`）设计，复用平台通用内核（项目/会话/任务链/人类任务/交付件/问答冒泡/技能分层），
> 只增量定义投标产线自己的 **阶段、角色、工具、技能、任务流转规则、交付件**。
> 版本：v1.6.0　　创建：2026-08-26　　修订：2026-09-17（v1.1 上传招标文件起点+QC 门禁；v1.2 编写分商务/技术角色+篇幅门禁+样板标书规范+并发编写；v1.6 标准流程技术标模版裁剪链 A3 段，见 3.7）

---

## 零、产线边界（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 / agent.bid_biz_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_biz_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      → 逐章写作（每章一个任务，可并行）
    （section=business 的章节派 agent.bid_biz_writer，其余派 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 连续不达标 | 项目全部角色任务 |
| `tech_template_confirm` | 技术方案骨架用户确认（标准流程 A3 段链激活时；2026-09-17 起从全局阻塞降级为**章节级**：只挡 technical 章，商务/报价章照常） | technical 章节编写 |
| `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 编写分角色、篇幅门禁与并发（v1.2 新增）

**分角色**：章节按 `bid_chapters.section` 分流——
- `business`（投标函/报价/资质证明/承诺/业绩，骨架生成时按标题关键词自动推断）→ `agent.bid_biz_writer`；
- `technical`/`price` → `agent.bid_writer`。
- 两类内容不混写；capability 共用 `bid_write_capability`（工具白名单相同，角色技能不同）。

**篇幅门禁（机制层强制，review_chapter 内）**：
- 技术标章节字数 < `bid_chapter_min_words`（默认 800）或商务标 < `bid_chapter_min_words_biz`（默认 500）
  → 直接不通过 + 自动附「篇幅不达标」意见；与得分率门限取并集。
- 内容完整性由评审员按 bid-doc-spec 查（评分子维度漏应答/商务要素缺失 = 退）。

**搜不到 → 冒泡**：写者检索知识库无所需素材/案例/参数时 ask_question 冒泡人类，禁编造凑字数。

**样板标书规范**：`bid_kb_docs.doc_type=sample_bid`；PM 调 `extract_writing_spec` 抽取
章节结构惯例/篇幅口径/表格图表示例/商务要素清单，落 `bid_doc_requirements(req_type=writing_spec)`，
写者与评审参照。无样板时提示人工录入。

**并发编写**：对账器 C 块单轮最多派 `bid_write_concurrency`（默认 4）个编写任务；
引擎 agent poller 另有每项目并发上限 `max_agents_per_project`（默认 4）兜底，任务间 asyncio 并发执行。

### 3.7 标准流程技术标模版裁剪链（A3 段，v1.6 新增）

标准投标流程内置与纯技术方案流程**同源**的三段链，产出标书「技术方案部分」：

```
tech_analysis（agent.tender_analyst，analysis_dim=tech，六类技术评估项落 bid_tech_items，
               对标招标文件技术需求部分）
    ↓
tech_qc（agent.qc，qc_type=tech_items，对标招标原文，10 分制同款门禁）
    ↓
template_confirm（agent.pm，task_kind=tech_template：find_template_candidates 三级检索
    → propose_tech_template 骨架六类覆盖硬校验 → tech_template_confirm 用户确认待办）
    ↓ 用户确认（confirm_tech_template 标准模式）
只替换 technical 章骨架（新章落原技术章 min(order_no) 位置，商务/报价章不动）
+ 落 kind='summary' 裁剪摘要行 → 技术章解禁开写
```

**链激活五条件**（bid_flow A3 段，任一不满足整链跳过 = 存量行为，技术章直接按招标骨架编写）：
1. 有招标文件（n_files > 0）且章节骨架已生成；
2. `tech_analysis` + `template_confirm` 两阶段都启用（BID_FLOW_STAGES 14 阶段，
   裁 tech_analysis 必连带裁 template_confirm——依赖断裂校验拒绝单裁）；
3. 骨架维度 QC 已通过（QC_TYPE_OUTLINE ∈ _qc_passed_eff——outline 重做会清空
   bid_chapters，防把已确认模版骨架连锅端）；
4. 项目存在 technical 章节且全部 pending（任一 writing/written/approved = 已按原骨架
   推进或存量项目，不激活）；
5. 无裁剪摘要行（`bid_tech_items kind='summary'`，confirm 时落库、新招标文件 reset 时清除）。

**完成判定定案用摘要行**，不用 done 待办或章节状态：换代后旧 done 待办仍在会永久锁死
新代链；替换后的新骨架也是 pending，靠章节状态判完成会复活死循环。

**门禁语义**：链激活时 C 段只挡 technical 章（`_tech_gate_on`），商务/报价章照常流转——
`tech_template_confirm` 待办已从全局阻塞降级为章节级依赖（bid_common BLOCKING/HT 定义同步）。

**共用段实现**：`_reconcile_tech_analysis_qc`（T1/T2：评估项派发+QC+升级）与
`_reconcile_template_confirm`（T3：模版任务派发+确认待办补发+驳回重派）——纯技术方案分支
`_reconcile_tech_proposal` 重构为调共用段，逻辑只此一份；`flow_key` 写进任务 params 区分来源。
`confirm_tech_template` 按「项目是否存在非 technical 章」自动分流标准/纯技术方案双模式，
重确认守卫收窄到待替换范围。**tech 维度不进 ANALYSIS_DIMS、不走 PM 编排**（对账器直接派发，
避免编排误派/掉链误判）。新招标文件导入 reset：清 bid_tech_items + 作废 pending 骨架确认待办。

### 3.8 硬规则

- 章节写作任务与章节一对一（`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 最大审核轮次 / 解析重做轮次上限 |
| `bid_chapter_min_words` | 800 | 技术标章节最低字数（低于评审必退） |
| `bid_chapter_min_words_biz` | 500 | 商务标章节最低字数 |
| `bid_write_concurrency` | 4 | 章节编写单轮并发派发上限 |

---

## 九、验收口径

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）。