@fa-software/semi2-dsh 0.0.16 → 0.0.17-preview.20260929054409

package/lib/domains/models/web-search.js

@@ -1,11 +1,11 @@
 import { codeOf } from "../../hub/errors.js";
-import { hasSection, sectionValue, userSection } from "../../service/namespaces.js";
+import { hasSection } from "../../service/namespaces.js";
 const WEB_SEARCH_DEEPSEEK_NAMESPACE = 'web-search-deepseek';
 const WEB_SEARCH_API_KEY_ENV_KEY = 'apiKeyEnv';
 const DEFAULT_DEEPSEEK_SEARCH_KEY_ENV = 'DEEPSEEK_API_KEY';
 /**
  * 官方搜索默认解析 `DEEPSEEK_API_KEY`，而 hub 下发的是连接级引用；这里只对齐引用，
- * 搜索端点与其他搜索配置仍归本地配置的所有者。
+ * 搜索端点与其他搜索配置仍归本地配置的所有者。接管判定用写瞬间的生效值（官方事务内）。
  * @returns 本进程写进该段的引用；null = 没写或已交还用户。
  */
 export async function syncWebSearchKeyEnv(host, run, deepseek, previous) {
@@ -15,25 +15,29 @@ export async function syncWebSearchKeyEnv(host, run, deepseek, previous) {
             host.warn('DeepSeek 网页搜索密钥引用同步失败，搜索按当前本地配置继续');
         return previous;
     }
-    const current = webSearchKeyEnvOf(run.settings);
-    // 用户自写的引用（或组合层默认之外的既有值）不接管：只有我们写过的前值才覆盖。
-    if (current !== undefined &&
-        current !== previous &&
-        current !== DEFAULT_DEEPSEEK_SEARCH_KEY_ENV)
-        return null;
     try {
-        await host.ports.replaceNamespace(run.settings, WEB_SEARCH_DEEPSEEK_NAMESPACE, {
-            ...userSection(run.settings, WEB_SEARCH_DEEPSEEK_NAMESPACE),
-            [WEB_SEARCH_API_KEY_ENV_KEY]: deepseek.apiKeyEnv,
+        return await host.ports.replaceNamespace(run.settings, WEB_SEARCH_DEEPSEEK_NAMESPACE, (view) => {
+            const current = keyEnvOf(view);
+            // 用户自写的引用（或组合层默认之外的既有值）不接管：只有我们写过的前值才覆盖。
+            if (current !== undefined &&
+                current !== previous &&
+                current !== DEFAULT_DEEPSEEK_SEARCH_KEY_ENV)
+                return { write: null, result: null };
+            return {
+                write: {
+                    kind: 'section',
+                    section: { ...view.user, [WEB_SEARCH_API_KEY_ENV_KEY]: deepseek.apiKeyEnv },
+                },
+                result: deepseek.apiKeyEnv,
+            };
         });
     }
     catch (error) {
         host.warn(`DeepSeek 网页搜索密钥引用同步失败（${codeOf(error)}），搜索按当前本地配置继续`);
         return previous;
     }
-    return deepseek.apiKeyEnv;
 }
-function webSearchKeyEnvOf(settings) {
-    const value = sectionValue(settings, WEB_SEARCH_DEEPSEEK_NAMESPACE).apiKeyEnv;
+function keyEnvOf(view) {
+    const value = view.value[WEB_SEARCH_API_KEY_ENV_KEY];
     return typeof value === 'string' && value !== '' ? value : undefined;
 }

package/lib/service/config-service.js

@@ -18,6 +18,14 @@ export function installConfiguration(ctx, options = {}) {
             // 无 logger 的宿主（单测）忽略。
         }
     };
+    // 生命周期操作单飞（官方 saveSelection 同款 promise 链）：load / 登录 / 登出 / 同步交错时
+    // 按到达顺序整段落定——设置事务、credentials 与 saveSelection 三类写由此一并有序。
+    let opTail = Promise.resolve();
+    const run = (op) => {
+        const next = opTail.then(op, op);
+        opTail = next.then(() => undefined, () => undefined);
+        return next;
+    };
     const ports = createPorts(ctx, warn, options);
     // api 门面读连接凭据的桥：闭包延迟求值（编排层构造完成后才可能被调用）。
     const engineRef = { current: undefined };
@@ -34,16 +42,16 @@ export function installConfiguration(ctx, options = {}) {
     installSessionReporting(orchestrator);
     void orchestrator
         .mountDomains()
-        .then(() => lifecycle.start(orchestrator))
+        .then(() => run(() => lifecycle.start(orchestrator)))
         .catch((error) => {
         warn(`首次领取失败：${error instanceof Error ? error.message : String(error)}`);
     });
     return {
         config: new ConfigService(orchestrator),
         session: {
-            login: input => lifecycle.login(orchestrator, input),
-            logout: () => lifecycle.logout(orchestrator),
-            sync: scope => lifecycle.syncByScope(orchestrator, scope),
+            login: input => run(() => lifecycle.login(orchestrator, input)),
+            logout: () => run(() => lifecycle.logout(orchestrator)),
+            sync: scope => run(() => lifecycle.syncByScope(orchestrator, scope)),
         },
         health: { snapshot: () => healthSnapshot(orchestrator) },
         status: () => statusSection(orchestrator),

package/lib/service/namespaces.js

@@ -1,24 +1,11 @@
-/** 本插件自铸的名字形状：路由 `semi2-<32 hex>`、密钥引用 `SEMI2_MODEL_KEY_<大写 hex>`。 */
+/** 本插件自铸的路由名形状：`semi2-<32 hex>`（密钥引用名由 hub/compile 的 connectionApiKeyEnv 自铸）。 */
 export const SELF_MINTED_ROUTE = /^semi2-[\da-f]{32}$/;
-export const SELF_MINTED_KEY_ENV = /^SEMI2_MODEL_KEY_[\dA-F]+$/;
 /** 本插件在官方 `llm-deepseek` 段表达过的三个键：服务端撤下 DEEPSEEK 连接时一并清掉。 */
 export const DEEPSEEK_OVERRIDE_KEYS = ['apiKeyEnv', 'baseURL', 'models'];
-/** 一个设置段的当前有效值：官方描述符的 `value` 是不透明值，本插件只认对象段，其余按空段处理。 */
-export function sectionValue(settings, ns) {
-    const value = settings.describe().find(entry => entry.ns === ns)?.value;
-    return isRecord(value) ? value : {};
-}
 /** 设置段是否已可描述（条目 ACTIVE 且声明了 volatile 字段）。 */
 export function hasSection(settings, ns) {
     return settings.describe().some(entry => entry.ns === ns);
 }
-/**
- * 该段的**用户层**原始内容（只认 `describe()` 的 `user`：组合层与 schema 默认不算用户写过）。
- * 写入前用它保住用户写在同一段里的其他键——`replace` 会把用户层整体对齐到给定内容。
- */
-export function userSection(settings, ns) {
-    return persistedSection(settings.describe(), ns);
-}
 /**
  * 该段的**组合层**内容（`describe()` 的 `base`，已带 schema 默认）＝部署默认；
  * 登出撤下默认模型时用它把选择交还给组合层。
@@ -30,8 +17,3 @@ export function baseSection(settings, ns) {
 function isRecord(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
-/** 用户层事实（`describe()` 的 `value` 含默认与组合层，`user` 才是用户写下的那一层）。 */
-function persistedSection(entries, ns) {
-    const entry = entries.find(row => row.ns === ns);
-    return isRecord(entry?.user) ? entry.user : {};
-}

package/lib/service/ports.js

@@ -1,31 +1,17 @@
-import { setTimeout as delay } from 'node:timers/promises';
-import { ConfigurationError } from "../hub/errors.js";
-import { createHostWrites } from "./host-writes.js";
+import { transact, } from "./settings-tx.js";
 const SETTINGS_TIMEOUT_MS = 5_000;
 const NAMESPACE_WAIT_MS = 2_000;
-/** 设置段就绪轮询间隔（纯内部预算，不单列到 Config）。 */
-const NAMESPACE_POLL_MS = 50;
+const WRITE_TIMEOUT_MS = 3_000;
 export function createPorts(ctx, warn, options = {}) {
     const settingsTimeoutMs = options.settingsTimeoutMs ?? SETTINGS_TIMEOUT_MS;
     const namespaceWaitMs = options.namespaceWaitMs ?? NAMESPACE_WAIT_MS;
-    const writes = createHostWrites(warn, {
-        // 宿主就绪门 = profile 的 loader 条目树：设置写入内部等的就是它。服务缺席（宿主直跑 / 假宿主）立即放行。
-        ready: () => {
-            const loader = ctx.get('loader', false);
-            return Promise.resolve(loader?.await?.());
-        },
-        writeTimeoutMs: options.writeTimeoutMs,
-    });
+    const writeTimeoutMs = options.writeTimeoutMs ?? WRITE_TIMEOUT_MS;
+    const tx = { warn, namespaceWaitMs, writeTimeoutMs };
     const service = (key) => new Promise((resolve) => {
         ctx.inject([key], (injected) => {
             resolve(injected.get(key));
         });
     });
-    const requireNamespace = async (settings, ns) => {
-        if (await waitForNamespace(settings, ns, namespaceWaitMs))
-            return;
-        throw new ConfigurationError('CONFIG_APPLY_FAILED');
-    };
     const hasWorkspaceController = () => ctx.get('workspaceController', false) !== undefined;
     return {
         settings: () => {
@@ -43,36 +29,10 @@ export function createPorts(ctx, warn, options = {}) {
         credentialsNow: () => ctx.get('credentials', false),
         agentDefaultModel: () => ctx.get('agentDefaultModel', false),
         hasWorkspaceController,
-        replaceNamespace: async (settings, ns, section) => {
-            await requireNamespace(settings, ns);
-            const replace = settings.replace?.bind(settings);
-            if (replace === undefined) {
-                warn(`宿主 settings 无 replace，${ns} 退回合并写入：服务端已撤下的条目可能残留`);
-                await writes.run(ns, () => settings.update(ns, section));
-                return;
-            }
-            await writes.run(ns, () => replace(ns, section));
-        },
-        clearKeys: async (settings, ns, keys) => {
-            const mutate = settings.mutate?.bind(settings);
-            if (mutate === undefined) {
-                warn(`宿主 settings 无 mutate，${ns} 无法按路径删除：服务端已撤销的覆盖可能残留`);
-                return;
-            }
-            await requireNamespace(settings, ns);
-            const ops = keys.map(key => ({ op: 'unset', path: [key] }));
-            await writes.run(ns, () => mutate(ns, ops));
-        },
+        replaceNamespace: (settings, ns, plan) => transact(settings, ns, plan, tx),
+        clearKeys: (settings, ns, keys) => transact(settings, ns, () => ({
+            write: { kind: 'ops', ops: keys.map(key => ({ op: 'unset', path: [key] })) },
+            result: undefined,
+        }), tx),
     };
 }
-/** 等设置段可描述（条目 ACTIVE 且声明了 volatile 字段）；超时返回 false，不抛。 */
-async function waitForNamespace(settings, ns, waitMs) {
-    const deadline = Date.now() + waitMs;
-    for (;;) {
-        if (settings.describe().some(entry => entry.ns === ns))
-            return true;
-        if (Date.now() >= deadline)
-            return false;
-        await delay(NAMESPACE_POLL_MS);
-    }
-}

package/lib/service/sessions.js

@@ -36,7 +36,7 @@ async function scopeOf(engine, cwd) {
 /** 会话创建：带上工作区与默认模型选择，hub 据此建行。 */
 async function reportCreated(engine, session) {
     const scope = await scopeOf(engine, session.header.cwd);
-    const selection = engine.ctx.get('agentDefaultModel', false)?.currentSelection?.();
+    const selection = engine.ports.agentDefaultModel()?.currentSelection?.();
     await reportEvent(engine, {
         action: 'SESSION_CREATED',
         outcome: 'SUCCESS',

package/lib/service/settings-tx.js

@@ -0,0 +1,109 @@
+// @fa-software/semi2-dsh/service/settings-tx —— 官方设置事务：describe 现读 → 带 expectedRevision 写 → 冲突重读重算 → 超时降级。
+// 官方 write 在文件锁内与 Loader 热重载串行（dsh-config-editor 的 edit），跨写者互斥不归本模块；
+// 这里只补官方没有的两样：读改写一致性（CAS + 重算重试）与调用方有界等待。
+// 被超时放弃的那笔仍会照常落定或迟到时被 CAS 拒掉——两种结局都比无条件覆盖安全。
+import { SettingsConflictError } from '@deepseek-ai/dsh-settings';
+import { setTimeout as delay } from 'node:timers/promises';
+import { ConfigurationError } from "../hub/errors.js";
+/** 冲突重试上限（含首次）：并发编辑同一段（用户正在设置页写）给两次重算机会。 */
+const MAX_ATTEMPTS = 3;
+/** 设置段就绪轮询间隔（纯内部预算，不单列到 Config）。 */
+const NAMESPACE_POLL_MS = 50;
+/** 到点标记：与「底层真的返回了 undefined」区分开。 */
+const EXPIRED = Symbol('expired');
+/**
+ * 一笔官方设置事务。plan 必须是 view 的纯函数（外部输入放闭包里）：
+ * 冲突重试会用新鲜视图重调它，副作用（记账、集合填充）应以 result 带出而不是改外部状态。
+ */
+export async function transact(settings, ns, plan, options) {
+    if (!(await waitForNamespace(settings, ns, options.namespaceWaitMs)))
+        throw new ConfigurationError('CONFIG_APPLY_FAILED');
+    for (let attempt = 1;; attempt += 1) {
+        const view = viewOf(settings, ns);
+        const outcome = plan(view);
+        if (outcome.write == null)
+            return outcome.result;
+        try {
+            const settled = await within(applyWrite(settings, ns, outcome.write, view.revision, options), options.writeTimeoutMs);
+            if (settled === EXPIRED) {
+                options.warn(`${ns} 设置写入超时（${String(options.writeTimeoutMs)}ms），本端继续，状态可能落后`);
+                throw new ConfigurationError('CONFIG_APPLY_FAILED');
+            }
+            return outcome.result;
+        }
+        catch (error) {
+            if (isConflict(error)) {
+                if (attempt < MAX_ATTEMPTS)
+                    continue;
+                options.warn(`${ns} 设置写入连续冲突（${String(MAX_ATTEMPTS)} 次），本轮降级`);
+                throw new ConfigurationError('CONFIG_APPLY_FAILED');
+            }
+            throw error;
+        }
+    }
+}
+/** 写瞬间视图；宿主不提供 revision 时按 undefined（不带 CAS）透传。 */
+function viewOf(settings, ns) {
+    const entry = settings.describe().find(row => row.ns === ns);
+    return {
+        value: recordOf(entry?.value),
+        user: recordOf(entry?.user),
+        revision: typeof entry?.revision === 'number' ? entry.revision : undefined,
+    };
+}
+function recordOf(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+/** 落一笔写：section 走 replace（缺则回退 update 的合并写入）、ops 走 mutate；都带上 CAS。 */
+function applyWrite(settings, ns, write, revision, options) {
+    if (write.kind === 'ops') {
+        const mutate = settings.mutate?.bind(settings);
+        if (mutate === undefined) {
+            options.warn(`宿主 settings 无 mutate，${ns} 无法按路径删除：服务端已撤销的覆盖可能残留`);
+            return Promise.resolve();
+        }
+        return mutate(ns, write.ops, revision);
+    }
+    const replace = settings.replace?.bind(settings);
+    if (replace === undefined) {
+        options.warn(`宿主 settings 无 replace，${ns} 退回合并写入：服务端已撤下的条目可能残留`);
+        return settings.update(ns, write.section, revision);
+    }
+    return replace(ns, write.section, revision);
+}
+/** 官方冲突（读与写之间有人改了段）：按结构判 code，防闭包内模块实例分裂时漏认。 */
+function isConflict(error) {
+    return error instanceof SettingsConflictError ||
+        (error instanceof Error && error.code === 'SETTINGS_CONFLICT');
+}
+/** 到点返回 {@link EXPIRED}，否则原样给出结果；定时器总在返回前清掉。 */
+async function within(promise, ms) {
+    let timer;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((resolve) => {
+                timer = globalThis.setTimeout(() => {
+                    resolve(EXPIRED);
+                }, ms);
+            }),
+        ]);
+    }
+    finally {
+        if (timer !== undefined)
+            globalThis.clearTimeout(timer);
+    }
+}
+/** 等设置段可描述（条目 ACTIVE 且声明了 volatile 字段）；超时返回 false，不抛。 */
+export async function waitForNamespace(settings, ns, waitMs) {
+    const deadline = Date.now() + waitMs;
+    for (;;) {
+        if (settings.describe().some(entry => entry.ns === ns))
+            return true;
+        if (Date.now() >= deadline)
+            return false;
+        await delay(NAMESPACE_POLL_MS);
+    }
+}

package/lib/types/domains/models/domain.d.ts

@@ -1,5 +1,5 @@
 import type { DomainHost, DomainService, LoadRun, ModelsPeer, RevertRun } from '../types.ts';
-import { type CompiledConfiguration } from '../../hub/compile.ts';
+import type { CompiledConfiguration } from '../../hub/compile.ts';
 import type { Semi2ConfigState } from '../../hub/facts.ts';
 export declare class ModelsDomain implements DomainService, ModelsPeer {
     private readonly host;
@@ -29,11 +29,11 @@ export declare class ModelsDomain implements DomainService, ModelsPeer {
      * 发行 `llm-pi-ai` 的 `providers` 段：本插件的路由完全对齐服务端现状（含回收），用户自己写的路由原样保留。
      *
      * 预设路由键就是 dsh 的提供方 id，与用户手写的路由同名时以用户为准（改用自铸路由），
-     * 否则会把人家配置里的 `anthropic:` 段整段替换掉。
+     * 否则会把人家配置中的 `anthropic:` 段整段替换掉。让位判定看生效值（value 层），
+     * 认领回收只认用户层里的自铸名字——组合层条目由官方 `replace` 的 base 合并自行带回。
      *
      * @returns 实际落地的路由表（原路由键 → 最终路由键），调用侧据此改写默认模型与项目选择——
      * 让位后若仍按原路由键选模型，`agent-default-model` 会指向一条属于用户的路由。
      */
     private applyProviders;
-    private readProviders;
 }

package/lib/types/domains/models/web-search.d.ts

@@ -2,7 +2,7 @@ import type { CompiledDeepSeek } from '../../hub/compile.ts';
 import type { DomainHost, LoadRun } from '../types.ts';
 /**
  * 官方搜索默认解析 `DEEPSEEK_API_KEY`，而 hub 下发的是连接级引用；这里只对齐引用，
- * 搜索端点与其他搜索配置仍归本地配置的所有者。
+ * 搜索端点与其他搜索配置仍归本地配置的所有者。接管判定用写瞬间的生效值（官方事务内）。
  * @returns 本进程写进该段的引用；null = 没写或已交还用户。
  */
 export declare function syncWebSearchKeyEnv(host: DomainHost, run: LoadRun, deepseek: CompiledDeepSeek | null, previous: string | null): Promise<string | null>;

package/lib/types/hub/compile.d.ts

@@ -1,7 +1,7 @@
 import type { InputModality, ModelProtocol, ReasoningLevel, RuntimeBootQuery, RuntimeWorkspaceProjectsQuery } from '../api/generated/graphql.ts';
 /**
  * 生效可用目录的一条（连接启用 ∧ 模型启用 ∧ 存在性 ∧ 密钥齐备）。
- * 根字段可空：取数失败只让该字段为 null，故取 NonNullable 元素类型，null 由 runtime.ts 归一为空集合。
+ * 根字段可空：取数失败只让该字段为 null（形状见 api/index.ts 的 RuntimeBootFacts），各领域按降级处理。
  */
 export type RuntimeModel = NonNullable<RuntimeBootQuery['runtimeModels']>[number];
 export type RuntimeConnection = RuntimeModel['connection'];

package/lib/types/service/namespaces.d.ts

@@ -1,18 +1,10 @@
-import type { SettingsLike } from './ports.ts';
-/** 本插件自铸的名字形状：路由 `semi2-<32 hex>`、密钥引用 `SEMI2_MODEL_KEY_<大写 hex>`。 */
+import type { SettingsLike } from './settings-tx.ts';
+/** 本插件自铸的路由名形状：`semi2-<32 hex>`（密钥引用名由 hub/compile 的 connectionApiKeyEnv 自铸）。 */
 export declare const SELF_MINTED_ROUTE: RegExp;
-export declare const SELF_MINTED_KEY_ENV: RegExp;
 /** 本插件在官方 `llm-deepseek` 段表达过的三个键：服务端撤下 DEEPSEEK 连接时一并清掉。 */
 export declare const DEEPSEEK_OVERRIDE_KEYS: readonly ["apiKeyEnv", "baseURL", "models"];
-/** 一个设置段的当前有效值：官方描述符的 `value` 是不透明值，本插件只认对象段，其余按空段处理。 */
-export declare function sectionValue(settings: SettingsLike, ns: string): Record<string, unknown>;
 /** 设置段是否已可描述（条目 ACTIVE 且声明了 volatile 字段）。 */
 export declare function hasSection(settings: SettingsLike, ns: string): boolean;
-/**
- * 该段的**用户层**原始内容（只认 `describe()` 的 `user`：组合层与 schema 默认不算用户写过）。
- * 写入前用它保住用户写在同一段里的其他键——`replace` 会把用户层整体对齐到给定内容。
- */
-export declare function userSection(settings: SettingsLike, ns: string): Record<string, unknown>;
 /**
  * 该段的**组合层**内容（`describe()` 的 `base`，已带 schema 默认）＝部署默认；
  * 登出撤下默认模型时用它把选择交还给组合层。

package/lib/types/service/ports.d.ts

@@ -1,15 +1,9 @@
 import type { Context } from '@deepseek-ai/cordis';
 import type { CredentialProvider } from '@deepseek-ai/dsh-credentials';
 import type { AgentDefaultModelConfig } from '@deepseek-ai/dsh-agent-default-model';
-import type { SettingsForms } from '@deepseek-ai/dsh-settings';
 import type { ModelSelection } from '../hub/compile.ts';
-/**
- * 本插件消费的 host settings 服务接口：读 / 写口径照官方 `SettingsForms`。
- * 设置段 = Profile 插件条目 id，`describe()` 只列「光纤 ACTIVE 且 Config 声明了 volatile 字段」的条目，
- * 因此磁盘清理写与读都要先等目标条目可描述（内部 `requireNamespace`）；
- * `replace` / `mutate` / `configure` 是可缺的降级口。
- */
-export type SettingsLike = Pick<SettingsForms, 'describe' | 'update'> & Partial<Pick<SettingsForms, 'replace' | 'mutate' | 'configure'>>;
+import { type SettingsLike, type SettingsView, type TxPlan } from './settings-tx.ts';
+export type { SettingsLike, SettingsView, TxPlan } from './settings-tx.ts';
 /**
  * 本插件消费的 dsh agentDefaultModel 服务接口（默认模型与无头角色选择）。
  * 读口取自官方 `AgentDefaultModelConfig`；写入口径不变，档位是 hub 下发的普通字符串
@@ -18,18 +12,12 @@ export type SettingsLike = Pick<SettingsForms, 'describe' | 'update'> & Partial<
 export type AgentDefaultModelLike = Partial<Pick<AgentDefaultModelConfig, 'currentSelection'>> & {
     saveSelection(next: ModelSelection): Promise<void>;
 };
-/**
- * 本插件消费的 dsh loader 服务接口：`await()` 等整棵树空闲（设置写入的宿主就绪门）。
- */
-export interface LoaderLike {
-    await?: (() => Promise<unknown>) | undefined;
-}
 export interface PortsOptions {
     /** 等 settings 服务的上限（ms）。 */
     settingsTimeoutMs?: number | undefined;
     /** 等设置段可读可写的上限（ms）。 */
     namespaceWaitMs?: number | undefined;
-    /** 单次写盘的上限（ms；缺省见 host-writes）。 */
+    /** 单次写盘的上限（ms；缺省见 settings-tx）。 */
     writeTimeoutMs?: number | undefined;
 }
 export interface Ports {
@@ -44,13 +32,12 @@ export interface Ports {
     /** workspaceController 的即时宽松读取（缺席 = headless 应用，走隐式工作区）。 */
     hasWorkspaceController(): boolean;
     /**
-     * 权威写入：把该条目的用户层整体对齐到给定内容。
-     * `update` 是**递归合并**（dsh-settings 的 mergeLayers），只增不减——服务端撤掉的条目
-     * 会在本地留成残渣，provider 路由尤其致命：目录里已不存在的模型继续可选。
-     * `replace` 先回到组合层再合并给定字段，所以只用于本插件全权决定的段（`llm-pi-ai` 的 `providers`）。
+     * 权威写入（官方设置事务）：plan 拿写瞬间的 value / user / revision，冲突自动重算重试。
+     * `replace` 语义 = base ⊕ section，只用于本插件全权决定的段（`llm-pi-ai` 的 `providers`、
+     * `llm-deepseek` 的三键、`web-search-deepseek` 的 `apiKeyEnv`）；别的键用 `view.user` 原样带回。
      */
-    replaceNamespace(settings: SettingsLike, ns: string, section: object): Promise<void>;
-    /** 按路径删除本插件写过的键（合并写入删不掉；命中组合层的键会回继承该值）。 */
+    replaceNamespace<T>(settings: SettingsLike, ns: string, plan: (view: SettingsView) => TxPlan<T>): Promise<T>;
+    /** 按路径删除本插件写过的键（官方 mutate；命中组合层的键会回继承该值）。 */
     clearKeys(settings: SettingsLike, ns: string, keys: readonly string[]): Promise<void>;
 }
 export declare function createPorts(ctx: Context, warn: (message: string) => void, options?: PortsOptions): Ports;

package/lib/types/service/sessions.d.ts

@@ -1,10 +1,13 @@
 import type { Context } from '@deepseek-ai/cordis';
 export type { Session } from '@deepseek-ai/dsh-session';
 import { type AuditEngine } from './audit.ts';
+import type { Ports } from './ports.ts';
 import type { WorkspaceEntry } from '../hub/workspace-book.ts';
 /** 会话上报实际消费的编排事实与工作区 peer。 */
 export interface SessionEngine extends AuditEngine {
     ctx: Context;
+    /** 默认模型读口（经 ports 的统一宽松查找，不另碰 ctx.get）。 */
+    ports: Pick<Ports, 'agentDefaultModel'>;
     workspace(): {
         tracked(): WorkspaceEntry[];
     };

package/lib/types/service/settings-tx.d.ts

@@ -0,0 +1,42 @@
+import type { SettingsForms, SettingsPathOp } from '@deepseek-ai/dsh-settings';
+/**
+ * 本插件消费的 host settings 服务接口：读 / 写口径照官方 `SettingsForms`。
+ * 设置段 = Profile 插件条目 id，`describe()` 只列「光纤 ACTIVE 且 Config 声明了 volatile 字段」的条目，
+ * 因此写入前要先等目标条目可描述；`replace` / `mutate` 是可缺的降级口。
+ */
+export type SettingsLike = Pick<SettingsForms, 'describe' | 'update'> & Partial<Pick<SettingsForms, 'replace' | 'mutate' | 'configure'>>;
+/** 一次事务里 plan 拿到的写瞬间视图：生效值 / 用户层 / 官方修订号。 */
+export interface SettingsView {
+    /** 该段当前有效值（官方 value：schema 默认 → 组合层 → 用户层）。 */
+    value: Record<string, unknown>;
+    /** 该段的用户层原始内容（`describe()` 的 `user`）：保住别人写在同一段里的键靠它。 */
+    user: Record<string, unknown>;
+    /** 官方修订号（宿主不支持时 undefined = 不带 CAS 写）。 */
+    revision: number | undefined;
+}
+/** 事务的一次产出：`write` 为 null 表示无需写盘、只取 result。 */
+export interface TxPlan<T> {
+    write: {
+        kind: 'section';
+        section: object;
+    } | {
+        kind: 'ops';
+        ops: readonly SettingsPathOp[];
+    } | null;
+    /** 事务产出（冲突重算后以最后一次 plan 为准）。 */
+    result: T;
+}
+export interface TransactOptions {
+    warn(message: string): void;
+    /** 等设置段可描述的上限（ms）。 */
+    namespaceWaitMs: number;
+    /** 单次写盘的上限（ms）：到点调用方降级，那笔仍在官方锁内照常落定。 */
+    writeTimeoutMs: number;
+}
+/**
+ * 一笔官方设置事务。plan 必须是 view 的纯函数（外部输入放闭包里）：
+ * 冲突重试会用新鲜视图重调它，副作用（记账、集合填充）应以 result 带出而不是改外部状态。
+ */
+export declare function transact<T>(settings: SettingsLike, ns: string, plan: (view: SettingsView) => TxPlan<T>, options: TransactOptions): Promise<T>;
+/** 等设置段可描述（条目 ACTIVE 且声明了 volatile 字段）；超时返回 false，不抛。 */
+export declare function waitForNamespace(settings: SettingsLike, ns: string, waitMs: number): Promise<boolean>;

package/lib/types/web/welcome-ack.d.ts

@@ -3,7 +3,7 @@
  * 时由 `packages/semi2-dsh/test/unit/dsh-contract.test.ts` 核对该串仍等于客户端 bundle 里的字面量；
  * 陈旧值只退化为原生行为。
  */
-export declare const WELCOME_NOTICE_VERSION = "2026-08-13.1";
+export declare const WELCOME_NOTICE_VERSION = "2026-09-28.1";
 /** 产品级 GUI onboarding 事实的 durable settings 段（= Profile 条目 id）。 */
 export declare const WELCOME_NOTICE_NAMESPACE = "ui-settings-general";
 /** 记录已确认的欢迎声明文案版本。 */

package/lib/web/welcome-ack.js

@@ -5,7 +5,7 @@
  * 时由 `packages/semi2-dsh/test/unit/dsh-contract.test.ts` 核对该串仍等于客户端 bundle 里的字面量；
  * 陈旧值只退化为原生行为。
  */
-export const WELCOME_NOTICE_VERSION = '2026-08-13.1';
+export const WELCOME_NOTICE_VERSION = '2026-09-28.1';
 /** 产品级 GUI onboarding 事实的 durable settings 段（= Profile 条目 id）。 */
 export const WELCOME_NOTICE_NAMESPACE = 'ui-settings-general';
 /** 记录已确认的欢迎声明文案版本。 */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fa-software/semi2-dsh",
-  "version": "0.0.16",
+  "version": "0.0.17-preview.20260929054409",
   "description": "Semi2 单插件：semi2-hub 配置引导 + 公共 Web 能力。",
   "homepage": "https://cnb.cool/fa-software/semi2/dsh/dsh-mono",
   "bugs": "https://cnb.cool/fa-software/semi2/dsh/dsh-mono/-/issues",
@@ -31,7 +31,8 @@
     "registry": "https://registry.npmjs.org/"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.2.0-rc.1",
     "@fa-software/test-kit": "0.0.0",
     "@graphql-codegen/cli": "7.4.0",
     "@graphql-codegen/typescript-operations": "6.1.6",
@@ -44,16 +45,16 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "~4.0.4",
-    "@deepseek-ai/dsh-agent-default-model": "^0.1.7-rc.2",
-    "@deepseek-ai/dsh-api-workspace-controller": "^0.1.7-rc.2",
-    "@deepseek-ai/dsh-client-connection": "^0.1.7-rc.2",
-    "@deepseek-ai/dsh-credentials": "^0.1.7-rc.2",
-    "@deepseek-ai/dsh-host-webserver": "^0.1.7-rc.2",
-    "@deepseek-ai/dsh-mcp-client": "^0.1.7-rc.2",
-    "@deepseek-ai/dsh-session": "^0.1.7-rc.2",
-    "@deepseek-ai/dsh-settings": "^0.1.7-rc.2",
-    "@deepseek-ai/dsh-skill": "^0.1.7-rc.2",
-    "@deepseek-ai/dsh-system-prompt": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-agent-default-model": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-api-workspace-controller": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-connection": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-credentials": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-host-webserver": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-mcp-client": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-session": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-settings": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-skill": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.2.0-rc.1",
     "@deepseek-ai/schemastery": "~3.18.4"
   },
   "peerDependenciesMeta": {