Telegram Managed Bot Factory

Telegram 托管式 Bot 工厂

一个可自托管的 MCP 控制平面，可将一个由用户拥有的 Telegram 管理 Bot 转变为彼此隔离、实用的子 Bot。向 Hermes 请求一个受支持的 Bot，在 Telegram 中确认这项具体创建操作，然后由持久运行的 Factory 工作进程获取并隔离子 Bot 凭据，不向模型或 MCP 暴露该凭据。

版本 0.2.3 仅支持终端操作：没有桌面应用引导流程。 每个 PyPI 版本都是不可变的；请安装以下固定版本。

为何这很重要

手动创建 Bot 涉及有价值的凭据和真实的外部副作用。Factory 将此工作流明确化：Agent 可以准备范围受限的请求，但由所有者在 Telegram 中批准创建，再由持久运行的工作进程在 Agent 上下文之外接收生成的凭据。

我构建了什么

我设计了 MCP／控制平面边界、持久化工作进程生命周期、凭据隔离、请求状态与协调规则，并将该工具打包发布，供用户自托管。设计有意不声称能确保外部副作用恰好执行一次：对于结果不明确的崩溃，会提示进行协调，而不是盲目重试。

安装

需要 Linux（支持 systemd --user）、Python 3.11–3.14、uv、Hermes 0.18，以及一个启用了 Bot 管理模式的独立 Telegram Bot。

uvx --refresh --from telegram-managed-bot-factory==0.2.3 bot-factory install-hermes

本地安装程序首先验证 systemd --user，并启用已验证的用户 linger，以确保工作进程在 SSH 注销后继续运行；随后通过安全提示一次性接收管理 Bot 凭据，为所有者注册，安装并验证持久化用户服务及新鲜的工作进程心跳，将九工具 stdio 服务注册到 Hermes，并验证其发现结果。它不会创建子 Bot。

仅限终端的首次运行

请在将运行工作进程的同一台 Linux 主机上，通过交互式 SSH 或控制台终端运行安装命令。该命令会在该终端中完成全部设置：

1. 将确切的 Factory 版本安装为持久化的 uv tool（工作进程单元不会指向可能被清理的 uvx 缓存）；
2. 在请求任何凭据之前验证 systemd --user 并启用已验证的用户 linger；
3. 仅通过隐藏的终端输入接收管理 Bot 令牌；
4. 为所有者注册、安装服务、确保服务处于活动状态，并观察到新鲜的工作进程心跳；
5. 将九工具 stdio 服务注册到 Hermes 并验证；任何 Hermes 确认提示都会显示在此终端中。

没有图形界面启动器，也没有未配置的 MCP 引导工具。在此命令完成之前，Factory MCP 会有意拒绝启动。绝不能将令牌粘贴到 Hermes 聊天、MCP 参数、Shell 命令或环境变量中。

工作原理

You → Hermes → Factory MCP ──durable request──▶ persistent worker
                  ▲                                │
                  │ safe status                    │ Bot API
                  │                                ▼
                  └──── Telegram confirmation ◀─ manager bot
                                                   │ child credential
                                                   ▼
                                         isolated child runtime

Hermes 和 MCP 是不包含机密信息的控制平面。只有持久运行的工作进程会轮询管理 Bot 并获取凭据。每个子 Bot 只会获得自己的凭据，并使用实例本地状态。

实用配置档案

同一组四个内置配置档案以严格的 Hermes 函数目录形式提供。Telegram 确认并创建子 Bot 后，使用 factory_list_functions，然后调用 factory_attach_function，传入现有的子 Bot slug 并设置 confirm=true。重复进行相同的附加操作不会产生任何效果；重新绑定会保留 Bot 用户名和 Telegram 身份。 暂停和恢复仍使用现有的停止／启动工具。

配置档案	用途
quick_faq	提供包含 3–8 条本地纯文本回答和联系信息的公开菜单。
lead_inbox	提供带隐私说明的消息表单，并支持通知所有者以及经确认后导出／清除数据。
link_inbox	仅限所有者访问的 URL 和备注，支持 /list 和 /done；不会获取 URL。

还包含 owner_echo，用于仅限所有者的隔离和运行状况冒烟测试。 配置档案不能提供任意代码、可执行文件、文件系统路径、HTML、Agent 工具或远程抓取功能。

60–90 秒演示

安装后，向 Hermes 提出请求：

创建一个名为“Studio FAQ”、用户名为 studio_faq_bot 的快速 FAQ 机器人。 欢迎语：“请选择一个问题。”添加价格、交付时间和联系方式相关的 FAQ。

Hermes 会返回 Telegram 创建链接。打开链接并批准一次，然后打开新子机器人，发送 /start、/faq 1 和 /health。如果仍在配置中，请向 Hermes 查询请求状态。对于其他配置文件，提交一个测试线索，并尝试仅限所有者使用的 /export confirm，然后是 /purge confirm；或者在 link_inbox 中保存一个 URL，查看 /list，然后使用 /done 1。

平台与边界

• 支持的运行环境：使用 systemd --user 的 Linux；已测试 Ubuntu 和 WSL2。
• 支持的客户端：Hermes 0.18 legacy stdio 和经过测试的 MCP 2026-07-28 路径。
• 不支持：Windows/macOS 安装、托管式多租户、任意子机器人代码、自动删除机器人账号，或绕过 Telegram 审批。
• 管理器机器人归用户所有，与 Hermes 网关机器人相互独立。
• 创建每个子机器人都需要 Telegram 确认；这并非“一键”操作。
• Official MCP Registry 条目仅提供元数据，不是安全认证。

安全要点

• 令牌绝不会进入 MCP 参数/结果、聊天、CLI 参数、YAML、SQLite、清单、日志、追踪记录、测试样例或 Git。
• 秘密目录权限为 0700，文件权限为 0600；子机器人凭据通过继承的匿名文件描述符传递，而非通过 argv 或环境变量传递。
• 子机器人的入站更新 ID 和偏移量会持久化。已完成的冲突会被视为无操作；结果不明的崩溃副作用会被隔离以供协调处理，而不会被静默重试。我们不声称外部副作用只会发生一次。
• 输入会受到限制并经过验证；配置文件无法执行或获取所提供的内容。

完整的边界模型请参阅安全策略和架构。

文档与源代码

• 源代码与问题
• 规范 · 验收 · 状态 · 发布证明
• 变更日志 · 贡献指南 · 安全
• Telegram 托管机器人 · Official MCP Registry 条目

故障排除与移除

检查工作进程和 Hermes 注册情况，但不要分享未经审核的 journal 输出：

systemctl --user status bot-factory-manager.service
hermes mcp test bot-factory

在 WSL2 上，PID 1 必须是 systemd，且发行版必须保持运行状态。卸载服务/软件包不会删除 Factory 数据或撤销 Telegram 机器人；请分别检查本地 XDG bot-factory 目录和 BotFather 控制项。