前言¶

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 仓库