# dsh-nightshift（夜航）设计规范

> DeepSeek Harness 第三方插件：白天高峰时段把任务排队冻结，低谷电价时段自动逐个执行、失败自动重试，跑完生成省钱报告。
>
> 状态：v1.1（集成对齐完成）。本文件是 host 与 client 两个实现线的共同契约。实现中发现 SPEC 与 dsh 源码冲突时，**以源码为准并回报 team-lead 修订 SPEC**，不得私自变更接口形状。SPEC 中标注 `[TBD-验证]` 的条目由对应实现者从源码确认后回填——**全部已回填销账**（#5 slot props 形状、#6 dsh.client.inject 裁定）。

## 0. 产品定义

**一句话**：白天排队，错峰自动跑，跑完看账单。

| 能力 | 说明 |
|---|---|
| 入队 | 会话输入框旁「夜航」按钮：把当前输入框内容作为任务入队，续当前会话；「新会话」按钮则以 fresh 模式入队（cwd = 当前会话所属工作区路径，未分组时缺省） |
| 峰时冻结 | 高峰时段（默认北京时间 09:00–12:00、14:00–18:00）不派发任何任务 |
| 错峰 drain | 非高峰时段逐个派发（含午间、夜间、凌晨），一次只跑一个，冷会话自动 resume |
| 失败处理 | `turn/end` 结构化原因分类：error→退避重试；max-tokens→自动「继续」；blocked→标记等人工；aborted→视为用户取消 |
| 省钱账本 | 实测 token 用量 × 峰谷单价记账，报告展示绝对省钱额与 token 数 |
| 报告 | 队列清空（或高峰来临时）生成报告，面板一键查看 |

**非目标**（v1 不做）：跨机器同步、并发执行、working tree 冲突检测、自动 git 分支、余额/钱包查询、多语言 UI（中文为主）、报告注入会话（v1.1 候选）、watchdog 自动纠偏（v2 候选）、模型可调用工具 `nightshift_enqueue`（v1.1 候选，理由：工具 schema 会进入所有会话的 system prompt，与"省 token"的立身之本冲突；默认不注册，config 预留 `exposeTool: false`）。

## 1. 仓库布局

```
C:\code\learn\dshPlugin\
├── package.json          # dsh-nightshift bundle 清单（dsh.bundle + dsh.client）
├── cordis.patch.yml      # - insert: [{ id: nightshift, name: dsh-nightshift }]
├── index.js              # host 半（ESM cordis 函数式插件）
├── client.js             # client 半（手写 __ModuleLoader__.load 工厂）
├── lib/                  # 纯逻辑（零依赖，host 半 import，独立可测）
│   ├── schedule.js       # 峰谷窗口判定纯函数
│   ├── queue.js          # 队列状态机
│   ├── retry.js          # 退避策略
│   ├── ledger.js         # token/费用账本 + 省钱计算
│   ├── report.js         # 报告汇总
│   └── format.js         # 展示格式化（client 也复用的纯函数）
├── test/                 # vitest 单测
├── install.ps1           # 一键安装
├── README.md / README.zh.md
└── LICENSE               # MIT
```

- 语言：**纯 ESM JavaScript + JSDoc**，无构建步骤。运行时直接依赖仅 dsh 提供的包（见 §11）。
- 测试：vitest（devDependency）。lib 纯函数直测；index.js 用 `vi.mock` 掉 dsh 包测调度行为。

## 2. 关键技术事实（已由两份源码调研确认）

### host 侧

| 事实 | 依据 |
|---|---|
| `TokenUsage` 字段：`inputTokens`/`outputTokens`/`totalTokens?`/`cacheReadTokens?`/`cacheWriteTokens?`/`reasoningTokens?`（reasoning ⊆ output） | `packages/llm/llm/src/types.ts:135-149` |
| 每回合用量 = `ctx.sessionProjections.stateOf(session,'tokenUsage').totals` 回合前后差值（四桶：uncachedInput/output/cacheRead/cacheWrite；token-meter 在 base bundle 默认挂载）。已验证：`stateOf` 第二参为注册 key（`'tokenUsage'`），键未注册时返回 `undefined`——实现须判空告警（fail-loud，不可静默记 0）；totals 桶名字段为 `uncachedInputTokens/outputTokens/cacheReadTokens/cacheWriteTokens`（读取时映射到 ledger 四桶） | `packages/session/session-projection/src/index.ts:307-315`；`packages/llm/token-meter/src/usage-projection.ts:38-41,120-157`；`packages/bundle/base/cordis.patch.yml:323` |
| harness **无任何定价/余额/峰谷感知** → 单价全由插件 config 提供 | 全库搜索确认 |
| config：函数式插件导出 `Config`（Schema.object），`apply(ctx, config)` 第二参注入，改配置触发 HMR 重载 | `docs/user/develop/basic/config.md` |
| 持久化：`await ctx.storageDomain.open(spec)`（zod 行 schema），读同步、写 `put/update` 落盘后发 `domain/changed`，**不可原地 mutate**；调用方自持生命周期（`ctx.effect(() => async () => domain.close())`） | `packages/feedback/message-feedback/src/spec.ts:84-90`、`index.ts:173-181` |
| host 进程随 web profile **常驻且独立于浏览器**（refresh 不丢队列）；headless 是一次性的 | `packages/bundle/headless/src/index.ts:205`；apps/cli 无 serve/daemon 子命令 |
| 冷会话：`ctx.sessionController.resolveAgent(sessionId)` 对冷 session 自动从盘 resume，并发去重 | `packages/api/session-controller/src/agent.ts:165→178→393` |
| 夜间派发**不走 prompt RPC**，直接 `agent.followup(msg)`（少一层，语义同 queue 模式） | `packages/api/session-controller/src/commands.ts:283-336` |
| `UserMessage` 构造：`createUserMessage({content:[{type:'text',text}], source:{kind:'plugin',plugin:'nightshift'}})`，id 自动生成 | `packages/llm/llm/src/message.ts:194-201`；样板 `packages/schedule/schedule/src/runtime.ts:271-275` |
| `turn/end` 事件：`ctx.on('session/event',(session,event)=>…)`，`data:{turn,reason}`，`reason.kind`∈completed/aborted/blocked/error/max-tokens/interrupted | `packages/core/session/src/types.ts:232` |
| 进程级定时器：顶层 `apply` 里 `ctx.effect` 挂**自递归 setTimeout**（单次 ≤ 2³¹-1ms 钳制），禁 setInterval；**不得挂在 session/agent 级 effect** | 样板 `packages/schedule/schedule/src/{index,runtime}.ts` |
| 会话创建：`sessionController.create({cwd?, sessionId?, agentPreset?})`；**不要用 subagent 机制**（`origin==='subagent'` 被 API 路由拒绝） | `packages/api/session-controller/src/types.ts:255`；`agent.ts:79-102` |

