@goodandready/dsh-goal 0.1.8 → 0.1.10

package/README.md

@@ -11,78 +11,127 @@
   <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>
 
-<!-- Author Showcase Link -->
+<!-- Обязательная кнопка перехода на витрину всех проектов -->
 <p align="center">
-  <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/All_Author_Projects-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="GoodAndReady Showcase"></a>
+  <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="docs/README.ru.md"><b>🇷🇺 Русский</b></a> •
-  <a href="docs/README.zh.md"><b>🇨🇳 中文说明</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>If you like this plugin, please star it on GitHub</strong> — it shows me that the plugin is useful to you and motivates me to keep developing it.
+      <br><br>
+      🐛 <strong>If you find a bug or would like to request a feature</strong>, open a GitHub issue in any language — I will review your proposal and implement useful suggestions in a future plugin version.
+    </td>
+  </tr>
+</table>
+
 </div>
 
 ---
 
 ## ⚡ Overview & The Problem
 
-Complex engineering tasks require multi-step autonomy: decomposing high-level objectives into milestones, executing successive iterations without manual user re-prompting, and maintaining clear visibility into task progress.
+Complex engineering tasks require multi-step autonomy: decomposing high-level objectives into sequential milestones, executing iterations without requiring manual user re-prompting, and maintaining clear visibility into task progress.
+
+Without an autonomous tracking framework, agents can lose context across turns, stall in passive loops, or fail to notify users when complex workflows stall.
 
-**`@goodandready/dsh-goal`** brings autonomous goal execution to DeepSeek Harness via the `/goal` command:
-* 🎯 **Sticky Top Goal Banner**: Pinned status header with live timer (`• 2s`, `• 1m 45s`), active goal title, and interactive control buttons.
-* ⏸️ **Play / Pause / Cancel**: Instantly pause the autonomous loop or resume execution on demand.
-* 📋 **Milestone Breakdown Drawer**: Interactive checklist showing sub-tasks, percentage completion, and iteration logs.
-* 🤖 **Autonomous Agent Tools**: Provides `goal_set_milestones`, `goal_update_progress`, and `goal_finish` tools directly to the agent.
-* 🛡️ **Safety Guardrails**: Configurable `maxIterations` limit to prevent runaway loops.
+**`@goodandready/dsh-goal`** introduces Goal Mode to DeepSeek Harness:
+* 🎯 **Sticky Top Goal Banner**: Pinned header over composer dock with live elapsed timer (`• 2s`, `• 1m 45s`), real-time status badge (`RUNNING`, `PAUSED`, `COMPLETED`), active goal title, and control actions.
+* ⏸️ **Play / Pause / Resume / Cancel**: Instantly pause the autonomous loop or resume execution on demand via buttons or `/goal` command.
+* 📋 **Milestone Breakdown & ETA**: Interactive checklist showing sub-tasks, completion status (`pending`, `in_progress`, `completed`, `failed`), progress bar, and dynamic completion ETA.
+* 🌐 **Multi-Language Auto-Detection (*Added in v0.1.9*)**: Prompt injection, autonomous follow-ups, and UI badges automatically follow the user's input language (English by default, Chinese, or Russian when entered in Cyrillic).
+* 🔘 **Quick Launch Button (*Added in v0.1.8*)**: Fast goal launcher docked above the message input with instant objective prompt modal. Toggleable in settings.
+* 📊 **Token Usage Tracking & Markdown Export (*Added in v0.1.7*)**: Accumulated prompt, completion, and total tokens tracked per session with one-click Markdown summary export.
+* 🤖 **Autonomous Agent Contract**: Provides `goal_set_milestones`, `goal_update_progress`, and `goal_finish` tools directly to the agent.
+* 🔄 **Core DSH Goal Tools Interception (*Added in v0.1.10*)**: Seamless drop-in compatibility for models calling built-in DSH goal tools (`update_goal`, `get_goal`, `create_goal`). Intercepts actions (`complete`, `pause`, `resume`, `edit`, `blocked`), bypasses rigid authority restrictions that caused crashes (`complete and blocked require a direct human turn`), and routes all state updates directly to GoalEngine.
+* 🛡️ **Safety Guardrails**: Configurable `maxIterations` safety limit and Smart Progress Guard to catch and pause idle turns without progress.
+* 🔔 **Web Audio Chimes**: Pleasant synthesized audio feedback on goal completion or failure via Web Audio API.
 
 ---
 
 ## 🏛️ Architecture
 
 ```mermaid
-graph TD
-    subgraph Input ["User Interaction"]
+graph LR
+    subgraph UserInterface ["User Interface & Interaction"]
         Cmd["Slash Command: /goal &lt;objective&gt;"]
-        API["REST API: POST /dsh-goal/action"]
+        Dock["Sticky Goal Banner (conversation.input.dock)"]
+        Modal["Goal Details & Milestone Modal"]
+        QuickLaunch["Quick Launch Goal Button"]
     end
 
-    subgraph GoalEngine ["Goal Lifecycle Engine (lib/index.js)"]
+    subgraph GoalEngineCore ["Goal Engine Core (lib/goal-engine.js)"]
         State["State Manager (IDLE, RUNNING, PAUSED, COMPLETED)"]
-        Milestones["Milestone Tracker & Decomposition"]
-        Disk["Persistence Store (~/.dsh/goal-state.json)"]
+        Milestones["Milestone Tracker & ETA Calculation"]
+        DiskStore["Persistence Store (goal-state.json)"]
+        LangDetector["detectLanguage (en, zh, ru)"]
     end
 
-    subgraph AgentLoop ["Autonomous Agent Drive"]
+    subgraph AutonomousLoop ["Autonomous Drive & Turn Coordinator (lib/index.js)"]
+        TurnHook["ctx.on('turn/end') AutoDrive"]
+        Guard["Smart Progress Guard & Iteration Limiter"]
+        PromptInject["getStatePromptInjection"]
+    end
+
+    subgraph AgentTools ["Cordis Registered Tools"]
         ToolSet["goal_set_milestones"]
         ToolProgress["goal_update_progress"]
         ToolFinish["goal_finish"]
-        LimitGuard{"maxIterations Guard"}
-    end
-
-    subgraph UI ["DSH Web Interface"]
-        Banner["Sticky Top Goal Banner"]
-        Timer["Live Elapsed Timer"]
-        Drawer["Milestone Checklist Modal"]
-        Settings["Settings Card (Schemastery)"]
     end
 
-    Cmd --> GoalEngine
-    API --> GoalEngine
-    GoalEngine --> State
-    State --> Disk
-    State --> Banner
-    State --> Drawer
-    GoalEngine --> AgentLoop
-    AgentLoop --> LimitGuard
-    ToolSet --> GoalEngine
-    ToolProgress --> GoalEngine
-    ToolFinish --> GoalEngine
+    Cmd --> GoalEngineCore
+    Dock --> GoalEngineCore
+    QuickLaunch --> GoalEngineCore
+    GoalEngineCore --> DiskStore
+    GoalEngineCore --> AutonomousLoop
+    AutonomousLoop --> PromptInject
+    GoalEngineCore --> Modal
+    AgentTools --> GoalEngineCore
+    AutonomousLoop --> Guard
 ```
 
 ---
 
