tg-opencode

🚀 TG OpenCode Agent

通过 Telegram 远程驱动本机 OpenCode 的私人 Coding Agent。 手机发消息 → Telegram Bot → 本地任务队列 → OpenCode 执行 → 结果回传手机。

---

✨ 特性

• 📱 手机远程 Coding Agent — 消息 / 文件直接交给 opencode 执行，结果自动分段回传
• 🧠 会话记忆 — 自动续接上次会话，多轮连续干活；/attach 可续接电脑上任意会话（含 OpenCode Desktop）
• 📋 任务队列 — 单 worker 串行执行，排队 / 取消 / 状态查看，支持短编号 #N
• 🔄 进程树管理 — Windows taskkill /T 递归终止，取消或崩溃不残留 opencode / MCP 子进程
• 🎛 模型切换 — /models 实时列出可用模型（分组 + 编号），/model 一键切换
• 🔐 安全设计 — 用户白名单（默认拒绝所有）、会话/任务归属隔离、文件路径清洗防穿越
• 🛡 工程化 — 原子 state 写入 + 损坏自动备份、单实例锁、全局错误兜底、异常路径进程清理
• 💰 零付费 — 纯本地运行，无第三方服务；长轮询模式，无需公网 IP / 服务器

---

📐 架构

┌────────────┐        ┌──────────────────────────────────────────────┐
│  Telegram   │  Bot  │              你的电脑（本地）                    │
│  手机/桌面   │ ←API→ │                                                │
└────────────┘        │  bot.py ── python-telegram-bot（长轮询）        │
                      │      │                                          │
                      │      ▼                                          │
                      │  TaskManager（asyncio.Queue + 单 Worker）        │
                      │      │                                          │
                      │      ▼                                          │
                      │  opencode run --format json（子进程）             │
                      │      │                                          │
                      │      ▼                                          │
                      │  MCP 能力（ida-pro-mcp / frida / chrome-devtools）│
                      └──────────────────────────────────────────────┘

• bot.py — Telegram 网关：全部命令、权限、会话管理、消息分段
• task_manager.py — 任务队列：串行执行、取消（进程树终止）、shutdown 收敛
• tests/ — 45 个单元测试（零 token、零真实 Telegram），集成测试可用 RUN_INTEGRATION=1 开启

---

🚀 快速开始

⏱ 约 5 分钟，全程本地，无需服务器。

0. 前置要求

依赖	版本	说明
Python	≥ 3.10	开发环境建议 3.12
Node.js + npm	≥ 18	安装 opencode CLI
Telegram 账号	—	用于创建 Bot

1. 创建 Telegram Bot（2 分钟）

1. 在 Telegram 里找到 @BotFather，发送 /newbot
2. 按提示设置 Bot 名称和用户名（如 @MyCodingBot）
3. BotFather 会给你一个 Token（形如 123456789:AAHxxxxxxxxxxxxxxxxxxxx）——妥善保存，不要泄露

2. 安装 opencode CLI

npm install -g opencode-ai
opencode --version   # 验证安装

opencode 的模型凭据、MCP 配置（ida-pro-mcp / frida / chrome-devtools 等）会直接复用你本机已有的 opencode 配置，无需重复设置。

3. 安装本项目

git clone <你的仓库地址> tg-opencode
cd tg-opencode

# 创建虚拟环境并安装依赖
python -m venv venv
venv\Scripts\python -m pip install -r requirements.txt

4. 配置

copy .env.example .env

用编辑器打开 .env，至少填写两项：

# 必填：你的 Bot Token
BOT_TOKEN=123456789:AAHxxxxxxxxxxxxxxxxxxxx

# 必填：你的 Telegram 数字 ID（从 @userinfobot 获取）
# 留空 = 拒绝所有用户
ALLOWED_USER_IDS=123456789

OPENCODE_CMD 可以留空——程序会自动从 PATH 查找 opencode。

5. 启动

venv\Scripts\python -u bot.py

看到 Bot gateway 已启动 后，手机给 Bot 发一条消息试试：

📥 任务已提交 ID: t_3f8a2c1
⏳ 正在执行，请稍候…
（opencode 处理中…）
<opencode 的回复>

🎉 完成！ 你现在拥有一个手机遥控的私人 Coding Agent 了。

6.（可选）开机自启

Windows 使用任务计划程序（或参考 run_bot.bat 手动启动脚本，含防双开）：

# 以普通权限注册开机自启（登录时启动）
$action = New-ScheduledTaskAction -Execute "<项目绝对路径>\run_bot.bat" -WorkingDirectory "<项目绝对路径>"
$trigger = New-ScheduledTaskTrigger -AtLogOn -User "$env:USERNAME"
Register-ScheduledTask -TaskName "tg-opencode-bot" -Action $action -Trigger $trigger

