Telegram 提醒 chintoleung/dsh-ping

dsh-ping

English · 简体中文

原生 DSH。Telegram 通知。仅此而已。

离开 DeepSeek Harness 时，不会错过任何问题、审批请求或已完成的回合。

dsh-ping 负责发送通知。DSH 保留问题卡片、回答和审批决策。

一个运行时源文件 · 零运行时依赖 · 无自定义问题卡片

快速开始 ·
[兼容性状态][compatibility] ·
面向编码代理 ·配置

DSH 支持概览

✅ 已通过 DSH 0.1.7-rc.2 验证

_next 检查于 2026 年 9 月 25 日 · 05:30 UTC · 插件 c10b480_

| 检查项 | 发布结果 |
| 跟踪的发布渠道 | next |
| 发布时解析的渠道 | 0.1.7-rc.2 · 检查于 2026 年 9 月 25 日 · 05:30 UTC |
| 测试的插件修订版本 | c10b480 |
| 单元测试 | 64 项通过 |
| 真实 DSH 兼容性金丝雀测试 | 8 项通过；无跳过 |
| 安装冒烟测试 | 通过 |
| 验证时间 | 2026 年 9 月 25 日 · 05:30 UTC |
| 测试环境 | Node.js v24.21.0 · darwin 27.0.0 arm64 |

[机器可读兼容性信息][compatibility] ·
验证日志

我们通过发布监控和维护者运行的验证来跟踪 DSH 的 next 渠道。DSH 保留其原生问题卡片、回答和审批处理；dsh-ping 仅发送通知。

“已通过……验证”表示我们在所述时间发布的测试结果。更新的上游版本在检查通过之前仍处于未验证状态。npm 单独的 latest 渠道必须独立检查。

这是维护者生成的兼容性证据，并非对 dsh.so 独立验证的声明。

有意保持小巧

- 原生问题。 代理使用 DSH 的 ask_user_question。没有替代工具、特殊提示约定或自定义澄清卡片。
- 原生交互。 在 DSH 的 Web GUI 中回答，包括 dsh-mobile。dsh-ping 不会拦截回答或做出审批决策。
- 简单设置。 安装插件，配置两个凭据，重启。无需操作额外服务或仪表盘。
- 发布监控兼容性。 当 next 上出现新版本时，维护者会运行真实 DSH 金丝雀测试。结果会标明所测试的确切版本。

没有 Telegram 回答流程。没有入站轮询或 webhook。没有管理控制台。没有运行时状态文件。没有额外通知渠道。

DSH 负责交互。dsh-ping 引起你的注意。

你将获得

| 事件 | Telegram 通知 | 默认 |
| 代理提出问题 | ❓ Question asked: | 开启 |
| 请求审批 | ⚠️ Approval requested: — | 开启 |
| 会话回合完成 | ✅ Done: (turn N) | 开启 |
| 代理遇到错误 | ❗ Agent error: | 可选启用 |
问题卡片仍保留在 DSH 的 Web GUI 中，你在那里回答它们。

已完成回合的通知使用按会话的尾随防抖：默认一秒。header.origin === 'subagent' 的会话被排除在完成通知之外；普通的分叉对话则不会。

通知报告的是观察到的请求，而非保证待处理的工作。
DSH 可能在发出请求后拒绝或取消审批，而问题通知会在下游回答者运行之前发起。

一次 ping 并不保证仍有东西在等待。沉默永远不会批准任何东西。

快速开始

你需要：

- DSH，且 pnpm 在 PATH 上。
- Node.js 22 或更新版本，并满足你的 DSH 版本的任何附加要求。
- 一个 Telegram 机器人令牌和聊天 ID。

使用 @BotFather 创建一个机器人。给你的机器人发一次消息，然后从以下地址获取你的 chat.id：

https://api.telegram.org/bot/getUpdates

将令牌视为机密。

1. 安装到你使用的配置文件中

对于 web 配置文件：

dsh plugin --profile web add github:chintoleung/dsh-ping

如果你使用其他配置文件，请替换 web。

