#创建自定义 Skills

Skills 是过程化提示——逐步的专家操作手册——当用户的问题匹配时，Alauda Hyperflux 会自动加载它们。当查询命中某个 skill 时，skill 主体会注入到 agent 的上下文中，因此答案会遵循你组织的操作步骤，而不是通用回答。

Alauda Hyperflux 内置了故障排查 skills（pod failure diagnosis、node NotReady、ingress 5xx triage、PVC binding failure、routine inspection），开箱即用。 你可以通过 ConfigMaps 添加自己的 skills；与内置 skill 同名的自定义 skill 会覆盖内置 skill。

#匹配机制

每个 skill 都会声明一个 name 和一个 description。在启动时，它们会使用与 knowledge base 相同的 embedding model 进行嵌入；在查询时，用户的问题会通过 cosine similarity 与它们进行比较。得分最高且不低于 Skills Match Threshold（默认值 0.35）的那个 skill 会被注入；低于该阈值则不会发生任何操作。

请相应地编写 description：它是匹配的主要内容。说明该 skill 用于诊断什么，并包含用户可能会使用的短语。

#编写 skill 文件

skill 是带有 YAML frontmatter 的 Markdown 文件：

---
name: etcd-degraded
description: Diagnose an etcd cluster reporting degraded or unhealthy members. Use when the user reports etcd alerts, slow API server, or a control-plane node showing etcd errors.
---

# etcd Degraded Diagnosis

1. List the etcd pods in `kube-system` and check their status and recent events.
2. Check member health: report which member is unhealthy and the specific error.
3. Correlate with node disk pressure or clock skew; cite the exact log line.
4. Recommend the remediation matching the identified cause; do not guess.

规则：

• name（必填）：必须匹配 ^[a-z][a-z0-9_-]*$。同一次扫描中如果存在重复名称：第一个文件生效；自定义 skill 会覆盖同名的内置 skill。
• description（必填）：不能为空；用于驱动匹配。
• Body（必填）：frontmatter 之后的所有内容。请将其控制在 4 KB 以内——更大的 body 仍然会加载，但会记录 warning，并在每次匹配时占用上下文。
• 不符合这些规则的文件会被跳过，并记录 WARN 日志；它们不会导致服务中断。

#通过 ConfigMap 部署 skills

在 Alauda Hyperflux 安装所在的 namespace（cpaas-system）中创建一个 ConfigMap。 每个 *.md 数据键都会作为一个 skill 加载：

apiVersion: v1
kind: ConfigMap
metadata:
  name: my-org-skills-sre
  namespace: cpaas-system
data:
  etcd-degraded.md: |
    ---
    name: etcd-degraded
    description: Diagnose an etcd cluster reporting degraded or unhealthy members. Use when the user reports etcd alerts, slow API server, or a control-plane node showing etcd errors.
    ---

    # etcd Degraded Diagnosis

    1. List the etcd pods in `kube-system` and check their status and recent events.
    2. Check member health: report which member is unhealthy and the specific error.
    3. Correlate with node disk pressure or clock skew; cite the exact log line.
    4. Recommend the remediation matching the identified cause; do not guess.

然后在 管理员 / Marketplace / Cluster Plugins 中安装或更新 Alauda Hyperflux 插件：

• Enable Skills：开启（默认）。
• Skills Match Threshold：保持 0.35，除非 skills 触发过于频繁（提高它）或从不匹配（降低它）。
• Skills ConfigMaps：添加 ConfigMap 名称，例如 my-org-skills-sre。

每个列出的 ConfigMap 都会以只读方式挂载到 /opt/skills/<configmap-name>/，并且在启动时仅扫描一次。在表单中添加或删除 ConfigMap 名称会自动重启服务；修改已注册 ConfigMap 的内容需要手动重启：

kubectl -n cpaas-system rollout restart deploy/smart-doc

#验证

检查启动日志：

kubectl -n cpaas-system logs -l app=smart-doc -c serve | grep '\[skills\]'

加载成功时应显示：

[skills] loaded 6 skill(s) (built-in=5, admin=1 from /opt/skills), threshold=0.35, vec_dim=768

然后在聊天面板中提出一个在语义上与 skill 描述接近的问题。 命中时，日志会显示所选 skill 及其得分：

[skills] selected name=etcd-degraded team=my-org-skills-sre score=0.62 query='...'

如果某个 skill 一直无法匹配，请将日志中的得分与阈值进行比较，并重写 description，使其更接近用户实际的提问方式。

其他值得注意的日志行：