# Contributing to dsh-model-router

[完整中文说明](./CONTRIBUTING.zh.md)

Thank you for considering a contribution. This is the maintainer's first open-source project, so clear explanations, small reproducible examples, patient review, and suggestions about project process are all welcome.

感谢你考虑参与这个项目。这是维护者第一次做开源项目，因此非常欢迎清楚的解释、最小复现、耐心的代码审查，以及对项目协作方式的建议。

## Ways to help / 参与方式

- Report a reproducible bug. / 提交可以复现的问题。
- Review code, security boundaries, DSH assumptions, or documentation. / 审查代码、安全边界、DSH 接口假设或文档。
- Improve Chinese-English parity. / 补齐中英文对应内容。
- Add tests that demonstrate a real failure before changing behavior. / 在修改行为前，先增加能够复现真实问题的测试。
- Pick an item from the [roadmap](./ROADMAP.md). / 从[公开路线图](./ROADMAP.md)中选择任务。

Questions are welcome. You do not need to arrive with a complete solution. / 欢迎先提问题，不要求一开始就给出完整解决方案。

## Before opening an issue / 提交 Issue 前

1. Search existing issues. / 先搜索已有 Issue。
2. Remove API keys, settings files, signed URLs, generated media, local absolute paths, and employer or customer data. / 删除 API Key、设置文件、签名地址、生成媒体、本机绝对路径及单位或客户资料。
3. Include DSH version, Node version, operating system, the smallest reproduction, expected behavior, and actual behavior. / 写明 DSH 版本、Node 版本、操作系统、最小复现、预期行为和实际行为。
4. Report security issues privately through the process in [SECURITY.md](./SECURITY.md). / 安全问题请按照 [SECURITY.zh.md](./SECURITY.zh.md) 私下报告。

## Development setup / 开发环境

Requirements / 运行要求：

- Node.js `^22.19.0` or / 或 `>=24.0.0`
- pnpm 11.21.0 through Corepack / 通过 Corepack 使用 pnpm 11.21.0
- DSH 0.1.0-rc.6 peer packages from the lockfile / 锁文件中的 DSH 0.1.0-rc.6 对等依赖

```bash
corepack enable
pnpm install --frozen-lockfile
pnpm test
pnpm check:secrets
pnpm build
```

## Change rules / 修改规则

- Keep each pull request focused on one problem. / 每个 Pull Request 聚焦一个问题。
- For behavior changes, first add a test that fails for the intended reason; then implement the smallest fix. / 行为修改先写能按预期原因失败的测试，再实现最小修复。
- `lib/` is committed for direct installation; commit matching generated changes whenever `src/` changes. / `lib/` 为直接安装而提交；修改 `src/` 后必须提交对应生成产物。
- Do not reintroduce a duplicate text-model adapter stack. DSH owns text providers and credentials. / 不要重新引入重复的文字模型适配器；文字模型和凭据由 DSH 管理。
- Do not run `pnpm accept:models` in automated CI; it can consume paid quota. / 不要在自动化持续集成中运行 `pnpm accept:models`，它可能产生费用。
- Public-facing English documentation must include a complete Chinese counterpart, and vice versa. / 面向用户的英文文档必须有完整中文对应，中文文档也应提供英文入口。

## Pull requests / Pull Request 要求

Please explain / 请说明：

1. the problem and why it matters / 问题及其影响；
2. the root cause or design reasoning / 根因或设计理由；
3. the files and behavior changed / 修改的文件和行为；
4. tests and commands run / 已运行的测试与命令；
5. compatibility, security, cost, or migration impact / 兼容性、安全、成本或迁移影响。

Draft pull requests are welcome for early discussion. Maintainers may ask for a smaller scope; that is about making review easier, not rejecting the idea. / 欢迎用草稿 Pull Request 提前讨论。维护者可能建议缩小范围，这是为了便于审查，并不等于否定想法。

## Review style / 审查方式

Please be direct about technical problems and kind to people. Explain why a change is unsafe or incorrect, link evidence when possible, and separate required fixes from optional preferences. / 技术问题可以直接指出，但请尊重参与者。尽量说明为什么不安全或不正确，有条件时提供依据，并区分必须修复与个人偏好。