### client 侧

| 事实 | 依据 |
|---|---|
| 单包双半：`package.json` 同时声明 `dsh.bundle.patch` 与 `dsh.client{platform:'web'}` + `exports["./client"]`；`cordis.patch.yml` 一行 loader 插入同时带起两半（client 扫描器只扫已加载 loader 条目）；`dsh.client.inject` 是可选的**到达顺序边**（非硬依赖，web boot 的 `loader.create` 不消费），仅当 require 非 seed 包时才需要——本插件不加 | `packages/client/modules/src/index.ts:577,760`；`web/src/boot.ts:129`；`modules/src/client/system.ts:165-168` |
| client.js 产物形状：`window.__ModuleLoader__.load({id:"dsh-nightshift", factory:(require)=>{ var module={exports:{}}; var exports=module.exports; /*…*/ return module.exports }})`，classic script | `packages/client/tsdown.client.ts:566-568` |
| 可 require 的键仅平台基座：`react`、`react/jsx-runtime`、`react-dom`、`react-dom/client`、`@deepseek-ai/cordis`、`@deepseek-ai/dsh-client-store`、`@deepseek-ai/dsh-client-ui-slots`、`@deepseek-ai/dsh-client-ui-primitives` | `packages/client/web/src/platform.ts:8-14` |
| 仓库外插件自行维护 client.js 是官方承认路径（clientBundle 预设不随包发布） | `packages/client/ui-settings-plugins/README.md:96` |
| npm bundle 的 client 是**全权页面 JS**：无沙箱、无 guard 门面、React 18 与 shell 同实例、可自由同源 fetch（guard/reportRenderFailure 仅属 dynamic-cordis 路径） | `packages/extensions/cordis-client-runner/src/client/*` 对照 |
| slot 注册：client 插件 `inject:['slots']`，`ctx.slots.register({name,id?,order?,…}, Component)`；**组件永远拿不到 ctx**，只收 props。乱序激活用 `ctx.slots.inject(key, () => ctx.slots.register(...))` 包裹（声明已存在则同步执行，塌缩自动回收） | `packages/client/ui-schedule/src/client/index.ts:23-35`；`ui-renderer/src/client/registry.ts:172-234`；`packages/client/AGENTS.md:38-40` |
| 相关 slot：`conversation.input.dock`（输入框停靠，session 作用域）、`sidebar.footer.action`（侧栏底入口）、`conversation.session.header.actions`、`settings.section` | `docs/subsystems/slots.md:110-163` |
| **第三方不可用 @Remote/Typert**（贡献由根构建固定装配）；读路径用 **exact fetch route**：host `inject:['connection']` → `ctx.connection.fetch.register(route)`，路由必须在 `/api` 下且仅 GET/HEAD，自动获得 Origin/Host 围栏 + HttpHttp cookie 认证 | `packages/connection/src/rpc.ts:122-130`；`rpc-host.ts:285-296`；活例 `packages/session-query/session-log-export/src/index.ts` |
| 写路径（POST）：走**裸 webServer 路由 + handler 内自调 `connection.requestRejection` 鉴权**（webserver 本身不识 harness 概念）。已验证：`ctx.webServer.register({kind:'exact', path, handler(req,res)}) → disposer`（`packages/host/webserver/src/index.ts:42-48,165-172`；函数式插件活例 `packages/webhook/webhook-github/src/index.ts:47-62` 以 `ctx.effect(() => ctx.webServer.register(route), …)` 挂载）；鉴权 `const rejection = ctx.connection.requestRejection(req); if (rejection !== undefined) { res.writeHead(rejection); res.end(); return }`（`rejection`∈`401|403|undefined`，`packages/client/connection/src/rpc.ts:85,174-179`；调用样板原在 `packages/api/gateway/src/index.ts:211-228`——注意该处是 registerUpgrade（WebSocket mux），HTTP POST 的 requestRejection 样板即 webhook-github 组合） | `packages/api/gateway/src/index.ts:215`；`packages/webhook/webhook-github/src/index.ts` |
| 推送无第三方通道 → client 用 `useEffect+setInterval` 轮询（ui-schedule 同款） | `ui-schedule/src/client/ScheduleCatalogAction.tsx:125-130` |
| 样式：只用 `--dsw-alias-*` 语义 token（禁字面颜色/组件内明暗分支）；手写 client 自插 `<style>`、类名 `nightshift-` 前缀；物化窗口内自插的 style 会被 `claimStyles` 自动打 `data-plugin`（HMR 记账）。**token 白名单见 §10**（`fill-l2`/`label-invert` 不存在） | `docs/subsystems/web-styling.md`；`modules/src/client/system.ts:42-52` |
| i18n：第三方不依赖 dsh-client-locale（不在基座），自带字典 | 同 client 报告 |

