# HANDOFF · Claude Code 源码分析科普项目（零背景完整交接）

> **给接手的 agent**：你不需要任何先前的对话记录。请先通读本文（约 10 分钟），再按「7. 新电脑一次性搭建」和「8. 日常工作流」行动。
> 写于 2026-08-07，面向“换新电脑 / 完全无项目背景的接手者”。
> 本文**取代**旧版 `handoff.md`（2026-07-24）与 `阶段29-回核交接.md`（2026-08-05，历史归档，保留不删）。

---

## 0. 三分钟版

- **这是什么**：一个中文“AI 编程 Agent 源码分析科普”项目。用户是计算机小白，想看懂 Claude Code、Codex、DeepSeek-Reasonix 等 Agent 是怎么工作的。项目把源码拆成科普文档（全部标注 `文件:行号`），并做成能在浏览器打开的 HTML 讲义站和交互学习站。
- **工作目录**：`/Users/mikayiyanglin/Documents/Github claude-code/claude code源码分析`（**路径里有空格，所有命令必须给路径加引号**）。
- **动任何内容文件之后必做三件事**：
  1. 改了被 `build-html.py` 收录的 Markdown → `python3 build-html.py`；
  2. 任何 `.md`/`.html` 增删改 → `python3 update-catalog.py`；
  3. 提交前确认干净 → `git add -A && git commit`。
- **给用户打开**：双击 `打开总目录.command`，或运行 `./start-html-previews.sh` 后访问 `总目录.html`。
- **硬性红线**：不提交 `node_modules/`、`dist/`、`参考项目/`、`claude-code/`；不手改 `总目录` 的 `AUTO-CATALOG` 区间；不用 7100/7101 端口（Kimi 平台占用）。

---

## 1. 项目是什么 / 用户是谁

### 1.1 项目使命

把“AI 编程 Agent 内部到底怎么工作”讲给非技术背景的人听。做法是：

1. 把上游开源项目浅克隆到 `参考项目/`，逐文件读源码；
2. 产出结构化的源码分析文档（`项目分析/<项目>-源码分析.md`），每个关键技术点标注 `文件:行号`；
3. 配套产出「从零构建 <项目>」开发全流程教程（PRD → 功能模块 → 完整工作流）；
4. 把文档渲染成 HTML 讲义站（统一设计系统），并维护若干可交互实验台（LAB）和 Vite 学习站；
5. 用 `总目录.html` / `html-hub.html` 作为统一检索入口，自动记录“最近更新”。

### 1.2 用户画像与偏好

- 中文用户，计算机基础较弱，最终交付消息要**大白话**，少堆术语；
- 喜欢“打开即看”的 HTML，优先交付 HTML 版本；
- 明确要求过：总目录入口固定、每次更新自动出现在总目录；页面风格参考课程讲义（白底、浅色、有设计感但不怪异的字体）；中文可读性优先；
- 习惯每次任务后提交 git，要求工作区干净；
- 历史上曾禁止使用子代理/深研类功能（见 `阶段29-回核交接.md` 的会话级约束），**不要默认开子代理**，除非用户明确要求。

---

## 2. 仓库现状快照（2026-08-07）

| 项目 | 状态 |
|---|---|
| git 分支 | `main`，无远程 remote，未推送任何地方 |
| 最新提交 | `1823dff style: 升级全站字体系统，改用可变字体排版阶梯` |
| 工作区 | 干净 |
| 跟踪文件 | 503 个 |
| 根目录 `.md` | 27 个 |
| 根目录 `.html` | 24 个 |
| `项目分析/` | 31 个 .md + 6 个 .html（见 §4） |
| `调查报告/` | 3 份 Claude Code 盘点素材 |
| Vite 学习站 | 4 个被 `start-html-previews.sh` 托管 + 1 个休眠站（`mimo-code-learn`） |
| 本地预览 | 当前已在运行：7200 / 7300 / 7301 / 7397 / 7400（127.0.0.1） |
| Python | 3.14.3，`markdown` 3.10.2 已装（`build-html.py` 依赖） |

---

## 3. 目录地图

