# 🤝 贡献指南（CONTRIBUTING）

> 感谢你愿意让这本白皮书变得更好。无论你是新手还是老手，下面 5 分钟就能看懂怎么参与。

## 📖 项目简介

**dsh-handbook（DeepSeek Harness 白皮书）** 是一本面向新手的开源教程：从"什么是 Agent 运行时"讲起，到安装、使用、开发插件、性能调优——每一章都有可复制、可运行的命令，全部在本机实测验证。

- 语言：中文优先，英文同步
- 覆盖：11 章正文 + Benchmark + 快速上手资产（速查卡 / 插件模板 / 配置参考 / FAQ）
- 许可：内容 [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/)，示例代码 MIT
- 约束：dsh 目前是 `0.1.0-rc` 预发布阶段，命令/行为可能随版本迭代变化

## 🧭 怎么贡献（3 种方式，按门槛从低到高）

### 1. 提 Issue 报错（零门槛，最有价值）

读文档时发现**命令失效、截图过期、链接打不开、表述有误**？直接提 Issue：

- **标题**：一句话说清问题（如 `第 2 章：安装命令 404，疑似 rc.6 变更`）
- **内容**：章节/文件位置 + 你执行的命令 + 报错信息（截图更佳）+ 环境（OS / Node 版本 / dsh 版本）
- **标签**：按需选 `bug`（内容错误）或 `documentation`（表述/排版）

> 提示：rc 版本迭代快，**先确认问题是否已在 [ROADMAP.md](./ROADMAP.md) 的"进行中"里**，避免重复。

### 2. 提 PR 改内容（有写作/校对经验）

想直接改正文、修错别字、补案例？走标准 PR 流程（见下方）。适合：

- 修正失效命令 / 过期版本号
- 补充实测数据（附命令与日志证据）
- 润色表述、修中英混排空格、补代码块语言标注
- 新增社区案例（如新的 dsh-plugin 生态项目）

### 3. 分享案例（不碰代码也能参与）

你用自己的话跑通了某个场景？欢迎：

- 在 [Discussions](https://github.com/deepseek-ai/deepseek-harness/discussions) 分享使用经验（官方当前建议的贡献入口）
- 给我们提 Issue 附上你的案例，合适合并进 [第 5 章：dsh 应用场景](./docs/05-cases.md) 或 [第 10 章：复杂实战案例](./docs/10-complex-cases.md)
- 案例需含：场景 / 命令 / 耗时或产物 / 验证方式（与正文"每章可运行、全部实测"的标准一致）

## 🔀 PR 流程（fork → branch → PR）

> 本项目走标准 GitHub fork 工作流。所有改动需保持"每章可运行、命令实测"的底线。

```text
1. Fork 本仓库 → 克隆到本地
2. 新建分支：git checkout -b docs/fix-xxx   （分支名用 docs/、fix/、feat/ 前缀）
3. 修改 → 本地验证（见"提交前自检"）
4. git add → git commit（信息用中文或英文均可，参考仓库历史风格）
5. git push origin 你的分支
6. 在 GitHub 提 PR → base 选 main → 描述改动原因与验证结果
```

### 提交前自检清单

- [ ] 只改了该改的文件，**没动无关的章节 / 数据 / 目录结构**
- [ ] 新增命令已在本机实际跑过，并附输出证据
- [ ] 中英混排空格符合规范（见下）
- [ ] 标题层级正确、代码块有语言标注
- [ ] 链接是相对路径（`./docs/...`），不是绝对路径

### PR 标题风格（参考历史）

- `docs: 补第 5 章 xx 案例（附实测日志）`
- `fix: 第 2 章安装命令适配 rc.6`
- `feat: 新增 xxxx 章节`

> 合入后，你的名字会出现在下面的"贡献者"名单里 🎉

## ✍️ 写作规范

统一风格才能让 14 章读起来像一本书。请遵守：

### 1. 中英混排空格

中文与英文/数字之间**加一个空格**：

- ✅ `dsh 当前版本 0.1.0-rc.6`（中文「dsh」「0.1.0」之间）
- ❌ `dsh当前版本0.1.0-rc.6`
- 例外：全角标点（，。：；）与中文之间不加空格；代码/内联代码内部不加

### 2. 标题层级

- `#` 仅用于文件首行标题；正文一级分节用 `##`，往下递减，**禁止跳级**（`##` → `####`）
- 中文标题末尾**不加句号**；长标题可用 `：` 分隔主副标题
- 每章开头保留 `> 本章目标：...` 引言块，保持全书统一

### 3. 代码块标注语言

所有代码块必须标注语言，方便语法高亮：

- bash / yaml / json / typescript / markdown 等，按实际内容选
- 命令示例用 `bash`，配置用 `yaml`，严禁留空或写错语言
- 需要强调"输出结果"的，用 `# →` 注释放在命令下方（见 README 演示区写法）

### 4. 证据优先

正文中的耗时、命中率、版本号等数据**必须来自实测**，并尽量附命令与日志。禁止无依据的推测性数字。

## 🎉 贡献者

按合入顺序致谢（2026-08-13 启动，等你来占位）：

- 维护者：[Electricitysheep](https://github.com/Electricitysheep) —— 全书撰写与实测
- **下一个就是你** —— 详见上文贡献方式

> 贡献者名单随每次合入自动追加；若你在 Issue / Discussion 中提供了被采纳的案例或勘误，同样收录。

## 💬 沟通渠道

- 问题讨论：[GitHub Discussions](https://github.com/deepseek-ai/deepseek-harness/discussions)（官方）
- 社区插件：[topic:dsh-plugin](https://github.com/topics/dsh-plugin)
- 本项目路线：[ROADMAP.md](./ROADMAP.md)