DSH 高级设置（Settings Plus）

English · 中文

██████╗  ███████╗ ██╗  ██╗
██╔══██╗ ██╔════╝ ██║  ██║
██║  ██║ ███████╗ ███████║
██║  ██║ ╚════██║ ██╔══██║
██████╔╝ ███████║ ██║  ██║
╚═════╝  ╚══════╝ ╚═╝  ╚═╝

┌─────────────────────────────────────────────────────────────┐
│  dsh-settings-plus                                          │
│  DeepSeek Harness 官方设置的 plus                           │
│  表单级 + 文件级配置管理                                    │
│  + 面向所有插件的开放注册 SDK                               │
│                                                             │
│  175 个测试 | MIT | TypeScript ESM | Cordis v4              │
└─────────────────────────────────────────────────────────────┘

dsh-settings-plus 是 DeepSeek Harness 官方设置的 plus。官方入口是单个设置表单；本插件提供的是设置管理面：所有已注册的 settings namespace 与所有已挂载插件的组合配置，既可以表单方式浏览编辑，也可以文件方式浏览编辑。任何插件都能通过薄 SDK 注册自己的设置 namespace。

本仓库是自包含的独立 ESM Cordis 插件仓库。DSH 宿主是成品包的运行时消费者，不是源码或构建输入。

已发布至 dsh-plugin topic，PR 进入 awesome-DSH-plugin，dsh-market 跟随。

架构

flowchart LR
    subgraph HOST["DSH 宿主（运行时）"]
        REG["cordis registry：settings namespace + 组合行"]
        GW["gateway：exposed-namespaces 白名单"]
        FS["ctx.fs 形态通道"]
    end

    subgraph PLUS["dsh-settings-plus（本仓库）"]
        C1["C1 宿主爬取"]
        C2["C2 表单级编辑（浏览器半）"]
        C3["C3 文件级编辑"]
        C4["C4 插件 SDK"]
        CLIENT["lib/client.js"]
    end

    C4 -->|注册用户 namespace| C1
    C1 -->|枚举，secret 脱敏| REG
    C1 -->|经 settings seam + 版本守卫写入| REG
    C1 -.->|Fabric 加宽，可选| GW
    C3 -->|原子读写 + expected-version 守卫| FS
    C2 -->|打包为| CLIENT
    C2 -->|经 catalog source seam 读取，wire 待落地| C1

四大能力

🔭 C1 · 宿主爬取

（src/crawler.ts、src/service.ts、src/fabric.ts）

只读 crawler 枚举所有已注册的 settings namespace（ctx.settings.describe + secret 脱敏）与所有已挂载插件的组合配置（schemastery Config + 行 id，来自 cordis 运行时 registry）。bundle 以 ctx.dshSettingsPlus 宿主服务发布：listNamespaces、listCompositionConfigs、updateComposition、removeComposition。写操作经宿主 settings seam + 乐观并发版本守卫。普通 cordis.yml 组合行不可经服务写入（请用文件编辑面或 cordis.patch.yml）。Fabric 绑定在加载时加宽 gateway 的 exposed-namespaces 白名单：可选挂载，缺失时安全 no-op。

🎛️ C2 · 表单级编辑

（src/client/）

浏览器半注册 settings.section 贡献：始终存在的高级设置入口（order 30）、catalog 无数据时的 loading/empty/error 三态状态行、每 catalog 条目一个分区，按签名差分（${key}\u0000${label}）reconcile。通用 schema 表单渲染器（src/client/schema-form.tsx）渲染白名单控件：string/number/boolean 原生、const-only union 下拉、嵌套对象分组、其余 JSON textarea 兜底。secret 占位协议保证占位永不回传、留空保持原值、显式输入才提交。逐字段 reset 用 unset 操作，绝不写值。revision 冲突给出重载提示，restart 提示说明宿主何时需要重启。渲染器已完整实现并通过测试；接入数据分区随宿主 wire 面落地（见"已知限制"）。

🗂️ C3 · 文件级编辑

（src/file-browser.ts、src/file-store.ts、src/yaml-editor.ts、src/patch-validator.ts、src/hmr-aware.ts）

