eric/bid-doctor
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
94c3bfd68810486bd1e91af76f1c45145b88bf70
bid-doctor/AGENTS.md
YANG JIANKUAN 94c3bfd688 docs(architecture): 新增技术架构设计 v0.2，记录选型决策 T2–T5、AR1–AR10 
- 架构文档：模块化单体 + 按负载拆进程；后端 Python（FastAPI），前端 Vue 3 + Vite 单页应用；PostgreSQL 做权威数据和任务队列（Procrastinate），Valkey 只存可丢数据；S3 / 本地磁盘存储；Compose 与 Helm 共用镜像；桌面端为客户端外壳
- 文档处理组件参考标擎的做法（§3.13）：转换服务、Docling、标书组装与两遍导出
- UI 不引入带样式框架，视觉自写，复杂交互用 Reka UI 打底（§4.3）
- decisions.md 记录 T2–T5、AR1–AR10；AGENTS.md 同步技术约束与进度

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 11:56:19 +08:00

16 KiB
Raw Blame History

AGENTS.md — 标博士（bid-doctor）

本文件是所有 AI 编码代理（Claude Code、Codex、Cursor 等）的共用项目说明。CLAUDE.md 只做引用，请只改本文件。

项目概况

  • 产品名：标博士（代码仓库名 bid-doctor）
  • 一句话定位：站在投标方一侧，贯穿「寻标 → 读标 → 写标 → 查标 → 投标」全生命周期的 AI 辅助工具。产品是「副驾驶」，不是「自动驾驶」。
  • 口号：标博士，你的AI投标专家（固定写法，见决策 B5）。
  • 当前阶段：需求分析、品牌与 VI 已完成，产品界面设计规范 v0.1、MVP 可点击原型 v0.1、技术架构设计 v0.2（选型已定，待技术验证 S1–S4）已完成，尚无代码。工作流：需求分析 ✅ → 主题 / 品牌设计 ✅ → 产品界面设计规范 ✅ → 原型设计 ✅ → UI 设计 → 技术架构 ✅ → 实现 → 测试。
  • 需求来源：当前有效版本是 docs/招投标AI工具PRD-v0.9.1.html（docs/招投标AI工具PRD.html 是 v0.9 原稿，保留作对照），再加上 docs/decisions.md 和 docs/analysis/ 里已确认的 MVP 细化需求。三者冲突时：decisions.md > analysis > PRD。发现矛盾或缺失时，记录问题并向用户确认，不要自行假设。
  • 工作语言：文档、界面文案、提交说明默认使用简体中文；代码标识符、文件名使用英文。

产品结构速览

模块 内容 MVP（P0）
M1 商机筛选 标讯聚合、订阅、AI 匹配打分、招标计划采集 否（P1/P2）
M2 招标文件解读 上传解析（PDF/Word/OCR）→ 资格 / 废标条款 / 评分点 / 关键日期结构化提取 → 原文回链 → 生成项目检查清单 是
M3 废标风险检查（楔子） 响应完整性、形式要件、资质匹配检查 → 人工逐项确认 → 检查报告 PDF 导出 是
M4 标书生成 目录框架、分章初稿、知识库填充、偏离表、Word 导出 否（V1）
M5 查重雷同 自有历史查重、多份互查、雷同风险报告 否（V1/V2，合规边界条款为 P0）
M6 基础平台 项目工作台、额度计量与账单（P0）；协作权限、资产库（P1）；私有化（P2） 部分

MVP 范围 = M2 全部 P0 + M3 全部 P0 + M6 项目工作台 + 额度计量 + 免费版 / 专业版。需求分析阶段确认新增：多包 / 多标段、最小资质库、报价形式检查、补遗追加（简化版）、最小运营后台。完整清单见 docs/analysis/03-functional-requirements.md。

首发行业是 IT 集成（D1）。IT 集成项目多数走政府采购体系（《政府采购法》、财政部令第 87 号），少数走招标投标体系。两套体系的术语不一样（投标无效 / 否决投标）、无效情形也不一样，产品要先识别项目属于哪一套，再套用对应规则。详见 docs/analysis/05-it-integration-domain.md。

核心数据设计：M2、M3、M4、M5 共用同一份「项目检查清单」数据结构——解读阶段提取的要求项，在写标阶段是生成约束，在投前阶段是核对项。任何建模与架构设计都必须围绕它展开。

