omdsh-dev/ex-setting

English | 中文

自动 DSH Web 设置组合包。它把宿主侧配置 crawler 和浏览器设置导航放在同一个外部包中：host 枚举已注册的 settings namespace 和带 schema 的 composition row，client 把它们投影为一级设置区段和编辑器。

仓库结构

package.json              # host/client 包以及 dsh.bundle/dsh.client 清单
cordis.patch.yml          # 挂载 crawler 的 profile 层
src/index.ts              # host crawler 插件（提供服务）
src/routes.ts             # crawler 自有的 webserver composition 路由
src/composition-contract.ts # host/client composition wire 类型
src/composition-ops.ts     # host 侧路径编辑应用
src/client/               # 浏览器设置页（store、section、crawler wire、nav scroll）
src/invariant.ts          # crawler invariant companion
lib/                      # 生成的 host/client 产物
docs/                     # host 和 client 协议详细说明
tests/host/               # crawler、route、export、invariant 与 loader 测试
tests/client/             # browser store、section 和 wire 测试
tests/client-bundles/     # 可复用的 closure-bundle 测试种子
tests/module-loader.ts    # module-table materialization harness
scripts/                  # 声明组装与构建产物契约检查
.agents/skills/           # dsh-plugin-* 贡献工作流

两个 runtime face 共享一个 package identity，因此 release/profile 安装只有一个 root 产物。浏览器 face 通过 @deepseek-ai/dsh-ex-setting/client 导出，并由 package 的 dsh.client 清单选择。纯 schema-form 路径操作会被内联进浏览器 closure，不再要求 profile 提供独立的动态 @deepseek-ai/dsh-client-schema-form row，因此也兼容由 settings UI 自己提供 schema service 的 profile。声明构建写入 lib/.client-dts 并在打包前删除；浏览器实际只加载 lib/client.js。

通过官方插件通道安装现成的 release 产物：

dsh plugin --profile web add https://github.com/omdsh-dev/ex-setting/releases/latest/download/pkg.tgz

profile 只需提供 DSH 宿主 peer；本包没有 Stent runtime 或宿主 bundle 重写依赖。浏览器 client 直接 安装导航 fallback，而 cordis.patch.yml 仍是用于挂载 crawler 行的 DSH bundle 层。

组合行为

安装组合包后加入 web-config-crawler 行，表示部署决定挂载 crawler、通过 Web 配置面暴露带 schema 的 composition row 并启用 composition editor。宿主 gateway 会独立提供已注册的 settings namespace。profile 可以关闭 crawler 行：

- id: web-config-crawler
  disabled: true

Crawler 会脱敏 secret，按路径应用并通过 schema resolve 编辑，持久化完整 row 到个人 overlay，并通过删除 row 恢复下层组合。浏览器页面保持 settings namespace 与 composition row 的来源区分，并提供 schema 字段、secret、reset、revision conflict、restart notice 和失效刷新。

外部零改动设计

本组合包零包外宿主改动，靠三个机制实现：

• 宿主提供 settings namespace — DSH gateway 会提供当前 composition 注册的所有 namespace。挂载本组合包只增加 crawler 和 composition editor，不会 transform 或替换 gateway 的暴露决策。
• crawler 自有的 composition 路由 — 浏览器侧通过 crawler 自己的 webserver 路由(/dsh-config/crawler/composition，src/routes.ts)读写 composition row，而不是 gateway RPC 域，因此写路径不向 apiproxy 或 connection 添加任何东西。
• 浏览器自有导航 fallback — 浏览器侧直接以 fiber-owned effect 安装语义化滚动规则，因此设置对话框不 依赖宿主 bundle transform；样式可幂等安装，并在插件 dispose 时移除。

Settings/composition wire 协议、API proxy handler、slot host 和 browser shell 由 profile 使用的 DSH 版本提供。

开发

宿主包(@deepseek-ai/dsh-*、@deepseek-ai/cordis)直接从 npm registry 安装：每个运行时 import 都以 ^0.1.0-rc.0 系列声明 peer + dev 双依赖，开发解析全部来自本仓库自己的 node_modules——不再需要 sibling checkout。devDependencies 同时列全了测试专用宿主树的 peer 闭包（apiproxy 组合测试会 import 真实网关）。

pnpm install
pnpm run typecheck
pnpm test
pnpm run build
pnpm pack --dry-run --json

release 产物在打包前从 src/ 构建。声明构建写入临时 ignored 目录，scripts/assemble-client-dts.mjs 只提升公开的 client 声明，最后的 runtime 构建独占写入 lib/client.js；scripts/verify-client-bundle.mjs 会拒绝 plain ESM、动态 import 和未允许的 module-table 请求。profile 安装消费现成的 lib/ 产物，不运行安装期 prepare hook。

CI

仓库自带一个 GitHub Actions 工作流：

• .github/workflows/release.yml — 每次推送到 main：使用冻结 lockfile 安装，运行类型检查、测试和构建（包括最终 client 产物 gate），打包现成 tarball 与 checksum；只有 package.json 发生变化时才创建 v<version> GitHub Release。非版本推送只做验证；已存在的 tag 会直接失败，不会覆盖。

模型体验

本组合包不添加模型可见的提示文本或工具。它只通过 loopback Web 设置面暴露配置；DSH settings、composition、session 与 permission 服务保留日志、脱敏和授权语义。

已知限制

• 原生 Zod composition Config 可以通过文件配置，但通用编辑器不会渲染；编辑器要求 schemastery toJSON()。
• Crawler 的范围有意较宽；不希望自动编辑 composition 的部署应禁用该行并保留 gateway allowlist 行为。