Skip to content

Commit a401460

Browse files
jinzhongjiajinzhongjia
committed
docs(project): restructure AGENTS.md version guide
- Replace file reference table with version maintenance workflows - Reorganize build system documentation into practical procedures - Add detailed procedures for version-specific compilation fixes - Consolidate version compatibility information
1 parent 1688e8c commit a401460

File tree

1 file changed

+82
-272
lines changed

1 file changed

+82
-272
lines changed

‎AGENTS.md‎

Lines changed: 82 additions & 272 deletions
Original file line numberDiff line numberDiff line change
@@ -121,308 +121,118 @@ bun check
121121
- `zig fmt` 处理 Zig 源文件
122122
- AutoCorrect 处理中文文本格式
123123

124-
## 关键文件及其用途
124+
## 版本兼容性维护
125125

126-
| 文件/目录 | 用途 |
127-
| ------------------------------ | ------------------------------------------------- |
128-
| `build.zig` | 主构建编排器，检测 Zig 版本并委托给对应的构建脚本 |
129-
| `build/0.15.zig` | 当前活跃的构建脚本，具有智能示例发现功能 |
130-
| `course/.vitepress/config.mts` | VitePress 配置（语言、主题、SEO） |
131-
| `course/.vitepress/sidebar.ts` | 定义课程导航结构 |
132-
| `course/code/15/` | Zig 0.15 可运行示例（当前活跃版本） |
133-
| `course/basic/` | Zig 基础概念（变量、类型、控制流） |
134-
| `course/advanced/` | 进阶主题（comptime、异步、内存管理） |
135-
| `course/update/` | 版本迁移指南 |
136-
| `package.json` | 构建脚本和 Node.js 依赖 |
137-
| `.github/workflows/build.yml` | 跨平台和版本的 CI/CD 测试 |
126+
### 多版本构建系统架构
138127

139-
## 代码示例组织方式
128+
项目采用版本分发架构来支持多个 Zig 版本：
140129

141-
示例按 Zig 版本组织在 `course/code/` 目录下：
130+
1. **主构建入口** (`build.zig`): 检测当前 Zig 编译器版本，自动分发到对应的版本特定构建脚本
131+
2. **版本构建脚本** (`build/0.XX.zig`): 每个版本有独立的构建逻辑
132+
3. **代码示例目录** (`course/code/XX/`): 每个版本维护独立的示例代码
142133

143-
### 结构模式
134+
### 修复不同版本编译问题的工作流程
144135

145-
1. **独立文件**：简单示例作为单个 `.zig` 文件
146-
- 示例：`course/code/15/array.zig`、`course/code/15/comptime.zig`
147-
- 构建脚本自动发现并编译这些文件
136+
当需要修复特定 Zig 版本的编译问题时，需要处理以下目录：
148137

149-
2. **子项目**：复杂示例拥有自己的 `build.zig`
150-
- 示例：`course/code/15/build_system/`、`course/code/15/package_management_importer/`
151-
- 构建脚本递归调用子构建
138+
#### 1. 更新构建脚本
152139

153-
### 添加新示例
140+
**路径**: `build/0.XX.zig`
154141

155-
添加新示例时：
142+
当 Zig 编译器 API 发生变更时需要更新：
143+
- 构建系统 API 变更（如 `std.Build` 接口改变）
144+
- 模块系统变更（如 `root_module` 相关 API）
145+
- 目标平台和优化选项变更
156146

157-
1. **简单概念**：在 `course/code/15/` 创建独立 `.zig` 文件
158-
2. **复杂功能**：创建带有 `build.zig` 的子目录
159-
3. **更新文档**：在相应章节添加对应的 `.md` 文件
160-
4. **确保编译**：运行 `zig build` 验证
161-
5. **格式化代码**：提交前运行 `bun format`
147+
**示例场景**:
148+
- Zig 0.12 引入模块系统，需要从 `addExecutable` 迁移到 `addModule`
149+
- Zig 0.14 更改了目标解析方式，需要更新 `resolved_target` 相关代码
162150

163-
## 文档结构
151+
#### 2. 更新代码示例
164152

165-
课程遵循渐进式学习路径：
153+
**路径**: `course/code/XX/`
166154

167-
1. **环境搭建**（`course/environment/`）
168-
- 安装指南
169-
- 编辑器配置
170-
- Zig CLI 参考
155+
此目录包含两类文件需要维护：
171156

