refactor: unify skill source model

skiff/source-model.md

@@ -25,7 +25,7 @@ skiff 当前使用 `owned` 表示本仓库 `skills/` 中维护的 Skill，同时
 来源都可以包含一个或多个 Skill；除 builtin 外，catalog 和 custom 都可以使用
 Git 仓库或本地目录。
 
-## 当前模型
+## 迁移前模型
 
 ```mermaid
 flowchart TD
@@ -46,7 +46,7 @@ flowchart TD
     R2 --> E
 ```
 
-当前实现中：
+迁移前实现中：
 
 - `list` 和 `status` 支持 owned、registry 和 custom source。
 - `resolve_skill_source` 可以解析三种来源并处理同名歧义。
@@ -54,7 +54,7 @@ flowchart TD
 - `.skills.yaml` 默认将未声明来源的 Skill 解释为 `owned`。
 - custom source 的 `skills_path` 已经可以包含多个 Skill，本质上也是 collection。
 
-## 推荐模型
+## 现行模型
 
 ```mermaid
 flowchart TD
@@ -86,7 +86,7 @@ flowchart TD
 | 类型 | 含义 | 配置来源 | 用户界面展示 |
 | --- | --- | --- | --- |
 | `builtin` | 随当前 skiff 仓库提供 | `skills/` | `builtin` |
-| `catalog` | skiff 预先登记、所有用户可发现的来源 | `catalog.yaml`，迁移前为 `registry.yaml` | `catalog:<name>` |
+| `catalog` | skiff 预先登记、所有用户可发现的来源 | `catalog.yaml` | `catalog:<name>` |
 | `custom` | 用户在本机显式注册的命名来源 | `~/.config/skiff/config.yaml` | `custom:<name>` |
 
 `builtin` 比 `owned` 更适合作为用户可见名称，因为它表达 Skill 的分发位置和可用
@@ -166,9 +166,9 @@ skills:
 custom source 在 manifest 中继续保存其逻辑名称，例如 `company`。这样不同机器可以
 独立配置仓库地址，而项目只依赖稳定的来源名称。
 
-## 兼容迁移
+## 兼容策略
 
-这是一次用户可见术语调整，应提供兼容层，避免已有项目立即失效：
+用户可见术语已经调整，并保留以下读取兼容，避免已有项目立即失效：
 
 1. 对外文档、CLI 输出和 selector 统一使用 `builtin`、`catalog:<name>` 和
    `custom:<name>`。
@@ -177,22 +177,21 @@ custom source 在 manifest 中继续保存其逻辑名称，例如 `company`。
 4. CLI 参数在过渡期继续接受 `--source owned`，但帮助和输出只推荐 `builtin`。
 5. 读取旧 manifest 中的 `source: registry` 和 `registry: <name>`，归一化为
    `catalog:<name>`。
-6. `registry.yaml` 可以先保留文件名，仅将用户界面术语改为 catalog；单独迁移为
-   `catalog.yaml` 时，应兼容读取旧文件。
+6. 主文件使用 `catalog.yaml`；不存在时兼容读取旧 `registry.yaml`。
 7. custom source 的逻辑名称和现有 `config.yaml` 结构保持不变。
 8. 将 `builtin`、`catalog` 和兼容别名 `owned`、`registry` 设为 custom source
    保留字。
 9. `select` 同步接入 custom Skill，并让 custom collection 与 catalog collection
    使用相同的父子展示逻辑。
 
-## 影响范围
+## 实现范围
 
-实施时预计涉及：
+当前实现覆盖：
 
 - `skiff/skills.py`：来源解析、归一化和 builtin 命名。
 - `skiff/project.py`：manifest 默认值、序列化与旧值兼容。
 - `skiff/sources.py`：来源保留字。
-- `skiff/registry.py`：逐步重命名为 catalog 概念。
+- `skiff/catalog.py`：catalog 配置、checkout 与 Skill 发现。
 - `skiff/cli.py`：`list`、`status`、`add`、`select` 和输出文案。
 - `skiff/selector.py`：统一 catalog/custom collection 的父子展示。
 - CLI 与来源解析测试。
@@ -213,7 +212,6 @@ custom source 在 manifest 中继续保存其逻辑名称，例如 `company`。
 
 ## 设计前提
 
-本方案假设 `registry.yaml` 当前的真实职责是维护 skiff 预置的来源目录，而不是提供
-远程发布、版本解析或可信签名等注册中心能力。因此推荐逐步将用户可见概念改为
-`catalog`。如果未来实现真正的远程 registry，再单独定义其协议和与 catalog 的同步
-关系，不复用当前含义模糊的名称。
+迁移前 `registry.yaml` 的真实职责只是维护 skiff 预置的来源目录，而不是提供远程
+发布、版本解析或可信签名等注册中心能力，因此现已改为 `catalog.yaml`。如果未来
+实现真正的远程 registry，应单独定义其协议和与 catalog 的同步关系，不复用旧名称。