# 参与贡献

感谢你愿意花时间。这个项目不大，但**证据标准不低** —— 先说清楚这一点，能省下双方很多来回。

---

## 这个项目的两条底线

### 1. 不写「已验证」，除非真验证过

仓库里所有功能声明都区分三种状态：

| 状态 | 含义 | 写法 |
|---|---|---|
| ✅ **已实测** | 有人**真的跑过/点过**，并留下可复核的记录 | 可以写「已实测」 |
| 🟨 **未实测** | 代码读起来是对的，但没人取得运行期证据 | **必须**写「未实测」 |
| ⚪ **已知限制** | 明确不打算修，或受上游接口边界约束 | 写进已知限制表 |

**提交 PR 时请保持这个习惯。** 把「我觉得应该能行」写成「已验证」是这个项目最不欢迎的行为。

### 2. 缺陷报告要可复现

「不工作」这样的描述没法处理。有效的报告包含：

- 你**点了什么**、**期望什么**、**实际看到什么**
- 涉及的源（内置 / 自定义）与条目（可脱敏，但要能定位）
- 如果是自定义源，**给出该 JSON 的结构**（键名即可，不必给内容）

---

## 开发环境

```cmd
git clone https://github.com/yi-yezhiqiu/dsh-prompt-market.git
cd dsh-prompt-market

:: 软链接安装（改代码只需重启 DSH，不用重装）
mklink /D "<DSH profile>\node_modules\dsh-prompt-market" "<本仓库路径>"
```

安装后**完全退出并重新打开 DSH**。

### 自检

```cmd
node check-syntax.js                            :: 全部 .js 语法（自动跳过拼装片段）
node core/build-client-bundle.js --check        :: 装配区段一致性（权威判据）
node core/selftest-node.js                      :: 数据层算法自检
powershell -NoProfile -ExecutionPolicy Bypass -File ui/check-ui.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File core/check-data-layer.ps1
```

> ⏱ `selftest-node.js` 里有一条约 **78 秒**的用例（生产默认超时预算不可注入所致），属已知限制 L1。

---

## 改代码时最容易踩的三个坑

### 坑一：改了源码，忘了重新装配

`client.js` 是**装配产物**（`core/browser.js` 的 9 个单元 + `ui/` 的 8 个单元）。
改 `core/` 或 `ui/` 之后必须重新装配，否则 DSH 加载的还是旧代码。

**装配后一定要跑 `build-client-bundle.js --check`** —— 它比对的是「区段对区段」，这是唯一权威判据。

### 坑二：拿整文件去比对

- ❌ `client.js` 整文件 ↔ `browser.js` 整文件 —— 前者是装配产物、含壳层与 UI 区，**长度本就无关**
- ❌ `browser.js` ↔ `core/*.js` —— 单元体是**精简重写版**，逐行 diff **必然误报**
- ✅ 只比 **区段**：`client.js` 的 `PM-CORE-INLINE` 区段 ↔ `browser.js` 的单元区段

### 坑三：在注释里写出会导致解析出错的字面量

边界标记（`BEGIN`/`END inlined file:`）的**完整字面量不要写进任何注释**：
朴素子串匹配的脚本会把它误当成一个真实单元标记，导致区段提取错位。
（历史上 `build-client-bundle.js --check` 与 `check-ui.ps1` 的 A2 都因此误报过。）

**任何匹配标记的代码都必须锚定行首**：

```js
/^\/\* (BEGIN|END) inlined file: ?(.*?) \*\/$/
```

---

## 提交 PR

1. **一个 PR 只做一件事** —— 便于审阅，也便于回退
2. **跑一遍自检**，并把**实际输出**贴进 PR 描述（不是「应该没问题」）
3. **新增或改动功能时，同步更新文档**：`README.md`、`ui/DESIGN.md`、`core/.linecount.txt`
4. **改动了行号，就刷新台账** `core/.linecount.txt`
5. 提交信息说清**为什么**，而不只是**改了什么**

### 改了用户可见行为

请在 PR 描述里明确写出**如何验证**（点击路径、预期结果），这样别人能独立复核。

---

## 特别欢迎的三类贡献

### 🐛 补齐「未实测」清单

README 里列了一组**未实测**的场景（断网降级、重启持久化、内容过滤运行期生效、条件替换……）。
**无论结果是"通过"还是"失败"都有价值** —— 失败更有价值。

请在 issue 里附上：你的 DSH 版本、操作步骤、实际观察结果。

### 🌐 补充内置提示词源

**必须附带**：

- 上游仓库地址
- **许可证类型**
- **版权人字符串**（逐字从上游 `LICENSE` 取，不要臆造）
- 该源的 JSON 结构（标题 / 正文的字段名）

> ⚠️ 两个不同版权人的源**不得共用同一条署名**。这是本项目踩过的坑。

### 🌍 翻译 README

目前有 **简体中文 / English / 日本語**。新增语言请以中文版为基准，
保持**章节顺序与数量一致**，并保留 **「已实测 / 未实测」的区分**（**不要**把未实测翻成「已验证」）。

---

## 许可

贡献即表示你同意以本项目的 [MIT 许可](LICENSE) 发布你的贡献。

若你的贡献涉及第三方数据或代码，请确保其许可与 [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md) 相容，并一并更新该文件。