dsh-manage-session 0.1.0-alpha.0 → 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,19 +1,42 @@
1
1
  /**
2
- * 病案室(会话历史文件)面板 —— 自 dsh-session-search-toggle `src/client/archive-panel.tsx`
3
- * **迁入**并适配到本包的方法名(`session-history-list` / `session-history-prune`)。
2
+ * 养老院(会话历史文件)面板 —— 自 dsh-session-search-toggle `src/client/archive-panel.tsx`
3
+ * **迁入**并适配到本包的方法名。
4
4
  *
5
- * 行为与迁移前一致(含「显式编辑模式才允许清理」的门禁与 JS confirm):
6
- * 行不可导航(归档会话已离开活跃系统);清理写存储文件(自动备份)并需要重启 DSH。
7
- * 差异:列表来源改为官方归档集合真值,因此额外显示来源与降级提示。
5
+ * 与迁移前的关键差异(**两个操作刻意分开,不可互换**):
6
+ *
7
+ * | 操作 | 路由 | 改什么 | 可逆 |
8
+ * |---|---|---|---|
9
+ * | 取消归档状态 | `session-history-prune` | 只改归档数组 | ✅ 重启后会话回到侧边栏 |
10
+ * | 清理归档文件 | `session-history-purge` | **真删**转录目录 + 投影缓存 + 两处 id | ❌ 不可逆 |
11
+ *
12
+ * 「删除」一词在本面板**不存在** —— 旧文案承诺「删除」却只改了个数组,
13
+ * 是导致「点了确认没反应」那类误判的一部分。
14
+ * 体积**按行**显示(实测单条可从 0 到 23 MB,报一个总量没有意义),按钮上给所选小计。
8
15
  */
9
16
  import { createElement, useEffect, useState, type ReactElement } from 'react'
10
- import { callHost, callHostAny, type HistoryRow } from './host-api.ts'
17
+ import { callHostAny, type HistoryRow } from './host-api.ts'
11
18
  import { translate, type LocaleKey } from './locales.ts'
12
19
 
13
20
  /** 面板收到的字典面。 */
14
21
  export type PanelTranslate = (key: LocaleKey, params?: Record<string, unknown>) => string
15
22
 