```
claude code源码分析/
├── AGENTS.md                     # ⭐ 项目协作规则（每次动工前必读）
├── CHANGELOG.md                  # ⭐ 全项目阶段日志（始终最新，新工作要追加）
├── 总目录.md / 总目录.html        # ⭐ 检索台：手维护正式分区 + 自动「最近更新」区
├── html-hub.html                 # ⭐ 学习站总入口（手维护）
├── md-view.html                  # Markdown 在线渲染器（?doc= 参数）
├── build-html.py                 # ⭐ MD → HTML 讲义生成器（17 个文档在 CONFIG）
├── update-catalog.py             # ⭐ 总目录自动更新器（必跑）
├── start-html-previews.sh        # 一键启动全部预览（4 个 Vite 站 + 静态 7400）
├── 打开总目录.command             # 用户双击入口：刷新目录→起服务→开浏览器
├── assets/
│   ├── lecture-site.css          # ⭐ 全站统一设计系统（核心）
│   ├── marked.min.js             # md-view.html 用的本地 Markdown 渲染器
│   ├── mermaid.min.js            # md-view.html 用的本地 mermaid
│   └── *-site.js                 # 各手写解析站的交互脚本（见 §5.9）
├── Claude-Code-工作原理科普*.md   # 主线科普（深入版为旗舰文档）
├── 调查报告/                     # Claude Code 工具/组件/命令盘点素材
├── 项目分析/                     # ⭐ 20+ 份源码分析（标注 文件:行号）
├── 从零构建*-开发全流程教程.md     # ⭐ 一套 PRD→模块→工作流的构建教程
├── *-解析.html                   # 手写/生成的 HTML 讲义站（含交互 LAB）
├── claude-code-learn/            # Vite 站 v1（:7300，苹果官网风）
├── claude-code-learn-v2/         # Vite 站 v2（:7301，蓝皮书风）
├── openmanus-suna-learn/         # Vite 站（:7200，含 build-guide.html）
├── build-an-agent-guide/         # Vite 站（:7397，从零构建编程助手指南）
├── mimo-code-learn/              # 休眠 Vite 站（有源码，无 dist，未接入预览）
├── 参考项目/                     # ⭐ 20 个上游源码浅克隆（只读、不提交）
├── claude-code/                  # Claude Code 上游源码镜像（只读、不提交）
├── 资料归档/                     # 参考材料（beyond-answers 等，已跟踪）
├── beyond-answers-part1/         # 引用资料本地库（PDF/网页镜像）
├── .workbuddy/                   # 自动目录状态 + 校验脚本 + 项目长期记忆
│   ├── catalog-state.json        # update-catalog 的状态（签名/事件）
│   ├── memory/MEMORY.md          # ⭐ 分析流程约定（多项目复用经验）
│   └── verify_*.py               # 引用/行数/命名校验脚本
├── 阶段29-回核交接.md             # 旧交接（历史归档）
├── 全量审查汇总报告.md            # 阶段 20 的 22 份文档审查（约 73 条错误）
├── 架构图*.md / 架构图库.html     # 架构图方法论与图库
└── 文档与站点索引.md              # ⭐ 已冻结的快照（阶段 17），以总目录为准
```

### 3.1 参考项目（20 个上游克隆，只读）

`CodeWhale` `DeepSeek-Reasonix` `MiMo-Code` `MiroFish` `OpenAI4S` `OpenManus` `Raven` `cline` `codepilot` `codex`（OpenAI Codex）`codexmonitor` `goose` `hermes-agent` `kanban` `nanobot` `open-design` `opencode` `openworker`（coworker 底座）`pi` `suna`（Kortix）

- 用途：作为 `文件:行号` 引用的核对源；`.workbuddy/verify_*.py` 直接扫这些目录。
- 都是浅克隆，**不要改**；改动也不进 git（`.gitignore` 已排除）。
- 每份分析文档头部都固定了分析对象的 commit/版本。

---

## 4. 产物体系

### 4.1 Markdown 文档族

| 类型 | 位置 | 说明 |
|---|---|---|
| 主线科普 | `Claude-Code-工作原理科普-深入版.md`（旗舰，14 章 36 图）、`Claude-Code-工作原理科普.md`（初版存档） | Claude Code 内部原理 |
| 单项目源码分析 | `项目分析/<项目>-源码分析.md`（20+ 份） | 统一框架（约 12~15 章）+ 横向对比 + 源码指路表；全部 `文件:行号` |
| 从零构建教程 | 根目录 `从零构建<项目>-开发全流程教程.md` | PRD → 20+ 功能模块（目的/实现/技术栈/取舍/优劣/配合）→ 完整工作流 |
| 横向/方法论文档 | `项目分析/横向对比与总结评价.md`、`Agent工程模式目录.md`、`按水平分级的阅读路线.md`、`Agent评测与基准测试.md`、`后续待剖析的开源项目推荐列表.md`、`项目分析/Claude-Code-vs-OpenCode-vs-Codex-深度对比.md` 等 | 跨项目提炼 |
| 调查报告 | `调查报告/01-工具盘点.md` `02-核心功能组件盘点.md` `03-斜杠命令盘点.md` | Claude Code 盘点素材 |

