From 142ef2a3f42098443e0f2115077598b38627c462 Mon Sep 17 00:00:00 2001
From: sunrisepeak <speakshen@163.com>
Date: Wed, 10 Jun 2026 10:47:47 +0800
Subject: [PATCH 1/3] docs: mcpp-first README; move xmake usage to
 docs/<lang>/xmake.md

README now leads with the mcpp ecosystem workflow (mcpp new --template
llmapi / mcpp add llmapi) like imgui-m; the xmake package usage moved
from README into docs/{en,zh,zh-hant}/xmake.md and getting-started is
rewritten mcpp-first. All three README languages stay in sync.
---
 README.md                       | 117 ++++++++++++++++----------------
 README.zh.hant.md               |  89 +++++++++++++++---------
 README.zh.md                    |  89 +++++++++++++++---------
 docs/en/README.md               |   1 +
 docs/en/getting-started.md      |  49 +++++++------
 docs/en/xmake.md                |  47 +++++++++++++
 docs/zh-hant/README.md          |   1 +
 docs/zh-hant/getting-started.md |  49 +++++++------
 docs/zh-hant/xmake.md           |  45 ++++++++++++
 docs/zh/README.md               |   1 +
 docs/zh/getting-started.md      |  49 +++++++------
 docs/zh/xmake.md                |  45 ++++++++++++
 12 files changed, 402 insertions(+), 180 deletions(-)
 create mode 100644 docs/en/xmake.md
 create mode 100644 docs/zh-hant/xmake.md
 create mode 100644 docs/zh/xmake.md

diff --git a/README.md b/README.md
index 5be4e2a..ca41fb2 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,8 @@
 # llmapi
 
-> Modern C++23 LLM client built with modules
+> Modern C++23 LLM client built with modules — `import` and chat, OpenAI-compatible, template-ready
 
