dsh-llm-codebuddy-power 1.0.0 → 1.2.0

package/lib/types/adapter.d.ts

@@ -10,7 +10,8 @@
  */
 import { LlmAdapter } from '@deepseek-ai/dsh-llm';
 import type { GenerateOptions, LlmModelInfo, LlmProviderInfo, LlmResolvedModelInfo, StreamChunk } from '@deepseek-ai/dsh-llm';
-import type { AttachmentStore } from '@deepseek-ai/dsh-attachment';
+import type { ImageAttachmentAccess } from '@deepseek-ai/dsh-llm';
+import type { AttachmentStore, ImageAttachmentRef } from '@deepseek-ai/dsh-attachment';
 import { DEFAULT_CONTEXT_WINDOW, DEFAULT_MAX_TOKENS } from './constants.ts';
 import type { CodeBuddySession } from './session.ts';
 import type { WireError } from './types.ts';
@@ -32,6 +33,11 @@ export interface CodeBuddyAdapterOptions {
     options: () => CodeBuddyConnectionOptions;
     /** 解析持久化附件服务;缺失时拒绝图像输入。 */
     resolveAttachments: () => AttachmentStore | undefined;
+    /**
+     * 解析单张图在当前执行世界中的只读路径,随读取提示词交给模型供 `read_image` 读取。
+     * 未设置时解析不出路径,用户消息里的图退回内联。
+     */
+    resolveImageAccess?: (attachments: AttachmentStore, ref: ImageAttachmentRef) => ImageAttachmentAccess | undefined;
     /** 已设置时,解析用户为单个模型设置的上限(上下文窗口 / 最大输出)。 */
     resolveOverrides?: (modelId: string) => Promise<ModelOverrides | undefined>;
 }

package/lib/types/auth-service.d.ts

@@ -1,10 +1,11 @@
 /**
  * 通过私有 RPC 通道暴露给 Web 客户端的宿主侧 OAuth 服务。
  *
- * 浏览器登录是长时操作(要等待用户完成登录),因此拆成两个 RPC endpoint:
- * `startLogin` 生成握手并返回用户必须打开的 URL,`pollLogin` 检查该握手是否已完成;
+ * 浏览器登录是长时操作(要等待用户完成登录),因此拆成三个 RPC endpoint:
+ * `startLogin` 生成握手并返回用户必须打开的 URL,`pollLogin` 检查该握手是否已完成,
+ * `pendingLogin` 报出仍在轮询的握手(浏览器刷新后据此接回);
  * 一次完成的登录会**追加**一个账号,而不是取代已有的。`accounts`、`activate`、
- * `setDefault`、`logout` 是设置页与会话账号按钮其余时间驱动的读写组合。
+ * `setDefault`、`logout` 是配置页与会话账号按钮其余时间驱动的读写组合。
  *
  * @module dsh-llm-codebuddy-power/auth-service
  */
