Skip to content

Commit 0f14d75

Browse files
jnMetaCodejnMetaCode
committed
feat(book): mdbook scaffold for 3-volume reorg
Reorganize the repo into a 3-volume + appendix book using mdbook. Volumes: getting-started / workflows / architecture; appendix is the cheatsheet. Content uses symlinks to existing markdown — single source of truth, zero duplication. Run 'brew install mdbook && cd book && mdbook serve --open' to preview.
1 parent 7a42f76 commit 0f14d75

25 files changed

Lines changed: 474 additions & 0 deletions

‎book/.gitignore‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# mdbook build output
2+
book/
3+
4+
# 系统文件
5+
.DS_Store
6+
*.swp
7+
8+
# 临时
9+
*.tmp

‎book/README.md‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
# book/ — AI 编程实战三卷书脚手架
2+
3+
> 把 ai-coding-guide 仓库的现成内容重组成 **3 卷 + 1 别册** 的渐进式读本。
4+
> 用 [mdBook](https://rust-lang.github.io/mdBook/) 编译成静态 HTML 网站 + PDF。
5+
6+
## 结构
7+
8+
```
9+
book/
10+
├── README.md ← 你正在看
11+
├── book.toml ← mdbook 配置
12+
├── .gitignore ← 忽略 book/book/ 输出目录
13+
└── src/
14+
├── SUMMARY.md ← 主目录（决定章节顺序）
15+
├── intro.md ← 总序
16+
├── v1-intro.md ← 卷一·入门 序
17+
├── v2-intro.md ← 卷二·工作流 序
18+
├── v3-intro.md ← 卷三·架构 序
19+
├── about.md ← 关于本书
20+
│
21+
├── cheatsheet.md ← 软链 → ../../cheatsheet.md
22+
├── changelog.md ← 软链 → ../../CHANGELOG.md
23+
├── resources.md ← 软链 → ../../resources.md
24+
├── methods/ ← 软链 → ../../common/ (7 套方法论)
25+
├── workflows-src/ ← 软链 → ../../workflows/ (协作 + 场景)
26+
├── pitfalls-src/ ← 软链 → ../../pitfalls/ (踩坑合集)
27+
└── tools/
28+
├── claude-code/ ← 软链 → ../../../claude-code/
29+
├── codex/ ← 软链 → ../../../codex/
30+
├── cursor/ ← 软链 → ../../../cursor/
31+
└── ...（10 工具全部）
32+
```
33+
34+
**关键设计**：所有内容都是 symlink 而不是复制。仓库主目录改了，重新 `mdbook build` 立刻同步。零内容重复维护。
35+
36+
## 怎么本地预览
37+
38+
```bash
39+
# 一次性装 mdbook
40+
brew install mdbook
41+
# 或 cargo install mdbook
42+
43+
# 预览（实时热更新，浏览器自动打开）
44+
cd book
45+
mdbook serve --open
46+
47+
# 编译成静态 HTML（输出在 book/book/）
48+
mdbook build
49+
```
50+
51+
## 怎么发布
52+
53+
### 选项 1：GitHub Pages（最简单）
54+
55+
加一个 `.github/workflows/book.yml`，push 到 main 时自动 build + 推到 `gh-pages` 分支。
56+
57+
```yaml
58+
name: Build book
59+
on:
60+
push:
61+
branches: [main]
62+
paths: ['book/**', 'common/**', 'workflows/**', 'pitfalls/**',
63+
'*.md', 'cheatsheet.md', 'CHANGELOG.md',
64+
'claude-code/**', 'codex/**', 'cursor/**', 'copilot/**',
65+
'windsurf/**', 'trae/**', 'aider/**', 'gemini-cli/**',
66+
'kiro/**', 'openclaw/**']
67+
68+
jobs:
69+
build:
70+
runs-on: ubuntu-latest
71+
steps:
72+
- uses: actions/checkout@v5
73+
- run: cargo install mdbook
74+
- run: cd book && mdbook build
75+
- uses: peaceiris/actions-gh-pages@v4
76+
with:
77+
github_token: ${{ secrets.GITHUB_TOKEN }}
78+
publish_dir: ./book/book
79+
```
80+
81+
### 选项 2：Netlify / Vercel（PR preview 友好）
82+
83+
仓库根目录加 `netlify.toml`：
84+
85+
```toml
86+
[build]
87+
command = "cd book && mdbook build"
88+
publish = "book/book"
89+
[build.environment]
90+
RUST_VERSION = "1.78"
91+
```
92+
93+
netlify 会自动装 mdbook（用 `cargo install mdbook` build 命令前面手动加一下）。
94+
95+
### 选项 3：Leanpub / GitBook 商业版
96+
97+
如果想出电子书赚钱：mdbook build 出 HTML 之后，用 [pandoc](https://pandoc.org/) 转成 epub / mobi / PDF：
98+
99+
```bash
100+
mdbook build
101+
cd book/book
102+
# 把所有 HTML 串起来转 PDF
103+
pandoc -o ../../ai-coding-guide.pdf $(find . -name "*.html" | sort) \
104+
--pdf-engine=xelatex \
105+
-V mainfont="PingFang SC" -V CJKmainfont="PingFang SC"
106+
```
107+
108+
## 节奏
109+
110+
这是 **v0.1 脚手架**——目录结构、3 卷序、symlink 就位，可以 build 出能看的版本了，但内容主要靠的是仓库里既有的章节。后续要加的：
111+
112+
- [ ] 各卷之间的"过渡章"（卷一末→卷二首的承上启下）
113+
- [ ] 卷三的「CI 集成 / 团队治理」实战章节（仓库里还没有，需要新写）
114+
- [ ] 端到端项目案例（"用 Claude Code + Codex CLI 做完一个真实小项目"）
115+
- [ ] 出版用的封面 / ISBN / 版式（如果要走出版社）
116+
- [ ] PDF 导出脚本调优（中文字体 / 代码块换行）
117+
118+
每一项都可以独立 PR 进来。
119+
120+
## 上游
121+
122+
GitHub: [jnMetaCode/ai-coding-guide](https://github.com/jnMetaCode/ai-coding-guide)

‎book/book.toml‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
[book]
2+
title = "AI 编程实战三卷书"
3+
authors = ["jnMetaCode"]
4+
description = "把 ai-coding-guide 仓库里的 10 工具教程 + 7 套方法论 + 实战工作流，重组为 3 卷 + 1 别册的渐进式读本"
5+
language = "zh-CN"
6+
multilingual = false
7+
src = "src"
8+
9+
[output.html]
10+
default-theme = "light"
11+
preferred-dark-theme = "navy"
12+
git-repository-url = "https://github.com/jnMetaCode/ai-coding-guide"
13+
git-repository-icon = "fa-github"
14+
edit-url-template = "https://github.com/jnMetaCode/ai-coding-guide/edit/main/book/{path}"
15+
site-url = "/"
16+
17+
[output.html.search]
18+
enable = true
19+
limit-results = 30
20+
use-boolean-and = true
21+
boost-title = 2
22+
boost-hierarchy = 1
23+
boost-paragraph = 1
24+
expand = true
25+
heading-split-level = 3
26+
27+
[output.html.fold]
28+
enable = true
29+
level = 1
30+
31+
[output.html.print]
32+
enable = true
33+
page-break = true
34+
35+
[preprocessor.links]
36+
# 默认开，处理 {{#include}}
37+
38+
[preprocessor.index]
39+
# 把 README.md 当作各章首页

‎book/src/SUMMARY.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# 目录
2+
3+
[总序](./intro.md)
4+
5+
---
6+
7+
# 卷一 · 入门：AI 编程从零开始
8+
9+
- [卷一·序](./v1-intro.md)
10+
- [9 工具速查表](./cheatsheet.md)
11+
- [提示词工程](./methods/prompting.md)
12+
- [需求拆解](./methods/task-decomposition.md)
13+
- [上下文管理](./methods/context-management.md)
14+
- 工具速通
15+
- [Cursor — IDE 起步](./tools/cursor/README.md)
16+
- [GitHub Copilot — 行内补全 + Agent](./tools/copilot/README.md)
17+
- [Claude Code — CLI Agent 之王](./tools/claude-code/README.md)
18+
- [OpenAI Codex CLI — 内核沙箱 + ChatGPT 订阅可用](./tools/codex/README.md)
19+
20+
---
21+
22+
# 卷二 · 工作流：实战进阶
23+
24+
- [卷二·序](./v2-intro.md)
25+
- [代码审查](./methods/code-review.md)
26+
- [调试方法论](./methods/debugging.md)
27+
- [测试策略](./methods/testing.md)
28+
- 多工具协作
29+
- [选型指南](./workflows-src/tool-selection.md)
30+
- [实战场景脚本](./workflows-src/scenarios.md)
31+
- [Claude Code + Cursor 协作](./workflows-src/claude-code-cursor.md)
32+
- [Claude Code + Copilot 协作](./workflows-src/claude-code-copilot.md)
33+
- 踩坑合集
34+
- [陷阱总览](./pitfalls-src/README.md)
35+
- [Claude Code 陷阱](./pitfalls-src/claude-code.md)
36+
- [Cursor 陷阱](./pitfalls-src/cursor.md)
37+
- [Copilot 陷阱](./pitfalls-src/copilot.md)
38+
- [Aider 陷阱](./pitfalls-src/aider.md)
39+
- 进阶工具
40+
- [Aider — Git 原生多模型](./tools/aider/README.md)
41+
- [Gemini CLI — 2M 上下文](./tools/gemini-cli/README.md)
42+
- [Windsurf — Cascade 自动上下文](./tools/windsurf/README.md)
43+
- [Trae — 字节出品免费版](./tools/trae/README.md)
44+
- [Kiro — Spec 驱动开发](./tools/kiro/README.md)
45+
46+
---
47+
48+
# 卷三 · 架构：把 AI 编程接进团队
49+
50+
- [卷三·序](./v3-intro.md)
51+
- [安全注意事项](./methods/security.md)
52+
- [OpenClaw — Agent 框架](./tools/openclaw/README.md)
53+
- [延伸学习资源](./resources.md)
54+
55+
---
56+
57+
# 别册 · 速查手册
58+
59+
- [9 工具速查表（同卷一）](./cheatsheet.md)
60+
- [项目更新日志](./changelog.md)
61+
62+
---
63+
64+
[关于本书](./about.md)

‎book/src/about.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# 关于本书
2+
3+
## 为什么有这本书
4+
5+
[ai-coding-guide](https://github.com/jnMetaCode/ai-coding-guide) 仓库到 2026-04 已经积累了：
6+
7+
- 10 款主流 AI 编程工具的中文教程
8+
- 7 套通用方法论（提示词、需求拆解、调试、测试、代码审查、上下文管理、安全）
9+
- 多个端到端实战脚本 + 31 个深度踩坑合集
10+
- 9 工具横向对比速查表
11+
12+
但仓库形态有个问题：**新读者打开 README 看到 50 个链接，不知道从哪读起**。
13+
14+
这本书就是把这堆"各自精彩但散乱"的内容，按读者画像重新编排，给一个**有顺序、有节奏、有起承转合**的阅读路径。
15+
16+
## 内容来源
17+
18+
每一章本质上都是仓库里某个文件的"重新装订"——内容 0 修改，只在卷首加导读、卷末加串联。
19+
20+
| 章节 | 上游文件 |
21+
|------|---------|
22+
| 卷一 各工具速通 | `<tool>/README.md`（如 `claude-code/README.md`） |
23+
| 卷二 方法论 | `common/<topic>.md`（如 `common/debugging.md`） |
24+
| 卷二 踩坑合集 | `pitfalls/<tool>.md` |
25+
| 卷二 协作章节 | `workflows/<combo>.md` |
26+
| 别册速查表 | `cheatsheet.md` |
27+
28+
**好处**：仓库更新 → 书自动更新（用 mdbook 重新 build 即可）。这本书永远跟仓库同步，不会出现"书是 2026 年印的，工具早换代了"的尴尬。
29+
30+
## 怎么本地构建
31+
32+
```bash
33+
# 装 mdbook（一次性）
34+
brew install mdbook # macOS
35+
# 或 cargo install mdbook # 其他平台
36+
37+
# 在仓库根目录
38+
cd book
39+
mdbook serve --open # 实时预览（改 markdown 自动热更新）
40+
mdbook build # 生成静态 HTML 到 book/book/
41+
```
42+
43+
## 反馈渠道
44+
45+
- GitHub Issues：[jnMetaCode/ai-coding-guide/issues](https://github.com/jnMetaCode/ai-coding-guide/issues)
46+
- 微信公众号：**AI不止语**（搜索 `AI_BuZhiYu`）
47+
- QQ 群 / 微信群：见仓库 README
48+
49+
## License
50+
51+
内容遵循 Apache-2.0（与仓库一致）。允许转载、修改、商用，请保留来源。

‎book/src/changelog.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../CHANGELOG.md

‎book/src/cheatsheet.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../cheatsheet.md

‎book/src/intro.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# 总序
2+
3+
> 这套书的最大野心：让你看完之后，再也不用问"这个任务该用哪个 AI 工具"。
4+
5+
## 这套书是什么
6+
7+
这不是 9 本工具说明书，也不是一篇又一篇博客拼起来的合订本。
8+
9+
它是把 [ai-coding-guide](https://github.com/jnMetaCode/ai-coding-guide) 仓库里两年沉淀的 **10 款主流 AI 编程工具教程 + 7 套通用方法论 + 多个端到端实战脚本**，按 **读者画像** 而不是按工具，重新编排成的渐进式读物。
10+
11+
工具会换代，方法论永生。所以这套书的结构是：**先教你方法，再用工具佐证**。
12+
13+
## 三卷分别给谁
14+
15+
| 卷 | 适合谁 | 看完能做什么 |
16+
|---|--------|------------|
17+
| **卷一 · 入门** | AI 编程零基础 / 只用过 Tab 补全 | 从命令行 Agent 到 IDE 集成，4 款主流工具任选其一独立完成日常任务 |
18+
| **卷二 · 工作流** | 已经会用 1-2 款工具，想把效率往上拔 | 多工具组合、Skill / Hook / Subagent 编排、典型场景的端到端剧本 |
19+
| **卷三 · 架构** | 团队 lead / 平台工程师 / CTO | 把 AI 编程接进 CI、安全策略、企业治理；MCP 生态选型 |
20+
21+
**别册** 是一页 `cheatsheet.md`——所有工具关键命令、配置文件、组合方案的横向速查。案头放一份，每天翻两眼。
22+
23+
## 怎么读最高效
24+
25+
- **顺读**：按卷一→卷二→卷三的顺序——是为完全新手设计的
26+
- **挑章读**：每章互相独立，目录里看到顺眼的就跳进去——卷二/卷三尤其如此
27+
- **遇到工具不熟**：随时退回卷一对应章节补课
28+
- **别册当字典**：写代码时遇到"那个命令叫啥来着"，直接搜别册
29+
30+
## 信息源与可信度
31+
32+
每条工具的 CLI flag、配置字段、子命令、模型名都对照过相应仓库的源码（特别是 Codex CLI 那章，6 轮源码核实）。社区博客里常见的过期信息（如 `--full-auto`、`bubblewrap` 等）已修正——任何被否决的"常识"都附了源码出处链接。
33+
34+
工具迭代快，每一版的"信息核实截止日期"在对应章节末尾标注。如果你看的版本距今超过 6 个月，建议先扫一眼 [项目更新日志](./changelog.md) 看有没有 breaking change。
35+
36+
## 上游仓库
37+
38+
GitHub: [jnMetaCode/ai-coding-guide](https://github.com/jnMetaCode/ai-coding-guide) — 欢迎 issue 和 PR。

‎book/src/methods‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../common

‎book/src/pitfalls-src‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../pitfalls

0 commit comments

Comments
 (0)