Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Alur kerja

Melaksanakan Transformasi

Bagian ini menjelaskan berbagai cara untuk mengeksekusi transformasi dan opsi untuk mengendalikan perilaku eksekusi.

Mode Eksekusi

AWS Transform custom mendukung tiga mode eksekusi untuk mengakomodasi alur kerja yang berbeda.

Mode Percakapan Interaktif

Mulai CLI dengan atx dan minta agen untuk melakukan transformasi melalui bahasa alami. Mode ini memungkinkan Anda untuk melakukan percakapan penuh dengan agen, mengganggu eksekusi kapan saja, dan memberikan umpan balik selama proses transformasi.

Gunakan mode ini ketika Anda menginginkan kontrol maksimum dan kemampuan untuk memandu agen melalui skenario yang kompleks.

Eksekusi Interaktif Langsung

Gunakan atx custom def exec -n <transformation-name> -p <path> untuk memulai transformasi tertentu secara interaktif. Mode ini memungkinkan Anda untuk meninjau dan berinteraksi dengan agen di awal, selama, atau di akhir eksekusi. Agen akan berhenti di titik keputusan utama dan meminta masukan Anda.

Ini sangat ideal untuk menguji dan menyempurnakan transformasi sebelum menjalankannya secara mandiri.

Anda dapat menjalankan transformasi dalam mode non-interaktif atau mode tanpa kepala. Non-interactive mode menekan prompt selama transformasi bernama. Mode tanpa kepala memungkinkan Anda menjalankan agen dengan prompt teks biasa, melewati antarmuka interaktif sepenuhnya.

Non-interactive modus

Gunakan atx custom def exec -n <transformation-name> -p <path> -x -t untuk otomatisasi penuh. Tambahkan -x untuk menjalankan dalam mode non-interaktif, dan -t untuk mempercayai semua alat secara otomatis tanpa meminta.

Mode ini dirancang untuk integrasi CI/CD pipa dan eksekusi massal di mana tidak ada intervensi manusia yang tersedia atau diinginkan.

Mode tanpa kepala

Untuk menyelesaikan tugas tanpa berinteraksi dengan agen, jalankan atx -x "<prompt>" -t dan berikan instruksi Anda dalam teks biasa.

Eksekusi transformasi tanpa kepala

Gunakan mode ini untuk menerapkan definisi transformasi yang ada ke basis kode Anda. Transformasi berjalan setiap langkah secara otomatis tanpa memerlukan persetujuan Anda.

atx -x "apply transformation definition <transformation_definition_name> to <codebase_path>" -t

Pengembangan transformasi tanpa kepala

Membuat atau memodifikasi definisi transformasi.

Untuk mengonversi definisi transformasi lama ke format keterampilan baru (SKILL.md + referensi/), jalankan perintah berikut:

atx -x "convert <legacy_transformation_definition_name> transformation definition to skill and save as draft" -t

Untuk membuat definisi transformasi baru, jalankan perintah berikut:

atx -x "create a transformation definition to <description> with references docs <reference_docs_path>" -t

Bendera Perintah Umum

Saat menjalankan transformasi denganatx custom def exec, flag berikut biasanya digunakan:

Menggunakan File Konfigurasi

AWS Transform custom mendukung file konfigurasi opsional dalam format YAMG atau JSON. File konfigurasi memungkinkan Anda menentukan parameter eksekusi dan memberikan konteks tambahan kepada agen.

Untuk menggunakan file konfigurasi:

atx custom def exec --configuration file://config.yaml

Anda juga dapat memberikan konfigurasi sebagai pasangan nilai kunci inline:

atx custom def exec --configuration "key=value,key2=value2"

Contoh file konfigurasi (config.yaml):

codeRepositoryPath: ./my-project
transformationName: my-transformation
buildCommand: mvn clean install
additionalPlanContext: |
  The target Java version to upgrade to is Java 17.
  Ensure compatibility with our internal logging framework version 2.3.
validationCommands: |
  mvn test
  mvn verify

additionalPlanContextParameter memberikan konteks tambahan untuk rencana eksekusi agen. Ini sangat berguna dengan transformasi AWS yang dikelola untuk menyesuaikan perilaku mereka untuk kebutuhan spesifik Anda.

