dsh-reactor
Event-Driven Autonomous Agent Runtime for DeepSeek Harness
Turn your DeepSeek Agent from an on-demand assistant into a proactive daemon that senses the world, acts on real conditions, and finishes the job autonomously.
Community plugin — not an official DeepSeek product.
English | 中文
Why not cron?
| Dimension | Traditional cron plugin | dsh-reactor |
|---|
| Trigger | Fixed schedule | Any event source + condition evaluation |
| Decision | Runs on time | Evaluates conditions first |
| Execution | Preset shell script | Spawns isolated Agent, LLM ReAct does the work |
| Verification | None | Deterministic checks (file exists / command exit code) |
| Recovery | None | Failure classification + smart retry |
| State | Stateless | Last summary injected — continues where it left off |
| Audit | Logs only | Full Run Trace decision chain |
Install
dsh plugin --profile web add dsh-reactor
Restart dsh web after install. A clock-themed widget appears in the bottom-right corner.
Uninstall
dsh plugin --profile web remove dsh-reactor
Quick Start
After install, just describe your goal in the DSH chat:
"Watch https://api.github.com/repos/snhna-a/dsh-reactor for new commits. When HEAD changes, git pull in C:\work\dsh-reactor and run npm run build, then tell me the result."
The Agent calls reactor_define to create the rule. It runs in the background without further input.
More examples:
- "Watch deploy.json; when version changes, send a webhook alert."
- "Every 5 minutes run
git log --oneline -1; when output changes, analyze the commit in a new session."
- "Poll a status API; when status becomes error, let the Agent diagnose and fix it."
Core Concept: ECG (Event-Condition-Goal)
dsh-reactor upgrades traditional ECA to ECG:
Event
↓ poll / watch / webhook
Condition
↓ JSONPath + operators + AND/OR + changed
Goal
↓ spawn isolated Agent Session, LLM ReAct autonomously
Key difference: Action mode runs a fixed script. Goal mode injects your goal + event context into an isolated Agent Session — the LLM decides how to do it: pull code, run tests, read errors, fix, re-verify, all autonomously.
Event Sources
| Type | Description |
|---|
http-poll | Poll HTTP endpoints, parse JSON/text |
file-watch | Read local files (BOM handled) |
command | Execute shell command, parse stdout |
webhook | External system POSTs events directly |
Conditions
JSONPath ($.status, $.data.count) + operators (eq/ne/gt/contains/exists/changed) + AND/OR.
Two Execution Modes
Action mode (classic ECA)
shell: run command (with {{payload.field}} templating)webhook: POST JSON to a URLagent-talk: run prompt in an isolated session
Goal mode (ECG, recommended)
- Spawn isolated Agent Session
- Inject your goal + last run summary (continuation)
- LLM ReAct works autonomously: read files, run commands, call tools, verify
- Automatic deterministic verification after settle (file exists / exit code)
- Failure auto-classification + smart retry
Safety & Guards
| Mechanism | Description |
|---|
| Budget Gate | maxRunsPerDay / maxTokens hard limits; over → blocked, 0 tokens |
| Approval Gate | riskLevel: high + requireApproval → wait for human approval |
| Preflight | Check workspace/filesystem/network before spawning Agent; missing → blocked, 0 tokens |
| Cooldown | No duplicate triggers within window |
| Overlap Protection | Same rule never runs concurrently |
| Failure Classification | Auto-tag transient/repairable/dangerous |
| Smart Retry | Transient errors (network blip/timeout) auto-retry once |
Widget UI
Clock-themed floating widget in the bottom-right of DSH Web:
- Drag & snap: drag to any edge/corner; left-snap mirrors automatically
- Size: 0.6–2.5x, semi-transparent settings panel
- Trigger alerts: bubble on trigger/failure/retry
- Management panel: stats overview, rule list (toggle/delete), rule detail
- Run Trace: full decision chain timeline (trigger→decision→approval→budget→retry→agent→verify→result)
- Failure tags: one-glance failure type (transient/repairable/dangerous)
- Token usage: input/output/cache tokens per run
Model Tools
The Agent manages rules via these tools (natural language, no manual UI needed):
| Tool | Purpose |
|---|
reactor_define | Create a rule (action/goal mode) |
reactor_list | List all rules and their status |
reactor_status | Rule detail (last payload, run state) |
reactor_test | Test rule with a simulated payload |
reactor_remove | Delete a rule |
reactor_history | Execution history (Run Trace, tokens, failure class) |
Persistence & Audit
- Rules auto-persist to
~/.dsh/reactor/rules.json, restored on restart
- Every trigger recorded to
~/.dsh/reactor/history.jsonl (ring buffer, 500 entries)
- History includes: timestamp, match result, payload, session ID, token usage, Run Trace steps, failure class
- Last summary auto-injected into goal prompt on next trigger (continuation)
Relationship to Other DSH Plugins
- dsh-cron / dsh-automation: scheduled tasks. dsh-reactor is event-driven + Agent ReAct.
- dsh-cron-panel: cron UI panel. dsh-reactor widget is for event rules.
- dsh-taskboard: human-agent kanban. dsh-reactor runs autonomously in the background.
- dsh-agent-teams: multi-agent orchestration. dsh-reactor is event routing — one isolated Agent per event.
Permissions & Risks
- shell actions run in the dsh process; only trust rules you create.
- http-poll makes requests to configured URLs; ensure targets are trusted.
- Goal mode creates isolated Agent sessions with
permissionPreset boundary control.
- webhook listens on loopback by default; configure
webhookToken + TLS for external exposure.
- All data stored locally in
~/.dsh/reactor/; no third-party telemetry.
Compatibility
| Item | Requirement |
|---|
| DeepSeek Harness | ≥ 0.1.2-rc.1 (@deepseek-ai/cordis ^4.0.0) |
| Node.js | ≥ 22 |
| Profile | web full features; headless auto-degrades |
| Platform | Windows / Linux / macOS |
Development
pnpm install
pnpm typecheck
pnpm build
License
MIT
中文
面向 DeepSeek Harness 的事件驱动自主 Agent 运行时
让 DeepSeek Agent 从"随叫随到的助理"变成"主动感知环境、自主完成目标的守护进程"。
dsh-reactor 不是另一个 cron 插件。它把 DeepSeek Harness 的 Agent 变成一个事件驱动的自主运行时：你告诉它"监控什么、什么时候值得处理、想达成什么目标"，它就在后台持续观察，一旦条件命中，拉起一个隔离的 Agent Session，让 LLM 用 ReAct 自主完成任务、验证结果、自动恢复，并留下完整运行轨迹。
社区插件，非 DeepSeek 官方出品。
为什么不是 cron？
| 维度 | 传统 cron 插件 | dsh-reactor |
|---|
| 触发方式 | 固定时间 | 任意事件源 + 条件评估 |
| 决策逻辑 | 到点就执行 | 评估条件后决定是否执行 |
| 执行方式 | 跑预设脚本 | 拉起隔离 Agent，LLM ReAct 自主完成 |
| 结果验证 | 无 | 确定性验证（文件存在/命令退出码） |
| 失败恢复 | 无 | 自动分类 + 智能 retry |
| 状态感知 | 无 | 上次摘要注入，续作不重头开始 |
| 可审计 | 日志 | 完整 Run Trace 决策链 |
安装
dsh plugin --profile web add dsh-reactor
安装后重启 dsh web，右下角出现时钟主题挂件。
卸载
dsh plugin --profile web remove dsh-reactor
快速开始
安装后，在 DSH 对话中直接用自然语言描述你的目标：
"帮我监控 https://api.github.com/repos/snhna-a/dsh-reactor 的最新 commit，当 HEAD 变化时，在 C:\work\dsh-reactor 目录里 git pull 最新代码并跑 npm run build，然后告诉我结果。"
Agent 会自动调用 reactor_define 创建规则。之后无需人工干预，规则在后台持续运行。
更多示例：
- "监控 deploy.json 文件，当 version 字段变化时，发 webhook 通知"
- "每 5 分钟跑
git log --oneline -1，当输出变化时，在新会话里分析这次提交"
- "轮询某网站的监控 API，当 status 变成 error 时，让 Agent 自动诊断并修复"
核心概念：ECG（事件-条件-目标）
dsh-reactor 把传统 ECA 升级为 ECG：
Event（事件）
↓ 轮询/监听/接收推送
Condition（条件）
↓ JSONPath + 比较运算 + AND/OR + changed
Goal（目标）
↓ 拉起隔离 Agent Session，LLM ReAct 自主完成
关键区别：Action 模式跑固定脚本；Goal 模式把你的目标 + 事件上下文注入隔离 Agent Session，让 LLM 自己决定怎么完成——拉代码、跑测试、分析报错、修复、再验证，全程自主。
事件源
| 类型 | 说明 |
|---|
http-poll | 轮询 HTTP 接口，解析 JSON/文本 |
file-watch | 读取本地文件（自动处理 BOM） |
command | 执行 shell 命令，解析 stdout |
webhook | 外部系统 HTTP POST 主动推送 |
条件
JSONPath（$.status、$.data.count）+ 运算符（eq/ne/gt/contains/exists/changed）+ AND/OR 组合。
两种执行模式
Action 模式（传统 ECA）
shell：执行命令（支持 {{payload.field}} 模板）webhook：POST JSON 到指定 URLagent-talk：在隔离 Session 中跑提示词
Goal 模式（ECG，推荐）
- 拉起隔离 Agent Session
- 注入你的目标 + 上次运行摘要（续作）
- LLM ReAct 自主完成：读文件、跑命令、调工具、验证结果
- 完成后自动做确定性验证（文件存在/命令退出码）
- 失败自动分类 + 智能 retry
安全与防护
| 机制 | 说明 |
|---|
| Budget Gate | maxRunsPerDay / maxTokens 硬门，超限 blocked 0 token |
| Approval Gate | riskLevel: high + requireApproval → 等人工批准才跑 |
| Preflight | 启动 Agent 前检查工作目录/文件系统/网络能力，缺能力 blocked 0 token |
| Cooldown | 触发后冷却时间，防刷屏 |
| Overlap Protection | 同一规则不并发跑 |
| Failure Classification | 自动分类 transient/repairable/dangerous |
| Smart Retry | transient 错误（网络 blip/超时）自动多 retry 一次 |
可视化挂件
DSH Web 右下角常驻时钟主题挂件：
- 拖拽吸附：可拖到四边/四角，左吸附自动镜像翻转
- 大小调节：0.6–2.5x，半透明设置面板
- 触发提醒：规则触发、失败、重试时气泡提示
- 管理面板：总览 stats、规则列表（启停/删除）、规则详情
- Run Trace：每次 run 完整决策链时间线
- Failure 标签：一眼看出失败类型
- Token 消耗：每次 run 的 input/output/cache token
模型工具
Agent 通过以下工具管理规则（自然语言即可，无需手动操作）：
| 工具 | 用途 |
|---|
reactor_define | 创建规则（支持 action/goal 模式） |
reactor_list | 列出所有规则及运行状态 |
reactor_status | 查看规则详情 |
reactor_test | 用模拟载荷手动测试规则 |
reactor_remove | 删除规则 |
reactor_history | 查看执行历史 |
规则持久化与审计
- 规则自动持久化到
~/.dsh/reactor/rules.json，重启自动恢复
- 每次触发记录到
~/.dsh/reactor/history.jsonl（ring buffer 500 条）
- 历史包含：触发时间、匹配结果、事件载荷、Agent 会话 ID、Token 消耗、Run Trace steps、失败分类
- 下次同规则触发时，上次摘要自动注入 goal prompt（续作不重头开始）
与其他 DSH 插件的关系
- dsh-cron / dsh-automation：定时任务。dsh-reactor 是事件驱动 + Agent ReAct，不重复。
- dsh-cron-panel：定时任务面板。dsh-reactor 挂件是事件驱动规则的可视化。
- dsh-taskboard：人机协作看板。dsh-reactor 是后台自主运行，不需要人逐条验收。
- dsh-agent-teams：多 Agent 编排。dsh-reactor 是事件路由，每个事件拉起一个隔离 Agent。
权限与风险
- shell 动作在 dsh 运行环境执行命令，仅信任你自己创建的规则。
- http-poll向配置 URL 发请求，确保目标可信。
- Goal 模式在隔离工作区创建 Agent Session，使用
permissionPreset 控制能力边界。
- webhook 入口默认仅本地回环监听；对外暴露请配置
webhookToken + TLS。
- 所有数据存储在本地
~/.dsh/reactor/，不上传第三方。
兼容性
| 项 | 说明 |
|---|
| DeepSeek Harness | ≥ 0.1.2-rc.1（@deepseek-ai/cordis ^4.0.0） |
| Node.js | ≥ 22 |
| profile | web 完整能力；headless 自动降级 |
| 平台 | Windows / Linux / macOS |
开发
pnpm install
pnpm typecheck
pnpm build
License
MIT