### 4.2 静态 HTML（统一 lecture-site.css）

**A. 由 `build-html.py` 生成（16 个，改 MD 后要重跑）**：

`Agent工程模式目录.html`、`按水平分级的阅读路线.html`、`Agent评测与基准测试.html`、`后续待剖析的开源项目推荐列表.html`、`CodePilot-解析.html`、`从零构建CodePilot-开发全流程教程.html`、`OpenWorker-企业级开发方案.html`、`OpenAI4S-解析.html`、`从零构建OpenAI4S-开发全流程教程.html`、`项目分析/cline-源码分析.html`、`项目分析/kanban-源码分析.html`、`项目分析/codexmonitor-源码分析.html`、`项目分析/openai-codex-源码分析.html`、`项目分析/DeepSeek-Reasonix-源码分析.html`、`从零构建Cline-开发全流程教程.html`、`从零构建Kanban-开发全流程教程.html`

**B. 手写精修解析站（含交互 LAB，改它们要同时改对应 `assets/*-site.js`）**：

`open-design-解析.html`（4 LAB）、`MiMo-Code-解析.html`（5 LAB）、`MiroFish-解析.html`（5 LAB）、`openai-codex-解析.html`（5 LAB）、`Pi-解析.html`（5 LAB，生成器会跳过 pi）、`beyond-answers-part1.html`、`架构图库.html`、`从零构建通用任务Agent-Manus系-开发全流程教程.html`、`build-claude-code.html`、`从零构建AI设计Agent-OpenDesign系-开发全流程教程.html`

**C. 工具页**：`总目录.html`（自动+手维护）、`html-hub.html`（手维护）、`md-view.html`（渲染器）。

### 4.3 Vite 学习站（React + TS + Vite + Tailwind + shadcn/ui）

| 目录 | 端口 | 内容 |
|---|---|---|
| `claude-code-learn/` | 7300 | Claude Code 学习站 v1（苹果官网风），含 8+ Agent 大观园、ToolAtlas、CommandAtlas |
| `claude-code-learn-v2/` | 7301 | 同内容蓝皮书重排版（18 CHAPTERS / 6 PARTS） |
| `openmanus-suna-learn/` | 7200 | OpenManus × Suna 学习站 + `build-guide.html` |
| `build-an-agent-guide/` | 7397 | 从零构建 AI 编程助手 · 指南站（知识树 + 术语图谱） |
| `mimo-code-learn/` | 未接入 | 早期 OpenManus×Suna 源码站，**休眠**：有源码、无 dist/node_modules、不在启动脚本里；不要删，用户没要求不要动 |

每个站的数据与 UI 分离：`src/content/*.ts`（projects.ts / comparison.ts / verdict.ts / chapters.ts / glossary.ts / build.ts…）+ `src/sections/*.tsx` + `src/components/ProjectDiagrams.tsx`。

---

## 5. 功能与调用清单（“调用了哪些功能”）

### 5.1 `update-catalog.py` —— 总目录自动更新（每次内容变更必跑）

```bash
python3 update-catalog.py
```

- 扫描范围：根目录 `*.md`/`*.html`、`项目分析/*.md`/`*.html`、`调查报告/*.md`。
- 排除：`AGENTS.md`、`总目录.md/.html`、`html-hub.html`、`md-view.html`、`update-catalog.py` 自身。
- 状态文件：`.workbuddy/catalog-state.json`，用 `mtime_ns:size` 签名判断“新增/更新/删除”；事件保留最近 200 条，目录里展示最近 20 条。
- 重写 `总目录.html` / `总目录.md` 中 `<!-- AUTO-CATALOG:START -->` ~ `<!-- AUTO-CATALOG:END -->` 之间的内容；**该区间禁止手改**。
- 首次运行（状态文件不存在）只播种存量、不产生“新增”事件。⚠️ 新电脑首次运行有洪水风险，见 §12。

