@linxunxr/dsh-auto-archive 0.0.0-stage → 0.1.0

package/cordis.patch.yml

@@ -0,0 +1,22 @@
+# Host 插件行：定时扫描不活跃会话并归档。
+# id 同时是设置命名空间键，保持全局唯一。
+- insert:
+    - id: auto-archive
+      name: '@linxunxr/dsh-auto-archive'
+      config:
+        # 不活跃判定阈值（天）：会话最后一个事件距今超过该天数才归档。
+        idleDays: 7
+        # 扫描间隔（小时）。
+        intervalHours: 6
+        # 首次扫描前的延迟（分钟），避开启动高峰。
+        startupDelayMinutes: 5
+        # 每轮最多归档的会话数（0 = 不限）。
+        maxPerRun: 20
+        # 归档时若仍有运行中的工作是否强制停止（stopActivity）。
+        stopActivity: false
+        # 置顶会话是否豁免（建议 true）。
+        excludePinned: true
+        # 空白会话（无任何事件）是否按创建时间判定。
+        countBlankByCreation: true
+        # 只输出日志不实际归档（试运行开关）。
+        dryRun: false

package/docs/DETAIL.md

@@ -0,0 +1,35 @@
+# dsh-auto-archive
+
+定期扫描会话历史，把超过配置天数没有任何事件的会话自动归档，保持会话列表清爽。
+
+## 设置界面
+
+打开 **设置 → auto-archive** 即可直接修改全部配置项（阈值、间隔、dryRun 等），保存后立即生效并持久化，无需改文件或重启。也可以按下面的方式手动编辑 `cordis.patch.yml`，两种途径等价。
+
+## 工作方式
+
+- 通过 `ctx.sessionQuery.listSessions()` 枚举全部会话，`listEvents(id)` 取每个会话最后一个事件的时间作为"最后活跃时间"。
+- 空白会话（无任何事件）默认按 `createdAt` 判定（可关掉：`countBlankByCreation: false` 时空白会话永不归档）。
+- 已归档会话自动跳过；置顶会话默认豁免（`excludePinned: true`），因为置顶与归档互斥。
+- 归档调用官方 `ctx.workspaceRegistry.archiveSession(id, { stopActivity })`：仍有运行中工作的会话会被框架拒绝并记录跳过，不会误伤；只有显式设置 `stopActivity: true` 才会先归档再停止。
+- 归档是可逆的：在会话列表"已归档"里取消归档即可恢复原位置。
+
+## 配置（cordis.patch.yml）
+
+| 键 | 默认 | 说明 |
+|---|---|---|
+| `idleDays` | `7` | 不活跃判定阈值（天） |
+| `intervalHours` | `6` | 扫描间隔（小时） |
+| `startupDelayMinutes` | `5` | 启动后首次扫描延迟（分钟） |
+| `maxPerRun` | `20` | 每轮最多归档数（`0` 不限） |
+| `stopActivity` | `false` | 归档时是否强制停止运行中的工作 |
+| `excludePinned` | `true` | 置顶会话豁免 |
+| `countBlankByCreation` | `true` | 空白会话按创建时间判定 |
+| `dryRun` | `false` | 试运行：只记日志不实际归档 |
+
+建议首次启用时先开 `dryRun: true` 观察一轮日志，确认候选无误后再关闭。
+
+## 限制
+
+- "不活跃"以会话日志最后一个事件的时间为准；标题生成等后台小请求若写入事件，也会刷新该时间戳。
+- 只处理本机 profile 中 `sessionQuery` 可见的会话。

package/icon.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round">
+  <!-- 归档箱 -->
+  <rect x="3" y="4" width="18" height="5" rx="1.2"/>
+  <path d="M5 9v10a1.5 1.5 0 0 0 1.5 1.5h11A1.5 1.5 0 0 0 19 19V9"/>
+  <path d="M10 12.5h4"/>
+  <!-- 循环箭头（定时自动） -->
+  <path d="M20.2 6.5a8.5 8.5 0 0 1 .8 3.5" opacity="0" />
+  <path d="M12 1.8v2.6M9.2 2.6l.9 2.2M14.8 2.6l-.9 2.2" stroke-width="1.5"/>
+</svg>

package/lib/index.js

