企业官网建设流程全解析

Takopi 是一个把 Codex、Claude Code 等 AI 编程引擎接入 Telegram 的开源桥梁工具，完全靠插件机制扩展能力。这篇 Takopi 插件开发教程带你从零实现 Engine（新 AI 引擎）、Transport（新消息平台）与 Command（自定义斜杠命令）三类插件，并掌握验证与排错方法。

一、先看懂：Takopi 的三种插件类型 🧩

Takopi 通过 Python entrypoint 机制发现插件，你无需改动核心代码。官方内置插件也是这样声明的，比如 codex、claude、opencode、pi 四个引擎和 telegram 消息通道，都可以在 pyproject.toml 中找到：

记住三条规则：

• ID 就是 entrypoint 名称，且必须匹配^[a-z0-9_]{1,32}$；
• 插件后端对象的id必须与 entrypoint 名称一致；
• 公共 API 全部从 src/takopi/api.py（即takopi.api）导出，不要导入内部模块。

二、准备插件项目：pyproject.toml 配置 📦

创建你自己的 Python 包（例如myengine），在它的pyproject.toml中声明 entrypoint，并锁定 takopi 版本范围：

[project] dependencies = ["takopi>=0.14,<0.15"] [project.entry-points."takopi.engine_backends"] myengine = "myengine.backend:BACKEND" [project.entry-points."takopi.command_backends"] mycommand = "mycommand.backend:BACKEND"

值的格式是模块路径:变量名。安装后 Takopi 会通过组名自动发现你的插件，发现逻辑见 src/takopi/plugins.py。

三、Command 插件：最快上手的入门示例 ⚡

Command 插件最轻量，适合作为你的第一个 Takopi 插件。在mycommand/backend.py中定义一个带id、description和异步handle方法的类：

from takopi.api import CommandContext, CommandResult class MyCommand: id = "hello" description = "say hello" async def handle(self, ctx: CommandContext) -> CommandResult | None: return CommandResult(text="hello") BACKEND = MyCommand()

使用要点：

• 只有当消息以/hello开头、且hello不与引擎 ID、项目别名、保留词（如cancel、init）冲突时才会触发；
• 配置写在[plugins.hello]下，会以字典形式出现在handle的ctx.plugin_config中；
• 通过ctx.executor.run_one(...)可复用 Takopi 完整引擎流水线，mode="capture"可以收集结果并组装自定义回复。

四、Engine 插件：接入一个新的 AI 引擎 🤖

Engine 插件的核心是构建一个Runner，把你的引擎 CLI 输出翻译成 Takopi 的标准化事件。在模块顶层声明EngineBackend：

from takopi.api import EngineBackend, EngineConfig, Runner from myengine.runner import MyEngineRunner def build_runner(config: EngineConfig, config_path) -> Runner: return MyEngineRunner(config) BACKEND = EngineBackend( id="myengine", build_runner=build_runner, cli_cmd="myengine", # 用于检查 CLI 是否在 PATH 上 install_cmd="pip install myengine", # onboarding 时展示的装包指引 )

Runner 编写要点：

• 事件契约：恰好一个StartedEvent、恰好一个CompletedEvent，且CompletedEvent必须是最后一个事件，其resume与StartedEvent.resume一致；
• 如果你的引擎是 JSONL 流式 CLI（类似 claude、codex），直接继承JsonlSubprocessRunner，只需实现build_args、decode_jsonl、translate等方法，进程管理与完成语义由基类保证；
• 引擎配置表即takopi.toml中与 ID 同名的表（如[myengine] model = "..."）；
• 完整分步指南参考官方文档 docs/how-to/add-a-runner.md。

五、Transport 插件：接入新的消息平台 📡

Transport 插件把 Takopi 连接到其他消息系统。一个TransportBackend对象需要提供：

• id与description：插件标识与描述；
• check_setup/interactive_setup：校验配置并引导用户完成初始设置；
• lock_token：提供锁 token，防止并行运行；
• build_and_run：启动消息循环。

关键捷径：消息处理可以整体委托给takopi.api中的handle_message()——进度更新与节流、resume 处理、取消传播、最终渲染都已实现，Transport 层只需保持轻薄。

六、验证插件加载与常见问题 🔍

安装包后运行两条命令验证：

takopi plugins # 列出发现的 entrypoint（不导入代码） takopi plugins --load # 强制加载每个插件，提前暴露导入错误

常见问题速查：

默认enabled = []表示加载所有已安装插件；如需只启用部分，写入包名列表即可。

七、延伸阅读 📚

• 插件快速上手：docs/how-to/write-a-plugin.md
• 插件系统设计原理（惰性发现、enabled 白名单）：docs/explanation/plugin-system.md
• 插件 API 参考（全部公开符号与版本约定）：docs/reference/plugin-api.md
• 内置引擎实现参考：src/takopi/runners/claude.py、最小事件示例 src/takopi/runners/mock.py