Skip to content

Commit 96ebb19

Browse files
SunrisepeakSunrisepeak
committed
docs: update README + add agent skills (contributing, usage)
- Move WIP notice from bottom to after "why mcpp" section - Soften "Linux上体验最好的选择" wording - Change AI prompts to copyable code blocks with repo URL - Simplify contributing section, reference .agents/skills/ - Add .agents/skills/contributing.md (agent contribution guide) - Add .agents/skills/mcpp-usage.md (agent usage guide)
1 parent 3f873c4 commit 96ebb19

3 files changed

Lines changed: 410 additions & 41 deletions

File tree

‎.agents/skills/contributing.md‎

Lines changed: 211 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,211 @@
1+
# mcpp 项目开发贡献指南
2+
3+
本文档面向 AI Agent，说明如何参与 mcpp 项目的开发贡献，包括 Bug 修复、新功能、代码优化、文档改进等。
4+
5+
## 项目概况
6+
7+
- 仓库：https://github.com/mcpp-community/mcpp
8+
- 语言：C++23（纯模块化，43+ 个模块，零 .h 头文件）
9+
- 构建：`mcpp build`（mcpp 用自己构建自己）
10+
- 测试：E2E 测试在 `tests/e2e/` 目录下
11+
- 设计文档：`.agents/docs/` 目录
12+
- CI：GitHub Actions，基于 `main` 分支的 PR 自动触发
13+
14+
## 贡献流程
15+
16+
### 1. 先创建 Issue
17+
18+
**所有贡献都应该先创建 Issue**，特别是新功能。这是为了：
19+
- 与维护者对齐需求和设计方向
20+
- 避免重复工作
21+
- 留下讨论记录
22+
23+
**Bug 修复**
24+
25+
```bash
26+
gh issue create \
27+
--title "fix: 简短描述问题" \
28+
--body "## 复现步骤
29+
1. ...
30+
2. ...
31+
32+
## 期望行为
33+
...
34+
35+
## 实际行为
36+
...
37+
38+
## 环境
39+
- mcpp 版本：
40+
- 操作系统：
41+
- 编译器："
42+
```
43+
44+
**新功能请求**
45+
46+
```bash
47+
gh issue create \
48+
--title "feat: 简短描述功能" \
49+
--body "## 动机
50+
为什么需要这个功能？
51+
52+
## 设计思路
53+
大致方案描述。
54+
55+
## 涉及的文件/模块
56+
预估改动范围。"
57+
```
58+
59+
**代码优化 / 重构**
60+
61+
```bash
62+
gh issue create \
63+
--title "refactor: 简短描述优化" \
64+
--body "## 当前问题
65+
...
66+
67+
## 优化方案
68+
...
69+
70+
## 风险评估
71+
是否影响现有功能？"
72+
```
73+
74+
### 2. 实现改动
75+
76+
**分支规范**
77+
78+
```bash
79+
git checkout main
80+
git pull origin main
81+
git checkout -b <type>/<short-description>
82+
# type: feat / fix / refactor / test / docs
83+
```
84+
85+
**开发要求**
86+
87+
- 代码风格：遵循现有代码模式（查看相邻代码的格式、命名、错误处理方式）
88+
- 模块导入：使用 `import std;` 和 `import mcpp.xxx;`
89+
- 不要引入不必要的改动：只改需要改的，不顺手重构不相关代码
90+
91+
**构建验证**
92+
93+
```bash
94+
# 找到 mcpp 二进制
95+
ls target/x86_64-linux-gnu/*/bin/mcpp
96+
97+
# 构建
98+
<mcpp-binary> build
99+
100+
# 如果修改了构建相关代码，确认自举仍能通过
101+
```
102+
103+
**测试**
104+
105+
```bash
106+
# 运行基础测试
107+
bash tests/e2e/01_help_and_version.sh
108+
109+
# 运行与改动相关的 E2E 测试
110+
bash tests/e2e/<relevant-test>.sh
111+
112+
# 如果添加新功能，应创建对应的 E2E 测试
113+
# 测试脚本放在 tests/e2e/ 下，命名格式：<序号>_<描述>.sh
114+
```
115+
116+
### 3. 提交 PR
117+
118+
**提交信息规范**
119+
120+
```
121+
<type>: <简短描述>
122+
123+
type 取值：
124+
feat: 新功能
125+
fix: Bug 修复
126+
refactor: 代码重构（不改变功能）
127+
test: 添加/修改测试
128+
docs: 文档改动
129+
ci: CI/CD 相关
130+
```
131+
132+
**创建 PR**
133+
134+
```bash
135+
git push -u origin <branch-name>
136+
137+
gh pr create \
138+
--title "<type>: 简短描述" \
139+
--body "## Summary
140+
- 改动点 1
141+
- 改动点 2
142+
143+
Closes #<issue-number>
144+
145+
## Test plan
146+
- [ ] mcpp build 编译通过
147+
- [ ] 相关 E2E 测试通过
148+
- [ ] 新增 E2E 测试（如适用）"
149+
```
150+
151+
### 4. CI 必须通过
152+
153+
**PR 的 CI 检查是硬性要求**。CI 不通过的 PR 不会被合入。
154+
155+
- CI workflow 在 `.github/workflows/ci.yml`
156+
- 只有 base 为 `main` 的 PR 会触发 CI
157+
- CI 内容：mcpp 自举构建 + E2E 测试套件
158+
- 如果 CI 失败，检查 `gh run view <run-id> --log-failed` 定位问题
159+
160+
```bash
161+
# 查看 PR 的 CI 状态
162+
gh pr checks <pr-number>
163+
164+
# 查看失败日志
165+
gh run view <run-id> --log-failed
166+
```
167+
168+
### 5. Review & 合入
169+
170+
- 维护者会 review PR 并给出反馈
171+
- 根据反馈修改后再次 push（CI 会重新运行）
172+
- 合入方式：Squash merge
173+
174+
## 常用工具
175+
176+
| 工具 | 用途 |
177+
|---|---|
178+
| `gh` | GitHub CLI — 创建 issue/PR、查看 CI、管理仓库 |
179+
| `git` | 版本控制 |
180+
| `mcpp build` | 编译项目 |
181+
| `mcpp run` | 构建并运行 |
182+
| `mcpp test` | 运行测试 |
183+
| `bash tests/e2e/*.sh` | 运行 E2E 测试 |
184+
185+
## 项目目录结构
186+
187+
```
188+
src/
189+
├── cli.cppm ← 命令行入口（最大文件）
190+
├── config.cppm ← 全局配置
191+
├── manifest.cppm ← mcpp.toml 解析
192+
├── build/ ← 构建系统（ninja 后端、编译标志）
193+
├── pm/ ← 包管理子系统
194+
├── toolchain/ ← 编译器检测与管理
195+
├── modgraph/ ← 模块图扫描与验证
196+
├── pack/ ← 打包发布
197+
├── xlings.cppm ← xlings 抽象层
198+
└── ui.cppm ← 输出样式
199+
200+
tests/e2e/ ← E2E 测试脚本
201+
docs/ ← 用户文档
202+
.agents/docs/ ← 设计文档
203+
.agents/skills/ ← Agent 技能文档
204+
```
205+
206+
## 注意事项
207+
208+
- mcpp 是 C++23 模块项目，修改模块时注意 import 依赖顺序
209+
- 不要修改 `.agents/docs/` 下的设计文档（除非是专门的文档 PR）
210+
- E2E 测试应该能独立运行，不依赖网络（使用本地 path index 等方式）
211+
- 如果不确定设计方向，先在 Issue 里讨论再动手

