# 参与贡献指南（CONTRIBUTING）

感谢你花时间考虑为 **dsh-workspace-enhance** 贡献代码、测试或文档！🎉

本文件是本仓库的贡献规范，结构参考
[github/explore 的 CONTRIBUTING.md](https://github.com/github/explore/blob/main/CONTRIBUTING.md)
的规范骨架：**贡献前检查清单 → 什么算好的贡献 → 质量与数据完整性 → 提交流程 → 保持关注**。

在提交 Issue、Pull Request 或改动之前，请先通读本文件。

---

## 仓库定位与贡献范围

dsh-workspace-enhance 是 DSH（DeepSeek Harness）Web 界面的侧栏工作区增强插件：
以默认工作区浏览器为基础，把左侧栏改造成**工作区文件夹列表**，每个文件夹下有
**任务 / 文件 / Git** 三个子 Tab，另加右侧文件预览面板。

架构速览（详见 [README.md](./README.md)）：

- **node 半边**（`lib/index.js`，宿主进程运行）：注册通用 RPC 通道
  `/dsh-workspace-enhance`，endpoints：`fs/root`、`fs/list`、`fs/read`、
  `git/log`、`git/show`、`git/status`、`git/branches`、`session/delete`、
  `debug/report`。
- **client 半边**（`src/`，浏览器运行，构建产物为 `lib/client.js`）：注册
  `sidebar.workspaces`（`priority: -1` 遮蔽内置浏览器）与 `shell.overlay` 两个槽位。

### 什么算好的贡献

对应 explore 规范中的 *What makes a good topic* —— 贡献应当聚焦、相关、可验证：

| 类型 | 好贡献示例 |
|---|---|
| 新功能 | 与默认 DSH 浏览器行为对齐的新能力（复用 `--dsw-*` 样式变量、同一套交互语言） |
| 缺陷修复 | 任务/文件/Git 面板的 bug、样式错位、边界情况（空目录、非 git 目录、超长路径） |
| 测试 | 为 node 半边端点、store、渲染行为补充集成测试或渲染测试 |
| 文档 | README / CONTRIBUTING / CHANGELOG / 注释的修正与补全 |
| 工程质量 | 类型收紧、错误处理、可访问性（键盘操作、aria）、性能（懒加载、大目录截断） |

### 不适合的贡献

对应 explore 规范中的 *Data integrity* —— 以下改动会被拒绝：

- 与插件定位无关的改动（如独立的主题系统、与工作区无关的工具）。
- 自我宣传或与仓库无关的链接、内容。
- 伪造或「美化」测试结果（测试必须真实通过，见下文「质量与数据完整性」）。
- 直接手改构建产物 `lib/client.js`（它是 `src/` 的构建输出，改动会被覆盖）。
- 破坏 profile 安装 / 卸载流程的改动（`dsh plugin add`、`cordis.patch.yml` 注入、
  `files` 白名单等）。
- 未经验证、无对应测试或文档说明的改动。

---

## 贡献前检查清单

**在发起 Pull Request 前，请逐项核对（PR 模板中也会再次出现）：**

### 代码

- [ ] `npm run typecheck` 通过（`tsc --noEmit`，strict 模式）。
- [ ] `npm run build` 通过（esbuild 产出 web2 ModuleLoader 格式 bundle）。
- [ ] `npm test` 全绿（node 半边集成测试 + client 干跑 + 真实 store 测试）。
- [ ] 涉及 UI 的改动，渲染测试（`scripts/render-tabs-test.tsx` /
      `scripts/render-git-test.tsx`）通过。
- [ ] **RPC 契约同步**：新增 / 修改端点时，`lib/index.js`（实现）、
      `src/contract.ts`（类型）、README（文档）三处必须一致。
- [ ] client 半边改动只改 `src/`，**不手改** `lib/client.js`；构建后确认
      `lib/` 产物已同步（详见「开发环境与构建」的注意项）。
- [ ] 样式对齐：复用默认工作区的 `--dsw-*` 变量与尺寸约定（文件夹行 34px、
      会话行 32px 等），不另起独立主题。
- [ ] 命名与注释：模块头 JSDoc、关键类型注释、清晰的命名。

### 文档

- [ ] 行为变化同步更新 `README.md`（功能表 / 端点表 / 已知限制）。
- [ ] `CHANGELOG.md` 增加对应条目（Keep a Changelog 格式）。
- [ ] 删除 / 变更已有能力时，同步更新本文件与相关文档，避免文档与实现漂移。

---

## 质量与数据完整性

- 只提交**你实际验证过**的改动：改完必须本地跑一遍检查清单。
- 文档必须与实现一致：README 说支持什么，代码就必须支持什么；不夸大能力。
- 已知问题必须如实记录到 README 的「已知限制」，而不是隐瞒或绕过。
- 测试必须真实通过：不允许删改测试来「变绿」，不允许提交未运行的测试。
- 不引入与仓库无关的依赖；新增依赖需说明理由（如内联打包 prismjs 与
  micromark/mdast 渲染管线进 client bundle 的先例）。

---

## 开发环境与构建

```powershell
# 1) 前置：本机已安装 DSH，且存在 web profile
# 2) 安装构建期依赖（esbuild + prismjs + micromark 管线；会被打进 client
#    bundle，无需进 profile）
npm install --ignore-scripts --legacy-peer-deps

# 3) 构建 / 监听（client 半边改动）
npm run build          # 或 npm run watch（HMR 免刷新热加载浏览器半边）

# 4) 测试
npm run typecheck      # tsc --noEmit
npm test               # 聚合：node 半边集成测试 + client 干跑 + 真实 store 测试
node scripts/test-node.mjs        # node 半边集成测试（需本机 git）
node scripts/dry-run-client.mjs   # client bundle 干跑（ModuleLoader 格式校验）
node scripts/test-real-store.mjs  # 真实 store 引擎 + persist 测试
# 渲染测试：esbuild 打包 scripts/render-tabs-test.tsx 后运行（见该文件头部注释）
```

**注意（重要）**：web profile 用 pnpm 安装的 `file:` 依赖是**打包拷贝**，不是
符号链接——`npm run build` 会把 `lib/*` 同步进
`C:\Users\yicheng\.dsh\profiles\web\node_modules\dsh-workspace-enhance\lib`。
**client 半边**改动靠 HMR 热加载（无需重启）；**node 半边（`lib/index.js`）改动
必须重启 `dsh web`**。

---

## 提交流程

### Commit message 规范

采用 Conventional Commits 风格：

```
<type>(<scope>): <subject>

<body（可选）>
```

- `type`：`feat` / `fix` / `docs` / `test` / `refactor` / `chore` / `perf` / `style`
- `scope`（可选）：`session` / `files` / `git` / `preview` / `store` / `rpc` / `build` / `docs`
- `subject`：祈使句、小写开头、不超过 72 字符

示例：`feat(files): 支持在文件树中按扩展名过滤`、`fix(git): 非 git 目录下 Graph 视图空指针`。

### Pull Request 检查清单

发起 PR 时请勾选（模板 `.github/PULL_REQUEST_TEMPLATE.md` 中会自动出现）：

- [ ] 描述了改动内容与动机（关联 Issue 编号）。
- [ ] 贡献前检查清单全部通过（见上文）。
- [ ] 附上了必要的验证证据（测试输出 / 截图 / 复现与修复说明）。
- [ ] 已更新 README 与 CHANGELOG。

### Review 期望

- 小步提交、聚焦单一目的，便于 review 与回滚。
- 收到 review 意见后及时响应；被要求修改时重新跑一遍检查清单。
- 维护者合入前会要求所有检查项通过；重大行为变化需要 README 同步说明。

---

## 保持关注

对应 explore 规范中的 *Staying informed*：

- Watch 本仓库，关注 Releases 与 CHANGELOG 更新。
- 功能讨论、使用问题请开 GitHub Issue；先搜索是否已有相同 Issue。
- 关注 README 的「已知限制」，它反映当前已知边界，也决定了哪些贡献最被需要。

---

## 许可

本仓库采用 [MIT](./LICENSE) 许可。贡献即表示你同意你的改动以相同许可发布。