diff --git a/README.md b/README.md index aefb7b97..39e67e6e 100644 --- a/README.md +++ b/README.md @@ -96,6 +96,13 @@ By default it opens `http://127.0.0.1:8766` in your browser (loopback only). See IaC Code Web app

+### Agent Skill + +Add IaC Code to a compatible agent to plan cloud architectures, work with ROS or Terraform templates, estimate costs, +operate stacks, and deploy Alibaba Cloud resources from the agent conversation. Download the +[latest stable Skill package](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/iac-code-skill.zip) +or compare the distributions in [Official IaC Code Skills](https://aliyun.github.io/iac-code/docs/a2a/skill-overview). + ## Contributing Install [uv](https://docs.astral.sh/uv/getting-started/installation/), then: diff --git a/readme/README.de.md b/readme/README.de.md index 44e65c94..64289b5b 100644 --- a/readme/README.de.md +++ b/readme/README.de.md @@ -98,6 +98,10 @@ Standardmäßig öffnet sie `http://127.0.0.1:8766` in Ihrem Browser (nur Loopba IaC Code Web-App

+### Agent Skill + +Fuegen Sie IaC Code einem kompatiblen Agenten hinzu, um im Gespraech Cloud-Architekturen zu planen, ROS- oder Terraform-Vorlagen zu bearbeiten, Kosten zu schaetzen, Stacks zu verwalten und Alibaba-Cloud-Ressourcen bereitzustellen. Laden Sie den [aktuellen stabilen Skill](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/iac-code-skill.zip) herunter oder vergleichen Sie die Distributionen im [Ueberblick ueber offizielle IaC Code Skills](https://aliyun.github.io/iac-code/de/docs/a2a/skill-overview). + ## Mitwirken Installieren Sie [uv](https://docs.astral.sh/uv/getting-started/installation/), dann: diff --git a/readme/README.es.md b/readme/README.es.md index 14e7d149..3a1021f9 100644 --- a/readme/README.es.md +++ b/readme/README.es.md @@ -98,6 +98,10 @@ De forma predeterminada, abre `http://127.0.0.1:8766` en tu navegador (solo bucl Aplicación web de IaC Code

+### Agent Skill + +Añade IaC Code a un agente compatible para diseñar arquitecturas cloud, trabajar con plantillas ROS o Terraform, estimar costes, gestionar stacks y desplegar recursos de Alibaba Cloud desde la conversación. Descarga el [último Skill estable](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/iac-code-skill.zip) o compara las distribuciones en la [visión general de los Skills oficiales](https://aliyun.github.io/iac-code/es/docs/a2a/skill-overview). + ## Contribuir Instale [uv](https://docs.astral.sh/uv/getting-started/installation/), luego: diff --git a/readme/README.fr.md b/readme/README.fr.md index 8dd7b475..8bccb4b3 100644 --- a/readme/README.fr.md +++ b/readme/README.fr.md @@ -98,6 +98,10 @@ Par défaut, elle ouvre `http://127.0.0.1:8766` dans votre navigateur (bouclage Application web IaC Code

+### Agent Skill + +Ajoutez IaC Code à un agent compatible pour concevoir des architectures cloud, travailler sur des templates ROS ou Terraform, estimer les coûts, gérer des stacks et déployer des ressources Alibaba Cloud depuis la conversation. Téléchargez le [dernier Skill stable](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/iac-code-skill.zip) ou comparez les distributions dans la [présentation des Skills IaC Code officiels](https://aliyun.github.io/iac-code/fr/docs/a2a/skill-overview). + ## Contribuer Installez [uv](https://docs.astral.sh/uv/getting-started/installation/), puis : diff --git a/readme/README.ja.md b/readme/README.ja.md index b307d99c..e52325e6 100644 --- a/readme/README.ja.md +++ b/readme/README.ja.md @@ -98,6 +98,10 @@ iac-code web IaC Code Web アプリ

+### Agent Skill + +IaC Code を対応エージェントに追加すると、会話からクラウド構成の設計、ROS/Terraform テンプレート、料金見積もり、スタック操作、Alibaba Cloud リソースのデプロイを行えます。[最新の安定版 Skill](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/iac-code-skill.zip)をダウンロードするか、[IaC Code 公式 Skills の概要](https://aliyun.github.io/iac-code/ja/docs/a2a/skill-overview)で配布方法を比較してください。 + ## コントリビュート [uv](https://docs.astral.sh/uv/getting-started/installation/) をインストールしてから： diff --git a/readme/README.pt.md b/readme/README.pt.md index 79164803..1db84415 100644 --- a/readme/README.pt.md +++ b/readme/README.pt.md @@ -98,6 +98,10 @@ Por padrão, ele abre `http://127.0.0.1:8766` no seu navegador (apenas loopback) Aplicativo web do IaC Code

+### Agent Skill + +Adicione o IaC Code a um agente compatível para planejar arquiteturas em nuvem, trabalhar com templates ROS ou Terraform, estimar custos, operar stacks e implantar recursos do Alibaba Cloud a partir da conversa. Baixe o [Skill estável mais recente](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/iac-code-skill.zip) ou compare as distribuições na [visão geral dos Skills oficiais](https://aliyun.github.io/iac-code/pt/docs/a2a/skill-overview). + ## Contribuir Instale o [uv](https://docs.astral.sh/uv/getting-started/installation/), depois: diff --git a/readme/README.zh.md b/readme/README.zh.md index 0e161e2a..a7517f9e 100644 --- a/readme/README.zh.md +++ b/readme/README.zh.md @@ -98,6 +98,10 @@ iac-code web IaC Code Web 应用

