分类、正式注册表与安全迁移

StarHub 同时支持普通分类和正式分类注册表。两者都显示在左侧分类栏，但用途不同。

1. 核心概念

普通分类

普通分类包含稳定的本地 id、名称、颜色、可选 Emoji 和仓库关系。适合临时整理、个人快速标注或尚未确定的分类体系。

正式分类注册表

正式注册表是在普通分类基础上增加结构化元数据：

字段	作用
`registryKey`	跨导入版本识别同一语义分类的稳定键
`sourceVersion`	本次导入的注册表版本
`nameZh` / `nameEn`	中英文正式名称
`aliases`	同义名称和缩写，用于迁移匹配与 AI 理解
`descriptionZh` / `descriptionEn`	分类边界说明
`examples`	典型仓库、技术或主题
`exclusions`	容易混淆但不属于该分类的内容
`level1` / `level2`	可选层级和侧栏短名称

StarHub 不提供统一的个人分类清单。每位用户自行决定分类数量、层级和边界。

仓库关系

repoTags 是仓库—分类关系的唯一事实来源。Tag.repos 仅在读取时派生，不能写回 tags 表。

2. 创建普通分类

在左侧“分类”标题旁点击“+”：

输入名称；
选择颜色；
可选填写 Emoji；
保存。

新分类会尽量使用当前列表中较少使用的颜色。普通分类可以稍后通过正式注册表导入转为受管理分类。

3. 为仓库分配分类

单个仓库

打开详情面板，在分类编辑区域添加或移除分类。一个仓库可拥有多个分类。

批量添加

批量“添加”只增加所选分类，不移除已有关系。

批量替换

批量“设置/替换”会把所选仓库的分类集合替换成当前选择。未选择任何分类时等于清空分类，提交前会二次确认。

批量提交逐仓库执行；部分失败时，失败仓库保持选中以便重试。

4. 导入入口和格式

入口：分类工具 → 导入分类。

支持：

每行一个名称；
逗号、中文逗号、分号、中文分号或 Tab 分隔；
TXT、CSV；
JSON 字符串数组；
JSON 对象数组；
{ "tags": [...] }；
StarHub 备份 { "data": { "tags": [...] } }。

格式限制

正式注册表顶层字段当前必须使用 tags，不识别 categories。建议在应用中先查看预览，定义数量为 0 时不要提交。

仅名称示例

text

GIS
GeoAI
交通预测
城市气候

仅名称也会生成稳定的本地 registryKey 和默认说明，但缺少明确边界。要供 AI 长期使用，建议补全别名、说明、示例和排除项。

完整注册表示例

json

{
  "version": "team-taxonomy-2026-08",
  "tags": [
    {
      "categoryId": "geo.web-mapping",
      "nameZh": "WebGIS 与在线地图",
      "nameEn": "Web GIS and Web Mapping",
      "aliases": ["WebGIS", "Web Mapping"],
      "descriptionZh": "浏览器地图、在线空间服务和 WebGIS 应用。",
      "descriptionEn": "Browser mapping, online spatial services, and Web GIS applications.",
      "examples": ["Leaflet", "OpenLayers", "MapLibre"],
      "exclusions": ["纯桌面 GIS", "仅空间数据库驱动"],
      "level1": "GIS 与空间计算",
      "level2": "WebGIS 与在线地图",
      "color": "#2563EB",
      "emoji": "🗺️"
    }
  ]
}

字段兼容：

稳定键可使用 categoryId、registryKey 或 sourceId；
中文名称可使用 nameZh 或 name；
description 可作为中文说明；
keywords 可作为 examples；
列表字段既可使用数组，也可使用逗号或分号分隔字符串。

导入限制：

名称最长 120 个字符；
说明最长 1000 个字符；
别名、示例、排除项分别最多 30 个；
重复名称和重复 registryKey 会在解析阶段忽略；
空项和无法识别的项计入“无效”。

5. 迁移预览如何判断

导入后不会立即写库。系统先根据 registryKey、当前名称、中英文名称和别名计算预览：

