dominds 1.2.5 → 1.2.7

package/dist/docs/drive-logic-context-refactor-plan.zh.md

@@ -0,0 +1,338 @@
+# Drive 逻辑上下文拼装现状与重构计划（2026-02）
+
+状态：Draft  
+语义基线：以 `dominds/main/llm/driver.ts` 与 `dominds/main/persistence.ts` 当前实现为准。
+测试基线（2026-02-09 更新）：drive 相关脚本统一通过 `main/llm/driver-entry.ts` 调用，可用 `DOMINDS_DRIVER_ENGINE=v1|v2` 进行引擎切换验证。
+
+## 1. 背景与目标
+
+近期在对话 `@ux (39/12/417f4a49)` 中暴露出一个上下文一致性问题：同一主线对话内已经收到了 `@cmdr/@browser_tester` 的回贴并据此更新 Taskdoc，但后续回复仍声称“没看到原始回贴文本”。
+
+这类问题的根因不是单条提示词，而是 **drive 内多轮生成的上下文来源语义不统一**：有的上下文是持久消息（`dlg.msgs`），有的是一次性注入（仅首轮），还有的是消费队列（take/commit/rollback）。
+
+本文目标：
+
+1. 固化“当前代码结构现状”的可审计视图。
+2. 记录本轮已做的修补。
+3. 制定一次更大范围的 drive logic 重构计划，使后续维护更清晰、不易回归。
+
+## 2. 当前结构（代码现状）
+
+### 2.1 核心文件与职责
+
+- `main/llm/driver.ts`
+  - `_driveDialogStream()`：单次 drive 主循环，负责 prompt 处理、上下文拼装、LLM 调用、工具调用、suspend/continue。
+  - `supplyResponseToSupdialog()`：子对话回贴写入父对话响应队列、更新 pending、触发 auto-revive。
+- `main/persistence.ts`
+  - `takeSubdialogResponses()/commitTakenSubdialogResponses()/rollbackTakenSubdialogResponses()`：子对话回贴队列的“取走-提交/回滚”机制。
+  - `rebuildFromEvents()`：重建 `dlg.msgs`（包含 `teammate_response_record -> tellask_result_msg` 映射）。
+- `main/dialog.ts`
+  - `addChatMessages()`：运行时消息容器（in-memory）。
+
+### 2.2 当前上下文来源（进入 LLM 的入口）
+
+在 `_driveDialogStream()` 中，每轮 gen 的 `ctxMsgs` 由以下部分拼装：
+
+1. `prependedContextMessages`（策略注入）
+2. `memories`
+3. `taskDocMsg`
+4. `coursePrefixMsgs`
+5. `dialogMsgsForContext`（来自 `dlg.msgs`）
+6. `subdialogResponseContextMsgs`（来自 `takeSubdialogResponses` 的注入）
+7. `internalDrivePromptMsg`（internal prompt 注入）
+8. reminders + language guide（末尾插入）
+
+要点：`dlg.msgs` 是“稳定上下文”；队列/内部 prompt 属于“drive 级上下文”。
+
+## 3. 本轮修补（已落地）
+
+### 3.1 已修问题
+
+1. **同一 drive 多轮丢失 teammate response 上下文**
+   - 修复：把 `takeSubdialogResponses` 生成的 `subdialogResponseContextMsgs` 在同一 drive 内跨迭代保留，而非仅 `genIterNo===1` 注入。
+
+2. **中断时误 commit 已 take 队列**
+   - 修复：在 interrupted 分支标记 `generationHadError = true`，确保 finally 走 rollback，不会把未稳定消费的队列当作已消费。
+
+3. **internal prompt 语义收敛为 drive 级 priming**
+   - 修复：移除生命周期分支；`persistMode='internal'` 统一为 drive-scoped priming 注入。
+   - 语义：仅在当前 drive 生效、不入 `dlg.msgs`、不持久化、不渲染 UI。
+   - 依据：当前唯一使用场景是 Agent Priming，且明确要求 loop 迭代中持续可见。
+
+4. **teammate response 稳定化到 `dlg.msgs`（与工具结果语义对齐）**
+   - 修复：当 take/commit 成功后，把该批回贴镜像为 `tellask_result_msg` 写入 `dlg.msgs`，让后续 drive 不依赖一次性队列注入。
+
+5. **队列记录补齐状态字段**
+   - 修复：`subdialog-responses` 记录新增可选 `status`（`completed|failed`），并在镜像消息时使用该状态（默认 `completed`）。
+
+## 4. 仍存在的结构债务
+
+### 4.1 状态语义分散
+
+同一类“队友回贴事实”同时存在于：
+
+- `teammate_response_record`（事件持久层）
+- `subdialog-responses.json`（消费队列）
+- `dlg.msgs`（运行时上下文）
+
+缺少单一“源事实 -> 视图派生”的规范，维护成本高。
+
+### 4.2 拼装流程耦合过深
+
+`_driveDialogStream()` 同时承担：
+
+- prompt 生命周期管理
+- 上下文装配
+- policy 校验
+- 流式/非流式分支
+- 工具调用循环
+- suspend/revive 与队列提交事务
+
+单函数职责过重，不利于做语义回归验证。
+
+### 4.3 缺少针对性回归测试矩阵
+
+现有 tellask 测试覆盖“auto-revive 能跑通”，但对以下关键边界覆盖不足：
+
+- 同一 drive 的多轮迭代上下文一致性
+- interrupted + take queue 的 rollback 语义
+- committed queue 镜像到 `dlg.msgs` 后的去重/恢复语义
+
+## 5. 语义决策记录（本轮确认）
+
+1. `persistMode='internal'` 不是“下一轮临时补丁”，而是 **drive 级 priming 通道**。
+2. 当前无 `next_gen` 真实业务需求，先不保留该分支，避免语义包袱。
+3. 如未来出现单轮内部提示需求，新增能力应基于明确场景和回归测试，不提前抽象。
+
+## 6. Priming 重点支持目标
+
+本次重构把 Agent Priming 作为第一优先级目标，不再作为“顺带兼容”。
+
+### 6.1 Priming 对 drive 的硬需求
+
+1. Priming 使用的临时引导 prompt 只作用于当前 drive。
+2. 在同一 drive 的多轮迭代中（工具调用、context remediation、continue）必须持续可见。
+3. 该 prompt 不进入 `dlg.msgs`，不写事件，不落盘，不渲染 UI。
+4. drive 中断/失败后不得残留到下一次 drive。
+
+### 6.2 Priming 支持实现（简化方案）
+
+核心原则：**不做通用“多生命周期临时 prompt 框架”，只保留 drive 级 priming 通道**。
+
+1. 在新 driver 中把 priming 输入建模为单一字段：`internalDrivePrimingMsg?: ChatMessage`。
+2. 上下文装配时固定规则：每轮迭代都在末尾注入 `internalDrivePrimingMsg`。
+3. 通过 driver 生命周期自然回收：drive 结束即销毁，不做额外状态机。
+4. 仅保留 `persistMode='internal'` 这一种 priming 入口，不再引入 `next_gen`/scope 分叉。
+
+这样可以把 priming 需求落实为“一个字段 + 一条注入规则”，实现面最小化。
+
+## 7. 两阶段重构计划（按新模块重写）
+
+### 阶段 1：新建并上线 `driver-v2`，旧模块原样保留
+
+目标：在新模块里重写 drive 逻辑，旧 `driver.ts` 保持原样，便于并排对比与问题定位。
+
+交付物：
+
+1. 新模块（建议）：
+   - `main/llm/driver-v2/index.ts`（对外入口）
+   - `main/llm/driver-v2/orchestrator.ts`（drive 级编排入口）
+   - `main/llm/driver-v2/types.ts`（v2 内部类型与运行态）
+   - `main/llm/driver-v2/context.ts`（上下文装配，含 priming 注入）
+   - `main/llm/driver-v2/policy.ts`（策略模型骨架）
+   - `main/llm/driver-v2/context-health.ts`（context-health 决策骨架）
+   - `main/llm/driver-v2/subdialog-txn.ts`（take/commit/rollback 事务）
+   - `main/llm/driver-v2/supdialog-response.ts`（subdialog 回贴与 auto-revive 编排）
+   - `main/llm/driver-v2/round.ts`（单轮生成与 side effects）
+   - 当前状态（2026-02-09 最新）：`orchestrator` 已去除 `emitSayingEvents / supplyResponseToSupdialog / runBackendDriver` 的 v1 passthrough；`round` 已接管 lock/dead-check/upNext/subdialog-reply 收尾流程；核心循环已切换到 `driver-v2/core.ts:driveDialogStreamCoreV2`，不再调用 `_driveDialogStream/driveDialogStreamCoreV1`。
+   - 仍保留的过渡 bridge（2026-02-09）：`coreV2` 已把重试、diligence、参数校验、saying-event 处理迁入 `driver-v2/`（`runtime-utils.ts`、`saying-events.ts`）；当前仅 `tellask` 执行链仍通过 `driver-v2/tellask-bridge.ts -> driver.ts` 过渡调用，属于阶段 1 末尾需继续收敛的技术债。
+2. 保持旧模块文件不动：
+   - `main/llm/driver.ts` 继续存在，作为对照基线。
+3. 切换方式：
+   - 通过单点入口切换到 v2（建议配置开关或固定切换点），避免多处散改 import。
+   - 当前状态（2026-02-09）：`main/llm/driver-entry.ts` 已支持 `DOMINDS_DRIVER_ENGINE=v1|v2`（默认 `v2`）。
+4. Priming 专项支持：
+   - v2 内置 `internalDrivePrimingMsg` 注入规则（每轮注入、drive 内有效、绝不持久化）。
+5. 关键回归与复放：
+   - `multi-iter subdialog response`
+   - `interrupt rollback`
+   - `commit mirror to dlg.msgs`
+   - `no duplicate after restore`
+   - `internal drive priming persists across iterations`
+   - 复放 `39/12/417f4a49` 风格样本
+
+阶段 1 验收门槛：
+
+1. `pnpm -C dominds run lint:types` 通过。
+2. tellask 相关回归通过。
+3. priming 专项回归通过。
+4. 对比旧 driver，关键语义一致且已知 bug 被修复。
+
+### 阶段 2：v2 稳定后删除旧模块并清理
+
+目标：确认 v2 可稳定替代后，删除旧逻辑，收敛维护面。
+
+交付物：
+
+1. 删除旧 `driver.ts` 中被 v2 覆盖的实现（或将其瘦身为转发壳并最终移除）。
+2. 清理迁移期开关、对照代码、过渡注释和 dead code。
+3. 固化最终文档：
+   - 新 driver 模块边界
+   - priming 通道语义
+   - 事务边界与错误处理约束
+
+阶段 2 验收门槛：
+
+1. 全量类型检查与回归通过。
+2. 无旧模块引用残留（import/调用链清零）。
+3. 行为与阶段 1 上线结果一致。
+
+## 8. 目标接口草案（v2，简化版）
+
+```ts
+type DriveV2Input = {
+  persistedPrompt?: HumanPrompt; // 常规用户输入（会持久化）
+  internalDrivePrimingMsg?: ChatMessage; // 仅 drive 内可见
+  skipTaskdoc?: boolean;
+};
+
+type DriveV2Runtime = {
+  takenSubdialogResponses: TakenSubdialogResponse[];
+  generationAttempted: boolean;
+};
+```
+
+说明：
+
+1. priming 只保留 `internalDrivePrimingMsg` 一条路径。
+2. 不提供“下一轮临时注入”接口，避免再次引入语义分叉。
+3. 所有持久化副作用统一在编排层执行，不放进上下文纯函数。
+
+## 9. 重构约束（必须保持）
+
+1. 不改变现有 wire 协议事件名与基础语义（除非显式版本升级）。
+2. 不引入 silent fallback；上下文事务异常需 loud 日志与可见错误信号。
+3. 保持 TypeScript strict 与可静态验证属性；禁止 `any`。
+4. 旧模块在阶段 1 必须原样保留，便于对照和回滚。
+
+## 10. 现有测试合理性评估（针对 dlg drive）
+
+结论（2026-02-09 更新）：**覆盖面已明显提升，足以支撑阶段 1 的持续迁移；但仍有未完成的对照/复放用例，尚未达到“可删除旧模块”的阶段 2 门槛**。
+
+### 10.1 现有测试的合理性（优点）
+
+1. 以脚本方式在临时 rtws 跑通关键链路，具备真实文件系统与持久化路径，能抓到不少“运行态”问题。
+2. 已覆盖部分核心行为：
+   - tellask 解析/流式解析稳定性
+   - root auto-revive 基础路径
+   - type B 注册去重基础路径
+   - diligence push/Q4H 的部分事件行为
+3. 执行成本低，适合快速 smoke。
+
+### 10.2 仍存关键缺口（阶段 2 前需补齐）
+
+1. `v1-v2-parity-diligence-q4h.ts` 仍未实现（当前只有 switch-smoke 级别验证，不是逐断言 parity）。
+2. `replay-39-12-417f4a49-style.ts` 仍未实现（尚未形成稳定复放门禁）。
+3. 旧模块仍保留；v2 已激活入口与外围编排，且核心生成循环已独立到 `coreV2`，但仍存在 bridge 依赖（tellask/重试/diligence 等辅助函数），尚未进入“删除旧模块”收敛阶段。
+
+## 11. v2 测试设计与上线门禁
+
+### 11.1 分层策略
+
+1. L0 单元层（纯逻辑，零 I/O）
+   - 目标：验证 v2 新模块内部规则和数据变换。
+   - 关注：context 装配顺序、priming 注入规则、txn 状态机。
+2. L1 集成层（临时 rtws + mock provider）
+   - 目标：验证 drive 主链路和持久化副作用。
+   - 关注：take/commit/rollback、auto-revive、runState、event 语义。
+3. L2 对照/复放层（v1 vs v2）
+   - 目标：验证重写后与既有正确语义一致，且已知 bug 被修复。
+   - 关注：同输入下关键输出等价、上下文可见性不回退。
+
+### 11.2 v2 必做用例（最小集）
+
+1. `driver-v2/context-assembly-order.ts`
+   - 断言：`base -> ephemeral -> tail` 装配顺序稳定，且 reminders/language guide 插入点与现有语义一致。
+   - v1 状态：可跑；已实现并通过（2026-02-09）。
+2. `driver-v2/internal-drive-priming-multi-iter.ts`
+   - 断言：priming 提示在同一 drive 第 1/2/3 轮均可见。
+   - v1 状态：可跑；已实现并通过（2026-02-09）。
+3. `driver-v2/internal-drive-priming-not-persisted.ts`
+   - 断言：priming 不进入 `dlg.msgs`、不写 events、不落盘。
+   - v1 状态：可跑；已实现并通过（2026-02-09）。
+4. `driver-v2/internal-drive-priming-no-leak-next-drive.ts`
+   - 断言：drive 结束后 priming 不泄漏到下一次 drive。
+   - v1 状态：可跑；已实现并通过（2026-02-09）。
+5. `driver-v2/subdialog-queue-interrupt-rollback.ts`
+   - 断言：take 后 interrupted/error 必 rollback，下一次 drive 可重见。
+   - v1 状态：可跑；已实现并通过（2026-02-09）。
+6. `driver-v2/subdialog-queue-commit-mirror.ts`
+   - 断言：成功 commit 后镜像到 `dlg.msgs`，后续不依赖队列注入。
+   - v1 状态：可跑；已实现并通过（2026-02-09）。
+7. `driver-v2/subdialog-restore-live-equivalence.ts`
+   - 断言：restore 路径与 live 路径对 teammate response 的上下文等价。
+   - v1 状态：可跑；已实现并通过（2026-02-09）。`restoreDialogHierarchy(rootId, status)` 需由调用方显式传入状态。
+8. `driver-v2/multi-iter-tool-round-context-continuity.ts`
+   - 断言：工具回合 continue 后，前序关键上下文不丢失。
+   - v1 状态：可跑；已实现并通过（2026-02-09）。
+9. `driver-v2/v1-v2-parity-basic-tellask.ts`
+   - 断言：同 mock 输入下，v1/v2 在可观察语义上等价（除已知 bug 修复差异）。
+   - v1 状态：可跑；已实现并通过（2026-02-09）。
+10. `driver-v2/v1-v2-parity-diligence-q4h.ts`
+    - 断言：diligence/Q4H 关键事件与 runState 语义一致。
+    - v1 状态：尚未实现专门 parity 用例；但已通过 `driver-v2:switch-smoke:engine-v1|v2` 覆盖该链路的切换可用性验证（2026-02-09）。
+
+11. `driver-v2/replay-39-12-417f4a49-style.ts`
+    - 断言：复放样本不再出现“已收到回贴却声称没看到”的语义回归。
+    - v1 状态：可先做“现状复放”脚本；v2 需要转为门禁回归。当前未实现。
+
+### 11.3 阶段 1/2 的测试门禁
+
+阶段 1（v2 上线前）必须通过：
+
+1. `lint:types`
+2. 全部 L0 用例
+3. 全部 L1 最小集（上面 1~7）
+4. 至少 2 个 L2 对照用例（上面 8~9）
+5. priming 专项 3 条（上面 1~3）全部通过
+
+阶段 2（删除旧模块前）必须通过：
+
+1. 阶段 1 全部门禁
+2. 全部 L2 用例（含复放样本）
+3. old-driver 引用清零后再跑一次全套，确保无隐性依赖
+
+### 11.4 执行组织建议
+
+在 `tests/package.json` 里新增独立脚本分组（阶段 1 即可开始）：
+
+1. `driver-v2:unit`
+2. `driver-v2:integration`
+3. `driver-v2:parity`
+4. `driver-v2:replay`
+5. `driver-v2:gate`（汇总门禁脚本）
+
+目的：把“能跑”与“可上线”分开，避免只凭单条 smoke 测试判断重写完成。
+
+当前已落地脚本（2026-02-09）：
+
+1. `driver-v2:integration:engine-v1`
+2. `driver-v2:integration:engine-v2`
+3. `driver-v2:switch-smoke:engine-v1`
+4. `driver-v2:switch-smoke:engine-v2`
+5. `driver-v2:parity`
+
+### 11.5 测试基座约定（script-rtws + mock provider）
+
+1. 阶段 1 的集成测试默认基于 `tests/script-rtws` 运行，避免污染真实 rtws。
+   - 执行约束：统一通过 `tests/cli.ts` 入口传 `-C script-rtws`；不允许其它 rtws。
+   - 并发约束：同一时刻只允许一个 `tests/cli.ts` 进程使用 `script-rtws`，禁止并发执行多个脚本（会互相污染快照与恢复过程）。
+   - 运行收尾：`tests/cli.ts` 默认会在脚本结束后将 `tests/script-rtws` 恢复到“测试前快照”（可通过 `DOMINDS_TEST_RTWS_RESTORE_MODE=head` 改为恢复到 git HEAD；`DOMINDS_TEST_RTWS_RESTORE=0` 可禁用自动恢复用于调试）。
+2. 默认使用 `apiType: mock`，通过 `mock-db/<model>.yaml` 驱动可重复测试。
+   - driver 入口切换统一走 `main/llm/driver-entry.ts`，通过环境变量 `DOMINDS_DRIVER_ENGINE=v1|v2` 选择引擎；测试代码避免直接调用 `driveDialogStream` 的 v1 直连入口。
+3. mock 响应可使用：
+   - `delayMs`：整次响应前延迟（用于中断/rollback窗口）
+   - `chunkDelayMs`：流式分块延迟（用于流顺序与 stop 时序）
+   - `funcCalls`：响应后追加函数调用序列（用于工具回合/continue 测试）
+   - `contextContains`：要求上下文中必须包含指定片段（用于上下文连续性断言）
+4. 需要“慢速请求”场景时，优先在 mock 数据层配置，不依赖真实外部 provider。