这会添加依赖项，并在该配置文件的 dsh.profile.bundles 中激活其 bundle。

若要获得可复现的安装，请使用通过的[兼容性记录][compatibility]中固定的 installRef，
而不是默认分支引用。

2. 配置你的凭据

将这一行添加到你的配置文件的 cordis.patch.yml 中，例如 $DSH_HOME/profiles/web/cordis.patch.yml：

- id: dsh-ping
config:
telegram:
botToken: !!js "process.env.DSH_PING_TG_TOKEN || ''"
chatId: !!js "process.env.DSH_PING_TG_CHAT || ''"

设置这两个环境变量：

export DSH_PING_TG_TOKEN='your-bot-token'
export DSH_PING_TG_CHAT='your-chat-id'

它们必须对启动 DSH 的进程可用。如果你使用 launchd、systemd 或其他服务管理器，请在那里配置它们——而不是只在一个无关的终端中配置。

为什么用 !!js 而不是 ${ENV:…}？
DSH 的热重载路径会将 ${ENV:…} 原样传递，而不是展开它。!!js 绑定在 YAML 解析期间求值，包括热重载。

3. 重启 DSH

使用默认事件设置时，请查找：

[dsh-ping] armed: question/approval/turnEnd → telegram chat …

让 agent 向你提出一个澄清问题。你应该会收到一条 Telegram 通知，并看到 DSH 的原生问题卡片。

在 DSH 中回答，而不是在 Telegram 中。

没有凭据时，该插件保持惰性，不注册任何监听器。

隐私： 通知内容会发送到 Telegram。问题摘录、审批详情和会话标题可能包含敏感信息。
参见隐私。

兼容性

原生优先减少了必须跟随 DSH 变更的代码。
真实 DSH 金丝雀检查会检查剩余的集成点。

dsh-ping 不实现自己的问题卡片、澄清协议、应答服务或审批系统。它观察 DSH 的现有事件，并保持原生交互流程不变。

这是一个更小的维护面——并不意味着上游事件永远不会破坏它。

发布监视 → 验证金丝雀

我们的维护策略是在 next 渠道上为每个新的 DSH 发布运行兼容性金丝雀。

发布监视工作流是：

1. DSH 发布监视检测到新的上游版本。
2. 维护者选择那个确切的 DSH 版本以及一个特定的 dsh-ping 修订版本。
3. 运行单元测试套件和真实 DSH 兼容性金丝雀。
4. 结果和验证证据发布在 [compatibility.json][compatibility] 中。
5. 调查失败的检查。缺失的包、缺失的匹配 testkit 或设置失败将保持明确未验证状态。

验证是维护者侧的自动化。你不需要它来安装或运行 dsh-ping。 插件本身不会轮询 npm、检查更新或更新你的 DSH 安装。

新发布在检查通过之前都是未验证的。针对旧版本的成功检查并不代表新版本通过。

在哪里检查当前兼容性

阅读 [compatibility.json][compatibility]。

一条已完成的验证记录会标明：

- 确切的 DSH 和匹配的 testkit 版本。
- dsh-ping 版本和已测试的 Git 提交。
- 一个固定的安装引用。
- 所使用的 Node.js 版本和平台。
- 单元测试和金丝雀的结果。
- 验证时间以及支持日志或报告的链接。

状态含义：

| 状态 | 含义 |
| passed | 所记录的版本/修订版本对所需的测试已通过。 |
| pending | 已确定目标；验证尚未完成。 |
| failed | 某项必需测试失败；请检查证据。 |
| blocked | 验证无法完成，例如因为匹配的 testkit 不可用。 |
| unknown | 尚未发布可用的验证结果。 |

缺失证据即为未验证，而非隐含通过。

我们跟踪的渠道是 next。npm 单独的 latest 标签并不会仅仅因为 next 检查通过就被覆盖。这两个标签名称都不保证版本顺序。

面向编码代理

要回答“dsh-ping 是否与当前的 DSH next 兼容？”：

1. 立即解析该渠道：

npm view @deepseek-ai/dsh@next version

