# 贡献指南

> **面向：**贡献者。本文说明开发环境、改动纪律、测试与文档要求。
> 架构与代码地图见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)；发布流程见 [docs/PUBLISHING.md](docs/PUBLISHING.md)。

## 1. 开发环境

```bash
npm ci            # 安装依赖
npm run typecheck # 类型检查（必须 0 错误）
npm run build     # 编译 src → lib，并构建客户端 bundle（内含契约自检）
npm test          # 全量回归（提交前必须全绿）
```

**新增 `src/*.ts` 文件时**：必须同时把该文件加入 `tsconfig.json` 的 `include`，否则它不会进入构建产物。
**改客户端（`src/client.ts`）时**：`npm run build` 会做**客户端契约自检**，失败即说明 bundle 不符合宿主契约。

## 2. 改动纪律（按风险从高到低）

| 类别 | 要求 |
|---|---|
| **安全默认值** | **不得放松**。默认拒绝、fail-closed、私有 Key 不可被他人读取等不变量见 [SECURITY.md](docs/SECURITY.md)；确需权衡请在 PR 中显式说明并更新该文档的"已知边界" |
| **认证/会话/加密** | 必须附带测试；改密、删除用户、撤销分享后必须**立即失效** |
| **宿主交互**（路由注册、cookie、mux、按用户模型） | 必须做 **live 验证**（起一个一次性实例跑 `test/live-020-check.mjs`），单测不足以证明 |
| **UI** | 保持既有排版约定（12px 字段标题、按钮 `white-space:nowrap`、一列一行）；改完在浏览器里量测关键对齐 |
| **文案** | 一律走 i18n（见 §4） |

## 3. 提交与分支

- 提交信息用**祈使句**，第一段说明"改了什么"，正文解释**为什么**（尤其安全相关）；
- 一次提交尽量聚焦一件事；**提交前必须 `npm test` 全绿**；
- 分支：功能用 `feat/<name>`，修复用 `fix/<name>`；合入 `main` 由维护者执行；
- **不要**提交构建产物以外的临时脚本、探测文件或截图原图（截图产物 `assets/*.png` 例外，属发布材料）。

## 4. 文案与 i18n（强制）

新增任何**用户可见**文案时：

1. 若是"语义化"的一句话/标签，加入 `src/i18n.ts` 的词典（同时给 `zh` 与 `en`）；
2. 若是零散短语（含拼装式文案），加入 `src/i18n-phrases.ts`（`[中文原文, 英文译文]`，**原文必须唯一**）；
3. 运行 `node test/i18n.test.mjs`（会校验：两种语言键一致、译文非空、原文不重复、译文不引入 HTML 标签）；
4. **不要**把运维日志（`[dsh-ui-auth]` 前缀）或纯代码片段加入词典。

## 5. 测试要求

- 逻辑改动 → 单测（`test/*.test.mjs`）；新增文件要**接进 `npm test`**；
- 宿主行为改动 → live 检查（`test/live-*.mjs` 或 `npm run test:compat:matrix`）；
- 安全相关改动 → 在 `test/security-suite.mjs` 补用例（`check('类别', '用例名', 条件)`）；
- 修复 bug 时**优先补一条会失败的用例**，再修（本仓库的多个回归都是这样做出来的）。

## 6. 文档要求

- **角色优先**：新内容先判断读者（首次使用者 / 运维 / 审计员 / 集成者 / 开发者 / 维护者），放进对应文档；
- 每份文档开头有 `> **面向：**…` 声明；**新增文档必须在 [docs/INDEX.md](docs/INDEX.md) 登记**；
- 同一事实只在一处详解，其它地方给**摘要 + 链接**；
- 运维与审计类内容给**可复制命令**，不要写"请自行确认"；
- 版本相关的变化同步 [CHANGELOG.md](CHANGELOG.md)；兼容性变化同步 [兼容性矩阵](docs/DSH-0.2.0-COMPATIBILITY.md)。

## 7. 报告问题

功能缺陷走公开 Issue（附：DSH 版本、插件版本、复现命令、期望/实际）。
**安全问题请勿公开细节**，按 [SECURITY.md](docs/SECURITY.md) §9 的渠道报告。