scriptoriumadmin/skillhub
1
0
Fork 0
mirror of https://github.com/iflytek/skillhub.git synced 2026-08-27 11:14:59 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

docs: rename project to skillhub

Browse source
This commit is contained in:
vsxd 2026-03-11 20:34:09 +08:00
parent db64bef098
commit dfa66bbfbe
11 changed files with 48 additions and 48 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
docs/00-product-direction.md
View file

@ -1,4 +1,4 @@
# Astron Skills 产品定位与 MVP 范围
# skillhub 产品定位与 MVP 范围
## 1. 定位
@ -38,7 +38,7 @@
- 四级目录优先级（`.agent/skills` → `~/.agent/skills` → `.claude/skills` → `~/.claude/skills`）
- 目录名作为 lookup key（安装后目录名 = skill slug）
- AGENTS.md `<skill>` 描述块格式兼容
- 目标：Astron CLI 安装的技能可被 OpenSkills/Claude 兼容客户端发现和使用
- 目标：skillhub CLI 安装的技能可被 OpenSkills/Claude 兼容客户端发现和使用
不直接继承：
- 以 CLI 为中心的产品定位
@ -48,7 +48,7 @@
- Hub 优先：服务端是核心，CLI 和 Agent 集成是入口能力
- 兼容优先：兼容 `SKILL.md` 及常见目录约定
- CLI 兼容优先：除 Astron CLI 外，一期明确要求实现 ClawHub CLI 协议兼容层
- CLI 兼容优先：除 skillhub CLI 外，一期明确要求实现 ClawHub CLI 协议兼容层
- 分层优先：搜索、对象存储都必须有可替换边界
- 开放认证：基于标准 OAuth2 协议，一期 GitHub 登录，架构支持后续扩展多 Provider
- 审计优先：企业内部分发平台必须保留发布、下载、删除、授权等审计链路

28
docs/01-system-architecture.md
View file