状态	含义	写入行为
新增	没有匹配分类	创建确定性 ID 的正式分类
重命名	稳定分类已存在但名称变化	保留 ID，只修改名称和元数据
合并	多个现有分类匹配同一导入项	选择目标分类并迁移、去重全部关系
更新	名称相同但说明、别名或版本变化	更新注册表元数据
不变	与当前版本一致	不修改
冲突	ID 被占用、一个分类匹配多个导入项或正式键不一致	阻止整批提交

名称匹配会进行 NFKC、大小写、空格和常见标点归一化，但不会进行不可解释的语义猜测。

截图待补：迁移预览 同时展示一个新增、一个重命名、一个合并和一个冲突；冲突存在时“应用”按钮应禁用。

6. 事务、备份和回滚

应用迁移时：

读取当前 tags 和 repoTags；
创建完整 categoryMigrationSnapshots 快照；
在共享 dataMutationQueue 中开始事务；
写入新分类状态；
重映射并去重仓库关系；
任一步失败则回滚整个事务；
只保留最近 10 份本地迁移快照。

分类管理中的“撤销上次迁移”恢复最近快照中的全部分类和关系，并删除已经使用的快照。

WARNING

迁移快照只存在当前浏览器，不进入备份 v4。执行大规模迁移前仍应下载一份 StarHub 备份。

7. 分类管理

入口：分类工具 → 管理。

支持：

搜索中文名、英文名和别名；
按名称、项目数升序/降序、更新时间排序；
只看空分类；
编辑名称、说明、别名、示例、排除项、层级和外观；
把来源分类合并到目标分类；
撤销最近一次迁移。

安全重命名

重命名只更新显示元数据，不改变 tag.id，因此 repoTags 和 AI 任务引用不会因名称变化而失效。

手动合并

选择来源和目标后，系统先创建快照，再把来源关系映射到目标、去重并删除来源分类。合并是有方向的：目标分类的 ID 保留。

8. 正式注册表和 AI

只要至少存在一个 registry.managed = true 的分类：

AI 候选集合只包含正式分类；
普通分类继续保留在界面和仓库关系中，但不发送给模型；
注册表内容生成 registry-v2-* 哈希；
任务写入前再次检查版本；
注册表变化后，旧任务会被阻止继续执行或提交。

这是为了避免模型在任务中途看到一套分类，写入时却面对另一套分类。

9. 删除分类

删除单个分类会删除该分类以及对应 repoTags，不会删除仓库或取消 GitHub Star。

“删除全部”会删除所有分类和关系，也不会删除仓库。该操作本身没有分类迁移撤销，执行前应导出备份。

10. 分类设计建议

registryKey 表达稳定语义，不要包含年份或显示语言；
名称简短，边界写在 description；
用别名承接旧名称和缩写；
示例用于说明“应该放什么”，排除项用于说明“容易误分什么”；
level2 适合作为侧栏短名称；
不要用颜色承担唯一语义；
先用 100–200 个仓库验证分类边界，再大规模运行 AI；
同义分类使用合并，不要先删除再重建。

当前限制

只有最近一次迁移可以直接一键撤销；
快照保存完整关系，分类很多时占用空间较大；
迁移快照不随备份导出；
普通分类与旧分类预设仍是不同概念；
尚无跨设备注册表同步或在线注册表市场。

分类、正式注册表与安全迁移 ​

1. 核心概念 ​

普通分类 ​

正式分类注册表 ​

仓库关系 ​

2. 创建普通分类 ​

3. 为仓库分配分类 ​

单个仓库 ​

批量添加 ​

批量替换 ​

4. 导入入口和格式 ​

仅名称示例 ​

完整注册表示例 ​

5. 迁移预览如何判断 ​

6. 事务、备份和回滚 ​

7. 分类管理 ​

安全重命名 ​

手动合并 ​

8. 正式注册表和 AI ​

9. 删除分类 ​

10. 分类设计建议 ​

当前限制 ​

下一步 ​