dsh-plugin-effort-declare 0.1.0

package/src/client/README.md

@@ -0,0 +1,27 @@
+# src/client/
+
+<p align="center">
+  <samp>
+    <strong>中文</strong> ·
+    <a href="./README.en.md">English</a>
+  </samp>
+</p>
+
+浏览器半区：在 Web UI 的设置面板注册「推理档位」，并经官方 settings RPC 写入 `llm-pi-ai`。
+
+`apply` 接线失败会抛出，与官方模型页相同；不要整段 `try/catch` 吞掉。卸载时 locale、CSS 与事件订阅随 `ctx.effect` 清理。
+
+跨插件协作只使用 Cordis 服务（`connection`、`settingsScope`、`settingsSchema`、`slots`、`locale`、`remote`）。不要 value-import `@deepseek-ai/dsh-client-ui-settings-models`：client bundle 的 purity 规则禁止把其它 `@deepseek-ai/*` 打进包内（shell 冻结模块表里的平台模块除外）。
+
+## 这个目录里有什么
+
+| 文件 | 说明 |
+| --- | --- |
+| [`index.ts`](./index.ts) | 注册 zh/en 文案、CSS（`ctx.effect` 插入/移除）与 `settings.section`（id `effort-declare`，order 15）。在 `apply` 里订阅 `settings/document-updated`（仅 `llm-pi-ai`）、`llm/adapters-updated`、`connection/reset`。 |
+| [`EffortDeclareSection.tsx`](./EffortDeclareSection.tsx) | 路由卡片、预设、Off 三态、高级协议开关、保存与取消。 |
+| [`load-drafts.ts`](./load-drafts.ts) | 从 `llm.providers` + 镜像组装草稿；草稿取自 `user`，协议分类可用 `value`。 |
+| [`locales.ts`](./locales.ts) | 文案 namespace `plugin-effort-declare`。 |
+| [`effort-declare.module.css`](./effort-declare.module.css) | 仅使用 `--dsw-alias-*` 设计令牌，保证暗色主题正确。 |
+| [`schema-ops.ts`](./schema-ops.ts) | 将 `settingsSchema` 收成普通回调，避免把服务身份带进 React。 |
+
+样式与交互对齐官方模型页，而不是带浅色 fallback 的 `--ds-*` 变量。

package/src/client/effort-declare.module.css

