# 02 · 技术方案 — dsh-free-models-hub

> 依据 DSH 官方文档（developer preview，2026-08）：插件开发 basic 系列、publish、settings-card cookbook、client-modules / ui-sidebar 参考手册编写。

---

## 1. 总体架构

```
┌─────────────────────────────── 浏览器（DSH Web UI 页面） ───────────────────────────────┐
│  dsh-free-models-hub · client 半边（lib/client.cjs, 懒加载 CJS bundle）                   │
│  ├─ slots.inject('sidebar.workspaces') → 左侧「免费模型榜」面板                          │
│  ├─ 分页器 / 展开详情 / 复制 / toast                                                     │
│  ├─ fetch(站长后端 /api/models.php) ←── CORS 白名单                                      │
│  └─ 一键配置：ctx.settingsScope → llm-pi-ai.providers 写入；失败→YAML 引导弹窗            │
└──────────────────────────────────────────────────────────────────────────────────────┘
        │ GET JSON（只读、无密钥）                        ▲ settings 写入走本机 DSH Host
┌───────▼─────────────────────────┐
│ 站长后端 server-php/             │
│  api/models.php   公开分页 API   │   PHP 7.4 + PDO SQLite
│  admin/*          管理后台       │   （登录/CSRF/限速/预编译语句）
│  data/*.db        SQLite 库      │
└─────────────────────────────────┘
```

数据流要点：

1. **模型清单**：站长后台维护 → SQLite → 公开 API → 面板渲染。浏览器直连站长站点，需 CORS 放行 DSH 来源。
2. **配置写入**：不经过站长后端。Client 半边通过本机 DSH 的设置作用域直接写 `llm-pi-ai.providers`。
3. **API Key**：用户在 DSH 官方 设置 → 模型 里填写（write-only，存 `$DSH_HOME/.credentials.yaml`）。本插件任何一端都不出现 Key。

---

## 2. 插件包结构（仓库根 = 包根）

> `dsh plugin add github:<owner>/<repo>` 从仓库根读取 `package.json`，因此包必须在根目录。

```
/                          # = npm 包根
├── package.json           # dsh.bundle + dsh.client 声明；files 只发布 lib/
├── cordis.patch.yml       # bundle 补丁层：insert 插件行
├── src/index.js           # Host 半边入口（Node, ESM）
├── src/client/index.js    # Client 半边源码（零依赖单文件）
├── lib/index.js           # 预构建产物（随仓库提交，免 allowBuilds）
├── lib/client.cjs          # 懒加载 CJS 工厂格式 bundle
├── test/                  # node:test 单测
├── scripts/build.mjs      # 构建（生成 lib/）
├── docs/                  # 本文档集
├── server-php/            # 配套 PHP 后端（独立部署到站长网站）
└── .github/workflows/ci.yml
```

### 2.1 package.json 关键字段

```jsonc
{
  "name": "dsh-free-models-hub",
  "version": "0.1.0",
  "type": "module",
  "main": "lib/index.js",
  "exports": {
    ".": "./lib/index.js",
    "./client": "./lib/client.cjs"
  },
  "files": ["lib", "cordis.patch.yml", "README.md"],
  "dsh": {
    "bundle": { "patch": "./cordis.patch.yml" },
    "client": { "platform": "web" }
  }
}
```

- `dsh.bundle.patch` 缺失时包会"装了但不激活"（官方文档明确警告），此字段为激活开关。
- `dsh.client.platform: 'web'` 让 client-modules 扫描器把 `lib/client.cjs` 挂进 `window.__DSH_BOOT__` 图谱并经 `/plugins/<id>/client.js` 下发。

### 2.2 cordis.patch.yml

```yaml
- insert:
    - id: free-models-hub
      name: dsh-free-models-hub     # 引用包名，Node 解析找到 lib/index.js
      config:
        backendUrl: ''
        pageSize: 10
        requestTimeoutMs: 10000
        uiSlot: sidebar.workspaces
        providerIdPrefix: freehub
        footerLinks:
          - label: 技术笔记
            url: http://blog.4wc.cn
          - label: 插件开发
            url: https://blog.gd7.cn/
          - label: 联系站长
            url: http://web.wuyiyun.cn/
```

