Move production planning out of README

.agents/skills/README.md

@@ -7,6 +7,7 @@
 | 技能 | 说明 |
 |------|------|
 | [mcpp-style-ref](mcpp-style-ref/SKILL.md) | 面向 mcpp 项目的 Modern/Module C++ (C++23) 命名、模块化与实践规则 |
+| [llmapi-best-practices](llmapi-best-practices/SKILL.md) | 面向本仓库 llmapi 的使用最佳实践、文档入口、示例位置、并发/异常/重试建议与相关生态链接 |
 
 ## 使用方式
 

.agents/skills/llmapi-best-practices/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: llmapi-best-practices
+description: 在本仓库中使用 llmapi 的最佳实践。适用于用户询问如何使用 llmapi、如何接入 OpenAI/Anthropic/兼容端点、并发模型、错误处理、文档入口、示例位置、xmake/xlings/mcpplibs-index 安装方式，或需要快速定位本项目相关链接与推荐用法时。
+---
+
+# llmapi-best-practices
+
+用于回答“如何正确使用本项目 `llmapi`”相关问题的技能。
+
+## 何时使用
+
+在以下场景使用：
+
+- 用户询问如何集成或调用 `llmapi`
+- 用户想知道 OpenAI / Anthropic / 兼容端点的推荐接法
+- 用户询问并发、异常处理、重试边界、生产可用性
+- 用户需要项目文档、示例、仓库、生态链接
+- 用户询问 `mcpplibs` / `mcpplibs-index` / `xlings` 与本项目的关系
+
+如果问题是“如何修改 C++ 模块代码风格”，优先改用 `mcpp-style-ref`。
+
+## 快速工作流
+
+1. 先确认用户要的是“使用方式”还是“改库实现”。
+2. 默认优先引用本仓库文档入口：
+   - 英文文档：`docs/en/README.md`
+   - 简中文档：`docs/zh/README.md`
+   - 繁中文档：`docs/zh-hant/README.md`
+3. 解释推荐接法时，优先给当前项目的真实 API：
+   - 默认 OpenAI 风格：`Client(Config{...})`
+   - Anthropic：`Client(AnthropicConfig{...})`
+4. 解释并发时，使用当前仓库推荐边界：
+   - 实例隔离，上层并发，不共享 `Client`
+5. 解释错误处理时，明确当前建议：
+   - 当前以异常为主
+   - 自动重试更适合由库使用者在上层实现
+
+## 推荐回答要点
+
+### 1. 默认 API 入口
+
+OpenAI 风格默认入口：
+
+```cpp
+auto client = Client(Config{
+    .apiKey = std::getenv("OPENAI_API_KEY"),
+    .model = "gpt-4o-mini",
+});
+```
+
+Anthropic：
+
+```cpp
+auto client = Client(AnthropicConfig{
+    .apiKey = std::getenv("ANTHROPIC_API_KEY"),
+    .model = "claude-sonnet-4-20250514",
+});
+```
+
+兼容端点：
+
+```cpp
+auto client = Client(Config{
+    .apiKey = std::getenv("DEEPSEEK_API_KEY"),
+    .baseUrl = std::string(URL::DeepSeek),
+    .model = "deepseek-chat",
+});
+```
+
+### 2. 并发建议
+
+- `Client` 是有状态对象，不要跨线程共享
+- 每个任务 / 线程各自创建一个 `Client`
+- 多模型 / 多 provider 并发调用时，各自实例隔离即可
+
+### 3. 错误处理建议
+
+- 当前主路径是异常模式
+- 如果用户不希望异常外抛，建议在调用点包一层转换成 `optional` / `expected`
+- 自动重试策略先由使用者在上层实现，不要默认承诺库内自动重试
+
+### 4. 文档和示例定位
+
+如果用户要具体用法，优先引导到：
+
+- 入门：`docs/*/getting-started.md`
+- 使用场景：`docs/*/examples.md`
+- Provider：`docs/*/providers.md`
+- 并发 / 高级用法：`docs/*/advanced.md`
+- API：`docs/*/cpp-api.md`
+
+## 参考文件
+
+需要项目和生态链接时，读取：
+
+- [references/links.md](references/links.md)

.agents/skills/llmapi-best-practices/references/links.md

