# 贡献指南 / Contributing

感谢你帮助改进 `dsh-mcp-connector`。请不要在 Issue、PR、日志、截图或测试数据中提交 Token、API Key、Cookie、OAuth 凭据或真实业务数据。

Thank you for contributing. Never put tokens, API keys, cookies, OAuth credentials, or real business data in issues, pull requests, logs, screenshots, or fixtures.

## 参与方式

- 报告安全漏洞：请遵循 [安全报告政策](https://github.com/duhu2000/dsh-mcp-connector/blob/main/SECURITY.md)，使用 [私密报告入口](https://github.com/duhu2000/dsh-mcp-connector/security/advisories/new)，勿公开提交利用细节。
- 报告普通缺陷或提交功能建议：[GitHub Issues](https://github.com/duhu2000/dsh-mcp-connector/issues)
- 为公共市场增加连接器：阅读 [Connector onboarding](https://github.com/duhu2000/dsh-mcp-connector-registry/blob/main/docs/ONBOARDING.md)，连接器描述与插件代码分仓管理。
- 修复插件或改进文档：Fork 本仓库，从最新 `main` 创建单一目的的分支并提交 PR。
- 第一次参与：从带有 [`good first issue`](https://github.com/duhu2000/dsh-mcp-connector/labels/good%20first%20issue) 标签的任务开始，并按[首次贡献路径](docs/FIRST-CONTRIBUTION.md)完成本地校验。
- 搭建私有目录：参考 [README 配置说明](README.md#配置) 和 [市场注册指南](docs/MARKET-REGISTRATION.md)。

## 本地开发

要求 Node.js 20 或更高版本。DSH 运行期 peer dependencies 由 Host 提供，本地安装使用：

```bash
npm install --legacy-peer-deps
npm run check
```

如果修改公共 Registry 或市场元数据，还应运行：

```bash
npm run registry:build
npm run registry:validate
npm run market:check
```

UI 可以在无真实凭据的 mock 环境中验收：

```bash
npm run dev:ui
```

## PR 要求

1. 一个 PR 解决一个明确问题，不要夹带无关重构。
2. 新增或修改行为时增加对应测试；纯文档改动也必须通过 `npm run check`。
3. 中英文用户文档应同步更新。
4. README 中的当前版本必须与 `package.json` 一致，`npm run docs:check` 会阻断版本漂移。
5. 只使用无凭据 mock 或已脱敏数据做测试与截图。

## 从 Fork 到 PR

```bash
git switch main
git pull --ff-only
git switch -c feat/<short-purpose>
npm install --legacy-peer-deps
npm run check
```

提交时说明用户问题、解决方案、测试结果与必要的手工验收步骤。

## 维护者如何准备首次贡献任务

首次贡献任务应边界清楚、无需真实凭据或私有 DSH 环境，并在 Issue 中写明背景、建议修改文件、验收标准和验证命令。适合的范围包括文档示例、无凭据测试夹具、可访问性文案和小型校验器改进；涉及发布、OAuth 凭据、Registry 上架审批或大规模重构的工作不应标记为 `good first issue`。