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

Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
2026-08-27 11:14:59 +00:00 · 2026-08-11 13:43:42 +08:00 · 2026-08-11 13:43:42 +08:00 · 76d95b615e
commit 76d95b615e
parent 2fe7514a4e
8 changed files with 360 additions and 3 deletions
--- 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 技能包目录结构

 ```
--- 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' },
            ],
          },
          {
--- 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
--- a/docs/skillhub/en/guide/runtime-integration.md
+++ 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.
--- 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**:
--- 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 记录
 - **批量审核**：管理员可以批量批准多个技能包
 - **审核意见**：拒绝时建议提供详细的改进建议
 - **撤回限制**：只有待审核状态的技能包可以撤回
--- a/docs/skillhub/guide/runtime-integration.md
+++ 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。
--- 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 接口

 **发布技能包**：