插件核心概念

一个插件由声明文件和代码组成。声明文件告诉 Eidos 插件叫什么、从哪里打开，以及需要访问哪些数据。代码负责界面和操作。

插件声明

在 plugin.json 中设置插件的 id、name 和 version，用 views 列出视图，用 placements 指定用户从哪里打开它们。

id 是插件的稳定标识。发布更新时保持它不变，并增加 version，让用户的设置和已保存视图继续关联到同一个插件。

页面视图：独立打开

将视图的 kind 设置为 page，再添加 navigation 入口，即可从侧边导航打开页面。例如，一个项目看板的声明片段如下：

{
  "views": [
    {
      "id": "dashboard",
      "title": "项目看板",
      "kind": "page",
      "entry": "./src/dashboard.ts"
    }
  ],
  "placements": [{ "location": "navigation", "view": "dashboard" }]
}

页面可以使用路由区分自己的内容，例如 / 和 /settings。当前路由通过 ctx.binding.route 获取。需要访问 Space 中的文件时，在插件中声明 workspace.files 权限。

文件视图：随内容打开

将视图的 kind 设置为 file，再添加 file/open 入口和支持的文件扩展名。用户便可以在文件的“打开方式”中选择它。

接下来根据操作选择数据接口。例如，文本编辑器声明 capabilities: ["document"]，通过 ctx.capabilities.document 读取内容、编辑和保存。Eidos 会维护未保存内容和撤销记录。

Eidos 文件的接口组织在 ctx.capabilities.eidos 下：schema 读取文件结构，table 查询当前表格，config 读写本插件配置。根据需要组合声明 eidos/schema、eidos/table、eidos/config。

展示 Eidos 文件内部的表格时，声明 capabilities: ["eidos/table"] 并使用 table/view 入口。用户在表格的视图菜单中添加它，插件通过 ctx.capabilities.eidos.table 查询当前表格的数据。

文件信息通过 ctx.binding.file 获取。视图在表格中打开时，ctx.binding.location 还提供表格和视图 ID。具体数据接口见 API 参考。

在代码中使用上下文

Eidos 打开视图时调用默认导出的 mount(ctx, root)。在 root 中创建界面，并通过 ctx 获取当前视图所需的信息：

• ctx.binding：当前文件、表格位置或页面路由。
• ctx.capabilities：读取数据、保存内容、显示通知等操作。
• ctx.signal：视图关闭时取消异步工作。
• ctx.subscriptions：登记需要随视图一起释放的订阅。

mount 可以返回带 dispose() 的对象，在关闭时释放自己创建的界面。例如，React 插件在其中调用 reactRoot.unmount()。

命令与格式化

命令执行生成今日笔记或处理选中记录等动作。在 actions 中声明命令，在 extension 指向的模块中导出 activate(ctx)，通过 ctx.capabilities.actions 注册处理函数。

格式化器接收文档文本并返回格式化结果。通过 ctx.capabilities.formatters 注册后，用户可以从 Eidos 的格式化操作中调用它。

申请访问权限

视图和动作的 access 默认为 read。需要修改数据时声明 access: "write"。如果操作涉及整个 Space 的文件，还需要声明 workspace.files，例如：

{ "workspace": { "files": { "read": true, "write": false } } }

这个声明适合只读取工作区内容的索引页面。需要创建或修改文件时将 write 设为 true，同时将对应视图或动作的 access 设为 write。Eidos 会在启用插件时向用户展示它需要的访问范围。