dsh-desktop-kit 0.0.0-stage → 2.0.0

package/plugins/dsh-gkb-ru-ui/lib/skills.js

@@ -0,0 +1,570 @@
+/**
+ * dsh-gkb-ru-ui — skills inventory and usage scanner (Host side).
+ *
+ * Pure Node module: reads `~/.dsh/skills/*\/SKILL.md`, computes per-skill file
+ * stats, and aggregates usage from session logs (zstd frames, JSONL events).
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import zlib from "node:zlib";
+
+export const CATEGORY_COLORS = {
+  design: "#0E6E5E",
+  seo: "#2C5F8A",
+  content: "#B36A43",
+  process: "#6B7275",
+  quality: "#1F7A57",
+  safety: "#94661C",
+  release: "#2C5F8A",
+  project: "#8E2B18",
+  memory: "#5B4B8A",
+  other: "#7A7F87",
+};
+
+const SKILL_CATEGORIES = {
+  "wow-design": ["design", "Дизайн"],
+  "design-critique": ["design", "Дизайн"],
+  "ui-design-system": ["design", "Дизайн"],
+  seo: ["seo", "SEO"],
+  "content-writing": ["content", "Контент"],
+  "dev-workflow": ["process", "Процесс"],
+  "requirements-and-planning": ["process", "Процесс"],
+  "skills-router": ["process", "Процесс"],
+  "context-economy": ["process", "Процесс"],
+  "requirements-and-planning": ["process", "Процесс"],
+  "testing-strategy": ["quality", "Качество"],
+  "debugging-playbook": ["quality", "Качество"],
+  "code-review-checklist": ["quality", "Качество"],
+  "database-safety": ["safety", "Данные"],
+  "security-review": ["safety", "Данные"],
+  "pg-upgrade-verify": ["safety", "Данные"],
+  "release-and-deploy": ["release", "Релиз"],
+  "git-and-ci": ["release", "Релиз"],
+  "service-desk-conventions": ["project", "Проект"],
+  "service-desk-db-safety": ["project", "Проект"],
+  "service-desk-testing": ["project", "Проект"],
+  "service-desk-release": ["project", "Проект"],
+  "service-desk-ui": ["project", "Проект"],
+  "project-deep-dive": ["memory", "Память"],
+  "project-memory-maintenance": ["memory", "Память"],
+};
+
+const ZSTD_MAGIC = Buffer.from([0x28, 0xb5, 0x2f, 0xfd]);
+const CACHE_TTL_MS = 30 * 1000;
+const CORE_TOKEN_BUDGET = 6000;
+const MAX_SKILL_BYTES = 200 * 1024;
+
+/** Rough token count for mixed Russian/English markdown. */
+export function approxTokens(bytes) {
+  return Math.max(40, Math.round(Number(bytes) / 3.2));
+}
+
+export function skillNameIsValid(name) {
+  return typeof name === "string" && /^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(name) && name.length <= 64;
+}
+
+let cache = { key: "", at: 0, data: null };
+
+export function invalidateSkillsCache() {
+  cache = { key: "", at: 0, data: null };
+}
+
+export function skillsHome() {
+  return process.env.DSH_HOME ?? path.join(os.homedir(), ".dsh");
+}
+
+function humanSize(bytes) {
+  if (bytes < 1024) return `${bytes} Б`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} КБ`;
+  if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} МБ`;
+  return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} ГБ`;
+}
+
+function unquote(value) {
+  const text = String(value).trim();
+  if ((text.startsWith('"') && text.endsWith('"')) || (text.startsWith("'") && text.endsWith("'"))) {
+    try {
+      return JSON.parse(text.startsWith("'") ? `"${text.slice(1, -1).replaceAll('"', '\\"')}"` : text);
+    } catch {
+      return text.slice(1, -1);
+    }
+  }
+  return text;
+}
+
+export function parseFrontmatter(text) {
+  const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---/u);
+  const result = { name: "", description: "", whenToUse: "", userInvocable: false };
+  if (match === null) return result;
+  for (const line of match[1].split(/\r?\n/u)) {
+    const pair = line.match(/^([A-Za-z][\w-]*):\s*(.*)$/u);
+    if (pair === null) continue;
+    const key = pair[1];
+    const value = unquote(pair[2]);
+    if (key === "name") result.name = value;
+    else if (key === "description") result.description = value;
+    else if (key === "whenToUse") result.whenToUse = value;
+    else if (key === "user-invocable") result.userInvocable = value === "true";
+  }
+  return result;
+}
+
+function walkStats(directory) {
+  let files = 0;
+  let bytes = 0;
+  let updatedAt = 0;
+  let references = 0;
+  let assets = 0;
+  const walk = (current, depth) => {
+    if (depth > 6) return;
+    let entries = [];
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name === "node_modules" || entry.name === ".git") continue;
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        if (depth === 0 && entry.name === "references") references = 1;
+        if (depth === 0 && entry.name === "assets") assets = 1;
+        walk(full, depth + 1);
+        continue;
+      }
+      try {
+        const stat = fs.statSync(full);
+        files += 1;
+        bytes += stat.size;
+        if (stat.mtimeMs > updatedAt) updatedAt = stat.mtimeMs;
+      } catch {
+        /* skip */
+      }
+    }
+  };
+  walk(directory, 0);
+  return { files, bytes, updatedAt, references, assets };
+}
+
+function firstParagraph(text) {
+  const body = text.replace(/^---[\s\S]*?---\r?\n/u, "");
+  const paragraphs = body.split(/\r?\n\s*\r?\n/u).map((item) => item.trim()).filter((item) => item.length > 0 && !item.startsWith("#") && !item.startsWith(">"));
+  const textOut = paragraphs[0] ?? "";
+  return textOut.replace(/[*_`]/gu, "").slice(0, 400);
+}
+
+export function listSkills(home = skillsHome()) {
+  const directory = path.join(home, "skills");
+  let entries = [];
+  try {
+    entries = fs.readdirSync(directory, { withFileTypes: true }).filter((entry) => entry.isDirectory());
+  } catch {
+    return [];
+  }
+  const skills = [];
+  for (const entry of entries) {
+    const skillDir = path.join(directory, entry.name);
+    const skillFile = path.join(skillDir, "SKILL.md");
+    if (!fs.existsSync(skillFile)) continue;
+    let text = "";
+    try {
+      text = fs.readFileSync(skillFile, "utf8");
+    } catch {
+      continue;
+    }
+    const front = parseFrontmatter(text);
+    const stats = walkStats(skillDir);
+    const category = SKILL_CATEGORIES[entry.name] ?? ["other", "Другое"];
+    const skillBytes = Buffer.byteLength(text, "utf8");
+    const tokens = approxTokens(skillBytes);
+    skills.push({
+      name: front.name.length > 0 ? front.name : entry.name,
+      directory: entry.name,
+      title: entry.name,
+      description: front.description.length > 0 ? front.description : firstParagraph(text),
+      whenToUse: front.whenToUse,
+      userInvocable: front.userInvocable,
+      category: category[0],
+      categoryLabel: category[1],
+      color: CATEGORY_COLORS[category[0]] ?? CATEGORY_COLORS.other,
+      files: stats.files,
+      bytes: stats.bytes,
+      skillBytes,
+      tokens,
+      heavy: tokens > CORE_TOKEN_BUDGET,
+      human: humanSize(stats.bytes),
+      updatedAt: stats.updatedAt > 0 ? new Date(stats.updatedAt).toISOString() : null,
+      references: stats.references === 1,
+      assets: stats.assets === 1,
+      path: skillDir,
+      skillFile,
+    });
+  }
+  return skills;
+}
+
+/* ------------------------------------------------------------------ */
+/* session log scanning (concatenated zstd frames with JSONL events)   */
+/* ------------------------------------------------------------------ */
+
+function decodeSessionLog(buffer) {
+  const positions = [];
+  let from = 0;
+  while (true) {
+    const index = buffer.indexOf(ZSTD_MAGIC, from);
+    if (index < 0) break;
+    positions.push(index);
+    from = index + 1;
+  }
+  if (positions.length === 0) return "";
+  const chunks = [];
+  for (let index = 0; index < positions.length; index += 1) {
+    const start = positions[index];
+    const end = positions[index + 1] ?? buffer.length;
+    try {
+      chunks.push(zlib.zstdDecompressSync(buffer.subarray(start, end)));
+    } catch {
+      /* a false magic match inside compressed data */
+    }
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+function walkSessionFiles(root) {
+  const files = [];
+  const walk = (dir, depth) => {
+    if (depth > 3) return;
+    let entries = [];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(full, depth + 1);
+      else if (entry.name.endsWith(".zstd")) files.push(full);
+    }
+  };
+  walk(root, 0);
+  return files;
+}
+
+function sessionSignature(home) {
+  const sessionDir = path.join(home, "sessions");
+  const files = walkSessionFiles(sessionDir);
+  const parts = [];
+  for (const file of files) {
+    try {
+      const stat = fs.statSync(file);
+      parts.push(`${path.basename(path.dirname(file))}:${stat.size}:${Math.floor(stat.mtimeMs)}`);
+    } catch {
+      /* ignore */
+    }
+  }
+  const skillsDir = path.join(home, "skills");
+  let skillsStamp = "";
+  try {
+    const stats = fs.readdirSync(skillsDir, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => {
+      try {
+        return `${entry.name}:${fs.statSync(path.join(skillsDir, entry.name)).mtimeMs}`;
+      } catch {
+        return entry.name;
+      }
+    });
+    skillsStamp = stats.sort().join("|");
+  } catch {
+    skillsStamp = "";
+  }
+  return { files, key: `${parts.sort().join(";")}::${skillsStamp}` };
+}
+
+function collectUsage(files) {
+  const usage = new Map();
+  const sessionsById = new Map();
+  const dayKey = (timestamp) => new Date(timestamp).toISOString().slice(0, 10);
+  for (const file of files) {
+    let text = "";
+    try {
+      text = decodeSessionLog(fs.readFileSync(file));
+    } catch {
+      continue;
+    }
+    let sessionId = path.basename(path.dirname(file));
+    let origin = "user";
+    let cwd = "";
+    for (const line of text.split(/\r?\n/u)) {
+      if (line.length === 0) continue;
+      let event;
+      try {
+        event = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      if (event.type === "session") {
+        sessionId = event.id ?? sessionId;
+        origin = event.origin ?? "user";
+        cwd = event.cwd ?? "";
+        sessionsById.set(sessionId, { sessionId, origin, cwd, createdAt: event.createdAt ?? null });
+        continue;
+      }
+      if (event.type !== "tool/call" || event.data?.name !== "skill") continue;
+      let args;
+      try {
+        args = typeof event.data.arguments === "string" ? JSON.parse(event.data.arguments) : event.data.arguments;
+      } catch {
+        args = undefined;
+      }
+      const name = typeof args?.name === "string" ? args.name : undefined;
+      if (name === undefined || name.length === 0) continue;
+      const at = Number(event.time) || null;
+      const record = usage.get(name) ?? { name, count: 0, lastAt: 0, days: new Map(), sessions: new Set() };
+      record.count += 1;
+      if (at !== null && at > record.lastAt) record.lastAt = at;
+      if (at !== null) {
+        const key = dayKey(at);
+        record.days.set(key, (record.days.get(key) ?? 0) + 1);
+      }
+      record.sessions.add(sessionId);
+      usage.set(name, record);
+    }
+  }
+  return { usage, sessionsById };
+}
+
+export function collectSkillsData(home = skillsHome(), sessionId = null) {
+  const { files, key } = sessionSignature(home);
+  const cacheKey = `${key}::${sessionId ?? ""}`;
+  const now = Date.now();
+  if (cache.data !== null && cache.key === cacheKey && now - cache.at < CACHE_TTL_MS) return cache.data;
+  const skills = listSkills(home);
+  const { usage } = collectUsage(files);
+  const today = new Date();
+  const days = [];
+  for (let index = 13; index >= 0; index -= 1) {
+    const date = new Date(today);
+    date.setDate(date.getDate() - index);
+    days.push(date.toISOString().slice(0, 10));
+  }
+  let totalRuns = 0;
+  const active = [];
+  for (const skill of skills) {
+    const record = usage.get(skill.name);
+    const series = days.map((day) => record?.days.get(day) ?? 0);
+    skill.usage = {
+      count: record?.count ?? 0,
+      lastAt: record?.lastAt ? new Date(record.lastAt).toISOString() : null,
+      sessions: record?.sessions.size ?? 0,
+      series,
+      week: series.slice(-7).reduce((sum, value) => sum + value, 0),
+      inCurrentSession: sessionId !== null && (record?.sessions.has(sessionId) ?? false),
+    };
+    totalRuns += skill.usage.count;
+    if (sessionId !== null && (record?.sessions.has(sessionId) ?? false)) {
+      active.push({ name: skill.name, lastAt: skill.usage.lastAt, count: record.count });
+    }
+  }
+  active.sort((left, right) => (right.lastAt ?? "").localeCompare(left.lastAt ?? ""));
+  const data = {
+    skills,
+    totals: {
+      skills: skills.length,
+      used: skills.filter((skill) => skill.usage.count > 0).length,
+      runs: totalRuns,
+      active: active.length,
+      tokens: skills.reduce((sum, skill) => sum + (skill.tokens || 0), 0),
+      heavy: skills.filter((skill) => skill.heavy).length,
+      references: skills.filter((skill) => skill.references).length,
+      budget: CORE_TOKEN_BUDGET,
+    },
+    active,
+    categories: Object.entries(CATEGORY_COLORS).map(([id, color]) => ({ id, label: (skills.find((skill) => skill.category === id)?.categoryLabel) ?? id, color })),
+    generatedAt: new Date().toISOString(),
+    days,
+  };
+  cache = { key: cacheKey, at: now, data };
+  return data;
+}
+
+export function readSkillContent(home, name) {
+  const skills = listSkills(home);
+  const skill = skills.find((item) => item.name === name || item.directory === name);
+  if (skill === undefined) return null;
+  let content = "";
+  try {
+    content = fs.readFileSync(skill.skillFile, "utf8");
+  } catch {
+    content = "";
+  }
+  return { ...skill, content, resources: listSkillResources(skill.path) };
+}
+
+/* ------------------------------------------------------------------ */
+/* skill studio: read resources, write, create, duplicate, archive      */
+/* ------------------------------------------------------------------ */
+
+function listSkillResources(skillDir) {
+  const resources = [];
+  const walk = (current, depth) => {
+    if (depth > 3) return;
+    let entries = [];
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name === "node_modules" || entry.name === ".git") continue;
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        walk(full, depth + 1);
+        continue;
+      }
+      if (entry.name === "SKILL.md") continue;
+      try {
+        const stat = fs.statSync(full);
+        if (!/\.(md|txt|json|ya?ml)$/u.test(entry.name)) continue;
+        resources.push({
+          path: path.relative(skillDir, full).replaceAll("\\", "/"),
+          bytes: stat.size,
+          tokens: approxTokens(stat.size),
+        });
+      } catch {
+        /* skip */
+      }
+    }
+  };
+  walk(skillDir, 0);
+  resources.sort((left, right) => right.tokens - left.tokens);
+  return resources;
+}
+
+function resolveSkill(home, name) {
+  const skills = listSkills(home);
+  return skills.find((item) => item.name === name || item.directory === name) ?? null;
+}
+
+function backupFile(home, skillFile, name) {
+  try {
+    if (!fs.existsSync(skillFile)) return null;
+    const directory = path.join(home, "skills", ".dsh-kit-backups");
+    fs.mkdirSync(directory, { recursive: true });
+    const stamp = new Date().toISOString().replace(/[:.]/gu, "-");
+    const target = path.join(directory, `${name}-${stamp}.md`);
+    fs.copyFileSync(skillFile, target);
+    return target;
+  } catch {
+    return null;
+  }
+}
+
+function assertContent(content) {
+  if (typeof content !== "string") throw Object.assign(new Error("content должен быть строкой"), { code: "skills/bad-request" });
+  const bytes = Buffer.byteLength(content, "utf8");
+  if (bytes > MAX_SKILL_BYTES) {
+    throw Object.assign(new Error(`слишком большой SKILL.md: ${bytes} байт > ${MAX_SKILL_BYTES}`), { code: "skills/too-large" });
+  }
+  const front = content.match(/^---\r?\n([\s\S]*?)\r?\n---/u);
+  if (front === null) {
+    throw Object.assign(new Error("нет frontmatter: файл должен начинаться с --- и полей name/description"), { code: "skills/bad-request" });
+  }
+  const nameLine = front[1].match(/^name:\s*(.+)$/mu);
+  if (nameLine === null) {
+    throw Object.assign(new Error("во frontmatter нет поля name"), { code: "skills/bad-request" });
+  }
+  return { bytes, frontName: unquote(nameLine[1]) };
+}
+
+export function saveSkillContent(home, name, content) {
+  const skill = resolveSkill(home, name);
+  if (skill === null) throw Object.assign(new Error(`навык «${name}» не найден`), { code: "skills/not-found" });
+  const { bytes, frontName } = assertContent(content);
+  if (frontName !== skill.directory) {
+    throw Object.assign(new Error(`поле name (${frontName}) не совпадает с папкой (${skill.directory}); переименование — через дубликат`), { code: "skills/bad-request" });
+  }
+  const backup = backupFile(home, skill.skillFile, skill.directory);
+  const temp = `${skill.skillFile}.tmp-${process.pid}-${Date.now()}`;
+  fs.writeFileSync(temp, content, "utf8");
+  fs.renameSync(temp, skill.skillFile);
+  invalidateSkillsCache();
+  return { ...readSkillContent(home, skill.name), bytes, backup, savedAt: new Date().toISOString() };
+}
+
+export function skillTemplate(name, description) {
+  return `---
+name: ${name}
+description: "${String(description ?? "").replaceAll('"', "'").slice(0, 200)}"
+whenToUse: "Когда задача совпадает с триггерами ниже"
+user-invocable: true
+---
+
+# ${name} — ядро
+
+> ≈400 токенов. Это ядро; детали — в references и только когда реально нужны.
+
+## 0. Когда применять
+- ...
+
+## 1. Главное
+1. ...
+
+## 2. Куда грузить дальше
+| Нужно | Файл | ≈токенов |
+|---|---|---|
+| ... | references/....md | ≈... |
+
+## 3. Гейт перед сдачей
+- [ ] ...
+`;
+}
+
+export function createSkill(home, payload) {
+  const name = String(payload?.name ?? "").trim();
+  if (!skillNameIsValid(name)) {
+    throw Object.assign(new Error("имя навыка: только kebab-case [a-z0-9-], до 64 символов"), { code: "skills/bad-request" });
+  }
+  const directory = path.join(home, "skills", name);
+  if (fs.existsSync(directory)) {
+    throw Object.assign(new Error(`навык «${name}» уже существует`), { code: "skills/exists" });
+  }
+  const content = typeof payload?.content === "string" && payload.content.trim().length > 0
+    ? payload.content
+    : skillTemplate(name, payload?.description);
+  assertContent(content);
+  fs.mkdirSync(directory, { recursive: true });
+  fs.writeFileSync(path.join(directory, "SKILL.md"), content, "utf8");
+  invalidateSkillsCache();
+  return readSkillContent(home, name);
+}
+
+export function duplicateSkill(home, source, nextName) {
+  const skill = resolveSkill(home, source);
+  if (skill === null) throw Object.assign(new Error(`навык «${source}» не найден`), { code: "skills/not-found" });
+  const name = String(nextName ?? "").trim();
+  if (!skillNameIsValid(name)) {
+    throw Object.assign(new Error("новое имя: только kebab-case [a-z0-9-]"), { code: "skills/bad-request" });
+  }
+  const target = path.join(home, "skills", name);
+  if (fs.existsSync(target)) throw Object.assign(new Error(`навык «${name}» уже существует`), { code: "skills/exists" });
+  fs.cpSync(skill.path, target, { recursive: true });
+  const targetFile = path.join(target, "SKILL.md");
+  const text = fs.readFileSync(targetFile, "utf8");
+  const rewritten = text.replace(/^(---\r?\n[\s\S]*?)^name:\s*.+$/mu, `$1name: ${name}`);
+  fs.writeFileSync(targetFile, rewritten, "utf8");
+  invalidateSkillsCache();
+  return readSkillContent(home, name);
+}
+
+export function deleteSkill(home, name) {
+  const skill = resolveSkill(home, name);
+  if (skill === null) throw Object.assign(new Error(`навык «${name}» не найден`), { code: "skills/not-found" });
+  const trash = path.join(home, "skills", ".dsh-kit-trash");
+  fs.mkdirSync(trash, { recursive: true });
+  const stamp = new Date().toISOString().replace(/[:.]/gu, "-");
+  const target = path.join(trash, `${stamp}-${skill.directory}`);
+  fs.renameSync(skill.path, target);
+  invalidateSkillsCache();
+  return { deleted: skill.directory, trash: target };
+}

