@cowwo/dsh-lookout 0.1.2 → 0.5.0

package/lib/icon/index.js

@@ -41,6 +41,13 @@ import {
 	pruneSeen
 } from './unread.js'
 import { normalizeRunningConfig } from './running.js'
+import {
+	emptyWorkspacePrefs,
+	normalizeWorkspacePrefs,
+	readWorkspacePrefs,
+	workspacePrefsFilePath,
+	writeWorkspacePrefs
+} from './workspace-prefs.js'
 
 const MAX_BYTES = 10 * 1024 * 1024 // 10 MB
 // Normalized mime -> safe extension. CUR (mouse cursor) is accepted as ICO.
@@ -344,6 +351,10 @@ export class FaviconCustomService extends TypertRemoteService {
 		// list already carries each session's `running`), so nothing about it is
 		// stored here — only whether to show the projection of it.
 		this.runningPath = join(this.storageDir, 'running.json')
+		// Per-workspace preferences (tag / color / pinned / hidden). Same folder as
+		// the icon library, but its own file + endpoint pair: a corrupt preference
+		// document must never take the favicon or the badge rules down with it.
+		this.workspacePrefsPath = workspacePrefsFilePath(this.storageDir)
 		// { activeId, icons: { [id]: { id, mime, ext, name, size, savedAt, rev, pwa, logo } } }
 		this.library = { activeId: null, icons: {} }
 		// The active icon's loaded state: { rev, mime, ext, name, size, savedAt, pwa, logo, bytes } | null
@@ -355,6 +366,9 @@ export class FaviconCustomService extends TypertRemoteService {
 		// Running-mark switch: whether the yellow projection of the official
 		// `running` fact is drawn. See lib/running.js.
 		this.running = normalizeRunningConfig(null)
+		// Workspace preferences: { version: 1, workspaces: { [workspaceId]: { tag, color, pinned, hidden, pinAnchor } } }.
+		// The client sends the whole document on every set (full replacement).
+		this.workspacePrefs = emptyWorkspacePrefs()
 		// Host-side watermark: { [sessionId]: endAt } — see lib/unread.js.
 		this.seen = {}
 		// Platform PWA manifest (raw + parsed), read once at startup.
@@ -362,6 +376,7 @@ export class FaviconCustomService extends TypertRemoteService {
 		this._load()
 		this._loadUnread()
 		this._loadRunning()
+		this._loadWorkspacePrefs()
 		this._loadUnreadSeen()
 		// "How did this session's last turn end" as an official session
 		// projection. Optional registration on purpose: this plugin is a display
@@ -477,6 +492,16 @@ export class FaviconCustomService extends TypertRemoteService {
 		return writeFile(this.runningPath, JSON.stringify(this.running, null, 2))
 	}
 
+	/** Load workspace preferences (missing or corrupt file = empty document). */
+	_loadWorkspacePrefs() {
+		this.workspacePrefs = readWorkspacePrefs(this.workspacePrefsPath)
+	}
+
+	/** Persist workspace preferences (best effort; atomic tmp+rename in the helper). */
+	_saveWorkspacePrefs() {
+		return writeWorkspacePrefs(this.workspacePrefsPath, this.workspacePrefs)
+	}
+
 	/**
 	 * Load the host-side watermark.
 	 *
@@ -585,6 +610,35 @@ export class FaviconCustomService extends TypertRemoteService {
 		return { ...this.running }
 	}
 
+	/**
+	 * typert endpoint: read the per-workspace preferences (tag / color / pinned /
+	 * hidden). A copy, not the live object: a caller must not be able to mutate the
+	 * Host's state by editing the response.
+	 * @returns `{ version: 1, workspaces: { [workspaceId]: { tag, color, pinned, hidden, pinAnchor } } }`.
+	 */
+	async getWorkspacePrefs() {
+		return normalizeWorkspacePrefs(this.workspacePrefs)
+	}
+
+	/**
+	 * typert endpoint: replace the whole workspace-preferences document.
+	 *
+	 * Full replacement, not a patch: the client owns the document and sends it
+	 * whole, so a workspace the client dropped disappears here too. Dirty input is
+	 * normalized (invalid ids/values degrade to defaults) and never throws; the
+	 * write is best effort, like the other advisory preference files.
+	 * @param request - `{ version: 1, workspaces: { ... } }`.
+	 * @returns the stored (normalized) document.
+	 */
+	async setWorkspacePrefs(request) {
+		if (request === null || typeof request !== 'object' || Array.isArray(request)) {
+			throw new Error('缺少 workspaces 参数')
+		}
+		this.workspacePrefs = normalizeWorkspacePrefs(request)
+		await this._saveWorkspacePrefs().catch(() => {}) // preference file is advisory
+		return normalizeWorkspacePrefs(this.workspacePrefs)
+	}
+
 	/**
 	 * typert endpoint: merge this browser's "seen" watermarks into the Host's copy.
 	 *

package/lib/icon/workspace-prefs.js

@@ -0,0 +1,129 @@
+/**
+ * dsh-lookout · 工作区偏好(标签/隐藏/置顶)的宿主半
+ *
+ * 只干两件事:
+ *   1. 把任意脏输入夹成一份**完整、可安全落盘**的偏好文档;
+ *   2. 在 $DSH_HOME/custom-favicon/workspace-prefs.json 上读/写这份文档。
+ *
+ * 设计约束(与 unread.js 的规则开关同一条思路):
+ *   * normalize 永不抛错 —— 文件被手改坏、客户端版本对不上,都只降级成默认值,
+ *     绝不因为一条偏好把图标/红点这些主功能一起带崩;
+ *   * 写盘 best effort —— 调用方(index.js)吞掉落盘错误,内存里的偏好照常生效;
+ *   * 文档整份覆盖 —— 客户端每次提交完整文档,宿主不保留任何"上一版残留"。
+ *
+ * 文档形状(version 固定为 1):
+ *   { "version": 1, "workspaces": { "<workspaceId>": { "tag", "color",
+ *     "pinned", "hidden", "pinAnchor" } } }
+ */
+import { readFileSync } from 'node:fs'
+import { mkdir, rename, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+
+/** 文档版本。未来改结构时靠它整份丢弃旧文档,而不是猜字段。 */
+export const WORKSPACE_PREFS_VERSION = 1
+
+/** 与 library.json / unread.json 同目录:custom-favicon/。 */
+export const WORKSPACE_PREFS_FILE = 'workspace-prefs.json'
+
+/** 标签颜色白名单。非法颜色一律落到 gray,不猜"最接近的颜色"。 */
+export const WORKSPACE_COLORS = ['red', 'orange', 'yellow', 'green', 'cyan', 'blue', 'purple', 'gray']
+
+/** 非法/缺省颜色。 */
+export const WORKSPACE_COLOR_DEFAULT = 'gray'
+
+/** 标签最多 6 个 Unicode 字符(不是 UTF-16 单元:emoji 也只算一个)。 */
+export const WORKSPACE_TAG_MAX = 6
+
+/** 工作区 id 长度上限(与客户端约定一致)。 */
+export const WORKSPACE_ID_MAX = 200
+
+/** 危险对象键:绝不能通过 JSON 里的 `__proto__` 改到原型。 */
+const UNSAFE_KEYS = new Set(['__proto__', 'constructor', 'prototype'])
+
+/** 空文档。文件缺失/损坏/版本未知时都用它。 */
+export function emptyWorkspacePrefs() {
+	return { version: WORKSPACE_PREFS_VERSION, workspaces: {} }
+}
+
+/** 只留可打印字符:去掉控制字符(Cc),再 trim。 */
+export function normalizeTag(input) {
+	if (typeof input !== 'string') return ''
+	const cleaned = input.replace(/\p{Cc}/gu, '').trim()
+	return [...cleaned].slice(0, WORKSPACE_TAG_MAX).join('')
+}
+
+/** 颜色白名单,非法回落 gray。 */
+export function normalizeColor(input) {
+	return WORKSPACE_COLORS.includes(input) ? input : WORKSPACE_COLOR_DEFAULT
+}
+
+/**
+ * 夹一个工作区条目。未知字段丢弃,坏类型一律降级:
+ * tag 非法 → '';color 非法 → 'gray';pinned/hidden 非 true → false;
+ * pinAnchor 非 string → null。
+ */
+export function normalizeWorkspaceEntry(input) {
+	const source = input !== null && typeof input === 'object' && !Array.isArray(input) ? input : {}
+	return {
+		tag: normalizeTag(source.tag),
+		color: normalizeColor(source.color),
+		// 只认真正的 true:字符串 'true' / 1 都不能把工作区置顶或藏起来。
+		pinned: source.pinned === true,
+		hidden: source.hidden === true,
+		pinAnchor: typeof source.pinAnchor === 'string' ? source.pinAnchor : null
+	}
+}
+
+/** 工作区 id 是否可用:非空 string,长度不超过 200。 */
+export function isValidWorkspaceId(input) {
+	return typeof input === 'string' && input.length > 0 && input.length <= WORKSPACE_ID_MAX
+}
+
+/**
+ * 把任意输入夹成完整文档 —— 永不抛错。
+ * @param {unknown} input - 可能是 null、数组、字符串、缺字段、字段类型全错的对象,或一份旧文档
+ * @returns {{ version: 1, workspaces: Record<string, { tag: string, color: string, pinned: boolean, hidden: boolean, pinAnchor: string | null }> }}
+ */
+export function normalizeWorkspacePrefs(input) {
+	const document = emptyWorkspacePrefs()
+	if (input === null || typeof input !== 'object' || Array.isArray(input)) return document
+	const workspaces = input.workspaces
+	if (workspaces === null || typeof workspaces !== 'object' || Array.isArray(workspaces)) return document
+	for (const [workspaceId, entry] of Object.entries(workspaces)) {
+		if (!isValidWorkspaceId(workspaceId) || UNSAFE_KEYS.has(workspaceId)) continue
+		document.workspaces[workspaceId] = normalizeWorkspaceEntry(entry)
+	}
+	return document
+}
+
+/** 偏好文件路径(与图标库同目录)。 */
+export function workspacePrefsFilePath(storageDir) {
+	return join(storageDir, WORKSPACE_PREFS_FILE)
+}
+
+/**
+ * 读偏好文档。文件缺失、空文件、坏 JSON、版本/结构不对 —— 一律返回空文档,绝不抛错。
+ * 同步读:与 index.js 其余"启动时读一次"的文件保持一致,调用方不必等 Promise。
+ */
+export function readWorkspacePrefs(filePath) {
+	try {
+		const raw = readFileSync(filePath, 'utf8').replace(/^\uFEFF/, '')
+		return normalizeWorkspacePrefs(JSON.parse(raw))
+	} catch {
+		return emptyWorkspacePrefs()
+	}
+}
+
+/**
+ * 原子写偏好文档:先写 `<file>.tmp`,再 rename 覆盖正式文件,
+ * 这样进程在写一半时被杀也不会留下半截 JSON(照 unread-seen.json 的写法)。
+ * 失败会 throw,由调用方决定是否吞掉 —— 偏好文件是 advisory(尽力而为)。
+ */
+export async function writeWorkspacePrefs(filePath, prefs) {
+	const document = normalizeWorkspacePrefs(prefs)
+	await mkdir(dirname(filePath), { recursive: true })
+	const tmp = `${filePath}.tmp`
+	await writeFile(tmp, JSON.stringify(document, null, 2))
+	await rename(tmp, filePath)
+	return document
+}

package/lib/index.js

@@ -14,15 +14,41 @@
  * 合并后的 lib/typert.host.js 是唯一的 typert 清单(package.json 的
  * exports["./typert"] 指向它),里面的服务命名空间 iconCustom / mailNotify
  * 原样保留 —— 浏览器侧的调用串依赖这两个名字。
+ *
+ * 另外还有一件事必须在**模块顶层**做(不是接线,但只能放在这里):
+ * 导出 `Config`(见下方)。设置页读的就是入口模块的这个导出。
  */
 import { FaviconCustomService } from './icon/index.js'
 import { apply as applyNotify } from './notify/index.js'
 import { apply as applySessionInfo } from './session/index.js'
+import { MailSchema } from './notify/config.js'
 
 export const name = 'dsh-lookout'
 
-/** A 的 static inject(webServer) ∪ B 的 inject(sessions, settings)。 */
-export const inject = ['webServer', 'sessions', 'settings']
+/**
+ * A 的 static inject(webServer) ∪ B 的 inject(sessions)。
+ *
+ * 这里**没有 settings**：B 的配置就是它自己的入口 config（lib/notify/config.js 的
+ * MailSchema），代码里没有任何 `ctx.settings` 调用；留着这条 inject 只会让插件
+ * 多等一个用不到的服务，还会让人误以为配置来自 settings 服务。
+ */
+export const inject = ['webServer', 'sessions']
+
+/**
+ * 本插件的配置 schema —— **设置页能用的前提，不能删**。
+ *
+ * DSH 0.2.x 的 dsh-settings 从 `entry.fiber.runtime.Config` 取 schema
+ * （见 dsh-settings 的 `schema(entry)`）。没有这个导出，`describe()` 直接跳过
+ * 本 entry —— 设置页只会显示「这一页读不到本插件的配置」，读不到也写不进。
+ *
+ * 两条硬约束：
+ *   1. 必须在**模块顶层**导出，settings 服务读的是模块的导出，不是 apply 的产物；
+ *   2. schema 里 15 个字段全部标了 `.volatile()`（见 lib/notify/config.js），
+ *      否则 `volatileForm()` 返回 undefined，同样被跳过。
+ *
+ * 只做转手：schema 本体仍住在 lib/notify/config.js，这里不复制、不改写。
+ */
+export const Config = MailSchema
 
 // 具名再导出:合并清单里两条 service 的 exportName 指向这两个类名。
 export { FaviconCustomService }
@@ -31,7 +57,7 @@ export { MailNotifyRemoteService } from './notify/service.js'
 /**
  * 插件入口。三段装配按 A → B → C 的顺序执行。
  * @param {import('@deepseek-ai/cordis').Context} ctx 插件上下文
- * @param {object} [config] cordis 行的 config(组合层默认值;B 自己会接 settings)
+ * @param {object} [config] cordis 行的 config(组合层默认值;B 每次读活的它,不缓存)
  * @returns {void}
  */
 export function apply(ctx, config) {

package/lib/notify/config.js

@@ -1,180 +1,175 @@
 // dsh-notify-p · 配置层
 //
-// 一个 settings namespace 承载全部非机密配置（落 $DSH_HOME/settings.yaml），
+// 全部非机密配置都来自组合层入口：$DSH_HOME/profiles/<profile>/cordis.patch.yml
+// 里本插件 entry 的 `config:`（运行时以 volatile 引用交给 apply，见下面的 unwrapVolatile）。
 // 机密（SMTP 授权码）只在这里存"引用名"，真值在凭据库
-// （$DSH_HOME/.credentials.yaml 或同名环境变量）——settings 文档里永不出现密钥。
+// （$DSH_HOME/.credentials.yaml 或同名环境变量）——配置文件里永不出现密钥。
 //
 // 本文件只依赖 schemastery，不碰 cordis，便于单测。
 
 import z from '@deepseek-ai/schemastery';
 
-/** settings namespace；客户端卡片以同名 key 注册到 settings.plugin.item。 */
-export const NAMESPACE = 'dsh-notify-p';
-
 /** 默认凭据引用名（与 $DSH_HOME/.credentials.yaml 的键同名）。 */
 export const DEFAULT_SMTP_PASSWORD_REF = 'DSH_MAIL_NOTIFY_SMTP_PASSWORD';
 
-/** 发件人显示名的默认值（清单里某条留空显示名时也用它）。 */
+/**
+ * 发件人显示名（固定值）。
+ *
+ * 发件地址固定用 smtpUser——发件人清单与旧发件人字段已整块删除，
+ * 这里只剩一个固定显示名，不再走任何配置字段。
+ */
 export const DEFAULT_SENDER_NAME = 'DSH 通知 / DSH Notification';
 
+// ---- 节奏参数：界面不再暴露，硬编码 ----
+//
+// 这三个值以前是配置字段（settleMs / minDurationMs / ratePerMinute），
+// 现在从 schema 里删掉了：设置页不再出现它们，行为与原来的默认值完全一致。
+// 想改节奏请改这里的常量（需要重新加载插件）。
+
+/** 空闲合并窗口：turn/end 后再等这么久，期间若同会话又开新轮则合并成一封。 */
+export const SETTLE_MS = 1500;
+
+/** 短任务不打扰：会话总时长低于此值不发（只对"完成"生效）。 */
+export const MIN_DURATION_MS = 2000;
+
+/** 全局发信速率上限（封/分钟），多会话并停时保护 SMTP。 */
+export const RATE_PER_MINUTE = 10;
+
 /**
  * 本插件的完整配置 schema。
  * 每个字段都会出现在「设置 → 插件 → 插件配置 → 邮件通知」卡片上（中英并列）。
+ *
+ * 发件人身份与「邮件直达链接」两条能力已整块删除：相关字段一条都不剩。
+ * 发件地址固定用 smtpUser，邮件正文不带任何链接。
+ *
+ * ⚠️ 两条不能删的约束（DSH 0.2.x 的 settings 契约，见 docs/adr/0005）：
+ *
+ *   1. **本 schema 必须由入口模块（lib/index.js）以 `Config` 的名字导出**。
+ *      dsh-settings 的 `schema(entry)` 只读 `entry.fiber.runtime.Config`；
+ *      没有这个导出，`describe()` 直接跳过本 entry —— 设置页显示
+ *      「这一页读不到本插件的配置」，读不到也写不进。
+ *   2. **每个字段都必须 `.volatile()`**。settings 的 `volatileForm()` 只把
+ *      `meta.volatile` 的字段算作可编辑：一个都没有时它返回 undefined，
+ *      `describe()` 同样跳过；写回还会报 `has no volatile fields`。
+ *
+ * 附带后果（很重要，别当成 bug）：标了 volatile 的字段在 schemastery 校验时
+ * 会被包成 **volatile 引用**（`{ get(), [Symbol.for('cosmokit.volatile.write')] }`），
+ * 运行中的 config 对象里存的就是这种引用，见下面 `unwrapVolatile()` 的注释。
  */
 export const MailSchema = z.object({
   /** 总开关。关掉后插件只订阅不动作。 */
-  enabled: z.boolean().default(true),
+  enabled: z.boolean().default(true).volatile(),
 
   /** 收件人：一行一个（也接受逗号/分号分隔）。 */
-  recipients: z.string().default(''),
-
-  /**
-   * 发件人显示名（**旧字段**，与 fromAddress 一起被 senders 取代）。
-   * 留着是为了老配置照常发信；新配置只写 senders，见 senderList() 的迁移约定。
-   */
-  senderName: z.string().default(DEFAULT_SENDER_NAME),
-
-  /**
-   * 发件人地址（**旧字段**）；留空时按 transport 取默认（SMTP 用 smtpUser）。
-   *
-   * 写 senders 时必须**同一批 op 里清掉它**，否则删光的清单会让它复活。
-   * @deprecated 用 senders + activeSender。
-   */
-  fromAddress: z.string().default(''),
-
-  /**
-   * 发件人清单：保存所有发件身份，发信时用 activeSender 选中的那条。
-   *
-   * 空数组的语义是"没设置过 vs 显式清空"分不清：settings 的 describe() 返回 schema 解析后的
-   * 完整值，没写过 senders 的老配置读出来也是 `[]`，跟"用户删光了"长得一模一样。约定是
-   * **非空才作数，空了回落到旧的 senderName/fromAddress**。
-   *
-   * 这里**允许删光**：设置页写列表时会在同一批 op 里把 fromAddress/senderName 一并清掉，
-   * 刚删掉的那条不会借旧字段"复活"。
-   */
-  senders: z.array(z.object({
-    /** 显示名；留空 = 用默认显示名，由 resolveSender 兜底（不把本地化默认值写进配置）。 */
-    name: z.string().default(''),
-    /** 邮箱地址；清单里的每条都必须是能用的 From。 */
-    address: z.string(),
-  })).default([]),
-
-  /** 当前生效的发件人。**记地址而不是序号**——删掉前面一条时序号会整体错位。 */
-  activeSender: z.string().default(''),
-
-  /** 邮件里链接的对外地址，如 http://127.0.0.1:3081 或 https://dsh.example.com；留空则读 DSH_WEB_URL。 */
-  publicBaseUrl: z.string().default(''),
-
-  /** 是否在邮件里附带"直达会话"链接（需要另装 dsh-deeplink / dsh-session-link 才能被识别）。 */
-  linkEnabled: z.boolean().default(true),
+  recipients: z.string().default('').volatile(),
 
   /** 是否也通知子代理会话（默认关：一个 workflow 能扇出几十个子会话）。 */
-  includeSubagents: z.boolean().default(false),
-
-  /** 空闲合并窗口：turn/end 后再等这么久，期间若同会话又开新轮则合并成一封。 */
-  settleMs: z.natural().default(1500),
-
-  /** 短任务不打扰：会话总时长低于此值不发。 */
-  minDurationMs: z.natural().default(2000),
-
-  /** 全局发信速率上限（封/分钟），多会话并停时保护 SMTP。 */
-  ratePerMinute: z.natural().default(10),
-
-  /** 投递账本路径；留空 = $DSH_HOME/dsh-notify-p/state.json（排错时 cat 它）。 */
-  statePath: z.string().default(''),
+  includeSubagents: z.boolean().default(false).volatile(),
 
-  // ---- SMTP（唯一的发送通道）----
-  smtpHost: z.string().default(''),
-  smtpPort: z.natural().max(65535).default(465),
+  // ---- SMTP（唯一的发送通道；smtpUser 同时是发件地址）----
+  smtpHost: z.string().default('').volatile(),
+  smtpPort: z.natural().max(65535).default(465).volatile(),
   /** auto：465 走隐式 TLS，其余走 STARTTLS。 */
-  smtpSecure: z.union([z.const('auto'), z.const('tls'), z.const('starttls'), z.const('plain')]).default('auto'),
-  smtpUser: z.string().default(''),
+  smtpSecure: z.union([z.const('auto'), z.const('tls'), z.const('starttls'), z.const('plain')]).default('auto').volatile(),
+  smtpUser: z.string().default('').volatile(),
   /** 凭据引用名，不是密码本身。 */
-  smtpPasswordRef: z.string().default(DEFAULT_SMTP_PASSWORD_REF),
+  smtpPasswordRef: z.string().default(DEFAULT_SMTP_PASSWORD_REF).volatile(),
 
   // ---- 事件开关 ----
-  notifyCompleted: z.boolean().default(true),
-  notifyError: z.boolean().default(true),
-  notifyBlocked: z.boolean().default(true),
+  notifyCompleted: z.boolean().default(true).volatile(),
+  notifyError: z.boolean().default(true).volatile(),
+  notifyBlocked: z.boolean().default(true).volatile(),
   /** 只有 aborted.reason.kind === 'user'（真·你主动停止）才算。 */
-  notifyAbortedByUser: z.boolean().default(false),
+  notifyAbortedByUser: z.boolean().default(false).volatile(),
   /** 重启/热更/被父级取消 等系统中断。 */
-  notifyInterrupted: z.boolean().default(false),
-  notifyMaxTokens: z.boolean().default(false),
-  notifyApproval: z.boolean().default(true),
+  notifyInterrupted: z.boolean().default(false).volatile(),
+  notifyMaxTokens: z.boolean().default(false).volatile(),
+  notifyApproval: z.boolean().default(true).volatile(),
 });
 
+// ---- volatile 引用：读配置前必须先拆掉这层壳 ----
+//
+// 字段标了 .volatile() 之后，schemastery 在校验时把每个值包成 cosmokit 的
+// **volatile 引用**（`Object.freeze({ get, [Symbol.for('cosmokit.volatile.write')] })`）。
+// 这不是本插件的发明，是 DSH 0.2.x 的运行态真相：
+//
+//   * 插件拿到 config 时，标了 volatile 的字段已经是引用对象（不是裸值）；
+//   * 设置页保存走 cordis-plugin-loader 的 `_commitVolatile`：它**原地**把新值写进
+//     这些引用（`updateVolatile(ref, source)` → `ref[write](source.get())`），
+//     **不会重跑 apply**。所以"每次读活的 config"= 每次都从引用里 `.get()`，
+//     而不是把启动时解析出来的那份对象当真相。
+//   * 反过来，把引用对象喂回 schema 会直接校验失败
+//     （`$.smtpHost expected string but got [object Object]`），所以入参也要先拆壳。
+//
+// 用 `Symbol.for()` 取协议键：全局符号表是进程级的，不需要 import cosmokit
+// （本插件的模块图刻意不出现 DSH 裸包名，理由见 lib/deps.js 那类注释）。
+
+/** cosmokit volatile 引用协议键（与 cordis 用的是同一个全局符号）。 */
+const VOLATILE_WRITE = Symbol.for('cosmokit.volatile.write');
+
 /**
- * schema 默认值（也给 cordis 行 config 缺省时兜底）。
- * @returns {object} 完整默认配置
+ * 判断一个值是不是 cosmokit 的 volatile 引用。
+ * @param {unknown} value 候选值
+ * @returns {boolean}
  */
-export function defaultConfig() {
-  return MailSchema({});
+export function isVolatileRef(value) {
+  return value !== null
+    && typeof value === 'object'
+    && typeof value.get === 'function'
+    && VOLATILE_WRITE in value;
 }
 
 /**
- * 把（可选）组合层入口配置解析成完整配置。
- * @param {object} [entry] cordis 行的 config
- * @returns {object} 补齐默认值后的配置
+ * 递归拆掉 volatile 引用，返回**全新**的普通对象（绝不改动传进来的对象——
+ * 它可能是 loader 正在用的那份 config）。
+ * @template T
+ * @param {T} value 可能含引用的值
+ * @returns {T} 拆壳后的普通值
  */
-export function resolveConfig(entry) {
-  return MailSchema(entry ?? {});
+export function unwrapVolatile(value) {
+  if (isVolatileRef(value)) return unwrapVolatile(value.get());
+  if (Array.isArray(value)) return value.map((item) => unwrapVolatile(item));
+  if (value !== null && typeof value === 'object') {
+    const proto = Object.getPrototypeOf(value);
+    // 只递归普通对象：Date / Map / 类实例原样带过，免得把别的东西拆坏
+    if (proto !== Object.prototype && proto !== null) return value;
+    const out = {};
+    for (const [key, child] of Object.entries(value)) out[key] = unwrapVolatile(child);
+    return out;
+  }
+  return value;
 }
 
 /**
- * 归一化发件人清单，并把**老配置迁移**成清单。
- *
- * 迁移规则：`senders` 非空就作数；为空且旧 `fromAddress` 有值时，合成唯一一条
- * `{ name: senderName, address: fromAddress }`。旧地址为空时**不迁移**——
- * 那时旧行为本来就是"回退到默认"，与"清单为空"完全等价，凭空造一条反而会改变行为。
- * @param {object} [config] 已解析配置（或任何带 senders / fromAddress 的对象）
- * @returns {{ name: string, address: string }[]} 去空、去重后的清单（可能为空）
+ * schema 默认值（也给 cordis 行 config 缺省时兜底）。
+ * @returns {object} 完整默认配置
  */
-export function senderList(config) {
-  const raw = Array.isArray(config?.senders) ? config.senders : [];
-  const list = [];
-  const seen = new Set();
-  for (const entry of raw) {
-    const address = String(entry?.address ?? '').trim();
-    if (address === '') continue; // 地址是唯一必填项：没有地址的条目等于没配置
-    const key = address.toLowerCase();
-    if (seen.has(key)) continue;
-    seen.add(key);
-    list.push({ name: String(entry?.name ?? '').trim(), address });
-  }
-  if (list.length > 0) return list;
-
-  const address = String(config?.fromAddress ?? '').trim();
-  if (address === '') return [];
-  return [{ name: String(config?.senderName ?? '').trim(), address }];
+export function defaultConfig() {
+  return resolveConfig({});
 }
 
 /**
- * 解析"这次用哪个发件人"。
+ * 把（可选）组合层入口配置解析成完整配置。
  *
- * 选中项按**地址**匹配；地址已被删掉（或压根没设过）就退回清单第一条。
- * 清单为空时回落到旧的 senderName/fromAddress，显示名再兜底到默认值——
- * 所以老配置一行都不用改，行为与加清单之前完全一致。
- * @param {object} [config] 已解析配置
- * @returns {{ name: string, address: string }} 生效的发件人；清单为空且无旧值时 address 为 ''
+ * 入参可以是：cordis 行 config（可能含 volatile 引用）、settings 读到的值、
+ * 或者上一层的解析结果。出参**永远是裸值的普通对象**——调用方（发信判定、
+ * 渲染、测试邮件）都按裸值用，谁也不必再关心 volatile 这层壳。
+ * @param {object} [entry] cordis 行的 config（活的、可原地更新的那个对象）
+ * @returns {object} 补齐默认值后的配置
  */
-export function resolveSender(config) {
-  const list = senderList(config);
-  const wanted = String(config?.activeSender ?? '').trim().toLowerCase();
-  const picked = list.find((entry) => entry.address.toLowerCase() === wanted) ?? list[0];
-
-  if (picked !== undefined) {
-    const name = picked.name !== '' ? picked.name : String(config?.senderName ?? '').trim();
-    return { name: name !== '' ? name : DEFAULT_SENDER_NAME, address: picked.address };
-  }
-  return { name: String(config?.senderName ?? '').trim() || DEFAULT_SENDER_NAME, address: '' };
+export function resolveConfig(entry) {
+  // 先拆入参的壳（引用喂回 schema 会校验失败），再拆出参的壳（schema 会重新包上）
+  return unwrapVolatile(MailSchema(unwrapVolatile(entry ?? {})));
 }
 
 /**
  * SMTP 缺什么（发信前能查出来的）。
  *
- * 只查"SMTP 特有"的必填项；收件人、发件人之类跟发送方式无关的，由调用方查一次，
+ * 只查"SMTP 特有"的必填项；收件人这类跟发送方式无关的，由调用方查一次，
  * 免得同一句话被重复报。
+ *
+ * 发件地址固定取 smtpUser（见 send/index.js 的 resolveFrom），所以"发件人地址为空"
+ * 这件事不会单独出现：用户名查过就够了。
  * @param {object} config 已解析配置
  * @returns {string[]} 问题列表（空数组表示没发现明显问题）
  */
@@ -187,7 +182,6 @@ export function smtpIssues(config) {
   if (String(config?.smtpUser ?? '').trim() === '') {
     issues.push('SMTP 用户名为空（通常是你的完整邮箱地址）/ smtpUser is empty');
   }
-  // 发件人地址不在这里报：拿不到时 SMTP 会退回 smtpUser（见 resolveFrom），那是合法的。
   return issues;
 }
 
@@ -253,31 +247,3 @@ export function parseRecipients(raw) {
   }
   return { valid, invalid };
 }
-
-/**
- * 解析邮件里链接的基地址：优先用户配置，其次 DSH_WEB_URL，最后回退回环地址。
- * @param {object} config 已解析配置
- * @param {string} [webUrl] 运行时探测到的 Web GUI 地址
- * @returns {string} 不带结尾斜杠的基地址；都拿不到时返回空串
- */
-export function resolveBaseUrl(config, webUrl) {
-  const raw = typeof config?.publicBaseUrl === 'string' && config.publicBaseUrl.trim() !== ''
-    ? config.publicBaseUrl
-    : (typeof webUrl === 'string' ? webUrl : '');
-  return String(raw).trim().replace(/\/+$/, '');
-}
-
-/**
- * 拼一条"直达会话"链接。
- *
- * 本插件**不实现** `?session=` 的接收端——那由 dsh-deeplink（或 dsh-session-link）负责。
- * 这里只负责把链接拼对放进正文。
- * @param {string} baseUrl 基地址（已去掉结尾斜杠）
- * @param {string} sessionId 会话 ID
- * @returns {string} 形如 http://127.0.0.1:3081/?session=session-xxxx；baseUrl 为空时返回空串
- */
-export function sessionLink(baseUrl, sessionId) {
-  if (typeof baseUrl !== 'string' || baseUrl === '') return '';
-  if (typeof sessionId !== 'string' || sessionId === '') return '';
-  return `${baseUrl}/?session=${encodeURIComponent(sessionId)}`;
-}