diff --git a/.lychee.toml b/.lychee.toml
index 3653050..b573be8 100644
--- a/.lychee.toml
+++ b/.lychee.toml
@@ -49,6 +49,9 @@ exclude = [
   # 需要登录的 GitHub 仓库设置页
   "^https?://github\\.com/.+/settings",
 
+  # 对 CI 爬虫返回 403 的站点（人工访问正常）
+  "^https?://platform\\.openai\\.com",
+
   # QQ 链接跳转
   "^https?://qm\\.qq\\.com",
 ]
diff --git a/copilot/README.en.md b/copilot/README.en.md
index decb849..390965a 100644
--- a/copilot/README.en.md
+++ b/copilot/README.en.md
@@ -3,6 +3,8 @@
 # GitHub Copilot Best Practices
 
 > GitHub Copilot is the built-in AI coding assistant for VS Code and JetBrains IDEs. Its core strength is **seamless integration** — no tool switching needed, just write code in your editor and get completions and suggestions naturally. Copilot Agent mode evolves it from a completion tool into an autonomous agent that can tackle tasks independently.
+>
+> Last updated: 2026-09.
 
 ---
 
@@ -11,12 +13,13 @@
 | Concept | Description | Use Case |
 |---------|-------------|----------|
 | **Code Completion** | Inline gray suggestions | Daily coding, press Tab to accept |
-| **Chat** | Sidebar conversation `Cmd+Shift+I` | Q&A, code explanations |
-| **Agent Mode** | Autonomously completes multi-step tasks | Complex tasks, cross-file changes |
+| **Chat** | Chat view `⌃⌘I` | Q&A, code explanations |
+| **Agent Mode** | Autonomously completes multi-step tasks (`⇧⌘I` opens chat in agent mode) | Complex tasks, cross-file changes |
 | **Copilot Instructions** | `.github/copilot-instructions.md` | Project-level configuration |
-| **Chat Modes** | Custom conversation roles | Security auditor, testing expert, etc. |
-| **MCP Server** | Extends Copilot's tool capabilities | Connect to databases, APIs, etc. |
-| **# References** | `#file` `#selection` `#terminal` | Pinpoint context precisely |
+| **Instructions files** | `.github/instructions/*.instructions.md`, scoped by path via `applyTo` | Per-directory / per-file-type rules |
+| **Custom Agents** | `.github/agents/*.agent.md` (formerly Chat Modes) | Security auditor, testing expert, etc. |
+| **MCP Server** | `.vscode/mcp.json`, extends Copilot's tool capabilities | Connect to databases, APIs, etc. |
+| **# References** | `#file` `#selection` `#terminal` `#codebase` | Pinpoint context precisely |
 
 ---
 
@@ -63,6 +66,9 @@ Create `.github/copilot-instructions.md` in your project root:
 
 # Reference VS Code problems panel
 #problems Fix these type errors for me
+
+# Force a semantic search of the codebase
+#codebase Where in the project do we build SQL by string concatenation?
 ```
 
 ---
@@ -75,10 +81,10 @@ Copilot Agent was the biggest update of 2025. Enter a task in the chat, and Agen
 
 ### Using Agent Mode
 
-Select Agent mode in Chat (or just describe a complex task):
+Select Agent mode in Chat (or press `⇧⌘I` to jump straight in). The agent searches the codebase on its own — no need for `@workspace`:
 
 ```
-@workspace Add rate limiting to all endpoints under src/api/,
+Add rate limiting to all endpoints under src/api/,
 using Redis as the counter. Max 60 requests per user per minute.
 Requirements:
 1. A reusable rate_limit decorator
@@ -89,15 +95,14 @@ Requirements:
 
 ### Agent + MCP for Extended Capabilities
 
-Use MCP Servers to give Agent access to external tools:
+Use MCP Servers to give Agent access to external tools. Create `.vscode/mcp.json` in your project (the top-level key is `servers`):
 
 ```json
-// .vscode/settings.json
 {
-  "github.copilot.chat.mcpServers": {
+  "servers": {
     "postgres": {
       "command": "npx",
-      "args": ["@modelcontextprotocol/server-postgres", "postgresql://..."]
+      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://..."]
     }
   }
 }
@@ -141,36 +146,57 @@ You are a security review expert. When reviewing code:
 4. Label risk levels: 🔴 Critical / 🟡 Medium / 🟢 Low
 ```
 
-Invoke this role in Chat with `@security-reviewer`.
+Select it from the **Agent dropdown** in the Chat view, or type `/agents` in the chat input to pick it from the list.
 
-### 3. Leverage Workspace for Global Understanding
+### 3. Let the Agent Search the Whole Codebase
 
 ```
-@workspace Are there any hardcoded secrets or sensitive values in the project?
+Are there any hardcoded secrets or sensitive values in the project?
 Find them all and refactor to use environment variables.
 ```
 
+The agent searches the codebase automatically; add `#codebase` when you want to force a semantic search.
+
 ---
 
 ## Advanced Tips
 
-### Custom Instruction Files
+### Custom Instructions and Extension Files
+
+Copilot supports these files to fine-tune behavior:
+
+| File | Purpose |
+|------|---------|
+| `.github/copilot-instructions.md` | Global project instructions |
+| `.github/instructions/*.instructions.md` | Scoped by path via the `applyTo` glob in frontmatter |
+| `AGENTS.md` / `CLAUDE.md` | Cross-tool instruction files, also read by Copilot |
+| `.github/agents/*.agent.md` | Custom agents (`.chatmode.md` is deprecated — rename to `.agent.md` to migrate) |
+| `.github/prompts/*.prompt.md` | Reusable prompts, invoked in Chat as `/name` |
+| `.github/skills/`, `.claude/skills/`, `.agents/skills/` | Agent Skills, loaded on demand |
+| Hooks | Run scripts before/after agent actions |
 
-Copilot supports instruction files to fine-tune behavior:
+`applyTo` example (`.github/instructions/python.instructions.md`):
 
-- **`.github/copilot-instructions.md`** — Global project instructions
-- **`.github/chatModes/`** — Custom Chat roles (e.g., security reviewer, testing expert)
+```markdown
+---
+applyTo: "**/*.py"
+---
 
-If you use superpowers-zh, you can also write methodology in skill files under `.claude/skills/` — Copilot Agent's `@workspace` command reads markdown files in the project.
+- All functions must have type annotations
+- Use pytest, not unittest
+```
 
-### VS Code Keyboard Shortcuts
+If you use superpowers-zh, put the skill files under `.github/skills/`, `.claude/skills/` or `.agents/skills/` — Copilot Agent loads them on demand as Agent Skills.
+
+### VS Code Keyboard Shortcuts (macOS)
 
 | Shortcut | Action |
 |----------|--------|
 | `Tab` | Accept completion |
 | `Esc` | Reject completion |
-| `Cmd+Shift+I` | Open Copilot Chat |
-| `Cmd+I` | Inline edit |
+| `⌃⌘I` | Open the Chat view |
+| `⇧⌘I` | Open chat in agent mode |
+| `⌘I` | Inline chat (in the editor) |
 | `Alt+]` / `Alt+[` | Cycle through completion suggestions |
 
 ### Completion Optimization
@@ -182,6 +208,30 @@ Tips for more accurate Copilot completions:
 3. **Write function signatures first** — Define the name, parameters, and return type, then let Copilot complete the body
 4. **Keep files short** — Large files add context noise, causing Copilot to drift
 
