docs: 说明 Ragflow 安全性与二开后换底座成本

Co-authored-by: haijd <haijd@163.com>

README.md

@@ -1,2 +1,32 @@
-# xianjing-ai
+# 鲜境物联 · AI 智能客服｜技术路线建议
 
+综合建议书、验收标准、**委托开发合同**与**附件二进度表**后的实施路线结论。
+
+## 结论
+
+**推荐：开源自托管二开 + 核心业务定制。不建议纯自研，不建议纯公有云 SaaS。**
+
+| 路线 | 结论 |
+|------|------|
+| 纯自研 | 不推荐首期（撞上 **7 周 / ¥5 万** 硬顶） |
+| 纯 SaaS（扣子 / 阿里云客服等） | 不推荐（数据自主可控冲突） |
+| **Dify 自托管二开 + 方案判定定制** | **推荐** |
+
+**二开首选：Dify**；检索吃力时加 **Ragflow**；人工席位 **Chatwoot**（或企微/飞书）。
+
+合同已锁：实施 **¥50,000**、订阅 **¥30,000/年**、周期 **7 周**、线上场景 **只做一个高频渠道**。详见完整建议书。
+
+## 文档
+
+| 文件 | 说明 |
+|------|------|
+| [docs/技术方案建议书.md](./docs/技术方案建议书.md) | 决策依据、平台对比、架构、7 周映射、风险 |
+| [uploads/](./uploads/) | 原始合同、进度表、建议书、验收标准 |
+
+## 建议立刻确认
+
+1. 首期唯一渠道：网站还是 Facebook？  
+2. 方案判定树的业务拍板人  
+3. 模型：智谱 API 是否可上生产 / 是否必须私有化  
+4. 场景二（录音辅助）是否与场景一同期验收  
+5. 部署：甲方机房还是乙方 VPC

docs/技术方案建议书.md

