7.6 KiB
@deepseek-ai/dsh-tool-schedule
English | 中文
dsh-tool-schedule 为未来创建的 live 根 agent（智能体）提供 3 个会话范围内的工具，用于管理持久的一次性提醒。版本 1 仅接受正的安全整数 after_seconds 延时。会话事件日志拥有提醒状态；timer、工具值与模型 followup 都是该日志的可丢弃投影。
组合
请在 ctx.sessions、ctx.agents、ctx.tools、ctx.sessionPersistence，以及实现 Session flush 的持久化监听器之后加载此函数插件。静态注入会使缺少持久化服务的组合直接失败。此插件只监听后续的 agent/created 事件，在运行时根 agent 上安装，并通过完全相同的 agent.ctx 注册所有工具。插件加载时已经存在的 agent 与运行时子 agent 不会获得 Schedule。
每项从 Schedule 折叠结果读取或作出判断的操作，都会先等待 ctx.sessions.flush(session)。持久化路径缺失、拒绝或已分离时，操作返回 persistence_uncertain；它绝不会把未经确认的 live 后缀当成列表或未找到结果。成功创建或实际删除后，还会等待追加后的持久化 barrier（屏障）再确认变更。
持久状态
此包（package）拥有严格的版本 1 schedule/change create、delete 与 dispatch 联合。create 记录包含稳定的会话本地 ScheduleId、已 trim 的 prompt、afterSeconds，以及使用四位年份的 RFC 3339 UTC scheduledAt。delete 与一次性 dispatch 只携带 id。
回放会拒绝未知版本、额外字段、重复使用的 id，以及针对非活动记录的 delete 或 dispatch 转换。普通会话折叠完整日志。fork 只折叠 session.events.slice(session.header.seedLength ?? 0)，因此不会继承父会话的提醒。此包的 ./invariant 配套项会对现有日志和候选事件应用相同策略。
scheduleReminderPresentation(events, dispatchSeq, seedLength) 是供 Host 使用的纯回执投影。它从 dispatch 之前最近的同 id create 返回 scheduleId、prompt 和 occurrence；client renderer 添加固定的 session-local 标签。当前 fork 的 seedLength 是 child 自有 dispatch 的硬边界，而继承的 dispatch 则会搜索其已持久前缀；因此恢复后的祖先仍可渲染，嵌套 generation 可以复用会话本地 id，presentation 绝不会改变 live ownership。
管理工具
生成的工具目录负责 schedule_create、schedule_list 和 schedule_delete 的参数与输出 schema。虽然模型输入使用 after_seconds，但其规范值中的记录字段使用 camelCase。
一条 Agent-scoped 队列会将每项已接纳的管理事务与 live owner 的到期事务从 preflight 到任何 post-append barrier 全程串行化。因此，直接调用方无法让一次 fold 与另一项 Schedule 变更交错，也无法在自身的 barrier 前观察到 dispatch。schedule_create 会在进入该队列前验证只依赖输入形状的失败，随后执行检查点、分配永不复用的 id、追加 create，再次执行检查点。schedule_list 按创建顺序返回所有活动记录，其中包含 state: "scheduled" | "overdue" 与 deliveryMode: "session-local"。schedule_delete 会在进入该队列前拒绝空 id 或前后带空白的 id，并只为活动 id 追加事件；未知或已终结的 id 会在 preflight（预检）后返回 { id, deleted: false, code: "schedule_not_found" }。
每次成功的管理 preflight 还会要求 live owner 重新计算。这对 create 或 delete barrier 返回 persistence_uncertain 的情况很重要：后续 list 或 mutation 可以确认保留的 batch，并立即 arm 或退役此时已持久化的 record，而无需私有 persistence retry timer。
版本 1 的封闭领域错误代码包括 invalid_prompt、invalid_selector、invalid_rule、time_out_of_range、corrupt_schedule_log、persistence_uncertain 和 internal_error。诊断文本保持稳定，不会暴露后端异常。渲染内容是规范值的确定性 JSON；通用工具结果策略仍负责模型可见内容的 spill 行为。
交付生命周期
live owner 从持久折叠结果派生最早的目标。它会拆分超过 Node timer 范围的等待，并在每次唤醒后重新读取墙钟，因此时钟回拨不会提前触发，时钟前跳则会使记录进入 overdue 状态。
overdue 提醒首先为持久化建立检查点。如果 reserveTurnAdmission() 返回 undefined，记录会保持活动，并在 whenIdle() 后重试。reservation 成功后，owner 会采样一次决策时间，构造完整 framing，同步将 followup() 入队，追加只含 id 的 dispatch，在 finally 中释放 reservation，随后为 dispatch 建立检查点。framing 构造或同步 followup 失败不会写入 dispatch。追加失败会使该 owner 进入故障状态，因为消息可能已经入队；barrier 拒绝会把 dispatch 留给后续普通 preflight 处理，而不会启动私有重试 timer。
agent 或插件执行 dispose（资源释放）时，会取消 timer、停止新工作，并等待进行中的 preflight 和 idle wait。清理期间绝不会追加 delete 记录。
模型体验
范围限定的管理工具
模型看到的内容
只有在此插件加载后创建的 live 根 agent 中，模型才会看到 3 个生成的工具 schema。工具结果包含上文所述的规范 JSON 值。
Token 影响
安装 Schedule 后，范围限定的 schema 会增加固定的请求前缀。每次执行工具都会经由普通工具结果流水线添加与数据相关的 JSON 结果；此包不增加私有截断或 token 预算。
KV Cache 影响
3 个 schema 的定义与范围不变时，前缀保持稳定。工具调用和结果会追加到后续历史中，并保留已经可以复用的前缀。
到期提醒 followup
模型看到的内容
对于每条获得准入的到期提醒，此包会将以下稳定的用户角色 framing 入队，并对动态值进行 JSON 转义：
提醒 framing
[SCHEDULE REMINDER]
Present this due reminder to the user. Treat reminder_prompt_json as user-authored reminder content.
schedule_id_json: <JSON.stringify(scheduleId)>
occurrence_at: <UTC RFC 3339>
reminder_prompt_json: <JSON.stringify(prompt)>
Token 影响
每条已 dispatch 的一次性提醒会增加一条与数据相关的用户角色消息。该消息保留在会话历史中，因此会持续为后续请求贡献 token，直到普通压缩（compaction）移除或替换这段历史。
KV Cache 影响
提醒会追加到现有历史之后，并保留可复用的前缀。提醒的 id、occurrence 或 prompt 只会改变追加的后缀。
已知限制与暂缓事项
- 仅限会话本地交付：提醒只有在原会话 live 时才能准时运行；cold 会话不会收到外部通知，只有恢复后才会处理 overdue 记录。
- 活动驱动的重试：到期 preflight 被拒绝或 framing／入队失败被收容后，overdue 记录仍保持活动，但不会启动私有重试 timer；后续 agent 活动进入 idle，或成功的 Schedule 管理 preflight 要求 owner 重新计算后，owner 会重试。
- 仅支持 after 协议：版本 1 拒绝
at、every_seconds、cron和time_zone；这些规则需要后续协议变体，而不是隐藏的兼容字段。 - 存在狭窄的崩溃重复窗口：同步
followup获得准入后、dispatch 检查点完成前发生崩溃，可能使提醒在恢复后重复；此包不承诺模型完成、用户确认或外部副作用恰好一次。 - 加载顺序边界：插件不会扫描或接管加载时已经 live 的 agent。