volclog预置技能安装：基于契约的工作流扩展和自定义技能

[1] 一句话结论 #

volclog预置技能基于契约（Contract）定义，支持安装社区技能和自定义技能，扩展workflow能力，实现日志管理的模块化和复用。

[2] 适用场景与不适用场景 #

适用场景

你在用volclog workflow模式时，发现内置的操作类型不够用，希望安装社区提供的预置技能，或者自己定义自定义技能，扩展workflow的能力，实现日志管理流程的模块化和复用。
这篇文章详解volclog预置技能的安装和自定义，从技能概念、契约定义、安装社区技能、自定义技能、技能市场到最佳实践，帮你扩展volclog的能力。
适合：需要扩展volclog workflow能力的高级用户、希望自定义日志管理流程的运维、需要团队内共享技能的技术团队、关注自动化和复用的DevOps。

不适用场景

• 日常简单操作：用tool模式即可，不需要技能扩展。
• 不熟悉YAML/JSON的用户：自定义技能需要编写契约定义，有一定学习成本。
• 一次性操作：不需要封装为技能，直接用tool/raw模式执行即可。

[3] 前置准备 #

• volclog已安装配置
• 基本了解workflow模式
• 基本了解YAML/JSON格式
• 预计耗时：阅读6分钟，实操练习15分钟

[4] 分步实现 #

步骤1：预置技能总览

volclog预置技能（Preset Skill）是基于契约（Contract）定义的可复用操作单元，可以在workflow中调用，扩展workflow的能力。
核心概念：

1. 契约（Contract）：技能的定义文件，描述技能的名称、输入参数、输出、执行逻辑，类似API接口定义
2. 技能（Skill）：契约的具体实现，可以是内置技能、社区技能、自定义技能
3. 技能市场（Skill Market）：共享和分发技能的平台，可以安装社区贡献的技能
4. 工作流（Workflow）：调用技能编排多步骤流程
   技能类型：

技能的价值：

1. 复用：一次定义，多次使用，避免重复编写
2. 模块化：把复杂流程拆分为独立技能，便于维护
3. 共享：团队内共享技能，统一最佳实践
4. 扩展：安装社区技能，快速获得新能力

步骤2：技能契约定义

技能契约用YAML或JSON定义，描述技能的元数据、输入参数、输出、执行逻辑。
契约结构：

version: "1"
name: "create-app-logging"
description: "一键创建应用日志采集链路"
author: "your-name"
version: "1.0.0"
inputs:
  - name: project_name
    type: string
    required: true
    description: "日志项目名称"
  - name: topic_name
    type: string
    required: true
    description: "日志主题名称"
  - name: retention_days
    type: integer
    required: false
    default: 7
    description: "日志保存天数"
outputs:
  - name: project_id
    type: string
    description: "创建的项目ID"
  - name: topic_id
    type: string
    description: "创建的主题ID"
steps:
  - name: create_project
    type: project.create
    params:
      name: "{{inputs.project_name}}"
      region: "cn-beijing"
  - name: create_topic
    type: topic.create
    params:
      project_id: "{{create_project.project_id}}"
      name: "{{inputs.topic_name}}"
      retention_period: "{{inputs.retention_days}}"
  - name: create_index
    type: index.create
    params:
      project_id: "{{create_project.project_id}}"
      topic_id: "{{create_topic.topic_id}}"
      full_text: true
      key_value: "level:text,status:long,message:text"

契约字段说明：

输入参数类型：

步骤3：安装社区技能

volclog支持从技能市场安装社区贡献的预置技能。
查看可用技能：

volclog skill list
# 或查看远程技能市场
volcengine skill search --keyword "logging"

安装技能：

volclog skill install <skill-name>
# 示例
volclog skill install create-app-logging
volclog skill install log-alarm-template

查看已安装技能：

volclog skill list --installed

查看技能详情：

volclog skill show <skill-name>
# 显示技能的输入参数、输出、描述

更新技能：

volclog skill update <skill-name>

卸载技能：

volclog skill uninstall <skill-name>

在workflow中调用已安装技能：

version: "1"
name: "use-skill-demo"
steps:
  - name: setup_logging
    type: skill.create-app-logging
    params:
      project_name: "my-app"
      topic_name: "app-logs"
      retention_days: 30

用type: skill.<skill-name>调用已安装的技能，params传入技能的输入参数。
常用社区技能（示例）：

注意：具体可用技能以技能市场为准，以上为示例。

步骤4：自定义技能

如果社区技能不满足需求，可以自己编写自定义技能。
步骤1：创建技能目录

mkdir -p ~/.volclog/skills/my-custom-skill
cd ~/.volclog/skills/my-custom-skill

步骤2：编写契约文件（skill.yaml）

