# Contribution Guide

贡献路径取决于你改的是哪一层。先判断层级，再选入口。

## 先选路径

| 你要改什么 | 首选位置 | 什么时候不该走这条路 |
| --- | --- | --- |
| 补一条资源、补标签、补技术栈 | `catalog/**/curated.json` | 你要修的是全局规则或同步机制 |
| 修同步、去重、评分、发布逻辑 | `scripts/`、`.github/workflows/` | 你只是在修单条数据 |
| 改安装命令或平台适配 | `platforms/`、`install.sh`、`install.ps1` | 问题其实来自目录数据本身 |
| 补维护文档 | `docs/wiki/` | 内容只是一次性研究或正式规格 |
| 做结构性变更 | 单独设计稿 / proposal / tasks | 只是局部字段修正或文案修正 |

如果这一步判断错了，后面的工作大概率都在补错误层的症状。

## 1. 资源类贡献

资源类贡献默认走 `curated.json`。这是当前仓库最稳定、最可控的人工入口。

典型场景包括：

- 上游还没收录这条资源
- 自动同步收到了，但标签和技术栈明显不够
- 描述不准确，影响搜索和推荐
- 安装信息缺失，导致资源虽然在目录里但几乎不可用

资源类贡献不适合用来解决这些问题：

- 分类逻辑本身有系统性偏差
- 去重策略误杀大量条目
- 某个同步脚本本来就抓错数据
- 平台命令的行为和目录层约定不一致

这些问题都不是单条数据能修好的。

### 最小要求

至少保证这些字段是你自己确认过的：

- `name`
- `type`
- `description`
- `source_url`
- `category`
- `tags`
- `install`

如果其中某个字段语义你说不清，就先不要提交。

### 提交前检查

资源类改动至少做这些检查：

- 跑 `scripts/validate_curated.py`
- 检查 `id` 是否重复
- 检查 `source_url` 是否已经存在
- 检查描述是不是自然语言，不是关键词堆砌

### 这条路径的边界

`curated.json` 是人工纠偏入口，不是全局覆盖层。当前合并逻辑不会让 curated 无条件重写所有核心字段；它更适合补充，而不是接管事实来源。

## 2. 规则和脚本类贡献

改 `scripts/`、workflow、安装脚本之前，先回答三个问题：

1. 改动影响哪一层。
2. 会不会改变 `catalog/index.json` 或发布产物。
3. 你准备怎么验证不会引入新的系统性噪声。

这类改动可以解决机制问题，但也最容易把影响范围放大。

### 适合直接改的情况

- 某个校验规则明显漏判或误判
- 某个 workflow 的命令、路径、触发条件明显错误
- 某段同步逻辑已知有确定性 bug
- 安装脚本和当前平台目录结构已经不匹配

### 不适合直接改的情况

- 你还没想清楚这是不是目录模型问题
- 你希望靠一个脚本同时补救上游质量差、历史数据脏和平台差异
- 你只能描述现象，无法定位层级

这时先回到 `Architecture` 和 `Catalog Governance`，不要直接下手。

## 3. 文档类贡献

文档也分层，不是都往一个地方写。

| 内容类型 | 放哪里 |
| --- | --- |
| 对外介绍、安装、使用 | README |
| 稳定维护说明、边界、操作入口 | `docs/wiki/` |
| 深入研究、策略分析、专题设计 | 单独保存的研究文档 |
| proposal、design、tasks、spec | 单独维护的规格文档 |

最常见的问题不是“文档没写”，而是“写在了错误的位置”。位置错了，后面的人就会在 README 找维护手册，或在规格文档里找当前实现说明。

## 4. 什么时候先写独立设计稿

以下情况建议先把 proposal / design / tasks 写清楚，再做实现：

- 新增一类核心能力
- 调整目录模型或 schema 语义
- 改变去重、评分、治理原则
- 改变平台命令契约
- 引入新的长期维护流程

这些改动的共同点是：它们会改变多人协作的共同前提。没有 proposal 和 design，后面很难判断改动是偏离实现，还是偏离原意。

## 5. PR 里应该说清什么

### 资源类改动

PR 至少说清：

- 你补了什么资源或字段
- 为什么现状不够
- 你怎么确认字段准确

### 机制类改动

PR 至少说清：

- 问题在哪一层
- 改动会影响哪些产物
- 你跑了什么验证

### 文档类改动

PR 至少说清：

- 为什么这段内容应该放在这里
- 它取代或补充了哪份现有说明

## 6. 仓库欢迎什么样的改动

欢迎的改动有共性：

- 让目录更准
- 让安装更清楚
- 让维护动作更可解释
- 让自动化更稳定

不欢迎的改动也有共性：

- 靠兜底值掩盖不确定字段
- 用个例去污染全局规则
- 没有验证路径的大改
- 只因为“看起来更高级”就重构

## 7. 常见误区

### 直接改 `index.json`

通常没有意义。很多 `index.json` 是自动同步产物，下次同步会覆盖。

### 先在前端层打补丁

如果问题本质在目录数据，前端兼容只会把问题藏起来。

### 补一条 curated 就等于长期人工维护

不是。curated 只表示这条记录进入了人工纠偏入口，不表示维护者承诺持续手工追踪它。

## 8. 最稳妥的首次贡献方式

第一次参与时，最稳妥的路径仍然是：

1. 修一条 curated 记录。
2. 跑校验。
3. 在 PR 里把问题和修改范围讲清楚。
4. 不顺手改全局脚本。

先学会“改对层”，比第一次就改大系统更重要。
