GooDAnDReaDY/dsh-goal

---

⚡ 概述与解决的问题

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

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

@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{\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 "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/<timestamp>-<slug>.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 状态的问题，未就绪时正确显示不可用/加载状态。