第三方插件开发¶

手册 · 工具与能力 · 阅读扩展

官方模块 wheel 与 DeepTutor 共享解释器和版本。 第三方插件拥有独立的清单、审批和生命周期契约。 从可运行的 Learning Echo 示例 开始， 该示例声明了一个工具、能力、HTTP 路由和静态页面，且不依赖外部 Python 依赖。

清单与注册¶

一个包使用 schema deeptutor.plugin/v1 提供静态的 deeptutor.plugin.json。 请阅读 manifest.py 和 示例清单 了解具体字段。它声明了身份/版本、DeepTutor/API 兼容性、 权限披露、依赖闭包和类型化扩展。未知字段 和无效路径将被拒绝。

内置 ID 具有优先级。每个扩展保留各自的类型化协议。 现有的 Python 入口点组在存在根清单审批时会遵守该审批； 新包不应依赖旧的无清单路径。 发现过程只读取元数据，不导入第三方代码。 注册表 区分可用、 需要审批、已启用、已禁用、不兼容、损坏和已弃用状态。

安装与审批¶

使用 deeptutor plugin --help 查看生命周期命令。托管安装 接受本地 wheel 或从随附的 catalog.json 中解析已审核的条目。 目录浏览/版本解析是离线的；显式安装会下载固定版本的构件。 不存在任意 URL 安装器或自动后台升级。

目录构件绑定 HTTPS wheel URL、SHA-256、大小和平台元数据。 下载在 pip 之前拒绝重定向以及大小/摘要不匹配。本地 生命周期在导入代码之前从 wheel 中验证清单，创建 版本私有的环境，并安装显式的仅 wheel 依赖 闭包。它不会修改宿主解释器。

审批绑定规范化后的清单与构件身份。在审批前请检查 当前快照。安装、升级、同版本 重装和回滚都会清除先前的审批。审批不会自动 启用本地已禁用的插件。失败的安装会保留之前可用的状态； 保留的版本支持回滚。外部宿主安装的 插件升级需要重启才能替换已导入的 Python 模块。

所有者是 lifecycle.py，状态 位于运行时 data/user/settings/plugins.json 下。API 生命周期变更需要 管理员授权。插件测试 覆盖清单、 构件、事务、恢复和审批边界。

Worker 协议与取消¶

runtime.py 使用 插件环境的 Python 启动 worker 模块。Worker 声明不能超出已审批的 清单。旧版 worker 在 stdin/stdout 上交换一个 JSON 请求和响应。

能力可以在其描述中声明 "transport": "ndjson-v1"。 然后它会输出 JSON 行，包含 {"kind":"event","event":{...}}，随后 是 {"kind":"complete"}。事件进入正常的持久化轮次流； worker 不拥有并行的公共流。完成前出现 EOF 以及 格式错误的帧会导致运行失败。请求、帧、输出、stderr 和执行 都有界限；队列应用背压。取消操作会关闭进程组 并等待清理。该示例同时支持流式模式和旧版模式。

HTTP 与静态页面¶

托管 HTTP 路由使用 /api/plugins/{plugin-id}{path}，不能替代 内置路由。宿主在启动 worker 之前会解析已审批、已启用、兼容的托管状态 并进行认证。在启用宿主认证的情况下， 即使插件路由声明为 public 也需要宿主会话：它不会 绕过宿主账户边界。admin 策略会增加管理员 检查。不可用的插件路由返回 404。

Worker 接收声明的方法/路径、规范化后的查询值和有界的 JSON 请求体，而非宿主 cookie、bearer 令牌或认证头。 响应具有经过验证的 JSON 状态/请求体和受限的 Cache-Control； 重定向和认证响应属于宿主。参见 API 测试。

静态页面声明 schema deeptutor.plugin-frontend-page/v1、一个入口 以及显式的资源闭包。只允许提供已审批的常规包文件； 符号链接和未声明的资源将被拒绝。规范 URL 是 /api/plugins/{plugin-id}/pages/{extension-id}/。请保留尾部斜杠以支持 相对资源。

页面在沙箱浏览器上下文中运行，带有严格的 CSP，包括 connect-src 'none'；它们不会将 React/Next 代码注入宿主 bundle， 也不会任意获取宿主 API。参见 frontend.py、 前端测试 和 示例页面清单。

信任限制与验证¶

权限声明和批准并非操作系统沙箱。宿主入口点扩展在宿主解释器中执行；受管工作进程隔离 Python 依赖，但仍保留宿主操作系统访问权限。请审查实际使用的包和依赖项。打包的浏览器页面拥有各自的浏览器沙箱。不支持直接复用 Chrome 扩展。

• 验证 manifest，构建 wheel 包，测试批准/启用、工作器与页面，然后禁用/撤销并取消运行。使用一次性的运行时主目录。 参见 测试 以及单独的 读取扩展上下文/结果规则。