@goodandready/dsh-goal

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

📦 @goodandready/dsh-goal

<div align="center">

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

<p align="center">

<a href="https://www.npmjs.com/package/@goodandready/dsh-goal"><img src="https://img.shields.io/npm/v/@goodandready/dsh-goal.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>

<a href="LICENSE"><img src="https://img.shields.io/github/license/GooDAnDReaDY/dsh-goal.svg?style=for-the-badge&color=10b981&labelColor=064e3b" alt="license"></a>

<a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065" alt="DSH Plugin"></a>

<a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03" alt="Node version"></a>

</p>

<!-- Обязательная кнопка перехода на витрину всех проектов -->

<p align="center">

<a href="https://goodandready.app/"><img src="https://img.shields.io/badge/Все_проекты_автора-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="Все проекты автора"></a>

</p>

<p align="center">

<a href="README.md"><b>🇬🇧 English</b></a> •

<a href="README.ru.md"><b>🇷🇺 Русский</b></a> •

<a href="README.zh.md"><b>🇨🇳 中文说明</b></a>

</p>

<!-- Обязательный блок поддержки проекта: локализуй текст под язык README -->

<table align="center">

<tr>

<td align="center">

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

<br><br>

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

</td>

</tr>

</table>

</div>

---

⚡ 概述与解决的问题

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

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

@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 播放舒缓的合成音效。
• 📋 **两阶段目标模式：Plan Mode ⇄ Act Mode (#162)**：分离规划设计与落地执行。只读规划阶段严格限制文件变更与危险命令，待操作者在横幅或弹窗点击“批准并执行 (Approve & Execute)”后切入执行阶段。
• 🛡️ **自动化验收门禁与评审检验 (Critic Verification) (#163)**：里程碑可配置 verificationCommand 验证命令（如 npm test、pytest）。智能体尝试关闭阶段时，在受控 safeCwd 中自动执行检查；若失败（exitCode != 0）则阻断关闭并向模型反馈错误输出，仅当命令返回 0 时方可进入完成态并创建 Git 检查点。

---

🏛️ 架构图

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{\text{已运行时间}}{\text{已完成里程碑数}} \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 "Conten

…(truncated)