前言¶
DSH 的插件体系把能力拆到多个插件里，但插件声明不完整、任务原地循环、子代理嵌套过深、宿主重启打断会话等问题，都会影响正在执行的任务。
akira399/dsh-guardian 针对这些情况提供检测和引导：它不直接终止任务，而是通过注入 user/message 引导 Agent 调整方向，同时提供预检、状态查询和事件日志入口。
这是什么¶
dsh-guardian 是 DeepSeek Harness（DSH）任务防护插件，由 akira399 维护，许可证为 MIT，版权标注为 MIT © 2026 dsh-guardian contributors。
它的定位是：通过插件预检、循环检测、递归防护与中断感知做检测和引导，永不终止任务。package.json 声明运行环境为 node >=20。
核心功能¶
插件预检¶
插件预检用于检查插件源码中的服务声明是否与用法一致。它会静态分析 ctx.<服务> 用法与 inject 声明是否一致，可识别缺失 timer、tools、settings 等服务，并给出修复提示。
预检命令如下：
node <dsh-guardian>/scripts/preflight.mjs <插件目录或 index.js>
也可以在代码中调用：
import { scanSource } from "dsh-guardian/preflight";
循环检测¶
循环检测关注同一工具调用是否反复发生。
当同一工具调用，按“名称 + 参数指纹”判断，在滑动窗口内重复达到 maxLoopRepeats 时，插件会判定为循环，然后注入换方向提示，并记录 LOOP_DETECTED。
递归防护¶
递归防护关注子代理和工作流嵌套深度。
当子代理或工作流嵌套深度超过 maxSubagentDepth 时，插件会注入收敛提示，并记录 RECURSION_DETECTED。
中断感知¶
中断感知通过状态路由提供当前会话的运行信息。
状态路由会返回：
runningbusy- 嵌套深度
- 近期调用数
safeToRestart
其中 safeToRestart 用于判断当前是否适合重启。资料中的安全重启助手会先查这个字段：如果存在运行中会话，则拒绝重启，除非使用 -Force。
事件日志与状态查询¶
事件会写入 guardian/events.jsonl。资料中给出的本地查看路径为：
~/.dsh/guardian/events.jsonl
状态路由可以查询最近 50 条事件。
不终止任务¶
dsh-guardian 的核心行为是引导，而不是终止。
它通过注入 user/message 引导 Agent 调整方向，不会主动结束任务。
安装与启用¶
由于插件以当前 dsh 进程权限运行，安装前建议先检查源码与许可证。
确认环境满足 node >=20 后，执行安装命令：
npx -p @deepseek-ai/dsh dsh plugin --profile web add github:akira399/dsh-guardian
插件默认启用。修改 guardian 配置后热生效，无需重启。
典型用法¶
运行插件预检¶
对某个插件目录或入口文件做预检：
node <dsh-guardian>/scripts/preflight.mjs <插件目录或 index.js>
在代码中调用预检¶
如果需要在自己的工具链里做静态检查，可以导入预检模块：
import { scanSource } from "dsh-guardian/preflight";
查看状态¶
状态路由如下：
GET /api/dsh-guardian/status
资料中也给出了具体地址示例：
GET http://127.0.0.1:3080/api/dsh-guardian/status
返回内容包括 running、busy、嵌套深度、近期调用数和 safeToRestart，并可查询最近 50 条事件。
安全重启助手¶
安全重启脚本会先检查 safeToRestart。如果仍有会话运行，它会拒绝重启，除非使用 -Force。
命令示例：
powershell -NoProfile -ExecutionPolicy Bypass -File <dsh-guardian>\scripts\safe-restart.ps1
资料中仅说明强制重启可加 -Force，未给出完整命令。
配置示例¶
settings.yaml 中的 guardian 配置示例如下：
guardian:
maxLoopRepeats: 4
maxSubagentDepth: 3
修改 guardian 配置后热生效，无需重启。
查看事件日志¶
事件日志路径示例：
~/.dsh/guardian/events.jsonl
资料中事件日志路径同时出现 $DSH_HOME/guardian/events.jsonl 与 ~/.dsh/guardian/events.jsonl，两者关系未明确。
运行验证¶
资料中给出的验证命令：
pnpm verify
适用场景与注意¶
适合需要管理 DSH 插件、检查插件声明、观察长任务状态，并希望在重启前确认会话是否安全的人。
使用注意：
- 插件以当前
dsh进程权限运行，安装前应检查源码与许可证。 dsh-guardian只做检测和引导，不终止任务。- 资料未确认插件分类与星标数。
- 目录页链接来自线索，未抓取目录页正文。
safe-restart.ps1的强制重启资料仅说明可加-Force，未给出完整命令。
结尾¶
dsh-guardian 的价值在于把 DSH 任务运行中常见的风险点做成可检查、可观察、可引导的防护路径：插件预检、循环检测、递归防护、中断感知，以及安全重启检查。它不提供任务终止动作，而是通过提示和事件记录帮助 Agent 和开发者保持任务可控。
GitHub：
https://github.com/akira399/dsh-guardian
目录页（线索，未抓取正文）：
https://www.skillhub.cn/plugins/akira399/dsh-guardian
