dsh-better-goal

目标管“要完成什么”，todo_write 管“下一步做什么”。 两者分开，长任务不会只剩一页待办，目标也不会在重开后消失。

与 DSH 原生 goal 对比

自动续跑不应该变成“明知做不了，还继续跑”。 原生 goal 已经提供持久目标与自动续跑；better-goal 改进的是遇到阻塞时及时停下、可控的提问等待，以及更简单的目标操作。

对比以 DSH 0.2.1-rc.2 的默认行为为基准。原生也支持完成、用户暂停和清除，并非完全不能停止；关键差异是自主续跑中的模型能否在需要人介入时立即暂停。

两者都能保存目标、跨轮推进、暂停和恢复；这些不是本插件独有的能力。原生也有可选的定时提问，本插件的改进是在目标执行时默认应用统一的等待策略，而不是声称只有本插件才能处理超时。

例子：任务卡在必需的 API 密钥

如果后续步骤必须请求外部服务，而当前没有可用密钥，Agent 不能靠“再努力一轮”把密钥变出来。应当先说明缺失项并停下，而不是反复请求、重复验证，或把未完成的任务标成成功。

原生默认行为下，这里容易落入两种困境：

• 没有成功报告受阻：目标仍在进行中，回合结束后继续排下一轮，缺失的密钥却不会因此出现。
• 改为提问等待：默认会卡在当前提问上，直到用户回答或中止；即使还有独立工作能做，也不能先从这次等待返回。轮数上限不是等待超时，不能解决这个问题。

flowchart TD
    A["自动执行目标"] --> B["发现缺少必需的 API 密钥<br/>Agent 无法自行补齐"]
    B --> N["原生 goal<br/>报告受阻有轮数门槛"]
    N -->|"目标仍在进行中"| L["下一轮继续尝试<br/>缺失条件并未改变"]
    L --> N
    N -->|"满足受阻条件并报告 / 到上限 / 用户停止"| X["停止续跑"]
    B --> G["better-goal<br/>立即暂停并说明缺失项"]
    G --> S["停止自动续跑<br/>不假装完成"]
    S -->|"补齐密钥后，用户或 Agent 明确继续"| R["沿用目标与计数<br/>继续执行"]

原生并不一定无限循环：报告受阻、达到轮数上限或用户停止都能结束续跑。这里要避免的是在无法改变的阻塞上继续消耗回合；如果还有可以独立推进的有效工作，Agent 应先完成那些工作，再判断是否需要停下。

安装：只选一个入口

需要 DSH >=0.2.1-rc.2 <0.3.0 和 Node.js ^22.19.0 || >=24.0.0。无构建步骤。

通过 Apollo 安装（推荐）

Apollo（npm 包）是包含流程技能、工程模式和本插件的集合，goal 是其中一个独立子插件。从 npm 安装 Apollo 会自动带入 dsh-better-goal，不需要再安装一次：

dsh plugin --profile <profile> add @menghuan1918/dsh-apollo@0.4.1

安装后，目标设置出现在 Plugins → @menghuan1918/dsh-apollo → dsh-better-goal 行。只保留 Apollo 入口即可。

旧版通过 GitHub 安装的 Apollo，在 Plugins 里仍显示为 dsh-apollo；迁移到 @menghuan1918/dsh-apollo 时先移除旧入口，再安装新包。会话记录保留，/goal 用法不变；迁移后请检查插件设置。

只安装目标插件（独立安装）

如果不需要 Apollo，可从 npm 单独安装本插件：

# npm 安装（推荐）
dsh plugin --profile <profile> add dsh-better-goal@0.2.0

# 或从 GitHub main 源码安装（次入口）
dsh plugin --profile <profile> add github:Menghuan1918/dsh-better-goal

完成后，目标设置出现在 Plugins → dsh-better-goal → dsh-better-goal 行。npm 包页面：dsh-better-goal。

安装或升级后要重启对应的 DSH profile。 刷新网页只会重载界面，不会替换正在运行的实现；插件也不会自动修改你当前打开的 GUI。

本地开发安装见开发文档。

用起来

典型流程：

flowchart TD
    A["提出一个完整目标<br/>/goal 目标，或让 Agent 创建"] --> B["目标进入进行中<br/>开始自动续跑"]
    B --> C{"这一轮结束"}
    C -->|"还有未完成的工作"| D["自动开始下一轮"]
    D --> C
    C -->|"当前证据证明完成"| E["标记完成<br/>GoalBar 隐藏"]
    C -->|"需要人介入（缺密钥 / 权限 / 决定）"| F["Agent 暂停并说明缺什么"]
    C -->|"用户暂停或中断"| G["暂停<br/>不再自动续跑"]
    F --> H["用户或 Agent 显式恢复"]
    G --> H
    H --> B
    J["重开、恢复或 fork 会话"] --> K["恢复目标与轮数<br/>自动续跑保持关闭"]
    K --> H

