skillhub/docs/00-product-direction.md

skillhub 产品定位与 MVP 范围

1. 定位

单实例共享技能注册中心（Skills Hub / Registry），不是多租户平台。

• 平台只有一个共享注册中心实例
• 隔离边界是 namespace，不是租户
• @global 是平台级公共空间，由平台管理员管理
• @team-* 是协作与治理边界（部门/团队），不是租户边界
• 公共技能（visibility=PUBLIC）匿名可浏览和下载

以 ClawHub 为产品蓝本（继承产品模型，不照搬技术实现），以 OpenSkills 借鉴 SKILL.md 格式和目录结构约定（不兼容其客户端运行时行为）。

同时，一期必须提供 ClawHub CLI 协议兼容层：服务端需要暴露一组与 ClawHub CLI 兼容的 registry API，使现有 ClawHub CLI 在不修改或仅最小配置修改的前提下可完成 registry 侧查询、解析、下载、发布、校验等核心操作。

1.2 身份主键约束（已冻结）

• 用户身份主键全链路统一使用 string，不得使用 int / long / bigint 作为平台用户标识的正式契约类型。
• 该约束覆盖认证主体、API 入参/出参、权限判定、审计、资源 owner、creator、updater、reviewer、actor、submittedBy 等全部用户关联字段。
• 原因：平台需要兼容外部 SSO / OAuth / OIDC / SCIM 等身份源，外部 UID 通常是稳定字符串，不应先压缩为本地自增整数再作为系统主契约继续传播。
• 旧版草案中任何“整型用户标识”写法都已失效，当前唯一有效约束是“平台用户标识全链路使用字符串主键”。

1.1 技能坐标体系（已冻结）

skillhub 内部使用 namespace 坐标模型：@{namespace_slug}/{skill_slug}。

ClawHub CLI 使用单一 slug 模型，slug 校验规则为 [a-z0-9]([a-z0-9-]*[a-z0-9])?，不允许 / 出现。

为同时满足两套模型，定义以下双向映射规则：

映射规则：

skillhub 坐标	兼容层 canonical slug	说明
@global/my-skill	my-skill	全局空间省略前缀，直接使用 skill slug
@team-name/my-skill	team-name--my-skill	团队空间使用 {namespace_slug}--{skill_slug} 格式

约束规则：

• 分隔符为双连字符 --
• skill slug 和 namespace slug 均禁止包含 --（在校验规则中追加此限制）
• slug 格式校验更新为：[a-z0-9]([a-z0-9-]*[a-z0-9])?，且不得包含连续两个以上的连字符 --
• 兼容层解析 canonical slug 时：包含 -- 则拆分为 namespace_slug + skill_slug，不包含则视为 @global/{slug}
• 冲突规则：如果 @global/team-name--my-skill 与 @team-name/my-skill 产生冲突，以 -- 拆分优先（即优先解析为团队空间技能）。全局空间的 skill slug 禁止包含 -- 以避免歧义
• 保留字规则：namespace slug 保留词列表同样适用于 canonical slug 的 namespace 部分

显示规则：

• Web 端始终显示完整坐标：@global/my-skill、@team-name/my-skill
• ClawHub CLI 兼容层返回 canonical slug：my-skill、team-name--my-skill
• skillhub 自有 CLI 支持两种格式输入，内部统一转换为 namespace 坐标

Well-known 发现：

• skillhub 服务端提供 /.well-known/clawhub.json，返回 { "apiBase": "/api/v1" }
• ClawHub CLI 通过此机制自动发现兼容层 API 基地址

2. 参考项目取舍

2.1 继承 ClawHub 的部分

• Skill Registry 的整体产品边界
• 技能版本、标签、下载的业务模型
• 发布后治理机制（报告、标记、隐藏、撤回）
• Web 浏览、详情页、上传发布、管理后台的功能切分
• 公共查询 API 与 CLI API 的双通道设计
• ClawHub CLI 所依赖的 registry API 协议面
• Skill 元数据提取与服务端校验思路
• 审计、收藏、评分、统计、运营标签等扩展位

不直接继承：

• Convex 数据模型与运行时
• 向量检索的一期实现方式

2.2 借鉴 OpenSkills 的部分

• SKILL.md 格式兼容（frontmatter + markdown body）
• 技能包目录结构约定（SKILL.md + references/ + scripts/ + assets/）
• 四级目录优先级（.agents/skills → ~/.agents/skills → .claude/skills → ~/.claude/skills）
• 目录名作为 lookup key（安装后目录名 = skill slug）
• AGENTS.md <skill> 描述块格式兼容
• 目标：skillhub CLI 安装的技能可被 OpenSkills/Claude 兼容客户端发现和使用

