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

XiaoSeS 1dfe3756a9 feat(search): refine compliance discovery interactions

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

2026-08-10 10:42:19 +08:00

13 KiB

Raw Permalink Blame History

Compliance Metadata 设计方案

状态：第一阶段已落地发布校验和版本级 snapshot 固化；详情展示、审核 diff、搜索 facet 和 Runtime trace 集成仍按本文后续阶段推进。

1. 背景

Issue #556 提出的方向是让 SkillHub 支持“可标准映射、可审计引用”的技能元数据。它参考了两个不同类型的开源仓库：

mukul975/Anthropic-Cybersecurity-Skills：大量 SKILL.md 在 frontmatter 中声明 MITRE ATT&CK、NIST CSF 等标准映射，并通过 references/standards.md 等文件补充证据。
calesthio/OpenMontage：通过 pipeline manifest、artifact schema、checkpoint 和 review gate 证明垂直工作流的可恢复、可审核和可追踪。

这两个仓库给 SkillHub 的启发不同：

标准映射应该进入 skill 协议和版本事实，而不是只作为 UI 标签。
运行时 trace 应由执行方记录，SkillHub 不应承担 Agent Runtime 的执行事实。

需要注意：compliance 不是当前已经被广泛应用的 SKILL.md 标准字段。SkillHub 现有协议文档已经约定 x-astron-* 作为平台私有扩展命名空间。因此第一阶段应使用 x-astron-compliance，先解决 SkillHub 自己的治理和审计需求；未来如果 OpenSkills / Agent Skills 生态形成公开字段，再通过兼容读取 compliance 或迁移工具对齐。

因此本方案采用职责分离：

SkillHub 负责“这个技能版本声明了什么合规能力”；Agent Runtime 负责“这次执行实际用了哪个技能版本”。两者通过 skillVersionId + complianceSnapshotDigest 关联。

这里的 compliance 是作者随技能包提交的声明型元数据。SkillHub 第一阶段只验证字段结构、取值格式、包内证据文件是否存在、外部证据 URL 是否是合法 HTTP(S) URL，并生成不可变快照摘要；它不验证外部标准内容是否真实适用，也不代表第三方审计、认证通过或平台背书。

2. 职责边界

2.1 SkillHub 职责

SkillHub 是技能注册中心和元数据权威源，负责：

解析 SKILL.md frontmatter 中的 x-astron-compliance 字段。
发布时校验 compliance 元数据和证据引用。
将规范化结果固化为技能版本级 snapshot。
在已有技能详情、版本详情、审核和搜索能力中投影 compliance 信息。
记录 SkillHub 内部发生的发布、审核、compliance 变更审计。
为未来 Agent Runtime 引用提供稳定的 skillVersionId 和 complianceSnapshotDigest。

2.2 Agent Runtime 职责

Agent Runtime，例如 Astron、Claude Code、Codex、OpenClaw 或其他执行方，负责：

实际加载和执行技能。
生成 execution trace。
记录本次执行使用的 skill coordinate、skill version、skillVersionId 和 complianceSnapshotDigest。
记录运行时输入输出摘要、审批 gate、执行结果、错误和运行时策略。

SkillHub 不记录 Agent 每次执行，也不实现 Agent execution trace。

3. 非目标

第一阶段不做以下内容：

不新增独立 compliance 查询 API。
不实现 Astron execution trace。
不新增复杂 facet / 聚合搜索。
不引入外部审计系统集成。
不把 compliance 当作已经存在的上游通用标准字段。
不为了 compliance 过早新建复杂表结构，除非后续性能或查询需求明确。

4. 协议草案

建议在 SKILL.md frontmatter 中先支持 SkillHub/Astron 私有扩展字段 x-astron-compliance：

---
name: incident-response-helper
description: Guide analysts through incident response triage and evidence collection.
version: "1.2.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
      - type: external-url
        url: https://attack.mitre.org/techniques/T1059/
---

字段含义：

字段	含义
`standard`	标准名称，例如 `mitre-attack`、`nist-csf`、`soc2`、`hipaa`
`version`	标准版本，例如 `v19.1`、`2.0`
`controlId`	标准控制项、技术编号或条款 ID
`title`	人类可读名称
`evidence`	证据列表
`evidence.type`	`packaged-file` 或 `external-url`
`evidence.path`	技能包内证据文件路径，仅 `packaged-file` 使用
`evidence.url`	外部证据链接，仅 `external-url` 使用