@@ -0,0 +1,164 @@
+// dsh-auto-archive — Host 插件：定期扫描不活跃会话并自动归档。
+// npm 包名 @linxunxr/dsh-auto-archive（无作用域名 dsh-auto-archive 已被他人占用）。
+//
+// 判据（对照 0.2.2-rc.3 源码验证）：
+//   - ctx.sessionQuery.listSessions() → SessionRecord[]；header 只有 createdAt
+//     （epoch ms），无 lastActivity 字段。
+//   - ctx.sessionQuery.listEvents(id) → SessionEventRecord[]（升序，带 time），
+//     取末条 time 作“最后活跃时间”；空日志视为空白会话。
+//   - ctx.workspaceRegistry.archiveSession(id, { stopActivity })：
+//     活动中的会话抛 WorkspaceActiveSessionError（安全网），
+//     不存在的会话抛 WorkspaceUnknownSessionError。
+//   - ctx.workspaceRegistry.pinnedSessionIds / archivedSessionIds：
+//     公开只读 getter（src/index.ts:360/439），用于置顶豁免与去重。
+//   - ctx.interval/ctx.timeout 来自 @deepseek-ai/cordis-plugin-timer，需注入 'timer'。
+//
+// 设置界面：DSH 0.2.x 的 Settings 页只显示“loader entry id 对应的插件所导出
+// Config 中带 volatile 标记的字段”（规则与 qq-mode-console 的注释一致）。
+// 本插件的 entry id 是 auto-archive，所以下方 Config 的全部字段都标了
+// volatile：在设置界面直接改 idleDays 等值，写入会持久化到 profile 的
+// cordis.patch.yml，插件即时生效、无需重装。普通（非 volatile）字段改配置
+// 文件才生效——这里全部做成 volatile，两种途径等价。
+import z from '@deepseek-ai/schemastery'
+
+export const name = 'dsh-auto-archive'
+
+export const inject = ['workspaceRegistry', 'sessionQuery', 'timer']
+
+const DAY_MS = 24 * 60 * 60 * 1000
+const HOUR_MS = 60 * 60 * 1000
+const MINUTE_MS = 60 * 1000
+
+// .extra('volatile', true) 与 .volatile() 等价（后者只是 DSH 自带 schemastery
+// 的语法糖）；用 .extra 写法兼容任何 schemastery 版本（qq-mode-console 的教训）。
+export const Config = z.object({
+  idleDays: z.number().min(1).max(365).step(1).default(7)
+    .description('不活跃判定阈值（天）：会话最后一个事件距今超过该天数才归档')
+    .extra('volatile', true),
+  intervalHours: z.number().min(1).max(168).step(1).default(6)
+    .description('扫描间隔（小时）')
+    .extra('volatile', true),
+  startupDelayMinutes: z.number().min(0).max(720).step(1).default(5)
+    .description('启动后首次扫描延迟（分钟）')
+    .extra('volatile', true),
+  maxPerRun: z.number().min(0).max(1000).step(1).default(20)
+    .description('每轮最多归档数（0 = 不限）')
+    .extra('volatile', true),
+  stopActivity: z.boolean().default(false)
+    .description('归档时强制停止运行中的工作（默认拒绝并跳过）')
+    .extra('volatile', true),
+  excludePinned: z.boolean().default(true)
+    .description('置顶会话豁免')
+    .extra('volatile', true),
+  countBlankByCreation: z.boolean().default(true)
+    .description('空白会话（无任何事件）按创建时间判定')
+    .extra('volatile', true),
+  dryRun: z.boolean().default(false)
+    .description('试运行：只记日志不实际归档')
+    .extra('volatile', true),
+})
+
+export function apply(ctx, config) {
+  const logger = ctx.logger('dsh-auto-archive')
+  let running = false
+
+  function errorName(error) {
+    return error && typeof error === 'object' && typeof error.constructor?.name === 'string'
+      ? error.constructor.name
+      : ''
+  }
+
+  async function runOnce() {
+    if (running) return
+    running = true
+    try {
+      // volatile 字段每次扫描时读当前值（settings 写入即时生效）。
+      const idleDays = config.idleDays.get()
+      const idleMs = idleDays * DAY_MS
+      const now = Date.now()
+      const registry = ctx.workspaceRegistry
+
+      const records = await ctx.sessionQuery.listSessions()
+      const archived = new Set(registry.archivedSessionIds.map(String))
+      const excludePinned = config.excludePinned.get()
+      const pinned = excludePinned
+        ? new Set(registry.pinnedSessionIds.map(String))
+        : new Set()
+
+      const candidates = []
+      for (const record of records) {
+        const id = String(record.header.id)
+        if (archived.has(id) || pinned.has(id)) continue
+
+        let last = null
+        try {
+          const events = await ctx.sessionQuery.listEvents(id)
+          last = events.length > 0 ? events[events.length - 1].time : null
+        } catch (error) {
+          logger.warn(`读取会话 ${id} 事件失败，跳过：${error instanceof Error ? error.message : String(error)}`)
+          continue
+        }
+
+        const anchor = last ?? (config.countBlankByCreation.get() ? record.header.createdAt : null)
+        if (anchor === null) continue
+        const idleFor = now - anchor
+        if (idleFor >= idleMs) candidates.push({ id, idleFor })
+      }
+
+      if (candidates.length === 0) {
+        logger.info(`扫描完成：${records.length} 个会话中没有满足 ${idleDays} 天不活跃的候选`)
+        return
+      }
+
+      const maxPerRun = config.maxPerRun.get()
+      const limit = maxPerRun > 0 ? maxPerRun : candidates.length
+      let archivedCount = 0
+      let skipped = 0
+      for (const candidate of candidates.slice(0, limit)) {
+        const days = Math.floor(candidate.idleFor / DAY_MS)
+        if (config.dryRun.get()) {
+          logger.info(`[dry-run] 将归档会话 ${candidate.id}（不活跃 ${days} 天）`)
+          archivedCount++
+          continue
+        }
+        try {
+          await registry.archiveSession(candidate.id, { stopActivity: config.stopPropagation.get() })
+          archivedCount++
+          logger.info(`已归档会话 ${candidate.id}（不活跃 ${days} 天）`)
+        } catch (error) {
+          skipped++
+          const kind = errorName(error)
+          if (kind === 'WorkspaceActiveSessionError') {
+            logger.info(`会话 ${candidate.id} 仍有运行中的工作，本轮跳过`)
+          } else if (kind === 'WorkspaceUnknownSessionError') {
+            logger.info(`会话 ${candidate.id} 已不存在，跳过`)
+          } else {
+            logger.warn(`归档会话 ${candidate.id} 失败：${error instanceof Error ? error.message : String(error)}`)
+          }
+        }
+      }
+      logger.info(`扫描完成：共 ${records.length} 个会话，归档 ${archivedCount} 个，跳过 ${skipped} 个`)
+    } catch (error) {
+      logger.error(`自动归档扫描失败：${error instanceof Error ? error.message : String(error)}`)
+    } finally {
+      running = false
+    }
+  }
+
+  // ctx.interval/ctx.timeout（cordis-plugin-timer）注册在当前 fiber 上，
+  // 插件卸载时自动清理；返回值同时是 disposer，稳妥起见仍显式保存。
+  const disposeInterval = ctx.interval(() => { void runOnce() }, config.intervalHours.get() * HOUR_MS)
+  const delayMinutes = config.startupDelayMinutes.get()
+  const disposeInitial = delayMinutes > 0
+    ? ctx.timeout(() => { void runOnce() }, delayMinutes * MINUTE_MS)
+    : null
+
+  logger.info(
+    `dsh-auto-archive 已加载：idleDays=${config.idleDays.get()} intervalHours=${config.intervalHours.get()} maxPerRun=${config.maxPerRun.get()} dryRun=${config.dryRun.get()}`,
+  )
+
+  return () => {
+    disposeInterval()
+    disposeInitial?.()
+  }
+}

package/locale/en.json

@@ -0,0 +1,7 @@
+{
+  "meta": {
+    "title": "Auto-archive idle sessions",
+    "description": "Periodically archives sessions whose last event is older than a configured number of days. Pinned and already-archived sessions are skipped, and sessions with running work are never force-stopped unless enabled.",
+    "detail": "docs/DETAIL.md"
+  }
+}

package/locale/zh.json

@@ -0,0 +1,7 @@
+{
+  "meta": {
+    "title": "不活跃会话自动归档",
+    "description": "定期扫描并归档超过设定天数没有任何事件的会话。置顶与已归档会话自动豁免；仍有运行中工作的会话默认不会被强制停止（可在配置中开启）。",
+    "detail": "docs/DETAIL.md"
+  }
+}

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@linxunxr/dsh-auto-archive",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Auto-archive idle sessions: periodically archives unarchived sessions with no events for a configured number of days",
+  "type": "module",
+  "main": "./lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "engines": {
+    "dsh": ">=0.2.2-rc.1 <0.3.0"
+  },
+  "files": [
+    "lib",
+    "locale",
+    "docs",
+    "icon.svg",
+    "cordis.patch.yml"
+  ],
+  "license": "MIT"
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.