计划模式或待提交选择期间，自动轮次会先让路；等待提问、还有子代理在运行时也不会抢跑。你打断当前回合时，进行中的目标会停在暂停状态，而不是自己重新启动。

Agent 侧：五个动作

模型侧只用一个 goal 工具，你不需要记调用格式，也没有内部编号要填：

只在确实要替换总目标时用 set；不要用它绕过轮数上限或丢掉未完成的范围。Agent 不会用 mock、硬编码或跳过检查来“完成”目标；缺条件就暂停并说明缺什么。清除仍由 GoalBar 或 /goal clear 完成。

0.2.0 变更：模型侧的 fail 改为 pause。/goal fail <原因> 保留为人类命令，会记录原因并标记受阻；历史上由模型记录的受阻目标仍可读取和恢复。

人类命令

例如：

/goal 给导出接口补上分页，并用现有测试证明没有回归
# Agent 自动接续；需要你决定时会提问
/goal pause
/goal resume

/goal 命令由插件直接提供，不依赖模型是否记得调用工具。/goal create <目标> 是 /goal set 的显式别名。编辑一个已经完成的目标会新建目标；旧目标仍保留在会话历史里。

GoalBar

输入框上方会出现目标条，显示当前状态、目标摘要和 第 n / 上限 轮。暂停、恢复、编辑和清除按钮会按当前状态出现；完成的目标会自动隐藏。

目标条不负责新建或整体替换目标：用 /goal <目标>（或 /goal set <目标>），或让 Agent 设定。

设置

打开 Plugins → dsh-better-goal → dsh-better-goal 行；由 @menghuan1918/dsh-apollo 装配时，打开 Plugins → @menghuan1918/dsh-apollo → dsh-better-goal 行。两处操作同一份配置。保存后立即生效，不需要重启。

默认设置速览

默认组合：agent + 256 + 120 秒。 其中 256 只在切到“固定轮数”后生效，120 秒只影响目标进行中的新提问。

设置只影响之后的新轮次和新提问：不重置已用轮数，也不会自动恢复已经停下的目标。

轮数上限：三种模式

flowchart TD
    S["轮数上限策略"] --> A{"选择"}
    A -->|"agent（默认）"| AG["由 Agent 决定<br/>可显式设上限；创建时没给就不设"]
    A -->|"unlimited"| UN["无上限<br/>忽略模型传来的轮数"]
    A -->|"fixed"| FX["固定轮数<br/>默认 256，忽略模型传来的值"]
    AG --> R["设了有限上限时<br/>达到后停下，调高后可继续"]
    FX --> R
    UN --> OK["不会因轮数自动停下"]

• agent（默认）：Agent 可以给目标设一个轮数上限；新建时没给就不设上限，编辑或恢复时没给则沿用原值。
• unlimited：统一无上限，模型传入的轮数会被忽略。
• fixed：统一使用设置里的固定值（默认 256），模型传入的轮数会被忽略。

达到上限时，目标会变为受阻并停止自动续跑。把上限调高后，可以 /goal resume 继续；把上限调到已用轮数以下不会让计数倒退，只会让运行中的目标停下。

提问超时

• 默认等待 120 秒；设为 -1 表示永不超时。
• 只在目标进行中、且自动续跑开启时接管本来就存在的 ask_user_question；不会给“无提问”预设新增提问工具。
• 超时后，问题仍然是待回答：之后仍可回答，Agent 也可以先做不依赖答案的工作。超时不是同意，也不是跳过。
• 修改设置只影响新发起的等待；已经开始等待的问题保留原期限。

恢复、暂停与完成

• 重开、恢复或 fork：恢复目标、状态和已用轮数，但自动续跑保持关闭；必须显式恢复。
• 用户中断：停止自动续跑，并在安全的回合边界保存为暂停；不会把暂停通知当成新提示自动启动。
• 计划模式：计划模式或待提交的选择不会自动续跑。
• 完成：Agent 会按目标逐项核对当前文件、命令结果、测试和运行状态；局部进度或“应该可以”不算完成证据。你也可以用 /goal complete 直接标记完成。
• 失败：遇到明确阻塞时，Agent 会带着具体原因立即停下，不会为了凑轮数继续空转。

FAQ

dsh plugin --profile <profile> remove dsh-better-goal

开发与许可

• 开发文档：数据兼容、双入口限制、测试与真实 DSH 冒烟、卸载回退。
• 许可证：GPL-3.0。移植的 DeepSeek Harness 代码保留 MIT 声明，见第三方声明和 MIT 许可证。
• 项目地址：Menghuan1918/dsh-better-goal。