@@ -0,0 +1,278 @@
+/* Effort-declare settings section — --dsw-alias-* only (dark theme safe). */
+
+.section {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  max-width: 720px;
+  color: var(--dsw-alias-label-primary);
+}
+
+.title {
+  margin: 0;
+  font-size: 16px;
+  line-height: 24px;
+  font-weight: 500;
+  color: var(--dsw-alias-label-primary);
+}
+
+.intro {
+  margin: 0;
+  font-size: 14px;
+  line-height: 22px;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+.notice {
+  margin: 0;
+  font-size: 12px;
+  line-height: 18px;
+  color: var(--dsw-alias-state-warn-label);
+}
+
+.savedNotice {
+  margin: 0;
+  font-size: 12px;
+  line-height: 18px;
+  color: var(--dsw-alias-state-success-primary);
+}
+
+.error {
+  margin: 0;
+  font-size: 12px;
+  line-height: 18px;
+  color: var(--dsw-alias-state-error-primary);
+}
+
+.rows {
+  list-style: none;
+  margin: 12px 0 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.rowCard {
+  border: 1px solid var(--dsw-alias-border-l2);
+  border-radius: 12px;
+  padding: 12px 14px;
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.rowHead {
+  display: flex;
+  align-items: baseline;
+  gap: 8px;
+}
+
+.rowName {
+  font-size: 14px;
+  line-height: 22px;
+  font-weight: 500;
+  color: var(--dsw-alias-label-primary);
+}
+
+.rowTag {
+  flex: none;
+  padding: 1px 6px;
+  border: 1px solid var(--dsw-alias-border-l3);
+  border-radius: 4px;
+  font-size: 11px;
+  line-height: 16px;
+  color: var(--dsw-alias-label-secondary);
+}
+
+.compatSummary {
+  margin: 0;
+  font-size: 12px;
+  line-height: 18px;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+.presetRow,
+.actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+  align-items: center;
+}
+
+.fieldLabel {
+  font-size: 12px;
+  line-height: 18px;
+  font-weight: 500;
+  color: var(--dsw-alias-label-secondary);
+}
+
+.primaryButton,
+.secondaryButton {
+  box-sizing: border-box;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  height: 36px;
+  padding: 0 14px;
+  border-radius: 18px;
+  font: inherit;
+  font-size: 14px;
+  line-height: 22px;
+  cursor: pointer;
+}
+
+.primaryButton {
+  border: none;
+  background: var(--dsw-alias-button-primary-fill);
+  color: var(--dsw-alias-label-primary-foreground);
+}
+
+.primaryButton:hover:not(:disabled) {
+  background: var(--dsw-alias-button-primary-hover);
+}
+
+.secondaryButton {
+  border: 1px solid var(--dsw-alias-border-l2);
+  background: transparent;
+  color: var(--dsw-alias-label-primary);
+}
+
+.secondaryButton:hover:not(:disabled) {
+  background: var(--dsw-alias-interactive-bg-hover-solid);
+}
+
+.primaryButton:disabled,
+.secondaryButton:disabled,
+.linkButton:disabled,
+.input:disabled {
+  opacity: 0.4;
+  cursor: default;
+}
+
+.primaryButton:focus-visible,
+.secondaryButton:focus-visible,
+.linkButton:focus-visible,
+.input:focus-visible {
+  outline: none;
+  box-shadow: 0 0 0 2px var(--dsw-alias-border-l3);
+}
+
+.linkButton {
+  box-sizing: border-box;
+  display: inline-flex;
+  align-items: center;
+  height: 28px;
+  padding: 0 10px;
+  border: none;
+  border-radius: 14px;
+  background: transparent;
+  color: var(--dsw-alias-label-tertiary);
+  font: inherit;
+  font-size: 12px;
+  line-height: 18px;
+  cursor: pointer;
+}
+
+.linkButton:hover:not(:disabled) {
+  background: var(--dsw-alias-interactive-bg-hover);
+  color: var(--dsw-alias-label-secondary);
+}
+
+.modelEntry {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 10px 0;
+  border-top: 1px solid var(--dsw-alias-border-l2);
+}
+
+.modelHead {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: baseline;
+  gap: 8px;
+}
+
+.modelId {
+  font-size: 13px;
+  line-height: 20px;
+  font-weight: 500;
+}
+
+.modelName {
+  font-size: 12px;
+  line-height: 18px;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+.levels {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 10px 14px;
+}
+
+.level {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 12px;
+  line-height: 18px;
+}
+
+.wireRow {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+  align-items: center;
+}
+
+.input,
+.selectInput {
+  box-sizing: border-box;
+  height: 32px;
+  padding: 0 10px;
+  border: 1px solid var(--dsw-alias-border-l2);
+  border-radius: 8px;
+  background: var(--dsw-alias-bg-module-platform);
+  color: var(--dsw-alias-label-primary);
+  font: inherit;
+  font-size: 13px;
+}
+
+.wireInput {
+  width: 7em;
+}
+
+.offGroup {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+
+.advanced {
+  border-top: 1px solid var(--dsw-alias-border-l2);
+  padding-top: 8px;
+}
+
+.advanced summary {
+  cursor: pointer;
+  font-size: 12px;
+  line-height: 18px;
+  color: var(--dsw-alias-label-secondary);
+}
+
+.advancedBody {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  padding-top: 10px;
+}
+
+.check {
+  display: flex;
+  align-items: flex-start;
+  gap: 8px;
+  font-size: 12px;
+  line-height: 18px;
+}

package/src/client/index.ts

@@ -0,0 +1,97 @@
+/**
+ * dsh-plugin-effort-declare — browser half: settings.section for per-model
+ * reasoning effort declarations.
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+import type { ConnectionHandle } from '@deepseek-ai/dsh-api-remotes/client'
+import type {} from '@deepseek-ai/dsh-client-ui-settings/client'
+import type {} from '@deepseek-ai/dsh-client-locale/client'
+import type {} from '@deepseek-ai/dsh-api-remotes/client'
+import { EffortDeclareSection } from './EffortDeclareSection.tsx'
+import type { EffortDeclareSectionInjected, InvalidationSource } from './EffortDeclareSection.tsx'
+import { bindSchema } from './schema-ops.ts'
+import { LLM_PI_AI_NS } from '../core/catalog.ts'
+import { NS, en, zh, type EffortDeclareKey } from './locales.ts'
+import { cssTagId, cssText } from './effort-declare.module.css'
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface LocaleNamespaceMap {
+    /** Effort-declare settings section copy. */
+    'plugin-effort-declare': EffortDeclareKey
+  }
+}
+
+export const inject = ['slots', 'locale', 'connection', 'remote', 'settingsScope', 'settingsSchema']
+
+const PLUGIN_ID = 'dsh-plugin-effort-declare'
+
+function mountPluginCss(): () => void {
+  if (typeof document === 'undefined') return () => {}
+  const selector = `style[data-plugin-css=${JSON.stringify(cssTagId)}]`
+  let tag = document.querySelector(selector) as HTMLStyleElement | null
+  if (tag === null) {
+    tag = document.createElement('style')
+    tag.dataset.plugin = PLUGIN_ID
+    tag.dataset.pluginCss = cssTagId
+    document.head.appendChild(tag)
+  }
+  tag.textContent = cssText
+  return () => { tag?.remove() }
+}
+
+export function apply(ctx: ClientContext): void {
+  ctx.effect(() => ctx.locale.register(NS, { zh, en }), `${PLUGIN_ID}: dictionaries`)
+  ctx.effect(() => mountPluginCss(), `${PLUGIN_ID}: css`)
+
+  const connection = ctx.get('connection') as ConnectionHandle
+  const settingsSchema = ctx.settingsSchema
+  const schema = bindSchema({
+    rehydrate: serialized => settingsSchema.rehydrate(serialized),
+    nodeAtPath: (root, path) => settingsSchema.nodeAtPath(
+      root as Parameters<typeof settingsSchema.nodeAtPath>[0],
+      path,
+    ),
+    getPath: (value, path) => settingsSchema.getPath(value, path),
+    hasPath: (value, path) => settingsSchema.hasPath(value, path),
+  })
+  const t = ctx.locale.bind(NS) as EffortDeclareSectionInjected['t']
+  const describe = ctx.settingsScope.describe()
+  const invalidation = new Set<(source: InvalidationSource) => void>()
+
+  ctx.effect(() => {
+    const emit = (source: InvalidationSource) => {
+      for (const listener of invalidation) listener(source)
+    }
+    const disposers = [
+      ctx.remote.$on('settings/document-updated', (ns: string) => {
+        if (ns !== LLM_PI_AI_NS) return
+        emit('settings')
+      }),
+      ctx.remote.$on('llm/adapters-updated', () => { emit('directory') }),
+      ctx.on('connection/reset', () => { emit('directory') }),
+    ]
+    return () => {
+      for (const dispose of disposers) dispose()
+    }
+  }, `${PLUGIN_ID}: invalidations`)
+
+  const subscribeInvalidate: EffortDeclareSectionInjected['subscribeInvalidate'] = (listener) => {
+    invalidation.add(listener)
+    return () => { invalidation.delete(listener) }
+  }
+
+  ctx.slots.inject('settings.section', () => ctx.slots.register({
+    name: 'settings.section',
+    id: 'effort-declare',
+    order: 15,
+    label: () => t('nav'),
+    locale: NS,
+    inject: (): EffortDeclareSectionInjected => ({
+      api: connection.api,
+      describe,
+      schema,
+      t,
+      subscribeInvalidate,
+    }),
+  }, EffortDeclareSection))
+}

package/src/client/load-drafts.ts

@@ -0,0 +1,83 @@
+/**
+ * Load editable route drafts from llm.providers + the llm-pi-ai namespace.
+ * Drafts come from the user layer; route protocol classification may use effective value.
+ */
+import type { IApiClient, SettingsNamespaceView } from '@deepseek-ai/dsh-api-remotes/client'
+import type { SettingsDescribeFace } from '@deepseek-ai/dsh-client-ui-settings/client'
+import {
+  FALLBACK_THINKING_FORMATS,
+  LLM_PI_AI_NS,
+  SCHEMA_PROBE_ROUTE,
+} from '../core/catalog.ts'
+import { routeDraftFromUserProfile, type RouteDraft } from '../core/drafts.ts'
+import { classifyRoute, profileAt, unionStringChoices } from '../core/filter.ts'
+import { isPlainObject } from '../core/paths.ts'
+import type { SchemaOps } from './schema-ops.ts'
+
+function schemaDefaultString(node: unknown): string | undefined {
+  if (!isPlainObject(node) || !isPlainObject(node.meta)) return undefined
+  return typeof node.meta.default === 'string' ? node.meta.default : undefined
+}
+
+export interface LoadDraftsResult {
+  writable: boolean
+  formats: string[]
+  drafts: RouteDraft[]
+  error?: string
+}
+
+/**
+ * First paint: `ensure()` (reads only from idle). Never treat ensure as refresh.
+ * Callers that must not apply a stale settlement compare generation themselves.
+ */
+export async function loadDrafts(
+  api: Pick<IApiClient, 'llm'>,
+  describe: Pick<SettingsDescribeFace, 'ensure' | 'getSnapshot'>,
+  schema: SchemaOps,
+): Promise<LoadDraftsResult> {
+  await describe.ensure()
+  const mirrored = describe.getSnapshot()
+  if (mirrored.view === undefined) {
+    return { writable: false, formats: [...FALLBACK_THINKING_FORMATS], drafts: [], error: mirrored.error ?? undefined }
+  }
+  const providersResponse = await api.llm.providers({})
+  if (!providersResponse.result.ok) {
+    return {
+      writable: mirrored.view.writable,
+      formats: [...FALLBACK_THINKING_FORMATS],
+      drafts: [],
+      error: providersResponse.result.error.message,
+    }
+  }
+  const namespaces = new Map(mirrored.view.namespaces.map((view: SettingsNamespaceView) => [view.ns, view]))
+  const pi = namespaces.get(LLM_PI_AI_NS)
+  let formats: string[] = [...FALLBACK_THINKING_FORMATS]
+  let schemaDefaultApi: string | undefined
+  if (pi !== undefined) {
+    try {
+      const root = schema.rehydrate(pi.schema)
+      const formatNode = schema.nodeAtPath(root, ['providers', SCHEMA_PROBE_ROUTE, 'compat', 'thinkingFormat'])
+      const fromSchema = unionStringChoices(formatNode)
+      if (fromSchema.length > 0) formats = fromSchema
+      schemaDefaultApi = schemaDefaultString(schema.nodeAtPath(root, ['providers', SCHEMA_PROBE_ROUTE, 'api']))
+    } catch {
+      // Live schema walk is best-effort; fallback list is test-pinned.
+    }
+  }
+  const drafts: RouteDraft[] = []
+  for (const entry of providersResponse.result.value.providers) {
+    const settingsPath = entry.settingsPath !== undefined && entry.settingsPath.length > 0
+      ? [...entry.settingsPath]
+      : ['providers', entry.provider]
+    const effective = profileAt(pi?.value, settingsPath, entry.provider)
+    if (!classifyRoute(entry, effective, schemaDefaultApi).editable) continue
+    drafts.push(routeDraftFromUserProfile({
+      provider: entry.provider,
+      displayName: entry.displayName ?? entry.provider,
+      settingsPath,
+      revision: pi?.revision ?? 0,
+      userProfile: profileAt(pi?.user, settingsPath, entry.provider),
+    }))
+  }
+  return { writable: mirrored.view.writable, formats, drafts }
+}

package/src/client/locales.ts

@@ -0,0 +1,133 @@
+/**
+ * Dictionary namespace for the effort-declare settings section.
+ */
+
+export type EffortDeclareKey =
+  | 'nav'
+  | 'title'
+  | 'intro'
+  | 'empty'
+  | 'emptyHint'
+  | 'loadError'
+  | 'loading'
+  | 'readOnly'
+  | 'save'
+  | 'saving'
+  | 'cancel'
+  | 'saved'
+  | 'conflict'
+  | 'dirtyConflict'
+  | 'presets'
+  | 'presetDeepSeek'
+  | 'presetOpenAI'
+  | 'presetToggle'
+  | 'presetToggleWarn'
+  | 'model'
+  | 'levels'
+  | 'wire'
+  | 'offMode'
+  | 'offAbsent'
+  | 'offEmpty'
+  | 'offValue'
+  | 'offValuePlaceholder'
+  | 'clear'
+  | 'advanced'
+  | 'thinkingFormat'
+  | 'thinkingFormatDefault'
+  | 'supportsDeveloperRole'
+  | 'supportsReasoningEffort'
+  | 'developerTrueHint'
+  | 'compatSummary'
+  | 'errorEmpty'
+  | 'errorOffOnly'
+  | 'errorBadWire'
+  | 'noModels'
+  | 'reload'
+
+export const NS = 'plugin-effort-declare'
+
+export const zh: Record<EffortDeclareKey, string> = {
+  nav: '推理档位',
+  title: '推理档位声明',
+  intro: '本页声明「这模型能选哪些推理档」。对话里的档位选择仍在输入框模型菜单。没声明 = 和现在一样没有 Effort 行。不会改密钥、目录或当次选择。',
+  empty: '没有可编辑的手工 openai-completions 路由。',
+  emptyHint: '请先到「模型」页添加提供方（llm-pi-ai 手工路由）。官方 DeepSeek 与 catalog 路由不在本页编辑。需要 DSH ≥ 0.1.0-rc.8（providers.declared）。',
+  loadError: '无法加载提供方或设置。',
+  loading: '正在加载…',
+  readOnly: '当前设置为只读，无法保存。',
+  save: '保存',
+  saving: '保存中…',
+  cancel: '取消',
+  saved: '已保存。对话选择器会按新的能力声明显示 Effort 行。',
+  conflict: '设置已被其他地方改过，请重新加载后再保存。',
+  dirtyConflict: '此路由有未保存修改，设置已在其他地方更新。保存会写到最新文档上，或先取消再改。',
+  presets: '预设',
+  presetDeepSeek: 'DeepSeek 兼容',
+  presetOpenAI: 'OpenAI 兼容',
+  presetToggle: '仅开/关',
+  presetToggleWarn: '选择器里多档在线上没有区别：除 Off 外请求体相同。',
+  model: '模型',
+  levels: '可选档位',
+  wire: '线上拼写',
+  offMode: 'Off',
+  offAbsent: '无 Off',
+  offEmpty: 'Off 且不发参数',
+  offValue: 'Off 且发字符串',
+  offValuePlaceholder: 'none',
+  clear: '清除本模型声明',
+  advanced: '高级：协议方言',
+  thinkingFormat: 'thinkingFormat',
+  thinkingFormatDefault: '默认（openai）',
+  supportsDeveloperRole: '系统提示走 system 而不是 developer（supportsDeveloperRole: false）',
+  supportsReasoningEffort: '不发 reasoning_effort，只发开关（supportsReasoningEffort: false）',
+  developerTrueHint: '当前文档是 supportsDeveloperRole: true。v1 只能强制 false 或缺席；勾选会写成 false，取消勾选会删除该键。',
+  compatSummary: '协议',
+  errorEmpty: '不能保存空的 reasoningEfforts。请选择档位，或清除声明。',
+  errorOffOnly: '不能只开 Off，必须再开一档思考档。',
+  errorBadWire: '思考档必须填写线上拼写；只有 Off 可以留空。不能使用未知档位键。',
+  noModels: '这条路由还没有 models 列表。请先到「模型」页添加模型。',
+  reload: '重新加载',
+}
+
+export const en: Record<EffortDeclareKey, string> = {
+  nav: 'Reasoning efforts',
+  title: 'Reasoning effort declarations',
+  intro: 'This page declares which reasoning levels a model can offer. The per-turn choice stays in the composer model menu. Undeclared models keep having no Effort row. Keys, catalogs, and the current selection are not edited here.',
+  empty: 'No editable hand-declared openai-completions routes.',
+  emptyHint: 'Add a provider on the Models page first (an llm-pi-ai hand-declared route). Official DeepSeek and catalog routes are not edited here. Requires DSH ≥ 0.1.0-rc.8 (providers.declared).',
+  loadError: 'Could not load providers or settings.',
+  loading: 'Loading…',
+  readOnly: 'Settings are read-only; saving is disabled.',
+  save: 'Save',
+  saving: 'Saving…',
+  cancel: 'Cancel',
+  saved: 'Saved. The composer Effort row follows this capability declaration.',
+  conflict: 'Settings changed elsewhere. Reload, then save again.',
+  dirtyConflict: 'This route has unsaved edits and settings changed elsewhere. Save writes onto the latest document, or cancel first.',
+  presets: 'Presets',
+  presetDeepSeek: 'DeepSeek compatible',
+  presetOpenAI: 'OpenAI compatible',
+  presetToggle: 'On/off only',
+  presetToggleWarn: 'Multiple selector levels are identical on the wire except Off.',
+  model: 'Model',
+  levels: 'Offered levels',
+  wire: 'Wire spelling',
+  offMode: 'Off',
+  offAbsent: 'No Off',
+  offEmpty: 'Off, send nothing',
+  offValue: 'Off, send a string',
+  offValuePlaceholder: 'none',
+  clear: 'Clear this model’s declaration',
+  advanced: 'Advanced: protocol dialect',
+  thinkingFormat: 'thinkingFormat',
+  thinkingFormatDefault: 'Default (openai)',
+  supportsDeveloperRole: 'Send system prompts as system, not developer (supportsDeveloperRole: false)',
+  supportsReasoningEffort: 'Do not send reasoning_effort; switch only (supportsReasoningEffort: false)',
+  developerTrueHint: 'The document has supportsDeveloperRole: true. v1 can only force false or omit the key; checking writes false, unchecking deletes the key.',
+  compatSummary: 'Protocol',
+  errorEmpty: 'Empty reasoningEfforts cannot be saved. Pick levels, or clear the declaration.',
+  errorOffOnly: 'Off alone is not enough; declare at least one thinking level.',
+  errorBadWire: 'Thinking levels need a wire spelling; only Off may be empty. Unknown effort keys are rejected.',
+  noModels: 'This route has no models list yet. Add models on the Models page first.',
+  reload: 'Reload',
+}

package/src/client/schema-ops.ts

@@ -0,0 +1,20 @@
+/**
+ * Bind the settings-owned schema service without importing executable
+ * helpers from another client plugin (bundle purity).
+ */
+export interface SchemaOps {
+  rehydrate: (serialized: unknown) => unknown
+  nodeAtPath: (root: unknown, path: readonly string[]) => unknown
+  getPath: (value: unknown, path: readonly string[]) => unknown
+  hasPath: (value: unknown, path: readonly string[]) => boolean
+}
+
+/** Wrap a live settingsSchema service as plain callbacks. */
+export function bindSchema(service: SchemaOps): SchemaOps {
+  return {
+    rehydrate: serialized => service.rehydrate(serialized),
+    nodeAtPath: (root, path) => service.nodeAtPath(root, path),
+    getPath: (value, path) => service.getPath(value, path),
+    hasPath: (value, path) => service.hasPath(value, path),
+  }
+}

package/src/core/README.en.md

@@ -0,0 +1,27 @@
+# src/core/
+
+<p align="center">
+  <samp>
+    <a href="./README.md">中文</a> ·
+    <strong>English</strong>
+  </samp>
+</p>
+
+Domain logic for the plugin: no React, no Cordis service instances. The settings page and Vitest both depend on these pure functions, so effort semantics can regress without booting DSH.
+
+Canonical level names and `thinkingFormat` values follow `@deepseek-ai/dsh-llm-pi-ai` (0.1.0-rc.8). A fallback whitelist is pinned by tests so the UI cannot silently drift from the upstream schema.
+
+## What's in this directory
+
+| File | Role |
+| --- | --- |
+| [`catalog.ts`](./catalog.ts) | Canonical level order, `thinkingFormat` fallback list, `llm-pi-ai` / DeepSeek constants. |
+| [`efforts.ts`](./efforts.ts) | `reasoningEfforts` read/write, Off tri-state, validation (empty object / Off-only / unknown keys return an error code, never throw). |
+| [`presets.ts`](./presets.ts) | DeepSeek, OpenAI, and on/off presets; each states all three dialect keys; spread onto existing model rows and route `compat`. |
+| [`path-ops.ts`](./path-ops.ts) | Same one-level key diff as the official Models page; `buildSaveOps` uses `settingsPath` and only submits that route’s full `models` table and dirty `compat` keys. |
+| [`drafts.ts`](./drafts.ts) | User-layer drafts, dirty aligned with pathOps, post-save revision bump, dirty merge, generation. |
+| [`paths.ts`](./paths.ts) | Nested reads; clones of objects and model tables (non-object rows skipped). |
+| [`filter.ts`](./filter.ts) | Which routes are editable: hand-declared `llm-pi-ai` + openai-completions; skip catalog and official DeepSeek. |
+| [`validate.ts`](./validate.ts) | Per-row `reasoningEfforts` validation. |
+
+An **absent** field means default-off. Do not encode “undeclared” as `reasoningEfforts: false` — in official semantics `false` strips reasoning from a catalog model.

package/src/core/README.md

@@ -0,0 +1,27 @@
+# src/core/
+
+<p align="center">
+  <samp>
+    <strong>中文</strong> ·
+    <a href="./README.en.md">English</a>
+  </samp>
+</p>
+
+本插件的领域逻辑：无 React、无 Cordis 服务实例。设置页与 Vitest 都只依赖这些纯函数，因此档位语义可以在不启动 DSH 的情况下回归。
+
+规范键名与 `thinkingFormat` 取值对齐 `@deepseek-ai/dsh-llm-pi-ai`（0.1.0-rc.8）。仓库内有回退白名单，并由测试钉住，避免 UI 与上游 schema 静默分叉。
+
+## 这个目录里有什么
+
+| 文件 | 说明 |
+| --- | --- |
+| [`catalog.ts`](./catalog.ts) | 规范档位顺序、`thinkingFormat` 回退列表、`llm-pi-ai` / DeepSeek 相关常量。 |
+| [`efforts.ts`](./efforts.ts) | `reasoningEfforts` 读写、Off 三态、校验（空对象 / 只开 Off / 未知键返回错误码，不抛异常）。 |
+| [`presets.ts`](./presets.ts) | DeepSeek、OpenAI、仅开/关三套预设；每套对三个方言键都表态；spread 到已有模型行与路由 `compat`。 |
+| [`path-ops.ts`](./path-ops.ts) | 与官方模型页相同的一层键 diff；`buildSaveOps` 使用 `settingsPath`，只提交该路由的 `models` 整表和有差异的 `compat` 键。 |
+| [`drafts.ts`](./drafts.ts) | 用户层草稿、dirty 与 pathOps 一致、保存后 revision、脏卡合并、generation。 |
+| [`paths.ts`](./paths.ts) | 嵌套读取、对象与模型表的 clone（非对象行跳过）。 |
+| [`filter.ts`](./filter.ts) | 哪些路由可编辑：手工 `llm-pi-ai` + openai-completions；排除 catalog 与官方 DeepSeek。 |
+| [`validate.ts`](./validate.ts) | 对单行 `reasoningEfforts` 调用校验。 |
+
+**缺席字段**表示默认关闭。不要把「未声明」写成 `reasoningEfforts: false`——`false` 在官方语义里是从 catalog 模型上剥掉推理。