@dsh-plus/subagent-model 0.1.0

package/src/config-api.ts

@@ -0,0 +1,133 @@
+/**
+ * 配置 HTTP 通道：webui 插件配置卡片的后端。
+ * 背景：官方 apiproxy 的 settings.* RPC 对 namespace 有硬编码白名单，第三方
+ * namespace 一律 settings-not-exposed；故卡片数据走自建 webServer 路由，
+ * 读写仍经 ctx.settings 用户层（持久化 $DSH_HOME/settings.yaml）。
+ * 仅监听 dsh web 同源（webserver 默认 127.0.0.1），与 GUI 其余面同等暴露面。
+ * @module subagent-model/config-api
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http'
+
+import type { Context } from '@deepseek-ai/cordis'
+
+import { buildModelCatalog, type ModelCatalog } from './catalog.ts'
+import {
+  SETTINGS_NS, toUserPatch, toWire, validateEntry, WirePatch, type WirePatchOutput,
+} from './config.ts'
+import type { SubagentModelService } from './service.ts'
+
+const ROUTE_CONFIG = '/dsh-plus/subagent-model/config'
+const ROUTE_CATALOG = '/dsh-plus/subagent-model/catalog'
+const MAX_BODY_BYTES = 256 * 1024
+
+function sendJson(res: ServerResponse, status: number, body: unknown): void {
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' })
+  res.end(JSON.stringify(body))
+}
+
+function readBody(req: IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = []
+    let size = 0
+    req.on('data', (chunk: Buffer) => {
+      size += chunk.length
+      if (size > MAX_BODY_BYTES) {
+        reject(new Error('request body too large'))
+        req.destroy()
+        return
+      }
+      chunks.push(chunk)
+    })
+    req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')))
+    req.on('error', reject)
+  })
+}
+
+async function readPatch(req: IncomingMessage): Promise<WirePatchOutput> {
+  const raw = await readBody(req)
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    throw new Error('request body is not valid JSON')
+  }
+  return WirePatch(parsed)
+}
+
+/** 校验用户提交的 entries（model 不能脱离 provider 等）；返回首个错误消息或 null。 */
+function firstEntryError(patch: WirePatchOutput): string | null {
+  for (const [name, entry] of Object.entries(patch.entries)) {
+    const error = validateEntry(entry)
+    if (error !== null) return `条目 ${name}: ${error}`
+  }
+  return null
+}
+
+async function handleConfig(
+  ctx: Context,
+  service: SubagentModelService,
+  req: IncomingMessage,
+  res: ServerResponse,
+): Promise<void> {
+  const settings = ctx.get('settings')
+  if (req.method === 'GET') {
+    sendJson(res, 200, toWire(service.currentConfig(), service.subagentProviders(), settings !== undefined))
+    return
+  }
+  if (req.method !== 'PUT') {
+    sendJson(res, 405, { error: 'method not allowed' })
+    return
+  }
+  if (settings === undefined) {
+    sendJson(res, 503, { error: 'settings provider 不可用，无法在线保存；请编辑 settings.yaml' })
+    return
+  }
+  const patch = await readPatch(req)
+  const entryError = firstEntryError(patch)
+  if (entryError !== null) {
+    sendJson(res, 400, { error: entryError })
+    return
+  }
+  await settings.update(SETTINGS_NS, toUserPatch(patch))
+  sendJson(res, 200, toWire(service.currentConfig(), service.subagentProviders(), true))
+}
+
+async function handleCatalog(ctx: Context, res: ServerResponse): Promise<void> {
+  const catalog: ModelCatalog = await buildModelCatalog(ctx)
+  sendJson(res, 200, catalog)
+}
+
+/** 注册配置读写与目录路由；返回是否注册成功（webServer 缺失时由调用方保证不调用）。 */
+export function registerConfigApi(ctx: Context, service: SubagentModelService): void {
+  const logger = ctx.logger('subagent-model')
+  const guard = (
+    handler: (req: IncomingMessage, res: ServerResponse) => Promise<void>,
+  ): ((req: IncomingMessage, res: ServerResponse) => Promise<void>) => {
+    return async (req, res) => {
+      try {
+        await handler(req, res)
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error)
+        logger.warn(`config api ${req.method ?? '?'} ${req.url ?? '?'} failed: ${message}`)
+        if (!res.headersSent) sendJson(res, 400, { error: message })
+        else res.end()
+      }
+    }
+  }
+  ctx.webServer.register({
+    kind: 'exact',
+    path: ROUTE_CONFIG,
+    handler: guard((req, res) => handleConfig(ctx, service, req, res)),
+  })
+  ctx.webServer.register({
+    kind: 'exact',
+    path: ROUTE_CATALOG,
+    handler: guard(async (req, res) => {
+      if (req.method !== 'GET') {
+        sendJson(res, 405, { error: 'method not allowed' })
+        return
+      }
+      await handleCatalog(ctx, res)
+    }),
+  })
+}

