cs-bots 0.0.0-stage → 0.1.0

package/src/settings.js

@@ -0,0 +1,107 @@
+/**
+ * cs-bots /settings —— 平台设置（**持久化、且真正生效**）。
+ *
+ * 为什么单独一个文件：设置必须是**数据**而不是散落的魔法数。
+ * 本文件的键会被 `index.js` 在装配时读取并传给各域服务，因此改设置=改行为
+ *（内核级参数需重启 DSH 生效，UI 会明确标注）。
+ *
+ * 纪律：
+ *   - **零依赖**：只用 node 内置 + store.js。
+ *   - **缺文件用默认值**，坏文件**不静默**（返回 diagnostics 让 UI 显示）。
+ *   - **写入前校验**：越界值一律拒绝并给可读原因（不写半坏配置）。
+ */
+
+import { readJson, writeJsonAtomic, ensureDir, statePath } from './store.js'
+
+/** 设置项定义：默认值 + 校验。 */
+export const SETTING_SPECS = Object.freeze({
+  /** 任务默认租约时长（ms）：owner claim 后多久未心跳即视为失联。 */
+  defaultLeaseMs: { def: 5 * 60_000, min: 10_000, max: 24 * 60 * 60_000, label: '任务租约默认时长（ms）' },
+  /** 唤醒节流窗口（ms）：同一目标在窗内最多唤醒一次。 */
+  throttleMs: { def: 5_000, min: 0, max: 60 * 60_000, label: '唤醒节流窗口（ms）' },
+  /** 每目标唤醒队列上限（背压阈值）。 */
+  maxWakesPerTarget: { def: 50, min: 1, max: 1000, label: '每目标唤醒队列上限' },
+  /** 唤醒记录保留时长（ms）。 */
+  wakeTtlMs: { def: 24 * 60 * 60_000, min: 60_000, max: 30 * 24 * 60 * 60_000, label: '唤醒记录保留（ms）' },
+  /** 记忆单条上限（码点）。600 的依据：实测真实条目最长 826，ds-bot 的 300 会全拒收。 */
+  memoryEntryMax: { def: 600, min: 100, max: 10_000, label: '记忆单条上限（字符）' },
+  /** 超过该字符数的记忆条目在写入时自动切分（而非拒收）。 */
+  memorySplitOnOverflow: { def: true, bool: true, label: '记忆超长自动切分' },
+  /** K1 闸门：Bot 会话禁用 ask_user_question。关掉会让投递链有被堵风险。 */
+  k1Enabled: { def: true, bool: true, label: 'K1：Bot 禁阻塞式提问' },
+})
+
+/** 默认设置。 */
+export function defaultSettings() {
+  const out = {}
+  for (const [key, spec] of Object.entries(SETTING_SPECS)) out[key] = spec.def
+  return out
+}
+
+/**
+ * 校验单项设置。
+ * @returns {{ ok: true, value: unknown } | { ok: false, reason: string }}
+ */
+export function validateSetting(key, raw) {
+  const spec = SETTING_SPECS[key]
+  if (!spec) return { ok: false, reason: `未知设置项：${key}` }
+  if (spec.bool) {
+    if (typeof raw !== 'boolean') return { ok: false, reason: `${key} 必须是布尔值` }
+    return { ok: true, value: raw }
+  }
+  const n = Number(raw)
+  if (!Number.isFinite(n)) return { ok: false, reason: `${key} 必须是数字` }
+  if (n < spec.min || n > spec.max) {
+    return { ok: false, reason: `${key} 越界：${n} 不在 [${spec.min}, ${spec.max}]` }
+  }
+  return { ok: true, value: n }
+}
+
+/**
+ * 读取设置（缺文件/坏文件都退回默认值，并把诊断暴露出来）。
+ * @param {string} stateDir
+ * @returns {{ values: object, diagnostics: object }}
+ */
+export function loadSettings(stateDir) {
+  const file = statePath(stateDir, 'settings.json')
+  const stored = readJson(file, undefined)
+  const values = defaultSettings()
+  const diagnostics = { file, source: 'default', badKeys: [] }
+  if (stored && typeof stored === 'object') {
+    diagnostics.source = 'file'
+    for (const [key, raw] of Object.entries(stored)) {
+      const result = validateSetting(key, raw)
+      if (result.ok) values[key] = result.value
+      else diagnostics.badKeys.push({ key, raw, reason: result.reason })
+    }
+  } else if (stored !== undefined) {
+    diagnostics.source = 'invalid'
+  }
+  return { values, diagnostics }
+}
+
+/**
+ * 保存设置（只写校验过的键）。
+ * @param {string} stateDir
+ * @param {object} patch
+ * @returns {{ ok: true, values: object } | { ok: false, reason: string }}
+ */
+export function saveSettings(stateDir, patch) {
+  if (!patch || typeof patch !== 'object') return { ok: false, reason: 'patch 必须是对象' }
+  const rejected = []
+  const accepted = {}
+  for (const [key, raw] of Object.entries(patch)) {
+    const result = validateSetting(key, raw)
+    if (result.ok) accepted[key] = result.value
+    else rejected.push(result.reason)
+  }
+  if (rejected.length) return { ok: false, reason: rejected.join('；') }
+
+  if (!ensureDir(stateDir)) return { ok: false, reason: `状态目录不可写：${stateDir}` }
+  const { values } = loadSettings(stateDir)
+  const next = { ...values, ...accepted }
+  if (!writeJsonAtomic(statePath(stateDir, 'settings.json'), next)) {
+    return { ok: false, reason: '写入 settings.json 失败' }
+  }
+  return { ok: true, values: next }
+}

