jnMetaCode · jnMetaCode · Sep 28, 2026 · Sep 28, 2026
diff --git a/book/src/about.md b/book/src/about.md
@@ -7,7 +7,7 @@
 - 10 款主流 AI 编程工具的中文教程
 - 7 套通用方法论（提示词、需求拆解、调试、测试、代码审查、上下文管理、安全）
 - 多个端到端实战脚本 + 31 个深度踩坑合集
-- 9 工具横向对比速查表
+- 10 款工具横向对比速查表
 
 但仓库形态有个问题：**新读者打开 README 看到 50 个链接，不知道从哪读起**。
 

diff --git a/book/src/intro.md b/book/src/intro.md
@@ -21,7 +21,7 @@
 
 ## 这套书是什么
 
-这不是 9 本工具说明书，也不是一篇又一篇博客拼起来的合订本。
+这不是 10 本工具说明书，也不是一篇又一篇博客拼起来的合订本。
 
 它是把 [ai-coding-guide](https://github.com/jnMetaCode/ai-coding-guide) 仓库里两年沉淀的 **10 款主流 AI 编程工具教程 + 7 套通用方法论 + 多个端到端实战脚本**，按 **读者画像** 而不是按工具，重新编排成的渐进式读物。
 
@@ -46,7 +46,7 @@
 
 ## 信息源与可信度
 
-每条工具的 CLI flag、配置字段、子命令、模型名都对照过相应仓库的源码（特别是 Codex CLI 那章，6 轮源码核实）。社区博客里常见的过期信息（如 `--full-auto`、`bubblewrap` 等）已修正——任何被否决的"常识"都附了源码出处链接。
+每条工具的 CLI flag、配置字段、子命令、模型名都对照过相应仓库的源码（特别是 Codex CLI 那章，6 轮源码核实）。社区博客里常见的过期信息（如 `--full-auto`、退役模型 ID 等）已修正——任何被否决的"常识"都附了源码出处链接。
 
 工具迭代快，每一版的"信息核实截止日期"在对应章节末尾标注。如果你看的版本距今超过 6 个月，建议先扫一眼 [项目更新日志](./changelog.md) 看有没有 breaking change。
 

diff --git a/book/src/v2-intro.md b/book/src/v2-intro.md
@@ -18,7 +18,7 @@
    ↓
 踩坑合集（4 款主流工具的 31 个深度陷阱）
    ↓
-进阶工具（Aider / Gemini CLI / Windsurf / Trae / Kiro）
+进阶工具（Aider / Gemini CLI / Devin Desktop（原 Windsurf）/ Trae / Kiro）
 ```
 
 学完这一卷你应该能：
@@ -27,7 +27,7 @@
 - 用 AI 做端到端调试：从复现 → 定位 → 修复 → 写防回归测试，一条龙
 - 设计 Claude Code + Cursor 这种双工具流水线，明确各自职责边界
 - 看到典型陷阱描述就能心里咯噔一下（"这个我也遇到过"）并知道怎么躲
-- 在小众但有特定优势的工具（如 Gemini CLI 的 2M 上下文）上做出选择
+- 在小众但有特定优势的工具（如 Kiro 的 Spec 驱动、Aider 的多模型切换）上做出选择
 
 ## 这一卷的"必读"
 

diff --git a/common/context-management.en.md b/common/context-management.en.md
@@ -12,10 +12,10 @@ Every AI coding tool has a **context window** — think of it as the AI's "worki
 
 | Tool | Context Window | Notes |
 |---|---|---|
-| Claude Code | 200K tokens | ~150K words, largest among coding tools |
-| Cursor | 128K-200K tokens | Depends on the selected model |
-| Copilot | 128K tokens | Includes open files |
-| Gemini CLI | 1M-2M tokens | Largest window, but bigger isn't always better |
+| Claude Code | 1M tokens | Opus/Sonnet 5.5 both 1M (Haiku 200K) |
+| Cursor | per model | Depends on the selected model |
+| Copilot | per model | Depends on the selected model; includes open files |
+| Gemini CLI | 1M tokens | Large window, but bigger isn't always better (no longer serves individual users — enterprise / paid API keys only) |
 
 **Key insight**: More context is not always better. Stuffing in irrelevant information causes "attention dilution" — important details get buried.
 
@@ -39,9 +39,9 @@ Every tool has a project config file that loads automatically at startup:
 | Tool | Config File | Purpose |
 |---|---|---|
 | Claude Code | `CLAUDE.md` | Project background, conventions, common commands |
-| Cursor | `.cursorrules` / `.cursor/rules/` | Project rules |
+| Cursor | `.cursor/rules/*.mdc` | Project rules (`.cursorrules` is legacy) |
 | Copilot | `.github/copilot-instructions.md` | Project guidelines |
-| Windsurf | `.windsurfrules` | Project rules |
+| Devin Desktop (formerly Windsurf) | `.devin/rules/*.md` | Project rules (`.windsurfrules` kept only for backward compatibility) |
 | Gemini CLI | `GEMINI.md` | Project config |
 
 **A well-written config file = the most critical context automatically included in every conversation.**
@@ -90,7 +90,7 @@ The longer a conversation runs, the less weight earlier messages carry. When AI
 @src/models/user.ts @src/schemas/user.ts
 Write a user registration endpoint based on these two files
 
-# Use Notepads to save frequently used context
+# Use Rules / Skills to save frequently used context (Notepads were removed in 2.0)
 # Use Rules globs to auto-load rules by file type
 
 # Open related files as implicit context

diff --git a/common/context-management.md b/common/context-management.md
@@ -10,10 +10,10 @@
 
 | 工具 | 上下文窗口 | 说明 |
 |------|-----------|------|
-| Claude Code | 200K tokens | 约 15 万字，最大 |
-| Cursor | 128K-200K tokens | 取决于选择的模型 |
-| Copilot | 128K tokens | 包含打开的文件 |
-| Gemini CLI | 1M-2M tokens | 窗口最大，但太大也有问题 |
+| Claude Code | 1M tokens | Opus/Sonnet 5.5 均为 1M（Haiku 200K） |
+| Cursor | 跟模型 | 取决于选择的模型 |
+| Copilot | 跟模型 | 取决于选择的模型，包含打开的文件 |
+| Gemini CLI | 1M tokens | 窗口大，但太大也有问题（个人用户已停服，仅企业版 / 付费 API Key） |
 
 **关键认知**：上下文不是越大越好。塞太多无关信息，AI 会"注意力分散"，重要信息反而被淹没。
 
@@ -37,9 +37,9 @@
 | 工具 | 配置文件 | 作用 |
 |------|---------|------|
 | Claude Code | `CLAUDE.md` | 项目背景、规范、常用命令 |
-| Cursor | `.cursorrules` / `.cursor/rules/` | 项目规则 |
+| Cursor | `.cursor/rules/*.mdc` | 项目规则（`.cursorrules` 为旧格式） |
 | Copilot | `.github/copilot-instructions.md` | 项目指引 |
-| Windsurf | `.windsurfrules` | 项目规则 |
+| Devin Desktop（原 Windsurf） | `.devin/rules/*.md` | 项目规则（`.windsurfrules` 仅向后兼容） |
 | Gemini CLI | `GEMINI.md` | 项目配置 |
 
 **写好配置文件 = 每次对话自动带上最关键的上下文。**
@@ -88,7 +88,7 @@
 @src/models/user.ts @src/schemas/user.ts
 基于这两个文件写一个用户注册接口
 
-# 用 Notepads 保存常用上下文
+# 用 Rules / Skills 保存常用上下文（Notepads 已在 2.0 移除）
 # 用 Rules globs 按文件类型自动加载规则
 
 # 打开相关文件作为隐式上下文

diff --git a/common/security.en.md b/common/security.en.md
@@ -25,7 +25,7 @@ const DB_URL = process.env.DATABASE_URL
 **Mitigation**: Explicitly prohibit this in your project rules:
 
 ```markdown
-# CLAUDE.md / .cursorrules
+# CLAUDE.md / .cursor/rules/*.mdc
 Never hardcode secrets, passwords, or tokens in source code.
 All sensitive configuration must be read from environment variables.
 ```
@@ -79,7 +79,7 @@ console.log('Payment response:', { id: response.id, status: response.status })
 Add these rules to your project config file:
 
 ```markdown
-# Security Rules (for CLAUDE.md / .cursorrules / .windsurfrules)
+# Security Rules (for CLAUDE.md / .cursor/rules/*.mdc / .devin/rules/*.md)
 
 ## Never
 - Hardcode secrets, passwords, or tokens

diff --git a/common/security.md b/common/security.md
@@ -23,7 +23,7 @@ const DB_URL = process.env.DATABASE_URL
 **防护**：在项目规则里明确禁止：
 
 ```markdown
-# CLAUDE.md / .cursorrules
+# CLAUDE.md / .cursor/rules/*.mdc
 禁止在代码中硬编码任何密钥、密码、token。
 所有敏感配置必须通过环境变量读取。
 ```
@@ -77,7 +77,7 @@ console.log('Payment response:', { id: response.id, status: response.status })
 在项目配置文件中加入这些规则：
 
 ```markdown
-# 安全规则（加到 CLAUDE.md / .cursorrules / .windsurfrules）
+# 安全规则（加到 CLAUDE.md / .cursor/rules/*.mdc / .devin/rules/*.md）
 
 ## 禁止
 - 不要硬编码密钥、密码、token

diff --git a/pitfalls/README.en.md b/pitfalls/README.en.md
@@ -13,15 +13,15 @@
 | Tool | # of pitfalls | Topics |
 |------|--------------|--------|
 | [Claude Code](./claude-code.en.md) | 8 | Context overflow / hallucinated APIs / over-refactoring / fake verification / CLAUDE.md ignored / git amend / plan drift / subagent context |
-| [Cursor](./cursor.en.md) | 8 | Composer rogue / Tab blast / .cursorrules too long / @file silent fail / mode confusion / model switching / stale Notepads / stale index |
-| [GitHub Copilot](./copilot.en.md) | 8 | Outdated APIs / Agent reads .env / instructions too long / #file vs @workspace / MCP silent fail / IDE differences / free tier throttling / custom roles not discovered |
+| [Cursor](./cursor.en.md) | 8 | Agent rogue / Tab blast / rules not applied / @file silent fail / Agent·Ask mode confusion / model switching / Notepads removed / stale index |
+| [GitHub Copilot](./copilot.en.md) | 8 | Outdated APIs / Agent reads .env / instructions too long / #file vs Agent search / MCP silent fail / IDE differences / AI Credits exhausted / custom agents not discovered |
 | [Aider](./aider.en.md) | 7 | Auto-commit swallows WIP / /add misses deps / model-switch quality drop / lint loop burns tokens / stale map / Architect→Code drift / amend chaos |
 
 ---
 
 ## Other Tools
 
-Windsurf / Gemini CLI / Kiro / Trae / OpenClaw pitfall pages aren't written yet. You're welcome to:
+Devin Desktop (formerly Windsurf) / Codex CLI / Gemini CLI / Kiro / Trae / OpenClaw pitfall pages aren't written yet. You're welcome to:
 
 1. Check if you've hit any pain points with the tool you use
 2. Send a PR using the template below
@@ -74,7 +74,7 @@ Pitfalls of writing pitfalls (the meta-pitfall):
 - ❌ **Symptom and cause conflated**: readers can't tell "is this me?"
 - ✅ **Reproducible symptoms**: readers can recognize themselves
 - ✅ **Concrete recovery**: give a command or prompt, not "pay attention"
-- ✅ **Copy-pasteable prevention**: directly droppable into `CLAUDE.md` / `.cursorrules` / settings.json
+- ✅ **Copy-pasteable prevention**: directly droppable into `CLAUDE.md` / `.cursor/rules/*.mdc` / settings.json
 
 ---
 

diff --git a/pitfalls/README.md b/pitfalls/README.md
@@ -11,15 +11,15 @@
 | 工具 | 陷阱数 | 覆盖主题 |
 |------|-------|---------|
 | [Claude Code](./claude-code.md) | 8 | 上下文溢出 / 幻觉 API / 过度重构 / 测试谎报 / CLAUDE.md 被忽略 / git amend / Plan 漂移 / Subagent 传话 |
-| [Cursor](./cursor.md) | 8 | Composer 脱缰 / Tab 暴吐 / .cursorrules 超长 / @file 失效 / Chat 模式混用 / 模型切换 / Notepads 过期 / 索引陈旧 |
-| [GitHub Copilot](./copilot.md) | 8 | 过期 API / Agent 读 .env / instructions 太长 / #file vs @workspace / MCP 失效 / IDE 差异 / 免费限流 / 自定义角色不生效 |
+| [Cursor](./cursor.md) | 8 | Agent 脱缰 / Tab 暴吐 / 规则不生效 / @file 失效 / Agent·Ask 模式混用 / 模型切换 / Notepads 已移除 / 索引陈旧 |
+| [GitHub Copilot](./copilot.md) | 8 | 过期 API / Agent 读 .env / instructions 太长 / #file vs Agent 搜索 / MCP 失效 / IDE 差异 / AI Credits 耗尽 / 自定义 Agent 不生效 |
 | [Aider](./aider.md) | 7 | auto-commit 吃变更 / /add 漏依赖 / 模型切换质量塌 / lint 循环烧 token / Map 过期 / Architect→Code 漂移 / amend 失控 |
 
 ---
 
 ## 其他工具陷阱
 
-Windsurf / Gemini CLI / Kiro / Trae / OpenClaw 的陷阱页还没写。欢迎：
+Devin Desktop（原 Windsurf）/ Codex CLI / Gemini CLI / Kiro / Trae / OpenClaw 的陷阱页还没写。欢迎：
 
 1. 看你用的工具有没有踩过坑
 2. 按下面模板写一篇 PR 过来
@@ -74,7 +74,7 @@ Windsurf / Gemini CLI / Kiro / Trae / OpenClaw 的陷阱页还没写。欢迎：
 - ❌ **症状和根因混在一起**：读者看不清"这是不是我遇到的"
 - ✅ **可复现的症状**：读者能对号入座
 - ✅ **出坑操作具体**：给命令或提示词，不是"注意一下"
-- ✅ **预防措施落地**：能直接抄到 `CLAUDE.md` / `.cursorrules` / settings.json
+- ✅ **预防措施落地**：能直接抄到 `CLAUDE.md` / `.cursor/rules/*.mdc` / settings.json
 
 ---
 

diff --git a/workflows/claude-code-copilot.en.md b/workflows/claude-code-copilot.en.md
@@ -42,5 +42,5 @@
 ## Why This Works
 
 - **No context switching** — Claude Code lives in the terminal, Copilot lives in VS Code, each doing its own thing
-- **Cost control** — Copilot is a flat monthly fee with unlimited completions, no extra charges for heavy usage
+- **Cost control** — Copilot paid plans include unlimited code completions, no extra charges for heavy completion usage (Chat / Agent are billed in AI Credits)
 - **Strong complementarity** — Claude Code isn't great at inline completion, Copilot isn't great at Agent tasks
diff --git a/workflows/claude-code-copilot.md b/workflows/claude-code-copilot.md
@@ -26,7 +26,7 @@
    > 按设计方案创建 src/services/notification/ 下的所有文件
 
 2. VS Code + Copilot 填充实现
-   打开 Copilot 创建的文件，写代码时 Copilot 自动补全
+   打开 Claude Code 创建的文件，写代码时 Copilot 自动补全
 
 3. Claude Code 跑测试和审查
    > 跑测试看有没有问题，然后做一次代码审查
@@ -40,5 +40,5 @@
 ## 优势
 
 - **无需切换** — Claude Code 在终端，Copilot 在 VS Code，各干各的
-- **成本控制** — Copilot 包月制不限量，大量补全不额外花钱
+- **成本控制** — Copilot 付费套餐代码补全不限量，大量补全不额外花钱（Chat / Agent 按 AI Credits 计费）
 - **互补性强** — Claude Code 不擅长行内补全，Copilot 不擅长 Agent 任务
diff --git a/workflows/claude-code-cursor.en.md b/workflows/claude-code-cursor.en.md
@@ -37,7 +37,7 @@ Phase 2: Skeleton Code (Claude Code)
 
 Phase 3: Implementation Details (Cursor)
 Open Cursor and flesh out the implementation on top of the skeleton Claude Code created.
-Use Composer mode to implement business logic file by file.
+Use the Agent panel (Cmd+I) to implement business logic file by file.
 
 Phase 4: Testing (Claude Code)
 > Write comprehensive tests for the notification module.
@@ -71,7 +71,7 @@ Phase 3: Verify (Claude Code)
 Keep project configuration consistent across both tools:
 
 ```
-# Write the same core rules in both CLAUDE.md and .cursorrules
+# Write the same core rules in both CLAUDE.md and .cursor/rules/*.mdc
 # Or use superpowers-zh, which supports both tools
 
 cd /your/project

diff --git a/workflows/claude-code-cursor.md b/workflows/claude-code-cursor.md
@@ -35,7 +35,7 @@
 
 阶段 3：实现细节（Cursor）
 打开 Cursor，在 Claude Code 创建的骨架上填充实现。
-用 Composer 模式逐个文件实现业务逻辑。
+用 Agent 面板（Cmd+I）逐个文件实现业务逻辑。
 
 阶段 4：测试（Claude Code）
 > 给通知模块写完整的测试。
@@ -68,7 +68,7 @@
 两个工具的项目配置保持一致：
 
 ```
-# CLAUDE.md 和 .cursorrules 写相同的核心规则
+# CLAUDE.md 和 .cursor/rules/*.mdc 写相同的核心规则
 # 或者用 superpowers-zh，它同时支持两个工具
 
 cd /your/project

diff --git a/workflows/scenarios.en.md b/workflows/scenarios.en.md
@@ -89,7 +89,7 @@ Type definitions should be complete so IDE autocomplete works in the next step.
 
 ### Step 3: Switch to Cursor — fill in the implementation
 
-Open the skeletons in Cursor and use Composer file by file. Example prompt for `order-export.service.ts`:
+Open the skeletons in Cursor and use the Agent panel file by file. Example prompt for `order-export.service.ts`:
 
 ```
 @order-export.service.ts Implement each method per the TODOs.

diff --git a/workflows/scenarios.md b/workflows/scenarios.md
@@ -87,7 +87,7 @@
 
 ### 第三步：切 Cursor 填实现
 
-在 Cursor 里打开骨架文件，用 Composer 逐个填充。以 `order-export.service.ts` 为例，Composer 里输入：
+在 Cursor 里打开骨架文件，用 Agent 面板逐个填充。以 `order-export.service.ts` 为例，在 Agent 里输入：
 
 ```
 @order-export.service.ts 按 TODO 实现每个方法。

diff --git a/workflows/tool-selection.en.md b/workflows/tool-selection.en.md
@@ -15,12 +15,12 @@
 | **New project scaffolding** | Claude Code | Starting from scratch needs big-picture planning ability |
 | **Bug debugging** | Claude Code | Can read logs, run commands, do systematic analysis |
 | **Code review** | Claude Code / Cursor | Claude Code is more thorough, Cursor is quicker |
-| **Learning a new codebase** | Cursor + Chat | Select code and ask questions — the most natural interaction |
+| **Learning a new codebase** | Cursor (Ask mode) | Select code and ask questions — the most natural interaction |
 | **Writing tests** | Claude Code | Can run tests, check coverage, auto-fix failures |
 | **Documentation / comments** | Copilot | Inline completion makes writing comments seamless |
 | **Frontend UI tweaks** | Cursor | Live preview + visual editing |
-| **CLI / scripting** | Claude Code / Gemini CLI | CLI-native, fits terminal workflows |
-| **Exploring large codebases** | Gemini CLI | Largest context window (2M tokens) |
+| **CLI / scripting** | Claude Code / Codex CLI | CLI-native, fits terminal workflows |
+| **Exploring large codebases** | Claude Code | Opus/Sonnet 5.5 both have 1M context (Gemini CLI is also 1M, but no longer serves individual users — enterprise / paid API keys only) |
 | **CI / automated code review** | Codex CLI | Official GitHub Action with built-in restricted sandbox proxy |
 | **Already on ChatGPT Plus/Pro** | Codex CLI | Subscription quota included; OS-kernel sandbox out of the box |
 | **Fully offline / zero API cost** | Codex CLI or Aider | `codex --oss --local-provider ollama` runs local models |
@@ -39,11 +39,11 @@
 | Multi-file coordination | 3/3 | 2/3 | 2/3 | 2/3 | 2/3 |
 | Project rules config | 3/3 | 3/3 | 3/3 | 2/3 | 2/3 |
 | Extensibility (MCP) | 3/3 | 3/3 | 2/3 | 2/3 | 2/3 |
-| Sandbox depth | App-layer + hooks | **OS kernel** | -- | -- | -- |
+| Sandbox depth | OS-level Bash sandbox + hooks | **OS kernel** | -- | -- | -- |
 | Local model support | -- | 3/3 (--oss) | -- | -- | -- |
-| Context window | 2/3 | 2/3 | 2/3 | 2/3 | 3/3 |
+| Context window | 3/3 (1M) | 2/3 | 2/3 | 2/3 | 3/3 (1M) |
 | IDE integration | -- | -- | 3/3 | 3/3 | -- |
-| Free tier | 1/3 | 2/3 (ChatGPT plan included) | 1/3 | 2/3 | 3/3 |
+| Free tier | 1/3 | 2/3 (ChatGPT plan included) | 1/3 | 2/3 | -- (individual free tier ended) |
 
 ---
 
@@ -67,14 +67,14 @@ Copilot     -> Inline completion, writing comments, simple Q&A
 
 Best for: Backend developers, VS Code users
 
-### Combo 3: Gemini CLI + Cursor (Budget-Friendly)
+### Combo 3: Copilot Free + Aider with a Local Model (Budget-Friendly)
 
 ```
-Gemini CLI -> Large-scale analysis, code exploration (free)
-Cursor     -> Daily coding, interactive editing
+Copilot Free           -> Inline completion, simple Q&A
+Aider + local model    -> Terminal Agent tasks (e.g. `aider --model ollama/qwen3-coder`)
 ```
 
-Best for: Solo developers who want to keep costs down
+Best for: Solo developers who want to keep costs down (IDE completion + terminal Agent with zero subscriptions; Trae's free tier, Auto mode only, also works)
 
 ### Combo 4: Codex CLI + Cursor (ChatGPT Subscribers)
 
@@ -84,7 +84,7 @@ Cursor    -> Daily coding, Tab completion
 ```
 
 Best for: ChatGPT Plus/Pro subscribers who want their plan to drive Agent value;
-especially for security-sensitive work needing kernel-level sandbox (Seatbelt / Landlock).
+especially for security-sensitive work needing kernel-level sandbox (Seatbelt / bubblewrap).
 
 ### Combo 5: Codex CLI + Claude Code (Dual CLI)
 
@@ -107,8 +107,8 @@ Signals that it's time to switch from one tool to another:
 | Cursor's completion is wrong after 3 attempts | Switch to Claude Code for systematic analysis |
 | Claude Code conversation is too long and quality drops | Start a new conversation, or switch to Cursor for remaining small tasks |
 | Need to see live results | Switch to Cursor / Copilot (in-IDE preview) |
-| Need to run commands to verify | Switch to Claude Code / Gemini CLI (in-terminal) |
-| Need to understand a large codebase | Switch to Gemini CLI (largest context) |
+| Need to run commands to verify | Switch to Claude Code / Codex CLI (in-terminal) |
+| Need to understand a large codebase | Switch to Claude Code (1M context) |
 | Need to run a non-interactive Agent in CI | Switch to Codex CLI (`codex exec --json` + official Action) |
 | Handling sensitive data / offline environment | Switch to Codex CLI (`--oss --local-provider ollama`) |
-| Need kernel-level sandbox guarantees | Switch to Codex CLI (Seatbelt / Landlock) |
+| Need kernel-level sandbox guarantees | Switch to Codex CLI (Seatbelt / bubblewrap) |