package.schema.json 字段说明#

const record = {
  schemaVersion: 2, // 当前公共契约版本。
  id: "dsh.example-skin", // 跨版本和投影稳定的逻辑 ID。
  name: "example-skin", // 源内包名。
  displayName: "Example Skin", // 网页显示名。
  version: "1.4.0", // 上游原始版本。
  versionScheme: "semver", // 仅作为比较提示。
  description: "A GUI skin plugin for DSH.", // 人类可读描述。
  releaseNotes: "Adds compact navigation icons.", // 本版本说明。
  license: "MIT", // 上游许可证声明，不代表法律核验。
  links: { // 所有链接都只做索引。
    repository: "https://github.com/example/example-skin", // 源码仓库。
    homepage: "https://example.com/example-skin", // 项目主页。
    readme: "https://github.com/example/example-skin#readme", // README 链接。
    license: "https://github.com/example/example-skin/blob/v1.4.0/LICENSE", // LICENSE 链接。
    documentation: "https://example.com/example-skin/docs", // 文档链接。
    changelog: "https://github.com/example/example-skin/blob/v1.4.0/CHANGELOG.md", // 变更记录。
    issues: "https://github.com/example/example-skin/issues", // 问题追踪。
  },
  keywords: ["gui", "skin", "desktop"], // 自由文本搜索词。
  maintainers: [{ // 维护者声明。
    name: "Example Maintainer", // 姓名。
    url: "https://github.com/example", // 主页。
    email: "[email protected]", // 联系地址。
    role: "maintainer", // 角色。
  }],
  platform: { // 平台提示，不是可用性保证。
    os: ["linux", "windows"], // 操作系统。
    arch: ["x86_64", "arm64"], // CPU 架构。
    libc: ["glibc"], // libc。
    runtime: ["nodejs>=20"], // 运行时。
  },
  type: "plugin", // 一级分类。
  subtype: "skin", // 管理员定义的唯一 subtype。
  pluginDetails: { // plugin 专用信息。
    manifestPath: ".dsh/plugin.json", // 插件 manifest 路径。
    sourceType: "github-repo", // 上游来源平台与形式。
    marketplaceUrl: "https://example.com/marketplace/example-skin", // 市场页。
    entrypoint: "dist/index.js", // 入口。
    permissions: ["filesystem.workspace-read"], // 上游声明的权限。
  },
  targets: [{ // Agent 兼容目标。
    agentId: "dsh", // Agent 稳定 ID。
    agentVersionRange: "^0.2.0", // 可解析范围。
    versionScheme: "semver", // Agent 版本规则。
    compatibilityStatus: "known", // 已提供可解析范围。
    targetMetadata: { desktop: true }, // 目标专属元数据。
    installMetadata: { mode: "plugin" }, // 安装器可用提示。
    status: "active", // 目标生命周期。
  }, {
    agentId: "future-agent", // 另一个 Agent。
    agentVersionRange: null, // 未提供可解析范围时必须为 null。
    versionScheme: "unknown", // 不确定版本方案。
    compatibilityStatus: "unknown", // 只允许展示，不参与自动交集。
    compatibilityNote: "Upstream did not publish a parseable range.", // 必填说明。
    targetMetadata: {}, // 可为空对象。
    installMetadata: {}, // 可为空对象。
    status: "experimental", // 目标状态。
  }],
  distributions: [{ // 插件本体发行候选，不是元数据镜像。
    id: "github-release", // 候选稳定 ID。
    type: "release", // 发行方式。
    url: "https://github.com/example/example-skin/releases/download/v1.4.0/example-skin.zip", // 下载或访问地址。
    agentIds: ["dsh"], // 适用 Agent。
    version: "1.4.0", // 候选版本。
    ref: "v1.4.0", // Git/Release 引用。
    registry: "github", // 发行平台名称。
    priority: 10, // 数字越小优先级越高。
    regions: ["global"], // 地区提示。
    checksum: { sha256: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }, // 声明的摘要。
    signature: { // 声明的签名材料。
      url: "https://github.com/example/example-skin/releases/download/v1.4.0/example-skin.zip.sig", // 签名地址。
      type: "sigstore", // 签名类型。
      keyId: "example-key", // 可选 key ID。
      keyUrl: "https://example.com/keys/example.asc", // 可选 key 地址。
    },
    install: { // 安装提示，不自动执行。
      type: "url", // 安装提示类型。
      url: "https://github.com/example/example-skin/releases/download/v1.4.0/example-skin.zip", // 安装地址。
      command: "dsh plugin install example-skin", // 示例命令。
      scriptIntegrity: "sha256-BASE64-VALUE", // 脚本完整性声明。
      requires: ["dsh>=0.2.0"], // 前置条件。
      notes: "Review the upstream instructions before execution.", // 注意事项。
    },
    notes: "Primary global distribution.", // 候选备注。
  }],
  dependencies: [{ // 普通依赖。
    id: "dsh.ui-runtime", // 依赖 ID。
    versionRange: "^0.2.0", // 依赖版本范围。
    versionScheme: "semver", // 范围规则。
    agentId: "dsh", // 依赖适用 Agent。
    optional: false, // 是否可选。
    reason: "Provides the desktop extension host.", // 依赖原因。
  }],
  conflicts: [{ id: "dsh.legacy-theme", versionRange: "<2.0.0", versionScheme: "semver", agentId: "dsh", optional: false, reason: "Both replace the same theme slot." }], // 冲突声明。
  provides: [{ id: "dsh.gui.skin", versionRange: "1.4.0", versionScheme: "semver", agentId: "dsh", optional: false, reason: "Provides the skin capability." }], // 提供的能力。
  replaces: [{ id: "dsh.example-skin-old", versionRange: "*", versionScheme: "custom", agentId: "dsh", optional: false, reason: "Successor package." }], // 替代关系。
  facets: { // 管理员维护的受控 facet。
    capabilities: ["gui.modify"], // 能力。
    effects: ["user-config.modify"], // 影响。
    dataPractices: ["public:read"], // 数据类别和动作声明。
    permissions: ["filesystem.workspace-read"], // 权限。
    runtime: ["interactive.required"], // 运行环境。
    integrations: ["agent-ui"], // 集成方式。
  },
  customFacets: { // 用户自定义、未核验 facet。
    capabilities: ["theme.preview"], // 自定义能力。
    effects: ["desktop.appearance.modify"], // 自定义影响。
    dataPractices: ["telemetry:unknown"], // 自定义数据声明。
    permissions: [], // 可为空。
    runtime: ["gpu.optional"], // 自定义运行提示。
    integrations: ["community-dashboard"], // 自定义集成。
    other: ["community-entered"], // 其他自定义标签。
  },
  lifecycle: { // 生命周期。
    status: "active", // 当前状态。
    reason: "Maintained upstream.", // 状态原因。
    replacementId: "dsh.example-skin-next", // 可选替代包。
    since: "2026-09-30T16:00:00Z", // 状态生效时间。
  },
  createdAt: "2026-09-01T00:00:00Z", // 创建时间。
  updatedAt: "2026-09-30T15:00:00Z", // 更新时间。
  publishedAt: "2026-09-30T16:00:00Z", // 公共发布时间。
  _meta: { // 命名空间扩展，项目不解释其值。
    "org.example/review": { importedBy: "community" }, // 示例扩展。
  },
} as const;