business-assistant

营商助手（Business Assistant）

断网银河麒麟V10服务器使用项目资料包、ARM64 CPU环境包及deploy-offline.sh；目标机为aarch64/glibc 2.28，Python 3.14由部署同事安装。F152已为缺少pidfd接口的环境增加核对进程身份后发送PID信号的重启兼容，现场替换后停启仍待验证。两个交付包已生成并校验，目标机安装尚未完整验证；现场操作以最新部署操作指南为准。现有deploy.sh保留联网部署流程。

当前HTTP接口

服务入口为python -m src.step4_api，目前注册POST /api/chat及POST /api/talent/chat（JSON请求、SSE响应）、POST /api/company/classify（JSON请求与响应）和GET /health（启动就绪响应）。聊天支持可选图片/文件数组、附件处理状态、正文增量事件与最终结果快照；前端应以answer_end替换临时正文。/health不表示外部依赖实时健康。请求字段、错误码及前端消费规则见聊天接口、第四步服务说明和公司分类接口。

目标：用户描述个人或企业的实际困难，无需知道政策名称；助手识别需求，按需补充主体信息，主动寻找政策与配套服务，核验适用条件后给出有引用的建议。

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

当前状态

人才客服137条知识（31服务、15QA、91事项关联22篇原文）使用独立准备目录和 talent_knowledge 前缀；QA按问题、其他按标题加摘要索引。离线包指定 --agent talent 导入，见人才知识说明。独立流式接口为 POST /api/talent/chat，请求/事件沿用营商接口，角色、三库和会话隔离，启用及验证边界见人才接口。

原始知识按Agent分目录保存：现有营商助手的15份资料位于 reference/营商助手/，默认知识整理仅读取此目录；其他Agent后续使用同级独立目录。已有知识ID和逻辑来源标识保持，详见原始资料目录。

2026-09-24 F117：新增青浦区介绍与新闻998条基础知识，已规整、生成LLM摘要并写入Milvus新快照4231条；独立复验与在线重启状态见知识整理及知识入库。新闻仅作原文证据，历史措施不自动视为现行政策。

2026-09-24 F116：惠企政策源已替换为25个政策、170个事项，原文与新字段完成规整；170条LLM摘要生成，Milvus新快照3233条独立回读通过。其他3063条摘要保持，旧集合保留；在线服务需重启读取新manifest，真实问答和政策有效性未验收。见知识整理与知识入库。

2026-09-24 F115：列举多个办理情形时，按已核验指南的结构化关联项有界补查同事项同区划的独立原文，真实Milvus同问题取得五份各带URL的指南；链接映射漏项可按情形名称补齐。用户授权后的真实模型固定五来源回放返回五链接，314项问答、96项API及离线基线通过；在线候选分析全链路、前端及重启后效果待验证。见第三步说明。

2026-09-23 F114：知识原文的image-scope图片可在对应正文位置返回，模型选位置、程序按已采用来源绑定，最终text供前端就地渲染。目标知识真实Milvus回读及模型输出、311项问答和96项API通过；需重启，图片实际渲染待前端联调。见接口文档。

2026-09-23 F113：办事指南情形名称随分块分析与综合传递，链接带具体事项及情形；只问时限等细节直接回答该项。历史问答三份指南的两组真实模型回放仅采用延续来源，304项问答回归通过；实时召回及前端待复验，需重启。见答复规范。

2026-09-23 F111：任一图片/文件下载、格式或读取失败立即结束本轮；SSE错误或HTTP 422指出具体附件，不再基于部分附件分类、检索或回答。合成回归通过，需重启并做真实附件/前端联调。见附件接口。

2026-09-22 F104：新增问答/分类/后台共享内存接纳，默认4个名额，RSS预算及系统余量不足时拒绝或延后；Linux附件解析限额与systemd硬隔离生成入口已实现。需重启及在服务器安装unit才启用硬隔离，未生产容量/OOM验收。见内存保护。

2026-09-22 F103：最终输出预留默认在4096–8192内按输入剩余空间动态调整，实际max_tokens同步，明显超长保留中间整理；独立副本保持并发隔离。300项问答、82项API通过，需重启后评估真实长答质量与耗时。见综合预算。

