Skip to content

Commit 980987b

Browse files
SunrisepeakSunrisepeak
authored
Pr/ci docs refresh (#7)
* Add multilingual docs structure * Document production readiness gaps * Document isolated-client concurrency model * Expand usage scenarios in examples docs * Add llmapi usage best-practices skill * Release 0.1.0
1 parent 861c96b commit 980987b

31 files changed

+2252
-122
lines changed

‎.agents/skills/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
| 技能 | 说明 |
88
|------|------|
99
| [mcpp-style-ref](mcpp-style-ref/SKILL.md) | 面向 mcpp 项目的 Modern/Module C++ (C++23) 命名、模块化与实践规则 |
10+
| [llmapi-best-practices](llmapi-best-practices/SKILL.md) | 面向本仓库 llmapi 的使用最佳实践、文档入口、示例位置、并发/异常/重试建议与相关生态链接 |
1011

1112
## 使用方式
1213

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

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
---
2+
name: llmapi-best-practices
3+
description: 在本仓库中使用 llmapi 的最佳实践。适用于用户询问如何使用 llmapi、如何接入 OpenAI/Anthropic/兼容端点、并发模型、错误处理、文档入口、示例位置、xmake/xlings/mcpplibs-index 安装方式，或需要快速定位本项目相关链接与推荐用法时。
4+
---
5+
6+
# llmapi-best-practices
7+
8+
用于回答“如何正确使用本项目 `llmapi`”相关问题的技能。
9+
10+
## 何时使用
11+
12+
在以下场景使用：
13+
14+
- 用户询问如何集成或调用 `llmapi`
15+
- 用户想知道 OpenAI / Anthropic / 兼容端点的推荐接法
16+
- 用户询问并发、异常处理、重试边界、生产可用性
17+
- 用户需要项目文档、示例、仓库、生态链接
18+
- 用户询问 `mcpplibs` / `mcpplibs-index` / `xlings` 与本项目的关系
19+
20+
如果问题是“如何修改 C++ 模块代码风格”，优先改用 `mcpp-style-ref`。
21+
22+
## 快速工作流
23+
24+
1. 先确认用户要的是“使用方式”还是“改库实现”。
25+
2. 默认优先引用本仓库文档入口：
26+
- 英文文档：`docs/en/README.md`
27+
- 简中文档：`docs/zh/README.md`
28+
- 繁中文档：`docs/zh-hant/README.md`
29+
3. 解释推荐接法时，优先给当前项目的真实 API：
30+
- 默认 OpenAI 风格：`Client(Config{...})`
31+
- Anthropic：`Client(AnthropicConfig{...})`
32+
4. 解释并发时，使用当前仓库推荐边界：
33+
- 实例隔离，上层并发，不共享 `Client`
34+
5. 解释错误处理时，明确当前建议：
35+
- 当前以异常为主
36+
- 自动重试更适合由库使用者在上层实现
37+
38+
## 推荐回答要点
39+
40+
### 1. 默认 API 入口
41+
42+
OpenAI 风格默认入口：
43+
44+
```cpp
45+
auto client = Client(Config{
46+
.apiKey = std::getenv("OPENAI_API_KEY"),
47+
.model = "gpt-4o-mini",
48+
});
49+
```
50+
51+
Anthropic：
52+
53+
```cpp
54+
auto client = Client(AnthropicConfig{
55+
.apiKey = std::getenv("ANTHROPIC_API_KEY"),
56+
.model = "claude-sonnet-4-20250514",
57+
});
58+
```
59+
60+
兼容端点：
61+
62+
```cpp
63+
auto client = Client(Config{
64+
.apiKey = std::getenv("DEEPSEEK_API_KEY"),
65+
.baseUrl = std::string(URL::DeepSeek),
66+
.model = "deepseek-chat",
67+
});
68+
```
69+
70+
### 2. 并发建议
71+
72+
- `Client` 是有状态对象，不要跨线程共享
73+
- 每个任务 / 线程各自创建一个 `Client`
74+
- 多模型 / 多 provider 并发调用时，各自实例隔离即可
75+
76+
### 3. 错误处理建议
77+
78+
- 当前主路径是异常模式
79+
- 如果用户不希望异常外抛，建议在调用点包一层转换成 `optional` / `expected`
80+
- 自动重试策略先由使用者在上层实现，不要默认承诺库内自动重试
81+
82+
### 4. 文档和示例定位
83+
84+
如果用户要具体用法，优先引导到：
85+
86+
- 入门：`docs/*/getting-started.md`
87+
- 使用场景：`docs/*/examples.md`
88+
- Provider：`docs/*/providers.md`
89+
- 并发 / 高级用法：`docs/*/advanced.md`
90+
- API：`docs/*/cpp-api.md`
91+
92+
## 参考文件
93+
94+
需要项目和生态链接时，读取：
95+
96+
- [references/links.md](references/links.md)

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

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# llmapi 相关链接
2+
3+
## 仓库与主页
4+
5+
- GitHub 仓库：`https://github.com/mcpplibs/llmapi`
6+
- README（英文）：`/home/speak/workspace/github/mcpplibs/llmapi/README.md`
7+
- README（简中）：`/home/speak/workspace/github/mcpplibs/llmapi/README.zh.md`
8+
- README（繁中）：`/home/speak/workspace/github/mcpplibs/llmapi/README.zh.hant.md`
9+
10+
## 文档入口
11+
12+
- 文档导航：`/home/speak/workspace/github/mcpplibs/llmapi/docs/README.md`
13+
- 英文文档主页：`/home/speak/workspace/github/mcpplibs/llmapi/docs/en/README.md`
14+
- 简中文档主页：`/home/speak/workspace/github/mcpplibs/llmapi/docs/zh/README.md`
15+
- 繁中文档主页：`/home/speak/workspace/github/mcpplibs/llmapi/docs/zh-hant/README.md`
16+
17+
## 使用文档
18+
19+
- 英文入门：`/home/speak/workspace/github/mcpplibs/llmapi/docs/en/getting-started.md`
20+
- 英文示例：`/home/speak/workspace/github/mcpplibs/llmapi/docs/en/examples.md`
21+
- 英文 Provider：`/home/speak/workspace/github/mcpplibs/llmapi/docs/en/providers.md`
22+
- 英文高级用法：`/home/speak/workspace/github/mcpplibs/llmapi/docs/en/advanced.md`
23+
- 英文 C++ API：`/home/speak/workspace/github/mcpplibs/llmapi/docs/en/cpp-api.md`
24+
25+
- 简中入门：`/home/speak/workspace/github/mcpplibs/llmapi/docs/zh/getting-started.md`
26+
- 简中示例：`/home/speak/workspace/github/mcpplibs/llmapi/docs/zh/examples.md`
27+
- 简中 Provider：`/home/speak/workspace/github/mcpplibs/llmapi/docs/zh/providers.md`
28+
- 简中高级用法：`/home/speak/workspace/github/mcpplibs/llmapi/docs/zh/advanced.md`
29+
- 简中 C++ API：`/home/speak/workspace/github/mcpplibs/llmapi/docs/zh/cpp-api.md`
30+
31+
- 繁中入门：`/home/speak/workspace/github/mcpplibs/llmapi/docs/zh-hant/getting-started.md`
32+
- 繁中示例：`/home/speak/workspace/github/mcpplibs/llmapi/docs/zh-hant/examples.md`
33+
- 繁中 Provider：`/home/speak/workspace/github/mcpplibs/llmapi/docs/zh-hant/providers.md`
34+
- 繁中高级用法：`/home/speak/workspace/github/mcpplibs/llmapi/docs/zh-hant/advanced.md`
35+
- 繁中 C++ API：`/home/speak/workspace/github/mcpplibs/llmapi/docs/zh-hant/cpp-api.md`
36+
37+
## 示例源码
38+
39+
- `examples/hello_mcpp.cpp`
40+
- `examples/basic.cpp`
41+
- `examples/chat.cpp`
42+
- `examples/xmake.lua`
43+
44+
## 生态与依赖
45+
46+
- mcpplibs：`https://github.com/mcpplibs`
47+
- mcpplibs-index：`https://github.com/mcpplibs/mcpplibs-index`
48+
- xlings：`https://github.com/d2learn/xlings`
49+
- xmake：`https://xmake.io/`
50+
- OpenAI API：`https://platform.openai.com/docs/api-reference`
51+
- Anthropic API：`https://docs.anthropic.com/`
52+
53+
## 推荐回答时的关键事实
54+
55+
- 默认 OpenAI 风格入口：`Client(Config{...})`
56+
- Anthropic 入口：`Client(AnthropicConfig{...})`
57+
- 推荐并发模型：实例隔离，上层并发，不共享 `Client`
58+
- 推荐错误处理：异常模式为主，自动重试建议由库使用者在上层实现

‎README.md‎

Lines changed: 20 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99

1010
| English - [简体中文](README.zh.md) - [繁體中文](README.zh.hant.md) |
1111
|:---:|
12-
| [Documentation](docs/) - [C++ API](docs/cpp-api.md) - [Examples](docs/examples.md) |
12+
| [Documentation](docs/README.md) - [English Docs](docs/en/README.md) - [中文文档](docs/zh/README.md) - [繁體中文文件](docs/zh-hant/README.md) |
1313

1414
`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.
1515

@@ -22,6 +22,23 @@
2222
- Conversation save/load helpers
2323
- OpenAI-compatible endpoint support through `openai::Config::baseUrl`
2424

25+
## Production Readiness
26+
27+
`llmapi` is usable for internal tools, prototypes, and early production experiments, but it should not yet be treated as fully industrial-grade infrastructure.
28+
29+
Required gaps before that bar:
30+
31+
- Unified error model across providers and transport
32+
- Retry, backoff, timeout, and idempotency policy
33+
- Request cancellation for long-running and streaming calls
34+
- Logging, metrics, trace hooks, and request correlation
35+
- Hardening of the custom HTTP/TLS transport layer
36+
- Fault-injection, concurrency, and large-scale mock testing
37+
- Stronger API compatibility and versioning guarantees
38+
- More complete production configuration surface
39+
- Explicit thread-safety and concurrency semantics
40+
- Operational documentation for retries, keys, proxies, and failure handling
41+
2542
## Quick Start
2643

2744
```cpp
@@ -79,7 +96,7 @@ xmake run chat
7996

8097
```lua
8198
add_repositories("mcpplibs-index https://github.com/mcpplibs/mcpplibs-index.git")
82-
add_requires("llmapi 0.0.2")
99+
add_requires("llmapi 0.1.0")
83100

84101
target("demo")
85102
set_kind("binary")
@@ -89,7 +106,7 @@ target("demo")
89106
add_packages("llmapi")
90107
```
91108

92-
See [docs/getting-started.md](docs/getting-started.md) and [docs/providers.md](docs/providers.md) for more setup detail.
109+
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.
93110

94111
## License
95112

‎README.zh.hant.md‎

Lines changed: 75 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -1,86 +1,113 @@
11
# llmapi
22

3-
> Modern C++ LLM API client with openai-compatible support
3+
> 使用 C++23 模組建構的現代 LLM 客戶端
44
55
[![C++23](https://img.shields.io/badge/C%2B%2B-23-blue.svg)](https://en.cppreference.com/w/cpp/23)
66
[![Module](https://img.shields.io/badge/module-ok-green.svg)](https://en.cppreference.com/w/cpp/language/modules)
77
[![License](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](LICENSE)
8-
[![OpenAI Compatible](https://img.shields.io/badge/OpenAI_API-Compatible-green.svg)](https://platform.openai.com/docs/api-reference)
8+
[![OpenAI Compatible](https://img.shields.io/badge/OpenAI-Compatible-green.svg)](https://platform.openai.com/docs/api-reference)
99

1010
| [English](README.md) - [简体中文](README.zh.md) - 繁體中文 |
1111
|:---:|
12-
| [完整文件](docs/) - [C++ API](docs/cpp-api.md) - [C API](docs/c-api.md) - [範例](docs/examples.md) |
12+
| [文件導覽](docs/README.md) - [繁體中文文件](docs/zh-hant/README.md) - [English Docs](docs/en/README.md) - [简体中文文档](docs/zh/README.md) |
1313

14-
簡潔、型別安全的 LLM API 客戶端，使用 C++23 模組。流式介面設計，零成本抽象。支援 OpenAI、Poe、DeepSeek 及相容端點。
14+
`llmapi` 提供型別化的 `Client<Provider>` API，涵蓋聊天、串流輸出、embeddings、工具呼叫與對話持久化。預設別名 `Config` 對應 OpenAI 風格設定，常見情況下不需要顯式寫出 `openai::OpenAI(...)`。
1515

16-
## ✨ 特性
16+
## 特性
1717

18-
- **C++23 模組** - `import mcpplibs.llmapi`
19-
- **自動儲存歷史** - 對話歷史自動管理
20-
- **型別安全串流** - 概念約束的回呼函式
21-
- **流式介面** - 可鏈式呼叫的方法
22-
- **提供商無關** - OpenAI、Poe 及相容端點
18+
- C++23 模組：`import mcpplibs.llmapi`
19+
- 強型別訊息、工具與回應結構
20+
- 同步、非同步、串流聊天介面
21+
- OpenAI Provider 支援 embeddings
22+
- 支援儲存 / 載入對話歷史
23+
- 可透過 `baseUrl` 存取 OpenAI 相容端點
2324

24-
## 快速開始
25+
## 生產可用性
26+
27+
`llmapi` 目前適合內部工具、原型專案與早期生產試用，但還不應直接視為完整工業級基礎設施。
28+
29+
要達到那個標準，至少還需要補齊：
2530

31+
- 統一的 provider / 傳輸層錯誤模型
32+
- 重試、退避、逾時、冪等策略
33+
- 長請求與串流請求的取消能力
34+
- 日誌、指標、trace hook、請求關聯資訊
35+
- 自研 HTTP/TLS 傳輸層的進一步加固
36+
- 故障注入、並發、Mock、大規模測試
37+
- 更強的 API 相容性與版本穩定性承諾
38+
- 更完整的生產設定面
39+
- 明確的執行緒安全與並發語義
40+
- 面向維運的重試、金鑰、代理、故障處理文件
41+
42+
## 快速開始
2643

2744
```cpp
28-
import std;
2945
import mcpplibs.llmapi;
46+
import std;
3047

3148
int main() {
32-
using namespace mcpplibs;
33-
34-
llmapi::Client client(std::getenv("OPENAI_API_KEY"), llmapi::URL::Poe);
35-
36-
client.model("gpt-5")
37-
.system("You are a helpful assistant.")
38-
.user("In one sentence, introduce modern C++. 並給出中文翻譯")
39-
.request([](std::string_view chunk) {
40-
std::print("{}", chunk);
41-
std::cout.flush();
42-
});
49+
using namespace mcpplibs::llmapi;
50+
51+
auto apiKey = std::getenv("OPENAI_API_KEY");
52+
if (!apiKey) {
53+
std::cerr << "OPENAI_API_KEY not set\n";
54+
return 1;
55+
}
56+
57+
auto client = Client(Config{
58+
.apiKey = apiKey,
59+
.model = "gpt-4o-mini",
60+
});
4361

62+
client.system("You are a concise assistant.");
63+
auto resp = client.chat("用兩句話解釋 C++23 模組的價值。");
64+
65+
std::cout << resp.text() << '\n';
4466
return 0;
4567
}
4668
```
4769

48-
### 模型 / 提供商
70+
## Provider
71+
72+
- `Config`：`openai::Config` 的匯出別名，預設走 OpenAI 風格
73+
- `openai::OpenAI`：OpenAI 聊天、串流、工具呼叫、embeddings
74+
- `AnthropicConfig` / `anthropic::Anthropic`：Anthropic 聊天與串流
75+
76+
相容端點範例：
4977

5078
```cpp
51-
llmapi::Client client(apiKey, llmapi::URL::OpenAI); // OpenAI
52-
llmapi::Client client(apiKey, llmapi::URL::Poe); // Poe
53-
llmapi::Client client(apiKey, llmapi::URL::DeepSeek); // Deepseek
54-
llmapi::Client client(apiKey, "https://custom.com"); // 自訂
79+
auto client = Client(Config{
80+
.apiKey = std::getenv("DEEPSEEK_API_KEY"),
81+
.baseUrl = std::string(URL::DeepSeek),
82+
.model = "deepseek-chat",
83+
});
5584
```
5685

57-
## 🛠️ 建置
86+
## 建置與執行
5887

5988
```bash
60-
xmake # 建置
61-
xmake run basic # 執行範例（需先設定 OPENAI_API_KEY）
89+
xmake
90+
xmake run hello_mcpp
91+
xmake run basic
92+
xmake run chat
6293
```
6394

64-
## 📦 在建置工具中使用
65-
66-
### xmake
95+
## 套件管理使用
6796

6897
```lua
69-
-- 0 - 新增 mcpplibs 索引倉庫
70-
add_repositories("mcpplibs-index https://github.com/mcpplibs/llmapi.git")
71-
72-
-- 1 - 新增需要的函式庫和版本
73-
add_requires("llmapi 0.0.2")
98+
add_repositories("mcpplibs-index https://github.com/mcpplibs/mcpplibs-index.git")
99+
add_requires("llmapi 0.1.0")
100+
101+
target("demo")
102+
set_kind("binary")
103+
set_languages("c++23")
104+
set_policy("build.c++.modules", true)
105+
add_files("src/*.cpp")
106+
add_packages("llmapi")
74107
```
75108

76-
> More: [mcpplibs-index](https://github.com/mcpplibs/mcpplibs-index)
77-
78-
### cmake
79-
80-
```
81-
todo...
82-
```
109+
更多內容見 [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)。
83110

84-
## 📄 授權條款
111+
## 授權
85112

86-
Apache-2.0 - 詳見 [LICENSE](LICENSE)
113+
Apache-2.0，詳見 [LICENSE](LICENSE)

0 commit comments

Comments
 (0)