172-
2. **基础学习**（`course/basic/`）
173-
- 变量和类型
174-
- 控制流
175-
- 错误处理
176-
- 类型系统基础
157+
##### a) 单文件示例（直接的 .zig 文件）
158+
这些文件会被构建脚本直接编译为可执行文件和测试：
159+
- `hello_world.zig`
160+
- `array.zig`
161+
- `comptime.zig`
162+
- 等等...
177163

178-
3. **进阶学习**（`course/advanced/`）
179-
- 编译期计算（comptime）
180-
- 异步/await
181-
- 内存管理
182-
- C 互操作
183-
- 反射和元编程
164+
**修复重点**:
165+
- 标准库 API 变更（如 `std.debug.print`、`std.mem.Allocator`）
166+
- 语法变更（如错误处理、可选类型语法）
167+
- 类型系统变更
184168

185-
4. **工程实践**（`course/engineering/`）
186-
- 构建系统
187-
- 包管理
188-
- 单元测试
189-
- 代码风格指南
169+
##### b) 项目类型示例（子目录包含 build.zig）
170+
这些是完整的 Zig 项目，有自己的构建系统：
171+
- `build_system/` - 构建系统示例
172+
- `import_dependency_build/` - 依赖管理示例
173+
- `import_vcpkg/` - C 库集成示例
190174

191-
5. **实战示例**（`course/examples/`）
192-
- 完整项目（如 TCP 服务器）
175+
**修复重点**:
176+
- 项目自己的 `build.zig` 需要同步更新
177+
- 依赖声明方式的变更（如 `build.zig.zon`）
178+
- 模块导入和导出方式的变更
193179

194-
6. **版本指南**（`course/update/`）
195-
- 版本发布说明
196-
- 迁移指南
180+
#### 3. 版本符号链接维护
197181

198-
## 构建系统内部机制
182+
**当前符号链接**:
183+
- `course/code/13/` → `./12` (Zig 0.13 与 0.12 兼容)
184+
- `course/code/release/` → `./15` (指向最新稳定版)
199185

200-
### 主构建脚本（`build.zig`）
186+
**维护规则**:
187+
- 如果新版本完全兼容旧版本，可以创建符号链接而不是复制代码
188+
- 当有破坏性变更时，必须创建独立目录并更新所有示例
201189

202-
主构建脚本：
190+
#### 4. 验证流程
203191

204-
1. 检测当前 Zig 编译器版本
205-
2. 分发到 `build/` 目录下对应的版本特定构建脚本
206-
3. 优雅处理版本兼容性
192+
在根目录运行 `zig build` 验证修复：
207193

208-
### 版本特定构建脚本（`build/0.15.zig`）
209-
210-
每个版本构建脚本：
211-
212-
1. **发现示例**：扫描 `course/code/VERSION/` 目录
213-
2. **分类**：
214-
- 独立 `.zig` 文件 → 编译为可执行文件
215-
- 包含 `build.zig` 的目录 → 作为子项目调用
216-
3. **平台处理**：应用平台特定配置
217-
4. **测试执行**：运行内嵌的单元测试
218-
219-
### 示例发现算法
194+
```bash
195+
# 主 build.zig 会自动选择对应版本的构建脚本
196+
zig build
220197

198+
# 构建过程会：
199+
# 1. 编译 course/code/XX/ 下的所有单文件示例
200+
# 2. 运行所有测试
201+
# 3. 递归构建子目录中的项目示例
221202
```
222-
对于 course/code/VERSION/ 中的每个项目：
223-
如果项目是 .zig 文件：
224-
→ 创建可执行文件构建步骤
225-
否则如果项目是目录：
226-
如果目录包含 build.zig：
227-
→ 创建对子项目构建的依赖
228-
否则：
229-
→ 跳过（可能是支持文件）
230-
```
231-
232-
## CI/CD 流水线
233-
234-
### 构建工作流（`.github/workflows/build.yml`）
235203

236-
- **触发器**：`.zig` 文件、构建脚本或配置文件变更
237-
- **矩阵**：3 个操作系统（Ubuntu、macOS、Windows）× 6 个 Zig 版本
238-
- **目的**：确保所有示例在各平台和版本上都能编译
239-
- **调度**：每日运行
204+
#### 5. 常见破坏性变更类型
240205

241-
### 部署工作流（`.github/workflows/deploy.yml`）
206+
**标准库变更**:
207+
- 分配器 API (`std.heap.GeneralPurposeAllocator`)
208+
- 文件系统 API (`std.fs`)
209+
- 网络 API (`std.net`)
242210

243-
- **触发器**：推送到 `main` 分支
244-
- **目的**：构建并部署文档到 GitHub Pages
245-
- **步骤**：
246-
1. 安装 Bun
247-
2. 安装依赖
248-
3. 构建 VitePress 站点
249-
4. 上传到 GitHub Pages
250-
251-
### 检查工作流（`.github/workflows/check.yml`）
252-
253-
- **触发器**：Pull Request、推送
254-
- **目的**：验证代码格式
255-
- **工具**：Prettier、Zig fmt、AutoCorrect
256-
257-
## 编码规范
258-
259-
### 提交信息
260-
261-
遵循 Conventional Commits：
262-
263-
```
264-
<type>(<scope>): <description>
211+
**语言特性变更**:
212+
- 错误处理语法
213+
- 可选类型语法
214+
- 编译时特性
265215

