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