DeepSeek 原型扩展事件源:11 步清单
DeepSeek 官方 008 Cookbook 写明新增一个 Source 要走 11 步、11 项核对,默认不接收任何消息、轮询 30 秒起、投递失败 5 秒重试。附 005 面板七条原则。
2026-11-13 13:24:07 · Editor: 刘立永DeepSeek 官方原型的 008 号文档写明:新增一个事件源要走 11 个编号步骤、11 项核对清单,配置默认值必须是「什么都不接收」。
11 个步骤,不是写个轮询脚本
这份 Cookbook 以虚构的消息队列命令行 hookq 为例,示范在 dsh-superagent-prototype 里新增一个名为 webhook 的 Source。文档把工作拆成四个职责:把事件翻译成 Trigger、定义接收与授权规则、提供回复与上下文、维护轮询循环。
落到代码上远不止一个脚本。要定义配置 schema 与自动生成的设置表单,实现 scope 决定监听范围、channel 决定回复去向,补上 threadContext、policy 准入名单、Executor 环境变量、插件入口、轮询循环、健康检查与测试;外围还要改构建入口、package.json 的 exports 与 cordis.patch.yml,并把模块与测试补进 007 架构文档的索引表,tests/docs.spec.ts 会检查索引是否完整。
最关键的是稳定 ID:Trigger ID、Thread ID 与 Channel address 会被持久化,事后改名会断开已有记录。示例用 key('webhook', message.id) 从队列消息 ID 派生,Engine.receive 对重复 ID 返回 duplicate,重复读取只产生一张工单。文档还提醒,新 kind 不会自动获得内置技能、原始服务记录资源或 PR 绑定。
默认值必须站在保守一侧
示例的 ConfigSchema 里,conversations 默认是空数组,文档明确写着默认值必须「什么都不接收」;注册表在管理员保存实例之前就会用默认值创建 enabled 实例。监听粒度只有 mentions 与 all 两档,会话 ID 只允许小写字母、数字和连字符。
轮询间隔 pollSeconds 默认 30 秒,下限 10 秒,上限 3600 秒,范围外的值在 schema 层即被拒掉。
另一条容易忽略:超出接收范围的消息不能静默丢弃,仍要交给 receive,由 Engine 记为 filtered 并带上 reason,例如 conversation_not_listed,面板才能解释「为什么这条没被处理」。
重试、幂等与可解释的失败
发送必须幂等。示例用 message.id 作为回复的 key,同一个 key 只回复一次;只有确认永久不可投递(HTTP 410)才返回 gone,其余失败一律抛错,交给 Outbox 重试。重试从 5 秒起步、按倍数退避,上限 300 秒;Policy 成员同步失败从 1 分钟起步、上限 1 小时。
游标只在所有 Trigger 都存储成功后才推进,中途断掉的一轮保持游标不变,靠稳定 ID 保证重放安全;时间戳游标回退 5 秒,容忍远端迟到的写入。健康检查也克制:连续三次轮询失败才报 error,因为 error 会让状态脚本以 2 退出并触发每小时告警。环境变量统一以 DSH_SUPERAGENT_ 加 kind 名作前缀,文档注明不得包含凭据。
面板只显示需要人的事
配套的 005 号文档把面板问题排成三问:现在有没有需要我的事、系统是否健康、一件工作从 Trigger 到 Eval 到 Ticket 的完整历史。六个标签页依次是 Overview、Source、Trigger、Eval、Execution、Settings。
七条设计原则里有两条最实用:一个数字只有会改变监督者行为时才出现,且计数必须等于它所链接列表的长度;健康状态不占额外空间,一次偶发网络错误不足以构成问题。Overview 只呈现需人工处理的工单、系统问题、最近 24 小时活动计数与 Executor 负载。这套约束的本质,是让异常有出处、有责任人。
以上数字全部来自官方设计文档与示例代码,是研究原型的设计约束,不是生产环境的压测结论。仓库 README 明确写着 Research prototype for reference only, not an official DeepSeek product,公开代码与内部实现不同,设计文章中的部分方向并未在原型里实现。把 30 秒轮询、5 秒重试搬进自己系统前,要按实际接口限流与数据量重新验算。
给中小企业的三条建议
• 先立幂等与稳定 ID。把 ERP、工单或审批流接给 Agent 时,用业务单号派生事件 ID,重复推送只生成一张工单,避免重复下笔或重复回写。这与做 ERP 接口时对流水号去重是同一套规矩。
• 新事件源默认不接收、只观察。跑一段时间,先看「本来会接」的记录是否靠谱,再逐条放开权限;凭据放凭据管理,不写进环境变量、配置文件或提示词。
• 面板只留需要人拍板的事,并保留过滤原因、重试次数与失败告警的可追溯记录。信息化项目上线后真正耗人的往往不是功能,是异常没人说得清、没人认领。
参考来源:
• DeepSeek 官方 dsh-superagent-prototype 仓库 docs/008-cookbook.md,2026-11-13 核验:https://github.com/deepseek-ai/dsh-superagent-prototype/blob/main/docs/008-cookbook.md
• DeepSeek 官方 dsh-superagent-prototype 仓库 docs/005-panel.md,2026-11-13 核验:https://github.com/deepseek-ai/dsh-superagent-prototype/blob/main/docs/005-panel.md
• DeepSeek 官方仓库 docs 目录索引(000 至 008 共 9 份文档),2026-11-13 核验:https://github.com/deepseek-ai/dsh-superagent-prototype/tree/main/docs
• CSDN《一天一个开源项目(第 253 篇):dsh-superagent》,2026-11-13 查阅:https://blog.csdn.net/chendongqi2007/article/details/170052984