@mhfire/dsh-im-bridge 0.1.3 → 0.2.0

package/src/client/card-form.ts

@@ -0,0 +1,293 @@
+/**
+ * Staged settings form owned by this plugin.
+ * Mirrors the Host Plugins section model without importing its chrome.
+ */
+
+import {
+  createSnapshotStore,
+  type SettingsScope,
+  type SettingsScopeSnapshot,
+  type SnapshotStore,
+} from '@deepseek-ai/dsh-client-runtime/client'
+
+/** Write one staged field performs on save. */
+export type FieldWrite =
+  | { kind: 'set'; value: unknown }
+  | { kind: 'clear' }
+
+/** Convert one section field between stored value and draft text. */
+export interface CardFieldSpec {
+  /** Field name inside the namespace section. */
+  field: string
+  /** Render a stored value as draft text. */
+  format: (value: unknown) => string
+  /** The write this draft stages, or undefined when the text is invalid. */
+  parse: (text: string) => FieldWrite | undefined
+}
+
+/**
+ * A control whose literal never rides a response. The draft starts blank;
+ * a blank draft writes nothing so a save cannot clear a stored secret.
+ */
+export interface CardSecretSpec {
+  /** Field name addressing this control inside the card's form. */
+  field: string
+  /** Write the staged text; resolves to whether the Host accepted it. */
+  write: (text: string) => Promise<boolean>
+}
+
+/** One field as a control renders it. */
+export interface CardFieldState {
+  /** Draft text the control renders. */
+  text: string
+  /** Whether saving would leave a user-layer entry. */
+  overridden: boolean
+  /** Whether the draft is not a value this field accepts. */
+  invalid: boolean
+}
+
+/** Card-level form state. */
+export interface CardShell {
+  /** False while the namespace is not served; the card renders nothing. */
+  available: boolean
+  /** Whether the Host document accepts writes. */
+  writable: boolean
+  /** Whether the form holds edits a save would write. */
+  dirty: boolean
+  /** Whether any staged draft is invalid. */
+  invalid: boolean
+  /** Whether a save is crossing the wire. */
+  saving: boolean
+  /** Whether the last save did not land. */
+  failed: boolean
+}
+
+/** Write actions a card's slot entry injects. */
+export interface CardActions {
+  /** Stage draft text for one field. */
+  edit: (field: string, text: string) => void
+  /** Stage a clear so the field re-inherits the composition layer. */
+  resetField: (field: string) => void
+  /** Write every staged edit, then re-seed from what the Host accepted. */
+  save: () => void
+  /** Drop every staged edit. */
+  discard: () => void
+}
+
+interface StagedEdit {
+  text: string
+  clear: boolean
+}
+
+interface PlannedWrite {
+  field: string
+  run: (() => Promise<boolean>) | undefined
+}
+
+/** Whole-number field. Empty draft clears. */
+export function numberField(field: string): CardFieldSpec {
+  return {
+    field,
+    format: value => typeof value === 'number' ? String(value) : '',
+    parse: (text) => {
+      const trimmed = text.trim()
+      if (trimmed === '') return { kind: 'clear' }
+      const parsed = Number(trimmed)
+      return Number.isFinite(parsed) ? { kind: 'set', value: parsed } : undefined
+    },
+  }
+}
+
+/** Free-text field. Empty draft clears. */
+export function textField(field: string): CardFieldSpec {
+  return {
+    field,
+    format: value => typeof value === 'string' ? value : '',
+    parse: (text) => {
+      const trimmed = text.trim()
+      return trimmed === '' ? { kind: 'clear' } : { kind: 'set', value: trimmed }
+    },
+  }
+}
+
+/** Comma-separated string list. Empty draft stores []. */
+export function csvField(field: string): CardFieldSpec {
+  return {
+    field,
+    format: value => Array.isArray(value) ? value.join(',') : '',
+    parse: (text) => {
+      const items = text.split(',').map(item => item.trim()).filter(Boolean)
+      return { kind: 'set', value: items }
+    },
+  }
+}
+
+/** Stages edits over one settings namespace and writes them on save. */
+export class CardForm<T> {
+  private readonly specs: Map<string, CardFieldSpec>
+  private readonly secretSpecs: Map<string, CardSecretSpec>
+  private readonly staged = new Map<string, StagedEdit>()
+  private readonly listeners = new Set<() => void>()
+  private saving = false
+  private failed = false
+
+  /**
+   * @param scope - bound settings scope for this card's namespace.
+   * @param specs - section fields this card edits.
+   * @param secrets - write-only controls; a blank draft is a no-op.
+   */
+  constructor(
+    private readonly scope: SettingsScope<T>,
+    specs: CardFieldSpec[],
+    secrets: CardSecretSpec[] = [],
+  ) {
+    this.specs = new Map(specs.map(spec => [spec.field, spec]))
+    this.secretSpecs = new Map(secrets.map(spec => [spec.field, spec]))
+    scope.subscribe(() => { this.publish() })
+  }
+
+  /** Publish a projection rebuilt whenever the scope or a draft changes. */
+  bind<S>(project: () => S): SnapshotStore<S> {
+    const store = createSnapshotStore(project())
+    this.listeners.add(() => { store.set(project()) })
+    return store
+  }
+
+  /** Card-level state: what the Host serves and what a save would do. */
+  shell(): CardShell {
+    const snapshot = this.scope.getSnapshot()
+    const plan = this.plan()
+    return {
+      available: snapshot.status === 'ready',
+      writable: snapshot.writable,
+      dirty: plan.length > 0,
+      invalid: plan.some(item => item.run === undefined),
+      saving: this.saving,
+      failed: this.failed,
+    }
+  }
+
+  /** One control's staged text, override badge, and validity. */
+  field(field: string): CardFieldState {
+    const staged = this.staged.get(field)
+    if (this.secretSpecs.has(field)) {
+      return { text: staged?.text ?? '', overridden: false, invalid: false }
+    }
+    const spec = this.spec(field)
+    if (staged === undefined) {
+      return { text: spec.format(this.sectionValue(field)), overridden: this.stored(field), invalid: false }
+    }
+    const write = staged.clear ? { kind: 'clear' as const } : spec.parse(staged.text)
+    return {
+      text: staged.text,
+      overridden: write?.kind === 'set',
+      invalid: write === undefined,
+    }
+  }
+
+  /** Edit, reset, save, and discard actions bound to this form. */
+  actions(): CardActions {
+    return {
+      edit: (field, text) => { this.stage(field, { text, clear: false }) },
+      resetField: (field) => {
+        this.stage(field, { text: this.spec(field).format(this.baseValue(field)), clear: true })
+      },
+      save: () => { void this.save() },
+      discard: () => {
+        if (this.staged.size === 0 && !this.failed) return
+        this.staged.clear()
+        this.failed = false
+        this.publish()
+      },
+    }
+  }
+
+  /** Write every staged edit, then re-seed from what the Host accepted. */
+  async save(): Promise<void> {
+    const plan = this.plan()
+    const writes = plan.flatMap(item => item.run === undefined ? [] : [item.run])
+    if (plan.length === 0 || this.saving || writes.length !== plan.length) return
+    this.saving = true
+    this.failed = false
+    this.publish()
+    let landed = true
+    for (const write of writes) {
+      landed = await write() && landed
+    }
+    if (landed) this.staged.clear()
+    this.saving = false
+    this.failed = !landed
+    this.publish()
+  }
+
+  private plan(): PlannedWrite[] {
+    const plan: PlannedWrite[] = []
+    for (const [field, staged] of this.staged) {
+      const secret = this.secretSpecs.get(field)
+      if (secret !== undefined) {
+        const value = staged.text.trim()
+        if (value !== '') plan.push({ field, run: () => secret.write(value) })
+        continue
+      }
+      const spec = this.spec(field)
+      if (staged.clear) {
+        if (this.stored(field)) plan.push({ field, run: () => this.clear(field) })
+        continue
+      }
+      if (staged.text === spec.format(this.sectionValue(field))) continue
+      const write = spec.parse(staged.text)
+      if (write === undefined) plan.push({ field, run: undefined })
+      else if (write.kind === 'clear') plan.push({ field, run: () => this.clear(field) })
+      else plan.push({ field, run: () => this.store(field, write.value) })
+    }
+    return plan
+  }
+
+  private async clear(field: string): Promise<boolean> {
+    await this.scope.unset(field)
+    return !this.stored(field)
+  }
+
+  private async store(field: string, value: unknown): Promise<boolean> {
+    await this.scope.set(field, value)
+    return this.userLayer()?.[field] === value
+      || (Array.isArray(value) && JSON.stringify(this.userLayer()?.[field]) === JSON.stringify(value))
+  }
+
+  private stage(field: string, edit: StagedEdit): void {
+    this.staged.set(field, edit)
+    this.failed = false
+    this.publish()
+  }
+
+  private spec(field: string): CardFieldSpec {
+    const spec = this.specs.get(field)
+    if (spec === undefined) throw new Error(`im-bridge card has no field ${field}`)
+    return spec
+  }
+
+  private snapshotOf(): SettingsScopeSnapshot<T> {
+    return this.scope.getSnapshot()
+  }
+
+  private sectionValue(field: string): unknown {
+    return (this.snapshotOf().value as Record<string, unknown> | undefined)?.[field]
+  }
+
+  private baseValue(field: string): unknown {
+    return (this.snapshotOf().base as Record<string, unknown> | undefined)?.[field]
+  }
+
+  private userLayer(): Record<string, unknown> | undefined {
+    return this.snapshotOf().user as Record<string, unknown> | undefined
+  }
+
+  private stored(field: string): boolean {
+    const user = this.userLayer()
+    return user !== undefined && Object.hasOwn(user, field)
+  }
+
+  private publish(): void {
+    for (const listener of this.listeners) listener()
+  }
+}

