38 lines
3.6 KiB
Markdown
38 lines
3.6 KiB
Markdown
# Community Catalog v1
|
||
|
||
状态：独立目录服务与 Web 消费入口已实现；完整升级/回滚事务、桌面 Extension Manager 和各类别应用链路尚未交付。原型入口为 `community-server/community`，前端为 `/community`。没有预置或宣称上线的官方市场。
|
||
|
||
## 来源与发行
|
||
|
||
用户添加 HTTPS 来源（本机开发可用 HTTP），查看并固定来源公布的 Ed25519 公钥；来源密钥改变不自动继承信任。客户端每次安装重新获取发行、撤回及公钥状态，缓存只用于离线浏览。来源信任由用户核对维护者公钥建立，不由 ZIP 摘要推导，也不由 Sync 绑定继承。
|
||
|
||
`Release` v1 字段及限制见 `community-server/community/package.py`、前端 `src/contracts/community.ts`。签名覆盖除 `signature` 和服务端展示字段外的全部发行元数据，以 UTF-8、递归键排序、无空白且不转义 Unicode 的 JSON 编码。签名包括包类型、版本、许可证、权限、兼容版本、依赖、对象摘要与大小。前后端真实签名互验向量为 `frontend/src/services/fixtures/community-python-vector.json`，仅含受控测试包和公钥。
|
||
|
||
SHA-256 证明内容完整性，Ed25519 证明固定签名者；二者均不能替代运行权限。主题保留 5 MiB ZIP / 10 MiB 展开 / 100 条限制，其他包为 10 MiB / 50 MiB / 2048 条。拒绝路径穿越、Windows 特殊路径、大小写重名、链接、加密 ZIP、非法压缩法和扩展后超限；清单身份、版本及权限须与签名元数据一致。
|
||
|
||
## 接口
|
||
|
||
公共只读接口不携带 Vault Token：
|
||
|
||
| 方法 / 路径 | 行为 |
|
||
| --- | --- |
|
||
| GET `/catalog/v1/sources` | 来源 ID、公钥与撤回状态 |
|
||
| GET `/catalog/v1/packages?q=&type=&offset=&limit=` | 搜索、分页及 ETag；包括已撤回记录 |
|
||
| GET `/catalog/v1/packages/{namespace}/{id}/releases` | 包版本记录 |
|
||
| GET `/catalog/v1/releases/{id}/archive` | 已发布包；撤回或签名键撤销为 410 |
|
||
| POST `/catalog/v1/publish/submissions` | 作者独立 Bearer Token、签名 metadata 和 archive_base64 |
|
||
| GET、POST `/catalog/v1/moderation/reviews` | 审核员列出待审包、批准或拒绝并留原因 |
|
||
| POST `/catalog/v1/releases/{id}/withdraw` | 作者本人或审核员撤回，历史不可覆盖 |
|
||
| POST `/catalog/v1/releases/{id}/reports` | 登录身份举报，写入审计 |
|
||
| POST `/catalog/v1/keys/{id}/revoke` | 审核员撤销签名键，后续下载拒绝 |
|
||
|
||
namespace 归属绑定作者；作者无审核角色；审核拒绝自审。版本一旦提交不可原地替换，拒绝后也须使用新版本。账号令牌在独立 SQLite 中只保存摘要；CLI 排他写出首次令牌文件，服务不需要作者私钥。
|
||
|
||
## 客户端安装与明确限制
|
||
|
||
前端支持来源启停、搜索、发行详情、固定公钥、取消/错误、离线浏览。Theme / Skill / Plugin 经已有类型安装 API，安装后保持未启用。MCP、人设、模板和模型方案保存为候选，可预览和删除，**尚未应用到各自 Runtime**。存在依赖的包当前要求先人工核对，不自动启用依赖。
|
||
|
||
该原型尚不具备全量安全安装状态机：统一持久安装库迁移、事务升级/回滚、断点下载、资源托管、维护者转移、账号登录/令牌过期、举报处理 UI 和生产限流均待完成。目录读取目前在 SQLite 中筛选；大规模服务索引和负载测试待完成。客户端分页当前展示前 100 条，需缩小搜索范围。
|
||
|
||
开发 CORS 只允许部署者指定的来源执行 GET，不共享作者凭据。所有返回文案作为文本渲染，包内代码不在目录服务运行。
|