## 3. 配置（Config schema）

```js
export const Config = Schema.object({
  timeZone: Schema.string().default('Asia/Shanghai'),        // IANA
  peakWindows: Schema.array(Schema.object({
    start: Schema.string().default('09:00'),                 // 'HH:MM' 本地墙钟
    end:   Schema.string().default('12:00'),
  })).default([{start:'09:00',end:'12:00'},{start:'14:00',end:'18:00'}]), // DeepSeek 公告峰窗
  peakPricePerMTok:   Schema.number().default(2),            // 相对单位：高峰价（README 指导填真实 CNY/Mtok）
  offPeakPricePerMTok: Schema.number().default(1),           // 低谷价
  currency: Schema.string().default('¥'),                    // 仅展示
  tickMs: Schema.number().default(30_000),                   // 峰谷检查周期
  maxRetries: Schema.number().default(3),                    // error 类重试上限
  retryBaseMs: Schema.number().default(60_000),
  retryFactor: Schema.number().default(2),
  retryMaxMs: Schema.number().default(1_800_000),            // 30min
  continuationLimit: Schema.number().default(3),             // max-tokens 自动「继续」上限
  continuationPrompt: Schema.string().default('继续'),
  drainGapMs: Schema.number().default(5_000),                // 任务间隔
  allowRunNow: Schema.boolean().default(true),               // 面板「立即跑」按钮
  reportRetentionDays: Schema.number().default(30),
  exposeTool: Schema.boolean().default(false),               // v1.1 预留，v1 不读取
})
```

## 4. 数据模型（storageDomain）

```js
import { defineDomain, domainTable } from '@deepseek-ai/dsh-storage-domain'
// zod 行 schema（版本字段 version:0；schema 演进时升 version 迁移）
const spec = defineDomain({ name: 'nightshift', version: 0, tables: {
  queue:  domainTable('string', QueueRow),   // key = task id
  reports: domainTable('string', ReportRow), // key = 'YYYY-MM-DD'
}})
```

```ts
QueueRow {
  id: string                    // `nightshift-${crypto.randomUUID()}`
  prompt: string                // 任务内容（非空，≤100KB）
  target: { mode:'continue', sessionId } | { mode:'fresh', cwd? }  // 续会话 / 新建会话（cwd 缺省 = host 默认目录，未分组来源）
  createdAt: number
  status: 'queued'|'running'|'done'|'failed'|'blocked'|'cancelled'
  attempts: number              // error 重试次数（不含 continuation）
  continuations: number         // max-tokens 续跑次数
  lastError?: string            // `${reasonKind}: ${detail}`
  lastAttemptAt?: number
  nextRetryAt?: number          // 退避到期时间戳
  tokens?: { uncachedInput, output, cacheRead, cacheWrite }   // 累计
  cost?: number             // [host 扩展] 累计实际花费（见下 rationale）
  savedVsPeak?: number      // [host 扩展] 累计省钱额
  reportedAt?: number       // [host 扩展] 已并入哪天的报告；报告去重用
  enqueueSource: 'panel'|'tool'
}

ReportRow {
  date: 'YYYY-MM-DD'            // 本地（timeZone）日期
  generatedAt: number
  window: 'off-peak'|'peak'     // 生成时所处窗口
  tasks: { total, done, failed, blocked, cancelled, retried }
  tokens: { uncachedInput, output, cacheRead, cacheWrite }
  cost: number                  // 实际花费（按执行时窗口价）
  savedVsPeak: number           // 同用量按高峰价 - 实际花费
  perTask: Array<{ id, prompt摘要(≤80字), status, tokens四桶, cost, savedVsPeak, attempts }>
}
```

**[host 扩展，已裁定入约]** QueueRow 新增可选字段 `cost`/`savedVsPeak`/`reportedAt`：报告在 turn/end **之后的另一个 tick**（甚至重启后）才生成，而跨窗口/跨重试的逐回合窗口价无法从持久化的 `tokens` 反推，故每次 turn/end 记账时把当次 delta 按**当时的窗口价**换算成钱累加进 row。`reportedAt` 用于「终态行留在队列表（面板可见/失败等人工）但不进第二天的报表」。此三项随 zod 行 schema 持久化（见 index.js queueRowSchema）。终态行的清理：报告归档后仍保留 `reportRetentionDays` 天（面板历史区可见），过期后由 `pruneHistory` 在低谷 tick 里删除（队列表有界，每 tick 全表扫描不随月数膨胀；报告表本身是长期归档）。

