使用 eidos serve 打开本地、局域网与 Relay 编辑器

eidos serve 嵌入第一方 Web 与 Lite Host 使用的同一套 Eidos File 编辑器。它适合希望 保留终端文件工作流，同时使用可视化 UI 的场景。

eidos create tracker.eidos \
  --table Tasks \
  --label-field Title \
  --fields '[{"name":"Title","type":"text"},{"name":"Status","type":"select"}]'

eidos serve tracker.eidos --open

行为

• 默认绑定 127.0.0.1；
• 默认端口是 8420；
• 一次只打开一个文件；
• 编辑器 mutation 直接提交到该文件；
• 不需要额外 Save 步骤；
• macOS、Linux 与 Windows binary 都内置 UI。

需要时可更换端口：

eidos serve tracker.eidos --port 9000 --open

显式挂载 assets 文件夹

Serve 不会推测或自动打开 assets 目录。文件包含 assets/cover.png 这类 relative entry 时，需要显式挂载一个已经存在的目录：

eidos serve tracker.eidos --assets-dir ./assets --open

挂载后，内置 UI 的 File 字段可以预览图片、打开或下载已有文件，也可以通过文件选择器、 拖放或剪贴板粘贴上传文件。上传内容会以避免覆盖同名文件的名称写入挂载目录，UI 再通过 正常 Runtime mutation 持久化生成的 assets/<name> File entry。

这个目录是一项显式 capability：没有 --assets-dir 时，Serve 不会读取或写入猜测出的 相邻目录；该 mount 也不会解析 assets/ 前缀之外的 relative entry。单个上传限制为 256 MiB，预览限制为 64 MiB。已配对 LAN 浏览器、Relay 账号浏览器，以及持有 --share 链接的访客，在 Serve 进程存活期间都拥有同样的上传权限，因此只应挂载准备 授权给这些用户的目录。

加载自定义插件

eidos serve 支持加载 .eidos-plugin 格式的插件包（如 eidos.chart 或各类自定义表格视图），并在嵌入式 Web 编辑器中运行。

# 加载单个插件包
eidos serve tracker.eidos --plugin ./dist/eidos.chart-0.1.0.eidos-plugin --open

# 加载多个插件包
eidos serve tracker.eidos \
  --plugin ./dist/eidos.chart-0.1.0.eidos-plugin \
  --plugin ./dist/eidos.map-0.1.0.eidos-plugin

# 扫描并加载目录下的所有插件
eidos serve tracker.eidos --plugins-dir ./plugins

如果所打开文件同级目录下存在 .eidos/plugins/ 文件夹，Serve 启动时会自动扫描并加载其中的全部 .eidos-plugin 插件包。

Serve 还会加载设备级共享存储 ~/.eidos/plugins（可用 EIDOS_HOME 覆盖），因此在 Eidos Lite 中安装的插件在此同样可用。同级 .eidos/plugins/ 目录优先，严格的 --publish 模式忽略共享存储。

沙箱与安全隔离

自定义插件视图运行在严格受限的 iframe 沙箱中（设置 sandbox="allow-scripts"，无 allow-same-origin），每个插件均具有独立的 null origin，完全隔离宿主 DOM、Cookie、LocalStorage 及其他插件。

宿主为插件注入动态内容安全策略 (CSP)：

• 默认完全禁止外部网络请求；仅允许在 manifest.browser.networkOrigins 显式声明的 HTTPS 源。
• 默认禁止 Web Worker；仅在声明 manifest.browser.workers: true 时开放 Blob Worker。
• 脚本与样式均限制在沙箱文档内执行。

宿主能力支持

插件通过异步 JSON-RPC 与 Serve 通信：