项目状态流：跟进中 → 编制中 → 已检查 → 已递交 → 已归档。

必须遵守的产品红线

这些约束贯穿设计、文案与实现，评审时逐条核对：

  1. 辅助定位四件套（PRD 4.1）：辅助生成（产出标注为初稿）、检查清单（逐项列出、含原文出处）、人工确认（关键节点须逐项确认）、全程留痕（谁在何时确认了什么，可审计）。
  2. 可复核：每条 AI 提取 / 检查结论必须可回溯到原文（页码 + 原句高亮）；无出处的结果只能进「待确认」区或降级为「提示」。
  3. 禁用绝对化表述：界面、协议、营销文案中禁止「保证不废标」「零废标」「100% 通过 / 准确」等说法；M3 只能称「辅助检查 / 风险提示」，报告首页须写明检查覆盖范围。
  4. 不阻断用户：「致命」项未处理完时项目状态保持「未就绪」，但不阻止导出——决定权在用户。
  5. 不编造：资质、业绩、知识库引用只能来自用户自有数据；缺失处用占位符提示补录。胜率等数据不足时宁可不展示。
  6. 报价数字永不由系统生成或建议，只提供结构与填充位。
  7. 签章检查只做「位置与有无」提示，不做真伪鉴定，界面明示。
  8. M5 只服务投前自查：不得支持或宣传「帮多家投标人去雷同」等围串标规避用途。
  9. 额度即货币（PRD 4.3）：所有扣点规则可见、可查、可预警；解析失败 / 超时 / 系统异常不扣点；额度绑定账号与企业主体，不可转让。
  10. 数据敏感：传输与存储加密、按租户隔离、支持自助删除；SaaS 数据不用于训练公共模型。

政策引用的「双层口径」

先按项目所属的法律体系区分，再在体系内区分现行层和草案层（PRD v0.9.1 1.5）。政府采购项目的异常低价无效（87 号令第六十条）是现行规定，不能写成草案层，也不能挂「政策预警」标签。招标投标体系里引用政策时，严格区分两层，不得混同：

  • 现行依据层：发改法规〔2026〕195 号《关于加快招标投标领域人工智能推广应用的实施意见》——现行有效，但属政策指导文件而非法律。
  • 草案强化层：《招标投标法》修订草案——尚在审议、未施行，引用时必须标注。「政策预警」标签只用于草案层（如异常低价否决）。
  • 195 号文「2026 年底全覆盖」只指招标文件检测、智能辅助评标、围串标识别三个场景；本产品的楔子场景对应 2027 年底全国推广，对外不得混写。

待决策事项（PRD 第 12 章）

开工涉及以下事项时先向用户确认，不要默认：

  • D1 首发行业：✅ 已定为 IT 集成（2026-11-02，见 docs/decisions.md）。IT 集成项目多数走政府采购体系，术语和规则见 docs/analysis/05-it-integration-domain.md。
  • D2 专业版额度数字：解析 500 / 生成 300 为建议值，待成本实测定版。
  • D3 M1 商机数据来源：自建抓取 vs 第三方接口（V2 前决策）。
  • D4 企业版首单策略：是否提前准备私有化部署包。

需求分析阶段的待确认事项 G1–G10 已全部确认，见 docs/decisions.md A1。

技术约束（已定）

  • 大模型（T1）：只用国内云端的国产大模型，数据不出境。按场景路由：多模态（扫描件、签章）/ 快速 / 深度思考。业务代码只声明需要什么能力，不直接写死供应商和模型；每个 AI 任务都要记下模型和提示词版本。
  • 后端语言（T2）：Python 单语言，业务接口和后台任务是同一套代码、两种进程。
  • 桌面客户端（T3）：连服务端的客户端外壳，界面和网页版同一套；前端从第一天起守住 docs/architecture/architecture.md §5.2 的约束。
  • 部署（T4）：同一批镜像，两种编排（Docker Compose / Helm）；SaaS 内测期用 Compose，商用后切到托管 K8s。
  • 云厂商（T5）：暂不定，只依赖 PostgreSQL、S3 兼容的对象存储、OpenAI 兼容的模型接口。
  • 已确认的选型（AR1–AR3、AR5–AR9）：模块化单体；前端用 Vue 3 + TypeScript + Vite 单页应用；数据库 PostgreSQL；文件存储用 S3 协议 + 本地磁盘驱动；单一仓库。详见 docs/architecture/architecture.md 第 11 节。
  • Valkey（AR4）：只存丢了也没关系的数据（限速、验证码、推送、缓存）；权威数据（含会话、任务队列）都在 PostgreSQL。
  • UI 组件（AR10）：不引入带样式的 UI 框架（如 Element Plus），视觉自己写，样式只来自 tokens.css；复杂交互用无样式组件库 Reka UI 打底；不用 Tailwind。
  • 工程骨架搭好后，在本文件回填构建、运行、测试命令和目录结构。

