{"_id":"@buddhilive/dsh-time-context","name":"@buddhilive/dsh-time-context","dist-tags":{"alpha":"0.1.2-alpha.3","latest":"0.1.2-alpha.3"},"versions":{"0.1.2-alpha.3":{"name":"@buddhilive/dsh-time-context","description":"Opt-in durable per-step context with the current time and elapsed time","version":"0.1.2-alpha.3","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/Buddhilive/buddhi-ai-harness.git","directory":"packages/context/time-context"},"type":"module","main":"lib/index.js","types":"lib/types/index.d.ts","exports":{".":{"types":"./lib/types/index.d.ts","default":"./lib/index.js"},"./invariant":{"types":"./lib/types/invariant.d.ts","default":"./lib/invariant.js"},"./src/*":"./src/*","./package.json":"./package.json"},"license":"MIT","dependencies":{"zod":"^4.4.3","@buddhilive/dsh-util-values":"^0.1.2-alpha.3","@deepseek-ai/schemastery":"^3.18.2"},"peerDependencies":{"@deepseek-ai/cordis":"^4.0.2","@buddhilive/dsh-agent":"^0.1.2-alpha.3","@buddhilive/dsh-invariants":"^0.1.2-alpha.3","@buddhilive/dsh-session":"^0.1.2-alpha.3","@buddhilive/dsh-llm":"^0.1.2-alpha.3","@buddhilive/dsh-session-projection":"^0.1.2-alpha.3"},"devDependencies":{"@deepseek-ai/cordis":"^4.0.2","@buddhilive/dsh-agent-loop":"^0.1.2-alpha.3","@buddhilive/dsh-agent":"^0.1.2-alpha.3","@buddhilive/dsh-agent-loop-testkit":"^0.1.2-alpha.3","@buddhilive/dsh-app-boot":"^0.1.2-alpha.3","@buddhilive/dsh-agent-spine-demo":"^0.1.2-alpha.3","@buddhilive/dsh-bash-local":"^0.1.2-alpha.3","@buddhilive/dsh-invariants":"^0.1.2-alpha.3","@buddhilive/dsh-loader-smoke":"^0.1.2-alpha.3","@buddhilive/dsh-llm":"^0.1.2-alpha.3","@buddhilive/dsh-session":"^0.1.2-alpha.3","@buddhilive/dsh-session-persistence-jsonl":"^0.1.2-alpha.3","@buddhilive/dsh-session-checkpoint-policy":"^0.1.2-alpha.3","@buddhilive/dsh-session-projection":"^0.1.2-alpha.3","@buddhilive/dsh-subprocess-local":"^0.1.2-alpha.3","@buddhilive/dsh-system-prompt":"^0.1.2-alpha.3","@buddhilive/dsh-tools":"^0.1.2-alpha.3"},"_id":"@buddhilive/dsh-time-context@0.1.2-alpha.3","bugs":{"url":"https://github.com/Buddhilive/buddhi-ai-harness/issues"},"homepage":"https://github.com/Buddhilive/buddhi-ai-harness#readme","_integrity":"sha512-i8mZTUQfV7X1SJ9ym3Z0Dm1iFqeJL0PLlqfUoAhclYtzok0+KlxOgX2EvaDV5gnVfW4viRi1mmYHAxP3FN0uMw==","_resolved":"C:\\DevDojo\\Buddhi\\buddhi-ai-harness\\dist\\npm\\buddhilive-dsh-time-context-0.1.2-alpha.3.tgz","_from":"file:C:/DevDojo/Buddhi/buddhi-ai-harness/dist/npm/buddhilive-dsh-time-context-0.1.2-alpha.3.tgz","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-i8mZTUQfV7X1SJ9ym3Z0Dm1iFqeJL0PLlqfUoAhclYtzok0+KlxOgX2EvaDV5gnVfW4viRi1mmYHAxP3FN0uMw==","shasum":"eae74cbd5a777565a45256e05c25187ef933086c","tarball":"https://registry.npmjs.org/@buddhilive/dsh-time-context/-/dsh-time-context-0.1.2-alpha.3.tgz","fileCount":11,"unpackedSize":46384,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIEWPAAVaT/MYtDi0/px3bd1pjuBT9VIYMAN/fMNMrfHyAiBZlJS3tP1NapaD+NiE0VCZK7WYKt82fRDUUzwITP4m6Q=="}]},"_npmUser":{"name":"buddhilive","email":"visitbudkavin@gmail.com"},"directories":{},"maintainers":[{"name":"buddhilive","email":"visitbudkavin@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/dsh-time-context_0.1.2-alpha.3_1788166603411_0.825617300121039"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-31T08:56:43.070Z","0.1.2-alpha.3":"2026-08-31T08:56:43.545Z","modified":"2026-08-31T08:56:43.762Z"},"maintainers":[{"name":"buddhilive","email":"visitbudkavin@gmail.com"}],"description":"Opt-in durable per-step context with the current time and elapsed time","homepage":"https://github.com/Buddhilive/buddhi-ai-harness#readme","repository":{"type":"git","url":"git+https://github.com/Buddhilive/buddhi-ai-harness.git","directory":"packages/context/time-context"},"bugs":{"url":"https://github.com/Buddhilive/buddhi-ai-harness/issues"},"license":"MIT","readme":"---\ndescription: \"可选的按步骤时钟上下文，包含当前时间、浏览器时区与经过时长，供启用或调优本插件的用户与维护者阅读。\"\nkind: \"package-reference\"\n---\n\n# @buddhilive/dsh-time-context\n\n[English](README.md) | 中文\n\n## 概述\n\n`dsh-time-context` 给模型一只时钟：在符合条件的步骤上，它追加一条持久、带来源的读数，包含当前时间、附加到当前开放请求的浏览器时区，以及自前一条模型可见消息以来的经过时长。它帮助模型按用户的浏览器时区解释未明确限定时区的日期与时间；时区来源混杂或缺失时，它告诉模型去询问。本插件需主动启用：默认组合不启用它，Schedule Web overlay 会挂载它。正的 `refreshIntervalMs` 会减少读数累积的频率；省略或设为 `0` 时，每个符合条件的步骤都会注入。\n\n## 目录\n\n- [使用本包](#use-this-package)\n- [理解实现](#understand-the-implementation)\n- [进一步探索](#further-exploration)\n- [模型体验](#model-experience)\n- [已知限制与延期工作](#known-limitations-and-deferred-work)\n- [开发备注](#dev-note)\n\n-----\n\n<a id=\"use-this-package\"></a>\n## 使用本包\n\n当模型需要按用户所在时区解释未限定的日期与时间，且请求本地浏览器时区可用或已配置的回退值可接受时，挂载此插件。每次注入都是持久历史中额外的一条 user 角色消息；当按步骤读数超出对话需要时，用 `refreshIntervalMs` 调度。\n\n### 模型能得到什么\n\n每条注入读数包含三行：带数字偏移与 IANA 时区、形如 ISO 的时间戳，该请求的浏览器时区策略，以及以紧凑整秒单位表示的经过时长。第 1 步从最新一条先前模型可见消息起测量；后续步骤从同一轮次中前一个 time-context 事件起测量。缺少基线时报告 `unavailable`，挂钟时间倒退时把经过时长钳制为零。\n\n### 配置\n\n最小挂载无需任何配置。正的 `refreshIntervalMs` 会抑制距最近一次注入不足该毫秒数的注入；省略或设为 `0` 时，每个信号尚未中止且将进入步骤的合格 pre-step 都会注入。\n\n```yaml\n- name: '@buddhilive/dsh-time-context'\n  config:\n    timeZone: Asia/Shanghai\n```\n\n| 字段 | 默认值 | 含义 |\n|---|---|---|\n| `timeZone` | 进程时区 | 当前开放轮次没有唯一浏览器时区时的显示回退时区 |\n| `refreshIntervalMs` | `0`（每个合格步骤） | 同一会话中两次持久注入之间的最小毫秒数 |\n\n生成的[配置目录](../../../docs/config-catalog.zh.md#buddhilivedsh-time-context)是每个受支持字段及其 JSDoc 的穷尽式真源。\n\n### 选择时区\n\n当当前开放轮次只包含一个经 Host 校验的浏览器时区时，时间戳按该请求本地时区格式化。浏览器来源信息缺失或混杂时，配置的 `timeZone` 格式化显示；省略它则在插件加载时解析一次 Node 进程时区，每个显式回退值都经 `Intl.DateTimeFormat` 校验。解析后的指令告诉模型按所选时区解释未限定的日期与时间；来源信息混杂或不可用时，则要求用户澄清。\n\n-----\n\n<a id=\"understand-the-implementation\"></a>\n## 理解实现\n\n<details>\n<summary>实现细节——点击展开</summary>\n\n本节解释插件的设计；可观察行为见[使用本包](#use-this-package)。\n\n### 设计理念\n\n插件前置注册一个 `agent/pre-step` 监听器，先委托下游，需要注入且下游决策进入步骤时追加一条带来源的 `UserMessage`。每个读数都使用确切的快照来源 `{ kind: 'plugin', plugin: 'time-context', form: 'snapshot', sections: [{ name: 'time-context', text }] }`，不变式伴生插件会校验该形状，根据原始 `user-rpc` 消息重新派生当前轮次的浏览器策略，并检查时间戳时区与经过时长基线。\n\n### 源码地图\n\n| 文件 | 职责 |\n|---|---|\n| [`src/index.ts`](src/index.ts) | 插件入口：pre-step 监听器、到期调度、读数组合 |\n| [`src/request-zone.ts`](src/request-zone.ts) | 从开放轮次 `user-rpc` 来源派生浏览器时区策略 |\n| [`src/timestamp.ts`](src/timestamp.ts) | `Intl.DateTimeFormat` 创建与时间戳格式化 |\n| [`src/invariant.ts`](src/invariant.ts) | 快照约定的不变式伴生插件 |\n\n### 主要流程\n\n需要注入时，插件采样挂钟时间，从开放轮次的 `user-rpc` 消息派生浏览器时区策略，解析显示时区（请求本地或回退），并渲染三行读数。正数间隔调度会扫描原始持久会话事件，查找最新一条归因于插件的消息——包括被压缩（compaction）遮蔽的读数——因此调度无需进程本地缓存也能在恢复后存续。读数记录的是已进入的步骤，不是已完成或已传输的请求；后续准备失败时，该读数可能留在历史中。\n\n</details>\n\n-----\n\n<a id=\"further-exploration\"></a>\n## 进一步探索\n\n包级约定不够用时阅读以下页面。它们从设计决策进入挂载本插件的组合与穷尽式配置。\n\n- [持久按步骤 time-context 决策记录](../../../.agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.zh.md)——持久读数的设计理由。\n- [Schedule 用户指南](../../../docs/user/guide/schedule.zh.md)——挂载本插件的官方配置路径。\n- [context 组地图](../README.zh.md)——相邻的请求上下文包。\n- [生成的配置目录](../../../docs/config-catalog.zh.md#buddhilivedsh-time-context)——每个受支持配置字段及其源声明。\n\n-----\n\n<a id=\"model-experience\"></a>\n## 模型体验\n\n### 准备期时间上下文\n\n#### 模型看到的内容\n\n每条注入消息包含三行。`<timestamp>` 是带数字偏移和 IANA 时区、形如 ISO 的时间戳；持续时间使用紧凑的整秒单位。\n\n##### 第一步\n\n```markdown\nTime sampled while preparing turn <turn>, step 1: <timestamp>\nBrowser time zone for this request: <iana-zone-or-mixed-or-unavailable-policy>.\nElapsed since the preceding model-visible message: <duration-or-unavailable>.\n```\n\n##### 后续步骤\n\n```markdown\nTime sampled while preparing turn <turn>, step <step>: <timestamp>\nBrowser time zone for this request: <iana-zone-or-mixed-or-unavailable-policy>.\nElapsed since the preceding step context: <duration-or-unavailable>.\n```\n\n#### Token 影响\n\n每个读数都会累积，直到压缩将其遮蔽。正数间隔会减少新增读数；省略或设为 `0` 时，每次合格的准备尝试都会添加一条。\n\n#### KV Cache 影响\n\n仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。\n\n## 已知限制与延期工作\n\n<a id=\"known-limitations-and-deferred-work\"></a>\n\n\n这些限制说明时钟上下文何时不合适。它们是当前包约束。\n\n- **仅限提示词来源信息**：浏览器时区上下文用于指导自然语言解释，但不会悄然填入另一工具所要求的时区字段。\n- **混合轮次会询问**：如果同一个开放轮次包含来自不同浏览器时区的提示词，模型会收到要求澄清的指令，而不会猜测哪个时区拥有未限定的时间。\n- **回退值不代表用户权威**：浏览器来源信息缺失或混杂时，配置或进程时区用于格式化时钟，但面向模型的策略仍要求澄清。\n- **整秒显示**：时间戳与持续时间省略亚秒精度，尽管持久事件时间保留毫秒。\n- **压缩之间的历史成本**：省略或设为 `0` 时，每次合格尝试都会保留一条读数；正数间隔可以降低但无法消除该成本，也可能使后续请求缺少新鲜的浏览器时区指导。\n\n<a id=\"dev-note\"></a>\n### 开发备注\n\n<details>\n<summary>维护者的工作上下文——点击展开</summary>\n\n无。\n\n</details>\n","readmeFilename":"README.zh.md","_rev":"1-e3e639d185c04f1ba9ade03a98f84f3d"}