mirror of
https://git.openapi.site/https://github.com/desirecore/registry.git
synced 2026-10-21 01:13:19 +08:00
Yige
3828aa6800
* feat(registry): 增加插件贡献与应用依赖的4.2契约 * fix(registry): preserve legacy App manifests for published clients --------- Co-authored-by: yi-ge <6657330+yi-ge@users.noreply.github.com>
463 lines
23 KiB
Markdown
463 lines
23 KiB
Markdown
# DesireCore Registry
|
||
|
||
DesireCore 官方注册表仓库，包含应用、插件、MCP 服务、HTTP API 服务，以及只用于发现和合规披露的第三方外部集成。可否安装由条目的来源和治理证据决定。
|
||
|
||
DesireCore 客户端启动时会克隆此仓库，并定期同步更新。用户在应用商店中看到的所有条目均来自此仓库。
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
.
|
||
├── README.md # 本文件
|
||
├── SCHEMA_VERSION # 数据格式版本号（当前 4.2.0）
|
||
├── manifest.json # 仓库元数据（版本、统计、维护者）
|
||
├── package.json # Registry 校验入口
|
||
├── schemas/ # legacy entry、仓库 manifest 与 catalog sidecar Schema
|
||
├── scripts/ # Registry v4 校验入口与回归测试
|
||
├── scripts/catalog/ # 零依赖离线 validator 与 node:test
|
||
├── entries/ # 🔑 所有注册表条目（统一格式）
|
||
│ ├── n8n/ # 示例：Docker 应用
|
||
│ │ ├── manifest.json # 条目元数据（必需）
|
||
│ │ ├── catalog-metadata.v1.json # 统一目录元数据（迁移窗口内可选）
|
||
│ │ ├── install.md # 安装说明（Agent 使用，可选）
|
||
│ │ └── usage.md # 使用说明（Agent 使用，可选）
|
||
│ ├── playwright-mcp/ # 示例：MCP 服务
|
||
│ │ ├── manifest.json
|
||
│ │ ├── install.md
|
||
│ │ └── usage.md
|
||
│ ├── baidu-map/ # 示例：HTTP API（无需安装）
|
||
│ │ ├── manifest.json
|
||
│ │ └── usage.md
|
||
│ └── kimi-webbridge/ # external-integration：只允许 manifest.json
|
||
│ └── manifest.json
|
||
├── models/ # 模型能力描述符与分类
|
||
│ ├── descriptors.json
|
||
│ └── categories.json
|
||
└── ui-config/ # UI 展示配置
|
||
├── app-categories.json
|
||
└── service-status.json
|
||
```
|
||
|
||
## 原生应用（4.1）
|
||
|
||
[DesireCore Control 1.4.0](entries/desirecore-control/) 是面向外部智能体的独立宿主机应用，包含 ChatGPT 隧道管理。它以 `type: native-app`、`install.method: native-node`、`identity.kind: app` 收录；MCP 只是对外协议，不注册到 DesireCore 内部工具列表，不伪装为 Docker。
|
||
|
||
原生应用必须声明宿主机 Node 版本、`docker: false`、精确管理端口、最低客户端版本、不可变 Release URL/ref/SHA-256 和审核记录。安装说明同时覆盖安装、升级、验证及卸载，不随 DesireCore 启停，不默认启用控制或隧道。条目禁止 `connection`、`exposes`、`endpoint`、工具数等内部服务配置；`allowAgentBinding` 为 false。兼容来源字段只写在 manifest.source 与 sidecar.provenance.content，二者必须一致；sidecar 不写运行时 governance.source。
|
||
|
||
安装要求支持 native-app 的客户端（Control 条目最低 10.0.170）及核心应用安装技能 >=1.5.0。目录同步不能升级桌面客户端或技能；旧版看不到条目或提示升级时，不得修改类型绕过兼容检查。新制品已发布不代表新版桌面客户端已发布，也不代表用户已完成 ChatGPT 联调。
|
||
|
||
English: Native applications are independently installed host processes. Their outward MCP protocol does not make them internal service packages. Pinned artifacts, explicit client/skill compatibility and App lifecycle receipts are required; catalog publication alone cannot upgrade an older client. The Control listing is the sole application entry, not a Docker or MCP duplicate.
|
||
|
||
## 应用与插件（4.2）
|
||
|
||
插件仍是统一 App 产品，`productKind: plugin` 表示它向宿主提供能力；`productKind: application` 表示它交付独立业务。`type` 只区分交付形态：Docker、宿主进程或纯声明 `artifact`。插件使用同一来源内产品 ID、版本、安装材料与安装登记，不重复创建 MCP 服务或第二份安装事实。
|
||
|
||
应用类型必须明确声明 `entrypoints`。普通 native/Docker 应用可省略 `productKind`，受信读取时归一为 `application`，并至少有一个入口；插件必须明确声明 `productKind: plugin`，无 UI 插件可以声明空数组，但必须通过 `extension.contributes` 提供至少一项实际宿主贡献。新 `artifact` 仍要求明确产品归属，使用 `install.method: artifact`、`docker: false`、空端口与声明式 runtime，不能伪装成 Docker 或宿主进程。
|
||
|
||
`extension` 区分提供与消费：
|
||
|
||
- `contributes` 指明本产品提供的贡献 ID、贡献点、契约版本及包内 `definitionRef.path/sha256`。当前贡献点限于 `document.parsers`、`session.panels`、`session.widgets`、`session.actions`、`tools`、`skills`。
|
||
- `requires` 指明必需或可选的直接能力依赖，使用精确 `sourceId/appId/contributionId/contractVersion`，可加版本范围。普通应用可以只声明依赖；插件即使有依赖也必须提供贡献。两项同时为空无实际关系，校验拒绝。
|
||
- 产品引用不携带安装实例 ID、凭据、启用状态或权限。客户端运行时解析精确安装实例，由目标宿主维护接入、配置和撤销；目录声明不会自动安装、启用或授权依赖。
|
||
|
||
依赖中的 `extension.requires[].sourceId` 是产品引用；条目自身的 `sourceId` 与 `hasInstall` 仍只由受信客户端注入。贡献材料必须使用规范 POSIX 包内相对路径并固定摘要；实际获取与消费仍由客户端核验字节与文件归属。
|
||
|
||
4.2 对现有 9 个应用在 sidecar 中声明 `application` 身份，legacy manifest 省略旧客户端不认识的 `productKind`，并提供读取安装/使用材料后委派 Agent 的真实维护入口。现有目录没有可引用的用户 UI 服务 ID，不猜测 API endpoint 或任意本机端口为 Web 页面；`legacy-port:`/`native-port:` 仅供客户端兼容适配层生成，发布者不能自行声明。原有版本、来源、许可证、审核及 `listing-only` 事实保留，未完成治理证据的条目不会因为格式迁移变为可安装。当前官方条目数仍为 23，没有新增或默认启用插件。
|
||
|
||
Catalog sidecar 的 App spec 同步 `productKind`、可选 `extension` 和入口类型摘要；与 manifest 的受信归一结果必须一致。4.2 Schema 的固定 LF SHA-256 为 `ea63d6305ae17994e595aea009a131c41300d2b7fdb07ec83cc2c19c37b32038`。旧普通应用 manifest 保留已发布 10.0.177 可读取的字段；这不表示旧客户端支持 4.2 插件、artifact 或受新 authored 契约校验的外部集成。新能力上线前须确保目标客户端固定了此摘要并支持 4.2，目录发布不会升级客户端。
|
||
|
||
English: Plugins are App products with host contributions, sharing the canonical catalog and installation identity. Deployment type does not decide product kind. Applications may provide contributions or consume direct dependencies; a plugin must provide a real contribution. Artifact packages contain declarative materials without ports or processes. Dependency product references do not grant installation, activation or permission. Existing listings retain their source and compliance evidence; schema migration does not make listing-only content installable or publish a client release.
|
||
|
||
## 条目格式
|
||
|
||
每个条目是 `entries/<id>/` 下的一个目录，目录名即条目 ID。
|
||
|
||
### manifest.json（必需）
|
||
|
||
条目元数据，供客户端渲染商店列表和详情页。
|
||
|
||
**公共字段（所有类型）：**
|
||
|
||
| 字段 | 类型 | 必需 | 说明 |
|
||
|------|------|------|------|
|
||
| `id` | string | ✅ | 唯一标识，与目录名一致 |
|
||
| `name` | string | ✅ | 显示名称 |
|
||
| `type` | string | ✅ | 条目类型：`native-app` / `docker-app` / `artifact` / `mcp` / `http-api` / `external-integration` |
|
||
| `version` | string | ✅ | 上游原始版本字符串；可为 SemVer、CalVer 或不透明版本 |
|
||
| `description` | string | ✅ | 一行功能摘要 |
|
||
| `author` | string | | 作者或组织 |
|
||
| `tags` | string[] | | 搜索标签 |
|
||
| `icon` | string | | 图标（CSS 渐变或 Lucide icon 名） |
|
||
| `platformSupport` | string[] | | 支持平台：`macos` / `windows` / `linux` |
|
||
|
||
**静态数据边界 / Static-data boundary**：本仓库保存发布者声明，不采集用户行为。禁止新增 Stars、访问量、下载量、评分、热度、安装数以及本机健康度等动态状态。目录条目数可由文件推导，不能与使用量混淆。版本指目录收录版本；内存和磁盘字段仅在上游有明确要求或建议时填写，不能用通用估计补齐。 / This Git-backed catalog contains publisher declarations, not usage analytics. Do not publish stars, views, downloads, ratings, popularity, installation counts, or device health. File-derived catalog counts are not usage counts. Versions are listed releases; hardware requirements must come from the publisher, not generic estimates.
|
||
|
||
**Docker 应用专属字段（`type: "docker-app"`）：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `iconLetter` | string | 图标上显示的字母 |
|
||
| `category` | string | 应用分类：`ai-platform` / `chat` / `workflow` / `rag` / `tools` |
|
||
| `shortDesc` | string | 简短描述（列表页） |
|
||
| `fullDesc` | string | 详细描述（详情页） |
|
||
| `githubUrl` | string | GitHub 仓库地址 |
|
||
| `install` | object | 安装配置（见下方） |
|
||
|
||
Docker 应用 `install` 结构：
|
||
|
||
```json
|
||
{
|
||
"method": "docker",
|
||
"requirements": {
|
||
"docker": true,
|
||
"minMemory": "2GB",
|
||
"minDisk": "5GB",
|
||
"ports": [5678]
|
||
},
|
||
"configNeeded": ["Docker 运行环境", "数据库（SQLite / PostgreSQL）"]
|
||
}
|
||
```
|
||
|
||
**MCP 服务专属字段（`type: "mcp"`）：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `capabilities` | string[] | 能力标签列表 |
|
||
| `toolCount` | number | 可选：收录版本中可验证的工具声明数，不是本机实时发现/启用工具数 |
|
||
| `install` | object | 安装配置：`{ method, packageName, command, args, postInstall?, env? }` |
|
||
| `connection` | object | 连接配置：`{ transport, command?, args?, url? }` |
|
||
| `sourceAppId` | string | 关联的应用 ID（如 dify-mcp 关联 dify） |
|
||
| `sourceAppName` | string | 关联的应用名称 |
|
||
|
||
MCP `connection.transport` 取值：`stdio` / `streamable-http` / `sse`
|
||
|
||
**HTTP API 专属字段（`type: "http-api"`）：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `endpoint` | string | API 基础 URL |
|
||
| `capabilities` | string[] | 能力标签列表 |
|
||
| `sourceAppId` | string | 关联的应用 ID |
|
||
| `sourceAppName` | string | 关联的应用名称 |
|
||
|
||
**第三方外部集成专属字段（`type: "external-integration"`）：**
|
||
|
||
Schema v4 的 external integration 是严格、失败关闭的目录指针，不是 `StoreApp`、安装事实、连接或 Browser Provider。当前只准入经过审核的 `kimi-webbridge` ID，并固定以下治理语义：
|
||
|
||
- `stewardship: "pointer"`
|
||
- `availability: "listing-only"`
|
||
- `redistribution: "source-pointer-only"`
|
||
- `branding.relationship: "independent-listing"`
|
||
- `branding.nameUsage: "nominative"`
|
||
- `branding.logoStatus: "not-used"`
|
||
- `admission.status: "blocked"`
|
||
|
||
条目还必须结构化披露上游维护者、完整官方 URL、浏览器扩展 ID、物理组件、扩展权限、独立 Profile 建议、WebBridge 本地链路与 DesireCore 模型 Provider 的不同数据边界、阻塞准入原因，以及固定版本 daemon 的 SHA-256 审核记录。
|
||
|
||
external integration 目录必须恰好包含一个常规文件 `manifest.json`。额外文件、目录、符号链接、设备节点、FIFO、Socket 或二进制制品全部被拒绝；因此它没有可被 Agent 当成安装指令执行的自由文本面。`sourceId` 和 `hasInstall` 仅由客户端从可信来源和目录事实注入，禁止写入上游 manifest。
|
||
|
||
### install.md（可选）
|
||
|
||
自然语言安装说明，供 DesireCore Agent 读取并执行安装流程。
|
||
|
||
内容应包含：
|
||
|
||
- 环境要求（Node.js 版本、Python 等）
|
||
- 安装步骤（可直接执行的命令）
|
||
- 验证方式
|
||
|
||
**不需要 install.md 的情况**：纯 HTTP API 服务（无需在本地安装）、通过关联应用附带安装的服务（如 dify-mcp 随 Dify 一起可用）。`external-integration` 明确禁止 `install.md`。
|
||
|
||
### usage.md（可选）
|
||
|
||
使用说明，描述安装后如何连接和使用此服务。
|
||
|
||
内容应包含：
|
||
|
||
- 连接配置（transport、command、URL 等）
|
||
- 配置示例（JSON 格式，可直接使用）
|
||
- 注意事项
|
||
|
||
`external-integration` 不允许 `usage.md` 或其他附加文件；所有用户可见披露必须是经过 Schema 约束的 manifest 字段。
|
||
|
||
### catalog-metadata.v1.json（迁移窗口内可选）
|
||
|
||
固定路径为 `entries/<id>/catalog-metadata.v1.json`，Schema 为
|
||
`schemas/catalog-metadata.v1.schema.json`。它给新客户端提供统一目录读模型所需的条目事实，
|
||
不会替换 `manifest.json`；旧客户端继续只读 legacy manifest，新客户端在 sidecar 缺失时也必须
|
||
回退到 legacy adapter。
|
||
|
||
Sidecar 只允许声明条目自身事实：
|
||
|
||
- `identity`：`app` / `service` 与来源内 ID。不得写 `sourceId` 或 `catalogSourceId`。
|
||
- `presentation`：默认语言和真实 i18n 文案。未翻译文本只能保留一个 locale，不能复制成伪双语。
|
||
- `release`：显式 `known` / `unknown`；已知时保留原始版本与 `semver` / `calver` / `opaque` 解释方式。
|
||
- `timestamps`：目录更新、内容发布、治理审核和上游观察时间相互独立；客户端同步时间不写入。
|
||
- `provenance.content`：内容上游及其不可变 ref/digest；Catalog 仓库来源由客户端受信上下文注入。
|
||
- `governance`：listing-only/installable、维护者、许可证、品牌和审核证据。
|
||
- `compatibility`：平台必须显式区分 `known` / `all` / `unknown`。
|
||
- `spec`：App 的产品归属、宿主贡献/依赖、分类、入口类型与放置策略，或 Service 协议、鉴权类型、能力与工具数；安装命令、endpoint 和凭据不进入统一目录元数据。
|
||
|
||
示例（证据不足的条目必须失败关闭为 listing-only）：
|
||
|
||
```json
|
||
{
|
||
"$schema": "../../schemas/catalog-metadata.v1.schema.json",
|
||
"schemaVersion": 1,
|
||
"identity": { "kind": "app", "id": "my-app" },
|
||
"presentation": {
|
||
"defaultLocale": "zh-CN",
|
||
"i18n": {
|
||
"zh-CN": { "name": "My App", "summary": "应用摘要" }
|
||
},
|
||
"tags": ["demo"]
|
||
},
|
||
"release": { "state": "known", "version": "1.0.0", "versionScheme": "semver" },
|
||
"timestamps": {
|
||
"catalogUpdatedAt": { "state": "unknown" },
|
||
"releasePublishedAt": { "state": "unknown" },
|
||
"reviewedAt": { "state": "unknown" },
|
||
"upstreamObservedAt": { "state": "unknown" }
|
||
},
|
||
"provenance": {},
|
||
"governance": {
|
||
"availability": "listing-only",
|
||
"license": { "state": "unknown" },
|
||
"redistribution": "verify-package-terms"
|
||
},
|
||
"compatibility": { "platforms": { "state": "unknown" } },
|
||
"spec": { "kind": "app", "category": "tools" }
|
||
}
|
||
```
|
||
|
||
`official` 不是条目可以自报的属性。即使本仓库由 DesireCore 维护，第三方应用或服务也不能因此
|
||
自动成为 DesireCore 官方内容。正文中的 `sourceId`、`catalogSourceId` 或 `official` 声明会被
|
||
validator 拒绝；受信 Provider 身份只能由客户端同步器注入。
|
||
|
||
只有同时具备 HTTPS 不可变内容来源、已知许可证、分发策略、双维护者身份、品牌依据以及绑定到
|
||
同一 ref 的审核记录时，`availability` 才能写 `installable`。Git 分支名、`latest`、浮动包版本或
|
||
缺少 SHA-256 的制品只能保持 `listing-only`。
|
||
|
||
## 添加新条目
|
||
|
||
### 添加 Docker 应用
|
||
|
||
```bash
|
||
mkdir entries/my-app
|
||
|
||
# 1. 创建 manifest.json
|
||
cat > entries/my-app/manifest.json << 'EOF'
|
||
{
|
||
"id": "my-app",
|
||
"name": "My App",
|
||
"type": "docker-app",
|
||
"productKind": "application",
|
||
"entrypoints": [{ "id": "manage", "name": "委派 Agent 打开与维护 My App", "kind": "agent" }],
|
||
"version": "1.0.0",
|
||
"author": "Author",
|
||
"description": "一行功能描述",
|
||
"category": "tools",
|
||
"tags": ["tag1", "tag2"],
|
||
"icon": "linear-gradient(135deg, #3B82F6, #1D4ED8)",
|
||
"iconLetter": "M",
|
||
"platformSupport": ["macos", "windows", "linux"],
|
||
"fullDesc": "详细描述...",
|
||
"shortDesc": "简短描述...",
|
||
"install": {
|
||
"method": "docker",
|
||
"requirements": {
|
||
"docker": true,
|
||
"minMemory": "2GB",
|
||
"minDisk": "5GB",
|
||
"ports": [8080]
|
||
},
|
||
"configNeeded": ["Docker 运行环境"]
|
||
}
|
||
}
|
||
EOF
|
||
|
||
# 2. 创建 install.md（安装说明）
|
||
cat > entries/my-app/install.md << 'EOF'
|
||
# 安装 My App
|
||
|
||
## 环境要求
|
||
- Docker >= 20.10
|
||
|
||
## 安装步骤
|
||
1. 拉取镜像并启动容器：
|
||
```bash
|
||
docker run -d -p 8080:8080 --name my-app my-app:latest
|
||
```
|
||
|
||
## 验证
|
||
访问 http://localhost:8080 确认服务已启动。
|
||
EOF
|
||
|
||
# 3. 创建 usage.md（使用说明）
|
||
cat > entries/my-app/usage.md << 'EOF'
|
||
# 使用 My App
|
||
|
||
## 访问方式
|
||
浏览器打开 http://localhost:8080
|
||
EOF
|
||
```
|
||
|
||
新条目必须添加 `catalog-metadata.v1.json`。3.1 的全量迁移已经完成，根
|
||
`manifest.json#catalogMetadata.required` 为 `true`，CI 会阻断缺失 sidecar 的条目；
|
||
`legacyFallback` 继续保留，供尚未退出兼容窗口的旧客户端读取原始 manifest。
|
||
|
||
### 添加 MCP 服务
|
||
|
||
```bash
|
||
mkdir entries/my-mcp
|
||
|
||
cat > entries/my-mcp/manifest.json << 'EOF'
|
||
{
|
||
"id": "my-mcp",
|
||
"name": "My MCP",
|
||
"type": "mcp",
|
||
"version": "1.0.0",
|
||
"author": "Author",
|
||
"description": "一行功能描述",
|
||
"tags": ["tag1"],
|
||
"icon": "terminal",
|
||
"platformSupport": ["macos", "windows", "linux"],
|
||
"capabilities": ["capability_1", "capability_2"],
|
||
"toolCount": 5,
|
||
"install": {
|
||
"method": "npx",
|
||
"packageName": "@my-org/my-mcp",
|
||
"command": "npx",
|
||
"args": ["-y", "@my-org/my-mcp"]
|
||
},
|
||
"connection": {
|
||
"transport": "stdio",
|
||
"command": "npx",
|
||
"args": ["-y", "@my-org/my-mcp"]
|
||
}
|
||
}
|
||
EOF
|
||
```
|
||
|
||
### 添加 HTTP API 服务
|
||
|
||
```bash
|
||
mkdir entries/my-api
|
||
|
||
cat > entries/my-api/manifest.json << 'EOF'
|
||
{
|
||
"id": "my-api",
|
||
"name": "My API",
|
||
"type": "http-api",
|
||
"version": "1.0",
|
||
"author": "Author",
|
||
"description": "一行功能描述",
|
||
"tags": ["tag1"],
|
||
"icon": "globe",
|
||
"platformSupport": ["macos", "windows", "linux"],
|
||
"endpoint": "https://api.example.com/v1",
|
||
"capabilities": ["capability_1"]
|
||
}
|
||
EOF
|
||
```
|
||
|
||
HTTP API 通常不需要 install.md，只需 usage.md 说明如何调用。
|
||
|
||
### 添加第三方外部集成
|
||
|
||
external integration 不是开放的自助条目类型。新增 ID、URL、扩展 ID、组件或制品审核事实需要先修改严格 Schema、校验器与 DesireCore 客户端契约，并经过安全与合规 review；未知 ID 会失败关闭。请以 [`entries/kimi-webbridge/manifest.json`](entries/kimi-webbridge/manifest.json) 为唯一当前示例。
|
||
|
||
## 修改现有条目
|
||
|
||
1. 编辑 `entries/<id>/manifest.json` 中的字段
|
||
2. 如有安装/使用流程变更，同步更新 `install.md` / `usage.md`；external integration 不适用
|
||
3. 上游已发布新版本时更新 `version` 字段；它保留上游版本事实，仅修改目录元数据或格式不能伪造新产品版本
|
||
4. 新增或删除条目时同步更新根 `manifest.json#stats`
|
||
5. 执行 `npm ci && npm test`
|
||
6. 提交并创建 PR
|
||
|
||
## 版本规范
|
||
|
||
- `SCHEMA_VERSION`：数据格式版本，格式不兼容时递增主版本号
|
||
- `manifest.json#version`：仓库元数据版本，必须等于 `SCHEMA_VERSION`
|
||
- `manifest.json#dataVersion`：仓库数据版本，必须等于 `SCHEMA_VERSION`
|
||
- `entries/<id>/manifest.json#version`：条目自身版本
|
||
|
||
**Schema 版本历史：**
|
||
|
||
| 版本 | 说明 |
|
||
|------|------|
|
||
| 1.0.0 | 初始格式 — 单文件 JSON 数组 |
|
||
| 2.0.0 | 分散式目录 — apps/mcp/services 三目录，每个条目 `<id>/index.json` |
|
||
| 3.0.0 | 统一 entries/ 目录，manifest.json + install.md + usage.md |
|
||
| 4.0.0 | Draft-07 严格判别 Schema、仓库校验和 listing-only external integration |
|
||
| 4.1.0 | 原生应用、不可变制品与 App 生命周期边界 |
|
||
| 4.2.0 | **当前** — 应用/插件身份、纯声明 artifact、宿主贡献与直接能力依赖 |
|
||
|
||
## 校验
|
||
|
||
```bash
|
||
npm ci
|
||
npm test
|
||
```
|
||
|
||
校验包含 JSON Schema、目录与 ID、全局唯一性、根版本、统计、来源注入字段、贡献/入口 ID 唯一性、应用与插件关系、artifact 无进程约束、sidecar 一致性、external 单文件布局、固定 Kimi ID、完整官方 URL、扩展 ID、组件/权限/准入集合、真实日历日期和不可变供应链审核记录。条件块使用 Draft-07 的父约束补充语义；Ajv 保留严格关键字检查，关闭 `strictTypes/strictRequired` 的额外作者风格限制，不降低数据值校验。
|
||
|
||
Schema v4 同时保留 `catalog-metadata.v1.json` 统一目录 sidecar、strict validator 与 legacy fallback。
|
||
|
||
## 本地验证
|
||
|
||
本仓库的验证器只依赖 Node.js 22，不联网、不读取 Git 历史，也不会把当前时间伪造成目录事实：
|
||
|
||
```bash
|
||
# 逐条验证根 stats、目录 ID、legacy manifest 与全部 sidecar
|
||
node scripts/catalog/validate-registry.mjs --require-sidecars
|
||
|
||
# 机器可读报告
|
||
node scripts/catalog/validate-registry.mjs --json
|
||
|
||
# 正反 fixture 与当前目录兼容回归
|
||
node --test scripts/catalog/*.test.mjs
|
||
```
|
||
|
||
证据路径必须是安全相对路径，禁止绝对路径和 `..` 穿越。离线 validator 只证明字段结构、路径安全
|
||
和 ref/digest 一致性，不把网络不可达或未验证的远端事实伪造成通过。
|
||
|
||
## 同步机制
|
||
|
||
DesireCore 客户端的同步流程：
|
||
|
||
1. 启动时检查本地缓存（2 分钟 TTL）
|
||
2. 缓存过期时 `git fetch` 检查更新
|
||
3. 有新 commit 时 `git pull` 并重建本地索引
|
||
4. 离线时使用本地缓存或内置 fallback 数据
|
||
|
||
客户端读取 `entries/` 目录下所有 `manifest.json`，按 `type` 字段分类为应用、MCP 服务、HTTP 服务和第三方外部集成展示在商店中。旧三类条目的 `install.md` 和 `usage.md` 可供 AI Agent 执行安装和配置时使用；external integration 只有结构化 manifest，且 listing-only 条目不会被派生为 Docker 应用、installed-entry、ready 连接或 Browser Provider。
|
||
|
||
本仓库的 `scripts/validate-registry.mjs` 只服务 Registry 自身的 CI 与贡献者本地检查。主仓库
|
||
`npm run sync-registry` 把 checkout 视为待验证数据，使用主仓受审的固定 Schema、策略与 commit
|
||
门禁校验后再打包，**绝不执行本 checkout 携带的脚本**。两侧任一校验失败都不能生成新的
|
||
`defaults/registry.zip`。
|
||
|
||
`.gitattributes` 将所有文本固定为 LF；这是跨平台信任边界的一部分。主仓固定 authored Schema
|
||
与受审内容摘要，Windows checkout 不得把已审核的 JSON/Markdown 改写为 CRLF，否则运行时会
|
||
按哈希不匹配失败关闭整个官方 v4 目录。
|
||
|
||
## 贡献指南
|
||
|
||
1. Fork 本仓库
|
||
2. 在 `entries/` 下创建以 ID 命名的子目录
|
||
3. 按上述格式添加 `manifest.json`，旧三类按需添加 `install.md` 和 `usage.md`
|
||
4. 更新根目录 `manifest.json` 中的 `stats` 统计
|
||
5. 执行 `npm ci && npm test`
|
||
并运行 `node --test scripts/catalog/*.test.mjs` 与 `node scripts/catalog/validate-registry.mjs --require-sidecars`
|
||
6. 提交 PR 并描述变更内容、来源和验证结果
|
||
7. 等待审核合并
|
||
|
||
external integration 需要额外安全、供应链、商标和隐私 review，不接受绕过严格 Schema 的未知 ID 或自由文本安装说明。
|
||
|
||
## 镜像
|
||
|
||
- GitHub（主）：https://github.com/desirecore/registry.git
|
||
- git.hxr.so（镜像）：https://git.hxr.so/desirecore/registry.git
|