# 把待办交给 Superagent

> 面向：想用 [dsh-superagent](https://github.com/deepseek-ai/dsh-superagent-prototype)
> 自动处理待办的人。本文只描述**契约**，不描述那一侧的实现。

Superagent 是一个独立进程：它轮询待办清单，把「人打了授权标签」的记录当成工作请求，
派给一个 worker 去做，做完把进展写回同一个清单。两边只通过 HTTP 和这份契约相连。

## 一句话契约

**人打标签发起，agent 写 note 交回，人点完成收尾。**

三步都不由 agent 代劳。

## 清单这一侧保证什么

| 保证 | 依据 |
|---|---|
| 只有带授权标签的记录会被读成请求 | 由 Superagent 的 Source 判定（它自己配置标签名，例如 `auto:3`） |
| 记录必须有人类作者 | `createdBy !== 'agent'` 或 `updatedBy === 'human'` |
| 在收件箱里的记录不构成请求 | `inboxReason` 非空时不派 |
| 没有来源目录的记录不构成请求 | `originDir` 为空时不派——worker 需要知道在哪个目录开工 |
| 有存活会话的记录不重复派 | `sessionAlive` 为真时跳过 |

最后两条是这个插件的字段语义，不是 Superagent 的发明：一条待办是「在某个目录里做的一件事」，
不知道目录就没法开始；已经有人在跑的事不该再派一次。

## 写回：note 的归属

`POST /api/global-todo/note` 接受 `by: 'human' | 'agent'`（缺省 `human`，因为面板不带这个字段）。
**agent 的 note 记在 agent 名下**，面板上能看到是谁写的。这条曾经写死成 `human`——
那等于让 agent 冒充人说话，也是审计上最不该含糊的一处。

## 关键语义：一次回复会关掉再触发

写 note 会同时更新记录的 `updatedAt` 和 `updatedBy`。因此：

1. `updatedBy` 变成 `agent` → 这条记录不再满足「人发起的请求」，下一轮轮询**不会**再派一次；
2. `updatedAt` 变了 → 即使标签还在，它的触发标识（由 `updatedAt` 参与计算）也换了。

这不是副作用，是**防自我触发的闸门**：没有它，worker 写完 note 就等于给自己发了新请求，
形成无限循环。所以：

> **同一条待办要再跑一次，必须由人再碰它一下**（改标题、加 note、改标签都行）。
> agent 自己的回复永远不能给自己续命。

## 完成仍然由人

`/status` 支持 `by: 'agent'`，但**不要**让 Superagent 调它标 `done`。
这个清单的规矩是「完成是一个人的判断」；worker 能做的是写清做了什么、验证了什么、卡在哪，
由人在面板上确认。Superagent 的 reply 通道也只写 note，不碰状态。

## 推荐配置

```
标签        auto:3        # 一档：只读核对 / 文档 / 本机小修
日上限      10            # 一上来就给 20 会让一天堆十几条 note，人也看不完
来源目录     必填          # 在哪个仓库/目录里做，worker 从这里开工
完成        人点           # agent 不调 /status done
回复        写 note        # 面板可见、可追溯
```

分档建议（与标签一一对应）：

| 档位 | 允许做的事 |
|---|---|
| 只读 | 调查、核对、给结论 |
| 本机小修 | 改来源目录里的文本/配置，能一眼 diff |
| 其他 | 生产变更、凭据、删除、对外发送——**不打标签**，只出方案 |

## 一轮典型流程

```text
人：给待办加 auto:3（并确认 originDir 非空）
 ↓
Superagent：轮询读到 → 策略评估 → 建工单 → worker 在 originDir 里干活
 ↓
worker：POST /note { by: 'agent', text: '做了什么 / 改了什么 / 验证结果 / 没做完的部分' }
 ↓
人：面板上看 note → 满意就点完成；不满意就再改一次待办，让它重跑
```

## 实测记录

2026-11-04 用这套契约跑过一轮：32 条 `auto:3`、35 个工单、15 小时。
可外部核实的抽样结论 7 条里 6 条完全准确、1 条编号写错；
真正的教训是**note 的自述不能当作完成证据**——必须查它声称产出的文件。
把「独立复核」当成这套流程的一环，而不是可选项。

## 不要做的事

- 不要让 agent 调 `POST /status` 把记录标成 done（那会让「完成」失去意义）。
- 不要给「删除 / 生产变更 / 凭据 / 对外发送」类记录打标签。
- 不要指望它自己重试：一次回复就关掉了再触发，重跑要人碰。
- 不要只读 note 就相信它干完了（见上）。