## 5. 队列状态机

```
queued ──drain──▶ running ──turn/end completed───▶ done
  ▲                 │└─turn/end error(≤maxRetries)─▶ queued(nextRetryAt=now+backoff)   [attempts++]
  │                 │└─turn/end error(>maxRetries)─▶ failed
  │                 │└─turn/end max-tokens(continuations<limit)─▶ running(发「继续」) [continuations++]
  │                 │└─turn/end max-tokens(≥limit)─▶ failed('max-tokens 连续截断')
  │                 │└─turn/end blocked───────────▶ blocked（面板红点，等人工）
  │                 │└─turn/end aborted───────────▶ cancelled（视为用户意图）
  │                 │└─turn/end interrupted───────▶ queued(重试，同 error 退避)
  │                 └─目标 agent 正忙──▶ 移到队尾（本轮跳过）
  └─host 重启发现 running（无在跑记录）─▶ queued（lastError='重启重排'，at-least-once 语义）
cancelled/failed/blocked/done 为终态；cancel 按钮对 queued 直接终态、对 running 先 agent.cancel(cause,{keepInbox:true}) 再置 cancelled
```

- 派发顺序：`nextRetryAt` 到期的重试任务与普通任务统一按 `createdAt` FIFO。
- **峰窗边界不抢跑**：drain 只在 tick 判定为非高峰时开始派发；派发后进入高峰，当前 running 任务**让它自然跑完**（不打断已完成的工作），之后冻结。跨窗任务照常记账（按任务结束时刻的窗口价）。

## 6. 峰谷窗口判定（lib/schedule.js）

纯函数，全部可测：

```js
// wallClockInZone(dateMs, timeZone) → { minutesOfDay, hhmm, dateKey:'YYYY-MM-DD' }（用 Intl.DateTimeFormat 解析，天然处理 DST）
// isInPeakWindow(minutesOfDay, windows) → boolean（窗口跨午夜如 22:00→06:00 必须支持环绕）
// nextTransition(nowMs, timeZone, windows) → { toWindow:'peak'|'off-peak', atMs }（下一边界时间戳）
```

- 窗口比较全部用**配置时区的墙钟分钟数**，与 host 进程本地时区无关。
- `peakWindows: []` ⇒ 永远非高峰（即随时 drain）。
- DST 间隙/重叠：仅影响墙钟读数（Intl 自动处理），判定按读到的墙钟值，无需拒绝。
- 边界含头不含尾：`[start, end)`；`start===end` 视为空窗。

## 7. drain 算法（index.js 核心）

每个 tick（`tickMs`，自递归 setTimeout）：

```
reconcile(): 重启后把孤儿 running → queued
window = schedule.isInPeak(now)
if window === peak: 记录冻结态（供面板显示），return
if 队列无到期任务(nextRetryAt<=now 或无此字段) 且 无 running: return
if 有 running 任务在本 tick 仍未终态: return（等待其 turn/end 事件驱动，不重复派发）
取队首到期任务 t:
  agent = resolveAgent(t.target)           // continue: resolveAgent(sessionId)（冷自动 resume）
                                           // fresh: sessionController.create({cwd?}) 再 resolveAgent（cwd 缺省走 host 默认）
                                           //        有 cwd 时 best-effort：workspaceRegistry.resolveByPath → attachSession（侧栏分组归属）
  if agent.status === 'running': 移到队尾, return
  before = projections.stateOf(agent.session,'tokenUsage').totals   // 快照
  t.status='running'; t.lastAttemptAt=now; table.update(t)
  agent.followup(createUserMessage({content:[{type:'text',text:t.prompt}],
                                    source:{kind:'plugin',plugin:'nightshift'}}))
```

`session/event` 监听（仅处理 `turn/end` 且 session 属于当前 running 任务）：

```
after = totals 快照; delta = after - before（四桶，clamp≥0）
ledger.record(t, delta, 当前窗口单价)
按 §5 矩阵分类处理；终态任务从 running 槽位移除
若队列清空（无 queued/running）→ 生成 ReportRow 写入 reports 表（dateKey=今天）
drainGapMs 后下一 tick 继续下一个任务
```

- token 四桶费用：`cost = (uncachedInput + output + cacheRead + cacheWrite) × price / 1e6`（cache 计价 v1 简化为同价，README 注明误差方向）。`savedVsPeak = 同用量×高峰价 − 实际`。
- 报告生成时机二选一先到者：队列清空 / 进入高峰窗。同 dateKey 已有报告则**覆盖合并**（凌晨已清空又手动跑新任务）。

## 8. HTTP API 契约

**读（exact fetch route，`ctx.connection.fetch.register`，GET）**

