参与 Iris 开发

贡献不一定从修改 runtime 开始。可以先修正一个有依据的文档说明，补齐一个真实使用示例，或在对应领域增加工具。关键是先找到行为的 owner，再选择改动和验证范围。

准备开发环境

从源码仓库根目录执行：

uv sync

需要 Python 3.12 或更新版本。Docker 和 OTel 导出分别按需安装 sandbox、observability extra，不必为了编辑普通工具把所有外部服务都部署起来。新增依赖使用 uv add，同步提交依赖声明与锁文件的必要变化。

模块职责的当前阅读入口是源码地图。

根据目的选择入口

你想做什么	从哪里开始
为自己的应用增加一个工具	工具配方，通常不需要修改 Iris 内核
使用已有扩展点	扩展接口和扩展选择
修改核心运行行为	架构总览 → 源码地图 → 相应契约测试
补回归或理解现有验证	测试与实验
补文档、示例和导航	文档维护

一个正常改动的工作顺序

1. 描述具体触发方式与期望结果。例如“从一个终态 Run 分支后，目标会话应看到该截点历史，而不继承活跃执行状态”。
2. 从公开入口追踪到 owner，读实现与现有测试。不要只依据旧 README 猜测调用关系。
3. 增加能表达行为差异的精准用例，再修改最窄实现位置。
4. 更新同一契约的调用方、测试替身和文档。接口变化默认采用新契约，不补一层仅为旧调用方式服务的探测或别名。
5. 运行相关测试和针对修改文件的规范检查，记录实际通过的范围。

这条流程不要求每个小改动运行全部测试。也不要把输入边界已经完成的校验复制到每个内部函数；所有权、恢复和副作用边界的必要检查则要保留在对应操作处。

代码和提交约定

公开模块、类与方法提供 docstring，中文说明中保留 Google Style 的 Args:、Returns: 等关键字。参数和返回值有类型注解；项目内部导入使用相对路径。日志复用标准 logging，领域错误使用 iris.exceptions 的对应类型。

提交信息包含 subject 和 body，例如：

「docs」(Docs): 补充会话分支使用说明

- 解释终态历史截点与新会话的关系
- 添加可运行示例与相关接口链接

描述具体问题和最终行为，验证部分区分静态核对、执行测试和真实服务运行。不要把未执行的示例或历史实验结果写成本次验证。