Perintah Build dan Validasi

Perintah build atau validasi adalah parameter opsional yang menentukan cara memvalidasi kode Anda selama proses transformasi. AWS Transform custom akan mencoba menyimpulkan perintah build terbaik berdasarkan transformasi jika tidak ditentukan, meskipun disarankan untuk spesifik untuk kualitas.

Contoh perintah build dan validasi:

Bahkan untuk bahasa atau transformasi yang tidak memerlukan pembangunan, memberikan perintah yang memvalidasi hasil dan mengembalikan masalah jika validasi gagal sangat penting untuk meningkatkan kualitas transformasi.

Jika tidak diperlukan build atau validasi, hilangkan input Anda.

Mengontrol Perilaku Belajar

Secara default, AWS Transform custom mengekstrak pelajaran dari setiap eksekusi transformasi. Anda dapat mencegah pembelajaran untuk eksekusi tertentu.

Untuk mencegah pembelajaran dari eksekusi:

atx custom def exec -n my-transformation -p ./my-project -d

--do-not-learnBendera -d atau memilih untuk tidak mengizinkan ekstraksi pelajaran dari eksekusi saat ini.

Melanjutkan Percakapan

AWS Transform custom memungkinkan Anda untuk melanjutkan percakapan sebelumnya dalam 30 hari pembuatan.

Untuk melanjutkan percakapan terbaru:

atx --resume

Untuk melanjutkan percakapan tertentu:

atx --conversation-id <conversation-id>

Menit Agen Pelacakan

AWS Transform custom track menit agen yang dikonsumsi selama sesi transformasi. Menit agen terakumulasi sepanjang siklus hidup percakapan dan ditampilkan saat percakapan berakhir:

Agent minutes used: 12.50

Menit agen bertahan di seluruh interupsi. Jika Anda menyela sesi dengan Ctrl+C dan melanjutkannya nanti, menit yang sebelumnya terakumulasi terbawa dan terus terakumulasi dalam sesi yang dilanjutkan.

Untuk memeriksa Risalah Agen selama sesi interaktif:

Ketik /usage pada prompt input untuk menampilkan Menit Agen yang terakumulasi saat ini tanpa mengakhiri percakapan.

Untuk menetapkan batas anggaran Risalah Agen:

atx custom def exec -n my-transformation -p ./my-project --limit 30

--limitOpsi menetapkan anggaran Menit Agen maksimum untuk sesi tersebut. Agent Minutes mencerminkan waktu kerja agen aktif, bukan waktu jam dinding. Ketika batas tercapai, CLI menampilkan pesan dan keluar dengan instruksi untuk melanjutkan:

⚠️ Budget limit reached: 30.00 / 30.00 Agent Minutes. Exiting.

Anda dapat melanjutkan percakapan nanti dengan batas yang meningkat:

atx --conversation-id <conversation_id> -t --limit <increased_limit>

Pembelajaran Terus Berkelanjutan

Bagian ini menjelaskan cara meninjau dan mengelola pelajaran yang dibuat oleh pembelajaran berkelanjutan.

Memahami Pelajaran

Sistem pembelajaran berkelanjutan secara otomatis mengekstrak pelajaran dari transformasi sebelumnya. Sistem membuatnya secara asinkron berdasarkan:

Pelajaran terakumulasi dari waktu ke waktu saat Anda menjalankan transformasi di berbagai basis kode. Sistem menerapkannya secara otomatis untuk meningkatkan future run. Setiap pelajaran termasuk dalam kategori yang berisi semua pelajaran dari domain yang sama sehingga Anda dapat meninjau pelajaran terkait bersama-sama. Untuk pelajaran yang tidak ingin Anda gunakan, Anda dapat mengarsipkan atau menghapus pelajaran sepenuhnya.

Melihat dan Mengelola Pelajaran

Gunakan learnings perintah untuk membuka sesi interaktif untuk menjelajah dan mengelola pelajaran definisi transformasi.

Untuk membuka penampil pelajaran:

atx custom def learnings -n my-transformation

Penampil membuka daftar kategori pelajaran, masing-masing menunjukkan berapa banyak pelajaran aktif yang dikandungnya. Pilih kategori untuk melihat pelajarannya, lalu pilih pelajaran untuk melihat detail lengkapnya, termasuk badan pelajaran, dampaknya, dan berapa banyak proses sebelumnya yang dikonsultasikan.

