Temps 插件系统开发指南：基于 Plugin SDK 编写自定义外部插件的完整教程-平芜编程栈

【免费下载链接】temps

AI-native open-source alternative to Vercel + Sentry + PostHog + Pingdom + Resend + E2B. 440+ CLI operations with drop-in skills for Claude Code, Codex & OpenCode — deployments, analytics, session replay, error tracking, OpenTelemetry, email, sandboxes & AI gateway in one self-hosted Rust binary.

项目地址：https://gitcode.com/gh_mirrors/temp/temps

点击查看免费下载

Temps 是一个 AI-native 的开源自托管平台，用单个 Rust 二进制文件集成部署、分析、错误追踪、会话回放、邮件与 AI 网关等能力。本文是面向新手的 Temps 插件开发教程：你将基于官方 Plugin SDK，从零编写、本地调试并安装一个自己的自定义外部插件。

为什么需要 Temps 插件

Temps 控制台已内置仪表盘、分析、监控等模块，但业务千差万别——你可能想在每次部署成功后自动跑性能审计、自动提交搜索引擎索引，或把部署事件接入内部工单系统。插件系统正是为此设计：每个外部插件是一个独立二进制进程，由 Temps 主进程扫描、拉起并管理生命周期，你只需关注自己的业务逻辑。

插件系统架构：Temps 如何加载一个外部插件

Temps 主进程会扫描~/.temps/plugins/目录，为每个插件完成五步工作：

拉起子进程：启动插件二进制，通过一次性管道下发握手密钥；
读取 JSON 清单：从标准输出读取插件 manifest（名称、版本、导航、事件订阅等）；
建立数据通道：向插件的/_temps/channel打开 WebSocket 双向通道；
代理 API 路由：把/api/x/{插件名}/*的请求转发到插件的 Unix socket；
挂载插件 UI：解压插件内嵌的 UI 资源，并注册控制台侧边栏导航。

这套握手与权限契约的完整设计见 external-plugin-sdk-boundary.md，Rust 侧 SDK 的入口在 lib.rs。

两条开发路线：TypeScript 或 Rust

路线	SDK 位置	适合场景
TypeScript + Bun（官方推荐）	sdks/node/packages/plugin-sdk/	新插件首选，可走源码仓库分发流程
Rust 原生	crates/temps-plugin-sdk/	追求性能、与平台深度集成

TypeScript 路线围绕两个核心 API：runPlugin定义插件、createManifest构建清单（见 index.ts）。
Rust 路线只需实现ExternalPlugintrait（提供清单 + axum 路由），再用一行temps_plugin_sdk::main!宏接管整个进程生命周期。

第一步：创建插件项目脚手架

一条命令即可生成可独立构建的 TypeScript 插件项目：

bunx --bun @temps-sdk/cli plugin init my-plugin --name @your-scope/my-plugin

生成后请检查并替换占位的作者、版本与描述，并务必提交 lockfile。完整的脚手架与运行时约定见官方技能文档 SKILL.md。

第二步：声明插件清单（manifest）

manifest 是插件与 Temps 之间的"握手契约"，TypeScript 示例：

runPlugin({ manifest: () => createManifest("my-plugin", "0.1.0") .displayName("My Plugin") .requestPermissions("events_read") .addNav("My Plugin", "puzzle", "/my-plugin") .build(), // handler / onEvent ... });

清单关键字段（定义见 manifest.rs）：

name/version：插件唯一标识与语义化版本；
nav：侧边栏入口（图标、路由路径、排序）；
events：订阅的平台事件，如deployment.succeeded；
权限声明：插件只是"申请"权限，管理员安装时才真正授予。

第三步：用本地插件模拟器调试

Temps CLI 内置了无需真实 Temps 服务、数据库或 Docker 的本地模拟器（实现位于 apps/temps-cli/src/commands/plugin/dev/）：

# 启动插件（前台运行，输出 loopback 预览地址） bunx --bun @temps-sdk/cli plugin dev ./dist/my-plugin --session dev --grant events_read # 另一个终端：发送真实的部署事件 bunx --bun @temps-sdk/cli plugin dev emit deployment.succeeded --session dev --url https://example.com # 查看状态 / 撤销授权 bunx --bun @temps-sdk/cli plugin dev status --session dev --json bunx --bun @temps-sdk/cli plugin dev grants set --session dev --clear

模拟器提供模拟的主机 API、Mock AI 与确定性事件 fixture，让你在没有服务器的情况下验证 UI、事件回调和权限撤销逻辑。设计细节见 plugin-dev-runner-plan.md。

第四步：响应部署事件与调用 AI

Temps 通过 WebSocket 通道把平台事件推送给订阅了事件的插件。典型的"部署后自动化"模式：

在清单中订阅deployment.succeeded；
收到事件后只做入队，不要阻塞事件通道做长任务；
在分配的ctx.dataDir下持久化工作记录（推荐 SQLite），保证重启后可恢复。

需要 AI 能力时，一律走 Temps 主机的代理通道（SDK 中的PluginAiClient）：Provider 凭据不会暴露给插件，配额、并发与超时由平台统一管理。

第五步：安装到 Temps 控制台并分发

在真实实例上，可通过控制台 "Plugins" 页或 CLI 从公开源码仓库安装：

bunx --bun @temps-sdk/cli plugin install <仓库地址> --ref <commit-sha> --grant events_read

几个必须知道的要点：

主机安装器会在干净检出上离线编译，不会执行你的 build 脚本，因此 UI 构建产物必须随仓库提交；
--ref可指定分支、标签或 commit，每次操作都会记录解析到的 commit；
想让插件进入公共插件目录，需向插件目录仓库提交一条注册记录，流程见 publishing.md。

实战参考：Lighthouse 性能审计插件

仓库自带一个完整的 Rust 示例插件：部署成功后自动运行 Lighthouse 审计，跟踪 LCP、FCP、TBT、CLS 等核心指标，并支持分数回归告警。

它演示了插件系统的完整能力面：事件订阅（deployment.succeeded/deployment.ready）、React 控制台 UI 内嵌、SQLite 持久化与 OpenAPI 文档生成。入口代码见 main.rs，前端在 web/。仓库中还有 Google 索引、IndexNow 推送等示例插件可作参考。

新手常见误区清单

❌往 stdout 打日志：stdout 是协议通道，诊断信息一律走 stderr；
❌自授权限：manifest 声明 ≠ 已授予，每次调用前查询运行时权限；
❌把数据写进主机数据库：插件数据应存放在分配的dataDir；
❌认为插件是沙箱：外部插件以主机 OS 账户运行，manifest 权限保护的是平台 API 而非文件系统；
❌收到事件就宣称任务完成：事件送达只代表交付成功，任务完成需要业务侧确认。

关键资料速查

资料	路径
Rust 插件 SDK	crates/temps-plugin-sdk/
TypeScript 插件 SDK	sdks/node/packages/plugin-sdk/
主机侧插件运行时	crates/temps-external-plugins/
清单契约定义	crates/temps-core/src/external_plugin/manifest.rs
权限边界设计	docs/design/external-plugin-sdk-boundary.md
本地模拟器设计	docs/design/plugin-dev-runner-plan.md
官方插件开发技能文档	skills/temps-plugin/