Skip to content

Commit b2391c0

Browse files
agentscope-ai-javaagentscope-ai-java
committed
docs: add Spanish and Korean translations across all docs
1 parent eb2c60e commit b2391c0

70 files changed

Lines changed: 5895 additions & 44 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# DashScope Python SDK
22

3-
> **English** | [中文](README_zh.md) | [日本語](README_ja.md)
3+
> **English** | [中文](README_zh.md) | [日本語](README_ja.md) | [Español](README_es.md) | [한국어](README_ko.md)
44
55
The DashScope Python SDK provides a comprehensive interface to [Alibaba Cloud Model Studio (Bailian)](https://www.alibabacloud.com/help/en/model-studio/) APIs, covering text generation, multi-modal understanding, embeddings, reranking, image/video generation, speech synthesis & recognition, and more.
66

‎README_es.md‎

Lines changed: 1067 additions & 0 deletions
Large diffs are not rendered by default.

‎README_ja.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# DashScope Python SDK
22

3-
> [English](README.md) | [中文](README_zh.md) | **日本語**
3+
> [English](README.md) | [中文](README_zh.md) | **日本語** | [Español](README_es.md) | [한국어](README_ko.md)
44
55
DashScope Python SDK は、[Alibaba Cloud Model Studio（百煉／Bailian）](https://www.alibabacloud.com/help/en/model-studio/) の API を包括的に利用できるインターフェースを提供します。テキスト生成、マルチモーダル理解、Embedding（埋め込み）、リランキング、画像・動画生成、音声合成・音声認識など、幅広い機能をカバーしています。
66

‎README_ko.md‎

Lines changed: 1066 additions & 0 deletions
Large diffs are not rendered by default.

‎README_zh.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# DashScope Python SDK
22

3-
> [English](README.md) | **中文** | [日本語](README_ja.md)
3+
> [English](README.md) | **中文** | [日本語](README_ja.md) | [Español](README_es.md) | [한국어](README_ko.md)
44
55
DashScope Python SDK 提供了访问[阿里云百炼（Model Studio）](https://help.aliyun.com/zh/model-studio/) API 的完整接口，覆盖文本生成、多模态理解、向量（Embedding）、重排（Rerank）、图像/视频生成、语音合成与识别等能力。
66

@@ -149,11 +149,11 @@ try:
149149
response = Generation.call(model="qwen-plus", messages=[{"role": "user", "content": "Hi"}])
150150
except DashScopeException as e:
151151
# 本地校验失败时抛出，例如 InputRequired、ModelRequired、AuthenticationError
152-
print(f"请求参数有误: {e}")
152+
print(f"Invalid request: {e}")
153153
else:
154154
if response.status_code != HTTPStatus.OK:
155155
# 服务端返回的错误，例如模型名不合法、触发限流、余额不足
156-
print(f"接口报错 {response.status_code}: {response.code} - {response.message}")
156+
print(f"API error {response.status_code}: {response.code} - {response.message}")
157157
else:
158158
print(response.output.choices[0].message.content)
159159
```

‎dashscope/acli/examples/basic-chat/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Basic Chat — Minimal Working acli Example
22

3-
> **English** | [中文](README_zh.md) | [日本語](README_ja.md)
3+
> **English** | [中文](README_zh.md) | [日本語](README_ja.md) | [Español](README_es.md) | [한국어](README_ko.md)
44
55
Shows how to start a general-purpose chat agent with web search capability using minimal configuration. **All the intelligence lives in the `.acli/` configuration — there is no Python startup code** — download and run `acli` directly.
66

‎dashscope/acli/examples/basic-chat/README_es.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# Basic Chat — Ejemplo mínimo funcional de acli
2+
3+
> [English](README.md) | [中文](README_zh.md) | [日本語](README_ja.md) | **Español** | [한국어](README_ko.md)
4+
5+
Muestra cómo iniciar un agente de chat de propósito general con capacidad de búsqueda web usando una configuración mínima. **Toda la inteligencia reside en la configuración de `.acli/` — no hay código de arranque en Python** — descarga y ejecuta `acli` directamente.
6+
7+
## Estructura de directorios
8+
9+
```
10+
basic-chat/
11+
└── .acli/
12+
├── config.toml # Provider/modelo/user_name por defecto
13+
├── custom-extensions.toml # Declaración del provider tongyi + plantillas de comentarios de capability/skill/shell_tool
14+
├── hooks.toml # Plantillas de comentarios de hooks de eventos (before/after_tool_call, on_error, etc.)
15+
├── system-prompt.md # Persona del agente y reglas de comportamiento
16+
└── skills/
17+
├── research-topic.md # Busca un tema en la web y genera un resumen (llama a web_search)
18+
├── explain-code.md # Explica la lógica del código
19+
├── translate.md # Traducción chino-inglés
20+
└── write-poem.md # Escribe una cuarteta de siete caracteres (demuestra una plantilla de prompt pura)
21+
```
22+
23+
## Inicio rápido
24+
25+
```bash
26+
pip install acli
27+
export DASHSCOPE_API_KEY="sk-xxx"
28+
29+
# Fusiona el ejemplo en ./.acli/ (los archivos con el mismo nombre se respaldan automáticamente en .acli/backup/; deshazlo con example restore)
30+
acli example download basic-chat
31+
32+
# Edita .acli/custom-extensions.toml para añadir los providers que necesites
33+
# Edita .acli/system-prompt.md para definir la persona del agente
34+
# Añade tus propias plantillas de skill en .acli/skills/
35+
36+
# Inicia (no hace falta cd; la configuración ya está en el directorio actual)
37+
acli
38+
acli --tui
39+
acli -c "hello"
40+
```
41+
42+
> ¿Quieres usarlo en un directorio nuevo? `mkdir my-agent && cd my-agent && acli example download basic-chat`,
43+
> o usa `acli example download basic-chat --target my-agent`.
44+
45+
## La configuración como programa
46+
47+
### custom-extensions.toml — Declaraciones de providers
48+
49+
Declara qué providers de LLM puede usar acli. Una configuración mínima solo necesita un bloque `[[providers]]`:
50+
51+
```toml
52+
[[providers]]
53+
name = "tongyi"
54+
base_url = "https://dashscope.aliyuncs.com/compatible-mode/v1"
55+
api_key_env = "DASHSCOPE_API_KEY" # ← solo guarda el nombre de la variable de entorno; el shell provee el sk-xxx
56+
default_model = "qwen3.8-max"
57+
models = ["qwen3.8-max", "qwen3.7-max", "qwen3.7-plus", "qwen-turbo", "qwen-vl-max"]
58+
vision_models = ["qwen-vl-max"] # ← le indica a acli que estos modelos aceptan entrada de imagen
59+
protocol = "openai" # ← openai / anthropic / dashscope
60+
```
61+
62+
¿Quieres Claude / GPT / un Ollama local? Solo descomenta el bloque `[[providers]]` correspondiente en el toml.
63+
64+
**Tres formas de proporcionar una API key** (en orden decreciente de recomendación):
65+
66+
1. `api_key_env = "FOO_API_KEY"` — `export FOO_API_KEY=sk-xxx` en el shell; el toml se puede subir a git de forma segura
67+
2. Asistente interactivo `/provider` — escribe `api_key = "ENC:..."` (cifrado vinculado a la máquina)
68+
3. Texto plano `api_key = "sk-xxx"` — rechazado por el cargador; solo es un ejemplo ilustrativo
69+
70+
### system-prompt.md — Persona del agente
71+
72+
Define quién "es" el agente. acli carga automáticamente `.acli/system-prompt.md` al iniciar (la configuración del workspace tiene prioridad sobre `~/.acli/system-prompt.md`).
73+
74+
### skills/*.md — Plantillas de prompt
75+
76+
Cada archivo `.md` es un prompt reutilizable con frontmatter YAML:
77+
78+
```yaml
79+
---
80+
name: research-topic
81+
description: Web-search a topic and produce a briefing with source URLs
82+
arguments: [topic]
83+
---
84+
85+
Use the web_search tool to research "{topic}":
86+
...
87+
```
88+
89+
Cómo invocarlo:
90+
- `/skill research-topic quantum computing` — invocación explícita
91+
- Lenguaje natural: "help me research the latest progress in quantum computing" — el LLM decide si usarlo
92+
93+
`research-topic` muestra cómo usar un prompt para guiar al LLM a llamar a la herramienta integrada `web_search` para recopilar información en línea.
94+
95+
### config.toml — Valores por defecto
96+
97+
```toml
98+
user_name = "dashscope"
99+
provider = "tongyi"
100+
model = "qwen3.8-max"
101+
memory_user_id = "acli-basic"
102+
```
103+
104+
## Próximos pasos
105+
106+
- **Añadir más providers**: añade bloques `[[providers]]` en `custom-extensions.toml`
107+
- **Añadir herramientas HTTP**: añade bloques `[[capabilities]]` + `[[capabilities.tools]]` (por ejemplo, generación de imágenes, llamar a un motor de workflows remoto)
108+
- **Añadir capacidad de visión**: añade una herramienta de capability con `type = "vision"` para que el agente de texto pueda llamar a un LLM de visión bajo demanda
109+
- **Añadir herramientas de shell**: añade bloques `[[shell_tools]]` para envolver comandos locales comunes
110+
- **Añadir hooks**: configura hooks pre/post de llamada a herramientas en `.acli/hooks.toml` (por ejemplo, `py_compile` automático tras escribir un archivo `.py`, confirmación antes de `pip install`, bloquear el borrado de archivos). Consulta la plantilla en `.acli/hooks.toml`, que cubre los 5 eventos (`before_tool_call` / `after_tool_call` / `on_error` / `on_message` / `on_response`) × 6 acciones (run/block/confirm/warn/alert/log).
111+
- **Añadir conocimiento persistente**: coloca en `.acli/references/*.md` los documentos que deban aparecer **siempre** en el system prompt (por ejemplo, un índice de API)
112+
- **Cambiar la persona**: edita `system-prompt.md` — por ejemplo, conviértelo en un "revisor de código", "analista de datos" o "agente de atención al cliente"
113+
114+
Consulta el `README.md` de la raíz del proyecto para la documentación completa de funcionalidades.

‎dashscope/acli/examples/basic-chat/README_ja.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Basic Chat — 最小構成で動く acli の例
22

3-
> [English](README.md) | [中文](README_zh.md) | **日本語**
3+
> [English](README.md) | [中文](README_zh.md) | **日本語** | [Español](README_es.md) | [한국어](README_ko.md)
44
55
最小限の設定で、Web 検索機能を備えた汎用チャットエージェントを起動する方法を示します。**すべての知能は `.acli/` の設定に存在しており、Python の起動コードは一切ありません**——`acli` をダウンロードしてそのまま実行するだけです。
66

‎dashscope/acli/examples/basic-chat/README_ko.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# Basic Chat — 최소한으로 동작하는 acli 예제
2+
3+
> [English](README.md) | [中文](README_zh.md) | [日本語](README_ja.md) | [Español](README_es.md) | **한국어**
4+
5+
최소한의 설정으로 웹 검색 기능을 갖춘 범용 채팅 에이전트를 시작하는 방법을 보여줍니다. **모든 지능은 `.acli/` 설정에 담겨 있으며, Python 시작 코드는 전혀 없습니다** — `acli`를 다운로드해서 바로 실행하면 됩니다.
6+
7+
## 디렉터리 구조
8+
9+
```
10+
basic-chat/
11+
└── .acli/
12+
├── config.toml # 기본 provider/model/user_name
13+
├── custom-extensions.toml # tongyi provider 선언 + capability/skill/shell_tool 주석 템플릿
14+
├── hooks.toml # 이벤트 훅(before/after_tool_call, on_error 등) 주석 템플릿
15+
├── system-prompt.md # 에이전트 페르소나와 행동 규칙
16+
└── skills/
17+
├── research-topic.md # 주제를 웹 검색하여 브리핑 작성(web_search 호출)
18+
├── explain-code.md # 코드 로직 설명
19+
├── translate.md # 중국어-영어 번역
20+
└── write-poem.md # 칠언절구 작성(순수 프롬프트 템플릿 예시)
21+
```
22+
23+
## 빠른 시작
24+
25+
```bash
26+
pip install acli
27+
export DASHSCOPE_API_KEY="sk-xxx"
28+
29+
# 예제를 ./.acli/ 에 병합합니다(동일한 이름의 파일은 .acli/backup/ 에 자동 백업되며, example restore로 되돌릴 수 있습니다)
30+
acli example download basic-chat
31+
32+
# 필요한 provider를 추가하려면 .acli/custom-extensions.toml을 수정하세요
33+
# 에이전트 페르소나를 정의하려면 .acli/system-prompt.md를 수정하세요
34+
# .acli/skills/ 아래에 자신만의 skill 템플릿을 추가하세요
35+
36+
# 시작(cd 불필요, 설정이 이미 현재 디렉터리에 있습니다)
37+
acli
38+
acli --tui
39+
acli -c "hello"
40+
```
41+
42+
> 새 디렉터리에서 사용하고 싶다면? `mkdir my-agent && cd my-agent && acli example download basic-chat`를 실행하거나,
43+
> `acli example download basic-chat --target my-agent`를 사용하세요.
44+
45+
## 프로그램으로서의 설정
46+
47+
### custom-extensions.toml — Provider 선언
48+
49+
acli가 사용할 수 있는 LLM provider를 선언합니다. 최소 설정은 `[[providers]]` 블록 하나만 있으면 됩니다:
50+
51+
```toml
52+
[[providers]]
53+
name = "tongyi"
54+
base_url = "https://dashscope.aliyuncs.com/compatible-mode/v1"
55+
api_key_env = "DASHSCOPE_API_KEY" # ← 환경 변수 이름만 저장하며, sk-xxx는 셸에서 제공됩니다
56+
default_model = "qwen3.8-max"
57+
models = ["qwen3.8-max", "qwen3.7-max", "qwen3.7-plus", "qwen-turbo", "qwen-vl-max"]
58+
vision_models = ["qwen-vl-max"] # ← 이 모델들이 이미지 입력을 받을 수 있음을 acli에 알려줍니다
59+
protocol = "openai" # ← openai / anthropic / dashscope
60+
```
61+
62+
Claude / GPT / 로컬 Ollama를 사용하고 싶다면, toml에서 해당 `[[providers]]` 블록의 주석을 해제하면 됩니다.
63+
64+
**API Key를 제공하는 세 가지 방법**(권장 순서대로):
65+
66+
1. `api_key_env = "FOO_API_KEY"` — 셸에서 `export FOO_API_KEY=sk-xxx` 실행; toml을 git에 안전하게 커밋할 수 있습니다
67+
2. `/provider` 대화형 마법사 — `api_key = "ENC:..."`(기기에 종속된 암호화)를 기록합니다
68+
3. 평문 `api_key = "sk-xxx"` — 로더에 의해 거부됩니다; 자리 표시용 예시일 뿐입니다
69+
70+
### system-prompt.md — 에이전트 페르소나
71+
72+
에이전트가 "누구인지"를 정의합니다. acli는 시작 시 `.acli/system-prompt.md`를 자동으로 로드합니다(워크스페이스 설정이 `~/.acli/system-prompt.md`보다 우선합니다).
73+
74+
### skills/*.md — 프롬프트 템플릿
75+
76+
각 `.md` 파일은 YAML frontmatter가 포함된 재사용 가능한 프롬프트입니다:
77+
78+
```yaml
79+
---
80+
name: research-topic
81+
description: Web-search a topic and produce a briefing with source URLs
82+
arguments: [topic]
83+
---
84+
85+
Use the web_search tool to research "{topic}":
86+
...
87+
```
88+
89+
호출 방법:
90+
- `/skill research-topic quantum computing` — 명시적 호출
91+
- 자연어: "help me research the latest progress in quantum computing" — LLM이 사용 여부를 판단합니다
92+
93+
`research-topic`은 프롬프트를 사용하여 LLM이 내장된 `web_search` 도구를 호출해 온라인 정보를 수집하도록 유도하는 방법을 보여줍니다.
94+
95+
### config.toml — 기본값
96+
97+
```toml
98+
user_name = "dashscope"
99+
provider = "tongyi"
100+
model = "qwen3.8-max"
101+
memory_user_id = "acli-basic"
102+
```
103+
104+
## 다음 단계
105+
106+
- **더 많은 provider 추가**: `custom-extensions.toml`에 `[[providers]]` 블록을 추가하세요
107+
- **HTTP 도구 추가**: `[[capabilities]]` + `[[capabilities.tools]]` 블록을 추가하세요(예: 이미지 생성, 원격 워크플로 엔진 호출)
108+
- **비전 기능 추가**: `type = "vision"`인 capability 도구를 추가하여 텍스트 에이전트가 필요할 때 비전 LLM을 호출할 수 있게 하세요
109+
- **셸 도구 추가**: 자주 쓰는 로컬 명령을 감싸는 `[[shell_tools]]` 블록을 추가하세요
110+
- **훅 추가**: `.acli/hooks.toml`에서 도구 호출 전/후 훅을 설정하세요(예: `.py` 파일 작성 후 자동 `py_compile`, `pip install` 전 확인, 파일 삭제 차단). `.acli/hooks.toml`의 템플릿을 참고하세요. 5가지 이벤트(`before_tool_call` / `after_tool_call` / `on_error` / `on_message` / `on_response`) × 6가지 액션(run/block/confirm/warn/alert/log)을 모두 다룹니다.
111+
- **영구 지식 추가**: system prompt에 **항상** 표시되어야 하는 문서(예: API 색인)를 `.acli/references/*.md`에 두세요
112+
- **페르소나 변경**: `system-prompt.md`를 수정하세요 — 예를 들어 "코드 리뷰어", "데이터 분석가", "고객 지원 담당자"로 바꿀 수 있습니다
113+
114+
전체 기능 문서는 프로젝트 루트의 `README.md`를 참고하세요.

‎dashscope/acli/examples/basic-chat/README_zh.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Basic Chat — 最小可用的 acli 示例
22

3-
> [English](README.md) | **中文** | [日本語](README_ja.md)
3+
> [English](README.md) | **中文** | [日本語](README_ja.md) | [Español](README_es.md) | [한국어](README_ko.md)
44
55
演示如何用最少的配置启动一个具备联网搜索能力的通用聊天 Agent。**所有的智能都体现在 `.acli/` 配置中——没有任何 Python 启动代码**——直接下载并运行 `acli` 即可。
66

0 commit comments

Comments
 (0)