一个 Loader 行同时驱动 Node 半边与 client 扫描（扫描按"启用的 Loader 条目里声明了 dsh.client 的包"进行）。

---

## 3. Host 半边（src/index.js）

职责（刻意保持薄，兼容性优先）：

1. **配置规范化**：不导出 Config schema（避免硬依赖 schemastery 的版本矩阵），在 apply 内做白名单校验 + 默认值回填，非法值 fail-loud 打印可操作错误。
2. **设置分区注册（可选增强）**：动态 `import('@deepseek-ai/dsh-settings')` 尝试 `installSettingsSection(ctx, NS, …)`，把 backendUrl 等暴露到设置页「插件配置」页签；import 失败静默跳过（老版本仍可用，仅少设置卡片）。
3. **日志**：统一 `[free-models-hub]` 前缀，级别受 `debug` 配置控制。
4. **可逆性**：所有副作用走 ctx 注册/effect，卸载自动清理。

依赖策略：`dependencies: {}`（零运行时依赖）。对宿主服务一律 feature-detect + try/catch，杜绝因内部 API 漂移导致 fiber FAIL。

## 4. Client 半边（src/client → lib/client.cjs）

### 4.1 形态

- 导出 `{ name, inject, apply }`；构建为懒加载 CJS 工厂文本（`module.exports = …`），匹配 `/plugins/<id>/client.js` 的消费方式。
- `inject = ['slots']`；其余能力（settingsScope 等）运行时探测 `ctx.settingsScope`，避免声明式注入在不提供该服务的 profile 上直接失败。

### 4.2 UI 组件（纯 DOM，零框架）

| 组件 | 说明 |
|---|---|
| Panel | 标题行 + 列表容器 + 分页器 + 底部菜单；class 前缀 `fmh-`，样式经 `<style>` 注入并在 dispose 时移除 |
| ListRow | 序号 + 标题；点击切换展开态（aria-expanded） |
| DetailCard | baseURL/modelName（点击复制）、申请密钥按钮（`target=_blank rel="noopener noreferrer"`）、一键配置按钮 |
| Pager | 首页/上一页/窗口页码/省略号/下一页/末页 + 统计文案 |
| Toast | 3.5s 自动消失，成功/错误两态 |
| FallbackDialog | 一键配置失败时的 YAML 引导弹窗（含复制按钮） |

状态机：`idle → loading → ready | error(重试)`；请求超时/非 200/JSON 解析失败都落到 error 态并提供手动重试。

### 4.3 Slot 注入与降级

```js
const SLOT_CANDIDATES = [config.uiSlot /* 默认 'sidebar.workspaces' */]
```

- 主路径：`ctx.slots.inject(slotName, register)`。若 slot 名不存在或抛错（DSH 版本漂移），进入降级路径。
- 降级路径：向 `document.body` 注入左侧悬浮启动钮 + 抽屉式面板（自持 DOM，dispose 时整体移除）。保证"任何版本都能看到功能"。
- 该决策源于官方文档"developer preview 迭代快、UI 可能破坏性变更"的明示；slot 名做成配置项便于社区快速适配。

### 4.4 数据获取

- `GET {backendUrl}/api/models.php?page=N&page_size=10`，`AbortController` 超时。
- 校验响应 schema（ok/items/total…），防御性渲染：字段缺失显示占位而非崩溃；URL 字段仅接受 `http(s):` 协议，其余一律置灰不可点。

### 4.5 一键配置实现

```js
const pid = `${prefix}-${slug(title)}`            // slug: 小写字母数字与连字符, ≤40
const entry = {
  apiKeyEnv: `${PID_SNAKE}_API_KEY`,              // 允许环境变量供 Key（可选路径）
  api: 'openai-completions',
  baseURL: item.api_base_url,
  compat: { supportsDeveloperRole: false, maxTokensField: 'max_tokens' },
  models: [{ id: item.model_name }],
}
```

