From 76d95b615e3dd227148e3e3ba71a634bac7079e1 Mon Sep 17 00:00:00 2001 From: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com> Date: Tue, 11 Aug 2026 13:43:42 +0800 Subject: [PATCH] docs(compliance): document runtime integration contract (#704) Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com> --- docs/07-skill-protocol.md | 41 ++++++- docs/skillhub/.vitepress/config.ts | 2 + docs/skillhub/en/guide/review.md | 20 ++++ docs/skillhub/en/guide/runtime-integration.md | 101 ++++++++++++++++++ docs/skillhub/en/guide/skill-publish.md | 39 +++++++ docs/skillhub/guide/review.md | 20 ++++ docs/skillhub/guide/runtime-integration.md | 101 ++++++++++++++++++ docs/skillhub/guide/skill-publish.md | 39 +++++++ 8 files changed, 360 insertions(+), 3 deletions(-) create mode 100644 docs/skillhub/en/guide/runtime-integration.md create mode 100644 docs/skillhub/guide/runtime-integration.md diff --git a/docs/07-skill-protocol.md b/docs/07-skill-protocol.md index d98ca793..5694f9f6 100644 --- a/docs/07-skill-protocol.md +++ b/docs/07-skill-protocol.md @@ -56,6 +56,7 @@ x-astron-compliance: # 可选，平台私有合规元数据 - standard: mitre-attack version: "v19.1" controlId: T1059 + title: Command and Scripting Interpreter evidence: - type: packaged-file path: references/standards.md @@ -63,11 +64,45 @@ x-astron-compliance: # 可选，平台私有合规元数据 ``` > 合规元数据先按 SkillHub/Astron 私有扩展实现，字段名采用 `x-astron-compliance`。 -> 当前第一阶段支持发布校验和版本级 `complianceSnapshot` 固化；这些信息表示“技能作者声明的合规映射”， -> SkillHub 校验证据引用的格式和可访问性，但不等同于第三方认证或平台背书。详情展示、审核 diff、搜索投影 -> 和 Runtime trace 集成按后续阶段推进。设计边界、分阶段实现和 Runtime 职责划分见 +> 当前支持发布校验、版本级 `complianceSnapshot` 固化、详情展示、审核 diff 和轻量搜索投影。 +> 这些信息表示“技能作者声明的合规映射”，SkillHub 校验证据引用的格式和可追溯性， +> 但不等同于第三方认证或平台背书。设计边界、分阶段实现和 Runtime 职责划分见 > [24-compliance-metadata-design.md](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 技能包目录结构 ``` diff --git a/docs/skillhub/.vitepress/config.ts b/docs/skillhub/.vitepress/config.ts index 001ff010..3cfef1d8 100644 --- a/docs/skillhub/.vitepress/config.ts +++ b/docs/skillhub/.vitepress/config.ts @@ -44,6 +44,7 @@ export default defineConfig({ { text: '审核与治理', link: '/guide/review' }, { text: '安全扫描', link: '/guide/scanner' }, { text: '用户交互与社交', link: '/guide/social' }, + { text: 'Runtime 集成契约', link: '/guide/runtime-integration' }, ], }, { @@ -90,6 +91,7 @@ export default defineConfig({ { text: 'Review & Governance', link: '/en/guide/review' }, { text: 'Security Scanning', link: '/en/guide/scanner' }, { text: 'Social & Interaction', link: '/en/guide/social' }, + { text: 'Runtime Integration Contract', link: '/en/guide/runtime-integration' }, ], }, { diff --git a/docs/skillhub/en/guide/review.md b/docs/skillhub/en/guide/review.md index 6d8bf00e..c2f99b1f 100644 --- a/docs/skillhub/en/guide/review.md +++ b/docs/skillhub/en/guide/review.md @@ -71,6 +71,7 @@ An administrator batch-approves multiple skill packages that meet the standards. - Browse the file list - View file contents online - Download the full package for local testing + - Review the compliance snapshot and the diff from the previous published version ![Flow Diagram](/diagrams/review-flow.png) @@ -80,6 +81,24 @@ An administrator batch-approves multiple skill packages that meet the standards. 5. Add review comments (optional) +**Reviewing Compliance Declarations**: + +If the pending version contains `x-astron-compliance`, the review detail page shows the version-level compliance snapshot and a diff summary: + +- Added declarations: standards, controls, or evidence newly added by the pending version. +- Removed declarations: declarations that existed in the previous published version and are no longer present. +- Modified declarations: standard metadata, control title, or evidence changed. +- Digest changes: `complianceSnapshot.digest` changed, which means the normalized declaration content changed. + +Review guidance: + +1. Check whether each declaration matches the actual skill behavior. For example, a security response skill that declares a MITRE ATT&CK technique should provide supporting documentation or packaged evidence. +2. Expand diff items to inspect evidence paths, external links, and digests instead of relying only on the declaration title. +3. Treat removals and broad rewrites as higher-priority review items because downstream audit systems may reference those snapshots. +4. Reject the submission if evidence is missing, paths are inaccessible, or declarations clearly do not match the skill capability. + +SkillHub guarantees structural validation, traceable evidence references, and immutable version snapshots. It does not certify that the author's declaration is objectively compliant. + **Withdrawing a Review**: If a developer discovers an issue, they can withdraw the submission before it is approved: @@ -181,6 +200,7 @@ Content-Type: application/json - **Review Turnaround**: It is recommended to complete reviews within 24 hours to avoid blocking developers - **Review Records**: All review actions are recorded in the audit log +- **Compliance Audit**: Compliance declarations are recorded as version snapshots. Approval or rejection should consider the diff summary, but Agent execution traces are not recorded by SkillHub - **Batch Review**: Administrators can batch-approve multiple skill packages - **Review Comments**: When rejecting, it is recommended to provide detailed improvement suggestions - **Withdrawal Restrictions**: Only skill packages in the pending review state can be withdrawn diff --git a/docs/skillhub/en/guide/runtime-integration.md b/docs/skillhub/en/guide/runtime-integration.md new file mode 100644 index 00000000..530141b2 --- /dev/null +++ b/docs/skillhub/en/guide/runtime-integration.md @@ -0,0 +1,101 @@ +# Runtime Integration Contract + +## Responsibility Boundary + +SkillHub and Agent Runtime own different facts: + +| System | Source of truth | +|--------|-----------------| +| SkillHub | Skill packages, versions, metadata, compliance declaration snapshots, downloads, and review records | +| Agent Runtime | Actual skill execution, inputs and outputs, model calls, tool calls, and execution traces | + +SkillHub does not execute skills, so it does not record Runtime traces and does not decide whether a real execution was compliant. SkillHub provides version-level facts: what compliance declarations were included in an immutable skill version at publish time, and the stable digest of that normalized snapshot. + +## What Runtime Should Record + +When Runtime needs to connect an execution trace with SkillHub compliance declarations, record these fields: + +| Field | Source | Description | +|-------|--------|-------------| +| `registryUrl` | Runtime configuration | SkillHub registry URL | +| `namespace` | SkillHub coordinate | Skill namespace, such as `global` or a team slug | +| `skillSlug` | SkillHub coordinate | Skill slug | +| `requestedVersion` | Runtime request | User-requested version, tag, or range | +| `resolvedVersion` | SkillHub response | Exact resolved version | +| `skillVersionId` | Version `id` from SkillHub response | Immutable version ID and the primary audit join key | +| `complianceSnapshotDigest` | `complianceSnapshot.digest` | Stable digest of the version-level compliance declaration snapshot | +| `packageDigest` | Download or install flow | Skill package content digest, useful for confirming executed content | +| `runtimeTraceId` | Runtime | Execution trace ID generated by Runtime | + +If Runtime uses an Astron-specific trace schema, it may map these fields into `x-astron-*` keys. That is a Runtime-owned trace convention; SkillHub server does not need to write or parse those trace fields. + +## Reading Version-Level Compliance Snapshots + +The first phase does not expose a standalone compliance API. Runtime can read the version ID and snapshot from the existing version detail endpoint: + +```bash +GET /api/v1/skills/{namespace}/{slug}/versions/{version} +``` + +Key response fields: + +```json +{ + "id": 123, + "version": "1.2.0", + "complianceSnapshot": { + "schemaVersion": "1.0", + "digest": "sha256:8d8c...", + "items": [ + { + "standard": "mitre-attack", + "version": "v19.1", + "controlId": "T1059", + "title": "Command and Scripting Interpreter", + "evidence": [ + { + "type": "packaged-file", + "path": "references/mitre-t1059.md", + "sha256": "sha256:..." + } + ] + } + ] + } +} +``` + +Runtime should write both `id` and `complianceSnapshot.digest` to the execution trace. Recording only the digest is not enough, because the version ID is needed to locate the full snapshot across registries or future migrations. + +## Recommended Execution Flow + +1. Runtime resolves the requested skill coordinate and version. +2. Runtime reads exact version details from SkillHub. +3. Runtime downloads and verifies the skill package. +4. Runtime executes the skill. +5. Runtime records these facts in its own trace: + - SkillHub registry; + - skill coordinate; + - exact version; + - `skillVersionId`; + - `complianceSnapshotDigest`; + - Runtime-owned execution evidence. + +An audit system can then start from the Runtime trace, locate the exact execution, and query SkillHub for the compliance declaration snapshot that existed when that version was published. + +## Anti-Patterns + +- Do not copy the raw `x-astron-compliance` declaration into a trace and let Runtime mutate it. +- Do not record only the skill slug without the version ID; the slug identifies the skill container, not an immutable version. +- Do not treat SkillHub compliance declarations as third-party certification. +- Do not require SkillHub to record model inputs and outputs; that belongs to the Runtime audit boundary. + +## Possible Future API + +If a clear consumer appears, such as Runtime needing only the compliance snapshot without full skill details, SkillHub can add an immutable version-level endpoint: + +```text +GET /api/skill-versions/{skillVersionId}/compliance +``` + +For now, reuse the version detail response to avoid designing multiple APIs before the caller contract is stable. diff --git a/docs/skillhub/en/guide/skill-publish.md b/docs/skillhub/en/guide/skill-publish.md index 5f083a3d..c217485b 100644 --- a/docs/skillhub/en/guide/skill-publish.md +++ b/docs/skillhub/en/guide/skill-publish.md @@ -95,6 +95,45 @@ Team admins receive review notifications and approve skill packages for official Skill package can be discovered through search, others can download via CLI or Web UI. +## Compliance Declarations + +Skill authors can add `x-astron-compliance` to the `SKILL.md` frontmatter to declare how a skill version maps to compliance standards, controls, or security knowledge-base entries. + +```yaml +--- +name: incident-response-helper +description: Helps analysts draft incident response steps. +x-astron-compliance: + - standard: mitre-attack + version: "v19.1" + controlId: T1059 + title: Command and Scripting Interpreter + evidence: + - type: packaged-file + path: references/mitre-t1059.md + - type: external-url + url: https://attack.mitre.org/techniques/T1059/ +--- +``` + +Important boundaries: + +- This is an author declaration, not a SkillHub endorsement or third-party certification. +- SkillHub validates the structure, duplicate mappings, packaged evidence paths, and external URL format. +- After publishing, the declaration is normalized into the version-level `complianceSnapshot` with a stable `digest`. +- Review pages show the diff when a later version adds, removes, or changes compliance declarations. +- Searching for `mitre-attack`, `T1059`, or the declaration title can discover the matching skill. + +Field reference: + +| Field | Required | Description | +|-------|----------|-------------| +| `standard` | Yes | Standard or framework identifier, such as `mitre-attack`, `nist-csf`, or `soc2` | +| `version` | Yes | Standard version | +| `controlId` | Yes | Control, technique, or clause ID | +| `title` | No | Human-readable control title; recommended for review and search | +| `evidence` | No | Evidence list, supporting packaged files and external URLs | + ## API Reference **Publish Skill Package**: diff --git a/docs/skillhub/guide/review.md b/docs/skillhub/guide/review.md index c6a0b8e5..ef1d333b 100644 --- a/docs/skillhub/guide/review.md +++ b/docs/skillhub/guide/review.md @@ -71,6 +71,7 @@ SkillHub 提供了完整的审核工作流，确保发布到注册中心的技 - 浏览文件列表 - 在线查看文件内容 - 下载完整包进行本地测试 + - 查看合规声明快照和相对上一发布版本的差异 ![流程图](/diagrams/review-flow.png) @@ -80,6 +81,24 @@ SkillHub 提供了完整的审核工作流，确保发布到注册中心的技 5. 添加审核意见（可选） +**审核合规声明**： + +如果待审核版本包含 `x-astron-compliance`，审核详情会展示版本级合规快照和差异摘要： + +- 新增声明：待审版本新增了标准、控制项或证据。 +- 删除声明：待审版本移除了上一发布版本已有的声明。 +- 修改声明：标准、控制项标题或证据发生变化。 +- 摘要变化：`complianceSnapshot.digest` 变化，表示规范化后的声明内容发生变化。 + +审核建议： + +1. 确认声明是否与技能实际能力相关。例如安全响应技能声明 MITRE ATT&CK 技术编号时，应能在说明或证据文件中看到对应依据。 +2. 点击差异项查看证据路径、外部链接和摘要，不只看声明标题。 +3. 对删除或大范围修改的声明提高审核优先级，因为这会影响下游审计系统引用。 +4. 如果证据缺失、路径不可访问、声明明显不匹配技能能力，建议拒绝并要求作者修正。 + +SkillHub 能保证的是结构正确、证据可追溯、版本快照不可变；不能替作者保证“真的合规”。 + **撤回审核**： 开发者发现问题，可以在审核通过前撤回提交： @@ -181,6 +200,7 @@ Content-Type: application/json - **审核时效**：建议在 24 小时内完成审核，避免阻塞开发者 - **审核记录**：所有审核操作都会记录到审计日志 +- **合规审计**：合规声明以版本快照形式记录。审核通过或拒绝时，应结合差异摘要判断风险，但 Agent 执行 trace 不由 SkillHub 记录 - **批量审核**：管理员可以批量批准多个技能包 - **审核意见**：拒绝时建议提供详细的改进建议 - **撤回限制**：只有待审核状态的技能包可以撤回 diff --git a/docs/skillhub/guide/runtime-integration.md b/docs/skillhub/guide/runtime-integration.md new file mode 100644 index 00000000..cb3b42b4 --- /dev/null +++ b/docs/skillhub/guide/runtime-integration.md @@ -0,0 +1,101 @@ +# Runtime 集成契约 + +## 职责边界 + +SkillHub 和 Agent Runtime 的职责分开： + +| 系统 | 权威负责内容 | +|------|--------------| +| SkillHub | 技能包、版本、元数据、合规声明快照、下载与审核记录 | +| Agent Runtime | 技能实际执行、输入输出、模型调用、工具调用、执行 trace | + +SkillHub 不执行技能，因此不记录 Runtime trace，也不判断一次真实执行是否合规。SkillHub 提供的是版本级事实：某个不可变技能版本在发布时包含了什么合规声明，以及该声明快照的稳定摘要。 + +## Runtime 应记录什么 + +Runtime 在执行技能时，如果需要把执行链路与 SkillHub 的合规声明关联起来，建议记录以下字段： + +| 字段 | 来源 | 说明 | +|------|------|------| +| `registryUrl` | Runtime 配置 | 使用的 SkillHub 注册中心地址 | +| `namespace` | SkillHub 坐标 | 技能命名空间，例如 `global` 或团队 slug | +| `skillSlug` | SkillHub 坐标 | 技能 slug | +| `requestedVersion` | Runtime 请求 | 用户请求的版本、标签或版本范围 | +| `resolvedVersion` | SkillHub 响应 | 实际解析到的版本号 | +| `skillVersionId` | SkillHub 响应里的版本 `id` | 不可变版本 ID，审计关联的主键 | +| `complianceSnapshotDigest` | `complianceSnapshot.digest` | 该版本合规声明快照的稳定摘要 | +| `packageDigest` | 下载或安装流程 | 技能包内容摘要，便于确认执行内容 | +| `runtimeTraceId` | Runtime | Runtime 自己生成的执行链路 ID | + +如果 Runtime 使用 Astron 自有 trace schema，可以把这些字段映射成 `x-astron-*` 键；这属于 Runtime 的 trace 约定，不是 SkillHub 服务端必须写入或解析的字段。 + +## 获取版本级合规快照 + +第一阶段不提供独立的 compliance API。Runtime 可以通过既有版本详情接口读取版本 ID 和快照： + +```bash +GET /api/v1/skills/{namespace}/{slug}/versions/{version} +``` + +响应中的关键字段： + +```json +{ + "id": 123, + "version": "1.2.0", + "complianceSnapshot": { + "schemaVersion": "1.0", + "digest": "sha256:8d8c...", + "items": [ + { + "standard": "mitre-attack", + "version": "v19.1", + "controlId": "T1059", + "title": "Command and Scripting Interpreter", + "evidence": [ + { + "type": "packaged-file", + "path": "references/mitre-t1059.md", + "sha256": "sha256:..." + } + ] + } + ] + } +} +``` + +Runtime 应把 `id` 和 `complianceSnapshot.digest` 一起写入执行 trace。只记录 digest 不够，因为不同注册中心或未来迁移场景下需要版本 ID 来定位完整快照。 + +## 推荐执行链路 + +1. Runtime 根据用户请求解析技能坐标和版本。 +2. Runtime 从 SkillHub 获取精确版本详情。 +3. Runtime 下载并校验技能包。 +4. Runtime 执行技能。 +5. Runtime 在自己的 trace 中记录： + - SkillHub 注册中心； + - 技能坐标； + - 实际版本号； + - `skillVersionId`； + - `complianceSnapshotDigest`； + - Runtime 自己的执行证据。 + +这样审计系统可以先通过 Runtime trace 找到实际执行，再回到 SkillHub 查询该版本发布时的合规声明快照。 + +## 不建议的做法 + +- 不要把 `x-astron-compliance` 原文复制到 trace 后再由 Runtime 修改。 +- 不要只记录技能 slug，不记录版本 ID；slug 指向的是技能容器，不是不可变版本。 +- 不要把 SkillHub 的合规声明当成第三方认证结果。 +- 不要要求 SkillHub 记录模型输入输出；这是 Runtime 的审计边界。 + +## 未来可能新增的 API + +如果出现明确使用方，例如 Runtime 只需要合规快照而不需要完整技能详情，可以新增不可变版本维度的接口： + +```text +GET /api/skill-versions/{skillVersionId}/compliance +``` + +当前阶段先复用版本详情响应，避免为尚未稳定的调用方提前设计多套 API。 diff --git a/docs/skillhub/guide/skill-publish.md b/docs/skillhub/guide/skill-publish.md index 758bfb94..19233eaf 100644 --- a/docs/skillhub/guide/skill-publish.md +++ b/docs/skillhub/guide/skill-publish.md @@ -95,6 +95,45 @@ visibility: PUBLIC 技能包可以通过搜索发现，其他人可以通过 CLI 或 Web UI 下载使用。 +## 合规声明 + +技能作者可以在 `SKILL.md` frontmatter 中添加 `x-astron-compliance`，声明该技能版本与某些合规标准、控制项或安全知识库条目的映射关系。 + +```yaml +--- +name: incident-response-helper +description: Helps analysts draft incident response steps. +x-astron-compliance: + - standard: mitre-attack + version: "v19.1" + controlId: T1059 + title: Command and Scripting Interpreter + evidence: + - type: packaged-file + path: references/mitre-t1059.md + - type: external-url + url: https://attack.mitre.org/techniques/T1059/ +--- +``` + +需要注意： + +- 这是“作者声明”，不是 SkillHub 或第三方机构的合规认证。 +- SkillHub 会校验字段结构、重复项、包内证据路径和外部 URL 格式。 +- 发布成功后，声明会被固化为当前版本的 `complianceSnapshot`，并生成稳定摘要 `digest`。 +- 后续版本如果新增、删除或修改合规声明，审核页会展示差异。 +- 搜索 `mitre-attack`、`T1059` 或声明标题时，可以命中对应技能。 + +字段说明： + +| 字段 | 必填 | 说明 | +|------|------|------| +| `standard` | 是 | 标准或框架标识，例如 `mitre-attack`、`nist-csf`、`soc2` | +| `version` | 是 | 标准版本 | +| `controlId` | 是 | 控制项、技术编号或条款 ID | +| `title` | 否 | 控制项名称，建议填写，便于审核和搜索 | +| `evidence` | 否 | 证据列表，支持包内文件和外部 URL | + ## API 接口 **发布技能包**：