未来兼容策略：

写入规范：第一阶段只推荐作者写 x-astron-compliance。
读取兼容：如果后续生态出现公开 compliance 字段，解析器可以同时读取 compliance 和 x-astron-compliance，但需要定义冲突优先级。
对外展示：UI 和审计报告仍统一展示为“Compliance Metadata”，不暴露内部字段名前缀给普通用户。

5. 版本级 Snapshot

发布时，SkillHub 将 compliance 规范化为版本级 snapshot，并写入版本元数据。

第一阶段优先复用：

skill_version.parsed_metadata_json

建议结构：

{
  "frontmatter": {
    "name": "incident-response-helper",
    "description": "Guide analysts through incident response triage and evidence collection.",
    "version": "1.2.0",
    "x-astron-compliance": []
  },
  "complianceSnapshot": {
    "schemaVersion": "1.0",
    "items": [
      {
        "standard": "mitre-attack",
        "version": "v19.1",
        "controlId": "T1059",
        "title": "Command and Scripting Interpreter",
        "evidence": [
          {
            "type": "packaged-file",
            "path": "references/standards.md",
            "sha256": "..."
          },
          {
            "type": "external-url",
            "url": "https://attack.mitre.org/techniques/T1059/"
          }
        ]
      }
    ],
    "digest": "sha256:..."
  }
}

digest 用于未来运行时 trace 或外部审计引用。第一阶段只生成并写入 parsed_metadata_json，不新增独立 endpoint；后续再通过既有详情或版本详情投影给前端。

6. 分步执行计划

Phase 1：协议和领域模型

目标：先把 x-astron-compliance 字段定义清楚，并放在领域层。

建议新增位置：

server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/metadata/

候选对象：

ComplianceMapping
ComplianceEvidence
ComplianceEvidenceType
ComplianceMetadataService
ComplianceSnapshot

设计要求：

SkillMetadataParser 继续只负责解析 frontmatter，不承担 compliance 业务校验。
ComplianceMetadataService 负责提取、规范化、校验 compliance。
不在 controller 中做 compliance 校验。
使用已有 x-astron-* 私有扩展命名空间，不新增未验证的公开字段。

Phase 2：发布时解析和校验

目标：技能发布时能识别并校验 compliance。

接入点：

SkillPackageValidator
SkillPublishService
SkillVersion.parsedMetadataJson

基础校验规则：

x-astron-compliance 缺失时兼容旧技能。
x-astron-compliance 存在时必须是数组。
每个 mapping 必须是对象。
standard、version、controlId 必填。
title 可选，但应有长度限制。
evidence 可选；提供时必须是数组。
同一版本内不允许重复 standard + version + controlId。
mapping 数量、evidence 数量和字符串长度要有上限。

证据校验规则：

packaged-file.path 必须存在于技能包。
packaged-file.path 不允许 ../ 路径逃逸。
external-url.url 只允许 http / https。
包内证据文件应计算 sha256 并写入 snapshot。

错误信息要求：

使用现有 i18n 机制。
不在领域服务中散落不可翻译的长英文错误字符串。

Phase 3：固化版本级 Snapshot

目标：每个技能版本都有不可变 compliance snapshot。

实现要求：

发布成功后生成规范化 complianceSnapshot。
snapshot 内容和 digest 与该 SkillVersion 绑定。
后续详情、审核、搜索均读取 snapshot，不重新解释最新源码。
snapshot 为空时也要有确定行为，避免旧技能受影响。

第一阶段不强制新建表。后续出现结构化过滤、统计或性能瓶颈时，再考虑：

jsonb GIN index；
skill_version_compliance_mapping 表；
搜索 projection 表扩展。

Phase 4：已有接口投影，不新增独立 API

目标：让前端和审核能看到 compliance，但不发布猜测性 public API。

建议：

在已有技能详情或版本详情 response 中增加 compliance projection。
审核详情中带出当前版本 compliance snapshot。
不新增以下 endpoint：

GET /api/skills/{namespace}/{slug}/versions/{version}/compliance
GET /api/skills/{namespace}/{slug}/versions/{version}/metadata