+[![Release](https://img.shields.io/github/v/release/mcpplibs/llmapi)](https://github.com/mcpplibs/llmapi/releases)
 [![C++23](https://img.shields.io/badge/C%2B%2B-23-blue.svg)](https://en.cppreference.com/w/cpp/23)
 [![Module](https://img.shields.io/badge/module-ok-green.svg)](https://en.cppreference.com/w/cpp/language/modules)
 [![License](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](LICENSE)
@@ -9,20 +10,37 @@
 
 | English - [简体中文](README.zh.md) - [繁體中文](README.zh.hant.md) |
 |:---:|
-| [Documentation](docs/README.md) - [English Docs](docs/en/README.md) - [中文文档](docs/zh/README.md) - [繁體中文文件](docs/zh-hant/README.md) |
+| [mcpp build tool](https://github.com/mcpp-community/mcpp) · [package index](https://github.com/mcpp-community/mcpp-index) · [Documentation](docs/README.md) · [Issues](https://github.com/mcpplibs/llmapi/issues) |
 
 `llmapi` provides a typed `Client<Provider>` API for chat, streaming, embeddings, tool calls, and conversation persistence. The default config alias `Config` maps to OpenAI-style providers, so the common case does not need an explicit `openai::OpenAI` wrapper.
 
-## Features
+## Quick Start (mcpp)
 
-- `import mcpplibs.llmapi` with C++23 modules
-- Strongly typed messages, tools, and response structs
-- Sync, async, and streaming chat APIs
-- Embeddings via the OpenAI provider
-- Conversation save/load helpers
-- OpenAI-compatible endpoint support through `openai::Config::baseUrl`
+```bash
+mcpp new myagent --template llmapi && cd myagent
+export OPENAI_API_KEY="sk-..."
+mcpp run
+```
+
+Templates ship with the library and version-track it automatically:
+
+```bash
+mcpp new --list-templates llmapi              # list available templates
+mcpp new mybot --template llmapi:chat        # interactive streaming chat CLI
+mcpp new mybot --template llmapi:anthropic   # Anthropic provider
+mcpp new mybot --template llmapi:deepseek    # OpenAI-compatible endpoint (DeepSeek)
+```
 
-## Quick Start
+Or add it to an existing mcpp project:
+
+```bash
+mcpp add llmapi
+```
+
+```toml
+[dependencies.mcpplibs]
+llmapi = "0.2.7"
+```
 
 ```cpp
 import mcpplibs.llmapi;
@@ -33,7 +51,7 @@ int main() {
 
     auto apiKey = std::getenv("OPENAI_API_KEY");
     if (!apiKey) {
-        std::cerr << "OPENAI_API_KEY not set\n";
+        std::println(stderr, "OPENAI_API_KEY not set");
         return 1;
     }
 
@@ -45,11 +63,30 @@ int main() {
     client.system("You are a concise assistant.");
     auto resp = client.chat("Explain why C++23 modules are useful in two sentences.");
 
-    std::cout << resp.text() << '\n';
+    std::println("{}", resp.text());
     return 0;
 }
 ```
 
+## Features
+
+- `import mcpplibs.llmapi` with C++23 modules
+- Strongly typed messages, tools, and response structs
+- Sync, async, and streaming chat APIs
+- Embeddings via the OpenAI provider
+- Conversation save/load helpers
+- OpenAI-compatible endpoint support through `openai::Config::baseUrl`
+- Project templates: `mcpp new <name> --template llmapi[:<template>]`
+
+## Templates
+
+| Template | Description |
+|---|---|
+| `openai` (default) | Minimal OpenAI chat — one request, one answer |
+| `chat` | Interactive streaming chat CLI (OpenAI) |
+| `anthropic` | Anthropic (Claude) chat |
+| `deepseek` | OpenAI-compatible endpoint via `baseUrl` (DeepSeek) |
+
 ## Providers
 
 - `openai::OpenAI` for OpenAI chat, streaming, embeddings, and OpenAI-compatible endpoints
@@ -59,65 +96,27 @@ int main() {
 Compatible endpoints can reuse the OpenAI provider:
 
 ```cpp
-auto provider = openai::OpenAI({
+auto client = Client(Config{
     .apiKey = std::getenv("DEEPSEEK_API_KEY"),
     .baseUrl = std::string(URL::DeepSeek),
     .model = "deepseek-chat",
 });
 ```
 
-## Build And Run
-
-```bash
-xmake
-xmake run hello_mcpp
-xmake run basic
-xmake run chat
-```
-
-## Package Usage
-
-```lua
-add_repositories("mcpplibs-index https://github.com/mcpplibs/mcpplibs-index.git")
-add_requires("llmapi 0.1.0")
-
-target("demo")
-    set_kind("binary")
-    set_languages("c++23")
-    set_policy("build.c++.modules", true)
-    add_files("src/*.cpp")
-    add_packages("llmapi")
-```
-
-See [docs/en/getting-started.md](docs/en/getting-started.md), [docs/en/providers.md](docs/en/providers.md), and [docs/en/README.md](docs/en/README.md) for more setup and readiness detail.
-
-## 使用 mcpp 构建
-
-### 添加依赖
-
-```bash
-mcpp add llmapi@0.2.5
-```
-
-或在 `mcpp.toml` 中手动添加：
-
-```toml
-[dependencies]
-llmapi = "0.2.5"
-```
-
-### 构建
+## Build From Source
 
 ```bash
+git clone https://github.com/mcpplibs/llmapi.git && cd llmapi
 mcpp build
 ```
 
-### 代码示例
+## Documentation
 
-```cpp
-import mcpplibs.llmapi;
-// ... usage example
-```
+- [Getting Started](docs/en/getting-started.md)
+- [Providers](docs/en/providers.md)
+- [C++ API Guide](docs/en/cpp-api.md)
+- [Using llmapi with xmake](docs/en/xmake.md)
+- [Docs index](docs/README.md)
 
 ## License
 
diff --git a/README.zh.hant.md b/README.zh.hant.md
index fab6078..16ef282 100644
--- a/README.zh.hant.md
+++ b/README.zh.hant.md
@@ -1,7 +1,8 @@
 # llmapi
 
-> 使用 C++23 模組建構的現代 LLM 客戶端
+> 使用 C++23 模組建構的現代 LLM 客戶端 — `import` 即聊天 · OpenAI 相容 · 模板開箱即用
 
+[![Release](https://img.shields.io/github/v/release/mcpplibs/llmapi)](https://github.com/mcpplibs/llmapi/releases)
 [![C++23](https://img.shields.io/badge/C%2B%2B-23-blue.svg)](https://en.cppreference.com/w/cpp/23)
 [![Module](https://img.shields.io/badge/module-ok-green.svg)](https://en.cppreference.com/w/cpp/language/modules)
 [![License](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](LICENSE)
@@ -9,20 +10,37 @@
 
 | [English](README.md) - [简体中文](README.zh.md) - 繁體中文 |
 |:---:|
-| [文件導覽](docs/README.md) - [繁體中文文件](docs/zh-hant/README.md) - [English Docs](docs/en/README.md) - [简体中文文档](docs/zh/README.md) |
+| [mcpp 建置工具](https://github.com/mcpp-community/mcpp) · [套件索引 mcpp-index](https://github.com/mcpp-community/mcpp-index) · [文件導覽](docs/README.md) · [Issues](https://github.com/mcpplibs/llmapi/issues) |
 
 `llmapi` 提供型別化的 `Client<Provider>` API，涵蓋聊天、串流輸出、embeddings、工具呼叫與對話持久化。預設別名 `Config` 對應 OpenAI 風格設定，常見情況下不需要顯式寫出 `openai::OpenAI(...)`。
 
-## 特性
+## 快速開始(mcpp)
 
-- C++23 模組：`import mcpplibs.llmapi`
-- 強型別訊息、工具與回應結構
-- 同步、非同步、串流聊天介面
-- OpenAI Provider 支援 embeddings
-- 支援儲存 / 載入對話歷史
-- 可透過 `baseUrl` 存取 OpenAI 相容端點
+```bash
+mcpp new myagent --template llmapi && cd myagent
+export OPENAI_API_KEY="sk-..."
+mcpp run
+```
+
+模板隨函式庫發佈、版本自動對齊:
+
+```bash
+mcpp new --list-templates llmapi              # 列出函式庫提供的模板
+mcpp new mybot --template llmapi:chat        # 互動式串流聊天 CLI
+mcpp new mybot --template llmapi:anthropic   # Anthropic Provider
+mcpp new mybot --template llmapi:deepseek    # OpenAI 相容端點(DeepSeek)
+```
+
+或在既有 mcpp 專案中接入:
+
+```bash
+mcpp add llmapi
+```
 
-## 快速開始
+```toml
+[dependencies.mcpplibs]
+llmapi = "0.2.7"
+```
 
 ```cpp
 import mcpplibs.llmapi;
@@ -33,7 +51,7 @@ int main() {
 
     auto apiKey = std::getenv("OPENAI_API_KEY");
     if (!apiKey) {
-        std::cerr << "OPENAI_API_KEY not set\n";
+        std::println(stderr, "OPENAI_API_KEY not set");
         return 1;
     }
 
@@ -45,11 +63,30 @@ int main() {
     client.system("You are a concise assistant.");
     auto resp = client.chat("用兩句話解釋 C++23 模組的價值。");
 
-    std::cout << resp.text() << '\n';
+    std::println("{}", resp.text());
     return 0;
 }
 ```
 
+## 特性
+
+- C++23 模組：`import mcpplibs.llmapi`
+- 強型別訊息、工具與回應結構
+- 同步、非同步、串流聊天介面
+- OpenAI Provider 支援 embeddings
+- 支援儲存 / 載入對話歷史
+- 可透過 `baseUrl` 存取 OpenAI 相容端點
+- 專案模板：`mcpp new <name> --template llmapi[:<template>]`
+
+## 模板
+
+| 模板 | 說明 |
+|---|---|
+| `openai`(預設) | 最小 OpenAI 聊天 — 一問一答 |
+| `chat` | 互動式串流聊天 CLI(OpenAI) |
+| `anthropic` | Anthropic(Claude)聊天 |
+| `deepseek` | 透過 `baseUrl` 走 OpenAI 相容端點(DeepSeek) |
+
 ## Provider
 
 - `Config`：`openai::Config` 的匯出別名，預設走 OpenAI 風格
@@ -66,30 +103,20 @@ auto client = Client(Config{
 });
 ```
 
-## 建置與執行
+## 原始碼建置
 
 ```bash
-xmake
-xmake run hello_mcpp
-xmake run basic
-xmake run chat
+git clone https://github.com/mcpplibs/llmapi.git && cd llmapi
+mcpp build
 ```
 
-## 套件管理使用
-
-```lua
-add_repositories("mcpplibs-index https://github.com/mcpplibs/mcpplibs-index.git")
-add_requires("llmapi 0.1.0")
-
-target("demo")
-    set_kind("binary")
-    set_languages("c++23")
-    set_policy("build.c++.modules", true)
-    add_files("src/*.cpp")
-    add_packages("llmapi")
-```
+## 文件
 
-更多內容見 [docs/zh-hant/getting-started.md](docs/zh-hant/getting-started.md)、[docs/zh-hant/providers.md](docs/zh-hant/providers.md) 與 [docs/zh-hant/README.md](docs/zh-hant/README.md)。
+- [快速上手](docs/zh-hant/getting-started.md)
+- [Provider 設定](docs/zh-hant/providers.md)
+- [C++ API 指南](docs/zh-hant/cpp-api.md)
+- [使用 xmake 整合 llmapi](docs/zh-hant/xmake.md)
+- [文件導覽](docs/README.md)
 
 ## 授權
 
diff --git a/README.zh.md b/README.zh.md
index 89e4b9d..7da308c 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -1,7 +1,8 @@
 # llmapi
 
-> 使用 C++23 模块构建的现代 LLM 客户端
+> 使用 C++23 模块构建的现代 LLM 客户端 — `import` 即聊天 · OpenAI 兼容 · 模板开箱即用
 
+[![Release](https://img.shields.io/github/v/release/mcpplibs/llmapi)](https://github.com/mcpplibs/llmapi/releases)
 [![C++23](https://img.shields.io/badge/C%2B%2B-23-blue.svg)](https://en.cppreference.com/w/cpp/23)
 [![Module](https://img.shields.io/badge/module-ok-green.svg)](https://en.cppreference.com/w/cpp/language/modules)
 [![License](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](LICENSE)
@@ -9,20 +10,37 @@
 
 | [English](README.md) - 简体中文 - [繁體中文](README.zh.hant.md) |
 |:---:|
-| [文档导航](docs/README.md) - [中文文档](docs/zh/README.md) - [English Docs](docs/en/README.md) - [繁體中文文件](docs/zh-hant/README.md) |
+| [mcpp 构建工具](https://github.com/mcpp-community/mcpp) · [包索引 mcpp-index](https://github.com/mcpp-community/mcpp-index) · [文档导航](docs/README.md) · [Issues](https://github.com/mcpplibs/llmapi/issues) |
 
 `llmapi` 提供类型化的 `Client<Provider>` API，覆盖聊天、流式输出、嵌入、工具调用与对话持久化。默认别名 `Config` 对应 OpenAI 风格配置，常见场景不需要显式写 `openai::OpenAI(...)`。
 
-## 特性
+## 快速开始(mcpp)
 
-- C++23 模块：`import mcpplibs.llmapi`
-- 强类型消息、工具与响应结构
-- 同步、异步、流式聊天接口
-- OpenAI Provider 支持 embeddings
-- 支持保存 / 加载对话历史
-- 可通过 `baseUrl` 访问 OpenAI 兼容端点
+```bash
+mcpp new myagent --template llmapi && cd myagent
+export OPENAI_API_KEY="sk-..."
+mcpp run
+```
+
+模板随库分发、版本自动对齐:
+
+```bash
+mcpp new --list-templates llmapi              # 列出库提供的模板
+mcpp new mybot --template llmapi:chat        # 交互式流式聊天 CLI
+mcpp new mybot --template llmapi:anthropic   # Anthropic Provider
+mcpp new mybot --template llmapi:deepseek    # OpenAI 兼容端点(DeepSeek)
+```
+
+或在已有 mcpp 项目中接入:
+
+```bash
+mcpp add llmapi
+```
 
-## 快速开始
+```toml
+[dependencies.mcpplibs]
+llmapi = "0.2.7"
+```
 
 ```cpp
 import mcpplibs.llmapi;
@@ -33,7 +51,7 @@ int main() {
 
     auto apiKey = std::getenv("OPENAI_API_KEY");
     if (!apiKey) {
-        std::cerr << "OPENAI_API_KEY not set\n";
+        std::println(stderr, "OPENAI_API_KEY not set");
         return 1;
     }
 
@@ -45,11 +63,30 @@ int main() {
     client.system("You are a concise assistant.");
     auto resp = client.chat("用两句话解释 C++23 模块的价值。");
 
-    std::cout << resp.text() << '\n';
+    std::println("{}", resp.text());
     return 0;
 }
 ```
 
+## 特性
+
+- C++23 模块：`import mcpplibs.llmapi`
+- 强类型消息、工具与响应结构
+- 同步、异步、流式聊天接口
+- OpenAI Provider 支持 embeddings
+- 支持保存 / 加载对话历史
+- 可通过 `baseUrl` 访问 OpenAI 兼容端点
+- 项目模板：`mcpp new <name> --template llmapi[:<template>]`
+
+## 模板
+
+| 模板 | 说明 |
+|---|---|
+| `openai`(默认) | 最小 OpenAI 聊天 — 一问一答 |
+| `chat` | 交互式流式聊天 CLI(OpenAI) |
+| `anthropic` | Anthropic(Claude)聊天 |
+| `deepseek` | 通过 `baseUrl` 走 OpenAI 兼容端点(DeepSeek) |
+
 ## Provider
 
 - `Config`：`openai::Config` 的导出别名，默认走 OpenAI 风格
@@ -66,30 +103,20 @@ auto client = Client(Config{
 });
 ```
 
-## 构建与运行
+## 源码构建
 
 ```bash
-xmake
-xmake run hello_mcpp
-xmake run basic
-xmake run chat
+git clone https://github.com/mcpplibs/llmapi.git && cd llmapi
+mcpp build
 ```
 
-## 包管理使用
-
-```lua
-add_repositories("mcpplibs-index https://github.com/mcpplibs/mcpplibs-index.git")
-add_requires("llmapi 0.1.0")
-
-target("demo")
-    set_kind("binary")
-    set_languages("c++23")
-    set_policy("build.c++.modules", true)
-    add_files("src/*.cpp")
-    add_packages("llmapi")
-```
+## 文档
 
-更多内容见 [docs/zh/getting-started.md](docs/zh/getting-started.md)、[docs/zh/providers.md](docs/zh/providers.md) 与 [docs/zh/README.md](docs/zh/README.md)。
+- [快速上手](docs/zh/getting-started.md)
+- [Provider 配置](docs/zh/providers.md)
+- [C++ API 指南](docs/zh/cpp-api.md)
+- [使用 xmake 集成 llmapi](docs/zh/xmake.md)
+- [文档导航](docs/README.md)
 
 ## 许可证
 
diff --git a/docs/en/README.md b/docs/en/README.md
index f014e96..ccf62c2 100644
--- a/docs/en/README.md
+++ b/docs/en/README.md
@@ -15,6 +15,7 @@ Language:
 - [Examples](examples.md) - chat, streaming, embeddings, and tool flows
 - [Providers](providers.md) - OpenAI, Anthropic, and compatible endpoints
 - [Advanced Usage](advanced.md) - persistence, async calls, and custom configuration
+- [Using llmapi with xmake](xmake.md) - consume the library from an xmake project
 
 ## What The Library Provides
 
diff --git a/docs/en/getting-started.md b/docs/en/getting-started.md
index 27332d6..366b7cb 100644
--- a/docs/en/getting-started.md
+++ b/docs/en/getting-started.md
@@ -2,26 +2,38 @@
 
 ## Prerequisites
 
-- **C++ Compiler**: GCC 14+, Clang 18+, or MSVC 2022+ with C++23 support
-- **Build System**: [xmake](https://xmake.io/) 3.0.0+
-- **Dependencies**: `mbedtls` is resolved automatically by xmake
+- **Build Tool**: [mcpp](https://github.com/mcpp-community/mcpp) — toolchain and
+  dependencies (e.g. `tinyhttps`) are resolved automatically
+- Alternatively the library can be consumed from xmake — see
+  [Using llmapi with xmake](xmake.md)
 
 ## Installation
 
-### Using xmake Package Manager
+### Start From a Template (recommended)
 
-Add to your `xmake.lua`:
+```bash
+mcpp new myagent --template llmapi
+cd myagent
+mcpp run
+```
 
-```lua
-add_repositories("mcpplibs-index git@github.com:mcpplibs/mcpplibs-index.git")
-add_requires("llmapi 0.1.0")
+List the templates the library ships:
 
-target("myapp")
-    set_kind("binary")
-    set_languages("c++23")
-    set_policy("build.c++.modules", true)
-    add_files("src/*.cpp")
-    add_packages("llmapi")
+```bash
+mcpp new --list-templates llmapi
+```
+
+### Add To an Existing Project
+
+```bash
+mcpp add llmapi
+```
+
+Or declare it in `mcpp.toml`:
+
+```toml
+[dependencies.mcpplibs]
+llmapi = "0.2.7"
 ```
 
 ### Building from Source
@@ -29,11 +41,7 @@ target("myapp")
 ```bash
 git clone https://github.com/mcpplibs/llmapi.git
 cd llmapi
-
-xmake
-xmake run hello_mcpp
-xmake run basic
-xmake run chat
+mcpp build
 ```
 
 ## First Example
@@ -69,8 +77,7 @@ int main() {
 Build and run:
 
 ```bash
-xmake
-xmake run hello_mcpp
+mcpp run
 ```
 
 ## Environment Setup
diff --git a/docs/en/xmake.md b/docs/en/xmake.md
new file mode 100644
index 0000000..73119e1
--- /dev/null
+++ b/docs/en/xmake.md
@@ -0,0 +1,47 @@
+# Using llmapi with xmake
+
+`llmapi` is developed and published mcpp-first, but the library itself is a
+plain C++23 module package and can also be consumed from an
+[xmake](https://xmake.io/) project.
+
+## Prerequisites
+
+- **C++ Compiler**: GCC 14+, Clang 18+, or MSVC 2022+ with C++23 support
+- **Build System**: xmake 3.0.0+
+- **Dependencies**: `mbedtls` is resolved automatically by xmake
+
+## Package Usage
+
+Add the mcpplibs xmake repository and require the package in your `xmake.lua`:
+
+```lua
+add_repositories("mcpplibs-index https://github.com/mcpplibs/mcpplibs-index.git")
+add_requires("llmapi 0.1.0")
+
+target("demo")
+    set_kind("binary")
+    set_languages("c++23")
+    set_policy("build.c++.modules", true)
+    add_files("src/*.cpp")
+    add_packages("llmapi")
+```
+
+## Building From Source
+
+```bash
+git clone https://github.com/mcpplibs/llmapi.git
+cd llmapi
+
+xmake
+xmake run hello_mcpp
+xmake run basic
+xmake run chat
+```
+
+## Notes
+
+- The xmake package tracks the `mcpplibs-index` repository and may lag behind
+  the mcpp package index ([mcpp-index](https://github.com/mcpp-community/mcpp-index)).
+- For the mcpp workflow (recommended) see
+  [Getting Started](getting-started.md) and the project
+  [README](../../README.md).
diff --git a/docs/zh-hant/README.md b/docs/zh-hant/README.md
index 4d68715..4aa46f7 100644
--- a/docs/zh-hant/README.md
+++ b/docs/zh-hant/README.md
@@ -15,6 +15,7 @@
 - [範例](examples.md)
 - [Provider 設定](providers.md)
 - [進階用法](advanced.md)
+- [使用 xmake 整合](xmake.md)
 
 ## 核心能力
 
diff --git a/docs/zh-hant/getting-started.md b/docs/zh-hant/getting-started.md
index 13c0e7e..650d579 100644
--- a/docs/zh-hant/getting-started.md
+++ b/docs/zh-hant/getting-started.md
@@ -2,22 +2,35 @@
 
 ## 環境需求
 
-- 編譯器：GCC 14+、Clang 18+ 或 MSVC 2022+
-- 建置工具：`xmake`
-- 依賴：`mbedtls` 由 xmake 自動處理
-
-## 使用 xmake 引入
-
-```lua
-add_repositories("mcpplibs-index git@github.com:mcpplibs/mcpplibs-index.git")
-add_requires("llmapi 0.1.0")
-
-target("myapp")
-    set_kind("binary")
-    set_languages("c++23")
-    set_policy("build.c++.modules", true)
-    add_files("src/*.cpp")
-    add_packages("llmapi")
+- 建置工具：[mcpp](https://github.com/mcpp-community/mcpp) — 工具鏈與相依
+  （如 `tinyhttps`）自動解析
+- 也可以在 xmake 專案中使用，見[使用 xmake 整合](xmake.md)
+
+## 從模板建立專案（推薦）
+
+```bash
+mcpp new myagent --template llmapi
+cd myagent
+mcpp run
+```
+
+列出函式庫提供的模板：
+
+```bash
+mcpp new --list-templates llmapi
+```
+
+## 在既有專案中引入
+
+```bash
+mcpp add llmapi
+```
+
+或在 `mcpp.toml` 中宣告：
+
+```toml
+[dependencies.mcpplibs]
+llmapi = "0.2.7"
 ```
 
 ## 從原始碼建置
@@ -25,9 +38,7 @@ target("myapp")
 ```bash
 git clone https://github.com/mcpplibs/llmapi.git
 cd llmapi
-
-xmake
-xmake run hello_mcpp
+mcpp build
 ```
 
 ## 第一個範例
diff --git a/docs/zh-hant/xmake.md b/docs/zh-hant/xmake.md
new file mode 100644
index 0000000..e142495
--- /dev/null
+++ b/docs/zh-hant/xmake.md
@@ -0,0 +1,45 @@
+# 使用 xmake 整合 llmapi
+
+`llmapi` 以 mcpp 生態為主進行開發與發佈,但函式庫本身是標準的 C++23 模組套件,
+也可以在 [xmake](https://xmake.io/) 專案中使用。
+
+## 前置條件
+
+- **C++ 編譯器**:支援 C++23 的 GCC 14+、Clang 18+ 或 MSVC 2022+
+- **建置系統**:xmake 3.0.0+
+- **相依**:`mbedtls` 由 xmake 自動解析
+
+## 套件管理使用
+
+在 `xmake.lua` 中加入 mcpplibs 的 xmake 倉庫並引入套件:
+
+```lua
+add_repositories("mcpplibs-index https://github.com/mcpplibs/mcpplibs-index.git")
+add_requires("llmapi 0.1.0")
+
+target("demo")
+    set_kind("binary")
+    set_languages("c++23")
+    set_policy("build.c++.modules", true)
+    add_files("src/*.cpp")
+    add_packages("llmapi")
+```
+
+## 原始碼建置
+
+```bash
+git clone https://github.com/mcpplibs/llmapi.git
+cd llmapi
+
+xmake
+xmake run hello_mcpp
+xmake run basic
+xmake run chat
+```
+
+## 說明
+
+- xmake 套件追蹤 `mcpplibs-index` 倉庫,版本可能落後於 mcpp 套件索引
+  ([mcpp-index](https://github.com/mcpp-community/mcpp-index))。
+- 推薦的 mcpp 工作流程見[快速上手](getting-started.md)與專案
+  [README](../../README.zh.hant.md)。
diff --git a/docs/zh/README.md b/docs/zh/README.md
index 54baa70..2de46b9 100644
--- a/docs/zh/README.md
+++ b/docs/zh/README.md
@@ -15,6 +15,7 @@
 - [示例](examples.md)
 - [Provider 配置](providers.md)
 - [高级用法](advanced.md)
+- [使用 xmake 集成](xmake.md)
 
 ## 核心能力
 
diff --git a/docs/zh/getting-started.md b/docs/zh/getting-started.md
index afce254..b1cb873 100644
--- a/docs/zh/getting-started.md
+++ b/docs/zh/getting-started.md
@@ -2,22 +2,35 @@
 
 ## 环境要求
 
-- 编译器：GCC 14+、Clang 18+ 或 MSVC 2022+
-- 构建工具：`xmake`
-- 依赖：`mbedtls` 由 xmake 自动处理
-
-## 使用 xmake 引入
-
-```lua
-add_repositories("mcpplibs-index git@github.com:mcpplibs/mcpplibs-index.git")
-add_requires("llmapi 0.1.0")
-
-target("myapp")
-    set_kind("binary")
-    set_languages("c++23")
-    set_policy("build.c++.modules", true)
-    add_files("src/*.cpp")
-    add_packages("llmapi")
+- 构建工具：[mcpp](https://github.com/mcpp-community/mcpp) — 工具链与依赖
+  （如 `tinyhttps`）自动解析
+- 也可以在 xmake 项目中使用，见[使用 xmake 集成](xmake.md)
+
+## 从模板创建项目（推荐）
+
+```bash
+mcpp new myagent --template llmapi
+cd myagent
+mcpp run
+```
+
+列出库提供的模板：
+
+```bash
+mcpp new --list-templates llmapi
+```
+
+## 在已有项目中引入
+
+```bash
+mcpp add llmapi
+```
+
+或在 `mcpp.toml` 中声明：
+
+```toml
+[dependencies.mcpplibs]
+llmapi = "0.2.7"
 ```
 
 ## 从源码构建
@@ -25,9 +38,7 @@ target("myapp")
 ```bash
 git clone https://github.com/mcpplibs/llmapi.git
 cd llmapi
-
-xmake
-xmake run hello_mcpp
+mcpp build
 ```
 
 ## 第一个例子
diff --git a/docs/zh/xmake.md b/docs/zh/xmake.md
new file mode 100644
index 0000000..a12df35
--- /dev/null
+++ b/docs/zh/xmake.md
@@ -0,0 +1,45 @@
+# 使用 xmake 集成 llmapi
+
+`llmapi` 以 mcpp 生态为主进行开发与发布,但库本身是标准的 C++23 模块包,
+也可以在 [xmake](https://xmake.io/) 项目中使用。
+
+## 前置条件
+
+- **C++ 编译器**:支持 C++23 的 GCC 14+、Clang 18+ 或 MSVC 2022+
+- **构建系统**:xmake 3.0.0+
+- **依赖**:`mbedtls` 由 xmake 自动解析
+
+## 包管理使用
+
+在 `xmake.lua` 中添加 mcpplibs 的 xmake 仓库并引入包:
+
+```lua
+add_repositories("mcpplibs-index https://github.com/mcpplibs/mcpplibs-index.git")
+add_requires("llmapi 0.1.0")
+
+target("demo")
+    set_kind("binary")
+    set_languages("c++23")
+    set_policy("build.c++.modules", true)
+    add_files("src/*.cpp")
+    add_packages("llmapi")
+```
+
+## 源码构建
+
+```bash
+git clone https://github.com/mcpplibs/llmapi.git
+cd llmapi
+
+xmake
+xmake run hello_mcpp
+xmake run basic
+xmake run chat
+```
+
+## 说明
+
+- xmake 包跟踪 `mcpplibs-index` 仓库,版本可能滞后于 mcpp 包索引
+  ([mcpp-index](https://github.com/mcpp-community/mcpp-index))。
+- 推荐的 mcpp 工作流见[快速上手](getting-started.md)与项目
+  [README](../../README.zh.md)。

From e970035e55c391601ccea4319a411e979011d792 Mon Sep 17 00:00:00 2001
From: sunrisepeak <speakshen@163.com>
Date: Wed, 10 Jun 2026 10:47:47 +0800
Subject: [PATCH 2/3] feat: ship project templates (openai default, chat,
 anthropic, deepseek)

templates/openai (default): minimal one-shot OpenAI chat.
templates/chat: interactive streaming chat CLI.
templates/anthropic: Claude via AnthropicConfig.
templates/deepseek: OpenAI-compatible endpoint via baseUrl.
Generated projects pin {{self.version}} under [dependencies.mcpplibs],
so the scaffold can never drift from the library version it shipped
with. Consumed by mcpp package templates:
`mcpp new app --template llmapi[:chat|anthropic|deepseek]` /
`mcpp new --list-templates llmapi`.
---
 templates/anthropic/mcpp.toml.in    |  6 ++++
 templates/anthropic/src/main.cpp.in | 24 ++++++++++++++++
 templates/anthropic/template.toml   |  3 ++
 templates/chat/mcpp.toml.in         |  6 ++++
 templates/chat/src/main.cpp.in      | 44 +++++++++++++++++++++++++++++
 templates/chat/template.toml        |  3 ++
 templates/deepseek/mcpp.toml.in     |  6 ++++
 templates/deepseek/src/main.cpp.in  | 26 +++++++++++++++++
 templates/deepseek/template.toml    |  3 ++
 templates/openai/mcpp.toml.in       |  6 ++++
 templates/openai/src/main.cpp.in    | 24 ++++++++++++++++
 templates/openai/template.toml      |  4 +++
 12 files changed, 155 insertions(+)
 create mode 100644 templates/anthropic/mcpp.toml.in
 create mode 100644 templates/anthropic/src/main.cpp.in
 create mode 100644 templates/anthropic/template.toml
 create mode 100644 templates/chat/mcpp.toml.in
 create mode 100644 templates/chat/src/main.cpp.in
 create mode 100644 templates/chat/template.toml
 create mode 100644 templates/deepseek/mcpp.toml.in
 create mode 100644 templates/deepseek/src/main.cpp.in
 create mode 100644 templates/deepseek/template.toml
 create mode 100644 templates/openai/mcpp.toml.in
 create mode 100644 templates/openai/src/main.cpp.in
 create mode 100644 templates/openai/template.toml

diff --git a/templates/anthropic/mcpp.toml.in b/templates/anthropic/mcpp.toml.in
new file mode 100644
index 0000000..f9558ba
--- /dev/null
+++ b/templates/anthropic/mcpp.toml.in
@@ -0,0 +1,6 @@
+[package]
+name        = "{{project.name}}"
+version     = "0.1.0"
+
+[dependencies.mcpplibs]
+{{self.name}} = "{{self.version}}"
diff --git a/templates/anthropic/src/main.cpp.in b/templates/anthropic/src/main.cpp.in
new file mode 100644
index 0000000..021cebf
--- /dev/null
+++ b/templates/anthropic/src/main.cpp.in
@@ -0,0 +1,24 @@
+// {{project.name}} — generated from {{self.name}}@{{self.version}}:anthropic
+import mcpplibs.llmapi;
+import std;
+
+int main() {
+    using namespace mcpplibs::llmapi;
+
+    auto apiKey = std::getenv("ANTHROPIC_API_KEY");
+    if (!apiKey) {
+        std::println(stderr, "ANTHROPIC_API_KEY not set");
+        return 1;
+    }
+
+    auto client = Client(AnthropicConfig{
+        .apiKey = apiKey,
+        .model = "claude-sonnet-4-20250514",
+    });
+
+    client.system("You are a concise assistant.");
+    auto resp = client.chat("Say hello from {{project.name}} in one sentence.");
+
+    std::println("{}", resp.text());
+    return 0;
+}
diff --git a/templates/anthropic/template.toml b/templates/anthropic/template.toml
new file mode 100644
index 0000000..60d8c1c
--- /dev/null
+++ b/templates/anthropic/template.toml
@@ -0,0 +1,3 @@
+[template]
+description  = "Anthropic (Claude) chat via AnthropicConfig"
+post_message = "cd into the project, export ANTHROPIC_API_KEY, then `mcpp run`."
diff --git a/templates/chat/mcpp.toml.in b/templates/chat/mcpp.toml.in
new file mode 100644
index 0000000..f9558ba
--- /dev/null
+++ b/templates/chat/mcpp.toml.in
@@ -0,0 +1,6 @@
+[package]
+name        = "{{project.name}}"
+version     = "0.1.0"
+
+[dependencies.mcpplibs]
+{{self.name}} = "{{self.version}}"
diff --git a/templates/chat/src/main.cpp.in b/templates/chat/src/main.cpp.in
new file mode 100644
index 0000000..8d59565
--- /dev/null
+++ b/templates/chat/src/main.cpp.in
@@ -0,0 +1,44 @@
+// {{project.name}} — generated from {{self.name}}@{{self.version}}:chat
+// Interactive streaming chat CLI. Type 'quit' (or 'q') to exit.
+import mcpplibs.llmapi;
+import std;
+
+int main() {
+    using namespace mcpplibs::llmapi;
+
+    auto apiKey = std::getenv("OPENAI_API_KEY");
+    if (!apiKey) {
+        std::println(stderr, "OPENAI_API_KEY not set");
+        return 1;
+    }
+
+    auto client = Client(Config{
+        .apiKey = apiKey,
+        .model = "gpt-4o-mini",
+    });
+    client.system("You are a helpful assistant.");
+
+    std::println("{{project.name}} — chat CLI (type 'quit' to exit)");
+
+    while (true) {
+        std::print("\nYou: ");
+        std::string input;
+        if (!std::getline(std::cin, input)) break;
+        if (input == "quit" || input == "q") break;
+        if (input.empty()) continue;
+
+        try {
+            std::print("AI: ");
+            client.chat_stream(input, [](std::string_view chunk) {
+                std::print("{}", chunk);
+                std::fflush(stdout);
+            });
+            std::println("");
+        } catch (const std::exception& e) {
+            std::println(stderr, "\nError: {}", e.what());
+        }
+    }
+
+    std::println("Bye!");
+    return 0;
+}
diff --git a/templates/chat/template.toml b/templates/chat/template.toml
new file mode 100644
index 0000000..ed25f9e
--- /dev/null
+++ b/templates/chat/template.toml
@@ -0,0 +1,3 @@
+[template]
+description  = "Interactive streaming chat CLI (OpenAI)"
+post_message = "cd into the project, export OPENAI_API_KEY, then `mcpp run` and start chatting."
diff --git a/templates/deepseek/mcpp.toml.in b/templates/deepseek/mcpp.toml.in
new file mode 100644
index 0000000..f9558ba
--- /dev/null
+++ b/templates/deepseek/mcpp.toml.in
@@ -0,0 +1,6 @@
+[package]
+name        = "{{project.name}}"
+version     = "0.1.0"
+
+[dependencies.mcpplibs]
+{{self.name}} = "{{self.version}}"
diff --git a/templates/deepseek/src/main.cpp.in b/templates/deepseek/src/main.cpp.in
new file mode 100644
index 0000000..2b8aba7
--- /dev/null
+++ b/templates/deepseek/src/main.cpp.in
@@ -0,0 +1,26 @@
+// {{project.name}} — generated from {{self.name}}@{{self.version}}:deepseek
+// Any OpenAI-compatible endpoint works the same way — change baseUrl/model.
+import mcpplibs.llmapi;
+import std;
+
+int main() {
+    using namespace mcpplibs::llmapi;
+
+    auto apiKey = std::getenv("DEEPSEEK_API_KEY");
+    if (!apiKey) {
+        std::println(stderr, "DEEPSEEK_API_KEY not set");
+        return 1;
+    }
+
+    auto client = Client(Config{
+        .apiKey = apiKey,
+        .baseUrl = std::string(URL::DeepSeek),
+        .model = "deepseek-chat",
+    });
+
+    client.system("You are a concise assistant.");
+    auto resp = client.chat("Say hello from {{project.name}} in one sentence.");
+
+    std::println("{}", resp.text());
+    return 0;
+}
diff --git a/templates/deepseek/template.toml b/templates/deepseek/template.toml
new file mode 100644
index 0000000..d320708
--- /dev/null
+++ b/templates/deepseek/template.toml
@@ -0,0 +1,3 @@
+[template]
+description  = "OpenAI-compatible endpoint via baseUrl (DeepSeek)"
+post_message = "cd into the project, export DEEPSEEK_API_KEY, then `mcpp run`."
diff --git a/templates/openai/mcpp.toml.in b/templates/openai/mcpp.toml.in
new file mode 100644
index 0000000..f9558ba
--- /dev/null
+++ b/templates/openai/mcpp.toml.in
@@ -0,0 +1,6 @@
+[package]
+name        = "{{project.name}}"
+version     = "0.1.0"
+
+[dependencies.mcpplibs]
+{{self.name}} = "{{self.version}}"
diff --git a/templates/openai/src/main.cpp.in b/templates/openai/src/main.cpp.in
new file mode 100644
index 0000000..135f1f1
--- /dev/null
+++ b/templates/openai/src/main.cpp.in
@@ -0,0 +1,24 @@
+// {{project.name}} — generated from {{self.name}}@{{self.version}}:openai
+import mcpplibs.llmapi;
+import std;
+
+int main() {
+    using namespace mcpplibs::llmapi;
+
+    auto apiKey = std::getenv("OPENAI_API_KEY");
+    if (!apiKey) {
+        std::println(stderr, "OPENAI_API_KEY not set");
+        return 1;
+    }
+
+    auto client = Client(Config{
+        .apiKey = apiKey,
+        .model = "gpt-4o-mini",
+    });
+
+    client.system("You are a concise assistant.");
+    auto resp = client.chat("Say hello from {{project.name}} in one sentence.");
+
+    std::println("{}", resp.text());
+    return 0;
+}
diff --git a/templates/openai/template.toml b/templates/openai/template.toml
new file mode 100644
index 0000000..eac3acd
--- /dev/null
+++ b/templates/openai/template.toml
@@ -0,0 +1,4 @@
+[template]
+description  = "Minimal OpenAI chat — one request, one answer"
+default      = true
+post_message = "cd into the project, export OPENAI_API_KEY, then `mcpp run`."

From c3864e07f1118b5e0e9cfbd8e709f634d641df7b Mon Sep 17 00:00:00 2001
From: sunrisepeak <speakshen@163.com>
Date: Wed, 10 Jun 2026 10:47:47 +0800
Subject: [PATCH 3/3] =?UTF-8?q?chore:=20bump=20version=200.2.7;=20workspac?=
 =?UTF-8?q?e=20mcpp=200.0.13=20=E2=86=92=200.0.53?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

mcpp 0.0.13 is no longer resolvable from the xim index locally; 0.0.53
is the current release (and the floor for package templates is 0.0.48).
mcpp.lock regenerated by mcpp 0.0.53 (lock v2, tinyhttps 0.2.3).
---
 .github/workflows/ci.yml | 6 +++---
 .xlings.json             | 2 +-
 mcpp.lock                | 9 +++++----
 mcpp.toml                | 2 +-
 4 files changed, 10 insertions(+), 9 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index d492352..66f5053 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -26,14 +26,14 @@ jobs:
       - name: Refresh package index
         run: xlings update
 
-      - name: Install workspace tools (.xlings.json → mcpp 0.0.13)
+      - name: Install workspace tools (.xlings.json → mcpp 0.0.53)
         run: xlings install -y
 
       - name: Cache mcpp sandbox
         uses: actions/cache@v4
         with:
-          path: ~/.xlings/data/xpkgs/xim-x-mcpp/0.0.13/registry
-          key: mcpp-sandbox-${{ runner.os }}-mcpp0.0.13
+          path: ~/.xlings/data/xpkgs/xim-x-mcpp/0.0.53/registry
+          key: mcpp-sandbox-${{ runner.os }}-mcpp0.0.53
 
       - name: Build with mcpp
         run: mcpp build
diff --git a/.xlings.json b/.xlings.json
index 62fdda3..925b1b8 100644
--- a/.xlings.json
+++ b/.xlings.json
@@ -1,5 +1,5 @@
 {
   "workspace": {
-    "mcpp": { "linux": "0.0.13" }
+    "mcpp": { "linux": "0.0.53" }
   }
 }
diff --git a/mcpp.lock b/mcpp.lock
index 23cee57..f673c75 100644
--- a/mcpp.lock
+++ b/mcpp.lock
@@ -1,8 +1,9 @@
 # Auto-generated by mcpp. Do not edit by hand.
-version = 1
+version = 2
 
 [package."mcpplibs.tinyhttps"]
-version = "0.2.2"
-source  = "mcpp-index+https://github.com/mcpp-community/mcpp-index.git"
-hash    = "sha256:<from-xlings>"
+namespace = "mcpplibs"
+version = "0.2.3"
+source  = "index+mcpplibs@0.2.3"
+hash    = "fnv1a:dcefd9d20be9c419"
 
diff --git a/mcpp.toml b/mcpp.toml
index 72311c0..b70222a 100644
--- a/mcpp.toml
+++ b/mcpp.toml
@@ -1,7 +1,7 @@
 [package]
 namespace   = "mcpplibs"
 name        = "llmapi"
-version     = "0.2.6"
+version     = "0.2.7"
 description = "Modern C++ LLM API client with openai-compatible support"
 license     = "Apache-2.0"
 repo        = "https://github.com/mcpplibs/llmapi"