# 贡献指南

## 开始前

先阅读 [模块结构](DESIGN.md) 和 [自检与验收](docs/verify.md)。使用与目标宿主兼容的 Node，推荐 24。仓库使用原生 ESM 和 Node 测试，无第三方运行时依赖；执行仓库测试不需要安装宿主。

```powershell
npm run check
```

## 修改约定

- 先找到真实入口和调用链，只修改本次问题所需的模块。
- 行为修复先添加能复现问题的测试；入口行为变化需要覆盖共用服务和真实适配器。
- 保持宿主命令、HTTP 响应、包导出与持久格式兼容；确需变化时在 PR 解释迁移与回退。
- 新增功能必须同步补齐用户说明、失败状态和验收方法。
- 保留独立实现的可核验记录，不复制其他项目的代码、注释、提示词或素材。需要引入第三方内容时先核对来源与适用许可，不能通过改名规避。
- 不把凭据、用户规则、恢复快照、运行日志或个人绝对路径提交进仓库。

## 补丁适配

只在隔离的宿主源码副本中操作。版本升级先确认原文、路径、命中数和预期效果，再更新声明、目标版本和哈希；不要只重采哈希让检查变绿。

```powershell
npm run reconcile -- '<宿主根>'
npm run check:host -- '<宿主根>'
git diff --check
```

提交 PR 时说明问题触发条件、修改后行为、实际运行的命令和未验证边界。不要把本地自检称为真实安装验收。

## 提交、PR 与版本

- 一个 PR 解决一个问题或完成一项连贯的改动，使用现有 PR 模板。界面行为变化附对应的实际验收说明。
- 提交标题使用简洁中文；实质改动在正文说明原因、主要变化和实际验证。仅格式或拼写改动可省略正文。
- PR 自动运行 Windows、Ubuntu × Node 22.19、24 检查，以及固定宿主对账与夹具预检。维护者阅读改动和结果后手动合入；不强制第二位维护者审批。
- 维护者可直接推送 main，仓库不强制分支保护；直接推送同样需要检查和明确的改动范围。
- 发布时同步更新 `package.json`、`CHANGELOG.md`、安装示例和对应的 `docs/releases/<版本>.md`。`npm run check` 会检查包版本与变更记录、宿主声明及必需文件。
- 标签使用 `v<版本>`，指向最终落地提交。已推送标签不移动；修复已打标签的代码时使用新版本。0.9 系列一律作为 Pre-release，不设为稳定最新版。
- 发布操作见 [发布流程](docs/releasing.md)：源码通过、附件通过、真实安装通过分别记录，最终发布由维护者操作。

## 报告问题

使用 [Issue 表单](https://github.com/rumoii/dsh-breaklimit/issues/new/choose)，提供插件提交、宿主版本及提交、Node 版本、系统和脱敏错误。一个 Issue 只报告一个问题，先搜索已有和已关闭的问题。不要提交完整配置、会话内容、token 或完整 `DSH_HOME`。安全问题的最小报告方式见 [安全说明](SECURITY.md)。

## 使用 AI 的说明

允许使用 AI 辅助分析、实现、测试或整理文字；Issue 和 PR 必须如实填写是否使用、具体工具和模型版本及用途。未使用写“没有使用”。

AI 发现的问题需要说明你是否亲自确认；未确认时明确标注。提交 AI 辅助生成的改动前，提交人应读过全部改动、执行相应检查，并在 PR 写明结果。未披露或未验证的自动化 PR 会被要求补充，无法补充时关闭。

English contributions are welcome. Disclose AI tools and model versions, explain their use, and report the checks you actually ran.

## 许可

提交贡献表示同意按本项目 [MIT 许可](LICENSE) 发布该贡献。