package/dist/docs/keep-going.md

@@ -0,0 +1,176 @@
+# Keep-Going (Diligence Auto-Continue) — Design Doc
+
+## Summary
+
+Dominds root dialogs are intended for long-run operation. A root dialog “stopping” (becoming idle)
+is often not what operators want: they want the agent to keep pushing forward until it either:
+
+- legitimately suspends for a human decision (Q4H), or
+- legitimately suspends waiting for subdialogs (tellask/backfill).
+
+This document specifies a runtime mechanism (“keep-going”) that, for **root/main dialogs only**,
+prevents the dialog from stopping: whenever the driver would otherwise stop, it auto-sends a short
+diligence prompt (rendered as a normal user bubble) and continues generation, except when the dialog
+is legitimately suspended (Q4H or pending subdialogs).
+
+## Goals
+
+- Prevent root dialogs from stopping except for legitimate suspension states (Q4H / subdialogs).
+- Keep behavior predictable and bounded (no infinite loops).
+- Make the nudge text configurable per workspace (rtws) and language.
+- Provide a clear, user-controlled “disable” mechanism.
+
+## Non-goals
+
+- Auto-completing / auto-marking a dialog as done.
+- Applying this behavior to subdialogs (subdialogs remain scoped and should report back to their caller).
+
+## Definitions
+
+- **Root/main dialog**: a `RootDialog` (`dlg.id.rootId === dlg.id.selfId`), the primary conversation thread.
+- **Subdialog**: a `SubDialog`, created for tellask / scoped work.
+- **Q4H**: “Questions for Human”, initiated via `!?@human`, which suspends dialog progression until the human responds.
+
+## Expected “normal” completion path (recommended)
+
+When the agent needs a human decision to conclude (e.g., confirm a choice or decide whether to mark the dialog done), the correct path is:
+
+1. The agent issues a Q4H (`!?@human`) with the necessary context and explicit decision request.
+2. The WebUI surfaces the Q4H clearly.
+3. The human decides and either:
+   - marks the root dialog “done” manually, or
+   - provides the requested info so the dialog can proceed.
+
+This is the “controlled convergence” path. The keep-going mechanism should **not** override legitimate suspension states.
+
+## Keep-going behavior (“auto-continue” fallback)
+
+### Trigger conditions (must all hold)
+
+- Dialog is the **root/main dialog** (never for subdialogs).
+- Dialog is **not suspended**:
+  - no pending Q4H, and
+  - no pending subdialogs (waiting for backfill).
+- The driver would otherwise stop the generation loop (i.e., no tool/function outputs require another iteration).
+
+### Action
+
+The runtime auto-sends a diligence prompt (rendered as a normal user bubble) and runs another
+generation iteration.
+
+### Boundedness
+
+To avoid infinite loops, keep-going has a per-dialog budget (per-member `diligence-push-max`) that controls
+how many auto-continued diligence prompts can be injected for a given dialog before the runtime forces a
+Q4H suspension.
+
+- Default: **3**
+- If `< 1`, keep-going is effectively disabled for that member
+- Configurable per-member via `diligence-push-max` in `.minds/team.yaml`
+
+### Reset on Q4H
+
+When a dialog becomes suspended due to a pending Q4H (Questions for Human), the keep-going injection
+counter is reset. This ensures that after the human answers the Q4H and the dialog is resumed, the
+dialog gets a fresh keep-going budget again.
+
+### Budget exhausted → force Q4H
+
+When the keep-going budget is exhausted, the runtime creates a Q4H entry that asks the human whether
+to continue or stop. This converts “boundedness” into a legitimate suspension point and avoids
+infinite auto-continue loops.
+
+### Disable switch
+
+Keep-going can be disabled per-rtws in either of these ways:
+
+- If the selected diligence file exists but its content is empty/whitespace, keep-going is disabled (no injection).
+
+Keep-going can be disabled per-member in either of these ways:
+
+- If `diligence-push-max < 1`, keep-going is disabled for that member (no injection).
+
+## Diligence prompt resolution
+
+Let `<rtws>` be the current runtime workspace (i.e., `process.cwd()`).
+
+Resolution order:
+
+1. `<rtws>/.minds/diligence.<work-lang-id>.md` (e.g., `diligence.zh.md`)
+2. `<rtws>/.minds/diligence.md` (language-agnostic fallback)
+3. Built-in fallback text (hardcoded i18n; `zh` is canonical and embedded in source)
+
+If the first existing file in the above order has empty/whitespace content, **disable** keep-going.
+
+Note: YAML frontmatter in diligence files is **ignored** by the runtime. If present, it is treated as
+non-content metadata and stripped from the prompt body.
+
+### Team member cap: `diligence-push-max`
+
+Each team member can optionally cap keep-going via `.minds/team.yaml`:
+
+```yaml
+members:
+  alice:
+    diligence-push-max: 10
+```
+
+Rules:
+
+- If missing, `diligence-push-max` defaults to **3** for that member.
+- If `diligence-push-max < 1`, keep-going is disabled for that member (no injection), even if the diligence file exists.
+- Built-in shadow members `fuxi` and `pangu` default to `diligence-push-max: 0` unless explicitly overridden in team.yaml.
+
+## UX notes
+
+- Keep-going is a runtime-only nudge, but it should be **visible**: the diligence prompt is rendered
+  as a normal user message bubble (auto-sent by the runtime) so operators can understand why an
+  extra iteration occurred.
+- Users should observe that the agent continues with a brief follow-up after tool-only operations.
+- When the agent truly needs user intervention, it should use Q4H. Keep-going should not try to “fake” completion.
+
+## Implementation (backend)
+
+### Where
+
+Implemented in the LLM driver loop (`dominds/main/llm/driver.ts`) as a small post-iteration check:
+
+1. If `suspendForHuman` is true, stop (Q4H / subdialog pending).
+2. If there is any tool feedback, continue normally.
+3. Otherwise (root only), attempt keep-going auto-continue:
+   - If disabled → stop normally.
+   - If budget exhausted → create Q4H and stop.
+   - Else → auto-send diligence prompt and continue.
+
+### Message type
+
+We inject the diligence prompt as an auto-sent user message:
+
+- `ChatMessage` of type `prompting_msg` with `role: 'user'`
+
+This ensures:
+
+- It is present in the model context
+- It is persisted as a human message record
+- It renders in the chat timeline as a normal user bubble (like any other user message)
+
+## Observability
+
+Recommended follow-ups (not required for initial implementation):
+
+- Add a structured log line when keep-going is triggered, including:
+  - dialog id
+  - language
+  - which diligence source was used (lang-specific / generic / built-in / disabled)
+- Optional metrics counter for “keep-going triggered” and “keep-going disabled by empty file”.
+
+## Testing
+
+Regression tests should cover:
+
+- Root dialog: tool-only output → diligence injection → continued response
+- Root dialog: empty assistant output → diligence injection → continued response
+- Subdialog: no diligence injection
+- Workspace config:
+  - `.minds/diligence.md` is honored when lang-specific file is absent
+  - empty diligence file disables keep-going