@@ -0,0 +1,58 @@
+# llmapi 相关链接
+
+## 仓库与主页
+
+- GitHub 仓库：`https://github.com/mcpplibs/llmapi`
+- README（英文）：`/home/speak/workspace/github/mcpplibs/llmapi/README.md`
+- README（简中）：`/home/speak/workspace/github/mcpplibs/llmapi/README.zh.md`
+- README（繁中）：`/home/speak/workspace/github/mcpplibs/llmapi/README.zh.hant.md`
+
+## 文档入口
+
+- 文档导航：`/home/speak/workspace/github/mcpplibs/llmapi/docs/README.md`
+- 英文文档主页：`/home/speak/workspace/github/mcpplibs/llmapi/docs/en/README.md`
+- 简中文档主页：`/home/speak/workspace/github/mcpplibs/llmapi/docs/zh/README.md`
+- 繁中文档主页：`/home/speak/workspace/github/mcpplibs/llmapi/docs/zh-hant/README.md`
+
+## 使用文档
+
+- 英文入门：`/home/speak/workspace/github/mcpplibs/llmapi/docs/en/getting-started.md`
+- 英文示例：`/home/speak/workspace/github/mcpplibs/llmapi/docs/en/examples.md`
+- 英文 Provider：`/home/speak/workspace/github/mcpplibs/llmapi/docs/en/providers.md`
+- 英文高级用法：`/home/speak/workspace/github/mcpplibs/llmapi/docs/en/advanced.md`
+- 英文 C++ API：`/home/speak/workspace/github/mcpplibs/llmapi/docs/en/cpp-api.md`
+
+- 简中入门：`/home/speak/workspace/github/mcpplibs/llmapi/docs/zh/getting-started.md`
+- 简中示例：`/home/speak/workspace/github/mcpplibs/llmapi/docs/zh/examples.md`
+- 简中 Provider：`/home/speak/workspace/github/mcpplibs/llmapi/docs/zh/providers.md`
+- 简中高级用法：`/home/speak/workspace/github/mcpplibs/llmapi/docs/zh/advanced.md`
+- 简中 C++ API：`/home/speak/workspace/github/mcpplibs/llmapi/docs/zh/cpp-api.md`
+
+- 繁中入门：`/home/speak/workspace/github/mcpplibs/llmapi/docs/zh-hant/getting-started.md`
+- 繁中示例：`/home/speak/workspace/github/mcpplibs/llmapi/docs/zh-hant/examples.md`
+- 繁中 Provider：`/home/speak/workspace/github/mcpplibs/llmapi/docs/zh-hant/providers.md`
+- 繁中高级用法：`/home/speak/workspace/github/mcpplibs/llmapi/docs/zh-hant/advanced.md`
+- 繁中 C++ API：`/home/speak/workspace/github/mcpplibs/llmapi/docs/zh-hant/cpp-api.md`
+
+## 示例源码
+
+- `examples/hello_mcpp.cpp`
+- `examples/basic.cpp`
+- `examples/chat.cpp`
+- `examples/xmake.lua`
+
+## 生态与依赖
+
+- mcpplibs：`https://github.com/mcpplibs`
+- mcpplibs-index：`https://github.com/mcpplibs/mcpplibs-index`
+- xlings：`https://github.com/d2learn/xlings`
+- xmake：`https://xmake.io/`
+- OpenAI API：`https://platform.openai.com/docs/api-reference`
+- Anthropic API：`https://docs.anthropic.com/`
+
+## 推荐回答时的关键事实
+
+- 默认 OpenAI 风格入口：`Client(Config{...})`
+- Anthropic 入口：`Client(AnthropicConfig{...})`
+- 推荐并发模型：实例隔离，上层并发，不共享 `Client`
+- 推荐错误处理：异常模式为主，自动重试建议由库使用者在上层实现

README.md

@@ -9,7 +9,7 @@
 
 | English - [简体中文](README.zh.md) - [繁體中文](README.zh.hant.md) |
 |:---:|
-| [Documentation](docs/) - [C++ API](docs/cpp-api.md) - [Examples](docs/examples.md) |
+| [Documentation](docs/README.md) - [English Docs](docs/en/README.md) - [中文文档](docs/zh/README.md) - [繁體中文文件](docs/zh-hant/README.md) |
 
 `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.
 
@@ -79,7 +79,7 @@ xmake run chat
 
 ```lua
 add_repositories("mcpplibs-index https://github.com/mcpplibs/mcpplibs-index.git")
-add_requires("llmapi 0.0.2")
+add_requires("llmapi 0.1.0")
 
 target("demo")
     set_kind("binary")
