# Contributing to dsh-live-loop

[English](#english) | [简体中文](#简体中文)

## English

Thank you for improving the runtime-verification loop. Contributions are especially useful when they add a reproducible compatibility case, a failure fixture, a security boundary, or a translation.

### Before opening a pull request

1. Read [Architecture](./docs/ARCHITECTURE.md), [Decisions](./docs/DECISIONS.md), and [Security](./docs/SECURITY.md).
2. Keep the Host as the source of truth and use public DeepSeek Harness Extension Points.
3. Do not bypass DSH Tool execution, permission, approval, subprocess, Attachment, or Client Module boundaries.
4. Add tests for both the success path and the false-pass/failure path.
5. If `src/` changes, rebuild and commit the matching prebuilt `lib/` artifacts.

### Local validation

```bash
npm ci --legacy-peer-deps
npm run check
npm test
npm run test:e2e
npm run build
npm pack --dry-run --ignore-scripts
```

Use focused tests while iterating, but run the complete gate before submitting. Browser integration currently requires an installed Chrome, Edge, or Chromium runtime.

### Pull-request scope

- Keep one change set focused on one behavior or compatibility seam.
- Describe the observed problem, the chosen public DSH seam, and the evidence that verifies the fix.
- Never commit local Profiles, browser state, caches, credentials, generated tarballs, or retained app evidence.
- Preserve bounded output, cancellation, ownership, cleanup, and untrusted-page-content labeling.

### Translations

The canonical English entry is [README.md](./README.md); Simplified Chinese is [README.zh.md](./README.zh.md). New translations are welcome as `README.<language>.md`. Add every real translation to the language selector in all README variants—do not add a language link before its document exists.

### Security reports

Do not publish exploit details or credentials in a normal Issue. Prefer GitHub's private vulnerability-reporting flow for this repository. If it is unavailable, open a minimal Issue requesting a private contact channel without including sensitive details.

## 简体中文

感谢你帮助完善这个前端运行时验证闭环。能够补充可复现兼容案例、故障 Fixture、安全边界或翻译的贡献尤其有价值。

### 提交 Pull Request 之前

1. 阅读[架构](./docs/ARCHITECTURE.md)、[架构决策](./docs/DECISIONS.md)和[安全文档](./docs/SECURITY.md)。
2. 保持 Host 为唯一状态权威，并使用 DeepSeek Harness 公共 Extension Point。
3. 不得绕过 DSH Tool 执行、Permission、Approval、Subprocess、Attachment 或 Client Module 边界。
4. 同时为成功路径和“不得假通过”的失败路径增加测试。
5. 修改 `src/` 后，请重新构建并提交匹配的预构建 `lib/`。

### 本地验收

```bash
npm ci --legacy-peer-deps
npm run check
npm test
npm run test:e2e
npm run build
npm pack --dry-run --ignore-scripts
```

开发过程中可以运行聚焦测试，但提交前应执行完整门禁。浏览器集成测试目前要求系统已经安装 Chrome、Edge 或 Chromium。

### PR 范围

- 一个变更集只聚焦一个行为或兼容接缝。
- 说明观察到的问题、使用的公共 DSH 接缝，以及验证修复的证据。
- 不要提交本地 Profile、浏览器状态、缓存、凭据、生成的 tarball 或业务应用 Evidence。
- 保留输出上限、取消、所有权、清理和“不可信页面内容”标记。

### 翻译

英文入口是 [README.md](./README.md)，简体中文入口是 [README.zh.md](./README.zh.md)。欢迎以 `README.<language>.md` 添加新语言。只有文档真实存在后，才能把它加入所有 README 的语言选择器。

### 安全报告

不要在普通 Issue 中公开漏洞利用细节或凭据。优先使用仓库的 GitHub 私密漏洞报告；如果该功能尚未开启，请只创建一个不包含敏感细节的最小 Issue，请求建立私密联系方式。