前言¶
在 DSH 的 Web 工作流开发中，代理的运行状态通常隐藏在后端，前端缺乏直观的反馈。用户在等待回复时，往往不知道代理是否正在处理。dsh-pelican 插件通过在右下角展示 SVG 动画以及全局任务状态提示，解决了这一状态可见性的问题。
插件定位¶
dsh-pelican 是一个 DSH Web 静态双端插件。由 Little-Star888 维护。它通过右下角的 SVG 骑行动画和全局任务状态提示，将后端的代理运行状态映射到前端交互中。
核心功能¶
该插件包含以下核心能力：
- 右下角 SVG 骑行动画：在 Web 客户端的右下角展示 SVG 动画。
- 全局任务状态提示：维护一个
idle/thinking/done的状态机，并在前端进行对应展示。 - API 接口：提供
GET /api/pelican/status接口，允许浏览器主动轮询当前状态。 - 调试工具：提供
pelican_debug工具，用于查看状态、序列号和事件计数。 - 交互反馈：
- 任务思考时，鹈鹕会说话提示「我在呢，稍等～」。
- 任务完成时，会弹出「任务完成啦 🎉」气泡，播放提示音，并支持发送系统通知。
安装与启用¶
该插件常驻磁盘，不是会话内动态插件，安装后需要重启 dsh 进程才能生效。支持以下三种安装方式：
1. 本地路径安装（无需发布）
dsh plugin --profile web add ./dsh-pelican
2. npm 安装（需先发布）
dsh plugin --profile web add dsh-pelican
3. GitHub 安装（需先推送仓库）
dsh plugin --profile web add github:Little-Star888/dsh-pelican
安装完成后，重启 dsh 进程即可。
状态机制¶
插件通过监听全局代理事件来维护状态机：
| 事件 | 状态 |
|---|---|
用户发消息 (agent/inbox/inserted) |
thinking |
回复收尾 (agent/turn-stopping / agent/status: idle) |
done |
| 无活动 | idle |
调试¶
使用 pelican_debug 工具可以查看当前的状态、序列号、待处理的 Agent ID 以及事件计数。这对于排查状态同步问题很有帮助。
适用场景与注意事项¶
- 适用场景：需要在前端界面展示代理运行状态的 Web 工作流。
- 注意事项：
- 该插件以当前 dsh 进程的权限运行，请确保安装源代码安全。
- 插件遵循 MIT 许可证。
- 本地安装无需发布，但通过 npm 或 GitHub 安装前需确保仓库已发布或推送。
总结¶
dsh-pelican 通过轻量级的动画和状态通知，让 Web 界面与 DSH 后端的交互更加直观。开发者可以通过安装命令快速集成，并通过调试工具确认状态流转。
