| name | tina-plugin-system |
| description | TinaIDE 插件系统、.tinaplug、manifest、权限、Lua script/hybrid、LSP plugin、插件市场、内置插件和 starter 模板开发指南。用于新增/修改插件 API、插件包、host commands、插件模板或插件 UI。 |
TinaIDE 插件系统
先读文件
core/plugin/**：插件解析、安装、权限、扩展点、script API、marketplace。docs/plugins/README.md：插件系统总览。docs/registry/GitHub-Registry.md：公开插件/依赖包 Registry 仓库、目录结构与索引格式。docs/plugin-api-contract.md：host API 契约。docs/plugins/Plugin-State-Model.md：插件状态模型。docs/plugins/LSP-Plugin-Development-Guide.md：LSP 插件开发。docs/plugins/Plugin-Authoring-Tutorial.md、docs/plugins/Plugin-API-Guide.md。tools/plugin-starters/**：starter 模板与校验/打包脚本。plugins/**、test-plugins/**、app/src/main/assets/bundled_plugins/**。https://github.com/wuxianggujun/TinaIDE-Registry：插件/依赖包发布事实源，包含 sources/plugins/**、sources/plugin-starters/**、plugins/index.v2.json、packages/index.v2.json、详情 JSON 和 scripts/build-registry.ps1。
项目事实
.tinaplug 本质是 zip，根目录必须有 manifest.json。apiVersion 当前固定为 1；非 1 插件会无效。- 支持 contributions：themes、menus
filetree/context、editor/context、editor/toolbar、keybindings、snippets、projectTemplates、apkExports 等。
- 插件菜单与命令解析统一输出
ResolvedPluginCommand 元数据，包含 pluginId、pluginName、commandId、group、surface 与 source。
- 旧
ResolvedHostMenuItem 仅作为菜单 UI 兼容层保留；命令面板等需要插件来源、搜索关键词或诊断信息的入口应优先消费 resolveEditorToolbarCommands() 等统一命令解析入口。
- 不支持动态 DEX；script/hybrid 走 Lua runtime 和权限确认。
- 插件权限是两层：manifest 声明 + 运行时授权。
- 稳定
tina API 包括 pluginId、apiVersion、log、events、editor、diagnostics、workspace、commands、fs、clipboard、network、db。
- 插件系统负责安装、启用、禁用、卸载和注入扩展点；工具链/包管理负责依赖安装，插件不直接安装依赖库。
- 内置插件目录支持
app/src/main/assets/bundled_plugins/<pluginId>/manifest.json 或 .tinaplug。
- 公开插件与依赖包 Registry 固定为
https://github.com/wuxianggujun/TinaIDE-Registry。
- 客户端默认读取该 Registry 的
plugins/index.v2.json 与 packages/index.v2.json；v2 不存在、请求失败或解析失败时直接报错，不再回退 plugins/index.json / packages/index.json；每个索引入口优先 GitHub Raw，失败后回退 jsDelivr CDN。
- Registry v2 从
0.17.11 引入；0.18.0 起 Android 客户端删除 v1 fallback；Registry 默认停止生成 v1 全量索引。确实需要服务旧客户端时，Registry 仓库可显式使用 build-registry.ps1 -IncludeLegacyV1 与 validate-registry.ps1 -AllowLegacyV1。
- 该 Registry 承载索引、可下载包文件、官方插件源码、starter 源模板和索引构建脚本；不承载后端、数据库或管理后台。
- 如果 v2 的
plugins / packages 索引为空，市场列表为空属于 Registry 未发布内容，不是 Android 仓库缺代码。
- 宿主行为应消费启用态插件，例如
enabledPluginsFlow 或中心状态快照；不要遍历安装态插件后临时过滤。
修改流程
- 先确认是 host API、manifest schema、权限、Lua runtime、LSP plugin、marketplace 还是 starter 模板。
- 修改 manifest/API 前阅读
docs/plugin-api-contract.md 和对应 core/plugin tests。
- 新增 manifest 字段或贡献点时，同步更新
PluginModels.kt、PluginManifestValidator.kt、相关 resolver/manager、文档和测试。
- 新增权限时同时更新 manifest 解析、授权流程、文案和测试。
- 修改 starter 模板后运行模板自己的
validate.ps1 或 validate.sh。
- 修改插件市场发布内容时，优先在
TinaIDE-Registry 更新 sources/plugins/** / sources/plugin-starters/** / packages/**，运行 scripts/build-registry.ps1 并提交 v2 轻量索引和详情文件。
- 如果仍需保留 APK 内置兜底插件，再同步
app/src/main/assets/bundled_plugins/**。
禁止事项
- 不要引入动态 DEX 插件能力，除非项目明确改变安全模型。
- 不要让插件直接安装系统/项目依赖库。
- 不要只看 docs 就实现贡献点；必须核对
core/plugin 是否已落地。
- 不要把市场插件、依赖包索引或包文件回填到 Android 主仓库；发布内容应进入
wuxianggujun/TinaIDE-Registry，大文件可在索引里填写可信 CDN/对象存储绝对 URL。
- 不要绕过权限声明和运行时授权。
- 不要忘记提升 starter plugin manifest version。
- 不要在
script/hybrid 禁用或卸载时遗漏 Lua 运行时、事件订阅和插件命令注册清理。
验证
./gradlew :core:plugin:testDebugUnitTest --console=plain
pwsh ./tools/plugin-starters/script-basic/validate.ps1
pwsh ./tools/plugin-starters/lsp-basic/validate.ps1
pwsh ../TinaIDE-Registry/scripts/build-registry.ps1
pwsh ../TinaIDE-Registry/scripts/validate-registry.ps1 -SkipBuild -SkipGitDiffCheck
- 插件包变更检查
.tinaplug 根目录是否含 manifest.json。
- 插件市场或设置页 UI 变更同时跑 settings/plugin 相关测试。