+## ✨ Features & Module Breakdown
+
+### 1. `lib/goal-engine.js` — State Engine
+Zero external dependency core managing session goals, milestone states, elapsed time calculations, ETA forecasts, token accumulators, and crash recovery hydration.
+* **Auto Language Detection**: Automatically analyzes goal title and parameters (`detectLanguage`) to select English (`en`), Chinese (`zh`), or Russian (`ru`).
+* **ETA Estimator**: Predicts remaining time based on average milestone velocity:
+  $$\text{ETA} = \frac{\text{elapsed}}{\text{completedMilestones}} \times \text{remainingMilestones}$$
+* **Low-Latency State Serialization**: Synchronous debounced atomic file persistence to prevent data loss on crashes.
+
+### 2. `lib/command-handler.js` — Slash Commands
+Handles `/goal` commands and subcommands:
+* `/goal <objective>`: Starts a new autonomous goal.
+* `/goal pause`: Pauses current goal and halts agent turn.
+* `/goal resume`: Resumes execution and triggers agent continuation.
+* `/goal clear`: Resets session goal to IDLE.
+* `/goal`: Shows status, elapsed time, ETA, iterations, tokens, and active milestones.
+
+### 3. `lib/index.js` — DSH Cordis Lifecycle Coordinator
+* Registers REST API endpoints (`GET /dsh-goal/state`, `POST /dsh-goal/action`, `GET /dsh-goal/events` SSE stream).
+* Subscribes to `turn/end` for zero-latency turn-to-turn auto-drive using `setImmediate`.
+* Listens to `approval/asked` to automatically pause goal when operator confirmation is needed.
+* Registers agent tools: `goal_set_milestones`, `goal_update_progress`, `goal_finish`.
+* Seamlessly shadows core DSH goal tools: `update_goal`, `get_goal`, `create_goal` with zero collision and full `GOAL_OUTPUT` schema compliance.
+
+### 4. `lib/client.js` — Frontend Web UI
+* **Sticky Top Banner**: Mounts via slot `conversation.input.dock` with live timer, status badge, pause/resume, and details button.
+* **Goal Details Modal**: Full milestone list, progress bar, token statistics, and 📋 Markdown Report Copy.
+* **Quick Launch Button**: Floating launcher for rapid goal formulation without typing slash commands.
+* **Plugin Settings Card**: Schemastery-backed settings UI registered via `settings.plugin.item`.
+
+---
+
 ## 📦 Installation
 
 ```bash
@@ -95,42 +144,70 @@ Restart your DeepSeek Harness instance and refresh the browser.
 
 ## 💬 Usage & Quick Start
 
-Start a goal directly in chat:
+### 1. Start a Goal via Chat
+Simply enter the `/goal` slash command:
 
 ```text
