04 贡献流程与风格规范

04 贡献流程与风格规范

本节摘要:这是全书正文的最后一节,把「读懂」推向「能改」。当你想给 OpenCode 贡献代码——加 Provider、加工具、改内核——该遵循什么?本节讲贡献流程与风格规范:加 Provider 走哪几步、加工具符合什么契约、改内核守哪些依赖铁律、测试要求。读完本节,你就能从读者变成参与者。

一、贡献的前提:先读懂

贡献的第一步不是写代码,而是确保你读懂了相关部分。具体说:

• 加 Provider → 读懂第 6 章(LLM 抽象层)
• 加工具 → 读懂第 5 章(工具系统)
• 改会话核心 → 读懂第 7、8 章
• 改权限 → 读懂第 4 章
• 改客户端 → 读懂第 13 章前三节

读懂的标准是「能向别人讲清楚现状」。因为贡献是「在现有架构上加东西」,不理解现状就加,容易破坏一致性。

二、加 Provider 的流程

加一个新 Provider(模型厂商)是常见贡献。流程大致:

1. 确认该 Provider 用哪种协议(已有 or 新建)
   │
   ├─ 已有协议(如 openai-compatible-chat)
   │   └─ 只需加 Route(端点+认证),5-15 行
   │
   └─ 新协议
       └─ 写新协议模块(构造请求体 + 解析流)
       │
2. 加 Provider 配置(门面)
   │
3. 加测试(provider fixture + 录像带测试)
   │
4. 提交
​

大多数 Provider 用已有协议(很多家用 openai-compatible-chat),只需加 Route,很简单。只有真正新协议的 Provider 才需要写协议模块。

💡 加 Provider 的「5-15 行」:第 6 章说的「加一个新部署只要 5-15 行」不是夸张——如果用已有协议,真的就是这么少。这是 LLM 抽象层分层带来的红利。

三、加工具的流程

加一个新工具(内置或自定义):

1. 决定工具类型
   ├─ 内置工具(进内核) ──► 改内核,符合工具定义抽象(第 5 章)
   └─ 自定义工具(项目级) ──► 放项目目录,动态导入(第 11 章)
   │
2. 定义工具(标识 + 参数 Schema + 执行函数)
   │
3. 处理横切(参数校验、截断、追踪会被自动加,你只写 execute)
   │
4. 配权限默认规则(第 4 章)
   │
5. 加测试
​

关键点:你只写业务逻辑(execute 函数),横切关注点(校验/截断/追踪)系统自动加(第 5 章 01 节)。不要自己 reimplement 这些。

四、改内核的铁律

改内核(领域核心层)时,第 2 章的依赖铁律是硬约束:

• 依赖只能自下而上,下层绝不 import 上层
• 模式层不依赖数据库/运行时/任何上层
• 同层内允许互相 import

提交内核改动的 PR,如果违反依赖方向,基本会被要求改到合规。代码评审里这是一票否决项。

⚠️ 别图方便反向依赖:改内核时可能觉得「这里 import 上层方便」,但这是病毒——一次反向依赖会污染整个依赖图。宁可多写点,也别违反铁律。

五、测试要求

OpenCode 有浓厚的测试文化。贡献代码通常要求带测试:

特别说录像带测试——它录一次真实的模型调用(或工具执行),保存响应,之后测试时重放这个响应(不再真调)。这让你能稳定测试「涉及外部依赖」的逻辑,不依赖网络和真实模型。

六、风格规范

除了架构铁律,还有些代码风格规范:

• TypeScript + ESM:源码是 TS、ESM,贡献代码要一致。
• 效应式风格:业务逻辑用 Effect 组织(生成器、Layer、Service),和现有代码风格一致。
• 命名/注释:遵循现有惯例。
• 中文/多语言:README 等支持多语言,贡献文档可能要考虑。

最稳的做法是先读几段相关现有代码,模仿其风格——不要把别处的风格带进来。

七、提交与评审

写完代码、加完测试后,提交 PR。评审会看:

• 功能正确性(测试覆盖)
• 架构合规(依赖方向、风格)
• 文档/注释是否更新
• 是否破坏现有行为

评审反馈后迭代,直到合并。这是开源协作的标准流程。

八、第 13 章收尾:从读者到参与者

读完第 13 章四节,你完成了从「读懂」到「能改」的转变:

这是全书正文的终点。从第 1 章「跑起来」,到第 2 章「看懂架构」,到第 3~12 章「逐子系统拆解」,到第 13 章「能改」——你走完了从使用者到参与者的完整旅程。

本节要点回顾

1. 贡献前提是读懂:相关章节先读懂,「能讲清现状」再改。
2. 加 Provider:大多用已有协议只加 Route(5-15 行),新协议才写协议模块。
3. 加工具:只写 execute 业务逻辑,横切系统自动加;配权限默认+测试。
4. 改内核守依赖铁律:自下而上、模式层纯净、一票否决。
5. 测试文化:单元+录像带(recorded,重放真实响应)+端到端。
6. 风格规范:TS+ESM+效应式,模仿现有代码风格。
7. 第 13 章结束:你已从读者变参与者——全书正文到此完成。

全书十三章正文到此结束。附录 A 是检索型参考,可随时查阅术语、命令、报错排查。