package/dist/docs/keep-going.zh.md

@@ -0,0 +1,162 @@
+# Keep-Going（鞭策）— 设计文档
+
+## 概述
+
+Dominds 根对话旨在长期运行。根对话"停止"（变为空闲）通常不是操作员想要的：他们希望智能体持续推进，直到：
+
+- 合法地暂停等待人类决策（Q4H），或
+- 合法地暂停等待子对话（tellask/backfill）。
+
+本文档指定了一个运行时机制（"keep-going"），仅针对**根/主对话**，防止对话停止：每当驱动程序即将停止时，它会自动发送一个简短的鞭策语（渲染为正常的用户气泡）并继续生成，除非对话处于合法暂停状态（Q4H 或待处理的子对话）。
+
+## 目标
+
+- 防止根对话停止，除非处于合法暂停状态（Q4H / 子对话）。
+- 保持行为可预测和有界（无无限循环）。
+- 使鞭策语文本可按工作区（rtws）和语言配置。
+- 提供清晰的用户控制的"禁用"机制。
+
+## 非目标
+
+- 自动完成/自动将对话标记为完成。
+- 将此行为应用于子对话（子对话保持范围，应向其调用者报告）。
+
+## 定义
+
+- **根/主对话**：`RootDialog`（`dlg.id.rootId === dlg.id.selfId`），主要对话线程。
+- **子对话**：`SubDialog`，为 tellask / 作用域工作创建。
+- **Q4H**："Questions for Human"，通过 `!?@human` 发起，暂停对话进度直到人类响应。
+
+## 预期的"正常"完成路径（推荐）
+
+当智能体需要人类决策来结束时（例如，确认选择或决定是否将对话标记为完成），正确的路径是：
+
+1. 智能体发出 Q4H（`!?@human`）并提供必要的上下文和明确的决策请求。
+2. WebUI 清楚地呈现 Q4H。
+3. 人类决定并：
+   - 手动将根对话标记为"完成"，或
+   - 提供请求的信息以便对话继续。
+
+这是"受控收敛"路径。keep-going 机制不应覆盖合法的暂停状态。
+
+## Keep-Going 行为（"自动继续"回退）
+
+### 触发条件（必须全部满足）
+
+- 对话是**根/主对话**（绝不会是子对话）。
+- 对话**未暂停**：
+  - 没有待处理的 Q4H，并且
+  - 没有待处理的子对话（等待回填）。
+- 驱动程序即将停止生成循环（即没有工具/函数输出需要另一次迭代）。
+
+### 操作
+
+运行时自动发送一个鞭策语（渲染为正常的用户气泡）并运行另一次生成迭代。
+
+### 有界性
+
+为避免无限循环，keep-going 有一个按对话的预算（每个成员的 `diligence-push-max`），控制对于给定对话在运行时强制 Q4H 暂停之前可以注入多少个自动继续的鞭策语。
+
+- 默认值：**3**
+- 如果 `< 1`，则该成员的 keep-going 有效禁用
+- 可通过 `.minds/team.yaml` 中的 `diligence-push-max` 按成员配置
+
+### Q4H 时重置
+
+当对话因待处理的 Q4H（Questions for Human）而暂停时，keep-going 注入计数器会被重置。这确保在人类回答 Q4H 并恢复对话后，对话会获得新的 keep-going 预算。
+
+### 预算耗尽 → 强制 Q4H
+
+当 keep-going 预算耗尽时，运行时会创建一个 Q4H 条目，询问人类是否继续或停止。这将"有界性"转换为合法的暂停点，并避免无限自动继续循环。
+
+### 禁用开关
+
+可以通过以下任一方式按 rtws 禁用 keep-going：
+
+- 如果选中的鞭策语文件存在但其内容为空/仅空白，则禁用 keep-going（不注入）。
+
+可以通过以下任一方式按成员禁用 keep-going：
+
+- 如果 `diligence-push-max < 1`，则该成员的 keep-going 被禁用（不注入）。
+
+## 鞭策语解析
+
+让 `<rtws>` 为当前运行时工作区（即 `process.cwd()`）。
+
+解析顺序：
+
+1. `<rtws>/.minds/diligence.<work-lang-id>.md`（例如，`diligence.zh.md`）
+2. `<rtws>/.minds/diligence.md`（语言无关的回退）
+3. 内置回退文本（硬编码的 i18n；`zh` 是规范的并嵌入在源代码中）
+
+如果上述顺序中第一个存在的文件具有空/空白内容，则**禁用** keep-going。
+
+注意：鞭策语文件中的 YAML frontmatter 会被运行时忽略。如果存在，它被视为非内容元数据并从提示正文中剥离。
+
+### 团队成员上限：`diligence-push-max`
+
+每个团队成员可以选择通过 `.minds/team.yaml` 限制 keep-going：
+
+```yaml
+members:
+  alice:
+    diligence-push-max: 10
+```
+
+规则：
+
+- 如果缺失，`diligence-push-max` 对于该成员默认为 **3**。
+- 如果 `diligence-push-max < 1`，则该成员的 keep-going 被禁用（不注入），即使鞭策语文件存在。
+- 内置影子成员 `fuxi` 和 `pangu` 默认为 `diligence-push-max: 0`，除非在 team.yaml 中显式覆盖。
+
+## UX 备注
+
+- Keep-going 是一个仅运行时的提示，但它应该是**可见的**：鞭策语渲染为正常的用户消息气泡（由运行时自动发送），以便操作员理解为什么会出现额外的迭代。
+- 用户应该观察到智能体在仅工具操作后继续简短的跟进。
+- 当智能体真正需要用户干预时，它应该使用 Q4H。Keep-going 不应试图"假装"完成。
+
+## 实现（后端）
+
+### 位置
+
+在 LLM 驱动程序循环中实现（`dominds/main/llm/driver.ts`），作为迭代后的小检查：
+
+1. 如果 `suspendForHuman` 为 true，则停止（Q4H / 子对话待处理）。
+2. 如果有任何工具反馈，则正常继续。
+3. 否则（仅限根），尝试 keep-going 自动继续：
+   - 如果禁用 → 正常停止。
+   - 如果预算耗尽 → 创建 Q4H 并停止。
+   - 否则 → 自动发送鞭策语并继续。
+
+### 消息类型
+
+我们将鞭策语作为自动发送的用户消息注入：
+
+- 类型为 `prompting_msg`、角色为 `'user'` 的 `ChatMessage`
+
+这确保了：
+
+- 它存在于模型上下文中
+- 它作为人类消息记录持久化
+- 它在聊天时间线中渲染为正常的用户气泡（像任何其他用户消息一样）
+
+## 可观察性
+
+建议的后续步骤（初始实现不需要）：
+
+- 当触发 keep-going 时添加结构化日志行，包括：
+  - 对话 id
+  - 语言
+  - 使用的鞭策语来源（语言特定/通用/内置/禁用）
+- 为"keep-going 触发"和"keep-going 因空文件禁用"添加可选的指标计数器。
+
+## 测试
+
+回归测试应覆盖：
+
+- 根对话：仅工具输出 → 鞭策语注入 → 继续响应
+- 根对话：空助手输出 → 鞭策语注入 → 继续响应
+- 子对话：无鞭策语注入
+- 工作区配置：
+  - 当语言特定文件缺失时，`.minds/diligence.md` 被遵守
+  - 空的鞭策语文件禁用 keep-going