# control 使用场景

## 模板（场景）

### 场景格式

- 目标
- 前置条件
- 步骤
- 期望信号
- 失败分支处理
- 完成判据

## 场景 1：提醒项手头工作跟踪

### 场景描述

使用 reminders 承接当前任务的手头工作：下一步、临时阻塞、易丢细节，而不是把它写成面向全队同步的 Taskdoc 公告牌。准备 `clear_mind` 的接续包是当前对话恢复线索，必须显式 `scope=dialog` 并写明本路对话任务目标。

### 示例

```typescript
// 默认添加 task 范围提醒：同一差遣牒任务换新对话继续时仍可见
add_reminder({
  content: '下一步：复核 control 手册是否已经完整表达 Taskdoc progress 的公告牌语义',
});

// 只有真正只对当前对话局部有效，才显式写成 dialog
add_reminder({
  content: '本对话里临时对照一下刚才那段 tool output 的第 12 行',
  scope: 'dialog',
});

// clear_mind 接续包必须显式 dialog，并写明当前这一路对话的任务目标
add_reminder({
  content:
    '接续目标：继续复核 control 手册换程引导；下一步先检查 scenarios/index 是否还把接续包暗示成 task',
  scope: 'dialog',
});

// 只有紧急、短期、全局刺眼提醒，才写成 agent
add_reminder({
  content: '紧急：在删除任何外部资源前必须先向用户确认授权',
  scope: 'agent',
});

// 当手头工作细节变化后更新
update_reminder({
  reminder_id: 'abc123de',
  content: '阻塞已解除：control 手册文案已与 Taskdoc progress 语义对齐',
});

// 删除已完成的提醒
delete_reminder({
  reminder_id: 'abc123de',
});
```

### 关键点

- 同一差遣牒任务内的普通下一步、临时阻塞、手头细节默认用 `task`
- 真正只对当前对话有效的提醒才用 `dialog`；准备 `clear_mind` 的接续包必须显式 `scope=dialog`，并写明本路对话任务目标
- 只有紧急、短期、全局刺眼提醒才用 `agent`
- 如果信息需要向全队同步当前有效状态、关键决策、下一步或仍成立阻塞，应写入 Taskdoc `progress`
- 如果内容本质上是长期知识而不是当前手头工作提示，应改存到 `personal_memory`

## 场景 2：支线已完成，按任务开头要求调用 replyTellask

### 场景描述

当前支线处理完毕，任务开头明确写着“完成任务时必须调用 `replyTellask`”。

### 示例

```typescript
replyTellask({
  replyContent: '已核对实现与约束，结论：当前方案可接受，剩余风险为测试覆盖不足。',
});
```

### 关键点

- 不要再发一条普通最终消息代替；正式回贴必须走 Dominds 点名的回复工具，否则对方可能收不到正式回贴
- `replyContent` 直接放最终交付正文
- 若任务开头写的是 `replyTellaskSessionless`，则同结构替换函数名

## 场景 3：当前未完成，需要回问诉请者

### 场景描述

当前支线仍未完成，因此需要向诉请者补问缺失信息。

### 示例

```typescript
tellaskBack({
  tellaskContent: '还缺少生产环境端口与部署入口信息。请补充这两项后我再继续给出最终方案。',
});

// 等诉请者补充后，Dominds 会在当前对话里继续推进
```

### 关键点

- 这里只是“必须向诉请者补输入”的例子，所以用 `tellaskBack`
- 若团队规程 / SOP / 职责卡已经能明确执行负责人，应直接 `tellask` / `tellaskSessionless` 对应负责人，而不是机械因为“未完成态”就用 `tellaskBack`
- `tellaskBack` 只负责把问题问回去，不负责最终交付；中间澄清不要调用回复工具

## 场景 4：收到 ask-back 续诉请后，用 replyTellaskBack 收口

### 场景描述

你之前发过 `tellaskBack`，诉请者现在补回了所需信息，Dominds 显示了 `replyTellaskBack`。

### 示例