‎.agents/skills/mcpp-usage.md‎

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
# mcpp 基础用法指南
2+
3+
本文档面向 AI Agent，说明 mcpp 的基础使用方法以及如何帮助用户解决问题。
4+
5+
## mcpp 是什么
6+
7+
mcpp 是一个现代 C++ 模块化构建工具，纯 C++23 模块编写，已实现自举。
8+
9+
- 仓库：https://github.com/mcpp-community/mcpp
10+
- 文档：https://github.com/mcpp-community/mcpp/tree/main/docs
11+
- 包索引：https://github.com/mcpp-community/mcpp-index
12+
- 模块化库集合：https://github.com/mcpplibs
13+
14+
## 安装
15+
16+
```bash
17+
# 方式一：xlings 安装（推荐）
18+
xlings install mcpp -y
19+
20+
# 方式二：一键安装脚本
21+
curl -fsSL https://github.com/mcpp-community/mcpp/releases/latest/download/install.sh | bash
22+
```
23+
24+
安装到 `~/.mcpp/`，自动加入 shell PATH。删除 `~/.mcpp` 即可卸载。
25+
26+
首次运行会自动安装 GCC 工具链到隔离沙盒，不影响系统。
27+
28+
## 核心命令
29+
30+
### 项目管理
31+
32+
```bash
33+
mcpp new <name> # 创建新项目（默认 C++23 模块模板）
34+
mcpp build # 构建
35+
mcpp run [-- args] # 构建并运行（args 透传给可执行文件）
36+
mcpp test [-- args] # 构建并运行测试
37+
mcpp clean # 清理构建产物
38+
```
39+
40+
### 依赖管理
41+
42+
```bash
43+
mcpp add <pkg>[@<ver>] # 添加依赖（如 mcpp add gtest@1.15.2）
44+
mcpp remove <pkg> # 移除依赖
45+
mcpp update [pkg] # 更新依赖版本
46+
mcpp search <keyword> # 搜索包索引
47+
```
48+
49+
### 工具链管理
50+
51+
```bash
52+
mcpp toolchain list # 查看已安装工具链
53+
mcpp toolchain install gcc 16 # 安装 GCC 16
54+
mcpp toolchain install llvm 20 # 安装 LLVM/Clang 20
55+
mcpp toolchain default gcc@16.1.0 # 设置默认工具链
56+
```
57+
58+
### 包索引管理
59+
60+
```bash
61+
mcpp index list # 查看已配置的包索引
62+
mcpp index update [<name>] # 刷新索引
63+
mcpp index pin <name> [rev] # 锁定索引到指定 commit
64+
mcpp index unpin <name> # 解除锁定
65+
```
66+
67+
### 打包发布
68+
69+
```bash
70+
mcpp pack # 打包（默认 bundle-project 模式）
71+
mcpp pack --mode static # musl 全静态打包
72+
mcpp publish --dry-run # 预览发布内容
73+
```
74+
75+
### 诊断
76+
77+
```bash
78+
mcpp self doctor # 环境健康检查
79+
mcpp self env # 打印路径和配置
80+
mcpp explain E0001 # 查看错误码详细解释
81+
mcpp self config --mirror CN # 切换镜像（CN / GLOBAL）
82+
```
83+
84+
## mcpp.toml 基础配置
85+
86+
```toml
87+
[package]
88+
name = "myapp"
89+
version = "0.1.0"
90+
91+
[targets.myapp]
92+
kind = "bin" # bin / lib / shared / test
93+
main = "src/main.cpp"
94+
95+
[dependencies]
96+
gtest = "1.15.2" # 从默认索引安装
97+
98+
[toolchain]
99+
default = "gcc@16.1.0" # 指定编译器
100+
```
101+
102+
更多配置项参见：https://github.com/mcpp-community/mcpp/blob/main/docs/05-mcpp-toml.md
103+
104+
## 工作空间（多包项目）
105+
106+
```toml
107+
# 根 mcpp.toml
108+
[workspace]
109+
members = ["libs/*", "apps/*"]
110+
111+
[workspace.dependencies]
112+
gtest = "1.15.2"
113+
```
114+
115+
```bash
116+
mcpp build # 构建整个工作空间
117+
mcpp build -p member-name # 只构建指定成员
118+
```
119+
120+
## 自定义包索引
121+
122+
```toml
123+
# mcpp.toml
124+
[indices]
125+
my-index = "git@gitlab.example.com:team/mcpp-index.git"
126+
local-dev = { path = "/path/to/local/index" }
127+
128+
[dependencies.my-index]
129+
internal-lib = "1.0.0"
130+
```
131+
132+
## 常见问题处理
133+
134+
### 首次构建慢
135+
136+
首次运行需要下载工具链（GCC/Clang），这是正常的。后续构建会使用缓存。
137+
138+
### command not found
139+
140+
`~/.mcpp/bin` 未加入 PATH。重启终端或执行：
141+
```bash
142+
source ~/.bashrc # bash
143+
source ~/.zshrc # zsh
144+
exec fish # fish
145+
```
146+
147+
### 编译错误
148+
149+
1. 确认 mcpp 版本：`mcpp --version`
150+
2. 确认工具链：`mcpp toolchain list`
151+
3. 尝试清理重建：`mcpp clean && mcpp build`
152+
153+
### 依赖找不到
154+
155+
1. 更新索引：`mcpp index update`
156+
2. 搜索确认包名：`mcpp search <keyword>`
157+
3. 确认 mcpp.toml 中的依赖声明格式
158+
159+
## 问题反馈
160+
161+
如果遇到无法解决的问题：
162+
163+
1. **优先在项目 Issue 中反馈**：https://github.com/mcpp-community/mcpp/issues
164+
- 使用 `gh issue create` 或在页面上创建
165+
- 描述复现步骤、期望行为、实际行为、mcpp 版本和操作系统
166+
167+
2. **社区论坛讨论**：https://forum.d2learn.org/category/20
168+
- 适合使用疑问、最佳实践讨论等
169+
170+
如果 AI Agent 无法直接创建 Issue，请提示用户手动创建，并提供整理好的问题描述。

0 commit comments

Comments
 (0)