package/src/config.ts

@@ -0,0 +1,199 @@
+/**
+ * 配置单一事实源：cordis 行级 Config（组合默认值，dev/prod patch 层可覆盖）
+ * 与 settings namespace（用户层，经 dsh-settings-file 持久化到 $DSH_HOME/settings.yaml）
+ * 共用同一 schemastery schema。条目按【子代理 provider 名】键控
+ * （standard preset 事实映射：subagent↔spawn、subagent_fork↔fork）。
+ *
+ * 运行时语义（详见 delegation.ts）：
+ * - provider/model 显式时注入子代理 `agentOptions`（覆盖"继承主代理"快照）；
+ * - reasoningEffort 显式时经私有字段随 agentOptions 抵达子代理，再由
+ *   `agent/request` 瀑布监听器应用（dsh 原生 AgentOptions 不含 effort 字段）。
+ *
+ * 类型说明：z.dict 的推断类型引用 cosmokit 的 Dict，直接导出会触发
+ * dts 的 TS2742（不可具名引用）；按官方 dsh-permission-presets 模式，
+ * 显式声明输入/输出接口并注解 schema（输出为规范型，输入为可空宽松型）。
+ * @module subagent-model/config
+ */
+import z from '@deepseek-ai/schemastery'
+import { settingsNamespace } from '@deepseek-ai/dsh-settings'
+
+/** settings 命名空间；webui 配置卡片与插件运行期读取同一份。 */
+export const SETTINGS_NS = settingsNamespace('dsh-plus-subagent-model')
+
+/** 思考程度哨兵值：继承主代理（不注入 effort 字段）。 */
+export const EFFORT_INHERIT = 'inherit'
+/** 思考程度哨兵值：跟随模型默认（显式剥离任何继承/推导出的 effort）。 */
+export const EFFORT_DEFAULT = 'default'
+
+/** 一条条目的规范输出形态。 */
+export interface EntryConfig {
+  enabled: boolean
+  provider: string
+  model: string
+  reasoningEffort: string
+}
+
+/** 配置的规范输出形态。 */
+export interface SubagentModelConfig {
+  enabled: boolean
+  entries: Record<string, EntryConfig>
+}
+
+/** 配置的宽松输入形态（schema 校验前的用户数据）。 */
+export interface SubagentModelConfigInput {
+  enabled?: boolean | null
+  entries?: Record<string, {
+    enabled?: boolean | null
+    provider?: string | null
+    model?: string | null
+    reasoningEffort?: string | null
+  }> | null
+}
+
+const EntrySchema = z.object({
+  enabled: z.boolean().description('该子代理 provider 行的开关').default(false),
+  provider: z.string().description('LLM 提供商 id；留空 = 继承主代理').default(''),
+  model: z.string().description('模型 id；留空 = 继承主代理').default(''),
+  reasoningEffort: z.string()
+    .description(`思考程度：${EFFORT_INHERIT}（继承主代理）/ ${EFFORT_DEFAULT}（跟随模型默认）/ 提供商目录档位 id`)
+    .default(EFFORT_INHERIT),
+})
+
+export const Config: z<SubagentModelConfigInput, SubagentModelConfig> = z.object({
+  enabled: z.boolean().description('总开关').default(false),
+  entries: z.dict(EntrySchema).description('按子代理 provider 名（spawn/fork/…）配置').default({}),
+})
+
+/** 注入子代理 AgentOptions 的结果对象：只含需要覆盖的字段。 */
+export interface InjectedOptions {
+  provider?: string
+  model?: string
+  /** 私有标记：随 agentOptions 抵达子代理 options，由 agent/request 监听器消费。 */
+  reasoningEffort?: string
+}
+
+/**
+ * 解析一条条目为要注入的 agentOptions 片段。
+ * 未启用或全继承时返回 undefined（完全保持 dsh 原生行为）。
+ */
+export function resolveEntry(entry: EntryConfig): InjectedOptions | undefined {
+  if (!entry.enabled) return undefined
+  const out: InjectedOptions = {}
+  if (entry.provider.length > 0) out.provider = entry.provider
+  if (entry.model.length > 0) out.model = entry.model
+  if (entry.reasoningEffort !== EFFORT_INHERIT) out.reasoningEffort = entry.reasoningEffort
+  return out.provider !== undefined || out.model !== undefined || out.reasoningEffort !== undefined
+    ? out
+    : undefined
+}
+
+/**
+ * 合并注入片段与工具行已有的 agentOptions：部署级显式配置优先，
+ * 插件只补空缺（standard preset 的工具行无 agentOptions，插件即生效）。
+ */
+export function mergeAgentOptions(
+  injected: InjectedOptions,
+  existing: InjectedOptions | undefined,
+): InjectedOptions {
+  return { ...injected, ...existing }
+}
+
+/** 请求配置的形状（与 dsh agent/request 瀑布产物的相关字段）。 */
+export interface RequestConfig {
+  provider: string
+  model: string
+  reasoningEffort?: string
+  maxTokens?: number
+}
+
+/**
+ * 把条目的 effort 决策应用到一次 LLM 请求配置上（纯函数）：
+ * - undefined：直通（未配置 effort，保持原生推导）；
+ * - EFFORT_DEFAULT：剥离 reasoningEffort（跟随模型默认，覆盖 fork 的 seed 继承）；
+ * - 其余：显式覆盖。
+ */
+export function applyEffort<T extends RequestConfig>(resolved: T, effort: string | undefined): T {
+  if (effort === undefined) return resolved
+  if (effort === EFFORT_DEFAULT) {
+    const { reasoningEffort: _dropped, ...rest } = resolved
+    return rest as T
+  }
+  return { ...resolved, reasoningEffort: effort } as T
+}
+
+/** 条目校验的输入面（卡片提交的可能为宽松形态）。 */
+export interface EntryValidationInput {
+  provider?: string | null
+  model?: string | null
+  reasoningEffort?: string | null
+}
+
+/** 校验一条用户提交的条目；返回错误消息，合法时返回 null。 */
+export function validateEntry(entry: EntryValidationInput): string | null {
+  const model = entry.model ?? ''
+  const provider = entry.provider ?? ''
+  const effort = entry.reasoningEffort ?? ''
+  if (model.length > 0 && provider.length === 0) {
+    return 'model 不能脱离 provider 单独配置（请先选择提供商或改回继承）'
+  }
+  if (effort.length === 0) {
+    return 'reasoningEffort 不能为空（inherit / default / 档位 id）'
+  }
+  return null
+}
+
+/** 配置卡片读取用的传输对象（writable 表示是否存在可写的 settings provider）。 */
+export interface WireEntry {
+  enabled: boolean
+  provider: string
+  model: string
+  reasoningEffort: string
+}
+
+export interface WireConfig {
+  enabled: boolean
+  entries: Record<string, WireEntry>
+  /** 当前已注册的子代理 provider 名（spawn/fork/…），供卡片合成空行。 */
+  subagentProviders: string[]
+  writable: boolean
+}
+
+export function toWire(cfg: SubagentModelConfig, subagentProviders: string[], writable: boolean): WireConfig {
+  const entries: Record<string, WireEntry> = {}
+  for (const [name, entry] of Object.entries(cfg.entries)) {
+    entries[name] = {
+      enabled: entry.enabled,
+      provider: entry.provider,
+      model: entry.model,
+      reasoningEffort: entry.reasoningEffort,
+    }
+  }
+  return { enabled: cfg.enabled, entries, subagentProviders: [...subagentProviders], writable }
+}
+
+/** 配置卡片写回用的宽松输入形态（字段全部可选，无默认值，深合并进用户层）。 */
+export interface WirePatchInput {
+  enabled?: boolean | null
+  entries?: Record<string, {
+    enabled?: boolean | null
+    provider?: string | null
+    model?: string | null
+    reasoningEffort?: string | null
+  }> | null
+}
+
+/** 配置卡片写回用的规范输出形态（校验后条目已填默认）。 */
+export interface WirePatchOutput {
+  enabled: boolean
+  entries: Record<string, EntryConfig>
+}
+
+export const WirePatch: z<WirePatchInput, WirePatchOutput> = z.object({
+  enabled: z.boolean(),
+  entries: z.dict(EntrySchema),
+})
+
+/** 把卡片提交的 patch 规整为 settings.update 的用户层 patch（entries 整体替换）。 */
+export function toUserPatch(input: WirePatchInput): Record<string, unknown> {
+  return { ...input }
+}

