dsh-superinput 0.7.0 → 0.12.1

package/server.js

@@ -8,6 +8,7 @@ import Schema from '@deepseek-ai/schemastery'
 import { AsyncLocalStorage } from 'node:async_hooks'
 import { appendFile, mkdir, readFile, readdir, rename, stat, unlink, writeFile } from 'node:fs/promises'
 import { closeSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, utimesSync, writeSync, writeFileSync, appendFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import { dirname, join } from 'node:path'
@@ -721,6 +722,465 @@ const moduleInject = []
 /** 官方余额查询：host 白名单（安全约束——只允许官方域名，内网/环回不可能出现）。 */
 const BALANCE_HOST = 'api.deepseek.com'
 
+/* ------------------------------------------------------------------ */
+/* Coding Plan 订阅配额（对标 dsh-cost-meter lib/coding-plans.js 的      */
+/* Bearer 子集：端点/解析/降级链照抄上游，全部官方域名硬编码白名单）      */
+/* ------------------------------------------------------------------ */
+
+/** 0-100 已用百分比（保留 1 位）。 */
+const clampPct = (p) => Math.max(0, Math.min(100, Math.round(p * 10) / 10))
+
+/** 归一化百分比：0-1 视为小数，>=1 视为已是百分数；非法 → null。 */
+function normalizePercent(value) {
+  const n = Number(value)
+  if (!Number.isFinite(n) || n < 0) return null
+  return clampPct(n <= 1 ? n * 100 : n)
+}
+
+/** 归一化重置时刻：unix 秒 / 毫秒 / ISO 字符串 → ISO 字符串；非法 → ''。 */
+function normalizeResetAt(value) {
+  if (typeof value === 'string' && value.length > 0) {
+    const ms = Date.parse(value)
+    if (Number.isFinite(ms)) return new Date(ms).toISOString()
+    const asNum = Number(value)
+    if (Number.isFinite(asNum) && asNum > 0) return new Date(asNum > 1e12 ? asNum : asNum * 1000).toISOString()
+    return ''
+  }
+  const n = Number(value)
+  if (!Number.isFinite(n) || n <= 0) return ''
+  return new Date(n > 1e12 ? n : n * 1000).toISOString()
+}
+
+/** 组装文本窗口（余额等无百分比的量）：text 空 → null。 */
+const textWindowOf = (text) => {
+  const s = String(text ?? '').trim()
+  return s.length > 0 ? { resetsAt: '', text: s } : null
+}
+
+/** 单窗口：utilization（0-100 或 0-1）+ resets（unix 秒/毫秒/ISO）。 */
+function windowOf(utilization, resetsAt) {
+  const percent = normalizePercent(utilization)
+  return percent === null ? null : { percent, resetsAt: normalizeResetAt(resetsAt) }
+}
+
+/** Anthropic：{ five_hour: { utilization, resets_at }, seven_day: {...}, ... }；子配额窗口丢弃。 */
+function parseAnthropicUsage(data) {
+  if (data === null || typeof data !== 'object') return null
+  const windows = {}
+  for (const [name, raw] of Object.entries(data)) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) continue
+    if (/^(five[_ -]?hour|seven[_ -]?day)[_ -]/i.test(name)) continue
+    if (name === 'iguana_necktie') continue
+    const win = windowOf(raw.utilization ?? raw.used_percentage, raw.resets_at ?? raw.reset_at)
+    if (win !== null) windows[name] = win
+  }
+  return Object.keys(windows).length > 0 ? windows : null
+}
+
+/** Z.ai / 智谱 GLM：monitor 端点 limits 数组（unit 3=小时档/6=周档）→ plans 数组 → 扁平窗口。 */
+function parseZaiUsage(data) {
+  if (data === null || typeof data !== 'object') return null
+  const windows = {}
+  const limits = data.data !== null && typeof data.data === 'object' && Array.isArray(data.data.limits)
+    ? data.data.limits : null
+  if (limits !== null) {
+    const monWindows = {}
+    const rest = []
+    for (const limit of limits) {
+      if (limit === null || typeof limit !== 'object' || (limit.type !== 'TOKENS_LIMIT' && limit.type !== 'CREDIT_LIMIT')) continue
+      const pct = limit.percentage !== undefined ? clampPct(Number(limit.percentage))
+        : Number.isFinite(Number(limit.usage)) && Number(limit.usage) > 0 && Number.isFinite(Number(limit.currentValue))
+          ? clampPct((Number(limit.currentValue) / Number(limit.usage)) * 100)
+          : null
+      if (pct === null) continue
+      const resetsAt = normalizeResetAt(limit.nextResetTime)
+      const unit = Number(limit.unit)
+      if (unit === 3 && monWindows.fiveHour === undefined) monWindows.fiveHour = { percent: pct, resetsAt }
+      else if (unit === 6 && monWindows.weekly === undefined) monWindows.weekly = { percent: pct, resetsAt }
+      else if (!Number.isFinite(unit)) rest.push({ pct, resetsAt, resetMs: Number(limit.nextResetTime) })
+    }
+    if (rest.length > 0) {
+      rest.sort((a, b) => {
+        const av = Number.isFinite(a.resetMs) && a.resetMs > 0 ? a.resetMs : 0
+        const bv = Number.isFinite(b.resetMs) && b.resetMs > 0 ? b.resetMs : 0
+        return av - bv
+      })
+      for (const item of rest) {
+        if (monWindows.fiveHour === undefined) monWindows.fiveHour = { percent: item.pct, resetsAt: item.resetsAt }
+        else if (monWindows.weekly === undefined) monWindows.weekly = { percent: item.pct, resetsAt: item.resetsAt }
+      }
+    }
+    if (Object.keys(monWindows).length > 0) return monWindows
+  }
+  if (Array.isArray(data.plans)) {
+    for (const plan of data.plans) {
+      if (plan === null || typeof plan !== 'object') continue
+      const total = Number(plan.total_units)
+      const used = Number(plan.used_units)
+      const pct = Number.isFinite(total) && total > 0 && Number.isFinite(used)
+        ? clampPct((used / total) * 100)
+        : normalizePercent(plan.utilization ?? plan.percent ?? plan.used_percentage)
+      if (pct === null) continue
+      const spanMs = Number(plan.period_end) * 1000 - Date.now()
+      const key = Number.isFinite(spanMs) && spanMs > 24 * 3600_000 ? 'weekly' : 'fiveHour'
+      windows[key] = { percent: pct, resetsAt: normalizeResetAt(plan.period_end) }
+    }
+  }
+  for (const [name, raw] of Object.entries(data)) {
+    if (name === 'plans' || raw === null || typeof raw !== 'object' || Array.isArray(raw)) continue
+    const win = windowOf(raw.utilization ?? raw.percent ?? raw.used_percentage, raw.resets_at ?? raw.reset_at ?? raw.resetsAt)
+    if (win !== null) windows[name] = win
+  }
+  return Object.keys(windows).length > 0 ? windows : null
+}
+
+/** MiniMax 单条记录的剩余百分比（优先 *_remaining_percent，total 常为 0）。 */
+function remainingPercentOf(row, remainPctKey, totalKey, usedKey, remainKey) {
+  if (row === null || typeof row !== 'object') return null
+  const numeric = (key) => (row[key] == null || row[key] === '' ? NaN : Number(row[key]))
+  const rp = numeric(remainPctKey)
+  if (Number.isFinite(rp)) return Math.min(100, Math.max(0, rp <= 1 ? rp * 100 : rp))
+  const total = numeric(totalKey)
+  const used = numeric(usedKey)
+  const remain = numeric(remainKey)
+  if (Number.isFinite(total) && total > 0) {
+    if (Number.isFinite(remain)) return (remain / total) * 100
+    if (Number.isFinite(used)) return ((total - used) / total) * 100
+  }
+  return null
+}
+
+/** MiniMax 单条记录 → 5h/7d 窗口；status=3 为不限量，保留显式 ∞。 */
+function windowsFromMiniMaxRecord(row) {
+  if (row === null || typeof row !== 'object') return {}
+  const windows = {}
+  if (Number(row.current_interval_status) === 3) {
+    windows['5h'] = { unlimited: true, text: '∞', resetsAt: '' }
+  } else {
+    const remain = remainingPercentOf(row, 'current_interval_remaining_percent', 'current_interval_total_count', 'current_interval_usage_count', 'current_interval_remain_count')
+    if (remain !== null) {
+      windows['5h'] = { percent: clampPct(100 - remain), resetsAt: normalizeResetAt(row.end_time ?? row.reset_time ?? row.next_reset_time) }
+    }
+  }
+  if (Number(row.current_weekly_status) === 3) {
+    windows['7d'] = { unlimited: true, text: '∞', resetsAt: '' }
+  } else {
+    const remain = remainingPercentOf(row, 'current_weekly_remaining_percent', 'current_weekly_total_count', 'current_weekly_usage_count', 'current_weekly_remain_count')
+    if (remain !== null) {
+      windows['7d'] = { percent: clampPct(100 - remain), resetsAt: normalizeResetAt(row.weekly_end_time) }
+    }
+  }
+  return windows
+}
+
+/** 选 MiniMax 通用额度行：general → MiniMax-M* → 第一条可解析行。 */
+function pickMiniMaxModelRow(rows) {
+  const list = rows.filter((row) => row !== null && typeof row === 'object' && !/^(video|speech|audio|image)(?:$|[-_])/i.test(String(row.model_name ?? '')))
+  const byName = (name) => list.find((row) => String(row.model_name ?? '').toLowerCase() === name)
+  return byName('general')
+    ?? list.find((row) => /^minimax-m/i.test(String(row.model_name ?? '')))
+    ?? list.find((row) => Object.keys(windowsFromMiniMaxRecord(row)).length > 0)
+    ?? list[0]
+    ?? null
+}
+
+/** MiniMax：token_plan/remains（现行 model_remains）→ 平铺 → 旧数组形态。 */
+function parseMiniMaxRemains(data) {
+  if (data === null || typeof data !== 'object') return null
+  const payload = data.data !== null && typeof data.data === 'object' && !Array.isArray(data.data) ? data.data : data
+  const pickArray = (...keys) => {
+    for (const key of keys) {
+      if (Array.isArray(data?.[key])) return data[key]
+      if (Array.isArray(data?.data?.[key])) return data.data[key]
+    }
+    return null
+  }
+  const modelRows = pickArray('model_remains')
+  if (modelRows !== null) {
+    const fromRow = windowsFromMiniMaxRecord(pickMiniMaxModelRow(modelRows))
+    if (Object.keys(fromRow).length > 0) return fromRow
+    // 旧计数制：无 remaining_percent、靠 total>0 汇总。
+    let total = 0
+    let used = 0
+    let found = false
+    for (const item of modelRows) {
+      if (item === null || typeof item !== 'object') continue
+      const t = Number(item.current_interval_total_count ?? item.total)
+      const u = Number(item.current_interval_usage_count ?? item.used)
+      if (!Number.isFinite(t) || t <= 0) continue
+      found = true
+      total += t
+      used += Number.isFinite(u) ? u : 0
+    }
+    if (found && total > 0) return { current: { percent: clampPct((used / total) * 100), resetsAt: '' } }
+  }
+  const flat = windowsFromMiniMaxRecord(payload)
+  if (Object.keys(flat).length > 0) return flat
+  const windows = {}
+  const planRows = pickArray('token_plan_remains', 'plan_remains', 'remains', 'windows')
+  if (planRows !== null) {
+    planRows.forEach((row, index) => {
+      if (row === null || typeof row !== 'object') return
+      const total = Number(row.current_interval_total_count ?? row.total_count ?? row.total ?? row.limit)
+      const used = Number(row.current_interval_usage_count ?? row.used_count ?? row.usage_count ?? row.used)
+      const remain = Number(row.current_interval_remain_count ?? row.remain_count ?? row.remain ?? row.remaining)
+      let pct = null
+      if (Number.isFinite(total) && total > 0 && Number.isFinite(used)) pct = (used / total) * 100
+      else if (Number.isFinite(total) && total > 0 && Number.isFinite(remain)) pct = ((total - remain) / total) * 100
+      else pct = normalizePercent(row.utilization ?? row.percent ?? row.used_percentage)
+      if (pct === null) return
+      const labelRaw = row.interval ?? row.interval_type ?? row.window_type ?? row.type ?? row.name
+      const label = typeof labelRaw === 'string' && labelRaw.length > 0 ? labelRaw : `window${index + 1}`
+      windows[label] = { percent: clampPct(pct), resetsAt: normalizeResetAt(row.reset_time ?? row.resets_at ?? row.next_reset_time ?? row.reset_at) }
+    })
+  }
+  return Object.keys(windows).length > 0 ? windows : null
+}
+
+/** Kimi Code 订阅配额（api.kimi.com/coding/v1/usages，Kimi CLI 同款接口）。 */
+function parseKimiCodingUsage(data) {
+  if (data === null || typeof data !== 'object') return null
+  const payload = data.data && typeof data.data === 'object' ? data.data : data
+  const quota = payload.quota && typeof payload.quota === 'object' ? payload.quota : payload
+  const windows = {}
+  const numeric = (value) => (value == null || typeof value === 'boolean' || String(value).trim() === '' ? NaN : Number(value))
+  const counter = (row) => {
+    if (!row || typeof row !== 'object' || Array.isArray(row)) return null
+    const total = numeric(row.limit)
+    const used = numeric(row.used)
+    const remaining = numeric(row.remaining)
+    const pct = total > 0 && Number.isFinite(total)
+      ? Number.isFinite(used) && used >= 0 ? (used / total) * 100
+        : Number.isFinite(remaining) && remaining >= 0 ? ((total - remaining) / total) * 100 : NaN
+      : NaN
+    return Number.isFinite(pct) ? { percent: clampPct(pct), resetsAt: normalizeResetAt(row.resetTime ?? row.reset_time ?? row.resetAt ?? row.resetsAt) } : null
+  }
+  const usages = quota.usages ?? {}
+  const shapes = [['5h', ['limit_5h', 'limit5h']], ['weekly', ['limit_7d', 'limit7d']], ['monthly', ['limit_month_total', 'limitMonthTotal']]]
+  for (const [name, aliases] of shapes) {
+    const raw = aliases.map((key) => usages[key]).find((row) => row && typeof row === 'object' && !Array.isArray(row))
+    if (!raw) continue
+    const counted = counter(raw)
+    const ratio = numeric(raw.usedRatio ?? raw.used_ratio)
+    if (counted) windows[name] = counted
+    else if (Number.isFinite(ratio) && ratio >= 0 && ratio <= 1) {
+      windows[name] = { percent: clampPct(ratio * 100), resetsAt: normalizeResetAt(raw.resetTime ?? raw.reset_time ?? raw.resetAt) }
+    }
+  }
+  const usage = counter(quota.usage)
+  if (usage && (!Object.keys(usages).length || usages.limit_7d || usages.limit7d)) windows.weekly = usage
+  const limits = Array.isArray(quota.limits) ? quota.limits : []
+  limits.forEach((row, index) => {
+    const parsed = counter(row?.detail)
+    if (!parsed) return
+    const duration = numeric(row.window?.duration)
+    const unitRaw = String(row.window?.timeUnit ?? '').toLowerCase().replace(/^time_unit_/, '')
+    const unit = unitRaw.startsWith('hour') ? 'h' : unitRaw.startsWith('day') ? 'd'
+      : unitRaw.startsWith('week') ? 'w' : unitRaw.startsWith('minute') ? 'm'
+        : unitRaw.startsWith('month') ? 'mo' : unitRaw.slice(0, 4)
+    const name = unit === 'm' && duration === 300 ? '5h'
+      : Number.isFinite(duration) && duration > 0 && unit.length > 0 ? `${duration}${unit}` : `window${index + 1}`
+    windows[name] = parsed
+  })
+  return Object.keys(windows).length > 0 ? windows : null
+}
+
+/** Kimi / Moonshot PAYG 余额（人民币分；<100 视为已是元）。 */
+function parseKimiBalance(data) {
+  if (data === null || typeof data !== 'object') return null
+  const raw = data.available_balance ?? data.balance ?? data.cash_balance ?? data.data?.available_balance
+  const n = Number(raw)
+  if (!Number.isFinite(n) || n < 0) return null
+  const cny = n >= 100 ? n / 100 : n
+  const win = textWindowOf(`¥${(Math.round(cny * 100) / 100).toFixed(2)}`)
+  return win === null ? null : { balance: win }
+}
+
+/** OpenRouter：{ data: { total_credits, total_usage } }（美元）→ 已用%。 */
+function parseOpenRouterCredits(data) {
+  if (data === null || typeof data !== 'object') return null
+  const d = data.data !== null && typeof data.data === 'object' ? data.data : data
+  const total = Number(d.total_credits ?? d.credits)
+  const used = Number(d.total_usage ?? d.usage)
+  if (!Number.isFinite(total) || total <= 0 || !Number.isFinite(used)) return null
+  return { credits: { percent: clampPct((used / total) * 100), resetsAt: normalizeResetAt(d.resets_at ?? d.next_reset_time) } }
+}
+
+/** SiliconFlow：balance/amount/remain（人民币）→ 文本窗口。 */
+function parseSiliconFlowInfo(data) {
+  if (data === null || typeof data !== 'object') return null
+  const d = data.data !== null && typeof data.data === 'object' ? data.data : data
+  const n = Number(d.balance ?? d.amount ?? d.remain ?? d.remaining)
+  if (!Number.isFinite(n) || n < 0) return null
+  const win = textWindowOf(`¥${(Math.round(n * 100) / 100).toFixed(2)}`)
+  return win === null ? null : { balance: win }
+}
+
+/** CommandCode：windowLimits（used/cap）+ 月度 Credits 余额文本。 */
+function parseCommandCodeCredits(data) {
+  if (data === null || typeof data !== 'object') return null
+  const windows = {}
+  const limits = data.windowLimits
+  if (limits !== null && typeof limits === 'object' && !Array.isArray(limits)) {
+    for (const [name, raw] of Object.entries(limits)) {
+      if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) continue
+      const used = Number(raw.used)
+      const cap = Number(raw.cap)
+      if (!Number.isFinite(used) || !Number.isFinite(cap) || cap <= 0 || used < 0) continue
+      windows[name] = { percent: clampPct((used / cap) * 100), resetsAt: normalizeResetAt(raw.resetAt) }
+    }
+  }
+  const monthly = Number(data.credits !== null && typeof data.credits === 'object' ? data.credits.monthlyCredits : undefined)
+  if (Number.isFinite(monthly) && monthly >= 0) {
+    const win = textWindowOf(`$${(Math.round(monthly * 100) / 100).toFixed(2)}`)
+    if (win !== null) windows.monthly = win
+  }
+  return Object.keys(windows).length > 0 ? windows : null
+}
+
+/** Cline Pass：limits[].percentUsed 已是 0-100 已用百分比，不走 0-1 猜测。 */
+function parseClinePassUsage(data) {
+  if (data === null || typeof data !== 'object') return null
+  const limits = data.data !== null && typeof data.data === 'object' ? data.data.limits : undefined
+  if (!Array.isArray(limits)) return null
+  const names = new Map([['five_hour', 'fiveHour'], ['weekly', 'weekly'], ['monthly', 'monthly']])
+  const windows = {}
+  for (const entry of limits) {
+    if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) continue
+    const name = names.get(entry.type)
+    const raw = entry.percentUsed
+    const percent = typeof raw === 'number'
+      ? raw
+      : typeof raw === 'string' && /^[+-]?(\d+(\.\d+)?|\.\d+)([eE][+-]?\d+)?$/.test(raw.trim()) ? Number(raw) : Number.NaN
+    if (name === undefined || !Number.isFinite(percent) || percent < 0) continue
+    windows[name] = { percent: clampPct(percent), resetsAt: normalizeResetAt(entry.resetsAt) }
+  }
+  return Object.keys(windows).length > 0 ? windows : null
+}
+
+const CODING_PLAN_PARSERS = {
+  anthropic: parseAnthropicUsage,
+  zai: parseZaiUsage,
+  minimax: parseMiniMaxRemains,
+  openrouter: parseOpenRouterCredits,
+  siliconflow: parseSiliconFlowInfo,
+  commandcode: parseCommandCodeCredits,
+  clinepass: parseClinePassUsage,
+}
+
+/**
+ * 官方端点白名单（硬编码，配置不可改；MiniMax 是唯一例外——允许显式 HTTPS
+ * origin 覆盖，且经 normalizeMiniMaxOrigin 校验为公网域名）。顺序即降级链：
+ * 认证失败(401/403)与解析成功立即返回，其余错误换下一端点。
+ */
+const CODING_PLAN_ENDPOINTS = {
+  anthropic: ['https://api.anthropic.com/api/oauth/usage'],
+  zai: [
+    'https://open.bigmodel.cn/api/monitor/usage/quota/limit',
+    'https://api.z.ai/api/monitor/usage/quota/limit',
+    'https://api.z.ai/api/coding/paas/v3/dashboard/billing/coding_plan/usage',
+    'https://open.bigmodel.cn/api/coding/paas/v3/dashboard/billing/coding_plan/usage',
+  ],
+  minimax: [
+    'https://www.minimax.cn/v1/token_plan/remains',
+    'https://www.minimax.io/v1/token_plan/remains',
+    'https://www.minimaxi.com/v1/token_plan/remains',
+  ],
+  kimi: [
+    'https://api.kimi.com/coding/v1/usages',
+    'https://api.kimi.com/coding/v1/usage',
+    'https://api.moonshot.cn/v1/users/me/balance',
+  ],
+  openrouter: ['https://openrouter.ai/api/v1/credits'],
+  siliconflow: ['https://api.siliconflow.cn/v1/user/info'],
+  commandcode: ['https://api.commandcode.ai/alpha/billing/credits'],
+  clinepass: ['https://api.cline.bot/api/v1/users/me/plan/usage-limits'],
+}
+
+const CODING_PLAN_IDS = Object.keys(CODING_PLAN_ENDPOINTS)
+
+/**
+ * MiniMax 自定源归一化：只接受 HTTPS origin（无路径/凭据/空白），并拒绝
+ * 环回/内网/链路本地/裸 IP —— SSRF 硬化比上游更严（上游只查 HTTPS origin）。
+ */
+function normalizeMiniMaxOrigin(value) {
+  if (value === undefined || value === null || value === '') return ''
+  if (typeof value !== 'string' || value.length > 2048) return null
+  const text = value.trim()
+  if (!text) return ''
+  if (!/^https:\/\/[^/?#]+\/?$/i.test(text) || /[\s\\@?#]/.test(text)) return null
+  let url
+  try { url = new URL(text) } catch { return null }
+  const host = url.hostname.toLowerCase()
+  if (!host || url.username || url.password || url.pathname !== '/') return null
+  if (host === '::1' || host.endsWith('.local') || host.endsWith('.internal')) return null
+  if (/^(localhost|0\.|10\.|127\.|169\.254\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.)/.test(host)) return null
+  if (/^\[?[0-9a-f:]+\]?$/i.test(host) && host.includes(':')) return null
+  if (/^\d{1,3}(\.\d{1,3}){3}$/.test(host)) return null
+  return url.origin
+}
+
+/** 单端点抓取：Bearer 鉴权；Kimi 订阅端点须带官方 CLI 的 UA（上游实测约束）。 */
+async function fetchPlanJson(url, key, { kimiCoding = false, redirect } = {}) {
+  const headers = {
+    authorization: `Bearer ${key.trim()}`,
+    accept: 'application/json',
+    'user-agent': 'dsh-cost (DeepSeek Harness plugin)',
+  }
+  if (kimiCoding) headers['user-agent'] = 'KimiCLI/1.6'
+  return fetch(url, { headers, redirect, signal: AbortSignal.timeout(15_000) })
+}
+
+/** 响应体有界 JSON（256KiB 上限，防异常端点拖内存）。 */
+async function readJsonBounded(res, cap = 262_144) {
+  const text = await res.text()
+  if (text.length > cap) throw new Error('response too large')
+  return JSON.parse(text)
+}
+
+/**
+ * 查询单家 Coding Plan 额度：按白名单端点顺序尝试。401/403 与解析成功立即
+ * 定论，其余错误换下一端点；zai/minimax 双域 Key 不互通、kimi 订阅端点 401
+ * 视为「非订阅 Key」继续降级到 PAYG 余额端点（上游 issue #42/#53 同语义）。
+ * 全部错误均为 soft（未订阅/Key 无效属预期场景，面板中性提示）。
+ */
+async function queryCodingPlan(provider, key, origin) {
+  const urls = provider === 'minimax'
+    ? (() => {
+      const base = normalizeMiniMaxOrigin(origin)
+      if (base === null) throw Object.assign(new Error('minimax: invalid HTTPS origin'), { soft: true })
+      return base ? [`${base}/v1/token_plan/remains`, `${base}/v1/api/openplatform/coding_plan/remains`] : CODING_PLAN_ENDPOINTS.minimax
+    })()
+    : CODING_PLAN_ENDPOINTS[provider]
+  let lastError = 'HTTP error'
+  for (const url of urls) {
+    const kimiCoding = provider === 'kimi' && new URL(url).hostname === 'api.kimi.com'
+    let res
+    try {
+      res = await fetchPlanJson(url, key, {
+        kimiCoding,
+        redirect: provider === 'minimax' ? 'error' : provider === 'zai' ? 'manual' : undefined,
+      })
+    } catch (error) {
+      lastError = String(error?.message ?? error).slice(0, 120)
+      continue
+    }
+    if (res.status === 401 || res.status === 403) {
+      lastError = `HTTP ${res.status}`
+      if (provider === 'zai' || provider === 'minimax' || kimiCoding) continue
+      throw Object.assign(new Error(lastError), { soft: true })
+    }
+    if (!res.ok) { lastError = `HTTP ${res.status}`; continue }
+    let data = null
+    try { data = await readJsonBounded(res) } catch { lastError = 'invalid JSON response'; continue }
+    const windows = (kimiCoding ? parseKimiCodingUsage(data) : CODING_PLAN_PARSERS[provider](data))
+    if (windows) return { windows, endpoint: url }
+    lastError = 'no usage windows in response'
+  }
+  throw Object.assign(new Error(lastError), { soft: true })
+}
+
+
 const Config = Schema.object({
   enabled: Schema.boolean().default(true).description('是否启用费用统计'),
   /** 展示汇率（USD → CNY）；金额账本恒存美元，展示时换算。 */
@@ -738,6 +1198,8 @@ const Config = Schema.object({
   peakAlertNotify: Schema.boolean().default(false).description('同时发送系统通知'),
   /** DeepSeek 开放平台 API Key（选填）：配置后费用弹卡显示官方账户余额。 */
   apiKey: Schema.string().default('').description('DeepSeek 开放平台 API Key（查官方余额用，可选）'),
+  /** Coding Plan 订阅配额：{ 厂商: { key, origin? } }，Key 在费用设置页配置、不回显。 */
+  codingPlans: Schema.object({}).default({}).description('Coding Plan 订阅配额（在费用设置页配置）'),
 })
 
 function apply(ctx, config) {
@@ -749,7 +1211,7 @@ function apply(ctx, config) {
   if (!live.enabled) return
 
   // 设置持久化：只落与 config 不同的键，防抖 400ms 原子写。
-  const SETTINGS_KEYS = ['budgetEnabled', 'budgetAmount', 'budgetPeriod', 'peakAlertEnabled', 'peakAlertNotify', 'peakAlertLeadMinutes', 'exchangeRate', 'apiKey']
+  const SETTINGS_KEYS = ['budgetEnabled', 'budgetAmount', 'budgetPeriod', 'peakAlertEnabled', 'peakAlertNotify', 'peakAlertLeadMinutes', 'exchangeRate', 'apiKey', 'codingPlans']
   const SETTINGS_PATH = join(homedir(), '.dsh', 'storages', 'dsh-cost', 'settings.json')
   try {
     const saved = JSON.parse(readFileSync(SETTINGS_PATH, 'utf8'))
@@ -771,9 +1233,38 @@ function apply(ctx, config) {
     }, 400)
   }
 
+  /* -- Coding Plan 配额缓存与查询编排 -------------------------------- */
+
+  const PLAN_TTL_MS = 600_000
+  const planCache = new Map() // provider → { at, result }
+  const planKeyOf = (id) => {
+    const entry = live.codingPlans?.[id]
+    const key = typeof entry?.key === 'string' ? entry.key.trim() : ''
+    return key.length > 0 && key.length <= 4096 ? key : ''
+  }
+  async function refreshCodingPlan(id, force = false) {
+    const key = planKeyOf(id)
+    if (!key) return { hasKey: false }
+    const cached = planCache.get(id)
+    if (!force && cached && Date.now() - cached.at < PLAN_TTL_MS) return cached.result
+    let result
+    try {
+      const { windows } = await queryCodingPlan(id, key, live.codingPlans?.[id]?.origin)
+      result = { hasKey: true, windows, at: Date.now() }
+      void report(`coding plan ${id} refreshed: ${Object.keys(windows).join(',')}`)
+    } catch (error) {
+      result = { hasKey: true, error: String(error?.message ?? error).slice(0, 160), at: Date.now() }
+      void report(`coding plan ${id} refresh failed: ${result.error}`)
+    }
+    planCache.set(id, { at: Date.now(), result })
+    return result
+  }
+
   const lockPath = join(STORE_DIR, 'ledger.lock')
+  // 存储目录可能不存在（全新安装）：锁文件 openSync(wx) 要求父目录已建。
+  try { mkdirSync(STORE_DIR, { recursive: true }) } catch { /* ignore */ }
   const lock = acquireLedgerLock(lockPath)
-  void report(`server boot v0.8.2 pid=${process.pid} ledgerOwner=${lock.owner} retention=${live.retentionDays} rate=${live.exchangeRate} budget=${live.budgetEnabled ? `${live.budgetAmount}/${live.budgetPeriod}` : 'off'} backfill=${live.backfillEnabled && lock.owner ? 'on' : 'off'}`)
+  void report(`server boot v0.10.0 pid=${process.pid} ledgerOwner=${lock.owner} retention=${live.retentionDays} rate=${live.exchangeRate} budget=${live.budgetEnabled ? `${live.budgetAmount}/${live.budgetPeriod}` : 'off'} backfill=${live.backfillEnabled && lock.owner ? 'on' : 'off'} plans=${CODING_PLAN_IDS.filter((id) => planKeyOf(id)).length}`)
 
   const ledger = createLedger(live.retentionDays)
   if (lock.owner) ledger.load()
@@ -1156,7 +1647,7 @@ function apply(ctx, config) {
           const daysLeft = daysInMonth - nowDate.getDate()
           const projected = monthCost + avgDaily * daysLeft
 
-          return json({
+          send(200, {
             monthCost,
             monthCalls,
             avgDaily,
@@ -1168,6 +1659,7 @@ function apply(ctx, config) {
             basis: n >= 3 ? 'recent' : 'insufficient',
             recent,
           })
+          return
         }
 
         if (path === '/calls' && req.method === 'GET') {
@@ -1342,6 +1834,83 @@ function apply(ctx, config) {
           return
         }
 
+        // 热力图：近 N 天逐日 { cost, calls, tokens }（GitHub 贡献图样式）。
+        if (path === '/heatmap' && req.method === 'GET') {
+          const url = new URL(req.url ?? '/api/dsh-cost/heatmap', 'http://localhost')
+          const days = Math.min(365, Math.max(28, Number(url.searchParams.get('days') ?? 182)))
+          const snap = await ledgerSnapshotFresh()
+          const since = localDayKey(Date.now() - days * 86400000)
+          const rows = []
+          for (const key of Object.keys(snap.days).sort()) {
+            if (key < since) continue
+            const day = snap.days[key]
+            rows.push({
+              date: key,
+              cost: day.cost ?? 0,
+              calls: day.calls ?? 0,
+              tokens: (day.input ?? 0) + (day.output ?? 0) + (day.cacheRead ?? 0) + (day.cacheWrite ?? 0) + (day.reasoning ?? 0),
+            })
+          }
+          send(200, { days: rows })
+          return
+        }
+
+        // Coding Plan 配额：只下发窗口/错误/时间戳，Key 永不出服务端。
+        const planState = () => {
+          const providers = {}
+          for (const id of CODING_PLAN_IDS) providers[id] = { hasKey: planKeyOf(id).length > 0 }
+          for (const id of CODING_PLAN_IDS) {
+            if (!providers[id].hasKey) continue
+            const cached = planCache.get(id)
+            if (cached) providers[id] = { ...providers[id], ...cached.result, stale: Date.now() - cached.at >= PLAN_TTL_MS }
+          }
+          return providers
+        }
+        if (path === '/coding-plans' && req.method === 'GET') {
+          // 已配置且缓存过期的后台补刷：GET 不阻塞，下一轮轮询取到新值。
+          for (const id of CODING_PLAN_IDS) {
+            if (!planKeyOf(id)) continue
+            const cached = planCache.get(id)
+            if (!cached || Date.now() - cached.at >= PLAN_TTL_MS) void refreshCodingPlan(id)
+          }
+          send(200, { providers: planState() })
+          return
+        }
+        if (path === '/coding-plans/refresh' && req.method === 'POST') {
+          let raw = ''
+          for await (const chunk of req) raw += chunk
+          let body = {}
+          try { body = raw ? JSON.parse(raw) : {} } catch { send(400, { error: 'invalid-json' }); return }
+          const only = typeof body.provider === 'string' ? body.provider : ''
+          const ids = only ? [only] : CODING_PLAN_IDS.filter((id) => planKeyOf(id))
+          for (const id of ids) await refreshCodingPlan(id, true)
+          send(200, { ok: true, providers: planState() })
+          return
+        }
+        if (path === '/coding-plans/config' && req.method === 'POST') {
+          let raw = ''
+          for await (const chunk of req) raw += chunk
+          let body
+          try { body = JSON.parse(raw) } catch { send(400, { error: 'invalid-json' }); return }
+          const id = typeof body.provider === 'string' ? body.provider : ''
+          if (!CODING_PLAN_IDS.includes(id)) { send(400, { error: 'unknown-provider' }); return }
+          const key = typeof body.key === 'string' ? body.key.trim().slice(0, 4096) : ''
+          const merged = { ...(live.codingPlans ?? {}) }
+          if (key) {
+            const origin = normalizeMiniMaxOrigin(typeof body.origin === 'string' ? body.origin : undefined)
+            if (origin === null) { send(400, { error: 'invalid-origin' }); return }
+            merged[id] = origin ? { key, origin } : { key }
+          } else {
+            delete merged[id] // 空 key = 清除配置
+          }
+          live.codingPlans = merged
+          planCache.delete(id)
+          persistSettings()
+          void report(`coding plan config updated: ${id} ${key ? 'set' : 'cleared'}`)
+          send(200, { ok: true })
+          return
+        }
+
         send(404, { error: 'not-found' })
       },
     }), 'dsh-cost: /api/dsh-cost/*')
@@ -2983,6 +3552,424 @@ const Config = Schema.object({ enabled: Schema.boolean().default(true).descripti
   return { apply, Config, inject: typeof moduleInject === 'undefined' ? undefined : moduleInject }
 })()
 
+/* ==== module: compaction（原 dsh-compaction-control） ==== */
+const compactionModule = (() => {
+/* 由 scripts/build-suite.mjs 从 dsh-compaction-control/index.js 机械生成；勿手改，重跑脚本再生成。 */
+/**
+ * dsh-compaction-control — 上下文压缩控制中心（DeepSeek Harness / dsh）
+ *
+ * 三件事：
+ *   1. 手动压缩：把官方 compaction 服务的 ctx.compaction.compactNow(agent, signal)
+ *      暴露成 HTTP 路由，客户端面板一键触发（等价 /compact，免打字）。
+ *   2. 调节自动压缩：把 {auto, thresholdRatio, retainRatio} 写进每个挂载了
+ *      本插件的 profile 的用户补丁层（~/.dsh/profiles/<name>/cordis.patch.yml，
+ *      id 定向覆盖 compaction-basic 的 config；applyEntryPatches 后写者胜）。
+ *      补丁层是 initProfile 官方创建的用户文件，插件管理器不会回收它；
+ *      但 loader 只在启动时读取——保存后需重启 dsh 生效。
+ *   3. 状态源：~/.dsh/compaction-control.json 是唯一事实源（含 hideBuiltIn
+ *      等 UI 偏好），补丁文件由它派生，可随时重生成。
+ *
+ * 已核对的 dsh API（dsh-reference 源码对照）：
+ *   - ctx.agents.get(sessionId) → Agent（core/agent AgentRegistry，实现
+ *     runMaintenance，满足 compaction 的 ManualCompactAgentContext）
+ *   - ctx.compaction.compactNow(agent, signal) → CompactionResult |
+ *     null；错误带 code: busy/cancelled/changed/summary/commit/persistence
+ *   - BasicCompactionConfig 键集（compaction-basic/src/config.ts）：
+ *     auto/thresholdRatio/retainRatio/headroomTokens/maxTokens/
+ *     summarizationProvider/summarizationModel/compactionRetries/
+ *     maxOverflowRetries/modelPolicies —— 只写前三个，其余走默认
+ *   - applyEntryPatches（vendor/include）：{id, name, config} 直接整体
+ *     替换目标条目的 config；未知键会让 compaction-basic 加载即抛错，
+ *     所以这里的 config 永远是完整合法子集
+ */
+
+
+
+
+
+
+
+
+const require = createRequire(import.meta.url)
+
+const name = 'compaction-control'
+
+const DSH_DIR = join(homedir(), '.dsh')
+const PROFILES_DIR = join(DSH_DIR, 'profiles')
+const STATE_FILE = join(DSH_DIR, 'compaction-control.json')
+const DIAG_LOG = join(DSH_DIR, 'compaction-control-debug.log')
+
+/** 与 compaction-basic 的默认对齐（thresholdRatio 0.8 / retainRatio 0.16 / auto）。 */
+const DEFAULT_STATE = { auto: true, thresholdRatio: 0.8, retainRatio: 0.16, hideBuiltIn: true, checkpoint: true }
+
+const MANAGED_BEGIN = '# BEGIN dsh-compaction-control (managed)'
+const MANAGED_END = '# END dsh-compaction-control'
+
+/** 补丁文件语法校验用；运行时没带 yaml 就跳过校验（写入逻辑本身保守）。 */
+let Yaml = null
+try {
+  const mod = require('yaml')
+  if (typeof mod?.parse === 'function') Yaml = mod
+} catch { Yaml = null }
+
+const Config = Schema.object({
+  /** 关闭后客户端不再注册圆环与面板（压缩行为恢复 compaction-basic 默认）。 */
+  enabled: Schema.boolean().default(true).description('是否启用上下文压缩控制'),
+})
+
+/** 校验并归一化一份状态；不合法直接抛中文错误给面板显示。 */
+function sanitizeState(input) {
+  const ratio = (value, fallback, lo, hi, label) => {
+    const n = Number(value ?? fallback)
+    if (!Number.isFinite(n) || n < lo || n > hi) {
+      throw new Error(`${label} 需在 ${lo}~${hi} 之间`)
+    }
+    return Math.round(n * 1000) / 1000
+  }
+  const state = {
+    auto: input?.auto === undefined ? DEFAULT_STATE.auto : Boolean(input.auto),
+    thresholdRatio: ratio(input?.thresholdRatio, DEFAULT_STATE.thresholdRatio, 0.3, 0.99, '触发阈值'),
+    retainRatio: ratio(input?.retainRatio, DEFAULT_STATE.retainRatio, 0.02, 0.5, '保留比例'),
+    hideBuiltIn: input?.hideBuiltIn === undefined ? DEFAULT_STATE.hideBuiltIn : Boolean(input.hideBuiltIn),
+    checkpoint: input?.checkpoint === undefined ? DEFAULT_STATE.checkpoint : Boolean(input.checkpoint),
+  }
+  // compaction-basic 加载期硬约束：retainRatio >= thresholdRatio 直接抛错。
+  if (state.retainRatio >= state.thresholdRatio) {
+    throw new Error(`保留比例 (${state.retainRatio}) 必须小于触发阈值 (${state.thresholdRatio})`)
+  }
+  return state
+}
+
+async function readState() {
+  try {
+    return sanitizeState(JSON.parse(await readFile(STATE_FILE, 'utf8')))
+  } catch {
+    return { ...DEFAULT_STATE }
+  }
+}
+
+/** 列出挂载了本插件的 profile 名（manifest 里出现包名即算）。 */
+async function listMountedProfiles() {
+  let entries = []
+  try { entries = await readdir(PROFILES_DIR, { withFileTypes: true }) } catch { return [] }
+  const mounted = []
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue
+    try {
+      const raw = await readFile(join(PROFILES_DIR, entry.name, 'package.json'), 'utf8')
+      if (raw.includes('dsh-compaction-control')) mounted.push(entry.name)
+    } catch { /* 无 manifest 的目录不是 profile */ }
+  }
+  return mounted.sort()
+}
+
+function managedBlock(state) {
+  return [
+    MANAGED_BEGIN,
+    '- id: compaction-basic',
+    "  name: '@deepseek-ai/dsh-compaction-basic'",
+    '  config:',
+    `    auto: ${state.auto}`,
+    `    thresholdRatio: ${state.thresholdRatio}`,
+    `    retainRatio: ${state.retainRatio}`,
+    MANAGED_END,
+  ].join('\n')
+}
+
+/** 纯文本手术：由现有内容与目标状态算出下一版补丁文件内容（不落盘）。 */
+function composePatch(raw, state) {
+  const begin = raw.indexOf(MANAGED_BEGIN)
+  const end = raw.indexOf(MANAGED_END)
+  if (begin !== -1 && end !== -1 && end > begin) {
+    return raw.slice(0, begin) + managedBlock(state) + raw.slice(end + MANAGED_END.length)
+  }
+  const stripped = raw
+    .split('\n')
+    .filter((line) => line.trim() !== '' && !line.trim().startsWith('#'))
+    .join('')
+    .trim()
+  if (stripped === '[]') {
+    return raw.replace('[]', managedBlock(state))
+  }
+  if (stripped === '') {
+    return `${managedBlock(state)}\n`
+  }
+  const base = raw.replace(/\s+$/, '')
+  return `${base}\n${managedBlock(state)}\n`
+}
+
+/** 移除受管块后的剩余内容；没有受管块时返回 null（无需写回）。 */
+function stripManaged(raw) {
+  const begin = raw.indexOf(MANAGED_BEGIN)
+  const end = raw.indexOf(MANAGED_END)
+  if (begin === -1 || end === -1 || end < begin) return null
+  return raw.slice(0, begin) + raw.slice(end + MANAGED_END.length)
+}
+
+/** 官方 initProfile 的用户补丁层模板（移除后文件为空时回填）。 */
+const PATCH_TEMPLATE = '# Your patch layer for this dsh profile, applied after every bundle layer:\n'
+  + '# a top-level YAML array of loader patch entries (id-targeted config\n'
+  + '# overrides, disables, and insert lists; `!!js` expressions allowed).\n'
+  + '[]\n'
+
+/** 恢复默认：从 profile 补丁层移除受管块，让 compaction-basic 回落自身默认。 */
+async function clearProfilePatch(profileName, report) {
+  const file = join(PROFILES_DIR, profileName, 'cordis.patch.yml')
+  let raw = ''
+  try { raw = await readFile(file, 'utf8') } catch { return }
+  const strippedManaged = stripManaged(raw)
+  if (strippedManaged === null) return
+  const stripped = strippedManaged
+    .split('\n')
+    .filter((line) => line.trim() !== '' && !line.trim().startsWith('#'))
+    .join('')
+    .trim()
+  const next = stripped === ''
+    ? PATCH_TEMPLATE
+    : `${strippedManaged.replace(/\s+$/, '')}\n`
+  if (Yaml) {
+    try {
+      const parsed = Yaml.parse(next)
+      if (!Array.isArray(parsed)) throw new Error('not an array')
+    } catch (error) {
+      throw new Error(`${profileName}/cordis.patch.yml 语法校验失败，未写入：${String(error?.message ?? error)}`)
+    }
+  } else {
+    report(`yaml lib unavailable, rewrote ${profileName}/cordis.patch.yml without validation`)
+  }
+  await writeFile(file, next, 'utf8')
+  return file
+}
+
+/**
+ * 把受管块写入一个 profile 的 cordis.patch.yml。
+ * 纯文本手术：只动 BEGIN/END 标记之间的内容，用户自己写的其他条目原样保留；
+ * 全新文件（官方模板是注释 + `[]`）用受管块替换 `[]`。写前用 yaml 库校验
+ * （如果运行时带了这个库），校验失败不落盘。
+ */
+async function syncProfilePatch(profileName, state, report) {
+  const file = join(PROFILES_DIR, profileName, 'cordis.patch.yml')
+  let raw = ''
+  try { raw = await readFile(file, 'utf8') } catch { raw = '' }
+  const next = composePatch(raw, state)
+
+  if (Yaml) {
+    try {
+      const parsed = Yaml.parse(next)
+      if (!Array.isArray(parsed)) throw new Error('not an array')
+    } catch (error) {
+      throw new Error(`${profileName}/cordis.patch.yml 语法校验失败，未写入：${String(error?.message ?? error)}`)
+    }
+  } else {
+    report(`yaml lib unavailable, wrote ${profileName}/cordis.patch.yml without validation`)
+  }
+
+  await writeFile(file, next, 'utf8')
+  return file
+}
+
+/** 把状态同步进所有挂载 profile；返回写入的 profile 名单。 */
+async function syncAllProfiles(state, report) {
+  const profiles = await listMountedProfiles()
+  const written = []
+  for (const profileName of profiles) {
+    await syncProfilePatch(profileName, state, report)
+    written.push(profileName)
+  }
+  return written
+}
+
+function apply(ctx, config) {
+  const say = (message) => {
+    try { console.info(`[dsh-compaction-control] ${message}`) } catch { /* ignore */ }
+  }
+  const report = async (line) => {
+    try {
+      await mkdir(dirname(DIAG_LOG), { recursive: true })
+      await appendFile(DIAG_LOG, `${new Date().toISOString()} ${line}\n`, 'utf8')
+    } catch { /* ignore */ }
+  }
+
+  say(`server boot, enabled=${config.enabled !== false}`)
+  void report(`server boot enabled=${config.enabled !== false}`)
+
+  // 压缩前自动落档：客户端圆环在占用率上穿「阈值-5%」时布防，本进程在
+  // 该会话下一次模型调用前往消息尾追加落档指令——agent 用自己的文件工具
+  // 把项目状态写进工作区 checkpoint.md，随后 compaction-basic 照常压缩。
+  // 只注入一次（注入即解除布防；占用回落后客户端重新布防）。
+  const armedSessions = new Set()
+  const CHECKPOINT_MARKER = 'dsh-auto-checkpoint'
+  const CHECKPOINT_TEXT = [
+    '【自动落档】上下文即将压缩。请先把当前任务状态写入工作区文件 `checkpoint.md`（覆盖旧内容）：',
+    '任务目标、已完成事项、待办事项、关键决定与约束、涉及的重要文件路径。',
+    '写完落档后，再回答上一条消息的问题。（dsh-auto-checkpoint）',
+  ].join('\n')
+
+  ctx.on('agent/pre-step', async ({ agent, signal }, next) => {
+    const decision = await next()
+    try {
+      if (!decision || decision.kind !== 'enter' || !Array.isArray(decision.messages)) return decision
+      const sessionId = String(agent?.sessionId ?? '')
+      if (!sessionId || !armedSessions.has(sessionId)) return decision
+      const state = await readState()
+      if (state.checkpoint === false) { armedSessions.delete(sessionId); return decision }
+      const tail = decision.messages.slice(-3).map((m) => JSON.stringify(m?.content ?? '')).join('')
+      armedSessions.delete(sessionId)
+      if (tail.includes(CHECKPOINT_MARKER)) return decision
+      const message = createUserMessage({ content: [{ type: 'text', text: CHECKPOINT_TEXT }] })
+      await report(`checkpoint injected session=${sessionId} msgs=${decision.messages.length}`)
+      return { ...decision, messages: [...decision.messages, message] }
+    } catch (error) {
+      await report(`checkpoint pre-step failed: ${String(error?.message ?? error).slice(0, 200)}`)
+      return decision
+    }
+  })
+
+  // compaction/agents 属于可选依赖：base bundle 没带它们时路由仍注册，
+  // /compact 返回 503，面板其余功能（状态展示、参数保存）不受影响。
+  let runtime = null
+
+  ctx.inject(['webServer'], (webCtx) => {
+    webCtx.effect(() => webCtx.webServer.register({
+      kind: 'prefix',
+      path: '/api/dsh-compaction-control',
+      handler: async (req, res) => {
+        const send = (status, body) => {
+          res.statusCode = status
+          res.setHeader('content-type', 'application/json')
+          res.end(JSON.stringify(body))
+        }
+        const readBody = async () => {
+          let raw = ''
+          for await (const chunk of req) raw += chunk
+          try { return raw ? JSON.parse(raw) : {} } catch { return null }
+        }
+        const path = (req.url ?? '').split('?')[0].replace(/^\/api\/dsh-compaction-control/, '')
+
+        if (path === '/enabled' && req.method === 'GET') {
+          send(200, { enabled: config.enabled !== false, name })
+          return
+        }
+
+        if (path === '/diag' && req.method === 'POST') {
+          await report(String((await readBody())?.line ?? '').slice(0, 2000))
+          send(200, { ok: true })
+          return
+        }
+
+        // 压缩前落档布防：客户端占用率上穿阈值-5% 时 arm=true（升沿只发一次），
+        // 占用回落后 arm=false。服务端只记标记，注入发生在下一次 pre-step。
+        if (path === '/checkpoint-arm' && req.method === 'POST') {
+          const body = await readBody()
+          const sessionId = String(body?.sessionId ?? '')
+          if (!sessionId) { send(400, { error: '缺少 sessionId' }); return }
+          const arm = body?.arm === true
+          const state = await readState()
+          if (arm && state.checkpoint === false) { send(200, { ok: true, armed: false, reason: 'checkpoint-disabled' }); return }
+          if (arm) armedSessions.add(sessionId)
+          else armedSessions.delete(sessionId)
+          await report(`checkpoint ${arm ? 'armed' : 'disarmed'} session=${sessionId}`)
+          send(200, { ok: true, armed })
+          return
+        }
+
+        if (path === '/state' && req.method === 'GET') {
+          try {
+            const [state, profiles] = await Promise.all([readState(), listMountedProfiles()])
+            send(200, { ok: true, state, defaults: DEFAULT_STATE, profiles, version: '0.1.0' })
+          } catch (error) {
+            send(500, { error: String(error?.message ?? error) })
+          }
+          return
+        }
+
+        if (path === '/state' && req.method === 'POST') {
+          const body = await readBody()
+          if (body === null) { send(400, { error: '请求体不是合法 JSON' }); return }
+          try {
+            const state = sanitizeState(body)
+            await mkdir(DSH_DIR, { recursive: true })
+            await writeFile(STATE_FILE, `${JSON.stringify(state, null, 2)}\n`, 'utf8')
+            const profiles = await syncAllProfiles(state, report)
+            await report(`state saved ${JSON.stringify(state)} profiles=${profiles.join(',') || 'none'}`)
+            send(200, { ok: true, state, profiles, restartRequired: true })
+          } catch (error) {
+            send(400, { error: String(error?.message ?? error) })
+          }
+          return
+        }
+
+        if (path === '/reset' && req.method === 'POST') {
+          try {
+            const state = { ...DEFAULT_STATE }
+            await mkdir(DSH_DIR, { recursive: true })
+            await writeFile(STATE_FILE, `${JSON.stringify(state, null, 2)}\n`, 'utf8')
+            const profiles = await listMountedProfiles()
+            for (const profileName of profiles) await clearProfilePatch(profileName, report)
+            await report(`state reset to defaults, managed block removed from: ${profiles.join(',') || 'none'}`)
+            send(200, { ok: true, state, profiles, restartRequired: true })
+          } catch (error) {
+            send(400, { error: String(error?.message ?? error) })
+          }
+          return
+        }
+
+        if (path === '/compact' && req.method === 'POST') {
+          if (!runtime) { send(503, { error: '压缩服务未就绪（本 profile 未挂载 compaction/agents）' }); return }
+          const body = await readBody()
+          const sessionId = body?.sessionId
+          if (!sessionId) { send(400, { error: '缺少 sessionId' }); return }
+          const agent = runtime.agents.get(sessionId)
+          if (!agent) { send(409, { error: '未找到该会话的 agent' }); return }
+          const controller = new AbortController()
+          try {
+            const result = await runtime.compaction.compactNow(agent, controller.signal)
+            if (result === null) {
+              send(200, { ok: true, empty: true, message: '暂无可压缩的历史' })
+            } else {
+              await report(`manual compact ok: ${result.shadowedSeqs.length} items ~${result.shadowedTokenCount} tokens`)
+              send(200, {
+                ok: true,
+                shadowed: result.shadowedSeqs.length,
+                tokens: result.shadowedTokenCount,
+              })
+            }
+          } catch (error) {
+            const code = typeof error?.code === 'string' ? error.code.toLowerCase() : ''
+            const messages = {
+              busy: '会话正忙（运行中或已有压缩任务），请在空闲时重试',
+              cancelled: '压缩已取消',
+              changed: '待压缩历史在提交前发生了变化，本次已放弃并记录',
+              summary: '未能生成有效摘要，本次已记录',
+              commit: '压缩未干净完成，请检查会话状态后再试',
+              persistence: '压缩完成，但会话保存失败',
+            }
+            await report(`manual compact failed: code=${code || 'unknown'} ${String(error?.message ?? error).slice(0, 300)}`)
+            if (messages[code]) { send(409, { error: messages[code], code }); return }
+            send(500, { error: String(error?.message ?? error) })
+          }
+          return
+        }
+
+        send(404, { error: 'not-found' })
+      },
+    }), 'dsh-compaction-control: /api/dsh-compaction-control/*')
+
+    webCtx.inject(['compaction', 'agents'], (deep) => {
+      runtime = { compaction: deep.compaction, agents: deep.agents }
+      say('compaction + agents ready')
+      void report('runtime ready (compaction + agents)')
+      return () => { runtime = null }
+    })
+  })
+}
+
+
+/** 仅供离线自测（scripts/ 与 CI 可直接 import），运行时不使用。 */
+const __internals = { sanitizeState, managedBlock, composePatch, stripManaged, PATCH_TEMPLATE, DEFAULT_STATE }
+  return { apply, Config, inject: typeof moduleInject === 'undefined' ? undefined : moduleInject }
+})()
+
 /* ==== module: prompts（手写） ==== */
 const promptsModule = (() => {
 /**
@@ -2999,12 +3986,31 @@ const promptsModule = (() => {
 
 
 
+
 const moduleInject = []
 
 const STORE_DIR = join(homedir(), '.dsh', 'storages', 'dsh-superinput')
 const STORE_PATH = join(STORE_DIR, 'prompts.json')
 const CLIENT_DIAG = join(homedir(), '.dsh', 'superinput-debug.log')
 
+/* 划选上下文：客户端把「选段 + 评论」暂存到这里，下一轮 pre-step 一次性
+ * 注入成一条 sourced UserMessage，随后立即删除（只影响紧接着的一次发送）。 */
+const CONTEXT_MAX_ITEMS = 8
+const CONTEXT_TEXT_MAX = 4000
+const CONTEXT_COMMENT_MAX = 600
+const CONTEXT_TTL_MS = 10 * 60_000
+const pendingContext = new Map()
+
+function renderSelectionContext(items) {
+  const lines = [
+    '以下是我从对话中选中的上下文，按顺序附带我的评论。回答时请优先参考这些内容，并针对评论中的问题作答。',
+  ]
+  items.forEach((item, index) => {
+    lines.push(`【选段 ${index + 1}】\n${item.text}${item.comment ? `\n我的评论：${item.comment}` : ''}`)
+  })
+  return lines.join('\n\n')
+}
+
 const Config = Schema.object({
   enabled: Schema.boolean().default(true).description('启用提示词模板库'),
   maxItems: Schema.number().default(500).description('最多保存多少条模板（收藏不计入上限）'),
@@ -3196,6 +4202,36 @@ function apply(ctx, config) {
   store.load()
   ctx.effect(() => store.dispose(), 'dsh-superinput: prompts store')
 
+  // 划选上下文注入：挂在 pre-step 最前面，先让下游（含提示词增强）处理完，
+  // 再把上下文作为一条独立的 sourced 用户消息追加到本轮送模消息末尾。
+  ctx.on('agent/pre-step', async ({ agent, step, signal }, next) => {
+    const decision = await next()
+    if (decision.kind === 'reject' || signal?.aborted) return decision
+    const rawSession = agent?.session
+    const sessionId = typeof rawSession === 'string'
+      ? rawSession
+      : rawSession?.id === undefined ? '' : String(rawSession.id)
+    const pending = sessionId ? pendingContext.get(sessionId) : undefined
+    if (step !== 1 || !pending) return decision
+    pendingContext.delete(sessionId)
+    if (pending.items.length === 0 || Date.now() - pending.at > CONTEXT_TTL_MS) return decision
+    const text = renderSelectionContext(pending.items)
+    try {
+      appendFileSync(CLIENT_DIAG, `${new Date().toISOString()} context injected session=${sessionId.slice(0, 50)} items=${pending.items.length}\n`, 'utf8')
+    } catch { /* 日志失败不影响注入 */ }
+    return {
+      ...decision,
+      messages: [...decision.messages, createUserMessage({
+        content: [{ type: 'text', text }],
+        source: {
+          kind: 'dsh-superinput-selection',
+          form: 'snapshot',
+          sections: [{ name: 'selection-context', text }],
+        },
+      })],
+    }
+  }, { prepend: true })
+
   ctx.inject(['webServer'], (webCtx) => {
     webCtx.effect(() => webCtx.webServer.register({
       kind: 'prefix',
@@ -3243,6 +4279,22 @@ function apply(ctx, config) {
           send(200, { ok: true })
           return
         }
+        // 划选上下文暂存：items 为空表示清除；真正的注入在 agent/pre-step。
+        if (path === '/context' && req.method === 'POST') {
+          const body = await readBody()
+          const sessionId = String(body.sessionId ?? '').trim().slice(0, 200)
+          if (!sessionId) { send(400, { error: 'missing-session' }); return }
+          const items = Array.isArray(body.items)
+            ? body.items.slice(0, CONTEXT_MAX_ITEMS).map((item) => ({
+              text: String(item?.text ?? '').replace(/\0/g, '').trim().slice(0, CONTEXT_TEXT_MAX),
+              comment: String(item?.comment ?? '').replace(/\0/g, '').trim().slice(0, CONTEXT_COMMENT_MAX),
+            })).filter((item) => item.text.length > 0)
+            : []
+          if (items.length === 0) pendingContext.delete(sessionId)
+          else pendingContext.set(sessionId, { items, at: Date.now() })
+          send(200, { ok: true, count: items.length })
+          return
+        }
         if (path === '/list' && req.method === 'GET') {
           send(200, { items: store.list() })
           return
@@ -3379,6 +4431,7 @@ const MODULES = [
   ['followup', followupModule],
   ['voice', voiceModule],
   ['prompts', promptsModule],
+  ['compaction', compactionModule],
   ['hub', hubModule],
 ]
 
@@ -3393,6 +4446,7 @@ export const Config = Schema.object({
   followup: followupModule.Config,
   voice: voiceModule.Config,
   prompts: promptsModule.Config,
+  compaction: compactionModule.Config,
   hub: hubModule.Config,
 })