2026-09-22 F102：会话状态改为Lua原子定向读取最新/指定检查点及对应pending writes，避免历史正文回传；旧hash兼容，历史及恢复保留。296项问答、82项API及真实Redis合成验证通过；需重启后采集实际耗时，见Redis读取诊断。

2026-09-22 F100：综合输入去除完全重复证据项，最终输出预算独立配置为ANSWER_MAX_OUTPUT_TOKENS，当前8192；全文分析/中间整理保持16384，超长仍分批。新增去重前后体积日志，需重启后验证真实效果。见综合预算。

2026-09-22 F099：全文分析与跨库完整原文回读改为环境变量控制，当前两项均设8；回读按库并发且完整性校验保持。需重启后采集真实速度与多请求表现，见并发配置。

2026-09-22 F098：已召回可用同题QA时直接返回原答案和来源，跳过rerank及其他候选模型分析；冲突、附件和检索失败规则保持。需重启后生效，真实耗时待采集。见问答流程。

2026-09-22 F097：新增问答耗时汇总日志request_performance，包含thread_id/request_id、阶段处理与模型排队、首卡/首字和总耗时。仅增加观测，不改变问答流程；需重启后采集真实基线。见耗时观测。

2026-09-22 F095：前端创建助手会话草稿并填写资料，后台按c_session_id实时查找，已有则补写摘要分析，缺失才新建；保留前端业务字段。112项分析回归通过，真实更新及前端联调待验收。见会话分析。

2026-09-21 F093：全文分析前接入逐资料四级相关性并发判断，保留强/中相关，保护必要前置和不确定资料，弱/不相关可过滤。提示与返回精简，支持开关、超时回退和诊断；需重启，验证范围与配置见rerank说明。

2026-09-21 F083：候选分析改用证据编号，程序回填原文及路径，解释正文保持自然表达；错误编号隔离并定向修正，前端引用字段不变。需重启后端，见引用与候选分析。

2026-09-21 F081：新增公安Excel三个工作表共53条知识，保留旧3189条；入库与检索统一读取EMBEDDING_MODEL_PATH=models/bge-large-zh-v1.5。Excel新增53条已获授权生成DeepSeek摘要，合并单元格和来源完整保留；BGE全量重建后需重启后端。详见知识整理与知识入库。

2026-09-21 F080：区域前提和末尾建议按顺序进入正文流，独立提示不再重复开头或打断正文；最终替换协议保持。需重启后端，见流式协议。

2026-09-20 F079：政策完整卡片先返回，再流式讲解；节点结束不重复发卡，result保持完整。前端收到item即可展示，需重启后端，见正文流式协议。

2026-09-20 F077：候选错误保存字段及名称引文差异，定向重试；多块原文先提取证据再合并卡片，单块失败继续后续块但不推荐不完整候选。加强普通开店与科创需求区分，需重启后端；诊断和验证边界见候选分析恢复。

2026-09-20 F076：会话摘要同次生成多标签诉求词，优先12类及同义归一，允许自定义类别；写入营商助手-诉求词，每会话每类别一条有效草稿，续聊更新及失败恢复。需重启后端，见诉求词分类。

2026-09-20 F074：chat新增可选pictures/files链接数组；图片视觉识别及Excel/DOCX/文字PDF解析，与知识证据联合回答，失败和超长处理保留明确状态。空数组/省略保持原调用，公司确认保留原轮附件。格式、来源字段与预算见附件接口。新增解析依赖已锁定，后端需重启；生产附件下载与前端待联调。

2026-09-20 F069：公司检索先查DMS企业基础信息草稿；精确匹配或用户确认后读取基础资料，再按信用代码查询荣誉。DMS候选最多3家，支持“搜索更多公司”进入企查查；无候选自动补充查询。业务字段保持企查查兼容，来源明确为DMS。前端操作与边界见公司检索，后端需重启。

2026-09-18 F059真实测试：新增run_session --session-id即时入口，指定会话2轮首轮分析成功，已创建真实DMS助手会话草稿并回读completed。86分析回归和离线基线通过；后台静默V4仍待验收，详见docs/session-analysis.md。

2026-09-18 F059部门名称优化：提示统一标准名称并列出31项允许值，明确简称/本区全称/空白归一，未知名称反馈具体位置与允许值。81分析、45API及纯合成真实模型修正通过；需重启，真实用户会话未复验。

