前言¶
在 DeepSeek Harness（DSH）里跑 Agent，工具调用往往堆在对话流的折叠区里：你知道「读了什么文件」「跑了什么命令」，但很难在同一屏里看到「模型为什么在这一步做这件事」以及「这一步想达到什么作用」。若希望把判断写成可读的工作日志、强制每次普通工具调用带上文字说明，并在界面里实时看到 act 卡片，就需要在 Host 协议与 Client UI 两侧一起做文章。
下面介绍社区维护者 FunnyBishop 发布的 dsh-better-tooluse（当前仓库版本 0.4.0，MIT 许可证）。它不替代 DSH 内核的工具分组，而是在 profile 模式下叠加决策流可见性、describe 护栏和右侧「梳理」面板。
这是什么¶
dsh-better-tooluse 是 DSH 的 bundle 插件：把 Agent 的每次思考与工具调用做成「可见、可纠偏」的决策流。
维护者与源码归属：FunnyBishop，仓库 https://github.com/FunnyBishop/dsh-better-tooluse。目录页：https://www.skillhub.cn/plugins/FunnyBishop/dsh-better-tooluse（社区目录站点，与 DeepSeek / 幻方无官方从属关系）。
环境要求（资料原文）：
- DeepSeek Harness
>=0.2.2-rc.1 <0.3.0（profile 模式）。 - 可选：
dsh-better-sidebar（右侧「梳理」页；未安装时降级为仅输入框梳理条）、@changfenhuang/dsh-genui（阶段梳理卡）、dsh-ops（插件已适配ops_*工具名替换）。
核心功能¶
资料中归纳的三件事，展开如下。
决策流播报（纯文本）¶
模型在可见正文里按协议输出四类行（UI 不能替代正文播报）：
◎ 目标▸ 决策：<思考结果> → <本步作用>↳ 发现⟲ 调整
常驻协议文本在 lib/protocol.js，配置项 protocolTone 可选 normal（含阶段梳理卡与事件化说明）或 quiet（仅核心规则）。
强制 act 外包装与护栏¶
普通工具必须通过 act({ describe, tool, input }) 调用；直连会被 Host 护栏拒绝，describe 缺省即失败。配置 enforceDescribe 默认 hard（soft 只记录，off 关闭）；exemptTools 可叠加内置豁免表，允许额外直连的工具名。
act 卡片与「梳理」界面¶
Client 半（client.js）提供：输入框梳理条、右侧「梳理」页、act 工具卡。卡片展示工具名、思考结果、作用、状态、耗时、结果摘要；支持展开全文、状态与工具筛选、运行中置顶。被 act 包装后，各工具不再显示原生富卡片（diff/搜索/终端等），统一为 describe 优先的 act 卡。
后台 event 工具¶
长任务可交给后台运行，完成后结果回到上下文并触发新一轮；支持 list / kill。相关配置包括 eventEnabled、backfillEvents、autoEventizeMs、eventProgressMs 等。
配置化与测试¶
护栏强度、豁免表、协议档位、面板显隐均可配；仓库附带 node:test 单元测试（README 标明当前 9 个用例通过）。
安装与启用¶
安装前请自行审阅仓库源码与 MIT 许可证；插件在当前 DSH 进程权限下运行，与所用 profile 一致。
方式一：通过 plugin_manager（推荐）¶
在 DSH 会话里让 Agent 执行（将 <path-to-this-checkout> 换成仓库在本机的绝对路径）：
plugin_manager action=install_bundle target=link:<path-to-this-checkout>
安装会写入 profile 的 dependencies 与 dsh.profile.bundles，随后自动激活。
方式二：CLI¶
dsh plugin --profile <profile> install <path-to-this-checkout>
手动安装¶
- 在 profile 的
package.json中加入"dsh-better-tooluse": "link:<path-to-this-checkout>"； - 把
dsh-better-tooluse追加到dsh.profile.bundles； - 重启 DSH，或在插件列表里把
include:dsh-better-tooluse关→开。
Host 侧（index.js）修改后需 set_plugin 关→开或重启；client.js 修改会随客户端图变更热加载。
典型用法¶
播报与 act 调用¶
模型在调用工具前先播报（纯文本）：
▸ 决策：需要确认依赖版本 → 读取 package.json
工具调用通过 act 包装：
act({ describe: "需要确认依赖版本 → 读取 package.json", tool: "read", input: { path: "package.json" } })
打开右侧「梳理」页¶
点输入框下方梳理条右侧的「梳理」按钮，或在右侧栏的 + 菜单里选「梳理」。
常用配置键¶
在插件行直接写配置键（无需 schema；未知键忽略，非法值回退默认）。节选：
| 键 | 默认 | 说明 |
|---|---|---|
enforceDescribe |
hard |
护栏强度 |
exemptTools |
[] |
额外允许直连的工具名 |
protocolTone |
normal |
normal / quiet |
showDockStrip |
true |
是否显示输入框梳理条 |
showActCards |
true |
梳理页是否显示 act 卡片区 |
actCardLimit |
10 |
梳理页 act 卡片上限（1–30） |
浏览器半可通过 GET /plugins/dsh-better-tooluse/config 读取 showDockStrip / showActCards / actCardLimit。
架构简述¶
Host 半（index.js）负责系统提示协议、act / event 工具、护栏、SSE 路由与事件派生；Client 半经 Host 私有前缀 /plugins/dsh-better-tooluse/* 收 SSE，不依赖 typert 生成物，也不 import @deepseek-ai/* 包。事件派生从 assistant/message 拆播报行与 describe，从 tool/call / tool/result 生成工具事件。
开发时无需构建；自检可执行：
npm test
适用场景与注意¶
适合谁：需要在 DSH 里长期调试 Agent 工具链、希望「每一步为什么做、做了什么」留在对话正文且侧栏可扫读的开发者；愿意接受「普通工具必须走 act」约束的团队。
已知限制（资料原文）：
- DSH 仍把原生工具行归入可折叠「已调用工具」区；act 卡片由插件自行渲染。
- 后台事件表仅存在于内存，插件重载或 DSH 重启后不保留历史。
- 面板暂不提供跳转到对话内对应工具卡（依赖 Chat owner 的
inspectCall，公开槽位未暴露）。 - README 写明仅在 Windows + desktop profile 实测；其他平台未验证。
安装与启用后，若与 dsh-ops 等插件共存，工具名被替换为 ops_* 时插件仍按资料说明兼容，无需改调用方式里的 tool 字段假设。
结尾¶
dsh-better-tooluse 把决策流写成正文、用 describe 护栏约束工具调用，并在梳理条与侧栏用 act 卡片做实时复盘；适合在 profile 模式下做 Agent 可观测性增强。进一步了解可访问目录页 skillhub.cn/plugins/FunnyBishop/dsh-better-tooluse 与 GitHub 仓库 github.com/FunnyBishop/dsh-better-tooluse。
