@@ -1,5 +1,7 @@
 # Basic Chat — Minimal Working acli Example
 
+> **English** | [中文](README_zh.md) | [日本語](README_ja.md)
+
 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.
 
 ## Directory Structure
 
@@ -0,0 +1,114 @@
+# Basic Chat — 最小構成で動く acli の例
+
+> [English](README.md) | [中文](README_zh.md) | **日本語**
+
+最小限の設定で、Web 検索機能を備えた汎用チャットエージェントを起動する方法を示します。**すべての知能は `.acli/` の設定に存在しており、Python の起動コードは一切ありません**——`acli` をダウンロードしてそのまま実行するだけです。
+
+## ディレクトリ構成
+
+```
+basic-chat/
+└── .acli/
+    ├── config.toml                   # デフォルトの provider/model/user_name
+    ├── custom-extensions.toml        # tongyi provider の宣言 + capability/skill/shell_tool のコメントテンプレート
+    ├── hooks.toml                    # イベントフック（before/after_tool_call、on_error など）のコメントテンプレート
+    ├── system-prompt.md              # エージェントのペルソナと行動ルール
+    └── skills/
+        ├── research-topic.md         # トピックを Web 検索してブリーフィングを作成（web_search を呼び出す）
+        ├── explain-code.md           # コードのロジックを説明
+        ├── translate.md              # 中国語⇔英語の翻訳
+        └── write-poem.md             # 七言絶句を作る（純粋な prompt テンプレートのデモ）
+```
+
+## クイックスタート
+
+```bash
+pip install acli
+export DASHSCOPE_API_KEY="sk-xxx"
+
+# サンプルを ./.acli/ にマージする（同名ファイルは自動的に .acli/backup/ にバックアップされ、example restore で元に戻せます）
+acli example download basic-chat
+
+# 必要な provider を .acli/custom-extensions.toml に追加する
+# .acli/system-prompt.md を編集してエージェントのペルソナを定義する
+# .acli/skills/ に独自の skill テンプレートを追加する
+
+# 起動（cd は不要、設定はすでにカレントディレクトリにあります）
+acli
+acli --tui
+acli -c "hello"
+```
+
+> 新しいディレクトリで使いたい場合は？ `mkdir my-agent && cd my-agent && acli example download basic-chat` を実行するか、
+> `acli example download basic-chat --target my-agent` を使ってください。
+
+## プログラムとしての設定
+
+### custom-extensions.toml —— Provider の宣言
+
+acli が利用できる LLM provider を宣言します。最小構成では `[[providers]]` ブロックが1つあれば十分です：
+
+```toml
+[[providers]]
+name = "tongyi"
+base_url = "https://dashscope.aliyuncs.com/compatible-mode/v1"
+api_key_env = "DASHSCOPE_API_KEY"      # ← 環境変数名のみを保存し、sk-xxx はシェルから提供されます
+default_model = "qwen3.8-max"
+models = ["qwen3.8-max", "qwen3.7-max", "qwen3.7-plus", "qwen-turbo", "qwen-vl-max"]
+vision_models = ["qwen-vl-max"]        # ← これらのモデルが画像入力を受け付けることを acli に伝えます
+protocol = "openai"                     # ← openai / anthropic / dashscope
+```
+
+Claude / GPT / ローカルの Ollama を使いたい場合は、toml 内の対応する `[[providers]]` ブロックのコメントを外すだけです。
+
+**API Key を指定する3つの方法**（推奨度が高い順）：
+
+1. `api_key_env = "FOO_API_KEY"` —— シェルで `export FOO_API_KEY=sk-xxx` を実行する方法。toml を git にコミットしても安全です
+2. `/provider` ウィザードによる対話的な入力 —— `api_key = "ENC:..."`（端末に紐づく暗号化）が書き込まれます
+3. 平文の `api_key = "sk-xxx"` —— ローダーによって拒否されます。あくまでプレースホルダーの例示です
+
+### system-prompt.md —— エージェントのペルソナ
+
+エージェントが「何者であるか」を定義します。acli は起動時に `.acli/system-prompt.md` を自動的に読み込みます（ワークスペース側の設定が `~/.acli/system-prompt.md` より優先されます）。
+
+### skills/*.md —— Prompt テンプレート
+
+各 `.md` ファイルは、YAML フロントマターを持つ再利用可能な prompt です：
+
+```yaml
+---
+name: research-topic
+description: Web-search a topic and produce a briefing with source URLs
+arguments: [topic]
+---
+
+Use the web_search tool to research "{topic}":
+...
+```
+
+呼び出し方法：
+- `/skill research-topic quantum computing` —— 明示的な呼び出し
+- 自然言語："help me research the latest progress in quantum computing" —— LLM が使用するかどうかを判断します
+
+`research-topic` は、prompt を使って LLM に組み込みの `web_search` ツールを呼び出させ、オンラインで情報収集を行わせる方法を示しています。
+
+### config.toml —— デフォルト設定
+
+```toml
+user_name = "dashscope"
+provider = "tongyi"
+model = "qwen3.8-max"
+memory_user_id = "acli-basic"
+```
+
+## 次のステップ
+
+- **provider を追加する**：`custom-extensions.toml` に `[[providers]]` ブロックを追加します
+- **HTTP ツールを追加する**：`[[capabilities]]` + `[[capabilities.tools]]` ブロックを追加します（画像生成やリモートのワークフローエンジン呼び出しなど）
+- **ビジョン機能を追加する**：`type = "vision"` の capability ツールを追加し、テキストエージェントが必要に応じてビジョン LLM を呼び出せるようにします
+- **shell ツールを追加する**：`[[shell_tools]]` ブロックを追加して、よく使うローカルコマンドをラップします
+- **フックを追加する**：`.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）をすべてカバーしています。
+- **永続的な知識を追加する**：system prompt に**常に**表示させたいドキュメント（API インデックスなど）を `.acli/references/*.md` に配置します
+- **ペルソナを変更する**：`system-prompt.md` を編集します——例えば「コードレビュアー」「データアナリスト」「カスタマーサポート担当」に作り変えることができます
+
+完全な機能ドキュメントについては、プロジェクトルートの `README.md` を参照してください。
@@ -0,0 +1,114 @@
+# Basic Chat — 最小可用的 acli 示例
+
+> [English](README.md) | **中文** | [日本語](README_ja.md)
+
+演示如何用最少的配置启动一个具备联网搜索能力的通用聊天 Agent。**所有的智能都体现在 `.acli/` 配置中——没有任何 Python 启动代码**——直接下载并运行 `acli` 即可。
+
+## 目录结构
+
+```
+basic-chat/
+└── .acli/
+    ├── config.toml                   # 默认的 provider/model/user_name
+    ├── custom-extensions.toml        # tongyi provider 声明 + capability/skill/shell_tool 注释模板
+    ├── hooks.toml                    # 事件钩子（before/after_tool_call、on_error 等）注释模板
+    ├── system-prompt.md              # Agent 人设与行为规则
+    └── skills/
+        ├── research-topic.md         # 对某个主题进行联网搜索并生成简报（调用 web_search）
+        ├── explain-code.md           # 解释代码逻辑
+        ├── translate.md              # 中英文互译
+        └── write-poem.md             # 写一首七言绝句（演示纯 prompt 模板的用法）
+```
+
+## 快速开始
+
+```bash
+pip install acli
+export DASHSCOPE_API_KEY="sk-xxx"
+
+# 将示例合并到 ./.acli/（同名文件会自动备份到 .acli/backup/；可用 example restore 撤销）
+acli example download basic-chat
+
+# 编辑 .acli/custom-extensions.toml 添加你需要的 provider
+# 编辑 .acli/system-prompt.md 定义 Agent 人设
+# 在 .acli/skills/ 下添加你自己的 skill 模板
+
+# 启动（无需 cd，配置已在当前目录下）
+acli
+acli --tui
+acli -c "hello"
+```
+
+> 想在全新目录中使用？执行 `mkdir my-agent && cd my-agent && acli example download basic-chat`，
+> 或者使用 `acli example download basic-chat --target my-agent`。
+
+## 配置即程序
+
+### custom-extensions.toml —— Provider 声明
+
+声明 acli 可以使用哪些 LLM provider。最简配置只需要一个 `[[providers]]` 块：
+
+```toml
+[[providers]]
+name = "tongyi"
+base_url = "https://dashscope.aliyuncs.com/compatible-mode/v1"
+api_key_env = "DASHSCOPE_API_KEY"      # ← 只存储环境变量名；sk-xxx 由 shell 提供
+default_model = "qwen3.8-max"
+models = ["qwen3.8-max", "qwen3.7-max", "qwen3.7-plus", "qwen-turbo", "qwen-vl-max"]
+vision_models = ["qwen-vl-max"]        # ← 告诉 acli 这些模型支持图片输入
+protocol = "openai"                     # ← openai / anthropic / dashscope
+```
+
+想用 Claude / GPT / 本地 Ollama？只需取消 toml 中对应 `[[providers]]` 块的注释即可。
+
+**提供 API Key 的三种方式**（按推荐程度递减排序）：
+
+1. `api_key_env = "FOO_API_KEY"` —— 在 shell 中 `export FOO_API_KEY=sk-xxx`；toml 可以安全地提交到 git
+2. `/provider` 交互式向导 —— 写入 `api_key = "ENC:..."`（与本机绑定的加密存储）
+3. 明文 `api_key = "sk-xxx"` —— 会被加载器拒绝；仅作占位示例
+
+### system-prompt.md —— Agent 人设
+
+定义 Agent「是谁」。acli 启动时会自动加载 `.acli/system-prompt.md`（工作目录下的配置优先于 `~/.acli/system-prompt.md`）。
+
+### skills/*.md —— Prompt 模板
+
+每个 `.md` 文件都是一个带 YAML frontmatter 的可复用 prompt：
+
+```yaml
+---
+name: research-topic
+description: Web-search a topic and produce a briefing with source URLs
+arguments: [topic]
+---
+
+Use the web_search tool to research "{topic}":
+...
+```
+
+调用方式：
+- `/skill research-topic quantum computing` —— 显式调用
+- 自然语言："help me research the latest progress in quantum computing" —— 由 LLM 自行判断是否使用该 skill
+
+`research-topic` 演示了如何用 prompt 引导 LLM 调用内置的 `web_search` 工具来进行联网信息收集。
+
+### config.toml —— 默认配置
+
+```toml
+user_name = "dashscope"
+provider = "tongyi"
+model = "qwen3.8-max"
+memory_user_id = "acli-basic"
+```
+
+## 下一步
+
+- **添加更多 provider**：在 `custom-extensions.toml` 中添加 `[[providers]]` 块
+- **添加 HTTP 工具**：添加 `[[capabilities]]` + `[[capabilities.tools]]` 块（例如图像生成、调用远程工作流引擎）
+- **添加视觉能力**：添加一个 `type = "vision"` 的 capability 工具，让文本 Agent 可以按需调用视觉 LLM
+- **添加 shell 工具**：添加 `[[shell_tools]]` 块来封装常用的本地命令
+- **添加钩子**：在 `.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）。
+- **添加持久化知识**：把必须**始终**出现在 system prompt 中的文档（例如某个 API 索引）放到 `.acli/references/*.md`
+- **更换人设**：编辑 `system-prompt.md`——例如把它改造成「代码审查员」「数据分析师」或「客服坐席」
+
+完整功能文档请参见项目根目录的 `README.md`。
@@ -1,5 +1,7 @@
 # DashScope SDK Expert — acli Configuration-Driven Example
 
+> **English** | [中文](README_zh.md) | [日本語](README_ja.md)
+
 **Online guide**: https://help.aliyun.com/en/model-studio/dashscope-sdk-expert
 
 This example shows how to build a scenario-specific AI expert agent using **AgenticCLI (acli)**'s native configuration mechanisms.
 
@@ -0,0 +1,115 @@
+# DashScope SDK Expert —— 設定駆動型の acli の例
+
+> [English](README.md) | [中文](README_zh.md) | **日本語**
+
+**オンラインガイド**：https://help.aliyun.com/en/model-studio/dashscope-sdk-expert
+
+この例は、**AgenticCLI（acli）** のネイティブな設定機構を使って、特定のシナリオに特化した AI エキスパートエージェントを構築する方法を示しています。
+
+**基本コンセプト：設定駆動、Python によるグルーコードは不要。** エージェントのアイデンティティ、能力、スキル、ナレッジインデックスはすべて `.acli/` 配下のファイルで定義されます。サンプルをダウンロードして `acli` を実行するだけで起動できます。
+
+## ディレクトリ構成
+
+```
+dashscope-sdk-expert/
+└── .acli/                      # エージェント設定ディレクトリ
+    ├── config.toml              # モデルとユーザーの設定
+    ├── custom-extensions.toml   # Provider の宣言（tongyi）
+    ├── hooks.toml               # イベントフック
+    ├── system-prompt.md         # System prompt（エージェントのペルソナと行動ルール）
+    └── skills/                  # スキルテンプレート（use_skill によりモデルが必要に応じて読み込む）
+        ├── text-generation.md   # テキスト生成（Generation / OpenAI 互換、Python+Java）
+        ├── multimodal.md        # マルチモーダル（MultiModalConversation/ImageSynthesis/VideoSynthesis）
+        ├── speech.md            # 音声（SpeechSynthesizer/Transcription）
+        ├── retrieval.md         # 検索（Embedding/TextReRank/RAG）
+        ├── fine-tuning.md       # ファインチューニングとデプロイ（SFT/CPT/DPO/Deployments）
+        ├── agent.md             # エージェント（Application/Assistants/プラグインと MCP）
+        ├── cli.md               # dashscope CLI コマンドリファレンス
+        ├── sdk-example.md       # SDK コード例を生成
+        ├── api-doc.md           # API パラメータのドキュメントを参照
+        ├── diagnose.md          # SDK 呼び出しエラーを診断
+        ├── error-code.md        # エラーコードの説明
+        ├── explain-code.md      # コードのロジックを説明
+        └── translate.md         # 中国語⇔英語の翻訳
+```
+
+## クイックスタート
+
+```bash
+pip install acli
+export DASHSCOPE_API_KEY="sk-xxx"
+
+# サンプルを ./.acli/ にマージする（同名ファイルは自動的に .acli/backup/ にバックアップされ、example restore で元に戻せます）
+acli example download dashscope-sdk-expert
+
+# 起動 —— cd も Python の起動スクリプトも不要です
+acli
+acli --tui
+acli -c "How do I use Generation.call?"
+```
+
+## 設定駆動アプローチの仕組み
+
+### 1. system-prompt.md —— エージェントのペルソナ
+
+エージェントのアイデンティティ、知識範囲、行動ルールを定義します。これはエージェントが「何者であるか」の核心部分です：
+
+```markdown
+You are DashScope SDK Expert, an intelligent assistant for the DashScope Python SDK...
+
+## Grounded Knowledge First
+Before answering, ALWAYS verify against the actual installed SDK...
+```
+
+### 2. skills/ —— 必要に応じて読み込まれるドメイン知識ベース
+
+SDK/CLI の公開インターフェースに関する知識は、ドメインごとの skill に直接格納されています：ドメインごとに1ファイルで、モデル一覧、Python と Java の SDK シグネチャ、入出力構造、エラーコードが含まれます。API に関する質問に答える際、モデルは `use_skill` によって該当する skill を必要に応じて読み込みます——**system prompt に常駐する内容は一切ありません**——これにより最初のターンの入力トークンが約16,000文字削減されます。skill でカバーされていない詳細は、インストール済みパッケージに対する `inspect.signature` / `help()` にフォールバックします。
+
+### 3. skills/ —— タスクテンプレート
+
+各 `.md` ファイルは、フロントマターのメタデータを持つ再利用可能な prompt テンプレートです：
+
+```yaml
+---
+name: sdk-example
+description: Generate runnable DashScope SDK code examples
+arguments: [api_name]
+---
+
+Before generating code, first verify the user's installed SDK version and API signature:
+1. `run_command("python -c 'import dashscope; ...'")`
+...
+```
+
+- **name**：skill の識別子。`/skill` コマンドで呼び出します
+- **description**：短い説明。エージェントはこれを見て、いつこの skill を適用するかを判断します
+- **arguments**：テンプレート変数。呼び出し時に実際の値に置き換えられます
+
+### 4. config.toml —— 実行時設定
+
+```toml
+user_name = "dashscope"
+provider = "tongyi"
+model = "qwen3.8-max"
+memory_user_id = "acli-dashscope"
+```
+
+## このパターンを再利用する
+
+自分のシナリオ向けに AI エキスパートを作成するには：
+
+1. `acli example download dashscope-sdk-expert`（プロジェクトの `./.acli/` にマージされます）
+2. `.acli/system-prompt.md` を編集 —— 自分のエージェントのペルソナを定義します
+3. `.acli/skills/` を編集 —— 自分のドメイン知識とスキルテンプレートを追加します（モデルが必要に応じて読み込みます）
+4. `.acli/config.toml` を編集 —— 適切なモデルを選択します
+5. `acli` を実行します
+
+## 設計上のポイント
+
+| 従来のアプローチ | acli の設定駆動アプローチ |
+|---------|---------------|
+| コードにハードコードされた prompt | `system-prompt.md` ファイル |
+| シナリオごとの if-else 分岐 | `skills/*.md` テンプレートライブラリ |
+| 巨大なドキュメントをすべて prompt に詰め込む | `skills/` のドメイン知識を必要に応じて読み込み |
+| 動作を変えるにはコード修正が必要 | Markdown を編集するだけ |
+| 共有・再利用が困難 | `.acli/` ディレクトリ全体が可搬 |