# 开发与验证

本项目在 `C:\Users\tanos\OneDrive\Document\项目\chatsync` 持续维护，具体约定见 `AGENTS.md`。

## 发布要求

每次发布先更新 `package.json` 版本，并在 `CHANGELOG.md` 添加 `## 版本号 · YYYY-MM-DD` 格式的中文日志，记录实际变化、升级注意事项及验证情况。完成下述验证后，提交源码并推送对应的 `v版本号` 标签。

标签触发的发布流程会先检查版本和日志，再运行测试并发布 npm，最后创建或更新 GitHub Release，将对应版本日志写入正文并上传完整源码 ZIP（含受版本控制的测试和文档）。日志缺失会阻止发布。手动重试时必须选择对应版本标签；npm 已存在的版本会跳过 npm 发布，继续补齐 Release。发布后核实正文和源码附件均可访问。

## 更新日志写法

面向插件使用者写更新日志。先回答「这次更新最值得关注什么」，再说明使用变化、升级注意和实际验证范围。GitHub Release 正文沿用该版本日志。

- 保留版本标题 `## 版本号 · YYYY-MM-DD`，下一行用一句话概括本版重点，避免「全面升级」「更加稳定」等没有具体依据的表述。
- 重点通常选 1–3 项，按用户影响排序，以 **简短结果标题** 开头，再用一两句说明具体场景和变化。小版本只有一项变化就写一项，不为凑格式增加内容。
- 其余有用户影响的修复可合并为一条「其他改进」。纯内部重构、文档文件清单和维护过程不逐项罗列；仅维护类版本说明实际维护变化即可。
- 正文使用用户能理解的名称，如「会话」「项目文件」「桌面端」。服务名、函数名、接口路径、脚本名、锁和缓存的实现细节留在开发文档或验证记录中；包名、命令、格式名等只有在用户确实需要据此操作或判断兼容性时才保留。
- 「升级注意」只写本版新增或改变的操作、默认值和兼容性影响；没有变化时可省略，不重复安装教程及每版都相同的密钥、依赖说明。
- 「验证」用一两句说明本版实际检查范围和与本次变化相关的重要未验证项，链接详细记录。测试数量、环境完整版本和工具错误留在记录中；不得把自动测试写成实机验收，或省略影响判断的验证限制。
- 历史日志不自动套用新格式重写；需要改写时只调整表达，保留该版本事实及当时的验证边界。

可参考 [0.20.0 表达示例](docs/changelog-example.md)。推荐结构如下，按实际改动删减条目：

```markdown
## 版本号 · YYYY-MM-DD

一句话说明本版重点。

- **重点变化。** 在什么场景下，现在有什么改善。
- **另一项重点。** 用户会看到什么变化。
- **其他改进。** 简述其余有用户影响的修复。

**升级注意：** 本版需要用户留意的变化。

**验证：** 实际检查范围；必要的未验证项。[详细记录](文档相对路径)
```

## 源码与安装包边界

Release 的源码 ZIP 由 `git archive` 打包对应标签下全部受版本控制的文件，与 `package.json` 的 `files` 无关；不包含 Git 历史、依赖或仓库外脚本。npm 包仅包含 `files` 选定内容及 npm 自动包含的包元数据等文件，不包含 `tests/`、`patch-version-agnostic-test.mjs`、`scripts/check-dsh-host.mjs`、`scripts/check-dsh-sessions.mjs` 或发布脚本。下述开发验证及验证记录中的检查命令应在 clone 或解压源码 ZIP 后运行，不能直接在 npm 安装目录运行 `npm test`。

保留随包提供的历史验证记录，以保证 README 的相对链接可用；这些记录不作为当前版本的新增验证结论。调整 `files` 时检查 `npm pack --dry-run` 的实际文件列表和随包文档的相对链接。

## 验证

需要 Node.js（建议 24）和 Git。项目采用原生 ESM，无运行时 npm 依赖，无需构建。

```sh
git clone https://github.com/dpskk2/dsh-chatsync.git
cd dsh-chatsync
npm test
npm pack --dry-run
```

`npm test` 验证仓库连接和同步偏好的加载 / 保存 / 失败交互、配置校验、自动调度、私有仓库校验、本地 Git 多副本双向恢复与故障重试，以及补丁应用的内容比对行为。界面测试使用隔离的宿主与 React 钩子替身；引擎集成测试在临时目录使用真实 Git。测试不连接真实 GitHub 或用户数据，不能替代真实 DSH 的挂载与双机验收。

历史同步引擎回归脚本目前部分位于作者的仓库外工作目录，不包含在普通 clone 中，不能宣称完整引擎测试已在仓库 CI 覆盖。后续应将这些测试移入仓库并移除机器路径依赖。

修改文案或功能时，保持中文 README、英文 README、配置参考与实际默认值一致；变更同步行为需在临时数据目录及本地测试远端验证，显式设置 `autoRepo: false`，避免访问真实同步仓库。

发布前至少在两台测试环境完成：A 上传 → B 取回 → B 新增 → A 取回；同时检查工作区、凭据排除、故障提示和重启后的模式。平台与 DSH 版本只记录实际验证过的组合。