| 路由 | 响应 JSON |
|---|---|
| `GET /api/nightshift/state` | `{ window:'peak'\|'off-peak', nextTransitionAt:number\|null, now:number, running:TaskView\|null, queue:TaskView[], history:TaskView[], lastReport:{date,…摘要}\|null, config:{timeZone,peakWindows,peakPricePerMTok,offPeakPricePerMTok,currency,allowRunNow} }`（已验证实现；原文 `offPeakPricePerMtTok` 系笔误，与 §3 对齐为 `offPeakPricePerMTok`；空 `peakWindows` 时 `nextTransitionAt` 为 `null`；`queue` 仅含 queued 行，`history` 仅含终态行按时间倒序封顶 50 条——终审修复：host 原先只回 queued 行而 client 从 `queue` 里筛终态，历史区/徽标永远为空） |
| `GET /api/nightshift/report?date=YYYY-MM-DD` | `ReportRow`（缺省返回最新） |

`TaskView` = QueueRow 的全部字段（prompt 截断到 2000 字符返回）。响应头 `Cache-Control: no-store`。

**写（裸 webServer 路由 POST + requestRejection 鉴权；注册 API 已验证，见 §2 client 侧表）**

| 路由 | 请求 | 响应 |
|---|---|---|
| `POST /api/nightshift/enqueue` | `{prompt, target:{mode:'continue',sessionId}\|{mode:'fresh',cwd?}}` | `{ok:true, taskId}` / `{ok:false, error}` |
| `POST /api/nightshift/task/cancel` | `{taskId}` | `{ok:boolean}`（终态或 running 可取消） |
| `POST /api/nightshift/task/run-now` | `{taskId}` | `{ok:boolean}`（仅 queued；立即当 tick 处理一次，绕过峰窗判定） |

- 所有 POST：`Content-Type: application/json`；handler 首行鉴权（gateway 样板），非法→403；body 非法→400；未找到→404。
- run-now 在高峰期也执行（用户显式覆盖），报告照常按实际窗口价记账。
- 响应统一 `{ok:boolean, error?:string, …}`。
- 实现细化（已验证）：run-now 在已有 running 任务时返回 `409`（单并发不变量）；**派发闩锁**（`runtime.dispatching`）同样拒绝 run-now——drainStep 在 `resolveTargetAgent` 的 await 间隙尚未占坑，此窗口内到达的 run-now 曾会与 drain 双重派发（终审修复：后到者覆写 `runningTask`，先到任务的 token 基线永久丢失、存储行沦为孤儿 running）；`allowRunNow:false` 时返回 403；enqueue body 可带 `source:'tool'`（v1.1 工具用），缺省 `'panel'`；POST body 上限 1MB（超限 400/断开）。

## 9. host 半 index.js 结构

```js
export const name = 'nightshift'
// 已验证：v1 从 inject 移除 'tools'（exposeTool 恒 false，不注册工具，
// 声明未使用服务会让 fiber 依赖 bundle 未提供的服务而可能 strand）。
// 保留的注入项按实际用到的服务精简为：
export const inject = ['sessionController','sessionProjections',
                       'storageDomain','connection','webServer',
                       'workspaceRegistry']
// 'agents'/'sessions' 未直接用（resolveAgent/create 走 sessionController，
// 会话比对走 sessionController 返回的 agent.session）；workspaceRegistry
// 用于 fresh 会话的侧栏分组归属（resolveByPath → attachSession）。v1.1 exposeTool=true 时再加回 'tools'。

export async function apply(ctx, config) {     // 已验证：async apply 合法
  // 先例 packages/client/connection/src/index.ts:99、packages/lsp/lsp-stdio/src/index.ts:126 等。
  // storageDomain.open 是 async，故 apply 必须 async 才能 await（不可塞进非 await 的 effect）。
  const domain = await ctx.storageDomain.open(spec)
  ctx.effect(() => async () => { await domain.close() }, 'nightshift.domain')
  const tables = { queue: domain.table('queue'), reports: domain.table('reports') }
  const runtime = { runningTask: null, nextDispatchAt: 0, wasPeak: null, needsReport: false, dispatching: false, disposed: false }
  // ① 顶层 ctx.effect：tickTimer（自递归 setTimeout，tickMs，2³¹-1 钳制；disposer 置 disposed+clearTimeout）
  // ② ctx.on('session/event') → turn/end 分派（§7）
  // ③ ctx.connection.fetch.register ×2（GET 读路由）；注意 register 同步返回 async disposer
  // ④ webServer POST 路由 ×3（§8）
  // ⑤ boot reconcile + 立即首 tick
}
```

> `beforeTotals` 内联进 `runtime.runningTask`（连同 agent 一起持有），不再单独作字段；新增 `dispatching` 闩锁防 tick 与 run-now/enqueue 触发的并发 drainStep 在 resolve 的 await 间隙双派发（单并发不变量）。

- HMR 安全：apply 重入前旧实例 effect 全部回收（timer 清、domain close、监听注销——`ctx.on` 返回的 disposer 由 effect 语义自动管理）。
- **禁止**：session 级 effect 挂 timer、原地 mutate table 行对象、`setInterval`、依赖未导出的 dsh 内部深路径（如 `token-meter/turn-usage`）。

## 10. client 半 client.js 结构