```typescript
replyTellaskBack({
  replyContent: '已基于你补充的生产端口与入口信息完成检查；结论：发布脚本只需补一条端口注入配置。',
});
```

### 关键点

- 看到 `replyTellaskBack` 被暴露时，说明当前语义是“回复上一条 ask-back”
- 这时不要误用 `replyTellask` / `replyTellaskSessionless`

## 场景 5：差遣牒进度更新

### 场景描述

把当前有效状态、关键决策、下一步与仍成立阻塞公告给全队，而不是写个人流水账。若细节已整理到 rtws 正式文档，`progress` 只写摘要和文档定位 pointer。

### 示例

```typescript
// 少量新增当前仍有效的公告条目
mind_more({
  items: ['- 下一步：复核 control / team_mgmt 手册与测试是否对齐（详见 <文档路径>#<章节>）'],
});

// 需要清理旧项、重排、同主题合并或压缩流水账时，整章替换
recall_taskdoc({
  selector: 'progress',
});

change_mind({
  selector: 'progress',
  content:
    '## Progress\n\n### 当前有效状态\n- 已完成三类记忆载体边界收口，准备补 Taskdoc 公告牌属性；细节见 <文档路径>#<章节>\n\n### 已生效决策\n- `personal_memory` 不再作为短期杂物柜\n- `team_memory` 只承接团队长期共识与不变量\n\n### 下一步\n- 在 control / team_mgmt 手册中补强 `progress` 的公告牌语义\n\n### 仍成立阻塞\n- 无',
  previous_content_hash: 'crc32:...',
});
```

## 场景 6：差遣牒目标更新

### 场景描述

更新任务目标。

### 示例

```typescript
recall_taskdoc({
  selector: 'goals',
});

change_mind({
  selector: 'goals',
  content:
    '## Goals\n\n- [ ] 创建所有工具集手册\n  - [x] ws_mod\n  - [x] team_mgmt\n  - [x] personal_memory\n  - [ ] control (进行中)\n- [ ] 编写工具描述',
  previous_content_hash: 'crc32:...',
});
```

## 场景 7：差遣牒约束更新

### 场景描述

更新任务约束条件。

### 示例

```typescript
recall_taskdoc({
  selector: 'constraints',
});

change_mind({
  selector: 'constraints',
  content:
    '## Constraints\n\n- man 函数必须根据 team.yaml 动态过滤工具集\n- 运行时生效：team.yaml 配置变更后立即可见\n- 工具集名称使用下划线格式\n- 新增约束：每个工具集需要 5 个 topic × 2 个语言',
  previous_content_hash: 'crc32:...',
});
```

## 场景 8：读取差遣牒

### 场景描述

读取差遣牒章节内容。

### 示例

```typescript
// 顶层章节正文会自动注入，但 content_hash 由 recall_taskdoc 返回
recall_taskdoc({
  selector: 'progress',
});

// 读取 bearinmind/runbook
recall_taskdoc({
  category: 'bearinmind',
  selector: 'runbook',
});

// 读取 bearinmind/contracts
recall_taskdoc({
  category: 'bearinmind',
  selector: 'contracts',
});
```

## 场景 9：差遣牒维护

### 场景描述

维护差遣牒的完整性和一致性，并确保 `progress` 始终是可供全队扫读的当前真相快照；细节展开放入 rtws 正式文档，差遣牒只保留摘要和定位 pointer。

### 示例

```typescript
// 更新 progress（保持 goals / constraints / progress 一致）
recall_taskdoc({
  selector: 'progress',
});

change_mind({
  selector: 'progress',
  content:
    '## Progress\n\n### 当前有效状态\n- 边界口径已统一到手册源头与测试；细节见 <文档路径>#<章节>\n\n### 已生效决策\n- 角色级资产 / personal_memory / team_memory / Taskdoc-progress / reminders 的职责已经切开\n\n### 下一步\n- 复验 control 手册、Taskdoc 展示文案与边界测试\n\n### 仍成立阻塞\n- 无',
  previous_content_hash: 'crc32:...',
});
```