Pengarsipan dan Pemulihan Pelajaran

Sistem menerapkan pelajaran secara otomatis. Jika Anda tidak ingin sistem menerapkan pelajaran, Anda dapat mengarsipkannya. Sistem mempertahankan pelajaran yang diarsipkan tetapi tidak menerapkannya ke masa depan. Semua pelajaran yang diarsipkan dikelompokkan bersama sehingga Anda dapat meninjaunya dan mengembalikan apa pun ke penggunaan aktif.

Menghapus Pelajaran

Hapus pelajaran yang tidak berguna secara permanen. Penghapusan tidak dapat dibatalkan, dan sistem mungkin mempelajari kembali pelajaran yang dihapus dari future run.

Pelajaran harus diarsipkan sebelum dapat dihapus.

Konfigurasi Lanjutan

Bagian ini menjelaskan fitur lanjutan dan opsi konfigurasi untuk AWS mengubah kustom.

Variabel lingkungan

Anda dapat menyesuaikan perilaku CLI menggunakan variabel lingkungan.

ATX_SHELL_TIMEOUT

Ganti batas waktu default untuk perintah shell (900 seconds/15 menit).

Linux and macOS

export ATX_SHELL_TIMEOUT=1800  # 30 minutes

Windows (PowerShell)

$env:ATX_SHELL_TIMEOUT=1800  # 30 minutes

Ini berguna untuk basis kode besar atau proses build yang berjalan lama.

ATX_DISABLE_UPDATE_CHECK

Nonaktifkan pemeriksaan versi otomatis dan perbarui pemberitahuan selama eksekusi perintah.

Linux and macOS

export ATX_DISABLE_UPDATE_CHECK=true

Windows (PowerShell)

$env:ATX_DISABLE_UPDATE_CHECK="true"

ATX_GIT_COMMITTER_NAME dan ATX_GIT_COMMITTER_EMAIL

Konfigurasikan identitas penulis yang digunakan untuk komit pos pemeriksaan yang dibuat kustom AWS Transform di repositori Anda saat menerapkan perubahan selama transformasi. Ketika variabel-variabel ini tidak disetel, komit pos pemeriksaan dikaitkan dengan identitas default ()ATX Bot <checkpoint@atx.bot>. Tetapkan kedua variabel untuk mengaitkan pos pemeriksaan ke penulis tertentu.

Linux and macOS

export ATX_GIT_COMMITTER_NAME="Jane Developer"
export ATX_GIT_COMMITTER_EMAIL="jane@example.com"

Windows (PowerShell)

$env:ATX_GIT_COMMITTER_NAME="Jane Developer"
$env:ATX_GIT_COMMITTER_EMAIL="jane@example.com"

Pengaturan Kepercayaan

Pengaturan kepercayaan memungkinkan Anda untuk menyetujui alat dan perintah tertentu untuk dijalankan tanpa permintaan. Anda juga dapat meminta izin eksplisit untuk perintah shell tertentu terlepas dari tingkat kepercayaan. Pengaturan ini dikonfigurasi dalam ~/.aws/atx/trust-settings.yaml file.

File berisi tiga daftar:

Alat tepercaya default:

Mengedit pengaturan kepercayaan:

Anda dapat mengedit file trust-settings.yaml secara manual untuk menambah atau menghapus alat dan perintah tepercaya. Keduanya trustedShellCommands dan alwaysPromptCommands mendukung pola wildcard glob menggunakan. *

Berikut ini menjelaskan setiap daftar perintah dan memberikan contoh:

Session-level kepercayaan:

Selama permintaan interaktif, Anda dapat memilih:

Session-level pengaturan trust bersifat sementara dan diatur ulang saat CLI dimulai ulang, memberikan persetujuan sementara tanpa memodifikasi trust-settings.yaml secara permanen.

Server Protokol Konteks Model (MCP)

AWS Transform CLI mendukung server Model Context Protocol (MCP), yang memperluas fungsinya dengan alat tambahan.

Konfigurasi:

Konfigurasikan server MCP dalam ~/.aws/atx/mcp.json file. AWS Transform CLI mendukung dua jenis server MCP: server berbasis perintah lokal dan server HTTP jarak jauh.

