# 开发指南

> 中文文档 | [English](../en/DEVELOPMENT.md)

## 架构

```
host（零构建，node:crypto / node:http）
├── index.js          # Cordis 插件入口：gateway 生命周期、tapIndex 注入（randomUUID + authenticated LAN trust）、安全事件与登录审计接线、首次部署初始密码
├── lib/gateway.js    # 认证网关：HTTP/WS 拦截与转发、认证状态机、防爆破三层、防重放、basePath 路由/跳转/转发剥离、登录审计事件、静态资产免认证
├── lib/gateway-otp.js # OTP 路由 handler（/otp/setup|enable|verify-setup|verify|verify-backup|disable，自 gateway.js 拆分）
├── lib/forward.js    # HTTP/WS 转发管道（Host/Origin 回环改写、upgrade 双向管道、lanAddresses）
├── lib/upstream-auth.js # dsh ≥ 0.1.2 上游浏览器认证桥接（经 credentials 服务读密钥、为回环一跳铸同构 cookie；含 record 晚到快速重试/后台轮询与轮换重铸）
├── lib/auth.js       # 会话表与 Cookie：内存 256-bit token、onboarding/OTP 状态标记、改密吊销
├── lib/audit-log.js  # 审计日志文件 sink（JSONL，$DSH_HOME/auth-gateway/log/audit.log，按天轮转、保留 90 天）
├── lib/page-shell.js # 页面脚手架共享件（基础 CSS、HTML 骨架、script 头：ERRORS + post）
├── lib/errors.js     # 页面错误文案总字典（中英双语，errorsFor 按页选取 + 覆盖）
├── lib/locale.js     # 页面语言解析（dsh 偏好 > Accept-Language > zh）
├── lib/store.js      # 密码存储（scrypt 异步哈希，$DSH_HOME/auth-gateway/password.json）
├── lib/otp-store.js  # OTP 存储（secret + 备份码哈希 + lastCounter 水印）
├── lib/otp-crypto.js # OTP 密钥加解密（AES-256-GCM，主密钥来自环境变量或 key 文件）
├── lib/totp.js       # TOTP（RFC 6238/4226）：base32、生成/验证、防重放、otpauth URI、备份码
├── lib/qr-svg.js     # 零依赖 QR SVG 生成（Reed-Solomon、掩码评估）
├── lib/otp-page.js   # OTP 设置/验证页面（自包含 HTML）
├── lib/login-page.js # 登录/设置/改密页面
├── lib/onboarding-page.js # 引导页（设置个人密码 + 可选 OTP 绑定）
├── lib/policy.js     # 密码强度策略
├── lib/version.js    # 自身版本/仓库读取（package.json）+ SemVer 子集比较
├── lib/update-check.js # 新版本检查（唯一的对外请求，TTL 缓存 + 绝不抛错）
└── lib/config.js     # Standard Schema 配置校验（含 basePath 子路径前缀）

client（可选，源码构建）
├── client/src/index.jsx        # 面板容器：全部 state/handler、api 工厂、slot 注册（settings.section）
├── client/src/locales.js       # 中英文字典（自有命名空间）
├── client/src/styles.js        # dsh 设计 token 与共享样式对象
├── client/src/ui.jsx           # Button / Pill / StatusBanner 原语
├── client/src/*-card.jsx       # 展示卡片（OTP/改密/会话/Cookie Secure/关于）：只吃 props，无 state 无请求
├── client/src/otp-setup-dialog.jsx # OTP 绑定弹窗（扫码 / 验证 / 一次性备份码）
├── client/src/cookie-secure.js # Cookie Secure 状态推导（纯函数，单测）
├── client/src/update-notice.js # 更新提示推导（纯函数，单测）
└── client/build.mjs            # esbuild 构建 → client/index.js（dsh 经 exports["./client"] 服务）

scripts / tests
├── scripts/deploy.sh         # 部署流水线：语法检查 → 全量测试 → 同步到 DSH 安装目录 → 安装后验证（--restart 可选重启）
├── scripts/e2e.mjs           # Playwright 端到端（真实 dsh web：登录/2FA/改密全流程）
├── scripts/screenshots.mjs   # README 界面截图（docs/assets/*.png）
├── scripts/verify.sh         # curl 门禁验证（401/302/WS 拒绝/锁定）
├── scripts/reset.mjs         # dsh-auth-gateway-reset：仅删 password.json（双语输出）
├── scripts/uninstall.mjs     # dsh-auth-gateway-uninstall：删整个 auth-gateway/（双语输出）
└── tests/                    # gateway / config / policy / otp / locale / basepath / patch-ports / plugin-contract / client-contract / audit-log
```

设计要点：

