---
title: "私有商店：在 Halo 里添加公司自己的商店来源"
description: "在 Halo 的设置 › 应用商店里管理商店来源：认识 5 个内置来源，添加公司自建的私有源，开关或移除来源，并弄清私有源需要提供哪些文件。"
type: "how-to"
audience: ["admin"]
related: ["digital-humans/store", "developers/dhp", "advanced/security"]
lang: "zh-CN"
canonical: "https://hello-halo.cc/docs/advanced/private-store.html"
last_updated: "2026-10-19T00:11:17+08:00"
source: "Halo 3.0.4 docs"
---
# 私有商店

在 Halo 的设置 › 应用商店里管理商店来源：认识 5 个内置来源，添加公司自建的私有源，开关或移除来源，并弄清私有源需要提供哪些文件。

::: say
> 在商店来源里加上公司的源：https://store.example.com

Halo 会把这个地址加进 **设置 › 应用商店**，之后在 [商店](https://hello-halo.cc/docs/digital-humans/store.html) 里就能看到这个源里的数字人和技能。它也能帮你开关、移除来源。

**前提**：在输入框 **＋ › 能力** 里打开 **操作 Halo**。AI 加来源时不会弹确认框。
:::

## 开始之前 {#before-you-start}

**设置 › 应用商店** 管的是商店的 **来源**，不是商店本身。浏览和安装在侧边栏的 **商店** 里进行，见 [商店](https://hello-halo.cc/docs/digital-humans/store.html)。商店把所有已打开的来源合在一起显示，搜索也覆盖全部来源。

搭私有商店，你需要：

- 一个同事的电脑都能访问的网址，用来放静态文件（任何能托管静态网页的服务都行）
- 按 [私有源要提供什么](#registry-format) 准备好的索引和软件包
- 每位同事在自己的 Halo 里加一次这个来源。来源保存在每台电脑自己的设置里，不会自动同步

## 内置来源 {#sources}

打开 **设置 › 应用商店**，说明文字是「管理用于发现和安装应用的注册表源」。从官网下载的 Halo 内置 5 个来源，默认全部打开：

| 显示名称 | 类型标签 | 提供什么 |
|---|---|---|
| Digital Human Protocol | Halo | 数字人、技能、MCP。这是官方源，总排第一，也是主来源：商店的分类和发现页布局都来自它 |
| MCP Official Registry | MCP | MCP 服务器，实时查询 |
| Smithery | Smithery | MCP 服务器，实时查询。下面有一个可选的 **Smithery API密钥（可选）** 输入框，填好后点 **保存** |
| Claude Skills Registry | Claude Skills | 约 100 个精选技能，安装时从 GitHub 下载文件 |
| SkillHub (33k+ Skills) | skillhub | 社区技能，实时查询。服务部署在国内 |

每一行显示名称、类型标签、地址和一个开关。数字人只来自 Halo 类型的来源（官方源和你加的自定义源）。

::: info
公司提供的 Halo 可能显示不同的来源，见 [公司提供的 Halo](#company-builds)。
:::

## 添加自定义来源 {#add-source}

1. 打开 **设置 › 应用商店**，点列表下方的 **添加注册表**。
2. 在 **名称** 里填一个同事认得出的名字，例如「公司商店」。
3. 在 **URL** 里填私有源的根地址，例如 `https://store.example.com`。末尾的 `/` 会被去掉。
4. 点 **添加**。新来源出现在列表最后，开关是打开的。

表单没有类型选项：自定义来源一律按 Halo 静态来源（DHP 静态格式）读取，列表里不显示类型标签。

地址的要求：

| 要求 | 不满足时看到 |
|---|---|
| 名称和 URL 都要填 | 「名称为必填项」或「URL 为必填项」 |
| 是一个完整的网址 | 「请输入有效的 URL」 |
| 以 `http://` 或 `https://` 开头 | `Registry URL must use http:// or https://` |
| 不是 `localhost`、`127.0.0.1` 或 `10.x`、`172.16–31.x`、`192.168.x`、`169.254.x` 这类内网 IP 地址 | `Registry URL must point to a public host (loopback, private, and link-local addresses are not allowed)` |
| 列表里没有同一个地址 | `Registry already exists: 公司商店`（显示已有来源的名字） |

Halo 只检查直接写成 IP 的地址。内网服务请用域名访问，例如 `https://store.example.com`。

::: done
回到侧边栏的 **商店**，私有源里的数字人出现在 **数字人** 标签，技能出现在 **技能** 标签，就说明加好了。新来源要先下载一次索引，没马上出现就点 **刷新**。
:::

## 开关和移除来源 {#manage-sources}

| 操作 | 怎么做 | 结果 |
|---|---|---|
| 关闭来源 | 关掉这一行的开关 | 它的内容不再出现在浏览、搜索和分类计数里。本地缓存保留，重新打开时不用重新下载。已经装好的内容照常可用 |
| 打开来源 | 打开开关 | 内容回到商店 |
| 移除自定义来源 | 点这一行右侧的 **移除注册表**（垃圾桶图标） | 来源和它的本地缓存被删掉，已经装好的数字人和技能不会被卸载。没有确认框，想恢复就重新添加 |
| 调整顺序 | 不支持 | 官方源总在第一位，新加的来源排在最后 |

内置来源不能删，只能关。SkillHub 那一行虽然也显示垃圾桶图标，但点了会失败，列表上方显示 `Cannot remove a built-in registry`。不想用 SkillHub 就关掉它的开关。

任何改动之后，商店列表都会立即重新加载。

## 商店多久刷新一次 {#refresh}

在私有源里发了新版本，同事那边多久能看到：

| 时机 | 发生什么 |
|---|---|
| Halo 启动时 | 下载各静态来源的索引，存进本机缓存（缓存 1 小时） |
| 切回 **商店** 的某个标签，或切回 Halo 窗口 | 发一次很轻的「有没有变化」检查，两次至少间隔 2 秒。有变化就重新加载列表 |
| 点商店里的 **刷新** | 强制完整地重新检查一遍 |
| 某个来源加载失败或为空 | 后台重试，最多每 30 秒一次。一个来源出错不会让整个商店变空，其他来源照常显示 |
| 实时查询的来源（SkillHub、MCP Official Registry、Smithery） | 查询结果缓存 5 分钟 |

所以发布新版本后，同事切回商店就能看到；急的话让他们点 **刷新**。

## 更新怎么到达已装的内容 {#upgrade-strategy}

Halo 在启动 60 秒后检查一次已装内容的更新，之后每 6 小时检查一次。只检查从商店装的、正在启用的内容，版本号按 semver 比较，无法解析的版本号按主要版本处理。

每个数字人可以在 **数字人 › 某个数字人 › 能力与设置 › 高级 › 升级 › 升级策略** 里选择怎么处理更新：

| 升级策略 | 实际行为 |
|---|---|
| **自动（静默安装补丁/次要更新）**（默认） | 补丁和次要版本（如 1.2.0 → 1.2.1、1.3.0）直接装上，不打扰你；主要版本（如 2.0.0）先问你 |
| **仅通知** | 每次有更新都提示，不自动安装 |
| **手动** | 界面说明是「不自动检查升级。使用「检查升级」按需更新。」，但后台检查照常运行，商店详情页照样出现 **更新至** 按钮，只是从不自动安装 |

旁边的 **检查升级** 会立即检查一遍。更新对话框里还能选 **跳过此版本**，只对这一个版本生效。

对私有商店来说，这意味着：你在私有源里把某个数字人从 1.0.0 升到 1.0.1，同事电脑上默认会在 Halo 下次同步商店目录之后的更新检查里自动装上；升到 2.0.0 则会先问他们。同步商店目录发生在 Halo 启动时、打开商店页面（或切回它）时，以及点 **刷新** 时；每 6 小时一次的更新检查只读已同步的目录。

## 私有源要提供什么 {#registry-format}

自定义来源按 DHP 静态格式读取，一组放在网址下的静态文件就够了，不需要专门的服务端。完整格式见 [DHP 协议](https://hello-halo.cc/docs/developers/dhp.html)，发布流程见 [发布到商店](https://hello-halo.cc/docs/developers/store-publishing.html)。

| 文件（相对来源根地址） | 内容 |
|---|---|
| `digital-humans.json`、`skills.json`、`mcps.json` | 分开的索引，优先读取。三个文件缺任何一个，Halo 就改读 `index.json` |
| `index.json` | 单文件索引，分开的索引不全时使用 |
| 条目路径下的 `spec.yaml` | 每个数字人或技能的定义，路径取自索引条目的 `path` |
| 条目路径下的 `files/` | 技能的文件，例如 `files/SKILL.md`（商店详情页的文档就读它） |
| 条目路径下的 `skills/` 加技能 ID | 数字人内嵌的技能文件 |

只放数字人的私有源，也要提供 `skills.json` 和 `mcps.json`：内容是完整的索引对象，`apps` 为空数组 `[]`，`version`、`generated_at`、`source` 和下面的示例一样。只写一个 `[]` 会校验失败，Halo 会改读 `index.json`。也可以干脆只用一个 `index.json`。

官方源的仓库把每个数字人放在 `packages/digital-humans/` 加 slug 的目录下，再生成索引。自建时照这个结构最省事。索引大致长这样：

```json
{
  "version": 1,
  "generated_at": "2026-10-18T00:00:00Z",
  "source": "https://store.example.com",
  "apps": [
    {
      "slug": "ops/daily-report",
      "name": "日报助手",
      "version": "1.0.0",
      "author": "ops",
      "description": "每天汇总运营数据，发到群里",
      "type": "automation",
      "path": "packages/digital-humans/daily-report"
    }
  ]
}
```

`type` 为 `automation` 的是数字人，`skill` 是技能。`slug` 可以是 `daily-report` 这样的单段，也可以是 `ops/daily-report` 这样带作者的两段。

::: tip
托管服务返回 `ETag` 时，Halo 的「有没有变化」检查只需几次条件请求（每个索引文件一次），索引没变就不会重新下载。
:::

静态私有源只提供目录和下载。下面这些功能要靠 DHP v2 商店服务器，并且要由公司版把主来源指向它：登录后发布、**我的** 和「我的发布」、服务端审核消息、安装次数、「精选」标记、排行榜和场景专题。

## 公司提供的 Halo {#company-builds}

公司可以在打包 Halo 时预设商店来源：

- 把官方源改成指向公司自己的商店服务器，名称和地址每次启动都会重新套用
- 隐藏某个内置来源：它从列表里消失，缓存也被清掉
- 固定某个来源的开关状态，用户改了也会在下次启动时恢复

常见做法是把官方源指向公司的 DHP v2 商店服务器，再隐藏其他 4 个来源，商店就变成只有公司内容的私有商店。

::: info
公司提供的 Halo 可能显示不同的来源，或者少了某些来源。以你屏幕上 **设置 › 应用商店** 里的列表为准。
:::

## 只添加你信任的来源 {#safety}

::: danger
装一个数字人或技能，就是让 AI 按它的说明和脚本做事，而且拥有 AI 的全部权限：读写文件、执行命令、上网，不会逐次确认。来源里的内容一旦更新，默认的 **自动** 策略还会静默装上补丁和次要版本。只添加你信任的来源，并控制谁能往私有源里发布。详见 [AI 执行工具不会逐次确认](https://hello-halo.cc/docs/advanced/security.html#tool-permissions)。
:::

- 私有源尽量用 `https://`，避免下载内容在传输中被改
- 关掉不需要的内置来源，可以减少 Halo 对外的请求
- 想让同事只能装公司审过的内容，用 [公司提供的 Halo](#company-builds) 隐藏其他来源

## 遇到问题 {#troubleshooting}

### 添加时提示 `Registry URL must point to a public host`

地址里直接写了 `localhost` 或内网 IP。给私有源配一个域名，用 `https://store.example.com` 这样的地址再加一次。

### 添加时提示 `Registry already exists`

列表里已有同一个地址的来源，提示里带着它的名字。地址末尾多一个 `/` 也算同一个地址。

### 点 SkillHub 的垃圾桶，提示 `Cannot remove a built-in registry`

SkillHub 是内置来源，不能删。关掉它的开关就不会再显示它的内容。

### 加好了来源，商店里却看不到内容

1. 在浏览器里打开 `https://store.example.com/digital-humans.json`（或 `index.json`），确认能从这台电脑访问到。
2. 检查三个分开的索引是否齐全；缺一个时 Halo 会改读 `index.json`，两边都没有就读不到内容。
3. 检查索引条目的必填项：`slug`、`name`、`version`、`author`、`description`、`type`、`path`。
4. 回到商店点 **刷新**。

### 私有源发了新版本，商店里还是旧的

切回商店的标签或点 **刷新**。已装的内容要等下一次更新检查（启动后 60 秒、之后每 6 小时）；想马上检查，先在商店点 **刷新**，再在数字人的 **升级** 设置里点 **检查升级**。

## 下一步 {#next-steps}

- [商店](https://hello-halo.cc/docs/digital-humans/store.html)：同事怎么在商店里浏览、安装和更新私有源里的内容
- [DHP 协议](https://hello-halo.cc/docs/developers/dhp.html)：索引和 `spec.yaml` 的完整格式
- [安全、隐私与数据流](https://hello-halo.cc/docs/advanced/security.html)：交给安全评审前，先看 Halo 会连接哪些地址、AI 有哪些权限