@@ -0,0 +1,296 @@
+# 鲜境物联 · AI 智能客服｜技术路线建议书
+
+> 依据材料：框架合作建议书、AI 客服建议书与报价、验收标准（附件三）、委托开发合同、开发计划与进度表（附件二）。  
+> 结论先看：**推荐「开源自托管二开 + 核心业务定制」；不推荐纯自研，不推荐纯公有云 SaaS。二开底座首选 Dify。**
+
+---
+
+## 1. 项目边界（合同已锁死的硬约束）
+
+| 维度 | 合同 / 计划约定 | 对技术选型的含义 |
+|------|------------------|-------------------|
+| 周期 | **7 周**（约 2 个月），自首付款 + 必要资料齐备起算 | 必须复用成熟对话/RAG 底座，禁止从零造轮子 |
+| 费用 | 一次性实施 **¥50,000**；年度订阅 **¥30,000/年** | 人力预算紧，二开性价比远高于纯自研 |
+| 场景一 | 选 **一个高频渠道** 做 24h 智能咨询（意图→追问→方案→人工接管） | 首期渠道做深一个，勿同时铺网站+FB+邮件 |
+| 场景二 | 录音/对话 → 语义识别 → 知识库 → 自动生成方案 | 可与场景一共用同一知识库与方案引擎 |
+| IP | 定制功能 + 知识库归甲方；乙方保留通用框架复用权；开源须清单披露 | **自托管开源二开完全合规**，且利于乙方后续复用 |
+| 数据 | 建议书明确：数据自主可控、避开对第三方平台（如阿里）依赖 | 排除强绑定公有云客服 SaaS 作为主路径 |
+| 验收 | 功能闭环 + AI Eval（意图≥85%、方案≥80%、完成≥70%、幻觉≤5%、泄露 0%） | 必须单独做评测与人工接管，不能只做「能聊天」 |
+
+进度锚点（附件二）：
+
+| 阶段 | 周次 | 必须产出 |
+|------|------|----------|
+| P1 需求诊断 | W1 | 需求清单、资料清单、方案判定逻辑初稿 |
+| P2 概念验证 | W2 | 可运行 Concept Demo |
+| P3 真实验验 | W3 | 真实场景验证报告 |
+| P4 MVP | W4–W6 | 可上线 MVP（含约定渠道对接） |
+| P5 试运行 | W7+ | 效果看板、首轮优化 |
+
+在 **5 万 / 7 周** 约束下，任何「自研完整客服中台」都会在 W2–W3 断档。
+
+---
+
+## 2. 三条路线怎么选
+
+### 2.1 纯自研（LangChain/自写服务 + 自研后台）
+
+| 优点 | 风险 |
+|------|------|
+| 完全可控、后续扩展空间大 | 知识库后台、对话编排、评测、权限、多轮状态机都要自写 |
+| 契合乙方「保留通用框架」长期意图 | 7 周内难同时达到验收阈值；5 万预算撑不起完整团队 |
+
+**结论：不作为首期主路径。** 可作为二期沉淀「方案判定引擎 / Eval」时逐步抽离自研模块。
+
+### 2.2 纯 SaaS（扣子 Coze、阿里云智能客服、腾讯企点等）
+
+| 优点 | 风险 |
+|------|------|
+| 上线快、少运维 | 与「数据自主可控、避开第三方平台依赖」直接冲突 |
+| | 知识库/对话数据常落在厂商侧；出海/模型切换受限 |
+| | 合同要求开源清单与定制归属，SaaS 难谈清底层复用 |
+
+**结论：不推荐作主交付。** Demo 可用公有能力试效果，生产必须迁出自托管。
+
+### 2.3 开源自托管二开 + 业务定制（推荐）
+
+| 优点 | 风险 |
+|------|------|
+| W2 即可出 Concept Demo | 底座升级需跟社区版本 |
+| 知识库/对话/工作流开箱可用 | 「卖方案」逻辑仍要定制，不能只靠默认 FAQ RAG |
+| 符合数据本地化与 IP 条款 | 需选好 License（Apache/MIT 优先）并出开源清单 |
+| 年度订阅可覆盖模型+运维+迭代 | 多渠道若一次做满会爆工期——合同已限制「选一个高频渠道」 |
+
+**结论：唯一与合同周期、金额、数据主权、验收指标同时匹配的路线。**
+
+---
+
+## 3. 二开底座对比与推荐
+
+面向本项目关键能力：RAG 知识库、多轮工作流（追问）、工具调用（方案匹配）、自托管、国产/海外模型可切换、可接人工接管。
+
+| 底座 | 知识库/RAG | 工作流/Agent | 业务后台完备度 | 中文生态 | 与本项目匹配 | 建议 |
+|------|------------|--------------|-----------------|----------|--------------|------|
+| **Dify** | 强 | **强**（可视化工作流贴合意图→追问→方案） | **高**（知识库/日志/应用开箱） | 强 | ★★★★★ | **首选** |
+| Flowise | 中（偏编排侧） | **强**（LangChain 节点灵活） | **低**（缺完整客服运营后台） | 中 | ★★★ | 可做引擎，不适合单独交付 |
+| Ragflow | **检索质量突出** | 工作流弱于 Dify | 中（偏知识工程） | 强 | ★★★★ | 检索难达标时与 Dify 组合 |
+| FastGPT | 强（偏问答） | 中 | 高 | 强 | ★★★★ | 备选，复杂判定易顶天花板 |
+| MaxKB | 够用 | 偏基础 | 中高 | 强 | ★★★ | 简单 FAQ 够用，本项目偏弱 |
+| Botpress | 中 | 对话机器人强 | 中高 | 中 | ★★★ | 渠道多时考虑 |
+| 扣子/阿里云等 SaaS | 强 | 强 | 高（非自托管） | 强 | ★★ | 违背数据自主原则 |
+
+### Dify vs Ragflow（鲜境场景专项对比）
+
+两者都能自托管、都能接国产模型；差别是**谁强在「对话编排/交付」**，谁强在「把资料检准」。
+
+| 维度 | Dify | Ragflow |
+|------|------|---------|
+| 产品重心 | LLM 应用平台：Chatflow / Workflow / 发布 API | RAG 引擎：解析、切块、召回、引用；Agent 在增强 |
+| 知识库质量 | 够用；复杂 PDF/表格/扫描件易成瓶颈 | **明显更强**（版面解析、多路召回、重排、引用） |
+| 「意图→追问→出方案」 | **更顺**：可视化分支、槽位追问、工具调用成熟 | 有 Agent/Workflow，但成熟度与交付模板仍弱于 Dify |
+| 业务后台 | 应用、日志、发布、团队协作更完整 | 偏知识工程与助手配置 |
+| License | Apache-2.0 **+ 附加条款**（多租户/去 Logo） | **纯 Apache-2.0** |
+| 中文落地案例 | 多，FDE 好讲 | 多（尤其文档型知识库） |
+| 部署体感 | Docker 较轻、功能面全 | 解析链路更重，资源占用通常更高 |
+| 幻觉治理（贴验收≤5%） | 靠提示词 + 普通 RAG，要多调 | **从检索侧更易压幻觉** |
+| 7 周 / 5 万 | **更快出可验收客服形态** | 检索达标快，复杂对话流要多投人天 |
+
+**怎么选（只选一个时）：**
+
+| 情况 | 选谁 |
+|------|------|
+| 资料以参数表、方案 Word/PDF、图纸说明为主，怕检不准、怕幻觉 | 更倾向 **Ragflow** |
+| 核心难在多轮追问、方案判定分支、尽快像「客服产品」上线 | 更倾向 **Dify** |
+| 法务要纯 Apache/MIT/BSD，或乙方要多租户平台化 | **Ragflow**（或 Ragflow + 自研薄编排） |
+| 单客户交付、可留 Logo、要工期最短 | **Dify** |
+
+**怎么选（允许组合时，效果最好）：**
+
+```
+Ragflow（知识库 / 检索 / 引用）
+        ↑ 检索 API
+Dify（意图分类 → 追问槽位 → 调 Ragflow → 方案生成 → 转人工）
+```
+
+- W2 Demo 可先 **单底座**（别一上来双栈）。  
+- W3 若方案匹配/幻觉不达标，再把检索切到 Ragflow，对话流仍留在 Dify。  
+- 若已定纯许可、不用 Dify：用 **Ragflow + 少量自研判定/追问 API**（或 Flowise 社区版只做编排）。
+
+**对鲜境一句话：**  
+卖的是「方案」不是「搜文档」——对话闭环 Dify 更省事；过验收里的**准确率/幻觉**时 Ragflow 更扛打。许可干净选 Ragflow；工期最紧且单租户可选 Dify；预算与运维允许则 **Dify 编排 + Ragflow 检索**。
+
+#### 「Ragflow 是不是更安全更好？二开后还换得了吗？」
+
+**更安全（许可/合规）：是，Ragflow 更干净。**  
+纯 Apache-2.0，无多租户/去 Logo 附加条款；乙方以后多客户复用、招标写「MIT/Apache/BSD」时更省事。Dify 在本单风险可控，但协议本身不如 Ragflow「安」。
+
+**更好（交付效果）：不一定。**  
+- 资料检准、降幻觉、引用溯源 → Ragflow 通常更好。  
+- 多轮追问、方案分支、7 周内像「客服产品」上线 → Dify 通常更好。  
+- 选错的代价：Ragflow 省了许可麻烦，但可能在对话流上多烧人天；Dify 省了编排，但许可与厂商政策要一直盯。
+
+**二开后换底座：确实不容易，但不是换「整个项目」。**  
+难换的是绑死在画布/控制台上的东西；好搬的是你们自己沉淀的资产。
+
+| 资产 | 换底座难度 | 建议一开始就怎么做 |
+|------|------------|-------------------|
+| 产品/方案**原文资料**、结构化产品表 | 低 | 资料进 Git/对象存储，底座只当索引器 |
+| **方案判定树、追问槽位、验收评测集** | 低 | 写成独立文档/JSON/规则表，不要只活在某个 Workflow 节点里 |
+| 渠道接入、ASR、人工接管、自研 API | 中 | 自研层调「检索/对话」接口，少写死厂商 SDK |
+| 底座里的**可视化工作流、提示词、分段策略** | **高** | 默认要重配；这是二开锁定的主成本 |
+| 向量库里的 embedding | **高** | 换模型/换引擎通常要**全量重建索引** |
+
+**因此：**
+
+1. 若更看重长期许可安全、少被厂商附加条款绑住 → **首期就上 Ragflow 更稳**，别指望「先 Dify 再轻松迁 Ragflow」。  
+2. 若已上 Dify，真正能带走的是知识原文 + 判定逻辑 + Eval；工作流本身当沉没成本。  
+3. 降低锁定的做法：自研一层薄「方案引擎」（判定 + 槽位 + 调检索 API），底座只负责 RAG/或编排；这样换 Dify↔Ragflow 只换检索/编排适配器。  
+4. **双栈（Dify+Ragflow）** 运维更重，但换的时候可以先只丢一边，比 All-in 单一画布稍主动。
+
+**结合合同（5 万/7 周）的务实结论：**  
+- 法务/平台化复用优先 → **直接 Ragflow**，接受对话流多做一点定制。  
+- 只求本单快验收、单租户可留 Logo → Dify 仍可行，但把判定树/评测集/原始知识**外置**，当保险。  
+- 不要假设「二开完还能廉价换家」——能换的是资产，不是画布。
+
+---
+### 为何首选 Dify（而不是 Flowise）
+
+Dify 和 Flowise 都能自托管、都能画工作流，但**产品形态不同**：
+
+| 对比项 | Dify | Flowise |
+|--------|------|---------|
+| 定位 | 偏「可交付的 LLM 应用平台」 | 偏「LangChain 可视化编排器」 |
+| 知识库运营 | 文档上传、分段、召回测试、权限较完整 | 有向量/文档节点，**缺甲方业务人员可长期维护的知识库后台** |
+| 合同要的后台 | 对话日志、应用配置、基础观测更开箱 | 多半要**另做 Admin / 日志 / 效果看板** |
+| 「卖方案」链路 | Chatflow/Workflow 直接支撑意图→追问→出方案 | 也能搭，但槽位追问、会话状态、对外 Chat API 要更多拼装 |
+| 甲方侧使用门槛 | 运营/销售助理可在控制台改知识库 | 改流程基本是**开发在画布上改节点** |
+| 中文资料与实施案例 | 多，便于 FDE 驻场与交接 | 英文社区为主，国内交付摩擦更大 |
+| 二开成本（相对本项目） | 定制重心在业务规则与 Eval | 定制要覆盖 **规则 + 大半个运营后台**，易吃掉 5 万预算 |
+| License | **非纯 Apache**：Apache-2.0 + 附加条款（多租户 SaaS、去 Logo 等需商业授权） | Apache-2.0 |
+
+**对本合同的含义：**
+
+1. 验收写了「知识库可增删改查、对话记录可追溯、数据看板」——Dify 自带大半；Flowise 二开等于还要自研一层运营面。  
+2. 7 周里 W2 就要 Concept Demo、W3 真实验证——Dify 用控制台灌资料即可；Flowise 更适合「工程师已写好链路」的演示，不适合业务专家自己改库。  
+3. Flowise **不是不能用**，更适合：团队强依赖 LangChain 生态、只要 API 引擎、运营后台另有系统承接。鲜境首期没有现成客服中台，用 Flowise 会把二开做成「半自研」。  
+4. 若坚持 Flowise：建议 **Flowise 只做编排引擎 + 自研/套 Chatwoot 做会话与人工接管 + 自研轻量知识库管理**，工作量和风险高于 Dify 单底座。
+
+**一句话：Flowise 是好用的编排器；Dify 更接近「能验收交付的 AI 客服底座」。** 在 5 万 / 7 周下选后者。
+
+### 为何首选 Dify（相对其他底座）
+
+1. **工作流原生支持**合同核心链路「意图识别 → 追问 → 方案生成」，比纯问答库更贴「卖方案」。  
+2. **自托管 + 多模型**：满足数据可控与智谱/Gemini 等切换。  
+3. **许可可用但非纯 OSI 开源**：主体基于 Apache-2.0，另有附加条款（见下节）；单客户自托管交付通常可行，多租户转售/去 Logo 需另谈商业授权。  
+4. **W2 Concept Demo** 可在底座上直接配知识库+简易流，不必先写后台。  
+5. 人工接管、评测、渠道适配用周边开源/薄封装即可，不必绑死一家云。
+
+#### Dify 许可要点（合同 5.4 开源清单必写清）
+
+- **不是** MIT / BSD，也**不是**无修改的纯 Apache-2.0 / 纯 OSI 开源。  
+- 官方名称：**Dify Open Source License** = **Apache License 2.0 + 附加条件**。  
+- 一般允许：商业使用、作为企业应用开发平台、作为其他应用的后端（含单客户私有化部署）。  
+- 附加限制（触发则需向 LangGenius 取得书面商业授权）：  
+  1. 用源码运营**多租户**环境（一个 Workspace ≈ 一个租户）；  
+  2. 使用其前端时**去除或修改**控制台/应用中的 Logo 与版权信息（纯 API、不使用其 `web` 前端则不受此项约束）。  
+- 贡献代码方面：生产方可调整协议；贡献可能被用于其云业务。  
+#### 还要不要用 Dify？要不要换成纯 MIT/Apache/BSD？
+
+**对鲜境这一单：可以继续用 Dify，许可风险可控。**  
+前提：单甲方独立部署（或单 Workspace）、**不**做多租户转售、控制台**保留** Dify Logo/版权；合同开源清单写明「Apache-2.0 + 附加条款」全文链接。
+
+**若甲方法务硬性只要 MIT/Apache/BSD，或乙方要把底座做成多客户共用的标准交付平台：不要赌 Dify，换纯许可栈。**
+
+| 候选（纯/更接近宽松许可） | License | 适不适合鲜境首期 | 说明 |
+|---------------------------|---------|------------------|------|
+| **Ragflow** | **Apache-2.0** | ★★★★ 首选替代 | 知识库/解析强；「意图→追问→方案」工作流弱于 Dify，需多做一点编排定制 |
+| **Flowise**（社区版，避开 `enterprise/`） | **Apache-2.0** | ★★★ | 编排灵活；运营后台弱，等于半自研 |
+| **AnythingLLM** | **MIT** | ★★★ | 文档问答上手快；复杂方案判定/追问链路偏弱 |
+| LangGraph / LlamaIndex 自拼 | MIT / Apache | ★★ | 许可最干净，但 7 周/5 万工作量接近纯自研 |
+| FastGPT | Apache + 附加条件 | — | **同类坑**，不是纯 Apache |
+| MaxKB | GPL-3.0 系 | — | 传染性开源，和乙方「框架复用」更别扭 |
+
+**决策口诀：**
+
+1. 只交付鲜境、单租户、可留 Logo、要最快验收 → **继续 Dify**。  
+2. 法务/招标要求纯 OSI，或乙方要多客户平台化复用 → **Ragflow 为主底座**（必要时 + 薄工作流/自研判定），不要为了「像 Dify」去碰附加条款。  
+3. 不要为了许可换成 GPL；也不要以为 Flowise「全仓库都是 Apache」——其 `enterprise/` 等目录是商业许可，二开只用社区部分。
+
+
+## 4. 必须自研/定制的部分（二开不等于零开发）
+
+这些是验收与差异化的关键，**不要指望底座默认能力**：
+
+| 模块 | 做法 | 归属（按合同） |
+|------|------|----------------|
+| 方案判定逻辑 | 从业务专家萃取规则/决策树 → Dify 工作流节点或 Tool | 定制成果 → 甲方 |
+| 产品组合匹配 | 结构化产品表 + 规则/检索混合，禁止纯自由发挥 hallucination | 定制 + 知识库 → 甲方 |
+| 追问槽位设计 | 按两大类技术路线设计必问项（预算、场景、工况等） | 定制 → 甲方 |
+| 人工接管策略 | 置信度阈值、敏感词、超时、留资表单 | 定制 → 甲方 |
+| AI Eval | 200 条标注集、盲测流程、幻觉抽检脚本 | 评测资产 → 甲方 |
+| 渠道适配 | **只做一个**高频入口的对接与样式 | 定制 → 甲方 |
+| 开源清单 | Dify/Chatwoot/依赖 License 列表 | 合同强制交付 |
+
+底座本身、通用连接器、模板工作流 → 属乙方可复用框架（合同 5.1 / 5.2）。
+
+---
+
+## 5. 与 7 周计划的落地映射
+
+| 周次 | 技术动作（建议） | 防延期要点 |
+|------|------------------|------------|
+| W1 | 锁定唯一渠道；萃取方案判定树；资料分级入库标准 | 甲方不给齐资料则工期按合同顺延 |
+| W2 | Dify 部署 + 样本知识库 + Concept Demo（追问 3–5 轮能出草案） | Demo 先通闭环，不追求全量资料 |
+| W3 | 导入真实资料；人工盲测方案准确率；调检索与提示词 | 未达标先调知识结构，勿急着上第二渠道 |
+| W4–W5 | 人工接管、留资、日志；场景二 ASR 联调（可并行薄做） | 渠道对接放本阶段，避免 W2 分心 |
+| W6 | UAT、安全脱敏、开源清单、部署文档 | 预留修缺陷缓冲 |
+| W7 | 生产试运行、效果看板、首轮 Eval 报告 | 订阅期内持续迭代算年度服务 |
+
+**砍范围优先级（预算不够时）：**  
+保：知识库 + 追问闭环 + 方案生成 + 人工接管 + 单渠道。  
+可后置：多渠道、精美独立 Admin、复杂经营看板、海外获客（属框架二期）。
+
+---
+
+## 6. 模型与部署建议（贴合数据自主）
+
+- **推理**：优先智谱 / 其他国产 API；敏感或申报需要时再上私有化（vLLM 等），首期不必自建 GPU。  
+- **Embedding**：与知识库同环境部署，避免文档出域。  
+- **ASR（场景二）**：可先用云端 ASR 降本；若录音含客户机密，改为私有化 Whisper 类方案。  
+- **部署**：客户机房或乙方托管的独立 VPC 均可，但知识库与对话日志不得默认进公有 SaaS。
+
+年度 ¥3 万订阅建议覆盖：Token 上限、监控、知识库更新、Eval 与小迭代——与合同 3.3 一致；超用量或新渠道走变更单。
+
+---
+
+## 7. 风险与门禁
+
+| 风险 | 应对 |
+|------|------|
+| 把项目做成「通用 FAQ 机器人」导致方案匹配<80% | W1 必须产出判定树；W3 专家盲测不过不进 P4 全量开发 |
+| 同时做多渠道拖死工期 | 严格按合同「一个高频渠道」 |
+| 幻觉与敏感泄露 | RAG 强制引用；输出护栏；Eval 自动化+人工抽检 |
+| 开源协议纠纷 | 交付开源组件清单；避免传染性 Copyleft 污染定制代码 |
+| 5 万预算被运维吞掉 | 首期单机/小集群 Docker Compose；监控用开源 |
+
+---
+
+## 8. 最终建议（决策一页纸）
+
+1. **路线**：开源自托管 **二开**，不是纯自研，不是纯 SaaS。  
+2. **底座**：**Dify 首选**；检索吃力再加 **Ragflow**；人工席位用 **Chatwoot**（或现有企微/飞书）。  
+3. **定制重心**：方案判定 + 产品组合 + 追问槽位 + AI Eval + 单渠道接入。  
+4. **与合同一致**：7 周、5 万实施、3 万/年订阅、知识库与定制归甲方、框架归乙方可复用。  
+5. **首期成功标准**：附件三阈值达标 + 一个渠道 7×24 可用 + 销售辅助能基于录音/文本出方案。
+
+---
+
+## 9. 建议甲方/乙方立刻确认的 5 件事
+
+1. 首期「一个高频渠道」究竟是网站还是 Facebook？  
+2. 两大类技术的方案判定树由哪几位业务专家拍板？  
+3. 模型选型：智谱 API 是否可直接用于生产？是否有私有化硬性要求？  
+4. 场景二是否与场景一同周验收，还是 W7 后订阅期迭代？  
+5. 部署位置：甲方机房还是乙方托管 VPC？
+
+确认以上后，即可按附件二从 P1 启动，无需再纠结纯自研。