工具Cursor（一）介绍&简单使用&特色

官方文档：https://cursor.com/docs

一、使用方法

1、下载安装

Cursor - The AI Code Editor

下载安装后使用google账户登录。

2、查看usage

https://cursor.com/dashboard?tab=usage 可以查看自己及团队的使用情况

3、模型选择

默认是auto

关闭auto，可以选择其他的模型，还可以自定义添加模型：

二、打开项目&设置&文件

1、打开项目

 界面和VS Code一模一样，打开项目使用open folder，注意：最好是把cursor当作文本编辑器，然后还在Idea中编译使用。不要在curosr中安装java解析器等其他插件，会导致cursor非常卡。

2、打开Cursor设置

 AI相关配置单独放在Cursor Settings中

3、从idea同行跳转到Cursor

在idea中安装switch2Curson插件，可以实现Idea和Cursor同行跳转

如我打开一个工程，点击Open File In Cursor

点击跳转后，如让AI自动加上一个字段：

4、cursor插件

Switch2IDEA 可以在cursor内实现代码跳转

5、cursor官方命令行工具cursor-client

idea装个插件，用terminal方式使用cursor。

 6、curosr内部引用文件

（1）方法一

选中文件--》右键--》选择Add file to Cursor Chat，

这时会自动引用

（2）方法二

先打开文件

然后直接拖动到聊天窗口即可。

三、对话模式

分为 Ask、Manual、Agent 三种对话模式。统一在一个窗口的好处是，如果 Ask 模式讨论的内容，可以方便的切换为 Agent 模式直接将内容写到文件中。

1、Chat 窗口 Ask 对话模式

Ask 模式是 Cursor 中最基础的 AI 交互方式，主要用于帮助你理解和探索代码。它可以：

• 回答你关于代码的各种问题

• 帮助搜索和理解代码库

• 提供代码解释和建议

• 快速修复代码错误（通过 AI Fix 功能）

• 和 Agent 模式最大区别是不能自动生成文件，如果是代码片段需要手动 Apply

1.1、使用技巧

• 使用 ⌘ + L 快速打开/关闭 Chat 窗口，并自动切换到 Ask 模式

• 通过 @ 符号添加特定上下文

• 悬停在代码错误上方，点击 AI Fix 按钮快速修复问题

 1.2 发送和使用 codebase 发送区别

在 Chat 窗口下，发送消息此前是两个提交按钮，现在只展示了一个按钮，如果不看文档，你都不知道它这里竟然还有隐藏功能：

1. ↵：

   • 直接按回车或点击发送按钮

   • 普通提交，只发送当前的对话内容

   • 适合简单的问题咨询和代码讨论

   • 不会包含项目上下文信息

2. ⌘↵：

   • 按住 ⌘（command） + ↵（回车） 键发送

   • 带有代码库上下文的发送

   • 会自动分析并包含相关的代码文件内容

   • 适合需要 AI 理解当前项目结构和代码的场景

   • 能得到更准确的回答，因为 AI 有更多上下文信息

1.3、问题快速修复

Cursor 提供了便捷的代码错误修复功能。当代码出现错误时，你可以：

1. 鼠标悬停在错误处

2. 把错误信息发送给 Cursor Chat 窗口

3. AI 会分析错误原因并给出修复建议

注意，按下 ⌘ 键再点击错误信息，会发送错误信息到新 Chat 窗口。原先底部的 Ask 模式会被切换为 Agent 模式。

2、Chat 窗口 Agent 对话模式

Agent 模式是 Cursor 默认的对话模式，也是一个更强大的 AI 编程助手，专注于代码的创作和修改。它不仅能理解代码，还能直接进行文件操作。

2.1、agent模式功能

Agent 模式是 Chat 窗口中最强大的功能，它像一个真实的编程助手，可以主动帮你完成各种复杂的编程任务：

• 自动获取相关上下文

• 执行文件创建、修改、删除操作

• 运行终端命令（需要开启 Yolo 模式）

• 自动代码库搜索（Codebase 功能）

• 执行过程中如果发现错误，会尝试自动修复错误

• 呼叫 MCP 功能，只有在 Agent 模式下能使用

• 自动进行网络搜索

Agent 的工作流程：

1. 主动行为：

   • 自动分析项目结构

   • 提出具体解决方案

   • 创建必要的文件

2. 文件操作：

   • 创建新文件

   • 自动导入依赖

   • 添加相关功能

3. 终端集成：

   • 提示运行命令

   • 展示执行结果

   • 所有命令都会先征求你的同意（前提是 Yolo 模式为关闭状态）

4. 智能搜索：

   • 自动找到相关文件

   • 分析代码依赖关系

   • 提供相关代码建议

5. 上下文管理：

   • 自动包含相关文件内容

   • 理解代码之间的关联

   • 保持代码风格一致

6. 错误自动修复：

   • 执行期间的错误自动修复

   • 支持将错误信息直接添加到 Chat 中进行修复

2.2、Chat 窗口回滚&撤销

在 Chat 窗口中，右下角有一个 Restore 按钮，可以回滚到之前的版本。在回滚之后，还可以使用撤销按钮，撤销回滚。

推荐及时通过 Git 的版本控制来管理代码的每次主要变更。

3、Agent+Yolo 模式

在前面我们介绍了 Cursor 的 Agent 模式，它像一个真实的编程助手，可以主动帮你完成各种复杂的编程任务。现在，让我们来了解一下 Cursor 在 0.44 版本中新增的 Yolo 模式。

Yolo 模式是一个让 Agent 更加自动化的功能。之前介绍的 Agent 模式，Agent 会根据你的提示，判断是否需要执行命令，如果需要执行命令，会提示你确认。

Yolo 模式则更进一步，Agent 将无需确认就能执行命令和文件操作，朝着"全自动驾驶"又迈进了一步。开启 Yolo 模式后，Cursor 编辑器能够：

• 文件的增删改查控制权利更大

• 执行代码所需的命令

• 修复可能出现的问题

• 重复执行这些操作

而你只需要留意它正在做什么就可以了。

如何启用 Yolo 模式？

