企业官网建设流程全解析

1. 从“AI 员工”这个说法说起：dsh-waker 到底想解决什么问题

第一次看到“dsh-waker”这个名字，我脑子里蹦出来的不是“唤醒”，而是“待命”。waker 这个词在系统里通常跟“唤醒源”“触发器”挂钩，放到 dsh 这个插件体系里，它要干的事情其实很直白：让一个挂在 IM 里的 AI 角色，从“你问一句它答一句”的被动状态，变成“有事它能主动找你、你不在它也能自己动起来”的状态。这就是所谓“AI 员工”和普通聊天机器人的分水岭。

我接触过不少团队做内部助手，卡点几乎一模一样：模型接进来了，知识库也灌了，但用起来还是像个搜索框。原因不复杂——它没有“工作时间”的概念，没有“任务队列”的概念，更没有“到点了该提醒谁”的概念。dsh-waker 这类插件补的就是这一层。它把 IM 当成了 AI 员工的工位，把消息通道当成了任务总线，让 AI 能定时唤醒、按事件唤醒、按条件唤醒。

这篇文章适合三类人看：一是正在用 dsh 搭内部工具、想让 AI 从玩具变成生产力的开发者；二是做 IM 机器人、想理解“主动式 AI”怎么落地的人；三是单纯对 dsh 插件机制好奇、想自己写一个 waker 类插件的同学。我会把设计思路、核心机制、实操步骤、踩坑记录都摊开讲，代码和配置尽量给到能直接抄的程度。

需要先说明一点：dsh 生态里插件命名和接口在不同版本间有差异，下面涉及的具体字段名、命令参数，我会按常见实践给出，你在自己环境里以实际版本为准，思路是通用的。

2. dsh-waker 的整体设计与选型思路

2.1 为什么是“唤醒”而不是“轮询”

很多人第一反应是写个定时脚本，每隔几分钟去查一次有没有新任务。这个方案能跑，但放到 IM 场景里很快就崩。原因有三个：第一，轮询频率高了浪费资源，频率低了响应慢；第二，IM 的消息是事件驱动的，你硬要用拉的方式去适配推的模型，中间必然要维护一堆状态；第三，多实例部署时轮询会重复触发，你得额外做分布式锁。

dsh-waker 走的是唤醒源注册的路子。它不自己造轮子去扫，而是把“什么时候该叫醒 AI”这件事抽象成几种唤醒源：时间唤醒、消息唤醒、外部事件唤醒。每种唤醒源注册到 waker 核心，核心只负责在条件满足时把任务投递出去。这样做的好处是职责清晰——waker 不管 AI 怎么回答，只管“什么时候该让它回答”。

提示：如果你现在的助手还是纯被动响应，先别急着上复杂的唤醒逻辑。把“消息唤醒”这一种跑通，确认 IM 通道稳定、AI 响应链路通畅，再叠加时间唤醒和外部事件，否则出问题你分不清是哪一层。

2.2 唤醒源的三种类型与适用场景

时间唤醒最容易被低估。我见过一个团队用时间唤醒做“每天早上把昨天未关闭的工单整理成摘要发到群里”，就这一个功能，把项目经理从每天手动翻列表里解放出来了。它的价值不在于技术多难，而在于把“人记得要做的事”变成了“系统一定会做的事”。

消息唤醒是基础盘。但这里有个细节：不是所有消息都值得唤醒 AI。如果群里每句话都触发，AI 会变成噪音源。所以 waker 里必须有一层过滤，支持按前缀、按 @、按正则、按发送者白名单来筛。我一般建议默认只响应 @ 和特定前缀，比如!ask或/ai，这样用户有明确的预期。

外部事件唤醒是进阶玩法。它的核心是提供一个 HTTP 入口，外部系统 POST 一个事件过来，waker 校验签名后投递任务。这里要注意幂等——同一个事件重复推送不能重复触发，否则告警风暴的时候 AI 会被刷屏。

2.3 任务投递与并发控制的设计取舍

唤醒之后，任务不能直接丢给 AI 就完事。IM 场景下并发是真实存在的：一个群可能同时有多个人 @，外部事件可能短时间涌入几十条。如果每个唤醒都起一个独立请求，轻则限流，重则把模型配额打满。