package/src/store.js

@@ -0,0 +1,243 @@
+/**
+ * cs-bots 存储层 —— append-only JSONL + 原子快照。
+ *
+ * 纪律（依据实测踩坑，见 `11-融合最终稿-v1.md`）：
+ *   - **按文件性质分选写策略**（K3）：状态/快照类用 `tmp → rename` 原子替换；
+ *     高频追加类**就地 append**（DS-BOT `resume.js:117-119` 原文：Windows 上
+ *     rename 会撞读，且撕裂写只丢一次重启能捡回的东西）。
+ *   - **单写者锁三段式**（照搬 DS-BOT 已验证做法）：认领失败降级 warn 不阻塞、
+ *     易主检测转只读、写前校验归属。
+ *   - **绝不静默失败**：任何丢弃都要能被调用方看见。
+ *
+ * 本文件不 import 任何 `@deepseek-ai/*`（零依赖 CI 检查 1 覆盖）。
+ */
+
+import { mkdirSync, readFileSync, writeFileSync, renameSync, appendFileSync, existsSync, rmSync, statSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+/** 确保目录存在。 */
+export function ensureDir(dir) {
+  try {
+    mkdirSync(dir, { recursive: true })
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** 读 JSON（失败返回 fallback，不抛）。 */
+export function readJson(file, fallback = undefined) {
+  try {
+    if (!existsSync(file)) return fallback
+    const text = readFileSync(file, 'utf8').trim()
+    if (!text) return fallback
+    return JSON.parse(text)
+  } catch {
+    return fallback
+  }
+}
+
+/**
+ * 原子写 JSON：`<file>.tmp-<pid>` → rename。
+ * 适用**状态/快照类**（半截 JSON 不可接受）。高频追加类请用 `appendJsonl`。
+ * @returns {boolean} 是否成功
+ */
+export function writeJsonAtomic(file, value) {
+  try {
+    ensureDir(dirname(file))
+    const tmp = `${file}.tmp-${process.pid}`
+    writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, 'utf8')
+    renameSync(tmp, file)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * 就地在文件尾追加一行 JSON（**不是**原子重写）。
+ * 适用高频追加类日志：`rooms/*.log.jsonl` / `board.jsonl` / `wakes.jsonl`。
+ * @returns {boolean} 是否成功
+ */
+export function appendJsonl(file, value) {
+  try {
+    ensureDir(dirname(file))
+    appendFileSync(file, `${JSON.stringify(value)}\n`, 'utf8')
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * 读 JSONL 全部行。坏行**不静默丢弃**：计入 `bad` 返回给调用方。
+ * @param {string} file
+ * @param {{ limit?: number }} [options] 只取最后 limit 行（limit 为 0/undefined 表示不限）
+ * @returns {{ rows: object[], bad: number, total: number }}
+ */
+export function readJsonl(file, options = {}) {
+  const result = { rows: [], bad: 0, total: 0 }
+  try {
+    if (!existsSync(file)) return result
+    let lines = readFileSync(file, 'utf8').split('\n')
+    // 末尾空行不算行
+    if (lines.length && lines[lines.length - 1] === '') lines.pop()
+    result.total = lines.length
+    if (options.limit && options.limit > 0 && lines.length > options.limit) {
+      lines = lines.slice(-options.limit)
+    }
+    for (const line of lines) {
+      if (!line.trim()) continue
+      try {
+        result.rows.push(JSON.parse(line))
+      } catch {
+        result.bad += 1
+      }
+    }
+  } catch {
+    result.bad += 1
+  }
+  return result
+}
+
+// ── 单写者锁（三段式，照搬 DS-BOT 已验证做法）────────────────────────────────
+
+/** 锁判死阈值（ms）：超过则视为上一个持有者已死。 */
+const LOCK_STALE_MS = 60_000
+/** 心跳间隔（ms）。 */
+const LOCK_HEARTBEAT_MS = 15_000
+
+/**
+ * 认领一个单写者锁。
+ *
+ * 三段式之一：**认领失败不阻塞**（DS-BOT `store.js:45-56` 原文
+ * "An unusable lock must not stop the team"）→ 返回 `{ owns: false }`，
+ * 调用方降级为只读并 warn，而不是拒绝启动。
+ *
+ * @param {string} lockFile
+ * @returns {{ owns: boolean, token: string, reason?: string }}
+ */
+export function claimLock(lockFile) {
+  const token = `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`
+  try {
+    ensureDir(dirname(lockFile))
+    if (existsSync(lockFile)) {
+      const current = readJson(lockFile, null)
+      if (current && typeof current.at === 'number' && Date.now() - current.at < LOCK_STALE_MS) {
+        // 锁仍新 → 不抢（别人在写）
+        return { owns: false, token, reason: 'held-by-other' }
+      }
+      // 锁已过期 → 视为上一个持有者已死，接管
+    }
+    writeJsonAtomic(lockFile, { token, at: Date.now(), pid: process.pid })
+    return { owns: true, token }
+  } catch (error) {
+    return { owns: false, token, reason: `claim-failed:${error?.message ?? error}` }
+  }
+}
+
+/**
+ * 校验锁是否仍归本 token 所有（三段式之三：**写前校验，失败即抛错不静默写**）。
+ * @param {string} lockFile
+ * @param {string} token
+ * @returns {boolean}
+ */
+export function ownsLock(lockFile, token) {
+  const current = readJson(lockFile, null)
+  return Boolean(current && current.token === token)
+}
+
+/**
+ * 续期心跳（三段式之二的数据基础）。
+ * @param {string} lockFile
+ * @param {string} token
+ * @returns {boolean}
+ */
+export function heartbeatLock(lockFile, token) {
+  if (!ownsLock(lockFile, token)) return false
+  return writeJsonAtomic(lockFile, { token, at: Date.now(), pid: process.pid })
+}
+
+/** 释放锁（仅当仍归本 token）。 */
+export function releaseLock(lockFile, token) {
+  try {
+    if (!ownsLock(lockFile, token)) return false
+    rmSync(lockFile, { force: true })
+    return true
+  } catch {
+    return false
+  }
+}
+
+// ── 幂等键 ──────────────────────────────────────────────────────────────────
+
+/**
+ * 幂等去重器（内存 + 可选落盘快照）。
+ * 用于「同一逻辑消息重投不改语义」——避免二次副作用。
+ */
+export class IdempotencySet {
+  /** @param {number} [max] 内存中保留的键上限（LRU 近似：超限丢最旧） */
+  constructor(max = 10_000) {
+    this.max = max
+    /** @type {Set<string>} */
+    this.keys = new Set()
+  }
+
+  /** @returns {boolean} true=首次见到（可执行）；false=重复（应跳过） */
+  check(key) {
+    if (!key) return true
+    if (this.keys.has(key)) return false
+    this.keys.add(key)
+    if (this.keys.size > this.max) {
+      const first = this.keys.values().next().value
+      this.keys.delete(first)
+    }
+    return true
+  }
+
+  has(key) {
+    return this.keys.has(key)
+  }
+
+  /** 从 JSONL 事件流重建（重启后去重仍然有效）。 */
+  rebuildFrom(rows, keyField = 'dedupKey') {
+    for (const row of rows ?? []) {
+      const k = row?.[keyField]
+      if (k) this.keys.add(k)
+    }
+    return this.keys.size
+  }
+}
+
+// ── 单调序号 ────────────────────────────────────────────────────────────────
+
+/**
+ * 从 JSONL 文件取下一个单调序号（`seq`），用于房间消息保序与断点续传。
+ * 空文件从 1 开始。
+ * @param {string} file
+ * @param {string} [field]
+ * @returns {number}
+ */
+export function nextSeq(file, field = 'seq') {
+  const { rows } = readJsonl(file)
+  let max = 0
+  for (const row of rows) {
+    const v = row?.[field]
+    if (typeof v === 'number' && v > max) max = v
+  }
+  return max + 1
+}
+
+/** 让 `statSync` 可被外部按需使用（避免调用方再 import node:fs）。 */
+export function fileMtime(file) {
+  try {
+    return statSync(file).mtimeMs
+  } catch {
+    return undefined
+  }
+}
+
+/** 拼平台状态目录下的路径。 */
+export function statePath(dir, ...parts) {
+  return join(dir, ...parts)
+}