贡献流程
需求
贡献应聚焦一个可验证问题，并包含代码、测试和受影响文档。不要在同一变更中混入无关重构，也不要把规划能力写成已实现事实。
提交前请准备：
- 问题复现或明确需求；
- 受影响组件与版本；
- 最小修改范围；
- 对应自动化测试或真实环境验证记录；
- 协议、配置、命令、UI 或扩展点变化对应的文档更新。
架构
按组件边界分配修改：
| 变更 | 主要位置 | 必须联动检查 |
|---|---|---|
| 模型 Provider | agent-core/src/main/llm/ | 配置、路由、提示工具格式、UI |
| TriggerAdapter | agent-core/src/main/trigger/ | TriggerSource、wiring、事件测试 |
| 本地工具 | Agent Core Schema 与 handler | 工作区合并、权限、副作用 |
| Java 工具 API | adapter-java/.../api/ | 附属模组兼容、Fabric entrypoint |
| Bedrock 工具 | adapter-bedrock/src/tools/ | LSE 构建输出、目录扫描、BDS 验证 |
| 通信协议 | shared / Agent Core / 两个 Adapter | 握手、注册、单次与批量调用 |
| 用户可见行为 | 对应源码 | web/pages/ 文档 |
执行
1. 建立基线
- 从最新目标分支创建功能分支。
- 记录修改前可复现步骤和日志，但移除 token、API Key、QQ 账号与用户数据。
- 先运行目标包现有测试，区分基线失败与本次回归。
2. 实现
- 遵循当前目录的代码风格和类型；
- 使用现有依赖，新增依赖前说明必要性；
- 工具名、Provider id、TriggerSource 与协议 method 避免冲突；
- 高风险世界写入、外部消息和持久化操作需要明确权限与副作用；
- 扩展点变更保持最小，不为单次需求创建新的插件框架。
3. 验证
按测试与调试执行目标包检查。至少记录：
- 运行的命令；
- 自动化测试结果；
- 真实 Electron/Fabric/BDS 环境是否验证；
- 未验证项及原因；
- 协议兼容边界。
4. 更新文档
出现以下变化时更新用户文档：
- 构建环境、依赖版本或命令；
- Java entrypoint 或公开 API；
- Bedrock 工具目录、接口或运行环境；
- Provider、TriggerAdapter、本地工具或 skill wiring；
- 协议字段、方向、错误或批量行为。
文档只陈述当前源码与测试能够证明的内容。动态工具数量、模型列表和性能数据不得写成固定承诺。
5. 提交评审
变更说明建议包含：
问题：为什么需要修改
方案：修改了哪些边界
验证：执行了哪些命令和运行时场景
兼容性：协议/API/数据是否变化
文档：更新了哪些页面
限制：仍未覆盖什么评审重点是正确性、兼容性、安全与可验证性，而不是变更行数。
完成标准
- 目标包构建和测试通过；
- 运行时能力在需要的真实环境验证；
- 不记录或提交密钥和用户数据；
- 新增工具有 Schema、执行处理和失败路径；
- 协议修改同步更新所有受影响端；
- 用户文档链接与 MDX 生产构建通过。