1. 开发环境
当前官方开发文档要求现代 Node（22.19+ / 24+ 等受支持线）、Corepack 管理的 pnpm，并通过 workspace 构建 Host 与 Client 包。源码仍在快速迭代，因此学习时应以你 checkout 的版本为准。
2. 修改代码前先判定你改的是哪种层
| 需求 | 优先位置 |
|---|---|
| 新模型 | LLM provider plugin |
| 新模型工具 | ctx.tools plugin |
| 工具权限策略 | tools/* listener |
| 新持久化后端 | session persistence provider |
| 只影响一个 agent | agent scoped context / preset |
| 改变 turn/step 定义 | 最后才考虑 agent-loop |
3. 调试调用链
- 先用配置 dump 确认插件真的挂载。
- 确认 service provider 是否 active。
- 确认 scoped context 下能否解析该 service/tool。
- 看 session event 是否出现预期边界。
- 最后才看 LLM wire。
4. 测试思路
对 Harness 最有价值的不是端到端聊天截图，而是生命周期与不变量测试：插件卸载是否撤销注册、同 session id 并发 publication 是否只有一个成功、tool result 是否与 call 同 step、取消后是否还有 continuation 发布状态。