2026-09-18 F059会话并发：不同会话默认4路并行分析，SESSION_ANALYSIS_CONCURRENCY可设1至32；同会话不重入、内部两阶段串行，快任务独立回收。77分析、45API及离线基线通过；需重启，真实并发吞吐与写回待验收。

2026-09-18 F059持续写入修复：分页改为固定主键上界与范围游标，不再要求各页记录总数一致；模型调用前复读会话，变化后重新静默。74分析、45API及离线初始化通过，真实DMS只读聚合通过；需重启，生产写回与持续写入压力待验收。

2026-09-18 F059最新：长会话按模型预算分段摘要后分析；取消摘要/关注点字符数硬限制；DMS日志增加session_id及目标记录ID。三次失败后也保存会话，摘要写失败原因、其他分析清空；保存失败只重试保存，避免重复分析。70项分析回归、3组合成长文真实模型检查通过，需重启及生产写回复验。详见会话分析。

2026-09-18 F059历史（前端职责已由F095替代）：前端仅保存助手问答记录，后台静默分析后自动创建缺失助手会话；已有摘要只因问答内容变化而更新，重启/版本变化不重写。目标过滤查询异常增加完整列表精确匹配回退。58项分析、45项API及离线基线通过；需重启生效，真实新增/更新待验收。以下旧的前端创建与版本重分析规则已被替代。

2026-09-18 F059补充：核心需求取消条数和字数硬限制，允许空数组，保留基本结构校验；51项分析、45项API回归通过。此前核心需求长度定向修正规则已被替代，需重启后生效，生产写回复验待完成。

2026-09-18 F059：DMS无需手动配置token，使用账号密码自动登录，212/HTTP401时有界重新登录；核心需求长度改为字段定向修正，缺失回答等待前端补齐并仅在异常变化时提示。50项分析及45项API回归通过，需重启生效，生产复验待完成。

2026-09-17 F059 DMS迁移：API/CLI停止本地会话JSON落盘。前端创建助手会话并保存逐轮问答草稿；后台只读「营商助手－助手问答记录」，按c_session_id聚合，超过SESSION_IDLE_SECONDS后将分析更新到「助手会话」草稿。旧SESSION_DIR不再观察，Redis上下文保留。需重启后端；真实写回与前端验收待完成。详见 DMS会话监视。以下较早JSON方案已被本条替代。

2026-09-17 F059：API启动后持续观察SESSION_DIR，静默超过30分钟分析完整会话。第一阶段三个判断全部为“是”才执行招商分析；总结、两阶段结果及保存时间写回同一会话JSON的analysis。继续提问使旧分析过期，再静默后更新。文件名改为thread_id，兼容旧哈希文件；需重启后端。详见 会话分析。

2026-09-17 F058：API及CLI新增会话JSON保存，每个thread_id一份文件，含逐轮问题、AI回答、补问和完整结果；SESSION_DIR=session相对于项目根目录，支持运行系统的绝对路径。独立于Redis保留，重启后续写；暂不实现对话分析或后台页面。需重启服务，详见 会话保存。

2026-09-16 F046：四份reference JSON已更新，涉外由目录迁移为JSON；3189条完成规整、摘要及Milvus独立全量复验。卡片限定指定四来源且原条目is_policy严格为true，其他知识保留有据正文；新版惠企content包装已兼容。四组真实检索通过，服务由用户自行重启加载新规则和快照。详见 知识入库说明。

2026-09-15 15:50（F037）：回答开头优先给出针对问题的有据结论，summary.text使用Markdown，末尾保留三项下一步建议；过程SSE改用自然服务表达。惠企政策库来源标识和优先排序保持。接口字段未变，见 前端对接文档。

本项目已完成Harness、第一步知识规整与摘要、第二步Milvus知识入库；第三步已有LangGraph问答框架与企查查公司确认画像CLI，已接入政策检索与LLM匹配原因，提供完整原文JSON/HTML；第四步已有JSON请求、SSE事件流与单进程有界并发接口，生产鉴权和完整业务容量尚未验收。 后续重点为 F005“从实际问题主动发现政策”：先建立不含政策名称的口语化问题评测集，再推进需求拆解、跨库检索和适用性核验。当前入库成功不代表政策匹配准确，详见 政策发现功能与验收。 已存在 pyproject.toml（Python >=3.14，tokenizers 用于离线长度统计）、本地 .env、models/ 和 reference/。 参考文件已全量解析为本地知识集；本地BGE Embedding已由第二步入库脚本接入。现有虚拟环境为 Python 3.14.5，已验证可用，并已生成 uv.lock。 此前沙箱内的 Python 启动失败由执行权限限制引起，不代表虚拟环境损坏。

