核心概念

Eidos 插件是运行在本地沙箱中的扩展模块，能够为 Eidos Lite 增加自定义文件视图、独立面板、快捷指令以及数据表功能。

在开发插件前，了解以下几个核心概念：

---

1. 空间与文件 (Spaces and Files)

Eidos 基于本地文件系统运行，主要包含两层结构：

• Space (工作区)：用户打开的顶层工作区目录。插件可以挂载侧边栏独立页面，或注册全局命令。
• File (物理文件)：工作区内的具体文件（如 .md、.csv、.png、.mp4 以及 .eidos 等）。插件可以为指定扩展名提供自定义视图或文件操作。
  • .eidos 文件：基于 SQLite 的结构化数据文件，内部可包含多张数据表（Table）与视图配置。

---

2. 插件能力类型

插件通过清单文件 plugin.json 声明其提供的能力：

视图 (Views)

视图是嵌入在宿主中的交互界面，由前端技术（如 React、Vue 或原生 DOM）构建：

• 文件视图 (context: "file")：作为特定文件类型的编辑器或查看器，挂载在文件的“打开方式”菜单中。
• 独立页面 (context: "page")：作为常驻功能面板，展示在 Space 左侧主导航栏中。
• 数据表视图 (context: "table")：嵌入在 .eidos 数据表内部，提供表格记录的自定义可视化（如看板、日历、图表）。

动作 (Actions)

动作是无界面的命令或后台任务，可通过快捷键或菜单触发：

• 全局动作 (context: "workspace")：注册到全局快捷命令面板（Cmd+K / Ctrl+K）。
• 文件动作 (context: "file")：注册到文件列表的右键菜单中。
• 数据表动作 (context: "table")：注册到表格右键菜单或批量操作中（支持动态操作提供器）。

主题 (Themes)

独立主题包（kind: "theme"），通过语义 CSS 变量定制整个 Eidos Lite 宿主界面的浅色与深色外观。

---

3. 上下文对象 (ctx) 与文件专有贡献点

当宿主挂载视图或执行动作时，会向入口函数传入一个上下文对象 ctx。

基础通用能力

所有视图与动作均可通过 ctx 访问以下基础能力：

属性	类型	说明
ctx.fs	PluginFileSystem	完整的文件系统接口：读写文本与二进制文件、列出目录、重命名、删除、监听文件变化、获取流式媒体播放地址等。
ctx.storage	PluginStorage	插件专属的离线键值存储，数据持久化保存在本地。
ctx.network	PluginNetwork	向清单中声明的白名单域名发起受限 HTTPS 网络请求。
ctx.settings	PluginSettings	读取、更新及监听用户在设置界面中配置的插件参数。
ctx.ui	HostUI	宿主交互接口：弹出通知、确认弹窗、单选/多选输入框、打开文件及路由跳转。
ctx.signal	AbortSignal	随视图卸载或动作取消自动触发的中断信号。
ctx.subscriptions	SubscriptionDisposer	资源管理器，注册的事件监听或定时器会在上下文销毁时自动清理。

文件的专有接口与特殊贡献点

针对具体物理文件时，所有文件视图均可访问 ctx.file 获取文件路径、名称及大小。此外，特定文件类型还拥有专有的上下文接口与贡献点：

• 文本文件（.md、.txt、.csv 等）：
  • 专有接口 ctx.editor：提供文档草稿读取、内容编辑与冲突同步机制。
  • 特殊贡献点：格式化程序 (formatters)：作为文本文件的专属贡献点，声明在清单的 formatters 数组中，并由 ctx.formatters.register 提供排版逻辑，直接挂载到系统的“格式化文档”指令（Shift+Alt+F / Cmd+K）。
• .eidos 数据文件：
  • 专有接口 ctx.table 与 ctx.eidos：提供数据表结构发现、记录分页拉取以及 SQLite 服务端聚合计算。
  • 特殊贡献点：支持贡献数据表内嵌视图（table/view）以及针对表格记录的动态批量动作（table/context）。

---

4. 界面挂载点 (placements)

placements 声明插件功能在 Eidos Lite 界面中的具体入口位置：

挂载点 (location)	适用能力	上下文要求	说明
"file/open"	View	context: "file"	注册为指定文件扩展名的“打开方式（Open with）”。
"navigation"	View	context: "page"	挂载到 Space 左侧主导航栏中，作为独立的一级页面入口。
"plugin/settings"	View	context: "page"	嵌入到当前插件的设置详情面板中，提供自定义配置 UI。
"table/view"	View	context: "table"	挂载到数据表内部的视图切换菜单中（如新建图表、看板视图）。
"command-palette"	Action	context: "workspace" | "file"	注册到全局快捷命令面板（Cmd+K / Ctrl+K）。
"file/context"	Action	context: "file"	挂载到文件列表的右键菜单中。
"table/context"	Action	context: "table"	挂载到数据表格右键或选区操作菜单中。
"view/toolbar"	Action	与视图上下文匹配	挂载到特定视图顶部的工具栏中。
"keybinding"	Action	对应 action	绑定自定义键盘快捷键。
"Format Document"	Formatter	formatters	文本文件的特殊格式化贡献点，注册到系统格式化指令与快捷键中。