Server berbasis perintah lokal:

Server lokal berjalan sebagai proses anak di mesin Anda. Konfigurasikan mereka dengan command properti:

{
  "mcpServers": {
    "my-local-server": {
      "command": "npx",
      "args": ["-y", "@example/mcp-server"]
    }
  }
}

Server HTTP jarak jauh:

Server jarak jauh terhubung ke server MCP yang dihosting di URL HTTP atau HTTPS. Konfigurasikan mereka dengan url properti:

{
  "mcpServers": {
    "my-remote-server": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${MCP_API_TOKEN}"
      }
    }
  }
}

headersProperti ini opsional dan mendukung ekspansi variabel lingkungan menggunakan ${VAR_NAME} sintaks. Ini memungkinkan Anda untuk menyimpan nilai sensitif seperti token API dalam variabel lingkungan daripada di file konfigurasi.

Properti konfigurasi:

Server berbasis perintah lokal mendukung properti berikut:

Server HTTP jarak jauh mendukung properti berikut:

Mengelola server MCP:

Lihat daftar server MCP yang dikonfigurasi:

atx mcp tools

Daftar alat yang tersedia yang ditawarkan oleh server MCP tertentu:

atx mcp tools --server <server-name>

Pelacakan penggunaan:

CLI secara otomatis melacak penggunaan alat MCP selama eksekusi transformasi. Statistik penggunaan dipertahankan seperti mcp_usage.json di direktori percakapan di sampingmetadata.json. File merekam metrik per-alat untuk setiap eksekusi, termasuk:

Client-Side Keterampilan

Client-side keterampilan adalah kemampuan tambahan yang memperluas agen selama eksekusi transformasi. Mereka memungkinkan Anda untuk menyediakan alat khusus, skrip, dan instruksi yang dapat digunakan agen bersama kemampuan bawaannya.

Direktori penemuan keterampilan:

Keterampilan ditemukan dari empat direktori dalam urutan prioritas. Jika keterampilan dengan nama yang sama ada di beberapa direktori, direktori pertama dalam daftar diprioritaskan:

.aws/atx/skills/Direktori khusus untuk AWS Transform CLI. .agents/skills/Direktori adalah cross-client, yang berarti keterampilan yang ditempatkan di sana tersedia untuk perkakas agen yang kompatibel di luar Transform AWS CLI.

Struktur direktori keterampilan:

Setiap skill adalah direktori yang berisi SKILL.md file dengan frontmatter YAMM:

~/.aws/atx/skills/
└── my-skill/
    ├── SKILL.md          # Required: frontmatter + instructions
    ├── references/       # Optional: reference docs the agent can read
    │   └── guide.md
    └── scripts/          # Optional: scripts the agent can execute
        └── validate.py

SKILL.md format:

---
name: my-skill
description: When to use this skill
---
# Skill Title

Instructions for the agent...

nameBidang harus cocok dengan nama direktori induk.

Menonaktifkan keterampilan:

Untuk mencegah keterampilan dimuat tanpa menghapus file-nya, tambahkan disable-model-invocation: true ke frontmatter:

---
name: my-skill
description: When to use this skill
disable-model-invocation: true
---

Ketika properti ini diatur, CLI melewatkan keterampilan selama penemuan. Agen tidak dapat melihat atau menggunakan keterampilan kecuali definisi transformasi secara eksplisit menginstruksikannya untuk membaca file keterampilan. Gunakan ini untuk menonaktifkan sementara keterampilan, menandainya sebagai pekerjaan yang sedang berlangsung, atau menyimpan materi referensi yang ditujukan hanya untuk pembaca manusia.

Ketersediaan keterampilan dengan mode eksekusi:

Memverifikasi penemuan keterampilan:

Periksa log debug CLI setelah dijalankan untuk memverifikasi keterampilan mana yang ditemukan:

Linux and macOS

grep -i "skill" ~/.aws/atx/logs/debug.log | tail -20

Windows (PowerShell)

Select-String -Pattern "skill" "$env:USERPROFILE\.aws\atx\logs\debug.log" | Select-Object -Last 20

Keterampilan yang gagal validasi dilewati dengan peringatan di log debug.

