关于 interactive-bot
为 Gmail Commander Telegram 机器人的使用与代码维护提供说明，面向负责操作或修改该机器人的开发者。涵盖 Gmail 命令、自由文本 Agent 路由及运行安全约束。
主要功能
- 01Gmail 邮件斜杠命令
- 02自由文本 Agent 路由
- 03Gmail MCP 工具调用
- 04并发、超时与熔断控制
- 05Telegram 用户授权校验
适用场景
- 01查看和搜索 Gmail 收件箱
- 02撰写、回复及管理草稿
- 03通过自然语言请求邮件操作
MCP 相关
自由文本消息通过 Agent SDK 路由，并调用 4 个 Gmail MCP 工具：列出、搜索、读取和草拟邮件。
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/interactive-bot确认已加载。
附带文件references/evolution-log.md
详细介绍
交互式机器人
Gmail Commander Telegram 机器人——使用斜杠命令访问邮件，并通过 AI 路由自由文本。本技能说明机器人的功能及其代码所在位置；运行中的机器人如何操作，请参阅 bot-process-control。
自我演进的技能：本技能会在使用过程中不断改进。如果说明有误、参数发生偏移，或需要采用变通方法，请立即修正此文件，不要拖延。仅针对真实、可复现的问题进行更新。
运行位置
机器人运行在一台始终开机的 Mac mini 上的私有 Restate 租户中。该租户从 scripts/bot.ts 导入 buildBot()，拥有自己的持久化 Telegram getUpdates 链，并将每次更新传递给返回的 grammY 机器人，调用 bot.handleUpdate() 处理。没有工作站守护进程；笔记本上的 launchd 任务已于 2026-09-24 停用。
不要直接使用生产机器人的令牌启动 scripts/bot.ts 来“测试”。Telegram 对每个令牌只允许一个 getUpdates 消费者，因此第二个轮询器会因 409 Conflict 导致已部署的机器人中断。请使用单独的机器人令牌进行测试，或通过导入 buildBot() 来测试代码。
必须执行的预检
步骤 1：检查机器人代码是否存在，以及是否仍导出 buildBot
PLUGIN="$HOME/.claude/plugins/marketplaces/cc-skills/plugins/gmail-commander"
ls -la "$PLUGIN/scripts/bot.ts" 2>/dev/null || echo "SCRIPT_NOT_FOUND"
grep -n "export async function buildBot" "$PLUGIN/scripts/bot.ts" || echo "buildBot EXPORT MISSING — the deployment depends on it"
机器人命令（侧边栏菜单）
| 命令 | 说明 |
|---|---|
| /inbox | 显示最近的收件箱邮件 |
| /search | 搜索邮件（Gmail 查询语法） |
| /read | 按 ID 读取邮件 |
| /compose | 撰写新邮件 |
| /reply | 回复邮件 |
| /abort | 取消当前撰写/回复操作 |
| /drafts | 列出草稿邮件 |
| /digest | 立即整理过去 N 小时的邮件（默认 6 小时） |
| /status | 机器人状态和统计信息 |
| /help | 显示所有命令 |
两级命令系统
第 1 级——确定性：斜杠命令直接调用 Gmail CLI（通过 scripts/lib/gmail-client.ts，该文件运行由 GMAIL_CLI_BIN 指定的二进制文件）。
第 2 级——智能：自由文本消息通过 Agent SDK（HAIKU_MODEL）路由，并使用 4 个 Gmail MCP 工具（列表、搜索、读取、草稿）。
安全控制
- 互斥锁：一次仅处理 1 个 Agent 查询
- 超时：每个查询使用
AGENT_TIMEOUT_MS（默认 2 分钟） - 熔断器：连续失败 3 次后，停用 Agent 10 分钟
- 防污染：检测所有 Agent 回复中的技能污染
- 身份验证守卫：仅响应已授权的
TELEGRAM_CHAT_ID
源码索引
| 内容 | 文件 |
|---|---|
| 接线、撰写/回复会话流程 | scripts/bot.ts（buildBot()） |
| 命令列表和处理程序 | scripts/lib/commands.ts |
| 行内键盘回调、会话存储 | scripts/lib/callbacks.ts |
| 自由文本路由、MCP 工具 | scripts/lib/agent-router.ts |
| 邮件格式化、HTML 转义 | scripts/lib/telegram-format.ts |
| 消息分块（4096 字符限制） | scripts/lib/telegram-chunk.ts |
变更后检查清单
- YAML frontmatter 有效（描述中没有冒号）
- 触发关键词保持最新
- 路径模式使用 $HOME，而非硬编码路径
- 导入时
buildBot()仍不会启动传输，也不会获取 PID 锁
执行后反思
此技能完成后，请在结束任务前进行反思：
- 确认位置。——编辑前，找到此 SKILL.md 的规范路径。
- 哪里失败了？——修复导致问题的指令。
- 哪些做得比预期更好？——将其列为推荐做法。
- 哪里偏离了？——修复任何与实际情况不符的脚本、参考资料或依赖项。
- 记录下来。——在演进日志中记录触发原因、修复内容和证据。
不要推迟。下一次调用会继承你留下的一切。