### 5.2 `build-html.py` —— MD → 讲义 HTML 生成器

```bash
python3 build-html.py                 # 重建 CONFIG 里全部 17 个文档
python3 build-html.py 项目分析/foo-源码分析.md   # 只重建某一个
```

- 依赖：`pip install markdown`（Python-Markdown，本地 3.10.2）。
- **`ROOT` 是硬编码绝对路径（文件第 12 行）**，换电脑路径不同必须改，否则写错位置。
- `CONFIG` 目前收录 17 个文档，每个有 title/description/nav_title/eyebrow/h1/dek/stats 等元数据。
- 输出名特殊映射 `ROOT_OUT`：`项目分析/codepilot-源码分析.md → CodePilot-解析.html`、`OpenAI4S-源码分析.md → OpenAI4S-解析.html` 等；其余 `.md → .html` 同路径。
- 主题路由：`HERMES_THEME`（当前空集）；`CLAUDE_BLOG_THEME`（当前只有 `项目分析/DeepSeek-Reasonix-源码分析.md`，走 `build_claude_blog_html()`）；默认走 `build_html()`。**两个主题现在都引用 `assets/lecture-site.css`**，视觉已统一。
- `项目分析/pi-源码分析.md` 被**跳过**（Pi-解析.html 是手写精修版，勿被生成器覆盖）。
- 生成逻辑：Markdown → tables/fenced_code 扩展 → 去掉第一个 H1 → mermaid 代码块转 `<pre class="mermaid">` → h2/h3 加锚点 id → 自动建左侧 TOC + 顶部导航 → 按 H2/H3 包成 `.part`/`.section.ch` → 注入滚动进度条/滚动淡入/scroll-spy/回到顶部 → mermaid 走 jsdelivr CDN（**需要网络**）。
- 输出路径 CSS 前缀：`项目分析/` 下的页面用 `../assets/...`，根目录用 `./assets/...`。

### 5.3 `start-html-previews.sh` —— 一键启动全部预览

```bash
./start-html-previews.sh
```

- 先跑一次 `update-catalog.py`，确保总目录最新。
- `free_port()` 会**杀掉**目标端口上的旧进程再启动，逻辑上安全（只杀本机 127.0.0.1 监听），但不要在别人正在用时乱跑。
- 启动：`openmanus-suna-learn:7200`、`claude-code-learn:7300`、`claude-code-learn-v2:7301`、`build-an-agent-guide:7397` 用 `npx --yes vite preview`（**要求该站已有 `dist/`**），静态页用 `python3 -m http.server 7400 --bind 127.0.0.1`。
- 日志在 `${TMPDIR}/claude-code-html-previews/*.log`。
- 脚本会给 PATH 前置 `~/.hermes/node/bin`、`~/.local/bin`、`~/.bun/bin` 等。
- 只绑 127.0.0.1；**提示用户用 127.0.0.1 而不是 localhost**。

### 5.4 `打开总目录.command` —— 用户双击入口

```bash
./打开总目录.command
```

刷新总目录 → 启动预览 → `open 总目录.html`。关闭终端窗口不影响已启动的服务。

### 5.5 `md-view.html` —— Markdown 在线渲染器

- 用法：`md-view.html?doc=项目分析/DeepSeek-Reasonix-源码分析.md`（相对仓库根路径）。
- 功能：`fetch` 读 MD → `assets/marked.min.js` 渲染 → 本地 `assets/mermaid.min.js` 画图 → 自动 TOC、滚动进度条、高亮当前章节、表格横向滚动、标题锚点。
- 生成页侧栏的“阅读 Markdown 原文 ↗”就是链到这里。

### 5.6 `html-hub.html` —— 学习站总入口（手维护）

- 分区：交互学习站 / 架构图库 / 源码解析讲义 / 学习指南 / 独立静态；顶部有实时搜索（按卡片 `data-k` 过滤）。
- 新增页面时**手工**在对应分区加卡片（标题 + 端口 + 一句话描述 + data-k 关键词）。

### 5.7 `.workbuddy/` 校验脚本（质量闸门）

```bash
python3 .workbuddy/verify_citations.py <文档> <参考项目目录名>       # 校验 文件:行号 引用
python3 .workbuddy/verify_linecounts.py <文档> <repo1,repo2>          # 校验 “xxx（N 行）” 行数声明
python3 .workbuddy/verify_names.py <文档> <repo1,repo2> [paths|identifiers]  # 校验反引号路径/标识符存在
```

