2.3 KiB
2.3 KiB
扩展安装持久化与社区包开发说明
本文档用于 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 开发说明。