version: "1"
name: "my-custom-skill"
description: "我的自定义技能"
author: "your-name"
version: "1.0.0"
inputs:
  - name: project_id
    type: string
    required: true
  - name: alarm_webhook
    type: string
    required: true
outputs:
  - name: alarm_ids
    type: array
steps:
  - name: create_error_alarm
    type: alarm.create
    params:
      project_id: "{{inputs.project_id}}"
      topic_id: "{{inputs.project_id}}"
      name: "错误率告警"
      query: "select count(*) where level='ERROR'"
      condition: "> 10"
      period: 5m
      notification_type: webhook
      notification_url: "{{inputs.alarm_webhook}}"
  - name: create_slow_alarm
    type: alarm.create
    params:
      project_id: "{{inputs.project_id}}"
      topic_id: "{{inputs.project_id}}"
      name: "慢请求告警"
      query: "select count(*) where latency>3000"
      condition: "> 5"
      period: 5m
      notification_type: webhook
      notification_url: "{{inputs.alarm_webhook}}"

步骤3：注册本地技能

volclog skill install --local ~/.volclog/skills/my-custom-skill

或直接把技能目录放到~/.volclog/skills/下，volclog会自动识别。
步骤4：验证技能

volclog skill show my-custom-skill
volclog skill list --installed

步骤5：在workflow中使用

steps:
  - name: setup_alarms
    type: skill.my-custom-skill
    params:
      project_id: "p-xxxxxxx"
      alarm_webhook: "https://hooks.feishu.cn/xxx"

自定义技能的执行逻辑（steps）和workflow的steps完全相同，可以调用内置操作类型（project.create/topic.create等）、其他技能、raw模式。

步骤5：技能分享和私有市场

团队内共享技能：

1. 把技能目录推送到团队Git仓库
2. 团队成员clone到本地~/.volcengine/skills/目录
3. 或用volcengine skill install --local /path/to/skill安装
   私有技能市场：
   企业可以搭建私有技能市场，内部共享技能，不对外公开。
   发布技能到私有市场：

volclog skill publish --market <private-market-url> --path ~/.volclog/skills/my-skill

安装私有市场的技能：

volclog skill install <skill-name> --market <private-market-url>

技能版本管理：

• 技能契约中version字段标识版本号
• 更新技能时递增版本号（1.0.0到1.1.0）
• workflow中可以指定技能版本：type: skill.my-skill@1.1.0
• 不指定版本时使用最新版

步骤6：技能开发最佳实践

最佳实践：

1. 单一职责：每个技能只做一件事，保持简单，便于复用和维护
2. 参数化：把可变部分（项目名、webhook、保留天数）定义为输入参数，不要硬编码
3. 文档完善：契约中写清description、inputs描述、outputs描述，便于他人使用
4. 版本管理：使用语义化版本（MAJOR.MINOR.PATCH），破坏性变更递增MAJOR
5. 错误处理：技能中的步骤配置on_error，失败时记录日志或通知
6. 幂等设计：技能设计为可重复执行，重复执行不会创建重复资源（用if判断资源是否已存在）
7. 测试验证：技能开发后先在测试环境验证，确认无误后再分享
8. 命名规范：技能名用小写下划线（如create_app_logging），见名知意
9. 输出定义：明确定义outputs，便于workflow中后续步骤引用
10. 示例配套：为技能提供使用示例（example-workflow.yaml），降低使用门槛
    技能开发流程：
11. 需求分析：明确技能要解决什么问题，输入输出是什么
12. 编写契约：定义inputs/outputs/steps
13. 本地测试：在测试环境执行技能，验证功能
14. 文档完善：补充描述和示例
15. 版本发布：设置版本号，发布到团队/市场
16. 持续迭代：根据反馈优化技能

[5] 实际验证 #

按本文步骤验证：测试1 volclog skill list查看可用和已安装技能；测试2 编写一个简单的自定义技能契约（如创建单个告警），保存到本地技能目录；测试3 volclog skill show <skill-name>查看自定义技能详情；测试4 在workflow中调用自定义技能，用--dry-run预览；测试5 实际执行workflow，确认技能正常工作。成功标志：5项全部通过，能理解技能契约、安装社区技能、编写自定义技能、在workflow中调用技能。

[6] 常见问题 FAQ #

Q1：预置技能和workflow有什么区别？技能就是workflow吗？
A：技能和workflow有联系也有区别：