---

⚙️ 配置详解（.env）

变量	必填	默认	说明
BOT_TOKEN	✅	—	Telegram Bot Token（@BotFather 获取）
ALLOWED_USER_IDS	✅	空=拒绝所有	允许使用 Bot 的 Telegram 数字 ID，逗号分隔
ADMIN_USER_IDS	—	=白名单	管理员 ID，可查看电脑端(Desktop)会话
OPENCODE_CMD	—	PATH 自动查找	opencode 可执行文件路径
OPENCODE_MODEL	—	opencode 默认	默认模型，格式 provider/model
OPENCODE_WORKDIR	—	当前目录	任务工作目录
OPENCODE_TIMEOUT	—	600	单任务超时秒数

---

💬 Bot 命令一览

命令	说明
直接发消息 / 发文件	交给 opencode 执行（自动续接上次会话）；文件自动下载分析（≤20MB）
/help	命令帮助
/status	查看当前配置（模型 / 目录 / 会话 / PID）
/new	重置会话（开启新任务）
/sessions [N|--all]	列出会话（📱手机 / 💻电脑 + 消息数）
/attach <ID>	续接任意会话（支持短前缀，如 ses_00f51fce）
/history [N]	回看当前会话最近 N 条对话
/tasks [N]	我的任务列表（状态 + 耗时，短编号 #N）
/cancel <编号或ID>	取消任务（运行中=进程树终止；排队=直接取消）
/models	列出可用模型（免费组 / Go 组 + 编号 + 当前标记）
/model [编号或名称]	查看 / 切换模型（/model opencode-go/glm-5.2）
/workdir [路径]	查看 / 切换工作目录
/stats	token 用量与费用统计

使用小贴士

• 任务编号是动态生成的：取消前先 /tasks 确认当前编号
• 长回复自动分段发送（每段 ≤4000 字符）
• 任务期间可随时 /cancel，排队任务直接取消、运行中任务强杀进程树

---

🧪 测试

# 默认单元测试：零 token、零真实 Telegram、零真实 opencode
venv\Scripts\python -m unittest tests.test_task_manager -v

# 集成测试：真实 opencode 进程树清理验证（需本机 opencode CLI）
$env:RUN_INTEGRATION = "1"
venv\Scripts\python -m unittest tests.test_task_manager

---

❓ 常见问题

Q: 没有公网 IP 能跑吗？ 能。Bot 使用长轮询（long polling）主动向 Telegram API 拉取消息，不需要公网 IP、端口映射或服务器。

Q: 手机发的任务在电脑上执行吗？ 是的，所有任务都在运行 bot.py 的那台电脑上执行（终端命令、文件读写、MCP 工具）。

Q: 能看到电脑上的 opencode 会话吗？ 能。Bot 与电脑共用同一个 opencode 数据目录，/sessions 会列出全部会话并标注来源（📱手机 / 💻电脑）。

Q: 换模型后任务失败了？ 确认模型格式为 provider/model（用 /models 查看真实可用列表），或 /model opencode-go/deepseek-v4-flash 切回默认。

Q: 任务一直在排队？ 单 worker 串行设计，一次执行一个任务。队列上限 50，用 /cancel 取消排队中的任务释放容量。

Q: 文件发送失败 / 提示超过 20MB？ Telegram Bot API 下载上限 20MB，更大的文件请放到电脑本地后让 agent 直接访问路径。

---

⚠️ 已知限制

• 任务记录保存在内存（Bot 重启后丢失），state.json 仅持久化用户配置与会话映射
• 单 worker 串行执行（一次一个任务，其余排队）
• 文件上传上限 20MB（Telegram Bot API 限制）
• 任务编号动态生成，列表刷新后可能变化

🛠 技术要点（给贡献者）

• 任务取消：cancel_event（asyncio.Event）双字段同步 + 启动前后双重检查，杜绝"已取消仍启动"
• 进程清理：taskkill /PID /T /F 递归终止 + cleanup_process 统一收尾（kill → wait → 释放引用）
• 状态写入：临时文件 + os.replace 原子替换，损坏自动备份 state.json.corrupt.<ts>
• 会话隔离：bot_sessions 归属推导 + 管理员可见电脑会话；任务按 user_id 过滤
• 安全：参数化 SQL、文件名清洗 + realpath 防穿越、白名单默认拒绝

📄 许可

MIT © 2026

免责声明：本项目仅供个人与学习用途。使用前请遵守 Telegram 服务条款、模型提供商条款及所在地区法律法规。