-/goal Refactor the authentication middleware and add integration tests
+/goal Refactor authentication middleware and cover with unit tests
 ```
 
-Or trigger via REST API:
+The agent will immediately:
+1. Establish a structured milestone plan via `goal_set_milestones`.
+2. Advance through milestones, marking each `in_progress` and `completed` via `goal_update_progress`.
+3. Conclude with a full summary via `goal_finish`.
+
+### 2. Quick Launch Button
+Click the **Start Goal** button directly above the message input box, type your objective, and click **Start Goal**.
+
+### 3. REST API Control
+Control goals programmatically via HTTP:
 
 ```bash
+# Start a goal
 curl -X POST http://localhost:3080/dsh-goal/action \
   -H "Content-Type: application/json" \
-  -d '{"action":"start","title":"Optimize database queries"}'
+  -d '{"action":"start","title":"Implement automated backup pipeline"}'
+
+# Pause
+curl -X POST http://localhost:3080/dsh-goal/action \
+  -H "Content-Type: application/json" \
+  -d '{"action":"pause"}'
+
+# Resume
+curl -X POST http://localhost:3080/dsh-goal/action \
+  -H "Content-Type: application/json" \
+  -d '{"action":"resume"}'
+
+# Inspect live state
+curl http://localhost:3080/dsh-goal/state
 ```
 
 ---
 
 ## ⚙️ Configuration Reference (`settings.yaml`)
 
+Configure settings in `settings.yaml` or through the **Settings → Plugins → Goal Mode** UI card:
+
 ```yaml
 dsh-goal:
   maxIterations: 25
   autoDrive: true
   enableSound: true
+  showQuickLaunchButton: true
 ```
 
 | Parameter | Type | Default | Description |
 |:---|:---|:---|:---|
-| `maxIterations` | `number` | `25` | Safety limit: maximum autonomous iterations per goal |
+| `maxIterations` | `number` | `25` | Safety limit: maximum autonomous turns per goal |
 | `autoDrive` | `boolean` | `true` | Keep the autonomous agent loop running between turns |
-| `enableSound` | `boolean` | `true` | Play completion audio chime when a goal finishes |
+| `enableSound` | `boolean` | `true` | Play audio chime when a goal completes or fails |
+| `showQuickLaunchButton` | `boolean` | `true` | Show the quick launch goal button above the composer dock |
 
 ---
 
 ## 🧪 Testing
 
-Run the automated test suite:
+Run unit and integration tests:
 
 ```bash
 npm test

package/{docs/README.ru.md → README.ru.md}

@@ -17,11 +17,21 @@
 </p>
 
 <p align="center">
-  <a href="../README.md"><b>🇬🇧 English</b></a> •
+  <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>
 
+<table align="center">
+  <tr>
+    <td align="center">
+      ⭐ <strong>Если вам нравится этот плагин, поставьте ему звезду на GitHub</strong> — это покажет мне, что плагин вам полезен, и будет мотивировать меня развивать его дальше.
+      <br><br>
+      🐛 <strong>Если вы нашли баг или хотите предложить новый функционал</strong>, создайте issue на GitHub на любом языке — я рассмотрю ваше предложение и реализую полезные идеи в одной из следующих версий плагина.
+    </td>
+  </tr>
+</table>
+
 </div>
 
 ---