- **零运行时依赖**：host 全部使用 Node 内置模块；client 构建产物仅 external 引用 dsh 运行时提供的模块。其中 `@deepseek-ai/dsh-client-ui-slots` 与 `@deepseek-ai/dsh-client-ui-primitives`（`Menu` 等官方 UI 原语，面板的下拉框用它而非原生 `<select>`）都属于外壳的**冻结模块表**（`PLATFORM_MODULES`），按 baseline 直接 external require 即可——**不要**写进 `dsh.client.external`（那里只列基线之外的动态包行，且需要提供方 row）；同理也不得内联宿主 UI，否则样式与升级行为都会与 dsh 分叉；
- **官方扩展点**：`ctx.effect`（生命周期）、`webServer.tapIndex`（randomUUID 与 authenticated LAN trust 注入）、`ctx.slots`（client UI）、`ctx.emit`（安全事件）、`dsh.bundle`（组合 patch）；
- **basePath 子路径部署**：网关路由先剥离 `basePath` 前缀（带边界检查，`/dsh2/foo` 不会被误当作 `/dsh` 前缀），302 跳转统一拼接前缀，转发上游时再剥离；PWA 元数据（`manifest.webmanifest` / `favicon.svg`）与静态资产（`/assets/*`）免认证放行（浏览器子资源请求，无敏感信息）；
- **客户端 trust 时序**：index 注入脚本在 connection 注册时翻转 `isLoopback`，早于 settings 持久化决策生效；这是项目记录的安全例外；
- **设置面板导航顺序**：注册 `settings.section` 时 `order` 必须严格大于官方 section；`tests/client-contract.test.mjs` 断言此不变量；
- **唯一的对外请求，且默认关闭**：`lib/update-check.js` 向公共 npm registry 查询 `latest` 标签，用于面板的「检查更新」（版本号与仓库链接本身来自本机 `package.json`，离线可见）。自动检查默认**关闭**（`updateCheck: false`），全新安装不联网；触发方式只有两种——用户在「关于」卡片点「检查更新」（`GET /login-api/version?refresh=1`），或部署方把 `updateCheck` 设为 `true` 让面板打开时自动查一次。约束是硬性的：**不在认证或面板的关键路径上**、结果与失败都进内存缓存（成功 6h / 失败 15min，手动重复点击另有 5s 下限）、绝不抛错（失败降级为「无法检查」而非「已是最新」）、过期结果不再当作结论展示（`lastKnown()` 只报 TTL 内的缓存）。详见 SECURITY.md；
- **页面双语**：`lib/locale.js` 读取官方 `settings` 服务的 `locale.preference`，再回退请求 `Accept-Language` 和 zh；错误消息集中在 `lib/errors.js` 一处维护（登录失败统一返回单一 `invalid-credentials` 码，防凭据枚举）；
- **登录审计**：登录成功/失败/登出/改密/OTP 启停经 `gateway.onAuthEvent` 回调输出审计日志（`ctx.logger.info`，仅事件种类 + IP + 原因，绝不记录凭据），并与暴力破解告警（`onSecurityEvent`）一同经 lib/audit-log.js 追加写入 `$DSH_HOME/auth-gateway/log/audit.log`（JSONL，按天轮转、保留 90 天；写失败只告警、不影响认证流程）——当前 dsh 运行时的 `ctx.logger` 仅入内存缓冲，该文件是唯一持久审计记录；
- **存储**：原子写（temp + rename）、0600/0700，与密码同模式；OTP 密钥以 AES-256-GCM 加密存储（主密钥来自 `DSH_AUTH_GATEWAY_MASTER_KEY` 或 `auth-gateway/otp-master.key`，见 SECURITY.md）。

## 构建

```bash
npm run build:client   # 构建 client bundle（esbuild）
npm run build:check    # 重建并断言产物与源码一致
npm run typecheck      # JSDoc 类型检查（tsc --noEmit --checkJs；宿主服务声明见 types/dsh-host.d.ts）
npm run check          # 语法检查（lib/*.js）+ 类型检查 + 全量测试
npm test               # 全量测试
npm run deploy         # 部署流水线（语法 → 类型 → 测试 → 同步 → 安装后验证）
```

client 构建产物（`client/index.js` + `.map`）随源码入库，但 `build:check` 确保二者一致——修改 JSX 源码后必须重新构建。

## 开发统计

本项目由 **DeepSeek Harness（dsh）** 完成开发与测试。早期开发会话（密码门禁阶段，模型 `deepseek-v4-flash`）：

| 指标 | 数值 |
|---|---|
| 开发时长 | 约 93 分钟 |
| 轮数（turn） | 20 |
| 步数（step） | 381 |
| 工具调用 | 393 |
| 输入 token（新增） | 206,172 |
| 缓存命中 token（KV cache） | 95,108,864 |
| 缓存命中率 | 99.8% |
| 输出 token | 243,803（其中推理 121,760） |
| 总 token（输入 + 输出） | ≈ 9,556 万 |

> 说明：缓存命中数据来自模型提供方返回的 prefix-cache（KV cache）指标；高命中率源于长会话中每步输入前缀的稳定复用。OTP 阶段（含安全评审、跨仓库 PR 协作）另计，未包含在上表。

## 版本历史

- `0.5.0`：重置/卸载命令中英双语输出；部署文档中英双语（DEPLOYMENT / NGINX-DEPLOYMENT）；文档维护；
- `0.4.2`：basePath 子路径部署（路由/跳转/转发剥离 + PWA/静态资产免认证）、登录审计日志、登录失败统一错误码 + 页面错误字典集中化（lib/errors.js）、中英文部署文档；
- `0.4.1`：认证后 LAN 浏览器设置支持（loopback-trusted，PR #7）；
- `0.4.0`：OTP 密钥 AES-256-GCM 加密存储（主密钥来自 `DSH_AUTH_GATEWAY_MASTER_KEY` 或自动生成的 `otp-master.key`）；
- `0.3.1`：从设置面板启用 OTP 无需部署开关；激活时吊销全部会话；
- `0.3.0`：网关页面跟随 dsh 语言（preference > Accept-Language > zh）、设置面板 i18n、首次部署控制台提示中英对照；
- `0.2.0`：OTP 双因素认证（TOTP + 备份码 + QR）、多层防爆破、client 设置面板、安全评审修复（重验证、防重放、限流）；
- `0.1.0`：密码门禁（设置/登录/改密、密码策略、失败锁定、全局限速、安全事件）。