diff --git a/ai_assistant_proposal.md b/ai_assistant_proposal.md new file mode 100644 index 00000000..a686cd46 --- /dev/null +++ b/ai_assistant_proposal.md @@ -0,0 +1,283 @@ +# 企业级 AI 工作助手:技术选型与实施路径建议书 + +## 一、底座架构选择 + +### 推荐方案:Spring AI Alibaba + 自定义 Agent 编排层 + +**核心理由:** + +| 评估维度 | Spring AI Alibaba | LangChain | LlamaIndex | 大厂托管平台 | +|---------|------------------|-----------|------------|-------------| +| Java 生态集成 | ✅ 原生 Spring Boot | ❌ Python 为主 | ❌ Python 为主 | ⚠️ 黑盒 | +| 内部部署支持 | ✅ 完全支持 | ✅ 支持 | ✅ 支持 | ❌ 仅 SaaS | +| 数据隐私 | ✅ 数据不出域 | ✅ 可控 | ✅ 可控 | ❌ 数据出境风险 | +| 定制深度 | ✅ 源码级可控 | ✅ 灵活 | ⚠️ 偏 RAG | ❌ 受限 | +| 社区成熟度 | ⚠️ 成长中 | ✅ 最成熟 | ✅ 成熟 | ✅ 大厂背书 | +| 工程化程度 | ✅ 企业级规范 | ⚠️ 偏弱 | ⚠️ 中等 | ✅ 开箱即用 | + +**权衡点:** +- Spring AI Alibaba 社区相对较小,遇到问题需更多自研能力。 +- 建议搭配 LiteLLM 做模型路由抽象,避免框架层绑定。 + +**架构建议:** +``` +员工请求 → 意图分类网关 → Agent 编排层(Spring AI) → 工具调用层 → 下游系统 + ↓ + 权限网关 + 审计日志 +``` + +--- + +## 二、LLM 模型选型策略 + +### 模型策略矩阵 + +| 任务类型 | 推荐模型 | 备选模型 | 单次成本(¥) | 月调用占比 | +|---------|---------|---------|------------|-----------| +| 意图分类/路由 | Qwen-Turbo / DeepSeek-V3 | GLM-4-Air | 0.002 | 100% | +| 简单问答/查询 | Qwen-Plus | DeepSeek-V3 | 0.008 | 40% | +| 复杂推理/多步 | GPT-4o / Claude 3.5 Sonnet | Qwen-Max | 0.05 | 25% | +| 视觉理解 | GPT-4o | Claude 3.5 Sonnet | 0.08 | 10% | +| 长文档摘要 | Qwen-Long | Kimi | 0.02 | 15% | +| 代码生成 | DeepSeek-Coder / GPT-4o | Claude 3.5 | 0.04 | 10% | + +### Fallback 链设计 +``` +主模型请求 → 超时/失败 → 降级到备选模型 → 仍失败 → 返回"暂时无法处理,请稍后重试" +``` + +**关键机制:** +- **统一抽象层**:使用 LiteLLM 或自研 Model Router,业务代码不直接调用具体模型 API。 +- **成本监控**:按部门/用户/任务类型统计 token 消耗,设置月度预算告警(80% 预警,100% 熔断)。 +- **能力差异处理**:在工具定义中标注所需能力(如 `requires_vision=true`),路由时自动匹配。 + +--- + +## 三、与企业现有系统集成方式 + +### 推荐路径:混合模式 + 渐进迁移 + +**阶段一(1-3个月):传统 API 适配层** +- 为高频系统(人事、财务、CRM)编写标准 REST API 适配器。 +- 使用 OpenAPI/Swagger 规范定义接口契约。 +- 优势:快速见效,验证核心流程。 + +**阶段二(4-6个月):MCP 试点** +- 选择 2-3 个新系统或改造成本低的系统试点 MCP Server。 +- 验证 MCP 协议稳定性、工具发现机制、错误处理。 +- 建立内部 MCP 开发规范。 + +**阶段三(7-12个月):全面迁移** +- 存量系统逐步包装为 MCP Server。 +- 新系统默认采用 MCP 协议。 +- 保留 API 适配层作为 fallback。 + +### 试点顺序建议 +1. **第一批**:人事系统 + 财务系统(验证"预算查询"场景)。 +2. **第二批**:CRM + 项目管理(验证"会议准备"场景)。 +3. **第三批**:知识库 + 合同管理 + 审批流。 + +--- + +## 四、权限与数据安全 + +### 推荐方案:权限网关 + OAuth 2.0 Token Exchange(方案 c+d 混合) + +**架构:** +``` +员工 → AI助手 → 权限网关 → 下游系统 + ↓ + 审计日志中心 +``` + +**权限流转:** +1. 员工登录 AI 助手时,获取员工身份 token。 +2. AI 助手发起下游请求时,通过 Token Exchange 获取**受限委托 token**。 +3. 权限网关根据员工角色 + 数据敏感度 + 操作类型进行实时鉴权。 +4. 敏感操作(如查看薪资)需二次确认或动态权限提升。 + +**四种方案对比:** + +| 方案 | 安全性 | 复杂度 | 可维护性 | 推荐度 | +|-----|-------|-------|---------|-------| +| (a) 员工 token 直调 | 高 | 中 | 中 | ⭐⭐⭐ | +| (b) 统一服务账号 | 低 | 低 | 高 | ⭐ | +| (c) 权限网关代理 | 高 | 高 | 高 | ⭐⭐⭐⭐ | +| (d) Token Exchange | 高 | 高 | 中 | ⭐⭐⭐⭐ | + +**审计日志要求:** +- 每次 AI 代表员工的操作必须记录:`who(员工) → what(操作) → when(时间) → which_system(系统) → result(结果)`。 +- 日志不可篡改,保留至少 3 年。 +- 支持按员工/系统/时间范围检索。 + +--- + +## 五、Agent 能力边界与人工审批 + +### Risk-Based 审批策略 + +| 风险等级 | 判定标准(程序化) | 操作示例 | 处理方式 | +|---------|------------------|---------|---------| +| **低风险** | 只读操作、聚合查询、生成报告、不影响他人 | 查预算、查项目进度、生成周报 | AI 直接执行 | +| **中风险** | 写入操作但可回滚、仅影响本人数据 | 提交报销、修改个人日程、创建草稿 | AI 执行 + 企微/钉钉通知员工确认 | +| **高风险** | 不可回滚、影响他人、涉及资金/合同/人事 | 删除项目、批量发邮件、调薪、审批合同 | 必须人工审批,走 OA 流程 | + +### 程序化判定规则 +```yaml +risk_level: + low: + - method in [GET, HEAD, OPTIONS] + - operation_type in [query, aggregate, generate_report] + medium: + - method in [POST, PUT, PATCH] + - has_rollback_mechanism == true + - affects_others == false + high: + - method in [DELETE] + - involves_financial_data == true + - affects_others == true + - operation in [delete_project, batch_email, salary_adjust] +``` + +### 审批流形态 +- **中风险**:企微/钉钉卡片通知,员工点击"确认"或"撤销",24 小时未操作自动撤销。 +- **高风险**:对接企业现有 OA 审批系统,按业务规则路由到对应审批人。 +- **紧急通道**:员工可随时在 AI 助手中查看待审批列表并加急处理。 + +--- + +## 六、渐进式部署与风险控制 + +### 灰度策略 + +| 阶段 | 人群 | 场景 | 时长 | 成功标准 | +|-----|------|------|------|---------| +| **Alpha** | IT 团队 + HR 管理员(50人) | 仅查询类操作 | 4 周 | 任务完成率 >70%,错误率 <5%,满意度 >4.0/5 | +| **Beta** | 全公司 10%(100人) | 查询 + 中风险操作 | 6 周 | 任务完成率 >80%,错误率 <3%,满意度 >4.2/5 | +| **GA** | 全公司 50%(500人) | 全场景(含高风险审批) | 8 周 | 任务完成率 >85%,错误率 <2%,满意度 >4.3/5 | +| **Full** | 全公司 100% | 全场景 | 持续 | 持续优化 | + +### 熔断回退触发条件 +- 错误率连续 2 天 >15%。 +- 发生安全事件(数据泄露、越权访问)。 +- 用户满意度 <3.0/5 且持续 1 周。 +- 核心系统响应超时率 >20%。 + +**回退机制**:一键切换回传统操作模式,所有 AI 操作自动转人工工单。 + +--- + +## 七、性能与成本预算 + +### 成本估算(1000 员工 × 30 次/天) + +| 指标 | 数值 | +|-----|------| +| 日均 Query 数 | 30,000 | +| 平均 Token/Query | 2,500(输入 2K + 输出 500) | +| 月均 Token 总量 | 22.5 亿 | +| 模型混合成本 | ¥35,000 - ¥65,000/月 | +| 单次 Query 平均成本 | ¥0.04 - ¥0.07 | + +**成本优化措施:** +- 意图分类前置过滤:30% 简单问题走本地小模型或规则引擎。 +- Prompt 缓存:相同模板缓存,减少重复 token。 +- 响应截断:非关键场景限制输出长度。 + +### 性能目标 + +| 场景 | 延迟目标 | 优化手段 | +|-----|---------|---------| +| 简单查询 | <2 秒 | 意图路由 + 本地缓存 | +| 单系统操作 | <3 秒 | 流式输出 + 连接池 | +| 多系统聚合 | <8 秒 | 并行调用 + 推测性预拉 | +| 复杂推理 | <15 秒 | 流式输出 + 进度提示 | + +**架构优化:** +- 意图分类层:本地部署 Qwen-7B 做前置路由,<100ms。 +- 并行工具调用:多系统查询并发执行,取最慢者决定总延迟。 +- 流式输出:首字响应 <1 秒,避免用户等待焦虑。 + +--- + +## 八、最容易踩的坑 + +### 五大陷阱与预防措施 + +| 陷阱 | 表现 | 预防措施 | +|-----|------|---------| +| **过度承诺** | 员工期望 AI 万能,第一次失败就失去信任 | 明确告知能力边界,试点期只承诺"辅助"而非"替代" | +| **数据质量差** | AI 拿到垃圾输入,输出不可用 | 集成前做数据质量评估,建立数据清洗管道 | +| **部门 KPI 冲突** | 业务部门觉得"AI 抢饭碗",消极配合 | 高管背书,明确 AI 是"增效工具",与绩效挂钩 | +| **摊子铺太大** | 一次性 onboard 太多系统,哪个都没做好 | 严格遵循"先做深再做广",每个系统验证通过再扩展 | +| **合规一票否决** | 项目卡在合规审查数月 | 早期引入合规团队,隐私设计(Privacy by Design) | + +### 额外建议 +- **建立 AI 治理委员会**:IT、业务、合规、法务代表共同参与。 +- **设立"AI 体验官"**:从各业务线选拔早期使用者,收集反馈。 +- **准备 Plan B**:如果 AI 助手效果不达预期,保留传统操作路径。 + +--- + +## 九、度量体系 + +### 指标矩阵 + +| 类别 | 指标 | 目标值 | 采集方式 | 报告频率 | 负责人 | +|-----|------|-------|---------|---------|-------| +| **使用率** | DAU/MAU | >60% | 埋点统计 | 周报 | 产品经理 | +| | 人均交互次数 | >25 次/天 | 埋点统计 | 周报 | 产品经理 | +| | 7 日留存率 | >70% | 埋点统计 | 月报 | 产品经理 | +| **效率** | 任务完成时长 vs 手工 | 缩短 40% | A/B 测试 | 月报 | 业务分析师 | +| | 员工节省小时数 | >5 小时/周/人 | 问卷调查 + 系统日志 | 季报 | HR | +| **质量** | 用户满意度(NPS) | >50 | 问卷 | 月报 | 产品经理 | +| | AI 答错率 | <5% | 人工抽检 + 用户反馈 | 周报 | QA | +| | 人工纠错率 | <10% | 系统日志 | 周报 | QA | +| **成本** | 每 Query 成本 | <¥0.05 | Token 统计 | 周报 | 财务 | +| | 月总成本占 IT 预算 | <3% | 财务系统 | 月报 | CTO | +| **业务** | 关键 KPI 影响 | 正向 | 业务系统数据 | 季报 | CEO/业务负责人 | + +--- + +## 十、执行 Timeline + +**Month 1-2: 奠基期** +- 完成架构设计与技术选型。 +- 搭建权限网关与审计日志基础。 +- 完成合规审查与隐私设计。 +- 选定试点系统(人事+财务)。 +- 组建核心团队(PM + 2 后端 + 1 前端 + 1 QA)。 + +**Month 3-4: 核心开发** +- 完成 API 适配层(人事+财务)。 +- 实现意图分类与 Agent 编排。 +- 开发权限网关与 Token Exchange。 +- 搭建监控与成本看板。 +- 内部 Alpha 测试(IT 团队)。 + +**Month 5-6: Alpha 试点** +- 50 人试点上线(IT+HR)。 +- 仅开放查询类操作。 +- 收集反馈,迭代优化。 +- 验证成功标准(完成率>70%,错误率<5%)。 +- 准备 Beta 扩展。 + +**Month 7-9: Beta 扩展** +- 扩展至 100 人(10% 全公司)。 +- 开放中风险操作(需确认)。 +- 接入 CRM + 项目管理。 +- 启动 MCP 试点。 +- 验证成功标准(完成率>80%,错误率<3%)。 + +**Month 10-12: GA 推广** +- 扩展至 500 人(50% 全公司)。 +- 开放高风险操作(审批流)。 +- 全面 MCP 迁移。 +- 性能优化与成本调优。 +- 业务 KPI 影响评估。 + +**Month 13+: 全面运营** +- 100% 员工覆盖。 +- 持续优化与场景扩展。 +- 建立 AI 治理常态化机制。 +- 探索 AI 驱动的业务创新。 \ No newline at end of file diff --git a/enterprise_ai_assistant_proposal.md b/enterprise_ai_assistant_proposal.md new file mode 100644 index 00000000..dbdca266 --- /dev/null +++ b/enterprise_ai_assistant_proposal.md @@ -0,0 +1,295 @@ +--- +title: 企业级 AI 工作助手技术选型与实施路径建议书 +subtitle: 数字化转型关键阶段的技术规划与落地指南 +header: 内部资料 - 仅限管理层审阅 +footer: MateClaw AI 咨询团队 © 2026 +--- + +# 企业级 AI 工作助手:技术选型与实施路径建议书 + +## 一、底座架构选择 + +### 推荐方案:Spring AI Alibaba + 自定义 Agent 编排层 + +**核心理由:** + +| 评估维度 | Spring AI Alibaba | LangChain | LlamaIndex | 大厂托管平台 | +|---------|------------------|-----------|------------|-------------| +| Java 生态集成 | ✅ 原生 Spring Boot | ❌ Python 为主 | ❌ Python 为主 | ⚠️ 黑盒 | +| 内部部署支持 | ✅ 完全支持 | ✅ 支持 | ✅ 支持 | ❌ 仅 SaaS | +| 数据隐私 | ✅ 数据不出域 | ✅ 可控 | ✅ 可控 | ❌ 数据出境风险 | +| 定制深度 | ✅ 源码级可控 | ✅ 灵活 | ⚠️ 偏 RAG | ❌ 受限 | +| 社区成熟度 | ⚠️ 成长中 | ✅ 最成熟 | ✅ 成熟 | ✅ 大厂背书 | +| 工程化程度 | ✅ 企业级规范 | ⚠️ 偏弱 | ⚠️ 中等 | ✅ 开箱即用 | + +**权衡点:** +- Spring AI Alibaba 社区相对较小,遇到问题需更多自研能力 +- 建议搭配 LiteLLM 做模型路由抽象,避免框架层绑定 + +**架构建议:** +``` +员工请求 → 意图分类网关 → Agent 编排层(Spring AI) → 工具调用层 → 下游系统 + ↓ + 权限网关 + 审计日志 +``` + +--- + +## 二、LLM 模型选型策略 + +### 模型策略矩阵 + +| 任务类型 | 推荐模型 | 备选模型 | 单次成本(¥) | 月调用占比 | +|---------|---------|---------|------------|-----------| +| 意图分类/路由 | Qwen-Turbo / DeepSeek-V3 | GLM-4-Air | 0.002 | 100% | +| 简单问答/查询 | Qwen-Plus | DeepSeek-V3 | 0.008 | 40% | +| 复杂推理/多步 | GPT-4o / Claude 3.5 Sonnet | Qwen-Max | 0.05 | 25% | +| 视觉理解 | GPT-4o | Claude 3.5 Sonnet | 0.08 | 10% | +| 长文档摘要 | Qwen-Long | Kimi | 0.02 | 15% | +| 代码生成 | DeepSeek-Coder / GPT-4o | Claude 3.5 | 0.04 | 10% | + +### Fallback 链设计 +``` +主模型请求 → 超时/失败 → 降级到备选模型 → 仍失败 → 返回"暂时无法处理,请稍后重试" +``` + +**关键机制:** +- **统一抽象层**:使用 LiteLLM 或自研 Model Router,业务代码不直接调用具体模型 API +- **成本监控**:按部门/用户/任务类型统计 token 消耗,设置月度预算告警(80% 预警,100% 熔断) +- **能力差异处理**:在工具定义中标注所需能力(如 `requires_vision=true`),路由时自动匹配 + +--- + +## 三、与企业现有系统集成方式 + +### 推荐路径:混合模式 + 渐进迁移 + +**阶段一(1-3个月):传统 API 适配层** +- 为高频系统(人事、财务、CRM)编写标准 REST API 适配器 +- 使用 OpenAPI/Swagger 规范定义接口契约 +- 优势:快速见效,验证核心流程 + +**阶段二(4-6个月):MCP 试点** +- 选择 2-3 个新系统或改造成本低的系统试点 MCP Server +- 验证 MCP 协议稳定性、工具发现机制、错误处理 +- 建立内部 MCP 开发规范 + +**阶段三(7-12个月):全面迁移** +- 存量系统逐步包装为 MCP Server +- 新系统默认采用 MCP 协议 +- 保留 API 适配层作为 fallback + +### 试点顺序建议 +1. **第一批**:人事系统 + 财务系统(验证"预算查询"场景) +2. **第二批**:CRM + 项目管理(验证"会议准备"场景) +3. **第三批**:知识库 + 合同管理 + 审批流 + +--- + +## 四、权限与数据安全 + +### 推荐方案:权限网关 + OAuth 2.0 Token Exchange(方案 c+d 混合) + +**架构:** +``` +员工 → AI助手 → 权限网关 → 下游系统 + ↓ + 审计日志中心 +``` + +**权限流转:** +1. 员工登录 AI 助手时,获取员工身份 token +2. AI 助手发起下游请求时,通过 Token Exchange 获取**受限委托 token** +3. 权限网关根据员工角色 + 数据敏感度 + 操作类型进行实时鉴权 +4. 敏感操作(如查看薪资)需二次确认或动态权限提升 + +**四种方案对比:** +| 方案 | 安全性 | 复杂度 | 可维护性 | 推荐度 | +|-----|-------|-------|---------|-------| +| (a) 员工 token 直调 | 高 | 中 | 中 | ⭐⭐⭐ | +| (b) 统一服务账号 | 低 | 低 | 高 | ⭐ | +| (c) 权限网关代理 | 高 | 高 | 高 | ⭐⭐⭐⭐ | +| (d) Token Exchange | 高 | 高 | 中 | ⭐⭐⭐⭐ | + +**审计日志要求:** +- 每次 AI 代表员工的操作必须记录:`who(员工) → what(操作) → when(时间) → which_system(系统) → result(结果)` +- 日志不可篡改,保留至少 3 年 +- 支持按员工/系统/时间范围检索 + +--- + +## 五、Agent 能力边界与人工审批 + +### Risk-Based 审批策略 + +| 风险等级 | 判定标准(程序化) | 操作示例 | 处理方式 | +|---------|------------------|---------|---------| +| **低风险** | 只读操作、聚合查询、生成报告、不影响他人 | 查预算、查项目进度、生成周报 | AI 直接执行 | +| **中风险** | 写入操作但可回滚、仅影响本人数据 | 提交报销、修改个人日程、创建草稿 | AI 执行 + 企微/钉钉通知员工确认 | +| **高风险** | 不可回滚、影响他人、涉及资金/合同/人事 | 删除项目、批量发邮件、调薪、审批合同 | 必须人工审批,走 OA 流程 | + +### 程序化判定规则 +```yaml +risk_level: + low: + - method in [GET, HEAD, OPTIONS] + - operation_type in [query, aggregate, generate_report] + medium: + - method in [POST, PUT, PATCH] + - has_rollback_mechanism == true + - affects_others == false + high: + - method in [DELETE] + - involves_financial_data == true + - affects_others == true + - operation in [delete_project, batch_email, salary_adjust] +``` + +### 审批流形态 +- **中风险**:企微/钉钉卡片通知,员工点击"确认"或"撤销",24 小时未操作自动撤销 +- **高风险**:对接企业现有 OA 审批系统,按业务规则路由到对应审批人 +- **紧急通道**:员工可随时在 AI 助手中查看待审批列表并加急处理 + +--- + +## 六、渐进式部署与风险控制 + +### 灰度策略 + +| 阶段 | 人群 | 场景 | 时长 | 成功标准 | +|-----|------|------|------|---------| +| **Alpha** | IT 团队 + HR 管理员(50人) | 仅查询类操作 | 4 周 | 任务完成率 >70%,错误率 <5%,满意度 >4.0/5 | +| **Beta** | 全公司 10%(100人) | 查询 + 中风险操作 | 6 周 | 任务完成率 >80%,错误率 <3%,满意度 >4.2/5 | +| **GA** | 全公司 50%(500人) | 全场景(含高风险审批) | 8 周 | 任务完成率 >85%,错误率 <2%,满意度 >4.3/5 | +| **Full** | 全公司 100% | 全场景 | 持续 | 持续优化 | + +### 熔断回退触发条件 +- 错误率连续 2 天 >15% +- 发生安全事件(数据泄露、越权访问) +- 用户满意度 <3.0/5 且持续 1 周 +- 核心系统响应超时率 >20% + +**回退机制**:一键切换回传统操作模式,所有 AI 操作自动转人工工单 + +--- + +## 七、性能与成本预算 + +### 成本估算(1000 员工 × 30 次/天) + +| 指标 | 数值 | +|-----|------| +| 日均 Query 数 | 30,000 | +| 平均 Token/Query | 2,500(输入 2K + 输出 500) | +| 月均 Token 总量 | 22.5 亿 | +| 模型混合成本 | ¥35,000 - ¥65,000/月 | +| 单次 Query 平均成本 | ¥0.04 - ¥0.07 | + +**成本优化措施:** +- 意图分类前置过滤:30% 简单问题走本地小模型或规则引擎 +- Prompt 缓存:相同模板缓存,减少重复 token +- 响应截断:非关键场景限制输出长度 + +### 性能目标 + +| 场景 | 延迟目标 | 优化手段 | +|-----|---------|---------| +| 简单查询 | <2 秒 | 意图路由 + 本地缓存 | +| 单系统操作 | <3 秒 | 流式输出 + 连接池 | +| 多系统聚合 | <8 秒 | 并行调用 + 推测性预拉 | +| 复杂推理 | <15 秒 | 流式输出 + 进度提示 | + +**架构优化:** +- 意图分类层:本地部署 Qwen-7B 做前置路由,<100ms +- 并行工具调用:多系统查询并发执行,取最慢者决定总延迟 +- 流式输出:首字响应 <1 秒,避免用户等待焦虑 + +--- + +## 八、最容易踩的坑 + +### 五大陷阱与预防措施 + +| 陷阱 | 表现 | 预防措施 | +|-----|------|---------| +| **过度承诺** | 员工期望 AI 万能,第一次失败就失去信任 | 明确告知能力边界,试点期只承诺"辅助"而非"替代" | +| **数据质量差** | AI 拿到垃圾输入,输出不可用 | 集成前做数据质量评估,建立数据清洗管道 | +| **部门 KPI 冲突** | 业务部门觉得"AI 抢饭碗",消极配合 | 高管背书,明确 AI 是"增效工具",与绩效挂钩 | +| **摊子铺太大** | 一次性 onboard 太多系统,哪个都没做好 | 严格遵循"先做深再做广",每个系统验证通过再扩展 | +| **合规一票否决** | 项目卡在合规审查数月 | 早期引入合规团队,隐私设计(Privacy by Design) | + +### 额外建议 +- **建立 AI 治理委员会**:IT、业务、合规、法务代表共同参与 +- **设立"AI 体验官"**:从各业务线选拔早期使用者,收集反馈 +- **准备 Plan B**:如果 AI 助手效果不达预期,保留传统操作路径 + +--- + +## 九、度量体系 + +### 指标矩阵 + +| 类别 | 指标 | 目标值 | 采集方式 | 报告频率 | 负责人 | +|-----|------|-------|---------|---------|-------| +| **使用率** | DAU/MAU | >60% | 埋点统计 | 周报 | 产品经理 | +| | 人均交互次数 | >25 次/天 | 埋点统计 | 周报 | 产品经理 | +| | 7 日留存率 | >70% | 埋点统计 | 月报 | 产品经理 | +| **效率** | 任务完成时长 vs 手工 | 缩短 40% | A/B 测试 | 月报 | 业务分析师 | +| | 员工节省小时数 | >5 小时/周/人 | 问卷调查 + 系统日志 | 季报 | HR | +| **质量** | 用户满意度(NPS) | >50 | 问卷 | 月报 | 产品经理 | +| | AI 答错率 | <5% | 人工抽检 + 用户反馈 | 周报 | QA | +| | 人工纠错率 | <10% | 系统日志 | 周报 | QA | +| **成本** | 每 Query 成本 | <¥0.05 | Token 统计 | 周报 | 财务 | +| | 月总成本占 IT 预算 | <3% | 财务系统 | 月报 | CTO | +| **业务** | 关键 KPI 影响 | 正向 | 业务系统数据 | 季报 | CEO/业务负责人 | + +--- + +## 十、执行 Timeline + +``` +Month 1-2: 奠基期 +├── 完成架构设计与技术选型 +├── 搭建权限网关与审计日志基础 +├── 完成合规审查与隐私设计 +├── 选定试点系统(人事+财务) +└── 组建核心团队(PM + 2 后端 + 1 前端 + 1 QA) + +Month 3-4: 核心开发 +├── 完成 API 适配层(人事+财务) +├── 实现意图分类与 Agent 编排 +├── 开发权限网关与 Token Exchange +├── 搭建监控与成本看板 +└── 内部 Alpha 测试(IT 团队) + +Month 5-6: Alpha 试点 +├── 50 人试点上线(IT+HR) +├── 仅开放查询类操作 +├── 收集反馈,迭代优化 +├── 验证成功标准(完成率>70%,错误率<5%) +└── 准备 Beta 扩展 + +Month 7-9: Beta 扩展 +├── 扩展至 100 人(10% 全公司) +├── 开放中风险操作(需确认) +├── 接入 CRM + 项目管理 +├── 启动 MCP 试点 +└── 验证成功标准(完成率>80%,错误率<3%) + +Month 10-12: GA 推广 +├── 扩展至 500 人(50% 全公司) +├── 开放高风险操作(审批流) +├── 全面 MCP 迁移 +├── 性能优化与成本调优 +└── 业务 KPI 影响评估 + +Month 13+: 全面运营 +├── 100% 员工覆盖 +├── 持续优化与场景扩展 +├── 建立 AI 治理常态化机制 +└── 探索 AI 驱动的业务创新 +``` + +--- + +*本建议书涵盖从技术选型到落地运营的全链路规划。如需进一步细化某个维度的技术方案或调整成本估算,请随时联系项目组。* \ No newline at end of file diff --git a/mateclaw-server/src/main/java/vip/mate/channel/ChannelMessageRouter.java b/mateclaw-server/src/main/java/vip/mate/channel/ChannelMessageRouter.java index ecff71fd..5478cfa8 100644 --- a/mateclaw-server/src/main/java/vip/mate/channel/ChannelMessageRouter.java +++ b/mateclaw-server/src/main/java/vip/mate/channel/ChannelMessageRouter.java @@ -96,8 +96,47 @@ public class ChannelMessageRouter { /** 每个渠道的队列容量 */ private static final int QUEUE_CAPACITY = 1000; - /** 防抖等待时间(毫秒) */ - private static final long DEBOUNCE_MS = 500; + /** 防抖等待时间(毫秒)。Package-private for unit-test access. */ + static final long DEBOUNCE_MS = 500; + + /** + * Extended debounce window for suspected paste-split scenarios. WeCom + * (and other IM clients) silently split a single pasted long prompt + * into 2-4 separate messages when it exceeds the per-frame limit + * (~2000 chars). The fragments arrive 0.5-2s apart, which means the + * default {@link #DEBOUNCE_MS} flushes the first fragment before the + * second one arrives — the agent then sees a torn context, calls the + * LLM on a partial prompt, and gets re-triggered when the next + * fragment lands. When merged content exceeds + * {@link #LONG_TEXT_THRESHOLD} we extend the window so the merger has + * time to absorb the rest. + *
+ * Package-private for unit-test access. + */ + static final long LONG_DEBOUNCE_MS = 2500; + + /** + * Content length (chars) above which we treat the message as a likely + * paste-split fragment. 1500 sits below the typical ~2000-char IM + * client split point while staying well above any normally-typed + * message, so the long-debounce path doesn't penalize ordinary + * chatting. A short typed "hello" still flushes in 500ms. + *
+ * Package-private for unit-test access. + */ + static final int LONG_TEXT_THRESHOLD = 1500; + + /** + * Pick the debounce window: extend to {@link #LONG_DEBOUNCE_MS} when + * either the new arrival or the accumulated merged buffer looks like + * a paste-split fragment, otherwise stay at {@link #DEBOUNCE_MS}. + *
+ * Package-private + static so tests can pin the threshold without + * spinning up the whole router (which has 12+ injected dependencies). + */ + static long pickDebounceMs(int currentMergedLength) { + return currentMergedLength > LONG_TEXT_THRESHOLD ? LONG_DEBOUNCE_MS : DEBOUNCE_MS; + } /** * Plan-Execute SSE events that the Web Console mirror needs to see when @@ -223,7 +262,11 @@ public class ChannelMessageRouter { log.info("[{}] Enqueuing message: sender={}, conversationId={}, agentId={}", channelType, message.getSenderId(), conversationId, agentId); - // 防抖:同一会话 500ms 内的连续消息合并 + // Debounce + adaptive merge: same conversation messages within the + // (500ms / 2.5s) window get concatenated into one. Adaptive: when + // the merged buffer crosses the LONG_TEXT_THRESHOLD we extend to + // LONG_DEBOUNCE_MS so paste-split fragments arrive together + // instead of triggering one agent call per piece. synchronized (pendingMessages) { PendingMessage existing = pendingMessages.get(conversationId); if (existing != null) { @@ -232,18 +275,31 @@ public class ChannelMessageRouter { existing.timer.cancel(false); } existing.appendContent(message.getContent()); + int mergedLen = existing.getMergedContent().length(); + long debounceMs = pickDebounceMs(mergedLen); existing.timer = debounceScheduler.schedule( - () -> flushPending(conversationId), DEBOUNCE_MS, TimeUnit.MILLISECONDS); - log.debug("[{}] Message merged with pending (debounce): conversationId={}", - channelType, conversationId); + () -> flushPending(conversationId), debounceMs, TimeUnit.MILLISECONDS); + if (debounceMs > DEBOUNCE_MS) { + log.info("[{}] Long-text merger active: conversationId={}, mergedLen={}, debounce={}ms (paste-split suspected)", + channelType, conversationId, mergedLen, debounceMs); + } else { + log.debug("[{}] Message merged with pending (debounce {}ms): conversationId={}", + channelType, debounceMs, conversationId); + } return; } // 首条消息,创建 PendingMessage 并设定防抖定时器 PendingMessage pending = new PendingMessage(message, adapter, channelEntity); pendingMessages.put(conversationId, pending); + int firstLen = message.getContent() != null ? message.getContent().length() : 0; + long debounceMs = pickDebounceMs(firstLen); pending.timer = debounceScheduler.schedule( - () -> flushPending(conversationId), DEBOUNCE_MS, TimeUnit.MILLISECONDS); + () -> flushPending(conversationId), debounceMs, TimeUnit.MILLISECONDS); + if (debounceMs > DEBOUNCE_MS) { + log.info("[{}] Long-text merger armed on first message: conversationId={}, len={}, debounce={}ms", + channelType, conversationId, firstLen, debounceMs); + } } }