插件开发工作流

本文档介绍进阶开发流程：从模板创建、宿主兼容性检查、与 .eidos SQLite 数据包交互、动态表格动作，到制作独立主题与打包发布。

---

1. 选择脚手架模板

官方脚手架提供多种面向不同开发场景的预设模板：

# 查看所有可用模板
npx @eidos.space/plugin-tools templates

# 使用特定模板创建项目
npx @eidos.space/plugin-tools create my-plugin --template file-view

# 或者使用 eidos CLI（效果完全相同）
eidos plugin create my-plugin --template file-view

cd my-plugin
npm install
npm run check

模板	目标场景	核心能力与接口
file-view（推荐）	物理文件自定义视图（右键打开方式）	context: "file"，ctx.file，ctx.fs，可选 React UI
table-view	数据表内部视图（表内新建视图）	context: "table"，ctx.table 记录拉取与 SQLite 聚合
table-action	数据表格批量操作（表格右键上下文）	registerTableProvider，任务进度与读取令牌安全更新
page	独立一级面板（侧边栏导航）	context: "page"，navigation，workspace.files
theme	Eidos Lite 宿主主题定制	kind: "theme"，语义配色与离线内嵌字体

---

2. 检查宿主兼容性

Eidos Lite 与 CLI Serve 对插件特性的支持范围有所不同。在打包发布前，使用内置工具链进行兼容性静态校验：

# 针对 Eidos Lite 桌面端进行完整校验
npm run check -- --target lite

# 针对 Eidos CLI Serve 网页端进行校验
npm run check -- --target cli

# 输出 JSON 格式诊断信息（便于 CI/CD 集成）
npm run check -- --json

宿主	支持范围
Eidos Lite (桌面端)	全功能支持：File View、Page View、Table View、Action、Formatter、完整 ctx.fs 原语、私有存储、受限网络与独立主题。
Eidos CLI (Serve 网页端)	专注于数据表可视化：Table View 及声明的 Web Worker 与浏览器网络能力。

当前 Eidos Lite 的可执行插件必须声明 API 2.0.0：

{
  "requires": { "pluginApi": "2.0.0" }
}

---

API 1.x 可执行插件需要将文件访问迁移到 ctx.fs，导航迁移到 ctx.ui.openFile， Space 权限迁移到 workspace.files。旧资源声明和 Markdown 专用方法不再支持。 已安装的不兼容插件仍可查看和卸载。纯 API 1.6.0 主题继续兼容。 CLI Serve 的表格视图范围仍使用 API 1.0.0。

3. 操作 .eidos 数据文件

当插件视图打开 .eidos 文件时，可以通过 ctx.eidos 接口读取数据表元数据并持久化保存插件的表级配置：

// 1. 列出当前 .eidos 文件中包含的所有数据表
const tables = await ctx.eidos.listTables()

// 2. 读取指定数据表的字段定义元数据
const { fields } = await ctx.eidos.readTable(tables[0].id)

// 3. 读取当前插件在数据表上的持久化私有配置
const config = await ctx.eidos.readPluginConfig(tables[0].id)

// 4. 基于版本控制安全保存表配置（随 .eidos 文件一起移动和同步）
await ctx.eidos.writePluginConfig(tables[0].id, {
  value: { customFilter: "status = 'done'" },
  expectedVersion: config.version,
})

---

4. 动态数据表动作 (registerTableProvider)

对于需要深度集成在数据表格右键或批量处理记录的场景，可在扩展激活中注册动态动作提供器：

在 plugin.json 中声明：

{
  "extension": "./src/extension.ts",
  "actions": [
    {
      "id": "batch-processor",
      "title": "批量处理记录",
      "context": "table",
      "access": "write"
    }
  ],
  "placements": [
    { "location": "table/context", "action": "batch-processor" }
  ]
}

在 src/extension.ts 中实现：

import type { ExtensionContext, TableActionProvider } from "@eidos.space/plugin-sdk"

export default function activate(ctx: ExtensionContext) {
  const provider: TableActionProvider = {
    // 动态生成菜单项列表
    getItems({ table, signal }) {
      return [
        {
          id: "uppercase-names",
          title: "将选中文本转换为大写",
          targets: ["row", "selection"],
        },
      ]
    },

    // 执行具体选中的动作
    async run(actionCtx, itemId) {
      const { target, task, signal } = actionCtx

      // 1. 分批读取目标行（带只读 token）
      const rows = await target.read({ offset: 0, limit: 100, fields: ["name"] })

      // 2. 声明样本输出字段（Lite 直接应用）
      await task.preview(rows)

      // 3. 循环批量更新
      for (let i = 0; i < rows.length; i++) {
        signal.throwIfAborted()
        const row = rows[i]
        const currentName = String(row.values["name"] || "")

        await target.update({
          readToken: row.readToken,
          values: { name: currentName.toUpperCase() },
        })

        // 报告任务处理进度
        await task.report({
          completed: i + 1,
          message: `正在处理第 ${i + 1}/${rows.length} 条记录...`,
        })
      }
    },
  }

  const registration = ctx.actions.registerTableProvider("batch-processor", provider)
  ctx.subscriptions.add(registration)
}

---

5. 制作独立的 Eidos Lite 主题

除了功能性插件，你还可以制作定制整个桌面宿主外观的主题包：

npx @eidos.space/plugin-tools create my-theme --template theme
cd my-theme
npm run check -- --target lite
npm run pack:plugin

在 theme.css 中定义浅色与深色语义色彩变量：

:root[data-theme="light"] {
  --theme-surface: #f7f8fa;
  --theme-ink: #19212b;
  --theme-accent: #2563eb;
  --lite-sidebar: #f1f3f7;
  --control-radius: 8px;
}

:root[data-theme="dark"] {
  --theme-surface: #181d24;
  --theme-ink: #eef2f6;
  --theme-accent: #3b82f6;
  --lite-sidebar: #13171c;
  --control-radius: 8px;
}

• 语义变量范围：涵盖表面背景、字体色彩、高亮强调、边栏、圆角与字号规范。
• 离线内嵌字体：可通过 @font-face 引入本地 .woff2 / .ttf 字体文件，打包时自动内嵌为 Base64 Data URL。
• 纯静态安全：主题包不包含任何 JavaScript 可执行代码，安装后在宿主设置中全局选用。

---

6. 视图样式与设计系统变量

编写插件视图 UI 时，优先使用宿主注入的设计系统 CSS 变量，确保与用户当前主题无缝融合：

.viewer-container {
  background-color: var(--eidos-background);
  color: var(--eidos-foreground);
  font-family: var(--eidos-font-family, system-ui);
  border: 1px solid var(--eidos-border);
}

button.primary {
  background-color: var(--eidos-accent);
  color: #ffffff;
  border-radius: var(--eidos-control-radius, 6px);
}

---

7. 调试、测试与发布

1. 结构化诊断：运行 npm run check，快速捕获清单遗漏、未定义入口或 TypeScript 类型错误。
2. 热重载调试：在 Eidos Lite 工具栏中点击 Plugins → Load development source… 加载本地源码目录。修改保存代码后，视图自动秒级热重载。
3. 打包分发：运行 npm run pack:plugin，在 dist/ 目录下生成 .eidos-plugin 自包含安装包及其 SHA-256 校验和文件，可直接分发给用户或提交至插件官方注册表。