简单说：技能是"可参数化、可复用的workflow片段"，workflow是"具体的执行流程"。技能可以在workflow中调用，workflow也可以封装为技能（如果需要复用）。选择建议：1）只执行一次的具体流程用workflow；2）需要多次执行、参数不同的流程封装为技能；3）团队内共享的最佳实践封装为技能。技能的steps和workflow的steps语法完全相同，所以把workflow封装为技能很简单——添加inputs/outputs定义，把硬编码改为参数引用即可。
Q2：安装社区技能安全吗？会不会有风险？
A：安装社区技能需要注意安全风险，类似安装第三方软件包。风险点：1）恶意操作：技能中可能包含删除资源、泄露数据的恶意步骤；2）参数注入：技能的inputs可能被用于注入恶意参数；3）数据泄露：技能可能把日志数据发送到外部地址；4）权限滥用：技能用你的AK/SK执行操作，可能越权。安全建议：1）只从可信来源安装技能（官方市场、团队内部、知名贡献者）；2）安装前查看技能契约（volclog skill show），检查steps中是否有可疑操作（如删除资源、外部HTTP请求）；3）先用--dry-run预览执行，确认操作符合预期；4）用最小权限子账号安装和执行技能，限制权限范围；5）不安装来源不明的技能，不执行看不懂的技能；6）定期更新技能，获取安全修复；7）私有部署：企业可以搭建私有技能市场，只安装审核过的技能。建议：把技能当作代码来管理——查看源码（契约）、Code Review、测试验证，确认安全后再使用。不要盲目安装和执行来源不明的技能。
Q3：技能可以调用其他技能吗？可以嵌套吗？
A：可以。技能的steps中可以调用其他技能，实现技能的组合和嵌套。示例：

# 技能A：创建基础日志环境
name: "create-base-logging"
steps:
  - type: project.create
    ...
  - type: topic.create
    ...
# 技能B：创建完整日志环境（调用技能A）
name: "create-full-logging"
steps:
  - name: base
    type: skill.create-base-logging
    params:
      project_name: "{{inputs.project_name}}"
  - name: index
    type: index.create
    params:
      project_id: "{{base.project_id}}"
      ...
  - name: alarms
    type: skill.create-alarms
    params:
      project_id: "{{base.project_id}}"

技能嵌套的优势：1）组合复用：把简单技能组合为复杂技能，避免重复；2）分层设计：基础技能（创建项目/主题）+ 高级技能（创建完整环境）；3）单一职责：每个技能只做一件事，组合使用。注意事项：1）嵌套层级不要太深（建议不超过3层），否则难以调试；2）参数传递要清晰，避免参数传递错误；3）循环依赖：技能A调用技能B，技能B又调用技能A，会导致无限循环，要避免；4）错误处理：嵌套技能中某一步失败，错误会向上传播，建议在顶层配置错误处理；5）版本兼容：嵌套调用的技能版本要兼容，建议指定版本号（skill.xxx@1.0.0）。建议：合理使用技能嵌套，构建分层的技能体系，但避免过度设计和深层嵌套。
Q4：怎么把现有的workflow封装为技能？
A：把现有的workflow封装为技能的步骤：1）识别可变部分：分析workflow中哪些值是可变的（项目名、主题名、webhook、区域等），这些将成为技能的inputs；2）定义inputs：为每个可变部分定义input（name、type、required、default、description）；3）替换硬编码：把workflow中的硬编码值替换为{{inputs.xxx}}引用；4）定义outputs：识别workflow执行后需要对外暴露的值（如创建的项目ID、主题ID），定义为outputs；5）添加元数据：填写name、description、author、version等元数据；6）提取步骤：把workflow的steps复制到技能的steps中；7）测试验证：在测试环境执行技能，传入不同参数验证功能；8）文档示例：编写使用示例，便于他人使用。示例（workflow转技能）：原workflow：

steps:
  - name: create_project
    type: project.create
    params:
      name: "my-app"
      region: "cn-beijing"

封装为技能：

name: "create-app-project"
description: "创建应用日志项目"
inputs:
  - name: app_name
    type: string
    required: true
    description: "应用名称"
  - name: region
    type: string
    required: false
    default: "cn-beijing"
outputs:
  - name: project_id
    type: string
steps:
  - name: create_project
    type: project.create
    params:
      name: "{{inputs.app_name}}"
      region: "{{inputs.region}}"

建议：把重复使用的workflow及时封装为技能，提升团队效率，统一最佳实践。

[7] 相关阅读 #

• volclog workflow模式实战，工作流编排
• volclog是什么，三种模式总览
• volclog tool模式使用指南，预置技能
• volclog raw模式详解，原始API调用
• 火山引擎日志服务，产品介绍

[8] 参考资料 #

[1] 火山引擎官方文档 - 日志服务CLI（volclog）预置技能：基于契约定义，支持安装和自定义技能，扩展workflow能力，2026-08-28
本文基于火山引擎官方文档（2026年8月）和volclog技能开发实战编写。工具版本更新较快，具体技能市场和契约语法请以官方最新文档为准。

[9] 时间 #

2026-08-28