```js
// 严格保持此形状（classic script，同步注册工厂）：
window.__ModuleLoader__.load({ id: "dsh-nightshift", factory: (require) => {
  var module = { exports: {} }; var exports = module.exports;
  const React = require('react')                 // seed 值是 import * as 命名空间
  const { useState, useEffect, useRef, useCallback, Fragment } = React
  const { createElement: h } = React             // 浏览器直接执行、无转译 → 禁 JSX，一律 createElement
  const { createPortal } = require('react-dom')
  const { useAnchoredPosition, useDismissOnOutsidePointer,
          IconCloseOutline16, IconPlayOutline16 } = require('@deepseek-ai/dsh-client-ui-primitives')
  // …组件定义（见下）…
  // 自插 <style id="nightshift-client-style">：全部类名 nightshift- 前缀，颜色只取已核验存在的 token
  exports.name = 'nightshift-client'
  exports.inject = ['slots']
  exports.apply = function (ctx) {
    ensureStyles()
    ctx.slots.inject('conversation.input.dock', () => ctx.slots.register(
      { name: 'conversation.input.dock', id: 'nightshift-chip', order: 30 }, NightshiftChip))
    ctx.slots.inject('sidebar.footer.action', () => ctx.slots.register(
      { name: 'sidebar.footer.action', id: 'nightshift-panel', order: 30 }, NightshiftPanelButton))
  }
  return module.exports
}})
```

**实现要点（#5/#6 已回填，`[TBD-验证]` 全部销账）**：

- **`ctx.slots.inject` 即 ui-renderer registry 的 inject**（`packages/client/ui-renderer/src/client/registry.ts:172`）：签名 `inject(key, callback) → disposer`；声明已存在则**同步**执行 callback，否则在声明方 `register()` 提交后执行，声明塌缩自动回收、再声明重放——天然容忍本插件先于 ui-conversation/ui-sidebar 激活的乱序，故 apply 用 `inject(...)` 包裹 `register` 而非直接 register。callback 内的 `ctx.slots.register` 借 cordis 服务代理把 effect 记账进**调用方 fiber**，插件卸载级联回收。
- **dock slot props 形状（原 `[TBD-验证]`）**：owner props = InputZone `{ session: SessionSnapshot, input: InputState }`（`ui-conversation/contract/slots.ts:196-200`；`ConversationRoot.tsx:274-275` 构造、:355 渲染）；`input.draft` 是 clipboard-text 投影的 **string**（`contract/input.ts:321-323`）。会话标准 kit（SessionStandardProps）额外提供 `inputActions`，其中 **`setDraft(text)`**（`contract/input.ts:221-223`）——芯片读草稿、入队成功后清空。`inputActions` 可选链调用（advisory API，失败不影响入队）。
- **侧栏 slot props**：`sidebar.footer.action` owner props 仅 `{ wide: boolean }`（`ui-sidebar/contract/slots.ts:83-86`；`SidebarRoot.tsx:214`），芯片/文字/徽标做宽窄双形态。
- **`dsh.client.inject` 字段不需要**（裁定）：该字段只是 BootModuleRow 的**到达顺序边**（`modules/src/client/system.ts:165-168` arriveGraphRow 对 row.inject 只递归 arrive、且重置环检查栈），与硬依赖（row.external——消费方物化前必须到达）不同；而 web boot 的 `loader.create({name})` 根本不传 inject（`web/src/boot.ts:129`）。本插件 require 只命中 seed 8 键，无需顺序边；cordis 服务依赖由 `exports.inject = ['slots']` 表达（`assertEntriesActive` 用 `entry.fiber.inject` 审计，boot.ts:149）。ui-schedule 带 inject 是因为它 require 了 locale/ui-conversation 等非 seed 包。故 `dsh.client` 保持 `{ platform: 'web' }` 不加 inject。
- **共享轮询层**：两 slot 组件共用一个 `createStateClient()`（单飞 in-flight 去重 + 5s 节流 + 失败保留最后快照不空白）；`useNightshiftState(active)` 挂载订阅、自适应周期（面板开 30s / 关 120s），revision 缓存保证 getSnapshot 身份稳定；HMR 重挂后从共享快照自恢复（§13.9）。
- **倒计时用服务器时间差**：`nextTransitionAt − state.now`（host 时间戳），不用 `Date.now()` 直减，避免宿主时钟漂移。
- **样式认领**：模块系统物化期间 `claimStyles`（system.ts:42-52）给无 `data-plugin` 标签的 `<style>` 自动打上插件 id——`ensureStyles()` 在 apply 首行执行（此刻在物化窗口内），自插样式天然获得 HMR 记账。
- **CSS token 白名单（已全量核验 design-platform.css 明暗两套均定义）**：label-primary/secondary/tertiary、border-l2、state-business-primary/tertiary、state-error-primary、state-success-primary、state-warn-primary/tertiary/label、interactive-bg-hover、scrollbar-bg-l2/hover-l2、specific-menu/tip、shadow-lv3。**注意**：`--dsw-alias-fill-l2`（ui-jobs 引用但主题未定义——上游 bug）与 `--dsw-alias-label-invert` **不存在**，不得使用。

组件（React 函数组件，**不接触 ctx**）：

