基于钉钉机器人的 Qoder CLI / Claude Code 双引擎 AI 助手实践

阿里妹导读

文章内容基于作者个人技术实践与独立思考，旨在分享经验，仅代表个人观点。

一、背景与问题

在闪购搜索团队的日常工作中，我们需要频繁地进行搜索问题排查、性能分析、实验管理等操作。这些操作分散在多个平台（SLS日志、TPP实验平台、代码仓库等），效率低下。

我们的目标是：在钉钉群里直接对话一个AI助手，它能代替人去查日志、看实验、分析性能、甚至部署代码。

然而面临几个核心挑战：

挑战	具体描述
内网部署限制	服务部署在内网，无法暴露公网回调地址，传统Webhook方案不可行
实时性要求	AI推理耗时较长(30s-120s)，用户无法接受"发消息→等2分钟→一次性返回"
安全性要求	需要权限隔离，非管理员不能执行写操作(部署代码、修改配置等)
工具集成需求	需要访问代码仓库、日志系统、实验平台等多种外部工具

二、方案概览

2.1 整体架构

我们最终采用 "钉钉 Stream + CLI 代理" 的方案：

┌────────────────────────────────────────────────────────────────┐│                    钉钉群 / 单聊                               │├────────────────────────────────────────────────────────────────┤│  钉钉 Stream WebSocket 长连接（内网直通，无需公网回调）        │├────────────────────────────────────────────────────────────────┤│                  Java 服务（alsc-intervene）                    ││  ┌──────────────────────────────────────────────────────────┐  ││  │  DingTalkStreamService                                    │  ││  │  • 权限校验（管理员 vs 只读用户）                        │  ││  │  • 上下文管理（LRU + TTL + 滑动窗口）                    │  ││  │  • 并发控制（线程池 10-15）                              │  ││  │  • AI卡片投放与流式更新                                  │  ││  └──────────────────────────────────────────────────────────┘  ││                           │                                    ││                           ▼                                    ││  ┌──────────────────────────────────────────────────────────┐  ││  │  CLI 代理层（ProcessBuilder）                             │  ││  │  • Qoder CLI / Claude Code（可切换）                     │  ││  │  • stdbuf -oL 行缓冲优化                                │  ││  │  • 120s 超时保护 + 异常杀进程                           │  ││  └──────────────────────────────────────────────────────────┘  ││                           │                                    ││                           ▼                                    ││              MCP Server（工具调用层）                          │└────────────────────────────────────────────────────────────────┘

2.2 关键技术选型

组件	方案	选择理由
消息通道	钉钉 Stream（WebSocket）	内网无需公网回调地址，完全规避DNS/防火墙限制
AI引擎	CLI 代理模式	轻量无框架依赖，复用成熟 CLI 生态
流式展示	钉钉 AI 卡片	原生支持打字机效果，用户体验好
进程管理	Java ProcessBuilder	进程级隔离，一个请求一个进程，互不影响
工具扩展	MCP（Model Context Protocol）	标准化协议，可插拔配置驱动
上下文存储	内存 LinkedHashMap	自动 LRU 淘汰，无需外部存储

三、引擎选型：

从 Qoder CLI 到 Claude Code

3.1 最初选择 Qoder CLI

项目最初选择 Qoder CLI 作为 AI 引擎，主要考虑：

内部产品，接入方便，有现成的 Skills 和 MCP 生态
CLI 模式天然适合服务端 spawn 调用
支持 stream-json 流式输出

3.2 遇到的问题

实际使用中发现，Qoder CLI 在复杂问题排查场景下的表现不如预期：

对于需要多步推理的复杂排查（如跨系统问题定位），回答质量有时不够准确
与 Qoder IDE 桌面端相比，CLI 模式的能力有一定差距

3.3 引入 Claude Code

为了提升复杂场景下的回答质量，我们后续引入了 Claude Code 作为替代引擎。实际效果验证：

复杂问题排查能力显著更强：对于涉及多系统、多步骤的排查场景，Claude Code 的推理深度和准确性明显优于之前的方案
MCP 工具调用更稳定：工具调用的成功率和参数构造准确度更高

目前两个引擎并行部署，通过不同的入口调用：

Qoder CLI：钉钉 Stream 入口（群聊场景）
Claude Code：HTTP SSE 入口 + 独立钉钉机器人

四、Docker 部署方案

4.1 部署架构

两个引擎部署在同一个 Docker 容器内，共享工作目录和 MCP 配置：

Docker 容器├── /home/admin/qoder-workspace/     # 共享工作目录│   ├── .mcp.json                    # MCP服务配置│   ├── AGENTS.md                    # Qoder CLI 知识入口│   └── CLAUDE.md                    # Claude Code 指令文件├── /home/admin/.qoder/              # Qoder CLI 专属配置│   ├── settings.json                # MCP server列表│   ├── mcp-oauth-tokens.json        # OAuth认证token│   └── skills/                      # 安装的Skills├── /home/admin/.claude/             # Claude Code 专属配置│   └── settings.json                # 环境变量 + 权限└── /opt/mcp-auth/                   # Claude MCP认证文件

