# 贡献指南

欢迎提交缺陷报告和改进。较大的行为调整请先通过 Issue 描述具体场景、预期结果和取舍。

## 本地检查

使用 Node.js 22.19.0 或更高版本：

```sh
npm ci
npm run check
```

`check` 包括类型检查、行为测试、构建和运行入口检查。修改宿主接入或客户端交互时，还需在目标版本 Harness 的隔离 profile 中验证实际加载、设置保存和交互；不要把 Mock 结果当成真实模型验收。

开发依赖固定在最低支持版本 `0.2.0-rc.2`；CI 同时检查该版本和 `0.2.1-alpha.1`。安装兼容声明使用范围，开发依赖的精确版本用于可复现验证。扩大范围前应检查边界版本，更新回归矩阵；不要只通过修改版本声明跳过接口验证。

## 修改范围

- 保持改动聚焦，避免无关重构和新依赖。
- 代码注释使用中文；对复杂边界解释原因，避免复述代码。
- 修改调度、状态或异步行为时，增加能复现问题的针对性测试。
- 依赖升级需同时核查 SDK 类型、公开扩展点、安装兼容检查和实际宿主行为。
- 修改用户可见行为时同步更新 README 和设计文档。
- 保留第三方代码所需的版权与许可证声明。

## 问题反馈与 PR

问题报告应包含 Harness 版本、操作系统、profile、插件版本、复现步骤及预期结果。PR 应说明具体问题、改动后的行为、验证方法和尚未验证的边界。

不要提交 API Key、认证令牌、私人会话、个人路径或用户配置。验收 fixture 只能使用虚构数据和无外部副作用的工具。`.scratch/` 为本地任务记录，不随安装包发布。