@dsh-plus/lifeboat 0.1.3 → 0.1.5

package/src/client/health-tab.tsx

@@ -0,0 +1,303 @@
+/**
+ * lifeboat 健康页：settings.plugins.tab 第三页「救生艇」。
+ * - 应急翻译状态 banner（激活中显示源路由/临时路由/时间）
+ * - 已隔离插件卡片 + 「恢复」按钮（两段确认）
+ * - journal 时间线（kind 徽标着色）
+ * - dsh-plus 兄弟插件状态点（pluginInventory.list）
+ * 依赖隔离：本模块被 client.ts 延迟 require，react 系异常不拖垮哨兵。
+ * @module lifeboat/client/health-tab
+ */
+
+import { getJson, postJson } from '@dsh-plus/shared/client'
+import { type ReactElement, useCallback, useEffect, useMemo, useState } from 'react'
+
+import { injectHealthStyle } from './health-styles.ts'
+
+interface JournalEntry {
+  at: string
+  kind: string
+  detail: string
+}
+
+interface FallbackState {
+  active: boolean
+  originalProvider: string
+  originalModel: string
+  fallbackProvider: string
+  at: string
+}
+
+interface StatusResponse {
+  journal: JournalEntry[]
+  llmFallback: FallbackState | null
+  quarantined: string[]
+}
+
+interface InventoryRow {
+  id: string
+  enabled: boolean
+  status?: number
+}
+
+interface RemoteLike {
+  pluginInventory: { list(): Promise<{ entries?: InventoryRow[] }> }
+}
+
+interface SlotsLike {
+  inject(key: string, callback: () => unknown): unknown
+  register(options: Record<string, unknown>, component: unknown): () => void
+}
+
+interface LocaleLike {
+  register(ns: string, dict: { zh: Record<string, string>; en: Record<string, string> }): () => void
+  bind(ns: string): (key: string) => string
+}
+
+interface HealthContext {
+  slots: SlotsLike
+  locale: LocaleLike
+  get(key: 'remote'): RemoteLike
+  effect(execute: () => () => void, label?: string): unknown
+}
+
+const NS = 'dsh-plus-lifeboat'
+const ROUTE_STATUS = '/dsh-plus/lifeboat/status'
+const ROUTE_RESTORE = '/dsh-plus/lifeboat/restore'
+
+/** journal kind → 徽标语义色。 */
+const KIND_STYLES: Record<string, string> = {
+  alert: 'dlb-kindAlert',
+  quarantine: 'dlb-kindQuarantine',
+  'quarantine-restore': 'dlb-kindRestore',
+  'llm-fallback': 'dlb-kindFallback',
+  'llm-fallback-revert': 'dlb-kindRestore',
+}
+
+const zhDict = {
+  tab: '救生艇',
+  fallbackActive: 'LLM 应急翻译进行中',
+  fallbackFrom: '源路由',
+  fallbackTo: '临时路由',
+  fallbackAt: '启用时间',
+  quarantined: '已隔离插件',
+  restore: '恢复',
+  restoring: '恢复中…',
+  restoreConfirm: '确认恢复该插件？将移除用户 patch 层的禁用覆盖，热应用即时生效。',
+  journalTitle: '操作日志',
+  pluginsTitle: 'dsh-plus 插件状态',
+  pluginFailed: 'FAILED',
+  pluginOk: '正常',
+  pluginDisabled: '已禁用',
+  emptyJournal: '暂无记录。',
+  emptyQuarantined: '当前无隔离插件。',
+  loadFailed: '状态加载失败：',
+  retry: '重试',
+  restored: '已恢复，热应用即时生效。',
+  restoreFailed: '恢复失败：',
+}
+
+const enDict = {
+  tab: 'Lifeboat',
+  fallbackActive: 'LLM emergency translation active',
+  fallbackFrom: 'Source route',
+  fallbackTo: 'Fallback route',
+  fallbackAt: 'Since',
+  quarantined: 'Quarantined plugins',
+  restore: 'Restore',
+  restoring: 'Restoring…',
+  restoreConfirm:
+    'Restore this plugin? The disable override in the user patch layer will be removed and hot-applied.',
+  journalTitle: 'Journal',
+  pluginsTitle: 'dsh-plus plugin status',
+  pluginFailed: 'FAILED',
+  pluginOk: 'OK',
+  pluginDisabled: 'Disabled',
+  emptyJournal: 'No entries yet.',
+  emptyQuarantined: 'No quarantined plugins.',
+  loadFailed: 'Failed to load: ',
+  retry: 'Retry',
+  restored: 'Restored; hot-applied immediately.',
+  restoreFailed: 'Restore failed: ',
+}
+
+function HealthTab(props: { t(key: string): string }): ReactElement {
+  const { t } = props
+  const [status, setStatus] = useState<StatusResponse | null>(null)
+  const [failed, setFailed] = useState(false)
+  const [busyName, setBusyName] = useState<string | null>(null)
+  const [notice, setNotice] = useState<string | null>(null)
+  const [confirming, setConfirming] = useState<string | null>(null)
+
+  const load = useCallback((): void => {
+    getJson<StatusResponse>(ROUTE_STATUS)
+      .then((data) => {
+        setStatus(data)
+        setFailed(false)
+      })
+      .catch(() => setFailed(true))
+  }, [])
+
+  useEffect(() => {
+    load()
+  }, [load])
+
+  const onRestore = (name: string): void => {
+    setBusyName(name)
+    setConfirming(null)
+    postJson<{ ok: boolean; error?: string }>(ROUTE_RESTORE, { name })
+      .then(() => {
+        setNotice(t('restored'))
+        load()
+      })
+      .catch((error: unknown) => {
+        setNotice(`${t('restoreFailed')}${error instanceof Error ? error.message : ''}`)
+      })
+      .finally(() => setBusyName(null))
+  }
+
+  const journalGroups = useMemo(() => {
+    if (status === null) return []
+    const groups = new Map<string, JournalEntry[]>()
+    for (const entry of [...status.journal].reverse()) {
+      const day = entry.at.slice(0, 10)
+      const list = groups.get(day) ?? []
+      list.push(entry)
+      groups.set(day, list)
+    }
+    return [...groups.entries()]
+  }, [status])
+
+  if (status === null) {
+    return (
+      <div className="dlb-tab">
+        <p className="dlb-empty">{failed ? t('loadFailed') : t('pluginOk') === 'OK' ? '…' : '…'}</p>
+        {failed ? (
+          <button type="button" className="dlb-btn dlb-btnGhost" onClick={load}>
+            {t('retry')}
+          </button>
+        ) : null}
+      </div>
+    )
+  }
+
+  return (
+    <div className="dlb-tab">
+      {notice !== null ? (
+        <p className="dlb-notice" role="status">
+          {notice}
+        </p>
+      ) : null}
+
+      {status.llmFallback?.active === true ? (
+        <div className="dlb-fallback" role="status">
+          <p className="dlb-fallbackTitle">{t('fallbackActive')}</p>
+          <div className="dlb-kv">
+            <span>{t('fallbackFrom')}</span>
+            <code>
+              {status.llmFallback.originalProvider}/{status.llmFallback.originalModel}
+            </code>
+          </div>
+          <div className="dlb-kv">
+            <span>{t('fallbackTo')}</span>
+            <code>{status.llmFallback.fallbackProvider}</code>
+          </div>
+          <div className="dlb-kv">
+            <span>{t('fallbackAt')}</span>
+            <code>{status.llmFallback.at.slice(0, 19).replace('T', ' ')}</code>
+          </div>
+        </div>
+      ) : null}
+
+      <h3 className="dlb-title">{t('quarantined')}</h3>
+      {status.quarantined.length === 0 ? (
+        <p className="dlb-empty">{t('emptyQuarantined')}</p>
+      ) : (
+        <div className="dlb-cards">
+          {status.quarantined.map((name) => (
+            <div className="dlb-quarantineCard" key={name}>
+              <code className="dlb-pluginName">{name}</code>
+              {confirming === name ? (
+                <div className="dlb-confirm">
+                  <span className="dlb-confirmText">{t('restoreConfirm')}</span>
+                  <button
+                    type="button"
+                    className="dlb-btn dlb-btnGhost"
+                    disabled={busyName === name}
+                    onClick={() => setConfirming(null)}
+                  >
+                    ×
+                  </button>
+                  <button
+                    type="button"
+                    className="dlb-btn dlb-btnPrimary"
+                    disabled={busyName === name}
+                    onClick={() => onRestore(name)}
+                  >
+                    {busyName === name ? t('restoring') : t('restore')}
+                  </button>
+                </div>
+              ) : (
+                <button
+                  type="button"
+                  className="dlb-btn dlb-btnPrimary"
+                  disabled={busyName === name}
+                  onClick={() => setConfirming(name)}
+                >
+                  {busyName === name ? t('restoring') : t('restore')}
+                </button>
+              )}
+            </div>
+          ))}
+        </div>
+      )}
+
+      <h3 className="dlb-title">{t('journalTitle')}</h3>
+      {journalGroups.length === 0 ? (
+        <p className="dlb-empty">{t('emptyJournal')}</p>
+      ) : (
+        <div className="dlb-journal">
+          {journalGroups.map(([day, entries]) => (
+            <div className="dlb-journalDay" key={day}>
+              <span className="dlb-dayLabel">{day}</span>
+              {entries.map((entry) => (
+                <div className="dlb-entry" key={`${entry.at}-${entry.kind}`}>
+                  <span className={`dlb-kind ${KIND_STYLES[entry.kind] ?? 'dlb-kindInfo'}`}>
+                    {entry.kind}
+                  </span>
+                  <span className="dlb-entryAt">{entry.at.slice(11, 19)}</span>
+                  <span className="dlb-entryDetail">{entry.detail}</span>
+                </div>
+              ))}
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  )
+}
+
+/** 挂载健康页（由 client.ts 延迟 require；任何异常由调用方捕获）。 */
+export function mountHealthTab(ctx: Context): void {
+  const c = ctx as unknown as HealthContext
+  const tag = injectHealthStyle()
+  c.effect(
+    () => () => {
+      tag?.remove()
+    },
+    'lifeboat: health style',
+  )
+  c.effect(() => c.locale.register(NS, { zh: zhDict, en: enDict }), 'lifeboat: locale')
+  const t = c.locale.bind(NS)
+  c.slots.inject('settings.plugins.tab', () =>
+    c.slots.register(
+      {
+        name: 'settings.plugins.tab',
+        id: 'dsh-plus-lifeboat',
+        order: 20,
+        label: () => t('tab'),
+        inject: () => ({ t }),
+      },
+      HealthTab,
+    ),
+  )
+}

package/src/config.ts

@@ -34,7 +34,8 @@ export const Config = z.object({
 export type LifeboatConfig = Schemastery.TypeT<typeof Config>
 
 /** journal 单条记录。 */
-const JournalEntry = z.object({
+// biome-ignore lint/suspicious/noExplicitAny: dts 可移植性——嵌套 schema 精确类型经消费方断开 cosmokit 推断链
+const JournalEntry: any = z.object({
   at: z.string(),
   kind: z.string(),
   detail: z.string(),
@@ -51,7 +52,8 @@ const FallbackState = z.object({
 })
 
 /** 命名空间 schema：宽松承载 journal 与翻译状态，上限截断防膨胀。 */
-export const JournalSchema = z.object({
+// biome-ignore lint/suspicious/noExplicitAny: dts 可移植性（同 JournalEntry；上次成功构建未触发是因旧 lockfile，现同 usage-panel 口径）
+export const JournalSchema: any = z.object({
   journal: z.array(JournalEntry).description('救生艇操作日志（最新在尾，封顶 50 条）').default([]),
   llmFallback: z
     .union([FallbackState, z.const(null)])

package/src/health-api.ts

@@ -0,0 +1,120 @@
+/**
+ * lifeboat 健康面板 host 接收面：
+ * - GET  /dsh-plus/lifeboat/status  → journal + 翻译状态 + 当前用户 patch 层已禁用的 dsh-plus 插件
+ * - POST /dsh-plus/lifeboat/restore {name} → removeDisable + journal + 告警
+ * rc8 用户 patch 层热应用：恢复无需重启，watchUserPatches 即时重载。
+ * @module lifeboat/health-api
+ */
+import { readFile } from 'node:fs/promises'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-host-webserver'
+import { parseDocument } from 'yaml'
+import type { Alerter } from './notify.ts'
+import { listDisabled, type PatchEntry, removeDisable } from './patch-file.ts'
+import { isGuardedPlugin } from './quarantine.ts'
+
+const ROUTE_STATUS = '/dsh-plus/lifeboat/status'
+const ROUTE_RESTORE = '/dsh-plus/lifeboat/restore'
+
+export interface HealthDeps {
+  patchFile: string
+  journal: (kind: string, detail: string) => void
+  alert: Alerter
+  /** journal 文档（settings 命名空间内，最新在前的尾插列表）。 */
+  readJournal(): Array<{ at: string; kind: string; detail: string }>
+  readFallback(): {
+    active: boolean
+    originalProvider: string
+    originalModel: string
+    fallbackProvider: string
+    at: string
+  } | null
+}
+
+function sendJson(res: ServerResponse, status: number, body: unknown): void {
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' })
+  res.end(JSON.stringify(body))
+}
+
+function readBody(req: IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = []
+    req.on('data', (chunk: Buffer) => chunks.push(chunk))
+    req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')))
+    req.on('error', reject)
+  })
+}
+
+/** 解析用户 patch 层中已被禁用且属于 dsh-plus 兄弟域的插件名。 */
+export async function readQuarantined(patchFile: string): Promise<string[]> {
+  let text: string
+  try {
+    text = await readFile(patchFile, 'utf-8')
+  } catch {
+    return []
+  }
+  const root = parseDocument(text).toJS() as unknown
+  if (!Array.isArray(root)) return []
+  const ids = listDisabled(root as PatchEntry[])
+  return ids.filter((id) => isGuardedPlugin(id) || id.startsWith('dsh-plus-'))
+}
+
+/** 注册健康面板路由（webServer 缺席时由调用方保证不调用）。 */
+export function registerHealthApi(ctx: Context, deps: HealthDeps): void {
+  const logger = ctx.logger('lifeboat')
+  ctx.webServer.register({
+    kind: 'prefix',
+    path: ROUTE_STATUS,
+    handler: async (_req: IncomingMessage, res: ServerResponse) => {
+      try {
+        const quarantined = await readQuarantined(deps.patchFile)
+        sendJson(res, 200, {
+          journal: deps.readJournal(),
+          llmFallback: deps.readFallback(),
+          quarantined,
+        })
+      } catch (error) {
+        logger.warn(
+          `status endpoint failed: ${error instanceof Error ? error.message : String(error)}`,
+        )
+        sendJson(res, 500, { error: 'internal' })
+      }
+    },
+  })
+  ctx.webServer.register({
+    kind: 'prefix',
+    path: ROUTE_RESTORE,
+    handler: async (req: IncomingMessage, res: ServerResponse) => {
+      try {
+        if (req.method !== 'POST') {
+          sendJson(res, 405, { error: 'POST only' })
+          return
+        }
+        const body = JSON.parse(await readBody(req)) as { name?: unknown }
+        if (typeof body.name !== 'string' || !body.name.startsWith('dsh-plus-')) {
+          sendJson(res, 400, { error: 'invalid-name' })
+          return
+        }
+        const written = await removeDisable(deps.patchFile, body.name)
+        deps.journal(
+          'quarantine-restore',
+          written
+            ? `${body.name}：已移除用户 patch 层的禁用覆盖（热应用即时恢复）`
+            : `${body.name}：无需恢复（patch 层无禁用覆盖）`,
+        )
+        deps.alert(
+          '[DSH] 插件恢复',
+          `插件 ${body.name} 的隔离已解除（移除 patch 层禁用覆盖）。${
+            written ? 'rc8 热应用即时生效，无需重启。' : 'patch 层本无覆盖，可能已被手动恢复。'
+          }`,
+        )
+        sendJson(res, 200, { ok: true, written })
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error)
+        logger.warn(`restore endpoint failed: ${message}`)
+        sendJson(res, 500, { error: message })
+      }
+    },
+  })
+}

package/src/index.ts

@@ -24,6 +24,7 @@ import {
   SETTINGS_NS,
 } from './config.ts'
 import { installLlmFallback } from './fallback-llm.ts'
+import { registerHealthApi } from './health-api.ts'
 import { installAlerter } from './notify.ts'
 import { createQuarantine, installHostWatch } from './quarantine.ts'
 import { registerQuarantineApi } from './quarantine-api.ts'
@@ -80,6 +81,13 @@ export function apply(ctx: Context, config: LifeboatConfig): void {
     installHostWatch(ctx, quarantine)
     ctx.inject(['webServer'], (webCtx) => {
       registerQuarantineApi(webCtx, quarantine)
+      registerHealthApi(webCtx, {
+        patchFile,
+        journal,
+        alert,
+        readJournal: () => doc.journal,
+        readFallback: () => doc.llmFallback,
+      })
     })
   }
 

package/src/patch-file.ts

@@ -43,3 +43,57 @@ export async function appendDisable(patchFile: string, targetId: string): Promis
   await rename(tmp, patchFile)
   return true
 }
+
+/** 顶层条目中已禁用的 id 列表（不含 insert 子列表；用户层 disabled 语义只在顶层）。 */
+export function listDisabled(entries: PatchEntry[]): string[] {
+  const out: string[] = []
+  for (const entry of entries) {
+    if (typeof entry.id === 'string' && entry.disabled === true) out.push(entry.id)
+  }
+  return out
+}
+
+/**
+ * 从 patch 文件移除针对 targetId 的禁用覆盖（恢复插件）；返回是否实际写入。
+ * 只移除「id 定向且 disabled: true」的行，其余内容（注释经 yaml 文档保留、
+ * 其他条目）原样不动；无该覆盖时幂等返回 false。
+ * @throws 文件不可读/顶层不是数组/落盘失败——调用方负责告警。
+ */
+export async function removeDisable(patchFile: string, targetId: string): Promise<boolean> {
+  const text = await readFile(patchFile, 'utf-8')
+  const doc = parseDocument(text)
+  const root = doc.toJS() as unknown
+  if (!Array.isArray(root)) throw new Error(`patch 文件顶层不是数组: ${patchFile}`)
+  let removed = false
+  const items = doc.contents
+  if (items?.items !== undefined && Array.isArray(items.items)) {
+    // 头注释挂在首个条目的 commentBefore 上：被移除项若为首项，注释迁移给
+    // 新的首项，避免整文件头注释丢失。
+    const headComment = (items.items[0] as unknown as { commentBefore?: string })?.commentBefore
+    doc.contents.items = items.items.filter((item) => {
+      const value = (item as unknown as { toJS?(doc: unknown): unknown }).toJS?.(doc) as
+        | PatchEntry
+        | undefined
+      if (
+        value !== undefined &&
+        typeof value === 'object' &&
+        value.id === targetId &&
+        value.disabled === true
+      ) {
+        removed = true
+        return false
+      }
+      return true
+    })
+    if (removed && headComment !== undefined && doc.contents.items.length > 0) {
+      const next = doc.contents.items[0] as unknown as { commentBefore?: string }
+      if (next.commentBefore === undefined) next.commentBefore = headComment
+    }
+  }
+  if (!removed) return false
+  await copyFile(patchFile, `${patchFile}.lifeboat.bak`)
+  const tmp = `${patchFile}.lifeboat.tmp`
+  await writeFile(tmp, doc.toString(), 'utf-8')
+  await rename(tmp, patchFile)
+  return true
+}

package/src/quarantine.ts

@@ -31,7 +31,17 @@ export interface QuarantineDeps {
 
 export interface Quarantine {
   /** 隔离指定插件（幂等；冷却期内重复触发只计 journal 不写文件）。 */
-  quarantine(name: string, origin: 'host' | 'client'): Promise<void>
+  quarantine(name: string, origin: 'host' | 'client', reason?: unknown): Promise<void>
+}
+
+/** 告警/journal 里的失败原因摘录上限，防长堆栈淹没通知渠道。 */
+const REASON_CAP = 500
+
+/** 提取 fiber 失败原因的短文本（无则空串）；cordis 把错误挂在 fiber._error。 */
+function reasonText(reason: unknown): string {
+  if (reason === undefined || reason === null) return ''
+  const text = reason instanceof Error ? (reason.stack ?? reason.message) : String(reason)
+  return text.length > REASON_CAP ? `${text.slice(0, REASON_CAP)}…` : text
 }
 
 /** 装配隔离执行器（纯逻辑，可测）。 */
@@ -40,15 +50,21 @@ export function createQuarantine(ctx: Context, deps: QuarantineDeps): Quarantine
   const lastAlertAt = new Map<string, number>()
   const inFlight = new Set<string>()
 
-  async function quarantine(name: string, origin: 'host' | 'client'): Promise<void> {
+  async function quarantine(
+    name: string,
+    origin: 'host' | 'client',
+    reason?: unknown,
+  ): Promise<void> {
     if (!isGuardedPlugin(name)) return
     if (inFlight.has(name)) return
     inFlight.add(name)
+    const reasonBlock = reasonText(reason)
+    const reasonSuffix = reasonBlock === '' ? '' : `\n失败原因：\n${reasonBlock}`
     try {
       const written = await appendDisable(deps.patchFile, name)
       deps.journal(
         'quarantine',
-        `${name}（来源 ${origin}，${written ? '已写入禁用' : '已存在禁用'}）`,
+        `${name}（来源 ${origin}，${written ? '已写入禁用' : '已存在禁用'}）${reasonSuffix}`,
       )
       const now = Date.now()
       const last = lastAlertAt.get(name) ?? 0
@@ -58,7 +74,7 @@ export function createQuarantine(ctx: Context, deps: QuarantineDeps): Quarantine
           `[DSH] 插件 ${name} 加载失败，已自动隔离`,
           `检测到插件 ${name} 的 fiber 进入 FAILED（来源：${origin}）。\n` +
             `已向 ${deps.patchFile} 写入 disabled 覆盖，重启/刷新后该插件不再加载，其余插件不受影响。\n` +
-            `修复后删除该条覆盖即可恢复。`,
+            `修复后删除该条覆盖即可恢复。${reasonSuffix}`,
         )
       }
     } catch (error) {
@@ -82,9 +98,9 @@ export function createQuarantine(ctx: Context, deps: QuarantineDeps): Quarantine
  * fiber.name 对 loader 条目即插件 display name（模块导出的 name 字段）。
  */
 export function installHostWatch(ctx: Context, q: Quarantine): void {
-  ctx.root.on('internal/status', (fiber: { state: number; name: string }) => {
+  ctx.root.on('internal/status', (fiber: { state: number; name: string; _error?: unknown }) => {
     if (fiber.state !== FIBER_FAILED) return
     if (!isGuardedPlugin(fiber.name)) return
-    void q.quarantine(fiber.name, 'host')
+    void q.quarantine(fiber.name, 'host', fiber._error)
   })
 }