package/plugins/dsh-gkb-ru-ui/package.json

@@ -0,0 +1,28 @@
+{
+    "name":  "dsh-gkb-ru-ui",
+    "version":  "2.0.0",
+    "description":  "Russian language pack for the DSH web GUI + compact AURORA sidebar tiles (skills/tokens/balance/spend) + Skills Studio: catalog, token cost, inline SKILL.md editor, create/duplicate/archive.",
+    "type":  "module",
+    "main":  "lib/index.js",
+    "exports":  {
+                    ".":  {
+                              "default":  "./lib/index.js"
+                          },
+                    "./client":  {
+                                     "default":  "./lib/client.js"
+                                 },
+                    "./package.json":  "./package.json"
+                },
+    "dsh":  {
+                "manifestVersion":  1,
+                "bundle":  {
+                               "patch":  "./cordis.patch.yml"
+                           },
+                "client":  {
+                               "platform":  "web",
+                               "inject":  [
+
+                                          ]
+                           }
+            }
+}

package/plugins/dsh-peak-guard/README.md

@@ -0,0 +1,70 @@
+# dsh-peak-guard — живое уведомление о пиковом тарифе DeepSeek
+
+Клиентский плагин для DeepSeek Harness: пока действует пиковый тариф (токены ×2),
+в чате над композером показывается красная карточка, а в заголовке сессии —
+компактный бейдж «Пик ×2 · осталось N мин».
+
+## Что показывает уведомление
+
+### За 5 минут до пика — жёлтое предупреждение
+
+Когда до начала пикового окна остаётся **5 минут** (настраивается константой
+`PEAK_LEAD_MS`), появляется янтарная карточка «Скоро пик ×2» и бейдж
+«Пик через N мин»: причина, время старта, живой отсчёт до начала, совет
+«завершите текущий шаг до 09:00 — или вернитесь после 13:00».
+Кнопка «Скрыть до начала пика» убирает именно предупреждение; в момент старта
+пика карточка сменится на красную (если не была скрыта уже на пик).
+
+**Плагин ничего не останавливает и не закрывает:** он только информирует.
+Сессии, история и файлы сохраняются, чат можно продолжить в любой момент.
+
+- причину: в пиковые часы цена **всех** типов токенов для `deepseek-flash` и
+  `deepseek-v4-pro` увеличивается вдвое;
+- текущее окно пика в **местном времени** и по UTC, прогресс окна;
+- **живой обратный отсчёт** до конца пика (обновляется каждую секунду);
+- рекомендацию: «Вернитесь после 13:00 (через 26 мин) — цена упадёт вдвое»;
+- расписание пика по будням и напоминание, что выходные — без пика;
+- кнопку «Скрыть на этот пик» (до конца текущего окна; в следующее окно карточка
+  появится снова) и «Расписание» для подробностей.
+
+## Расписание
+
+По референсу владельца (UTC, по будням):
+
+| Сессия | UTC | Москва (MSK) | Пекин (CST) |
+|---|---|---|---|
+| Утренняя | 01:00–04:00 | 04:00–07:00 | 09:00–12:00 |
+| Дневная | 06:00–10:00 | 09:00–13:00 | 14:00–18:00 |
+
+Всё остальное время — off-peak со скидкой 50%. Будни определяются по UTC; выходные
+пика не имеют. Государственные праздники Китая по расписанию не вычисляются.
+
+## Реальное время
+
+- тик каждую секунду: обратный отсчёт и прогресс-бар не «застывают»;
+- отдельный таймер на границу окна: карточка появляется/исчезает в момент начала
+  или конца пика (а не через полчаса);
+- при возврате фокуса/вкладки время пересчитывается сразу, даже если браузер
+  троттлил таймеры в фоне;
+- при открытии чата посреди пика карточка видна сразу.
+
+## Хранение
+
+`localStorage`:
+
+- `dsh-peak-guard:dismissed-window-end` — до какого окна скрыта карточка;
+- `dsh-peak-guard:enabled` — `0` отключает уведомления (служебное; в UI нет).
+
+## Отладка/проверка
+
+`window.__DSH_PEAK_GUARD__`:
+
+- `state()` — текущее вычисленное состояние (пик/нет, окно, остаток);
+- `preview('2026-11-04T12:34:00+03:00')` — принудительно выставить время для
+  скриншотов и проверок; `clearPreview()` — вернуть реальное время.
+
+## Ограничения
+
+- Расписание зашито в плагин; при изменении тарифов правится `WINDOWS_UTC` в
+  `client.js` (или добавляется конфиг в будущем).
+- Уведомление внутри DSH; системные push-уведомления не отправляются.