Skip to content

Commit f41bcbc

Browse files
SunrisepeakSunrisepeak
committed
Add llmapi usage best-practices skill
1 parent 4ec1654 commit f41bcbc

File tree

3 files changed

+155
-0
lines changed

3 files changed

+155
-0
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+
- 推荐错误处理：异常模式为主，自动重试建议由库使用者在上层实现

0 commit comments

Comments
 (0)