封闭配置清单（可写的 $DSH_HOME 根 YAML 文件 + 每 profile 的 cordis*.yml，bundle 层只读展示）经 realpath 越界校验。读写经注入的 ctx.fs 形态通道原子进行，带字节上限与 expected-version 写守卫。YAML round-trip 保留注释。语义校验拒绝会破坏文档的补丁编辑。HMR 说明诚实：插件不拥有 watcher，宿主已热重载 cordis.patch.yml 与 settings.yaml，保存策略只保证原子写。

🧩 C4 · 开放注册 SDK

（src/sdk.ts、[docs/sdk-contract.md](docs/sdk-contract.md)）

其他插件通过 registerUserSettings（实注册 + 显式移除 disposer）、defineSettingsSection（声明式，无副作用）、settingsNamespace（命名品牌，^[a-z][a-z0-9-]*$）在宿主上注册自己的 settings namespace。注册随调用方 fiber 回收，secret 语义归宿主 seam，重复注册在宿主响亮报错。

官方设置 vs dsh-settings-plus

领域	官方设置入口	dsh-settings-plus
编辑形态	单个设置表单	表单级编辑，外加文件级编辑面
可浏览范围	宿主设置表单	所有已注册 settings namespace 与所有已挂载插件的组合配置，secret 脱敏
文件写入	不在范围内	封闭可写清单，原子写 + 版本守卫
插件自定义设置	仅宿主管理	任何插件经 SDK 注册自己的 namespace

来自真实 DSH profile 的实机截图——左为官方设置入口，右为 SDK 注册 namespace 渲染出的插件设置页：

设计原则

默认只读。 crawler 从不写入；文件浏览器只枚举与校验。
secret 归宿主 seam。 占位永不回传，脱敏在 schema 遍历中完成。
写入有守卫。 每条写路径都有 expected-version 守卫、字节上限与 realpath 越界校验。
不自建 watcher。 插件从不擅自重启你，只如实说明宿主已经热重载什么。
响亮失败，安全降级。 畸形 Fabric facade 响亮报错；缺失 facade 是安全 no-op。

快速开始

1. 安装 到 DSH profile（对本仓库做 file: 安装）：

dsh plugin --profile <name> add file:/<repo-dir>/dsh-settings-plus

2. 启动 profile。 包 manifest 声明 dsh.bundle.patch（cordis.patch.yml），在所选 profile 的运行时上组合三行：dsh-settings-plus、dsh-settings-plus-invariant companion、以及一个禁用状态的 cordis-fabric 桩（加载时加宽 gateway 的 exposed-namespaces 白名单，运行时绑定在 src/fabric.ts）。补丁只组合插件；不改宿主源码、编译器设置或构建脚本。profile 的 node_modules 提供裸名 peer 依赖。

3. 打开设置导航。 高级设置入口出现，带 loading/empty/error 三态状态行。每条目数据分区随宿主 wire 面落地后渲染（见"已知限制"）。

插件作者的 SDK 用法

在插件 apply 内注册一个 namespace，随调用方 fiber 回收：

import { Context } from 'cordis'
import z from 'schemastery'
import { registerUserSettings } from '@oneinitai/dsh-settings-plus/sdk'

export const name = 'my-plugin'
export const inject = ['settings']

const MySection = z.object({
  host: z.string().default('localhost'),
  token: z.string().role('secret'),
})

export function apply(ctx: Context) {
  ctx.effect(() => registerUserSettings(ctx, 'my-plugin', MySection, { applies: 'live' }))
}

注册后 namespace 立即进入宿主设置面：crawler 的 ctx.dshSettingsPlus.listNamespaces() 会包含它，配置 UI 自动渲染其 schema。完整契约（命名、secret、生命周期、去重语义）见 [docs/sdk-contract.md](docs/sdk-contract.md)。

浏览器半

src/client/ 是 Web bundle，以 lib/client.js 提供（exports map ./client）。它注册 settings.section 贡献与 dsh-settings-plus locale namespace（[src/client/locales.ts](src/client/locales.ts) 中 zh/en 双字典；中文是产品文案，英文镜像，en satisfies Record<keyof typeof zh, string> 保证对齐）。catalog 通过可注入的 settingsPlusCatalog source seam 读取。生产默认是诚实的本地空源（宿主 wire 面落地前），因此设置导航显示状态行的 empty 阶段，尚无数据分区。

