GooDAnDReaDY/dsh-goal

📦 @goodandready/dsh-goal

DeepSeek Harness 自主目标执行与多轮任务跟踪引擎

🇬🇧 English •
🇷🇺 Русский •
🇨🇳 中文说明

⭐ 如果您喜欢这个插件，请在 GitHub 上为它点亮 Star — 这能让我知道插件对您有用，并鼓励我继续开发和维护它。

🐛 如果您发现 Bug 或希望增加功能，请使用任意语言在 GitHub 上提交 Issue — 我会评估您的建议，并在后续版本中实现有价值的改进。

⚡ 概述与解决的问题

复杂的工程开发任务需要多步骤的自主推进：将高层目标分解为有序的里程碑、在各轮交互间无需用户重复提示即可持续执行，并保持清晰直观的进度可视化。

如果缺乏目标跟踪框架，智能体容易在多轮对话中丢失上下文、陷入被动等待，或在遇到卡点时无法及时提醒用户。

@goodandready/dsh-goal 为 DeepSeek Harness 带来了完整的目标模式（Goal Mode）：
* 🎯 输入框上方常驻目标横幅：顶部常驻状态条，配备实时计时器（• 2s、• 1m 45s）、状态徽章（RUNNING、PAUSED、COMPLETED）、当前目标名称与控制操作。
* ⏸️ 播放 / 暂停 / 恢复 / 取消：可通过按钮或 /goal 命令随时暂停自主循环，或在需要时恢复执行。
* 📋 里程碑拆解与 ETA 预测：交互式清单抽屉，展示子任务状态（pending、in_progress、completed、failed）、进度百分比与动态预估剩余时间。
* 🌐 多语言智能识别（v0.1.9 新增）：提示词注入、自主轮次追问和 UI 状态徽章自动匹配用户输入语言（默认英语，支持中文和俄语）。
* 🔘 快速启动按钮（v0.1.8 新增）：常驻于输入框上方的启动按钮，支持弹窗一键制定目标，可在设置中自由开关。
* 📊 Token 消耗统计与 Markdown 导出（v0.1.7 新增）：实时累计提示词、生成词及总 Token 消耗，支持一键复制完整 Markdown 报告。
* 🤖 智能体自主协作工具：向智能体直接提供 goal_set_milestones、goal_update_progress 和 goal_finish 工具。
* 🔄 DSH 核心目标工具无缝拦截与兼容 (v0.1.10 新增): 为使用原生 DSH 目标控制指令的模型提供完美向下兼容，透明接管 update_goal、get_goal、create_goal。拦截并处理 complete、pause、resume、edit、blocked 等操作，彻底解决原生工具抛出的 complete and blocked require a direct human turn 权限崩溃错误，所有状态直接同步至 GoalEngine。
* 🛡️ 安全防护机制：支持自定义最大迭代次数（maxIterations）以及智能卡顿检测（Smart Progress Guard）。
* 🔔 Web Audio 提示音：任务完成或失败时，通过 Web Audio API 播放舒缓的合成音效。

🏛️ 架构图

graph LR
subgraph UserInterface ["用户界面与交互"]
Cmd["斜杠命令: /goal <目标>"]
Dock["常驻目标横幅 (conversation.input.dock)"]
Modal["目标详情与里程碑弹窗"]
QuickLaunch["快速启动目标按钮"]
end

subgraph GoalEngineCore ["目标引擎核心 (lib/goal-engine.js)"]
State["状态管理 (IDLE, RUNNING, PAUSED, COMPLETED)"]
Milestones["里程碑跟踪与 ETA 计算"]
DiskStore["状态持久化存储 (goal-state.json)"]
LangDetector["语言检测器 (en, zh, ru)"]
end

subgraph AutonomousLoop ["自主循环与轮次协调器 (lib/index.js)"]
TurnHook["ctx.on('turn/end') 自动推进"]
Guard["卡顿防守与最大迭代限制"]
PromptInject["getStatePromptInjection 提示词注入"]
end

subgraph AgentTools ["Cordis 注册工具"]
ToolSet["goal_set_milestones"]
ToolProgress["goal_update_progress"]
ToolFinish["goal_finish"]
end

Cmd --> GoalEngineCore
Dock --> GoalEngineCore
QuickLaunch --> GoalEngineCore
GoalEngineCore --> DiskStore
GoalEngineCore --> AutonomousLoop
AutonomousLoop --> PromptInject
GoalEngineCore --> Modal
AgentTools --> GoalEngineCore
AutonomousLoop --> Guard

✨ 核心模块详解

1. lib/goal-engine.js — 状态引擎
纯 JavaScript 实现，零外部依赖，完整管理会话目标、里程碑状态、运行计时、ETA 预测、Token 累计与崩溃恢复水合。
* 语言自动识别：根据目标文本自动选择英语 (en)、中文 (zh) 或俄语 (ru)。
* ETA 预估计算：基于已完成里程碑的平均耗时进行动态预估：
$$\text{ETA} = \frac}} \times \text{剩余里程碑数}$$
* 原子防抖持久化：采用安全的临时文件写入与重命名机制，避免进程中断导致数据损坏。

2. lib/command-handler.js — 命令处理
处理 /goal 斜杠命令及其子命令：
* /goal ：启动新目标。
* /goal pause：暂停当前目标并中止智能体当前轮次。
* /goal resume：恢复执行并自动提示智能体继续。
* /goal clear：重置当前目标为 IDLE。
* /goal：展示状态、耗时、预估时间、迭代进度、Token 统计与里程碑列表。

