mirror of
https://gitee.com/mateos/mateclaw.git
synced 2026-09-13 03:13:41 +08:00
Inbound (WeCom):
- Save uploaded media under data/chat-uploads/{conversationId}/ with full
fileName/path/fileUrl/storedName/fileSize on the content part. Web mirrors
of an IM conversation now show real thumbnails instead of "未命名".
- Magic-byte sniff (PDF / PNG / JPEG / GIF / Office / ODF / archives /
audio / video) recovers a real extension when the platform omits filename
for forwarded files — no more PDFs labelled "file.bin".
- ZIP container peek distinguishes DOCX / XLSX / PPTX / VSDX / ODT / ODS /
ODP / EPUB / JAR from a plain zip via discriminator paths and the OASIS
mimetype entry.
Outbound (WeCom):
- Chunk upload field name corrected so server-side actually stores the
bytes — file messages used to arrive with correct filename/size but
empty content, breaking every PDF / DOCX / PPTX recipient.
- Scan agent text for served-file URLs in both the text-reply and
content-parts paths; fetch bytes from the in-memory generated-file
cache and dispatch through the native chunk upload + media message
protocol so users receive a tappable file card instead of an
unopenable markdown link. Cache miss surfaces a clear retry hint.
Async tool result forwarding:
- New AsyncTaskMediaDispatcher routes generation completions (image,
video, music, 3D model) to whichever IM channel the conversation is
bound to via ChannelSessionStore + ChannelManager. Web / webchat
conversations are intentionally skipped — their SSE stream already
renders the result.
- Wired into all four generation services so IM users actually receive
generated media as native attachments. Each part now carries an
absolute disk path so adapters read bytes locally instead of round-
tripping through an authenticated served URL.
Slack native file upload:
- SlackChannelAdapter overrides the content-parts dispatch. Image /
audio / video / file / model3d parts ride filesUploadV2 so users see a
file card with preview thumbnail bound to the same thread as the
originating message. Text parts continue through chat.postMessage.
- Resolves bytes from the part's local path, falls back to an HTTP fetch
of fully-qualified URLs.
IM approval hint visibility:
- IM-driven approve / deny / auto-cancel / replay-error hints now go
through saveMessage + tracker broadcast in addition to the channel
adapter, so a Web mirror viewing the same conversationId sees the
resolution. Previously hints reached only the IM channel; the Web
admin console had no record of the outcome.
Adaptive paste-merge debounce:
- WeCom and other IM clients silently split long pasted prompts into
fragments that arrive 0.5-2 seconds apart, missing the existing 500ms
merge window. The agent then saw torn context and emitted multiple
conflicting replies.
- When the merged buffer crosses a content-length threshold, extend the
debounce window so subsequent fragments arrive in time. Default
500ms unchanged for normal short messages.
12 KiB
12 KiB
| title | subtitle | header | footer |
|---|---|---|---|
| 企业级 AI 工作助手技术选型与实施路径建议书 | 数字化转型关键阶段的技术规划与落地指南 | 内部资料 - 仅限管理层审阅 | 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
试点顺序建议
- 第一批:人事系统 + 财务系统(验证"预算查询"场景)
- 第二批:CRM + 项目管理(验证"会议准备"场景)
- 第三批:知识库 + 合同管理 + 审批流
四、权限与数据安全
推荐方案:权限网关 + OAuth 2.0 Token Exchange(方案 c+d 混合)
架构:
员工 → AI助手 → 权限网关 → 下游系统
↓
审计日志中心
权限流转:
- 员工登录 AI 助手时,获取员工身份 token
- AI 助手发起下游请求时,通过 Token Exchange 获取受限委托 token
- 权限网关根据员工角色 + 数据敏感度 + 操作类型进行实时鉴权
- 敏感操作(如查看薪资)需二次确认或动态权限提升
四种方案对比:
| 方案 | 安全性 | 复杂度 | 可维护性 | 推荐度 |
|---|---|---|---|---|
| (a) 员工 token 直调 | 高 | 中 | 中 | ⭐⭐⭐ |
| (b) 统一服务账号 | 低 | 低 | 高 | ⭐ |
| (c) 权限网关代理 | 高 | 高 | 高 | ⭐⭐⭐⭐ |
| (d) Token Exchange | 高 | 高 | 中 | ⭐⭐⭐⭐ |
审计日志要求:
- 每次 AI 代表员工的操作必须记录:
who(员工) → what(操作) → when(时间) → which_system(系统) → result(结果) - 日志不可篡改,保留至少 3 年
- 支持按员工/系统/时间范围检索
五、Agent 能力边界与人工审批
Risk-Based 审批策略
| 风险等级 | 判定标准(程序化) | 操作示例 | 处理方式 |
|---|---|---|---|
| 低风险 | 只读操作、聚合查询、生成报告、不影响他人 | 查预算、查项目进度、生成周报 | AI 直接执行 |
| 中风险 | 写入操作但可回滚、仅影响本人数据 | 提交报销、修改个人日程、创建草稿 | AI 执行 + 企微/钉钉通知员工确认 |
| 高风险 | 不可回滚、影响他人、涉及资金/合同/人事 | 删除项目、批量发邮件、调薪、审批合同 | 必须人工审批,走 OA 流程 |
程序化判定规则
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 驱动的业务创新
本建议书涵盖从技术选型到落地运营的全链路规划。如需进一步细化某个维度的技术方案或调整成本估算,请随时联系项目组。