• table.read：获取表格字段定义与合并后的视图配置。
• table.page：分页拉取当前视图过滤与检索后的行记录。
• table.aggregate：在服务端 SQLite 层直接执行高速分组指标计算（支持计数、求和、平均值、最值等），无需在客户端拉取数万行原始数据。
• table.properties：持久化保存视图个性化配置到 properties.plugin。在 --publish 模式下禁止修改并返回 PERMISSION_DENIED。
• table.openRecord：打开行记录详情抽屉。
• View settings：插件声明 configuration 时，Serve 会自动在表格工具栏渲染 View settings 配置菜单。

可信局域网访问

--lan 会检测并绑定一个私有 IPv4 接口：

eidos serve tracker.eidos --lan

终端输出的 URL 在 fragment 中携带 access key。打开该链接后，浏览器会与当前 CLI 进程配对；后续访问使用只存在于该进程内的 HttpOnly session cookie。自动检测找不到合适 地址，或机器有多个网络接口时，可以指定准确的私网或 overlay network 地址：

eidos serve tracker.eidos --lan --host 192.168.1.20
eidos serve tracker.eidos --lan --host 100.80.12.4

LAN 模式接受 RFC 1918、link-local、CGNAT（包括常见 Tailscale 地址）与 IPv6 unique-local 地址，不接受公网地址或 wildcard bind。API Host 与 Origin 必须准确匹配所选 地址。

LAN 模式使用普通 HTTP。access link 可以阻止未配对的浏览器调用 API，但不能防止能够监听 局域网流量的人读取通信内容，因此只应在可信私有网络使用。

Eidos Relay 访问

当另一台设备无法通过私网访问 CLI 时，可以启用 --relay：

eidos login
eidos whoami
eidos serve tracker.eidos --relay --open

eidos login 会打开 eidos.space，通过 Authorization Code + PKCE 登录， 并把可刷新的 CLI 会话存入仅当前用户可读的配置文件。后续 Relay 命令会 无系统凭据弹窗地静默复用或刷新它；eidos logout 用于删除本机凭据。

账号会话用于授权 CLI 认领稳定匿名的 r-….eidos.ink 域名。默认输出的 URL 不包含 access key。在任意设备打开后，浏览器会跳转到 eidos.space； 只有认领该域名的同一账号才能完成登录。Relay 随后为该浏览器建立 host-only HttpOnly session。OAuth token 不会进入浏览器 URL 或本地 Serve 进程。

只有在访客需要不登录所有者 Eidos 账号就访问文件时，才使用 --share：

eidos serve tracker.eidos --relay --share

这种显式分享模式会输出当前 Serve 进程的 fragment-key capability。Relay 会把它 换成 HttpOnly 浏览器 session，所以 key 不会出现在普通 HTTP 请求中。任何获得 该链接的人，在本次 Relay session 有效期间都可以编辑文件。

同一账号启动新的 Relay serve 时，新连接会接管域名并断开旧 connector，同时 使上一次 claim 建立的浏览器 session 失效。本地与 --lan 模式仍然无需账号。 Relay 当前限制单个请求 body 为 4 MiB，大型 CSV 导入请使用 localhost 或 LAN。 --share 需要同时使用 --relay；--relay 与 --lan 不能同时使用。

开发 UI override

--ui-dir 可以用另一份静态 build 替代 binary 内嵌 UI。这是开发和发行校验选项，不是普通 使用要求。

eidos serve tracker.eidos --ui-dir ./dist --port 8420

并发

多个 localhost、已配对的 LAN、经账号授权的 Relay 或显式分享的 Relay 浏览器可以 同时编辑。Serve 通过一个权威 Runtime writer 串行提交 mutation，并在每次 revision 提交后 通知其他浏览器。同时发生的 stale edit 会以零副作用拒绝，浏览器随后刷新到最新 revision。

单元格变更和新增行都会乐观渲染。新行的远端 insert 返回前就可以继续输入； Serve 仍会先提交建行，再发送依赖其权威 Row ID 的后续编辑。

Serve 进程仍必须是该文件唯一的物理 writer。使用其他可写 Host 或 SQLite 工具打开同一路径 前，先停止服务。会话结束后，可以用 eidos validate tracker.eidos --level full 做独立完整性 校验。