2. 从仓库中读取当前的 [compatibility.json][compatibility]——而不仅仅是旧版本附带的副本。

3. 要求：
- status 为 passed。
- unitTests 和 canary 均为 passed。
- dshVersion 与你刚刚解析出的版本匹配。
- 已测试的 pluginCommit 是你打算使用的修订版本。
- 你使用的记录是 records[] 中同时匹配 dshVersion 和 pluginCommit 的条目。
- 证据表明执行了金丝雀测试，而非跳过的测试。

4. 使用记录中固定的 installRef 来安装已测试的修订版本。
5. 如果版本不匹配、记录不完整，或无法检查该渠道，则报告 未针对当前渠道验证。运行金丝雀测试，而不是猜测。

如果用户指的是 npm 的 latest 渠道，请解析 @deepseek-ai/dsh@latest 并改为验证该确切版本。

旧结果仍然可以描述一个已验证的历史配对。但它本身并不能确定当前渠道指向什么。

不要根据安装成功、没有对等依赖限制，或一个通用的绿色 CI 徽章来推断兼容性。

金丝雀测试会检验什么

金丝雀测试会启动真实的 DSH 组件，包括：

- Cordis Context。
- AgentLoop。
- 用户问题瀑布流。
- 审批处理。
- 会话标题处理。

它使用离线模型适配器和打桩的 Telegram 投递。金丝雀测试本身不进行实时 LLM 调用，也不需要实时机器人凭据。

它会检验：

- 完成回合通知和会话标签。
- 子代理来源的完成过滤。
- 在不改变决策的情况下观察审批。
- 全局的、前置的问题观察。
- 保留下游问题结果和失败。
- 可选的错误通知。
- 插件卸载/重载行为。

边界：

- 这是一个集成金丝雀测试，不是浏览器渲染或实时 Telegram 投递测试。
- 问题检查使用测试应答器来检验真实的瀑布流，而不是完整的浏览器交互。
- 子代理夹具提供自己的 origin 元数据。该检查验证的是过滤，而不是上游委托是否总是产生该元数据。

自行验证版本

在你打算部署的 dsh-ping 修订版本的检出目录中运行这些命令。

要一次性解析当前的 next，然后测试该确切版本：

DSH_VERSION="$(npm view @deepseek-ai/dsh@next version)" &&
npm test &&
npm run test:dsh -- "$DSH_VERSION"

对于其他目标，将 DSH_VERSION 设置为其确切已发布版本。

对于 release-watch 事件，请使用该事件中的版本，而不是用 next 之后指向的任何版本替换它。

也可以使用便捷形式：

npm run test:dsh -- next

对于预先配置好的安装树：

node scripts/dsh-compat.mjs --root /path/to/preprovisioned-dsh

运行器会安装 DSH 及其匹配的 testkit，并禁用安装脚本，隔离 DSH_HOME 和工作目录，剥离继承的 Telegram 凭据，并保留失败的安装以供诊断。

没有匹配的 dsh-agent-loop-testkit 的 DSH 版本无法由该运行器进行金丝雀测试。这意味着 兼容性未评估，而不是自动不兼容。

只有在所需检查通过后，才使用已测试的插件修订版本部署已测试的 DSH 版本。更改任一项时都要重复这些检查。

配置

需要凭据才能启用该插件。其他设置是可选的；默认值如下所示。

- id: dsh-ping
config:
enabled: true

telegram:
botToken: !!js "process.env.DSH_PING_TG_TOKEN || ''"
chatId: !!js "process.env.DSH_PING_TG_CHAT || ''"

events:
question: true
approval: true
turnEnd: true
agentError: false

debounceMs: 1000
excerptChars: 80

| 设置 | 行为 |
| enabled | 设为 false 可禁用该插件。 |
| events.question | 当观察到原生问题请求时发送通知。 |
| events.approval | 当观察到审批请求时发送通知。 |
| events.turnEnd | 当符合条件的会话轮次完成时发送通知。 |
| events.agentError | 选择启用错误消息通知。 |
| debounceMs | 针对完成通知的每会话尾部防抖。0 表示立即；限制在 0–3600000。 |
| excerptChars | 负载摘录长度限制。默认 80；限制在 20–2048。 |