开发入口

Linux部署入口：sh deploy.sh；知识更新并启动：sh deploy.sh update-knowledge；代码更新后重启：sh deploy.sh restart。脚本安装uv/Python与依赖，补齐BGE和摘要tokenizer，支持后台进程管理；首次无知识快照时执行全量规整、摘要和入库。知识更新先在独立依赖环境及暂存目录处理并校验，成功后才停止旧服务、切换并启动；准备失败保留旧服务。配置与运行边界见部署说明。

Harness 开发记录及检查器仅本地保留，不上传仓库。克隆后可正常运行初始化；上传范围见 Git上传说明。

公司分类：POST /api/company/classify 直接接收chat返回的 company_info，六角度独立LLM多标签分类，信息不足为空数组。请求、返回、提示词与错误语义见 公司分类接口。

前端对接文档：POST /api/chat接口与返回结果，包含SSE事件、普通对话/政策/需求结果、卡片、补问及错误示例。

API现默认在终端打印脱敏JSON日志，包括接收请求、当前阶段、后台完成耗时及错误码；使用request_id关联，完整问题与资料不写日志。字段说明见 服务日志。

日志和Redis新增提问历史统一上海时间（+08:00）。历史按请求保存问题、接收/开始/结束时间和状态，供后续后台分析；默认随会话写入续期15天。见 历史字段与读取说明。

第四步启动：.\.venv\Scripts\python.exe -m src.step4_api。POST /api/chat 接收 {"thread_id":"窗口ID","question":"用户问题"}，返回SSE进度、回答、推荐及来源事件；监听地址由 .env 的 API_HOST、API_PORT 控制。并发配置、公司补问与前端读取示例见 第四步接口。

知识整理入口与四类模板见 knowledge/README.md。代码在 src/step1_knowledge_prepare/。

.\.venv\Scripts\python.exe -m src.step1_knowledge_prepare
.\.venv\Scripts\python.exe -m src.step1_knowledge_prepare --verify
.\.venv\Scripts\python.exe -m src.step1_knowledge_prepare.summarize
.\.venv\Scripts\python.exe -m src.step1_knowledge_prepare.summarize --verify-only
.\.venv\Scripts\python.exe -m unittest discover -s src/step1_knowledge_prepare/tests -v

JSON/CSV/TXT知识规整使用标准库，Excel使用已有openpyxl依赖，输出 JSONL 和 Markdown；摘要脚本复用本地tokenizer检查预算，并使用 .env 配置调用DeepSeek，按五类场景生成JSON摘要。配置、缓存、翻倍重试和增强JSONL见 摘要生成。 保留原始资料和未知项，摘要生成不代表政策有效性已核验或检索已接入。

pwsh -NoProfile -File ./init.ps1
# 已有本地解释器和所需依赖缓存时，可禁止联网：
pwsh -NoProfile -File ./init.ps1 -Offline
# 仅本地含 Harness 文件时：检查开发文档和功能状态，不要求 uv/Python：
pwsh -NoProfile -File ./init.ps1 -CheckOnly

Windows PowerShell 备用入口：powershell -NoProfile -ExecutionPolicy Bypass -File ./init.ps1。 Bypass 只作用于该进程，不修改系统持久执行策略；受组织策略限制时应使用获准的终端。 从其他目录调用时提供 init.ps1 的绝对路径，脚本自动定位本仓库。

默认初始化会在本地 Harness 检查器存在时先执行检查，再检查 uv，验证现有 Python，首次运行 uv lock，已有锁文件时执行 uv lock --check，然后 uv sync --frozen --inexact 并运行 Python 标准库冒烟。 锁文件过期会失败；修改依赖后应显式执行 uv lock 并审查差异。--inexact 保留原环境的额外包， 因此现有环境通过不代表包集合与锁文件完全相同。没有 .venv 时由 uv 创建。