@@ -27,6 +28,15 @@ export interface CodeBuddyLoginStart {
     authUrl: string;
     /** 握手 id;客户端会把它回传给 `pollLogin`。 */
     state: string;
+    /** 握手发起时刻(epoch ms);客户端据此计算截止时间。 */
+    startedAt: number;
+}
+/** `pendingLogin` 返回给客户端的结构。 */
+export interface CodeBuddyLoginPending {
+    /** 仍在轮询的握手 id。 */
+    state: string;
+    /** 该握手的发起时刻(epoch ms)。 */
+    startedAt: number;
 }
 /** `pollLogin` 返回给客户端的结构。 */
 export interface CodeBuddyLoginPoll {
@@ -89,13 +99,18 @@ export interface CodeBuddyTurnCreditAccount {
 /**
  * CodeBuddy 认证 RPC 服务。
  *
- * 握手由 `startLogin` 发起,由 `pollLogin` 轮询至完成,其账号由适配器的
- * `CodeBuddySession` 在下一个请求中取用 → 因此通过 UI 完成的登录无需重启
- * 即可到达运行中的 harness。`logout` 移除指定账号并使会话缓存失效。
+ * 握手由 `startLogin` 发起并**脱手**开跑,客户端经 `pollLogin` 反复查问它是否已结算,
+ * 其账号由适配器的 `CodeBuddySession` 在下一个请求中取用 → 因此通过 UI 完成的登录
+ * 无需重启即可到达运行中的 harness。`logout` 移除指定账号并使会话缓存失效。
  */
 export declare class CodeBuddyAuthService {
     private readonly session?;
-    /** 按 state id 索引的进行中握手。 */
+    /**
+     * 按 state id 索引的握手。
+     *
+     * 同时存放进行中的与**刚结算、尚在保留窗口内**的条目 —— 后者供客户端取回结果,
+     * 由 `settle()` 安排回收,因此本表不是"进行中握手"的集合。
+     */
     private readonly pending;
     constructor(ctx: Context, session?: CodeBuddySession | undefined);
     /** 把一次 RPC endpoint 调用路由到对应的处理器。 */
@@ -107,15 +122,35 @@ export declare class CodeBuddyAuthService {
     accounts(): Promise<CodeBuddyAccountsResult>;
     /**
      * 发起一次浏览器登录握手。
-     * @returns 用户必须打开的 URL。
+     * @returns 用户必须打开的 URL,以及该握手的 id 与发起时刻。
      */
     startLogin(): Promise<CodeBuddyLoginStart>;
+    /**
+     * 仍在进行的握手。
+     *
+     * 客户端的「登录中」状态只活在浏览器内存里,刷新即丢,而本表里的握手仍在轮询,
+     * 浏览器重新挂载后据此接回(否则界面显示可再次登录,而宿主那边已有一次握手在等,
+     * 用户点了就会平白多出第二次)。
+     *
+     * **只报尚未结算的握手**:已结算的条目会在表里多留一会儿供客户端取结果,若把它们
+     * 也算作"进行中",刷新后接回的就是一次已经结束(甚至已经失败)的登录,界面会重新
+     * 显示「登录中…」并空转到截止时间。
+     *
+     * 同时存在多次时给出最近发起的那次:客户端的轮询、取消与超时都只针对一个握手,
+     * 而最晚发起的那次正是用户此刻在等的那次。
+     * @returns 该握手;没有进行中的登录时缺省。
+     */
+    pendingLogin(): CodeBuddyLoginPending | undefined;
     /**
      * 检查已发起的握手是否完成。
+     *
+     * **立即返回**,不等待后台握手:`runLogin` 可能还要跑满十分钟,若在这里 await 它,
+     * 浏览器的一次请求就会在整个登录窗口内停在待处理,占住一条连接不放;而客户端是
+     * 按自己的间隔反复来问的,让它每次都立刻拿到"还没好"才是这条 endpoint 的职责。
      * @param state - 来自 `startLogin` 的握手 id。
      * @returns 登录是否完成、账号是否已持久化。
      */
-    pollLogin(state: string): Promise<CodeBuddyLoginPoll>;
+    pollLogin(state: string): CodeBuddyLoginPoll;
     /**
      * 某会话此刻生效的账号。
      * @param sessionId - dsh 会话身份;为空时按未选定处理。
@@ -169,13 +204,25 @@ export declare class CodeBuddyAuthService {
      */
     usage(sessionId: string): Promise<CodeBuddyUsageResult>;
     /**
-     * 把一次握手推进到持久化的账号。
+     * 把一次握手推进到持久化的账号,并把结果写回 {@link pending} 里对应条目。
      *
      * 复用 `buildAccount`,使落盘结构与 CLI 登录完全一致。
-     * 任何失败都返回 `undefined`,让客户端的轮询得到 `done: false`,
+     * 任何失败都记为"结算为失败",让客户端的轮询得到 `done: false`,
      * 从而可以从 `startLogin` 重试。
+     *
+     * 本方法由 `startLogin` **脱手**调用,`pollLogin` 不 await 它;因此它自己不返回
+     * 结果,只负责把结果写进条目并安排回收。
      */
     private runLogin;
+    /**
+     * 记录一次握手的结局,并在保留窗口之后回收该条目。
+     *
+     * 回收之所以要延迟:客户端是按自己的间隔来问结果的,一结算就删会让那次本已成功的
+     * 登录再也答不出 `done: true`。取消过的握手已不在表里,这里的写入自然丢弃。
+     * @param state - 握手 id。
+     * @param account - 已落盘的账号;失败或取消时为 `undefined`。
+     */
+    private settle;
     /**
      * 供客户端面板使用的增强版 CodeBuddy 目录:应用了促销/等级展示信息与覆盖配置的模型。
      * @param sessionId - 用哪个会话的账号读目录;为空时用默认账号。

package/lib/types/client/CodeBuddySection.d.ts

@@ -14,8 +14,8 @@ import type { CodeBuddyPrefs } from '../prefs.ts';
  * 设置分区与对话内账号控件共享的、经 RPC 支撑的业务面。每个回调都经 store action
  * 写入;组件自身不接触 wire。
  *
- * 界面偏好走 `hooks` 隔舱:它与对话输入区的控件组是同一份活来源(用户设置文档里
- * 的命名空间),写入经 `setPref`。
+ * 界面偏好走 `hooks` 隔舱:它与对话输入区的控件组是同一份活来源(本入口的
+ * volatile 配置字段),写入经 `setPref`。
  */
 export interface CodeBuddySectionInjected {
     hooks: {
@@ -26,6 +26,11 @@ export interface CodeBuddySectionInjected {
     refreshAccounts: () => Promise<void>;
     /** 发起浏览器登录握手(在新标签页打开鉴权 URL);完成后账号被追加到列表。 */
     startLogin: () => Promise<void>;
+    /**
+     * 接回宿主仍在轮询的握手。浏览器刷新后本地状态已丢而宿主的握手还在等,
+     * 挂载时调用一次即可让「登录中」继续显示并恢复轮询。
+     */
+    resumeLogin: () => Promise<void>;
     /**
      * 发起一次登录握手并把鉴权 URL 复制到剪贴板(不打开浏览器),用于在别的浏览器或
      * 机器上完成登录。失败时会发布一条页面级错误。
@@ -34,11 +39,13 @@ export interface CodeBuddySectionInjected {
     copyLoginLink: () => Promise<boolean>;
     /**
      * 放弃一次进行中的登录握手,并把界面从“登录中”收回到可再次发起的状态。
-     * @returns 是否确已放弃;未知或已完成的握手同样返回 true(取消是幂等的)。
+     *
+     * 调用方不必等它的结果:取消对界面是即刻生效的,而宿主侧的中止即使慢或失败,
+     * 该握手也会在宿主自己的截止时间被回收。
      */
-    cancelLogin: (state: string) => Promise<boolean>;
+    cancelLogin: (state: string, signal?: AbortSignal) => Promise<void>;
     /** 按 state id 轮询一次握手;账号持久化后解析为 true。 */
-    pollLogin: (state: string) => Promise<boolean>;
+    pollLogin: (state: string, signal?: AbortSignal) => Promise<boolean>;
     /** 退出若干账号。 */
     logoutAccounts: (uids: string[]) => Promise<void>;
     /**
@@ -48,11 +55,11 @@ export interface CodeBuddySectionInjected {
     reorderAccounts: (uids: string[]) => Promise<void>;
     /** 指定默认账号;`null` 表示取消默认账号。 */
     setDefault: (uid: string | null) => Promise<void>;
-    /** 写入一个界面偏好字段;该写入持久化到用户设置文档。 */
+    /** 写入一个界面偏好字段;该写入持久化到本入口的 profile patch。 */
     setPref: (field: keyof CodeBuddyPrefs, value: boolean | number) => void;
 }
 /** 完整组件 props:runtime 份额 + store 份额 + locale seat + inject face。 */
-export type CodeBuddySectionProps = PropsRuntime<'settings.section'> & PropsStore<ReturnType<typeof createCodeBuddyStore>> & PropsLocale<'settings.codebuddy'> & InjectFace<CodeBuddySectionInjected>;
+export type CodeBuddySectionProps = PropsRuntime<'plugins.bundle.config'> & PropsStore<ReturnType<typeof createCodeBuddyStore>> & PropsLocale<'settings.codebuddy'> & InjectFace<CodeBuddySectionInjected>;
 /**
  * CodeBuddy 设置分区。
  * @param props - 组合后的 slot props。

package/lib/types/client/index.d.ts

@@ -1,13 +1,13 @@
 /**
- * Web 客户端部分:一个 CodeBuddy 设置页,以及对话框输入区的账号控件。
+ * Web 客户端部分:一个 CodeBuddy 配置页(挂在侧边栏插件面板上),以及对话框输入区的账号控件。
  *
- * 在 `settings.section` 中注册一个条目 —— 一个展示全部已登录账号、追加登录、
- * 退出单个或选中账号、指定默认账号的 “CodeBuddy” 页面 —— 再在
- * `conversation.input.right` 中注册一个条目,在 CodeBuddy 模型按钮左侧渲染当前
+ * 在 `plugins.bundle.config` 中注册一个条目 —— 一个展示全部已登录账号、追加登录、
+ * 退出单个或选中账号、指定默认账号的页面,按本包名派发到插件页本插件自己的卡片上 ——
+ * 再在 `conversation.input.right` 中注册一个条目,在 CodeBuddy 模型按钮左侧渲染当前
  * 会话的额度圆环与账号切换按钮。
  *
- * 两个条目处在**不同作用域**(设置页 root、输入区 session),而一个 store handle
- * 只能绑一个作用域,因此它们不共用句柄:设置页持有 store,对话控件按会话经 RPC
+ * 两个条目处在**不同作用域**(配置页 root、输入区 session),而一个 store handle
+ * 只能绑一个作用域,因此它们不共用句柄:配置页持有 store,对话控件按会话经 RPC
  * 自取账号集合与用量(见该处的注册注释)。
  *
  * @module dsh-llm-codebuddy-power/client

package/lib/types/client/locales.d.ts

@@ -79,7 +79,7 @@ export declare const en: {
 export type CodeBuddyKey = keyof typeof en;
 declare module '@deepseek-ai/dsh-client-ui-slots' {
     interface LocaleNamespaceMap {
-        /** CodeBuddy 设置页与对话内账号控件的文案。 */
+        /** CodeBuddy 配置页与对话内账号控件的文案。 */
         'settings.codebuddy': CodeBuddyKey;
     }
 }

package/lib/types/client/store.d.ts

@@ -1,14 +1,13 @@
 /**
- * CodeBuddy 页面 store:设置分区共享的账号快照。
+ * CodeBuddy 页面 store:配置页共享的账号快照。
  *
- * 客户端插件在设置页条目下挂载本句柄,因此在设置分区里完成的登录、退出或改
+ * 客户端插件在配置页条目下挂载本句柄,因此在该页完成的登录、退出或改
  * 默认账号无需跨组件接线即可到达同一页面的各个徽章。
  *
- * **界面偏好不在这里**:它们是 harness 用户设置文档里的一段(见 `../prefs.ts`),
- * 由 `./index.ts` 经 `ctx.settingsScope.bind()` 读取,并以一个派生的活快照经
- * 注入面的 `hooks` 隔舱同时下发给设置页与对话输入区的控件组 —— 后者处在另一个
- * 作用域,共享不了本句柄。偏好此前存在 `localStorage` 并由输入区按 5 秒轮询
- * 读取,导致开关与圆环之间有最多一个轮询周期的延迟。
+ * **界面偏好不在这里**:它们是插件自己的 volatile 配置字段(见 `../prefs.ts`),
+ * 由 `./index.ts` 经 `ctx.configForms.get()` 读取,并以一个派生的活快照经
+ * 注入面的 `hooks` 隔舱同时下发给配置页与对话输入区的控件组 —— 后者处在另一个
+ * 作用域,共享不了本句柄。
  *
  * @module dsh-llm-codebuddy-power/client/store
  */
@@ -22,7 +21,7 @@ export interface PendingLogin {
     state: string;
     /**
      * 发起时刻(epoch ms)。截止时间据此计算并存进 store —— 放在组件的 effect 里会让
-     * 每次重新挂载(关闭再打开设置页)都把计时归零,于是反复开关就能把"登录中…"
+     * 每次重新挂载(关闭再打开配置页)都把计时归零,于是反复开关就能把"登录中…"
      * 无限延长。
      */
     startedAt: number;
@@ -47,12 +46,21 @@ type CodeBuddyActions = {
     setAccounts: (draft: CodeBuddyState, result: CodeBuddyAccountsResult) => void;
     /** 发布页面级失败。 */
     fail: (draft: CodeBuddyState, message: string) => void;
+    /** 丢弃页面级失败,回到可再次发起的阶段。 */
+    clearError: (draft: CodeBuddyState) => void;
     /** 跟踪进行中的浏览器登录握手(null 表示没有)。 */
     setLoginState: (draft: CodeBuddyState, state: PendingLogin | null) => void;
+    /**
+     * 采纳宿主报出的握手(仅当本地此刻没有握手时)。
+     *
+     * 判据放在 action 里而不是调用方:采纳是异步读了一次 RPC 之后才发生的,
+     * 期间用户可能刚点了登录;无条件写入会把那次新握手的发起时刻换成宿主的旧时刻。
+     */
+    adoptLogin: (draft: CodeBuddyState, state: PendingLogin) => void;
 };
 /**
  * 声明 CodeBuddy 页面状态与写入接口。
- * @returns store 句柄(在 apply 中挂载于设置页条目下)。
+ * @returns store 句柄(在 apply 中挂载于配置页条目下)。
  */
 export declare function createCodeBuddyStore(): EngineStoreHandle<CodeBuddyState, CodeBuddyActions>;
 export {};

package/lib/types/client/wire.d.ts

@@ -36,6 +36,18 @@ export interface CodeBuddyAccountsResult {
 export interface CodeBuddyLoginStart {
     authUrl: string;
     state: string;
+    /**
+     * 握手发起时刻(epoch ms)。按"可能缺失"声明,与 {@link CodeBuddyAccountView} 同理:
+     * 旧宿主不返回该字段,客户端据本机当前时刻兜底。
+     */
+    startedAt?: number;
+}
+/** `pendingLogin` 的结果结构;没有进行中的登录时缺省。 */
+export interface CodeBuddyLoginPending {
+    /** 仍在轮询的握手 id。 */
+    state: string;
+    /** 该握手的发起时刻(epoch ms)。 */
+    startedAt: number;
 }
 /** `pollLogin` 的结果结构。 */
 export interface CodeBuddyLoginPoll {
@@ -142,6 +154,11 @@ export interface CodeBuddyTurnCreditRecord {
 /**
  * 在共享通道上调用一个鉴权 endpoint。该通道调用按设计不做类型约束;
  * endpoint 所记录的 payload 结构在此唯一的 wire 边界处恢复。
+ * @param rpc - 当前连接的 RPC 调用器。
+ * @param endpoint - 通道下的 endpoint 名。
+ * @param payload - endpoint 自己的请求载荷。
+ * @param signal - 可选取消;中止后该请求的连接随即释放,而不是等宿主应答。
+ * @returns endpoint 自己声明的结果。
  */
-export declare function authCall<T>(rpc: ClientConnectionRpc, endpoint: string, payload?: unknown): Promise<ConnectionRpcResult<T>>;
+export declare function authCall<T>(rpc: ClientConnectionRpc, endpoint: string, payload?: unknown, signal?: AbortSignal): Promise<ConnectionRpcResult<T>>;
 //# sourceMappingURL=wire.d.ts.map

package/lib/types/constants.d.ts

@@ -62,6 +62,14 @@ export declare const REQUEST_IMAGE_DIMENSION_LADDER: readonly [1920, 1440, 1080]
 export declare const LOGIN_TIMEOUT_MS: number;
 /** 等待浏览器登录完成时的轮询间隔,单位 ms。 */
 export declare const LOGIN_POLL_INTERVAL_MS = 1000;
+/**
+ * 握手结算后在宿主表里保留结果的时长,单位 ms。
+ *
+ * 逾期即回收,但**客户端是过一会儿才来问的**(它按自己的间隔轮询),所以结果不能
+ * 一结算就丢:一丢,那次本已成功的登录就再也答不出 `done: true`,客户端只能干等到
+ * 十分钟截止。保留窗口只需覆盖一个客户端轮询周期,取一个宽裕值。
+ */
+export declare const LOGIN_RESULT_RETENTION_MS: number;
 /** 含义为“浏览器登录尚未完成”的服务码。 */
 export declare const AUTH_PENDING_CODE = 11217;
 //# sourceMappingURL=constants.d.ts.map

package/lib/types/index.d.ts

@@ -11,12 +11,13 @@
  * @module dsh-llm-codebuddy-power
  */
 import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
 import type { CodeBuddyConnectionOptions } from './adapter.ts';
 import type { CodeBuddyPrefs, CodeBuddyPrefsConfig } from './prefs.ts';
 export { CodeBuddyAdapter, httpErrorCode } from './adapter.ts';
 export type { CodeBuddyAdapterOptions, CodeBuddyConnectionOptions } from './adapter.ts';
 export { CodeBuddyAuthService, CODEBUDDY_AUTH_CHANNEL } from './auth-service.ts';
-export type { CodeBuddyAccountsResult, CodeBuddyLoginStart, CodeBuddyLoginPoll, CodeBuddySessionAccount, CodeBuddyUsageResult, CodeBuddyUsageWindow, } from './auth-service.ts';
+export type { CodeBuddyAccountsResult, CodeBuddyLoginPending, CodeBuddyLoginStart, CodeBuddyLoginPoll, CodeBuddySessionAccount, CodeBuddyUsageResult, CodeBuddyUsageWindow, } from './auth-service.ts';
 export { CodeBuddySession, NotLoggedInError } from './session.ts';
 export type { CodeBuddyAccountInfo, TurnCreditAccount, TurnCreditAccountView, TurnCreditRecord, TurnCreditRecordView, } from './session.ts';
 export { login } from './login.ts';
@@ -34,17 +35,18 @@ export type * from './types.ts';
 export declare const name = "llm-codebuddy-power";
 /**
  * 本插件的激活服务。`llm` 承载适配器路由,`tools` 接受文生图工具注册,
- * `agents` 用于极简模式会话中按 agent 限制画图工具可见性。生成图片经
- * 标准附件通道(attachments.saveImage + uiConversation.imageUrl)持久化与
- * 展示,工具注册在附件服务挂载后(`ctx.inject(['attachments'])`)。
+ * `agents` 用于极简模式会话中按 agent 限制画图工具可见性。生成图片经标准附件通道
+ * (attachments.saveImage + uiConversation.imageUrl)持久化与展示,工具注册在
+ * 附件服务挂载后(`ctx.inject(['attachments'])`)。
  */
 export declare const inject: string[];
 /**
- * 插件配置。每个字段都是可选的:内置默认值直达公开的 CodeBuddy 服务,且按
- * 设计完全没有凭据字段 → 唯一的进入方式是浏览器登录。
+ * 插件配置。连接字段都可选:内置默认值直达公开的 CodeBuddy 服务,且按设计完全
+ * 没有凭据字段 → 唯一的进入方式是浏览器登录。
  *
- * 界面偏好字段(`CodeBuddyPrefsConfig`)是设置命名空间的 base 层:用户在 Web
- * 设置页的写入存在 harness 的用户设置文档里并覆盖它们。
+ * 界面偏好字段(`CodeBuddyPrefsConfig`)是 volatile 的:设置表单只能读写 volatile
+ * 字段,写入落回本入口的 profile patch,而 volatile 引用原地更新,因此宿主每次
+ * 读取都拿到当前值、无需重挂插件。
  */
 export interface Config extends CodeBuddyPrefsConfig {
     /** Chat 端点基址;默认为 CodeBuddy 的 OpenAI 兼容路由。 */
@@ -57,23 +59,43 @@ export interface Config extends CodeBuddyPrefsConfig {
     streamIdleTimeoutMs?: number;
 }
 /**
- * 校验并补全原始配置。
+ * {@link Config} 的运行时 schema。
  *
- * 编程式构造可以绕过任何 schema,因此边界在此判定,坏值在加载时就带字段名
- * 失败,而不是等到请求中途。
- * @param config - 原始入口配置。
- * @returns 解析出的连接事实。
+ * 三个界面偏好字段必须是 volatile 才会被设置表单投影,而 volatile 只从
+ * schemastery schema 产生;连接字段保持普通字段,因此不在表单里暴露 ——
+ * 它们由 profile 的 cordis.patch.yml 配置。
  */
-export declare function resolveConnectionOptions(config?: Config): CodeBuddyConnectionOptions;
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    baseURL: z<string, string, "plain">;
+    defaultContextWindow: z<number, number, "plain">;
+    defaultMaxTokens: z<number, number, "plain">;
+    streamIdleTimeoutMs: z<number, number, "plain">;
+    showUsage: z<boolean, boolean, "volatile-defined">;
+    dangerPct: z<number, number, "volatile-defined">;
+    drawToolInMinimal: z<boolean, boolean, "volatile-defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    baseURL: z<string, string, "plain">;
+    defaultContextWindow: z<number, number, "plain">;
+    defaultMaxTokens: z<number, number, "plain">;
+    streamIdleTimeoutMs: z<number, number, "plain">;
+    showUsage: z<boolean, boolean, "volatile-defined">;
+    dangerPct: z<number, number, "volatile-defined">;
+    drawToolInMinimal: z<boolean, boolean, "volatile-defined">;
+}>>, "plain">;
 /**
- * 解析界面偏好的部署级 base 层。用户设置文档中的写入覆盖它。
+ * 从配置解析连接事实。
  *
- * 与 {@link resolveConnectionOptions} 同理,编程式构造可以绕过任何 schema,
- * 因此坏值在此判定并在加载时失败。
- * @param config - 原始入口配置。
- * @returns 设置命名空间的 base 值。
+ * 连接字段在 `Config` 里都是可选的,缺省值即公开的 CodeBuddy 服务。
+ * @param config - 入口配置。
+ * @returns 解析出的连接事实。
+ */
+export declare function resolveConnectionOptions(config: Config): CodeBuddyConnectionOptions;
+/**
+ * 读取界面偏好的当前值。
+ * @param config - 入口配置。
+ * @returns 三个界面偏好。
  */
-export declare function resolvePrefsBase(config?: Config): CodeBuddyPrefs;
+export declare function resolvePrefs(config: Config): CodeBuddyPrefs;
 /** 挂载插件:解析配置,然后注册路由。 */
-export declare function apply(ctx: Context, config?: Config): void;
+export declare function apply(ctx: Context, config: Config): void;
 //# sourceMappingURL=index.d.ts.map

package/lib/types/prefs.d.ts

@@ -1,23 +1,25 @@
 /**
- * CodeBuddy 界面偏好的命名空间契约,Host 与 Client 两面共享。
+ * CodeBuddy 界面偏好的契约,Host 与 Client 两面共享。
  *
- * 这些偏好是**插件自己的设置命名空间**里的一段:`Config` 提供部署级 base,
- * 用户在 Web 设置页的写入落在 harness 的用户设置文档里,因此换浏览器、重启
- * harness 后仍然生效 —— 其中「极简模式画图工具」还会被宿主读取来决定
- * `codebuddy-draw` 对模型是否可见,存在浏览器里会让同一次部署因浏览器而异。
+ * 这些偏好是**插件自己的 volatile 配置字段**:`Config` 里声明为 volatile 后,
+ * 设置表单按入口 id 把它们投影成可读写的表单,宿主在每次操作时读取当前值,因此
+ * 换浏览器、重启 harness 后仍然生效。其中「极简模式画图工具」还会被宿主读取来
+ * 决定 `codebuddy-draw` 对模型是否可见。
  *
- * 本文件必须保持零依赖:两面都会编译它,而 Client 面若因此引入 schemastery
+ * 本文件必须保持零运行时依赖:两面都会编译它,而 Client 面若因此引入 schemastery
  * 就会把它打进浏览器产物(校验 schema 是宿主面的事,见 `./settings.ts`)。
+ * `Volatile` 是纯类型导入,擦除后不留依赖。
  *
  * @module dsh-llm-codebuddy-power/prefs
  */
-/** 本插件拥有的设置命名空间,与插件名一致。 */
+import type { Volatile } from '@deepseek-ai/cordis';
+/** 本插件的设置入口 id,与插件名一致。 */
 export declare const CODEBUDDY_SETTINGS_NAMESPACE = "llm-codebuddy-power";
 /** 告警百分比的下界(含)。 */
 export declare const DANGER_PCT_MIN = 1;
 /** 告警百分比的上界(含)。 */
 export declare const DANGER_PCT_MAX = 100;
-/** 本插件在用户设置文档里持久化的界面偏好。 */
+/** 本插件的界面偏好;设置表单投影出的就是这个结构。 */
 export interface CodeBuddyPrefs {
     /** 对话输入区是否显示额度圆环。 */
     showUsage: boolean;
@@ -29,15 +31,17 @@ export interface CodeBuddyPrefs {
 /** 未覆盖任何一层时使用的偏好默认值。 */
 export declare const DEFAULT_CODEBUDDY_SETTINGS: CodeBuddyPrefs;
 /**
- * 插件配置里可覆盖的偏好字段。三者都是部署级默认值,用户设置文档中的写入
- * 覆盖它们。
+ * `Config` 里的界面偏好字段。
+ *
+ * 三者都声明为 volatile:设置表单只能读写 volatile 字段,而 volatile 引用在原地
+ * 更新,所以宿主每次 `.get()` 都拿到当前值,不必重挂插件。
  */
 export interface CodeBuddyPrefsConfig {
     /** 对话输入区是否显示额度圆环。 */
-    showUsage?: boolean;
+    showUsage: Volatile<boolean>;
     /** 圆环填充变为告警颜色的已用百分比。 */
-    dangerPct?: number;
+    dangerPct: Volatile<number>;
     /** 极简模式会话是否注入 codebuddy-draw 工具。 */
-    drawToolInMinimal?: boolean;
+    drawToolInMinimal: Volatile<boolean>;
 }
 //# sourceMappingURL=prefs.d.ts.map

package/lib/types/serialize.d.ts

@@ -2,28 +2,35 @@
  * 把 harness 消息序列化为 CodeBuddy(OpenAI 兼容)chat 请求。
  *
  * 用户文本被拼接,助手文本成为 `content`,工具调用成为
- * `tool_calls`,每个工具结果成为其自身的 `role: 'tool'` 消息 →
- * harness 把工具结果放在用户消息内部,而这条 wire 路由
- * 不接受这种形式。对于支持图像的模型,图像以 OpenAI 兼容的
- * `image_url` 部件(`data:<type>;base64,...`)出现在用户或工具 content
- * 数组中,与官方 CLI 的发送方式完全一致。工具结果的图只对 `read_image`
- * 这类"看图"工具发送,生成图工具的结果仍走纯文本信封。
+ * `tool_calls`,每个工具结果是一条 `role: 'tool'` 的 harness 消息,直接映射为
+ * 同名 wire 条目。对于支持图像的模型,用户消息里的图**不内联**:改为给出一段
+ * 引导模型自行用 `read_image` 读取的提示词(附件服务解析出的只读绝对路径);
+ * 解析不出路径时退回内联,以免模型既拿不到图也拿不到路径。`read_image` 的工具
+ * 结果仍内联图片本身 —— 那是像素交给模型的唯一途径。生成图工具的结果继续走
+ * 纯文本信封。
  *
  * @module dsh-llm-codebuddy-power/serialize
  */
-import type { GenerateOptions, Message } from '@deepseek-ai/dsh-llm';
+import type { GenerateOptions, ImageAttachmentAccessResolver, RequestMessage } from '@deepseek-ai/dsh-llm';
 import type { RequestImageAttachment } from '@deepseek-ai/dsh-attachment';
 import type { WireMessage, WireRequest } from './types.ts';
 /** 请求中每个图像已解析的请求版本,以 attachment id 为键。 */
 export type RequestImages = ReadonlyMap<RequestImageAttachment['attachment']['attachmentId'], RequestImageAttachment>;
 /**
  * 按顺序序列化整个对话。
+ *
+ * 工具结果在 harness 里是**独立的 `role: 'tool'` 消息**(`ToolResultMessage`),
+ * 因此这里逐条映射,而不是按块从 user 消息里筛选。
+ * developer 消息由运行时在 `projectToolUpdates` 中剥离(本 adapter 未声明
+ * `toolUpdate`),因此不会到达这里;万一到达即明确拒绝,而不是静默丢弃。
  * @param messages - harness 会话。
  * @param supportsImages - 所选模型是否声明支持图像输入。
  * @param images - 请求中每个图像已解析的请求版本。
- * @returns wire 消息,每个工具结果展开为独立条目。
+ * @param resolveAccess - 解析单张图在当前执行世界中的只读路径。
+ * @param route - 本请求的读图形态。
+ * @returns wire 消息,工具结果各自成为独立条目。
  */
-export declare function serializeMessages(messages: readonly Message[], supportsImages: boolean, images?: RequestImages): WireMessage[];
+export declare function serializeMessages(messages: readonly RequestMessage[], supportsImages: boolean, images?: RequestImages, resolveAccess?: ImageAttachmentAccessResolver, route?: 'direct' | 'ptc' | 'none'): WireMessage[];
 /**
  * 构建 chat-completions 请求体。始终流式并上报 usage;
  * 缺省的选项被省略而非以 null 发送,以便应用
@@ -31,7 +38,9 @@ export declare function serializeMessages(messages: readonly Message[], supports
  * @param options - 组装好的 harness 请求。
  * @param supportsImages - 所选模型是否声明支持图像输入。
  * @param images - 请求中每个图像已解析的请求版本。
+ * @param resolveAccess - 解析单张图在当前执行世界中的只读路径。
+ * @param route - 本请求的读图形态,由工具目录决定;写入前由调用方计算一次。
  * @returns 请求体。
  */
-export declare function serializeRequest(options: GenerateOptions, supportsImages: boolean, images?: RequestImages): WireRequest;
+export declare function serializeRequest(options: GenerateOptions, supportsImages: boolean, images?: RequestImages, resolveAccess?: ImageAttachmentAccessResolver): WireRequest;
 //# sourceMappingURL=serialize.d.ts.map

package/lib/types/session.d.ts

@@ -30,7 +30,7 @@ interface Catalog {
     promotions: readonly CodeBuddyModelPromotion[];
     tiers: readonly CodeBuddyModelTier[] | undefined;
 }
-/** 设置页与账号切换按钮读取的账号投影。 */
+/** 配置页与账号切换按钮读取的账号投影。 */
 export interface CodeBuddyAccountInfo {
     uid: string;
     nickname: string;
@@ -322,7 +322,7 @@ export declare class CodeBuddySession {
      */
     isLoggedIn(): Promise<boolean>;
     /**
-     * 已存账号及其默认账号,供设置页与会话切换按钮展示。
+     * 已存账号及其默认账号,供配置页与会话切换按钮展示。
      * @returns 账号列表(顺序与磁盘一致)与默认账号 uid;未登录时列表为空。
      */
     accountList(): Promise<{
@@ -390,7 +390,7 @@ export declare class CodeBuddySession {
     /**
      * 目录;读不到时返回空列表。
      *
-     * 列出模型是设置页上的浏览动作,所以失败必须降级为“没有可显示的内容”,
+     * 列出模型是配置页上的浏览动作,所以失败必须降级为“没有可显示的内容”,
      * 而不是让页面崩掉。请求路径直接使用 {@link models} 并保留真实失败。
      * @param signal - 可选取消信号。
      * @param sessionId - 用哪个会话的账号;缺省时用默认账号。

package/lib/types/settings.d.ts

@@ -1,9 +1,9 @@
 /**
- * 本插件设置命名空间的宿主 schema。
+ * 本插件的 `Config` schema —— 连接事实与界面偏好合一。
  *
- * 校验只在宿主发生:浏览器面若也引入 schemastery,它会连同校验器一起被打进
- * `lib/client.js`,而客户端本来就把服务端返回的数据当作已校验结果接收。因此
- * schema 只在此文件出现,浏览器面经 `./prefs.ts` 取同一份类型与默认值。
+ * 设置表单只投影**入口自己的 `Config`** 里声明为 `.volatile()` 的字段(入口 id
+ * 即命名空间),因此界面偏好字段与连接字段同在 `Config` 中,只有偏好那三个是
+ * volatile。
  *
  * 字段的默认值一律取自 `DEFAULT_CODEBUDDY_SETTINGS`,不在此重复字面量 ——
  * 两处各写一份时,改了一处就会出现「宿主默认 90、界面显示 80」这种只有用户
@@ -12,7 +12,10 @@
  * @module dsh-llm-codebuddy-power/settings
  */
 import z from '@deepseek-ai/schemastery';
-import type { CodeBuddyPrefs } from './prefs.ts';
-/** 用户设置文档中本插件命名空间的 schema。 */
-export declare const CodeBuddySettingsSchema: z<CodeBuddyPrefs>;
+/** `Config.showUsage` 的 schema。 */
+export declare const ShowUsageField: z<boolean, boolean, "volatile-defined">;
+/** `Config.dangerPct` 的 schema。 */
+export declare const DangerPctField: z<number, number, "volatile-defined">;
+/** `Config.drawToolInMinimal` 的 schema。 */
+export declare const DrawToolInMinimalField: z<boolean, boolean, "volatile-defined">;
 //# sourceMappingURL=settings.d.ts.map

package/lib/types/storage.d.ts

@@ -5,7 +5,7 @@
  * (`$DSH_HOME/data/plugins/llm-codebuddy-power/`,通过 harness 所用的同一个
  * `@deepseek-ai/dsh-home-paths` 解析),而不放在插件包内,因此重装不会让
  * 用户退出登录。写入经 [atomic-file.ts](./atomic-file.ts) 做原子替换并按路径串行化:
- * 多个账号的令牌刷新、设置页的增删与 CLI 的调用都在改同一份文件,不串行化时
+ * 多个账号的令牌刷新、配置页的增删与 CLI 的调用都在改同一份文件,不串行化时
  * 两个并发写入会各自基于自己读到的旧内容覆盖对方。残缺文件会让用户手里只有
  * 一份读不出的凭据,还无法与“从未登录过”区分开。
  *
@@ -80,7 +80,7 @@ export declare function updateStorage(change: (current: CodeBuddyStorage) => Cod
  * 插入一个账号,或替换同 uid 账号的凭据。
  *
  * 同 uid 视为重新登录同一个账号:令牌被替换而不是追加成第二个条目,否则
- * 设置页会出现两个同名徽章,退出其中一个还会留下另一个。
+ * 配置页会出现两个同名徽章,退出其中一个还会留下另一个。
  * @param entry - 刚登录得到的账号。
  */
 export declare function upsertAccount(entry: CodeBuddyStoredAccount): Promise<void>;