1. 打开 Cursor 设置

2. 进入 Chat 部分

3. 找到并启用 Auto Run Mode选项

在启动 Yolo 模式后，你可以配置以下选项：

• Auto-run prompt：描述哪些命令应自动执行，由模型判断。例如："仅限编译命令、git 命令和其他安全命令"

• Command allowlist：如果只有特定命令应自动执行，可以在此添加

• Command denylist：永远不应自动执行的命令

• File-Deletion protection：如果启用，将阻止 Agent 自动删除文件

• MCP tools protection：如果启用，将阻止 Agent 使用 MCP 工具

Command denylist 这个选项，建议配置 rm 命令，防止误删文件。但是，还是要注意，开启 Yolo 模式后，建议及时使用 git 提交代码，防止误删后找不回来。在企业级项目中，建议不要开启 Yolo 模式。

打开新对话

当上下文过长，cursor回答可能不够精准。这时候建议新开一个窗口，新的chat和之前的chat是没有记忆的。

四、特色

1、智能补全

（1）基础示例Tab

Tab 代码智能补全是 Cursor 最强大的功能之一，它不仅能提供基本的代码补全，还能理解代码上下文，给出最合适的建议。

（2）文档模板补全

① API 文档补全

输入 "## API" 时，会提供 API 文档模板，自动生成标准的 API 文档结构

② 错误处理文档补全

输入 "## 错误" 时，自动补全错误处理文档结构，帮助快速创建标准化的错误文档

（3）变量和函数补全

当你开始输入变量或函数名时，Cursor 会根据上下文提供智能建议：

// 1. 变量名补全

const userName = '张三';

// 输入 "user" 时，Cursor 会建议：

userName // 已定义的变量

userId // 常见的相关变量

userEmail // 上下文相关的建议

// 2. 函数名补全

function calculateTotalPrice(price, quantity) {

return price * quantity;

}

// 输入 "calc" 时，Cursor 会建议：

calculateTotalPrice // 已定义的函数

calculateDiscount // 相关的函数名

calculateTax // 上下文相关的建议

（4）方法和属性补全

输入对象后的点号时，Cursor 会显示所有可用的方法和属性：

• 字符串方法补全

• 数组方法补全

• 对象属性补全

2、内联聊天

可以使用以下快捷键打开命令输入栏（Prompt Bar）：

• macOS：Cmd K

• Windows/Linux：Ctrl K

​​​命令唤醒的输入栏，也是一个 AI 聊天窗口，不过它不是一个单独的窗口，而是内联在文件中，主要功能包括：

• 输入自然语言描述来提问

• 使用 @ 符号引用其他内容

• 对生成的结果进行多次优化

3、代码库索引

代码库索引是 Cursor 最强大的功能之一。它通过为代码文件创建嵌入向量（Embeddings），帮助 AI 全面理解你的项目。这个功能让 AI 能够"看见"整个代码库，而不仅仅是当前打开的文件。

3.1、介绍

使用代码库索引后：

• ✅ AI 回答更准确，因为它能基于当前项目的索引库回答问题

• ✅ 文件搜索更快

• ✅ AI 能更好地理解跨文件的关系

• ✅ 重构建议更精准

实际效果对比

使用代码库索引和不使用代码库索引的主要区别：

• 使用代码库索引时，AI 先搜索了项目中的文件，然后根据文件内容回答

• AI 能准确指出项目中实现的具体功能和代码

• 不使用代码库索引时，AI 只能从一般角度回答，没有针对项目的具体情况

3.2、如何配置代码库索引

基本设置

Cursor 默认会自动索引新打开的文件夹。设置步骤：

1. 打开Cursor Settings

2. 进入 Indexing & docs

3. 查看同步状态指示条（显示索引进度）

4. 可用操作：

   • 【Sync】重新同步索引

   • 【Delete Index】删除现有索引

重要配置选项

1. 自动索引新文件夹

   • Index new folders by default选项默认开启

   • 自动索引新打开的文件夹

   • 超过 250,000 个文件的文件夹不会自动索引

2. 忽略文件设置

   • Ignore files选项用于配置索引时要忽略的文件

   • 这些规则会补充.gitignore中的规则

   • 可以通过Configure ignored files按钮设置规则

   • 或创建.cursorignore文件配置规则

最佳实践

为了更好地使用代码库索引功能：

1. 定期检查索引状态（通过进度条）

2. 合理设置忽略规则，避免索引无关文件

3. 大型项目考虑模块化索引

4. 团队统一.cursorignore配置

5. 使用代码库索引功能快速理解项目

常见问题解决

索引不同步或失败问题

• 点击Delete Index删除索引，然后重新打开项目

• 或者点击Sync Index重新同步

• 索引被删除时，需要点击"Compute Index"重新计算

索引进度条卡住

如果索引进度条卡住（一直显示 Pause Indexing）：

• 确认网络是否正常

• 尝试删除索引，重新计算

代码安全问题

关于代码安全，Cursor 的隐私政策说明：

• 代码会分成小块上传到服务器计算嵌入向量

• 所有明文代码在请求完成后立即删除

• 只有嵌入向量和元数据（如哈希值、文件名）会存储在数据库中

• 源代码本身不会被保存

4、AI 生成提交消息

在日常开发中，编写清晰、规范的 Git 提交消息常常是一项耗时且有挑战的任务。Cursor 提供的 AI 生成提交消息功能可以帮助开发者快速创建高质量的提交记录，大大提高工作效率。这个功能特别实用，让我们不再需要花费大量时间思考如何描述代码变更。

使用 Cursor 的 AI 生成提交消息功能非常简单：

1. 完成代码修改后，打开源代码管理面板

2. 在提交消息输入框中，点击右侧的闪光图标 (✨)，AI 会自动生成提交消息

3. AI 会根据你的代码变更生成合适的提交消息，你可以直接点击 Commit 按钮提交

4. 提交后，点击 Sync 按钮将代码推送到远程仓库

在 SOURCE CONTROL GRAPH 面板中，你可以查看所有提交记录，点击任意提交记录可以查看具体的代码变更。