266-
类型: feat, fix, docs, refactor, chore, test, style
267-
作用域: course/basic, course/advanced, build, ci 等
216+
**构建系统变更**:
217+
- `std.Build` API
218+
- 模块系统
219+
- 依赖管理（`build.zig.zon`）
268220

269-
示例:
270-
- feat(course/basic): 为 0.15 添加数组示例
271-
- fix(build): 修正平台检测逻辑
272-
- docs(course/update): 更新 0.15.1 迁移指南
273-
- refactor(course/code/15): 简化 comptime 示例
274-
```
221+
#### 6. 实用技巧
275222

276-
### 分支命名
223+
**批量测试多个版本**:
224+
项目的 CI 系统（`.github/workflows/build.yml`）会在多个平台和 Zig 版本上运行构建，可以参考 CI 配置来本地测试多版本兼容性。
277225

278-
```
279-
feature/<description> # 新功能
280-
fix/<description> # Bug 修复
281-
docs/<description> # 文档更新
282-
update/<description> # 版本更新
226+
**创建新版本支持**:
227+
1. 复制最近版本的 `build/0.XX.zig` 到新版本
228+
2. 复制或链接 `course/code/XX/` 目录
229+
3. 在主 `build.zig` 中添加新版本的 case 分支
230+
4. 运行构建并修复所有编译错误
231+
5. 更新 `course/code/release/` 符号链接（如果是最新稳定版）
283232