无效的数值设置会回退到其默认值。组装后的消息还会额外限制在 4,096 个字符以内。

运行时设计

该插件默认使用两个事件订阅，以及一个可选的错误订阅：

| 集成点 | 行为 |
| session/event | 观察审批、已完成的轮次和会话标题。 |
| user-questions/request | 观察问题，然后传递给原生下游处理器。 |
| agent/error | 在显式启用时观察错误。 |

问题监听器以 { prepend: true, global: true } 注册，并返回 next()。它不会解决该问题、替换回答者，也不会吞掉下游失败。

其他设计选择：

- 无服务注入： 没有 inject 声明或 DSH 服务 API 调用。
- 不读取历史： 会话标题通过 session/title 事件被动获知。
- 有界的内存簿记： 没有运行时状态文件。
- 防抖前去重： 重放的会话事件无法取消较新的待处理完成通知。
- 生命周期感知的投递： 销毁会取消待处理的定时器，并阻止新的发送和重试。

未声明任何 DSH 对等依赖。这避免了声明版本门槛；但这并不证明兼容性。

运行时审计入口是 src/index.mjs。

已测试行为

测试套件覆盖：

- 缺失或空的凭据会使插件保持惰性。
- DSH 事件处理器从不等待 Telegram 投递。
- 下游问题结果和错误对象会被保留。
- 通知失败会被隔离、记录并丢弃。
- 销毁会取消待处理的定时器，并阻止后续的发送/重试。
- 数值配置会被验证并限制范围，包括显式的 debounceMs: 0。
- Bot token 会从插件日志中脱敏；armed 行仅显示 chat ID 尾部。
- 子代理来源的完成过滤不会抑制普通 fork。

投递策略

投递为尽力而为：

- 网络故障和服务器错误会获得一次重试。
- HTTP 4xx 响应，包括 429 限流，会被丢弃且不重试。
- 不存在持久化队列或投递保证。
- 在服务中断或消息突发期间，消息可能会丢失。

一个已经在进行中的请求可能会在插件被销毁后完成。

隐私

通知会通过你的机器人向 Telegram 发送以下内容：

- 问题摘录。
- 审批详情：工具名称和原因。
- 会话标题。
- 错误消息（如果启用了错误通知）。

这些内容可能包含敏感信息，且不会被脱敏。
日志中的令牌脱敏并不等同于通知中的内容脱敏。

运行时插件会向 api.telegram.org 发送流量。它没有遥测、分析、版本监视器流量或其他网络调用。

兼容性报告是由维护者发布的仓库元数据，而非插件在你的机器上创建的状态文件。

有意为之的限制

- 单一目标： 一个机器人令牌和一个聊天 ID。
- 仅通知： 在 DSH 中回答问题并处理审批，而非在 Telegram 中。
- 仅观测，非待处理： 通知并不证明请求仍在等待。
- 尽力投递： 没有持久化队列或保证投递。
- 冷启动标题： 在插件加载之前就已命名的会话可能会显示为 #，直到观测到标题为止。
- 无自动升级： dsh-ping 不会更改你的 DSH 版本。
- 无笼统兼容性承诺： 证据仅适用于所记录的版本/修订对及已测试的集成范围。

开发与验证

在仓库检出目录中： sh
npm test
node --check src/index.mjs
npm run test:dsh -- next

除非设置了 DSH_COMPAT_ROOT，否则默认测试套件会跳过真实 DSH 金丝雀测试。仅 npm test 通过并不代表真实 DSH 兼容性结果。 请使用金丝雀运行器。

在发布插件更改之前，请再次针对目标 DSH 版本进行验证。上游发布监控不能替代对本插件更改的测试。

安装后的实时冒烟测试

1. 确认启动日志显示 armed:，而非 inert: 或禁用消息。
2. 让智能体向你提出一个澄清问题。
3. 确认 Telegram 通知和原生 DSH 问题卡片均出现。
4. 在 DSH 中回答，并确认交互正常继续。
5. 让一个回合完成，并检查完成通知。

