沉浸式阅读扩展¶

手册 · 相关指南

沉浸式阅读通过 deeptutor.reading_extensions Python 入口点组发现服务端包。DeepTutor 在该组中附带朗读、学习指导、词汇、测验和显式目标翻译扩展；当未安装任何扩展时，阅读器不会渲染扩展工具栏。

入口点解析为具有已验证的 manifest 和 run_action(action, context) 方法的对象或类。当前协议版本为 1。

[project.entry-points."deeptutor.reading_extensions"]
example = "example_reading_plugin:ExampleExtension"

from deeptutor.reading.extensions import (
    ReadingAction,
    ReadingExtensionManifest,
    ReadingExtensionResult,
)


class ExampleExtension:
    manifest = ReadingExtensionManifest(
        id="example",
        version="1.0.0",
        name="Example",
        actions=[ReadingAction(id="explain", label="Explain")],
        result_types=["card"],
    )

    def run_action(self, action, context):
        return ReadingExtensionResult(
            type="card",
            title="Example",
            payload={"body": context.visible_text[:500]},
        )

安全边界¶

• 全局 Reading API 身份验证策略保护扩展路由。
• 服务器解析语料、定位符、保存的源锚点和存储的单元文本；浏览器不能将其替换为任意值。
• 仅当选中内容与存储单元中的文本完全一致时，该选择才会被转发。
• 扩展返回四种经过验证的结果类型之一：card、quiz、feedback 或 browser_speech。
• 结果序列化上限为 64 KB。测验和语音负载还会接受额外的形状和长度验证。
• 超出协议 60,000 字符上下文上限的单元会被拒绝并返回客户端错误，而不会调用扩展。
• 操作有 30 秒执行超时；超时后返回标准的可恢复不可用响应。已在线程中运行的同步 Python 处理器无法被安全终止，因此每个扩展有一个私有工作线程，并且其熔断器在超时后保持打开；后续调用快速失败，而不是在进程级线程池上消耗或排队工作。修复或移除卡住的扩展后，请重启 DeepTutor。
• 结果数据作为 React 文本渲染。扩展不能向阅读器发送 JavaScript 或原始 HTML。
• 发现和执行故障相互隔离。损坏的可选包不能阻止文档或其他扩展打开。

协议变更必须在版本 1 内保持向后兼容。未来的不兼容约定必须使用新的协议版本，而不是改变现有字段的含义。

实现与验证¶

• deeptutor/reading/extensions.py