yumoqing b40f54d63f feat(bidding v1.2): 编写分商务/技术角色+篇幅门禁+样板标书规范+并发编写
- 章节按section分流: business→agent.bid_biz_writer(新角色), technical/price→agent.bid_writer
- 骨架生成自动推断section(_infer_section标题关键词)
- 篇幅门禁机制层强制: review_chapter字数低于门限必退+自动附意见
  (参数bid_chapter_min_words=800/bid_chapter_min_words_biz=500)
- 并发编写: 对账器单轮最多派bid_write_concurrency(4)个编写任务
- 样板标书: bid_kb_docs doc_type=sample_bid码值; extract_writing_spec工具
  (PM抽章节结构/篇幅口径/表格图示/商务要素, 落bid_doc_requirements writing_spec)
- DESIGN.md v1.2
2026-08-31 15:40:03 +08:00

292 lines
20 KiB
Markdown
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 投标产线bidding_general设计文档
> 对照开发产线(`sdlc_general`)设计,复用平台通用内核(项目/会话/任务链/人类任务/交付件/问答冒泡/技能分层),
> 只增量定义投标产线自己的 **阶段、角色、工具、技能、任务流转规则、交付件**。
> 版本v1.2.0  创建2026-08-26  修订2026-08-31v1.1 上传招标文件起点+QC 门禁v1.2 编写分商务/技术角色+篇幅门禁+样板标书规范+并发编写)
---
## 零、产线边界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_documentsdocx |
| 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.qcA2 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 连续不达标 | 项目全部角色任务 |
| `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 硬规则
- 章节写作任务与章节一对一(`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` 支持全路径 module8 行) | 引擎零投标特判 |
---
## 八、门限参数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