1. **NightshiftChip**（`conversation.input.dock`）：输入框旁小芯片。props 解构 `{ session, input, inputActions }`，`session.sessionId` 作续跑目标、`input.draft` 作任务内容；点击 = POST enqueue（mode:'continue'）并 `inputActions?.setDraft('')` 清草稿；峰时显示「🌙 等低谷」，谷时显示「🚀 夜航中」+ 倒计时到下个窗口切换；旁列已排队数。无 sessionId（会话未就绪）时渲染 null。轮询始终走关闭档周期（无自身界面状态需要细粒度）。
2. **NightshiftPanelButton**（`sidebar.footer.action`）：侧栏底「夜航」入口 + 徽标（blocked/failed 数），宽窄双形态（`wide` 决定是否带文字标签）。点击开 portal 浮层（ui-schedule 的浮层模式：`useAnchoredPosition` 锚定 + `useDismissOnOutsidePointer` 外点关闭 + Escape 关闭回焦 trigger）：峰谷状态条、running 任务实时行、排队列表（状态点、重试数、立即跑/取消按钮）、终态历史、最新报告摘要（任务数/tokens/花费/省钱）。
3. 空状态文案 + 失败兜底（fetch 失败显示连接失败提示，保留最后快照不空白）。

- 轮询节流：浮层关闭时降频到 2min；state fetch 失败保留最后快照（静默重试，不空白）。
- 文案中文为主，集中放文件头 `const STR = {...}` 字典。
- 展示格式化：lib/format.js 的纯函数语义在 client 内**重实现**（client 工厂无法触达 host 的 ESM 模块图）；报告行读 `cost/savedVsPeak/tokens` 四桶全字段、`?? 0` 兜底（与 §4 host 扩展字段兼容）。

## 11. 打包与发布

```json
{
  "name": "dsh-nightshift",
  "version": "1.0.1",
  "type": "module",
  "main": "index.js",
  "files": ["index.js","client.js","lib/","cordis.patch.yml","README.md","README.zh.md","LICENSE"],
  "exports": { ".": "./index.js", "./client": "./client.js" },
  "peerDependencies": {
    "@deepseek-ai/dsh-llm": ">=0.0.1-rc.1",
    "@deepseek-ai/dsh-storage-domain": ">=0.0.1-rc.1",
    "@deepseek-ai/schemastery": ">=3.18.2",
    "zod": "^4.4.3"
  },
  "peerDependenciesMeta": { "…四项均 optional: true…": "" },
  "dependencies": {},
  "devDependencies": {
    "@deepseek-ai/dsh-llm": "0.0.1-rc.1",
    "@deepseek-ai/dsh-storage-domain": "0.0.1-rc.1",
    "@deepseek-ai/schemastery": "3.18.2",
    "vitest": "^3.2.4",
    "zod": "^4.4.3"
  },
  "scripts": { "test": "vitest run" },
  "dsh": { "bundle": { "patch": "./cordis.patch.yml" },
           "client": { "platform": "web" } }
}
```