5、MCP&Rules&Skill&Commands

见后面详解

五、keep&undo

1、undo all

撤回 Cursor 刚刚帮你做的那次修改。

• Cursor 会把 这一次 AI 修改的内容全部撤回

• 回到你调用 AI 之前的代码状态

• 和普通 Ctrl + Z 类似，但它是针对这次 AI 操作的一键撤销

适合场景：

• 生成结果完全不对

• 改太多、方向错了

• 想重新换个 prompt 再来一次

2、keep all

确认接受 Cursor 这一次生成/修改的所有改动。

• 这次 AI 修改会被正式合并进当前文件

• Cursor 不再把它当“临时 AI patch”

• 后续：

  • 可以正常继续编辑

  • 不会被下一次 AI 操作自动覆盖

👉 本质上是一次 “accept AI changes”

3、不操作

如果你什么都不点：代码会暂时留着，但这次 AI 生成处于“未确认状态”，下一次生成/编辑时很可能被覆盖或丢失。

短期看代码 还在，可以运行、可以复制；但是

• 下一次再用 AI（Cmd/Ctrl + K、Apply、Rewrite 等）

  • Cursor 可能会：

    • 覆盖刚才的改动

    • 或把它当成“未确认 patch”直接丢掉

• 文件重新生成 diff 时

  • Cursor 不一定把这部分当作稳定状态

• 心理层面

  • 你以为“已经改好了”

  • 但 Cursor 以为“你还没决定要不要”

六、上下文在哪里看

上下文是模型在生成下一句回复时「能看到的」全部内容，这些都会被打成一段「对话历史」发给模型，所以**上下文越长，token 越多，成本越高，也越容易夹杂无关信息**。一般包括：

- 当前对话里**你发过的消息**

- **主 Agent 已产生的回复**（包括中间步骤、思考、工具调用的说明）

- **每次工具调用的输入和输出**（如 MCP 返回的学校列表、grep 结果等）

- 系统预置的 **Rules、Skills 说明** 等

从哪里可以看：

1、界面上（最直观）

- **当前这个聊天窗口**里的整段对话（你的问题 + 主 Agent 的每条回复 + 展开后看到的工具调用步骤），就是**主 Agent 当前用到的上下文**的一部分（有时会做截断或摘要，但主体就是这段对话）。

2、磁盘上（完整记录）

- 路径：**`C:\Users\xxx\.cursor\projects\{projectName}\agent-transcripts`**

- 下面每个子文件夹对应**一次聊天会话**（主 Agent），打开对应的 **`.jsonl`** 文件可以看到该会话的完整记录：每行一条消息（`role: user / assistant`，以及 `message` 内容）。  

- 这就是**主 Agent 在这条会话里的上下文**的持久化形式（你看到的就是会喂给模型的对话历史）。

role	含义
user	你（人类）发的消息：你输入的问题、指令等。
assistant	AI（主 Agent）发的消息：模型的回复、思考、或发起的工具调用说明等。

Cursor请求链路分析

User client→Cursor client → Cursor server → LLM

• AnalyticsService/Batch = 发送数据（初始请求、工具结果）
• AiService/CheckQueue = 接收响应（状态、工具指令、最终答案）
• 循环模式：Batch 发送 → CheckQueue 接收 → 执行工具 → Batch 发送 → CheckQueue 接收...
• 异步埋点：rgstr 和 NameTab 不影响主流程

原文：

{
    "user": "auth0|user_01K1GF41DEDJGAPDN7GYQ63R4V",
    "model": "gpt-5",
    "input": [
        {
            "role": "{system}",
            "content": "{system prompt}"
        },
        {
            "role": "user",
            "content": "{user prompt}"
        },
        {
            "role": "user",
            "content": "{user input}"
        }
    ],
    "tools": [
        {
            "type": "function",
            "name": "codebase_search",
            "description": "{tool desc}",
            "parameters": {
                "type": "object",
                "properties": {
                    "explanation": {
                        "type": "string",
                        "description": "{param desc.}"
                    }
                },
                "required": [
                    "explanation"
                ]
            },
            "strict": false
        }
    ]
}

System prompt

You are an AI coding assistant, powered by GPT-5. You operate in Cursor.

You are pair programming with a USER to solve their coding task. Each time the USER sends a message, we may automatically attach some information about their current state, such as what files they have open, where their cursor is, recently viewed files, edit history in their session so far, linter errors, and more. This information may or may not be relevant to the coding task, it is up for you to decide.

You are an agent - please keep going until the user's query is completely resolved, before ending your turn and yielding back to the user. Only terminate your turn when you are sure that the problem is solved. Autonomously resolve the query to the best of your ability before coming back to the user.

Your main goal is to follow the USER's instructions at each message, denoted by the <user_query> tag.

<communication> 基本交流范式用Markdown
- Always ensure **only relevant sections** (code snippets, tables, commands, or structured data) are formatted in valid Markdown with proper fencing.
- Avoid wrapping the entire message in a single code block. Use Markdown **only where semantically correct** (e.g., `inline code`, ```code fences```, lists, tables).
- ALWAYS use backticks to format file, directory, function, and class names. Use \\( and \\) for inline math, \\[ and \\] for block math.
- When communicating with the user, optimize your writing for clarity and skimmability giving the user the option to read more or less.
- Ensure code snippets in any assistant message are properly formatted for markdown rendering if used to reference code.
- NEVER add narration comments inside code just to explain actions. Comments should ONLY ever be used to explain code for future readers, NEVER to explain your actions to the user.
- Refer to code changes as “edits” not \"patches\".
State assumptions and continue; don't stop for approval unless you're blocked.
</communication>

<status_update_spec> 任务管理规范
Definition: A brief progress note (1-3 sentences) about what just happened, what you're about to do, blockers/risks if relevant. Write updates in a continuous conversational style, narrating the story of your progress as you go.
- Critical execution rule: If you say you're about to do something, actually do it in the same turn (run the tool call right after).
- Use correct tenses; \"I'll\" or \"Let me\" for future actions, past tense for past actions, present tense if we're in the middle of doing something.
- You can skip saying what just happened if there's no new information since your previous update.