这通过检查你实际的凭据、Telegram 连接性和用户界面，对自动化金丝雀测试形成补充。

卸载 / 迁移

对于 web 配置文件： sh
dsh plugin --profile web remove dsh-ping

这会移除该依赖及其 dsh.profile.bundles 条目。

移除配置文件配置行和这两个环境变量，然后重启 DSH。

许可证

MIT — 参见 LICENSE。

原生 DSH 交互。Telegram 通知。仅此而已。

离开屏幕，也不错过 DeepSeek Harness 智能体的提问、审批请求和回合完成。

dsh-ping 负责提醒你。问题卡片、回答和审批决定，继续交给 DSH。

单个运行时源文件 · 零运行时依赖 · 不自建问题卡片

[兼容性状态][compatibility] ·
快速开始 ·供编码智能体使用

DSH 支持速览 ✅ 已随 DSH 0.1.7-rc.2 验证

_next 检查于 2026-09-25 05:30 UTC · 插件 c10b480_

| 项目 | 已发布结果 |
| 跟踪的发布渠道 | next |
| 发布时渠道解析 | 0.1.7-rc.2 · 检查于 2026-09-25 05:30 UTC |
| 被测插件修订 | c10b480 |
| 单元测试 | 64 通过 |
| 真实 DSH 兼容性 canary | 8 通过；无跳过 |
| 安装冒烟测试 | 通过 |
| 验证时间 | 2026-09-25 05:30 UTC |
| 测试环境 | Node.js v24.21.0 · darwin 27.0.0 arm64 |

[机器可读兼容性数据][compatibility] ·
验证日志

我们通过发布监控与维护者执行的验证跟踪 DSH 的 next 渠道。
DSH 保留原生问题卡片、回答与审批处理；dsh-ping 只负责通知。

“已随 … 验证”指所述时间点发布的测试结果。更新的上游版本在检查通过前一律视为未验证。npm 单独的 latest 渠道需单独验证。

这是维护者产出的兼容性证据，不代表 dsh.so 的独立验证。

小而专一

- 原生提问： 使用 DSH 的 ask_user_question，不引入替代工具、特殊提示词约定或自定义澄清卡片。
- 原生交互： 在 DSH 的 Web GUI（含 dsh-mobile）里作答。
插件不拦截回答，也不代替你作审批决定。
- 简单配置： 安装插件、配置两个凭据、重启。
不需要额外运行服务或管理后台。
- 跟随发布验证： DSH 发布监控发现 next 上的新版本后，维护者运行真实 DSH 兼容性 canary，并记录确切的测试版本。

无 Telegram 应答流程、无入站轮询或 webhook、无管理台、无运行时状态文件、无额外通知渠道。

DSH 负责交互，dsh-ping 负责提醒。

功能一览

| 事件 | Telegram 通知 | 默认 |
| 智能体提问 | ❓ Question asked: | 开 |
| 请求审批 | ⚠️ Approval requested: — | 开 |
| 会话回合完成 | ✅ Done: (turn N) | 开 |
| 智能体出错 | ❗ Agent error: | 需显式开启 |

问题卡片仍在 DSH 的 Web GUI 中显示，并在那里作答。

回合完成通知采用每会话尾随去抖，默认一秒。
header.origin === 'subagent' 的会话不发送完成通知；普通 fork 会话不受此限制。

通知表示观测到了请求，不保证请求仍在等待处理。
审批可能随后被拒绝或取消；提问通知也在下游应答器运行之前发起。

收到通知不代表仍有待办；沉默永远不会批准任何操作。

快速开始

需要：

- DSH，且 pnpm 在 PATH 上。
- Node.js 22 或更新版本；同时满足所用 DSH 版本的额外要求。
- Telegram bot token 和 chat ID。

通过 @BotFather 创建 bot。
先给 bot 发一条消息，再从以下接口读取 chat.id： text https://api.telegram.org/bot/getUpdates