我的做法是在 waker 和 AI 之间加一个任务队列，队列按“会话”维度做串行，按“全局”维度做限流。同一个会话里的任务排队执行，保证上下文不乱；全局限制同时执行的任务数，比如 3 到 5 个，超出的排队等待。这个设计不复杂，但能避免 90% 的并发事故。

注意：队列一定要有超时和丢弃策略。我踩过的坑是某个外部事件源疯狂重试，队列越堆越长，最后内存告警。后来加了单队列最大长度和任务过期时间，超过就直接丢弃并记日志，问题才稳住。

3. 核心机制拆解：唤醒、过滤、投递、回执

3.1 唤醒源的注册与生命周期

dsh 插件的典型结构是有一个入口文件，在激活时注册能力。dsh-waker 的入口大概长这样（以常见的插件写法为例，具体 API 名以你环境为准）：

// index.js 示意 module.exports = { name: 'dsh-waker', activate(ctx) { const waker = ctx.getService('waker'); // 注册时间唤醒 waker.registerSource('cron', { expression: '0 9 * * *', handler: async () => { await waker.dispatch({ sessionId: 'daily-report', prompt: '生成昨日工单摘要', priority: 'normal' }); } }); // 注册消息唤醒 waker.registerSource('message', { match: /^!ask\s+/, handler: async (msg) => { await waker.dispatch({ sessionId: msg.channelId, prompt: msg.content.replace(/^!ask\s+/, ''), priority: 'high' }); } }); } };

这里的关键是registerSource把唤醒源和 handler 绑定，handler 里只做“决定要不要投递”和“投递什么”，不直接调 AI。这样后续换模型、换通道，都不用动唤醒逻辑。

生命周期上，插件激活时注册，停用时注销。时间唤醒要记得在停用时清掉定时器，否则热重载的时候会注册多份，任务重复触发。这个坑我踩过，表现是晨报发了三遍，排查半天才发现是定时器没清。

3.2 消息过滤：怎么让 AI 不被噪音淹没

消息唤醒的过滤规则我一般分三层：

第一层是通道过滤。只监听指定的频道或私聊，其他一律忽略。配置里维护一个白名单，比如channels: ['team-dev', 'ops-alert']。

第二层是触发词过滤。支持前缀匹配、@ 匹配、正则匹配。前缀匹配最简单也最可控，!ask、/ai这种。@ 匹配适合群聊，用户 @ 机器人就触发。正则适合复杂场景，比如匹配工单号#\d+。

第三层是频率限制。同一个用户在同一会话里，短时间内重复触发要合并或拒绝。我一般设成 10 秒内同一用户只处理第一条，后面的返回“正在处理中”。这能防止有人手抖连发。

// 过滤逻辑示意 function shouldWake(msg, config) { if (!config.channels.includes(msg.channelId)) return false; if (config.mentionOnly && !msg.mentionsBot) return false; if (config.prefix && !msg.content.startsWith(config.prefix)) return false; const key = `${msg.channelId}:${msg.userId}`; if (isRateLimited(key, 10000)) return false; return true; }

3.3 任务投递与队列的串并行策略

投递这块的核心是“会话串行、全局限流”。会话串行保证同一个对话的上下文顺序正确，全局限流保护下游。

队列实现可以用内存队列加信号量，简单够用。如果要多实例部署，就得换成外部队列，比如基于 Redis 的列表。但大多数内部工具单实例就够了，别过度设计。