写入流程（每步 try/catch，收集诊断）：

1. `const scope = ctx.settingsScope?.bind?.({ namespace: 'llm-pi-ai' })`
2. 读快照 `scope.value?.providers ?? scope.user?.providers ?? {}`
3. 合并后 `await scope.set('providers', merged)`
4. 回读校验成功 → toast 成功；任一步异常 → FallbackDialog（YAML 片段一键复制 + 打开设置指引）。

> Provider ID一经使用不可改名（官方约束），slug 生成必须稳定幂等——同标题重复点击产生同一 ID 并覆盖更新，属预期行为。

---

## 5. 站长后端设计（PHP 7.4 + SQLite）

### 5.0 路由与隐匿（对用户零暴露）

后端是**单入口前置控制器**（`index.php`），全站只对外暴露干净 URL，访客无法感知 PHP/SQLite 技术栈：

| 干净 URL | 内容 |
|---|---|
| `/` | 公开「免费模型榜」榜单页（服务端渲染分页 + `<details>` 展开详情 + 申请密钥按钮 + 底部三菜单） |
| `/api/models` | 只读分页 JSON API（DSH 面板数据源） |
| `/admin` | 管理后台登录 |
| `/admin/models`、`/admin/settings`、`/admin/logout` | 后台各屏 |

隐匿措施：

1. Apache `.htaccess` 把除 `assets/` 外的一切请求重写给 FC；nginx 示例同理（`@front` 兜底）。
2. 对 `*.php` 的直连一律 **301 规范化到干净路由**；未知路径映射为通用 404 页。
3. `header_remove('X-Powered-By')` + `.htaccess php_flag expose_php Off`，响应无版本指纹。
4. 视图/动作文件带 `FMH_ROUTE` 守卫，即使被直接执行也返回 404 空白。
5. 共享文件全部 `require_once`，杜绝重复声明 fatal。
6. 部署前缀由 `DOCUMENT_ROOT ↔ 应用目录` 差值推导，域名根或子目录部署均稳定。

> 用户侧唯一需要知道的就是站长的**域名根**：插件面板里填 `https://your-domain.com`，
> 自动请求 `/api/models`。`.php`、数据库、后台路径对终端用户完全不可见。

### 5.1 数据模型

```sql
CREATE TABLE IF NOT EXISTS models (
  id            INTEGER PRIMARY KEY AUTOINCREMENT,
  title         TEXT    NOT NULL,              -- 标题信息
  api_base_url  TEXT    NOT NULL,              -- API 调用地址
  model_name    TEXT    NOT NULL,              -- 模型名称
  key_apply_url TEXT    NOT NULL,              -- 密钥申请链接（第三方注册页）
  sort          INTEGER NOT NULL DEFAULT 0,    -- 小者靠前
  enabled       INTEGER NOT NULL DEFAULT 1,
  created_at    TEXT    NOT NULL DEFAULT (datetime('now')),
  updated_at    TEXT    NOT NULL DEFAULT (datetime('now'))
);
CREATE TABLE IF NOT EXISTS settings (
  key   TEXT PRIMARY KEY,
  value TEXT NOT NULL
);                       -- site_title / cors_origins / admin_user / admin_pass(hash) / foot_*
CREATE TABLE IF NOT EXISTS login_throttle (
  ip TEXT PRIMARY KEY, fails INTEGER NOT NULL DEFAULT 0, last_try INTEGER NOT NULL DEFAULT 0
);
```

DB 文件落在 `data/`（随机文件名 + `.htaccess deny-all` + 无目录索引），Web 不可直达。

### 5.2 公开 API

`GET /api/models?page=1&page_size=10`（前端只需提供站点根，路径由面板自动拼接）