请妥善保管 token。

1. 安装到正在使用的 profile

以 web 为例： sh
dsh plugin --profile web add github:chintoleung/dsh-ping

如果使用其他 profile，请替换 web。

该命令会添加依赖，并在 profile 的 dsh.profile.bundles 中激活 bundle。

需要可复现安装时，请使用通过验证的
[兼容性记录][compatibility] 中的 installRef，
而不是默认分支引用。

2. 配置凭据

在 profile 的 cordis.patch.yml 中加入以下配置。
例如 $DSH_HOME/profiles/web/cordis.patch.yml： yaml
- id: dsh-ping
config:
telegram:
botToken: !!js "process.env.DSH_PING_TG_TOKEN || ''"
chatId: !!js "process.env.DSH_PING_TG_CHAT || ''"

设置环境变量： sh
export DSH_PING_TG_TOKEN='your-bot-token'
export DSH_PING_TG_CHAT='your-chat-id'

这两个变量必须对启动 DSH 的进程可见。
使用 launchd、systemd 等服务管理器时，应在那里配置，而不是只在另一个终端中导出。

为什么使用 !!js，而不是 ${ENV:…}？
DSH 的热加载路径曾将 ${ENV:…} 作为字面量透传。
!!js 在 YAML 解析时求值，也适用于热加载路径。

3. 重启 DSH

默认事件配置下，应看到： text [dsh-ping] armed: question/approval/turnEnd → telegram chat …

让智能体向你提出一个澄清问题。
确认收到 Telegram 通知，同时 DSH 中出现原生问题卡片。

在 DSH 中回答，不是在 Telegram 中。

凭据为空时，插件保持惰性，不注册任何监听器。

隐私提示： 提问摘要、审批详情和会话标题会发送到 Telegram，其中可能包含敏感信息。请先阅读下方隐私说明。

兼容性与发布跟踪

尽量使用原生交互，减少需要跟随 DSH 变化的代码；用真实 DSH canary 验证剩余的集成点。

dsh-ping 不实现自己的问题卡片、澄清协议、应答服务或审批系统。
它观察 DSH 已有的事件，让原生交互流程保持不变。
这意味着更小的维护面，不代表上游事件永远不会发生破坏性变化。

发布监控 → 验证 canary

维护策略是：针对 next 渠道的每个新 DSH 发布运行兼容性 canary。

流程如下：

1. DSH 发布监控发现新版本。
2. 维护者选定该确切 DSH 版本和一个确定的 dsh-ping Git 修订。
3. 运行单元测试和真实 DSH 兼容性 canary。
4. 将结果及验证证据发布到 [compatibility.json][compatibility]。
5. 测试失败时排查；缺少软件包、匹配的 testkit 或运行环境异常时，明确记录为尚未完成验证。

验证是维护者侧的自动化。
安装和运行 dsh-ping 不需要这套验证。
插件本身不会轮询 npm、检查更新或升级你的 DSH。

新版本只有在验证通过后才算已验证。
旧版本的通过结果不能自动算作新版本通过。

查看兼容性状态

查看 [compatibility.json][compatibility]。

完整验证记录包含：

- DSH 和匹配 testkit 的确切版本。
- dsh-ping 版本、被测试的 Git commit 和固定安装引用。
- Node.js 版本与运行平台。
- 单元测试和 canary 结果。
- 验证时间，以及日志或报告链接。

状态含义：

| 状态 | 含义 |
| passed | 记录中的版本与修订组合通过了要求的测试。 |
| pending | 已发现目标版本，验证尚未完成。 |
| failed | 必需的测试失败，需要查看证据。 |
| blocked | 无法完成验证，例如缺少匹配的 testkit。 |
| unknown | 尚无可用验证结果。 |

缺少证据意味着未验证，不是默认通过。

本项目跟踪 next。
npm 的 latest 是另一个 dist-tag；next 验证通过不意味着
latest 也已验证。标签名称也不保证版本先后顺序。

供编码智能体使用

判断“是否兼容当前 DSH next”时：

1. 查询当前渠道对应的确切版本：

