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 仓库