都基于 `参考项目/` 的目录索引做存在性与行号核对。分析类文档交付前至少跑 `verify_citations.py`，把 `[WRONG]`/`[PARTIAL]` 清掉或改正。

### 5.8 Vite 站 npm 功能

```bash
cd <站点目录>
npm ci              # 全新环境按 package-lock 精确装依赖
npm run build       # tsc -b && vite build，产出 dist/
npm run dev -- --port <port>   # 开发预览
npm run preview     # 预览 dist/（start-html-previews.sh 用的就是这个）
```

### 5.9 手写解析站的交互脚本（`assets/*-site.js`）

| 脚本 | 页面 |
|---|---|
| `codex-site.js` | `openai-codex-解析.html`（审批×沙箱正交表、预算模拟器等 5 LAB） |
| `mimo-site.js` | `MiMo-Code-解析.html`（Goal 裁判、四道闸门、提示词路由器、归属核对台） |
| `mf-site.js` | `MiroFish-解析.html`（归一化流水线、作息曲线、双世界对照台） |
| `gallery-site.js` | `架构图库.html`（全屏看图） |
| `od-site.js` | `open-design-解析.html`、`beyond-answers-part1.html` |
| `od-build.js` | `从零构建AI设计Agent-OpenDesign系-开发全流程教程.html`（装配进度/验收断言） |
| `pi-site.js` | `Pi-解析.html`（双层 while、租约、TUI diff 等 5 LAB） |
| `codepilot-site.js` | ⚠️ 当前没有任何页面引用（历史遗留，勿删即可） |

---

## 6. 设计系统（改视觉必须延续）

统一入口：`assets/lecture-site.css`（2026-08-06 全面重写，参考 `ai.richardxu.com/ml` 课程讲义风格 + 用户字体审美要求）。

- 底色白、正文 `--ink` 深墨、主强调色靛蓝 `--accent` + teal `--teal` 渐变光晕；浅灰面板、细分割线。
- 字体（Google Fonts `@import`，**需网络**）：
  - `Inter` 可变字体（`opsz,wght@14..32,100..900`）；
  - `Inter Tight` 作显示字体（标题 900/850、紧字距、`text-wrap: balance`）；
  - `JetBrains Mono` 作等宽（统计数字、眉题、代码），数字 `tabular-nums`；
  - 正文 450 字重、行高 1.78、`text-wrap: pretty`；眉题/标签 800 + 0.2~0.24em 字距。
- 组件词汇：`.nav/.hero/.shell/.toc/.article/.part/.section.ch/.stats/.card/.gcard/.lab-hd/.layers/.finding/.argv/.acc-hd/.ck` 等；引用块用靛蓝→teal 渐变边条；代码块深色 `#0f172a` 底。
- 所有静态 HTML（27 个）现在都引用 `lecture-site.css`；`assets/od-site.css` 是旧系统，仅少数手写页内联样式/遗留引用，不要再扩散。
- 用户审美约束：中文可读性优先；字体要有艺术感但不能造型奇特影响阅读；白底浅色。

---

## 7. 新电脑一次性搭建（换机清单）

1. **Python 3**（3.12+）：`python3 --version`；装 Markdown 生成器依赖：
   ```bash
   python3 -m pip install markdown
   ```
2. **Node.js 20+ / npm**：`node -v`。`start-html-previews.sh` 会找 `~/.hermes/node/bin`，若不在就把它加进 PATH，或系统装 Node。
3. **拿到仓库**：`git clone`（本机没有 remote，需从旧电脑整体拷贝目录，含 `.git/`）或直接拷贝整个文件夹。
4. **修正硬编码路径**：若新电脑目录不是 `/Users/<用户名>/Documents/Github claude-code/claude code源码分析`，必须改 `build-html.py` 第 12 行 `ROOT`。`update-catalog.py` / `start-html-previews.sh` / `打开总目录.command` 用脚本自身位置定位，无需改。
5. **重建四个 Vite 站**（`dist/` 和 `node_modules/` 不进 git，全新环境必须重建）：
   ```bash
   for d in claude-code-learn claude-code-learn-v2 openmanus-suna-learn build-an-agent-guide; do
     (cd "$d" && npm ci && npm run build)
   done
   ```