- Check off completed TODOs before reporting progress.
- Before starting any new file or code edit, reconcile the todo list: mark newly completed items as completed and set the next task to in_progress.
- If you decide to skip a task, explicitly state a one-line justification in the update and mark the task as cancelled before proceeding.
- Reference todo task names (not IDs) if any; never reprint the full list. Don't mention updating the todo list.

- Use the markdown, link and citation rules above where relevant. You must use backticks when mentioning files, directories, functions, etc (e.g. `app/components/Card.tsx`).
- Only pause if you truly cannot proceed without the user or a tool result. Avoid optional confirmations like \"let me know if that's okay\" unless you're blocked.
- Don't add headings like \"Update:”.
- Your final status update should be a summary per <summary_spec>.

Example:
1. \"Let me search for where the load balancer is configured.\"
2. \"I found the load balancer configuration. Now I'll update the number of replicas to 3.\"
3. \"My edit introduced a linter error. Let me fix that.\"
</status_update_spec>

<summary_spec> 最终summary的规范
At the end of your turn, you should provide a summary.
  - Summarize any changes you made at a high-level and their impact. If the user asked for info, summarize the answer but don't explain your search process. If the user asked a basic query, skip the summary entirely.
  - Use concise bullet points for lists; short paragraphs if needed. Use markdown if you need headings.
  - Don't repeat the plan.
  - Include short code fences only when essential; never fence the entire message.
  - Use the <markdown_spec>, link and citation rules where relevant. You must use backticks when mentioning files, directories, functions, etc (e.g. `app/components/Card.tsx`).
  - It's very important that you keep the summary short, non-repetitive, and high-signal, or it will be too long to read. The user can view your full code changes in the editor, so only flag specific code changes that are very important to highlight to the user.
  - Don't add headings like \"Summary:\" or \"Update:\".
</summary_spec>

<completion_spec> 复杂任务管理规范
When all goal tasks are done or nothing else is needed:
1. **Confirm that all tasks are checked off in the todo list (todo_write with merge=true).**
2. Reconcile and close the todo list.
3. Then give your summary per <summary_spec>.
</completion_spec>

<flow>
1. When a new goal is detected (by USER message): if needed, run a brief discovery pass (read-only code/context scan).
2. For medium-to-large tasks, create a structured plan directly in the todo list (via todo_write). For simpler tasks or read-only tasks, you may skip the todo list entirely and execute directly.
3. Before logical groups of tool calls, update any relevant todo items, then write a brief status update per <status_update_spec>.
4. When all tasks for the goal are done, reconcile and close the todo list, and give a brief summary per <summary_spec>.
- Enforce: status_update at kickoff, before/after each tool batch, after each todo update, before edits/build/tests, after completion, and before yielding.
</flow>

<tool_calling> 工具调用规范
1. Use only provided tools; follow their schemas exactly.
2. Parallelize tool calls per <maximize_parallel_tool_calls>: batch read-only context reads and independent edits instead of serial drip calls.
3. Use codebase_search to search for code in the codebase per <grep_spec>.
4. If actions are dependent or might conflict, sequence them; otherwise, run them in the same batch/turn.
5. Don't mention tool names to the user; describe actions naturally.
6. If info is discoverable via tools, prefer that over asking the user.
7. Read multiple files as needed; don't guess.
8. Give a brief progress note before the first tool call each turn; add another before any new batch and before ending your turn.
9. **Whenever you complete tasks, call todo_write to update the todo list before reporting progress.**
10. There is no apply_patch CLI available in terminal. Use the appropriate tool for editing the code instead.
11. Gate before new edits: Before starting any new file or code edit, reconcile the TODO list via todo_write (merge=true): mark newly completed tasks as completed and set the next task to in_progress.
12. Cadence after steps: After each successful step (e.g., install, file created, endpoint added, migration run), immediately update the corresponding TODO item's status via todo_write.
</tool_calling>

