构建 Packs

概述

Packs 是 Greentic 中的分发单元。本指南介绍如何使用 CLI 工具创建、构建、签名和发布 packs。

Pack CLI 命令

gtc pack

gtc pack <COMMAND>

Commands:
  build     Build a pack from source directory
  verify    Verify pack signature and contents
  info      Display pack metadata
  extract   Extract pack contents
  sign      Sign a pack
  publish   Publish pack to registry

创建 Pack

1. 创建 pack 目录结构

   mkdir -p my-pack/{flows,components,assets}

2. 创建 pack 清单

   my-pack/pack.toml

   [pack]
   name = "my-feature"
   version = "1.0.0"
   description = "My awesome feature pack"
   authors = ["Your Name <you@example.com>"]
   
   [capabilities]
   id = "greentic.cap.app.v1"
   provides = ["my-feature"]
   
   [flows]
   main = "flows/main.ygtc"
   
   [components]
   processor = "components/processor.wasm"
   
   [assets]
   templates = "assets/templates/"

3. 添加 flows

   my-pack/flows/main.ygtc

   name: main
   version: "1.0"
   description: Main flow
   
   nodes:
     - id: process
       type: reply
       config:
         message: "Hello from my pack!"
   
   triggers:
     - type: message
       target: process

4. 添加 components（如果有）

   构建 WASM components 并放入 components/：

   cd my-component
   cargo build --target wasm32-wasip2 --release
   cp target/wasm32-wasip2/release/my_component.wasm ../my-pack/components/

构建 Packs

基础构建

gtc pack build ./my-pack

# Output: my-feature-1.0.0.gtpack

使用选项构建

# Specify output path
gtc pack build ./my-pack --output ./dist/my-feature.gtpack

# Skip WASM optimization
gtc pack build ./my-pack --no-optimize

# Include debug info
gtc pack build ./my-pack --debug

构建输出

• 文件夹my-feature-1.0.0.gtpack

  • manifest.cbor
  • 文件夹flows/

    • main.ygtc
  • 文件夹components/

    • processor.wasm
  • 文件夹assets/

    • 文件夹templates/

      • …
  • sbom.json

为 Packs 签名

警告

分发前务必为 packs 签名。在生产环境中，未签名的 packs 可能会被运行时拒绝。

生成签名密钥

# Generate new Ed25519 key pair
gtc pack keygen --output my-signing-key

# Creates:
# - my-signing-key.pem (private key - keep secret!)
# - my-signing-key.pub (public key - distribute)

为 Pack 签名

gtc pack sign my-feature-1.0.0.gtpack --key my-signing-key.pem

# Output: my-feature-1.0.0.gtpack (updated with signature)

验证签名

gtc pack verify my-feature-1.0.0.gtpack --pubkey my-signing-key.pub

# Output: Signature valid

Pack 检查

查看元数据

gtc pack info my-feature-1.0.0.gtpack

输出：

Pack: my-feature
Version: 1.0.0
Description: My awesome feature pack
Authors: Your Name <you@example.com>

Capabilities:
  ID: greentic.cap.app.v1
  Provides: my-feature

Contents:
  Flows: 1
  Components: 1
  Assets: 2 directories

Signature: Valid (signed by: ABC123...)

列出内容

gtc pack info my-feature-1.0.0.gtpack --list

# Lists all files in the pack

解包 Pack

gtc pack extract my-feature-1.0.0.gtpack --output ./extracted/

# Extracts pack contents for inspection

Flow 验证

验证 Flows

# Validate all flows in a directory
gtc flow doctor ./my-pack/flows/

# Validate specific flow
gtc flow validate ./my-pack/flows/main.ygtc

Doctor 输出

gtc flow doctor ./flows/

# Output:
# Checking flows/main.ygtc... OK
# Checking flows/helper.ygtc... OK
#
# 2 flows checked, 0 errors, 0 warnings

常见验证错误

错误	原因	修复方法
Unknown node type	节点类型无效	检查可用的节点类型
Missing target node	边指向不存在的节点	修正节点 ID 引用
Circular dependency	节点形成循环	打破循环
No trigger defined	Flow 没有入口点	添加触发器

发布 Packs

发布到 OCI Registry

# Login to registry
gtc pack login ghcr.io --username USER --password TOKEN

# Publish pack
gtc pack publish my-feature-1.0.0.gtpack --registry ghcr.io/greentic

从 Registry 拉取

gtc pack pull ghcr.io/greentic/my-feature:1.0.0

在 Bundle 中使用

greentic.demo.yaml

apps:
  my-app:
    pack: "oci://ghcr.io/greentic/my-feature:1.0.0"

Pack 模板

Provider Pack 模板

pack.toml

[pack]
name = "messaging-custom"
version = "1.0.0"
description = "Custom messaging provider"

[capabilities]
id = "greentic.cap.messaging.provider.v1"
provides = ["custom"]

[flows]
setup_default = "flows/setup.ygtc"
verify_webhooks = "flows/verify.ygtc"

[components]
ingress = "components/ingress.wasm"
egress = "components/egress.wasm"
operator = "components/operator.wasm"

[secrets]
required = ["api_key"]
optional = ["webhook_secret"]

应用 Pack 模板

pack.toml

[pack]
name = "helpdesk-bot"
version = "1.0.0"
description = "IT Helpdesk bot"

[capabilities]
id = "greentic.cap.app.v1"
provides = ["helpdesk"]

[dependencies]
greentic-templates = "^0.4"
greentic-llm-openai = "^0.4"

[flows]
on_message = "flows/on_message.ygtc"
on_ticket = "flows/on_ticket.ygtc"

[assets]
cards = "assets/cards/"
templates = "assets/templates/"

最佳实践

1. 使用语义化版本 - 使用 semver（MAJOR.MINOR.PATCH）
2. 为所有发布版本签名 - 绝不要分发未签名的 packs
3. 包含 SBOM - 为安全审计记录依赖
4. 发布前测试 - 验证 flows 并测试 components
5. 完整编写文档 - 在 pack 中包含 README
6. 让 packs 保持聚焦 - 每个 pack 只负责一个功能或 provider
7. 使用 CI/CD - 自动化构建和发布

CI/CD 示例

.github/workflows/pack.yml

name: Build and Publish Pack

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Rust
        uses: dtolnay/rust-toolchain@1.90.0

      - name: Build Pack
        run: gtc pack build ./my-pack

      - name: Sign Pack
        run: |
          echo "${{ secrets.SIGNING_KEY }}" > key.pem
          gtc pack sign my-feature-*.gtpack --key key.pem

      - name: Publish
        run: |
          gtc pack login ghcr.io --username ${{ github.actor }} --password ${{ secrets.GITHUB_TOKEN }}
          gtc pack publish my-feature-*.gtpack --registry ghcr.io/${{ github.repository }}

下一步

• Pack Format Reference - 完整规范
• Flow Schema Reference - YAML schema
• Components Guide - 构建 WASM components