插件开发概览

星汉的插件系统让你用熟悉的 Web 技术扩展表格编辑器 —— 从一个纯静态页面的侧边小工具，到带后端进程、能读写表格数据、贡献自定义字段和自动化节点的完整应用。内置的 Agent、番茄钟、JSON 字段、白板等功能，全部就是用这套机制实现的插件。

一张能力地图

先回答最重要的问题：你想做的事，用哪个扩展点？

你想做	用哪个贡献点	直达指南	内置范例
右侧抽屉里的常驻面板（计时器、便签…）	views · right-drawer	面板	番茄钟 源码全文
左侧活动栏图标 → 占满编辑区的工作台	views · activity-bar	面板	Agent 工作台
表格右键菜单加一项（选中行/单元格/列头）	contextMenus	右键菜单与命令	划词翻译 selection-translate
一种新的字段类型（渲染 + 编辑归你）	fieldTypes	自定义字段类型	JSON 字段、富文本字段
一种新的文件类型（新建入口 + 编辑器归你）	fileTypes	自定义文件类型	思维导图、白板
表格顶部视图 tab 里加一种（日历/时间线/地图…）	tableViews	自定义表格视图	卡片视图 源码全文
一种自动化工作流节点	automationNodes	自定义自动化节点	图片生成、JS 转换
给 Agent 投知识/工具/人格，或借用它的 AI 通道	contributions / micro-panel	与 Agent 集成	公式小抄 formula-tips
接管某类文件的渲染	fileRenderers	自定义文件类型	—
偏好设置里的配置项	settings / views · settings	manifest 参考	—
命令与快捷键	commands	右键菜单与命令	—

以上都是 manifest 声明：写在 plugin.json 里，宿主加载时静态接线。UI 落点归宿主管，你的插件只负责内容。

系统组成

一个插件由三部分组成，按需取用：

my-plugin/
├── plugin.json     # manifest:身份 + 能力声明 + 贡献点(必需)
├── ui/             # 前端:iframe 里跑的页面(需要界面时)
│   └── index.html
└── src/server.ts   # 后端:独立 node 进程(需要碰数据/文件/LLM 时)

两种运行时，按是否需要后端二选一：

• static —— 纯前端插件。宿主直接静态服务你的 ui/ 目录，不起进程。做纯展示、纯交互的小工具零成本。
• node —— 宿主为你 fork 一个 node 子进程，HTTP 反代到 /plugins/<id>/*。进程里拿到一个 CapabilityClient，经它访问数据引擎、文件、LLM、存储等宿主能力 —— 每一项都要在 manifest 里显式声明，未声明的调用一律拒绝。

安全模型（一句话版）

插件按最小权限运行：manifest 的 capabilities 数组声明了什么才能用什么；对表格的写入走宿主的 changeset 管线（用户可撤销、有历史）；写入尺寸有护栏；卫星项目（如 Agent 会话库）需要单独声明 satellite:<kind> 才可访问。详见插件解剖。

从哪里开始

1. 5 分钟第一个插件 —— 两个文件，右抽屉里看到你的面板。
2. 开发环境与调试 —— 目录约定、热重载、日志；卡住了先查排障速查。
3. 插件解剖 —— manifest 逐字段、运行时模型、授权、边界与限制。
4. 按上面地图的”直达指南”列挑你要做的事；通用底座在带后端的完整骨架、读写表格数据、主题与语言。
5. 完整示例 —— 两个内置插件源码全文，抄下来改个 id 就能跑。
6. 查细节用参考：plugin.json、Capability API；做完了看发布与分发。