DeepSeek Harness 显式 Schedule 时区边界从请求本地 provenance 到绝对 UTC 时刻的架构实践【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness本篇文章围绕 DeepSeek Harness 中dsh-schedule与dsh-time-context两个包的设计决策展开解读浏览器时区只属于请求本地 provenance、Schedule 只接受显式时区这条边界如何落地Web client 如何为每条提示词采样浏览器时区、Host 如何在 RPC 边界校验并规范化、time-context 如何派生唯一/混合/缺失三种模型策略、以及at调度器如何在不依赖任何隐式上下文的前提下完成严格的日历校验与确定性 UTC 归一化。读完本文你将掌握该仓库在自然语言时间解释与工具级绝对时间之间划出的工程边界并能从源码与测试层面理解每条规则的可验证依据。背景为什么隐式本地时区是危险的在会话式 AI 工具中提醒我下午三点开会这类自然语言天然带有时间含义但其语义依赖听者所处的时区。DeepSeek Harness 的原 Agent Note实现记录指出如果把隐式本地at输入当作共享产品状态浏览器事实就会被固化进会话。若在 Session 创建时捕获默认时区将连锁引入新的 Session header、createresumefork 冲突规则、JSONL metadata、SQLite migration、client 创建 plumbing、Host 比较以及与 time-context 标记耦合的 Schedule 逻辑旅行场景、并发 tab、缺失 provenance 和旧 Session 都需要一套确认协议仅仅为了判断省略字段是否安全。更关键的是大部分复杂度都位于 Schedule 之外模型在调用工具前已经解释自然语言因此持久化 Session 默认值只是重复了一个假设并没有强化绝对时间边界。决策总览两条各司其职的边界最终决策可以概括为三句话浏览器时区是请求本地的 provenance只在模型解释自然语言时起作用Schedule 不接受任何隐式本地时区at必须携带显式偏移或显式time_zone浏览器假设只会通过模型的显式工具参数跨入 Schedule不存在任何隐式注入路径。这一设计同时砍掉了整组待实现子系统不再保留 Session 时区字段、createresumefork 时区冲突、JSONL header 字段、SQLite column 或 migration、连接默认值也不再保留 Schedule 专属的 Hostclient 呈现。官方 Schedule 用户指南 用一句话给出了该边界的权威表述schedule_create.at必须是带Z或数值偏移的严格 RFC 3339 日期时间或者{ date, time, time_zone }形式的显式时区对象Schedule 不保留也不推断 Session 默认时区。第一道边界Web client 采样与 Host 校验请求本地 provenance每条提示词采样一次浏览器时区Web client 会为每条提示词采样Intl.DateTimeFormat().resolvedOptions().timeZone把浏览器事实绑定在确切的那条user-rpc消息上而不是绑定到 Session。其源码形态可见于 request-zone.ts 中的browserTimeZone()只有当消息source.kind user、携带字符串rpcId且存在字符串clientTimeZone时才把它视作浏览器时区来源。Host 在 RPC 边界校验并规范化Host 接受可选的clientTimeZone在 RPC 边界完成两件事格式校验只接受UTC或 IANAArea/Location形式的名称如Asia/Shanghai、America/New_York拒绝CST、PST、GMT、08:00这类缩写或数值偏移规范化通过Intl.DateTimeFormat(en-US, { timeZone: value }).resolvedOptions().timeZone把别名收敛为规范名例如US/Eastern→America/New_York并要求返回结果与输入一致否则拒绝。request-zone.spec.ts中的测试测试用例专门验证了08:00会被拒绝、不存在的 IANA 名会报 browser time zone is unsupported、Etc/UTC这种非规范别名会被判 must be canonical。无效值会使提示词准入被拒绝非浏览器 client如 SDK 或 CLI可以省略clientTimeZone不构成错误。第二道边界time-context 只做解释指令不做权威dsh-time-context插件包说明从 open turn 中原始user-rpc消息派生三类浏览器事实定义在 request-zone.ts情形类型模型得到的指令turn 内所有 user-rpc 消息时区唯一resolvedBrowser time zone for this request:zone。把未限定时间的日期和时间解释为该时区。turn 内出现多个不同时区mixed列出排序去重后的时区集合并指示询问用户澄清没有任何 user-rpc 时区missing指示询问用户澄清派生的核心实现在deriveBrowserTimeZoneContext()派生逻辑它只收集携带clientTimeZone的 user-rpc 消息做排序去重后判定唯一/混合/缺失插件注入的消息source.kind plugin不携带浏览器时区天然归入missing。对应的三条模型策略文本由renderBrowserTimeZoneContext()策略渲染生成。配置或进程时区只做显示 fallback当 provenance 混合或缺失时时间戳的显示使用插件配置的timeZone默认取 Node 进程时区但模型策略文本仍然明确指示询问用户。这就是显示 fallback 绝不是用户权威的含义——timeZone配置项只影响时钟的格式化展示不参与任何工具参数的隐式填充。配置示例如下- name: deepseek-ai/dsh-time-context config: timeZone: Asia/Shanghai字段默认值含义timeZone进程时区open turn 无唯一浏览器时区时的显示 fallbackrefreshIntervalMs0每个符合条件步骤注入一次同一会话内两次持久注入的最小毫秒间隔减少注入频率第三道边界Schedule 的显式绝对时间契约拒绝一切隐式上下文Schedule 包包说明的设计哲学是Session log 拥有状态重放严格持久化先于决策仅会话本地投递其中时区边界被明确写死at要么是带显式偏移量且严格符合 RFC 3339 的字符串要么是精确的{ date, time, time_zone }对象。即便 time-context 刚向模型展示了浏览器时区结构化形式仍要求自己的时区。Schedule 不导入 time-context、不检查 user message provenance、不读取 Session header、不产生确认错误——四条不做在源码层面得到印证dsh-schedule的依赖中不含 time-context其工具执行路径tools.ts只消费模型显式传入的参数。schedule_create的at参数形态从工具定义工具注册可以看到at的精确 JSON Schemaat: - 字符串严格偏移 RFC 3339 日期时间 - 对象{ date: string (必填), time: string (必填), time_zone: string (必填) } additionalProperties: false不接受额外字段也就是说模型在调用工具前已经解释完自然语言它必须自己把下午三点翻译成带偏移的字符串或带时区的对象——工具层面不替它做任何翻译也不允许它省略时区字段。严格解析与确定性归一化domain.ts[domain.ts](https://link.gitcode.com/i/56d31834ec3da91c3ac311979782df05)是时区边界的核心实现其中每个校验规则都能在domain.spec.ts测试用例找到对应断言严格偏移字符串parseOffsetInstant解析实现格式必须是YYYY-MM-DDTHH:mm:ss可带 13 位小数秒结尾必须是Z或±HH:MM数值偏移拒绝无偏移的本地时间如2026-08-06T01:00:00、空格分隔、24:00:00、秒数 60、4 位以上小数秒、-00:00以及非法偏移如24:00、01:60偏移量参与计算后统一换算成 UTC 时刻。测试示例2026-08-06T09:00:0008:00→2026-08-06T01:00:00.000Z2026-08-05T20:30:00-05:30→2026-08-06T02:00:00.000Z。结构化本地时间parseLocalAtresolveLocalInstant本地解析date必须是四位数 ISO 日期YYYY-MM-DDtime必须是HH:mm:ss可带 13 位小数秒且必须真实存在2026-02-30、24:00:00均拒绝time_zone经canonicalizeTimeZone()时区规范化校验为UTC或合法 IANA 名夏令时缺口拒绝如果本地墙钟时间在目标时区不存在如America/New_York的2026-03-08T02:30:00抛出invalid_rule重叠选择第一个时点在 DST 重叠期选择更早的瞬时测试America/New_York的2026-11-01T01:30:00→2026-11-01T05:30:00.000Z即 EDT 那个时刻。只存储规范 UTC无论输入是带偏移字符串还是本地对象持久化记录AtScheduleRecord都只保留scheduledAt四位数年份 RFC 3339 UTC 时刻不保留提交时的偏移量或本地字段记录类型。这意味着重放replay完全不依赖环境时区状态。未来时刻与范围约束futureInstant未来校验目标必须严格晚于创建时刻否则not_future必须可表示为四位数年份的 UTC 时刻否则time_out_of_range目标时刻必须真实存在如2026-02-30T00:00:00.000Z这类被 Date 自动归一化的非法日历会因回读不一致而被拒绝。稳定的错误码协议Schedule 的错误是封闭的、带稳定机器码的联合类型错误联合与输入边界直接对应错误码触发条件invalid_promptprompt 去空格后为空invalid_selectorafter_secondsatevery_seconds选择器数量不为 1或出现未知参数invalid_rule日历不存在、格式非法、夏令时缺口、参数类型错误invalid_time_zone时区不是UTC或合法 IANA 名not_future目标不严格晚于当前时刻time_out_of_range目标无法表示为四位数年份 UTC 时刻frequency_too_highevery_seconds小于 300 秒MIN_EVERY_INTERVAL_SECONDScorrupt_schedule_log持久化schedule/change事件流损坏persistence_uncertain持久化屏障未能确认工具提示先用schedule_list复核internal_error不对外暴露的内部失败这套错误码同时在工具的输出 JSON Schema 中生效输出模式定义确保模型每次都能读到结构化失败原因而不是自由文本。浏览器事实如何合法跨入 Schedule只有显式工具参数一条路两层职责的完整调用链用户自然语言 明天早上9点提醒我 │ Web client: Intl.DateTimeFormat().resolvedOptions().timeZone 采样 │ → user-rpc 消息携带 clientTimeZone: Asia/Shanghai ▼ Host: 校验并规范化 clientTimeZone拒绝非 IANA 名 │ ├──▶ time-context 插件从 open turn 的 user-rpc 派生唯一/混合/缺失 │ → resolved: 把未限定时区的日期和时间解释为 Asia/Shanghai │ → mixed/missing: 询问用户澄清配置/进程时区只用于时钟显示 │ └──▶ 模型解释自然语言 → 显式调用 schedule_create at: 2026-09-01T09:00:0008:00显式偏移 或 at: { date: 2026-09-01, time: 09:00:00, time_zone: Asia/Shanghai } │ ▼ Schedule: 严格解析 → 校验日历/拒绝缺口/重叠取首个 → 规范化 UTC scheduledAt → 持久化这条链路清楚地表明浏览器时区只影响模型的自然语言理解真正进入 Schedule 的必须是模型显式产出的工具参数。任何让 Schedule 读取最新 time-context 消息让 Host 向工具调用注入 time_zone持久化浏览器默认值的替代方案都被否决详见 Agent Note 的备选方案章节文本快照是模型可见证据而非有类型的包 seamHost 无法知道模型解释的是哪个表达式而持久化默认值会把归属扩散到 core 与 persistence。源码审计防线Agent Note 明确要求源码审计拒绝以下任何残留这是团队自我约束的可验证契约SessionHeader.timeZone字段persistence 层time_zonecolumn确认错误confirmation error路径Schedule 对 time-context 的 import独立回执receipt机制。测试矩阵把边界钉死在回归之外该设计的验证覆盖三个层次均可在仓库测试中找到Host 与 client 测试固定别名的规范化、clientTimeZone可省略行为、以及进入 Agent 前的拒绝。client 测试固定每条提示词进行一次浏览器时区采样。time-context 测试request-zone.spec.ts固定当前 turn 中唯一、混合与缺失三种情形的派生以及对应的精确模型策略文本。Schedule 测试domain.spec.ts固定必需的time_zone、严格偏移量解析、日历校验、时区规范化含US/Eastern→America/New_York的别名收敛、DST 缺口拒绝、重叠时选择第一个时点以及不存在隐式上下文路径本地对象缺time_zone、含额外字段、非字符串字段全部被拒。此外Web 组装场景测试schedule-after.e2e.ts把 Playwright 固定到Asia/Shanghai通过真实 composer 发送提示词在模型请求中观察同一时区验证显式本地工具调用并对普通提醒响应执行 snapshot。设计后果与取舍这条边界的直接收益清晰可数无需持久 Session 时区子系统浏览器本地自然语言也能正常工作Schedule 拥有一个显式且可独立测试的绝对时间边界——重放不依赖任何环境时区状态旅行与并发 tab 只影响各自的提示词provenance 混合的 turn 会询问用户而不是悄悄改变共享状态非浏览器 client 仍然有效但必须提供足够的自然语言上下文或显式工具参数省略clientTimeZone只会让 time-context 显示missing策略。同时也有必须诚实保留的边界模型仍可能产生解释错误——工具只保证显式日历值有效且具有确定性不保证模型对自然语言的翻译永远正确。这正是把解释权留给模型、把校验权留给工具这一分工的代价与价值所在。延伸阅读显式 Schedule 时区边界决策记录本文依据的原始 Agent Notedsh-schedule 包说明含持久化重放、管理管线与 live owner 投递机制dsh-time-context 包说明含插件注入格式与 token/KV Cache 影响Schedule 用户指南官方配置路径dsh web --patch apps/cli/config/examples/schedule/cordis.yml装载 Schedule overlaySchedule 领域实现 与 工具注册请求时区派生 及其 测试Schedule 域测试 与 Web 端到端测试【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考