dsh-date-wrapper 0.1.1-beta.1

package/cordis.patch.yml

@@ -0,0 +1,16 @@
+# dsh-date-wrapper bundle patch：一行装配进 profile。
+#
+# host 半（src/index.js）把当前日期注册为一条动态运行上下文，
+# 由平台并入自己那条「Current runtime context」快照消息，文本形如：
+#   Current date: 2026-09-08 Asia/Shanghai Tuesday
+#
+# 设计取舍：不加载 @deepseek-ai/dsh-time-context。Cordis 的 prepend 用 unshift，
+# 子 fiber 异步加载后注册的监听器会跑到 wrapper 外面，verbose 文本既看不到也删不掉
+# （详见 .agents/plans/dsh-date-wrapper/findings.md 的 D1）。
+#
+# config 随行下发；改时区只需改这里。
+- insert:
+    - id: date-wrapper
+      name: dsh-date-wrapper
+      config:
+        timeZone: Asia/Shanghai

package/docs/dsh-session-and-context-mechanics.md

@@ -0,0 +1,387 @@
+# DSH 会话、JSONL 与请求组装机制
+
+> 本文档描述 DeepSeek Harness 的**会话事件日志 ⇄ JSONL 持久化**、**surface 派生**、**请求组装**与**运行上下文快照的取代机制**。
+> 所有结论都带 `文件:行号` 依据，路径以本机安装为基准：
+> `[DSH]` = `C:\nvm\v22.22.1\node_modules\@deepseek-ai\dsh\`，`[PKG]` = `[DSH]node_modules\@deepseek-ai\`。
+> 实测数据来自一个真实会话（373 步 / 822 个 surface 事件 / 2.1 MB 压缩日志），见 §8。
+
+---
+
+## 0. 一页速览
+
+```
+用户输入 / steering
+      │
+      ▼
+  inbox（两个列表：next-step / next-turn）
+      │  claim(target, turn)  →  本次请求的「claimed 批次」
+      ▼
+agent/pre-step  waterfall（13 个监听器，8 个会改批次）
+      │  默认决策在最内层追加 runtime-context 快照
+      ▼
+decision.messages  ← 这一步要落盘的 user/message 们
+      │  session.append(..., { surfaceOp:'append' })
+      ▼
+会话事件日志（唯一真相，append-only）
+      │                         │
+      │ surfaceOp: append       │ surfaceOp: replace{start,end}  ← 只遮蔽「表面」，不删日志
+      ▼                         ▼
+   surface（模型可见消息序列）
+      │  deriveMessages()
+      ▼
+ buildRequest(turn, step, tools, system, deriveMessages(), signal)
+      │
+      ├── request/header  ← 仅在 system/tools/config 变化时追加（含整份 system + 工具 schema）
+      ├── request/context ← 仅在 provider/model/contextWindow 变化时追加
+      ▼
+ deepFreeze(request) + markAgentLoopRequest(request)
+      │
+      ▼
+ llm/stream waterfall → adapter
+      │  （只允许包流；agent-loop invariant 断言 messages 必须等于 deriveMessages()）
+      ▼
+ 模型
+      │
+      ▼
+ assistant/message + tool/call + tool/result → 再次 session.append
+```
+
+---
+
+## 1. 会话事件日志：唯一真相
+
+### 1.1 事件形状
+
+```js
+{ type, seq, time, data, ...surfaceMetadata }   // surfaceMetadata = { surfaceOp?, sourceEventSeqs? }
+```
+
+`session.append()` 做三件事（`[PKG]dsh-session/lib/types/index.js:484-509`）：
+
+1. `snapshotJsonValue(data)` —— 必须**无损 JSON 序列化**（不能有 `undefined`、函数、`Date`、循环、非有限数）；
+2. `assertSupportedRequestHeader()` —— 拒绝已废弃的历史格式；
+3. `deepFreeze({ type, seq, time, data, ... })` —— **日志自己深冻结快照**，调用方不需要预冻结，也不会被后续别名修改。
+
+> 日志是 durable source of truth：坏事件在 `append` 处就失败，而不是等到刷盘时（`:478-483` 的注释）。
+
+### 1.2 主要事件类型（本会话实测计数）
+
+| 事件 | 说明 | 本会话 |
+|---|---|---|
+| `turn/start` · `turn/end` | 轮次边界 | 10 / 9 |
+| `step/start` · `step/end` | 步骤边界（= 一次模型调用） | 231 / 230 |
+| `user/message` | 用户输入 + 所有注入上下文 | 20 |
+| `assistant/message` | 模型回复 | 231 |
+| `assistant/chunk` / `text-chunks` / `reasoning-chunks` / `tool-call-chunks` | 流式增量（后三者是 `packChunks` 打包行） | 1756 / 164 / 1202 / 851 |
+| `tool/call` · `tool/result` | 工具调用与结果 | 275 / 274 |
+| `request/header` | 请求头（system + tools + config）变化 | 1 |
+| `request/context` | provider/model/contextWindow 变化 | 1 |
+| `agent/inbox/spliced` | 入队/出队审计 | 27 |
+
+### 1.3 落盘路径
+
+`session.append` 后，持久化层把事件批量写成 JSONL：
+
+- 目录：`<sessionRoot>/<project>/<session-id>/`（`[PKG]dsh-session-persistence-jsonl/lib/index.js:145-157`）；
+- 文件：`session.jsonl`（`compression: none`）或 `session.jsonl.zstd`（默认）。
+
+---
+
+## 2. 会话 ⇄ JSONL 的转换
+
+### 2.1 物理布局：header 帧 + N 个批次帧
+
+```
+session.jsonl.zstd
+├── [zstd frame #1]  首行 header（JSON）           ← encodeMaterialization
+├── [zstd frame #2]  首批事件行                    ← encodeMaterialization
+├── [zstd frame #3]  一次 append 批次的事件行      ← encodeEventBatch
+├── ...
+└── [zstd frame #N]  ...
+```
+
+- `encodeMaterialization()`（`:1170-1178`）：header 行与首批事件**分成两个独立 zstd 帧**，刻意不合并帧边界；
+- `encodeEventBatch()`（`:1179-1183`）：每次持久化 append = 一批事件 → `eventLines() + "\n"` → 一个 zstd 帧；
+- 所以一个长会话是**多帧 zstd 拼接**：本会话实测 **2731 个帧**（`0x28 0xB5 0x2F 0xFD` 魔数计数），普通解压只解出第一帧——需要按魔数切帧或走 DSH 自带的 `zstd-private-decoder`（`:336-383`）。
+
+### 2.2 header 行
+
+```js
+{ type: 'session', version, id, createdAt, cwd?, parentSession?, seedLength?, origin?, delegationDepth, agentPreset? }
+```
+（`toHeaderLine()`，`:36-49`）—— 首行必须是合法 header，否则日志判为损坏（`:187-198`）。
+
+### 2.3 事件行与 `packChunks`
+
+```js
+eventLines(events, packChunks) {
+  return (packChunks ? packChunkRuns(events) : events).map((r) => JSON.stringify(r)).join("\n")
+}
+```
+（`:160-172`）
+
+- 默认 `packChunks: true`：连续的流式 delta 会被**打包成 `text-chunks` / `reasoning-chunks` / `tool-call-chunks` 存储行**，不再是一事件一行；
+- 关闭时逐事件一行，与打包前的字节布局一致；读取端对布局不敏感（`scanLog` 总是先解码再读）。
+
+### 2.4 崩溃安全
+
+- 写入后 `fsync`；部分写或同步失败时**回滚到之前的文件长度**再抛错，因为游标未变会重试该批次，残留半行会造成重复 `seq`（`:1195-1199` 起）。
+
+### 2.5 读回与恢复
+
+- 解码：多帧 zstd → 逐行 JSON → 事件对象；header 行单独校验（`refuseForeignFormatVersion()` 拒绝未来格式）；
+- 形状校验发生在**导入边界**：`adoptSessionEvent` / `snapshotSessionEvent` → `assertMessageEventShape()`（`[PKG]dsh-session/lib/types/index.js:219-247`）。`user/message` 要求 `id` 非空串、`role` 匹配、`source.kind` 非空串、`content` 是数组；**不检查** `source.form` / `sections`；
+- 历史消息缺 `id` 时会被补铸确定性 id `legacy-message:${sessionId}:${seq}`（`[PKG]dsh-session-persistence/lib/index.js:665-678`、`:518-521`）；
+- 由于日志可完整重建，**恢复 = 重放**，不需要额外快照文件。
+
+---
+
+## 3. Surface：从日志派生「模型可见的消息」
+
+日志里并非每条事件都进对话。`surfaceOp` 决定可见性（`[PKG]dsh-session/lib/types/surface.js`）：
+
+| op | 含义 |
+|---|---|
+| 缺失 | 不是 surface 事件（如 `step/start`、`tool/call`），不参与消息派生 |
+| `'append'` | 追加到可见序列 |
+| `{ op: 'replace', start, end, sourceEventSeqs? }` | **遮蔽** `[start, end]` 区间的既有可见事件；事件本身仍留在日志里 |
+
+- surface 事件类型是固定的那几种（`user/message`、`assistant/message`、`tool/result` 等，`:12`）；
+- `deriveMessages()` 增量遍历 surface 节点，产出模型可见的消息数组，并在 `replaceGeneration` 变化时重建缓存（`[PKG]dsh-session/lib/types/index.js` 的 `deriveMessages()`）；
+- **`replace` 的真实使用者**：压缩检查点 —— `session.append('user/message', checkpoint, { surfaceOp: { op:'replace', start, end }, sourceEventSeqs:[…] })`（`[PKG]dsh-compaction-basic/lib/index.js:606-611`）。它把被折叠的一段历史从**表面**遮掉，日志里一条不删。
+
+> 这就是「日志 ≠ 对话」的分界线：日志只追加，对话靠 `surfaceOp` 重新投影。
+
+---
+
+## 4. 请求组装（`buildRequest`）
+
+每次 step 前，`[PKG]dsh-agent-loop/lib/index.js:693-762` 组装三块：
+
+| 块 | 来源 | 变化时记录 |
+|---|---|---|
+| `system` | `renderPrompt(assembly)` 把 sections 用 `\n\n` 拼起来（`[PKG]dsh-system-prompt/lib/index.js:65-67`） | `request/header.system` |
+| `tools` | 各 provider 提供的 schema，按 scope 收集 + `orderTools()` 排序（`[PKG]dsh-tools:2595`、`[PKG]dsh-system-prompt:280`） | `request/header.tools` |
+| `messages` | `session.deriveMessages()`（即 §3 的 surface 派生） | 不单独记录（就是日志本身） |
+
+### 4.1 `request/header`：只在变化时写
+
+```js
+const header = canonicalHeader({ config, adapterDefaults?, system?, tools? })
+if (!requestHeaderLogged) append('request/header', { header, reason: 'initial' | 'resume' })
+else if (!headerEquals(baseline, header)) append('request/header', { header, reason: 'change' })
+```
+（`:725-741`）
+
+`headerEquals` 比较 `config`、`adapterDefaults`、**`system` 全串**、**`tools` 全量 schema**（`:548` 起）。所以：
+
+- 系统提示词或工具表**不变**时，一条 header 都不写（本会话 373 步只有 **1 条** header：`system` 16853 字符 + **56** 个工具 schema）；
+- 一旦变化，追加的是**整份** header —— 这是「改系统提示词代价高」的直接原因。
+
+### 4.2 请求对象被冻结并打标
+
+```js
+request: markAgentLoopRequest(deepFreeze({ ...header.config, messages, system?, tools?, sessionId, signal }))
+```
+（`:751-761`）—— `deepFreeze` 后不可改；`markAgentLoopRequest` 把对象登记进 WeakSet（`[PKG]dsh-llm/lib/index.js:87-90`），供下游按身份识别。
+
+### 4.3 `llm/stream` 只能包流，不能改请求
+
+```js
+streamWithRegistration(options, prepared) {
+  return this.ctx.waterfall(this, 'llm/stream', options, () => this.adapterStream(options, prepared))
+}
+```
+（`[PKG]dsh-llm/lib/index.js:1636-1641`）
+
+`next` 是零参闭包、`options` 已冻结 → 监听器只能包装返回的流（in-box 的 `llm-invariant` 就是 `validateStream(next())`）。
+
+### 4.4 「请求必须等于日志派生」是硬契约
+
+`[PKG]dsh-agent-loop/lib/invariant.js:15-33` 在 `llm/stream` 上断言：
+
+```js
+if (!isAgentLoopRequest(options)) return next()
+if (!Object.isFrozen(options)) fail('a loop-built request must be frozen')
+const expected = session.deriveMessages()
+if (JSON.stringify(options.messages) !== JSON.stringify(expected))
+  fail('llm request … diverges from the dispatch-time durable derivation (log-reconstruction desync)')
+if (!(options.model === header.config.model && options.system === header.system && …)) fail(…)
+```
+
+→ **任何「只发给模型、不落日志」的消息注入都会被判为违约**。想影响模型看到的 messages，只能通过日志（`agent/pre-step` 追加消息）；想影响 system，只能通过 `request/header`（即 `systemPrompt.section`）。
+
+---
+
+## 5. pre-step 批次：`decision.messages`
+
+### 5.1 组装顺序
+
+```js
+const claimed = this.inbox.claim(target, position.turn)
+const assembly = await this.loopCtx.systemPrompt.assemble(assembleContextFor(this, signal))
+const context  = this.runtimeContext.project(joinContextSections(sections), sections)
+const decision = await this.dispatch.waterfall('agent/pre-step',
+  { messages: claimed, ...position, signal },
+  () => Promise.resolve({ kind: 'enter', messages: context === undefined ? claimed : [...claimed, context] }))
+```
+（`[PKG]dsh-agent-loop/lib/index.js:492-514`）
+
+### 5.2 `claim` 规则
+
+```js
+claim(target, turn) {
+  const claimed = this.mutate('next-step', 0, this.nextStep.length, [], false)   // next-step 全部
+  if (target === 'next-turn') claimed.push(...this.mutate('next-turn', 0, 1, [], false))  // 至多 1 条
+  …
+}
+```
+（`[PKG]dsh-agent/lib/types/inbox.js:50-57`）
+
+- `next-step`：`steer()` / `inject()` 的目标，**没有条数上限**（连续插队会累积）；
+- `next-turn`：`followup()` 的目标，每次 claim **最多取 1 条**；
+- `turn()` 里 `target` 首步是 `'next-turn'`，之后变 `'next-step'`（`:529`、`:572`）。
+
+### 5.3 谁在动批次
+
+本版本 13 个 `agent/pre-step` 监听器，其中 8 个会改批次：`time-context`(append)、`tmux-context`(prepend)、`session-reference`(改写+插入)、`tool-skill`(append/replace/remove)、`agent-instructions`(插在最后一条 claimed 之后)、`tool-cordis`(append)、`plan-mode`(append)、以及运行上下文默认追加。
+
+### 5.4 实测：大多数步骤批次是空的
+
+| 每步 `user/message` 条数 | 步数 |
+|---|---|
+| 0 | 349 |
+| 1 | 20 |
+| 2 | 2 |
+| 3 | 1 |
+| 6 | 1 |
+
+工具调用后的续跑没有新输入 → 批次为空 → `for (const m of decision.messages) session.append(...)`（`:554`）空转，但 `step/start` 照常开、模型继续。
+
+---
+
+## 6. 运行上下文快照与「取代」机制
+
+### 6.1 它是「动态事实」的合并通道
+
+四个贡献者（`systemPrompt.context({ name, order, text })`，`[PKG]dsh-system-prompt/lib/index.js:196-199`）：
+
+| 来源 | name | order |
+|---|---|---|
+| `dsh-sandbox-policy` | `sandbox:policy` | 110 |
+| `dsh-user-approval` | `approval:policy` | 115 |
+| `dsh-date-wrapper` | `date-wrapper:date` | 116 |
+| `dsh-subagent` | `subagent:delegation` | 120 |
+
+每次 assemble 重新求值（`text` 可以是函数，`:271`），按 order 排序后用 `\n\n` 拼成一条快照文本。
+
+### 6.2 只在文本变化时才产生消息
+
+```js
+project(current, sections) {
+  if (this.retained === void 0 && current.length === 0) return
+  const snapshot = current.length === 0 ? CLEARED : current
+  if (this.retained?.text === snapshot) return          // ← 文本没变：不产生任何消息
+  return createUserMessage({ content: [{ type:'text', text: snapshot }], source: … })
+}
+```
+（`[PKG]dsh-agent-loop/lib/index.js:57-75`）
+
+### 6.3 取代不是改写，是「追加 + 声明」
+
+快照正文第一句固定为：
+
+```
+Current runtime context. This snapshot supersedes earlier runtime-context snapshots.
+```
+（`[PKG]dsh-system-prompt/lib/index.js:84-88`）
+
+- 新快照以 `surfaceOp: 'append'` **追加**，旧快照**留在日志里**；
+- 模型按「最新优先」读；`RuntimeContextProjection` 在快照被 `replace` 遮蔽时把 `retained` 清空（`[PKG]dsh-agent-loop:54`），以便下次变化重新发布；
+- 本会话三条快照的演进（全部 `append`，零 `replace`）：
+
+```
+seq=8      466 chars  无日期   ← 初始
+seq=76791  390 chars  无日期   ← 沙箱/审批策略变化触发重发
+seq=248462 438 chars  含日期   ← 插件生效
+```
+
+### 6.4 与「系统提示词 section」的区别
+
+| | `context()`（快照） | `section()`（系统提示词） |
+|---|---|---|
+| 落点 | 一条 `user/message` | 请求的 `system` 字符串 |
+| 日志 | 文本变化时追加一条快照消息 | 变化时在 `request/header` 里重记**整份** system |
+| 前缀缓存 | 尾部追加，前缀不变 | **头部被重写 → 整个前缀失效** |
+| 被 preset 顶掉 | `includeRuntimeContext: false` → `contexts: []` | `complete: true` 的 section 会独占 `sections` |
+
+（抑制逻辑：`[PKG]dsh-system-prompt/lib/index.js:243`、`:276`、`:284-289`；官方 `minimal` 与本地 `simple-reply` 两个 preset 同时设了这两项，因此**任何**提示词/上下文注入在那类 preset 下都失效。）
+
+---
+
+## 7. 体积与缓存
+
+### 7.1 三种变更的代价
+
+| 变更 | 请求序列怎么变 | 前缀缓存 |
+|---|---|---|
+| 追加消息（用户输入、注入上下文、快照） | 末尾多一条 | **不受影响**，只有新增后缀是 miss |
+| `surfaceOp: replace` 遮蔽一段 | 可见序列变短 | 遮蔽点之后需要重算 |
+| 改 `system` 或 `tools` | 头部被重写 | **整个前缀失效**（这是 Anthropic 系 `defer_loading` 想解决的问题） |
+
+### 7.2 本会话实测
+
+| 项 | 数值 |
+|---|---|
+| 日志 | 822 个 surface 事件，**全部 `append`，0 个 `replace`**；压缩后 2.1 MB，2731 个 zstd 帧 |
+| `request/header` | 1 条：`system` 16853 字符 + 56 个工具 schema |
+| 运行上下文快照 | 3 条，390–466 字符（JSONL 1055–1211 字节/条） |
+| 真实用户消息 | 22 条 |
+| 最大单条注入 | `skill-catalog` 56527 字节（19887 字符） |
+| `subagent-settled` | 33683 字节/条 × 2 |
+| 本插件贡献 | 46 字符 ≈ 12 token（`CHARS_PER_TOKEN=4`，`[PKG]dsh-token-meter/lib/index.js:15`），且仅在日期变化时随快照带上 |
+
+---
+
+## 8. 本插件在其中的位置
+
+`dsh-date-wrapper` 只做一件事：往「动态运行上下文」通道里加一行。
+
+```js
+ctx.inject(['systemPrompt'], (scope) => {
+  scope.systemPrompt.context({
+    name: 'date-wrapper:date', order: 116,
+    text: () => renderDate(Date.now(), formatter, zone),   // 每次 assemble 重新求值
+  })
+})
+```
+
+- 不产生额外 `user/message`：日期并入平台**本来就会发**的那条快照；
+- 同一天内 0 条额外事件（`project()` 文本去重）；
+- 跨天时追加一条新快照，旧的那条留在历史里，靠 supersedes 声明让最新生效；
+- 前缀缓存不受影响（追加而非改写）。
+
+---
+
+## 9. 代码索引
+
+| 主题 | 位置 |
+|---|---|
+| 事件 append 与深冻结 | `[PKG]dsh-session/lib/types/index.js:484-509` |
+| surface 判定与 op 词表 | `[PKG]dsh-session/lib/types/surface.js:32-56,124-145,255-290` |
+| 消息形状校验（导入边界） | `[PKG]dsh-session/lib/types/index.js:219-247` |
+| JSONL 路径 / header / 批次编码 | `[PKG]dsh-session-persistence-jsonl/lib/index.js:145-198,160-172,1170-1199` |
+| 多帧 zstd 解码 | 同上 `:336-383`、`:456-468` |
+| legacy 消息 id 补铸 | `[PKG]dsh-session-persistence/lib/index.js:518-521,665-678` |
+| pre-step 与默认决策 | `[PKG]dsh-agent-loop/lib/index.js:492-514` |
+| inbox claim | `[PKG]dsh-agent/lib/types/inbox.js:50-57` |
+| 请求组装 / header 比较 | `[PKG]dsh-agent-loop/lib/index.js:693-762,529-548` |
+| 请求冻结与打标 | `[PKG]dsh-agent-loop/lib/index.js:751-761`、`[PKG]dsh-llm/lib/index.js:87-90` |
+| `llm/stream` waterfall | `[PKG]dsh-llm/lib/index.js:1636-1641` |
+| log-reconstruction 断言 | `[PKG]dsh-agent-loop/lib/invariant.js:15-33` |
+| prompt 组装 / sections / contexts / variables | `[PKG]dsh-system-prompt/lib/index.js:65-102,186-230,240-289` |
+| 快照去重与 supersedes | `[PKG]dsh-agent-loop/lib/index.js:26-75`、`[PKG]dsh-system-prompt/lib/index.js:84-88` |
+| 工具 schema 提供者 | `[PKG]dsh-tools/lib/index.js:2595`、`[PKG]dsh-system-prompt/lib/index.js:280` |
+| 技能目录的 digest + 批内替换 | `[PKG]dsh-tool-skill/lib/index.js:181-214,247,309-336` |
+| 压缩检查点用 replace 遮蔽 | `[PKG]dsh-compaction-basic/lib/index.js:606-611` |
+| token 估算启发式 | `[PKG]dsh-token-meter/lib/index.js:15` |

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "dsh-date-wrapper",
+  "version": "0.1.1-beta.1",
+  "type": "module",
+  "description": "Minimal date line for the DeepSeek Harness runtime-context snapshot: 'Current date: 2026-09-08 Asia/Shanghai Tuesday' (46 chars, ~12 tokens) - a cordis host plugin, no dsh source changes, no PR required",
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "plugin",
+    "time",
+    "date",
+    "context",
+    "timezone"
+  ],
+  "license": "MIT",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src/",
+    "docs/",
+    "cordis.patch.yml",
+    "README.md",
+    "README.zh.md",
+    "README.ja.md",
+    "README.ko.md",
+    "INSTALL.md",
+    "INSTALL.zh.md",
+    "INSTALL.ja.md",
+    "INSTALL.ko.md",
+    "CHANGELOG.md",
+    "CHANGELOG.ja.md",
+    "CHANGELOG.ko.md",
+    "HANDOVER.md",
+    "LICENSE"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "scripts": {
+    "test": "node --test \"tests/*.test.mjs\"",
+    "tdd": "node --test --watch \"tests/*.test.mjs\"",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "verify": "npm run lint && npm run test"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.10.0"
+  },
+  "engines": {
+    "node": ">=20",
+    "dsh": ">=0.1.0-rc.7 <0.2.0-0"
+  }
+}

package/src/format.js

@@ -0,0 +1,119 @@
+/**
+ * dsh-date-wrapper — 时区投影与日期文本（纯函数，零依赖，可单测）。
+ *
+ * 输出格式：`Current date: 2026-09-08 Asia/Shanghai Tuesday`
+ * —— 标签 + ISO 日期 + IANA 时区名 + 英文星期，无时分秒。
+ * 标签与快照里其它条目的风格一致（`Current DSH file policy: …`、`Approval policy: …`）。
+ *
+ * 设计要点：
+ * - 日期与星期都从**同一份投影结果**推出：先用 `formatToParts` 得到该时区的
+ *   Y/M/D，再由 `Date.UTC(y, m-1, d).getUTCDay()` 求星期。这样星期不可能与
+ *   日期错位（跨时区边界时，北京 2026-09-08 00:30 必须是 Tuesday，而 UTC
+ *   同一时刻还是 2026-09-07 Monday）。
+ * - 不依赖 locale 数据：星期用固定英文表，日期手工拼串（`en-CA` 恰好也给
+ *   `YYYY-MM-DD`，但那是巧合而非契约）。
+ * - 只产出**文本**：注入点是 `systemPrompt.context()`（动态运行上下文），由平台
+ *   把它并入「Current runtime context」快照消息 —— 不产生额外的 user/message，
+ *   也不改写系统提示词（见 README）。
+ * - 文本 provider 必须 fail-soft：prompt 组装期抛错会让**每一次请求**都失败，
+ *   所以无法渲染时返回空串（平台会过滤掉空文本，见 dsh-system-prompt:102）。
+ */
+
+/** 星期名（索引同 `getUTCDay()`：0=Sunday）。固定英文表，不依赖 locale。 */
+const WEEKDAY_NAMES = Object.freeze([
+  'Sunday',
+  'Monday',
+  'Tuesday',
+  'Wednesday',
+  'Thursday',
+  'Friday',
+  'Saturday',
+])
+
+/**
+ * 文本标签。与快照里其它条目的风格一致（`Current DSH file policy: …`）。
+ * 想换成 `Date:` / `Date refer:` 只改这一处。
+ */
+export const TEXT_LABEL = 'Current date: '
+
+/**
+ * 解析并校验时区，产出一个可复用的格式化器。
+ *
+ * @param {string|undefined} timeZone IANA 时区名；`undefined` 表示用进程时区。
+ * @returns {{ formatter: Intl.DateTimeFormat, zone: string }} 格式化器与规范化时区名。
+ * @throws {Error} 时区非法或无法解析时抛错（fail-fast，绝不静默降级成 UTC）。
+ */
+export function resolveZone(timeZone) {
+  let formatter
+  try {
+    formatter = new Intl.DateTimeFormat('en-US', {
+      ...(timeZone === undefined ? {} : { timeZone }),
+      year: 'numeric',
+      month: '2-digit',
+      day: '2-digit',
+    })
+  } catch (error) {
+    const reason =
+      timeZone === undefined
+        ? '系统时区无法解析'
+        : `非法 IANA timeZone ${JSON.stringify(timeZone)}`
+    throw new Error(`date-wrapper: ${reason}`, { cause: error })
+  }
+  return { formatter, zone: formatter.resolvedOptions().timeZone }
+}
+
+/**
+ * 渲染一行日期文本。
+ *
+ * @param {number} now 时间戳（毫秒）。
+ * @param {Intl.DateTimeFormat} formatter 由 {@link resolveZone} 产出。
+ * @param {string} zone 规范化 IANA 时区名，原样出现在文本里。
+ * @returns {string} 形如 `Current date: 2026-09-08 Asia/Shanghai Tuesday`。
+ */
+export function renderDate(now, formatter, zone) {
+  const parts = Object.fromEntries(
+    formatter.formatToParts(new Date(now)).map((part) => [part.type, part.value]),
+  )
+  const date = `${parts.year}-${parts.month}-${parts.day}`
+  const weekday = WEEKDAY_NAMES[new Date(Date.UTC(parts.year, parts.month - 1, parts.day)).getUTCDay()]
+  return `${TEXT_LABEL}${date} ${zone} ${weekday}`
+}
+
+/**
+ * 构造运行上下文条目的文本 provider。
+ *
+ * 平台每次组装 prompt 都会调用它（`dsh-system-prompt:271`），所以日期始终是
+ * 当次请求的当下日期。渲染失败时返回空串而不是抛出 —— prompt 组装期抛错会
+ * 让每一次请求都失败，而日期缺失只是可接受的降级；空文本会被平台过滤掉
+ * （`dsh-system-prompt:102`）。
+ *
+ * @param {{ formatter: Intl.DateTimeFormat, zone: string }} deps 渲染依赖。
+ * @returns {() => string} 每次调用重新取当前时间的文本 provider。
+ */
+export function createDateContextText({ formatter, zone }) {
+  return () => {
+    try {
+      return renderDate(Date.now(), formatter, zone)
+    } catch {
+      return ''
+    }
+  }
+}
+
+/**
+ * 校验并规范化插件配置。
+ *
+ * @param {unknown} config 来自 `cordis.patch.yml` 的行配置。
+ * @returns {{ timeZone: string|undefined }} 去空白后的配置。
+ * @throws {Error} `timeZone` 类型或取值非法时抛错。
+ */
+export function validateConfig(config) {
+  const raw = config && typeof config === 'object' && !Array.isArray(config) ? config : {}
+  const { timeZone } = raw
+  if (timeZone !== undefined && (typeof timeZone !== 'string' || timeZone.trim() === '')) {
+    throw new Error(
+      `date-wrapper: config.timeZone must be a non-empty IANA zone string, got ${JSON.stringify(timeZone)}`,
+    )
+  }
+  return { timeZone: timeZone === undefined ? undefined : timeZone.trim() }
+}

package/src/index.js

@@ -0,0 +1,49 @@
+/**
+ * dsh-date-wrapper — host 半。
+ *
+ * 把当前日期注册为一条**动态运行上下文**（`systemPrompt.context`）。平台在每次
+ * 组装 prompt 时渲染它，并把它并入自己那条「Current runtime context」快照消息，
+ * 文本形如 `2026-09-08 Asia/Shanghai Tuesday`：
+ *
+ * - 不产生额外的 `user/message`（对比：往 `agent/pre-step` 塞消息会每轮落一条）；
+ * - 平台对快照**按文本去重**（`RuntimeContextProjection.project()` 只在文本变化时
+ *   追加新快照），所以日期不变时一条事件都不多，跨天时最多多一条；
+ * - 快照是**追加**而非原地改写，请求序列只增长，因此不破坏前缀缓存。
+ *
+ * 生命周期：`ctx.inject(['systemPrompt'], …)` 建立子 fiber，注册随插件 fiber
+ * 一起回收。**不导出插件级 `inject`** —— 那会让 fiber 卡在 PENDING，服务缺失时
+ * 触发启动审计失败；`ctx.inject` 的等待语义相同但不拖垮 boot（先例：
+ * `@deepseek-ai/dsh-user-approval`）。
+ */
+import { createDateContextText, resolveZone, validateConfig } from './format.js'
+
+/** Cordis 插件名。 */
+export const name = 'date-wrapper'
+
+/** 运行上下文条目的名字（同名重复注册会抛错）。 */
+export const CONTEXT_NAME = 'date-wrapper:date'
+
+/**
+ * 排序位。上下文按 order 升序渲染（`dsh-system-prompt:276`）；
+ * 已占用：110 sandbox:policy、115 approval:policy、120 subagent:delegation。
+ */
+export const CONTEXT_ORDER = 116
+
+/**
+ * 注册日期运行上下文。
+ *
+ * @param {object} ctx Cordis 上下文。
+ * @param {{ timeZone?: string }} [config] patch 行下发的配置。
+ * @throws {Error} `timeZone` 非法时抛错（fail-fast，绝不静默降级成 UTC）。
+ */
+export function apply(ctx, config) {
+  const { timeZone } = validateConfig(config)
+  const { formatter, zone } = resolveZone(timeZone)
+  ctx.inject(['systemPrompt'], (scope) => {
+    scope.systemPrompt.context({
+      name: CONTEXT_NAME,
+      order: CONTEXT_ORDER,
+      text: createDateContextText({ formatter, zone }),
+    })
+  })
+}