AI 赋能效能提升

选择 Claude Code CLI 而非直接调用 API：核心原因是 CLI 模式下 AI 可主动使用 Read、Grep、Glob 等工具自主导航代码库——搜索符号定义、追踪调用链、阅读配置文件——这种主动探索能力是深度问题分析的关键。直接调用 API 时上下文完全由调用方构建，AI 只能被动接收预设代码片段。

自建 relay 层的原因：需要将 Claude 的 stream-json 输出转换为标准 OpenAI SSE 格式；管理 CLI 子进程生命周期（启动、心跳、超时、优雅终止）；提供会话 JSONL 持久化和实时 WebSocket 查看能力；支持 Token 统计与成本核算。直接连接 CLI 无法满足生产环境的稳定性和可观测性要求。

选择 WebSocket 长连接而非 HTTP 回调：企业微信 2025 年推出的 WSS 模式不需要公网 URL、不需要消息加解密、原生支持流式推送，部署复杂度大幅降低。相比 HTTP 回调模式，无需公网域名和消息加解密配置。

部署架构：整体部署在一台 Windows Server 上，Claude CLI 通过 npm 全局安装，relay 编译为单一 Go 二进制（无外部依赖），wecom-server 通过 Python 直接运行。出站连接仅需 wss://openws.work.weixin.qq.com 和 Anthropic API，无需公网入站 URL。

并发模型：每个 bot 实例运行在独立 asyncio.Task 中，支持多 bot 并发。心跳循环和消息接收循环并发执行，每条用户消息通过 asyncio.create_task 异步处理避免阻塞主循环。全局 Semaphore(100) 限制同时 AI 调用数，TaskRegistry 统一管理运行中的任务，支持 stop 命令取消。

指数退避重连：WebSocket 断连后按 2^n 秒间隔重试（n 从 0 开始），上限 60 秒，订阅成功后重置计数器。既保证快速重连，又避免服务端过载时雪崩。

日志体系：四级分离——服务运行日志（按级别过滤）、聊天日志（JSONL 格式支持结构化查询）、CLI 原始输出日志、relay 中继日志，各自独立存储。

会话查看器：relay 层内置 Web 查看器，支持深色/浅色主题、Markdown 渲染、WebSocket 实时更新、72 小时自动清理。

关键技术难题与解决方案：

Windows CLI 调用限制——Windows CreateProcess 命令行参数约 32KB 限制，长 system prompt 无法通过参数传入。解决方案：将 prompt 写入临时文件，通过环境变量告知路径；用户消息通过 stdin 管道传入。

stream-json 括号感知解析——JSON 字符串值内可能包含换行符和嵌套括号，简单按行分割无法正确解析。实现字符级深度跟踪解析器：维护嵌套深度计数器 + 字符串内转义状态标志，逐字符扫描，仅在深度归零时才将累积 JSON 片段作为完整对象发出。

SSE 长连接稳定性——三层超时设计：total timeout 3600s（匹配企业微信 response_url 有效期）、sock_read 90s（借助上游心跳检测卡死）、relay 层每 30s 主动发送 SSE 心跳注释行防止中间代理断开。

resume 失败处理——会话 ID 可能因 CLI 重启而过期，relay 先尝试 --resume，通过缓冲前 N 个事件检测是否返回错误；失败则自动降级为 --session-id 创建新会话，用户无感知。

增强网关遵循四个设计原则：纵深防御（多层叠加互为兜底）、最小改动（在现有架构上叠加安全模块）、可观测（所有安全决策有日志可追溯）、优雅降级（守卫模块故障时自动放行）。

输入守卫采用"快速路径 + 深度检测"两级架构。快速路径做轻量正则匹配，毫秒级返回，覆盖六类注入检测：角色伪装（"你现在是..."）、指令覆盖（"ignore previous instructions"）、分隔符注入（伪造系统标记）、编码绕过（Base64/URL 编码/HTML 实体）、越狱模板（DAN 等已知模式）、零宽字符。同时实现意图三分类（产品问题/模糊/非产品），快速路径无法确定时调用 LLM 分类器深度分析，3 秒超时自动放行。基于企业微信身份实现角色感知路由——研发允许技术深度访问，普通用户执行严格审查。

速率限制采用双层令牌桶：用户级（容量 10，补充 1/s）防止单用户滥用，全局级（容量 100，补充 5/s）控制系统总负载。超出限流后请求进入 50 长度队列排队等待而非直接拒绝，30 秒超时返回"系统繁忙"。

输出守卫对流式回复实时扫描，核心原则"宁可误拦，不可漏放"。五层级规则匹配（滑动窗口保持最近 1000 字符上下文）：L1 代码块 → 脱敏替换为占位符、L2 密钥 Token → 完全拦截、L3 个人隐私信息 → 掩码处理（138****1234）、L4 敏感路径 → 脱敏替换、L5 客户数据 → 完全拦截。L2/L5 触发后后续所有 chunk 静默丢弃。

多轮对话防越狱：追踪用户行为模式，第 1 次追加安全警告，第 2 次进入严格模式（TTL 缩短至 10 分钟），第 3 次拒绝服务 1 小时并通知管理员。

优雅降级矩阵（fail-open）：所有安全模块故障时自动放行，不影响正常服务，依靠审计日志事后追溯。

software-product-issue-analyzer 技能是系统的核心分析能力，设计了四阶段渐进式问题分析流程：

阶段零：强制前置门禁。每次分析前必须先确认产品和版本信息。通过code_paths.json进行产品匹配，支持版本模糊匹配（如用户输入"5.4.1"可匹配"V5.4.1-F25.11.1"），并验证对应代码路径存在且可访问。任一步失败则终止分析并给出友好提示。这一步确保AI始终在正确的代码版本上工作，避免因版本错误导致的误判。

阶段一：问题信息收集。进行问题类型预检（区分软件问题与非软件问题）、安全防护检查（确保代码不泄露给外部）、附件大小检查（非图片文件超过1MB时拒绝直接读取，引导用户上传至指定位置）、信息收集引导（最多追问2轮，获取复现步骤、错误日志、影响范围等关键信息）。

阶段二：三步法问题分析。第一步确认问题并输出结构化摘要（问题现象、影响范围、初步判断）；第二步初步定位到架构层级和业务流程（判断问题属于前端、后端还是数据层）；第三步通过三种分析策略进行详细定位——自顶向下追踪（从入口点沿调用链深入）、错误反向追踪（从异常点回溯至根因）、数据流分析（跟踪数据在各模块间的流转路径）。AI在此阶段读取源代码进行深度分析，但不向用户展示代码细节。

阶段三：结论输出。根据分析确定性程度采用不同输出策略：准确定位根因时输出"问题本质+解决方案+预防建议"的三段式结论；存在多种可能性时输出"可能性排序+各假设的验证步骤+警示说明"，引导用户逐步排查。

多版本代码管理：同一产品有8个版本同时在线维护，不同客户使用不同版本。通过code_paths.json维护"产品→版本→代码路径"三层映射关系，阶段零的强制门禁确保每次分析都精确路由到用户所使用的代码版本目录。