# 贡献与验证流程

本项目为 DSH 提供会话内可编辑草图与原生 Agent 协作。保持 DSH 固定版本兼容；提出新的模型能力时，同时说明使用场景与验收方法。

## 小步开发

1. 从最新 `main` 建立独立分支，一个 PR 处理一个相关问题。
2. 修复缺陷时先添加能够复现问题的测试；重构时保持外部协议与现有行为，补测受影响的边界。
3. 不升级无关依赖、不提交凭据、个人会话、构建产物或浏览器登录地址。复用代码保留来源和许可证。
4. 执行 `pnpm run typecheck`、`pnpm test`、`pnpm run bundle`、`pnpm pack`，检查 `git diff --check`。新增运行依赖需更新 lockfile 与许可清单。
5. 发起 PR，说明问题、改动、验证证据与未验证范围，待 GitHub CI 通过后审阅合并。

## 边界与扩展

- 场景、图片、RPC 大小和超时使用 `src/core/limits.ts` 的公共常量。保持该模块不依赖 Node 或浏览器 API，以供 iframe、客户端与宿主共享。
- 修改限制时，检查契约校验、导出、HTTP 接收与客户端超时的配套关系，更新 README 和边界测试。模型路由、协议版本与存储格式的变化应单独评审。
- 保存继续遵守会话生命身份、revision 和 mutationId 约束；建议只作为用户可确认的输入，不自动执行或提交。

## 验证证据

更改 UI、会话绑定、附件桥或宿主生命周期时，在专用本地 Web profile 执行 `pnpm run test:browser`；准备方式见 `docs/validation.md`。构建包还应在干净 profile 中验证安装与移除。

模拟模型测试只能证明请求和解析契约。真实 AI 功能验收需使用有效 DS 配置，明确记录路线、场景和结果；不上传凭据。未实测的模型效果、平台或宿主状态应继续标为待验收。

验证记录按日期和改动追加，保留已有记录，避免把一次测试扩大为全平台兼容声明。提交材料使用实测数据，披露 AI 辅助开发和第三方复用。

## 原生集成与性能改动

优先公开 Slot/hooks、主题事件、会话与原生输入/附件动作；固定版适配保留明确边界，不以 DOM 劫持或模拟发送替代宿主接口。UI/通信优化补跑 `pnpm run test:browser:native`，批注链路补跑 `pnpm run test:browser:comments`。

原生 Agent 工具或批注同步改动补跑 `pnpm run test:browser:agent`，覆盖失败刷新、响应丢失重试、读取/写入交错和通知断线。模型夹具仅用于隔离 profile，不能代替真实模型验收。

修改提议或选区协作变更补跑 `pnpm run test:browser:edits` / `pnpm run test:browser:focus`，检查确认前不写入、旧版本拒绝、原生撤销、丢失响应重试、恢复快照下载及真实原生框选。跨表 receipt 必须有恢复路径，不能声明未实现的事务或跨刷新撤销历史。

视觉参考或图片工具变更补跑 `pnpm run test:browser:visual`，检查原生 image block、版本/选区隔离、缺图/过期拒绝、缓存与丢失确认重试；实际退出重启后检查持久化及关闭画板读取。Windows 与真实模型验收使用 [0.3.2 清单](docs/windows-acceptance-v0.3.2.md)，脚本模型不得作为真实语义或 Token 节省证据。

声称性能收益时使用 `pnpm run test:performance` 与相同场景/视口/采样条件，并保留原始数据与安装包客户端核对。隔离测试覆盖层应复制到安装 profile 内，避免从源码路径解析到其他版本；不得提交登录地址或个人会话。参见 `docs/native-integration.md`。