package/src/client/css-modules.d.ts

@@ -0,0 +1,4 @@
+declare module '*.module.css' {
+  const classes: { readonly [key: string]: string }
+  export default classes
+}

package/src/client/fields.module.css

@@ -0,0 +1,124 @@
+/* Plugin configuration fields: label, control, override badge, and hint. */
+
+.field {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 12px 0;
+}
+
+.field + .field {
+  border-top: 1px solid var(--dsw-alias-border-l2);
+}
+
+.head {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.label {
+  flex: 1;
+  min-width: 0;
+  font-size: 13px;
+  font-weight: 500;
+  line-height: 1.5;
+  color: var(--dsw-alias-label-primary);
+}
+
+.badges {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.badge {
+  border-radius: 999px;
+  padding: 1px 8px;
+  font-size: 11px;
+  line-height: 17px;
+  white-space: nowrap;
+  font-weight: 500;
+  background: var(--dsw-alias-bg-module-platform);
+  color: var(--dsw-alias-label-secondary);
+}
+
+.badgeMuted {
+  border-radius: 999px;
+  padding: 1px 8px;
+  font-size: 11px;
+  line-height: 17px;
+  white-space: nowrap;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+.reset {
+  border: none;
+  background: none;
+  padding: 0;
+  font: inherit;
+  font-size: 12px;
+  line-height: 1.5;
+  color: var(--dsw-alias-label-secondary);
+  cursor: pointer;
+}
+
+.reset:hover:not(:disabled) {
+  color: var(--dsw-alias-label-primary);
+}
+
+.reset:disabled {
+  cursor: default;
+}
+
+.input {
+  height: 34px;
+  padding: 0 12px;
+  border: 1px solid var(--dsw-alias-border-l2);
+  border-radius: 8px;
+  background: var(--dsw-alias-bg-layer-3);
+  font: inherit;
+  font-size: 13px;
+  line-height: 1.5;
+  color: var(--dsw-alias-label-primary);
+}
+
+.input:focus-visible {
+  outline: none;
+  border-color: var(--dsw-alias-brand-primary);
+}
+
+.input:disabled {
+  color: var(--dsw-alias-label-tertiary);
+  cursor: default;
+}
+
+.inputInvalid {
+  height: 34px;
+  padding: 0 12px;
+  border: 1px solid var(--dsw-alias-label-error);
+  border-radius: 8px;
+  background: var(--dsw-alias-bg-layer-3);
+  font: inherit;
+  font-size: 13px;
+  line-height: 1.5;
+  color: var(--dsw-alias-label-primary);
+}
+
+.inputInvalid:focus-visible {
+  outline: none;
+}
+
+.invalid {
+  margin: 0;
+  font-size: 12px;
+  line-height: 1.5;
+  color: var(--dsw-alias-label-error);
+}
+
+.hint {
+  margin: 0;
+  font-size: 12px;
+  line-height: 1.5;
+  color: var(--dsw-alias-label-tertiary);
+}

package/src/client/fields.tsx

@@ -0,0 +1,112 @@
+/** Staged value and write-only secret controls. */
+
+import type { ReactElement } from 'react'
+import css from './fields.module.css'
+
+/** Shared props for a labelled field control. */
+export interface FieldProps {
+  /** Stable id associating the label with its control. */
+  id: string
+  /** Visible label. */
+  label: string
+  /** One-line explanation under the control. */
+  hint: string
+  /** Draft text the control renders. */
+  text: string
+  /** Whether saving would leave a user-layer entry. */
+  overridden: boolean
+  /** Whether the draft is not a value this field accepts. */
+  invalid: boolean
+  /** Copy for the overridden badge. */
+  overriddenLabel: string
+  /** Copy for the reset control. */
+  resetLabel: string
+  /** Copy shown in place of the hint while the draft is invalid. */
+  invalidLabel: string
+  /** Disables every control. */
+  disabled: boolean
+  /** Stage draft text. */
+  onEdit: (text: string) => void
+  /** Stage a clear so the field re-inherits the composition layer. */
+  onReset: () => void
+}
+
+/**
+ * A staged value field.
+ * @param props - the field's copy, staged text, and edit actions.
+ * @returns the labelled control.
+ */
+export function ValueField(props: FieldProps & {
+  /** Hints a numeric keypad without narrowing accepted drafts. */
+  numeric?: boolean
+}): ReactElement {
+  return (
+    <div className={css.field}>
+      <div className={css.head}>
+        <label className={css.label} htmlFor={props.id}>{props.label}</label>
+        {props.overridden
+          ? (
+            <span className={css.badges}>
+              <span className={css.badge}>{props.overriddenLabel}</span>
+              <button
+                type="button"
+                className={css.reset}
+                disabled={props.disabled}
+                onClick={props.onReset}
+              >
+                {props.resetLabel}
+              </button>
+            </span>
+          )
+          : null}
+      </div>
+      <input
+        id={props.id}
+        className={props.invalid ? css.inputInvalid : css.input}
+        type="text"
+        {...props.numeric === true ? { inputMode: 'numeric' as const } : {}}
+        {...props.invalid ? { 'aria-invalid': true } : {}}
+        value={props.text}
+        disabled={props.disabled}
+        onChange={(event) => { props.onEdit(event.target.value) }}
+      />
+      <p className={props.invalid ? css.invalid : css.hint}>
+        {props.invalid ? props.invalidLabel : props.hint}
+      </p>
+    </div>
+  )
+}
+
+/**
+ * Write-only credential control. The literal never rides a response, so the
+ * control starts blank and reports only whether one is configured.
+ * @param props - the field's copy, staged text, and configured state.
+ * @returns the labelled control.
+ */
+export function SecretField(props: Pick<FieldProps, 'id' | 'label' | 'hint' | 'text' | 'disabled' | 'onEdit'> & {
+  /** Whether the Host reports a configured value for this secret slot. */
+  configured: boolean
+  /** Copy describing the configured state. */
+  stateLabel: string
+}): ReactElement {
+  return (
+    <div className={css.field}>
+      <div className={css.head}>
+        <label className={css.label} htmlFor={props.id}>{props.label}</label>
+        <span className={css.badges}>
+          <span className={props.configured ? css.badge : css.badgeMuted}>{props.stateLabel}</span>
+        </span>
+      </div>
+      <input
+        id={props.id}
+        className={css.input}
+        type="password"
+        autoComplete="off"
+        value={props.text}
+        disabled={props.disabled}
+        onChange={(event) => { props.onEdit(event.target.value) }}
+      />
+      <p className={css.hint}>{props.hint}</p>
+    </div>
+  )
+}

package/src/client/index.ts

@@ -0,0 +1,37 @@
+/**
+ * Browser half: Settings card keyed by the `im-bridge` namespace.
+ */
+
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+// Type-only: ctx.settingsScope.describe and the keyed slot declaration.
+import type {} from '@deepseek-ai/dsh-client-ui-settings/client'
+import type {} from '@deepseek-ai/dsh-client-ui-settings-plugins/client'
+import { WecomCard } from './WecomCard.tsx'
+import { WecomCardController } from './card-controller.ts'
+import { en, zh } from './locales.ts'
+
+/** Settings namespace shared with the Host half. */
+const NS = 'im-bridge'
+
+/** Required browser services. */
+export const inject = ['slots', 'locale', 'connection', 'remote', 'settingsScope']
+
+/**
+ * Register locale copy and the Plugins-tab card.
+ * @param ctx - browser plugin context.
+ */
+export function apply(ctx: ClientContext): void {
+  const card = new WecomCardController(
+    ctx.settingsScope.bind({ namespace: NS }),
+    ctx.settingsScope.describe(),
+  )
+
+  ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'im-bridge: locale dicts')
+
+  ctx.slots.inject('settings.plugin.item', () => ctx.slots.register({
+    name: 'settings.plugin.item',
+    key: NS,
+    locale: NS,
+    inject: () => card.inject(),
+  }, WecomCard))
+}

package/src/client/locales.ts

@@ -0,0 +1,112 @@
+/** Dictionary keys owned by the im-bridge settings card. */
+export type ImBridgeLocaleKey =
+  | 'title'
+  | 'description'
+  | 'unsaved'
+  | 'readOnly'
+  | 'saveFailed'
+  | 'save'
+  | 'saving'
+  | 'discard'
+  | 'expand'
+  | 'collapse'
+  | 'overridden'
+  | 'reset'
+  | 'invalidNumber'
+  | 'botId'
+  | 'secret'
+  | 'secretHint'
+  | 'secretConfigured'
+  | 'secretUnset'
+  | 'allowFrom'
+  | 'allowFromHint'
+  | 'agentTimeoutSec'
+  | 'agentTimeoutSecHint'
+  | 'startHint'
+  | 'startHintHint'
+  | 'deniedMessage'
+  | 'deniedMessageHint'
+  | 'welcomeMessage'
+  | 'welcomeMessageHint'
+  | 'provider'
+  | 'providerHint'
+  | 'model'
+  | 'modelHint'
+
+/** English copy for the im-bridge card. */
+export const en: Record<ImBridgeLocaleKey, string> = {
+  title: 'WeCom Bridge',
+  description: 'Credentials, allow-list, timeouts, and WeCom-only model overrides.',
+  unsaved: 'Unsaved',
+  readOnly: 'This document is read-only.',
+  saveFailed: 'Save did not land. Correct the fields and try again.',
+  save: 'Save',
+  saving: 'Saving…',
+  discard: 'Discard',
+  expand: 'Show settings',
+  collapse: 'Hide settings',
+  overridden: 'Overridden',
+  reset: 'Reset',
+  invalidNumber: 'Enter a finite number.',
+  botId: 'Bot ID',
+  secret: 'Secret',
+  secretHint: 'Leave blank to keep the stored value. Save, then restart the process to open the WebSocket.',
+  secretConfigured: 'Configured',
+  secretUnset: 'Not configured',
+  allowFrom: 'Allowed sender userids',
+  allowFromHint: 'Comma-separated. Empty allows everyone.',
+  agentTimeoutSec: 'Task timeout (seconds)',
+  agentTimeoutSecHint: 'Progress bar and remaining-time estimate.',
+  startHint: 'Placeholder while thinking',
+  startHintHint: 'First stream line after a message arrives.',
+  deniedMessage: 'Denied-sender reply',
+  deniedMessageHint: 'Sent when the userid is outside the allow-list.',
+  welcomeMessage: 'Welcome message',
+  welcomeMessageHint: 'Sent when a user opens the WeCom chat.',
+  provider: 'WeCom-only provider',
+  providerHint: 'Empty follows the GUI default model. Both provider and model must be set to override.',
+  model: 'WeCom-only model',
+  modelHint: 'Takes effect only together with provider.',
+}
+
+/** Chinese copy for the im-bridge card. */
+export const zh: Record<ImBridgeLocaleKey, string> = {
+  title: '企业微信桥接',
+  description: '凭证、白名单、超时和企微专用模型覆盖。',
+  unsaved: '未保存',
+  readOnly: '当前文档不可写。',
+  saveFailed: '保存未生效，请修正后重试。',
+  save: '保存',
+  saving: '保存中…',
+  discard: '放弃',
+  expand: '展开设置',
+  collapse: '收起设置',
+  overridden: '已覆盖',
+  reset: '重置',
+  invalidNumber: '请输入有效数字。',
+  botId: 'Bot ID',
+  secret: 'Secret',
+  secretHint: '留空保留已存值。保存后需重启进程才会连 WebSocket。',
+  secretConfigured: '已配置',
+  secretUnset: '未配置',
+  allowFrom: '允许的发送者 userid',
+  allowFromHint: '逗号分隔；空 = 允许所有人。',
+  agentTimeoutSec: '单任务超时（秒）',
+  agentTimeoutSecHint: '动画进度条和剩余估算的基准。',
+  startHint: '开始处理时的占位提示',
+  startHintHint: '收到消息后推送的第一条流式文案。',
+  deniedMessage: '非白名单拒绝文案',
+  deniedMessageHint: '发送者不在白名单时回复。',
+  welcomeMessage: '进入会话欢迎语',
+  welcomeMessageHint: '用户打开企微会话时发送。',
+  provider: '企微专用 provider',
+  providerHint: '空 = 跟随 GUI 默认模型。须与 model 同时填写才覆盖。',
+  model: '企微专用 model',
+  modelHint: '仅在同时填写 provider 时生效。',
+}
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface LocaleNamespaceMap {
+    'im-bridge': ImBridgeLocaleKey
+  }
+}