class TaskQueue { constructor({ concurrency = 3, maxLength = 100 }) { this.concurrency = concurrency; this.maxLength = maxLength; this.running = 0; this.queues = new Map(); // sessionId -> tasks[] } async push(task) { const q = this.queues.get(task.sessionId) || []; if (q.length >= this.maxLength) { log.warn('queue full, drop task', task.sessionId); return; } q.push(task); this.queues.set(task.sessionId, q); this.drain(); } async drain() { if (this.running >= this.concurrency) return; for (const [sessionId, q] of this.queues) { if (q.length === 0) continue; const task = q.shift(); this.running++; this.execute(task).finally(() => { this.running--; this.drain(); }); if (this.running >= this.concurrency) break; } } }

这段代码不复杂，但把并发控制的关键点都覆盖了：按会话排队、全局并发上限、队列满丢弃。实际用的时候把execute换成调 AI 的逻辑就行。

3.4 回执与失败重试：让“员工”靠谱

AI 员工和真人一样，会有“没回消息”的时候。可能是模型超时，可能是 IM 发送失败，可能是任务本身报错。waker 必须处理这些情况，否则用户会觉得这员工不靠谱。

我的策略是：任务执行结果分三类——成功、可重试失败、不可重试失败。超时和限流归为可重试，重试最多两次，间隔递增；参数错误、内容违规归为不可重试，直接回执错误信息。无论哪种，都要给用户一个明确的回执，不能石沉大海。

async function executeWithRetry(task, maxRetry = 2) { for (let i = 0; i <= maxRetry; i++) { try { const result = await callAI(task); await sendReply(task.sessionId, result); return; } catch (err) { if (!isRetryable(err) || i === maxRetry) { await sendReply(task.sessionId, `处理失败：${err.message}`); return; } await sleep(1000 * Math.pow(2, i)); } } }

提示：回执消息要带上任务标识，比如“任务 #123 已完成”。这样用户能对应上自己发的那条，排查问题时也有据可查。

4. 实操落地：从零把 dsh-waker 跑起来

4.1 环境准备与插件安装

假设你已经有一个可用的 dsh 环境，并且 IM 通道已经打通。第一步是拿到 dsh-waker 插件。如果它在市场里有，直接通过插件市场安装最省事；如果是本地开发，就把插件目录放到 dsh 的插件路径下，然后在配置里启用。

# 示意：通过 dsh 命令添加插件（具体命令以你的版本为准） dsh plugin add dsh-waker # 或者本地开发模式 dsh plugin link ./plugins/dsh-waker

安装完先别急着配复杂规则，用最小配置验证插件是否被正确加载。看日志里有没有dsh-waker activated之类的输出。如果没有，检查插件入口的name字段和目录名是否一致，这是最常见的加载失败原因。

4.2 最小可用配置：先让一个定时唤醒跑通

最小配置我建议只开一个时间唤醒，比如每分钟触发一次，往指定会话发一条测试消息。目的是验证“唤醒 -> 投递 -> AI 响应 -> IM 回执”整条链路。

# waker 配置示意 waker: sources: - type: cron name: test-heartbeat expression: '* * * * *' session: test-channel prompt: '回复：心跳正常' queue: concurrency: 2 maxLength: 50

跑通之后你会看到测试频道每分钟收到一条“心跳正常”。这一步看着简单，但它把最容易出问题的几个环节都串起来了：定时器是否生效、任务是否投递、AI 是否可达、IM 是否能发。任何一环断了，日志里都能定位。

4.3 配置消息唤醒与关键词规则

链路通了之后，加消息唤醒。配置里定义触发规则，我一般从最保守的开始：只响应 @ 机器人，且消息以!ask开头。

waker: sources: - type: message name: ask-trigger channels: ['team-dev', 'team-ops'] mentionOnly: true prefix: '!ask' rateLimit: window: 10000 max: 1

这里rateLimit的窗口和次数要根据团队习惯调。开发群可能问得频繁，窗口设短一点；运维群告警多，窗口设长一点避免刷屏。没有标准答案，跑一周看日志再调。

4.4 接入外部事件：webhook 的正确姿势

外部事件唤醒需要一个 HTTP 入口。dsh 插件一般可以注册路由，注册一个/waker/event的 POST 接口。外部系统调用时带上签名，waker 校验后投递任务。

ctx.registerRoute('POST', '/waker/event', async (req, res) => { const signature = req.headers['x-waker-sign']; if (!verifySignature(req.body, signature, config.secret)) { return res.status(401).json({ error: 'invalid signature' }); } const event = req.body; if (isDuplicate(event.id)) { return res.json({ ok: true, dedup: true }); } await waker.dispatch({ sessionId: event.targetSession, prompt: buildPromptFromEvent(event), priority: event.priority || 'normal' }); res.json({ ok: true }); });

签名校验和幂等是必须的。签名防止伪造请求，幂等防止重复触发。isDuplicate可以用事件 ID 加一个短过期时间的缓存实现，比如 5 分钟内同一 ID 只处理一次。

注意：webhook 入口不要暴露在公网无保护状态。至少要有签名校验，最好再加 IP 白名单。我见过有人图省事直接裸奔，结果被扫到之后疯狂触发任务，模型配额一夜清零。

4.5 参数计算：并发数、超时、重试怎么定

这几个参数没有魔法值，得根据你的模型响应时间和 IM 限流来算。

并发数：假设模型平均响应 5 秒，你希望最坏情况下 30 秒内处理完积压，那并发数大概是积压任务数 * 5 / 30。如果平时积压不超过 20 条，并发 3 到 4 就够。

超时：模型响应时间 P99 如果是 15 秒，超时设 20 到 25 秒比较合理。设太短会误杀正常请求，设太长会拖住队列。

重试间隔：第一次重试等 1 秒，第二次等 2 秒，这是指数退避的简化版。如果下游是限流导致的失败，退避时间要更长，比如 5 秒起。

5. 常见问题与排查技巧实录

5.1 唤醒不触发：从日志倒着查

唤醒不触发是最常见的问题。排查顺序我一般是从后往前：先确认任务有没有进队列，再看唤醒源有没有触发，最后看配置有没有加载。

如果队列里没有任务，说明唤醒源没触发。时间唤醒检查 cron 表达式和时区，消息唤醒检查过滤规则是不是太严，外部事件检查路由有没有注册上。如果队列里有任务但没执行，检查并发数是不是被占满、队列是不是满了被丢弃。

日志里我会在关键节点都打上标记：source triggered、task dispatched、task started、task finished。出问题时 grep 这几个关键词，一眼就能看出断在哪。

5.2 重复触发：定时器和幂等的坑

重复触发有两个典型来源。一是定时器没清理，热重载后注册了多份。解决办法是在插件停用钩子里清掉所有定时器，并且注册前先检查是否已存在同名源。

二是外部事件重复推送。这个靠幂等缓存解决，前面提过。但要注意缓存的过期时间，太短了防不住慢重试，太长了占内存。5 到 10 分钟是个折中。

5.3 AI 响应慢导致队列堆积

模型响应慢的时候，队列会堆积。如果只是偶尔慢，靠队列缓冲就行。如果持续慢，说明并发数或者模型选型有问题。可以先临时调大并发，但要注意下游限流。更根本的办法是把任务分级，高优先级的走快速通道，低优先级的排队或者降级处理。

我一般会给任务加priority字段，队列里高优先级插队。实现上可以用两个队列，高优先级队列先消费。这样告警类任务不会被日报类任务堵住。

5.4 IM 发送失败与消息格式问题

IM 发送失败常见原因有：频道 ID 写错、机器人没有发言权限、消息内容触发平台风控、消息太长被截断。排查时先看 IM 客户端返回的错误码，再对照平台文档。

消息格式上，AI 返回的 Markdown 在 IM 里可能渲染不正常。我的做法是在发送前做一次格式转换，把不支持的语法降级成纯文本或者平台支持的格式。这个转换逻辑最好做成可配置的，不同 IM 平台规则不一样。

5.5 常见问题速查表

提示：把这张表打印出来贴在工位上，出问题时按行排查，比临时抓瞎快得多。我自己的经验是，80% 的问题都能在前三行找到答案。

6. 一些实操心得与扩展方向

dsh-waker 这类插件最大的价值，是把 AI 从“问答工具”变成了“有工作节奏的协作者”。我自己的体会是，定时唤醒比消息唤醒更能体现这个价值，因为它让 AI 有了“主动”的属性。哪怕只是每天早上发一条摘要，用户对它的感知也会从“我用的工具”变成“帮我干活的同事”。

扩展方向上，我最近在试的是把唤醒源和任务结果做关联。比如一个外部事件唤醒后，AI 处理完的结果可以再触发下一个唤醒，形成简单的流水线。这需要 waker 支持任务完成后的回调注册，实现不难，但能让自动化程度上一个台阶。

另一个方向是唤醒源的动态管理。现在配置是静态的，改规则要重启。如果能通过 IM 命令动态增删唤醒源，比如发一条!waker add cron ...，灵活性会好很多。不过这会带来权限问题，得先想清楚谁能改。

最后分享一个小技巧：给每个唤醒源加一个“静默期”配置。比如告警类唤醒，同一个来源 5 分钟内只触发一次，避免告警风暴时 AI 被刷爆。这个配置在 waker 核心做比在每个源里做更省事，我后来统一挪到核心层了。