6. **启动预览**：`./start-html-previews.sh`，然后：
   ```bash
   curl -s -o /dev/null -w '%{http_code}\n' html-hub.html   # 期望 200
   curl -s -o /dev/null -w '%{http_code}\n' learn/claude-v1/                # 期望 200
   ```
7. **验证生成链路**：`python3 build-html.py` 应全部成功（会打印每个文件字节数）。
8. **处理总目录状态文件**（重要，见 §12 洪水问题）：新机器第一次跑 `update-catalog.py` 前，先删掉 `.workbuddy/catalog-state.json` 让它重新播种，避免所有文件被记成“更新”刷屏。

---

## 8. 日常工作流（每轮任务的标准步骤）

1. 读 `AGENTS.md`、`CHANGELOG.md` 尾部、相关文档，先搞清楚用户要什么；
2. 改内容（MD / HTML / Vite 源码）；
3. 若改了 `build-html.py` 收录的 MD → `python3 build-html.py`（含新增 CONFIG 条目）；
4. 若新增内容应在总目录正式分区出现 → 按现有卡片格式手补 `总目录.md/.html` 对应分区（自动区只负责“被发现了”，正式卡片负责“好找”）；新页面也要补 `html-hub.html` 卡片；
5. `python3 update-catalog.py`；
6. 在 `CHANGELOG.md` 追加阶段条目（日期 + 阶段号 + Added/Changed + Verified），并按需更新文末“产物总览”表；
7. `git status` 检查（不该出现 node_modules/dist/参考项目/claude-code），`git add -A && git commit`，提交信息用 `feat:`/`docs:`/`style:` 等前缀 + 中文描述；
8. 给用户大白话汇报（HTML 优先交付，附绝对路径和 127.0.0.1 链接）。

---

## 9. 新增一个项目分析的标准流程（沿用 20+ 次的经验）

详见 `.workbuddy/memory/MEMORY.md`，要点：

1. **先确认目标**：用户口述简称可能指别的仓库，先 `ls 参考项目/` 比对真实目录，必要时问用户。
2. **取源码**：优先 `git clone --depth 1`；大仓库用 `git sparse-checkout + blob:none`（cline 16 秒/27MB 成功）；中小仓库直接浅克隆。
3. **分析**：产出 `项目分析/<项目>-源码分析.md`（约 15 章 + 横向对比 + 🔍 源码指路表；头部写明对象/规模/一句话定位；关键结论标注 `文件:行号` 并固定 commit）。
4. **配套教程**：产出 `从零构建<项目>-开发全流程教程.md`（PRD → 功能模块：目的/实现/技术栈/取舍/优劣/配合/验收 → 完整工作流详解）。
5. **HTML 生成闭环（易漏，重点检查）**：把两份 MD 加进 `build-html.py` 的 `CONFIG`，跑生成器，确认 HTML 真实生成（grep 文件名 + curl HTTP 200）。历史上 OpenAI4S 与 Codex 曾漏生成 HTML。
6. **交叉核验**：用 `.workbuddy/verify_citations.py` 等清掉 WRONG/PARTIAL；注意 `参考项目/` 与 `claude-code/` 里同名副本同步问题（根目录与 `项目分析/` 同名 MD 副本要一致）。
7. **收尾**：CHANGELOG 加阶段条目（含关键发现/Verified）+ 产物总览表两行；`update-catalog.py`；提交；交付 HTML。

---

## 10. 内容质量底线

- 所有技术陈述以 `参考项目/` 真实源码为准，**不要自己发明**；标注 `文件:行号` 可追溯。
- 分析文档结构统一（约 12~15 章 + 横向对比 + 源码指路表），头部固定分析对象/规模/commit。
- 行数/路径/标识符声明必须能通过 `.workbuddy/verify_*.py`。
- 跨项目对比（横向对比与总结评价）事实以各分析 MD 为准。
- 交付前必须自己跑验证（build、HTTP 200、grep 关键词、标签配平），不能写完就交。

---

## 11. 用户偏好与交付习惯

- 最终回复用中文大白话，不堆术语、不展示中间命令细节（用户会看到工具调用，但回复要翻译成人话）。
- 交付 HTML 优先：给出**绝对路径** + `...` 链接。
- 每次更新后让总目录自动记录；定期 commit；不要留后台进程（`start-html-previews.sh` 是用户环境的一部分，例外）。
- 用户对风格有明确审美要求：讲义感、白底浅色、艺术但不怪异的字体、中文优先。