4.2 Dockerfile 核心设计

FROM reg.docker.alibaba-inc.com/alibase/alios7u2-min# 基础运行时RUN yum install -y ajdk11-11.0.27.26 nodejs git# 安装双引擎RUN npm install -g @qoder-ai/qodercli \        --registry=https://registry.npm.alibaba-inc.com && \    npm install -g @ali/claude-code@2.1.144 \        --registry=https://registry.npm.alibaba-inc.com# 部署工作区COPY qoder-workspace/ /home/admin/qoder-workspace/# Qoder CLI 认证COPY qoder-home/.qoder/ /home/admin/.qoder/RUN chmod 600 /home/admin/.qoder/mcp-oauth-tokens.json && \    chmod 444 /home/admin/.qoder/mcp-oauth-clients.json# Claude Code 认证COPY claude-home/.claude/ /home/admin/.claude/COPY claude-mcp-auth/ /opt/mcp-auth/RUN ln -sf /opt/mcp-auth /home/admin/.mcp-auth

4.3 Java 层调用方式

两个引擎的调用方式几乎相同，都是通过 ProcessBuilder spawn 子进程：

// Qoder CLIProcessBuilder pb = new ProcessBuilder(    "stdbuf", "-oL", "qodercli",    "-p", prompt,    "--output-format", "stream-json",    "--yolo", "--max-turns", "10",    "-w", "/home/admin/qoder-workspace");pb.environment().put("QODER_PERSONAL_ACCESS_TOKEN", qoderToken);// Claude CodeProcessBuilder pb = new ProcessBuilder(    claudeCliPath, "-p", prompt,    "--output-format", "stream-json",    "--verbose", "--max-turns", "5");pb.environment().put("ANTHROPIC_AUTH_TOKEN", anthropicToken);

两者输出格式统一为 stream-json，Java 层的流式解析、AI卡片更新逻辑完全复用。

五、MCP 工具集成与 OAuth 认证跳过方案

5.1 MCP 是什么

MCP（Model Context Protocol）是 AI 调用外部工具的标准化协议。通过 MCP，AI 可以像人一样去调用各种平台的 API——查代码、看日志、管实验，实现"问一句话，帮你查完所有系统"的效果。

我们从本地常用的 MCP 服务中选择了一部分部署到远端，覆盖代码仓库、日志查询、实验管理等核心场景。

5.2 MCP 认证问题

MCP 服务默认采用 OAuth2 认证流程：

客户端向 MCP 网关发起请求
网关返回 401 + OAuth discovery URL
客户端走 OAuth 授权码流程获取 access_token
后续请求携带 Bearer token

这个流程在本地开发时没问题（浏览器打开授权页面点击授权），但在无头服务器（Docker容器）上完全行不通——没有浏览器，无法完成交互式授权。

5.3 跳过 OAuth 的方案：
静态 Bearer Token

我们的解决方案是预先获取 token，以静态方式注入配置文件，跳过运行时的 OAuth 流程：

// .mcp.json - 直接在 headers 中携带 Bearer token{  "mcpServers": {    "code": {      "type": "streamable-http",      "url": "https://mcp.alibaba-inc.com/code/mcp",      "headers": {        "Authorization": "Bearer mcpa_xxxxxxxxxxxxxxxx"      }    },    "sls-mcp": {      "type": "streamable-http",      "url": "https://mcp.alibaba-inc.com/sls-mcp/mcp",      "headers": {        "Authorization": "Bearer mcpa_yyyyyyyyyyyyyyyy"      }    }  }}

工作原理：

本地预获取：在本地开发环境通过正常 OAuth 流程获取 access_token（mcpa_ 前缀的长期token）
静态注入：将 token 写入 .mcp.json 的 headers.Authorization 字段
直接认证：CLI 发起 MCP 请求时直接携带此 header，MCP 网关验证 token 有效即放行，完全跳过 OAuth 握手
Docker 构建时打包：.mcp.json 在 Dockerfile 中 COPY 进容器，启动即可用

Token 管理要点：

Token 有有效期，过期后需要重新获取并更新配置
.mcp.json 文件权限设为 600，防止泄露
mcp-oauth-clients.json 设为 444 只读，防止运行时被 DCR（Dynamic Client Registration）覆盖

5.4 Qoder CLI 的 OAuth Token 方式

Qoder CLI 还支持另一种认证方式——通过 mcp-oauth-tokens.json 文件存储 OAuth token：

[  {    "serverName": "code",    "token": {      "accessToken": "mcpa_xxxxx",      "refreshToken": "mcpr_xxxxx",      "expiresAt": 1782186490063,      "tokenType": "Bearer"    },    "clientId": "mcp-client-xxxx",    "tokenUrl": "https://mcp.alibaba-inc.com/oauth/token",    "mcpServerUrl": "https://mcp.alibaba-inc.com/code/mcp"  }]

理论上 refreshToken 可以自动续期，但实测发现远端环境中 token 刷新不够可靠，因此 Claude Code 端我们统一使用 .mcp.json 静态 headers 方案，更加稳定。

