需求对齐护栏jiezeng2004-design/dsh-requirements-alignment

dsh-requirements-alignment

阻止长时间运行的 agent 悄悄改变你的需求。

让 DSH Agent 自己做工程决策，但别让它在长任务里悄悄改需求、扩范围、换架构。

dsh-requirements-alignment 是面向 DeepSeek Harness (DSH) 的轻量级运行时漂移防护工具。它把用户意图转化为持久的需求基线，在 agent 工作期间保持不干扰，只有当下一步会实质性改变方向时才介入。

你决定方向。Agent 决定工程实现。

当前版本：v0.4.2，面向 DeepSeek Harness 0.1.1-rc.2。需要 Node.js >=22.18.0。

问题所在

长时间运行的编码 agent 擅长保持推进势头。这也正是它们可能发生漂移的原因。

一个任务可能最初是这样的：

修复结果页筛选器。
不要重构后端逻辑。

后来 agent 发现，更干净的解决方案需要改动后端。如果没有明确的护栏，它可能就直接扩大范围并继续下去。

Requirements Alignment 改变了这种行为：

用户意图
↓
持久的需求基线
↓
Agent 正常工作
↓
检测到改变方向的步骤？
├─ 否  → 静默继续工作
└─ 是 → 询问一次 → 记录决策 → 继续

什么算作漂移

该插件关注的是方向层面的变更，而非实现细节。

典型的漂移候选包括：

- 扩大或缩小已批准的范围；
- 违反明确的约束；
- 改变用户可见的行为；
- 切换架构或产品形态；
- 使已确定的假设失效；
- 改变此前已批准的用户决策；
- 采取会改变预期结果的破坏性路径。

它不应为了询问变量命名、辅助函数放置位置、已批准范围内的普通重构，或其他常规工程选择而中断 agent。

Requirements Alignment 与 Plan Mode 的对比

Plan Mode 问的是：
“这是正确的实现计划吗？”

Requirements Alignment 问的是：
“我们还在解决正确的问题吗？”

Plan Mode 在实现开始之前提供帮助。Requirements Alignment 在执行期间保护意图。

二者互补：

计划 → 批准 → 执行 → 检测方向漂移 → 仅在需要时重新对齐

快速开始

安装到你的 DSH Web profile：

dsh plugin --profile web add dsh-requirements-alignment

然后正常使用 DSH 即可。

Auto 模式是推荐的默认模式。 清晰的任务会零中断地继续。当出现真正的方向变更时，插件会呈现一个决策并记录结果。

随时使用 /align 进行显式状态检查。

三种模式

| 模式 | 行为 |
| --- | --- |
| Auto | 监视方向层面的漂移，仅在必要时询问 |
| Manual | 无自动漂移策略；需要检查时使用 /align |
| Off | 该会话的 Alignment 能力被禁用；/align-mode 仍可用，以便你切换回来 |

常用命令：

/align
/align-mode
/align-mode auto
/align-mode manual
/align-mode off
/align-mode reset

按会话控制：

/align-mode session
/align-mode session auto
/align-mode session manual
/align-mode session off
/align-mode session reset

会话覆盖只会更改该会话。共享运行时设置保持独立。

示例

保持在原始范围内

用户：
改进结果页筛选器。不要重构后端逻辑。

智能体：
[正常执行]

智能体发现：
完整修复需要更改后端。

需求对齐：
[报告一个偏移候选并询问]

用户：
保持在当前范围内。

智能体：
[保持后端不变，并在已批准的方向内继续]

批准真正的方向变更

用户：
该应用是单用户且仅本地使用。

之后：
让它跨设备工作。

需求对齐：
[检测到账户/云同步可能会改变架构]

用户：
批准方向变更：多用户，带账户和云同步。

智能体：
[记录新的基线修订并继续]

工作原理

该插件提供一小组对齐原语：

- establish_baseline 记录当前目标、明确约束、必须保留的行为、允许的范围以及已确定的用户决策；
- report_drift 呈现实质性的方向变更，通过 DSH 的原生用户提问路径进行询问，并记录确切的决策；
- /align 报告当前对齐状态并请求重新检查；
- /align-mode 更改自动 / 手动 / 关闭行为，而无需卸载插件。

规范的对齐状态保存在持久化的 sidecar 存储中，而不是混入普通的 DSH 会话事件。这样可以保持恢复/分叉/压缩行为的稳定，并避免将会话日志变成插件专用的状态数据库。

运行时模式模型

有效模式遵循以下顺序：

有效的会话覆盖
↓
有效的持久化运行时覆盖
↓
有效的配置文件默认值
↓
auto

这意味着两个活动会话可以使用不同的对齐模式，而不会相互泄漏状态。

切换模式会改变哪些对齐能力处于活动状态。它不会删除需求基线或偏移历史。

Web UI

在支持的 DSH Web 构建中，该插件包含一个小型浮动对齐控件，可显示当前会话模式和共享模式，而无需手动编辑配置文件。

该 UI 和 /align-mode 作用于相同的底层状态，因此它们旨在保持一致。

长时间运行的任务可以等待并继续

当智能体确实需要你的决策时，预期行为是等待而不是猜测。

等待浏览器授权，然后授权完成并恢复发布

同样的设计原则也适用于需求偏移：在高影响选择处暂停，记录它，然后从新的基线继续。

该插件不做什么
- 它不会取代 DSH Plan Mode。
- 它不会把每一个工程选择都变成用户问题。
- 它不会要求在工作开始前必须有完整的 PRD 或规格说明。
- 它不会重写 DSH 核心包。
- 它不会持续打断清晰明确的任务。
- 它不会在模式变更时删除对齐状态。

卸载

dsh plugin --profile web rm dsh-requirements-alignment

Off 与卸载并不相同：Off 会保留插件安装，以便会话在运行时可以切回 Auto 或 Manual。

设计目标

该项目有意避免成为一个完整的需求管理系统。

它的职责更窄：

保护少数定义“正在构建什么”的人类决策，然后让 agent 开始工作。

开发重点

该实现围绕以下方面设计：

- 持久的基线状态与漂移状态；
- 会话范围内的模式隔离；
- 恢复 / 分叉 / 压缩的连续性；
- 热模式切换，且不会产生重复注册或监听器泄漏；
- 与常规 DSH 会话语义兼容；
- 当请求的方向已经明确时，尽量减少打断。

许可证

MIT。参见 LICENSE。