# 投标产线（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）。