3. lib/index.js — DSH Cordis 生命周期管理
* 注册 HTTP REST API（GET /dsh-goal/state、POST /dsh-goal/action 及 GET /dsh-goal/events SSE 实时流）。
* 监听 turn/end 事件，通过 setImmediate 实现轮次间的极低延迟自动驱动。
* 监听 approval/asked 事件，在需要操作员审批时自动暂停。
* 为智能体注册专属工具：goal_set_milestones、goal_update_progress、goal_finish。

4. lib/client.js — Web 前端界面
* 常驻目标横幅：注入 conversation.input.dock 插槽，包含实时计时、状态徽章、暂停/恢复与详情按钮。
* 目标详情弹窗：展示完整里程碑清单、进度条、Token 统计，并支持 📋 一键复制 Markdown 报告。
* 快速启动按钮：输入框上方的便捷入口，免去手动输入命令的繁琐。
* 设置卡片：基于 Schemastery 注册至 settings.plugin.item 的可视化设置面板。

📦 安装说明

dsh plugin --profile web add @goodandready/dsh-goal

安装完成后重启 DeepSeek Harness 实例并刷新浏览器即可。

💬 使用指南

1. 通过聊天输入启动目标
在聊天输入框中直接输入 /goal 命令：

/goal 重构鉴权中间件并补充完整的单元测试

智能体将立即：
1. 通过 goal_set_milestones 制定清晰的步骤规划；
2. 逐项执行，并通过 goal_update_progress 标记 in_progress 与 completed；
3. 全部完成后调用 goal_finish 输出最终总结。

2. 快速启动按钮
点击输入框上方的 启动目标 按钮，在弹出的窗口中输入任务描述并点击确认。

3. 通过 REST API 控制
也可以通过 HTTP 请求远程控制目标：

启动目标
curl -X POST http://localhost:3080/dsh-goal/action \
-H "Content-Type: application/json" \
-d '{"action":"start","title":"实现自动化备份流水线"}'

暂停目标
curl -X POST http://localhost:3080/dsh-goal/action \
-H "Content-Type: application/json" \
-d '{"action":"pause"}'

恢复目标
curl -X POST http://localhost:3080/dsh-goal/action \
-H "Content-Type: application/json" \
-d '{"action":"resume"}'

查看实时状态
curl http://localhost:3080/dsh-goal/state

⚙️ 配置说明 (settings.yaml)

可在 settings.yaml 中配置，或在 设置 → 插件 → 目标模式 界面中调整：

dsh-goal:
maxIterations: 25
autoDrive: true
enableSound: true
showQuickLaunchButton: true
| consecutiveToolFailureLimit | number | 3 | 连续 N 轮工具错误自动熔断暂停（0 为禁用） |
| enableBrowserNotifications | boolean | true | 目标完成时发送桌面原生系统通知 |

| 参数项 | 类型 | 默认值 | 说明 |
|:---|:---|:---|:---|
| maxIterations | number | 25 | 安全限制：每个目标允许执行的最大自主轮次 |
| autoDrive | boolean | true | 是否在轮次之间自动保持循环执行 |
| enableSound | boolean | true | 目标完成或失败时是否播放提示音效 |
| showQuickLaunchButton | boolean | true | 是否在输入框上方常驻快速启动按钮 |

🧪 自动化测试

运行单元与集成测试套件：

npm test

📄 开源许可

MIT © GooDAnDReaDY

📦 版本历史 (Release Notes)

v0.2.6
- Token 预算守护 (Token Budget Guard)：设置安全使用上限，并在消耗达阈值（默认80%）时注入预警引导，达到100%时软暂停（PAUSED_BUDGET_EXCEEDED），支持一键延展 +50k 预算。
- 子里程碑与检查清单 (Sub-milestones & Checklists)：支持里程碑层级下的细分任务清单（checklist: [{ text, done }]），支持前端实时勾选及提示词自动同步。
- Git 自动检查点 (Auto Git Checkpoints)：里程碑达成时可选自动生成快照提交，并在详情弹窗中支持一键回滚。
- 执行成果导出 (Run Artifact Export)：一键导出 Markdown 格式执行成果至 .dsh/goals/-.md（已添加 .dsh/ 至 .gitignore）。
- 紧凑面板模式 (Compact Dock Mode)：输入栏固定面板可折叠为精巧胶囊状态栏，状态保存至 localStorage。

v0.2.3
- 自动更新: 在 /api/dsh-goal/update 集成了一键更新 API 端点，并配备安全的原点验证。
- 模块化架构: 将服务端完整解耦为高内聚子模块（各模块均低于 600 行）：路由、工具、持久化存储、报告生成与更新器。
- 严格的多语言规范: 从 lib/.js 中清除了硬编码的俄语字符串与分支；核心原生支持英文（默认）与中文，俄语由 @goodandready/dsh-russian-lang 插件提供。
- 健壮性与错误处理: 消除了所有空 catch 块，在目标完成与阻塞的上下文延迟中添加了日志记录，并自动清理断开的 SSE 连接。
- 设计系统规范: 将第三方 CSS 类与硬编码 RGBA 颜色替换为原生 DSH 主题设计变量（--dsw-alias-）。
- 设置卡片状态保护: 修复了设置作用域未加载时错误显示 ready 状态的问题，未就绪时正确显示不可用/加载状态。