+### Agent Skill + +将 IaC Code 添加到兼容的 Agent，即可在对话中规划云架构、处理 ROS 或 Terraform 模板、估算费用、操作资源栈并部署阿里云资源。下载[最新稳定版 Skill](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/iac-code-skill.zip)，或通过 [IaC Code 官方 Skills 概览](https://aliyun.github.io/iac-code/zh-Hans/docs/a2a/skill-overview)对比不同发行版。 + ## 贡献 安装 [uv](https://docs.astral.sh/uv/getting-started/installation/)，然后： diff --git a/tests/test_website_skill_docs.py b/tests/test_website_skill_docs.py index a1de8545..cb4475b4 100644 --- a/tests/test_website_skill_docs.py +++ b/tests/test_website_skill_docs.py @@ -19,19 +19,54 @@ def test_website_documents_external_skill_integration_in_all_locales() -> None: missing: list[str] = [] checks = { + "a2a/skill-overview.md": [ + "iac-code-skill.zip", + "alibabacloud-iac-code", + "alibabacloud-ros-agent", + "npx skills add", + "https://skills.aliyun.com/", + "/api/public/skills/alibabacloud-iac-code/download", + "/api/public/skills/alibabacloud-ros-agent/download", + "ros:StartChat", + "ros:StopChat", + "~/.iac-code/", + "skill-integration.md", + "skill-host-integration.md", + ], "a2a/skill-integration.md": [ "ensure-runtime", "cache clean", "llm_not_configured", "cloud_credentials_not_configured", + "ask_user_question", + "candidate_selection", + "deployment_confirmation", + "incompatible_host", + "Pipeline", + "iac-code-skill.zip", + "~/.agents/skills/iac-code/", + "~/.claude/skills/iac-code/", + "/iac-code", + ".iac-code-skill-results/", + "127.0.0.1", + "skill-host-integration.md", + ], + "a2a/skill-host-integration.md": [ + "config.json", + "preferredLanguage", "boundaryReached", + "presentationRequired", "inputRequired", + "turn_completed", "ask_user_question", "candidate_selection", + "deployment_confirmation", "allow_once", + "continue --job-id", + "poll --job-id", + "incompatible_host", "skill-package-contract.json", "skill-runtime///", - ".iac-code-skill-results/", "127.0.0.1", ], "a2a/protocol-reference.md": [ @@ -44,7 +79,9 @@ def test_website_documents_external_skill_integration_in_all_locales() -> None: "schemaVersion", ], "a2a/overview.md": [ + "skill-overview.md", "skill-integration.md", + "skill-host-integration.md", "preferredLanguage", "allow_once", ], @@ -71,7 +108,16 @@ def test_website_documents_external_skill_integration_in_all_locales() -> None: def test_skill_integration_registered_in_sidebar() -> None: sidebars = (WEBSITE_ROOT / "sidebars.ts").read_text(encoding="utf-8") + assert "label: 'IaC Code Skill'" in sidebars, "IaC Code Skill category is not registered in sidebars.ts" + assert "'a2a/skill-overview'" in sidebars, "a2a/skill-overview is not registered in sidebars.ts" assert "'a2a/skill-integration'" in sidebars, "a2a/skill-integration is not registered in sidebars.ts" + assert "'a2a/skill-host-integration'" in sidebars, "a2a/skill-host-integration is not registered in sidebars.ts" + assert (WEBSITE_ROOT / "docs" / "a2a" / "skill-overview.md").exists(), ( + "English source document for a2a/skill-overview is missing" + ) assert (WEBSITE_ROOT / "docs" / "a2a" / "skill-integration.md").exists(), ( "English source document for a2a/skill-integration is missing" ) + assert (WEBSITE_ROOT / "docs" / "a2a" / "skill-host-integration.md").exists(), ( + "English source document for a2a/skill-host-integration is missing" + ) diff --git a/website/docs/a2a/overview.md b/website/docs/a2a/overview.md index 0ee660be..119b09a5 100644 --- a/website/docs/a2a/overview.md +++ b/website/docs/a2a/overview.md @@ -22,7 +22,7 @@ Use A2A when another agent, workflow engine, or service needs to call iac-code a - **Workflow automation** — Internal tools can submit IaC generation, review, or conversion tasks over HTTP. - **Service discovery** — Clients can fetch the Agent Card and choose capabilities such as IaC generation or template review. - **Streaming integrations** — A chatops or dashboard client can show model text, tool activity, usage metadata, and final task state as the turn runs. -- **External Skill integration** — External agents use the packaged iac-code Skill to drive a local authenticated A2A runtime through a standard-library-only bridge script, embedding iac-code as their Alibaba Cloud infrastructure capability. See [Skill integration](./skill-integration.md). +- **External Skill integration** — External agents use an official IaC Code Skill to add Alibaba Cloud infrastructure capabilities to their workflows. See [Official IaC Code Skills](./skill-overview.md) to choose a distribution, [Install and Use the IaC Code Skill](./skill-integration.md), or the [Host Integration Reference](./skill-host-integration.md). ## Interaction Modes Comparison diff --git a/website/docs/a2a/skill-host-integration.md b/website/docs/a2a/skill-host-integration.md new file mode 100644 index 00000000..d289ff1e --- /dev/null +++ b/website/docs/a2a/skill-host-integration.md @@ -0,0 +1,175 @@ +--- +sidebar_position: 3 +title: IaC Code Skill Host Integration Reference +description: Integrate the packaged IaC Code Skill bridge with a Skill-capable host agent. +--- + +# IaC Code Skill Host Integration Reference + +This document is for developers of agents and Skill distribution systems. It defines how a host invokes the packaged +bridge, presents IaC Code results, handles user interaction, and resumes an existing task. End users should read +[Install and Use the IaC Code Skill](./skill-integration.md). + +## Integration Model + +The Skill package contains `SKILL.md` and the standard-library-only `scripts/iac_code.py` bridge. The host invokes the +bridge; the bridge installs and starts the pinned, verified Runtime and communicates with it over an authenticated +local A2A connection. + +The host must: + +- use CPython 3.8–3.14 to run the bridge; +- treat stdout as the stable JSON result and stderr as diagnostics and bounded progress; +- preserve the current `jobId`, `contextId`, cursor, and input correlation fields; +- show every user-facing boundary before continuing; and +- fail closed on bridge errors instead of bypassing the bridge with direct cloud calls or another Runtime. + +## Optional Distribution Configuration + +A distributor can place `config.json` beside `SKILL.md`: + +```json +{ + "channel": "codex", + "pipelineName": "selling_solution_first", + "permissionWaitPolicy": { + "residentTimeoutSeconds": null, + "subPipelineTimeoutSeconds": null, + "timeoutGraceSeconds": 30 + } +} +``` + +- `channel` is the channel identifier; the bridge adds the `skill/` prefix. +- `pipelineName` applies only after Pipeline mode is selected. The default is `selling_solution_first`; `selling` is + available for distributors that explicitly require the legacy workflow. +- `permissionWaitPolicy` controls waits in the temporary A2A server owned by the Skill. `null` means unlimited for the + resident or Sub Pipeline timeout. + +The bridge rejects unknown fields and invalid values. This file is installation policy: do not derive it from a user +request, expose it in task output, or modify it during a task. + +## Start a Job + +Write the complete request to a UTF-8 file in the workspace, resolve the workspace to an absolute path, and run: + +```text +python3 scripts/iac_code.py start --mode normal --cwd --prompt-file --language --follow +``` + +Use `normal` by default. Select `pipeline` only for a requested solution-comparison flow that needs candidate +architectures, cost comparison, confirmation, and deployment. Set the language to `en`, `zh`, `es`, `fr`, `de`, `ja`, +`pt`, or `auto`. Keep the returned `preferredLanguage` for every later turn. + +`start` performs a non-secret readiness check. `llm_not_configured` stops before job creation. Pipeline mode also +requires cloud credentials and otherwise returns `cloud_credentials_not_configured`. Normal mode may proceed with a +warning when the task does not need cloud APIs. + +## Follow Progress and Completion + +`--follow` stops at the next presentation or interaction boundary, `turn_completed`, or terminal Pipeline state. When +a result has `boundaryReached: true`, show all strings in `userUpdates`, then immediately follow the same job using the +returned cursor: + +```text +python3 scripts/iac_code.py follow --job-id --cursor --wait-seconds 60 +``` + +Do not treat `boundaryReached` as completion. `presentationRequired` means that the current update must be made visible +before another bridge call. A normal-mode answer is authoritative only when `state` is `turn_completed`; use +`finalText` and `artifacts`. For a terminal Pipeline state, use `pipelineResult` and `artifacts` and report cleanup +failures instead of claiming success. + +If `follow` cannot be used during diagnosis or recovery, poll the same job: + +```text +python3 scripts/iac_code.py poll --job-id --cursor --wait-seconds 5 +``` + +When a result says `state: input-required` but does not contain `inputRequired`, report its latest text or error and +leave the job unchanged. Do not submit a duplicate response or create a replacement job. + +## Handle User Input + +Treat every `inputRequired` object as a hard interaction boundary. Present it through the host's native question or +approval UI, stop, and wait for an explicit answer. Never infer an answer from the original request or choose a +default. Preserve `kind`, `inputId`, `requestTaskId`, `contextId`, and `toolUseId` when present. + +| `kind` | What the host must present | Response | +|---|---|---| +| `permission` | Purpose, effect, target, read-only status, deployment summary, safe summary, and returned actions | `allow_once` or `deny` | +| `ask_user_question` | The prompt, options, and free-text prompt when allowed | Selected option or allowed free text | +| `candidate_selection` | Every summary, Mermaid architecture diagram, monthly total, and cost items | Candidate ID or index | +| `deployment_confirmation` | Solution, template URL, quote or quote failure, effective parameters, overrides, Preview status, and returned actions | `confirm`, `adjust`, `reselect`, or `cancel` | + +Write the correlated answer to a new UTF-8 JSON file and resume the same job: + +```text +python3 scripts/iac_code.py respond --job-id --input-file --follow +``` + +Example envelopes: + +```json +{"kind":"permission","requestTaskId":"","contextId":"","inputId":"","toolUseId":"","decision":"allow_once"} +``` + +```json +{"kind":"ask_user_question","requestTaskId":"","contextId":"","inputId":"","answer":""} +``` + +```json +{"kind":"candidate_selection","requestTaskId":"","contextId":"","inputId":"","answer":""} +``` + +```json +{"kind":"deployment_confirmation","requestTaskId":"","contextId":"","inputId":"","action":"","parameterOverrides":{"":""}} +``` + +Omit `parameterOverrides` when the user did not request an adjustment. A deployment request is not approval for a +later `deployment_confirmation`, and an outer host approval must not override a denial from IaC Code. + +## Continue a Conversation + +After a normal turn completes, or after a completed Pipeline hands the conversation to normal mode, write the next +message to a new prompt file and continue the existing job: + +```text +python3 scripts/iac_code.py continue --job-id --prompt-file --follow +``` + +Keep the same `jobId` and `contextId`; a new `taskId` for each normal turn is expected. Do not use `start` merely +because the previous turn completed. Keeping the job identity also allows the bridge to recover permission waits and +resume after a host interruption. + +To cancel the whole operation, run: + +```text +python3 scripts/iac_code.py cancel --job-id +``` + +Cancellation is different from denying one permission request. + +## Errors and Runtime Lifecycle + +Treat a pre-job bridge error as authoritative. In particular, `incompatible_host` includes available host and Runtime +compatibility facts; present them and stop. Do not fall back to pip installation, another Runtime artifact, or direct +cloud calls. + +The downloaded Runtime is cached under +`/skill-runtime///`. The package layout and integrity metadata +are defined by `skill-runtime/skill-package-contract.json` and the release manifest. The bridge verifies the package +before use. Runtime cache cleanup must be a separate, explicitly requested operation; current and active packages are +protected. + +The Runtime binds to a random `127.0.0.1` port and generates a process-specific Bearer token. Do not expose the token, +local state, credentials, environment values, or raw tool inputs and results. Bounded result projections and display +fields are the supported host interface. + +## Related Documentation + +- [Official IaC Code Skills](./skill-overview.md) +- [Install and Use the IaC Code Skill](./skill-integration.md) +- [A2A Protocol Overview](./overview.md) +- [A2A Protocol Reference](./protocol-reference.md) +- [Runtime Configuration](../configuration/runtime-configuration.md) diff --git a/website/docs/a2a/skill-integration.md b/website/docs/a2a/skill-integration.md index cae6a63e..1272ab90 100644 --- a/website/docs/a2a/skill-integration.md +++ b/website/docs/a2a/skill-integration.md @@ -1,69 +1,38 @@ --- -sidebar_position: 7 +sidebar_position: 2 title: Install and Use the IaC Code Skill -description: Download and install the IaC Code Skill so an external agent can manage Alibaba Cloud infrastructure. +description: Add IaC Code to a Skill-capable agent and use it to manage Alibaba Cloud infrastructure. --- # Install and Use the IaC Code Skill -The IaC Code Skill is designed for external agents that support Skills. Once installed, a host agent can delegate -cloud architecture planning, ROS or Terraform template generation and review, cost estimation, resource selection, -stack operations, and deployment to IaC Code. The Skill uses a Python standard-library bridge to start a locally -authenticated A2A Runtime. You do not need to install IaC Code with pip, and the host must not fall back to headless -commands. +The IaC Code Skill lets a compatible agent delegate Alibaba Cloud infrastructure work to IaC Code. You can use it to +plan cloud architectures, generate or review ROS and Terraform templates, estimate costs, select existing resources, +operate ROS stacks, and deploy resources. The package includes its own verified IaC Code Runtime, so you do not need +to install IaC Code separately. -## Download the Skill +## Download -### Latest stable release +[Download the latest iac-code-skill.zip](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/iac-code-skill.zip) -Download the latest stable release directly: +This fixed URL always points to the latest stable Skill package. Automated installers can read +[latest.json](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/latest.json) +to obtain the current version, immutable download URL, file size, and SHA-256 digest. For reproducible installation, +download `skill.url` from that file and verify `skill.sha256`. -[Download iac-code-skill.zip](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/iac-code-skill.zip) +## Install -This fixed URL always points to the Skill package promoted to the stable channel. It is suitable for browser downloads -and manual installation, and it does not change when a new version is released. +Before installing, make sure that: -Installers that need the version, file size, SHA-256 digest, and immutable version URL can read the stable channel -metadata: +- Your agent supports local Skills defined by `SKILL.md`. +- CPython 3.8–3.14 is available. Use `python3` on macOS or Linux and `py -3` on Windows. +- The environment can access the download URL on first use. -[View latest.json](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/latest.json) +Official Runtime packages support macOS on Apple Silicon, Linux x86_64, and Windows x86_64. The Runtime checks the +operating-system and ABI requirements before it is downloaded. -The document contains: - -- `skillVersion`: the current stable Skill version. -- `skill.url`: the immutable ZIP URL for that version. -- `skill.sha256` and `skill.size`: values used to verify the download. -- `manifest.url`: the immutable release manifest for that version. - -For strict verification or reproducible automated installation, read `latest.json`, download `skill.url`, and verify -`skill.sha256`. Do not construct a version URL yourself. - -## Install the Skill - -### Prerequisites - -- The host agent supports local Skills defined by `SKILL.md`. -- CPython 3.8–3.14 is installed. Use `python3` on macOS/Linux and prefer `py -3` on Windows. -- The environment can access the OSS URLs above to download the Skill ZIP and the Runtime required on first use. -- Model service configuration is available. A least-privilege Alibaba Cloud identity is also required for tasks that - query or manage cloud resources. - -Official Skill Runtime releases support these platforms: - -| Operating system | Architecture | -|---|---| -| macOS | Apple Silicon (arm64) | -| Linux | x86_64 | -| Windows | x86_64 | - -The minimum operating-system and Linux glibc versions are defined by the Runtime manifest pinned by the Skill. The -bridge checks compatibility before downloading. On an unsupported platform, it returns an error instead of -downloading an artifact for another platform or ABI. - -### Extract into the host agent's Skill directory - -Extract the ZIP directly into the host agent's Skill root. The exact Skill root varies by product; follow the host -product's documentation. The final layout must be: +Extract the ZIP into the Skill directory documented by your agent. The archive already contains the top-level +`iac-code/` directory, so the final layout must be: ```text / @@ -75,137 +44,138 @@ product's documentation. The final layout must be: └── iac_code.py ``` -The ZIP already contains the top-level `iac-code/` directory. Do not add another directory with the same name. After -installing or updating, restart the host agent or open a new session so that it discovers the Skill again. +Common host locations: -### Verify the installation +- **Codex**: extract to `~/.agents/skills/iac-code/` for all projects, or + `/.agents/skills/iac-code/` for one repository. See the + [Codex Skills documentation](https://developers.openai.com/codex/skills#where-codex-loads-local-skills). +- **Claude Code**: extract to `~/.claude/skills/iac-code/` for all projects, or + `/.claude/skills/iac-code/` for one repository. See the + [Claude Code Skills documentation](https://code.claude.com/docs/en/skills#where-skills-live). -In the extracted `iac-code` directory, run this command on macOS or Linux: +Restart the agent or open a new session after installation. To verify the Runtime in advance, run the following +command from the extracted `iac-code` directory. + +macOS or Linux: ```bash python3 scripts/iac_code.py ensure-runtime ``` -In Windows PowerShell, run: +Windows PowerShell: ```powershell py -3 scripts\iac_code.py ensure-runtime ``` -On first use, the command downloads the Runtime for the current platform, verifies its size and SHA-256 digest, and -prints JSON containing `skillVersion`, `runtimeTag`, and the installation path. A verified cached Runtime is reused -without another download. +On first use, the bridge downloads the Runtime for the current platform and verifies its size and SHA-256 digest. +Later tasks reuse the verified local copy. ## Configure the Model and Alibaba Cloud Identity -The Skill Runtime uses the same configuration directory as other IaC Code modes: `~/.iac-code/` by default. If you -already configured IaC Code through the REPL, Web app, or Desktop app, the Skill can reuse those settings. Set -`IAC_CODE_CONFIG_DIR` to use a different configuration directory. +The Skill uses the standard IaC Code configuration directory, `~/.iac-code/` by default. If you already configured +IaC Code in the REPL, Web app, or Desktop app, the Skill reuses those settings. You can set `IAC_CODE_CONFIG_DIR` to +select another configuration directory. + +For automated environments, inject model settings and Alibaba Cloud credentials through a secret-management +solution. Do not place credentials in `SKILL.md`, prompts, project files, or shell history. Prefer temporary +credentials, RAM roles, or OAuth and grant only the permissions needed by the task. + +See [LLM Providers](../configuration/llm-providers.md) and +[Alibaba Cloud Credentials](../configuration/alibaba-cloud-credentials.md) for configuration options and supported +environment variables. -In automated environments, provide these variables through a secret-management solution: +## Choose How to Work -| Category | Environment variable | Description | -|---|---|---| -| Model | `IAC_CODE_PROVIDER` | Model provider | -| Model | `IAC_CODE_MODEL` | Model name | -| Model | `IAC_CODE_API_KEY` | Model service API key | -| Model | `IAC_CODE_BASE_URL` | Optional compatible endpoint override | -| Alibaba Cloud | `ALIBABA_CLOUD_ACCESS_KEY_ID` | AccessKey ID | -| Alibaba Cloud | `ALIBABA_CLOUD_ACCESS_KEY_SECRET` | AccessKey secret | -| Alibaba Cloud | `ALIBABA_CLOUD_SECURITY_TOKEN` | Security token for STS credentials | -| Alibaba Cloud | `ALIBABA_CLOUD_REGION_ID` | Default region | +The Skill chooses between two modes according to the request: -Never put real credentials in `SKILL.md`, host-agent prompts, project files, or shell history. Prefer temporary -credentials, RAM roles, or OAuth, and grant only the cloud API permissions required by the task. See -[LLM Providers](../configuration/llm-providers.md) and -[Alibaba Cloud Credentials](../configuration/alibaba-cloud-credentials.md) for complete instructions. +- **Normal mode** is the default for resource queries and changes, template work, troubleshooting, and deployment of + a clear target. +- **Pipeline mode** is used when you explicitly request it or need candidate architectures, cost comparison, plan + confirmation, and deployment as one guided process. + +You normally do not need to select a mode yourself. Describe the outcome you want, and mention Pipeline mode only +when you want the solution-comparison workflow. ## First Use -After installation and configuration, open a new session in the host agent and describe an Alibaba Cloud -infrastructure task directly. For example: +Open a new session in the host agent and describe an Alibaba Cloud infrastructure task. For example: ```text Use iac-code to review the ROS template in this project. List security risks and recommended changes without modifying the file. ``` -Hosts that support explicit Skill syntax can use `$iac-code` to select the Skill. The host reads `SKILL.md`, writes the -complete request to a UTF-8 file inside the workspace, and uses the bridge to create and follow one task. The user does -not need to start an A2A Server manually. - -Expected flow: +Use `$iac-code` to select the Skill explicitly in Codex, or `/iac-code` in Claude Code. On the first request, the agent verifies the model +and cloud configuration, prepares the Runtime, and starts the task. You do not need to start an A2A server manually. -1. The bridge checks whether model and Alibaba Cloud configuration is ready. -2. On first use, it downloads and verifies the IaC Code Runtime pinned by the Skill. -3. The Runtime listens only on a random `127.0.0.1` port and generates a process-specific Bearer token. -4. The host agent presents progress, questions, candidate plans, and permission requests returned by IaC Code. -5. When the task completes, the host agent returns the final result and files generated in the workspace. +IaC Code may pause and ask you to: -## Update and Uninstall - -For a manual update, download `skill/stable/iac-code-skill.zip` again and replace the complete `iac-code/` directory in -the host's Skill root. An automatic updater can compare `skillVersion` from `latest.json`, then download and verify the -new package using its immutable URL and SHA-256 digest. Each official Skill is pinned to a verified Runtime. Do not -replace only `scripts/iac_code.py` or edit its Runtime URL or digest manually. +- approve or deny a tool or deployment operation (`permission`); +- answer a question (`ask_user_question`); +- choose a proposed architecture (`candidate_selection`); or +- review the final solution, price, and deployment parameters, then confirm, adjust, reselect, or cancel + (`deployment_confirmation`). -To uninstall, remove `iac-code/` from the host agent's Skill root. The Runtime cache is not removed with the Skill -directory. Run `cache list` and `cache clean` only when the user explicitly asks to remove it. +Always review the target resources, region, impact, and quoted price before answering. A deployment request does not +pre-approve the later deployment confirmation. After a task finishes, you can continue with a follow-up request in +the same agent session; the Skill keeps the IaC Code conversation context. -## Runtime Cache +IaC Code can return progress and questions in English, Simplified Chinese, Spanish, French, German, Japanese, or +Portuguese according to the conversation language. -The Runtime downloaded on first use is cached under -`/skill-runtime///` and reused automatically. Normal use does -not require managing this directory. To inspect disk usage or remove historical versions, use: +## Update and Uninstall -- `python3 scripts/iac_code.py cache list` — list installed Runtimes and candidate packages. -- `python3 scripts/iac_code.py cache clean [--runtime-tag ] [--candidates] --confirm` — remove Runtime caches or - candidate packages; `--confirm` is required. +To update manually, download the stable ZIP again and replace the complete `iac-code/` directory. Restart the host +agent or open a new session so it reloads the Skill. Do not replace only the bridge script or edit its Runtime URL and +digest. -The current Runtime and any Runtime used by a live process are protected from cleanup. The package format and Runtime -constraints are defined by `skill-runtime/skill-package-contract.json` in the source repository; users do not need to -modify this file. +To uninstall, remove `iac-code/` from the host agent's Skill directory. Downloaded Runtime packages remain in the IaC +Code configuration directory so other installations and active tasks are not disrupted. If you also want to remove +those packages, first run `cache list`, review the result, and then run `cache clean ... --confirm`. ## Troubleshooting ### Configuration is incomplete -The Skill checks configuration before creating a task but never reads or returns secret values: +If the model provider or API key is incomplete, the Skill returns `llm_not_configured` before starting a task. Both +Pipeline workflows require Alibaba Cloud credentials and return `cloud_credentials_not_configured` when they are +missing. Normal mode can still perform work that does not call cloud APIs and reports a warning when cloud operations +are unavailable. + +### The Runtime cannot start + +Run `ensure-runtime` and check the returned error. Confirm the host Python version, operating system, architecture, +network access, and proxy settings. An `incompatible_host` result means the machine does not meet the Runtime +requirements; update or move to a supported host instead of installing an unrelated package or Runtime. -| Situation | Result | -|---|---| -| LLM provider or API key is incomplete | Returns `llm_not_configured` and does not create the task | -| Alibaba Cloud credentials are incomplete for the selling Pipeline | Returns `cloud_credentials_not_configured` and does not create the task | -| Alibaba Cloud credentials are incomplete in normal mode | Tasks that do not call cloud APIs may continue with a preflight warning | +### The task pauses or was interrupted -### Why execution pauses +A pause usually means IaC Code is waiting for a question, permission, candidate selection, or deployment confirmation; +it is not a failure. Answer the request shown by the agent. If the host session is still available after an +interruption, ask it to continue the same task so it can recover the existing job instead of starting over. -IaC Code pauses when it needs permission, additional information, or a plan selection. The host agent presents the -request directly: +### Manage Runtime disk usage -- A tool or deployment permission request (`permission`). -- A multiple-choice question or request for more information (`ask_user_question`). -- A Pipeline candidate plan selection (`candidate_selection`). +From the installed Skill directory, use: -Before confirming, review the target resource, region, expected impact, and price. The host agent cannot override a -denial from IaC Code. A one-time approval is represented as `allow_once` in the protocol. +- `python3 scripts/iac_code.py cache list` to inspect installed Runtime packages; +- `python3 scripts/iac_code.py cache clean --runtime-tag --confirm` to remove one historical Runtime; or +- `python3 scripts/iac_code.py cache clean --candidates --confirm` to remove candidate packages. -> **Host agent integration note** -> -> When a bridge result contains `inputRequired`, the host agent must present the current request and wait for a -> response. `boundaryReached` marks a presentation or interaction boundary, not task completion; the host must show -> the update and continue following the same task. +The current Runtime and packages used by a live process are protected from cleanup. On Windows, replace `python3` +with `py -3`. ## Security -- The Runtime listens only on a random `127.0.0.1` port. Every start generates a new Bearer token, and every bridge - request carries that token. -- The bridge keeps artifacts and results in the job workspace. Results are written to `.iac-code-skill-results/`. -- Preflight and permission display fields are sanitized; secrets and credentials do not appear in display fields. +- The Runtime listens only on a random `127.0.0.1` port and uses a new Bearer token for each process. +- Task artifacts and result files stay in the selected workspace, under `.iac-code-skill-results/` when applicable. +- Readiness and permission summaries are sanitized and do not include credential values. ## Related Documentation +- [Official IaC Code Skills](./skill-overview.md) +- [IaC Code Skill Host Integration Reference](./skill-host-integration.md) - [A2A Protocol Overview](./overview.md) -- [A2A Protocol Reference](./protocol-reference.md) - [LLM Providers](../configuration/llm-providers.md) - [Alibaba Cloud Credentials](../configuration/alibaba-cloud-credentials.md) - [Runtime Configuration](../configuration/runtime-configuration.md) diff --git a/website/docs/a2a/skill-overview.md b/website/docs/a2a/skill-overview.md new file mode 100644 index 00000000..7846269c --- /dev/null +++ b/website/docs/a2a/skill-overview.md @@ -0,0 +1,76 @@ +--- +sidebar_position: 1 +title: Official IaC Code Skills +description: Compare the official IaC Code Skills and choose the right installation for your workflow. +--- + +# Official IaC Code Skills + +IaC Code is available as three official Skill distributions. They share the goal of managing Alibaba Cloud +infrastructure through an agent conversation, but differ in distribution channel and where the IaC Code agent runs. + +## Choose a Skill + +| Skill | Where it runs | Choose it when | +|---|---|---| +| `iac-code` | A verified IaC Code Runtime downloaded to your machine | You want the standalone package published with the iac-code project and direct control over installation and updates. | +| `alibabacloud-iac-code` | The same local, verified IaC Code Runtime, packaged for the Alibaba Cloud Agent Skills Portal | You install and update Alibaba Cloud Skills through the portal or the `npx skills` workflow. | +| `alibabacloud-ros-agent` | The hosted Alibaba Cloud ROS Agent, called through the ROS StartChat API | You want a remote ROS Agent conversation without downloading the local IaC Code Runtime. | + +`iac-code` and `alibabacloud-iac-code` provide the same runtime-backed IaC Code capability. Select one distribution +for a given agent scope; installing both adds overlapping routing without adding functionality. + +`alibabacloud-ros-agent` is a separate remote-service integration. It can coexist with one local Runtime distribution +when users need to choose explicitly between local IaC Code and the hosted ROS Agent. + +## Get the Standalone Skill + +Download the fixed stable package: + +[Download iac-code-skill.zip](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/iac-code-skill.zip) + +This distribution is best when you want to install the Skill directory yourself. It downloads the Runtime on first use +and reuses the model and Alibaba Cloud configuration under `~/.iac-code/`. See +[Install and Use the IaC Code Skill](./skill-integration.md) for supported hosts and configuration. + +## Get the Alibaba Cloud Portal Skills + +Find the Skills by their exact names in the +[Alibaba Cloud Agent Skills Portal](https://skills.aliyun.com/), or install them from the official repository: + +```bash +npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-iac-code +npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-ros-agent +``` + +You can also download the packages directly: + +- [`alibabacloud-iac-code` ZIP](https://skills.aliyun.com/api/public/skills/alibabacloud-iac-code/download) · + [source](https://github.com/aliyun/alibabacloud-aiops-skills/tree/master/skills/developertools/ros/alibabacloud-iac-code) +- [`alibabacloud-ros-agent` ZIP](https://skills.aliyun.com/api/public/skills/alibabacloud-ros-agent/download) · + [source](https://github.com/aliyun/alibabacloud-aiops-skills/tree/master/skills/developertools/ros/alibabacloud-ros-agent) + +The `npx skills` installer can select a supported agent and installation scope interactively. Node.js 18 or later is +required for this installation method. If you download a ZIP, extract its top-level Skill directory into the user- or +project-level Skill directory supported by your agent and restart the agent when necessary. + +## Capability and Configuration Differences + +Both local Runtime distributions support normal conversations and Pipeline workflows, including architecture planning, +ROS and Terraform template work, cost estimation, stack operations, deployment, questions, candidate selection, and +permission or deployment confirmation. They require a configured model; Alibaba Cloud credentials are required when a +task reads or changes cloud resources. + +The hosted `alibabacloud-ros-agent` sends conversations to the Alibaba Cloud ROS Agent through `ros:StartChat`. It uses +the Alibaba Cloud identity available to the host and does not require the local IaC Code Runtime or a locally configured +model provider. Grant only the required RAM permissions. Explicit remote cancellation additionally uses `ros:StopChat`. + +Regardless of distribution, review the target resources, region, impact, price, and requested permissions before +approving a change or deployment. Do not place credentials in `SKILL.md`, prompts, or project files. + +## Related Documentation + +- [Install and Use the IaC Code Skill](./skill-integration.md) +- [IaC Code Skill Host Integration Reference](./skill-host-integration.md) +- [Alibaba Cloud Credentials](../configuration/alibaba-cloud-credentials.md) +- [A2A Protocol Overview](./overview.md) diff --git a/website/docs/intro.md b/website/docs/intro.md index a0750888..d06c8917 100644 --- a/website/docs/intro.md +++ b/website/docs/intro.md @@ -6,7 +6,7 @@ description: What IaC Code does and where to start. # Overview -IaC Code is an AI-powered Infrastructure as Code assistant for cloud infrastructure. It helps cloud resource users and operators generate, deploy, and manage infrastructure templates through a terminal workflow. The architecture is designed for multi-cloud workflows; the current release supports Alibaba Cloud ROS and Terraform workflows. +IaC Code is an AI-powered assistant for planning, generating, deploying, and managing cloud infrastructure. You can use it from the Desktop app, local Web app, interactive terminal, automation interfaces, or as a Skill in another agent. The architecture is designed for multi-cloud workflows; the current release supports Alibaba Cloud ROS and Terraform workflows. Core capabilities: @@ -14,4 +14,11 @@ Core capabilities: - **One command to production** — for Alibaba Cloud ROS, go from template to running infrastructure in one flow: create, update, delete, and monitor stacks across regions. Terraform support covers template generation and conversion, not deployment. - **Cloud smarts built in** — search documentation, check resource availability, and estimate costs before you deploy; every decision backed by real cloud data. -The documentation is organized around user tasks. Start with installation and quick start, then configure providers and credentials, then use the CLI reference when you need command details. +Choose the entry point that matches your workflow: + +- Download the [Desktop app](./desktop-app.md) for a ready-to-use graphical application. +- Follow [Installation](./getting-started/installation.md) and [Quick Start](./getting-started/quick-start.md) to use the REPL, headless mode, or local [Web app](./web-app.md). +- Choose an option in [Official IaC Code Skills](./a2a/skill-overview.md) to give a compatible agent IaC Code's Alibaba Cloud infrastructure capabilities. +- Use [ACP](./acp/overview.md), [A2A](./a2a/overview.md), or [AG-UI](./agui/overview.md) when integrating IaC Code into another application or service. + +Model configuration is required for every entry point. Configure [Alibaba Cloud credentials](./configuration/alibaba-cloud-credentials.md) when a task needs to query, change, or deploy cloud resources. diff --git a/website/i18n/de/docusaurus-plugin-content-docs/current.json b/website/i18n/de/docusaurus-plugin-content-docs/current.json index ff71397b..727c3d3a 100644 --- a/website/i18n/de/docusaurus-plugin-content-docs/current.json +++ b/website/i18n/de/docusaurus-plugin-content-docs/current.json @@ -11,6 +11,10 @@ "message": "IaC Code verwenden", "description": "The label for category 'Using iac-code' in sidebar 'docsSidebar'" }, + "sidebar.docsSidebar.category.IaC Code Skill": { + "message": "IaC Code Skill", + "description": "The label for category 'IaC Code Skill' in sidebar 'docsSidebar'" + }, "sidebar.docsSidebar.category.MCP Integration": { "message": "MCP-Integration", "description": "The label for category 'MCP Integration' in sidebar 'docsSidebar'" diff --git a/website/i18n/de/docusaurus-plugin-content-docs/current/a2a/overview.md b/website/i18n/de/docusaurus-plugin-content-docs/current/a2a/overview.md index f4e24dd4..b78574ba 100644 --- a/website/i18n/de/docusaurus-plugin-content-docs/current/a2a/overview.md +++ b/website/i18n/de/docusaurus-plugin-content-docs/current/a2a/overview.md @@ -22,7 +22,7 @@ Verwenden Sie A2A, wenn ein anderer Agent, eine Workflow-Engine oder ein Service - **Workflow-Automatisierung** - Interne Tools koennen IaC-Generierungs-, Review- oder Konvertierungs-Tasks ueber HTTP einreichen. - **Service Discovery** - Clients koennen die Agent Card abrufen und Faehigkeiten wie IaC-Generierung oder Template-Review auswaehlen. - **Streaming-Integrationen** - Ein ChatOps- oder Dashboard-Client kann Modelltext, Tool-Aktivitaet, Nutzungsmetadaten und den finalen Task-Zustand anzeigen, waehrend der Turn laeuft. -- **Externe Skill-Integration** - Externe Agenten nutzen das paketiere iac-code-Skill, um eine lokale authentifizierte A2A-Runtime ueber ein Bridge-Skript mit reiner Standardbibliothek anzusteuern, und betten iac-code als Alibaba-Cloud-Infrastrukturfaehigkeit ein. Siehe [Skill-Integration](./skill-integration.md). +- **Externe Skill-Integration** - Externe Agents koennen mit einem offiziellen IaC Code Skill Alibaba-Cloud-Infrastrukturfaehigkeiten in ihre Workflows einbinden. Waehlen Sie unter [Offizielle IaC Code Skills](./skill-overview.md) eine Distribution aus und lesen Sie anschliessend [Skill installieren und verwenden](./skill-integration.md) oder die [Host-Integrationsreferenz](./skill-host-integration.md). ## Vergleich der Interaktionsmodi diff --git a/website/i18n/de/docusaurus-plugin-content-docs/current/a2a/skill-host-integration.md b/website/i18n/de/docusaurus-plugin-content-docs/current/a2a/skill-host-integration.md new file mode 100644 index 00000000..9f5df8cb --- /dev/null +++ b/website/i18n/de/docusaurus-plugin-content-docs/current/a2a/skill-host-integration.md @@ -0,0 +1,139 @@ +--- +sidebar_position: 3 +title: Referenz zur Host-Integration des IaC Code Skills +description: Integrieren Sie die IaC-Code-Skill-Bridge in einen Skill-faehigen Host-Agenten. +--- + +# Referenz zur Host-Integration des IaC Code Skills + +Diese Referenz richtet sich an Entwickler von Agenten und Skill-Verteilungssystemen. Endbenutzer lesen +[IaC Code Skill installieren und verwenden](./skill-integration.md). + +## Integrationsmodell und Konfiguration + +Das Paket enthaelt `SKILL.md` und die nur auf der Standardbibliothek basierende Bridge `scripts/iac_code.py`. Fuehren Sie +sie mit CPython 3.8 bis 3.14 aus. stdout ist das stabile JSON-Ergebnis, stderr enthaelt Diagnose und Fortschritt. Bewahren +Sie `jobId`, `contextId`, cursor und Korrelationsfelder auf. Bei Fehlern darf nicht auf eine andere Runtime oder direkte +Cloud-API-Aufrufe ausgewichen werden. + +Ein Verteiler kann neben `SKILL.md` diese `config.json` ablegen: + +```json +{ + "channel": "codex", + "pipelineName": "selling_solution_first", + "permissionWaitPolicy": { + "residentTimeoutSeconds": null, + "subPipelineTimeoutSeconds": null, + "timeoutGraceSeconds": 30 + } +} +``` + +Die Bridge setzt `skill/` vor `channel`. Standard fuer `pipelineName` ist `selling_solution_first`; `selling` dient nur +einem explizit benoetigten Legacy-Ablauf. `null` bedeutet unbegrenztes Warten. Unbekannte oder ungueltige Werte werden +abgewiesen. Diese Installationsrichtlinie darf nicht aus Benutzerwuenschen abgeleitet, ausgegeben oder waehrend einer +Aufgabe veraendert werden. + +## Job starten und verfolgen + +Schreiben Sie die vollstaendige Anfrage in eine UTF-8-Datei im Workspace und verwenden Sie einen absoluten Pfad: + +```text +python3 scripts/iac_code.py start --mode normal --cwd --prompt-file --language --follow +``` + +Verwenden Sie standardmaessig `normal`, `pipeline` nur fuer Vergleich, Bestaetigung und Bereitstellung. Moegliche +Sprachen sind `en`, `zh`, `es`, `fr`, `de`, `ja`, `pt` und `auto`; behalten Sie danach `preferredLanguage` bei. +`llm_not_configured` stoppt vor der Job-Erstellung, `cloud_credentials_not_configured` meldet fehlende Zugangsdaten in +Pipeline. + +`--follow` kehrt an der naechsten Darstellungs- oder Interaktionsgrenze, bei `turn_completed` oder einem terminalen +Pipeline-Status zurueck. Bei `boundaryReached: true` zeigen Sie alle `userUpdates` und folgen demselben Job: + +```text +python3 scripts/iac_code.py follow --job-id --cursor --wait-seconds 60 +``` + +`boundaryReached` ist kein Abschluss. `presentationRequired` verlangt eine sichtbare Ausgabe vor dem naechsten Aufruf. +Im Normalmodus sind `finalText` und `artifacts` bei `turn_completed` massgeblich; bei einer terminalen Pipeline +`pipelineResult` und `artifacts`. Melden Sie Fehler der Bereinigung. Nur fuer Diagnose oder Wiederaufnahme: + +```text +python3 scripts/iac_code.py poll --job-id --cursor --wait-seconds 5 +``` + +Bei `state: input-required` ohne `inputRequired` melden Sie den letzten Text oder Fehler und lassen den Job unveraendert. + +## Benutzereingaben behandeln + +Jedes `inputRequired` ist eine harte Interaktionsgrenze. Zeigen Sie es in der nativen Host-Oberflaeche und warten Sie +auf eine ausdrueckliche Antwort. Leiten Sie keine Standardantwort ab. Bewahren Sie `kind`, `inputId`, `requestTaskId`, +`contextId` und gegebenenfalls `toolUseId` auf. + +| `kind` | Anzuzeigende Informationen | Antwort | +|---|---|---| +| `permission` | Zweck, Wirkung, Ziel, Nur-Lesen, Bereitstellungs- und Sicherheitszusammenfassung, Aktionen | `allow_once` / `deny` | +| `ask_user_question` | Frage, Optionen und erlaubter Freitext | Antwort | +| `candidate_selection` | Alle Zusammenfassungen, Mermaid-Diagramme, Monatssumme und Positionen | ID oder Nummer | +| `deployment_confirmation` | Loesung, URL, Preis, effektive Werte, Ueberschreibungen, Preview, Aktionen | `confirm` / `adjust` / `reselect` / `cancel` | + +Schreiben Sie die korrelierte Antwort in eine neue UTF-8-JSON-Datei und setzen Sie denselben Job fort: + +```text +python3 scripts/iac_code.py respond --job-id --input-file --follow +``` + +```json +{"kind":"permission","requestTaskId":"","contextId":"","inputId":"","toolUseId":"","decision":"allow_once"} +``` + +```json +{"kind":"ask_user_question","requestTaskId":"","contextId":"","inputId":"","answer":""} +``` + +```json +{"kind":"candidate_selection","requestTaskId":"","contextId":"","inputId":"","answer":""} +``` + +```json +{"kind":"deployment_confirmation","requestTaskId":"","contextId":"","inputId":"","action":"","parameterOverrides":{"":""}} +``` + +Lassen Sie `parameterOverrides` ohne Anpassung weg. Leiten Sie die Bestaetigung nicht aus dem urspruenglichen Wunsch +oder einer Host-Freigabe ab. + +## Fortsetzen, abbrechen und wiederaufnehmen + +Nach einem normalen Turn oder dem Wechsel einer abgeschlossenen Pipeline in den Normalmodus setzen Sie den Job fort: + +```text +python3 scripts/iac_code.py continue --job-id --prompt-file --follow +``` + +Behalten Sie `jobId` und `contextId`; eine neue `taskId` ist normal. So koennen auch Freigabewartezeiten und +Host-Unterbrechungen wiederaufgenommen werden. Vollstaendiger Abbruch: + +```text +python3 scripts/iac_code.py cancel --job-id +``` + +Dies unterscheidet sich von der Ablehnung einer einzelnen Freigabe. + +## Fehler und Runtime + +Ein Fehler vor Job-Erstellung ist fuer den Aufruf massgeblich. Zeigen Sie bei `incompatible_host` die +Kompatibilitaetsdaten und stoppen Sie, ohne pip, eine andere Runtime oder direkte APIs zu verwenden. Die Runtime liegt +unter `/skill-runtime///`. Aufbau und Integritaet werden durch +`skill-runtime/skill-package-contract.json` und das Release-Manifest festgelegt. Bereinigung erfolgt nur auf +ausdruecklichen Wunsch; aktuelle und aktive Pakete sind geschuetzt. + +Die Runtime verwendet einen zufaelligen `127.0.0.1`-Port und einen prozessspezifischen Bearer token. Legen Sie token, +lokalen Zustand, Zugangsdaten, Umgebungswerte und rohe Tool-Ein-/Ausgaben nicht offen. + +## Weitere Dokumentation + +- [Ueberblick ueber offizielle IaC Code Skills](./skill-overview.md) +- [IaC Code Skill installieren und verwenden](./skill-integration.md) +- [A2A-Uebersicht](./overview.md) +- [A2A-Referenz](./protocol-reference.md) diff --git a/website/i18n/de/docusaurus-plugin-content-docs/current/a2a/skill-integration.md b/website/i18n/de/docusaurus-plugin-content-docs/current/a2a/skill-integration.md index 16c84c1d..79fa42d0 100644 --- a/website/i18n/de/docusaurus-plugin-content-docs/current/a2a/skill-integration.md +++ b/website/i18n/de/docusaurus-plugin-content-docs/current/a2a/skill-integration.md @@ -1,225 +1,130 @@ --- -sidebar_position: 7 +sidebar_position: 2 title: IaC Code Skill installieren und verwenden -description: Laden Sie den IaC Code Skill herunter und installieren Sie ihn, damit ein externer Agent Alibaba-Cloud-Ressourcen verwalten kann. +description: Fuegen Sie IaC Code einem Skill-faehigen Agenten hinzu und verwalten Sie Alibaba-Cloud-Infrastruktur. --- # IaC Code Skill installieren und verwenden -Der IaC Code Skill richtet sich an externe Agenten, die Skills unterstützen. Nach der Installation kann ein -Host-Agent die Planung von Cloud-Architekturen, das Erstellen und Prüfen von ROS- oder Terraform-Vorlagen, -Kostenschätzungen, die Ressourcenauswahl, Stack-Operationen und Bereitstellungen an IaC Code delegieren. Der Skill -verwendet eine ausschließlich mit der Python-Standardbibliothek erstellte Bridge, um eine lokale, authentifizierte -A2A-Runtime zu starten. IaC Code muss nicht mit pip installiert werden, und der Host darf nicht auf Headless-Befehle -ausweichen. +Mit dem IaC Code Skill kann ein kompatibler Agent Aufgaben an IaC Code delegieren: Cloud-Architekturen planen, +ROS- oder Terraform-Vorlagen erstellen und pruefen, Kosten schaetzen, vorhandene Ressourcen auswaehlen, ROS-Stacks +verwalten und Ressourcen bereitstellen. Das Paket enthaelt eine gepruefte IaC Code Runtime; eine separate +IaC-Code-Installation ist nicht erforderlich. -## Skill herunterladen +## Download -### Neueste stabile Version +[Aktuelle stabile iac-code-skill.zip herunterladen](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/iac-code-skill.zip) -Laden Sie die neueste stabile Version direkt herunter: +Diese feste URL verweist immer auf die aktuelle stabile Version. Automatische Installer koennen +[latest.json](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/latest.json) +lesen, um Version, unveraenderliche URL, Groesse und SHA-256 zu erhalten und `skill.url` gegen `skill.sha256` zu pruefen. -[iac-code-skill.zip herunterladen](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/iac-code-skill.zip) +## Installation -Diese feste URL verweist immer auf das Skill-Paket, das für den stabilen Kanal freigegeben wurde. Sie eignet sich für -Downloads im Browser und für die manuelle Installation und ändert sich bei einer neuen Version nicht. +Der Agent muss lokale, mit `SKILL.md` definierte Skills unterstuetzen. Benoetigt werden CPython 3.8 bis 3.14 und beim +ersten Einsatz Netzwerkzugriff auf die Downloadadresse. Verwenden Sie unter macOS/Linux `python3`, unter Windows +`py -3`. Offizielle Runtimes gibt es fuer macOS auf Apple Silicon, Linux x86_64 und Windows x86_64. System und ABI +werden vor dem Download geprueft. -Installationsprogramme, die Version, Dateigröße, SHA-256-Prüfsumme und die unveränderliche versionsspezifische URL -benötigen, können die Metadaten des stabilen Kanals abrufen: - -[latest.json anzeigen](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/latest.json) - -Das Dokument enthält: - -- `skillVersion`: die aktuelle stabile Version des Skills; -- `skill.url`: die unveränderliche ZIP-URL für diese Version; -- `skill.sha256` und `skill.size`: Werte zur Überprüfung des Downloads; -- `manifest.url`: das unveränderliche Release-Manifest für diese Version. - -Für eine strenge Überprüfung oder eine reproduzierbare automatisierte Installation lesen Sie `latest.json`, laden -`skill.url` herunter und überprüfen `skill.sha256`. Erstellen Sie eine versionsspezifische URL nicht selbst. - -## Skill installieren - -### Voraussetzungen - -- Der Host-Agent unterstützt lokale Skills, die durch `SKILL.md` definiert werden. -- CPython 3.8 bis 3.14 ist installiert. Verwenden Sie unter macOS/Linux `python3` und unter Windows vorzugsweise - `py -3`. -- Die Umgebung kann auf die oben genannten OSS-URLs zugreifen, um das Skill-ZIP und die beim ersten Start benötigte - Runtime herunterzuladen. -- Eine Modellservice-Konfiguration ist vorhanden. Für Aufgaben, die Cloud-Ressourcen abfragen oder verwalten, ist - außerdem eine Alibaba-Cloud-Identität mit minimal erforderlichen Berechtigungen nötig. - -Offizielle Skill-Runtime-Versionen unterstützen folgende Plattformen: - -| Betriebssystem | Architektur | -|---|---| -| macOS | Apple Silicon (arm64) | -| Linux | x86_64 | -| Windows | x86_64 | - -Die Mindestversionen des Betriebssystems und der Linux-glibc werden durch das vom Skill festgelegte Runtime-Manifest -bestimmt. Die Bridge prüft die Kompatibilität vor dem Download. Auf einer nicht unterstützten Plattform gibt sie -einen Fehler zurück, statt ein Artefakt für eine andere Plattform oder ABI herunterzuladen. - -### In das Skill-Verzeichnis des Host-Agenten entpacken - -Entpacken Sie das ZIP direkt in das Skill-Stammverzeichnis des Host-Agenten. Der genaue Pfad ist vom jeweiligen -Produkt abhängig; beachten Sie die Dokumentation des Host-Agenten. Die endgültige Verzeichnisstruktur muss so -aussehen: +Entpacken Sie die ZIP-Datei in das vom Agenten dokumentierte Skill-Verzeichnis. Das Archiv enthaelt bereits +`iac-code/`: ```text / └── iac-code/ ├── SKILL.md - ├── agents/ - │ └── openai.yaml - └── scripts/ - └── iac_code.py + ├── agents/openai.yaml + └── scripts/iac_code.py ``` -Das ZIP enthält bereits das oberste Verzeichnis `iac-code/`. Legen Sie kein weiteres Verzeichnis mit demselben Namen -an. Starten Sie den Host-Agenten nach der Installation oder Aktualisierung neu oder öffnen Sie eine neue Sitzung, -damit er den Skill erneut erkennt. +Uebliche Speicherorte: -### Installation überprüfen +- **Codex**: `~/.agents/skills/iac-code/` fuer alle Projekte oder + `/.agents/skills/iac-code/` fuer ein Repository. Siehe + [Codex-Skills-Dokumentation](https://developers.openai.com/codex/skills#where-codex-loads-local-skills). +- **Claude Code**: `~/.claude/skills/iac-code/` fuer alle Projekte oder + `/.claude/skills/iac-code/` fuer ein Repository. Siehe + [Claude-Code-Skills-Dokumentation](https://code.claude.com/docs/en/skills#where-skills-live). -Führen Sie im entpackten Verzeichnis `iac-code` unter macOS oder Linux folgenden Befehl aus: +Starten Sie den Agenten neu oder oeffnen Sie eine neue Sitzung. Pruefen Sie die Runtime im entpackten Verzeichnis mit: ```bash python3 scripts/iac_code.py ensure-runtime ``` -Führen Sie in Windows PowerShell folgenden Befehl aus: - -```powershell -py -3 scripts\iac_code.py ensure-runtime -``` - -Beim ersten Aufruf lädt der Befehl die Runtime für die aktuelle Plattform herunter, überprüft Größe und -SHA-256-Prüfsumme und gibt JSON mit `skillVersion`, `runtimeTag` und dem Installationspfad aus. Eine überprüfte Runtime -im Cache wird ohne erneuten Download wiederverwendet. +In Windows PowerShell verwenden Sie `py -3 scripts\iac_code.py ensure-runtime`. Beim ersten Aufruf werden Groesse und +SHA-256 der passenden Runtime geprueft; spaetere Aufgaben nutzen die verifizierte lokale Kopie. -## Modell und Alibaba-Cloud-Identität konfigurieren +## Modell und Alibaba-Cloud-Identitaet konfigurieren -Die Skill Runtime verwendet dasselbe Konfigurationsverzeichnis wie die anderen IaC-Code-Modi: standardmäßig -`~/.iac-code/`. Wenn Sie IaC Code bereits über REPL, Web-App oder Desktop-App konfiguriert haben, kann der Skill diese -Einstellungen wiederverwenden. Mit `IAC_CODE_CONFIG_DIR` legen Sie ein anderes Konfigurationsverzeichnis fest. +Der Skill verwendet standardmaessig `~/.iac-code/` und uebernimmt vorhandene Einstellungen aus REPL, Web- oder +Desktop-App. Ein anderes Verzeichnis wird mit `IAC_CODE_CONFIG_DIR` gewaehlt. Automatisierte Umgebungen sollten Modell- +und Cloud-Zugangsdaten aus einer Geheimnisverwaltung beziehen. Schreiben Sie sie nicht in `SKILL.md`, Prompts, +Projektdateien oder die Shell-Historie. Bevorzugen Sie temporaere Zugangsdaten, RAM-Rollen oder OAuth mit minimalen +Rechten. Details: [LLM-Anbieter](../configuration/llm-providers.md) und +[Alibaba-Cloud-Zugangsdaten](../configuration/alibaba-cloud-credentials.md). -Stellen Sie in automatisierten Umgebungen die folgenden Variablen über eine Lösung zur Geheimnisverwaltung bereit: +## Arbeitsmodus waehlen -| Kategorie | Umgebungsvariable | Beschreibung | -|---|---|---| -| Modell | `IAC_CODE_PROVIDER` | Modellanbieter | -| Modell | `IAC_CODE_MODEL` | Modellname | -| Modell | `IAC_CODE_API_KEY` | API-Schlüssel des Modellservice | -| Modell | `IAC_CODE_BASE_URL` | Optionale Überschreibung des kompatiblen Endpunkts | -| Alibaba Cloud | `ALIBABA_CLOUD_ACCESS_KEY_ID` | AccessKey-ID | -| Alibaba Cloud | `ALIBABA_CLOUD_ACCESS_KEY_SECRET` | AccessKey-Secret | -| Alibaba Cloud | `ALIBABA_CLOUD_SECURITY_TOKEN` | Sicherheitstoken für STS-Anmeldeinformationen | -| Alibaba Cloud | `ALIBABA_CLOUD_REGION_ID` | Standardregion | +- Der **Normalmodus** ist der Standard fuer Abfragen und Aenderungen, Vorlagenarbeit, Fehleranalyse und die + Bereitstellung eines klaren Ziels. +- Der **Pipeline-Modus** wird auf ausdruecklichen Wunsch oder fuer einen gefuehrten Ablauf mit Architekturvorschlaegen, + Kostenvergleich, Bestaetigung und Bereitstellung verwendet. -Speichern Sie echte Anmeldeinformationen niemals in `SKILL.md`, in Prompts des Host-Agenten, in Projektdateien oder -im Shell-Verlauf. Bevorzugen Sie temporäre Anmeldeinformationen, RAM-Rollen oder OAuth und vergeben Sie nur die für -die Aufgabe erforderlichen Cloud-API-Berechtigungen. Vollständige Anleitungen finden Sie unter -[LLM-Anbieter](../configuration/llm-providers.md) und -[Alibaba-Cloud-Anmeldeinformationen](../configuration/alibaba-cloud-credentials.md). +Beschreiben Sie normalerweise nur das gewuenschte Ergebnis. Nennen Sie Pipeline, wenn Sie Loesungen vergleichen wollen. ## Erste Verwendung -Öffnen Sie nach Installation und Konfiguration eine neue Sitzung im Host-Agenten und beschreiben Sie direkt eine -Alibaba-Cloud-Infrastrukturaufgabe. Beispiel: +Oeffnen Sie eine neue Sitzung im Host-Agenten und geben Sie beispielsweise ein: ```text -Verwende iac-code, um die ROS-Vorlage in diesem Projekt zu prüfen. Liste Sicherheitsrisiken und empfohlene Änderungen auf, ohne die Datei zu verändern. +Pruefe mit iac-code die ROS-Vorlage in diesem Projekt. Liste Sicherheitsrisiken und Verbesserungen auf, ohne die Datei zu aendern. ``` -Host-Agenten mit einer expliziten Skill-Syntax können den Skill mit `$iac-code` auswählen. Der Host-Agent liest -`SKILL.md`, schreibt die vollständige Anfrage in eine UTF-8-Datei im Arbeitsbereich und verwendet die Bridge, um eine -Aufgabe zu erstellen und zu verfolgen. Der Benutzer muss keinen A2A-Server manuell starten. +Waehlen Sie den Skill in Codex mit `$iac-code` oder in Claude Code mit `/iac-code` explizit aus. Konfigurationspruefung und Runtime-Start erfolgen +automatisch; ein A2A Server muss nicht manuell gestartet werden. IaC Code kann pausieren, um Folgendes anzufordern: -Erwarteter Ablauf: +- Freigabe oder Ablehnung einer Aktion (`permission`) +- Antwort auf eine Frage (`ask_user_question`) +- Auswahl einer Architektur (`candidate_selection`) +- Pruefung von Loesung, Preis und Parametern sowie Bestaetigen, Anpassen, Neuauswaehlen oder Abbrechen + (`deployment_confirmation`) -1. Die Bridge prüft, ob die Modell- und Alibaba-Cloud-Konfiguration vollständig ist. -2. Bei der ersten Verwendung lädt sie die vom Skill festgelegte IaC Code Runtime herunter und überprüft sie. -3. Die Runtime lauscht ausschließlich an einem zufälligen Port auf `127.0.0.1` und erzeugt ein prozessspezifisches - Bearer-Token. -4. Der Host-Agent zeigt Fortschritt, Fragen, Planvorschläge und Berechtigungsanfragen von IaC Code an. -5. Nach Abschluss der Aufgabe gibt der Host-Agent das Endergebnis und die im Arbeitsbereich erzeugten Dateien zurück. +Pruefen Sie Zielressourcen, Region, Auswirkungen und Preis. Ein urspruenglicher Bereitstellungswunsch genehmigt nicht +automatisch die spaetere Bestaetigung. Nach Abschluss koennen Sie in derselben Sitzung weiterarbeiten; der Kontext bleibt +erhalten. Fortschritt und Fragen werden auf Englisch, vereinfachtem Chinesisch, Spanisch, Franzoesisch, Deutsch, +Japanisch oder Portugiesisch ausgegeben. ## Aktualisieren und deinstallieren -Laden Sie für eine manuelle Aktualisierung `skill/stable/iac-code-skill.zip` erneut herunter und ersetzen Sie das -gesamte Verzeichnis `iac-code/` im Skill-Stammverzeichnis des Hosts. Ein automatisches Aktualisierungsprogramm kann -`skillVersion` aus `latest.json` vergleichen und anschließend das neue Paket über dessen unveränderliche URL und -SHA-256-Prüfsumme herunterladen und überprüfen. Jeder offizielle Skill ist auf eine überprüfte Runtime festgelegt. -Ersetzen Sie nicht nur `scripts/iac_code.py` und ändern Sie Runtime-URL oder Prüfsumme nicht manuell. - -Zum Deinstallieren entfernen Sie `iac-code/` aus dem Skill-Stammverzeichnis des Host-Agenten. Der Runtime-Cache wird -nicht zusammen mit dem Skill-Verzeichnis gelöscht. Führen Sie `cache list` und `cache clean` nur aus, wenn der Benutzer -ausdrücklich das Löschen des Caches verlangt. - -## Runtime-Cache - -Die bei der ersten Verwendung heruntergeladene Runtime wird unter -`/skill-runtime///` zwischengespeichert und automatisch -wiederverwendet. Im normalen Betrieb müssen Sie dieses Verzeichnis nicht verwalten. Mit folgenden Befehlen können Sie -den Speicherbedarf prüfen oder ältere Versionen entfernen: - -- `python3 scripts/iac_code.py cache list` — installierte Runtimes und Kandidatenpakete auflisten; -- `python3 scripts/iac_code.py cache clean [--runtime-tag ] [--candidates] --confirm` — Runtime-Caches oder - Kandidatenpakete entfernen; `--confirm` ist erforderlich. - -Die aktuelle Runtime und jede Runtime, die von einem laufenden Prozess verwendet wird, sind vor dem Bereinigen -geschützt. Paketformat und Runtime-Einschränkungen werden im Quelldepot durch -`skill-runtime/skill-package-contract.json` definiert; Benutzer müssen diese Datei nicht ändern. +Laden Sie fuer ein Update die stabile ZIP erneut herunter, ersetzen Sie `iac-code/` vollstaendig und starten Sie den +Agenten neu. Ersetzen Sie nicht nur das Bridge-Skript und aendern Sie weder Runtime-URL noch Digest. Zum Deinstallieren +loeschen Sie `iac-code/`. Die Runtime bleibt im Cache; pruefen Sie vor einer zusaetzlichen Bereinigung `cache list` und +verwenden Sie danach `cache clean ... --confirm`. ## Fehlerbehebung -### Konfiguration ist unvollständig - -Der Skill prüft die Konfiguration vor dem Erstellen einer Aufgabe, liest oder übermittelt jedoch niemals geheime -Werte: - -| Situation | Ergebnis | -|---|---| -| LLM-Anbieter oder API-Schlüssel ist unvollständig | Gibt `llm_not_configured` zurück und erstellt die Aufgabe nicht | -| Alibaba-Cloud-Anmeldeinformationen für die Selling Pipeline sind unvollständig | Gibt `cloud_credentials_not_configured` zurück und erstellt die Aufgabe nicht | -| Alibaba-Cloud-Anmeldeinformationen sind im normalen Modus unvollständig | Aufgaben ohne Cloud-API-Aufrufe können mit einer Vorabwarnung fortgesetzt werden | - -### Warum die Ausführung pausiert - -IaC Code pausiert, wenn eine Berechtigung, zusätzliche Informationen oder die Auswahl eines Plans erforderlich ist. -Der Host-Agent zeigt die Anfrage unmittelbar an: - -- eine Berechtigungsanfrage für ein Tool oder eine Bereitstellung (`permission`); -- eine Multiple-Choice-Frage oder eine Bitte um weitere Informationen (`ask_user_question`); -- die Auswahl eines Planvorschlags aus der Pipeline (`candidate_selection`). - -Prüfen Sie vor der Bestätigung Zielressource, Region, erwartete Auswirkungen und Preis. Der Host-Agent kann eine -Ablehnung von IaC Code nicht außer Kraft setzen. Eine einmalige Genehmigung wird im Protokoll als `allow_once` -dargestellt. +- `llm_not_configured`: Vervollstaendigen Sie die Modellkonfiguration. +- `cloud_credentials_not_configured`: Hinterlegen Sie die fuer Pipeline erforderlichen Cloud-Zugangsdaten. Der + Normalmodus kann Aufgaben ohne Cloud-API mit einer Warnung fortsetzen. +- `incompatible_host`: Fuehren Sie `ensure-runtime` aus und pruefen Sie Python, System, Architektur, Netzwerk und Proxy. + Aktualisieren oder wechseln Sie den Host, statt die Pruefung zu umgehen. +- Pausierte Aufgabe: Sie wartet auf eine Antwort, Freigabe, Auswahl oder Bereitstellungsbestaetigung. Ist die + Host-Sitzung nach einer Unterbrechung noch vorhanden, setzen Sie dieselbe Aufgabe fort. -> **Hinweis zur Integration des Host-Agenten** -> -> Enthält ein Bridge-Ergebnis `inputRequired`, muss der Host-Agent die aktuelle Anfrage anzeigen und auf eine Antwort -> warten. `boundaryReached` kennzeichnet eine Anzeige- oder Interaktionsgrenze, nicht den Abschluss der Aufgabe; der -> Host muss die Aktualisierung anzeigen und dieselbe Aufgabe weiter verfolgen. +Mit `python3 scripts/iac_code.py cache list` pruefen Sie den Cache. Alte Runtimes entfernen Sie mit +`cache clean --runtime-tag --confirm`, Kandidaten mit `cache clean --candidates --confirm`. Aktuelle und aktive +Runtimes sind geschuetzt. ## Sicherheit -- Die Runtime lauscht ausschließlich an einem zufälligen Port auf `127.0.0.1`. Bei jedem Start wird ein neues - Bearer-Token erzeugt, das jede Anfrage der Bridge mitführt. -- Die Bridge speichert Artefakte und Ergebnisse im Arbeitsbereich der Aufgabe. Ergebnisse werden in - `.iac-code-skill-results/` geschrieben. -- Anzeigefelder der Vorabprüfung und der Berechtigungsanfragen werden bereinigt; Geheimnisse und Anmeldeinformationen - erscheinen dort nicht. +- Die Runtime lauscht nur auf einem zufaelligen `127.0.0.1`-Port und nutzt pro Prozess einen neuen Bearer token. +- Ergebnisse bleiben im Workspace, gegebenenfalls unter `.iac-code-skill-results/`. +- Bereitschafts- und Freigabeanzeigen enthalten keine Werte von Zugangsdaten. -## Verwandte Dokumentation +## Weitere Dokumentation -- [Übersicht zum A2A-Protokoll](./overview.md) -- [Referenz zum A2A-Protokoll](./protocol-reference.md) -- [LLM-Anbieter](../configuration/llm-providers.md) -- [Alibaba-Cloud-Anmeldeinformationen](../configuration/alibaba-cloud-credentials.md) +- [Ueberblick ueber offizielle IaC Code Skills](./skill-overview.md) +- [Referenz zur Host-Integration des IaC Code Skills](./skill-host-integration.md) +- [A2A-Protokolluebersicht](./overview.md) - [Runtime-Konfiguration](../configuration/runtime-configuration.md) diff --git a/website/i18n/de/docusaurus-plugin-content-docs/current/a2a/skill-overview.md b/website/i18n/de/docusaurus-plugin-content-docs/current/a2a/skill-overview.md new file mode 100644 index 00000000..a5af5e9a --- /dev/null +++ b/website/i18n/de/docusaurus-plugin-content-docs/current/a2a/skill-overview.md @@ -0,0 +1,69 @@ +--- +sidebar_position: 1 +title: Ueberblick ueber offizielle IaC Code Skills +description: Vergleichen Sie die offiziellen IaC Code Skills und waehlen Sie die passende Distribution. +--- + +# Ueberblick ueber offizielle IaC Code Skills + +IaC Code ist in drei offiziellen Skill-Distributionen verfuegbar. Alle verwalten Alibaba-Cloud-Infrastruktur ueber +einen Agenten, unterscheiden sich aber bei Vertriebskanal und Ausfuehrungsort des IaC Code Agenten. + +## Skill auswaehlen + +| Skill | Ausfuehrungsort | Geeignet, wenn | +|---|---|---| +| `iac-code` | Verifizierte IaC Code Runtime auf Ihrem Rechner | Sie das eigenstaendige Paket des iac-code-Projekts und direkte Kontrolle ueber Installation und Updates wollen. | +| `alibabacloud-iac-code` | Dieselbe lokale Runtime, verpackt fuer das Alibaba Cloud Agent Skills Portal | Sie Alibaba Cloud Skills ueber das Portal oder `npx skills` verwalten. | +| `alibabacloud-ros-agent` | Gehosteter Alibaba Cloud ROS Agent ueber die ROS StartChat API | Sie einen Remote-Agenten ohne lokale IaC Code Runtime verwenden wollen. | + +`iac-code` und `alibabacloud-iac-code` bieten dieselbe Runtime-Funktion. Waehlen Sie innerhalb eines Agentenbereichs +eine Distribution; beide zusammen erzeugen ueberlappende Ausloeser, aber keine zusaetzlichen Funktionen. + +`alibabacloud-ros-agent` ist eine getrennte Remote-Integration. Sie kann neben einer lokalen Distribution installiert +werden, wenn Benutzer explizit zwischen lokaler und gehosteter Ausfuehrung waehlen sollen. + +## Eigenstaendigen Skill beziehen + +[Stabile iac-code-skill.zip herunterladen](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/iac-code-skill.zip) + +Diese Distribution eignet sich fuer eine manuell verwaltete Installation. Sie laedt beim ersten Einsatz die Runtime +und verwendet Modell- sowie Alibaba-Cloud-Einstellungen aus `~/.iac-code/`. Siehe +[IaC Code Skill installieren und verwenden](./skill-integration.md). + +## Skills aus dem Alibaba Cloud Portal beziehen + +Suchen Sie die exakten Namen im [Alibaba Cloud Agent Skills Portal](https://skills.aliyun.com/) oder installieren Sie +aus dem offiziellen Repository: + +```bash +npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-iac-code +npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-ros-agent +``` + +Direkte Downloads: + +- [`alibabacloud-iac-code` ZIP](https://skills.aliyun.com/api/public/skills/alibabacloud-iac-code/download) · [Quellcode](https://github.com/aliyun/alibabacloud-aiops-skills/tree/master/skills/developertools/ros/alibabacloud-iac-code) +- [`alibabacloud-ros-agent` ZIP](https://skills.aliyun.com/api/public/skills/alibabacloud-ros-agent/download) · [Quellcode](https://github.com/aliyun/alibabacloud-aiops-skills/tree/master/skills/developertools/ros/alibabacloud-ros-agent) + +`npx skills` benoetigt Node.js 18 oder neuer und laesst Agent sowie Installationsbereich interaktiv auswaehlen. Bei einem +ZIP entpacken Sie das oberste Skill-Verzeichnis in das Benutzer- oder Projekt-Skill-Verzeichnis des Agenten. + +## Unterschiede bei Funktionen und Konfiguration + +Beide lokalen Distributionen unterstuetzen normale Gespraeche und Pipeline, Architekturplanung, ROS-/Terraform- +Vorlagen, Kostenschaetzung, Stack-Operationen, Bereitstellung und Bestaetigungen. Sie benoetigen ein konfiguriertes Modell +und fuer Abfragen oder Aenderungen von Cloud-Ressourcen Alibaba-Cloud-Zugangsdaten. + +`alibabacloud-ros-agent` verbindet sich mit `ros:StartChat` zum Alibaba Cloud ROS Agent. Lokale Runtime und lokaler +Modellanbieter sind nicht erforderlich; verwendet wird die Alibaba-Cloud-Identitaet des Hosts. Gewaehren Sie nur die +noetigen RAM-Rechte. Ein expliziter Remote-Abbruch nutzt zusaetzlich `ros:StopChat`. + +Pruefen Sie bei allen Varianten Ressourcen, Region, Auswirkungen, Preis und Rechte vor einer Freigabe. Speichern Sie +Zugangsdaten nicht in `SKILL.md`, Prompts oder Projektdateien. + +## Weitere Dokumentation + +- [IaC Code Skill installieren und verwenden](./skill-integration.md) +- [Host-Integrationsreferenz](./skill-host-integration.md) +- [Alibaba-Cloud-Zugangsdaten](../configuration/alibaba-cloud-credentials.md) diff --git a/website/i18n/de/docusaurus-plugin-content-docs/current/intro.md b/website/i18n/de/docusaurus-plugin-content-docs/current/intro.md index 78d75bbf..7983b5ca 100644 --- a/website/i18n/de/docusaurus-plugin-content-docs/current/intro.md +++ b/website/i18n/de/docusaurus-plugin-content-docs/current/intro.md @@ -6,7 +6,7 @@ description: Was IaC Code macht und wo Sie anfangen koennen. # Ueberblick -IaC Code ist ein KI-gestuetzter Infrastructure-as-Code-Assistent fuer Cloud-Infrastruktur. Er hilft Cloud-Ressourcen-Nutzern und -Betreibern dabei, Infrastrukturvorlagen ueber einen Terminal-Workflow zu generieren, bereitzustellen und zu verwalten. Die Architektur ist fuer Multicloud-Workflows ausgelegt; die aktuelle Version unterstuetzt Alibaba Cloud ROS- und Terraform-Workflows. +IaC Code ist ein KI-Assistent zum Planen, Erstellen, Bereitstellen und Verwalten von Cloud-Infrastruktur. Er ist als Desktop-App, lokale Web-App, interaktives Terminal, Automatisierungsschnittstelle oder als Skill in einem anderen Agenten nutzbar. Die Architektur ist fuer Multicloud-Workflows ausgelegt; die aktuelle Version unterstuetzt Alibaba Cloud ROS und Terraform. Kernfunktionen: @@ -14,4 +14,11 @@ Kernfunktionen: - **Von der Vorlage zur laufenden Infrastruktur** -- fuer Alibaba Cloud ROS gehen Sie von der Vorlage bis zur laufenden Infrastruktur: erstellen, aktualisieren, loeschen und ueberwachen Sie Stacks ueber Regionen hinweg. Die Terraform-Unterstuetzung umfasst die Generierung und Konvertierung von Vorlagen, nicht jedoch die Bereitstellung. - **Integrierte Cloud-Intelligenz** -- durchsuchen Sie Dokumentation, pruefen Sie die Ressourcenverfuegbarkeit und schaetzen Sie Kosten, bevor Sie bereitstellen; jede Entscheidung wird durch echte Cloud-Daten gestuetzt. -Die Dokumentation ist nach Benutzeraufgaben organisiert. Beginnen Sie mit Installation und Schnellstart, konfigurieren Sie dann Anbieter und Anmeldedaten und verwenden Sie die CLI-Referenz, wenn Sie Befehlsdetails benoetigen. +Waehlen Sie den passenden Einstieg: + +- Laden Sie die [Desktop-App](./desktop-app.md) fuer eine sofort nutzbare grafische Anwendung herunter. +- Folgen Sie [Installation](./getting-started/installation.md) und [Schnellstart](./getting-started/quick-start.md) fuer REPL, Headless-Modus oder die lokale [Web-App](./web-app.md). +- Waehlen Sie im [Ueberblick ueber offizielle IaC Code Skills](./a2a/skill-overview.md) eine Distribution, um einem kompatiblen Agenten Alibaba-Cloud-Infrastrukturfaehigkeiten zu geben. +- Verwenden Sie [ACP](./acp/overview.md), [A2A](./a2a/overview.md) oder [AG-UI](./agui/overview.md) zur Integration in eine Anwendung oder einen Dienst. + +Alle Einstiege benoetigen ein konfiguriertes Modell. Fuer Abfragen, Aenderungen oder Bereitstellungen konfigurieren Sie zudem [Alibaba-Cloud-Zugangsdaten](./configuration/alibaba-cloud-credentials.md). diff --git a/website/i18n/es/docusaurus-plugin-content-docs/current.json b/website/i18n/es/docusaurus-plugin-content-docs/current.json index 1202557c..eb4a466a 100644 --- a/website/i18n/es/docusaurus-plugin-content-docs/current.json +++ b/website/i18n/es/docusaurus-plugin-content-docs/current.json @@ -11,6 +11,10 @@ "message": "Usar IaC Code", "description": "The label for category 'Using iac-code' in sidebar 'docsSidebar'" }, + "sidebar.docsSidebar.category.IaC Code Skill": { + "message": "Skill de IaC Code", + "description": "The label for category 'IaC Code Skill' in sidebar 'docsSidebar'" + }, "sidebar.docsSidebar.category.MCP Integration": { "message": "Integración MCP", "description": "The label for category 'MCP Integration' in sidebar 'docsSidebar'" diff --git a/website/i18n/es/docusaurus-plugin-content-docs/current/a2a/overview.md b/website/i18n/es/docusaurus-plugin-content-docs/current/a2a/overview.md index 540971ef..e2331551 100644 --- a/website/i18n/es/docusaurus-plugin-content-docs/current/a2a/overview.md +++ b/website/i18n/es/docusaurus-plugin-content-docs/current/a2a/overview.md @@ -22,7 +22,7 @@ Usa A2A cuando otro agente, motor de flujos de trabajo o servicio necesite llama - **Automatización de flujos de trabajo** — Las herramientas internas pueden enviar tareas de generación, revisión o conversión de IaC por HTTP. - **Descubrimiento de servicios** — Los clientes pueden obtener la Agent Card y elegir capacidades como generación de IaC o revisión de plantillas. - **Integraciones con streaming** — Un cliente de chatops o panel puede mostrar texto del modelo, actividad de herramientas, metadatos de uso y el estado final de la tarea mientras se ejecuta el turno. -- **Integración de Skill externa** — Agentes externos usan el Skill empaquetado de iac-code para impulsar un runtime A2A local autenticado mediante un script puente de solo biblioteca estándar, incorporando iac-code como su capacidad de infraestructura de Alibaba Cloud. Consulta [Integración de Skill](./skill-integration.md). +- **Integración de Skill externa** — Los agentes externos pueden añadir capacidades de infraestructura de Alibaba Cloud a sus flujos de trabajo con un Skill oficial de IaC Code. Consulta [Skills oficiales de IaC Code](./skill-overview.md) para elegir una distribución y después [Instalar y usar el Skill](./skill-integration.md) o la [referencia para hosts](./skill-host-integration.md). ## Comparación de modos de interacción diff --git a/website/i18n/es/docusaurus-plugin-content-docs/current/a2a/skill-host-integration.md b/website/i18n/es/docusaurus-plugin-content-docs/current/a2a/skill-host-integration.md new file mode 100644 index 00000000..33997332 --- /dev/null +++ b/website/i18n/es/docusaurus-plugin-content-docs/current/a2a/skill-host-integration.md @@ -0,0 +1,137 @@ +--- +sidebar_position: 3 +title: Referencia de integración del Skill de IaC Code para hosts +description: Integra el puente del Skill de IaC Code en un agente host compatible. +--- + +# Referencia de integración del Skill de IaC Code para hosts + +Este documento está dirigido a desarrolladores de agentes y sistemas de distribución de Skills. Los usuarios deben +consultar [Instalar y usar el Skill de IaC Code](./skill-integration.md). + +## Modelo de integración y configuración + +El paquete contiene `SKILL.md` y el puente `scripts/iac_code.py`, que solo usa la biblioteca estándar. Ejecútalo con +CPython 3.8 a 3.14. Trata stdout como resultado JSON estable y stderr como diagnóstico y progreso. Conserva `jobId`, +`contextId`, el cursor y los campos de correlación. Ante un error, no recurras a otro Runtime ni a llamadas directas a +las API cloud. + +El distribuidor puede colocar este `config.json` junto a `SKILL.md`: + +```json +{ + "channel": "codex", + "pipelineName": "selling_solution_first", + "permissionWaitPolicy": { + "residentTimeoutSeconds": null, + "subPipelineTimeoutSeconds": null, + "timeoutGraceSeconds": 30 + } +} +``` + +El puente antepone `skill/` a `channel`. El valor predeterminado de `pipelineName` es `selling_solution_first`; +`selling` queda para un flujo heredado solicitado explícitamente. `null` significa espera ilimitada. Se rechazan campos +desconocidos o inválidos. Esta política de instalación no se debe derivar de una petición, mostrar ni modificar durante +una tarea. + +## Iniciar y seguir un trabajo + +Escribe la petición completa en un archivo UTF-8 del workspace y usa una ruta absoluta: + +```text +python3 scripts/iac_code.py start --mode normal --cwd --prompt-file --language --follow +``` + +Usa `normal` por defecto y `pipeline` solo para el flujo de comparación, confirmación y despliegue. El idioma puede ser +`en`, `zh`, `es`, `fr`, `de`, `ja`, `pt` o `auto`; conserva después `preferredLanguage`. `llm_not_configured` detiene +antes de crear el trabajo y `cloud_credentials_not_configured` indica credenciales ausentes en Pipeline. + +`--follow` devuelve el siguiente límite de presentación o interacción, `turn_completed` o el estado terminal de un +Pipeline. Con `boundaryReached: true`, muestra todos los `userUpdates` y sigue el mismo trabajo: + +```text +python3 scripts/iac_code.py follow --job-id --cursor --wait-seconds 60 +``` + +`boundaryReached` no significa que haya terminado. `presentationRequired` exige mostrar la actualización antes de la +siguiente llamada. En modo normal, usa `finalText` y `artifacts` en `turn_completed`; en un Pipeline terminal, usa +`pipelineResult` y `artifacts` e informa de fallos de limpieza. Solo para diagnóstico o recuperación: + +```text +python3 scripts/iac_code.py poll --job-id --cursor --wait-seconds 5 +``` + +Si el estado es `input-required` sin `inputRequired`, informa del último texto o error y no cambies el trabajo. + +## Gestionar la entrada del usuario + +Cada `inputRequired` es un límite estricto: muéstralo en la interfaz nativa del host y espera una respuesta explícita. +No deduzcas valores predeterminados. Conserva `kind`, `inputId`, `requestTaskId`, `contextId` y, si existe, `toolUseId`. + +| `kind` | Información que debe mostrar el host | Respuesta | +|---|---|---| +| `permission` | Propósito, efecto, objetivo, solo lectura, resúmenes de despliegue y seguridad, acciones | `allow_once` / `deny` | +| `ask_user_question` | Pregunta, opciones y texto libre permitido | Respuesta | +| `candidate_selection` | Todos los resúmenes, diagramas Mermaid, total mensual y partidas | ID o número | +| `deployment_confirmation` | Solución, URL, precio, parámetros efectivos y modificados, Preview, acciones | `confirm` / `adjust` / `reselect` / `cancel` | + +Escribe la respuesta correlacionada en un archivo JSON UTF-8 nuevo y reanuda el mismo trabajo: + +```text +python3 scripts/iac_code.py respond --job-id --input-file --follow +``` + +```json +{"kind":"permission","requestTaskId":"","contextId":"","inputId":"","toolUseId":"","decision":"allow_once"} +``` + +```json +{"kind":"ask_user_question","requestTaskId":"","contextId":"","inputId":"","answer":""} +``` + +```json +{"kind":"candidate_selection","requestTaskId":"","contextId":"","inputId":"","answer":""} +``` + +```json +{"kind":"deployment_confirmation","requestTaskId":"","contextId":"","inputId":"","action":"","parameterOverrides":{"":""}} +``` + +Omite `parameterOverrides` si no hay ajustes. No deduzcas la confirmación de la petición inicial ni de una aprobación +del host. + +## Continuar, cancelar y recuperar + +Después de un turno normal o de pasar un Pipeline terminado al modo normal, continúa el trabajo existente: + +```text +python3 scripts/iac_code.py continue --job-id --prompt-file --follow +``` + +Conserva `jobId` y `contextId`; es normal recibir un `taskId` nuevo. Así también se recuperan esperas de permisos e +interrupciones del host. Para cancelar toda la operación: + +```text +python3 scripts/iac_code.py cancel --job-id +``` + +La cancelación completa no equivale a denegar un permiso. + +## Errores y Runtime + +Un error anterior a la creación es definitivo para esa llamada. Ante `incompatible_host`, muestra la información de +compatibilidad y detente, sin usar pip, otro Runtime ni API directas. El Runtime se guarda en +`/skill-runtime///`. Su estructura e integridad se definen en +`skill-runtime/skill-package-contract.json` y el manifiesto de versión. La limpieza requiere una petición explícita; +los paquetes actuales o activos están protegidos. + +El Runtime usa un puerto aleatorio de `127.0.0.1` y un Bearer token por proceso. No expongas el token, estado local, +credenciales, valores del entorno ni entradas o salidas sin filtrar de herramientas. + +## Documentación relacionada + +- [Visión general de los Skills oficiales de IaC Code](./skill-overview.md) +- [Instalar y usar el Skill de IaC Code](./skill-integration.md) +- [Visión general de A2A](./overview.md) +- [Referencia de A2A](./protocol-reference.md) diff --git a/website/i18n/es/docusaurus-plugin-content-docs/current/a2a/skill-integration.md b/website/i18n/es/docusaurus-plugin-content-docs/current/a2a/skill-integration.md index fde73c99..c2016fca 100644 --- a/website/i18n/es/docusaurus-plugin-content-docs/current/a2a/skill-integration.md +++ b/website/i18n/es/docusaurus-plugin-content-docs/current/a2a/skill-integration.md @@ -1,218 +1,127 @@ --- -sidebar_position: 7 +sidebar_position: 2 title: Instalar y usar el Skill de IaC Code -description: Descarga e instala el Skill de IaC Code para que un agente externo pueda gestionar recursos de Alibaba Cloud. +description: Añade IaC Code a un agente compatible con Skills para gestionar infraestructura de Alibaba Cloud. --- # Instalar y usar el Skill de IaC Code -El Skill de IaC Code está diseñado para agentes externos compatibles con Skills. Una vez instalado, un agente host -puede delegar en IaC Code la planificación de arquitecturas cloud, la generación y revisión de plantillas ROS o -Terraform, la estimación de costes, la selección de recursos, las operaciones con stacks y el despliegue. El Skill -utiliza un puente escrito únicamente con la biblioteca estándar de Python para iniciar un Runtime A2A local y -autenticado. No es necesario instalar IaC Code con pip y el host no debe recurrir a comandos headless. +El Skill de IaC Code permite que un agente compatible delegue en IaC Code el diseño de arquitecturas cloud, la +generación o revisión de plantillas ROS y Terraform, la estimación de costes, la selección de recursos, las operaciones +con stacks ROS y los despliegues. El paquete incluye un Runtime de IaC Code verificado, por lo que no necesitas instalar +IaC Code por separado. -## Descargar el Skill +## Descargar -### Última versión estable +[Descargar el último iac-code-skill.zip estable](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/iac-code-skill.zip) -Descarga directamente la última versión estable: +Esta URL fija siempre apunta a la versión estable más reciente. Los instaladores automáticos pueden leer +[latest.json](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/latest.json) +para obtener la versión, URL inmutable, tamaño y SHA-256, y verificar `skill.url` con `skill.sha256`. -[Descargar iac-code-skill.zip](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/iac-code-skill.zip) +## Instalar -Esta URL fija siempre apunta al paquete del Skill publicado en el canal estable. Es adecuada para descargarlo desde el -navegador o instalarlo manualmente, y no cambia cuando se publica una nueva versión. +Comprueba que el agente admite Skills locales definidos por `SKILL.md`, que dispone de CPython 3.8 a 3.14 y que puede +acceder a la descarga durante el primer uso. Utiliza `python3` en macOS/Linux y `py -3` en Windows. Los Runtimes +oficiales admiten macOS Apple Silicon, Linux x86_64 y Windows x86_64; el sistema y la ABI se comprueban antes de la +descarga. -Los instaladores que necesiten conocer la versión, el tamaño del archivo, el resumen SHA-256 y la URL inmutable de la -versión pueden consultar los metadatos del canal estable: - -[Ver latest.json](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/latest.json) - -El documento contiene: - -- `skillVersion`: versión estable actual del Skill; -- `skill.url`: URL inmutable del archivo ZIP de esa versión; -- `skill.sha256` y `skill.size`: valores para verificar la descarga; -- `manifest.url`: manifiesto de publicación inmutable de esa versión. - -Para realizar una verificación estricta o una instalación automatizada reproducible, lee `latest.json`, descarga -`skill.url` y verifica `skill.sha256`. No construyas por tu cuenta una URL a partir del número de versión. - -## Instalar el Skill - -### Requisitos previos - -- El agente host admite Skills locales definidos mediante `SKILL.md`. -- CPython 3.8–3.14 está instalado. Usa `python3` en macOS/Linux y, preferiblemente, `py -3` en Windows. -- El entorno puede acceder a las URL de OSS anteriores para descargar el ZIP del Skill y el Runtime necesario en el - primer uso. -- La configuración del servicio de modelos está disponible. Para las tareas que consultan o gestionan recursos cloud, - también se necesita una identidad de Alibaba Cloud con privilegios mínimos. - -Las versiones oficiales del Skill Runtime son compatibles con estas plataformas: - -| Sistema operativo | Arquitectura | -|---|---| -| macOS | Apple Silicon (arm64) | -| Linux | x86_64 | -| Windows | x86_64 | - -Las versiones mínimas del sistema operativo y de glibc en Linux se definen en el manifiesto del Runtime fijado por el -Skill. El puente comprueba la compatibilidad antes de descargar. En una plataforma no compatible, devuelve un error en -lugar de descargar un artefacto destinado a otra plataforma o ABI. - -### Extraer en el directorio de Skills del agente host - -Extrae el ZIP directamente en la raíz de Skills del agente host. La ubicación exacta depende de cada producto; -consulta la documentación del agente host. La estructura final debe ser: +Extrae el ZIP en el directorio de Skills indicado por el agente. El archivo ya contiene `iac-code/`: ```text / └── iac-code/ ├── SKILL.md - ├── agents/ - │ └── openai.yaml - └── scripts/ - └── iac_code.py + ├── agents/openai.yaml + └── scripts/iac_code.py ``` -El ZIP ya contiene el directorio superior `iac-code/`. No añadas otro directorio con el mismo nombre. Después de -instalar o actualizar, reinicia el agente host o abre una sesión nueva para que vuelva a detectar el Skill. +Ubicaciones habituales: -### Verificar la instalación +- **Codex**: `~/.agents/skills/iac-code/` para todos los proyectos o + `/.agents/skills/iac-code/` para uno. Consulta la + [documentación de Codex Skills](https://developers.openai.com/codex/skills#where-codex-loads-local-skills). +- **Claude Code**: `~/.claude/skills/iac-code/` para todos los proyectos o + `/.claude/skills/iac-code/` para uno. Consulta la + [documentación de Claude Code Skills](https://code.claude.com/docs/en/skills#where-skills-live). -En el directorio `iac-code` extraído, ejecuta este comando en macOS o Linux: +Reinicia el agente o abre una sesión nueva. Para comprobar el Runtime desde el directorio `iac-code`: ```bash python3 scripts/iac_code.py ensure-runtime ``` -En Windows PowerShell, ejecuta: - -```powershell -py -3 scripts\iac_code.py ensure-runtime -``` - -En la primera ejecución, el comando descarga el Runtime para la plataforma actual, verifica su tamaño y su resumen -SHA-256, y muestra un objeto JSON con `skillVersion`, `runtimeTag` y la ruta de instalación. Un Runtime verificado que -ya esté en caché se reutiliza sin volver a descargarlo. +En Windows PowerShell utiliza `py -3 scripts\iac_code.py ensure-runtime`. La primera ejecución descarga el Runtime +adecuado y verifica su tamaño y SHA-256; las siguientes tareas reutilizan la copia local verificada. ## Configurar el modelo y la identidad de Alibaba Cloud -El Skill Runtime utiliza el mismo directorio de configuración que los demás modos de IaC Code: `~/.iac-code/` de forma -predeterminada. Si ya has configurado IaC Code mediante el REPL, la aplicación web o la aplicación Desktop, el Skill -puede reutilizar esos ajustes. Define `IAC_CODE_CONFIG_DIR` para usar otro directorio de configuración. +El Skill usa `~/.iac-code/` de forma predeterminada y reutiliza los ajustes del REPL, la aplicación Web o Desktop. +Puedes elegir otro directorio con `IAC_CODE_CONFIG_DIR`. En entornos automatizados, inyecta la configuración del modelo +y las credenciales de Alibaba Cloud desde un gestor de secretos. No las escribas en `SKILL.md`, prompts, archivos del +proyecto ni el historial del shell. Prefiere credenciales temporales, roles RAM u OAuth con permisos mínimos. Consulta +[Proveedores LLM](../configuration/llm-providers.md) y +[Credenciales de Alibaba Cloud](../configuration/alibaba-cloud-credentials.md). -En entornos automatizados, proporciona estas variables mediante una solución de gestión de secretos: +## Elegir el modo de trabajo -| Categoría | Variable de entorno | Descripción | -|---|---|---| -| Modelo | `IAC_CODE_PROVIDER` | Proveedor del modelo | -| Modelo | `IAC_CODE_MODEL` | Nombre del modelo | -| Modelo | `IAC_CODE_API_KEY` | Clave de API del servicio de modelos | -| Modelo | `IAC_CODE_BASE_URL` | Sustitución opcional del endpoint compatible | -| Alibaba Cloud | `ALIBABA_CLOUD_ACCESS_KEY_ID` | ID de AccessKey | -| Alibaba Cloud | `ALIBABA_CLOUD_ACCESS_KEY_SECRET` | Secreto de AccessKey | -| Alibaba Cloud | `ALIBABA_CLOUD_SECURITY_TOKEN` | Token de seguridad para credenciales STS | -| Alibaba Cloud | `ALIBABA_CLOUD_REGION_ID` | Región predeterminada | +- El **modo normal** es el predeterminado para consultar o cambiar recursos, trabajar con plantillas, resolver + problemas y desplegar un objetivo claro. +- El **modo Pipeline** se usa cuando lo solicitas o cuando necesitas un flujo guiado con arquitecturas candidatas, + comparación de costes, confirmación y despliegue. -No incluyas nunca credenciales reales en `SKILL.md`, los prompts del agente host, los archivos del proyecto ni el -historial del shell. Da preferencia a credenciales temporales, roles RAM u OAuth, y concede solo los permisos de API -cloud necesarios para la tarea. Consulta [Proveedores de LLM](../configuration/llm-providers.md) y -[Credenciales de Alibaba Cloud](../configuration/alibaba-cloud-credentials.md) para ver las instrucciones completas. +Normalmente basta con describir el resultado. Menciona Pipeline solo si quieres comparar soluciones. ## Primer uso -Después de instalar y configurar el Skill, abre una sesión nueva en el agente host y describe directamente una tarea -de infraestructura de Alibaba Cloud. Por ejemplo: +Abre una sesión nueva en el agente host y escribe, por ejemplo: ```text -Usa iac-code para revisar la plantilla ROS de este proyecto. Enumera los riesgos de seguridad y los cambios recomendados sin modificar el archivo. +Usa iac-code para revisar la plantilla ROS de este proyecto. Enumera los riesgos de seguridad y las mejoras sin modificar el archivo. ``` -Los hosts compatibles con una sintaxis explícita de Skills pueden seleccionar el Skill mediante `$iac-code`. El -agente host lee `SKILL.md`, escribe la solicitud completa en un archivo UTF-8 del espacio de trabajo y utiliza el -puente para crear y seguir una única tarea. El usuario no tiene que iniciar manualmente un servidor A2A. +Selecciona el Skill explícitamente con `$iac-code` en Codex o `/iac-code` en Claude Code. La comprobación de configuración y el +inicio del Runtime son automáticos; no necesitas iniciar un A2A Server manualmente. IaC Code puede pausar para pedirte: -Flujo previsto: +- aprobar o rechazar una operación (`permission`); +- responder una pregunta (`ask_user_question`); +- elegir una arquitectura (`candidate_selection`); +- revisar la solución, precio y parámetros, y confirmar, ajustar, volver a seleccionar o cancelar + (`deployment_confirmation`). -1. El puente comprueba si la configuración del modelo y de Alibaba Cloud está lista. -2. En el primer uso, descarga y verifica el Runtime de IaC Code fijado por el Skill. -3. El Runtime escucha únicamente en un puerto aleatorio de `127.0.0.1` y genera un token Bearer específico del proceso. -4. El agente host muestra el progreso, las preguntas, los planes candidatos y las solicitudes de permisos devueltos - por IaC Code. -5. Cuando termina la tarea, el agente host devuelve el resultado final y los archivos generados en el espacio de - trabajo. +Revisa los recursos, región, impacto y precio antes de responder. La petición inicial de desplegar no aprueba por +adelantado la confirmación posterior. Al terminar, continúa en la misma sesión para conservar el contexto. El progreso +y las preguntas están disponibles en inglés, chino simplificado, español, francés, alemán, japonés y portugués. ## Actualizar y desinstalar -Para realizar una actualización manual, vuelve a descargar `skill/stable/iac-code-skill.zip` y sustituye todo el -directorio `iac-code/` de la raíz de Skills del host. Un actualizador automático puede comparar el valor -`skillVersion` de `latest.json` y, después, descargar y verificar el paquete nuevo mediante su URL inmutable y su -resumen SHA-256. Cada Skill oficial está fijado a un Runtime verificado. No sustituyas únicamente -`scripts/iac_code.py` ni modifiques manualmente la URL o el resumen del Runtime. - -Para desinstalarlo, elimina `iac-code/` de la raíz de Skills del agente host. La caché del Runtime no se elimina junto -con el directorio del Skill. Ejecuta `cache list` y `cache clean` solo si el usuario solicita expresamente eliminarla. - -## Caché del Runtime - -El Runtime descargado durante el primer uso se almacena en -`/skill-runtime///` y se reutiliza automáticamente. Durante el -uso normal no es necesario gestionar este directorio. Para consultar el espacio en disco utilizado o eliminar -versiones antiguas, usa: - -- `python3 scripts/iac_code.py cache list` — enumera los Runtimes instalados y los paquetes candidatos; -- `python3 scripts/iac_code.py cache clean [--runtime-tag ] [--candidates] --confirm` — elimina cachés del Runtime - o paquetes candidatos; `--confirm` es obligatorio. - -El Runtime actual y cualquier Runtime utilizado por un proceso activo están protegidos frente a la limpieza. El -formato del paquete y las restricciones del Runtime se definen en `skill-runtime/skill-package-contract.json` dentro -del repositorio de código fuente; los usuarios no necesitan modificar este archivo. +Para actualizar, descarga de nuevo el ZIP estable, reemplaza todo `iac-code/` y reinicia el agente. No sustituyas solo +el puente ni edites la URL o el hash del Runtime. Para desinstalar, elimina `iac-code/`. Los Runtimes quedan en caché; +si también quieres borrarlos, consulta `cache list` y después ejecuta `cache clean ... --confirm`. ## Solución de problemas -### La configuración está incompleta - -El Skill comprueba la configuración antes de crear una tarea, pero nunca lee ni devuelve valores secretos: - -| Situación | Resultado | -|---|---| -| El proveedor de LLM o la clave de API están incompletos | Devuelve `llm_not_configured` y no crea la tarea | -| Las credenciales de Alibaba Cloud están incompletas para el Pipeline de venta | Devuelve `cloud_credentials_not_configured` y no crea la tarea | -| Las credenciales de Alibaba Cloud están incompletas en el modo normal | Las tareas que no llaman a API cloud pueden continuar con una advertencia previa | - -### Por qué se pausa la ejecución - -IaC Code se pausa cuando necesita un permiso, información adicional o la selección de un plan. El agente host muestra -directamente la solicitud: - -- una solicitud de permiso para una herramienta o un despliegue (`permission`); -- una pregunta de opción múltiple o una solicitud de información (`ask_user_question`); -- la selección de un plan candidato del Pipeline (`candidate_selection`). - -Antes de confirmar, revisa el recurso de destino, la región, el impacto previsto y el precio. El agente host no puede -anular una denegación de IaC Code. En el protocolo, una autorización para una sola vez se representa como `allow_once`. +- `llm_not_configured`: completa la configuración del modelo. +- `cloud_credentials_not_configured`: configura las credenciales que requiere Pipeline. El modo normal puede continuar + tareas sin API cloud mostrando una advertencia. +- `incompatible_host`: ejecuta `ensure-runtime` y comprueba Python, sistema, arquitectura, red y proxy. Actualiza o + cambia el host en vez de omitir la comprobación. +- Tarea en pausa: está esperando una respuesta, permiso, selección o confirmación. Si la sesión sigue disponible tras + una interrupción, pide continuar la misma tarea. -> **Nota sobre la integración del agente host** -> -> Cuando un resultado del puente contiene `inputRequired`, el agente host debe mostrar la solicitud actual y esperar -> una respuesta. `boundaryReached` indica un límite de presentación o interacción, no que la tarea haya finalizado; el -> host debe mostrar la actualización y continuar siguiendo la misma tarea. +Usa `python3 scripts/iac_code.py cache list` para consultar la caché, +`cache clean --runtime-tag --confirm` para eliminar una versión anterior y +`cache clean --candidates --confirm` para paquetes candidatos. El Runtime actual o activo está protegido. ## Seguridad -- El Runtime escucha únicamente en un puerto aleatorio de `127.0.0.1`. Cada inicio genera un token Bearer nuevo y cada - solicitud del puente incluye ese token. -- El puente conserva los artefactos y resultados en el espacio de trabajo de la tarea. Los resultados se escriben en - `.iac-code-skill-results/`. -- Los campos que se muestran durante las comprobaciones previas y las solicitudes de permisos se depuran; no contienen - secretos ni credenciales. +- El Runtime solo escucha en un puerto aleatorio de `127.0.0.1` y usa un Bearer token nuevo por proceso. +- Los resultados permanecen en el workspace, bajo `.iac-code-skill-results/` cuando corresponde. +- Los estados de preparación y resúmenes de permisos no contienen valores de credenciales. ## Documentación relacionada -- [Descripción general del protocolo A2A](./overview.md) -- [Referencia del protocolo A2A](./protocol-reference.md) -- [Proveedores de LLM](../configuration/llm-providers.md) -- [Credenciales de Alibaba Cloud](../configuration/alibaba-cloud-credentials.md) +- [Visión general de los Skills oficiales de IaC Code](./skill-overview.md) +- [Referencia de integración del Skill de IaC Code para hosts](./skill-host-integration.md) +- [Visión general de A2A](./overview.md) - [Configuración del Runtime](../configuration/runtime-configuration.md) diff --git a/website/i18n/es/docusaurus-plugin-content-docs/current/a2a/skill-overview.md b/website/i18n/es/docusaurus-plugin-content-docs/current/a2a/skill-overview.md new file mode 100644 index 00000000..15d3cdfd --- /dev/null +++ b/website/i18n/es/docusaurus-plugin-content-docs/current/a2a/skill-overview.md @@ -0,0 +1,69 @@ +--- +sidebar_position: 1 +title: Visión general de los Skills oficiales de IaC Code +description: Compara los Skills oficiales de IaC Code y elige la distribución adecuada. +--- + +# Visión general de los Skills oficiales de IaC Code + +IaC Code está disponible en tres distribuciones oficiales de Skill. Todas permiten gestionar infraestructura de +Alibaba Cloud desde un agente, pero difieren en el canal de distribución y en dónde se ejecuta el Agent de IaC Code. + +## Elegir un Skill + +| Skill | Dónde se ejecuta | Cuándo elegirlo | +|---|---|---| +| `iac-code` | Runtime verificado de IaC Code descargado en tu equipo | Quieres el paquete independiente del proyecto iac-code y controlar directamente instalación y actualizaciones. | +| `alibabacloud-iac-code` | El mismo Runtime local, empaquetado para el portal Alibaba Cloud Agent Skills | Gestionas Alibaba Cloud Skills mediante el portal o `npx skills`. | +| `alibabacloud-ros-agent` | Agent ROS alojado por Alibaba Cloud, llamado con la API ROS StartChat | Quieres una conversación remota sin descargar el Runtime local de IaC Code. | + +`iac-code` y `alibabacloud-iac-code` ofrecen la misma capacidad. Elige una distribución por ámbito del agente; +instalar ambas añade activadores solapados, no funciones nuevas. + +`alibabacloud-ros-agent` es una integración remota independiente. Puede convivir con una distribución local si el +usuario debe elegir explícitamente entre IaC Code local y el Agent ROS alojado. + +## Obtener el Skill independiente + +[Descargar iac-code-skill.zip estable](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/iac-code-skill.zip) + +Esta distribución es adecuada para una instalación gestionada manualmente. Descarga el Runtime en el primer uso y +reutiliza la configuración del modelo y Alibaba Cloud de `~/.iac-code/`. Consulta +[Instalar y usar el Skill de IaC Code](./skill-integration.md). + +## Obtener los Skills del portal de Alibaba Cloud + +Busca los nombres exactos en el [portal Alibaba Cloud Agent Skills](https://skills.aliyun.com/) o instala desde el +repositorio oficial: + +```bash +npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-iac-code +npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-ros-agent +``` + +Descargas directas: + +- [`alibabacloud-iac-code` ZIP](https://skills.aliyun.com/api/public/skills/alibabacloud-iac-code/download) · [código fuente](https://github.com/aliyun/alibabacloud-aiops-skills/tree/master/skills/developertools/ros/alibabacloud-iac-code) +- [`alibabacloud-ros-agent` ZIP](https://skills.aliyun.com/api/public/skills/alibabacloud-ros-agent/download) · [código fuente](https://github.com/aliyun/alibabacloud-aiops-skills/tree/master/skills/developertools/ros/alibabacloud-ros-agent) + +`npx skills` requiere Node.js 18 o posterior y permite elegir interactivamente el agente y el ámbito. Si descargas un +ZIP, extrae su directorio Skill superior en el directorio de usuario o proyecto admitido por el agente. + +## Diferencias de capacidad y configuración + +Las dos distribuciones locales admiten conversaciones normales y Pipeline, arquitectura, plantillas ROS/Terraform, +costes, stacks, despliegue y confirmaciones. Requieren un modelo configurado y credenciales de Alibaba Cloud cuando la +tarea consulta o modifica recursos. + +`alibabacloud-ros-agent` usa `ros:StartChat` para conectar con el Agent ROS de Alibaba Cloud. No requiere Runtime local +ni proveedor de modelo local, pero usa la identidad de Alibaba Cloud del host. Concede solo los permisos RAM necesarios; +una cancelación remota explícita también usa `ros:StopChat`. + +En todos los casos, revisa recursos, región, impacto, precio y permisos antes de aprobar. No guardes credenciales en +`SKILL.md`, prompts ni archivos del proyecto. + +## Documentación relacionada + +- [Instalar y usar el Skill de IaC Code](./skill-integration.md) +- [Referencia de integración para hosts](./skill-host-integration.md) +- [Credenciales de Alibaba Cloud](../configuration/alibaba-cloud-credentials.md) diff --git a/website/i18n/es/docusaurus-plugin-content-docs/current/intro.md b/website/i18n/es/docusaurus-plugin-content-docs/current/intro.md index 7aa6bb32..2b5a22d4 100644 --- a/website/i18n/es/docusaurus-plugin-content-docs/current/intro.md +++ b/website/i18n/es/docusaurus-plugin-content-docs/current/intro.md @@ -6,7 +6,7 @@ description: Que hace IaC Code y por donde empezar. # Vision general -IaC Code es un asistente de Infraestructura como Codigo potenciado por IA para infraestructura cloud. Ayuda a los usuarios y operadores de recursos en la nube a generar, desplegar y gestionar plantillas de infraestructura a traves de un flujo de trabajo en terminal. Su arquitectura esta disenada para flujos de trabajo multicloud; la version actual admite flujos de trabajo de Alibaba Cloud ROS y Terraform. +IaC Code es un asistente de IA para diseñar, generar, desplegar y gestionar infraestructura cloud. Puedes usarlo desde la aplicación Desktop, la aplicación Web local, el terminal interactivo, interfaces de automatización o como Skill de otro agente. Su arquitectura está diseñada para flujos multicloud; la versión actual admite Alibaba Cloud ROS y Terraform. Capacidades principales: @@ -14,4 +14,11 @@ Capacidades principales: - **De la plantilla a produccion** — para Alibaba Cloud ROS, pasa de la plantilla a la infraestructura en ejecucion: crea, actualiza, elimina y monitorea stacks en distintas regiones. El soporte de Terraform cubre la generacion y conversion de plantillas, no el despliegue. - **Inteligencia de nube integrada** — consulta documentacion, verifica la disponibilidad de recursos y estima costos antes de desplegar; cada decision respaldada por datos reales de la nube. -La documentacion esta organizada en torno a las tareas del usuario. Comienza con la instalacion y el inicio rapido, luego configura los proveedores y las credenciales, y usa la referencia del CLI cuando necesites detalles sobre los comandos. +Elige el punto de entrada que corresponda: + +- Descarga la [aplicación Desktop](./desktop-app.md) para una interfaz gráfica lista para usar. +- Sigue la [instalación](./getting-started/installation.md) y el [inicio rápido](./getting-started/quick-start.md) para usar REPL, modo headless o la [aplicación Web](./web-app.md) local. +- Elige una distribución en la [visión general de los Skills oficiales de IaC Code](./a2a/skill-overview.md) para añadir sus capacidades de Alibaba Cloud a un agente compatible. +- Usa [ACP](./acp/overview.md), [A2A](./a2a/overview.md) o [AG-UI](./agui/overview.md) para integrarlo en una aplicación o servicio. + +Todos los puntos de entrada requieren un modelo configurado. Configura también las [credenciales de Alibaba Cloud](./configuration/alibaba-cloud-credentials.md) para consultar, modificar o desplegar recursos. diff --git a/website/i18n/fr/docusaurus-plugin-content-docs/current.json b/website/i18n/fr/docusaurus-plugin-content-docs/current.json index 164dad33..2e96979c 100644 --- a/website/i18n/fr/docusaurus-plugin-content-docs/current.json +++ b/website/i18n/fr/docusaurus-plugin-content-docs/current.json @@ -11,6 +11,10 @@ "message": "Utiliser IaC Code", "description": "The label for category 'Using iac-code' in sidebar 'docsSidebar'" }, + "sidebar.docsSidebar.category.IaC Code Skill": { + "message": "Skill IaC Code", + "description": "The label for category 'IaC Code Skill' in sidebar 'docsSidebar'" + }, "sidebar.docsSidebar.category.MCP Integration": { "message": "Intégration MCP", "description": "The label for category 'MCP Integration' in sidebar 'docsSidebar'" diff --git a/website/i18n/fr/docusaurus-plugin-content-docs/current/a2a/overview.md b/website/i18n/fr/docusaurus-plugin-content-docs/current/a2a/overview.md index c06528ec..7ee19514 100644 --- a/website/i18n/fr/docusaurus-plugin-content-docs/current/a2a/overview.md +++ b/website/i18n/fr/docusaurus-plugin-content-docs/current/a2a/overview.md @@ -22,7 +22,7 @@ Utilisez A2A lorsqu'un autre agent, moteur de workflow ou service doit appeler i - **Automatisation de workflows** — Des outils internes peuvent soumettre des tâches de génération, de revue ou de conversion IaC via HTTP. - **Découverte de service** — Les clients peuvent récupérer l'Agent Card et choisir des capacités comme la génération IaC ou la revue de modèles. - **Intégrations en streaming** — Un client chatops ou tableau de bord peut afficher le texte du modèle, l'activité des outils, les métadonnées d'utilisation et l'état final de la tâche pendant l'exécution du tour. -- **Intégration Skill externe** — Des agents externes utilisent le Skill empaqueté d'iac-code pour piloter un runtime A2A local authentifié via un script pont utilisant uniquement la bibliothèque standard, en intégrant iac-code comme capacité d'infrastructure Alibaba Cloud. Voir [Intégration Skill](./skill-integration.md). +- **Intégration Skill externe** — Des agents externes peuvent ajouter les capacités d'infrastructure Alibaba Cloud à leur workflow avec un Skill IaC Code officiel. Consultez [Skills IaC Code officiels](./skill-overview.md) pour choisir une distribution, puis [Installer et utiliser le Skill](./skill-integration.md) ou la [référence d'intégration hôte](./skill-host-integration.md). ## Comparaison des modes d'interaction diff --git a/website/i18n/fr/docusaurus-plugin-content-docs/current/a2a/skill-host-integration.md b/website/i18n/fr/docusaurus-plugin-content-docs/current/a2a/skill-host-integration.md new file mode 100644 index 00000000..a1d14fba --- /dev/null +++ b/website/i18n/fr/docusaurus-plugin-content-docs/current/a2a/skill-host-integration.md @@ -0,0 +1,138 @@ +--- +sidebar_position: 3 +title: Référence d'intégration hôte du Skill IaC Code +description: Intégrez le pont du Skill IaC Code à un agent hôte compatible. +--- + +# Référence d'intégration hôte du Skill IaC Code + +Ce document s'adresse aux développeurs d'agents et de systèmes de distribution de Skills. Les utilisateurs doivent +consulter [Installer et utiliser le Skill IaC Code](./skill-integration.md). + +## Modèle d'intégration et configuration + +Le paquet contient `SKILL.md` et le pont `scripts/iac_code.py`, fondé uniquement sur la bibliothèque standard. Exécutez +le pont avec CPython 3.8 à 3.14. Considérez stdout comme le résultat JSON stable et stderr comme les diagnostics et la +progression. Conservez `jobId`, `contextId`, le cursor et les champs de corrélation. En cas d'erreur, n'utilisez ni un +autre Runtime ni un appel direct aux API cloud. + +Le distributeur peut placer ce `config.json` à côté de `SKILL.md` : + +```json +{ + "channel": "codex", + "pipelineName": "selling_solution_first", + "permissionWaitPolicy": { + "residentTimeoutSeconds": null, + "subPipelineTimeoutSeconds": null, + "timeoutGraceSeconds": 30 + } +} +``` + +Le pont préfixe `channel` par `skill/`. `pipelineName` vaut par défaut `selling_solution_first` ; `selling` est réservé à +un besoin explicite du flux historique. `null` signifie une attente illimitée. Les champs inconnus ou invalides sont +refusés. Cette politique d'installation ne doit pas être dérivée d'une demande utilisateur, exposée ou modifiée durant +une tâche. + +## Démarrer et suivre une tâche + +Écrivez la demande complète dans un fichier UTF-8 de l'espace de travail et utilisez un chemin absolu : + +```text +python3 scripts/iac_code.py start --mode normal --cwd --prompt-file --language --follow +``` + +Utilisez `normal` par défaut et `pipeline` seulement pour le parcours de comparaison, confirmation et déploiement. +La langue peut être `en`, `zh`, `es`, `fr`, `de`, `ja`, `pt` ou `auto` ; conservez ensuite `preferredLanguage`. +`llm_not_configured` arrête avant la création et `cloud_credentials_not_configured` signale les identifiants manquants +en Pipeline. + +`--follow` retourne au prochain seuil de présentation ou d'interaction, à `turn_completed`, ou à l'état terminal d'un +Pipeline. Avec `boundaryReached: true`, affichez toutes les chaînes de `userUpdates`, puis suivez le même job : + +```text +python3 scripts/iac_code.py follow --job-id --cursor --wait-seconds 60 +``` + +`boundaryReached` n'est pas une fin. `presentationRequired` impose d'afficher la mise à jour avant l'appel suivant. +En mode normal, utilisez `finalText` et `artifacts` à `turn_completed`. Pour un Pipeline terminal, utilisez +`pipelineResult` et `artifacts` et signalez tout échec de nettoyage. Pour le diagnostic ou la reprise uniquement : + +```text +python3 scripts/iac_code.py poll --job-id --cursor --wait-seconds 5 +``` + +Si l'état est `input-required` sans `inputRequired`, signalez le dernier texte ou l'erreur et laissez le job inchangé. + +## Traiter les entrées utilisateur + +Chaque `inputRequired` est une frontière stricte : affichez-la dans l'interface native de l'hôte et attendez une réponse +explicite. Ne déduisez jamais de valeur par défaut. Conservez `kind`, `inputId`, `requestTaskId`, `contextId` et, s'il +existe, `toolUseId`. + +| `kind` | Informations à afficher | Réponse | +|---|---|---| +| `permission` | But, effet, cible, lecture seule, résumés de déploiement et sécurité, actions | `allow_once` / `deny` | +| `ask_user_question` | Question, choix et texte libre s'il est autorisé | Réponse | +| `candidate_selection` | Tous les résumés, diagrammes Mermaid, total mensuel et postes | ID ou numéro | +| `deployment_confirmation` | Solution, URL, devis, paramètres effectifs et modifiés, Preview, actions | `confirm` / `adjust` / `reselect` / `cancel` | + +Écrivez la réponse corrélée dans un nouveau fichier JSON UTF-8 et reprenez le même job : + +```text +python3 scripts/iac_code.py respond --job-id --input-file --follow +``` + +```json +{"kind":"permission","requestTaskId":"","contextId":"","inputId":"","toolUseId":"","decision":"allow_once"} +``` + +```json +{"kind":"ask_user_question","requestTaskId":"","contextId":"","inputId":"","answer":""} +``` + +```json +{"kind":"candidate_selection","requestTaskId":"","contextId":"","inputId":"","answer":""} +``` + +```json +{"kind":"deployment_confirmation","requestTaskId":"","contextId":"","inputId":"","action":"","parameterOverrides":{"":""}} +``` + +Omettez `parameterOverrides` sans ajustement. La demande initiale ou l'approbation de l'hôte ne vaut pas confirmation. + +## Continuer, annuler et reprendre + +Après un tour normal ou le passage d'un Pipeline terminé au mode normal, continuez le job existant : + +```text +python3 scripts/iac_code.py continue --job-id --prompt-file --follow +``` + +Conservez `jobId` et `contextId` ; un nouveau `taskId` est normal. Cela permet aussi de reprendre après une attente +d'autorisation ou une interruption de l'hôte. Pour tout annuler : + +```text +python3 scripts/iac_code.py cancel --job-id +``` + +Cette annulation diffère du refus d'une autorisation. + +## Erreurs et Runtime + +Une erreur avant création est définitive pour cet appel. Pour `incompatible_host`, affichez les informations de +compatibilité et arrêtez, sans basculer vers pip, un autre Runtime ou les API directes. Le Runtime est mis en cache dans +`/skill-runtime///`. Sa structure et son intégrité sont définies +par `skill-runtime/skill-package-contract.json` et le manifeste de version. Le nettoyage doit être demandé +explicitement ; les paquets courants ou actifs sont protégés. + +Le Runtime utilise un port aléatoire de `127.0.0.1` et un Bearer token propre au processus. N'exposez pas le token, +l'état local, les identifiants, l'environnement ou les entrées/sorties brutes des outils. + +## Documentation associée + +- [Présentation des Skills IaC Code officiels](./skill-overview.md) +- [Installer et utiliser le Skill IaC Code](./skill-integration.md) +- [Présentation A2A](./overview.md) +- [Référence A2A](./protocol-reference.md) diff --git a/website/i18n/fr/docusaurus-plugin-content-docs/current/a2a/skill-integration.md b/website/i18n/fr/docusaurus-plugin-content-docs/current/a2a/skill-integration.md index b110962b..f824c318 100644 --- a/website/i18n/fr/docusaurus-plugin-content-docs/current/a2a/skill-integration.md +++ b/website/i18n/fr/docusaurus-plugin-content-docs/current/a2a/skill-integration.md @@ -1,222 +1,131 @@ --- -sidebar_position: 7 +sidebar_position: 2 title: Installer et utiliser le Skill IaC Code -description: Téléchargez et installez le Skill IaC Code afin qu'un agent externe puisse gérer des ressources cloud Alibaba Cloud. +description: Ajoutez IaC Code à un agent compatible avec les Skills pour gérer l'infrastructure Alibaba Cloud. --- # Installer et utiliser le Skill IaC Code -Le Skill IaC Code s'adresse aux agents externes qui prennent en charge les Skills. Une fois installé, il permet à un -agent hôte de déléguer à IaC Code la conception d'architectures cloud, la génération et la vérification de modèles ROS -ou Terraform, l'estimation des coûts, le choix des ressources, les opérations sur les stacks et le déploiement. Le -Skill utilise un pont écrit uniquement avec la bibliothèque standard de Python pour démarrer un Runtime A2A local et -authentifié. Il n'est pas nécessaire d'installer IaC Code avec pip, et l'agent hôte ne doit pas se rabattre sur des -commandes headless. +Le Skill IaC Code permet à un agent compatible de déléguer à IaC Code la conception d'architectures cloud, la +génération et la révision de templates ROS ou Terraform, l'estimation des coûts, la sélection de ressources, les +opérations sur les stacks ROS et le déploiement. Le paquet inclut un Runtime IaC Code vérifié ; aucune installation +séparée d'IaC Code n'est nécessaire. -## Télécharger le Skill +## Télécharger -### Dernière version stable +[Télécharger le dernier iac-code-skill.zip stable](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/iac-code-skill.zip) -Téléchargez directement la dernière version stable : +Cette URL fixe désigne toujours la dernière version stable. Un installateur automatique peut lire +[latest.json](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/latest.json) +pour obtenir la version, l'URL immuable, la taille et le SHA-256, puis vérifier `skill.url` avec `skill.sha256`. -[Télécharger iac-code-skill.zip](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/iac-code-skill.zip) +## Installer -Cette URL fixe pointe toujours vers le paquet du Skill promu sur le canal stable. Elle convient au téléchargement -depuis un navigateur et à l'installation manuelle, et ne change pas à chaque nouvelle version. +Vérifiez que l'agent accepte les Skills locaux définis par `SKILL.md`, que CPython 3.8 à 3.14 est disponible et que +l'environnement peut accéder à l'URL de téléchargement. Utilisez `python3` sous macOS/Linux et `py -3` sous Windows. +Les Runtimes officiels prennent en charge macOS Apple Silicon, Linux x86_64 et Windows x86_64 ; le système et l'ABI +sont contrôlés avant le téléchargement. -Les programmes d'installation qui ont besoin de la version, de la taille du fichier, de l'empreinte SHA-256 et de -l'URL immuable propre à la version peuvent consulter les métadonnées du canal stable : - -[Consulter latest.json](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/latest.json) - -Ce document contient : - -- `skillVersion` : version stable actuelle du Skill ; -- `skill.url` : URL immuable du fichier ZIP correspondant à cette version ; -- `skill.sha256` et `skill.size` : valeurs utilisées pour vérifier le téléchargement ; -- `manifest.url` : manifeste de publication immuable correspondant à cette version. - -Pour une vérification stricte ou une installation automatisée reproductible, lisez `latest.json`, téléchargez -`skill.url`, puis vérifiez `skill.sha256`. Ne construisez pas vous-même une URL à partir du numéro de version. - -## Installer le Skill - -### Prérequis - -- L'agent hôte prend en charge les Skills locaux définis par un fichier `SKILL.md`. -- CPython 3.8 à 3.14 est installé. Utilisez `python3` sous macOS/Linux et, de préférence, `py -3` sous Windows. -- L'environnement peut accéder aux URL OSS ci-dessus afin de télécharger le fichier ZIP du Skill et le Runtime requis - lors de la première utilisation. -- La configuration du service de modèles est disponible. Une identité Alibaba Cloud avec le principe du moindre - privilège est également requise pour les tâches qui consultent ou gèrent des ressources cloud. - -Les versions officielles du Skill Runtime prennent en charge les plateformes suivantes : - -| Système d'exploitation | Architecture | -|---|---| -| macOS | Apple Silicon (arm64) | -| Linux | x86_64 | -| Windows | x86_64 | - -Les versions minimales du système d'exploitation et de la glibc sous Linux sont définies par le manifeste du Runtime -épinglé par le Skill. Le pont vérifie la compatibilité avant le téléchargement. Sur une plateforme non prise en -charge, il renvoie une erreur au lieu de télécharger un artefact destiné à une autre plateforme ou ABI. - -### Extraire le paquet dans le répertoire des Skills de l'agent hôte - -Extrayez directement le fichier ZIP à la racine des Skills de l'agent hôte. L'emplacement exact dépend du produit ; -consultez la documentation de l'agent hôte. L'arborescence finale doit être la suivante : +Décompressez le ZIP dans le répertoire de Skills indiqué par l'agent. L'archive contient déjà `iac-code/` : ```text / └── iac-code/ ├── SKILL.md - ├── agents/ - │ └── openai.yaml - └── scripts/ - └── iac_code.py + ├── agents/openai.yaml + └── scripts/iac_code.py ``` -Le fichier ZIP contient déjà le répertoire de premier niveau `iac-code/`. N'ajoutez pas un second répertoire du même -nom. Après une installation ou une mise à jour, redémarrez l'agent hôte ou ouvrez une nouvelle session afin qu'il -détecte à nouveau le Skill. +Emplacements courants : -### Vérifier l'installation +- **Codex** : `~/.agents/skills/iac-code/` pour tous les projets, ou + `/.agents/skills/iac-code/` pour un dépôt. Consultez la + [documentation Codex Skills](https://developers.openai.com/codex/skills#where-codex-loads-local-skills). +- **Claude Code** : `~/.claude/skills/iac-code/` pour tous les projets, ou + `/.claude/skills/iac-code/` pour un dépôt. Consultez la + [documentation Claude Code Skills](https://code.claude.com/docs/en/skills#where-skills-live). -Dans le répertoire `iac-code` extrait, exécutez la commande suivante sous macOS ou Linux : +Redémarrez l'agent ou ouvrez une nouvelle session. Pour vérifier le Runtime depuis le répertoire `iac-code` : ```bash python3 scripts/iac_code.py ensure-runtime ``` -Dans Windows PowerShell, exécutez : - -```powershell -py -3 scripts\iac_code.py ensure-runtime -``` - -Lors de la première exécution, cette commande télécharge le Runtime correspondant à la plateforme, vérifie sa taille -et son empreinte SHA-256, puis affiche un objet JSON contenant `skillVersion`, `runtimeTag` et le chemin -d'installation. Un Runtime déjà vérifié et mis en cache est réutilisé sans nouveau téléchargement. +Sous Windows PowerShell, utilisez `py -3 scripts\iac_code.py ensure-runtime`. Au premier lancement, le Runtime adapté +est téléchargé et sa taille ainsi que son SHA-256 sont vérifiés ; la copie locale est ensuite réutilisée. ## Configurer le modèle et l'identité Alibaba Cloud -Le Skill Runtime utilise le même répertoire de configuration que les autres modes de IaC Code : `~/.iac-code/` par -défaut. Si IaC Code est déjà configuré via le REPL, l'application Web ou l'application Desktop, le Skill peut -réutiliser ces paramètres. Définissez `IAC_CODE_CONFIG_DIR` pour employer un autre répertoire de configuration. - -Dans les environnements automatisés, fournissez les variables suivantes au moyen d'une solution de gestion des -secrets : - -| Catégorie | Variable d'environnement | Description | -|---|---|---| -| Modèle | `IAC_CODE_PROVIDER` | Fournisseur du modèle | -| Modèle | `IAC_CODE_MODEL` | Nom du modèle | -| Modèle | `IAC_CODE_API_KEY` | Clé API du service de modèles | -| Modèle | `IAC_CODE_BASE_URL` | Remplacement facultatif de l'endpoint compatible | -| Alibaba Cloud | `ALIBABA_CLOUD_ACCESS_KEY_ID` | ID de l'AccessKey | -| Alibaba Cloud | `ALIBABA_CLOUD_ACCESS_KEY_SECRET` | Secret de l'AccessKey | -| Alibaba Cloud | `ALIBABA_CLOUD_SECURITY_TOKEN` | Jeton de sécurité pour les identifiants STS | -| Alibaba Cloud | `ALIBABA_CLOUD_REGION_ID` | Région par défaut | - -Ne placez jamais d'identifiants réels dans `SKILL.md`, les prompts de l'agent hôte, les fichiers du projet ou -l'historique du shell. Privilégiez les identifiants temporaires, les rôles RAM ou OAuth, et n'accordez que les -autorisations d'API cloud nécessaires à la tâche. Pour les instructions complètes, consultez -[Fournisseurs de LLM](../configuration/llm-providers.md) et +Le Skill utilise par défaut `~/.iac-code/` et réemploie les réglages du REPL, de l'application Web ou Desktop. +`IAC_CODE_CONFIG_DIR` permet de choisir un autre répertoire. Dans les environnements automatisés, injectez les réglages +du modèle et les identifiants Alibaba Cloud avec un gestionnaire de secrets. Ne placez aucun identifiant dans +`SKILL.md`, les prompts, les fichiers du projet ou l'historique du shell. Préférez les identifiants temporaires, les +rôles RAM ou OAuth avec le minimum de droits. Consultez [Fournisseurs LLM](../configuration/llm-providers.md) et [Identifiants Alibaba Cloud](../configuration/alibaba-cloud-credentials.md). -## Première utilisation - -Après l'installation et la configuration, ouvrez une nouvelle session dans l'agent hôte et décrivez directement une -tâche d'infrastructure Alibaba Cloud. Par exemple : - -```text -Utilise iac-code pour vérifier le modèle ROS de ce projet. Répertorie les risques de sécurité et les modifications recommandées sans modifier le fichier. -``` - -Les agents hôtes qui prennent en charge une syntaxe explicite peuvent sélectionner le Skill avec `$iac-code`. -L'agent hôte lit `SKILL.md`, écrit la demande complète dans un fichier UTF-8 de l'espace de travail, puis utilise le -pont pour créer et suivre une seule tâche. L'utilisateur n'a pas besoin de démarrer manuellement un serveur A2A. +## Choisir le mode de travail -Déroulement attendu : +- Le **mode normal** est utilisé par défaut pour consulter ou modifier des ressources, travailler sur des templates, + diagnostiquer un problème et déployer une cible clairement définie. +- Le **mode Pipeline** est choisi à votre demande, ou lorsqu'un parcours guidé doit comparer des architectures et des + coûts avant la confirmation et le déploiement. -1. Le pont vérifie que la configuration du modèle et d'Alibaba Cloud est prête. -2. Lors de la première utilisation, il télécharge et vérifie le Runtime IaC Code épinglé par le Skill. -3. Le Runtime écoute uniquement sur un port aléatoire de `127.0.0.1` et génère un jeton Bearer propre au processus. -4. L'agent hôte présente la progression, les questions, les plans candidats et les demandes d'autorisation renvoyés - par IaC Code. -5. Une fois la tâche terminée, l'agent hôte renvoie le résultat final et les fichiers générés dans l'espace de travail. - -## Mettre à jour et désinstaller +Décrivez simplement le résultat attendu. Mentionnez Pipeline seulement si vous souhaitez comparer des solutions. -Pour effectuer une mise à jour manuelle, téléchargez à nouveau `skill/stable/iac-code-skill.zip` et remplacez -l'intégralité du répertoire `iac-code/` dans la racine des Skills de l'agent hôte. Un programme de mise à jour -automatique peut comparer la valeur `skillVersion` de `latest.json`, puis télécharger et vérifier le nouveau paquet à -l'aide de son URL immuable et de son empreinte SHA-256. Chaque Skill officiel est épinglé à un Runtime vérifié. Ne -remplacez pas uniquement `scripts/iac_code.py` et ne modifiez pas manuellement l'URL ou l'empreinte du Runtime. - -Pour désinstaller le Skill, supprimez `iac-code/` de la racine des Skills de l'agent hôte. Le cache du Runtime n'est -pas supprimé avec le répertoire du Skill. N'exécutez `cache list` et `cache clean` que si l'utilisateur demande -explicitement de supprimer ce cache. - -## Cache du Runtime - -Le Runtime téléchargé lors de la première utilisation est mis en cache dans -`/skill-runtime///` et réutilisé automatiquement. En usage -normal, il n'est pas nécessaire de gérer ce répertoire. Pour examiner l'espace disque utilisé ou supprimer -d'anciennes versions, utilisez : +## Première utilisation -- `python3 scripts/iac_code.py cache list` — répertorie les Runtimes installés et les paquets candidats ; -- `python3 scripts/iac_code.py cache clean [--runtime-tag ] [--candidates] --confirm` — supprime les caches du - Runtime ou les paquets candidats ; l'option `--confirm` est obligatoire. +Dans une nouvelle session de l'agent hôte, saisissez par exemple : -Le Runtime actuel et tout Runtime utilisé par un processus actif sont protégés contre le nettoyage. Le format du -paquet et les contraintes du Runtime sont définis par `skill-runtime/skill-package-contract.json` dans le dépôt -source ; les utilisateurs n'ont pas à modifier ce fichier. +```text +Utilise iac-code pour réviser le template ROS de ce projet. Liste les risques de sécurité et les améliorations sans modifier le fichier. +``` -## Résolution des problèmes +Sélectionnez explicitement le Skill avec `$iac-code` dans Codex ou `/iac-code` dans Claude Code. La vérification de la +configuration et le démarrage du Runtime sont automatiques ; aucun serveur A2A ne doit être lancé manuellement. -### La configuration est incomplète +IaC Code peut s'arrêter pour vous demander : -Le Skill vérifie la configuration avant de créer une tâche, mais ne lit ni ne renvoie jamais les valeurs secrètes : +- d'autoriser ou refuser une opération (`permission`) ; +- de répondre à une question (`ask_user_question`) ; +- de choisir une architecture (`candidate_selection`) ; +- de vérifier la solution, le prix et les paramètres, puis confirmer, ajuster, resélectionner ou annuler + (`deployment_confirmation`). -| Situation | Résultat | -|---|---| -| Le fournisseur de LLM ou la clé API est incomplet | Renvoie `llm_not_configured` et ne crée pas la tâche | -| Les identifiants Alibaba Cloud sont incomplets pour le Pipeline de vente | Renvoie `cloud_credentials_not_configured` et ne crée pas la tâche | -| Les identifiants Alibaba Cloud sont incomplets en mode normal | Les tâches qui n'appellent pas d'API cloud peuvent continuer avec un avertissement préalable | +Vérifiez les ressources, la région, l'impact et le prix avant de répondre. Une demande initiale de déploiement ne vaut +pas confirmation ultérieure. Après la fin d'une tâche, poursuivez dans la même session : le contexte IaC Code est +conservé. Les mises à jour sont disponibles en anglais, chinois simplifié, espagnol, français, allemand, japonais et +portugais. -### Pourquoi l'exécution se met en pause +## Mettre à jour et désinstaller -IaC Code se met en pause lorsqu'il attend une autorisation, une information complémentaire ou le choix d'un plan. -L'agent hôte présente directement la demande : +Pour mettre à jour, téléchargez à nouveau le ZIP stable et remplacez tout le dossier `iac-code/`, puis redémarrez +l'agent. Ne remplacez pas uniquement le pont et ne modifiez pas l'URL ou l'empreinte du Runtime. Pour désinstaller, +supprimez `iac-code/`. Les Runtimes restent en cache ; pour les supprimer, consultez d'abord `cache list`, puis lancez +`cache clean ... --confirm`. -- une demande d'autorisation pour un outil ou un déploiement (`permission`) ; -- une question à choix multiple ou une demande d'informations (`ask_user_question`) ; -- le choix d'un plan candidat du Pipeline (`candidate_selection`). +## Dépannage -Avant de confirmer, vérifiez la ressource cible, la région, l'impact prévu et le prix. L'agent hôte ne peut pas passer -outre un refus de IaC Code. Dans le protocole, une autorisation ponctuelle est représentée par `allow_once`. +- `llm_not_configured` : complétez la configuration du modèle. +- `cloud_credentials_not_configured` : configurez les identifiants requis par Pipeline. Le mode normal peut continuer + les tâches sans API cloud avec un avertissement. +- `incompatible_host` : exécutez `ensure-runtime`, puis vérifiez Python, le système, l'architecture, le réseau et le + proxy. Mettez à niveau ou changez d'hôte au lieu de contourner le contrôle. +- Tâche en pause : elle attend une réponse, une autorisation, une sélection ou une confirmation de déploiement. Si la + session existe encore après une interruption, demandez à l'agent de poursuivre la même tâche. -> **Note pour l'intégration de l'agent hôte** -> -> Lorsqu'un résultat du pont contient `inputRequired`, l'agent hôte doit présenter la demande en cours et attendre une -> réponse. `boundaryReached` indique une limite d'affichage ou d'interaction, et non la fin de la tâche ; l'agent hôte -> doit afficher la mise à jour et continuer à suivre la même tâche. +Utilisez `python3 scripts/iac_code.py cache list` pour inspecter le cache, +`cache clean --runtime-tag --confirm` pour supprimer une ancienne version et +`cache clean --candidates --confirm` pour les paquets candidats. Le Runtime courant ou actif est protégé. ## Sécurité -- Le Runtime écoute uniquement sur un port aléatoire de `127.0.0.1`. Chaque démarrage génère un nouveau jeton Bearer, - transmis avec chaque requête du pont. -- Le pont conserve les artefacts et les résultats dans l'espace de travail de la tâche. Les résultats sont enregistrés - dans `.iac-code-skill-results/`. -- Les champs affichés lors des vérifications préalables et des demandes d'autorisation sont nettoyés ; aucun secret ni - identifiant n'y apparaît. +- Le Runtime écoute uniquement sur un port aléatoire de `127.0.0.1` avec un Bearer token propre au processus. +- Les résultats restent dans l'espace de travail, notamment sous `.iac-code-skill-results/` le cas échéant. +- Les états de préparation et résumés d'autorisation n'exposent aucune valeur d'identifiant. ## Documentation associée +- [Présentation des Skills IaC Code officiels](./skill-overview.md) +- [Référence d'intégration hôte du Skill IaC Code](./skill-host-integration.md) - [Présentation du protocole A2A](./overview.md) -- [Référence du protocole A2A](./protocol-reference.md) -- [Fournisseurs de LLM](../configuration/llm-providers.md) -- [Identifiants Alibaba Cloud](../configuration/alibaba-cloud-credentials.md) - [Configuration du Runtime](../configuration/runtime-configuration.md) diff --git a/website/i18n/fr/docusaurus-plugin-content-docs/current/a2a/skill-overview.md b/website/i18n/fr/docusaurus-plugin-content-docs/current/a2a/skill-overview.md new file mode 100644 index 00000000..d5e58bf9 --- /dev/null +++ b/website/i18n/fr/docusaurus-plugin-content-docs/current/a2a/skill-overview.md @@ -0,0 +1,69 @@ +--- +sidebar_position: 1 +title: Présentation des Skills IaC Code officiels +description: Comparez les Skills IaC Code officiels et choisissez la distribution adaptée. +--- + +# Présentation des Skills IaC Code officiels + +IaC Code existe sous trois distributions Skill officielles. Toutes permettent de gérer l'infrastructure Alibaba Cloud +depuis un agent, mais diffèrent par leur canal de distribution et le lieu d'exécution de l'Agent IaC Code. + +## Choisir un Skill + +| Skill | Lieu d'exécution | À choisir lorsque | +|---|---|---| +| `iac-code` | Runtime IaC Code vérifié téléchargé sur votre machine | Vous souhaitez le paquet autonome du projet iac-code et gérer vous-même installation et mises à jour. | +| `alibabacloud-iac-code` | Même Runtime local, empaqueté pour le portail Alibaba Cloud Agent Skills | Vous gérez les Skills Alibaba Cloud via le portail ou `npx skills`. | +| `alibabacloud-ros-agent` | Agent ROS hébergé par Alibaba Cloud, appelé avec l'API ROS StartChat | Vous souhaitez une conversation distante sans télécharger le Runtime IaC Code local. | + +`iac-code` et `alibabacloud-iac-code` fournissent la même capacité IaC Code. Choisissez une seule distribution dans un +même périmètre d'agent : les installer ensemble ajoute des règles de déclenchement concurrentes, pas des fonctions. + +`alibabacloud-ros-agent` est une intégration distante distincte. Elle peut coexister avec une distribution locale si +l'utilisateur doit choisir explicitement entre IaC Code local et l'Agent ROS hébergé. + +## Obtenir le Skill autonome + +[Télécharger iac-code-skill.zip stable](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/iac-code-skill.zip) + +Cette distribution convient à une installation manuelle. Elle télécharge le Runtime au premier usage et réemploie la +configuration du modèle et d'Alibaba Cloud sous `~/.iac-code/`. Consultez +[Installer et utiliser le Skill IaC Code](./skill-integration.md). + +## Obtenir les Skills du portail Alibaba Cloud + +Recherchez leur nom exact sur le [portail Alibaba Cloud Agent Skills](https://skills.aliyun.com/) ou installez-les depuis +le dépôt officiel : + +```bash +npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-iac-code +npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-ros-agent +``` + +Téléchargements directs : + +- [`alibabacloud-iac-code` ZIP](https://skills.aliyun.com/api/public/skills/alibabacloud-iac-code/download) · [source](https://github.com/aliyun/alibabacloud-aiops-skills/tree/master/skills/developertools/ros/alibabacloud-iac-code) +- [`alibabacloud-ros-agent` ZIP](https://skills.aliyun.com/api/public/skills/alibabacloud-ros-agent/download) · [source](https://github.com/aliyun/alibabacloud-aiops-skills/tree/master/skills/developertools/ros/alibabacloud-ros-agent) + +`npx skills` nécessite Node.js 18 ou version ultérieure et permet de choisir l'agent et la portée d'installation. Pour +un ZIP, extrayez le dossier Skill racine dans le répertoire utilisateur ou projet accepté par l'agent. + +## Différences de capacité et de configuration + +Les deux distributions locales prennent en charge les conversations normales et Pipeline, l'architecture, les +templates ROS/Terraform, les coûts, les stacks, le déploiement et les confirmations. Elles nécessitent un modèle +configuré, ainsi que des identifiants Alibaba Cloud lorsque la tâche consulte ou modifie des ressources. + +`alibabacloud-ros-agent` utilise `ros:StartChat` pour joindre l'Agent ROS Alibaba Cloud. Il ne nécessite ni Runtime IaC +Code ni fournisseur de modèle local, mais utilise l'identité Alibaba Cloud du host. N'accordez que les droits RAM +nécessaires ; une annulation distante explicite emploie aussi `ros:StopChat`. + +Dans tous les cas, contrôlez les ressources, la région, l'impact, le prix et les autorisations avant d'approuver. Ne +placez aucun identifiant dans `SKILL.md`, les prompts ou le projet. + +## Documentation associée + +- [Installer et utiliser le Skill IaC Code](./skill-integration.md) +- [Référence d'intégration hôte](./skill-host-integration.md) +- [Identifiants Alibaba Cloud](../configuration/alibaba-cloud-credentials.md) diff --git a/website/i18n/fr/docusaurus-plugin-content-docs/current/intro.md b/website/i18n/fr/docusaurus-plugin-content-docs/current/intro.md index 6c4b7d3e..ed5578d4 100644 --- a/website/i18n/fr/docusaurus-plugin-content-docs/current/intro.md +++ b/website/i18n/fr/docusaurus-plugin-content-docs/current/intro.md @@ -6,7 +6,7 @@ description: Ce que fait IaC Code et par où commencer. # Présentation -IaC Code est un assistant d'Infrastructure as Code alimenté par l'IA pour l'infrastructure cloud. Il aide les utilisateurs et opérateurs de ressources cloud à générer, déployer et gérer des templates d'infrastructure via un flux de travail en terminal. Son architecture est conçue pour des workflows multicloud ; la version actuelle prend en charge les workflows Alibaba Cloud ROS et Terraform. +IaC Code est un assistant IA pour concevoir, générer, déployer et gérer l'infrastructure cloud. Il s'utilise depuis l'application Desktop, l'application Web locale, le terminal interactif, les interfaces d'automatisation ou comme Skill d'un autre agent. Son architecture est conçue pour des workflows multicloud ; la version actuelle prend en charge Alibaba Cloud ROS et Terraform. Capacités principales : @@ -14,4 +14,11 @@ Capacités principales : - **Du template à l'infrastructure** -- pour Alibaba Cloud ROS, passez du template à l'infrastructure en cours d'exécution ; créez, mettez à jour, supprimez et surveillez les stacks dans toutes les régions. La prise en charge de Terraform couvre la génération et la conversion de templates, pas le déploiement. - **Intelligence cloud intégrée** -- recherchez dans la documentation, vérifiez la disponibilité des ressources et estimez les coûts avant de déployer ; chaque décision est étayée par des données cloud réelles. -La documentation est organisée autour des tâches utilisateur. Commencez par l'installation et le démarrage rapide, puis configurez les fournisseurs et les identifiants, puis utilisez la référence CLI lorsque vous avez besoin de détails sur les commandes. +Choisissez le point de départ adapté : + +- Téléchargez l'[application Desktop](./desktop-app.md) pour une interface graphique prête à l'emploi. +- Suivez l'[installation](./getting-started/installation.md) et le [démarrage rapide](./getting-started/quick-start.md) pour utiliser le REPL, le mode headless ou l'[application Web](./web-app.md) locale. +- Choisissez une distribution dans la [présentation des Skills IaC Code officiels](./a2a/skill-overview.md) pour ajouter ses capacités Alibaba Cloud à un agent compatible. +- Utilisez [ACP](./acp/overview.md), [A2A](./a2a/overview.md) ou [AG-UI](./agui/overview.md) pour intégrer IaC Code à une application ou un service. + +Tous les points d'entrée nécessitent un modèle configuré. Configurez aussi les [identifiants Alibaba Cloud](./configuration/alibaba-cloud-credentials.md) pour consulter, modifier ou déployer des ressources. diff --git a/website/i18n/ja/docusaurus-plugin-content-docs/current.json b/website/i18n/ja/docusaurus-plugin-content-docs/current.json index 34e1ef9d..7b0d24f0 100644 --- a/website/i18n/ja/docusaurus-plugin-content-docs/current.json +++ b/website/i18n/ja/docusaurus-plugin-content-docs/current.json @@ -11,6 +11,10 @@ "message": "IaC Code の使い方", "description": "The label for category 'Using iac-code' in sidebar 'docsSidebar'" }, + "sidebar.docsSidebar.category.IaC Code Skill": { + "message": "IaC Code Skill", + "description": "The label for category 'IaC Code Skill' in sidebar 'docsSidebar'" + }, "sidebar.docsSidebar.category.MCP Integration": { "message": "MCP 連携", "description": "The label for category 'MCP Integration' in sidebar 'docsSidebar'" diff --git a/website/i18n/ja/docusaurus-plugin-content-docs/current/a2a/overview.md b/website/i18n/ja/docusaurus-plugin-content-docs/current/a2a/overview.md index e88fdf0b..f4c17732 100644 --- a/website/i18n/ja/docusaurus-plugin-content-docs/current/a2a/overview.md +++ b/website/i18n/ja/docusaurus-plugin-content-docs/current/a2a/overview.md @@ -22,7 +22,7 @@ iac-code は A2A 1.0 Server / Agent として実行できます。他の A2A 互 - **ワークフロー自動化** — 内部ツールは IaC の生成、レビュー、変換タスクを HTTP 経由で送信できます。 - **サービスディスカバリー** — クライアントは Agent Card を取得し、IaC 生成やテンプレートレビューなどの機能を選択できます。 - **ストリーミング統合** — chatops やダッシュボードクライアントは、ターンの実行中にモデルテキスト、ツールアクティビティ、使用量メタデータ、最終タスク状態を表示できます。 -- **外部 Skill 統合** — 外部エージェントがパッケージ化された iac-code Skill を使い、標準ライブラリのみで書かれたブリッジスクリプト経由でローカルの認証済み A2A runtime を駆動して、iac-code を Alibaba Cloud インフラ機能として組み込みます。詳細は [Skill 統合](./skill-integration.md) を参照してください。 +- **外部 Skill 統合** — 外部エージェントは公式 IaC Code Skill を利用して、Alibaba Cloud インフラストラクチャ機能をワークフローに追加できます。配布方法は[公式 IaC Code Skills](./skill-overview.md)で選択し、[IaC Code Skill のインストールと使用](./skill-integration.md)または[ホスト統合リファレンス](./skill-host-integration.md)を参照してください。 ## インタラクションモードの比較 diff --git a/website/i18n/ja/docusaurus-plugin-content-docs/current/a2a/skill-host-integration.md b/website/i18n/ja/docusaurus-plugin-content-docs/current/a2a/skill-host-integration.md new file mode 100644 index 00000000..3f033bcc --- /dev/null +++ b/website/i18n/ja/docusaurus-plugin-content-docs/current/a2a/skill-host-integration.md @@ -0,0 +1,129 @@ +--- +sidebar_position: 3 +title: IaC Code Skill ホスト統合リファレンス +description: Skill 対応ホストエージェントに IaC Code ブリッジを統合します。 +--- + +# IaC Code Skill ホスト統合リファレンス + +本書はエージェントおよび Skill 配布システムの開発者向けです。通常の利用者は +[IaC Code Skill のインストールと使用](./skill-integration.md)を参照してください。 + +## 統合モデルと設定 + +パッケージには `SKILL.md` と標準ライブラリだけで動く `scripts/iac_code.py` が含まれます。ホストは +CPython 3.8～3.14 でブリッジを実行し、stdout を安定した JSON、stderr を診断・進捗として扱います。 +`jobId`、`contextId`、cursor、入力相関フィールドを保持し、エラー時に別 Runtime や直接クラウド API へ +フォールバックしてはいけません。 + +配布者は `SKILL.md` の隣に次の `config.json` を配置できます。 + +```json +{ + "channel": "codex", + "pipelineName": "selling_solution_first", + "permissionWaitPolicy": { + "residentTimeoutSeconds": null, + "subPipelineTimeoutSeconds": null, + "timeoutGraceSeconds": 30 + } +} +``` + +`channel` には `skill/` が付加されます。`pipelineName` の既定値は `selling_solution_first`、`selling` は +明示的な旧フロー用です。待機ポリシーの `null` は無期限です。未知・不正な値は拒否されます。この設定を +ユーザー依頼から生成、公開、またはタスク中に変更しないでください。 + +## ジョブの開始と追跡 + +完全な依頼を UTF-8 ファイルに書き、絶対ワークスペースで開始します。 + +```text +python3 scripts/iac_code.py start --mode normal --cwd --prompt-file --language --follow +``` + +既定は `normal`、比較・確認・デプロイの案内が必要な場合だけ `pipeline` です。言語は `en`、`zh`、`es`、 +`fr`、`de`、`ja`、`pt`、`auto` から選び、返された `preferredLanguage` を保持します。 +`llm_not_configured` は作成前に停止し、Pipeline の認証情報不足は `cloud_credentials_not_configured` です。 + +`--follow` は表示・対話境界、`turn_completed`、Pipeline 終端で返ります。`boundaryReached: true` なら +`userUpdates` をすべて表示し、同じ cursor から続けます。 + +```text +python3 scripts/iac_code.py follow --job-id --cursor --wait-seconds 60 +``` + +`boundaryReached` は完了ではなく、`presentationRequired` は次の呼び出し前に表示が必要という意味です。 +通常モードは `finalText` と `artifacts`、Pipeline 終端は `pipelineResult` と `artifacts` を正式結果にします。 +診断・復旧時だけ次を使用します。 + +```text +python3 scripts/iac_code.py poll --job-id --cursor --wait-seconds 5 +``` + +`state: input-required` なのに `inputRequired` がない場合は最新情報を報告し、ジョブを変更しません。 + +## ユーザー入力 + +各 `inputRequired` を厳格な対話境界として表示し、明示回答を待ちます。`kind`、`inputId`、 +`requestTaskId`、`contextId`、存在する `toolUseId` を保持します。 + +| `kind` | ホストが表示する情報 | 応答 | +|---|---|---| +| `permission` | 目的、影響、対象、読み取り専用、デプロイ・安全概要、選択肢 | `allow_once` / `deny` | +| `ask_user_question` | 質問、選択肢、許可された自由入力 | 回答 | +| `candidate_selection` | 全候補、Mermaid 図、月額と内訳 | 候補 ID / 番号 | +| `deployment_confirmation` | 案、URL、見積もり、実効値、上書き、Preview、選択肢 | `confirm` / `adjust` / `reselect` / `cancel` | + +相関フィールドを含む新しい UTF-8 JSON ファイルで同じジョブを再開します。 + +```text +python3 scripts/iac_code.py respond --job-id --input-file --follow +``` + +```json +{"kind":"permission","requestTaskId":"","contextId":"","inputId":"","toolUseId":"","decision":"allow_once"} +``` + +```json +{"kind":"ask_user_question","requestTaskId":"","contextId":"","inputId":"","answer":""} +``` + +```json +{"kind":"candidate_selection","requestTaskId":"","contextId":"","inputId":"","answer":""} +``` + +```json +{"kind":"deployment_confirmation","requestTaskId":"","contextId":"","inputId":"","action":"","parameterOverrides":{"":""}} +``` + +調整しない場合は `parameterOverrides` を省略します。元のデプロイ依頼やホスト承認から回答を推定しません。 + +## 継続、キャンセル、復旧 + +通常ターン完了後、または Pipeline から通常モードへ移行した後は、同じジョブを続けます。 + +```text +python3 scripts/iac_code.py continue --job-id --prompt-file --follow +``` + +同じ `jobId` と `contextId` を保持し、新しい `taskId` を受け入れます。これにより権限待ちやホスト中断から +復旧できます。全体のキャンセルは `python3 scripts/iac_code.py cancel --job-id ` で行います。 + +## エラーと Runtime + +作成前のエラーは正式な結果です。`incompatible_host` の互換性情報を表示して停止し、pip、別 Runtime、 +直接 API に切り替えません。Runtime は +`/skill-runtime///` にキャッシュされ、構成と整合性は +`skill-runtime/skill-package-contract.json` とリリースマニフェストで検証されます。削除はユーザーが +明示した場合だけ行います。 + +Runtime はランダムな `127.0.0.1` ポートとプロセス専用 Bearer token を使います。token、ローカル状態、 +認証情報、環境値、未加工のツール入出力を公開しないでください。 + +## 関連ドキュメント + +- [IaC Code 公式 Skills の概要](./skill-overview.md) +- [IaC Code Skill のインストールと使用](./skill-integration.md) +- [A2A プロトコル概要](./overview.md) +- [A2A プロトコルリファレンス](./protocol-reference.md) diff --git a/website/i18n/ja/docusaurus-plugin-content-docs/current/a2a/skill-integration.md b/website/i18n/ja/docusaurus-plugin-content-docs/current/a2a/skill-integration.md index 5ccabfd5..bb6877ad 100644 --- a/website/i18n/ja/docusaurus-plugin-content-docs/current/a2a/skill-integration.md +++ b/website/i18n/ja/docusaurus-plugin-content-docs/current/a2a/skill-integration.md @@ -1,175 +1,116 @@ --- -sidebar_position: 7 +sidebar_position: 2 title: IaC Code Skill のインストールと使用 -description: IaC Code Skill をダウンロードしてインストールし、外部エージェントから Alibaba Cloud インフラストラクチャを管理します。 +description: Skill 対応エージェントに IaC Code を追加し、Alibaba Cloud インフラを管理します。 --- # IaC Code Skill のインストールと使用 -IaC Code Skill は、Skill に対応する外部エージェント向けです。インストールすると、ホストエージェントはクラウドアーキテクチャの設計、ROS または Terraform テンプレートの生成とレビュー、コスト見積もり、リソース選択、スタック操作、デプロイを IaC Code に委任できます。Skill は Python 標準ライブラリだけで構成されたブリッジを使い、ローカルで認証された A2A Runtime を起動します。IaC Code を pip でインストールする必要はなく、Headless コマンドにフォールバックすることもありません。 +IaC Code Skill を使うと、対応エージェントからクラウド構成の設計、ROS/Terraform テンプレートの生成・ +レビュー、料金見積もり、既存リソースの選択、ROS スタック操作、デプロイを IaC Code に委任できます。 +検証済み Runtime が含まれるため、IaC Code を別途インストールする必要はありません。 -## Skill のダウンロード +## ダウンロード -### 最新の安定版 +[最新の iac-code-skill.zip をダウンロード](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/iac-code-skill.zip) -最新の安定版を直接ダウンロードします。 +この固定 URL は常に最新の安定版を指します。自動インストーラーは +[latest.json](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/latest.json) +からバージョン、不変 URL、サイズ、SHA-256 を取得し、`skill.url` と `skill.sha256` を使って検証できます。 -[iac-code-skill.zip をダウンロード](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/iac-code-skill.zip) +## インストール -この固定 URL は、stable チャンネルに昇格された Skill パッケージを常に指します。ブラウザーからのダウンロードや手動インストールに利用でき、新しいバージョンが公開されても URL は変わりません。 +エージェントが `SKILL.md` 形式のローカル Skill に対応し、CPython 3.8～3.14 が使えることを確認します。 +macOS/Linux は `python3`、Windows は `py -3` を使います。公式 Runtime は Apple Silicon macOS、 +Linux x86_64、Windows x86_64 に対応し、ダウンロード前に OS と ABI を検証します。 -バージョン、ファイルサイズ、SHA-256、変更されないバージョン別 URL が必要なインストーラーは、stable チャンネルのメタデータを参照できます。 - -[latest.json を表示](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/latest.json) - -このファイルには次の情報が含まれます。 - -- `skillVersion`：現在の安定版 Skill のバージョン。 -- `skill.url`：そのバージョンに固定された ZIP の URL。 -- `skill.sha256` と `skill.size`：ダウンロードの検証に使う値。 -- `manifest.url`：そのバージョンに固定されたリリースマニフェスト。 - -厳密な検証や再現可能な自動インストールが必要な場合は、`latest.json` を読み取り、`skill.url` からダウンロードして `skill.sha256` を検証してください。バージョン URL を独自に組み立てないでください。 - -## Skill のインストール - -### 前提条件 - -- ホストエージェントが `SKILL.md` で定義されたローカル Skill に対応していること。 -- CPython 3.8～3.14 がインストールされていること。macOS/Linux では `python3`、Windows では `py -3` の使用を推奨します。 -- 上記 OSS URL にアクセスでき、Skill ZIP と初回実行時に必要な Runtime をダウンロードできること。 -- モデルサービスが設定済みであること。クラウドリソースを照会または管理する場合は、最小権限の Alibaba Cloud ID も必要です。 - -公式 Skill Runtime は次のプラットフォームをサポートします。 - -| OS | アーキテクチャ | -|---|---| -| macOS | Apple Silicon（arm64） | -| Linux | x86_64 | -| Windows | x86_64 | - -最低 OS バージョンと Linux の glibc バージョンは、Skill に固定された Runtime manifest で定義されます。ブリッジはダウンロード前に互換性を確認します。未対応の環境では、別のプラットフォームや ABI の成果物をダウンロードせず、エラーを返します。 - -### ホストエージェントの Skill ディレクトリに展開する - -ZIP をホストエージェントの Skill ルートへ直接展開します。Skill ルートは製品ごとに異なるため、ホスト製品のドキュメントを参照してください。最終的な構成は次のようになります。 +ZIP をエージェント指定の Skill ディレクトリに展開します。アーカイブには最上位の `iac-code/` が含まれます。 ```text -/ +/ └── iac-code/ ├── SKILL.md - ├── agents/ - │ └── openai.yaml - └── scripts/ - └── iac_code.py + ├── agents/openai.yaml + └── scripts/iac_code.py ``` -ZIP には最上位の `iac-code/` ディレクトリがすでに含まれています。同名のディレクトリを重ねて作成しないでください。インストールまたは更新後、ホストエージェントを再起動するか新しいセッションを開き、Skill を再検出させます。 +主なホストの配置先: -### インストールを確認する +- **Codex**: 全プロジェクトでは `~/.agents/skills/iac-code/`、単一リポジトリでは + `/.agents/skills/iac-code/`。詳細は [Codex Skills ドキュメント](https://developers.openai.com/codex/skills#where-codex-loads-local-skills)を参照してください。 +- **Claude Code**: 全プロジェクトでは `~/.claude/skills/iac-code/`、単一リポジトリでは + `/.claude/skills/iac-code/`。詳細は [Claude Code Skills ドキュメント](https://code.claude.com/docs/en/skills#where-skills-live)を参照してください。 -展開した `iac-code` ディレクトリで、macOS または Linux では次を実行します。 +エージェントを再起動するか新しいセッションを開きます。事前確認は展開先で実行します。 ```bash python3 scripts/iac_code.py ensure-runtime ``` -Windows PowerShell では次を実行します。 - -```powershell -py -3 scripts\iac_code.py ensure-runtime -``` - -初回実行時に現在のプラットフォーム用 Runtime をダウンロードし、サイズと SHA-256 を検証したうえで、`skillVersion`、`runtimeTag`、インストール先を含む JSON を出力します。検証済みの Runtime がキャッシュにあれば再利用し、再ダウンロードしません。 +Windows PowerShell では `py -3 scripts\iac_code.py ensure-runtime` を使います。初回はプラットフォーム向け +Runtime のサイズと SHA-256 を検証し、以後は検証済みコピーを再利用します。 ## モデルと Alibaba Cloud ID の設定 -Skill Runtime は、他の IaC Code 実行モードと同じ設定ディレクトリを使用します。既定は `~/.iac-code/` です。REPL、Web、Desktop のいずれかで IaC Code を設定済みであれば、その設定を再利用できます。別の設定ディレクトリを使う場合は `IAC_CODE_CONFIG_DIR` を指定します。 +Skill は既定で `~/.iac-code/` を使い、REPL、Web、Desktop アプリの既存設定を再利用します。別の場所は +`IAC_CODE_CONFIG_DIR` で指定できます。自動化では認証情報をシークレット管理から注入し、`SKILL.md`、 +プロンプト、プロジェクト、シェル履歴に書かないでください。一時認証情報、RAM ロール、OAuth と最小権限を +推奨します。詳細は [LLM プロバイダー](../configuration/llm-providers.md)と +[Alibaba Cloud 認証情報](../configuration/alibaba-cloud-credentials.md)を参照してください。 -自動化環境では、Secret 管理機能を使って次の環境変数を提供します。 +## 動作モード -| 分類 | 環境変数 | 説明 | -|---|---|---| -| モデル | `IAC_CODE_PROVIDER` | モデルプロバイダー | -| モデル | `IAC_CODE_MODEL` | モデル名 | -| モデル | `IAC_CODE_API_KEY` | モデルサービスの API Key | -| モデル | `IAC_CODE_BASE_URL` | 任意の互換エンドポイント上書き | -| Alibaba Cloud | `ALIBABA_CLOUD_ACCESS_KEY_ID` | AccessKey ID | -| Alibaba Cloud | `ALIBABA_CLOUD_ACCESS_KEY_SECRET` | AccessKey Secret | -| Alibaba Cloud | `ALIBABA_CLOUD_SECURITY_TOKEN` | STS 認証情報の Security Token | -| Alibaba Cloud | `ALIBABA_CLOUD_REGION_ID` | 既定のリージョン | +- **通常モード**は、リソース照会・変更、テンプレート作業、トラブルシューティング、対象が明確なデプロイの既定です。 +- **Pipeline モード**は、明示的に指定した場合、または候補構成、料金比較、確認、デプロイまでの案内が必要な場合に使います。 -実際の認証情報を `SKILL.md`、ホストエージェントのプロンプト、プロジェクトファイル、シェル履歴に記録しないでください。一時認証情報、RAM Role、OAuth を優先し、タスクに必要なクラウド API 権限だけを付与します。詳しくは [LLM プロバイダー](../configuration/llm-providers.md) と [Alibaba Cloud 認証情報](../configuration/alibaba-cloud-credentials.md)を参照してください。 +通常は目的をそのまま記述し、比較フローが必要な場合だけ Pipeline を指定します。 -## 最初の利用 +## 最初のタスク -インストールと設定が完了したら、ホストエージェントで新しいセッションを開き、Alibaba Cloud インフラストラクチャのタスクをそのまま記述します。例： +ホストエージェントの新しいセッションで、例えば次のように依頼します。 ```text -iac-code を使用して、このプロジェクトの ROS テンプレートをレビューしてください。ファイルは変更せず、セキュリティリスクと修正案を一覧にしてください。 +iac-code を使って、このプロジェクトの ROS テンプレートをレビューしてください。ファイルは変更せず、セキュリティリスクと改善案を示してください。 ``` -明示的な Skill 構文に対応するホストでは、`$iac-code` でこの Skill を選択できます。ホストエージェントは `SKILL.md` を読み取り、完全なリクエストをワークスペース内の UTF-8 ファイルに書き込み、ブリッジを使って同じタスクを作成して追跡します。ユーザーが A2A Server を手動で起動する必要はありません。 +Codex では `$iac-code`、Claude Code では `/iac-code` で Skill を明示選択できます。設定確認と Runtime 起動は自動で行われ、A2A Server +を手動起動する必要はありません。IaC Code は次の入力を待って一時停止することがあります。 -想定される流れ： +- 操作の許可・拒否（`permission`） +- 質問への回答（`ask_user_question`） +- 候補構成の選択（`candidate_selection`） +- 最終案、料金、パラメーターを確認して確定、調整、再選択、キャンセル（`deployment_confirmation`） -1. ブリッジがモデルと Alibaba Cloud の設定状態を確認します。 -2. 初回実行時に、Skill に固定された IaC Code Runtime をダウンロードして検証します。 -3. Runtime は `127.0.0.1` のランダムなポートだけで待ち受け、プロセス固有の Bearer Token を生成します。 -4. ホストエージェントが、IaC Code から返された進捗、質問、候補プラン、権限リクエストを表示します。 -5. タスクが完了すると、ホストエージェントが最終結果とワークスペースで生成されたファイルを返します。 +対象、リージョン、影響、見積額を確認して回答してください。最初のデプロイ依頼は後の確認を事前承認しません。 +完了後は同じセッションで会話を続けられます。進捗と質問は英語、簡体字中国語、スペイン語、フランス語、 +ドイツ語、日本語、ポルトガル語に対応します。 ## 更新とアンインストール -手動で更新する場合は `skill/stable/iac-code-skill.zip` を再度ダウンロードし、ホストの Skill ルートにある `iac-code/` ディレクトリ全体を置き換えます。自動更新では `latest.json` の `skillVersion` を比較し、変更されない URL と SHA-256 を使って新しいパッケージをダウンロード、検証できます。公式 Skill はそれぞれ検証済み Runtime に固定されています。`scripts/iac_code.py` だけを置き換えたり、Runtime URL やダイジェストを手動で変更したりしないでください。 - -アンインストールするには、ホストエージェントの Skill ルートから `iac-code/` を削除します。Runtime キャッシュは Skill ディレクトリと一緒には削除されません。ユーザーが明示的に削除を求めた場合にだけ `cache list` と `cache clean` を実行してください。 - -## Runtime キャッシュ - -初回利用時にダウンロードされた Runtime は `/skill-runtime///` にキャッシュされ、その後は自動的に再利用されます。通常はこのディレクトリを管理する必要はありません。ディスク使用量の確認や過去バージョンの削除には次を使用します。 - -- `python3 scripts/iac_code.py cache list` — インストール済み Runtime と Candidate パッケージを表示します。 -- `python3 scripts/iac_code.py cache clean [--runtime-tag ] [--candidates] --confirm` — Runtime キャッシュまたは Candidate パッケージを削除します。`--confirm` が必須です。 - -現在使用中の Runtime と実行中プロセスが使用している Runtime は削除から保護されます。パッケージ形式と Runtime の制約は、ソースリポジトリの `skill-runtime/skill-package-contract.json` で定義されます。通常のユーザーがこのファイルを操作する必要はありません。 +更新では安定版 ZIP を再ダウンロードし、`iac-code/` 全体を置き換えてホストを再起動します。ブリッジだけの +差し替えや Runtime URL の編集は行わないでください。アンインストールでは `iac-code/` を削除します。 +Runtime も削除する場合は `cache list` を確認してから `cache clean ... --confirm` を実行します。 ## トラブルシューティング -### 設定が不完全と表示される - -Skill はタスク作成前に設定を確認しますが、Secret の値を読み取ったり返したりしません。 - -| 状況 | 結果 | -|---|---| -| LLM プロバイダーまたは API Key が不完全 | `llm_not_configured` を返し、タスクを作成しません | -| selling Pipeline で Alibaba Cloud 認証情報が不完全 | `cloud_credentials_not_configured` を返し、タスクを作成しません | -| normal モードで Alibaba Cloud 認証情報が不完全 | クラウド API を呼び出さないタスクは、事前確認の警告付きで続行できる場合があります | - -### 実行中に一時停止する理由 - -IaC Code は権限の確認、追加情報、プラン選択が必要になると一時停止し、ホストエージェントが要求をユーザーに表示します。 - -- ツールまたはデプロイの権限リクエスト（`permission`）。 -- 選択式の質問または追加情報の要求（`ask_user_question`）。 -- Pipeline の候補プラン選択（`candidate_selection`）。 - -確認前に、対象リソース、リージョン、想定される影響、価格を確認してください。ホストエージェントは IaC Code の拒否を上書きできません。1 回限りの許可はプロトコル上 `allow_once` として表されます。 +- `llm_not_configured`: モデル設定を完了してください。 +- `cloud_credentials_not_configured`: Pipeline に必要な Alibaba Cloud 認証情報を設定してください。通常モードではクラウド API 不要の作業を警告付きで続行できます。 +- `incompatible_host`: `ensure-runtime` で Python、OS、アーキテクチャ、ネットワーク、プロキシを確認し、対応ホストへ更新または移行してください。 +- タスクの一時停止: 質問、権限、候補、デプロイ確認を待つ正常な状態です。中断後もセッションが残る場合は同じタスクを続行します。 -> **ホストエージェントの統合に関する注意** -> -> ブリッジ結果に `inputRequired` が含まれる場合、ホストエージェントは現在の要求を表示し、応答を待つ必要があります。`boundaryReached` は表示または対話の境界に到達したことを示すだけで、タスクの完了を意味しません。ホストは更新を表示して、同じタスクの追跡を続けます。 +Runtime の確認には `python3 scripts/iac_code.py cache list`、過去版の削除には +`python3 scripts/iac_code.py cache clean --runtime-tag --confirm`、Candidate の削除には +`python3 scripts/iac_code.py cache clean --candidates --confirm` を使います。現在・実行中の Runtime は保護されます。 ## セキュリティ -- Runtime は `127.0.0.1` のランダムなポートだけで待ち受けます。起動ごとに新しい Bearer Token を生成し、すべてのブリッジリクエストに付与します。 -- ブリッジは成果物と結果をジョブのワークスペース内に保持します。結果は `.iac-code-skill-results/` に書き込まれます。 -- 事前確認と権限表示のフィールドはサニタイズされ、Secret や認証情報は表示されません。 +- Runtime はランダムな `127.0.0.1` ポートとプロセスごとの Bearer token を使います。 +- 成果物はワークスペース（必要に応じて `.iac-code-skill-results/`）に保存されます。 +- 準備状態と権限の表示には認証情報の値を含みません。 ## 関連ドキュメント +- [IaC Code 公式 Skills の概要](./skill-overview.md) +- [IaC Code Skill ホスト統合リファレンス](./skill-host-integration.md) - [A2A プロトコル概要](./overview.md) -- [A2A プロトコルリファレンス](./protocol-reference.md) -- [LLM プロバイダー](../configuration/llm-providers.md) -- [Alibaba Cloud 認証情報](../configuration/alibaba-cloud-credentials.md) - [Runtime 設定](../configuration/runtime-configuration.md) diff --git a/website/i18n/ja/docusaurus-plugin-content-docs/current/a2a/skill-overview.md b/website/i18n/ja/docusaurus-plugin-content-docs/current/a2a/skill-overview.md new file mode 100644 index 00000000..a6fa43f6 --- /dev/null +++ b/website/i18n/ja/docusaurus-plugin-content-docs/current/a2a/skill-overview.md @@ -0,0 +1,69 @@ +--- +sidebar_position: 1 +title: IaC Code 公式 Skills の概要 +description: 公式 IaC Code Skills を比較し、用途に合う配布方法を選びます。 +--- + +# IaC Code 公式 Skills の概要 + +IaC Code には 3 種類の公式 Skill 配布があります。いずれもエージェントとの会話から Alibaba Cloud +インフラを管理できますが、配布元と IaC Code Agent の実行場所が異なります。 + +## Skill を選ぶ + +| Skill | 実行場所 | 適した用途 | +|---|---|---| +| `iac-code` | マシンにダウンロードされる検証済み IaC Code Runtime | iac-code プロジェクトの単体パッケージを使い、インストールと更新を自分で管理する。 | +| `alibabacloud-iac-code` | Alibaba Cloud Agent Skills ポータル向けにパッケージされた同じローカル Runtime | ポータルまたは `npx skills` で Alibaba Cloud Skills を管理する。 | +| `alibabacloud-ros-agent` | ROS StartChat API 経由で利用する Alibaba Cloud のホステッド ROS Agent | ローカル Runtime をダウンロードせず、リモート ROS Agent を利用する。 | + +`iac-code` と `alibabacloud-iac-code` の機能は同じです。同じエージェントスコープではどちらか一方を +選んでください。両方を入れても機能は増えず、ルーティングが重複します。 + +`alibabacloud-ros-agent` は別のリモートサービス統合です。ローカル IaC Code とホステッド ROS Agent を +明示的に使い分ける場合は、ローカル版の一つと共存できます。 + +## 単体 Skill の入手 + +[安定版 iac-code-skill.zip をダウンロード](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/iac-code-skill.zip) + +この版は Skill ディレクトリを自分で管理する場合に適しています。初回に Runtime を取得し、 +`~/.iac-code/` のモデルと Alibaba Cloud 設定を再利用します。詳細は +[IaC Code Skill のインストールと使用](./skill-integration.md)を参照してください。 + +## Alibaba Cloud ポータル版の入手 + +[Alibaba Cloud Agent Skills ポータル](https://skills.aliyun.com/)で正確な名前を検索するか、公式リポジトリから +インストールします。 + +```bash +npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-iac-code +npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-ros-agent +``` + +直接ダウンロードもできます。 + +- [`alibabacloud-iac-code` ZIP](https://skills.aliyun.com/api/public/skills/alibabacloud-iac-code/download) · [ソース](https://github.com/aliyun/alibabacloud-aiops-skills/tree/master/skills/developertools/ros/alibabacloud-iac-code) +- [`alibabacloud-ros-agent` ZIP](https://skills.aliyun.com/api/public/skills/alibabacloud-ros-agent/download) · [ソース](https://github.com/aliyun/alibabacloud-aiops-skills/tree/master/skills/developertools/ros/alibabacloud-ros-agent) + +`npx skills` には Node.js 18 以降が必要で、対応エージェントとインストール範囲を対話的に選べます。 +ZIP の場合は最上位 Skill ディレクトリをホストのユーザー用またはプロジェクト用 Skill ディレクトリへ展開します。 + +## 機能と設定の違い + +ローカル Runtime の 2 配布は、通常会話と Pipeline、構成設計、ROS/Terraform テンプレート、料金見積もり、 +スタック操作、デプロイ、質問、候補選択、権限・デプロイ確認に対応します。モデル設定が必要で、クラウド +リソースの照会・変更には Alibaba Cloud 認証情報も必要です。 + +`alibabacloud-ros-agent` は `ros:StartChat` で Alibaba Cloud ROS Agent に接続します。ローカル Runtime と +ローカルモデル設定は不要で、ホストの Alibaba Cloud ID を使います。必要最小限の RAM 権限を付与し、 +明示的なリモートキャンセルには `ros:StopChat` も必要です。 + +どの版でも、変更やデプロイを承認する前にリソース、リージョン、影響、料金、権限を確認し、認証情報を +`SKILL.md`、プロンプト、プロジェクトファイルへ書かないでください。 + +## 関連ドキュメント + +- [IaC Code Skill のインストールと使用](./skill-integration.md) +- [ホスト統合リファレンス](./skill-host-integration.md) +- [Alibaba Cloud 認証情報](../configuration/alibaba-cloud-credentials.md) diff --git a/website/i18n/ja/docusaurus-plugin-content-docs/current/intro.md b/website/i18n/ja/docusaurus-plugin-content-docs/current/intro.md index d29709b8..c1c383a1 100644 --- a/website/i18n/ja/docusaurus-plugin-content-docs/current/intro.md +++ b/website/i18n/ja/docusaurus-plugin-content-docs/current/intro.md @@ -6,7 +6,7 @@ description: IaC Code の機能と始め方。 # 概要 -IaC Code は、クラウドインフラ向けの AI 駆動 Infrastructure as Code アシスタントです。ターミナルワークフローを通じて、インフラテンプレートの生成、デプロイ、管理をサポートします。アーキテクチャはマルチクラウドワークフローを想定して設計されており、現在のリリースでは Alibaba Cloud ROS と Terraform ワークフローをサポートしています。 +IaC Code は、クラウドインフラの設計、生成、デプロイ、管理を支援する AI アシスタントです。Desktop アプリ、ローカル Web アプリ、対話型ターミナル、自動化インターフェイスから利用でき、別のエージェントの Skill としても組み込めます。アーキテクチャはマルチクラウドワークフローを想定して設計されており、現在のリリースでは Alibaba Cloud ROS と Terraform ワークフローをサポートしています。 主な機能： @@ -14,4 +14,11 @@ IaC Code は、クラウドインフラ向けの AI 駆動 Infrastructure as Cod - **ワンコマンドで本番へ** — Alibaba Cloud ROS では、テンプレートから稼働中のインフラまでを一気通貫で実現し、リージョンをまたいでスタックの作成・更新・削除・監視を行います。Terraform のサポートはテンプレートの生成と変換が対象で、デプロイは含みません。 - **クラウドの知見を内蔵** — ドキュメント検索、リソース在庫確認、デプロイ前のコスト見積もり。すべての判断が実際のクラウドデータに裏付けられています。 -ドキュメントはユーザータスクに沿って構成されています。まずインストールとクイックスタートから始め、次にプロバイダーと認証情報を設定し、コマンドの詳細が必要な場合は CLI リファレンスをご覧ください。 +用途に合う入口を選んでください。 + +- すぐに使える GUI には [Desktop アプリ](./desktop-app.md)をダウンロードします。 +- [インストール](./getting-started/installation.md)と[クイックスタート](./getting-started/quick-start.md)に従って、REPL、ヘッドレスモード、またはローカル [Web アプリ](./web-app.md)を使います。 +- [IaC Code 公式 Skills の概要](./a2a/skill-overview.md)で配布方法を選び、対応エージェントに Alibaba Cloud インフラ機能を追加します。 +- 他のアプリやサービスへの統合には [ACP](./acp/overview.md)、[A2A](./a2a/overview.md)、[AG-UI](./agui/overview.md)を使います。 + +すべての入口でモデル設定が必要です。クラウドリソースの照会、変更、デプロイを行う場合は [Alibaba Cloud 認証情報](./configuration/alibaba-cloud-credentials.md)も設定してください。 diff --git a/website/i18n/pt/docusaurus-plugin-content-docs/current.json b/website/i18n/pt/docusaurus-plugin-content-docs/current.json index 7564b35c..f853067b 100644 --- a/website/i18n/pt/docusaurus-plugin-content-docs/current.json +++ b/website/i18n/pt/docusaurus-plugin-content-docs/current.json @@ -11,6 +11,10 @@ "message": "Usando o IaC Code", "description": "The label for category 'Using iac-code' in sidebar 'docsSidebar'" }, + "sidebar.docsSidebar.category.IaC Code Skill": { + "message": "Skill do IaC Code", + "description": "The label for category 'IaC Code Skill' in sidebar 'docsSidebar'" + }, "sidebar.docsSidebar.category.MCP Integration": { "message": "Integração MCP", "description": "The label for category 'MCP Integration' in sidebar 'docsSidebar'" diff --git a/website/i18n/pt/docusaurus-plugin-content-docs/current/a2a/overview.md b/website/i18n/pt/docusaurus-plugin-content-docs/current/a2a/overview.md index cad4164b..d7780122 100644 --- a/website/i18n/pt/docusaurus-plugin-content-docs/current/a2a/overview.md +++ b/website/i18n/pt/docusaurus-plugin-content-docs/current/a2a/overview.md @@ -22,7 +22,7 @@ Use A2A quando outro agente, mecanismo de workflow ou serviço precisar chamar o - **Automação de workflow** — Ferramentas internas podem enviar tarefas de geração, revisão ou conversão de IaC via HTTP. - **Descoberta de serviço** — Clientes podem buscar o Agent Card e escolher capacidades como geração de IaC ou revisão de templates. - **Integrações de streaming** — Um cliente de chatops ou dashboard pode mostrar texto do modelo, atividade de ferramentas, metadados de uso e o estado final da tarefa enquanto o turno executa. -- **Integração de Skill externa** — Agentes externos usam o Skill empacotado do iac-code para acionar um runtime A2A local autenticado por meio de um script ponte de apenas biblioteca padrão, incorporando o iac-code como capacidade de infraestrutura Alibaba Cloud. Veja [Integração de Skill](./skill-integration.md). +- **Integração de Skill externa** — Agentes externos podem adicionar capacidades de infraestrutura do Alibaba Cloud aos seus fluxos de trabalho com um Skill oficial do IaC Code. Consulte [Skills oficiais do IaC Code](./skill-overview.md) para escolher uma distribuição e depois [Instalar e usar o Skill](./skill-integration.md) ou a [referência para hosts](./skill-host-integration.md). ## Comparação dos modos de interação diff --git a/website/i18n/pt/docusaurus-plugin-content-docs/current/a2a/skill-host-integration.md b/website/i18n/pt/docusaurus-plugin-content-docs/current/a2a/skill-host-integration.md new file mode 100644 index 00000000..c98e0b5e --- /dev/null +++ b/website/i18n/pt/docusaurus-plugin-content-docs/current/a2a/skill-host-integration.md @@ -0,0 +1,136 @@ +--- +sidebar_position: 3 +title: Referência de integração do Skill do IaC Code para hosts +description: Integre a ponte do Skill do IaC Code a um agente host compatível. +--- + +# Referência de integração do Skill do IaC Code para hosts + +Este documento é destinado a desenvolvedores de agentes e sistemas de distribuição de Skills. Usuários devem ler +[Instalar e usar o Skill do IaC Code](./skill-integration.md). + +## Modelo de integração e configuração + +O pacote contém `SKILL.md` e a ponte `scripts/iac_code.py`, que usa apenas a biblioteca padrão. Execute-a com CPython +3.8 a 3.14. Trate stdout como o resultado JSON estável e stderr como diagnóstico e progresso. Preserve `jobId`, +`contextId`, cursor e os campos de correlação. Em caso de erro, não use outro Runtime nem chamadas diretas às APIs de +nuvem. + +O distribuidor pode colocar este `config.json` ao lado de `SKILL.md`: + +```json +{ + "channel": "codex", + "pipelineName": "selling_solution_first", + "permissionWaitPolicy": { + "residentTimeoutSeconds": null, + "subPipelineTimeoutSeconds": null, + "timeoutGraceSeconds": 30 + } +} +``` + +A ponte adiciona `skill/` antes de `channel`. O padrão de `pipelineName` é `selling_solution_first`; `selling` serve +apenas para um fluxo legado solicitado explicitamente. `null` significa espera ilimitada. Campos desconhecidos ou +inválidos são recusados. Essa política de instalação não deve ser derivada de uma solicitação, exposta ou alterada +durante uma tarefa. + +## Iniciar e acompanhar um job + +Grave a solicitação completa em um arquivo UTF-8 no workspace e use um caminho absoluto: + +```text +python3 scripts/iac_code.py start --mode normal --cwd --prompt-file --language --follow +``` + +Use `normal` por padrão e `pipeline` apenas para comparação, confirmação e implantação. O idioma pode ser `en`, `zh`, +`es`, `fr`, `de`, `ja`, `pt` ou `auto`; preserve depois `preferredLanguage`. `llm_not_configured` interrompe antes da +criação, e `cloud_credentials_not_configured` indica credenciais ausentes no Pipeline. + +`--follow` retorna no próximo limite de apresentação ou interação, em `turn_completed` ou no estado terminal do +Pipeline. Com `boundaryReached: true`, mostre todos os `userUpdates` e acompanhe o mesmo job: + +```text +python3 scripts/iac_code.py follow --job-id --cursor --wait-seconds 60 +``` + +`boundaryReached` não significa conclusão. `presentationRequired` exige exibir a atualização antes da próxima chamada. +No modo normal, use `finalText` e `artifacts` em `turn_completed`; no Pipeline terminal, use `pipelineResult` e +`artifacts` e informe falhas de limpeza. Apenas para diagnóstico ou recuperação: + +```text +python3 scripts/iac_code.py poll --job-id --cursor --wait-seconds 5 +``` + +Se o estado for `input-required` sem `inputRequired`, informe o texto ou erro mais recente e não altere o job. + +## Tratar a entrada do usuário + +Cada `inputRequired` é um limite rígido: apresente-o na interface nativa do host e aguarde uma resposta explícita. Não +deduza padrões. Preserve `kind`, `inputId`, `requestTaskId`, `contextId` e, quando houver, `toolUseId`. + +| `kind` | Informações que o host deve mostrar | Resposta | +|---|---|---| +| `permission` | Objetivo, efeito, alvo, somente leitura, resumos de implantação e segurança, ações | `allow_once` / `deny` | +| `ask_user_question` | Pergunta, opções e texto livre permitido | Resposta | +| `candidate_selection` | Todos os resumos, diagramas Mermaid, total mensal e itens | ID ou número | +| `deployment_confirmation` | Solução, URL, preço, parâmetros efetivos e alterados, Preview, ações | `confirm` / `adjust` / `reselect` / `cancel` | + +Grave a resposta correlacionada em um novo arquivo JSON UTF-8 e retome o mesmo job: + +```text +python3 scripts/iac_code.py respond --job-id --input-file --follow +``` + +```json +{"kind":"permission","requestTaskId":"","contextId":"","inputId":"","toolUseId":"","decision":"allow_once"} +``` + +```json +{"kind":"ask_user_question","requestTaskId":"","contextId":"","inputId":"","answer":""} +``` + +```json +{"kind":"candidate_selection","requestTaskId":"","contextId":"","inputId":"","answer":""} +``` + +```json +{"kind":"deployment_confirmation","requestTaskId":"","contextId":"","inputId":"","action":"","parameterOverrides":{"":""}} +``` + +Omita `parameterOverrides` sem ajustes. Não deduza a confirmação da solicitação inicial nem de uma aprovação do host. + +## Continuar, cancelar e recuperar + +Após um turno normal ou a passagem de um Pipeline concluído para o modo normal, continue o job existente: + +```text +python3 scripts/iac_code.py continue --job-id --prompt-file --follow +``` + +Preserve `jobId` e `contextId`; um novo `taskId` é esperado. Isso também permite recuperar esperas de permissão e +interrupções do host. Para cancelar toda a operação: + +```text +python3 scripts/iac_code.py cancel --job-id +``` + +O cancelamento completo é diferente de negar uma permissão. + +## Erros e Runtime + +Um erro anterior à criação é definitivo para a chamada. Em `incompatible_host`, mostre as informações de compatibilidade +e pare, sem usar pip, outro Runtime ou APIs diretas. O Runtime fica em +`/skill-runtime///`. Sua estrutura e integridade são definidas +por `skill-runtime/skill-package-contract.json` e pelo manifesto da versão. A limpeza exige solicitação explícita; +pacotes atuais ou ativos são protegidos. + +O Runtime usa uma porta aleatória de `127.0.0.1` e um Bearer token por processo. Não exponha token, estado local, +credenciais, valores de ambiente nem entradas ou saídas brutas das ferramentas. + +## Documentação relacionada + +- [Visão geral dos Skills oficiais do IaC Code](./skill-overview.md) +- [Instalar e usar o Skill do IaC Code](./skill-integration.md) +- [Visão geral do A2A](./overview.md) +- [Referência do A2A](./protocol-reference.md) diff --git a/website/i18n/pt/docusaurus-plugin-content-docs/current/a2a/skill-integration.md b/website/i18n/pt/docusaurus-plugin-content-docs/current/a2a/skill-integration.md index 9e498376..3b2b2987 100644 --- a/website/i18n/pt/docusaurus-plugin-content-docs/current/a2a/skill-integration.md +++ b/website/i18n/pt/docusaurus-plugin-content-docs/current/a2a/skill-integration.md @@ -1,214 +1,126 @@ --- -sidebar_position: 7 +sidebar_position: 2 title: Instalar e usar o Skill do IaC Code -description: Baixe e instale o Skill do IaC Code para que um agente externo possa gerenciar recursos do Alibaba Cloud. +description: Adicione o IaC Code a um agente compatível com Skills para gerenciar infraestrutura Alibaba Cloud. --- # Instalar e usar o Skill do IaC Code -O Skill do IaC Code foi desenvolvido para agentes externos compatíveis com Skills. Depois da instalação, um agente -host pode delegar ao IaC Code o planejamento de arquiteturas de nuvem, a geração e revisão de templates ROS ou -Terraform, a estimativa de custos, a seleção de recursos, as operações com stacks e o deploy. O Skill usa uma ponte -escrita apenas com a biblioteca padrão do Python para iniciar um Runtime A2A local e autenticado. Não é necessário -instalar o IaC Code com pip, e o host não deve recorrer a comandos headless. +O Skill do IaC Code permite que um agente compatível delegue ao IaC Code o planejamento de arquiteturas em nuvem, +a geração ou revisão de templates ROS e Terraform, estimativas de custo, seleção de recursos, operações de stacks ROS +e implantações. O pacote inclui um Runtime verificado do IaC Code; não é necessário instalar o IaC Code separadamente. -## Baixar o Skill +## Download -### Versão estável mais recente +[Baixar o iac-code-skill.zip estável mais recente](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/iac-code-skill.zip) -Baixe diretamente a versão estável mais recente: +Essa URL fixa sempre aponta para a versão estável mais recente. Instaladores automáticos podem ler +[latest.json](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/latest.json) +para obter versão, URL imutável, tamanho e SHA-256, e verificar `skill.url` com `skill.sha256`. -[Baixar iac-code-skill.zip](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/iac-code-skill.zip) +## Instalação -Essa URL fixa sempre aponta para o pacote do Skill promovido ao canal estável. Ela é adequada para downloads pelo -navegador e instalações manuais e não muda quando uma nova versão é publicada. +Confirme que o agente aceita Skills locais definidos por `SKILL.md`, que o CPython 3.8 a 3.14 está disponível e que o +ambiente acessa o download no primeiro uso. Use `python3` no macOS/Linux e `py -3` no Windows. Os Runtimes oficiais +oferecem suporte a macOS Apple Silicon, Linux x86_64 e Windows x86_64; o sistema e a ABI são verificados antes do +download. -Instaladores que precisam da versão, do tamanho do arquivo, do hash SHA-256 e da URL imutável específica da versão -podem consultar os metadados do canal estável: - -[Ver latest.json](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/latest.json) - -O documento contém: - -- `skillVersion`: versão estável atual do Skill; -- `skill.url`: URL imutável do ZIP dessa versão; -- `skill.sha256` e `skill.size`: valores usados para verificar o download; -- `manifest.url`: manifesto de release imutável dessa versão. - -Para uma verificação rigorosa ou uma instalação automatizada reproduzível, leia `latest.json`, baixe `skill.url` e -verifique `skill.sha256`. Não monte manualmente uma URL com base no número da versão. - -## Instalar o Skill - -### Pré-requisitos - -- O agente host é compatível com Skills locais definidos por `SKILL.md`. -- O CPython 3.8–3.14 está instalado. Use `python3` no macOS/Linux e, de preferência, `py -3` no Windows. -- O ambiente consegue acessar as URLs OSS acima para baixar o ZIP do Skill e o Runtime necessário no primeiro uso. -- A configuração do serviço de modelo está disponível. Para tarefas que consultam ou gerenciam recursos de nuvem, - também é necessária uma identidade do Alibaba Cloud com o mínimo de privilégios. - -Os releases oficiais do Skill Runtime são compatíveis com estas plataformas: - -| Sistema operacional | Arquitetura | -|---|---| -| macOS | Apple Silicon (arm64) | -| Linux | x86_64 | -| Windows | x86_64 | - -As versões mínimas do sistema operacional e da glibc no Linux são definidas pelo manifesto do Runtime fixado pelo -Skill. A ponte verifica a compatibilidade antes de baixar. Em uma plataforma não compatível, ela retorna um erro em -vez de baixar um artefato destinado a outra plataforma ou ABI. - -### Extrair no diretório de Skills do agente host - -Extraia o ZIP diretamente na raiz de Skills do agente host. O local exato varia de acordo com o produto; consulte a -documentação do agente host. A estrutura final deve ser: +Extraia o ZIP no diretório de Skills indicado pelo agente. O arquivo já contém `iac-code/`: ```text / └── iac-code/ ├── SKILL.md - ├── agents/ - │ └── openai.yaml - └── scripts/ - └── iac_code.py + ├── agents/openai.yaml + └── scripts/iac_code.py ``` -O ZIP já contém o diretório de nível superior `iac-code/`. Não adicione outro diretório com o mesmo nome. Depois de -instalar ou atualizar, reinicie o agente host ou abra uma nova sessão para que ele detecte o Skill novamente. +Locais comuns: -### Verificar a instalação +- **Codex**: `~/.agents/skills/iac-code/` para todos os projetos ou + `/.agents/skills/iac-code/` para um repositório. Consulte a + [documentação de Codex Skills](https://developers.openai.com/codex/skills#where-codex-loads-local-skills). +- **Claude Code**: `~/.claude/skills/iac-code/` para todos os projetos ou + `/.claude/skills/iac-code/` para um repositório. Consulte a + [documentação de Claude Code Skills](https://code.claude.com/docs/en/skills#where-skills-live). -No diretório `iac-code` extraído, execute este comando no macOS ou Linux: +Reinicie o agente ou abra uma nova sessão. Para verificar o Runtime no diretório `iac-code`: ```bash python3 scripts/iac_code.py ensure-runtime ``` -No Windows PowerShell, execute: - -```powershell -py -3 scripts\iac_code.py ensure-runtime -``` - -Na primeira execução, o comando baixa o Runtime da plataforma atual, verifica o tamanho e o hash SHA-256 e imprime um -objeto JSON com `skillVersion`, `runtimeTag` e o caminho de instalação. Um Runtime verificado que já esteja no cache é -reutilizado sem um novo download. +No Windows PowerShell, use `py -3 scripts\iac_code.py ensure-runtime`. No primeiro uso, o Runtime correto é baixado e +seu tamanho e SHA-256 são verificados; tarefas posteriores reutilizam a cópia local validada. -## Configurar o modelo e a identidade do Alibaba Cloud +## Configurar o modelo e a identidade Alibaba Cloud -O Skill Runtime usa o mesmo diretório de configuração que os outros modos do IaC Code: `~/.iac-code/` por padrão. Se -você já configurou o IaC Code pelo REPL, pelo aplicativo Web ou pelo aplicativo Desktop, o Skill pode reutilizar essas -configurações. Defina `IAC_CODE_CONFIG_DIR` para usar outro diretório de configuração. +O Skill usa `~/.iac-code/` por padrão e reutiliza as configurações do REPL e dos aplicativos Web ou Desktop. Escolha +outro diretório com `IAC_CODE_CONFIG_DIR`. Em automações, injete configurações do modelo e credenciais do Alibaba Cloud +por um gerenciador de segredos. Não as grave em `SKILL.md`, prompts, arquivos do projeto ou histórico do shell. Prefira +credenciais temporárias, funções RAM ou OAuth com privilégios mínimos. Consulte +[Provedores LLM](../configuration/llm-providers.md) e +[Credenciais do Alibaba Cloud](../configuration/alibaba-cloud-credentials.md). -Em ambientes automatizados, forneça estas variáveis por meio de uma solução de gerenciamento de segredos: +## Escolher o modo de trabalho -| Categoria | Variável de ambiente | Descrição | -|---|---|---| -| Modelo | `IAC_CODE_PROVIDER` | Provedor do modelo | -| Modelo | `IAC_CODE_MODEL` | Nome do modelo | -| Modelo | `IAC_CODE_API_KEY` | Chave de API do serviço de modelo | -| Modelo | `IAC_CODE_BASE_URL` | Substituição opcional do endpoint compatível | -| Alibaba Cloud | `ALIBABA_CLOUD_ACCESS_KEY_ID` | ID da AccessKey | -| Alibaba Cloud | `ALIBABA_CLOUD_ACCESS_KEY_SECRET` | Segredo da AccessKey | -| Alibaba Cloud | `ALIBABA_CLOUD_SECURITY_TOKEN` | Token de segurança para credenciais STS | -| Alibaba Cloud | `ALIBABA_CLOUD_REGION_ID` | Região padrão | +- O **modo normal** é o padrão para consultar ou alterar recursos, trabalhar com templates, solucionar problemas e + implantar um objetivo claro. +- O **modo Pipeline** é usado quando solicitado ou quando é necessário um fluxo guiado com arquiteturas candidatas, + comparação de custos, confirmação e implantação. -Nunca coloque credenciais reais em `SKILL.md`, nos prompts do agente host, nos arquivos do projeto ou no histórico do -shell. Prefira credenciais temporárias, funções RAM ou OAuth e conceda apenas as permissões de API de nuvem necessárias -para a tarefa. Consulte [Provedores de LLM](../configuration/llm-providers.md) e -[Credenciais do Alibaba Cloud](../configuration/alibaba-cloud-credentials.md) para obter instruções completas. +Normalmente, basta descrever o resultado. Mencione Pipeline apenas quando quiser comparar soluções. ## Primeiro uso -Depois da instalação e da configuração, abra uma nova sessão no agente host e descreva diretamente uma tarefa de -infraestrutura do Alibaba Cloud. Por exemplo: +Abra uma nova sessão no agente host e escreva, por exemplo: ```text -Use o iac-code para revisar o template ROS deste projeto. Liste os riscos de segurança e as alterações recomendadas sem modificar o arquivo. +Use o iac-code para revisar o template ROS deste projeto. Liste riscos de segurança e melhorias sem alterar o arquivo. ``` -Hosts compatíveis com uma sintaxe explícita de Skills podem selecionar o Skill usando `$iac-code`. O agente host lê -`SKILL.md`, grava a solicitação completa em um arquivo UTF-8 dentro do workspace e usa a ponte para criar e acompanhar -uma única tarefa. O usuário não precisa iniciar manualmente um servidor A2A. +Selecione o Skill explicitamente com `$iac-code` no Codex ou `/iac-code` no Claude Code. A verificação da configuração e a inicialização do +Runtime são automáticas; não é preciso iniciar um A2A Server manualmente. O IaC Code pode pausar para solicitar: -Fluxo esperado: +- aprovação ou recusa de uma operação (`permission`); +- resposta a uma pergunta (`ask_user_question`); +- escolha de uma arquitetura (`candidate_selection`); +- revisão da solução, preço e parâmetros, seguida de confirmação, ajuste, nova seleção ou cancelamento + (`deployment_confirmation`). -1. A ponte verifica se a configuração do modelo e do Alibaba Cloud está pronta. -2. No primeiro uso, ela baixa e verifica o Runtime do IaC Code fixado pelo Skill. -3. O Runtime escuta apenas em uma porta aleatória de `127.0.0.1` e gera um token Bearer específico do processo. -4. O agente host apresenta o progresso, as perguntas, os planos candidatos e as solicitações de permissão retornados - pelo IaC Code. -5. Quando a tarefa termina, o agente host retorna o resultado final e os arquivos gerados no workspace. +Revise recursos, região, impacto e preço antes de responder. O pedido inicial de implantação não aprova antecipadamente +a confirmação posterior. Após a conclusão, continue na mesma sessão para preservar o contexto. Progresso e perguntas +podem ser retornados em inglês, chinês simplificado, espanhol, francês, alemão, japonês e português. ## Atualizar e desinstalar -Para fazer uma atualização manual, baixe `skill/stable/iac-code-skill.zip` novamente e substitua todo o diretório -`iac-code/` na raiz de Skills do host. Um atualizador automático pode comparar o valor `skillVersion` de `latest.json` -e, em seguida, baixar e verificar o novo pacote usando a URL imutável e o hash SHA-256. Cada Skill oficial é fixado a -um Runtime verificado. Não substitua apenas `scripts/iac_code.py` nem altere manualmente a URL ou o hash do Runtime. - -Para desinstalar, remova `iac-code/` da raiz de Skills do agente host. O cache do Runtime não é removido com o -diretório do Skill. Execute `cache list` e `cache clean` somente quando o usuário solicitar explicitamente a remoção. - -## Cache do Runtime - -O Runtime baixado no primeiro uso é armazenado em -`/skill-runtime///` e reutilizado automaticamente. No uso -normal, não é necessário gerenciar esse diretório. Para verificar o uso do disco ou remover versões antigas, use: - -- `python3 scripts/iac_code.py cache list` — lista os Runtimes instalados e os pacotes candidatos; -- `python3 scripts/iac_code.py cache clean [--runtime-tag ] [--candidates] --confirm` — remove caches do Runtime - ou pacotes candidatos; `--confirm` é obrigatório. - -O Runtime atual e qualquer Runtime usado por um processo ativo são protegidos contra a limpeza. O formato do pacote e -as restrições do Runtime são definidos por `skill-runtime/skill-package-contract.json` no repositório de código-fonte; -os usuários não precisam modificar esse arquivo. +Para atualizar, baixe novamente o ZIP estável, substitua todo o diretório `iac-code/` e reinicie o agente. Não substitua +apenas o script de ponte nem edite a URL ou o hash do Runtime. Para desinstalar, remova `iac-code/`. Os Runtimes +permanecem em cache; para removê-los também, consulte `cache list` e depois execute `cache clean ... --confirm`. ## Solução de problemas -### A configuração está incompleta - -O Skill verifica a configuração antes de criar uma tarefa, mas nunca lê nem retorna valores secretos: - -| Situação | Resultado | -|---|---| -| O provedor de LLM ou a chave de API está incompleto | Retorna `llm_not_configured` e não cria a tarefa | -| As credenciais do Alibaba Cloud estão incompletas para o Pipeline de vendas | Retorna `cloud_credentials_not_configured` e não cria a tarefa | -| As credenciais do Alibaba Cloud estão incompletas no modo normal | Tarefas que não chamam APIs de nuvem podem continuar com um aviso prévio | - -### Por que a execução é pausada - -O IaC Code pausa quando precisa de permissão, informações adicionais ou da seleção de um plano. O agente host apresenta -a solicitação diretamente: - -- uma solicitação de permissão para uma ferramenta ou um deploy (`permission`); -- uma pergunta de múltipla escolha ou uma solicitação de mais informações (`ask_user_question`); -- a seleção de um plano candidato do Pipeline (`candidate_selection`). - -Antes de confirmar, revise o recurso de destino, a região, o impacto esperado e o preço. O agente host não pode anular -uma recusa do IaC Code. Uma aprovação única é representada no protocolo como `allow_once`. +- `llm_not_configured`: conclua a configuração do modelo. +- `cloud_credentials_not_configured`: configure as credenciais exigidas pelo Pipeline. O modo normal pode continuar + tarefas sem API de nuvem com um aviso. +- `incompatible_host`: execute `ensure-runtime` e verifique Python, sistema, arquitetura, rede e proxy. Atualize ou mude + o host, em vez de contornar a verificação. +- Tarefa pausada: ela aguarda uma resposta, permissão, seleção ou confirmação. Se a sessão ainda existir após uma + interrupção, solicite que o agente continue a mesma tarefa. -> **Observação sobre a integração do agente host** -> -> Quando um resultado da ponte contém `inputRequired`, o agente host deve apresentar a solicitação atual e aguardar -> uma resposta. `boundaryReached` indica um limite de apresentação ou interação, e não a conclusão da tarefa; o host -> deve mostrar a atualização e continuar acompanhando a mesma tarefa. +Use `python3 scripts/iac_code.py cache list` para inspecionar o cache, +`cache clean --runtime-tag --confirm` para remover uma versão antiga e +`cache clean --candidates --confirm` para pacotes candidatos. O Runtime atual ou ativo é protegido. ## Segurança -- O Runtime escuta apenas em uma porta aleatória de `127.0.0.1`. Cada inicialização gera um novo token Bearer, e cada - solicitação da ponte inclui esse token. -- A ponte mantém artefatos e resultados no workspace da tarefa. Os resultados são gravados em - `.iac-code-skill-results/`. -- Os campos exibidos na verificação prévia e nas solicitações de permissão são higienizados; segredos e credenciais - não aparecem nesses campos. +- O Runtime escuta apenas em uma porta aleatória de `127.0.0.1` e usa um Bearer token novo por processo. +- Os resultados permanecem no workspace, em `.iac-code-skill-results/` quando aplicável. +- Estados de prontidão e resumos de permissão não incluem valores de credenciais. ## Documentação relacionada -- [Visão geral do protocolo A2A](./overview.md) -- [Referência do protocolo A2A](./protocol-reference.md) -- [Provedores de LLM](../configuration/llm-providers.md) -- [Credenciais do Alibaba Cloud](../configuration/alibaba-cloud-credentials.md) +- [Visão geral dos Skills oficiais do IaC Code](./skill-overview.md) +- [Referência de integração do Skill do IaC Code para hosts](./skill-host-integration.md) +- [Visão geral do A2A](./overview.md) - [Configuração do Runtime](../configuration/runtime-configuration.md) diff --git a/website/i18n/pt/docusaurus-plugin-content-docs/current/a2a/skill-overview.md b/website/i18n/pt/docusaurus-plugin-content-docs/current/a2a/skill-overview.md new file mode 100644 index 00000000..1628ebf6 --- /dev/null +++ b/website/i18n/pt/docusaurus-plugin-content-docs/current/a2a/skill-overview.md @@ -0,0 +1,69 @@ +--- +sidebar_position: 1 +title: Visão geral dos Skills oficiais do IaC Code +description: Compare os Skills oficiais do IaC Code e escolha a distribuição adequada. +--- + +# Visão geral dos Skills oficiais do IaC Code + +O IaC Code está disponível em três distribuições oficiais de Skill. Todas permitem gerenciar infraestrutura Alibaba +Cloud a partir de um agente, mas diferem no canal de distribuição e em onde o Agent do IaC Code é executado. + +## Escolher um Skill + +| Skill | Onde é executado | Quando escolher | +|---|---|---| +| `iac-code` | Runtime verificado do IaC Code baixado na sua máquina | Você quer o pacote independente do projeto iac-code e controle direto de instalação e atualizações. | +| `alibabacloud-iac-code` | O mesmo Runtime local, empacotado para o portal Alibaba Cloud Agent Skills | Você gerencia Alibaba Cloud Skills pelo portal ou por `npx skills`. | +| `alibabacloud-ros-agent` | Agent ROS hospedado pelo Alibaba Cloud, chamado pela API ROS StartChat | Você quer uma conversa remota sem baixar o Runtime local do IaC Code. | + +`iac-code` e `alibabacloud-iac-code` oferecem a mesma capacidade. Escolha uma distribuição em cada escopo do agente; +instalar ambas adiciona acionamentos sobrepostos, não novos recursos. + +`alibabacloud-ros-agent` é uma integração remota separada. Ele pode coexistir com uma distribuição local quando o +usuário precisa escolher explicitamente entre IaC Code local e o Agent ROS hospedado. + +## Obter o Skill independente + +[Baixar iac-code-skill.zip estável](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/iac-code-skill.zip) + +Essa distribuição é ideal para instalação gerenciada manualmente. Ela baixa o Runtime no primeiro uso e reutiliza a +configuração de modelo e Alibaba Cloud em `~/.iac-code/`. Consulte +[Instalar e usar o Skill do IaC Code](./skill-integration.md). + +## Obter os Skills do portal Alibaba Cloud + +Pesquise os nomes exatos no [portal Alibaba Cloud Agent Skills](https://skills.aliyun.com/) ou instale pelo repositório +oficial: + +```bash +npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-iac-code +npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-ros-agent +``` + +Downloads diretos: + +- [`alibabacloud-iac-code` ZIP](https://skills.aliyun.com/api/public/skills/alibabacloud-iac-code/download) · [código-fonte](https://github.com/aliyun/alibabacloud-aiops-skills/tree/master/skills/developertools/ros/alibabacloud-iac-code) +- [`alibabacloud-ros-agent` ZIP](https://skills.aliyun.com/api/public/skills/alibabacloud-ros-agent/download) · [código-fonte](https://github.com/aliyun/alibabacloud-aiops-skills/tree/master/skills/developertools/ros/alibabacloud-ros-agent) + +`npx skills` exige Node.js 18 ou posterior e permite escolher interativamente o agente e o escopo. Para um ZIP, extraia +o diretório Skill superior no diretório de usuário ou projeto aceito pelo agente. + +## Diferenças de recursos e configuração + +As duas distribuições locais oferecem conversas normais e Pipeline, arquitetura, templates ROS/Terraform, custos, +stacks, implantação e confirmações. Elas exigem um modelo configurado e credenciais do Alibaba Cloud quando a tarefa +consulta ou altera recursos. + +`alibabacloud-ros-agent` usa `ros:StartChat` para acessar o Agent ROS do Alibaba Cloud. Não exige Runtime local nem +provedor de modelo local, mas usa a identidade Alibaba Cloud do host. Conceda apenas as permissões RAM necessárias; +um cancelamento remoto explícito também usa `ros:StopChat`. + +Em qualquer distribuição, revise recursos, região, impacto, preço e permissões antes de aprovar. Não salve credenciais +em `SKILL.md`, prompts ou arquivos do projeto. + +## Documentação relacionada + +- [Instalar e usar o Skill do IaC Code](./skill-integration.md) +- [Referência de integração para hosts](./skill-host-integration.md) +- [Credenciais do Alibaba Cloud](../configuration/alibaba-cloud-credentials.md) diff --git a/website/i18n/pt/docusaurus-plugin-content-docs/current/intro.md b/website/i18n/pt/docusaurus-plugin-content-docs/current/intro.md index 9e878b39..88c9f7ef 100644 --- a/website/i18n/pt/docusaurus-plugin-content-docs/current/intro.md +++ b/website/i18n/pt/docusaurus-plugin-content-docs/current/intro.md @@ -6,7 +6,7 @@ description: O que o IaC Code faz e por onde comecar. # Visao geral -O IaC Code e um assistente de Infrastructure as Code com tecnologia de IA para infraestrutura em nuvem. Ele ajuda utilizadores e operadores de recursos na nuvem a gerar, implantar e gerenciar templates de infraestrutura atraves de um fluxo de trabalho no terminal. A arquitetura foi pensada para fluxos de trabalho multicloud; a versao atual oferece suporte a workflows Alibaba Cloud ROS e Terraform. +O IaC Code é um assistente de IA para planejar, gerar, implantar e gerenciar infraestrutura em nuvem. Ele pode ser usado no aplicativo Desktop, no aplicativo Web local, no terminal interativo, em interfaces de automação ou como Skill de outro agente. A arquitetura foi projetada para fluxos multicloud; a versão atual oferece suporte a Alibaba Cloud ROS e Terraform. Capacidades principais: @@ -14,4 +14,11 @@ Capacidades principais: - **Do template a producao** — para o Alibaba Cloud ROS, va do template a infraestrutura em execucao: crie, atualize, exclua e monitore stacks em diferentes regioes. O suporte a Terraform cobre a geracao e a conversao de templates, nao a implantacao. - **Inteligencia de nuvem integrada** — pesquise documentacao, verifique a disponibilidade de recursos e estime custos antes de implantar; cada decisao respaldada por dados reais da nuvem. -A documentacao esta organizada em torno das tarefas do utilizador. Comece com a instalacao e o inicio rapido, depois configure provedores e credenciais, e em seguida use a referencia do CLI quando precisar de detalhes sobre os comandos. +Escolha o ponto de entrada adequado: + +- Baixe o [aplicativo Desktop](./desktop-app.md) para uma interface gráfica pronta para uso. +- Siga a [instalação](./getting-started/installation.md) e o [início rápido](./getting-started/quick-start.md) para usar REPL, modo headless ou o [aplicativo Web](./web-app.md) local. +- Escolha uma distribuição na [visão geral dos Skills oficiais do IaC Code](./a2a/skill-overview.md) para adicionar seus recursos de Alibaba Cloud a um agente compatível. +- Use [ACP](./acp/overview.md), [A2A](./a2a/overview.md) ou [AG-UI](./agui/overview.md) para integrar o IaC Code a outro aplicativo ou serviço. + +Todos os pontos de entrada exigem um modelo configurado. Configure também as [credenciais do Alibaba Cloud](./configuration/alibaba-cloud-credentials.md) para consultar, alterar ou implantar recursos. diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current.json b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current.json index 92204a73..8502c5b5 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current.json +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current.json @@ -11,6 +11,10 @@ "message": "使用 IaC Code", "description": "The label for category 'Using iac-code' in sidebar 'docsSidebar'" }, + "sidebar.docsSidebar.category.IaC Code Skill": { + "message": "IaC Code Skill", + "description": "The label for category 'IaC Code Skill' in sidebar 'docsSidebar'" + }, "sidebar.docsSidebar.category.MCP Integration": { "message": "MCP 集成", "description": "The label for category 'MCP Integration' in sidebar 'docsSidebar'" diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/a2a/overview.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/a2a/overview.md index 6d912c74..c118d85c 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/a2a/overview.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/a2a/overview.md @@ -22,7 +22,7 @@ iac-code 可以作为 A2A 1.0 Server / Agent 运行。其他兼容 A2A 的客户 - **工作流自动化** — 内部工具可以通过 HTTP 提交 IaC 生成、审查或转换任务。 - **服务发现** — 客户端可以获取 Agent Card，并选择 IaC 生成或模板审查等能力。 - **流式集成** — chatops 或仪表板客户端可以在轮次运行时显示模型文本、工具活动、用量元数据和最终任务状态。 -- **外部 Skill 集成** — 外部 agent 使用打包好的 iac-code Skill，通过纯标准库桥接脚本驱动本地认证的 A2A runtime，把 iac-code 作为阿里云基础设施能力嵌入自己的工作流。详见 [Skill 集成](./skill-integration.md)。 +- **外部 Skill 集成** — 外部 Agent 可以通过官方 IaC Code Skill，将阿里云基础设施能力接入自己的工作流。请先查看[官方 IaC Code Skills](./skill-overview.md)选择合适的发行方式，再参考[安装和使用 IaC Code Skill](./skill-integration.md)或[宿主集成参考](./skill-host-integration.md)。 ## 交互模式对比 diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/a2a/skill-host-integration.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/a2a/skill-host-integration.md new file mode 100644 index 00000000..281e170b --- /dev/null +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/a2a/skill-host-integration.md @@ -0,0 +1,164 @@ +--- +sidebar_position: 3 +title: IaC Code Skill 宿主集成参考 +description: 在支持 Skill 的宿主 Agent 中集成 IaC Code 桥接脚本。 +--- + +# IaC Code Skill 宿主集成参考 + +本文面向 Agent 和 Skill 分发系统的开发者，说明宿主如何调用桥接脚本、展示 IaC Code 结果、处理用户交互 +并恢复已有任务。普通用户请阅读[安装和使用 IaC Code Skill](./skill-integration.md)。 + +## 集成模型 + +Skill 包含 `SKILL.md` 和只使用 Python 标准库的 `scripts/iac_code.py`。宿主调用桥接脚本，桥接脚本安装并 +启动固定版本且经过校验的 Runtime，然后通过本地鉴权 A2A 连接与其通信。 + +宿主必须： + +- 使用 CPython 3.8～3.14 运行桥接脚本； +- 将 stdout 视为稳定的 JSON 结果，将 stderr 视为诊断和受限的进度输出； +- 保存当前 `jobId`、`contextId`、cursor 和输入关联字段； +- 展示每个面向用户的边界后再继续； +- 桥接出错时终止流程，不得改用云 API 直调或其他 Runtime 绕过。 + +## 可选分发配置 + +分发方可以在 `SKILL.md` 同级目录放置 `config.json`： + +```json +{ + "channel": "codex", + "pipelineName": "selling_solution_first", + "permissionWaitPolicy": { + "residentTimeoutSeconds": null, + "subPipelineTimeoutSeconds": null, + "timeoutGraceSeconds": 30 + } +} +``` + +- `channel` 是渠道标识，桥接脚本会自动添加 `skill/` 前缀。 +- `pipelineName` 仅在选择 Pipeline 模式后生效。默认值为 `selling_solution_first`；仅当分发方明确需要旧流程 + 时才使用 `selling`。 +- `permissionWaitPolicy` 控制 Skill 临时 A2A Server 的等待策略。常驻或子 Pipeline 超时为 `null` 表示无限等待。 + +桥接脚本会拒绝未知字段和非法值。此文件属于安装策略，不得根据用户请求生成、在任务输出中展示或在任务 +执行期间修改。 + +## 启动作业 + +把完整请求写入工作目录中的 UTF-8 文件，将工作目录解析为绝对路径，然后运行： + +```text +python3 scripts/iac_code.py start --mode normal --cwd --prompt-file --language --follow +``` + +默认使用 `normal`。仅在用户需要候选架构、费用对比、确认和部署组成的方案对比流程时选择 `pipeline`。 +语言可以设置为 `en`、`zh`、`es`、`fr`、`de`、`ja`、`pt` 或 `auto`。后续轮次始终保留返回的 +`preferredLanguage`。 + +`start` 会进行不读取密钥值的就绪检查。`llm_not_configured` 会在创建作业前终止。Pipeline 模式还要求 +云凭证完整，否则返回 `cloud_credentials_not_configured`。普通模式在任务不需要云 API 时可以带警告继续。 + +## 跟进进度和完成状态 + +`--follow` 会在下一个展示或交互边界、`turn_completed` 或 Pipeline 终态停止。结果包含 +`boundaryReached: true` 时，先展示 `userUpdates` 中的全部文本，再使用返回的 cursor 继续同一作业： + +```text +python3 scripts/iac_code.py follow --job-id --cursor --wait-seconds 60 +``` + +不要把 `boundaryReached` 当作任务完成。`presentationRequired` 表示继续调用桥接脚本前必须让用户看到当前 +更新。普通模式只有 `state` 为 `turn_completed` 时结果才具有权威性，应使用 `finalText` 和 `artifacts`。 +Pipeline 到达终态后使用 `pipelineResult` 和 `artifacts`，清理失败时必须明确告知，不能宣称任务成功。 + +诊断或恢复期间无法使用 `follow` 时，可以轮询同一作业： + +```text +python3 scripts/iac_code.py poll --job-id --cursor --wait-seconds 5 +``` + +如果结果显示 `state: input-required`，但没有 `inputRequired`，请报告最新文本或错误并保持作业不变，不要 +重复提交回答或新建替代作业。 + +## 处理用户输入 + +每个 `inputRequired` 都是必须暂停的交互边界。通过宿主原生的提问或审批界面展示它，等待用户明确回答。 +不得从原始请求推断答案或替用户选择默认项。必须保留 `kind`、`inputId`、`requestTaskId`、`contextId`， +以及存在时的 `toolUseId`。 + +| `kind` | 宿主需要展示 | 回答 | +|---|---|---| +| `permission` | 用途、影响、目标、是否只读、部署摘要、安全摘要和可选操作 | `allow_once` 或 `deny` | +| `ask_user_question` | 问题、选项，以及允许自由输入时的提示 | 选项或允许的自由文本 | +| `candidate_selection` | 每个方案摘要、Mermaid 架构图、月费用总计和费用项 | 方案 ID 或序号 | +| `deployment_confirmation` | 方案、模板地址、报价或报价失败、有效参数、参数覆盖、预览状态和可选操作 | `confirm`、`adjust`、`reselect` 或 `cancel` | + +将带有关联字段的回答写入新的 UTF-8 JSON 文件，并恢复同一作业： + +```text +python3 scripts/iac_code.py respond --job-id --input-file --follow +``` + +回答示例： + +```json +{"kind":"permission","requestTaskId":"","contextId":"","inputId":"","toolUseId":"","decision":"allow_once"} +``` + +```json +{"kind":"ask_user_question","requestTaskId":"","contextId":"","inputId":"","answer":""} +``` + +```json +{"kind":"candidate_selection","requestTaskId":"","contextId":"","inputId":"","answer":""} +``` + +```json +{"kind":"deployment_confirmation","requestTaskId":"","contextId":"","inputId":"","action":"","parameterOverrides":{"":""}} +``` + +用户未要求调整时省略 `parameterOverrides`。用户提出部署需求，不代表已经同意后续的 +`deployment_confirmation`；宿主自身的审批也不能覆盖 IaC Code 的拒绝结果。 + +## 继续对话 + +普通模式一轮完成后，或 Pipeline 完成并将对话切换到普通模式后，把下一条消息写入新的提示词文件并继续 +已有作业： + +```text +python3 scripts/iac_code.py continue --job-id --prompt-file --follow +``` + +保持相同的 `jobId` 和 `contextId`；普通模式每轮产生新的 `taskId` 属于正常行为。不得仅因上一轮结束就改用 +`start`。保留作业标识还能让桥接脚本恢复权限等待，并在宿主中断后继续执行。 + +取消整个操作时运行： + +```text +python3 scripts/iac_code.py cancel --job-id +``` + +取消整个操作与拒绝单次权限请求不同。 + +## 错误和 Runtime 生命周期 + +创建作业前返回的桥接错误是权威结果。特别是 `incompatible_host` 会返回可用的宿主和 Runtime 兼容性信息； +展示这些信息后停止。不得改用 pip 安装、其他 Runtime 软件包或云 API 直调。 + +Runtime 缓存在 `/skill-runtime///`。软件包布局和 +完整性元数据由 `skill-runtime/skill-package-contract.json` 及版本清单定义，使用前由桥接脚本校验。 +清理 Runtime 缓存必须是用户单独明确要求的操作，当前和正在使用的软件包会受到保护。 + +Runtime 绑定随机的 `127.0.0.1` 端口，并生成进程专用的 Bearer Token。不得暴露 Token、本地状态、凭证、 +环境变量值或原始工具输入输出。受限的结果投影和展示字段才是宿主支持的接口。 + +## 相关文档 + +- [IaC Code 官方 Skills 概览](./skill-overview.md) +- [安装和使用 IaC Code Skill](./skill-integration.md) +- [A2A 协议概览](./overview.md) +- [A2A 协议参考](./protocol-reference.md) +- [运行时配置](../configuration/runtime-configuration.md) diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/a2a/skill-integration.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/a2a/skill-integration.md index 9db5a3e6..c63a06ce 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/a2a/skill-integration.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/a2a/skill-integration.md @@ -1,65 +1,36 @@ --- -sidebar_position: 7 +sidebar_position: 2 title: 安装和使用 IaC Code Skill -description: 下载并安装 IaC Code Skill，让外部 Agent 获得阿里云基础设施管理能力。 +description: 将 IaC Code 添加到支持 Skill 的 Agent，并用它管理阿里云资源。 --- # 安装和使用 IaC Code Skill -IaC Code Skill 面向支持 Skill 的外部 Agent。安装后，宿主 Agent 可以把云架构规划、ROS 或 -Terraform 模板生成与审查、成本估算、资源选择、资源栈操作和部署等任务委派给 IaC Code。 -Skill 会通过纯 Python 标准库桥接脚本启动本地认证的 A2A Runtime；不需要通过 pip 安装 -IaC Code，也不应改用 Headless 命令。 +IaC Code Skill 可以让兼容的 Agent 将阿里云基础设施任务交给 IaC Code。它支持规划云架构、生成或评审 +ROS 与 Terraform 模板、估算费用、选择已有资源、操作 ROS 资源栈和部署资源。安装包自带经过校验的 +IaC Code Runtime，不需要单独安装 IaC Code。 -## 下载 Skill +## 下载 -### 最新稳定版 +[下载最新版 iac-code-skill.zip](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/iac-code-skill.zip) -直接下载最新稳定版： +这个固定地址始终指向最新稳定版 Skill。自动安装程序可以读取 +[latest.json](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/latest.json)， +获取当前版本、不可变下载地址、文件大小和 SHA-256 摘要。如果需要可复现安装，请下载其中的 +`skill.url` 并校验 `skill.sha256`。 -[下载 iac-code-skill.zip](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/iac-code-skill.zip) +## 安装 -该固定地址始终指向已经提升到 stable 频道的 Skill 包，适合浏览器下载和手工安装。发布新 -版本时地址保持不变，不需要修改下载链接。 +安装前请确认： -需要获取版本号、文件大小、SHA-256 和不可变版本地址的安装器，可以读取稳定频道元数据： +- Agent 支持通过 `SKILL.md` 定义的本地 Skill。 +- 已安装 CPython 3.8～3.14。macOS 或 Linux 使用 `python3`，Windows 使用 `py -3`。 +- 首次使用时环境能够访问下载地址。 -[查看 latest.json](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/latest.json) +官方 Runtime 支持 Apple 芯片的 macOS、Linux x86_64 和 Windows x86_64。下载前会检查操作系统和 +ABI 要求。 -其中： - -- `skillVersion` 是当前稳定版 Skill 版本。 -- `skill.url` 是对应版本不可变的 ZIP 下载地址。 -- `skill.sha256` 和 `skill.size` 用于校验下载文件。 -- `manifest.url` 指向该版本不可变的发布清单。 - -自动化安装需要严格校验或可重复构建时，应先读取 `latest.json`，再下载 `skill.url` 并校验 -`skill.sha256`。不要自行拼接版本地址。 - -## 安装 Skill - -### 前提条件 - -- 宿主 Agent 支持由 `SKILL.md` 定义的本地 Skill。 -- 已安装 CPython 3.8～3.14。macOS/Linux 使用 `python3`，Windows 优先使用 `py -3`。 -- 可以访问上述 OSS 地址，以下载 Skill ZIP 和首次运行所需的 Runtime。 -- 已准备模型服务配置；需要查询或管理云资源时，还需准备最小权限的阿里云身份。 - -正式发布的 Skill Runtime 支持以下平台： - -| 操作系统 | 架构 | -|---|---| -| macOS | Apple Silicon（arm64） | -| Linux | x86_64 | -| Windows | x86_64 | - -最低操作系统和 Linux glibc 版本以 Skill 固定的 Runtime manifest 为准。桥接脚本会在 -下载前检查平台，平台不受支持时会直接返回错误，不会下载其他平台或 ABI 的产物。 - -### 解压到宿主 Agent 的 Skill 目录 - -下载 ZIP 后，将其直接解压到宿主 Agent 的 Skill 根目录。不同 Agent 的 Skill 根目录可能 -不同，请以宿主产品文档为准。解压后的最终结构必须是： +把 ZIP 解压到 Agent 文档指定的 Skill 目录。压缩包中已经包含顶层 `iac-code/` 目录，最终结构应为： ```text / @@ -71,131 +42,122 @@ IaC Code，也不应改用 Headless 命令。 └── iac_code.py ``` -ZIP 已经包含顶层 `iac-code/` 目录。不要再手工增加一层同名目录。安装或更新完成后，重新 -启动宿主 Agent 或新建会话，让它重新发现 Skill。 +常见宿主的安装位置： + +- **Codex**：所有项目使用 `~/.agents/skills/iac-code/`，单个仓库使用 + `<仓库>/.agents/skills/iac-code/`。详见 [Codex Skills 文档](https://developers.openai.com/codex/skills#where-codex-loads-local-skills)。 +- **Claude Code**：所有项目使用 `~/.claude/skills/iac-code/`，单个仓库使用 + `<仓库>/.claude/skills/iac-code/`。详见 [Claude Code Skills 文档](https://code.claude.com/docs/en/skills#where-skills-live)。 -### 校验安装 +安装后重启 Agent 或新建会话。也可以在解压后的 `iac-code` 目录提前验证 Runtime。 -进入解压后的 `iac-code` 目录，在 macOS 或 Linux 上运行： +macOS 或 Linux： ```bash python3 scripts/iac_code.py ensure-runtime ``` -Windows PowerShell 运行： +Windows PowerShell： ```powershell py -3 scripts\iac_code.py ensure-runtime ``` -首次运行会下载当前平台的 Runtime、校验大小和 SHA-256，并输出包含 `skillVersion`、 -`runtimeTag` 和安装位置的 JSON。已经缓存且校验通过时会直接复用，不会重复下载。 +首次使用时，桥接脚本会下载当前平台对应的 Runtime，并校验文件大小和 SHA-256 摘要。后续任务会复用 +本地已验证的副本。 ## 配置模型和阿里云身份 -Skill Runtime 与其他 IaC Code 运行方式使用相同的配置目录，默认为 `~/.iac-code/`。如果 -已经使用 REPL、Web 或 Desktop 完成配置，Skill 可以复用这些设置；也可以通过 -`IAC_CODE_CONFIG_DIR` 指向另一个配置目录。 - -在自动化环境中，可通过 Secret 管理方案提供以下环境变量： - -| 类别 | 环境变量 | 说明 | -|---|---|---| -| 模型 | `IAC_CODE_PROVIDER` | 模型提供商 | -| 模型 | `IAC_CODE_MODEL` | 模型名称 | -| 模型 | `IAC_CODE_API_KEY` | 模型服务 API Key | -| 模型 | `IAC_CODE_BASE_URL` | 可选的兼容端点覆盖 | -| 阿里云 | `ALIBABA_CLOUD_ACCESS_KEY_ID` | AccessKey ID | -| 阿里云 | `ALIBABA_CLOUD_ACCESS_KEY_SECRET` | AccessKey Secret | -| 阿里云 | `ALIBABA_CLOUD_SECURITY_TOKEN` | 使用 STS 时的安全令牌 | -| 阿里云 | `ALIBABA_CLOUD_REGION_ID` | 默认地域 | - -不要把真实密钥写入 `SKILL.md`、宿主 Agent 提示词、项目文件或命令历史。优先使用临时凭证、 -RAM Role 或 OAuth，并只授予任务实际需要的云 API 权限。完整说明参见 -[LLM 提供商](../configuration/llm-providers.md)和 +Skill 默认使用 IaC Code 的标准配置目录 `~/.iac-code/`。如果你已经在 REPL、Web 版或桌面版中配置过 +IaC Code，Skill 会复用这些设置。可以通过 `IAC_CODE_CONFIG_DIR` 指定其他配置目录。 + +在自动化环境中，请通过密钥管理方案注入模型设置和阿里云凭证。不要把凭证写入 `SKILL.md`、提示词、 +项目文件或 Shell 历史记录。建议使用临时凭证、RAM 角色或 OAuth，并只授予任务所需权限。 + +配置选项和支持的环境变量详见[模型服务](../configuration/llm-providers.md)和 [阿里云凭证](../configuration/alibaba-cloud-credentials.md)。 +## 选择工作方式 + +Skill 会根据请求选择两种模式之一： + +- **普通模式**：默认模式，适合查询或变更资源、处理模板、排查问题，以及部署目标明确的资源。 +- **Pipeline 模式**：当你明确要求使用，或需要候选架构、费用对比、方案确认和部署组成的引导流程时使用。 + +通常不需要手工选择模式，直接描述期望结果即可。只有需要方案对比流程时，才需要特别说明使用 Pipeline。 + ## 首次使用 -安装并配置后，在宿主 Agent 中新建会话，直接描述阿里云基础设施任务。例如： +在宿主 Agent 中新建会话，直接描述阿里云基础设施任务。例如： ```text -使用 iac-code 检查当前项目中的 ROS 模板，列出安全风险和修改建议，不要修改文件。 +使用 iac-code 评审当前项目中的 ROS 模板，列出安全风险和修改建议，但不要修改文件。 ``` -支持显式 Skill 语法的宿主也可以使用 `$iac-code` 指定该 Skill。宿主 Agent 应读取 -`SKILL.md`，把完整请求写入工作区内的 UTF-8 文件，并通过桥接脚本创建和跟进同一个任务； -用户不需要自己启动 A2A Server。 +在 Codex 中使用 `$iac-code`，在 Claude Code 中使用 `/iac-code`，可以显式选择 Skill。第一次请求时，Agent 会检查模型和云凭证配置、准备 +Runtime 并启动任务，不需要手工启动 A2A Server。 -预期流程如下： +执行过程中，IaC Code 可能暂停并请你： -1. 桥接脚本检查模型和阿里云配置是否就绪。 -2. 首次运行时下载并校验 Skill 固定的 IaC Code Runtime。 -3. Runtime 仅在 `127.0.0.1` 随机端口启动，并生成本次进程专用的 Bearer Token。 -4. 宿主 Agent 展示 IaC Code 返回的进度、问题、候选方案和权限请求。 -5. 任务完成后，宿主 Agent 返回最终结果和工作区内生成的文件。 +- 允许或拒绝工具及部署操作（`permission`）； +- 回答问题（`ask_user_question`）； +- 选择候选架构（`candidate_selection`）； +- 检查最终方案、价格和部署参数，然后确认、调整、重新选择或取消（`deployment_confirmation`）。 -## 更新和卸载 +回答前请检查目标资源、地域、影响和报价。最初提出部署需求，不代表已经批准后续的部署确认。任务结束后， +可以在同一 Agent 会话继续提出要求，Skill 会保留 IaC Code 对话上下文。 -手工更新时重新下载固定地址 `skill/stable/iac-code-skill.zip`，然后完整替换宿主 Skill 目录 -中的 `iac-code/`。自动更新程序可以读取 `latest.json` 比较 `skillVersion`，并通过其中的 -不可变地址和 SHA-256 下载、校验新包。每个正式 Skill 都固定到经过校验的 Runtime，不能 -只替换 `scripts/iac_code.py` 或手工修改其中的 Runtime URL 和摘要。 +IaC Code 可以根据会话语言，以英语、简体中文、西班牙语、法语、德语、日语或葡萄牙语返回进度和问题。 -卸载时删除宿主 Agent Skill 根目录中的 `iac-code/` 即可。Runtime 缓存不会随 Skill 目录 -一起删除；只有用户明确要求清理时，才执行后文的 `cache list` 和 `cache clean`。 +## 更新和卸载 -## Runtime 缓存 +手工更新时，重新下载稳定版 ZIP 并完整替换 `iac-code/` 目录。随后重启 Agent 或新建会话，让它重新加载 +Skill。不要只替换桥接脚本，也不要手工修改 Runtime 地址或摘要。 -首次使用下载的 Runtime 会缓存在 -`/skill-runtime///`，后续调用自动复用。 -普通使用无需管理该目录。需要查看占用空间或清理历史版本时，使用： +卸载时，从宿主 Agent 的 Skill 目录删除 `iac-code/`。已经下载的 Runtime 会保留在 IaC Code 配置目录， +避免影响其他安装和正在运行的任务。如果也要清理这些文件，请先运行 `cache list` 检查，再运行 +`cache clean ... --confirm`。 -- `python3 scripts/iac_code.py cache list` — 查看已安装的 Runtime 与候选包。 -- `python3 scripts/iac_code.py cache clean [--runtime-tag ] [--candidates] --confirm` — 清理 Runtime 缓存或候选包；必须显式传 `--confirm`。 +## 常见问题 -当前使用的 Runtime 和正在运行的进程会受到保护，不会被清理。Skill 包格式和运行约束由 -源码仓库中的 `skill-runtime/skill-package-contract.json` 定义，普通用户无需操作该文件。 +### 配置不完整 -## 常见问题 +如果模型服务或 API Key 配置不完整，Skill 会在创建任务前返回 `llm_not_configured`。两种 Pipeline 都要求 +配置阿里云凭证，缺失时会返回 `cloud_credentials_not_configured`。普通模式仍可执行不调用云 API 的任务， +但会提示当前无法进行云资源操作。 -### 提示配置不完整 +### Runtime 无法启动 -Skill 会在创建任务前检查配置，但不会读取或返回密钥明文： +运行 `ensure-runtime` 并查看错误信息，检查宿主 Python 版本、操作系统、架构、网络和代理设置。 +`incompatible_host` 表示当前机器不满足 Runtime 要求，应升级宿主环境或换到支持的平台，不要安装无关的 +软件包或 Runtime 规避检查。 -| 情况 | 结果 | -|---|---| -| LLM provider 或 API Key 不完整 | 返回 `llm_not_configured`，拒绝创建任务 | -| selling Pipeline 且阿里云凭证不完整 | 返回 `cloud_credentials_not_configured`，拒绝创建任务 | -| normal 模式且阿里云凭证不完整 | 可继续执行不调用云 API 的任务，但会给出预检警告 | +### 任务暂停或中断 -### 为什么执行过程中会暂停 +暂停通常表示 IaC Code 正在等待回答、权限、候选方案选择或部署确认，并非执行失败。请回答 Agent 展示的 +当前请求。如果中断后宿主会话仍然存在，请让它继续同一个任务，以便恢复已有作业，而不是重新开始。 -IaC Code 在需要确认权限、补充信息或选择方案时会暂停，宿主 Agent 会直接向用户展示： +### 管理 Runtime 磁盘占用 -- 工具或部署权限请求（`permission`）。 -- 选择题或补充信息（`ask_user_question`）。 -- Pipeline 候选方案选择（`candidate_selection`）。 +在已安装的 Skill 目录中使用： -确认前请核对目标资源、地域、预期影响和价格。拒绝操作不会被宿主 Agent 绕过；允许单次 -操作在协议中表示为 `allow_once`。 +- `python3 scripts/iac_code.py cache list`：查看已经安装的 Runtime； +- `python3 scripts/iac_code.py cache clean --runtime-tag --confirm`：删除指定的历史 Runtime； +- `python3 scripts/iac_code.py cache clean --candidates --confirm`：删除候选版本。 -> **宿主 Agent 集成说明** -> -> 桥接结果出现 `inputRequired` 时，宿主 Agent 应展示当前请求并等待应答。 -> `boundaryReached` 只表示到达一个展示或交互边界，不代表任务已经完成；宿主 Agent 应 -> 展示本次更新并继续跟进同一个任务。 +当前 Runtime 和正在被进程使用的软件包不会被清理。Windows 请把 `python3` 替换为 `py -3`。 ## 安全说明 -- Runtime 只监听 `127.0.0.1` 上的随机端口，每次启动生成独立的随机 Bearer token，桥接脚本的每个请求都携带该 token。 -- 桥接脚本把产物和结果限制在 job 工作区内，结果写入工作区的 `.iac-code-skill-results/`。 -- 预检与权限展示字段均经脱敏处理；密钥、凭证等敏感值不会出现在展示字段中。 +- Runtime 只监听随机的 `127.0.0.1` 端口，每个进程都会生成新的 Bearer Token。 +- 任务产物和结果文件保存在所选工作目录中；适用时位于 `.iac-code-skill-results/`。 +- 就绪状态和权限摘要经过脱敏，不包含凭证值。 ## 相关文档 -- [A2A 协议概述](./overview.md) -- [A2A 协议参考](./protocol-reference.md) -- [LLM 提供商](../configuration/llm-providers.md) +- [IaC Code 官方 Skills 概览](./skill-overview.md) +- [IaC Code Skill 宿主集成参考](./skill-host-integration.md) +- [A2A 协议概览](./overview.md) +- [模型服务](../configuration/llm-providers.md) - [阿里云凭证](../configuration/alibaba-cloud-credentials.md) - [运行时配置](../configuration/runtime-configuration.md) diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/a2a/skill-overview.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/a2a/skill-overview.md new file mode 100644 index 00000000..11f5d408 --- /dev/null +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/a2a/skill-overview.md @@ -0,0 +1,72 @@ +--- +sidebar_position: 1 +title: IaC Code 官方 Skills 概览 +description: 对比 IaC Code 官方 Skills，并根据使用方式选择合适的版本。 +--- + +# IaC Code 官方 Skills 概览 + +IaC Code 提供三种官方 Skill 发行形式。它们都能让用户在 Agent 对话中管理阿里云基础设施，但发行渠道和 +IaC Code Agent 的运行位置不同。 + +## 选择 Skill + +| Skill | 运行位置 | 适用场景 | +|---|---|---| +| `iac-code` | 下载到本机且经过校验的 IaC Code Runtime | 希望使用 iac-code 项目直接发布的软件包，并自行控制安装和更新。 | +| `alibabacloud-iac-code` | 同样在本地运行的 IaC Code Runtime，针对阿里云 Agent Skills 门户打包 | 通过 Skills 门户或 `npx skills` 安装、更新阿里云 Skills。 | +| `alibabacloud-ros-agent` | 通过 ROS StartChat API 调用的阿里云云端 ROS Agent | 希望直接使用云端 ROS Agent，不在本机下载 IaC Code Runtime。 | + +`iac-code` 和 `alibabacloud-iac-code` 提供相同的 IaC Code Runtime 能力。同一个 Agent 作用域中选择一种 +发行方式即可；同时安装只会造成触发范围重叠，不会增加功能。 + +`alibabacloud-ros-agent` 是独立的云端服务集成。如果需要明确选择本地 IaC Code 或云端 ROS Agent，可以将 +它与一种本地 Runtime 发行版同时安装。 + +## 获取独立发行版 + +通过固定地址下载最新稳定版： + +[下载 iac-code-skill.zip](https://ros-public-tools.oss-cn-beijing.aliyuncs.com/github-releases/aliyun/iac-code/skill/stable/iac-code-skill.zip) + +独立发行版适合手工管理 Skill 目录。它会在首次使用时下载 Runtime，并复用 `~/.iac-code/` 中的模型和 +阿里云配置。支持的宿主和配置方法详见[安装和使用 IaC Code Skill](./skill-integration.md)。 + +## 获取阿里云 Skills 门户版本 + +在[阿里云 Agent Skills 门户](https://skills.aliyun.com/)中搜索准确的 Skill 名称，或者从官方仓库安装： + +```bash +npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-iac-code +npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-ros-agent +``` + +也可以直接下载软件包： + +- [`alibabacloud-iac-code` ZIP](https://skills.aliyun.com/api/public/skills/alibabacloud-iac-code/download) · + [查看源码](https://github.com/aliyun/alibabacloud-aiops-skills/tree/master/skills/developertools/ros/alibabacloud-iac-code) +- [`alibabacloud-ros-agent` ZIP](https://skills.aliyun.com/api/public/skills/alibabacloud-ros-agent/download) · + [查看源码](https://github.com/aliyun/alibabacloud-aiops-skills/tree/master/skills/developertools/ros/alibabacloud-ros-agent) + +`npx skills` 会交互式选择支持的 Agent 和安装范围，这种方式要求 Node.js 18 或更高版本。手工下载 ZIP 时， +请将其中的顶层 Skill 目录解压到宿主支持的用户级或项目级 Skill 目录，并按需重启 Agent。 + +## 能力和配置差异 + +两种本地 Runtime 发行版都支持普通对话和 Pipeline，包括架构规划、ROS 与 Terraform 模板处理、费用估算、 +资源栈操作、部署、提问、候选方案选择、权限审批和部署确认。它们需要配置模型；任务查询或变更云资源时还需 +配置阿里云凭证。 + +云端 `alibabacloud-ros-agent` 通过 `ros:StartChat` 将会话发送给阿里云 ROS Agent。它使用宿主可用的阿里云 +身份，不需要本地 IaC Code Runtime，也不需要在本地配置模型服务。请只授予所需的 RAM 权限；明确取消远程 +任务时还会调用 `ros:StopChat`。 + +无论选择哪种发行版，批准变更或部署前都应检查目标资源、地域、影响、价格和请求的权限。不要把凭证写入 +`SKILL.md`、提示词或项目文件。 + +## 相关文档 + +- [安装和使用 IaC Code Skill](./skill-integration.md) +- [IaC Code Skill 宿主集成参考](./skill-host-integration.md) +- [阿里云凭证](../configuration/alibaba-cloud-credentials.md) +- [A2A 协议概览](./overview.md) diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/intro.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/intro.md index 25284b6d..b8b8590e 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/intro.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/intro.md @@ -6,7 +6,7 @@ description: IaC Code 的用途以及从哪里开始。 # 概览 -IaC Code 是面向云基础设施的 AI 基础设施即代码助手。它帮助云资源用户和运维人员通过终端工作流生成、部署和管理基础设施模板。架构设计面向多云工作流；当前版本支持阿里云 ROS 与 Terraform 工作流。 +IaC Code 是用于规划、生成、部署和管理云基础设施的 AI 助手。你可以通过桌面版、本地 Web 版、交互式终端、自动化接口使用，也可以把它作为 Skill 集成到其他 Agent 中。架构设计面向多云工作流；当前版本支持阿里云 ROS 与 Terraform 工作流。 核心能力： @@ -14,4 +14,11 @@ IaC Code 是面向云基础设施的 AI 基础设施即代码助手。它帮助 - **一句话到上线** — 面向阿里云 ROS，从模板到基础设施运行一站式完成：创建、更新、删除资源栈，并跨地域监控部署进度；Terraform 支持仅覆盖模板生成与转换，不包含部署。 - **云端智能加持** — 搜索云产品文档、查询资源库存、部署前估算成本；每一个决策都有真实云数据支撑。 -文档按用户任务组织。建议先阅读安装和快速开始，然后配置提供商与凭证；需要命令细节时再查看 CLI 参考。 +根据使用方式选择入口： + +- 下载[桌面版](./desktop-app.md)，直接使用图形化应用。 +- 阅读[安装](./getting-started/installation.md)和[快速开始](./getting-started/quick-start.md)，使用 REPL、无头模式或本地 [Web 版](./web-app.md)。 +- 通过 [IaC Code 官方 Skills 概览](./a2a/skill-overview.md)选择合适的发行版，让兼容的 Agent 获得 IaC Code 的阿里云基础设施能力。 +- 通过 [ACP](./acp/overview.md)、[A2A](./a2a/overview.md) 或 [AG-UI](./agui/overview.md) 将 IaC Code 集成到其他应用或服务。 + +所有入口都需要配置模型。任务需要查询、变更或部署云资源时，还需要配置[阿里云凭证](./configuration/alibaba-cloud-credentials.md)。 diff --git a/website/sidebars.ts b/website/sidebars.ts index aebb21a8..ee8530e5 100644 --- a/website/sidebars.ts +++ b/website/sidebars.ts @@ -27,7 +27,15 @@ const sidebars: SidebarsConfig = { 'cli/sessions', 'web-app', 'desktop-app', - 'a2a/skill-integration', + { + type: 'category', + label: 'IaC Code Skill', + items: [ + 'a2a/skill-overview', + 'a2a/skill-integration', + 'a2a/skill-host-integration', + ], + }, { type: 'category', label: 'MCP Integration',