前言¶
在 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 後端的交互更加直觀。開發者可以通過安裝命令快速集成，並通過調試工具確認狀態流轉。