sh
npm view @deepseek-ai/dsh@next version

2. 读取仓库当前的 [compatibility.json][compatibility]，不要只使用旧版本中附带的副本。

3. 确认：
- status 为 passed。
- unitTests 与 canary 都为 passed。
- dshVersion 等于刚查询到的版本。
- pluginCommit 是准备安装或使用的修订。
- 使用 records[] 中同时匹配 dshVersion 与 pluginCommit 的那一条记录。
- 证据表明确实执行了 canary，而不是跳过。

4. 使用记录中的固定 installRef 安装已测试修订。

5. 如果版本不匹配、记录不完整或无法查询当前渠道，应回答 “尚未验证与当前渠道兼容”，并运行 canary，不要推测。

如果用户所说的“latest”指 npm 的 latest 标签，请单独查询 @deepseek-ai/dsh@latest 并验证该确切版本。

历史通过结果仍可证明相应历史组合经过验证，但不能单独证明当前渠道指向什么版本。

安装成功、没有 peer 版本限制或通用 CI 绿灯，都不是兼容性证明。

Canary 验证什么

Canary 启动真实 DSH 组件，包括 Cordis Context、AgentLoop、 user-questions waterfall、审批处理和会话标题处理。

它使用离线模型适配器，并对 Telegram 投递打桩。
Canary 本身不调用真实 LLM，也不需要真实 bot 凭据。

覆盖内容包括：

- 回合完成通知和会话标题。
- 子智能体来源会话的完成通知过滤。
- 不改变审批决定的请求观察。
- 全局、前置的提问观察器。
- 下游提问结果和错误的原样传播。
- 错误通知开关。
- 插件卸载与重新加载。

边界：

- 这是集成 canary，不是浏览器渲染测试或真实 Telegram 投递测试。
- 提问测试使用真实 waterfall 和测试应答器，不覆盖完整浏览器交互。
- 子智能体 fixture 自行提供 origin 元数据，因此验证的是过滤逻辑，不是上游委派机制是否始终产生该字段。

自行验证版本

在准备部署的 dsh-ping 修订对应的仓库 checkout 中运行。

先解析一次当前 next，再验证该确切版本： sh
DSH_VERSION="$(npm view @deepseek-ai/dsh@next version)" &&
npm test &&
npm run test:dsh -- "$DSH_VERSION"

验证其他版本时，将 DSH_VERSION 设置为目标的确切发布版本。

处理发布监控事件时，应使用事件中的版本，不要用稍后可能已经变化的 next 替代它。

也可以直接运行： sh
npm run test:dsh -- next

使用预置安装目录： sh
node scripts/dsh-compat.mjs --root /path/to/preprovisioned-dsh

Runner 安装 DSH 和匹配 testkit 时禁用安装脚本，隔离 DSH_HOME 与工作目录，移除继承的 Telegram 凭据，并在失败时保留安装目录供排查。

缺少匹配的 dsh-agent-loop-testkit 时，runner 无法执行 canary。
这表示未能评估兼容性，不自动等于不兼容。

只有要求的检查都通过后，才部署被测试的 DSH 版本与插件修订。
任一方变化后，都应重新验证。

配置

凭据用于激活插件；其他设置可选。默认值如下： yaml
- id: dsh-ping
config:
enabled: true

telegram:
botToken: !!js "process.env.DSH_PING_TG_TOKEN || ''"
chatId: !!js "process.env.DSH_PING_TG_CHAT || ''"

events:
question: true
approval: true
turnEnd: true
agentError: false
debounceMs: 1000
excerptChars: 80

- enabled: false：禁用插件。
- events：分别控制提问、审批、完成和错误通知。
- debounceMs：完成通知的每会话尾随去抖，范围 0–3600000； 0 表示立即发送。
- excerptChars：内容摘要上限，默认 80，范围 20–2048。
- 非法数值回退为默认值。
- 完整消息另外限制为最多 4,096 个字符。

运行时设计

默认使用两个事件订阅，另有一个可选错误订阅：