品牌与设计资产（已定）

设计文档索引见 docs/design/README.md。做界面、文案、物料时先看这几条：

  • 视觉方向：A「校样」。蓝铅笔 #2F5BD3 = AI 标注 / 出处，墨 #1D2733 = 正文 / 人工确认，校样纸 #F5F6F3 = 底色。
  • 两种红色不能混用：印章红 #D9291C 只用于 logo；致命红 #C4122F 只用于界面里的致命问题。
  • 界面规范：docs/design/design-system.md；写界面代码时颜色、字号、间距只用 docs/design/system/tokens.css 里的变量。
  • 字体（均为 OFL，可免费商用）：思源宋体（标题、字标）、思源黑体 / 系统黑体（界面正文）、Libre Caslon（英文品牌字）、Barlow Semi Condensed（数字）。
  • Logo：正式文件在 docs/design/logo/svg/、png/。要改 logo，改 docs/design/logo/scripts/logo_lib.py 里的参数，再运行 scripts/build_assets.sh，不要手改 SVG。工具环境（logo/.work/）不进 git，搭建方法见 logo-spec.md 第 6 节。
  • VI 手册：docs/design/vi/标博士-VI视觉识别规范-v1.1.pdf，源文件是同目录的 vi-manual.html，重新导出方法见 docs/design/vi/README.md。logo 或口号变化后要同步重出。
  • 红线：logo 不能当作「通过 / 合格」章用在报告或任何结论上。

目录约定

docs/
  招投标AI工具PRD.html   # PRD v0.9 原稿（只读）
  招投标AI工具PRD-v0.9.1.html  # 当前有效版本；后续修订继续出新版本文件
  analysis/              # 需求分析：用户旅程、用例、数据模型草案、样本分析
  design/                # 品牌与设计（索引见 design/README.md）
    brand-strategy.md    #   品牌策略：定位、性格、口号、语气
    brand-directions.html#   三个视觉方向对比（已选 A 校样）
    logo/                #   logo 正式资产、规范、构建脚本、历史版本
    vi/                  #   VI 视觉识别规范（PDF + HTML 源文件）
    design-system.md     #   产品界面设计规范：原则、颜色、字体、组件、文案
    system/              #   tokens.css（设计变量）、components.css（组件样式）、components.html（预览）
  prototype/             # MVP 可点击原型（HTML，说明见 prototype/README.md）
  architecture/          # 技术架构、ADR（docs/architecture/adr/NNNN-*.md）
  decisions.md           # 产品与工程决策记录（含 D1–D4 的拍板结果）
samples/
  tenders/               # 真实招标文件样本（README 是清单；原始文件不进 git，用 fetch.sh 获取）

以上目录按阶段推进时再创建，不要提前建空目录。代码目录结构在技术架构确定后补充到本文件。

参考开源项目（opensource-ref/）

opensource-ref/ 放的是别人的开源项目，只供用户本人对照参考，不属于本项目，已在 .gitignore 中忽略。

  • opensource-ref/bid-engine/：标擎 BidEngine（github.com/panviviplus/bid-engine），招投标 AI 工作台，Go + Next.js。
  • 不参与本项目的编码、文件查找和逻辑：搜索代码、排查问题、设计架构、写需求时都排除这个目录；不要引用、复制或改写其中的代码、提示词、SQL 和文案，也不要把它的设计当作本项目的既定做法。用户明确要求「看一下参考项目」时才去读，读到的内容只作为讨论素材，结论仍以本项目的 decisions.md / analysis / PRD 为准。
  • 许可证：PolyForm Noncommercial 1.0.0，只允许非商业用途；本产品是商业产品，其代码不能进入本项目。
  • 已清理掉其中与本项目无关的工程化文件（嵌套的 .git、.gitignore、.gitkeep、.DS_Store、它自带的 AGENTS.md、ESLint / Prettier 配置、第三方库的 CI 配置）；保留了运行它所需的 .env*、.npmrc、Dockerfile、docker-compose 和启动脚本，以及 LICENSE / NOTICE。