16
- /** 病案室面板。 */
23
+ /** 当前正在跑的操作;任一进行中都锁住两个按钮。 */
24
+ type Busy = 'unarchive' | 'purge' | null
25
+
26
+ /** 人类可读体积。 */
27
+ export function fmtSize(bytes: number): string {
28
+ if (!Number.isFinite(bytes) || bytes <= 0) return '0 B'
29
+ const units = ['B', 'KB', 'MB', 'GB', 'TB']
30
+ let value = bytes
31
+ let unit = 0
32
+ while (value >= 1024 && unit < units.length - 1) {
33
+ value /= 1024
34
+ unit++
35
+ }
36
+ return `${unit === 0 || value >= 100 ? Math.round(value) : value.toFixed(1)} ${units[unit]}`
37
+ }
38
+
39
+ /** 养老院面板。 */
17
40
  export function HistoryPanel({
18
41
  t,
19
42
  onClose,
@@ -24,17 +47,26 @@ export function HistoryPanel({
24
47
  const [items, setItems] = useState<HistoryRow[] | null>(null)
25
48
  const [source, setSource] = useState<string>('')
26
49
  const [degraded, setDegraded] = useState<string>('')
50
+ const [pendingRestart, setPendingRestart] = useState(0)
27
51
  const [error, setError] = useState<string | null>(null)
28
52
  const [attempt, setAttempt] = useState(0)
29
53
  const [selected, setSelected] = useState<ReadonlySet<string>>(new Set())
30
- const [pruning, setPruning] = useState(false)
54
+ const [busy, setBusy] = useState<Busy>(null)
31
55
  const [note, setNote] = useState<string | null>(null)
56
+ /** 清理失败明细(逐条);空数组表示无失败。 */
57
+ const [failures, setFailures] = useState<{ sessionId: string; reason: string }[]>([])
32
58
  const [editing, setEditing] = useState(false)
33
59
 
34
60
  useEffect(() => {
35
61
  let cancelled = false
36
62
  setError(null)
37
- callHostAny<{ items?: HistoryRow[]; source?: string; degraded?: string; error?: string }>(
63
+ callHostAny<{
64
+ items?: HistoryRow[]
65
+ source?: string
66
+ degraded?: string
67
+ pendingRestart?: number
68
+ error?: string
69
+ }>(
38
70
  'session-history-list',
39
71
  {},
40
72
  ).then((res) => {
@@ -43,6 +75,7 @@ export function HistoryPanel({
43
75
  setItems(res.items)
44
76
  setSource(typeof res.source === 'string' ? res.source : '')
45
77
  setDegraded(typeof res.degraded === 'string' ? res.degraded : '')
78
+ setPendingRestart(typeof res.pendingRestart === 'number' ? res.pendingRestart : 0)
46
79
  } else {
47
80
  setError(res.error ?? '读取归档列表失败')
48
81
  }
@@ -71,6 +104,7 @@ export function HistoryPanel({
71
104
  setEditing(prev => !prev)
72
105
  setSelected(new Set())
73
106
  setNote(null)
107
+ setFailures([])
74
108
  }
75
109
 
76
110
  const toggleAll = (): void => {
@@ -79,34 +113,83 @@ export function HistoryPanel({
79
113
  : new Set((items ?? []).map(item => item.sessionId))))
80
114
  }
81
115
 
82
- /** JS confirm 门禁,然后提交清理。 */
83
- const pruneSelected = (): void => {
84
- const ids = [...selected]
85
- if (ids.length === 0) return
86
- const summary = ids.length <= 5
87
- ? ids.map(id => `${id.slice(0, 22)}…`).join('\n')
88
- : `${ids.slice(0, 4).map(id => `${id.slice(0, 22)}…`).join('\n')}\n… 共 ${ids.length} 个`
89
- const confirmed = typeof window !== 'undefined' && typeof window.confirm === 'function'
90
- ? window.confirm(translate(t, 'history.confirm', { n: ids.length, summary }))
91
- : false
92
- if (!confirmed) return
93
- setPruning(true)
116
+ const selectedRows = (items ?? []).filter(item => selected.has(item.sessionId))
117
+ const selectedBytes = selectedRows.reduce((sum, item) => sum + item.bytes + item.cacheBytes, 0)
118
+ const totalBytes = (items ?? []).reduce((sum, item) => sum + item.bytes + item.cacheBytes, 0)
119
+
120
+ /** 确认弹窗里的逐条摘要(清理时带体积,取消归档时不带)。 */
121
+ const summarise = (rows: HistoryRow[], withSize: boolean): string => {
122
+ const lines = rows.slice(0, 5).map((row) => {
123
+ const label = row.title || translate(t, 'panel.untitled')
124
+ const size = fmtSize(row.bytes + row.cacheBytes)
125
+ return withSize ? `· ${label} — ${size}` : `· ${label}`
126
+ })
127
+ if (rows.length > 5) lines.push(`… 共 ${rows.length} 个`)
128
+ return lines.join('\n')
129
+ }
130
+
131
+ const confirm = (message: string): boolean =>
132
+ typeof window !== 'undefined' && typeof window.confirm === 'function' ? window.confirm(message) : false
133
+
134
+ /** 提交一次操作:确认 → 调用 → 刷新列表(列表以存储文件为准,因此立刻可见变化)。 */
135
+ const run = (kind: Exclude<Busy, null>, method: string, confirmText: string): void => {
136
+ const rows = selectedRows
137
+ if (rows.length === 0) return
138
+ if (!confirm(confirmText)) return
139
+ setBusy(kind)
94
140
  setNote(null)
95
- void callHostAny<{ removed?: number; remaining?: number }>('session-history-prune', { sessionIds: ids }, 60_000)
141
+ setFailures([])
142
+ void callHostAny<{
143
+ removed?: number
144
+ remaining?: number
145
+ purged?: number
146
+ freedBytes?: number
147
+ failures?: { sessionId: string; reason: string }[]
148
+ }>(
149
+ method,
150
+ { sessionIds: rows.map(row => row.sessionId) },
151
+ 60_000,
152
+ )
96
153
  .then((res) => {
97
154
  if (res.ok === true) {
98
- setNote(translate(t, 'history.restartHint', {
99
- removed: res.removed ?? ids.length,
100
- remaining: res.remaining ?? '?',
101
- }))
155
+ if (kind === 'unarchive') {
156
+ setNote(translate(t, 'history.restartHint', {
157
+ removed: res.removed ?? rows.length,
158
+ remaining: res.remaining ?? '?',
159
+ }))
160
+ } else {
161
+ const freed = fmtSize(res.freedBytes ?? 0)
162
+ const failed = res.failures?.length ?? 0
163
+ setNote(failed === 0
164
+ ? translate(t, 'history.purgeResult', { purged: res.purged ?? rows.length, size: freed })
165
+ : translate(t, 'history.purgePartial', { purged: res.purged ?? rows.length, size: freed, failed }))
166
+ setFailures(res.failures ?? [])
167
+ }
102
168
  setSelected(new Set())
103
169
  setAttempt(n => n + 1)
104
170
  } else {
105
- setNote(res.error ?? '清理失败')
171
+ setNote(res.error ?? '操作失败')
106
172
  }
107
173
  })
108
- .catch((err: unknown) => setNote(`清理失败:${String(err instanceof Error ? err.message : err)}`))
109
- .finally(() => setPruning(false))
174
+ .catch((err: unknown) => setNote(`操作失败:${String(err instanceof Error ? err.message : err)}`))
175
+ .finally(() => setBusy(null))
176
+ }
177
+
178
+ const unarchiveSelected = (): void => {
179
+ run('unarchive', 'session-history-prune',
180
+ translate(t, 'history.confirmUnarchive', {
181
+ n: selectedRows.length,
182
+ summary: summarise(selectedRows, false),
183
+ }))
184
+ }
185
+
186
+ const purgeSelected = (): void => {
187
+ run('purge', 'session-history-purge',
188
+ translate(t, 'history.confirmPurge', {
189
+ n: selectedRows.length,
190
+ summary: summarise(selectedRows, true),
191
+ size: fmtSize(selectedBytes),
192
+ }))
110
193
  }
111
194
 
112
195
  const children: ReactElement[] = []
@@ -133,13 +216,26 @@ export function HistoryPanel({
133
216
  children.push(createElement('div', { key: 'manage', className: 'dss_btnRow', style: { padding: '4px 10px 0' } }, [
134
217
  createElement('button', { key: 'all', type: 'button', className: 'dss_actBtn', onClick: toggleAll },
135
218
  allSelected ? translate(t, 'history.unselectAll') : translate(t, 'history.selectAll')),
219
+ // 可逆:只改归档数组。
220
+ createElement('button', {
221
+ key: 'unarchive',
222
+ type: 'button',
223
+ className: 'dss_actBtn',
224
+ disabled: busy !== null || selected.size === 0,
225
+ onClick: unarchiveSelected,
226
+ }, busy === 'unarchive'
227
+ ? translate(t, 'history.unarchiving')
228
+ : translate(t, 'history.unarchive', { n: selected.size })),
229
+ // 不可逆:真删磁盘实体。危险样式 + 体积小计。
136
230
  createElement('button', {
137
- key: 'prune',
231
+ key: 'purge',
138
232
  type: 'button',
139
233
  className: 'dss_actBtn dss_dangerBtn',
140
- disabled: pruning || selected.size === 0,
141
- onClick: pruneSelected,
142
- }, pruning ? translate(t, 'history.deleting') : translate(t, 'history.delete', { n: selected.size })),
234
+ disabled: busy !== null || selected.size === 0,
235
+ onClick: purgeSelected,
236
+ }, busy === 'purge'
237
+ ? translate(t, 'history.purging')
238
+ : translate(t, 'history.purge', { n: selected.size, size: fmtSize(selectedBytes) })),
143
239
  ]))
144
240
  }
145
241
  children.push(createElement('ul', {
@@ -159,6 +255,10 @@ export function HistoryPanel({
159
255
  createElement('span', { key: 'x', className: 'dss_titleText' }, item.title || translate(t, 'panel.untitled')),
160
256
  item.updatedAt > 0 && createElement('span', { key: 'tag', className: 'dss_tag' }, fmtTime(item.updatedAt)),
161
257
  ]),
258
+ createElement('span', { key: 'size', className: 'dss_meta dss_size' },
259
+ item.bytes + item.cacheBytes > 0
260
+ ? translate(t, 'history.size', { t: fmtSize(item.bytes), c: fmtSize(item.cacheBytes) })
261
+ : translate(t, 'history.sizeUnknown')),
162
262
  item.cwd !== '' && createElement('span', { key: 'c', className: 'dss_meta' }, item.cwd),
163
263
  createElement('span', { key: 'id', className: 'dss_meta dss_uuid' }, item.sessionId),
164
264
  ]))))
@@ -166,10 +266,21 @@ export function HistoryPanel({
166
266
 
167
267
  return createElement('div', { className: 'dss_tabBody' }, [
168
268
  note !== null && createElement('div', { key: 'note', className: 'dss_status' }, note),
269
+ failures.length > 0 && createElement('div', { key: 'fail', className: 'dss_status dss_error' }, [
270
+ createElement('div', { key: 'h' }, translate(t, 'history.purgeFailures')),
271
+ ...failures.slice(0, 10).map((failure, index) => createElement('div', {
272
+ key: `f${index}`,
273
+ className: 'dss_meta',
274
+ }, `${failure.sessionId.slice(0, 22)}… — ${failure.reason}`)),
275
+ ]),
169
276
  editing && createElement('div', { key: 'hint', className: 'dss_status' }, translate(t, 'history.editingHint')),
170
277
  degraded !== '' && createElement('div', { key: 'degraded', className: 'dss_status dss_warnText' }, degraded),
278
+ pendingRestart > 0 && createElement('div', { key: 'pending', className: 'dss_status dss_warnText' },
279
+ translate(t, 'history.pendingRestart', { n: pendingRestart })),
171
280
  source !== '' && createElement('div', { key: 'source', className: 'dss_metaLine' },
172
281
  translate(t, source === 'registry' ? 'history.source.registry' : source === 'storage-file' ? 'history.source.storage-file' : 'history.source.none')),
282
+ items !== null && error === null && createElement('div', { key: 'count', className: 'dss_metaLine' },
283
+ translate(t, 'history.count', { n: items.length, size: fmtSize(totalBytes) })),
173
284
  createElement('div', { key: 'headBtns', className: 'dss_btnRow' }, [
174
285
  createElement('button', {
175
286
  key: 'edit',
@@ -200,5 +311,9 @@ export function fmtTime(ms: number): string {
200
311
  }
201
312
  }
202
313
 
203
- /** 供单测使用:确认面板依赖的方法名(防止与 index-* 冲突)。 */
204
- export const HISTORY_METHOD_NAMES = ['session-history-list', 'session-history-prune'] as const
314
+ /** 供单测使用:面板依赖的方法名。锁住「两个操作是两条独立路由」,防止再被合并成一个动词。 */
315
+ export const HISTORY_METHOD_NAMES = [
316
+ 'session-history-list',
317
+ 'session-history-prune',
318
+ 'session-history-purge',
319
+ ] as const
@@ -1,135 +1,177 @@
1
- /**
2
- * 客户端 host 调用助手:一切经 fenced `/session-steward/api/<method>` 路由,
3
- * 不 value-import 任何官方包(与 dsh-session-search-toggle 的 host-api.ts 同范式,
4
- * 仅把路由前缀换成会话管家自己的)。
5
- */
6
-
7
- /** 单次 host 调用超时(导入类大响应可单独放宽)。 */
8
- const FETCH_TIMEOUT = 20_000
9
-
10
- /** POST 一个 JSON body 到会话管家的 fenced API(items 形状)。 */
11
- export function callHost<T>(method: string, body: unknown): Promise<{ ok: boolean; items: T[]; error?: string }> {
12
- const controller = typeof AbortController === 'undefined' ? undefined : new AbortController()
13
- const timer = controller !== undefined && typeof setTimeout === 'function'
14
- ? setTimeout(() => { controller.abort() }, FETCH_TIMEOUT)
15
- : undefined
16
- return fetch(`/session-steward/api/${method}`, {
17
- method: 'POST',
18
- headers: { 'content-type': 'application/json' },
19
- body: JSON.stringify(body),
20
- signal: controller?.signal,
21
- })
22
- .then((res) => (res.ok ? res.json() : Promise.reject(new Error(`HTTP ${res.status}`))))
23
- .then((data: unknown) => {
24
- const record = data as { ok?: boolean; items?: T[]; error?: string }
25
- if (record && record.ok === true && Array.isArray(record.items)) {
26
- return { ok: true, items: record.items }
27
- }
28
- return { ok: false, items: [], error: record?.error ?? '请求失败' }
29
- })
30
- .catch((err: unknown) => ({
31
- ok: false,
32
- items: [],
33
- error: err instanceof DOMException && err.name === 'AbortError' ? '请求超时' : String(err instanceof Error ? err.message : err),
34
- }))
35
- .finally(() => {
36
- if (timer !== undefined) clearTimeout(timer)
37
- })
38
- }
39
-
40
- /** POST 一个 JSON body,返回整条记录。 */
41
- export function callHostAny<T>(
42
- method: string,
43
- body: unknown,
44
- timeout = FETCH_TIMEOUT,
45
- ): Promise<Partial<T> & { ok: boolean; error?: string }> {
46
- const controller = typeof AbortController === 'undefined' ? undefined : new AbortController()
47
- const timer = typeof setTimeout === 'function'
48
- ? setTimeout(() => { controller?.abort() }, timeout)
49
- : undefined
50
- return fetch(`/session-steward/api/${method}`, {
51
- method: 'POST',
52
- headers: { 'content-type': 'application/json' },
53
- body: JSON.stringify(body),
54
- signal: controller?.signal,
55
- })
56
- .then((res) => (res.ok ? res.json() : Promise.reject(new Error(`HTTP ${res.status}`))))
57
- .catch((err: unknown) => ({
58
- ok: false,
59
- error: err instanceof DOMException && err.name === 'AbortError' ? '请求超时' : String(err instanceof Error ? err.message : err),
60
- }))
61
- .finally(() => {
62
- if (timer !== undefined) clearTimeout(timer)
63
- })
64
- }
65
-
66
- /** 一条历史文件行(与 host 侧 StewardHistoryRow 对齐)。 */
67
- export interface HistoryRow {
68
- sessionId: string
69
- title: string
70
- cwd: string
71
- updatedAt: number
72
- }
73
-
74
- /** 历史文件列表响应。 */
75
- export interface HistoryListResponse {
76
- ok: boolean
77
- items?: HistoryRow[]
78
- source?: 'registry' | 'storage-file' | 'none'
79
- degraded?: string
80
- error?: string
81
- }
82
-
83
- /** 一个 gate 的结果(与 host 侧 GateResult 对齐)。 */
84
- export interface HealthGate {
85
- id: 'log-integrity' | 'projection-cache' | 'lossless-json' | 'cold-read'
86
- level: 'ok' | 'warn' | 'fail'
87
- evidence: string
88
- attribution?: { projection?: string; package?: string; field?: string }
89
- detail?: Record<string, unknown>
90
- }
91
-
92
- /** 单会话体检报告。 */
93
- export interface HealthReport {
94
- sessionId: string
95
- level: 'ok' | 'warn' | 'fail'
96
- gates: HealthGate[]
97
- generatedAt: number
98
- }
99
-
100
- /** 体检扫描响应。 */
101
- export interface HealthScanResponse {
102
- ok: boolean
103
- scanned?: number
104
- findings?: HealthReport[]
105
- error?: string
106
- }
107
-
108
- /** 单会话体检响应。 */
109
- export interface HealthSessionResponse {
110
- ok: boolean
111
- report?: HealthReport
112
- prescriptions?: string[]
113
- error?: string
114
- }
115
-
116
- /** 出院(可逆处置)响应。 */
117
- export interface HealthRepairResponse {
118
- ok: boolean
119
- changed?: boolean
120
- before?: HealthReport
121
- after?: HealthReport
122
- repair?: { ok: boolean; from?: string; to?: string; error?: string; requiresRestart?: boolean }
123
- prescriptions?: string[]
124
- error?: string
125
- }
126
-
127
- /** 状态响应。 */
128
- export interface HealthStatusResponse {
129
- ok: boolean
130
- switches?: { enabled: boolean; historyFiles: boolean; healthCheck: boolean }
131
- historyMethods?: string[]
132
- healthMethods?: string[]
133
- home?: string
134
- error?: string
135
- }
1
+ /**
2
+ * 客户端 host 调用助手:一切经 fenced `/session-steward/api/<method>` 路由,
3
+ * 不 value-import 任何官方包(与 dsh-session-search-toggle 的 host-api.ts 同范式,
4
+ * 仅把路由前缀换成会话管家自己的)。
5
+ */
6
+
7
+ /** 单次 host 调用超时(导入类大响应可单独放宽)。 */
8
+ const FETCH_TIMEOUT = 20_000
9
+
10
+ /** POST 一个 JSON body 到会话管家的 fenced API(items 形状)。 */
11
+ export function callHost<T>(method: string, body: unknown): Promise<{ ok: boolean; items: T[]; error?: string }> {
12
+ const controller = typeof AbortController === 'undefined' ? undefined : new AbortController()
13
+ const timer = controller !== undefined && typeof setTimeout === 'function'
14
+ ? setTimeout(() => { controller.abort() }, FETCH_TIMEOUT)
15
+ : undefined
16
+ return fetch(`/session-steward/api/${method}`, {
17
+ method: 'POST',
18
+ headers: { 'content-type': 'application/json' },
19
+ body: JSON.stringify(body),
20
+ signal: controller?.signal,
21
+ })
22
+ .then((res) => (res.ok ? res.json() : Promise.reject(new Error(`HTTP ${res.status}`))))
23
+ .then((data: unknown) => {
24
+ const record = data as { ok?: boolean; items?: T[]; error?: string }
25
+ if (record && record.ok === true && Array.isArray(record.items)) {
26
+ return { ok: true, items: record.items }
27
+ }
28
+ return { ok: false, items: [], error: record?.error ?? '请求失败' }
29
+ })
30
+ .catch((err: unknown) => ({
31
+ ok: false,
32
+ items: [],
33
+ error: err instanceof DOMException && err.name === 'AbortError' ? '请求超时' : String(err instanceof Error ? err.message : err),
34
+ }))
35
+ .finally(() => {
36
+ if (timer !== undefined) clearTimeout(timer)
37
+ })
38
+ }
39
+
40
+ /** POST 一个 JSON body,返回整条记录。 */
41
+ export function callHostAny<T>(
42
+ method: string,
43
+ body: unknown,
44
+ timeout = FETCH_TIMEOUT,
45
+ ): Promise<Partial<T> & { ok: boolean; error?: string }> {
46
+ const controller = typeof AbortController === 'undefined' ? undefined : new AbortController()
47
+ const timer = typeof setTimeout === 'function'
48
+ ? setTimeout(() => { controller?.abort() }, timeout)
49
+ : undefined
50
+ return fetch(`/session-steward/api/${method}`, {
51
+ method: 'POST',
52
+ headers: { 'content-type': 'application/json' },
53
+ body: JSON.stringify(body),
54
+ signal: controller?.signal,
55
+ })
56
+ .then((res) => (res.ok ? res.json() : Promise.reject(new Error(`HTTP ${res.status}`))))
57
+ .catch((err: unknown) => ({
58
+ ok: false,
59
+ error: err instanceof DOMException && err.name === 'AbortError' ? '请求超时' : String(err instanceof Error ? err.message : err),
60
+ }))
61
+ .finally(() => {
62
+ if (timer !== undefined) clearTimeout(timer)
63
+ })
64
+ }
65
+
66
+ /** 一条历史文件行(与 host 侧 StewardHistoryRow 对齐)。 */
67
+ export interface HistoryRow {
68
+ sessionId: string
69
+ title: string
70
+ cwd: string
71
+ updatedAt: number
72
+ /** 转录目录占用字节数(0 = 未知或磁盘上无实体)。 */
73
+ bytes: number
74
+ /** 投影缓存占用字节数。 */
75
+ cacheBytes: number
76
+ }
77
+
78
+ /** 历史文件列表响应。 */
79
+ export interface HistoryListResponse {
80
+ ok: boolean
81
+ items?: HistoryRow[]
82
+ source?: 'registry' | 'storage-file' | 'none'
83
+ degraded?: string
84
+ /** 已从存储文件移除、但宿主内存里仍生效的 id 数。 */
85
+ pendingRestart?: number
86
+ error?: string
87
+ }
88
+
89
+ /** 归档文件清理(真删除)响应。 */
90
+ export interface HistoryPurgeResponse {
91
+ ok: boolean
92
+ purged?: number
93
+ freedBytes?: number
94
+ failures?: { sessionId: string; reason: string }[]
95
+ requiresRestart?: boolean
96
+ error?: string
97
+ }
98
+
99
+ /** 一个 gate 的结果(与 host 侧 GateResult 对齐)。 */
100
+ export interface HealthGate {
101
+ id: 'log-integrity' | 'projection-cache' | 'lossless-json' | 'cold-read'
102
+ level: 'ok' | 'warn' | 'fail' | 'skipped'
103
+ evidence: string
104
+ attribution?: { projection?: string; package?: string; field?: string }
105
+ detail?: Record<string, unknown>
106
+ }
107
+
108
+ /** 单会话体检报告。 */
109
+ export interface HealthReport {
110
+ sessionId: string
111
+ /** 总判:聚合时 `skipped` 不抬升(见 host 侧 buildSessionReport)。 */
112
+ level: 'ok' | 'warn' | 'fail'
113
+ gates: HealthGate[]
114
+ generatedAt: number
115
+ }
116
+
117
+ /** 体检扫描响应。 */
118
+ export interface HealthScanResponse {
119
+ ok: boolean
120
+ /** 本次响应是否来自缓存(`resume: true` 时的命中标记)。 */
121
+ cached?: boolean
122
+ /** 本批已访问的会话数(分批扫描的进度步长)。 */
123
+ scanned?: number
124
+ /** 语料总数(进度分母);缓存命中时为**缓存生成时**的语料总数。 */
125
+ total?: number
126
+ /** 本批起点(原样回显)。 */
127
+ offset?: number
128
+ findings?: HealthReport[]
129
+ /** 缓存的生成时刻(epoch ms);仅缓存命中时给出。 */
130
+ generatedAt?: number
131
+ /** 当前语料总数;与 `total` 不一致即「语料已变化」。 */
132
+ currentTotal?: number
133
+ error?: string
134
+ }
135
+
136
+ /** 单会话体检响应。 */
137
+ export interface HealthSessionResponse {
138
+ ok: boolean
139
+ report?: HealthReport
140
+ prescriptions?: string[]
141
+ error?: string
142
+ }
143
+
144
+ /** 处置结果的定性分类(与 host 侧 RepairVerdict 对齐)。 */
145
+ export type RepairVerdict =
146
+ | 'nothing-to-do'
147
+ | 'repaired'
148
+ | 'repaired-with-residual'
149
+ | 'not-applicable'
150
+ | 'failed'
151
+
152
+ /** 出院(可逆处置)响应。 */
153
+ export interface HealthRepairResponse {
154
+ ok: boolean
155
+ changed?: boolean
156
+ before?: HealthReport
157
+ after?: HealthReport
158
+ repair?: { ok: boolean; from?: string; to?: string; error?: string; requiresRestart?: boolean }
159
+ /** 处置结果的定性分类:区分「生效」「生效但有无关残留」「无可处置项」「失败」。 */
160
+ verdict?: RepairVerdict
161
+ /** 人读说明:为什么处置后仍然异常(或已恢复)。 */
162
+ explanation?: string
163
+ /** 处置后仍未解决的门。 */
164
+ residual?: { id: HealthGate['id']; level: HealthGate['level'] }[]
165
+ prescriptions?: string[]
166
+ error?: string
167
+ }
168
+
169
+ /** 状态响应。 */
170
+ export interface HealthStatusResponse {
171
+ ok: boolean
172
+ switches?: { enabled: boolean; historyFiles: boolean; healthCheck: boolean }
173
+ historyMethods?: string[]
174
+ healthMethods?: string[]
175
+ home?: string
176
+ error?: string
177
+ }