跨仓库OpenCode集成 - 研究摘要

技术研究人工智能 OpenCode

❌ 明确不支持的功能： - 任务完成回调钩子（、） - 进程状态查询 API - 程序化触发会话 - 跨进程事件广播机制 - 内置 Webhook 通知 ⚠️ 有限支持的功能： - 命令返回退出码（0=成功，非0=失败） - 提供 HTTP API（但不支持状态查询） - Plugin 系统（但无生命周期钩子）

可行性结论

结论: ✅ 可行（需变通方案）

OpenCode 原生不支持跨仓库集成所需的进程管理 API 和生命周期钩子，但可以通过包装器脚本或外部协调机制实现完整的跨仓库自动化流程。

可行性等级

方案	可行性	实施周期	复杂度
方案B1 - Shell 包装器	✅ 完全可行	1-2 天	低
方案B2 - 文件信号机制	✅ 完全可行	3-5 天	中
方案B3 - 消息队列	✅ 完全可行	1-2 周	高
方案A - 原生集成	❌ 不可行	N/A	N/A

研究目标

解决以下跨仓库自动化场景的核心问题：

业务场景：

仓库A（Telegram Bot）接收用户发送的 /research <主题> 命令
仓库A触发仓库B执行 OpenCode 研究任务
仓库B完成研究并将结果提交到 GitHub
核心问题：如何自动感知任务完成并执行后续操作（进程清理或新会话）

核心发现

1. OpenCode 原生能力评估

❌ 明确不支持的功能：

任务完成回调钩子（onComplete、onFailure）
进程状态查询 API
程序化触发 /new 会话
跨进程事件广播机制
内置 Webhook 通知

⚠️ 有限支持的功能：

opencode run 命令返回退出码（0=成功，非0=失败）
opencode serve 提供 HTTP API（但不支持状态查询）
Plugin 系统（但无生命周期钩子）

2. 推荐实施方案

主要推荐：方案B1 - Shell 包装器 ⭐

┌─────────────────────────────────────────────────────┐
│                   实施架构                           │
├─────────────────────────────────────────────────────┤
│  仓库A (Telegram Bot)                               │
│  ├─ 接收 /research 命令                             │
│  ├─ 解析研究主题                                    │
│  └─ 执行: ssh server "bash repo-b/wrapper.sh 主题" │
├─────────────────────────────────────────────────────┤
│  仓库B (Research)                                   │
│  ├─ research_wrapper.sh                             │
│  │  ├─ 执行: opencode run "主题"                    │
│  │  ├─ 捕获退出码 ($?)                              │
│  │  ├─ 发送 Telegram 通知                           │
│  │  ├─ 清理进程 (pkill)                             │
│  │  └─ 可选: 启动新会话                             │
│  └─ 自动提交 GitHub                                 │
└─────────────────────────────────────────────────────┘

核心优势：

✅ 实施周期短（1-2天）
✅ 无额外依赖（仅需标准 Linux 工具）
✅ 可靠性足够（适用于中等并发量）
✅ 易于调试和维护

3. 备选方案适用场景

场景	推荐方案	理由
单个/少量任务	B1	简单高效
5+ 并发任务	B2	避免进程冲突
任务执行>30分钟	B2	避免 SSH 超时
企业级/高可靠	B3	消息持久化
多消费者通知	B3	Redis Pub/Sub

目录结构

文件	内容摘要
01-需求拆解	用户目标分析、关键路径识别（3大技术障碍）、约束条件（OpenCode限制、业务需求）
02-核心能力验证	OpenCode API 详细分析、能力差距评估、黑盒测试建议
03-解决方案设计	3种方案对比（B1/B2/B3）、架构图、决策矩阵、实施路线图
04-实施指南	完整配置步骤、4个可直接使用的代码片段、部署清单、故障排除

快速开始（5分钟部署）

步骤1：环境配置（2分钟）

# 设置环境变量
export TELEGRAM_BOT_TOKEN="your-bot-token"
export TELEGRAM_CHAT_ID="your-chat-id"
export REPO_B_PATH="/path/to/repo-b"

步骤2：创建包装脚本（2分钟）

将 04-实施指南中的 research_wrapper.sh 复制到仓库B目录。

步骤3：测试运行（1分钟）

cd $REPO_B_PATH
bash research_wrapper.sh "帮我调研电动车行业的现状"

步骤4：集成到 Telegram Bot

在仓库A的 Bot 代码中调用：

subprocess.run(
    ['bash', f'{REPO_B_PATH}/research_wrapper.sh', research_topic],
    timeout=3600
)

关键成功因素

进程管理：使用 timeout 命令防止任务无限执行
错误处理：捕获退出码并区分超时/失败/成功
通知机制：Telegram API 简单可靠，适合此场景
日志记录：详细的日志便于排查问题
并发控制：使用锁文件防止任务冲突

风险评估

风险	可能性	影响	缓解措施
opencode 进程未清理	中	中	使用 `pkill -f` 强制终止
Telegram API 限流	低	低	添加发送延迟和重试
研究任务超时	中	中	配置合理的 timeout 值
并发任务冲突	低	高	使用锁文件机制
SSH 连接中断	低	中	使用 nohup 或迁移到方案B2

下一步行动

立即执行（本周内）

部署方案B1（Shell 包装器）到测试环境
配置 Telegram Bot 和通知
进行3-5次完整流程测试
收集日志并优化超时参数

短期优化（本月内）

添加监控和告警（Prometheus/Grafana）
实现任务队列（防止并发冲突）
评估是否需要升级到方案B2/B3
编写运维文档

长期规划（视需求）

向 OpenCode 提交功能请求（原生支持 lifecycle hooks）
评估迁移到 OpenCode Server Mode
考虑容器化部署（Docker/K8s）

核心参考文献

官方文档

OpenCode CLI Documentation - CLI commands and flags
OpenCode Server Mode - HTTP API for automation
OpenCode Plugins - Plugin system documentation
Telegram Bot API - sendMessage endpoint reference

技术实现

Node.js Child Process - spawn, exec, fork API documentation
Shell Exit Codes - Linux exit code conventions
Redis Pub/Sub - Message queue implementation guide
Python Watchdog - File system monitoring library

社区资源

Does OpenCode Support Hooks? - Community analysis of OpenCode extensibility
Telegram Bot Tutorial - Getting started guide

研究完成时间: 2026-02-18
建议复审周期: 每季度或在 OpenCode 重大版本更新后
相关项目: OpenCode CLI v1.x, Telegram Bot API, Node.js/Python 运行时