# 贡献指南 / Contributing

欢迎 PR、issue、文档纠错。请先读 [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md)（架构与踩坑）和 [`SECURITY.md`](SECURITY.md)。

## 快速开始 / Quick start

```sh
git clone https://github.com/muvuula/DeepSeek-Harness-Core.git
cd DeepSeek-Harness-Core
node --version          # 需要 Node >= 20（开发用 26 测过）
node --check dsh/index.mjs
```

本仓库是 **DeepSeek Harness（DSH）插件**，没有独立可执行入口。要看到效果必须装进 DSH profile：

```sh
dsh plugin --profile web add github:muvuula/DeepSeek-Harness-Core#master   # 或本地目录
# 重启 dsh web 后访问 http://127.0.0.1:3080/api/dhc/panel
```

**运行时副本铁律 / Copy discipline**：DSH 实际加载的是 `~/.dsh/profiles/web/node_modules/mcore/`，
不是你的 git 工作区。改完源码必须同步过去并核对哈希，不然你会以为"改了没生效"：

```sh
cp dsh/index.mjs ~/.dsh/profiles/web/node_modules/mcore/dsh/index.mjs
md5sum dsh/index.mjs ~/.dsh/profiles/web/node_modules/mcore/dsh/index.mjs
```

## 改动前必读 / Before you change anything

1. **不要**把个人数据写进仓库：`persona-core.json*`、`mcore-backup.json`、`stockdata/`、
   任何本机路径（`C:\Users\<你>`、`/home/<你>`）、机器码、账号、token 都在 `.gitignore` 之外的红线内。
   `node release-check.mjs` 会拦常见泄漏。
2. **小步验证**：每改一处 → `node --check` → 同步 → 重启 → 调 API 验证。
   一次大改曾留下孤立 `}`，让面板 JS 全崩。
3. **面板 HTML 不受 `node --check` 保护**：`dsh/index.mjs` 里的 `panelPageHtml` 模板字符串内含
   `<script>`。改完请做括号平衡（`{}` 深度归零）和标签平衡（`<div>` vs `</div>`）自检。
4. **中英双语成对改**：面板文案在 `P_I18N.zh` / `P_I18N.en` 两块，漏一边就会显示 key 名。
5. **五器官不内联**：ModLens / at-file / genui / automation / better-sidebar 是独立插件，
   内联会触发 `duplicate factory registration`（页面白屏）。
6. **client 重建**：改了 `client-dhc.mjs` / `client-entry.mjs` 后跑 `npm run build:client`，
   产物 `dsh/client.js` 一起提交。

## 提交规范 / Commit & PR

- 分支：`feat/<topic>`、`fix/<topic>`、`docs/<topic>`，直接对 `master` 开 PR。
- 提交信息：`feat: vX.Y.Z <一句话>` / `fix: <现象> (<根因>)`，中文可以，动词开头。
- PR 请写清：现象 → 根因 → 改法 → 验证命令与输出（贴 `curl` 结果、截图都行）。
- 只改必要的文件；`docs/`、`README.md`、`CHANGELOG.md` 的改动请单独成 PR，方便 review。
- 提交前自查：

```sh
node --check dsh/index.mjs && node --check dsh/client.js
node release-check.mjs      # 语法 + 泄漏 + 版本一致性
```

## 发版流程（维护者） / Release

```sh
# 1. 三处版本同步：package.json version / dsh/index.mjs 的 PLUGIN_VERSION / git tag
# 2. CHANGELOG.md 顶部插入 | vNN | 行
# 3. README 版本 badge 同步
node release-check.mjs
git add -A && git commit -m "feat: vX.Y.Z ..."
git tag vX.Y.Z && git push origin master --tags
gh release create vX.Y.Z --title "mcore vX.Y.Z — ..." --notes "..."
```

面板的「插件升级」按钮靠 GitHub Releases 的 `latest` 判定版本，**漏发 release 等于没发版**。

## 行为准则 / Code of conduct

技术讨论可以很直接，人身攻击不行。隐私是硬红线：贴日志前把路径、机器码、账号、密钥抹掉。