初始化不自动下载 Python；需预先安装满足 pyproject.toml 的解释器，必要时设置 UV_PYTHON 指向它。 默认可联网同步依赖；-Offline 在本地资源不足时失败。缓存固定在仓库 .uv-cache/，环境固定在 .venv/。 现有环境不可运行时直接报错，不删除或重建；“拒绝访问”应先排查终端/沙箱权限。 默认模式退出码 0 表示环境检查和同步成功；任一步失败返回非零。-CheckOnly 成功仅表示 Harness 有效。 初始化的任何模式均不读取 .env 或调用模型/企业信息服务。第三步业务CLI由F017实现，见下方说明。

初始化回归：.\.venv\Scripts\python.exe -m unittest discover -s scripts/tests -v。 当前测试使用隔离目录、uv 替身和真实 Python，验证退出码、锁文件策略、环境保留与重复执行；不代表业务测试。

依赖镜像

pyproject.toml 已将清华 PyPI 镜像 https://pypi.tuna.tsinghua.edu.cn/simple 配置为 uv 默认源。 运行初始化脚本或在本项目中执行 uv add、uv lock、uv sync 时自动读取。 配置采用 uv 的 [[tool.uv.index]] 与 default = true，见 uv 索引文档。

如需临时切换，可在当前 PowerShell 中设置 $env:UV_DEFAULT_INDEX = 'https://pypi.org/simple'， 使用完后通过 Remove-Item Env:UV_DEFAULT_INDEX 恢复项目默认源。已有锁文件记录其他源的包时， 需显式执行 uv lock 并审查差异后再初始化。-Offline 仍禁止联网；此配置只针对 Python 包，不用于下载 Python 解释器。

文件导航

文件	用途
docs/README.md	按任务阅读的文档路由
init.ps1	开发基线检查入口

建议开发顺序：运行骨架 → 公司信息获取 → 知识入库 → 检索 → 有引用的回答 → 会话与接口 → 端到端质量验收。 知识库后端已确定为Milvus，本地Embedding使用bge-large-zh-v1.5；公司信息来源已确定为企查查886/410/1001；需求识别、查询规划与推荐分析使用DeepSeek，接口见 流式API，详细业务范围见 业务说明。

第二步知识入库代码位于 src/step2_knowledge_ingest/，按类型分Milvus数据库，标题＋摘要生成本地BGE向量，完整知识另行无损保存。配置、运行命令和快照规则见 知识入库。

第二步为使用本机RTX4080，在Windows上将torch单独绑定官方 https://download.pytorch.org/whl/cu130 源（explicit=true），其余包继续使用清华默认镜像；锁文件记录此平台条件。代码默认CPU，本机.env配置为cuda。

第三步入口：.\.venv\Scripts\python.exe -m src.step3_question_answer。默认调用DeepSeek区分闲聊、政策了解、具体需求：闲聊依据角色信息自主回应；政策了解检索六库（含QA）并依据原文回答；具体需求按需画像、拆解检索并分析适用条件。未说明主题时自然补问；分类失败按原问题检索并标记错误。加 --manual 显式跳过自动分流，以具体需求模式手工提供公司线索。密钥保存在Git忽略的.env。检索回答提供完整来源页；详见 第三步框架与配置。

第三步启动会先加载并预热Embedding模型，显示“检索模型已就绪”后接收问题；同进程复用模型，--company-only跳过预热。详见 启动预热。

推荐后端现返回按主体匹配依据排序的items、六类卡片信息及独立summary，不再额外限制最多6项；工商/荣誉或本轮个人自述参与检索规划和逐项比较。CLI/HTML渲染暂不调整，后续对接前端时使用卡片及综合说明字段。详见推荐数据契约。

第三步CLI使用Redis保存会话检查点，启动时输出会话ID；使用 --session-id <会话ID> 恢复咨询。配置读取 REDIS_URL 和 REDIS_CONTEXT_TTL_SECONDS（默认1296000秒，即15天）。会话新建与清除由前端控制，CLI不提供对应命令。F057已为闲聊、政策了解和具体需求接入同会话上下文，支持追问指代及明确延续的已确认公司。模型最多读取最近8轮、6000 UTF-8字节历史，超出时标注省略；历史回答不作政策证据。详见上下文持久化。需重启后端生效，真实用户复验待完成。