business-assistant/docs/architecture.md

技术现状与目标边界

当前事实

• 2026-09-15最新三类约定（F034）：仅闲聊smalltalk、政策了解policy_overview、具体需求specific_need。闲聊含身份、能力和使用方式介绍，由LLM依据现有角色信息自主回答，不检索或推荐政策；政策了解检索知识库，包含QA；具体需求按需画像、需求拆解、检索与适用性分析后依据原文回答。一般事实咨询归知识问答；无依据与服务失败分别说明，QA答案不因缺少卡片丢弃。

• pyproject.toml：项目名 business-assistant，版本 1.0.0，Python >=3.14；声明tokenizers用于离线token统计，以及torch、transformers、pymilvus用于第二步本地Embedding与Milvus入库，依赖已锁定。F011 规整仍只使用标准库。

• uv 默认包索引为清华 PyPI 镜像，使用项目级 [[tool.uv.index]] 配置；不修改全局 pip 设置。

• 已有第一步知识整理、第三步公司确认画像CLI、政策检索与推荐；第四步 src/step4_api/ 当前注册POST /api/chat（SSE）、POST /api/company/classify（JSON）与GET /health。聊天请求可带附件链接，返回阶段状态、正文增量、来源/卡片和最终快照；分类接口接收已取得的company_info。单进程有界线程池复用图、Redis与模型，问答和分类共享内存接纳限制。生产鉴权、多副本及真实问答容量待验收。已建立 uv.lock、Python冒烟与初始化回归，现有 .venv 为Python 3.14.5。接口字段以聊天接口及分类接口为准。

• 沙箱内 Python 执行被权限限制，获准的沙箱外版本检查及初始化通过；不能据此把环境判为损坏。

• Qwen Embedding 已在第二步接入；reference/ 已全量规整为 knowledge/prepared/ 四类 JSONL 和 Markdown，保留原始字段、来源定位及质量标记。模板契约见 knowledge/templates/README.md，第二步建立分类型索引，政策有效性仍未核实。

• F013 的 summarize.py 使用用户DeepSeek配置、五场景提示词、JSON结束状态校验、token截断翻倍重试、SQLite逐条缓存及增强JSONL导出；Qwen Embedding由第二步接入。官方DeepSeek tokenizer用于本地预算预检。

• init.ps1 默认进行环境同步与检查，-CheckOnly 仅验证 Harness，-Offline 禁止联网。未变更原 Python 版本要求。

目标数据流（已实现基础链路，质量与生产能力待验收）

用户实际困难 + 可用会话上下文（无需政策名称）
          ↓
需求识别 + 个人/企业/交叉主体识别 → 按需消歧与获取相关画像
          ↓
保留原问题 + 查询拆解 → 按manifest跨一个或多个知识库召回
          ↓                         ↑
候选原文与适用条件核验 → 有界扩展检索或必要补问
          ↓
有证据的建议 + 来源引用 + 待确认条件

建议边界：入口/会话、公司信息适配器、知识入库、检索、回答编排、外部模型客户端。 正式代码以后放 src/，回归放 scripts/tests/，集成验证入口放 scripts/。 完整问答链路仍为目标；Agent框架已按用户要求采用LangGraph，向量数据库采用Milvus。

F005为后续重点：检索端消费原问题、需求、相关主体事实及未知项，返回候选原文、条款判断与补问需求；F006负责据此生成建议。检索方向是模型假设，政策存在性与资格必须由证据支持。个人画像接口未实现，不能沿用“所有问题先获取公司”的前置条件。具体功能与评测顺序见 政策发现功能与验收。

跨模块约定方向

• 公司上下文携带稳定身份、属性、来源、获取时间、未知项；检索和回答消费同一份上下文。
• 知识片段携带文档/片段标识、来源定位和可获得的发布/生效/失效、适用范围元数据。
• 回答可区分公司事实、知识事实与推断，引用必须指向实际参与生成的证据。
• 请求关联 ID 支持失败定位；公司缓存按身份隔离，索引与模型版本变化应可追踪。
• 日志不默认记录完整问题、画像、知识正文或密钥；重试有界，失败不伪装成成功。
• 测试使用固定合成公司、文档、时间和服务替身；真实服务验证另外保存脱敏结果。

实际协议随 Feature 实现和验证后在这里更新。F009 完成环境初始化修正，F002 后续聚焦最小业务运行入口与对应测试。已有锁文件先检查再冻结同步；保留原环境额外包，不自动重建环境。

第二步知识入库（F015）

独立CLI位于 src/step2_knowledge_ingest/；Qwen本地模型通过torch/transformers加载，pymilvus连接用户指定服务。按五场景、QA、目录共七类分别建数据库；全文存储段与标题摘要语义索引分集合。完整字段逐条回读校验，模型与数据哈希组成不可变快照，成功后发布本地manifest。F018检索端已按manifest选择数据库/索引并回溯完整记录；旧快照不自动删除。详见 入库协议。

第三步问答框架（F017）

新增LangGraph StateGraph和InMemorySaver，需求识别复用DeepSeek，企查查按886候选检索、interrupt等待确认、410身份核对、1001有界分页构建画像。来源携带接口、获取时间、确认KeyNo及页码，原问题完整交接。F018已扩展政策召回、引用校验与分析节点；生产持久化、自动跨轮公司继承及多公司联合分析待实现。代码、配置与边界见 第三步框架。

F018新增retrieval.py、recommendation.py和report.py：按manifest使用原问题及最多2条扩展查询六库，完整记录分段回读并校验哈希；LLM逐条基于原文分析，引用必须逐字存在；企业与个人均返回完整记录和本地可查看来源。预算、未知资格与真实验证边界见 第三步实现。此前第三步仅画像的说明为F017历史边界，现已由F018扩展。