前言¶

DeepSeek Harness 的生態以插件爲中心。開發者在編寫插件時，往往需要自行處理設置頁面的表單渲染、存儲邏輯、路由註冊以及安全校驗。重複造輪子不僅耗時，還容易引入安全漏洞。dsh-config-form 提供了一個統一的設置頁面容器，插件只需聲明字段，即可獲得渲染好的表單和路由。

插件簡介¶

這是一個路由器和渲染器，而非框架。它爲所有主動接入的 DeepSeek Harness 插件提供統一的設置入口。維護者爲 begonia599。通過聲明式配置，插件可以快速獲取一個完整的配置表單，同時共享路由與安全檢查機制。

核心功能¶

• 聲明式字段路由與渲染：插件通過聲明定義表單結構，由該插件負責路由和渲染。
• 共享路由與安全檢查：提供統一的 HTTP 路由和入口，集中處理安全校驗。
• 密鑰隔離處理：敏感信息（如 Token）通過 ctx.credentials 獲取，不會出現在設置文檔中。
• 分層解析與版本圍欄：支持配置值的分層解析，並通過版本圍欄防止併發寫入衝突。
• HTTP API 支持：提供列表、詳情、寫入及密鑰管理的 HTTP 接口。

安裝與啓用¶

使用官方安裝命令即可完成安裝：

dsh plugin --profile web add dsh-config-form

典型用法¶

插件開發者需要引入 configForm 依賴，並聲明字段結構。以下是標準使用流程：

1. 聲明字段：在插件代碼中調用 ctx.configForm.declare 定義配置項。
2. 獲取配置：使用 cfg.get() 獲取解析後的配置值。
3. 監聽變更：通過 cfg.watch 監聽用戶保存操作，執行後續邏輯。
4. 處理密鑰：使用 await cfg.secret('token') 安全獲取敏感憑據。

代碼示例：

export const inject = ['configForm']

export function apply(ctx: Context) {
  const cfg = ctx.configForm.declare<Settings>(ctx, {
    id: 'my-plugin',
    title: { zh: '插件標題', en: 'Plugin Title' },
    groups: [
      {
        title: { zh: '常規', en: 'General' },
        fields: [
          { kind: 'text', key: 'settingKey', label: { zh: '設置項', en: 'Setting' }, default: 'value' }
        ]
      }
    ]
  })

  // 讀取配置
  cfg.get().settingKey

  // 監聽變更
  cfg.watch(next => {
    // 配置已保存
  })

  // 安全獲取密鑰
  await cfg.secret('token')
}

適用場景與注意¶

• 定位：它是一個路由器和渲染器，不是框架。
• 存儲：存儲邏輯由插件作者自行選擇。可以傳遞 store 對象，或者依賴設置縫線自動保存。
• 安全限制：密鑰不會出現在設置文檔中。安全檢查依賴於迴環地址、Host 頭和同源策略。寫入操作只能修改已聲明的值字段。
• 環境要求：安裝前請確認 Node.js 版本滿足 ^22.19.0 || >=24.0.0。

結語¶

通過這一插件，開發者可以專注於業務邏輯，而非重複的 UI 和安全代碼。詳細信息請查閱插件目錄或源碼倉庫。

• 插件目錄
• GitHub 倉庫