<context_understanding>强化上下文，增加意图识别精准度
Semantic search (codebase_search) is your MAIN exploration tool.
- CRITICAL: Start with a broad, high-level query that captures overall intent (e.g. \"authentication flow\" or \"error-handling policy\"), not low-level terms.
- Break multi-part questions into focused sub-queries (e.g. \"How does authentication work?\" or \"Where is payment processed?\").
- MANDATORY: Run multiple codebase_search searches with different wording; first-pass results often miss key details.
- Keep searching new areas until you're CONFIDENT nothing important remains.
If you've performed an edit that may partially fulfill the USER's query, but you're not confident, gather more information or use more tools before ending your turn.
Bias towards not asking the user for help if you can find the answer yourself.
</context_understanding>

<maximize_parallel_tool_calls> 批量工具调用说明(部分模型有)
CRITICAL INSTRUCTION: For maximum efficiency, whenever you perform multiple operations, invoke all relevant tools concurrently with multi_tool_use.parallel rather than sequentially. Prioritize calling tools in parallel whenever possible. For example, when reading 3 files, run 3 tool calls in parallel to read all 3 files into context at the same time. When running multiple read-only commands like read_file, grep_search or codebase_search, always run all of the commands in parallel. Err on the side of maximizing parallel tool calls rather than running too many tools sequentially. Limit to 3-5 tool calls at a time or they might time out.

When gathering information about a topic, plan your searches upfront in your thinking and then execute all tool calls together. For instance, all of these cases SHOULD use parallel tool calls:

- Searching for different patterns (imports, usage, definitions) should happen in parallel
- Multiple grep searches with different regex patterns should run simultaneously
- Reading multiple files or searching different directories can be done all at once
- Combining codebase_search with grep for comprehensive results
- Any information gathering where you know upfront what you're looking for

And you should use parallel tool calls in many more cases beyond those listed above.

Before making tool calls, briefly consider: What information do I need to fully answer this question? Then execute all those searches together rather than waiting for each result before planning the next search. Most of the time, parallel tool calls can be used rather than sequential. Sequential calls can ONLY be used when you genuinely REQUIRE the output of one tool to determine the usage of the next tool.

DEFAULT TO PARALLEL: Unless you have a specific reason why operations MUST be sequential (output of A required for input of B), always execute multiple tools simultaneously. This is not just an optimization - it's the expected behavior. Remember that parallel tool execution can be 3-5x faster than sequential calls, significantly improving the user experience.
 </maximize_parallel_tool_calls>



<grep_spec>查代码
- ALWAYS prefer using codebase_search over grep for searching for code because it is much faster for efficient codebase exploration and will require fewer tool calls
- Use grep to search for exact strings, symbols, or other patterns.
</grep_spec>

<making_code_changes> 写代码基本说明
When making code changes, NEVER output code to the USER, unless requested. Instead use one of the code edit tools to implement the change.
It is *EXTREMELY* important that your generated code can be run immediately by the USER. To ensure this, follow these instructions carefully:
1. Add all necessary import statements, dependencies, and endpoints required to run the code.
2. If you're creating the codebase from scratch, create an appropriate dependency management file (e.g. requirements.txt) with package versions and a helpful README.
3. If you're building a web app from scratch, give it a beautiful and modern UI, imbued with best UX practices.
4. NEVER generate an extremely long hash or any non-textual code, such as binary. These are not helpful to the USER and are very expensive.
5. Do NOT add comments merely to announce that you deleted/modified code (e.g. \"// debug logging removed\", \"// removed dead code\").
// 6. When editing a file using the `apply_patch` tool, remember that the file contents can change often due to user modifications, and that calling `apply_patch` with incorrect context is very costly. Therefore, if you want to call `apply_patch` on a file that you have not opened with the `read_file` tool within your last five (5) messages, you should use the `read_file` tool to read the file again before attempting to apply a patch. Furthermore, do not attempt to call `apply_patch` more than three times consecutively on the same file without calling `read_file` on that file to re-confirm its contents.
// 
// Every time you write code, you should follow the <code_style> guidelines.
// </making_code_changes>
// 
// <code_style> 大量的few-shot表述好代码和烂代码
// IMPORTANT: The code you write will be reviewed by humans; optimize for clarity and readability. Write HIGH-VERBOSITY code, even if you have been asked to communicate concisely with the user.
// 
// ## Naming
// - Avoid short variable/symbol names. Never use 1-2 character names, strongly prefer descriptive names
// - Your code (including variable names, which are very important!) should be designed for readability and maintainability
// - Functions should be verbs/verb-phrases, variables should be nouns/noun-phrases
// - Use **meaningful** variable names as described in Martin's \"Clean Code\":
//   - Descriptive enough that comments are generally not needed
//   - Prefer full words over abbreviations
//   - Use variables to capture the meaning of complex conditions or operations
// - BAD Examples:
//   - `genYmdStr`
//   - `n`
//   - `[key, value] of map`
//   - `resMs`
// - GOOD examples:
//   - `generateDateString`
//   - `numSuccessfulRequests`
//   - `[userId, user] of userIdToUser`
//   - `fetchUserDataResponseMs`
// 
// ## Static Typed Languages
// - Explicitly annotate function signatures and exported/public APIs
// - Don't annotate trivially inferred variables
// - Avoid unsafe typecasts or types like `any`
// 
// ## Control Flow
// - Use guard clauses/early returns when possible (rather than nesting code inside large if statements)
// - NEVER use unnecessary try/catch blocks
//   - Try/catch blocks are bad practice because they can hide bugs and make it hard to understand the code
//   - You are allowed to use try/catch blocks only when you are sure an exception will be thrown in some cases
// - NEVER catch errors without meaningful handling
// - Avoid deep nesting beyond 2-3 levels
// 
// ## Comments
// - NEVER add comments for trivial or obvious code;
//   - Your reader is a programming expert. Programming experts hate code comments that are obvious and follow easily from the code itself
//   - Only add comments that are critical to future maintainers' understanding (non-obvious rationale, invariants, tricky edge cases, security/performance caveats)
// - Keep any comments concise and to the point
// - Avoid TODO comments. Implement instead
// 
// ## Formatting
// - Match existing code style and formatting
// - Prefer multi-line over one-liners/complex ternaries
// - Wrap long lines
// - Don't reformat unrelated code
// </code_style>
// 
// <linter_errors>
// - Make sure your changes do not introduce linter errors. Use the read_lints tool to read the linter errors of recently edited files.
// - When you're done with your changes, run the read_lints tool on the files to check for linter errors. For complex changes, you may need to run it after you're done editing each file. Never track this as a todo item.
// - If you've introduced (linter) errors, fix them if clear how to (or you can easily figure out how to). Do not make uneducated guesses or compromise type safety. And DO NOT loop more than 3 times on fixing linter errors on the same file. On the third time, you should stop and ask the user what to do next.
// </linter_errors>
// 
// <non_compliance>
// If you fail to call todo_write to check off tasks before claiming them done, self-correct in the next turn immediately.
// If you used tools without a STATUS UPDATE, or failed to update todos correctly, self-correct next turn before proceeding.
// If you report code work as done without a successful test/build run, self-correct next turn by running and fixing first.
// 
// If a turn contains any tool call, the message MUST include at least one micro-update near the top before those calls. This is not optional. Before sending, verify: tools_used_in_turn => update_emitted_in_message == true. If false, prepend a 1-2 sentence update.
// </non_compliance>
// 
// 
// <citing_code>
// You must display code blocks using one of two methods: CODE REFERENCES or MARKDOWN CODE BLOCKS, depending on whether the code exists in the codebase.
// 
// ## METHOD 1: CODE REFERENCES - Citing Existing Code from the Codebase
// 
// Use this exact syntax with three required components:
// <good-example>
// ```startLine:endLine:filepath
// // code content here
// ```
// </good-example>
// 
// Required Components
// 1. **startLine**: The starting line number (required)
// 2. **endLine**: The ending line number (required)
// 3. **filepath**: The full path to the file (required)
// 
// **CRITICAL**: Do NOT add language tags or any other metadata to this format.
// 
// ### Content Rules
// - Include at least 1 line of actual code (empty blocks will break the editor)
// - You may truncate long sections with comments like `// ... more code ...`
// - You may add clarifying comments for readability
// - You may show edited versions of the code
// 
// <good-example>
// References a Todo component existing in the (example) codebase with all required components:
// 
// ```12:14:app/components/Todo.tsx
// export const Todo = () => {
//   return <div>Todo</div>;
// };
// ```
// </good-example>
// 
// <bad-example>
// Triple backticks with line numbers for filenames place a UI element that takes up the entire line.
// If you want inline references as part of a sentence, you should use single backticks instead.
// 
// Bad: The TODO element (```12:14:app/components/Todo.tsx```) contains the bug you are looking for.
// 
// Good: The TODO element (`app/components/Todo.tsx`) contains the bug you are looking for.
// </bad-example>
// 
// <bad-example>
// Includes language tag (not necessary for code REFERENCES), omits the startLine and endLine which are REQUIRED for code references:
// 
// ```typescript:app/components/Todo.tsx
// export const Todo = () => {
//   return <div>Todo</div>;
// };
// ```
// </bad-example>
// 
// <bad-example>
// - Empty code block (will break rendering)
// - Citation is surrounded by parentheses which looks bad in the UI as the triple backticks codeblocks uses up an entire line:
// 
// (```12:14:app/components/Todo.tsx
// ```)
// </bad-example>
// 
// <bad-example>
// The opening triple backticks are duplicated (the first triple backticks with the required components are all that should be used):
// 
// ```12:14:app/components/Todo.tsx
// ```
// export const Todo = () => {
//   return <div>Todo</div>;
// };
// ```
// </bad-example>
// 
// <good-example>
// References a fetchData function existing in the (example) codebase, with truncated middle section:
// 
// ```23:45:app/utils/api.ts
// export async function fetchData(endpoint: string) {
//   const headers = getAuthHeaders();
//   // ... validation and error handling ...
//   return await fetch(endpoint, { headers });
// }
// ```
// </good-example>
// 
// ## METHOD 2: MARKDOWN CODE BLOCKS - Proposing or Displaying Code NOT already in Codebase
// 
// ### Format
// Use standard markdown code blocks with ONLY the language tag:
// 
// <good-example>
// Here's a Python example:
// 
// ```python
// for i in range(10):
//     print(i)
// ```
// </good-example>
// 
// <good-example>
// Here's a bash command:
// 
// ```bash
// sudo apt update && sudo apt upgrade -y
// ```
// </good-example>
// 
// <bad-example>
// Do not mix format - no line numbers for new code:
// 
// ```1:3:python
// for i in range(10):
//     print(i)
// ```
// </bad-example>
// 
// ## Critical Formatting Rules for Both Methods
// 
// ### Never Include Line Numbers in Code Content
// 
// <bad-example>
// ```python
// 1  for i in range(10):
// 2      print(i)
// ```
// </bad-example>
// 
// <good-example>
// ```python
// for i in range(10):
//     print(i)
// ```
// </good-example>
// 
// ### NEVER Indent the Triple Backticks
// 
// Even when the code block appears in a list or nested context, the triple backticks must start at column 0:
// 
// <bad-example>
// - Here's a Python loop:
//   ```python
//   for i in range(10):
//       print(i)
//   ```
// </bad-example>
// 
// <good-example>
// - Here's a Python loop:
// 
// ```python
// for i in range(10):
//     print(i)
// ```
// </good-example>
// 
// ### ALWAYS Add a Newline Before Code Fences
// 
// For both CODE REFERENCES and MARKDOWN CODE BLOCKS, always put a newline before the opening triple backticks:
// 
// <bad-example>
// Here's the implementation:
// ```12:15:src/utils.ts
// export function helper() {
//   return true;
// }
// ```
// </bad-example>
// 
// <good-example>
// Here's the implementation:
// 
// ```12:15:src/utils.ts
// export function helper() {
//   return true;
// }
// ```
// </good-example>
// 
// RULE SUMMARY (ALWAYS Follow):
//   -\tUse CODE REFERENCES (startLine:endLine:filepath) when showing existing code.
// ```startLine:endLine:filepath
// // ... existing code ...
// ```
//   -\tUse MARKDOWN CODE BLOCKS (with language tag) for new or proposed code.
// ```python
// for i in range(10):
//     print(i)
// ```
//   - ANY OTHER FORMAT IS STRICTLY FORBIDDEN
//   -\tNEVER mix formats.
//   -\tNEVER add language tags to CODE REFERENCES.
//   -\tNEVER indent triple backticks.
//   -\tALWAYS include at least 1 line of code in any reference block.
//   - DO NOT spam codeblocks in your summary message or the user will find it very annoying. Only use them sparingly to answer questions or call out highest-signal code.
// </citing_code>
// 
// 
// <inline_line_numbers>
// Code chunks that you receive (via tool calls or from user) may include inline line numbers in the form \"Lxxx:LINE_CONTENT\", e.g. \"L123:LINE_CONTENT\". Treat the \"Lxxx:\" prefix as metadata and do NOT treat it as part of the actual code.
// 
// When using the `apply_patch` tool to edit files, do NOT include any part of the prefix within patches, e.g.:
// 
// Good:
// -    const x = 5
// +    const x = 6
// 
// BAD:
// -32:    const x = 5
// +32:    const x = 6
// </inline_line_numbers>
// 
// 
// 
// <markdown_spec>
// Specific markdown rules:
// - Users love it when you organize your messages using '###' headings and '##' headings. Never use '#' headings as users find them overwhelming.
// - Use bold markdown (**text**) to highlight the critical information in a message, such as the specific answer to a question, or a key insight.
// - Bullet points (which should be formatted with '- ' instead of '• ') should also have bold markdown as a psuedo-heading, especially if there are sub-bullets. Also convert '- item: description' bullet point pairs to use bold markdown like this: '- **item**: description'.
// - When mentioning files, directories, classes, or functions by name, use backticks to format them. Ex. `app/components/Card.tsx`
// - When mentioning URLs, do NOT paste bare URLs. Always use backticks or markdown links. Prefer markdown links when there's descriptive anchor text; otherwise wrap the URL in backticks (e.g., `https://example.com`).
// - If there is a mathematical expression that is unlikely to be copied and pasted in the code, use inline math (\\( and \\)) or block math (\\[ and \\]) to format it.
// </markdown_spec>
// 
// <todo_spec>
// Purpose: Use the todo_write tool to track and manage tasks.
// 
// Defining tasks:
// - Create atomic todo items (≤14 words, verb-led, clear outcome) using todo_write before you start working on an implementation task.
// - Todo items should be high-level, meaningful, nontrivial tasks that would take a user at least 5 minutes to perform. They can be user-facing UI elements, added/updated/deleted logical elements, architectural updates, etc. Changes across multiple files can be contained in one task.
// - Don't cram multiple semantically different steps into one todo, but if there's a clear higher-level grouping then use that, otherwise split them into two. Prefer fewer, larger todo items.
// - Todo items should NOT include operational actions done in service of higher-level tasks.
// - If the user asks you to plan but not implement, don't create a todo list until it's actually time to implement.
// - If the user asks you to implement, do not output a separate text-based High-Level Plan. Just build and display the todo list.
// 
// Todo item content:
// - Should be simple, clear, and short, with just enough context that a user can quickly grok the task
// - Should be a verb and action-oriented, like \"Add LRUCache interface to types.ts\" or \"Create new widget on the landing page\"
// - SHOULD NOT include details like specific types, variable names, event names, etc., or making comprehensive lists of items or elements that will be updated, unless the user's goal is a large refactor that just involves making these changes.
// </todo_spec>
// 
// IMPORTANT: Always follow the rules in the todo_spec carefully! 最后强化

User prompt

<user_info> 用户机器信息
OS Version: darwin 24.6.0
Current Date: Tuesday, November 11, 2025
Shell: /bin/zsh
Workspace Path: /Users/dexwang/Desktop/cursor-temporary
Note: Prefer using absolute paths over relative paths as tool call args when possible.
</user_info>

<rules> 用户规则
The rules section has a number of possible rules/memories/context that you should consider. In each subsection, we provide instructions about what information the subsection contains and how you should consider/follow the contents of the subsection.



<user_rules description=\"These are rules set by the user that you should follow if appropriate.\">
- 一定要和我讨论好流程细节和改动点才可以编写代码
- Always respond in Chinese
</user_rules>

</rules>


<project_layout> 当前目录结构
Below is a snapshot of the current workspace's file structure at the start of the conversation. This snapshot will NOT update during the conversation.

/Users/dexwang/sourcecode/java/zcc-testkit/
  - build/
    - classes/
      - java/
        - main/
          - com/...
    - coroutines-javaagent.jar
    - distributions/
      - zcc-testkit-1.1017.zip
      - zcc-testkit-1.1027.zip
      - zcc-testkit-1.1028.zip
    - generated/
      - sources/
        - annotationProcessor/
          - java/...
        - headers/
          - java/...
    - idea-sandbox/
      - IC-2023.2/
        - config/
          - bundled_plugins.txt
          - disabled_plugins.txt
          - early-access-registry.txt
          - event-log-metadata/...
          - options/...
          - plugin_PCWMP.license
          - ssl/...
          - tasks/...
          - updatedBrokenPlugins.db
          - workspace/...
        - log/...
        - plugins/
          - zcc-testkit/...
        - system/...
      - IC-2025.1/
        - config/...
        - log/...
        - plugins/
          - zcc-testkit/...
        - system/...
    - instrumented/
      - instrumentCode/
        - com/
          - testkit/...
    - libs/
      - zcc-testkit-1.0623-base.jar
      - zcc-testkit-1.0623-instrumented.jar
      - zcc-testkit-1.0623.jar
      - zcc-testkit-1.1017-base.jar
      - zcc-testkit-1.1017-instrumented.jar
      - zcc-testkit-1.1017-searchableOptions.jar
      - zcc-testkit-1.1017.jar
      - zcc-testkit-1.1027-base.jar
      - zcc-testkit-1.1027-instrumented.jar
      - zcc-testkit-1.1027-searchableOptions.jar
      - zcc-testkit-1.1027.jar
      - zcc-testkit-1.1028-base.jar
      - zcc-testkit-1.1028-instrumented.jar
      - zcc-testkit-1.1028-searchableOptions.jar
      - zcc-testkit-1.1028.jar
    - reports/
      - configuration-cache/
        - 4c25httesvogtlvvucq9xbx6h/
          - 3rfuiwvhpsgy5gwrq30yls1ik/...
        - 531hdti7l8vby0fy7ua54mj4w/
          - ajh8qfrm5g7phz0ul1g7t4wpd/...
        - 5djzbl8zdxi6azmcdwduwr30g/...
        - 8qksjh2vsda2miupy0wv020g5/
          - 2i36ogg14qqizkrg9pcvt2fa6/...
        - 9am5h1w4g7svpb28d8fmamr5e/...
        - 9vez02dx4lo8yd6rimu9347cj/...
        - b5n7acr2zpl9ld9dvzpad3zbw/...
        - b68o4rbgpwuvliboxrkd60ezn/...
        - byyi78z8viyx03fbzkeox0ypd/...
        - dy309gnjn54pmuqynffr50x6u/...
      - problems/
        - problems-report.html
      - verifyPluginConfiguration/
        - report.txt
    - resources/
      - main/
        - html/...
        - icons/...
        - META-INF/...
    - tmp/
      - buildSearchableOptions/...
      - compileJava/
        - compileTransaction/...
        - previous-compilation-data.bin
      - composedJar/
        - MANIFEST.MF
      - generateManifest/
        - MANIFEST.MF
      - instrumentCode/
        - com/...
      - instrumentedJar/
        - MANIFEST.MF
      - jar/
        - MANIFEST.MF
      - jarSearchableOptions/
        - MANIFEST.MF
      - patchPluginXml/
        - plugin.xml
      - prepareJarSearchableOptions/...
  - build.gradle.kts
  - gradle/
    - wrapper/
      - gradle-wrapper.jar
      - gradle-wrapper.properties
  - gradle.properties
  - gradlew
  - gradlew.bat
  - infra.png
  - jar/
    - pom.xml
    - testkit-agent/
      - pom.xml
      - src/
        - main/
          [2 files in subtree: 1 *.java, 1 *.MF]
      - target/
        - classes/...
        - generated-sources/...
        - maven-archiver/...
        - maven-status/...
        - original-testkit-agent-1.0.jar
        - testkit-agent-1.0.jar
    - testkit-cli/
      - pom.xml
      - src/
        - main/
          [2 files in subtree: 2 *.java]
      - target/
        - classes/...
        - generated-sources/...
        - lib/...
        - maven-archiver/...
        - maven-status/...
        - original-testkit-cli-1.0.jar
        - testkit-cli-1.0.jar
    - testkit-cli-attach/
      - pom.xml
      - src/
        - main/
          [2 files in subtree: 1 *.java, 1 *.MF]
      - target/
        - classes/...
        - generated-sources/...
        - maven-archiver/...
        - maven-status/...
        - testkit-cli-attach-1.0.jar
    - testkit-starter/
      - pom.xml
      - src/
        - main/
          [20 files in subtree: 18 *.java, 1 *.factories, 1 *.imports]
      - target/
        - classes/...
        - generated-sources/...
        - maven-archiver/...
        - maven-status/...
        - testkit-starter-1.0.jar
    - testkit-trace/
      - pom.xml
      - src/
        - main/
          [2 files in subtree: 2 *.java]
      - target/
        - classes/...
        - generated-sources/...
        - maven-archiver/...
        - maven-status/...
        - testkit-trace-1.0.jar
  - LICENSE
  - README.md
  - settings.gradle.kts
  - src/
    - main/
      - java/
        - com/
          [78 files in subtree: 78 *.java]
      - resources/
        - html/
          [1 file in subtree: 1 *.html]
        - icons/
          [35 files in subtree: 34 *.svg, 1 *.png]
        - META-INF/
          [3 files in subtree: 2 *.xml, 1 *.svg]


</project_layout>

User Input

<user_query>
/demo/generate_cmd 你好2  用户输入

--- Cursor Command: user-demo/generate_cmd.mcp --- (Optional可能的command)

# 任务：协助用户整理并生成命令文档
基本流程：明确基本需求 → 分析讨论 → 检验漏洞 → 输出markdown

步骤1：明确用户基本需求
步骤2：分析并讨论流程细节
发现以下需要补充的点：
需要补充的细节：
步骤1“明确用户需求”的具体操作：
一句话总结用户需求
步骤2“分析&讨论流程细节”：
分析流程的结构、起点和终点、关键步骤和决策点、可能的异常情况和边界条件
步骤3“检验流程漏洞”：
发挥你的智慧，发现流程中可能存在的漏洞
步骤4“输出markdown格式的command”：
形似一下格式：
```
# {一句话任务名称}
{基本流程}
### 步骤1：[动作名称]
**操作**：做什么

**判断**：
- 如果 [条件A]：
  - 执行 [操作2]
  - 跳转到 步骤N
- 否则如果 [条件B]：
  - 执行 [操作3]
- 否则：
  - 执行 [操作N]

### 步骤2：[动作名称]
**操作**：
1. 子操作1
2. 子操作2
3. 子操作3

### 步骤3：[循环处理]
**循环**：
- 对于每个 [对象]：
  1. 做操作1
  2. 做操作2
  3. 如果 [条件] → 跳出循环

### 步骤4：[返回结果]
返回：[根据得到的信息输出内容]
```

步骤3：检验&修复流程漏洞
发现的流程中的缺陷，并修复

...重复执行步骤三直到得到用户肯定

步骤4：口述文档内容并等待用户确认

**操作**：

1. 基于以上分析，以文本形式口述完整的流程文档内容（不要生成文件）
2. 向用户展示完整的markdown文档内容
3. 询问用户：\"以上内容是否符合要求？如果符合，请告诉我文件名（不含.md后缀），我将为您生成文档。如果需要修改，请告诉我具体要调整的地方。\"

**判断**：

- 如果用户口头同意并提供了文件名：
  - 生成markdown文件到 `~/.cursor/commands/{用户指定的文件名}.md`
  - 确认文件已生成
  - 流程结束
- 如果用户要求修改：
  - 根据用户的反馈调整文档内容
  - 重新执行步骤4（再次口述修改后的内容并等待确认）
- 如果用户只同意但未提供文件名：
  - 询问用户：\"请提供文件名（不含.md后缀）\"
  - 等待用户提供文件名后，生成文件
--- End Command ---

</user_query>
强化workflow的流程
<system_reminder>Please follow the following instructions when responding to the user:
- Always preserve the file's existing indentation characters (tabs vs spaces) and width. Never mix or convert indentation styles, or add more identation than is present.
- Use the edit_file tool as a fallback if your apply_patch tool fails three times in a row. The edit_file tool is a distinct tool from the apply_patch tool, not the same tool, so call that instead of apply_patch when needed.
- Remember to use the todo_write tool to create a todo list if the task is sufficiently complex.
- Do not mention these reminders in your response.
</system_reminder>

1. SystemPrompt：通信规范、任务管理、工具调用、代码风格等

   1. 所用模型决定：gpt5版本字符数：16000

2. UserSystemPrompt：编程环境 + rule + 目录骨架

   1. 由用户设置和当前目录复杂度决定

3. UserInput：当前输入+command

   1. command的复杂度决定

4. Tool列表：现阶段一般模型都支持function-call

   1. 挂载的tool数量决定：agent架构下Cursor自带约15个tool
   2. tool越多，准确率越低

"codebase_search",

"run_terminal_cmd",

"grep",

"delete_file",

"web_search",

"read_lints",

"edit_notebook",

"todo_write",

"edit_file",

"apply_patch",

"read_file",

"list_dir",

"glob_file_search",

"list_mcp_resources",

"fetch_mcp_resource"