核心概念

插件由清单、可选的后台入口、视图入口和包内资源组成。先确定每部分负责什么，再选择接口。

清单描述能力

extension.json 声明稳定的插件 ID、版本、兼容范围、权限和贡献项。用户安装时可以检查这些信息。显示名称和作者署名可变，升级应保留插件 ID 与贡献 ID。

contributes 可以声明命令、视图、导航、文件处理器、启动入口、Agent 能力、设置、Skills、主题和图标主题。纯声明式主题或 Skills 包可以没有脚本入口。

三种执行上下文

上下文	入口	适合的职责
后台	activate(context: ExtensionContext)	注册命令、工具与动作，管理共享业务数据和调度
视图	render(context: ViewContext, container)	绘制自己的界面，处理文件、用户操作和实例状态
Agent 调用	已注册工具或动作的回调	使用本次任务与模型能力，处理取消并返回结果

后台也在浏览器沙箱中，不能直接使用 Node.js、系统命令或任意磁盘路径。视图不能访问宿主 DOM。Agent 回调使用宿主绑定的原任务，不通过当前焦点选择目标。

声明、注册与调用

命令、工具和动作先在清单声明，再在 activate 注册对应处理器。视图通过自己的命令与后台通信；后台用 views.broadcast 向本插件的视图发送 JSON 消息。

视图定义描述内容；挂载声明描述位置。同一视图定义可以创建多个实例，每个实例有独立 JS 环境和状态。隐藏视图可能保留实例，关闭或停用才结束相应生命周期。

状态存在哪里

内容	存放方式
宿主渲染的原生设置	configuration
插件私有 JSON 业务数据	后台 storage
资源标签或普通挂载实例的阅读位置、筛选条件	视图 state / setState
下载文件、生成的二进制副本	resources
编辑内容、原件绑定、恢复草稿	交互视图 documents

文档未保存状态、标签标题和界面布局不能替代内容保存。详细选择见设置与状态和文件与文档。

清理与升级

把后台注册加入 context.subscriptions；视图监听、计时器和异步任务跟随 context.signal 释放。Agent 操作使用本次 invocation.signal，不能保留旧调用句柄给后来的任务。

dataVersion 管理私有 JSON 迁移，视图 stateVersion 管理实例状态迁移。升级应处理旧数据，迁移失败时保留恢复可能；普通卸载与清除数据的区别见使用指南。