工作方式

  • 每个阶段产出落到 docs/ 对应目录，并在本文件「当前进度」中更新一行。
  • 用户确认的决策写入 docs/decisions.md（日期 + 决策 + 理由），不要只留在对话里。
  • 设计与文案产出提交前，对照上方「产品红线」自查一遍。
  • 技术栈确定后，在本文件补充：构建 / 运行 / 测试命令、代码规范、目录结构。

当前进度

  • 2026-11-02：项目初始化，建立 AGENTS.md / CLAUDE.md。
  • 2026-11-02：D1 定为 IT 集成；完成 MVP 需求分析（docs/analysis/）。
  • 2026-11-02：G1–G10 全部按建议确认；出 PRD v0.9.1（补充政府采购体系）；大模型策略定为国产云端模型 + 按场景路由（T1）。
  • 2026-11-02：从苏采云公开渠道收集了 10 份 IT 集成采购文件（samples/tenders/），分析结论见 docs/analysis/07-sample-findings.md。关键结论：实质性条款不能只认 ★（有的用斜体 + 下划线标注，解析时必须保留文字格式）；文件扩展名不可信；报价限价有三层。
  • 2026-11-02：品牌与 VI 完成。
    • 品牌策略：定位「投前审校员」，口号「标博士，你的AI投标专家」（B5）；视觉方向选 A「校样」（B1）。
    • Logo v5.1：AI 生成的白文印「标」+ 思源宋体 SemiBold / Libre Caslon 字标，比例 H2、英文视觉内缩 C2（B3、B4）。中间经历的 v1–v4（Codex 精细化、SVG 程序化模拟印泥）归档在 docs/design/logo/archive/，教训见 logo/seal-research.md：印泥质感本质上是位图，不要再用 SVG 程序化模拟。
    • VI 视觉识别规范 v1.1（A4 横版 24 页，含名片、信封、信纸、报告、演示文稿、网站等应用），见 docs/design/vi/。
  • 2026-11-02：产品界面设计规范 v0.1（docs/design/design-system.md + system/tokens.css + system/components.html）。要点：红色只给致命问题（表单错误、额度、截止临近都用赭色）；问题级别靠实心 / 描边 / 无框区分，不只靠颜色（色弱模拟验证过）；字体全部自托管；出处是固定组件。U1–U4 全部按建议确认（只做桌面 Web、图标用 Lucide、致命问题确认无误也要写说明）。
  • 2026-11-02：MVP 可点击原型 v0.1（docs/prototype/，13 个页面，覆盖 J1–J5）。中保真，直接用设计规范的组件；查标页可逐条处理、键盘操作、看原文。原型阶段的 P1（24 小时免扣从上一次扣点的检查算起）、P2（人工核对勾选按项目保存）已按建议确认。
  • 2026-11-03：应用图标改为印泥铺满、不留白边，圆角按 Apple 连续曲率圆角由系统裁（B6）；VI 手册 v1.1 第 22 页改为 iPhone 18 Pro 主屏幕模拟（docs/design/vi/mockup/，Apple 素材不进 git，机身需本人同意 Apple Design Resources 许可后放入）。
  • 2026-11-03：分析参考项目标擎 BidEngine 的架构、提示词和模型路由，整理出可参考的做法和避坑清单（docs/architecture/ref-bid-engine-analysis.md），留给技术架构阶段用。
  • 2026-11-03：技术架构设计 v0.2（docs/architecture/architecture.md）。T2–T5 已确认：Python 单语言、桌面端做客户端外壳、SaaS 先 Compose 后 K8s、云无关。之后确认了 AR1–AR3、AR5–AR9，前端改为 Vue 3；AR4 复议后改为引入 Valkey（已确认）；AR10 定为不引入带样式的 UI 框架，用 Reka UI 打底。选型全部确认。编码前先做技术验证 S1–S4。
  • 下一步：用原型找种子用户走查（顺带问 G15 苏采云客户端的分册对应），再进入 UI 设计精修。