61 lines
6.8 KiB
Markdown
61 lines
6.8 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，不共享作者凭据。所有返回文案作为文本渲染，包内代码不在目录服务运行。
|
||
|
||
|
||
## Rust 包验证基础
|
||
|
||
Host 的 `extension_package` 已实现 Release v1 字段校验、递归排序 canonical JSON 和 Ed25519 严格验签，复用已有 Python 签名向量。校验入口要求提供 Host 固定信任根及已核实的撤回/键撤销状态；该离线函数自身不获取在线状态，也不授权安装。验签采用 [ed25519-dalek verify_strict](https://docs.rs/ed25519-dalek/2.2.0/ed25519_dalek/struct.VerifyingKey.html#method.verify_strict)，拒绝无效签名及弱键。
|
||
|
||
ZIP 在解压前独立校验中央目录计数、重复原始名称、本地头一致性和数据区不重叠，避免解压库的名称映射隐藏重复项。逐条检查 NFC 路径、Windows 保留名、完整大小写折叠冲突、文件/目录前缀冲突、链接/特殊文件、加密与压缩方法；按类别检查压缩/展开/条目限额，并用有界缓冲验证全部条目及 CRC。当前只返回文件摘要清单，不写出包文件；不支持多卷或需 ZIP64 中央目录的包。
|
||
|
||
类型清单的身份、版本和权限校验已接入 `verify_package`；完整 Runtime 配置 schema、在线来源复核、持久安装库、迁移与事务运行生命周期仍待接入。因此当前不能据此开启 extensions capability 或标记完整 D-01 通过。
|
||
|
||
|
||
清单解析最多 1 MiB、32 层、10000 个节点、一个文档，限制别名及记录的锚点大小；重复键、包含指令、循环别名、非 UTF-8 和未知 schema_version 拒绝。关闭文件包含与环境插值特性。JSON 类别先验证 JSON 语法再进行重复键检查，不接受伪装为 JSON 的 YAML。
|
||
|
||
Theme 必须声明 theme_id；Skill/Plugin 支持 Runtime 现有的 id 或专用 skill_id/plugin_id，两者同时出现须相等。YAML 类型版本及全部类型权限集合须与发行一致，重复权限拒绝。人设、模板、MCP 和模型方案检查各自基本结构及递归秘密字段；声明式包通过检查不代表已具备运行权限。项目自带 markdown-workbench/note-reviewer 清单已在 Rust 和 Community 校验中验证。
|
||
|
||
|
||
## 本地依赖锁预览
|
||
|
||
Rust 暂存库可为指定根发行生成只读依赖预览。依赖键为同命名空间的包 ID，或同一来源下的 `namespace/package_id`；不跨来源借用同名包。完整裸版本（如 `1.2.3`）表示精确版本，其余采用 Rust SemVer 的 `=`, `^`, `~`, 比较符、通配符和逗号交集语法；不支持的范围明确拒绝，不能当作任意版本。
|
||
|
||
预览固定根发行，优先选择符合全部约束的较新稳定版本，发生依赖冲突时回溯；验证应用 min/max 版本、平台和架构，按依赖先于使用者输出。缺包、版本冲突和环均不生成部分结果。预算为同来源最多 4096 个候选、64 MiB 元数据、200 个解析包、10000 次搜索展开和 4 MiB 预览编码。
|
||
|
||
锁定结果包含来源、命名空间、包类型/版本、归档摘要、签名者摘要、完整发行摘要和权限集；整体摘要另绑定应用版本与目标平台/架构。所选包会重新读取归档并复核签名与清单。该本地预览不下载缺包、不启用实例、不授予许可；正式安装仍须在线复核撤回状态并确认权限，随后按锁定结果执行事务。
|