dsh-ai-ball：通過文件給智能體裝上懸浮球

前言¶

在 DeepSeek Harness (DSH) 的生態裏開發智能體，Agent 的輸出通常只表現爲日誌文本。要讓 Agent 有更直觀的反饋，比如一個能說話、做表情的視覺形象，需要引入一箇中間層。ai-ball 是一個運行在 Windows 上的懸浮球工具，它本身通過讀取特定文件來控制自己的行爲。dsh-ai-ball 插件就是連接 DSH Agent 和 ai-ball 的橋樑，它負責寫文件，讓球“說話”或改變狀態。

這是什麼¶

dsh-ai-ball 是一個輕量級的客戶端插件，由用戶 Hyfwdnmd666 維護。它的核心職責不在於操作窗口或啓動進程，而是作爲“寫手”，將 Agent 的指令寫入 ai-ball 正在監聽的日誌文件中。這種設計使得任何進程（包括非 DSH 的 Python 腳本）都可以充當球的“大腦”。

安裝與啓用¶

使用 DeepSeek Harness 的命令行工具進行安裝。該插件本身不包含 ai-ball 的本體，需要先單獨安裝並運行。

dsh plugin --profile web add link:/path/to/dsh-ai-ball

配置¶

插件在 cordis.patch.yml 中進行配置。爲了保證準確性，ballDir（球本體所在的目錄）是必填項，沒有默認值，必須手動指定，否則插件無法寫入文件。

- id: dsh-ai-ball
  name: dsh-ai-ball
  config:
    ballDir: C:\tools\ai-ball        # 必填：ai-ball 的 ball.py 所在目錄
    startCommand: C:\tools\ai-ball\start.bat   # 可選：ball_launch 使用的啓動命令
    cps: 50                          # 可選：打字速度
    heartbeatMs: 3000                # 可選：心跳間隔，必須小於球配置中的 stale_s
    files:                           # 可選：與球自己的 config.json 對齊
      monologue: monologue.log
      input: input.log
      status: status.json

核心功能¶

插件提供了六個工具函數，用於控制球的行爲：

ball_say(text, options): 說話。將內容寫入 monologue.log，球會逐字念出。支持 clear: true 參數來清屏後再說話。
ball_mood(mood): 改變表情。支持 idle、thinking、nervous、smug、broken 等狀態。
ball_panel(show): 顯示或收起獨白麪板。
ball_listen(): 讀取 input.log 中新增的輸入內容。
ball_status(): 報告接線情況，包括文件大小、最後內容、心跳狀態等。
ball_launch(): 按照配置的 startCommand 啓動 ai-ball 進程。

技術細節與注意事項¶

1. 心跳機制¶

插件會持續發送心跳（寫入 status.json），這是爲了防止球因超時而被渲染成灰色。如果不保持心跳，球的大腦狀態會失效。
* 第一次調用 ball_mood 時，插件會啓動一個後臺心跳。
* 插件卸載/重載時，心跳會自動停止。

2. 面板控制機制¶

ball_panel 使用序號機制來避免與球自身的邏輯衝突。status.json 中的 panel 是命令而非狀態，panel_seq 是序號。球只在序號變化時執行一次操作。這樣設計可以防止插件頻繁寫入導致面板頻繁閃爍或搶奪控制權。

3. 輸入監聽與編碼¶

ball_listen 使用字節游標讀取 input.log，並且只推進到換行符爲止。這樣做是爲了防止在讀取到 UTF-8 字符中間時發生解碼錯誤，導致內容永久丟失。

4. 不做的事¶

不判斷窗口狀態：插件只檢查文件狀態，不檢查球是否在運行。
不限制實例數量：重複調用 ball_launch 會產生多個球實例。
不渲染 Markdown：球是“嘴”，不是文檔，不會對 Markdown 格式進行渲染。

總結¶

dsh-ai-ball 是一個爲了解決 Agent 視覺反饋問題的薄插件。它通過文件 IO 的方式，將 DSH 的邏輯與 ai-ball 的渲染層解耦。正確配置 ballDir 並理解心跳與面板序號的機制，是使用好該插件的關鍵。

插件目錄頁
 GitHub 倉庫