前言¶

DeepSeek Harness (DSH) 生态强调“一切皆插件”。插件开发者常面临一个具体需求：需要在不同粒度上管理配置——例如，为当前会话指定模型，为整个工作区设置构建标志，或者为全局安装调整主题色。dsh-granular-settings 旨在解决这一问题，它作为一个共享平台，允许其他插件注册这些配置项。

这是什么¶

这是一个 DSH 插件，提供 Granular Settings 页面，包含 Workspace、Session 和 Plugin 三个选项卡。它支持作用域控制，并提供了 8 种控件类型（toggle, text, color, number, slider, enum, multiselect, path）。

核心功能¶

• 作用域与命名空间：支持 session（会话级）、workspace（工作区级）、global（全局级）三种作用域。所有设置通过插件包名进行命名空间隔离，防止键名冲突。
• 控件类型：提供 8 种控件类型，包括文本、数字滑块、颜色选择、枚举和多选等。
• 无会话支持：在没有打开会话时，Plugin 作用域依然可用；Global 作用域可以独立于会话工作。
• 调试接口：提供 /granular-settings/describe 和 /relay/events 端点用于调试。

安装¶

安装需要 DeepSeek Harness 的检出目录和配置文件（如 profile），并且必须先安装其硬依赖 dsh-event-relay。

mkdir -p ~/dsh-plugins && cd ~/dsh-plugins
git clone https://github.com/joao-paulo-santos/dsh-event-relay.git
git clone https://github.com/joao-paulo-santos/dsh-granular-settings.git

# from the harness checkout
pnpm dsh plugin --profile web add ~/dsh-plugins/dsh-event-relay
pnpm dsh plugin --profile web add ~/dsh-plugins/dsh-granular-settings

典型用法¶

Host side (注册控件)：
插件可以在 Host 端注册设置项，指定命名空间、作用域、类型以及默认值。

const gs = ctx.get('granularSettings')
const s = gs.register({
  namespace: 'my-plugin',
  scope: 'session',
  key: 'model',
  type: 'enum',
  label: 'Model',
  owner: 'My Plugin',
  description: 'Which model this session uses',
  options: [{ value: 'a', label: 'Model A' }],
  defaultValue: 'a',
  onChange: (value, target) => {}
})

Browser side (读取与订阅)：
在浏览器端，可以使用 useSetting 钩子来读取和设置值。

const gs = ctx.get('granularSettings')
const [model, setModel] = gs.useSetting('my-plugin', 'session', 'model')

注意事项¶

• 硬依赖：必须安装 dsh-event-relay。
• 环境要求：需要 DeepSeek Harness 的检出目录和配置文件。
• 许可证：MIT。