284-
示例: update/fix-0.15.1
233+
**检查依赖项目**:
234+
不要忘记检查子目录项目的构建：
235+
```bash
236+
cd course/code/15/build_system
237+
zig build
285238
```
286-
287-
### 代码风格
288-
289-
**Zig 代码**：
290-
291-
- 使用 `zig fmt`（在 CI 中强制执行）
292-
- 遵循 Zig 风格指南原则
293-
- 为公共 API 添加文档注释
294-
295-
**Markdown**：
296-
297-
- 中文文本使用中文标点（。，！？）
298-
- 中文和英文/数字之间添加空格
299-
- 代码块使用具体语言标记：` ```zig`，不要用 ` ```
300-
- 图片使用相对路径：`![描述](../picture/...)`
301-
302-
**中文文本**：
303-
304-
- 正确使用标点符号（。不是 .）
305-
- 正确使用引号（「」不是 ""）
306-
- 中英文之间加空格
307-
- 由 CI 中的 AutoCorrect 检查
308-
309-
### 文件组织
310-
311-
**文档文件**：
312-
313-
- 放在 `course/` 下的适当分类中
314-
- 使用英文描述性文件名
315-
- 如添加新页面需更新 `course/.vitepress/sidebar.ts`
316-
317-
**代码示例**：
318-
319-
- 放在 `course/code/15/`（或当前版本）
320-
- 尽可能匹配文档结构
321-
- 包含解释概念的文档注释
322-
323-
**图片**：
324-
325-
- 放在 `course/picture/` 中
326-
- 使用子目录组织
327-
- 提交前优化图片
328-
329-
## 常见任务
330-
331-
### 添加新的语言概念
332-
333-
1. **创建文档**：`course/basic/<topic>.md` 或 `course/advanced/<topic>.md`
334-
2. **添加代码示例**：`course/code/15/<topic>.zig`
335-
3. **更新侧边栏**：在 `course/.vitepress/sidebar.ts` 添加条目
336-
4. **测试编译**：运行 `zig build`
337-
5. **格式化**：运行 `bun format`
338-
6. **提交**：使用规范的提交信息
339-
340-
### 为新 Zig 版本更新
341-
342-
1. **创建新构建脚本**：`build/0.XX.zig`（从上一版本复制并修改）
343-
2. **复制示例**：`cp -r course/code/15 course/code/XX`
344-
3. **更新符号链接**：`ln -sf XX course/code/release`
345-
4. **修复破坏性变更**：根据需要更新代码示例
346-
5. **记录变更**：创建 `course/update/upgrade-0.XX.md`
347-
6. **更新 CI**：在 `.github/workflows/build.yml` 矩阵中添加新版本
348-
7. **彻底测试**：确保所有示例都能编译
349-
350-
### 修复文档问题
351-
352-
1. **定位文件**：使用 grep 或文件搜索
353-
2. **编辑内容**：保持中文文档风格
354-
3. **预览**：运行 `bun dev` 查看变更
355-
4. **格式化**：运行 `bun format`
356-
5. **提交**：使用 `docs(<scope>): <description>` 格式
357-
358-
### 添加复杂示例
359-
360-
1. **创建目录**：`course/code/15/<project-name>/`
361-
2. **添加 build.zig**：创建适当的构建配置
362-
3. **添加源文件**：实现示例
363-
4. **添加 README**：解释示例演示的内容
364-
5. **更新文档**：在相关 `.md` 文件中引用示例
365-
6. **测试**：从项目根目录运行 `zig build`
366-
367-
## 版本兼容性策略
368-
369-
项目使用以下方式维护跨 Zig 版本兼容性：
370-
371-
1. **独立代码目录**：每个主要版本有自己的示例
372-
2. **版本特定构建脚本**：处理语法/API 差异
373-
3. **符号链接**：用于兼容版本（如 0.13 → 0.12）
374-
4. **迁移指南**：记录破坏性变更和升级路径
375-
5. **CI 矩阵测试**：通过自动化测试确保兼容性
376-
377-
## 技术栈
378-
379-
- **语言**：Zig（0.11 - 0.16）
380-
- **文档**：VitePress（Vue 3、TypeScript）
381-
- **包管理器**：Bun（也可使用 npm/yarn）
382-
- **CI/CD**：GitHub Actions
383-
- **托管**：GitHub Pages
384-
- **格式化**：Prettier、Zig fmt、AutoCorrect
385-
386-
## AI 助手重要注意事项
387-
388-
### 处理文档时
389-
390-
1. **语言**：使用简体中文编写，使用正确的标点符号
391-
2. **代码块**：始终指定语言：` ```zig`，绝不使用纯 ` ```
392-
3. **格式化**：中文文本应使用中文标点（。而非 .）
393-
4. **间距**：在中文字符和英文/数字之间添加空格
394-
5. **链接**：内部文档使用相对路径
395-
396-
### 处理代码示例时
397-
398-
1. **版本**：除非另有说明，目标版本为 Zig 0.15
399-
2. **位置**：添加到 `course/code/15/`
400-
3. **测试**：确保代码能编译和运行
401-
4. **文档**：代码配合解释性文档
402-
5. **注释**：为公共 API 使用文档注释（`///`）
403-
404-
### 修改构建系统时
405-
406-
1. **主 build.zig**：很少需要更改（处理版本分发）
407-
2. **版本脚本**：修改适当的 `build/0.XX.zig`
408-
3. **发现逻辑**：理解自动示例检测机制
409-
4. **平台处理**：考虑 Linux、macOS、Windows 差异
410-
411-
### 更新 CI/CD 时
412-
413-
1. **构建矩阵**：保持版本矩阵更新
414-
2. **缓存**：保留 Zig 编译器缓存以提高速度
415-
3. **平台测试**：确保跨平台兼容性
416-
4. **部署工作流**：仅在 main 分支运行
417-
418-
## 资源链接
419-
420-
- [Zig 官方文档](https://ziglang.org/documentation/)
421-
- [VitePress 文档](https://vitepress.dev/)
422-
- [Conventional Commits](https://www.conventionalcommits.org/)
423-
- [贡献指南](CONTRIBUTING.md)
424-
- [行为准则](CODE_OF_CONDUCT.md)
425-
426-
---
427-
428-
最后更新：2025-10-22（由 AI 助手自动生成）

0 commit comments

Comments
 (0)