不直接继承：

• 以 CLI 为中心的产品定位
• "无服务端"的前提

3. 产品原则

• Hub 优先：服务端是核心，CLI 和 Agent 集成是入口能力
• 兼容优先：兼容 SKILL.md 及常见目录约定
• CLI 兼容优先：除 skillhub CLI 外，一期明确要求实现 ClawHub CLI 协议兼容层
• 分层优先：搜索、对象存储都必须有可替换边界
• 开放认证：基于标准 OAuth2 协议，一期 GitHub 登录，架构支持后续扩展多 Provider
• 审计优先：企业内部分发平台必须保留发布、下载、删除、授权等审计链路

4. 一期 MVP 功能

核心能力：

• 技能发布（当前版本采用“提交 → 审核 → 上线”；SUPER_ADMIN 保留直发能力）
• 技能版本管理（semver + 标签）
• 技能浏览、详情、下载（公共技能匿名可访问）
• 标签管理（latest 系统保留只读 + 自定义标签人工维护）
• 技能包文件校验与 SKILL.md 元数据抽取
• 基于 PostgreSQL 全文索引的搜索

命名空间与组织：

• 单一全局命名空间（@global/skill-name），由平台管理员管理，不支持多个平台级 namespace
• 团队/部门命名空间（@team-slug/skill-name）
• 命名空间成员管理
• 创建技能时选择归属空间

审核流程：

• 当前版本：普通用户发布后进入审核，审核通过后上线
• SUPER_ADMIN 发布可直达 PUBLISHED
• 分级审核：团队空间由团队管理员审核，全局空间由平台管理员审核
• 团队技能提升到全局需平台管理员二次审核
• 平台管理员只负责全局空间审核与提升审核，不介入团队空间审核
• 当前不引入自动审核；PrePublishValidator 仅作为未来扩展点保留，默认实现为 NoOp
• 撤回审核语义统一为 PENDING_REVIEW → DRAFT，不再走删除版本记录
• skill 生命周期管理读模型统一为 headlineVersion / publishedVersion / ownerPreviewVersion / resolutionMode
• hidden 是独立治理覆盖层，不属于 skill 容器状态机

认证与权限：

• OAuth2 标准登录（一期 GitHub OAuth）
• CLI 认证采用 OAuth Device Flow，由 Web 授权后签发 CLI 可用凭证
• API Token 保留为平台通用凭证能力，用于自动化、兼容层和后续扩展
• ClawHub CLI 协议兼容层（一期聚焦 search、resolve、download、publish、whoami 等核心接口）
• RBAC 角色权限体系（平台角色：SUPER_ADMIN / SKILL_ADMIN / USER_ADMIN / AUDITOR + 命名空间角色）
• 管理后台：用户角色管理、发布审核

社交功能：

• 收藏（star）
• 评分（1-5 分）

审计：

• 发布、审核、下载、删除等关键操作审计

5. 一期明确不做（含后续规划）

• 评论 → Phase 5 上线，含举报机制
• 自动安全扫描 → Phase 5 上线，接入 PrePublishValidator 扩展点
• 举报/标记机制 → Phase 5 上线，配合评论和治理闭环
• 向量搜索 → 当前进入第一阶段规划，仅做搜索增强，不引入推荐系统
• 在线编辑器 → 暂不规划
• Webhook/事件通知 → Phase 5（预留扩展点）
• 技能依赖/兼容性声明 → 暂不规划（预留 parsed_metadata_json 字段）

latest 语义说明

这是有意的产品决策，不是继承 ClawHub 的回滚模型：

• latest 自动跟随最新已发布版本，只读，不可手动移动
• 回滚/稳定通道管理通过自定义标签实现（如 stable、beta、stable-2026q1）
• ClawHub 的"通过移动 latest 做回滚"能力被替换为"通过自定义标签做通道管理"

6. 一期核心约束

• Skill 包视为"文本资源包"，不接受二进制大文件
• 技能包主入口文件固定为 SKILL.md
• 元数据以 SKILL.md frontmatter 为主，数据库持久化解析结果
• 文件内容原文存对象存储，检索面向数据库中的派生字段与可索引文本
• Web 认证、CLI Device Flow 与 API Token 凭证统一汇聚到平台用户体系
• 公共技能（visibility=PUBLIC）匿名可浏览和下载，无需登录