六、钉钉 Stream 集成核心实现

6.1 为什么选择 Stream 模式

传统钉钉机器人采用 HTTP 回调，要求服务有公网可达地址。Stream 模式通过 WebSocket 长连接解决了这个问题——服务主动连接钉钉服务器，无需暴露任何端口。

@PostConstructpublic void init() {    if (!streamEnabled) return;    OpenDingTalkClient client = OpenDingTalkStreamClientBuilder.custom()        .credential(new AuthCredential() {{            setClientId(appKey);            setClientSecret(appSecret);        }})        .registerCallbackListener("/v1.0/im/bot/messages/get", this)        .build();    client.start();}

6.2 进程管理与流式输出

public void chatStream(String prompt, String workspace,                        Consumer<String> lineConsumer, Consumer<Process> processConsumer) {    List<String> cmd = Arrays.asList(        "stdbuf", "-oL",           // 强制行缓冲        cliPath, "-p", prompt,        "--output-format", "stream-json",        "--yolo", "--max-turns", "10",        "-w", workspace    );    ProcessBuilder pb = new ProcessBuilder(cmd);    pb.environment().put("QODER_PERSONAL_ACCESS_TOKEN", token);    pb.redirectErrorStream(true);    Process process = pb.start();    processConsumer.accept(process);    try (BufferedReader reader = new BufferedReader(            new InputStreamReader(process.getInputStream()), 256)) {        String line;        while ((line = reader.readLine()) != null) {            lineConsumer.accept(line);        }    }    if (!process.waitFor(120, TimeUnit.SECONDS)) {        process.destroyForcibly();    }}

关键设计点：

stdbuf -oL：强制行缓冲，避免 Node.js 4KB 全缓冲导致的延迟
256字节 BufferedReader：Java 侧小缓冲确保及时输出
异常即杀进程：consumer 异常立即 destroyForcibly，停止消耗推理额度
进程引用暴露：支持用户发"停止"命令时主动中断

6.3 AI卡片流式更新

// 频率控制：累计超50字符才更新一次if (fullContent.length() - lastUpdateLen > 50) {    String content = fullContent.length() > 3000         ? fullContent.substring(0, 3000)        : fullContent.toString();    cardService.streamUpdate(trackId, content, false, false);    lastUpdateLen = fullContent.length();}

6.4 用户上下文管理（三重防护）

private final LinkedHashMap<String, UserContext> contextMap =    new LinkedHashMap<>(16, 0.75f, true) {        @Override        protected boolean removeEldestEntry(Entry<String, UserContext> eldest) {            return size() > 500;        }    };

保护层	机制	触发条件	效果
第一层	TTL过期	48小时无活动	清空上下文
第二层	滑动窗口	单用户超200KB	FIFO删除最早对话
第三层	LRU淘汰	全局超500用户	淘汰最久未使用

6.5 权限隔离

管理员：完全权限（读写+命令执行+部署）
普通用户：只读模式（系统指令最高优先级强制约束）

6.6 并发控制

private final ExecutorService qoderExecutor = new ThreadPoolExecutor(    10, 15, 60L, TimeUnit.SECONDS,    new LinkedBlockingQueue<>(30),    new ThreadPoolExecutor.AbortPolicy());

七、知识自进化机制

五级知识沉淀模型，让 AI 越用越聪明：

L0  git history（自动追踪代码变更） ↓L1  .qoder/context/（每次任务的过程报告） ↓L2  .qoder/memory_recent.md（最近5次会话摘要） ↓L3  .qoder/rules/candidates/（候选规则，经验沉淀） ↓L4  AGENTS.md + P0-constraints.md（正式规则）

候选规则触发 ≥3 次且成功率 ≥80%，自动提议晋升为正式规则。

八、钉钉机器人配置与申请指南

8.1 创建机器人应用

登录钉钉开放平台[1]
创建企业内部应用 → 选择"机器人"类型，选群聊机器人即可（只需要主管审批）
获取 appKey 和 appSecret

8.2 开通必要权限

目前看下来内部申请的机器人默认都开通了下面三项重要的权限，如果有遗漏，可能得单独申请一下
| 权限名称 | 用途 |
|----------|------|
| 企业内机器人发送消息 | 主动回复用户消息 |
| 互动卡片实例写权限 | 创建和投放AI卡片 |
| AI卡片流式更新权限 | 实现打字机效果 |

8.3 启用 Stream 模式

机器人配置页 → "消息接收模式" → Stream 模式
无需填写回调URL
发布到组织内

8.4 AI卡片模板配置

进入卡片平台[2]
新建卡片模板 → 场景选"消息卡片 + AI卡片"
开启"流式组件"开关
记录模板ID配置到 application.properties

8.5 关键配置项

dingtalk.stream.enabled=true           # Stream开关（预发/线上设false）dingtalk.app.key=${DINGTALK_APP_KEY}   # antx注入dingtalk.app.secret=${DINGTALK_APP_SECRET}dingtalk.robot.code=${DINGTALK_ROBOT_CODE}

8.6 注意事项