---

## 12. 已知坑与注意事项

1. **路径有空格**：所有命令引用根目录必须加引号；shell 变量赋值也要带引号。
2. **`build-html.py` 的 `ROOT` 硬编码**：换电脑/换用户名必改。
3. **总目录自动区禁止手改**：只改正式分区；自动区由脚本覆盖。
4. **新电脑 catalog 洪水**：仓库里的 `.workbuddy/catalog-state.json` 记录的是旧机器 mtime，克隆后所有文件 mtime 变化，首次 `update-catalog.py` 会把所有文件标成“更新”。解决：新机器首次运行前删除该 json 重新播种。
5. **Vite 站 dist 不进 git**：全新环境不 `npm ci && npm run build`，预览全 404。
6. **端口**：7400 静态 / 7200/7300/7301/7397 Vite；**7100/7101 是 Kimi 平台占用，不要碰**；服务只绑 127.0.0.1，提示用户别用 localhost。
7. **mermaid 双源**：`build-html.py` 生成页走 jsdelivr CDN（断网会空白），`md-view.html` 用本地 `assets/mermaid.min.js`。
8. **生成器会跳过 pi**：`项目分析/pi-源码分析.md` 不会生成 HTML，`Pi-解析.html` 是手写精修版，别被“重建全部”覆盖。
9. **不要提交**：`node_modules/`、`dist/`、`参考项目/`、`claude-code/`、`*.git.bak/`（已在 .gitignore）。
10. **休眠站 mimo-code-learn**：有源码无 dist，不在启动脚本，别误以为坏了。
11. **macOS 没有 `timeout` 命令**：需要时用 `gtimeout` 或直接跑。
12. **网络代理**：历史上有过 HTTP_PROXY 502 / git early EOF，clone 失败时先检查代理。

---

## 13. 常见排查

| 症状 | 排查 |
|---|---|
| 总目录没出现刚改的文件 | 跑 `python3 update-catalog.py`；看 `.workbuddy/catalog-state.json` 的 files 是否更新签名 |
| 生成页样式错乱/链接 404 | 检查 `css_prefix`：`项目分析/` 下必须 `../assets/`；确认生成器 ROOT 路径正确 |
| Vite 站 404 | `cd 站点 && npm run build`，确认 dist 存在 |
| mermaid 不渲染 | 生成页需要外网；md-view 用本地库 |
| 端口被占 | `lsof -iTCP:<port> -sTCP:LISTEN` 看进程；7100/7101 不要动 |
| HTML 标签不配平 | 生成页可数 `div` 开闭；手写页检查手改部分 |
| 引用行号对不上 | `python3 .workbuddy/verify_citations.py <doc> <repo>` |

---

## 14. 项目历史（两分钟版）

1. 阶段 1–4（07-23）：Claude Code 源码科普起步 → 深入版 14 章 → 网站 v1/v2 → 工具/命令/生态四大板块；
2. 阶段 5–17（07-24~31）：五大开源 Agent 分析 → 两站大观园整合 → nanobot/grok-build → OpenManus×Suna 学习站 → Open Design / MiMo Code / MiroFish / OpenAI Codex 专线与交互解析站 → 架构图库 → 工程模式目录/阅读路线/评测/推荐列表；
3. 阶段 18–22（07-31）：CodePilot / Pi 专线；
4. 阶段 23–28（08-03~04）：OpenWorker 企业方案、Cline、Kanban、CodexMonitor、OpenAI4S 专线 + 交叉核验；
5. 阶段 29–30（08-05）：近三日全量回核纠错；总目录固定入口 + 自动更新机制；
6. 阶段 31–34（08-05）：Kanban/CodexMonitor Hermes 风格 → DeepSeek-Reasonix 动机驱动重写 + HTML 版（Claude blog 版式）；
7. 阶段 35（08-06）：全站 UI 统一为 richardxu 课程讲义风格（lecture-site.css）+ 可变字体排版阶梯（提交 95148f2 / 1823dff）；
8. 阶段 36（08-07）：本交接文档全面重写（换新电脑/零背景可上手）。

祝顺利。有任何不清楚的地方，先读 `AGENTS.md`、`.workbuddy/memory/MEMORY.md` 和 `CHANGELOG.md` 尾部。