# 开发与发布指南

本文供维护者使用。安装与日常审查见 [README](README.md)。

## 本地验证

要求 Node.js 22+、Git、SVN 和 svnadmin。测试只在临时目录创建样本仓库，不修改业务仓库。

	npm ci --ignore-scripts
	npm test
	node scripts/host-smoke.mjs <DSH-checkout>

宿主检查加载真实 DSH 工具运行时，但使用受控模型响应，不是 GUI 安装或真实模型质量测试。Windows SVN 需要支持 UTF-8 路径；CI 使用临时工具，不修改用户安装。

## 会话与模式

服务按DSH session对象隔离缓存和锁，同一会话changes/project两种模式共用互斥锁；不同会话可并行，模型调用与取消由各请求生命周期约束。宿主dispose终止全部会话服务。全项目是跟踪文件的当前源码分批，不是多仓库汇总或跨批次语义分析。

项目捕获最多10000清单节点、1000选择节点、16MiB，不设默认总模型调用次数或执行秒表，初次捕获/复核均遵循宿主与用户取消。SVN项目模式拒绝不支持节点属性，不隐式继承固定历史审查的网络权限。

## 审查预算

除 README 中的文件和输入上限外：

- 采集、导航、命令及模型审查默认不设插件内部秒表；内部API调用者仍可显式指定timeoutMs（0表示无内部截止）。用户/宿主取消仍传播并等待清理。
- 每阶段最多三轮检索；全局最多 50 次读取请求，返回内容累计 256 KiB，单次最多 64 KiB，读取最多 200 行。
- Git 工作区依赖链最多三层、512 个精确路径查询、20 个候选、手动入口与自动依赖共享 1 MiB 正文；文件读取与最终复核共享宿主/用户取消信号。
- SVN工作副本全采集记录命令次数、共享1MiB元数据内存保护，不设默认命令次数或时间截止，含初始/重复采集、导航、属性和末尾验证；cat输出另受16MiB总硬上限约束。历史采集也有独立的元数据与正文内存保护，不以命令次数或时间中断。
- SVN 依赖链最多三层，以精确本地路径和安全正常节点捕获；512 路径、20 候选和上下文。工作副本显式上下文、自动依赖、调用方扫描（含非命中）及关键字BASE核验共享1 MiB来源内存账本与宿主/用户取消信号，不能切换阶段重新获得额度；切换、外部与不支持属性节点拒绝。
- Git 历史依赖链同样最多三层，两侧共享 512 个路径、20 个候选和上下文、1 MiB 正文内存保护和取消信号；只读取固定对象。
- 引用方发现最多四个不重叠的非根目录；128 个候选正文共 1 MiB，目录索引最多 256 条／64 KiB，竞争路径最多 512 个。发现与复核共享宿主/用户取消信号。

达到上限必须阻断或说明未完成，不能静默扩大范围、丢弃证据或重新计时。

## 正式发布

将一次完整需求的代码和文档改动集中完成，再统一执行相关复现、全量测试、提交推送与正式发布；不把同一功能拆成多个细碎发布。未执行的测试和未验收实现必须明确标注。版本格式为 `vX.Y.Z`：X是大版本（重大或不兼容升级），Y是小版本/新增功能，Z是BUG修复；纯修复递增Z，不一律递增Y。已发布标签不移动，发布不自动安装、升级或重启宿主。

1. 修改版本号与锁文件；更新 [变更记录](CHANGELOG.md) 和 [发布说明](RELEASE-NOTES.md)。
2. 完成测试、差异检查和独立安装验证后，提交、推送，并创建对应 vX.Y.Z 标签。标签一旦进入发布流程就不再移动。
3. 等待标签 CI 的 Ubuntu/Windows × Node.js 22/24 四组测试全部成功。
4. 在 Actions 的 CI 工作流选择该标签，设置 publish: true，并将 ci_run_id 填为第3步成功的push标签CI运行ID，仅触发一次正式发布。发布不再重复四矩阵；先核验同仓库/工作流/标签/提交/当前attempt及四组npm test成功证据，缺失或变化直接失败。
5. 发布任务打包一次、验证安装、保存安装包，再发布 npm。随后下载 npm 实际安装包，检查它与保存的原包是否一致。
6. 核验通过后，把同一安装包与 SHA256SUMS.txt 附到 GitHub Release，并使用发布说明作为正文。
7. 下载 Release 的实际附件，与原包逐字节比较，核验 SHA-256、SHA-512 及校验清单。

需要仓库 Secret NPM_AUTOMATION_TOKEN。普通标签测试不会发布，普通分支推送也不会触发这套 CI。

## npm 已成功，但 Release 失败怎么办

**不要再次 npm publish，不要重新打包，不要移动标签。**

先检查原发布任务中的保存工件和日志。注册表元数据存在不代表安装包已经可下载；等待实际安装包可读，并与原包核验。恢复工作流只能下载原运行的安装包、验证固定提交及校验值，然后补建 Release。

若原包缺失或实际字节不一致，不得宣称该版本正式交付。

## 文档写作约定

- 使用者文档先回答用途、操作和结果，不从内部字段或测试编号开始。
- 新术语首次出现就解释。状态名保留英文时，同时写出中文含义。
- 变更记录写用户能感受到的变化；流水线日志和长哈希不是功能介绍。
- 能力清单区分实现、验证与发布，不能把“读过参考源码”写成“功能已完成”。
- 不保留逐轮过程记录，不把小样本观察说成总体质量成绩。