Memilih Antara Project-Level dan User-Level Keterampilan

Di mana Anda menempatkan keterampilan menentukan siapa yang mendapat manfaat darinya dan kapan itu diaktifkan.

Project-level keterampilan (<project>/.aws/atx/skills/):

Komit ini ke kontrol versi sehingga setiap anggota tim yang menjalankan transformasi terhadap repositori secara otomatis menemukannya. Gunakan keterampilan tingkat proyek untuk:

User-level keterampilan (~/.aws/atx/skills/):

Ini tetap ada di mesin Anda dan diaktifkan selama semua transformasi terlepas dari repositori mana yang Anda targetkan. Gunakan keterampilan tingkat pengguna untuk:

Kiat untuk keterampilan yang efektif:

Client-Side Contoh Keterampilan

Contoh-contoh ini menunjukkan dua pola umum: keterampilan validasi berbasis skrip dan keterampilan referensi saja.

Contoh: Dockerfile Compliance Checker () Script-Based

Keterampilan ini memvalidasi Dockerfiles terhadap praktik terbaik keamanan dan operasional. Ini menggunakan skrip validasi yang dijalankan agen sebelum dan sesudah membuat perubahan.

Struktur direktori:

.aws/atx/skills/
└── dockerfile-compliance/
    ├── SKILL.md
    ├── scripts/
    │   └── lint_dockerfile.sh
    └── references/
        └── dockerfile-best-practices.md

SKILL.md:

---
name: dockerfile-compliance
description: Validates Dockerfiles against security and operational best practices
---
# Dockerfile Compliance Checker

When a transformation creates or modifies Dockerfiles, run the compliance checker.

## When to use

- After creating a new Dockerfile
- After modifying FROM, RUN, USER, or EXPOSE directives
- When containerizing an application as part of a transformation

## How to use

Run: `bash scripts/lint_dockerfile.sh <path-to-Dockerfile>`

If violations are found, consult `references/dockerfile-best-practices.md`
for compliant patterns.

Skrip validasi memeriksa tag gambar dasar yang tidak disematkan, berjalan sebagai root, rahasia hardcode dalam ENV arahan, dan definisi yang hilang. HEALTHCHECK Agen menjalankan skrip, memperbaiki pelanggaran menggunakan pola dari file referensi, dan menjalankan kembali skrip untuk mengonfirmasi kepatuhan.

Contoh: API Deprecation Helper () Reference-Only

Keterampilan ini memandu agen untuk mengganti panggilan API yang tidak digunakan lagi selama transformasi pemutakhiran. Ini hanya menggunakan file referensi tanpa skrip.

Struktur direktori:

.aws/atx/skills/
└── api-deprecation-helper/
    ├── SKILL.md
    └── references/
        ├── aws-sdk-v2-to-v3.md
        └── react-class-to-hooks.md

SKILL.md:

---
name: api-deprecation-helper
description: Guides the agent through replacing deprecated API calls with modern equivalents
---
# API Deprecation Helper

When performing upgrade transformations, use this skill to identify and replace
deprecated API calls with their modern equivalents.

## When to use

- During any version upgrade transformation
- When build warnings mention deprecated APIs
- When transforming code that uses legacy patterns

## Process

1. Identify deprecated API calls in the codebase
2. For each deprecated call, find the replacement in `references/`
3. Apply the replacement, preserving the original behavior
4. Verify the replacement compiles and tests pass

File referensi berisi contoh kode sebelum dan sesudah. Misalnya, pola aws-sdk-v2-to-v3.md peta seperti yang s3.putObject(params).promise() setara dengan modular v3 menggunakan S3Client danPutObjectCommand.

Tag dan Organisasi

Anda dapat mengatur transformasi dengan tag untuk kontrol akses dan kategorisasi.

Untuk membuat daftar tag untuk transformasi:

atx custom def list-tags --arn <transformation-arn>

Untuk menambahkan tag ke transformasi:

atx custom def tag --arn <transformation-arn> --tags '{"env":"prod","team":"backend"}'

Untuk menghapus tag dari transformasi:

atx custom def untag --arn <transformation-arn> --tag-keys "env,team"