已知限制

如实陈述：

defer 到 v2（计划约定）：聚合配置页、per-namespace 拒绝名单、导出/导入、required secret 保存修复。
宿主 wire 面处于诚实降级状态：T16 分发冒烟验证了插件安装/加载与服务挂载；宿主 wire 面（浏览器 catalog 数据通道、真实 ctx.fs 适配器、Fabric patch 端到端）待宿主升级后补验证。当前为诚实降级状态：catalog 空源、Fabric no-op、文件写走本地 FsLike 通道。
Fabric 依赖姿态：cordis-fabric 在绑定时从宿主上下文可选加载。未挂载 facade → 安全 no-op（桩行保持禁用，gateway 保持默认白名单）；facade 挂载但畸形 → 响亮报错。
updateComposition 的写范围：只有已注册 settings namespace 的 id 可经服务写入；普通 cordis.yml 组合行响亮失败，须经文件编辑面或 cordis.patch.yml 修改。

后续计划（Roadmap）

L2 浏览器 RPC 接入：把客户端 catalog 从空本地源接到真实宿主数据通道。
L3 外部 HTTP API：按需将 settings 服务暴露为外部 HTTP 接口。
宿主版本兼容范围锁定：维持宿主版本范围锁定（见 peerDependencies），宿主升级后补验证 wire 面。

独立开发

所有命令都在本目录运行：

pnpm install
pnpm run verify:self-contained
pnpm run typecheck
pnpm test
pnpm run build
pnpm run prepare

verify:self-contained 拒绝文件系统依赖 spec、离开仓库的编译器路径、外部或损坏的 Markdown 链接、绝对工作站路径和格式错误的 bundle skill 元数据。typecheck 同时检查声明工程与源码平面测试。build 是开发/CI 类型安全门禁；prepare 产出消费者侧产物（含 lib/），供 Git 与 tarball 安装。

仓库布局

.
├── .agents/skills/               # 仓库本地插件开发工作流
├── docs/
│   ├── dsh-plugin-contracts.md   # 所有插件 skill 共享的本地契约
│   └── sdk-contract.md           # 注册 SDK 契约（C4）
├── patches/                      # 依赖补丁与 DSH host patch 契约
├── scripts/                      # prepare、verify-self-contained、补丁辅助
├── src/
│   ├── index.ts                  # Loader 面向的函数插件命名空间
│   ├── config.ts                 # 可序列化 schema 与解析后的默认值
│   ├── runtime.ts                # Cordis 激活与宿主边界接线
│   ├── invariant.ts              # 包自有的 invariant companion
│   ├── crawler.ts                # 只读设置/组合枚举（C1）
│   ├── service.ts                # ctx.dshSettingsPlus 服务面（C1）
│   ├── fabric.ts                 # 可选 gateway 白名单加宽（C1）
│   ├── sdk.ts                    # 开放注册 SDK（C4）
│   ├── file-browser.ts           # 封闭配置清单 + 越界校验（C3）
│   ├── file-store.ts             # 原子读写 + 版本守卫（C3）
│   ├── yaml-editor.ts            # 保留注释的 YAML round-trip（C3）
│   ├── patch-validator.ts        # 语义补丁校验 + 自保护（C3）
│   ├── hmr-aware.ts              # 保存的 HMR 说明（C3）
│   └── client/                   # 浏览器半，以 lib/client.js 提供（C2）
│       ├── index.ts              # settings.section 注册 + 状态行
│       ├── catalog.ts            # 可观察 catalog store + 可注入 source seam
│       ├── component.tsx         # 入口 / 状态行 / 数据分区组件
│       ├── schema-form.tsx       # 通用 schema 表单渲染器
│       ├── form-logic.ts         # 表单逻辑 + secret/reset/冲突协议
│       └── locales.ts            # zh/en locale 字典
├── tests/                        # 宿主 spec（node）与客户端 spec（jsdom）
├── AGENTS.md                     # 仓库本地贡献契约
├── LICENSE                       # MIT
├── README.md / README.zh.md      # 仓库与使用契约
├── cordis.patch.yml              # profile bundle 贡献
└── package.json                  # 导出、peers、dsh.bundle.patch