@ -1,4 +1,4 @@
# Astron Skills 系统架构设计
# skillhub 系统架构设计
## 1. 技术基线
@ -19,12 +19,12 @@
```
server/
├── astron-skills-app # 启动、配置装配、Controller 聚合
├── astron-skills-domain # 领域模型 + 领域服务 + 应用服务
├── astron-skills-auth # OAuth2 认证 + RBAC + 授权判定
├── astron-skills-search # 搜索 SPI + MySQL 全文实现
├── astron-skills-storage # 对象存储抽象 + S3 实现
└── astron-skills-infra # MyBatis、通用工具、配置基础
├── skillhub-app # 启动、配置装配、Controller 聚合
├── skillhub-domain # 领域模型 + 领域服务 + 应用服务
├── skillhub-auth # OAuth2 认证 + RBAC + 授权判定
├── skillhub-search # 搜索 SPI + MySQL 全文实现
├── skillhub-storage # 对象存储抽象 + S3 实现
└── skillhub-infra # MyBatis、通用工具、配置基础
```
## 4. 模块依赖方向（依赖倒置，禁止领域层依赖基础设施）
@ -45,19 +45,19 @@ storage → (独立抽象) # 纯 SPI，不依赖 domain
## 5. 各模块职责
### astron-skills-app
### skillhub-app
- Spring Boot 启动类
- Controller 分包：`controller.portal`（公开查询）、`controller.cli`（CLI API）、`controller.admin`（管理后台）
- 全局异常处理、请求日志、OpenAPI 配置
- 配置文件与环境 profile
### astron-skills-domain
### skillhub-domain
- 核心实体：Skill, SkillVersion, SkillFile, SkillTag, Namespace, NamespaceMember, ReviewTask, AuditLog, SkillStar, SkillRating
- 领域服务：发布流程编排、审核状态机、命名空间管理、标签管理
- 应用服务：面向 Controller 的用例编排
- Repository 接口定义（实现在 infra）
### astron-skills-auth
### skillhub-auth
- Spring Security OAuth2 Client 配置（一期 GitHub，可扩展多 Provider）
- `CustomOAuth2UserService`：OAuth2 用户 → 平台用户映射
- `IdentityBindingService`：外部身份 → 平台用户绑定
@ -66,13 +66,13 @@ storage → (独立抽象) # 纯 SPI，不依赖 domain
- RBAC：角色定义、权限点、资源级授权判定
- 用户实体：UserAccount, IdentityBinding, ApiToken, Role, Permission, UserRoleBinding
### astron-skills-search
### skillhub-search
- SPI 接口：`SearchIndexService`, `SearchQueryService`, `SearchRebuildService`
- 一期实现：`MysqlFullTextIndexService`, `MysqlFullTextQueryService`
- 独立搜索文档表 `skill_search_document`
- 未来扩展点：ES / 向量检索实现
### astron-skills-storage
### skillhub-storage
- SPI 接口：`ObjectStorageService`
- 一期实现：S3 兼容实现（MinIO / AWS S3）
- 文件哈希校验、打包下载
@ -81,7 +81,7 @@ storage → (独立抽象) # 纯 SPI，不依赖 domain
- 打包路径：`packages/{skillId}/{versionId}/bundle.zip`
- 临时上传：`tmp/{uploadId}/{filePath}`（24h GC 清理）
### astron-skills-infra
### skillhub-infra
- MyBatis-Plus Mapper 实现
- Repository 实现
- 通用工具（ID 生成、时间、JSON 等）
@ -107,7 +107,7 @@ web/
## 7. Monorepo 顶层结构
```
astron-skills/
skillhub/
├── server/ # Maven 多模块 Java 后端
├── web/ # React 前端
├── Makefile # 顶层构建编排（dev / build / docker）

4
docs/02-domain-model.md
View file

@ -1,4 +1,4 @@
# Astron Skills 领域模型与数据模型
# skillhub 领域模型与数据模型
## 3.1 核心实体
@ -392,4 +392,4 @@ MySQL Full-Text Index 建在 `(title, summary, keywords, search_text)` 上。
| namespace_member | `(namespace_id, user_id)` UNIQUE | 成员唯一约束 |
| namespace_member | `(user_id)` | 用户所属空间 |
| identity_binding | `(provider_code, subject)` UNIQUE | 身份查找 |
| api_token | `(token_hash)` | Token 校验 |
| api_token | `(token_hash)` | Token 校验 |

2
docs/03-authentication-design.md
View file

@ -1,4 +1,4 @@
# Astron Skills 认证与授权设计
# skillhub 认证与授权设计
## 1. 认证架构

2
docs/04-search-architecture.md
View file

@ -1,4 +1,4 @@
# Astron Skills 搜索架构
# skillhub 搜索架构
## 1 SPI 接口

2
docs/05-business-flows.md
View file

@ -1,4 +1,4 @@
# Astron Skills 核心业务流
# skillhub 核心业务流
## 1 发布流程

12
docs/06-api-design.md
View file

@ -1,4 +1,4 @@
# Astron Skills API 设计
# skillhub API 设计
## 7.1 Public API（匿名可访问）
@ -97,13 +97,13 @@ Public API 的可见性规则：
### ClawHub CLI 协议兼容层
一期不仅提供 Astron 自有 CLI API，还必须暴露一组兼容 ClawHub CLI 的 registry API。
一期不仅提供 skillhub 自有 CLI API，还必须暴露一组兼容 ClawHub CLI 的 registry API。
- 目标：让现有 ClawHub CLI 可通过配置 registry base URL 直接对接 Astron Skills
- 目标：让现有 ClawHub CLI 可通过配置 registry base URL 直接对接 skillhub
- 范围：覆盖 ClawHub CLI 所依赖的查询、版本解析、下载、发布、校验等核心接口
- 要求：兼容层优先保持 ClawHub CLI 既有请求/响应语义；若内部领域模型不同，通过 adapter 层完成协议转换，而不是要求客户端适配 Astron 私有协议
- 要求：兼容层优先保持 ClawHub CLI 既有请求/响应语义；若内部领域模型不同，通过 adapter 层完成协议转换，而不是要求客户端适配 skillhub 私有协议
- 要求：兼容层纳入 OpenAPI 或独立兼容协议文档，并作为正式对外契约维护
- 要求：兼容层与 Astron 自有 `/api/v1/cli/**` 并存，二者共享同一套权限、审计、限流与领域服务
- 要求：兼容层与 skillhub 自有 `/api/v1/cli/**` 并存，二者共享同一套权限、审计、限流与领域服务
- 非目标：前端页面不直接依赖兼容层；兼容层用于服务已有 ClawHub CLI 和相关自动化脚本
兼容层最少需要覆盖的能力类别：
@ -113,7 +113,7 @@ Public API 的可见性规则：
- Publish workflow：包上传、发布状态查询、提交审核
- Integrity check：版本存在性校验、摘要/哈希比对、whoami/token 上下文确认
如 ClawHub CLI 的现有协议与 Astron 自有接口存在差异，文档以“兼容 ClawHub CLI 协议”为准，Astron 内部 API 可继续保持当前风格。
如 ClawHub CLI 的现有协议与 skillhub 自有接口存在差异，文档以“兼容 ClawHub CLI 协议”为准，skillhub 内部 API 可继续保持当前风格。
## 7.6 Admin API（需对应平台角色）

28
docs/07-skill-protocol.md
View file

@ -1,16 +1,16 @@
# Astron Skills 技能包协议
# skillhub 技能包协议
## 8.1 OpenSkills 互操作边界
Astron 的目标是客户端可互操作：Astron CLI 安装的技能可以被 Claude Code / OpenSkills 兼容客户端发现和使用，反之亦然。
skillhub 的目标是客户端可互操作：skillhub CLI 安装的技能可以被 Claude Code / OpenSkills 兼容客户端发现和使用，反之亦然。
### 互操作层（Astron CLI 必须兼容）
### 互操作层（skillhub CLI 必须兼容）
- SKILL.md 格式（frontmatter + markdown body）
- 技能包目录结构约定（SKILL.md + references/ + scripts/ + assets/）
- 四级目录优先级：Astron CLI 遵循 `.agent/skills` → `~/.agent/skills` → `.claude/skills` → `~/.claude/skills` 的发现顺序，与 OpenSkills/Claude 一致
- 四级目录优先级：skillhub CLI 遵循 `.agent/skills` → `~/.agent/skills` → `.claude/skills` → `~/.claude/skills` 的发现顺序，与 OpenSkills/Claude 一致
- 目录名作为 lookup key：安装后的目录名等于 `skill.slug`（即 SKILL.md 的 `name` 字段），客户端通过目录名发现技能
- AGENTS.md `<skill>` 描述块格式：Astron CLI 生成的 AGENTS.md 索引区块与 OpenSkills 格式兼容
- AGENTS.md `<skill>` 描述块格式：skillhub CLI 生成的 AGENTS.md 索引区块与 OpenSkills 格式兼容
### 服务端职责边界
@ -18,11 +18,11 @@ Astron 的目标是客户端可互操作：Astron CLI 安装的技能可以被 C
- `location` 是客户端本地安装路径，由 CLI 根据安装目录计算生成，写入 AGENTS.md
- 服务端不生成、不修改 AGENTS.md，这是客户端职责
### Astron 私有扩展（不影响互操作）
### skillhub 私有扩展（不影响互操作）
- `<skills_system>` / `<available_skills>` 区块格式：Astron CLI 可自定义，但必须保证 `<skill>` 节点格式与 OpenSkills 一致
- progressive disclosure（按需加载技能内容）：Astron CLI 自行实现
- `.astron/metadata.json`：Astron 私有元数据，其他客户端可忽略
- `<skills_system>` / `<available_skills>` 区块格式：skillhub CLI 可自定义，但必须保证 `<skill>` 节点格式与 OpenSkills 一致
- progressive disclosure（按需加载技能内容）：skillhub CLI 自行实现
- `.astron/metadata.json`：skillhub 私有元数据，其他客户端可忽略
## 8.2 SKILL.md 规范
@ -74,7 +74,7 @@ my-skill/
## 8.4 客户端安装目录约定
Astron CLI 遵循以下目录优先级，与 OpenSkills/Claude 保持互操作：
skillhub CLI 遵循以下目录优先级，与 OpenSkills/Claude 保持互操作：
| 优先级 | 路径 | 说明 |
|--------|------|------|
@ -87,20 +87,20 @@ Astron CLI 遵循以下目录优先级，与 OpenSkills/Claude 保持互操作
## 8.5 与 AGENTS.md 的关系
- Astron CLI 安装技能后，通过 `sync` 命令在 AGENTS.md 中生成 `<skill>` 描述块
- skillhub CLI 安装技能后，通过 `sync` 命令在 AGENTS.md 中生成 `<skill>` 描述块
- `<skill>` 块包含 `name`、`description`、`location`（本地安装路径），格式与 OpenSkills 一致
- `location` 由 CLI 根据实际安装路径计算，不由服务端提供
- 服务端不直接生成或修改 AGENTS.md，这是客户端职责
## 8.6 客户端本地元数据文件（Astron 私有实现）
## 8.6 客户端本地元数据文件（skillhub 私有实现）
以下为 Astron CLI 的私有实现细节，不属于互操作协议的一部分。其他客户端可忽略此文件。
以下为 skillhub CLI 的私有实现细节，不属于互操作协议的一部分。其他客户端可忽略此文件。
CLI 安装后在本地写入 `.astron/metadata.json`：
```json
{
"source": "astron-skills",
"source": "skillhub",
"sourceType": "registry",
"registryUrl": "https://skills.example.com",
"namespace": "@ai-platform-team",

2
docs/08-frontend-architecture.md
View file

@ -1,4 +1,4 @@
# Astron Skills 前端架构设计
# skillhub 前端架构设计
## 1 技术栈

4
docs/09-deployment.md
View file

@ -1,4 +1,4 @@
# Astron Skills 部署架构与运维
# skillhub 部署架构与运维
## 1 K8s 部署拓扑
@ -87,6 +87,6 @@ Makefile 顶层命令：`make dev-server`, `make dev-web`, `make build`, `make d
## 7 数据库迁移
Flyway 管理 schema 变更：
- 脚本路径：`server/astron-skills-app/src/main/resources/db/migration/`
- 脚本路径：`server/skillhub-app/src/main/resources/db/migration/`
- 命名：`V{version}__{description}.sql`
- 多 Pod 安全：Flyway 自带数据库锁

6
docs/10-delivery-roadmap.md
View file

@ -1,4 +1,4 @@
# Astron Skills 交付路线
# skillhub 交付路线
## Phase 0：设计定稿（当前阶段）
@ -80,7 +80,7 @@
### 验收
发布必须经审核，分级审核权限生效，Astron CLI 全流程可用，ClawHub CLI 通过兼容层可完成核心 registry 操作，评分收藏可用
发布必须经审核，分级审核权限生效，skillhub CLI 全流程可用，ClawHub CLI 通过兼容层可完成核心 registry 操作，评分收藏可用
## Phase 4：运维增强 + 打磨
@ -109,4 +109,4 @@
| 搜索效果不佳 | SPI 架构允许随时切换实现 |
| 前后端接口频繁变更 | OpenAPI spec 先行，类型自动生成 |
| 新增 OAuth Provider | Spring Security OAuth2 原生多 Provider 支持，只需配置 + 属性映射 |
| ClawHub CLI 协议细节与现有模型不完全一致 | 增加兼容适配层与协议回归测试，避免把 Astron 内部模型直接暴露给兼容客户端 |
| ClawHub CLI 协议细节与现有模型不完全一致 | 增加兼容适配层与协议回归测试，避免把 skillhub 内部模型直接暴露给兼容客户端 |