文档

六个 Service，一套约定

每个 Service 可以单独启用；业务包只 inject 用到的那几个。六个 Service 都在 @mc/dsh-agent-kit 中，业务包只依赖这一个包；doctor、setup 与设置页在可选的 @mc/dsh-agent-kit-admin 中。下面的约定对所有 Service 都成立。

壹 · 连接 WebSocket 客户端 · ctx.agentWs 仅 wss:// 的 WebSocket 客户端：可刷新的鉴权请求头、心跳、指数退避重连、并发与背压控制；鉴权失败或指定关闭码时进入 failed 状态并可慢速重试。贰 · 推送钉钉推送 · ctx.dingtalk 通过钉钉 dws CLI 发送文本 / Markdown 消息，支持 user / bot / webhook 身份、群聊 / 单聊 / 多群、@ 人、幂等键和 dryRun。叁 · 推送飞书推送 · ctx.feishu 通过飞书官方 CLI lark-cli 发送文本 / Markdown 消息，支持 bot / user 身份、群聊 / 单聊 / 多群、@ 人、幂等键和 dryRun。肆 · 通知通知渠道 · ctx.notify 与渠道无关的通知：业务包只调用 ctx.notify.send()，同一时间发往一个渠道（钉钉或飞书）。渠道由配置决定，也可以在运行中用 ctx.notify.use() 切换，不需要改业务代码。伍 · 委托 Agent 任务 · ctx.agentTasks 调用 dsh 已注册的 subagent provider（如 claude-code、codex）执行一次性任务：默认只读权限、每个任务独立目录、类型化的 JSON Schema 输出、并发与排队上限。陆 · 校验 Jev 判断 · ctx.jev 调用 TypeSafe Jev 或本地部署的 Laya（二选一），返回 Choice / Noul / Score 的类型化判断和概率；一次 judge() 有严格的总时长。

配置引导可选的 @mc/dsh-agent-kit-admin：用 doctor 检查、用 setup 配置，或在 dsh Web 的设置页里操作。安全密钥、子进程、不可信数据、Agent 权限与 Web 写入限制。

通用约定

错误模型

所有错误都继承 KitError，带有 service、code、retryable，以及经过脱敏的 cause 与 details。业务包用 isKitError(e) 和 code 判断错误，不依赖 instanceof，这样即使出现多份模块实例也能正确判断。配置或环境变量非法时抛出 ConfigError（code: invalid_config），对应 Service 启动失败。

import { isKitError } from '@mc/dsh-agent-kit'

onError: (err, frame) => {
  if (isKitError(err) && err.retryable) {
    // 例如：记录下来，交给对端系统重投
  }
}

生命周期与卸载

连接、定时器、子进程、排队中的任务都随调用方插件的生命周期释放。
卸载时：WebSocket 以 1001 关闭；正在执行的 onMessage 收到的 signal 被中止；Agent 任务以 aborted 结束；dws、lark-cli 子进程先 SIGTERM、宽限后 SIGKILL 回收。

健康状态与可观测性

每个启用的 Service 提供 health()，返回 { status: 'ok' | 'degraded' | 'failed', detail, counters }。
状态变为 failed 时，除日志外还触发 Cordis 事件 agent-kit/service-failed（参数 { service, detail, error? }，已脱敏），可据此向外部监控上报。
所有调用都接受可选的 traceId 并写入日志，便于用事件 ID 串起一次处理链路。
日志通过 ctx.logger('agent-kit:<service>') 输出。cordis 默认只导出 error 与 info 级别，warn 与 debug 需要在 Profile 的日志 exporter 中调高级别。

本地开发与测试

@mc/dsh-agent-kit/testing 导出本地 WebSocket 测试服务端、假 subagent provider、Jev mock、假 dws 脚本（createFakeDws）和假 lark-cli 脚本（createFakeLark），业务包可以在没有 dws、lark-cli 与 Agent 登录态的环境下开发和测试；钉钉推送与飞书推送也可以设为 dryRun。