# 贡献指南

这个项目接受 Issue 与 Pull Request。开始之前说明几件必要的事，能省掉来回。

## 报告问题

到 [Issues](https://github.com/FiretrUCK666/dsh-task-board/issues) 提交，请先搜索已有的 Issue 避免重复。**插件无法加载**是最常见的一类，请附上：

- 你的 DeepSeek Harness 版本（`dsh --version`）；
- 本插件版本（设置 → 已安装插件列表里看）；
- 界面上那段报错原文，或终端启动时的报错；
- 怎么复现（操作步骤；偶发的也说明当时在做什么）。

这四样基本能直接定位。DeepSeek Harness 的内部接口会随版本变化，插件需要跟着改；报错原文能直接指出是哪个接口变了。

## 提出改动

1. 开一个 Issue 说明你想改什么、为什么。涉及行为变化或新增依赖的，先在 Issue 里讨论清楚再动手。
2. 在分支上改，然后开拉取请求：
   - **没有本仓库写权限**（大多数情况）：先 **fork** 到你自己的账号，克隆 fork 出来的那份，在分支上开发，推回你自己的 fork，再从那个分支开拉取请求；
   - **有写权限**（协作者）：直接从主干拉一个分支即可；
   - **只改文字**（错别字、文档表述）：在网页上点开文件、点铅笔图标改完提交即可，GitHub 会替你建好分支与拉取请求——这条路跑不了下面「提交 PR 前」那些检查，别用它改代码。
3. 跑完「提交 PR 前」那几条检查，全绿再提交。
4. 提交拉取请求，说明改了什么、为什么、怎么验证的。

第一次提拉取请求、或不确定 fork 怎么用，看 GitHub 官方的[参与项目](https://docs.github.com/zh/get-started/exploring-projects-on-github/contributing-to-a-project)（复刻到拉取请求的完整步骤）。fork 落后于正本时，在自己 fork 的页面上点 **Sync fork** 更新即可。

**不要往本仓库推主干，也不要打版本标签或发布**——发版由维护者执行（见「发布」）。

## 仓库结构

克隆下来之后，根目录每一项是什么：

| 路径 | 是什么 |
| --- | --- |
| `src/` | 源码。host 半区（Node 主进程）、client 半区（浏览器）、`core/` 纯逻辑三层；各自的入口与职责见 `AGENTS.md` 的「架构」 |
| `lib/` | 构建产物，**但它入库**：安装来源（npm / GitHub / 本地链接）都不执行构建，缺了它别人起不来。改完源码必须 `pnpm build` 再一起提交，CI 会比对 |
| `tests/` | 测试。按域组织：一个 src 模块通常对应一个 `tests/<模块>.spec.ts`，入口与纯类型定义除外；`panel-harness.ts` 是被多个 spec 共用的渲染台架，不是测试本身 |
| `scripts/` | 能直接 `node` 跑的程序：`verify-*` 是随 `pnpm verify` 跑的静态门禁，其余是构建、发版与开发工具。**门禁不用登记**：`scripts/run-gates.mjs` 发现磁盘上每一个 `verify-*.mjs` 并逐个跑（连同它们各自的自测开关），所以新写一个门禁脚本就自动生效——清单会过时，发现不会 |
| `scripts/probes/` | **探针**：不能自己跑，只能当载荷交给 `shot-panel --eval-file` 在真 Chromium 里求值。`DESIGN.md` 里每一条「量法」点的就是这里 |
| `build/` | 构建配置：打包器的预设与它用的平台模块表，由根目录的 `tsdown.config.ts` 导入 |
| `locale/` | 界面文案的中英词条 |
| `.impeccable/` | `impeccable` 设计技能的状态；`design.json` 与 `config.json` 入库，`pnpm verify` 的设计文档检查要读它们 |
| `.design/` | 本地草稿：截图、候选页、一次性探针。**不入库，也不许被 `DESIGN.md` 引用**——正文里写的路径必须是干净克隆也打得开的 |

## 开发环境

```sh
git clone https://github.com/FiretrUCK666/dsh-task-board.git
cd dsh-task-board
pnpm install
pnpm build       # 产出 lib/index.js 与 lib/client.js
pnpm typecheck
pnpm test        # 单元与契约测试
pnpm verify      # 静态门禁 + 客户端 bundle 冒烟
```

本地调试挂载：

```sh
dsh plugin --profile web add .
```

挂载一次就够了——本地安装是指向工作目录的链接，改完代码不必重跑这条命令。之后的循环是：改代码 → `pnpm build`（运行时读 `lib/`，不读 `src/`）→ 改 client 半区刷新页面即可，改 host 半区（`src/index.ts`、`src/host/`）要重启 `dsh web`。

## 提交 PR 前

CI 跑七步，本地跑下面这条能省一轮——它覆盖了 CI 的每一步，包括最后那条最容易漏的：

```sh
pnpm install --frozen-lockfile && pnpm build && pnpm typecheck && pnpm test && pnpm verify
git diff --exit-code --stat -- lib   # 产物与源码一致：有输出就说明你忘了 pnpm build 后再提交
```

| CI 步骤 | 本地对应 |
| --- | --- |
| Script syntax（`node --check` 扫 `scripts/` 全部脚本） | 上面那条不覆盖，见下 |
| Install dependencies | `pnpm install --frozen-lockfile` |
| Build / Typecheck / Test | `pnpm build` / `pnpm typecheck` / `pnpm test` |
| Verify standalone gate | `pnpm verify` |
| Committed artifacts match a fresh build | `git diff --exit-code --stat -- lib` |

- **`lib/` 必须与源码一起提交**。它是发布产物，但仓库里的安装来源不执行构建（见 README 的说明）。CI 会在 Linux 上重新构建并与提交比对，不一致就失败——所以本地改完源码后一定要 `pnpm build` 再提交，并用上面那条 `git diff` 自查。
- **`scripts/` 里的脚本要能解析**。CI 用 `node --check` 逐个扫，因为发版脚本只在打 tag 时才跑，语法错误会一路混到发布失败才暴露。改过脚本的话，本地跑一遍：

  ```sh
  node --check scripts/<你改的那个>.mjs
  ```

- **用户可见改动 bump 一个 patch**：行为、界面、报错文案、README 任一变了就算；纯重构、测试、内部文档不用。
- **新增或修改行为要带测试**。测试按域组织：一个 src 模块通常对应一个 spec（入口与纯类型定义除外），新增逻辑归入对应域的现有 spec。
- **遵守项目的硬性规范**（见下）。

## 硬性规范

这些不是风格偏好，是项目已成型时定下的约束，改它们需要先讨论：

- **不引入新依赖**（运行时尤其）。需要时先在 Issue 里说明理由。
- **只使用官方 `@deepseek-ai/*` SDK**；不修改 DeepSeek Harness 源码；`tsconfig` 不得指向外部目录。
- **文档与代码、文案一律不用 emoji**。
- **命名不得偏离既有约定**（包名、插件 id、路由、存储单元名、localStorage 键）。这些标识与已装用户的数据绑定，改名会造成数据错位。
- **任何界面改动都要同时给出桌面与窄屏两档的处理**，且不能靠藏掉标签、藏掉控件或缩小字号来省空间。**这一条没有自动门禁，靠评审把关**——改界面时请自己说清楚两档各是什么样；写新面板或新断点时，`tests/bands.spec.ts` 那份「JS 与 CSS 对同一条边界必须给出同一个答案」的断言可以照抄，它守的是两档的**判定一致**，不替代你对布局本身的判断。

## 关于 AGENTS.md

仓库根目录的 `AGENTS.md` 是项目的约定文档，也是 AI 助手在这个仓库里工作时的依据。改动项目行为（尤其架构、发布流程、硬性规范）时，请一并检查它是否需要同步——它描述的是「项目要求什么」，不是某个人的笔记，所以对任何接手者都成立。

## 提交信息

简短说明这次改了什么。中文或英文都可以，不用 emoji。一个逻辑变更一个提交，便于回退。

## 发布

发版由维护者执行：更新版本号 → 构建 → 提交 → 推 tag。推 tag 会触发 GitHub Actions 完成构建、测试、GitHub Release 说明与 npm 发布，不需要手动操作 npm。

## 许可

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