NotesAgentic/docs/development/扩展安装持久化与社区包开发说明.md

扩展安装持久化与社区包开发说明

本文档用于 Skill、Plugin 安装及社区示例包开发。

更新日期：2026-09-06。代码基线：a5c44c4；社区服务仍处于第三阶段规划。

当前实现

backend/app/extensions/archive.py 解析上传 ZIP，installed.py 为运行时增加本地安装日志。extension-installations.sqlite3 位于 data_dir 下，记录包路径、内容摘要、启用状态、插件授权及受管理目录；成功解压的包保存在 extension-packages，供后续命令读取。

环节	行为
安装 ZIP	最大 10 MiB，解压总量最大 50 MiB，最多 2048 条目
路径检查	拒绝目录穿越、链接、特殊文件、加密条目、重复及大小写冲突路径
包布局	根目录或唯一顶层目录包含 skill.yaml / plugin.yaml
重启恢复	校验目录和内容摘要后恢复安装状态；插件恢复授权
包内容变化	不自动启用变化后的包，需重新安装并检查权限
卸载	受管理 ZIP 目录可清理；用户目录安装源不删除

安装持久化不等于操作系统级沙箱、签名验证或远程社区服务上线。生产隔离、社区发布治理与签名机制仍按第三阶段规划推进。

社区示例

源码与打包入口位于 backend/extensions/community/。note-reviewer 为笔记审阅 Skill，markdown-workbench 为可执行 Plugin。功能、安装和测试输入见该目录 README 与各包 README。

重新打包：

cd backend
uv run python extensions/community/build_packages.py

仅在需要更新社区示例产物时执行，并核对 dist 中 ZIP 和 index.json 是否与源码一致。

验证方法

在 backend 目录执行：

uv run pytest tests/test_extension_archive.py tests/test_installed_extensions.py tests/test_community_packages.py -q -p no:cacheprovider

手动使用测试数据目录安装示例包，启用并调用；重启后端后确认状态恢复。对包副本修改内容再重启，应出现恢复失败提示。卸载目录安装包时，原目录应继续存在。

生产社区规划见 第三阶段实施规划，命令和设置接口见 Plugin Command 与 Settings 开发说明。