后续只有出现明确使用方时再新增独立 API，例如：

Agent Runtime 只需要拉 compliance snapshot，不需要完整技能详情。
企业审计系统按 skillVersionId 拉取合规声明。
前端需要单独比较两个版本的 compliance diff。
完整 detail payload 性能不可接受。

如果后续需要独立 API，优先考虑按不可变版本 ID 设计：

GET /api/skill-versions/{skillVersionId}/compliance

Phase 5：轻量搜索

目标：先提升可发现性，不直接做复杂 facet。

后续阶段：

在搜索文档重建时，将 snapshot 中的 standard、controlId、title 加入搜索文本。
用户搜索 T1059、mitre-attack、nist-csf 时能命中对应技能。

更后续再考虑：

按 standard filter。
按 controlId filter。
compliance coverage 聚合。
独立索引或结构化 projection。

Phase 6：审核和审计

目标：只记录 SkillHub 自己发生的事实。

审核展示：

当前版本 compliance snapshot。
与上一发布版本的 diff：
- 新增 mapping；
- 删除 mapping；
- 修改 mapping；
- evidence 变化；
- digest 变化。

审计记录：

发布时记录 compliance digest。
审核通过 / 拒绝时记录 compliance diff 摘要。
evidence 变化作为风险信息进入 audit detail。

不记录：

Agent 执行输入输出。
Astron trace。
runtime 调用结果。

Phase 7：文档

目标：让技能作者、平台维护者和 Agent Runtime 接入方都理解边界。

需要更新的文档：

docs/07-skill-protocol.md：实现稳定后补充正式 x-astron-compliance 协议。
用户文档：说明如何在 SKILL.md 中声明 x-astron-compliance。
管理员文档：说明发布校验、审核 diff、审计记录。
集成文档：说明 Runtime 如何引用 skillVersionId + complianceSnapshotDigest。

文档必须明确：

SkillHub 只提供版本级 compliance snapshot。运行时 trace 由 Agent Runtime 记录，并可引用 SkillHub 的 skillVersionId 和 complianceSnapshotDigest。

Phase 8：测试

单元测试：

无 x-astron-compliance 的旧技能正常发布。
合法 x-astron-compliance 正常解析。
standard 缺失失败。
version 缺失失败。
controlId 缺失失败。
重复 standard + version + controlId 失败。
packaged-file.path 不存在失败。
packaged-file.path 路径逃逸失败。
external-url.url scheme 非法失败。
digest 稳定生成。

发布链路测试：

上传含 x-astron-compliance 的技能包成功。
上传非法 x-astron-compliance 的技能包失败。
发布后 parsedMetadataJson 包含 complianceSnapshot。
snapshot digest 与内容一致。

搜索测试：

搜标准名能命中。
搜 controlId 能命中。
无 compliance 的旧技能不受影响。

审核测试：

新版本新增 compliance。
新版本删除 compliance。
新版本修改 evidence。
审核详情能看到 diff。

7. 推荐 PR 拆分

PR 1：协议、解析、校验、快照

范围：

domain metadata service；
package validator；
publish snapshot；
parsedMetadataJson 结构；
单元测试和发布链路测试。

不包含：

UI；
搜索 facet；
独立 API；
Agent trace。

PR 2：详情页和审核展示

范围：

既有 response 增加 compliance projection；
技能详情展示；
审核 diff 展示；
前端测试。

PR 3：轻量搜索

范围：

搜索文档增加 compliance keywords；
搜索测试。

不做复杂 facet。

PR 4：文档和 Runtime 集成契约

范围：

用户文档；
管理员文档；
Runtime 引用方式；
skillVersionId + complianceSnapshotDigest 契约说明。

不实现 Astron trace。

8. 最终架构原则

SkillHub 不执行技能，因此不记录执行 trace。
SkillHub 是 skill metadata 和 version snapshot 的权威源。
Agent Runtime 是 execution trace 的权威源。
合规审计通过 skillVersionId + complianceSnapshotDigest 把两边事实关联起来。
第一阶段不发布猜测性 API；先通过已有详情和版本投影满足内部使用。
先做稳定协议和可验证快照，再做 UI、搜索和外部集成。

13 KiB Raw Permalink Blame History Unescape Escape