- `cordis.patch.yml`：`- insert:\n  - id: nightshift\n    name: dsh-nightshift`
- 依赖版本 `[TBD-验证]` **已核实**（原文 `dependencies` 方案作废）：
  - `C:\code\deepseek-harness\package.json` 根为 `@deepseek-ai/dsh-root@0.1.2-alpha.3`（private）。各包 `dsh-llm`/`dsh-storage-domain` 的 **repo 版本 = 0.1.2-alpha.3**，但 `publishConfig.access:public`；**npm registry 实测只有 `0.0.1-rc.1`**（`npm view` 确认，0.1.2-alpha.3 尚未发布）。`@deepseek-ai/schemastery` 在 `vendor/schemastery`，repo 版本 **3.18.2**，npm 有 3.18.2。`zod`：repo lock pin **4.4.3**，npm 最新 4.5.4。
  - 结论：四包一律 **`peerDependencies`（optional）+ `devDependencies` 锁 repo 对齐版**。运行时不声明 `dependencies`——宿主 dsh 进程已加载这些包的**正确版本副本**，若插件自带一份会导致 cordis 服务标识、zod brand、schemastery schema **跨副本不识别**（实例身份断裂）。devDependencies 仅为本地 vitest 跑通（`import` 得到真实纯函数，不 mock @deepseek-ai/*）。`zod` 用 `^4.4.3` 兼容 minor。
  - 回退方案（若宿主拒绝 peerDeps）：README 安装章节注明「需与目标 profile 的 node_modules 共享同一份 @deepseek-ai/* 实例，故不打包依赖」，并由 install.ps1 校验宿主版本 ≥ 声明下界。
- install.ps1：把本目录 link 进目标 profile node_modules（Junction，失败则复制）→ 追加 `insert` 行到 profile 的 cordis.patch.yml → 校验 `exports['./client']` 可解析。参考 dsh-improved-inline-edit 的 install.ps1 思路（其仓库已公开）。
- README.md（英）/README.zh.md（中）双语：第一屏 = 省钱数字与产品图；安装/卸载/配置表；「与 sleep-send/session-guard/input-traffic 的差异」一节；已知限制（cache 计价简化、at-least-once、手动改配置需重启或 HMR）。

## 12. 测试要求（vitest）

- `schedule.test.js`：常规窗、跨午夜窗、午间谷、全天峰、空窗=恒谷、边界含头不含尾、`America/New_York` 3 月 DST 切换日的墙钟读数、nextTransition 正反向。
- `queue.test.js`：§5 状态机全转移矩阵（含重启 reconcile、忙 agent 移队尾、FIFO+nextRetryAt 排序）。
- `retry.test.js`：退避序列（base×2ⁿ 封顶）、jitter 有界、attempts 计数与 continuation 不混计。
- `ledger.test.js`：四桶 delta、clamp、cost/savedVsPeak、报告合并覆盖。
- `index.test.js`（mock ctx + vi.mock dsh 包）：峰转冻结不打断 running、谷转首 tick 派发、turn/end 六类 reason 分派、max-tokens 连发「继续」至上限、报告生成两触发时机、HMR 卸载清理（timer/domain/listener）。
- client 纯逻辑（lib/format.js 倒计时/数字格式）直测；React 组件不要求测。

## 13. 风险与已确认的坑（实现者必读）

1. **第三方 dsh.client 无实战先例**——client.js 格式偏差会在激活期爆 AggregateError 使 fiber FAIL。client 实现完成后**必须**先冒烟：`dsh --profile <test> --patch` 或临时 profile 装 bundle，确认 web GUI 出现芯片/面板再交付。**已于 2026-09-02 在真实 web profile 实测闭环（里程碑 #10）**：boot 图/combo bundle/全部 HTTP 路由/组件渲染全通过，日志零 AggregateError。
2. POST 路由的 webServer 注册 API 与 requestRejection 用法**已核实**（§2 client 侧表 + §9）：`ctx.webServer.register({kind:'exact',…})→disposer`，`ctx.connection.requestRejection(req)` 首行鉴权。
3. `apply` 可 async **已核实**（`packages/client/connection/src/index.ts:99` 等；storageDomain.open 需 await，故 async apply）。
4. exact fetch route 仅 GET/HEAD——写操作绝不许塞进 GET（浏览器预取会误触发）。
5. storage 行不可原地 mutate——一律 `table.put(id, newRow)` / `update`。
6. 单 setTimeout ≤ 2³¹-1ms（约 24.8 天）——tick 自递归天然规避，但 nextTransition 计算的 atMs 也要防远期一次性 setTimeout。
7. 冻结 = 不派发，**不是**冻结用户会话——不与 input-traffic/session-guard 冲突，也不依赖它们。
8. `resolveAgent` 对 subagent-origin 会话会被拒——队列目标必须是普通会话。
9. HMR：client 半边 `lib/client.js` stat-poll 触发重载，React state 会丢——组件需从轮询 state 自恢复，不依赖内存态。

## 14. 里程碑分工

| 任务 | 负责 | 产出 |
|---|---|---|
| #4 host 侧 | host 实现者 | `lib/*.js`、`index.js`、`package.json`、`cordis.patch.yml`、`[TBD-验证]` 回填报告、冒烟自测（lib 直测 + mock 调度跑通）— **已完成** |
| #5 client 侧 | client 实现者 | `client.js`、`lib/format.js`、slot props 调研回填、（有条件则）GUI 冒烟截图 — **已完成**（node --check 通过；GUI 冒烟并入 #9） |
| #6 集成 | team-lead | 接口对齐、联调、SPEC 修订落盘 — **已完成**（dsh.client.inject 裁定不加、dock/侧栏 props 形状入约、token 白名单入约、format 双侧一致性确认） |
| #7 测试 | 测试实现者 | §12 全量用例绿灯 — **已完成**（117 例全绿：ledger 15 + queue 25 + retry 6 + format 22 + schedule 19 + index 30；终审新增 state history 分离、run-now 闩锁并发、历史保留期清理 3 组回归） |
| #8 打包文档 | 文档实现者 | README×2、install.ps1、发布清单 — **已完成**（双语 README、install.ps1 过 parser 校验、MIT LICENSE） |
| #9 终审 | team-lead | 代码审查 + 验证清单 + 遗留问题 — **已完成**（client.js 全部平台 API 对照 dsh 源码逐项核验零偏差；交叉审查发现并修复三处真实缺陷：① host state 响应缺终态行而 client 从 queue 筛终态——历史区/徽标永不可见，新增 `history` 字段 + client 改读之；② run-now 与 drainStep 在 resolveTargetAgent await 间隙双重派发——run-now 补查 `dispatching` 闩锁 + dispatchNow 复查坑位；③ 终态行永不过期导致队列表无限膨胀——`pruneHistory` 按 `reportRetentionDays` 清理） |
| #10 GUI 冒烟 | team-lead | §13.1 用户 profile 实测 — **已完成**（2026-09-02，web profile 实机：boot 图含 dsh-nightshift 条目、combo 路由 200 服务 27.5KB bundle、全部 5 条 HTTP 路由实测通过（state GET/HEAD 200、report 404、enqueue→入队→cancel→history 全链路、run-now 空 taskId 400 拒绝、PUT 404）、peak 冻结确认（attempts=0）、当日报告自动生成、服务日志零错误零 AggregateError、bundle 在 headless 环境按真实 slots 契约完整走通 apply 生命周期且两个组件（nightshift-chip/nightshift-panel）以各 slot 代表性 owner props 渲染成功、全部 UI 依赖（react/react-dom/ui-primitives 三 seed + useAnchoredPosition 等 4 hooks + 2 图标）对照源码导出面核验零缺漏、中文文案完整。同轮修复 install.ps1 两处真实缺陷：profile root 误判（新增 -Profile 参数）与非法 YAML 追加（改合并式写入）） |