mirror of https://github.com/iflytek/skillhub.git synced 2026-08-27 11:14:59 +00:00

docs(compliance): document runtime integration contract (#704 )

Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>

2026-08-11 13:43:42 +08:00

8.2 KiB

Raw Blame History

skillhub 技能包协议

8.1 OpenSkills 互操作边界

skillhub 的目标是客户端可互操作：skillhub CLI 安装的技能可以被 Claude Code / OpenSkills 兼容客户端发现和使用，反之亦然。

互操作层（skillhub CLI 必须兼容）

SKILL.md 格式（frontmatter + markdown body）
技能包目录结构约定（SKILL.md + references/ + scripts/ + assets/）
四级目录优先级：.agents/skills → ~/.agents/skills → .claude/skills → ~/.claude/skills（与 OpenSkills/Claude 一致）。详见 §8.4。
目录名作为 lookup key：安装后的目录名等于 skill.slug（即 SKILL.md 的 name 字段），客户端通过目录名发现技能
AGENTS.md <skill> 描述块格式：skillhub CLI 生成的 AGENTS.md 索引区块与 OpenSkills 格式兼容

服务端职责边界

服务端返回技能元数据（name, description, version），不返回 location
location 是客户端本地安装路径，由 CLI 根据安装目录计算生成，写入 AGENTS.md
服务端不生成、不修改 AGENTS.md，这是客户端职责

skillhub 私有扩展（不影响互操作）

<skills_system> / <available_skills> 区块格式：skillhub CLI 可自定义，但必须保证 <skill> 节点格式与 OpenSkills 一致
progressive disclosure（按需加载技能内容）：skillhub CLI 自行实现
.astron/metadata.json：skillhub 私有元数据，其他客户端可忽略

8.2 SKILL.md 规范

服务端必须兼容的格式：

---
name: my-skill              # 必需，kebab-case
description: When to use    # 必需，1-2 句话
---

# Markdown 正文（技能指令内容）

解析规则：

name 和 description 为必需字段，缺失则校验失败
name 映射为 skill.slug（首次发布时），后续版本不可变更
description 映射为 skill.summary
frontmatter 完整解析结果存入 skill_version.parsed_metadata_json

平台扩展字段（可选，x-astron- 前缀）：

---
name: my-skill
description: When to use
x-astron-category: code-review
x-astron-runtime: claude-code        # 预留
x-astron-min-version: "1.0"          # 预留
x-astron-compliance:                 # 可选，平台私有合规元数据
  - standard: mitre-attack
    version: "v19.1"
    controlId: T1059
    title: Command and Scripting Interpreter
    evidence:
      - type: packaged-file
        path: references/standards.md
---

合规元数据先按 SkillHub/Astron 私有扩展实现，字段名采用 x-astron-compliance。当前支持发布校验、版本级 complianceSnapshot 固化、详情展示、审核 diff 和轻量搜索投影。这些信息表示“技能作者声明的合规映射”，SkillHub 校验证据引用的格式和可追溯性，但不等同于第三方认证或平台背书。设计边界、分阶段实现和 Runtime 职责划分见 24-compliance-metadata-design.md。

x-astron-compliance 的稳定字段如下：

字段	必填	说明
`standard`	是	合规标准、框架或知识库标识，例如 `mitre-attack`、`nist-csf`、`soc2`
`version`	是	标准版本或适用版本，例如 `v19.1`、`2.0`
`controlId`	是	控制项、技术编号或条款 ID，例如 `T1059`、`PR.AA-01`
`title`	否	人类可读的控制项名称
`evidence`	否	证据列表，指向包内文件或外部 URL

evidence 支持两类：

`type`	字段	说明
`packaged-file`	`path`	指向技能包内的证据文件。路径必须在包内，不能路径逃逸。
`external-url`	`url`	指向外部证据材料。URL 必须使用允许的安全 scheme。

发布校验规则：

没有 x-astron-compliance 的旧技能继续正常发布。
x-astron-compliance 存在时必须是数组。
standard、version、controlId 必填。
同一技能版本内不允许重复 standard + version + controlId。
packaged-file.path 必须存在于上传包内，且不能使用 ../ 等方式逃逸包目录。
合法合规声明会被规范化为版本级 complianceSnapshot，并生成稳定 digest。

Runtime 集成边界：

SkillHub 是技能元数据和版本级 complianceSnapshot 的权威源。
Agent Runtime 是执行 trace 的权威源。
Runtime 如需在执行链路中记录合规上下文，应引用 SkillHub 返回的不可变版本 id 和 complianceSnapshot.digest，而不是复制或改写 SkillHub 的声明内容。
SkillHub 当前不记录 Agent 执行输入输出、Runtime trace 或实际调用结果。

8.3 技能包目录结构

my-skill/
├── SKILL.md              # 主入口文件（必需）
├── references/           # 参考资料（可选）
├── scripts/              # 脚本（可选）
└── assets/               # 静态资源（可选）

校验规则：

根目录必须包含规范入口文件 SKILL.md；上传时服务端兼容 skill.md、Skill.md 等大小写变体，并在内部归一化为 SKILL.md
文件类型白名单：.md, .txt, .json, .yaml, .yml, .js, .cjs, .mjs, .ts, .py, .sh, .png, .jpg, .svg
单文件大小限制：1MB（可配置）
总包大小限制：10MB（可配置）
文件数量限制：100 个（可配置）

8.4 客户端安装目录约定

skillhub CLI 遵循以下目录优先级，与 OpenSkills/Claude 保持互操作：

优先级	路径	说明
1	`./.agents/skills/`	项目级，universal 模式
2	`~/.agents/skills/`	全局级，universal 模式
3	`./.claude/skills/`	项目级，Claude 默认
4	`~/.claude/skills/`	全局级，Claude 默认

安装后目录名等于 skill.slug（SKILL.md 的 name 字段），确保其他兼容客户端可通过目录名发现。

8.5 与 AGENTS.md 的关系

skillhub CLI 安装技能后，通过 sync 命令在 AGENTS.md 中生成 <skill> 描述块
<skill> 块包含 name、description、location（本地安装路径），格式与 OpenSkills 一致
location 由 CLI 根据实际安装路径计算，不由服务端提供
服务端不直接生成或修改 AGENTS.md，这是客户端职责

8.6 客户端本地元数据文件（skillhub 私有实现）

以下为 skillhub CLI 的私有实现细节，不属于互操作协议的一部分。其他客户端可忽略此文件。

CLI 安装后在本地写入 .astron/metadata.json：

{
  "source": "skillhub",
  "sourceType": "registry",
  "registryUrl": "https://skills.example.com",
  "namespace": "@ai-platform-team",
  "skillSlug": "code-review",
  "version": "1.2.0",
  "installedAt": "2026-03-11T10:00:00Z",
  "sha256": "abc123..."
}

8.7 版本解析规则

skillhub 自有 CLI 支持完整 namespace 坐标：

install @team/my-skill              → 最新已发布版本（实现上通常由 `latest_version_id` / published pointer 解析）
install @team/my-skill@1.2.0        → 精确版本
install @team/my-skill@latest        → 等同于不带版本号（系统保留标签，只读）
install @team/my-skill@beta          → beta 标签（自定义标签）
install my-skill                     → 等同于 @global/my-skill

ClawHub CLI 通过兼容层使用 canonical slug：

clawhub install my-skill             → @global/my-skill 的最新版本
clawhub install team-name--my-skill  → @team-name/my-skill 的最新版本
clawhub install my-skill@1.2.0       → @global/my-skill 的精确版本

8.8 坐标映射与 ClawHub CLI 兼容

skillhub 内部使用 @{namespace_slug}/{skill_slug} 坐标，ClawHub CLI 使用单一 slug。映射规则详见 00-product-direction.md 1.1 节。

安装后的本地目录名始终使用 skill.slug（不含 namespace 前缀），确保与 OpenSkills/Claude 兼容客户端的互操作性。

skillhub 坐标	ClawHub canonical slug	本地安装目录名
`@global/my-skill`	`my-skill`	`my-skill/`
`@team-name/my-skill`	`team-name--my-skill`	`my-skill/`

注意：不同 namespace 下同名 skill 安装到本地时会产生目录冲突。skillhub CLI 应在安装时检测冲突并提示用户选择安装目录或使用别名。

8.2 KiB Raw Blame History Unescape Escape