package/src/delegation.ts

@@ -0,0 +1,119 @@
+/**
+ * 运行时挂钩：子代理模型路由的注入点。
+ *
+ * 机制依据（官方 dsh-subagent / dsh-agent-loop）：
+ * - 子代理的模型由【创建时】的 AgentOptions 决定：`resolveChildAgentOptions(parent,
+ *   request.agentOptions, depth)` = 父 options 快照 + 显式 agentOptions（后者胜出）。
+ *   子代理不经 api-proxy 的 create/resume setup，不安装模型 selection，
+ *   `agent/request` 瀑布默认无人覆盖 —— 因此 provider/model 只需注入
+ *   `request.agentOptions`，路由即命中。
+ * - reasoningEffort 不在 AgentOptions 读取路径上（AgentLoop 只读 provider/model/maxTokens，
+ *   子代理 buildRequest 的 effort 仅来自自身 session 折叠的 request/header）。
+ *   故 effort 以私有字段随 agentOptions 抵达子代理 options，再由根 ctx 的
+ *   `agent/request` 瀑布监听器应用（origin==='subagent' 过滤）。
+ * - 冷恢复（continuable resume）：descriptor 持久化 agentProvider/agentModel
+ *   （来自 request.agentOptions），恢复后模型保持；effort 经 session log 的
+ *   request/header 保留 —— 与热路径注入结果一致。
+ *
+ * 两个挂钩均幂等（Symbol 标记 + dispose 恢复），HMR 重载安全。
+ * @module subagent-model/delegation
+ */
+import type { Context } from '@deepseek-ai/cordis'
+import type { Agent, AgentOptions } from '@deepseek-ai/dsh-agent'
+import type { LlmCallConfig } from '@deepseek-ai/dsh-llm'
+import type { ContinuableStartSpec, SubagentStartRequest } from '@deepseek-ai/dsh-subagent'
+
+import { applyEffort, mergeAgentOptions, resolveEntry, type RequestConfig, type SubagentModelConfig } from './config.ts'
+
+const WRAPPED = Symbol('dsh-plus-subagent-model.wrapped')
+
+/** 子代理服务的最小运行期面（仅包装用到的两个入口）。 */
+interface SubagentsLike {
+  start(name: string, request: SubagentStartRequest): Promise<unknown>
+  startContinuable(spec: ContinuableStartSpec): Promise<unknown>
+}
+
+function entryFor(current: () => SubagentModelConfig, name: string | undefined) {
+  if (name === undefined) return undefined
+  const entry = current().entries[name]
+  return entry === undefined ? undefined : resolveEntry(entry)
+}
+
+/**
+ * 包装 `ctx.subagents.start` / `startContinuable`：按 provider 名命中配置条目，
+ * 向委托请求注入 agentOptions（显式工具行配置优先，插件只补空缺）。
+ * 未命中条目时完全直通（原生继承主代理行为）。
+ * 返回注销函数（恢复原方法），随调用方 fiber 释放。
+ */
+export function installDelegationHook(
+  ctx: Context,
+  current: () => SubagentModelConfig,
+): () => void {
+  const subagents = ctx.get('subagents') as SubagentsLike | undefined
+  if (subagents === undefined) {
+    ctx.logger('subagent-model').warn('subagents 服务不可用，跳过委托挂钩')
+    return () => {}
+  }
+  const marked = subagents as SubagentsLike & { [WRAPPED]?: boolean }
+  if (marked[WRAPPED]) {
+    ctx.logger('subagent-model').warn('subagents 服务已被本插件包装，跳过重复挂钩')
+    return () => {}
+  }
+  const originalStart = subagents.start.bind(subagents)
+  const originalContinuable = subagents.startContinuable.bind(subagents)
+  subagents.start = async (name, request) => {
+    const injected = entryFor(current, name)
+    if (injected === undefined) return originalStart(name, request)
+    return originalStart(name, {
+      ...request,
+      agentOptions: mergeAgentOptions(injected, request.agentOptions),
+    })
+  }
+  subagents.startContinuable = async (spec) => {
+    const injected = entryFor(current, spec.provider)
+    if (injected === undefined) return originalContinuable(spec)
+    return originalContinuable({
+      ...spec,
+      request: {
+        ...spec.request,
+        agentOptions: mergeAgentOptions(injected, spec.request.agentOptions),
+      },
+    })
+  }
+  marked[WRAPPED] = true
+  return ctx.effect(
+    () => () => {
+      subagents.start = originalStart
+      subagents.startContinuable = originalContinuable
+      delete marked[WRAPPED]
+    },
+    'subagent-model: delegation hook',
+  )
+}
+
+/**
+ * 读取一次 LLM 请求的发起 agent 上本插件携带的 effort 私有标记：
+ * 仅对子代理（session header origin==='subagent'）生效，主代理不受影响。
+ * 纯函数（agent 为最小结构面），便于单测。
+ */
+export function childEffortOf(agent: {
+  session: { header: { origin?: 'subagent' } }
+  options: AgentOptions & { reasoningEffort?: string }
+}): string | undefined {
+  if (agent.session.header.origin !== 'subagent') return undefined
+  return agent.options.reasoningEffort
+}
+
+/**
+ * 根 ctx 监听 `agent/request` 瀑布：对子代理应用条目配置的思考程度。
+ * provider/model 无需在此处理（路由直接读 options）。
+ * 根级监听覆盖 HMR 重载后已存在子代理的后续请求。
+ */
+export function installChildRoute(ctx: Context): void {
+  ctx.on('agent/request', async (payload, next) => {
+    const resolved = await next()
+    const effort = childEffortOf(payload.agent)
+    if (effort === undefined) return resolved
+    return applyEffort(resolved as RequestConfig, effort) as LlmCallConfig
+  })
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+/**
+ * dsh 插件：子代理独立模型配置（subagent / subagent_fork 等）。
+ * 为子代理按 provider 名配置 LLM 提供商、模型与思考程度（reasoningEffort），
+ * 或选择从主代理继承；只负责模型选定，其余参数（maxTokens/persona/toolFilter/
+ * maxDepth 等）保持 dsh 原生行为。配置 UI 位于 webui 设置-插件-插件配置，
+ * 持久化到 $DSH_HOME/settings.yaml 并热生效。
+ * @module @dsh-plus/subagent-model
+ */
+import type { Context } from '@deepseek-ai/cordis'
+
+import { Config, type SubagentModelConfig } from './config.ts'
+import { SubagentModelService } from './service.ts'
+
+export const name = 'dsh-plus-subagent-model'
+
+export const inject = ['subagents', 'llm'] as const
+
+export { Config }
+
+export type { EntryConfig, InjectedOptions, SubagentModelConfig } from './config.ts'
+export { SubagentModelService } from './service.ts'
+
+export function apply(ctx: Context, config: SubagentModelConfig): void {
+  ctx.plugin(SubagentModelService, config)
+}

package/src/service.ts

@@ -0,0 +1,56 @@
+/**
+ * SubagentModelService：子代理模型配置中枢。
+ * - 配置：installSettingsSection 接入 settings 用户层（$DSH_HOME/settings.yaml，热生效），
+ *   无 settings provider 时退化为 cordis 行级 config。
+ * - 委托挂钩：包装 ctx.subagents.start/startContinuable，按 provider 名注入
+ *   agentOptions（provider/model/effort 私有标记），未命中条目完全直通。
+ * - 子代理路由：根 ctx 的 agent/request 瀑布监听，把条目 effort 应用到子代理请求。
+ * - 配置通道：ctx.webServer 注册 config/catalog 同源路由（官方 settings RPC
+ *   白名单不含第三方 namespace）。
+ * @module @dsh-plus/subagent-model
+ */
+import { Context, Service } from '@deepseek-ai/cordis'
+import { installSettingsSection } from '@deepseek-ai/dsh-settings'
+
+import { registerConfigApi } from './config-api.ts'
+import { Config, SETTINGS_NS, type SubagentModelConfig } from './config.ts'
+import { installChildRoute, installDelegationHook } from './delegation.ts'
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    subagentModel: SubagentModelService
+  }
+}
+
+export class SubagentModelService extends Service {
+  static [Context.inject] = ['subagents', 'llm']
+
+  private current: () => SubagentModelConfig
+
+  constructor(ctx: Context, config: SubagentModelConfig) {
+    super(ctx, 'subagentModel')
+    this.current = () => config
+    installSettingsSection(ctx, SETTINGS_NS, Config, config, {
+      setSource: (source) => {
+        this.current = source
+      },
+      onChange: () => {},
+    })
+    installDelegationHook(ctx, () => this.current())
+    installChildRoute(ctx)
+    ctx.inject(['webServer'], (webCtx) => {
+      registerConfigApi(webCtx, this)
+    })
+  }
+
+  /** 当前生效配置（settings 用户层解析结果或 cordis 行级 config）。 */
+  currentConfig(): SubagentModelConfig {
+    return this.current()
+  }
+
+  /** 已注册的子代理 provider 名（配置卡片据此合成行）。 */
+  subagentProviders(): string[] {
+    const subagents = this.ctx.get('subagents')
+    return subagents === undefined ? [] : [...subagents.list()]
+  }
+}