```jsonc
{
  "ok": true,
  "page": 1, "page_size": 10, "total": 87, "total_pages": 9,
  "items": [{
    "id": 12, "title": "GLM-5-Flash 免费额度",
    "api_base_url": "https://…/v1", "model_name": "glm-5-flash",
    "key_apply_url": "https://…/register",
    "updated_at": "2026-08-20 10:00:00"
  }]
}
```

- page_size 服务端钳制 `1..50`（默认 10）；page ≥1；`total_pages ≥ 1`。
- 仅输出 `enabled=1`，按 `sort ASC, id DESC`。
- CORS：`Origin` 命中后台白名单才回 `Access-Control-Allow-Origin`（精确回显，不用 `*`）；处理 OPTIONS 预检。
- `Cache-Control: no-store`；输出前禁掉 PHP 错误泄漏（display_errors 关 + 自定义兜底）。

### 5.3 管理后台

- `admin/index.php` 登录（POST 用户名+密码+CSRF）；`password_verify/hash` 存 bcrypt。
- 会话：`session.cookie_httponly=1`、`cookie_samesite=Lax`、登录成功 `session_regenerate_id(true)`。
- 登录限速：同 IP 连续失败 ≥5 次锁 10 分钟（login_throttle 表）。
- `admin/models.php` 列表/新建/编辑/删除/启停/排序（全部 POST + CSRF token 校验 + PDO 预编译）。
- `admin/settings.php` 站点标题、CORS 白名单（逐行域名）、底部菜单三项文案链接、改密码（需旧密码）。
- 所有输出经 `e()`（htmlspecialchars ENT_QUOTES UTF-8）；重定向头拼接收敛白名单。
- 首次访问自动建库建表并生成默认管理员（`admin` / 随机 12 位密码一次性展示，强制首次登录修改）。

### 5.4 兼容性约束

- 仅用 PHP 7.4 语法（箭头函数、null 合并可用；不用 8.x 特性）。
- 零 Composer 依赖；SQLite 经 PDO（`sqlite:`）。目录下放置 `index.html` 空文件防列目录。

---

## 6. 构建与分发

- `scripts/build.mjs`：零依赖 Node 脚本。① 把 `src/index.js` 原样落至 `lib/index.js`（ESM 直出）；② 将 `src/client/index.js` 包一层 CJS 工厂文本写 `lib/client.cjs`。产物随 git 提交 → GitHub 安装无需 prepare/allowBuilds（官方 publish 文档推荐路径之一）。
- 发版：CI 跑测试 → 手动 tag `vX.Y.Z` → GitHub Release 附 zip（`scripts/pack.ps1`）。
- 市场：topic `dsh-plugin` 收录；更新 = 用户在市场点更新（重新执行 add 至新 tag/main）。

## 7. 风险登记与缓解

| # | 风险 | 影响 | 缓解 |
|---|---|---|---|
| R1 | DSH 预览期 UI slot 名称变化 | 面板不出现 | slot 名可配置 + 自动降级为悬浮抽屉（§4.3） |
| R2 | settingsScope 内部 API 漂移 | 一键配置失败 | 逐步 try/catch + YAML 引导弹窗兜底（§4.5） |
| R3 | client bundle 加载格式与目标版本不符 | 面板不出现 | CJS 工厂为文档指认格式；降级路径同样生效；README 记录适配方法 |
| R4 | 第三方网关请求形态差异 | 配好后报错 | 默认写入 `compat.supportsDeveloperRole:false & maxTokensField:max_tokens`（官方排障首推两项） |
| R5 | 站长后端被刷/注入 | 数据面受损 | 预编译语句、CSRF、登录限速、deny-all 数据目录（见 05 文档威胁建模） |
| R6 | CORS 配错 | 面板拉不到数据 | 后台白名单精确回显 + 错误态给出自查清单 |

## 8. 明确的实现偏差记录（诚实工程）

1. 未导出 schemastery 版 `Config`（改为内建规范化）——换取跨版本零依赖；代价：patch 层需自带完整默认值（已内置在 cordis.patch.yml）。
2. v1 不采集用户 Key（包括面板输入框都不做）——Key 只走官方 write-only 凭据通道，安全面最小化。