@@ -35,6 +45,7 @@
 * ⏸️ **Управление циклом (Play / Pause / Cancel)**: мгновенная приостановка автономного цикла агента или его возобновление в любой момент.
 * 📋 **Интерактивная панель майлстоунов**: модальное окно со списком подзадач, прогресс-баром и журналом выполнения.
 * 🤖 **Инструменты агента**: `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` для предотвращения бесконечных циклов.
 
 ---

package/README.zh.md

@@ -0,0 +1,219 @@
+# 📦 @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 播放舒缓的合成音效。
+
+---
+
+## 🏛️ 架构图
+
+```mermaid
+graph LR
+    subgraph UserInterface ["用户界面与交互"]
+        Cmd["斜杠命令: /goal &lt;目标&gt;"]
+        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
+```
+
+| 参数项 | 类型 | 默认值 | 说明 |
+|:---|:---|:---|:---|
+| `maxIterations` | `number` | `25` | 安全限制：每个目标允许执行的最大自主轮次 |
+| `autoDrive` | `boolean` | `true` | 是否在轮次之间自动保持循环执行 |
+| `enableSound` | `boolean` | `true` | 目标完成或失败时是否播放提示音效 |
+| `showQuickLaunchButton` | `boolean` | `true` | 是否在输入框上方常驻快速启动按钮 |
+
+---
+
+## 🧪 自动化测试
+
+运行单元与集成测试套件：
+
+```bash
+npm test
+```
+
+---
+
+## 📄 开源许可
+
+MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)

package/docs/design/DESIGN.md

@@ -116,3 +116,26 @@
 4. **Экспорт отчета в Markdown (One-click Markdown Export):**
    - Для выполненной цели модальное окно предоставляет кнопку «📋 Скопировать отчёт в Markdown».
    - Генерирует отчет с заголовком, статусом, длительностью, итерациями, расходом токенов, резюме результатов и таблицей вех.
+
+### Решение 10: Бесшовная совместимость и перехват базовых инструментов целей DSH (update_goal, get_goal, create_goal) (v0.1.10)
+
+**Контекст:**
+В GitHub Issue #2 пользователи столкнулись с ошибкой:
+`complete and blocked require a direct human turn or the current goal round`
+при попытке модели завершить или обновить цель вызовом встроенного инструмента `update_goal`.
+Причина: встроенный плагин ядра DSH (`@deepseek-ai/dsh-tool-goal`) накладывает жёсткие проверки происхождения хода (authority checks), которые дают сбой в автономных циклах и при вызовах вне строго размеченного раунда цели.
+
+**Принятые решения:**
+1. **Динамическое замещение инструментов ядра в `ToolRuntime`:**
+   - При инициализации `ctx.inject(['tools'], (tctx) => { ... })` плагин проверяет наличие `update_goal`, `get_goal`, `create_goal` в глобальном слое (`tctx.tools.layers.global.tools.data`), удаляет конфликтующие строгие определения ядра и регистрирует собственные полнофункциональные версии.
+2. **Маршрутизация действий в `GoalEngine`:**
+   - `update_goal` перехватывает все действия модели:
+     - `action: 'complete'` — завершает цель в `engine.completeGoal()`, внедряет заключительный контекст `<goal_complete>` и возвращает статус `complete`;
+     - `action: 'pause'` — переводит цель в паузу через `engine.pause()`;
+     - `action: 'resume'` — возобновляет цель (`engine.resume()`) и перезапускает автодрайв агента;
+     - `action: 'edit'` — обновляет цель (`title`) и лимит раундов (`maxIterations`);
+     - `action: 'blocked'` — фиксирует блокер в `engine.pause()` с возвратом фазы `blocked` и кода причины.
+3. **Строгое соответствие схеме `GOAL_OUTPUT`:**
+   - Все перехваченные инструменты возвращают структуры, валидные по спецификации `GOAL_VALUE_SCHEMA` ядра (`goal: null` при отсутствии активной цели, либо объект цели с `id`, `revision`, `objective`, `phase`, `roundsStarted`, `maxGoalRounds`, `activation`).
+4. **Нейтрализация устаревшего системного промпта ядра:**
+   - Удаляется секция `tool:goal` ядра с ошибочными директивами и заменяется актуальной динамической инструкцией `tool:dsh-goal`.