| 集成点 | 行为 |
| session/event | 观察审批、回合完成和会话标题。 |
| user-questions/request | 观察提问，再交给原生下游处理器。 |
| agent/error | 显式开启后观察错误。 |

提问监听器以 { prepend: true, global: true } 注册，
并返回 next()。
它不自行完成提问、不替换应答器，也不吞掉下游错误。

其他设计选择：

- 无 inject 声明，不调用 DSH 服务 API。
- 不读取会话历史，通过 session/title 事件被动学习标题。
- 只使用有界的内存记录，不写运行时状态文件。
- 会话事件先去重，再处理去抖，避免旧事件重放吞掉新的待发通知。
- 销毁时取消待执行计时器，阻止新的发送与重试。

不声明 DSH peer 依赖意味着没有声明式版本门禁，不意味着所有版本都兼容。

运行时代码可在一个文件中审阅： src/index.mjs。

已测试的行为

测试覆盖：

- 凭据缺失或为空时保持惰性。
- DSH 事件处理器不等待 Telegram 投递。
- 下游提问结果和错误对象原样保留。
- 通知失败被隔离、记录并丢弃。
- 销毁后取消待执行计时器并阻止后续发送与重试。
- 数值配置经过校验和边界限制，尊重显式 debounceMs: 0。
- 插件日志对 bot token 脱敏，armed 日志仅显示 chat ID 尾部。
- 子智能体来源过滤不会抑制普通 fork 的完成通知。

投递策略

尽力投递：

- 网络错误和服务器错误重试一次。
- HTTP 4xx（包括 429 限流）不重试，直接丢弃。
- 无持久化队列，不保证送达。
- 故障或突发期间可能丢消息。

插件销毁时，已经发出的网络请求仍可能完成。

隐私

通知通过你的 bot 将以下内容发送到 Telegram：

- 提问摘要。
- 审批工具名和原因。
- 会话标题。
- 显式开启后的错误消息。

这些内容可能含有敏感信息，且不会脱敏。
日志中的 token 脱敏不等于通知正文脱敏。

运行时插件只向 api.telegram.org 发送网络请求，无遥测、分析、发布监控流量或其他网络调用。

兼容性报告是维护者发布到仓库的元数据，不是插件在用户机器上创建的状态文件。

刻意保留的限制

- 单一目标： 一个 bot token、一个 chat ID。
- 仅通知： 在 DSH 中回答问题和处理审批，不在 Telegram 中操作。
- 观测而非待处理： 通知不证明请求仍在等待。
- 尽力投递： 无持久化队列或送达保证。
- 冷启动标题： 插件加载前已命名的会话，在观察到标题前可能显示为 #。
- 不自动升级： 插件不会修改你的 DSH 版本。
- 不作无限兼容承诺： 证据只适用于记录中的版本、修订和测试范围。

开发与验证

在仓库 checkout 中运行：

npm test
node --check src/index.mjs
npm run test:dsh -- next

未设置 DSH_COMPAT_ROOT 时，默认测试会跳过真实 DSH canary。
仅 npm test 通过，不代表真实 DSH 兼容性验证通过。
请使用 canary runner。

发布插件修改前，应重新针对目标 DSH 版本验证。
监控上游发布不能替代对插件自身修改的测试。

安装后的线上检查

1. 确认启动日志出现 armed:，而非 inert: 或禁用提示。
2. 让智能体向你提出澄清问题。
3. 确认收到 Telegram 通知，且 DSH 中出现原生问题卡片。
4. 在 DSH 中回答，确认交互正常继续。
5. 让一个回合完成，确认收到完成通知。

这补充了自动 canary 未覆盖的真实凭据、Telegram 连通性和界面检查。

卸载 / 迁移

以 web profile 为例：

dsh plugin --profile web remove dsh-ping

该命令移除依赖及对应的 dsh.profile.bundles 条目。

随后删除 profile 配置行和两个环境变量，并重启 DSH。

许可证

MIT — 见 LICENSE。

[compatibility]: https://raw.githubusercontent.com/chintoleung/dsh-ping/master/compatibility.json