Tag dapat digunakan untuk kontrol akses yang dikelompokkan dalam kebijakan IAM. Anda dapat membuat kebijakan yang memberikan izin untuk semua transformasi dengan tag tertentu (misalnya, semua transformasi yang ditandai dengan atau). team:frontend environment:production

Beberapa catatan

AWS Transform CLI memelihara tiga jenis log untuk pemecahan masalah dan debugging.

Log percakapan:

Linux and macOS

~/.aws/atx/custom/<conversation_id>/logs/<timestamp>-conversation.log

Windows

%USERPROFILE%\.aws\atx\custom\<conversation_id>\logs\<timestamp>-conversation.log

Log ini berisi riwayat percakapan lengkap untuk sesi tertentu.

Log subagent:

Linux and macOS

~/.aws/atx/custom/<conversation_id>/logs/subagents/<name>.log

Windows

%USERPROFILE%\.aws\atx\custom\<conversation_id>\logs\subagents\<name>.log

Log ini berisi output dari subagen yang ditimbulkan oleh agen utama selama transformasi. Anda tidak perlu mengelola subagen secara langsung.

Log debug pengembang:

Linux and macOS

~/.aws/atx/logs/debug*.log
~/.aws/atx/logs/error.log

Windows

%USERPROFILE%\.aws\atx\logs\debug*.log
%USERPROFILE%\.aws\atx\logs\error.log

Log ini memberikan informasi pemecahan masalah lanjutan untuk CLI itu sendiri.

Pembaruan CLI

Perbarui CLI Anda untuk mengakses fitur dan peningkatan baru.

Untuk memeriksa pembaruan:

atx update --check

Untuk memperbarui ke versi terbaru:

atx update

Untuk memperbarui ke versi tertentu:

atx update --target-version <version>

Buat Transformasi Kustom

Bagian ini menjelaskan cara membuat, memodifikasi, dan mengelola definisi transformasi kustom.

Menciptakan Transformasi Baru

Gunakan CLI interaktif untuk membuat definisi transformasi baru.

Untuk membuat definisi transformasi

Praktik terbaik untuk membuat transformasi:

Menyediakan Bahan Referensi

Anda dapat memberikan file referensi ke AWS Transform custom dengan menentukan path file selama percakapan. File-file ini disimpan dalam references/ folder definisi transformasi.

Jenis file referensi yang direkomendasikan:

Untuk menyediakan file referensi:

Take a look at the documentation here: /path/to/migration-guide.md

Anda juga dapat menyediakan direktori yang berisi beberapa file referensi:

Take a look at the docs we have here: /path/to/docs/

Memodifikasi Transformasi yang Ada

Anda dapat memodifikasi transformasi kustom sebelum dan sesudah menyimpannya sebagai draf atau menerbitkannya. Anda tidak dapat memodifikasi transformasi AWS-managed. Jika Anda perlu menyesuaikannya, Anda dapat memberikan konteks tambahan menggunakan file konfigurasi.

Untuk memodifikasi transformasi yang ada

Menerbitkan dan Mengelola Transformasi

Anda dapat mempublikasikan dan mengelola transformasi Anda menggunakan pengalaman interaktif atau dengan perintah berikut.

Untuk menyimpan transformasi sebagai konsep:

atx custom def save-draft -n my-transformation --description "Description of the transformation" --sd ./transformation-directory

Untuk mempublikasikan transformasi:

atx custom def publish -n my-transformation --description "Description of the transformation" --sd ./transformation-directory

Untuk membuat daftar transformasi yang tersedia:

atx custom def list

Untuk mengunduh definisi transformasi:

atx custom def get -n my-transformation

Ini mengunduh definisi transformasi ke direktori kerja Anda saat ini. Anda dapat menentukan direktori target dengan --td bendera dan versi dengan --tv bendera.

Untuk menghapus definisi transformasi:

atx custom def delete -n my-transformation

Mengelola Versi Transformasi

AWS Transform custom mempertahankan versi definisi transformasi Anda. Anda dapat menentukan versi saat menjalankan atau mengunduh transformasi.

Untuk menjalankan versi tertentu:

atx custom def exec -n my-transformation --tv v1 -p ./my-project

Untuk mengunduh versi tertentu:

atx custom def get -n my-transformation --tv v1

Jika tidak ada versi yang ditentukan, versi terbaru digunakan.