+### Billing and Plans
+
+Since 2026-06-01 Copilot bills usage in **GitHub AI Credits**: Chat, agent mode, code review, the cloud agent, Copilot CLI, etc. consume credits; code completions stay unlimited on paid plans.
+
+| Plan | Price | Included per month |
+|------|-------|--------------------|
+| Free | $0 | 2,000 completions + a small credit allowance |
+| Pro | $10/mo | 1,500 credits |
+| Pro+ | $39/mo | 7,000 credits |
+| Max | $100/mo | 20,000 credits |
+| Business | $19/seat/mo | 1,900 credits per user |
+| Enterprise | $39/seat/mo | 3,900 credits per user |
+
+See the [official plans page](https://docs.github.com/en/copilot/get-started/plans) for the latest.
+
+### New in 2026
+
+- **Copilot coding agent renamed to Copilot cloud agent**: takes an Issue to a PR in the cloud
+- **GitHub Copilot app**: desktop app, GA on 2026-06-17, available on all plans
+- **Copilot CLI GA**: Copilot agent in the terminal
+- **Agent Plugins 1.0**: package and distribute custom agents, skills and more
+- **Copilot code review**: consumes AI Credits + GitHub Actions minutes
+- **JetBrains**: custom agents, subagents and the plan agent went GA in March 2026, with AGENTS.md / CLAUDE.md support
+
 ---
 
 ## Common Pitfalls
@@ -190,10 +240,10 @@ Tips for more accurate Copilot completions:
 |---------|-------------|----------|
 | Outdated API completions | Copilot suggests deprecated library APIs | Open the library source or docs as a tab for context |
 | Agent edits wrong files | Multi-file changes touch things they shouldn't | Use `#file` to limit scope |
-| Ignores .gitignore | Copilot may read node_modules | Check exclude settings in configuration |
-| Instructions too long | Exceeds model context window | Trim to essential rules, move details into Chat Modes |
+| Sensitive files get read | Agent mode in the IDE doesn't support content exclusion, so `.env` etc. may still be read | Keep secrets out of the project directory; content exclusion is configured at repo/org/enterprise level and doesn't apply to agent mode |
+| Instructions too long | Key points get buried, later rules work poorly | Trim to essential rules; move situational rules into `.instructions.md` (`applyTo`) or custom agents |
 
-👉 **Deep dive**: [Copilot Pitfalls](../pitfalls/copilot.en.md) — 8 real-world traps (Agent reads .env / MCP silent fail / free tier throttling and more), each with Symptom / Cause / Recovery / Prevention
+👉 **Deep dive**: [Copilot Pitfalls](../pitfalls/copilot.en.md) — 8 real-world traps (Agent reads .env / MCP silent fail / running out of credits and more), each with Symptom / Cause / Recovery / Prevention
 
 ---
 
@@ -204,12 +254,13 @@ Copy directly into your project:
 | Template | Purpose |
 |----------|---------|
 | [copilot-instructions.md](templates/copilot-instructions.md) | Project guidelines template, copy to `.github/copilot-instructions.md` |
-| [security-reviewer.agent.md](templates/security-reviewer.agent.md) | Security reviewer role, copy to `.github/agents/` |
+| [security-reviewer.agent.md](templates/security-reviewer.agent.md) | Security reviewer custom agent, copy to `.github/agents/` |
 
 ---
 
 ## Further Reading
 
 - [Copilot Official Docs](https://docs.github.com/en/copilot)
+- [VS Code Copilot customization docs](https://code.visualstudio.com/docs/copilot/customization/custom-agents) — Custom agents, instructions, MCP
 - [awesome-copilot](https://github.com/github/awesome-copilot) — Official resource collection (27k+ stars)
 - [superpowers-zh](https://github.com/jnMetaCode/superpowers-zh) — Skills methodology (also supports VS Code Copilot)
diff --git a/copilot/README.md b/copilot/README.md
index 77e2baf..cd5b08a 100644
--- a/copilot/README.md
+++ b/copilot/README.md
@@ -1,6 +1,8 @@
 # GitHub Copilot 最佳实践
 
 > GitHub Copilot 是 VS Code / JetBrains 内置的 AI 编程助手。它的核心优势是**无缝集成** — 不需要切换工具，在编辑器里自然地写代码就有补全和建议。Copilot Agent 模式让它从补全工具进化成了能独立完成任务的 Agent。
+>
+> 信息更新于 2026-09。
 
 ---
 
@@ -9,12 +11,13 @@
 | 概念 | 说明 | 用途 |
 |------|------|------|
 | **代码补全** | 行内灰色建议 | 日常编码，按 Tab 接受 |
-| **Chat** | 侧边栏对话 `Cmd+Shift+I` | 问答、解释代码 |
-| **Agent 模式** | 自主完成多步骤任务 | 复杂任务、跨文件修改 |
+| **Chat** | Chat 视图 `⌃⌘I` | 问答、解释代码 |
+| **Agent 模式** | 自主完成多步骤任务（`⇧⌘I` 直接以 Agent 模式打开） | 复杂任务、跨文件修改 |
 | **Copilot Instructions** | `.github/copilot-instructions.md` | 项目级配置 |
-| **Chat Modes** | 自定义对话角色 | 安全审查、测试专家等 |
-| **MCP Server** | 扩展 Copilot 的工具能力 | 连接数据库、API 等 |
-| **#引用** | `#file` `#selection` `#terminal` | 精确指定上下文 |
+| **Instructions 文件** | `.github/instructions/*.instructions.md`，用 `applyTo` 按路径生效 | 按目录/文件类型细化规则 |
+| **自定义 Agent** | `.github/agents/*.agent.md`（原 Chat Modes） | 安全审查、测试专家等 |
+| **MCP Server** | `.vscode/mcp.json`，扩展 Copilot 的工具能力 | 连接数据库、API 等 |
+| **#引用** | `#file` `#selection` `#terminal` `#codebase` | 精确指定上下文 |
 
 ---
 
@@ -61,6 +64,9 @@
 
 # 引用 VS Code 问题面板
 #problems 帮我修复这些类型错误
+
+# 强制做一次代码库语义搜索
+#codebase 项目里哪些地方在直接拼接 SQL？
 ```
 
 ---
@@ -73,10 +79,10 @@ Copilot Agent 是 2025 年最大的更新。从对话框输入任务，Agent 会
 
 ### 使用 Agent 模式
 
-在 Chat 中选择 Agent 模式（或直接描述复杂任务）：
+在 Chat 中选择 Agent 模式（或按 `⇧⌘I` 直接进入）。Agent 会自己搜索代码库，不需要再加 `@workspace`：
 
 ```
-@workspace 给 src/api/ 下所有接口加上 rate limiting，
+给 src/api/ 下所有接口加上 rate limiting，
 使用 Redis 做计数器，每个用户每分钟最多 60 次请求。
 需要：
 1. 一个可复用的 rate_limit 装饰器
@@ -87,15 +93,14 @@ Copilot Agent 是 2025 年最大的更新。从对话框输入任务，Agent 会
 
 ### Agent + MCP 扩展能力
 
-通过 MCP Server 让 Agent 访问外部工具：
+通过 MCP Server 让 Agent 访问外部工具。在项目里创建 `.vscode/mcp.json`（顶层键是 `servers`）：
 
 ```json
-// .vscode/settings.json
 {
-  "github.copilot.chat.mcpServers": {
+  "servers": {
     "postgres": {
       "command": "npx",
-      "args": ["@modelcontextprotocol/server-postgres", "postgresql://..."]
+      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://..."]
     }
   }
 }
@@ -139,36 +144,57 @@ description: 按 OWASP Top 10 审查代码安全
 4. 标注风险等级：🔴 严重 / 🟡 中等 / 🟢 低
 ```
 
-在 Chat 中用 `@security-reviewer` 调用这个角色。
+在 Chat 视图的 **Agent 下拉框**里选中它，或在输入框里输入 `/agents` 打开列表选择。
 
-### 3. 利用 Workspace 全局理解
+### 3. 让 Agent 全局搜索
 
 ```
-@workspace 项目里有没有硬编码的密钥或敏感信息？
+项目里有没有硬编码的密钥或敏感信息？
 帮我全部找出来，改成环境变量。
 ```
 
+Agent 会自动搜索代码库；想强制做一次语义搜索时加上 `#codebase`。
+
 ---
 
 ## 进阶技巧
 
-### 自定义指令文件
+### 自定义指令与扩展文件
+
+Copilot 支持这些文件来细化行为：
+
+| 文件 | 作用 |
+|------|------|
+| `.github/copilot-instructions.md` | 全局项目指令 |
+| `.github/instructions/*.instructions.md` | 用 frontmatter 的 `applyTo`（glob）按路径生效 |
+| `AGENTS.md` / `CLAUDE.md` | 跨工具通用的指令文件，Copilot 也会读 |
+| `.github/agents/*.agent.md` | 自定义 Agent（原 `.chatmode.md` 已弃用，改名为 `.agent.md` 即可迁移） |
+| `.github/prompts/*.prompt.md` | 可复用的 Prompt，在 Chat 里用 `/名字` 调用 |
+| `.github/skills/`、`.claude/skills/`、`.agents/skills/` | Agent Skills，Agent 按需加载 |
+| Hooks | 在 Agent 动作前后跑脚本 |
+
+`applyTo` 示例（`.github/instructions/python.instructions.md`）：
 
-Copilot 支持通过指令文件细化行为：
+```markdown
+---
+applyTo: "**/*.py"
+---
 
-- **`.github/copilot-instructions.md`** — 全局项目指令
-- **`.github/chatModes/`** — 自定义 Chat 角色（如安全审查员、测试专家）
+- 所有函数必须有类型注解
+- 用 pytest，不用 unittest
+```
 
-如果你用 superpowers-zh，也可以在 `.claude/skills/` 下的 skill 文件里写方法论，Copilot Agent 的 `@workspace` 命令会读取项目中的 markdown 文件。
+如果你用 superpowers-zh，skill 文件放在 `.github/skills/`、`.claude/skills/` 或 `.agents/skills/` 下，Copilot Agent 会作为 Agent Skills 按需加载。
 
-### VS Code 快捷键
+### VS Code 快捷键（macOS）
 
 | 快捷键 | 功能 |
 |--------|------|
 | `Tab` | 接受补全 |
 | `Esc` | 拒绝补全 |
-| `Cmd+Shift+I` | 打开 Copilot Chat |
-| `Cmd+I` | 行内编辑 |
+| `⌃⌘I` | 打开 Chat 视图 |
+| `⇧⌘I` | 以 Agent 模式打开 Chat |
+| `⌘I` | 行内 Chat（编辑器内） |
 | `Alt+]` / `Alt+[` | 切换不同补全建议 |
 
 ### 补全优化
@@ -180,6 +206,30 @@ Copilot 支持通过指令文件细化行为：
 3. **函数签名先写好** — 先写好函数名、参数、返回类型，再让它补全函数体
 4. **保持文件简短** — 大文件上下文噪音多，Copilot 容易跑偏
 
+### 计费与套餐
+
+2026-06-01 起 Copilot 改为按 **GitHub AI Credits** 计费：Chat、Agent 模式、代码审查、云端 Agent、Copilot CLI 等消耗 Credits；代码补全在付费套餐中不限量。
+
+| 套餐 | 价格 | 每月包含 |
+|------|------|---------|
+| Free | $0 | 2,000 次补全 + 少量 Credits |
+| Pro | $10/月 | 1,500 Credits |
+| Pro+ | $39/月 | 7,000 Credits |
+| Max | $100/月 | 20,000 Credits |
+| Business | $19/席位/月 | 每人 1,900 Credits |
+| Enterprise | $39/席位/月 | 每人 3,900 Credits |
+
+以 [官方套餐说明](https://docs.github.com/en/copilot/get-started/plans) 为准。
+
+### 2026 新增
+
+- **Copilot coding agent 更名为 Copilot cloud agent**：在云端独立完成 Issue → PR
+- **GitHub Copilot App**：桌面应用，2026-06-17 GA，所有套餐可用
+- **Copilot CLI GA**：终端里的 Copilot Agent
+- **Agent Plugins 1.0**：打包分发自定义 Agent、Skills 等扩展
+- **Copilot 代码审查**：消耗 AI Credits + GitHub Actions 分钟数
+- **JetBrains**：自定义 Agent、子 Agent、Plan Agent 于 2026 年 3 月 GA，并支持 AGENTS.md / CLAUDE.md
+
 ---
 
 ## 常见陷阱
@@ -188,10 +238,10 @@ Copilot 支持通过指令文件细化行为：
 |------|------|------|
 | 补全过时 API | Copilot 用了过期的库 API | 打开库的源码或文档作为 tab 上下文 |
 | Agent 改错文件 | 多文件修改时动了不该动的 | 用 `#file` 限定范围 |
-| 忽略 .gitignore | Copilot 可能读取 node_modules | 检查设置里的 exclude 配置 |
-| Instructions 太长 | 超过模型上下文窗口 | 精简到关键规则，详细规则拆到 Chat Modes |
+| 敏感文件被读 | IDE 里的 Agent 模式不支持内容排除（Content Exclusion），`.env` 等照样可能被读 | 敏感信息不落在项目目录；内容排除只能在仓库/组织/企业级配置，且对 Agent 模式无效 |
+| Instructions 太长 | 重点被淹没，靠后的规则效果差 | 精简到关键规则，场景化规则拆到 `.instructions.md`（`applyTo`）或自定义 Agent |
 
-👉 **深度展开版**：[Copilot 陷阱合集](../pitfalls/copilot.md) — 8 个真实踩坑场景（Agent 读 .env / MCP 失效 / 免费限流 等），每个带症状 / 根因 / 出坑 / 预防
+👉 **深度展开版**：[Copilot 陷阱合集](../pitfalls/copilot.md) — 8 个真实踩坑场景（Agent 读 .env / MCP 失效 / 额度耗尽 等），每个带症状 / 根因 / 出坑 / 预防
 
 ---
 
@@ -202,12 +252,13 @@ Copilot 支持通过指令文件细化行为：
 | 模板 | 用途 |
 |------|------|
 | [copilot-instructions.md](templates/copilot-instructions.md) | 项目指引模板，复制到 `.github/copilot-instructions.md` |
-| [security-reviewer.agent.md](templates/security-reviewer.agent.md) | 安全审查角色，复制到 `.github/agents/` |
+| [security-reviewer.agent.md](templates/security-reviewer.agent.md) | 安全审查自定义 Agent，复制到 `.github/agents/` |
 
 ---
 
 ## 延伸阅读
 
 - [Copilot 官方文档](https://docs.github.com/en/copilot)
+- [VS Code Copilot 自定义文档](https://code.visualstudio.com/docs/copilot/customization/custom-agents) — 自定义 Agent、Instructions、MCP
 - [awesome-copilot](https://github.com/github/awesome-copilot) — 官方资源集合（27k+ star）
 - [superpowers-zh](https://github.com/jnMetaCode/superpowers-zh) — Skills 方法论（也支持 VS Code Copilot）
diff --git a/copilot/templates/security-reviewer.agent.md b/copilot/templates/security-reviewer.agent.md
index ac46fe9..1bb1506 100644
--- a/copilot/templates/security-reviewer.agent.md
+++ b/copilot/templates/security-reviewer.agent.md
@@ -3,6 +3,8 @@ name: 安全审查员
 description: 按 OWASP Top 10 审查代码安全性
 ---
 
+<!-- 用法：复制到项目的 .github/agents/security-reviewer.agent.md，在 Chat 的 Agent 下拉框或输入 /agents 选择 -->
+
 你是一名安全审查专家。审查代码时请按以下流程执行：
 
 1. **注入攻击**：检查 SQL 注入、命令注入、XSS
diff --git a/cursor/README.en.md b/cursor/README.en.md
index 326728c..9076981 100644
--- a/cursor/README.en.md
+++ b/cursor/README.en.md
@@ -2,7 +2,11 @@
 
 # Cursor Best Practices
 
-> Cursor is an AI-powered IDE based on VS Code, featuring three core capabilities: code completion, Chat, and Composer (Agent). Its strength lies in deep editor integration — select code to start a conversation, preview changes in real time right in the editor.
+> Cursor is an AI-powered IDE based on VS Code. Its core features are Tab completion, the Agent panel (with Agent / Ask / Plan modes) and inline edit. Its strength lies in deep editor integration — select code to start a conversation, preview changes in real time right in the editor.
+>
+> Note: the old "Composer panel" is now the **Agent panel**; "Composer" now refers to Cursor's own model (e.g. Composer 2.5).
+>
+> SpaceX completed its acquisition of Cursor on 2026-08-14 ([announcement](https://cursor.com/blog/joining-spacex)). Last updated: 2026-09.
 
 ---
 
@@ -11,21 +15,29 @@
 | Concept | Description | Use Case |
 |---------|-------------|----------|
 | **Tab Completion** | Context-aware code completion | Speed up daily coding |
-| **Chat** | Sidebar conversation, select code to ask questions | Understanding code, Q&A |
-| **Composer** | Agent mode, cross-file editing | Complex tasks, refactoring |
-| **Rules** | `.cursor/rules/*.md` rule files | Control AI behavior |
-| **@ References** | `@file` `@folder` `@web` etc. | Pinpoint context precisely |
-| **Notepads** | Reusable context snippets | Context management for complex projects |
+| **Agent panel** | Sidepanel; `Shift+Tab` cycles Agent / Ask / Plan modes | Agent edits across files; Ask is read-only Q&A; Plan drafts a plan first |
+| **Agents Window** | Multi-agent window since Cursor 3; local / worktree / cloud agents in parallel | Running several tasks at once |
+| **Rules** | `.cursor/rules/*.mdc` rule files (must be `.mdc`) | Control AI behavior |
+| **AGENTS.md** | Markdown instructions at the root or in any subdirectory | Rules shared across tools |
+| **Skills / Subagents / Hooks** | `.cursor/skills/`, `.cursor/agents/`, `.cursor/hooks.json` | Reusable methods, specialist subagents, scripts around agent actions |
+| **@ References** | `@Files` `@Folders` `@Terminals` `@Chats` `@Commit` `@Branch` `@Browser` | Pinpoint context precisely |
 
 ---
 
 ## Getting Started
 
-### .cursorrules — Project Rules
+### .cursor/rules/ — Project Rules
 
-Create `.cursorrules` in your project root or place rule files under `.cursor/rules/`:
+Put rule files under `.cursor/rules/`. **The extension must be `.mdc`** (a plain `.md` file has no frontmatter and is ignored by the rules system). A root-level `.cursorrules` file is the legacy format, kept only for compatibility; `AGENTS.md` (also supported in subdirectories) works too.
+
+`.cursor/rules/project.mdc`:
 
 ```markdown
+---
+description: General project rules
+alwaysApply: true
+---
+
 # Project Rules
 
 ## Tech Stack
@@ -55,21 +67,28 @@ Create `.cursorrules` in your project root or place rule files under `.cursor/ru
 # Reference a folder
 @src/api/ Error handling across these endpoints is inconsistent, unify them to...
 
-# Reference documentation
-@https://tanstack.com/query/latest Refer to the official docs and refactor the useEffect data fetching to useQuery
-
 # Reference terminal
-@terminal Check the error output and help me fix it
+@Terminals Check the error output and help me fix it
+
+# Reference git changes
+@Branch Review this branch's changes against main
+
+# Documentation: just paste the link for the Agent to look up
+Refer to https://tanstack.com/query/latest and refactor the useEffect data fetching to useQuery
 ```
 
+> If you're not sure which files matter, skip the @ — the Agent searches the codebase on its own.
+
 ---
 
 ## Prompting Tips
 
-### 1. Breaking Down Large Tasks with Composer
+### 1. Breaking Down Large Tasks with the Agent
+
+For big tasks, switch to **Plan mode** (`Shift+Tab`) to get a plan first, then switch back to Agent mode to execute:
 
 ```
-Use Composer mode. Execute the following steps:
+Execute the following steps:
 1. Read all page components under src/pages/ to understand the routing structure
 2. Create src/layouts/DashboardLayout.tsx as a unified layout
 3. Migrate all page components to use the new layout
@@ -79,7 +98,7 @@ Pause after each step and wait for my confirmation before continuing.
 
 ### 2. Select Code and Chat Directly
 
-Select code and press `Cmd+L` (macOS) to open Chat:
+Select code and press `Cmd+L` (macOS) to open the Agent panel with the selection included; switch to Ask mode for pure Q&A:
 
 ```
 # Select a complex regex
@@ -92,13 +111,18 @@ What's the time complexity of this function? Is there a more optimal approach?
 Rewrite this CSS using Tailwind classes
 ```
 
-### 3. Managing Complex Context with Notepads
+### 3. Turn Reusable Context into Rules
 
-For large projects, create a Notepad to save frequently used context:
+Notepads were deprecated in October 2025 and removed in 2.0. Move stable conventions you used to keep in a Notepad into a **manually applied rule** (or a Skill) and @ it when needed; for things that change often, reference the live code with `@Files`.
 
-```
-Notepad: "API Spec"
+`.cursor/rules/api-spec.mdc`:
+
+```markdown
+---
+description: API response format and error codes
+alwaysApply: false
 ---
+
 All APIs return this format:
 { code: number, data: T, message: string }
 
@@ -111,7 +135,7 @@ Error codes:
 Auth: Bearer Token in Authorization header
 ```
 
-Reference it in conversation: `@notepad:API Spec Implement the user list endpoint following this format`
+Reference it in conversation: `@api-spec Implement the user list endpoint following this format`
 
 ---
 
@@ -121,18 +145,27 @@ Reference it in conversation: `@notepad:API Spec Implement the user list endpoin
 
 ```
 .cursor/rules/
-├── global.md          # Global rules (code style, naming, etc.)
-├── react.md           # React-specific rules
-├── api.md             # API development rules
-├── testing.md         # Testing rules
-└── security.md        # Security rules
+├── global.mdc         # Global rules (code style, naming, etc.)
+├── react.mdc          # React-specific rules
+├── api.mdc            # API development rules
+├── testing.mdc        # Testing rules
+└── security.mdc       # Security rules
 ```
 
-Each file can specify trigger conditions:
+The `description` / `globs` / `alwaysApply` frontmatter decides the rule type:
+
+| Type | How | When loaded |
+|------|-----|-------------|
+| Always Apply | `alwaysApply: true` | Every conversation |
+| Apply Intelligently | `description` only | When the Agent decides it's relevant |
+| Apply to Specific Files | `globs` | When matching files are involved |
+| Apply Manually | none of the above | When you @ it |
 
 ```markdown
 ---
-globs: ["src/components/**/*.tsx"]
+description: React component rules
+globs: src/components/**/*.tsx
+alwaysApply: false
 ---
 
 # React Component Rules
@@ -141,36 +174,58 @@ globs: ["src/components/**/*.tsx"]
 - Must handle loading and error states
 ```
 
-### Supercharge Rules with superpowers-zh
+### Skills, Subagents, Hooks
 
-Writing rules manually is slow. Use superpowers-zh to install methodologies in one command:
+| Capability | Location | Notes |
+|------------|----------|-------|
+| Skills | `.cursor/skills/`, `.agents/skills/`, `.claude/skills/` | Reusable methodologies the Agent loads on demand |
+| Subagents | `.cursor/agents/` (also reads `.claude/agents/`) | Specialist subagents, e.g. code review, writing tests |
+| Hooks | `.cursor/hooks.json` | Run scripts before/after Agent actions (e.g. block dangerous commands) |
+
+### Supercharge with superpowers-zh Skills
+
+Writing methodologies by hand is slow. Install them in one command:
 
 ```bash
 cd /your/project
 npx superpowers-zh
-# Auto-installs to .cursor/rules/ with brainstorming, debugging, verification skills, etc.
+# Includes brainstorming, debugging, verification skills, etc.
 ```
 
-Once installed, Cursor automatically loads the matching skill rules for relevant files.
+These are **Skills** and belong in a Cursor Skills directory (`.cursor/skills/`, `.agents/skills/` or `.claude/skills/`), not `.cursor/rules/`. Once installed, the Agent loads them on demand for relevant tasks.
 
 ### Model Selection Strategy
 
 | Scenario | Recommended Model | Why |
 |----------|-------------------|-----|
-| Tab completion | cursor-small | Fast, low latency |
-| Simple Q&A | Claude Sonnet | Best value |
-| Complex refactoring | Claude Opus | Strongest comprehension |
-| Large Composer tasks | Claude Opus | Best at multi-file coordination |
+| Everyday Agent tasks | Composer 2.5 | Cursor's own model — fast and cheap |
+| Simple Q&A | Claude Sonnet / GPT-5.x | Best value |
+| Complex refactoring / large tasks | Claude Opus / GPT-5.x | Strong comprehension, good multi-file coordination |
+| Don't want to pick | Auto (Cursor Router) | Routes automatically based on your Cost / Balance / Intelligence preference |
+
+The list also includes Grok 4.x, Gemini, Kimi, GLM and more — check `Cursor Settings > Models` for what's actually available.
 
 ### Keyboard Shortcuts
 
 | Shortcut | Action |
 |----------|--------|
 | `Tab` | Accept completion |
-| `Cmd+L` | Open Chat (selected code auto-included) |
-| `Cmd+I` | Open Composer |
+| `Cmd+I` / `Cmd+L` | Toggle the Agent sidepanel (selected code auto-included) |
+| `Shift+Tab` | Cycle Agent / Ask / Plan modes |
+| `Cmd+E` | Toggle the Agent layout |
 | `Cmd+K` | Inline edit (after selecting code) |
-| `Cmd+Shift+L` | Add current file to Chat context |
+| `Cmd+Shift+L` | Add selected code to Agent context |
+
+### New in 2026
+
+- **Agents Window** (Cursor 3, 2026-04-02): run local / worktree / cloud agents in parallel
+- **Plan mode**: plan first, then act
+- **`/loop`**: have the Agent run a task in a loop
+- **Cloud subagents**, **Automations** (trigger agents automatically)
+- **Cursor Router**: Auto model routing with Cost / Balance / Intelligence options
+- **Bugbot + `/review`**: PR and local code review
+- **Projects coordinator agent**: one agent orchestrates several agents on a project
+- **iOS app**: check on and steer agents from your phone
 
 ---
 
@@ -178,23 +233,24 @@ Once installed, Cursor automatically loads the matching skill rules for relevant
 
 | Pitfall | Description | Solution |
 |---------|-------------|----------|
-| Rules too long | `.cursorrules` is thousands of lines, AI can't retain it all | Split into `.cursor/rules/` with globs for on-demand loading |
-| Composer goes off the rails | Agent mode edits files it shouldn't | Use `@file` to limit scope, or mark no-go zones in rules |
-| Completion too aggressive | Tab completion generates too much code at once | Adjust completion length in settings, or press `Esc` to reject |
-| Not enough context | AI doesn't understand project structure | Use `@folder` to reference key directories, write good `.cursorrules` |
+| Rules ignored | You put `.md` files in `.cursor/rules/` | Rename to `.mdc` and add frontmatter |
+| Rules too long | A single rule is thousands of lines, AI can't retain it all | Official advice: keep each rule under 500 lines; split into multiple `.mdc` files with globs |
+| Agent goes off the rails | Agent mode edits files it shouldn't | Confirm scope in Plan mode first, limit with `@Files`, or mark no-go zones in rules |
+| Completion too aggressive | Tab completion generates too much code at once | Press `Esc` to reject; snooze or disable it in `Cursor Settings → Tab` |
+| Not enough context | AI doesn't understand project structure | Use `@Folders` to reference key directories, write good rules / `AGENTS.md` |
 
-👉 **Deep dive**: [Cursor Pitfalls](../pitfalls/cursor.en.md) — 8 real-world traps (Composer rogue / @file silent fail / stale Notepads and more), each with Symptom / Cause / Recovery / Prevention
+👉 **Deep dive**: [Cursor Pitfalls](../pitfalls/cursor.en.md) — 8 real-world traps (Agent rogue / @ reference silent fail / migrating off Notepads and more), each with Symptom / Cause / Recovery / Prevention
 
 ---
 
 ## Configuration Templates
 
-Copy directly into your project's `.cursor/rules/` directory:
+Copy into your project's `.cursor/rules/` directory **and change the extension to `.mdc`** (e.g. `global.mdc`, `api.mdc`):
 
 | Template | Purpose |
 |----------|---------|
-| [global.cursorrules.md](templates/global.cursorrules.md) | Global rules (code style, naming, restrictions) |
-| [api.cursorrules.md](templates/api.cursorrules.md) | API development rules (only active in API directories) |
+| [global.cursorrules.md](templates/global.cursorrules.md) | Global rules (code style, naming, restrictions); save as `.cursor/rules/global.mdc` |
+| [api.cursorrules.md](templates/api.cursorrules.md) | API development rules (only active in API directories); save as `.cursor/rules/api.mdc` |
 
 ### Model Configuration
 
@@ -204,6 +260,7 @@ Cursor's model selection is configured in the settings UI (`Cursor Settings > Mo
 
 ## Further Reading
 
-- [Cursor Official Docs](https://docs.cursor.com)
+- [Cursor Official Docs](https://cursor.com/docs)
+- [Cursor Rules Docs](https://cursor.com/docs/context/rules)
 - [awesome-cursorrules](https://github.com/PatrickJS/awesome-cursorrules) — Community rules collection (38k+ stars)
 - [superpowers-zh](https://github.com/jnMetaCode/superpowers-zh) — Skills methodology (also supports Cursor)
diff --git a/cursor/README.md b/cursor/README.md
index 6f59e2b..1bda70e 100644
--- a/cursor/README.md
+++ b/cursor/README.md
@@ -1,6 +1,10 @@
 # Cursor 最佳实践
 
-> Cursor 是基于 VS Code 的 AI IDE，集成了代码补全、Chat、Composer（Agent）三大核心功能。它的优势在于和编辑器的深度集成——选中代码直接对话、在编辑器内实时预览修改。
+> Cursor 是基于 VS Code 的 AI IDE，核心功能是 Tab 补全、Agent 面板（Agent / Ask / Plan 三种模式）和行内编辑。它的优势在于和编辑器的深度集成——选中代码直接对话、在编辑器内实时预览修改。
+>
+> 注意：旧版的 "Composer 面板" 已改名为 **Agent 面板**；现在 "Composer" 指的是 Cursor 自研的模型（如 Composer 2.5）。
+>
+> 2026-08-14 SpaceX 完成对 Cursor 的收购（[官方公告](https://cursor.com/blog/joining-spacex)）。信息更新于 2026-09。
 
 ---
 
@@ -9,21 +13,29 @@
 | 概念 | 说明 | 用途 |
 |------|------|------|
 | **Tab 补全** | 基于上下文的代码补全 | 日常编码提速 |
-| **Chat** | 侧边栏对话，可选中代码提问 | 理解代码、问答 |
-| **Composer** | Agent 模式，可跨文件修改 | 复杂任务、重构 |
-| **Rules** | `.cursor/rules/*.md` 规则文件 | 控制 AI 行为 |
-| **@引用** | `@file` `@folder` `@web` 等 | 精确指定上下文 |
-| **Notepads** | 可复用的上下文片段 | 复杂项目的上下文管理 |
+| **Agent 面板** | 侧边栏，`Shift+Tab` 在 Agent / Ask / Plan 模式间切换 | Agent 跨文件改代码；Ask 只读问答；Plan 先出方案 |
+| **Agents Window** | Cursor 3 起的多 Agent 窗口，本地 / worktree / 云端 Agent 并行 | 同时跑多个任务 |
+| **Rules** | `.cursor/rules/*.mdc` 规则文件（必须是 `.mdc`） | 控制 AI 行为 |
+| **AGENTS.md** | 根目录或任意子目录的 Markdown 指令 | 跨工具通用的规则 |
+| **Skills / Subagents / Hooks** | `.cursor/skills/`、`.cursor/agents/`、`.cursor/hooks.json` | 可复用方法论、专项子 Agent、动作前后跑脚本 |
+| **@引用** | `@Files` `@Folders` `@Terminals` `@Chats` `@Commit` `@Branch` `@Browser` | 精确指定上下文 |
 
 ---
 
 ## 快速上手
 
-### .cursorrules — 项目规则
+### .cursor/rules/ — 项目规则
 
-在项目根目录创建 `.cursorrules` 或 `.cursor/rules/` 下放规则文件：
+在 `.cursor/rules/` 下放规则文件，**扩展名必须是 `.mdc`**（普通 `.md` 没有 frontmatter，会被规则系统忽略）。根目录单文件 `.cursorrules` 是旧格式，仅作兼容；也可以用 `AGENTS.md`（支持放在子目录）。
+
+`.cursor/rules/project.mdc`：
 
 ```markdown
+---
+description: 项目通用规则
+alwaysApply: true
+---
+
 # 项目规则
 
 ## 技术栈
@@ -53,21 +65,28 @@
 # 引用文件夹
 @src/api/ 这些接口的错误处理不统一，帮我统一改成...
 
-# 引用文档
-@https://tanstack.com/query/latest 参考官方文档，帮我把 useEffect 里的数据获取改成 useQuery
-
 # 引用终端
-@terminal 看看刚才的报错信息，帮我修
+@Terminals 看看刚才的报错信息，帮我修
+
+# 引用 Git 改动
+@Branch 帮我 review 这个分支相对 main 的改动
+
+# 参考文档：直接贴链接让 Agent 查阅
+参考 https://tanstack.com/query/latest ，帮我把 useEffect 里的数据获取改成 useQuery
 ```
 
+> 不确定哪些文件相关时可以不 @，Agent 会自己搜索代码库。
+
 ---
 
 ## 提示词技巧
 
-### 1. Composer 大任务拆解
+### 1. Agent 大任务拆解
+
+大任务可以先切到 **Plan 模式**（`Shift+Tab`）让它出方案，确认后再切回 Agent 模式执行：
 
 ```
-用 Composer 模式。按以下步骤执行：
+按以下步骤执行：
 1. 先读 src/pages/ 下所有页面组件，理解路由结构
 2. 创建 src/layouts/DashboardLayout.tsx 统一布局
 3. 把所有页面组件改成使用新布局
@@ -77,7 +96,7 @@
 
 ### 2. 选中代码直接对话
 
-选中一段代码后按 `Cmd+L`（macOS）进入 Chat：
+选中一段代码后按 `Cmd+L`（macOS）打开 Agent 面板（选中内容自动带入），纯问答可切到 Ask 模式：
 
 ```
 # 选中一段复杂的正则表达式
@@ -90,13 +109,18 @@
 把这段 CSS 改成 Tailwind 的写法
 ```
 
-### 3. 用 Notepads 管理复杂上下文
+### 3. 把常用上下文写成规则
 
-对于大型项目，创建 Notepad 保存常用上下文：
+Notepads 已于 2025 年 10 月弃用、在 2.0 版本移除。原来放 Notepad 的稳定约定，改写成一条**手动触发的规则**（或 Skill），用到时 @ 引用；易变的内容直接用 `@Files` 引用实时代码。
 
-```
-Notepad: "API 规范"
+`.cursor/rules/api-spec.mdc`：
+
+```markdown
+---
+description: API 返回格式与错误码规范
+alwaysApply: false
 ---
+
 所有 API 返回格式：
 { code: number, data: T, message: string }
 
@@ -109,7 +133,7 @@ Notepad: "API 规范"
 认证方式：Bearer Token in Authorization header
 ```
 
-对话时引用：`@notepad:API规范 按这个格式实现用户列表接口`
+对话时引用：`@api-spec 按这个格式实现用户列表接口`
 
 ---
 
@@ -119,18 +143,27 @@ Notepad: "API 规范"
 
 ```
 .cursor/rules/
-├── global.md          # 全局规则（代码风格、命名等）
-├── react.md           # React 相关规则
-├── api.md             # API 开发规则
-├── testing.md         # 测试规则
-└── security.md        # 安全规则
+├── global.mdc         # 全局规则（代码风格、命名等）
+├── react.mdc          # React 相关规则
+├── api.mdc            # API 开发规则
+├── testing.mdc        # 测试规则
+└── security.mdc       # 安全规则
 ```
 
-每个文件可以设置触发条件：
+每个文件用 frontmatter 的 `description` / `globs` / `alwaysApply` 决定规则类型：
+
+| 类型 | 写法 | 何时加载 |
+|------|------|---------|
+| Always Apply | `alwaysApply: true` | 每次对话 |
+| Apply Intelligently | 只写 `description` | Agent 根据描述判断是否需要 |
+| Apply to Specific Files | 写 `globs` | 涉及匹配文件时 |
+| Apply Manually | 都不写 | 你 @ 引用时 |
 
 ```markdown
 ---
-globs: ["src/components/**/*.tsx"]
+description: React 组件规则
+globs: src/components/**/*.tsx
+alwaysApply: false
 ---
 
 # React 组件规则
@@ -139,36 +172,58 @@ globs: ["src/components/**/*.tsx"]
 - 必须处理 loading 和 error 状态
 ```
 
-### 用 superpowers-zh 增强 Rules
+### Skills、Subagents、Hooks
+
+| 能力 | 位置 | 说明 |
+|------|------|------|
+| Skills | `.cursor/skills/`、`.agents/skills/`、`.claude/skills/` | 可复用的方法论，Agent 按需加载 |
+| Subagents | `.cursor/agents/`（也会读 `.claude/agents/`） | 专项子 Agent，如代码审查、写测试 |
+| Hooks | `.cursor/hooks.json` | 在 Agent 动作前后跑脚本（如拦截危险命令） |
+
+### 用 superpowers-zh 增强 Skills
 
-手动写 Rules 太慢？用 superpowers-zh 一键安装方法论：
+手动写方法论太慢？用 superpowers-zh 一键安装：
 
 ```bash
 cd /your/project
 npx superpowers-zh
-# 自动安装到 .cursor/rules/，包含 brainstorming、debugging、verification 等
+# 包含 brainstorming、debugging、verification 等 skill
 ```
 
-安装后 Cursor 在匹配文件时会自动加载对应的 skill 规则。
+这些是 **Skill**，应放在 Cursor 的 Skills 目录（`.cursor/skills/`、`.agents/skills/` 或 `.claude/skills/`），而不是 `.cursor/rules/`。安装后 Agent 会在相关任务中按需加载。
 
 ### 模型选择策略
 
 | 场景 | 推荐模型 | 原因 |
 |------|---------|------|
-| Tab 补全 | cursor-small | 速度快，延迟低 |
-| 简单问答 | Claude Sonnet | 性价比高 |
-| 复杂重构 | Claude Opus | 理解力最强 |
-| Composer 大任务 | Claude Opus | 多文件协调能力好 |
+| 日常 Agent 任务 | Composer 2.5 | Cursor 自研，速度快、成本低 |
+| 简单问答 | Claude Sonnet / GPT-5.x | 性价比高 |
+| 复杂重构 / 大任务 | Claude Opus / GPT-5.x | 理解力强，多文件协调好 |
+| 不想手动挑 | Auto（Cursor Router） | 按 Cost / Balance / Intelligence 偏好自动路由 |
+
+列表里还有 Grok 4.x、Gemini、Kimi、GLM 等，以 `Cursor Settings > Models` 实际显示为准。
 
 ### 快捷键
 
 | 快捷键 | 功能 |
 |--------|------|
 | `Tab` | 接受补全 |
-| `Cmd+L` | 打开 Chat（选中代码自动带入） |
-| `Cmd+I` | 打开 Composer |
+| `Cmd+I` / `Cmd+L` | 打开/关闭 Agent 侧边栏（选中代码自动带入） |
+| `Shift+Tab` | 在 Agent / Ask / Plan 模式间切换 |
+| `Cmd+E` | 切换 Agent 布局 |
 | `Cmd+K` | 行内编辑（选中代码后） |
-| `Cmd+Shift+L` | 把当前文件加入 Chat 上下文 |
+| `Cmd+Shift+L` | 把选中代码加入 Agent 上下文 |
+
+### 2026 新增
+
+- **Agents Window**（Cursor 3，2026-04-02）：并行运行本地 / worktree / 云端 Agent
+- **Plan 模式**：先出方案再动手
+- **`/loop`**：让 Agent 循环执行任务
+- **云端子 Agent**、**Automations**（自动触发 Agent）
+- **Cursor Router**：Auto 模型路由，可选 Cost / Balance / Intelligence
+- **Bugbot + `/review`**：PR 与本地代码审查
+- **Projects 协调 Agent**：由一个 Agent 统筹多个 Agent 推进项目
+- **iOS App**：在手机上查看和指挥 Agent
 
 ---
 
@@ -176,23 +231,24 @@ npx superpowers-zh
 
 | 陷阱 | 说明 | 解决 |
 |------|------|------|
-| 规则太长 | `.cursorrules` 几千行，AI 记不住 | 拆分到 `.cursor/rules/` 用 globs 按需加载 |
-| Composer 失控 | Agent 模式改了不该改的文件 | 用 `@file` 限定范围，或在 rules 里标明禁区 |
-| 补全太激进 | Tab 补全一次生成太多代码 | 设置里调整补全长度，或按 `Esc` 拒绝 |
-| 上下文不够 | AI 不理解项目结构 | 用 `@folder` 引用关键目录，写好 `.cursorrules` |
+| 规则不生效 | 在 `.cursor/rules/` 里放了 `.md` 文件 | 改成 `.mdc` 并写 frontmatter |
+| 规则太长 | 单个规则几千行，AI 记不住 | 官方建议单条规则 < 500 行，拆成多个 `.mdc` 用 globs 按需加载 |
+| Agent 失控 | Agent 模式改了不该改的文件 | 先用 Plan 模式确认范围，用 `@Files` 限定，或在 rules 里标明禁区 |
+| 补全太激进 | Tab 补全一次生成太多代码 | 按 `Esc` 拒绝；`Cursor Settings → Tab` 里可暂停（snooze）或关闭 |
+| 上下文不够 | AI 不理解项目结构 | 用 `@Folders` 引用关键目录，写好 rules / `AGENTS.md` |
 
-👉 **深度展开版**：[Cursor 陷阱合集](../pitfalls/cursor.md) — 8 个真实踩坑场景（Composer 脱缰 / @file 失效 / Notepads 过期 等），每个带症状 / 根因 / 出坑 / 预防
+👉 **深度展开版**：[Cursor 陷阱合集](../pitfalls/cursor.md) — 8 个真实踩坑场景（Agent 脱缰 / @ 引用失效 / Notepads 迁移 等），每个带症状 / 根因 / 出坑 / 预防
 
 ---
 
 ## 配置模板
 
-直接复制到你的项目 `.cursor/rules/` 目录下：
+复制到你的项目 `.cursor/rules/` 目录下，**并把扩展名改成 `.mdc`**（如 `global.mdc`、`api.mdc`）：
 
 | 模板 | 用途 |
 |------|------|
-| [global.cursorrules.md](templates/global.cursorrules.md) | 全局规则（代码风格、命名、禁止事项） |
-| [api.cursorrules.md](templates/api.cursorrules.md) | API 开发规则（仅在 API 目录下生效） |
+| [global.cursorrules.md](templates/global.cursorrules.md) | 全局规则（代码风格、命名、禁止事项），保存为 `.cursor/rules/global.mdc` |
+| [api.cursorrules.md](templates/api.cursorrules.md) | API 开发规则（仅在 API 目录下生效），保存为 `.cursor/rules/api.mdc` |
 
 ### 模型配置
 
@@ -202,6 +258,7 @@ Cursor 的模型选择在设置界面（`Cursor Settings > Models`）中配置
 
 ## 延伸阅读
 
-- [Cursor 官方文档](https://docs.cursor.com)
+- [Cursor 官方文档](https://cursor.com/docs)
+- [Cursor Rules 文档](https://cursor.com/docs/context/rules)
 - [awesome-cursorrules](https://github.com/PatrickJS/awesome-cursorrules) — 社区 Rules 集合（38k+ star）
 - [superpowers-zh](https://github.com/jnMetaCode/superpowers-zh) — Skills 方法论（也支持 Cursor）
diff --git a/cursor/templates/api.cursorrules.md b/cursor/templates/api.cursorrules.md
index 0e8ca0e..16e3c37 100644
--- a/cursor/templates/api.cursorrules.md
+++ b/cursor/templates/api.cursorrules.md
@@ -1,7 +1,11 @@
 ---
-globs: ["src/app/api/**/*", "src/api/**/*"]
+description: API 开发规则（接口格式、安全、命名）
+globs: src/app/api/**/*,src/api/**/*
+alwaysApply: false
 ---
 
+<!-- 用法：保存为 .cursor/rules/api.mdc（扩展名必须是 .mdc，普通 .md 会被忽略） -->
+
 # API 开发规则
 
 ## 接口规范
diff --git a/cursor/templates/global.cursorrules.md b/cursor/templates/global.cursorrules.md
index c464b39..f70c995 100644
--- a/cursor/templates/global.cursorrules.md
+++ b/cursor/templates/global.cursorrules.md
@@ -1,7 +1,10 @@
 ---
-globs: ["**/*"]
+description: 全局规则（技术栈、代码风格、禁止事项）
+alwaysApply: true
 ---
 
+<!-- 用法：保存为 .cursor/rules/global.mdc（扩展名必须是 .mdc，普通 .md 会被忽略） -->
+
 # 全局规则
 
 ## 技术栈
diff --git a/pitfalls/copilot.en.md b/pitfalls/copilot.en.md
index d5f6285..ab99a66 100644
--- a/pitfalls/copilot.en.md
+++ b/pitfalls/copilot.en.md
@@ -2,7 +2,7 @@
 
 # GitHub Copilot Pitfalls
 
-> Copilot is the oldest AI coding tool and most underestimated — people think "it's just completion," but Agent mode and MCP support are deep. 8 real-world pitfalls.
+> Copilot is the oldest AI coding tool and most underestimated — people think "it's just completion," but Agent mode and MCP support are deep. 8 real-world pitfalls. Last updated: 2026-09.
 >
 > Hit a new one? Open an Issue or PR.
 
@@ -47,34 +47,22 @@ Declare key library versions and API style in `.github/copilot-instructions.md`:
 - Worst: completion suggestions leak real secrets
 
 **Cause**
-Copilot's exclude config isn't on by default. Files in `.gitignore` are still readable. `.env`, `.aws/credentials`, `id_rsa` are all in scope unless explicitly excluded.
+Files in `.gitignore` can still be read by Copilot. GitHub's **content exclusion** can only be configured by admins at the repository / organization / enterprise level, and the official docs state plainly: **agent mode in Copilot Chat in IDEs does not support content exclusion**. So even with exclusions configured, agent mode may still read `.env`, `.aws/credentials`, `id_rsa` and the like.
 
-**Recovery**
-Add excludes to `.vscode/settings.json`:
-
-```json
-{
-  "github.copilot.enable": {
-    "*": true,
-    "env": false,
-    "secrets": false
-  },
-  "github.copilot.advanced": {
-    "exclude": ["**/.env*", "**/secrets/**", "**/*.pem", "**/*.key"]
-  }
-}
-```
+(The widely shared `github.copilot.advanced.exclude` setting is not an official exclusion mechanism — don't rely on it.)
 
-If secrets already hit Chat history: clear Chat (`Ctrl+L` or panel button) **and rotate the affected keys**.
+**Recovery**
+If secrets already hit Chat history: start a new session / clear the current one **and rotate the affected keys immediately**.
 
 **Prevention**
-- Configure excludes at project init, don't wait for an incident
-- Enterprise: use GitHub's Copilot Content Exclusion as org-level backstop
-- Inject sensitive config via `direnv` / `1Password CLI` from outside the project dir
+- **Keep secrets out of the project directory**: inject them via `direnv` / `1Password CLI` from outside, never on disk in the repo
+- Configure content exclusion at repo / org level — it covers completions and regular Chat at least (not agent mode)
+- Pay attention to the agent's confirmation prompts before it reads files or runs commands; don't blanket-approve
+- State "don't read `.env*`, `*.pem`, `*.key`" in instructions — a soft constraint that only lowers the odds
 
 ---
 
-## Pitfall 3: `.github/copilot-instructions.md` Too Long, Silently Ignored
+## Pitfall 3: `.github/copilot-instructions.md` Too Long, Key Points Buried
 
 **Symptom**
 - You wrote 20 rules in instructions
@@ -82,76 +70,85 @@ If secrets already hit Chat history: clear Chat (`Ctrl+L` or panel button) **and
 - Especially in Chat, detail rules barely take effect
 
 **Cause**
-copilot-instructions.md effectiveness drops sharply past ~150 lines. Copilot truncates on context injection; trailing content gets cut.
+The instructions file is injected into context as a whole. The longer and messier it gets, the less weight each rule carries, and rules unrelated to the current task compete for attention.
 
 **Recovery**
 Split by role:
-- Stable core rules → `.github/copilot-instructions.md` (< 100 lines)
-- Scenario rules → `.github/chatModes/*.chatmode.md`
+- Stable core rules → `.github/copilot-instructions.md` (keep it short)
+- Path-scoped rules → `.github/instructions/*.instructions.md` with an `applyTo` glob
 - Specialist personas → `.github/agents/*.agent.md`
+- Full methodologies → Agent Skills (`.github/skills/`)
 
 **Prevention**
 Keep instructions **cross-scenario globals only** (tech stack, naming, forbidden patterns). Scenario-specific rules:
 
 ```
 .github/
-├── copilot-instructions.md     # Core rules
-├── chatModes/
-│   ├── security-review.md      # Security review
-│   └── write-tests.md          # Test writing
+├── copilot-instructions.md          # Core rules
+├── instructions/
+│   ├── python.instructions.md       # applyTo: "**/*.py"
+│   └── tests.instructions.md        # applyTo: "tests/**"
 └── agents/
-    └── migration-helper.md     # Project migration
+    ├── security-reviewer.agent.md   # Security review
+    └── migration-helper.agent.md    # Project migration
 ```
 
 ---
 
-## Pitfall 4: `#file` References Don't Match `@workspace` Finds
+## Pitfall 4: `#file` References Don't Match What the Agent Finds
 
 **Symptom**
 - You say `#file:src/api/user.ts apply this change`
 - Copilot gets it mostly right, but not exactly
-- Another time you `@workspace` for user.ts — it mentions 2 user.ts (project has two same-named files)
+- Another time you just say "change user.ts" — the agent searches on its own and finds 2 user.ts files (the project has two with the same name)
 
 **Cause**
 - `#file` precisely references the path you give
-- `@workspace` makes Copilot search the whole workspace
-- With duplicate filenames, `@workspace` may pick the wrong one
+- Agent mode searches the codebase automatically (`#codebase` forces a semantic search)
+- With duplicate filenames, automatic search may pick the wrong one
 
 **Recovery**
-Explicit path beats fuzzy index:
+Explicit path beats fuzzy search:
 
 ```
-❌ @workspace fix the register method in user.ts
+❌ Fix the register method in user.ts
 ✅ #file:src/api/v2/user.ts fix the register method
 ```
 
 **Prevention**
 - Avoid duplicate filenames in your project (`user.ts` × 3 is a smell)
 - If duplicates must exist, always reference by full path, not filename
-- Use `@workspace` for **discovery** ("is there an X?"), not for **targeting** ("change X")
+- Use automatic search / `#codebase` for **discovery** ("is there an X?"), not for **targeting** ("change X")
 
 ---
 
 ## Pitfall 5: MCP Server Configured But Not Working
 
 **Symptom**
-- You set `github.copilot.chat.mcpServers` in `.vscode/settings.json`
-- Chat doesn't use the MCP tool when it should; takes a different path
+- You configured an MCP server, but Chat doesn't use its tools when it should; takes a different path
 - No error, just silently unused
 
 **Cause**
-Three common reasons:
-1. Startup command wrong (`npx` path, arg order)
-2. MCP server starts but Copilot version doesn't support it (needs recent VS Code + Copilot Chat)
-3. Server starts OK but tool schema is malformed; Copilot can't recognize it
+Four common reasons:
+1. **Wrong config location or format**: VS Code's MCP config lives in `.vscode/mcp.json` with a top-level `servers` key; the old `github.copilot.chat.mcpServers` in `settings.json` is not the current way to configure it
+2. Startup command wrong (`npx` path, arg order)
+3. You're not in agent mode, or the tools aren't enabled in the tools picker
+4. Server starts OK but tool schema is malformed; Copilot can't recognize it
 
 **Recovery**
-```
-# In Chat, ask directly
-What MCP tools can you call right now? List them.
+```jsonc
+// .vscode/mcp.json
+{
+  "servers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
+    }
+  }
+}
 ```
 
-If your configured tools aren't listed → MCP didn't load. Check VS Code Output panel → Copilot Chat for errors.
+Then run **MCP: List Servers** from the Command Palette, pick your server → **Show Output** for logs. When a server fails, the Chat view also shows an error indicator you can click to see the output.
 
 **Prevention**
 - Verify MCP with an official sample server (e.g. `@modelcontextprotocol/server-filesystem`) first
@@ -160,76 +157,84 @@ If your configured tools aren't listed → MCP didn't load. Check VS Code Output
 
 ---
 
-## Pitfall 6: Completion Behaves Differently in JetBrains vs VS Code
+## Pitfall 6: JetBrains and VS Code Features Out of Sync
 
 **Symptom**
-- Your team's VS Code users get noticeably better completions than JetBrains users
-- Same prompt yields different suggestions
-- Shared `.github/copilot-instructions.md` takes full effect in VS Code, partial in JetBrains
+- VS Code users on your team get a new feature that JetBrains users don't have yet
+- The same config behaves a bit differently in the two IDEs
 
 **Cause**
-- VS Code is Copilot's primary target; new features ship there first
-- JetBrains support for instructions, MCP, Agent mode lags behind
-- Underlying models may differ (JetBrains sometimes uses older models)
+- VS Code is usually where new Copilot features ship first
+- The gap has narrowed a lot, though: custom agents, subagents and the plan agent went GA in JetBrains in March 2026, along with AGENTS.md / CLAUDE.md support
+- A few of the newest features may still land in JetBrains a bit later, and outdated plugins make the gap more visible
 
 **Recovery**
-Either standardize IDE team-wide, or accept JetBrains being a step behind.
+Update the Copilot plugin in JetBrains first; if a feature is missing, check the official docs for its IDE support.
 
 **Prevention**
-- Make IDE consistency a hard constraint when adopting AI tools
-- JetBrains users: put **restated core rules at the top** of instructions — even if mid-doc rules don't load, the first few lines do
+- For team-shared rules, prefer formats both IDEs support (`.github/copilot-instructions.md`, `AGENTS.md`, `.agent.md`)
+- Before depending on a new feature, confirm every IDE your team uses supports it
+- Keep plugins up to date
 
 ---
 
-## Pitfall 7: Free Tier Users Hit Hidden Rate Limits
+## Pitfall 7: Running Out of AI Credits / Free Allowance
 
 **Symptom**
-- Copilot Free worked fine; one day completion latency spikes
-- Chat requests queue or get outright rejected ("usage limit reached"-style messages)
-- Completions slow down, fewer suggestions
+- Copilot Free worked fine; one day completions or Chat stop working ("usage limit reached"-style messages)
+- Paid users find agent mode or code review warning about insufficient credits mid-month
+- The notification in VS Code isn't always prominent, so it's easy to miss
 
 **Cause**
-Copilot Free has monthly completion and Chat quotas. As you approach them you get rate-limited; once exceeded, requests are rejected. The notification in VS Code isn't always prominent, so it's easy to miss. Enterprise users may hit org-level quotas similarly.
+Since 2026-06-01 Copilot bills in **GitHub AI Credits**:
+- Chat, agent mode, code review, the cloud agent, Copilot CLI, etc. consume credits (code review also consumes GitHub Actions minutes)
+- Code completions are unlimited on paid plans; Free includes 2,000 completions + a small credit allowance per month
+- Each plan includes a monthly allowance (Pro 1,500 / Pro+ 7,000 / Max 20,000 credits; Business 1,900 and Enterprise 3,900 per user); beyond that you buy more or wait for next month
+- Requests to large, high-reasoning models burn credits faster
 
 **Recovery**
 - GitHub Account → Copilot settings to check usage
-- Near the cap: upgrade to Pro / Pro+ / Business, or lean on another tool for the rest of the month
+- Near the cap: upgrade to Pro / Pro+ / Max, set an additional spending limit, or lean on another tool for the rest of the month
 
 **Prevention**
-- Heavy users: pay for Pro ($10/mo) from day 1, don't try to squeeze Free
-- Teams: align quota and usage strategy with admins
-- Build a "Copilot fallback" plan (switch to Claude Code or Cursor when capped)
+- Heavy users: pay for Pro ($10/mo) or higher from day 1, don't try to squeeze Free
+- Use cheaper models for small everyday tasks; switch to large models for complex work
+- Teams: align allowances and spending limits with admins
+- Build a "Copilot out of credits" fallback plan (switch to Claude Code or Cursor)
 
 ---
 
-## Pitfall 8: Custom Chat Mode / Agent Not Discovered
+## Pitfall 8: Custom Agent Not Discovered
 
 **Symptom**
-- You wrote a specialist in `.github/chatModes/security-review.md`
-- Type `@security-review` in Chat — Copilot doesn't recognize it
-- Or it recognizes it but behaves like plain Chat
+- You wrote a specialist role file and typed `@security-review` in Chat — Copilot doesn't recognize it
+- Or it doesn't show up in the Agent dropdown at all
+- Or you selected it but it behaves like plain Chat
 
 **Cause**
-- Filename and frontmatter `name` don't match
-- Missing frontmatter or missing fields
-- VS Code / Copilot version too old to support custom Chat Mode
+- **Wrong invocation**: custom agents aren't invoked with `@name` — pick them from the **Agent dropdown** in the Chat view, or type `/agents` in the chat input to open the list
+- **Still on the old format**: Chat Modes (`.github/chatModes/*.chatmode.md`) are deprecated; they're now called custom agents
+- **Wrong location or extension**: must be `*.agent.md` under `.github/agents/` (`.claude/agents/` also works)
+- Missing frontmatter, or `user-invocable: false` is set (hides it from the dropdown)
 
 **Recovery**
-Verify required frontmatter:
+Rename/move the file to `.github/agents/security-review.agent.md` and check the frontmatter:
 
 ```markdown
 ---
-name: security-review       # Matches filename
+name: security-review
 description: Security review using OWASP Top 10
 ---
 
 # Role content below
 ```
 
+Then pick it from the Agent dropdown.
+
 **Prevention**
-- Start from an official sample Chat Mode file, modify from there
-- Restart VS Code (not just Copilot) after edits
-- `.github/chatModes/*.md` path is fixed — don't put it elsewhere
+- Generate the file with **Chat: New Custom Agent** from the Command Palette and edit from there, rather than writing from scratch
+- Rename old `.chatmode.md` files to `.agent.md` and move them into `.github/agents/`
+- Add `tools` in frontmatter to restrict tools, or `model` to pin a model
 
 ---
 
diff --git a/pitfalls/copilot.md b/pitfalls/copilot.md
index 7a0c305..5664685 100644
--- a/pitfalls/copilot.md
+++ b/pitfalls/copilot.md
@@ -1,6 +1,6 @@
 # GitHub Copilot 陷阱合集
 
-> Copilot 是最老牌的 AI 编程工具，也最容易被低估——以为就是补全，结果 Agent 模式和 MCP 支持都挺深。8 个常见坑。
+> Copilot 是最老牌的 AI 编程工具，也最容易被低估——以为就是补全，结果 Agent 模式和 MCP 支持都挺深。8 个常见坑。信息更新于 2026-09。
 >
 > 踩过新坑？提 Issue 或 PR。
 
@@ -37,7 +37,7 @@ import { useQuery } from '@tanstack/react-query';
 
 ---
 
-## 陷阱 2：Agent 模式改了 `.env` 或敏感文件
+## 陷阱 2：Agent 模式读了 `.env` 或敏感文件
 
 **症状**
 - 让 Copilot Agent 改个配置，它顺手扫了 `.env` 把 key 读进上下文
@@ -45,34 +45,22 @@ import { useQuery } from '@tanstack/react-query';
 - 最坏：补全建议里带出了真实的 secret
 
 **根因**
-Copilot 的 exclude 配置不是默认启用的。`.gitignore` 里的文件 Copilot 依然会读。`.env`、`.aws/credentials`、`id_rsa` 这类敏感文件如果不显式排除，都在它的感知范围。
+`.gitignore` 里的文件 Copilot 依然可能读到。GitHub 提供的 **Content Exclusion（内容排除）** 只能在仓库 / 组织 / 企业级由管理员配置，而且官方文档明确写着：**IDE 里 Copilot Chat 的 Agent 模式不支持内容排除**。也就是说，即使配了排除规则，Agent 模式照样可能读到 `.env`、`.aws/credentials`、`id_rsa` 这类文件。
 
-**出坑**
-立刻在 `.vscode/settings.json` 加排除：
-
-```json
-{
-  "github.copilot.enable": {
-    "*": true,
-    "env": false,
-    "secrets": false
-  },
-  "github.copilot.advanced": {
-    "exclude": ["**/.env*", "**/secrets/**", "**/*.pem", "**/*.key"]
-  }
-}
-```
+（早期流传的 `github.copilot.advanced.exclude` 设置并不是官方的排除机制，别指望它。）
 
-如果敏感信息已经进了 Chat 历史：清空 Chat（`Ctrl+L` 或面板里清除），**并轮换相关密钥**。
+**出坑**
+如果敏感信息已经进了 Chat 历史：开一个新会话 / 清空当前会话，**并立即轮换相关密钥**。
 
 **预防**
-- 项目初始化就配好 exclude，不要等出事
-- 用 GitHub 的 Copilot Content Exclusion（企业版）做组织级兜底
-- 敏感配置用 `direnv` / `1Password CLI` 等从非项目目录注入，不落地
+- **敏感信息别放在项目目录里**：用 `direnv` / `1Password CLI` 等从项目外注入，不落地
+- 仓库 / 组织层面配好 Content Exclusion，至少能覆盖补全和普通 Chat（对 Agent 模式无效）
+- Agent 执行读文件、跑命令前留意确认提示，别无脑全部批准
+- 在 instructions 里写明"不要读取 `.env*`、`*.pem`、`*.key`"——这是软约束，只能降低概率
 
 ---
 
-## 陷阱 3：`.github/copilot-instructions.md` 太长被忽略
+## 陷阱 3：`.github/copilot-instructions.md` 太长，重点被淹没
 
 **症状**
 - 你在 instructions 里写了 20 条规则
@@ -80,76 +68,85 @@ Copilot 的 exclude 配置不是默认启用的。`.gitignore` 里的文件 Copi
 - 尤其 Chat 窗口里提问时，细节规则几乎不生效
 
 **根因**
-copilot-instructions.md 超过 ~150 行时效果显著下降。Copilot 在注入上下文时会做截断，靠后的内容被牺牲。
+instructions 会整体注入上下文，写得越长、越杂，每条规则的"分量"越低；和当前任务无关的规则还会挤占注意力。
 
 **出坑**
 拆文件：
-- 核心不变规则 → `.github/copilot-instructions.md`（< 100 行）
-- 场景化规则 → `.github/chatModes/` 下各自的 `.chatmode.md`
+- 核心不变规则 → `.github/copilot-instructions.md`（尽量短）
+- 按路径生效的规则 → `.github/instructions/*.instructions.md`，用 `applyTo` 指定 glob
 - 专项角色 → `.github/agents/` 下各自的 `.agent.md`
+- 成套方法论 → Agent Skills（`.github/skills/`）
 
 **预防**
 Instructions 里**只放跨场景的全局规则**（技术栈、命名、禁止事项）。具体场景规则：
 
 ```
 .github/
-├── copilot-instructions.md     # 核心规则
-├── chatModes/
-│   ├── security-review.md      # 安全审查专用
-│   └── write-tests.md          # 写测试专用
+├── copilot-instructions.md          # 核心规则
+├── instructions/
+│   ├── python.instructions.md       # applyTo: "**/*.py"
+│   └── tests.instructions.md        # applyTo: "tests/**"
 └── agents/
-    └── migration-helper.md     # 迁移项目专用
+    ├── security-reviewer.agent.md   # 安全审查专用
+    └── migration-helper.agent.md    # 迁移项目专用
 ```
 
 ---
 
-## 陷阱 4：`#file` 引用的 vs `@workspace` 找到的不一致
+## 陷阱 4：`#file` 引用的 vs Agent 自己搜到的不一致
 
 **症状**
 - 你说 `#file:src/api/user.ts 按这个改`
 - Copilot 改得基本对，但不完全
-- 另一次你用 `@workspace` 让它找 user.ts，它提到了 2 个 user.ts（项目有两处重名）
+- 另一次你只说"改一下 user.ts"，Agent 自己搜索，找到了 2 个 user.ts（项目有两处重名）
 
 **根因**
 - `#file` 精确引用你给的路径
-- `@workspace` 会让 Copilot 自主搜索整个工作区
-- 项目里有重名文件时，`@workspace` 可能选错那个
+- Agent 模式会自动搜索整个代码库（`#codebase` 可以强制做一次语义搜索）
+- 项目里有重名文件时，自动搜索可能选错那个
 
 **出坑**
-明确路径 > 模糊索引：
+明确路径 > 模糊搜索：
 
 ```
-❌ @workspace 改一下 user.ts 的 register 方法
+❌ 改一下 user.ts 的 register 方法
 ✅ #file:src/api/v2/user.ts 改一下这里的 register 方法
 ```
 
 **预防**
 - 项目里避免重名文件（`user.ts` × 3 这种结构重构一下）
 - 如果必须重名，引用时用完整路径而非文件名
-- `@workspace` 只用于**探索**（"项目里有没有 XX"），不用于**指向**（"改 XX"）
+- 自动搜索 / `#codebase` 只用于**探索**（"项目里有没有 XX"），不用于**指向**（"改 XX"）
 
 ---
 
 ## 陷阱 5：MCP Server 配置了但没生效
 
 **症状**
-- 在 `.vscode/settings.json` 配了 `github.copilot.chat.mcpServers`
-- Chat 里该用 MCP 工具时它没用，走了别的路径
+- 配了 MCP server，Chat 里该用 MCP 工具时它没用，走了别的路径
 - 不报错，就是悄悄没用
 
 **根因**
-常见三种：
-1. MCP server 启动命令写错（`npx` 路径、参数顺序）
-2. MCP server 启动了但 Copilot 版本不支持（需要较新 VS Code + Copilot Chat）
-3. server 启动成功但工具 schema 定义有问题，Copilot 认不出
+常见四种：
+1. **配置位置或格式不对**：VS Code 的 MCP 配置在 `.vscode/mcp.json`，顶层键是 `servers`；写在 `settings.json` 里的旧 `github.copilot.chat.mcpServers` 不是当前的配置方式
+2. MCP server 启动命令写错（`npx` 路径、参数顺序）
+3. 当前不在 Agent 模式，或工具没在工具列表里勾选
+4. server 启动成功但工具 schema 定义有问题，Copilot 认不出
 
 **出坑**
-```
-# 在 Chat 里直接问
-你当前可以调用哪些 MCP 工具？列出来。
+```jsonc
+// .vscode/mcp.json
+{
+  "servers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
+    }
+  }
+}
 ```
 
-如果它列不出你配的工具 → MCP 没加载。看 VS Code 的 Output 面板 → Copilot Chat，找错误日志。
+然后命令面板运行 **MCP: List Servers**，选中你的 server → **Show Output** 看日志。Chat 视图里 MCP 出错时也会显示错误标记，点开可以直接看输出。
 
 **预防**
 - 先用官方示例 server（比如 `@modelcontextprotocol/server-filesystem`）验证 MCP 能接通
@@ -158,76 +155,84 @@ Instructions 里**只放跨场景的全局规则**（技术栈、命名、禁止
 
 ---
 
-## 陷阱 6：补全在 JetBrains 和 VS Code 行为不一致
+## 陷阱 6：JetBrains 和 VS Code 功能不同步
 
 **症状**
-- 团队里 VS Code 用户的补全质量明显比 JetBrains 用户好
-- 同一个 prompt 给的建议不一样
-- 共享 `.github/copilot-instructions.md` 后，VS Code 生效，JetBrains 部分生效
+- 团队里 VS Code 用户用上了某个新功能，JetBrains 用户那边还没有
+- 同一份配置在两边表现有差异
 
 **根因**
-- VS Code 是 Copilot 的主战场，新功能优先 ship
-- JetBrains 插件的 instructions 支持、MCP 支持、Agent 模式都滞后
-- 底层模型也可能不一样（JetBrains 插件有时用老模型）
+- VS Code 通常是 Copilot 新功能最先上线的地方
+- 不过差距已经明显缩小：JetBrains 的自定义 Agent、子 Agent、Plan Agent 已于 2026 年 3 月 GA，也支持 AGENTS.md / CLAUDE.md
+- 个别最新功能在 JetBrains 上仍可能晚一步，插件版本旧时差异更明显
 
 **出坑**
-要么全团队统一 IDE，要么接受 JetBrains 体验差一截。
+先把 JetBrains 的 Copilot 插件升到最新；遇到某个功能缺失，查一下官方文档里该功能的 IDE 支持情况。
 
 **预防**
-- 团队 AI 工具选型时，把 IDE 一致性当硬约束
-- JetBrains 用户补 instructions 时，在文件开头加上**复述式核心规则**（即使 instructions 不生效，开头几行总会被注入）
+- 团队共享的规则优先用两边都支持的格式（`.github/copilot-instructions.md`、`AGENTS.md`、`.agent.md`）
+- 依赖某个新功能前，先确认团队用的所有 IDE 都支持
+- 插件保持最新版
 
 ---
 
-## 陷阱 7：免费用户遇到隐形限流
+## 陷阱 7：AI Credits 用完 / 免费额度耗尽
 
 **症状**
-- 免费额度（Copilot Free）用得好好的，某天开始补全延迟暴涨
-- Chat 请求经常排队或直接拒绝（"已达使用上限"之类的提示）
-- 补全变慢、建议数量减少
+- Copilot Free 用得好好的，某天补全或 Chat 突然不能用了（"已达使用上限"之类的提示）
+- 付费用户月中发现 Agent 模式、代码审查开始提示额度不足
+- VS Code 里提示不一定醒目，容易忽略
 
 **根因**
-Copilot Free 有每月补全数和 Chat 次数上限。接近上限时会排队/限速，超出后直接拒绝请求。VS Code 里提示不一定醒目，容易忽略。企业版用户也可能遇到组织级配额。
+2026-06-01 起 Copilot 按 **GitHub AI Credits** 计费：
+- Chat、Agent 模式、代码审查、云端 Agent、Copilot CLI 等都消耗 Credits（代码审查还会消耗 GitHub Actions 分钟数）
+- 代码补全在付费套餐中不限量；Free 每月 2,000 次补全 + 少量 Credits
+- 每个套餐每月有包含额度（Pro 1,500 / Pro+ 7,000 / Max 20,000 Credits；Business 每人 1,900、Enterprise 每人 3,900），用完需要额外购买或等下个月
+- 高推理、大模型的请求消耗更快
 
 **出坑**
 - 在 GitHub 账户 → Copilot 设置页查看用量
-- 用量接近上限：升级 Pro / Pro+ / Business，或当月剩余时间依赖其他工具
+- 用量接近上限：升级 Pro / Pro+ / Max，设置额外支出上限，或当月剩余时间依赖其他工具
 
 **预防**
-- 高频使用者直接上 Pro（$10/月），别在 Free 上省
-- 团队用户和管理员对齐配额和使用策略
-- 建立"Copilot 挂了用谁"的 fallback（比如切 Claude Code 或 Cursor）
+- 高频使用者直接上 Pro（$10/月）或更高档，别在 Free 上省
+- 日常小任务用消耗低的模型，复杂任务再切大模型
+- 团队用户和管理员对齐额度和支出上限
+- 建立"Copilot 额度用完用谁"的 fallback（比如切 Claude Code 或 Cursor）
 
 ---
 
-## 陷阱 8：自定义 Chat Mode / Agent 不被发现
+## 陷阱 8：自定义 Agent 不被发现
 
 **症状**
-- 你在 `.github/chatModes/security-review.md` 写了个专家角色
-- 在 Chat 里输入 `@security-review`，Copilot 不识别
-- 或者识别了但行为和普通 Chat 没区别
+- 你写了个专家角色文件，在 Chat 里输入 `@security-review`，Copilot 不识别
+- 或者 Agent 下拉框里根本找不到它
+- 或者选中了但行为和普通 Chat 没区别
 
 **根因**
-- 文件名和 frontmatter 里的 `name` 字段不匹配
-- 没有 frontmatter 或字段缺失
-- VS Code / Copilot 版本太旧不支持自定义 Chat Mode
+- **调用方式不对**：自定义 Agent 不是用 `@名字` 调用的，要在 Chat 视图的 **Agent 下拉框**里选，或在输入框输入 `/agents` 打开列表
+- **还在用旧格式**：Chat Modes（`.github/chatModes/*.chatmode.md`）已弃用，现在叫自定义 Agent
+- **位置或扩展名不对**：必须是 `.github/agents/` 下的 `*.agent.md`（也支持 `.claude/agents/`）
+- frontmatter 缺失，或设置了 `user-invocable: false`（不在下拉框中显示）
 
 **出坑**
-检查 frontmatter 必备字段：
+把文件改名/移动到 `.github/agents/security-review.agent.md`，检查 frontmatter：
 
 ```markdown
 ---
-name: security-review       # 和文件名一致
+name: security-review
 description: Security review using OWASP Top 10
 ---
 
 # 后面是角色内容
 ```
 
+然后在 Agent 下拉框里选中它。
+
 **预防**
-- 拷一个官方示例 Chat Mode 文件，基于它改，别从零写
-- 改完重启 VS Code（不是重启 Copilot）
-- `.github/chatModes/*.md` 路径固定，别放错目录
+- 用命令面板的 **Chat: New Custom Agent** 生成文件，基于它改，别从零写
+- 老项目的 `.chatmode.md` 统一改名为 `.agent.md` 并挪到 `.github/agents/`
+- 需要工具限制时在 frontmatter 里写 `tools`，需要固定模型时写 `model`
 
 ---
 
diff --git a/pitfalls/cursor.en.md b/pitfalls/cursor.en.md
index 5eb30ab..8e918fb 100644
--- a/pitfalls/cursor.en.md
+++ b/pitfalls/cursor.en.md
@@ -4,19 +4,21 @@
 
 > Cursor is powerful but has its own traps. 8 real-world pitfalls, each with Symptom / Cause / Recovery / Prevention.
 >
+> Note: the old Composer panel is now the **Agent panel** (Agent / Ask / Plan modes); "Composer" is now the name of Cursor's own model. Last updated: 2026-09.
+>
 > Hit a new one? Open an Issue or PR.
 
 ---
 
-## Pitfall 1: Composer Goes Rogue — Edits Files You Didn't Touch
+## Pitfall 1: Agent Goes Rogue — Edits Files You Didn't Touch
 
 **Symptom**
-- You Composer-edit one feature; the diff spans 6 files
+- You ask the Agent to change one feature; the diff spans 6 files
 - Some of those files you never opened; it found them across directories and edited them
 - Worst case: it "refactored" something in `src/utils/` and broke an unrelated feature
 
 **Cause**
-Composer is agent mode with cross-file edit permission by default. It searches related files and decides "these need changing too." Without explicit boundaries, it defines "related."
+Agent mode has cross-file edit permission by default. It searches related files and decides "these need changing too." Without explicit boundaries, it defines "related."
 
 **Recovery**
 ```
@@ -25,19 +27,19 @@ Keep only the changes in @src/pages/order/list.tsx.
 ```
 
 **Prevention**
-Set the scope explicitly in the Composer prompt:
+For big changes, switch to **Plan mode** (`Shift+Tab`) first so it lists the files it intends to touch, then execute. Set the scope explicitly in the prompt:
 
 ```
-Use Composer. Only these two files:
+Only these two files:
 @src/pages/order/list.tsx @src/pages/order/detail.tsx
 
 If other files need changes to complete this, tell me first.
 ```
 
-Or codify in `.cursor/rules/`:
+Or codify it in `.cursor/rules/boundaries.mdc` (`alwaysApply: true`):
 
 ```markdown
-## Composer boundaries
+## Agent boundaries
 - Unless I @ the file, don't modify it
 - src/utils/ and src/types/ are shared code — notify before editing
 ```
@@ -59,7 +61,7 @@ Cursor's Tab completion predicts "the next full chunk," not single-line completi
 - Accepted something bad: `Cmd+Z` to undo, or `Cmd+K` the selection: "what's wrong with this?"
 
 **Prevention**
-- Cursor Settings → Features → shorten completion length (or disable `Auto` and require manual trigger)
+- If it's too distracting, snooze or disable Tab in `Cursor Settings → Tab`
 - Write **function signature and types first**, then let it complete — fuller signature → better completion
 - Comment the intent before waiting for completion:
 
@@ -72,32 +74,36 @@ function countBusinessDays(start: Date, end: Date): number {
 
 ---
 
-## Pitfall 3: `.cursorrules` Too Long, Rules Silently Dropped
+## Pitfall 3: Lots of Rules, None of Them Applied
 
 **Symptom**
-- You spend half a day writing 300 lines of `.cursorrules`
+- You spend half a day writing 300 lines of `.cursorrules`, or drop a pile of `.md` files into `.cursor/rules/`
 - In practice, the AI ignores half of them
 - New rules feel like "shouting into a void"
 
 **Cause**
-Single-file `.cursorrules` beyond ~200 lines gets marginalized. Cursor auto-summarizes long docs and drops trailing detail.
+Two common reasons:
+1. **Wrong file format**: rules in `.cursor/rules/` must be `.mdc`; a plain `.md` file has no frontmatter and is ignored by the rules system. A root `.cursorrules` file is legacy, kept only for compatibility
+2. **A single rule is too long**: hundreds of lines bury the important parts — official advice is to keep each rule under 500 lines
 
 **Recovery**
-Split into `.cursor/rules/` (the **directory**, not the single file):
+Split into `.cursor/rules/` (the **directory**, with `.mdc` files):
 
 ```
 .cursor/rules/
-├── global.md           # Always-loaded core rules (< 100 lines)
-├── react.md            # Loads only for .tsx files
-├── api.md              # Loads only under src/api/
-└── testing.md          # Loads only for *.test.ts
+├── global.mdc          # Core rules with alwaysApply: true
+├── react.mdc           # Loads when globs match .tsx files
+├── api.mdc             # Loads when globs match src/api/
+└── testing.mdc         # Loads when globs match *.test.ts
 ```
 
 Add frontmatter for conditional loading:
 
 ```markdown
 ---
-globs: ["src/components/**/*.tsx"]
+description: React component rules
+globs: src/components/**/*.tsx
+alwaysApply: false
 ---
 
 # React component rules
@@ -106,13 +112,13 @@ globs: ["src/components/**/*.tsx"]
 ```
 
 **Prevention**
-- **Start new projects with `.cursor/rules/` directory**, skip `.cursorrules` entirely
-- Keep each rule file under 100 lines
-- Context-specific rules go in Notepads, referenced on demand
+- **Start new projects with `.cursor/rules/*.mdc`**, skip `.cursorrules` entirely; to share rules across tools, use `AGENTS.md`
+- Keep each rule focused on one topic, short and specific
+- Very specific, situational rules → make them manual (no `globs`, `alwaysApply: false`) and @ them when needed; full methodologies → Skills (`.cursor/skills/`)
 
 ---
 
-## Pitfall 4: `@file` Reference Doesn't Actually Load
+## Pitfall 4: @ Reference Doesn't Actually Load
 
 **Symptom**
 - You say `@src/types/user.ts fix the API to match this type`
@@ -120,10 +126,10 @@ globs: ["src/components/**/*.tsx"]
 - Looking closely: it never actually read the file
 
 **Cause**
-Three common reasons:
-1. Path is wrong (case / relative vs absolute)
-2. File is huge and got truncated (read only the first N lines)
-3. You edited but haven't saved (Cursor reads the disk version)
+Common reasons:
+1. Path is wrong (case / picked the wrong same-named file)
+2. The file is large and the Agent only read part of it
+3. You edited but haven't saved
 
 **Recovery**
 ```
@@ -134,57 +140,55 @@ List them so I can verify, then start the refactor.
 Make the AI recite the file contents first to confirm the reference worked.
 
 **Prevention**
-- For big files, `@folder` the directory and let it find the right file — more robust than exact path
+- Pick files from the @ popup instead of typing paths by hand
 - **Save (Cmd+S) before @ referencing** changed files
-- For huge files (>1000 lines), reference by line range: `@src/models/big.ts:50-120`
+- For huge files, name the specific function / class in your prompt so it locates and reads that section
 
 ---
 
-## Pitfall 5: Chat vs Composer Confusion Kills Productivity
+## Pitfall 5: Mixing Up Agent / Ask / Inline Edit Kills Productivity
 
 **Symptom**
-- In Chat: you ask "refactor this module" — it just suggests, doesn't edit code
-- In Composer: you ask "how does this work?" — it doesn't explain, just starts editing
+- In Ask mode: you say "refactor this module" — it just suggests, doesn't edit code
+- In Agent mode: you ask "how does this work?" — it answers and starts editing too
 - You keep switching and always pick wrong
 
 **Cause**
-- **Chat (`Cmd+L`)**: Q&A mode, no auto-edits
-- **Composer (`Cmd+I`)**: Agent mode, prioritizes code changes
-- **Inline (`Cmd+K`)**: inline edit, selection only
+- **Agent mode**: edits code and runs commands autonomously
+- **Ask mode**: read-only Q&A, no edits
+- **Plan mode**: drafts a plan first, executes after you approve
+- **Inline edit (`Cmd+K`)**: edits the selection only
 
-Three modes, three hotkeys — easy to mix up early.
+In the Agent panel (`Cmd+I` / `Cmd+L`), `Shift+Tab` cycles modes — easy to lose track of which one you're in.
 
 **Recovery**
-Wrong mode: copy the prompt, close the panel, open the right mode, paste.
+Wrong mode: `Shift+Tab` to the right one and resend.
 
 **Prevention**
-Memorize the hotkey ↔ purpose mapping:
+Memorize the purpose ↔ entry mapping:
 
-| Intent | Mode | Hotkey |
-|--------|------|--------|
-| Ask a question, understand code | Chat | `Cmd+L` |
-| Edit a selection | Inline | `Cmd+K` |
-| Multi-file changes | Composer | `Cmd+I` |
+| Intent | Use | Entry |
+|--------|-----|-------|
+| Ask a question, understand code | Ask mode | Agent panel + `Shift+Tab` |
+| Edit a selection | Inline edit | `Cmd+K` |
+| Multi-file changes | Plan → Agent mode | Agent panel + `Shift+Tab` |
 
 ---
 
 ## Pitfall 6: Model Switching Breaks Style Consistency
 
 **Symptom**
-- You alternate between Claude 3.5 and cursor-small
+- You alternate between Claude and Composer or GPT
 - Code style in the same project splits: some files strict types, others sloppy `any`
 - You don't even notice it's the model switch
 
 **Cause**
-Cursor supports multiple models with different default styles:
-- Claude Sonnet: strict, adds types and error handling
-- GPT-4: terse, minimal comments
-- cursor-small: fast, cuts corners on complex tasks
+Cursor supports many models (Composer 2.5, Claude, GPT-5.x, Gemini, Grok, etc.) with different default styles: some lean strict, adding types and error handling; others lean terse with minimal comments.
 
-`Auto` mode (system picks per task) hides this drift.
+With Auto (Cursor Router), requests are routed based on your Cost / Balance / Intelligence preference, so the model can differ from request to request — which hides this drift.
 
 **Recovery**
-Push style into `.cursor/rules/global.md` so it applies regardless of model:
+Push style into `.cursor/rules/global.mdc` (`alwaysApply: true`) so it applies regardless of model:
 
 ```markdown
 # Cross-model style
@@ -194,30 +198,31 @@ Push style into `.cursor/rules/global.md` so it applies regardless of model:
 ```
 
 **Prevention**
-- **One project, one primary model**, locked in settings
-- Switch explicitly per task ("use Opus for this deep refactor")
-- Don't rely on `auto`
+- Enforce style with **rules + linters/formatters**, not by pinning a model
+- With Auto, pick the preference per task: Cost / Balance for small everyday edits, Intelligence (or a manually chosen top model) for complex refactors
+- For big tasks where consistency matters, pin one model manually from start to finish
 
 ---
 
-## Pitfall 7: Notepads Become Stale Context
+## Pitfall 7: Still Looking for Notepads — Old Context Never Migrated
 
 **Symptom**
-- A Notepad from six months ago has outdated info (old API design, deprecated style)
-- The AI references it in a new chat and gives outdated advice
-- You don't remember creating that Notepad
+- After upgrading, the Notepads panel is gone, and your saved API spec and conventions "disappeared"
+- Or stale snippets (old API design, deprecated style) are still around and the AI gives outdated advice from them
 
 **Cause**
-Notepads are **manually managed** context. Cursor never auto-updates them. Over months, Notepads drift from real code.
+Notepads were deprecated in October 2025 and removed in Cursor 2.0. They were **manually managed** context that never auto-updated, so they drifted from real code over time anyway.
 
 **Recovery**
-- Periodically prune: if the AI suggests something weird, suspect Notepad pollution — check the Notepad panel
-- Delete or update stale entries immediately
+Move what's still useful to the current mechanisms:
+- Stable conventions (API response shape, auth flow) → `.cursor/rules/*.mdc`, set to manual, referenced with `@rule-name`
+- Full methodologies / procedures → Skills (`.cursor/skills/`)
+- Volatile things (current feature) → don't store them; reference live code with `@Files` / `@Folders`
+- Delete stale content while migrating
 
 **Prevention**
-- Notepads = **stable conventions only** (API response shape, auth flow — rarely changing)
-- Volatile things (current feature, temporary plan) → reference live code via `@folder`
-- Date your Notepads: review everything older than N months
+- Keep rule files in Git so they're reviewed and evolve with the code
+- State each rule's scope and review periodically: "look over every rule untouched for six months"
 
 ---
 
@@ -225,18 +230,18 @@ Notepads are **manually managed** context. Cursor never auto-updates them. Over
 
 **Symptom**
 - You renamed or deleted a file
-- Chat still `@`-references it with old contents
+- `@` still references it with old contents
 - AI suggests changes based on the old file; you apply them; compile fails ("file not found")
 
 **Cause**
-Cursor's codebase index doesn't update in real time. After deletions/renames, the in-memory index holds old entries for a while.
+Cursor's codebase index doesn't update in real time. After deletions/renames, the index may hold old entries for a while.
 
 **Recovery**
-Command Palette (`Cmd+Shift+P`) → `Cursor: Resync Index`
+- Check the index status in Cursor Settings' indexing section and resync manually if needed (exact entry point depends on your version)
+- Or have the Agent confirm the file exists via search / terminal before continuing
 
 **Prevention**
-- After large renames/deletions, resync manually
-- If you branch-switch a lot, resync after each switch
+- After large renames/deletions, make sure the index has caught up before relying on @ references
 - If `@` references behave weirdly, check the index first — don't blame the AI
 
 ---
diff --git a/pitfalls/cursor.md b/pitfalls/cursor.md
index 8db0c48..0590403 100644
--- a/pitfalls/cursor.md
+++ b/pitfalls/cursor.md
@@ -2,19 +2,21 @@
 
 > Cursor 用过的都知道，它强但也有独特的坑。8 个真实踩坑场景，症状 / 根因 / 出坑 / 预防 四段式展开。
 >
+> 说明：旧版的 Composer 面板现在叫 **Agent 面板**（Agent / Ask / Plan 三种模式），"Composer" 现在是 Cursor 自研模型的名字。信息更新于 2026-09。
+>
 > 踩过新坑？提 Issue 或 PR。
 
 ---
 
-## 陷阱 1：Composer 脱缰 — 动了你没让它动的文件
+## 陷阱 1：Agent 脱缰 — 动了你没让它动的文件
 
 **症状**
-- 用 Composer 改一个功能，结果 diff 涉及 6 个文件
+- 用 Agent 改一个功能，结果 diff 涉及 6 个文件
 - 有些文件你都没打开过，它跨目录找到然后顺手改了
 - 最糟：它"重构"了 `src/utils/` 某个公共工具，破坏了别的功能
 
 **根因**
-Composer 是 Agent 模式，默认有权限跨文件修改。它会自己搜索相关文件、自己决定"这个也得改"。没有显式边界时，"相关"的定义由它说了算。
+Agent 模式默认有权限跨文件修改。它会自己搜索相关文件、自己决定"这个也得改"。没有显式边界时，"相关"的定义由它说了算。
 
 **出坑**
 ```
@@ -23,19 +25,19 @@ Composer 是 Agent 模式，默认有权限跨文件修改。它会自己搜索
 ```
 
 **预防**
-Composer 提示词里**显式圈定范围**：
+大改动先切到 **Plan 模式**（`Shift+Tab`）让它列出要改的文件，确认后再执行。提示词里**显式圈定范围**：
 
 ```
-用 Composer。只改这两个文件：
+只改这两个文件：
 @src/pages/order/list.tsx @src/pages/order/detail.tsx
 
 如果需要改其他文件才能完成，先告诉我，让我决定。
 ```
 
-或者在 `.cursor/rules/` 里加：
+或者在 `.cursor/rules/boundaries.mdc` 里加（`alwaysApply: true`）：
 
 ```markdown
-## Composer 边界
+## Agent 边界
 - 除非我 @ 引用了某文件，不要修改它
 - src/utils/ src/types/ 目录属于公共代码，改动前必须告知
 ```
@@ -57,7 +59,7 @@ Cursor 的 Tab 补全会预测"你接下来想写的一整段"，不是单行补
 - 已经接受了不对：`Cmd+Z` 撤销，或用 `Cmd+K` 选中这段问"这段有什么问题"
 
 **预防**
-- Cursor Settings → Features → 调低补全长度（或关闭 `Auto` 模式改成只补全当前行）
+- 干扰太多时在 `Cursor Settings → Tab` 里暂时 snooze 或关闭 Tab 补全
 - 写**函数签名和类型**再等补全——签名越完整，补全越准（反之越瞎猜）
 - 重要逻辑块先写一行注释再等补全：
 
@@ -70,32 +72,36 @@ function countBusinessDays(start: Date, end: Date): number {
 
 ---
 
-## 陷阱 3：`.cursorrules` 太长，规则全没生效
+## 陷阱 3：规则写了一大堆，却没生效
 
 **症状**
-- 花半天写了 300 行 `.cursorrules`，覆盖各种场景
+- 花半天写了 300 行 `.cursorrules`，或者在 `.cursor/rules/` 下放了一堆 `.md` 文件
 - 实际用起来：AI 该违反的还是违反，感觉根本没读
 - 新加的规则像"扔进黑洞"
 
 **根因**
-`.cursorrules` 单文件超过 ~200 行时，靠后的规则被边缘化——Cursor 会对长文件做"摘要注入"，细节条款被丢弃。
+常见两种：
+1. **文件格式不对**：`.cursor/rules/` 下的规则必须是 `.mdc`，普通 `.md` 没有 frontmatter，会被规则系统直接忽略；根目录 `.cursorrules` 是旧格式，仅作兼容
+2. **单条规则太长**：几百行混在一起，重点被淹没，官方建议每条规则控制在 500 行以内
 
 **出坑**
-拆到 `.cursor/rules/`（注意是目录，不是单文件）：
+拆到 `.cursor/rules/`（注意是目录，扩展名 `.mdc`）：
 
 ```
 .cursor/rules/
-├── global.md           # 无条件加载的核心规则（< 100 行）
-├── react.md            # 仅 .tsx 文件触发
-├── api.md              # 仅 src/api/ 下触发
-└── testing.md          # 仅 *.test.ts 触发
+├── global.mdc          # alwaysApply: true 的核心规则
+├── react.mdc           # globs 匹配 .tsx 时加载
+├── api.mdc             # globs 匹配 src/api/ 时加载
+└── testing.mdc         # globs 匹配 *.test.ts 时加载
 ```
 
 每个文件加 frontmatter 控制加载：
 
 ```markdown
 ---
-globs: ["src/components/**/*.tsx"]
+description: React 组件规则
+globs: src/components/**/*.tsx
+alwaysApply: false
 ---
 
 # React 组件规则
@@ -104,13 +110,13 @@ globs: ["src/components/**/*.tsx"]
 ```
 
 **预防**
-- 新项目**一开始就用 `.cursor/rules/` 目录**，别用单文件 `.cursorrules`
-- 每个规则文件控制在 100 行内
-- 规则太具体、太场景化的，放 Notepad，用到再 @ 引用
+- 新项目**一开始就用 `.cursor/rules/*.mdc`**，别用单文件 `.cursorrules`；想跨工具共用，可以写 `AGENTS.md`
+- 每条规则聚焦一个主题，写得短而具体
+- 太具体、太场景化的规则设成手动触发（不写 `globs`、`alwaysApply: false`），用到再 @ 引用；成套的方法论做成 Skill（`.cursor/skills/`）
 
 ---
 
-## 陷阱 4：`@file` 引用失效 — 上下文没真传进去
+## 陷阱 4：@ 引用没真传进去
 
 **症状**
 - 你说 `@src/types/user.ts 按这个类型改接口`
@@ -118,10 +124,10 @@ globs: ["src/components/**/*.tsx"]
 - 仔细看会发现：它根本没读那个文件
 
 **根因**
-常见原因三种：
-1. 路径错了（大小写 / 相对绝对）
-2. 文件超大被截断（只读了前 N 行）
-3. 你文件刚改过还没存盘（Cursor 读的是磁盘版本）
+常见原因：
+1. 路径错了（大小写 / 选错同名文件）
+2. 文件很大，Agent 只读了其中一部分
+3. 你文件刚改过还没存盘
 
 **出坑**
 ```
@@ -132,57 +138,55 @@ globs: ["src/components/**/*.tsx"]
 让 AI 先复述文件内容，确认它**真的读到了**，再让它动手。
 
 **预防**
-- 大文件用 `@folder` 引用整个目录让它自己找，比 `@file` 精确到路径稳
+- 从 @ 弹出的列表里选文件，别手敲路径
 - 改完文件**先 Cmd+S 存盘**再 @ 引用
-- 超大文件（>1000 行）精确引用行号范围：`@src/models/big.ts:50-120`
+- 超大文件：在提示词里点名具体的函数 / 类名，让它定位到那一段再读
 
 ---
 
-## 陷阱 5：Chat vs Composer 混用，效率全失
+## 陷阱 5：Agent / Ask / 行内编辑混用，效率全失
 
 **症状**
-- 在 Chat 里问"帮我重构这个模块"——它给你一大堆建议文字，不改代码
-- 在 Composer 里问"这段代码怎么理解"——它不回答，直接开始改
+- 在 Ask 模式里说"帮我重构这个模块"——它给你一大堆建议文字，不改代码
+- 在 Agent 模式里问"这段代码怎么理解"——它不只回答，还顺手开始改
 - 你来回切换，每次都选错模式
 
 **根因**
-- **Chat (`Cmd+L`)**：问答模式，不主动改代码
-- **Composer (`Cmd+I`)**：Agent 模式，优先改代码
-- **Inline (`Cmd+K`)**：行内编辑，只改选中区域
+- **Agent 模式**：自主改代码、跑命令
+- **Ask 模式**：只读问答，不改代码
+- **Plan 模式**：先出方案，确认后再执行
+- **行内编辑（`Cmd+K`）**：只改选中区域
 
-三个模式的触发入口不一样，新手分不清。
+Agent 面板（`Cmd+I` / `Cmd+L`）里用 `Shift+Tab` 切模式，新手容易忽略当前在哪个模式。
 
 **出坑**
-切错模式了：把任务内容复制，关闭当前面板，打开正确模式粘进去。
+切错模式了：`Shift+Tab` 切到正确模式，重新发一次。
 
 **预防**
-记住**快捷键和用途的一一对应**：
+记住**用途和入口的对应**：
 
-| 你想做什么 | 用哪个 | 快捷键 |
+| 你想做什么 | 用哪个 | 入口 |
 |-----------|-------|-------|
-| 问问题、理解代码 | Chat | `Cmd+L` |
-| 改选中的一段代码 | Inline | `Cmd+K` |
-| 跨文件大改动 | Composer | `Cmd+I` |
+| 问问题、理解代码 | Ask 模式 | Agent 面板 + `Shift+Tab` |
+| 改选中的一段代码 | 行内编辑 | `Cmd+K` |
+| 跨文件大改动 | Plan → Agent 模式 | Agent 面板 + `Shift+Tab` |
 
 ---
 
 ## 陷阱 6：模型切换导致风格不一致
 
 **症状**
-- 你在 Cursor 里一半时间用 Claude 3.5，一半用 cursor-small
+- 你在 Cursor 里一半时间用 Claude，一半用 Composer 或 GPT
 - 同一个项目里代码风格分裂：有的地方严谨地写类型，有的地方随意 `any`
 - 你自己都没意识到是模型切换导致的
 
 **根因**
-Cursor 支持多模型，不同模型的"默认风格"不同：
-- Claude Sonnet：倾向严谨，会主动加类型、加错误处理
-- GPT-4：倾向简洁，少废话少注释
-- cursor-small：速度快，但在复杂任务上会偷懒
+Cursor 支持多模型（Composer 2.5、Claude、GPT-5.x、Gemini、Grok 等），不同模型的"默认风格"不同：有的倾向严谨、主动加类型和错误处理，有的倾向简洁、少注释。
 
-自动切换（系统根据任务复杂度选模型）会让这个问题更隐蔽。
+用 Auto（Cursor Router）时，系统按你选的 Cost / Balance / Intelligence 偏好自动路由，每次用的模型可能不同，这个问题会更隐蔽。
 
 **出坑**
-把风格规则写进 `.cursor/rules/global.md`，不管用哪个模型都会遵守：
+把风格规则写进 `.cursor/rules/global.mdc`（`alwaysApply: true`），不管用哪个模型都会遵守：
 
 ```markdown
 # 代码风格（跨模型一致）
@@ -192,30 +196,31 @@ Cursor 支持多模型，不同模型的"默认风格"不同：
 ```
 
 **预防**
-- **一个项目定一个主模型**，在设置里锁定
-- 明确任务才换模型（"这个任务用 Opus 深度思考"）
-- 不要依赖 `auto` 选模型
+- 风格靠 **rules + lint/格式化工具** 兜底，而不是靠固定某个模型
+- 用 Auto 时按任务选偏好：日常小改用 Cost / Balance，复杂重构用 Intelligence 或手动指定最强模型
+- 对风格一致性要求高的大任务，手动指定一个模型从头做到尾
 
 ---
 
-## 陷阱 7：Notepads 上下文污染
+## 陷阱 7：还在找 Notepads — 旧上下文没迁移
 
 **症状**
-- 半年前建的 Notepad 里有过时信息（旧 API 设计、废弃的代码风格）
-- 新对话里 AI 引用 Notepad，给出了过时方案
-- 你都不记得自己建过这个 Notepad
+- 升级后找不到 Notepads 面板，之前存的 API 规范、约定"没了"
+- 或者还留着一些早就过时的上下文片段（旧 API 设计、废弃的代码风格），AI 照着给了过时方案
 
 **根因**
-Notepads 是**手动管理**的上下文片段，Cursor 不会自动更新它。项目演进几个月后，Notepads 和真实代码就开始脱节。
+Notepads 于 2025 年 10 月弃用、在 Cursor 2.0 移除。它本来就是**手动管理**的上下文，不会自动更新，项目演进几个月后就和真实代码脱节。
 
 **出坑**
-- 定期清理：看到 AI 用了奇怪方案，怀疑是 Notepad 污染，去 Notepad 面板检查
-- 发现过时内容立刻删除或更新
+把还有用的内容迁到新机制：
+- 稳定约定（API 返回格式、认证方式）→ `.cursor/rules/*.mdc`，设成手动触发，用 `@规则名` 引用
+- 成套的方法论 / 流程 → Skill（`.cursor/skills/`）
+- 易变内容（当前在做的功能）→ 不存，直接 `@Files` / `@Folders` 引用实时代码
+- 迁移时顺手删掉过时内容
 
 **预防**
-- Notepad **只放稳定的约定**（API 返回格式、认证方式等不常变的）
-- 易变的内容（当前正在做的功能、临时方案）**用 `@folder` 引用实时代码**而不是 Notepad
-- Notepad 里加修改日期，定期检查："2026-01 以前的都复审一次"
+- 规则文件进 Git，和代码一起评审、一起演进
+- 规则里写明适用范围，定期复审："半年没动过的规则都看一遍"
 
 ---
 
@@ -223,18 +228,18 @@ Notepads 是**手动管理**的上下文片段，Cursor 不会自动更新它。
 
 **症状**
 - 你重命名或删除了某个文件
-- 在 Chat 里 @ 还能引用到它（带着旧内容）
+- @ 还能引用到它（带着旧内容）
 - AI 基于旧文件给建议，你按建议改，编译报错"文件不存在"
 
 **根因**
-Cursor 的代码库索引**不是实时更新**。删除/重命名后，内存里的索引还保留旧条目一段时间。
+Cursor 的代码库索引**不是实时更新**。删除/重命名后，索引可能还保留旧条目一段时间。
 
 **出坑**
-命令面板（`Cmd+Shift+P`）→ `Cursor: Resync Index`
+- 在 Cursor Settings 的索引设置里查看索引状态，必要时手动重新同步（具体入口以当前版本为准）
+- 或者直接让 Agent 用搜索 / 终端确认文件是否存在，再继续
 
 **预防**
-- 大规模重命名/删除后主动重建索引
-- 如果用 Git 分支切换频繁，切分支后跑一次 resync
+- 大规模重命名/删除后，确认索引已更新再依赖 @ 引用
 - 发现 @ 引用结果奇怪，第一反应先检查索引，不要怀疑 AI
 
 ---
diff --git a/windsurf/README.en.md b/windsurf/README.en.md
index a746cd6..596f7d0 100644
--- a/windsurf/README.en.md
+++ b/windsurf/README.en.md
@@ -1,8 +1,12 @@
 [简体中文](./README.md) | **English**
 
-# Windsurf Best Practices
+# Devin Desktop (formerly Windsurf) Best Practices
 
-> Windsurf is an AI IDE from Codeium. Its standout feature is **Cascade** — an AI Agent that tracks your editing behavior. It automatically follows your actions (file switches, code changes, terminal output) and proactively offers help, rather than waiting for you to ask.
+> **Windsurf is now Devin Desktop.** Cognition acquired Windsurf in July 2025, and on 2026-06-02 it was renamed via an automatic update; the website moved from windsurf.com to [devin.ai](https://devin.ai). Existing settings, keybindings and extensions migrate automatically — no reinstall needed.
+>
+> It's still a VS Code-based AI IDE, but the focus has shifted from "an editor with an agent" to **a command center for local + cloud agents**: the local agent Cascade has been replaced by **Devin Local** (rebuilt in Rust, with subagent support), and the home view is a board for managing all your agents. It still picks up your edits, terminal output and other actions (officially called "real-time awareness" now — the "Flows" term is gone).
+>
+> Last updated: 2026-09.
 
 ---
 
@@ -10,11 +14,14 @@
 
 | Concept | Description | Use Case |
 |---------|-------------|----------|
-| **Cascade** | Context-aware Agent | Automatically understands what you're doing and suggests proactively |
-| **Flows** | Action tracking | Records your editing trail as context |
-| **Write Mode** | Direct code writing | Similar to Cursor Composer |
-| **Chat Mode** | Conversational Q&A | Understanding code, asking questions |
-| **Rules** | `.windsurfrules` | Project-level rule configuration |
+| **Devin Local** | Local agent (replaces Cascade), supports subagents | Multi-step tasks inside the editor |
+| **Code / Plan / Ask modes** | Code (default, edits code) / Plan (proposes a plan first) / Ask (read-only Q&A); switch with `⌘.` | Pick the mode per task |
+| **Agent Command Center** | Kanban view of all local and cloud agents | Running several tasks in parallel |
+| **Spaces** | Group sessions, PRs, files and context; agents share context | Organizing work by project/feature |
+| **Rules** | `.devin/rules/*.md` (preferred) or `.windsurf/rules/*.md` | Project-level rule configuration |
+| **AGENTS.md** | Allowed in any directory; root is always on, subdirectories apply to that directory | Rules shared across tools |
+| **Workflows / Skills** | Markdown in `.devin/workflows/`, invoked as `/name`; Devin Local uses Skills instead | Reusable procedures |
+| **Hooks** | `.devin/hooks.json`, 12 events | Run scripts before/after agent actions |
 | **@ References** | `@file` `@folder` `@web` etc. | Pinpoint context precisely |
 
 ---
@@ -23,13 +30,19 @@
 
 ### Installation
 
-Download from [windsurf.com](https://windsurf.com). Supports macOS / Windows / Linux. Based on VS Code — most existing VS Code extensions are compatible.
+Download from [devin.ai/download](https://devin.ai/download). Supports macOS / Windows / Linux. Based on VS Code — most existing VS Code extensions are compatible. Existing Windsurf installs auto-update to Devin Desktop; on first launch you can choose to migrate your Windsurf settings.
 
-### .windsurfrules — Project Rules
+The CLI launcher changed from `surf` / `windsurf` to `devin-desktop` (the old commands are still kept for now).
 
-Create `.windsurfrules` in your project root:
+### Project Rules — `.devin/rules/`
+
+Create a `.devin/rules/` directory in your project (legacy `.windsurf/rules/` is still read; if both exist, `.devin/rules/` wins). One `.md` file per rule, up to **12,000 characters** per file:
 
 ```markdown
+---
+trigger: always_on
+---
+
 # Project Rules
 
 ## Tech Stack
@@ -41,42 +54,65 @@ Vue 3 + TypeScript + Pinia + Element Plus
 - Split stores by feature module
 - All API requests go through wrappers under src/api/
 
-## Cascade Behavior
+## Agent Behavior
 - Auto-check Props types when modifying components
 - Remind to update TypeScript types when modifying API endpoints
 - Do not auto-refactor code I haven't asked you to change
 ```
 
-### Using Cascade Effectively
+The `trigger` frontmatter field controls when a rule is loaded:
+
+| trigger | Behavior |
+|---------|----------|
+| `always_on` | Full content included in every conversation |
+| `model_decision` | Only the description is shown; the model reads the full rule when needed |
+| `glob` | Loaded when the files being worked on match the glob |
+| `manual` | Loaded only when you `@rule-name` it |
+
+Other rule sources:
+
+- **Global rules**: `global_rules.md` (`~/.codeium/windsurf/memories/global_rules.md`, 6,000-character limit), applies to every project
+- **AGENTS.md**: at the root it behaves like `always_on`; in a subdirectory it only applies to that directory — handy for sharing one rule set with Claude Code, Cursor, etc.
+- **`.windsurfrules`**: root-level single file, **legacy only** — don't use it for new projects
 
-Cascade tracks your actions. Take advantage of this:
+> Cursor users can import `.cursor/rules` into `.devin/rules/`.
+
+### Using Real-Time Awareness
+
+Devin Local picks up your actions (open files, edits, terminal output). Take advantage of this:
 
 ```
-1. Open a few related files first (so Cascade knows what you're working on)
-2. Make a small change (so Cascade understands your intent)
-3. At this point, Cascade's suggestions will be more accurate than a cold start
+1. Open a few related files first (so the agent knows what you're working on)
+2. Make a small change (so the agent understands your intent)
+3. Now ask — you'll get better answers than from a cold start
 ```
 
 ---
 
 ## Prompting Tips
 
-### 1. Write Mode — Large Tasks
+### 1. Large Tasks: Plan First, Then Code
+
+Press `⌘.` to switch to Plan mode, get a plan, then switch back to Code mode to execute:
 
 ```
-Use Write mode.
+[Plan mode]
 Migrate all user management pages under src/views/user/ from Options API to Composition API.
-Keep functionality unchanged, only change the syntax.
-Go file by file. Let me confirm after each one.
+Keep functionality unchanged, only change the syntax. List the files to change and what changes in each.
+
+[After approving the plan, switch to Code mode]
+Execute the plan file by file. Let me confirm after each one.
 ```
 
-### 2. Leverage Flows Context
+When you only want answers and no edits, use **Ask mode** (read-only).
+
+### 2. Leverage Real-Time Awareness
 
 ```
 # You just ran tests in the terminal and saw errors
-# Cascade already knows — just say:
+# The agent already saw them — just say:
 The test just failed, help me figure out why.
-# No need to paste the error — Cascade already picked it up from the Flow
+# Usually no need to paste the error
 ```
 
 ### 3. @ References
@@ -89,16 +125,53 @@ Use types/user.ts as the source of truth.
 
 ---
 
+## Advanced Tips
+
+### Workflows and Skills
+
+Write repeatable procedures as Markdown in `.devin/workflows/` (12,000 characters per file) and invoke them in chat with `/filename`, e.g. `/release`. Workflows are manual-only.
+
+Note: **Devin Local does not support Workflows** — the official recommendation is to migrate them to Skills (`.devin/skills/`), which the agent can invoke automatically when relevant.
+
+### Hooks
+
+Configure hooks in `.devin/hooks.json`. There are 12 events (e.g. before/after the agent reads a file, writes a file, or runs a command). **A pre-hook script that exits with code 2 blocks the action** — useful for stopping edits to `.env` or dangerous commands.
+
+### Parallel Agents: Agent Command Center
+
+Devin Desktop opens to the Agent Command Center — a kanban board showing both local agent sessions and cloud Devin sessions. Good patterns:
+
+- Local agent for changes you want to watch; cloud Devin for long-running independent tasks
+- Use **Spaces** to group the sessions, PRs and files for one feature so agents share context
+- Plug in third-party agents (Codex, Claude Agent, OpenCode, etc.) via ACP (Agent Client Protocol); they're managed on the board just like native sessions
+
+### Model Selection
+
+The model picker includes the in-house SWE family (SWE-1.6 / SWE-1.7 / SWE-2), **Adaptive** (automatic model selection), plus third-party models such as Claude, GPT, Gemini, Grok, Kimi and GLM. Use SWE models or Adaptive for everyday work to save credits; switch to the strongest third-party model for complex refactors.
+
+### Pricing
+
+| Plan | Price |
+|------|-------|
+| Free | $0 |
+| Pro | $20/mo |
+| Max | $200/mo |
+| Teams | $80/mo + $40/seat |
+
+See [devin.ai/pricing](https://devin.ai/pricing) for the latest.
+
+---
+
 ## How It Differs from Cursor
 
-| Dimension | Windsurf | Cursor |
+| Dimension | Devin Desktop | Cursor |
 |-----------|----------|--------|
-| Core philosophy | **Proactive awareness**, tracks your actions and offers help automatically | **On-demand**, responds only when you ask |
-| Agent | Cascade (auto-tracks Flows) | Composer (manually triggered) |
-| Context | Automatically inferred from action flow | Requires manual @ references |
-| Rules | `.windsurfrules` single file | `.cursor/rules/` with glob-based splitting |
-| Models | Proprietary + Claude/GPT | Claude/GPT/proprietary |
-| Best for | People who like AI to proactively help | People who prefer precise control |
+| Core philosophy | **Agent command center** — one board for local + cloud agents | **Editor-first** — Agents Window for parallel agents |
+| Local agent | Devin Local (Code / Plan / Ask) | Agent (Agent / Ask / Plan) |
+| Context | Real-time awareness of your actions + @ references | @ references + codebase index |
+| Rules | `.devin/rules/*.md`, loading controlled by `trigger` | `.cursor/rules/*.mdc`, loading controlled by `globs`/`alwaysApply` |
+| Models | In-house SWE family + Claude/GPT/Gemini etc. | In-house Composer + Claude/GPT/Gemini etc. |
+| Best for | People orchestrating several local/cloud agents | People who prefer precise control in the editor |
 
 ---
 
@@ -106,9 +179,11 @@ Use types/user.ts as the source of truth.
 
 | Pitfall | Description | Solution |
 |---------|-------------|----------|
-| Cascade too proactive | You're just browsing code and it starts suggesting changes | Adjust Cascade sensitivity in settings |
-| Flows context gets confused | Switched too many files, Cascade loses track of what you're doing | Start a new Cascade session |
-| Write mode scope creep | Edits files it shouldn't | Use @ references to limit scope |
+| Rules still in `.windsurfrules` | The single-file format is legacy only | Move to `.devin/rules/*.md` and use `trigger` for on-demand loading |
+| Rules truncated | A file exceeds 12,000 characters | Split by topic into multiple rule files |
+| Awareness context gets confused | Switched too many files, the agent loses track | Start a new session |
+| Code mode scope creep | Edits files it shouldn't | Confirm scope in Plan mode first, or limit with @ references |
+| Workflow does nothing under Devin Local | Devin Local doesn't support Workflows | Migrate to Skills |
 
 ---
 
@@ -116,12 +191,14 @@ Use types/user.ts as the source of truth.
 
 | Template | Purpose |
 |----------|---------|
-| [.windsurfrules](templates/windsurfrules.md) | Project rules template (Vue 3 + TypeScript), copy to project root and rename to `.windsurfrules` |
+| [windsurfrules.md](templates/windsurfrules.md) | Project rules template (Vue 3 + TypeScript); copy to `.devin/rules/project.md` (or `.windsurf/rules/` for older setups) |
 
 ---
 
 ## Further Reading
 
-- [Windsurf Official Docs](https://docs.codeium.com/windsurf)
+- [Devin Desktop Official Docs](https://docs.devin.ai/desktop)
+- [Devin Desktop FAQ](https://docs.devin.ai/desktop/devin-desktop-faq) — Details on migrating from Windsurf
+- [Windsurf is now Devin Desktop](https://devin.ai/blog/windsurf-is-now-devin-desktop) — Official rename announcement
 - [awesome-windsurf](https://github.com/detailobsessed/awesome-windsurf) — Community resource collection
-- [superpowers-zh](https://github.com/jnMetaCode/superpowers-zh) — Skills methodology (also supports Windsurf)
+- [superpowers-zh](https://github.com/jnMetaCode/superpowers-zh) — Skills methodology (also supports Windsurf / Devin Desktop)
diff --git a/windsurf/README.md b/windsurf/README.md
index 5ee2d0b..3f979b7 100644
--- a/windsurf/README.md
+++ b/windsurf/README.md
@@ -1,6 +1,10 @@
-# Windsurf 最佳实践
+# Devin Desktop（原 Windsurf）最佳实践
 
-> Windsurf 是 Codeium 推出的 AI IDE，核心特色是 **Cascade** — 一个能感知你编辑行为的 AI Agent。它会自动追踪你的操作（文件切换、代码修改、终端输出），主动提供帮助，而不是等你提问。
+> **Windsurf 已更名为 Devin Desktop。** Cognition 于 2025 年 7 月收购 Windsurf，2026-06-02 通过自动更新正式改名，官网从 windsurf.com 迁到 [devin.ai](https://devin.ai)。原有设置、快捷键、扩展会自动迁移，老用户无需重装。
+>
+> 它仍是基于 VS Code 的 AI IDE，但定位从"带 Agent 的编辑器"变成了**本地 + 云端 Agent 的指挥中心**：本地 Agent 从 Cascade 换成了用 Rust 重写的 **Devin Local**（支持子 Agent），首页是管理所有 Agent 的看板。它依然会感知你的编辑、终端输出等操作（官方现在叫 "real-time awareness"，不再用 "Flows" 这个词）。
+>
+> 信息更新于 2026-09。
 
 ---
 
@@ -8,11 +12,14 @@
 
 | 概念 | 说明 | 用途 |
 |------|------|------|
-| **Cascade** | 上下文感知 Agent | 自动理解你在做什么，主动建议 |
-| **Flows** | 操作流追踪 | 记录你的编辑轨迹作为上下文 |
-| **Write 模式** | 直接写代码 | 类似 Cursor Composer |
-| **Chat 模式** | 对话问答 | 理解代码、问问题 |
-| **Rules** | `.windsurfrules` | 项目级规则配置 |
+| **Devin Local** | 本地 Agent（取代 Cascade），支持子 Agent | 在编辑器里完成多步骤任务 |
+| **Code / Plan / Ask 模式** | Code（默认，直接改代码）/ Plan（先出方案）/ Ask（只读问答），`⌘.` 切换 | 按任务选模式 |
+| **Agent Command Center** | 看板视图，统一管理本地和云端 Agent | 并行跑多个任务 |
+| **Spaces** | 把会话、PR、文件、上下文归到一组，Agent 之间共享上下文 | 按项目/需求组织工作 |
+| **Rules** | `.devin/rules/*.md`（推荐）或 `.windsurf/rules/*.md` | 项目级规则配置 |
+| **AGENTS.md** | 任意目录都可放，根目录总是生效，子目录按目录范围生效 | 跨工具通用的规则 |
+| **Workflows / Skills** | `.devin/workflows/` 里的 Markdown，用 `/名字` 调用；Devin Local 改用 Skills | 可复用的流程 |
+| **Hooks** | `.devin/hooks.json`，12 种事件 | 在 Agent 动作前后跑脚本 |
 | **@引用** | `@file` `@folder` `@web` 等 | 精确指定上下文 |
 
 ---
@@ -21,13 +28,19 @@
 
 ### 安装
 
-从 [windsurf.com](https://windsurf.com) 下载安装，支持 macOS / Windows / Linux。基于 VS Code，现有 VS Code 扩展大部分兼容。
+从 [devin.ai/download](https://devin.ai/download) 下载，支持 macOS / Windows / Linux。基于 VS Code，现有 VS Code 扩展大部分兼容。已经装了 Windsurf 的会自动更新成 Devin Desktop，首次启动可选择从 Windsurf 迁移设置。
 
-### .windsurfrules — 项目规则
+命令行启动命令从 `surf` / `windsurf` 换成了 `devin-desktop`（旧命令暂时保留）。
 
-在项目根目录创建 `.windsurfrules`：
+### 项目规则 — `.devin/rules/`
+
+在项目里创建 `.devin/rules/` 目录（老项目的 `.windsurf/rules/` 也还能读，两者都有时 `.devin/rules/` 优先），每个规则一个 `.md` 文件，单文件上限 **12,000 字符**：
 
 ```markdown
+---
+trigger: always_on
+---
+
 # 项目规则
 
 ## 技术栈
@@ -39,42 +52,65 @@ Vue 3 + TypeScript + Pinia + Element Plus
 - Store 按功能模块拆分
 - API 请求统一走 src/api/ 下的封装
 
-## Cascade 行为
+## Agent 行为
 - 修改组件时自动检查 Props 类型是否正确
 - 修改 API 接口时提醒更新对应的 TypeScript 类型
 - 不要自动重构我没要求改的代码
 ```
 
-### Cascade 的正确用法
+frontmatter 里的 `trigger` 决定规则什么时候加载：
+
+| trigger | 行为 |
+|---------|------|
+| `always_on` | 每次对话都完整加载 |
+| `model_decision` | 只给模型看 description，需要时再读全文 |
+| `glob` | 操作的文件匹配 glob 时加载 |
+| `manual` | 只在你 `@规则名` 时加载 |
+
+其他规则来源：
+
+- **全局规则**：`global_rules.md`（`~/.codeium/windsurf/memories/global_rules.md`，上限 6,000 字符），对所有项目生效
+- **AGENTS.md**：放根目录相当于 `always_on`，放子目录只对该目录生效——和 Claude Code、Cursor 等工具共用一份规则很方便
+- **`.windsurfrules`**：根目录单文件，**仅作兼容保留**，新项目别再用
+
+> Cursor 用户可以把 `.cursor/rules` 导入到 `.devin/rules/`。
 
-Cascade 会追踪你的操作。利用这一点：
+### 用好实时感知
+
+Devin Local 会感知你的操作（打开的文件、编辑、终端输出）。利用这一点：
 
 ```
-1. 先手动打开几个相关文件（让 Cascade 知道你在关注什么）
-2. 做一个小修改（让 Cascade 理解你的意图）
-3. 这时候 Cascade 的建议会比直接提问更准确
+1. 先手动打开几个相关文件（让 Agent 知道你在关注什么）
+2. 做一个小修改（让 Agent 理解你的意图）
+3. 这时候再提问，比冷启动直接问更准确
 ```
 
 ---
 
 ## 提示词技巧
 
-### 1. Write 模式 — 大任务
+### 1. 大任务先 Plan 再 Code
+
+按 `⌘.` 切到 Plan 模式，让它先出方案，确认后切回 Code 模式执行：
 
 ```
-用 Write 模式。
+[Plan 模式]
 把 src/views/user/ 下的用户管理页面从 Options API 迁移到 Composition API。
-保持功能不变，只改写法。
-一个文件一个文件来，每个文件改完让我确认。
+保持功能不变，只改写法。先列出要改的文件和每个文件的改动点。
+
+[确认方案后切到 Code 模式]
+按刚才的方案执行，一个文件一个文件来，每个文件改完让我确认。
 ```
 
-### 2. 利用 Flows 上下文
+只想问问题、不想让它动代码时用 **Ask 模式**（只读）。
+
+### 2. 利用实时感知
 
 ```
 # 你刚在终端跑了测试，看到了报错
-# Cascade 已经知道了，直接说：
+# Agent 已经感知到了，直接说：
 刚才测试报错了，帮我看看什么原因。
-# 不需要贴报错信息，Cascade 已经从 Flow 里拿到了
+# 通常不需要贴报错信息
 ```
 
 ### 3. @ 引用
@@ -87,16 +123,53 @@ Cascade 会追踪你的操作。利用这一点：
 
 ---
 
+## 进阶技巧
+
+### Workflows 与 Skills
+
+把重复流程写成 Markdown 放进 `.devin/workflows/`（单文件上限 12,000 字符），在对话里用 `/文件名` 调用，例如 `/release`。Workflow 只能手动触发。
+
+注意：**Devin Local 不支持 Workflows**，官方建议迁移到 Skills（`.devin/skills/`）——Skills 可以由 Agent 按需自动调用。
+
+### Hooks
+
+在 `.devin/hooks.json` 里配置 Hooks，支持 12 种事件（比如 Agent 读文件、写文件、跑命令前后）。**pre-hook 脚本以 exit code 2 退出会阻止这次操作**，适合拦截改 `.env`、跑危险命令这类场景。
+
+### 并行 Agent：Agent Command Center
+
+Devin Desktop 的首页是 Agent Command Center——一个看板，本地 Agent 和云端 Devin 的会话都在上面。适合的用法：
+
+- 本地 Agent 做需要你盯着的改动，云端 Devin 跑耗时的独立任务
+- 用 **Spaces** 把同一个需求的会话、PR、文件归到一起，Agent 之间共享上下文
+- 通过 ACP（Agent Client Protocol）接入第三方 Agent（Codex、Claude Agent、OpenCode 等），和原生会话一样在看板里管理
+
+### 模型选择
+
+模型选择器里有自研的 SWE 系列（SWE-1.6 / SWE-1.7 / SWE-2）、自动选模型的 **Adaptive**，以及 Claude、GPT、Gemini、Grok、Kimi、GLM 等第三方模型。日常任务用 SWE 系列或 Adaptive 更省额度，复杂重构再切到最强的第三方模型。
+
+### 价格
+
+| 方案 | 价格 |
+|------|------|
+| Free | $0 |
+| Pro | $20/月 |
+| Max | $200/月 |
+| Teams | $80/月 + $40/席位 |
+
+以 [devin.ai/pricing](https://devin.ai/pricing) 为准。
+
+---
+
 ## 与 Cursor 的区别
 
-| 维度 | Windsurf | Cursor |
+| 维度 | Devin Desktop | Cursor |
 |------|---------|--------|
-| 核心理念 | **主动感知**，追踪你的操作自动提供帮助 | **按需触发**，你提问它才响应 |
-| Agent | Cascade（自动追踪 Flows） | Composer（手动触发） |
-| 上下文 | 自动从操作流推断 | 需要手动用 @ 引用 |
-| Rules | `.windsurfrules` 单文件 | `.cursor/rules/` 可按 globs 拆分 |
-| 模型 | 自研 + Claude/GPT | Claude/GPT/自研 |
-| 适合 | 喜欢 AI 主动帮忙的人 | 喜欢精确控制的人 |
+| 核心理念 | **Agent 指挥中心**，本地 + 云端 Agent 统一看板 | **编辑器优先**，Agents Window 管理并行 Agent |
+| 本地 Agent | Devin Local（Code / Plan / Ask） | Agent（Agent / Ask / Plan） |
+| 上下文 | 实时感知你的操作 + @ 引用 | @ 引用 + 代码库索引 |
+| Rules | `.devin/rules/*.md`，`trigger` 控制加载 | `.cursor/rules/*.mdc`，`globs`/`alwaysApply` 控制加载 |
+| 模型 | SWE 系列自研 + Claude/GPT/Gemini 等 | Composer 自研 + Claude/GPT/Gemini 等 |
+| 适合 | 想同时调度多个本地/云端 Agent 的人 | 喜欢在编辑器里精确控制的人 |
 
 ---
 
@@ -104,9 +177,11 @@ Cascade 会追踪你的操作。利用这一点：
 
 | 陷阱 | 说明 | 解决 |
 |------|------|------|
-| Cascade 太主动 | 你只是浏览代码它就开始建议修改 | 设置里调整 Cascade 敏感度 |
-| Flows 上下文错乱 | 切了太多文件，Cascade 搞不清你在做什么 | 开新 Cascade 会话，重新开始 |
-| Write 模式范围失控 | 改了不该改的文件 | 用 @ 引用限定范围 |
+| 规则写在 `.windsurfrules` | 老单文件格式只是兼容保留 | 迁到 `.devin/rules/*.md`，用 `trigger` 按需加载 |
+| 规则被截断 | 单文件超过 12,000 字符 | 按主题拆成多个规则文件 |
+| 感知上下文错乱 | 切了太多文件，Agent 搞不清你在做什么 | 开新会话重新开始 |
+| Code 模式范围失控 | 改了不该改的文件 | 先用 Plan 模式确认范围，或用 @ 引用限定 |
+| Workflow 在 Devin Local 下不生效 | Devin Local 不支持 Workflows | 迁移成 Skills |
 
 ---
 
@@ -114,12 +189,14 @@ Cascade 会追踪你的操作。利用这一点：
 
 | 模板 | 用途 |
 |------|------|
-| [.windsurfrules](templates/windsurfrules.md) | 项目规则模板（Vue 3 + TypeScript），复制到项目根目录重命名为 `.windsurfrules` |
+| [windsurfrules.md](templates/windsurfrules.md) | 项目规则模板（Vue 3 + TypeScript），复制到 `.devin/rules/project.md`（旧项目也可放 `.windsurf/rules/`） |
 
 ---
 
 ## 延伸阅读
 
-- [Windsurf 官方文档](https://docs.codeium.com/windsurf)
+- [Devin Desktop 官方文档](https://docs.devin.ai/desktop)
+- [Devin Desktop FAQ](https://docs.devin.ai/desktop/devin-desktop-faq) — 从 Windsurf 迁移的细节
+- [Windsurf is now Devin Desktop](https://devin.ai/blog/windsurf-is-now-devin-desktop) — 官方更名公告
 - [awesome-windsurf](https://github.com/detailobsessed/awesome-windsurf) — 社区资源集合
-- [superpowers-zh](https://github.com/jnMetaCode/superpowers-zh) — Skills 方法论（也支持 Windsurf）
+- [superpowers-zh](https://github.com/jnMetaCode/superpowers-zh) — Skills 方法论（也支持 Windsurf / Devin Desktop）
diff --git a/windsurf/templates/windsurfrules.md b/windsurf/templates/windsurfrules.md
index 64aea07..c40db57 100644
--- a/windsurf/templates/windsurfrules.md
+++ b/windsurf/templates/windsurfrules.md
@@ -1,3 +1,10 @@
+---
+trigger: always_on
+---
+
+<!-- 用法：复制到项目的 .devin/rules/project.md（Devin Desktop，原 Windsurf；旧项目也可放 .windsurf/rules/）。
+     单文件上限 12,000 字符。.windsurfrules 根目录单文件仅作兼容保留，新项目不建议再用。 -->
+
 # 项目规则
 
 ## 项目背景
@@ -28,7 +35,7 @@
 - src/utils/     — 工具函数
 - src/types/     — TypeScript 类型定义
 
-## Cascade 行为
+## Agent 行为
 - 修改组件时自动检查 Props 类型是否完整
 - 修改 API 接口时提醒更新对应的 TypeScript 类型
 - 不要自动重构我没要求改的代码