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

> 本文档用于 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。

重新打包：

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

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

## 验证方法

在 backend 目录执行：

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

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

生产社区规划见 [第三阶段实施规划](../architecture/第三阶段实施规划.md)，命令和设置接口见 [Plugin Command 与 Settings 开发说明](Plugin-Command与Settings开发说明.md)。