# 贡献指南

## 先说结论

这个项目**没有自动化测试**，只有语法自检。所以 PR 的门槛不是"CI 绿了"，而是**你说明清楚验证到了什么程度**。

## 提 Issue

请直接用仓库里的表单，别手写空 Issue（该仓库已关闭空白 Issue）：

- **[🐞 Bug 报告](../../issues/new?template=bug_report.yml)** —— 表单会强制你先过「前置自检三关」：浏览器是否存在、`browser_use` 返回原文、`computer-use` 是否可用。这三项不填会被退回，因为 90% 的「采集没反应」都是前提没到位。
- **[✨ 功能建议](../../issues/new?template=feature_request.yml)**
- **🔒 安全漏洞** —— 不要开公开 Issue，走 [私密漏洞报告](../../security/advisories/new)。

一个能被处理的 Bug 报告至少要有：

- 前置自检三关的实际结果（**贴工具返回原文，不要改写**）
- 版本号（插件版本 + DSH Desktop 版本 + Node 版本）
- 复现步骤：用了哪个品牌关键词、数量、整批分钟数、启动方式
- 实际结果 vs 预期结果
- **脱敏后的**日志片段

> 提交前请把 API Key、Cookie、订单号、真实商品链接里的签名参数、个人信息全部替换掉。
>
> 另外：**登录墙、验证码、403/429、权限拒绝不是 Bug**，那是 [设计上的停止行为](README.md#合规与免责声明)，报了也不会修。

## 提 PR

### 硬性要求

1. **不要提交采集数据。** `product-tasks/`、`outputs/`、`exports/`、`collection-index.json`、任何 `*-private.json` 都不许进仓库。`.gitignore` 已覆盖，但请自己再确认一遍 `git status`。
2. **不要提交真实商品图。** 版权归品牌/平台，不接受用作测试素材。需要示例请在 PR 里用纯色占位图。
3. **不要提交 API Key / token / cookie**，哪怕是"已经失效的旧 key"。
4. `npm run check` 必须通过。
5. 改 `assets/native-desktop/` 下的宿主适配文件时，必须同时说明**基线 DSH 版本**和**你验证过的原文件哈希**，否则不接受。

### 提交前自检

```powershell
npm install
npm run check        # 全部 .mjs/.cjs/.js 语法自检
npm run pack:check   # 看 npm pack 会打包什么，确认没把脏东西带进去
git status           # 再肉眼过一遍
git diff --stat
```

### 涉及采集流程的改动

这个项目的采集逻辑有大量"平台真实行为"的细节，纯靠读代码改很容易改坏。所以：

- PR 描述里请写：**是否真的在线验证过**、采集了多少条、哪些平台
- 没在线验证的改动，请在标题里标 `[未验证]`，我们会按未验证处理，不会合进主线
- 只有本地模拟/单元级验证的，也照实说 —— 这不丢人，假装验证过才丢人

### 代码风格

项目现有代码偏紧凑（大量单行、短变量名），那是历史原因。**新代码请正常写**：可读优先、必要时才压行。不要为了"统一风格"去重排整个文件 —— 那样的 diff 无法 review。

## 不符合规范的 PR

以下会直接关闭，不做讨论：

- 加入验证码识别、登录态伪造、代理池轮换、风控对抗
- 把默认采集间隔改小到秒级
- 加入绕过平台访问限制的"重试到成功"逻辑
- 提交真实用户数据或凭据
- 提交来源不明的大段第三方代码而不附许可声明

## 许可

提交 PR 即视为你同意以 [MIT](LICENSE) 许可贡献你的代码。