mcpplibs
diff --git a/‎.agents/docs/v0.1.0/README.md‎
Lines changed: 1437 additions & 0 deletions b/‎.agents/docs/v0.1.0/README.md‎
Lines changed: 1437 additions & 0 deletions
diff --git a/‎.agents/plans/2026-03-10-llmapi-v0.1.0.md‎
Lines changed: 2103 additions & 0 deletions b/‎.agents/plans/2026-03-10-llmapi-v0.1.0.md‎
Lines changed: 2103 additions & 0 deletions
diff --git a/‎.agents/skills/README.md‎
Lines changed: 24 additions & 0 deletions b/‎.agents/skills/README.md‎
Lines changed: 24 additions & 0 deletions
diff --git a/‎.agents/skills/mcpp-style-ref/SKILL.md‎
Lines changed: 171 additions & 0 deletions b/‎.agents/skills/mcpp-style-ref/SKILL.md‎
Lines changed: 171 additions & 0 deletions
diff --git a/‎.agents/skills/mcpp-style-ref/reference.md‎
Lines changed: 187 additions & 0 deletions b/‎.agents/skills/mcpp-style-ref/reference.md‎
Lines changed: 187 additions & 0 deletions
@@ -0,0 +1,24 @@
+# mcpp-style-ref Agent Skills
+
+用于指导 Agent 在编写或审查 Modern/Module C++ 代码时遵循 mcpp-style-ref 规范的技能。
+
+## 可用技能
+
+| 技能 | 说明 |
+|------|------|
+| [mcpp-style-ref](mcpp-style-ref/SKILL.md) | 面向 mcpp 项目的 Modern/Module C++ (C++23) 命名、模块化与实践规则 |
+
+## 使用方式
+
+要在 Cursor 中使用，请将技能软链接或复制到项目的 `.cursor/skills/`：
+
+```bash
+mkdir -p .cursor/skills
+ln -s ../../skills/mcpp-style-ref .cursor/skills/mcpp-style-ref
+```
+
+或安装为个人技能：
+
+```bash
+ln -s /path/to/mcpp-style-ref/skills/mcpp-style-ref ~/.cursor/skills/mcpp-style-ref
+```
@@ -0,0 +1,171 @@
+---
+name: mcpp-style-ref
+description: 为 mcpp 项目应用 Modern/Module C++ (C++23) 编码风格。适用于编写或审查带模块的 C++ 代码、命名标识符、组织 .cppm/.cpp 文件，或用户提及 mcpp、module C++、现代 C++ 风格时。
+---
+
+# mcpp-style-ref
+
+mcpp 项目的 Modern/Module C++ 风格参考。C++23，使用 `import std`。
+
+## 快速参考
+
+### 命名
+
+| 种类 | 风格 | 示例 |
+|------|------|------|
+| 类型/类 | PascalCase（大驼峰） | `StyleRef`, `HttpServer` |
+| 对象/成员 | camelCase（小驼峰） | `fileName`, `configText` |
+| 函数 | snake_case（下划线） | `load_config_file()`, `parse_()` |
+| 私有 | `_` 后缀 | `fileName_`, `parse_()` |
+| 常量 | UPPER_SNAKE | `MAX_SIZE`, `DEFAULT_TIMEOUT` |
+| 全局 | `g` 前缀 | `gStyleRef` |
+| 命名空间 | 全小写 | `mcpplibs`, `mylib` |
+
+### 模块基础
+
+- 使用 `import std` 替代 `#include <print>` 和 `#include <xxx>`
+- 使用 `.cppm` 作为模块接口；分离实现时用 `.cpp`
+- `export module module_name;` — 模块声明
+- `export import :partition;` — 导出分区
+- `import :partition;` — 内部分区（不导出）
+
+### 模块结构
+
+```
+// .cppm
+export module a;
+
+export import a.b;
+export import :a2;   // 可导出分区
+
+import std;
+import :a1;          // 内部分区
+```
+
+### 模块命名
+
+- 模块：`topdir.subdir.filename`（如 `a.b`, `a.c`）
+- 分区：`module_name:partition`（如 `a:a1`, `a.b:b1`）
+- 用目录路径区分同名：`a/c.cppm` → `a.c`，`b/c.cppm` → `b.c`
+
+### 类布局
+
+```cpp
+class StyleRef {
+private:
+    std::string fileName_;  // 数据成员带 _ 后缀
+
+public:  // Big Five
+    StyleRef() = default;
+    StyleRef(const StyleRef&) = default;
+    // ...
+
+public:  // 公有接口
+    void load_config_file(std::string fileName);  // 函数 snake_case，参数 camelCase
+
+private:
+    void parse_(std::string config);  // 私有函数以 _ 结尾
+};
+```
+
+### 实践规则
+
+- **初始化**：用 `{}` — `int n { 42 }`，`std::vector<int> v { 1, 2, 3 }`
+- **字符串**：只读参数用 `std::string_view`
+- **错误**：用 `std::optional` / `std::expected` 替代 int 错误码
+- **内存**：用 `std::unique_ptr`、`std::shared_ptr`；避免裸 `new`/`delete`
+- **RAII**：将资源与对象生命周期绑定
+- **auto**：用于迭代器、lambda、复杂类型；需要明确表达意图时保留显式类型
+- **宏**：优先用 `constexpr`、`inline`、`concept` 替代宏
+
+### 接口与实现
+
+两种写法均支持。
+
+**写法 A：合并** — 接口与实现同在一个 `.cppm` 中：
+
+```cpp
+// mylib.cppm
+export module mylib;
+
+export int add(int a, int b) {
+    return a + b;
+}
+```
+
+**写法 B：分离** — 接口在 `.cppm`，实现在 `.cpp`（编译期隐藏实现）：
+
+```cpp
+// error.cppm（接口）
+export module error;
+
+export struct Error {
+    void test();
+};
+```
+
+```cpp
+// error.cpp（实现）
+module error;
+
+import std;
+
+void Error::test() {
+    std::println("Hello");
+}
+```
+
+简单模块用写法 A；需隐藏实现或减少编译依赖时用写法 B。
+
+## 项目环境配置
+
+安装 xlings 包管理器后，获取 GCC 15 工具链：
+
+#### Linux/MacOS
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/d2learn/xlings/refs/heads/main/tools/other/quick_install.sh | bash
+```
+
+#### Windows - PowerShell
+
+```bash
+irm https://raw.githubusercontent.com/d2learn/xlings/refs/heads/main/tools/other/quick_install.ps1 | iex
+```
+
+然后安装工具链(仅linux, 其中windows默认用msvc)：
+
+```bash
+xlings install gcc@15 -y
+```
+
+> xlings详细信息可参考 [xlings](https://github.com/d2learn/xlings) 文档。
+
+## 示例项目创建
+
+参考本仓库 `src/` 目录结构：
+
+- `xmake.lua`：配置 `set_languages("c++23")`、`set_policy("build.c++.modules", true)`
+- `add_files("main.cpp")`、`add_files("**.cppm")` 添加源文件
+- 可执行目标与静态库目标分离（如 `mcpp-style-ref` 主程序、`error` 静态库）
+
+构建：
+
+```bash
+xmake build
+xmake run
+```
+
+## 适用场景
+
+- 编写新的 C++ 模块代码（`.cppm`、`.cpp`）
+- 审查或重构 mcpp 项目中的 C++ 代码
+- 用户询问「mcpp 风格」「module C++ 风格」或「现代 C++ 惯例」
+
+## 更多资源
+
+- 完整参考：[reference.md](reference.md)
+- mcpp-style-ref 仓库：[github.com/mcpp-community/mcpp-style-ref](https://github.com/mcpp-community/mcpp-style-ref)
+    - 项目说明：[../../README.md](../../README.md)
+    - 示例项目：[src/](../../../src)
+- xlings 包管理器：[github.com/d2learn/xlings](https://github.com/d2learn/xlings)
@@ -0,0 +1,187 @@
+# mcpp-style-ref 参考
+
+来自 [mcpp-style-ref](https://github.com/mcpp-community/mcpp-style-ref) 的详细风格规则。
+
+## 一、标识符命名
+
+### 1.0 类型 — PascalCase（大驼峰）
+
+```cpp
+struct StyleRef {
+    using FileNameType = std::string;
+};
+```
+
+### 1.1 对象/数据成员 — camelCase（小驼峰）
+
+```cpp
+struct StyleRef {
+    std::string fileName;
+};
+StyleRef mcppStyle;
+```
+
+### 1.2 函数 — snake_case（下划线）
+
+```cpp
+void load_config_file(const std::string& fileName);
+void parse_();
+int max_retry_count();
+```
+
+### 1.3 私有 — `_` 后缀
+
+私有的数据成员和函数使用 `_` 后缀：
+
+```cpp
+private:
+    std::string fileName_;
+    void parse_(const std::string& config);
+```
+
+### 1.4 空格
+
+运算符两侧加空格以增强可读性：`T x { ... }`、`int n { 42 }`。
+
+### 1.5 其他
+
+- 常量：`MAX_SIZE`、`DEFAULT_TIMEOUT`
+- 全局：`gStyleRef`、`g_debug`
+- 模板命名：遵循类/函数命名风格
+
+---
+
+## 二、模块化
+
+### 模块文件结构
+
+```cpp
+module;              // 可选的全局模块片段
+#include <xxx>       // 需要传统头文件时
+
+export module module_name;
+// export import :partition;
+// import :partition;
+
+import std;
+import xxx;
+
+export int add(int a, int b) {
+    return a + b;
+}
+```
+
+### .cppm 与 .h/.hpp
+
+使用 `.cppm` 作为模块接口。用 `export` 关键字导出：
+
+```cpp
+export module mcpplibs;
+
+export int add(int a, int b) {
+    return a + b;
+}
+```
+
+### 接口与实现
+
+合并（全部在 .cppm）与分离（.cppm + .cpp）均有效。
+
+**合并于 .cppm** — 见上方「.cppm 与 .h/.hpp」：导出与实现在同一文件。
+
+**方式一：命名空间隔离**
+
+```cpp
+export module mcpplibs;
+
+namespace mcpplibs_impl {
+    int add(int a, int b) { return a + b; }
+}
+
+export namespace mcpplibs {
+    using mcpplibs_impl::add;
+};
+```
+
+**方式二：分离（.cppm + .cpp）**
+
+- `.cppm`：仅接口 — `export module error;` + `export struct Error { void test(); };`
+- `.cpp`：实现 — `module error;` + 函数体
+
+简单模块用合并；需隐藏实现或减少编译依赖时用分离。
+
+### 多文件模块
+
+```
+a/
+├── a1.cppm     # module a:a1（内部分区）
+├── a2.cppm     # export module a:a2
+├── b/
+│   ├── b1.cppm # export module a.b:b1
+│   └── b2.cppm # export module a.b:b2
+├── b.cppm      # export module a.b
+└── c.cppm      # module a.c
+a.cppm          # export module a
+```
+
+- **可导出分区**：`export module a:a2;` — 可被重新导出
+- **内部分区**：`module a:a1;` — 不导出，仅模块内部使用
+
+```cpp
+// a.cppm
+export module a;
+export import :a2;
+import :a1;
+```
+
+### 向前兼容
+
+将传统 C/C++ 头文件封装到兼容模块中：
+
+```cpp
+module;
+
+#include <lua.h>
+// ...
+
+export module lua;
+
+export namespace lua {
+    using lua_State = ::lua_State;
+    // ...
+}
+```
+
+### 其他
+
+- 优先用 `constexpr` 替代宏
+- 模板的静态成员：使用 `inline static`（C++17）确保单一定义
+
+---
+
+## 三、实践参考
+
+### auto
+
+用于迭代器、lambda、复杂类型。显式类型更清晰时避免使用。
+
+### 花括号初始化
+
+`int n { 42 }`、`std::vector<int> v { 1, 2, 3 }`、`Point p { 10, 20 }`。
+
+### 智能指针
+
+`std::make_unique`、`std::make_shared`；避免裸 `new`/`delete`。
+
+### string_view
+
+用于只读字符串参数。不拥有数据，调用方需保证底层数据有效。
+
+### optional / expected
+
+- `std::optional`：可有可无的值
+- `std::expected`（C++23）：成功返回值或错误
+
+### RAII
+
+将资源与对象生命周期绑定。使用 `std::fstream`、`std::lock_guard` 等。