---
## ⚡ 概述与解决的问题
复杂的工程开发任务需要多步骤的自主推进：将高层目标分解为有序的里程碑、在各轮交互间无需用户重复提示即可持续执行，并保持清晰直观的进度可视化。
如果缺乏目标跟踪框架，智能体容易在多轮对话中丢失上下文、陷入被动等待，或在遇到卡点时无法及时提醒用户。
**`@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 检查点。
---
## 🏛️ 架构图
```mermaid
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` 的可视化设置面板。
---
## 📦 安装说明
```bash
dsh plugin --profile web add @goodandready/dsh-goal
```
安装完成后重启 DeepSeek Harness 实例并刷新浏览器即可。
---
## 💬 使用指南
### 1. 通过聊天输入启动目标
在聊天输入框中直接输入 `/goal` 命令：
```text
/goal 重构鉴权中间件并补充完整的单元测试
```
智能体将立即：
1. 通过 `goal_set_milestones` 制定清晰的步骤规划；
2. 逐项执行，并通过 `goal_update_progress` 标记 `in_progress` 与 `completed`；
3. 全部完成后调用 `goal_finish` 输出最终总结。
### 2. 快速启动按钮
点击输入框上方的 **启动目标** 按钮，在弹出的窗口中输入任务描述并点击确认。
### 3. 通过 REST API 控制
也可以通过 HTTP 请求远程控制目标：
```bash
# 启动目标
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` 中配置，或在 **设置 → 插件 → 目标模式** 界面中调整：
```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` | 是否在输入框上方常驻快速启动按钮 |
---
## 🧪 自动化测试
运行单元与集成测试套件：
```bash
npm test
```
---
## 📄 开源许可
MIT © [GooDAnDReaDY](https://github.com/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/