@@ -89,7 +89,7 @@ target("demo")
     add_packages("llmapi")
 ```
 
-See [docs/getting-started.md](docs/getting-started.md) and [docs/providers.md](docs/providers.md) for more setup detail.
+See [docs/en/getting-started.md](docs/en/getting-started.md), [docs/en/providers.md](docs/en/providers.md), [docs/en/roadmap.md](docs/en/roadmap.md), and [docs/en/README.md](docs/en/README.md) for more setup and planning detail.
 
 ## License
 

README.zh.hant.md

@@ -1,86 +1,96 @@
 # llmapi
 
-> Modern C++ LLM API client with openai-compatible support
+> 使用 C++23 模組建構的現代 LLM 客戶端
 
 [![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)
-[![OpenAI Compatible](https://img.shields.io/badge/OpenAI_API-Compatible-green.svg)](https://platform.openai.com/docs/api-reference)
+[![OpenAI Compatible](https://img.shields.io/badge/OpenAI-Compatible-green.svg)](https://platform.openai.com/docs/api-reference)
 
 | [English](README.md) - [简体中文](README.zh.md) - 繁體中文 |
 |:---:|
-| [完整文件](docs/) - [C++ API](docs/cpp-api.md) - [C API](docs/c-api.md) - [範例](docs/examples.md) |
+| [文件導覽](docs/README.md) - [繁體中文文件](docs/zh-hant/README.md) - [English Docs](docs/en/README.md) - [简体中文文档](docs/zh/README.md) |
 
-簡潔、型別安全的 LLM API 客戶端，使用 C++23 模組。流式介面設計，零成本抽象。支援 OpenAI、Poe、DeepSeek 及相容端點。
+`llmapi` 提供型別化的 `Client<Provider>` API，涵蓋聊天、串流輸出、embeddings、工具呼叫與對話持久化。預設別名 `Config` 對應 OpenAI 風格設定，常見情況下不需要顯式寫出 `openai::OpenAI(...)`。
 
-## ✨ 特性
+## 特性
 
-- **C++23 模組** - `import mcpplibs.llmapi`
-- **自動儲存歷史** - 對話歷史自動管理
-- **型別安全串流** - 概念約束的回呼函式
-- **流式介面** - 可鏈式呼叫的方法
-- **提供商無關** - OpenAI、Poe 及相容端點
+- C++23 模組：`import mcpplibs.llmapi`
+- 強型別訊息、工具與回應結構
+- 同步、非同步、串流聊天介面
+- OpenAI Provider 支援 embeddings
+- 支援儲存 / 載入對話歷史
+- 可透過 `baseUrl` 存取 OpenAI 相容端點
 
 ## 快速開始
 
-
 ```cpp
-import std;
 import mcpplibs.llmapi;
+import std;
 
 int main() {
-    using namespace mcpplibs;
-
-    llmapi::Client client(std::getenv("OPENAI_API_KEY"), llmapi::URL::Poe);
-
-    client.model("gpt-5")
-          .system("You are a helpful assistant.")
-          .user("In one sentence, introduce modern C++. 並給出中文翻譯")
-          .request([](std::string_view chunk) {
-                std::print("{}", chunk);
-                std::cout.flush();
-          });
+    using namespace mcpplibs::llmapi;
+
+    auto apiKey = std::getenv("OPENAI_API_KEY");
+    if (!apiKey) {
+        std::cerr << "OPENAI_API_KEY not set\n";
+        return 1;
+    }
 
+    auto client = Client(Config{
+        .apiKey = apiKey,
+        .model = "gpt-4o-mini",
+    });
+
+    client.system("You are a concise assistant.");
+    auto resp = client.chat("用兩句話解釋 C++23 模組的價值。");
+
+    std::cout << resp.text() << '\n';
     return 0;
 }
 ```
 
-### 模型 / 提供商
+## Provider
+
+- `Config`：`openai::Config` 的匯出別名，預設走 OpenAI 風格
+- `openai::OpenAI`：OpenAI 聊天、串流、工具呼叫、embeddings
+- `AnthropicConfig` / `anthropic::Anthropic`：Anthropic 聊天與串流
+
+相容端點範例：
 
 ```cpp
-llmapi::Client client(apiKey, llmapi::URL::OpenAI);    // OpenAI
-llmapi::Client client(apiKey, llmapi::URL::Poe);       // Poe
-llmapi::Client client(apiKey, llmapi::URL::DeepSeek);  // Deepseek
-llmapi::Client client(apiKey, "https://custom.com");   // 自訂
+auto client = Client(Config{
+    .apiKey = std::getenv("DEEPSEEK_API_KEY"),
+    .baseUrl = std::string(URL::DeepSeek),
+    .model = "deepseek-chat",
+});
 ```
 
-## 🛠️ 建置
+## 建置與執行
 
 ```bash
-xmake              # 建置
-xmake run basic    # 執行範例（需先設定 OPENAI_API_KEY）
+xmake
+xmake run hello_mcpp
+xmake run basic
+xmake run chat
 ```
 
-## 📦 在建置工具中使用
-
-### xmake
+## 套件管理使用
 
 ```lua
--- 0 - 新增 mcpplibs 索引倉庫
-add_repositories("mcpplibs-index https://github.com/mcpplibs/llmapi.git")
-
--- 1 - 新增需要的函式庫和版本
-add_requires("llmapi 0.0.2")
+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")
 ```
 
-> More: [mcpplibs-index](https://github.com/mcpplibs/mcpplibs-index)
-
-### cmake
-
-```
-todo...
-```
+更多內容見 [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/roadmap.md](docs/zh-hant/roadmap.md) 與 [docs/zh-hant/README.md](docs/zh-hant/README.md)。
 
-## 📄 授權條款
+## 授權
 
-Apache-2.0 - 詳見 [LICENSE](LICENSE)
+Apache-2.0，詳見 [LICENSE](LICENSE)